mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* fix(studio): a focused video or audio player keeps its arrow and play keys * fix(studio): every remaining shortcut asks the shared typing check
362 lines
14 KiB
TypeScript
362 lines
14 KiB
TypeScript
/**
|
|
* Keyboard surface for the active automation selection: Escape clears,
|
|
* Delete/Backspace deletes every breakpoint inside the selection box, Cmd/Ctrl+C
|
|
* copies its span, Cmd/Ctrl+V pastes at the selection's start (or the playhead) onto the
|
|
* selected clip's lane. Sibling of
|
|
* useKeyframeKeyboard and copies its contract: capture phase so playback
|
|
* shortcuts cannot swallow keys we act on, inert while any text input has
|
|
* focus, and a key is only consumed when it does something.
|
|
*
|
|
* Falling through is NOT enough to keep clip-level copy/paste working:
|
|
* useAppHotkeys listens on `window` with capture, so it always runs before this
|
|
* document-level listener and `stopImmediatePropagation` here comes too late.
|
|
* `automationOwnsKey` below is the arbitration that actually works — the
|
|
* central dispatcher asks it first and stands down.
|
|
*/
|
|
import { useEffect } from "react";
|
|
import { usePlayerStore, type TimelineElement } from "../player/store/playerStore";
|
|
import { laneFor, withLane } from "../player/components/automationLaneGeometry";
|
|
import { pointInSelection, replaceRange } from "../player/components/automationLaneSelection";
|
|
import {
|
|
copyRange,
|
|
isLastPasteSpan,
|
|
markLastPaste,
|
|
pastePoints,
|
|
readClipboard,
|
|
} from "../player/components/automationClipboard";
|
|
import {
|
|
resolveAutomationRange,
|
|
type AutomationRange,
|
|
type HfAutomation,
|
|
type HfAutomationLane,
|
|
} from "@hyperframes/core/audio-automation";
|
|
import { clampNumber } from "../utils/studioHelpers";
|
|
import { isTypingTarget } from "../utils/typingTarget";
|
|
import type { AutomationSelection } from "../player/store/automationSelectionSlice";
|
|
import type {
|
|
AutomationLaneBinding,
|
|
UseAutomationLanesResult,
|
|
} from "../player/components/useAutomationLanes";
|
|
|
|
type PlayerState = ReturnType<typeof usePlayerStore.getState>;
|
|
|
|
/**
|
|
* A Cmd/Ctrl+<letter> chord. `e.key` is normalised because CapsLock makes it
|
|
* "V"/"C", and useAppHotkeys already lowercases — a raw `e.key === "v"` test
|
|
* would silently drop the keystroke here while that dispatcher still acted on
|
|
* it. Shift and Alt are excluded for the same parity reason (useAppHotkeys
|
|
* gates its own copy/paste on `!shiftKey && !altKey`).
|
|
*/
|
|
function isChord(e: KeyboardEvent, letter: string): boolean {
|
|
return (e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === letter;
|
|
}
|
|
|
|
/** A `TimelineElement`'s identity as the selection and lane bindings key by. */
|
|
function elementKeyOf(element: TimelineElement): string {
|
|
return element.key ?? element.id;
|
|
}
|
|
|
|
function findElement(elements: TimelineElement[], key: string | null): TimelineElement | null {
|
|
if (!key) return null;
|
|
return elements.find((el) => elementKeyOf(el) === key) ?? null;
|
|
}
|
|
|
|
/**
|
|
* A selection's element, binding, lane and range — the resolution Delete and
|
|
* copy both need. Null when the clip is gone, its lane is read-only, or the
|
|
* target no longer resolves to a range.
|
|
*/
|
|
function resolveSelectionContext(
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
sel: AutomationSelection,
|
|
): { binding: AutomationLaneBinding; lane: HfAutomationLane; range: AutomationRange } | null {
|
|
const element = findElement(state.elements, sel.elementKey);
|
|
if (!element) return null;
|
|
const binding = lanes.bind(element, sel.elementKey === state.selectedElementId);
|
|
if (binding.readOnly) return null;
|
|
const range = resolveAutomationRange(sel.target, binding.chain ?? undefined);
|
|
if (!range) return null;
|
|
return { binding, lane: laneFor(binding.automation, sel.target), range };
|
|
}
|
|
|
|
/**
|
|
* The write that deletes the breakpoints inside the active selection, or null when
|
|
* there is nothing to do: the clip is gone, its lane is read-only, the target no
|
|
* longer resolves to a range, or the selection covers no breakpoints.
|
|
*
|
|
* Deletes them outright rather than emptying the span behind anchor points. Anchors
|
|
* are what `replaceRange` exists for, and they are right for a shape insert or a
|
|
* paste — the envelope either side of the edit must not move. But Delete over a
|
|
* selection is the author saying "these points, gone", and answering that with two
|
|
* NEW points at the selection's edges reads as the delete not having worked. The
|
|
* envelope between the surviving neighbours re-interpolates, which is what deleting
|
|
* a breakpoint means everywhere else in the lane (right-clicking one does exactly
|
|
* this).
|
|
*
|
|
* Both axes of the selection box, edges included: what Delete removes is exactly
|
|
* what the lane drew a ring around. A point at the right time but outside the box's
|
|
* value bounds stays — which is the whole reason the box has them.
|
|
*/
|
|
function resolveDeleteWrite(
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
sel: AutomationSelection,
|
|
): { onCommit: AutomationLaneBinding["onCommit"]; next: HfAutomation } | null {
|
|
const ctx = resolveSelectionContext(state, lanes, sel);
|
|
if (!ctx) return null;
|
|
const points = ctx.lane.points.filter((p) => !pointInSelection(p, sel));
|
|
// Nothing inside is nothing to do — and it must stay a no-op rather than
|
|
// writing, or Delete over a smooth stretch would push an undo entry that
|
|
// changed nothing.
|
|
if (points.length === ctx.lane.points.length) return null;
|
|
return {
|
|
onCommit: ctx.binding.onCommit,
|
|
next: withLane(ctx.binding.automation, { target: sel.target, points }),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The lane target Cmd+V writes to: the active selection's, when the
|
|
* selection belongs to the same clip the paste is landing on, else the
|
|
* clip's first automation lane. A selection left over on a different clip
|
|
* does not redirect the paste.
|
|
*/
|
|
function pasteTargetName(
|
|
binding: AutomationLaneBinding,
|
|
elementKey: string,
|
|
sel: AutomationSelection | null,
|
|
): string | undefined {
|
|
if (sel && sel.elementKey === elementKey) return sel.target;
|
|
return binding.lanes[0]?.target;
|
|
}
|
|
|
|
/**
|
|
* Where Cmd+V lands, or null when nothing is selected, the clip's lanes are
|
|
* read-only, or it has no automation lane to fall back to.
|
|
*/
|
|
function resolvePasteTarget(
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
sel: AutomationSelection | null,
|
|
): {
|
|
elementKey: string;
|
|
element: TimelineElement;
|
|
target: string;
|
|
binding: AutomationLaneBinding;
|
|
lane: HfAutomationLane;
|
|
range: AutomationRange;
|
|
} | null {
|
|
const element = findElement(state.elements, state.selectedElementId);
|
|
if (!element) return null;
|
|
const elementKey = elementKeyOf(element);
|
|
const binding = lanes.bind(element, true);
|
|
if (binding.readOnly) return null;
|
|
const target = pasteTargetName(binding, elementKey, sel);
|
|
if (!target) return null;
|
|
const range = resolveAutomationRange(target, binding.chain ?? undefined);
|
|
if (!range) return null;
|
|
return { elementKey, element, target, binding, lane: laneFor(binding.automation, target), range };
|
|
}
|
|
|
|
/** Is the playhead over this clip? Mirrors TimelineAutomationLaneSlot's own
|
|
* in-clip test, which is what decides a lane draws a playhead at all. */
|
|
function playheadInClip(state: PlayerState, element: TimelineElement): boolean {
|
|
return (
|
|
state.currentTime >= element.start && state.currentTime <= element.start + element.duration
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Clip-local seconds a `span`-wide paste should start at, or null when nothing
|
|
* can anchor it.
|
|
*
|
|
* Three refusals, all of which used to be silent mispastes:
|
|
* - A span wider than the clip has nowhere to go. Clamping the start to 0 still
|
|
* writes breakpoints past the clip's end and leaves a selection whose far
|
|
* edge can never be grabbed again.
|
|
* - A playhead outside the clip is not an anchor. It used to collapse to the
|
|
* clip's own t=0, so a playhead at 0:00 pasted into the head of a clip
|
|
* starting at 0:30.
|
|
* - No selection on this clip and no in-clip playhead means no anchor at all.
|
|
*
|
|
* A repeated Cmd+V chains. Paste leaves its own span selected (the user's only
|
|
* feedback that it landed), so anchoring at `sel.t0` unconditionally made the
|
|
* second press overwrite the first. When the live selection is exactly the mark
|
|
* the last paste left, anchor at its END; a selection the user drew themselves
|
|
* still pastes at its start.
|
|
*/
|
|
function pasteAnchor(
|
|
state: PlayerState,
|
|
element: TimelineElement,
|
|
span: number,
|
|
sel: AutomationSelection | null,
|
|
): number | null {
|
|
if (span > element.duration) return null;
|
|
const onThisElement = sel !== null && sel.elementKey === elementKeyOf(element);
|
|
const raw = onThisElement
|
|
? isLastPasteSpan(sel)
|
|
? sel.t1
|
|
: sel.t0
|
|
: playheadInClip(state, element)
|
|
? state.currentTime - element.start
|
|
: null;
|
|
if (raw === null) return null;
|
|
// Keeps the whole pasted span inside the clip — including a chain that has
|
|
// walked to the end — so its own selection stays grabbable.
|
|
return clampNumber(raw, 0, element.duration - span);
|
|
}
|
|
|
|
let latestPaste = 0;
|
|
|
|
/**
|
|
* Cmd/Ctrl+V: paste the clipboard onto the selected clip's lane, at the active
|
|
* selection or the playhead. Returns false (untouched event) when the chord
|
|
* doesn't match, there is nothing to paste, or no lane can take it.
|
|
* Checked ahead of the "no selection" guard in the handler below: paste must
|
|
* work from the playhead with no active selection at all.
|
|
*/
|
|
function handlePaste(
|
|
e: KeyboardEvent,
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
): boolean {
|
|
if (!isChord(e, "v")) return false;
|
|
const clip = readClipboard(state.timelineProjectId);
|
|
if (!clip) return false;
|
|
const sel = state.automationSelection;
|
|
const paste = resolvePasteTarget(state, lanes, sel);
|
|
if (!paste) return false;
|
|
const atT = pasteAnchor(state, paste.element, clip.span, sel);
|
|
if (atT === null) return false;
|
|
|
|
const t1 = atT + clip.span;
|
|
const inner = pastePoints(clip, paste.range, atT);
|
|
const points = replaceRange({ lane: paste.lane, range: paste.range, t0: atT, t1, inner });
|
|
|
|
e.preventDefault();
|
|
e.stopImmediatePropagation();
|
|
const saved = paste.binding.onCommit(
|
|
withLane(paste.binding.automation, { target: paste.target, points }),
|
|
);
|
|
const seq = ++latestPaste;
|
|
const mark = {
|
|
elementKey: paste.elementKey,
|
|
target: paste.target,
|
|
t0: atT,
|
|
t1,
|
|
v0: paste.range.min,
|
|
v1: paste.range.max,
|
|
};
|
|
// Once the latest paste lands, and only over the selection it was pasted at, select
|
|
// and mark its full-height span: the feedback that it landed, what a second Cmd+V
|
|
// chains after, and what Delete takes back in one press.
|
|
void saved.then((outcome) => {
|
|
if (outcome && outcome.status !== "saved") return;
|
|
const current = usePlayerStore.getState();
|
|
const moved = current.selectedElementId !== state.selectedElementId;
|
|
if (seq !== latestPaste || moved || current.automationSelection !== sel) return;
|
|
current.setAutomationSelection(mark);
|
|
markLastPaste(mark);
|
|
});
|
|
return true;
|
|
}
|
|
|
|
/** Cmd/Ctrl+C on the active selection. Returns false when the chord doesn't
|
|
* match, the selection no longer resolves to a copyable lane, or the lane is
|
|
* empty so there is no shape to capture. */
|
|
function handleCopy(
|
|
e: KeyboardEvent,
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
sel: AutomationSelection,
|
|
): boolean {
|
|
if (!isChord(e, "c")) return false;
|
|
const ctx = resolveSelectionContext(state, lanes, sel);
|
|
if (!ctx) return false;
|
|
if (!copyRange(state.timelineProjectId, ctx.lane, ctx.range, sel.t0, sel.t1)) return false;
|
|
e.preventDefault();
|
|
e.stopImmediatePropagation();
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Will an automation range claim this keystroke? Asked by useAppHotkeys, which
|
|
* listens on `window` with capture and therefore always runs BEFORE this
|
|
* hook's document listener — so `stopImmediatePropagation` cannot arbitrate and
|
|
* the dispatcher has to stand down of its own accord. Without it Cmd+C armed
|
|
* both clipboards and Cmd+V ran the whole clip-duplication path (read file →
|
|
* insert → save with history → reload preview) alongside the automation write:
|
|
* two async read-modify-writes of one file from one keypress.
|
|
*
|
|
* Store and clipboard only, no lane binding, so the dispatcher can call it
|
|
* without holding the binding factory. That leaves one accepted residual: the
|
|
* predicate cannot see a read-only lane or an unresolvable target, so in those rare cases
|
|
* the keystroke is a no-op instead of falling through to clip copy/paste. A
|
|
* dead key beats today's double write.
|
|
*/
|
|
export function automationOwnsKey(e: KeyboardEvent): boolean {
|
|
if (isTypingTarget(document.activeElement)) return false;
|
|
const state = usePlayerStore.getState();
|
|
if (isChord(e, "c")) return state.automationSelection !== null;
|
|
if (!isChord(e, "v")) return false;
|
|
const clip = readClipboard(state.timelineProjectId);
|
|
if (!clip) return false;
|
|
const element = findElement(state.elements, state.selectedElementId);
|
|
if (!element) return false;
|
|
// Same anchor resolution the handler uses, so predicate and handler cannot
|
|
// disagree about whether the paste has somewhere to land.
|
|
return pasteAnchor(state, element, clip.span, state.automationSelection) !== null;
|
|
}
|
|
|
|
/** Delete/Backspace on the active selection. Returns false when the key
|
|
* doesn't match or there is nothing to empty. */
|
|
function handleDelete(
|
|
e: KeyboardEvent,
|
|
state: PlayerState,
|
|
lanes: UseAutomationLanesResult,
|
|
sel: AutomationSelection,
|
|
): boolean {
|
|
const isDeleteKey = e.key === "Delete" || e.key === "Backspace";
|
|
if (!isDeleteKey || e.metaKey || e.ctrlKey) return false;
|
|
const write = resolveDeleteWrite(state, lanes, sel);
|
|
if (!write) return false;
|
|
e.preventDefault();
|
|
e.stopImmediatePropagation();
|
|
void write.onCommit(write.next);
|
|
return true;
|
|
}
|
|
|
|
export function useAutomationSelectionKeyboard({
|
|
lanes,
|
|
}: {
|
|
lanes: UseAutomationLanesResult;
|
|
}): void {
|
|
useEffect(() => {
|
|
const handler = (e: KeyboardEvent): void => {
|
|
if (isTypingTarget(document.activeElement)) return;
|
|
// Somebody upstream already claimed this key. useAppHotkeys is on
|
|
// window/capture so it always runs first, and it deliberately lets a
|
|
// keyframe selection outrank an automation range on Delete — without
|
|
// this, that keystroke deleted the keyframes there AND emptied the range
|
|
// here, two edits from one press. preventDefault does not stop
|
|
// propagation, so the claim has to be read, not assumed.
|
|
if (e.defaultPrevented) return;
|
|
const state = usePlayerStore.getState();
|
|
if (handlePaste(e, state, lanes)) return;
|
|
|
|
const sel = state.automationSelection;
|
|
if (!sel) return;
|
|
|
|
if (e.key === "Escape") {
|
|
state.clearAutomationSelection();
|
|
return;
|
|
}
|
|
if (handleCopy(e, state, lanes, sel)) return;
|
|
handleDelete(e, state, lanes, sel);
|
|
};
|
|
document.addEventListener("keydown", handler, true);
|
|
return () => document.removeEventListener("keydown", handler, true);
|
|
}, [lanes]);
|
|
}
|