k2-im 0.1.37 → 0.1.39

package/dist/browser.js

@@ -1 +1 @@
-export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-HUSCO5JM.js';import'./chunk-75GNCLQQ.js';import'./chunk-WOT6VMZA.js';
+export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-SRMSBFOP.js';import'./chunk-54HSPG2Z.js';import'./chunk-WOT6VMZA.js';

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

@@ -713,7 +713,7 @@ interface MediaTaskUpdate {
      * upload 任务子阶段。
      *
      * `waiting-upload-slot` 与 `state: 'queued'` 同时出现，表示还没开始传字节（在生成缩略图或在等上传槽位），
-     * 此时 percent 恒为 0；`transferring` 正在传字节；`finalizing` 是等待远端 URL 最终确认。
+     * 首发 percent 为 0，断点恢复时保留已有进度；`transferring` 正在传字节；`finalizing` 是等待远端 URL 最终确认。
      */
     phase?: 'waiting-upload-slot' | 'waiting-retry' | 'transferring' | 'finalizing';
     /** 当前发送意图的尝试序号与总上限。 */
@@ -722,6 +722,18 @@ interface MediaTaskUpdate {
     /** 已传与总字节数，供共享展示层估算速度。 */
     bytesTransferred?: number;
     bytesTotal?: number;
+    /** 上传合集的逐项真实字节快照；整组发送仍由外层任务控制，不为每格创建独立发送。 */
+    items?: readonly Readonly<{
+        /** 从零开始的合集位置。 */
+        itemIndex: number;
+        /** 本项实际上传字节与源文件总字节。 */
+        bytesTransferred: number;
+        bytesTotal: number;
+        /** 远端资源确认完成前最多 99%。 */
+        percent: number;
+        /** 本项状态；已完成项不随兄弟项取消或失败回退。 */
+        state: 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+    }>[];
     /** 跨刷新恢复可用性；缺省尚未建立恢复记录。 */
     recovery?: 'available' | 'session-only';
     recoveryReason?: string;
@@ -1860,6 +1872,8 @@ interface MediaAssetCacheStrategy {
     softMaxBytes: number;
     maxEntries: number;
     maxEntryBytes: number;
+    /** 完整媒体副本允许连续未访问的最长毫秒数；省略时不按时间过期，仍执行容量限制。 */
+    maxIdleMs?: number;
 }
 /** 精确按 kind 解析策略；未注册返回 undefined，不提供默认策略。 */
 interface MediaAssetCacheStrategyRegistry {
@@ -1873,8 +1887,12 @@ interface MediaAssetCacheStrategyRegistry {
  */
 interface MediaAssetCachePort {
     get: (key: MediaAssetCacheKey) => Promise<MediaAssetCacheEntry | null>;
+    /** 按输入顺序检查完整资源是否存在且未过期；不读取 Blob、不延长闲置期限，存储故障必须抛出。 */
+    hasMany?: (keys: readonly MediaAssetCacheKey[]) => Promise<readonly boolean[]>;
     put: (entry: MediaAssetCacheEntry) => Promise<'stored' | 'skipped'>;
     clear: () => Promise<void>;
+    /** 删除超过闲置期限的完整持久副本；不撤销已经返回的 Blob 或宿主持有的播放地址。 */
+    prune?: () => Promise<void>;
 }
 
 interface ImProfilePort {
@@ -2419,6 +2437,11 @@ type ImEvent = {
  | {
     type: 'receiving:changed';
     receiving: boolean;
+}
+/** 全局会话与离线消息同步；不包含当前会话的打开或历史分页。 */
+ | {
+    type: 'syncing:changed';
+    syncing: boolean;
 } | {
     type: 'auth:invalid';
     issue: ImAuthIssue;
@@ -2978,8 +3001,8 @@ interface IndexedDbStorageAdapterOptions {
         maxPendingWriteBytes?: number;
     };
 }
-/** 官方浏览器 adapter 始终提供背景和最近历史缓存；可选只存在于通用 `ImStoragePort` 兼容边界。 */
-type IndexedDbStorageAdapter = ImStoragePort & MediaAssetCachePort & Required<Pick<ImStoragePort, 'getConversationBackground' | 'recentHistoryCache' | 'saveConversationBackground' | 'deleteConversationBackground' | 'getDefaultConversationBackground' | 'saveDefaultConversationBackground' | 'deleteDefaultConversationBackground'>>;
+/** 官方浏览器 adapter 始终提供背景、最近历史和媒体缓存维护；通用端口为其它实现保留可选能力。 */
+type IndexedDbStorageAdapter = ImStoragePort & MediaAssetCachePort & Required<Pick<MediaAssetCachePort, 'prune' | 'hasMany'>> & Required<Pick<ImStoragePort, 'getConversationBackground' | 'recentHistoryCache' | 'saveConversationBackground' | 'deleteConversationBackground' | 'getDefaultConversationBackground' | 'saveDefaultConversationBackground' | 'deleteDefaultConversationBackground'>>;
 /**
  * 创建 IndexedDB 存储 adapter（实现 ImStoragePort）。
  * 生命周期：先 `open({ namespace })`（幂等，跑 schema 迁移），再读写；`close()` 释放句柄。
@@ -3901,6 +3924,8 @@ interface ImLifecycleSnapshot {
     authenticated: boolean;
     /** 会话同步或前台内容读取仍在进行；不包含后台预取、媒体下载和写操作，也不代表同步成功。 */
     receiving: boolean;
+    /** 全局会话与离线消息同步仍在进行；前台会话读取由 receiving 和窗口 loading 表示。 */
+    syncing: boolean;
 }
 /** logout 的本地数据与在途消息策略。 */
 interface ImLogoutOptions {
@@ -5071,17 +5096,19 @@ interface ConversationHandle<TType extends ProductHandleConversationType = Produ
     resolveMessage: (messageId: string) => Promise<ImMessageView | null>;
     history: {
         loadLatest: () => Promise<void>;
-        /** 有限加载进入时冻结边界；成功才替换窗口，不可定位返回 false，网络失败抛错并保留数量。 */
-        loadEntryUnread: () => Promise<boolean>;
+        /** 读取进入时冻结边界；signal 取消会停止查询且不替换窗口，可重新发起。不可定位返回 false，失败抛错。 */
+        loadEntryUnread: (options?: {
+            signal?: AbortSignal;
+        }) => Promise<boolean>;
         loadOlder: () => Promise<void>;
         /** 历史定位窗口向更新方向连续翻页；接回最新端后 `hasNewer` 变为 false。 */
         loadNewer: () => Promise<void>;
         /**
          * 按稳定消息 id 打开目标附近的连续历史窗口。
          *
-         * @remarks 冷启动时允许使用同一复合会话的完整置顶预览或短期搜索结果作为只读锚点；二者都不会因此写入
-         * 普通消息 Store，partial 置顶、过期搜索结果仍因缺少可信排序信息而明确拒绝定位。
-         * @throws 目标不在本机历史或不属于当前复合会话时，抛出稳定 `IM_SDK_MESSAGE_NOT_FOUND`
+         * @remarks GROUP 完整置顶预览可按消息时间定位；CHANNEL 置顶未缓存时先按 ID 取回正式历史记录，
+         * 以服务端游标继续双向分页。短期搜索结果只作为只读锚点；partial 置顶和过期搜索结果明确拒绝定位。
+         * @throws 没有可用锚点、远端确认缺失或目标不属于当前复合会话时，抛出稳定 `IM_SDK_MESSAGE_NOT_FOUND`
          * （`category: 'state'`、`retryable: false`、`details.messageId`）。这是常见产品结果而非链路异常，
          * 调用方应据此与真正的存储/协议失败区分反馈，不要解析错误文案。
          */
@@ -5217,6 +5244,8 @@ interface ImMediaTask {
      * 上传任务不带下标：一条合集整体只有一条上传进度（所有项都传完才算这条消息发出去）。
      */
     itemIndex?: number;
+    /** 合集各项的真实上传快照；控制动作仍作用于整条消息，不包含资源或传输凭据。 */
+    items?: MediaTaskUpdate['items'];
     /** upload 来自发送链路，download 来自本产品 API。 */
     direction: 'upload' | 'download';
     /** 终态 completed/failed/canceled 不会被同一尝试的迟到 progress 回退。 */
@@ -5262,6 +5291,20 @@ interface ImMediaTask {
  * ```
  */
 interface ImMediaTasksApi {
+    /** 清除当前账号完整媒体缓存及下载断点；保留消息、草稿、上传源和已交付的播放资源，在途下载仍可完成。 */
+    clearCache: () => Promise<void>;
+    /**
+     * 按输入顺序查询完整本机媒体是否可用；不下载、不读取 Blob、不续缓存期限或创建任务。
+     * 仅支持图片/视频（含媒体合集）；未配置持久缓存时只检查内存。
+     * @throws 不支持轻量查询或存储读取失败时明确拒绝，不伪装成未命中。
+     * @example const [available] = await client.media.probeCached([messageRef])
+     */
+    probeCached: (messages: readonly ImMessageRef[]) => Promise<readonly boolean[]>;
+    /**
+     * 缓存写入、清理或过期后通知消费者重新查询；账号销毁后自动退订。
+     * @example const stop = client.media.subscribeCacheChanges(() => refreshVisibleMedia())
+     */
+    subscribeCacheChanges: (listener: () => void) => () => void;
     /**
      * 返回当前账号全部活跃任务与近期终态任务的冻结快照；总量超过 128 时只淘汰终态，极端并发活跃可暂时超过上限。
      * @throws runtime 已 logout/dispose 时抛 `IM_SDK_MEDIA_RUNTIME_INACTIVE`。
@@ -5276,7 +5319,10 @@ interface ImMediaTasksApi {
      * 取消 queued/running 任务；上传委托 core，下载中止当前 AbortController。
      * @throws 未知任务、非法状态或底层未受理时以稳定 `IM_SDK_MEDIA_TASK_*` 错误拒绝。
      */
-    cancel: (taskId: string) => Promise<void>;
+    cancel: (taskId: string, options?: {
+        /** 取消发送但保留已确认上传分片与原文件，只有用户显式重试才继续。默认取消仍清理。 */
+        retainCheckpoint?: boolean;
+    }) => Promise<void>;
     /** 暂停上传，等待请求收尾后返回；下载不支持暂停。 */
     pause: (taskId: string) => Promise<void>;
     /** 恢复已暂停上传，复用同一原文件与消息。 */
@@ -5294,19 +5340,28 @@ interface ImMediaTasksApi {
     /**
      * 重试 failed/canceled 任务；上传复用保留原文件，下载重新解析同一精确消息引用。
      * 续传不可用或清理未确认时，必须先征得用户同意重新上传，再传 restartUpload:true。
-     * 用户取消后的重发始终重新上传尚未完成的资源；成功的合集项仍可复用。
+     * 保留式取消后的重发复用已确认分片和原密钥；默认清理式取消不保证保有原文件。
      * 下载取消已受理后即可创建新尝试，不复用旧取消 Promise；旧 loader 结束前仍占用并发槽，但不能覆盖新任务。
      * @throws 原文件已淘汰、任务仍在途或消息/下载 capability 不可用时显式拒绝。
      */
     retry: (taskId: string, options?: {
         /** 用户已确认放弃旧进度并重新上传；仅上传任务接受，清理失败时仍停止。 */
         restartUpload?: boolean;
+        /** 下载断点已失效或超出缓存预算时，用户确认从头下载。 */
+        restartDownload?: boolean;
     }) => Promise<void>;
     /**
      * 下载并按消息正文合同解密，同一消息并发调用复用同一 Promise，成功返回 Blob。
      * @throws 消息不存在/非媒体/无远端 URL/未装配 capability、传输失败、取消或 teardown 均以稳定错误拒绝，不返回空 Blob。
      */
     download: (message: ImMessageRef) => Promise<Blob>;
+    /**
+     * 将最近预览的精确媒体项设为最高下载优先级，不新建或取消任务。
+     * 下一空闲任务/分片请求名额优先给该项；已发请求不中断，关闭播放器不撤销优先级。
+     * 后续调用替换上一个目标；账号退出后不可调用。
+     * @example client.media.prioritizeDownload({ conversation, messageId, itemIndex: 1 })
+     */
+    prioritizeDownload: (message: ImMessageRef) => void;
     /**
      * 仅读取当前账号内存或持久媒体资产缓存；命中返回 Blob，未缓存或类型未注册返回 `null`。
      *
@@ -5516,6 +5571,10 @@ interface ImProductEventMap {
     'receiving:changed': Readonly<{
         receiving: boolean;
     }>;
+    /** 全局同步所有支路的汇总状态；不包含打开会话、历史分页或后台预取。 */
+    'syncing:changed': Readonly<{
+        syncing: boolean;
+    }>;
     /** `lastLoginTime` 为服务端记录的上次登录时间（毫秒），仅被踢且走登录 ACK 的路径才有值。 */
     'auth:invalid': Readonly<{
         code: string;
@@ -5832,7 +5891,18 @@ interface ProductMessageSearchResult<TContent extends MessageContentType = Messa
     createdAt: number;
     contentType: TContent;
     preview: string;
+    /** 展示用片段；正文/配文携带提及信息，文件名等业务字段保持普通文本。拼接后与 preview 相同。 */
+    previewParts: readonly ProductMessageSearchPreviewPart[];
 }
+/** 搜索摘要的最小内容投影；不携带完整消息、媒体资源或协议字段。 */
+type ProductMessageSearchPreviewPart = {
+    kind: 'plain';
+    text: string;
+} | {
+    kind: 'rich-text';
+    text: string;
+    mention?: ImMessageMention;
+};
 /** 产品消息搜索页；底层 `beforeSortKey` 仅存在于账号 runtime token registry。 */
 interface ProductMessageSearchPage<TContent extends MessageContentType = MessageContentType> {
     items: readonly ProductMessageSearchResult<TContent>[];
@@ -6097,6 +6167,7 @@ interface ImClientOptions {
     /** 显式开启视频/文件跨刷新续传。最多 3 条、24 小时，保存加密密钥但不保存文件副本；注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
 }
 /**
@@ -6713,6 +6784,7 @@ interface ChatRuntimeHostDeps {
     /** 显式启用账号隔离的跨刷新恢复记录；保存密钥、不保存原文件，注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
     /** 获取 GIF provider 配置；API key 只留在宿主闭包与 SDK adapter，不进入共享 Store。 */
     getExpressionOptions?: () => ImExpressionOptions | undefined;
@@ -6990,7 +7062,11 @@ interface ChatRuntime {
     resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number) => void;
     /** 为指定消息取得本地媒体播放租约；没有本地缓存时返回 `undefined`，调用方应改用远端资源。 */
     acquireMediaBlob: (ref: ChatMediaMessageRef) => MediaObjectUrlLease | undefined;
+    /** 只读检查完整本地媒体是否可用，不取得租约、不改变缓存淘汰顺序。 */
+    hasMediaBlob: (ref: ChatMediaMessageRef) => boolean;
     /** 撤销当前账号创建的全部媒体预览地址并释放 Blob 内存，切账号、退出或销毁时调用。 */
+    /** 清理当前账号完整媒体缓存和下载断点；上传源保留，正在使用的播放地址在释放后才撤销。 */
+    clearMediaCache: () => Promise<void>;
     cleanupLocalMediaBlobs: () => void;
     /** 删除会话时释放该会话绑定的本地媒体预览/播放缓存。 */
     cleanupConversationMediaBlobs: (conversation: ConversationRef<'direct' | 'group' | 'channel' | 'robot'>) => void;
@@ -7655,11 +7731,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7671,7 +7754,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -7687,11 +7772,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7703,7 +7795,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -7719,11 +7813,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7735,7 +7836,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -8881,7 +8984,7 @@ interface ImQuotedMessageStoreActions {
      * 声明当前这一屏需要哪些被引原消息，并按需解析尚未解析的部分。
      *
      * 幂等且可以高频调用：已有结论的（解析成功、确认缺失、解析失败）都不会重复查询，窗口内已有的
-     * 消息也不占用回源额度。同一时刻只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
+     * 消息也不占用回源额度。同一活动线程只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
      * 所以在消息列表变化时无脑调一次就行，不需要宿主自己做防抖。
      *
      * 传入顺序就是解析顺序。默认按窗口顺序传即可；如果宿主能判断用户正在看哪一段，把那段的 id 放
@@ -8955,6 +9058,96 @@ type ImReactionStore = Store<'k2-im-reaction', ImReactionStoreState, Record<stri
 /** 取得当前 Vue setup 或显式 Pinia 的 Reaction Store；不持有菜单、Toast 或 Reaction 领域快照。 */
 declare function useImReactionStore(pinia?: Pinia): ImReactionStore;
 
+/**
+ * 为聊天主区域管理唯一一个“用户当前正在查看的消息线程”。
+ *
+ * 【页面得到什么】
+ * Store 用 SDK 会话句柄打开一个明确的单聊、普通群或社群，并把该线程的一次完整更新转换成
+ * `activeRef`、消息列表、已保存草稿、加载/就绪/过期状态、能否继续向前后翻页和错误。消息与草稿仍由
+ * SDK 和本机存储维护；只供资料页使用的隐藏系统消息不会显示在聊天时间线，但原数据不会被删除。
+ *
+ * 【提供的能力】
+ * - `open` / `close`：打开或关闭当前会话；打开新会话会停止旧会话页面订阅。
+ * - `closeActiveConversation`：只关闭精确活动会话，保留正在打开的其他会话意图。
+ * - `loadLatest` / `loadOlder` / `loadNewer`：加载最新一屏、向上翻更早消息或向下补更新消息。
+ * - `loadAround`：为搜索定位加载目标消息附近窗口。
+ * - `resolveMessage`：解析当前窗口之外但属于同一会话的本地消息。
+ * - `retainHandle`：让已经开始的发送或上传在用户切会话后仍能安全完成，再关闭旧句柄。
+ * - `reset` / `dispose`：切账号或销毁时作废订阅、分页结果并关闭全部会话句柄。
+ *
+ * 【并发与资源所有权】
+ * 同一 Store 同时只有一个活动会话句柄。异步结果必须同时匹配最新操作序号、当前账号版本号、当前句柄
+ * 和会话类型 + ID 才能更新页面；同 ID 的不同会话类型不会串线。句柄、订阅函数和“仍在使用”计数只在
+ * 闭包中，不进入 `$state`。
+ *
+ * 【明确不负责】
+ * Composer 输入、消息菜单、多选、DOM 滚动、路由和 toast 分别由其他共享 Store 或宿主平台层负责。
+ */
+
+type ProductConversationHandle = ConversationHandle<ProductHandleConversationType>;
+/** Thread Store 中由 Pinia 管理的当前窗口投影；句柄、订阅和租约留在闭包中。 */
+interface ImThreadStoreState {
+    activeRef: ConversationRef<ProductHandleConversationType> | null;
+    /** SDK 已校验的活动聊天展示资料；不依赖该聊天是否已进入会话列表。 */
+    display: ConversationHandleSnapshot['display'] | null;
+    messages: readonly ImMessageView[];
+    entryUnread: ConversationEntryUnreadSnapshot;
+    /** 本次进入前的数量与定位状态；列表清零后仍保留。 */
+    entryUnreadNavigation: ConversationHandleSnapshot['entryUnreadNavigation'];
+    draft: ConversationDraft | null;
+    loading: boolean;
+    ready: boolean;
+    stale: boolean;
+    hasOlder: boolean;
+    hasNewer: boolean;
+    error: ImSdkErrorShape | null;
+    /** 当前活动会话待 Surface 消费的实时对端消息版本。 */
+    activeRemoteMessageRevision: number;
+}
+/** Thread Store 的稳定公共动作；DOM 滚动、路由和反馈仍由宿主负责。 */
+interface ImThreadStoreActions {
+    open: (ref: ConversationRef<ProductHandleConversationType>) => Promise<ProductConversationHandle | undefined>;
+    invalidatePendingOpen: () => void;
+    loadLatest: () => Promise<boolean>;
+    /** 读取本次进入时冻结的首未读窗口；signal 取消时不替换当前窗口。 */
+    loadEntryUnread: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<boolean>;
+    /** 页面确认可阅读后结算整会话；不会自动扩大可见消息回执。 */
+    markConversationRead: () => Promise<void>;
+    /** 只上报当前线程实际显示的消息集合。 */
+    markVisibleMessages: (messageIds: readonly string[]) => Promise<void>;
+    /** 明确业务离开；账号销毁和页面卸载仍使用无副作用的 close/reset。 */
+    leave: () => void;
+    loadOlder: () => Promise<boolean>;
+    loadNewer: () => Promise<boolean>;
+    loadAround: (messageId: string) => Promise<boolean>;
+    resolveMessage: (messageId: string) => Promise<ImMessageView | null>;
+    retainHandle: (handle?: ProductConversationHandle) => () => void;
+    retainCurrentHandle: () => () => void;
+    close: () => void;
+    closeActiveConversation: (ref: ConversationRef<ProductHandleConversationType>) => boolean;
+    reset: () => void;
+    dispose: () => void;
+    getHandle: () => ProductConversationHandle | undefined;
+    /** 原子取走当前活动会话尚未被 Surface 消费的实时对端消息 id。 */
+    drainActiveRemoteMessageIds: () => readonly string[];
+}
+/** 宿主从 `useImThreadStore` 获得的完整 Pinia Store 公共类型。 */
+type ImThreadStore = Store<'k2-im-thread', ImThreadStoreState, Record<string, never>, ImThreadStoreActions>;
+/** 取得当前 Vue setup 或显式 Pinia 的消息线程 Store；每个实例只管理一个当前会话。 */
+declare function useImThreadStore(pinia?: Pinia): ImThreadStore;
+
+/** 搜索行的发送者投影；非 ready 状态不提供伪造姓名，由宿主翻译状态文案。 */
+interface ImSearchSenderPresentation {
+    /** ready 表示已有名称；self/system 由宿主翻译；其余状态明确区分等待、缺失和请求失败。 */
+    status: 'ready' | 'self' | 'system' | 'loading' | 'unavailable' | 'failed';
+    /** 仅使用资料中的真实名称；没有名称时为空，数字昵称仍原样保留。 */
+    name: string;
+    /** 来自同一份共享资料缓存；缺失头像时为空。 */
+    avatarUrl: string;
+}
+
 /**
  * 读取当前会话的消息搜索结果和分类媒体列表。
  *
@@ -8984,6 +9177,9 @@ type ImSearchOperationResult = Readonly<{
 declare function defineImSearchStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-search", Pick<{
     keyword: any;
     results: any;
+    senderFor: (row: ProductMessageSearchResult) => ImSearchSenderPresentation;
+    hasRetryableSenderProfiles: any;
+    retrySenderProfiles: () => Promise<void>;
     searching: any;
     hasMore: any;
     category: any;
@@ -9003,6 +9199,9 @@ declare function defineImSearchStore(pinia: Pinia): pinia.StoreDefinition<"k2-im
 }, any>, Pick<{
     keyword: any;
     results: any;
+    senderFor: (row: ProductMessageSearchResult) => ImSearchSenderPresentation;
+    hasRetryableSenderProfiles: any;
+    retrySenderProfiles: () => Promise<void>;
     searching: any;
     hasMore: any;
     category: any;
@@ -9022,6 +9221,9 @@ declare function defineImSearchStore(pinia: Pinia): pinia.StoreDefinition<"k2-im
 }, any>, Pick<{
     keyword: any;
     results: any;
+    senderFor: (row: ProductMessageSearchResult) => ImSearchSenderPresentation;
+    hasRetryableSenderProfiles: any;
+    retrySenderProfiles: () => Promise<void>;
     searching: any;
     hasMore: any;
     category: any;
@@ -9107,6 +9309,8 @@ interface ImSessionStore {
     readonly connectionState: ImConnectionState;
     /** SDK 正在同步会话、离线消息或读取前台会话内容；连接异常提示仍应优先展示。 */
     readonly receiving: boolean;
+    /** SDK 全局会话与离线消息同步；列表标题使用此状态，避免前台读取引起闪动。 */
+    readonly syncing: boolean;
     readonly generation: number;
     readonly phase: ImSessionPhase;
     readonly errorKey: string;
@@ -9124,6 +9328,7 @@ declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-i
     accountId: any;
     connectionState: any;
     receiving: any;
+    syncing: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -9141,6 +9346,7 @@ declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-i
     accountId: any;
     connectionState: any;
     receiving: any;
+    syncing: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -9158,6 +9364,7 @@ declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-i
     accountId: any;
     connectionState: any;
     receiving: any;
+    syncing: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -9224,84 +9431,6 @@ interface ImThreadReturnToLatestCoordinator {
  */
 declare function useImThreadReturnToLatestCoordinator(pinia?: Pinia): ImThreadReturnToLatestCoordinator;
 
-/**
- * 为聊天主区域管理唯一一个“用户当前正在查看的消息线程”。
- *
- * 【页面得到什么】
- * Store 用 SDK 会话句柄打开一个明确的单聊、普通群或社群，并把该线程的一次完整更新转换成
- * `activeRef`、消息列表、已保存草稿、加载/就绪/过期状态、能否继续向前后翻页和错误。消息与草稿仍由
- * SDK 和本机存储维护；只供资料页使用的隐藏系统消息不会显示在聊天时间线，但原数据不会被删除。
- *
- * 【提供的能力】
- * - `open` / `close`：打开或关闭当前会话；打开新会话会停止旧会话页面订阅。
- * - `closeActiveConversation`：只关闭精确活动会话，保留正在打开的其他会话意图。
- * - `loadLatest` / `loadOlder` / `loadNewer`：加载最新一屏、向上翻更早消息或向下补更新消息。
- * - `loadAround`：为搜索定位加载目标消息附近窗口。
- * - `resolveMessage`：解析当前窗口之外但属于同一会话的本地消息。
- * - `retainHandle`：让已经开始的发送或上传在用户切会话后仍能安全完成，再关闭旧句柄。
- * - `reset` / `dispose`：切账号或销毁时作废订阅、分页结果并关闭全部会话句柄。
- *
- * 【并发与资源所有权】
- * 同一 Store 同时只有一个活动会话句柄。异步结果必须同时匹配最新操作序号、当前账号版本号、当前句柄
- * 和会话类型 + ID 才能更新页面；同 ID 的不同会话类型不会串线。句柄、订阅函数和“仍在使用”计数只在
- * 闭包中，不进入 `$state`。
- *
- * 【明确不负责】
- * Composer 输入、消息菜单、多选、DOM 滚动、路由和 toast 分别由其他共享 Store 或宿主平台层负责。
- */
-
-type ProductConversationHandle = ConversationHandle<ProductHandleConversationType>;
-/** Thread Store 中由 Pinia 管理的当前窗口投影；句柄、订阅和租约留在闭包中。 */
-interface ImThreadStoreState {
-    activeRef: ConversationRef<ProductHandleConversationType> | null;
-    /** SDK 已校验的活动聊天展示资料；不依赖该聊天是否已进入会话列表。 */
-    display: ConversationHandleSnapshot['display'] | null;
-    messages: readonly ImMessageView[];
-    entryUnread: ConversationEntryUnreadSnapshot;
-    /** 本次进入前的数量与定位状态；列表清零后仍保留。 */
-    entryUnreadNavigation: ConversationHandleSnapshot['entryUnreadNavigation'];
-    draft: ConversationDraft | null;
-    loading: boolean;
-    ready: boolean;
-    stale: boolean;
-    hasOlder: boolean;
-    hasNewer: boolean;
-    error: ImSdkErrorShape | null;
-    /** 当前活动会话待 Surface 消费的实时对端消息版本。 */
-    activeRemoteMessageRevision: number;
-}
-/** Thread Store 的稳定公共动作；DOM 滚动、路由和反馈仍由宿主负责。 */
-interface ImThreadStoreActions {
-    open: (ref: ConversationRef<ProductHandleConversationType>) => Promise<ProductConversationHandle | undefined>;
-    invalidatePendingOpen: () => void;
-    loadLatest: () => Promise<boolean>;
-    /** 读取本次进入时冻结的首未读窗口。 */
-    loadEntryUnread: () => Promise<boolean>;
-    /** 页面确认可阅读后结算整会话；不会自动扩大可见消息回执。 */
-    markConversationRead: () => Promise<void>;
-    /** 只上报当前线程实际显示的消息集合。 */
-    markVisibleMessages: (messageIds: readonly string[]) => Promise<void>;
-    /** 明确业务离开；账号销毁和页面卸载仍使用无副作用的 close/reset。 */
-    leave: () => void;
-    loadOlder: () => Promise<boolean>;
-    loadNewer: () => Promise<boolean>;
-    loadAround: (messageId: string) => Promise<boolean>;
-    resolveMessage: (messageId: string) => Promise<ImMessageView | null>;
-    retainHandle: (handle?: ProductConversationHandle) => () => void;
-    retainCurrentHandle: () => () => void;
-    close: () => void;
-    closeActiveConversation: (ref: ConversationRef<ProductHandleConversationType>) => boolean;
-    reset: () => void;
-    dispose: () => void;
-    getHandle: () => ProductConversationHandle | undefined;
-    /** 原子取走当前活动会话尚未被 Surface 消费的实时对端消息 id。 */
-    drainActiveRemoteMessageIds: () => readonly string[];
-}
-/** 宿主从 `useImThreadStore` 获得的完整 Pinia Store 公共类型。 */
-type ImThreadStore = Store<'k2-im-thread', ImThreadStoreState, Record<string, never>, ImThreadStoreActions>;
-/** 取得当前 Vue setup 或显式 Pinia 的消息线程 Store；每个实例只管理一个当前会话。 */
-declare function useImThreadStore(pinia?: Pinia): ImThreadStore;
-
 /** 新消息提醒所需的领域与宿主事实；本模块不读取浏览器、路由或全局设置。 */
 interface MessageNotificationInput {
     source: 'live' | 'offline';
@@ -9323,4 +9452,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, 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 };
+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, ImSearchSenderPresentation, ImSearchStore, ImSessionFavoritesReloadResult, ImSessionFavoritesStoreError, ImSessionFavoritesWriteResult, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };