@lazycatcloud/vue-media-preview 0.1.2 → 0.1.4

package/docs/testing.md

@@ -149,3 +149,7 @@ AI、OCR、云端分享等入口显示明确的演示状态，不计为业务功
 在 Android WebView 远程调试中录制 Performance：刷新页面，打开尚未缩放的本地 JPEG，双指放大缩回，停两秒，再次放大缩回。按 pointerdown/pointerup 划分两轮，分别检查主线程 RunTask、GPU 图片解码/上传与 RAF 回调；不能用第二轮缓存后的手感代表首次性能。JPEG 在独立 Worker 从 Blob 解码并生成完整/运动 ImageBitmap 后才交给 Canvas，观察缩放区间是否仍出现同步 JPEG 解码长任务。额外验证切图、关闭、取消下载和缓存淘汰时没有使用已关闭的位图；检查 EXIF 旋转照片与非 JPEG 图片的方向、画幅和颜色。
 
 2026-10-29 在 Redmi Note 12 Turbo 的相册 WebView 实测：优化前首轮缩放有约 245ms 主线程任务，其中 JPEG 解码约 172ms。完整解码和运动位图缩放放入 Worker 后，五次快速打开后缩放的录制区间内，没有主线程 JPEG 解码或 GPU 图片解码缓存事件，RAF 绘制回调最大 0.32–0.99ms。仍观察到约 38–56ms 的整页样式更新，不能把绘制回调耗时当成完整帧耗时，也不能据此承诺所有设备无掉帧。用户真机反馈为“基本上不卡顿了”。
+
+## GIF 回归
+
+`imageResource.test.ts` 覆盖 GIF87a / GIF89a 文件头、错误 MIME、截断/不匹配头、解码失败与取消、共享租约和播放 URL 回收。`renderer.test.ts` 覆盖当前页/渲染/加载开关、返回恢复、保持同一 img 的缩放平移旋转、替换为普通图片和关闭转场租约。浏览器实测可在 Demo 中通过“添加”选择循环 GIF：打开后确认帧变化，缩放旋转后继续播放，切到普通图再返回，最后关闭；PC 与 mobile 两种模式都执行一遍。真实浏览器播放验证不能用 DOM 单测替代。

package/docs/vue-media-preview.md

@@ -139,7 +139,7 @@ function resolveAnchor(media: PreviewMedia): PreviewAnchor {
 
 这是独立组件库测试版，未修改相册仓库。Demo 不接真实相册 API，收藏只保留当前会话。
 
-尚未包含 GIF 连续播放、RAW 解码、HDR 色彩保真承诺、瓦片式超大图、业务路由/系统返回栈、OCR 与 AI 裁剪。已提供虚拟时间线与分页事件；真实相册的分页 API、业务路由和删除接口仍由适配层负责。
+尚未包含 RAW 解码、HDR 色彩保真承诺、瓦片式超大图、业务路由/系统返回栈、OCR 与 AI 裁剪。已提供 GIF 连续播放、虚拟时间线与分页事件；真实相册的分页 API、业务路由和删除接口仍由适配层负责。
 
 ## 相册 UI 外壳
 
@@ -207,3 +207,23 @@ const resolveImageSource = (media, quality, targetWidth) =>
 组件不管理焦点：打开、关闭及清空列表均不主动聚焦或恢复焦点，不拦截 Tab / Shift+Tab，也不提供自定义焦点框样式。Demo 弹层遵循同一规则。按钮和视频进度条沿用浏览器正常的焦点行为，视频进度条仍支持方向键、Home / End 定位；`keyboardEnabled` 只控制预览快捷键。
 
 `goTo(index)` 在会话打开时同步宿主下标；相邻项平滑翻页，跨多项直接定位。列表窗口更新按稳定 ID 保留当前项，仅调整其下标，不取消翻页动画或拖动；页面引用也以媒体 ID 管理。删除当前媒体才重新定位到邻项。`element` 是预览根元素，`canvasElement()` 返回当前图片画布，`mediaElement()` 返回当前解码媒体，`togglePlayback()` 控制视频播放。`ready(index, quality)` 仅报告当前页真实就绪。
+
+### 缩放边界
+
+图片以适应屏幕时的大小作为 1 倍，默认最大缩放为 16 倍；双击仍按画幅选择 2–8 倍。双指越过 1 倍或 16 倍时允许少量阻尼拉伸，松手或取消后平滑回到边界。剩余单指只平移，不会把这次缩放转成翻页或下拉关闭；再次接手回弹时从当前可见大小继续。
+
+### 快速下滑与关闭画面
+
+下滑关闭统一采用屏幕短边 14% 的距离阈值；快速下甩超过 16 CSS 像素且速度超过 0.35 CSS 像素/毫秒也会关闭。打开阶段与打开后的速度采样规则一致，松手前停顿 100 毫秒后不再按轻甩判定。
+
+打开动画期间的单指接触会保留到打开交接完成，再继续跟手下滑；若下滑已达到关闭阈值并提前松手，直接反向收回打开动画。宿主应在 `opening` 和 `open` 阶段允许 `gesturesEnabled`，关闭及其他交互覆盖层仍禁用。
+
+关闭动画通过 `retainFrame()` 持有像素，清晰图切换、请求取消及渲染器卸载不会提前释放该帧。持有者必须在完成、失败或取消时调用返回值的 `release()`；MediaPreview 统一在 `finally` 中释放。原有 `captureFrame()` 保持即时借用语义，跨异步操作持有画面应使用 `retainFrame()`。独立视频、实况合成帧和普通图片采用同一个帧持有协议。
+
+## GIF 资源与播放
+
+`core/resources/image/gif.ts` 按 GIF87a / GIF89a 文件头识别动图，不依赖 URL 后缀或响应 MIME。解码成功后保留独立的 Blob URL，并将 Blob 大小计入资源预算；取消或解码失败时不会创建播放地址。资源类型集中在 `core/resources/image/types.ts`，动画资源通过 `animation.kind` 标明播放能力，静态自定义 loader 的原有结构仍然有效。
+
+`ImageCanvasRenderer` 保留原有加载、质量升级与静态画面流程，仅在当前页可绘制且允许加载时显示 `renderers/image/AnimatedImageLayer.vue`。播放层复用 viewport 的尺寸、平移和旋转，缩放时不重建 img；原 Canvas 保留用于截图与转场，但播放期间隐藏，避免透明 GIF 与首帧叠加。静态 Canvas 恢复时继承父层可见性，避免共享转场隐藏页面后残留画面。离页、停止渲染、停止加载和卸载会移除播放层，缓存与转场租约共同决定 Blob URL 的最终释放时机。
+
+宿主仍须提供含完整 GIF 字节的地址。静态 thumbnail / previewSrc 不会恢复已被转换丢失的动画；可按现有策略调用 `original()` 加载 GIF 原文件，下载和像素限制保持生效。GIF 的循环次数由文件本身决定；静态截图与转场不承诺捕获正在显示的动画帧。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazycatcloud/vue-media-preview",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Vue 3 canvas media preview with shared element transitions, gestures, and virtual paging.",
   "private": false,
   "type": "module",