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

package/README.md

@@ -13,6 +13,7 @@
 - method payload/result 与错误的 wire 类型；
 - Mobile Mini-program Native Host 的无版本 envelope、operation vocabulary 与跨语言 fixture；
 - `runtime_permissions` schema 解析器和相关类型。
+- CLI / Host 专用的 `local_dev_grant` 严格合同与纯数据合成，不向小程序业务 API 暴露权限来源。
 
 它不拥有：
 
@@ -50,12 +51,25 @@ import { MINI_PROGRAM_PROTOCOL_CAPABILITIES, type MiniProgramBridgeMessage } fro
 
 协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
 
+## 本地调试临时权限
+
+`parseMiniProgramLocalDevGrant()` 严格接受 schema 1、非负安全整数 revision，以及 `network` / `companion` 清单；未知字段、未知权限、重复项、非 enabled 状态或非法配置都会拒绝整份 grant。网络配置必须是 `useOfficialDomain: false`。解析成功只表示数据合法，Host 仍须验证现有启动票、canonical identity、摘要、期限、CLI lease 并取得每次启动确认。
+
+`createMiniProgramLocalDevGrant()` 仅生成已声明而线上未批准的缺口；Companion 由 CLI 完成本地产物检查后显式列入 eligible keys。`composeLocalDevRuntimePermissions()` 将线上基线与本地声明求交后补齐合法 grant，保留已批准配置的声明子集，输出独立的普通 Runtime 快照和 Host 专用提示清单。生产路径不得调用此合成函数，grant 也不得进入 Manifest、发布资料或 iframe 握手。
+
 ## 握手环境快照
 
 Runtime 可以在握手 response 中附带 `MiniProgramRuntimeEnvironmentInfo`。该快照只包含运行模式、Host App 版本、canonical 小程序 ID/版本和标准化操作系统信息，不包含账号、设备唯一标识、UA 或凭据。字段缺失和旧 Host 通过固定的 `null` / `'unknown'` 语义兼容；客户端 SDK 会在对外派发 `ready` 事件前缓存快照，业务代码通过根包的 `environment` 模块读取。
 
 该 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 +99,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',
@@ -439,7 +447,7 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
  * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) Runtime 权限快照解析器。
  */
 function isMiniProgramBridgeMessage(value) {
-    if (!isRecord$2(value))
+    if (!isRecord$3(value))
         return false;
     if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString$1(value.nonce)) {
         return false;
@@ -589,7 +597,7 @@ function isMiniProgramRelativePath(value) {
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 可作为 derived path root 的目录代理。
  */
 function isMiniProgramPathRootRef(value) {
-    if (!isRecord$2(value))
+    if (!isRecord$3(value))
         return false;
     if (value.kind === 'sandbox')
         return hasOnlyKeys(value, ['kind']);
@@ -655,7 +663,7 @@ function isMiniProgramPathRootRef(value) {
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 使用文件引用的公开 I/O 代理。
  */
 function isMiniProgramFileRef(value) {
-    if (!isRecord$2(value) || value.kind !== 'file')
+    if (!isRecord$3(value) || value.kind !== 'file')
         return false;
     if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
@@ -722,7 +730,7 @@ function isMiniProgramFileRef(value) {
  * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 使用目录引用的公开路径操作代理。
  */
 function isMiniProgramDirectoryRef(value) {
-    if (!isRecord$2(value) || value.kind !== 'directory')
+    if (!isRecord$3(value) || value.kind !== 'directory')
         return false;
     if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
@@ -796,7 +804,7 @@ function isMiniProgramDirectoryRef(value) {
  * @see [SaveFileResult](/reference/symbols/protocol/types/SaveFileResult) save picker 的 direct-ref 文件结果。
  */
 function isMiniProgramFileDescriptor(value) {
-    return (isRecord$2(value) &&
+    return (isRecord$3(value) &&
         value.kind === 'file' &&
         isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
@@ -866,7 +874,7 @@ function isMiniProgramFileDescriptor(value) {
  * @see [PickDirectoryResult](/reference/symbols/protocol/types/PickDirectoryResult) picker 的 direct-ref 返回契约。
  */
 function isMiniProgramDirectoryDescriptor(value) {
-    return (isRecord$2(value) &&
+    return (isRecord$3(value) &&
         value.kind === 'directory' &&
         isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
@@ -1045,7 +1053,7 @@ function isMiniProgramByteArray(value) {
  * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 提供 `stat()` 的当前 session 文件代理。
  */
 function isMiniProgramFileStat(value) {
-    return (isRecord$2(value) &&
+    return (isRecord$3(value) &&
         value.kind === 'file' &&
         isNonNegativeSafeInteger(value.size) &&
         (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
@@ -1105,7 +1113,7 @@ function isMiniProgramFileStat(value) {
  * @see [isMiniProgramBridgeMessage](/reference/symbols/protocol/functions/isMiniProgramBridgeMessage) operation progress envelope 的最低校验。
  */
 function isMiniProgramDownloadProgressPayload(value) {
-    if (!isRecord$2(value) ||
+    if (!isRecord$3(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
         typeof value.lengthComputable !== 'boolean' ||
         !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
@@ -1116,7 +1124,7 @@ function isMiniProgramDownloadProgressPayload(value) {
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 function isMiniProgramCompanionPrepareProgress(value) {
-    if (!isRecord$2(value))
+    if (!isRecord$3(value))
         return false;
     if (value.phase === 'downloading') {
         return (isNonNegativeSafeInteger(value.loaded) &&
@@ -1134,10 +1142,10 @@ function isMiniProgramOperationProgressPayload(value) {
     return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
 }
 function isSDKHandshakePayload(value) {
-    return isRecord$2(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
+    return isRecord$3(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
 }
 function isBridgeError(value) {
-    return isRecord$2(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
+    return isRecord$3(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
 function isFileMode(value) {
     return value === 'read' || value === 'readwrite';
@@ -1155,156 +1163,10 @@ function hasOnlyKeys(value, allowedKeys) {
     const allowed = new Set(allowedKeys);
     return Object.keys(value).every((key) => allowed.has(key));
 }
-function isRecord$2(value) {
+function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** 由 scripts/generate-native-host-contract.mjs 生成，请勿手改。 */
-const MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION = 1;
-const MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION = 1;
-const MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES = 65536;
-const MINI_PROGRAM_NATIVE_OPERATIONS = {
-    "system": [
-        "describe"
-    ],
-    "network": [
-        "open",
-        "read",
-        "release",
-        "transfer"
-    ],
-    "files": [
-        "create",
-        "remove",
-        "exists",
-        "openRead",
-        "openWrite",
-        "read",
-        "release",
-        "write",
-        "stat",
-        "list",
-        "pickFiles",
-        "pickDirectory",
-        "saveFile"
-    ]
-};
-const MINI_PROGRAM_NATIVE_HOST_DESCRIPTION = {
-    "protocolVersion": 1,
-    "contractRevision": 1,
-    "operations": {
-        "system": [
-            "describe"
-        ],
-        "network": [
-            "open",
-            "read",
-            "release",
-            "transfer"
-        ],
-        "files": [
-            "create",
-            "remove",
-            "exists",
-            "openRead",
-            "openWrite",
-            "read",
-            "release",
-            "write",
-            "stat",
-            "list",
-            "pickFiles",
-            "pickDirectory",
-            "saveFile"
-        ]
-    }
-};
-
-/** Android WebMessageListener object 与 iOS WKScriptMessageHandler 共用名称。 */
-const MINI_PROGRAM_NATIVE_HOST_OBJECT = 'hbMiniProgramHost';
-/** Native 通过主文档 CustomEvent 回送 progress/result/error。 */
-const MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT = 'heybox:miniprogram-native-host-message';
-function isMiniProgramNativeHostMessage(value) {
-    if (!isRecord$1(value) || !isNonEmptyString(value.requestId))
-        return false;
-    if (value.type === 'progress')
-        return Object.prototype.hasOwnProperty.call(value, 'payload');
-    if (value.type === 'result')
-        return !Object.prototype.hasOwnProperty.call(value, 'error');
-    if (value.type !== 'error' || !isRecord$1(value.error))
-        return false;
-    return isNonEmptyString(value.error.code) && isNonEmptyString(value.error.message);
-}
-function isMiniProgramNativeHostDescription(value) {
-    if (!isRecord$1(value) ||
-        !isPositiveSafeInteger(value.protocolVersion) ||
-        !isPositiveSafeInteger(value.contractRevision) ||
-        !isRecord$1(value.operations))
-        return false;
-    const operations = value.operations;
-    if (!isOperationList(operations.system) ||
-        !isOperationList(operations.network) ||
-        !isOperationList(operations.files))
-        return false;
-    return operations.system.includes('describe');
-}
-function isMiniProgramNativeBinaryChunk(value) {
-    return (isRecord$1(value) &&
-        isNonEmptyString(value.resourceId) &&
-        typeof value.data === 'string' &&
-        Number.isSafeInteger(value.byteLength) &&
-        Number(value.byteLength) >= 0 &&
-        Number(value.byteLength) <= MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES &&
-        typeof value.eof === 'boolean' &&
-        (Number(value.byteLength) > 0 || value.eof));
-}
-function isRecord$1(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-    return typeof value === 'string' && value.length > 0;
-}
-function isPositiveSafeInteger(value) {
-    return Number.isSafeInteger(value) && Number(value) > 0;
-}
-function isOperationList(value) {
-    return (Array.isArray(value) &&
-        value.every(operation => isNonEmptyString(operation) && operation === operation.trim()) &&
-        new Set(value).size === value.length);
-}
-
-/** 当前用户信息与登录能力支持的完整 scope 目录（canonical 顺序）。 */
-const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile', 'steam_account'];
-/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
-const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
-/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
-const COMPANION_ERROR_CODES = [
-    'COMPANION_UNSUPPORTED',
-    'COMPANION_PREVIEW_UNSUPPORTED',
-    'COMPANION_NOT_DECLARED',
-    'COMPANION_TARGET_UNSUPPORTED',
-    'COMPANION_NOT_PREPARED',
-    'COMPANION_PREPARATION_CANCELLED',
-    'COMPANION_DOWNLOAD_FAILED',
-    'COMPANION_DESCRIPTOR_UNAVAILABLE',
-    'COMPANION_ARCHIVE_INVALID',
-    'COMPANION_INTEGRITY_FAILED',
-    'COMPANION_ENTRYPOINT_INVALID',
-    'COMPANION_USER_CANCELLED',
-    'COMPANION_ELEVATION_DENIED',
-    'COMPANION_OS_BLOCKED',
-    'COMPANION_LAUNCH_FAILED',
-    'COMPANION_SESSION_VERSION_MISMATCH',
-    'COMPANION_SESSION_OWNERSHIP_LOST',
-    'COMPANION_SESSION_EXITED',
-    'COMPANION_PIPE_CLOSED',
-    'COMPANION_OUTPUT_LIMIT',
-    'COMPANION_PROCESS_CRASHED',
-    'COMPANION_ATTACHMENT_NOT_FOUND',
-    'COMPANION_NOTIFICATION_UNAVAILABLE',
-    'COMPANION_TERMINATE_FAILED',
-];
-
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
     'steamLibrary',
@@ -1458,6 +1320,7 @@ const MINI_PROGRAM_NO_DECLARATION_METHODS = [
     'ui.hideLoading',
     'viewport.getWindowInfo',
     'viewport.setNavigationBarStyle',
+    'viewport.setDisplay',
     'device.vibrate',
     'navigation.close',
     'navigation.reload',
@@ -1598,7 +1461,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
  */
 function parseMiniProgramRuntimePermissions(snapshot) {
-    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+    if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
         return { valid: false, permissions: {} };
     }
     if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
@@ -1607,7 +1470,7 @@ function parseMiniProgramRuntimePermissions(snapshot) {
     const seenKeys = new Set();
     const permissions = {};
     for (const rawEntry of snapshot.entries) {
-        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+        if (!isRecord$2(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
             return { valid: false, permissions: {} };
         }
         const inputKey = rawEntry.key.trim();
@@ -1623,7 +1486,7 @@ function parseMiniProgramRuntimePermissions(snapshot) {
         }
         if (key === 'network') {
             const config = rawEntry.config;
-            if (!isRecord(config) || typeof config.useOfficialDomain !== 'boolean') {
+            if (!isRecord$2(config) || typeof config.useOfficialDomain !== 'boolean') {
                 return { valid: false, permissions: {} };
             }
             permissions[key] = {
@@ -1633,7 +1496,7 @@ function parseMiniProgramRuntimePermissions(snapshot) {
             };
             continue;
         }
-        if (rawEntry.config !== null && rawEntry.config !== undefined && (!isRecord(rawEntry.config) || Object.keys(rawEntry.config).length > 0)) {
+        if (rawEntry.config !== null && rawEntry.config !== undefined && (!isRecord$2(rawEntry.config) || Object.keys(rawEntry.config).length > 0)) {
             return { valid: false, permissions: {} };
         }
         permissions[key] = {
@@ -1644,10 +1507,266 @@ function parseMiniProgramRuntimePermissions(snapshot) {
     }
     return { valid: true, permissions };
 }
-function isRecord(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** 仅供开发工具和 Host 使用；新增权限必须单独评估，不能从平台审批目录自动推导。 */
+const LOCAL_DEV_GRANT_PERMISSION_KEYS = ['network', 'companion'];
+/**
+ * 严格解析本地 grant。任何未知字段、重复权限或非法配置都拒绝整份输入。
+ * 只校验数据合同；票据、身份、摘要、过期时间和 CLI lease 必须由 Host 另行验证。
+ */
+function parseMiniProgramLocalDevGrant(value) {
+    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 = [];
+    const seen = new Set();
+    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，不能作为存在临时权限的判断依据。
+ */
+function createMiniProgramLocalDevGrant(options) {
+    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 = [];
+    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 整体降权到基线，已批准配置不会被临时配置覆盖。
+ */
+function composeLocalDevRuntimePermissions(options) {
+    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 = [];
+    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$1(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$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactFields(value, fields) {
+    return isRecord$1(value) && Object.keys(value).length === fields.length
+        && fields.every((field) => Object.prototype.hasOwnProperty.call(value, field));
+}
+
+/** 由 scripts/generate-native-host-contract.mjs 生成，请勿手改。 */
+const MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION = 1;
+const MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION = 1;
+const MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES = 65536;
+const MINI_PROGRAM_NATIVE_OPERATIONS = {
+    "system": [
+        "describe"
+    ],
+    "network": [
+        "open",
+        "read",
+        "release",
+        "transfer"
+    ],
+    "files": [
+        "create",
+        "remove",
+        "exists",
+        "openRead",
+        "openWrite",
+        "read",
+        "release",
+        "write",
+        "stat",
+        "list",
+        "pickFiles",
+        "pickDirectory",
+        "saveFile"
+    ]
+};
+const MINI_PROGRAM_NATIVE_HOST_DESCRIPTION = {
+    "protocolVersion": 1,
+    "contractRevision": 1,
+    "operations": {
+        "system": [
+            "describe"
+        ],
+        "network": [
+            "open",
+            "read",
+            "release",
+            "transfer"
+        ],
+        "files": [
+            "create",
+            "remove",
+            "exists",
+            "openRead",
+            "openWrite",
+            "read",
+            "release",
+            "write",
+            "stat",
+            "list",
+            "pickFiles",
+            "pickDirectory",
+            "saveFile"
+        ]
+    }
+};
+
+/** Android WebMessageListener object 与 iOS WKScriptMessageHandler 共用名称。 */
+const MINI_PROGRAM_NATIVE_HOST_OBJECT = 'hbMiniProgramHost';
+/** Native 通过主文档 CustomEvent 回送 progress/result/error。 */
+const MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT = 'heybox:miniprogram-native-host-message';
+function isMiniProgramNativeHostMessage(value) {
+    if (!isRecord(value) || !isNonEmptyString(value.requestId))
+        return false;
+    if (value.type === 'progress')
+        return Object.prototype.hasOwnProperty.call(value, 'payload');
+    if (value.type === 'result')
+        return !Object.prototype.hasOwnProperty.call(value, 'error');
+    if (value.type !== 'error' || !isRecord(value.error))
+        return false;
+    return isNonEmptyString(value.error.code) && isNonEmptyString(value.error.message);
+}
+function isMiniProgramNativeHostDescription(value) {
+    if (!isRecord(value) ||
+        !isPositiveSafeInteger(value.protocolVersion) ||
+        !isPositiveSafeInteger(value.contractRevision) ||
+        !isRecord(value.operations))
+        return false;
+    const operations = value.operations;
+    if (!isOperationList(operations.system) ||
+        !isOperationList(operations.network) ||
+        !isOperationList(operations.files))
+        return false;
+    return operations.system.includes('describe');
+}
+function isMiniProgramNativeBinaryChunk(value) {
+    return (isRecord(value) &&
+        isNonEmptyString(value.resourceId) &&
+        typeof value.data === 'string' &&
+        Number.isSafeInteger(value.byteLength) &&
+        Number(value.byteLength) >= 0 &&
+        Number(value.byteLength) <= MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES &&
+        typeof value.eof === 'boolean' &&
+        (Number(value.byteLength) > 0 || value.eof));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isPositiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function isOperationList(value) {
+    return (Array.isArray(value) &&
+        value.every(operation => isNonEmptyString(operation) && operation === operation.trim()) &&
+        new Set(value).size === value.length);
+}
+
+/** 当前用户信息与登录能力支持的完整 scope 目录（canonical 顺序）。 */
+const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile', 'steam_account'];
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+const COMPANION_ERROR_CODES = [
+    'COMPANION_UNSUPPORTED',
+    'COMPANION_PREVIEW_UNSUPPORTED',
+    'COMPANION_NOT_DECLARED',
+    'COMPANION_TARGET_UNSUPPORTED',
+    'COMPANION_NOT_PREPARED',
+    'COMPANION_PREPARATION_CANCELLED',
+    'COMPANION_DOWNLOAD_FAILED',
+    'COMPANION_DESCRIPTOR_UNAVAILABLE',
+    'COMPANION_ARCHIVE_INVALID',
+    'COMPANION_INTEGRITY_FAILED',
+    'COMPANION_ENTRYPOINT_INVALID',
+    'COMPANION_USER_CANCELLED',
+    'COMPANION_ELEVATION_DENIED',
+    'COMPANION_OS_BLOCKED',
+    'COMPANION_LAUNCH_FAILED',
+    'COMPANION_SESSION_VERSION_MISMATCH',
+    'COMPANION_SESSION_OWNERSHIP_LOST',
+    'COMPANION_SESSION_EXITED',
+    'COMPANION_PIPE_CLOSED',
+    'COMPANION_OUTPUT_LIMIT',
+    'COMPANION_PROCESS_CRASHED',
+    'COMPANION_ATTACHMENT_NOT_FOUND',
+    'COMPANION_NOTIFICATION_UNAVAILABLE',
+    'COMPANION_TERMINATE_FAILED',
+];
+
 exports.AUTH_LOGIN_METHOD = AUTH_LOGIN_METHOD;
 exports.CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD;
 exports.CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD = CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD;
@@ -1688,6 +1807,7 @@ exports.FILE_REMOVE_METHOD = FILE_REMOVE_METHOD;
 exports.FILE_STAT_METHOD = FILE_STAT_METHOD;
 exports.FILE_WRITE_BYTES_METHOD = FILE_WRITE_BYTES_METHOD;
 exports.FILE_WRITE_TEXT_METHOD = FILE_WRITE_TEXT_METHOD;
+exports.LOCAL_DEV_GRANT_PERMISSION_KEYS = LOCAL_DEV_GRANT_PERMISSION_KEYS;
 exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
 exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
 exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
@@ -1725,7 +1845,10 @@ 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.composeLocalDevRuntimePermissions = composeLocalDevRuntimePermissions;
+exports.createMiniProgramLocalDevGrant = createMiniProgramLocalDevGrant;
 exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
 exports.isMiniProgramByteArray = isMiniProgramByteArray;
@@ -1744,4 +1867,5 @@ exports.isMiniProgramOperationProgressPayload = isMiniProgramOperationProgressPa
 exports.isMiniProgramPathRootRef = isMiniProgramPathRootRef;
 exports.isMiniProgramPermissionKey = isMiniProgramPermissionKey;
 exports.isMiniProgramRelativePath = isMiniProgramRelativePath;
+exports.parseMiniProgramLocalDevGrant = parseMiniProgramLocalDevGrant;
 exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;