@heybox/hb-sdk-protocol 0.8.3-alpha.1 → 0.8.3-alpha.3

package/README.md

@@ -56,6 +56,13 @@ Runtime 可以在握手 response 中附带 `MiniProgramRuntimeEnvironmentInfo`
 
 该 response 是 v2 envelope 上的向后兼容扩展，不新增 capability method 或权限，也不提升 `MINI_PROGRAM_MESSAGE_VERSION`。旧 SDK 没有对应 pending request，会忽略该 response；新 SDK 遇到旧 Host 时生成未知值快照。
 
+## 窗口协议
+
+`viewport.setDisplay` 接受 `{ orientation?: 'portrait' | 'landscape', fullscreen?: boolean }`，返回 `{ supported: boolean }`。`true` 表示原生方向与胶囊设置已完成；`false` 表示原生能力不可用，保留原生状态，宿主仍可尽力处理 H5 顶部栏。能力缺失的兼容错误由 SDK 统一转换为 `false`，其它执行错误继续保留。
+至少传一个字段，省略字段保持当前目标值；初始为竖屏、非全屏。全屏同时收起胶囊和宿主额外顶部栏。SDK 复用 request-scoped cancel 协议；
+Runtime 持有截止时间与意图替换语义，Host 负责原子应用与终止恢复。
+`viewport_change` 事件载荷复用 `MiniProgramWindowInfoResult`，描述当前窗口与四边安全区。
+
 ## 公开入口
 
 - `@heybox/hb-sdk-protocol`：本包唯一入口，适合 Host、Runtime 和协议维护代码。
@@ -85,3 +92,9 @@ pnpm --filter @heybox/hb-sdk-protocol run check:boundary
 pnpm --filter @heybox/hb-sdk-protocol run test:unit
 pnpm --filter @heybox/hb-sdk-protocol run build:package
 ```
+
+### 展示状态事件
+
+`display_change` 在宿主确认方向或全屏状态发生变化后发送 `{ orientation, fullscreen, source }`，包括开发者调用 `setDisplay()` 和用户点击宿主退出全屏按钮。两个字段独立；退出全屏不改变方向。重复状态、不支持（`supported: false`）、失败、超时、取消及被后续请求替换的设置不发送事件。事件不回放初始状态，新容器默认竖屏、非全屏；它不监听手机旋转传感器，窗口尺寸与安全区仍通过 `viewport_change` 获取。请在调用设置前注册监听，并在页面销毁时取消。
+
+`display_change.source` 区分变化来源：`api` 为开发者调用，`user` 为用户点击宿主退出全屏按钮。同目标并发合并时保留首次发起操作的来源；重复状态不额外发事件。旧宿主可能不含 source，不能将缺失来源推断为用户操作。仅用户退出时跳页，应判断 `source === 'user' && !fullscreen`，再按业务需要调用竖屏设置并跳转。

package/dist/index.cjs.js

@@ -41,6 +41,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';
@@ -164,6 +165,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',
@@ -1458,6 +1466,7 @@ const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'ui.hideLoading',
     'viewport.getWindowInfo',
     'viewport.setNavigationBarStyle',
+    'viewport.setDisplay',
     'device.vibrate',
     'navigation.close',
     'navigation.reload',
@@ -1725,6 +1734,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/index.esm.js

@@ -39,6 +39,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';
@@ -162,6 +163,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',
@@ -1456,6 +1464,7 @@ const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'ui.hideLoading',
     'viewport.getWindowInfo',
     'viewport.setNavigationBarStyle',
+    'viewport.setDisplay',
     'device.vibrate',
     'navigation.close',
     'navigation.reload',
@@ -1646,4 +1655,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, COMPANION_ALIAS_PATTERN, COMPANION_CANCEL_PREPARATION_METHOD, COMPANION_ERROR_CODES, COMPANION_GET_ACTIVE_SESSION_METHOD, COMPANION_GET_INFO_METHOD, COMPANION_GET_PREPARATION_STATUS_METHOD, COMPANION_LAUNCH_METHOD, COMPANION_OPEN_ATTACHMENT_METHOD, COMPANION_PREPARE_METHOD, COMPANION_SESSION_ACK_OUTPUT_METHOD, COMPANION_SESSION_CLOSE_STDIN_METHOD, COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, COMPANION_SESSION_TERMINATE_METHOD, COMPANION_SESSION_WRITE_METHOD, COMPANION_SHOW_NOTIFICATION_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_NATIVE_CHUNK_MAX_BYTES, MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION, MINI_PROGRAM_NATIVE_HOST_DESCRIPTION, MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT, MINI_PROGRAM_NATIVE_HOST_OBJECT, MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION, MINI_PROGRAM_NATIVE_OPERATIONS, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, 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, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramNativeBinaryChunk, isMiniProgramNativeHostDescription, isMiniProgramNativeHostMessage, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, 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, COMPANION_ALIAS_PATTERN, COMPANION_CANCEL_PREPARATION_METHOD, COMPANION_ERROR_CODES, COMPANION_GET_ACTIVE_SESSION_METHOD, COMPANION_GET_INFO_METHOD, COMPANION_GET_PREPARATION_STATUS_METHOD, COMPANION_LAUNCH_METHOD, COMPANION_OPEN_ATTACHMENT_METHOD, COMPANION_PREPARE_METHOD, COMPANION_SESSION_ACK_OUTPUT_METHOD, COMPANION_SESSION_CLOSE_STDIN_METHOD, COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION_SESSION_OWNERSHIP_LOST_EVENT, COMPANION_SESSION_TERMINATE_METHOD, COMPANION_SESSION_WRITE_METHOD, COMPANION_SHOW_NOTIFICATION_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_NATIVE_CHUNK_MAX_BYTES, MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION, MINI_PROGRAM_NATIVE_HOST_DESCRIPTION, MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT, MINI_PROGRAM_NATIVE_HOST_OBJECT, MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION, MINI_PROGRAM_NATIVE_OPERATIONS, MINI_PROGRAM_NO_DECLARATION_METHODS, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PERMISSION_CATALOG, MINI_PROGRAM_PERMISSION_KEYS, 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, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramNativeBinaryChunk, isMiniProgramNativeHostDescription, isMiniProgramNativeHostMessage, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

package/generated/permission-catalog.json

@@ -1,5 +1,5 @@
 {
-  "hash": "411af8cb9f6bffc9a10c7b1bdf8eda6f777d25e52e34b8b2e72eb9ab0b2ee095",
+  "hash": "6a5978e344f22fd060ff55f77a1248a7c161cd8fbf5be2b8c73eddd308e8fe78",
   "permissions": [
     {
       "key": "userInfo",
@@ -177,6 +177,7 @@
     "ui.hideLoading",
     "viewport.getWindowInfo",
     "viewport.setNavigationBarStyle",
+    "viewport.setDisplay",
     "device.vibrate",
     "navigation.close",
     "navigation.reload",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk-protocol",
-  "version": "0.8.3-alpha.1",
+  "version": "0.8.3-alpha.3",
   "description": "Heybox mini-program iframe bridge wire contracts.",
   "sideEffects": false,
   "exports": {

package/src/bridge.ts

@@ -18,6 +18,8 @@ import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from '.
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName =
   | 'launch'
+  | 'viewport_change'
+  | 'display_change'
   | 'ready'
   | 'show'
   | 'hide'
@@ -123,6 +125,12 @@ export interface MiniProgramBridgeProgressMessage<
   error?: never;
 }
 export interface MiniProgramEventPayloadMap {
+  /** 展示状态实际变化后通知；不回放初始状态，不支持或失败时不通知。 */
+  display_change: import('./payloads').MiniProgramDisplayState & {
+    /** api 为开发者调用；user 为用户点击宿主退出全屏按钮。同目标合并时保留首次发起来源。旧宿主可能不提供。 */
+    source?: 'api' | 'user';
+  };
+  viewport_change: import('./payloads').MiniProgramWindowInfoResult;
   launch: { timestamp: number; url?: string };
   ready: { timestamp: number };
   show: { timestamp: number; source?: string };

package/src/capabilities.ts

@@ -91,6 +91,8 @@ import type {
   SaveFileResult,
   SetClipboardPayload,
   SetClipboardResult,
+  SetDisplayPayload,
+  SetDisplayResult,
   SetNavigationBarStylePayload,
   SetNavigationBarStyleResult,
   SetStoragePayload,
@@ -114,6 +116,7 @@ export const USER_GET_STEAM_GAME_LIST_METHOD = 'user.getSteamGameList' as const;
 export const SHARE_COPY_LINK_METHOD = 'share.copyLink' as const;
 export const SHARE_SHOW_SHARE_MENU_METHOD = 'share.showShareMenu' as const;
 export const SHARE_SCREENSHOT_METHOD = 'share.screenshot' as const;
+export const VIEWPORT_SET_DISPLAY_METHOD = 'viewport.setDisplay' as const;
 export const VIEWPORT_GET_WINDOW_INFO_METHOD = 'viewport.getWindowInfo' as const;
 export const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle' as const;
 export const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage' as const;
@@ -165,6 +168,7 @@ export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
 export type MiniProgramViewportMethod =
+  | typeof VIEWPORT_SET_DISPLAY_METHOD
   | typeof VIEWPORT_GET_WINDOW_INFO_METHOD
   | typeof VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
 export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
@@ -329,6 +333,13 @@ export 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',
@@ -541,6 +552,7 @@ export interface MiniProgramCapabilityPayloadMap {
   [SHARE_COPY_LINK_METHOD]: CopyLinkPayload;
   [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuPayload;
   [SHARE_SCREENSHOT_METHOD]: ScreenshotPayload;
+  [VIEWPORT_SET_DISPLAY_METHOD]: SetDisplayPayload;
   [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoPayload;
   [VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD]: SetNavigationBarStylePayload;
   [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
@@ -597,6 +609,7 @@ export interface MiniProgramCapabilityResultMap {
   [SHARE_COPY_LINK_METHOD]: CopyLinkResult;
   [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuResult;
   [SHARE_SCREENSHOT_METHOD]: ScreenshotResult;
+  [VIEWPORT_SET_DISPLAY_METHOD]: SetDisplayResult;
   [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoResult;
   [VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD]: SetNavigationBarStyleResult;
   [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;

package/src/payloads.ts

@@ -368,6 +368,27 @@ export interface MiniProgramWindowInfoResult {
   safeArea: MiniProgramSafeArea;
   screenTop: number;
 }
+/** 小程序窗口方向。 */
+export type MiniProgramOrientationMode = 'portrait' | 'landscape';
+/** 宿主确认生效的小程序展示状态；不表示手机旋转传感器状态。 */
+export interface MiniProgramDisplayState {
+  /** 当前小程序锁定的窗口方向。 */
+  orientation: MiniProgramOrientationMode;
+  /** 是否同时收起胶囊和宿主额外顶部栏；横屏始终为 true。 */
+  fullscreen: boolean;
+}
+export interface SetDisplayPayload {
+  /** 锁定竖屏或横屏；省略保持当前目标方向，初始为 portrait。 */
+  orientation?: MiniProgramOrientationMode;
+  /** 同时收起胶囊和宿主额外顶部栏；省略保持当前目标值，初始为 false。合并后横屏强制 true；退出横屏全屏需同时设置 portrait 和 false。 */
+  fullscreen?: boolean;
+}
+/** 本次展示设置的原生支持结果；不支持时保留原生状态，宿主仍可尽力收起 H5 顶部栏。 */
+export type SetDisplayResult = {
+  /** true 表示原生方向与胶囊设置已完成；false 表示已按宿主可用能力降级。 */
+  supported: boolean;
+};
+
 export type GetWindowInfoPayload = void;
 export type GetWindowInfoResult = MiniProgramWindowInfoResult;
 export type MiniProgramNavigationBarForegroundStyle = 'light' | 'dark';

package/src/permission-catalog.ts

@@ -179,6 +179,7 @@ export const MINI_PROGRAM_NO_DECLARATION_METHODS = [
   'ui.hideLoading',
   'viewport.getWindowInfo',
   'viewport.setNavigationBarStyle',
+  'viewport.setDisplay',
   'device.vibrate',
   'navigation.close',
   'navigation.reload',

package/types/bridge.d.ts

@@ -2,7 +2,7 @@ import { COMPANION_SESSION_EXIT_EVENT, COMPANION_SESSION_OUTPUT_EVENT, COMPANION
 import type { CompanionSessionExitPayload, CompanionSessionOutputPayload, CompanionSessionOwnershipLostPayload, MiniProgramRuntimeEnvironmentInfo, UserInfoAuthorization } from './payloads';
 import type { MiniProgramCapabilityProgress, MiniProgramProgressMethod } from './capabilities';
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
-export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
+export type MiniProgramEventName = 'launch' | 'viewport_change' | 'display_change' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change' | typeof COMPANION_SESSION_OUTPUT_EVENT | typeof COMPANION_SESSION_EXIT_EVENT | typeof COMPANION_SESSION_OWNERSHIP_LOST_EVENT;
 export interface MiniProgramBridgeError {
     code: string;
     message: string;
@@ -92,6 +92,12 @@ export interface MiniProgramBridgeProgressMessage<TMethod extends MiniProgramPro
     error?: never;
 }
 export interface MiniProgramEventPayloadMap {
+    /** 展示状态实际变化后通知；不回放初始状态，不支持或失败时不通知。 */
+    display_change: import('./payloads').MiniProgramDisplayState & {
+        /** api 为开发者调用；user 为用户点击宿主退出全屏按钮。同目标合并时保留首次发起来源。旧宿主可能不提供。 */
+        source?: 'api' | 'user';
+    };
+    viewport_change: import('./payloads').MiniProgramWindowInfoResult;
     launch: {
         timestamp: number;
         url?: string;

package/types/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { CompanionCancelPreparationPayload, CompanionCancelPreparationResult, CompanionGetActiveSessionPayload, CompanionGetActiveSessionResult, CompanionGetInfoPayload, CompanionGetInfoResult, CompanionGetPreparationStatusPayload, CompanionGetPreparationStatusResult, CompanionLaunchPayload, CompanionLaunchResult, CompanionOpenAttachmentPayload, CompanionOpenAttachmentResult, CompanionPreparePayload, CompanionPrepareProgress, CompanionPrepareResult, CompanionSessionAckOutputPayload, CompanionSessionAckOutputResult, CompanionSessionCloseStdinPayload, CompanionSessionCloseStdinResult, CompanionSessionTerminatePayload, CompanionSessionTerminateResult, CompanionSessionWritePayload, CompanionSessionWriteResult, CompanionShowNotificationPayload, CompanionShowNotificationResult, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
+import type { CompanionCancelPreparationPayload, CompanionCancelPreparationResult, CompanionGetActiveSessionPayload, CompanionGetActiveSessionResult, CompanionGetInfoPayload, CompanionGetInfoResult, CompanionGetPreparationStatusPayload, CompanionGetPreparationStatusResult, CompanionLaunchPayload, CompanionLaunchResult, CompanionOpenAttachmentPayload, CompanionOpenAttachmentResult, CompanionPreparePayload, CompanionPrepareProgress, CompanionPrepareResult, CompanionSessionAckOutputPayload, CompanionSessionAckOutputResult, CompanionSessionCloseStdinPayload, CompanionSessionCloseStdinResult, CompanionSessionTerminatePayload, CompanionSessionTerminateResult, CompanionSessionWritePayload, CompanionSessionWriteResult, CompanionShowNotificationPayload, CompanionShowNotificationResult, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
 import type { MiniProgramPermissionRequirement } from './permission-catalog';
 export declare const AUTH_LOGIN_METHOD: "auth.login";
 export declare const USER_GET_INFO_METHOD: "user.getInfo";
@@ -7,6 +7,7 @@ export declare const USER_GET_STEAM_GAME_LIST_METHOD: "user.getSteamGameList";
 export declare const SHARE_COPY_LINK_METHOD: "share.copyLink";
 export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
 export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+export declare const VIEWPORT_SET_DISPLAY_METHOD: "viewport.setDisplay";
 export declare const VIEWPORT_GET_WINDOW_INFO_METHOD: "viewport.getWindowInfo";
 export declare const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD: "viewport.setNavigationBarStyle";
 export declare const STORAGE_GET_STORAGE_METHOD: "storage.getStorage";
@@ -56,7 +57,7 @@ export declare const COMPANION_SHOW_NOTIFICATION_METHOD: "companion.showNotifica
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
-export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD | typeof VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
+export type MiniProgramViewportMethod = typeof VIEWPORT_SET_DISPLAY_METHOD | typeof VIEWPORT_GET_WINDOW_INFO_METHOD | typeof VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
 export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
 export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD | typeof NETWORK_DOWNLOAD_METHOD;
 export type MiniProgramFilesMethod = typeof FILES_PICK_FILES_METHOD | typeof FILES_PICK_DIRECTORY_METHOD | typeof FILES_SAVE_FILE_METHOD;
@@ -174,6 +175,14 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
         readonly kind: "none";
     };
     readonly risk: "low";
+}, {
+    readonly method: "viewport.setDisplay";
+    readonly module: "viewport";
+    readonly capability: "viewport.setDisplay";
+    readonly requirement: {
+        readonly kind: "none";
+    };
+    readonly risk: "low";
 }, {
     readonly method: "storage.getStorage";
     readonly module: "storage";
@@ -473,6 +482,7 @@ export interface MiniProgramCapabilityPayloadMap {
     [SHARE_COPY_LINK_METHOD]: CopyLinkPayload;
     [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuPayload;
     [SHARE_SCREENSHOT_METHOD]: ScreenshotPayload;
+    [VIEWPORT_SET_DISPLAY_METHOD]: SetDisplayPayload;
     [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoPayload;
     [VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD]: SetNavigationBarStylePayload;
     [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
@@ -528,6 +538,7 @@ export interface MiniProgramCapabilityResultMap {
     [SHARE_COPY_LINK_METHOD]: CopyLinkResult;
     [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuResult;
     [SHARE_SCREENSHOT_METHOD]: ScreenshotResult;
+    [VIEWPORT_SET_DISPLAY_METHOD]: SetDisplayResult;
     [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoResult;
     [VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD]: SetNavigationBarStyleResult;
     [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;

package/types/payloads.d.ts

@@ -365,6 +365,26 @@ export interface MiniProgramWindowInfoResult {
     safeArea: MiniProgramSafeArea;
     screenTop: number;
 }
+/** 小程序窗口方向。 */
+export type MiniProgramOrientationMode = 'portrait' | 'landscape';
+/** 宿主确认生效的小程序展示状态；不表示手机旋转传感器状态。 */
+export interface MiniProgramDisplayState {
+    /** 当前小程序锁定的窗口方向。 */
+    orientation: MiniProgramOrientationMode;
+    /** 是否同时收起胶囊和宿主额外顶部栏；横屏始终为 true。 */
+    fullscreen: boolean;
+}
+export interface SetDisplayPayload {
+    /** 锁定竖屏或横屏；省略保持当前目标方向，初始为 portrait。 */
+    orientation?: MiniProgramOrientationMode;
+    /** 同时收起胶囊和宿主额外顶部栏；省略保持当前目标值，初始为 false。合并后横屏强制 true；退出横屏全屏需同时设置 portrait 和 false。 */
+    fullscreen?: boolean;
+}
+/** 本次展示设置的原生支持结果；不支持时保留原生状态，宿主仍可尽力收起 H5 顶部栏。 */
+export type SetDisplayResult = {
+    /** true 表示原生方向与胶囊设置已完成；false 表示已按宿主可用能力降级。 */
+    supported: boolean;
+};
 export type GetWindowInfoPayload = void;
 export type GetWindowInfoResult = MiniProgramWindowInfoResult;
 export type MiniProgramNavigationBarForegroundStyle = 'light' | 'dark';

package/types/permission-catalog.d.ts

@@ -113,5 +113,5 @@ export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
     readonly methods: readonly ["companion.getInfo", "companion.getPreparationStatus", "companion.prepare", "companion.cancelPreparation", "companion.getActiveSession", "companion.launch", "companion.session.write", "companion.session.closeStdin", "companion.session.terminate", "companion.session.ackOutput", "companion.openAttachment", "companion.showNotification"];
     readonly conditions: readonly ["声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"];
 }];
-export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
+export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "viewport.setDisplay", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
 export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;