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

package/skill/references/api-root.md

@@ -9,6 +9,7 @@
 - packages/hb-sdk/src/vite/index.ts
 - packages/hb-sdk/README.md
 - apps/docs/hb-sdk/guide/quick-start.md
+- apps/docs/hb-sdk/guide/environment.md
 - apps/docs/hb-sdk/guide/error-handling.md
 - apps/docs/hb-sdk/guide/lifecycle.md
 - apps/docs/hb-sdk/guide/cli.md
@@ -19,12 +20,13 @@
 - [Public root entrypoint](#public-root-entrypoint)
 - [Vite plugin export](#vite-plugin-export)
 - [App-facing concepts](#app-facing-concepts)
+- [Environment info](#environment-info)
 - [Public modules](#public-modules)
 - [Cloud leaderboard](#cloud-leaderboard)
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1-alpha.1`
+- Version at generation time: `0.8.1-alpha.3`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -47,6 +49,7 @@ export {
   network,
   ui,
   device,
+  environment,
   navigation,
   cloud,
 } from './core/singleton';
@@ -165,6 +168,12 @@ export type {
   VibratePayload,
   VibrateResult,
 } from './modules/device';
+export type {
+  MiniProgramEnvironmentInfo,
+  MiniProgramEnvironmentModule,
+  MiniProgramOperatingSystemName,
+  MiniProgramRuntimeMode,
+} from './modules/environment';
 export type {
   ClosePayload,
   CloseResult,
@@ -189,6 +198,7 @@ import {
   auth,
   cloud,
   device,
+  environment,
   getHandshakeState,
   navigation,
   network,
@@ -217,6 +227,7 @@ const hbSDK = {
   network,
   ui,
   device,
+  environment,
   navigation,
   cloud,
 };
@@ -237,11 +248,13 @@ import {
   MINIAPP_PLATFORM_VALUES,
   renderMiniappManifest,
   validateMiniappPackageVersionForBuild,
-  validateMiniappPlatforms,
   type MiniappPlatform,
 } from '../miniapp-manifest/schema';
-import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
-import { readMiniappPermissionsFromPackageJson } from '../miniapp-manifest/node';
+import {
+  readMiniappPermissionsFromPackageJson,
+  readMiniappPlatformsFromPackageJson,
+  readMiniappVersionFromPackageJson,
+} from '../miniapp-manifest/node';
 import { getMissingPermissionsWarning } from '../miniapp-manifest/permissions';
 import { enforceMiniappHtmlPolicy } from './html-policy';
 import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
@@ -311,16 +324,11 @@ function injectMiniDevConsoleBootstrap(html: string): string {
   return `${html.slice(0, insertAt)}${bootstrap}${html.slice(insertAt)}`;
 }
 
-export interface MiniappManifestOptions {
-  platforms: readonly MiniappPlatform[];
-}
-
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
 
-export function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin {
-  const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
+export function miniappManifest(): MiniappManifestPlugin {
   const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
   let root = process.cwd();
   let outDir = 'dist';
@@ -368,7 +376,8 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
         skipPlatformCsp,
       });
       return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-    },    async closeBundle() {
+    },
+    async closeBundle() {
       // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
       // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
       if (priorBuildError) {
@@ -377,6 +386,7 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
 
       const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
       const sdkVersion = resolveSdkVersion();
+      const platforms = readMiniappPlatformsFromPackageJson(root);
       const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
       if (!parsedPermissions.declared) this.warn(getMissingPermissionsWarning());
       const outputRoot = path.resolve(root, outDir);
@@ -458,7 +468,7 @@ function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
 hb-sdk build [--env <name>] [--verbose]
 ```
 
-`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
+`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
@@ -648,6 +658,96 @@ async function saveFromUserAction(text: string) {
 
 大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
+## Environment info
+
+
+# 环境信息
+
+`environment` 模块提供当前小程序实例的静态环境快照，包括运行模式、小黑盒 App 版本、canonical 小程序身份、操作系统和 SDK 版本。该能力无需在 `heybox.permissions` 中声明，也不会触发用户授权。
+
+## 推荐用法
+
+优先使用异步方法。SDK 尚未完成握手时，`getInfo()` 会自动等待：
+
+```ts
+import { environment } from '@heybox/hb-sdk'
+
+const info = await environment.getInfo()
+
+console.log(info.runtime.mode)
+console.log(info.host.appVersion)
+console.log(info.miniProgram.id, info.miniProgram.version)
+console.log(info.operatingSystem.name, info.operatingSystem.version)
+console.log(info.sdk.version)
+```
+
+返回对象采用固定结构并深度冻结：
+
+```ts
+interface MiniProgramEnvironmentInfo {
+  readonly runtime: {
+    readonly mode: 'production' | 'preview' | 'development' | 'unknown'
+  }
+  readonly host: {
+    readonly appVersion: string | null
+  }
+  readonly miniProgram: {
+    readonly id: string | null
+    readonly version: string | null
+  }
+  readonly operatingSystem: {
+    readonly name: 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown'
+    readonly version: string | null
+  }
+  readonly sdk: {
+    readonly version: string
+  }
+}
+```
+
+## 同步读取
+
+只有已经确认 SDK 为 `ready` 时才能调用 `getInfoSync()`。SDK 会在派发 `ready` 状态前缓存环境快照，因此可以在握手状态订阅中同步读取：
+
+```ts
+import { environment, onHandshakeStateChange } from '@heybox/hb-sdk'
+
+const unsubscribe = onHandshakeStateChange(state => {
+  if (state.status !== 'ready') return
+
+  const info = environment.getInfoSync()
+  console.log(info.operatingSystem.name)
+})
+```
+
+握手完成前调用会抛出 `HbMiniProgramSDKError`，错误码为 `ENVIRONMENT_NOT_READY`。通常不需要自行等待握手；不要求同步执行的代码直接使用 `await environment.getInfo()`。
+
+## 字段语义
+
+| 字段                      | 语义                                                                                                           |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `runtime.mode`            | 当前实例的粗粒度运行模式。正式发布为 `production`，版本预览为 `preview`，本地或 Dev Session 为 `development`。 |
+| `host.appVersion`         | 当前小黑盒 App 版本。它是 Host 提供的不透明字符串。                                                            |
+| `miniProgram.id`          | 平台确认的 canonical `mini_program_id`，不返回数字 ID、用户 ID 或其他旧 ID。                                   |
+| `miniProgram.version`     | 当前加载的小程序版本，是不透明字符串。                                                                         |
+| `operatingSystem.name`    | Host 明确提供的标准系统枚举，不从小程序 iframe 的 UA 推断。                                                    |
+| `operatingSystem.version` | Host 明确提供的系统版本；当前 Host 未提供时为 `null`。                                                         |
+| `sdk.version`             | 当前页面实际运行的 `@heybox/hb-sdk` 版本，遵循 npm SemVer。                                                    |
+
+除 `sdk.version` 外，其他版本字段均不承诺 SemVer 或大小比较语义。需要判断某项能力是否可用时，应依据能力调用结果进行降级，不要仅比较 App 或系统版本。
+
+## 缺失与兼容
+
+旧 Host、匿名本地调试或未提供某个字段的 Host 仍会返回完整结构：缺失字符串为 `null`，未知枚举为 `'unknown'`。非法 Host 字段只会被逐项降级，不会阻断 SDK 握手。
+
+Browser Mock 在 Runtime 启动时使用当前设备预设作为操作系统名称，不读取开发者电脑的 UA。切换设备预设会保留当前 Runtime 和页面状态；需要重新生成环境快照时，使用调试台的重启操作。
+
+## 信任边界
+
+环境信息仅用于界面适配、兼容降级、埋点和诊断，不能用于鉴权、权限控制或风控。小程序提交给服务端的任何环境字段都可能被修改；服务端安全判断必须使用自身认证上下文或平台受信数据。
+
+该 API 不提供设备型号、品牌、UA、CPU、内存、设备唯一标识、账号信息或凭据。屏幕和安全区域继续通过 [`viewport.getWindowInfo()`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/viewport/getWindowInfo/) 获取。
+
 
 # 错误处理
 
@@ -686,6 +786,7 @@ try {
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
 - `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
@@ -750,6 +851,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | 模块         | 用途                                            |
 | ------------ | ----------------------------------------------- |
 | `auth`       | 获取交给开发者服务端交换的短期授权码            |
+| `environment` | 读取当前实例的冻结环境快照                      |
 | `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权      |
 | `share`      | 打开分享、复制链接或截图分享流程                |
 | `ui`         | 展示 Toast 和 Loading                           |

package/skill/references/cli.md

@@ -162,7 +162,7 @@ Browser Mock uses the Node `hb-sdk login` session to send Host `heybox-session`
 hb-sdk build [--env <name>] [--verbose]
 ```
 
-`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
+`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
@@ -181,7 +181,7 @@ hb-sdk build [--env <name>] [--verbose]
 Agent rules:
 
 - Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry.
-- Require explicit `miniappManifest()` configuration and keep typechecking in the project's `scripts.build`.
+- Require target platforms in `package.json#heybox.platforms`, keep the no-argument `miniappManifest()` configured, and keep typechecking in the project's `scripts.build`.
 - Do not claim `hb-sdk build` needs login, binding, or network access, and do not invent unsupported build flags.
 - Existing `vite build` projects remain compatible and must not be auto-migrated.
 

package/skill/references/examples.md

@@ -165,13 +165,21 @@ hb-sdk login clear
 
 ### Vite manifest plugin
 
+```json
+{
+  "heybox": {
+    "platforms": ["android", "ios", "ohos"]
+  }
+}
+```
+
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
+  plugins: [miniappManifest()],
 });
 ```
 

package/skill/references/recipes.md

@@ -413,6 +413,7 @@ try {
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
 - `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。

package/skill/references/safety-boundaries.md

@@ -35,7 +35,7 @@
 - Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
 - `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
 - 仅当当前版本声明且平台已批准 `network` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
-- 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
+- 构建必须启用 `miniappManifest()`，并在 `package.json#heybox.platforms` 显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
 私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
 Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.1-alpha.1+skill.ee950165c4ff",
+  "skillVersion": "0.8.1-alpha.3+skill.c60361a729d0",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.1",
-    "compatibility": "0.8.1-alpha.1"
+    "version": "0.8.1-alpha.3",
+    "compatibility": "0.8.1-alpha.3"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.1",
+    "version": "0.8.1-alpha.3",
     "path": "skill"
   },
-  "integrity": "sha256-ee950165c4ffc752f728ca7b4a5fc8dc497788ecee975c80807f0c22d3e72cb4"
+  "integrity": "sha256-c60361a729d0821a4a2d350d1d06a92ad94abfb77ae2f42320fce078fba023e1"
 }

package/types/core/client.d.ts

@@ -1,4 +1,5 @@
 import { type MiniProgramSDKHandshakeState, type MiniProgramSDKHandshakeStateHandler } from './handshake-state';
+import { type MiniProgramEnvironmentInfo, type MiniProgramEnvironmentReader } from '../modules/environment';
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityPayload, MiniProgramCapabilityResult } from '../protocol/capabilities';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 /**
@@ -36,7 +37,7 @@ export interface MiniProgramOperationRequester extends MiniProgramRequester {
     requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
 }
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
-export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester {
+export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester, MiniProgramEnvironmentReader {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
@@ -61,6 +62,7 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     private destroyed;
     private runtimeUnavailable;
     private runtimeUnavailableError?;
+    private environmentInfo?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     waitForHandshake(): Promise<void>;
@@ -68,6 +70,10 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     getHandshakeState(): MiniProgramSDKHandshakeState;
     /** 订阅握手状态，并立即接收当前状态。 */
     onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
+    /** 等待握手后读取当前实例的环境快照。 */
+    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
     /** 注册小程序事件监听。 */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /** 移除小程序事件监听。 */

package/types/core/sdk.d.ts

@@ -9,6 +9,7 @@ import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
 import { type MiniProgramUiModule } from '../modules/ui';
 import { type MiniProgramDeviceModule } from '../modules/device';
+import { type MiniProgramEnvironmentModule } from '../modules/environment';
 import { type MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -48,6 +49,8 @@ export declare class MiniProgramSDK {
     readonly navigation: MiniProgramNavigationModule;
     /** 云端数据相关开放能力。 */
     readonly cloud: MiniProgramCloudModule;
+    /** 当前实例的环境信息。 */
+    readonly environment: MiniProgramEnvironmentModule;
     constructor(options?: MiniProgramSDKOptions);
     /** 获取当前握手状态。 */
     getHandshakeState(): MiniProgramSDKHandshakeState;

package/types/core/singleton.d.ts

@@ -8,6 +8,7 @@ import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
 import type { MiniProgramUiModule } from '../modules/ui';
 import type { MiniProgramDeviceModule } from '../modules/device';
+import type { MiniProgramEnvironmentModule } from '../modules/environment';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -103,5 +104,7 @@ export declare const device: MiniProgramDeviceModule;
 export declare const navigation: MiniProgramNavigationModule;
 /** 默认 SDK 实例的 cloud 模块。 */
 export declare const cloud: MiniProgramCloudModule;
+/** 默认 SDK 实例的 environment 模块。 */
+export declare const environment: MiniProgramEnvironmentModule;
 /** 重置默认 SDK 实例，仅用于测试。 */
 export declare function resetDefaultSDKForTest(): void;

package/types/index.d.ts

@@ -1,5 +1,5 @@
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, navigation, cloud, } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, environment, navigation, cloud, } from './core/singleton';
 export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
@@ -14,6 +14,7 @@ export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgra
 export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, MiniProgramUiModule, ShowLoadingPayload, ShowLoadingResult, ShowToastPayload, ShowToastResult, } from './modules/ui';
 export type { MiniProgramDeviceModule, MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult, } from './modules/device';
+export type { MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramOperatingSystemName, MiniProgramRuntimeMode, } from './modules/environment';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
 import { getHandshakeState, off, on, onHandshakeStateChange } from './core/singleton';
 declare const hbSDK: {
@@ -30,6 +31,7 @@ declare const hbSDK: {
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;
+    environment: import(".").MiniProgramEnvironmentModule;
     navigation: import(".").MiniProgramNavigationModule;
     cloud: import(".").MiniProgramCloudModule;
 };

package/types/miniapp-manifest/node.d.ts

@@ -1,4 +1,6 @@
 import { type ParsedMiniappPermissions } from './permissions';
+import type { MiniappPlatform } from './schema';
 export declare function readMiniappVersionFromPackageJson(root: string): string;
+export declare function readMiniappPlatformsFromPackageJson(root: string): readonly MiniappPlatform[];
 export declare function readMiniappPermissionsFromPackageJson(root: string, sdkVersion: string): ParsedMiniappPermissions;
 export declare function resolveMiniappSdkVersion(): string;

package/types/miniapp-manifest/schema.d.ts

@@ -27,4 +27,5 @@ export declare function validateMiniappManifestForDeploy(manifest: MiniappManife
     platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
 };
 export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
+export declare function areMiniappPlatformsEqual(left: readonly MiniappPlatform[], right: readonly MiniappPlatform[]): boolean;
 export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/modules/environment/index.d.ts

@@ -0,0 +1,70 @@
+import type { MiniProgramOperatingSystemName, MiniProgramRuntimeMode } from '@heybox/hb-sdk-protocol';
+/** 小程序环境信息中的运行模式。 */
+export type { MiniProgramRuntimeMode } from '@heybox/hb-sdk-protocol';
+/** 小程序环境信息中的操作系统名称。 */
+export type { MiniProgramOperatingSystemName } from '@heybox/hb-sdk-protocol';
+/** 当前小程序实例的只读环境快照。 */
+export interface MiniProgramEnvironmentInfo {
+    readonly runtime: {
+        readonly mode: MiniProgramRuntimeMode;
+    };
+    readonly host: {
+        readonly appVersion: string | null;
+    };
+    readonly miniProgram: {
+        readonly id: string | null;
+        readonly version: string | null;
+    };
+    readonly operatingSystem: {
+        readonly name: MiniProgramOperatingSystemName;
+        readonly version: string | null;
+    };
+    readonly sdk: {
+        readonly version: string;
+    };
+}
+/** SDK 内部读取环境快照所需的最小能力。 */
+export interface MiniProgramEnvironmentReader {
+    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
+    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
+}
+/** 外部小程序可调用的 environment 模块。 */
+export interface MiniProgramEnvironmentModule {
+    /**
+     * 获取当前小程序实例的环境快照，并在必要时自动等待 SDK 握手。
+     *
+     * @since 0.8.1-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    getInfo(): Promise<MiniProgramEnvironmentInfo>;
+    /**
+     * 同步读取握手完成后缓存的环境快照。
+     *
+     * @throws {@link HbMiniProgramSDKError} SDK 尚未 ready 时抛出 `ENVIRONMENT_NOT_READY`。
+     * @since 0.8.1-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    getInfoSync(): MiniProgramEnvironmentInfo;
+}
+/** 创建环境信息模块。 */
+export declare function createEnvironmentModule(reader: MiniProgramEnvironmentReader): MiniProgramEnvironmentModule;
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+export declare function normalizeMiniProgramEnvironmentInfo(value: unknown): MiniProgramEnvironmentInfo;

package/types/protocol.d.ts

@@ -1,5 +1,5 @@
 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, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_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_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_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_INFO_AUTHORIZATION_SCOPES, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramByteArray, isMiniProgramBridgeMessage, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions, } from '@heybox/hb-sdk-protocol';
-export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
+export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramRuntimePermissionEntry, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
 export type { LoginOptions } from './modules/auth';
 export type { GetSteamGameListOptions } from './modules/user';
 export type { MiniProgramEventHandler } from './protocol/types';

package/types/vite/index.d.ts

@@ -40,7 +40,4 @@ export interface MiniappManifestResolvedConfig {
 }
 export { MINIAPP_PLATFORM_VALUES };
 export type { MiniappPlatform };
-export interface MiniappManifestOptions {
-    platforms: readonly MiniappPlatform[];
-}
-export declare function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin;
+export declare function miniappManifest(): MiniappManifestPlugin;