@heybox/hb-sdk-protocol 0.8.1-alpha.9 → 0.8.2-alpha.1

package/README.md

@@ -11,6 +11,7 @@
 - bridge namespace、协议版本、method 常量和事件名称；
 - capability metadata（module、capability、requirement、risk）和权限机器目录；
 - method payload/result 与错误的 wire 类型；
+- Mobile Mini-program Native Host 的无版本 envelope、operation vocabulary 与跨语言 fixture；
 - `runtime_permissions` schema 解析器和相关类型。
 
 它不拥有：
@@ -45,7 +46,7 @@ import { MINI_PROGRAM_PROTOCOL_CAPABILITIES, type MiniProgramBridgeMessage } fro
 
 耗时能力通过 `MiniProgramCapabilityProgressMap` 按 method 绑定进度 payload；当前覆盖 `network.download` 与 `companion.prepare`。Companion Session wire 只携带不透明 Session ID、controller generation、原始字节 chunk/ack、exit 和 ownership-lost 事件，不暴露 PID、路径或原生句柄。
 
-`CompanionInfo.source` 由可信 Host 标识 `local-dev` 或 `released`，与 `signatureStatus` 一起供授权展示使用；旧 Host 未提供来源时保持未知，不能推定为已审核产物。
+`CompanionInfo.source` 由可信 Host 标识 `local-dev`、`preview` 或 `released`，与 `signatureStatus` 一起供授权展示使用；`preview` 表示审核前预览产物，旧 Host 未提供来源时保持未知，不能推定为已审核产物。
 
 协议包不决定业务授权。`auth.login()` 的 UI、账号会话、授权码签发和 OpenAPI 都由 Host/服务端负责；协议层只传递经过约束的 request/response 数据。
 
@@ -62,6 +63,21 @@ Runtime 可以在握手 response 中附带 `MiniProgramRuntimeEnvironmentInfo`
 
 完整符号以源码导出和生成的 TypeScript declarations 为准。Runtime 集成见 [`@heybox/hb-sdk-runtime`](../hb-sdk-runtime/README.md)，客户端能力见 [`@heybox/hb-sdk`](../hb-sdk/README.md)。
 
+## Mobile Native Host contract
+
+`src/native-host-contract.source.json` 是 operation、chunk limit 与跨语言 case 的唯一可编辑
+registry；`gen:native-host-contract` 同时派生 TypeScript 常量与 Swift/Kotlin 消费的 JSON，
+`check:native-host-contract` 已接入 package build/test 前置门禁。`src/native-host.ts` 提供 wire
+类型与 guards。request envelope 不携带版本号；H5 在创建 Mobile Host 时先调用
+`system.describe`，读取 `protocolVersion`、`contractRevision` 和各 domain 实际支持的 operations。
+缺少 handler、握手超时、协议版本不匹配或 operation 不完整时必须按实际能力 fail closed；公开
+`network.request` 保留 legacy transport，不因协商失败回归。每个请求只允许一个 terminal
+message，取消通过引用原 `requestId` 的独立 control message 完成，二进制 pull 每块最多 64 KiB。
+
+跨语言测试输入位于 `generated/native-host-contract.json`，禁止手改。该文件固定 network
+`open/read/release/transfer` 与 files operation 字段，并覆盖正常分块、取消竞态、重复终态、
+晚到进度、超大分块、跨 session handle 与错误脱敏；平台实现不得维护另一份可编辑 registry。
+
 ## 验证
 
 ```bash

package/dist/index.cjs.js

@@ -334,32 +334,32 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
 ];
 
 function isMiniProgramBridgeMessage(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
-    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString$1(value.nonce)) {
         return false;
     }
     if (value.type === 'handshake') {
-        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+        return isNonEmptyString$1(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
     }
     if (value.type === 'request') {
-        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+        return isNonEmptyString$1(value.id) && isNonEmptyString$1(value.method) && value.error === undefined;
     }
     if (value.type === 'response') {
-        return (isNonEmptyString(value.id) &&
-            (value.method === undefined || isNonEmptyString(value.method)) &&
+        return (isNonEmptyString$1(value.id) &&
+            (value.method === undefined || isNonEmptyString$1(value.method)) &&
             (value.error === undefined || isBridgeError(value.error)));
     }
     if (value.type === 'event') {
-        if (!isNonEmptyString(value.method) || value.error !== undefined)
+        if (!isNonEmptyString$1(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString$1(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
-        return value.id === undefined || isNonEmptyString(value.id);
+        return value.id === undefined || isNonEmptyString$1(value.id);
     }
     if (value.type === 'cancel') {
-        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+        return (value.version === 2 && isNonEmptyString$1(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
     }
     return false;
 }
@@ -372,40 +372,40 @@ function isMiniProgramRelativePath(value) {
     return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
 function isMiniProgramPathRootRef(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.kind === 'sandbox')
         return hasOnlyKeys(value, ['kind']);
-    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+    return value.kind === 'directory' && isNonEmptyString$1(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
 function isMiniProgramFileRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'file')
+    if (!isRecord$2(value) || value.kind !== 'file')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramDirectoryRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'directory')
+    if (!isRecord$2(value) || value.kind !== 'directory')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramFileRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
 }
 function isMiniProgramDirectoryDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'directory' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramDirectoryRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
@@ -417,7 +417,7 @@ function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
 function isMiniProgramFileStat(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
         isNonNegativeSafeInteger(value.size) &&
         (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
@@ -425,7 +425,7 @@ function isMiniProgramFileStat(value) {
         hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
 }
 function isMiniProgramDownloadProgressPayload(value) {
-    if (!isRecord$1(value) ||
+    if (!isRecord$2(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
         typeof value.lengthComputable !== 'boolean' ||
         !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
@@ -436,7 +436,7 @@ function isMiniProgramDownloadProgressPayload(value) {
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 function isMiniProgramCompanionPrepareProgress(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.phase === 'downloading') {
         return (isNonNegativeSafeInteger(value.loaded) &&
@@ -454,10 +454,10 @@ function isMiniProgramOperationProgressPayload(value) {
     return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
 }
 function isSDKHandshakePayload(value) {
-    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+    return isRecord$2(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
 }
 function isBridgeError(value) {
-    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+    return isRecord$2(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
 function isFileMode(value) {
     return value === 'read' || value === 'readwrite';
@@ -468,24 +468,139 @@ function isNonNegativeSafeInteger(value) {
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
-function isNonEmptyString(value) {
+function isNonEmptyString$1(value) {
     return typeof value === 'string' && value.length > 0;
 }
 function hasOnlyKeys(value, allowedKeys) {
     const allowed = new Set(allowedKeys);
     return Object.keys(value).every((key) => allowed.has(key));
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** 当前用户信息与登录能力支持的完整 scope 目录。 */
-const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** 由 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',
@@ -771,6 +886,13 @@ exports.FILE_WRITE_TEXT_METHOD = FILE_WRITE_TEXT_METHOD;
 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;
+exports.MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES = MINI_PROGRAM_NATIVE_CHUNK_MAX_BYTES;
+exports.MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION = MINI_PROGRAM_NATIVE_HOST_CONTRACT_REVISION;
+exports.MINI_PROGRAM_NATIVE_HOST_DESCRIPTION = MINI_PROGRAM_NATIVE_HOST_DESCRIPTION;
+exports.MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT = MINI_PROGRAM_NATIVE_HOST_MESSAGE_EVENT;
+exports.MINI_PROGRAM_NATIVE_HOST_OBJECT = MINI_PROGRAM_NATIVE_HOST_OBJECT;
+exports.MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION = MINI_PROGRAM_NATIVE_HOST_PROTOCOL_VERSION;
+exports.MINI_PROGRAM_NATIVE_OPERATIONS = MINI_PROGRAM_NATIVE_OPERATIONS;
 exports.MINI_PROGRAM_NO_DECLARATION_METHODS = MINI_PROGRAM_NO_DECLARATION_METHODS;
 exports.MINI_PROGRAM_OPERATION_PROGRESS_METHOD = MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
 exports.MINI_PROGRAM_PERMISSION_CATALOG = MINI_PROGRAM_PERMISSION_CATALOG;
@@ -810,6 +932,9 @@ exports.isMiniProgramFileDescriptor = isMiniProgramFileDescriptor;
 exports.isMiniProgramFileRef = isMiniProgramFileRef;
 exports.isMiniProgramFileStat = isMiniProgramFileStat;
 exports.isMiniProgramFileSystemEntityDescriptor = isMiniProgramFileSystemEntityDescriptor;
+exports.isMiniProgramNativeBinaryChunk = isMiniProgramNativeBinaryChunk;
+exports.isMiniProgramNativeHostDescription = isMiniProgramNativeHostDescription;
+exports.isMiniProgramNativeHostMessage = isMiniProgramNativeHostMessage;
 exports.isMiniProgramOperationProgressPayload = isMiniProgramOperationProgressPayload;
 exports.isMiniProgramPathRootRef = isMiniProgramPathRootRef;
 exports.isMiniProgramPermissionKey = isMiniProgramPermissionKey;

package/dist/index.esm.js

@@ -332,32 +332,32 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
 ];
 
 function isMiniProgramBridgeMessage(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
-    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString$1(value.nonce)) {
         return false;
     }
     if (value.type === 'handshake') {
-        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+        return isNonEmptyString$1(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
     }
     if (value.type === 'request') {
-        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+        return isNonEmptyString$1(value.id) && isNonEmptyString$1(value.method) && value.error === undefined;
     }
     if (value.type === 'response') {
-        return (isNonEmptyString(value.id) &&
-            (value.method === undefined || isNonEmptyString(value.method)) &&
+        return (isNonEmptyString$1(value.id) &&
+            (value.method === undefined || isNonEmptyString$1(value.method)) &&
             (value.error === undefined || isBridgeError(value.error)));
     }
     if (value.type === 'event') {
-        if (!isNonEmptyString(value.method) || value.error !== undefined)
+        if (!isNonEmptyString$1(value.method) || value.error !== undefined)
             return false;
         if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
-            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramOperationProgressPayload(value.payload);
+            return value.version === 2 && isNonEmptyString$1(value.id) && isMiniProgramOperationProgressPayload(value.payload);
         }
-        return value.id === undefined || isNonEmptyString(value.id);
+        return value.id === undefined || isNonEmptyString$1(value.id);
     }
     if (value.type === 'cancel') {
-        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+        return (value.version === 2 && isNonEmptyString$1(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
     }
     return false;
 }
@@ -370,40 +370,40 @@ function isMiniProgramRelativePath(value) {
     return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
 function isMiniProgramPathRootRef(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.kind === 'sandbox')
         return hasOnlyKeys(value, ['kind']);
-    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+    return value.kind === 'directory' && isNonEmptyString$1(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
 function isMiniProgramFileRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'file')
+    if (!isRecord$2(value) || value.kind !== 'file')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramDirectoryRef(value) {
-    if (!isRecord$1(value) || value.kind !== 'directory')
+    if (!isRecord$2(value) || value.kind !== 'directory')
         return false;
-    if (isNonEmptyString(value.handleId)) {
+    if (isNonEmptyString$1(value.handleId)) {
         return hasOnlyKeys(value, ['kind', 'handleId']);
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
 function isMiniProgramFileDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramFileRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
 }
 function isMiniProgramDirectoryDescriptor(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'directory' &&
-        isNonEmptyString(value.name) &&
+        isNonEmptyString$1(value.name) &&
         isFileMode(value.mode) &&
         isMiniProgramDirectoryRef(value.ref) &&
         hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
@@ -415,7 +415,7 @@ function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
 function isMiniProgramFileStat(value) {
-    return (isRecord$1(value) &&
+    return (isRecord$2(value) &&
         value.kind === 'file' &&
         isNonNegativeSafeInteger(value.size) &&
         (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
@@ -423,7 +423,7 @@ function isMiniProgramFileStat(value) {
         hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
 }
 function isMiniProgramDownloadProgressPayload(value) {
-    if (!isRecord$1(value) ||
+    if (!isRecord$2(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
         typeof value.lengthComputable !== 'boolean' ||
         !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
@@ -434,7 +434,7 @@ function isMiniProgramDownloadProgressPayload(value) {
     return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
 }
 function isMiniProgramCompanionPrepareProgress(value) {
-    if (!isRecord$1(value))
+    if (!isRecord$2(value))
         return false;
     if (value.phase === 'downloading') {
         return (isNonNegativeSafeInteger(value.loaded) &&
@@ -452,10 +452,10 @@ function isMiniProgramOperationProgressPayload(value) {
     return isMiniProgramDownloadProgressPayload(value) || isMiniProgramCompanionPrepareProgress(value);
 }
 function isSDKHandshakePayload(value) {
-    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+    return isRecord$2(value) && isNonEmptyString$1(value.href) && typeof value.userAgent === 'string' && isNonEmptyString$1(value.sdkVersion);
 }
 function isBridgeError(value) {
-    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+    return isRecord$2(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
 function isFileMode(value) {
     return value === 'read' || value === 'readwrite';
@@ -466,24 +466,139 @@ function isNonNegativeSafeInteger(value) {
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
-function isNonEmptyString(value) {
+function isNonEmptyString$1(value) {
     return typeof value === 'string' && value.length > 0;
 }
 function hasOnlyKeys(value, allowedKeys) {
     const allowed = new Set(allowedKeys);
     return Object.keys(value).every((key) => allowed.has(key));
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** 当前用户信息与登录能力支持的完整 scope 目录。 */
-const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
+/** 由 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',
@@ -726,4 +841,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_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, 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_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramCompanionPrepareProgress, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramNativeBinaryChunk, isMiniProgramNativeHostDescription, isMiniProgramNativeHostMessage, isMiniProgramOperationProgressPayload, isMiniProgramPathRootRef, isMiniProgramPermissionKey, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };