fix(studio): align audio rows, automation lanes and headers (#3451)

* fix(core): harden audio FX and group identity

* fix(core): address audio group review feedback

* fix(core): align preview transport with grouped audio

* test(core): pin audio group gain ceiling

* fix(core): preserve solo bridge through stack

* fix(engine): harden grouped audio rendering

* docs(engine): explain grouped mix fallback invariant

* test(engine): allow grouped mixes to finish on Windows

* feat(lint): validate audio group membership and timing

* test(lint): pin audio group membership guards

* fix(studio): unify audio IDs and group state

* fix(studio): make audio-group edits transactional

* fix(studio): keep preview state synchronized

* fix(studio): align audio rows, automation lanes and headers

* fix(studio): stabilize timeline audio derivations

* refactor(studio): simplify group metadata memoization

* style(studio): keep timeline layout within size gate

* fix(studio): keep timeline preset apply off auditions

Author: vanceingalls

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

@@ -91,7 +91,11 @@ export function TimelineFxPopover({
   onOpenRack,
 }: TimelineFxPopoverProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
-  const { audition, clearAudition } = useFxAudition(chain, onChainPreview, onAuditionTransport);
+  const { audition, clearAudition, storedChain } = useFxAudition(
+    chain,
+    onChainPreview,
+    onAuditionTransport,
+  );
 
   // Outside click dismisses like any other popover; the button itself is
   // excluded by pointerdown timing (the button's own click hasn't happened yet).
@@ -104,7 +108,7 @@ export function TimelineFxPopover({
   }, [onClose]);
 
   const applyPreset = (id: string) => {
-    const next = applyPresetToChain(chain, id, trackKind);
+    const next = applyPresetToChain(storedChain(), id, trackKind);
     if (!next) return;
     clearAudition();
     onChainChange(next);

packages/studio/src/components/editor/useAuditionTransport.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { auditionStart } from "./useAuditionTransport";
+
+const SPANS = [
+  { start: 2, duration: 7 },
+  { start: 18, duration: 7 },
+];
+
+describe("auditionStart", () => {
+  // Nothing to aim at — a caller with no spans keeps the old behaviour: play
+  // from wherever the author left the playhead.
+  it("stays put when there are no spans", () => {
+    expect(auditionStart(undefined, 0)).toBeNull();
+    expect(auditionStart([], 0)).toBeNull();
+  });
+
+  // Already inside the clip: moving the playhead here would be the UI taking a
+  // decision it was not asked for, and it would cost the author their place for
+  // no gain.
+  it("stays put when the playhead is already inside a span", () => {
+    expect(auditionStart(SPANS, 2)).toBeNull();
+    expect(auditionStart(SPANS, 8.9)).toBeNull();
+  });
+
+  // The bug this exists for: hovering a preset at 0:00 on a group whose members
+  // start at 0:02 played silence under the effect.
+  it("jumps to the next span when the playhead is before or between them", () => {
+    expect(auditionStart(SPANS, 0)).toBe(2);
+    expect(auditionStart(SPANS, 9)).toBe(18);
+  });
+
+  // Past everything, wrap to the first rather than play out the tail in silence.
+  it("wraps to the first span when the playhead is past them all", () => {
+    expect(auditionStart(SPANS, 40)).toBe(2);
+  });
+});

packages/studio/src/components/editor/useAuditionTransport.ts

@@ -0,0 +1,78 @@
+/**
+ * Start playback for an audition, and put the playhead back on the way out.
+ *
+ * An audition writes the hovered 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 affordance only worked mid-playback. Extracted from
+ * `useFxLevelling`, where the property panel's rack owned it privately, because
+ * the timeline's FX popover must render the preset shelf "exactly as FxSection
+ * renders it — same props" (runbook C1 §2) and was passing no transport at all.
+ */
+
+import { useRef } from "react";
+// The store's own module, not the `player` barrel: the barrel pulls the whole
+// timeline in, and the timeline's FX button imports this hook — a cycle.
+import { usePlayerStore } from "../../player/store/playerStore";
+
+/** A clip the audition is meant to be heard through. */
+export interface AuditionSpan {
+  start: number;
+  duration: number;
+}
+
+/**
+ * Where to start playing so the audition is actually audible, or null to stay.
+ *
+ * Playing "from the playhead" only works when the thing being auditioned is
+ * sounding there. A group whose members start at 0:02, hovered with the
+ * playhead at 0:00, plays the rest of the mix unchanged — the transport runs,
+ * the chain is in the graph, and the author hears nothing of the preset. So:
+ * inside a span, stay; otherwise jump to the next one, wrapping to the first
+ * when the playhead is past them all.
+ *
+ * Shared rather than the popover's own, which is where it went wrong the first
+ * time: the property panel's rack has the identical hole, and giving the two
+ * surfaces different audition behaviour is exactly what runbook C1 §2 forbids
+ * when it says the shelf renders "exactly as FxSection renders it".
+ */
+export function auditionStart(
+  spans: readonly AuditionSpan[] | undefined,
+  at: number,
+): number | null {
+  if (!spans || spans.length === 0) return null;
+  if (spans.some((span) => at >= span.start && at < span.start + span.duration)) return null;
+  const starts = spans.map((span) => span.start).sort((a, b) => a - b);
+  return starts.find((start) => start > at) ?? starts[0] ?? null;
+}
+
+export function useAuditionTransport(): (on: boolean, spans?: readonly AuditionSpan[]) => void {
+  /**
+   * 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);
+
+  /**
+   * 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 UI taking a decision that was not offered to it.
+   */
+  return (on: boolean, spans?: readonly AuditionSpan[]): void => {
+    const store = usePlayerStore.getState();
+    if (on) {
+      if (store.isPlaying || auditionReturn.current !== null) return;
+      // Recorded BEFORE the seek, so leaving returns the author to where they
+      // actually were rather than to the clip this jumped to.
+      auditionReturn.current = store.currentTime;
+      const from = auditionStart(spans, store.currentTime);
+      if (from !== null) store.requestSeek(from);
+      store.requestPlayback(true);
+      return;
+    }
+    const returnTo = auditionReturn.current;
+    if (returnTo === null) return;
+    auditionReturn.current = null;
+    store.requestPlayback(false, returnTo);
+  };
+}

packages/studio/src/components/editor/useFxAudition.ts

@@ -52,6 +52,17 @@ export function useFxAudition(
     [chain, onChainPreview, onAuditionTransport],
   );
 
+  /**
+   * The chain as the DOCUMENT has it, ignoring whatever is being auditioned.
+   *
+   * An audition writes through the preview channel, and the `chain` prop is
+   * read back from that same live attribute — so mid-hover it is the hovered
+   * preset, not the stored chain. Applying on top of it stacked the auditioned
+   * preset into the saved chain: hover a reverb, click a different preset, and
+   * both were persisted, which is heard as the effect running twice.
+   */
+  const storedChain = useCallback(() => auditionBase.current ?? chain, [chain]);
+
   /**
    * Drop whatever is being auditioned WITHOUT reverting the preview, for a
    * caller that is about to mutate the real chain anyway — reverting first
@@ -91,5 +102,5 @@ export function useFxAudition(
     [],
   );
 
-  return { audition, clearAudition };
+  return { audition, clearAudition, storedChain };
 }

packages/studio/src/player/components/AutomationSelectionMenu.tsx

@@ -41,6 +41,10 @@ export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
   return createPortal(
     <div
       ref={menuRef}
+      // z-[200] for the same reason the timeline's FX popover uses it: this is
+      // portaled to `document.body`, but the ruler's sticky header sits at z-70
+      // in the SAME root stacking context, so a z-50 menu opened near the top of
+      // the timeline is painted through by the ruler and the playhead.
       className="hf-automation-menu fixed z-[200] min-w-[140px] rounded border border-panel-border-input bg-panel-bg-2 py-1 shadow-lg"
       style={{ left: adjustedX, top: adjustedY }}
     >

packages/studio/src/player/components/LayerDisclosureRow.tsx

@@ -1,11 +1,56 @@
 import { TRACK_H } from "./timelineLayout";
 import { TrackClipCount } from "./TrackClipCount";
 
-// Layer row (Figma order: disclosure ∿, diamond, name) — the disclosure lives
+// Layer row (diamond, name, then the ∿ disclosure on the right edge) — the
+// disclosure lives
 // here, not on the clip bar, and re-expands a collapsed layer. `∿` (not a
 // caret) because a group's own row keeps the caret for its structural
 // disclosure (member rows) — this button only ever means "show this row's
 // lanes", so it needs its own distinct glyph.
+/**
+ * The `∿` that shows or hides a row's lanes.
+ *
+ * Shared, because two layouts need the identical control: the keyframe layer
+ * row below, and the plain track header — an audio track with automation keeps
+ * its own look (music glyph, indent) and gains this, rather than being
+ * re-rendered as a keyframe layer to get at the button.
+ */
+export function LaneToggleButton({
+  name,
+  isExpanded,
+  lanesId,
+  onToggle,
+}: {
+  name: string;
+  isExpanded: boolean;
+  lanesId: string;
+  onToggle: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      // ponytail: No focus id here; keyboard routing belongs to the enclosing logical row.
+      tabIndex={-1}
+      aria-expanded={isExpanded}
+      aria-controls={lanesId}
+      aria-label={`${isExpanded ? "Hide" : "Show"} ${name} lanes`}
+      title={`${isExpanded ? "Hide" : "Show"} lanes`}
+      // h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The glyph stays 11px;
+      // only the hit box grows.
+      className={`ml-auto flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+        isExpanded ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        onToggle();
+      }}
+    >
+      <span aria-hidden="true">∿</span>
+    </button>
+  );
+}
+
 export function LayerDisclosureRow({
   name,
   clipCount,
@@ -45,37 +90,26 @@ export function LayerDisclosureRow({
         background: gutterBackground,
       }}
     >
-      <button
-        type="button"
-        // ponytail: No focus id here; keyboard routing belongs to the enclosing logical row.
-        tabIndex={-1}
-        aria-expanded={isExpanded}
-        aria-controls={lanesId}
-        aria-label={`${isExpanded ? "Hide" : "Show"} ${name} lanes`}
-        title={`${isExpanded ? "Hide" : "Show"} lanes`}
-        // h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The glyph stays 11px;
-        // only the hit box grows.
-        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
-          isExpanded ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
-        }`}
-        onPointerDown={(event) => event.stopPropagation()}
-        onClick={(event) => {
-          event.stopPropagation();
-          onToggleClipExpanded();
-        }}
-      >
-        <span aria-hidden="true">∿</span>
-      </button>
       {/* Decorative: the disclosure button above already names the row's keyframe
           state, and aria-label on a plain span is not exposed reliably anyway. */}
       <span aria-hidden="true" className="shrink-0 text-[13px] leading-none text-white/40">
         ◇
       </span>
-      <span className="min-w-0 flex-1 truncate font-medium" title={name}>
-        {name}
-      </span>
+      {/* Wraps rather than truncating: a truncated name needs a hover to be
+          read, which a scanned column cannot rely on. */}
+      <span className="min-w-0 flex-1 break-words font-medium leading-tight">{name}</span>
       <TrackClipCount clipCount={clipCount} />
       {children}
+      {/* Anchored right, on every header that has one: the lane toggle is the
+          row's last word about itself, and a left-hand ∿ put it where the eye
+          looks for identity instead. `ml-auto` rather than a spacer so it holds
+          the edge whatever else the row grows. */}
+      <LaneToggleButton
+        name={name}
+        isExpanded={isExpanded}
+        lanesId={lanesId}
+        onToggle={onToggleClipExpanded}
+      />
     </div>
   );
 }

packages/studio/src/player/components/PlayerControls.tsx

@@ -6,7 +6,6 @@ import { liveTime, usePlayerStore } from "../store/playerStore";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { useSoloBannerText } from "../../hooks/useAudioSoloBridge";
 import { ShortcutsPanel } from "./ShortcutsPanel";
 import { SpeedMenu } from "./SpeedMenu";
 import { VolumeControl } from "./VolumeControl";
@@ -156,47 +155,12 @@ const FullscreenButton = memo(function FullscreenButton({
 
 /* ── Main component ──────────────────────────────────────────────── */
 
-/**
- * "Hearing only this" notice. Solo is a PREVIEW-only gate — it never touches an
- * attribute and never reaches the export — so the state has to say so out loud,
- * or a soloed session reads as a broken mix.
- */
-const SoloBanner = memo(function SoloBanner({
-  previewIframeRef,
-}: {
-  previewIframeRef: { current: HTMLIFrameElement | null };
-}) {
-  const bannerText = useSoloBannerText(previewIframeRef);
-  const clearSolo = usePlayerStore.getState().clearSolo;
-  if (bannerText === null) return null;
-  return (
-    <div
-      role="status"
-      className="flex h-7 items-center justify-center gap-2 border-b border-neutral-800 bg-neutral-900/90 px-3 text-[11px] text-neutral-300"
-    >
-      <span>
-        Hearing only <span className="font-medium text-neutral-100">{bannerText}</span> — your
-        export is not affected
-      </span>
-      <button
-        type="button"
-        onClick={() => clearSolo()}
-        className="rounded px-1.5 py-0.5 font-medium text-studio-accent transition-colors hover:text-white"
-      >
-        Clear
-      </button>
-    </div>
-  );
-});
-
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
   disabled?: boolean;
   isFullscreen?: boolean;
   onToggleFullscreen?: () => void;
-  /** Needed to read the soloed clips' labels out of the preview document. */
-  previewIframeRef?: { current: HTMLIFrameElement | null };
 }
 
 export const PlayerControls = memo(function PlayerControls({
@@ -205,7 +169,6 @@ export const PlayerControls = memo(function PlayerControls({
   disabled = false,
   isFullscreen = false,
   onToggleFullscreen,
-  previewIframeRef,
 }: PlayerControlsProps) {
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const duration = usePlayerStore((s) => s.duration);
@@ -258,7 +221,6 @@ export const PlayerControls = memo(function PlayerControls({
 
   return (
     <div>
-      {previewIframeRef && <SoloBanner previewIframeRef={previewIframeRef} />}
       <div
         className="grid h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-3"
         aria-disabled={disabled || undefined}