@hyperframes/studio 0.8.205 → 0.8.207

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/assets/hyperframes-player-Cm5aBiKq.js +478 -0
  2. package/dist/assets/{index-dy6GQJn4.js → index-BF9YeBnC.js} +142 -142
  3. package/dist/assets/{index-C8hp9Y7c.js → index-BrqAmMRt.js} +1 -1
  4. package/dist/{chunk-Z5NKM57J.js → chunk-3EAFE522.js} +8 -4
  5. package/dist/{chunk-2YCKGJFD.js → chunk-HPIJDMWG.js} +5 -5
  6. package/dist/{chunk-T43DM7Q6.js → chunk-OGIOFEC7.js} +4 -2
  7. package/dist/{domEditingLayers-WMDSHU5P.js → domEditingLayers-7Z6J4UOK.js} +2 -2
  8. package/dist/index.d.ts +1 -0
  9. package/dist/index.html +1 -1
  10. package/dist/index.js +235 -127
  11. package/dist/player.js +2 -2
  12. package/package.json +8 -8
  13. package/src/components/MediaPreview.test.tsx +69 -0
  14. package/src/components/MediaPreview.tsx +10 -5
  15. package/src/components/editor/domEditLayerWalkCache.test.ts +48 -0
  16. package/src/components/editor/domEditLayerWalkCache.ts +6 -0
  17. package/src/components/editor/domEditingLayers.ts +3 -2
  18. package/src/components/sidebar/PromptPreviewModal.test.tsx +22 -0
  19. package/src/components/sidebar/PromptPreviewModal.tsx +1 -0
  20. package/src/hooks/timelineEditingHelpers.test.ts +59 -0
  21. package/src/hooks/timelineEditingHelpers.ts +4 -5
  22. package/src/hooks/useGestureRecording.ts +5 -3
  23. package/src/player/components/PlayerControls.tsx +5 -2
  24. package/src/player/components/ShortcutsPanel.tsx +4 -2
  25. package/src/player/components/Timeline.test.ts +12 -0
  26. package/src/player/components/TimelineProvider.tsx +1 -0
  27. package/src/player/components/TimelineRuler.tsx +4 -7
  28. package/src/player/components/TimelineRulerPart.tsx +1 -0
  29. package/src/player/components/timelineClipDragPreview.test.ts +10 -0
  30. package/src/player/components/timelineClipDragPreview.ts +4 -5
  31. package/src/player/components/timelineRulerGeometry.ts +14 -3
  32. package/src/player/components/useTimelineClipDrag.ts +5 -2
  33. package/src/player/components/useTimelineProviderState.tsx +2 -1
  34. package/src/player/components/useTimelineTicks.ts +4 -1
  35. package/src/player/hooks/previewMessageRouter.test.ts +34 -0
  36. package/src/player/hooks/previewMessageRouter.ts +14 -3
  37. package/src/player/hooks/usePlaybackKeyboard.test.ts +19 -0
  38. package/src/player/hooks/usePlaybackKeyboard.ts +5 -2
  39. package/src/player/hooks/useShadowPreviewReload.ts +4 -1
  40. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +21 -0
  41. package/src/player/lib/mediaFetch.test.ts +163 -0
  42. package/src/player/lib/mediaFetch.ts +98 -0
  43. package/src/player/lib/mediaProbe.test.ts +21 -1
  44. package/src/player/lib/mediaProbe.ts +4 -2
  45. package/src/player/lib/thumbnailVideoDecoder.test.ts +24 -1
  46. package/src/player/lib/thumbnailVideoDecoder.ts +3 -1
  47. package/src/player/lib/time.test.ts +13 -13
  48. package/src/player/lib/time.ts +4 -4
  49. package/src/utils/linkedClipPreferences.ts +2 -0
  50. package/src/utils/sourceScopedSelectorIndex.ts +5 -2
  51. package/dist/assets/hyperframes-player-DzdSmJdB.js +0 -478
@@ -31,7 +31,7 @@ import type {
31
31
  } from "./timelineClipDragTypes";
32
32
  import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
33
33
  import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
34
- import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
34
+ import { isLinkedSelectionOn, useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
35
35
  import { useTimelineClipCapabilities } from "./timelineReadOnly";
36
36
  import { timelineClipFocusId } from "./timelineNavigationIdentity";
37
37
  import {
@@ -184,7 +184,10 @@ export function useTimelineClipDrag({
184
184
  // The ruler's line spacing at the current zoom; 0 with the magnet off, like the targets.
185
185
  const snapGridStep = useCallback(() => {
186
186
  if (!snapContextRef.current.enabled) return 0;
187
- const frameRate = rulerFrameRate(usePlayerStore.getState().timeDisplayMode);
187
+ const frameRate = rulerFrameRate(
188
+ usePlayerStore.getState().timeDisplayMode,
189
+ useLinkedClipPreferences.getState().compositionFps,
190
+ );
188
191
  return getTimelineGridStep(durationRef.current, ppsRef.current, frameRate);
189
192
  }, [durationRef, ppsRef]);
190
193
 
@@ -444,7 +444,7 @@ export function useTimelineProviderState({
444
444
  dragActive: draggedClip?.started === true || resizingClip != null,
445
445
  displayDuration,
446
446
  });
447
- const { major, minor, majorTickInterval } = useTimelineTicks(
447
+ const { major, minor, majorTickInterval, frameRate } = useTimelineTicks(
448
448
  displayDuration,
449
449
  pps,
450
450
  timeDisplayMode,
@@ -460,6 +460,7 @@ export function useTimelineProviderState({
460
460
  totalH: displayLayout.totalH,
461
461
  effectiveDuration,
462
462
  majorTickInterval,
463
+ tickFrameRate: frameRate,
463
464
  rangeSelection,
464
465
  marqueeRect,
465
466
  laneGapStrips,
@@ -1,5 +1,6 @@
1
1
  import { useMemo } from "react";
2
2
  import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
3
+ import { useCompositionFps } from "../../utils/linkedClipPreferences";
3
4
  import type { TimelineTimeRange } from "../lib/timelineClipIndex";
4
5
  import {
5
6
  generateTicks,
@@ -13,13 +14,15 @@ export function useTimelineTicks(
13
14
  timeDisplayMode: TimelineTimeDisplayMode,
14
15
  renderTimeRange?: TimelineTimeRange,
15
16
  ) {
16
- const frameRate = rulerFrameRate(timeDisplayMode);
17
+ const compositionFps = useCompositionFps();
18
+ const frameRate = rulerFrameRate(timeDisplayMode, compositionFps);
17
19
  const ticks = useMemo(
18
20
  () => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
19
21
  [duration, frameRate, pixelsPerSecond, renderTimeRange],
20
22
  );
21
23
  return {
22
24
  ...ticks,
25
+ frameRate,
23
26
  majorTickInterval: getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate),
24
27
  };
25
28
  }
@@ -23,6 +23,40 @@ describe("preview state messages", () => {
23
23
  });
24
24
  });
25
25
 
26
+ describe("preview state messages while a scrub posts them", () => {
27
+ it("re-reads the preview for missing compositions at most every 500 ms", () => {
28
+ vi.useFakeTimers();
29
+ try {
30
+ vi.setSystemTime(10_000);
31
+ const enrich = vi.fn();
32
+ const handle = createPreviewMessageHandler({
33
+ iframeRef: { current: null },
34
+ processTimelineMessageRef: { current: vi.fn() },
35
+ enrichMissingCompositionsRef: { current: enrich },
36
+ lastTimelineMessageRef: { current: 0 },
37
+ getAdapter: () => null,
38
+ syncTimelineElements: vi.fn(),
39
+ });
40
+ const state = () =>
41
+ handle(
42
+ new MessageEvent("message", {
43
+ data: { source: "hf-preview", type: "state", isPlaying: false },
44
+ }),
45
+ );
46
+ state();
47
+ vi.advanceTimersByTime(100);
48
+ state();
49
+ state();
50
+ expect(enrich).toHaveBeenCalledTimes(1);
51
+ vi.advanceTimersByTime(500);
52
+ state();
53
+ expect(enrich).toHaveBeenCalledTimes(2);
54
+ } finally {
55
+ vi.useRealTimers();
56
+ }
57
+ });
58
+ });
59
+
26
60
  describe("preview quality messages", () => {
27
61
  function routeMessage(data: unknown, frame?: { postMessage: (message: unknown) => void }) {
28
62
  const iframe = frame ? ({ contentWindow: frame } as unknown as HTMLIFrameElement) : null;
@@ -69,15 +69,24 @@ function acceptedPreviewMessage(
69
69
  return acceptStudioRuntimeMessage(data) ? data : null;
70
70
  }
71
71
 
72
+ /** Whether enrichment is due: no timeline message and no enrichment of ours for 500 ms. Marks it run. */
73
+ function enrichDue(lastTimelineMessage: number, enriched: { at: number }): boolean {
74
+ const now = Date.now();
75
+ if (now - lastTimelineMessage <= 500 || now - enriched.at <= 500) return false;
76
+ enriched.at = now;
77
+ return true;
78
+ }
79
+
72
80
  /**
73
81
  * A `state` tick doubles as a recovery hook: if the store still has no
74
82
  * elements, read the manifest straight off the iframe, and if no `timeline`
75
- * message has arrived recently, re-run enrichment.
83
+ * message has arrived recently, re-run enrichment (at most every 500 ms: it queries the whole document).
76
84
  */
77
85
  function handleStateMessage(
78
86
  deps: PreviewMessageRouterDeps,
79
87
  iframe: HTMLIFrameElement | null,
80
88
  playingHoldsClipListPosts: boolean,
89
+ enriched: { at: number },
81
90
  ): void {
82
91
  try {
83
92
  if (usePlayerStore.getState().elements.length === 0) {
@@ -86,7 +95,7 @@ function handleStateMessage(
86
95
  deps.processTimelineMessageRef.current(manifest);
87
96
  }
88
97
  }
89
- if (!playingHoldsClipListPosts && Date.now() - deps.lastTimelineMessageRef.current > 500) {
98
+ if (!playingHoldsClipListPosts && enrichDue(deps.lastTimelineMessageRef.current, enriched)) {
90
99
  deps.enrichMissingCompositionsRef.current();
91
100
  }
92
101
  } catch {}
@@ -135,11 +144,13 @@ function applyStoreReport(data: PreviewMessage): boolean {
135
144
  export function createPreviewMessageHandler(
136
145
  deps: PreviewMessageRouterDeps,
137
146
  ): (e: MessageEvent) => void {
147
+ const enriched = { at: 0 };
138
148
  return (e: MessageEvent) => {
139
149
  const iframe = deps.iframeRef.current;
140
150
  const data = acceptedPreviewMessage(e, iframe);
141
151
  if (!data) return;
142
- if (data.type === "state") return handleStateMessage(deps, iframe, data.isPlaying === true);
152
+ if (data.type === "state")
153
+ return handleStateMessage(deps, iframe, data.isPlaying === true, enriched);
143
154
  if (applyStoreReport(data)) return;
144
155
  if (data.type === "ready") {
145
156
  const level = usePlayerStore.getState().previewQuality;
@@ -6,12 +6,14 @@ import { createRoot } from "react-dom/client";
6
6
  import { afterEach, describe, expect, it, vi } from "vitest";
7
7
  import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
8
8
  import { usePlayerStore } from "../store/playerStore";
9
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
9
10
 
10
11
  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
11
12
 
12
13
  afterEach(() => {
13
14
  document.body.innerHTML = "";
14
15
  usePlayerStore.getState().reset();
16
+ useLinkedClipPreferences.getState().setCompositionFps(30);
15
17
  });
16
18
 
17
19
  interface Spies {
@@ -304,3 +306,20 @@ describe("usePlaybackKeyboard — a focused native player owns its keys", () =>
304
306
  expect(event.defaultPrevented).toBe(true);
305
307
  });
306
308
  });
309
+
310
+ describe("usePlaybackKeyboard — frame step", () => {
311
+ it.each([
312
+ [25, 3],
313
+ [30_000 / 1_001, 3],
314
+ ])("ArrowRight at %s fps steps one frame of the composition", (fps, frame) => {
315
+ const { dispatch, spies } = setupHook();
316
+ useLinkedClipPreferences.getState().setCompositionFps(fps);
317
+ usePlayerStore.setState({ currentTime: frame / fps });
318
+
319
+ act(() => {
320
+ dispatch(keydown({ code: "ArrowRight", key: "ArrowRight" }));
321
+ });
322
+
323
+ expect(spies.seek).toHaveBeenCalledWith((frame + 1) / fps);
324
+ });
325
+ });
@@ -11,7 +11,8 @@ import { useCaptionStore } from "../../captions/store";
11
11
  import { shouldIgnorePlaybackShortcutEvent, SHUTTLE_SPEEDS } from "../lib/playbackShortcuts";
12
12
  import { canvasNudgeKeysClaimed } from "../../utils/canvasNudgeGate";
13
13
  import { usePlayerStore } from "../store/playerStore";
14
- import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
14
+ import { stepFrameTime } from "../lib/time";
15
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
15
16
  import type { PlaybackAdapter } from "../lib/playbackTypes";
16
17
 
17
18
  interface UsePlaybackKeyboardParams {
@@ -53,7 +54,9 @@ export function usePlaybackKeyboard({
53
54
  (deltaFrames: number) => {
54
55
  const adapter = getAdapter();
55
56
  const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
56
- seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
57
+ seek(
58
+ stepFrameTime(currentTime, deltaFrames, useLinkedClipPreferences.getState().compositionFps),
59
+ );
57
60
  },
58
61
  [getAdapter, seek],
59
62
  );
@@ -8,6 +8,7 @@ import {
8
8
  isStudioManualEditGestureLiveIn,
9
9
  studioManualEditSavesIn,
10
10
  } from "../../components/editor/manualEditsDom";
11
+ import { refusedPreviewStatus } from "@hyperframes/core/studio-preview-mark";
11
12
  import { logReload } from "../../utils/reloadDebug";
12
13
  import {
13
14
  useTimelineSyncCallbacks,
@@ -131,7 +132,9 @@ export function useShadowPreviewReload({
131
132
  setPreviewReloading(false);
132
133
  const message = `The preview did not reload (${cause}). It was still waiting for ${waitingFor}. The previous preview is still showing.`;
133
134
  logReload("shadow-failed", { cause, waitingFor });
134
- console.error(`[studio] ${message}`);
135
+ const refused = refusedPreviewStatus(cause);
136
+ const pageMissingNow = refused !== null && refused < 500;
137
+ (pageMissingNow ? console.warn : console.error)(`[studio] ${message}`);
135
138
  onReloadFailedRef.current?.(message);
136
139
  },
137
140
  [stopPendingShadow, isRefreshingRef, pendingSeekRef],
@@ -5,6 +5,7 @@ import React, { act } from "react";
5
5
  import { createRoot } from "react-dom/client";
6
6
  import { afterEach, describe, expect, it, vi } from "vitest";
7
7
  import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
8
+ import { refusedPreviewMessage } from "@hyperframes/core/studio-preview-mark";
8
9
  import { usePlayerStore } from "../store/playerStore";
9
10
  import { isPreviewChanging } from "../previewReloading";
10
11
  import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
@@ -639,6 +640,26 @@ describe("shadow reload readiness and failure", () => {
639
640
  unmount(root);
640
641
  });
641
642
 
643
+ // An agent's edit moves the page away for a few saves: each reload is refused until it is back.
644
+ it.each([
645
+ [404, "warn"],
646
+ [500, "error"],
647
+ ] as const)("reports a reload the server refused with %i as a console %s", (status, level) => {
648
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
649
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
650
+ const onPreviewReloadFailed = vi.fn();
651
+ const { getApi, live, gen, root } = beginReload({ onPreviewReloadFailed });
652
+
653
+ act(() => getApi().onShadowError(gen, refusedPreviewMessage(status)));
654
+
655
+ expect(getApi().iframeRef.current).toBe(live);
656
+ expect(onPreviewReloadFailed).toHaveBeenCalledOnce();
657
+ const said = (spy: typeof warn) =>
658
+ spy.mock.calls.some(([text]) => String(text).includes(`(HTTP ${status})`));
659
+ expect([said(warn), said(error)]).toEqual([level === "warn", level === "error"]);
660
+ unmount(root);
661
+ });
662
+
642
663
  it("runs no load side effects for a superseded shadow", () => {
643
664
  const { getApi, gen, root } = beginReload();
644
665
  usePlayerStore.getState().setCurrentTime(7);
@@ -0,0 +1,163 @@
1
+ import { afterEach, describe, expect, it, vi } from "vitest";
2
+ import { MediaFetchError, mediaUrlSourceOptions, reportMediaFetchFailure } from "./mediaFetch";
3
+
4
+ const URL_WITH_PATH = "http://127.0.0.1:5190/api/projects/demo/preview/clips/take-1.mp4";
5
+
6
+ afterEach(() => {
7
+ vi.unstubAllGlobals();
8
+ vi.restoreAllMocks();
9
+ });
10
+
11
+ describe("mediaUrlSourceOptions", () => {
12
+ it("turns a network failure into a typed error without the URL", async () => {
13
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("Failed to fetch")));
14
+ const { fetchFn } = mediaUrlSourceOptions("probe");
15
+
16
+ const error = await fetchFn(URL_WITH_PATH).catch((e: unknown) => e);
17
+
18
+ expect(error).toBeInstanceOf(MediaFetchError);
19
+ expect(error).toMatchObject({ reader: "probe", status: null, code: "TypeError" });
20
+ expect(String((error as Error).message)).not.toContain("take-1");
21
+ });
22
+
23
+ it("names the network code when the failure carries one", async () => {
24
+ const failure = Object.assign(new TypeError("fetch failed"), { cause: { code: "EBUSY" } });
25
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(failure));
26
+
27
+ const error = await mediaUrlSourceOptions("thumbnail")
28
+ .fetchFn(URL_WITH_PATH)
29
+ .catch((e) => e);
30
+
31
+ expect(error).toMatchObject({ reader: "thumbnail", code: "EBUSY" });
32
+ });
33
+
34
+ it("turns an HTTP error status into a typed error", async () => {
35
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 403 })));
36
+
37
+ const error = await mediaUrlSourceOptions("probe")
38
+ .fetchFn(URL_WITH_PATH)
39
+ .catch((e) => e);
40
+
41
+ expect(error).toMatchObject({
42
+ status: 403,
43
+ message: "probe range fetch failed: HTTP 403 after 0 retries",
44
+ });
45
+ });
46
+
47
+ it("lets a cancellation through untouched", async () => {
48
+ const abort = new DOMException("Aborted", "AbortError");
49
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(abort));
50
+
51
+ await expect(mediaUrlSourceOptions("probe").fetchFn(URL_WITH_PATH)).rejects.toBe(abort);
52
+ });
53
+
54
+ it("retries a network failure twice, then gives up and records the retries", () => {
55
+ const { getRetryDelay } = mediaUrlSourceOptions("probe");
56
+ const failure = new MediaFetchError("probe", null, "TypeError");
57
+
58
+ expect([1, 2, 3].map((attempt) => getRetryDelay(attempt, failure))).toEqual([0.5, 1, null]);
59
+ expect(failure).toMatchObject({
60
+ retries: 2,
61
+ message: "probe range fetch failed: network TypeError after 2 retries",
62
+ });
63
+ });
64
+
65
+ it("gives up on a body that breaks mid-read with the typed error, through a real mediabunny read", async () => {
66
+ const brokenBody = () =>
67
+ new Response(
68
+ new ReadableStream({
69
+ pull: (controller) => controller.error(new TypeError("network error")),
70
+ }),
71
+ {
72
+ status: 206,
73
+ headers: { "Content-Range": "bytes 0-65535/1000000", "Content-Length": "65536" },
74
+ },
75
+ );
76
+ vi.stubGlobal(
77
+ "fetch",
78
+ vi.fn(async () => brokenBody()),
79
+ );
80
+ vi.useFakeTimers();
81
+ const mb = await import("mediabunny");
82
+ const runnerListeners = process.listeners("unhandledRejection");
83
+ const unhandled: unknown[] = [];
84
+ process.removeAllListeners("unhandledRejection");
85
+ process.on("unhandledRejection", (reason) => unhandled.push(reason));
86
+ try {
87
+ const input = new mb.Input({
88
+ source: new mb.UrlSource(URL_WITH_PATH, mediaUrlSourceOptions("thumbnail")),
89
+ formats: mb.ALL_FORMATS,
90
+ });
91
+ const read = input.getDurationFromMetadata().catch((e: unknown) => e);
92
+ await vi.runAllTimersAsync();
93
+ const error = await read;
94
+ input.dispose();
95
+ await vi.runAllTimersAsync();
96
+
97
+ expect(error).toMatchObject({
98
+ name: "MediaFetchError",
99
+ message: "thumbnail range fetch failed: network TypeError after 2 retries",
100
+ });
101
+ for (const reason of unhandled) expect(reason).toBeInstanceOf(MediaFetchError);
102
+ } finally {
103
+ vi.useRealTimers();
104
+ process.removeAllListeners("unhandledRejection");
105
+ for (const listener of runnerListeners) process.on("unhandledRejection", listener);
106
+ }
107
+ });
108
+
109
+ it("counts mid-stream read failures, which always arrive as attempt 1", () => {
110
+ const { getRetryDelay } = mediaUrlSourceOptions("thumbnail");
111
+ const readError = new TypeError("network error");
112
+
113
+ expect([1, 1, 1].map((attempt) => getRetryDelay(attempt, readError))).toEqual([0.5, 1, null]);
114
+ });
115
+
116
+ it("does not retry a client error status", () => {
117
+ const failure = new MediaFetchError("probe", 404, null);
118
+
119
+ expect(mediaUrlSourceOptions("probe").getRetryDelay(1, failure)).toBeNull();
120
+ expect(failure.retries).toBe(0);
121
+ });
122
+
123
+ // mediabunny rethrows a failed read-ahead nobody awaits "so it doesn't get swallowed": that copy is typed too.
124
+ it("fails a real mediabunny read, and its unawaited read-ahead, with the typed error", async () => {
125
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 404 })));
126
+ const mb = await import("mediabunny");
127
+ const runnerListeners = process.listeners("unhandledRejection");
128
+ const unhandled: unknown[] = [];
129
+ process.removeAllListeners("unhandledRejection");
130
+ process.on("unhandledRejection", (reason) => unhandled.push(reason));
131
+ try {
132
+ const input = new mb.Input({
133
+ source: new mb.UrlSource(URL_WITH_PATH, mediaUrlSourceOptions("probe")),
134
+ formats: mb.ALL_FORMATS,
135
+ });
136
+ const error = await input.getDurationFromMetadata().catch((e: unknown) => e);
137
+ input.dispose();
138
+ await new Promise(setImmediate);
139
+
140
+ expect(error).toMatchObject({ name: "MediaFetchError", status: 404, retries: 0 });
141
+ expect(unhandled.length).toBeGreaterThan(0);
142
+ for (const reason of unhandled) expect(reason).toBeInstanceOf(MediaFetchError);
143
+ } finally {
144
+ process.removeAllListeners("unhandledRejection");
145
+ for (const listener of runnerListeners) process.on("unhandledRejection", listener);
146
+ }
147
+ });
148
+ });
149
+
150
+ describe("reportMediaFetchFailure", () => {
151
+ it("writes one scrubbed line for a typed failure and nothing for anything else", () => {
152
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
153
+ const failure = new MediaFetchError("thumbnail", null, "TypeError");
154
+ failure.setRetries(2);
155
+
156
+ reportMediaFetchFailure(failure);
157
+ reportMediaFetchFailure(new Error("Video source has no decodable video track"));
158
+
159
+ expect(warn.mock.calls).toEqual([
160
+ ["[Studio] thumbnail range fetch failed: network TypeError after 2 retries"],
161
+ ]);
162
+ });
163
+ });
@@ -0,0 +1,98 @@
1
+ export type MediaReader = "probe" | "thumbnail";
2
+
3
+ const describe = (
4
+ reader: MediaReader,
5
+ status: number | null,
6
+ code: string | null,
7
+ retries: number,
8
+ ) =>
9
+ `${reader} range fetch failed: ${status === null ? `network ${code}` : `HTTP ${status}`} after ${retries} retries`;
10
+
11
+ /** A media range fetch that gave up: which reader, the HTTP status or network code, and the retries. Never the URL. */
12
+ export class MediaFetchError extends Error {
13
+ override readonly name = "MediaFetchError";
14
+ retries = 0;
15
+
16
+ constructor(
17
+ readonly reader: MediaReader,
18
+ readonly status: number | null,
19
+ readonly code: string | null,
20
+ ) {
21
+ super(describe(reader, status, code, 0));
22
+ }
23
+
24
+ setRetries(retries: number): void {
25
+ this.retries = retries;
26
+ this.message = describe(this.reader, this.status, this.code, retries);
27
+ }
28
+ }
29
+
30
+ const MAX_RETRIES = 2;
31
+
32
+ const isAbort = (error: unknown) => (error as { name?: unknown } | null)?.name === "AbortError";
33
+
34
+ function networkCode(error: unknown): string {
35
+ const cause = (error as { cause?: { code?: unknown } } | null)?.cause;
36
+ if (typeof cause?.code === "string") return cause.code;
37
+ const name = (error as { name?: unknown } | null)?.name;
38
+ return typeof name === "string" ? name : "unknown";
39
+ }
40
+
41
+ const typedFailure = (reader: MediaReader, error: unknown) =>
42
+ isAbort(error) ? error : new MediaFetchError(reader, null, networkCode(error));
43
+
44
+ /** The body, failing a broken read with a MediaFetchError: mediabunny rethrows a body error as-is. */
45
+ function typedBody(
46
+ reader: MediaReader,
47
+ body: ReadableStream<Uint8Array>,
48
+ ): ReadableStream<Uint8Array> {
49
+ const source = body.getReader();
50
+ return new ReadableStream<Uint8Array>({
51
+ async pull(controller) {
52
+ try {
53
+ const { done, value } = await source.read();
54
+ if (done) controller.close();
55
+ else controller.enqueue(value);
56
+ } catch (error) {
57
+ controller.error(typedFailure(reader, error));
58
+ }
59
+ },
60
+ cancel: (reason) => source.cancel(reason),
61
+ });
62
+ }
63
+
64
+ /**
65
+ * Options for a mediabunny `UrlSource`. Its default retries a same-origin network failure
66
+ * forever and logs a bare `TypeError` each time; these retry twice and fail with a MediaFetchError.
67
+ */
68
+ export function mediaUrlSourceOptions(reader: MediaReader) {
69
+ let failures = 0;
70
+ const fetchFn = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
71
+ let response: Response;
72
+ try {
73
+ // oxlint-disable-next-line no-restricted-globals -- a media read, on the media's sockets like mediabunny's own
74
+ response = await fetch(input, init);
75
+ } catch (error) {
76
+ throw typedFailure(reader, error);
77
+ }
78
+ if (!response.ok) throw new MediaFetchError(reader, response.status, null);
79
+ if (!response.body) return response;
80
+ const { status, statusText, headers } = response;
81
+ return new Response(typedBody(reader, response.body), { status, statusText, headers });
82
+ };
83
+ // Counted per source: mediabunny passes 1 for every failed mid-stream read.
84
+ const getRetryDelay = (_previousAttempts: number, error: unknown): number | null => {
85
+ const clientError =
86
+ error instanceof MediaFetchError && error.status !== null && error.status < 500;
87
+ if (error instanceof MediaFetchError) error.setRetries(failures);
88
+ if (clientError || failures >= MAX_RETRIES) return null;
89
+ failures++;
90
+ return 0.5 * failures;
91
+ };
92
+ return { fetchFn, getRetryDelay };
93
+ }
94
+
95
+ export function reportMediaFetchFailure(error: unknown): void {
96
+ if (!(error instanceof MediaFetchError)) return;
97
+ console.warn(`[Studio] ${error.message}`);
98
+ }
@@ -8,16 +8,22 @@ import {
8
8
  probeMissingSourceDurations,
9
9
  resetMediaProbeRegistry,
10
10
  } from "./mediaProbe";
11
+ import { MediaFetchError } from "./mediaFetch";
11
12
 
12
13
  const dispose = vi.fn();
13
14
  const getDurationFromMetadata = vi.fn(async () => 5);
14
15
  const requestedSources: string[] = [];
16
+ const sourceRetryRules: string[] = [];
15
17
 
16
18
  vi.mock("mediabunny", () => ({
17
19
  ALL_FORMATS: {},
18
20
  UrlSource: class {
19
- constructor(readonly url: string) {
21
+ constructor(
22
+ readonly url: string,
23
+ readonly options?: { getRetryDelay?: unknown },
24
+ ) {
20
25
  requestedSources.push(url);
26
+ sourceRetryRules.push(typeof options?.getRetryDelay);
21
27
  }
22
28
  },
23
29
  Input: class {
@@ -32,6 +38,7 @@ beforeEach(() => {
32
38
  resetMediaProbeRegistry();
33
39
  vi.clearAllMocks();
34
40
  requestedSources.length = 0;
41
+ sourceRetryRules.length = 0;
35
42
  getDurationFromMetadata.mockResolvedValue(5);
36
43
  });
37
44
 
@@ -40,6 +47,19 @@ afterEach(() => {
40
47
  });
41
48
 
42
49
  describe("media probe registry", () => {
50
+ it("reports a failed range fetch as one typed line and records the probe as failed", async () => {
51
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
52
+ const failure = new MediaFetchError("probe", 403, null);
53
+ getDurationFromMetadata.mockRejectedValue(failure);
54
+
55
+ await expect(probeMediaUrl("/locked.mp4")).resolves.toBeNull();
56
+ expect(sourceRetryRules).toEqual(["function"]);
57
+ expect(warn.mock.calls).toEqual([
58
+ ["[Studio] probe range fetch failed: HTTP 403 after 0 retries"],
59
+ ]);
60
+ warn.mockRestore();
61
+ });
62
+
43
63
  it("deduplicates and caches successful probes", async () => {
44
64
  const [first, second] = await Promise.all([
45
65
  probeMediaUrl("/video.mp4"),
@@ -1,5 +1,6 @@
1
1
  import { authoredSrcPath, resolveMediaPreviewUrl } from "../components/thumbnailUtils";
2
2
  import { TIMELINE_VIEWPORT_BUDGETS } from "./timelineViewportBudgets";
3
+ import { mediaUrlSourceOptions, reportMediaFetchFailure } from "./mediaFetch";
3
4
 
4
5
  export interface MediaProbeResult {
5
6
  duration: number;
@@ -55,7 +56,7 @@ async function probeOne(url: string): Promise<MediaProbeResult | null> {
55
56
  if (!mb) return null;
56
57
 
57
58
  const input = new mb.Input({
58
- source: new mb.UrlSource(url),
59
+ source: new mb.UrlSource(url, mediaUrlSourceOptions("probe")),
59
60
  formats: mb.ALL_FORMATS,
60
61
  });
61
62
  try {
@@ -73,7 +74,8 @@ async function probeOne(url: string): Promise<MediaProbeResult | null> {
73
74
  hasAudio: audioTracks.length > 0,
74
75
  };
75
76
  return result;
76
- } catch {
77
+ } catch (error) {
78
+ reportMediaFetchFailure(error);
77
79
  return null;
78
80
  } finally {
79
81
  input.dispose();
@@ -2,8 +2,10 @@
2
2
 
3
3
  import { beforeEach, describe, expect, it, vi } from "vitest";
4
4
  import { decodeVideoThumbnail, videoThumbnailTimestamps } from "./thumbnailVideoDecoder";
5
+ import { MediaFetchError } from "./mediaFetch";
5
6
 
6
7
  const dispose = vi.fn();
8
+ const sourceRetryRules: string[] = [];
7
9
  const canvasesAtTimestamps = vi.fn();
8
10
  const getKeyPacket = vi.fn(async (_time: number) => null as { timestamp: number } | null);
9
11
  const input = {
@@ -14,7 +16,12 @@ const input = {
14
16
  vi.mock("mediabunny", () => ({
15
17
  ALL_FORMATS: {},
16
18
  UrlSource: class {
17
- constructor(readonly url: string) {}
19
+ constructor(
20
+ readonly url: string,
21
+ readonly options?: { getRetryDelay?: unknown },
22
+ ) {
23
+ sourceRetryRules.push(typeof options?.getRetryDelay);
24
+ }
18
25
  },
19
26
  Input: class {
20
27
  getPrimaryVideoTrack = input.getPrimaryVideoTrack;
@@ -371,6 +378,22 @@ describe("decodeVideoThumbnail", () => {
371
378
  expect(URL.revokeObjectURL).toHaveBeenCalledTimes(5);
372
379
  });
373
380
 
381
+ it("reports a failed range fetch as one typed line and rethrows it", async () => {
382
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
383
+ sourceRetryRules.length = 0;
384
+ input.getPrimaryVideoTrack.mockRejectedValue(
385
+ new MediaFetchError("thumbnail", null, "TypeError"),
386
+ );
387
+ await expect(
388
+ decodeVideoThumbnail({ source: "/locked.mp4", frameCount: 1 }, new AbortController().signal),
389
+ ).rejects.toBeInstanceOf(MediaFetchError);
390
+ expect(sourceRetryRules).toEqual(["function"]);
391
+ expect(warn.mock.calls).toEqual([
392
+ ["[Studio] thumbnail range fetch failed: network TypeError after 0 retries"],
393
+ ]);
394
+ warn.mockRestore();
395
+ });
396
+
374
397
  it("releases input and degrades when the source has no video track", async () => {
375
398
  input.getPrimaryVideoTrack.mockResolvedValue(null);
376
399
  await expect(