@hyperframes/studio 0.8.229 → 0.8.231

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 (53) hide show
  1. package/dist/assets/{hyperframes-player-CtwXT8nW.js → hyperframes-player-ClW2l0Vl.js} +1 -1
  2. package/dist/assets/{index-CNO8BPjF.js → index-CGfRmZQd.js} +1 -1
  3. package/dist/assets/{index-CrRO-B3w.js → index-DxWNzvQJ.js} +187 -187
  4. package/dist/index.d.ts +73 -2
  5. package/dist/index.html +1 -1
  6. package/dist/index.js +2475 -2228
  7. package/package.json +8 -8
  8. package/src/captions/components/CaptionOverlay.tsx +7 -14
  9. package/src/captions/keyboard.test.ts +12 -1
  10. package/src/captions/keyboard.ts +8 -8
  11. package/src/components/EditorShell.tsx +2 -1
  12. package/src/components/TimelineToolPicker.tsx +6 -4
  13. package/src/components/TimelineToolbar.tsx +22 -18
  14. package/src/components/editor/GestureRecordControl.tsx +8 -3
  15. package/src/components/editor/InspectorHeaderActions.tsx +3 -1
  16. package/src/components/editor/PropertyPanelFlatFooter.tsx +3 -1
  17. package/src/components/editor/PropertyPanelFlatHeader.tsx +3 -1
  18. package/src/components/editor/SnapToolbar.tsx +11 -5
  19. package/src/components/editor/domEditNudge.test.ts +17 -1
  20. package/src/components/editor/domEditNudge.ts +16 -13
  21. package/src/components/editor/marqueeCommit.ts +2 -1
  22. package/src/hooks/appHotkeysDispatch.ts +104 -118
  23. package/src/hooks/linkShortcuts.test.ts +20 -0
  24. package/src/hooks/linkShortcuts.ts +11 -11
  25. package/src/hooks/useAppHotkeys.test.ts +201 -0
  26. package/src/hooks/useAppHotkeys.ts +1 -4
  27. package/src/hooks/useAutomationSelectionKeyboard.ts +7 -18
  28. package/src/hooks/useKeyframeKeyboard.ts +2 -3
  29. package/src/hooks/useTimelineDeleteOps.ts +2 -1
  30. package/src/index.ts +9 -1
  31. package/src/player/components/BeatStrip.tsx +2 -1
  32. package/src/player/components/ClipContextMenu.tsx +9 -6
  33. package/src/player/components/PlayerControls.tsx +3 -2
  34. package/src/player/components/ShortcutsPanel.tsx +3 -2
  35. package/src/player/components/TimelineClipFades.tsx +2 -1
  36. package/src/player/components/clipMenuLinkItems.tsx +5 -4
  37. package/src/player/components/studioCombo.test.ts +99 -0
  38. package/src/player/components/studioCombo.ts +108 -0
  39. package/src/player/components/studioShortcuts.test.tsx +124 -0
  40. package/src/player/components/studioShortcuts.ts +245 -96
  41. package/src/player/components/timelineClipDragGestureLifecycle.ts +2 -1
  42. package/src/player/components/timelineEditing.ts +2 -2
  43. package/src/player/components/useTimelineClipDrag.ts +2 -1
  44. package/src/player/components/useTimelineKeyboardActor.ts +7 -18
  45. package/src/player/components/useTimelineKeyframeHandlers.ts +2 -1
  46. package/src/player/components/useTimelineRangeSelection.ts +3 -2
  47. package/src/player/hooks/usePlaybackKeyboard.test.ts +164 -4
  48. package/src/player/hooks/usePlaybackKeyboard.ts +94 -102
  49. package/src/player/hooks/useShadowPreviewReload.ts +11 -4
  50. package/src/player/hooks/useShadowReloadRetry.ts +68 -0
  51. package/src/player/hooks/useTimelinePlayer.shadowRetry.test.ts +85 -0
  52. package/src/player/hooks/useTimelinePlayer.test.ts +19 -13
  53. package/src/player/lib/playbackShortcuts.ts +16 -7
@@ -3,14 +3,16 @@
3
3
 
4
4
  import React, { act, useEffect } from "react";
5
5
  import { createRoot } from "react-dom/client";
6
- import { afterEach, describe, expect, it, vi } from "vitest";
6
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
7
7
  import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
8
8
  import { usePlayerStore } from "../store/playerStore";
9
+ import { setStudioKeys } from "../components/studioShortcuts";
9
10
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
10
11
 
11
12
  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
12
13
 
13
14
  afterEach(() => {
15
+ setStudioKeys(null);
14
16
  document.body.innerHTML = "";
15
17
  usePlayerStore.getState().reset();
16
18
  useLinkedClipPreferences.getState().setCompositionFps(30);
@@ -74,11 +76,19 @@ function setupHook(): HookHandle {
74
76
  };
75
77
  }
76
78
 
77
- function keydown(init: { code: string; key: string; shiftKey?: boolean }): KeyboardEvent {
79
+ function keydown(init: {
80
+ code: string;
81
+ key: string;
82
+ shiftKey?: boolean;
83
+ metaKey?: boolean;
84
+ altKey?: boolean;
85
+ }): KeyboardEvent {
78
86
  return new KeyboardEvent("keydown", {
79
87
  code: init.code,
80
88
  key: init.key,
81
89
  shiftKey: init.shiftKey ?? false,
90
+ metaKey: init.metaKey ?? false,
91
+ altKey: init.altKey ?? false,
82
92
  cancelable: true,
83
93
  });
84
94
  }
@@ -197,7 +207,7 @@ describe("usePlaybackKeyboard — keyboard layout independence (#834)", () => {
197
207
  expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
198
208
  });
199
209
 
200
- it("Shift+A still seeks to the in-point while the razor is armed, since only plain A exits the razor", () => {
210
+ it("Shift+A is a different combo from A: it neither jumps to the in-point nor exits the razor", () => {
201
211
  const { dispatch, spies } = setupHook();
202
212
  usePlayerStore.setState({ inPoint: 1.5, activeTool: "razor" });
203
213
 
@@ -205,7 +215,8 @@ describe("usePlaybackKeyboard — keyboard layout independence (#834)", () => {
205
215
  dispatch(keydown({ code: "KeyA", key: "a", shiftKey: true }));
206
216
  });
207
217
 
208
- expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
218
+ expect(spies.seek).not.toHaveBeenCalled();
219
+ expect(usePlayerStore.getState().activeTool).toBe("razor");
209
220
  });
210
221
  });
211
222
 
@@ -323,3 +334,152 @@ describe("usePlaybackKeyboard — frame step", () => {
323
334
  expect(spies.seek).toHaveBeenCalledWith((frame + 1) / fps);
324
335
  });
325
336
  });
337
+
338
+ describe("usePlaybackKeyboard — keys the host can remap", () => {
339
+ beforeEach(() => usePlayerStore.setState({ audioMuted: false, loopEnabled: false }));
340
+
341
+ const press = (dispatch: HookHandle["dispatch"], key: string, shiftKey = false) =>
342
+ act(() => {
343
+ dispatch(keydown({ code: `Key${key.toUpperCase()}`, key, shiftKey }));
344
+ });
345
+
346
+ it("answers every default key", () => {
347
+ const { dispatch, release, spies } = setupHook();
348
+ press(dispatch, "m");
349
+ expect(usePlayerStore.getState().audioMuted).toBe(true);
350
+ press(dispatch, "l", true);
351
+ expect(usePlayerStore.getState().loopEnabled).toBe(true);
352
+ press(dispatch, "k");
353
+ expect(spies.pause).toHaveBeenCalledTimes(1);
354
+ act(() => release(keyup({ code: "KeyK", key: "k" })));
355
+ press(dispatch, "j");
356
+ expect(spies.playBackward).toHaveBeenCalledTimes(1);
357
+ press(dispatch, "i");
358
+ expect(usePlayerStore.getState().inPoint).not.toBeNull();
359
+ press(dispatch, "o");
360
+ expect(usePlayerStore.getState().outPoint).not.toBeNull();
361
+ press(dispatch, "a");
362
+ press(dispatch, "e");
363
+ expect(spies.seek).toHaveBeenCalledTimes(2);
364
+ });
365
+
366
+ it("a remapped key answers and the old one does not", () => {
367
+ setStudioKeys({ mute: "x", seekToIn: "u", shuttleForward: "y" });
368
+ const { dispatch, spies } = setupHook();
369
+ press(dispatch, "m");
370
+ expect(usePlayerStore.getState().audioMuted).toBe(false);
371
+ press(dispatch, "x");
372
+ expect(usePlayerStore.getState().audioMuted).toBe(true);
373
+ press(dispatch, "a");
374
+ expect(spies.seek).not.toHaveBeenCalled();
375
+ press(dispatch, "u");
376
+ expect(spies.seek).toHaveBeenCalledTimes(1);
377
+ press(dispatch, "l");
378
+ expect(spies.play).not.toHaveBeenCalled();
379
+ press(dispatch, "y");
380
+ expect(spies.play).toHaveBeenCalledTimes(1);
381
+ press(dispatch, "l", true);
382
+ expect(usePlayerStore.getState().loopEnabled).toBe(true);
383
+ });
384
+
385
+ it("holding the remapped stop key still frame-steps with the remapped shuttle keys", () => {
386
+ setStudioKeys({ pause: "p", shuttleForward: "y" });
387
+ const { dispatch, spies } = setupHook();
388
+ press(dispatch, "p");
389
+ press(dispatch, "y");
390
+ press(dispatch, "j");
391
+ expect(spies.seek).toHaveBeenCalledTimes(2);
392
+ expect(spies.play).not.toHaveBeenCalled();
393
+ expect(spies.playBackward).not.toHaveBeenCalled();
394
+ });
395
+
396
+ it("with the razor armed, jump-to-in still answers when razor-back-to-select moved", () => {
397
+ setStudioKeys({ exitRazor: "x" });
398
+ usePlayerStore.setState({ activeTool: "razor", inPoint: 2 });
399
+ const { dispatch, spies } = setupHook();
400
+ press(dispatch, "a");
401
+ expect(spies.seek).toHaveBeenCalledWith(2, { keepPlaying: true });
402
+ });
403
+
404
+ it("with the razor armed, a remapped jump-to-in key still answers", () => {
405
+ setStudioKeys({ seekToIn: "q" });
406
+ usePlayerStore.setState({ activeTool: "razor", inPoint: 3 });
407
+ const { dispatch, spies } = setupHook();
408
+ press(dispatch, "q");
409
+ expect(spies.seek).toHaveBeenCalledWith(3, { keepPlaying: true });
410
+ });
411
+ });
412
+
413
+ describe("usePlaybackKeyboard: space, arrows, loop and clear keys are combos", () => {
414
+ const send = (dispatch: HookHandle["dispatch"], init: Partial<Parameters<typeof keydown>[0]>) =>
415
+ act(() => {
416
+ dispatch(keydown({ code: "", key: "", ...init }));
417
+ });
418
+
419
+ it("Space, arrows (Shift = 10), Shift+L and Shift+I answer by default", () => {
420
+ const { dispatch, spies } = setupHook();
421
+ usePlayerStore.setState({ isPlaying: false, inPoint: 1, loopEnabled: false });
422
+ send(dispatch, { code: "Space", key: " " });
423
+ expect(spies.play).toHaveBeenCalledTimes(1);
424
+ send(dispatch, { code: "ArrowRight", key: "ArrowRight", shiftKey: true });
425
+ send(dispatch, { code: "ArrowLeft", key: "ArrowLeft" });
426
+ expect(spies.seek).toHaveBeenCalledTimes(2);
427
+ send(dispatch, { code: "KeyL", key: "L", shiftKey: true });
428
+ expect(usePlayerStore.getState().loopEnabled).toBe(true);
429
+ send(dispatch, { code: "KeyI", key: "I", shiftKey: true });
430
+ expect(usePlayerStore.getState().inPoint).toBeNull();
431
+ });
432
+
433
+ it("a remapped key answers and the old one does not", () => {
434
+ setStudioKeys({
435
+ playPause: "p",
436
+ frameForward: "x",
437
+ loop: "mod+shift+u",
438
+ clearInPoint: "shift+y",
439
+ });
440
+ const { dispatch, spies } = setupHook();
441
+ usePlayerStore.setState({ isPlaying: false, inPoint: 1, loopEnabled: false });
442
+ send(dispatch, { code: "Space", key: " " });
443
+ send(dispatch, { code: "ArrowRight", key: "ArrowRight" });
444
+ send(dispatch, { code: "KeyL", key: "L", shiftKey: true });
445
+ send(dispatch, { code: "KeyI", key: "I", shiftKey: true });
446
+ expect(spies.play).not.toHaveBeenCalled();
447
+ expect(spies.seek).not.toHaveBeenCalled();
448
+ expect(usePlayerStore.getState().loopEnabled).toBe(false);
449
+ expect(usePlayerStore.getState().inPoint).toBe(1);
450
+ send(dispatch, { code: "KeyP", key: "p" });
451
+ expect(spies.play).toHaveBeenCalledTimes(1);
452
+ send(dispatch, { code: "KeyX", key: "x" });
453
+ expect(spies.seek).toHaveBeenCalledTimes(1);
454
+ send(dispatch, { code: "KeyY", key: "Y", shiftKey: true });
455
+ expect(usePlayerStore.getState().inPoint).toBeNull();
456
+ });
457
+ });
458
+
459
+ describe("usePlaybackKeyboard: modifier combos and named keys", () => {
460
+ const send = (dispatch: HookHandle["dispatch"], init: Parameters<typeof keydown>[0]) =>
461
+ act(() => {
462
+ dispatch(keydown(init));
463
+ });
464
+
465
+ it("a playback action remapped to a Cmd or Alt combo answers, and the plain key does not", () => {
466
+ setStudioKeys({ playPause: "mod+p", mute: "alt+m" });
467
+ const { dispatch, spies } = setupHook();
468
+ usePlayerStore.setState({ isPlaying: false, audioMuted: false });
469
+ send(dispatch, { code: "KeyP", key: "p", metaKey: true });
470
+ expect(spies.play).toHaveBeenCalledTimes(1);
471
+ send(dispatch, { code: "KeyM", key: "µ", altKey: true });
472
+ expect(usePlayerStore.getState().audioMuted).toBe(true);
473
+ send(dispatch, { code: "KeyP", key: "p" });
474
+ expect(spies.play).toHaveBeenCalledTimes(1);
475
+ });
476
+
477
+ it("holding a stop key that is a named key still frame-steps instead of shuttling", () => {
478
+ setStudioKeys({ pause: "Home" });
479
+ const { dispatch, spies } = setupHook();
480
+ send(dispatch, { code: "Home", key: "Home" });
481
+ send(dispatch, { code: "KeyJ", key: "j" });
482
+ expect(spies.seek).toHaveBeenCalledTimes(1);
483
+ expect(spies.playBackward).not.toHaveBeenCalled();
484
+ });
485
+ });
@@ -8,9 +8,15 @@
8
8
 
9
9
  import { useRef, useCallback } from "react";
10
10
  import { useCaptionStore } from "../../captions/store";
11
- import { shouldIgnorePlaybackShortcutEvent, SHUTTLE_SPEEDS } from "../lib/playbackShortcuts";
11
+ import {
12
+ razorClaimsKey,
13
+ shouldIgnorePlaybackShortcutEvent,
14
+ SHUTTLE_SPEEDS,
15
+ } from "../lib/playbackShortcuts";
12
16
  import { canvasNudgeKeysClaimed } from "../../utils/canvasNudgeGate";
13
17
  import { usePlayerStore } from "../store/playerStore";
18
+ import { matchesKey, type StudioKeyAction } from "../components/studioShortcuts";
19
+ import { resolveCanvasNudgeDelta } from "../../components/editor/domEditNudge";
14
20
  import { stepFrameTime } from "../lib/time";
15
21
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
16
22
  import type { PlaybackAdapter } from "../lib/playbackTypes";
@@ -27,12 +33,62 @@ interface UsePlaybackKeyboardParams {
27
33
  seek: (time: number, options?: { keepPlaying?: boolean }) => void;
28
34
  }
29
35
 
30
- // The razor tool owns plain "a" (return to select) while it's armed; this
31
- // can't rely on defaultPrevented since both listeners register on window and
32
- // fire in an order this hook doesn't control. Shift+A and Alt+A are left for
33
- // the in-point seek below, since only plain A means "exit the razor".
34
- function shouldRazorClaimPlainA(e: KeyboardEvent): boolean {
35
- return !e.shiftKey && !e.altKey && usePlayerStore.getState().activeTool === "razor";
36
+ const FRAME_STEPS = {
37
+ frameBack: -1,
38
+ frameForward: 1,
39
+ frameBackTen: -10,
40
+ frameForwardTen: 10,
41
+ } as const;
42
+ const PLAYBACK_ACTIONS = [
43
+ "playPause",
44
+ ...(Object.keys(FRAME_STEPS) as Array<keyof typeof FRAME_STEPS>),
45
+ "mute",
46
+ "loop",
47
+ "pause",
48
+ "shuttleBack",
49
+ "shuttleForward",
50
+ "inPoint",
51
+ "clearInPoint",
52
+ "outPoint",
53
+ "clearOutPoint",
54
+ "seekToIn",
55
+ "seekToOut",
56
+ ] as const satisfies readonly StudioKeyAction[];
57
+ type PlaybackAction = (typeof PLAYBACK_ACTIONS)[number];
58
+
59
+ const playbackActionOf = (e: KeyboardEvent): PlaybackAction | undefined =>
60
+ PLAYBACK_ACTIONS.find((action) => matchesKey(e, action));
61
+
62
+ function ignoresPlaybackKey(e: KeyboardEvent): boolean {
63
+ const captionState = useCaptionStore.getState();
64
+ return shouldIgnorePlaybackShortcutEvent(e, {
65
+ isCaptionEditMode: captionState.isEditMode,
66
+ selectedCaptionSegmentCount: captionState.selectedSegmentIds.size,
67
+ });
68
+ }
69
+
70
+ function handleWorkAreaKey(
71
+ e: KeyboardEvent,
72
+ action: PlaybackAction,
73
+ getAdapter: () => PlaybackAdapter | null,
74
+ seek: UsePlaybackKeyboardParams["seek"],
75
+ ): boolean {
76
+ const store = usePlayerStore.getState();
77
+ const time = () => getAdapter()?.getTime() ?? store.currentTime;
78
+ const end = () => store.outPoint ?? getAdapter()?.getDuration() ?? store.duration;
79
+ const actions: Partial<Record<PlaybackAction, () => void>> = {
80
+ inPoint: () => store.setInPoint(time()),
81
+ clearInPoint: () => store.setInPoint(null),
82
+ outPoint: () => store.setOutPoint(time()),
83
+ clearOutPoint: () => store.setOutPoint(null),
84
+ seekToIn: () => seek(store.inPoint ?? 0, { keepPlaying: true }),
85
+ seekToOut: () => seek(end(), { keepPlaying: true }),
86
+ };
87
+ const run = actions[action];
88
+ if (!run || razorClaimsKey(e)) return false;
89
+ e.preventDefault();
90
+ run();
91
+ return true;
36
92
  }
37
93
 
38
94
  export function usePlaybackKeyboard({
@@ -46,7 +102,7 @@ export function usePlaybackKeyboard({
46
102
  pause,
47
103
  seek,
48
104
  }: UsePlaybackKeyboardParams) {
49
- const pressedKeysRef = useRef(new Set<string>());
105
+ const heldPauseRef = useRef(new Set<string>());
50
106
  const playbackKeyDownRef = useRef<(e: KeyboardEvent) => void>(() => {});
51
107
  const playbackKeyUpRef = useRef<(e: KeyboardEvent) => void>(() => {});
52
108
 
@@ -91,111 +147,47 @@ export function usePlaybackKeyboard({
91
147
  }
92
148
  }, [play, pause]);
93
149
 
94
- // Pre-existing dispatcher, already over the complexity gate before this
95
- // branch's one-line "a" fix touched it. A real fix is a dispatch-table
96
- // rewrite, out of scope here; the branch this PR changed is its own function.
97
- // fallow-ignore-next-line complexity
98
150
  const handlePlaybackKeyDown = useCallback(
99
151
  (e: KeyboardEvent) => {
100
- if (e.defaultPrevented) return;
101
- const captionState = useCaptionStore.getState();
102
- if (
103
- shouldIgnorePlaybackShortcutEvent(e, {
104
- isCaptionEditMode: captionState.isEditMode,
105
- selectedCaptionSegmentCount: captionState.selectedSegmentIds.size,
106
- })
107
- ) {
108
- return;
109
- }
110
- const key = e.key.toLowerCase();
111
- pressedKeysRef.current.add(key);
112
- if (e.code === "Space") {
113
- e.preventDefault();
114
- togglePlay();
115
- return;
116
- }
152
+ if (e.defaultPrevented || ignoresPlaybackKey(e)) return;
153
+ const action = playbackActionOf(e);
154
+ if (action === "pause") heldPauseRef.current.add(e.code || e.key);
155
+ if (!action) return;
156
+ const isFrameStep = action in FRAME_STEPS;
117
157
  // A nudgeable canvas selection owns the arrow keys (DomEditOverlay moves
118
158
  // the element); frame-stepping would double-handle the same keystroke.
119
- const arrowStep = e.code === "ArrowLeft" || e.code === "ArrowRight";
120
- if (arrowStep && canvasNudgeKeysClaimed()) return;
121
- if (e.code === "ArrowLeft") {
122
- e.preventDefault();
123
- stepFrames(e.shiftKey ? -10 : -1);
124
- return;
125
- }
126
- if (e.code === "ArrowRight") {
127
- e.preventDefault();
128
- stepFrames(e.shiftKey ? 10 : 1);
129
- return;
130
- }
131
- if (e.repeat) return;
132
- if (key === "m") {
133
- e.preventDefault();
134
- const state = usePlayerStore.getState();
135
- state.setAudioMuted(!state.audioMuted);
136
- return;
137
- }
138
- if (key === "l" && e.shiftKey) {
139
- e.preventDefault();
140
- const state = usePlayerStore.getState();
141
- state.setLoopEnabled(!state.loopEnabled);
142
- return;
143
- }
144
- if (key === "k") {
145
- e.preventDefault();
146
- pause();
147
- return;
148
- }
149
- if (key === "j") {
150
- e.preventDefault();
151
- if (pressedKeysRef.current.has("k")) {
152
- stepFrames(-1);
153
- return;
154
- }
155
- shuttle("backward");
156
- return;
157
- }
158
- if (key === "l") {
159
- e.preventDefault();
160
- if (pressedKeysRef.current.has("k")) {
161
- stepFrames(1);
162
- return;
163
- }
164
- shuttle("forward");
165
- return;
166
- }
167
- if (key === "i") {
168
- e.preventDefault();
169
- const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
170
- usePlayerStore.getState().setInPoint(e.shiftKey ? null : t);
171
- return;
172
- }
173
- if (key === "o") {
174
- e.preventDefault();
175
- const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
176
- usePlayerStore.getState().setOutPoint(e.shiftKey ? null : t);
177
- return;
178
- }
179
- if (key === "a") {
180
- if (shouldRazorClaimPlainA(e)) return;
181
- e.preventDefault();
182
- seek(usePlayerStore.getState().inPoint ?? 0, { keepPlaying: true });
183
- return;
184
- }
185
- if (key === "e") {
186
- e.preventDefault();
187
- const { outPoint } = usePlayerStore.getState();
188
- seek(outPoint ?? getAdapter()?.getDuration() ?? usePlayerStore.getState().duration, {
189
- keepPlaying: true,
190
- });
159
+ if (isFrameStep && canvasNudgeKeysClaimed() && resolveCanvasNudgeDelta(e)) return;
160
+ if (e.repeat && action !== "playPause" && !isFrameStep) return;
161
+ const shuttleOrStep = (direction: -1 | 1) =>
162
+ heldPauseRef.current.size > 0
163
+ ? stepFrames(direction)
164
+ : shuttle(direction < 0 ? "backward" : "forward");
165
+ const player = usePlayerStore.getState();
166
+ const run: Partial<Record<PlaybackAction, () => void>> = {
167
+ playPause: togglePlay,
168
+ frameBack: () => stepFrames(FRAME_STEPS.frameBack),
169
+ frameForward: () => stepFrames(FRAME_STEPS.frameForward),
170
+ frameBackTen: () => stepFrames(FRAME_STEPS.frameBackTen),
171
+ frameForwardTen: () => stepFrames(FRAME_STEPS.frameForwardTen),
172
+ mute: () => player.setAudioMuted(!player.audioMuted),
173
+ loop: () => player.setLoopEnabled(!player.loopEnabled),
174
+ pause,
175
+ shuttleBack: () => shuttleOrStep(-1),
176
+ shuttleForward: () => shuttleOrStep(1),
177
+ };
178
+ const act = run[action];
179
+ if (!act) {
180
+ handleWorkAreaKey(e, action, getAdapter, seek);
191
181
  return;
192
182
  }
183
+ e.preventDefault();
184
+ act();
193
185
  },
194
186
  [pause, shuttle, stepFrames, togglePlay, getAdapter, seek],
195
187
  );
196
188
 
197
189
  const handlePlaybackKeyUp = useCallback((e: KeyboardEvent) => {
198
- pressedKeysRef.current.delete(e.key.toLowerCase());
190
+ heldPauseRef.current.delete(e.code || e.key);
199
191
  }, []);
200
192
 
201
193
  playbackKeyDownRef.current = handlePlaybackKeyDown;
@@ -23,6 +23,7 @@ import { setPreviewReloading } from "../previewReloading";
23
23
  import { announcePreviewPromoted } from "../sceneSwap";
24
24
  import { afterStudioPendingEdits, isStudioEditSaving } from "../../utils/studioPendingEdits";
25
25
  import { usePlayerStore } from "../store/playerStore";
26
+ import { READY_TIMEOUT_CAUSE, useShadowReloadRetry } from "./useShadowReloadRetry";
26
27
 
27
28
  // One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
28
29
  // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
@@ -117,6 +118,7 @@ export function useShadowPreviewReload({
117
118
  const shadowUrlRef = useRef("");
118
119
  const savesAtRequestRef = useRef(0);
119
120
  const beginShadowReloadRef = useRef<(url: string) => void>(() => {});
121
+ const retry = useShadowReloadRetry(shadowGenRef, shadowUrlRef, beginShadowReloadRef);
120
122
  const promoteWhenReadyRef = useRef<(gen: number) => void>(() => {});
121
123
  const [previewSlots, setPreviewSlots] = useState<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
122
124
 
@@ -139,6 +141,7 @@ export function useShadowPreviewReload({
139
141
  : "its loaders to clear";
140
142
  const got = pageGotTo(shadowIframeRef.current);
141
143
  shadowGenRef.current += 1;
144
+ const failedGen = shadowGenRef.current;
142
145
  stopPendingShadow();
143
146
  shadowIframeRef.current = null;
144
147
  isRefreshingRef.current = false;
@@ -151,8 +154,9 @@ export function useShadowPreviewReload({
151
154
  const pageMissingNow = refused !== null && refused < 500;
152
155
  (pageMissingNow ? console.warn : console.error)(`[studio] ${message}`);
153
156
  onReloadFailedRef.current?.(message);
157
+ retry.afterFailure(cause, failedGen);
154
158
  },
155
- [stopPendingShadow, isRefreshingRef, pendingSeekRef],
159
+ [stopPendingShadow, retry, isRefreshingRef, pendingSeekRef],
156
160
  );
157
161
 
158
162
  const gestureSavesOnScreen = useCallback(() => {
@@ -313,7 +317,7 @@ export function useShadowPreviewReload({
313
317
  armReadyTimerRef.current(gen);
314
318
  return;
315
319
  }
316
- failShadow(gen, "it took too long to load");
320
+ failShadow(gen, READY_TIMEOUT_CAUSE);
317
321
  }, SHADOW_READY_TIMEOUT_MS);
318
322
  },
319
323
  [failShadow],
@@ -323,6 +327,7 @@ export function useShadowPreviewReload({
323
327
 
324
328
  const beginShadowReload = useCallback(
325
329
  (url: string) => {
330
+ retry.started();
326
331
  shadowGenRef.current += 1;
327
332
  const gen = shadowGenRef.current;
328
333
  stopPendingShadow();
@@ -335,12 +340,13 @@ export function useShadowPreviewReload({
335
340
  // Thumbnails of the edit wait for the new preview instead of competing with it.
336
341
  setPreviewReloading(true);
337
342
  },
338
- [stopPendingShadow, armReadyTimer, gestureSavesOnScreen],
343
+ [retry, stopPendingShadow, armReadyTimer, gestureSavesOnScreen],
339
344
  );
340
345
  beginShadowReloadRef.current = beginShadowReload;
341
346
 
342
347
  // Composition switch (not an edit reload): drop any in-flight shadow.
343
348
  const resetPreviewSlots = useCallback(() => {
349
+ retry.cancel();
344
350
  shadowGenRef.current += 1;
345
351
  stopPendingShadow();
346
352
  shadowIframeRef.current = null;
@@ -349,7 +355,7 @@ export function useShadowPreviewReload({
349
355
  usePlayerStore.getState().setTimelineReady(false);
350
356
  setPreviewSlots(planShadowDiscard);
351
357
  setPreviewReloading(false);
352
- }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
358
+ }, [retry, stopPendingShadow, isRefreshingRef, pendingSeekRef]);
353
359
 
354
360
  // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow.
355
361
  useMountEffect(() => {
@@ -364,6 +370,7 @@ export function useShadowPreviewReload({
364
370
  document.addEventListener("visibilitychange", onVisibilityChange);
365
371
  return () => {
366
372
  document.removeEventListener("visibilitychange", onVisibilityChange);
373
+ retry.cancel();
367
374
  stopPendingShadow();
368
375
  setPreviewReloading(false);
369
376
  };
@@ -0,0 +1,68 @@
1
+ import { useCallback, useMemo, useRef, type RefObject } from "react";
2
+
3
+ /** What a shadow reload gives as its cause when it ran out its wait budgets. */
4
+ export const READY_TIMEOUT_CAUSE = "it took too long to load";
5
+ export const SHADOW_RETRY_DELAY_MS = 2_000;
6
+
7
+ /** One more try for a reload that timed out, so an edit is not left unseen behind the old preview. A newer reload or
8
+ * a composition switch in the meantime cancels it, and a retry that times out is not tried again. */
9
+ export function useShadowReloadRetry(
10
+ generation: RefObject<number>,
11
+ url: RefObject<string>,
12
+ begin: RefObject<(url: string) => void>,
13
+ ) {
14
+ const retried = useRef(false);
15
+ const retrying = useRef(false);
16
+ const cancelRef = useRef(() => {});
17
+
18
+ const retryWhenVisible = useCallback(
19
+ (failedGen: number) => {
20
+ const schedule = () => {
21
+ const timer = setTimeout(() => {
22
+ cancelRef.current = () => {};
23
+ if (generation.current !== failedGen) return;
24
+ const next = new URL(url.current, window.location.origin);
25
+ next.searchParams.set("_t", String(Date.now()));
26
+ retrying.current = true;
27
+ begin.current(next.toString());
28
+ }, SHADOW_RETRY_DELAY_MS);
29
+ cancelRef.current = () => {
30
+ clearTimeout(timer);
31
+ cancelRef.current = () => {};
32
+ };
33
+ };
34
+ if (document.visibilityState !== "hidden") return schedule();
35
+ const onVisible = () => {
36
+ if (document.visibilityState === "hidden") return;
37
+ document.removeEventListener("visibilitychange", onVisible);
38
+ schedule();
39
+ };
40
+ document.addEventListener("visibilitychange", onVisible);
41
+ cancelRef.current = () => {
42
+ document.removeEventListener("visibilitychange", onVisible);
43
+ cancelRef.current = () => {};
44
+ };
45
+ },
46
+ [generation, url, begin],
47
+ );
48
+
49
+ /** A reload failed with `cause` as generation `failedGen`: a timeout is retried once. */
50
+ const afterFailure = useCallback(
51
+ (cause: string, failedGen: number) => {
52
+ if (cause !== READY_TIMEOUT_CAUSE || retried.current) return;
53
+ retried.current = true;
54
+ cancelRef.current();
55
+ retryWhenVisible(failedGen);
56
+ },
57
+ [retryWhenVisible],
58
+ );
59
+ /** A reload starts: a request of its own gets its own retry; the retry itself does not. */
60
+ const started = useCallback(() => {
61
+ cancelRef.current();
62
+ if (!retrying.current) retried.current = false;
63
+ retrying.current = false;
64
+ }, []);
65
+ /** The pending retry, if any, is dropped. */
66
+ const cancel = useCallback(() => cancelRef.current(), []);
67
+ return useMemo(() => ({ afterFailure, started, cancel }), [afterFailure, started, cancel]);
68
+ }
@@ -0,0 +1,85 @@
1
+ // @vitest-environment happy-dom
2
+ // A reload that ran out its budgets is tried once more, so an edit is not left unseen behind the old preview.
3
+
4
+ import { act } from "react";
5
+ import { afterEach, describe, expect, it, vi } from "vitest";
6
+ import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
7
+ import { SHADOW_RETRY_DELAY_MS } from "./useShadowReloadRetry";
8
+ import {
9
+ makeAdapterWindow,
10
+ makeFakeIframe,
11
+ renderTimelinePlayerHarness,
12
+ resetPlayerStore,
13
+ } from "./timelinePlayerTestHarness";
14
+
15
+ globalThis.IS_REACT_ACT_ENVIRONMENT = true;
16
+
17
+ const FULL_WAIT_MS = SHADOW_READY_TIMEOUT_MS * SHADOW_READY_BUDGETS;
18
+
19
+ vi.mock("../../utils/gsapSoftReload", async (importOriginal) => ({
20
+ ...(await importOriginal<typeof import("../../utils/gsapSoftReload")>()),
21
+ ensureMotionPathPluginLoaded: vi.fn(),
22
+ }));
23
+
24
+ afterEach(() => {
25
+ vi.useRealTimers();
26
+ vi.restoreAllMocks();
27
+ document.body.innerHTML = "";
28
+ resetPlayerStore();
29
+ });
30
+
31
+ function beginReload(onPreviewReloadFailed = vi.fn()) {
32
+ vi.useFakeTimers();
33
+ vi.spyOn(console, "error").mockImplementation(() => {});
34
+ const harness = renderTimelinePlayerHarness({ onPreviewReloadFailed });
35
+ const live = makeFakeIframe(makeAdapterWindow().win);
36
+ act(() => {
37
+ harness.getApi().iframeRef.current = live;
38
+ harness.getApi().onIframeLoad();
39
+ });
40
+ act(() => harness.getApi().refreshPlayer());
41
+ return { ...harness, onPreviewReloadFailed };
42
+ }
43
+
44
+ const shadows = (slots: { role: string; url?: string; gen: number }[]) =>
45
+ slots.filter((slot) => slot.role === "shadow");
46
+
47
+ describe("a shadow reload that timed out", () => {
48
+ it("is loaded once more after a short wait, with a fresh address", () => {
49
+ const { getApi, onPreviewReloadFailed } = beginReload();
50
+ const first = shadows(getApi().previewSlots)[0]!;
51
+
52
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
53
+ expect(onPreviewReloadFailed).toHaveBeenCalledTimes(1);
54
+ expect(shadows(getApi().previewSlots)).toHaveLength(0);
55
+
56
+ act(() => void vi.advanceTimersByTime(SHADOW_RETRY_DELAY_MS));
57
+ const again = shadows(getApi().previewSlots);
58
+ expect(again).toHaveLength(1);
59
+ expect(again[0]!.gen).toBeGreaterThan(first.gen);
60
+ expect(new URL(again[0]!.url!, "http://x").pathname).toBe(
61
+ new URL(first.url!, "http://x").pathname,
62
+ );
63
+ });
64
+
65
+ it("is not tried a third time when the retry also runs out its budgets", () => {
66
+ const { getApi, onPreviewReloadFailed } = beginReload();
67
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS + SHADOW_RETRY_DELAY_MS));
68
+ expect(shadows(getApi().previewSlots)).toHaveLength(1);
69
+
70
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS + SHADOW_RETRY_DELAY_MS * 3));
71
+ expect(onPreviewReloadFailed).toHaveBeenCalledTimes(2);
72
+ expect(shadows(getApi().previewSlots)).toHaveLength(0);
73
+ });
74
+
75
+ it("is not retried when a newer reload has taken over during the wait", () => {
76
+ const { getApi } = beginReload();
77
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
78
+ act(() => getApi().refreshPlayer());
79
+ const newer = shadows(getApi().previewSlots);
80
+ expect(newer).toHaveLength(1);
81
+
82
+ act(() => void vi.advanceTimersByTime(SHADOW_RETRY_DELAY_MS));
83
+ expect(shadows(getApi().previewSlots)).toEqual(newer);
84
+ });
85
+ });