@hyperframes/studio 0.8.230 → 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 (44) hide show
  1. package/dist/assets/{hyperframes-player-Dv5Ew1Dr.js → hyperframes-player-ClW2l0Vl.js} +1 -1
  2. package/dist/assets/{index-hiL49K7x.js → index-CGfRmZQd.js} +1 -1
  3. package/dist/assets/{index-BvqtI0ko.js → index-DxWNzvQJ.js} +153 -153
  4. package/dist/index.d.ts +40 -0
  5. package/dist/index.html +1 -1
  6. package/dist/index.js +530 -432
  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/TimelineToolbar.tsx +2 -3
  13. package/src/components/editor/InspectorHeaderActions.tsx +3 -1
  14. package/src/components/editor/PropertyPanelFlatHeader.tsx +3 -1
  15. package/src/components/editor/SnapToolbar.tsx +3 -3
  16. package/src/components/editor/domEditNudge.test.ts +17 -1
  17. package/src/components/editor/domEditNudge.ts +16 -13
  18. package/src/components/editor/marqueeCommit.ts +2 -1
  19. package/src/hooks/appHotkeysDispatch.ts +94 -107
  20. package/src/hooks/linkShortcuts.test.ts +20 -0
  21. package/src/hooks/linkShortcuts.ts +11 -11
  22. package/src/hooks/useAppHotkeys.test.ts +143 -0
  23. package/src/hooks/useAppHotkeys.ts +1 -4
  24. package/src/hooks/useAutomationSelectionKeyboard.ts +7 -18
  25. package/src/hooks/useKeyframeKeyboard.ts +2 -3
  26. package/src/hooks/useTimelineDeleteOps.ts +2 -1
  27. package/src/player/components/BeatStrip.tsx +2 -1
  28. package/src/player/components/ClipContextMenu.tsx +3 -3
  29. package/src/player/components/TimelineClipFades.tsx +2 -1
  30. package/src/player/components/clipMenuLinkItems.tsx +5 -4
  31. package/src/player/components/studioCombo.test.ts +99 -0
  32. package/src/player/components/studioCombo.ts +108 -0
  33. package/src/player/components/studioShortcuts.test.tsx +16 -1
  34. package/src/player/components/studioShortcuts.ts +85 -29
  35. package/src/player/components/timelineClipDragGestureLifecycle.ts +2 -1
  36. package/src/player/components/timelineEditing.ts +2 -2
  37. package/src/player/components/useTimelineClipDrag.ts +2 -1
  38. package/src/player/components/useTimelineKeyboardActor.ts +7 -18
  39. package/src/player/components/useTimelineKeyframeHandlers.ts +2 -1
  40. package/src/player/components/useTimelineRangeSelection.ts +3 -2
  41. package/src/player/hooks/usePlaybackKeyboard.test.ts +87 -4
  42. package/src/player/hooks/usePlaybackKeyboard.ts +78 -82
  43. package/src/player/hooks/useTimelinePlayer.test.ts +19 -13
  44. package/src/player/lib/playbackShortcuts.ts +13 -16
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperframes/studio",
3
- "version": "0.8.230",
3
+ "version": "0.8.231",
4
4
  "description": "",
5
5
  "repository": {
6
6
  "type": "git",
@@ -60,12 +60,12 @@
60
60
  "dockview-react": "8.3.1",
61
61
  "gsap": "^3.13.0",
62
62
  "mediabunny": "^1.45.3",
63
- "@hyperframes/parsers": "0.8.230",
64
- "@hyperframes/sdk": "0.8.230",
65
- "@hyperframes/player": "0.8.230",
66
- "@hyperframes/shader-transitions": "0.8.230",
67
- "@hyperframes/core": "0.8.230",
68
- "@hyperframes/studio-server": "0.8.230"
63
+ "@hyperframes/parsers": "0.8.231",
64
+ "@hyperframes/shader-transitions": "0.8.231",
65
+ "@hyperframes/sdk": "0.8.231",
66
+ "@hyperframes/core": "0.8.231",
67
+ "@hyperframes/studio-server": "0.8.231",
68
+ "@hyperframes/player": "0.8.231"
69
69
  },
70
70
  "devDependencies": {
71
71
  "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
82
82
  "vite": "^6.4.2",
83
83
  "vitest": "^4.1.11",
84
84
  "zustand": "^5.0.0",
85
- "@hyperframes/producer": "0.8.230"
85
+ "@hyperframes/producer": "0.8.231"
86
86
  },
87
87
  "peerDependencies": {
88
88
  "react": "19",
@@ -2,7 +2,8 @@ import { memo, useEffect, useState, useCallback, useRef } from "react";
2
2
  import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
3
3
  import { useCaptionStore } from "../store";
4
4
  import { usePlayerStore } from "../../player";
5
- import { shouldHandleCaptionNudgeKey, isEditableEventTarget } from "../keyboard";
5
+ import { resolveCaptionNudge, isEditableEventTarget } from "../keyboard";
6
+ import { matchesKey } from "../../player/components/studioShortcuts";
6
7
  import {
7
8
  readWordBoxes,
8
9
  getWordEl,
@@ -171,7 +172,7 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
171
172
  const { selectedSegmentIds: sel, model: m } = store;
172
173
 
173
174
  // Escape: cancel an in-flight drag first, else clear the selection.
174
- if (e.key === "Escape") {
175
+ if (matchesKey(e, "cancel")) {
175
176
  if (cancelActiveDrag()) {
176
177
  e.preventDefault();
177
178
  scheduleTick();
@@ -185,28 +186,20 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
185
186
  }
186
187
 
187
188
  // ⌘A / Ctrl+A selects every caption word (unless typing in a field).
188
- if (
189
- (e.metaKey || e.ctrlKey) &&
190
- e.key.toLowerCase() === "a" &&
191
- !e.shiftKey &&
192
- !e.altKey &&
193
- !isEditableEventTarget(e.target)
194
- ) {
189
+ if (matchesKey(e, "captionSelectAll") && !isEditableEventTarget(e.target)) {
195
190
  e.preventDefault();
196
191
  store.selectAll();
197
192
  return;
198
193
  }
199
194
 
200
195
  if (sel.size === 0 || !m) return;
201
- const arrow = e.key;
202
196
  // Pass the event target so arrows inside inputs keep their native
203
197
  // behavior instead of nudging the canvas word.
204
- if (!shouldHandleCaptionNudgeKey(e, e.target)) return;
198
+ const nudge = resolveCaptionNudge(e, e.target);
199
+ if (!nudge) return;
205
200
 
206
201
  e.preventDefault();
207
- const step = e.shiftKey ? 10 : 1;
208
- const dx = arrow === "ArrowLeft" ? -step : arrow === "ArrowRight" ? step : 0;
209
- const dy = arrow === "ArrowUp" ? -step : arrow === "ArrowDown" ? step : 0;
202
+ const { dx, dy } = nudge;
210
203
 
211
204
  const iframe = iframeRef.current;
212
205
  const win = iframe?.contentWindow;
@@ -1,6 +1,7 @@
1
1
  // @vitest-environment happy-dom
2
2
 
3
- import { describe, expect, it } from "vitest";
3
+ import { afterEach, describe, expect, it } from "vitest";
4
+ import { setStudioKeys } from "../player/components/studioShortcuts";
4
5
  import { shouldHandleCaptionNudgeKey } from "./keyboard";
5
6
 
6
7
  function mockKeyboardEvent(
@@ -60,3 +61,13 @@ describe("shouldHandleCaptionNudgeKey", () => {
60
61
  expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight"), player)).toBe(false);
61
62
  });
62
63
  });
64
+
65
+ describe("shouldHandleCaptionNudgeKey: remapped", () => {
66
+ afterEach(() => setStudioKeys(null));
67
+
68
+ it("follows the canvas nudge keys", () => {
69
+ setStudioKeys({ nudgeUp: "u" });
70
+ expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowUp"))).toBe(false);
71
+ expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("u"))).toBe(true);
72
+ });
73
+ });
@@ -1,18 +1,18 @@
1
1
  import { isEditableTarget } from "../utils/timelineDiscovery";
2
2
  import { ownsPlainKeys } from "../utils/typingTarget";
3
+ import { resolveCanvasNudgeDelta } from "../components/editor/domEditNudge";
3
4
 
4
- const CAPTION_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
5
+ type CaptionNudgeKeyEvent = Parameters<typeof resolveCanvasNudgeDelta>[0];
5
6
 
6
- type CaptionNudgeKeyEvent = Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "key">;
7
+ export function resolveCaptionNudge(event: CaptionNudgeKeyEvent, target?: EventTarget | null) {
8
+ if (target != null && ownsPlainKeys(target)) return null;
9
+ return resolveCanvasNudgeDelta(event);
10
+ }
7
11
 
8
- export function shouldHandleCaptionNudgeKey(
12
+ export const shouldHandleCaptionNudgeKey = (
9
13
  event: CaptionNudgeKeyEvent,
10
14
  target?: EventTarget | null,
11
- ): boolean {
12
- if (event.metaKey || event.ctrlKey || event.altKey) return false;
13
- if (target != null && ownsPlainKeys(target)) return false;
14
- return CAPTION_NUDGE_KEYS.has(event.key);
15
- }
15
+ ): boolean => resolveCaptionNudge(event, target) !== null;
16
16
 
17
17
  // Single editable-target check for the caption surface — re-exported from the
18
18
  // shared timeline helper so the two never diverge (it also covers ARIA
@@ -1,4 +1,5 @@
1
1
  import { memo, useCallback, type ReactNode } from "react";
2
+ import { matchesKey } from "../player/components/studioShortcuts";
2
3
  import { PreviewPane } from "./nle/PreviewPane";
3
4
  import { TimelinePane } from "./nle/TimelinePane";
4
5
  import { PreviewOverlays } from "./nle/PreviewOverlays";
@@ -293,7 +294,7 @@ function EditorShellBody({
293
294
  // Keyboard: Escape to pop composition level
294
295
  const handleKeyDown = useCallback(
295
296
  (e: React.KeyboardEvent) => {
296
- if (e.key === "Escape" && compositionStack.length > 1) {
297
+ if (matchesKey(e, "cancel") && compositionStack.length > 1) {
297
298
  updateCompositionStack((prev) => prev.slice(0, -1));
298
299
  }
299
300
  },
@@ -40,7 +40,7 @@ import { LinkedSelectionToggle } from "./LinkedSelectionToggle";
40
40
  import { useProjectHasAudio } from "../utils/audioMeterMath";
41
41
  import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";
42
42
  import { isTypingTarget } from "../utils/typingTarget";
43
- import { getStudioKey, keyHint, useStudioKeys } from "../player/components/studioShortcuts";
43
+ import { keyHint, matchesKey, useStudioKeys } from "../player/components/studioShortcuts";
44
44
  import type { TimelineProps } from "../player/components/TimelineTypes";
45
45
 
46
46
  interface DomEditSessionSlice extends EnableKeyframesSession {
@@ -213,8 +213,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
213
213
  // Skip when typing in an input/contenteditable.
214
214
  useEffect(() => {
215
215
  const onKeyDown = (e: KeyboardEvent) => {
216
- if (e.key.toLowerCase() !== getStudioKey("timelineSnap")) return;
217
- if (e.metaKey || e.ctrlKey || e.altKey) return;
216
+ if (!matchesKey(e, "timelineSnap")) return;
218
217
  if (isTypingTarget(e.target)) return;
219
218
  const store = usePlayerStore.getState();
220
219
  store.setTimelineSnapEnabled(!store.timelineSnapEnabled);
@@ -4,6 +4,8 @@ import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
4
4
  import type { DomEditSelection } from "./domEditingTypes";
5
5
 
6
6
  /** The action buttons in the inspector header: visibility, Ungroup (groups only), copy, clear. */
7
+ import { keyHint, useStudioKeys } from "../../player/components/studioShortcuts";
8
+
7
9
  export function InspectorHeaderActions({
8
10
  element,
9
11
  copied,
@@ -53,7 +55,7 @@ export function InspectorHeaderActions({
53
55
  track("button", "Ungroup");
54
56
  onUngroup();
55
57
  }}
56
- title="Ungroup (⌘⇧G)"
58
+ title={`Ungroup (${keyHint("ungroup", useStudioKeys())})`}
57
59
  className="flex h-6 items-center rounded-sm px-2 text-[11px] font-medium text-neutral-400 transition-colors hover:bg-neutral-800 hover:text-neutral-200"
58
60
  >
59
61
  Ungroup
@@ -9,6 +9,8 @@ const ICON_COLOR_BY_KIND = {
9
9
  other: "text-panel-container",
10
10
  } as const;
11
11
 
12
+ import { keyHint, useStudioKeys } from "../../player/components/studioShortcuts";
13
+
12
14
  export function PropertyPanelFlatHeader({
13
15
  name,
14
16
  meta,
@@ -54,7 +56,7 @@ export function PropertyPanelFlatHeader({
54
56
  <button
55
57
  type="button"
56
58
  aria-label="Ungroup"
57
- title="Ungroup (⌘⇧G)"
59
+ title={`Ungroup (${keyHint("ungroup", useStudioKeys())})`}
58
60
  onClick={() => {
59
61
  track("button", "Ungroup");
60
62
  onUngroup?.();
@@ -4,7 +4,7 @@ import { MagnetStraight, GridFour, Path, Ruler, FrameCorners } from "@phosphor-i
4
4
  import { usePlayerStore } from "../../player/store/playerStore";
5
5
  import { usePreviewOverlayContext } from "./PreviewOverlayProvider";
6
6
  import { ownsPlainKeys } from "../../utils/typingTarget";
7
- import { getStudioKey, keyHint, useStudioKeys } from "../../player/components/studioShortcuts";
7
+ import { keyHint, matchesKey, useStudioKeys } from "../../player/components/studioShortcuts";
8
8
 
9
9
  // fallow-ignore-next-line complexity
10
10
  export const SnapToolbar = memo(function SnapToolbar() {
@@ -53,12 +53,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
53
53
  if (e.defaultPrevented) return;
54
54
  if (ownsPlainKeys(e.target)) return;
55
55
  if (e.target instanceof HTMLIFrameElement) return;
56
- if (e.key === getStudioKey("snap") && !e.metaKey && !e.ctrlKey && !e.altKey) {
56
+ if (matchesKey(e, "snap")) {
57
57
  e.preventDefault();
58
58
  updatePrefs({ snapEnabled: !prefs.snapEnabled });
59
59
  if (!e.repeat) trackPreviewFeatureUsed("snapping", "keyboard");
60
60
  }
61
- if (e.key === getStudioKey("grid") && !e.metaKey && !e.ctrlKey && !e.altKey) {
61
+ if (matchesKey(e, "grid")) {
62
62
  e.preventDefault();
63
63
  updatePrefs({ gridVisible: !prefs.gridVisible });
64
64
  if (!e.repeat) trackPreviewFeatureUsed("grid", "keyboard");
@@ -1,4 +1,5 @@
1
- import { describe, expect, it } from "vitest";
1
+ import { afterEach, describe, expect, it } from "vitest";
2
+ import { setStudioKeys } from "../../player/components/studioShortcuts";
2
3
  import {
3
4
  CANVAS_NUDGE_SHIFT_STEP_PX,
4
5
  CANVAS_NUDGE_STEP_PX,
@@ -78,3 +79,18 @@ describe("canCanvasNudgeTargets", () => {
78
79
  expect(canCanvasNudgeTargets([movable, locked])).toBe(false);
79
80
  });
80
81
  });
82
+
83
+ describe("resolveCanvasNudgeDelta: remapped keys", () => {
84
+ afterEach(() => setStudioKeys(null));
85
+
86
+ it("a remapped direction and step key answer and the arrow goes dead", () => {
87
+ setStudioKeys({ nudgeLeft: "h", nudgeRightTen: "alt+l" });
88
+ expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft"))).toBeNull();
89
+ expect(resolveCanvasNudgeDelta(mockKeyboardEvent("h"))).toEqual({ dx: -1, dy: 0 });
90
+ expect(resolveCanvasNudgeDelta(mockKeyboardEvent("l", { altKey: true }))).toEqual({
91
+ dx: 10,
92
+ dy: 0,
93
+ });
94
+ expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowRight", { shiftKey: true }))).toBeNull();
95
+ });
96
+ });
@@ -6,7 +6,7 @@
6
6
  * mutually exclusively (caption edit mode returns before the DOM overlay).
7
7
  */
8
8
 
9
- const CANVAS_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
9
+ import { matchesKey, type StudioKeyAction } from "../../player/components/studioShortcuts";
10
10
 
11
11
  export const CANVAS_NUDGE_STEP_PX = 1;
12
12
  export const CANVAS_NUDGE_SHIFT_STEP_PX = 10;
@@ -16,22 +16,25 @@ export const CANVAS_NUDGE_COMMIT_DEBOUNCE_MS = 400;
16
16
  type CanvasNudgeKeyEvent = Pick<
17
17
  KeyboardEvent,
18
18
  "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key"
19
- >;
19
+ > & { code?: string };
20
20
 
21
- /**
22
- * Arrow key → composition-px delta (Shift = 10). Null when the key is not a
23
- * plain/Shift arrow, so browser and app shortcut chords pass through.
24
- */
21
+ const NUDGES: ReadonlyArray<[StudioKeyAction, number, number, number]> = [
22
+ ["nudgeLeft", -1, 0, CANVAS_NUDGE_STEP_PX],
23
+ ["nudgeRight", 1, 0, CANVAS_NUDGE_STEP_PX],
24
+ ["nudgeUp", 0, -1, CANVAS_NUDGE_STEP_PX],
25
+ ["nudgeDown", 0, 1, CANVAS_NUDGE_STEP_PX],
26
+ ["nudgeLeftTen", -1, 0, CANVAS_NUDGE_SHIFT_STEP_PX],
27
+ ["nudgeRightTen", 1, 0, CANVAS_NUDGE_SHIFT_STEP_PX],
28
+ ["nudgeUpTen", 0, -1, CANVAS_NUDGE_SHIFT_STEP_PX],
29
+ ["nudgeDownTen", 0, 1, CANVAS_NUDGE_SHIFT_STEP_PX],
30
+ ];
31
+
32
+ /** Nudge key (default: arrows, Shift = 10) to a composition-px delta; null for any other key. */
25
33
  export function resolveCanvasNudgeDelta(
26
34
  event: CanvasNudgeKeyEvent,
27
35
  ): { dx: number; dy: number } | null {
28
- if (event.metaKey || event.ctrlKey || event.altKey) return null;
29
- if (!CANVAS_NUDGE_KEYS.has(event.key)) return null;
30
- const step = event.shiftKey ? CANVAS_NUDGE_SHIFT_STEP_PX : CANVAS_NUDGE_STEP_PX;
31
- return {
32
- dx: event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0,
33
- dy: event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0,
34
- };
36
+ const hit = NUDGES.find(([action]) => matchesKey(event, action));
37
+ return hit ? { dx: hit[1] * hit[3], dy: hit[2] * hit[3] } : null;
35
38
  }
36
39
 
37
40
  export interface CanvasNudgeTarget {
@@ -1,4 +1,5 @@
1
1
  import type { DomSelectionResult } from "../../hooks/useDomSelectionTypes";
2
+ import { matchesKey } from "../../player/components/studioShortcuts";
2
3
  import { trackPreviewFeatureUsed } from "../../utils/previewFeatureUsage";
3
4
  // fallow-ignore-file code-duplication
4
5
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -233,7 +234,7 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
233
234
 
234
235
  useEffect(() => {
235
236
  const cancelBandBeforeHostEscape = (e: KeyboardEvent) => {
236
- if (e.key !== "Escape" || !marqueeRef.current) return;
237
+ if (!matchesKey(e, "cancel") || !marqueeRef.current) return;
237
238
  e.preventDefault();
238
239
  e.stopPropagation();
239
240
  cancel();
@@ -9,7 +9,7 @@ import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
9
9
  import { canSplitElement } from "../utils/timelineElementSplit";
10
10
  import { trackStudioEvent } from "../utils/studioTelemetry";
11
11
  import { razorClaimsKey } from "../player/lib/playbackShortcuts";
12
- import { getStudioKeys, keyHint } from "../player/components/studioShortcuts";
12
+ import { getStudioKeys, keyHint, matchesKey } from "../player/components/studioShortcuts";
13
13
  import { zoomTimelineToSelectedClips } from "../player/components/timelineZoomInput";
14
14
  import { openAudioGainDialog } from "../player/components/audioGainDialogStore";
15
15
  import type { LinkShortcutCallbacks } from "./linkShortcuts";
@@ -19,18 +19,11 @@ import type { LinkShortcutCallbacks } from "./linkShortcuts";
19
19
  // hook still owns the actual keydown listeners and calls into these.
20
20
 
21
21
  function handleUndoRedoKey(event: KeyboardEvent, onUndo: () => void, onRedo: () => void): boolean {
22
- const key = event.key.toLowerCase();
23
- if (key === "z" && !event.shiftKey) {
24
- event.preventDefault();
25
- onUndo();
26
- return true;
27
- }
28
- if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
29
- event.preventDefault();
30
- onRedo();
31
- return true;
32
- }
33
- return false;
22
+ const isUndo = matchesKey(event, "undo");
23
+ if (!isUndo && !matchesKey(event, "redo") && !matchesKey(event, "redoAlt")) return false;
24
+ event.preventDefault();
25
+ (isUndo ? onUndo : onRedo)();
26
+ return true;
34
27
  }
35
28
 
36
29
  export interface HotkeyCallbacks extends LinkShortcutCallbacks {
@@ -60,17 +53,80 @@ function timelineOwnsKey(event: KeyboardEvent): boolean {
60
53
  return event.target instanceof Element && event.target.closest("[data-studio-timeline]") !== null;
61
54
  }
62
55
 
63
- /** Exported for tests, like dispatchPlainKey below: lets the Cmd+C/Cmd+V
64
- * arbitration between an automation range and the clip clipboard be asserted
65
- * without standing up the whole hook. */
56
+ function dispatchTabKey(event: KeyboardEvent): boolean {
57
+ const tab = matchesKey(event, "tabCompositions")
58
+ ? ["tab_compositions", "compositions"]
59
+ : matchesKey(event, "tabAssets")
60
+ ? ["tab_assets", "assets"]
61
+ : null;
62
+ if (!tab) return false;
63
+ event.preventDefault();
64
+ trackStudioEvent("keyboard_shortcut", { action: tab[0] });
65
+ useDockLayoutStore.getState().activatePanel(tab[1] as "compositions" | "assets");
66
+ return true;
67
+ }
68
+
69
+ function dispatchGroupKey(event: KeyboardEvent, cb: HotkeyCallbacks): boolean {
70
+ const group = matchesKey(event, "group");
71
+ if (!group && !matchesKey(event, "ungroup")) return false;
72
+ if (isTypingTarget(event.target)) return false;
73
+ event.preventDefault();
74
+ if (cb.readOnlyPreview) return true;
75
+ if (group) cb.onGroupSelection?.();
76
+ else cb.onUngroupSelection?.();
77
+ return true;
78
+ }
79
+
80
+ function dispatchClipboardKey(event: KeyboardEvent, cb: HotkeyCallbacks): boolean {
81
+ if (isEditableTarget(event.target)) return false;
82
+ const copy = matchesKey(event, "copy");
83
+ const paste = matchesKey(event, "paste");
84
+ const cut = matchesKey(event, "cut");
85
+ const duplicate = matchesKey(event, "duplicate");
86
+ if (!copy && !paste && !cut && !duplicate) return false;
87
+ // An active automation range owns copy/paste: this capture listener runs before its own, so without
88
+ // this both clipboards raced the same key. No preventDefault, so the downstream handler still sees it.
89
+ if (automationOwnsKey(event)) return true;
90
+ if (copy) {
91
+ if (cb.handleCopy()) {
92
+ event.preventDefault();
93
+ trackStudioEvent("keyboard_shortcut", { action: "copy" });
94
+ }
95
+ return true;
96
+ }
97
+ if (cb.readOnlyPreview && cb.domEditSelectionRef.current !== null && !timelineOwnsKey(event)) {
98
+ event.preventDefault();
99
+ return true;
100
+ }
101
+ const hasSelection =
102
+ usePlayerStore.getState().selectedElementId || cb.domEditSelectionRef.current;
103
+ if (paste) {
104
+ event.preventDefault();
105
+ trackStudioEvent("keyboard_shortcut", { action: "paste" });
106
+ void cb.handlePaste();
107
+ } else if (cut && hasSelection) {
108
+ event.preventDefault();
109
+ trackStudioEvent("keyboard_shortcut", { action: "cut" });
110
+ void cb.handleCut();
111
+ } else if (duplicate) {
112
+ // Own this key even with nothing selected, or the browser's bookmark shortcut fires over the editor.
113
+ event.preventDefault();
114
+ if (usePlayerStore.getState().selectedElementId) {
115
+ trackStudioEvent("keyboard_shortcut", { action: "duplicate" });
116
+ void cb.handleDuplicate();
117
+ }
118
+ }
119
+ return true;
120
+ }
121
+
122
+ /** Exported for tests: the shortcuts that act on the editor, each read as a combo at event time. */
66
123
  export function dispatchModifierKey(
67
124
  event: KeyboardEvent,
68
- key: string,
125
+ _key: string,
69
126
  cb: HotkeyCallbacks,
70
127
  ): boolean {
71
- if (
72
- !shouldIgnoreHistoryShortcut(event.target) &&
73
- handleUndoRedoKey(
128
+ if (!shouldIgnoreHistoryShortcut(event.target)) {
129
+ const handled = handleUndoRedoKey(
74
130
  event,
75
131
  () => {
76
132
  trackStudioEvent("keyboard_shortcut", { action: "undo" });
@@ -80,92 +136,26 @@ export function dispatchModifierKey(
80
136
  trackStudioEvent("keyboard_shortcut", { action: "redo" });
81
137
  void cb.handleRedo();
82
138
  },
83
- )
84
- )
85
- return true;
86
-
87
- if (event.key === "1") {
88
- event.preventDefault();
89
- trackStudioEvent("keyboard_shortcut", { action: "tab_compositions" });
90
- useDockLayoutStore.getState().activatePanel("compositions");
91
- return true;
92
- }
93
- if (event.key === "2") {
94
- event.preventDefault();
95
- trackStudioEvent("keyboard_shortcut", { action: "tab_assets" });
96
- useDockLayoutStore.getState().activatePanel("assets");
97
- return true;
98
- }
99
-
100
- if (key === "g" && !event.altKey && !isTypingTarget(event.target)) {
101
- event.preventDefault();
102
- if (cb.readOnlyPreview) return true;
103
- if (event.shiftKey) cb.onUngroupSelection?.();
104
- else cb.onGroupSelection?.();
105
- return true;
106
- }
107
-
108
- if (!event.shiftKey && !event.altKey && !isEditableTarget(event.target)) {
109
- // An active automation range owns Cmd+C/Cmd+V, same as Delete below: this
110
- // capture listener runs before useAutomationSelectionKeyboard's, so without
111
- // this both clipboards raced the same key. No preventDefault, so the
112
- // downstream handler still sees it.
113
- if (automationOwnsKey(event)) return true;
114
- if (key === "c") {
115
- if (cb.handleCopy()) {
116
- event.preventDefault();
117
- trackStudioEvent("keyboard_shortcut", { action: "copy" });
118
- }
119
- return true;
120
- }
121
- const previewOwnsMutation =
122
- cb.readOnlyPreview && cb.domEditSelectionRef.current !== null && !timelineOwnsKey(event);
123
- if (previewOwnsMutation && ["v", "x", "d"].includes(key)) {
124
- event.preventDefault();
125
- return true;
126
- }
127
- if (key === "v") {
128
- event.preventDefault();
129
- trackStudioEvent("keyboard_shortcut", { action: "paste" });
130
- void cb.handlePaste();
131
- return true;
132
- }
133
- if (key === "x") {
134
- if (usePlayerStore.getState().selectedElementId || cb.domEditSelectionRef.current) {
135
- event.preventDefault();
136
- trackStudioEvent("keyboard_shortcut", { action: "cut" });
137
- void cb.handleCut();
138
- }
139
- return true;
140
- }
141
- if (key === "d") {
142
- // Always own this key here, even with nothing selected — otherwise the
143
- // browser's own Cmd+D (bookmark this page) fires over the editor.
144
- event.preventDefault();
145
- if (usePlayerStore.getState().selectedElementId) {
146
- trackStudioEvent("keyboard_shortcut", { action: "duplicate" });
147
- void cb.handleDuplicate();
148
- }
149
- return true;
150
- }
139
+ );
140
+ if (handled) return true;
151
141
  }
152
- return false;
142
+ return dispatchTabKey(event) || dispatchGroupKey(event, cb) || dispatchClipboardKey(event, cb);
153
143
  }
154
144
 
155
145
  // fallow-ignore-next-line complexity
156
146
  /** Exported for tests: the unmodified-key half of the dispatcher, so the
157
147
  * Delete arbitration between keyframes, an automation range and the clip can
158
148
  * be asserted without standing up the whole hook. */
159
- export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): void {
149
+ export function dispatchPlainKey(event: KeyboardEvent, _key: string, cb: HotkeyCallbacks): void {
160
150
  if (ownsPlainKeys(event.target)) return;
161
151
  const keys = getStudioKeys();
162
- if (key === keys.zoomSelection && !event.shiftKey && !event.altKey) {
152
+ if (matchesKey(event, "zoomSelection")) {
163
153
  if (!zoomTimelineToSelectedClips()) return;
164
154
  event.preventDefault();
165
155
  return;
166
156
  }
167
157
 
168
- if (key === keys.fullscreen && !event.shiftKey && !event.altKey) {
158
+ if (matchesKey(event, "fullscreen")) {
169
159
  event.preventDefault();
170
160
  if (document.fullscreenElement) void document.exitFullscreen();
171
161
  else
@@ -173,7 +163,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
173
163
  return;
174
164
  }
175
165
 
176
- if (event.key === keys.split && !event.altKey) {
166
+ if (matchesKey(event, "split")) {
177
167
  // Reserve bare `s` for Split even when the current selection cannot split,
178
168
  // so secondary listeners do not reinterpret the same key as Snap toggle.
179
169
  event.preventDefault();
@@ -204,46 +194,43 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
204
194
  }
205
195
 
206
196
  // Only with a sound clip selected, so bare G still reaches the canvas grid toggle otherwise.
207
- if (key === keys.audioGain && !event.shiftKey && !event.altKey) {
197
+ if (matchesKey(event, "audioGain")) {
208
198
  if (!cb.readOnlyPreview && openAudioGainDialog()) {
209
199
  event.preventDefault();
210
200
  return;
211
201
  }
212
202
  }
213
203
 
214
- if (key === keys.razorTool && !event.shiftKey && !event.altKey) {
204
+ if (matchesKey(event, "razorTool")) {
215
205
  event.preventDefault();
216
206
  const { activeTool, setActiveTool } = usePlayerStore.getState();
217
207
  setActiveTool(activeTool === "razor" ? "select" : "razor");
218
208
  return;
219
209
  }
220
210
 
221
- if (key === keys.selectTool && !event.shiftKey && !event.altKey) {
211
+ if (matchesKey(event, "selectTool")) {
222
212
  event.preventDefault();
223
213
  usePlayerStore.getState().setActiveTool("select");
224
214
  return;
225
215
  }
226
216
 
227
- if (
228
- (key === keys.selectLeftward || key === keys.selectRightward) &&
229
- !event.shiftKey &&
230
- !event.altKey
231
- ) {
217
+ const leftward = matchesKey(event, "selectLeftward");
218
+ if (leftward || matchesKey(event, "selectRightward")) {
232
219
  event.preventDefault();
233
220
  const store = usePlayerStore.getState();
234
- if (key === keys.selectLeftward) store.selectLeftward();
221
+ if (leftward) store.selectLeftward();
235
222
  else store.selectRightward();
236
223
  return;
237
224
  }
238
225
 
239
226
  // CapCut returns to the select tool with "A"; playback's seek-to-in asks the same razorClaimsKey.
240
- if (razorClaimsKey(event, key)) {
227
+ if (razorClaimsKey(event)) {
241
228
  event.preventDefault();
242
229
  usePlayerStore.getState().setActiveTool("select");
243
230
  return;
244
231
  }
245
232
 
246
- if (event.key === "Escape") {
233
+ if (matchesKey(event, "cancel")) {
247
234
  const { activeTool, selectedElementId, setActiveTool, setSelectedElementId } =
248
235
  usePlayerStore.getState();
249
236
  if (activeTool === "razor") {
@@ -254,7 +241,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
254
241
  }
255
242
  }
256
243
 
257
- if ((event.key === "Delete" || event.key === "Backspace") && !event.altKey) {
244
+ if (matchesKey(event, "deleteSelected") || matchesKey(event, "deleteSelectedAlt")) {
258
245
  if (usePlayerStore.getState().selectedKeyframes.size > 0) {
259
246
  cb.onDeleteSelectedKeyframes();
260
247
  usePlayerStore.getState().clearSelectedKeyframes();
@@ -266,7 +253,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
266
253
  // is what lets the document-level handler still see the key instead of
267
254
  // the press reaching the clip delete below.
268
255
  if (usePlayerStore.getState().automationSelection) return;
269
- if (event.key === "Backspace") {
256
+ if (matchesKey(event, "resetKeyframes")) {
270
257
  const { selectedElementId, keyframeCache } = usePlayerStore.getState();
271
258
  if (selectedElementId && keyframeCache.has(selectedElementId) && cb.onResetKeyframes()) {
272
259
  event.preventDefault();
@@ -299,7 +286,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
299
286
  return;
300
287
  }
301
288
 
302
- if (event.key === keys.record && !event.shiftKey && !event.altKey && cb.onToggleRecording) {
289
+ if (matchesKey(event, "record") && cb.onToggleRecording) {
303
290
  event.preventDefault();
304
291
  cb.onToggleRecording();
305
292
  }