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

package/dist/vite.esm.js

@@ -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.15';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -3113,6 +3113,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';
@@ -3278,7 +3307,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 +3321,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 +3355,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 +3376,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`;
 }
@@ -3369,6 +3406,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 +3527,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);
@@ -3435,6 +3547,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;
@@ -12890,11 +13007,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 +13040,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 +13089,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 +13203,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 +13214,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 +13244,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,8 +13332,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) {
@@ -13207,6 +13363,8 @@ function miniappManifest() {
                 platforms,
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
                 ...(companions === undefined ? {} : { companions }),
+                ...(windowDeclaration === undefined ? {} : { window: windowDeclaration }),
+                ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
             }));
         },
     };
@@ -13215,6 +13373,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 +13397,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 +13446,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 +13500,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.13",
+  "version": "0.8.1-alpha.15",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.1-alpha.13"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.15"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -114,11 +114,11 @@
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/hb-api": "~1.28.3",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.13",
-    "@heybox/runtime-policy": "~0.2.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.15",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/runtime": "~0.2.0",
+    "@heybox/runtime-policy": "~0.2.0",
     "@heybox/runtime-transport-fetch": "~0.2.0"
   },
   "publishConfig": {

package/skill/SKILL.md

@@ -56,6 +56,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 15. Use `companion.prepare()` and `companion.launch()` only from separate trusted user actions. Launch does not prepare implicitly. Treat stdio as raw `Uint8Array` with at-least-once output delivery, and implement business framing and sequence de-duplication explicitly.
 16. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
 17. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
+18. Declare window defaults only through `package.json#heybox.window` (`defaultWidth` / `defaultHeight` / `minWidth` / `minHeight` / `resizable`). `resizable` constrains user dragging only; `minWidth` / `minHeight` are the dragging lower bounds. Position is not open to developers.
 
 ## Step 5: Use CLI workflows
 
@@ -65,20 +66,21 @@ Apply these instructions when writing, reviewing, or debugging code that consume
    For real PC Companion debugging, configure local artifacts in `package.json#heybox.companions`, keep `miniappManifest()` enabled, bind the project, and ensure COA has approved `companion`. `hb-sdk dev` validates immutable snapshots without requiring an upload; config or artifact changes rotate the snapshot while existing Sessions retain their original artifact. Prepare and launch the new artifact explicitly. Check separate Browser, Mobile and PC Companion readiness in the debugging workbench. Without a local declaration, use Browser Fake only for state/UI integration.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
 5. Declare the actual supported platforms in `package.json#heybox.platforms` and keep the no-argument `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the declaration, Manifest, or Runtime gate output is missing or inconsistent.
-6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
-7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
-8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
-9. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
-10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
-11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
-12. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
-14. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
-15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
-16. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
-17. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
-18. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
-19. Do not print or expose cookies, tokens, private headers, or other credentials.
+6. When a released version should be discoverable from specific PC game workspaces, declare canonical decimal string appids in `package.json#heybox.bindAppIds` (maximum 20). This is version metadata, not a Runtime permission. Missing or empty clears bindings; `--from-version` inherits the source artifact snapshot.
+7. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
+8. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
+9. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
+10. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
+11. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
+12. Use `hb-sdk remote info` to compare local/current/added/removed game bindings, and use `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management. These commands do not edit game bindings.
+13. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
+14. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
+15. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
+16. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
+17. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
+18. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
+19. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
+20. Do not print or expose cookies, tokens, private headers, or other credentials.
 
 ## Step 6: Preserve capability boundaries
 
@@ -95,6 +97,7 @@ For workshop mini-program business code:
 9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
 10. Do not pass executable paths, dynamic args, cwd, environment variables, shell commands, URLs, hashes, PID, or native handles through `companion`; reviewed Manifest declarations are the only launch source.
 11. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
+12. Do not declare or set window position through the SDK. `package.json#heybox.window` rejects `x` / `y` and `width` / `height`. Position comes from user dragging and is remembered locally by the Host.
 
 For CLI and local development:
 

package/skill/references/api-protocol.md

@@ -301,10 +301,10 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | --- | ---: | ---: | ---: | ---: | ---: |
 | Root API | 2 | 4 | 75 | 73 | 3 |
 | Protocol API | 0 | 13 | 58 | 90 | 47 |
-| Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
-| Vite API | 0 | 1 | 5 | 1 | 2 |
+| Miniapp Publish API | 0 | 6 | 3 | 0 | 0 |
+| Vite API | 0 | 1 | 5 | 1 | 3 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=a80eea1bb8b0d64255afcb4a664911f025aeae33f3f766c9b126f55668400178 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=1dfd4c6306e8ac3680f60db083aa048395e38ffb49c30e19b49cc5db72249533 -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -27,7 +27,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1-alpha.13`
+- Version at generation time: `0.8.1-alpha.15`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -328,6 +328,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
+`hb-sdk remote info` 会只读展示 `package.json#heybox.bindAppIds`、当前线上绑定以及新增/移除差异。修改绑定必须更新项目配置并重新提交版本；CLI、Open 和 COA 都不提供第二个写入入口。普通 deploy 在上传文件前把实际构建 Manifest 交给服务端预检；`--from-version` 只使用源版本快照。
+
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
 推荐由项目的 `scripts.build` 保留类型检查：

package/skill/references/cli.md

@@ -172,6 +172,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
+`hb-sdk remote info` 会只读展示 `package.json#heybox.bindAppIds`、当前线上绑定以及新增/移除差异。修改绑定必须更新项目配置并重新提交版本；CLI、Open 和 COA 都不提供第二个写入入口。普通 deploy 在上传文件前把实际构建 Manifest 交给服务端预检；`--from-version` 只使用源版本快照。
+
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
 推荐由项目的 `scripts.build` 保留类型检查：

package/skill/references/safety-boundaries.md

@@ -42,6 +42,8 @@
 - Companion stdio 是原始 `Uint8Array` 且输出为 at-least-once 投递；业务自行定义 framing、去重、重放与恢复。
 - Browser Dev Host 的 Companion Fake 只用于状态和 UI 开发，不能作为桌面程序可执行、签名、权限或进程监管的真机证据。
 - 本地真 PC Companion 需要 `package.json#heybox.companions`、本地产物、已绑定项目和 COA `companion` 批准；未配置本地产物时使用 Browser Fake。配置或产物更新后校验并切换不可变快照；已有进程保留原产物，新产物须重新准备与启动。
+- `package.json#heybox.window` 只声明开窗初值与可缩放性；`resizable` 只约束用户拖拽。
+- 窗口位置不开放：开发者不能声明、也不能设置位置；位置由用户拖拽并由宿主按小程序身份本地记忆。
 
 私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
 Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.1-alpha.13+skill.3784ce3da843",
+  "skillVersion": "0.8.1-alpha.15+skill.b220fbc77b56",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.13",
-    "compatibility": "0.8.1-alpha.13"
+    "version": "0.8.1-alpha.15",
+    "compatibility": "0.8.1-alpha.15"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.13",
+    "version": "0.8.1-alpha.15",
     "path": "skill"
   },
-  "integrity": "sha256-3784ce3da8431dd675160a5c2a66e19d08f5210d3765a2cddcadee6e3dfa2a38"
+  "integrity": "sha256-b220fbc77b56021c0620c086c036ceba404be7a49741ffffb8bee9fce57706a7"
 }

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

@@ -0,0 +1,5 @@
+export declare const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+export interface ParseMiniappBindAppIdsOptions {
+    sourceLabel?: string;
+}
+export declare function parseMiniappBindAppIds(value: unknown, options?: ParseMiniappBindAppIdsOptions): readonly string[];

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

@@ -3,3 +3,4 @@ export * from './node';
 export * from './permissions';
 export * from './companions';
 export * from './companion-types';
+export * from './bindings';

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

@@ -1,6 +1,6 @@
 import { type ParsedMiniappPermissions } from './permissions';
 import type { MiniappCompanionAuthoringDeclarations } from './companion-types';
-import type { MiniappPlatform } from './schema';
+import type { MiniappPlatform, MiniappWindowDeclaration } from './schema';
 export declare function readMiniappVersionFromPackageJson(root: string): string;
 /** Companion source 始终相对声明所在 package.json，而非 Vite 的 HTML root。 */
 export declare function readMiniappCompanionsFromPackageJson(root: string): {
@@ -9,5 +9,13 @@ export declare function readMiniappCompanionsFromPackageJson(root: string): {
     packageJsonPath: string;
 };
 export declare function readMiniappPlatformsFromPackageJson(root: string): readonly MiniappPlatform[];
+/**
+ * 读取并校验 `package.json#heybox.window`。
+ *
+ * @returns 合法声明；未声明时返回 `undefined`，调用方不得向 manifest 写入空对象或 `null`。
+ * @throws 当声明违反 {@link validateMiniappWindow} 的规则时抛出，报错前缀为 `package.json#heybox.window`。
+ */
+export declare function readMiniappWindowFromPackageJson(root: string): MiniappWindowDeclaration | undefined;
 export declare function readMiniappPermissionsFromPackageJson(root: string, sdkVersion: string): ParsedMiniappPermissions;
+export declare function readMiniappBindAppIdsFromPackageJson(root: string): readonly string[];
 export declare function resolveMiniappSdkVersion(): string;