@hyperframes/studio 0.8.109 → 0.8.110

package/src/editorGesturesExports.test.tsx

@@ -82,6 +82,7 @@ function mountMarquee<T>(extra: Partial<MarqueeGesturesDeps<T>> = {}) {
       clientX: x,
       clientY: y,
       pointerId: 7,
+      buttons: 1,
       shiftKey,
       currentTarget: overlay,
     }) as unknown as PointerEvent<HTMLDivElement>;

package/src/hooks/appHotkeysDispatch.ts

@@ -9,6 +9,7 @@ import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";
+import { openAudioGainDialog } from "../player/components/audioGainDialogStore";
 import type { LinkShortcutCallbacks } from "./linkShortcuts";
 
 // Extracted from useAppHotkeys.ts to keep it under the studio 600-line cap,
@@ -190,6 +191,14 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     }
   }
 
+  // Only with a sound clip selected, so bare G still reaches the canvas grid toggle otherwise.
+  if (key === STUDIO_PLAIN_KEYS.audioGain && !event.shiftKey && !event.altKey) {
+    if (!cb.readOnlyPreview && openAudioGainDialog()) {
+      event.preventDefault();
+      return;
+    }
+  }
+
   if (key === "b" && !event.shiftKey && !event.altKey) {
     event.preventDefault();
     const { activeTool, setActiveTool } = usePlayerStore.getState();

package/src/hooks/timelineElementsAttribute.test.ts

@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { configurable: true, value: true });
+import type { TimelineElement } from "../player";
+
+const saved = vi.hoisted(() => ({ inputs: [] as Array<Record<string, unknown>> }));
+vi.mock("../utils/studioFileHistory", () => ({
+  saveProjectFilesWithHistory: vi.fn(async (input: Record<string, unknown>) => {
+    saved.inputs.push(input);
+    return [];
+  }),
+}));
+
+import { useSetElementsAttribute } from "./timelineElementsAttribute";
+
+const clip = (id: string, sourceFile?: string): TimelineElement => ({
+  id,
+  domId: id,
+  tag: "audio",
+  start: 0,
+  duration: 1,
+  track: 0,
+  sourceFile,
+});
+
+describe("useSetElementsAttribute", () => {
+  it("writes every clip's attribute in one history entry, one builder per file", async () => {
+    const showToast = vi.fn();
+    let write: ReturnType<typeof useSetElementsAttribute> | null = null;
+    function Probe() {
+      write = useSetElementsAttribute({
+        projectIdRef: { current: "p1" },
+        activeCompPath: "index.html",
+        showToast,
+        writeProjectFile: vi.fn(async () => {}),
+        recordEdit: vi.fn(async () => {}),
+        previewIframeRef: { current: null },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Probe)));
+    await write?.(
+      [
+        { element: clip("a"), value: "0.5" },
+        { element: clip("b"), value: "2" },
+        { element: clip("c", "scene.html"), value: "1.5" },
+      ],
+      "data-volume",
+      "Audio Gain",
+    );
+    act(() => root.unmount());
+    expect(showToast).not.toHaveBeenCalled();
+    expect(saved.inputs).toHaveLength(1);
+    const input = saved.inputs[0];
+    expect(input?.["label"]).toBe("Audio Gain");
+    const files = input?.["files"];
+    if (typeof files !== "object" || files === null) throw new Error("no files");
+    expect(Object.keys(files).sort()).toEqual(["index.html", "scene.html"]);
+    const build = Reflect.get(files, "index.html");
+    const html = '<audio id="a" data-volume="1"></audio><audio id="b"></audio>';
+    const out = typeof build === "function" ? String(build(html)) : "";
+    expect(out).toContain('id="a" data-volume="0.5"');
+    expect(out).toMatch(/id="b"[^>]*data-volume="2"/);
+  });
+
+  it("refuses while recording, like the single-clip write", async () => {
+    saved.inputs.length = 0;
+    const showToast = vi.fn();
+    let write: ReturnType<typeof useSetElementsAttribute> | null = null;
+    function Probe() {
+      write = useSetElementsAttribute({
+        projectIdRef: { current: "p1" },
+        activeCompPath: "index.html",
+        showToast,
+        writeProjectFile: vi.fn(async () => {}),
+        recordEdit: vi.fn(async () => {}),
+        previewIframeRef: { current: null },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        isRecordingRef: { current: true },
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Probe)));
+    await write?.([{ element: clip("a"), value: "0.5" }], "data-volume", "Audio Gain");
+    act(() => root.unmount());
+    expect(saved.inputs).toHaveLength(0);
+    expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error");
+  });
+});

package/src/hooks/timelineElementsAttribute.ts

@@ -0,0 +1,113 @@
+import { useCallback } from "react";
+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
+import { syncStoredElementAttribute } from "../player/lib/automationStoreSync";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { applyPatchByTarget } from "../utils/sourcePatcher";
+import {
+  buildPatchTarget,
+  findTimelineElementInIframe,
+  readFileContent,
+} from "./timelineEditingHelpers";
+import type { UseTimelineElementVisibilityEditingInput } from "./timelineTrackVisibility";
+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
+
+type ElementAttributeEdits = Parameters<
+  NonNullable<TimelineEditCallbacks["onSetElementsAttributeQuiet"]>
+>[0];
+
+type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
+
+function editsByFile(
+  edits: ElementAttributeEdits,
+  activeCompPath: string | null,
+): Map<string, Array<{ target: PatchTarget; value: string | null }>> {
+  const byFile = new Map<string, Array<{ target: PatchTarget; value: string | null }>>();
+  for (const { element, value } of edits) {
+    const target = buildPatchTarget(element);
+    if (!target) throw new Error("A clip has no id to save it by");
+    const path = element.sourceFile || activeCompPath || "index.html";
+    byFile.set(path, [...(byFile.get(path) ?? []), { target, value }]);
+  }
+  return byFile;
+}
+
+function patchLive(
+  iframe: HTMLIFrameElement | null,
+  edits: ElementAttributeEdits,
+  attr: string,
+  activeCompPath: string | null,
+): void {
+  for (const { element, value } of edits) {
+    const node = findTimelineElementInIframe(iframe, element, activeCompPath);
+    if (value === null) node?.removeAttribute(attr);
+    else node?.setAttribute(attr, value);
+    syncStoredElementAttribute(element, attr, value);
+  }
+}
+
+/** One attribute written on several clips as a single save and a single undo step. */
+export function useSetElementsAttribute({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+}: UseTimelineElementVisibilityEditingInput) {
+  return useCallback(
+    async (
+      edits: ElementAttributeEdits,
+      attr: string,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const projectId = projectForTimelineSave(
+        isRecordingRef?.current,
+        projectIdRef.current,
+        showToast,
+      );
+      if (typeof projectId !== "string") return projectId;
+      if (edits.length === 0) return { status: "saved" };
+      try {
+        const byFile = editsByFile(edits, activeCompPath);
+        const files = Object.fromEntries(
+          [...byFile].map(([path, patches]) => [
+            path,
+            (before: string) =>
+              patches.reduce(
+                (html, { target, value }) =>
+                  applyPatchByTarget(html, target, { type: "attribute", property: attr, value }),
+                before,
+              ),
+          ]),
+        );
+        for (const path of byFile.keys()) pendingTimelineEditPathRef.current.add(path);
+        await saveProjectFilesWithHistory({
+          projectId,
+          label,
+          files,
+          readFile: (path) => readFileContent(projectId, path),
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+        patchLive(previewIframeRef.current, edits, attr, activeCompPath);
+        return { status: "saved" };
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : "Could not save the clips";
+        showToast(reason, "error");
+        return { status: "failed", reason };
+      }
+    },
+    [
+      projectIdRef,
+      activeCompPath,
+      showToast,
+      writeProjectFile,
+      recordEdit,
+      previewIframeRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+    ],
+  );
+}

package/src/hooks/timelineLinkEditPlan.test.ts

@@ -1,6 +1,7 @@
 // @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
 import type { TimelineElement } from "../player";
+import { clipSyncState } from "../player/components/clipSync";
 import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";
 
 const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({
@@ -111,3 +112,30 @@ describe("planLinkEdit into sync", () => {
     expect(html).toBe('<audio id="talk-audio" data-playback-start="0.5"></audio>');
   });
 });
+
+describe("link edit plan", () => {
+  const PAIR =
+    '<div><video id="talk" src="talk.mp4" muted data-start="2" data-duration="6"></video><audio id="a" src="%SRC%" data-start="3" data-duration="3" data-media-start="1"></audio></div>';
+  const linkPlan = (src: string, audioEl: TimelineElement) => {
+    const v = clip("talk", "video", { muted: true });
+    const plan = planLinkEdit({ kind: "link", elements: [v, audioEl] }, [v, audioEl]);
+    return plan?.transform(PAIR.replace("%SRC%", src)) ?? "";
+  };
+
+  it("links a trimmed same-file audio with a sync origin that shows a nonzero offset", () => {
+    const trimmed = clip("a", "audio", { start: 3, duration: 3, playbackStart: 0 });
+    const out = linkPlan("talk.mp4", trimmed);
+    expect(out).toMatch(/<video[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);
+    expect(out).toMatch(/<audio[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);
+    const v = clip("talk", "video", { muted: true, syncOrigin: "lk-1" });
+    const a = { ...trimmed, syncOrigin: "lk-1" };
+    expect(clipSyncState(a, [v, a], 30)?.frames).toBe(30);
+  });
+
+  it("links different files without a sync origin", () => {
+    const music = clip("a", "audio", { src: "bgm.mp3" });
+    const out = linkPlan("bgm.mp3", music);
+    expect(out).toContain('data-link="lk-1"');
+    expect(out).not.toContain("data-sync-origin");
+  });
+});

package/src/hooks/timelineLinkEditPlan.ts

@@ -13,6 +13,7 @@ import {
   mergeAudioInSource,
   pickDetachedAudioTrack,
   setLinkInSource,
+  sharesSourceFile,
 } from "../components/editor/mediaLinkEdits";
 
 export interface LinkEditPlan {
@@ -92,7 +93,11 @@ export function planLinkEdit(
       const targets = targetsOf(edit.elements);
       const anchor = edit.elements[0];
       if (!targets || !anchor) return null;
-      return { label: "Link clips", anchor, transform: (s) => linkInSource(s, targets) };
+      return {
+        label: "Link clips",
+        anchor,
+        transform: (s) => linkInSource(s, targets, { syncOrigin: sharesSourceFile(edit.elements) }),
+      };
     }
     case "detach": {
       const target = buildPatchTarget(edit.element);

package/src/hooks/useAppHotkeys.test.ts

@@ -6,6 +6,7 @@ import type { DomEditSelection } from "../components/editor/domEditing";
 import { clearAutomationClipboard, copyRange } from "../player/components/automationClipboard";
 import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
 import type { TimelineElement } from "../player/store/timelineElement";
+import { useAudioGainDialogStore } from "../player/components/audioGainDialogStore";
 
 /** Minimal valid fixture — TimelineElement only requires these five fields. */
 const bgmElement: TimelineElement = {
@@ -474,3 +475,36 @@ describe("hotkeys with the preview read-only", () => {
     expect(cb.handleDomEditElementDelete).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("dispatchPlainKey — G opens Audio Gain", () => {
+  const video: TimelineElement = {
+    id: "b-roll",
+    key: "b-roll",
+    tag: "video",
+    start: 0,
+    duration: 4,
+    track: 1,
+  };
+
+  afterEach(() => useAudioGainDialogStore.getState().close());
+
+  it("opens the dialog for the selected clips with sound and owns the key", () => {
+    usePlayerStore.setState({
+      elements: [bgmElement, video],
+      selectedElementId: "bgm",
+      selectedElementIds: new Set(["bgm", "b-roll"]),
+    });
+    const event = press("g");
+    dispatchPlainKey(event, "g", callbacks());
+    expect(useAudioGainDialogStore.getState().targetKeys).toEqual(["bgm"]);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("leaves G to the grid toggle when nothing selected has sound", () => {
+    usePlayerStore.setState({ elements: [video], selectedElementId: "b-roll" });
+    const event = press("g");
+    dispatchPlainKey(event, "g", callbacks());
+    expect(useAudioGainDialogStore.getState().targetKeys).toBeNull();
+    expect(event.defaultPrevented).toBe(false);
+  });
+});

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -443,7 +443,14 @@ describe("useDomGeometryCommits resize of a cropped element", () => {
       const handle = document.querySelector<HTMLButtonElement>('[aria-label="Crop right"]')!;
       const press = (type: string, clientX: number) =>
         act(() =>
-          handle.dispatchEvent(new PointerEvent(type, { bubbles: true, pointerId: 3, clientX })),
+          handle.dispatchEvent(
+            new PointerEvent(type, {
+              bubbles: true,
+              pointerId: 3,
+              buttons: type === "pointerup" ? 0 : 1,
+              clientX,
+            }),
+          ),
         );
       press("pointerdown", 100);
       press("pointermove", 100 - by);

package/src/hooks/useRenderClipContent.ts

@@ -14,6 +14,7 @@ import { AudioWaveform, rendersWaveform } from "../player/components/AudioWavefo
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { AudibleVideoClipContent } from "../player/components/AudibleVideoClipContent";
 import { ClipPeakMarks } from "../player/components/ClipPeakMarks";
+import { clipPeaksUrl, clipSourceWindow } from "../player/components/clipPeakMap";
 import { clipHasSound } from "../player/components/clipMenuNormalize";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
 import { usePlayerStore } from "../player/store/playerStore";
@@ -91,11 +92,8 @@ function renderAudioClip(
   return createElement(
     ClipPeakMarks,
     {
-      peaksUrl: encodedRelative ? buildProjectApiPath(pid, `/peaks/${encodedRelative}`) : undefined,
-      sourceWindow: {
-        mediaStart: el.playbackStart ?? 0,
-        sourceSpan: el.duration * (el.playbackRate ?? 1),
-      },
+      peaksUrl: clipPeaksUrl(el.src, pid),
+      sourceWindow: clipSourceWindow(el),
       gain: el.volume ?? 1,
     },
     waveform,

package/src/hooks/useTimelineEditing.ts

@@ -26,6 +26,7 @@ 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 {
@@ -409,6 +410,17 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
+  const setElementsAttribute = useSetElementsAttribute({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+  });
+
   const setAudioGroupAttribute = useSetAudioGroupAttribute({
     projectIdRef,
     activeCompPath,
@@ -532,6 +544,7 @@ export function useTimelineEditing({
     },
     setElementFxAttribute: {
       ...setElementFxAttribute,
+      setMany: track(guard((edits) => edits.map((edit) => edit.element), setElementsAttribute)),
       setQuiet: track(
         guard(
           (element) => [element],

package/src/hooks/useTimelineLinkEditing.test.tsx

@@ -109,4 +109,16 @@ describe("useTimelineLinkEditing", () => {
     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

@@ -49,6 +49,10 @@ export function withLinkPartners(selection: readonly TimelineElement[]): Timelin
   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,
@@ -71,6 +75,7 @@ export function useTimelineLinkEditing({
       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(() =>

package/src/index.ts

@@ -32,6 +32,10 @@ export {
   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);
+  });
+});