@hyperframes/studio 0.8.5 → 0.8.7

package/src/player/components/TimelineGroupBusStrip.tsx

@@ -0,0 +1,103 @@
+/**
+ * B7: the group's own volume slider + a living level bar + "Holds …" — the
+ * bus, not the mechanism. No dB numbers, no peak-hold readout, no routing
+ * row (groups doc §5, casual-user section) — a slider, a bar that moves with
+ * the sound, and the words "Too loud" when it clips.
+ */
+import { useEffect, useRef, useState } from "react";
+import { useGroupLevel } from "../../hooks/useGroupLevel";
+import { STRIP_H, TRACK_H } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+
+/** How long "Too loud" stays lit after the last clipped block. */
+const CLIP_HOLD_MS = 2000;
+
+function clampVolume(value: number): number {
+  return Math.min(2, Math.max(0, value));
+}
+
+interface TimelineGroupBusStripProps {
+  groupId: string;
+  volume: number;
+  memberLabels: readonly string[];
+  onVolumeChange: (value: number) => void;
+  onVolumeCommit: (value: number) => void;
+  theme: TimelineTheme;
+}
+
+export function TimelineGroupBusStrip({
+  groupId,
+  volume,
+  memberLabels,
+  onVolumeChange,
+  onVolumeCommit,
+  theme,
+}: TimelineGroupBusStripProps) {
+  const [dragValue, setDragValue] = useState<number | null>(null);
+  const reading = useGroupLevel(groupId);
+  const [clipped, setClipped] = useState(false);
+  const clipTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!reading?.clipped) return;
+    setClipped(true);
+    if (clipTimerRef.current) clearTimeout(clipTimerRef.current);
+    clipTimerRef.current = setTimeout(() => setClipped(false), CLIP_HOLD_MS);
+  }, [reading?.clipped]);
+
+  useEffect(
+    () => () => {
+      if (clipTimerRef.current) clearTimeout(clipTimerRef.current);
+    },
+    [],
+  );
+
+  const shownVolume = dragValue ?? volume;
+  const level = Math.min(1, reading?.level ?? 0);
+  const holdsText =
+    memberLabels.length > 0 ? `Holds ${memberLabels.join(", ")}` : "Holds nothing yet";
+
+  return (
+    <div
+      className="absolute left-0 right-0 flex items-center gap-2 px-2 text-[10px] text-white/70"
+      style={{ top: TRACK_H, height: STRIP_H }}
+    >
+      <input
+        type="range"
+        aria-label="Group volume"
+        min={0}
+        max={2}
+        step={0.01}
+        value={shownVolume}
+        className="h-1 w-20 shrink-0 accent-[#3CE6AC]"
+        onChange={(event) => {
+          const next = clampVolume(Number(event.currentTarget.value));
+          setDragValue(next);
+          onVolumeChange(next);
+        }}
+        onPointerUp={(event) => {
+          const next = clampVolume(Number(event.currentTarget.value));
+          setDragValue(null);
+          onVolumeCommit(next);
+        }}
+      />
+      <div
+        className="relative h-1.5 w-16 shrink-0 overflow-hidden rounded-full"
+        style={{ background: theme.gutterBorder }}
+        aria-hidden="true"
+      >
+        <div
+          className="absolute inset-y-0 left-0 rounded-full"
+          style={{
+            width: `${level * 100}%`,
+            background: clipped ? "#ff5c5c" : "#3CE6AC",
+          }}
+        />
+      </div>
+      {clipped && <span className="shrink-0 font-medium text-[#ff5c5c]">Too loud</span>}
+      <span className="min-w-0 flex-1 truncate" title={holdsText}>
+        {holdsText}
+      </span>
+    </div>
+  );
+}

package/src/player/components/TimelineGroupHeader.tsx

@@ -0,0 +1,176 @@
+import { SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { TRACK_H } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+import { TimelineFxButton } from "./TimelineFxButton";
+
+interface TimelineGroupHeaderProps {
+  label: string;
+  memberCount: number;
+  /** Caret: shows/hides the member rows beneath this group (structural). */
+  isExpanded: boolean;
+  onToggleExpanded: () => void;
+  /** `∿`: shows/hides the group's own automation-lane rows. */
+  laneCount: number;
+  isLaneOpen: boolean;
+  onToggleLanes: () => void;
+  /** The group element's own `data-hidden` — mutes every member at once. */
+  hidden: boolean;
+  onToggleHidden: () => void;
+  /** This group id is itself in the soloed set (fully lit). */
+  isSoloed: boolean;
+  /** Not soloed itself, but at least one member is (half-lit). */
+  isHalfLitSolo: boolean;
+  /** `add: true` (⌘/Ctrl-click) toggles membership; a plain click is exclusive. */
+  onToggleSolo: (options?: { add?: boolean }) => void;
+  /** C1: the group's serialized `data-fx-chain`, when set. */
+  fxChain?: string;
+  onFxChainChange: (next: HfAudioFxChain) => void;
+  onFxChainPreview?: (next: HfAudioFxChain) => void;
+  onFxAuditionTransport?: (on: boolean) => void;
+  onOpenFxRack: () => void;
+  columnWidth: number;
+  theme: TimelineTheme;
+}
+
+/**
+ * A group's own row header: caret (member disclosure) + `▤` + label + count +
+ * mute + solo + FX + `∿ n` (lane disclosure).
+ */
+export function TimelineGroupHeader({
+  label,
+  memberCount,
+  isExpanded,
+  onToggleExpanded,
+  laneCount,
+  isLaneOpen,
+  onToggleLanes,
+  hidden,
+  onToggleHidden,
+  isSoloed,
+  isHalfLitSolo,
+  onToggleSolo,
+  fxChain,
+  onFxChainChange,
+  onFxChainPreview,
+  onFxAuditionTransport,
+  onOpenFxRack,
+  columnWidth,
+  theme,
+}: TimelineGroupHeaderProps) {
+  return (
+    <div
+      role="rowheader"
+      aria-colindex={1}
+      className="sticky left-0 z-[12] flex shrink-0 items-center gap-1.5 overflow-hidden px-1.5 text-[11px]"
+      style={{
+        width: columnWidth,
+        height: TRACK_H,
+        color: "#ffffff",
+        background: theme.gutterBackground,
+        borderRight: `1px solid ${theme.gutterBorder}`,
+      }}
+    >
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-expanded={isExpanded}
+        aria-label={`${isExpanded ? "Hide" : "Show"} ${label} tracks`}
+        title={`${isExpanded ? "Hide" : "Show"} tracks`}
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+          isExpanded ? "text-white" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleExpanded();
+        }}
+      >
+        <span aria-hidden="true" style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}>
+          ▸
+        </span>
+      </button>
+      <span aria-hidden="true" className="shrink-0 text-[12px] leading-none text-white/50">
+        ▤
+      </span>
+      <span className="min-w-0 flex-1 truncate font-medium" title={label}>
+        {label}
+      </span>
+      <span
+        className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
+        aria-hidden="true"
+        title={`${memberCount} tracks`}
+      >
+        {memberCount}
+      </span>
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-label={hidden ? "Unmute group" : `Mute group ${label}`}
+        title={hidden ? "Unmute group" : `Mute group ${label}`}
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+          hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleHidden();
+        }}
+      >
+        {hidden ? (
+          <SpeakerSlash size={14} weight="bold" aria-hidden="true" />
+        ) : (
+          <SpeakerHigh size={14} weight="bold" aria-hidden="true" />
+        )}
+      </button>
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-pressed={isSoloed}
+        aria-label="Hear only this"
+        title="Hear only this"
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[13px] font-semibold transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+          isSoloed
+            ? "text-[#F5C542] hover:text-white"
+            : isHalfLitSolo
+              ? "text-[#F5C542]/50 hover:text-white"
+              : "text-white/35 hover:text-white/75"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleSolo({ add: event.metaKey || event.ctrlKey });
+        }}
+      >
+        <span aria-hidden="true">⌗</span>
+      </button>
+      <TimelineFxButton
+        fxChainRaw={fxChain}
+        onChainChange={onFxChainChange}
+        onChainPreview={onFxChainPreview}
+        onAuditionTransport={onFxAuditionTransport}
+        onOpenRack={onOpenFxRack}
+      />
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-expanded={isLaneOpen}
+        aria-label={`${isLaneOpen ? "Hide" : "Show"} ${label} lanes`}
+        title={`${isLaneOpen ? "Hide" : "Show"} lanes`}
+        className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+          isLaneOpen ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleLanes();
+        }}
+      >
+        <span aria-hidden="true">∿</span>
+        {laneCount > 0 && (
+          <span className="text-[9px] tabular-nums text-white/55">{laneCount}</span>
+        )}
+      </button>
+    </div>
+  );
+}

package/src/player/components/TimelineGroupRow.tsx

@@ -0,0 +1,146 @@
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import { isGroupHalfLitUnderSolo } from "../store/audioSoloSlice";
+import {
+  HF_AUDIO_FX_ATTR,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { TimelineTrackRow } from "./TimelineTrackRow";
+import { TimelineGroupHeader } from "./TimelineGroupHeader";
+import { TimelineGroupBusStrip } from "./TimelineGroupBusStrip";
+import { groupAutomationLanes } from "./automationLaneData";
+import { LABEL_COL_W } from "./timelineLayout";
+import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
+import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+
+interface TimelineGroupRowProps {
+  index: number;
+  rowKey: number;
+  group: TimelineTrackGroupInfo;
+  logicalRow: TimelineLogicalRow;
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
+  top: number;
+  height: number;
+  virtualized: boolean;
+  contentOrigin: number;
+  theme: TimelineTheme;
+  rovingTargetId?: string | null;
+  expandedGroupIds: ReadonlySet<string>;
+  expandedLaneOwnerIds: ReadonlySet<string>;
+  toggleGroupExpanded: (id: string) => void;
+  toggleLaneOwnerExpanded: (id: string) => void;
+}
+
+/** A group's own row: the accessible shell (shared with track rows) plus the group header. */
+export function TimelineGroupRow({
+  index,
+  rowKey,
+  group,
+  logicalRow,
+  tracks,
+  top,
+  height,
+  virtualized,
+  contentOrigin,
+  theme,
+  rovingTargetId = null,
+  expandedGroupIds,
+  expandedLaneOwnerIds,
+  toggleGroupExpanded,
+  toggleLaneOwnerExpanded,
+}: TimelineGroupRowProps) {
+  const memberElements = group.memberTracks.flatMap(
+    (track) => tracks.find(([t]) => t === track)?.[1] ?? [],
+  );
+  const memberLabels = group.memberTracks.map((track, i) => {
+    const owner = tracks.find(([t]) => t === track)?.[1]?.find((el) => el.audioGroup);
+    return owner?.label ?? owner?.id ?? `track ${i + 1}`;
+  });
+  const isLaneOpen = expandedLaneOwnerIds.has(group.id);
+  const { onSetAudioGroupAttributeLive, onSetAudioGroupAttributeQuiet } = useTimelineEditContext();
+  const domEditActions = useDomEditActionsContextOptional();
+  const soloed = usePlayerStore((s) => s.soloed);
+  const toggleSolo = usePlayerStore((s) => s.toggleSolo);
+  const memberIds = memberElements.map((el) => el.key ?? el.id);
+  const writeGroupFxChain = (next: HfAudioFxChain, live: boolean) => {
+    const value = next.nodes.length ? serializeAudioFxChain(next) : null;
+    if (live) onSetAudioGroupAttributeLive?.(group.id, HF_AUDIO_FX_ATTR, value);
+    else void onSetAudioGroupAttributeQuiet?.(group.id, HF_AUDIO_FX_ATTR, value, "Apply preset");
+  };
+  const openGroupFxRack = () => {
+    const target = domEditActions?.previewIframeRef.current?.contentDocument?.getElementById(
+      group.id,
+    );
+    if (!target) return;
+    void domEditActions
+      ?.buildDomSelectionFromTarget(target)
+      .then((selection) => selection && domEditActions.applyDomSelection(selection));
+  };
+  return (
+    <TimelineTrackRow
+      index={index}
+      rowKey={rowKey}
+      logicalRow={logicalRow}
+      propertyRows={[]}
+      lanesId=""
+      headerLanesId=""
+      top={top}
+      height={height}
+      virtualized={virtualized}
+      background={theme.rowBackground}
+      borderColor={theme.rowBorder}
+      rovingTargetId={rovingTargetId}
+    >
+      <TimelineGroupHeader
+        label={group.label}
+        memberCount={group.memberTracks.length}
+        isExpanded={expandedGroupIds.has(group.id)}
+        onToggleExpanded={() => toggleGroupExpanded(group.id)}
+        laneCount={groupAutomationLanes(memberElements).length}
+        isLaneOpen={isLaneOpen}
+        onToggleLanes={() => toggleLaneOwnerExpanded(group.id)}
+        hidden={group.hidden}
+        onToggleHidden={() =>
+          onSetAudioGroupAttributeQuiet?.(
+            group.id,
+            "data-hidden",
+            group.hidden ? null : "",
+            group.hidden ? "Unmute group" : `Mute group ${group.label}`,
+          )
+        }
+        isSoloed={soloed.has(group.id)}
+        isHalfLitSolo={isGroupHalfLitUnderSolo(soloed, group.id, memberIds)}
+        onToggleSolo={(options) => toggleSolo(group.id, options)}
+        fxChain={group.fxChain}
+        onFxChainChange={(next) => writeGroupFxChain(next, false)}
+        onFxChainPreview={(next) => writeGroupFxChain(next, true)}
+        onOpenFxRack={openGroupFxRack}
+        columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
+        theme={theme}
+      />
+      {isLaneOpen && (
+        <TimelineGroupBusStrip
+          groupId={group.id}
+          volume={group.volume}
+          memberLabels={memberLabels}
+          onVolumeChange={(value) =>
+            onSetAudioGroupAttributeLive?.(group.id, "data-volume", String(value))
+          }
+          onVolumeCommit={(value) =>
+            onSetAudioGroupAttributeQuiet?.(
+              group.id,
+              "data-volume",
+              String(value),
+              "Set group volume",
+            )
+          }
+          theme={theme}
+        />
+      )}
+    </TimelineTrackRow>
+  );
+}

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

@@ -118,6 +118,10 @@ function renderLanes(options: RenderLanesOptions = {}): {
             selectedElementId: null,
             selectedElementIds: next.selectedElementIds ?? new Set(),
             expandedClipIds: new Set(next.expandedClipIds ?? []),
+            expandedGroupIds: new Set(),
+            expandedLaneOwnerIds: new Set(),
+            groups: [],
+            trackGroupOf: new Map(),
             gsapAnimations,
           })}
           clipIndex={createTimelineClipIndex(tracks)}
@@ -127,6 +131,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
           trackOrder={displayTrackOrder}
           tracks={tracks}
           trackStyles={new Map()}
+          groups={[]}
           laneCounts={laneCounts}
           selectedElementId={null}
           selectedElementIds={next.selectedElementIds ?? new Set()}

package/src/player/components/TimelineLanes.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useId, useMemo } from "react";
+import { Fragment, useId } from "react";
 import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineCompactDiamonds } from "./TimelineCompactDiamonds";
@@ -7,6 +7,8 @@ import { TimelineAutomationLaneSlot } from "./TimelineAutomationLaneSlot";
 import { useAutomationLanes } from "./useAutomationLanes";
 import { useAutomationSelectionKeyboard } from "../../hooks/useAutomationSelectionKeyboard";
 import { TimelineTrackHeader } from "./TimelineTrackHeader";
+import { TimelineGroupRow } from "./TimelineGroupRow";
+import { useTimelineLaneRowIndexes, useTimelineGroupDisclosure } from "./useTimelineLaneRowIndexes";
 import {
   isTrackRowExpanded,
   resolveTrackKeyframeClip,
@@ -17,12 +19,8 @@ import { clipTimingStart } from "../../hooks/gsapShared";
 import { getTimelineEditCapabilities } from "./timelineEditing";
 import { CLIP_Y, TRACK_H } from "./timelineLayout";
 import { usePlayerStore } from "../store/playerStore";
-import {
-  isMultiDragActive,
-  isMultiDragPassenger,
-  multiDragDeltaSeconds,
-  multiDragPassengerOffsetPx,
-} from "./timelineMultiDragPreview";
+import { isMultiDragPassenger, multiDragPassengerOffsetPx } from "./timelineMultiDragPreview";
+import { useTimelineMultiDragActorWindows } from "./useTimelineMultiDragActorWindows";
 import type { TimelineLanesProps } from "./timelineLaneProps";
 import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
@@ -32,7 +30,6 @@ import { TimelineTrackRow } from "./TimelineTrackRow";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
 import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
-import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
 import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
 
@@ -55,6 +52,7 @@ export function TimelineLanes({
   trackOrder,
   tracks,
   trackStyles,
+  groups,
   laneCounts,
   selectedElementId,
   selectedElementIds,
@@ -102,20 +100,14 @@ export function TimelineLanes({
   // from resolving into a second timeline that renders the same logical rows.
   const lanesIdPrefix = `timeline-lanes${useId().replaceAll(":", "")}`;
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
+  const { expandedGroupIds, expandedLaneOwnerIds, toggleGroupExpanded, toggleLaneOwnerExpanded } =
+    useTimelineGroupDisclosure();
   const automationLanes = useAutomationLanes();
   useAutomationSelectionKeyboard({ lanes: automationLanes });
   const expandClips = usePlayerStore((s) => s.expandClips);
   const setClipExpanded = usePlayerStore((s) => s.setClipExpanded);
   const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
-  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 { logicalRowsByTrack, groupByAnchor } = useTimelineLaneRowIndexes(logicalRows, groups);
   // 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
@@ -131,22 +123,11 @@ export function TimelineLanes({
     trackStudioKeyframeLaneExpand({ expanded: willExpand });
     toggleClipExpanded(key);
   };
-  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,
-          },
-        ]
-      : [];
+  const actorWindows = useTimelineMultiDragActorWindows(
+    multiDragPreview,
+    rowsVirtualized,
+    renderTimeRange,
+  );
   const keyboard = useTimelineKeyboardActor({
     logicalRows,
     focusedTargetId,
@@ -171,6 +152,31 @@ export function TimelineLanes({
         virtualRows.map(({ index: row, rowKey }) => {
           const trackNum = displayTrackOrder[row];
           if (trackNum === undefined) return null;
+          const group = groupByAnchor.get(trackNum);
+          if (group) {
+            const groupLogicalRow = logicalRowsByTrack.get(trackNum)?.[0];
+            if (!groupLogicalRow) return null;
+            return (
+              <TimelineGroupRow
+                key={rowKey}
+                index={row}
+                rowKey={rowKey}
+                group={group}
+                logicalRow={groupLogicalRow}
+                tracks={tracks}
+                top={rowGeometry.getRowTop(row)}
+                height={rowGeometry.getRowHeight(row)}
+                virtualized={rowsVirtualized}
+                contentOrigin={contentOrigin}
+                theme={theme}
+                rovingTargetId={keyboard.rovingTargetId}
+                expandedGroupIds={expandedGroupIds}
+                expandedLaneOwnerIds={expandedLaneOwnerIds}
+                toggleGroupExpanded={toggleGroupExpanded}
+                toggleLaneOwnerExpanded={toggleLaneOwnerExpanded}
+              />
+            );
+          }
           const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
           const trackLogicalRows = logicalRowsByTrack.get(trackNum) ?? [];
           const logicalRow = trackLogicalRows[0];

package/src/player/components/TimelineOverlays.tsx

@@ -12,6 +12,8 @@ import {
 import { ClipContextMenu } from "./ClipContextMenu";
 import { TrackGapContextMenu } from "./TrackGapContextMenu";
 import { TimelineShortcutHint } from "./TimelineShortcutHint";
+import { copyTextToClipboard } from "../../utils/clipboard";
+import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
 
 export interface ClipContextMenuState {
   x: number;
@@ -195,6 +197,38 @@ export function TimelineOverlays({
                 }
               : undefined
           }
+          // Routed to the same focused-ease-segment path a segment click takes,
+          // so the menu advertises the editor that exists rather than growing a
+          // second one. Offered only for a keyframe that names a tween to focus.
+          onEditEase={
+            kfContextMenu.animationId !== undefined && kfContextMenu.tweenPercentage !== undefined
+              ? (elementId, keyframe) => {
+                  if (
+                    keyframe.animationId === undefined ||
+                    keyframe.tweenPercentage === undefined
+                  ) {
+                    return;
+                  }
+                  usePlayerStore.getState().setFocusedEaseSegment({
+                    animationId: keyframe.animationId,
+                    collidingAnimationTargets: keyframe.collidingAnimationTargets,
+                    tweenPercentage: keyframe.tweenPercentage,
+                    elementId,
+                  });
+                  trackStudioSegmentEaseEdit({ action: "open" });
+                }
+              : undefined
+          }
+          onCopyProperties={(elementId, keyframe) => {
+            const entry = usePlayerStore.getState().keyframeCache.get(elementId);
+            // Tolerance match on clip-%, the same basis the cache is keyed on —
+            // an exact float compare misses a keyframe the menu just opened over.
+            const kf = entry?.keyframes.find(
+              (item) => Math.abs(item.percentage - keyframe.percentage) < 0.5,
+            );
+            if (!kf) return false;
+            return copyTextToClipboard(JSON.stringify(kf.properties, null, 2));
+          }}
         />
       )}
 

package/src/player/components/TimelineSoloButton.tsx

@@ -0,0 +1,32 @@
+/**
+ * "Hear only this" — the `⌗` toggle beside a track's mute control. Session
+ * state only (see `audioSoloSlice`): a plain click is exclusive, ⌘/Ctrl-click
+ * toggles membership without disturbing the rest of the set.
+ */
+export function TimelineSoloButton({
+  isSoloed,
+  onToggle,
+}: {
+  isSoloed: boolean;
+  onToggle: (options?: { add?: boolean }) => void;
+}) {
+  return (
+    <button
+      type="button"
+      tabIndex={-1}
+      aria-pressed={isSoloed}
+      aria-label="Hear only this"
+      title="Hear only this"
+      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[13px] font-semibold transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+        isSoloed ? "text-[#F5C542] hover:text-white" : "text-white/35 hover:text-white/75"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        onToggle({ add: event.metaKey || event.ctrlKey });
+      }}
+    >
+      <span aria-hidden="true">⌗</span>
+    </button>
+  );
+}