@linker-design-plus/timeline-track 2.0.4 → 2.0.5

package/README.md

@@ -1,29 +1,30 @@
 # @linker-design-plus/timeline-track
 
-基于 TypeScript 和 Konva 的时间线编辑组件库，提供单一主入口 `TimelineManager`，支持多轨片段编辑、缩放、分割、撤销重做、封面渲染以及多轨音视频预览播放。
+基于 TypeScript、Konva 和 Vue demo 的时间线编辑组件库，对外以 `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)
+- 主线重构已经完成，仓库已从“双轨实现 + 大量兼容层”收敛到单一轨道组件 `Track`
+- `TimelineManager` 仍然是 façade，但内部已经拆分为 `stores`、`commands`、`controllers`、`tracks`、`presentation`
+- 当前发布包实际内置的预览实现是 `DomPreviewBackend`
+- `previewBackend` 配置仍然保留，但当前实现会统一解析到 `dom`，不要把 `canvas` / `auto` 视为已交付能力
+- 仓库内保留了较完整的回归测试，适合继续做功能收敛和架构瘦身
 
-## 能力概览
+## 审计结论
 
-- 多轨时间线编辑，支持视频轨和音频轨
-- 片段拖拽、拉伸、分割、跨轨移动、自动避让重叠
-- 单一选中态，避免多个 clip 同时处于最终选中状态
-- 播放头、滚动、缩放和时间同步
-- 撤销 / 重做 / 历史变更通知
-- 缩略图提供器与异步封面加载
-- 多轨视频层级叠加预览与多轨音频混合播放
-- 预览容器挂载、buffering 状态与预览比例同步
+本轮已完成一次针对仓库现状的维护梳理，并同步修正了以下残留：
+
+- 修复了 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)。
 
 ## 安装
 
 ```bash
-npm install @linker-design-plus/timeline-track
+pnpm add @linker-design-plus/timeline-track konva
 ```
 
 ## 快速开始
@@ -36,29 +37,9 @@ 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'
-      };
-    }
-
-    return null;
-  }
+  previewBackend: 'dom'
 });
 
 timeline.attachPreview(preview);
@@ -72,72 +53,46 @@ await timeline.addClip({
     x: 0.5,
     y: 0.5,
     scale: 1
-  },
-  thumbnails: ['https://example.com/thumb-1.jpg']
+  }
 });
 
 timeline.on('history_change', (_event, data) => {
-  console.log('canUndo', data.canUndo, 'canRedo', data.canRedo);
+  console.log(data.canUndo, data.canRedo);
 });
-
-timeline.play();
 ```
 
-## 缩略图提供器
-
-`ThumbnailProvider` 使用 `getThumbnails(clip)`，返回 `string[]` 或 `Promise<string[]>`。
-音频 clip 默认不会使用缩略图渲染，`thumbnailProvider` 主要作用于视频 clip。
+## 核心能力
 
-```ts
-import { TimelineManager, type ThumbnailProvider } from '@linker-design-plus/timeline-track';
-
-const thumbnailProvider: ThumbnailProvider = {
-  async getThumbnails(clip) {
-    return [
-      `https://example.com/thumbnails/${clip.id}/0.jpg`,
-      `https://example.com/thumbnails/${clip.id}/1.jpg`
-    ];
-  }
-};
-
-const timeline = new TimelineManager({
-  container,
-  thumbnailProvider
-});
-
-timeline.setThumbnailProvider(thumbnailProvider);
-await timeline.refreshAllClipThumbnails();
-```
-
-## 对外主 API
+- 多轨时间线编辑，支持视频轨和音频轨
+- 片段拖拽、拉伸、分割、跨轨移动和重叠避让
+- 单一选中态与批量拖拽
+- 播放头、缩放、滚动和时间同步
+- 撤销 / 重做 / 历史变更通知
+- 缩略图提供器与异步封面加载
+- 预览容器挂载、预览比例同步和当前激活片段解析
+- 草稿导入导出、音视频分离/恢复等编辑工作流
 
-### `TimelineManager`
+## 主要 API
 
 常用方法：
 
 - `play()` / `pause()` / `togglePlay()`
 - `setCurrentTime(time)` / `getCurrentTime()`
-- `setZoom(zoom)` / `getZoom()`
+- `setZoom(zoom)` / `fitZoom()`
 - `setSpeed(speed)` / `getSpeed()`
 - `addClip(config)` / `addClips(configs)`
-- `updateClip(clipId, updates)` / `removeClip(clipId)` / `removeClipsByExternalId(externalId)`
+- `updateClip(clipId, updates)` / `removeClip(clipId)`
 - `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
-- `canSeparateClipAudio(clipId)` / `separateClipAudio(clipId)` / `canRestoreClipAudio(clipId)` / `restoreClipAudio(clipId)`
-- `splitCurrentClip()` / `removeClipGaps()` / `fitZoom()`
+- `splitCurrentClip()` / `removeClipGaps()`
 - `undo()` / `redo()` / `clearHistory()`
 - `attachPreview(containerOrConfig)` / `detachPreview()`
-- `getPreviewBackendType()`
-- `getCurrentActiveClips()` / `getActiveClipsAtTime(time)`
-- `getPreviewAspectRatio()` / `setPreviewAspectRatio({ width, height })` / `resetPreviewAspectRatioToAuto()`
-- `exportTimeline()`
+- `exportTimeline()` / `loadDraft(data)`
 
 常用事件：
 
 - `time_change`
 - `play_state_change`
-- `speed_change`
 - `zoom_change`
-- `preview_aspect_ratio_change`
 - `clip_added`
 - `clip_removed`
 - `clip_updated`
@@ -146,10 +101,9 @@ await timeline.refreshAllClipThumbnails();
 - `history_change`
 - `track_duration_change`
 - `buffering_state_change`
-- `can_play_change`
 - `source_loading_change`
 
-## 核心类型
+## 关键类型
 
 ```ts
 interface ClipConfig {
@@ -171,217 +125,68 @@ interface ClipConfig {
     y: number;
     scale: number;
   };
-  separatedAudioClipId?: string;
-  separatedFromVideoClipId?: string;
+  trackId?: string;
+  volume?: number;
 }
 ```
 
-当 `type: 'audio'` 时，clip 会渲染为音频卡片样式：内置音频图标、装饰性波形和文件名，不展示视频缩略图。
-视频 clip 可通过 `visualTransform` 控制预览中的归一化位置和等比缩放，默认值为 `{ x: 0.5, y: 0.5, scale: 1 }`。
-视频 clip 分离原声后会写入 `separatedAudioClipId`，对应音频 clip 会写入 `separatedFromVideoClipId`。
-导出时间线时会包含 `composition`、轨道 `order` / `isMuted`、clip `isMuted` 和视频 clip 的 `visualTransform`，便于后端按当前多轨预览语义做合成。
+## 预览实现说明
 
-### 预览后端
+- 当前代码路径实际只会创建 `DomPreviewBackend`
+- `previewBackend` 字段被保留，目的是不给后续预览实现扩展制造额外 breaking change
+- 如果你在业务接入层看到 `canvas` / `auto` 配置，请把它当作保留参数，而不是当前版本的有效能力
 
-`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;
-    }
-
-    return {
-      url: clip.src,
-      mimeType: 'video/mp4',
-      kind: 'mp4'
-    };
-  }
-});
+```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["Konva Views\nTimeline / Track / Clip / Playhead / Panels"]
 ```
 
-当前阶段限制：
-
-- `canvas` 后端仅面向 Chrome / Edge 桌面端
-- 视频预览源支持 MP4，以及 `EXT-X-MAP + m4s` 形式的 fMP4 HLS
-- 暂不支持基于 TS 分片的 HLS，也不支持 DRM 流
-- Firefox / Safari 会自动回退到 `dom` 后端
+当前最值得关注的热点：
 
-## 当前代码架构
+- `src/core/facade/timelineManager.ts` 仍然超过 4k 行，是后续最重要的瘦身目标
+- `src/components/track/Track.tsx` 内部还保留一层 `legacy` 交互镜像，用于兼容旧拖拽状态
+- `src/utils/rendering/KonvaUtils.ts` 仍偏大，适合继续拆分为更小的渲染工具模块
+- `demo/App.vue` 既承担演示又承担诊断面板职责，维护成本偏高
 
-### 入口与 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/        渲染与通用工具
+  components/   Konva 组件与交互 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
 ```
 
-## 架构图级别说明
-
-### 分层关系图
-
-```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
-```
-
-### 运行时职责图
-
-```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对外事件通知"]
-```
-
-### 核心分层说明
-
-- `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` 两套多轨预览实现。
-
-### 典型调用链路
-
-#### 1. Clip 拖拽/跨轨移动
-
-1. 用户在 `Track` / `Clip` 上产生指针操作。
-2. `trackInteractionState` 识别当前操作类型，`globalPointerDragSession` 保证拖拽期间的全局 move/end 监听。
-3. `Track` 通过回调把变更意图交给 `TimelineTrackBridge` 与 façade。
-4. façade 调用 `timelineTrackMutationController`、`timelineClipWorkflowController`、`TimelineCommands` 计算目标轨道、位置与合法性。
-5. 轨道集合与 store 更新后，同步写入 history，并触发重绘、事件通知与预览刷新。
-
-#### 2. 播放与时间推进
-
-1. `TimelineManager` 持有播放状态与当前时间。
-2. `TimelinePlaybackResolver` 与预览 session 根据当前时间解析 active clips。
-3. `DomPreviewBackend` 或 `CanvasPreviewBackend` 执行多轨音视频预览。
-4. 时间变化通过 `TimelineEventDispatcher` 向外发布 `time_change`、`play_state_change` 等事件。
-
-### 当前架构特点
-
-- 对外仍保持单一 façade：调用方只需面向 `TimelineManager`。
-- 内部已经拆成 store / commands / controllers / tracks / presentation，职责边界比早期单体 manager 更清晰。
-- UI 交互和领域规则分离：交互细节主要留在 `components`，领域决策集中在 `core`。
-- 预览后端可替换：预览能力通过 backend 抽象扩展，而不是直接耦合到时间轴视图。
-- 历史系统贯穿工作流：新增、删除、更新、跨轨移动都能进入 undo / redo 闭环。
-
 ## 开发
 
 ```bash
 pnpm install
-pnpm run dev
-pnpm run build
+pnpm dev
+pnpm build
 pnpm test
 pnpm exec tsc -p tsconfig.json --noEmit
 ```
 
-## 浏览器支持
+## 相关文档
 
-- Chrome
-- Edge
-- Firefox（`dom` 后端）
-- Safari（`dom` 后端）
+- [docs/interaction-model.md](./docs/interaction-model.md): 指针交互分层和拖拽约束
+- [docs/refactor-roadmap.md](./docs/refactor-roadmap.md): 主线重构归档与后续收敛方向
+- [docs/maintenance-audit.md](./docs/maintenance-audit.md): 本轮仓库审计、验证结果和依赖建议

package/dist/components/track/Track.d.ts

@@ -1,5 +1,6 @@
 import Konva from 'konva';
 import { Clip as ClipType, ClipStateUpdate, TrackConfig, TimeMs, Theme, TrackType } from '../../core/models';
+import { type TrackPointerOperation } from './trackInteractionState';
 import type { MultiDragMoveRequest } from '../../core/tracks/timelineTrackBridge';
 export declare class Track {
     private static readonly DEFAULT_DRAG_ACTIVATION_THRESHOLD;
@@ -26,6 +27,7 @@ export declare class Track {
     private multiDragOriginalPositions;
     private promotedClipParents;
     private interactionState;
+    private legacyInteractionSnapshot?;
     private isVisualUpdate;
     private onClipUpdate;
     private onClipAdd;
@@ -55,8 +57,37 @@ export declare class Track {
     private handleGlobalPointerMove;
     private handleGlobalPointerEnd;
     private handleWindowBlur;
+    get hasDragMoved(): boolean;
+    set hasDragMoved(value: boolean);
+    get activePointerOperation(): TrackPointerOperation | null;
+    set activePointerOperation(value: TrackPointerOperation | null);
+    get originalClipsState(): ClipType[];
+    set originalClipsState(value: ClipType[]);
+    get nonDraggedClips(): ClipType[];
+    set nonDraggedClips(value: ClipType[]);
+    get snapCandidateClips(): ClipType[];
+    set snapCandidateClips(value: ClipType[]);
+    get dragStartY(): number;
+    set dragStartY(value: number);
+    get dragTargetTrackY(): number;
+    set dragTargetTrackY(value: number);
+    get crossTrackDragOffsetY(): number;
+    set crossTrackDragOffsetY(value: number);
+    get crossTrackDragStartX(): number;
+    set crossTrackDragStartX(value: number);
+    get dragStartScrollLeft(): number;
+    set dragStartScrollLeft(value: number);
+    get dragGestureStartClientX(): number | null;
+    set dragGestureStartClientX(value: number | null);
+    get dragGestureStartClientY(): number | null;
+    set dragGestureStartClientY(value: number | null);
+    get lastDragClientX(): number | null;
+    set lastDragClientX(value: number | null);
+    get lastDragClientY(): number | null;
+    set lastDragClientY(value: number | null);
     constructor(layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: ClipType, originalClip?: ClipType, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: ClipType) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: ClipType, clip2: ClipType) => void, onClipSelect: (clip: ClipType) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: ClipType, currentTrackId: string) => void, onClipCrossTrackPreview?: (clip: ClipType, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: ClipType, originalClip: ClipType | null, targetTrackY: number, currentTrackId: string) => boolean | void, onClearDropPreview?: () => void, onClearSelection?: () => void, onSnapGuideChange?: (guideTime: TimeMs | null) => void, onClipToggleSelection?: (clipId: string) => void, onSetSingleSelection?: (clipId: string) => void, getMultiDragClipIds?: (clipId: string) => string[] | null, onMultiDragMove?: (request: MultiDragMoveRequest) => boolean | void, onMultiDragInteractionEnd?: () => void, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number);
     private initClips;
+    private getLegacyInteractionSnapshot;
     private ensureDropPreviewGroup;
     private createDropPreviewRect;
     private showDropPreview;
@@ -107,10 +138,9 @@ export declare class Track {
     render(shouldBatchDraw?: boolean): void;
     private getTrackBackgroundFill;
     getClips(): ClipType[];
-    getSelectedClip(): ClipType | null;
+    getPrimarySelectedClip(): ClipType | null;
     clearSelection(): void;
-    updateSelectionVisual(selectedClipId: string | null): void;
-    selectClip(clipId: string): void;
+    setSelection(clipIds: string[], preferredClipId?: string | null): void;
     private applySelectionVisual;
     private syncSelectionState;
     splitSelectedClip(time: TimeMs): void;

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

@@ -1,4 +1,4 @@
-import type { Clip, ClipConfig, PlayState, PreviewAspectRatio, Track, TrackInsertionPlacement, TrackType } from '../models/types';
+import type { ClipConfig, PlayState, PreviewAspectRatio, Track, TrackInsertionPlacement, TrackType } from '../models/types';
 export interface DemoPreviewClipSnapshot extends ClipConfig {
     id: string;
     previewAutoOrder?: number;
@@ -17,7 +17,8 @@ export interface DemoPreviewRebuildSnapshot {
     zoom: number;
     playState: PlayState;
     previewAspectRatio: PreviewAspectRatio;
-    selectedClipId: string | null;
+    selectedClipIds: string[];
+    selectedClipId?: string | null;
     isPreviewAttached: boolean;
     tracks: DemoPreviewTrackSnapshot[];
 }
@@ -27,7 +28,7 @@ interface DemoPreviewStateReader {
     getSpeed(): number;
     getZoom(): number;
     getPlayState(): PlayState;
-    getSelectedClip(): Clip | null;
+    getSelectedClipIds(): string[];
     getTracks(): Track[];
 }
 interface DemoPreviewStateWriter extends DemoPreviewStateReader {
@@ -40,7 +41,7 @@ interface DemoPreviewStateWriter extends DemoPreviewStateReader {
     play(): void;
     renameTrack(trackId: string, newName: string): boolean;
     resetPreviewAspectRatioToAuto(): void;
-    selectClip(clipId: string): void;
+    setSelection(clipIds: string[]): void;
     setCurrentTime(time: number): void;
     setPreviewAspectRatio(aspectRatio: {
         width: number;

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

@@ -1,5 +1,6 @@
-import type { TimelinePreviewBackend } from './previewBackend';
+import type { TimelinePreviewBackend, TimelinePreviewBackendOptions } from './previewBackend';
 import { TimelinePreviewSession } from './timelinePreviewSession';
 export declare class DomPreviewBackend extends TimelinePreviewSession implements TimelinePreviewBackend {
+    constructor(options?: TimelinePreviewBackendOptions);
     destroy(): void;
 }

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

@@ -8,6 +8,8 @@ export * from './timelineDurationController';
 export { TimelineEventDispatcher } from './timelineEventDispatcher';
 export { TimelinePlaybackResolver } from './timelinePlaybackResolver';
 export { TimelinePreviewSession } from './timelinePreviewSession';
+export { TimelinePreviewRuntimeController } from './timelinePreviewRuntimeController';
+export { TimelinePreviewStateController, type TimelinePendingPreviewState } from './timelinePreviewStateController';
 export * from './timelineSelectionController';
 export * from './timelineTrackMutationController';
 export { TimelineTrackInfoPanelController } from './timelineTrackInfoPanelController';

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

@@ -7,13 +7,14 @@ export interface TimelinePreviewSyncPayload {
     currentTime: TimeMs;
     playState: PlayState;
     speed: number;
-    selectedClipId?: string | null;
+    primarySelectedClipId?: string | null;
     syncRequestId?: number;
 }
 export interface TimelinePreviewBackendCallbacks {
     onBufferingStateChange?: (isBuffering: boolean) => void;
     onSourceLoadingChange?: (pending: number) => void;
     onSyncProcessed?: (syncRequestId?: number) => void;
+    onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onPendingPreviewRetry?: () => void;
@@ -26,6 +27,27 @@ export interface PreviewPendingState {
     isBuffering: boolean;
     errorMessage: string | null;
 }
+export type PreviewRuntimePhase = 'idle' | 'awaiting-sync' | 'awaiting-media' | 'ready' | 'failed';
+export type PreviewSlotPhase = 'idle' | 'binding' | 'primed' | 'active' | 'recovering' | 'failed';
+export interface PreviewSlotDiagnostic {
+    trackId: string;
+    role: 'current' | 'preload';
+    kind: ActiveClipPlaybackInfo['trackType'];
+    clipId: string | null;
+    desiredSource: string | null;
+    actualSource: string | null;
+    phase: PreviewSlotPhase;
+    retryCount: number;
+    errorMessage: string | null;
+}
+export interface PreviewRuntimeState {
+    syncRequestId?: number;
+    phase: PreviewRuntimePhase;
+    loadingCount: number;
+    isBuffering: boolean;
+    errorMessage: string | null;
+    slots: PreviewSlotDiagnostic[];
+}
 export interface TimelinePreviewBackend {
     attach(container: HTMLElement): void;
     detach(): void;

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

@@ -2,7 +2,7 @@ import { Theme, Clip } from '../models';
 export interface TimelineClipConfigControllerConfig {
     container: HTMLElement;
     theme: Theme;
-    getSelectedClip: () => Clip | null;
+    getPrimarySelectedClip: () => Clip | null;
     updateClip: (clipId: string, updates: Partial<Clip>) => void;
 }
 export declare class TimelineClipConfigController {

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

@@ -0,0 +1,40 @@
+import type { PreviewAspectRatio, PreviewBackendType } from '../models/types';
+import type { TimelinePreviewBackend, TimelinePreviewBackendCallbacks } from './previewBackend';
+interface TimelinePreviewRuntimeControllerOptions {
+    createBackendCallbacks: (callbackToken: number) => TimelinePreviewBackendCallbacks;
+    createBackend: (resolvedBackend: Exclude<PreviewBackendType, 'auto'>, callbacks: TimelinePreviewBackendCallbacks) => TimelinePreviewBackend;
+    resolveConfiguredBackend: (runtimeOverride: Exclude<PreviewBackendType, 'auto'> | null) => Exclude<PreviewBackendType, 'auto'>;
+}
+export declare class TimelinePreviewRuntimeController {
+    private readonly options;
+    private _previewSession?;
+    private _previewMountContainer;
+    private _resolvedPreviewBackend;
+    private _runtimePreviewBackendOverride;
+    private _activePreviewCallbackToken;
+    constructor(options: TimelinePreviewRuntimeControllerOptions);
+    get previewSession(): TimelinePreviewBackend | undefined;
+    set previewSession(value: TimelinePreviewBackend | undefined);
+    get previewMountContainer(): HTMLElement | null;
+    set previewMountContainer(value: HTMLElement | null);
+    get resolvedPreviewBackend(): Exclude<PreviewBackendType, 'auto'>;
+    set resolvedPreviewBackend(value: Exclude<PreviewBackendType, 'auto'>);
+    get runtimePreviewBackendOverride(): Exclude<PreviewBackendType, 'auto'> | null;
+    set runtimePreviewBackendOverride(value: Exclude<PreviewBackendType, 'auto'> | null);
+    get activePreviewCallbackToken(): number;
+    set activePreviewCallbackToken(value: number);
+    isActiveCallbackToken(callbackToken: number): boolean;
+    resolveConfiguredPreviewBackend(): Exclude<PreviewBackendType, 'auto'>;
+    createPreviewBackend(resolvedBackend?: Exclude<PreviewBackendType, 'auto'>): TimelinePreviewBackend;
+    getPreviewSession(): TimelinePreviewBackend;
+    hasAttachedPreview(): boolean;
+    attachPreview(container: HTMLElement, aspectRatio: PreviewAspectRatio): PreviewAspectRatio;
+    detachPreviewSession(): boolean;
+    destroyPreviewSession(clearReference?: boolean): void;
+    recreateDetachedPreviewSession(): void;
+    fallbackToDom(aspectRatio: PreviewAspectRatio): {
+        handled: boolean;
+        aspectRatio: PreviewAspectRatio;
+    };
+}
+export {};