@heybox/hb-sdk 0.9.1-alpha.3 → 0.9.1-alpha.5

package/types/core/singleton.d.ts

@@ -1,372 +0,0 @@
-import type { MiniProgramAuthModule } from '../modules/auth';
-import type { MiniProgramCloudModule } from '../modules/cloud';
-import type { MiniProgramCompanionModule } from '../modules/companion';
-import type { MiniProgramShareModule } from '../modules/share';
-import type { MiniProgramStorageModule } from '../modules/storage';
-import type { MiniProgramNetworkModule } from '../modules/network';
-import type { FilesModule } from '../modules/files';
-import type { MiniProgramViewportModule } from '../modules/viewport';
-import type { MiniProgramUserModule } from '../modules/user';
-import type { MiniProgramUiModule } from '../modules/ui';
-import type { MiniProgramDeviceModule } from '../modules/device';
-import type { MiniProgramEnvironmentModule } from '../modules/environment';
-import type { MiniProgramNavigationModule } from '../modules/navigation';
-import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/**
- * 获取默认 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
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-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
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
-/**
- * 注册默认 SDK 实例的事件监听。
- *
- * @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` 两项授权状态，支持 Steam 账号能力时还可能包含 `steam_account`；
- * - `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
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-/**
- * 移除默认 SDK 实例的事件监听。
- *
- * @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
- * @hbPlatform ohos
- * @hbPlatform windows
- * @hbPlatform macos
- * @hbClient android none
- * @hbClient ios none
- * @hbClient ohos none
- * @hbClient windows none
- * @hbClient macos none
- */
-export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-/** 默认 SDK 实例的授权模块。 */
-export declare const auth: MiniProgramAuthModule;
-/** 默认 SDK 实例的用户资料模块。 */
-export declare const user: MiniProgramUserModule;
-/** 默认 SDK 实例的分享模块。 */
-export declare const share: MiniProgramShareModule;
-/** 默认 SDK 实例的 Viewport 模块。 */
-export declare const viewport: MiniProgramViewportModule;
-/** 默认 SDK 实例的 storage 模块。 */
-export declare const storage: MiniProgramStorageModule;
-/** 默认 SDK 实例的 network 模块。 */
-export declare const network: MiniProgramNetworkModule;
-/** 默认 SDK 实例的 files 模块。 */
-export declare const files: FilesModule;
-/** 默认 SDK 实例的 UI 模块。 */
-export declare const ui: MiniProgramUiModule;
-/** 默认 SDK 实例的 device 模块。 */
-export declare const device: MiniProgramDeviceModule;
-/** 默认 SDK 实例的 navigation 模块。 */
-export declare const navigation: MiniProgramNavigationModule;
-/** 默认 SDK 实例的 cloud 模块。 */
-export declare const cloud: MiniProgramCloudModule;
-/** 默认 SDK 实例的受管桌面程序模块。 */
-export declare const companion: MiniProgramCompanionModule;
-/** 默认 SDK 实例的 environment 模块。 */
-export declare const environment: MiniProgramEnvironmentModule;
-/** 重置默认 SDK 实例，仅用于测试。 */
-export declare function resetDefaultSDKForTest(): void;

package/types/core/utils.d.ts

@@ -1,10 +0,0 @@
-/** 获取浏览器全局 window。 */
-export declare function getGlobalWindow(): Window | undefined;
-/** 获取父窗口；非 iframe 环境返回 null。 */
-export declare function getParentWindow(currentWindow?: Window): Window | null;
-/** 尝试读取父窗口 origin；跨域读取失败时回退到 document.referrer。 */
-export declare function readParentOrigin(currentWindow?: Window): string;
-/** 从父容器注入到 URL 的 query 中读取 bridge nonce。 */
-export declare function readBridgeNonce(currentWindow?: Window): string;
-/** 创建请求 ID。 */
-export declare function createMessageId(): string;

package/types/core/version.d.ts

@@ -1,2 +0,0 @@
-/** 构建时替换为当前发布包的实际版本。 */
-export declare const HB_SDK_VERSION: string;

package/types/devtools/device-logs.d.ts

@@ -1,48 +0,0 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-export declare const DEVICE_LOG_PATH = "/__hb_sdk__/device-logs";
-export declare function registerDeviceLogs(port: number, store: DeviceLogStore): () => void;
-export declare function getDeviceLogs(appUrl: string): any;
-export declare class DeviceLogStore {
-    private sandboxRequests;
-    listSandbox(id: string, path: string): Promise<unknown>;
-    readonly uploadToken: string;
-    readonly epoch: `${string}-${string}-${string}-${string}-${string}`;
-    private readonly expiresAt;
-    private cursor;
-    private logs;
-    private devices;
-    query(params: URLSearchParams): {
-        schemaVersion: number;
-        epoch: `${string}-${string}-${string}-${string}-${string}`;
-        items: {
-            cursor: number;
-            deviceSessionId: string;
-            sequence: number;
-            timestamp: number;
-            receivedAt: number;
-            level: string;
-            source: string;
-            message: string;
-            truncated: boolean;
-            method?: string;
-            callId?: string;
-            outcome?: string;
-            errorCode?: string;
-            durationMs?: number;
-        }[];
-        nextCursor: number;
-        hasMore: boolean;
-        gap: boolean;
-        devices: {
-            id: string;
-            name: string;
-            platform: string;
-            connectedAt: number;
-            lastSeen: number;
-            online: boolean;
-        }[];
-    };
-    upload(req: IncomingMessage, res: ServerResponse): Promise<void>;
-}
-/** 同源开发页面使用有界批量回传；传输失败不会递归写入 console。 */
-export declare function deviceLogBootstrap(token: string): string;

package/types/miniapp-manifest/basic-info-browser.d.ts

@@ -1,37 +0,0 @@
-/**
- * 在浏览器中校验构建产物的展示资料图片，并创建预览 URL。
- *
- * @param manifest - 构建产物 Manifest，必须包含合法的 `sdkVersion`。
- * @param files - 构建文件列表；`relativePath` 必须精确匹配 Manifest 中的图片路径。
- * @returns 名称、图标 `icon_url` 和按原顺序排列的 `cover_image_urls`；允许缺失资料的历史产物返回 `undefined`。
- * @throws `Error` 资料非法、图片缺失/为空/超过 10 MiB、格式与扩展名不符、超过 4000 万像素、
- * icon 不是 200×200，或仍使用脚手架占位图片时拒绝；浏览器解码和摘要计算失败也会拒绝。
- * @remarks
- * 需要浏览器提供 `crypto.subtle`、`createImageBitmap` 和 object URL API；不生成或回写 Manifest。
- * 失败时会释放本次已创建的 URL；成功后所有 URL 由调用方在预览结束或替换时释放。
- * @example
- * ```ts
- * import { previewMiniappBasicInfo } from '@heybox/hb-sdk/miniapp-publish';
- *
- * const preview = await previewMiniappBasicInfo(manifest, files);
- * if (preview) {
- *   try {
- *     const image = new Image();
- *     image.src = preview.icon_url;
- *     await image.decode();
- *     document.body.append(image);
- *   } finally {
- *     // 已加载的图像可继续显示；不再需要从这些 URL 加载时释放。
- *     [preview.icon_url, ...preview.cover_image_urls].forEach(URL.revokeObjectURL);
- *   }
- * }
- * ```
- */
-export declare function previewMiniappBasicInfo(manifest: Record<string, unknown>, files: readonly {
-    relativePath: string;
-    file: Blob;
-}[]): Promise<{
-    name: string;
-    icon_url: string;
-    cover_image_urls: string[];
-} | undefined>;

package/types/miniapp-manifest/basic-info-image-header.d.ts

@@ -1,6 +0,0 @@
-/** 在浏览器解码前读取尺寸上限；真实可解码性仍必须由图片解码器验证。 */
-export declare function readBasicInfoImageHeader(bytes: Uint8Array): {
-    format: string;
-    width: number;
-    height: number;
-};

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

@@ -1,17 +0,0 @@
-import { type MiniappBasicInfo } from './basic-info';
-export declare function inspectBasicInfoImage(bytes: Uint8Array, sourcePath: string, kind: 'icon' | 'cover'): Promise<{
-    sha256: string;
-    extension: string;
-}>;
-export declare function inspectRemoteBasicInfoImage(bytes: Uint8Array, kind: 'icon' | 'cover'): Promise<{
-    sha256: string;
-    extension: string;
-}>;
-export declare function readBasicInfoSource(projectRoot: string, relative: string, kind: 'icon' | 'cover'): Promise<{
-    sha256: string;
-    extension: string;
-    bytes: NonSharedBuffer;
-}>;
-export declare function prepareMiniappBasicInfo(projectRoot: string, outputRoot: string, sdkVersion: string): Promise<MiniappBasicInfo | undefined>;
-/** 逐级校验真实目录，避免保留目录或迁移目录中的符号链接将写入带到项目外。 */
-export declare function ensureBasicInfoDirectory(rootPath: string, relative: string): Promise<void>;

package/types/miniapp-manifest/basic-info-placeholder.d.ts

@@ -1 +0,0 @@
-export declare const BASIC_INFO_PLACEHOLDER_SHA256 = "d14e54b30f5e6d1bcbf51267bc82b06a0af7c333f2945bcc16b4e1adc3b123dd";

package/types/miniapp-manifest/basic-info.d.ts

@@ -1,33 +0,0 @@
-export declare const BASIC_INFO_MAX_BYTES: number;
-export declare const BASIC_INFO_MAX_PIXELS = 40000000;
-/** 小程序展示资料；项目声明和构建产物使用相同字段，图片路径的根目录不同。 */
-export interface MiniappBasicInfo {
-    /** NFKC 规范化并移除首尾 Unicode 空白后的名称，长度为 1–40 个 Unicode code point。 */
-    name: string;
-    /** 图标的规范相对路径；项目声明相对项目目录，Manifest 相对构建目录。 */
-    icon: string;
-    /** 1–5 个互不重复的封面相对路径，按展示顺序排列。 */
-    coverImages: string[];
-}
-/**
- * 规范化并校验小程序展示名称。
- *
- * @param raw - 原始名称，必须是字符串。
- * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
- * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
- * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
- */
-export declare function normalizeBasicInfoName(raw: unknown): string;
-export declare function validateBasicInfoPath(raw: unknown): string;
-/**
- * 校验项目声明或 Manifest 中的小程序展示资料。
- *
- * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
- * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
- * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
- * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
- * @remarks
- * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
- * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
- */
-export declare function parseMiniappBasicInfo(value: Record<string, unknown>, sdkVersion?: string): MiniappBasicInfo | undefined;

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

@@ -1,70 +0,0 @@
-/** 单个小程序版本最多声明的关联游戏数量。 */
-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/category.d.ts

@@ -1,11 +0,0 @@
-/** 小程序发布类别：`tool` 为工具、`game` 为游戏、`other` 为其他；新上传版本必须声明，历史读取可缺省。 */
-export type MiniappCategory = 'tool' | 'game' | 'other';
-/**
- * 校验项目配置或产物中的小程序类别。
- *
- * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
- * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
- * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
- * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
- */
-export declare function parseMiniappCategory(value: unknown, sourceLabel?: string): MiniappCategory | undefined;

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

@@ -1,2 +0,0 @@
-/** 双次读取校验输入稳定性；保留 .app 安全链接以避免破坏签名。 */
-export declare function packCompanionDirectory(root: string, label: string): Buffer;

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

@@ -1,4 +0,0 @@
-/** 检查原生入口的文件格式与目标架构；文件后缀和执行位不能代替此门禁。 */
-export declare function assertCompanionExecutable(bytes: Buffer, target: 'windows-x64' | 'macos-arm64'): void;
-/** 只解析 bundle 主字典的 CFBundleExecutable，兼容 XML 与 binary plist。 */
-export declare function companionBundleExecutable(plist: Buffer): string;