@linker-design-plus/timeline-track 2.1.0 → 2.1.1

package/README.md

@@ -2,24 +2,7 @@
 
 基于 TypeScript、Konva 和 Vue demo 的时间线编辑组件库，对外以 `TimelineManager` 为统一入口，提供多轨片段编辑、拖拽/拉伸/分割、撤销重做、选中态同步、封面渲染和预览挂载能力。时间轴主体仍由 Konva 驱动，播放指针使用独立的 SVG/DOM 覆盖层渲染。
 
-## 当前状态
-
-- 主线重构已经完成，仓库已从“双轨实现 + 大量兼容层”收敛到单一轨道组件 `Track`
-- `TimelineManager` 仍然是 façade，但内部已经拆分为 `stores`、`commands`、`controllers`、`tracks`、`presentation`
-- 当前发布包实际内置的预览实现是 `DomPreviewBackend`
-- `previewBackend` 配置仍然保留，但当前实现会统一解析到 `dom`，不要把 `canvas` / `auto` 视为已交付能力
-- 仓库内保留了较完整的回归测试，适合继续做功能收敛和架构瘦身
-
-## 审计结论
-
-本轮已完成一次针对仓库现状的维护梳理，并同步修正了以下残留：
-
-- 修复了 3 处测试残留，使 `pnpm test` 与 `pnpm exec tsc -p tsconfig.json --noEmit` 恢复通过
-- 清理了 `pixi` 预览类型和 demo 入口中的过期选项
-- 把 README 与重构路线文档改为“当前真实状态”，不再把未交付的 canvas 预览写成已完成能力
-- 把 `build` 脚本改为直接调用本地 `tsc`，避免 `npm run build:types` 带来的环境告警
-
-更细的维护记录见 [docs/maintenance-audit.md](./docs/maintenance-audit.md)。
+当前版本已经收敛到单一 `Track` 实现。预览侧真实交付的 backend 只有 `DomPreviewBackend`；`previewBackend` 配置仍保留兼容输入，但运行时会统一解析到 `dom`。
 
 ## 安装
 
@@ -66,35 +49,17 @@ timeline.on('history_change', (_event, data) => {
 });
 ```
 
-### 预览资源缓存
-
-预览资源缓存默认关闭。开启后，可被前端 `fetch` 读取且不超过 100MB 的 `http:` / `https:` 音视频文件会被缓存到浏览器存储中，用于后续预览播放。默认策略为 30 天 TTL、10GB 应用级容量上限、优先 OPFS，并在 OPFS 不可用时降级到 IndexedDB Blob。缓存失败会自动回退原始媒体 URL。
-
-```ts
-const timeline = new TimelineManager({
-  container,
-  previewBackend: 'dom',
-  resourceCache: {
-    enabled: true,
-    resolveMode: 'prefer-fast-start'
-  }
-});
-```
-
-第一版不会缓存 HLS manifest / 分片，也不会缓存超过 100MB 的媒体文件。
-
 ## 核心能力
 
-- 多轨时间线编辑，支持视频轨和音频轨
+- 多轨时间线编辑，支持视频轨、音频轨和文本片段
 - 片段拖拽、拉伸、分割、跨轨移动和重叠避让
-- 单一选中态与批量拖拽
+- 多选、框选与批量拖拽
 - 播放头、缩放、滚动和时间同步
 - 撤销 / 重做 / 历史变更通知
-- 缩略图提供器与异步封面加载
-- 预览容器挂载、预览比例同步和当前激活片段解析
-- 草稿导入导出、音视频分离/恢复等编辑工作流
+- 预览挂载、比例同步和当前激活片段解析
+- 草稿导入导出、音视频分离 / 恢复等编辑工作流
 
-## 主要 API
+## API 概览
 
 常用方法：
 
@@ -104,30 +69,30 @@ const timeline = new TimelineManager({
 - `setSpeed(speed)` / `getSpeed()`
 - `addClip(config)` / `addClips(configs)`
 - `updateClip(clipId, updates)` / `removeClip(clipId)`
-- `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
+- `selectClip(clipId)` / `setSelection(ids)` / `clearSelection()`
 - `splitCurrentClip()` / `removeClipGaps()`
-- `getRenderedHeight()`
 - `undo()` / `redo()` / `clearHistory()`
 - `attachPreview(containerOrConfig)` / `detachPreview()`
-- `exportTimeline()` / `loadDraft(data)`
+- `exportTimeline()` / `importTimeline(data)`
 
-快捷键配置：
+配音配置面板：
 
-- `keyboardShortcuts: false` 可彻底关闭快捷键
-- `keyboardShortcuts.bindings` 可按动作覆盖默认键位
-- 时间轴挂载后默认在当前页面生效
+- `attachClipConfig(container, options)` 返回 `TimelineClipConfigController`
+- 内建 `generateVoiceBatch` 流程会自动展示 / 关闭“配音生成中”全屏 loading
+- 外部自定义配音流程也可以手动调用 `controller.showVoiceGenerationLoading()` 和 `controller.hideVoiceGenerationLoading()`
 
-默认快捷键：
+```ts
+const controller = timeline.attachClipConfig(clipConfigContainer, {
+  voiceCatalog
+});
 
-- 播放 / 暂停：`Space`
-- 删除片段：`Delete` / `Backspace`
-- 复制片段：`Mod+C`
-- 剪切片段：`Mod+X`
-- 粘贴片段：`Mod+V`
-- 分离 / 还原音频：`Mod+Alt+A`
-- 分割片段：`Mod+B`
-- 撤销：`Mod+Z`
-- 还原：`Mod+Shift+Z`，Windows 另支持 `Ctrl+Y`
+controller.showVoiceGenerationLoading();
+try {
+  await customGenerateVoice();
+} finally {
+  controller.hideVoiceGenerationLoading();
+}
+```
 
 常用事件：
 
@@ -137,86 +102,30 @@ const timeline = new TimelineManager({
 - `clip_added`
 - `clip_removed`
 - `clip_updated`
-- `clip_selected`
 - `selected_clip_change`
 - `history_change`
 - `track_duration_change`
 - `buffering_state_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;
-  };
-  trackId?: string;
-  volume?: number;
-}
-```
-
-## 预览实现说明
+## 兼容与边界
 
-- 当前代码路径实际只会创建 `DomPreviewBackend`
-- `previewBackend` 字段被保留，目的是不给后续预览实现扩展制造额外 breaking change
-- 如果你在业务接入层看到 `canvas` / `auto` 配置，请把它当作保留参数，而不是当前版本的有效能力
-- 挂载预览且当前时间命中视频片段时，播放时间由预览视频的真实媒体时钟驱动；媒体 buffering 或 stalled 导致画面没有前进时，播放指针也不会继续超前
-- 多视频叠加播放时，任意一路 active 视频仍在加载或卡顿，预览层会暂停整个 active 播放组，等当前时刻所有视频都 ready 后统一恢复
+- 当前代码路径只会创建 `DomPreviewBackend`
+- `canvas` / `auto` 仍可作为兼容输入传入，但不应视为已交付能力
+- 挂载预览且当前时间命中视频片段时，时间轴会消费预览视频的真实媒体时钟
 - 空白段、纯音频、文本或未挂载预览时，播放仍回退到 `TimelineManager` 的 wall-clock 推进
 
-## 架构概览
-
-```mermaid
-flowchart TB
-  API["Public API\nsrc/index.ts"] --> FACADE["TimelineManager\nsrc/core/facade/timelineManager.ts"]
-  FACADE --> STORES["Stores\nTimeline / Selection / Playback / Viewport"]
-  FACADE --> COMMANDS["Commands\nTimelineCommands"]
-  FACADE --> CONTROLLERS["Controllers\nworkflow / selection / duration / playback / events"]
-  FACADE --> TRACKS["Tracks\nTrackManager / Bridge / Collection"]
-  FACADE --> PRESENTATION["Presentation\nTimelinePresentationAdapter"]
-  FACADE --> PREVIEW["Preview\nDomPreviewBackend"]
-  FACADE --> COMPONENTS["Presentation Views\nTimeline / Track / Clip / Panels / ManagedPlayhead"]
-```
+## 预览资源缓存
+
+预览资源缓存默认关闭。开启后，前端可直接 `fetch` 的音视频资源会被缓存到浏览器存储中，用于后续预览复用；缓存失败时会自动回退原始媒体 URL。完整边界和配置说明见 [docs/resource-cache.md](./docs/resource-cache.md)。
 
-当前最值得关注的热点：
-
-- `src/core/facade/timelineManager.ts` 仍然超过 4k 行，是后续最重要的瘦身目标
-- `src/components/track/Track.tsx` 内部还保留一层 `legacy` 交互镜像，用于兼容旧拖拽状态
-- `src/utils/rendering/KonvaUtils.ts` 仍偏大，适合继续拆分为更小的渲染工具模块
-- `demo/App.vue` 既承担演示又承担诊断面板职责，维护成本偏高
-
-## 目录结构
-
-```text
-src/
-  components/   时间轴视图、SVG/DOM 覆盖层与交互 helper
-  core/         stores / commands / controllers / facade / models
-  utils/        渲染、时间和日志工具
-  styles/       样式入口
-  index.ts      对外导出
-docs/
-  interaction-model.md
-  maintenance-audit.md
-  refactor-roadmap.md
-demo/
-  App.vue
-  main.ts
+```ts
+const timeline = new TimelineManager({
+  container,
+  resourceCache: {
+    enabled: true
+  }
+});
 ```
 
 ## 开发
@@ -229,10 +138,11 @@ pnpm 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/refactor-roadmap.md](./docs/refactor-roadmap.md): 主线重构归档与后续收敛方向
-- [docs/maintenance-audit.md](./docs/maintenance-audit.md): 本轮仓库审计、验证结果和依赖建议
-- [docs/review-remediation-plan.md](./docs/review-remediation-plan.md): 基于审查结论的修复计划与阶段性落地建议

package/dist/components/panel/ClipConfigPanel.d.ts

@@ -105,6 +105,8 @@ export declare class ClipConfigPanel {
     setClip(clip: Clip | null): void;
     setSelectionState(selectionState: ClipConfigPanelSelectionState): void;
     setPreferredTab(tab: 'voice' | null): void;
+    showVoiceGenerationLoading(): void;
+    hideVoiceGenerationLoading(): void;
     setVoiceGenerationBusy(isBusy: boolean): void;
     destroy(): void;
     private render;

package/dist/core/controllers/index.d.ts

@@ -13,4 +13,5 @@ export { TimelinePreviewStateController, type TimelinePendingPreviewState } from
 export { TimelineKeyboardShortcutsController, type TimelineKeyboardShortcutsControllerCallbacks } from './timelineKeyboardShortcutsController';
 export * from './timelineSelectionController';
 export * from './timelineTrackMutationController';
+export { TimelineClipConfigController } from './timelineClipConfigController';
 export { TimelineTrackInfoPanelController } from './timelineTrackInfoPanelController';

package/dist/core/controllers/timelineClipConfigController.d.ts

@@ -18,6 +18,8 @@ export declare class TimelineClipConfigController {
     updateFromExternal(): void;
     destroy(): void;
     setPreferredTab(tab: 'voice' | null): void;
+    showVoiceGenerationLoading(): void;
+    hideVoiceGenerationLoading(): void;
     setVoiceGenerationBusy(isBusy: boolean): void;
     private buildSelectionState;
     private resolveUpdateTargets;

package/dist/core/controllers/timelinePreviewSession.d.ts

@@ -85,6 +85,7 @@ export declare class TimelinePreviewSession {
     private readonly deferredPreloadSlotKeys;
     private deferredPreloadFlushScheduled;
     private lastSyncedPlayState;
+    private pendingClockAlignmentTargetTime;
     constructor(callbacks?: TimelinePreviewSessionCallbacks, dependencies?: TimelinePreviewSessionDependencies);
     private requestPauseIfPlaying;
     private emitDiagnostic;
@@ -162,6 +163,12 @@ export declare class TimelinePreviewSession {
     private buildPreviewClockStateFromSlot;
     private resolveClockBlockedReason;
     private getPreviewClockSourceSlot;
+    private buildPreviewClockSourceCandidate;
+    private comparePreviewClockSourceCandidates;
+    private isPreviewClockCandidateAlignedToTarget;
+    private getPreviewClockTargetAlignmentThresholdMs;
+    private isPreviewClockSlotAlignedToPendingTarget;
+    private updatePendingClockAlignmentTarget;
     private syncActivePlaybackGroupSuspension;
     private getSlotMediaTimeMs;
     private getSlotTimelineTime;

package/dist/core/facade/timelineManager.d.ts

@@ -61,6 +61,7 @@ export declare class TimelineManager {
     private lastSelectedClipId;
     private previewAspectRatio;
     private readonly bodyViewportScrollListener;
+    private stageMouseDownListener;
     private readonly bodyCanvasHostClickListener;
     private readonly rootWheelListener;
     private keyboardShortcutsController;
@@ -155,7 +156,6 @@ export declare class TimelineManager {
     private getTracksSortedByOrder;
     private getPlaybackTracksSnapshot;
     private buildPlaybackPlan;
-    private hasTimelineVideoClip;
     private playbackPlanHasActiveVideoClip;
     private hasActiveTimelineVideoClip;
     private getPreviewAutoAspectRatioClipOrderMap;
@@ -169,6 +169,8 @@ export declare class TimelineManager {
     private syncPreviewPlaybackStateIfNeeded;
     private shouldUsePreviewClockPlayback;
     private handlePreviewClockStateChange;
+    private isPreviewClockForCurrentActiveClip;
+    private shouldCommitUnavailablePreviewClock;
     private commitPlaybackTimeFromPreviewClock;
     private syncPreviewAfterPreviewClockCommitIfNeeded;
     private resumeWallClockPlaybackIfPreviewClockUnavailable;
@@ -353,6 +355,9 @@ export declare class TimelineManager {
     private findClipById;
     private buildGeneratedAudioClipName;
     private normalizeGeneratedAudioDuration;
+    private resolveVoiceTextContent;
+    private findSourceTextClipForTtsAudio;
+    private resolveTtsAudioVoiceGenerationSource;
     private getVoiceLinkedAudioClips;
     private hasVoiceLinkedAudioClipsToRegenerate;
     private scheduleVoiceLinkedTextRegeneration;

package/dist/core/history/history.d.ts

@@ -37,7 +37,7 @@ export declare class HistoryManager {
     /**
      * 创建添加片段操作
      */
-    createAddClipAction(clip: Clip): AddClipAction;
+    createAddClipAction(clip: Clip, targetTrackId?: string | null, targetTrackSnapshot?: Track | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): AddClipAction;
     /**
      * 创建移除片段操作
      */

package/dist/core/history/timelineHistoryExecutor.d.ts

@@ -23,6 +23,7 @@ export declare class TimelineHistoryExecutor {
     private executeRedoInternal;
     private restoreMovedClip;
     private normalizeRemoveClipActionData;
+    private normalizeAddClipActionData;
     private resolveTrackIdForHistorySnapshot;
     private resolveRestoreAnchor;
 }

package/dist/core/history/timelineHistoryRecorder.d.ts

@@ -4,8 +4,8 @@ export declare class TimelineHistoryRecorder {
     private readonly history;
     private readonly transactionStack;
     constructor(history: HistoryManager);
-    createAddClipAction(clip: Clip): Action;
-    recordAddClip(clip: Clip): Action;
+    createAddClipAction(clip: Clip, targetTrackId?: string | null, targetTrackSnapshot?: Track | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
+    recordAddClip(clip: Clip, targetTrackId?: string | null, targetTrackSnapshot?: Track | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     createRemoveClipAction(clip: Clip, sourceTrackId?: string | null, sourceTrackSnapshot?: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     recordRemoveClip(clip: Clip, sourceTrackId?: string | null, sourceTrackSnapshot?: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     recordClipUpdate(clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]): Action | null;

package/dist/core/models/constants.d.ts

@@ -9,6 +9,20 @@ export declare const ZOOM_PRESETS: {
     LARGE: number;
     MAX: number;
 };
+export declare const DEFAULT_TIMELINE_DURATION_MS = 3600000;
+export declare const ZOOM_GESTURE: {
+    SENSITIVITY_FACTOR: number;
+    CONVERGENCE_THRESHOLD: number;
+};
+export declare const DEFAULT_TEXT_CLIP_DURATION_MS = 3000;
+export declare const VOICE_LINKED_TEXT_REGEN_DEBOUNCE_MS = 450;
+export declare const SNAP_SCORING: {
+    ANCHOR_INDEX_WEIGHT: number;
+};
+export declare const TEXT_CLIP_FONT_SIZE_LIMITS: {
+    MIN: number;
+    MAX: number;
+};
 export declare const ZOOM_ANIMATION: {
     DURATION: number;
     EASING: string;

package/dist/core/models/types.d.ts

@@ -58,6 +58,8 @@ export interface VoiceOption {
     audiofile?: string;
     source?: Record<string, unknown>;
 }
+export declare function isAudioOnlyTtsClipCandidate(clip: Pick<ClipConfig, 'type' | 'textContent' | 'ttsVoiceId'> | Pick<ClipEntity, 'type' | 'textContent' | 'ttsVoiceId'> | Pick<Clip, 'type' | 'textContent' | 'ttsVoiceId'>): boolean;
+export declare function isTtsAudioClip(clip: Pick<ClipConfig, 'type' | 'ttsSourceTextClipId' | 'textContent' | 'ttsVoiceId'> | Pick<ClipEntity, 'type' | 'ttsSourceTextClipId' | 'textContent' | 'ttsVoiceId'> | Pick<Clip, 'type' | 'ttsSourceTextClipId' | 'textContent' | 'ttsVoiceId'>): boolean;
 export interface GenerateVoiceRequest {
     requestId: string;
     sourceTextClipId: string;
@@ -270,9 +272,15 @@ export interface ClipStateUpdate {
     newState: Clip;
     previousState: Clip;
 }
+export type AddClipActionData = Clip | {
+    clip: Clip;
+    targetTrackId: string | null;
+    targetTrackSnapshot: Track | null;
+    targetTrackRestoreAnchor: TrackRestoreAnchor | null;
+};
 export interface AddClipAction {
     type: 'add_clip';
-    data: Clip;
+    data: AddClipActionData;
     timestamp: number;
 }
 export interface RemoveClipAction {