@heybox/hb-sdk 0.9.0-alpha.0 → 0.9.0-alpha.10

package/dist/miniapp-publish.esm.js

@@ -1,4 +1,11 @@
-/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+/**
+ * 校验项目配置或产物中的小程序类别。
+ *
+ * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
+ * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
+ * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ */
 function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
     if (value === undefined)
         return undefined;
@@ -2794,7 +2801,14 @@ var semverExports = requireSemver();
 
 const BASIC_INFO_MAX_BYTES = 10 * 1024 * 1024;
 const BASIC_INFO_MAX_PIXELS = 40_000_000;
-/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+/**
+ * 规范化并校验小程序展示名称。
+ *
+ * @param raw - 原始名称，必须是字符串。
+ * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
+ * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
+ * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ */
 function normalizeBasicInfoName(raw) {
     if (typeof raw !== 'string')
         throw new Error('heybox.name 必须是字符串');
@@ -2815,7 +2829,17 @@ function validateBasicInfoPath(raw) {
         throw new Error('资料图片仅支持 JPEG、PNG、GIF、WebP');
     return raw;
 }
-/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+/**
+ * 校验项目声明或 Manifest 中的小程序展示资料。
+ *
+ * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
+ * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
+ * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
+ * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
+ * @remarks
+ * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
+ * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
     if (!semverExports.valid(sdkVersion) || sdkVersion.startsWith('v') || sdkVersion.includes('+'))
@@ -3218,6 +3242,16 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
     }
     return String(version).trim();
 }
+/**
+ * 校验发布 Manifest 并返回规范化后的已知字段。
+ *
+ * @param manifest - 从构建产物读取的 Manifest，图片和 Companion 路径相对构建目录。
+ * @returns 新对象：规范化版本、名称、平台与游戏绑定，省略空绑定及未声明的可选字段；不保留未知字段。
+ * @throws `Error` 版本、平台、资料、权限、窗口、游戏绑定或生成的 Companion 声明非法，以及类别缺失时抛出。
+ * @remarks
+ * 不修改输入对象，不执行文件 I/O；不会验证图片/归档是否存在、内容摘要是否匹配，也不查询远端发布资格。
+ * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
+ */
 function validateMiniappManifestForDeploy(manifest) {
     const version = validateMiniappManifestVersion(manifest.version, 'manifest.version');
     const sdkVersion = validateSdkVersion(manifest.sdkVersion, 'manifest.sdkVersion');
@@ -3250,6 +3284,7 @@ function validateGeneratedCompanions(value) {
         return undefined;
     if (!isRecord$1(value) || Object.keys(value).length === 0)
         throw new Error('manifest.companions 必须是非空对象');
+    let descriptorCount = 0;
     for (const [alias, definition] of Object.entries(value)) {
         if (!/^[a-z][a-z0-9-]{0,31}$/.test(alias) ||
             !isRecord$1(definition) ||
@@ -3263,6 +3298,9 @@ function validateGeneratedCompanions(value) {
             Object.keys(definition.targets).length === 0)
             throw new Error(`manifest.companions.${alias} 不合法`);
         for (const [target, artifact] of Object.entries(definition.targets)) {
+            descriptorCount += 1;
+            if (descriptorCount > 64)
+                throw new Error('manifest.companions 最多允许 64 个 target 描述符');
             if (isRecord$1(artifact) && artifact.elevation === 'required') {
                 throw new Error(`manifest.companions.${alias}.targets.${target}.elevation V1 仅支持 none，暂不支持管理员权限启动`);
             }
@@ -3550,7 +3588,35 @@ function readBasicInfoImageHeader(bytes) {
 // 脚手架开发占位图；构建可用，提审前必须替换。
 const BASIC_INFO_PLACEHOLDER_SHA256 = 'd14e54b30f5e6d1bcbf51267bc82b06a0af7c333f2945bcc16b4e1adc3b123dd';
 
-/** 只消费构建目录中的字节，不生成或回写 Manifest。返回 URL 的释放由页面负责。 */
+/**
+ * 在浏览器中校验构建产物的展示资料图片，并创建预览 URL。
+ *
+ * @param manifest - 构建产物 Manifest，必须包含合法的 `sdkVersion`。
+ * @param files - 构建文件列表；`relativePath` 必须精确匹配 Manifest 中的图片路径。
+ * @returns 名称、图标 `icon_url` 和按原顺序排列的 `cover_image_urls`；允许缺失资料的历史产物返回 `undefined`。
+ * @throws `Error` 资料非法、图片缺失/为空/超过 10 MiB、格式与扩展名不符、超过 4000 万像素、
+ * icon 不是 200×200，或仍使用脚手架占位图片时拒绝；浏览器解码和摘要计算失败也会拒绝。
+ * @remarks
+ * 需要浏览器提供 `crypto.subtle`、`createImageBitmap` 和 object URL API；不生成或回写 Manifest。
+ * 失败时会释放本次已创建的 URL；成功后所有 URL 由调用方在预览结束或替换时释放。
+ * @example
+ * ```ts
+ * import { previewMiniappBasicInfo } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * const preview = await previewMiniappBasicInfo(manifest, files);
+ * if (preview) {
+ *   try {
+ *     const image = new Image();
+ *     image.src = preview.icon_url;
+ *     await image.decode();
+ *     document.body.append(image);
+ *   } finally {
+ *     // 已加载的图像可继续显示；不再需要从这些 URL 加载时释放。
+ *     [preview.icon_url, ...preview.cover_image_urls].forEach(URL.revokeObjectURL);
+ *   }
+ * }
+ * ```
+ */
 async function previewMiniappBasicInfo(manifest, files) {
     const profile = parseMiniappBasicInfo(manifest, String(manifest.sdkVersion ?? ''));
     if (!profile)
@@ -11846,6 +11912,13 @@ function parse(html, options) {
 const RUNTIME_GATE_MARKER = 'data-heybox-runtime-gate';
 const RUNTIME_GATE_STYLE_MARKER = 'data-heybox-runtime-gate-style';
 const RUNTIME_GATE_BOOTSTRAP_MARKER = 'data-heybox-runtime-gate-bootstrap';
+/**
+ * 检查 HTML 是否包含 Runtime Gate 的三个结构标记。
+ *
+ * @param html - 待检查的完整 HTML 文本，使用 HTML parser 解析。
+ * @returns Gate、隐藏样式及 bootstrap 标记均出现时返回 `true`，否则返回 `false`。
+ * @remarks 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
+ */
 function hasMiniappRuntimeGate(html) {
     const document = parse(html);
     let hasGate = false;
@@ -11937,30 +12010,13 @@ const textEncoder = new TextEncoder();
 /**
  * 将扫描到的相对路径转换为统一的 `/` 分隔形式。
  *
- * @param relativePath - 待整理的构建产物路径。TypeScript 入口声明为字符串；JavaScript 运行时会
- * 先计算 `relativePath || ''`，再通过 `String(...)` 强制转换。
- * @returns 仅统一分隔符形态的新字符串：所有 `\\` 转为 `/`，所有前导 `/` 被删除，其余连续
- * `/` 合并为一个。空字符串以及运行时传入的 `undefined`、`null`、`false`、`0`、`NaN` 等
- * falsy 值返回 `''`；truthy 非字符串按标准 `String(value)` 结果继续整理。
+ * @param relativePath - 待整理的构建产物路径。
+ * @returns 反斜杠转为 `/`、删除前导 `/`、合并连续 `/` 后的新字符串；空输入返回空字符串。
  *
  * @remarks
- * 这是面向 build/deploy 文件扫描结果的**格式 helper**，不是路径安全校验或 canonical path
- * parser。它不会 trim、URL decode、Unicode normalize、解析盘符，也不会拒绝或消解 `.` / `..`
- * segment、控制字符、Windows drive prefix 或尾随 `/`。例如 `/etc/passwd` 会变成
- * `etc/passwd`，`C:\\temp\\app.js` 会变成 `C:/temp/app.js`，`assets/../secret/` 仍保留点段
- * 和尾随 slash；调用方不能根据返回值推断原输入是安全相对路径。
- *
- * SDK 的 build/deploy 流程会把扫描路径先用本函数统一分隔符，再分别使用
- * {@link relativePathContainsNodeModulesSegment} 排除完整 `node_modules` 目录段、用
- * {@link shouldUploadDistFile} 过滤根 `manifest.json` / `.DS_Store` / source map。`hb-sdk build`
- * 随后校验大小预算；`hb-sdk remote deploy` 还会在签名和上传前通过
- * `validateUploadPaths()`、`prepareMiniappArtifactFiles()` 或
- * `validateMiniappUploadPathLengths()` 执行真正的空路径、点段、控制字符、重复和长度校验。
- * 这些步骤不能由本函数单独替代；`shouldUploadDistFile()` 也不会自行检查 `node_modules`。
- *
- * 不要把本函数与 `@heybox/hb-sdk/protocol` 的 `isMiniProgramRelativePath()` 混用：协议 guard
- * 不做转换，只接受已经规范的非空字符串，并拒绝前导/尾随 `/`、反斜杠、空 segment、`.`、
- * `..` 与控制字符；本函数则会改写部分非法形态并保留其余不安全内容。
+ * 仅整理文本格式，不做路径安全校验：保留点段、控制字符、盘符和尾随 `/`，不 trim 或 URL decode。
+ * 上传前仍需校验路径安全、唯一性与长度。协议 `isMiniProgramRelativePath()` 则只校验、不改写输入。
+ * JavaScript 非字符串输入按 `String(relativePath || '')` 转换，falsy 值回退为空串。
  *
  * @example
  * ```ts
@@ -11968,8 +12024,6 @@ const textEncoder = new TextEncoder();
  *
  * normalizeRelativePath('///dist\\assets//app.js'); // 'dist/assets/app.js'
  * normalizeRelativePath('assets/../secret///'); // 'assets/../secret/'，仍需安全校验
- * normalizeRelativePath(123 as unknown as string); // '123'，JavaScript 运行时强制转换
- * normalizeRelativePath(0 as unknown as string); // ''，falsy 值先回退为空串
  * ```
  *
  * @see {@link relativePathContainsNodeModulesSegment}
@@ -11985,40 +12039,21 @@ function normalizeRelativePath(relativePath) {
 /**
  * 判断路径中是否包含大小写不敏感的完整 `node_modules` 目录段。
  *
- * @param relativePath - 待检查的构建产物路径。函数先通过 {@link normalizeRelativePath} 把
- * 反斜杠改为 `/`、删除前导 `/` 并合并连续 `/`，再按 `/` 分段。
- * @returns 至少一个非空段大小写不敏感地等于完整 `node_modules` 时返回 `true`；空路径、
- * 空段及 `node_modules.txt`、`node_modules-old`、`@node_modules` 等相似名称返回 `false`。
+ * @param relativePath - 构建产物路径，先按 {@link normalizeRelativePath} 整理分隔符再分段比较。
+ * @returns 任意目录段大小写不敏感地等于 `node_modules` 时返回 `true`；空路径和相似名称返回 `false`。
  *
  * @remarks
- * 比较使用每个非空 segment 的 `toLowerCase() === 'node_modules'`，因此根目录或任意深度的
- * `node_modules`、`NODE_MODULES`、`Node_Modules` 都会命中。前导和重复 slash 会先被
- * `normalizeRelativePath` 整理；尾随 slash 产生的空段会被忽略。
- *
- * 这是同步、无副作用的**单一 predicate**，只回答“规范化后的文本是否包含该完整段”。它
- * 不 trim segment、不进行 URL/percent decode、Unicode normalize 或文件系统解析。例如
- * `node_modules%2Fpkg/index.js`、`%6eode_modules/pkg.js` 和 `node_modules.txt` 都不会命中；调用方
- * 不应传 URL，也不能把未命中解释为路径安全。
- *
- * 本函数不会拒绝或消解 `.` / `..`、绝对路径、Windows drive prefix、控制字符、空路径、
- * symlink、重复路径或超长路径。`assets/../node_modules/pkg.js` 仍会命中，因为点段保持原样；
- * 不含 `node_modules` 的危险路径则仍可能返回 `false`。签名或上传前必须继续执行对应的上传
- * 路径规范、唯一性和长度校验。
- *
- * SDK build/deploy 会在文件扫描后用本函数拒绝整个 `node_modules` 树，再用
- * {@link shouldUploadDistFile} 排除根 `manifest.json`、`.DS_Store` 和 source map。build 随后
- * 校验大小预算；deploy 还会执行上传路径安全、唯一性、长度与签名校验。这些步骤互不替代：`shouldUploadDistFile()` 本身不检查
- * `node_modules`，本函数也不决定普通文件是否应该上传。
+ * 只检查目录段文本，不 trim、URL decode 或解析文件系统。未命中不表示路径安全；点段仍保留。
+ * SDK 用它排除 `node_modules` 树，再用 {@link shouldUploadDistFile} 过滤其他不上传的文件；
+ * 路径安全、唯一性、长度与上传大小需分别校验。
  *
  * @example
  * ```ts
  * import { relativePathContainsNodeModulesSegment } from '@heybox/hb-sdk/miniapp-publish';
  *
  * relativePathContainsNodeModulesSegment('dist\\NODE_MODULES/pkg/index.js'); // true
- * relativePathContainsNodeModulesSegment('dist//vendor///node_modules/'); // true
  * relativePathContainsNodeModulesSegment('dist/node_modules.txt'); // false
  * relativePathContainsNodeModulesSegment('dist/node_modules%2Fpkg.js'); // false，不做 URL decode
- * relativePathContainsNodeModulesSegment('assets/../secret.js'); // false，但这不代表路径安全
  * ```
  *
  * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
@@ -12398,8 +12433,9 @@ function createMiniappArtifactFileHeader(file) {
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
  * @param localFiles - 本地构建产物 receipt；除 `relativePath` 和 `size` 外，每项必须包含 64 位小写十六进制 `sha256`。
- * @param serverFiles - 服务端签发的文件映射；数量、路径、大小和 SHA-256 必须与本地产物一一一致。
+ * @param serverFiles - 服务端签发的会话文件映射；与复用的 Companion 合起来必须覆盖本地产物。
  * @param uploadedKeys - 服务端已确认上传成功的 key；每个值都必须属于当前会话，重复值会被去重。
+ * @param reusedCompanionFiles - 已验证 Blob 引用；仅允许当前产物中的 Companion 文件。
  * @returns
  * 包含三个字段的对象：`files` 是按路径 UTF-8 字节序排列的全部 `{ file, key }` 映射，
  * `missingFiles` 是其中尚未确认上传的映射，`uploadedKeys` 是去重后的已上传 key。
@@ -12415,15 +12451,38 @@ function createMiniappArtifactFileHeader(file) {
  *     sha256: 'a'.repeat(64),
  *   }],
  *   [],
+ *   [],
  * );
  *
  * console.log(resolved.missingFiles.length); // 1
  * ```
  */
-function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
+function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys, reusedCompanionFiles) {
     const preparedFiles = prepareMiniappArtifactFiles(localFiles);
-    if (serverFiles.length !== preparedFiles.length) {
-        throw new Error(`上传会话文件数量异常：期望 ${preparedFiles.length}，实际 ${serverFiles.length}`);
+    if (serverFiles.length + reusedCompanionFiles.length !== preparedFiles.length) {
+        throw new Error(`上传会话文件数量异常：期望 ${preparedFiles.length}，实际 ${serverFiles.length + reusedCompanionFiles.length}`);
+    }
+    const localByPath = new Map(preparedFiles.map((file) => [file.relativePath, file]));
+    const reused = new Map();
+    for (const reference of reusedCompanionFiles) {
+        const relativePath = normalizeMiniappArtifactRelativePath(reference.relative_path);
+        const local = localByPath.get(relativePath);
+        if (!relativePath.startsWith('companions/') || !local) {
+            throw new Error(`上传会话返回了不属于当前 Companion 产物的 Blob 引用：${relativePath}`);
+        }
+        if (reused.has(relativePath)) {
+            throw new Error(`上传会话返回重复 Blob 引用：${relativePath}`);
+        }
+        if (!Number.isSafeInteger(reference.size) || reference.size < 0 || reference.size !== local.size) {
+            throw new Error(`上传会话 Blob 文件大小与本地构建不一致：${relativePath}`);
+        }
+        if (!('sha256' in local) || !/^[a-f0-9]{64}$/.test(reference.sha256) || reference.sha256 !== local.sha256) {
+            throw new Error(`上传会话 Blob 文件 SHA-256 与本地构建不一致：${relativePath}`);
+        }
+        if (typeof reference.blob_id !== 'string' || !reference.blob_id.trim()) {
+            throw new Error(`上传会话 Blob 引用 ID 无效：${relativePath}`);
+        }
+        reused.set(relativePath, reference);
     }
     const mappings = new Map();
     const serverSizes = new Map();
@@ -12434,6 +12493,9 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         if (mappings.has(relativePath)) {
             throw new Error(`上传会话返回重复文件路径：${relativePath}`);
         }
+        if (reused.has(relativePath)) {
+            throw new Error(`上传会话同时返回文件 key 和 Blob 引用：${relativePath}`);
+        }
         const key = String(serverFile.key || '');
         if (!key) {
             throw new Error(`上传会话未返回文件 key：${relativePath}`);
@@ -12454,7 +12516,8 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         serverHashes.set(relativePath, sha256);
         knownKeys.add(key);
     }
-    const files = preparedFiles.map((file) => {
+    const sessionFiles = preparedFiles.filter((file) => !reused.has(file.relativePath));
+    const files = sessionFiles.map((file) => {
         const key = mappings.get(file.relativePath);
         if (!key) {
             throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
@@ -12479,6 +12542,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         files,
         missingFiles: files.filter((file) => !completed.has(file.key)),
         uploadedKeys: [...completed],
+        reusedCompanionFiles: [...reused.values()],
     };
 }
 /**

package/dist/vite.cjs.js

@@ -2797,7 +2797,14 @@ var semverExports = requireSemver();
 
 const BASIC_INFO_MAX_BYTES = 10 * 1024 * 1024;
 const BASIC_INFO_MAX_PIXELS = 40_000_000;
-/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+/**
+ * 规范化并校验小程序展示名称。
+ *
+ * @param raw - 原始名称，必须是字符串。
+ * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
+ * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
+ * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ */
 function normalizeBasicInfoName(raw) {
     if (typeof raw !== 'string')
         throw new Error('heybox.name 必须是字符串');
@@ -2818,7 +2825,17 @@ function validateBasicInfoPath(raw) {
         throw new Error('资料图片仅支持 JPEG、PNG、GIF、WebP');
     return raw;
 }
-/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+/**
+ * 校验项目声明或 Manifest 中的小程序展示资料。
+ *
+ * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
+ * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
+ * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
+ * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
+ * @remarks
+ * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
+ * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
     if (!semverExports.valid(sdkVersion) || sdkVersion.startsWith('v') || sdkVersion.includes('+'))
@@ -2948,7 +2965,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.0-alpha.0';
+    : '0.9.0-alpha.10';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3350,7 +3367,14 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
-/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+/**
+ * 校验项目配置或产物中的小程序类别。
+ *
+ * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
+ * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
+ * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ */
 function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
     if (value === undefined)
         return undefined;
@@ -13339,6 +13363,7 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
  * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
  * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 展示资料缺失、名称/图片路径非法、图片无法解码或不符合大小/尺寸约束，或类别非法时抛出。
  * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
  * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
  *
@@ -13349,6 +13374,10 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
+ * - `heybox.name`、`heybox.icon`、`heybox.coverImages`：SDK `0.8.2` 起须完整提供的展示资料。
+ *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
+ *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
+ * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；

package/dist/vite.esm.js

@@ -2794,7 +2794,14 @@ var semverExports = requireSemver();
 
 const BASIC_INFO_MAX_BYTES = 10 * 1024 * 1024;
 const BASIC_INFO_MAX_PIXELS = 40_000_000;
-/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+/**
+ * 规范化并校验小程序展示名称。
+ *
+ * @param raw - 原始名称，必须是字符串。
+ * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
+ * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
+ * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ */
 function normalizeBasicInfoName(raw) {
     if (typeof raw !== 'string')
         throw new Error('heybox.name 必须是字符串');
@@ -2815,7 +2822,17 @@ function validateBasicInfoPath(raw) {
         throw new Error('资料图片仅支持 JPEG、PNG、GIF、WebP');
     return raw;
 }
-/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+/**
+ * 校验项目声明或 Manifest 中的小程序展示资料。
+ *
+ * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
+ * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
+ * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
+ * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
+ * @remarks
+ * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
+ * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ */
 function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
     sdkVersion = sdkVersion.trim();
     if (!semverExports.valid(sdkVersion) || sdkVersion.startsWith('v') || sdkVersion.includes('+'))
@@ -2945,7 +2962,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.0-alpha.0';
+    : '0.9.0-alpha.10';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3347,7 +3364,14 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
-/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+/**
+ * 校验项目配置或产物中的小程序类别。
+ *
+ * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
+ * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
+ * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ */
 function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category') {
     if (value === undefined)
         return undefined;
@@ -13336,6 +13360,7 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
  * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
  * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 展示资料缺失、名称/图片路径非法、图片无法解码或不符合大小/尺寸约束，或类别非法时抛出。
  * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
  * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
  *
@@ -13346,6 +13371,10 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
+ * - `heybox.name`、`heybox.icon`、`heybox.coverImages`：SDK `0.8.2` 起须完整提供的展示资料。
+ *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
+ *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
+ * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；

package/docs/runtime-host-migration.md

@@ -89,12 +89,14 @@ Storage 面板只通过 `runtime.diagnostics.storage?.getSnapshot()` 读取 Runt
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | Browser Dev Host       | 私有 WebSocket channel 优先，HTTP/SSE 保留为兼容路径。账号 identity 的 canonical 读取仍由 HTTP session status 完成；channel 只发 revision hint，收到 hint 后重新读取 HTTP 状态。                                                                                                                                          | WebSocket 握手、重连或消息失败不阻断 Browser Mock；回退 HTTP/SSE 并继续有界轮询。                  |
 | Mobile Release         | 当前稳定客户端继续把原生 `mini_url` launch 交给详情 H5/Native Host；二维码保持 HTTPS `open_inapp` 与 `heybox://` `openWindow`，但短链这一跳是普通 H5。跳转页打开完整 sandbox query（`mini_url`、身份、启动票和 LAN Dev Context）后延迟 `closeWindow`。真机 WebView 基址是 `http://127.0.0.1` 详情页且 HTML 来自线上缓存。 | 生成真机二维码前仍需 CLI 登录、项目绑定和有效 Dev Context；这些条件不阻断 Browser 调试台启动。     |
-| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；Runtime 权限和本地 network proxy 仅在读取成功时采用。                                                                                                                                                                                                                        | Dev Context 缺失、过期、不可达或校验失败时记录脱敏诊断，继续使用原生 Host 的账号、网络与远端权限。 |
+| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；读取成功后采用本地 network proxy，代理不参与 Runtime 权限判断。 | Dev Context 缺失、过期、不可达或校验失败时记录脱敏诊断，继续使用原生 Host 的账号、网络与远端权限。 |
 
 `DevSession` 同时携带本地声明、独立的 `local_dev_grant` 与 context revision，不会反向修改线上配置。真实 H5 必须先以启动票取得 canonical identity，再将可信线上基线与声明及严格解析的 grant 合成普通 Runtime 快照；没有有效票据或非法 grant 时不临时放权。临时授权仅允许 `network` / `companion`，不包含 `useOfficialDomain`，且每次启动由用户确认。
 
 Node 负责 CLI-owned stable context endpoint、短跳转 registry 和 Launch Reference 生命周期；H5 负责持续验证 CLI lease，不能用 iframe heartbeat 代替。连续失联约 30 秒、到期、session/revision 或 Companion 摘要变化时销毁旧 Runtime；重连重新确认和创建实例。票据字符串轮换不改变授权指纹。线上权限快照在 Runtime 内不可变，临时权限来源不传给 iframe。Android、iOS 与新 PC 原生 adapter 沿用既有 operation；真实 PC Companion 还必须有私有 local-dev lease capability，缺能力继续 fail closed。
 
+真机公开 `network.request` 使用 Dev Context 下的 `/network` 转发。代理生命周期仅由 CLI dev server 管理，不另设激活、续租、撤销、权限或授权指纹检查。代理不判断黑盒域名，不注入或剥离应用层凭据，只处理 HTTP 传输头、超时、取消和大小限制，并保留上游重定向响应。Runtime 私有请求、`network.download` 和正式版本继续使用原生 adapter。
+
 多网卡环境中，CLI 从可用私有 IPv4 网卡派生候选 `mini_url`，并优先展示与 HMR 默认地址匹配的候选。用户切换网卡后，`mini_url` 和 Dev Context URL 都投影到同一选中地址。`dev_context_url` 必须嵌套在 `heybox-mini-dev://sandbox` 的 query 中，不能误放到最外层 `openWindow` payload。
 
 ## Mobile 短跳转安全边界

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.0-alpha.0",
+  "version": "0.9.0-alpha.10",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -65,7 +65,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.0-alpha.0"
+    "@heybox/hb-sdk-protocol": "0.9.0-alpha.10"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -116,13 +116,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-sdk-runtime": "~0.9.0-alpha.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-api": "~1.28.9",
-    "@heybox/runtime": "~0.2.0",
-    "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0"
+    "@heybox/hb-api": "~1.28.10",
+    "@heybox/hb-sdk-runtime": "~0.9.0-alpha.10",
+    "@heybox/runtime": "~0.2.1",
+    "@heybox/runtime-policy": "~0.2.1",
+    "@heybox/runtime-transport-fetch": "~0.2.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.0-alpha.0+skill.aa24d6656331",
+  "skillVersion": "0.9.0-alpha.10+skill.aa24d6656331",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.0-alpha.0",
-    "compatibility": "0.9.0-alpha.0"
+    "version": "0.9.0-alpha.10",
+    "compatibility": "0.9.0-alpha.10"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.0-alpha.0",
+    "version": "0.9.0-alpha.10",
     "path": "skill"
   },
   "integrity": "sha256-aa24d6656331cbad8f6aae7735258a49d7f1a82f6e900415de53a1b93a30ddb8"

package/types/core/singleton.d.ts

@@ -205,7 +205,7 @@ export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeS
  * - `heybox_app_login_change`：`{ isHeyboxAppLoggedIn }`；
  * - `user_info_authorization_change`：
  *   [UserInfoAuthorization](/reference/symbols/root/interfaces/UserInfoAuthorization)，包含 `identity` 与
- *   `profile` 两项授权状态；
+ *   `profile` 两项授权状态，支持 Steam 账号能力时还可能包含 `steam_account`；
  * - `companion.session.output`：`{ sessionId, controllerGeneration, stream, sequence, data }`；
  * - `companion.session.exit`：`{ sessionId, exit }`；
  * - `companion.session.ownershipLost`：`{ sessionId, controllerGeneration }`。

package/types/miniapp-manifest/basic-info-browser.d.ts

@@ -1,4 +1,32 @@
-/** 只消费构建目录中的字节，不生成或回写 Manifest。返回 URL 的释放由页面负责。 */
+/**
+ * 在浏览器中校验构建产物的展示资料图片，并创建预览 URL。
+ *
+ * @param manifest - 构建产物 Manifest，必须包含合法的 `sdkVersion`。
+ * @param files - 构建文件列表；`relativePath` 必须精确匹配 Manifest 中的图片路径。
+ * @returns 名称、图标 `icon_url` 和按原顺序排列的 `cover_image_urls`；允许缺失资料的历史产物返回 `undefined`。
+ * @throws `Error` 资料非法、图片缺失/为空/超过 10 MiB、格式与扩展名不符、超过 4000 万像素、
+ * icon 不是 200×200，或仍使用脚手架占位图片时拒绝；浏览器解码和摘要计算失败也会拒绝。
+ * @remarks
+ * 需要浏览器提供 `crypto.subtle`、`createImageBitmap` 和 object URL API；不生成或回写 Manifest。
+ * 失败时会释放本次已创建的 URL；成功后所有 URL 由调用方在预览结束或替换时释放。
+ * @example
+ * ```ts
+ * import { previewMiniappBasicInfo } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * const preview = await previewMiniappBasicInfo(manifest, files);
+ * if (preview) {
+ *   try {
+ *     const image = new Image();
+ *     image.src = preview.icon_url;
+ *     await image.decode();
+ *     document.body.append(image);
+ *   } finally {
+ *     // 已加载的图像可继续显示；不再需要从这些 URL 加载时释放。
+ *     [preview.icon_url, ...preview.cover_image_urls].forEach(URL.revokeObjectURL);
+ *   }
+ * }
+ * ```
+ */
 export declare function previewMiniappBasicInfo(manifest: Record<string, unknown>, files: readonly {
     relativePath: string;
     file: Blob;

package/types/miniapp-manifest/basic-info.d.ts

@@ -1,12 +1,33 @@
 export declare const BASIC_INFO_MAX_BYTES: number;
 export declare const BASIC_INFO_MAX_PIXELS = 40000000;
+/** 小程序展示资料；项目声明和构建产物使用相同字段，图片路径的根目录不同。 */
 export interface MiniappBasicInfo {
+    /** NFKC 规范化并移除首尾 Unicode 空白后的名称，长度为 1–40 个 Unicode code point。 */
     name: string;
+    /** 图标的规范相对路径；项目声明相对项目目录，Manifest 相对构建目录。 */
     icon: string;
+    /** 1–5 个互不重复的封面相对路径，按展示顺序排列。 */
     coverImages: string[];
 }
-/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+/**
+ * 规范化并校验小程序展示名称。
+ *
+ * @param raw - 原始名称，必须是字符串。
+ * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
+ * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
+ * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ */
 export declare function normalizeBasicInfoName(raw: unknown): string;
 export declare function validateBasicInfoPath(raw: unknown): string;
-/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+/**
+ * 校验项目声明或 Manifest 中的小程序展示资料。
+ *
+ * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
+ * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
+ * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
+ * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
+ * @remarks
+ * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
+ * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ */
 export declare function parseMiniappBasicInfo(value: Record<string, unknown>, sdkVersion?: string): MiniappBasicInfo | undefined;

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

@@ -1,4 +1,11 @@
-/** 小程序发布类别；新上传版本必须声明，历史产物读取允许缺省。 */
+/** 小程序发布类别：`tool` 为工具、`game` 为游戏、`other` 为其他；新上传版本必须声明，历史读取可缺省。 */
 export type MiniappCategory = 'tool' | 'game' | 'other';
-/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+/**
+ * 校验项目配置或产物中的小程序类别。
+ *
+ * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
+ * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
+ * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ */
 export declare function parseMiniappCategory(value: unknown, sourceLabel?: string): MiniappCategory | undefined;