@linker-design-plus/timeline-track 1.0.9 → 1.0.11

package/README.md

@@ -1,26 +1,24 @@
 # @linker-design-plus/timeline-track
 
-基于 TypeScript 和 Konva.js 的高性能视频编辑时间线库，支持拖拽、缩放、分割等核心功能，集成了完整的操作历史记录和日志系统。
-
-## 核心功能
-
-- ✅ 交互式时间线，支持水平缩放（鼠标滚轮/触摸手势）
-- ✅ 视频轨道系统，支持多个片段的拖拽、调整大小、分割功能
-- ✅ 播放头指针，用于精确时间指示
-- ✅ 操作历史记录，支持撤销/重做功能
-- ✅ Canvas-based 渲染，确保高性能
-- ✅ 外部 API，用于片段管理、时间同步和播放控制
-- ✅ 片段碰撞检测，防止重叠
-- ✅ 片段边界限制，确保在轨道范围内
-- ✅ 原视频长度边界限制，确保剪辑不超出原视频范围
-- ✅ 日志系统，支持调试模式开关
-- ✅ 间隙移除功能，自动删除片段之间的间隙
-- ✅ 批量片段更新，提高性能
-- ✅ 历史记录变更通知事件，用于外部应用调整撤销/重做按钮状态
-- ✅ 播放倍速控制，支持 0.1x 到 10x 的播放速度
-- ✅ 轨道总时长计算，包含片段间隙
-- ✅ 封面系统，支持自定义缩略图提供器
-- ✅ 异步封面加载，支持 Promise 形式的封面获取
+基于 TypeScript 和 Konva 的时间线编辑组件库，提供单一主入口 `TimelineManager`，支持多轨片段编辑、缩放、分割、撤销重做、封面渲染以及多轨音视频预览播放。
+
+## 当前状态
+
+- 主线重构已完成，代码已收敛到单一轨道实现 `Track`
+- `TimelineManager` 仍是对外 façade，但内部职责已拆分到 store / commands / controller / adapter
+- 工具层和核心层已有回归测试覆盖，当前保持全量自动化回归
+- 交互约束与重构路线分别见 [docs/interaction-model.md](./docs/interaction-model.md) 和 [docs/refactor-roadmap.md](./docs/refactor-roadmap.md)
+
+## 能力概览
+
+- 多轨时间线编辑，支持视频轨和音频轨
+- 片段拖拽、拉伸、分割、跨轨移动、自动避让重叠
+- 单一选中态，避免多个 clip 同时处于最终选中状态
+- 播放头、滚动、缩放和时间同步
+- 撤销 / 重做 / 历史变更通知
+- 缩略图提供器与异步封面加载
+- 多轨视频层级叠加预览与多轨音频混合播放
+- 预览容器挂载、buffering 状态与预览比例同步
 
 ## 安装
 
@@ -30,402 +28,360 @@ npm install @linker-design-plus/timeline-track
 
 ## 快速开始
 
-### 基本用法
-
-```typescript
+```ts
 import { TimelineManager } from '@linker-design-plus/timeline-track';
 
-// 获取容器元素
-const timelineContainer = document.getElementById('timeline-container');
-const videoElement = document.getElementById('video-element') as HTMLVideoElement;
+const container = document.getElementById('timeline-container') as HTMLDivElement;
+const preview = document.getElementById('preview-container') as HTMLDivElement;
+
+const timeline = new TimelineManager({
+  container,
+  debug: true,
+  zoom: 100,
+  currentTime: 0,
+  previewBackend: 'dom',
+  previewSourceResolver: (clip) => {
+    if (clip.src.endsWith('.mp4')) {
+      return {
+        url: clip.src,
+        mimeType: 'video/mp4',
+        kind: 'mp4'
+      };
+    }
+
+    if (clip.src.endsWith('.m3u8')) {
+      return {
+        url: clip.src,
+        mimeType: 'application/vnd.apple.mpegurl',
+        kind: 'hls-fmp4'
+      };
+    }
 
-// 创建 TimelineManager 实例
-const timelineManager = new TimelineManager({
-  container: timelineContainer,
-  debug: true, // 开启调试模式
+    return null;
+  }
 });
 
-// 连接到视频元素（可选）
-timelineManager.connectTo(videoElement);
+timeline.attachPreview(preview);
 
-// 添加片段
-const clipId = await timelineManager.addClip({
+await timeline.addClip({
   src: 'sample-video.mp4',
   name: 'Clip 1',
-  startTimeAtSource: 0, // 源视频中的开始时间（毫秒）
-  duration: 5000, // 片段持续时间（毫秒）
-  thumbnail: 'https://example.com/thumbnail1.jpg' // 可选：直接提供封面图片
+  startTimeAtSource: 0,
+  duration: 5000,
+  visualTransform: {
+    x: 0.5,
+    y: 0.5,
+    scale: 1
+  },
+  thumbnails: ['https://example.com/thumb-1.jpg']
 });
 
-// 开始播放
-timelineManager.play();
-
-// 设置播放倍速
-timelineManager.setSpeed(2); // 2 倍速
-
-// 适合缩放（自动调整缩放比例以适应所有片段）
-timelineManager.fitZoom();
-
-// 分割当前时间点的片段
-timelineManager.splitCurrentClip();
-
-// 移除片段之间的间隙
-timelineManager.removeClipGaps();
-
-// 监听历史记录变更事件
-timelineManager.on('history_change', (event, data) => {
-  console.log('History changed:', data);
-  // 更新撤销/重做按钮状态
-  updateUndoRedoButtons(data.canUndo, data.canRedo);
+timeline.on('history_change', (_event, data) => {
+  console.log('canUndo', data.canUndo, 'canRedo', data.canRedo);
 });
 
-// 销毁时间轴管理器
-// timelineManager.destroy();
+timeline.play();
 ```
 
-### 封面系统用法
+## 缩略图提供器
+
+`ThumbnailProvider` 使用 `getThumbnails(clip)`，返回 `string[]` 或 `Promise<string[]>`。
+音频 clip 默认不会使用缩略图渲染，`thumbnailProvider` 主要作用于视频 clip。
 
-```typescript
-import { TimelineManager, ThumbnailProvider } from '@linker-design-plus/timeline-track';
+```ts
+import { TimelineManager, type ThumbnailProvider } from '@linker-design-plus/timeline-track';
 
-// 创建缩略图提供器
 const thumbnailProvider: ThumbnailProvider = {
-  getThumbnail(clip) {
-    // 同步获取封面
-    return `https://example.com/thumbnails/${clip.id}.jpg`;
-    
-    // 或异步获取封面
-    // return new Promise((resolve) => {
-    //   // 模拟异步获取封面
-    //   setTimeout(() => {
-    //     resolve(`https://example.com/thumbnails/${clip.id}.jpg`);
-    //   }, 100);
-    // });
+  async getThumbnails(clip) {
+    return [
+      `https://example.com/thumbnails/${clip.id}/0.jpg`,
+      `https://example.com/thumbnails/${clip.id}/1.jpg`
+    ];
   }
 };
 
-// 创建 TimelineManager 实例时设置缩略图提供器
-const timelineManager = new TimelineManager({
-  container: timelineContainer,
-  thumbnailProvider: thumbnailProvider
+const timeline = new TimelineManager({
+  container,
+  thumbnailProvider
 });
 
-// 或动态设置缩略图提供器
-timelineManager.setThumbnailProvider(thumbnailProvider);
-
-// 添加片段时，会自动通过提供器获取封面
-const clipId = await timelineManager.addClip({
-  src: 'sample-video.mp4',
-  name: 'Clip 1',
-  duration: 5000
-});
+timeline.setThumbnailProvider(thumbnailProvider);
+await timeline.refreshAllClipThumbnails();
 ```
 
-### Vue 3 集成
-
-```vue
-<template>
-  <div class="app">
-    <div class="video-container">
-      <video ref="videoElement" class="video" controls playsinline></video>
-    </div>
-    
-    <div class="controls">
-      <button @click="togglePlay">{{ isPlaying ? 'Pause' : 'Play' }}</button>
-      <button @click="fitZoom">适合缩放</button>
-      <button @click="removeClipGaps">移除间隙</button>
-      <button @click="undo" :disabled="!canUndo">Undo</button>
-      <button @click="redo" :disabled="!canRedo">Redo</button>
-      <button @click="addClip">Add Clip</button>
-      <button @click="splitClip">Split Clip</button>
-    </div>
-
-    <div class="timeline-container" ref="timelineContainer"></div>
-
-    <div class="info-panel">
-      <div>Current Time: {{ formattedTime }}</div>
-      <div>Zoom: {{ zoom }} px/s</div>
-      <div>Clips: {{ clipCount }}</div>
-      <div>Status: {{ isPlaying ? 'Playing' : 'Paused' }}</div>
-      <div>Speed: {{ speed }}x</div>
-    </div>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref, onMounted, onUnmounted, computed } from 'vue';
-import { TimelineManager } from '@linker-design-plus/timeline-track';
-
-// 容器引用
-const timelineContainer = ref<HTMLDivElement | null>(null);
-const videoElement = ref<HTMLVideoElement | null>(null);
-
-// 状态
-const isPlaying = ref(false);
-const currentTime = ref(0);
-const zoom = ref(100);
-const clipCount = ref(0);
-const canUndo = ref(false);
-const canRedo = ref(false);
-const speed = ref(1.0);
-
-// TimelineManager 实例
-let timelineManager: TimelineManager | null = null;
-
-// 格式化时间显示
-const formattedTime = computed(() => {
-  const totalSeconds = Math.floor(currentTime.value / 1000);
-  const hours = Math.floor(totalSeconds / 3600);
-  const minutes = Math.floor((totalSeconds % 3600) / 60);
-  const seconds = totalSeconds % 60;
-  return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
-});
-
-// 初始化
-onMounted(async () => {
-  if (!timelineContainer.value) return;
-
-  // 创建 TimelineManager 实例
-  timelineManager = new TimelineManager({
-    container: timelineContainer.value,
-    debug: true,
-  });
-
-  // 连接到视频元素
-  if (videoElement.value) {
-    timelineManager.connectTo(videoElement.value);
-  }
-
-  // 添加事件监听器
-  timelineManager.on('time_change', (event, data) => {
-    currentTime.value = data.time;
-  });
-
-  timelineManager.on('play_state_change', (event, data) => {
-    isPlaying.value = data.playState === 'playing';
-  });
-
-  timelineManager.on('zoom_change', (event, data) => {
-    zoom.value = data.zoom;
-  });
-
-  timelineManager.on('history_change', (event, data) => {
-    canUndo.value = data.canUndo;
-    canRedo.value = data.canRedo;
-  });
-
-  timelineManager.on('speed_change', (event, data) => {
-    speed.value = data.speed;
-  });
-
-  // 添加示例片段
-  await addSampleClips();
-  updateClipCount();
-
-  // 初始设置
-  zoom.value = timelineManager.getZoom();
-  speed.value = timelineManager.getSpeed();
-});
-
-// 清理
-onUnmounted(() => {
-  timelineManager?.destroy();
-});
-
-// 控制方法
-const togglePlay = () => timelineManager?.togglePlay();
-const undo = () => timelineManager?.undo();
-const redo = () => timelineManager?.redo();
-const fitZoom = () => timelineManager?.fitZoom();
-const removeClipGaps = () => timelineManager?.removeClipGaps();
-
-// 添加片段
-const addClip = async () => {
-  if (!timelineManager) return;
-  
-  const clipId = await timelineManager.addClip({
-    src: 'sample-video.mp4',
-    name: `Clip ${Date.now()}`,
-    duration: 5000,
-    startTimeAtSource: 0
-  });
-  updateClipCount();
-};
-
-// 分割片段
-const splitClip = () => timelineManager?.splitCurrentClip();
-
-// 更新片段计数
-const updateClipCount = () => {
-  if (timelineManager) {
-    clipCount.value = timelineManager.getClips().length;
-  }
-};
+## 对外主 API
+
+### `TimelineManager`
+
+常用方法：
+
+- `play()` / `pause()` / `togglePlay()`
+- `setCurrentTime(time)` / `getCurrentTime()`
+- `setZoom(zoom)` / `getZoom()`
+- `setSpeed(speed)` / `getSpeed()`
+- `addClip(config)` / `addClips(configs)`
+- `updateClip(clipId, updates)` / `removeClip(clipId)`
+- `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
+- `canSeparateClipAudio(clipId)` / `separateClipAudio(clipId)` / `canRestoreClipAudio(clipId)` / `restoreClipAudio(clipId)`
+- `splitCurrentClip()` / `removeClipGaps()` / `fitZoom()`
+- `undo()` / `redo()` / `clearHistory()`
+- `attachPreview(containerOrConfig)` / `detachPreview()`
+- `getPreviewBackendType()`
+- `getCurrentActiveClips()` / `getActiveClipsAtTime(time)`
+- `getPreviewAspectRatio()` / `setPreviewAspectRatio({ width, height })` / `resetPreviewAspectRatioToAuto()`
+- `exportTimeline()`
+
+常用事件：
+
+- `time_change`
+- `play_state_change`
+- `speed_change`
+- `zoom_change`
+- `preview_aspect_ratio_change`
+- `clip_added`
+- `clip_removed`
+- `clip_updated`
+- `clip_selected`
+- `selected_clip_change`
+- `history_change`
+- `track_duration_change`
+- `buffering_state_change`
+- `can_play_change`
+- `source_loading_change`
+
+## 核心类型
+
+```ts
+interface ClipConfig {
+  id?: string;
+  type?: 'video' | 'audio';
+  externalId?: string;
+  src: string;
+  name: string;
+  isMuted?: boolean;
+  startTime?: number;
+  duration: number;
+  startTimeAtSource?: number;
+  endTimeAtSource?: number;
+  sourceDuration?: number;
+  thumbnails?: string[];
+  style?: Record<string, any>;
+  visualTransform?: {
+    x: number;
+    y: number;
+    scale: number;
+  };
+  separatedAudioClipId?: string;
+  separatedFromVideoClipId?: string;
+}
+```
 
-// 添加示例片段
-const addSampleClips = async () => {
-  if (!timelineManager) return;
-  
-  const clips = [
-    {
-      src: 'sample1.mp4',
-      name: 'Clip 1',
-      startTimeAtSource: 0,
-      duration: 5000
-    },
-    {
-      src: 'sample2.mp4',
-      name: 'Clip 2',
-      startTimeAtSource: 0,
-      duration: 8000
+当 `type: 'audio'` 时，clip 会渲染为音频卡片样式：内置音频图标、装饰性波形和文件名，不展示视频缩略图。
+视频 clip 可通过 `visualTransform` 控制预览中的归一化位置和等比缩放，默认值为 `{ x: 0.5, y: 0.5, scale: 1 }`。
+视频 clip 分离原声后会写入 `separatedAudioClipId`，对应音频 clip 会写入 `separatedFromVideoClipId`。
+导出时间线时会包含 `composition`、轨道 `order` / `isMuted`、clip `isMuted` 和视频 clip 的 `visualTransform`，便于后端按当前多轨预览语义做合成。
+
+### 预览后端
+
+`TimelineManager` 现在支持双预览后端：
+
+- `previewBackend: 'dom'`
+  当前默认后端，使用多媒体元素叠层完成多轨预览，兼容性最好。
+- `previewBackend: 'canvas'`
+  第一阶段的新预览后端，使用 Canvas2D + WebCodecs 进行视频解码与单画布合成。
+- `previewBackend: 'auto'`
+  在支持的浏览器中优先使用 `canvas`，否则自动回退到 `dom`。
+
+配合 `canvas` / `auto` 后端，建议显式提供 `previewSourceResolver`，让编辑预览使用代理 MP4：
+
+```ts
+const timeline = new TimelineManager({
+  container,
+  previewBackend: 'canvas',
+  previewSourceResolver: (clip) => {
+    if (!clip.src.endsWith('.mp4')) {
+      return clip.src.endsWith('.m3u8')
+        ? {
+            url: clip.src,
+            mimeType: 'application/vnd.apple.mpegurl',
+            kind: 'hls-fmp4'
+          }
+        : null;
     }
-  ];
 
-  for (const clip of clips) {
-    await timelineManager.addClip(clip);
+    return {
+      url: clip.src,
+      mimeType: 'video/mp4',
+      kind: 'mp4'
+    };
   }
-  
-  timelineManager.clearHistory();
-};
-</script>
-
-<style scoped>
-/* 样式省略 */
-</style>
+});
 ```
 
-## API 文档
-
-### TimelineManager
-
-#### 构造函数
-
-```typescript
-new TimelineManager(config?: Partial<TimelineConfig>)
+当前阶段限制：
+
+- `canvas` 后端仅面向 Chrome / Edge 桌面端
+- 视频预览源支持 MP4，以及 `EXT-X-MAP + m4s` 形式的 fMP4 HLS
+- 暂不支持基于 TS 分片的 HLS，也不支持 DRM 流
+- Firefox / Safari 会自动回退到 `dom` 后端
+
+## 当前代码架构
+
+### 入口与 façade
+
+- [src/index.ts](./src/index.ts)
+- [src/core/facade/timelineManager.ts](./src/core/facade/timelineManager.ts)
+
+### 组件层
+
+- [src/components/timeline/Timeline.tsx](./src/components/timeline/Timeline.tsx)
+- [src/components/track/Track.tsx](./src/components/track/Track.tsx)
+- [src/components/track/Clip.tsx](./src/components/track/Clip.tsx)
+- [src/components/timeline/Playhead.tsx](./src/components/timeline/Playhead.tsx)
+- [src/components/panel/TrackInfoPanel.tsx](./src/components/panel/TrackInfoPanel.tsx)
+
+### 核心状态与命令
+
+- `timelineStore` / `selectionStore` / `playbackStore` / `viewportStore`
+- `timelineCommands`
+- `timelineHistoryRecorder` / `timelineHistoryExecutor`
+
+### façade 已拆出的控制器与适配层
+
+- `timelineEventDispatcher`
+- `timelineTrackInfoPanelController`
+- `timelinePlaybackResolver`
+- `timelinePreviewSession`
+- `timelineSelectionController`
+- `timelineDurationController`
+- `timelineClipEventController`
+- `timelinePresentationAdapter`
+- `timelineTrackBridge`
+- `timelineTrackCollection`
+- `timelineTrackLayout`
+
+### 工具层
+
+- `clipVisualRenderer`
+- `clipCoverRenderer`
+- `timelineGridDrawing`
+- `timeUtils`
+- `KonvaUtils`
+
+### 目录结构
+
+```text
+src/
+  components/   Konva 组件和交互 helper
+  core/         状态、命令、controller、façade、类型
+  utils/        渲染与通用工具
+  styles/       样式入口
+  index.ts      对外导出
+docs/
+  interaction-model.md
+  refactor-roadmap.md
+demo/
+  App.vue
+  main.ts
 ```
 
-**参数：**
-- `config`：配置选项
-  - `container`：容器元素
-  - `debug`：是否开启调试模式，默认 false
-  - `duration`：总时长（毫秒），默认 3600000
-  - `zoom`：缩放比例（像素/秒），默认 100
-  - `currentTime`：初始当前时间（毫秒），默认 0
-  - `playState`：初始播放状态，默认 'paused'
-  - `speed`：初始播放倍速，默认 1.0
-  - `thumbnailProvider`：缩略图提供器，用于获取片段封面
-
-#### 核心方法
-
-| 方法名 | 描述 | 参数 | 返回值 |
-|--------|------|------|--------|
-| `play()` | 开始播放 | 无 | 无 |
-| `pause()` | 暂停播放 | 无 | 无 |
-| `togglePlay()` | 切换播放状态 | 无 | 无 |
-| `setCurrentTime(time)` | 设置当前时间 | `time`：时间（毫秒） | 无 |
-| `getCurrentTime()` | 获取当前时间 | 无 | `number` |
-| `setZoom(zoom)` | 设置缩放比例 | `zoom`：缩放比例（像素/秒） | 无 |
-| `getZoom()` | 获取缩放比例 | 无 | `number` |
-| `setSpeed(speed)` | 设置播放倍速 | `speed`：播放倍速 | 无 |
-| `getSpeed()` | 获取当前播放倍速 | 无 | `number` |
-| `setThumbnailProvider(provider)` | 设置缩略图提供器 | `provider`：缩略图提供器 | 无 |
-| `addClip(clipConfig)` | 添加片段 | `clipConfig`：片段配置 | `Promise<string>`（片段 ID） |
-| `removeClip(clipId)` | 移除片段 | `clipId`：片段 ID | 无 |
-| `removeSelectedClip()` | 移除当前选中的片段 | 无 | `boolean`（是否成功） |
-| `splitCurrentClip()` | 分割当前时间点的片段 | 无 | 无 |
-| `removeClipGaps()` | 移除片段之间的间隙 | 无 | 无 |
-| `fitZoom()` | 自动调整缩放比例以适应所有片段 | 无 | 无 |
-| `getClips()` | 获取所有片段 | 无 | `Clip[]` |
-| `getCurrentClip()` | 获取当前时间点所在的片段 | 无 | `Clip` 或 `null` |
-| `getSelectedClip()` | 获取当前选中的片段 | 无 | `Clip` 或 `null` |
-| `getTrackTotalDuration()` | 获取轨道总时长（包含间隙） | 无 | `number` |
-| `exportTimeline()` | 导出时间轴数据 | 无 | `TimelineExportData` |
-| `undo()` | 撤销操作 | 无 | `boolean`（是否成功） |
-| `redo()` | 重做操作 | 无 | `boolean`（是否成功） |
-| `clearHistory()` | 清空历史记录 | 无 | 无 |
-| `connectTo(video)` | 连接到视频元素 | `video`：视频元素 | 无 |
-| `on(event, listener)` | 添加事件监听器 | `event`：事件类型，`listener`：事件监听器 | 无 |
-| `off(event, listener)` | 移除事件监听器 | `event`：事件类型，`listener`：事件监听器 | 无 |
-| `destroy()` | 销毁时间轴管理器 | 无 | 无 |
-
-#### 事件
-
-| 事件名 | 描述 | 数据 |
-|--------|------|------|
-| `time_change` | 当前时间变化 | `{ time: number }` |
-| `play_state_change` | 播放状态变化 | `{ playState: 'playing' \| 'paused' }` |
-| `speed_change` | 播放倍速变化 | `{ speed: number }` |
-| `clip_added` | 添加片段 | `{ clip: Clip }` |
-| `clip_removed` | 移除片段 | `{ clipId: string }` |
-| `clip_updated` | 更新片段 | `{ clip: Clip }` |
-| `clip_selected` | 选择片段 | `{ clip: Clip }` |
-| `zoom_change` | 缩放比例变化 | `{ zoom: number }` |
-| `history_change` | 历史记录变更 | `{ canUndo: boolean, canRedo: boolean }` |
-| `track_duration_change` | 轨道总时长变化 | `{ duration: number }` |
-| `buffering_state_change` | 视频缓冲状态变化 | `{ isBuffering: boolean }` |
-
-### ClipConfig 接口
-
-```typescript
-interface ClipConfig {
-  src: string; // 视频源 URL
-  name?: string; // 片段名称
-  duration: number; // 片段持续时间（毫秒）
-  startTimeAtSource?: number; // 源视频中的开始时间（毫秒）
-  startTime?: number; // 片段在轨道上的起始时间（可选，自动计算）
-  thumbnail?: string; // 缩略图 URL
-}
+## 架构图级别说明
+
+### 分层关系图
+
+```mermaid
+flowchart TB
+  API["Public API\nsrc/index.ts"] --> FACADE["TimelineManager façade\nsrc/core/facade/timelineManager.ts"]
+
+  FACADE --> STORES["Stores\nTimelineStore / PlaybackStore / SelectionStore / ViewportStore"]
+  FACADE --> COMMANDS["Commands\nTimelineCommands"]
+  FACADE --> CONTROLLERS["Controllers\nclip workflow / track mutation / playback / selection / duration / event dispatcher"]
+  FACADE --> HISTORY["History\nHistoryManager / Recorder / Executor"]
+  FACADE --> TRACKS["Tracks\nTrackManager / TimelineTrackBridge / TimelineTrackCollection"]
+  FACADE --> PRESENTATION["Presentation\nTimelinePresentationAdapter"]
+  FACADE --> PREVIEW["Preview Backend\nDomPreviewBackend / CanvasPreviewBackend"]
+  FACADE --> COMPONENTS["Konva Views\nTimeline / Track / Clip / Playhead / TrackInfoPanel"]
+
+  COMPONENTS --> INTERACTION["Interaction\nglobalPointerDragSession / trackInteractionState"]
+  COMPONENTS --> UTILS["Utils\ntime / rendering / logging"]
+
+  TRACKS --> COMPONENTS
+  COMMANDS --> STORES
+  CONTROLLERS --> STORES
+  CONTROLLERS --> HISTORY
+  CONTROLLERS --> TRACKS
+  PRESENTATION --> COMPONENTS
+  PREVIEW --> STORES
 ```
 
-## 开发指南
-
-### 安装依赖
-
-```bash
-npm install
+### 运行时职责图
+
+```mermaid
+flowchart LR
+  USER["用户操作\n拖拽 / 拉伸 / 分割 / 播放"] --> VIEW["组件层\nTrack / Clip / Timeline"]
+  VIEW --> BRIDGE["TrackBridge / 回调桥接"]
+  BRIDGE --> WORKFLOW["Controllers\n工作流编排"]
+  WORKFLOW --> COMMANDS2["Commands\n领域规则与变更计划"]
+  COMMANDS2 --> STATE["Stores + TrackCollection\n时间轴状态与轨道集合"]
+  WORKFLOW --> HISTORY2["History\n记录 undo / redo"]
+  WORKFLOW --> PREVIEW2["Preview Session\n同步多轨预览"]
+  STATE --> PRESENTATION2["PresentationAdapter\n把状态转换为渲染输入"]
+  PRESENTATION2 --> VIEW
+  WORKFLOW --> EVENTS["EventDispatcher\n对外事件通知"]
 ```
 
-### 开发模式
-
-```bash
-npm run dev
-```
+### 核心分层说明
 
-### 构建
+- `src/index.ts`：对外导出层，暴露 `TimelineManager`、组件、`HistoryManager`、`TrackManager` 与模型类型。
+- `src/core/facade/timelineManager.ts`：系统总入口，负责装配 store、commands、controllers、history、preview backend 与 Konva 视图。
+- `src/core/stores/`：保存当前时间、播放状态、选中态、视口等最小状态源。
+- `src/core/commands/`：封装纯领域规则，例如选中、查找 clip、跨轨移动准备、轨道放置规划。
+- `src/core/controllers/`：把用户行为编排成完整工作流，处理副作用、事件派发、预览同步与轨道/clip 变更。
+- `src/core/tracks/`：管理轨道集合、轨道桥接和轨道级别操作，是 façade 与 `Track` 组件之间的中间层。
+- `src/core/presentation/`：把核心状态适配为视图输入，降低 façade 与 Konva 组件之间的耦合。
+- `src/components/`：Konva 视图层，负责时间轴、轨道、clip、滚动条、播放头和面板渲染。
+- `src/components/interaction/`：处理全局拖拽会话与交互状态机，保证拖拽移动/结束在窗口级别可靠收敛。
+- `src/core/history/`：记录命令结果，提供撤销/重做闭环。
+- `src/core/controllers/*Preview*`：抽象预览后端，支持 `dom` 与 `canvas` 两套多轨预览实现。
 
-```bash
-npm run build
-```
+### 典型调用链路
 
-### 预览构建结果
+#### 1. Clip 拖拽/跨轨移动
 
-```bash
-npm run preview
-```
+1. 用户在 `Track` / `Clip` 上产生指针操作。
+2. `trackInteractionState` 识别当前操作类型，`globalPointerDragSession` 保证拖拽期间的全局 move/end 监听。
+3. `Track` 通过回调把变更意图交给 `TimelineTrackBridge` 与 façade。
+4. façade 调用 `timelineTrackMutationController`、`timelineClipWorkflowController`、`TimelineCommands` 计算目标轨道、位置与合法性。
+5. 轨道集合与 store 更新后，同步写入 history，并触发重绘、事件通知与预览刷新。
 
-## 浏览器兼容性
+#### 2. 播放与时间推进
 
-- Chrome (推荐)
-- Firefox
-- Safari
-- Edge
+1. `TimelineManager` 持有播放状态与当前时间。
+2. `TimelinePlaybackResolver` 与预览 session 根据当前时间解析 active clips。
+3. `DomPreviewBackend` 或 `CanvasPreviewBackend` 执行多轨音视频预览。
+4. 时间变化通过 `TimelineEventDispatcher` 向外发布 `time_change`、`play_state_change` 等事件。
 
-## 许可证
+### 当前架构特点
 
-MIT
+- 对外仍保持单一 façade：调用方只需面向 `TimelineManager`。
+- 内部已经拆成 store / commands / controllers / tracks / presentation，职责边界比早期单体 manager 更清晰。
+- UI 交互和领域规则分离：交互细节主要留在 `components`，领域决策集中在 `core`。
+- 预览后端可替换：预览能力通过 backend 抽象扩展，而不是直接耦合到时间轴视图。
+- 历史系统贯穿工作流：新增、删除、更新、跨轨移动都能进入 undo / redo 闭环。
 
-## 贡献
+## 开发
 
-欢迎提交 Issue 和 Pull Request！
+```bash
+pnpm install
+pnpm run dev
+pnpm run build
+pnpm test
+pnpm exec tsc -p tsconfig.json --noEmit
+```
 
-## 更新日志
+## 浏览器支持
 
-### v1.0.0-beta.1
-- 首次发布
-- 基于 TypeScript 和 Konva.js 构建
-- 实现核心视频编辑时间线功能
-- 支持片段拖拽、调整大小、分割
-- 集成操作历史记录系统
-- 支持播放倍速控制
-- 提供完整的外部 API
-- 包含 TypeScript 类型声明
+- Chrome
+- Edge
+- Firefox（`dom` 后端）
+- Safari（`dom` 后端）