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

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

@@ -1,9 +1,10 @@
-import type { ActiveClipPlaybackInfo, ClipVisualTransform, PlayState, PreviewAspectRatio, TimeMs, TrackType } from '../models/types';
-import type { PreviewPendingState } from './previewBackend';
+import type { ActiveClipPlaybackInfo, ClipVisualTransform, PlayState, PreviewAspectRatio, PreviewSourceResolver, TimeMs, TrackType } from '../models/types';
+import type { PreviewPendingState, PreviewRuntimeState } from './previewBackend';
 interface TimelinePreviewSessionCallbacks {
     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;
@@ -15,6 +16,7 @@ interface TimelinePreviewSessionDependencies {
     rootClassName?: string;
     frameClassName?: string;
     slotClassNamePrefix?: string;
+    previewSourceResolver?: PreviewSourceResolver;
 }
 export interface TimelinePreviewSyncPayload {
     activeClips: ActiveClipPlaybackInfo[];
@@ -24,7 +26,7 @@ export interface TimelinePreviewSyncPayload {
     currentTime: TimeMs;
     playState: PlayState;
     speed: number;
-    selectedClipId?: string | null;
+    primarySelectedClipId?: string | null;
     syncRequestId?: number;
 }
 export declare class TimelinePreviewSession {
@@ -39,9 +41,13 @@ export declare class TimelinePreviewSession {
     private readonly trackSlots;
     private audioContext;
     private masterGainNode;
-    private isBuffering;
     private loadingCount;
-    private selectedClipId;
+    private isBuffering;
+    private bufferingVisibleTimeoutId;
+    private lastRuntimeSignature;
+    private lastRuntimeState;
+    private lastSettledSyncRequestId;
+    private primarySelectedClipId;
     private transientVisualTransform;
     private readonly callbacks;
     private readonly dependencies;
@@ -50,9 +56,14 @@ export declare class TimelinePreviewSession {
     private resolvedAutoAspectRatio;
     private aspectRatioProbe;
     private aspectRatioProbeSrc;
+    private aspectRatioProbeResolveToken;
     private isAspectRatioProbeLoading;
     private pendingState;
+    private activeSyncRequestId;
+    private isSyncProjecting;
     constructor(callbacks?: TimelinePreviewSessionCallbacks, dependencies?: TimelinePreviewSessionDependencies);
+    private logLoadTrace;
+    private buildSlotTraceData;
     hasPreview(): boolean;
     attach(container: HTMLElement): void;
     detach(): void;
@@ -65,7 +76,15 @@ export declare class TimelinePreviewSession {
     private destroySlot;
     private getTrackSlots;
     private swapTrackSlots;
-    private assignClipToSlot;
+    private applyTrackPlan;
+    private applySlotTarget;
+    private resolveDesiredSource;
+    private slotNeedsRecovery;
+    private recoverSlot;
+    private finishSlotRecovery;
+    private applyResolvedSlotState;
+    private isCurrentRequest;
+    private failSlot;
     private configureAudioRouting;
     private syncCurrentSlot;
     private preparePreloadSlot;
@@ -75,13 +94,13 @@ export declare class TimelinePreviewSession {
     private resumeAudioContext;
     private updateFrameLayout;
     private maybeResolveAutoAspectRatio;
+    private resolveAspectRatioProbeSource;
     private getAspectRatioProbe;
     private tryResolveAutoAspectRatioFromSlot;
     private handleResolvedAutoAspectRatio;
-    private refreshBufferingState;
-    private setBufferingState;
-    private refreshLoadingState;
-    private setLoadingCount;
+    private refreshRuntimeState;
+    private syncVisibleBufferingState;
+    private clearBufferingVisibleTimeout;
     private refreshPendingOverlay;
     private handlePreviewTransformChange;
     private refreshVisualLayout;

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

@@ -0,0 +1,53 @@
+import type { TimeMs } from '../models/types';
+import type { PreviewPendingState, PreviewRuntimeState } from './previewBackend';
+export interface TimelinePendingPreviewState {
+    mode: 'seek' | 'scrub';
+    targetTime: TimeMs;
+    resumePlayOnReady: boolean;
+    errorMessage: string | null;
+    timeoutId: ReturnType<typeof setTimeout> | null;
+    awaitingSync: boolean;
+    syncRequestId: number;
+}
+interface TimelinePreviewStateControllerCallbacks {
+    applyPendingState: (state: PreviewPendingState | null) => void;
+    emitBufferingStateChange: (isBuffering: boolean) => void;
+    emitSourceLoadingStateChange: () => void;
+    resumePlayback: () => void;
+    requestPreviewSync: () => void;
+}
+interface TimelinePreviewStateControllerOptions {
+    callbacks: TimelinePreviewStateControllerCallbacks;
+    pendingTimeoutMs?: number;
+}
+export declare class TimelinePreviewStateController {
+    private readonly callbacks;
+    private readonly pendingTimeoutMs;
+    private _previewSourceLoadingCount;
+    private _previewBuffering;
+    private _previewAwaitingMedia;
+    private _pendingPreviewState;
+    private _nextPendingPreviewSyncRequestId;
+    constructor(options: TimelinePreviewStateControllerOptions);
+    get previewSourceLoadingCount(): number;
+    set previewSourceLoadingCount(value: number);
+    get previewBuffering(): boolean;
+    set previewBuffering(value: boolean);
+    get pendingPreviewState(): TimelinePendingPreviewState | null;
+    set pendingPreviewState(value: TimelinePendingPreviewState | null);
+    get nextPendingPreviewSyncRequestId(): number;
+    set nextPendingPreviewSyncRequestId(value: number);
+    handleBufferingStateChange(isBuffering: boolean): void;
+    handleSourceLoadingChange(pending: number): void;
+    handleRuntimeStateChange(state: PreviewRuntimeState): void;
+    markSyncProcessed(syncRequestId?: number): void;
+    beginPendingPreview(time: TimeMs, mode: 'seek' | 'scrub', resumePlayOnReady: boolean): void;
+    buildPreviewPendingState(): PreviewPendingState | null;
+    updatePendingPreviewState(): void;
+    retryPendingPreview(): void;
+    clearPendingPreviewState(): void;
+    resetPreviewRuntimeState(): void;
+    private ensurePendingPreviewTimeout;
+    private clearPendingPreviewTimeout;
+}
+export {};

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

@@ -4,7 +4,7 @@ export interface SelectedClipSnapshot {
     hasSelectedClip: boolean;
 }
 interface ResolveSelectedClipOptions {
-    getSelectedClip: () => Clip | null;
+    getPrimarySelectedClip: () => Clip | null;
     findFallbackSelectedClip?: () => Clip | null;
 }
 interface EmitSelectedClipChangeOptions {

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

@@ -1,3 +1,4 @@
+import { type TimelinePreviewBackend } from '../controllers';
 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';
@@ -37,6 +38,7 @@ export declare class TimelineManager {
     private verticalScrollbar;
     private isExecutingHistoryAction;
     private lastTrackDuration;
+    private lastEffectiveTrackDuration;
     private thumbnailProvider;
     private canPlay;
     private sourceLoadingCount;
@@ -47,16 +49,12 @@ export declare class TimelineManager {
     private timelinePresentationAdapter?;
     private timelineTrackBridge?;
     private timelinePlaybackResolver?;
-    private previewSession?;
-    private previewMountContainer;
-    private resolvedPreviewBackend;
-    private runtimePreviewBackendOverride;
+    private previewRuntimeController?;
+    private previewStateController?;
+    private previewPlaybackSuspendedByBuffering;
+    private previewPlaybackAutoResume;
+    private previewBufferingSuspendTimeoutId;
     private lastSelectedClipId;
-    private previewSourceLoadingCount;
-    private previewBuffering;
-    private pendingPreviewState;
-    private nextPendingPreviewSyncRequestId;
-    private activePreviewCallbackToken;
     private previewAspectRatio;
     private readonly bodyViewportScrollListener;
     private readonly bodyCanvasHostClickListener;
@@ -73,11 +71,29 @@ export declare class TimelineManager {
     private getTimelinePresentationAdapter;
     private getTimelineTrackBridge;
     private getTimelinePlaybackResolver;
+    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);
+    private get previewSourceLoadingCount();
+    private set previewSourceLoadingCount(value);
+    get previewBuffering(): boolean;
+    set previewBuffering(value: boolean);
+    private get pendingPreviewState();
+    private set pendingPreviewState(value);
+    get nextPendingPreviewSyncRequestId(): number;
+    set nextPendingPreviewSyncRequestId(value: number);
+    private getPreviewStateController;
+    private getPreviewRuntimeController;
     private resolveConfiguredPreviewBackend;
     private createPreviewBackendCallbacks;
-    private createPreviewBackend;
     private isActivePreviewCallbackToken;
-    private getPreviewSession;
     private getEventDispatcher;
     private getDefaultTrackForHistory;
     private getTimelineHistoryRecorder;
@@ -120,14 +136,11 @@ export declare class TimelineManager {
     private registerPreviewAutoAspectRatioClip;
     private syncPreviewSession;
     private beginPendingPreview;
-    private updatePendingPreviewState;
+    updatePendingPreviewState(): void;
     private buildPreviewPendingState;
-    private ensurePendingPreviewTimeout;
-    private clearPendingPreviewTimeout;
     private clearPendingPreviewState;
     private resetPreviewRuntimeState;
     private destroyPreviewSession;
-    private recreateDetachedPreviewSession;
     private retryPendingPreview;
     private handlePreviewBackendRuntimeError;
     init(container: HTMLElement): void;
@@ -171,6 +184,8 @@ export declare class TimelineManager {
     pause(): void;
     togglePlay(): void;
     private animate;
+    private syncPlaybackClockToPreviewBuffering;
+    private clearPreviewBufferingSuspendTimeout;
     setCurrentTime(time: TimeMs): void;
     getCurrentTime(): TimeMs;
     setEnableClipSnap(enabled: boolean): void;
@@ -255,6 +270,7 @@ export declare class TimelineManager {
     private getExportComposition;
     exportTimeline(): TimelineExportData;
     importTimeline(data: TimelineExportData): Promise<void>;
+    private stopPlaybackForImport;
     getClipsData(): Clip[];
     /**
    * 获取插件版本号
@@ -318,12 +334,19 @@ export declare class TimelineManager {
      * @param clipId 目标片段的 ID
      */
     private notifySelectionChange;
+    private syncPrimarySelectionFromSelectionStore;
+    private getOrderedSelectionClipIds;
+    setSelection(clipIds: string[], options?: {
+        preferredPrimaryClipId?: string | null;
+        selectedClipEventClip?: Clip | null;
+    }): void;
     selectClip(clipId: string, clip?: any): void;
     /**
      * 清空所有轨道的选中状态
      */
     clearSelection(): void;
     getSelectedClipIds(): string[];
+    getPrimarySelectedClipId(): string | null;
     addToSelection(clipId: string): void;
     removeFromSelection(clipId: string): void;
     toggleSelection(clipId: string): void;
@@ -332,7 +355,6 @@ export declare class TimelineManager {
     separateSelectedClipsAudio(): void;
     selectAllClips(): void;
     private emitSelectionChangeEvent;
-    private updateAllTracksSelectionVisual;
     /**
      * 滚动到指定片段
      * @param clipId 目标片段的 ID
@@ -351,6 +373,7 @@ export declare class TimelineManager {
      * @returns 当前选中的 clip，如果没有则返回 null
      */
     getSelectedClip(): Clip | null;
+    getPrimarySelectedClip(): Clip | null;
     getSelectedClips(): Clip[];
     canDeleteSelectedClips(): boolean;
     getSelectedClipAudioAction(): 'separate' | 'restore' | null;
@@ -364,6 +387,7 @@ export declare class TimelineManager {
     detachPreview(): void;
     attachClipConfig(container: HTMLElement): TimelineClipConfigController;
     getPreviewBackendType(): Exclude<PreviewBackendType, 'auto'>;
+    hasAttachedPreview(): boolean;
     getPreviewAspectRatio(): PreviewAspectRatio;
     setPreviewAspectRatio(aspectRatio: {
         width: number;
@@ -378,6 +402,7 @@ export declare class TimelineManager {
     removeSelectedClips(): boolean;
     canSeparateClipAudio(clipId: string): boolean;
     canRestoreClipAudio(clipId: string): boolean;
+    private resolvePreferredSeparatedAudioTrackId;
     separateClipAudio(clipId: string): Promise<string | null>;
     restoreClipAudio(clipId: string): boolean;
     private applySelectedClipAudioAction;
@@ -390,8 +415,8 @@ export declare class TimelineManager {
     moveClipToTrack(clipId: string, targetTrackId: string): boolean;
     private moveClipToTrackWithHistorySnapshot;
     /**
-     * 获取轨道内的总时长（包含空隙）
-     * @returns 从0到最后一个clip结束时间的总时长（毫秒）
+     * 获取轨道内的有效总时长（去除首尾空白）
+     * @returns 最早 clip 起点到最晚 clip 终点的时长（毫秒）
      */
     getTrackTotalDuration(): TimeMs;
     destroy(): void;

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

@@ -20,7 +20,7 @@ export interface ClipVisualTransform {
     y: number;
     scale: number;
 }
-export type PreviewBackendType = 'dom' | 'canvas' | 'pixi' | 'auto';
+export type PreviewBackendType = 'dom' | 'canvas' | 'auto';
 export interface Mp4PreviewMediaSource {
     url: string;
     mimeType: string;

package/dist/core/presentation/timelinePresentationAdapter.d.ts

@@ -17,6 +17,6 @@ export declare class TimelinePresentationAdapter {
     syncZoom(timeline: TimelineZoomView | null, playhead: TimelineZoomView | null, tracks: TimelineTrackCollection, zoom: number): void;
     syncScrollLeft(playhead: TimelineScrollView | null, tracks: TimelineTrackCollection, scrollLeft: number): void;
     syncScrollTop(panel: TimelineVerticalScrollView | null, scrollbar: TimelineVerticalScrollView | null, scrollTop: number): void;
-    syncSelection(tracks: TimelineTrackCollection, selectedClipId: string | null, selectedClipIds?: string[]): void;
+    syncSelection(tracks: TimelineTrackCollection, selectedClipIds: string[]): void;
     findSelectedClip(tracks: TimelineTrackCollection): Clip | null;
 }

package/dist/core/stores/selectionStore.d.ts

@@ -1,11 +1,13 @@
 export declare class SelectionStore {
     private selectedClipIds;
+    getPrimarySelectedClipId(): string | null;
     getSelectedClipId(): string | null;
     getSelectedClipIds(): string[];
     addToSelection(clipId: string): void;
     removeFromSelection(clipId: string): void;
     toggleSelection(clipId: string): void;
     setSelection(clipIds: string[]): void;
+    setPrimarySelection(clipId: string | null): void;
     setSelectedClipId(clipId: string | null): void;
     clear(): void;
     hasSelection(): boolean;

package/dist/core/stores/timelineStore.d.ts

@@ -11,13 +11,18 @@ export interface TimelineStoreInitialState {
     viewportHeight?: number;
     contentHeight?: number;
     selectedClipId?: string | null;
+    selectedClipIds?: string[];
 }
 export declare class TimelineStore {
     private readonly selectionStore;
     private readonly playbackStore;
     private readonly viewportStore;
     constructor(initial: TimelineStoreInitialState);
+    getPrimarySelectedClipId(): string | null;
     getSelectedClipId(): string | null;
+    getSelectedClipIds(): string[];
+    setSelectedClipIds(clipIds: string[]): void;
+    setPrimarySelectedClipId(clipId: string | null): void;
     setSelectedClipId(clipId: string | null): void;
     clearSelection(): void;
     hasSelection(): boolean;

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

@@ -13,10 +13,9 @@ export interface TimelineTrackCollectionItem extends TimelineTrackView {
     updateClip?(clipId: string, updates: Partial<Clip>): void;
     updateClipPosition?(clipId: string, newStartTime: TimeMs, isFinal: boolean, previewOffsetY?: number): void;
     removeClipGaps?(): void;
-    updateSelectionVisual?(selectedClipId: string | null): void;
+    setSelection?(clipIds: string[], preferredClipId?: string | null): void;
     clearSelection?(): void;
-    getSelectedClip?(): Clip | null;
-    selectClip?(clipId: string): void;
+    getPrimarySelectedClip?(): Clip | null;
     setTrackY?(y: number): void;
     setTrackStackOrder?(order: number): void;
     setTrackHeight?(height: number): void;
@@ -26,7 +25,6 @@ export interface TimelineTrackCollectionItem extends TimelineTrackView {
     getTrackGroup?(): {
         destroy(): void;
     };
-    updateClipSelection?(clipId: string, isSelected: boolean): void;
 }
 export declare class TimelineTrackCollection {
     private readonly tracks;
@@ -52,6 +50,8 @@ export declare class TimelineTrackCollection {
     moveClipToTrack(clip: Clip, sourceTrackId: string, targetTrackId: string): boolean;
     removeClipGaps(): void;
     clearSelection(): void;
+    syncSelection(clipIds: string[], preferredClipId?: string | null): void;
+    findPrimarySelectedClip(): Clip | null;
     forEach(callback: (track: TimelineTrackCollectionItem) => void): void;
     private findIndexById;
     private resolveTrackId;

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

@@ -14,6 +14,7 @@ export declare class TrackManager {
     private insertTrack;
     muteTrack(trackId: string, isMuted: boolean): boolean;
     isTrackMuted(trackId: string): boolean;
+    clearAllTracks(): void;
     getTrackCount(): number;
     getTrackCountByType(type: TrackType): number;
 }