@hyperframes/studio 0.8.228 → 0.8.230

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 (31) hide show
  1. package/dist/assets/{hyperframes-player-Cf70g7g5.js → hyperframes-player-Dv5Ew1Dr.js} +1 -1
  2. package/dist/assets/{index-KTleZEQO.js → index-BvqtI0ko.js} +160 -160
  3. package/dist/assets/{index-Ds4bLp7M.js → index-hiL49K7x.js} +1 -1
  4. package/dist/index.d.ts +33 -2
  5. package/dist/index.html +1 -1
  6. package/dist/index.js +2171 -2003
  7. package/package.json +8 -8
  8. package/src/components/TimelineToolPicker.tsx +6 -4
  9. package/src/components/TimelineToolbar.tsx +22 -17
  10. package/src/components/editor/GestureRecordControl.tsx +8 -3
  11. package/src/components/editor/PropertyPanelFlatFooter.tsx +3 -1
  12. package/src/components/editor/SnapToolbar.tsx +11 -5
  13. package/src/hooks/appHotkeysDispatch.ts +25 -26
  14. package/src/hooks/useAppHotkeys.test.ts +58 -0
  15. package/src/hooks/useKeyframeKeyboard.ts +2 -2
  16. package/src/index.ts +9 -1
  17. package/src/player/components/ClipContextMenu.tsx +6 -3
  18. package/src/player/components/PlayerControls.tsx +3 -2
  19. package/src/player/components/ShortcutsPanel.tsx +3 -2
  20. package/src/player/components/VideoThumbnail.test.tsx +59 -0
  21. package/src/player/components/VideoThumbnail.tsx +36 -12
  22. package/src/player/components/studioShortcuts.test.tsx +109 -0
  23. package/src/player/components/studioShortcuts.ts +187 -94
  24. package/src/player/components/useTimelineClipDrag.resize.test.tsx +16 -0
  25. package/src/player/components/useTimelineClipDrag.ts +2 -0
  26. package/src/player/hooks/usePlaybackKeyboard.test.ts +78 -1
  27. package/src/player/hooks/usePlaybackKeyboard.ts +36 -40
  28. package/src/player/hooks/useShadowPreviewReload.ts +11 -4
  29. package/src/player/hooks/useShadowReloadRetry.ts +68 -0
  30. package/src/player/hooks/useTimelinePlayer.shadowRetry.test.ts +85 -0
  31. package/src/player/lib/playbackShortcuts.ts +12 -0
@@ -8,9 +8,14 @@
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 { getStudioKeys } from "../components/studioShortcuts";
14
19
  import { stepFrameTime } from "../lib/time";
15
20
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
16
21
  import type { PlaybackAdapter } from "../lib/playbackTypes";
@@ -27,12 +32,27 @@ interface UsePlaybackKeyboardParams {
27
32
  seek: (time: number, options?: { keepPlaying?: boolean }) => void;
28
33
  }
29
34
 
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";
35
+ function handleWorkAreaKey(
36
+ e: KeyboardEvent,
37
+ key: string,
38
+ getAdapter: () => PlaybackAdapter | null,
39
+ seek: UsePlaybackKeyboardParams["seek"],
40
+ ): boolean {
41
+ if (razorClaimsKey(e, key)) return false;
42
+ const keys = getStudioKeys();
43
+ const store = usePlayerStore.getState();
44
+ const time = () => getAdapter()?.getTime() ?? store.currentTime;
45
+ const end = () => store.outPoint ?? getAdapter()?.getDuration() ?? store.duration;
46
+ const actions: Record<string, () => void> = {
47
+ [keys.inPoint]: () => store.setInPoint(e.shiftKey ? null : time()),
48
+ [keys.outPoint]: () => store.setOutPoint(e.shiftKey ? null : time()),
49
+ [keys.seekToIn]: () => seek(store.inPoint ?? 0, { keepPlaying: true }),
50
+ [keys.seekToOut]: () => seek(end(), { keepPlaying: true }),
51
+ };
52
+ if (!Object.hasOwn(actions, key)) return false;
53
+ e.preventDefault();
54
+ actions[key]();
55
+ return true;
36
56
  }
37
57
 
38
58
  export function usePlaybackKeyboard({
@@ -108,6 +128,7 @@ export function usePlaybackKeyboard({
108
128
  return;
109
129
  }
110
130
  const key = e.key.toLowerCase();
131
+ const keys = getStudioKeys();
111
132
  pressedKeysRef.current.add(key);
112
133
  if (e.code === "Space") {
113
134
  e.preventDefault();
@@ -129,67 +150,42 @@ export function usePlaybackKeyboard({
129
150
  return;
130
151
  }
131
152
  if (e.repeat) return;
132
- if (key === "m") {
153
+ if (key === keys.mute) {
133
154
  e.preventDefault();
134
155
  const state = usePlayerStore.getState();
135
156
  state.setAudioMuted(!state.audioMuted);
136
157
  return;
137
158
  }
138
- if (key === "l" && e.shiftKey) {
159
+ if (key === keys.shuttleForward && e.shiftKey) {
139
160
  e.preventDefault();
140
161
  const state = usePlayerStore.getState();
141
162
  state.setLoopEnabled(!state.loopEnabled);
142
163
  return;
143
164
  }
144
- if (key === "k") {
165
+ if (key === keys.pause) {
145
166
  e.preventDefault();
146
167
  pause();
147
168
  return;
148
169
  }
149
- if (key === "j") {
170
+ if (key === keys.shuttleBack) {
150
171
  e.preventDefault();
151
- if (pressedKeysRef.current.has("k")) {
172
+ if (pressedKeysRef.current.has(keys.pause)) {
152
173
  stepFrames(-1);
153
174
  return;
154
175
  }
155
176
  shuttle("backward");
156
177
  return;
157
178
  }
158
- if (key === "l") {
179
+ if (key === keys.shuttleForward) {
159
180
  e.preventDefault();
160
- if (pressedKeysRef.current.has("k")) {
181
+ if (pressedKeysRef.current.has(keys.pause)) {
161
182
  stepFrames(1);
162
183
  return;
163
184
  }
164
185
  shuttle("forward");
165
186
  return;
166
187
  }
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
- });
191
- return;
192
- }
188
+ handleWorkAreaKey(e, key, getAdapter, seek);
193
189
  },
194
190
  [pause, shuttle, stepFrames, togglePlay, getAdapter, seek],
195
191
  );
@@ -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
+ });
@@ -7,6 +7,8 @@
7
7
  */
8
8
 
9
9
  import { ownsPlainKeys } from "../../utils/typingTarget";
10
+ import { getStudioKey } from "../components/studioShortcuts";
11
+ import { usePlayerStore } from "../store/playerStore";
10
12
 
11
13
  const PLAYBACK_FRAME_STEP_CODES = new Set(["ArrowLeft", "ArrowRight"]);
12
14
 
@@ -83,3 +85,13 @@ export function shouldIgnorePlaybackShortcutEvent(
83
85
 
84
86
  /** JKL shuttle speeds (×1, ×2, ×4). */
85
87
  export const SHUTTLE_SPEEDS = [1, 2, 4] as const;
88
+
89
+ /** Plain exit-razor key while the razor is armed: the razor owns it, playback must leave it alone. */
90
+ export function razorClaimsKey(e: KeyboardEvent, key: string): boolean {
91
+ return (
92
+ key === getStudioKey("exitRazor") &&
93
+ !e.shiftKey &&
94
+ !e.altKey &&
95
+ usePlayerStore.getState().activeTool === "razor"
96
+ );
97
+ }