@linker-design-plus/timeline-track 1.0.10 → 2.0.0

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

@@ -0,0 +1,385 @@
+import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener as TimelineEventListener, TimelineExportData, ThumbnailProvider, TrackInsertionPlacement, TrackType, ActiveClipPlaybackInfo, PreviewAspectRatio, PreviewMountConfig, PreviewBackendType } from '../models';
+import type { ResolvedPlaybackPlan } from '../controllers/timelinePlaybackResolver';
+import { TimelineClipConfigController } from '../controllers/timelineClipConfigController';
+export declare class TimelineManager {
+    private timeline;
+    private tracks;
+    private trackManager;
+    private trackInfoPanelController;
+    private playhead;
+    private history;
+    private config;
+    private eventDispatcher;
+    private animationFrameId;
+    private lastUpdateTime;
+    private isInitialized;
+    private stage;
+    private headerStage;
+    private headerLayer;
+    private backgroundLayer;
+    private trackLayer;
+    private snapGuideLayer;
+    private resizeObserver;
+    private rootContainer;
+    private layout;
+    private bodyBackgroundRect;
+    private snapGuideLine;
+    private trackInsertionPreviewLine;
+    private trackInsertionPreviewY;
+    private snapGuideTime;
+    private horizontalScrollbar;
+    private verticalScrollbar;
+    private isExecutingHistoryAction;
+    private lastTrackDuration;
+    private thumbnailProvider;
+    private canPlay;
+    private sourceLoadingCount;
+    private timelineStore?;
+    private timelineCommands?;
+    private timelineHistoryExecutor?;
+    private timelineHistoryRecorder?;
+    private timelinePresentationAdapter?;
+    private timelineTrackBridge?;
+    private timelinePlaybackResolver?;
+    private previewSession?;
+    private previewMountContainer;
+    private resolvedPreviewBackend;
+    private runtimePreviewBackendOverride;
+    private lastSelectedClipId;
+    private previewSourceLoadingCount;
+    private previewBuffering;
+    private pendingPreviewState;
+    private nextPendingPreviewSyncRequestId;
+    private activePreviewCallbackToken;
+    private previewAspectRatio;
+    private readonly bodyViewportScrollListener;
+    private readonly bodyCanvasHostClickListener;
+    private readonly rootWheelListener;
+    private mountManager;
+    private pendingDraftData;
+    constructor(config?: Partial<TimelineConfig>);
+    private getTimelineStore;
+    private getTimelineCommands;
+    private getTrackCollection;
+    private getTimelinePresentationAdapter;
+    private getTimelineTrackBridge;
+    private getTimelinePlaybackResolver;
+    private resolveConfiguredPreviewBackend;
+    private createPreviewBackendCallbacks;
+    private createPreviewBackend;
+    private isActivePreviewCallbackToken;
+    private getPreviewSession;
+    private getEventDispatcher;
+    private getDefaultTrackForHistory;
+    private getTimelineHistoryRecorder;
+    private getTimelineHistoryExecutor;
+    private get selectedClipId();
+    private set selectedClipId(value);
+    private ensureConfigState;
+    private getCurrentTimeState;
+    private getPlayStateState;
+    private setPlayStateState;
+    private getSpeedState;
+    private getZoomState;
+    private getDurationState;
+    private setDurationState;
+    private getScrollLeftState;
+    private setScrollLeftState;
+    private getScrollTopState;
+    private setScrollTopState;
+    private setViewportMetrics;
+    private syncCurrentTimeToScene;
+    private syncZoomToScene;
+    private syncScrollTopPresentation;
+    private refreshScrollbarMetrics;
+    private getTimeScaleHeight;
+    private getTrackContentTopOffset;
+    private getViewportWidth;
+    private getViewportHeight;
+    private getHorizontalContentWidth;
+    private getVerticalContentHeight;
+    private clampScrollLeft;
+    private clampScrollTop;
+    private syncScrollLeft;
+    private syncScrollTop;
+    private getResolvedTracksSnapshot;
+    private getPlaybackTracksSnapshot;
+    private buildPlaybackPlan;
+    private getPreviewAutoAspectRatioClipOrderMap;
+    private getNextPreviewAutoAspectRatioOrder;
+    private getAutoAspectRatioClip;
+    private registerPreviewAutoAspectRatioClip;
+    private syncPreviewSession;
+    private beginPendingPreview;
+    private updatePendingPreviewState;
+    private buildPreviewPendingState;
+    private ensurePendingPreviewTimeout;
+    private clearPendingPreviewTimeout;
+    private clearPendingPreviewState;
+    private resetPreviewRuntimeState;
+    private destroyPreviewSession;
+    private recreateDetachedPreviewSession;
+    private retryPendingPreview;
+    private handlePreviewBackendRuntimeError;
+    init(container: HTMLElement): void;
+    createTrack(type: TrackType, name?: string, insertionPlacement?: TrackInsertionPlacement, referenceTrackId?: string): string;
+    removeTrack(trackId: string): boolean;
+    renameTrack(trackId: string, newName: string): boolean;
+    getTracks(): any[];
+    initTrackInfoPanel(container: HTMLElement): void;
+    updateTrackInfoPanel(): void;
+    muteTrack(trackId: string, isMuted: boolean): boolean;
+    isTrackMuted(trackId: string): boolean;
+    private calculateTrackY;
+    private calculateTotalHeight;
+    private updateAllTrackPositions;
+    private cleanupEmptyTracks;
+    private clearAllTrackDropPreviews;
+    private showClipDropPreview;
+    private ensureTrackInsertionPreviewLine;
+    private refreshTrackInsertionPreview;
+    private showTrackInsertionPreview;
+    private hideTrackInsertionPreview;
+    private resolveTrackInsertionPreviewY;
+    private updateViewportLayout;
+    private renderBodyBackground;
+    private handleBodyBackgroundClick;
+    private handleBodyCanvasHostClick;
+    private ensureSnapGuideLine;
+    private refreshSnapGuideLine;
+    private updateSnapGuideLine;
+    private handleBodyViewportScroll;
+    private handleHorizontalDragAutoScroll;
+    private handleUnifiedWheel;
+    private normalizeWheelDelta;
+    private getPrimaryWheelDelta;
+    private isHorizontalWheelGesture;
+    private getHorizontalScrollDelta;
+    private handleWheelZoom;
+    private getWheelAnchorPointerX;
+    play(): void;
+    pause(): void;
+    togglePlay(): void;
+    private animate;
+    setCurrentTime(time: TimeMs): void;
+    getCurrentTime(): TimeMs;
+    setEnableClipSnap(enabled: boolean): void;
+    getEnableClipSnap(): boolean;
+    setZoom(zoom: number): void;
+    /**
+     * 以游标（playhead）为中心设置缩放，用于外置 slider 等非幕布上的缩放操作
+     * 调整 scrollLeft 使游标在屏幕上的位置保持不变
+     */
+    setZoomCenteredOnPlayhead(zoom: number): void;
+    /**
+     * 外部缩放入口：
+     * - 鼠标在时间轴内：以鼠标位置为中心缩放
+     * - 鼠标不在时间轴内：回退为以游标（playhead）为中心缩放
+     */
+    setZoomByInteraction(zoom: number): void;
+    /**
+     * 以时间轴上的指定像素点为中心缩放，保持该像素对应时间不变
+     */
+    setZoomCenteredOnTimelinePointer(zoom: number, pointerX: number): void;
+    getZoom(): number;
+    /**
+     * 设置播放倍速
+     * @param speed 播放倍速，默认为 1.0
+     */
+    setSpeed(speed: number): void;
+    /**
+     * 获取当前播放倍速
+     * @returns 当前播放倍速
+     */
+    getSpeed(): number;
+    /**
+     * 获取当前是否可以播放
+     * @returns 是否可以播放
+     */
+    getCanPlay(): boolean;
+    /**
+     * 当前是否存在视频源加载任务（例如 addClip 期间读取视频时长）
+     */
+    isSourceLoading(): boolean;
+    /**
+     * 获取视频源加载状态
+     */
+    getSourceLoadingState(): {
+        isLoading: boolean;
+        pending: number;
+    };
+    /**
+     * 设置缩略图提供器
+     * @param provider 缩略图提供器
+     */
+    setThumbnailProvider(provider: ThumbnailProvider): void;
+    /**
+     * 加载片段的封面
+     * @param clip 片段对象
+     * @returns Promise<boolean> 加载是否成功
+     */
+    private loadClipThumbnails;
+    /**
+     * 刷新指定片段的封面
+     * @param clipId 片段 ID
+     * @returns Promise<boolean> 刷新是否成功
+     */
+    refreshClipThumbnails(clipId: string): Promise<boolean>;
+    /**
+     * 刷新所有片段的封面
+     * @returns Promise<boolean[]> 每个片段的刷新结果
+     */
+    refreshAllClipThumbnails(): Promise<boolean[]>;
+    addClip(clipConfig: ClipConfig): Promise<string>;
+    /**
+     * 批量添加片段。批量模式下仅维护一段连续的视频源加载状态。
+     */
+    addClips(clipConfigs: ClipConfig[]): Promise<string[]>;
+    private addClipInternal;
+    removeClip(clipId: string): void;
+    updateClip(clipId: string, updates: Partial<Clip>): void;
+    splitClip(clipId: string, time: TimeMs): void;
+    splitCurrentClip(): void;
+    getClips(): Clip[];
+    private getExportComposition;
+    exportTimeline(): TimelineExportData;
+    importTimeline(data: TimelineExportData): Promise<void>;
+    getClipsData(): Clip[];
+    /**
+   * 获取插件版本号
+   */
+    getVersion(): string;
+    undo(): boolean;
+    redo(): boolean;
+    getHistoryState(): {
+        past: Action[];
+        future: Action[];
+    };
+    /** 调整缩放比例以适应当前所有片段 */
+    fitZoom(): void;
+    /** 删除轨道内clip 间的空隙 */
+    removeClipGaps(): void;
+    private handleTimeChange;
+    private handleScrollChange;
+    private handleClipUpdate;
+    private handleClipAdd;
+    private handleClipRemove;
+    /**
+     * 检查并重新加载关键帧（如果需要）
+     * @param clip 更新后的片段
+     * @param originalClip 原始片段
+     */
+    private reloadClipThumbnailsIfNeeded;
+    /**
+     * 更新 canPlay 状态
+     */
+    private updateCanPlayState;
+    private handleClipSplit;
+    private handleClipSelect;
+    private handleActionUndo;
+    private handleActionRedo;
+    on(event: TimelineEvent, listener: TimelineEventListener): void;
+    off(event: TimelineEvent, listener: TimelineEventListener): void;
+    private emitEvent;
+    private emitSelectedClipChangeIfNeeded;
+    private beginSourceLoading;
+    private endSourceLoading;
+    private handleClipOverlap;
+    private handleClipCrossTrackPreview;
+    private handleClipCrossTrack;
+    getPlayState(): PlayState;
+    setDuration(duration: TimeMs): void;
+    getDuration(): TimeMs;
+    /**
+     * 调整时间轴大小以适配容器
+     * @param width 新的宽度
+     * @param height 新的高度
+     */
+    resize(width: number, height: number): void;
+    /**
+     * 滚动到指定时间
+     * @param time 目标时间（毫秒）
+     * @param setCurrentTime 是否同时将当前时间设置为该时间点，默认为 false
+     */
+    scrollToTime(time: TimeMs, setCurrentTime?: boolean): void;
+    /**
+     * 选择指定的片段
+     * @param clipId 目标片段的 ID
+     */
+    private notifySelectionChange;
+    selectClip(clipId: string, clip?: any): void;
+    /**
+     * 清空所有轨道的选中状态
+     */
+    clearSelection(): void;
+    /**
+     * 滚动到指定片段
+     * @param clipId 目标片段的 ID
+     * @param options 配置选项
+     */
+    scrollToClip(clipId: string, options?: {
+        selectClip?: boolean;
+        setCurrentTime?: boolean;
+    }): void;
+    /**
+     * 获取当前时间点所在的clip
+     * @returns 当前时间点所在的clip，如果没有则返回null
+     */
+    /**
+     * 获取当前选中的 clip
+     * @returns 当前选中的 clip，如果没有则返回 null
+     */
+    getSelectedClip(): Clip | null;
+    getCurrentActiveClips(): ActiveClipPlaybackInfo[];
+    getCurrentPlaybackPlan(): ResolvedPlaybackPlan;
+    getPlaybackPlanAtTime(time: TimeMs): ResolvedPlaybackPlan;
+    getActiveClipsAtTime(time: TimeMs): ActiveClipPlaybackInfo[];
+    attachPreview(containerOrConfig: HTMLElement | PreviewMountConfig): void;
+    detachPreview(): void;
+    attachClipConfig(container: HTMLElement): TimelineClipConfigController;
+    getPreviewBackendType(): Exclude<PreviewBackendType, 'auto'>;
+    getPreviewAspectRatio(): PreviewAspectRatio;
+    setPreviewAspectRatio(aspectRatio: {
+        width: number;
+        height: number;
+    }): void;
+    resetPreviewAspectRatioToAuto(): void;
+    /**
+     * 删除当前选中的 clip
+     * @returns 是否成功删除了选中的 clip
+     */
+    removeSelectedClip(): boolean;
+    canSeparateClipAudio(clipId: string): boolean;
+    canRestoreClipAudio(clipId: string): boolean;
+    separateClipAudio(clipId: string): Promise<string | null>;
+    restoreClipAudio(clipId: string): boolean;
+    /**
+     * 将片段从一个轨道移动到另一个轨道
+     * @param clipId 要移动的片段 ID
+     * @param targetTrackId 目标轨道 ID
+     * @returns 是否成功移动
+     */
+    moveClipToTrack(clipId: string, targetTrackId: string): boolean;
+    private moveClipToTrackWithHistorySnapshot;
+    /**
+     * 获取轨道内的总时长（包含空隙）
+     * @returns 从0到最后一个clip结束时间的总时长（毫秒）
+     */
+    getTrackTotalDuration(): TimeMs;
+    destroy(): void;
+    /** 清除历史堆栈 */
+    clearHistory(): void;
+    private handleClipChange;
+    private addClipToTrack;
+    private cloneTrackSnapshot;
+    private ensureTrackFromHistorySnapshot;
+    private resolveTrackIdByClipId;
+    private findTrackByClipId;
+    /**
+     * 检查轨道总时长是否变化，如果变化则触发事件并更新时间轴时长
+     */
+    private checkTrackDurationChange;
+    private resolveSelectedClipSnapshot;
+    private commitPreviewVisualTransform;
+    clearAllTracksAndClips(): void;
+}

package/dist/core/{history.d.ts → history/history.d.ts}

@@ -1,4 +1,4 @@
-import { Action, HistoryState } from './types';
+import { Action, Clip, ClipStateUpdate, HistoryState, MoveClipBetweenTracksAction, MoveClipAction, MultiClipUpdateAction, RemoveClipAction, RemoveGapsAction, RestoreClipAudioAction, ResizeClipAction, SeparateClipAudioAction, SetTimeAction, SplitClipAction, Track, UpdateClipAction, AddClipAction } from '../models/types';
 export declare class HistoryManager {
     private state;
     private maxHistorySize;
@@ -37,41 +37,43 @@ export declare class HistoryManager {
     /**
      * 创建添加片段操作
      */
-    createAddClipAction(clip: any): Action;
+    createAddClipAction(clip: Clip): AddClipAction;
     /**
      * 创建移除片段操作
      */
-    createRemoveClipAction(clip: any): Action;
+    createRemoveClipAction(clip: Clip): RemoveClipAction;
     /**
      * 创建更新片段操作
      */
-    createUpdateClipAction(clipId: string, updates: any, previousState: any): Action;
+    createUpdateClipAction(clipId: string, updates: Partial<Clip>, previousState: Partial<Clip>): UpdateClipAction;
     /**
      * 创建分割片段操作
      */
-    createSplitClipAction(originalClip: any, clip1: any, clip2: any): Action;
+    createSplitClipAction(originalClip: Clip, clip1: Clip, clip2: Clip): SplitClipAction;
     /**
      * 创建移动片段操作
      */
-    createMoveClipAction(clipId: string, newStartTime: number, previousStartTime: number): Action;
+    createMoveClipAction(clipId: string, newStartTime: number, previousStartTime: number): MoveClipAction;
     /**
      * 创建调整片段大小操作
      */
-    createResizeClipAction(clipId: string, newDuration: number, newStartTime: number, previousDuration: number, previousStartTime: number): Action;
+    createResizeClipAction(clipId: string, newDuration: number, newStartTime: number, previousDuration: number, previousStartTime: number): ResizeClipAction;
     /**
      * 创建设置时间操作
      */
-    createSetTimeAction(newTime: number, previousTime: number): Action;
+    createSetTimeAction(newTime: number, previousTime: number): SetTimeAction;
     /**
      * 创建移除间隙操作
      */
-    createRemoveGapsAction(clipsBefore: any[]): Action;
+    createRemoveGapsAction(clipsBefore: Clip[]): RemoveGapsAction;
     /**
      * 创建多个片段同时更新操作
      */
-    createMultiClipUpdateAction(clipUpdates: Array<{
-        clipId: string;
-        newState: any;
-        previousState: any;
-    }>): Action;
+    createMultiClipUpdateAction(clipUpdates: ClipStateUpdate[]): MultiClipUpdateAction;
+    /**
+     * 创建跨轨道移动片段操作
+     */
+    createMoveClipBetweenTracksAction(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | 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;
 }

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

@@ -0,0 +1,3 @@
+export { HistoryManager } from './history';
+export { TimelineHistoryExecutor } from './timelineHistoryExecutor';
+export { TimelineHistoryRecorder } from './timelineHistoryRecorder';

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

@@ -0,0 +1,23 @@
+import type { Action, Clip, Track } from '../models/types';
+export interface TimelineHistoryExecutionTrack {
+    addClip(clip: Clip): void;
+}
+export interface TimelineHistoryExecutionTarget {
+    removeClip(clipId: string): void;
+    addClipToTrack(trackId: string, clip: Clip): boolean;
+    updateClip(clipId: string, updates: Partial<Clip>): void;
+    moveClipToTrack(clipId: string, targetTrackId: string): boolean;
+    ensureTrackFromHistorySnapshot(trackSnapshot: Track): string | null;
+    removeClipGaps(): void;
+    getClips(): Clip[];
+    findTrackByClipId(clipId: string): TimelineHistoryExecutionTrack | null;
+    getDefaultTrack(): TimelineHistoryExecutionTrack | null;
+    loadClipThumbnails?(clip: Clip): Promise<boolean> | void;
+}
+export declare class TimelineHistoryExecutor {
+    private readonly target;
+    constructor(target: TimelineHistoryExecutionTarget);
+    executeUndo(action: Action): void;
+    executeRedo(action: Action): void;
+    private restoreMovedClip;
+}

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

@@ -0,0 +1,15 @@
+import { HistoryManager } from '../history/history';
+import type { Action, Clip, ClipStateUpdate, Track } from '../models/types';
+export declare class TimelineHistoryRecorder {
+    private readonly history;
+    constructor(history: HistoryManager);
+    recordAddClip(clip: Clip): Action;
+    recordRemoveClip(clip: Clip): Action;
+    recordClipUpdate(clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]): Action | null;
+    recordSplitClip(clip1: Clip, clip2: Clip): Action;
+    recordRemoveGaps(clipsBefore: Clip[]): Action | null;
+    recordMoveClipBetweenTracks(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | 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;
+    private createClipUpdateAction;
+}

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

@@ -0,0 +1 @@
+export * from './timelineTrackLayout';

package/dist/core/layout/timelineManagerDom.d.ts

@@ -0,0 +1,22 @@
+import type { Theme } from '../models/types';
+export declare const TIMELINE_MANAGER_LEFT_PANEL_WIDTH = 200;
+export declare const TIMELINE_MANAGER_SCROLLBAR_SIZE = 8;
+export interface TimelineManagerLayoutElements {
+    headerCorner: HTMLDivElement;
+    headerViewport: HTMLDivElement;
+    headerCanvasHost: HTMLDivElement;
+    trackInfoViewport: HTMLDivElement;
+    bodyViewport: HTMLDivElement;
+    bodyCanvasHost: HTMLDivElement;
+    verticalScrollbarCanvasHost: HTMLDivElement;
+    horizontalScrollbarCanvasHost: HTMLDivElement;
+    playheadOverlay: HTMLDivElement;
+}
+export interface CreateTimelineManagerLayoutOptions {
+    theme: Theme;
+    timeScaleHeight: number;
+    leftPanelWidth?: number;
+    scrollbarSize?: number;
+}
+export declare function ensureTimelineManagerStyles(): void;
+export declare function createTimelineManagerLayout(container: HTMLElement, options: CreateTimelineManagerLayoutOptions): TimelineManagerLayoutElements;

package/dist/core/layout/timelineTrackLayout.d.ts

@@ -0,0 +1,10 @@
+import { Track, TrackType } from '../models/types';
+export interface TrackLayout {
+    trackId: string;
+    y: number;
+    height: number;
+}
+export declare function getTrackHeightByType(type: TrackType): number;
+export declare function calculateTrackY(tracks: Track[], trackId: string, timeScaleHeight: number): number;
+export declare function calculateTotalTrackHeight(tracks: Track[], timeScaleHeight: number): number;
+export declare function buildTrackLayouts(tracks: Track[], timeScaleHeight: number): TrackLayout[];

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

@@ -0,0 +1,3 @@
+import type { Clip, ClipEntity, ClipViewState } from '../models/types';
+export declare function createClipViewState(overrides?: Partial<ClipViewState>): ClipViewState;
+export declare function createClipWithViewState(clip: ClipEntity, viewState?: Partial<ClipViewState>): Clip;

package/dist/core/{constants.d.ts → models/constants.d.ts}

@@ -20,3 +20,7 @@ export declare const TIME_SCALE: {
 };
 export declare const TIMELINE_LEFT_PADDING = 15;
 export declare const MIN_CLIP_LINE_WIDTH = 6;
+export declare const TRACK_HEIGHT: {
+    VIDEO: number;
+    AUDIO: number;
+};

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

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './constants';
+export * from './clipState';