Initial TrueGrowth source import

docs/MEDIA_PREVIEW_TRACKPAD_ZOOM_LESSONS.md

@@ -0,0 +1,77 @@
+# 媒体预览触控板缩放经验
+
+更新日期：2026-04-30
+
+## 背景
+
+图片、视频预览里使用触控板放大缩小时，缩放速度太快，细微手势也会明显跳变，导致用户很难停在想要的比例。
+
+这类问题不要只看“最大/最小缩放值”。真正影响手感的通常是 wheel 事件的粒度、单次缩放步进、连续事件同步方式。
+
+## 根因
+
+### 1. 高频 wheel 不能用固定大步进
+
+触控板会连续发出很多小 `wheel` 事件。若每次都固定 `+0.1` 或 `-0.1`，微小手势也会被放大成大幅缩放。
+
+经验：
+
+- 触控板/滚轮缩放要按 `deltaY` 计算比例，而不是只看方向。
+- 要限制单个事件最大缩放量，防止鼠标滚轮或系统加速度造成跳变。
+- `deltaMode` 不是像素时要先归一化，避免不同设备手感差异过大。
+
+### 2. 首次自适应不能制造视觉跳动
+
+预览容器、图片/视频元信息和 CSS 尺寸可能不是同一帧就绪。如果先显示原始比例，再下一帧自适应，会让用户看到明显跳动。
+
+经验：
+
+- 首次进入预览时可以等 auto-fit 计算完成后再显示媒体内容。
+- 容器尺寸变化要重新触发 auto-fit，但用户手动拖拽/缩放后不要再自动覆盖视图。
+- auto-fit 相关隐藏样式要只作用于媒体内容，不影响工具栏和视频控件交互状态。
+
+### 3. 连续缩放要读取最新值
+
+React 事件回调在高频输入下容易遇到闭包值滞后。连续 wheel 中如果一直基于旧 `localZoom` 计算，会让缩放节奏不稳定。
+
+经验：
+
+- 高频交互中的当前值可用 `ref` 保存。
+- 状态更新仍走 `setState`，但计算基准优先读 ref 中的最新缩放。
+- 只有缩放值实际变化超过极小阈值时才通知父层，减少无意义渲染。
+
+### 4. 同步模式不要传相对增量
+
+媒体预览内部已经算出了目标缩放值，父层若再用 `z - zoomLevel` 转为相对增量，高频事件下容易叠加闭包误差。
+
+经验：
+
+- 子组件已经得到目标 zoom 时，父级 action 应支持设置绝对缩放值。
+- 快捷键、按钮这类明确步进仍适合保留相对 `zoom(delta)`。
+- wheel/pinch 这类连续输入更适合 `setZoomLevel(value)`。
+
+## 修复规则
+
+1. 媒体预览 wheel 缩放按归一化 `deltaY` 计算。
+2. 单次 wheel 缩放增量必须有限幅。
+3. 首次 auto-fit 完成前隐藏媒体内容，避免先大后小的闪跳。
+4. 用户手动拖拽/缩放后，auto-fit 不再覆盖当前视图。
+5. 触控板缩放基准值使用 ref 保持最新。
+6. 父层同步缩放使用绝对值 setter，避免连续事件误差。
+7. 按钮和快捷键步进保持原有节奏，不和触控板手感绑定。
+
+## 验证清单
+
+- 图片预览中触控板轻推时缩放变化更细。
+- 视频预览中触控板轻推时缩放变化更细。
+- 工具栏放大/缩小按钮仍按原步进工作。
+- 对比联动模式下缩放同步稳定，不出现过度叠加。
+- `pnpm nx typecheck drawnix` 通过。
+
+## 相关文件
+
+- `packages/drawnix/src/components/shared/media-preview/MediaViewport.tsx`
+- `packages/drawnix/src/components/shared/media-preview/MediaViewport.scss`
+- `packages/drawnix/src/components/shared/media-preview/useViewerState.ts`
+- `packages/drawnix/src/components/shared/media-preview/UnifiedMediaViewer.tsx`
+- `packages/drawnix/src/components/shared/media-preview/types.ts`