@hyperframes/studio 0.8.11 → 0.8.13

package/src/player/components/useAutomationLaneGestures.ts

@@ -25,6 +25,7 @@ import {
   type GroupDragSnapshot,
   type ShiftAxis,
 } from "./automationLaneDragMath";
+import { useAutomationSegmentDrag } from "./useAutomationSegmentDrag";
 
 /** How far a press may travel and still count as a click rather than a drag. */
 const CLICK_SLOP_PX = 3;
@@ -63,10 +64,16 @@ export interface UseAutomationLaneGesturesResult {
   dragIndex: number | null;
   /** Segment being bent, identified by the point that owns its curve. */
   curveIndex: number | null;
+  /** Segment whose two endpoints are being translated together. */
+  segmentDragIndex: number | null;
+  /** Segment close enough to the pointer to offer that translation. */
+  segmentHoverIndex: number | null;
   /** Value readout to show while a gesture is live. */
   hint: string | null;
   hitIndex(clientX: number, clientY: number): number | null;
   segmentIndex(clientX: number, clientY: number): number | null;
+  /** Clear hover feedback when the pointer leaves the lane. */
+  onPointerLeave(): void;
   onPointerDown(e: ReactPointerEvent<SVGSVGElement>): void;
   onPointerMove(e: ReactPointerEvent<SVGSVGElement>): void;
   /** Edge being stretched, for the cursor. Null when no stretch is live. */
@@ -227,16 +234,37 @@ export function useAutomationLaneGestures({
     [lane, pointAt],
   );
 
-  /** What a press starts: moving a point, or — with Alt on the line — bending it. */
+  const segmentDrag = useAutomationSegmentDrag({
+    getBox,
+    lane,
+    range,
+    pointAt,
+    xOf,
+    yOf,
+    segmentIndex,
+    commitPoints,
+    duration,
+    snapTimes,
+    readOnly,
+    onHint: setHint,
+  });
+
+  /** What a press starts: point move, segment move, or Alt segment bend. */
   const gestureAt = useCallback(
-    (e: ReactPointerEvent<SVGSVGElement>): { curve: boolean; index: number } | null => {
+    (
+      e: ReactPointerEvent<SVGSVGElement>,
+    ): { kind: "point" | "segment" | "curve"; index: number } | null => {
       const index = hitIndex(e.clientX, e.clientY);
-      if (index !== null) return { curve: false, index };
-      if (!e.altKey) return null;
-      const segment = segmentIndex(e.clientX, e.clientY);
-      return segment === null ? null : { curve: true, index: segment };
+      if (index !== null) return { kind: "point", index };
+      // Alt is an explicit bend gesture and retains its span-wide hit target.
+      // The unmodified translation is offered only close to the drawn line.
+      const segment = e.altKey
+        ? segmentIndex(e.clientX, e.clientY)
+        : segmentDrag.hitIndex(e.clientX, e.clientY);
+      if (segment === null) return null;
+      return { kind: e.altKey ? "curve" : "segment", index: segment };
     },
-    [hitIndex, segmentIndex],
+    [hitIndex, segmentDrag, segmentIndex],
   );
 
   const onPointerDown = useCallback(
@@ -274,10 +302,15 @@ export function useAutomationLaneGestures({
       }
       e.preventDefault();
       capturePointer(e);
-      if (gesture.curve) {
+      segmentDrag.clearHover();
+      if (gesture.kind === "curve") {
         setCurveIndex(gesture.index);
         return;
       }
+      if (gesture.kind === "segment") {
+        segmentDrag.arm(gesture.index, e.clientX, e.clientY);
+        return;
+      }
       dragOrigin.current = originOf(lane.points[gesture.index]);
       // Pressing one of a selected set drags the whole set. Pressing a point
       // outside the selection is an ordinary single-point drag, selection or no.
@@ -299,6 +332,7 @@ export function useAutomationLaneGestures({
       // selecting a range read the previous selection, or none.
       rangeSelection,
       stretch,
+      segmentDrag,
     ],
   );
 
@@ -394,6 +428,20 @@ export function useAutomationLaneGestures({
     [dragIndex, duration, lane, pointAt, range, commitPoints, snapTimes, xOf, yOf, moveGroup],
   );
 
+  /** Route a live point, bend, or segment gesture after global gestures stand down. */
+  const moveLiveGesture = useCallback(
+    (e: ReactPointerEvent<SVGSVGElement>): void => {
+      const from = pressAt.current;
+      if (from && Math.hypot(e.clientX - from.x, e.clientY - from.y) > CLICK_SLOP_PX) {
+        pressTravelled.current = true;
+      }
+      if (curveIndex !== null) bendSegment(e.clientX, e.clientY);
+      else if (segmentDrag.dragIndex !== null) segmentDrag.move(e);
+      else movePoint(e);
+    },
+    [bendSegment, curveIndex, movePoint, segmentDrag],
+  );
+
   const onPointerMove = useCallback(
     (e: ReactPointerEvent<SVGSVGElement>): void => {
       if (stretch.edge !== null) {
@@ -409,19 +457,15 @@ export function useAutomationLaneGestures({
         rangeDrag.move(e);
         return;
       }
-      if (curveIndex === null && dragIndex === null) {
+      if (curveIndex === null && dragIndex === null && segmentDrag.dragIndex === null) {
         stretch.updateHover(e);
+        segmentDrag.updateHover(e.clientX, e.clientY);
         return;
       }
       e.stopPropagation();
-      const from = pressAt.current;
-      if (from && Math.hypot(e.clientX - from.x, e.clientY - from.y) > CLICK_SLOP_PX) {
-        pressTravelled.current = true;
-      }
-      if (curveIndex !== null) bendSegment(e.clientX, e.clientY);
-      else movePoint(e);
+      moveLiveGesture(e);
     },
-    [rangeDrag, curveIndex, dragIndex, bendSegment, movePoint, stretch],
+    [rangeDrag, curveIndex, dragIndex, segmentDrag, moveLiveGesture, stretch],
   );
 
   const endDrag = useCallback(
@@ -436,12 +480,13 @@ export function useAutomationLaneGestures({
         rangeDrag.finish();
         return;
       }
-      if (dragIndex === null && curveIndex === null) return;
+      if (dragIndex === null && curveIndex === null && segmentDrag.dragIndex === null) return;
       e.stopPropagation();
       const index = dragIndex;
       const shiftClicked = index !== null && e.shiftKey && !pressTravelled.current;
       setDragIndex(null);
       setCurveIndex(null);
+      segmentDrag.finish();
       dragOrigin.current = null;
       groupDrag.current = null;
       shiftAxis.current = null;
@@ -459,7 +504,7 @@ export function useAutomationLaneGestures({
       }
       commitPoints(lane.points, true);
     },
-    [rangeDrag, curveIndex, dragIndex, lane, commitPoints, stretch],
+    [rangeDrag, curveIndex, dragIndex, segmentDrag, lane, commitPoints, stretch],
   );
 
   /**
@@ -519,12 +564,15 @@ export function useAutomationLaneGestures({
   return {
     dragIndex,
     curveIndex,
+    segmentDragIndex: segmentDrag.dragIndex,
+    segmentHoverIndex: segmentDrag.hoverIndex,
     edgeDrag: stretch.edge,
     edgeHover: stretch.hover,
     cancelDrag,
     hint,
     hitIndex,
     segmentIndex,
+    onPointerLeave: segmentDrag.clearHover,
     onPointerDown,
     onPointerMove,
     endDrag,

package/src/player/components/useAutomationSegmentDrag.ts

@@ -0,0 +1,110 @@
+/**
+ * The grab target and translation gesture for one automation segment.
+ *
+ * Kept separate from the lane's gesture router: proximity is measured against
+ * the sampled envelope, while movement reuses the same shape-preserving group
+ * math as a box selection.
+ */
+
+import { useCallback, useRef, useState, type PointerEvent as ReactPointerEvent } from "react";
+import {
+  sampleAutomationLane,
+  type AutomationRange,
+  type HfAutomationLane,
+} from "@hyperframes/core/audio-automation";
+import { SEGMENT_GRAB_PX } from "./automationLaneGeometry";
+import { armSegmentDrag, computeGroupMove, type GroupDragSnapshot } from "./automationLaneDragMath";
+
+interface UseAutomationSegmentDragInput {
+  getBox(): DOMRect | null;
+  lane: HfAutomationLane;
+  range: AutomationRange;
+  pointAt(clientX: number, clientY: number): { t: number; v: number };
+  xOf(t: number): number;
+  yOf(v: number): number;
+  segmentIndex(clientX: number, clientY: number): number | null;
+  commitPoints(points: HfAutomationLane["points"], persist: boolean): void;
+  duration: number;
+  snapTimes: readonly number[] | undefined;
+  readOnly: boolean | undefined;
+  onHint(hint: string | null): void;
+}
+
+export function useAutomationSegmentDrag({
+  getBox,
+  lane,
+  range,
+  pointAt,
+  xOf,
+  yOf,
+  segmentIndex,
+  commitPoints,
+  duration,
+  snapTimes,
+  readOnly,
+  onHint,
+}: UseAutomationSegmentDragInput) {
+  const [dragIndex, setDragIndex] = useState<number | null>(null);
+  const [hoverIndex, setHoverIndex] = useState<number | null>(null);
+  const snapshot = useRef<GroupDragSnapshot | null>(null);
+
+  /** Segment whose drawn line is close enough to grab, or null. */
+  const hitIndex = useCallback(
+    (clientX: number, clientY: number): number | null => {
+      const box = getBox();
+      if (!box) return null;
+      const index = segmentIndex(clientX, clientY);
+      if (index === null) return null;
+      const { t } = pointAt(clientX, clientY);
+      const value = sampleAutomationLane(lane, t, range.scale);
+      return Math.abs(yOf(value) - (clientY - box.top)) <= SEGMENT_GRAB_PX ? index : null;
+    },
+    [getBox, lane, pointAt, range.scale, segmentIndex, yOf],
+  );
+
+  const arm = useCallback(
+    (index: number, clientX: number, clientY: number): void => {
+      snapshot.current = armSegmentDrag(lane, index, pointAt(clientX, clientY));
+      setHoverIndex(null);
+      setDragIndex(index);
+    },
+    [lane, pointAt],
+  );
+
+  const move = useCallback(
+    (e: ReactPointerEvent<SVGSVGElement>): void => {
+      const group = snapshot.current;
+      if (!group) return;
+      const moved = computeGroupMove({
+        group,
+        raw: pointAt(e.clientX, e.clientY),
+        shiftKey: e.shiftKey,
+        altKey: e.altKey,
+        range,
+        duration,
+        snapTimes,
+        xOf,
+        yOf,
+      });
+      onHint(moved.hint);
+      commitPoints(moved.points, false);
+    },
+    [commitPoints, duration, onHint, pointAt, range, snapTimes, xOf, yOf],
+  );
+
+  const finish = useCallback((): void => {
+    snapshot.current = null;
+    setDragIndex(null);
+  }, []);
+
+  const updateHover = useCallback(
+    (clientX: number, clientY: number): void => {
+      setHoverIndex(readOnly ? null : hitIndex(clientX, clientY));
+    },
+    [hitIndex, readOnly],
+  );
+
+  const clearHover = useCallback((): void => setHoverIndex(null), []);
+
+  return { dragIndex, hoverIndex, hitIndex, arm, move, finish, updateHover, clearHover };
+}

package/src/player/components/useTimelineClipDisclosure.ts

@@ -0,0 +1,41 @@
+/**
+ * Opening and closing a track's keyframe property lanes, with the telemetry that
+ * goes with it.
+ *
+ * Split out of `TimelineLanes.tsx` to keep that file under the studio's 600-line
+ * cap. Both callbacks were already the only place the disclosure state and its
+ * `keyframe_lane_expand` event were written together, which is what makes them a
+ * seam rather than a shuffle.
+ */
+
+import { usePlayerStore } from "../store/playerStore";
+import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
+
+export interface TimelineClipDisclosure {
+  /** The caret belongs to the ROW, so it opens and closes every clip on it at
+   *  once. Toggling only the active clip left the row's state depending on which
+   *  sibling happened to be selected: expand one, click another, and the row
+   *  collapsed under a caret that still pointed down. */
+  toggleRowExpanded: (keys: readonly string[]) => void;
+  toggleClipExpanded: (key: string) => void;
+}
+
+export function useTimelineClipDisclosure(): TimelineClipDisclosure {
+  const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
+  const expandClips = usePlayerStore((s) => s.expandClips);
+  const setClipExpanded = usePlayerStore((s) => s.setClipExpanded);
+  const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
+
+  return {
+    toggleRowExpanded: (keys) => {
+      const willExpand = !keys.some((key) => expandedClipIds.has(key));
+      trackStudioKeyframeLaneExpand({ expanded: willExpand });
+      if (willExpand) expandClips(keys);
+      else for (const key of keys) setClipExpanded(key, false);
+    },
+    toggleClipExpanded: (key) => {
+      trackStudioKeyframeLaneExpand({ expanded: !expandedClipIds.has(key) });
+      toggleClipExpanded(key);
+    },
+  };
+}

package/src/player/components/useTimelineLaneRowIndexes.ts

@@ -6,7 +6,7 @@ import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 /** The four pieces of group-disclosure state a group row's header reads and writes. */
 export function useTimelineGroupDisclosure() {
   return {
-    expandedGroupIds: usePlayerStore((s) => s.expandedGroupIds),
+    collapsedGroupIds: usePlayerStore((s) => s.collapsedGroupIds),
     expandedLaneOwnerIds: usePlayerStore((s) => s.expandedLaneOwnerIds),
     toggleGroupExpanded: usePlayerStore((s) => s.toggleGroupExpanded),
     toggleLaneOwnerExpanded: usePlayerStore((s) => s.toggleLaneOwnerExpanded),

package/src/player/components/useTimelineLogicalFocus.ts

@@ -35,7 +35,7 @@ interface TimelineLogicalFocusInput {
 
 export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
   const expandedClipIds = usePlayerStore((state) => state.expandedClipIds);
-  const expandedGroupIds = usePlayerStore((state) => state.expandedGroupIds);
+  const collapsedGroupIds = usePlayerStore((state) => state.collapsedGroupIds);
   const expandedLaneOwnerIds = usePlayerStore((state) => state.expandedLaneOwnerIds);
   const projectId = usePlayerStore((state) => state.timelineProjectId);
   const logicalRows = useTimelineLogicalRows({
@@ -45,7 +45,7 @@ export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
     selectedElementId: input.selectedElementId,
     selectedElementIds: input.selectedElementIds,
     expandedClipIds,
-    expandedGroupIds,
+    collapsedGroupIds,
     expandedLaneOwnerIds,
     groups: input.groups,
     trackGroupOf: input.trackGroupOf,

package/src/player/components/useTimelineLogicalRows.test.tsx

@@ -22,7 +22,7 @@ const displayTrackOrder = tracks.map(([track]) => track);
 const laneCounts = new Map<string, number>();
 const selectedElementIds = new Set<string>();
 const expandedClipIds = new Set<string>();
-const expandedGroupIds = new Set<string>();
+const collapsedGroupIds = new Set<string>();
 const expandedLaneOwnerIds = new Set<string>();
 const groups: never[] = [];
 const trackGroupOf = new Map();
@@ -37,7 +37,7 @@ function Harness({ snapshots }: { snapshots: Array<readonly TimelineLogicalRow[]
     selectedElementId: null,
     selectedElementIds,
     expandedClipIds,
-    expandedGroupIds,
+    collapsedGroupIds,
     expandedLaneOwnerIds,
     groups,
     trackGroupOf,

package/src/player/components/useTimelineLogicalRows.ts

@@ -14,7 +14,7 @@ export function useTimelineLogicalRows({
   selectedElementId,
   selectedElementIds,
   expandedClipIds,
-  expandedGroupIds,
+  collapsedGroupIds,
   expandedLaneOwnerIds,
   groups,
   trackGroupOf,
@@ -29,7 +29,7 @@ export function useTimelineLogicalRows({
         selectedElementId,
         selectedElementIds,
         expandedClipIds,
-        expandedGroupIds,
+        collapsedGroupIds,
         expandedLaneOwnerIds,
         groups,
         trackGroupOf,
@@ -38,7 +38,7 @@ export function useTimelineLogicalRows({
     [
       displayTrackOrder,
       expandedClipIds,
-      expandedGroupIds,
+      collapsedGroupIds,
       expandedLaneOwnerIds,
       groups,
       trackGroupOf,

package/src/player/components/useTimelineTrackDerivations.ts

@@ -1,5 +1,5 @@
 import { useMemo } from "react";
-import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { getTrackStyle, type TrackVisualStyle } from "./timelineIcons";
 
 /** One resolved audio group, positioned in the row order. */
@@ -15,12 +15,26 @@ export interface TimelineTrackGroupInfo {
   anchorKey: number;
   /** Member track numbers, ascending. */
   memberTracks: number[];
+  /**
+   * Every clip under this group, in member-track order — INDEPENDENT of whether
+   * the group is expanded.
+   *
+   * Collapsing a group stops emitting its member rows into `tracks`, so anything
+   * that recovered member elements by looking them up there got an empty list in
+   * the default (collapsed) state — silently disabling the
+   * automation-lane count, and the bus strip's member labels. Membership is not
+   * a display concern, so it does not travel through the display list.
+   */
+  memberElements: TimelineElement[];
   /** The group element's `data-volume`, mirrored from a member's parse (B7's slider). */
   volume: number;
   /** The group element's `data-hidden`, mirrored from a member's parse (B5's group mute). */
   hidden: boolean;
   /** The group element's serialized `data-fx-chain`, mirrored from a member's parse (C1's FX entry). */
   fxChain?: string;
+  /** The group element's serialized `data-automation` — the group's OWN lanes,
+   *  which are what its `∿` discloses (groups doc §5). */
+  automation?: string;
 }
 
 interface GroupMembership {
@@ -30,6 +44,7 @@ interface GroupMembership {
   volumeByGroup: Map<string, number>;
   hiddenByGroup: Map<string, boolean>;
   fxChainByGroup: Map<string, string | undefined>;
+  automationByGroup: Map<string, string | undefined>;
 }
 
 /** Which track belongs to which group, and each group's label/volume/hidden/fxChain — one pass over raw tracks. */
@@ -40,6 +55,7 @@ function resolveGroupMembership(rawTracks: [number, TimelineElement[]][]): Group
   const volumeByGroup = new Map<string, number>();
   const hiddenByGroup = new Map<string, boolean>();
   const fxChainByGroup = new Map<string, string | undefined>();
+  const automationByGroup = new Map<string, string | undefined>();
   for (const [trackNum, elements] of rawTracks) {
     const owner = elements.find((el) => el.audioGroup);
     if (!owner?.audioGroup) continue;
@@ -49,6 +65,7 @@ function resolveGroupMembership(rawTracks: [number, TimelineElement[]][]): Group
       volumeByGroup.set(owner.audioGroup, owner.audioGroupVolume ?? 1);
       hiddenByGroup.set(owner.audioGroup, owner.audioGroupHidden ?? false);
       fxChainByGroup.set(owner.audioGroup, owner.audioGroupFxChain);
+      automationByGroup.set(owner.audioGroup, owner.audioGroupAutomation);
     }
     const members = memberTracksByGroup.get(owner.audioGroup) ?? [];
     members.push(trackNum);
@@ -61,6 +78,7 @@ function resolveGroupMembership(rawTracks: [number, TimelineElement[]][]): Group
     volumeByGroup,
     hiddenByGroup,
     fxChainByGroup,
+    automationByGroup,
   };
 }
 
@@ -69,33 +87,50 @@ function buildGroupInfo(
   groupId: string,
   fallbackTrackNum: number,
   membership: GroupMembership,
+  rawByTrack: ReadonlyMap<number, TimelineElement[]>,
 ): TimelineTrackGroupInfo {
   const memberTracks = [...(membership.memberTracksByGroup.get(groupId) ?? [])].sort(
     (a, b) => a - b,
   );
   const fxChain = membership.fxChainByGroup.get(groupId);
+  const automation = membership.automationByGroup.get(groupId);
   return {
     id: groupId,
     label: membership.labelByGroup.get(groupId) ?? groupId,
+    // Exactly x.5, which sub-composition child rows are now kept strictly below
+    // (`useExpandedTimelineElements`) — they used to be able to land here and
+    // collide, duplicating the group header.
     anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
     memberTracks,
+    memberElements: memberTracks.flatMap((track) => rawByTrack.get(track) ?? []),
     volume: membership.volumeByGroup.get(groupId) ?? 1,
     hidden: membership.hiddenByGroup.get(groupId) ?? false,
     ...(fxChain ? { fxChain } : {}),
+    ...(automation ? { automation } : {}),
   };
 }
 
-/** Push a group's synthetic anchor row plus its members' rows, contiguously. */
+/**
+ * Push a group's synthetic anchor row plus its members' rows, contiguously.
+ *
+ * A collapsed group emits its anchor and nothing else. `buildTimelineLogicalRows`
+ * already stops at the anchor when collapsed, so leaving the member rows in
+ * `tracks` left row geometry reserving a full row each for rows that then
+ * rendered as `null` — a header trailed by its members' worth of blank,
+ * unreachable dead space. Membership still lands in `trackGroupOf`: a collapsed
+ * member is hidden, not ungrouped.
+ */
 function emitGroupRows(
   info: TimelineTrackGroupInfo,
   rawByTrack: ReadonlyMap<number, TimelineElement[]>,
   trackGroupOf: Map<number, TimelineTrackGroupInfo>,
   tracks: [number, TimelineElement[]][],
+  expanded: boolean,
 ): void {
   tracks.push([info.anchorKey, []]);
   for (const member of info.memberTracks) {
     trackGroupOf.set(member, info);
-    tracks.push([member, rawByTrack.get(member) ?? []]);
+    if (expanded) tracks.push([member, rawByTrack.get(member) ?? []]);
   }
 }
 
@@ -105,7 +140,10 @@ function emitGroupRows(
  * their position; a group's members move up to sit under its anchor even when
  * other (ungrouped) tracks were interleaved between them.
  */
-function groupTimelineTracks(rawTracks: [number, TimelineElement[]][]): {
+function groupTimelineTracks(
+  rawTracks: [number, TimelineElement[]][],
+  collapsedGroupIds: ReadonlySet<string>,
+): {
   tracks: [number, TimelineElement[]][];
   groups: TimelineTrackGroupInfo[];
   trackGroupOf: Map<number, TimelineTrackGroupInfo>;
@@ -125,9 +163,9 @@ function groupTimelineTracks(rawTracks: [number, TimelineElement[]][]): {
     }
     if (emitted.has(groupId)) continue;
     emitted.add(groupId);
-    const info = buildGroupInfo(groupId, trackNum, membership);
+    const info = buildGroupInfo(groupId, trackNum, membership, rawByTrack);
     groups.push(info);
-    emitGroupRows(info, rawByTrack, trackGroupOf, tracks);
+    emitGroupRows(info, rawByTrack, trackGroupOf, tracks, !collapsedGroupIds.has(groupId));
   }
   return { tracks, groups, trackGroupOf };
 }
@@ -156,9 +194,10 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])
     return Array.from(map.entries()).sort(([a], [b]) => a - b);
   }, [expandedElements]);
 
+  const collapsedGroupIds = usePlayerStore((s) => s.collapsedGroupIds);
   const { tracks, groups, trackGroupOf } = useMemo(
-    () => groupTimelineTracks(rawTracks),
-    [rawTracks],
+    () => groupTimelineTracks(rawTracks, collapsedGroupIds),
+    [rawTracks, collapsedGroupIds],
   );
 
   const trackStyles = useMemo(() => {

package/src/player/components/useTimelineTrackLayout.test.ts

@@ -38,6 +38,125 @@ function renderTrackLayout(
   return { layout, unmount: () => act(() => root.unmount()) };
 }
 
+describe("collapsed audio groups", () => {
+  const member = (id: string, track: number): TimelineElement => ({
+    id,
+    domId: id,
+    tag: "audio",
+    start: 0,
+    duration: 5,
+    track,
+    audioGroup: "voiceover",
+  });
+
+  /** `collapsed` seeds the collapsed set — expanded is the default state. */
+  function renderGrouped(collapsed = false): {
+    layout: ReturnType<typeof useTimelineTrackLayout>;
+    unmount: () => void;
+  } {
+    if (collapsed) usePlayerStore.setState({ collapsedGroupIds: new Set(["voiceover"]) });
+    const elements = [member("voice-1", 0), member("voice-2", 1)];
+    let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
+    function Probe() {
+      layout = useTimelineTrackLayout(elements, new Map(), null, new Set());
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    if (!layout) throw new Error("Timeline track layout did not render");
+    return { layout, unmount: () => act(() => root.unmount()) };
+  }
+
+  // The `∿` area holds the group's own automation rows. Sized without them,
+  // every lane the count had just promised was clipped out of the row — which
+  // is what "expanding automation on a group doesn't show the automation"
+  // looked like from outside.
+  it("reserves room for the group's own automation rows, not just the strip", () => {
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [
+        {
+          target: "volume",
+          points: [
+            { t: 0, v: 1 },
+            { t: 5, v: 0.4 },
+          ],
+        },
+      ],
+    });
+    const elements = [
+      { ...member("voice-1", 0), audioGroupAutomation: automation },
+      { ...member("voice-2", 1), audioGroupAutomation: automation },
+    ];
+    let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
+    function Probe() {
+      layout = useTimelineTrackLayout(elements, new Map(), null, new Set());
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => {
+      usePlayerStore.setState({ expandedLaneOwnerIds: new Set(["voiceover"]) });
+      root.render(React.createElement(Probe));
+    });
+    // The group's anchor row: the first member track minus 0.5.
+    const anchorIndex = layout!.tracks.findIndex(([track]) => track === -0.5);
+    expect(anchorIndex).toBeGreaterThanOrEqual(0);
+    const openHeight = layout!.rowHeights[anchorIndex];
+    // One lane of headroom beyond the header row itself.
+    expect(openHeight).toBe(TRACK_H + AUTOMATION_LANE_H);
+    act(() => root.unmount());
+  });
+
+  // buildTimelineLogicalRows stops emitting member rows once a group is
+  // collapsed, so TimelineLanes renders null for them. Rows left in `tracks`
+  // still reserve height, turning that null into visible dead space — the row
+  // list and the logical rows have to agree.
+  it("emits only the anchor row while the group is collapsed", () => {
+    const { layout, unmount } = renderGrouped(true);
+    expect(layout.groups).toHaveLength(1);
+    expect(layout.groups[0]!.memberTracks).toEqual([0, 1]);
+    // The anchor (0 - 0.5) and nothing else.
+    expect(layout.trackOrder).toEqual([-0.5]);
+    expect(layout.rowGeometry.rowHeights).toHaveLength(1);
+    // Membership still resolves — collapsed is hidden, not ungrouped.
+    expect(layout.trackGroupOf.get(0)?.id).toBe("voiceover");
+    unmount();
+  });
+
+  // Membership is not a display concern. Half-lit solo, the automation-lane
+  // count and the bus strip's member labels all read the group's members, and
+  // all three silently degraded to empty when those were recovered from the
+  // display list — which a collapsed group does not appear in. Collapsed is the
+  // default, so that was every group until someone opened it.
+  it("carries its member elements even while collapsed", () => {
+    const { layout, unmount } = renderGrouped(true);
+    expect(layout.trackOrder).toEqual([-0.5]); // collapsed: no member rows
+    expect(layout.groups[0]!.memberElements.map((el) => el.id)).toEqual(["voice-1", "voice-2"]);
+    unmount();
+  });
+
+  // The reason the set is stored inverted. As an expanded-set, "absent" could
+  // not tell never-touched from deliberately-collapsed, so a freshly created
+  // group started collapsed — grouping three tracks made all three vanish
+  // behind a header the user had not yet learned to open.
+  it("is expanded by default, with nothing seeded", () => {
+    const { layout, unmount } = renderGrouped();
+    expect(usePlayerStore.getState().collapsedGroupIds.size).toBe(0);
+    expect(layout.trackOrder).toEqual([-0.5, 0, 1]);
+    unmount();
+  });
+
+  it("emits the member rows once the group is expanded", () => {
+    // Expanded is the default now — nothing to seed.
+    const { layout, unmount } = renderGrouped();
+    expect(layout.trackOrder).toEqual([-0.5, 0, 1]);
+    for (const track of layout.groups[0]!.memberTracks) {
+      expect(layout.rowGeometry.getRowHeight(layout.rowGeometry.getRowIndex(track))).toBe(TRACK_H);
+    }
+    unmount();
+  });
+});
+
 describe("useTimelineTrackLayout", () => {
   it("counts a flat tween lane and reserves its expanded row height", () => {
     const elements: TimelineElement[] = [