@hyperframes/studio 0.8.6 → 0.8.8

package/src/hooks/timelineTrackVisibility.test.ts

@@ -2,7 +2,11 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore, type TimelineElement } from "../player";
-import { toggleTimelineElementHidden, toggleTimelineTrackHidden } from "./timelineTrackVisibility";
+import {
+  createAudioGroupAndAssignMembers,
+  toggleTimelineElementHidden,
+  toggleTimelineTrackHidden,
+} from "./timelineTrackVisibility";
 
 afterEach(() => {
   document.body.innerHTML = "";
@@ -194,6 +198,118 @@ describe("toggleTimelineTrackHidden", () => {
 
     expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Show track 2");
   });
+
+  it("labels an audio-only track Mute/Unmute instead of Hide/Show", async () => {
+    const files = new Map([
+      ["index.html", `<div id="voiceover" data-start="0" data-duration="2"></div>`],
+    ]);
+    stubProjectFiles(files);
+
+    const recordEdit = vi.fn();
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [element({ id: "voiceover", domId: "voiceover", track: 0, tag: "audio" })],
+      track: 0,
+      hidden: true,
+      previewIframe: null,
+      writeProjectFile: async () => {},
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Mute track 1");
+  });
+
+  // The header derives its row from the GROUP-AWARE order (a synthetic anchor
+  // row, members pulled contiguous); this function's own fallback derives it
+  // from ascending element-bearing keys. Once a group exists those disagree, so
+  // the same click announced "Mute track 2" and recorded "Mute track 1". The
+  // clicked control passes the row it showed, and that is what gets recorded.
+  it("records the display row the clicked control announced, not its own derivation", async () => {
+    const files = new Map([
+      ["index.html", `<div id="voiceover" data-start="0" data-duration="2"></div>`],
+    ]);
+    stubProjectFiles(files);
+
+    const recordEdit = vi.fn();
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [element({ id: "voiceover", domId: "voiceover", track: 0, tag: "audio" })],
+      track: 0,
+      hidden: true,
+      // Row 2 in the header: the group's anchor row sits above this member.
+      displayNumber: 2,
+      previewIframe: null,
+      writeProjectFile: async () => {},
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Mute track 2");
+  });
+
+  it("labels unmuting an audio-only track back on", async () => {
+    const files = new Map([
+      ["index.html", `<div id="voiceover" data-start="0" data-duration="2" data-hidden=""></div>`],
+    ]);
+    stubProjectFiles(files);
+
+    const recordEdit = vi.fn();
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [
+        element({ id: "voiceover", domId: "voiceover", track: 0, tag: "audio", hidden: true }),
+      ],
+      track: 0,
+      hidden: false,
+      previewIframe: null,
+      writeProjectFile: async () => {},
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Unmute track 1");
+  });
+
+  it("keeps Hide/Show wording for a mixed (audio + visual) track", async () => {
+    const files = new Map([
+      [
+        "index.html",
+        `<div id="voiceover" data-start="0" data-duration="2"></div>
+<div id="caption" data-start="0" data-duration="2"></div>`,
+      ],
+    ]);
+    stubProjectFiles(files);
+
+    const recordEdit = vi.fn();
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [
+        element({ id: "voiceover", domId: "voiceover", track: 0, tag: "audio" }),
+        element({ id: "caption", domId: "caption", track: 0, tag: "div" }),
+      ],
+      track: 0,
+      hidden: true,
+      previewIframe: null,
+      writeProjectFile: async () => {},
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide track 1");
+  });
 });
 
 describe("toggleTimelineElementHidden", () => {
@@ -314,3 +430,139 @@ describe("toggleTimelineElementHidden", () => {
     expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide 2 elements");
   });
 });
+
+describe("createAudioGroupAndAssignMembers", () => {
+  it("writes data-audio-group on every member in ONE atomic edit and updates the player store", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    if (iframe.contentDocument) {
+      iframe.contentDocument.body.innerHTML = `
+        <audio id="narration"></audio>
+        <audio id="interview-guest"></audio>
+      `;
+    }
+
+    const files = new Map([
+      [
+        "index.html",
+        `<audio id="narration" data-start="0" data-duration="5"></audio>
+<audio id="interview-guest" data-start="10" data-duration="5"></audio>
+<audio id="sfx-boom" data-start="0" data-duration="1"></audio>`,
+      ],
+    ]);
+    stubProjectFiles(files);
+
+    const narration = element({
+      id: "narration",
+      key: "index.html:#narration",
+      domId: "narration",
+      track: 0,
+    });
+    const guest = element({
+      id: "interview-guest",
+      key: "index.html:#interview-guest",
+      domId: "interview-guest",
+      track: 1,
+    });
+    usePlayerStore.getState().setElements([narration, guest]);
+
+    const writes = new Map<string, string>();
+    const recordEdit = vi.fn();
+
+    const changedPaths = await createAudioGroupAndAssignMembers({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      elements: [narration, guest],
+      groupId: "voiceover",
+      previewIframe: iframe,
+      writeProjectFile: async (path, content) => {
+        writes.set(path, content);
+      },
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(changedPaths).toEqual(["index.html"]);
+    expect(
+      iframe.contentDocument?.getElementById("narration")?.getAttribute("data-audio-group"),
+    ).toBe("voiceover");
+    expect(
+      iframe.contentDocument?.getElementById("interview-guest")?.getAttribute("data-audio-group"),
+    ).toBe("voiceover");
+    // One write carrying BOTH members — per-element writes would clobber each
+    // other (each starts from the original file content).
+    expect(writes.get("index.html")).toContain(
+      'id="narration" data-start="0" data-duration="5" data-audio-group="voiceover"',
+    );
+    expect(writes.get("index.html")).toContain(
+      'id="interview-guest" data-start="10" data-duration="5" data-audio-group="voiceover"',
+    );
+    expect(writes.get("index.html")).toContain(
+      'id="sfx-boom" data-start="0" data-duration="1"></audio>',
+    );
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Group 2 voice clips");
+    expect(
+      usePlayerStore.getState().elements.find((el) => el.key === "index.html:#narration")
+        ?.audioGroup,
+    ).toBe("voiceover");
+    expect(
+      usePlayerStore.getState().elements.find((el) => el.key === "index.html:#interview-guest")
+        ?.audioGroup,
+    ).toBe("voiceover");
+  });
+
+  it("does nothing for fewer than two elements — grouping is a plural concept", async () => {
+    const recordEdit = vi.fn();
+    const changedPaths = await createAudioGroupAndAssignMembers({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      elements: [element({ id: "narration", domId: "narration" })],
+      groupId: "voiceover",
+      previewIframe: null,
+      writeProjectFile: async () => {},
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+    expect(changedPaths).toEqual([]);
+    expect(recordEdit).not.toHaveBeenCalled();
+  });
+
+  it("reverts the optimistic live patch when the save fails", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    if (iframe.contentDocument) {
+      iframe.contentDocument.body.innerHTML = `
+        <audio id="narration"></audio>
+        <audio id="interview-guest"></audio>
+      `;
+    }
+    // No stubbed fetch: readFileContent's request will fail, forcing the
+    // catch path.
+    const narration = element({ id: "narration", domId: "narration" });
+    const guest = element({ id: "interview-guest", domId: "interview-guest" });
+
+    await expect(
+      createAudioGroupAndAssignMembers({
+        projectId: "project-1",
+        activeCompPath: "index.html",
+        elements: [narration, guest],
+        groupId: "voiceover",
+        previewIframe: iframe,
+        writeProjectFile: async () => {},
+        recordEdit: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        pendingTimelineEditPathRef: { current: new Set() },
+      }),
+    ).rejects.toThrow();
+
+    expect(
+      iframe.contentDocument?.getElementById("narration")?.hasAttribute("data-audio-group"),
+    ).toBe(false);
+    expect(
+      iframe.contentDocument?.getElementById("interview-guest")?.hasAttribute("data-audio-group"),
+    ).toBe(false);
+  });
+});

package/src/hooks/timelineTrackVisibility.ts

@@ -7,6 +7,8 @@ import {
   trackDisplaySuffix,
 } from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { isAudioTimelineElement } from "../utils/timelineInspector";
+import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
 import {
   applyPatchByTarget,
@@ -16,7 +18,7 @@ import {
   type RecordEditInput,
 } from "./timelineEditingHelpers";
 
-interface MutableRef<T> {
+export interface MutableRef<T> {
   current: T;
 }
 
@@ -30,6 +32,13 @@ interface ToggleTimelineTrackHiddenInput {
   timelineElements: readonly TimelineElement[];
   track: number;
   hidden: boolean;
+  /**
+   * The display row the clicked control announced, when the caller has one.
+   * Absent (a keyboard path or a programmatic call), the row is derived here
+   * from ascending element-bearing keys — correct whenever no group has
+   * reordered the header.
+   */
+  displayNumber?: number | null;
   previewIframe: HTMLIFrameElement | null;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
@@ -66,7 +75,7 @@ interface UseTimelineTrackVisibilityEditingInput extends Omit<
   forceReloadSdkSession?: () => void;
 }
 
-interface UseTimelineElementVisibilityEditingInput extends Omit<
+export interface UseTimelineElementVisibilityEditingInput extends Omit<
   ToggleTimelineElementHiddenInput,
   "projectId" | "elementKey" | "hidden" | "previewIframe" | "timelineElements"
 > {
@@ -207,6 +216,7 @@ export async function toggleTimelineTrackHidden({
   timelineElements,
   track,
   hidden,
+  displayNumber,
   previewIframe,
   writeProjectFile,
   recordEdit,
@@ -214,16 +224,28 @@ export async function toggleTimelineTrackHidden({
   pendingTimelineEditPathRef,
 }: ToggleTimelineTrackHiddenInput): Promise<string[]> {
   // `track` is the fractional sort key the callback needs; the history entry is
-  // read by a human, so it gets the display row instead.
+  // read by a human, so it gets the display row instead — the one the clicked
+  // control announced, when the caller passed it. Deriving it again here would
+  // use ascending element-bearing keys, which stop matching the header as soon
+  // as an audio group reorders the rows and inserts an anchor.
   const suffix = trackDisplaySuffix(
-    trackDisplayNumber(timelineTrackOrder(timelineElements), track),
+    displayNumber ?? trackDisplayNumber(timelineTrackOrder(timelineElements), track),
   );
+  const trackElements = timelineElements.filter((element) => element.track === track);
+  const isAudioOnlyTrack = trackElements.length > 0 && trackElements.every(isAudioTimelineElement);
+  const label = isAudioOnlyTrack
+    ? hidden
+      ? `Mute track${suffix}`
+      : `Unmute track${suffix}`
+    : hidden
+      ? `Hide track${suffix}`
+      : `Show track${suffix}`;
   return setElementsHidden({
     projectId,
     activeCompPath,
-    elements: timelineElements.filter((element) => element.track === track),
+    elements: trackElements,
     hidden,
-    label: hidden ? `Hide track${suffix}` : `Show track${suffix}`,
+    label,
     previewIframe,
     writeProjectFile,
     recordEdit,
@@ -267,6 +289,114 @@ export async function toggleTimelineElementHidden({
   });
 }
 
+function patchLiveAudioGroupState(
+  iframe: HTMLIFrameElement | null,
+  elements: readonly TimelineElement[],
+  groupId: string | null,
+  activeCompPath: string | null,
+): void {
+  for (const element of elements) {
+    const target = findTimelineElementInIframe(iframe, element, activeCompPath);
+    if (!target) continue;
+    if (groupId) target.setAttribute(HF_AUDIO_GROUP_ATTR, groupId);
+    else target.removeAttribute(HF_AUDIO_GROUP_ATTR);
+  }
+}
+
+interface CreateAudioGroupAndAssignMembersInput {
+  projectId: string;
+  activeCompPath: string | null;
+  elements: readonly TimelineElement[];
+  groupId: string;
+  previewIframe: HTMLIFrameElement | null;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRef<number>;
+  pendingTimelineEditPathRef: MutableRef<Set<string>>;
+}
+
+/**
+ * Group two or more voice clips: write `data-audio-group="<groupId>"` on
+ * every one of them, atomically, one undo entry — the same multi-target shape
+ * `setElementsHidden` uses for mute. The group needs no `<hf-audio-group>`
+ * element of its own to exist: `resolveAudioGroups` already degrades
+ * gracefully to label = id when one is absent, and a naming dialog is out of
+ * scope here — the id itself is the default name.
+ */
+// fallow-ignore-next-line complexity
+export async function createAudioGroupAndAssignMembers({
+  projectId,
+  activeCompPath,
+  elements,
+  groupId,
+  previewIframe,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  pendingTimelineEditPathRef,
+}: CreateAudioGroupAndAssignMembersInput): Promise<string[]> {
+  if (elements.length < 2) return [];
+
+  patchLiveAudioGroupState(previewIframe, elements, groupId, activeCompPath);
+  reseekPreviewRuntime(previewIframe);
+
+  const groupOperation: PatchOperation = {
+    type: "attribute",
+    property: HF_AUDIO_GROUP_ATTR,
+    value: groupId,
+  };
+  const originalByPath = new Map<string, string>();
+  const files: Record<string, string> = {};
+
+  try {
+    for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
+      let patchedContent = await readFileContent(projectId, targetPath);
+      originalByPath.set(targetPath, patchedContent);
+
+      for (const element of fileElements) {
+        const patchTarget = buildPatchTarget(element);
+        if (!patchTarget) {
+          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
+        }
+        if (readTagSnippetByTarget(patchedContent, patchTarget) === undefined) {
+          throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
+        }
+        patchedContent = applyPatchByTarget(patchedContent, patchTarget, groupOperation);
+      }
+
+      files[targetPath] = patchedContent;
+      pendingTimelineEditPathRef.current.add(targetPath);
+    }
+
+    domEditSaveTimestampRef.current = Date.now();
+    const changedPaths = await saveProjectFilesWithHistory({
+      projectId,
+      label: `Group ${elements.length} voice clips`,
+      kind: "timeline",
+      files,
+      readFile: async (path) => {
+        const original = originalByPath.get(path);
+        if (original !== undefined) return original;
+        return readFileContent(projectId, path);
+      },
+      writeFile: writeProjectFile,
+      recordEdit,
+    });
+    domEditSaveTimestampRef.current = Date.now();
+    for (const element of elements) {
+      usePlayerStore.getState().updateElement(element.key ?? element.id, { audioGroup: groupId });
+    }
+    return changedPaths;
+  } catch (error) {
+    // Mirrors setElementsHidden's failure path: the optimistic live patch
+    // already ran, so a save failure has to be unwound or the preview shows a
+    // grouping that never made it to disk.
+    patchLiveAudioGroupState(previewIframe, elements, null, activeCompPath);
+    reseekPreviewRuntime(previewIframe);
+    throw error;
+  }
+}
+
 export function useTimelineTrackVisibilityEditing({
   projectIdRef,
   activeCompPath,
@@ -278,14 +408,18 @@ export function useTimelineTrackVisibilityEditing({
   pendingTimelineEditPathRef,
   isRecordingRef,
   forceReloadSdkSession,
-}: UseTimelineTrackVisibilityEditingInput): (track: number, hidden: boolean) => Promise<void> {
+}: UseTimelineTrackVisibilityEditingInput): (
+  track: number,
+  hidden: boolean,
+  displayNumber?: number | null,
+) => Promise<void> {
   // Resolve the eye toggle against the EXPANDED rows the canvas actually renders:
   // virtual sub-comp children carry their own (display.track + idx) track numbers,
   // so filtering the raw store list by a virtual track number would hide the wrong
   // outer-scene sibling sharing that index.
   const expandedElements = useExpandedTimelineElements();
   return useCallback(
-    async (track: number, hidden: boolean) => {
+    async (track: number, hidden: boolean, displayNumber?: number | null) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
         return;
@@ -299,6 +433,7 @@ export function useTimelineTrackVisibilityEditing({
           timelineElements: expandedElements,
           track,
           hidden,
+          displayNumber,
           previewIframe: previewIframeRef.current,
           writeProjectFile,
           recordEdit,
@@ -397,3 +532,67 @@ export function useTimelineElementVisibilityEditing({
     ],
   );
 }
+
+/**
+ * The write behind B6's auto-group: pick two or more voice clips in the carve
+ * picker and they land in a group instead of naming each other by id. Same
+ * expanded-rows resolution as element-visibility, for the same reason — a
+ * nested sub-composition child has no entry in the raw store list.
+ */
+export function useAudioGroupCarveAssignment({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+}: UseTimelineElementVisibilityEditingInput): (
+  clipIds: readonly string[],
+  groupId: string,
+) => Promise<void> {
+  const expandedElements = useExpandedTimelineElements();
+  return useCallback(
+    async (clipIds: readonly string[], groupId: string) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const keys = new Set(clipIds);
+      const elements = expandedElements.filter((item) => keys.has(item.key ?? item.id));
+      try {
+        await createAudioGroupAndAssignMembers({
+          projectId: pid,
+          activeCompPath,
+          elements,
+          groupId,
+          previewIframe: previewIframeRef.current,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        });
+      } catch (error) {
+        console.error("[Timeline] Failed to group voice clips", error);
+        const message = error instanceof Error ? error.message : "Failed to group voice clips";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      expandedElements,
+      previewIframeRef,
+      writeProjectFile,
+      recordEdit,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+      showToast,
+      projectIdRef,
+    ],
+  );
+}

package/src/hooks/useAppHotkeys.ts

@@ -7,6 +7,11 @@ import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { isTypingTarget } from "../utils/typingTarget";
 import { isEditableTarget } from "../utils/timelineDiscovery";
+import { useCaptionStore } from "../captions/store";
+import {
+  applyCaptionModelToIframe,
+  isCaptionPreviewVisible,
+} from "../captions/components/CaptionOverlayUtils";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { trackStudioEvent } from "../utils/studioTelemetry";
@@ -413,6 +418,23 @@ export function useAppHotkeys({
 
   const applyHistory = useCallback(
     async (direction: "undo" | "redo") => {
+      // Caption edits live in their own in-memory stack. While caption edit
+      // mode is active, ⌘Z must revert the caption edit — not an unrelated
+      // earlier file edit (which would ALSO leave the caption change intact).
+      const captionState = useCaptionStore.getState();
+      // Only when the caption preview is actually visible: isEditMode stays
+      // true while the preview is hidden (storyboard view), and eating ⌘Z
+      // there would pop invisible caption edits instead of file history.
+      if (captionState.isEditMode && isCaptionPreviewVisible()) {
+        const restored = direction === "undo" ? captionState.undo() : captionState.redo();
+        if (restored) {
+          applyCaptionModelToIframe(restored);
+          showToast(`${direction === "undo" ? "Undid" : "Redid"} caption edit`, "info");
+          return;
+        }
+        // Empty caption stack: fall through to beat/file history as usual.
+      }
+
       // Beat edits interleave with file history by timestamp; handle them first.
       if (tryApplyBeatHistory(direction, editHistory.state, showToast)) return;
 

package/src/hooks/useAudioSoloBridge.ts

@@ -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]);
+}