@hyperframes/studio 0.8.78 → 0.8.80

package/src/player/components/useAutomationLanes.ts

@@ -5,15 +5,15 @@
  * Reading lives in `automationLaneData`, shared with the row layout, which needs
  * the lane count to reserve height.
  *
- * Edits go to the *selected* element, because that is what the attribute commit
- * path targets. An unselected clip still draws its envelopes — they are just
- * read only, which is also what stops a stray drag from editing the wrong track.
+ * Edits save through the timeline's gated save, as an effect preset does, so a
+ * locked clip or group refuses them. Only the selected element is editable: an
+ * unselected one still draws its envelopes read only, which is also what stops a
+ * stray drag from editing the wrong track.
  */
 
-import { useCallback, useMemo, useRef } from "react";
+import { useCallback, useMemo } from "react";
 import {
   HF_AUDIO_AUTOMATION_ATTR,
-  serializeAutomation,
   type HfAutomation,
   type HfAutomationLane,
 } from "@hyperframes/core/audio-automation";
@@ -22,22 +22,25 @@ import {
   useDomEditActionsContextOptional,
   useDomEditSelectionContextOptional,
 } from "../../contexts/DomEditContext";
-import { resolveTimelineIdForSelection } from "../../utils/studioHelpers";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { AutomationSelection } from "../store/automationSelectionSlice";
+import { automationAttrValue } from "../../components/editor/propertyPanelAutomation";
 import { elementAutomation, elementFxChain } from "./automationLaneData";
-import { createAutomationGestureKeys } from "./automationGestureKeys";
+import { isGroupAutomationElement } from "./groupAutomationElement";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
 
 export interface AutomationLaneBinding {
   automation: HfAutomation;
   /** One entry per lane, in draw order — each gets its own row. */
   lanes: HfAutomationLane[];
   chain: HfAudioFxChain | null;
-  /** Continuous write while dragging; does not persist. */
-  onPreview(next: HfAutomation): void;
+  /** Continuous write while dragging; does not persist. `ended`: a cancel put the start back. */
+  onPreview(next: HfAutomation, ended?: boolean): void;
   /** Gesture-end write; this is the one that persists and lands in undo. */
-  onCommit(next: HfAutomation): void;
+  onCommit(next: HfAutomation): Promise<TimelineEditOutcome | void>;
   /**
    * Select this clip, which is what makes its lanes editable. A lane calls this
    * instead of writing when it is read-only — pressing the lane is the only
@@ -46,15 +49,6 @@ export interface AutomationLaneBinding {
    */
   onSelect(): void;
   readOnly: boolean;
-  /**
-   * The timeline clip `onCommit`/`onPreview` will ACTUALLY persist to, which is
-   * whatever the dom-edit layer has selected — not necessarily the element this
-   * binding was made for (see `onSelect` below). Null outside an edit session or
-   * when the dom-edit selection maps to no clip. Resolved exactly the way
-   * applyDomSelection resolves it, so in a settled selection it equals the bound
-   * element's key; it lags only in the window a non-gesture caller can hit.
-   */
-  commitTargetKey: string | null;
   /** This element's active selection box, or null if none / it belongs to a
    *  different element. */
   selection: AutomationSelection | null;
@@ -69,80 +63,69 @@ export interface UseAutomationLanesResult {
   bind(element: TimelineElement, isSelected: boolean): AutomationLaneBinding;
 }
 
+const AUTOMATION_LABEL = "Edit automation";
+
+/** A group's lanes save on the group, gated by its members; a clip's on the clip. */
+function automationWriters(edit: TimelineEditCallbacks, element: TimelineElement) {
+  if (isGroupAutomationElement(element)) {
+    const { onSetAudioGroupAttributeLive: live, onSetAudioGroupAttributeQuiet: save } = edit;
+    if (!live || !save) return null;
+    return {
+      live: (value: string | null) => live(element.id, HF_AUDIO_AUTOMATION_ATTR, value),
+      revert: () => edit.onRevertAudioGroupAttributeLive?.(element.id, HF_AUDIO_AUTOMATION_ATTR),
+      save: (value: string | null) =>
+        save(element.id, HF_AUDIO_AUTOMATION_ATTR, value, AUTOMATION_LABEL),
+    };
+  }
+  const { onSetElementAttributeLive: live, onSetElementAttributeQuiet: save } = edit;
+  if (!live || !save) return null;
+  return {
+    live: (value: string | null) => live(element, HF_AUDIO_AUTOMATION_ATTR, value),
+    revert: () => edit.onRevertElementAttributeLive?.(element, HF_AUDIO_AUTOMATION_ATTR),
+    save: (value: string | null) =>
+      save(element, HF_AUDIO_AUTOMATION_ATTR, value, AUTOMATION_LABEL),
+  };
+}
+
 export function useAutomationLanes(): UseAutomationLanesResult {
-  // One per hook instance, held across renders: a gesture spans many commits and
-  // they all have to record under the same key for undo to take the whole drag.
-  const gestureKeys = useRef(createAutomationGestureKeys());
   // Optional: the player also runs outside Studio, where there is no edit
   // session. There the lanes render read-only, which is the right fallback.
   const domEdit = useDomEditActionsContextOptional();
-  const domEditSelection = useDomEditSelectionContextOptional()?.domEditSelection ?? null;
-  const elements = usePlayerStore((s) => s.elements);
+  const domEditSelectionRef = useDomEditSelectionContextOptional()?.domEditSelectionRef;
+  const timelineEdit = useTimelineEditContextOptional();
   const automationSelection = usePlayerStore((s) => s.automationSelection);
   const setAutomationSelection = usePlayerStore((s) => s.setAutomationSelection);
   const clearAutomationSelection = usePlayerStore((s) => s.clearAutomationSelection);
 
-  // Read from the SAME render as the commit handlers below: both contexts update
-  // in one commit, so a handler and this key can never describe different
-  // moments. activeCompPath is not needed — resolveTimelineIdForSelection only
-  // uses it as a fallback for a selection with no sourceFile of its own, and
-  // DomEditSelection always carries one.
-  const commitTargetKey = useMemo(
-    () =>
-      domEditSelection ? resolveTimelineIdForSelection(domEditSelection, elements, null) : null,
-    [domEditSelection, elements],
-  );
-
   const bind = useCallback(
     (element: TimelineElement, isSelected: boolean): AutomationLaneBinding => {
       const chain = elementFxChain(element);
       const automation = elementAutomation(element);
       const elementKey = getTimelineElementIdentity(element);
 
-      const write = (next: HfAutomation, persist: boolean): void => {
-        if (!domEdit || !isSelected) return;
-        const value = next.lanes.length > 0 ? serializeAutomation(next) : "";
-        // Every write of one gesture under one key, so undo takes back the whole
-        // drag rather than the last fragment history happened to keep.
-        const coalesce = persist ? gestureKeys.current.commit() : gestureKeys.current.live();
-        // Quiet, not the refreshing commit: releasing a dragged point used to
-        // reload the preview, which restarts every playing track — the same chop
-        // the live write during the drag exists to avoid. Quiet still persists
-        // and still resyncs the selection, so the next edit sees this one.
-        if (persist) {
-          void domEdit.handleDomAttributeQuietCommit(HF_AUDIO_AUTOMATION_ATTR, value, coalesce);
-        }
-        // Dragging a point writes live: no preview refresh, so the composition
-        // does not reload and restart playback on every pixel.
-        else {
-          // Preview only, because a gesture writes on every pointermove: the
-          // preview and the running audio follow the pointer, and the release
-          // below is the one write that reaches the file and the undo stack.
-          void domEdit.handleDomAttributeLiveCommit(
-            HF_AUDIO_AUTOMATION_ATTR,
-            value || null,
-            undefined,
-            {
-              coalesce,
-              previewOnly: true,
-            },
-          );
-        }
-      };
+      const writers = domEdit && isSelected ? automationWriters(timelineEdit, element) : null;
 
       return {
         automation,
         lanes: automation.lanes,
         chain,
-        onPreview: (next) => write(next, false),
-        onCommit: (next) => write(next, true),
-        // Deliberately not awaited before an edit: the commit handlers close
-        // over the selection as it was when they were built, so writing in the
-        // same tick would land on whichever element was selected before.
-        // Selecting is its own gesture; the lane goes live after it.
+        onPreview: (next, ended) => {
+          writers?.live(automationAttrValue(next) || null);
+          if (ended) writers?.revert();
+        },
+        onCommit: async (next) => {
+          if (!writers) return;
+          const outcome = await writers.save(automationAttrValue(next) || null);
+          // The FX panel reads the selection snapshot; a stale one makes its next
+          // edit start from the automation this one replaced.
+          const selection = domEditSelectionRef?.current;
+          if (selection) void domEdit?.refreshDomEditSelectionFromPreview(selection);
+          return outcome;
+        },
+        // Deliberately not awaited before an edit: the lane goes live when the
+        // selection lands and it re-renders as selected.
         onSelect: () => void domEdit?.handleTimelineElementSelect(element),
-        readOnly: !domEdit || !isSelected,
-        commitTargetKey: domEdit ? commitTargetKey : null,
+        readOnly: !writers,
         selection: automationSelection?.elementKey === elementKey ? automationSelection : null,
         // Not gated on `isSelected`, unlike the writes above. A selection is
         // ephemeral store state, and the drag that draws one on a read-only lane is
@@ -159,7 +142,8 @@ export function useAutomationLanes(): UseAutomationLanesResult {
     },
     [
       domEdit,
-      commitTargetKey,
+      domEditSelectionRef,
+      timelineEdit,
       automationSelection,
       setAutomationSelection,
       clearAutomationSelection,

package/src/player/hooks/useTimelinePlayer.hiddenPause.test.ts

@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  attachIframeWindow,
+  makeAdapterWindow,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+describe("useTimelinePlayer tab hidden while playing", () => {
+  it("pauses on the adapter's time, like any other pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    act(() => api.play());
+    adapter.seek(6);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(6);
+    act(() => root.unmount());
+  });
+
+  it("stops a reverse shuttle for good", async () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    adapter.seek(20);
+    act(() => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyJ", key: "j" })));
+    await act(() => new Promise((r) => setTimeout(r, 100)));
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    const stoppedAt = adapter.getTime();
+    await act(() => new Promise((r) => setTimeout(r, 200)));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(adapter.getTime()).toBe(stoppedAt);
+    expect(usePlayerStore.getState().currentTime).toBe(stoppedAt);
+    act(() => root.unmount());
+  });
+
+  it("does not carry the shuttle speed past the pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    attachIframeWindow(api, makeAdapterWindow().win);
+    const pressL = () =>
+      act(
+        () => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyL", key: "l" })),
+      );
+    pressL();
+    pressL();
+    expect(usePlayerStore.getState().playbackRate).toBe(2);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    pressL();
+
+    expect(usePlayerStore.getState().playbackRate).toBe(1);
+    act(() => root.unmount());
+  });
+});

package/src/player/hooks/useTimelinePlayer.play.test.ts

@@ -95,6 +95,42 @@ it.each([30, 0])(
   },
 );
 
+it("settles a load whose runtime learns its duration after its only readiness post", async () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  let duration = 0;
+  const { adapter, win } = makeAdapterWindow();
+  adapter.getDuration = () => duration;
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  expect(adapter.pause).not.toHaveBeenCalled();
+
+  // No further post comes: a paused low-power preview checks in only once a second.
+  duration = 30;
+  await act(() => new Promise((resolve) => requestAnimationFrame(() => resolve(undefined))));
+  expect(adapter.pause).toHaveBeenCalled();
+  act(() => root.unmount());
+});
+
+it.each(["unmounts", "resets"])("stops retrying a pending load once the player %s", async (how) => {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  let lookups = 0;
+  adapter.getDuration = () => (lookups++, 0);
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  act(() => (how === "resets" ? api.resetPlayer() : root.unmount()));
+  const atStop = lookups;
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  expect(lookups).toBe(atStop);
+  if (how === "resets") act(() => root.unmount());
+});
+
 it("does not let the blank page's load step enable Play for the preview that replaces it", async () => {
   const { api, root } = renderTimelinePlayerHarness();
   // The iframe's first load is about:blank, before the runtime exists; its load step waits for runtime messages.

package/src/player/hooks/useTimelinePlayer.ts

@@ -362,21 +362,25 @@ export function useTimelinePlayer({
       seek,
     });
 
-  const { processTimelineMessageRef, enrichMissingCompositionsRef, onIframeLoad } =
-    useTimelineSyncCallbacks({
-      iframeRef,
-      probeIntervalRef,
-      pendingSeekRef,
-      isRefreshingRef,
-      getAdapter,
-      syncTimelineElements,
-      setDuration,
-      setCurrentTime,
-      requestTimelineReady,
-      setIsPlaying,
-      attachIframeShortcutListeners,
-      applyPreviewAudioState,
-    });
+  const {
+    processTimelineMessageRef,
+    enrichMissingCompositionsRef,
+    onIframeLoad,
+    cancelPendingLoad,
+  } = useTimelineSyncCallbacks({
+    iframeRef,
+    probeIntervalRef,
+    pendingSeekRef,
+    isRefreshingRef,
+    getAdapter,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    attachIframeShortcutListeners,
+    applyPreviewAudioState,
+  });
 
   // Full-reload edits load behind a hidden shadow iframe (useShadowPreviewReload.ts).
   const {
@@ -452,8 +456,8 @@ export function useTimelinePlayer({
     applyPreviewVariablesToUrl(url);
     beginShadowReload(url.toString());
   }, [saveSeekPosition, getAdapter, beginShadowReload]);
-  const getAdapterRef = useRef(getAdapter);
-  getAdapterRef.current = getAdapter;
+  const pauseRef = useRef(pause);
+  pauseRef.current = pause;
 
   useMountEffect(() => {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
@@ -469,14 +473,7 @@ export function useTimelinePlayer({
     });
 
     const handleVisibilityChange = () => {
-      if (document.hidden && usePlayerStore.getState().isPlaying) {
-        const adapter = getAdapterRef.current?.();
-        if (adapter) {
-          adapter.pause();
-          setIsPlaying(false);
-          stopRAFLoop();
-        }
-      }
+      if (document.hidden && usePlayerStore.getState().isPlaying) pauseRef.current();
     };
 
     window.addEventListener("keydown", handleWindowKeyDown, true);
@@ -494,16 +491,16 @@ export function useTimelinePlayer({
       stopReverseLoop();
       stopScrubPreviewAudio();
       releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      cancelPendingLoad();
     };
   });
 
   const resetPlayer = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+    cancelPendingLoad();
     usePlayerStore.getState().reset();
-  }, [stopRAFLoop, stopReverseLoop]);
+  }, [stopRAFLoop, stopReverseLoop, cancelPendingLoad]);
 
   useEffect(() => {
     return usePlayerStore.subscribe((state, prev) => {

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -244,7 +244,7 @@ export function useTimelineSyncCallbacks({
       adapter.pause();
       const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
       const commit = () => {
-        // Keep non-React listeners such as the capture link and time display in sync
+        // Keep non-React listeners such as the time display in sync
         // with the initial adapter seek on iframe load.
         liveTime.notify(startTime);
         syncAdapterDuration(adapter, setDuration);
@@ -309,28 +309,36 @@ export function useTimelineSyncCallbacks({
       // Listen for those instead of polling.
       const iframe = iframeRef.current;
       let settled = false;
+      let retryFrame = 0;
+      const stopWaiting = () => {
+        window.removeEventListener("message", onMessage);
+        cancelAnimationFrame(retryFrame);
+      };
 
       const trySettle = () => {
         if (settled) return;
         if (initializeAdapter(context)) {
           settled = true;
-          window.removeEventListener("message", onMessage);
+          stopWaiting();
           if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+          return;
         }
+        cancelAnimationFrame(retryFrame);
+        retryFrame = requestAnimationFrame(trySettle);
       };
 
       const onMessage = (e: MessageEvent) => {
         if (isPreviewReadinessMessage(e, iframe)) trySettle();
       };
       window.addEventListener("message", onMessage);
-      stopWaitingRef.current = () => window.removeEventListener("message", onMessage);
+      stopWaitingRef.current = stopWaiting;
 
       // Safety net: if no message arrives within 5s, try one last time then give up.
       probeIntervalRef.current = setTimeout(() => {
         if (!settled) {
           trySettle();
         }
-        window.removeEventListener("message", onMessage);
+        stopWaiting();
         if (!settled) onLoadGiveUp?.(context);
         revealIframe(iframeRef.current);
       }, 5000) as unknown as ReturnType<typeof setInterval>;

package/src/player/lib/automationStoreSync.ts

@@ -6,8 +6,9 @@
  * an envelope afterwards writes to the preview document and the source file, and the
  * store would go on holding the value it was born with until a reload.
  *
- * One reader, called from the two places a change lands: the resync every dom-edit
- * attribute commit already runs, and the soft restore an undo or redo applies. It
+ * One reader, called where a change lands: the resync every dom-edit attribute
+ * commit runs, and an undo or redo's soft restore (timeline saves record their own
+ * value through syncStoredElementAttribute below). It
  * reads the preview rather than being told, because those callers know a file
  * changed, not which attribute — and because three separate writers shipped without
  * remembering to sync, which is what a single sink prevents.
@@ -17,7 +18,7 @@ import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { groupInfoFor } from "./timelineGroupInfo";
-import { previewElementFinder } from "./timelineElementHelpers";
+import { getTimelineElementIdentity, previewElementFinder } from "./timelineElementHelpers";
 
 /**
  * Re-read every element's automation and FX-chain attributes from the preview
@@ -72,3 +73,29 @@ export function syncStoredAutomationFromPreview(doc: Document | null | undefined
     return changed ? { elements } : {};
   });
 }
+
+const STORED_FIELD: Record<string, "automation" | "fxChain"> = {
+  [HF_AUDIO_AUTOMATION_ATTR]: "automation",
+  [HF_AUDIO_FX_ATTR]: "fxChain",
+};
+
+/** Record a saved automation or FX-chain value on one element's stored copy. */
+export function syncStoredElementAttribute(
+  target: TimelineElement,
+  attr: string,
+  value: string | null,
+): void {
+  const field = STORED_FIELD[attr];
+  if (!field) return;
+  const key = getTimelineElementIdentity(target);
+  const next = value ?? undefined;
+  usePlayerStore.setState((state) => {
+    let changed = false;
+    const elements = state.elements.map((element) => {
+      if (getTimelineElementIdentity(element) !== key || element[field] === next) return element;
+      changed = true;
+      return { ...element, [field]: next };
+    });
+    return changed ? { elements } : {};
+  });
+}

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

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { decodeImageThumbnail } from "./thumbnailImageDecoder";
+
+class TestImage {
+  static instances: TestImage[] = [];
+  naturalWidth = 180;
+  naturalHeight = 135;
+  src = "";
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  constructor() {
+    TestImage.instances.push(this);
+  }
+}
+beforeEach(() => {
+  TestImage.instances = [];
+  vi.stubGlobal("Image", TestImage);
+});
+afterEach(() => vi.unstubAllGlobals());
+function latest() {
+  const image = TestImage.instances.at(-1);
+  if (!image) throw new Error("missing image");
+  return image;
+}
+
+describe("timeline image thumbnails", () => {
+  it("requests a bounded local JPEG and accounts for its actual decoded dimensions", async () => {
+    const result = decodeImageThumbnail(
+      "/api/projects/p/preview/photo.jpg?v=2",
+      new AbortController().signal,
+    );
+    expect(latest().src).toBe(
+      new URL("/api/projects/p/image-thumbnail/photo.jpg?v=2", location.href).href,
+    );
+    latest().onload?.();
+    expect(await result).toEqual({
+      value: {
+        kind: "image",
+        url: new URL("/api/projects/p/image-thumbnail/photo.jpg?v=2", location.href).href,
+        aspect: 4 / 3,
+      },
+      weight: 180 * 135 * 4,
+    });
+    expect(latest().src).toBe("");
+  });
+  it.each([
+    "https://remote.test/photo.jpg",
+    "/api/projects/p/preview/image.png",
+    "/api/projects/p/preview/image.gif",
+    "/api/projects/p/preview/image.webp",
+    "/api/projects/p/preview/image.svg",
+    "/other/photo.jpg",
+  ])("preserves %s", async (source) => {
+    const result = decodeImageThumbnail(source, new AbortController().signal);
+    expect(latest().src).toBe(source);
+    latest().onload?.();
+    expect((await result).value).toMatchObject({ url: source });
+  });
+  it("falls back for an older server and accounts for original dimensions", async () => {
+    const result = decodeImageThumbnail(
+      "/api/projects/p/preview/photo.jpg",
+      new AbortController().signal,
+    );
+    latest().onerror?.();
+    await Promise.resolve();
+    expect(latest().src).toBe("/api/projects/p/preview/photo.jpg");
+    latest().naturalWidth = 2560;
+    latest().naturalHeight = 1920;
+    latest().onload?.();
+    expect((await result).weight).toBe(2560 * 1920 * 4);
+  });
+  it("does not retry a cancelled request", async () => {
+    const controller = new AbortController();
+    const result = decodeImageThumbnail("/api/projects/p/preview/photo.jpg", controller.signal);
+    controller.abort();
+    await expect(result).rejects.toMatchObject({ name: "AbortError" });
+    expect(TestImage.instances).toHaveLength(1);
+    expect(latest().src).toBe("");
+    expect(latest().onload).toBeNull();
+  });
+});

package/src/player/lib/thumbnailImageDecoder.ts

@@ -0,0 +1,73 @@
+import type { ThumbnailLoadedResult } from "./thumbnailScheduler";
+import { TIMELINE_VIEWPORT_BUDGETS } from "./timelineViewportBudgets";
+
+function thumbnailSource(source: string): string {
+  const url = new URL(source, window.location.href);
+  if (
+    url.origin !== window.location.origin ||
+    !/^\/api\/projects\/[^/]+\/preview\/.+\.jpe?g$/i.test(url.pathname)
+  )
+    return source;
+  url.pathname = url.pathname.replace(
+    /^(\/api\/projects\/[^/]+)\/preview\//,
+    "$1/image-thumbnail/",
+  );
+  return url.href;
+}
+
+function loadImage(source: string, signal: AbortSignal): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    const cleanup = () => {
+      image.onload = null;
+      image.onerror = null;
+      signal.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      image.src = "";
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    image.onload = () => {
+      cleanup();
+      resolve(image);
+    };
+    image.onerror = () => {
+      cleanup();
+      if (/\.svg($|\?)/i.test(source)) resolve(image);
+      else {
+        image.src = "";
+        reject(new Error("Image thumbnail failed to load"));
+      }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    image.src = source;
+  });
+}
+
+export async function decodeImageThumbnail(
+  source: string,
+  signal: AbortSignal,
+): Promise<ThumbnailLoadedResult> {
+  let url = thumbnailSource(source);
+  let image: HTMLImageElement;
+  try {
+    image = await loadImage(url, signal);
+  } catch (error) {
+    if (signal.aborted || url === source) throw error;
+    url = source;
+    image = await loadImage(source, signal);
+  }
+  try {
+    signal.throwIfAborted();
+    const width = image.naturalWidth || TIMELINE_VIEWPORT_BUDGETS.posterMaxPhysicalWidth;
+    const height = image.naturalHeight || TIMELINE_VIEWPORT_BUDGETS.posterMaxPhysicalHeight;
+    return { value: { kind: "image", url, aspect: width / height }, weight: width * height * 4 };
+  } finally {
+    image.src = "";
+  }
+}