@heybox/hb-sdk 0.7.0-alpha.5 → 0.7.0

package/skill/references/recipes.md

@@ -26,7 +26,26 @@
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 SDK。需要开放能力时，先等待 `ready()`，再根据小程序是否开通网络权限选择身份流程。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。SDK 导入时会自动启动握手，能力调用会自动等待；业务只需根据小程序是否开通网络权限选择身份流程。
+
+## 交互控件与握手状态
+
+`auth.login()`、`user.getLocalIdentity()` 等可能展示授权 UI 的能力必须保留原始可信用户手势。不要在点击回调中等待握手；页面加载时读取并订阅持久握手状态，只在 `status === 'ready'` 时启用按钮：
+
+```ts
+import hbSDK, { type MiniProgramSDKHandshakeState } from '@heybox/hb-sdk'
+import { computed, onUnmounted, ref } from 'vue'
+
+const handshakeState = ref<MiniProgramSDKHandshakeState>(hbSDK.getHandshakeState())
+const stopHandshakeState = hbSDK.onHandshakeStateChange((state) => {
+  handshakeState.value = state
+})
+const sdkReady = computed(() => handshakeState.value.status === 'ready')
+
+onUnmounted(stopHandshakeState)
+```
+
+把 `sdkReady` 用作按钮的 `disabled` 条件。订阅会立即回放当前状态，因此晚挂载组件也能得到 `ready` 或 `failed` 终态。`ready` 生命周期事件只在握手成功瞬间派发且不会重放，不能作为当前状态来源。
 
 ## 未开通网络权限
 
@@ -36,8 +55,6 @@
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 async function getLocalIdentityFromUserAction() {
-  await hbSDK.ready()
-
   try {
     const { appUserId } = await hbSDK.user.getLocalIdentity()
     return appUserId
@@ -56,11 +73,11 @@ async function getLocalIdentityFromUserAction() {
 
 有网络小程序通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作：
 
+SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用；点击回调直接调用 `auth.login()`，不要先等待其他异步任务，以免首次操作丢失可信手势。
+
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-await hbSDK.ready()
-
 async function loginFromUserAction() {
   try {
     const result = await hbSDK.auth.login({ scopes: ['profile'] })
@@ -79,11 +96,7 @@ async function loginFromUserAction() {
 }
 ```
 
-返回值与边界以[用户身份与登录](/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
-
-## ready 的含义
-
-`ready()` 只表示 SDK 已就绪，可以安全调用开放能力。它不表示已经取得用户授权，也不返回用户身份。
+返回值与边界以[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
 
 ## 默认单例
 
@@ -107,12 +120,12 @@ async function loginFromUserAction() {
 
 在登录、绑定账号或读取资料等明确的用户操作中调用 `auth.login()`：
 
+SDK 会在导入时自动握手，能力调用也会自动等待。不要在按钮回调中等待握手；用 `getHandshakeState()` 读取当前状态、用 `onHandshakeStateChange()` 订阅并立即接收状态，只在 `status === 'ready'` 时启用按钮，并在组件销毁时取消订阅。`ready` 生命周期事件不会重放，只是边沿通知，不能作为握手状态。
+
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 async function loginFromUserAction() {
-  await hbSDK.ready()
-
   try {
     const { code, expiresIn, scopes } = await hbSDK.auth.login({ scopes: ['profile'] })
     // expiresIn 以服务端返回为准，单位秒；当前后端签发 300 秒一次性 code
@@ -189,8 +202,6 @@ async function revokeAuthorizationFromUserAction() {
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 async function getLocalIdentityFromUserAction() {
-  await hbSDK.ready()
-
   try {
     const { appUserId } = await hbSDK.user.getLocalIdentity()
     return appUserId
@@ -252,7 +263,7 @@ onUnmounted(stopLifecycleEvents)
 | 事件                      | 触发时机                 | 典型用途                         |
 | ------------------------- | ------------------------ | -------------------------------- |
 | `launch`                  | 小程序首次启动           | 初始化一次性数据                 |
-| `ready`                   | SDK 可安全调用开放能力   | 标记 SDK 可用                    |
+| `ready`                   | SDK 握手成功瞬间         | 不可重放的边沿通知               |
 | `show`                    | 小程序页面展示           | 刷新可见态数据                   |
 | `hide`                    | 小程序页面隐藏           | 暂停轮询、暂停播放               |
 | `unload`                  | 当前小程序运行环境终止   | 清理资源并停止请求               |
@@ -266,11 +277,13 @@ onUnmounted(stopLifecycleEvents)
 
 ## 生命周期建议
 
-- 初始化开放能力前先 `await ready()`。
+- SDK 导入时自动启动握手，能力调用会自动等待；不要在用户手势回调中额外等待握手。
+- 当前握手状态只通过 `getHandshakeState()` 查询、通过 `onHandshakeStateChange()` 订阅；订阅会立即回放当前值并返回取消函数。
+- `ready` 事件只在握手成功瞬间派发，不会向晚订阅者重放，不能用于驱动按钮可用状态或替代握手状态 API。
 - UI 可见性相关逻辑放在 `show`、`hide`。
 - 使用 Host current-user APIs 的无网络小程序，可以在 `heybox_app_login_change` 后刷新本地状态。已开通网络权限的小程序使用 `auth.login()` 获取 code，并由开发者服务端维护业务会话。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
-- 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
+- 生命周期事件只派发给注册当时存在的监听器，不会重放；一次性 `launch` 信息应在页面启动阶段通过业务能力调用处理。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
 
 ## Error handling
@@ -327,7 +340,6 @@ type LoginViewState =
 
 async function loginFromUserAction(): Promise<LoginViewState> {
   try {
-    await hbSDK.ready()
     const result = await hbSDK.auth.login()
     await exchangeCodeWithDeveloperServer(result.code)
     return { status: 'ready' }
@@ -370,8 +382,6 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 export async function createServerSessionFromUserAction() {
-  await hbSDK.ready()
-
   try {
     const { code } = await hbSDK.auth.login({ scopes: ['profile'] })
     return await hbSDK.network.request({
@@ -399,9 +409,11 @@ async function handleSubmit() {
 }
 ```
 
+按钮在页面初始化时通过 `getHandshakeState()` 读取握手状态，并通过 `onHandshakeStateChange()` 持续更新；只在 `status === 'ready'` 时启用，组件卸载时调用订阅返回的取消函数。点击回调直接进入 `createServerSessionFromUserAction()`，不要在其中等待握手。完整接线见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start)。
+
 ## 注意事项
 
-完整授权契约见[用户身份与登录](/guide/auth)。本页只保留调用骨架。
+完整授权契约见[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)。本页只保留调用骨架。
 
 ## Community share recipe
 
@@ -415,9 +427,7 @@ async function handleSubmit() {
 普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
 
 ```ts
-import { ready, share } from '@heybox/hb-sdk'
-
-await ready()
+import { share } from '@heybox/hb-sdk'
 
 await share.showShareMenu({
   title: '本局战绩',
@@ -466,7 +476,6 @@ await share.screenshot({
 ```ts
 import hbSDK from '@heybox/hb-sdk'
 
-await hbSDK.ready()
 ```
 
 ## 测试环境注入 window
@@ -474,8 +483,21 @@ await hbSDK.ready()
 测试需要替换 bridge 或 window 时，应在应用测试边界 mock `@heybox/hb-sdk` 公开模块，不要从业务代码访问内部构造器。
 
 ```ts
+import type { MiniProgramSDKHandshakeStateHandler } from '@heybox/hb-sdk'
+
+const sdkMock = vi.hoisted(() => ({
+  state: { status: 'ready' as const },
+  unsubscribe: vi.fn(),
+}))
+
 vi.mock('@heybox/hb-sdk', () => ({
-  default: { ready: vi.fn(async () => undefined) },
+  default: {
+    getHandshakeState: vi.fn(() => sdkMock.state),
+    onHandshakeStateChange: vi.fn((handler: MiniProgramSDKHandshakeStateHandler) => {
+      handler(sdkMock.state)
+      return sdkMock.unsubscribe
+    }),
+  },
 }))
 ```
 

package/skill/references/safety-boundaries.md

@@ -10,7 +10,9 @@
 
 ## 关键约束
 
-- `ready()` 只表示 SDK 可调用，不表示已取得用户授权。
+- SDK 会自动等待与父容器完成握手；握手失败会在能力调用时抛出公开 SDK 错误。
+- 交互控件通过 `getHandshakeState()` 和 `onHandshakeStateChange()` 判断是否可用，只在 `status === 'ready'` 时启用；销毁时取消订阅。
+- `ready` 生命周期事件是不可重放的边沿通知，不代表可查询状态，也不能替代握手状态 API。
 - `auth.login({ scopes? })` 只返回 `{ code, expiresIn: 300, scopes }`；identity 隐式强制包含，code 只能提交给开发者服务端。
 - 需要授权 UI 时，`auth.login()` 必须来自可信用户手势，否则返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`。已授权时可以静默返回新 code。
 - `user.getSteamGameList()` 仅供未开通网络权限的小程序通过 Host 读取；已开通网络权限时返回 `SERVER_API_REQUIRED`，且授权码与 OpenAPI 不提供 Steam 游戏库 scope 或资源接口。

package/skill/references/smoke-evaluation.md

@@ -11,7 +11,9 @@ Use this template when evaluating whether an agent followed the hb-sdk skill.
 - [ ] Uses `@heybox/hb-sdk` root imports for iframe business code.
 - [ ] Uses `@heybox/hb-sdk/protocol` only for host/runtime/protocol tasks.
 - [ ] Uses `hb-sdk create`, `hb-sdk dev`, or `hb-sdk login` correctly for CLI tasks.
-- [ ] Calls or relies on `ready()` before capability calls.
+- [ ] Uses `getHandshakeState()` plus `onHandshakeStateChange()` for gesture-gated control state, enables only on `status === 'ready'`, and cleans up the subscription.
+- [ ] Treats the non-replayed `ready` lifecycle event as an edge notification that may repeat after a duplicate handshake, never as current state.
+- [ ] Calls gesture-gated capabilities directly from the original user action without waiting for handshake inside the handler.
 - [ ] Handles login, null user, and SDK errors safely.
 - [ ] Keeps CLI login cache separate from iframe SDK login state.
 - [ ] Avoids deep imports, token/cookie access, raw bridge mutation, second mock runtimes, and unsupported capabilities.

package/skill/scripts/sync-references.mjs

@@ -610,15 +610,39 @@ files.set(
     'apps/docs/hb-sdk/recipes/**',
   ])}## Positive examples
 
+### Gesture-gated control handshake state
+
+${fenced(
+  'ts',
+  `import hbSDK, { type MiniProgramSDKHandshakeState } from '@heybox/hb-sdk';
+
+let handshakeState: MiniProgramSDKHandshakeState = hbSDK.getHandshakeState();
+const stopHandshakeState = hbSDK.onHandshakeStateChange((state) => {
+  handshakeState = state;
+  setLoginButtonDisabled(state.status !== 'ready');
+});
+
+export function disposePage() {
+  stopHandshakeState();
+}
+
+export async function loginFromUserAction() {
+  if (handshakeState.status !== 'ready') return;
+  return hbSDK.auth.login();
+}
+
+function setLoginButtonDisabled(disabled: boolean) {
+  document.querySelector('button')?.toggleAttribute('disabled', disabled);
+}`,
+)}
+
 ### Local identity for a network-disabled mini-program
 
 ${fenced(
   'ts',
-  `import { ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+  `import { user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 export async function getLocalIdentityFromUserAction() {
-  await ready();
-
   try {
     return await user.getLocalIdentity();
   } catch (error) {
@@ -634,11 +658,9 @@ export async function getLocalIdentityFromUserAction() {
 
 ${fenced(
   'ts',
-  `import { auth, network, ready, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+  `import { auth, network, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 export async function createServerSessionFromUserAction() {
-  await ready();
-
   try {
     const result = await auth.login({ scopes: ['profile'] });
     await exchangeCodeWithDeveloperServer(result.code);
@@ -664,11 +686,9 @@ async function exchangeCodeWithDeveloperServer(code: string) {
 
 ${fenced(
   'ts',
-  `import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+  `import { network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
-  await ready();
-
   const response = await network.request<{ ok: boolean }>({
     url: 'https://api.example.com/demo',
     method: 'GET',
@@ -746,6 +766,8 @@ export default defineConfig({
 ## Negative examples
 
 - Do not import from internal hb-sdk implementation paths.
+- The non-replayed \`ready\` lifecycle event is only an edge notification. After a duplicate handshake it may repeat; never treat it as current state, and query or subscribe to the persistent state APIs instead.
+- Do not wait for handshake inside a gesture-gated click handler; keep the control disabled until the persistent state is \`ready\`.
 - Do not read cookies, tokens, phone numbers, or private credentials.
 - Do not create raw \`postMessage\` bridge envelopes in business pages.
 - Do not call unsupported storage delete/clear/info operations.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.7.0-alpha.2+skill.c5541658a22b",
+  "skillVersion": "0.7.0+skill.f8e5c8b940ab",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.7.0-alpha.2",
-    "compatibility": "0.7.0-alpha.2"
+    "version": "0.7.0",
+    "compatibility": "0.7.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-c5541658a22b5ef1a47a24dcdd617e59ef2a118858bedf547ac2833637f865b8"
+  "integrity": "sha256-f8e5c8b940abd2e9c14ae3407bc99ed1a8a8b5fb15a2577433226ec48f0dad22"
 }

package/types/core/client.d.ts

@@ -1,3 +1,4 @@
+import { type MiniProgramSDKHandshakeState, type MiniProgramSDKHandshakeStateHandler } from './handshake-state';
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityPayload, MiniProgramCapabilityResult } from '../protocol/capabilities';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 /**
@@ -40,18 +41,23 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private readonly handleSecurityPolicyViolation;
     private unsubscribeHistoryChanges?;
     private started;
-    private readySettled;
-    private readyPromise;
-    private resolveReady;
-    private rejectReady;
-    private readyTimer?;
+    private readonly handshakeState;
+    private handshakeSettled;
+    private handshakePromise;
+    private resolveHandshake;
+    private rejectHandshake;
+    private handshakeTimer?;
     private handshakeRetryTimer?;
     private destroyed;
     private runtimeUnavailable;
     private runtimeUnavailableError?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
-    ready(): Promise<void>;
+    waitForHandshake(): Promise<void>;
+    /** 获取当前握手状态。 */
+    getHandshakeState(): MiniProgramSDKHandshakeState;
+    /** 订阅握手状态，并立即接收当前状态。 */
+    onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
     /** 注册小程序事件监听。 */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /** 移除小程序事件监听。 */
@@ -68,9 +74,9 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private handleEvent;
     private handleResponse;
     private postMessage;
-    private resolveReadyOnce;
-    private failReady;
-    private clearReadyTimers;
+    private resolveHandshakeOnce;
+    private failHandshake;
+    private clearHandshakeTimers;
     private markRuntimeUnavailable;
     private getRuntimeUnavailableError;
     private rejectAllPending;

package/types/core/handshake-state.d.ts

@@ -0,0 +1,24 @@
+import type { HbMiniProgramSDKError } from './errors';
+/** SDK 与 Host 握手的持久状态。 */
+export type MiniProgramSDKHandshakeState = {
+    readonly status: 'connecting';
+} | {
+    readonly status: 'ready';
+} | {
+    readonly status: 'failed';
+    readonly error: HbMiniProgramSDKError;
+};
+/** SDK 握手状态变化处理函数。 */
+export type MiniProgramSDKHandshakeStateHandler = (state: MiniProgramSDKHandshakeState) => void;
+/** 保存握手终态，并向订阅者同步派发唯一一次状态迁移。 */
+export declare class MiniProgramSDKHandshakeStateStore {
+    private state;
+    private readonly handlers;
+    getState(): MiniProgramSDKHandshakeState;
+    subscribe(handler: MiniProgramSDKHandshakeStateHandler): () => void;
+    clear(): void;
+    settle(state: Extract<MiniProgramSDKHandshakeState, {
+        status: 'ready' | 'failed';
+    }>): void;
+    private notify;
+}

package/types/core/sdk.d.ts

@@ -10,6 +10,7 @@ import { type MiniProgramUiModule } from '../modules/ui';
 import { type MiniProgramDeviceModule } from '../modules/device';
 import { type MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
+import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
 /**
  * 外部小程序 SDK 实例。
  *
@@ -20,16 +21,7 @@ import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/
  * 多数业务页直接使用默认单例即可；只有在测试、多实例或需要定制运行参数时，
  * 才建议显式创建独立实例。
  *
- * @example
- * ```ts
- * import { createMiniProgramSDK } from '@heybox/hb-sdk'
- *
- * const sdk = createMiniProgramSDK({
- *   timeout: 15000,
- * })
- *
- * await sdk.ready()
- * ```
+ * 能力调用会自动等待与父容器完成握手。
  */
 export declare class MiniProgramSDK {
     private readonly client;
@@ -54,13 +46,10 @@ export declare class MiniProgramSDK {
     /** 云端数据相关开放能力。 */
     readonly cloud: MiniProgramCloudModule;
     constructor(options?: MiniProgramSDKOptions);
-    /**
-     * 等待 SDK 与父容器完成握手。
-     *
-     * @returns 当 bridge 握手成功后 resolve。
-     * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
-     */
-    ready(): Promise<void>;
+    /** 获取当前握手状态。 */
+    getHandshakeState(): MiniProgramSDKHandshakeState;
+    /** 订阅握手状态，并立即接收当前状态。 */
+    onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
     /**
      * 注册小程序生命周期或业务事件。
      *

package/types/core/singleton.d.ts

@@ -9,13 +9,11 @@ import type { MiniProgramUiModule } from '../modules/ui';
 import type { MiniProgramDeviceModule } from '../modules/device';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/**
- * 等待默认 SDK 实例与父容器完成握手。
- *
- * @returns 当默认 SDK 单例与父容器握手成功后 resolve。
- * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
- */
-export declare function ready(): Promise<void>;
+import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
+/** 获取默认 SDK 实例的当前握手状态。 */
+export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
+/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
 /**
  * 注册默认 SDK 实例的事件监听。
  *

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud, } from './core/singleton';
+export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
 export type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, LeaderboardEntry, LeaderboardOrder, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, } from './modules/cloud';
@@ -11,9 +12,10 @@ export type { MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNe
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, MiniProgramUiModule, ShowLoadingPayload, ShowLoadingResult, ShowToastPayload, ShowToastResult, } from './modules/ui';
 export type { MiniProgramDeviceModule, MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult, } from './modules/device';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
-import { off, on, ready } from './core/singleton';
+import { getHandshakeState, off, on, onHandshakeStateChange } from './core/singleton';
 declare const hbSDK: {
-    ready: typeof ready;
+    getHandshakeState: typeof getHandshakeState;
+    onHandshakeStateChange: typeof onHandshakeStateChange;
     on: typeof on;
     off: typeof off;
     auth: import(".").MiniProgramAuthModule;

package/types/protocol/trusted-user-gesture.d.ts

@@ -0,0 +1,6 @@
+export interface TrustedIframeUserGestureEnvironment {
+    readonly activeElement: Element | null;
+    readonly userActivation?: Pick<UserActivation, 'isActive'>;
+}
+/** 按当前浏览器消息、用户激活和目标 iframe 焦点生成请求级可信手势快照。 */
+export declare function computeTrustedIframeUserGesture(event: Pick<MessageEvent, 'isTrusted'>, iframe: HTMLIFrameElement, environment?: TrustedIframeUserGestureEnvironment): boolean;

package/types/protocol/types.d.ts

@@ -109,7 +109,7 @@ export interface MiniProgramEventPayloadMap {
         /** 父容器最终加载到 iframe 的 URL。 */
         url?: string;
     };
-    /** SDK 已可安全调用开放能力。 */
+    /** SDK 握手成功时派发的不可重放边沿通知，不是持久状态；需要当前状态时使用 `getHandshakeState()` / `onHandshakeStateChange()`。 */
     ready: {
         /** 事件时间戳。 */
         timestamp: number;

package/types/protocol.d.ts

@@ -1,5 +1,6 @@
 export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
+export { computeTrustedIframeUserGesture, type TrustedIframeUserGestureEnvironment, } from './protocol/trusted-user-gesture';
 export { isManagedMiniProgramRuntimePermissionKey, parseMiniProgramRuntimePermissions } from './protocol/runtime-permissions';
 export { isOfficialMiniProgramNetworkUrl, isProtectedMiniProgramNetworkPath, MINI_PROGRAM_NETWORK_PROTECTED_PATHS, normalizeMiniProgramNetworkPathname, } from './protocol/network-policy';
 export type { MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionStatus, MiniProgramRuntimePermissionsSnapshot, ParsedMiniProgramRuntimePermissions, } from './protocol/runtime-permissions';