@heybox/hb-sdk 0.9.4-alpha.0 → 0.9.4-alpha.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.4-alpha.2 - 2026-10-26
+
+### 必须操作
+
+- 使用 `esbuild: false` 的生产配置需要移除该设置，保留[生产构建](https://docs.xiaoheihe.cn/hb_sdk/guide/cli#%E7%94%9F%E4%BA%A7%E6%9E%84%E5%BB%BA)的语法转换；已有小程序需升级 SDK 后重新构建、提交并发布，已上线旧包不会自动更新。
+
+### 行为调整
+
+- [miniappManifest()](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest.html) 的生产构建保留 Chrome 64 / Safari 12 语法目标，项目更保守的目标继续生效；原样复制或远端加载的脚本、运行时 API polyfill 不在转换范围内。
+
+### 问题修复
+
+- 修复部分旧 WebView 因构建产物包含现代 JavaScript 语法而无法初始化小程序的问题。
+
+## 0.9.4-alpha.1 - 2026-10-26
+
+### 行为调整
+
+- [hb-sdk build](https://docs.xiaoheihe.cn/hb_sdk/guide/cli.html#%E7%94%9F%E4%BA%A7%E6%9E%84%E5%BB%BA) 与 [hb-sdk remote deploy](https://docs.xiaoheihe.cn/hb_sdk/guide/cli.html#%E9%83%A8%E7%BD%B2%E5%8F%91%E5%B8%83) 统一拒绝含真实反斜杠的文件名、空 `node_modules` 目录及符号链接；请调整产物内容后重新构建。
+
 ## 0.9.4-alpha.0 - 2026-10-26
 
 ### 问题修复

package/README.md

@@ -6,6 +6,8 @@
 
 SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部协议、登录凭据或私有实现入口。本地浏览器调试请使用 `hb-sdk dev` 提供的 Mock 环境，发布前仍需在小黑盒 APP 中完成真机验收。
 
+生产构建的 [`miniappManifest()`](https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest.html) 将 Vite 编译脚本的 JavaScript 语法目标约束为 Chrome 64 / Safari 12，避免现代默认目标把 `??=` 等语法带入旧 WebView。项目更保守的目标会保留，`esnext`、更高版本目标和环境级配置不能抬高该下限；生产构建不允许 `esbuild: false`。原样复制或远端加载的脚本不在转换范围内，也不包含运行时 API polyfill，不能据此认定全部业务依赖已适配旧设备；已有项目需升级到包含该修复的 SDK，重新构建、提交并发布后才会更新线上产物。
+
 宿主集成边界：`@heybox/hb-sdk-runtime` 运行在 iframe 外并负责 bridge/Host Port；跨 iframe 的 wire contract 唯一维护在零依赖 `@heybox/hb-sdk-protocol`。业务页面不需要创建 Runtime、实现 Host Port 或导入协议包；客户端 SDK 只依赖已兼容 re-export 的 `@heybox/hb-sdk/protocol`。
 
 ## 快速开始

package/dist/cli-chunks/{runtime-gate-alLUP4_C.cjs → artifact-BTi9i7N4.cjs}

@@ -1,18 +1,82 @@
 'use strict';
 
+var fs = require('node:fs');
+var fs$1 = require('node:fs/promises');
+var path = require('node:path');
+var runtimePermissionEnv = require('./runtime-permission-env-Beurz19O.cjs');
+require('./version-BKjLEHsb.cjs');
+var index = require('./index-CxelQqdy.cjs');
 var node_crypto = require('node:crypto');
+require('node:zlib');
 require('node:module');
 require('node:url');
-var fs = require('node:fs');
-var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DFFgIfoX.cjs');
-var index = require('./index-Czupnh5A.cjs');
 var _commonjsDynamicModules = require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
 var require$$0$1 = require('fs');
 var require$$1 = require('path');
 var require$$0 = require('os');
 var require$$6 = require('inspector');
 
+// Shorthands
+/**
+ * Parses an HTML string.
+ *
+ * @param html Input HTML string.
+ * @param options Parsing options.
+ * @returns Document
+ *
+ * @example
+ *
+ * ```js
+ * const parse5 = require('parse5');
+ *
+ * const document = parse5.parse('<!DOCTYPE html><html><head></head><body>Hi there!</body></html>');
+ *
+ * console.log(document.childNodes[1].tagName); //> 'html'
+ *```
+ */
+function parse(html, options) {
+    return runtimePermissionEnv.Parser.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 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
+ * @since 0.8.2
+ */
+function hasMiniappRuntimeGate(html) {
+    const document = parse(html);
+    let hasGate = false;
+    let hasGateStyle = false;
+    let hasGateBootstrap = false;
+    walk(document, (element) => {
+        hasGate ||= hasAttr(element, RUNTIME_GATE_MARKER);
+        hasGateStyle ||= hasAttr(element, RUNTIME_GATE_STYLE_MARKER);
+        hasGateBootstrap ||= hasAttr(element, RUNTIME_GATE_BOOTSTRAP_MARKER);
+    });
+    return hasGate && hasGateStyle && hasGateBootstrap;
+}
+function readAttr(element, name) {
+    return element.attrs.find((attr) => attr.name.toLowerCase() === name)?.value;
+}
+function hasAttr(element, name) {
+    return readAttr(element, name) !== undefined;
+}
+function walk(node, visit) {
+    if ('tagName' in node)
+        visit(node);
+    if ('childNodes' in node)
+        for (const child of node.childNodes)
+            walk(child, visit);
+    if ('content' in node && node.content)
+        walk(node.content, visit);
+}
+
 var typescript = {exports: {}};
 
 var sourceMapSupport = {exports: {}};
@@ -201881,67 +201945,74 @@ function verifyWorkspaceCardArtifacts(root, manifest) {
     }
 }
 
-// Shorthands
-/**
- * Parses an HTML string.
- *
- * @param html Input HTML string.
- * @param options Parsing options.
- * @returns Document
- *
- * @example
- *
- * ```js
- * const parse5 = require('parse5');
- *
- * const document = parse5.parse('<!DOCTYPE html><html><head></head><body>Hi there!</body></html>');
- *
- * console.log(document.childNodes[1].tagName); //> 'html'
- *```
- */
-function parse(html, options) {
-    return runtimePermissionEnv.Parser.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 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
- * @since 0.8.2
- */
-function hasMiniappRuntimeGate(html) {
-    const document = parse(html);
-    let hasGate = false;
-    let hasGateStyle = false;
-    let hasGateBootstrap = false;
-    walk(document, (element) => {
-        hasGate ||= hasAttr(element, RUNTIME_GATE_MARKER);
-        hasGateStyle ||= hasAttr(element, RUNTIME_GATE_STYLE_MARKER);
-        hasGateBootstrap ||= hasAttr(element, RUNTIME_GATE_BOOTSTRAP_MARKER);
-    });
-    return hasGate && hasGateStyle && hasGateBootstrap;
-}
-function readAttr(element, name) {
-    return element.attrs.find((attr) => attr.name.toLowerCase() === name)?.value;
-}
-function hasAttr(element, name) {
-    return readAttr(element, name) !== undefined;
+/** 仅描述读取时刻的产物；文件没有加锁，发布仍须生成并复核 receipt。 */
+async function inspectVersionArtifact(input) {
+    const distDir = path.join(input.projectRoot, 'dist');
+    const entryHtmlPath = path.join(distDir, 'index.html');
+    const manifestPath = path.join(distDir, 'manifest.json');
+    if (!fs.existsSync(manifestPath))
+        throw new Error('未找到 dist/manifest.json，请在 Vite 配置中显式启用 miniappManifest()');
+    if (!fs.existsSync(entryHtmlPath))
+        throw new Error('未找到 dist/index.html，Vite 构建产物不完整');
+    if (!hasMiniappRuntimeGate(await fs$1.readFile(entryHtmlPath, 'utf8'))) {
+        throw new Error('dist/index.html 缺少平台 Runtime 启动门禁，请在 Vite 配置中显式启用 miniappManifest()');
+    }
+    const { manifest, hadBom } = runtimePermissionEnv.parseMiniappManifestJson(await fs$1.readFile(manifestPath, 'utf8'), 'dist/manifest.json');
+    const validated = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
+    const bindAppIds = validated.bindAppIds ?? [];
+    if (validated.workspaceCards) {
+        verifyWorkspaceCardsSnapshot({ ...validated, bindAppIds, workspaceCards: validated.workspaceCards });
+        verifyWorkspaceCardArtifacts(distDir, validated.workspaceCards);
+    }
+    const declared = input.declarations;
+    if (validated.category !== declared.category) {
+        throw new Error('dist/manifest.json.category 与 package.json#heybox.category 不一致，请重新 build');
+    }
+    if (!runtimePermissionEnv.areMiniappPlatformsEqual(validated.platforms, declared.platforms)) {
+        throw new Error('dist/manifest.json.platforms 与 package.json#heybox.platforms 不一致，请重新 build');
+    }
+    if (!runtimePermissionEnv.areMiniappWindowsEqual(validated.window, declared.window)) {
+        throw new Error('dist/manifest.json.window 与 package.json#heybox.window 不一致，请重新 build');
+    }
+    if (bindAppIds.length !== declared.bindAppIds.length || bindAppIds.some((value, index) => value !== declared.bindAppIds[index])) {
+        throw new Error('dist/manifest.json.bindAppIds 与 package.json#heybox.bindAppIds 不一致，请重新 build');
+    }
+    return {
+        distDir,
+        hadBom,
+        // 上送仍保留原始未知字段，只归一原有 deploy 已处理的字段。
+        manifest: { ...manifest, platforms: validated.platforms, ...(bindAppIds.length === 0 ? {} : { bindAppIds }) },
+        summary: { ...validated, bindAppIds },
+    };
 }
-function walk(node, visit) {
-    if ('tagName' in node)
-        visit(node);
-    if ('childNodes' in node)
-        for (const child of node.childNodes)
-            walk(child, visit);
-    if ('content' in node && node.content)
-        walk(node.content, visit);
+/** 扫描不依赖元数据对象，不能把先前校验误当作文件持续不变的凭证。 */
+async function inspectVersionArtifactFiles(distDir) {
+    const files = [];
+    await walk(distDir, '');
+    const uploadFiles = runtimePermissionEnv.prepareMiniappArtifactFiles(files.filter((file) => runtimePermissionEnv.shouldUploadDistFile(file.relativePath)));
+    const sizeError = runtimePermissionEnv.validateMiniappUploadSizeBudgets(uploadFiles);
+    if (sizeError)
+        throw new Error(sizeError);
+    return { files: uploadFiles, fileCount: uploadFiles.length, totalBytes: uploadFiles.reduce((total, file) => total + file.size, 0) };
+    async function walk(directory, prefix) {
+        for (const entry of await fs$1.readdir(directory, { withFileTypes: true })) {
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const absolutePath = path.join(directory, entry.name);
+            const info = await fs$1.lstat(absolutePath);
+            if (info.isSymbolicLink())
+                throw new Error(`dist 目录包含 symlink，拒绝处理：${relativePath}`);
+            if (relativePath.includes('\\'))
+                throw new Error(`构建产物路径不能包含反斜杠：${relativePath}`);
+            // 在进入目录前检查，因此空的禁用目录同样拒绝。
+            if (runtimePermissionEnv.relativePathContainsNodeModulesSegment(relativePath))
+                throw new Error(`dist 目录含 node_modules：${relativePath}`);
+            if (info.isDirectory())
+                await walk(absolutePath, relativePath);
+            else if (info.isFile())
+                files.push({ relativePath, absolutePath, size: info.size });
+        }
+    }
 }
 
-exports.hasMiniappRuntimeGate = hasMiniappRuntimeGate;
-exports.verifyWorkspaceCardArtifacts = verifyWorkspaceCardArtifacts;
-exports.verifyWorkspaceCardsSnapshot = verifyWorkspaceCardsSnapshot;
+exports.inspectVersionArtifact = inspectVersionArtifact;
+exports.inspectVersionArtifactFiles = inspectVersionArtifactFiles;

package/dist/cli-chunks/{build-BHfbvke-.cjs → build-CScc5bgz.cjs}

@@ -1,35 +1,32 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-alLUP4_C.cjs');
-var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DFFgIfoX.cjs');
-var index = require('./index-Czupnh5A.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Beurz19O.cjs');
+var index = require('./index-CxelQqdy.cjs');
 require('node:crypto');
+require('node:fs');
 require('node:zlib');
-var projectVite = require('./project-vite-CTWRejM4.cjs');
-require('node:module');
-require('node:url');
-require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
-require('fs');
-require('path');
-require('os');
-require('inspector');
-require('./version-BQVBVZPA.cjs');
+var artifact = require('./artifact-BTi9i7N4.cjs');
+var projectVite = require('./project-vite-DBId94T0.cjs');
+require('./version-BKjLEHsb.cjs');
 require('node:async_hooks');
+require('node:module');
 require('readline');
+require('os');
 require('tty');
 require('assert');
 require('events');
 require('stream');
 require('buffer');
 require('util');
+require('path');
+require('fs');
 require('constants');
+require('node:url');
+require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
+require('inspector');
 
-function areStringArraysEqual(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
-}
 async function runBuildCommand(_options = {}, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
@@ -89,84 +86,38 @@ function createFixedBuildOutputPlugin(projectRoot) {
     };
 }
 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');
-    if (!fs$1.existsSync(entryHtmlPath)) {
-        throw new Error('未找到 dist/index.html，Vite 构建产物不完整');
-    }
-    if (!fs$1.existsSync(manifestPath)) {
-        throw new Error('未找到 dist/manifest.json，请在 Vite 配置中显式启用 miniappManifest()');
-    }
-    const entryHtml = await fs.readFile(entryHtmlPath, 'utf8');
-    if (!runtimeGate.hasMiniappRuntimeGate(entryHtml)) {
-        throw new Error('dist/index.html 缺少平台 Runtime 启动门禁，请在 Vite 配置中显式启用 miniappManifest()');
-    }
-    const { manifest, hadBom } = runtimePermissionEnv.parseMiniappManifestJson(await fs.readFile(manifestPath, 'utf8'), 'dist/manifest.json');
-    if (hadBom) {
+    const artifact$1 = await artifact.inspectVersionArtifact({
+        projectRoot,
+        declarations: {
+            platforms: declaredPlatforms,
+            window: declaredWindow,
+            bindAppIds: declaredBindAppIds,
+            category: declaredCategory,
+        },
+    });
+    if (artifact$1.hadBom)
         logger.warn('dist/manifest.json 包含 BOM，已自动剥离');
+    let inventory;
+    try {
+        inventory = await artifact.inspectVersionArtifactFiles(artifact$1.distDir);
     }
-    const validated = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
-    if (validated.workspaceCards) {
-        runtimeGate.verifyWorkspaceCardsSnapshot({ ...validated, bindAppIds: validated.bindAppIds ?? [], workspaceCards: validated.workspaceCards });
-        runtimeGate.verifyWorkspaceCardArtifacts(distDir, validated.workspaceCards);
-    }
-    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');
-    }
-    if (!runtimePermissionEnv.areMiniappWindowsEqual(window, declaredWindow)) {
-        throw new Error('dist/manifest.json.window 与 package.json#heybox.window 不一致，请重新 build');
-    }
-    if (!areStringArraysEqual(bindAppIds, declaredBindAppIds)) {
-        throw new Error('dist/manifest.json.bindAppIds 与 package.json#heybox.bindAppIds 不一致，请重新 build');
-    }
-    const allFiles = await walkDistFiles(distDir);
-    const uploadFiles = allFiles.filter((file) => runtimePermissionEnv.shouldUploadDistFile(file.relativePath));
-    const sizeError = runtimePermissionEnv.validateMiniappUploadSizeBudgets(uploadFiles);
-    if (sizeError) {
-        throw new Error(sizeError.replace('重新 deploy', '重新 build'));
+    catch (error) {
+        if (error instanceof Error)
+            error.message = error.message.replace('重新 deploy', '重新 build');
+        throw error;
     }
+    const { platforms, sdkVersion, version, permissions, bindAppIds } = artifact$1.summary;
     return {
-        distDir,
+        distDir: artifact$1.distDir,
         bindAppIds,
-        fileCount: uploadFiles.length,
+        fileCount: inventory.fileCount,
         sdkVersion,
         platforms,
         ...(permissions === undefined ? {} : { permissions }),
-        totalBytes: uploadFiles.reduce((total, file) => total + file.size, 0),
+        totalBytes: inventory.totalBytes,
         version,
     };
 }
-async function walkDistFiles(distDir) {
-    const results = [];
-    await walk(distDir, '');
-    return results;
-    async function walk(absDir, relDir) {
-        const entries = await fs.readdir(absDir, { withFileTypes: true });
-        for (const entry of entries) {
-            const absPath = path.join(absDir, entry.name);
-            const relPath = runtimePermissionEnv.normalizeRelativePath(relDir ? `${relDir}/${entry.name}` : entry.name);
-            const link = await fs.lstat(absPath);
-            if (link.isSymbolicLink()) {
-                throw new Error(`dist 目录包含 symlink，拒绝处理：${relPath}`);
-            }
-            if (runtimePermissionEnv.relativePathContainsNodeModulesSegment(relPath)) {
-                throw new Error(`dist 目录含 node_modules：${relPath}`);
-            }
-            if (entry.isDirectory()) {
-                await walk(absPath, relPath);
-            }
-            else if (entry.isFile()) {
-                results.push({ relativePath: relPath, size: (await fs.stat(absPath)).size });
-            }
-        }
-    }
-}
 function formatSize(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;

package/dist/cli-chunks/{create-B-KOcThY.cjs → create-BybyVKxB.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-Czupnh5A.cjs');
+var index = require('./index-CxelQqdy.cjs');
 require('node:module');
 require('readline');
 require('os');

package/dist/cli-chunks/{deploy-lock-DY7E8TFw.cjs → deploy-lock-CtJXBtKK.cjs}

@@ -3,7 +3,7 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var index = require('./index-Czupnh5A.cjs');
+var index = require('./index-CxelQqdy.cjs');
 
 const DEPLOY_LOCKED_MESSAGE = '当前设备已有同版本产物正在上传，请等待完成后重试';
 const DEPLOY_LOCK_DIRECTORY_NAME = 'deploy-locks';