@hyperframes/studio 0.8.6 → 0.8.7

package/src/player/components/timelineKeyboardNavigation.ts

@@ -1,6 +1,7 @@
 import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
 import type { TimelineElement } from "../store/playerStore";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { groupAutomationLanes } from "./automationLaneData";
 import {
   timelineKeyframeSelectionKey,
   type TimelineKeyframeTarget,
@@ -8,11 +9,13 @@ import {
 import {
   timelineClipFocusId,
   timelineEaseFocusId,
+  timelineGroupRowId,
   timelineKeyframeFocusId,
   timelinePropertyRowId,
   timelineTrackRowId,
 } from "./timelineNavigationIdentity";
 import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 
 export type TimelineNavigationKey =
   | "ArrowLeft"
@@ -54,9 +57,11 @@ export interface TimelineLogicalRow {
   kind: "row";
   physicalTrackKey: number;
   logicalIndex: number;
-  level: 1 | 2;
+  level: 1 | 2 | 3;
   parentId: string | null;
   elementId: string | null;
+  /** Set only on a group's own row (level 1, no clips of its own). */
+  groupId?: string;
   expandable: boolean;
   expanded: boolean;
   propertyGroup?: PropertyGroupName;
@@ -65,13 +70,19 @@ export interface TimelineLogicalRow {
 
 export type TimelineLogicalTarget = TimelineLogicalRow | TimelineLogicalItem;
 
-interface BuildTimelineLogicalRowsInput {
+export interface BuildTimelineLogicalRowsInput {
   tracks: readonly (readonly [number, readonly TimelineElement[]])[];
   displayTrackOrder: readonly number[];
   laneCounts: ReadonlyMap<string, number>;
   selectedElementId: string | null;
   selectedElementIds: ReadonlySet<string>;
   expandedClipIds: ReadonlySet<string>;
+  /** Groups whose member rows the caret has shown (structural, not lanes). */
+  expandedGroupIds: ReadonlySet<string>;
+  /** Rows (clip id or group id) whose automation-lane rows the `∿` button opened. */
+  expandedLaneOwnerIds: ReadonlySet<string>;
+  groups: readonly TimelineTrackGroupInfo[];
+  trackGroupOf: ReadonlyMap<number, TimelineTrackGroupInfo>;
   gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
 }
 
@@ -106,6 +117,35 @@ function clipItems(rowId: string, elements: readonly TimelineElement[]): Timelin
     });
 }
 
+/** A track's active clip (if any), its element id, and its automation lanes. */
+function resolveActiveTrackClip(
+  elements: readonly TimelineElement[],
+  laneCounts: BuildTimelineLogicalRowsInput["laneCounts"],
+  selectedElementId: string | null,
+  selectedElementIds: ReadonlySet<string>,
+  gsapAnimations: BuildTimelineLogicalRowsInput["gsapAnimations"],
+): {
+  activeClip: TimelineElement | null;
+  activeId: string | null;
+  lanes: ReturnType<typeof getTimelinePropertyLanes>;
+} {
+  const activeClip = resolveTrackKeyframeClip(
+    elements,
+    laneCounts,
+    selectedElementId,
+    selectedElementIds,
+  );
+  const activeId = activeClip ? elementId(activeClip) : null;
+  const lanes = activeClip
+    ? getTimelinePropertyLanes(
+        gsapAnimations.get(elementId(activeClip)) ?? [],
+        activeClip.start,
+        activeClip.duration,
+      )
+    : [];
+  return { activeClip, activeId, lanes };
+}
+
 function keyframeTarget(
   keyframe: ReturnType<typeof getTimelinePropertyLanes>[number]["keyframes"][number],
 ): TimelineKeyframeTarget {
@@ -167,6 +207,42 @@ function propertyItems(
   return items;
 }
 
+/** A clip's lanes are visible when either the caret or the `∿` button opened it. */
+function isRowOpen(
+  activeId: string | null,
+  expandedClipIds: ReadonlySet<string>,
+  expandedLaneOwnerIds: ReadonlySet<string>,
+): boolean {
+  if (activeId === null) return false;
+  return expandedClipIds.has(activeId) || expandedLaneOwnerIds.has(activeId);
+}
+
+/** A single automation-lane row, one level deeper than the track/group row that owns it. */
+function buildLaneRow(
+  track: number,
+  logicalIndex: number,
+  activeId: string,
+  activeClip: TimelineElement,
+  lane: ReturnType<typeof getTimelinePropertyLanes>[number],
+  level: 2 | 3,
+  parentId: string,
+): TimelineLogicalRow {
+  const laneRowId = timelinePropertyRowId(activeId, lane.group);
+  return {
+    id: laneRowId,
+    kind: "row",
+    physicalTrackKey: track,
+    logicalIndex,
+    level,
+    parentId,
+    elementId: activeId,
+    expandable: false,
+    expanded: false,
+    propertyGroup: lane.group,
+    items: propertyItems(laneRowId, activeClip, lane.keyframes),
+  };
+}
+
 /** Canonical model of the treegrid, independent of which virtual rows or clips are mounted. */
 export function buildTimelineLogicalRows({
   tracks,
@@ -175,57 +251,98 @@ export function buildTimelineLogicalRows({
   selectedElementId,
   selectedElementIds,
   expandedClipIds,
+  expandedGroupIds,
+  expandedLaneOwnerIds,
+  groups,
+  trackGroupOf,
   gsapAnimations,
 }: BuildTimelineLogicalRowsInput): TimelineLogicalRow[] {
   const trackMap = new Map(tracks);
+  const groupByAnchor = new Map(groups.map((group) => [group.anchorKey, group]));
   const rows: TimelineLogicalRow[] = [];
-  for (const track of displayTrackOrder) {
+
+  // A real track's own row (level 1 ungrouped, level 2 under a group) plus,
+  // when its clip's lanes are open, the lane rows one level deeper.
+  function emitTrack(track: number, level: 1 | 2, parentId: string | null): void {
     const elements = trackMap.get(track) ?? [];
     const trackId = timelineTrackRowId(track);
-    const activeClip = resolveTrackKeyframeClip(
+    const { activeClip, activeId, lanes } = resolveActiveTrackClip(
       elements,
       laneCounts,
       selectedElementId,
       selectedElementIds,
+      gsapAnimations,
     );
-    const activeId = activeClip ? elementId(activeClip) : null;
-    const lanes = activeClip
-      ? getTimelinePropertyLanes(
-          gsapAnimations.get(elementId(activeClip)) ?? [],
-          activeClip.start,
-          activeClip.duration,
-        )
-      : [];
-    const expanded = activeId !== null && expandedClipIds.has(activeId) && lanes.length > 0;
+    const expanded = isRowOpen(activeId, expandedClipIds, expandedLaneOwnerIds) && lanes.length > 0;
     rows.push({
       id: trackId,
       kind: "row",
       physicalTrackKey: track,
       logicalIndex: rows.length,
-      level: 1,
-      parentId: null,
+      level,
+      parentId,
       elementId: activeId,
       expandable: lanes.length > 0,
       expanded,
       items: clipItems(trackId, elements),
     });
-    if (!expanded || !activeClip) continue;
+    if (!expanded || !activeClip || !activeId) return;
     for (const lane of lanes) {
-      const rowId = timelinePropertyRowId(activeId, lane.group);
-      rows.push({
-        id: rowId,
-        kind: "row",
-        physicalTrackKey: track,
-        logicalIndex: rows.length,
-        level: 2,
-        parentId: trackId,
-        elementId: activeId,
-        expandable: false,
-        expanded: false,
-        propertyGroup: lane.group,
-        items: propertyItems(rowId, activeClip, lane.keyframes),
-      });
+      rows.push(
+        buildLaneRow(track, rows.length, activeId, activeClip, lane, level === 1 ? 2 : 3, trackId),
+      );
+    }
+  }
+
+  // A group's own row (level 1) plus, when its `∿` is open, its own
+  // automation-lane rows (level 2) — structural content deferred to whatever
+  // step wires group automation editing; this reserves the rows and their
+  // count.
+  function emitGroup(group: TimelineTrackGroupInfo): void {
+    const groupRowId = timelineGroupRowId(group.id);
+    const groupExpanded = expandedGroupIds.has(group.id);
+    rows.push({
+      id: groupRowId,
+      kind: "row",
+      physicalTrackKey: group.anchorKey,
+      logicalIndex: rows.length,
+      level: 1,
+      parentId: null,
+      elementId: null,
+      groupId: group.id,
+      expandable: group.memberTracks.length > 0,
+      expanded: groupExpanded,
+      items: [],
+    });
+    if (expandedLaneOwnerIds.has(group.id)) {
+      const memberElements = group.memberTracks.flatMap((track) => trackMap.get(track) ?? []);
+      for (const laneGroup of groupAutomationLanes(memberElements)) {
+        rows.push({
+          id: `${groupRowId}::${laneGroup.key}`,
+          kind: "row",
+          physicalTrackKey: group.anchorKey,
+          logicalIndex: rows.length,
+          level: 2,
+          parentId: groupRowId,
+          elementId: null,
+          expandable: false,
+          expanded: false,
+          items: [],
+        });
+      }
+    }
+    if (!groupExpanded) return;
+    for (const track of group.memberTracks) emitTrack(track, 2, groupRowId);
+  }
+
+  for (const key of displayTrackOrder) {
+    const group = groupByAnchor.get(key);
+    if (group) {
+      emitGroup(group);
+      continue;
     }
+    if (trackGroupOf.has(key)) continue; // emitted above, under its group
+    emitTrack(key, 1, null);
   }
   return rows;
 }

package/src/player/components/timelineLaneProps.ts

@@ -13,6 +13,7 @@ import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
 import type { TimelineClipRenderContext } from "./TimelineTypes";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 
 /**
  * Props shared by the scroll container ({@link import("./TimelineCanvas")}) and
@@ -99,6 +100,8 @@ export interface TimelineLaneBaseProps {
    */
   onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
   beatAnalysis?: MusicBeatAnalysis | null;
+  /** Resolved audio groups, positioned in row order — see useTimelineTrackDerivations. */
+  groups: readonly TimelineTrackGroupInfo[];
 }
 
 /**

package/src/player/components/timelineLayout.ts

@@ -7,10 +7,10 @@ export const GUTTER = 32;
 export const LABEL_COL_W = 232;
 export const TRACK_H = 48;
 export const LANE_H = 28;
+export const STRIP_H = 40; // group bus strip (B7) — one fixed block, not per-property like LANE_H
 export const RULER_H = 24;
 export const CLIP_Y = 3;
 export const CLIP_HANDLE_W = 18;
-
 export interface TimelineBeatEntry {
   readonly index: number;
   readonly time: number;

package/src/player/components/timelineNavigationIdentity.ts

@@ -13,6 +13,10 @@ export function timelineTrackRowId(track: number): string {
   return stableId("track", track);
 }
 
+export function timelineGroupRowId(groupId: string): string {
+  return stableId("group", groupId);
+}
+
 export function timelinePropertyRowId(elementId: string, group: PropertyGroupName): string {
   return stableId("property", elementId, group);
 }

package/src/player/components/useTimelineLaneRowIndexes.ts

@@ -0,0 +1,38 @@
+import { useMemo } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+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),
+    expandedLaneOwnerIds: usePlayerStore((s) => s.expandedLaneOwnerIds),
+    toggleGroupExpanded: usePlayerStore((s) => s.toggleGroupExpanded),
+    toggleLaneOwnerExpanded: usePlayerStore((s) => s.toggleLaneOwnerExpanded),
+  };
+}
+
+/** Two lookups TimelineLanes needs once per render: a row's logical rows by
+ *  physical key, and which physical key is a group's own anchor row. */
+export function useTimelineLaneRowIndexes(
+  logicalRows: readonly TimelineLogicalRow[],
+  groups: readonly TimelineTrackGroupInfo[],
+) {
+  const logicalRowsByTrack = useMemo(() => {
+    const byTrack = new Map<number, TimelineLogicalRow[]>();
+    for (const logicalRow of logicalRows) {
+      const trackRows = byTrack.get(logicalRow.physicalTrackKey) ?? [];
+      trackRows.push(logicalRow);
+      byTrack.set(logicalRow.physicalTrackKey, trackRows);
+    }
+    return byTrack;
+  }, [logicalRows]);
+
+  const groupByAnchor = useMemo(
+    () => new Map(groups.map((group) => [group.anchorKey, group])),
+    [groups],
+  );
+
+  return { logicalRowsByTrack, groupByAnchor };
+}

package/src/player/components/useTimelineLogicalFocus.ts

@@ -3,6 +3,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
 import { usePlayerStore } from "../store/playerStore";
 import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
@@ -15,6 +16,8 @@ interface TimelineLogicalFocusInput {
   laneCounts: ReadonlyMap<string, number>;
   selectedElementId: string | null;
   selectedElementIds: ReadonlySet<string>;
+  groups: readonly TimelineTrackGroupInfo[];
+  trackGroupOf: ReadonlyMap<number, TimelineTrackGroupInfo>;
   gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
   elements: readonly TimelineElement[];
   pixelsPerSecond: number;
@@ -32,6 +35,8 @@ interface TimelineLogicalFocusInput {
 
 export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
   const expandedClipIds = usePlayerStore((state) => state.expandedClipIds);
+  const expandedGroupIds = usePlayerStore((state) => state.expandedGroupIds);
+  const expandedLaneOwnerIds = usePlayerStore((state) => state.expandedLaneOwnerIds);
   const projectId = usePlayerStore((state) => state.timelineProjectId);
   const logicalRows = useTimelineLogicalRows({
     tracks: input.tracks,
@@ -40,6 +45,10 @@ export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
     selectedElementId: input.selectedElementId,
     selectedElementIds: input.selectedElementIds,
     expandedClipIds,
+    expandedGroupIds,
+    expandedLaneOwnerIds,
+    groups: input.groups,
+    trackGroupOf: input.trackGroupOf,
     gsapAnimations: input.gsapAnimations,
   });
   const focus = useTimelineFocusCoordinator({

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

@@ -22,6 +22,10 @@ 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 expandedLaneOwnerIds = new Set<string>();
+const groups: never[] = [];
+const trackGroupOf = new Map();
 const gsapAnimations = new Map();
 
 function Harness({ snapshots }: { snapshots: Array<readonly TimelineLogicalRow[]> }) {
@@ -33,6 +37,10 @@ function Harness({ snapshots }: { snapshots: Array<readonly TimelineLogicalRow[]
     selectedElementId: null,
     selectedElementIds,
     expandedClipIds,
+    expandedGroupIds,
+    expandedLaneOwnerIds,
+    groups,
+    trackGroupOf,
     gsapAnimations,
   });
   snapshots.push(logicalRows);

package/src/player/components/useTimelineLogicalRows.ts

@@ -1,17 +1,10 @@
 import { useMemo } from "react";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import type { TimelineElement } from "../store/playerStore";
-import { buildTimelineLogicalRows } from "./timelineKeyboardNavigation";
+import {
+  buildTimelineLogicalRows,
+  type BuildTimelineLogicalRowsInput,
+} from "./timelineKeyboardNavigation";
 
-interface TimelineLogicalRowsInput {
-  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
-  displayTrackOrder: readonly number[];
-  laneCounts: ReadonlyMap<string, number>;
-  selectedElementId: string | null;
-  selectedElementIds: ReadonlySet<string>;
-  expandedClipIds: ReadonlySet<string>;
-  gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
-}
+type TimelineLogicalRowsInput = BuildTimelineLogicalRowsInput;
 
 /** Shared by rendering and focus coordination; stable input refs preserve memo identity. */
 export function useTimelineLogicalRows({
@@ -21,6 +14,10 @@ export function useTimelineLogicalRows({
   selectedElementId,
   selectedElementIds,
   expandedClipIds,
+  expandedGroupIds,
+  expandedLaneOwnerIds,
+  groups,
+  trackGroupOf,
   gsapAnimations,
 }: TimelineLogicalRowsInput) {
   return useMemo(
@@ -32,11 +29,19 @@ export function useTimelineLogicalRows({
         selectedElementId,
         selectedElementIds,
         expandedClipIds,
+        expandedGroupIds,
+        expandedLaneOwnerIds,
+        groups,
+        trackGroupOf,
         gsapAnimations,
       }),
     [
       displayTrackOrder,
       expandedClipIds,
+      expandedGroupIds,
+      expandedLaneOwnerIds,
+      groups,
+      trackGroupOf,
       gsapAnimations,
       laneCounts,
       selectedElementId,

package/src/player/components/useTimelineMultiDragActorWindows.ts

@@ -0,0 +1,30 @@
+import { isMultiDragActive, multiDragDeltaSeconds } from "./timelineMultiDragPreview";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
+
+/** The extra render window a live multi-drag needs: its passengers still draw
+ *  at their ORIGIN position, offset by the drag delta, outside the normal
+ *  virtualized range. Empty when nothing is dragging. */
+export function useTimelineMultiDragActorWindows(
+  multiDragPreview: MultiDragPreviewInput | null,
+  rowsVirtualized: boolean,
+  renderTimeRange: TimelineTimeRange,
+) {
+  const multiDragDelta =
+    multiDragPreview && isMultiDragActive(multiDragPreview)
+      ? multiDragDeltaSeconds(multiDragPreview)
+      : 0;
+  const actorWindows =
+    rowsVirtualized && multiDragPreview && multiDragDelta !== 0
+      ? [
+          {
+            range: {
+              start: renderTimeRange.start - multiDragDelta,
+              end: renderTimeRange.end - multiDragDelta,
+            },
+            identities: multiDragPreview.selectedKeys,
+          },
+        ]
+      : [];
+  return actorWindows;
+}

package/src/player/components/useTimelineTrackDerivations.ts

@@ -1,20 +1,153 @@
 import { useMemo } from "react";
 import type { TimelineElement } from "../store/playerStore";
+import { isCanaryEnabled } from "../../telemetry/canary";
 import { getTrackStyle, type TrackVisualStyle } from "./timelineIcons";
 
+/** One resolved audio group, positioned in the row order. */
+export interface TimelineTrackGroupInfo {
+  id: string;
+  label: string;
+  /**
+   * Synthetic sort key for the group's own row — the same fractional-key
+   * convention sub-composition expansion already uses (see
+   * timelineTrackDisplay.ts): the first (lowest) member track's number minus
+   * 0.5, so it slots in immediately above that member.
+   */
+  anchorKey: number;
+  /** Member track numbers, ascending. */
+  memberTracks: number[];
+  /** 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;
+}
+
+interface GroupMembership {
+  trackToGroupId: Map<number, string>;
+  memberTracksByGroup: Map<string, number[]>;
+  labelByGroup: Map<string, string>;
+  volumeByGroup: Map<string, number>;
+  hiddenByGroup: Map<string, boolean>;
+  fxChainByGroup: Map<string, string | undefined>;
+}
+
+/** Which track belongs to which group, and each group's label/volume/hidden/fxChain — one pass over raw tracks. */
+function resolveGroupMembership(rawTracks: [number, TimelineElement[]][]): GroupMembership {
+  const trackToGroupId = new Map<number, string>();
+  const memberTracksByGroup = new Map<string, number[]>();
+  const labelByGroup = new Map<string, string>();
+  const volumeByGroup = new Map<string, number>();
+  const hiddenByGroup = new Map<string, boolean>();
+  const fxChainByGroup = new Map<string, string | undefined>();
+  for (const [trackNum, elements] of rawTracks) {
+    const owner = elements.find((el) => el.audioGroup);
+    if (!owner?.audioGroup) continue;
+    trackToGroupId.set(trackNum, owner.audioGroup);
+    if (!labelByGroup.has(owner.audioGroup)) {
+      labelByGroup.set(owner.audioGroup, owner.audioGroupLabel ?? owner.audioGroup);
+      volumeByGroup.set(owner.audioGroup, owner.audioGroupVolume ?? 1);
+      hiddenByGroup.set(owner.audioGroup, owner.audioGroupHidden ?? false);
+      fxChainByGroup.set(owner.audioGroup, owner.audioGroupFxChain);
+    }
+    const members = memberTracksByGroup.get(owner.audioGroup) ?? [];
+    members.push(trackNum);
+    memberTracksByGroup.set(owner.audioGroup, members);
+  }
+  return {
+    trackToGroupId,
+    memberTracksByGroup,
+    labelByGroup,
+    volumeByGroup,
+    hiddenByGroup,
+    fxChainByGroup,
+  };
+}
+
+/** One group's resolved row info, built once the first time its id is seen. */
+function buildGroupInfo(
+  groupId: string,
+  fallbackTrackNum: number,
+  membership: GroupMembership,
+): TimelineTrackGroupInfo {
+  const memberTracks = [...(membership.memberTracksByGroup.get(groupId) ?? [])].sort(
+    (a, b) => a - b,
+  );
+  const fxChain = membership.fxChainByGroup.get(groupId);
+  return {
+    id: groupId,
+    label: membership.labelByGroup.get(groupId) ?? groupId,
+    anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
+    memberTracks,
+    volume: membership.volumeByGroup.get(groupId) ?? 1,
+    hidden: membership.hiddenByGroup.get(groupId) ?? false,
+    ...(fxChain ? { fxChain } : {}),
+  };
+}
+
+/** Push a group's synthetic anchor row plus its members' rows, contiguously. */
+function emitGroupRows(
+  info: TimelineTrackGroupInfo,
+  rawByTrack: ReadonlyMap<number, TimelineElement[]>,
+  trackGroupOf: Map<number, TimelineTrackGroupInfo>,
+  tracks: [number, TimelineElement[]][],
+): void {
+  tracks.push([info.anchorKey, []]);
+  for (const member of info.memberTracks) {
+    trackGroupOf.set(member, info);
+    tracks.push([member, rawByTrack.get(member) ?? []]);
+  }
+}
+
+/**
+ * Pull each group's members out of raw ascending track order and re-emit them
+ * contiguously, directly beneath a synthetic anchor row. Ungrouped tracks keep
+ * 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[]][]): {
+  tracks: [number, TimelineElement[]][];
+  groups: TimelineTrackGroupInfo[];
+  trackGroupOf: Map<number, TimelineTrackGroupInfo>;
+} {
+  const membership = resolveGroupMembership(rawTracks);
+  const rawByTrack = new Map(rawTracks);
+  const groups: TimelineTrackGroupInfo[] = [];
+  const trackGroupOf = new Map<number, TimelineTrackGroupInfo>();
+  const emitted = new Set<string>();
+  const tracks: [number, TimelineElement[]][] = [];
+
+  for (const [trackNum, elements] of rawTracks) {
+    const groupId = membership.trackToGroupId.get(trackNum);
+    if (!groupId) {
+      tracks.push([trackNum, elements]);
+      continue;
+    }
+    if (emitted.has(groupId)) continue;
+    emitted.add(groupId);
+    const info = buildGroupInfo(groupId, trackNum, membership);
+    groups.push(info);
+    emitGroupRows(info, rawByTrack, trackGroupOf, tracks);
+  }
+  return { tracks, groups, trackGroupOf };
+}
+
 /**
  * Per-render track derivations Timeline.tsx feeds the canvas/lanes: the lane →
- * clip grouping (`tracks`, ascending), per-lane visual styles, the ascending
- * `trackOrder`, and the z-override badge set. Extracted from Timeline.tsx as a
- * cohesive unit (600-line studio cap); each memo keys on the expanded display
- * element set exactly as before.
+ * clip grouping (`tracks`, group-aware order), per-lane visual styles, the
+ * matching `trackOrder`, and audio-group membership. Extracted from
+ * Timeline.tsx as a cohesive unit (600-line studio cap); each memo keys on the
+ * expanded display element set exactly as before.
  */
 export function useTimelineTrackDerivations(expandedElements: TimelineElement[]): {
   tracks: [number, TimelineElement[]][];
   trackStyles: Map<number, TrackVisualStyle>;
   trackOrder: number[];
+  groups: TimelineTrackGroupInfo[];
+  trackGroupOf: Map<number, TimelineTrackGroupInfo>;
 } {
-  const tracks = useMemo(() => {
+  const rawTracks = useMemo(() => {
     const map = new Map<number, TimelineElement[]>();
     for (const el of expandedElements) {
       const list = map.get(el.track) ?? [];
@@ -24,6 +157,17 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])
     return Array.from(map.entries()).sort(([a], [b]) => a - b);
   }, [expandedElements]);
 
+  const { tracks, groups, trackGroupOf } = useMemo(() => {
+    if (!isCanaryEnabled("audio-groups")) {
+      return {
+        tracks: rawTracks,
+        groups: [],
+        trackGroupOf: new Map<number, TimelineTrackGroupInfo>(),
+      };
+    }
+    return groupTimelineTracks(rawTracks);
+  }, [rawTracks]);
+
   const trackStyles = useMemo(() => {
     const map = new Map<number, TrackVisualStyle>();
     for (const [trackNum, els] of tracks) {
@@ -34,5 +178,5 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])
 
   const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
 
-  return { tracks, trackStyles, trackOrder };
+  return { tracks, trackStyles, trackOrder, groups, trackGroupOf };
 }