npm - @heybox/hb-sdk - Versions diffs - 0.8.1-alpha.13 → 0.8.1-alpha.14 - Mend

@heybox/hb-sdk 0.8.1-alpha.13 → 0.8.1-alpha.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/dist/devtools/browser-dev-host/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-DoPg_zh_.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-DZ_umnQp.js">
+    <script type="module" crossorigin src="/assets/index-mfGqyKpq.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-C1GHFN_L.js">
     <link rel="stylesheet" crossorigin href="/assets/index-DXd5IZBz.css">
   </head>
   <body>

package/dist/index.cjs.js CHANGED Viewed

@@ -835,7 +835,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.13';
+    : '0.8.1-alpha.14';
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/index.esm.js CHANGED Viewed

@@ -831,7 +831,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.13';
+    : '0.8.1-alpha.14';
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);

package/dist/vite.cjs.js CHANGED Viewed

@@ -11,7 +11,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.13';
+    : '0.8.1-alpha.14';
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3281,7 +3281,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 +3295,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 +3329,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 +3350,14 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+    const window = validateMiniappWindow(manifest.window, 'manifest.window');
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
         platforms,
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
+        ...(window === undefined ? {} : { window }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3372,6 +3378,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 +3499,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);
@@ -12893,11 +12974,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 +13007,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 +13056,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 +13170,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 +13181,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 +13211,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,6 +13299,7 @@ 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;
             if (!parsedPermissions.declared)
@@ -13210,6 +13329,7 @@ function miniappManifest() {
                 platforms,
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
+                ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
             }));
         },
     };
@@ -13218,6 +13338,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 +13362,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 +13411,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 +13466,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;

package/dist/vite.esm.js CHANGED Viewed

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.1-alpha.13';
+    : '0.8.1-alpha.14';
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3278,7 +3278,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);
@@ -3292,7 +3292,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)
@@ -3326,11 +3326,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');
 }
@@ -3343,12 +3347,14 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
+    const window = validateMiniappWindow(manifest.window, 'manifest.window');
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
         platforms,
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
+        ...(window === undefined ? {} : { window }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3369,6 +3375,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)}`;
@@ -3426,6 +3496,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);
@@ -12890,11 +12971,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]) {
@@ -12911,7 +13004,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';
@@ -12959,8 +13053,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;
@@ -13065,7 +13167,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;
                 }
@@ -13075,16 +13178,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();
@@ -13096,9 +13208,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);
@@ -13178,6 +13296,7 @@ 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;
             if (!parsedPermissions.declared)
@@ -13207,6 +13326,7 @@ function miniappManifest() {
                 platforms,
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
+                ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
             }));
         },
     };
@@ -13215,6 +13335,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');
     }
@@ -13238,6 +13359,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)) };
 }
@@ -13286,11 +13408,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);
@@ -13339,4 +13462,4 @@ function resolveHmrWebSocketUrl(resolved) {
     return `${protocol}://${host}${port ? `:${port}` : ''}`;
 }
-export { HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV, MINIAPP_PLATFORM_VALUES, miniappManifest };
+export { HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV, HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV, MINIAPP_PLATFORM_VALUES, miniappManifest };