k2-im 0.1.20 → 0.1.22

package/dist/browser.js

@@ -1 +1 @@
-export{A as createLazyBrowserApiProtocolClient}from'./chunk-4RG5NHIL.js';import'./chunk-ZDD7A2BS.js';import'./chunk-WOT6VMZA.js';
+export{A as createLazyBrowserApiProtocolClient}from'./chunk-GZEX4V3P.js';import'./chunk-VKNZ76EP.js';import'./chunk-WOT6VMZA.js';

package/dist/chat-kit-pinia.d.ts

@@ -126,12 +126,17 @@ type LastMessageSummary = {
  *
  * 只给结构化计数与配文，**不在这里拼「2 张照片, 1 个视频」这种文案**——中英文的量词、复数与
  * 连接符各不相同，必须由 im-i18n 按 locale 组装。`caption` 非空时宿主优先显示配文（对齐三端）。
+ *
+ * `firstItemKind` 是第一项是照片还是视频。有配文时列表显示的是配文，光看计数无法决定该配
+ * 照片图标还是视频图标，三端统一按第一项取（对齐 iOS `IMMediaAlbumMessageBody`）。
+ * 入站解析后所有项都被丢弃时缺省，宿主据此不显示类型图标。
  */
  | {
     kind: 'mediaAlbum';
     imageCount: number;
     videoCount: number;
     caption?: string;
+    firstItemKind?: 'image' | 'video';
 } | {
     kind: 'encrypted';
 } | {
@@ -4036,12 +4041,16 @@ type ConversationLastMessageSummary = {
  *
  * 只给计数与配文，数量文案由宿主经 im-i18n 按 locale 组装；有配文时优先显示配文。
  * 两个计数都为 0 表示入站正文残缺（所有项都无法解析），宿主应按未知正文处理。
+ *
+ * `firstItemKind` 是第一项是照片还是视频。有配文时列表显示的是配文，光看计数决定不了该配
+ * 照片图标还是视频图标，三端统一按第一项取；正文残缺时缺省，宿主据此不显示类型图标。
  */
  | {
     kind: 'mediaAlbum';
     imageCount: number;
     videoCount: number;
     caption?: string;
+    firstItemKind?: 'image' | 'video';
 } | {
     kind: 'encrypted';
 } | {
@@ -4417,6 +4426,12 @@ interface ConversationOpenOptions {
      * 后续 read 事件或新消息不会移动分隔线。
      */
     initialPosition?: ConversationInitialPosition;
+    /**
+     * 默认 blocking 等待整个初始窗口；local-first 在本地窗口可读后返回，远端补齐和未读定位后台继续。
+     * local-first 调用方必须订阅 loading/error：加载失败保留本地窗口并写入 error，允许通过 history 重试；
+     * loading 结束前不要提交可见已读或最终首屏定位。本地存储打开失败仍会拒绝 openConversation。
+     */
+    initialLoad?: 'blocking' | 'local-first';
 }
 /**
  * 产品会话的连续窗口快照；协议 cursor、窗口 id 与 generation 始终保持在 SDK 内部。
@@ -4928,6 +4943,31 @@ interface ImMediaTasksApi {
      * @throws 持久缓存读取失败时抛 `IM_SDK_MEDIA_CACHE_READ_FAILED`，不能把存储故障伪装成 cache miss。
      */
     getCached: (message: ImMessageRef) => Promise<Blob | null>;
+    /**
+     * 为宿主手里的**本地**图片/视频文件预读展示元信息：尺寸、视频时长、视频首帧封面的 JPEG 字节。
+     *
+     * 给「发送前预览」这类场景用：宿主要在用户还没点发送时就把缩略图画出来，而浏览器读不出视频的
+     * 首帧——`<video preload="metadata">` 在 iOS Safari 上只加载元信息、**不解码任何一帧**，
+     * 拿它当缩略图会得到一个空白格子（还会白占一路解码）。
+     *
+     * 返回的对象可以**原样**作为 `localPreviewMetadata` 交给 `sendImage` / `sendVideo` /
+     * `sendMediaAlbum`：发送链路会跳过重复解码，上传中的气泡也从第一帧就有封面。
+     * 视频封面用的就是发送链路那套规格（长边 320、JPEG），所以弹层里看到的与最终发出去的是同一张。
+     *
+     * @param input.kind 按文件类型选解码路径；`'video'` 才会抽首帧与读时长。
+     * @param input.file 本地文件；不会被上传，也不会进任何缓存。
+     * @param input.signal 宿主放弃时中止解码（例如预览弹层被关掉）。
+     * @returns 解码成功返回元信息；**浏览器确实读不出这个文件**（格式不支持、解码超时）时返回 `null`，
+     * 调用方应当显式呈现「这个文件读不出来」，不要拿空白格子糊过去。失败原因会记入 SDK 结构化诊断。
+     * @throws 宿主通过 `signal` 中止时抛 `AbortError`——那是调用方自己的取消，不能和「读不出来」混为一谈。
+     * @throws runtime 已 logout/dispose 时抛 `IM_SDK_MEDIA_RUNTIME_INACTIVE`；
+     * 未装配预览端口时抛 `IM_SDK_MEDIA_PREVIEW_UNAVAILABLE`，不静默返回 `null`。
+     */
+    prepareLocalPreview: <TKind extends 'image' | 'video'>(input: {
+        kind: TKind;
+        file: Blob;
+        signal?: AbortSignal;
+    }) => Promise<(TKind extends 'video' ? VideoPreviewMetadata : ImagePreviewMetadata) | null>;
 }
 
 /**
@@ -5376,14 +5416,8 @@ interface ImSearchApi {
     readonly messages: ImMessageSearchApi;
 }
 
-/**
- * 会话收藏稳定产品门面。
- *
- * 本模块不缓存服务端列表；每次 list/add/delete 都以当前账号 provider 为准。
- * 收藏快照与原聊天消息解耦：原消息删除、撤回或编辑不会回写收藏。
- */
-
 type ImSessionFavoriteItem = Readonly<ImSessionFavoriteItem$1>;
+
 /** 产品层会话收藏 API。 */
 interface ImSessionFavoritesApi {
     list: () => Promise<readonly ImSessionFavoriteItem[]>;
@@ -6712,22 +6746,23 @@ declare function getImChatKitContext(pinia: Pinia): ImChatKitContext;
 /** 释放指定 Pinia 下全部 IM Store 和 Runtime；未安装时不执行任何操作。 */
 declare function disposeImChatKit(pinia: Pinia): void;
 
-type ProductConversationRef$5 = ConversationRef<ProductHandleConversationType>;
+type ProductConversationRef$6 = ConversationRef<ProductHandleConversationType>;
 /** 宿主可据此决定反馈的安全错误；底层 cause/details 只允许进入统一诊断。 */
 type ImConversationActivationError = Readonly<Omit<ImSdkErrorShape, 'cause' | 'details'>>;
 /**
  * 共享会话激活的稳定结果。
  *
- * 成功后宿主才提交路由/面板选择；`stale` 表示该意图已被更新点击、切账号或 Context dispose 取代。
+ * 成功表示已绑定目标句柄，后台历史加载状态仍从 Thread Store 读取；宿主可提前展示路由外壳与骨架。
+ * `stale` 表示该意图已被更新点击、切账号或 Context dispose 取代。
  */
 type ImConversationActivationResult = Readonly<{
     ok: true;
     status: 'opened';
-    conversation: ProductConversationRef$5;
+    conversation: ProductConversationRef$6;
 } | {
     ok: false;
     reason: 'draft-save-failed' | 'open-failed';
-    conversation: ProductConversationRef$5;
+    conversation: ProductConversationRef$6;
     error: ImConversationActivationError;
 } | {
     ok: false;
@@ -6736,29 +6771,32 @@ type ImConversationActivationResult = Readonly<{
 }>;
 /** 按单个 Pinia 串联 Composer 与 Thread Store 的无 UI coordinator。 */
 interface ImConversationActivationCoordinator {
-    activate: (conversation: ConversationRef) => Promise<ImConversationActivationResult>;
+    /** signal 取消本次在途激活；保留已显示线程，不影响之后开始的激活。 */
+    activate: (conversation: ConversationRef, options?: {
+        signal?: AbortSignal;
+    }) => Promise<ImConversationActivationResult>;
 }
 /**
  * 取得当前 Vue setup 或显式 Pinia 的会话激活 coordinator。
  *
  * coordinator 没有响应式产品状态；每个 Pinia 只持有 operation epoch，用于在草稿 flush 和 Thread open
- * 之间判定新点击、账号 generation 变化与 dispose。调用方不得根据 Thread 中间态提前提交宿主选择。
+ * 之间判定新点击、账号 generation 变化与 dispose。宿主可先展示目标页，但只有 exact handle 成功后才能展示线程内容。
  */
 declare function useImConversationActivationCoordinator(pinia?: Pinia): ImConversationActivationCoordinator;
 
-type ProductConversationRef$4 = ConversationRef<ProductConversationListType>;
+type ProductConversationRef$5 = ConversationRef<ProductConversationListType>;
 /** 删除失败时提供给宿主映射反馈的安全错误，不暴露底层 cause/details。 */
 type ImConversationDeletionError = Readonly<Omit<ImSdkErrorShape, 'cause' | 'details'>>;
 /** local-only 删除的稳定结果；成功只代表 SDK 已同步提交当前内存删除，不代表 durable 存储已完成。 */
 type ImConversationDeletionResult = Readonly<{
     ok: true;
     status: 'deleted';
-    conversation: ProductConversationRef$4;
+    conversation: ProductConversationRef$5;
     activeConversationCleared: boolean;
 } | {
     ok: false;
     reason: 'delete-failed';
-    conversation: ProductConversationRef$4;
+    conversation: ProductConversationRef$5;
     error: ImConversationDeletionError;
 } | {
     ok: false;
@@ -6777,7 +6815,7 @@ interface ImConversationDeletionCoordinator {
  */
 declare function useImConversationDeletionCoordinator(pinia?: Pinia): ImConversationDeletionCoordinator;
 
-type ProductConversationRef$3 = ConversationRef<ProductConversationListType>;
+type ProductConversationRef$4 = ConversationRef<ProductConversationListType>;
 type ImConversationListMutationOperation = 'set-pinned' | 'set-muted' | 'mark-read' | 'mark-unread' | 'delete-local';
 /** 会话列表动作失败时返回给宿主的安全错误；底层 cause/details 不跨出共享 Store。 */
 type ImConversationListActionError = Readonly<Omit<ImSdkErrorShape, 'cause' | 'details'>>;
@@ -6804,11 +6842,11 @@ interface ImConversationListStore {
     start: () => void;
     reset: () => void;
     refresh: () => Promise<ImConversationListRefreshResult>;
-    setPinned: (ref: ProductConversationRef$3, pinned: boolean) => ImConversationListMutationResult;
-    setMuted: (ref: ProductConversationRef$3, muted: boolean) => Promise<ImConversationListMutationResult>;
-    markRead: (ref: ProductConversationRef$3) => Promise<ImConversationListMutationResult>;
-    markUnread: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
-    deleteLocal: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
+    setPinned: (ref: ProductConversationRef$4, pinned: boolean) => ImConversationListMutationResult;
+    setMuted: (ref: ProductConversationRef$4, muted: boolean) => Promise<ImConversationListMutationResult>;
+    markRead: (ref: ProductConversationRef$4) => Promise<ImConversationListMutationResult>;
+    markUnread: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
+    deleteLocal: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
     dispose: () => void;
 }
 /**
@@ -6820,17 +6858,17 @@ interface ImConversationListStore {
 type ImConversationListMutationResult = Readonly<{
     ok: true;
     operation: ImConversationListMutationOperation;
-    conversation: ProductConversationRef$3;
+    conversation: ProductConversationRef$4;
 } | {
     ok: false;
     operation: ImConversationListMutationOperation;
     reason: 'stale';
-    conversation: ProductConversationRef$3;
+    conversation: ProductConversationRef$4;
 } | {
     ok: false;
     operation: ImConversationListMutationOperation;
     reason: 'failed';
-    conversation: ProductConversationRef$3;
+    conversation: ProductConversationRef$4;
     error: ImConversationListActionError;
 }>;
 declare function defineImConversationListStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-conversation-list", Pick<{
@@ -6841,11 +6879,11 @@ declare function defineImConversationListStore(pinia: Pinia): pinia.StoreDefinit
     start: () => void;
     reset: () => void;
     refresh: () => Promise<ImConversationListRefreshResult>;
-    setPinned: (ref: ProductConversationRef$3, pinned: boolean) => ImConversationListMutationResult;
-    setMuted: (ref: ProductConversationRef$3, muted: boolean) => Promise<ImConversationListMutationResult>;
-    markRead: (ref: ProductConversationRef$3) => Promise<ImConversationListMutationResult>;
-    markUnread: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
-    deleteLocal: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
+    setPinned: (ref: ProductConversationRef$4, pinned: boolean) => ImConversationListMutationResult;
+    setMuted: (ref: ProductConversationRef$4, muted: boolean) => Promise<ImConversationListMutationResult>;
+    markRead: (ref: ProductConversationRef$4) => Promise<ImConversationListMutationResult>;
+    markUnread: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
+    deleteLocal: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
     dispose: () => void;
 }, any>, Pick<{
     items: any;
@@ -6855,11 +6893,11 @@ declare function defineImConversationListStore(pinia: Pinia): pinia.StoreDefinit
     start: () => void;
     reset: () => void;
     refresh: () => Promise<ImConversationListRefreshResult>;
-    setPinned: (ref: ProductConversationRef$3, pinned: boolean) => ImConversationListMutationResult;
-    setMuted: (ref: ProductConversationRef$3, muted: boolean) => Promise<ImConversationListMutationResult>;
-    markRead: (ref: ProductConversationRef$3) => Promise<ImConversationListMutationResult>;
-    markUnread: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
-    deleteLocal: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
+    setPinned: (ref: ProductConversationRef$4, pinned: boolean) => ImConversationListMutationResult;
+    setMuted: (ref: ProductConversationRef$4, muted: boolean) => Promise<ImConversationListMutationResult>;
+    markRead: (ref: ProductConversationRef$4) => Promise<ImConversationListMutationResult>;
+    markUnread: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
+    deleteLocal: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
     dispose: () => void;
 }, any>, Pick<{
     items: any;
@@ -6869,11 +6907,11 @@ declare function defineImConversationListStore(pinia: Pinia): pinia.StoreDefinit
     start: () => void;
     reset: () => void;
     refresh: () => Promise<ImConversationListRefreshResult>;
-    setPinned: (ref: ProductConversationRef$3, pinned: boolean) => ImConversationListMutationResult;
-    setMuted: (ref: ProductConversationRef$3, muted: boolean) => Promise<ImConversationListMutationResult>;
-    markRead: (ref: ProductConversationRef$3) => Promise<ImConversationListMutationResult>;
-    markUnread: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
-    deleteLocal: (ref: ProductConversationRef$3) => ImConversationListMutationResult;
+    setPinned: (ref: ProductConversationRef$4, pinned: boolean) => ImConversationListMutationResult;
+    setMuted: (ref: ProductConversationRef$4, muted: boolean) => Promise<ImConversationListMutationResult>;
+    markRead: (ref: ProductConversationRef$4) => Promise<ImConversationListMutationResult>;
+    markUnread: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
+    deleteLocal: (ref: ProductConversationRef$4) => ImConversationListMutationResult;
     dispose: () => void;
 }, any>>;
 type InternalImConversationListStore = ReturnType<ReturnType<typeof defineImConversationListStore>>;
@@ -7033,7 +7071,7 @@ type ImExpressionStore = Store<'k2-im-expression', ImExpressionStoreState, ImExp
  */
 declare function useImExpressionStore(pinia?: Pinia): ImExpressionStore;
 
-type ProductConversationRef$2 = ConversationRef<ProductHandleConversationType>;
+type ProductConversationRef$3 = ConversationRef<ProductHandleConversationType>;
 /** 返回最新页失败时给宿主的安全错误；底层 cause/details 只进入统一诊断。 */
 type ImHistoryReturnError = Readonly<Omit<ImSdkErrorShape, 'cause' | 'details'>>;
 /** 历史窗口发送后的稳定结算；宿主只在 `applied` 时执行自己的 DOM 滚动。 */
@@ -7041,10 +7079,10 @@ type ImHistoryReturnResult = Readonly<{
     status: 'not-needed';
 } | {
     status: 'applied' | 'stale';
-    conversation: ProductConversationRef$2;
+    conversation: ProductConversationRef$3;
 } | {
     status: 'failed';
-    conversation: ProductConversationRef$2;
+    conversation: ProductConversationRef$3;
     error: ImHistoryReturnError;
 }>;
 /** 保留原发送动作的返回值，并把独立的历史窗口结算交给宿主消费。 */
@@ -7064,30 +7102,6 @@ interface ImHistoryReturnAfterSendCoordinator {
  */
 declare function useImHistoryReturnAfterSendCoordinator(pinia?: Pinia): ImHistoryReturnAfterSendCoordinator;
 
-/**
- * 为页面展示当前账号的媒体上传/下载进度，并提供取消、重试和重新选择原文件入口。
- *
- * 【状态从哪里来】
- * Store 订阅 SDK 的完整媒体任务列表，向页面提供任务、当前线程每条消息的上传百分比、是否还在排队等
- * 上传槽位、是否正在完成最后处理以及稳定错误。传输、任务状态、消息状态、取消和重试都由 SDK 维护；Store 不模拟进度，也不
- * 创建第二套上传队列。
- *
- * 【提供的能力】
- * - `start` / `reset`：开始监听当前 SDK Client，或切账号时退订并清空旧任务。
- * - `cancel` / `retry`：按 SDK 给出的任务 ID 取消或重试。
- * - `cancelUpload`：根据当前会话类型、会话 ID 和消息 ID 找到唯一上传任务后取消。
- * - `requestReplacement` / `takeReplacementRequest`：视频或文件刷新后失去本地源时，生成一次重新选择请求；
- *   宿主取走意图后自行打开平台文件选择器，File 本身不会写入 Store。
- *
- * 【安全、并发与资源边界】
- * 页面任务会删除 SDK 错误中的底层原因和详情，只保留错误码、分类和是否可重试。File、Blob、本地地址、
- * 播放器、中止控制器、传输能力、Client 和订阅函数都不能进入 `$state`。Store 同时核对当前 Client、
- * 账号版本号和绑定序号；旧账号任务或旧操作晚返回时只得到 `stale`，不会更新新页面。
- *
- * 【明确不负责】
- * 文件选择、预览、录音权限、播放器、Blob URL 生命周期、toast 和页面布局属于浏览器或宿主平台能力。
- */
-
 /** 页面可保存和判断的媒体错误；底层响应、异常对象和详情只进入统一诊断，不进入 Pinia。 */
 type ImMediaStoreError = Readonly<Omit<ImSdkErrorShape, 'cause' | 'details'>>;
 /** 页面可展示的只读媒体任务；不含文件字节、本地地址、密钥、中止控制器或传输对象。 */
@@ -7119,8 +7133,67 @@ type ImMediaOperationResult = Readonly<{
  * 宿主既有的 `downloadProgress[message.id]` 读法不受影响。
  */
 declare function imMediaDownloadKey(messageId: string, itemIndex?: number): string;
+declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-media", Pick<{
+    tasks: any;
+    error: any;
+    uploadProgress: any;
+    downloadTasks: any;
+    downloadProgress: any;
+    uploadWaiting: any;
+    uploadFinalizing: any;
+    replacementRequest: any;
+    start: () => void;
+    reset: () => void;
+    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
+    requestReplacement: (message: ImMessageView) => boolean;
+    takeReplacementRequest: () => ImMediaReplacementRequest | null;
+    clearReplacementRequest: () => void;
+    dispose: () => void;
+}, any>, Pick<{
+    tasks: any;
+    error: any;
+    uploadProgress: any;
+    downloadTasks: any;
+    downloadProgress: any;
+    uploadWaiting: any;
+    uploadFinalizing: any;
+    replacementRequest: any;
+    start: () => void;
+    reset: () => void;
+    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
+    requestReplacement: (message: ImMessageView) => boolean;
+    takeReplacementRequest: () => ImMediaReplacementRequest | null;
+    clearReplacementRequest: () => void;
+    dispose: () => void;
+}, any>, Pick<{
+    tasks: any;
+    error: any;
+    uploadProgress: any;
+    downloadTasks: any;
+    downloadProgress: any;
+    uploadWaiting: any;
+    uploadFinalizing: any;
+    replacementRequest: any;
+    start: () => void;
+    reset: () => void;
+    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
+    requestReplacement: (message: ImMessageView) => boolean;
+    takeReplacementRequest: () => ImMediaReplacementRequest | null;
+    clearReplacementRequest: () => void;
+    dispose: () => void;
+}, any>>;
+type ImMediaStore = ReturnType<ReturnType<typeof defineImMediaStore>>;
 /** 取得当前 Vue setup 或显式 Pinia 的媒体任务 Store；不会隐式创建 Runtime。 */
-declare function useImMediaStore(pinia?: Pinia): any;
+declare function useImMediaStore(pinia?: Pinia): ImMediaStore;
 
 /**
  * 执行“把当前会话中的一条或多条消息转发到若干目标会话”。
@@ -8320,30 +8393,20 @@ type ImReactionStore = Store<'k2-im-reaction', ImReactionStoreState, Record<stri
 declare function useImReactionStore(pinia?: Pinia): ImReactionStore;
 
 /**
- * 为当前聊天线程提供关键词搜索、分类媒体浏览、结果续页和跳转到原消息。
- *
- * 【对外状态】
- * Store 暴露关键词、全部/文件/图片/视频/语音分类、结果列表、搜索状态、是否还有下一页、正在定位的
- * 消息 ID、短暂高亮 ID 与稳定错误。SDK 仍维护搜索索引、消息历史窗口和真实分页位置，Pinia 只保存
- * 当前搜索面板需要展示的状态。
+ * 读取当前会话的消息搜索结果和分类媒体列表。
  *
- * 【提供的能力】
- * - `search`：更新关键词，用户停止输入 250ms 后执行，避免每个按键都发请求。
- * - `setCategory`：切换消息、文件、图片、视频或语音产品入口。
- * - `loadMore`：使用闭包中不可解析的分页凭证继续同一次查询。
- * - `locate`：让当前线程加载目标消息附近的历史并发布定位 ID；宿主完成实际滚动后，高亮 ID 再保留 2 秒。
- * - `clearLocation` / `reset`：结束定位或作废当前查询生命周期；`reset({ preserveLocation: true })` 可在关闭搜索面板时保留刚写入的高亮。
+ * 全部消息按关键词搜索；文件既可按名称搜索也可浏览；图片、视频和语音按分类浏览。单聊、普通群和
+ * 社群会调用各自的 SDK 搜索能力。分页位置由 SDK 封装成 `ImPageToken`，调用方只能原样传回续页，
+ * 不能解析或修改其中的账号、会话和查询条件。
  *
- * 【并发与身份隔离】
- * 分页凭证、定时器、会话句柄、请求序号和账号版本号全部留在闭包。切查询、分类、会话、账号或
- * 销毁 Store 会把等待/在途任务结算为 `stale`；同 ID 的单聊、普通群和社群始终按类型 + ID 隔离。旧任务
- * 不能关闭新任务的 loading，也不能覆盖新结果、错误或高亮。
- *
- * 【明确不负责】
- * Store 不访问滚动容器，不决定搜索面板、空态和反馈文案。宿主监听 `highlightMessageId` 后完成实际
- * DOM 居中/高亮；分页凭证、协议续页位置与底层响应不会暴露给宿主。
+ * 防抖、当前查询状态、切账号/切会话后的旧结果丢弃由 Search Store 负责。本 Service 只取一批结果，
+ * 并在底层出现稀疏空页时有限地向后查找，避免页面误显示“没有结果”。
  */
 
+/** 搜索面板可选择的业务分类：全部/文本走关键词；文件可空词浏览；图/音/视频按类型浏览。 */
+type ConversationSearchCategory = 'all' | 'text' | 'image' | 'video' | 'file' | 'voice';
+
+type ProductConversationRef$2 = ConversationRef<ProductHandleConversationType>;
 type SearchOperation = 'search' | 'load-more' | 'locate';
 /** 搜索、续页或定位结果；宿主只按操作和原因决定反馈，不解析 SDK 底层异常。 */
 type ImSearchOperationResult = Readonly<{
@@ -8355,8 +8418,67 @@ type ImSearchOperationResult = Readonly<{
     reason: 'not-ready' | 'no-condition' | 'busy' | 'exhausted' | 'stale' | 'failed';
     error?: ImSdkErrorShape;
 }>;
+declare function defineImSearchStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-search", Pick<{
+    keyword: any;
+    results: any;
+    searching: any;
+    hasMore: any;
+    category: any;
+    locatingMessageId: any;
+    highlightMessageId: any;
+    error: any;
+    search: (nextKeyword: string) => Promise<ImSearchOperationResult>;
+    setCategory: (nextCategory: ConversationSearchCategory) => Promise<ImSearchOperationResult>;
+    loadMore: () => Promise<ImSearchOperationResult>;
+    locate: (ref: ProductConversationRef$2, messageId: string) => Promise<ImSearchOperationResult>;
+    completeLocation: (messageId: string) => boolean;
+    clearLocation: () => void;
+    reset: (options?: {
+        preserveLocation?: boolean;
+    }) => void;
+    dispose: () => void;
+}, any>, Pick<{
+    keyword: any;
+    results: any;
+    searching: any;
+    hasMore: any;
+    category: any;
+    locatingMessageId: any;
+    highlightMessageId: any;
+    error: any;
+    search: (nextKeyword: string) => Promise<ImSearchOperationResult>;
+    setCategory: (nextCategory: ConversationSearchCategory) => Promise<ImSearchOperationResult>;
+    loadMore: () => Promise<ImSearchOperationResult>;
+    locate: (ref: ProductConversationRef$2, messageId: string) => Promise<ImSearchOperationResult>;
+    completeLocation: (messageId: string) => boolean;
+    clearLocation: () => void;
+    reset: (options?: {
+        preserveLocation?: boolean;
+    }) => void;
+    dispose: () => void;
+}, any>, Pick<{
+    keyword: any;
+    results: any;
+    searching: any;
+    hasMore: any;
+    category: any;
+    locatingMessageId: any;
+    highlightMessageId: any;
+    error: any;
+    search: (nextKeyword: string) => Promise<ImSearchOperationResult>;
+    setCategory: (nextCategory: ConversationSearchCategory) => Promise<ImSearchOperationResult>;
+    loadMore: () => Promise<ImSearchOperationResult>;
+    locate: (ref: ProductConversationRef$2, messageId: string) => Promise<ImSearchOperationResult>;
+    completeLocation: (messageId: string) => boolean;
+    clearLocation: () => void;
+    reset: (options?: {
+        preserveLocation?: boolean;
+    }) => void;
+    dispose: () => void;
+}, any>>;
+type ImSearchStore = ReturnType<ReturnType<typeof defineImSearchStore>>;
 /** 取得当前 Vue setup 或显式 Pinia 的搜索 Store；不同宿主实例不会共享查询或定位状态。 */
-declare function useImSearchStore(pinia?: Pinia): any;
+declare function useImSearchStore(pinia?: Pinia): ImSearchStore;
 
 /**
  * 为 PC/H5 提供同一套会话收藏列表和已收藏标记。
@@ -8621,4 +8743,4 @@ type MessageNotificationDecision = {
 declare function resolveMessageNotificationDecision(input: MessageNotificationInput): MessageNotificationDecision;
 
 export { applicationKey, createAndInstallImChatKit, createImChatKitContext, disposeImChatKit, ensureImChatKitSelfProfile, getImChatKitContext, imMediaDownloadKey, installImChatKit, resolveMessageNotificationDecision, useImApplicationsStore, useImCapabilitiesStore, useImComposerStore, useImConversationActivationCoordinator, useImConversationDeletionCoordinator, useImConversationListStore, useImExpressionStore, useImHistoryReturnAfterSendCoordinator, useImMediaStore, useImMessageOperationsStore, useImProfileDirectoryStore, useImQuotedMessageStore, useImReactionStore, useImSearchStore, useImSessionFavoritesStore, useImSessionStore, useImThreadPagingStore, useImThreadReturnToLatestCoordinator, useImThreadStore };
-export type { ApplyImSessionInput, ChatRuntimeFactories, ChatRuntimeHostDeps, ImApplicationDomainCounts, ImApplicationReviewOperation, ImApplicationReviewResult, ImApplicationsReloadResult, ImApplicationsStoreError, ImCapabilitiesStore, ImChannelManagementMemberTarget, ImChannelMemberManagementOperation, ImChannelMemberManagementResult, ImChannelMemberManagementResultFor, ImChannelProfileActionResult, ImChannelProfileActionResultFor, ImChannelProfileOperation, ImChatKitContext, ImChatKitInstallation, ImComposerStore, ImComposerStoreActions, ImComposerStoreState, ImComposerSubmitResult, ImConversationActivationCoordinator, ImConversationActivationError, ImConversationActivationResult, ImConversationDeletionCoordinator, ImConversationDeletionError, ImConversationDeletionResult, ImConversationListActionError, ImConversationListMutationOperation, ImConversationListMutationResult, ImConversationListRefreshResult, ImConversationListStore, ImDirectContactActionResult, ImDirectContactActionResultFor, ImDirectContactOperation, ImDirectoryState, ImEmojiPanelRecentEntry, ImEmojiRecentEntry, ImExpressionLoadStatus, ImExpressionOperation, ImExpressionOperationResult, ImExpressionRecentPersistencePort, ImExpressionRecentPersistenceSnapshot, ImExpressionRecentViewItem, ImExpressionResetOptions, ImExpressionSendResult, ImExpressionStore, ImExpressionStoreActions, ImExpressionStoreError, ImExpressionStoreGetters, ImExpressionStoreState, ImForwardPreparationResult, ImGameRecentEntry, ImGroupMemberManagementOperation, ImGroupMemberManagementResult, ImGroupMemberManagementResultFor, ImGroupProfileActionResult, ImGroupProfileActionResultFor, ImGroupProfileOperation, ImHistoryReturnAfterSendCoordinator, ImHistoryReturnError, ImHistoryReturnExecution, ImHistoryReturnResult, ImMediaOperationResult, ImMediaReplacementRequest, ImMediaStoreError, ImMediaTaskPresentation, ImMembershipJoinActionResult, ImMembershipJoinOperation, ImMessageOperationsStore, ImMessageOperationsStoreActions, ImMessageOperationsStoreState, ImMessageSelectionResult, ImPersistedEmojiPanelRecentEntry, ImPersistedEmojiRecentEntry, ImPersistedExpressionAssetRecentEntry, ImPersistedGameRecentEntry, ImProfileAccessDestination, ImProfileAccessResult, ImProfileDirectoryResult, ImQuotedMessageState, ImQuotedMessageStore, ImQuotedMessageStoreActions, ImQuotedMessageStoreState, ImReactionOperationResult, ImReactionStore, ImReactionStoreActions, ImReactionStoreError, ImReactionStoreState, ImSearchOperationResult, ImSessionFavoritesReloadResult, ImSessionFavoritesStoreError, ImSessionFavoritesWriteResult, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };
+export type { ApplyImSessionInput, ChatRuntimeFactories, ChatRuntimeHostDeps, ImApplicationDomainCounts, ImApplicationReviewOperation, ImApplicationReviewResult, ImApplicationsReloadResult, ImApplicationsStoreError, ImCapabilitiesStore, ImChannelManagementMemberTarget, ImChannelMemberManagementOperation, ImChannelMemberManagementResult, ImChannelMemberManagementResultFor, ImChannelProfileActionResult, ImChannelProfileActionResultFor, ImChannelProfileOperation, ImChatKitContext, ImChatKitInstallation, ImComposerStore, ImComposerStoreActions, ImComposerStoreState, ImComposerSubmitResult, ImConversationActivationCoordinator, ImConversationActivationError, ImConversationActivationResult, ImConversationDeletionCoordinator, ImConversationDeletionError, ImConversationDeletionResult, ImConversationListActionError, ImConversationListMutationOperation, ImConversationListMutationResult, ImConversationListRefreshResult, ImConversationListStore, ImDirectContactActionResult, ImDirectContactActionResultFor, ImDirectContactOperation, ImDirectoryState, ImEmojiPanelRecentEntry, ImEmojiRecentEntry, ImExpressionLoadStatus, ImExpressionOperation, ImExpressionOperationResult, ImExpressionRecentPersistencePort, ImExpressionRecentPersistenceSnapshot, ImExpressionRecentViewItem, ImExpressionResetOptions, ImExpressionSendResult, ImExpressionStore, ImExpressionStoreActions, ImExpressionStoreError, ImExpressionStoreGetters, ImExpressionStoreState, ImForwardPreparationResult, ImGameRecentEntry, ImGroupMemberManagementOperation, ImGroupMemberManagementResult, ImGroupMemberManagementResultFor, ImGroupProfileActionResult, ImGroupProfileActionResultFor, ImGroupProfileOperation, ImHistoryReturnAfterSendCoordinator, ImHistoryReturnError, ImHistoryReturnExecution, ImHistoryReturnResult, ImMediaOperationResult, ImMediaReplacementRequest, ImMediaStore, ImMediaStoreError, ImMediaTaskPresentation, ImMembershipJoinActionResult, ImMembershipJoinOperation, ImMessageOperationsStore, ImMessageOperationsStoreActions, ImMessageOperationsStoreState, ImMessageSelectionResult, ImPersistedEmojiPanelRecentEntry, ImPersistedEmojiRecentEntry, ImPersistedExpressionAssetRecentEntry, ImPersistedGameRecentEntry, ImProfileAccessDestination, ImProfileAccessResult, ImProfileDirectoryResult, ImQuotedMessageState, ImQuotedMessageStore, ImQuotedMessageStoreActions, ImQuotedMessageStoreState, ImReactionOperationResult, ImReactionStore, ImReactionStoreActions, ImReactionStoreError, ImReactionStoreState, ImSearchOperationResult, ImSearchStore, ImSessionFavoritesReloadResult, ImSessionFavoritesStoreError, ImSessionFavoritesWriteResult, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };