@heybox/hb-sdk 0.9.1-alpha.4 → 0.9.1-alpha.6

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

@@ -1,63 +0,0 @@
-export declare const MINIAPP_COMPANION_TARGETS: readonly ["windows-x64", "macos-arm64"];
-export declare const MINIAPP_COMPANION_CAPABILITIES: readonly ["stdio", "attachments", "notifications"];
-/** Companion 二进制目标：Windows x64 或 macOS arm64；不是小程序的通用平台列表。 */
-export type MiniappCompanionTarget = (typeof MINIAPP_COMPANION_TARGETS)[number];
-/**
- * Companion 声明的能力标识：`stdio` 为标准输入输出、`attachments` 为受管附件、`notifications` 为通知。
- * 声明不代表当前宿主可用；实际能力以启动后 Session 返回的 capability 集合为准。
- */
-export type MiniappCompanionCapability = (typeof MINIAPP_COMPANION_CAPABILITIES)[number];
-export interface MiniappCompanionAuthoringTarget {
-    /** 相对 package.json 所在目录的产物目录；SDK 在调试和构建时自动打包。 */
-    source: string;
-    entrypoint: {
-        kind: 'executable' | 'app-bundle';
-        path: string;
-    };
-    /** V1 仅支持普通权限启动；省略时等同于 `none`。 */
-    elevation?: 'none';
-    args?: readonly string[];
-}
-export interface MiniappCompanionAuthoringDefinition {
-    displayName: string;
-    capabilities?: readonly MiniappCompanionCapability[];
-    targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionAuthoringTarget>>;
-}
-export type MiniappCompanionAuthoringDeclarations = Record<string, MiniappCompanionAuthoringDefinition>;
-/** 构建生成的单个 Companion ZIP 归档描述；不使用项目声明中的 source 目录。 */
-export interface MiniappCompanionManifestTarget {
-    /** 相对构建目录的 ZIP 路径，固定为 `companions/{alias}/{target}.zip`。 */
-    path: string;
-    /** ZIP 文件完整字节数，必须为正安全整数；不是解压后的大小。 */
-    size: number;
-    /** ZIP 完整字节的 SHA-256，使用 64 位小写十六进制字符串。 */
-    sha256: string;
-    /** 解压归档中的启动入口，由构建时从项目声明校验并保留。 */
-    entrypoint: {
-        /** 普通可执行文件或 macOS `.app` bundle；Windows 仅支持 executable。 */
-        kind: 'executable' | 'app-bundle';
-        /** 相对归档根目录的入口路径，使用 `/` 分隔；不是 ZIP 路径或项目 source 路径。 */
-        path: string;
-    };
-    /** V1 固定为普通权限启动，不支持请求管理员权限。 */
-    elevation: 'none';
-    /** 启动参数列表；最多 64 项，每项 1024 UTF-8 bytes，总计 16 KiB，不允许 NUL、CR 或 LF。 */
-    args: string[];
-}
-/** 一个 Companion alias 对应的展示信息、声明能力与平台归档。 */
-export interface MiniappCompanionManifestDefinition {
-    /** 非空展示名称，最多 120 个 Unicode code point。 */
-    displayName: string;
-    /** 无重复的声明能力列表，可为空；不表示平台批准或宿主已提供这些能力。 */
-    capabilities: MiniappCompanionCapability[];
-    /** 按二进制目标索引的已生成归档，至少提供一个目标。 */
-    targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionManifestTarget>>;
-}
-/**
- * 发布 Manifest 的 Companion 声明，键为以小写字母开头、长度 1–32 的小写字母/数字/连字符 alias。
- *
- * @remarks
- * 声明时对象必须非空，所有 alias 合计最多 64 个 target 描述符。归档由构建插件生成，
- * 不应把含 source 目录的项目配置直接当作此类型；运行时还需声明 companion 权限并获得平台批准。
- */
-export type MiniappCompanionManifestDeclarations = Record<string, MiniappCompanionManifestDefinition>;

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

@@ -1,17 +0,0 @@
-import { type MiniappCompanionAuthoringDeclarations, type MiniappCompanionManifestDeclarations, type MiniappCompanionTarget } from './companion-types';
-export * from './companion-types';
-interface PrepareMiniappCompanionsOptions {
-    root: string;
-    outputRoot: string;
-    platforms?: readonly string[];
-    /** 本地调试仅准备当前 PC 目标；构建省略此项，校验全部目标。 */
-    targets?: readonly MiniappCompanionTarget[];
-    copyArtifacts?: boolean;
-    onPreparedArtifact?: (artifact: {
-        archive: Buffer;
-        path: string;
-        size: number;
-        sourcePath: string;
-    }) => void;
-}
-export declare function prepareMiniappCompanions(declarations: MiniappCompanionAuthoringDeclarations | undefined, options: PrepareMiniappCompanionsOptions): MiniappCompanionManifestDeclarations | undefined;

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

@@ -1,7 +0,0 @@
-export * from './schema';
-export * from './category';
-export * from './node';
-export * from './permissions';
-export * from './companions';
-export * from './companion-types';
-export * from './bindings';

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

@@ -1,22 +0,0 @@
-import { type ParsedMiniappPermissions } from './permissions';
-import type { MiniappCompanionAuthoringDeclarations } from './companion-types';
-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): {
-    declarations: MiniappCompanionAuthoringDeclarations | undefined;
-    projectRoot: 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 readMiniappCategoryFromPackageJson(root: string): import("./category").MiniappCategory | undefined;
-export declare function resolveMiniappSdkVersion(): string;

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

@@ -1,48 +0,0 @@
-import { type MiniProgramPermissionKey, type MiniProgramRuntimePermissionsSnapshot } from '@heybox/hb-sdk-protocol';
-export declare const MINIAPP_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion", "appProtocol"];
-export type MiniappPermissionKey = MiniProgramPermissionKey;
-/** 构建产物中一个已启用的权限声明；未启用的项目配置项会在构建时被省略。 */
-export interface SimpleMiniappPermissionDeclaration {
-    /** 固定为 true，表示应用请求使用该权限；不等同于平台已经批准。 */
-    enabled: true;
-}
-/** 构建产物中的网络权限声明，附带是否请求小黑盒官方域名访问的配置。 */
-export interface NetworkMiniappPermissionDeclaration extends SimpleMiniappPermissionDeclaration {
-    /** 是否申请官方域名访问，项目省略时规范化为 false；实际启用还需远端批准该配置。 */
-    useOfficialDomain: boolean;
-}
-/**
- * 构建规范化后写入 Manifest 的权限对象；仅包含请求启用的权限，空对象表示无权限需求。
- *
- * @remarks
- * 这是本地声明，不是运行时授权结果。仅需声明的权限按声明生效；要求平台批准的权限还需与远端批准
- * 求交，network 的 useOfficialDomain 配置也需同时获批。显式声明中缺失某权限表示不请求该权限；
- * SDK 0.9 系列起项目必须提供该对象，0.8 历史产物未声明时另按迁移规则处理。
- */
-export type MiniappPermissionDeclarations = Partial<Record<Exclude<MiniappPermissionKey, 'network'>, SimpleMiniappPermissionDeclaration> & {
-    network: NetworkMiniappPermissionDeclaration;
-}>;
-export interface ParsedMiniappPermissions {
-    declared: boolean;
-    permissions?: MiniappPermissionDeclarations;
-}
-export interface MiniappPermissionView {
-    key: MiniappPermissionKey;
-    access: 'declaration' | 'platform-approval';
-    declared: boolean;
-    approved: boolean | null;
-    requestedConfig?: Record<string, boolean>;
-    approvedConfig?: Record<string, boolean>;
-    effective: boolean;
-    effectiveConfig?: Record<string, boolean>;
-}
-export declare function parseMiniappPermissions(value: unknown, options: {
-    present: boolean;
-    sdkVersion: string;
-    sourceLabel?: string;
-}): ParsedMiniappPermissions;
-export declare function requiresExplicitPermissions(sdkVersion: string): boolean;
-export declare function composeMiniappRuntimePermissions(local: ParsedMiniappPermissions, approvals: unknown): {
-    runtimePermissions: MiniProgramRuntimePermissionsSnapshot;
-    views: MiniappPermissionView[];
-};

package/types/miniapp-manifest/runtime-gate.d.ts

@@ -1,12 +0,0 @@
-import { type DefaultTreeAdapterMap } from 'parse5';
-type HtmlDocument = DefaultTreeAdapterMap['document'];
-export declare function injectMiniappRuntimeGate(document: HtmlDocument): void;
-/**
- * 检查 HTML 是否包含 Runtime Gate 的三个结构标记。
- *
- * @param html - 待检查的完整 HTML 文本，使用 HTML parser 解析。
- * @returns Gate、隐藏样式及 bootstrap 标记均出现时返回 `true`，否则返回 `false`。
- * @remarks 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
- */
-export declare function hasMiniappRuntimeGate(html: string): boolean;
-export {};

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

@@ -1,302 +0,0 @@
-import { type MiniappCategory } from './category';
-import { type MiniappPermissionDeclarations } from './permissions';
-import type { MiniappCompanionManifestDeclarations } from './companion-types';
-export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
-/**
- * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
- *
- * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
- */
-export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
-/** `package.json#heybox.platforms` 中单个平台标识。 */
-export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
-/** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
-export declare const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = "0.9.0";
-/**
- * 历史兜底平台集合。
- *
- * @remarks
- * 仅在 `sdkVersion` 缺失或 SemVer precedence 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`，
- * 且 Manifest 完全没有 `platforms` 字段时生效，不是任何非法声明的兜底。
- *
- * 不含 `linux`：客户端暂无 linux 基线，后端 `x_os_type` 也不映射该平台，声明了也进不了运行门禁。
- */
-export declare const MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos"];
-/**
- * 历史兜底平台集合的旧名称。
- *
- * @deprecated Since 0.8.3. 请改用 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}，本别名取值与之一致，仅为不破坏既有 import 保留。
- */
-export declare const MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos"];
-/** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 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 / 桌面端；调试台据此取舍桌面调试入口。
- *
- * 注意：子集只表达「声明为桌面」，不保证已有可用的客户端基线——例如 `linux` 目前既没有 `@hbPlatform` 声明，
- * 也没有 Companion target，仅声明 `linux` 的项目会展示入口但未必能真正打开。
- */
-export declare const MINIAPP_DESKTOP_PLATFORM_VALUES: readonly ["windows", "macos", "linux"];
-export declare function hasMiniappDesktopPlatform(platforms: readonly MiniappPlatform[] | undefined): boolean;
-/**
- * 判断平台声明是否仍是旧版模板的移动端默认值。
- *
- * @param platforms - 待判断的平台数组；不要求预先规范化顺序，重复项会被长度校验挡下。
- * @returns 恰好包含 `android`、`ios`、`ohos` 三个平台时返回 `true`，其余组合返回 `false`。
- */
-export declare function isLegacyMobileTemplatePlatforms(platforms: readonly MiniappPlatform[]): boolean;
-/**
- * 生成「平台声明仍是旧模板移动端默认」的非阻断提示。
- *
- * @param sourceLabel - 提示前缀，默认指向开发者声明路径。
- * @returns 面向开发者的单行提示；调用方负责经 Vite 插件 `warn` 或等价日志通道输出，不得据此阻断构建。
- */
-export declare function getLegacyMobileTemplatePlatformsNotice(sourceLabel?: string): string;
-/** 构建生成的小程序发布 Manifest；可选字段用于兼容历史产物，发布前仍需完整校验。 */
-export interface MiniappManifest {
-    /** 原始产物可带额外元数据；发布校验返回值只保留已知字段。 */
-    [key: string]: unknown;
-    /** 展示名称；SDK `0.8.2` 起需与图标、封面一起提供。 */
-    name?: string;
-    /** 相对构建目录的图标路径。 */
-    icon?: string;
-    /** 相对构建目录的封面路径，1–5 张，按展示顺序排列。 */
-    coverImages?: string[];
-    /** 生成产物时实际安装的 hb-sdk 版本，不是小程序发布版本。 */
-    sdkVersion: string;
-    /** 小程序发布版本：完整 SemVer，可含 prerelease，不允许 build metadata 或 core `0.0.0`。 */
-    version: string;
-    /** 小程序承诺适配的非空、无重复目标平台列表。 */
-    platforms: readonly MiniappPlatform[];
-    /** 产物权限声明；SDK `0.9` 系列起必须显式提供，无权限需求时使用空对象。 */
-    permissions?: MiniappPermissionDeclarations;
-    /** 构建生成的 Companion 归档声明，不是含 source 目录的项目 authoring 配置。 */
-    companions?: MiniappCompanionManifestDeclarations;
-    /** 桌面窗口的可选初值、最小尺寸及是否可缩放。 */
-    window?: MiniappWindowDeclaration;
-    /** 关联游戏 App ID 字符串，最多 20 个；空列表在发布校验结果中省略。 */
-    bindAppIds?: readonly string[];
-    /** 发布类别；历史读取可缺省，发布校验必须提供。 */
-    category?: MiniappCategory;
-}
-export interface ParseMiniappManifestResult {
-    manifest: MiniappManifest;
-    hadBom: boolean;
-}
-/**
- * 判断小程序版本是否符合公开 Manifest 版本规则。
- *
- * @param version - 待判断的 `package.json.version` / Manifest 版本字符串；首尾空白会先被
- * 移除，但函数不会把规范化后的字符串返回给调用方。
- * @returns trim 后满足小程序严格版本规则时返回 `true`，否则返回 `false`。对类型声明允许的
- * 字符串输入，该函数只返回布尔值，不抛出校验错误。
- *
- * @remarks
- * 接受形式为 canonical SemVer `MAJOR.MINOR.PATCH[-PRERELEASE]`。trim 后的输入必须与
- * `semver` 严格解析得到的 `version` 完全相同，因此不完整版本（如 `1.2`）、`v` / `=`
- * 前缀、范围表达式、额外段，以及 major/minor/patch 或纯数字 prerelease 标识中的前导零
- * 都返回 `false`。只有首尾空白会被忽略，内部空白不会被修复。
- *
- * 合法 prerelease（如 `1.2.3-alpha.1`、`0.0.1-rc.0`）可以使用。build metadata 即使符合
- * 标准 SemVer（如 `1.2.3+build.1`）也被小程序发布合同显式禁止。模板占位 core
- * `0.0.0` 同样禁止，包括 `0.0.0-alpha` 等 prerelease；至少应提升 patch/minor/major
- * 之一，例如 `0.0.1-alpha.1`。
- *
- * 这是无 I/O、无状态修改的 predicate，适合表单即时判断。实际 Vite / `hb-sdk build`
- * 流程会调用同规则的 package version validator：成功时返回 trim 后版本并写入 Manifest，
- * 失败时抛出带 `package.json.version` 来源的错误；调用本函数为 `true` 不能跳过正式构建。
- *
- * {@link resolveMiniappManifestPlatforms} 处理的是 Manifest `sdkVersion` 对平台声明策略的
- * SemVer precedence，不是当前小程序的发布 `version`。不要用本函数替代平台解析，也不要
- * 把项目 version 当作 sdkVersion 传入。
- *
- * @example
- * ```ts
- * import { isValidVersion } from '@heybox/hb-sdk/miniapp-publish'
- *
- * isValidVersion(' 1.2.3 ') // true
- * isValidVersion('1.2.3-alpha.1') // true
- * isValidVersion('0.0.1-alpha.1') // true
- * isValidVersion('1.2') // false
- * isValidVersion('v1.2.3') // false
- * isValidVersion('1.2.3+build.1') // false
- * isValidVersion('0.0.0-alpha') // false
- * ```
- *
- * @see {@link resolveMiniappManifestPlatforms}
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
- */
-export declare function isValidMiniappManifestVersion(version: string): boolean;
-export declare function validateMiniappPackageVersionForBuild(version: string): string;
-export declare function validateMiniappManifestVersion(version: unknown, sourceLabel?: string): string;
-export declare function renderMiniappManifest(manifest: MiniappManifest): string;
-export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
-/**
- * 校验发布 Manifest 并返回规范化后的已知字段。
- *
- * @param manifest - 从构建产物读取的 Manifest，图片和 Companion 路径相对构建目录。
- * @returns 新对象：规范化版本、名称、平台与游戏绑定，省略空绑定及未声明的可选字段；不保留未知字段。
- * @throws `Error` 版本、平台、资料、权限、窗口、游戏绑定或生成的 Companion 声明非法，以及类别缺失时抛出。
- * @remarks
- * 不修改输入对象，不执行文件 I/O；不会验证图片/归档是否存在、内容摘要是否匹配，也不查询远端发布资格。
- * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
- */
-export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
-    category?: MiniappCategory | undefined;
-    bindAppIds?: readonly string[] | undefined;
-    window?: MiniappWindowDeclaration | undefined;
-    companions?: MiniappCompanionManifestDeclarations | undefined;
-    permissions?: Partial<Record<"userInfo" | "steamLibrary" | "share" | "storage" | "filesystem" | "clipboard" | "leaderboard" | "companion" | "appProtocol", import("./permissions").SimpleMiniappPermissionDeclaration> & {
-        network: import("./permissions").NetworkMiniappPermissionDeclaration;
-    }> | undefined;
-    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
-    name?: string | undefined;
-    icon?: string | undefined;
-    coverImages?: string[] | undefined;
-    version: string;
-    sdkVersion: string;
-};
-export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
-export declare function areMiniappPlatformsEqual(left: readonly MiniappPlatform[], right: readonly MiniappPlatform[]): boolean;
-/**
- * Manifest 平台解析所采用的策略。
- *
- * @remarks
- * - `explicit`：Manifest 自身拥有合法、非空的 `platforms` 字段；无论 sdkVersion 是否低于
- *   `0.9.0`，显式声明都优先且不会被兼容默认值覆盖。
- * - `legacy_mobile_default`：Manifest 完全没有 `platforms` 字段，且 sdkVersion 缺失/空白或
- *   SemVer precedence 低于 `0.9.0`；最终按 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES} 兜底。
- *
- * 字面量 `legacy_mobile_default` 已作为详情接口 wire 值下发、并持久化进后端平台快照；
- * 兜底集合虽已由移动端三件套扩为五平台，这里仍保持原字符串不变，避免存储与协议迁移。
- */
-export type MiniappPlatformPolicy = 'explicit' | 'legacy_mobile_default';
-/**
- * Manifest 平台声明的规范化解析结果，供 CLI、开放平台网页、后端与 Runtime 共用。
- *
- * @remarks
- * 返回对象通过 `Object.freeze()` 冻结，字段和数组在类型层也都是只读值。调用方应把其中
- * 的数组视为不可变集合，不要修改、重新排序或自行合并 fallback。`platformsDeclared` 与
- * `policy` 用于保留“显式声明”与“历史缺声明默认”的来源差异。
- */
-export interface MiniappPlatformResolution {
-    /**
-     * 规范化后的显式声明。`explicit` 时按固定顺序
-     * `android`、`ios`、`ohos`、`windows`、`macos`、`linux` 排列并只保留声明项；
-     * `legacy_mobile_default` 时是冻结的空数组，表示历史产物没有声明，而不是“不支持平台”。
-     */
-    readonly declared: readonly MiniappPlatform[];
-    /**
-     * 最终用于展示、校验和运行判断的平台集合。`explicit` 时与规范化后的 `declared` 相同；
-     * `legacy_mobile_default` 时固定为 {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}。
-     */
-    readonly effective: readonly MiniappPlatform[];
-    /**
-     * Manifest 是否拥有经过校验的显式 `platforms` 字段。显式声明时为 `true`，
-     * 历史 fallback 得到相同 effective 集合时仍为 `false`。
-     */
-    readonly platformsDeclared: boolean;
-    /** 本次解析采用的来源策略；与 `platformsDeclared` 保持一致。 */
-    readonly policy: MiniappPlatformPolicy;
-}
-/**
- * 解析 Manifest 平台声明，是 `0.9.0` 硬切规则的唯一实现。
- *
- * @param sdkVersion - 产物写入 Manifest 的 hb-sdk 版本，不是小程序自身的发布 version。
- * `undefined`、空字符串和纯空白按历史“缺失 sdkVersion”处理；其他字符串会先 trim，再按
- * canonical strict SemVer 校验并参与 precedence 比较。
- * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
- * 自有 `platforms` 字段，其他字段不参与平台解析。
- * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
- * effective；历史兼容返回空 declared 与历史兜底平台集合 effective。
- * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
- * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
- * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
- *
- * @remarks
- * 解析顺序与后端领域层保持一致：先校验 Manifest 对象，再处理 sdkVersion；只要非空
- * sdkVersion 非法，即使存在合法 platforms 也会抛出，不会忽略版本。版本比较使用 SemVer
- * precedence，不做字符串比较：`0.9.0-alpha.1 < 0.9.0`，而 `0.10.0 > 0.9.0`。
- *
- * Manifest 拥有 `platforms` 字段时总是走 `explicit`：字段必须是非空数组，每项必须属于
- * `MINIAPP_PLATFORM_VALUES` 且不能重复；结果按固定平台词表排序，而不是保留输入顺序。
- * 该规则与 sdkVersion 是否缺失、低于或达到硬切点无关。显式声明一旦非法绝不回退到
- * legacy 默认值。
- *
- * Manifest 完全没有 `platforms` 字段时才判断硬切：sdkVersion 缺失/空白，或 precedence
- * 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`（`0.9.0`）时返回
- * `legacy_mobile_default`；`0.9.0` 稳定版及更高版本直接抛错。`0.9.0-*` prerelease 仍低于
- * 稳定硬切点，因此可解析历史缺失声明。
- *
- * 返回对象被 `Object.freeze()`；显式声明数组和 legacy 的空 declared 数组也被冻结。所有
- * 数组均以 readonly 合同暴露，调用方应直接消费 `effective`，不得再比较版本或补默认值。
- *
- * 当前 Vite 构建入口
- * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
- * 会从 `package.json#heybox.platforms` 读取并写入显式声明；legacy 分支只用于解析缺少字段
- * 的历史产物，不是新项目省略 platforms 的许可。
- *
- * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
- * 判断的是小程序发布 `version`，并额外拒绝模板值 `0.0.0`；本函数的 sdkVersion 是 hb-sdk
- * 版本，`0.0.0` 本身是可比较的 strict SemVer 并低于硬切点。两类版本不能互换校验。
- *
- * @example
- * ```ts
- * import { resolveMiniappManifestPlatforms } from '@heybox/hb-sdk/miniapp-publish'
- *
- * const explicit = resolveMiniappManifestPlatforms('0.9.0', {
- *   platforms: ['linux', 'android', 'macos'],
- * })
- * console.log(explicit)
- * // {
- * //   declared: ['android', 'macos', 'linux'],
- * //   effective: ['android', 'macos', 'linux'],
- * //   platformsDeclared: true,
- * //   policy: 'explicit'
- * // }
- *
- * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
- * console.log(legacy.effective) // ['android', 'ios', 'ohos', 'windows', 'macos']
- * ```
- *
- * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
- * @see {@link MINIAPP_LEGACY_DEFAULT_PLATFORM_VALUES}
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
- * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
- */
-export declare function resolveMiniappManifestPlatforms(sdkVersion: string | undefined, manifest: unknown): MiniappPlatformResolution;
-/**
- * 校验并归一化 `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;