@heybox/hb-sdk-protocol 0.8.3-alpha.2 → 0.8.3-alpha.4

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/index.ts

@@ -2,6 +2,7 @@ export * from './bridge';
 export * from './capabilities';
 export * from './constants';
 export * from './guards';
+export * from './local-dev-grant';
 export * from './native-host';
 export * from './payloads';
 export * from './permission-catalog';

package/src/local-dev-grant.ts

@@ -0,0 +1,141 @@
+import { MINI_PROGRAM_PERMISSION_KEYS, type MiniProgramPermissionKey } from './permission-catalog';
+import { parseMiniProgramRuntimePermissions, type MiniProgramRuntimePermissionsSnapshot } from './permissions';
+
+/** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
+export const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'] as const;
+export type MiniProgramLocalDevPermissionKey = (typeof LOCAL_DEV_GRANT_PERMISSION_KEYS)[number];
+export type MiniProgramLocalDevGrantEntry =
+  | { key: 'network'; status: 'enabled'; config: { useOfficialDomain: false } }
+  | { key: 'companion'; status: 'enabled'; config: Record<string, never> };
+
+/** CLI-owned Dev Context 合同，不属于小程序业务 API 或线上批准快照。 */
+export interface MiniProgramLocalDevGrant {
+  schema_version: 1;
+  revision: number;
+  entries: MiniProgramLocalDevGrantEntry[];
+}
+
+/** 调用方已校验的本地声明；不存在的权限不会从 grant 获得授权。 */
+export type MiniProgramLocalDevPermissionDeclarations = Partial<
+  Record<MiniProgramPermissionKey, { enabled: boolean; useOfficialDomain?: boolean }>
+>;
+
+export type ParsedMiniProgramLocalDevGrant =
+  | { valid: true; grant: MiniProgramLocalDevGrant }
+  | { valid: false; grant?: undefined };
+
+/**
+ * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
+ * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
+ */
+export function parseMiniProgramLocalDevGrant(value: unknown): ParsedMiniProgramLocalDevGrant {
+  if (
+    !hasExactFields(value, ['schema_version', 'revision', 'entries']) ||
+    value.schema_version !== 1 ||
+    typeof value.revision !== 'number' ||
+    !Number.isSafeInteger(value.revision) ||
+    value.revision < 0 ||
+    !Array.isArray(value.entries) ||
+    value.entries.length > LOCAL_DEV_GRANT_PERMISSION_KEYS.length
+  ) return { valid: false };
+
+  const entries: MiniProgramLocalDevGrantEntry[] = [];
+  const seen = new Set<string>();
+  for (const entry of value.entries) {
+    if (!hasExactFields(entry, ['key', 'status', 'config']) || entry.status !== 'enabled') return { valid: false };
+    if (typeof entry.key !== 'string' || seen.has(entry.key)) return { valid: false };
+    seen.add(entry.key);
+    if (entry.key === 'network') {
+      if (!hasExactFields(entry.config, ['useOfficialDomain']) || entry.config.useOfficialDomain !== false) return { valid: false };
+      entries.push({ key: 'network', status: 'enabled', config: { useOfficialDomain: false } });
+    } else if (entry.key === 'companion') {
+      if (!hasExactFields(entry.config, [])) return { valid: false };
+      entries.push({ key: 'companion', status: 'enabled', config: {} });
+    } else {
+      return { valid: false };
+    }
+  }
+  entries.sort((a, b) => LOCAL_DEV_GRANT_PERMISSION_KEYS.indexOf(a.key) - LOCAL_DEV_GRANT_PERMISSION_KEYS.indexOf(b.key));
+  return { valid: true, grant: { schema_version: 1, revision: value.revision, entries } };
+}
+
+/**
+ * 从已校验声明生成批准缺口。Companion 默认不符合资格，由 CLI 确认平台、产物与摘要后显式加入。
+ * 空 entries 可保留 revision，不能作为存在临时权限的判断依据。
+ */
+export function createMiniProgramLocalDevGrant(options: {
+  declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
+  runtimePermissions: unknown;
+  revision: number;
+  eligiblePermissionKeys?: readonly MiniProgramLocalDevPermissionKey[];
+}): MiniProgramLocalDevGrant {
+  if (!Number.isSafeInteger(options.revision) || options.revision < 0) throw new Error('本地调试权限 revision 必须是非负安全整数');
+  const approvals = parseMiniProgramRuntimePermissions(options.runtimePermissions);
+  const eligible = new Set(options.eligiblePermissionKeys ?? ['network']);
+  const entries: MiniProgramLocalDevGrantEntry[] = [];
+  for (const key of LOCAL_DEV_GRANT_PERMISSION_KEYS) {
+    if (!eligible.has(key) || options.declaredPermissions[key]?.enabled !== true) continue;
+    if (approvals.valid && approvals.permissions[key]?.status === 'enabled') continue;
+    entries.push(key === 'network'
+      ? { key, status: 'enabled', config: { useOfficialDomain: false } }
+      : { key, status: 'enabled', config: {} });
+  }
+  return { schema_version: 1, revision: options.revision, entries };
+}
+
+/**
+ * 线上基线先与本地声明求交，再补齐临时权限，返回与输入脱离的普通 Runtime 快照。
+ * 调用方只可在当前 Dev Session 已验证且用户接受后传入 grant；本函数不证明其可信来源。
+ * 非法 grant 整体降权到基线，已批准配置不会被临时配置覆盖。
+ */
+export function composeLocalDevRuntimePermissions(options: {
+  declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
+  runtimePermissions: unknown;
+  localDevGrant?: unknown;
+}): {
+  runtimePermissions: MiniProgramRuntimePermissionsSnapshot;
+  temporaryPermissionKeys: MiniProgramLocalDevPermissionKey[];
+  grantValid: boolean;
+} {
+  const baseline = parseMiniProgramRuntimePermissions(options.runtimePermissions);
+  const parsed = parseMiniProgramLocalDevGrant(options.localDevGrant);
+  const permissions = baseline.valid ? baseline.permissions : {};
+  for (const key of MINI_PROGRAM_PERMISSION_KEYS) {
+    if (options.declaredPermissions[key]?.enabled !== true) {
+      delete permissions[key];
+    } else if (key === 'network' && permissions.network) {
+      permissions.network.config.useOfficialDomain = permissions.network.status === 'enabled'
+        && permissions.network.config.useOfficialDomain === true
+        && options.declaredPermissions.network?.useOfficialDomain === true;
+    }
+  }
+  const temporaryPermissionKeys: MiniProgramLocalDevPermissionKey[] = [];
+  if (parsed.valid) {
+    for (const entry of parsed.grant.entries) {
+      if (options.declaredPermissions[entry.key]?.enabled !== true || permissions[entry.key]?.status === 'enabled') continue;
+      permissions[entry.key] = entry;
+      temporaryPermissionKeys.push(entry.key);
+    }
+  }
+  const revision = isRecord(options.runtimePermissions) && typeof options.runtimePermissions.revision === 'number'
+    && Number.isSafeInteger(options.runtimePermissions.revision) && options.runtimePermissions.revision >= 0
+    ? options.runtimePermissions.revision : undefined;
+  return {
+    runtimePermissions: {
+      schema_version: 1,
+      ...(revision === undefined ? {} : { revision }),
+      entries: MINI_PROGRAM_PERMISSION_KEYS.flatMap((key) => permissions[key] ? [permissions[key]!] : []),
+    },
+    temporaryPermissionKeys,
+    grantValid: parsed.valid,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactFields(value: unknown, fields: readonly string[]): value is Record<string, unknown> {
+  return isRecord(value) && Object.keys(value).length === fields.length
+    && fields.every((field) => Object.prototype.hasOwnProperty.call(value, field));
+}

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/index.d.ts

@@ -2,6 +2,7 @@ export * from './bridge';
 export * from './capabilities';
 export * from './constants';
 export * from './guards';
+export * from './local-dev-grant';
 export * from './native-host';
 export * from './payloads';
 export * from './permission-catalog';

package/types/local-dev-grant.d.ts

@@ -0,0 +1,63 @@
+import { type MiniProgramPermissionKey } from './permission-catalog';
+import { type MiniProgramRuntimePermissionsSnapshot } from './permissions';
+/** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
+export declare const LOCAL_DEV_GRANT_PERMISSION_KEYS: readonly ["network", "companion"];
+export type MiniProgramLocalDevPermissionKey = (typeof LOCAL_DEV_GRANT_PERMISSION_KEYS)[number];
+export type MiniProgramLocalDevGrantEntry = {
+    key: 'network';
+    status: 'enabled';
+    config: {
+        useOfficialDomain: false;
+    };
+} | {
+    key: 'companion';
+    status: 'enabled';
+    config: Record<string, never>;
+};
+/** CLI-owned Dev Context 合同，不属于小程序业务 API 或线上批准快照。 */
+export interface MiniProgramLocalDevGrant {
+    schema_version: 1;
+    revision: number;
+    entries: MiniProgramLocalDevGrantEntry[];
+}
+/** 调用方已校验的本地声明；不存在的权限不会从 grant 获得授权。 */
+export type MiniProgramLocalDevPermissionDeclarations = Partial<Record<MiniProgramPermissionKey, {
+    enabled: boolean;
+    useOfficialDomain?: boolean;
+}>>;
+export type ParsedMiniProgramLocalDevGrant = {
+    valid: true;
+    grant: MiniProgramLocalDevGrant;
+} | {
+    valid: false;
+    grant?: undefined;
+};
+/**
+ * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
+ * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
+ */
+export declare function parseMiniProgramLocalDevGrant(value: unknown): ParsedMiniProgramLocalDevGrant;
+/**
+ * 从已校验声明生成批准缺口。Companion 默认不符合资格，由 CLI 确认平台、产物与摘要后显式加入。
+ * 空 entries 可保留 revision，不能作为存在临时权限的判断依据。
+ */
+export declare function createMiniProgramLocalDevGrant(options: {
+    declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
+    runtimePermissions: unknown;
+    revision: number;
+    eligiblePermissionKeys?: readonly MiniProgramLocalDevPermissionKey[];
+}): MiniProgramLocalDevGrant;
+/**
+ * 线上基线先与本地声明求交，再补齐临时权限，返回与输入脱离的普通 Runtime 快照。
+ * 调用方只可在当前 Dev Session 已验证且用户接受后传入 grant；本函数不证明其可信来源。
+ * 非法 grant 整体降权到基线，已批准配置不会被临时配置覆盖。
+ */
+export declare function composeLocalDevRuntimePermissions(options: {
+    declaredPermissions: MiniProgramLocalDevPermissionDeclarations;
+    runtimePermissions: unknown;
+    localDevGrant?: unknown;
+}): {
+    runtimePermissions: MiniProgramRuntimePermissionsSnapshot;
+    temporaryPermissionKeys: MiniProgramLocalDevPermissionKey[];
+    grantValid: boolean;
+};

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;