k2-im 0.2.15 → 0.2.17

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

@@ -1943,7 +1943,7 @@ interface ImHttpPort {
 }
 
 /** 可持久化的媒体资产类型；未注册类型必须跳过缓存，不能回退到其它类型。 */
-type MediaAssetKind = 'image' | 'video' | 'file';
+type MediaAssetKind = 'image' | 'image-display' | 'video-poster' | 'video' | 'file';
 /** 持久媒体资产的稳定键。resourceVersion 由远端资源标识派生，避免同消息替换资源后误命中旧缓存。 */
 interface MediaAssetCacheKey {
     kind: MediaAssetKind;
@@ -1992,7 +1992,10 @@ interface MediaAssetCachePort {
     get: (key: MediaAssetCacheKey) => Promise<MediaAssetCacheEntry | null>;
     /** 按输入顺序检查完整资源是否存在且未过期；不读取 Blob、不延长闲置期限，存储故障必须抛出。 */
     hasMany?: (keys: readonly MediaAssetCacheKey[]) => Promise<readonly boolean[]>;
-    put: (entry: MediaAssetCacheEntry) => Promise<'stored' | 'skipped'>;
+    /** isCurrent 在排队结束和写事务开始前复核；已失效的生成结果返回 skipped，已开始的事务不撤销。 */
+    put: (entry: MediaAssetCacheEntry, options?: {
+        isCurrent?: () => boolean;
+    }) => Promise<'stored' | 'skipped'>;
     clear: () => Promise<void>;
     /** 删除超过闲置期限的完整持久副本；不撤销已经返回的 Blob 或宿主持有的播放地址。 */
     prune?: () => Promise<void>;
@@ -3036,13 +3039,13 @@ interface MediaTransferAdapterConfig {
     useAccelerateEndpoint?: boolean;
     /**
      * 统一允许 S3 分片上传和 Range 分段下载，默认 false（单次 PUT / 普通 GET）。
-     * 显式 true 后仍按 16MiB 阈值及已确认下载大小选择策略，小资源不分片。
+     * 显式 true 后，上传对象达到 8 MiB 使用 Multipart；上传片长与下载段长均为 16 MiB。
      * 开启前各桶须支持分片请求方法，并暴露上传 ETag、下载 Content-Range 与强 ETag。
      * @example { multipartTransfer: true } 同时允许大资源分片上传、下载。
      */
     multipartTransfer?: boolean;
     /**
-     * 总开关开启后，是否允许超过分片阈值（16MiB）的上传使用 S3 分片上传。
+     * 总开关开启后，是否允许达到分片阈值（8 MiB）的上传使用 S3 分片上传。
      *
      * 分片相比单次 PUT 需要各物理桶的 CORS 额外放行 POST（Create/CompleteMultipartUpload）、
      * DELETE（AbortMultipartUpload）并 `ExposeHeaders: ETag`；未配齐时分片会直接失败。
@@ -3058,8 +3061,8 @@ interface MediaTransferAdapterConfig {
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，限制媒体任务数而非分片请求数。
      *
-     * 并发按媒体体积分两档：不超过分片阈值（16 MiB）的非视频媒体走小文件档，
-     * 缺省 5；视频与超过阈值（或字节数未知）的内容走大文件档，缺省 3。
+     * 并发按媒体体积分两档：小于分片阈值（8 MiB）的非视频媒体走小文件档，
+     * 缺省 5；视频与达到阈值（或字节数未知）的内容走大文件档，缺省 3。
      * 分档只限制媒体任务数；实际 PUT/UploadPart 另受 adapter 的六路数据请求限制。
      * 两档都只接受 1-6 的整数，超出范围由 core 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -3358,13 +3361,13 @@ interface MediaAlbumMessageOptions {
  * 本地视频的固有尺寸、时长与首帧封面。
  *
  * @remarks 宿主可从本地 object URL 解码首个可展示帧，使上传占位从首次渲染就使用真实比例和主图。
- * `posterData` 是等比缩放后的 JPEG（兼容已有 PNG）；存在时会作为消息 `thumbData` 随正文发送。宽高必须是有限正数，
+ * `posterData` 是等比缩放后的静态 WebP（兼容已有 JPEG/PNG）；存在时会作为消息 `thumbData` 随正文发送。宽高必须是有限正数，
  * duration 存在时必须是有限正数，posterData 必须是非空且不超过共享单项消息容量的 Uint8Array；合集发送会按项数复核容量。
  */
 interface VideoPreviewMetadata extends ImagePreviewMetadata {
     /** 秒。 */
     duration?: number;
-    /** 本地首个可展示帧生成的 JPEG 或已有 PNG 字节。 */
+    /** 本地首个可展示帧生成的 WebP 或已有 JPEG/PNG 字节。 */
     posterData?: Uint8Array;
 }
 /**
@@ -5397,6 +5400,17 @@ interface ImMessageRef {
      */
     itemIndex?: number;
 }
+/** 单次媒体下载的等待与调度选项；相同精确消息引用仍共用一次实际下载。 */
+interface ImMediaDownloadOptions {
+    /**
+     * 只取消本次调用；其它调用者仍需要结果时保留共享下载。
+     * 最后一个可取消调用者退出且没有无 signal 调用者时，才中止底层任务。
+     * 取消以 IM_SDK_MEDIA_DOWNLOAD_CANCELED 拒绝本次 Promise，不返回部分文件。
+     */
+    signal?: AbortSignal;
+    /** 默认 interactive；background 在空闲名额中排在交互下载之后，不能抢占已发请求。 */
+    priority?: 'background' | 'interactive';
+}
 /**
  * 可观察媒体上传/下载任务的只读产品投影。
  *
@@ -5495,7 +5509,8 @@ interface ImMediaTasksApi {
      */
     subscribe: (listener: (tasks: readonly ImMediaTask[]) => void) => () => void;
     /**
-     * 取消 queued/running 任务；上传委托 core，下载中止当前 AbortController。
+     * 取消 queued/running 任务；上传委托 core，下载中止共享任务并取消所有调用者。
+     * 只需结束某次下载等待时，应使用 download 的 signal。
      * @throws 未知任务、非法状态或底层未受理时以稳定 `IM_SDK_MEDIA_TASK_*` 错误拒绝。
      */
     cancel: (taskId: string, options?: {
@@ -5530,10 +5545,13 @@ interface ImMediaTasksApi {
         restartDownload?: boolean;
     }) => Promise<void>;
     /**
-     * 下载并按消息正文合同解密，同一消息并发调用复用同一 Promise，成功返回 Blob。
+     * 下载并按消息正文合同解密，同一精确消息引用共用实际下载，成功返回 Blob。
+     * 不带 signal 的并发调用保留共享 Promise；带 signal 的调用独立等待和取消，不影响其它调用者。
+     * 后加入的交互调用会提高共享下载优先级；prioritizeDownload 指定的最近预览仍优先于其它任务。
      * @throws 消息不存在/非媒体/无远端 URL/未装配 capability、传输失败、取消或 teardown 均以稳定错误拒绝，不返回空 Blob。
+     * @example const blob = await client.media.download(messageRef, { signal: controller.signal, priority: 'background' })
      */
-    download: (message: ImMessageRef) => Promise<Blob>;
+    download: (message: ImMessageRef, options?: ImMediaDownloadOptions) => Promise<Blob>;
     /**
      * 将最近预览的精确媒体项设为最高下载优先级，不新建或取消任务。
      * 下一空闲任务/分片请求名额优先给该项；已发请求不中断，关闭播放器不撤销优先级。
@@ -5549,7 +5567,7 @@ interface ImMediaTasksApi {
      */
     getCached: (message: ImMessageRef) => Promise<Blob | null>;
     /**
-     * 为宿主手里的**本地**图片/视频文件预读展示元信息：尺寸、视频时长、视频首帧封面的 JPEG 字节。
+     * 为宿主手里的**本地**图片/视频文件预读展示元信息：尺寸、视频时长、视频首帧封面的 WebP 字节。
      *
      * 给「发送前预览」这类场景用：宿主要在用户还没点发送时就把缩略图画出来，而浏览器读不出视频的
      * 首帧——`<video preload="metadata">` 在 iOS Safari 上只加载元信息、**不解码任何一帧**，
@@ -5557,7 +5575,7 @@ interface ImMediaTasksApi {
      *
      * 返回的对象可以**原样**作为 `localPreviewMetadata` 交给 `sendImage` / `sendVideo` /
      * `sendMediaAlbum`：发送链路会复用可用元信息；合集项超出其可用消息空间时重新生成封面。
-     * posterData 使用共享自适应发送规格（视频 JPEG，长边最多 960px，目标 8 KiB、硬上限 24 KiB）；includeDisplayPoster 可在同一次解码中额外生成
+     * posterData 使用共享自适应发送规格（视频 WebP，长边最多 1440px，目标 16 KiB、硬上限 32 KiB）；includeDisplayPoster 可在同一次解码中额外生成
      * 仅供页面显示的高清 displayPoster（长边最多 960），不得绕过发送校验直接用它替换 posterData。
      *
      * @param input.kind 按文件类型选解码路径；`'video'` 才会抽首帧与读时长。
@@ -5577,16 +5595,26 @@ interface ImMediaTasksApi {
         includeDisplayPoster?: boolean;
     }) => Promise<(TKind extends 'video' ? LocalVideoPreviewMetadata : ImagePreviewMetadata) | null>;
     /**
-     * 从本地视频提取仅供页面展示的高清 JPEG 封面，不上传、不下载、不写缓存。
+     * 从本地视频或已有截图生成气泡封面；传入消息身份时复用独立持久缓存，不下载或上传。
      *
      * 长边最多 960px 且不放大原视频；与发送预读共用同一解码执行器。返回 Blob 由宿主创建和释放
      * object URL，不能作为 localPreviewMetadata 发进消息正文。读取失败返回 null 并记录诊断；
      * 宿主取消抛 AbortError，运行时失效或未装配能力时抛与 prepareLocalPreview 相同的明确错误。
-     * @param input.file 本地或已解密的完整视频 Blob。
+     * @param input.file 本地或已解密的完整视频 Blob；已有 poster 时可以不传。
+     * @param input.poster 发送前已经提取的截图，避免重新加载视频抽帧。
+     * @param input.message 可选消息身份，用于持久保存封面。
+     * @param input.expectedResourceUrl 取得源文件前的资源地址，防止换图后的旧结果污染缓存。
      * @param input.signal 页面卸载、换源或切会话时取消这次抽帧。
      */
     prepareLocalVideoPoster: (input: {
-        file: Blob;
+        file?: Blob;
+        poster?: Blob;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /** 只读视频气泡封面缓存；不下载、不抽帧，未命中返回 null。 */
+    getCachedVideoPoster: (message: ImMessageRef, options?: {
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
     /**
@@ -5602,6 +5630,34 @@ interface ImMediaTasksApi {
         file: Blob;
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
+    /**
+     * 从本机原图生成独立的静态显示图，供 PC/H5 气泡使用；不下载、不上传、不改原图与消息尺寸。
+     * 传入消息引用时先查独立的显示图缓存；稳定远端资源的结果可持久保存，本地待上传资源只生成。
+     * 所有浏览器可解码格式均处理；最长边不超过 maxSize 且不放大，透明图优先保留透明度。
+     * WebP 质量 0.85，最低 0.82，目标 256 KiB、最多 512 KiB；超过字节预算时可继续缩小，失败返回 null 并记录诊断。
+     * 取消、账号失效、能力缺失和非法参数明确拒绝；返回 Blob 的 object URL 由宿主管理。
+     * @param input.file 原始或已解密的完整图片 Blob，不会被修改。
+     * @param input.maxSize 显示图最长边上限，必须是 1 到 2048 的整数。
+     * @param input.signal 页面退出、资源失效时取消准备。
+     * @param input.message 可选的精确消息引用，用于按消息、合集项、资源版本和尺寸隔离显示图缓存。
+     * @param input.expectedResourceUrl 取得 file 前记录的消息资源地址；与 message 配合使用，不匹配时返回 null，防止旧文件写入新资源缓存。
+     * @example const display = await client.media.prepareLocalImageDisplay({ file: original, maxSize: 1440 })
+     */
+    prepareLocalImageDisplay: (input: {
+        file: Blob;
+        maxSize: number;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /**
+     * 仅读取指定消息和尺寸的持久显示图，不下载原图、不编码；未命中或读取期间资源失效返回 null。
+     * maxSize 必须是 1 到 2048 的整数；取消、账号失效、存储读取失败明确拒绝。
+     */
+    getCachedImageDisplay: (message: ImMessageRef, options: {
+        maxSize: number;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
 }
 
 /**
@@ -6281,7 +6337,7 @@ interface ImSettingsApi {
  * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶并发请求复用和失败后重新签发由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
  *
  * 默认单次 PUT/GET；仅 multipartTransfer=true 才允许大资源分片上传、下载。
- * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，超过 16MiB 的上传另需放行
+ * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，达到 8 MiB 的上传另需放行
  * POST（Create/CompleteMultipartUpload）、DELETE（AbortMultipartUpload）并 ExposeHeaders: ETag。CORS 未配齐时
  * 下载还需暴露 Content-Range 与强 ETag；multipartTransfer=false 统一关闭分片上传和下载。
  * ⚠ 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
@@ -7140,6 +7196,8 @@ interface ChatMediaMessageRef {
      * 后绑定的一格把先绑定的挤掉并撤销其地址。单媒体消息不传这个字段。
      */
     itemIndex?: number;
+    /** 查询时校验当前正文资源地址；不匹配即未命中，不根据页面历史推断租约身份。 */
+    resourceUrl?: string;
 }
 /**
  * Chat Kit 提供给共享 Store 和业务 Service 的账号运行接口。
@@ -7332,8 +7390,9 @@ interface ChatRuntime {
      * 媒体上传成功并获得远端资源后，结束本地预览的“上传源”职责。
      *
      * 图片和视频保留为可淘汰本地缓存，使发送者短时间内查看无需重新下载；GIF 直接释放。
+     * resourceUrl 指定上传完成后的正文地址，用于绑定源文件身份；后续换地址会移除旧缓存。
      */
-    resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number) => void;
+    resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number, resourceUrl?: string) => void;
     /** 为指定消息取得本地媒体播放租约；没有本地缓存时返回 `undefined`，调用方应改用远端资源。 */
     acquireMediaBlob: (ref: ChatMediaMessageRef) => MediaObjectUrlLease | undefined;
     /** 只读检查完整本地媒体是否可用，不取得租约、不改变缓存淘汰顺序。 */

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

@@ -1272,13 +1272,13 @@ interface MediaTransferAdapterConfig {
     useAccelerateEndpoint?: boolean;
     /**
      * 统一允许 S3 分片上传和 Range 分段下载，默认 false（单次 PUT / 普通 GET）。
-     * 显式 true 后仍按 16MiB 阈值及已确认下载大小选择策略，小资源不分片。
+     * 显式 true 后，上传对象达到 8 MiB 使用 Multipart；上传片长与下载段长均为 16 MiB。
      * 开启前各桶须支持分片请求方法，并暴露上传 ETag、下载 Content-Range 与强 ETag。
      * @example { multipartTransfer: true } 同时允许大资源分片上传、下载。
      */
     multipartTransfer?: boolean;
     /**
-     * 总开关开启后，是否允许超过分片阈值（16MiB）的上传使用 S3 分片上传。
+     * 总开关开启后，是否允许达到分片阈值（8 MiB）的上传使用 S3 分片上传。
      *
      * 分片相比单次 PUT 需要各物理桶的 CORS 额外放行 POST（Create/CompleteMultipartUpload）、
      * DELETE（AbortMultipartUpload）并 `ExposeHeaders: ETag`；未配齐时分片会直接失败。
@@ -1294,8 +1294,8 @@ interface MediaTransferAdapterConfig {
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，限制媒体任务数而非分片请求数。
      *
-     * 并发按媒体体积分两档：不超过分片阈值（16 MiB）的非视频媒体走小文件档，
-     * 缺省 5；视频与超过阈值（或字节数未知）的内容走大文件档，缺省 3。
+     * 并发按媒体体积分两档：小于分片阈值（8 MiB）的非视频媒体走小文件档，
+     * 缺省 5；视频与达到阈值（或字节数未知）的内容走大文件档，缺省 3。
      * 分档只限制媒体任务数；实际 PUT/UploadPart 另受 adapter 的六路数据请求限制。
      * 两档都只接受 1-6 的整数，超出范围由 core 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -1581,7 +1581,7 @@ type ImRequestErrorHandler = (issue: ImRequestError) => void | Promise<void>;
  * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶并发请求复用和失败后重新签发由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
  *
  * 默认单次 PUT/GET；仅 multipartTransfer=true 才允许大资源分片上传、下载。
- * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，超过 16MiB 的上传另需放行
+ * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，达到 8 MiB 的上传另需放行
  * POST（Create/CompleteMultipartUpload）、DELETE（AbortMultipartUpload）并 ExposeHeaders: ETag。CORS 未配齐时
  * 下载还需暴露 Content-Range 与强 ETag；multipartTransfer=false 统一关闭分片上传和下载。
  * ⚠ 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
@@ -2079,6 +2079,8 @@ interface ThreadVisibilityTargetsOptions<TItem> {
     onScrollingChange?: (scrolling: boolean) => void;
     /** 节点在滚动停止后仍可见时首次触发，适合安排 cache-only 读取。 */
     onActivated?: (item: TItem) => void;
+    /** 当前与滚动根有实际交集的目标；滚动中仍更新，不受驻留、近邻范围或稳定数量限制。 */
+    onViewportVisibleChange?: (items: readonly TItem[]) => void;
     /** 每次稳定可见集合变化时触发，顺序按节点距离滚动根中心由近到远。 */
     onSettledVisibleChange?: (items: readonly TItem[]) => void;
     /** 激活和稳定集合要求的最小可见比例；默认只要有交集即可。 */

package/dist/chat-kit.d.ts

@@ -1940,7 +1940,7 @@ interface ImHttpPort {
 }
 
 /** 可持久化的媒体资产类型；未注册类型必须跳过缓存，不能回退到其它类型。 */
-type MediaAssetKind = 'image' | 'video' | 'file';
+type MediaAssetKind = 'image' | 'image-display' | 'video-poster' | 'video' | 'file';
 /** 持久媒体资产的稳定键。resourceVersion 由远端资源标识派生，避免同消息替换资源后误命中旧缓存。 */
 interface MediaAssetCacheKey {
     kind: MediaAssetKind;
@@ -1989,7 +1989,10 @@ interface MediaAssetCachePort {
     get: (key: MediaAssetCacheKey) => Promise<MediaAssetCacheEntry | null>;
     /** 按输入顺序检查完整资源是否存在且未过期；不读取 Blob、不延长闲置期限，存储故障必须抛出。 */
     hasMany?: (keys: readonly MediaAssetCacheKey[]) => Promise<readonly boolean[]>;
-    put: (entry: MediaAssetCacheEntry) => Promise<'stored' | 'skipped'>;
+    /** isCurrent 在排队结束和写事务开始前复核；已失效的生成结果返回 skipped，已开始的事务不撤销。 */
+    put: (entry: MediaAssetCacheEntry, options?: {
+        isCurrent?: () => boolean;
+    }) => Promise<'stored' | 'skipped'>;
     clear: () => Promise<void>;
     /** 删除超过闲置期限的完整持久副本；不撤销已经返回的 Blob 或宿主持有的播放地址。 */
     prune?: () => Promise<void>;
@@ -2853,12 +2856,12 @@ declare function canTransmit(message: ForwardCandidateMessage): boolean;
 type RecallFailReason = 'not-found' | 'not-own' | 'pinned' | 'not-sent' | 'expired' | 'unsupported' | 'timeout' | 'server-expired' | 'failed' | 'disconnected';
 
 /**
- * 根据缩略图签名选择 PNG 或 JPEG 的显示类型，供 SDK 和 PC/H5 创建 Blob、data URL。
- * 输入是消息中的原始字节或纯 base64；旧消息没有独立 MIME 字段，非 PNG 沿用 JPEG 解码，
+ * 根据缩略图签名选择 PNG、WebP 或 JPEG 的显示类型，供 SDK 和 PC/H5 创建 Blob、data URL。
+ * 输入是消息中的原始字节或纯 base64；旧消息没有独立 MIME 字段，未知格式沿用 JPEG 解码，
  * 损坏数据仍交给图片解码器报告失败。本函数不修改字节，也不将历史 JPEG 转码为 PNG。
  * @example resolveMediaThumbnailMimeType(new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10])) // 'image/png'
  */
-declare function resolveMediaThumbnailMimeType(source: Uint8Array | string): 'image/png' | 'image/jpeg';
+declare function resolveMediaThumbnailMimeType(source: Uint8Array | string): 'image/png' | 'image/webp' | 'image/jpeg';
 
 /** 浏览器 PushSubscription.toJSON() 的可移植数据；不依赖 DOM 或浏览器全局。 */
 interface ImWebPushSubscription {
@@ -3145,13 +3148,13 @@ interface MediaTransferAdapterConfig {
     useAccelerateEndpoint?: boolean;
     /**
      * 统一允许 S3 分片上传和 Range 分段下载，默认 false（单次 PUT / 普通 GET）。
-     * 显式 true 后仍按 16MiB 阈值及已确认下载大小选择策略，小资源不分片。
+     * 显式 true 后，上传对象达到 8 MiB 使用 Multipart；上传片长与下载段长均为 16 MiB。
      * 开启前各桶须支持分片请求方法，并暴露上传 ETag、下载 Content-Range 与强 ETag。
      * @example { multipartTransfer: true } 同时允许大资源分片上传、下载。
      */
     multipartTransfer?: boolean;
     /**
-     * 总开关开启后，是否允许超过分片阈值（16MiB）的上传使用 S3 分片上传。
+     * 总开关开启后，是否允许达到分片阈值（8 MiB）的上传使用 S3 分片上传。
      *
      * 分片相比单次 PUT 需要各物理桶的 CORS 额外放行 POST（Create/CompleteMultipartUpload）、
      * DELETE（AbortMultipartUpload）并 `ExposeHeaders: ETag`；未配齐时分片会直接失败。
@@ -3167,8 +3170,8 @@ interface MediaTransferAdapterConfig {
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，限制媒体任务数而非分片请求数。
      *
-     * 并发按媒体体积分两档：不超过分片阈值（16 MiB）的非视频媒体走小文件档，
-     * 缺省 5；视频与超过阈值（或字节数未知）的内容走大文件档，缺省 3。
+     * 并发按媒体体积分两档：小于分片阈值（8 MiB）的非视频媒体走小文件档，
+     * 缺省 5；视频与达到阈值（或字节数未知）的内容走大文件档，缺省 3。
      * 分档只限制媒体任务数；实际 PUT/UploadPart 另受 adapter 的六路数据请求限制。
      * 两档都只接受 1-6 的整数，超出范围由 core 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -3467,13 +3470,13 @@ interface MediaAlbumMessageOptions {
  * 本地视频的固有尺寸、时长与首帧封面。
  *
  * @remarks 宿主可从本地 object URL 解码首个可展示帧，使上传占位从首次渲染就使用真实比例和主图。
- * `posterData` 是等比缩放后的 JPEG（兼容已有 PNG）；存在时会作为消息 `thumbData` 随正文发送。宽高必须是有限正数，
+ * `posterData` 是等比缩放后的静态 WebP（兼容已有 JPEG/PNG）；存在时会作为消息 `thumbData` 随正文发送。宽高必须是有限正数，
  * duration 存在时必须是有限正数，posterData 必须是非空且不超过共享单项消息容量的 Uint8Array；合集发送会按项数复核容量。
  */
 interface VideoPreviewMetadata extends ImagePreviewMetadata {
     /** 秒。 */
     duration?: number;
-    /** 本地首个可展示帧生成的 JPEG 或已有 PNG 字节。 */
+    /** 本地首个可展示帧生成的 WebP 或已有 JPEG/PNG 字节。 */
     posterData?: Uint8Array;
 }
 /**
@@ -5508,6 +5511,17 @@ interface ImMessageRef {
      */
     itemIndex?: number;
 }
+/** 单次媒体下载的等待与调度选项；相同精确消息引用仍共用一次实际下载。 */
+interface ImMediaDownloadOptions {
+    /**
+     * 只取消本次调用；其它调用者仍需要结果时保留共享下载。
+     * 最后一个可取消调用者退出且没有无 signal 调用者时，才中止底层任务。
+     * 取消以 IM_SDK_MEDIA_DOWNLOAD_CANCELED 拒绝本次 Promise，不返回部分文件。
+     */
+    signal?: AbortSignal;
+    /** 默认 interactive；background 在空闲名额中排在交互下载之后，不能抢占已发请求。 */
+    priority?: 'background' | 'interactive';
+}
 /**
  * 可观察媒体上传/下载任务的只读产品投影。
  *
@@ -5606,7 +5620,8 @@ interface ImMediaTasksApi {
      */
     subscribe: (listener: (tasks: readonly ImMediaTask[]) => void) => () => void;
     /**
-     * 取消 queued/running 任务；上传委托 core，下载中止当前 AbortController。
+     * 取消 queued/running 任务；上传委托 core，下载中止共享任务并取消所有调用者。
+     * 只需结束某次下载等待时，应使用 download 的 signal。
      * @throws 未知任务、非法状态或底层未受理时以稳定 `IM_SDK_MEDIA_TASK_*` 错误拒绝。
      */
     cancel: (taskId: string, options?: {
@@ -5641,10 +5656,13 @@ interface ImMediaTasksApi {
         restartDownload?: boolean;
     }) => Promise<void>;
     /**
-     * 下载并按消息正文合同解密，同一消息并发调用复用同一 Promise，成功返回 Blob。
+     * 下载并按消息正文合同解密，同一精确消息引用共用实际下载，成功返回 Blob。
+     * 不带 signal 的并发调用保留共享 Promise；带 signal 的调用独立等待和取消，不影响其它调用者。
+     * 后加入的交互调用会提高共享下载优先级；prioritizeDownload 指定的最近预览仍优先于其它任务。
      * @throws 消息不存在/非媒体/无远端 URL/未装配 capability、传输失败、取消或 teardown 均以稳定错误拒绝，不返回空 Blob。
+     * @example const blob = await client.media.download(messageRef, { signal: controller.signal, priority: 'background' })
      */
-    download: (message: ImMessageRef) => Promise<Blob>;
+    download: (message: ImMessageRef, options?: ImMediaDownloadOptions) => Promise<Blob>;
     /**
      * 将最近预览的精确媒体项设为最高下载优先级，不新建或取消任务。
      * 下一空闲任务/分片请求名额优先给该项；已发请求不中断，关闭播放器不撤销优先级。
@@ -5660,7 +5678,7 @@ interface ImMediaTasksApi {
      */
     getCached: (message: ImMessageRef) => Promise<Blob | null>;
     /**
-     * 为宿主手里的**本地**图片/视频文件预读展示元信息：尺寸、视频时长、视频首帧封面的 JPEG 字节。
+     * 为宿主手里的**本地**图片/视频文件预读展示元信息：尺寸、视频时长、视频首帧封面的 WebP 字节。
      *
      * 给「发送前预览」这类场景用：宿主要在用户还没点发送时就把缩略图画出来，而浏览器读不出视频的
      * 首帧——`<video preload="metadata">` 在 iOS Safari 上只加载元信息、**不解码任何一帧**，
@@ -5668,7 +5686,7 @@ interface ImMediaTasksApi {
      *
      * 返回的对象可以**原样**作为 `localPreviewMetadata` 交给 `sendImage` / `sendVideo` /
      * `sendMediaAlbum`：发送链路会复用可用元信息；合集项超出其可用消息空间时重新生成封面。
-     * posterData 使用共享自适应发送规格（视频 JPEG，长边最多 960px，目标 8 KiB、硬上限 24 KiB）；includeDisplayPoster 可在同一次解码中额外生成
+     * posterData 使用共享自适应发送规格（视频 WebP，长边最多 1440px，目标 16 KiB、硬上限 32 KiB）；includeDisplayPoster 可在同一次解码中额外生成
      * 仅供页面显示的高清 displayPoster（长边最多 960），不得绕过发送校验直接用它替换 posterData。
      *
      * @param input.kind 按文件类型选解码路径；`'video'` 才会抽首帧与读时长。
@@ -5688,16 +5706,26 @@ interface ImMediaTasksApi {
         includeDisplayPoster?: boolean;
     }) => Promise<(TKind extends 'video' ? LocalVideoPreviewMetadata : ImagePreviewMetadata) | null>;
     /**
-     * 从本地视频提取仅供页面展示的高清 JPEG 封面，不上传、不下载、不写缓存。
+     * 从本地视频或已有截图生成气泡封面；传入消息身份时复用独立持久缓存，不下载或上传。
      *
      * 长边最多 960px 且不放大原视频；与发送预读共用同一解码执行器。返回 Blob 由宿主创建和释放
      * object URL，不能作为 localPreviewMetadata 发进消息正文。读取失败返回 null 并记录诊断；
      * 宿主取消抛 AbortError，运行时失效或未装配能力时抛与 prepareLocalPreview 相同的明确错误。
-     * @param input.file 本地或已解密的完整视频 Blob。
+     * @param input.file 本地或已解密的完整视频 Blob；已有 poster 时可以不传。
+     * @param input.poster 发送前已经提取的截图，避免重新加载视频抽帧。
+     * @param input.message 可选消息身份，用于持久保存封面。
+     * @param input.expectedResourceUrl 取得源文件前的资源地址，防止换图后的旧结果污染缓存。
      * @param input.signal 页面卸载、换源或切会话时取消这次抽帧。
      */
     prepareLocalVideoPoster: (input: {
-        file: Blob;
+        file?: Blob;
+        poster?: Blob;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /** 只读视频气泡封面缓存；不下载、不抽帧，未命中返回 null。 */
+    getCachedVideoPoster: (message: ImMessageRef, options?: {
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
     /**
@@ -5713,6 +5741,34 @@ interface ImMediaTasksApi {
         file: Blob;
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
+    /**
+     * 从本机原图生成独立的静态显示图，供 PC/H5 气泡使用；不下载、不上传、不改原图与消息尺寸。
+     * 传入消息引用时先查独立的显示图缓存；稳定远端资源的结果可持久保存，本地待上传资源只生成。
+     * 所有浏览器可解码格式均处理；最长边不超过 maxSize 且不放大，透明图优先保留透明度。
+     * WebP 质量 0.85，最低 0.82，目标 256 KiB、最多 512 KiB；超过字节预算时可继续缩小，失败返回 null 并记录诊断。
+     * 取消、账号失效、能力缺失和非法参数明确拒绝；返回 Blob 的 object URL 由宿主管理。
+     * @param input.file 原始或已解密的完整图片 Blob，不会被修改。
+     * @param input.maxSize 显示图最长边上限，必须是 1 到 2048 的整数。
+     * @param input.signal 页面退出、资源失效时取消准备。
+     * @param input.message 可选的精确消息引用，用于按消息、合集项、资源版本和尺寸隔离显示图缓存。
+     * @param input.expectedResourceUrl 取得 file 前记录的消息资源地址；与 message 配合使用，不匹配时返回 null，防止旧文件写入新资源缓存。
+     * @example const display = await client.media.prepareLocalImageDisplay({ file: original, maxSize: 1440 })
+     */
+    prepareLocalImageDisplay: (input: {
+        file: Blob;
+        maxSize: number;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /**
+     * 仅读取指定消息和尺寸的持久显示图，不下载原图、不编码；未命中或读取期间资源失效返回 null。
+     * maxSize 必须是 1 到 2048 的整数；取消、账号失效、存储读取失败明确拒绝。
+     */
+    getCachedImageDisplay: (message: ImMessageRef, options: {
+        maxSize: number;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
 }
 
 /**
@@ -6399,7 +6455,7 @@ interface ImEmojiCatalogEntry {
  * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶并发请求复用和失败后重新签发由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
  *
  * 默认单次 PUT/GET；仅 multipartTransfer=true 才允许大资源分片上传、下载。
- * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，超过 16MiB 的上传另需放行
+ * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，达到 8 MiB 的上传另需放行
  * POST（Create/CompleteMultipartUpload）、DELETE（AbortMultipartUpload）并 ExposeHeaders: ETag。CORS 未配齐时
  * 下载还需暴露 Content-Range 与强 ETag；multipartTransfer=false 统一关闭分片上传和下载。
  * ⚠ 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
@@ -7687,6 +7743,8 @@ interface ChatMediaMessageRef {
      * 后绑定的一格把先绑定的挤掉并撤销其地址。单媒体消息不传这个字段。
      */
     itemIndex?: number;
+    /** 查询时校验当前正文资源地址；不匹配即未命中，不根据页面历史推断租约身份。 */
+    resourceUrl?: string;
 }
 /**
  * Chat Kit 提供给共享 Store 和业务 Service 的账号运行接口。
@@ -7879,8 +7937,9 @@ interface ChatRuntime {
      * 媒体上传成功并获得远端资源后，结束本地预览的“上传源”职责。
      *
      * 图片和视频保留为可淘汰本地缓存，使发送者短时间内查看无需重新下载；GIF 直接释放。
+     * resourceUrl 指定上传完成后的正文地址，用于绑定源文件身份；后续换地址会移除旧缓存。
      */
-    resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number) => void;
+    resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number, resourceUrl?: string) => void;
     /** 为指定消息取得本地媒体播放租约；没有本地缓存时返回 `undefined`，调用方应改用远端资源。 */
     acquireMediaBlob: (ref: ChatMediaMessageRef) => MediaObjectUrlLease | undefined;
     /** 只读检查完整本地媒体是否可用，不取得租约、不改变缓存淘汰顺序。 */
@@ -8269,6 +8328,38 @@ type GifFileClassification = 'gif' | 'not-gif' | 'invalid-gif';
 declare function classifyGifFile(file: Blob): Promise<GifFileClassification>;
 declare function isGifFile(file: Blob): Promise<boolean>;
 
+/** 气泡显示图的像素规格；两端共用，完整原图和消息内嵌缩略图不使用此预算。 */
+declare function resolveImageDisplayMaxSize(message: ImMessageView, itemIndex?: number): number;
+/**
+ * 从借用的本机原图生成独立气泡地址。不会撤销输入 URL，也不会触发远端下载。
+ * identity 让 SDK 按完整资源身份复用持久显示缓存；调用方负责撤销返回的 URL。
+ * 预览必须继续使用原图，不能使用此方法的返回值。
+ */
+declare function prepareImageDisplayObjectUrl(runtime: ChatRuntime, url: string, maxSize: number, signal?: AbortSignal, identity?: {
+    message: ImMessageView;
+    itemIndex?: number;
+}): Promise<string | null>;
+/**
+ * 气泡优先读持久显示图；未命中才用已缓存的原图生成，不发起网络下载。
+ * 仅产生一个由调用方拥有的显示 URL，整个过程不创建或持有原图 URL。
+ */
+declare function loadCachedImageDisplayObjectUrl(runtime: ChatRuntime, message: ImMessageView, itemIndex?: number, signal?: AbortSignal): Promise<string | null>;
+/**
+ * 自动加载气泡显示图：优先恢复派生缓存或本机原图，均未命中才下载。
+ * 原图地址只在生成期间持有并始终释放；返回的独立显示地址归宿主。
+ * 显示缓存命中即可满足气泡，完整原件已被淘汰时留待用户预览再下载。
+ */
+declare function loadImageDisplayObjectUrl(runtime: ChatRuntime, message: ImMessageView, hooks: ServiceNoteHooks, options: ImMediaDownloadOptions, itemIndex?: number): Promise<string | null>;
+/**
+ * 借用本机视频地址或发送前截图生成气泡封面，优先命中持久缓存。
+ * 不触发远端下载；输入地址仍归调用方，返回的封面地址由调用方释放。
+ */
+declare function prepareVideoPosterObjectUrl(runtime: ChatRuntime, url: string, signal?: AbortSignal, identity?: {
+    message: ImMessageView;
+    itemIndex?: number;
+}, poster?: Blob): Promise<string | null>;
+/** 只恢复本机视频封面：先读派生缓存，未命中才读完整视频并抽帧；不触发视频下载。 */
+declare function loadCachedVideoPosterObjectUrl(runtime: ChatRuntime, message: ImMessageView, itemIndex?: number, signal?: AbortSignal): Promise<string | null>;
 /**
  * 将用户最后预览的媒体项交给 SDK 提高下载优先级，不创建任务或持有页面资源。
  * 在异步查缓存、加载 URL 之前调用，重复打开已有下载也会更新优先级。
@@ -8342,8 +8433,14 @@ declare function loadCachedVideoObjectUrl(runtime: ChatRuntime, message: ImMessa
  * 返回 `null` 表示下标越界、正文不是合集、内容非法或下载失败，失败原因经 `setNote` 反馈。
  * **唯一不反馈的失败是用户自己取消**（点击停止按钮取消这一项的在途下载）：同样返回 `null`，但不提示。
  * **调用方在不再使用地址时必须 `URL.revokeObjectURL`。**
+ * @param runtime 当前账号的运行时，用于访问 SDK 并阻止切账号后交付旧资源。
+ * @param message 包含媒体合集正文与精确会话身份的消息。
+ * @param itemIndex 要下载的合集项下标，从 0 开始。
+ * @param hooks 失败文案及提示入口；取消不提示失败。
+ * @param onProgress 可选的当前项下载进度回调，范围为 0–100。
+ * @param options 可选的下载优先级与本次调用取消信号；取消不影响同一资源的其它消费者，也不交付迟到的地址。
  */
-declare function loadMediaAlbumItemObjectUrl(runtime: ChatRuntime, message: ImMessageView, itemIndex: number, hooks: ServiceNoteHooks, onProgress?: (percent: number) => void): Promise<string | null>;
+declare function loadMediaAlbumItemObjectUrl(runtime: ChatRuntime, message: ImMessageView, itemIndex: number, hooks: ServiceNoteHooks, onProgress?: (percent: number) => void, options?: ImMediaDownloadOptions): Promise<string | null>;
 /**
  * 只读取合集某一项已持久化的明文资产并创建 object URL。
  *
@@ -8357,8 +8454,12 @@ declare function loadCachedMediaAlbumItemObjectUrl(runtime: ChatRuntime, message
  *
  * 解密结果不是已支持图片、内容为空或下载失败时返回 `null` 并显示明确提示，不把无效二进制交给
  * `<img>`。调用方关闭大图后必须撤销成功返回的地址。
+ * @param runtime 当前账号的运行时，用于访问 SDK 并阻止切账号后交付旧资源。
+ * @param message 包含原图正文与精确会话身份的消息。
+ * @param hooks 失败文案及提示入口；取消不提示失败。
+ * @param options 可选的下载优先级与本次调用取消信号；取消只结束本次等待并返回 null，不提示失败。
  */
-declare function loadImageObjectUrl(runtime: ChatRuntime, message: ImMessageView, hooks: ServiceNoteHooks): Promise<string | null>;
+declare function loadImageObjectUrl(runtime: ChatRuntime, message: ImMessageView, hooks: ServiceNoteHooks, options?: ImMediaDownloadOptions): Promise<string | null>;
 /**
  * 仅读取 SDK 已持久化的图片明文资产并创建 object URL。
  *
@@ -8376,31 +8477,43 @@ declare function loadFileObjectUrl(runtime: ChatRuntime, message: ImMessageView,
 declare const media_service_acquireMediaBlob: typeof acquireMediaBlob;
 declare const media_service_detectImageMime: typeof detectImageMime;
 declare const media_service_detectVideoMime: typeof detectVideoMime;
+declare const media_service_loadCachedImageDisplayObjectUrl: typeof loadCachedImageDisplayObjectUrl;
 declare const media_service_loadCachedImageObjectUrl: typeof loadCachedImageObjectUrl;
 declare const media_service_loadCachedMediaAlbumItemObjectUrl: typeof loadCachedMediaAlbumItemObjectUrl;
 declare const media_service_loadCachedVideoObjectUrl: typeof loadCachedVideoObjectUrl;
+declare const media_service_loadCachedVideoPosterObjectUrl: typeof loadCachedVideoPosterObjectUrl;
 declare const media_service_loadFileObjectUrl: typeof loadFileObjectUrl;
+declare const media_service_loadImageDisplayObjectUrl: typeof loadImageDisplayObjectUrl;
 declare const media_service_loadImageObjectUrl: typeof loadImageObjectUrl;
 declare const media_service_loadMediaAlbumItemObjectUrl: typeof loadMediaAlbumItemObjectUrl;
 declare const media_service_loadVideoObjectUrl: typeof loadVideoObjectUrl;
 declare const media_service_loadVoiceBytes: typeof loadVoiceBytes;
+declare const media_service_prepareImageDisplayObjectUrl: typeof prepareImageDisplayObjectUrl;
 declare const media_service_prepareLocalMediaPreview: typeof prepareLocalMediaPreview;
+declare const media_service_prepareVideoPosterObjectUrl: typeof prepareVideoPosterObjectUrl;
 declare const media_service_prioritizeMediaDownload: typeof prioritizeMediaDownload;
+declare const media_service_resolveImageDisplayMaxSize: typeof resolveImageDisplayMaxSize;
 declare namespace media_service {
   export {
     media_service_acquireMediaBlob as acquireMediaBlob,
     media_service_detectImageMime as detectImageMime,
     media_service_detectVideoMime as detectVideoMime,
+    media_service_loadCachedImageDisplayObjectUrl as loadCachedImageDisplayObjectUrl,
     media_service_loadCachedImageObjectUrl as loadCachedImageObjectUrl,
     media_service_loadCachedMediaAlbumItemObjectUrl as loadCachedMediaAlbumItemObjectUrl,
     media_service_loadCachedVideoObjectUrl as loadCachedVideoObjectUrl,
+    media_service_loadCachedVideoPosterObjectUrl as loadCachedVideoPosterObjectUrl,
     media_service_loadFileObjectUrl as loadFileObjectUrl,
+    media_service_loadImageDisplayObjectUrl as loadImageDisplayObjectUrl,
     media_service_loadImageObjectUrl as loadImageObjectUrl,
     media_service_loadMediaAlbumItemObjectUrl as loadMediaAlbumItemObjectUrl,
     media_service_loadVideoObjectUrl as loadVideoObjectUrl,
     media_service_loadVoiceBytes as loadVoiceBytes,
+    media_service_prepareImageDisplayObjectUrl as prepareImageDisplayObjectUrl,
     media_service_prepareLocalMediaPreview as prepareLocalMediaPreview,
+    media_service_prepareVideoPosterObjectUrl as prepareVideoPosterObjectUrl,
     media_service_prioritizeMediaDownload as prioritizeMediaDownload,
+    media_service_resolveImageDisplayMaxSize as resolveImageDisplayMaxSize,
   };
 }
 
@@ -9617,6 +9730,8 @@ declare function resolveMediaTransferPresentation(input: {
     aggregateFrom?: number;
     /** 宿主确实持有的完整本地资源；单条媒体以 undefined 表示，缩略图不属于完整资源。 */
     availableItemIndices?: readonly (number | undefined)[];
+    /** 仅气泡传入：已有清晰显示图或完整本机资源的项不显示下载胶囊；不能用作预览可用性证据。 */
+    displayAvailableItemIndices?: readonly (number | undefined)[];
     /** SDK 明确查到完整缓存已不存在；历史 completed 任务不能替代当前资源证据。 */
     unavailableItemIndices?: readonly (number | undefined)[];
     /** 当前窗口正在查询的媒体项，不表示未下载。 */