feat(studio): audition a preset from the playhead while paused

Hovering a preset writes it to the running graph — which is silent while
the transport is paused. So the whole affordance only worked mid-playback:
a paused author hovering the shelf heard nothing at all and had no way to
know the feature existed.

Hovering now starts playback from wherever the playhead sits, and leaving
stops it and returns the playhead to exactly where it was found. Browsing
the shelf is not an edit and must not cost the author their place.

Two guards, each with a test:

- **A transport the author started is left alone**, in both directions.
  Stopping their playback because they passed over a preset would be the
  panel taking a decision nobody offered it.
- **Every path that ends an audition stops the transport** — leaving,
  applying, and the panel unmounting. A click means "keep this", not "and
  carry on playing from wherever the audition reached".

Order matters at both ends: the chain goes into the graph before playback
starts, or the first moment heard is the un-auditioned mix; and playback
stops before the chain reverts, so the last thing heard is the preset
rather than a frame of the old chain coming back.

`playbackRequest` on the player store follows `requestedSeekTime`: the
panel cannot reach `useTimelinePlayer`, which is a single instance owned
by the shell. It carries a nonce because two hovers in a row both want
play, and without one the second is indistinguishable from the first
already having been served.

Falsified: not returning the playhead, and hijacking a transport the
author started, each fail a test.

studio 3716 passing, 18 todo.

Author: vanceingalls

packages/studio/src/components/editor/propertyPanelAudioFxGroup.test.tsx

@@ -435,6 +435,45 @@ describe("AudioFxGroup dynamic carve", () => {
    * nobody asked to level, through a channel that does not persist: audible,
    * absent from the document, and gone on the next reload.
    */
+  describe("auditioning starts the transport when it has to", () => {
+    const store = () => usePlayerStore.getState();
+
+    const hoverPreset = (host: HTMLElement) => {
+      act(() => byTextButton(host, "Presets")?.click());
+      act(() => host.querySelector<HTMLElement>(".hf-fx-preset-item")?.focus());
+    };
+    const leaveShelf = (host: HTMLElement) =>
+      act(() => {
+        host
+          .querySelector(".hf-fx-preset-menu")
+          ?.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+      });
+
+    it("plays from the playhead, then puts it back exactly where it was", () => {
+      // Browsing the shelf must not cost the author their place: hovering is not
+      // an edit, so the playhead it borrows has to be returned.
+      act(() => usePlayerStore.setState({ isPlaying: false, currentTime: 42 }));
+      const { host } = mount({ "fx-chain": CHAIN });
+      hoverPreset(host);
+      expect(store().playbackRequest?.playing).toBe(true);
+
+      leaveShelf(host);
+      expect(store().playbackRequest?.playing).toBe(false);
+      expect(store().playbackRequest?.returnTo).toBe(42);
+    });
+
+    it("leaves a transport the author started alone", () => {
+      // Stopping their playback because they passed over a preset would be the
+      // panel taking a decision nobody offered it.
+      act(() => usePlayerStore.setState({ isPlaying: true, currentTime: 12 }));
+      const { host } = mount({ "fx-chain": CHAIN });
+      const before = store().playbackRequest?.nonce ?? 0;
+      hoverPreset(host);
+      leaveShelf(host);
+      expect(store().playbackRequest?.nonce ?? 0).toBe(before);
+    });
+  });
+
   it("drops a levelling measurement that lands after the pointer has gone", async () => {
     const { release, decoded } = stubGatedDecode();
     const { host, onSetAttributeLive } = mount({ "fx-chain": CHAIN });

packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx

@@ -574,6 +574,40 @@ export function AudioFxGroup({
     }
   };
 
+  /**
+   * Where the playhead was when an audition started the transport, so leaving
+   * can put it back. Null means this audition did not start playback — the
+   * transport was already running and must be left alone.
+   */
+  const auditionReturn = useRef<number | null>(null);
+
+  /**
+   * Start playback for an audition, and stop it again on the way out.
+   *
+   * An audition writes the preset to the running graph, which is silent while
+   * the transport is paused — so a paused author hovering a preset heard
+   * nothing at all, and the whole affordance only worked mid-playback. Hovering
+   * now plays from the playhead, and leaving stops and rewinds to exactly where
+   * it started: browsing the shelf must not cost the author their place.
+   *
+   * Already playing, this does nothing in either direction. The author started
+   * that, and stopping their transport because they passed over a preset would
+   * be the panel taking a decision that was not offered to it.
+   */
+  const auditionTransport = (on: boolean): void => {
+    const store = usePlayerStore.getState();
+    if (on) {
+      if (store.isPlaying || auditionReturn.current !== null) return;
+      auditionReturn.current = store.currentTime;
+      store.requestPlayback(true);
+      return;
+    }
+    const returnTo = auditionReturn.current;
+    if (returnTo === null) return;
+    auditionReturn.current = null;
+    store.requestPlayback(false, returnTo);
+  };
+
   const [auditioningLevel, setAuditioningLevel] = useState(false);
   /**
    * Bumped on every enter and leave, so a measurement can tell whether the
@@ -808,6 +842,7 @@ export function AudioFxGroup({
           next.nodes.length ? serializeAudioFxChain(next) : null,
         )
       }
+      onAuditionTransport={auditionTransport}
       onChainPreview={(next) =>
         // Live writes skip the preview refresh entirely, so dragging a knob no
         // longer reloads the composition and restarts playback on every pixel.

packages/studio/src/components/editor/propertyPanelFxSection.test.tsx

@@ -90,6 +90,7 @@ function mount(overrides: Partial<Parameters<typeof FxSection>[0]> = {}) {
       onRemoveNodeAutomation={overrides.onRemoveNodeAutomation}
       onAutomatePreset={overrides.onAutomatePreset}
       onRemovePresetAutomation={overrides.onRemovePresetAutomation}
+      onAuditionTransport={overrides.onAuditionTransport}
       automatedPresets={overrides.automatedPresets}
       onLevel={overrides.onLevel}
       onRemoveLevel={overrides.onRemoveLevel}
@@ -695,6 +696,52 @@ describe("FxSection chain", () => {
     expect(item?.querySelector(".hf-fx-preset-name")?.textContent).toBe("Telephone");
   });
 
+  describe("auditioning while the transport is paused", () => {
+    it("starts playback so a paused author can hear the preset at all", () => {
+      // The audition is written to the running graph, which is silent while the
+      // transport is paused — so without this, hovering a preset did nothing
+      // whatsoever unless the author happened to be mid-playback.
+      const onAuditionTransport = vi.fn();
+      const { host } = mount({ chain: chainOf("peaking"), onAuditionTransport });
+      click(byText(host, "button", "Presets"));
+      act(() => (presetButton(host, "telephone") as HTMLElement | null)?.focus());
+      expect(onAuditionTransport).toHaveBeenLastCalledWith(true);
+    });
+
+    it("stops it again on the way out", () => {
+      const onAuditionTransport = vi.fn();
+      const { host } = mount({ chain: chainOf("peaking"), onAuditionTransport });
+      click(byText(host, "button", "Presets"));
+      act(() => (presetButton(host, "telephone") as HTMLElement | null)?.focus());
+      act(() => {
+        host
+          .querySelector(".hf-fx-preset-menu")
+          ?.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+      });
+      expect(onAuditionTransport).toHaveBeenLastCalledWith(false);
+    });
+
+    it("stops it when the preset is applied, rather than playing on", () => {
+      // The click means "keep this", not "and carry on playing from wherever
+      // the audition reached".
+      const onAuditionTransport = vi.fn();
+      const { host } = mount({ chain: { version: 1, nodes: [] }, onAuditionTransport });
+      click(byText(host, "button", "Presets"));
+      act(() => (presetButton(host, "telephone") as HTMLElement | null)?.focus());
+      click(presetButton(host, "telephone"));
+      expect(onAuditionTransport).toHaveBeenLastCalledWith(false);
+    });
+
+    it("stops it if the panel goes away mid-audition", () => {
+      const onAuditionTransport = vi.fn();
+      const { host, root } = mount({ chain: chainOf("peaking"), onAuditionTransport });
+      click(byText(host, "button", "Presets"));
+      act(() => (presetButton(host, "telephone") as HTMLElement | null)?.focus());
+      act(() => root.unmount());
+      expect(onAuditionTransport).toHaveBeenLastCalledWith(false);
+    });
+  });
+
   describe("getting back out of a menu", () => {
     /** Escape, from inside the section, the way a keystroke really arrives. */
     const escape = (host: HTMLElement) =>

packages/studio/src/components/editor/propertyPanelFxSection.tsx

@@ -111,6 +111,14 @@ export interface FxSectionProps {
   onAuditionLevel?(on: boolean): void;
   /** Whether that measurement is running, so the button can say so. */
   auditioningLevel?: boolean;
+  /**
+   * Start the transport for an audition, and stop it on the way out.
+   *
+   * An audition is written to the running graph, which is silent while the
+   * transport is paused — so without this, hovering a preset does nothing at all
+   * for a paused author.
+   */
+  onAuditionTransport?(on: boolean): void;
   /** Structural edits and gesture-end writes; this is the one that persists. */
   onChainChange(chain: HfAudioFxChain): void;
   /** Continuous updates while a control is being dragged. */
@@ -156,6 +164,7 @@ export function FxSection({
   onAutomatePreset,
   onRemovePresetAutomation,
   automatedPresets,
+  onAuditionTransport,
 }: FxSectionProps) {
   const presetAutomated = automatedPresets ?? new Set<string>();
   // Falls back to the persisting write when no preview handler is supplied, which
@@ -228,12 +237,18 @@ export function FxSection({
       if (make) {
         auditionBase.current ??= chain;
         onChainPreview(make(auditionBase.current));
+        // After the chain is in the graph, not before: starting the transport
+        // first plays a moment of the un-auditioned mix.
+        onAuditionTransport?.(true);
       } else if (auditionBase.current) {
+        // Stop before reverting, for the mirror of that reason — the last thing
+        // heard should be the preset, not a frame of the chain coming back.
+        onAuditionTransport?.(false);
         onChainPreview(auditionBase.current);
         auditionBase.current = null;
       }
     },
-    [chain, onChainPreview],
+    [chain, onChainPreview, onAuditionTransport],
   );
 
   /**
@@ -253,9 +268,14 @@ export function FxSection({
   // Leaving by any route other than the pointer — the element deselected, the
   // panel closed — would otherwise leave the audition playing over a chain the
   // document does not have.
+  const transportRef = useRef(onAuditionTransport);
+  transportRef.current = onAuditionTransport;
   useEffect(
     () => () => {
-      if (auditionBase.current) previewRef.current?.(auditionBase.current);
+      if (auditionBase.current) {
+        transportRef.current?.(false);
+        previewRef.current?.(auditionBase.current);
+      }
     },
     [],
   );
@@ -272,13 +292,14 @@ export function FxSection({
       // old chain back over the write that just landed is a race the author
       // hears as the preset arriving and then leaving again.
       auditionBase.current = null;
+      onAuditionTransport?.(false);
       mutate(next.nodes);
       // Land on the first node the preset wrote, so the author can hear what
       // arrived and immediately see what it is made of.
       setOpenNode(next.nodes.findIndex((n) => n.fromPreset === preset.id));
       setPicking(false);
     },
-    [chain, mutate],
+    [chain, mutate, onAuditionTransport],
   );
 
   /**
@@ -322,21 +343,23 @@ export function FxSection({
   const addJob = useCallback(
     (job: HfAudioFxJob) => {
       auditionBase.current = null;
+      onAuditionTransport?.(false);
       mutate(withJob(chain, job).nodes);
       setOpenNode(chain.nodes.length);
       setAdding(false);
     },
-    [chain, mutate, withJob],
+    [chain, mutate, withJob, onAuditionTransport],
   );
 
   const addEffect = useCallback(
     (type: string) => {
       auditionBase.current = null;
+      onAuditionTransport?.(false);
       mutate(withEffect(chain, type).nodes);
       setOpenNode(chain.nodes.length);
       setAdding(false);
     },
-    [chain, mutate, withEffect],
+    [chain, mutate, withEffect, onAuditionTransport],
   );
 
   const updateNode = useCallback(
@@ -458,11 +481,12 @@ export function FxSection({
 
   const addEq = useCallback(() => {
     auditionBase.current = null;
+    onAuditionTransport?.(false);
     const { chain: next, eqId } = addAudioEq(chain);
     mutate(next.nodes);
     setOpenEq(eqId);
     setAdding(false);
-  }, [chain, mutate]);
+  }, [chain, mutate, onAuditionTransport]);
 
   // Dragging a fader is heard immediately and written once on release, the same
   // split every other control in the rack uses.

packages/studio/src/player/hooks/useTimelinePlayer.ts

@@ -383,8 +383,20 @@ export function useTimelinePlayer() {
         seek(state.requestedSeekTime);
         usePlayerStore.getState().clearSeekRequest();
       }
+      // Play or stop from outside the loop — the FX rack auditioning a preset
+      // while paused, which is silent otherwise. `returnTo` puts the playhead
+      // back where the request found it: hovering is not an edit.
+      const request = state.playbackRequest;
+      if (request && request.nonce !== prev.playbackRequest?.nonce) {
+        if (request.playing) play();
+        else {
+          pause();
+          if (request.returnTo !== null) seek(request.returnTo);
+        }
+        usePlayerStore.getState().clearPlaybackRequest();
+      }
     });
-  }, [seek]);
+  }, [seek, play, pause]);
   const { playbackKeyDownRef, playbackKeyUpRef, attachIframeShortcutListeners, togglePlay } =
     usePlaybackKeyboard({
       iframeRef,

packages/studio/src/player/store/playerStore.ts

@@ -163,6 +163,22 @@ interface PlayerState extends KeyframeSlice, AutomationSelectionSlice {
   requestSeek: (time: number) => void;
   clearSeekRequest: () => void;
 
+  /**
+   * Request the transport start or stop from outside the player loop.
+   *
+   * The FX rack auditions a preset by writing it to the running graph, which is
+   * silent while the transport is paused — so hovering one has to start
+   * playback, and leaving has to put the playhead back where it was. Hovering is
+   * not an edit and must not cost the author their place.
+   *
+   * A nonce rather than a bare boolean: two hovers in a row both want play, and
+   * without it the second request is indistinguishable from the first having
+   * already been served.
+   */
+  playbackRequest: { playing: boolean; returnTo: number | null; nonce: number } | null;
+  requestPlayback: (playing: boolean, returnTo?: number | null) => void;
+  clearPlaybackRequest: () => void;
+
   /**
    * Request the timeline to scroll a clip into view (e.g. clicking an
    * already-added asset card in the sidebar). Consumed and cleared by
@@ -336,6 +352,13 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   requestSeek: (time) => set({ requestedSeekTime: time }),
   clearSeekRequest: () => set({ requestedSeekTime: null }),
 
+  playbackRequest: null,
+  requestPlayback: (playing, returnTo = null) =>
+    set((s) => ({
+      playbackRequest: { playing, returnTo, nonce: (s.playbackRequest?.nonce ?? 0) + 1 },
+    })),
+  clearPlaybackRequest: () => set({ playbackRequest: null }),
+
   clipRevealRequest: null,
   requestClipReveal: (elementId) =>
     set((s) => ({