@heybox/hb-sdk 0.8.3-alpha.2 → 0.8.3-alpha.3

package/dist/devtools/browser-dev-host/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-DWFHHorU.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-B1QBmFTk.js">
+    <script type="module" crossorigin src="/assets/index-8YA6OLi7.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-EnOYLhEx.js">
     <link rel="stylesheet" crossorigin href="/assets/index-D-cRoNV5.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -629,6 +629,7 @@ const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_SET_DISPLAY_METHOD = 'viewport.setDisplay';
 const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
@@ -1341,7 +1342,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.2';
+    : '0.8.3-alpha.3';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -4402,6 +4403,20 @@ function setNavigationBarStyle(requester, options) {
  */
 function createViewportModule(requester) {
     return {
+        // Runtime 持有唯一的操作截止时间；复用 cancel 链路，避免 SDK 普通请求 timer 提前失效。
+        setDisplay: async (options) => {
+            try {
+                return await requester.requestOperation(VIEWPORT_SET_DISPLAY_METHOD, options);
+            }
+            catch (error) {
+                // 旧 Runtime 或客户端缺少展示能力时统一降级，保留其它错误供业务处理。
+                const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+                if (code === 'METHOD_FORBIDDEN' || code === 'METHOD_NOT_FOUND' || code === 'REQUEST_UNSUPPORTED') {
+                    return { supported: false };
+                }
+                throw error;
+            }
+        },
         getWindowInfo: () => getWindowInfo(requester),
         setNavigationBarStyle: (options) => setNavigationBarStyle(requester, options),
     };
@@ -5243,6 +5258,7 @@ const share = {
 };
 /** 默认 SDK 实例的 Viewport 模块。 */
 const viewport = {
+    setDisplay: (options) => getDefaultSDK().viewport.setDisplay(options),
     getWindowInfo: () => getDefaultSDK().viewport.getWindowInfo(),
     setNavigationBarStyle: (options) => getDefaultSDK().viewport.setNavigationBarStyle(options),
 };

package/dist/index.esm.js

@@ -625,6 +625,7 @@ const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_SET_DISPLAY_METHOD = 'viewport.setDisplay';
 const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
@@ -1337,7 +1338,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.2';
+    : '0.8.3-alpha.3';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -4398,6 +4399,20 @@ function setNavigationBarStyle(requester, options) {
  */
 function createViewportModule(requester) {
     return {
+        // Runtime 持有唯一的操作截止时间；复用 cancel 链路，避免 SDK 普通请求 timer 提前失效。
+        setDisplay: async (options) => {
+            try {
+                return await requester.requestOperation(VIEWPORT_SET_DISPLAY_METHOD, options);
+            }
+            catch (error) {
+                // 旧 Runtime 或客户端缺少展示能力时统一降级，保留其它错误供业务处理。
+                const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+                if (code === 'METHOD_FORBIDDEN' || code === 'METHOD_NOT_FOUND' || code === 'REQUEST_UNSUPPORTED') {
+                    return { supported: false };
+                }
+                throw error;
+            }
+        },
         getWindowInfo: () => getWindowInfo(requester),
         setNavigationBarStyle: (options) => setNavigationBarStyle(requester, options),
     };
@@ -5239,6 +5254,7 @@ const share = {
 };
 /** 默认 SDK 实例的 Viewport 模块。 */
 const viewport = {
+    setDisplay: (options) => getDefaultSDK().viewport.setDisplay(options),
     getWindowInfo: () => getDefaultSDK().viewport.getWindowInfo(),
     setNavigationBarStyle: (options) => getDefaultSDK().viewport.setNavigationBarStyle(options),
 };

package/dist/protocol.cjs.js

@@ -38,6 +38,7 @@ const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_SET_DISPLAY_METHOD = 'viewport.setDisplay';
 const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
@@ -161,6 +162,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'none' },
         risk: 'low',
     },
+    {
+        method: VIEWPORT_SET_DISPLAY_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_SET_DISPLAY_METHOD,
+        requirement: { kind: 'none' },
+        risk: 'low',
+    },
     {
         method: STORAGE_GET_STORAGE_METHOD,
         module: 'storage',
@@ -1402,6 +1410,7 @@ exports.USER_GET_STEAM_GAME_LIST_METHOD = USER_GET_STEAM_GAME_LIST_METHOD;
 exports.USER_INFO_AUTHORIZATION_SCOPES = USER_INFO_AUTHORIZATION_SCOPES;
 exports.USER_REVOKE_AUTHORIZATION_METHOD = USER_REVOKE_AUTHORIZATION_METHOD;
 exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
+exports.VIEWPORT_SET_DISPLAY_METHOD = VIEWPORT_SET_DISPLAY_METHOD;
 exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
 exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;

package/dist/protocol.esm.js

@@ -36,6 +36,7 @@ const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList';
 const SHARE_COPY_LINK_METHOD = 'share.copyLink';
 const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu';
 const SHARE_SCREENSHOT_METHOD = 'share.screenshot';
+const VIEWPORT_SET_DISPLAY_METHOD = 'viewport.setDisplay';
 const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo';
 const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle';
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
@@ -159,6 +160,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'none' },
         risk: 'low',
     },
+    {
+        method: VIEWPORT_SET_DISPLAY_METHOD,
+        module: 'viewport',
+        capability: VIEWPORT_SET_DISPLAY_METHOD,
+        requirement: { kind: 'none' },
+        risk: 'low',
+    },
     {
         method: STORAGE_GET_STORAGE_METHOD,
         module: 'storage',
@@ -1350,4 +1358,4 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

package/dist/vite.cjs.js

@@ -2948,7 +2948,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.2';
+    : '0.8.3-alpha.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -2945,7 +2945,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.2';
+    : '0.8.3-alpha.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.3-alpha.2",
+  "version": "0.8.3-alpha.3",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -65,7 +65,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.8.3-alpha.2"
+    "@heybox/hb-sdk-protocol": "0.8.3-alpha.3"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -116,12 +116,12 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.3-alpha.2",
+    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/hb-api": "~1.28.9",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox-domain/heybox-theme": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.3-alpha.3",
     "@heybox/runtime-transport-fetch": "~0.2.0"
   },
   "publishConfig": {

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.3-alpha.2+skill.aa24d6656331",
+  "skillVersion": "0.8.3-alpha.3+skill.aa24d6656331",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.3-alpha.2",
-    "compatibility": "0.8.3-alpha.2"
+    "version": "0.8.3-alpha.3",
+    "compatibility": "0.8.3-alpha.3"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.3-alpha.2",
+    "version": "0.8.3-alpha.3",
     "path": "skill"
   },
   "integrity": "sha256-aa24d6656331cbad8f6aae7735258a49d7f1a82f6e900415de53a1b93a30ddb8"

package/types/index.d.ts

@@ -9,7 +9,7 @@ export type { AuthorizedUserInfo, GetUserInfoPayload, GetUserInfoResult, RevokeA
 export { USER_INFO_AUTHORIZATION_SCOPES } from './modules/user';
 export type { UserInfoAuthorizationScope } from './modules/user';
 export type { CopyLinkPayload, CopyLinkResult, MiniProgramCopyLinkOptions, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
-export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
+export type { MiniProgramOrientationMode, SetDisplayPayload, SetDisplayResult, MiniProgramDisplayState, GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
 export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload } from './modules/storage';
 export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
 export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
@@ -28,7 +28,7 @@ declare const hbSDK: {
     share: import(".").MiniProgramShareModule;
     viewport: import(".").MiniProgramViewportModule;
     storage: import(".").MiniProgramStorageModule;
-    files: import(".").FilesModule;
+    files: import("./protocol").FilesModule;
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;

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

@@ -1,4 +1,5 @@
-import type { MiniProgramRequester } from '../../core/client';
+import type { SetDisplayPayload, SetDisplayResult } from '../../protocol';
+import type { MiniProgramOperationRequester, MiniProgramRequester } from '../../core/client';
 /**
  * 小程序安全区域信息。
  *
@@ -59,6 +60,8 @@ export interface MiniProgramWindowInfoResult {
     /** 顶部可用偏移兼容值，单位逻辑像素；当前恒等于 `statusBarHeight`。 */
     screenTop: number;
 }
+export { VIEWPORT_SET_DISPLAY_METHOD } from '../../protocol/capabilities';
+export type { MiniProgramDisplayState, MiniProgramOrientationMode, SetDisplayPayload, SetDisplayResult } from '../../protocol';
 export { VIEWPORT_GET_WINDOW_INFO_METHOD } from '../../protocol/capabilities';
 export { VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD } from '../../protocol/capabilities';
 /** `viewport.getWindowInfo` 不接收 options 或 payload，调用时无需传入参数。 */
@@ -118,6 +121,34 @@ export type SetNavigationBarStyleResult = void;
 export type { MiniProgramViewportMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 Viewport 模块。 */
 export interface MiniProgramViewportModule {
+    /**
+     * 设置当前小程序的窗口方向和全屏状态。
+     *
+     * @remarks
+     * 新容器默认竖屏、非全屏。省略字段保持当前目标值，至少传一个字段；合并后横屏强制全屏，竖屏按 fullscreen 控制。
+     * 全屏同时收起胶囊和宿主额外顶部栏，不保证原生内容铺满容器；页面应按实际 WebView 窗口和安全区适配。
+     * 系统状态栏、手势条不保证隐藏，重要控件仍应按实际窗口与安全区信息避让。
+     * 横屏时仅设置 fullscreen: false 不会退出全屏；退出需同时设置 orientation: portrait、fullscreen: false。
+     * 宿主退出按钮恢复竖屏、非全屏；仅设置 orientation: portrait 则保留当前全屏目标。
+     * 设置持续到下次调用或退出容器；SPA 路由应在进入时明确设置所需状态。
+     * 后续设置先合并目标，再取消不同的旧设置；旧调用以 ORIENTATION_SUPERSEDED 失败。
+     * 相同目标共用操作；方向和全屏一起确认，失败时一起恢复最后确认状态。
+     * Promise 在宿主布局稳定后完成，窗口尺寸与安全区变化通过 viewport_change 事件通知。
+     * 方向或全屏状态确认变化时通过 display_change 通知，包括用户点击宿主退出全屏按钮。
+     * display_change 不回放初始状态；重复设置、不支持、失败或取消不会发出展示状态变化通知。
+     * 返回 supported: true 表示原生方向与胶囊设置已完成；不支持时返回 supported: false，保留原生状态。
+     * 降级时宿主仍尽力收起 H5 顶部栏，不能据此假定屏幕已旋转或胶囊已隐藏；布局始终按实际窗口适配。
+     * SDK 统一处理能力缺失错误；超时、取消、参数或其他执行错误仍抛出。
+     * @since 0.8.1-alpha.4
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @experimental
+     */
+    setDisplay(options: SetDisplayPayload): Promise<SetDisplayResult>;
     /**
      * 获取当前小程序窗口信息。
      *
@@ -265,4 +296,4 @@ export declare function setNavigationBarStyle(requester: MiniProgramRequester, o
  * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的 Viewport 模块对象。
  */
-export declare function createViewportModule(requester: MiniProgramRequester): MiniProgramViewportModule;
+export declare function createViewportModule(requester: MiniProgramOperationRequester): MiniProgramViewportModule;

package/types/protocol/capabilities.d.ts

@@ -1,2 +1,2 @@
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from '@heybox/hb-sdk-protocol';
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from '@heybox/hb-sdk-protocol';
 export type { MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryMethod, MiniProgramFileMethod, MiniProgramFilesMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from '@heybox/hb-sdk-protocol';

package/types/protocol.d.ts

@@ -1,5 +1,5 @@
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramByteArray, isMiniProgramBridgeMessage, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions, } from '@heybox/hb-sdk-protocol';
-export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramRuntimePermissionEntry, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramByteArray, isMiniProgramBridgeMessage, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions, } from '@heybox/hb-sdk-protocol';
+export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, MiniProgramOrientationMode, SetDisplayPayload, SetDisplayResult, MiniProgramDisplayState, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramRuntimePermissionEntry, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
 export type { LoginOptions } from './modules/auth';
 export type { GetSteamGameListOptions } from './modules/user';
 export type { MiniProgramEventHandler } from './protocol/types';