@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/dist/vite.cjs.js

@@ -11,7 +11,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1';
+    : '0.8.2-alpha.2';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3116,7 +3116,58 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+/** 单个小程序版本最多声明的关联游戏数量。 */
 const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
     if (value === undefined)
@@ -3145,8 +3196,25 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
 /** Companion alias 的跨构建、Runtime 与 Host 规范。 */
 const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
@@ -3362,6 +3430,11 @@ function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
@@ -13025,7 +13098,19 @@ const DEV_ERROR_MESSAGE = 'Companion 开发资源暂时不可用';
 /** 与 Companion manifest 一致的单响应上限，避免本地调试入口被大体积声明撑爆。 */
 const DEV_MINI_PROGRAM_MANIFEST_MAX_BYTES = 1024 * 1024;
 const DEV_COMPANION_PATH_PATTERN = /^\/__hb_sdk__\/companions\/([a-z][a-z0-9-]{0,31})\/(windows-x64|macos-arm64)\.zip$/;
+/**
+ * `hb-sdk dev` 为本地 Companion 产物访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+/**
+ * `hb-sdk dev` 为本地小程序 Manifest 访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = 'HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN';
 const devSnapshotStoreKey = Symbol.for('@heybox/hb-sdk/dev-companion-snapshots');
 const devSnapshotRegistry = globalThis;
@@ -13039,6 +13124,104 @@ if (!devSnapshotRegistry[devSnapshotStoreKey]) {
     });
 }
 const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
+/**
+ * 创建工坊小程序使用的 Vite 插件。
+ *
+ * @returns 可直接加入 Vite `plugins` 数组的
+ * [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin)。插件固定名为
+ * `heybox-miniapp-manifest`，并提供 `config`、`configResolved`、`configureServer`、`buildEnd`、
+ * `transformIndexHtml`、`closeBundle` hooks；这些 hooks 由 Vite 调用，应用代码不应手动调用。
+ * @throws `Error` `config` 阶段发现 Vite `base` 不是 `''` 或 `'./'`，或无法解析当前 SDK 版本时抛出。
+ * @throws `Error` `configResolved` 阶段发现已解析插件列表中 `miniappManifest()` 数量不是一个时抛出。
+ * @throws `Error` HTML 缺少 `<head>`，包含 `meta refresh`、`<base>`、禁止的 resource hint，或资源 URL
+ * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
+ * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
+ * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
+ * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
+ *
+ * @remarks
+ * 该函数必须从 `@heybox/hb-sdk/vite` 导入，在 `vite.config.ts` 中无参调用且只注册一次；它不是
+ * iframe 业务代码 API，也没有 options 对象。小程序声明统一来自从 Vite `root` 向上找到的最近一个
+ * `package.json`，插件只读取和规范化，不会改写源文件：
+ *
+ * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
+ *   `0.0.0`；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
+ *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
+ * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
+ * - `heybox.bindAppIds`：可选的最多 20 个正 int32 字符串 App ID；校验、去重并按数值排序，空数组
+ *   在本地产物中等同不写；
+ * - `heybox.companions`：可选的受管桌面程序声明；`source` 相对上述 `package.json` 所在目录解析，
+ *   必须同时声明启用的 `companion` 权限和匹配的 Windows/macOS 目标平台。
+ *
+ * 产物中的 `sdkVersion` 来自当前实际安装的 `@heybox/hb-sdk`，不是项目可配置字段。Vite options、页面
+ * 代码和普通环境变量不能覆盖上述 package 声明；插件也不会联网确认 App ID、平台批准或远端版本状态。
+ *
+ * Hook 行为如下：
+ *
+ * - `config`：省略 `base` 时补为 `'./'`，显式值只接受 `''` / `'./'`；注入 SDK 构建版本，且仅
+ *   `vite serve` 注入开发日志编译常量；
+ * - `configResolved`：确认插件唯一性，记录真实 `root`、`build.outDir`、`serve|build` 命令和精确 HMR
+ *   WebSocket 地址；直接 `vite build` 使用该实际 `outDir`，`hb-sdk build` 则由 CLI 固定为 `dist/`；
+ * - `configureServer`：为 `hb-sdk dev` 注册设备日志、本地小程序 Manifest 与 Companion Manifest/ZIP
+ *   中间件；敏感路由只接受数值 loopback socket/Host、`GET|HEAD` 和 CLI 注入的独立短期令牌，快照在
+ *   配置重载时按 digest 保留，并在服务真正关闭时清理；
+ * - `transformIndexHtml`：校验 HTML URL/标签策略，注入 Runtime Gate；默认注入平台 CSP，serve 时
+ *   `connect-src` 只开放解析出的 HMR WebSocket，并额外注入调试日志 bootstrap；
+ * - `buildEnd`：记住更早的 Rollup/Vite 错误，避免 `closeBundle` 的二次产物错误遮盖根因；
+ * - `closeBundle`：serve 时直接完成；build 时复检最终 HTML，要求整个输出树只有根 `index.html`，再于
+ *   `build.outDir` 写入 `manifest.json`，并把 Companion 目录打包成
+ *   `companions/<alias>/<target>.zip`，记录 size、SHA-256、固定入口与 args。
+ *
+ * HTML 策略会隔离业务 script/modulepreload，直到父 Runtime Gate 以 namespace、版本、nonce、source
+ * 以及 referrer 可确定时的 origin 完成探测；失败时显示只能在小黑盒 App 内打开的安全页。策略拒绝自动跳转、`<base>`、危险
+ * resource hints 和不受支持的外部 URL，并按标签只允许相对 URL、明确允许的 `data:` / `blob:` 或
+ * 小黑盒官方 HTTPS 资源。开发者自行提供的 CSP 会保留；插件管理的 CSP marker 可重复转换而不会叠加。
+ *
+ * 平台 CSP 默认始终保留，直接 `vite build` / `hb-sdk build` 不会因项目声明
+ * `heybox.permissions.network.useOfficialDomain` 而跳过。只有官方 `hb-sdk dev` 或
+ * `hb-sdk remote deploy` 将当前版本的 `network` 声明与远端批准结果求交并确认最终启用后，才会
+ * 建立 verified 上下文供插件读取内部
+ * `HB_SDK_RUNTIME_PERMISSION_CONTEXT` + `HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN` 组合跳过平台 CSP；单独设置
+ * 任一值无效。0.8 兼容期对完全缺失权限声明的项目仍按迁移规则处理；`useOfficialDomain` 不参与
+ * CSP 跳过决定。Runtime Gate、HTML 校验和 Manifest 生成始终保留。
+ *
+ * `HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN`、`HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN`、
+ * `HB_SDK_SKIP_COMPANIONS` 以及上述 CSP 上下文均是 CLI/发布链路内部开关，不是项目配置项。它们在
+ * 插件创建时捕获；开发服务配置重载只会从同一服务的内存快照恢复 CLI 令牌。业务代码和 Vite 配置
+ * 不应手工设置、读取、记录或转发令牌值。正式声明必须继续写在 `package.json#heybox`，内部环境变量
+ * 不能替代声明校验。
+ *
+ * `manifest.json` 是 release pipeline 元数据，不是部署后供页面 fetch 的 CDN 资源。发布链路使用
+ * [isValidVersion](/reference/symbols/miniapp-publish/functions/isValidVersion) 复核版本、
+ * [resolveMiniappManifestPlatforms](/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms)
+ * 解析平台硬切规则、
+ * [parseMiniappBindAppIds](/reference/symbols/miniapp-publish/functions/parseMiniappBindAppIds) 复核游戏绑定，
+ * 并通过 [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 将根
+ * `manifest.json` 排除出普通 CDN 文件。Web/Companion 上传预算由
+ * [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize) 等发布 helper
+ * 独立校验，不能用插件成功代替 deploy 预检。
+ *
+ * @example
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * import { miniappManifest } from '@heybox/hb-sdk/vite'
+ * import { defineConfig } from 'vite'
+ *
+ * export default defineConfig({
+ *   // base 省略时 miniappManifest() 会补为 './'
+ *   plugins: [vue(), miniappManifest()],
+ * })
+ * ```
+ *
+ * @see [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin) 返回插件及各 hook 类型。
+ * @see [安装](/guide/installation) Vite 接入、相对资源路径和构建命令。
+ * @see [权限声明](/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
+ * @see [窗口尺寸与可缩放性](/guide/window-size) `heybox.window` 字段与 Host 消费语义。
+ * @see [受管桌面程序](/guide/companion) Companion 声明、归档和本地联调边界。
+ */
 function miniappManifest() {
     const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
     const deviceLogs = new DeviceLogStore();

package/dist/vite.esm.js

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1';
+    : '0.8.2-alpha.2';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3113,7 +3113,58 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+/** 单个小程序版本最多声明的关联游戏数量。 */
 const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
     if (value === undefined)
@@ -3142,8 +3193,25 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
 /** Companion alias 的跨构建、Runtime 与 Host 规范。 */
 const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
@@ -3359,6 +3427,11 @@ function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
@@ -13022,7 +13095,19 @@ const DEV_ERROR_MESSAGE = 'Companion 开发资源暂时不可用';
 /** 与 Companion manifest 一致的单响应上限，避免本地调试入口被大体积声明撑爆。 */
 const DEV_MINI_PROGRAM_MANIFEST_MAX_BYTES = 1024 * 1024;
 const DEV_COMPANION_PATH_PATTERN = /^\/__hb_sdk__\/companions\/([a-z][a-z0-9-]{0,31})\/(windows-x64|macos-arm64)\.zip$/;
+/**
+ * `hb-sdk dev` 为本地 Companion 产物访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+/**
+ * `hb-sdk dev` 为本地小程序 Manifest 访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = 'HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN';
 const devSnapshotStoreKey = Symbol.for('@heybox/hb-sdk/dev-companion-snapshots');
 const devSnapshotRegistry = globalThis;
@@ -13036,6 +13121,104 @@ if (!devSnapshotRegistry[devSnapshotStoreKey]) {
     });
 }
 const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
+/**
+ * 创建工坊小程序使用的 Vite 插件。
+ *
+ * @returns 可直接加入 Vite `plugins` 数组的
+ * [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin)。插件固定名为
+ * `heybox-miniapp-manifest`，并提供 `config`、`configResolved`、`configureServer`、`buildEnd`、
+ * `transformIndexHtml`、`closeBundle` hooks；这些 hooks 由 Vite 调用，应用代码不应手动调用。
+ * @throws `Error` `config` 阶段发现 Vite `base` 不是 `''` 或 `'./'`，或无法解析当前 SDK 版本时抛出。
+ * @throws `Error` `configResolved` 阶段发现已解析插件列表中 `miniappManifest()` 数量不是一个时抛出。
+ * @throws `Error` HTML 缺少 `<head>`，包含 `meta refresh`、`<base>`、禁止的 resource hint，或资源 URL
+ * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
+ * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
+ * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
+ * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
+ *
+ * @remarks
+ * 该函数必须从 `@heybox/hb-sdk/vite` 导入，在 `vite.config.ts` 中无参调用且只注册一次；它不是
+ * iframe 业务代码 API，也没有 options 对象。小程序声明统一来自从 Vite `root` 向上找到的最近一个
+ * `package.json`，插件只读取和规范化，不会改写源文件：
+ *
+ * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
+ *   `0.0.0`；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
+ *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
+ * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
+ * - `heybox.bindAppIds`：可选的最多 20 个正 int32 字符串 App ID；校验、去重并按数值排序，空数组
+ *   在本地产物中等同不写；
+ * - `heybox.companions`：可选的受管桌面程序声明；`source` 相对上述 `package.json` 所在目录解析，
+ *   必须同时声明启用的 `companion` 权限和匹配的 Windows/macOS 目标平台。
+ *
+ * 产物中的 `sdkVersion` 来自当前实际安装的 `@heybox/hb-sdk`，不是项目可配置字段。Vite options、页面
+ * 代码和普通环境变量不能覆盖上述 package 声明；插件也不会联网确认 App ID、平台批准或远端版本状态。
+ *
+ * Hook 行为如下：
+ *
+ * - `config`：省略 `base` 时补为 `'./'`，显式值只接受 `''` / `'./'`；注入 SDK 构建版本，且仅
+ *   `vite serve` 注入开发日志编译常量；
+ * - `configResolved`：确认插件唯一性，记录真实 `root`、`build.outDir`、`serve|build` 命令和精确 HMR
+ *   WebSocket 地址；直接 `vite build` 使用该实际 `outDir`，`hb-sdk build` 则由 CLI 固定为 `dist/`；
+ * - `configureServer`：为 `hb-sdk dev` 注册设备日志、本地小程序 Manifest 与 Companion Manifest/ZIP
+ *   中间件；敏感路由只接受数值 loopback socket/Host、`GET|HEAD` 和 CLI 注入的独立短期令牌，快照在
+ *   配置重载时按 digest 保留，并在服务真正关闭时清理；
+ * - `transformIndexHtml`：校验 HTML URL/标签策略，注入 Runtime Gate；默认注入平台 CSP，serve 时
+ *   `connect-src` 只开放解析出的 HMR WebSocket，并额外注入调试日志 bootstrap；
+ * - `buildEnd`：记住更早的 Rollup/Vite 错误，避免 `closeBundle` 的二次产物错误遮盖根因；
+ * - `closeBundle`：serve 时直接完成；build 时复检最终 HTML，要求整个输出树只有根 `index.html`，再于
+ *   `build.outDir` 写入 `manifest.json`，并把 Companion 目录打包成
+ *   `companions/<alias>/<target>.zip`，记录 size、SHA-256、固定入口与 args。
+ *
+ * HTML 策略会隔离业务 script/modulepreload，直到父 Runtime Gate 以 namespace、版本、nonce、source
+ * 以及 referrer 可确定时的 origin 完成探测；失败时显示只能在小黑盒 App 内打开的安全页。策略拒绝自动跳转、`<base>`、危险
+ * resource hints 和不受支持的外部 URL，并按标签只允许相对 URL、明确允许的 `data:` / `blob:` 或
+ * 小黑盒官方 HTTPS 资源。开发者自行提供的 CSP 会保留；插件管理的 CSP marker 可重复转换而不会叠加。
+ *
+ * 平台 CSP 默认始终保留，直接 `vite build` / `hb-sdk build` 不会因项目声明
+ * `heybox.permissions.network.useOfficialDomain` 而跳过。只有官方 `hb-sdk dev` 或
+ * `hb-sdk remote deploy` 将当前版本的 `network` 声明与远端批准结果求交并确认最终启用后，才会
+ * 建立 verified 上下文供插件读取内部
+ * `HB_SDK_RUNTIME_PERMISSION_CONTEXT` + `HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN` 组合跳过平台 CSP；单独设置
+ * 任一值无效。0.8 兼容期对完全缺失权限声明的项目仍按迁移规则处理；`useOfficialDomain` 不参与
+ * CSP 跳过决定。Runtime Gate、HTML 校验和 Manifest 生成始终保留。
+ *
+ * `HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN`、`HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN`、
+ * `HB_SDK_SKIP_COMPANIONS` 以及上述 CSP 上下文均是 CLI/发布链路内部开关，不是项目配置项。它们在
+ * 插件创建时捕获；开发服务配置重载只会从同一服务的内存快照恢复 CLI 令牌。业务代码和 Vite 配置
+ * 不应手工设置、读取、记录或转发令牌值。正式声明必须继续写在 `package.json#heybox`，内部环境变量
+ * 不能替代声明校验。
+ *
+ * `manifest.json` 是 release pipeline 元数据，不是部署后供页面 fetch 的 CDN 资源。发布链路使用
+ * [isValidVersion](/reference/symbols/miniapp-publish/functions/isValidVersion) 复核版本、
+ * [resolveMiniappManifestPlatforms](/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms)
+ * 解析平台硬切规则、
+ * [parseMiniappBindAppIds](/reference/symbols/miniapp-publish/functions/parseMiniappBindAppIds) 复核游戏绑定，
+ * 并通过 [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 将根
+ * `manifest.json` 排除出普通 CDN 文件。Web/Companion 上传预算由
+ * [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize) 等发布 helper
+ * 独立校验，不能用插件成功代替 deploy 预检。
+ *
+ * @example
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * import { miniappManifest } from '@heybox/hb-sdk/vite'
+ * import { defineConfig } from 'vite'
+ *
+ * export default defineConfig({
+ *   // base 省略时 miniappManifest() 会补为 './'
+ *   plugins: [vue(), miniappManifest()],
+ * })
+ * ```
+ *
+ * @see [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin) 返回插件及各 hook 类型。
+ * @see [安装](/guide/installation) Vite 接入、相对资源路径和构建命令。
+ * @see [权限声明](/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
+ * @see [窗口尺寸与可缩放性](/guide/window-size) `heybox.window` 字段与 Host 消费语义。
+ * @see [受管桌面程序](/guide/companion) Companion 声明、归档和本地联调边界。
+ */
 function miniappManifest() {
     const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
     const deviceLogs = new DeviceLogStore();

package/package.json

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