@linker-design-plus/timeline-track 2.0.14 → 2.0.16

package/README.md

@@ -66,6 +66,23 @@ timeline.on('history_change', (_event, data) => {
 });
 ```
 
+### 预览资源缓存
+
+预览资源缓存默认关闭。开启后，可被前端 `fetch` 读取且不超过 100MB 的 `http:` / `https:` 音视频文件会被缓存到浏览器存储中，用于后续预览播放。默认策略为 30 天 TTL、10GB 应用级容量上限、优先 OPFS，并在 OPFS 不可用时降级到 IndexedDB Blob。缓存失败会自动回退原始媒体 URL。
+
+```ts
+const timeline = new TimelineManager({
+  container,
+  previewBackend: 'dom',
+  resourceCache: {
+    enabled: true,
+    resolveMode: 'prefer-fast-start'
+  }
+});
+```
+
+第一版不会缓存 HLS manifest / 分片，也不会缓存超过 100MB 的媒体文件。
+
 ## 核心能力
 
 - 多轨时间线编辑，支持视频轨和音频轨
@@ -89,6 +106,7 @@ timeline.on('history_change', (_event, data) => {
 - `updateClip(clipId, updates)` / `removeClip(clipId)`
 - `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
 - `splitCurrentClip()` / `removeClipGaps()`
+- `getRenderedHeight()`
 - `undo()` / `redo()` / `clearHistory()`
 - `attachPreview(containerOrConfig)` / `detachPreview()`
 - `exportTimeline()` / `loadDraft(data)`

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

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

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

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

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

@@ -1,5 +1,6 @@
 import type { ActiveClipPlaybackInfo, Clip, ClipVisualTransform, PlayState, PreviewAspectRatio, PreviewMediaSource, PreviewSourceResolver, TextPreviewFontConfig, TimeMs } from '../models/types';
 import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
+import type { ResourceCacheManager } from '../resources/resourceCache';
 import type { DiagnosticsCenter, DiagnosticEmitInput } from '../../utils/diagnostics';
 export interface TimelinePreviewSyncPayload {
     activeClips: ActiveClipPlaybackInfo[];
@@ -19,6 +20,7 @@ export interface TimelinePreviewBackendCallbacks {
     onSyncProcessed?: (syncRequestId?: number) => void;
     onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
+    onPreviewClipSelect?: (clipId: string) => void;
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onPendingPreviewRetry?: () => void;
     onRuntimeError?: (error: unknown) => void;
@@ -71,6 +73,7 @@ export interface TimelinePreviewBackendOptions {
     previewSourceResolver?: PreviewSourceResolver;
     textPreviewFont?: TextPreviewFontConfig | null;
     sourceMediaRegistry?: SourceMediaRegistry;
+    resourceCacheManager?: ResourceCacheManager | null;
     diagnostics?: DiagnosticsCenter;
     getDiagnosticsContext?: () => Partial<DiagnosticEmitInput>;
     rootClassName?: string;

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

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

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

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

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

@@ -1,5 +1,6 @@
 import type { ActiveClipPlaybackInfo, ClipVisualTransform, PlayState, PreviewAspectRatio, PreviewSourceResolver, TextPreviewFontConfig, TimeMs, TrackType } from '../models/types';
 import type { SourceMediaRegistry } from '../resources/sourceMediaRegistry';
+import type { ResourceCacheManager } from '../resources/resourceCache';
 import type { PreviewPendingState, PreviewRuntimeState } from './previewBackend';
 import { type DiagnosticEmitInput, type DiagnosticsCenter } from '../../utils/diagnostics';
 interface TimelinePreviewSessionCallbacks {
@@ -8,6 +9,7 @@ interface TimelinePreviewSessionCallbacks {
     onSyncProcessed?: (syncRequestId?: number) => void;
     onRuntimeStateChange?: (state: PreviewRuntimeState) => void;
     onAspectRatioChange?: (aspectRatio: PreviewAspectRatio) => void;
+    onPreviewClipSelect?: (clipId: string) => void;
     onVisualTransformCommit?: (clipId: string, visualTransform: ClipVisualTransform) => void;
     onPendingPreviewRetry?: () => void;
 }
@@ -23,6 +25,7 @@ interface TimelinePreviewSessionDependencies {
     previewSourceResolver?: PreviewSourceResolver;
     textPreviewFont?: TextPreviewFontConfig | null;
     sourceMediaRegistry?: SourceMediaRegistry;
+    resourceCacheManager?: ResourceCacheManager | null;
 }
 export interface TimelinePreviewSyncPayload {
     activeClips: ActiveClipPlaybackInfo[];
@@ -93,12 +96,19 @@ export declare class TimelinePreviewSession {
     private createSlot;
     private resetSlotRecoveryTracking;
     private destroySlot;
+    private releaseSlotObjectUrl;
+    private clearPendingRuntimeSource;
+    private rememberSlotObjectUrl;
+    private revokeResolvedObjectUrl;
     private getTrackSlots;
     private swapTrackSlots;
     private applyTrackPlan;
     private applySlotTarget;
+    private settleResolvedSourceWithoutRecovery;
     private resolveDesiredSource;
     private decorateSlotSourceUrl;
+    private resolvePlayableSlotSource;
+    private getReusableResolvedSlotSource;
     private slotNeedsRecovery;
     private recoverSlot;
     private finishSlotRecovery;
@@ -113,7 +123,9 @@ export declare class TimelinePreviewSession {
     private scheduleDeferredPreloadFlush;
     private flushDeferredPreloads;
     private applyResolvedSlotState;
+    private buildCurrentTargetForSlot;
     private isCurrentRequest;
+    private isCurrentSourceTarget;
     private shouldIgnoreExpectedEmptied;
     private shouldIgnoreExpectedAbort;
     private shouldIgnoreClearedSlotRecoverableEvent;

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

@@ -1,4 +1,5 @@
 import { type TimelinePreviewBackend } from '../controllers';
+import { type TimelineResourceCacheStats } from '../resources/resourceCache';
 import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener as TimelineEventListener, TimelineExportData, Track as TrackEntity, ThumbnailProvider, TrackInsertionPlacement, TrackType, ActiveClipPlaybackInfo, PreviewAspectRatio, PreviewMountConfig, PreviewBackendType, SelectedClipAudioAction, ClipConfigVoicePanelOptions } from '../models';
 import type { ResolvedPlaybackPlan } from '../controllers/timelinePlaybackResolver';
 import { TimelineClipConfigController } from '../controllers/timelineClipConfigController';
@@ -78,6 +79,7 @@ export declare class TimelineManager {
     private playbackAttemptId;
     private lastPreviewSyncedPlayState;
     private previewSyncInteractionMode;
+    private readonly resourceCacheManager;
     constructor(config?: Partial<TimelineConfig>);
     private createPlaybackAttemptId;
     private refreshPlaybackAttempt;
@@ -151,6 +153,7 @@ export declare class TimelineManager {
     private getTracksSortedByOrder;
     private getPlaybackTracksSnapshot;
     private buildPlaybackPlan;
+    private hasTimelineVideoClip;
     private getPreviewAutoAspectRatioClipOrderMap;
     private getNextPreviewAutoAspectRatioOrder;
     private getAutoAspectRatioClip;
@@ -160,6 +163,7 @@ export declare class TimelineManager {
     private beginPendingPreview;
     updatePendingPreviewState(): void;
     private buildPreviewPendingState;
+    private buildPreviewIndicatorState;
     private clearPendingPreviewState;
     private resetPreviewRuntimeState;
     private destroyPreviewSession;
@@ -375,6 +379,13 @@ export declare class TimelineManager {
     getPlayState(): PlayState;
     setDuration(duration: TimeMs): void;
     getDuration(): TimeMs;
+    /**
+     * 获取当前时间轴内容完整渲染高度。
+     *
+     * 该高度包含顶部时间刻度、所有轨道内容和底部横向滚动条，可供外部容器
+     * 在需要贴合内容时作为高度参考。
+     */
+    getRenderedHeight(): number;
     /**
      * 调整时间轴大小以适配容器
      * @param width 新的宽度
@@ -479,6 +490,7 @@ export declare class TimelineManager {
     removeSelectedClips(): boolean;
     canSeparateClipAudio(clipId: string): boolean;
     canRestoreClipAudio(clipId: string): boolean;
+    private pausePlaybackForAudioSeparation;
     private resolvePreferredSeparatedAudioTrackId;
     separateClipAudio(clipId: string): Promise<string | null>;
     restoreClipAudio(clipId: string): boolean;
@@ -496,6 +508,9 @@ export declare class TimelineManager {
      * @returns 从 0 到最后一个音视频 clip 终点的时长（毫秒）
      */
     getTrackTotalDuration(): TimeMs;
+    getResourceCacheStats(): Promise<TimelineResourceCacheStats>;
+    cleanupResourceCache(): Promise<void>;
+    clearResourceCache(): Promise<void>;
     destroy(): void;
     private initKeyboardShortcuts;
     /** 清除历史堆栈 */
@@ -543,6 +558,7 @@ export declare class TimelineManager {
     private handleBoxSelectEnd;
     private isPointOnClip;
     private getClipsIntersectingBox;
+    private resolveTrackRenderHeight;
     private addClipToTrack;
     private cloneTrackSnapshot;
     private ensureTrackFromHistorySnapshot;

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

@@ -22,7 +22,6 @@ export interface TextClipStyle {
     rotation: number;
     strokeColor: string;
     strokeWidth: number;
-    lineHeight: number;
     paddingX: number;
 }
 export declare const DEFAULT_TEXT_CLIP_STYLE: TextClipStyle;
@@ -38,7 +37,12 @@ export interface HlsFmp4PreviewMediaSource {
     mimeType: string;
     kind: 'hls-fmp4';
 }
-export type PreviewMediaSource = Mp4PreviewMediaSource | HlsFmp4PreviewMediaSource;
+export interface AudioPreviewMediaSource {
+    url: string;
+    mimeType: string;
+    kind: 'audio';
+}
+export type PreviewMediaSource = Mp4PreviewMediaSource | HlsFmp4PreviewMediaSource | AudioPreviewMediaSource;
 export type PreviewSourceResolver = (clip: Clip) => PreviewMediaSource | null | Promise<PreviewMediaSource | null>;
 export interface TextPreviewFontConfig {
     fontName: string;
@@ -191,6 +195,15 @@ export interface TimelineKeyboardShortcutsConfig {
 }
 export declare const defaultDarkTheme: Theme;
 export declare function resolveTheme(theme?: ThemeConfig): Theme;
+export interface TimelineResourceCacheConfig {
+    enabled?: boolean;
+    maxEntryBytes?: number;
+    maxTotalBytes?: number;
+    ttlMs?: number;
+    preferStorage?: 'opfs' | 'indexeddb';
+    resolveMode?: 'prefer-fast-start' | 'prefer-cache-ready';
+    allowedMimeTypes?: string[];
+}
 export interface TimelineConfig {
     duration: TimeMs;
     zoom: number;
@@ -207,6 +220,7 @@ export interface TimelineConfig {
     thumbnailProvider?: ThumbnailProvider;
     previewBackend?: PreviewBackendType;
     previewSourceResolver?: PreviewSourceResolver;
+    resourceCache?: boolean | TimelineResourceCacheConfig;
     textPreviewFont?: TextPreviewFontConfig | null;
     draftData?: TimelineExportData;
     keyboardShortcuts?: false | TimelineKeyboardShortcutsConfig;

package/dist/core/resources/previewMediaSourceResolver.d.ts

@@ -0,0 +1,4 @@
+import type { PreviewMediaSource } from '../models/types';
+export declare function resolveDefaultPreviewMediaSource(source: {
+    src: string;
+}): PreviewMediaSource | null;

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

@@ -0,0 +1,5 @@
+import type { ResolveResourceInput, ResourceCacheConfig, ResourceCacheOptions } from './types';
+export declare function normalizeResourceCacheOptions(config: ResourceCacheConfig | undefined): ResourceCacheOptions;
+export declare function normalizeResourceUrl(url: string): string;
+export declare function buildResourceCacheKey(input: Pick<ResolveResourceInput, 'sourceKey' | 'url'>): Promise<string>;
+export declare function shouldBypassResourceCache(input: ResolveResourceInput, allowedMimeTypes?: string[]): boolean;

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

@@ -0,0 +1,5 @@
+import type { ResourceCacheHttpClient, ResourceProbeResult } from './types';
+export declare class FetchResourceCacheHttpClient implements ResourceCacheHttpClient {
+    probe(url: string): Promise<ResourceProbeResult>;
+    download(url: string): Promise<Blob>;
+}

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

@@ -0,0 +1,7 @@
+export * from './types';
+export { IndexedDbResourceMetadataStore, createMemoryMetadataStore } from './metadataStore';
+export { IndexedDbResourceStorage, OpfsResourceStorage, createMemoryResourceStorage, createResourceCacheStorage } from './storage';
+export { buildResourceCacheKey, normalizeResourceCacheOptions, normalizeResourceUrl, shouldBypassResourceCache } from './cacheKey';
+export { FetchResourceCacheHttpClient } from './http';
+export { ResourceCacheManager } from './resourceCacheManager';
+export type { ResourceCacheManagerDependencies } from './resourceCacheManager';

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

@@ -0,0 +1,11 @@
+import type { CachedResourceMetadata, ResourceCacheMetadataStore } from './types';
+export declare class IndexedDbResourceMetadataStore implements ResourceCacheMetadataStore {
+    private dbPromise;
+    private getDb;
+    get(cacheKey: string): Promise<CachedResourceMetadata | null>;
+    put(metadata: CachedResourceMetadata): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+    list(): Promise<CachedResourceMetadata[]>;
+}
+export declare function createMemoryMetadataStore(initial?: CachedResourceMetadata[]): ResourceCacheMetadataStore;

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

@@ -0,0 +1,39 @@
+import type { ObjectUrlAdapter, ResolveResourceInput, ResolvedCachedResource, ResourceCacheConfig, ResourceCacheHttpClient, ResourceCacheMetadataStore, ResourceCacheStats, ResourceCacheStorage } from './types';
+export interface ResourceCacheManagerDependencies {
+    options?: ResourceCacheConfig;
+    metadataStore?: ResourceCacheMetadataStore;
+    storage?: ResourceCacheStorage;
+    http?: ResourceCacheHttpClient;
+    objectUrl?: ObjectUrlAdapter;
+    now?: () => number;
+    cacheKeyBuilder?: (input: Pick<ResolveResourceInput, 'sourceKey' | 'url'>) => Promise<string>;
+    onEvent?: (eventName: string, data: Record<string, unknown>) => void;
+}
+export declare class ResourceCacheManager {
+    private readonly options;
+    private readonly metadataStore;
+    private readonly storagePromise;
+    private readonly http;
+    private readonly objectUrl;
+    private readonly now;
+    private readonly cacheKeyBuilder;
+    private readonly onEvent?;
+    private readonly objectUrls;
+    private readonly inflightDownloads;
+    constructor(dependencies?: ResourceCacheManagerDependencies);
+    resolve(input: ResolveResourceInput): Promise<ResolvedCachedResource>;
+    resolvePlayableUrl(input: ResolveResourceInput): Promise<ResolvedCachedResource>;
+    revokeObjectUrl(url: string): void;
+    cleanupExpired(): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): Promise<ResourceCacheStats>;
+    private resolveExpired;
+    private probeCacheable;
+    private probeAndDownload;
+    private getOrCreateDownload;
+    private downloadAndStore;
+    private evictForWrite;
+    private deleteEntry;
+    private blobResult;
+    private emitEvent;
+}

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

@@ -0,0 +1,24 @@
+import type { ResourceCacheStorage, ResourceCacheStorageKind } from './types';
+export declare class IndexedDbResourceStorage implements ResourceCacheStorage {
+    readonly kind: "indexeddb";
+    private dbPromise;
+    private getDb;
+    read(cacheKey: string): Promise<Blob | null>;
+    write(cacheKey: string, blob: Blob): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class OpfsResourceStorage implements ResourceCacheStorage {
+    readonly kind: "opfs";
+    private directoryPromise;
+    private getDirectory;
+    ensureReady(): Promise<boolean>;
+    read(cacheKey: string): Promise<Blob | null>;
+    write(cacheKey: string, blob: Blob): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function createMemoryResourceStorage(kind?: ResourceCacheStorageKind): ResourceCacheStorage;
+export declare function createResourceCacheStorage(options: {
+    preferStorage: ResourceCacheStorageKind;
+}): Promise<ResourceCacheStorage>;

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

@@ -0,0 +1,85 @@
+export type ResourceCacheStorageKind = 'opfs' | 'indexeddb';
+export type ResourceCacheResolveMode = 'prefer-fast-start' | 'prefer-cache-ready';
+export type ResourceCacheStatus = 'hit' | 'miss' | 'bypass' | 'stale-revalidated' | 'fallback';
+export interface ResourceCacheOptions {
+    enabled: boolean;
+    maxEntryBytes: number;
+    maxTotalBytes: number;
+    ttlMs: number;
+    preferStorage: ResourceCacheStorageKind;
+    resolveMode: ResourceCacheResolveMode;
+    allowedMimeTypes: string[];
+}
+export type ResourceCacheConfig = boolean | Partial<ResourceCacheOptions>;
+export interface ResolveResourceInput {
+    url: string;
+    mimeType?: string | null;
+    kind?: string | null;
+    sourceKey?: string | null;
+}
+export interface ResolvedCachedResource {
+    url: string;
+    cacheStatus: ResourceCacheStatus;
+    sourceUrl: string;
+    sizeBytes?: number;
+    objectUrl?: string;
+}
+export interface ResourceProbeResult {
+    url: string;
+    ok: boolean;
+    status: number;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    etag: string | null;
+    lastModified: string | null;
+    acceptRanges: string | null;
+}
+export interface CachedResourceMetadata {
+    cacheKey: string;
+    sourceUrl: string;
+    mimeType: string | null;
+    sizeBytes: number;
+    etag: string | null;
+    lastModified: string | null;
+    contentLength: number | null;
+    storageKind: ResourceCacheStorageKind;
+    createdAt: number;
+    updatedAt: number;
+    lastAccessedAt: number;
+    expiresAt: number;
+}
+export interface ResourceCacheStats {
+    entryCount: number;
+    totalBytes: number;
+    maxTotalBytes: number;
+}
+export interface TimelineResourceCacheStats extends ResourceCacheStats {
+    enabled: boolean;
+}
+export interface ResourceCacheStorage {
+    readonly kind: ResourceCacheStorageKind;
+    read(cacheKey: string): Promise<Blob | null>;
+    write(cacheKey: string, blob: Blob): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface ResourceCacheMetadataStore {
+    get(cacheKey: string): Promise<CachedResourceMetadata | null>;
+    put(metadata: CachedResourceMetadata): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+    list(): Promise<CachedResourceMetadata[]>;
+}
+export interface ResourceCacheHttpClient {
+    probe(url: string): Promise<ResourceProbeResult>;
+    download(url: string): Promise<Blob>;
+}
+export interface ObjectUrlAdapter {
+    createObjectURL(blob: Blob): string;
+    revokeObjectURL(url: string): void;
+}
+export declare const RESOURCE_CACHE_DEFAULT_MAX_ENTRY_BYTES: number;
+export declare const RESOURCE_CACHE_DEFAULT_MAX_TOTAL_BYTES: number;
+export declare const RESOURCE_CACHE_DEFAULT_TTL_MS: number;
+export declare const RESOURCE_CACHE_DEFAULT_ALLOWED_MIME_TYPES: string[];
+export declare const RESOURCE_CACHE_DEFAULT_OPTIONS: ResourceCacheOptions;