# @linker-design-plus/timeline-track

基于 TypeScript、Konva 和 Vue demo 的时间线编辑组件库，对外以 `TimelineManager` 为统一入口，提供多轨片段编辑、拖拽/拉伸/分割、撤销重做、选中态同步、封面渲染和预览挂载能力。时间轴主体仍由 Konva 驱动，播放指针使用独立的 SVG/DOM 覆盖层渲染。

当前版本已经收敛到单一 `Track` 实现。预览侧真实交付的 backend 只有 `DomPreviewBackend`；`previewBackend` 配置仍保留兼容输入，但运行时会统一解析到 `dom`。

## 安装

```bash
pnpm add @linker-design-plus/timeline-track konva
```

## 快速开始

```ts
import { TimelineManager } from '@linker-design-plus/timeline-track';

const container = document.getElementById('timeline-container') as HTMLDivElement;
const preview = document.getElementById('preview-container') as HTMLDivElement;

const timeline = new TimelineManager({
  container,
  zoom: 100,
  currentTime: 0,
  previewBackend: 'dom',
  keyboardShortcuts: {
    bindings: {
      togglePlay: 'Mod+Alt+P'
    }
  }
});

timeline.attachPreview(preview);

await timeline.addClip({
  src: 'sample-video.mp4',
  name: 'Clip 1',
  startTimeAtSource: 0,
  duration: 5000,
  visualTransform: {
    x: 0.5,
    y: 0.5,
    scale: 1
  }
});

timeline.on('history_change', (_event, data) => {
  console.log(data.canUndo, data.canRedo);
});
```

## 核心能力

- 多轨时间线编辑，支持视频轨、音频轨和文本片段
- 片段拖拽、拉伸、分割、跨轨移动和重叠避让
- 多选、框选与批量拖拽
- 播放头、缩放、滚动和时间同步
- 撤销 / 重做 / 历史变更通知
- 预览挂载、比例同步和当前激活片段解析
- 草稿导入导出、音视频分离 / 恢复等编辑工作流

## API 概览

常用方法：

- `play()` / `pause()` / `togglePlay()`
- `setCurrentTime(time)` / `getCurrentTime()`
- `setZoom(zoom)` / `fitZoom()`
- `setSpeed(speed)` / `getSpeed()`
- `addClip(config)` / `addClips(configs)`
- `updateClip(clipId, updates)` / `removeClip(clipId)`
- `selectClip(clipId)` / `setSelection(ids)` / `clearSelection()`
- `splitCurrentClip()` / `removeClipGaps()`
- `undo()` / `redo()` / `clearHistory()`
- `attachPreview(containerOrConfig)` / `detachPreview()`
- `exportTimeline()` / `importTimeline(data)`

配音配置面板：

- `attachClipConfig(container, options)` 返回 `TimelineClipConfigController`
- 内建 `generateVoiceBatch` 流程会自动展示 / 关闭“配音生成中”全屏 loading
- 外部自定义配音流程也可以手动调用 `controller.showVoiceGenerationLoading()` 和 `controller.hideVoiceGenerationLoading()`

```ts
const controller = timeline.attachClipConfig(clipConfigContainer, {
  voiceCatalog
});

controller.showVoiceGenerationLoading();
try {
  await customGenerateVoice();
} finally {
  controller.hideVoiceGenerationLoading();
}
```

常用事件：

- `time_change`
- `play_state_change`
- `zoom_change`
- `clip_added`
- `clip_removed`
- `clip_updated`
- `selected_clip_change`
- `history_change`
- `track_duration_change`
- `buffering_state_change`
- `source_loading_change`

## 兼容与边界

- 当前代码路径只会创建 `DomPreviewBackend`
- `canvas` / `auto` 仍可作为兼容输入传入，但不应视为已交付能力
- 挂载预览且当前时间命中视频片段时，时间轴会消费预览视频的真实媒体时钟
- 空白段、纯音频、文本或未挂载预览时，播放仍回退到 `TimelineManager` 的 wall-clock 推进

## 预览资源缓存

预览资源缓存默认关闭。开启后，前端可直接 `fetch` 的音视频资源会被缓存到浏览器存储中，用于后续预览复用；缓存失败时会自动回退原始媒体 URL。完整边界和配置说明见 [docs/resource-cache.md](./docs/resource-cache.md)。

```ts
const timeline = new TimelineManager({
  container,
  resourceCache: {
    enabled: true
  }
});
```

## 开发

```bash
pnpm install
pnpm dev
pnpm build
pnpm test
pnpm harness:test
pnpm exec tsc -p tsconfig.json --noEmit
```

## 文档

- [docs/README.md](./docs/README.md): 文档入口
- [docs/architecture-overview.md](./docs/architecture-overview.md): 当前架构、模块边界、运行链路
- [docs/implementation-notes.md](./docs/implementation-notes.md): selection、preview、resource cache、draft 的实现笔记
- [docs/resource-cache.md](./docs/resource-cache.md): 预览资源缓存的能力边界与配置
- [docs/interaction-model.md](./docs/interaction-model.md): 指针交互分层和拖拽约束
- [docs/preview-playback-recovery-flow.md](./docs/preview-playback-recovery-flow.md): 预览媒体时钟驱动播放、buffering 阻塞与恢复续播流程
- [docs/testing-harness-roadmap.md](./docs/testing-harness-roadmap.md): Harness Engineering 导向的测试与诊断重构方案
