Files
hyperframes/packages/studio/src/hooks/useAutomationSelectionKeyboard.ts
T
Vance IngallsandClaude Opus 5 4dacf2842e fix(studio): close the typecheck and fallow gaps wa-18b-reschedule opened
useAutomationLanes.ts's write() assumed gesture-scoped coalescing and a
preview-only commit that useDomEditAttributeCommits.ts never grew — backported
that option support from its own later commit so the two sides of the API
agree. The paste path and its tests were missing the box selection's v0/v1
bounds a sibling commit added to AutomationSelection. The FX panel's carve
controls still edited the six mechanism numbers (maxCutDb, bands,
intelligibilityBias) after carveProfile() collapsed authoring to one Strength
knob, so those fields no longer existed on HfCarveSettings; UI now edits
strength, and analyseCarveBands is called with carveProfile(strength).

Also closes fallow's complexity, dead-code and duplication findings on this
PR's diff: extracted automationLaneDragMath.ts (pure group/point-move math)
and useAutomationRangeDrag.ts (the marquee-select gesture) out of
useAutomationLaneGestures.ts, pulled a couple of render-loop ternaries and a
resolver into named functions, dropped an export nothing outside its file
used, and shared a step-simplifier between audioCarve's two envelope
builders.

The edge-stretch vs. box-select priority test in TimelineAutomationLane.test
was still pinning the pre-box-select rule (edge wins over a point sitting on
it) that a sibling commit deliberately reversed — a point inside the box is
now selected content, so grabbing it drags the group instead. Updated the
test to the shipped rule instead of the old one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-12 23:30:27 -07:00

363 lines
14 KiB
TypeScript

/**
* Keyboard surface for the active automation selection: Escape clears,
* Delete/Backspace empties the range (anchors pinned, envelope outside
* untouched), Cmd/Ctrl+C copies it, 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 { 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 type { AutomationSelection } from "../player/store/automationSelectionSlice";
import type {
AutomationLaneBinding,
UseAutomationLanesResult,
} from "../player/components/useAutomationLanes";
type PlayerState = ReturnType<typeof usePlayerStore.getState>;
function isTextInput(el: Element | null): boolean {
if (!el) return false;
const tag = el.tagName;
if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
return el instanceof HTMLElement && el.isContentEditable;
}
/**
* 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 empties 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 lane already has no points in it. Split out of
* the keydown handler so each stays under the complexity a single branch of
* keyboard dispatch should carry.
*/
function resolveDeleteWrite(
state: PlayerState,
lanes: UseAutomationLanesResult,
sel: AutomationSelection,
): { onCommit(next: HfAutomation): void; next: HfAutomation } | null {
const ctx = resolveSelectionContext(state, lanes, sel);
if (!ctx || ctx.lane.points.length === 0) return null;
const points = replaceRange({
lane: ctx.lane,
range: ctx.range,
t0: sel.t0,
t1: sel.t1,
inner: [],
});
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, it has no automation lane to fall back to, or the dom-edit layer
* would write the result to a DIFFERENT clip.
*
* That last guard is the one with teeth. `binding.onCommit` persists through
* handleDomAttributeQuietCommit, which targets whatever the dom-edit layer
* currently has selected — not the element `bind()` was handed (see the
* doc-comment on `onSelect` in useAutomationLanes). Selecting a clip in the
* timeline sets `selectedElementId` synchronously but resolves the dom-edit
* selection asynchronously, so clicking clip B and immediately pressing Cmd+V
* would serialize B's automation onto A. Every other lane path is a pointer
* gesture on the lane itself, which cannot run before the selection lands;
* paste is the only one that can, so it refuses rather than write blind.
*/
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;
if (binding.commitTargetKey !== elementKey) 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);
}
/**
* 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();
paste.binding.onCommit(withLane(paste.binding.automation, { target: paste.target, points }));
// Select the pasted span — the only feedback that it landed — and mark it, so
// an immediate second Cmd+V recognises this selection as the paste's own and
// chains right after it instead of overwriting it. Full-height box over the
// pasted span: this path only ever reads t0/t1, so the box's value bounds are
// cosmetic — but the parameter's own range keeps it a sensible box to draw.
const mark = {
elementKey: paste.elementKey,
target: paste.target,
t0: atT,
t1,
v0: paste.range.min,
v1: paste.range.max,
};
state.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, an unresolvable target, or the
* dom-edit target mismatch `resolvePasteTarget` guards, 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 (isTextInput(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();
write.onCommit(write.next);
return true;
}
export function useAutomationSelectionKeyboard({
lanes,
}: {
lanes: UseAutomationLanesResult;
}): void {
useEffect(() => {
const handler = (e: KeyboardEvent): void => {
if (isTextInput(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]);
}