feat(studio,core): mute groups, and hear-only-this that cannot reach the export

B5: mute and solo, on groups and tracks (track mute already shipped by A2 — nothing to build there). Group mute — persisted as data-hidden on the <hf-audio-group> element itself (never written onto members, per design doc §2.1's state-restoration warning). Studio action reuses B7's generic setAudioGroupAttribute (setQuiet/setLive split) rather than duplicating toggleTimelineTrackHidden's shape — same one-atomic-patch/one-undo-entry contract, already built for exactly this purpose. Render: B4 already drops every member of a data-hidden group (confirmed by a new audioMixer.test.ts case — no production change needed there). Preview: a dedicated muteGain node (groupInput -> [fx] -> muteGain -> output -> master) so a mute toggle never fights scheduleVolumeLane's ramps on the same param — the same hazard B7's volume fader was split out to avoid. Mid-playback toggles sync via a new syncAudioGroupMute pass in init.ts (a group carries no data-start, so it's invisible to the existing visibility-node query). Members of a muted group render the strikethrough label treatment (TimelineTrackPlainHeader's isGroupMuted, sourced from TimelineElement.audioGroupHidden) — display only, no attribute touched. Solo — "Hear only this": a new session-only store slice (audioSoloSlice, soloed: ReadonlySet<string> of clip/group ids, never track numbers, never serialized). Predicate (isAudibleUnderSolo, packages/core/src/audioGroups.ts so both the store and the preview transport share one definition): an element is audible while any solo is active only if it or its own group is soloed. "Siblings, never ancestors" lives in the graph, not the predicate — solo gain is a per-element stage only; group buses are never attenuated by solo, so a soloed member's path through its group stays open by construction. Preview: a dedicated per-element soloGain in webAudioTransport.ts (parallel to the mute mechanics), pushed via window.__hf.setAudioSolo — a direct call, not an attribute write, so it can't ride the visibility-diff path mute uses. media.ts's HTMLMedia fallback folds the same predicate into its per-tick volume computation (the same seam A2 used for data-hidden). Half-lit group indicator (isGroupHalfLitUnderSolo) for "not soloed itself, but a member is". Exclusive-by-default toggle, ⌘/Ctrl-click to add/remove, TimelineSoloButton (⌗) beside mute on both track and group headers. Transport-bar banner ("Hearing only <label> — your export is not affected", Clear button) added in PlayerControls.tsx, reading labels straight off the live preview DOM. Export-safety, the most important property here: toggling/adding/clearing solo never calls setAttribute/removeAttribute on any element and never invokes the project save path (both asserted directly via spies in audioSoloSlice.test.ts) — solo cannot reach an export by construction, not by convention. Also: extracted useHydrateActiveCompPathFromUrl out of App.tsx (a pre-existing, unrelated effect) to stay under the 600-line filesize cap after wiring useAudioSoloBridge in; and fixed a circular dependency the solo-banner wiring introduced (useAudioSoloBridge.ts now imports usePlayerStore from its concrete module instead of the player/ barrel, which re-exports PlayerControls.tsx — the barrel path is what closed the cycle). Gates: bun run build clean; packages/core full suite 2379/2379; packages/ studio full suite 4276/4294 (18 pre-existing todo); packages/engine audioMixer.grouping.test.ts 5/5; oxfmt/oxlint clean on all 23 touched files; fallow clean (0 new circular deps, 0 new filesize/complexity findings). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-04 07:19:52 +00:00 · 2026-08-20 16:39:31 -07:00
parent e1c9b50948
commit 301cb8b51f
23 changed files with 941 additions and 235 deletions
@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef, useMemo, useEffect, useLayoutEffect } from "react";
+import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react";
 import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
 import { usePlayerStore } from "./player";
@@ -38,6 +38,7 @@ import { useToast } from "./hooks/useToast";
 import { useCompositionContentLoader } from "./hooks/useCompositionContentLoader";
 import { useStudioUrlState } from "./hooks/useStudioUrlState";
 import { useEffectiveTimelineDuration } from "./hooks/useEffectiveTimelineDuration";
+import { useAudioSoloBridge } from "./hooks/useAudioSoloBridge";
 import {
  buildStudioContextValue,
  useGlobalFileDrop,
@@ -61,11 +62,8 @@ import { StudioSplash } from "./components/StudioSplash";
 import { useServerConnection } from "./hooks/useServerConnection";
 import { useStudioSessionStart } from "./hooks/useStudioSessionStart";
 import { useTimelineAddAtPlayhead } from "./hooks/useTimelineAddAtPlayhead";
-import {
-  normalizeStudioCompositionPath,
-  readStudioUrlStateFromWindow,
-  resolveMasterCompositionPath,
-} from "./utils/studioUrlState";
+import { readStudioUrlStateFromWindow, resolveMasterCompositionPath } from "./utils/studioUrlState";
+import { useHydrateActiveCompPathFromUrl } from "./hooks/useHydrateActiveCompPathFromUrl";
 const getTimelineSelectionSet = () => usePlayerStore.getState().selectedElementIds;
 // fallow-ignore-next-line complexity
 export function StudioApp() {
@@ -84,6 +82,7 @@ export function StudioApp() {
  const [previewDocumentVersion, refreshPreviewDocumentVersion] = usePreviewDocumentVersion();
  const [blockPreview, setBlockPreview] = useState<BlockPreviewInfo | null>(null);
  const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
+  useAudioSoloBridge(previewIframeRef);
  const activeCompPathRef = useRef(activeCompPath);
  activeCompPathRef.current = activeCompPath;
  const leftSidebarRef = useRef<LeftSidebarHandle>(null);
@@ -127,16 +126,14 @@ export function StudioApp() {
    activeCompPath,
    masterCompPath,
  );
-  useEffect(() => {
-    if (activeCompPathHydrated) return;
-    if (!fileManager.fileTreeLoaded) return;
-    const nextCompPath = normalizeStudioCompositionPath(
-      initialUrlStateRef.current.activeCompPath,
-      fileManager.fileTree,
-    );
-    setActiveCompPath((current) => (current === nextCompPath ? current : nextCompPath));
-    setActiveCompPathHydrated(true);
-  }, [activeCompPathHydrated, fileManager.fileTree, fileManager.fileTreeLoaded]);
+  useHydrateActiveCompPathFromUrl({
+    hydrated: activeCompPathHydrated,
+    fileTreeLoaded: fileManager.fileTreeLoaded,
+    fileTree: fileManager.fileTree,
+    initialUrlStateRef,
+    setActiveCompPath,
+    setHydrated: setActiveCompPathHydrated,
+  });
  const previewPersistence = usePreviewPersistence({
    showToast,
    readOptionalProjectFile: fileManager.readOptionalProjectFile,
@@ -156,6 +156,7 @@ export function PreviewPane({
          disabled={timelineDisabled}
          isFullscreen={isFullscreen}
          onToggleFullscreen={toggleFullscreen}
+          previewIframeRef={iframeRef}
        />
      </div>
    </div>
@@ -0,0 +1,61 @@
+import { useEffect, useMemo } from "react";
+import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
+import { usePlayerStore } from "../player/store/playerStore";
+import { getTimelineElementDisplayLabel } from "../player/lib/timelineElementHelpers";
+
+interface IframeWindow extends Window {
+  __hf?: { setAudioSolo?: (ids: readonly string[]) => void };
+}
+
+/**
+ * Pushes the studio's "Hear only this" set into the preview runtime whenever
+ * it changes. A dedicated push, not a DOM write: solo is session-only and
+ * must never touch an attribute (design doc §2.2 / the export-safety
+ * guarantee), so it can't ride `syncTimedElementVisibility`'s attribute-diff
+ * the way group mute does — see `window.__hf.setAudioSolo`.
+ */
+export function useAudioSoloBridge(previewIframeRef: { current: HTMLIFrameElement | null }): void {
+  const soloed = usePlayerStore((s) => s.soloed);
+  useEffect(() => {
+    const win = previewIframeRef.current?.contentWindow as IframeWindow | null;
+    win?.__hf?.setAudioSolo?.([...soloed]);
+  }, [soloed, previewIframeRef]);
+}
+
+/** One soloed id's display label — reads the live preview DOM directly (same
+ *  approach as `patchLiveGroupAttribute`), since solo ids are never anywhere
+ *  but the document's own element ids. A group carries its label on
+ *  `data-label`; anything else falls back to the same label rule the
+ *  timeline itself uses. */
+function resolveSoloLabel(doc: Document | null | undefined, id: string): string {
+  const el = doc?.getElementById(id);
+  if (!el) return id;
+  if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) {
+    return getTimelineElementDisplayLabel({ id, label: el.getAttribute("data-label") });
+  }
+  return getTimelineElementDisplayLabel({
+    id,
+    label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
+    tag: el.tagName,
+  });
+}
+
+/**
+ * The transport bar's "Hear only this" banner text — `null` while nothing is
+ * soloed. One name when exactly one thing is soloed, `"N tracks"` otherwise
+ * (design doc §2.2's banner rule); "your export is not affected" is fixed
+ * copy the caller owns, this only resolves the variable half.
+ */
+export function useSoloBannerText(previewIframeRef: {
+  current: HTMLIFrameElement | null;
+}): string | null {
+  const soloed = usePlayerStore((s) => s.soloed);
+  return useMemo(() => {
+    if (soloed.size === 0) return null;
+    if (soloed.size === 1) {
+      const doc = previewIframeRef.current?.contentDocument;
+      return resolveSoloLabel(doc, [...soloed][0]);
+    }
+    return `${soloed.size} tracks`;
+  }, [soloed, previewIframeRef]);
+}
@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+import type { MutableRefObject } from "react";
+import { normalizeStudioCompositionPath, type StudioUrlState } from "../utils/studioUrlState";
+
+/**
+ * One-time hydration of `activeCompPath` from the initial URL state, once the
+ * file tree has loaded (a path that isn't in the tree yet can't be
+ * validated). Runs exactly once — `hydrated` flips true whether or not the
+ * URL named a valid path, so a later file-tree change never re-fires it.
+ */
+export function useHydrateActiveCompPathFromUrl({
+  hydrated,
+  fileTreeLoaded,
+  fileTree,
+  initialUrlStateRef,
+  setActiveCompPath,
+  setHydrated,
+}: {
+  hydrated: boolean;
+  fileTreeLoaded: boolean;
+  fileTree: string[];
+  initialUrlStateRef: MutableRefObject<StudioUrlState>;
+  setActiveCompPath: (updater: (current: string | null) => string | null) => void;
+  setHydrated: (value: boolean) => void;
+}): void {
+  useEffect(() => {
+    if (hydrated) return;
+    if (!fileTreeLoaded) return;
+    const nextCompPath = normalizeStudioCompositionPath(
+      initialUrlStateRef.current.activeCompPath,
+      fileTree,
+    );
+    setActiveCompPath((current) => (current === nextCompPath ? current : nextCompPath));
+    setHydrated(true);
+  }, [hydrated, fileTree, fileTreeLoaded, initialUrlStateRef, setActiveCompPath, setHydrated]);
+}
@@ -6,6 +6,7 @@ import { liveTime, usePlayerStore } from "../store/playerStore";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import { useSoloBannerText } from "../../hooks/useAudioSoloBridge";
 import { ShortcutsPanel } from "./ShortcutsPanel";
 import { SpeedMenu } from "./SpeedMenu";
 import { VolumeControl } from "./VolumeControl";
@@ -153,6 +154,34 @@ const FullscreenButton = memo(function FullscreenButton({
  );
 });

+const SoloBanner = memo(function SoloBanner({
+  previewIframeRef,
+}: {
+  previewIframeRef: { current: HTMLIFrameElement | null };
+}) {
+  const bannerText = useSoloBannerText(previewIframeRef);
+  const clearSolo = usePlayerStore.getState().clearSolo;
+  if (bannerText === null) return null;
+  return (
+    <div
+      role="status"
+      className="flex h-7 items-center justify-center gap-2 border-b border-neutral-800 bg-neutral-900/90 px-3 text-[11px] text-neutral-300"
+    >
+      <span>
+        Hearing only <span className="font-medium text-neutral-100">{bannerText}</span> — your
+        export is not affected
+      </span>
+      <button
+        type="button"
+        onClick={() => clearSolo()}
+        className="rounded px-1.5 py-0.5 font-medium text-studio-accent transition-colors hover:text-white"
+      >
+        Clear
+      </button>
+    </div>
+  );
+});
+
 /* ── Main component ──────────────────────────────────────────────── */

 interface PlayerControlsProps {
@@ -161,6 +190,7 @@ interface PlayerControlsProps {
  disabled?: boolean;
  isFullscreen?: boolean;
  onToggleFullscreen?: () => void;
+  previewIframeRef?: { current: HTMLIFrameElement | null };
 }

 export const PlayerControls = memo(function PlayerControls({
@@ -169,6 +199,7 @@ export const PlayerControls = memo(function PlayerControls({
  disabled = false,
  isFullscreen = false,
  onToggleFullscreen,
+  previewIframeRef,
 }: PlayerControlsProps) {
  const isPlaying = usePlayerStore((s) => s.isPlaying);
  const duration = usePlayerStore((s) => s.duration);
@@ -220,73 +251,80 @@ export const PlayerControls = memo(function PlayerControls({
  });

  return (
-    <div
-      className="grid h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-3"
-      aria-disabled={disabled || undefined}
-      style={{
-        paddingBottom: "env(safe-area-inset-bottom)",
-      }}
-    >
-      <Tooltip
-        label={timeDisplayMode === "time" ? "Switch to frame display" : "Switch to time display"}
+    <div>
+      {previewIframeRef && <SoloBanner previewIframeRef={previewIframeRef} />}
+      <div
+        className="grid h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-3"
+        aria-disabled={disabled || undefined}
+        style={{
+          paddingBottom: "env(safe-area-inset-bottom)",
+        }}
      >
-        <button
-          type="button"
-          onClick={() => setTimeDisplayMode(timeDisplayMode === "time" ? "frame" : "time")}
-          disabled={disabled}
-          className="min-w-0 justify-self-start whitespace-nowrap font-mono text-[11px] tabular-nums text-neutral-400 transition-colors hover:text-neutral-200 disabled:pointer-events-none"
+        <Tooltip
+          label={timeDisplayMode === "time" ? "Switch to frame display" : "Switch to time display"}
        >
-          <span ref={timeDisplayRef}>{formatTime(0)}</span>
-          {timeDisplayMode === "time" ? (
-            <>
-              <span className="mx-0.5 text-neutral-700">/</span>
-              <span className="text-neutral-600">{formatTime(duration)}</span>
-            </>
-          ) : null}
-        </button>
-      </Tooltip>
+          <button
+            type="button"
+            onClick={() => setTimeDisplayMode(timeDisplayMode === "time" ? "frame" : "time")}
+            disabled={disabled}
+            className="min-w-0 justify-self-start whitespace-nowrap font-mono text-[11px] tabular-nums text-neutral-400 transition-colors hover:text-neutral-200 disabled:pointer-events-none"
+          >
+            <span ref={timeDisplayRef}>{formatTime(0)}</span>
+            {timeDisplayMode === "time" ? (
+              <>
+                <span className="mx-0.5 text-neutral-700">/</span>
+                <span className="text-neutral-600">{formatTime(duration)}</span>
+              </>
+            ) : null}
+          </button>
+        </Tooltip>

-      <Tooltip label={isPlaying ? "Pause" : "Play"}>
-        <button
-          type="button"
-          aria-label={isPlaying ? "Pause" : "Play"}
-          onClick={() => {
-            trackStudioEvent("playback", { action: isPlaying ? "pause" : "play" });
-            onTogglePlay();
-          }}
-          disabled={controlsDisabled}
-          className="flex h-8 w-8 items-center justify-center justify-self-center rounded-md text-neutral-100 transition-colors hover:text-white disabled:pointer-events-none disabled:opacity-30"
-        >
-          <PlayPauseMorphIcon playing={isPlaying} />
-        </button>
-      </Tooltip>
+        <Tooltip label={isPlaying ? "Pause" : "Play"}>
+          <button
+            type="button"
+            aria-label={isPlaying ? "Pause" : "Play"}
+            onClick={() => {
+              trackStudioEvent("playback", { action: isPlaying ? "pause" : "play" });
+              onTogglePlay();
+            }}
+            disabled={controlsDisabled}
+            className="flex h-8 w-8 items-center justify-center justify-self-center rounded-md text-neutral-100 transition-colors hover:text-white disabled:pointer-events-none disabled:opacity-30"
+          >
+            <PlayPauseMorphIcon playing={isPlaying} />
+          </button>
+        </Tooltip>

-      <div className="flex min-w-0 items-center justify-self-end">
-        <VolumeControl
-          audioMuted={audioMuted}
-          audioVolume={audioVolume}
-          disabled={controlsDisabled}
-          setAudioMuted={setAudioMuted}
-          setAudioVolume={setAudioVolume}
-        />
-        <SpeedMenu
-          playbackRate={playbackRate}
-          setPlaybackRate={setPlaybackRate}
-          disabled={disabled}
-        />
-        <LoopButton loopEnabled={loopEnabled} disabled={disabled} setLoopEnabled={setLoopEnabled} />
-        {onToggleFullscreen && (
-          <FullscreenButton isFullscreen={isFullscreen} onToggleFullscreen={onToggleFullscreen} />
-        )}
-        <ShortcutsPanel
-          disabled={disabled}
-          duration={duration}
-          inPoint={inPoint}
-          outPoint={outPoint}
-          setInPoint={setInPoint}
-          setOutPoint={setOutPoint}
-          onSeek={onSeek}
-        />
+        <div className="flex min-w-0 items-center justify-self-end">
+          <VolumeControl
+            audioMuted={audioMuted}
+            audioVolume={audioVolume}
+            disabled={controlsDisabled}
+            setAudioMuted={setAudioMuted}
+            setAudioVolume={setAudioVolume}
+          />
+          <SpeedMenu
+            playbackRate={playbackRate}
+            setPlaybackRate={setPlaybackRate}
+            disabled={disabled}
+          />
+          <LoopButton
+            loopEnabled={loopEnabled}
+            disabled={disabled}
+            setLoopEnabled={setLoopEnabled}
+          />
+          {onToggleFullscreen && (
+            <FullscreenButton isFullscreen={isFullscreen} onToggleFullscreen={onToggleFullscreen} />
+          )}
+          <ShortcutsPanel
+            disabled={disabled}
+            duration={duration}
+            inPoint={inPoint}
+            outPoint={outPoint}
+            setInPoint={setInPoint}
+            setOutPoint={setOutPoint}
+            onSeek={onSeek}
+          />
+        </div>
      </div>
    </div>
  );
@@ -1,3 +1,4 @@
+import { SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
 import { TRACK_H } from "./timelineLayout";
 import type { TimelineTheme } from "./timelineTheme";

@@ -11,14 +12,23 @@ interface TimelineGroupHeaderProps {
  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;
  columnWidth: number;
  theme: TimelineTheme;
 }

 /**
- * A group's own row header: caret (member disclosure) + `▤` + label + `∿ n`
- * (lane disclosure). Mute/solo (B5) and the FX entry point (C1) land here as
- * siblings once those steps exist — nothing to reserve for them yet.
+ * A group's own row header: caret (member disclosure) + `▤` + label + count +
+ * mute + solo + `∿ n` (lane disclosure). The FX entry point (C1) lands here
+ * as a sibling once that step exists.
 */
 export function TimelineGroupHeader({
  label,
@@ -28,6 +38,11 @@ export function TimelineGroupHeader({
  laneCount,
  isLaneOpen,
  onToggleLanes,
+  hidden,
+  onToggleHidden,
+  isSoloed,
+  isHalfLitSolo,
+  onToggleSolo,
  columnWidth,
  theme,
 }: TimelineGroupHeaderProps) {
@@ -76,6 +91,47 @@ export function TimelineGroupHeader({
      >
        {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>
      <button
        type="button"
        tabIndex={-1}
@@ -1,4 +1,6 @@
 import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import { isGroupHalfLitUnderSolo } from "../store/audioSoloSlice";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
@@ -54,6 +56,9 @@ export function TimelineGroupRow({
  });
  const isLaneOpen = expandedLaneOwnerIds.has(group.id);
  const { onSetAudioGroupAttributeLive, onSetAudioGroupAttributeQuiet } = useTimelineEditContext();
+  const soloed = usePlayerStore((s) => s.soloed);
+  const toggleSolo = usePlayerStore((s) => s.toggleSolo);
+  const memberIds = memberElements.map((el) => el.key ?? el.id);
  return (
    <TimelineTrackRow
      index={index}
@@ -77,6 +82,18 @@ export function TimelineGroupRow({
        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)}
        columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
        theme={theme}
      />
@@ -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>
+  );
+}
@@ -1,15 +1,12 @@
-import { Eye, EyeSlash, SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { isCanaryEnabled } from "../../telemetry/canary";
-import { Music } from "../../icons/SystemIcons";
-import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { VisibilityButton, PlainTrackHeader } from "./TimelineTrackPlainHeader";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { groupAutomationLanes } from "./automationLaneData";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { clipTimingStart } from "../../hooks/gsapShared";
 import { LayerDisclosureRow } from "./LayerDisclosureRow";
-import { TrackClipCount } from "./TrackClipCount";
 import { LABEL_COL_W, LANE_H, getTimelineLaneTop } from "./timelineLayout";
 import type { TimelineTheme } from "./timelineTheme";
 import {
@@ -62,109 +59,6 @@ interface TimelineTrackHeaderProps {
  onSeek?: (time: number) => void;
 }

-// Audio tracks say "Mute", not "Hide" — the eye IS mute for sound-only rows.
-// Gated: the relabel ships behind the canary, unlike the preview fix.
-function visibilityButtonLabel(showAsMute: boolean, hidden: boolean, suffix: string): string {
-  if (showAsMute) return hidden ? "Muted" : "Mute";
-  return hidden ? `Show track${suffix}` : `Hide track${suffix}`;
-}
-
-function visibilityButtonIcon(showAsMute: boolean, hidden: boolean) {
-  const Icon = showAsMute ? (hidden ? SpeakerSlash : SpeakerHigh) : hidden ? EyeSlash : Eye;
-  return <Icon size={14} weight="bold" aria-hidden="true" />;
-}
-
-function VisibilityButton({
-  hidden,
-  trackNumber,
-  trackDisplayNumber,
-  visible,
-  isAudioTrack,
-  onToggle,
-}: {
-  hidden: boolean;
-  trackNumber: number;
-  trackDisplayNumber: number | null;
-  visible: boolean;
-  isAudioTrack?: boolean;
-  onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
-}) {
-  if (!visible) return <span aria-hidden="true" className="h-6 w-6 shrink-0" />;
-  // Display number in the text, real key in the callback. The two must not be
-  // conflated in either direction.
-  const suffix = trackDisplaySuffix(trackDisplayNumber);
-  const showAsMute = Boolean(isAudioTrack) && isCanaryEnabled("audio-track-mute");
-  const label = visibilityButtonLabel(showAsMute, hidden, suffix);
-  return (
-    <button
-      type="button"
-      aria-label={label}
-      title={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/35 hover:text-white/75"
-      }`}
-      onPointerDown={(event) => event.stopPropagation()}
-      onClick={(event) => {
-        event.stopPropagation();
-        void onToggle?.(trackNumber, !hidden);
-      }}
-    >
-      {visibilityButtonIcon(showAsMute, hidden)}
-    </button>
-  );
-}
-
-// The header a track gets when it has no keyframe clip to disclose: label, clip
-// count, eye. Not deprecated — it is the live path for every track without lanes.
-function PlainTrackHeader({
-  trackNumber,
-  trackDisplayNumber,
-  trackLabel,
-  clipCount,
-  showTrackLabel,
-  isTrackHidden,
-  isAudioTrack,
-  onToggleTrackHidden,
-}: Pick<
-  TimelineTrackHeaderProps,
-  | "trackNumber"
-  | "trackDisplayNumber"
-  | "trackLabel"
-  | "clipCount"
-  | "isTrackHidden"
-  | "isAudioTrack"
-  | "onToggleTrackHidden"
-> & { showTrackLabel: boolean }) {
-  return (
-    <>
-      {isAudioTrack && (
-        <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
-      )}
-      {showTrackLabel && (
-        <span
-          className={`min-w-0 flex-1 truncate text-[11px] ${
-            isAudioTrack && isTrackHidden && isCanaryEnabled("audio-track-mute")
-              ? "line-through"
-              : ""
-          }`}
-          title={trackLabel}
-        >
-          {trackLabel}
-        </span>
-      )}
-      {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
-      <VisibilityButton
-        hidden={isTrackHidden}
-        trackNumber={trackNumber}
-        trackDisplayNumber={trackDisplayNumber}
-        visible
-        isAudioTrack={isAudioTrack}
-        onToggle={onToggleTrackHidden}
-      />
-    </>
-  );
-}
-
 // Figma layout: prev-keyframe ‹, the add/remove toggle (children), next ›.
 function PropertyGroupNavigation({
  navigation,
@@ -478,6 +372,13 @@ export function TimelineTrackHeader({
  // left an audio clip's envelopes unreachable, since the track could not expand.
  const disclosable = lanes.length > 0 || automationRows.length > 0;
  const isKeyframeLayer = !!keyframeClip && disclosable;
+  // Solo is per-clip/per-group, never per track (design doc §2.2) — this header
+  // acts on the track's first clip as a pragmatic stand-in for "this track",
+  // the same simplification the mute button doesn't need to make (it patches
+  // every clip on the track at once).
+  const soloTargetId = trackElements[0] ? (trackElements[0].key ?? trackElements[0].id) : null;
+  const soloed = usePlayerStore((s) => s.soloed);
+  const toggleSolo = usePlayerStore((s) => s.toggleSolo);

  return (
    <div
@@ -505,6 +406,9 @@ export function TimelineTrackHeader({
          showTrackLabel={showTrackLabel}
          isTrackHidden={isTrackHidden}
          isAudioTrack={isAudioTrack}
+          isGroupMuted={trackElements.some((el) => el.audioGroupHidden)}
+          isSoloed={soloTargetId !== null && soloed.has(soloTargetId)}
+          onToggleSolo={soloTargetId ? (options) => toggleSolo(soloTargetId, options) : undefined}
          onToggleTrackHidden={onToggleTrackHidden}
        />
      ) : (
@@ -0,0 +1,119 @@
+import { Eye, EyeSlash, SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
+import { isCanaryEnabled } from "../../telemetry/canary";
+import { Music } from "../../icons/SystemIcons";
+import { TimelineSoloButton } from "./TimelineSoloButton";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { TrackClipCount } from "./TrackClipCount";
+import { trackDisplaySuffix } from "./timelineTrackDisplay";
+
+// Audio tracks say "Mute", not "Hide" — the eye IS mute for sound-only rows.
+// Gated: the relabel ships behind the canary, unlike the preview fix.
+function visibilityButtonLabel(showAsMute: boolean, hidden: boolean, suffix: string): string {
+  if (showAsMute) return hidden ? "Muted" : "Mute";
+  return hidden ? `Show track${suffix}` : `Hide track${suffix}`;
+}
+
+function visibilityButtonIcon(showAsMute: boolean, hidden: boolean) {
+  const Icon = showAsMute ? (hidden ? SpeakerSlash : SpeakerHigh) : hidden ? EyeSlash : Eye;
+  return <Icon size={14} weight="bold" aria-hidden="true" />;
+}
+
+export function VisibilityButton({
+  hidden,
+  trackNumber,
+  trackDisplayNumber,
+  visible,
+  isAudioTrack,
+  onToggle,
+}: {
+  hidden: boolean;
+  trackNumber: number;
+  trackDisplayNumber: number | null;
+  visible: boolean;
+  isAudioTrack?: boolean;
+  onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
+}) {
+  if (!visible) return <span aria-hidden="true" className="h-6 w-6 shrink-0" />;
+  // Display number in the text, real key in the callback. The two must not be
+  // conflated in either direction.
+  const suffix = trackDisplaySuffix(trackDisplayNumber);
+  const showAsMute = Boolean(isAudioTrack) && isCanaryEnabled("audio-track-mute");
+  const label = visibilityButtonLabel(showAsMute, hidden, suffix);
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={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/35 hover:text-white/75"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        void onToggle?.(trackNumber, !hidden);
+      }}
+    >
+      {visibilityButtonIcon(showAsMute, hidden)}
+    </button>
+  );
+}
+
+// The header a track gets when it has no keyframe clip to disclose: label, clip
+// count, eye. Not deprecated — it is the live path for every track without lanes.
+export function PlainTrackHeader({
+  trackNumber,
+  trackDisplayNumber,
+  trackLabel,
+  clipCount,
+  showTrackLabel,
+  isTrackHidden,
+  isAudioTrack,
+  isGroupMuted,
+  isSoloed,
+  onToggleSolo,
+  onToggleTrackHidden,
+}: {
+  trackNumber: number;
+  trackDisplayNumber: number | null;
+  trackLabel: string;
+  clipCount: number;
+  isTrackHidden: boolean;
+  isAudioTrack: boolean;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  showTrackLabel: boolean;
+  isGroupMuted: boolean;
+  isSoloed: boolean;
+  onToggleSolo?: (options?: { add?: boolean }) => void;
+}) {
+  return (
+    <>
+      {isAudioTrack && (
+        <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
+      )}
+      {showTrackLabel && (
+        <span
+          className={`min-w-0 flex-1 truncate text-[11px] ${
+            isAudioTrack && (isTrackHidden || isGroupMuted) && isCanaryEnabled("audio-track-mute")
+              ? "line-through"
+              : ""
+          }`}
+          title={isGroupMuted && !isTrackHidden ? `${trackLabel} (group muted)` : trackLabel}
+        >
+          {trackLabel}
+        </span>
+      )}
+      {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
+      <VisibilityButton
+        hidden={isTrackHidden}
+        trackNumber={trackNumber}
+        trackDisplayNumber={trackDisplayNumber}
+        visible
+        isAudioTrack={isAudioTrack}
+        onToggle={onToggleTrackHidden}
+      />
+      {isAudioTrack && isCanaryEnabled("audio-track-mute") && onToggleSolo && (
+        <TimelineSoloButton isSoloed={isSoloed} onToggle={onToggleSolo} />
+      )}
+    </>
+  );
+}
@@ -18,6 +18,8 @@ export interface TimelineTrackGroupInfo {
  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;
 }

 interface GroupMembership {
@@ -25,14 +27,16 @@ interface GroupMembership {
  memberTracksByGroup: Map<string, number[]>;
  labelByGroup: Map<string, string>;
  volumeByGroup: Map<string, number>;
+  hiddenByGroup: Map<string, boolean>;
 }

-/** Which track belongs to which group, and each group's label/volume — one pass over raw tracks. */
+/** Which track belongs to which group, and each group's label/volume/hidden — 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>();
  for (const [trackNum, elements] of rawTracks) {
    const owner = elements.find((el) => el.audioGroup);
    if (!owner?.audioGroup) continue;
@@ -40,12 +44,13 @@ function resolveGroupMembership(rawTracks: [number, TimelineElement[]][]): Group
    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);
    }
    const members = memberTracksByGroup.get(owner.audioGroup) ?? [];
    members.push(trackNum);
    memberTracksByGroup.set(owner.audioGroup, members);
  }
-  return { trackToGroupId, memberTracksByGroup, labelByGroup, volumeByGroup };
+  return { trackToGroupId, memberTracksByGroup, labelByGroup, volumeByGroup, hiddenByGroup };
 }

 /** One group's resolved row info, built once the first time its id is seen. */
@@ -63,6 +68,7 @@ function buildGroupInfo(
    anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
    memberTracks,
    volume: membership.volumeByGroup.get(groupId) ?? 1,
+    hidden: membership.hiddenByGroup.get(groupId) ?? false,
  };
 }

@@ -70,24 +70,27 @@ function resolveClipTag(clip: ClipManifestClip): string {

 // One `<hf-audio-group>` scan per document, not per clip — resolveAudioGroups
 // walks the whole tree, and a parse touches every clip in it.
-const groupInfoCache = new WeakMap<Document, Map<string, { label: string; volume: number }>>();
+const groupInfoCache = new WeakMap<
+  Document,
+  Map<string, { label: string; volume: number; hidden: boolean }>
+>();

 function groupInfoFor(
  doc: Document | null | undefined,
  groupId: string,
-): { label: string; volume: number } {
-  if (!doc) return { label: groupId, volume: 1 };
+): { label: string; volume: number; hidden: boolean } {
+  if (!doc) return { label: groupId, volume: 1, hidden: false };
  let info = groupInfoCache.get(doc);
  if (!info) {
    info = new Map(
      resolveAudioGroups(doc).map((group) => [
        group.id,
-        { label: group.label, volume: group.volume },
+        { label: group.label, volume: group.volume, hidden: group.hidden },
      ]),
    );
    groupInfoCache.set(doc, info);
  }
-  return info.get(groupId) ?? { label: groupId, volume: 1 };
+  return info.get(groupId) ?? { label: groupId, volume: 1, hidden: false };
 }

 // fallow-ignore-next-line complexity
@@ -167,6 +170,7 @@ export function createTimelineElementFromManifestClip(params: {
      const info = groupInfoFor(doc ?? hostEl.ownerDocument, audioGroup);
      entry.audioGroupLabel = info.label;
      entry.audioGroupVolume = info.volume;
+      entry.audioGroupHidden = info.hidden;
    }
    const fxChain = hostEl.getAttribute("data-fx-chain");
    if (fxChain) entry.fxChain = fxChain;
@@ -392,6 +396,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
      const domGroupInfo = groupInfoFor(doc, domAudioGroup);
      entry.audioGroupLabel = domGroupInfo.label;
      entry.audioGroupVolume = domGroupInfo.volume;
+      entry.audioGroupHidden = domGroupInfo.hidden;
    }

    // Sub-compositions
@@ -0,0 +1,113 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "./playerStore";
+import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "./audioSoloSlice";
+import * as studioFileHistory from "../../utils/studioFileHistory";
+
+describe("audioSoloSlice", () => {
+  it("is exclusive by default, and clicking the only soloed element again clears it", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a"]));
+    usePlayerStore.getState().toggleSolo("b");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
+    usePlayerStore.getState().toggleSolo("b");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set());
+  });
+
+  it("⌘/Ctrl-click adds and removes membership without disturbing the rest", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a", "b"]));
+    usePlayerStore.getState().toggleSolo("a", { add: true });
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
+  });
+
+  it("clearSolo empties the set", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().clearSolo();
+    expect(usePlayerStore.getState().soloed).toEqual(new Set());
+  });
+});
+
+describe("export-safety: solo never touches an attribute or the save path", () => {
+  it("toggling, ⌘-adding, and clearing solo never calls setAttribute/removeAttribute on any element", () => {
+    usePlayerStore.getState().clearSolo();
+    const setAttributeSpy = vi.spyOn(Element.prototype, "setAttribute");
+    const removeAttributeSpy = vi.spyOn(Element.prototype, "removeAttribute");
+
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    usePlayerStore.getState().toggleSolo("a", { add: true });
+    usePlayerStore.getState().clearSolo();
+
+    expect(setAttributeSpy).not.toHaveBeenCalled();
+    expect(removeAttributeSpy).not.toHaveBeenCalled();
+    setAttributeSpy.mockRestore();
+    removeAttributeSpy.mockRestore();
+  });
+
+  it("toggling, ⌘-adding, and clearing solo never invokes the project save path (setElementsHidden's own write function)", () => {
+    usePlayerStore.getState().clearSolo();
+    const saveSpy = vi.spyOn(studioFileHistory, "saveProjectFilesWithHistory");
+
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    usePlayerStore.getState().clearSolo();
+
+    expect(saveSpy).not.toHaveBeenCalled();
+    saveSpy.mockRestore();
+  });
+});
+
+describe("isAudibleUnderSolo — the three-bullet rule", () => {
+  it("everything is audible when no solo is active", () => {
+    expect(isAudibleUnderSolo(new Set(), "clip-a")).toBe(true);
+    expect(isAudibleUnderSolo(new Set(), "clip-a", "group-1")).toBe(true);
+  });
+
+  it("a soloed element is audible", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-a")).toBe(true);
+  });
+
+  it("a sibling of a soloed element is silent", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b")).toBe(false);
+  });
+
+  it("a member of a soloed group is audible (group solo = members solo)", () => {
+    expect(isAudibleUnderSolo(new Set(["group-1"]), "clip-a", "group-1")).toBe(true);
+  });
+
+  it("a member of an UNsoloed group, while a sibling group is soloed, is silent", () => {
+    expect(isAudibleUnderSolo(new Set(["group-2"]), "clip-a", "group-1")).toBe(false);
+  });
+
+  it("soloing one member of a group does not un-attenuate its siblings in the same group", () => {
+    // clip-a is soloed directly; clip-b shares its group but is not itself
+    // soloed and the group itself is not soloed — clip-b stays silent.
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b", "group-1")).toBe(false);
+  });
+
+  it("the group itself, monitored as a bus, is audible only when it or a member is soloed", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "group-1", null)).toBe(false);
+    expect(isAudibleUnderSolo(new Set(["group-1"]), "group-1", null)).toBe(true);
+  });
+});
+
+describe("isGroupHalfLitUnderSolo", () => {
+  it("is false when no solo is active", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(), "group-1", ["a", "b"])).toBe(false);
+  });
+
+  it("is false when the group itself is soloed (fully lit, not half)", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["group-1"]), "group-1", ["a", "b"])).toBe(false);
+  });
+
+  it("is true when a member is soloed but the group is not", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["a"]), "group-1", ["a", "b"])).toBe(true);
+  });
+
+  it("is false when an unrelated element is soloed", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["other"]), "group-1", ["a", "b"])).toBe(false);
+  });
+});
@@ -0,0 +1,43 @@
+/**
+ * "Hear only this" — session-only monitoring override, never persisted.
+ *
+ * Holds clip ids and group ids (never track numbers, per the design doc: solo
+ * is a per-element/per-group concept, not a row-position one). Exclusive by
+ * default (a plain toggle replaces the set); ⌘/Ctrl-click adds/removes one
+ * member without disturbing the rest. Never written to any attribute or
+ * document — the export-safety guarantee this slice exists to hold.
+ */
+import type { StoreApi } from "zustand";
+import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "@hyperframes/core/audio-groups";
+
+export { isAudibleUnderSolo, isGroupHalfLitUnderSolo };
+
+export interface AudioSoloSlice {
+  soloed: ReadonlySet<string>;
+  toggleSolo: (id: string, options?: { add?: boolean }) => void;
+  clearSolo: () => void;
+}
+
+export function createAudioSoloSlice(
+  set: StoreApi<AudioSoloSlice>["setState"],
+  get: StoreApi<AudioSoloSlice>["getState"],
+): AudioSoloSlice {
+  return {
+    soloed: new Set(),
+    toggleSolo: (id, options) => {
+      const current = get().soloed;
+      if (options?.add) {
+        const next = new Set(current);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        set({ soloed: next });
+        return;
+      }
+      // Exclusive click: soloing the only-soloed element again clears it;
+      // otherwise it replaces the set.
+      const isOnlyMember = current.size === 1 && current.has(id);
+      set({ soloed: isOnlyMember ? new Set() : new Set([id]) });
+    },
+    clearSolo: () => set({ soloed: new Set() }),
+  };
+}
@@ -16,6 +16,7 @@ import {
 } from "./automationSelectionSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
+import { createAudioSoloSlice, type AudioSoloSlice } from "./audioSoloSlice";

 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
@@ -47,7 +48,8 @@ function resolveElementSelection(
  };
 }

-interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice {
+interface PlayerState
+  extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice, AudioSoloSlice {
  isPlaying: boolean;
  currentTime: number;
  duration: number;
@@ -329,6 +331,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
  ...createThumbnailSlice(set),

  ...createAutomationSelectionSlice(set),
+  ...createAudioSoloSlice(set, get),

  activeKeyframePct: null,
  setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
@@ -73,6 +73,8 @@ export interface TimelineElement {
  audioGroupLabel?: string;
  /** The owning group's `data-volume` (defaults to 1) — resolved once per parse. */
  audioGroupVolume?: number;
+  /** The owning group's `data-hidden` (defaults to false) — resolved once per parse. */
+  audioGroupHidden?: boolean;
  /**
   * Set by useExpandedTimelineElements on an inline-expanded sub-composition
   * child: the absolute master-timeline start of the sub-comp host the child