@heybox/hb-sdk 0.8.1-alpha.8 → 0.8.1

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-alpha.8';
+    : '0.8.1';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3116,6 +3116,35 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+function parseMiniappBindAppIds(value, options = {}) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error(`${sourceLabel} 必须是字符串数组`);
+    if (value.length > MINIAPP_BIND_APP_IDS_MAX_COUNT) {
+        throw new Error(`${sourceLabel} 最多包含 ${MINIAPP_BIND_APP_IDS_MAX_COUNT} 个游戏 appid`);
+    }
+    const seen = new Set();
+    const appIds = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !/^[1-9]\d*$/.test(item)) {
+            throw new Error(`${sourceLabel} 包含非法游戏 appid：${String(item)}`);
+        }
+        const numeric = Number(item);
+        if (!Number.isSafeInteger(numeric) || numeric > 2_147_483_647) {
+            throw new Error(`${sourceLabel} 包含超出正 int32 范围的游戏 appid：${item}`);
+        }
+        if (seen.has(item))
+            throw new Error(`${sourceLabel} 包含重复游戏 appid：${item}`);
+        seen.add(item);
+        appIds.push(item);
+    }
+    appIds.sort((left, right) => Number(left) - Number(right));
+    return Object.freeze(appIds);
+}
+
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
@@ -3281,7 +3310,7 @@ function parseMiniappPermissions(value, options) {
         }
         return { declared: false };
     }
-    if (!isRecord$2(value)) {
+    if (!isRecord$3(value)) {
         throw new Error(`${sourceLabel} 必须是 JSON 对象`);
     }
     const knownKeys = new Set(MINIAPP_PERMISSION_KEYS);
@@ -3295,7 +3324,7 @@ function parseMiniappPermissions(value, options) {
             continue;
         const declaration = value[key];
         const itemLabel = `${sourceLabel}.${key}`;
-        if (!isRecord$2(declaration))
+        if (!isRecord$3(declaration))
             throw new Error(`${itemLabel} 必须是 JSON 对象`);
         const definition = MINI_PROGRAM_PERMISSION_CATALOG.find((item) => item.key === key);
         if (!definition)
@@ -3329,11 +3358,15 @@ function requiresExplicitPermissions(sdkVersion) {
 function getMissingPermissionsWarning(sourceLabel = 'package.json#heybox.permissions') {
     return `${sourceLabel} 尚未声明。当前按 0.8 兼容行为构建；0.9.0 起将拒绝构建，请尽快补充权限声明（无权限需求时配置 {}）。`;
 }
-function isRecord$2(value) {
+function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
+/** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
+const MINIAPP_WINDOW_SIZE_MAX = 16_384;
+const MINIAPP_WINDOW_NUMBER_FIELDS = ['defaultWidth', 'defaultHeight', 'minWidth', 'minHeight'];
+const MINIAPP_WINDOW_ALLOWED_FIELDS = [...MINIAPP_WINDOW_NUMBER_FIELDS, 'resizable'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
 }
@@ -3346,12 +3379,16 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+    const window = validateMiniappWindow(manifest.window, 'manifest.window');
+    const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
         platforms,
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
+        ...(window === undefined ? {} : { window }),
+        ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3372,6 +3409,70 @@ function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
     }
     return Object.freeze(MINIAPP_PLATFORM_VALUES.filter((platform) => seen.has(platform)));
 }
+/**
+ * 校验并归一化 `package.json#heybox.window` / `manifest.window` 声明。
+ *
+ * @remarks
+ * 与 `heybox.permissions` 同样的严格风格：未知字段报错，不做静默忽略。
+ * `width` / `height` 显式给出改名提示；`x` / `y` 按未知字段显式报错（`INV-NO-DEV-POSITION`）。
+ * 未声明时返回 `undefined`，由调用方决定不写入产物。
+ * @param value - 待校验的原始声明（不可信输入）。
+ * @param sourceLabel - 报错前缀，默认指向开发者声明路径。
+ * @throws 当声明不是非空对象、含未知字段、数值/布尔类型不合法或 min/default 不配对时抛出。
+ */
+function validateMiniappWindow(value, sourceLabel = 'package.json#heybox.window') {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord$2(value) || Object.keys(value).length === 0) {
+        throw new Error(`${sourceLabel} 至少需要声明 defaultWidth/defaultHeight/minWidth/minHeight/resizable 之一`);
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'width') || Object.prototype.hasOwnProperty.call(value, 'height')) {
+        throw new Error(`${sourceLabel} 请使用 defaultWidth/defaultHeight，而不是 width/height`);
+    }
+    for (const key of Object.keys(value)) {
+        if (!MINIAPP_WINDOW_ALLOWED_FIELDS.includes(key)) {
+            throw new Error(`${sourceLabel} 包含未知字段：${key}`);
+        }
+    }
+    const window = {};
+    for (const field of MINIAPP_WINDOW_NUMBER_FIELDS) {
+        if (!Object.prototype.hasOwnProperty.call(value, field))
+            continue;
+        const size = value[field];
+        if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0) {
+            throw new Error(`${sourceLabel}.${field} 必须是正整数`);
+        }
+        if (size > MINIAPP_WINDOW_SIZE_MAX) {
+            throw new Error(`${sourceLabel}.${field} 不能大于 ${MINIAPP_WINDOW_SIZE_MAX}`);
+        }
+        window[field] = size;
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'resizable')) {
+        if (typeof value.resizable !== 'boolean') {
+            throw new Error(`${sourceLabel}.resizable 必须是 boolean`);
+        }
+        window.resizable = value.resizable;
+    }
+    for (const [minimum, fallback] of [
+        ['minWidth', 'defaultWidth'],
+        ['minHeight', 'defaultHeight'],
+    ]) {
+        const minimumValue = window[minimum];
+        if (minimumValue === undefined)
+            continue;
+        const fallbackValue = window[fallback];
+        if (fallbackValue === undefined) {
+            throw new Error(`${sourceLabel}.${minimum} 必须与 ${fallback} 同时声明`);
+        }
+        if (minimumValue > fallbackValue) {
+            throw new Error(`${sourceLabel}.${minimum} 必须小于等于 ${fallback}`);
+        }
+    }
+    return window;
+}
+function isRecord$2(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function getMiniappManifestVersionError(version) {
     if (typeof version !== 'string' || version.trim() === '') {
         return `必须是合法 SemVer：${String(version)}`;
@@ -3429,6 +3530,17 @@ function readMiniappPlatformsFromPackageJson(root) {
     const heybox = readMiniappHeyboxConfig(packageJson);
     return validateMiniappPlatforms(heybox?.platforms, 'package.json#heybox.platforms');
 }
+/**
+ * 读取并校验 `package.json#heybox.window`。
+ *
+ * @returns 合法声明；未声明时返回 `undefined`，调用方不得向 manifest 写入空对象或 `null`。
+ * @throws 当声明违反 {@link validateMiniappWindow} 的规则时抛出，报错前缀为 `package.json#heybox.window`。
+ */
+function readMiniappWindowFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return validateMiniappWindow(heybox?.window, 'package.json#heybox.window');
+}
 function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
     const { packageJson } = readMiniappPackageJson(root, false);
     const heybox = readMiniappHeyboxConfig(packageJson);
@@ -3438,6 +3550,11 @@ function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
         sdkVersion,
     });
 }
+function readMiniappBindAppIdsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return parseMiniappBindAppIds(heybox?.bindAppIds);
+}
 function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
@@ -12893,11 +13010,23 @@ const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
 const DEV_MANIFEST_PATH = '/__hb_sdk__/companion/manifest.json';
+/**
+ * 本地 PC 调试开窗时的 manifest 入口。
+ *
+ * 开窗发生在扩展拿到 `LocalDevelopmentBinding` 之前，所以不能用 Companion 会话令牌守护；
+ * 该入口改由 CLI 随本地调试启动上下文（`mini_url` query）下发的专用令牌守护，
+ * 只回最新快照，不参与 Companion 会话的 digest 钉扎。
+ */
+const DEV_MINI_PROGRAM_MANIFEST_PATH = '/__hb_sdk__/mini-program/manifest.json';
 const DEV_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
+const DEV_MINI_PROGRAM_MANIFEST_TOKEN_HEADER = 'x-hb-sdk-mini-program-manifest-token';
 const DEV_DIGEST_HEADER = 'x-hb-sdk-companion-manifest-sha256';
 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$/;
 const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+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;
 if (!devSnapshotRegistry[devSnapshotStoreKey]) {
@@ -12914,7 +13043,8 @@ function miniappManifest() {
     const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
     const deviceLogs = new DeviceLogStore();
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
-    let companionArtifactAccessToken = parseCompanionArtifactAccessToken(process.env[HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV]);
+    let companionArtifactAccessToken = parseDevAccessToken(process.env[HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV]);
+    let miniProgramManifestAccessToken = parseDevAccessToken(process.env[HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV]);
     let root = process.cwd();
     let outDir = 'dist';
     let command = 'build';
@@ -12962,8 +13092,16 @@ function miniappManifest() {
                 registerLogs();
             let store = devSnapshotStores.get(root);
             companionArtifactAccessToken ??= store?.token;
-            if (!store || store.token !== companionArtifactAccessToken) {
-                store = { token: companionArtifactAccessToken ?? '', snapshots: new Map() };
+            // 与 Companion 令牌同因：配置重载时 env 已不在，只能从同一服务的注册表恢复。
+            miniProgramManifestAccessToken ??= store?.manifestToken;
+            if (!store ||
+                store.token !== companionArtifactAccessToken ||
+                store.manifestToken !== miniProgramManifestAccessToken) {
+                store = {
+                    token: companionArtifactAccessToken ?? '',
+                    ...(miniProgramManifestAccessToken ? { manifestToken: miniProgramManifestAccessToken } : {}),
+                    snapshots: new Map(),
+                };
                 devSnapshotStores.set(root, store);
             }
             const snapshots = store.snapshots;
@@ -13068,7 +13206,8 @@ function miniappManifest() {
                     return;
                 }
                 const companionMatch = pathname?.match(DEV_COMPANION_PATH_PATTERN);
-                if (pathname !== DEV_MANIFEST_PATH && !companionMatch) {
+                const miniProgramManifest = pathname === DEV_MINI_PROGRAM_MANIFEST_PATH;
+                if (pathname !== DEV_MANIFEST_PATH && !companionMatch && !miniProgramManifest) {
                     next();
                     return;
                 }
@@ -13078,16 +13217,25 @@ function miniappManifest() {
                     response.end();
                     return;
                 }
-                if (!companionArtifactAccessToken ||
-                    !isNumericLoopbackRequest(request) ||
-                    !isNumericLoopbackHost(request.headers.host) ||
-                    !hasValidCompanionArtifactToken(request, companionArtifactAccessToken)) {
+                // 两条链路共用「仅数值 loopback」边界，凭据各自独立。
+                if (!isNumericLoopbackRequest(request) || !isNumericLoopbackHost(request.headers.host)) {
+                    response.statusCode = 403;
+                    response.end();
+                    return;
+                }
+                const authorized = miniProgramManifest
+                    ? miniProgramManifestAccessToken !== undefined &&
+                        hasValidDevToken(request, DEV_MINI_PROGRAM_MANIFEST_TOKEN_HEADER, miniProgramManifestAccessToken)
+                    : companionArtifactAccessToken !== undefined &&
+                        hasValidDevToken(request, DEV_TOKEN_HEADER, companionArtifactAccessToken);
+                if (!authorized) {
                     response.statusCode = 403;
                     response.end();
                     return;
                 }
                 try {
-                    const requestedDigest = request.headers[DEV_DIGEST_HEADER];
+                    // 本地调试入口只回最新快照；digest 钉扎仍然只服务 Companion 会话。
+                    const requestedDigest = miniProgramManifest ? undefined : request.headers[DEV_DIGEST_HEADER];
                     if (requestedDigest !== undefined && (typeof requestedDigest !== 'string' || !/^[a-f0-9]{64}$/.test(requestedDigest))) {
                         response.statusCode = 400;
                         response.end();
@@ -13099,9 +13247,15 @@ function miniappManifest() {
                         response.end();
                         return;
                     }
+                    if (miniProgramManifest && snapshot.manifestBytes.length > DEV_MINI_PROGRAM_MANIFEST_MAX_BYTES) {
+                        response.statusCode = 500;
+                        response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                        response.end(DEV_ERROR_MESSAGE);
+                        return;
+                    }
                     response.setHeader('Cache-Control', 'no-store');
                     response.setHeader('X-Content-Type-Options', 'nosniff');
-                    if (pathname === DEV_MANIFEST_PATH) {
+                    if (pathname === DEV_MANIFEST_PATH || miniProgramManifest) {
                         response.statusCode = 200;
                         response.setHeader('Content-Type', 'application/json; charset=utf-8');
                         response.setHeader('Content-Length', snapshot.manifestBytes.length);
@@ -13181,8 +13335,10 @@ function miniappManifest() {
             const sdkVersion = resolveSdkVersion();
             const platforms = readMiniappPlatformsFromPackageJson(root);
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
+            const windowDeclaration = readMiniappWindowFromPackageJson(root);
             const companionConfig = readMiniappCompanionsFromPackageJson(root);
             const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
+            const bindAppIds = readMiniappBindAppIdsFromPackageJson(root);
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());
             if (companionDeclarations && !parsedPermissions.permissions?.companion) {
@@ -13210,6 +13366,8 @@ function miniappManifest() {
                 platforms,
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
+                ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
+                ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
             }));
         },
     };
@@ -13218,6 +13376,7 @@ function prepareDevSnapshot(root, outDir, platforms, declarations, snapshotRoot,
     const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
     const sdkVersion = resolveSdkVersion();
     const permissions = readMiniappPermissionsFromPackageJson(root, sdkVersion).permissions;
+    const windowDeclaration = readMiniappWindowFromPackageJson(root);
     if (declarations && !permissions?.companion) {
         throw new Error('配置 companions 时必须声明 package.json#heybox.permissions.companion.enabled=true');
     }
@@ -13241,6 +13400,7 @@ function prepareDevSnapshot(root, outDir, platforms, declarations, snapshotRoot,
         platforms,
         ...(permissions === undefined ? {} : { permissions }),
         ...(companions === undefined ? {} : { companions }),
+        ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
     };
     return { artifacts, manifestBytes: Buffer.from(renderMiniappManifest(manifest)) };
 }
@@ -13289,11 +13449,12 @@ function isNumericLoopbackHost(host) {
     const port = Number(match[1]);
     return port >= 1 && port <= 65_535;
 }
-function parseCompanionArtifactAccessToken(value) {
+/** 两条本地调试链路共用的凭据形状：32 字节 base64url，恰好 43 个字符。 */
+function parseDevAccessToken(value) {
     return value && /^[A-Za-z0-9_-]{43}$/.test(value) ? value : undefined;
 }
-function hasValidCompanionArtifactToken(request, expected) {
-    const value = request.headers[DEV_TOKEN_HEADER];
+function hasValidDevToken(request, header, expected) {
+    const value = request.headers[header];
     const candidate = Buffer.alloc(43);
     if (typeof value === 'string')
         Buffer.from(value).copy(candidate, 0, 0, candidate.length);
@@ -13343,5 +13504,6 @@ function resolveHmrWebSocketUrl(resolved) {
 }
 
 exports.HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV;
+exports.HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV;
 exports.MINIAPP_PLATFORM_VALUES = MINIAPP_PLATFORM_VALUES;
 exports.miniappManifest = miniappManifest;