@hyperframes/studio 0.8.108 → 0.8.110

package/src/hooks/useTimelineEditGuard.ts

@@ -0,0 +1,54 @@
+import { useCallback, useRef } from "react";
+import type { TimelineElement } from "../player";
+import { useTimelineEditRefusal } from "./timelineEditPermission";
+
+type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;
+type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
+type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;
+
+interface GuardedTimelineEntry {
+  resolveTargets: GuardedTimelineResolver;
+  onRefused?: GuardedTimelineRefusal;
+  wrapped: GuardedTimelineHandler;
+}
+
+export function useTimelineEditGuard(
+  canEdit: Parameters<typeof useTimelineEditRefusal>[0],
+  showToast: Parameters<typeof useTimelineEditRefusal>[1],
+) {
+  const refuseEdit = useTimelineEditRefusal(canEdit, showToast);
+  const refuseEditRef = useRef(refuseEdit);
+  refuseEditRef.current = refuseEdit;
+  const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
+  // Refuses (no call, no write, no history entry) when any target is
+  // blocked; otherwise runs fn as before. Cached by fn identity — like
+  // track() — so a fresh closure here doesn't defeat track's own cache.
+  const guard = useCallback(
+    <H extends (...args: never[]) => Promise<unknown>>(
+      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
+      fn: H,
+      onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,
+    ): H => {
+      const key = fn as unknown as GuardedTimelineHandler;
+      const cached = guardedRef.current.get(key);
+      if (cached) {
+        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+        return cached.wrapped as H;
+      }
+      const entry = {} as GuardedTimelineEntry;
+      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+      entry.wrapped = ((...args: Parameters<H>) => {
+        const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));
+        if (reason !== null)
+          return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));
+        return fn(...args);
+      }) as H as unknown as GuardedTimelineHandler;
+      guardedRef.current.set(key, entry);
+      return entry.wrapped as H;
+    },
+    [],
+  );
+  return guard;
+}

package/src/hooks/useTimelineEditing.ts

@@ -26,7 +26,14 @@ import {
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
+import { useSetElementsAttribute } from "./timelineElementsAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useTimelineEditGuard } from "./useTimelineEditGuard";
+import {
+  linkEditTargets,
+  useTimelineLinkEditing,
+  withLinkPartners,
+} from "./useTimelineLinkEditing";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
@@ -35,26 +42,12 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
-import {
-  useTimelineEditGate,
-  useTimelineEditRefusal,
-  type TimelineEditOutcome,
-} from "./timelineEditPermission";
+import { useTimelineEditGate, type TimelineEditOutcome } from "./timelineEditPermission";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
-type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;
-type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
-type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;
-
-interface GuardedTimelineEntry {
-  resolveTargets: GuardedTimelineResolver;
-  onRefused?: GuardedTimelineRefusal;
-  wrapped: GuardedTimelineHandler;
-}
-
 export function useTimelineEditing({
   projectId,
   activeCompPath,
@@ -80,40 +73,7 @@ export function useTimelineEditing({
   const editQueueRef = useRef(Promise.resolve());
   const track = useTrackPendingTimelineEdit();
   const checkEditable = useTimelineEditGate(canEdit, showToast);
-  const refuseEdit = useTimelineEditRefusal(canEdit, showToast);
-  const refuseEditRef = useRef(refuseEdit);
-  refuseEditRef.current = refuseEdit;
-  const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
-  // Refuses (no call, no write, no history entry) when any target is
-  // blocked; otherwise runs fn as before. Cached by fn identity — like
-  // track() — so a fresh closure here doesn't defeat track's own cache.
-  const guard = useCallback(
-    <H extends (...args: never[]) => Promise<unknown>>(
-      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
-      fn: H,
-      onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,
-    ): H => {
-      const key = fn as unknown as GuardedTimelineHandler;
-      const cached = guardedRef.current.get(key);
-      if (cached) {
-        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
-        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
-        return cached.wrapped as H;
-      }
-      const entry = {} as GuardedTimelineEntry;
-      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
-      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
-      entry.wrapped = ((...args: Parameters<H>) => {
-        const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));
-        if (reason !== null)
-          return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));
-        return fn(...args);
-      }) as H as unknown as GuardedTimelineHandler;
-      guardedRef.current.set(key, entry);
-      return entry.wrapped as H;
-    },
-    [],
-  );
+  const guard = useTimelineEditGuard(canEdit, showToast);
 
   const enqueueEdit = useCallback(
     (
@@ -252,7 +212,7 @@ export function useTimelineEditing({
         return reorderDone
           .then(() => {
             // SDK setTiming writes start only; a lane change needs the fallback's track patch.
-            if (sdkSession && element.hfId && !needsExtension && !trackChanged) {
+            if (sdkSession && element.hfId && !element.link && !needsExtension && !trackChanged) {
               return sdkTimingPersist(
                 element.hfId,
                 targetPath,
@@ -359,7 +319,7 @@ export function useTimelineEditing({
           finishResizeGsapSync(),
         );
       const persistDone =
-        sdkSession && element.hfId && !hasPbsAdjustment && !needsExtension
+        sdkSession && element.hfId && !element.link && !hasPbsAdjustment && !needsExtension
           ? sdkTimingPersist(
               element.hfId,
               targetPath,
@@ -450,6 +410,17 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
+  const setElementsAttribute = useSetElementsAttribute({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+  });
+
   const setAudioGroupAttribute = useSetAudioGroupAttribute({
     projectIdRef,
     activeCompPath,
@@ -461,7 +432,7 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
-  const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({
+  const { handleTimelineElementsDelete } = useTimelineDeleteOps({
     projectIdRef,
     activeCompPath,
     timelineElements,
@@ -491,6 +462,20 @@ export function useTimelineEditing({
       checkEditable,
     });
 
+  const linkEditing = useTimelineLinkEditing({
+    projectIdRef,
+    activeCompPath,
+    editQueueRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    reloadPreview,
+    forceReloadSdkSession,
+    handleTimelineElementsDelete,
+  });
+
   const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
   const { handleRazorSplit, handleRazorSplitAll, handleFreezeFrame } = useRazorSplit({
     projectId,
@@ -526,7 +511,9 @@ export function useTimelineEditing({
   // Every write-handler is tracked here, the one place all hand edits
   // converge, so undo never races a write; canEdit gates the same point.
   // Coverage boundary: see the PR body, not every kind resolves an element.
-  const trackedRazorSplit = track(guard((element) => [element], handleRazorSplit));
+  const trackedRazorSplit = track(
+    guard((element) => withLinkPartners([element]), handleRazorSplit),
+  );
   return {
     handleTimelineElementMove: track(guard((element) => [element], handleTimelineElementMove)),
     handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
@@ -557,6 +544,7 @@ export function useTimelineEditing({
     },
     setElementFxAttribute: {
       ...setElementFxAttribute,
+      setMany: track(guard((edits) => edits.map((edit) => edit.element), setElementsAttribute)),
       setQuiet: track(
         guard(
           (element) => [element],
@@ -568,10 +556,16 @@ export function useTimelineEditing({
         ),
       ),
     },
-    handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),
+    handleTimelineElementDelete: track(
+      guard((element) => withLinkPartners([element]), linkEditing.handleLinkedElementDelete),
+    ),
     handleTimelineElementsDelete: track(
-      guard((elements) => elements, handleTimelineElementsDelete),
+      guard(withLinkPartners, linkEditing.handleLinkedElementsDelete),
+    ),
+    handleTimelineElementDeleteOnly: track(
+      guard((element) => [element], linkEditing.handleDeleteElementOnly),
     ),
+    handleLinkEdit: track(guard(linkEditTargets, linkEditing.handleLinkEdit)),
     handleTimelineElementSplit: trackedRazorSplit,
     handleRazorSplit: trackedRazorSplit,
     handleFreezeFrame: track(guard((element) => [element], handleFreezeFrame)),

package/src/hooks/useTimelineLinkEditing.test.tsx

@@ -0,0 +1,124 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { useTimelineLinkEditing, withLinkPartners } from "./useTimelineLinkEditing";
+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const clip = (id: string, tag: string, link?: string): TimelineElement => ({
+  id,
+  domId: id,
+  tag,
+  start: 0,
+  duration: 4,
+  track: 0,
+  ...(link ? { link } : {}),
+});
+const video = clip("talk", "video", "lk-1");
+const audio = clip("talk-audio", "audio", "lk-1");
+const title = clip("title", "div");
+
+const SOURCE =
+  '<div><video id="talk" muted data-link="lk-1"></video><audio id="talk-audio" data-link="lk-1"></audio></div>';
+
+async function renderLinkEditing(handleTimelineElementsDelete = vi.fn()) {
+  usePlayerStore.getState().setElements([video, audio, title]);
+  const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+  const recordEdit = vi.fn().mockResolvedValue(undefined);
+  let api: ReturnType<typeof useTimelineLinkEditing> | undefined;
+  function Harness() {
+    api = useTimelineLinkEditing({
+      projectIdRef: { current: "p1" },
+      activeCompPath: "index.html",
+      editQueueRef: { current: Promise.resolve() },
+      pendingTimelineEditPathRef: { current: new Set() },
+      showToast: vi.fn(),
+      writeProjectFile,
+      recordEdit,
+      reloadPreview: vi.fn(),
+      handleTimelineElementsDelete,
+    });
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  await act(async () => root.render(React.createElement(Harness)));
+  if (!api) throw new Error("hook did not render");
+  return { api, writeProjectFile, recordEdit, unmount: () => act(() => root.unmount()) };
+}
+
+describe("withLinkPartners", () => {
+  it("adds partners after the selection, once", () => {
+    usePlayerStore.getState().setElements([video, audio, title]);
+    expect(withLinkPartners([video, title]).map((el) => el.id)).toEqual([
+      "talk",
+      "title",
+      "talk-audio",
+    ]);
+    expect(withLinkPartners([video, audio])).toHaveLength(2);
+  });
+});
+
+describe("useTimelineLinkEditing", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("deletes a linked clip with its partner", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    await act(async () => api.handleLinkedElementDelete(video));
+    expect(del.mock.calls[0]?.[0].map((el: TimelineElement) => el.id)).toEqual([
+      "talk",
+      "talk-audio",
+    ]);
+    unmount();
+  });
+
+  it("with Linked Selection off, delete removes the clip alone and unlinks the survivor", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    useLinkedClipPreferences.getState().setLinkedSelection(false);
+    try {
+      expect(withLinkPartners([video])).toEqual([video]);
+      await act(async () => api.handleLinkedElementDelete(video));
+      expect(del).toHaveBeenCalledWith([video], [audio]);
+    } finally {
+      useLinkedClipPreferences.getState().setLinkedSelection(true);
+    }
+    unmount();
+  });
+
+  it("delete-only removes one member and unlinks the survivor", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    await act(async () => api.handleDeleteElementOnly(video));
+    expect(del).toHaveBeenCalledWith([video], [audio]);
+    unmount();
+  });
+
+  it("unlink writes one undo step removing data-link from both", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ content: SOURCE }), { status: 200 }),
+    );
+    const { api, writeProjectFile, recordEdit, unmount } = await renderLinkEditing();
+    await act(async () => api.handleLinkEdit({ kind: "unlink", elements: [video, audio] }));
+    expect(writeProjectFile).toHaveBeenCalledTimes(1);
+    expect(writeProjectFile.mock.calls[0]?.[1]).not.toContain("data-link");
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit.mock.calls[0]?.[0].label).toBe("Unlink clips");
+    unmount();
+  });
+
+  it("unlink leaves nothing selected, so a later trim moves only the grabbed clip", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ content: SOURCE }), { status: 200 }),
+    );
+    const { api, unmount } = await renderLinkEditing();
+    usePlayerStore.getState().setSelection(["talk", "talk-audio"], "talk");
+    await act(async () => api.handleLinkEdit({ kind: "unlink", elements: [video, audio] }));
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    expect(usePlayerStore.getState().selectedElementId).toBeNull();
+    unmount();
+  });
+});

package/src/hooks/useTimelineLinkEditing.ts

@@ -0,0 +1,158 @@
+import { useCallback, type MutableRefObject } from "react";
+import { usePlayerStore, type TimelineElement } from "../player";
+import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";
+import { expandToLinkedMembers } from "../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
+import { readFileContent } from "./timelineEditingHelpers";
+import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";
+
+interface UseTimelineLinkEditingOptions {
+  projectIdRef: MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  editQueueRef: MutableRefObject<Promise<void>>;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  isRecordingRef?: MutableRefObject<boolean>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  reloadPreview: () => void;
+  forceReloadSdkSession?: () => void;
+  handleTimelineElementsDelete: (
+    selection: TimelineElement[],
+    alsoUnlink?: readonly TimelineElement[],
+  ) => Promise<void>;
+}
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+
+/** Every clip a link edit writes, for the edit-permission gate. */
+export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {
+  switch (edit.kind) {
+    case "unlink":
+    case "link":
+      return [...edit.elements];
+    case "detach":
+    case "move-into-sync":
+    case "slip-into-sync":
+      return [edit.element];
+    case "merge":
+      return [edit.video, edit.audio];
+  }
+}
+
+export function withLinkPartners(selection: readonly TimelineElement[]): TimelineElement[] {
+  const elements = usePlayerStore.getState().elements;
+  const keys = expandToLinkedMembers(selection.map(keyOf), elements, isLinkedSelectionOn());
+  const known = new Set(selection.map(keyOf));
+  return [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];
+}
+
+function clearSelectionOnUnlink(edit: TimelineLinkEdit): void {
+  if (edit.kind === "unlink") usePlayerStore.getState().clearSelection();
+}
+
+export function useTimelineLinkEditing({
+  projectIdRef,
+  activeCompPath,
+  editQueueRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  forceReloadSdkSession,
+  handleTimelineElementsDelete,
+}: UseTimelineLinkEditingOptions) {
+  const handleLinkEdit = useCallback(
+    async (edit: TimelineLinkEdit) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      const plan = planLinkEdit(edit, usePlayerStore.getState().elements);
+      if (!pid || !plan) return;
+      clearSelectionOnUnlink(edit);
+      const path = plan.anchor.sourceFile || activeCompPath || "index.html";
+      pendingTimelineEditPathRef.current.add(path);
+      const queued = editQueueRef.current.then(() =>
+        saveProjectFilesWithHistory({
+          projectId: pid,
+          label: plan.label,
+          files: {
+            [path]: (current) => {
+              const next = plan.transform(current);
+              if (next === null || next === current) {
+                throw new Error(`Couldn't ${plan.label.toLowerCase()}`);
+              }
+              return next;
+            },
+          },
+          readFile: (filePath) => readFileContent(pid, filePath),
+          writeFile: writeProjectFile,
+          recordEdit,
+        }),
+      );
+      editQueueRef.current = queued.then(
+        () => undefined,
+        () => undefined,
+      );
+      try {
+        await queued;
+        forceReloadSdkSession?.();
+        reloadPreview();
+      } catch (error) {
+        showToast(getStudioSaveErrorMessage(error), "error");
+      }
+    },
+    [
+      activeCompPath,
+      editQueueRef,
+      forceReloadSdkSession,
+      isRecordingRef,
+      pendingTimelineEditPathRef,
+      projectIdRef,
+      recordEdit,
+      reloadPreview,
+      showToast,
+      writeProjectFile,
+    ],
+  );
+
+  const handleLinkedElementsDelete = useCallback(
+    (selection: TimelineElement[]) => {
+      if (isLinkedSelectionOn()) return handleTimelineElementsDelete(withLinkPartners(selection));
+      const removed = new Set(selection.map(keyOf));
+      const orphans = clipsToUnlink(selection, usePlayerStore.getState().elements).filter(
+        (el) => !removed.has(keyOf(el)),
+      );
+      return handleTimelineElementsDelete(selection, orphans);
+    },
+    [handleTimelineElementsDelete],
+  );
+
+  const handleLinkedElementDelete = useCallback(
+    (element: TimelineElement) => handleLinkedElementsDelete([element]),
+    [handleLinkedElementsDelete],
+  );
+
+  const handleDeleteElementOnly = useCallback(
+    (element: TimelineElement) => {
+      const orphans = clipsToUnlink([element], usePlayerStore.getState().elements).filter(
+        (el) => keyOf(el) !== keyOf(element),
+      );
+      return handleTimelineElementsDelete([element], orphans);
+    },
+    [handleTimelineElementsDelete],
+  );
+
+  return {
+    handleLinkEdit,
+    handleLinkedElementsDelete,
+    handleLinkedElementDelete,
+    handleDeleteElementOnly,
+  };
+}

package/src/index.ts

@@ -31,6 +31,11 @@ export {
   liveTime,
   formatTime,
 } from "./player";
+export { usePreviewIframeStore } from "./player/store/previewIframeStore";
+export {
+  openAudioGainDialog,
+  useAudioGainDialogStore,
+} from "./player/components/audioGainDialogStore";
 export type {
   PlayerHandle,
   PlayerHandleElement,

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

@@ -0,0 +1,133 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { audioGainToDb } from "@hyperframes/core/audio-gain";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { AudioGainDialog } from "./AudioGainDialog";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineElement } from "../store/timelineElement";
+
+const onNotice = vi.fn();
+const setQuiet = vi.fn(async () => {});
+const setMany = vi.fn(
+  async (_edits: ReadonlyArray<{ value: string | null }>, _attr: string, _label: string) => {},
+);
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContextOptional: () => null,
+}));
+vi.mock("../../contexts/TimelineEditContext", () => ({
+  useTimelineEditContextOptional: () => ({
+    onSetElementAttributeQuiet: setQuiet,
+    onSetElementsAttributeQuiet: setMany,
+    onNotice,
+  }),
+}));
+
+const harness = createHappyDomRootHarness();
+const clip = (id: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({
+  id,
+  tag: "audio",
+  start: 0,
+  duration: 2,
+  track: 0,
+  src: `${id}.wav`,
+  ...extra,
+});
+
+function stubPeaks(peaks: Record<string, number[]>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const name = Object.keys(peaks).find((key) => String(url).includes(`/peaks/${key}.wav`));
+      return name
+        ? Response.json({ binSeconds: 1, bins: peaks[name] })
+        : new Response("", { status: 404 });
+    }),
+  );
+}
+
+function open(elements: TimelineElement[]) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  act(() => harness.mount(host).render(<AudioGainDialog elements={elements} onClose={() => {}} />));
+}
+
+const row = (text: string) =>
+  [...document.querySelectorAll("label")].find((label) => label.textContent?.startsWith(text));
+const choose = (text: string) =>
+  act(() => row(text)?.querySelector<HTMLInputElement>("input[type=radio]")?.click());
+function typeDb(text: string, value: string) {
+  const input = row(text)?.querySelector<HTMLInputElement>("input[type=number]");
+  if (!input) throw new Error(`no field for ${text}`);
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  act(() => {
+    setter?.call(input, value);
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+}
+const ok = () => [...document.querySelectorAll("button")].find((b) => b.textContent === "OK");
+const peakText = () => document.querySelector("[data-testid='audio-gain-peak']")?.textContent;
+
+beforeEach(() => {
+  usePlayerStore.getState().beginTimelineSession("p1");
+  vi.clearAllMocks();
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe("AudioGainDialog", () => {
+  it("shows the selection's peak amplitude at the clips' current gain", async () => {
+    stubPeaks({ pk1: [0.25, 0.5] });
+    open([clip("pk1", { volume: 2 })]);
+    await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: 0.0 dB"));
+  });
+
+  it("Set Gain writes every selected clip in one undo step", async () => {
+    stubPeaks({});
+    const a = clip("set-a");
+    const b = clip("set-b", { volume: 0.5 });
+    open([a, b]);
+    choose("Set Gain to");
+    typeDb("Set Gain to", "-6");
+    await act(async () => ok()?.click());
+    expect(setMany).toHaveBeenCalledTimes(1);
+    const [edits, attr, label] = setMany.mock.calls[0] ?? [];
+    expect(attr).toBe("data-volume");
+    expect(label).toBe("Audio Gain");
+    expect(edits?.map((e) => audioGainToDb(Number(e.value)))).toEqual([
+      expect.closeTo(-6, 3),
+      expect.closeTo(-6, 3),
+    ]);
+    expect(setQuiet).not.toHaveBeenCalled();
+  });
+
+  it("Normalize All Peaks brings each clip's own peak to the target", async () => {
+    stubPeaks({ na1: [0.5], na2: [0.25] });
+    open([clip("na1"), clip("na2")]);
+    await vi.waitFor(() => expect(peakText()).not.toContain("measuring"));
+    choose("Normalize All Peaks to");
+    typeDb("Normalize All Peaks to", "-3");
+    await act(async () => ok()?.click());
+    const [edits] = setMany.mock.calls[0] ?? [];
+    const gains = edits?.map((e) => Number(e.value)) ?? [];
+    expect(audioGainToDb(0.5 * (gains[0] ?? 0))).toBeCloseTo(-3, 3);
+    expect(audioGainToDb(0.25 * (gains[1] ?? 0))).toBeCloseTo(-3, 3);
+  });
+
+  it("refuses a peak target above 0 dB", async () => {
+    stubPeaks({ over: [0.5] });
+    open([clip("over")]);
+    await vi.waitFor(() => expect(peakText()).not.toContain("measuring"));
+    choose("Normalize Max Peak to");
+    typeDb("Normalize Max Peak to", "2");
+    expect(ok()?.disabled).toBe(true);
+  });
+
+  it("disables the peak options when the clip cannot be measured", async () => {
+    stubPeaks({});
+    open([clip("unmeasured")]);
+    await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: —"));
+    expect(row("Normalize Max Peak to")?.querySelector("input")?.disabled).toBe(true);
+    expect(row("Adjust Gain by")?.querySelector("input")?.disabled).toBe(false);
+  });
+});