@linker-design-plus/timeline-track 2.1.1 → 2.1.3

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/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/previewBackend.d.ts

@@ -9,6 +9,7 @@ export interface TimelinePreviewSyncPayload {
     autoAspectRatioClip: ActiveClipPlaybackInfo | null;
     currentTime: TimeMs;
     playState: PlayState;
+    requestedPlayState?: PlayState;
     speed: number;
     interactionMode?: 'steady' | 'seek' | 'scrub';
     primarySelectedClipId?: string | null;

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

@@ -11,7 +11,10 @@ export interface ResolvedPlaybackPlan {
     nextClips: ActiveClipPlaybackInfo[];
     firstVideoClip: ActiveClipPlaybackInfo | null;
 }
+export interface ResolvePlaybackPlanOptions {
+    includeEndedClipsAtTime?: boolean;
+}
 export declare class TimelinePlaybackResolver {
     resolveActiveClipsAtTime(tracks: PlaybackTrackSnapshot[], time: TimeMs): ActiveClipPlaybackInfo[];
-    resolvePlaybackPlan(tracks: PlaybackTrackSnapshot[], time: TimeMs): ResolvedPlaybackPlan;
+    resolvePlaybackPlan(tracks: PlaybackTrackSnapshot[], time: TimeMs, options?: ResolvePlaybackPlanOptions): ResolvedPlaybackPlan;
 }

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

@@ -35,6 +35,7 @@ export interface TimelinePreviewSyncPayload {
     autoAspectRatioClip: ActiveClipPlaybackInfo | null;
     currentTime: TimeMs;
     playState: PlayState;
+    requestedPlayState?: PlayState;
     speed: number;
     interactionMode?: 'steady' | 'seek' | 'scrub';
     primarySelectedClipId?: string | null;
@@ -146,6 +147,8 @@ export declare class TimelinePreviewSession {
     private resetSlotPlaybackProgressProbe;
     private updateSlotPlaybackProgressState;
     private maybeResumeRequestedPlayback;
+    private canRuntimeCheckRetryBufferedPlayback;
+    private shouldClearRecoveredBufferingSignal;
     private preparePreloadSlot;
     private setSlotVisible;
     private getAudioContext;
@@ -201,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,66 @@
+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;
+    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,7 +73,10 @@ export declare class TimelineManager {
     private splitOperationDepth;
     private readonly diagnostics;
     private previewRuntimeState;
+    private failedPreviewClipIds?;
     private previewActiveClipIds;
+    private previewClockSeekAlignmentTargetTime;
+    private previewClockSeekAlignmentDeadlineMs;
     private playbackAttemptId;
     private lastPreviewSyncedPlayState;
     private lastPreviewSyncSignature;
@@ -84,6 +86,9 @@ export declare class TimelineManager {
     private voiceLinkedTextRegenerationTimer;
     private pendingVoiceLinkedTextRegeneration;
     private historyRecordingSuppressionDepth;
+    private activeStructureSession;
+    private structureSessionDepth;
+    private preserveEmptyTracksDepth;
     constructor(config?: Partial<TimelineConfig>);
     private createPlaybackAttemptId;
     private refreshPlaybackAttempt;
@@ -119,7 +124,10 @@ 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;
@@ -156,6 +164,7 @@ export declare class TimelineManager {
     private getTracksSortedByOrder;
     private getPlaybackTracksSnapshot;
     private buildPlaybackPlan;
+    private buildPreviewPlaybackPlan;
     private playbackPlanHasActiveVideoClip;
     private hasActiveTimelineVideoClip;
     private getPreviewAutoAspectRatioClipOrderMap;
@@ -166,11 +175,13 @@ export declare class TimelineManager {
     private shouldSkipSteadyPlaybackPreviewSync;
     private syncPreviewSession;
     private resolvePreviewSyncPlayState;
+    private resolvePreviewRequestedPlayState;
     private syncPreviewPlaybackStateIfNeeded;
     private shouldUsePreviewClockPlayback;
     private handlePreviewClockStateChange;
     private isPreviewClockForCurrentActiveClip;
     private shouldCommitUnavailablePreviewClock;
+    private shouldIgnorePreviewClockUntilSeekTargetAligned;
     private commitPlaybackTimeFromPreviewClock;
     private syncPreviewAfterPreviewClockCommitIfNeeded;
     private resumeWallClockPlaybackIfPreviewClockUnavailable;
@@ -183,7 +194,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[];
@@ -193,6 +204,7 @@ export declare class TimelineManager {
     private calculateTrackY;
     private calculateTotalHeight;
     private updateAllTrackPositions;
+    private removeEmptyTracksFromStructure;
     private cleanupEmptyTracks;
     private clearAllTrackDropPreviews;
     private showClipDropPreview;
@@ -315,6 +327,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;
@@ -592,7 +608,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, 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,7 +74,7 @@ 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;
     createCompoundAction(actions: Action[], label?: string): CompoundAction;

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

@@ -13,6 +13,7 @@ export interface TimelineHistoryExecutionTarget {
     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 +23,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,9 +9,9 @@ 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;

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;
@@ -297,6 +302,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 +322,9 @@ export interface SplitClipAction {
         originalClip: Clip;
         clip1: Clip;
         clip2: Clip;
+        sourceTrackId?: string | null;
+        sourceTrackSnapshot?: Track | null;
+        sourceTrackRestoreAnchor?: TrackRestoreAnchor | null;
     };
     timestamp: number;
 }
@@ -367,6 +380,8 @@ export interface MoveClipBetweenTracksAction {
         clipAfter: Clip;
         sourceTrackSnapshot: Track | null;
         targetTrackSnapshot: Track | null;
+        sourceTrackRestoreAnchor?: TrackRestoreAnchor | null;
+        targetTrackRestoreAnchor?: TrackRestoreAnchor | null;
     };
     timestamp: 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/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[];