@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
@@ -32,6 +32,7 @@ import {
32
32
  } from "@hyperframes/core/audio-automation";
33
33
  import { clampNumber } from "../utils/studioHelpers";
34
34
  import { isTypingTarget } from "../utils/typingTarget";
35
+ import { matchesKey } from "../player/components/studioShortcuts";
35
36
  import type { AutomationSelection } from "../player/store/automationSelectionSlice";
36
37
  import type {
37
38
  AutomationLaneBinding,
@@ -40,17 +41,6 @@ import type {
40
41
 
41
42
  type PlayerState = ReturnType<typeof usePlayerStore.getState>;
42
43
 
43
- /**
44
- * A Cmd/Ctrl+<letter> chord. `e.key` is normalised because CapsLock makes it
45
- * "V"/"C", and useAppHotkeys already lowercases — a raw `e.key === "v"` test
46
- * would silently drop the keystroke here while that dispatcher still acted on
47
- * it. Shift and Alt are excluded for the same parity reason (useAppHotkeys
48
- * gates its own copy/paste on `!shiftKey && !altKey`).
49
- */
50
- function isChord(e: KeyboardEvent, letter: string): boolean {
51
- return (e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === letter;
52
- }
53
-
54
44
  /** A `TimelineElement`'s identity as the selection and lane bindings key by. */
55
45
  function elementKeyOf(element: TimelineElement): string {
56
46
  return element.key ?? element.id;
@@ -221,7 +211,7 @@ function handlePaste(
221
211
  state: PlayerState,
222
212
  lanes: UseAutomationLanesResult,
223
213
  ): boolean {
224
- if (!isChord(e, "v")) return false;
214
+ if (!matchesKey(e, "paste")) return false;
225
215
  const clip = readClipboard(state.timelineProjectId);
226
216
  if (!clip) return false;
227
217
  const sel = state.automationSelection;
@@ -271,7 +261,7 @@ function handleCopy(
271
261
  lanes: UseAutomationLanesResult,
272
262
  sel: AutomationSelection,
273
263
  ): boolean {
274
- if (!isChord(e, "c")) return false;
264
+ if (!matchesKey(e, "copy")) return false;
275
265
  const ctx = resolveSelectionContext(state, lanes, sel);
276
266
  if (!ctx) return false;
277
267
  if (!copyRange(state.timelineProjectId, ctx.lane, ctx.range, sel.t0, sel.t1)) return false;
@@ -298,8 +288,8 @@ function handleCopy(
298
288
  export function automationOwnsKey(e: KeyboardEvent): boolean {
299
289
  if (isTypingTarget(document.activeElement)) return false;
300
290
  const state = usePlayerStore.getState();
301
- if (isChord(e, "c")) return state.automationSelection !== null;
302
- if (!isChord(e, "v")) return false;
291
+ if (matchesKey(e, "copy")) return state.automationSelection !== null;
292
+ if (!matchesKey(e, "paste")) return false;
303
293
  const clip = readClipboard(state.timelineProjectId);
304
294
  if (!clip) return false;
305
295
  const element = findElement(state.elements, state.selectedElementId);
@@ -317,8 +307,7 @@ function handleDelete(
317
307
  lanes: UseAutomationLanesResult,
318
308
  sel: AutomationSelection,
319
309
  ): boolean {
320
- const isDeleteKey = e.key === "Delete" || e.key === "Backspace";
321
- if (!isDeleteKey || e.metaKey || e.ctrlKey) return false;
310
+ if (!matchesKey(e, "deleteSelected") && !matchesKey(e, "deleteSelectedAlt")) return false;
322
311
  const write = resolveDeleteWrite(state, lanes, sel);
323
312
  if (!write) return false;
324
313
  e.preventDefault();
@@ -348,7 +337,7 @@ export function useAutomationSelectionKeyboard({
348
337
  const sel = state.automationSelection;
349
338
  if (!sel) return;
350
339
 
351
- if (e.key === "Escape") {
340
+ if (matchesKey(e, "cancel")) {
352
341
  state.clearAutomationSelection();
353
342
  return;
354
343
  }
@@ -1,5 +1,5 @@
1
1
  import { useEffect, useCallback } from "react";
2
- import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";
2
+ import { matchesKey } from "../player/components/studioShortcuts";
3
3
  import { isTypingTarget } from "../utils/typingTarget";
4
4
 
5
5
  interface KeyframeKeyboardOptions {
@@ -12,8 +12,7 @@ export function useKeyframeKeyboard({ enabled, onAddKeyframe }: KeyframeKeyboard
12
12
  (e: KeyboardEvent) => {
13
13
  if (!enabled || !onAddKeyframe) return;
14
14
  if (isTypingTarget(document.activeElement)) return;
15
- if (e.metaKey || e.ctrlKey) return; // never shadow browser/system combos
16
- if (e.key.toLowerCase() !== STUDIO_PLAIN_KEYS.addKeyframe) return;
15
+ if (!matchesKey(e, "addKeyframe")) return;
17
16
  // K is also playback's stop key: claiming it here keeps playback from also pausing.
18
17
  e.preventDefault();
19
18
  e.stopImmediatePropagation();
@@ -2,6 +2,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
2
2
  // Timeline clip deletion: the marquee/multi path and the single-clip wrapper
3
3
  // the context menu uses. Extracted verbatim from useTimelineEditing.ts to keep
4
4
  // it under the studio 600-line cap, following useTimelineAssetDropOps.
5
+ import { keyHint } from "../player/components/studioShortcuts";
5
6
  import { useCallback, useRef, type MutableRefObject, type RefObject } from "react";
6
7
  import type { TimelineElement } from "../player";
7
8
  import { usePlayerStore } from "../player";
@@ -216,7 +217,7 @@ export function useTimelineDeleteOps({
216
217
  if (rippleChanges && !rippleFailed && !rippleNoticeShownRef.current) {
217
218
  rippleNoticeShownRef.current = true;
218
219
  showToast(
219
- "Ripple closed the gap on the main track. Undo (⌘Z) restores it, or turn off " +
220
+ `Ripple closed the gap on the main track. Undo (${keyHint("undo")}) restores it, or turn off ` +
220
221
  "Ripple in the timeline toolbar.",
221
222
  "info",
222
223
  );
package/src/index.ts CHANGED
@@ -5,7 +5,15 @@ export * from "./ui";
5
5
  export { EditorShell } from "./components/EditorShell";
6
6
  export type { EditorShellProps } from "./components/EditorShell";
7
7
  export { NLEPreview } from "./components/nle/NLEPreview";
8
- export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
8
+ export {
9
+ DEFAULT_SHORTCUT_SECTIONS,
10
+ DEFAULT_STUDIO_KEYS,
11
+ buildShortcutSections,
12
+ getStudioKeys,
13
+ setStudioKeys,
14
+ useStudioKeys,
15
+ } from "./player/components/studioShortcuts";
16
+ export type { StudioKeyAction, StudioKeys } from "./player/components/studioShortcuts";
9
17
  export { ShortcutsButton } from "./player/components/ShortcutsPanel";
10
18
  export { dispatchLinkShortcut } from "./hooks/linkShortcuts";
11
19
  export type { LinkShortcutCallbacks } from "./hooks/linkShortcuts";
@@ -1,4 +1,5 @@
1
1
  import { memo, useSyncExternalStore } from "react";
2
+ import { matchesKey } from "./studioShortcuts";
2
3
  import {
3
4
  deleteBeatAtCompositionTime,
4
5
  moveBeatCompositionTime,
@@ -184,7 +185,7 @@ function handleBeatDragPointerCancel(event: PointerEvent): void {
184
185
  }
185
186
 
186
187
  function handleBeatDragKeyDown(event: KeyboardEvent): void {
187
- if (event.key !== "Escape" || !beatDragActor) return;
188
+ if (!matchesKey(event, "cancel") || !beatDragActor) return;
188
189
  event.preventDefault();
189
190
  cancelBeatDrag();
190
191
  }
@@ -10,7 +10,7 @@ import { ClipMenuAudioItems } from "./clipMenuAudioItems";
10
10
  import { ClipMenuLinkItems } from "./clipMenuLinkItems";
11
11
  import { menuClasses } from "../../components/ui/menuStyle";
12
12
  import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
13
- import { SPLIT_SHORTCUT_HINT } from "./studioShortcuts";
13
+ import { keyHint, useStudioKeys } from "./studioShortcuts";
14
14
 
15
15
  const MENU_MARGIN = 8;
16
16
 
@@ -97,8 +97,9 @@ export const ClipContextMenu = memo(function ClipContextMenu({
97
97
  onDuplicate,
98
98
  canPaste,
99
99
  hostItems = [],
100
- splitShortcut = SPLIT_SHORTCUT_HINT,
100
+ splitShortcut,
101
101
  }: ClipContextMenuProps) {
102
+ const keys = useStudioKeys();
102
103
  const menuRef = useContextMenuDismiss(onClose);
103
104
  useMenuKeyboardNav(menuRef);
104
105
  const tools = useTimelineEditContextOptional().clipMenuTools !== false;
@@ -160,7 +161,9 @@ export const ClipContextMenu = memo(function ClipContextMenu({
160
161
  }}
161
162
  >
162
163
  <span>{splitLabel}</span>
163
- <span className="text-neutral-500 text-[10px] ml-3">{splitShortcut}</span>
164
+ <span className="text-neutral-500 text-[10px] ml-3">
165
+ {splitShortcut ?? keyHint("split", keys)}
166
+ </span>
164
167
  </button>
165
168
  )}
166
169
  {tools && splitLabel && (
@@ -212,7 +215,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
212
215
  }}
213
216
  >
214
217
  <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>
215
- <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>
218
+ <span className="text-neutral-500 text-[10px] ml-3">{keyHint("copy", keys)}</span>
216
219
  </button>
217
220
  )}
218
221
  {onPaste && (
@@ -228,7 +231,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
228
231
  }}
229
232
  >
230
233
  <span>Paste</span>
231
- <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>
234
+ <span className="text-neutral-500 text-[10px] ml-3">{keyHint("paste", keys)}</span>
232
235
  </button>
233
236
  )}
234
237
  {onDuplicate && (
@@ -242,7 +245,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
242
245
  }}
243
246
  >
244
247
  <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>
245
- <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>
248
+ <span className="text-neutral-500 text-[10px] ml-3">{keyHint("duplicate", keys)}</span>
246
249
  </button>
247
250
  )}
248
251
  </div>
@@ -8,7 +8,7 @@ import { Tooltip } from "../../components/ui";
8
8
  import { useMountEffect } from "../../hooks/useMountEffect";
9
9
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
10
10
  import { ShortcutsButton } from "./ShortcutsPanel";
11
- import type { ShortcutSection } from "./studioShortcuts";
11
+ import { keyHint, useStudioKeys, type ShortcutSection } from "./studioShortcuts";
12
12
  import { SpeedMenu } from "./SpeedMenu";
13
13
  import { VolumeControl } from "./VolumeControl";
14
14
  import { PreviewSeekBar } from "./PreviewSeekBar";
@@ -111,8 +111,9 @@ const FullscreenButton = memo(function FullscreenButton({
111
111
  isFullscreen: boolean;
112
112
  onToggleFullscreen: () => void;
113
113
  }) {
114
+ const fsKey = keyHint("fullscreen", useStudioKeys());
114
115
  return (
115
- <Tooltip label={isFullscreen ? "Exit fullscreen (F)" : "Enter fullscreen (F)"}>
116
+ <Tooltip label={isFullscreen ? `Exit fullscreen (${fsKey})` : `Enter fullscreen (${fsKey})`}>
116
117
  <button
117
118
  type="button"
118
119
  onClick={() => {
@@ -4,7 +4,7 @@ import { Popover, Tooltip } from "../../components/ui";
4
4
  import { flatActive, flatIdle } from "../../components/timelineToolbarStyles";
5
5
  import { usePlayerStore } from "../store/playerStore";
6
6
  import { useCompositionFps } from "../../utils/linkedClipPreferences";
7
- import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
7
+ import { useShortcutSections, type ShortcutSection } from "./studioShortcuts";
8
8
 
9
9
  interface ShortcutsPanelProps {
10
10
  disabled: boolean;
@@ -28,8 +28,9 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
28
28
  setInPoint,
29
29
  setOutPoint,
30
30
  onSeek,
31
- sections = DEFAULT_SHORTCUT_SECTIONS,
31
+ sections: hostSections,
32
32
  }: ShortcutsPanelProps) {
33
+ const sections = useShortcutSections(hostSections);
33
34
  const [showShortcuts, setShowShortcuts] = useState(false);
34
35
  const [jumpFrame, setJumpFrame] = useState("");
35
36
  const compositionFps = useCompositionFps();
@@ -9,6 +9,7 @@ import {
9
9
  type KeyboardEvent,
10
10
  type PointerEvent,
11
11
  } from "react";
12
+ import { matchesKey } from "./studioShortcuts";
12
13
  import {
13
14
  HF_AUDIO_FADE_IN_ATTR,
14
15
  HF_AUDIO_FADE_OUT_ATTR,
@@ -329,7 +330,7 @@ export function TimelineClipFades({
329
330
  if (dragging === null) return;
330
331
  const cancelOnWindowEscape = (e: globalThis.KeyboardEvent) => {
331
332
  const g = gesture.current;
332
- if (e.key !== "Escape" || !g) return;
333
+ if (!matchesKey(e, "cancel") || !g) return;
333
334
  e.preventDefault();
334
335
  e.stopPropagation();
335
336
  gesture.current = null;
@@ -1,4 +1,5 @@
1
1
  import { usePlayerStore, type TimelineElement } from "../store/playerStore";
2
+ import { keyHint } from "./studioShortcuts";
2
3
  import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
3
4
  import type { TimelineLinkEdit } from "./timelineCallbacks";
4
5
  import { linkedMembersOf } from "./audioClipLink";
@@ -61,7 +62,7 @@ function linkItem(
61
62
  const suffix = partnerSuffix(element, linkPair);
62
63
  return {
63
64
  label: `Link${suffix && ` to${suffix}`}`,
64
- ...(selectedPair ? { shortcut: "⌘L" } : {}),
65
+ ...(selectedPair ? { shortcut: keyHint("linkToggle") } : {}),
65
66
  run: () => onLinkEdit({ kind: "link", elements: linkPair }),
66
67
  };
67
68
  }
@@ -82,7 +83,7 @@ export function resolveLinkMenuItems(input: {
82
83
  if (canDetachAudio(element)) {
83
84
  items.push({
84
85
  label: "Detach audio",
85
- shortcut: "⌥⇧D",
86
+ shortcut: keyHint("detachAudio"),
86
87
  run: () => onLinkEdit({ kind: "detach", element }),
87
88
  });
88
89
  }
@@ -90,7 +91,7 @@ export function resolveLinkMenuItems(input: {
90
91
  if (linked) {
91
92
  items.push({
92
93
  label: `Unlink${partnerSuffix(element, members) && ` from${partnerSuffix(element, members)}`}`,
93
- shortcut: "⌘L",
94
+ shortcut: keyHint("linkToggle"),
94
95
  run: () => onLinkEdit({ kind: "unlink", elements: members }),
95
96
  });
96
97
  } else {
@@ -108,7 +109,7 @@ export function resolveLinkMenuItems(input: {
108
109
  if (linked && onDeleteElementOnly) {
109
110
  items.push({
110
111
  label: "Delete this clip only",
111
- shortcut: "⌥⌫",
112
+ shortcut: keyHint("deleteLinked"),
112
113
  destructive: true,
113
114
  run: () => onDeleteElementOnly(element),
114
115
  });
@@ -0,0 +1,99 @@
1
+ // @vitest-environment happy-dom
2
+ import { afterEach, describe, expect, it, vi } from "vitest";
3
+ import { formatCombo, matchCombo, parseCombo } from "./studioCombo";
4
+ import { getStudioKey, keyHint, matchesKey, setStudioKeys } from "./studioShortcuts";
5
+
6
+ afterEach(() => {
7
+ setStudioKeys(null);
8
+ vi.restoreAllMocks();
9
+ });
10
+
11
+ const press = (init: KeyboardEventInit) => new KeyboardEvent("keydown", init);
12
+ const matches = (text: string, init: KeyboardEventInit) =>
13
+ matchCombo(press(init), parseCombo(text)!);
14
+
15
+ describe("combo model", () => {
16
+ it("parses characters, named keys and modifiers", () => {
17
+ expect(parseCombo("B")).toMatchObject({ key: "b", named: false });
18
+ expect(parseCombo("Space")).toMatchObject({ key: "Space", named: true });
19
+ expect(parseCombo("mod+shift+z")).toMatchObject({ mod: true, shift: true, key: "z" });
20
+ expect(parseCombo("cmd++")).toMatchObject({ meta: true, key: "+" });
21
+ });
22
+
23
+ it("refuses what cannot be matched: modifier-only, unknown, empty, and Ctrl+Alt (AltGr on Windows)", () => {
24
+ for (const bad of [
25
+ "ctrl",
26
+ "shift+",
27
+ "",
28
+ "mod+ab",
29
+ "hyper+x",
30
+ "ctrl+alt+x",
31
+ "mod+alt+x",
32
+ "Spacebar",
33
+ ]) {
34
+ expect(parseCombo(bad), bad).toBeNull();
35
+ }
36
+ expect(parseCombo("cmd+alt+x")).not.toBeNull();
37
+ });
38
+
39
+ it("mod is Cmd or Ctrl; cmd and ctrl are exact; extra modifiers never match", () => {
40
+ expect(matches("mod+c", { key: "c", metaKey: true })).toBe(true);
41
+ expect(matches("mod+c", { key: "c", ctrlKey: true })).toBe(true);
42
+ expect(matches("mod+c", { key: "c" })).toBe(false);
43
+ expect(matches("mod+c", { key: "c", metaKey: true, shiftKey: true })).toBe(false);
44
+ expect(matches("cmd+c", { key: "c", ctrlKey: true })).toBe(false);
45
+ expect(matches("c", { key: "c", metaKey: true })).toBe(false);
46
+ });
47
+
48
+ it("characters match e.key (so layouts follow the typed letter), named keys match e.code", () => {
49
+ expect(matches("a", { key: "a", code: "KeyQ" })).toBe(true);
50
+ expect(matches("a", { key: "q", code: "KeyA" })).toBe(false);
51
+ expect(matches("Space", { key: " ", code: "Space" })).toBe(true);
52
+ expect(
53
+ matches("shift+ArrowLeft", { key: "ArrowLeft", code: "ArrowLeft", shiftKey: true }),
54
+ ).toBe(true);
55
+ expect(matches("alt+shift+d", { key: "∂", code: "KeyD", altKey: true, shiftKey: true })).toBe(
56
+ true,
57
+ );
58
+ });
59
+
60
+ it("formats like the shortcut lists do", () => {
61
+ expect(formatCombo(parseCombo("mod+shift+z")!)).toBe("⌘⇧Z");
62
+ expect(formatCombo(parseCombo("alt+shift+d")!)).toBe("⌥⇧D");
63
+ expect(formatCombo(parseCombo("ArrowLeft")!)).toBe("←");
64
+ expect(formatCombo(parseCombo("[")!)).toBe("[");
65
+ });
66
+ });
67
+
68
+ describe("resolver with combos", () => {
69
+ it("accepts a combo for an action that today takes a single key, and the list follows", () => {
70
+ setStudioKeys({ fullscreen: "mod+shift+f" });
71
+ expect(getStudioKey("fullscreen")).toBe("mod+shift+f");
72
+ expect(keyHint("fullscreen")).toBe("⌘⇧F");
73
+ expect(matchesKey(press({ key: "F", metaKey: true, shiftKey: true }), "fullscreen")).toBe(true);
74
+ expect(matchesKey(press({ key: "f" }), "fullscreen")).toBe(false);
75
+ });
76
+
77
+ it("keeps a single character working and canonical", () => {
78
+ setStudioKeys({ mute: "X" });
79
+ expect(getStudioKey("mute")).toBe("x");
80
+ expect(matchesKey(press({ key: "x" }), "mute")).toBe(true);
81
+ });
82
+
83
+ it("refuses a map with an AltGr combo or two actions on one combo, keeping every default", () => {
84
+ vi.spyOn(console, "warn").mockImplementation(() => {});
85
+ setStudioKeys({ mute: "ctrl+alt+m" });
86
+ expect(getStudioKey("mute")).toBe("m");
87
+ setStudioKeys({ mute: "mod+k", record: "cmd+k" });
88
+ expect(getStudioKey("mute")).toBe("m");
89
+ expect(getStudioKey("record")).toBe("r");
90
+ });
91
+ });
92
+
93
+ describe("combos with symbol keys", () => {
94
+ it("matches a symbol whatever Shift it needs, and refuses shift+symbol", () => {
95
+ expect(matches("?", { key: "?", shiftKey: true })).toBe(true);
96
+ expect(matches("mod++", { key: "+", metaKey: true, shiftKey: true })).toBe(true);
97
+ expect(parseCombo("shift+1")).toBeNull();
98
+ });
99
+ });
@@ -0,0 +1,108 @@
1
+ export interface Combo {
2
+ mod: boolean;
3
+ meta: boolean;
4
+ ctrl: boolean;
5
+ shift: boolean;
6
+ alt: boolean;
7
+ key: string;
8
+ named: boolean;
9
+ }
10
+
11
+ const NAMED = new Set([
12
+ "Space",
13
+ "ArrowLeft",
14
+ "ArrowRight",
15
+ "ArrowUp",
16
+ "ArrowDown",
17
+ "Home",
18
+ "End",
19
+ "PageUp",
20
+ "PageDown",
21
+ "Delete",
22
+ "Backspace",
23
+ "Escape",
24
+ "Enter",
25
+ "Tab",
26
+ ]);
27
+ const SYMBOL: Record<string, string> = {
28
+ ArrowLeft: "←",
29
+ ArrowRight: "→",
30
+ ArrowUp: "↑",
31
+ ArrowDown: "↓",
32
+ Delete: "Del",
33
+ Backspace: "⌫",
34
+ Escape: "Esc",
35
+ };
36
+ const MODIFIERS = new Set(["mod", "cmd", "ctrl", "shift", "alt"]);
37
+
38
+ /** "mod+shift+z", "Space", "b": mod is Cmd or Ctrl; Ctrl+Alt is refused because Windows sends AltGr as Ctrl+Alt. */
39
+ export function parseCombo(text: string): Combo | null {
40
+ const split = text.length > 1 ? text.slice(0, -1).lastIndexOf("+") : -1;
41
+ const tokens =
42
+ split < 0
43
+ ? []
44
+ : text
45
+ .slice(0, split)
46
+ .split("+")
47
+ .map((t) => t.toLowerCase());
48
+ const key = text.slice(split + 1);
49
+ const named = NAMED.has(key);
50
+ const symbol = !named && !/^[A-Za-z]$/.test(key);
51
+ if (tokens.some((t) => !MODIFIERS.has(t)) || (!named && [...key].length !== 1)) return null;
52
+ if (symbol && tokens.includes("shift")) return null;
53
+ const combo = {
54
+ mod: tokens.includes("mod"),
55
+ meta: tokens.includes("cmd"),
56
+ ctrl: tokens.includes("ctrl"),
57
+ shift: tokens.includes("shift"),
58
+ alt: tokens.includes("alt"),
59
+ key: named ? key : key.toLowerCase(),
60
+ named,
61
+ };
62
+ return combo.alt && (combo.ctrl || combo.mod) ? null : combo;
63
+ }
64
+
65
+ /** The one string a combo is stored and compared as. */
66
+ export function comboText(c: Combo): string {
67
+ const mods = [
68
+ c.mod && "mod",
69
+ c.meta && "cmd",
70
+ c.ctrl && "ctrl",
71
+ c.alt && "alt",
72
+ c.shift && "shift",
73
+ ];
74
+ return [...mods.filter(Boolean), c.key].join("+");
75
+ }
76
+
77
+ const namedMatches = (e: ComboEvent, name: string) =>
78
+ e.code === name || e.key === (name === "Space" ? " " : name);
79
+
80
+ function charMatches(e: ComboEvent, c: Combo): boolean {
81
+ if (e.key.toLowerCase() === c.key) return true;
82
+ // Option rewrites e.key on macOS (Option+D is "∂"), so fall back to the physical key.
83
+ const code = /^[0-9]$/.test(c.key) ? `Digit${c.key}` : `Key${c.key.toUpperCase()}`;
84
+ return e.altKey && /^[a-z0-9]$/.test(c.key) && e.code === code;
85
+ }
86
+
87
+ export type ComboEvent = Pick<
88
+ KeyboardEvent,
89
+ "key" | "altKey" | "ctrlKey" | "metaKey" | "shiftKey"
90
+ > & {
91
+ code?: string;
92
+ };
93
+
94
+ export function matchCombo(e: ComboEvent, c: Combo): boolean {
95
+ const symbol = !c.named && !/^[a-z]$/.test(c.key);
96
+ if ((!symbol && !!e.shiftKey !== c.shift) || !!e.altKey !== c.alt) return false;
97
+ const modsOk = c.mod ? e.metaKey || e.ctrlKey : !!e.metaKey === c.meta && !!e.ctrlKey === c.ctrl;
98
+ return modsOk && (c.named ? namedMatches(e, c.key) : charMatches(e, c));
99
+ }
100
+
101
+ export function formatCombo(c: Combo): string {
102
+ const mods = `${c.ctrl ? "⌃" : ""}${c.alt ? "⌥" : ""}${c.mod || c.meta ? "⌘" : ""}${c.shift ? "⇧" : ""}`;
103
+ return mods + (SYMBOL[c.key] ?? (c.named ? c.key : c.key.toUpperCase()));
104
+ }
105
+
106
+ /** Two combos clash when one press could satisfy both; Cmd and Ctrl both count as mod. */
107
+ export const comboClashKey = (c: Combo) =>
108
+ [c.mod || c.meta || c.ctrl, c.alt, c.shift, c.key].join("|");
@@ -0,0 +1,124 @@
1
+ // @vitest-environment happy-dom
2
+ import React, { act } from "react";
3
+ import { createRoot } from "react-dom/client";
4
+ import { afterEach, describe, expect, it, vi } from "vitest";
5
+ import {
6
+ DEFAULT_SHORTCUT_SECTIONS,
7
+ DEFAULT_STUDIO_KEYS,
8
+ getShortcutSections,
9
+ getStudioKey,
10
+ setStudioKeys,
11
+ useStudioKeys,
12
+ } from "./studioShortcuts";
13
+
14
+ (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
15
+
16
+ afterEach(() => {
17
+ setStudioKeys(null);
18
+ document.body.innerHTML = "";
19
+ vi.restoreAllMocks();
20
+ });
21
+
22
+ const hintFor = (label: string) =>
23
+ getShortcutSections()
24
+ .flatMap((s) => s.hints)
25
+ .find((h) => h.label === label)?.key;
26
+
27
+ describe("studio key resolver", () => {
28
+ it("answers today's keys when no host overrides anything", () => {
29
+ expect(DEFAULT_STUDIO_KEYS).toMatchObject({
30
+ mute: "m",
31
+ pause: "k",
32
+ shuttleBack: "j",
33
+ shuttleForward: "l",
34
+ inPoint: "i",
35
+ outPoint: "o",
36
+ seekToIn: "a",
37
+ seekToOut: "e",
38
+ fullscreen: "f",
39
+ split: "s",
40
+ record: "r",
41
+ addKeyframe: "k",
42
+ audioGain: "g",
43
+ zoomSelection: "z",
44
+ selectTool: "v",
45
+ razorTool: "b",
46
+ selectLeftward: "[",
47
+ selectRightward: "]",
48
+ exitRazor: "a",
49
+ snap: "s",
50
+ grid: "g",
51
+ timelineSnap: "n",
52
+ });
53
+ expect(getShortcutSections()).toEqual(DEFAULT_SHORTCUT_SECTIONS);
54
+ });
55
+
56
+ it("normalises an override to lower case and leaves the other actions alone", () => {
57
+ setStudioKeys({ mute: "X" });
58
+ expect(getStudioKey("mute")).toBe("x");
59
+ expect(getStudioKey("fullscreen")).toBe("f");
60
+ });
61
+
62
+ it("lists the remapped key in the shortcut list", () => {
63
+ setStudioKeys({ mute: "x", seekToIn: "u" });
64
+ expect(hintFor("Toggle mute")).toBe("X");
65
+ expect(hintFor("Jump to in-point")).toBe("U");
66
+ expect(hintFor("Toggle loop")).toBe("⇧L");
67
+ setStudioKeys({ shuttleForward: "y" });
68
+ expect(hintFor("Play forward")).toBe("Y");
69
+ expect(hintFor("Toggle loop")).toBe("⇧L");
70
+ });
71
+
72
+ it("refuses a map that binds two actions to one key and keeps every default", () => {
73
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
74
+ setStudioKeys({ mute: "x", razorTool: "x" });
75
+ expect(getStudioKey("mute")).toBe("m");
76
+ expect(getStudioKey("razorTool")).toBe("b");
77
+ setStudioKeys({ mute: "x", razorTool: "x" });
78
+ expect(warn).toHaveBeenCalledTimes(2);
79
+ });
80
+
81
+ it("refuses a key that is not one character", () => {
82
+ vi.spyOn(console, "warn").mockImplementation(() => {});
83
+ setStudioKeys({ razorTool: "y", mute: "ctrl" });
84
+ expect(getStudioKey("mute")).toBe("m");
85
+ expect(getStudioKey("razorTool")).toBe("b");
86
+ setStudioKeys({ razorTool: "y", toString: "z" } as never);
87
+ expect(getStudioKey("razorTool")).toBe("b");
88
+ });
89
+
90
+ it("still lets the keys Studio already shares (K stop/keyframe, S split/snap) share", () => {
91
+ setStudioKeys({ mute: "x" });
92
+ expect(getStudioKey("pause")).toBe(getStudioKey("addKeyframe"));
93
+ expect(getStudioKey("mute")).toBe("x");
94
+ });
95
+
96
+ it("re-renders a component using the hook when the host swaps the map", () => {
97
+ function Probe() {
98
+ return <span data-probe>{useStudioKeys().razorTool}</span>;
99
+ }
100
+ const host = document.createElement("div");
101
+ document.body.append(host);
102
+ const root = createRoot(host);
103
+ act(() => root.render(<Probe />));
104
+ expect(host.textContent).toBe("b");
105
+ act(() => setStudioKeys({ razorTool: "y" }));
106
+ expect(host.textContent).toBe("y");
107
+ act(() => root.unmount());
108
+ });
109
+ });
110
+
111
+ describe("lists follow combos", () => {
112
+ it("shows the remapped combos and keeps today's default text", () => {
113
+ expect(hintFor("Undo")).toBe("⌘Z");
114
+ expect(hintFor("Redo")).toBe("⌘⇧Z");
115
+ expect(hintFor("Play / Pause")).toBe("Space");
116
+ expect(hintFor("Step 1 frame")).toBe("←/→");
117
+ expect(hintFor("Step 10 frames")).toBe("⇧←/⇧→");
118
+ expect(hintFor("Toggle loop")).toBe("⇧L");
119
+ setStudioKeys({ undo: "mod+u", playPause: "p", frameBack: "y", frameForward: "u" });
120
+ expect(hintFor("Undo")).toBe("⌘U");
121
+ expect(hintFor("Play / Pause")).toBe("P");
122
+ expect(hintFor("Step 1 frame")).toBe("Y/U");
123
+ });
124
+ });