@linker-design-plus/timeline-track 2.1.5 → 2.2.0

package/README.md

@@ -146,5 +146,5 @@ pnpm exec tsc -p tsconfig.json --noEmit
 - [docs/implementation-notes.md](./docs/implementation-notes.md): selection、preview、resource cache、draft 的实现笔记
 - [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/preview-clock-flow.md](./docs/preview-clock-flow.md): 预览媒体时钟驱动播放与 buffering 阻塞流程
 - [docs/testing-harness-roadmap.md](./docs/testing-harness-roadmap.md): Harness Engineering 导向的测试与诊断重构方案

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

@@ -1,6 +1,6 @@
 import type { TimelinePreviewBackend, TimelinePreviewBackendOptions } from './previewBackend';
-import { TimelinePreviewSession } from './timelinePreviewSession';
-export declare class DomPreviewBackend extends TimelinePreviewSession implements TimelinePreviewBackend {
+import { PreviewEngine } from '../preview/previewEngine';
+export declare class DomPreviewBackend extends PreviewEngine implements TimelinePreviewBackend {
     constructor(options?: TimelinePreviewBackendOptions);
     destroy(): void;
 }

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

@@ -7,7 +7,8 @@ export { PreviewClockController } from './previewClockController';
 export * from './timelineDurationController';
 export { TimelineEventDispatcher } from './timelineEventDispatcher';
 export { TimelinePlaybackResolver } from './timelinePlaybackResolver';
-export { TimelinePreviewSession } from './timelinePreviewSession';
+export { PreviewEngine } from '../preview/previewEngine';
+export { PreviewEngine as TimelinePreviewSession } from '../preview/previewEngine';
 export { TimelinePreviewRuntimeController } from './timelinePreviewRuntimeController';
 export { TimelinePreviewStateController, type TimelinePendingPreviewState } from './timelinePreviewStateController';
 export { TimelineKeyboardShortcutsController, type TimelineKeyboardShortcutsControllerCallbacks } from './timelineKeyboardShortcutsController';

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

@@ -23,6 +23,10 @@ export interface TimelinePreviewBackendCallbacks {
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onTextFontSizeCommit?: (clipId: string, fontSize: number) => void;
     onTextRotationCommit?: (clipId: string, rotation: number) => void;
+    onTextLayoutCommit?: (clipId: string, layout: {
+        layoutWidth: number;
+        layoutHeight: number;
+    }) => void;
     onPendingPreviewRetry?: () => void;
     onRuntimeError?: (error: unknown) => void;
     /** 预览层文字交互（点击字幕或文字变换控件）时若时间线处于播放中，用于请求暂停 */

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

@@ -16,10 +16,16 @@ export interface PreviewMediaSize {
     height: number;
 }
 export declare const DEFAULT_CLIP_VISUAL_TRANSFORM: ClipVisualTransform;
+/** 文本预览底边与画幅底边的默认间距（相对画幅高度）。 */
+export declare const TEXT_CLIP_BOTTOM_MARGIN_RATIO = 0.06;
+/** 新建文本时的中心锚点默认位（基于 720 高 baseline 与估算框高）。 */
+export declare const DEFAULT_TEXT_CLIP_VISUAL_TRANSFORM: ClipVisualTransform;
 export declare const MIN_CLIP_VISUAL_SCALE = 0.1;
 export declare const MAX_CLIP_VISUAL_SCALE = 8;
 export declare function clampClipVisualScale(scale: number): number;
 export declare function resolveClipVisualTransform(transform?: Partial<ClipVisualTransform> | null): ClipVisualTransform;
+/** 文本位移使用框中心锚点；预览布局不使用 scale（固定为 1）。 */
+export declare function resolveTextClipVisualTransform(transform?: Partial<ClipVisualTransform> | null): ClipVisualTransform;
 export declare function areClipVisualTransformsEqual(left?: Partial<ClipVisualTransform> | null, right?: Partial<ClipVisualTransform> | null, epsilon?: number): boolean;
 export declare function calculateContainRect(frame: PreviewFrameSize, media: PreviewMediaSize): PreviewRect;
 export declare function calculatePreviewDisplayRect(frame: PreviewFrameSize, media: PreviewMediaSize, transform?: Partial<ClipVisualTransform> | null): PreviewRect;

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

@@ -9,6 +9,11 @@ export interface PreviewTransformOverlayState {
     clipType?: 'text' | 'video';
     currentFontSize?: number;
     currentRotation?: number;
+    currentLayoutWidth?: number;
+    currentLayoutHeight?: number;
+    /** 文本选中时把手柄挂到此元素，与文案共用一个框 */
+    textHostElement?: HTMLElement | null;
+    baselineScale?: number;
 }
 interface PreviewTransformOverlayCallbacks {
     onPreviewTransformChange?: (clipId: string, transform: ClipVisualTransform | null) => void;
@@ -17,6 +22,14 @@ interface PreviewTransformOverlayCallbacks {
     onFontSizeCommit?: (clipId: string, fontSize: number) => void;
     onRotationChange?: (clipId: string, rotation: number | null) => void;
     onRotationCommit?: (clipId: string, rotation: number) => void;
+    onTextLayoutChange?: (clipId: string, layout: {
+        layoutWidth: number;
+        layoutHeight: number;
+    } | null) => void;
+    onTextLayoutCommit?: (clipId: string, layout: {
+        layoutWidth: number;
+        layoutHeight: number;
+    }) => void;
     /** 文字片段预览变换框上开始拖拽/缩放/旋转（播放中时应暂停） */
     onTextTransformInteractionStart?: () => void;
 }
@@ -30,6 +43,7 @@ export declare class PreviewTransformOverlay {
     private readonly handlePointerDownHandlers;
     private state;
     private interaction;
+    private textHostElement;
     private readonly callbacks;
     private readonly boundPointerMove;
     private readonly boundPointerUp;
@@ -39,6 +53,8 @@ export declare class PreviewTransformOverlay {
     attach(frameElement: HTMLElement): void;
     detach(): void;
     sync(state: PreviewTransformOverlayState | null): void;
+    /** 在已选中的文本框上按下时启动移动（与手柄同属一个框） */
+    handleTextHostPointerDown(event: Event): void;
     private createRotateHandle;
     private getRotateHandlePointerDown;
     private createHandle;
@@ -49,6 +65,11 @@ export declare class PreviewTransformOverlay {
     private handleDocumentPointerMove;
     private finishInteraction;
     private render;
+    private renderTextHostHandles;
+    private renderOverlayBox;
+    private renderRotateHandle;
+    private setTextHost;
+    private mountHandlesOn;
     private positionHandle;
     private toLocalPoint;
     private getFrameBounds;

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

@@ -640,6 +640,7 @@ export declare class TimelineManager {
     private resolveSelectedClipSnapshot;
     private resolveSelectionChangeData;
     private commitPreviewVisualTransform;
+    private commitPreviewTextLayout;
     private commitPreviewTextFontSize;
     private commitPreviewTextRotation;
     clearAllTracksAndClips(): void;

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

@@ -23,6 +23,12 @@ export interface TextClipStyle {
     strokeColor: string;
     strokeWidth: number;
     paddingX: number;
+    /** 文本区域宽度（baseline 画布像素）。 */
+    layoutWidth?: number;
+    /** 文本区域高度（baseline 画布像素）；未设时由内容估算。 */
+    layoutHeight?: number;
+    /** 1 = visualTransform 为框中心锚点。 */
+    anchorVersion?: number;
 }
 export declare const DEFAULT_TEXT_CLIP_STYLE: TextClipStyle;
 export declare function resolveTextClipStyle(style?: Partial<TextClipStyle> | null): TextClipStyle;

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

@@ -0,0 +1,2 @@
+export { PreviewEngine, type PreviewEngineDependencies } from './previewEngine';
+export { PreviewSourceService } from './previewSourceService';

package/dist/core/preview/mediaHelpers.d.ts

@@ -0,0 +1,24 @@
+import type { ActiveClipPlaybackInfo } from '../models/types';
+import type { DiagnosticMediaState } from '../../utils/diagnostics';
+export declare const HAVE_CURRENT_DATA_STATE = 2;
+export declare const HAVE_FUTURE_DATA_STATE = 3;
+export declare const STEADY_PLAYBACK_CURRENT_SLOT_SEEK_THRESHOLD_SECONDS = 0.5;
+export declare const CLOCK_SOURCE_TARGET_ALIGNMENT_THRESHOLD_MS = 750;
+export declare const SOURCE_RESOLVE_TIMEOUT_MS = 15000;
+export declare const PREVIEW_SLOT_FAILURE_MESSAGE = "\u5A92\u4F53\u4E22\u5931";
+export declare function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T>;
+export declare function getAssignedSrc(element: HTMLMediaElement): string;
+export declare function getConfiguredSrc(element: HTMLMediaElement): string;
+export declare function getMediaSourceDebugState(element: HTMLMediaElement, desiredSource?: string | null): Record<string, unknown>;
+export declare function isVideoMediaElement(element: HTMLMediaElement): element is HTMLVideoElement;
+export declare function safeLoad(element: HTMLMediaElement): void;
+export declare function safePause(element: HTMLMediaElement): void;
+export declare function safePlay(element: HTMLMediaElement): void;
+export declare function safeSetCurrentTime(element: HTMLMediaElement, nextTimeSeconds: number): void;
+export declare function getClipStyleDimension(entry: ActiveClipPlaybackInfo | null, widthKey: 'sys_width' | 'sys_height'): number | null;
+export declare function parsePxValue(value?: string): number;
+export declare function getBufferedEnd(element: HTMLMediaElement): number | null;
+export declare function getMediaDebugState(element: HTMLMediaElement): DiagnosticMediaState;
+export declare function doesSlotSourceMatchDesired(configuredSource: string | null, assignedSource: string | null, desiredSource: string | null): boolean;
+export declare function getSlotSeekThresholdSeconds(role: 'current' | 'preload', playbackRate: number): number;
+export declare function buildPreviewSourceCacheKey(clip: ActiveClipPlaybackInfo['clip']): string;

package/dist/core/preview/previewClockAggregator.d.ts

@@ -0,0 +1,19 @@
+import type { TimeMs } from '../models/types';
+import type { PreviewClockState, PreviewLoadingState } from '../controllers/previewBackend';
+import type { PlaybackSlotState } from './types';
+export declare class PreviewClockAggregator {
+    private pendingClockAlignmentTargetTime;
+    updateAlignmentTarget(hasActiveVisualVideo: boolean, interactionMode: 'steady' | 'seek' | 'scrub' | undefined, currentTime: TimeMs): void;
+    buildClockState(loading: PreviewLoadingState, slots: PlaybackSlotState[], playbackGroupSuspended: boolean): PreviewClockState;
+    private getClockSourceSlot;
+    private buildCandidate;
+    private compareCandidates;
+    private isCandidateAligned;
+    private getAlignmentThresholdMs;
+    private isMediaTimeAligned;
+    private isTimelineAligned;
+    private getMediaTimeMs;
+    private getTimelineTime;
+    private buildFromSlot;
+    private resolveBlockedReason;
+}

package/dist/core/preview/previewDomCompositor.d.ts

@@ -0,0 +1,47 @@
+import type { ActiveClipPlaybackInfo, PreviewAspectRatio } from '../models/types';
+import { resolveClipVisualTransform, type PreviewFrameSize } from '../controllers/previewTransformMath';
+import { PreviewTransformOverlay, type PreviewTransformOverlayState } from '../controllers/previewTransformOverlay';
+import { type TextLayoutStyleOverride } from './textPreviewLayout';
+import type { PreviewPlaybackSlot } from './previewPlaybackSlot';
+export declare class PreviewDomCompositor {
+    private container;
+    private rootElement;
+    private frameElement;
+    private resizeObserver;
+    private requestedAspectRatio;
+    private resolvedAutoAspectRatio;
+    readonly transformOverlay: PreviewTransformOverlay;
+    constructor(transformOverlay: PreviewTransformOverlay);
+    attach(container: HTMLElement, options: {
+        rootClassName?: string;
+        frameClassName?: string;
+    }): void;
+    detach(): void;
+    getFrameElement(): HTMLDivElement | null;
+    getRootElement(): HTMLDivElement | null;
+    applyAspectRatio(aspectRatio: PreviewAspectRatio): void;
+    getAspectRatio(): PreviewAspectRatio;
+    resolveAutoAspectRatio(width: number, height: number, onChange?: (ratio: PreviewAspectRatio) => void): void;
+    tryResolveAutoAspectRatioFromSlot(slot: PreviewPlaybackSlot, onChange?: (ratio: PreviewAspectRatio) => void): void;
+    refreshSlotVisual(slot: PreviewPlaybackSlot): void;
+    buildSelectedOverlayState(primarySelectedClipId: string | null, slots: PreviewPlaybackSlot[], textOverlay: {
+        getEntry: (clipId: string) => {
+            entry: ActiveClipPlaybackInfo;
+            element: HTMLElement;
+        } | undefined;
+        getTransientFontSize: (clipId: string) => number | null;
+        getTransientRotation: (clipId: string) => number | null;
+        getTextLayoutOverride?: (clipId: string) => TextLayoutStyleOverride | null;
+    }, getEffectiveVisualTransform: (entry: ActiveClipPlaybackInfo) => ReturnType<typeof resolveClipVisualTransform>): PreviewTransformOverlayState | null;
+    getFrameSize(): PreviewFrameSize;
+    getTextBaselineMetrics(frameSize: PreviewFrameSize): {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    moveTransform(startTransform: ReturnType<typeof resolveClipVisualTransform>, deltaX: number, deltaY: number): ReturnType<typeof resolveClipVisualTransform>;
+    transformsEqual(left: ReturnType<typeof resolveClipVisualTransform>, right: ReturnType<typeof resolveClipVisualTransform>): boolean;
+    private updateFrameLayout;
+    private getMediaSize;
+    private syncFailureVisual;
+}

package/dist/core/preview/previewEngine.d.ts

@@ -0,0 +1,86 @@
+import type { ActiveClipPlaybackInfo, PreviewAspectRatio, PreviewSourceResolver, TextPreviewFontConfig, TrackType } from '../models/types';
+import type { PreviewPendingState, PreviewRuntimeState, TimelinePreviewSyncPayload } from '../controllers/previewBackend';
+import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
+import type { ResourceCacheManager } from '../resources/resourceCache';
+import { type DiagnosticEmitInput, type DiagnosticsCenter } from '../../utils/diagnostics';
+import { PreviewPlaybackSlot } from './previewPlaybackSlot';
+import type { PreviewEngineCallbacks } from './types';
+export interface PreviewEngineDependencies {
+    createMediaElement?: (kind: TrackType, role: 'current' | 'preload') => HTMLMediaElement;
+    createAspectRatioProbe?: () => HTMLVideoElement;
+    createAudioContext?: () => AudioContext | null;
+    diagnostics?: DiagnosticsCenter;
+    getDiagnosticsContext?: () => Partial<DiagnosticEmitInput>;
+    rootClassName?: string;
+    frameClassName?: string;
+    slotClassNamePrefix?: string;
+    previewSourceResolver?: PreviewSourceResolver;
+    textPreviewFont?: TextPreviewFontConfig | null;
+    sourceMediaRegistry?: SourceMediaRegistry;
+    resourceCacheManager?: ResourceCacheManager | null;
+}
+export declare class PreviewEngine {
+    private container;
+    private pendingOverlayElement;
+    private readonly pendingOverlayRenderer;
+    private readonly compositor;
+    private readonly textLayer;
+    private readonly sourceService;
+    private readonly syncCoordinator;
+    private readonly clockAggregator;
+    private readonly runtimePublisher;
+    private readonly trackSlots;
+    private readonly callbacks;
+    private readonly dependencies;
+    private audioContext;
+    private masterGainNode;
+    private loadingProbeTimeoutId;
+    private clockProbeTimeoutId;
+    private playbackGroupSuspended;
+    private primarySelectedClipId;
+    private transientVisualTransform;
+    private transientFontSize;
+    private transientTextLayout;
+    private transientRotation;
+    private pendingState;
+    private activeSyncRequestId;
+    private isSyncProjecting;
+    private lastSyncedPlayState;
+    private aspectRatioProbe;
+    private aspectRatioProbeSrc;
+    constructor(callbacks?: PreviewEngineCallbacks, dependencies?: PreviewEngineDependencies);
+    hasPreview(): boolean;
+    attach(container: HTMLElement): void;
+    detach(): void;
+    sync(payload: TimelinePreviewSyncPayload): void;
+    applyAspectRatio(aspectRatio: PreviewAspectRatio): void;
+    getAspectRatio(): PreviewAspectRatio;
+    setPendingState(state: PreviewPendingState | null): void;
+    failSlot(slot: PreviewPlaybackSlot, _entry: ActiveClipPlaybackInfo, message: string): void;
+    get lastRuntimeState(): PreviewRuntimeState;
+    refreshRuntimeState(): void;
+    private applyTrackPlan;
+    private getTrackSlots;
+    private collectSlots;
+    private buildLoadingState;
+    private buildTrackedSummary;
+    private syncPlaybackGroupSuspension;
+    private configureAudioRouting;
+    private getAudioContext;
+    private getMasterGainNode;
+    private bootstrapLayoutAspectRatioFromClipStyle;
+    private maybeResolveAutoAspectRatio;
+    private getAspectRatioProbe;
+    private getEffectiveVisualTransform;
+    private getTextLayoutOverride;
+    private getTextLayoutOptions;
+    private handlePreviewTransformChange;
+    refreshVisualLayout(): void;
+    private refreshPendingOverlay;
+    private syncLoadingProbe;
+    private syncClockProbe;
+    private clearProbes;
+    private clearLoadingProbe;
+    private clearClockProbe;
+    private emitDiagnostic;
+}

package/dist/core/preview/previewPlaybackSlot.d.ts

@@ -0,0 +1,59 @@
+import type { ActiveClipPlaybackInfo, PlayState, TrackType } from '../models/types';
+import type { PreviewSlotPhase } from '../controllers/previewBackend';
+import type { PlaybackSlotState, ResolvedSlotSource, TrackedVideoSlotStatus } from './types';
+export interface PreviewPlaybackSlotOptions {
+    createMediaElement?: (kind: TrackType, role: 'current' | 'preload') => HTMLMediaElement;
+    slotClassNamePrefix?: string;
+    onStateChange?: () => void;
+    onMediaError?: (slot: PreviewPlaybackSlot, message: string) => void;
+    onDiagnostic?: (eventName: string, slot: PreviewPlaybackSlot, extra?: Record<string, unknown>) => void;
+}
+export declare class PreviewPlaybackSlot implements PlaybackSlotState {
+    trackId: string;
+    kind: TrackType;
+    role: 'current' | 'preload';
+    element: HTMLMediaElement;
+    wrapper: HTMLDivElement | null;
+    failureOverlay: HTMLDivElement | null;
+    failureLabel: HTMLDivElement | null;
+    entry: ActiveClipPlaybackInfo | null;
+    stableSourceUrl: string | null;
+    boundStableKey: string | null;
+    desiredSource: string | null;
+    objectUrl: string | null;
+    requestedPlayState: PlayState;
+    isActive: boolean;
+    isLoading: boolean;
+    isResolvingSource: boolean;
+    isBuffering: boolean;
+    isSeeking: boolean;
+    phase: PreviewSlotPhase;
+    errorMessage: string | null;
+    hasReadyEventSinceSourceChange: boolean;
+    pendingClockAlignmentMediaTime: number | null;
+    sourceGen: number;
+    sourceNode: MediaElementAudioSourceNode | null;
+    gainNode: GainNode | null;
+    audioRoutingFailed: boolean;
+    cleanup: Array<() => void>;
+    private lastPlaybackResumeAttemptAtMs;
+    private readonly options;
+    constructor(trackId: string, kind: TrackType, role: 'current' | 'preload', options?: PreviewPlaybackSlotOptions);
+    mountVideoTo(frame: HTMLElement): void;
+    mountAudioTo(root: HTMLElement): void;
+    clear(): void;
+    fail(message: string): void;
+    clearFailureIfClipChanged(): void;
+    assignSource(resolved: ResolvedSlotSource, stableKey: string): boolean;
+    applyPlayback(entry: ActiveClipPlaybackInfo, playState: PlayState, speed: number, visible: boolean, zIndex: number): void;
+    sourceMatchesDesired(): boolean;
+    maybeResumePlayback(reason: 'canplay' | 'seeked' | 'runtime-check'): void;
+    destroy(releaseObjectUrl: (url: string | null) => void): void;
+    private syncCurrentPlayback;
+    private preparePreload;
+    private setVisible;
+    private createMediaElement;
+    private setupWrapper;
+    private bindMediaEvents;
+}
+export declare function evaluateTrackedVideoSlot(slot: PlaybackSlotState, isTracked: boolean): TrackedVideoSlotStatus;

package/dist/core/preview/previewPrefetchPool.d.ts

@@ -0,0 +1,11 @@
+import type { ActiveClipPlaybackInfo } from '../models/types';
+import type { PreviewSlotTarget } from '../controllers/previewTrackPlanner';
+import type { PreviewPlaybackSlot } from './previewPlaybackSlot';
+/**
+ * Prefetch pool schedules warm loading on preload slots without affecting
+ * playback failure state or preview clock aggregation.
+ */
+export declare class PreviewPrefetchPool {
+    shouldSchedule(target: PreviewSlotTarget): boolean;
+    onPrefetchFailure(slot: PreviewPlaybackSlot, _entry: ActiveClipPlaybackInfo, reason: string): void;
+}

package/dist/core/preview/previewRuntimePublisher.d.ts

@@ -0,0 +1,20 @@
+import type { PreviewRuntimeState } from '../controllers/previewBackend';
+import type { PreviewPlaybackSlot } from './previewPlaybackSlot';
+import type { TrackedVideoSlotStatus } from './types';
+export interface RuntimePublisherInput {
+    activeSyncRequestId?: number;
+    isSyncProjecting: boolean;
+    slots: PreviewPlaybackSlot[];
+    evaluateTracked: (slot: PreviewPlaybackSlot) => TrackedVideoSlotStatus;
+    isTrackedVideo: (slot: PreviewPlaybackSlot) => boolean;
+    clock: PreviewRuntimeState['clock'];
+}
+export declare class PreviewRuntimePublisher {
+    private lastSignature;
+    private lastState;
+    private lastSettledSyncRequestId;
+    getLastState(): PreviewRuntimeState;
+    publish(input: RuntimePublisherInput, onChange: (state: PreviewRuntimeState) => void, onSyncProcessed?: (syncRequestId?: number) => void): PreviewRuntimeState;
+    reset(): void;
+    private buildLoadingState;
+}

package/dist/core/preview/previewSourceService.d.ts

@@ -0,0 +1,25 @@
+import type { ActiveClipPlaybackInfo, PreviewSourceResolver } from '../models/types';
+import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
+import type { ResourceCacheManager } from '../resources/resourceCache';
+import type { ResolvedSlotSource } from './types';
+export interface PreviewSourceServiceDependencies {
+    previewSourceResolver?: PreviewSourceResolver;
+    sourceMediaRegistry?: SourceMediaRegistry;
+    resourceCacheManager?: ResourceCacheManager | null;
+    onDiagnostic?: (eventName: string, data: Record<string, unknown>) => void;
+}
+export declare class PreviewSourceService {
+    private readonly dependencies;
+    private readonly pendingRuntime;
+    constructor(dependencies?: PreviewSourceServiceDependencies);
+    resolve(entry: ActiveClipPlaybackInfo, options: {
+        sourceGen: number;
+        getCurrentSourceGen: () => number;
+        reuse?: ResolvedSlotSource | null;
+    }): Promise<ResolvedSlotSource | null> | ResolvedSlotSource | null;
+    getReusableSource(boundStableKey: string | null, stableSourceUrl: string | null, desiredSource: string | null, objectUrl: string | null, entry: ActiveClipPlaybackInfo): ResolvedSlotSource | null;
+    revokeObjectUrl(objectUrl: string | null | undefined): void;
+    private resolvePlayable;
+    private normalizeCachedResult;
+    private emit;
+}

package/dist/core/preview/previewSyncCoordinator.d.ts

@@ -0,0 +1,34 @@
+import type { ActiveClipPlaybackInfo, TrackType } from '../models/types';
+import type { PreviewSlotTarget, PreviewTrackPlan } from '../controllers/previewTrackPlanner';
+import { evaluateTrackedVideoSlot, PreviewPlaybackSlot } from './previewPlaybackSlot';
+import type { PreviewSourceService } from './previewSourceService';
+export interface TrackSlotPair {
+    current: PreviewPlaybackSlot;
+    preload: PreviewPlaybackSlot;
+}
+export interface PreviewSyncCoordinatorOptions {
+    sourceService: PreviewSourceService;
+    getTrackSlots: (trackId: string, kind: TrackType) => TrackSlotPair;
+    onAsyncWorkStarted: () => void;
+    onAsyncWorkFinished: () => void;
+    onStateChange: () => void;
+    releaseObjectUrl: (url: string | null) => void;
+    rememberObjectUrl: (slot: PreviewPlaybackSlot, url: string | null) => void;
+    configureAudio: (slot: PreviewPlaybackSlot, entry: ActiveClipPlaybackInfo) => void;
+    syncClockAlignment: (slot: PreviewPlaybackSlot, target: PreviewSlotTarget, clipChanged: boolean) => void;
+    isCurrentTarget: (slot: PreviewPlaybackSlot, entry: ActiveClipPlaybackInfo, stableKey: string) => boolean;
+}
+export declare class PreviewSyncCoordinator {
+    private syncGen;
+    private pendingAsyncCount;
+    private readonly options;
+    constructor(options: PreviewSyncCoordinatorOptions);
+    get isProjecting(): boolean;
+    applyTrackPlan(plan: PreviewTrackPlan): void | Promise<void>;
+    bumpSyncGeneration(): number;
+    private applySlotTarget;
+    private beginAsyncWork;
+    private endAsyncWork;
+}
+export declare function isTrackedActiveCurrentVideoSlot(slot: PreviewPlaybackSlot): boolean;
+export declare function evaluateSlotForRuntime(slot: PreviewPlaybackSlot): ReturnType<typeof evaluateTrackedVideoSlot>;

package/dist/core/preview/previewTextLayer.d.ts

@@ -0,0 +1,46 @@
+import type { ActiveClipPlaybackInfo, ClipVisualTransform, TextPreviewFontConfig } from '../models/types';
+import type { PreviewDomCompositor } from './previewDomCompositor';
+import { type TextLayoutStyleOverride, type TextPreviewBoxLayout } from './textPreviewLayout';
+export type { TextLayoutStyleOverride } from './textPreviewLayout';
+export { resolveTextEntryMaxWidthPx } from './textPreviewLayout';
+export interface RefreshTextLayoutOptions {
+    getStyleOverride?: (entry: ActiveClipPlaybackInfo) => TextLayoutStyleOverride | null;
+    resolveVisualTransform?: (entry: ActiveClipPlaybackInfo) => ClipVisualTransform;
+}
+/** 统一文本框 DOM 层：布局仅来自 computeTextPreviewBox。 */
+export declare class PreviewTextLayer {
+    private overlayRoot;
+    private readonly entries;
+    private fontStyleElement;
+    private fontSignature;
+    private fontLoadState;
+    private fontLoadToken;
+    private primarySelectedClipId;
+    private textPreviewFont;
+    private readonly compositor;
+    private readonly callbacks;
+    constructor(compositor: PreviewDomCompositor, callbacks: PreviewTextLayer['callbacks']);
+    mount(frameElement: HTMLDivElement): HTMLDivElement;
+    destroy(): void;
+    setPrimarySelectedClipId(clipId: string | null): void;
+    setTextPreviewFont(config: TextPreviewFontConfig | null): void;
+    syncEntries(activeEntries: ActiveClipPlaybackInfo[], resolveVisualTransform: (entry: ActiveClipPlaybackInfo) => ClipVisualTransform, layoutOptions?: RefreshTextLayoutOptions): void;
+    refreshLayout(resolveVisualTransform: (entry: ActiveClipPlaybackInfo) => ClipVisualTransform, options?: RefreshTextLayoutOptions): void;
+    getEntry(clipId: string): {
+        entry: ActiveClipPlaybackInfo;
+        element: HTMLDivElement;
+        layout: TextPreviewBoxLayout | null;
+    } | undefined;
+    getLayout(clipId: string): TextPreviewBoxLayout | null;
+    private resolveBaselineScale;
+    private reapplyAllContent;
+    private applyBoxLayout;
+    private applyContent;
+    private getFontFamily;
+    private ensureFontReady;
+    private resetFontState;
+    private clearEntries;
+    private removeEntry;
+    private createPointerDownHandler;
+    private refreshInteractionState;
+}

package/dist/core/preview/textPreviewLayout.d.ts

@@ -0,0 +1,55 @@
+import type { ClipVisualTransform, TextClipStyle } from '../models/types';
+import { type PreviewFrameSize, type PreviewRect } from '../controllers/previewTransformMath';
+/** 文本 visualTransform 使用框中心锚点。 */
+export declare const TEXT_CLIP_ANCHOR_VERSION_CENTER = 1;
+export interface TextLayoutStyleOverride {
+    fontSize?: number;
+    rotation?: number;
+    layoutWidth?: number;
+    layoutHeight?: number;
+}
+export interface TextPreviewBoxLayout {
+    layoutWidth: number;
+    layoutHeight: number;
+    frameRect: PreviewRect;
+    visualTransform: ClipVisualTransform;
+}
+export interface ComputeTextPreviewBoxInput {
+    frameSize: PreviewFrameSize;
+    baselineScale: number;
+    visualTransform: ClipVisualTransform;
+    textStyle: TextClipStyle;
+    contentText: string;
+    styleOverride?: TextLayoutStyleOverride | null;
+}
+/** 将 baseline 画布上的字号/内边距/描边换算为当前预览帧像素（短边 720 等比缩放）。 */
+export declare function scaleTextMetricsToFrame(fontSize: number, paddingX: number, strokeWidth: number, baselineScale: number): {
+    fontSize: number;
+    paddingX: number;
+    strokeWidth: number;
+};
+/** 布局换行宽度 fallback（仅 migrate / 无 layoutWidth 时）。 */
+export declare function resolveTextEntryMaxWidthPx(frameWidth: number, baselineScale: number, paddingX: number, anchorX?: number): number;
+export declare function estimateTextLayoutHeightBaseline(fontSize: number, contentText: string, layoutWidthBaseline: number, paddingX: number): number;
+export declare function resolveDefaultTextCenterTransform(frameSize: PreviewFrameSize, layoutHeightBaseline: number, baselineScale: number): ClipVisualTransform;
+export declare function resolveDefaultTextCenterTransformForBaselineFrame(baselineFrameHeight: number, layoutHeightBaseline?: number): ClipVisualTransform;
+export declare function migrateBottomAnchorTransformToCenter(transform: ClipVisualTransform, frameSize: PreviewFrameSize, displayHeightPx: number): ClipVisualTransform;
+export declare function resolveTextVisualTransformForPreview(transform: Partial<ClipVisualTransform> | null | undefined, textStyle: TextClipStyle, frameSize: PreviewFrameSize, displayHeightPx: number): ClipVisualTransform;
+export declare function resolveTextLayoutDimensions(input: ComputeTextPreviewBoxInput): {
+    layoutWidth: number;
+    layoutHeight: number;
+};
+export declare function computeTextPreviewBox(input: ComputeTextPreviewBoxInput): TextPreviewBoxLayout;
+/** 按指针相对框中心的轴向距离独立缩放宽高（不保持宽高比）。 */
+export declare function scaleTextLayoutFromPointer(pointerX: number, pointerY: number, centerX: number, centerY: number, baselineScale: number): {
+    layoutWidth: number;
+    layoutHeight: number;
+};
+export declare function buildTextPreviewBoxForEntry(entry: {
+    clip: {
+        textStyle?: Partial<TextClipStyle> | null;
+        textContent?: string;
+        name?: string;
+        visualTransform?: Partial<ClipVisualTransform> | null;
+    };
+}, frameSize: PreviewFrameSize, baselineScale: number, styleOverride?: TextLayoutStyleOverride | null): TextPreviewBoxLayout;

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

@@ -0,0 +1,64 @@
+import type { ActiveClipPlaybackInfo, PlayState, TrackType } from '../models/types';
+import type { PreviewSlotPhase } from '../controllers/previewBackend';
+export interface ResolvedSlotSource {
+    stableSourceUrl: string;
+    url: string;
+    objectUrl: string | null;
+    sizeBytes: number | null;
+}
+export interface SlotGeneration {
+    syncGen: number;
+    sourceGen: number;
+}
+export interface PlaybackSlotState {
+    trackId: string;
+    kind: TrackType;
+    role: 'current' | 'preload';
+    element: HTMLMediaElement;
+    wrapper: HTMLDivElement | null;
+    failureOverlay: HTMLDivElement | null;
+    failureLabel: HTMLDivElement | null;
+    entry: ActiveClipPlaybackInfo | null;
+    stableSourceUrl: string | null;
+    boundStableKey: string | null;
+    desiredSource: string | null;
+    objectUrl: string | null;
+    requestedPlayState: PlayState;
+    isActive: boolean;
+    isLoading: boolean;
+    isResolvingSource: boolean;
+    isBuffering: boolean;
+    isSeeking: boolean;
+    phase: PreviewSlotPhase;
+    errorMessage: string | null;
+    hasReadyEventSinceSourceChange: boolean;
+    pendingClockAlignmentMediaTime: number | null;
+    sourceGen: number;
+    sourceNode: MediaElementAudioSourceNode | null;
+    gainNode: GainNode | null;
+    audioRoutingFailed: boolean;
+    cleanup: Array<() => void>;
+    sourceMatchesDesired(): boolean;
+}
+export interface TrackedVideoSlotStatus {
+    failed: boolean;
+    resolving: boolean;
+    seeking: boolean;
+    mediaUnready: boolean;
+    ready: boolean;
+}
+export interface PreviewEngineCallbacks {
+    onSyncProcessed?: (syncRequestId?: number) => void;
+    onRuntimeStateChange?: (state: import('../controllers/previewBackend').PreviewRuntimeState) => void;
+    onAspectRatioChange?: (aspectRatio: import('../models/types').PreviewAspectRatio) => void;
+    onPreviewClipSelect?: (clipId: string) => void;
+    onVisualTransformCommit?: (clipId: string, visualTransform: import('../models/types').ClipVisualTransform) => void;
+    onTextFontSizeCommit?: (clipId: string, fontSize: number) => void;
+    onTextRotationCommit?: (clipId: string, rotation: number) => void;
+    onTextLayoutCommit?: (clipId: string, layout: {
+        layoutWidth: number;
+        layoutHeight: number;
+    }) => void;
+    onPendingPreviewRetry?: () => void;
+    onPauseIfPlaying?: () => void;
+}