@linker-design-plus/timeline-track 2.0.13 → 2.0.15

package/README.md

@@ -89,6 +89,7 @@ timeline.on('history_change', (_event, data) => {
 - `updateClip(clipId, updates)` / `removeClip(clipId)`
 - `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
 - `splitCurrentClip()` / `removeClipGaps()`
+- `getRenderedHeight()`
 - `undo()` / `redo()` / `clearHistory()`
 - `attachPreview(containerOrConfig)` / `detachPreview()`
 - `exportTimeline()` / `loadDraft(data)`
@@ -103,6 +104,9 @@ timeline.on('history_change', (_event, data) => {
 
 - 播放 / 暂停：`Space`
 - 删除片段：`Delete` / `Backspace`
+- 复制片段：`Mod+C`
+- 剪切片段：`Mod+X`
+- 粘贴片段：`Mod+V`
 - 分离 / 还原音频：`Mod+Alt+A`
 - 分割片段：`Mod+B`
 - 撤销：`Mod+Z`

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

@@ -94,8 +94,6 @@ export declare class ClipConfigPanel {
     private syncVoiceStateForClip;
     private syncActiveTab;
     private supportsVoicePanel;
-    private resolveDefaultVoiceFilterTag;
-    private getVisibleVoiceOptions;
     private ensureVoiceFilters;
     private handleVoiceFilterChange;
     private handleVoiceSelect;

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

@@ -79,6 +79,7 @@ export declare class ClipConfigPanelRenderer extends LitDomRenderer<ClipConfigPa
     private renderVoiceLoadingOverlay;
     private renderEmptyState;
     private renderPanel;
+    private renderTabPanel;
     private renderTabBar;
     private renderActionBar;
     private renderVoiceActionBar;

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

@@ -1,5 +1,6 @@
 import type { ActiveClipPlaybackInfo, Clip, ClipVisualTransform, PlayState, PreviewAspectRatio, PreviewMediaSource, PreviewSourceResolver, TextPreviewFontConfig, TimeMs } from '../models/types';
 import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
+import type { DiagnosticsCenter, DiagnosticEmitInput } from '../../utils/diagnostics';
 export interface TimelinePreviewSyncPayload {
     activeClips: ActiveClipPlaybackInfo[];
     nextClips: ActiveClipPlaybackInfo[];
@@ -8,6 +9,7 @@ export interface TimelinePreviewSyncPayload {
     currentTime: TimeMs;
     playState: PlayState;
     speed: number;
+    interactionMode?: 'steady' | 'seek' | 'scrub';
     primarySelectedClipId?: string | null;
     syncRequestId?: number;
 }
@@ -17,6 +19,7 @@ export interface TimelinePreviewBackendCallbacks {
     onSyncProcessed?: (syncRequestId?: number) => void;
     onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
+    onPreviewClipSelect?: (clipId: string) => void;
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onPendingPreviewRetry?: () => void;
     onRuntimeError?: (error: unknown) => void;
@@ -69,6 +72,8 @@ export interface TimelinePreviewBackendOptions {
     previewSourceResolver?: PreviewSourceResolver;
     textPreviewFont?: TextPreviewFontConfig | null;
     sourceMediaRegistry?: SourceMediaRegistry;
+    diagnostics?: DiagnosticsCenter;
+    getDiagnosticsContext?: () => Partial<DiagnosticEmitInput>;
     rootClassName?: string;
     frameClassName?: string;
     slotClassNamePrefix?: string;

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

@@ -3,6 +3,7 @@ import type { DomRenderer } from '../renderers/domRenderer';
 export interface PreviewPendingOverlayViewModel {
     pendingState: PreviewPendingState | null;
     runtimeState: PreviewRuntimeState;
+    isBuffering: boolean;
 }
 export declare class PreviewPendingOverlayRenderer implements DomRenderer<PreviewPendingOverlayViewModel> {
     private container;

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

@@ -17,6 +17,7 @@ export interface ClipSelectPlan {
 export declare function applyClipMutationEffects(handlers: ClipMutationEffectHandlers): void;
 export declare function applyClipUpdateEffects(handlers: ClipUpdateMutationEffectHandlers): void;
 export declare function shouldReloadClipThumbnails(clip: Clip, originalClip?: Clip, hasThumbnailProvider?: boolean): boolean;
+export declare function calculatePlaybackEndTime(clips: Pick<Clip, 'endTime'>[]): number;
 export declare function calculateCanPlayState(clips: Pick<Clip, 'endTime'>[], currentTime: number): boolean;
 interface SyncCanPlayStateOptions {
     currentCanPlay: boolean;

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

@@ -2,11 +2,17 @@ import type { TimelineKeyboardShortcutsConfig } from '../models';
 export interface TimelineKeyboardShortcutsControllerCallbacks {
     togglePlay(): void;
     deleteSelectedClips(): void;
+    copySelectedClips(): void;
+    cutSelectedClips(): void;
+    pasteClipboardClips(): Promise<boolean> | boolean;
     toggleSelectedClipsAudio(): Promise<boolean>;
     splitCurrentClip(): void;
     undo(): boolean;
     redo(): boolean;
     canDeleteSelectedClips(): boolean;
+    canCopySelectedClips(): boolean;
+    canCutSelectedClips(): boolean;
+    canPasteClipboardClips(): boolean;
     canSplitSelectedClip(): boolean;
     canToggleSelectedClipsAudio(): boolean;
 }

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

@@ -1,12 +1,14 @@
 import type { ActiveClipPlaybackInfo, ClipVisualTransform, PlayState, PreviewAspectRatio, PreviewSourceResolver, TextPreviewFontConfig, TimeMs, TrackType } from '../models/types';
 import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
 import type { PreviewPendingState, PreviewRuntimeState } from './previewBackend';
+import { type DiagnosticEmitInput, type DiagnosticsCenter } from '../../utils/diagnostics';
 interface TimelinePreviewSessionCallbacks {
     onBufferingStateChange?: (isBuffering: boolean) => void;
     onSourceLoadingChange?: (pending: number) => void;
     onSyncProcessed?: (syncRequestId?: number) => void;
     onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
+    onPreviewClipSelect?: (clipId: string) => void;
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onPendingPreviewRetry?: () => void;
 }
@@ -14,6 +16,8 @@ interface TimelinePreviewSessionDependencies {
     createMediaElement?: (kind: TrackType, role: 'current' | 'preload') => HTMLMediaElement;
     createAspectRatioProbe?: () => HTMLVideoElement;
     createAudioContext?: () => AudioContext | null;
+    diagnostics?: DiagnosticsCenter;
+    getDiagnosticsContext?: () => Partial<DiagnosticEmitInput>;
     rootClassName?: string;
     frameClassName?: string;
     slotClassNamePrefix?: string;
@@ -29,6 +33,7 @@ export interface TimelinePreviewSyncPayload {
     currentTime: TimeMs;
     playState: PlayState;
     speed: number;
+    interactionMode?: 'steady' | 'seek' | 'scrub';
     primarySelectedClipId?: string | null;
     syncRequestId?: number;
 }
@@ -73,8 +78,10 @@ export declare class TimelinePreviewSession {
     private pendingState;
     private activeSyncRequestId;
     private isSyncProjecting;
+    private readonly deferredPreloadSlotKeys;
+    private deferredPreloadFlushScheduled;
     constructor(callbacks?: TimelinePreviewSessionCallbacks, dependencies?: TimelinePreviewSessionDependencies);
-    private logLoadTrace;
+    private emitDiagnostic;
     private buildSlotTraceData;
     hasPreview(): boolean;
     attach(container: HTMLElement): void;
@@ -85,6 +92,7 @@ export declare class TimelinePreviewSession {
     getAspectRatio(): PreviewAspectRatio;
     private createMediaElement;
     private createSlot;
+    private resetSlotRecoveryTracking;
     private destroySlot;
     private getTrackSlots;
     private swapTrackSlots;
@@ -95,8 +103,24 @@ export declare class TimelinePreviewSession {
     private slotNeedsRecovery;
     private recoverSlot;
     private finishSlotRecovery;
+    private getSlotKey;
+    private isActiveCurrentSlot;
+    private hasBlockingActiveCurrentSlot;
+    private shouldDeferPreloadTarget;
+    private shouldDeferPreloadRecovery;
+    private buildDeferredPreloadTarget;
+    private deferPreloadTarget;
+    private deferPreloadRecovery;
+    private scheduleDeferredPreloadFlush;
+    private flushDeferredPreloads;
     private applyResolvedSlotState;
     private isCurrentRequest;
+    private shouldIgnoreExpectedEmptied;
+    private shouldIgnoreExpectedAbort;
+    private shouldIgnoreClearedSlotRecoverableEvent;
+    private shouldSkipImmediatePreloadRecovery;
+    private isBackgroundPreloadSlot;
+    private parkPreloadSlot;
     private failSlot;
     private configureAudioRouting;
     private syncCurrentSlot;

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

@@ -2,6 +2,7 @@ import { type TimelinePreviewBackend } from '../controllers';
 import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener as TimelineEventListener, TimelineExportData, Track as TrackEntity, ThumbnailProvider, TrackInsertionPlacement, TrackType, ActiveClipPlaybackInfo, PreviewAspectRatio, PreviewMountConfig, PreviewBackendType, SelectedClipAudioAction, ClipConfigVoicePanelOptions } from '../models';
 import type { ResolvedPlaybackPlan } from '../controllers/timelinePlaybackResolver';
 import { TimelineClipConfigController } from '../controllers/timelineClipConfigController';
+import { type DiagnosticExportPackage, type DiagnosticLiveSnapshot, type DiagnosticsListener, type DiagnosticsLiveListener, type DiagnosticSessionSnapshot } from '../../utils/diagnostics';
 export declare class TimelineManager {
     private timeline;
     private tracks;
@@ -63,13 +64,27 @@ export declare class TimelineManager {
     private readonly bodyCanvasHostClickListener;
     private readonly rootWheelListener;
     private keyboardShortcutsController;
+    private clipClipboard;
     private mountManager;
     private pendingDraftData;
     private selectionStore;
     private multiDragSession;
     private clipRemovalBatchDepth;
     private splitOperationDepth;
+    private readonly diagnostics;
+    private diagnosticsPanel;
+    private previewRuntimeState;
+    private previewActiveClipIds;
+    private playbackAttemptId;
+    private lastPreviewSyncedPlayState;
+    private previewSyncInteractionMode;
     constructor(config?: Partial<TimelineConfig>);
+    private createPlaybackAttemptId;
+    private refreshPlaybackAttempt;
+    private emitDiagnostic;
+    private buildDiagnosticsRuntimeState;
+    private buildPreviewDiagnosticsContext;
+    private mountDiagnosticsPanel;
     private getTimelineStore;
     private getTimelineCommands;
     private getTrackCollection;
@@ -136,14 +151,17 @@ export declare class TimelineManager {
     private getTracksSortedByOrder;
     private getPlaybackTracksSnapshot;
     private buildPlaybackPlan;
+    private hasTimelineVideoClip;
     private getPreviewAutoAspectRatioClipOrderMap;
     private getNextPreviewAutoAspectRatioOrder;
     private getAutoAspectRatioClip;
     private registerPreviewAutoAspectRatioClip;
     private syncPreviewSession;
+    private syncPreviewPlaybackStateIfNeeded;
     private beginPendingPreview;
     updatePendingPreviewState(): void;
     private buildPreviewPendingState;
+    private buildPreviewIndicatorState;
     private clearPendingPreviewState;
     private resetPreviewRuntimeState;
     private destroyPreviewSession;
@@ -321,9 +339,20 @@ export declare class TimelineManager {
     private applyGeneratedAudioClipResult;
     private syncTextClipDurationToAudio;
     private doesClipOverlapOnTrack;
+    private doesClipGroupOverlapOnTrack;
     private findNearestAvailableTrackForClip;
-    private relocateGeneratedAudioClipIfNeeded;
+    private resolveOverlapRelocationTargetTrackId;
+    private relocateClipToAvoidOverlap;
+    private buildClipboardPasteGroups;
+    private createTracksForTypeBoundary;
+    private buildClipboardPasteGroupPlacementClips;
+    private ensureClipboardPasteSourceTracks;
+    private resolveClipboardPasteTypeGroupAssignments;
+    private resolvePreferredTrackIndexForPasteGroup;
+    private resolveClipboardPasteTrackAssignments;
+    private relocateClipIfNeeded;
     private regenerateVoiceLinkedAudioClips;
+    private getSelectedTextClipsForVoiceGeneration;
     private handleVoiceGenerateAction;
     private primeOrLoadClipThumbnails;
     private markClipThumbnailLoadCompleted;
@@ -348,6 +377,13 @@ export declare class TimelineManager {
     getPlayState(): PlayState;
     setDuration(duration: TimeMs): void;
     getDuration(): TimeMs;
+    /**
+     * 获取当前时间轴内容完整渲染高度。
+     *
+     * 该高度包含顶部时间刻度、所有轨道内容和底部横向滚动条，可供外部容器
+     * 在需要贴合内容时作为高度参考。
+     */
+    getRenderedHeight(): number;
     /**
      * 调整时间轴大小以适配容器
      * @param width 新的宽度
@@ -383,6 +419,15 @@ export declare class TimelineManager {
     toggleSelection(clipId: string): void;
     isClipSelected(clipId: string): boolean;
     deleteSelectedClips(): void;
+    copySelectedClips(): boolean;
+    cutSelectedClips(): boolean;
+    pasteClipboardClips(): Promise<boolean>;
+    private deleteSelectedClipsWithHistoryLabel;
+    private captureSelectedClipsToClipboard;
+    private cloneClipForClipboard;
+    private buildClipboardPasteClipConfig;
+    private resolveClipboardPasteTrackId;
+    private generateClipId;
     separateSelectedClipsAudio(): void;
     selectAllClips(): void;
     private emitSelectionChangeEvent;
@@ -406,6 +451,9 @@ export declare class TimelineManager {
     getSelectedClip(): Clip | null;
     getPrimarySelectedClip(): Clip | null;
     getSelectedClips(): Clip[];
+    canCopySelectedClips(): boolean;
+    canCutSelectedClips(): boolean;
+    canPasteClipboardClips(): boolean;
     canDeleteSelectedClips(): boolean;
     canSplitSelectedClip(): boolean;
     getSelectedClipAudioAction(): SelectedClipAudioAction;
@@ -421,6 +469,12 @@ export declare class TimelineManager {
     getPreviewBackendType(): Exclude<PreviewBackendType, 'auto'>;
     hasAttachedPreview(): boolean;
     getPreviewAspectRatio(): PreviewAspectRatio;
+    getDiagnosticsSnapshot(): DiagnosticSessionSnapshot;
+    subscribeDiagnostics(listener: DiagnosticsListener): () => void;
+    getDiagnosticsLiveSnapshot(recentEventLimit?: number): DiagnosticLiveSnapshot;
+    subscribeDiagnosticsLive(listener: DiagnosticsLiveListener, recentEventLimit?: number): () => void;
+    exportDiagnosticsPackage(): DiagnosticExportPackage;
+    clearDiagnostics(sessionOnly?: boolean): void;
     setPreviewAspectRatio(aspectRatio: {
         width: number;
         height: number;
@@ -434,6 +488,7 @@ export declare class TimelineManager {
     removeSelectedClips(): boolean;
     canSeparateClipAudio(clipId: string): boolean;
     canRestoreClipAudio(clipId: string): boolean;
+    private pausePlaybackForAudioSeparation;
     private resolvePreferredSeparatedAudioTrackId;
     separateClipAudio(clipId: string): Promise<string | null>;
     restoreClipAudio(clipId: string): boolean;
@@ -498,6 +553,7 @@ export declare class TimelineManager {
     private handleBoxSelectEnd;
     private isPointOnClip;
     private getClipsIntersectingBox;
+    private resolveTrackRenderHeight;
     private addClipToTrack;
     private cloneTrackSnapshot;
     private ensureTrackFromHistorySnapshot;

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

@@ -3,6 +3,7 @@ import type { Action, Clip, ClipStateUpdate, Track, TrackRestoreAnchor } from '.
 export declare class TimelineHistoryRecorder {
     private readonly history;
     constructor(history: HistoryManager);
+    createAddClipAction(clip: Clip): Action;
     recordAddClip(clip: Clip): Action;
     createRemoveClipAction(clip: Clip, sourceTrackId?: string | null, sourceTrackSnapshot?: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;
     recordRemoveClip(clip: Clip, sourceTrackId?: string | null, sourceTrackSnapshot?: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null): Action;

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

@@ -1,12 +1,8 @@
+export type { DiagnosticEvent, DiagnosticExportPackage, DiagnosticLiveEvent, DiagnosticLiveSnapshot, DiagnosticsConfig, DiagnosticsLiveListener, DiagnosticSessionSnapshot } from '../../utils/diagnostics/types';
+import type { DiagnosticsConfig } from '../../utils/diagnostics/types';
 export type TrackType = 'video' | 'audio' | 'text';
 export type PlayState = 'playing' | 'paused';
 export type TimeMs = number;
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-export interface LogConfig {
-    enabled?: boolean;
-    level?: LogLevel;
-    moduleLevels?: Record<string, LogLevel>;
-}
 export interface ThumbnailProvider {
     /**
      * 获取片段的封面图片
@@ -26,7 +22,6 @@ export interface TextClipStyle {
     rotation: number;
     strokeColor: string;
     strokeWidth: number;
-    lineHeight: number;
     paddingX: number;
 }
 export declare const DEFAULT_TEXT_CLIP_STYLE: TextClipStyle;
@@ -187,7 +182,7 @@ export type ThemeConfig = Partial<Theme>;
 export type ResolvedTimelineConfig = Omit<TimelineConfig, 'theme'> & {
     theme: Theme;
 };
-export type TimelineKeyboardShortcutAction = 'togglePlay' | 'deleteSelectedClips' | 'toggleSelectedClipsAudio' | 'splitCurrentClip' | 'undo' | 'redo';
+export type TimelineKeyboardShortcutAction = 'togglePlay' | 'deleteSelectedClips' | 'copySelectedClips' | 'cutSelectedClips' | 'pasteClipboardClips' | 'toggleSelectedClipsAudio' | 'splitCurrentClip' | 'undo' | 'redo';
 export type TimelineKeyboardShortcutBindings = Partial<Record<TimelineKeyboardShortcutAction, string | string[]>>;
 export interface TimelineKeyboardShortcutsConfig {
     enabled?: boolean;
@@ -203,7 +198,7 @@ export interface TimelineConfig {
     container?: HTMLElement;
     theme?: ThemeConfig;
     timeScaleHeight?: number;
-    logConfig?: LogConfig;
+    diagnostics?: DiagnosticsConfig;
     speed?: number;
     dragActivationThreshold?: number;
     enableClipSnap?: boolean;
@@ -453,7 +448,7 @@ export interface EventListener {
 export interface TimelineManagerConfig {
     initialDuration?: TimeMs;
     initialZoom?: number;
-    logConfig?: LogConfig;
+    diagnostics?: DiagnosticsConfig;
     thumbnailProvider?: ThumbnailProvider;
 }
 export interface TimelineExportData {