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

package/dist/protocol.esm.js

@@ -30,6 +30,24 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+function readBrowserEnvironment() {
+    try {
+        return {
+            activeElement: globalThis.document?.activeElement ?? null,
+            userActivation: globalThis.navigator?.userActivation,
+        };
+    }
+    catch {
+        return { activeElement: null };
+    }
+}
+/** 按当前浏览器消息、用户激活和目标 iframe 焦点生成请求级可信手势快照。 */
+function computeTrustedIframeUserGesture(event, iframe, environment = readBrowserEnvironment()) {
+    return (event.isTrusted === true
+        && environment.userActivation?.isActive === true
+        && environment.activeElement === iframe);
+}
+
 const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
 /**
  * 判断 permission key 是否由 Runtime 权限快照管理。
@@ -433,4 +451,4 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     },
 ];
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NETWORK_PROTECTED_PATHS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_LOCAL_IDENTITY_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isOfficialMiniProgramNetworkUrl, isProtectedMiniProgramNetworkPath, normalizeMiniProgramNetworkPathname, parseMiniProgramRuntimePermissions };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_NETWORK_PROTECTED_PATHS, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_LOCAL_IDENTITY_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, computeTrustedIframeUserGesture, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isOfficialMiniProgramNetworkUrl, isProtectedMiniProgramNetworkPath, normalizeMiniProgramNetworkPathname, parseMiniProgramRuntimePermissions };

package/dist/templates/vue3-vite-ts/src/App.vue

@@ -3,15 +3,11 @@
     <section class="card">
       <p class="eyebrow">Heybox Mini Program</p>
       <h1><%= projectName %></h1>
-      <p class="intro">
-        这个模板只保留最小接入示例：等待 SDK ready，并由用户主动选择受支持的操作。
-      </p>
+      <p class="intro">这个模板只保留最小接入示例：SDK 会自动完成初始化，由用户主动选择受支持的操作。</p>
 
       <p class="status" data-testid="status">{{ status }}</p>
 
-      <button type="button" :disabled="loading" data-testid="login" @click="login">
-        获取授权码
-      </button>
+      <button type="button" :disabled="loading || !sdkReady" data-testid="login" @click="login">获取授权码</button>
 
       <pre data-testid="output">{{ output }}</pre>
     </section>
@@ -20,28 +16,37 @@
 
 <script setup lang="ts">
 import hbSDK from '@heybox/hb-sdk';
-import { onMounted, ref } from 'vue';
+import type { MiniProgramSDKHandshakeState } from '@heybox/hb-sdk';
+import { onBeforeUnmount, ref } from 'vue';
 import { loginAndExchangeAuthorizationCode } from './auth-handoff';
 
 const loading = ref(false);
+const sdkReady = ref(false);
 const status = ref('正在连接 SDK...');
-const output = ref('连接后请选择操作。');
+const output = ref('请选择操作。');
 
-onMounted(() => {
-  void connectSDK();
-});
+function updateHandshakeState(state: MiniProgramSDKHandshakeState) {
+  if (state.status === 'connecting') {
+    sdkReady.value = false;
+    status.value = '正在连接 SDK...';
+    return;
+  }
 
-async function connectSDK() {
-  try {
-    await hbSDK.ready();
-    status.value = 'SDK 已连接';
-    output.value = '请选择操作。';
-  } catch (error) {
+  if (state.status === 'failed') {
+    sdkReady.value = false;
     status.value = 'SDK 连接失败';
-    output.value = readErrorMessage(error);
+    output.value = readErrorMessage(state.error);
+    return;
   }
+
+  sdkReady.value = true;
+  status.value = 'SDK 已连接';
+  output.value = '请选择操作。';
 }
 
+const stopHandshakeState = hbSDK.onHandshakeStateChange(updateHandshakeState);
+onBeforeUnmount(stopHandshakeState);
+
 async function login() {
   loading.value = true;
   status.value = 'auth.login 调用中...';
@@ -63,6 +68,11 @@ async function login() {
 }
 
 function readErrorMessage(error: unknown) {
-  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+
+  const code = 'code' in error && typeof error.code === 'string' ? `\ncode: ${error.code}` : '';
+  return `${error.name}: ${error.message}${code}`;
 }
 </script>

package/dist/templates/vue3-vite-ts/src/__tests__/App.spec.ts

@@ -3,9 +3,37 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import App from '../App.vue';
 
 const sdkMock = vi.hoisted(() => ({
+  ...(() => {
+    type HandshakeState = { status: 'connecting' } | { status: 'ready' } | { status: 'failed'; error: Error & { code: string } };
+
+    let state: HandshakeState = { status: 'connecting' };
+    const handlers = new Set<(nextState: HandshakeState) => void>();
+    const unsubscribe = vi.fn();
+
+    return {
+      getHandshakeState: vi.fn(() => state),
+      onHandshakeStateChange: vi.fn((handler: (nextState: HandshakeState) => void) => {
+        handlers.add(handler);
+        handler(state);
+        return () => {
+          unsubscribe();
+          handlers.delete(handler);
+        };
+      }),
+      reset(nextState: HandshakeState = { status: 'connecting' }) {
+        state = nextState;
+        handlers.clear();
+        unsubscribe.mockReset();
+      },
+      setHandshakeState(nextState: HandshakeState) {
+        state = nextState;
+        handlers.forEach((handler) => handler(state));
+      },
+      unsubscribe,
+    };
+  })(),
   login: vi.fn(),
   networkRequest: vi.fn(),
-  ready: vi.fn(),
 }));
 
 vi.mock('@heybox/hb-sdk', () => ({
@@ -16,34 +44,79 @@ vi.mock('@heybox/hb-sdk', () => ({
     network: {
       request: sdkMock.networkRequest,
     },
-    ready: sdkMock.ready,
+    getHandshakeState: sdkMock.getHandshakeState,
+    onHandshakeStateChange: sdkMock.onHandshakeStateChange,
   },
 }));
 
 describe('App', () => {
   beforeEach(() => {
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     vi.unstubAllEnvs();
 
-    sdkMock.ready.mockResolvedValue(undefined);
+    sdkMock.reset();
     sdkMock.login.mockResolvedValue({ code: 'authorization_code', expiresIn: 300, scopes: ['identity'] });
     sdkMock.networkRequest.mockResolvedValue({ status: 200 });
   });
 
-  it('only waits for SDK readiness during startup', async () => {
+  it('keeps actions disabled while the SDK is connecting', () => {
+    const wrapper = mount(App);
+
+    expect(sdkMock.getHandshakeState).not.toHaveBeenCalled();
+    expect(wrapper.get('[data-testid="status"]').text()).toBe('正在连接 SDK...');
+    expect(wrapper.get<HTMLButtonElement>('[data-testid="login"]').element.disabled).toBe(true);
+  });
+
+  it('enables actions when the handshake becomes ready', async () => {
     const wrapper = mount(App);
+
+    sdkMock.setHandshakeState({ status: 'ready' });
     await flushPromises();
 
-    expect(sdkMock.ready).toHaveBeenCalledTimes(1);
-    expect(sdkMock.login).not.toHaveBeenCalled();
     expect(wrapper.get('[data-testid="status"]').text()).toBe('SDK 已连接');
     expect(wrapper.get('[data-testid="output"]').text()).toContain('请选择操作');
+    expect(wrapper.get<HTMLButtonElement>('[data-testid="login"]').element.disabled).toBe(false);
+  });
+
+  describe('late mount', () => {
+    it('renders an already-ready handshake immediately', () => {
+      sdkMock.reset({ status: 'ready' });
+
+      const wrapper = mount(App);
+
+      expect(wrapper.get('[data-testid="status"]').text()).toBe('SDK 已连接');
+      expect(wrapper.get<HTMLButtonElement>('[data-testid="login"]').element.disabled).toBe(false);
+    });
+
+    it('renders the original failed handshake details immediately', () => {
+      const error = Object.assign(new Error('Host 未响应'), {
+        code: 'HANDSHAKE_TIMEOUT',
+        name: 'HbMiniProgramSDKError',
+      });
+      sdkMock.reset({ status: 'failed', error });
+
+      const wrapper = mount(App);
+
+      expect(wrapper.get('[data-testid="status"]').text()).toBe('SDK 连接失败');
+      expect(wrapper.get<HTMLButtonElement>('[data-testid="login"]').element.disabled).toBe(true);
+      expect(wrapper.get('[data-testid="output"]').text()).toContain('HbMiniProgramSDKError');
+      expect(wrapper.get('[data-testid="output"]').text()).toContain('Host 未响应');
+      expect(wrapper.get('[data-testid="output"]').text()).toContain('HANDSHAKE_TIMEOUT');
+    });
+  });
+
+  it('stops observing handshake state after unmount', () => {
+    const wrapper = mount(App);
+
+    wrapper.unmount();
+
+    expect(sdkMock.unsubscribe).toHaveBeenCalledTimes(1);
   });
 
   it('hands the authorization code to the developer server without rendering it', async () => {
     vi.stubEnv('VITE_HEYBOX_AUTH_EXCHANGE_URL', 'https://developer.example.com/api/heybox/exchange');
+    sdkMock.reset({ status: 'ready' });
     const wrapper = mount(App);
-    await flushPromises();
 
     await wrapper.get('[data-testid="login"]').trigger('click');
     await flushPromises();
@@ -61,8 +134,8 @@ describe('App', () => {
   });
 
   it('does not request a code when the developer server is not configured', async () => {
+    sdkMock.reset({ status: 'ready' });
     const wrapper = mount(App);
-    await flushPromises();
 
     await wrapper.get('[data-testid="login"]').trigger('click');
     await flushPromises();

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0-alpha.5';
+    : '0.7.0-alpha.9';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0-alpha.5';
+    : '0.7.0-alpha.9';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.7.0-alpha.5",
+  "version": "0.7.0-alpha.9",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hb-sdk
-description: Uses @heybox/hb-sdk and its hb-sdk CLI to build, debug, review, and publish workshop mini-programs for the Heybox App. Use for public SDK APIs, lifecycle events, hb-sdk create/dev/login/doctor, browser Mock and device debugging, or publishing checks. Don't use for private credentials, internal Heybox client protocols, private package paths, or non-Heybox SDKs.
+description: Uses @heybox/hb-sdk and its hb-sdk CLI to build, debug, review, and publish workshop mini-programs for the Heybox App. Use for public SDK APIs, persistent handshake state, lifecycle events, hb-sdk create/dev/login/doctor, browser Mock and device debugging, or publishing checks. Don't use for private credentials, internal Heybox client protocols, private package paths, or non-Heybox SDKs.
 ---
 
 # hb-sdk Agent Procedure
@@ -38,17 +38,18 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 
 ## Step 4: Implement workshop mini-program code
 
-1. Call `await ready()` or `await hbSDK.ready()` near page startup when the page uses SDK capabilities.
+1. Import the root package eagerly; the SDK starts its handshake automatically and capability calls wait for it internally.
 2. For a network-enabled mini-program, use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
 3. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
 4. For a network-disabled mini-program, call `user.getLocalIdentity()` from a trusted user action to obtain `{ appUserId }`, because first login or identity consent may require UI. It cannot obtain a code or call OpenAPI.
 5. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
 6. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
-7. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
-8. Use the default SDK instance exposed by the root package.
-9. When authorization UI is required, call `auth.login()` or `user.getLocalIdentity()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
-10. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` and `user.getLocalIdentity()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
-11. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
+7. Use `getHandshakeState()` for the current persistent handshake state and `onHandshakeStateChange()` for an immediate replay plus future changes. Cancel the returned subscription when the page or component unmounts.
+8. Treat the non-replayed `ready` lifecycle event only as an edge notification. After a duplicate handshake it may repeat, so never use it as state or as the source for enabling a late-mounted control.
+9. Use the default SDK instance exposed by the root package. For gesture-gated controls, initialize from the current handshake state, subscribe to changes, and enable the control only when `status === 'ready'`. Keep calls such as `auth.login()` in the original user-action callback; do not wait for handshake inside that callback.
+10. When authorization UI is required, call `auth.login()` or `user.getLocalIdentity()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
+11. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` and `user.getLocalIdentity()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
+12. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
 
 ## Step 5: Use CLI workflows
 

package/skill/references/api-protocol.md

@@ -26,6 +26,10 @@ export {
   SDK_HANDSHAKE_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,
@@ -207,7 +211,7 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 51 | 52 | 0 |
-| Protocol API | 0 | 6 | 46 | 65 | 31 |
+| Root API | 2 | 4 | 51 | 54 | 0 |
+| Protocol API | 0 | 7 | 47 | 65 | 31 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.7.0-alpha.2`
+- Version at generation time: `0.7.0-alpha.9`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -33,7 +33,23 @@
 
 ```ts
 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 {
@@ -145,10 +161,26 @@ export type {
   ReloadResult,
 } from './modules/navigation';
 
-import { auth, cloud, device, navigation, network, off, on, ready, share, storage, ui, viewport, user } from './core/singleton';
+import {
+  auth,
+  cloud,
+  device,
+  getHandshakeState,
+  navigation,
+  network,
+  off,
+  on,
+  onHandshakeStateChange,
+  share,
+  storage,
+  ui,
+  viewport,
+  user,
+} from './core/singleton';
 
 const hbSDK = {
-  ready,
+  getHandshakeState,
+  onHandshakeStateChange,
   on,
   off,
   auth,
@@ -360,7 +392,26 @@ hb-sdk build [--env <name>] [--verbose]
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 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` 生命周期事件只在握手成功瞬间派发且不会重放，不能作为当前状态来源。
 
 ## 未开通网络权限
 
@@ -370,8 +421,6 @@ hb-sdk build [--env <name>] [--verbose]
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 async function getLocalIdentityFromUserAction() {
-  await hbSDK.ready()
-
   try {
     const { appUserId } = await hbSDK.user.getLocalIdentity()
     return appUserId
@@ -390,11 +439,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'] })
@@ -413,11 +462,7 @@ async function loginFromUserAction() {
 }
 ```
 
-返回值与边界以[用户身份与登录](/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
-
-## ready 的含义
-
-`ready()` 只表示 SDK 已就绪，可以安全调用开放能力。它不表示已经取得用户授权，也不返回用户身份。
+返回值与边界以[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
 
 ## 默认单例
 
@@ -475,7 +520,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' }
@@ -511,7 +555,7 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 ## 能力概览
 
-除 `ready()` 外，SDK 还提供 `on()` 和 `off()` 处理前后台、登录态等生命周期事件。
+SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握手状态，并通过 `on()` / `off()` 处理前后台、登录态等生命周期事件。
 
 | 模块         | 用途                                                         |
 | ------------ | ------------------------------------------------------------ |
@@ -561,7 +605,7 @@ onUnmounted(stopLifecycleEvents)
 | 事件                      | 触发时机                 | 典型用途                         |
 | ------------------------- | ------------------------ | -------------------------------- |
 | `launch`                  | 小程序首次启动           | 初始化一次性数据                 |
-| `ready`                   | SDK 可安全调用开放能力   | 标记 SDK 可用                    |
+| `ready`                   | SDK 握手成功瞬间         | 不可重放的边沿通知               |
 | `show`                    | 小程序页面展示           | 刷新可见态数据                   |
 | `hide`                    | 小程序页面隐藏           | 暂停轮询、暂停播放               |
 | `unload`                  | 当前小程序运行环境终止   | 清理资源并停止请求               |
@@ -575,11 +619,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 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
 
 ## 云端排行榜

package/skill/references/examples.md

@@ -9,14 +9,37 @@
 - apps/docs/hb-sdk/recipes/**
 ## Positive examples
 
+### Gesture-gated control handshake state
+
+```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
 
 ```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) {
@@ -31,11 +54,9 @@ export async function getLocalIdentityFromUserAction() {
 ### Developer server session for a network-enabled mini-program
 
 ```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);
@@ -60,11 +81,9 @@ async function exchangeCodeWithDeveloperServer(code: string) {
 ### Network request
 
 ```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',
@@ -138,6 +157,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.