Merge pull request #185 from walterlow/develop

Timeline compact clips, zoom perf, and filmstrip gap coverage

Author: walterlow

src/features/media-library/services/media-library-service.test.ts

@@ -203,7 +203,15 @@ describe('MediaLibraryService', () => {
       expect(indexedDbMocks.createMedia).toHaveBeenCalledTimes(1);
       expect(indexedDbMocks.associateMediaWithProject).toHaveBeenCalledWith('project-1', result.id);
       expect(indexedDbMocks.saveThumbnail).toHaveBeenCalledTimes(1);
-      expect(filmstripCacheMocks.prewarmPriorityWindow).toHaveBeenCalledWith(
+      expect(filmstripCacheMocks.prewarmPriorityWindow).toHaveBeenNthCalledWith(
+        1,
+        result.id,
+        mockFile,
+        10,
+        { startTime: 0, endTime: 1 },
+      );
+      expect(filmstripCacheMocks.prewarmPriorityWindow).toHaveBeenNthCalledWith(
+        2,
         result.id,
         mockFile,
         10,

src/features/media-library/services/media-library-service.ts

@@ -46,7 +46,9 @@ import {
 } from '@/features/media-library/deps/composition-runtime';
 export { FileAccessError } from './file-access';
 
+const IMPORT_FILMSTRIP_COVER_PREWARM_SECONDS = 1;
 const IMPORT_FILMSTRIP_PREWARM_SECONDS = 12;
+const IMPORT_BACKGROUND_COVER_WARM_DELAY_MS = 0;
 const IMPORT_BACKGROUND_WARM_DELAY_MS = 600;
 const IMPORT_BACKGROUND_HEAVY_DELAY_MS = 2200;
 
@@ -289,6 +291,20 @@ class MediaLibraryService {
     await associateMediaWithProject(projectId, id);
 
     if (metadata.type === 'video' && mediaMetadata.duration > 0) {
+      const coverWarmEndTime = Math.min(
+        mediaMetadata.duration,
+        IMPORT_FILMSTRIP_COVER_PREWARM_SECONDS,
+      );
+      enqueueBackgroundMediaWork(() => (
+        filmstripCache.prewarmPriorityWindow(id, file, mediaMetadata.duration, {
+          startTime: 0,
+          endTime: coverWarmEndTime,
+        })
+      ), {
+        priority: 'warm',
+        delayMs: IMPORT_BACKGROUND_COVER_WARM_DELAY_MS,
+      });
+
       const warmEndTime = Math.min(mediaMetadata.duration, IMPORT_FILMSTRIP_PREWARM_SECONDS);
       enqueueBackgroundMediaWork(() => (
         filmstripCache.prewarmPriorityWindow(id, file, mediaMetadata.duration, {

src/features/media-library/services/proxy-service.test.ts

@@ -387,7 +387,15 @@ describe('proxyService.loadExistingProxies', () => {
       loadCompletedProxy: (proxyKey: string) => Promise<void>;
     }).loadCompletedProxy('proxy-video-4');
 
-    expect(timelineServiceMocks.filmstripCache.prewarmPriorityWindow).toHaveBeenCalledWith(
+    expect(timelineServiceMocks.filmstripCache.prewarmPriorityWindow).toHaveBeenNthCalledWith(
+      1,
+      'video-4',
+      expect.objectContaining({ size: 1024 }),
+      20,
+      { startTime: 0, endTime: 1 },
+    );
+    expect(timelineServiceMocks.filmstripCache.prewarmPriorityWindow).toHaveBeenNthCalledWith(
+      2,
       'video-4',
       expect.objectContaining({ size: 1024 }),
       20,

src/features/media-library/services/proxy-service.ts

@@ -129,7 +129,9 @@ interface ProgressEmissionState {
 
 const PROXY_PROGRESS_EMIT_INTERVAL_MS = 150;
 const PROXY_PROGRESS_EMIT_MIN_DELTA = 0.01;
+const PROXY_FILMSTRIP_COVER_PREWARM_SECONDS = 1;
 const PROXY_FILMSTRIP_PREWARM_SECONDS = 12;
+const PROXY_FILMSTRIP_COVER_PREWARM_DELAY_MS = 0;
 const PROXY_FILMSTRIP_PREWARM_DELAY_MS = 900;
 const PROXY_PLAYBACK_ISSUE_SCORE_THRESHOLD = 5;
 const PROXY_PLAYBACK_ISSUE_WEIGHTS: Record<ProxyPlaybackIssue, number> = {
@@ -735,6 +737,17 @@ class ProxyService {
         continue;
       }
 
+      const coverWarmEndTime = Math.min(media.duration, PROXY_FILMSTRIP_COVER_PREWARM_SECONDS);
+      enqueueBackgroundMediaWork(() => (
+        filmstripCache.prewarmPriorityWindow(mediaId, proxyFile, media.duration, {
+          startTime: 0,
+          endTime: coverWarmEndTime,
+        })
+      ), {
+        priority: 'warm',
+        delayMs: PROXY_FILMSTRIP_COVER_PREWARM_DELAY_MS,
+      });
+
       const warmEndTime = Math.min(media.duration, PROXY_FILMSTRIP_PREWARM_SECONDS);
       enqueueBackgroundMediaWork(() => (
         filmstripCache.prewarmPriorityWindow(mediaId, proxyFile, media.duration, {

src/features/timeline/components/clip-filmstrip/index.tsx

@@ -531,7 +531,9 @@ export const ClipFilmstrip = memo(function ClipFilmstrip({
       const tileTime = effectiveStart + (tileCenterX / renderPixelsPerSecond) * speed;
       const nearestFrameIndex = Math.max(0, Math.round(tileTime));
       const frame = candidateFrameByIndex?.get(nearestFrameIndex)
-        ?? findClosestFrame(candidateFrames, tileTime);
+        ?? findClosestFrame(candidateFrames, tileTime)
+        // Fall back to full frame set — always cover gaps with the closest available frame
+        ?? findClosestFrame(frames, tileTime);
 
       if (frame) {
         result.push({ tileIndex: tile, frame, x: tileX, width: tileWidth });
@@ -553,6 +555,16 @@ export const ClipFilmstrip = memo(function ClipFilmstrip({
     renderWindow,
   ]);
 
+  // Pick a cover frame from the middle of available frames — used as a repeating
+  // CSS background behind tiles so gaps during zoom reconciliation show a frame
+  // instead of black. Track the full frame for stale-URL probing.
+  const coverFrame = useMemo(() => {
+    if (!frames || frames.length === 0) return null;
+    const mid = Math.floor(frames.length / 2);
+    return frames[mid] ?? frames[0] ?? null;
+  }, [frames]);
+  const coverFrameUrl = coverFrame?.url ?? null;
+
   if (error) {
     return null;
   }
@@ -577,6 +589,11 @@ export const ClipFilmstrip = memo(function ClipFilmstrip({
       )}
       <div
         className="absolute inset-0 overflow-hidden pointer-events-none"
+        style={coverFrameUrl ? {
+          backgroundImage: `url(${coverFrameUrl})`,
+          backgroundRepeat: 'repeat-x',
+          backgroundSize: `${thumbnailWidth}px ${height}px`,
+        } : undefined}
       >
         {tiles.map(({ tileIndex, frame, x, width }) => (
           <FilmstripTile
@@ -591,6 +608,17 @@ export const ClipFilmstrip = memo(function ClipFilmstrip({
             onSourceError={handleFrameSourceError}
           />
         ))}
+        {/* Hidden probe to detect stale cover background URL */}
+        {coverFrame && !coverFrame.bitmap && (
+          <img
+            src={coverFrame.url}
+            alt=""
+            aria-hidden
+            className="absolute h-px w-px opacity-0 pointer-events-none"
+            style={{ left: 0, top: 0 }}
+            onError={() => handleFrameSourceError(coverFrame.index)}
+          />
+        )}
       </div>
     </div>
   );

src/features/timeline/components/clip-waveform/adaptive-render-version.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import {
   getWaveformActiveTileCount,
+  getWaveformZoomCommitPhaseMs,
   getWaveformZoomRedrawIntervalMs,
 } from './adaptive-render-version';
 
@@ -27,4 +28,13 @@ describe('adaptive waveform render version helpers', () => {
     expect(getWaveformZoomRedrawIntervalMs(8)).toBe(24);
     expect(getWaveformZoomRedrawIntervalMs(12)).toBe(32);
   });
+
+  it('adds a stable phase delay for heavier redraw batches', () => {
+    expect(getWaveformZoomCommitPhaseMs(2, 'media-1')).toBe(0);
+    expect(getWaveformZoomCommitPhaseMs(8, 'media-1')).toBe(
+      getWaveformZoomCommitPhaseMs(8, 'media-1'),
+    );
+    expect(getWaveformZoomCommitPhaseMs(12, 'media-1')).toBeGreaterThanOrEqual(0);
+    expect(getWaveformZoomCommitPhaseMs(12, 'media-1')).toBeLessThanOrEqual(72);
+  });
 });

src/features/timeline/components/clip-waveform/adaptive-render-version.ts

@@ -12,6 +12,7 @@ interface AdaptiveWaveformRenderVersionOptions {
   baseVersion: string;
   pixelsPerSecond: number;
   activeTileCount: number;
+  phaseKey?: string;
 }
 
 function nowMs(): number {
@@ -46,10 +47,36 @@ export function getWaveformZoomRedrawIntervalMs(activeTileCount: number): number
   return 32;
 }
 
+function hashPhaseKey(phaseKey: string): number {
+  let hash = 0;
+  for (let i = 0; i < phaseKey.length; i += 1) {
+    hash = ((hash << 5) - hash) + phaseKey.charCodeAt(i);
+    hash |= 0;
+  }
+  return Math.abs(hash);
+}
+
+export function getWaveformZoomCommitPhaseMs(activeTileCount: number, phaseKey?: string): number {
+  if (!phaseKey || activeTileCount <= 2) {
+    return 0;
+  }
+
+  if (activeTileCount <= 4) {
+    return (hashPhaseKey(phaseKey) % 2) * 8;
+  }
+
+  if (activeTileCount <= 8) {
+    return (hashPhaseKey(phaseKey) % 4) * 8;
+  }
+
+  return (hashPhaseKey(phaseKey) % 6) * 10;
+}
+
 export function useAdaptiveWaveformRenderVersion({
   baseVersion,
   pixelsPerSecond,
   activeTileCount,
+  phaseKey,
 }: AdaptiveWaveformRenderVersionOptions): string {
   const zoomVersion = useMemo(
     () => `e${Math.round(Math.max(1, pixelsPerSecond) * 1000)}`,
@@ -59,6 +86,10 @@ export function useAdaptiveWaveformRenderVersion({
     () => getWaveformZoomRedrawIntervalMs(activeTileCount),
     [activeTileCount],
   );
+  const phaseDelayMs = useMemo(
+    () => getWaveformZoomCommitPhaseMs(activeTileCount, phaseKey),
+    [activeTileCount, phaseKey],
+  );
   const [committedZoomVersion, setCommittedZoomVersion] = useState(zoomVersion);
   const latestZoomVersionRef = useRef(zoomVersion);
   const lastCommitAtRef = useRef(0);
@@ -89,7 +120,11 @@ export function useAdaptiveWaveformRenderVersion({
     };
 
     const now = nowMs();
-    if (lastCommitAtRef.current === 0 || now - lastCommitAtRef.current >= redrawIntervalMs) {
+    const elapsedMs = now - lastCommitAtRef.current;
+    if (
+      lastCommitAtRef.current === 0
+      || (elapsedMs >= redrawIntervalMs && phaseDelayMs === 0)
+    ) {
       clearPending();
       commit();
       return;
@@ -99,17 +134,19 @@ export function useAdaptiveWaveformRenderVersion({
       return;
     }
 
-    const remainingMs = Math.max(0, redrawIntervalMs - (now - lastCommitAtRef.current));
+    const remainingMs = Math.max(0, redrawIntervalMs - elapsedMs);
+    const scheduledDelayMs = lastCommitAtRef.current === 0
+      ? phaseDelayMs
+      : remainingMs + phaseDelayMs;
     timeoutRef.current = setTimeout(() => {
       timeoutRef.current = null;
       rafRef.current = requestAnimationFrame(() => {
         rafRef.current = null;
         commit();
       });
-    }, remainingMs);
-
+    }, scheduledDelayMs);
     return clearPending;
-  }, [committedZoomVersion, redrawIntervalMs, zoomVersion]);
+  }, [committedZoomVersion, phaseDelayMs, redrawIntervalMs, zoomVersion]);
 
   useEffect(() => {
     return () => {

src/features/timeline/components/clip-waveform/compound-clip-waveform.tsx

@@ -47,6 +47,7 @@ export const CompoundClipWaveform = memo(function CompoundClipWaveform({
   const requestTokenRef = useRef(0);
   const pixelsPerSecondRef = useRef(pixelsPerSecond);
   pixelsPerSecondRef.current = pixelsPerSecond;
+  const amplitudesBufferRef = useRef<Float32Array>(new Float32Array(0));
   const [height, setHeight] = useState(0);
   const [waveformsByMediaId, setWaveformsByMediaId] = useState<Map<string, CachedWaveform>>(new Map());
   const [isLoading, setIsLoading] = useState(false);
@@ -217,12 +218,17 @@ export const CompoundClipWaveform = memo(function CompoundClipWaveform({
     const currentPps = Math.max(1, pixelsPerSecondRef.current);
     const centerY = height / 2;
     const maxWaveHeight = Math.max(1, (height / 2) - WAVEFORM_VERTICAL_PADDING_PX);
-    const amplitudes = new Array<number>(tileWidth + 1).fill(0);
+    const amplitudeCount = tileWidth + 1;
+    if (amplitudesBufferRef.current.length < amplitudeCount) {
+      amplitudesBufferRef.current = new Float32Array(amplitudeCount);
+    }
+    const amplitudes = amplitudesBufferRef.current;
+    amplitudes.fill(0, 0, amplitudeCount);
 
     ctx.beginPath();
     ctx.moveTo(0, centerY);
 
-    for (let x = 0; x <= tileWidth; x += 1) {
+    for (let x = 0; x < amplitudeCount; x += 1) {
       const timelinePosition = (tileOffset + x) / currentPps;
       const compoundTime = sourceStart + timelinePosition;
 
@@ -273,10 +279,10 @@ export const CompoundClipWaveform = memo(function CompoundClipWaveform({
       amplitudes[x] = amp * maxWaveHeight;
     }
 
-    for (let x = 0; x <= tileWidth; x += 1) {
+    for (let x = 0; x < amplitudeCount; x += 1) {
       ctx.lineTo(x, centerY - amplitudes[x]!);
     }
-    for (let x = tileWidth; x >= 0; x -= 1) {
+    for (let x = amplitudeCount - 1; x >= 0; x -= 1) {
       ctx.lineTo(x, centerY + amplitudes[x]!);
     }
     ctx.closePath();
@@ -296,6 +302,7 @@ export const CompoundClipWaveform = memo(function CompoundClipWaveform({
     baseVersion: `${peaks?.length ?? 0}:${height}:${waveformsByMediaId.size}`,
     pixelsPerSecond,
     activeTileCount,
+    phaseKey: mediaIdsKey,
   });
 
   if (hasError) {

src/features/timeline/components/clip-waveform/index.tsx

@@ -73,6 +73,7 @@ export const ClipWaveform = memo(function ClipWaveform({
   const containerRef = useRef<HTMLDivElement>(null);
   const pixelsPerSecondRef = useRef(pixelsPerSecond);
   pixelsPerSecondRef.current = pixelsPerSecond;
+  const amplitudesBufferRef = useRef<Float32Array>(new Float32Array(0));
   const [height, setHeight] = useState(0);
   const conformStartedRef = useRef(false);
   const { blobUrl, setBlobUrl, hasStartedLoadingRef, blobUrlVersion } = useMediaBlobUrl(mediaId);
@@ -212,12 +213,17 @@ export const ClipWaveform = memo(function ClipWaveform({
       const currentPps = Math.max(1, pixelsPerSecondRef.current);
       const centerY = height / 2;
       const maxWaveHeight = Math.max(1, (height / 2) - WAVEFORM_VERTICAL_PADDING_PX);
-      const amplitudes = new Array<number>(tileWidth + 1).fill(0);
+      const amplitudeCount = tileWidth + 1;
+      if (amplitudesBufferRef.current.length < amplitudeCount) {
+        amplitudesBufferRef.current = new Float32Array(amplitudeCount);
+      }
+      const amplitudes = amplitudesBufferRef.current;
+      amplitudes.fill(0, 0, amplitudeCount);
 
       ctx.beginPath();
       ctx.moveTo(0, centerY);
 
-      for (let x = 0; x <= tileWidth; x++) {
+      for (let x = 0; x < amplitudeCount; x++) {
         const timelinePosition = (tileOffset + x) / currentPps;
         const sourceTime = effectiveStart + (timelinePosition * speed);
 
@@ -274,10 +280,10 @@ export const ClipWaveform = memo(function ClipWaveform({
         amplitudes[x] = amp * maxWaveHeight;
       }
 
-      for (let x = 0; x <= tileWidth; x++) {
+      for (let x = 0; x < amplitudeCount; x++) {
         ctx.lineTo(x, centerY - amplitudes[x]!);
       }
-      for (let x = tileWidth; x >= 0; x--) {
+      for (let x = amplitudeCount - 1; x >= 0; x--) {
         ctx.lineTo(x, centerY + amplitudes[x]!);
       }
       ctx.closePath();
@@ -314,6 +320,7 @@ export const ClipWaveform = memo(function ClipWaveform({
     baseVersion: `${loadedSamples}:${height}`,
     pixelsPerSecond,
     activeTileCount,
+    phaseKey: mediaId,
   });
 
   // Show empty state for unsupported/failed waveforms (no infinite skeleton).