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

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

@@ -27,6 +27,7 @@ export interface TimelinePreviewBackendCallbacks {
         layoutWidth: number;
         layoutHeight: number;
     }) => void;
+    onTextLayoutResolved?: (clipId: string, layout: import('../models/types').TextClipResolvedLayout) => void;
     onPendingPreviewRetry?: () => void;
     onRuntimeError?: (error: unknown) => void;
     /** 预览层文字交互（点击字幕或文字变换控件）时若时间线处于播放中，用于请求暂停 */

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

@@ -349,6 +349,7 @@ export declare class TimelineManager {
     private clearTimelineClipMediaStatus;
     private getFailedPreviewClipIds;
     private getExportComposition;
+    private resolveTextClipExportLayout;
     private getExportCoverUrl;
     exportTimeline(): TimelineExportData;
     importTimeline(data: TimelineExportData): Promise<void>;
@@ -641,6 +642,7 @@ export declare class TimelineManager {
     private resolveSelectionChangeData;
     private commitPreviewVisualTransform;
     private commitPreviewTextLayout;
+    private commitPreviewTextResolvedLayout;
     private commitPreviewTextFontSize;
     private commitPreviewTextRotation;
     clearAllTracksAndClips(): void;

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

@@ -32,6 +32,26 @@ export interface TextClipStyle {
 }
 export declare const DEFAULT_TEXT_CLIP_STYLE: TextClipStyle;
 export declare function resolveTextClipStyle(style?: Partial<TextClipStyle> | null): TextClipStyle;
+export type TextClipLayoutMode = 'auto' | 'manual';
+/** 预览层布局完成后的归一化快照，供导出与后端渲染。 */
+export interface TextClipResolvedLayout {
+    /** 与 export composition 一致的 baseline 画布尺寸（短边 720）。 */
+    compositionWidth: number;
+    compositionHeight: number;
+    /** 文本框宽（baseline 参考画布 px，非最终成片 px）。 */
+    layoutWidth: number;
+    /** 文本框高（baseline 参考画布 px，非最终成片 px）。 */
+    layoutHeight: number;
+    /** layoutWidth / compositionWidth */
+    layoutWidthRatio: number;
+    /** layoutHeight / compositionHeight */
+    layoutHeightRatio: number;
+    /** 框中心锚点，画幅归一化 0–1（已从 legacy 底锚迁移）。 */
+    centerX: number;
+    centerY: number;
+    layoutMode: TextClipLayoutMode;
+    anchorVersion: 1;
+}
 export type PreviewBackendType = 'dom' | 'canvas' | 'auto';
 export interface Mp4PreviewMediaSource {
     url: string;
@@ -108,6 +128,7 @@ export interface ClipConfig {
     volume?: number;
     textContent?: string;
     textStyle?: Partial<TextClipStyle>;
+    textResolvedLayout?: TextClipResolvedLayout;
     ttsSourceTextClipId?: string;
     ttsVoiceId?: string;
     ttsVoiceName?: string;
@@ -136,6 +157,7 @@ export interface ClipEntity {
     volume?: number;
     textContent?: string;
     textStyle?: TextClipStyle;
+    textResolvedLayout?: TextClipResolvedLayout;
     ttsSourceTextClipId?: string;
     ttsVoiceId?: string;
     ttsVoiceName?: string;
@@ -518,6 +540,7 @@ export interface TimelineCompositionExportData {
     height: number;
     aspectRatio: string;
     mode: PreviewAspectRatioMode;
+    textPreviewFont?: TextPreviewFontConfig;
 }
 export interface TrackExportData {
     id: string;
@@ -548,6 +571,7 @@ export interface ClipExportData {
     volume?: number;
     textContent?: string;
     textStyle?: TextClipStyle;
+    textResolvedLayout?: TextClipResolvedLayout;
     ttsSourceTextClipId?: string;
     ttsVoiceId?: string;
     ttsVoiceName?: string;

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

@@ -22,3 +22,6 @@ export declare function getMediaDebugState(element: HTMLMediaElement): Diagnosti
 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;
+export declare function buildObjectUrlHolderId(clipId: string | undefined | null): string | null;
+export declare function isBlobObjectUrl(url: string | null | undefined): url is string;
+export declare function resolveBlobObjectUrl(objectUrl: string | null | undefined, playbackUrl: string): string | null;

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

@@ -1,13 +1,14 @@
 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 TextLayoutStyleOverride, type TextPreviewBoxLayout } from './textPreviewLayout';
 import type { PreviewPlaybackSlot } from './previewPlaybackSlot';
 export declare class PreviewDomCompositor {
     private container;
     private rootElement;
     private frameElement;
     private resizeObserver;
+    private onFrameLayoutChange;
     private requestedAspectRatio;
     private resolvedAutoAspectRatio;
     readonly transformOverlay: PreviewTransformOverlay;
@@ -15,6 +16,7 @@ export declare class PreviewDomCompositor {
     attach(container: HTMLElement, options: {
         rootClassName?: string;
         frameClassName?: string;
+        onFrameLayoutChange?: () => void;
     }): void;
     detach(): void;
     getFrameElement(): HTMLDivElement | null;
@@ -29,6 +31,7 @@ export declare class PreviewDomCompositor {
             entry: ActiveClipPlaybackInfo;
             element: HTMLElement;
         } | undefined;
+        getLayout?: (clipId: string) => TextPreviewBoxLayout | null;
         getTransientFontSize: (clipId: string) => number | null;
         getTransientRotation: (clipId: string) => number | null;
         getTextLayoutOverride?: (clipId: string) => TextLayoutStyleOverride | null;

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

@@ -60,6 +60,8 @@ export declare class PreviewEngine {
     get lastRuntimeState(): PreviewRuntimeState;
     refreshRuntimeState(): void;
     private applyTrackPlan;
+    private readonly releaseTrackedObjectUrl;
+    private rememberSlotObjectUrl;
     private getTrackSlots;
     private collectSlots;
     private buildLoadingState;
@@ -76,6 +78,7 @@ export declare class PreviewEngine {
     private getTextLayoutOptions;
     private handlePreviewTransformChange;
     refreshVisualLayout(): void;
+    private refreshTextSelectionOverlay;
     private refreshPendingOverlay;
     private syncLoadingProbe;
     private syncClockProbe;

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

@@ -21,6 +21,11 @@ export declare class PreviewPlaybackSlot implements PlaybackSlotState {
     boundStableKey: string | null;
     desiredSource: string | null;
     objectUrl: string | null;
+    objectUrlHolderId: string | null;
+    takeTrackedObjectUrl(): {
+        url: string | null;
+        holderId: string | null;
+    };
     requestedPlayState: PlayState;
     isActive: boolean;
     isLoading: boolean;
@@ -32,6 +37,7 @@ export declare class PreviewPlaybackSlot implements PlaybackSlotState {
     hasReadyEventSinceSourceChange: boolean;
     pendingClockAlignmentMediaTime: number | null;
     sourceGen: number;
+    private loadSourceGen;
     sourceNode: MediaElementAudioSourceNode | null;
     gainNode: GainNode | null;
     audioRoutingFailed: boolean;
@@ -48,7 +54,7 @@ export declare class PreviewPlaybackSlot implements PlaybackSlotState {
     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;
+    destroy(releaseObjectUrl: (url: string | null, holderId: string | null) => void): void;
     private syncCurrentPlayback;
     private preparePreload;
     private setVisible;

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

@@ -10,7 +10,7 @@ export interface PreviewSourceServiceDependencies {
 }
 export declare class PreviewSourceService {
     private readonly dependencies;
-    private readonly pendingRuntime;
+    private readonly pendingCacheRuntime;
     constructor(dependencies?: PreviewSourceServiceDependencies);
     resolve(entry: ActiveClipPlaybackInfo, options: {
         sourceGen: number;
@@ -18,7 +18,6 @@ export declare class PreviewSourceService {
         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

@@ -12,7 +12,7 @@ export interface PreviewSyncCoordinatorOptions {
     onAsyncWorkStarted: () => void;
     onAsyncWorkFinished: () => void;
     onStateChange: () => void;
-    releaseObjectUrl: (url: string | null) => void;
+    releaseObjectUrl: (url: string | null, holderId: string | null) => void;
     rememberObjectUrl: (slot: PreviewPlaybackSlot, url: string | null) => void;
     configureAudio: (slot: PreviewPlaybackSlot, entry: ActiveClipPlaybackInfo) => void;
     syncClockAlignment: (slot: PreviewPlaybackSlot, target: PreviewSlotTarget, clipChanged: boolean) => void;

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

@@ -19,6 +19,7 @@ export declare class PreviewTextLayer {
     private textPreviewFont;
     private readonly compositor;
     private readonly callbacks;
+    private autoRemeasureScheduled;
     constructor(compositor: PreviewDomCompositor, callbacks: PreviewTextLayer['callbacks']);
     mount(frameElement: HTMLDivElement): HTMLDivElement;
     destroy(): void;
@@ -36,6 +37,12 @@ export declare class PreviewTextLayer {
     private reapplyAllContent;
     private applyBoxLayout;
     private applyContent;
+    private usesManualTextLayout;
+    private emitResolvedLayout;
+    private finalizeTextBoxLayout;
+    private applyManualTextBoxLayout;
+    private applyAutoTextBoxLayout;
+    private scheduleAutoRemeasure;
     private getFontFamily;
     private ensureFontReady;
     private resetFontState;

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

@@ -0,0 +1,5 @@
+import type { Clip, TextClipResolvedLayout, TextPreviewFontConfig } from '../models/types';
+export declare function measureTextClipResolvedLayoutForExport(clip: Pick<Clip, 'textContent' | 'textStyle' | 'visualTransform' | 'name'>, composition: {
+    width: number;
+    height: number;
+}, textPreviewFont?: TextPreviewFontConfig | null): TextClipResolvedLayout | null;

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

@@ -1,4 +1,4 @@
-import type { ClipVisualTransform, TextClipStyle } from '../models/types';
+import type { ClipVisualTransform, TextClipLayoutMode, TextClipResolvedLayout, TextClipStyle } from '../models/types';
 import { type PreviewFrameSize, type PreviewRect } from '../controllers/previewTransformMath';
 /** 文本 visualTransform 使用框中心锚点。 */
 export declare const TEXT_CLIP_ANCHOR_VERSION_CENTER = 1;
@@ -33,8 +33,13 @@ export declare function resolveTextEntryMaxWidthPx(frameWidth: number, baselineS
 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 usesLegacyBottomAnchorY(textStyle: TextClipStyle, transformY: number): boolean;
+export declare function resolveTextBoxCenterY(frameSize: PreviewFrameSize, transform: ClipVisualTransform, textStyle: TextClipStyle, displayHeightPx: number): number;
 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;
+/** clip 已持久化 layoutHeight 表示用户手动调整过文本框，预览应固定高度并截断溢出。 */
+export declare function hasManualTextLayoutSize(textStyle: TextClipStyle): boolean;
+export declare function resolveTextClipLayoutMode(textStyle?: Partial<TextClipStyle> | null): TextClipLayoutMode;
 export declare function resolveTextLayoutDimensions(input: ComputeTextPreviewBoxInput): {
     layoutWidth: number;
     layoutHeight: number;
@@ -53,3 +58,22 @@ export declare function buildTextPreviewBoxForEntry(entry: {
         visualTransform?: Partial<ClipVisualTransform> | null;
     };
 }, frameSize: PreviewFrameSize, baselineScale: number, styleOverride?: TextLayoutStyleOverride | null): TextPreviewBoxLayout;
+export interface BuildTextClipResolvedLayoutInput {
+    frameSize: PreviewFrameSize;
+    composition: {
+        width: number;
+        height: number;
+    };
+    lastLayout: TextPreviewBoxLayout;
+    layoutMode: TextClipLayoutMode;
+}
+export declare function buildAutoMeasuredTextPreviewBoxLayout(input: {
+    layout: TextPreviewBoxLayout;
+    frameSize: PreviewFrameSize;
+    baselineScale: number;
+    visualTransform: ClipVisualTransform;
+    textStyle: TextClipStyle;
+    measuredHeightPx: number;
+}): TextPreviewBoxLayout;
+export declare function buildTextClipResolvedLayout(input: BuildTextClipResolvedLayoutInput): TextClipResolvedLayout;
+export declare function areTextClipResolvedLayoutsEqual(left?: TextClipResolvedLayout | null, right?: TextClipResolvedLayout | null, epsilon?: number): boolean;

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

@@ -59,6 +59,7 @@ export interface PreviewEngineCallbacks {
         layoutWidth: number;
         layoutHeight: number;
     }) => void;
+    onTextLayoutResolved?: (clipId: string, layout: import('../models/types').TextClipResolvedLayout) => void;
     onPendingPreviewRetry?: () => void;
     onPauseIfPlaying?: () => void;
 }

package/dist/core/resources/resourceCache/resourceCacheManager.d.ts

@@ -19,11 +19,18 @@ export declare class ResourceCacheManager {
     private readonly cacheKeyBuilder;
     private readonly onEvent?;
     private readonly objectUrls;
+    private readonly objectUrlByCacheKey;
+    private readonly cacheKeyByObjectUrl;
+    private readonly objectUrlHolders;
     private readonly inflightDownloads;
     constructor(dependencies?: ResourceCacheManagerDependencies);
     resolve(input: ResolveResourceInput): Promise<ResolvedCachedResource>;
     resolvePlayableUrl(input: ResolveResourceInput): Promise<ResolvedCachedResource>;
+    retainObjectUrl(url: string, holderId: string): void;
+    releaseObjectUrl(url: string, holderId: string): void;
+    /** @deprecated Prefer releaseObjectUrl with a clip holder id. */
     revokeObjectUrl(url: string): void;
+    forceRevokeObjectUrl(url: string): void;
     cleanupExpired(): Promise<void>;
     clear(): Promise<void>;
     getStats(): Promise<ResourceCacheStats>;
@@ -34,6 +41,9 @@ export declare class ResourceCacheManager {
     private downloadAndStore;
     private evictForWrite;
     private deleteEntry;
+    private registerObjectUrl;
+    private revokeTrackedObjectUrl;
     private blobResult;
+    private toResolvedBlob;
     private emitEvent;
 }