@hyperframes/studio 0.8.109 → 0.8.111

package/src/player/components/clipMenuAudioItems.tsx

@@ -1,18 +1,10 @@
-import { formatAudioGain } from "@hyperframes/core/audio-gain";
 import type { TimelineElement } from "../store/timelineElement";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { usePlayerStore } from "../store/playerStore";
 import { useLivePreviewIframe } from "../store/previewIframeStore";
-import {
-  clipHasSound,
-  normalizeToastText,
-  requestNormalizePlan,
-  throwUnlessSaved,
-  TimelineSaveError,
-  VOLUME_LANE_REFUSAL,
-  volumeLaneOwnsGain,
-} from "./clipMenuNormalize";
+import { clipHasSound, throwUnlessSaved, TimelineSaveError } from "./clipMenuNormalize";
+import { openAudioGainDialog } from "./audioGainDialogStore";
 import { offersDuck, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
 
 const ITEM_CLASS =
@@ -25,13 +17,13 @@ const DUCK_TOAST: Record<DuckOutcome, string> = {
   aborted: "Could not group the voices to duck under.",
 };
 
-/** Normalize loudness (one-shot) or Duck under voice (toggle), placed separately in the sound group. */
+/** Audio Gain… (opens the G dialog) or Duck under voice (toggle), placed separately in the sound group. */
 export function ClipMenuAudioItems({
   part,
   element,
   onClose,
 }: {
-  part: "normalize" | "duck";
+  part: "gain" | "duck";
   element: TimelineElement;
   onClose: () => void;
 }) {
@@ -48,28 +40,6 @@ export function ClipMenuAudioItems({
     return null;
   }
 
-  const normalize = async () => {
-    onClose();
-    if (volumeLaneOwnsGain(element)) {
-      showToast(VOLUME_LANE_REFUSAL, "error");
-      return;
-    }
-    try {
-      const plan = await requestNormalizePlan(projectId, element);
-      throwUnlessSaved(
-        await onSetElementAttributeQuiet(
-          element,
-          "data-volume",
-          formatAudioGain(plan.volume),
-          "Normalize loudness",
-        ),
-      );
-      showToast(normalizeToastText(plan), "info");
-    } catch (error) {
-      showToast(error instanceof Error ? error.message : String(error), "error");
-    }
-  };
-
   const toggleDuck = async () => {
     onClose();
     if (!doc || !bed) return;
@@ -93,10 +63,19 @@ export function ClipMenuAudioItems({
     showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
   };
 
-  if (part === "normalize") {
+  if (part === "gain") {
     return (
-      <button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>
-        <span>Normalize loudness</span>
+      <button
+        type="button"
+        role="menuitem"
+        className={ITEM_CLASS}
+        onClick={() => {
+          onClose();
+          openAudioGainDialog(element);
+        }}
+      >
+        <span>Audio Gain…</span>
+        <span className="text-neutral-500 text-[10px] ml-3">G</span>
       </button>
     );
   }

package/src/player/components/clipMenuLinkItems.test.ts

@@ -48,6 +48,51 @@ describe("resolveLinkMenuItems", () => {
     expect(labels(audio, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to video");
   });
 
+  it("offers Link to the lone same-file partner on another track when one clip is right-clicked", () => {
+    const video = clip("talk", "video", { track: 0 });
+    const audio = clip("talk-audio", "audio", { track: 1, start: 2 });
+    expect(labels(audio, [video, audio], ["talk-audio"])[0]).toBe("Link to video");
+    expect(labels(video, [video, audio])[0]).toBe("Link to audio");
+  });
+
+  it("dispatches the convenience link with the clip and its partner", () => {
+    const onLinkEdit = vi.fn();
+    const video = clip("talk", "video", { track: 0 });
+    const audio = clip("talk-audio", "audio", { track: 1 });
+    const [link] = resolveLinkMenuItems({
+      element: audio,
+      elements: [video, audio],
+      selectedKeys: new Set(["talk-audio"]),
+      onLinkEdit,
+    });
+    link?.run();
+    expect(onLinkEdit).toHaveBeenCalledWith({ kind: "link", elements: [audio, video] });
+  });
+
+  it("offers no convenience Link when the partner is ambiguous, linked, another file or the same track", () => {
+    const audio = clip("talk-audio", "audio", { track: 1 });
+    const video = clip("talk", "video", { track: 0 });
+    const twin = clip("talk-2", "video", { track: 2 });
+    expect(labels(audio, [video, twin, audio], ["talk-audio"])).not.toContain("Link to video");
+    const linked = clip("talk", "video", { track: 0, link: "lk-9" });
+    expect(labels(audio, [linked, audio], ["talk-audio"])).not.toContain("Link to video");
+    const other = clip("other", "video", { track: 0, src: "other.mp4" });
+    expect(labels(audio, [other, audio], ["talk-audio"])).not.toContain("Link to video");
+    const sameTrack = clip("talk", "video", { track: 1 });
+    expect(labels(audio, [sameTrack, audio], ["talk-audio"])).not.toContain("Link to video");
+  });
+
+  it("offers no convenience Link while other clips are also selected", () => {
+    const audio = clip("talk-audio", "audio", { track: 1 });
+    const video = clip("talk", "video", { track: 0 });
+    const title = clip("title", "div", { track: 2 });
+    expect(
+      labels(audio, [video, audio, title], ["talk-audio", "title"]).some((l) =>
+        l.startsWith("Link"),
+      ),
+    ).toBe(false);
+  });
+
   it("names the audio partner when unlinking from the video side", () => {
     const video = clip("talk", "video", { muted: true, link: "lk-1" });
     const audio = clip("talk-audio", "audio", { link: "lk-1" });
@@ -87,4 +132,43 @@ describe("resolveLinkMenuItems", () => {
     })[0]?.run();
     expect(onLinkEdit).toHaveBeenCalledWith({ kind: "detach", element: talk });
   });
+
+  it("offers Link for a trimmed audio and its video (timing does not matter)", () => {
+    const video = clip("talk", "video", { muted: true });
+    const audio = clip("talk-audio", "audio", { start: 1, duration: 2, playbackStart: 1 });
+    expect(labels(video, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to audio");
+  });
+
+  it("offers Link for a pair of different files", () => {
+    const video = clip("talk", "video", { muted: true });
+    const music = clip("bgm", "audio", { src: "bgm.mp3" });
+    expect(labels(music, [video, music], ["talk", "bgm"])).toEqual(["Link to video"]);
+  });
+
+  it("offers no Link when one selected clip is already linked elsewhere", () => {
+    const video = clip("talk", "video", { muted: true, link: "lk-9" });
+    const audio = clip("bgm", "audio", { src: "bgm.mp3" });
+    const partner = clip("talk-audio", "audio", { link: "lk-9" });
+    expect(labels(audio, [video, audio, partner], ["talk", "bgm"])).toEqual([]);
+  });
+
+  it("disables Merge back with a tooltip while the pair is out of sync", () => {
+    const video = clip("talk", "video", { muted: true, link: "lk-1" });
+    const audio = clip("talk-audio", "audio", { link: "lk-1", start: 0.5 });
+    const merge = resolveLinkMenuItems({
+      element: audio,
+      elements: [video, audio],
+      selectedKeys: new Set(),
+      onLinkEdit: vi.fn(),
+    }).find((item) => item.label === "Merge audio back into video");
+    expect(merge?.disabledReason).toBe("Move into Sync first");
+    const synced = clip("talk-audio", "audio", { link: "lk-1" });
+    const enabled = resolveLinkMenuItems({
+      element: synced,
+      elements: [video, synced],
+      selectedKeys: new Set(),
+      onLinkEdit: vi.fn(),
+    }).find((item) => item.label === "Merge audio back into video");
+    expect(enabled?.disabledReason).toBeUndefined();
+  });
 });

package/src/player/components/clipMenuLinkItems.tsx

@@ -2,12 +2,19 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import type { TimelineLinkEdit } from "./timelineCallbacks";
 import { linkedMembersOf } from "./audioClipLink";
-import { canDetachAudio, canLinkPair, findMergePair } from "../../components/editor/mediaLinkEdits";
+import {
+  canDetachAudio,
+  canLinkPair,
+  findMergePair,
+  isPairInSync,
+  sharesSourceFile,
+} from "../../components/editor/mediaLinkEdits";
 
 interface LinkMenuItem {
   label: string;
   shortcut?: string;
   destructive?: boolean;
+  disabledReason?: string;
   run: () => void;
 }
 
@@ -15,6 +22,22 @@ const keyOf = (el: TimelineElement) => el.key ?? el.id;
 
 const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();
 
+function loneSameFilePartner(
+  element: TimelineElement,
+  elements: readonly TimelineElement[],
+): TimelineElement | null {
+  const opposite = { video: "audio", audio: "video" }[tagOf(element)];
+  if (!opposite || element.link) return null;
+  const candidates = elements.filter(
+    (el) =>
+      !el.link &&
+      tagOf(el) === opposite &&
+      el.track !== element.track &&
+      sharesSourceFile([element, el]),
+  );
+  return candidates.length === 1 ? (candidates[0] ?? null) : null;
+}
+
 function partnerSuffix(element: TimelineElement, others: readonly TimelineElement[]): string {
   const partners = others.filter((el) => keyOf(el) !== keyOf(element));
   const [partner] = partners;
@@ -23,6 +46,26 @@ function partnerSuffix(element: TimelineElement, others: readonly TimelineElemen
   return pair === "audio+video" ? ` ${tagOf(partner)}` : "";
 }
 
+function linkItem(
+  element: TimelineElement,
+  elements: readonly TimelineElement[],
+  selected: TimelineElement[],
+  selectedKeys: ReadonlySet<string>,
+  onLinkEdit: (edit: TimelineLinkEdit) => unknown,
+): LinkMenuItem | null {
+  const selectedPair = canLinkPair(selected) && selectedKeys.has(keyOf(element));
+  const soleSelection = selected.every((el) => keyOf(el) === keyOf(element));
+  const partner = !selectedPair && soleSelection ? loneSameFilePartner(element, elements) : null;
+  const linkPair = selectedPair ? selected : partner ? [element, partner] : null;
+  if (!linkPair) return null;
+  const suffix = partnerSuffix(element, linkPair);
+  return {
+    label: `Link${suffix && ` to${suffix}`}`,
+    ...(selectedPair ? { shortcut: "⌘L" } : {}),
+    run: () => onLinkEdit({ kind: "link", elements: linkPair }),
+  };
+}
+
 /** The link-model items for a clip, in wireframe order (detach · unlink/link · merge · delete-one). */
 export function resolveLinkMenuItems(input: {
   element: TimelineElement;
@@ -50,17 +93,15 @@ export function resolveLinkMenuItems(input: {
       shortcut: "⌘L",
       run: () => onLinkEdit({ kind: "unlink", elements: members }),
     });
-  } else if (canLinkPair(selected) && selectedKeys.has(keyOf(element))) {
-    items.push({
-      label: `Link${partnerSuffix(element, selected) && ` to${partnerSuffix(element, selected)}`}`,
-      shortcut: "⌘L",
-      run: () => onLinkEdit({ kind: "link", elements: selected }),
-    });
+  } else {
+    const link = linkItem(element, elements, selected, selectedKeys, onLinkEdit);
+    if (link) items.push(link);
   }
   const pair = findMergePair(element, elements);
   if (pair) {
     items.push({
       label: "Merge audio back into video",
+      disabledReason: isPairInSync(pair.video, pair.audio) ? undefined : "Move into Sync first",
       run: () => onLinkEdit({ kind: "merge", ...pair }),
     });
   }
@@ -102,8 +143,12 @@ export function ClipMenuLinkItems({
           key={item.label}
           type="button"
           role="menuitem"
-          className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden cursor-pointer hover:bg-neutral-800 focus-visible:bg-neutral-800 ${
-            item.destructive ? "text-red-400" : "text-neutral-300"
+          disabled={item.disabledReason !== undefined}
+          title={item.disabledReason}
+          className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden ${
+            item.disabledReason !== undefined
+              ? "text-neutral-600 cursor-not-allowed"
+              : `cursor-pointer hover:bg-neutral-800 focus-visible:bg-neutral-800 ${item.destructive ? "text-red-400" : "text-neutral-300"}`
           }`}
           onClick={() => {
             item.run();

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

@@ -2,7 +2,7 @@
 
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
 import { useCropPresetBarStore } from "../../components/editor/cropPresetStore";
@@ -15,7 +15,10 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
 
 let root: Root | null = null;
 
+beforeEach(() => vi.useFakeTimers());
+
 afterEach(() => {
+  vi.useRealTimers();
   act(() => root?.unmount());
   root = null;
   document.body.innerHTML = "";
@@ -31,7 +34,14 @@ const video: TimelineElement = {
   hasAudio: true,
 };
 
-function renderItems(group: ClipMenuToolGroup, element: TimelineElement, currentTime = 2) {
+function renderItems(
+  group: ClipMenuToolGroup,
+  element: TimelineElement,
+  currentTime = 2,
+  withLive = true,
+) {
+  const setLive = vi.fn((_el: TimelineElement, _attr: string, _value: string | null) => undefined);
+  const revertLive = vi.fn((_el: TimelineElement, _attr: string) => undefined);
   const setQuiet = vi.fn(
     async (_el: TimelineElement, _attr: string, _value: string | null, _label: string) => undefined,
   );
@@ -42,7 +52,15 @@ function renderItems(group: ClipMenuToolGroup, element: TimelineElement, current
   root = createRoot(host);
   act(() => {
     root?.render(
-      <TimelineEditProvider value={{ onSetElementAttributeQuiet: setQuiet, onFreezeFrame: freeze }}>
+      <TimelineEditProvider
+        value={{
+          onSetElementAttributeQuiet: setQuiet,
+          onFreezeFrame: freeze,
+          ...(withLive
+            ? { onSetElementAttributeLive: setLive, onRevertElementAttributeLive: revertLive }
+            : {}),
+        }}
+      >
         <ClipMenuToolItems
           group={group}
           element={element}
@@ -52,7 +70,7 @@ function renderItems(group: ClipMenuToolGroup, element: TimelineElement, current
       </TimelineEditProvider>,
     );
   });
-  return { setQuiet, onClose, freeze };
+  return { setQuiet, onClose, freeze, setLive, revertLive };
 }
 
 function openSubmenu(label: string) {
@@ -136,4 +154,112 @@ describe("ClipMenuToolItems", () => {
     renderItems("time", { ...video, tag: "img" });
     expect(document.body.textContent).toBe("");
   });
+
+  describe("Look hover preview", () => {
+    function option(text: string) {
+      const found = Array.from(
+        document.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]'),
+      ).find((button) => button.textContent?.endsWith(text));
+      if (!found) throw new Error(`no option ${text}`);
+      return found;
+    }
+    const enter = (text: string) =>
+      option(text).dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+    const hover = (text: string) => {
+      act(() => {
+        enter(text);
+        vi.advanceTimersByTime(100);
+      });
+    };
+    const leave = () => {
+      const wrapper = document.querySelector('[role="menu"]')?.parentElement;
+      act(() => {
+        wrapper?.dispatchEvent(
+          new MouseEvent("mouseout", { bubbles: true, relatedTarget: document.body }),
+        );
+      });
+    };
+
+    it("hover applies the look live after the debounce, without saving", () => {
+      const { setLive, setQuiet } = renderItems("picture", video);
+      openSubmenu("Look");
+      act(() => {
+        enter("Warm daylight");
+        vi.advanceTimersByTime(40);
+      });
+      expect(setLive).not.toHaveBeenCalled();
+      act(() => vi.advanceTimersByTime(60));
+      expect(setLive).toHaveBeenCalledWith(
+        video,
+        "data-color-grading",
+        '{"preset":"warm-daylight","intensity":1}',
+      );
+      expect(setQuiet).not.toHaveBeenCalled();
+    });
+
+    it("opening the submenu by click does not preview the auto-focused first option", () => {
+      const { setLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      act(() => vi.advanceTimersByTime(200));
+      expect(setLive).not.toHaveBeenCalled();
+    });
+
+    it("keyboard focus previews and None previews no look", () => {
+      const { setLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      act(() => {
+        option("None").dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+        vi.advanceTimersByTime(100);
+      });
+      expect(setLive).toHaveBeenCalledWith(video, "data-color-grading", null);
+    });
+
+    it("leaving the submenu reverts to the saved look", () => {
+      const { revertLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      hover("Warm daylight");
+      leave();
+      expect(revertLive).toHaveBeenCalledWith(video, "data-color-grading");
+    });
+
+    it("leaving before the debounce fires never previews or reverts", () => {
+      const { setLive, revertLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      act(() => enter("Warm daylight"));
+      leave();
+      act(() => vi.advanceTimersByTime(200));
+      expect(setLive).not.toHaveBeenCalled();
+      expect(revertLive).not.toHaveBeenCalled();
+    });
+
+    it("clicking commits once and does not revert afterwards", () => {
+      const { setQuiet, revertLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      hover("Warm daylight");
+      act(() => option("Warm daylight").click());
+      act(() => root?.unmount());
+      root = null;
+      expect(setQuiet).toHaveBeenCalledTimes(1);
+      expect(revertLive).not.toHaveBeenCalled();
+    });
+
+    it("closing the menu while previewing reverts", () => {
+      const { revertLive } = renderItems("picture", video);
+      openSubmenu("Look");
+      hover("Warm daylight");
+      act(() => root?.unmount());
+      root = null;
+      expect(revertLive).toHaveBeenCalledWith(video, "data-color-grading");
+    });
+
+    it("does nothing when the host has no live callbacks", () => {
+      const { setQuiet } = renderItems("picture", video, 2, false);
+      openSubmenu("Look");
+      expect(() => {
+        hover("Warm daylight");
+        leave();
+      }).not.toThrow();
+      expect(setQuiet).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/player/components/clipMenuToolItems.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState, type KeyboardEvent } from "react";
+import { useEffect, useRef, useState, type KeyboardEvent } from "react";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_COLOR_GRADING_ATTR } from "@hyperframes/core/color-grading";
 import type { TimelineElement } from "../store/playerStore";
@@ -30,6 +30,47 @@ const ROW_CLASS =
 const DISABLED_ROW_CLASS =
   "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none text-neutral-600 cursor-not-allowed";
 const SUBMENU_WIDTH = 170;
+const HOVER_PREVIEW_DELAY_MS = 80;
+
+interface HoverPreview {
+  apply: (id: string | null) => void;
+  clear: () => void;
+}
+
+function useHoverPreview(preview: HoverPreview | undefined) {
+  const previewRef = useRef(preview);
+  previewRef.current = preview;
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const activeRef = useRef(false);
+
+  const cancelTimer = () => {
+    if (timerRef.current === null) return;
+    clearTimeout(timerRef.current);
+    timerRef.current = null;
+  };
+  const end = () => {
+    cancelTimer();
+    if (!activeRef.current) return;
+    activeRef.current = false;
+    previewRef.current?.clear();
+  };
+  const settle = () => {
+    cancelTimer();
+    activeRef.current = false;
+  };
+  const start = (id: string | null) => {
+    if (!previewRef.current) return;
+    cancelTimer();
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      activeRef.current = true;
+      previewRef.current?.apply(id);
+    }, HOVER_PREVIEW_DELAY_MS);
+  };
+
+  useEffect(() => end, []);
+  return { start, end, settle };
+}
 
 interface ChoiceSection {
   heading?: string;
@@ -48,22 +89,36 @@ function ChoiceSubmenu({
   sections,
   activeId,
   onPick,
+  preview,
 }: {
   label: string;
   sections: readonly ChoiceSection[];
   activeId: string | null;
   onPick: (id: string | null) => void;
+  preview?: HoverPreview;
 }) {
   const [open, setOpen] = useState(false);
   const [flipLeft, setFlipLeft] = useState(false);
   const rowRef = useRef<HTMLButtonElement | null>(null);
   const submenuRef = useRef<HTMLDivElement | null>(null);
+  const hover = useHoverPreview(preview);
+  const openingFocusRef = useRef(false);
+
+  const hideSubmenu = () => {
+    hover.end();
+    setOpen(false);
+  };
 
   const show = (focusFirst: boolean) => {
     const rect = rowRef.current?.getBoundingClientRect();
     setFlipLeft(rect ? rect.right + SUBMENU_WIDTH > window.innerWidth : false);
     setOpen(true);
-    if (focusFirst) requestAnimationFrame(() => focusSibling(submenuRef.current, 1));
+    if (!focusFirst) return;
+    openingFocusRef.current = true;
+    requestAnimationFrame(() => {
+      focusSibling(submenuRef.current, 1);
+      openingFocusRef.current = false;
+    });
   };
 
   const onSubmenuKeyDown = (event: KeyboardEvent) => {
@@ -74,7 +129,7 @@ function ChoiceSubmenu({
     } else if (event.key === "ArrowLeft") {
       event.preventDefault();
       event.stopPropagation();
-      setOpen(false);
+      hideSubmenu();
       rowRef.current?.focus();
     }
   };
@@ -86,7 +141,15 @@ function ChoiceSubmenu({
       role="menuitemradio"
       aria-checked={activeId === id}
       className={ROW_CLASS}
-      onClick={() => onPick(id)}
+      onClick={() => {
+        hover.settle();
+        onPick(id);
+      }}
+      onMouseEnter={() => hover.start(id)}
+      onFocus={() => {
+        if (openingFocusRef.current) openingFocusRef.current = false;
+        else hover.start(id);
+      }}
     >
       <span className="flex items-center gap-1.5">
         <span aria-hidden="true" className="w-3 text-center">
@@ -98,7 +161,7 @@ function ChoiceSubmenu({
   );
 
   return (
-    <div className="relative" onMouseEnter={() => show(false)} onMouseLeave={() => setOpen(false)}>
+    <div className="relative" onMouseEnter={() => show(false)} onMouseLeave={hideSubmenu}>
       <button
         ref={rowRef}
         type="button"
@@ -182,7 +245,8 @@ export function ClipMenuToolItems(props: ClipMenuToolItemsProps) {
 }
 
 function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsProps) {
-  const { onSetElementAttributeQuiet } = useTimelineEditContextOptional();
+  const { onSetElementAttributeQuiet, onSetElementAttributeLive, onRevertElementAttributeLive } =
+    useTimelineEditContextOptional();
   const state = useClipToolState(element);
   const openCropBar = useCropPresetBarStore((s) => s.open);
   if (!onSetElementAttributeQuiet) return null;
@@ -209,6 +273,14 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr
   }
 
   if (!isPictureClip(state.tag)) return null;
+  const lookPreview =
+    onSetElementAttributeLive && onRevertElementAttributeLive
+      ? {
+          apply: (id: string | null) =>
+            onSetElementAttributeLive(element, HF_COLOR_GRADING_ATTR, lookAttrValue(id)),
+          clear: () => onRevertElementAttributeLive(element, HF_COLOR_GRADING_ATTR),
+        }
+      : undefined;
   return (
     <>
       <ChoiceSubmenu
@@ -216,6 +288,7 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr
         sections={LOOK_SECTIONS}
         activeId={activeLook(state.colorGrading)}
         onPick={(id) => write(HF_COLOR_GRADING_ATTR, lookAttrValue(id), "Look")}
+        preview={lookPreview}
       />
       <button
         type="button"

package/src/player/components/clipPeakMap.ts

@@ -0,0 +1,46 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
+import { resolvePreviewRelative } from "../../utils/previewRelativePath";
+import type { TimelineElement } from "../store/timelineElement";
+import { clipSourcePeak, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";
+import { encodePreviewPath, resolveMediaPreviewUrl } from "./thumbnailUtils";
+
+const peakMapRequests = new Map<string, Promise<PeakMap | null>>();
+
+/** One fetch per peak-map URL per session; a failed or malformed answer reads as null. */
+export function loadPeakMap(url: string): Promise<PeakMap | null> {
+  const pending = peakMapRequests.get(url);
+  if (pending) return pending;
+  const request = fetch(url)
+    .then((res) => (res.ok ? res.json() : null))
+    .then((body: unknown) => (isPeakMap(body) ? body : null))
+    .catch(() => null);
+  peakMapRequests.set(url, request);
+  return request;
+}
+
+/** The studio-server `/peaks/*` URL for a clip's project media, or undefined for outside media. */
+export function clipPeaksUrl(src: string | undefined, projectId: string): string | undefined {
+  const origin = window.location.origin;
+  const relative = resolvePreviewRelative(
+    resolveMediaPreviewUrl(src ?? "", projectId, origin),
+    projectId,
+    origin,
+  );
+  return relative
+    ? buildProjectApiPath(projectId, `/peaks/${encodePreviewPath(relative)}`)
+    : undefined;
+}
+
+export function clipSourceWindow(el: TimelineElement): ClipSourceWindow {
+  return { mediaStart: el.playbackStart ?? 0, sourceSpan: el.duration * (el.playbackRate ?? 1) };
+}
+
+/** The clip's source peak, linear, over the part it plays; null when it cannot be measured. */
+export async function measureClipSourcePeak(
+  el: TimelineElement,
+  projectId: string,
+): Promise<number | null> {
+  const url = clipPeaksUrl(el.src, projectId);
+  const map = url ? await loadPeakMap(url) : null;
+  return map ? clipSourcePeak(map, clipSourceWindow(el)) : null;
+}