k2-im 0.1.36 → 0.1.38

package/dist/browser.js

@@ -1 +1 @@
-export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-4CH72T6I.js';import'./chunk-ANHUDX3C.js';import'./chunk-WOT6VMZA.js';
+export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-ZERTVCH2.js';import'./chunk-4I23ADH2.js';import'./chunk-WOT6VMZA.js';

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

@@ -202,6 +202,8 @@ interface ImVideoBody {
     width: number;
     /** 视频像素高（BMessage.height）。 */
     height: number;
+    /** 发送方显式选择了 HD 原视频（BMessage.hd）；不按分辨率猜测。 */
+    hd?: boolean;
     /** 时长（秒，可含小数）；移动端旧消息的毫秒值由 SDK 转换，宿主不得猜单位。 */
     duration?: number;
     /** SDK 已确认时长为秒的标记；兼容旧缓存时防止重复转换。缺省仍按公开 API 的秒约定传入。 */
@@ -711,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';
     /** 当前发送意图的尝试序号与总上限。 */
@@ -720,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;
@@ -774,7 +788,7 @@ interface ImMessage {
     };
     /**
      * CHANNEL 管理员/社群主全员删除终态。它与发送者本人撤回、`deleteLocal` 完全不同：服务端通过
-     * `RADIO_ADMIN_CANCEL_*` 同步给全员，正文不可逆清空，产品统一展示“管理员删除了一条消息”。
+     * `RADIO_ADMIN_CANCEL_*` 同步给全员，正文不可逆清空；线程与会话摘要仅向群主、管理员展示删除提示，普通成员及未知角色隐藏。
      */
     deletedForEveryone?: {
         by: string;
@@ -956,6 +970,15 @@ interface ImSession {
      * 派生展示字段（随最新消息变化，会话列表据此显示发送中 loading / 失败图标）；运行期真相，不持久化（persistSession 落盘时剔除）。
      */
     lastMessageSendState?: 'sending' | 'failed';
+    /**
+     * 最新一条己方已发送消息的回执态。
+     *
+     * 只在自己发出且 `status='sent'` 时投影；发送中/失败、对端消息、撤回、全员删除和系统提示都不给。
+     * `delivered` 与尚未回执一样投影为 `unread`；当前协议没有送达通知，不能把 `sent` 当作对端已收到。
+     * 该字段随最新消息变化，并随会话落盘，避免冷启动后
+     * 因「盘中缺字段 / 内存有字段」反复广播；对端已读变化必须刷新会话行。
+     */
+    lastMessageReceipt?: 'unread' | 'read';
     /** P0 我方已读游标（见 §4.3）。 */
     readCursor?: string;
     /** 群受限状态（仅 group；来自 0x2204 群通知 side-effect）。缺省视为 'active'（可正常发送）。 */
@@ -1057,8 +1080,8 @@ interface UserProfile {
     /** 用户自设昵称（后端 `nick_name`）。 */
     nickname: string;
     /**
-     * 好友备注名（后端 `/user/info/friend` 的 `remark_name`，仅好友关系有）。
-     * 与 `nickname` 并存：展示名优先级 = 备注名 > 昵称（安卓 SessionUtils.getShowUserName 实证）。
+     * 好友展示备注（后端 `/user/info/friend` 的 `remark_name`，无备注时回退 `contact_name`，仅好友关系有）。
+     * 与 `nickname` 并存：展示名优先级 = 备注名/通讯录名 > 昵称（安卓 SessionUtils.getShowUserName 实证）。
      */
     remark?: string;
     avatar?: string;
@@ -1849,6 +1872,8 @@ interface MediaAssetCacheStrategy {
     softMaxBytes: number;
     maxEntries: number;
     maxEntryBytes: number;
+    /** 完整媒体副本允许连续未访问的最长毫秒数；省略时不按时间过期，仍执行容量限制。 */
+    maxIdleMs?: number;
 }
 /** 精确按 kind 解析策略；未注册返回 undefined，不提供默认策略。 */
 interface MediaAssetCacheStrategyRegistry {
@@ -1862,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 {
@@ -2109,6 +2138,11 @@ type StoredConversationBackground = {
  * 失败经 `error` 事件（scope:'storage'）暴露、不静默吞、不阻塞内存主流程。
  */
 interface ImStoragePort {
+    /**
+     * 显式支持 CHANNEL 持久同步位置。声明 true 的 adapter 必须在删除会话正文/清历史事务中
+     * 同时删除 channelSyncCheckpointKey 对应 meta；旧 adapter 缺省不启用跨运行续传。
+     */
+    readonly supportsChannelSyncCheckpoint?: true;
     /** 可选的最近页持久缓存；缺少该能力时 SDK 必须明确跳过持久预取。 */
     recentHistoryCache?: ImRecentHistoryCachePort;
     /** 打开/创建账号库并跑迁移（幂等）。open 前的读写应视为未就绪并抛错（不静默兜底）。 */
@@ -2174,12 +2208,13 @@ interface ImStoragePort {
     deleteSession: (conversation: ImStorageConversation) => Promise<void>;
     /** 删除单会话已读态（删除会话用）。 */
     deleteReadState: (conversation: ImStorageConversation) => Promise<void>;
-    /** 删除某会话全部本地消息（删除会话用）。 */
+    /** 删除某会话全部本地消息及对应 CHANNEL 同步位置，二者须在同一事务内清理。 */
     deleteConversationMessages: (conversation: ImStorageConversation) => Promise<void>;
     /**
      * 原子清空精确会话的本机历史，并同步写入清空后的会话摘要与本机读态。
      *
      * @remarks 这是可选 capability，供产品 `history.clearLocal()` 使用；自定义 adapter 未实现时必须显式拒绝，不能退化为多次写入制造半清理状态。
+     * 同一事务还须删除 channelSyncCheckpointKey(conversation) 对应同步位置，避免正文已清而继续跳过旧页。
      * 不删除会话行、草稿、Outbox、置顶消息或任何远端数据。
      */
     clearConversationHistory?: (conversation: ConversationRef, nextSession?: ImSession, nextReadState?: ReadState) => Promise<void>;
@@ -2961,8 +2996,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()` 释放句柄。
@@ -4350,6 +4385,13 @@ interface ConversationListItem {
         by: string;
     }>;
     lastMessageSendState?: 'sending' | 'failed';
+    /**
+     * 最新一条己方已发送消息的对端已读态。
+     *
+     * 只在自己发出且已发送成功时出现；发送中/失败、对端消息、撤回和系统提示都不给。
+     * 单聊会话列表用它在摘要前画灰色单勾/绿色双勾；群组与社群即使有该字段也不展示。
+     */
+    lastMessageReceipt?: 'unread' | 'read';
     timestamp: number;
     unreadCount: number;
     /** 是否为用户手工添加的本地未读提醒；此时 `unreadCount` 至少投影为 1。 */
@@ -4538,6 +4580,21 @@ type ConversationEntryUnreadSnapshot = Readonly<{
 }> | Readonly<{
     state: 'unavailable';
 }>;
+/** 进入时冻结的导航提示；数量独立于会话已读，不暴露内部历史排序边界。 */
+type ConversationEntryUnreadNavigation = Readonly<{
+    state: 'none';
+}> | Readonly<{
+    state: 'pending' | 'unavailable';
+    count: number;
+}> | Readonly<{
+    state: 'located';
+    count: number;
+    firstMessageId: string;
+}> | Readonly<{
+    state: 'failed';
+    count: number;
+    error: ImSdkErrorShape;
+}>;
 
 /**
  * Emoji、GIF 与贴图稳定产品门面。
@@ -4701,6 +4758,8 @@ interface ConversationOpenOptions {
      * 后续 read 事件或新消息不会移动分隔线。
      */
     initialPosition?: ConversationInitialPosition;
+    /** 冻结进入时未读导航，独立于初始位置；清会话未读后仍可定位原边界。 */
+    captureEntryUnread?: boolean;
     /**
      * 初始历史加载方式，默认 `blocking`。
      *
@@ -4728,6 +4787,8 @@ interface ConversationHandleSnapshot<TType extends ProductHandleConversationType
     messages: readonly ImMessageView[];
     /** 本次打开时冻结的未读入口；只用于产品 UI 分隔线，不作为 SDK 已读真相。 */
     entryUnread: ConversationEntryUnreadSnapshot;
+    /** 显式请求的进入导航快照；旧消费者不请求时省略。 */
+    entryUnreadNavigation?: ConversationEntryUnreadNavigation;
     /** 当前账号本机草稿；不承诺跨端同步。 */
     draft: ConversationDraft | null;
     loading: boolean;
@@ -5028,15 +5089,17 @@ interface ConversationHandle<TType extends ProductHandleConversationType = Produ
     resolveMessage: (messageId: string) => Promise<ImMessageView | null>;
     history: {
         loadLatest: () => Promise<void>;
+        /** 有限加载进入时冻结边界；成功才替换窗口，不可定位返回 false，网络失败抛错并保留数量。 */
+        loadEntryUnread: () => 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`）。这是常见产品结果而非链路异常，
          * 调用方应据此与真正的存储/协议失败区分反馈，不要解析错误文案。
          */
@@ -5058,6 +5121,10 @@ interface ConversationHandle<TType extends ProductHandleConversationType = Produ
     draft: ConversationDraftApi;
     /** 标记窗口最新消息或显式可见消息为已读；SDK 按精确 sibling 解析真实 read cursor。 */
     markRead: (messageId?: string) => Promise<void>;
+    /** 结算最新可信边界的会话未读；不会将整个范围登记为对端可见回执。 */
+    markConversationRead: () => Promise<void>;
+    /** 只登记实际可见的消息 ID；历史消息也可补报，媒体消费继续使用独立动作。 */
+    markVisibleMessages: (messageIds: readonly string[]) => Promise<void>;
     setMuted: (muted: boolean) => Promise<void>;
     close: () => void;
 }
@@ -5168,6 +5235,8 @@ interface ImMediaTask {
      * 上传任务不带下标：一条合集整体只有一条上传进度（所有项都传完才算这条消息发出去）。
      */
     itemIndex?: number;
+    /** 合集各项的真实上传快照；控制动作仍作用于整条消息，不包含资源或传输凭据。 */
+    items?: MediaTaskUpdate['items'];
     /** upload 来自发送链路，download 来自本产品 API。 */
     direction: 'upload' | 'download';
     /** 终态 completed/failed/canceled 不会被同一尝试的迟到 progress 回退。 */
@@ -5213,6 +5282,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`。
@@ -5227,7 +5310,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>;
     /** 恢复已暂停上传，复用同一原文件与消息。 */
@@ -5245,19 +5331,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`。
      *
@@ -6048,6 +6143,7 @@ interface ImClientOptions {
     /** 显式开启视频/文件跨刷新续传。最多 3 条、24 小时，保存加密密钥但不保存文件副本；注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
 }
 /**
@@ -6664,6 +6760,7 @@ interface ChatRuntimeHostDeps {
     /** 显式启用账号隔离的跨刷新恢复记录；保存密钥、不保存原文件，注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
     /** 获取 GIF provider 配置；API key 只留在宿主闭包与 SDK adapter，不进入共享 Store。 */
     getExpressionOptions?: () => ImExpressionOptions | undefined;
@@ -6941,7 +7038,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;
@@ -7606,11 +7707,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>;
@@ -7622,7 +7730,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;
@@ -7638,11 +7748,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>;
@@ -7654,7 +7771,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;
@@ -7670,11 +7789,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>;
@@ -7686,7 +7812,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;
@@ -8832,7 +8960,7 @@ interface ImQuotedMessageStoreActions {
      * 声明当前这一屏需要哪些被引原消息，并按需解析尚未解析的部分。
      *
      * 幂等且可以高频调用：已有结论的（解析成功、确认缺失、解析失败）都不会重复查询，窗口内已有的
-     * 消息也不占用回源额度。同一时刻只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
+     * 消息也不占用回源额度。同一活动线程只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
      * 所以在消息列表变化时无脑调一次就行，不需要宿主自己做防抖。
      *
      * 传入顺序就是解析顺序。默认按窗口顺序传即可；如果宿主能判断用户正在看哪一段，把那段的 id 放
@@ -9209,6 +9337,8 @@ interface ImThreadStoreState {
     display: ConversationHandleSnapshot['display'] | null;
     messages: readonly ImMessageView[];
     entryUnread: ConversationEntryUnreadSnapshot;
+    /** 本次进入前的数量与定位状态；列表清零后仍保留。 */
+    entryUnreadNavigation: ConversationHandleSnapshot['entryUnreadNavigation'];
     draft: ConversationDraft | null;
     loading: boolean;
     ready: boolean;
@@ -9224,6 +9354,14 @@ 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>;