@hyperframes/studio 0.7.106 → 0.7.108

package/src/hooks/useAutomationSelectionKeyboard.ts

@@ -0,0 +1,371 @@
+/**
+ * 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 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 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(next: HfAutomation): void; 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, 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: everything that landed is selected, so
+  // Delete straight after a paste undoes it in one press.
+  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]);
+}

package/src/hooks/useDomEditAttributeCommits.ts

@@ -8,6 +8,7 @@ import {
 import type { PersistDomEditOperations } from "./domEditCommitTypes";
 import { reportDomEditPersistFailure } from "./domEditPersistFailure";
 import { bumpDomEditCommitMapVersion, runDomEditCommit } from "./domEditCommitRunner";
+import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";
 
 // ── Types ──
 
@@ -26,6 +27,26 @@ interface DataAttributeCommitOptions {
   skipRefresh: boolean;
   refreshAfter?: boolean;
   onSettled?: (ok: boolean) => void;
+  /**
+   * Undo grouping for a gesture that spans several commits.
+   *
+   * Without it the key is derived from the prefix, attribute and element, and the
+   * window is history's own 300ms — so a drag's moves and the release that ends it
+   * landed in different entries, and a drag slower than the window split further.
+   * A caller that knows a gesture is in progress passes one key for all of it.
+   */
+  coalesce?: { key: string; ms: number };
+  /**
+   * Apply to the preview and stop there — no file write, no history entry.
+   *
+   * What a gesture wants from every pointermove: the preview document and the
+   * audio graph following the pointer, with the file written once on release.
+   * Persisting each move put a fragment of one drag in the undo stack, and since
+   * those writes race, a follow-up's "before" was often not the previous entry's
+   * "after" — history refuses to coalesce across that gap, so undo took back a
+   * few milliseconds of the gesture and looked like it had done nothing.
+   */
+  previewOnly?: boolean;
 }
 
 function resolveFullAttrName(attr: string, prefixData: boolean | undefined): string {
@@ -108,7 +129,9 @@ export function useDomEditAttributeCommits({
       if (!domEditSelection) return;
       const iframe = previewIframeRef.current;
       const fullAttr = resolveFullAttrName(attr, true);
-      const commitKey = `${options.coalescePrefix}:${attr}:${getDomEditTargetKey(domEditSelection)}`;
+      const commitKey =
+        options.coalesce?.key ??
+        `${options.coalescePrefix}:${attr}:${getDomEditTargetKey(domEditSelection)}`;
       const isLatestCommit = bumpDomEditCommitMapVersion(
         domAttributeCommitVersionRef.current,
         commitKey,
@@ -134,12 +157,15 @@ export function useDomEditAttributeCommits({
           const nextValue = value === null || value === "" ? null : value;
           setOrRemovePreviewAttribute(editedElement, fullAttr, nextValue);
         },
-        persist: () =>
-          persistDomEditOperations(domEditSelection, [op], {
-            label: options.label,
-            coalesceKey: commitKey,
-            skipRefresh: options.skipRefresh,
-          }),
+        persist: options.previewOnly
+          ? async () => {}
+          : () =>
+              persistDomEditOperations(domEditSelection, [op], {
+                label: options.label,
+                coalesceKey: commitKey,
+                ...(options.coalesce ? { coalesceMs: options.coalesce.ms } : {}),
+                skipRefresh: options.skipRefresh,
+              }),
         shouldRevert: () => isLatestCommit(),
         revert: () => {
           if (!editedElement) return;
@@ -147,7 +173,19 @@ export function useDomEditAttributeCommits({
         },
         onError: (error) => reportDomEditPersistFailure(domEditSelection, [op], error, showToast),
         shouldResync: () => isLatestCommit() && !!options.refreshAfter,
-        resync: () => refreshDomEditSelectionFromPreview(domEditSelection),
+        resync: () => {
+          refreshDomEditSelectionFromPreview(domEditSelection);
+          // The player store keeps its own copy of each element's attributes, and
+          // that copy is what the timeline's automation lanes draw from. Nothing
+          // else refreshes it: a commit patches the preview document and the file,
+          // and resyncs the dom-edit SELECTION for the panel. So every writer that
+          // did not also update the store by hand — the FX panel's automate and
+          // un-automate buttons, the keyboard Delete, a paste — changed the file and
+          // the audio while the lane went on drawing what it had, until a reload.
+          // One sink here rather than a sync in each writer, because three of them
+          // shipped without one.
+          syncStoredAutomationFromPreview(previewIframeRef.current?.contentDocument ?? null);
+        },
         onSettled: options.onSettled,
       });
     },
@@ -273,12 +311,41 @@ export function useDomEditAttributeCommits({
   );
 
   const handleDomAttributeLiveCommit = useCallback(
-    async (attr: string, value: string | null, onSettled?: (ok: boolean) => void) => {
+    async (
+      attr: string,
+      value: string | null,
+      onSettled?: (ok: boolean) => void,
+      live?: { coalesce?: { key: string; ms: number }; previewOnly?: boolean },
+    ) => {
       await commitDataAttribute(attr, value, {
         label: `Edit ${attr.replace(/^(data-)?/, "").replace(/-/g, " ")}`,
         coalescePrefix: "attr-live",
         skipRefresh: true,
         onSettled,
+        ...(live?.coalesce ? { coalesce: live.coalesce } : {}),
+        ...(live?.previewOnly ? { previewOnly: true } : {}),
+      });
+    },
+    [commitDataAttribute],
+  );
+
+  /**
+   * Persist without reloading the preview, but re-read the selection afterwards.
+   *
+   * For attributes the runtime applies to the live graph itself — an audio FX
+   * chain, its automation — a reload would only interrupt playback to reach the
+   * state the preview already has. The resync is still needed: without it the
+   * panel keeps reading the selection snapshot it was built with, so a second
+   * edit computes from a pre-edit value and appears to do nothing.
+   */
+  const handleDomAttributeQuietCommit = useCallback(
+    async (attr: string, value: string | null, coalesce?: { key: string; ms: number }) => {
+      await commitDataAttribute(attr, value, {
+        label: `Edit ${attr.replace(/^(data-)?/, "").replace(/-/g, " ")}`,
+        coalescePrefix: "attr-quiet",
+        skipRefresh: true,
+        refreshAfter: true,
+        ...(coalesce ? { coalesce } : {}),
       });
     },
     [commitDataAttribute],
@@ -327,7 +394,19 @@ export function useDomEditAttributeCommits({
         },
         onError: (error) => reportDomEditPersistFailure(domEditSelection, [op], error, showToast),
         shouldResync: () => isLatestCommit(),
-        resync: () => refreshDomEditSelectionFromPreview(domEditSelection),
+        resync: () => {
+          refreshDomEditSelectionFromPreview(domEditSelection);
+          // The player store keeps its own copy of each element's attributes, and
+          // that copy is what the timeline's automation lanes draw from. Nothing
+          // else refreshes it: a commit patches the preview document and the file,
+          // and resyncs the dom-edit SELECTION for the panel. So every writer that
+          // did not also update the store by hand — the FX panel's automate and
+          // un-automate buttons, the keyboard Delete, a paste — changed the file and
+          // the audio while the lane went on drawing what it had, until a reload.
+          // One sink here rather than a sync in each writer, because three of them
+          // shipped without one.
+          syncStoredAutomationFromPreview(previewIframeRef.current?.contentDocument ?? null);
+        },
       });
     },
     [
@@ -343,6 +422,7 @@ export function useDomEditAttributeCommits({
   return {
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
+    handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
   };