@linker-design-plus/timeline-track 2.0.15 → 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 的媒体文件。
+
 ## 核心能力
 
 - 多轨时间线编辑，支持视频轨和音频轨

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[];
@@ -72,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/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 {
@@ -24,6 +25,7 @@ interface TimelinePreviewSessionDependencies {
     previewSourceResolver?: PreviewSourceResolver;
     textPreviewFont?: TextPreviewFontConfig | null;
     sourceMediaRegistry?: SourceMediaRegistry;
+    resourceCacheManager?: ResourceCacheManager | null;
 }
 export interface TimelinePreviewSyncPayload {
     activeClips: ActiveClipPlaybackInfo[];
@@ -94,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;
@@ -114,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;
@@ -506,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;
     /** 清除历史堆栈 */

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

@@ -37,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;
@@ -190,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;
@@ -206,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;