@linker-design-plus/timeline-track 2.0.23 → 2.1.0

package/README.md

@@ -176,6 +176,9 @@ interface ClipConfig {
 - 当前代码路径实际只会创建 `DomPreviewBackend`
 - `previewBackend` 字段被保留，目的是不给后续预览实现扩展制造额外 breaking change
 - 如果你在业务接入层看到 `canvas` / `auto` 配置，请把它当作保留参数，而不是当前版本的有效能力
+- 挂载预览且当前时间命中视频片段时，播放时间由预览视频的真实媒体时钟驱动；媒体 buffering 或 stalled 导致画面没有前进时，播放指针也不会继续超前
+- 多视频叠加播放时，任意一路 active 视频仍在加载或卡顿，预览层会暂停整个 active 播放组，等当前时刻所有视频都 ready 后统一恢复
+- 空白段、纯音频、文本或未挂载预览时，播放仍回退到 `TimelineManager` 的 wall-clock 推进
 
 ## 架构概览
 
@@ -229,6 +232,7 @@ pnpm exec tsc -p tsconfig.json --noEmit
 ## 相关文档
 
 - [docs/interaction-model.md](./docs/interaction-model.md): 指针交互分层和拖拽约束
+- [docs/preview-playback-recovery-flow.md](./docs/preview-playback-recovery-flow.md): 预览媒体时钟驱动播放、buffering 阻塞与恢复续播流程
 - [docs/refactor-roadmap.md](./docs/refactor-roadmap.md): 主线重构归档与后续收敛方向
 - [docs/maintenance-audit.md](./docs/maintenance-audit.md): 本轮仓库审计、验证结果和依赖建议
 - [docs/review-remediation-plan.md](./docs/review-remediation-plan.md): 基于审查结论的修复计划与阶段性落地建议

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

@@ -114,4 +114,6 @@ export declare class ClipConfigPanelRenderer extends LitDomRenderer<ClipConfigPa
     private getTransform;
     private calculatePresetPosition;
     private resizeSvg;
+    private static colorRafId;
+    private static createColorInputHandler;
 }

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

@@ -15,8 +15,6 @@ export interface TimelinePreviewSyncPayload {
     syncRequestId?: number;
 }
 export interface TimelinePreviewBackendCallbacks {
-    onBufferingStateChange?: (isBuffering: boolean) => void;
-    onSourceLoadingChange?: (pending: number) => void;
     onSyncProcessed?: (syncRequestId?: number) => void;
     onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
@@ -26,16 +24,34 @@ export interface TimelinePreviewBackendCallbacks {
     onTextRotationCommit?: (clipId: string, rotation: number) => void;
     onPendingPreviewRetry?: () => void;
     onRuntimeError?: (error: unknown) => void;
+    /** 预览层文字交互（点击字幕或文字变换控件）时若时间线处于播放中，用于请求暂停 */
+    onPauseIfPlaying?: () => void;
+}
+export type PreviewLoadingStatus = 'idle' | 'loading' | 'ready' | 'failed';
+export type PreviewLoadingReason = 'syncing' | 'resolving-source' | 'seeking' | 'media-pending' | 'failed' | null;
+export interface PreviewLoadingState {
+    status: PreviewLoadingStatus;
+    isLoading: boolean;
+    reason: PreviewLoadingReason;
 }
 export interface PreviewPendingState {
-    mode: 'seek' | 'scrub';
+    mode: 'seek' | 'scrub' | 'playback';
     targetTime: TimeMs;
-    loadingPending: number;
-    isBuffering: boolean;
+    loading: PreviewLoadingState;
     errorMessage: string | null;
 }
 export type PreviewRuntimePhase = 'idle' | 'awaiting-sync' | 'awaiting-media' | 'ready' | 'failed';
 export type PreviewSlotPhase = 'idle' | 'binding' | 'primed' | 'active' | 'recovering' | 'failed';
+export type PreviewClockStatus = 'unavailable' | 'priming' | 'running' | 'blocked' | 'failed';
+export type PreviewClockBlockedReason = 'no-video-clock' | 'syncing' | 'resolving-source' | 'seeking' | 'media-pending' | 'media-paused' | 'media-stalled' | 'failed' | null;
+export interface PreviewClockState {
+    status: PreviewClockStatus;
+    timelineTime: TimeMs | null;
+    mediaTime: TimeMs | null;
+    clipId: string | null;
+    trackId: string | null;
+    reason: PreviewClockBlockedReason;
+}
 export interface PreviewSlotDiagnostic {
     trackId: string;
     role: 'current' | 'preload';
@@ -50,8 +66,8 @@ export interface PreviewSlotDiagnostic {
 export interface PreviewRuntimeState {
     syncRequestId?: number;
     phase: PreviewRuntimePhase;
-    loadingCount: number;
-    isBuffering: boolean;
+    loading: PreviewLoadingState;
+    clock?: PreviewClockState;
     errorMessage: string | null;
     slots: PreviewSlotDiagnostic[];
 }

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

@@ -3,16 +3,15 @@ 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;
     private statusElement;
-    private detailElement;
     private actionElement;
     private readonly onRetry;
     constructor(onRetry: () => void);
     mount(container: HTMLElement): void;
     update(viewModel: PreviewPendingOverlayViewModel): void;
+    private resolveLoadingStatusText;
     destroy(): void;
 }

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

@@ -0,0 +1,25 @@
+import type { ActiveClipPlaybackInfo } from '../models/types';
+import { type PreviewSlotRecoveryReason } from './previewSlotPolicy';
+export interface PreviewRecoveryAttemptInput {
+    entry: ActiveClipPlaybackInfo;
+    desiredSource: string;
+    reason: PreviewSlotRecoveryReason;
+    previousRecoveryKey: string | null;
+    previousRetryCount: number;
+    maxImmediateRecoveryRetries: number;
+    recoveryTimeBucketMs: number;
+    isBackgroundPreload: boolean;
+}
+export type PreviewRecoveryAttemptResult = {
+    status: 'continue';
+    recoveryKey: string;
+    retryCount: number;
+} | {
+    status: 'park';
+    message: string;
+    parkReason: 'retries-exhausted';
+} | {
+    status: 'fail';
+    message: string;
+};
+export declare function resolveRecoveryAttempt(input: PreviewRecoveryAttemptInput): PreviewRecoveryAttemptResult;

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

@@ -0,0 +1,18 @@
+import type { ActiveClipPlaybackInfo, PlayState } from '../models/types';
+import type { PreviewSlotTarget } from './previewTrackPlanner';
+export interface PreviewSlotLike {
+    role: 'current' | 'preload';
+    trackId: string;
+    entry: ActiveClipPlaybackInfo | null;
+    requestedPlayState: PlayState;
+}
+export interface TrackSlotPairLike<TSlot extends PreviewSlotLike = PreviewSlotLike> {
+    current: TSlot;
+    preload: TSlot;
+}
+export declare function slotHasEntry(slot: PreviewSlotLike, clipId?: string | null): boolean;
+export declare function shouldSwapTrackSlotsForPlan(slots: TrackSlotPairLike, currentEntry: ActiveClipPlaybackInfo | null): boolean;
+export declare function swapTrackSlotPair<TSlot extends PreviewSlotLike>(slots: TrackSlotPairLike<TSlot>): TrackSlotPairLike<TSlot>;
+export declare function buildSlotKey(slot: Pick<PreviewSlotLike, 'trackId' | 'role'>): string;
+export declare function buildDeferredPreloadTarget(slot: PreviewSlotLike, syncRequestId?: number): PreviewSlotTarget | null;
+export declare function resolveSlotFromKey<TSlot extends PreviewSlotLike>(trackSlots: Map<string, TrackSlotPairLike<TSlot>>, slotKey: string): TSlot | null;

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

@@ -0,0 +1,41 @@
+import type { PlayState } from '../models/types';
+import type { PreviewSlotPhase } from './previewBackend';
+export interface PreviewSlotRecoveryStateLike {
+    isActive: boolean;
+    phase: PreviewSlotPhase;
+    errorMessage: string | null;
+    retryCount: number;
+    recoveryKey: string | null;
+    forceRecover: boolean;
+    isLoading: boolean;
+    isResolvingSource: boolean;
+    isBuffering: boolean;
+    isSeeking: boolean;
+    consecutiveStalledCount: number;
+    expectedEmptiedEvents: number;
+    recoverableEventCount: number;
+    loadStartedSinceRecover: boolean;
+}
+export interface PreviewTrackedCurrentVideoSlotStatus {
+    failed: boolean;
+    resolving: boolean;
+    seeking: boolean;
+    mediaUnready: boolean;
+    ready: boolean;
+}
+export declare function resetSlotRecoveryTrackingState(slot: PreviewSlotRecoveryStateLike, forceRecover?: boolean): void;
+export declare function clearSlotState(slot: PreviewSlotRecoveryStateLike): void;
+export declare function parkPreloadSlotState(slot: PreviewSlotRecoveryStateLike): void;
+export declare function settleResolvedSourceWithoutRecoveryState(slot: Pick<PreviewSlotRecoveryStateLike, 'isActive' | 'phase' | 'isResolvingSource' | 'isLoading' | 'isBuffering' | 'errorMessage'>): void;
+export declare function finalizeAppliedSlotPhase(slot: Pick<PreviewSlotRecoveryStateLike, 'isActive' | 'isLoading' | 'isSeeking' | 'phase'>): void;
+export declare function beginDeferredPreloadState(slot: Pick<PreviewSlotRecoveryStateLike, 'phase' | 'forceRecover' | 'isLoading' | 'isResolvingSource' | 'isSeeking' | 'isBuffering' | 'errorMessage'>, hasAssignedSource: boolean): void;
+export declare function reconcileTrackedCurrentVideoSlotState(slot: PreviewSlotRecoveryStateLike, input: {
+    hasDesiredSource: boolean;
+    sourceMatched: boolean;
+    withinSeekThreshold: boolean;
+    readyState: number;
+    haveCurrentDataState: number;
+}): PreviewTrackedCurrentVideoSlotStatus;
+export declare function failSlotState(slot: Pick<PreviewSlotRecoveryStateLike, 'phase' | 'isLoading' | 'isResolvingSource' | 'isSeeking' | 'isBuffering' | 'errorMessage' | 'forceRecover' | 'expectedEmptiedEvents'>, errorMessage: string): void;
+export declare function beginPreloadPrimingState(slot: Pick<PreviewSlotRecoveryStateLike, 'isActive' | 'isBuffering' | 'isSeeking'>): void;
+export declare function beginSlotRecoveryState(slot: PreviewSlotRecoveryStateLike, playState: PlayState): void;

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

@@ -0,0 +1,59 @@
+import type { ActiveClipPlaybackInfo, PlayState } from '../models/types';
+import type { PreviewSlotPhase } from './previewBackend';
+export type PreviewSlotRecoveryReason = 'reconcile' | 'stalled' | 'abort' | 'emptied' | 'error';
+export interface ResolvedSlotSourceLike {
+    stableSourceUrl: string;
+    url: string;
+    objectUrl: string | null;
+}
+export interface ReusableBoundSlotSourceInput {
+    currentSourceKey: string;
+    nextSourceKey: string;
+    desiredSource: string | null;
+    stableSourceUrl: string | null;
+    objectUrl: string | null;
+}
+export interface PreviewSlotRecoveryNeedInput {
+    desiredSource: string;
+    configuredSource: string | null;
+    assignedSource: string | null;
+    forceRecover: boolean;
+    isActive: boolean;
+    isLoading: boolean;
+    isSeeking: boolean;
+    isBuffering: boolean;
+    phase: PreviewSlotPhase;
+    networkState: number | null;
+    readyState: number | null;
+    networkEmptyState: number;
+    haveCurrentDataState: number;
+}
+export interface PreviewSlotRecoveryNeedResult {
+    needsRecovery: boolean;
+    recoveryReason: string | null;
+    actualSource: string | null;
+    configuredSource: string | null;
+    shouldWarn: boolean;
+}
+export declare function buildRecoveryKey(entry: ActiveClipPlaybackInfo, desiredSource: string, reason: PreviewSlotRecoveryReason, recoveryTimeBucketMs: number): string;
+export declare function getReusableBoundSlotSource(input: ReusableBoundSlotSourceInput): ResolvedSlotSourceLike | null;
+export declare function doesSlotSourceMatchDesired(configuredSource: string | null, assignedSource: string | null, desiredSource: string | null): boolean;
+export declare function evaluateSlotRecoveryNeed(input: PreviewSlotRecoveryNeedInput): PreviewSlotRecoveryNeedResult;
+export declare function getSlotSeekThresholdSeconds(role: 'current' | 'preload', playbackRate: number): number;
+export declare function shouldHardResetRecoveredSource(previousActualSource: string | null, reason: PreviewSlotRecoveryReason, retryCount: number): boolean;
+export declare function buildCurrentSlotTarget(input: {
+    role: 'current' | 'preload';
+    entry: ActiveClipPlaybackInfo;
+    requestedPlayState: PlayState;
+    isActive: boolean;
+    playbackRate: number;
+    syncRequestId?: number;
+}): {
+    role: 'current' | 'preload';
+    entry: ActiveClipPlaybackInfo;
+    playState: PlayState;
+    speed: number;
+    visible: boolean;
+    zIndex: number;
+    syncRequestId?: number;
+};

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

@@ -0,0 +1,24 @@
+import type { ActiveClipPlaybackInfo, TrackType } from '../models/types';
+import type { TimelinePreviewSyncPayload } from './previewBackend';
+export interface PreviewSlotTarget {
+    role: 'current' | 'preload';
+    entry: ActiveClipPlaybackInfo | null;
+    playState: TimelinePreviewSyncPayload['playState'];
+    speed: number;
+    visible: boolean;
+    zIndex: number;
+    syncRequestId?: number;
+}
+export interface PreviewTrackPlan {
+    trackId: string;
+    kind: TrackType;
+    order: number;
+    current: PreviewSlotTarget;
+    preload: PreviewSlotTarget;
+}
+export interface ExistingPreviewTrack {
+    trackId: string;
+    kind: TrackType;
+    order: number;
+}
+export declare function projectPreviewPlan(payload: TimelinePreviewSyncPayload, existingTracks: ExistingPreviewTrack[]): PreviewTrackPlan[];

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

@@ -17,6 +17,8 @@ interface PreviewTransformOverlayCallbacks {
     onFontSizeCommit?: (clipId: string, fontSize: number) => void;
     onRotationChange?: (clipId: string, rotation: number | null) => void;
     onRotationCommit?: (clipId: string, rotation: number) => void;
+    /** 文字片段预览变换框上开始拖拽/缩放/旋转（播放中时应暂停） */
+    onTextTransformInteractionStart?: () => void;
 }
 export declare class PreviewTransformOverlay {
     private frameElement;

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

@@ -4,8 +4,6 @@ import type { ResourceCacheManager } from '../resources/resourceCache';
 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;
@@ -14,6 +12,7 @@ interface TimelinePreviewSessionCallbacks {
     onTextFontSizeCommit?: (clipId: string, fontSize: number) => void;
     onTextRotationCommit?: (clipId: string, rotation: number) => void;
     onPendingPreviewRetry?: () => void;
+    onPauseIfPlaying?: () => void;
 }
 interface TimelinePreviewSessionDependencies {
     createMediaElement?: (kind: TrackType, role: 'current' | 'preload') => HTMLMediaElement;
@@ -53,9 +52,9 @@ export declare class TimelinePreviewSession {
     private readonly textPreviewEntries;
     private audioContext;
     private masterGainNode;
-    private loadingCount;
-    private isBuffering;
-    private bufferingVisibleTimeoutId;
+    private loadingProbeTimeoutId;
+    private clockProbeTimeoutId;
+    private playbackGroupSuspended;
     private lastRuntimeSignature;
     private lastRuntimeState;
     private lastSettledSyncRequestId;
@@ -80,13 +79,14 @@ export declare class TimelinePreviewSession {
     private aspectRatioProbe;
     private aspectRatioProbeSrc;
     private aspectRatioProbeResolveToken;
-    private isAspectRatioProbeLoading;
     private pendingState;
     private activeSyncRequestId;
     private isSyncProjecting;
     private readonly deferredPreloadSlotKeys;
     private deferredPreloadFlushScheduled;
+    private lastSyncedPlayState;
     constructor(callbacks?: TimelinePreviewSessionCallbacks, dependencies?: TimelinePreviewSessionDependencies);
+    private requestPauseIfPlaying;
     private emitDiagnostic;
     private buildSlotTraceData;
     hasPreview(): boolean;
@@ -114,11 +114,13 @@ export declare class TimelinePreviewSession {
     private resolvePlayableSlotSource;
     private emitRuntimeSourceDiagnostic;
     private getReusableResolvedSlotSource;
+    private getReusableBoundSlotSource;
     private slotNeedsRecovery;
     private recoverSlot;
     private finishSlotRecovery;
     private getSlotKey;
     private isActiveCurrentSlot;
+    private isTrackedActiveCurrentVideoSlot;
     private hasBlockingActiveCurrentSlot;
     private shouldDeferPreloadTarget;
     private shouldDeferPreloadRecovery;
@@ -140,6 +142,9 @@ export declare class TimelinePreviewSession {
     private failSlot;
     private configureAudioRouting;
     private syncCurrentSlot;
+    private resetSlotPlaybackProgressProbe;
+    private updateSlotPlaybackProgressState;
+    private maybeResumeRequestedPlayback;
     private preparePreloadSlot;
     private setSlotVisible;
     private getAudioContext;
@@ -153,9 +158,23 @@ export declare class TimelinePreviewSession {
     private tryResolveAutoAspectRatioFromSlot;
     private handleResolvedAutoAspectRatio;
     private refreshRuntimeState;
-    private syncVisibleBufferingState;
-    private clearBufferingVisibleTimeout;
+    private buildPreviewClockState;
+    private buildPreviewClockStateFromSlot;
+    private resolveClockBlockedReason;
+    private getPreviewClockSourceSlot;
+    private syncActivePlaybackGroupSuspension;
+    private getSlotMediaTimeMs;
+    private getSlotTimelineTime;
     private refreshPendingOverlay;
+    private buildPreviewLoadingState;
+    private evaluateTrackedCurrentVideoSlot;
+    private doesSlotSourceMatchDesired;
+    private getSlotSeekThresholdSeconds;
+    private finalizeSourceResolutionResult;
+    private syncLoadingProbe;
+    private syncClockProbe;
+    private clearLoadingProbe;
+    private clearClockProbe;
     private handlePreviewTransformChange;
     private refreshVisualLayout;
     private syncTextPreviewEntries;

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

@@ -1,5 +1,5 @@
 import type { TimeMs } from '../models/types';
-import type { PreviewPendingState, PreviewRuntimeState } from './previewBackend';
+import type { PreviewLoadingState, PreviewPendingState, PreviewRuntimeState } from './previewBackend';
 export interface TimelinePendingPreviewState {
     mode: 'seek' | 'scrub';
     targetTime: TimeMs;
@@ -13,36 +13,26 @@ export interface TimelinePendingPreviewState {
 }
 interface TimelinePreviewStateControllerCallbacks {
     applyPendingState: (state: PreviewPendingState | null) => void;
-    emitBufferingStateChange: (isBuffering: boolean) => void;
-    emitSourceLoadingStateChange: () => void;
+    emitLoadingStateChange: (state: PreviewLoadingState) => void;
     resumePlayback: () => void;
     requestPreviewSync: () => void;
 }
 interface TimelinePreviewStateControllerOptions {
     callbacks: TimelinePreviewStateControllerCallbacks;
-    pendingTimeoutMs?: number;
     failedOverlayDelayMs?: number;
 }
 export declare class TimelinePreviewStateController {
     private readonly callbacks;
-    private readonly pendingTimeoutMs;
     private readonly failedOverlayDelayMs;
-    private _previewSourceLoadingCount;
-    private _previewBuffering;
-    private _previewAwaitingMedia;
+    private _previewLoadingState;
     private _pendingPreviewState;
     private _nextPendingPreviewSyncRequestId;
     constructor(options: TimelinePreviewStateControllerOptions);
-    get previewSourceLoadingCount(): number;
-    set previewSourceLoadingCount(value: number);
-    get previewBuffering(): boolean;
-    set previewBuffering(value: boolean);
+    get previewLoadingState(): PreviewLoadingState;
     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;
@@ -51,7 +41,8 @@ export declare class TimelinePreviewStateController {
     retryPendingPreview(): void;
     clearPendingPreviewState(): void;
     resetPreviewRuntimeState(): void;
-    private ensurePendingPreviewTimeout;
+    private resolvePendingLoadingState;
+    private buildPlaybackLoadingOverlayState;
     private clearPendingPreviewTimeout;
     private scheduleFailedOverlay;
     private clearFailedOverlayTimeout;

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

@@ -58,7 +58,6 @@ export declare class TimelineManager {
     private previewStateController?;
     private previewPlaybackSuspendedByBuffering;
     private previewPlaybackAutoResume;
-    private previewBufferingSuspendTimeoutId;
     private lastSelectedClipId;
     private previewAspectRatio;
     private readonly bodyViewportScrollListener;
@@ -106,10 +105,7 @@ export declare class TimelineManager {
     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 getPreviewLoadingState;
     private get pendingPreviewState();
     private set pendingPreviewState(value);
     get nextPendingPreviewSyncRequestId(): number;
@@ -160,6 +156,8 @@ export declare class TimelineManager {
     private getPlaybackTracksSnapshot;
     private buildPlaybackPlan;
     private hasTimelineVideoClip;
+    private playbackPlanHasActiveVideoClip;
+    private hasActiveTimelineVideoClip;
     private getPreviewAutoAspectRatioClipOrderMap;
     private getNextPreviewAutoAspectRatioOrder;
     private getAutoAspectRatioClip;
@@ -167,11 +165,16 @@ export declare class TimelineManager {
     private buildPreviewSyncSignature;
     private shouldSkipSteadyPlaybackPreviewSync;
     private syncPreviewSession;
+    private resolvePreviewSyncPlayState;
     private syncPreviewPlaybackStateIfNeeded;
+    private shouldUsePreviewClockPlayback;
+    private handlePreviewClockStateChange;
+    private commitPlaybackTimeFromPreviewClock;
+    private syncPreviewAfterPreviewClockCommitIfNeeded;
+    private resumeWallClockPlaybackIfPreviewClockUnavailable;
     private beginPendingPreview;
     updatePendingPreviewState(): void;
     private buildPreviewPendingState;
-    private buildPreviewIndicatorState;
     private clearPendingPreviewState;
     private resetPreviewRuntimeState;
     private destroyPreviewSession;
@@ -218,8 +221,12 @@ export declare class TimelineManager {
     pause(): void;
     togglePlay(): void;
     private animate;
-    private syncPlaybackClockToPreviewBuffering;
-    private clearPreviewBufferingSuspendTimeout;
+    private cancelPlaybackAnimationFrame;
+    private emitPlayStateChangeEvent;
+    private suspendPlaybackForMediaPending;
+    private resumePlaybackAfterMediaPending;
+    private shouldSuspendPreviewPlaybackForLoadingState;
+    private syncPlaybackClockToPreviewLoadingState;
     /** 播放头不得超过全部片段的最大 endTime（与 canPlay / 播放结束对齐）；无片段时不设上限（由别处处理空轨道） */
     private clampPlaybackSeekTime;
     setCurrentTime(time: TimeMs): void;

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

@@ -404,7 +404,7 @@ export interface HistoryState {
     past: Action[];
     future: Action[];
 }
-export type TimelineEvent = 'time_change' | 'play_state_change' | 'clip_added' | 'clip_removed' | 'clip_updated' | 'zoom_change' | 'history_change' | 'track_duration_change' | 'clip_selected' | 'selected_clip_change' | 'speed_change' | 'can_play_change' | 'buffering_state_change' | 'source_loading_change' | 'preview_aspect_ratio_change' | 'draft_loaded' | 'selection_change';
+export type TimelineEvent = 'time_change' | 'play_state_change' | 'clip_added' | 'clip_removed' | 'clip_updated' | 'zoom_change' | 'history_change' | 'track_duration_change' | 'clip_selected' | 'selected_clip_change' | 'speed_change' | 'can_play_change' | 'loading_state_change' | 'preview_aspect_ratio_change' | 'draft_loaded' | 'selection_change';
 export interface TimeChangeData {
     time: TimeMs;
 }
@@ -437,12 +437,12 @@ export interface ClipRemovedEventData {
 export interface CanPlayChangeData {
     canPlay: boolean;
 }
-export interface BufferingStateChangeData {
-    isBuffering: boolean;
-}
-export interface SourceLoadingChangeData {
+export type LoadingStateStatus = 'idle' | 'loading' | 'ready' | 'failed';
+export type LoadingStateReason = 'syncing' | 'resolving-source' | 'seeking' | 'media-pending' | 'failed' | null;
+export interface LoadingStateChangeData {
+    status: LoadingStateStatus;
     isLoading: boolean;
-    pending: number;
+    reason: LoadingStateReason;
 }
 export interface PreviewAspectRatioChangeData {
     aspectRatio: PreviewAspectRatio;