@hyperframes/studio 0.8.139 → 0.8.140

package/src/player/components/useTimelinePlayhead.ts

@@ -2,6 +2,17 @@ import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
+import {
+  currentTimelineZoomPercent,
+  requestTimelineZoom,
+  registerTimelineZoomViewport,
+  redrawTimelineZoomPreview,
+  settleTimelineZoom,
+  subscribeTimelineZoomPreview,
+  takeTimelineZoomAnchor,
+  timelineTimeAtX,
+  timelineZoomMapping,
+} from "./timelineZoomInput";
 import {
   getTimelinePlaybackFollowScrollLeft,
   getTimelineScrubTime,
@@ -36,17 +47,13 @@ interface UseTimelinePlayheadInput {
   isDragging: React.RefObject<boolean>;
   currentTime: number;
   zoomMode: ZoomMode;
-  manualZoomPercent: number;
   zoomModeRef: React.RefObject<ZoomMode>;
-  manualZoomPercentRef: React.RefObject<number>;
   fitPps: number;
   fitPpsRef: React.RefObject<number>;
   effectiveDuration: number;
   pps: number;
   timelineReady: boolean;
   elementsLength: number;
-  setZoomMode: (mode: ZoomMode) => void;
-  setManualZoomPercent: (percent: number) => void;
   onSeek?: (time: number) => void;
   contentOrigin: number;
 }
@@ -60,28 +67,23 @@ export function useTimelinePlayhead({
   currentTime,
   zoomMode,
   zoomModeRef,
-  manualZoomPercentRef,
   fitPps: _fitPps,
   fitPpsRef,
   effectiveDuration,
   pps,
   timelineReady,
   elementsLength,
-  setZoomMode,
-  setManualZoomPercent,
   onSeek,
   contentOrigin,
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
-  // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  // A zoom keeps its anchor (pinch: pointer, else playhead) in place; a resize keeps the centre.
   const previousAnchorPpsRef = useRef(pps);
   const userZoomCount = usePlayerStore((s) => s.userZoomCount);
   const previousZoomCountRef = useRef(userZoomCount);
   const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
   const lastSeekCountRef = useRef(liveTime.seekCount());
-  const skipCenterAnchorRef = useRef(false);
   const contentOriginRef = useRef(contentOrigin);
   contentOriginRef.current = contentOrigin;
 
@@ -91,12 +93,15 @@ export function useTimelinePlayhead({
     previousAnchorPpsRef.current = pps;
     const prevZoomCount = previousZoomCountRef.current;
     previousZoomCountRef.current = userZoomCount;
-    // Always consume the skip flag, even when pps didn't change — otherwise a
-    // pinch that produced no pps change (already at the zoom clamp) would strand
-    // it true and the next toolbar zoom would wrongly skip center-anchoring.
-    const skip = skipCenterAnchorRef.current;
-    skipCenterAnchorRef.current = false;
-    if (!scroll || pps === prevPps || skip) return;
+    // Consumed even when pps didn't change (at the clamp), so it never lingers for a later zoom.
+    const anchor = takeTimelineZoomAnchor();
+    if (!scroll || pps === prevPps) return;
+    if (anchor) {
+      const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+      const left = anchor.time * pps + contentOrigin - anchor.x;
+      scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, left));
+      return;
+    }
     const zoomed = userZoomCount !== prevZoomCount;
     if (!zoomed && scroll.scrollLeft < 1) return;
     const time = Math.max(0, lastLiveTimeRef.current);
@@ -121,10 +126,11 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
+      const at = timelineZoomMapping(ppsRef.current, contentOrigin);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         time,
-        ppsRef.current,
-        contentOrigin,
+        at.pps,
+        at.contentOrigin,
         !usePlayerStore.getState().isPlaying,
       );
     },
@@ -158,14 +164,18 @@ export function useTimelinePlayhead({
   useMountEffect(() => {
     const place = (t: number, atRest: boolean) => {
       if (!playheadRef.current || durationRef.current <= 0) return false;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
-        ppsRef.current,
-        contentOriginRef.current,
+        at.pps,
+        at.contentOrigin,
         atRest,
       );
       return true;
     };
+    const unsubPreview = subscribeTimelineZoomPreview(() =>
+      place(lastLiveTimeRef.current, !usePlayerStore.getState().isPlaying),
+    );
     const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
     const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
       if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
@@ -177,7 +187,8 @@ export function useTimelinePlayhead({
       lastLiveTimeRef.current = t;
       const playing = usePlayerStore.getState().isPlaying;
       if (!place(t, !playing)) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
+      const playheadX = at.contentOrigin + Math.max(0, t) * at.pps;
       const scroll = scrollRef.current;
       // Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
       if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
@@ -197,6 +208,7 @@ export function useTimelinePlayhead({
     return () => {
       unsub();
       unsubPlaying();
+      unsubPreview();
     };
   });
 
@@ -237,62 +249,44 @@ export function useTimelinePlayhead({
     [scrollRef, isDragging, zoomModeRef, seekFromX],
   );
 
+  // Trackpad pinch arrives as ctrl+wheel; Cmd+wheel zooms too, as Mac editors do.
   const handlePinchWheel = useCallback(
     (e: WheelEvent) => {
-      if (!e.ctrlKey) return;
+      if (!e.ctrlKey && !e.metaKey) return;
       const scroll = scrollRef.current;
       if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0)
         return;
       e.preventDefault();
       e.stopPropagation();
-      const rect = scroll.getBoundingClientRect();
-      const nextZoomPercent = getPinchTimelineZoomPercent(
-        e.deltaY,
-        zoomModeRef.current,
-        manualZoomPercentRef.current,
-        fitPpsRef.current,
+      const x = e.clientX - scroll.getBoundingClientRect().left;
+      requestTimelineZoom(
+        getPinchTimelineZoomPercent(
+          e.deltaY,
+          "manual",
+          currentTimelineZoomPercent(),
+          fitPpsRef.current,
+        ),
+        { time: Math.max(0, timelineTimeAtX(x) ?? 0), x },
       );
-      if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual")
-        return;
-      const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
-      const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
-        pointerX: e.clientX - rect.left,
-        currentScrollLeft: scroll.scrollLeft,
-        contentOrigin,
-        currentPixelsPerSecond: ppsRef.current,
-        nextPixelsPerSecond: nextPps,
-        duration: durationRef.current,
-      });
-      // Pinch anchors at the cursor (below), so skip the center-anchor effect.
-      skipCenterAnchorRef.current = true;
-      setZoomMode("manual");
-      setManualZoomPercent(nextZoomPercent);
-      requestAnimationFrame(() => {
-        const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
-        scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
-      });
     },
-    [
-      scrollRef,
-      durationRef,
-      fitPpsRef,
-      ppsRef,
-      zoomModeRef,
-      manualZoomPercentRef,
-      setManualZoomPercent,
-      setZoomMode,
-      contentOrigin,
-    ],
+    [scrollRef, durationRef, fitPpsRef, ppsRef],
   );
 
   useEffect(() => {
     const scroll = scrollRef.current;
     if (!scroll) return;
     scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    // A press meets the zoom it sees, not the one still waiting to be laid out.
+    scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
+    scroll.addEventListener("scroll", redrawTimelineZoomPreview, { passive: true });
+    const unregisterZoomViewport = registerTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+      scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
+      scroll.removeEventListener("scroll", redrawTimelineZoomPreview);
+      unregisterZoomViewport();
     };
-  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength]);
+  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
 
   return { seekFromX, autoScrollDuringDrag, dragScrollRaf };
 }

package/src/player/components/useTimelineProviderState.tsx

@@ -131,7 +131,7 @@ export function useTimelineProviderState({
   const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   const sessionEpoch = sessionEpochProp ?? timelineSessionEpoch;
   const setFocusedEaseSegment = usePlayerStore((s) => s.setFocusedEaseSegment);
-  const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+  const { zoomMode, manualZoomPercent } = useTimelineZoom();
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -258,22 +258,21 @@ export function useTimelineProviderState({
       timelineElements.length,
       displayLayout.totalH,
     ]);
-  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef, manualZoomPercentRef } =
-    useTimelineGeometry({
-      viewportWidth: viewport.clientWidth,
-      effectiveDuration,
-      zoomMode,
-      manualZoomPercent,
-      ppsRef,
-      fitPpsRef,
-      draggedClip,
-      resizingClip,
-      expandedElements: timelineElements,
-      isDragging,
-      scrollRef,
-      lastScrollLeftRef,
-      contentOrigin,
-    });
+  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef } = useTimelineGeometry({
+    viewportWidth: viewport.clientWidth,
+    effectiveDuration,
+    zoomMode,
+    manualZoomPercent,
+    ppsRef,
+    fitPpsRef,
+    draggedClip,
+    resizingClip,
+    expandedElements: timelineElements,
+    isDragging,
+    scrollRef,
+    lastScrollLeftRef,
+    contentOrigin,
+  });
   const timelineFocus = useTimelineLogicalFocus({
     scrollRef,
     tracks,
@@ -342,17 +341,13 @@ export function useTimelineProviderState({
     isDragging,
     currentTime,
     zoomMode,
-    manualZoomPercent,
     zoomModeRef,
-    manualZoomPercentRef,
     fitPps,
     fitPpsRef,
     effectiveDuration,
     pps,
     timelineReady,
     elementsLength: timelineElements.length,
-    setZoomMode,
-    setManualZoomPercent,
     onSeek,
     contentOrigin,
   });

package/src/player/components/useTimelineZoom.ts

@@ -1,6 +1,6 @@
 // fallow-ignore-file dead-code
-import { useCallback } from "react";
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
+import { cancelTimelineZoom, requestTimelineZoom } from "./timelineZoomInput";
 
 export interface TimelineZoomState {
   zoomMode: ZoomMode;
@@ -9,18 +9,13 @@ export interface TimelineZoomState {
   setManualZoomPercent: (percent: number) => void;
 }
 
-/** Shared zoom-related store selectors used by Timeline and TimelineToolbar. */
 export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
-  const setZoomMode = usePlayerStore((s) => s.setZoomMode);
-  const setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
-  const setManualZoomPercent = useCallback(
-    (percent: number) => {
-      usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
-      setStorePercent(percent);
-    },
-    [setStorePercent],
-  );
-  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
+  const setStoreZoomMode = usePlayerStore((s) => s.setZoomMode);
+  const setZoomMode = (mode: ZoomMode) => {
+    cancelTimelineZoom();
+    setStoreZoomMode(mode);
+  };
+  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent: requestTimelineZoom };
 }

package/src/player/lib/thumbnailVideoDecoder.test.ts

@@ -39,10 +39,20 @@ function recordDecodes(decoded: number[][]): void {
   });
 }
 
+const endOf = (start: number, duration: number) => start + Math.max(0, duration - 0.001);
+
+// Decoded frames are shared per source for the module's life, so each test decodes its own file.
+let sources = 0;
+let source = "";
+
 beforeEach(() => {
+  source = `/clip-${++sources}.mp4`;
   vi.clearAllMocks();
   getKeyPacket.mockImplementation(async () => null);
-  vi.spyOn(URL, "createObjectURL").mockReturnValueOnce("blob:one").mockReturnValueOnce("blob:two");
+  vi.spyOn(URL, "createObjectURL")
+    .mockReturnValueOnce("blob:one")
+    .mockReturnValueOnce("blob:two")
+    .mockReturnValueOnce("blob:end");
   vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
   HTMLCanvasElement.prototype.toBlob = function toBlob(callback) {
     callback(new Blob(["frame"], { type: "image/jpeg" }));
@@ -55,9 +65,15 @@ beforeEach(() => {
 });
 
 describe("videoThumbnailTimestamps", () => {
-  it("uses the midpoint for a poster and sorted sparse points for a strip", () => {
+  it("uses the midpoint for a poster, and each slice's left edge then the end for a strip", () => {
     expect(videoThumbnailTimestamps(2, 6, 1)).toEqual([5]);
-    expect(videoThumbnailTimestamps(2, 6, 4)).toEqual([2, 4, 6, 8]);
+    expect(videoThumbnailTimestamps(2, 6, 4)).toEqual([2, 3.5, 5, 6.5, endOf(2, 6)]);
+  });
+
+  it("nests each strip in the strip twice as long, and the poster in every strip", () => {
+    const strip = videoThumbnailTimestamps(0, 8, 4);
+    expect(videoThumbnailTimestamps(0, 8, 8).filter((_, i) => i % 2 === 0)).toEqual(strip);
+    expect(strip).toContain(videoThumbnailTimestamps(0, 8, 1)[0]);
   });
 
   it("clamps invalid source ranges", () => {
@@ -71,31 +87,31 @@ describe("decodeVideoThumbnail", () => {
     const decoded: number[][] = [];
     recordDecodes(decoded);
     const result = await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 6, frameCount: 2 },
+      { source, sourceStart: 2, sourceRangeDuration: 6, frameCount: 2 },
       new AbortController().signal,
     );
 
-    expect(decoded).toEqual([[2, 8]]);
+    expect(decoded).toEqual([[2, 5, endOf(2, 6)]]);
     expect(result.value).toEqual({
       kind: "filmstrip",
-      urls: ["blob:one", "blob:two"],
+      urls: ["blob:one", "blob:two", "blob:end"],
       aspect: 9 / 16,
     });
     result.dispose?.();
     result.dispose?.();
-    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(2);
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(3);
     expect(dispose).toHaveBeenCalledTimes(1);
   });
 
   it("decodes each strip frame at its keyframe unless that keyframe is before the clip's range", async () => {
-    getKeyPacket.mockImplementation(async (time) => ({ timestamp: Math.floor(time / 4) * 4 }));
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: time - 0.5 }));
     const decoded: number[][] = [];
     recordDecodes(decoded);
     await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 8, frameCount: 3 },
+      { source, sourceStart: 2, sourceRangeDuration: 8, frameCount: 4 },
       new AbortController().signal,
     );
-    expect(decoded).toEqual([[2, 4, 8]]);
+    expect(decoded).toEqual([[2, 3.5, 5.5, 7.5, endOf(2, 8)]]);
   });
 
   it("keeps a slot's own time when its keyframe is more than half a slot earlier", async () => {
@@ -103,14 +119,10 @@ describe("decodeVideoThumbnail", () => {
     const decoded: number[][] = [];
     recordDecodes(decoded);
     await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
-      new AbortController().signal,
-    );
-    await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 1 },
+      { source, sourceStart: 0, sourceRangeDuration: 10, frameCount: 4 },
       new AbortController().signal,
     );
-    expect(decoded).toEqual([[0, 5, 10], [5]]);
+    expect(decoded).toEqual([[0, 2.5, 5, 7.5, endOf(0, 10)]]);
   });
 
   it("looks up each keyframe just before decoding it", async () => {
@@ -126,10 +138,11 @@ describe("decodeVideoThumbnail", () => {
       }
     });
     await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+      { source, sourceStart: 0, sourceRangeDuration: 10, frameCount: 2 },
       new AbortController().signal,
     );
-    expect(events).toEqual(["key 0", "frame 0", "key 5", "frame 5", "key 10", "frame 10"]);
+    const end = endOf(0, 10);
+    expect(events).toEqual(["key 0", "frame 0", "key 5", "frame 5", `key ${end}`, `frame ${end}`]);
   });
 
   it("ends the decode times without throwing when cancelled during a keyframe lookup", async () => {
@@ -146,7 +159,7 @@ describe("decodeVideoThumbnail", () => {
     });
     await expect(
       decodeVideoThumbnail(
-        { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+        { source, sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
         controller.signal,
       ),
     ).rejects.toThrow("Aborted");
@@ -164,10 +177,198 @@ describe("decodeVideoThumbnail", () => {
     const decoded: number[][] = [];
     recordDecodes(decoded);
     await decodeVideoThumbnail(
-      { source: "/clip.mp4", sourceStart: 5, sourceRangeDuration: 5, frameCount: 3 },
+      { source, sourceStart: 5, sourceRangeDuration: 5, frameCount: 2 },
       new AbortController().signal,
     );
-    expect(decoded).toEqual([[5, 7.5, 10]]);
+    expect(decoded).toEqual([[5, 7.5, endOf(5, 5)]]);
+  });
+
+  it("reuses the frames a strip of the same source shows, so a zoom decodes only new times", async () => {
+    vi.mocked(URL.createObjectURL).mockImplementation(() => `blob:${Math.random()}`);
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    const range = { source, sourceStart: 0, sourceRangeDuration: 8 };
+    const signal = new AbortController().signal;
+    const four = await decodeVideoThumbnail({ ...range, frameCount: 4 }, signal);
+    // Twice the frames decodes only the new half; half the frames decodes nothing. All share the end.
+    const eight = await decodeVideoThumbnail({ ...range, frameCount: 8 }, signal);
+    const two = await decodeVideoThumbnail({ ...range, frameCount: 2 }, signal);
+    expect(decoded).toEqual([
+      [0, 2, 4, 6, endOf(0, 8)],
+      [1, 3, 5, 7],
+    ]);
+    const urls = (result: typeof four) =>
+      result.value.kind === "filmstrip" ? result.value.urls : [];
+    expect(urls(eight).filter((_, i) => i % 2 === 0)).toEqual(urls(four));
+    expect(urls(two)).toEqual([urls(four)[0], urls(four)[2], urls(four)[4]]);
+    for (const result of [four, eight, two]) result.dispose?.();
+  });
+
+  it("decodes a frame again when the one shared for its time sits too far before it", async () => {
+    // Every keyframe is 2 s before the time asked: a 2-frame strip of 8 s accepts that (its
+    // frames stand for 4 s each), a 4-frame strip does not, or its frames would run backwards.
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: time - 2 }));
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    const range = { source, sourceStart: 0, sourceRangeDuration: 8 };
+    const signal = new AbortController().signal;
+    const two = await decodeVideoThumbnail({ ...range, frameCount: 2 }, signal);
+    const four = await decodeVideoThumbnail({ ...range, frameCount: 4 }, signal);
+    expect(decoded).toEqual([
+      [0, 2, endOf(0, 8)],
+      [2, 4, 6],
+    ]);
+    two.dispose?.();
+    four.dispose?.();
+  });
+
+  it("returns a strip whose frames are all shared without opening the file again", async () => {
+    recordDecodes([]);
+    const range = { source, sourceStart: 0, sourceRangeDuration: 8 };
+    const signal = new AbortController().signal;
+    const four = await decodeVideoThumbnail({ ...range, frameCount: 4 }, signal);
+    const two = await decodeVideoThumbnail({ ...range, frameCount: 2 }, signal);
+    expect(input.getPrimaryVideoTrack).toHaveBeenCalledTimes(1);
+    four.dispose?.();
+    two.dispose?.();
+  });
+
+  it("reopens the same asset after a project round trip and keeps new-session frames separate", async () => {
+    let frame = 0;
+    vi.mocked(URL.createObjectURL)
+      .mockReset()
+      .mockImplementation(() => `blob:version-${++frame}`);
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    const signal = new AbortController().signal;
+    const original = await decodeVideoThumbnail(
+      { source, contentVersion: "A:1", frameCount: 1 },
+      signal,
+    );
+    const other = await decodeVideoThumbnail(
+      { source: `${source}?B`, contentVersion: "B:2", frameCount: 1 },
+      signal,
+    );
+    input.getPrimaryVideoTrack.mockResolvedValue({
+      getDisplayWidth: vi.fn(async () => 1280),
+      getDisplayHeight: vi.fn(async () => 360),
+      getDurationFromMetadata: vi.fn(async () => 10),
+    });
+    const reopened = await decodeVideoThumbnail(
+      { source, contentVersion: "A:3", frameCount: 1 },
+      signal,
+    );
+    const shared = await decodeVideoThumbnail(
+      { source, contentVersion: "A:3", frameCount: 1 },
+      signal,
+    );
+    expect(reopened.value).toEqual({ kind: "image", url: "blob:version-3", aspect: 32 / 9 });
+    expect(shared.value).toEqual(reopened.value);
+    expect(decoded).toEqual([[5], [5], [5]]);
+    expect(input.getPrimaryVideoTrack).toHaveBeenCalledTimes(3);
+    original.dispose?.();
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:version-1");
+    expect(URL.revokeObjectURL).not.toHaveBeenCalledWith("blob:version-3");
+    other.dispose?.();
+    reopened.dispose?.();
+    expect(URL.revokeObjectURL).not.toHaveBeenCalledWith("blob:version-3");
+    shared.dispose?.();
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(3);
+  });
+
+  it("keeps one copy of a frame two strips decode at once, and revokes the other", async () => {
+    vi.mocked(URL.createObjectURL).mockImplementation(() => `blob:${Math.random()}`);
+    // The first strip holds its first frame until the second is decoding too.
+    let release!: () => void;
+    const bothDecoding = new Promise<void>((resolve) => (release = resolve));
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      const first = canvasesAtTimestamps.mock.calls.length === 1;
+      for await (const _time of timestamps) {
+        if (first) await bothDecoding;
+        else release();
+        yield { canvas: document.createElement("canvas") };
+      }
+    });
+    const range = { source, sourceStart: 0, sourceRangeDuration: 8 };
+    const signal = new AbortController().signal;
+    const decodingTwo = decodeVideoThumbnail({ ...range, frameCount: 2 }, signal);
+    await vi.waitFor(() => expect(canvasesAtTimestamps).toHaveBeenCalledOnce());
+    const [two, four] = await Promise.all([
+      decodingTwo,
+      decodeVideoThumbnail({ ...range, frameCount: 4 }, signal),
+    ]);
+    // Both decoded the frames at 0 s, 4 s and the end; the second copy of each goes at once.
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(3);
+    two.dispose?.();
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(3);
+    four.dispose?.();
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(8);
+  });
+
+  it("fills a frame that failed to decode from the one before it, so tiles stay on their times", async () => {
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      let slot = 0;
+      for await (const _time of timestamps) {
+        yield slot++ === 2 ? null : { canvas: document.createElement("canvas") };
+      }
+    });
+    const signal = new AbortController().signal;
+    const result = await decodeVideoThumbnail(
+      { source, sourceStart: 0, sourceRangeDuration: 8, frameCount: 2 },
+      signal,
+    );
+    expect(result.value).toMatchObject({
+      kind: "filmstrip",
+      urls: ["blob:one", "blob:two", "blob:two"],
+    });
+    // The cache is charged for the two decoded frames, not the filled copy.
+    recordDecodes([]);
+    const whole = await decodeVideoThumbnail(
+      { source: `${source}?whole`, sourceStart: 0, sourceRangeDuration: 8, frameCount: 2 },
+      signal,
+    );
+    expect(result.weight * 3).toBe(whole.weight * 2);
+    result.dispose?.();
+    whole.dispose?.();
+  });
+
+  it("snaps a poster up to a quarter of its range and a strip frame up to half a slice", async () => {
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    const signal = new AbortController().signal;
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: time - 2.4 }));
+    await decodeVideoThumbnail(
+      { source, sourceStart: 0, sourceRangeDuration: 10, frameCount: 1 },
+      signal,
+    );
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: time - 2.6 }));
+    await decodeVideoThumbnail(
+      { source: `${source}?b`, sourceStart: 0, sourceRangeDuration: 10, frameCount: 1 },
+      signal,
+    );
+    // Four slices of 8 s: a keyframe 0.9 s early snaps, one 1.1 s early does not.
+    getKeyPacket.mockImplementation(async (time) => ({
+      timestamp: time - (time === 4 ? 0.9 : 1.1),
+    }));
+    await decodeVideoThumbnail(
+      { source: `${source}?c`, sourceStart: 0, sourceRangeDuration: 8, frameCount: 4 },
+      signal,
+    );
+    expect(decoded).toEqual([[5 - 2.4], [5], [0, 2, 4 - 0.9, 6, endOf(0, 8)]]);
+  });
+
+  it("revokes a shared frame only once no strip shows it", async () => {
+    vi.mocked(URL.createObjectURL).mockImplementation(() => `blob:${Math.random()}`);
+    recordDecodes([]);
+    const range = { source, sourceStart: 0, sourceRangeDuration: 8 };
+    const signal = new AbortController().signal;
+    const four = await decodeVideoThumbnail({ ...range, frameCount: 4 }, signal);
+    const two = await decodeVideoThumbnail({ ...range, frameCount: 2 }, signal);
+    four.dispose?.();
+    // The three frames the 2-slice strip still shows stay; the other two go.
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(2);
+    two.dispose?.();
+    expect(URL.revokeObjectURL).toHaveBeenCalledTimes(5);
   });
 
   it("releases input and degrades when the source has no video track", async () => {
@@ -181,13 +382,15 @@ describe("decodeVideoThumbnail", () => {
   it("revokes partial results when cancellation lands during extraction", async () => {
     const controller = new AbortController();
     const canvas = document.createElement("canvas");
-    canvasesAtTimestamps.mockImplementation(async function* () {
-      yield { canvas, timestamp: 1, duration: 1 };
-      controller.abort();
-      yield { canvas, timestamp: 2, duration: 1 };
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      let frames = 0;
+      for await (const timestamp of timestamps) {
+        if (frames++ === 1) controller.abort();
+        yield { canvas, timestamp, duration: 1 };
+      }
     });
     await expect(
-      decodeVideoThumbnail({ source: "/clip.mp4", frameCount: 2 }, controller.signal),
+      decodeVideoThumbnail({ source, frameCount: 2 }, controller.signal),
     ).rejects.toMatchObject({ name: "AbortError" });
     expect(URL.revokeObjectURL).toHaveBeenCalledTimes(1);
     expect(dispose).toHaveBeenCalledTimes(1);
@@ -207,10 +410,7 @@ describe("decodeVideoThumbnail", () => {
       getDurationFromMetadata,
     });
 
-    const decoding = decodeVideoThumbnail(
-      { source: "/clip.mp4", frameCount: 1 },
-      controller.signal,
-    );
+    const decoding = decodeVideoThumbnail({ source, frameCount: 1 }, controller.signal);
     await vi.waitFor(() => expect(getDisplayWidth).toHaveBeenCalledOnce());
     controller.abort();
     resolveWidth(1080);