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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.13",
+  "version": "0.8.1-alpha.14",
   "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.14"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -115,10 +115,10 @@
     "vitest": "^3.2.4",
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.14",
     "@heybox/hb-api": "~1.28.3",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.13",
-    "@heybox/runtime-policy": "~0.2.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
 
@@ -95,6 +96,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

@@ -302,9 +302,9 @@ 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 |
+| 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=7356ab1376630f8bed1028cf9fca72895fc3a1603b8742280c265c53fdeff423 -->
 
 ## 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.14`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`

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.14+skill.63b05480eba4",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.13",
-    "compatibility": "0.8.1-alpha.13"
+    "version": "0.8.1-alpha.14",
+    "compatibility": "0.8.1-alpha.14"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.1-alpha.13",
+    "version": "0.8.1-alpha.14",
     "path": "skill"
   },
-  "integrity": "sha256-3784ce3da8431dd675160a5c2a66e19d08f5210d3765a2cddcadee6e3dfa2a38"
+  "integrity": "sha256-63b05480eba4af0e9aeb126196230250ec8349fa1d84e84ebac8005fabe3a602"
 }

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,12 @@ 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 resolveMiniappSdkVersion(): string;

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

@@ -3,6 +3,27 @@ import type { MiniappCompanionManifestDeclarations } from './companion-types';
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
 export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
 export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
+/** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
+export declare const MINIAPP_WINDOW_SIZE_MAX = 16384;
+/**
+ * `package.json#heybox.window` 的开发者声明字段。
+ *
+ * @remarks
+ * 只描述**开窗初值**与可缩放性，不是窗口当前尺寸；运行期尺寸请用 `viewport.getWindowInfo()`。
+ * 位置（`x` / `y`）不开放声明，由用户拖拽产生并由宿主记忆。
+ */
+export interface MiniappWindowDeclaration {
+    /** 默认窗口内容宽度（逻辑像素），正整数，不超过 16384。 */
+    defaultWidth?: number;
+    /** 默认窗口内容高度（逻辑像素），正整数，不超过 16384。 */
+    defaultHeight?: number;
+    /** 尺寸下限宽度；必须与 defaultWidth 同时声明，且不大于 defaultWidth。 */
+    minWidth?: number;
+    /** 尺寸下限高度；必须与 defaultHeight 同时声明，且不大于 defaultHeight。 */
+    minHeight?: number;
+    /** 是否允许用户手动拖拽改变尺寸。 */
+    resizable?: boolean;
+}
 /**
  * 桌面平台子集：从唯一平台词表 `MINIAPP_PLATFORM_VALUES` 派生，`satisfies` 阻止它漂移出词表。
  * 小程序声明其中任一平台，即视为该项目承诺适配 PC / 桌面端；调试台据此取舍桌面调试入口。
@@ -19,6 +40,7 @@ export interface MiniappManifest {
     platforms: readonly MiniappPlatform[];
     permissions?: MiniappPermissionDeclarations;
     companions?: MiniappCompanionManifestDeclarations;
+    window?: MiniappWindowDeclaration;
 }
 export interface ParseMiniappManifestResult {
     manifest: MiniappManifest;
@@ -30,6 +52,7 @@ export declare function validateMiniappManifestVersion(version: unknown, sourceL
 export declare function renderMiniappManifest(manifest: MiniappManifest): string;
 export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
+    window?: MiniappWindowDeclaration | undefined;
     companions?: MiniappCompanionManifestDeclarations | undefined;
     permissions?: Partial<Record<"userInfo" | "steamLibrary" | "share" | "storage" | "filesystem" | "clipboard" | "leaderboard" | "companion", import("./permissions").SimpleMiniappPermissionDeclaration> & {
         network: import("./permissions").NetworkMiniappPermissionDeclaration;
@@ -40,4 +63,18 @@ export declare function validateMiniappManifestForDeploy(manifest: MiniappManife
 };
 export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
 export declare function areMiniappPlatformsEqual(left: readonly MiniappPlatform[], right: readonly MiniappPlatform[]): boolean;
+/**
+ * 校验并归一化 `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 不配对时抛出。
+ */
+export declare function validateMiniappWindow(value: unknown, sourceLabel?: string): MiniappWindowDeclaration | undefined;
+/** 比较两份窗口声明是否逐字段一致；未声明视同 `undefined`。 */
+export declare function areMiniappWindowsEqual(left: MiniappWindowDeclaration | undefined, right: MiniappWindowDeclaration | undefined): boolean;
 export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/vite/index.d.ts

@@ -50,4 +50,5 @@ export interface MiniappManifestResolvedConfig {
 export { MINIAPP_PLATFORM_VALUES };
 export type { MiniappPlatform };
 export declare const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = "HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN";
+export declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN";
 export declare function miniappManifest(): MiniappManifestPlugin;