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

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.8.3-alpha.3 - 2026-09-20
+
+> 摘要：新增移动端横竖屏与全屏设置，并提供宿主退出全屏入口和展示状态通知。
+> 影响级别：常规
+> 开发者动作：按需调用 `viewport.setDisplay()`，并根据 `supported` 与实际窗口信息适配页面。
+> 兼容范围：现有 API 保持兼容；原生能力不可用时返回 `supported: false`，不代表已完成转屏或完整全屏。
+
+### 新增能力
+
+- [`viewport.setDisplay`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/viewport/setDisplay) 支持横竖屏与全屏设置；横屏统一全屏，返回普通页面时联合设置竖屏与非全屏。
+- `display_change` 通知已确认的展示状态，通过 `source` 区分 API 调用与用户点击退出按钮；窗口尺寸与安全区继续通过 `viewport_change` 获取。
+
+### 行为调整
+
+- 全屏时提供贴右边缘的退出按钮，一秒后收起并保留可点击入口；用户退出时恢复竖屏、非全屏。
+- 展示设置支持状态去重、并发淘汰、超时取消和退出恢复；页面按实际 WebView 窗口与安全区适配。
+
+
+## 0.8.3-alpha.2
+
+### 新增能力
+
+- 支持在 `package.json#heybox.category` 声明小程序类别（`tool`、`game`、`other`）；构建写入 Manifest，CLI 与 Open 提审自动采用，类别随版本审核、发布生效。
+
+### 必须操作
+
+- 新上传版本（含已有小程序更新）必须声明类别；缺少类别的项目需补配置后重新构建上传。开发者提审页不展示或提供手动选择类别，也不发送独立的 `category` 参数。
+- `manifest.category` 是本版本发布合同的硬切字段。早于本版本构建、且缺少类别的历史产物不能直接重新上传或提审；旧项目必须在 `package.json#heybox.category` 补齐类别并使用当前 SDK 重新构建。已发布版本不受影响，COA 运营维护存量分类的入口继续保留。
+
 ## 0.8.3-alpha.1
 
 ### 问题修复

package/README.md

@@ -120,6 +120,8 @@ async function revokeAuthorizationFromUserAction() {
 }
 ```
 
+小程序类别需在 `package.json#heybox.category` 声明为 `tool`、`game` 或 `other`，构建后写入 Manifest，CLI/Open 提审自动采用，发布后生效。开发者提审页不展示或提供手动选择类别；新上传版本（含已有小程序更新）必须声明，缺少类别的项目须补配置后重新构建上传，详见 [小程序类别](https://docs.xiaoheihe.cn/hb_sdk/guide/cli#小程序类别)。
+
 `bindAppIds` 只接受规范十进制字符串（形如 `/^[1-9]\d*$/`，拒绝前导零、空串与非数字），每项必须是正 int32（最大 `2147483647`），数组内不允许重复，最多 20 项，并按数值升序写入 Manifest。它不是权限，构建不联网；游戏真实性在远端预检和提审时校验。字段缺失或 `[]` 都表示清空绑定。PC 展示仍受 `platforms` 过滤。
 
 再启用构建插件：
@@ -251,6 +253,40 @@ V1 仅支持普通权限启动；Manifest 的 `elevation` 只能省略或设为
 `displayName` 最多 120 个 Unicode code point；args 最多 64 项，单项最多 1024 UTF-8 bytes、总计最多
 16384 UTF-8 bytes，并拒绝 NUL、CR 和 LF。
 
+## 横竖屏与胶囊
+
+```ts
+const { supported } = await hbSDK.viewport.setDisplay({ orientation: 'landscape', fullscreen: true });
+if (!supported) {
+  // 原生方向与胶囊保持现状，继续按实际窗口尺寸提供可用布局。
+}
+// 横屏始终全屏；返回普通页面时联合恢复默认展示。
+await hbSDK.viewport.setDisplay({ orientation: 'portrait', fullscreen: false });
+
+const stopViewport = hbSDK.on('viewport_change', (windowInfo) => {
+  console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea);
+});
+// 页面销毁时调用 stopViewport()。
+```
+
+新容器默认竖屏、非全屏，配置持续到下次调用或退出容器。SPA 路由应在进入页面时设置目标状态。
+`setDisplay` 至少传一个字段；省略字段保持当前目标值，合并后横屏强制 `fullscreen: true`，竖屏才按 `fullscreen` 控制。后续设置先合并目标，再替换不同的在途设置，旧调用以 `ORIENTATION_SUPERSEDED` 失败；重复设置会合并。
+支持原生能力时，Promise 在宿主布局稳定后返回 `{ supported: true }`。缺少能力时 SDK 返回 `{ supported: false }`，原生方向与胶囊保持现状；新版 H5 宿主仍尽力收起额外顶部栏。`false` 不代表已经实现完整全屏。超时仍返回 `ORIENTATION_TIMEOUT`，取消、参数及其它执行错误也不被吞掉。布局应适配当前窗口与四边安全区，
+不能依赖固定竖屏宽度；首次读取使用 `viewport.getWindowInfo()`，后续使用 `viewport_change`。
+`display_change` 在宿主确认方向或全屏状态发生变化后发送 `{ orientation, fullscreen, source }`，包括开发者调用 `setDisplay()` 和用户点击宿主退出全屏按钮。事件报告归一化后的实际状态：横屏始终全屏，用户点击退出按钮后恢复竖屏、非全屏。重复状态、不支持（`supported: false`）、失败、超时、取消及被后续请求替换的设置不发送事件。事件不回放初始状态，新容器默认竖屏、非全屏；它不监听手机旋转传感器，窗口尺寸与安全区仍通过 `viewport_change` 获取。请在调用设置前注册监听，并在页面销毁时取消。
+
+```ts
+const stopDisplay = hbSDK.on('display_change', ({ orientation, fullscreen }) => {
+  console.log('当前方向', orientation, '当前全屏状态', fullscreen)
+})
+
+// 页面销毁时调用 stopDisplay()。
+```
+
+全屏同时收起胶囊和宿主额外顶部栏，不保证原生内容铺满容器；页面应按实际 WebView 窗口和安全区适配；这不代表系统状态栏、手势条被隐藏或设备安全区消失，重要控件仍应按实际窗口信息避让。宿主 Runtime 统一提供小尺寸“退出全屏”浮动按钮：首次出现和点击右侧边缘重新唤出后，均在 1 秒后淡出并收至边缘，保留可点击的唤出入口。展开时点击按钮会调用 `setDisplay({ orientation: 'portrait', fullscreen: false })`，恢复竖屏、非全屏；退出全屏或销毁会话时移除按钮。H5 无需另行提供退出控件，也可按需提供自己的入口。业务也可通过 `navigation.close()` 提供退出入口；窗口变化事件本身不代表设备方向发生变化。
+
+该 API 为实验能力，自 SDK `0.8.1-alpha.4` 提供，Android/iOS 原生能力最低客户端版本为 `1.3.396`，实际以桥接能力为准。SDK 将 `METHOD_FORBIDDEN`、`METHOD_NOT_FOUND` 和 `REQUEST_UNSUPPORTED` 统一转换为 `{ supported: false }`。本地 Web/PC Host 不伪造方向或胶囊支持，请在已接入的移动端真机验收。
+
 ## 错误处理
 
 握手失败会保留在持久状态中，可在订阅回放时直接处理原始错误：
@@ -282,7 +318,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `ui`         | 展示 Toast 和 Loading                           |
 | `device`     | 调用振动和剪贴板能力                            |
 | `navigation` | 关闭、刷新页面或打开小黑盒页面                  |
-| `viewport`   | 读取窗口信息和设置导航栏样式                    |
+| `viewport`   | 读取窗口信息、设置方向/胶囊及导航栏样式                    |
 | `storage`    | 读写当前小程序的隔离存储                        |
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
@@ -419,6 +455,8 @@ hb-sdk remote deploy --release-note "本次更新说明"
 
 Host/Runtime 集成维护者请先阅读 [`@heybox/hb-sdk-runtime` README](../hb-sdk-runtime/README.md)、[Runtime Reference](../hb-sdk-runtime/docs/reference/) 和 [`@heybox/hb-sdk-protocol` README](../hb-sdk-protocol/README.md)。
 
+`display_change.source` 区分变化来源：`api` 为开发者调用，`user` 为用户点击宿主退出全屏按钮。同目标并发合并时保留首次发起操作的来源；重复状态不额外发事件。旧宿主可能不含 source，不能将缺失来源推断为用户操作。仅用户退出时跳页，应判断 `source === 'user' && !fullscreen`，确认已恢复竖屏、非全屏后按业务需要跳转。
+
 ## 版本名称与图片（0.8.2）
 
 在 `package.json#heybox` 配置 `name`、`icon`、`coverImages`。图片为项目内文件，icon 200×200、封面 1–5 张，单张不超过 10 MiB 和 4000 万像素。构建原样复制到版本产物，发布时才更新线上资料。全缺失配置可通过 bind/dev/deploy 从当前正式发布快照自动迁移；离线 build 不迁移。详见[版本资料与迁移指南](https://docs.xiaoheihe.cn/hb_sdk/guide/version-profile)。

package/dist/cli-chunks/{build-DUtuGfHf.cjs → build-Dydd4Rzd.cjs}

@@ -3,13 +3,13 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-xuikbF7W.cjs');
-var index = require('./index-PKu0Zv8R.cjs');
-var projectVite = require('./project-vite-BU2-_Krd.cjs');
-require('./version-BTkX3iYg.cjs');
+var runtimeGate = require('./runtime-gate-CE1ln9xc.cjs');
+var index = require('./index-B_HjHK3d.cjs');
+var projectVite = require('./project-vite-CUh6Dsv5.cjs');
+require('./version-BNNxfn8M.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');
@@ -36,6 +36,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
     const declaredPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     const declaredWindow = runtimePermissionEnv.readMiniappWindowFromPackageJson(projectRoot);
     const declaredBindAppIds = runtimePermissionEnv.readMiniappBindAppIdsFromPackageJson(projectRoot);
+    const declaredCategory = runtimePermissionEnv.readMiniappCategoryFromPackageJson(projectRoot);
     runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
     await fs.rm(distDir, { force: true, recursive: true });
     try {
@@ -54,7 +55,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
                     write: true,
                 },
             }), { successText: 'Vite 构建完成' });
-            const result = await validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds);
+            const result = await validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds, declaredCategory);
             logger.success(`构建完成: dist/ | manifest version ${result.version} | sdkVersion ${result.sdkVersion} | 待上传文件 ${result.fileCount} 个 | ${formatSize(result.totalBytes)}`);
             return result;
         }, env);
@@ -83,7 +84,7 @@ function createFixedBuildOutputPlugin(projectRoot) {
         },
     };
 }
-async function validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds) {
+async function validateBuildOutput(projectRoot, logger, declaredPlatforms, declaredWindow, declaredBindAppIds, declaredCategory) {
     const distDir = path.join(projectRoot, 'dist');
     const entryHtmlPath = path.join(distDir, 'index.html');
     const manifestPath = path.join(distDir, 'manifest.json');
@@ -104,6 +105,9 @@ async function validateBuildOutput(projectRoot, logger, declaredPlatforms, decla
     const validated = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
     const { platforms, sdkVersion, version, permissions, window } = validated;
     const bindAppIds = validated.bindAppIds ?? [];
+    if (validated.category !== declaredCategory) {
+        throw new Error('dist/manifest.json.category 与 package.json#heybox.category 不一致，请重新 build');
+    }
     if (!runtimePermissionEnv.areMiniappPlatformsEqual(platforms, declaredPlatforms)) {
         throw new Error('dist/manifest.json.platforms 与 package.json#heybox.platforms 不一致，请重新 build');
     }

package/dist/cli-chunks/{context-DebQqIXh.cjs → context-DcuY0bGO.cjs}

@@ -3,10 +3,10 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-CySUtnTY.cjs');
+var session = require('./session-CKuEz-ih.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

package/dist/cli-chunks/{create-BYQb0ptI.cjs → create-DKVTlorM.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 require('node:module');
 require('os');
 require('node:crypto');

package/dist/cli-chunks/{dev-ILhZhsHN.cjs → dev-DbrUeTqi.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var context = require('./context-DebQqIXh.cjs');
+var context = require('./context-DcuY0bGO.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
 var os = require('node:os');
@@ -9,16 +9,16 @@ var net = require('node:net');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CySUtnTY.cjs');
+var session = require('./session-CKuEz-ih.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-BU2-_Krd.cjs');
-var version = require('./version-BTkX3iYg.cjs');
+var projectVite = require('./project-vite-CUh6Dsv5.cjs');
+var version = require('./version-BNNxfn8M.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1950,8 +1950,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-ILhZhsHN.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-ILhZhsHN.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-DbrUeTqi.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-DbrUeTqi.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -11049,7 +11049,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-Sczt7W37.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-42g2R7qD.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;

package/dist/cli-chunks/{doctor-KSe4lGEv.cjs → doctor-D184dg_h.cjs}

@@ -3,7 +3,7 @@
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{index-IBIMsIDt.cjs → index-BG8JJ9pA.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-PKu0Zv8R.cjs');
+var index$2 = require('./index-B_HjHK3d.cjs');
 var require$$0$3 = require('fs');
 var require$$0$2 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$5 = require('assert');
 var require$$0$4 = require('events');
 var require$$1$1 = require('util');
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
 var require$$0$7 = require('net');
 var require$$0$6 = require('url');
 var require$$2$1 = require('http');

package/dist/cli-chunks/{index-PKu0Zv8R.cjs → index-B_HjHK3d.cjs}

@@ -235,19 +235,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-PKu0Zv8R.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B_HjHK3d.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-PKu0Zv8R.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B_HjHK3d.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-PKu0Zv8R.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B_HjHK3d.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-PKu0Zv8R.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B_HjHK3d.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-PKu0Zv8R.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-B_HjHK3d.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13467,7 +13467,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.3-alpha.1';
+const BUILT_CLI_VERSION = '0.8.3-alpha.3';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13826,39 +13826,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-i8NtyI10.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-D3MBcgNb.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-i8NtyI10.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-D3MBcgNb.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-i8NtyI10.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-D3MBcgNb.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-DUtuGfHf.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-Dydd4Rzd.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BYQb0ptI.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-DKVTlorM.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-ILhZhsHN.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DbrUeTqi.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-KSe4lGEv.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-D184dg_h.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-BN_mjQ_T.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-oLEQS_U6.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-B-f9D0yj.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-EBGDOJL3.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index.esm-Sczt7W37.cjs → index.esm-42g2R7qD.cjs}

@@ -11,8 +11,8 @@ var require$$0$4 = require('url');
 var require$$0 = require('zlib');
 var require$$0$1 = require('buffer');
 var require$$1 = require('util');
-var index = require('./index-PKu0Zv8R.cjs');
-var dev = require('./dev-ILhZhsHN.cjs');
+var index = require('./index-B_HjHK3d.cjs');
+var dev = require('./dev-DbrUeTqi.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');
@@ -23,12 +23,12 @@ require('node:crypto');
 require('readline');
 require('tty');
 require('assert');
-require('./context-DebQqIXh.cjs');
-require('./runtime-permission-env-Bl2jhPQm.cjs');
-require('./version-BTkX3iYg.cjs');
+require('./context-DcuY0bGO.cjs');
+require('./runtime-permission-env-CVt4QPbX.cjs');
+require('./version-BNNxfn8M.cjs');
 require('node:async_hooks');
 require('sharp');
-require('./session-CySUtnTY.cjs');
+require('./session-CKuEz-ih.cjs');
 require('fs');
 require('constants');
 require('node:os');
@@ -42,7 +42,7 @@ require('node:buffer');
 require('node:url');
 require('node:util');
 require('node:child_process');
-require('./project-vite-BU2-_Krd.cjs');
+require('./project-vite-CUh6Dsv5.cjs');
 require('node:zlib');
 
 var bufferUtil = {exports: {}};

package/dist/cli-chunks/{login-i8NtyI10.cjs → login-D3MBcgNb.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-CySUtnTY.cjs');
+var session = require('./session-CKuEz-ih.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-BU2-_Krd.cjs → project-vite-CUh6Dsv5.cjs}

@@ -5,7 +5,7 @@ var fs$1 = require('node:fs/promises');
 var node_module = require('node:module');
 var path = require('node:path');
 var node_url = require('node:url');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-B-f9D0yj.cjs → remote-EBGDOJL3.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
-var context = require('./context-DebQqIXh.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
+var context = require('./context-DcuY0bGO.cjs');
 var promises = require('node:readline/promises');
-var index = require('./index-PKu0Zv8R.cjs');
-var session = require('./session-CySUtnTY.cjs');
+var index = require('./index-B_HjHK3d.cjs');
+var session = require('./session-CKuEz-ih.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
 var node_crypto = require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-xuikbF7W.cjs');
-require('./version-BTkX3iYg.cjs');
+var runtimeGate = require('./runtime-gate-CE1ln9xc.cjs');
+require('./version-BNNxfn8M.cjs');
 require('node:async_hooks');
 require('sharp');
 require('node:module');
@@ -274,7 +274,7 @@ function createDefaultCosClient(uploadToken, COS) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-IBIMsIDt.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-BG8JJ9pA.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {
@@ -517,6 +517,7 @@ async function runDeployCommand(options, runtime = {}) {
     const declaredPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     const declaredWindow = runtimePermissionEnv.readMiniappWindowFromPackageJson(projectRoot);
     const declaredBindAppIds = runtimePermissionEnv.readMiniappBindAppIdsFromPackageJson(projectRoot);
+    const declaredCategory = runtimePermissionEnv.readMiniappCategoryFromPackageJson(projectRoot);
     const releaseNote = await resolveDeployReleaseNote(options, runtime);
     const session$1 = await logger.task('正在校验 Heybox 登录态', () => (runtime.requireAuthSession ?? session.requireHeyboxAuthSession)({ loginBaseUrl }), { successText: 'Heybox 登录态有效' });
     logger.debug(`Heybox API: ${apiBaseUrl}`);
@@ -590,6 +591,9 @@ async function runDeployCommand(options, runtime = {}) {
             const distDir = path.join(projectRoot, 'dist');
             const parsedManifest = await readDeployManifest(projectRoot, logger);
             ({ manifest, version } = parsedManifest);
+            if (manifest.category !== declaredCategory) {
+                throw new Error('dist/manifest.json.category 与 package.json#heybox.category 不一致，请重新 build 后再 deploy');
+            }
             if (!declaredPlatforms || !runtimePermissionEnv.areMiniappPlatformsEqual(parsedManifest.platforms, declaredPlatforms)) {
                 throw new Error('dist/manifest.json.platforms 与 package.json#heybox.platforms 不一致，请重新 build 后再 deploy');
             }

package/dist/cli-chunks/{runtime-gate-xuikbF7W.cjs → runtime-gate-CE1ln9xc.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-Bl2jhPQm.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CVt4QPbX.cjs');
 
 // Shorthands
 /**

package/dist/cli-chunks/{runtime-permission-env-Bl2jhPQm.cjs → runtime-permission-env-CVt4QPbX.cjs}

@@ -2,10 +2,19 @@
 
 var fs = require('node:fs');
 var path = require('node:path');
-var version = require('./version-BTkX3iYg.cjs');
+var version = require('./version-BNNxfn8M.cjs');
 require('node:crypto');
 var node_async_hooks = require('node:async_hooks');
 
+/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
+    if (value === undefined)
+        return undefined;
+    if (value === 'tool' || value === 'game' || value === 'other')
+        return value;
+    throw new Error(`${sourceLabel} 必须是 tool、game 或 other`);
+}
+
 var re = {exports: {}};
 
 var constants;
@@ -3467,6 +3476,10 @@ function validateMiniappManifestForDeploy(manifest) {
     });
     const companions = validateGeneratedCompanions(manifest.companions);
     const window = validateMiniappWindow(manifest.window, 'manifest.window');
+    const category = parseMiniappCategory(manifest.category, 'manifest.category');
+    if (category === undefined) {
+        throw new Error('manifest.category 缺失，请在 package.json#heybox.category 声明 tool、game 或 other 后重新构建');
+    }
     const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
     return {
         version,
@@ -3477,6 +3490,7 @@ function validateMiniappManifestForDeploy(manifest) {
         ...(companions === undefined ? {} : { companions }),
         ...(window === undefined ? {} : { window }),
         ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
+        ...(category === undefined ? {} : { category }),
     };
 }
 function validateGeneratedCompanions(value) {
@@ -12603,6 +12617,10 @@ function readMiniappBindAppIdsFromPackageJson(root) {
     const heybox = readMiniappHeyboxConfig(packageJson);
     return parseMiniappBindAppIds(heybox?.bindAppIds);
 }
+function readMiniappCategoryFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root);
+    return parseMiniappCategory(readMiniappHeyboxConfig(packageJson)?.category);
+}
 function resolveMiniappSdkVersion() {
     if (!version.HB_SDK_VERSION.startsWith('__HB_SDK_'))
         return version.HB_SDK_VERSION;
@@ -12764,6 +12782,7 @@ exports.parseMiniappBasicInfo = parseMiniappBasicInfo;
 exports.parseMiniappManifestJson = parseMiniappManifestJson;
 exports.prepareMiniappArtifactFiles = prepareMiniappArtifactFiles;
 exports.readMiniappBindAppIdsFromPackageJson = readMiniappBindAppIdsFromPackageJson;
+exports.readMiniappCategoryFromPackageJson = readMiniappCategoryFromPackageJson;
 exports.readMiniappPermissionsFromPackageJson = readMiniappPermissionsFromPackageJson;
 exports.readMiniappPlatformsFromPackageJson = readMiniappPlatformsFromPackageJson;
 exports.readMiniappWindowFromPackageJson = readMiniappWindowFromPackageJson;

package/dist/cli-chunks/{session-CySUtnTY.cjs → session-CKuEz-ih.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli-chunks/{skill-BN_mjQ_T.cjs → skill-oLEQS_U6.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var version = require('./version-BTkX3iYg.cjs');
+var version = require('./version-BNNxfn8M.cjs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 var childProcess = require('node:child_process');
-var index = require('./index-PKu0Zv8R.cjs');
+var index = require('./index-B_HjHK3d.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{version-BTkX3iYg.cjs → version-BNNxfn8M.cjs}

@@ -3,6 +3,6 @@
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.3-alpha.1';
+    : '0.8.3-alpha.3';
 
 exports.HB_SDK_VERSION = HB_SDK_VERSION;

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-PKu0Zv8R.cjs');
+var index = require('./cli-chunks/index-B_HjHK3d.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');