@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/core/singleton.d.ts

@@ -16,6 +16,66 @@ import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler
 /**
  * 获取默认 SDK 实例的当前握手状态。
  *
+ * @returns 当前冻结的
+ * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState)：
+ * `connecting` 表示初始握手尚未落定，`ready` 表示握手成功；`failed` 表示握手失败，并通过
+ * `error` 保留原始
+ * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。状态不变期间重复调用
+ * 返回同一个对象引用，落定时只会替换一次。
+ *
+ * @remarks
+ * 该函数不接收参数并同步返回当前快照，不等待 Promise、不轮询、不发送 bridge 请求，也不会因为
+ * 握手失败而抛出 `failed.error`。读取状态无需在 `package.json#heybox.permissions` 中声明权限，
+ * 不要求可信用户手势。根包导入时已经自动启动握手；普通异步能力调用也会自行等待，不需要用本
+ * API 手动实现等待器。
+ *
+ * 状态 wrapper 已浅冻结。状态机只允许 `connecting -> ready` 或 `connecting -> failed` 一次迁移，
+ * 终态不会回退或互相转换；`failed.error` 是握手 Promise 使用的同一个原始错误实例，可根据稳定的
+ * `code` 分支处理。常见初始失败包括 `NOT_IN_IFRAME`、`MISSING_NONCE`、`READY_TIMEOUT`、
+ * `HANDSHAKE_FAILED`、`RUNTIME_UNAVAILABLE` 或握手完成前的 `SDK_DESTROYED`。
+ *
+ * 需要让界面跟随状态变化时，使用
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)：它会在订阅期间同步回放
+ * 当前值，再通知至多一次终态迁移。不要轮询本函数。对于必须保留原始可信用户手势的按钮，可用
+ * 该持久状态提前控制 `disabled`，但不要在点击回调里等待握手。
+ *
+ * [on('ready')](/reference/sdk/lifecycle/on) 是握手成功瞬间的事件：不会向晚订阅者重放，Host 重复
+ * 派发时也可能再次触发事件 handler；持久状态则只迁移一次并始终可查询。`ready` 只表示初始握手
+ * 已成功，后续 `unload` 不会把状态改回 `failed`，因此不能把它当作 Runtime 持续存活检查。
+ *
+ * SDK 会在发布 `ready` 状态前缓存环境快照，所以 `status === 'ready'` 时可以立即调用
+ * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。`failed` 时该同步环境 API 会抛出
+ * 同一个 `state.error`；不要求同步读取时，优先使用会自动等待的
+ * [environment.getInfo()](/reference/sdk/environment/getInfo)。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const state = hbSDK.getHandshakeState()
+ *
+ * switch (state.status) {
+ *   case 'connecting':
+ *     submitButton.disabled = true
+ *     break
+ *   case 'ready': {
+ *     submitButton.disabled = false
+ *     const environment = hbSDK.environment.getInfoSync()
+ *     console.log(environment.runtime.mode)
+ *     break
+ *   }
+ *   case 'failed':
+ *     submitButton.disabled = true
+ *     console.error('SDK 握手失败', state.error.code)
+ *     break
+ * }
+ * ```
+ *
+ * @see [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 三种状态及冻结语义。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 同步回放当前状态并订阅终态迁移。
+ * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的生命周期边沿事件。
+ * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` 后同步读取环境快照。
+ *
  * @since 0.7.0-alpha.9
  * @hbPlatform android
  * @hbPlatform ios
@@ -32,6 +92,83 @@ export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
 /**
  * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
  *
+ * @param handler - 接收
+ * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 的处理函数。
+ * 注册期间会在本函数返回前同步调用一次：`connecting` 表示初始握手仍在进行，`ready` 表示成功，
+ * `failed.error` 是原始
+ * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。
+ * @returns 从默认 SDK 状态 store 移除当前 handler 的 unsubscribe。调用一次或多次都返回 `void` 且
+ * 不会抛错；取消后不再接收未来迁移，但不会撤销已经同步回放的当前状态。
+ *
+ * @remarks
+ * 订阅是纯本地同步操作，不发送 bridge 请求、不等待握手，也无需在
+ * `package.json#heybox.permissions` 中声明权限或保留可信用户手势。根包导入时握手已经自动启动；
+ * 本 API 用于观察状态，不用于主动发起或重试握手。
+ *
+ * handler 会在加入订阅集合后、unsubscribe 返回前立即同步收到当前冻结状态：
+ *
+ * - 当前为 `connecting`：先立即收到 `connecting`，随后至多再收到一次 `ready` 或 `failed`；
+ * - 当前已是 `ready` 或 `failed`：立即收到该终态，之后不会再迁移；
+ * - 在终态通知过程中新增订阅：通过即时回放收到一次终态，不会因同一迁移重复调用。
+ *
+ * 状态只允许 `connecting -> ready` 或 `connecting -> failed`，终态不回退。`failed.error` 是握手失败
+ * 和同步环境读取使用的同一个原始错误实例，可按稳定的 `code` 分支处理。`ready` 只表示初始握手
+ * 已成功；后续 `unload` 不会把状态改回 `failed`，因此它不是 Runtime 持续存活探针。
+ *
+ * SDK 会逐个捕获 handler 的同步异常：初次即时回放或终态通知中抛错，都不会从本函数传播、改变
+ * 状态、阻断握手 Promise 或阻止其他订阅者收到通知。handler 返回值会被忽略，Promise 也不会被
+ * 等待；异步 handler 应在自身内部捕获 rejected Promise，避免未处理拒绝。
+ *
+ * 每个 handler 以 Set 语义保存；同一函数引用重复订阅只有一个未来通知注册，但每次调用本函数仍会
+ * 同步回放当前状态，任一 unsubscribe 都会移除该注册。应在页面、组件或业务模块销毁时调用
+ * unsubscribe。SDK 内部销毁会清空全部状态订阅；若销毁发生在握手落定前，会先发布携带
+ * `SDK_DESTROYED` 的 `failed`，再清空订阅。此后重复调用已经返回的 unsubscribe 仍是安全空操作。
+ * `unload` 发生在握手前时则以 `RUNTIME_UNAVAILABLE` 落为 `failed`；发生在 `ready` 后不会产生
+ * 第二次状态通知。
+ *
+ * 与 [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 相比，本 API 适合让 UI 自动跟随
+ * 唯一一次迁移，且即时回放意味着通常不需要先额外读取一次状态。
+ * [on('ready')](/reference/sdk/lifecycle/on) 则是不可重放、可能因 Host 重复事件再次触发的边沿通知，
+ * 不应用于驱动晚挂载按钮的可用状态。
+ *
+ * SDK 会在发布 `ready` 状态前缓存环境快照，因此可以在 `ready` handler 中立即调用
+ * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。在 `failed` handler 中调用该
+ * API 会抛出同一个 `state.error`；一般异步读取可使用
+ * [environment.getInfo()](/reference/sdk/environment/getInfo) 自动等待。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const stop = hbSDK.onHandshakeStateChange(state => {
+ *   switch (state.status) {
+ *     case 'connecting':
+ *       submitButton.disabled = true
+ *       statusText.textContent = '正在连接'
+ *       break
+ *     case 'ready':
+ *       submitButton.disabled = false
+ *       statusText.textContent = hbSDK.environment.getInfoSync().runtime.mode
+ *       break
+ *     case 'failed':
+ *       submitButton.disabled = true
+ *       statusText.textContent = `连接失败：${state.error.code}`
+ *       break
+ *   }
+ * })
+ *
+ * // 页面或组件真正销毁时执行；重复取消也安全。
+ * window.addEventListener('unload', () => {
+ *   stop()
+ *   stop()
+ * }, { once: true })
+ * ```
+ *
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 一次性同步读取当前持久状态。
+ * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的握手成功边沿事件。
+ * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` handler 中同步读取环境。
+ * @see [事件与生命周期](/guide/lifecycle) 握手与普通生命周期事件的使用建议。
+ *
  * @since 0.7.0-alpha.9
  * @hbPlatform android
  * @hbPlatform ios
@@ -48,9 +185,83 @@ export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeS
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName - 要监听的事件名。
- * @param handler - 事件处理函数。
- * @returns 事件解绑函数。
+ * @param eventName - 要监听的
+ * [MiniProgramEventName](/reference/symbols/root/types/MiniProgramEventName)。泛型 `T` 通常由该字符串
+ * 字面量推断，并决定 handler 的 payload 类型。
+ * @param handler - 与 `eventName` 对应的
+ * [MiniProgramEventHandler](/reference/symbols/root/types/MiniProgramEventHandler)。payload 由
+ * [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 精确映射。
+ * @returns 只解绑当前 `eventName` / handler 组合的函数。调用一次或多次都返回 `void` 且不会抛错，
+ * 不影响同一事件上的其他 handler。
+ *
+ * @remarks
+ * 事件名决定 payload 字段：
+ *
+ * - `launch`：`{ timestamp, url? }`；`ready`：`{ timestamp }`；
+ * - `show` / `hide`：`{ timestamp, source? }`；`unload`：`{ timestamp }`；
+ * - `error`：
+ *   [MiniProgramBridgeError](/reference/symbols/protocol/interfaces/MiniProgramBridgeError)，包含 `code`、
+ *   `message` 与可选 `data`，不是 JavaScript `Error` 实例；
+ * - `heybox_app_login_change`：`{ isHeyboxAppLoggedIn }`；
+ * - `user_info_authorization_change`：
+ *   [UserInfoAuthorization](/reference/symbols/root/interfaces/UserInfoAuthorization)，包含 `identity` 与
+ *   `profile` 两项授权状态；
+ * - `companion.session.output`：`{ sessionId, controllerGeneration, stream, sequence, data }`；
+ * - `companion.session.exit`：`{ sessionId, exit }`；
+ * - `companion.session.ownershipLost`：`{ sessionId, controllerGeneration }`。
+ *
+ * `on()` 同步把 handler 加入默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求。
+ * 注册本身无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势，也不会因当前
+ * 握手处于 `connecting`、`ready` 或 `failed` 而抛出 SDK 错误。具体事件是否会产生，仍取决于 Host、
+ * Runtime 生命周期和相关业务能力。
+ *
+ * event bus 使用 Set 保存每个事件的 handler。同一事件与同一函数引用重复注册只有一个有效监听；
+ * 任一返回的 unsubscribe 或 [off()](/reference/sdk/lifecycle/off) 都会移除该唯一注册。不同函数引用
+ * 不会去重，同一函数注册到不同事件也彼此独立。应保存 unsubscribe，并在页面、组件或业务模块销毁
+ * 时调用；unsubscribe 可安全重复调用。
+ *
+ * handler 在事件派发时同步执行。SDK 不捕获普通事件 handler 的同步异常，也不等待其 Promise；某个
+ * handler 抛错可能阻断同次派发中的后续 handler，异步拒绝也可能成为未处理 Promise。需要隔离时在
+ * handler 内自行 `try/catch`，并显式处理异步任务的 rejected Promise。
+ *
+ * 所有生命周期与业务事件都不会重放：只派发给事件到达时已经注册的 handler，晚注册无法取回
+ * `launch`、`ready` 或其他历史事件。`ready` 只是握手成功瞬间的边沿通知，Host 重复派发时 handler
+ * 也可能再次执行；需要可查询、会向订阅者立即回放且只迁移一次的握手状态时，使用
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 和
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)。
+ *
+ * 收到 `unload` 后当前 Runtime 上下文不可恢复，在途请求会失败，也不应再依赖后续 bridge 事件；
+ * SDK 内部销毁会移除底层 message listener。调用 unsubscribe 只清理该本地事件 handler，不取消
+ * API 请求、业务任务、Companion 进程或握手状态订阅。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const stopShow = hbSDK.on('show', ({ timestamp, source }) => {
+ *   try {
+ *     refreshVisibleData({ timestamp, source })
+ *   } catch (error) {
+ *     reportHandlerError(error)
+ *   }
+ * })
+ *
+ * const stopError = hbSDK.on('error', ({ code, message }) => {
+ *   console.error(code, message)
+ * })
+ *
+ * // 页面或组件销毁时；重复调用也安全。
+ * stopShow()
+ * stopShow()
+ * stopError()
+ * ```
+ *
+ * @see [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 所有事件与 payload 字段。
+ * @see [off()](/reference/sdk/lifecycle/off) 使用事件名与 handler 引用精确移除监听。
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
+ * @see [事件与生命周期](/guide/lifecycle) 生命周期时机与清理建议。
+ *
  * @since 0.2.0-alpha.0
  * @hbPlatform android
  * @hbPlatform ios
@@ -67,9 +278,57 @@ export declare function on<T extends MiniProgramEventName>(eventName: T, handler
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName - 要移除的事件名。
- * @param handler - 对应的事件处理函数。
- * @returns 无返回值。
+ * @param eventName - 注册 handler 时使用的同一个事件名。只检查该事件自己的监听集合，不影响
+ * 其他事件上的注册。
+ * @param handler - 传给 `on(eventName, handler)` 的同一个函数对象。签名或函数体相同的新函数不是
+ * 同一引用，不能移除原监听。
+ * @returns `void`。移除成功、目标从未注册或此前已经移除时都不返回状态。
+ *
+ * @remarks
+ * 该函数同步修改默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求，也不会调用
+ * handler。它无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势；握手处于
+ * `connecting`、`ready` 或 `failed`，以及已经收到 `unload` 时，取消操作本身都不会产生 SDK 错误。
+ *
+ * 匹配规则是 `eventName` 与 handler 函数引用同时相等。匹配后只移除这一项，同一事件上的其他
+ * handler、同一 handler 在其他事件上的注册均保留。event bus 对同一事件与同一函数引用使用集合
+ * 语义，重复 `on()` 只有一个有效注册，一次 `off()` 即会移除；重复调用 `off()` 是幂等的，未知事件
+ * 或未注册 handler 会被静默忽略。
+ *
+ * 大多数场景优先保存并调用 [on()](/reference/sdk/lifecycle/on) 返回的 unsubscribe：它已经闭包绑定
+ * 正确的事件名和 handler，同样可以重复调用。只有调用方需要在另一处按具名 handler 精确移除时，
+ * 才直接使用 `off()`。匿名函数必须先保存引用；重新创建一个内容相同的箭头函数无法取消旧监听。
+ *
+ * 生命周期与业务事件不会重放，只派发给事件到达时仍处于注册状态的 handler。`off()` 只阻止后续
+ * 事件，不能撤销已经执行的 handler，也不能取回注册前错过的 `launch`、`ready`、`show`、`hide`、
+ * `unload` 等事件。当前握手状态应通过
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 或
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 获取，不要通过重新注册
+ * `ready` 事件补状态。
+ *
+ * Runtime `unload` 或 SDK 内部销毁后不会再有可依赖的未来 bridge 生命周期事件，但调用 unsubscribe
+ * 或 `off()` 做本地清理仍可安全重复执行。取消监听不会取消已经开始的 API 请求、业务任务或
+ * `onHandshakeStateChange()` 订阅；后者必须调用其自己返回的取消函数。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const pauseOnHide = () => pausePolling()
+ * const reportHide = () => reportVisibility('hidden')
+ *
+ * hbSDK.on('hide', pauseOnHide)
+ * const stopReporting = hbSDK.on('hide', reportHide)
+ *
+ * hbSDK.off('hide', pauseOnHide) // 只移除 pauseOnHide
+ * hbSDK.off('hide', pauseOnHide) // 已移除，仍然安全
+ * stopReporting()                // 推荐：使用 on() 返回的取消函数
+ * ```
+ *
+ * @see [on()](/reference/sdk/lifecycle/on) 注册事件并取得绑定好的取消函数。
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
+ * @see [事件与生命周期](/guide/lifecycle) 生命周期事件列表与清理建议。
+ *
  * @since 0.2.0-alpha.0
  * @hbPlatform android
  * @hbPlatform ios

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

@@ -1,5 +1,70 @@
+/** 单个小程序版本最多声明的关联游戏数量。 */
 export declare const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * {@link parseMiniappBindAppIds} 的诊断文案配置。
+ *
+ * @remarks
+ * 该选项只改变抛出 `Error` 的来源前缀，不改变校验、排序或返回值。函数不会 trim、补全或
+ * 校验标签；调用方应传能准确定位配置位置的非空文本。
+ */
 export interface ParseMiniappBindAppIdsOptions {
+    /**
+     * 写入每条错误消息开头的来源标签，默认 `package.json#heybox.bindAppIds`。
+     *
+     * @remarks
+     * Manifest 校验器会传 `manifest.bindAppIds`，因此同一个非法值可明确指出来自项目声明还是
+     * 构建产物。传入值会原样插入文案，不会自动添加冒号、路径或字段名。
+     */
     sourceLabel?: string;
 }
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 export declare function parseMiniappBindAppIds(value: unknown, options?: ParseMiniappBindAppIdsOptions): readonly string[];

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

@@ -1,7 +1,13 @@
 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";
@@ -57,6 +63,49 @@ 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;
@@ -75,40 +124,108 @@ 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;
-/** 平台解析策略：显式声明，或历史产物缺少声明时的移动端兼容。 */
+/**
+ * Manifest 平台解析所采用的策略。
+ *
+ * @remarks
+ * - `explicit`：Manifest 自身拥有合法、非空的 `platforms` 字段；无论 sdkVersion 是否低于
+ *   `0.9.0`，显式声明都优先且不会被兼容默认值覆盖。
+ * - `legacy_mobile_default`：Manifest 完全没有 `platforms` 字段，且 sdkVersion 缺失/空白或
+ *   SemVer precedence 低于 `0.9.0`；最终按 `android`、`ios`、`ohos` 历史集合兼容。
+ */
 export type MiniappPlatformPolicy = 'explicit' | 'legacy_mobile_default';
 /**
- * Manifest 平台解析结果，供 CLI、开放平台网页、后端与 Runtime 共用。
+ * Manifest 平台声明的规范化解析结果，供 CLI、开放平台网页、后端与 Runtime 共用。
  *
  * @remarks
- * `declared` 是规范化后的显式声明，历史兼容场景为空数组；`effective` 是用于展示与运行
- * 判断的最终平台集合。调用方不得自行比较 `0.9.0` 或补默认值，只能消费该结果。
+ * 返回对象通过 `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` 时固定为 `android`、`ios`、`ohos`。
+     */
     readonly effective: readonly MiniappPlatform[];
-    /** 是否显式声明了 `platforms`，用于区分显式移动端声明与历史移动端默认。 */
+    /**
+     * 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 与 Android/iOS/OHOS effective。
+ * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
+ * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
+ * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
+ *
  * @remarks
- * 规则与后端领域层保持一致：
- * - 无 `platforms` 字段：`sdkVersion` 缺失或 SemVer precedence 低于
- *   `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION` 时按历史移动端兼容；达到或高于硬切点即非法。
- * - 有 `platforms` 字段：复用 `validateMiniappPlatforms` 校验并规范化顺序；任何非法值
- *   （空数组、非数组、未知值、重复值）都不回退到历史兼容，即使 `sdkVersion < 0.9.0`。
- * - 任何非法的 `sdkVersion` 都会抛出，不做字符串比较。
- * @param sdkVersion - 产物 hb-sdk 版本；历史产物可能缺失。
- * @param manifest - 待解析的 Manifest（不可信输入）。
- * @returns 冻结的平台解析结果。
- * @throws Manifest 不是对象、`sdkVersion` 不是合法 SemVer、达到硬切点仍缺失 `platforms`，
- *   或 `platforms` 声明非法时抛出。
+ * 解析顺序与后端领域层保持一致：先校验 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']
+ * ```
+ *
+ * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
+ * @see {@link MINIAPP_LEGACY_MOBILE_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;
 /**