@linker-design-plus/timeline-track 2.1.2 → 2.1.4

package/README.md

@@ -135,6 +135,7 @@ pnpm install
 pnpm dev
 pnpm build
 pnpm test
+pnpm harness:test
 pnpm exec tsc -p tsconfig.json --noEmit
 ```
 
@@ -146,3 +147,4 @@ pnpm exec tsc -p tsconfig.json --noEmit
 - [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 导向的测试与诊断重构方案

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

@@ -35,6 +35,7 @@ export declare class Track {
     private onClipSelect;
     private onTimeJump;
     private onClipOverlap?;
+    private onPrimaryTrackMagnetMove?;
     private hasBoundGlobalPointerListenersForDrag;
     private hasLockedGlobalCursor;
     private edgeAutoScrollAnimationFrameId;
@@ -56,7 +57,7 @@ export declare class Track {
     private handleGlobalPointerMove;
     private handleGlobalPointerEnd;
     private handleWindowBlur;
-    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, originalClip?: ClipType | null) => 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);
+    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, originalClip?: ClipType | null) => void, onPrimaryTrackMagnetMove?: (clip: ClipType, originalClip: ClipType | null, peerClips: ClipType[], currentTrackId: string) => boolean | 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 ensureDropPreviewGroup;
     private createDropPreviewRect;
@@ -83,6 +84,7 @@ export declare class Track {
     private resolveDraggedClipForInteraction;
     private applyInteractionTransition;
     private handleClipMoveEnd;
+    private compactPrimaryTrackClips;
     private updateAllClips;
     private buildAndSendUpdates;
     private updateHoverCursor;

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

@@ -12,6 +12,7 @@ export { TimelinePreviewRuntimeController } from './timelinePreviewRuntimeContro
 export { TimelinePreviewStateController, type TimelinePendingPreviewState } from './timelinePreviewStateController';
 export { TimelineKeyboardShortcutsController, type TimelineKeyboardShortcutsControllerCallbacks } from './timelineKeyboardShortcutsController';
 export * from './timelineSelectionController';
+export { TimelineStructureSession, type TimelineStructureSessionSummary } from './timelineStructureSession';
 export * from './timelineTrackMutationController';
 export { TimelineClipConfigController } from './timelineClipConfigController';
 export { TimelineTrackInfoPanelController } from './timelineTrackInfoPanelController';

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

@@ -0,0 +1,16 @@
+import type { TimeMs } from '../models/types';
+export declare const PLAYBACK_VIEWPORT_FOLLOW_MARGIN_PX = 48;
+export declare function getPlayheadScreenX(time: TimeMs, zoom: number, scrollLeft: number): number;
+export interface PlaybackViewportFollowInput {
+    time: TimeMs;
+    zoom: number;
+    scrollLeft: number;
+    viewportWidth: number;
+    contentWidth: number;
+    margin?: number;
+}
+export declare function clampScrollLeft(scrollLeft: number, viewportWidth: number, contentWidth: number): number;
+/**
+ * 播放边距跟随：播放头超出左右安全边距时返回目标 scrollLeft，否则返回 null。
+ */
+export declare function resolveScrollLeftForPlaybackFollow(input: PlaybackViewportFollowInput): number | null;

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

@@ -204,6 +204,7 @@ export declare class TimelinePreviewSession {
     private ensureTextPreviewFontReady;
     private resetTextPreviewFontState;
     private refreshSlotVisualLayout;
+    private syncSlotFailureVisualState;
     private buildSelectedOverlayState;
     private getFrameSize;
     private getDocument;

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

@@ -0,0 +1,67 @@
+import type { Clip, Track, TrackRestoreAnchor } from '../models/types';
+import type { TimelineTrackCollection, TimelineTrackCollectionItem } from '../tracks/timelineTrackCollection';
+import type { TimelineHistoryExecutionTarget } from '../history/timelineHistoryExecutor';
+export interface TimelineStructureSessionEvent {
+    type: 'clip_added' | 'clip_removed' | 'clip_updated';
+    payload: Record<string, unknown>;
+}
+export interface TimelineStructureSessionSummary {
+    cleanupEmptyTracks: boolean;
+    durationDirty: boolean;
+    canPlayDirty: boolean;
+    selectionDirty: boolean;
+    trackLayoutDirty: boolean;
+    trackInfoDirty: boolean;
+    stageDirty: boolean;
+    previewDirty: boolean;
+    events: TimelineStructureSessionEvent[];
+}
+interface TimelineStructureSessionOptions {
+    trackCollection: TimelineTrackCollection;
+    ensureTrackFromHistorySnapshot: (trackSnapshot: Track, restoreAnchor?: TrackRestoreAnchor | null) => string | null;
+    removeClipGaps: () => void;
+    setPrimaryTrackMagnetEnabled: (enabled: boolean) => void;
+    loadClipThumbnails?: (clip: Clip) => Promise<boolean> | void;
+    addClipToTrack?: (trackId: string, clip: Clip) => boolean;
+    removeClip?: (clipId: string) => void;
+    removeClipFromTrack?: (trackId: string, clipId: string) => boolean;
+    updateClip?: (clipId: string, updates: Partial<Clip>) => void;
+    moveClipToTrack?: (clip: Clip, sourceTrackId: string, targetTrackId: string) => boolean;
+    getClips?: () => Clip[];
+    findTrackById?: (trackId: string) => TimelineTrackCollectionItem | null;
+    findTrackByClipId?: (clipId: string) => TimelineTrackCollectionItem | null;
+    getDefaultTrack?: () => TimelineTrackCollectionItem | null;
+    onCommit: (summary: TimelineStructureSessionSummary) => void;
+}
+export declare class TimelineStructureSession {
+    private readonly options;
+    private cleanupEmptyTracks;
+    private durationDirty;
+    private canPlayDirty;
+    private selectionDirty;
+    private trackLayoutDirty;
+    private trackInfoDirty;
+    private stageDirty;
+    private previewDirty;
+    private committed;
+    private readonly events;
+    constructor(options: TimelineStructureSessionOptions);
+    addClipToTrack(trackId: string, clip: Clip): boolean;
+    removeClip(clipId: string): void;
+    removeClipFromTrack(trackId: string, clipId: string): boolean;
+    updateClip(clipId: string, updates: Partial<Clip>): void;
+    moveClipToTrack(clipId: string, targetTrackId: string): boolean;
+    ensureTrackFromHistorySnapshot(trackSnapshot: Track, restoreAnchor?: TrackRestoreAnchor | null): string | null;
+    removeClipGaps(): void;
+    getClips(): Clip[];
+    findTrackByClipId(clipId: string): TimelineTrackCollectionItem | null;
+    getDefaultTrack(): TimelineTrackCollectionItem | null;
+    queueEvent(type: TimelineStructureSessionEvent['type'], payload: Record<string, unknown>): void;
+    markStructureMutation(): void;
+    markClipStateMutation(): void;
+    markTrackLayoutMutation(): void;
+    commit(): void;
+    createHistoryExecutionTarget(): TimelineHistoryExecutionTarget;
+    private resolveTrackId;
+}
+export {};

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

@@ -49,7 +49,6 @@ export declare class TimelineManager {
     private sourceLoadingCount;
     private timelineStore?;
     private timelineCommands?;
-    private timelineHistoryExecutor?;
     private timelineHistoryRecorder?;
     private timelinePresentationAdapter?;
     private timelineTrackBridge?;
@@ -74,6 +73,7 @@ export declare class TimelineManager {
     private splitOperationDepth;
     private readonly diagnostics;
     private previewRuntimeState;
+    private failedPreviewClipIds?;
     private previewActiveClipIds;
     private previewClockSeekAlignmentTargetTime;
     private previewClockSeekAlignmentDeadlineMs;
@@ -86,6 +86,11 @@ export declare class TimelineManager {
     private voiceLinkedTextRegenerationTimer;
     private pendingVoiceLinkedTextRegeneration;
     private historyRecordingSuppressionDepth;
+    private activeStructureSession;
+    private structureSessionDepth;
+    private preserveEmptyTracksDepth;
+    private playbackViewportFollowSuspended;
+    private isProgrammaticScrollChange;
     constructor(config?: Partial<TimelineConfig>);
     private createPlaybackAttemptId;
     private refreshPlaybackAttempt;
@@ -121,13 +126,20 @@ export declare class TimelineManager {
     private getEventDispatcher;
     private getDefaultTrackForHistory;
     private getTimelineHistoryRecorder;
-    private getTimelineHistoryExecutor;
+    private withStructureSession;
+    private getActiveStructureSession;
+    private withPreservedEmptyTracks;
+    private applyStructureSessionSummary;
     private withHistoryBoundary;
     private shouldSkipHistoryRecording;
     private withHistoryTransaction;
     private get selectedClipId();
     private set selectedClipId(value);
     private ensureConfigState;
+    private isPlaybackViewportFollowEnabled;
+    private suspendPlaybackViewportFollowIfUserScrolling;
+    private runProgrammaticScrollChange;
+    private followPlaybackViewportIfNeeded;
     private getCurrentTimeState;
     private getPlayStateState;
     private setPlayStateState;
@@ -188,7 +200,7 @@ export declare class TimelineManager {
     private retryPendingPreview;
     private handlePreviewBackendRuntimeError;
     init(container: HTMLElement): void;
-    createTrack(type: TrackType, name?: string, insertionPlacement?: TrackInsertionPlacement, referenceTrackId?: string, roleOverride?: TrackEntity['role']): string;
+    createTrack(type: TrackType, name?: string, insertionPlacement?: TrackInsertionPlacement, referenceTrackId?: string, roleOverride?: TrackEntity['role'], explicitTrackId?: string): string;
     removeTrack(trackId: string): boolean;
     renameTrack(trackId: string, newName: string): boolean;
     getTracks(): any[];
@@ -198,6 +210,7 @@ export declare class TimelineManager {
     private calculateTrackY;
     private calculateTotalHeight;
     private updateAllTrackPositions;
+    private removeEmptyTracksFromStructure;
     private cleanupEmptyTracks;
     private clearAllTrackDropPreviews;
     private showClipDropPreview;
@@ -240,6 +253,17 @@ export declare class TimelineManager {
     getCurrentTime(): TimeMs;
     setEnableClipSnap(enabled: boolean): void;
     getEnableClipSnap(): boolean;
+    setEnablePrimaryTrackMagnet(enabled: boolean): void;
+    getEnablePrimaryTrackMagnet(): boolean;
+    private setPrimaryTrackMagnetEnabledFromHistory;
+    private setPrimaryTrackMagnetEnabledState;
+    private getPrimaryTrackId;
+    private isPrimaryTrackId;
+    private shouldNormalizePrimaryTrackForTrackIds;
+    private getStableStartOrderedClips;
+    private buildPrimaryTrackContinuousClips;
+    private buildPrimaryTrackMultiDragOrderedClips;
+    private normalizePrimaryTrackInSession;
     setZoom(zoom: number): void;
     /**
      * 以游标（playhead）为中心设置缩放，用于外置 slider 等非幕布上的缩放操作
@@ -320,6 +344,10 @@ export declare class TimelineManager {
     splitClip(clipId: string, time: TimeMs): void;
     splitCurrentClip(): void;
     getClips(): Clip[];
+    private syncTimelineClipMediaStateFromPreview;
+    private applyTimelineClipMediaStatus;
+    private clearTimelineClipMediaStatus;
+    private getFailedPreviewClipIds;
     private getExportComposition;
     private getExportCoverUrl;
     exportTimeline(): TimelineExportData;
@@ -404,6 +432,7 @@ export declare class TimelineManager {
     private emitSelectedClipChangeIfNeeded;
     private beginSourceLoading;
     private endSourceLoading;
+    private handlePrimaryTrackMagnetMove;
     private handleClipOverlap;
     private handleClipCrossTrackPreview;
     private handleClipCrossTrack;
@@ -575,6 +604,7 @@ export declare class TimelineManager {
     private resolveMultiDragOverlapTargetTrackId;
     private commitMultiDragPlacements;
     private finalizeMultiDragSameTrack;
+    private compactPrimaryTrackAfterMultiDrag;
     private previewMultiDragCrossTrack;
     private finalizeMultiDragCrossTrack;
     private resolveTrackIndexDelta;
@@ -597,7 +627,6 @@ export declare class TimelineManager {
     private isPointOnClip;
     private getClipsIntersectingBox;
     private resolveTrackRenderHeight;
-    private addClipToTrack;
     private cloneTrackSnapshot;
     private ensureTrackFromHistorySnapshot;
     private getTrackRestoreAnchor;

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

@@ -1,4 +1,4 @@
-import { Action, Clip, ClipStateUpdate, CompoundAction, HistoryState, MoveClipBetweenTracksAction, MoveClipAction, MultiClipUpdateAction, RemoveClipAction, RemoveGapsAction, RestoreClipAudioAction, ResizeClipAction, SeparateClipAudioAction, SetTimeAction, SplitClipAction, Track, TrackRestoreAnchor, UpdateClipAction, AddClipAction } from '../models/types';
+import { Action, Clip, ClipStateUpdate, CompoundAction, HistoryState, MoveClipBetweenTracksAction, MoveClipAction, MultiClipUpdateAction, RemoveClipAction, RemoveGapsAction, RestoreClipAudioAction, ResizeClipAction, SeparateClipAudioAction, SetPrimaryTrackMagnetAction, SetTimeAction, SplitClipAction, Track, TrackRestoreAnchor, TrackHistoryReference, UpdateClipAction, AddClipAction } from '../models/types';
 export declare class HistoryManager {
     private state;
     private maxHistorySize;
@@ -50,7 +50,7 @@ export declare class HistoryManager {
     /**
      * 创建分割片段操作
      */
-    createSplitClipAction(originalClip: Clip, clip1: Clip, clip2: Clip): SplitClipAction;
+    createSplitClipAction(originalClip: Clip, clip1: Clip, clip2: Clip, sourceTrackReference?: Partial<TrackHistoryReference>): SplitClipAction;
     /**
      * 创建移动片段操作
      */
@@ -74,8 +74,9 @@ export declare class HistoryManager {
     /**
      * 创建跨轨道移动片段操作
      */
-    createMoveClipBetweenTracksAction(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | null): MoveClipBetweenTracksAction;
+    createMoveClipBetweenTracksAction(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): MoveClipBetweenTracksAction;
     createSeparateClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): SeparateClipAudioAction;
     createRestoreClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): RestoreClipAudioAction;
+    createSetPrimaryTrackMagnetAction(previousEnabled: boolean, nextEnabled: boolean): SetPrimaryTrackMagnetAction;
     createCompoundAction(actions: Action[], label?: string): CompoundAction;
 }

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

@@ -7,12 +7,14 @@ export interface TimelineHistoryExecutionTarget {
     addClipToTrack(trackId: string, clip: Clip): boolean;
     updateClip(clipId: string, updates: Partial<Clip>): void;
     moveClipToTrack(clipId: string, targetTrackId: string): boolean;
+    setPrimaryTrackMagnetEnabled?(enabled: boolean): void;
     ensureTrackFromHistorySnapshot(trackSnapshot: Track, restoreAnchor?: TrackRestoreAnchor | null): string | null;
     removeClipGaps(): void;
     getClips(): Clip[];
     findTrackByClipId(clipId: string): TimelineHistoryExecutionTrack | null;
     getDefaultTrack(): TimelineHistoryExecutionTrack | null;
     loadClipThumbnails?(clip: Clip): Promise<boolean> | void;
+    withClipRemovalBatch?<T>(callback: () => T): T;
 }
 export declare class TimelineHistoryExecutor {
     private readonly target;
@@ -22,8 +24,11 @@ export declare class TimelineHistoryExecutor {
     private executeUndoInternal;
     private executeRedoInternal;
     private restoreMovedClip;
+    private withClipRemovalBatch;
     private normalizeRemoveClipActionData;
     private normalizeAddClipActionData;
+    private normalizeSplitClipActionData;
+    private normalizeMoveClipBetweenTracksActionData;
     private resolveTrackIdForHistorySnapshot;
     private resolveRestoreAnchor;
 }

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

@@ -9,13 +9,14 @@ export declare class TimelineHistoryRecorder {
     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;
-    recordSplitClip(clip1: Clip, clip2: Clip): Action;
+    recordSplitClip(clip1: Clip, clip2: Clip, sourceTrackId?: string | null, sourceTrackSnapshot?: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     recordRemoveGaps(clipsBefore: Clip[]): Action | null;
-    recordMoveClipBetweenTracks(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | null): Action;
+    recordMoveClipBetweenTracks(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     recordSeparateClipAudio(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
     recordRestoreClipAudio(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
     createSeparateClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
     createRestoreClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
+    recordSetPrimaryTrackMagnet(previousEnabled: boolean, nextEnabled: boolean): Action;
     recordCompoundAction(actions: Action[], label?: string): Action | null;
     createClipUpdateAction(clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]): Action | null;
     withTransaction<T>(label: string | undefined, callback: () => T): T;

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

@@ -76,6 +76,7 @@ export interface GenerateVoiceResult {
     voiceId: string;
     voiceName: string;
 }
+export type ClipMediaStatus = 'ready' | 'failed';
 export interface ClipConfigVoicePanelOptions {
     voiceCatalog?: VoiceOption[];
     generateVoiceBatch?: (requests: GenerateVoiceRequest[]) => Promise<GenerateVoiceResult[]>;
@@ -105,6 +106,8 @@ export interface ClipConfig {
     ttsVoiceId?: string;
     ttsVoiceName?: string;
     ttsFollowTextUpdates?: boolean;
+    mediaStatus?: ClipMediaStatus;
+    mediaStatusMessage?: string | null;
 }
 export interface ClipEntity {
     id: string;
@@ -131,6 +134,8 @@ export interface ClipEntity {
     ttsVoiceId?: string;
     ttsVoiceName?: string;
     ttsFollowTextUpdates?: boolean;
+    mediaStatus?: ClipMediaStatus;
+    mediaStatusMessage?: string | null;
 }
 export interface ClipViewState {
     isDragging: boolean;
@@ -218,6 +223,7 @@ export interface TimelineConfig {
     speed?: number;
     dragActivationThreshold?: number;
     enableClipSnap?: boolean;
+    enablePrimaryTrackMagnet?: boolean;
     clipSnapThreshold?: number;
     thumbnailProvider?: ThumbnailProvider;
     previewBackend?: PreviewBackendType;
@@ -226,6 +232,8 @@ export interface TimelineConfig {
     textPreviewFont?: TextPreviewFontConfig | null;
     draftData?: TimelineExportData;
     keyboardShortcuts?: false | TimelineKeyboardShortcutsConfig;
+    /** 播放时自动横向滚动以保持播放头在可视安全区内；默认开启 */
+    playbackViewportFollow?: boolean;
 }
 export type PreviewAspectRatioMode = 'auto-first-added-video' | 'auto-first-video' | 'manual';
 export interface PreviewAspectRatio {
@@ -297,6 +305,11 @@ export interface TrackRestoreAnchor {
     previousTrackId: string | null;
     nextTrackId: string | null;
 }
+export interface TrackHistoryReference {
+    trackId: string | null;
+    trackSnapshot: Track | null;
+    trackRestoreAnchor: TrackRestoreAnchor | null;
+}
 export interface UpdateClipAction {
     type: 'update_clip';
     data: {
@@ -312,6 +325,9 @@ export interface SplitClipAction {
         originalClip: Clip;
         clip1: Clip;
         clip2: Clip;
+        sourceTrackId?: string | null;
+        sourceTrackSnapshot?: Track | null;
+        sourceTrackRestoreAnchor?: TrackRestoreAnchor | null;
     };
     timestamp: number;
 }
@@ -367,6 +383,8 @@ export interface MoveClipBetweenTracksAction {
         clipAfter: Clip;
         sourceTrackSnapshot: Track | null;
         targetTrackSnapshot: Track | null;
+        sourceTrackRestoreAnchor?: TrackRestoreAnchor | null;
+        targetTrackRestoreAnchor?: TrackRestoreAnchor | null;
     };
     timestamp: number;
 }
@@ -390,6 +408,14 @@ export interface RestoreClipAudioAction {
     };
     timestamp: number;
 }
+export interface SetPrimaryTrackMagnetAction {
+    type: 'set_primary_track_magnet';
+    data: {
+        previousEnabled: boolean;
+        nextEnabled: boolean;
+    };
+    timestamp: number;
+}
 export interface CompoundAction {
     type: 'compound';
     data: {
@@ -398,7 +424,7 @@ export interface CompoundAction {
     };
     timestamp: number;
 }
-export type Action = AddClipAction | RemoveClipAction | UpdateClipAction | SplitClipAction | MoveClipAction | ResizeClipAction | SetTimeAction | RemoveGapsAction | MultiClipUpdateAction | MoveClipBetweenTracksAction | SeparateClipAudioAction | RestoreClipAudioAction | CompoundAction;
+export type Action = AddClipAction | RemoveClipAction | UpdateClipAction | SplitClipAction | MoveClipAction | ResizeClipAction | SetTimeAction | RemoveGapsAction | MultiClipUpdateAction | MoveClipBetweenTracksAction | SeparateClipAudioAction | RestoreClipAudioAction | SetPrimaryTrackMagnetAction | CompoundAction;
 export type ActionType = Action['type'];
 export interface Position {
     x: number;

package/dist/core/theme/colorTokens.d.ts

@@ -10,6 +10,7 @@ export declare const SHARED_COLOR_TOKENS: {
     readonly videoClipBackground: "#1e5679";
     readonly textClipBackground: "#604c32";
     readonly audioClipBackground: "#254428";
+    readonly mediaClipFailedBackground: "#670014";
     readonly selectedTrackSurface: "#292929";
     readonly borderStrong: "#333333";
     readonly borderMedium: "#444444";
@@ -125,6 +126,8 @@ export declare const PLAYHEAD_DEFAULT_COLORS: {
 export declare const PREVIEW_PENDING_OVERLAY_COLORS: {
     readonly background: "rgba(0, 0, 0, 0.56)";
     readonly text: "#ffffff";
+    readonly failedBackground: "#670014";
+    readonly failedText: "#ffffff";
     readonly actionBackground: "#4c8dff";
     readonly actionText: "#ffffff";
 };

package/dist/core/tracks/timelineTrackBridge.d.ts

@@ -18,6 +18,7 @@ export interface TimelineTrackBridgeHandlers {
     onTimeJump: (time: TimeMs) => void;
     onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number;
     onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void;
+    onPrimaryTrackMagnetMove?: (clip: Clip, originalClip: Clip | null, peerClips: Clip[], currentTrackId: string) => boolean | void;
     onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear';
     onClipCrossTrack?: (clip: Clip, originalClip: Clip | null, targetTrackY: number, currentTrackId: string) => boolean | void;
     onClearDropPreview?: () => void;
@@ -41,7 +42,7 @@ export interface TimelineTrackBridgeCreateOptions {
     enableClipSnap?: boolean;
     clipSnapThreshold?: number;
 }
-export type TimelineTrackConstructor<TTrack = Track> = new (layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: Clip) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: Clip, clip2: Clip) => void, onClipSelect: (clip: Clip) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void, onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: Clip, originalClip: Clip | 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) => TTrack;
+export type TimelineTrackConstructor<TTrack = Track> = new (layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: Clip) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: Clip, clip2: Clip) => void, onClipSelect: (clip: Clip) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void, onPrimaryTrackMagnetMove?: (clip: Clip, originalClip: Clip | null, peerClips: Clip[], currentTrackId: string) => boolean | void, onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: Clip, originalClip: Clip | 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) => TTrack;
 export declare class TimelineTrackBridge<TTrack = Track> {
     private readonly handlers;
     private readonly TrackCtor;

package/dist/core/tracks/trackManager.d.ts

@@ -3,7 +3,7 @@ export declare class TrackManager {
     private tracks;
     private trackCounter;
     constructor(initialTracks?: Track[]);
-    createTrack(type: TrackType, name?: string, insertionPlacement?: TrackInsertionPlacement, referenceTrackId?: string, roleOverride?: Track['role']): Track;
+    createTrack(type: TrackType, name?: string, insertionPlacement?: TrackInsertionPlacement, referenceTrackId?: string, roleOverride?: Track['role'], explicitTrackId?: string): Track;
     removeTrack(trackId: string): boolean;
     renameTrack(trackId: string, newName: string): boolean;
     getTracks(): Track[];