feat(studio): give the clips on a track one automation lane row per property

Several clips can share a track row. The row was named after whichever of
them was selected, carried its clip count as a badge, and listed only that
clip's envelopes — so a lane belonging to one slice read as governing the
whole row, and clicking a sibling silently swapped which envelopes existed.

A lane is a property over time, not a clip's private strip. Clips on one row
now share a lane row when it is the same property of the same effect, keyed
by `laneGroupKey` (the label, which is what identifies a parameter to a
reader — node ids are minted per chain and collide across clips). Each clip
draws its own envelope over its own span, and a clip that does not automate
the property leaves that stretch empty rather than drawing a flat line that
would claim an envelope exists.

Gestures stay per clip: every clip keeps its own binding, its own
useAutomationLaneGestures and its own selection box. A shared row is a shared
lane track, not a shared envelope, so two clips' curves can never drag as one
thing. That is why the slot loops over components rather than over lanes.

Row height and the label column follow the grouped count, and the header
names the track once the row holds several clips. Disclosure had the same
selection-dependence: it was stored against the active clip, so expanding one
slice and clicking another collapsed the row. The caret now opens and closes
every clip on the row together, and any expanded clip holds it open.

The remove button acts only on the clip the header is showing, since that is
the only one a write can reach; a row that clip is absent from offers none.

Effects stay on the CLIP. There is no track entity to own a chain —
data-track-index is parsed in one place, only to choose a row, and both
runtimes build audio per element.

Author: vanceingalls

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

@@ -1,12 +1,11 @@
 import { CaretRight } from "@phosphor-icons/react";
-import type { TimelineElement } from "../store/playerStore";
 import { TRACK_H } from "./timelineLayout";
 import { TrackClipCount } from "./TrackClipCount";
 
 // Layer row (Figma order: disclosure ▸/▾, diamond, name) — the disclosure lives
 // here, not on the clip bar, and re-expands a collapsed layer.
 export function LayerDisclosureRow({
-  keyframeClip,
+  name,
   clipCount,
   isExpanded,
   gutterBackground,
@@ -15,7 +14,10 @@ export function LayerDisclosureRow({
   onToggleClipExpanded,
   children,
 }: {
-  keyframeClip: TimelineElement;
+  /** What this row is called. The active clip's own name when it is alone on the
+   *  track; the track itself once it holds several, since naming a shared row
+   *  after one of its clips reads as if the rows under it were that clip's. */
+  name: string;
   clipCount: number;
   isExpanded: boolean;
   gutterBackground: string;
@@ -31,7 +33,6 @@ export function LayerDisclosureRow({
   /** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */
   children?: React.ReactNode;
 }) {
-  const name = keyframeClip.label ?? keyframeClip.domId ?? keyframeClip.id;
   return (
     <div
       className="absolute left-0 top-0 flex items-center gap-1.5 overflow-hidden px-1.5 text-[11px]"

packages/studio/src/player/components/Timeline.test.ts

@@ -37,6 +37,7 @@ import {
   getTimelineLaneTop,
   createTimelineRowGeometry,
 } from "./timelineLayout";
+import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { formatTime } from "../lib/time";
 import { usePlayerStore } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
@@ -559,6 +560,42 @@ describe("Timeline provider boundary", () => {
     act(() => root.unmount());
   });
 
+  // The caret belongs to the row, not to whichever clip on it is selected: the
+  // automation lanes below it are the track's, shared per property. Toggling one
+  // clip left the row's state depending on the selection, and a collapse that
+  // only dropped the active clip left the row stuck open.
+  it("expands and collapses every clip on a shared track together", () => {
+    const host = createSizedTimelineHost(720);
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
+    });
+    usePlayerStore.setState({
+      duration: 8,
+      timelineReady: true,
+      elements: [
+        { id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
+        { id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
+      ],
+    });
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Timeline)));
+
+    const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
+      ?.parentElement;
+    // A row of several clips is named for the track, so the caret is too.
+    const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" keyframes"]');
+    expect(caret()?.getAttribute("aria-label")).toBe("Expand Track 1 keyframes");
+
+    act(() => caret()?.click());
+    // One shared volume row, and BOTH clips hold it open.
+    expectTrackExpansion(row, ["narration-1", "narration-2"], TRACK_H + AUTOMATION_LANE_H);
+
+    act(() => caret()?.click());
+    expectTrackExpansion(row, [], TRACK_H);
+    act(() => root.unmount());
+  });
+
   it("marks every clip in selectedElementIds as selected", () => {
     const host = createSizedTimelineHost(720);
 

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

@@ -44,6 +44,9 @@ import { simplifyPoints } from "./automationSimplify";
 import { pointInSelection, pointsIn, replaceRange } from "./automationLaneSelection";
 import { getTimelineLaneTop } from "./timelineLayout";
 import { defaultTimelineTheme } from "./timelineTheme";
+import { groupAutomationLanes } from "./automationLaneData";
+import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
 import type { UseAutomationLanesResult } from "./useAutomationLanes";
 
@@ -483,35 +486,42 @@ export function TimelineAutomationLane({
   );
 }
 
-export interface TimelineAutomationLaneSlotProps {
-  element: TimelineElement;
-  isSelected: boolean;
-  lanes: UseAutomationLanesResult;
-  pps: number;
-  /** Keyframe lanes already stacked above, which automation sits under. */
-  laneCount: number;
-  accentColor: string;
-  /** Composition-time playhead; the slot converts it to clip-local. */
-  currentTime: number;
-  /** Composition-time beat grid; the slot converts it to clip-local too. */
-  beatTimes?: readonly number[];
+/** Which shared rows one clip draws into, and with which of its lanes. */
+interface ClipLaneRow {
+  lane: HfAutomationLane;
+  rowIndex: number;
 }
 
 /**
- * Every automated parameter on this clip, one lane per row — the way a DAW
- * stacks them, so two envelopes can be read and edited without swapping a
- * control to see either.
+ * One clip's envelopes, each in the shared row its property owns.
+ *
+ * Its own component because every clip on the row needs its own binding, its own
+ * gestures and its own selection box — a shared row is a shared lane track, not a
+ * shared envelope, and two clips' curves must never drag as one thing. Hooks
+ * cannot run in a loop, so the loop is over components.
  */
-export function TimelineAutomationLaneSlot({
+function ClipAutomationLanes({
   element,
+  rows,
   isSelected,
   lanes,
   pps,
-  laneCount,
+  top,
   accentColor,
   currentTime,
   beatTimes,
-}: TimelineAutomationLaneSlotProps) {
+}: {
+  element: TimelineElement;
+  rows: readonly ClipLaneRow[];
+  isSelected: boolean;
+  lanes: UseAutomationLanesResult;
+  pps: number;
+  /** y of the first automation row on this track. */
+  top: number;
+  accentColor: string;
+  currentTime: number;
+  beatTimes?: readonly number[];
+}) {
   // Beats inside this clip, in the clip's own frame — the lane's times are
   // clip-local, and a beat outside the clip can never be snapped to anyway.
   const snapTimes = useMemo(
@@ -525,19 +535,19 @@ export function TimelineAutomationLaneSlot({
   // Stale-selection guard: the selected lane's target can vanish out from under
   // it (e.g. its effect got deleted from the chain, dropping the lane), leaving
   // a rectangle selecting nothing. Clear it rather than let it point at a
-  // target that no longer draws.
+  // target that no longer draws. Above the empty-rows return, because a clip
+  // that draws nothing is exactly when a selection goes stale.
   useEffect(() => {
     const target = bound.selection?.target;
     if (target !== undefined && !bound.lanes.some((lane) => lane.target === target)) {
       bound.onRangeClear();
     }
   }, [bound]);
-  if (bound.lanes.length === 0) return null;
+  if (rows.length === 0) return null;
   const inClip = currentTime >= element.start && currentTime <= element.start + element.duration;
-  const top = getTimelineLaneTop(laneCount);
   return (
     <>
-      {bound.lanes.map((lane, index) => {
+      {rows.map(({ lane, rowIndex }) => {
         const range = resolveAutomationRange(lane.target, bound.chain ?? undefined);
         // A lane whose target no longer resolves was already dropped upstream;
         // this is belt and braces so a row can never draw on the wrong axis.
@@ -548,7 +558,7 @@ export function TimelineAutomationLaneSlot({
             duration={element.duration}
             widthPx={Math.max(element.duration * pps, 4)}
             leftPx={element.start * pps}
-            topPx={top + index * AUTOMATION_LANE_H}
+            topPx={top + rowIndex * AUTOMATION_LANE_H}
             automation={bound.automation}
             target={lane.target}
             range={range}
@@ -577,3 +587,69 @@ export function TimelineAutomationLaneSlot({
     </>
   );
 }
+
+export interface TimelineAutomationLaneSlotProps {
+  /** Every clip on the track, in row order — not just the selected one. */
+  elements: readonly TimelineElement[];
+  isSelected: (element: TimelineElement) => boolean;
+  lanes: UseAutomationLanesResult;
+  pps: number;
+  /** Keyframe lanes already stacked above, which automation sits under. */
+  laneCount: number;
+  accentColor: string;
+  /** Composition-time playhead; the slot converts it to clip-local. */
+  currentTime: number;
+  /** Composition-time beat grid; the slot converts it to clip-local too. */
+  beatTimes?: readonly number[];
+}
+
+/**
+ * Every automated parameter on this TRACK, one lane per row — the way a DAW
+ * stacks them, so two envelopes can be read and edited without swapping a
+ * control to see either.
+ *
+ * Rows belong to the track, not to a clip: clips sharing a row share a row per
+ * property (see `groupAutomationLanes`), each drawing over its own span, and a
+ * clip that does not automate that property leaves its stretch empty. Binding one
+ * clip at a time is what made the visible envelopes change with the selection.
+ */
+export function TimelineAutomationLaneSlot({
+  elements,
+  isSelected,
+  lanes,
+  pps,
+  laneCount,
+  accentColor,
+  currentTime,
+  beatTimes,
+}: TimelineAutomationLaneSlotProps) {
+  const clips = elements.filter(isAudioTimelineElement);
+  const rowsByClip = new Map<string, ClipLaneRow[]>();
+  groupAutomationLanes(clips).forEach((group, rowIndex) => {
+    for (const entry of group.entries) {
+      const key = getTimelineElementIdentity(entry.element);
+      const rows = rowsByClip.get(key);
+      if (rows) rows.push({ lane: entry.lane, rowIndex });
+      else rowsByClip.set(key, [{ lane: entry.lane, rowIndex }]);
+    }
+  });
+  const top = getTimelineLaneTop(laneCount);
+  return (
+    <>
+      {clips.map((element) => (
+        <ClipAutomationLanes
+          key={getTimelineElementIdentity(element)}
+          element={element}
+          rows={rowsByClip.get(getTimelineElementIdentity(element)) ?? []}
+          isSelected={isSelected(element)}
+          lanes={lanes}
+          pps={pps}
+          top={top}
+          accentColor={accentColor}
+          currentTime={currentTime}
+          beatTimes={beatTimes}
+        />
+      ))}
+    </>
+  );
+}

packages/studio/src/player/components/TimelineAutomationLaneSlot.test.tsx

@@ -3,6 +3,10 @@ import { act } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { createRoot } from "react-dom/client";
 import { TimelineAutomationLaneSlot } from "./TimelineAutomationLane";
+import { AUTOMATION_LANE_H } from "./automationLaneHeight";
+import { PAD_X } from "./automationLaneGeometry";
+import { getTimelineLaneTop } from "./timelineLayout";
+import { elementAutomation, elementAutomationLanes, elementFxChain } from "./automationLaneData";
 import type { AutomationLaneBinding, UseAutomationLanesResult } from "./useAutomationLanes";
 import type { TimelineElement } from "../store/timelineElement";
 
@@ -40,8 +44,8 @@ function mountSlot(binding: Partial<AutomationLaneBinding>) {
   act(() => {
     createRoot(host).render(
       <TimelineAutomationLaneSlot
-        element={element}
-        isSelected={false}
+        elements={[element]}
+        isSelected={() => false}
         lanes={lanes}
         pps={100}
         laneCount={0}
@@ -53,6 +57,106 @@ function mountSlot(binding: Partial<AutomationLaneBinding>) {
   return { onRangeClear };
 }
 
+/** Two narration slices sharing a row, each with its own chain. */
+const chainOf = (nodes: unknown[]) => JSON.stringify({ version: 1, nodes });
+const lanesOf = (...targets: string[]) =>
+  JSON.stringify({
+    version: 1,
+    lanes: targets.map((target) => ({ target, points: [{ t: 0, v: 1 }] })),
+  });
+
+const narration1: TimelineElement = {
+  ...element,
+  id: "narration-1",
+  key: "narration-1",
+  start: 0,
+  duration: 4,
+  fxChain: chainOf([
+    { type: "lowpass", id: "n1", params: { frequency: 8000, q: 0.7, poles: "2" } },
+    { type: "peaking", id: "n2", params: { frequency: 1000, gain: -3, q: 1.4 } },
+  ]),
+  automation: lanesOf("fx.n2.q"),
+};
+const narration2: TimelineElement = {
+  ...element,
+  id: "narration-2",
+  key: "narration-2",
+  start: 4,
+  duration: 4,
+  fxChain: chainOf([{ type: "peaking", id: "n1", params: { frequency: 1000, gain: -6, q: 1.4 } }]),
+  automation: lanesOf("fx.n1.q", "volume"),
+};
+
+/** Reads what a clip really carries, the way the live binding does. */
+const readingBind = (element: TimelineElement, isSelected: boolean): AutomationLaneBinding => ({
+  automation: elementAutomation(element),
+  lanes: elementAutomationLanes(element),
+  chain: elementFxChain(element),
+  onPreview: vi.fn(),
+  onCommit: vi.fn(),
+  onSelect: vi.fn(),
+  readOnly: !isSelected,
+  commitTargetKey: null,
+  selection: null,
+  onRangeSelect: vi.fn(),
+  onRangeClear: vi.fn(),
+});
+
+/** Every drawn envelope as `row @ left`, which is the whole claim under test. */
+function mountRow(elements: readonly TimelineElement[], selectedKey?: string) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => {
+    createRoot(host).render(
+      <TimelineAutomationLaneSlot
+        elements={elements}
+        isSelected={(el) => el.key === selectedKey}
+        lanes={{ bind: readingBind }}
+        pps={100}
+        laneCount={0}
+        accentColor="#0af"
+        currentTime={0}
+      />,
+    );
+  });
+  return [...host.querySelectorAll<HTMLElement>(".hf-automation-lane")]
+    .map((lane) => `${lane.style.top} @ ${lane.querySelector("svg")?.style.left}`)
+    .sort();
+}
+
+const ROW_0 = `${getTimelineLaneTop(0)}px`;
+const ROW_1 = `${getTimelineLaneTop(0) + AUTOMATION_LANE_H}px`;
+
+describe("TimelineAutomationLaneSlot shared rows", () => {
+  it("draws two clips' envelopes for one property in the same row", () => {
+    // One lane track, two envelopes — same row, each over its own span. The
+    // 1 kHz peaking Q is `fx.n2.q` on one clip and `fx.n1.q` on the other.
+    expect(mountRow([narration1, narration2])).toEqual(
+      [
+        `${ROW_0} @ ${0 - PAD_X}px`,
+        `${ROW_0} @ ${400 - PAD_X}px`,
+        `${ROW_1} @ ${400 - PAD_X}px`,
+      ].sort(),
+    );
+  });
+
+  it("leaves a clip's stretch empty in a row it does not automate", () => {
+    // Only narration-2 has a volume envelope, so row 1 carries one curve and
+    // narration-1's half of it stays blank rather than drawing a flat line.
+    expect(mountRow([narration1, narration2]).filter((row) => row.startsWith(ROW_1))).toEqual([
+      `${ROW_1} @ ${400 - PAD_X}px`,
+    ]);
+  });
+
+  it("keeps the same rows whichever clip is selected", () => {
+    // The bug this replaces: the row listed only the selected clip's lanes, so
+    // clicking a sibling swapped which envelopes existed.
+    expect(mountRow([narration1, narration2], "narration-1")).toEqual(
+      mountRow([narration1, narration2], "narration-2"),
+    );
+  });
+});
+
 describe("TimelineAutomationLaneSlot stale-selection guard", () => {
   it("clears the selection when its lane's target no longer exists", () => {
     const { onRangeClear } = mountSlot({