k2-im 0.2.16 → 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 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -5592,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>;
     /**
@@ -5617,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>;
 }
 
 /**
@@ -6296,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。
@@ -7155,6 +7196,8 @@ interface ChatMediaMessageRef {
      * 后绑定的一格把先绑定的挤掉并撤销其地址。单媒体消息不传这个字段。
      */
     itemIndex?: number;
+    /** 查询时校验当前正文资源地址；不匹配即未命中，不根据页面历史推断租约身份。 */
+    resourceUrl?: string;
 }
 /**
  * Chat Kit 提供给共享 Store 和业务 Service 的账号运行接口。
@@ -7347,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。

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>;
@@ -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 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -5703,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>;
     /**
@@ -5728,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>;
 }
 
 /**
@@ -6414,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。
@@ -7702,6 +7743,8 @@ interface ChatMediaMessageRef {
      * 后绑定的一格把先绑定的挤掉并撤销其地址。单媒体消息不传这个字段。
      */
     itemIndex?: number;
+    /** 查询时校验当前正文资源地址；不匹配即未命中，不根据页面历史推断租约身份。 */
+    resourceUrl?: string;
 }
 /**
  * Chat Kit 提供给共享 Store 和业务 Service 的账号运行接口。
@@ -7894,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;
     /** 只读检查完整本地媒体是否可用，不取得租约、不改变缓存淘汰顺序。 */
@@ -8284,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 之前调用，重复打开已有下载也会更新优先级。
@@ -8401,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,
   };
 }
 
@@ -9642,6 +9730,8 @@ declare function resolveMediaTransferPresentation(input: {
     aggregateFrom?: number;
     /** 宿主确实持有的完整本地资源；单条媒体以 undefined 表示，缩略图不属于完整资源。 */
     availableItemIndices?: readonly (number | undefined)[];
+    /** 仅气泡传入：已有清晰显示图或完整本机资源的项不显示下载胶囊；不能用作预览可用性证据。 */
+    displayAvailableItemIndices?: readonly (number | undefined)[];
     /** SDK 明确查到完整缓存已不存在；历史 completed 任务不能替代当前资源证据。 */
     unavailableItemIndices?: readonly (number | undefined)[];
     /** 当前窗口正在查询的媒体项，不表示未下载。 */