@heybox/hb-sdk 0.8.1-alpha.1 → 0.8.1-alpha.3

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

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-C5MZZDa5.js"></script>
+    <script type="module" crossorigin src="/assets/index-B-NHlLsr.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/workbench-state-BwV7bm4n.js">
     <link rel="stylesheet" crossorigin href="/assets/index-P-ra4m1y.css">
   </head>

package/dist/index.cjs.js

@@ -799,7 +799,50 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.1';
+    : '0.8.1-alpha.3';
+
+const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
+const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
+/** 创建环境信息模块。 */
+function createEnvironmentModule(reader) {
+    return {
+        getInfo: () => reader.getEnvironmentInfo(),
+        getInfoSync: () => reader.getEnvironmentInfoSync(),
+    };
+}
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+function normalizeMiniProgramEnvironmentInfo(value) {
+    const root = readRecord$1(value);
+    const runtime = readRecord$1(root?.runtime);
+    const host = readRecord$1(root?.host);
+    const miniProgram = readRecord$1(root?.miniProgram);
+    const operatingSystem = readRecord$1(root?.operatingSystem);
+    return Object.freeze({
+        runtime: Object.freeze({
+            mode: RUNTIME_MODES.has(runtime?.mode) ? runtime?.mode : 'unknown',
+        }),
+        host: Object.freeze({
+            appVersion: readOptionalString(host?.appVersion),
+        }),
+        miniProgram: Object.freeze({
+            id: readOptionalString(miniProgram?.id),
+            version: readOptionalString(miniProgram?.version),
+        }),
+        operatingSystem: Object.freeze({
+            name: OPERATING_SYSTEM_NAMES.has(operatingSystem?.name)
+                ? operatingSystem?.name
+                : 'unknown',
+            version: readOptionalString(operatingSystem?.version),
+        }),
+        sdk: Object.freeze({ version: HB_SDK_VERSION }),
+    });
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function readRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -831,6 +874,7 @@ class MiniProgramBridgeClient {
     destroyed = false;
     runtimeUnavailable = false;
     runtimeUnavailableError;
+    environmentInfo;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -857,6 +901,21 @@ class MiniProgramBridgeClient {
     onHandshakeStateChange(handler) {
         return this.handshakeState.subscribe(handler);
     }
+    /** 等待握手后读取当前实例的环境快照。 */
+    async getEnvironmentInfo() {
+        await this.waitForHandshake();
+        return this.getEnvironmentInfoSync();
+    }
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync() {
+        const state = this.handshakeState.getState();
+        if (state.status === 'failed')
+            throw state.error;
+        if (state.status !== 'ready' || !this.environmentInfo) {
+            throw createSDKError('ENVIRONMENT_NOT_READY', '环境信息将在 SDK ready 后可用');
+        }
+        return this.environmentInfo;
+    }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
         return this.eventBus.on(eventName, handler);
@@ -1109,7 +1168,10 @@ class MiniProgramBridgeClient {
         if (eventName === 'unload') {
             this.markRuntimeUnavailable();
         }
-        else if (eventName === 'ready' && !this.runtimeUnavailable) {
+        else if (eventName === 'ready' && !this.runtimeUnavailable && this.handshakeState.getState().status !== 'failed') {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(undefined);
+            }
             this.resolveHandshakeOnce();
         }
         else if (eventName === 'show' && !this.runtimeUnavailable) {
@@ -1118,6 +1180,12 @@ class MiniProgramBridgeClient {
         this.eventBus.emit(eventName, message.payload);
     }
     handleResponse(message) {
+        if (message.method === SDK_HANDSHAKE_METHOD && message.error === undefined) {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(readRecord(message.payload)?.environment);
+            }
+            return;
+        }
         if (!message.id) {
             return;
         }
@@ -1237,6 +1305,9 @@ class MiniProgramBridgeClient {
         this.pendingRequests.clear();
     }
 }
+function readRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTerminalError) {
     if (!signal)
         return handshake;
@@ -3691,6 +3762,8 @@ class MiniProgramSDK {
     navigation;
     /** 云端数据相关开放能力。 */
     cloud;
+    /** 当前实例的环境信息。 */
+    environment;
     constructor(options) {
         const launchHref = (options?.selfWindow ?? getGlobalWindow())?.location.href;
         this.client = new MiniProgramBridgeClient(options);
@@ -3705,6 +3778,7 @@ class MiniProgramSDK {
         this.device = createDeviceModule(this.client);
         this.navigation = createNavigationModule(this.client);
         this.cloud = createCloudModule(this.client);
+        this.environment = createEnvironmentModule(this.client);
     }
     /** 获取当前握手状态。 */
     getHandshakeState() {
@@ -4003,6 +4077,11 @@ const cloud = {
         getInfo: (options) => getDefaultSDK().cloud.leaderboard.getInfo(options),
     },
 };
+/** 默认 SDK 实例的 environment 模块。 */
+const environment = {
+    getInfo: () => getDefaultSDK().environment.getInfo(),
+    getInfoSync: () => getDefaultSDK().environment.getInfoSync(),
+};
 
 const hbSDK = {
     getHandshakeState,
@@ -4018,6 +4097,7 @@ const hbSDK = {
     network,
     ui,
     device,
+    environment,
     navigation,
     cloud,
 };
@@ -4029,6 +4109,7 @@ exports.auth = auth;
 exports.cloud = cloud;
 exports.default = hbSDK;
 exports.device = device;
+exports.environment = environment;
 exports.files = files;
 exports.getHandshakeState = getHandshakeState;
 exports.navigation = navigation;

package/dist/index.esm.js

@@ -795,7 +795,50 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.1';
+    : '0.8.1-alpha.3';
+
+const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
+const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
+/** 创建环境信息模块。 */
+function createEnvironmentModule(reader) {
+    return {
+        getInfo: () => reader.getEnvironmentInfo(),
+        getInfoSync: () => reader.getEnvironmentInfoSync(),
+    };
+}
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+function normalizeMiniProgramEnvironmentInfo(value) {
+    const root = readRecord$1(value);
+    const runtime = readRecord$1(root?.runtime);
+    const host = readRecord$1(root?.host);
+    const miniProgram = readRecord$1(root?.miniProgram);
+    const operatingSystem = readRecord$1(root?.operatingSystem);
+    return Object.freeze({
+        runtime: Object.freeze({
+            mode: RUNTIME_MODES.has(runtime?.mode) ? runtime?.mode : 'unknown',
+        }),
+        host: Object.freeze({
+            appVersion: readOptionalString(host?.appVersion),
+        }),
+        miniProgram: Object.freeze({
+            id: readOptionalString(miniProgram?.id),
+            version: readOptionalString(miniProgram?.version),
+        }),
+        operatingSystem: Object.freeze({
+            name: OPERATING_SYSTEM_NAMES.has(operatingSystem?.name)
+                ? operatingSystem?.name
+                : 'unknown',
+            version: readOptionalString(operatingSystem?.version),
+        }),
+        sdk: Object.freeze({ version: HB_SDK_VERSION }),
+    });
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function readRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -827,6 +870,7 @@ class MiniProgramBridgeClient {
     destroyed = false;
     runtimeUnavailable = false;
     runtimeUnavailableError;
+    environmentInfo;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -853,6 +897,21 @@ class MiniProgramBridgeClient {
     onHandshakeStateChange(handler) {
         return this.handshakeState.subscribe(handler);
     }
+    /** 等待握手后读取当前实例的环境快照。 */
+    async getEnvironmentInfo() {
+        await this.waitForHandshake();
+        return this.getEnvironmentInfoSync();
+    }
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync() {
+        const state = this.handshakeState.getState();
+        if (state.status === 'failed')
+            throw state.error;
+        if (state.status !== 'ready' || !this.environmentInfo) {
+            throw createSDKError('ENVIRONMENT_NOT_READY', '环境信息将在 SDK ready 后可用');
+        }
+        return this.environmentInfo;
+    }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
         return this.eventBus.on(eventName, handler);
@@ -1105,7 +1164,10 @@ class MiniProgramBridgeClient {
         if (eventName === 'unload') {
             this.markRuntimeUnavailable();
         }
-        else if (eventName === 'ready' && !this.runtimeUnavailable) {
+        else if (eventName === 'ready' && !this.runtimeUnavailable && this.handshakeState.getState().status !== 'failed') {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(undefined);
+            }
             this.resolveHandshakeOnce();
         }
         else if (eventName === 'show' && !this.runtimeUnavailable) {
@@ -1114,6 +1176,12 @@ class MiniProgramBridgeClient {
         this.eventBus.emit(eventName, message.payload);
     }
     handleResponse(message) {
+        if (message.method === SDK_HANDSHAKE_METHOD && message.error === undefined) {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(readRecord(message.payload)?.environment);
+            }
+            return;
+        }
         if (!message.id) {
             return;
         }
@@ -1233,6 +1301,9 @@ class MiniProgramBridgeClient {
         this.pendingRequests.clear();
     }
 }
+function readRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTerminalError) {
     if (!signal)
         return handshake;
@@ -3687,6 +3758,8 @@ class MiniProgramSDK {
     navigation;
     /** 云端数据相关开放能力。 */
     cloud;
+    /** 当前实例的环境信息。 */
+    environment;
     constructor(options) {
         const launchHref = (options?.selfWindow ?? getGlobalWindow())?.location.href;
         this.client = new MiniProgramBridgeClient(options);
@@ -3701,6 +3774,7 @@ class MiniProgramSDK {
         this.device = createDeviceModule(this.client);
         this.navigation = createNavigationModule(this.client);
         this.cloud = createCloudModule(this.client);
+        this.environment = createEnvironmentModule(this.client);
     }
     /** 获取当前握手状态。 */
     getHandshakeState() {
@@ -3999,6 +4073,11 @@ const cloud = {
         getInfo: (options) => getDefaultSDK().cloud.leaderboard.getInfo(options),
     },
 };
+/** 默认 SDK 实例的 environment 模块。 */
+const environment = {
+    getInfo: () => getDefaultSDK().environment.getInfo(),
+    getInfoSync: () => getDefaultSDK().environment.getInfoSync(),
+};
 
 const hbSDK = {
     getHandshakeState,
@@ -4014,8 +4093,9 @@ const hbSDK = {
     network,
     ui,
     device,
+    environment,
     navigation,
     cloud,
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, environment, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };

package/dist/templates/vanilla-vite-js/README.md.ejs

@@ -9,6 +9,6 @@ npm run build
 npm run deploy -- --release-note "更新说明"
 ```
 
-`vite.config.js` 默认声明 `android`、`ios`、`ohos`。发布前请在每个声明的平台完成真机验收；需要支持桌面平台时，由项目自行加入并验收。
+`package.json#heybox.platforms` 默认声明 `android`、`ios`、`ohos`。发布前请在每个声明的平台完成真机验收；需要支持桌面平台时，由项目自行加入并验收。
 
 更多内容见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli) 和 [SDK 文档](https://docs.xiaoheihe.cn/hb_sdk/)。

package/dist/templates/vanilla-vite-js/package.json.ejs

@@ -5,6 +5,7 @@
   "type": "module",
   "heybox": {
     "miniProgramId": "",
+    "platforms": ["android", "ios", "ohos"],
     "permissions": {}
   },
   "scripts": {

package/dist/templates/vanilla-vite-js/vite.config.js

@@ -3,5 +3,5 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
+  plugins: [miniappManifest()],
 });

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.1';
+    : '0.8.1-alpha.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3085,14 +3085,16 @@ function findNearestPackageJsonPath(startDir) {
 function readMiniappVersionFromPackageJson(root) {
     return readMiniappPackageJson(root, true).version;
 }
+function readMiniappPlatformsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return validateMiniappPlatforms(heybox?.platforms, 'package.json#heybox.platforms');
+}
 function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
     const { packageJson } = readMiniappPackageJson(root, false);
-    const heybox = packageJson.heybox;
-    if (heybox !== undefined && !isRecord(heybox)) {
-        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
-    }
-    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
-    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    const present = heybox !== undefined && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(heybox?.permissions, {
         present,
         sdkVersion,
     });
@@ -3118,6 +3120,12 @@ function readMiniappPackageJson(root, requireVersion) {
     }
     return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
 }
+function readMiniappHeyboxConfig(packageJson) {
+    if (packageJson.heybox !== undefined && !isRecord(packageJson.heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    return packageJson.heybox;
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -11903,8 +11911,7 @@ function injectMiniDevConsoleBootstrap(html) {
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
-function miniappManifest(options) {
-    const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
+function miniappManifest() {
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
@@ -11951,7 +11958,8 @@ function miniappManifest(options) {
                 skipPlatformCsp,
             });
             return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-        }, async closeBundle() {
+        },
+        async closeBundle() {
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11959,6 +11967,7 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            const platforms = readMiniappPlatformsFromPackageJson(root);
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.1';
+    : '0.8.1-alpha.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3082,14 +3082,16 @@ function findNearestPackageJsonPath(startDir) {
 function readMiniappVersionFromPackageJson(root) {
     return readMiniappPackageJson(root, true).version;
 }
+function readMiniappPlatformsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return validateMiniappPlatforms(heybox?.platforms, 'package.json#heybox.platforms');
+}
 function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
     const { packageJson } = readMiniappPackageJson(root, false);
-    const heybox = packageJson.heybox;
-    if (heybox !== undefined && !isRecord(heybox)) {
-        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
-    }
-    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
-    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    const present = heybox !== undefined && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(heybox?.permissions, {
         present,
         sdkVersion,
     });
@@ -3115,6 +3117,12 @@ function readMiniappPackageJson(root, requireVersion) {
     }
     return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
 }
+function readMiniappHeyboxConfig(packageJson) {
+    if (packageJson.heybox !== undefined && !isRecord(packageJson.heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    return packageJson.heybox;
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -11900,8 +11908,7 @@ function injectMiniDevConsoleBootstrap(html) {
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
-function miniappManifest(options) {
-    const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
+function miniappManifest() {
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
@@ -11948,7 +11955,8 @@ function miniappManifest(options) {
                 skipPlatformCsp,
             });
             return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-        }, async closeBundle() {
+        },
+        async closeBundle() {
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11956,6 +11964,7 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            const platforms = readMiniappPlatformsFromPackageJson(root);
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.1",
+  "version": "0.8.1-alpha.3",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.1-alpha.1"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.3"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,13 +113,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.28.2",
+    "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.1",
-    "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.3",
+    "@heybox/hb-api": "~1.28.2",
     "@heybox/runtime": "~0.2.0",
-    "@heybox-domain/heybox-theme": "~0.1.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime-policy": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -52,6 +52,8 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
 13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
 14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
+15. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
+16. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
 
 ## Step 5: Use CLI workflows
 
@@ -59,7 +61,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
 3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
-5. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
+5. Declare the actual supported platforms in `package.json#heybox.platforms` and keep the no-argument `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the declaration, Manifest, or Runtime gate output is missing or inconsistent.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
 7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
 8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
@@ -88,13 +90,14 @@ For workshop mini-program business code:
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
 9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
+10. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
 
 For CLI and local development:
 
 1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
 2. Do not skip `auth.login()` in mini-program code. Browser Mock may reuse the Node `hb-sdk login` session for Host network requests, but the page must still call `auth.login()` and handle the authorization dialog. Never paste CLI credentials into page JavaScript.
 3. Use the built-in local debugging page instead of creating another browser Mock.
-4. Keep the Vite `miniappManifest()` plugin enabled.
+4. Keep target platforms in `package.json#heybox.platforms` and the no-argument Vite `miniappManifest()` plugin enabled. Do not configure platforms in Vite or maintain a second platform list.
 5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
 7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.

package/skill/references/api-protocol.md

@@ -176,7 +176,10 @@ export type {
   MiniProgramNetworkMethod,
   MiniProgramNetworkParams,
   MiniProgramNetworkRequestMethod,
+  MiniProgramOperatingSystemName,
   MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimeEnvironmentInfo,
+  MiniProgramRuntimeMode,
   MiniProgramRuntimePermissionsSnapshot,
   MiniProgramRuntimePermissionStatus,
   MiniProgramSafeArea,
@@ -215,6 +218,7 @@ export type {
   SaveFilePayload,
   SaveFileResult,
   SDKHandshakePayload,
+  SDKHandshakeResult,
   SetClipboardPayload,
   SetClipboardResult,
   SetNavigationBarStylePayload,
@@ -295,12 +299,12 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 65 | 60 | 1 |
-| Protocol API | 0 | 13 | 56 | 90 | 47 |
+| Root API | 2 | 4 | 67 | 62 | 2 |
+| Protocol API | 0 | 13 | 58 | 90 | 47 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
-| Vite API | 0 | 1 | 5 | 1 | 1 |
+| Vite API | 0 | 1 | 4 | 1 | 1 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=f9457e0ad4a2e5f69896c7b05a8563ae5171df141d86cf81aa6fe1b4aca6b280 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=a8018ebd23e4d885efbe08f622a6cf4780dd152d5f90cc4a78d2eb7e15eca2e2 -->
 
 ## SDK API