From a1a6fb6b3cdca7c2c81f2ac21f95c82ff5d4b4ad Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 10:14:40 -0700
Subject: [PATCH 01/20] feat(studio): show clip speed in the clip name as
 [150%] or [ramp]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../player/components/TimelineClip.test.tsx   | 41 +++++++++++++++++++
 .../src/player/components/TimelineClip.tsx    |  3 +-
 .../player/components/clipToolAttrs.test.ts   | 15 +++++++
 .../src/player/components/clipToolAttrs.ts    | 11 +++++
 4 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/packages/studio/src/player/components/TimelineClip.test.tsx b/packages/studio/src/player/components/TimelineClip.test.tsx
index 3c4786be67..8a9ebe7f8c 100644
--- a/packages/studio/src/player/components/TimelineClip.test.tsx
+++ b/packages/studio/src/player/components/TimelineClip.test.tsx
@@ -133,6 +133,47 @@ describe("TimelineClip", () => {
     act(() => root.unmount());
   });
 
+  it("names a speed-changed clip like Premiere: [150%] for a constant rate, [ramp] for a lane", () => {
+    const fast = renderClip({
+      element: {
+        id: "a",
+        label: "Hero",
+        tag: "video",
+        start: 0,
+        duration: 2,
+        track: 0,
+        playbackRate: 1.5,
+      },
+    });
+    expect(fast.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [150%]");
+    act(() => fast.root.unmount());
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [
+        {
+          target: "rate",
+          points: [
+            { t: 0, v: 0.5 },
+            { t: 1, v: 1 },
+          ],
+        },
+      ],
+    });
+    const ramp = renderClip({
+      element: {
+        id: "b",
+        label: "Hero",
+        tag: "video",
+        start: 0,
+        duration: 2,
+        track: 0,
+        automation,
+      },
+    });
+    expect(ramp.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [ramp]");
+    act(() => ramp.root.unmount());
+  });
+
   it("drops the label chip under 60px even when the clip is selected", () => {
     const { host, root } = renderClip({
       element: { id: "fx", label: "FX", tag: "div", start: 0, duration: 1, track: 0 },
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 2b63755c05..2558e269cb 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -14,6 +14,7 @@ import { rendersWaveform } from "./AudioWaveform";
 import { ClipBadges } from "./ClipBadges";
 import { linkLabelColor } from "./linkLabelColor";
 import { OutOfSyncBadge } from "./OutOfSyncBadge";
+import { clipSpeedSuffix } from "./clipToolAttrs";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -68,7 +69,7 @@ export const TimelineClip = memo(function TimelineClip({
   const leftPx = el.start * pps;
   const widthPx = Math.max(el.duration * pps, 4);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
-  const displayLabel = el.label || el.id || el.tag;
+  const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;
   const ladder = clipWidthLadder(widthPx);
   const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);
   const showLabel = ladder === "labeled";
diff --git a/packages/studio/src/player/components/clipToolAttrs.test.ts b/packages/studio/src/player/components/clipToolAttrs.test.ts
index d54d061df8..143bda89c2 100644
--- a/packages/studio/src/player/components/clipToolAttrs.test.ts
+++ b/packages/studio/src/player/components/clipToolAttrs.test.ts
@@ -5,6 +5,7 @@ import {
   activeLook,
   activeVoicePreset,
   chainWithVoicePreset,
+  clipSpeedSuffix,
   hasCrop,
   isDucked,
   lookAttrValue,
@@ -159,3 +160,17 @@ describe("readClipBadges", () => {
     expect(hidden.map((b) => b.label)).toEqual(["60%"]);
   });
 });
+
+describe("clipSpeedSuffix", () => {
+  it("shows a constant speed as a percentage and hides 100%", () => {
+    expect(clipSpeedSuffix(1.5, null)).toBe(" [150%]");
+    expect(clipSpeedSuffix(0.35, null)).toBe(" [35%]");
+    expect(clipSpeedSuffix(1, null)).toBe("");
+    expect(clipSpeedSuffix(undefined, null)).toBe("");
+  });
+
+  it("shows a rate lane as a ramp, whatever the base rate", () => {
+    expect(clipSpeedSuffix(2, rampAutomation)).toBe(" [ramp]");
+    expect(clipSpeedSuffix(1, rampAutomation)).toBe(" [ramp]");
+  });
+});
diff --git a/packages/studio/src/player/components/clipToolAttrs.ts b/packages/studio/src/player/components/clipToolAttrs.ts
index e7418b7073..c9e05d576b 100644
--- a/packages/studio/src/player/components/clipToolAttrs.ts
+++ b/packages/studio/src/player/components/clipToolAttrs.ts
@@ -117,6 +117,17 @@ function hasRateRamp(rawAutomation: string | null | undefined): boolean {
   return parseRateLane(rawAutomation) !== null;
 }
 
+/** Premiere's speed cue on the clip name: ` [ramp]` under a rate lane, else ` [150%]` off 100%. */
+export function clipSpeedSuffix(
+  playbackRate: number | null | undefined,
+  rawAutomation: string | null | undefined,
+): string {
+  if (hasRateRamp(rawAutomation)) return " [ramp]";
+  const rate = playbackRate ?? 1;
+  if (!Number.isFinite(rate) || Math.abs(rate - 1) < 0.005) return "";
+  return ` [${Math.round(rate * 100)}%]`;
+}
+
 const ZERO_INSET = /^inset\(\s*0(px|%)?\s*\)$/i;
 
 export function hasCrop(clipPath: string | null | undefined): boolean {

From b1fac418dbfc0b7b26781d45b6ed3e7721ba7668 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 10:35:31 -0700
Subject: [PATCH 02/20] feat(studio): one fx badge per clip replaces the
 per-tool and link badges

Grey with no effects, white with any. The tooltip lists look, voice, other
fx, crop and ducking; a click opens the clip menu. The volume badge stays
when volume is off 100%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/player/components/ClipBadges.test.tsx | 40 +++++++--
 .../src/player/components/ClipBadges.tsx      | 68 ++++++++-------
 .../src/player/components/TimelineClip.tsx    |  2 +-
 .../player/components/clipToolAttrs.test.ts   | 85 ++++++++++---------
 .../src/player/components/clipToolAttrs.ts    | 83 +++++++++---------
 .../src/player/components/useClipToolState.ts |  5 --
 6 files changed, 151 insertions(+), 132 deletions(-)

diff --git a/packages/studio/src/player/components/ClipBadges.test.tsx b/packages/studio/src/player/components/ClipBadges.test.tsx
index e03e8c6617..57a53fc813 100644
--- a/packages/studio/src/player/components/ClipBadges.test.tsx
+++ b/packages/studio/src/player/components/ClipBadges.test.tsx
@@ -2,7 +2,7 @@
 
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { usePreviewIframeStore } from "../store/previewIframeStore";
 import { ClipBadges } from "./ClipBadges";
@@ -54,29 +54,53 @@ function mountPreview(html: string): Document {
 }
 
 describe("ClipBadges", () => {
-  it("renders nothing for an untouched clip", () => {
+  it("shows a grey fx badge and no volume on an untouched clip", () => {
     render(talk);
-    expect(document.querySelector("[data-testid='clip-badges']")).toBeNull();
+    expect(labels()).toEqual(["fx:fx"]);
+    const fx = document.querySelector("[data-badge='fx']");
+    expect(fx?.getAttribute("data-fx-active")).toBe("false");
+    expect(fx?.getAttribute("title")).toBe("No effects");
   });
 
   it("falls back to the store's volume without a preview", () => {
     render({ ...talk, volume: 1.8 });
-    expect(labels()).toEqual(["volume:180%"]);
+    expect(labels()).toEqual(["volume:180%", "fx:fx"]);
   });
 
-  it("reads the live node and follows an agent's attribute edit", async () => {
+  it("lights the fx badge from the live node, lists the effects, and shows no link badge", async () => {
     const doc = mountPreview(
       `<video id="talk" data-has-audio="true" data-link="talk-pair" style="clip-path: inset(10px)"></video>`,
     );
     render(talk);
-    expect(labels()).toEqual(["link:🔗", "crop:Crop"]);
+    const fx = () => document.querySelector("[data-badge='fx']");
+    expect(labels()).toEqual(["fx:fx"]);
+    expect(fx()?.getAttribute("data-fx-active")).toBe("true");
+    expect(fx()?.getAttribute("title")).toBe("Crop");
     const node = doc.getElementById("talk");
     await act(async () => {
       node?.setAttribute("data-color-grading", '{"preset":"warm-daylight","intensity":1}');
       node?.setAttribute("data-volume", "0.6");
       await new Promise((resolve) => setTimeout(resolve, 0));
     });
-    expect(labels()).toEqual(["link:🔗", "look:Warm daylight", "crop:Crop", "more:+1"]);
-    expect(document.querySelector("[data-badge='more']")?.getAttribute("title")).toBe("60%");
+    expect(labels()).toEqual(["volume:60%", "fx:fx"]);
+    expect(fx()?.getAttribute("title")).toBe("Look: Warm daylight · Crop");
+  });
+
+  it("opens the clip menu from the fx badge without reaching the clip", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const onOpenMenu = vi.fn();
+    const onClipClick = vi.fn();
+    root = createRoot(host);
+    act(() =>
+      root?.render(
+        <div onClick={onClipClick}>
+          <ClipBadges el={talk} onOpenMenu={onOpenMenu} />
+        </div>,
+      ),
+    );
+    act(() => document.querySelector<HTMLElement>("[data-badge='fx']")?.click());
+    expect(onOpenMenu).toHaveBeenCalledTimes(1);
+    expect(onClipClick).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/studio/src/player/components/ClipBadges.tsx b/packages/studio/src/player/components/ClipBadges.tsx
index 9792ae8039..3e3c514b9a 100644
--- a/packages/studio/src/player/components/ClipBadges.tsx
+++ b/packages/studio/src/player/components/ClipBadges.tsx
@@ -1,6 +1,6 @@
-import { memo } from "react";
+import { memo, type MouseEvent } from "react";
 import type { TimelineElement } from "../store/playerStore";
-import { readClipBadges, splitVisibleBadges, type ClipBadge } from "./clipToolAttrs";
+import { clipVolumeBadge, readClipEffects } from "./clipToolAttrs";
 import { useClipToolState } from "./useClipToolState";
 
 function SpeakerGlyph({ muted }: { muted: boolean }) {
@@ -21,47 +21,53 @@ function SpeakerGlyph({ muted }: { muted: boolean }) {
   );
 }
 
-function BadgeContent({ badge }: { badge: ClipBadge }) {
-  if (badge.kind === "link") return <span aria-hidden="true">🔗</span>;
-  if (badge.kind === "volume") {
-    const muted = badge.label === "Muted";
-    return (
-      <>
-        <SpeakerGlyph muted={muted} />
-        {muted ? null : <span>{badge.label}</span>}
-      </>
-    );
-  }
-  return <span>{badge.label}</span>;
-}
-
 const BADGE_CLASS =
-  "inline-flex items-center gap-0.5 rounded-[3px] border border-white/20 bg-black/55 px-1 text-[9px] leading-[14px] text-white/90 whitespace-nowrap";
+  "timeline-clip__badge inline-flex items-center gap-0.5 rounded-[3px] border bg-black/55 px-1 text-[9px] leading-[14px] whitespace-nowrap";
+const FX_ON = "border-white/40 text-white font-semibold";
+const FX_OFF = "border-white/10 text-white/35";
 
-/** What is applied to a clip, read from its attributes: a link badge, then at most two more and `+N`. */
-export const ClipBadges = memo(function ClipBadges({ el }: { el: TimelineElement }) {
+/** Premiere's fx badge — grey with no effects, white with any; hover lists them, click opens the clip menu. */
+export const ClipBadges = memo(function ClipBadges({
+  el,
+  onOpenMenu,
+}: {
+  el: TimelineElement;
+  onOpenMenu?: (event: MouseEvent) => void;
+}) {
   const state = useClipToolState(el);
-  const { visible, hidden } = splitVisibleBadges(readClipBadges(state));
-  if (visible.length === 0) return null;
+  const effects = readClipEffects(state);
+  const volume = clipVolumeBadge(state);
+  const hasEffects = effects.length > 0;
+  const openMenu = (event: MouseEvent) => {
+    event.stopPropagation();
+    onOpenMenu?.(event);
+  };
   return (
     <span
       className="pointer-events-none absolute right-1.5 top-0.5 z-[3] flex gap-1"
       data-testid="clip-badges"
     >
-      {visible.map((badge) => (
-        <span key={badge.kind} className={BADGE_CLASS} title={badge.label} data-badge={badge.kind}>
-          <BadgeContent badge={badge} />
-        </span>
-      ))}
-      {hidden.length > 0 && (
+      {volume && (
         <span
-          className={`${BADGE_CLASS} pointer-events-auto`}
-          title={hidden.map((badge) => badge.label).join(", ")}
-          data-badge="more"
+          className={`${BADGE_CLASS} border-white/20 text-white/90`}
+          title={volume}
+          data-badge="volume"
         >
-          +{hidden.length}
+          <SpeakerGlyph muted={volume === "Muted"} />
+          {volume === "Muted" ? null : <span>{volume}</span>}
         </span>
       )}
+      <span
+        className={`${BADGE_CLASS} pointer-events-auto cursor-pointer ${hasEffects ? FX_ON : FX_OFF}`}
+        title={hasEffects ? effects.join(" · ") : "No effects"}
+        data-badge="fx"
+        data-fx-active={hasEffects ? "true" : "false"}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={openMenu}
+        onContextMenu={openMenu}
+      >
+        fx
+      </span>
     </span>
   );
 });
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 2558e269cb..c5d959c883 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -211,7 +211,7 @@ export const TimelineClip = memo(function TimelineClip({
         </div>
       )}
       {showLabel && <span className="timeline-clip__label">{displayLabel}</span>}
-      {showLabel && !isGestureActor && <ClipBadges el={el} />}
+      {showLabel && !isGestureActor && <ClipBadges el={el} onOpenMenu={onContextMenu} />}
       {!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}
       {showDefaultText && (
         <span className="timeline-clip__timecode">
diff --git a/packages/studio/src/player/components/clipToolAttrs.test.ts b/packages/studio/src/player/components/clipToolAttrs.test.ts
index 143bda89c2..52a2a0da63 100644
--- a/packages/studio/src/player/components/clipToolAttrs.test.ts
+++ b/packages/studio/src/player/components/clipToolAttrs.test.ts
@@ -8,9 +8,9 @@ import {
   clipSpeedSuffix,
   hasCrop,
   isDucked,
+  clipVolumeBadge,
   lookAttrValue,
-  readClipBadges,
-  splitVisibleBadges,
+  readClipEffects,
   type ClipToolState,
 } from "./clipToolAttrs";
 
@@ -99,7 +99,6 @@ const baseState: ClipToolState = {
   colorGrading: null,
   clipPath: null,
   carve: null,
-  link: null,
 };
 
 const rampAutomation = JSON.stringify({
@@ -115,49 +114,51 @@ const rampAutomation = JSON.stringify({
   ],
 });
 
-describe("readClipBadges", () => {
-  it("shows nothing for a plain clip at 100%", () => {
-    expect(readClipBadges(baseState)).toEqual([]);
-  });
-
-  it("lists every applied tool in the wireframe's order", () => {
-    const labels = readClipBadges({
-      ...baseState,
-      volume: 1.8,
-      fxChain: chainWithVoicePreset(null, "voice-clean"),
-      automation: rampAutomation,
-      colorGrading: lookAttrValue("warm-daylight"),
-      clipPath: "inset(0px 20px)",
-      carve: "{}",
-      link: "talk",
-    }).map((b) => b.label);
-    expect(labels).toEqual([
-      "Linked",
-      "Warm daylight",
-      "Voice: Clean",
-      "Ramp",
-      "Crop",
-      "Ducked",
-      "180%",
-    ]);
+describe("readClipEffects", () => {
+  it("lists nothing for a plain clip, so the fx badge stays grey", () => {
+    expect(readClipEffects(baseState)).toEqual([]);
+    expect(readClipEffects({ ...baseState, automation: rampAutomation, volume: 1.8 })).toEqual([]);
+  });
+
+  it("lists every applied effect in the tooltip's order", () => {
+    expect(
+      readClipEffects({
+        ...baseState,
+        fxChain: chainWithVoicePreset(null, "voice-clean"),
+        colorGrading: lookAttrValue("warm-daylight"),
+        clipPath: "inset(0px 20px)",
+        carve: "{}",
+      }),
+    ).toEqual(["Look: Warm daylight", "Voice: Clean", "Crop", "Ducked"]);
+  });
+
+  it("names a hand-added effect and skips disabled and carve-generated nodes", () => {
+    const chain = serializeAudioFxChain({
+      version: 1,
+      nodes: [
+        { id: "a", type: "highpass", enabled: true, params: { frequency: 80 } },
+        { id: "b", type: "gain", enabled: false, params: {} },
+        { id: "c", type: "gain", enabled: true, fromCarve: true, params: {} },
+      ],
+    });
+    const effects = readClipEffects({ ...baseState, fxChain: chain });
+    expect(effects).toHaveLength(1);
+    expect(effects[0]).not.toBe("highpass");
   });
 
-  it("badges a muted audio clip but not muted b-roll", () => {
-    expect(readClipBadges({ ...baseState, tag: "audio", muted: true })[0]?.label).toBe("Muted");
-    expect(readClipBadges({ ...baseState, hasSound: false, muted: true })).toEqual([]);
+  it("reads a hand-made grading without a menu preset as a Look", () => {
+    expect(readClipEffects({ ...baseState, colorGrading: '{"adjust":{"contrast":0.2}}' })).toEqual([
+      "Look",
+    ]);
   });
+});
 
-  it("caps at two visible badges plus the link badge", () => {
-    const badges = readClipBadges({
-      ...baseState,
-      link: "talk",
-      colorGrading: lookAttrValue("mono-clean"),
-      clipPath: "inset(5px)",
-      volume: 0.6,
-    });
-    const { visible, hidden } = splitVisibleBadges(badges);
-    expect(visible.map((b) => b.label)).toEqual(["Linked", "Mono", "Crop"]);
-    expect(hidden.map((b) => b.label)).toEqual(["60%"]);
+describe("clipVolumeBadge", () => {
+  it("shows volume off 100% and Muted only on a clip with sound", () => {
+    expect(clipVolumeBadge({ ...baseState, volume: 1.8 })).toBe("180%");
+    expect(clipVolumeBadge(baseState)).toBeNull();
+    expect(clipVolumeBadge({ ...baseState, tag: "audio", muted: true })).toBe("Muted");
+    expect(clipVolumeBadge({ ...baseState, hasSound: false, muted: true })).toBeNull();
   });
 });
 
diff --git a/packages/studio/src/player/components/clipToolAttrs.ts b/packages/studio/src/player/components/clipToolAttrs.ts
index c9e05d576b..088412bbce 100644
--- a/packages/studio/src/player/components/clipToolAttrs.ts
+++ b/packages/studio/src/player/components/clipToolAttrs.ts
@@ -4,11 +4,13 @@
  */
 
 import {
+  getAudioFxDef,
   parseAudioFxChain,
   serializeAudioFxChain,
   type HfAudioFxChain,
+  type HfAudioFxNode,
 } from "@hyperframes/core/audio-fx";
-import { activeAudioFxPresetIds } from "@hyperframes/core/audio-fx-presets";
+import { activeAudioFxPresetIds, getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";
 import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
 import { parseRateLane } from "@hyperframes/core/speed-ramp";
 import { applyPresetToChain } from "../../components/editor/useApplyAudioFxPreset";
@@ -135,13 +137,6 @@ export function hasCrop(clipPath: string | null | undefined): boolean {
   return value !== "" && value !== "none" && !ZERO_INSET.test(value);
 }
 
-export type ClipBadgeKind = "link" | "look" | "voice" | "ramp" | "crop" | "ducked" | "volume";
-
-export interface ClipBadge {
-  kind: ClipBadgeKind;
-  label: string;
-}
-
 /** What a clip's attributes say is applied; the element's own attributes, as read off its node. */
 export interface ClipToolState {
   tag: string;
@@ -153,46 +148,44 @@ export interface ClipToolState {
   colorGrading: string | null;
   clipPath: string | null;
   carve: string | null;
-  link: string | null;
 }
 
-function volumeBadge(state: ClipToolState): ClipBadge | null {
-  const isAudio = state.tag === "audio";
-  if (!isAudio && !state.hasSound) return null;
-  if (state.muted) return { kind: "volume", label: "Muted" };
+/** The volume badge text, or null at 100% and on clips with no sound. */
+export function clipVolumeBadge(state: ClipToolState): string | null {
+  if (state.tag !== "audio" && !state.hasSound) return null;
+  if (state.muted) return "Muted";
   const volume = state.volume ?? 1;
   if (Math.abs(volume - 1) < 0.005) return null;
-  return { kind: "volume", label: `${Math.round(volume * 100)}%` };
-}
-
-/** Badges in the wireframe's order: look, voice, ramp, crop, ducked, volume. The link badge leads. */
-export function readClipBadges(state: ClipToolState): ClipBadge[] {
-  const look = lookLabel(activeLook(state.colorGrading));
-  const voice = voicePresetLabel(activeVoicePreset(state.fxChain));
-  const volume = volumeBadge(state);
-  const badges: Array<ClipBadge | null> = [
-    state.link ? { kind: "link", label: "Linked" } : null,
-    look ? { kind: "look", label: look } : null,
-    voice ? { kind: "voice", label: `Voice: ${voice}` } : null,
-    hasRateRamp(state.automation) ? { kind: "ramp", label: "Ramp" } : null,
-    hasCrop(state.clipPath) ? { kind: "crop", label: "Crop" } : null,
-    isDucked(state.carve) ? { kind: "ducked", label: "Ducked" } : null,
-    volume,
+  return `${Math.round(volume * 100)}%`;
+}
+
+function lookEffect(rawGrading: string | null): string | null {
+  const grading = normalizeHfColorGrading(parseJson(rawGrading));
+  if (!grading) return null;
+  const label = lookLabel(grading.preset ?? null);
+  return label ? `Look: ${label}` : "Look";
+}
+
+function presetEffect(presetId: string): string {
+  const voice = voicePresetLabel(presetId);
+  return voice ? `Voice: ${voice}` : (getAudioFxPreset(presetId)?.label ?? presetId);
+}
+
+function chainNodeEffect(node: HfAudioFxNode): string | null {
+  if (node.enabled === false || node.fromCarve) return null;
+  if (node.fromPreset) return presetEffect(node.fromPreset);
+  if (node.fromEq) return "EQ";
+  if (node.fromLeveller) return "Leveller";
+  return node.label ?? getAudioFxDef(node.type)?.label ?? node.type;
+}
+
+/** Every effect on the clip, in the fx badge tooltip's order; empty means a grey badge. */
+export function readClipEffects(state: ClipToolState): string[] {
+  const effects: Array<string | null> = [
+    lookEffect(state.colorGrading),
+    ...parseChainOrEmpty(state.fxChain).nodes.map(chainNodeEffect),
+    hasCrop(state.clipPath) ? "Crop" : null,
+    isDucked(state.carve) ? "Ducked" : null,
   ];
-  return badges.filter((badge): badge is ClipBadge => badge !== null);
-}
-
-const MAX_VISIBLE_BADGES = 2;
-
-/** The link badge is always shown; the rest cap at two, then `+N`. */
-export function splitVisibleBadges(badges: readonly ClipBadge[]): {
-  visible: ClipBadge[];
-  hidden: ClipBadge[];
-} {
-  const link = badges.filter((badge) => badge.kind === "link");
-  const rest = badges.filter((badge) => badge.kind !== "link");
-  return {
-    visible: [...link, ...rest.slice(0, MAX_VISIBLE_BADGES)],
-    hidden: rest.slice(MAX_VISIBLE_BADGES),
-  };
+  return [...new Set(effects.filter((effect): effect is string => effect !== null))];
 }
diff --git a/packages/studio/src/player/components/useClipToolState.ts b/packages/studio/src/player/components/useClipToolState.ts
index 364ce9585e..b99c91fcc7 100644
--- a/packages/studio/src/player/components/useClipToolState.ts
+++ b/packages/studio/src/player/components/useClipToolState.ts
@@ -11,14 +11,11 @@ import { committedClipPath } from "../../components/editor/cropPresetStore";
 import { isAudibleVideoNode } from "../lib/timelineElementHelpers";
 import type { ClipToolState } from "./clipToolAttrs";
 
-const LINK_ATTR = "data-link";
-
 const WATCHED_ATTRS = [
   HF_AUDIO_FX_ATTR,
   HF_AUDIO_AUTOMATION_ATTR,
   HF_AUDIO_CARVE_ATTR,
   HF_COLOR_GRADING_ATTR,
-  LINK_ATTR,
   "data-volume",
   "data-has-audio",
   "muted",
@@ -42,7 +39,6 @@ function toolStateFromNode(node: Element): ClipToolState {
     colorGrading: node.getAttribute(HF_COLOR_GRADING_ATTR),
     clipPath: committedClipPath(node),
     carve: node.getAttribute(HF_AUDIO_CARVE_ATTR),
-    link: node.getAttribute(LINK_ATTR),
   };
 }
 
@@ -58,7 +54,6 @@ function toolStateFromElement(el: TimelineElement): ClipToolState {
     colorGrading: null,
     clipPath: null,
     carve: null,
-    link: null,
   };
 }
 

From 89440bdadcd50d012bc9b7d8663de48ba64f80ac Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 11:03:03 -0700
Subject: [PATCH 03/20] feat(studio): premiere-style audio gain dialog on G

Set Gain to, Adjust Gain by, Normalize Max Peak to, Normalize All Peaks to
and Normalize loudness to -16 LUFS, with the selection's peak amplitude read
from the peak map. Writes data-volume on every selected clip with sound as
one undo step. The clip menu's Normalize loudness becomes Audio Gain... (G).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../nle/useTimelineEditCallbacks.ts           |   2 +
 .../src/contexts/TimelineEditContext.tsx      |   1 +
 .../studio/src/hooks/appHotkeysDispatch.ts    |   9 +
 .../hooks/timelineElementsAttribute.test.ts   |  70 ++++++
 .../src/hooks/timelineElementsAttribute.ts    |  98 ++++++++
 .../studio/src/hooks/useAppHotkeys.test.ts    |  34 +++
 .../studio/src/hooks/useRenderClipContent.ts  |   8 +-
 .../studio/src/hooks/useTimelineEditing.ts    |  12 +
 packages/studio/src/index.ts                  |   4 +
 .../components/AudioGainDialog.test.tsx       | 133 +++++++++++
 .../src/player/components/AudioGainDialog.tsx | 226 ++++++++++++++++++
 .../ClipContextMenu.groups.test.tsx           |   2 +-
 .../src/player/components/ClipContextMenu.tsx |   2 +-
 .../src/player/components/ClipPeakMarks.tsx   |  16 +-
 .../player/components/TimelineOverlays.tsx    |   2 +
 .../src/player/components/audioGainApply.ts   |  45 ++++
 .../player/components/audioGainDialogStore.ts |  36 +++
 .../player/components/audioGainPlan.test.ts   |  82 +++++++
 .../src/player/components/audioGainPlan.ts    |  53 ++++
 .../clipMenuAudioItems.noShell.test.tsx       |  24 +-
 .../components/clipMenuAudioItems.test.tsx    |  20 +-
 .../player/components/clipMenuAudioItems.tsx  |  53 ++--
 .../src/player/components/clipPeakMap.ts      |  46 ++++
 .../player/components/clipPeakRuns.test.ts    |  15 +-
 .../src/player/components/clipPeakRuns.ts     |  12 +
 .../src/player/components/studioShortcuts.ts  |   2 +
 .../player/components/timelineCallbacks.ts    |   6 +
 27 files changed, 934 insertions(+), 79 deletions(-)
 create mode 100644 packages/studio/src/hooks/timelineElementsAttribute.test.ts
 create mode 100644 packages/studio/src/hooks/timelineElementsAttribute.ts
 create mode 100644 packages/studio/src/player/components/AudioGainDialog.test.tsx
 create mode 100644 packages/studio/src/player/components/AudioGainDialog.tsx
 create mode 100644 packages/studio/src/player/components/audioGainApply.ts
 create mode 100644 packages/studio/src/player/components/audioGainDialogStore.ts
 create mode 100644 packages/studio/src/player/components/audioGainPlan.test.ts
 create mode 100644 packages/studio/src/player/components/audioGainPlan.ts
 create mode 100644 packages/studio/src/player/components/clipPeakMap.ts

diff --git a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
index beacb819ed..8f66485f15 100644
--- a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
+++ b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts
@@ -72,6 +72,7 @@ export interface TimelineEditCallbackDeps {
       value: string | null,
       label: string,
     ) => Promise<TimelineEditOutcome | void>;
+    setMany?: TimelineEditCallbacks["onSetElementsAttributeQuiet"];
   };
 }
 
@@ -228,6 +229,7 @@ export function useTimelineEditCallbacks({
       onGroupClips: handleGroupClips,
       onSetElementAttributeLive: setElementFxAttribute?.setLive,
       onSetElementAttributeQuiet: setElementFxAttribute?.setQuiet,
+      onSetElementsAttributeQuiet: setElementFxAttribute?.setMany,
       onRevertElementAttributeLive: setElementFxAttribute?.revertLive,
       onBlockedEditAttempt: handleBlockedTimelineEdit,
       onSplitElement: handleTimelineElementSplit,
diff --git a/packages/studio/src/contexts/TimelineEditContext.tsx b/packages/studio/src/contexts/TimelineEditContext.tsx
index 3144ee661f..48d7989111 100644
--- a/packages/studio/src/contexts/TimelineEditContext.tsx
+++ b/packages/studio/src/contexts/TimelineEditContext.tsx
@@ -37,6 +37,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {
   onGroupClips: true,
   onSetElementAttributeLive: true,
   onSetElementAttributeQuiet: true,
+  onSetElementsAttributeQuiet: true,
   onRevertElementAttributeLive: true,
   onBlockedEditAttempt: true,
   onLinkEdit: true,
diff --git a/packages/studio/src/hooks/appHotkeysDispatch.ts b/packages/studio/src/hooks/appHotkeysDispatch.ts
index 35c82f6ef2..f7dae35234 100644
--- a/packages/studio/src/hooks/appHotkeysDispatch.ts
+++ b/packages/studio/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();
diff --git a/packages/studio/src/hooks/timelineElementsAttribute.test.ts b/packages/studio/src/hooks/timelineElementsAttribute.test.ts
new file mode 100644
index 0000000000..8dfcf0362a
--- /dev/null
+++ b/packages/studio/src/hooks/timelineElementsAttribute.test.ts
@@ -0,0 +1,70 @@
+// @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"/);
+  });
+});
diff --git a/packages/studio/src/hooks/timelineElementsAttribute.ts b/packages/studio/src/hooks/timelineElementsAttribute.ts
new file mode 100644
index 0000000000..7141d53647
--- /dev/null
+++ b/packages/studio/src/hooks/timelineElementsAttribute.ts
@@ -0,0 +1,98 @@
+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";
+
+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,
+}: UseTimelineElementVisibilityEditingInput) {
+  return useCallback(
+    async (edits: ElementAttributeEdits, attr: string, label: string): Promise<void> => {
+      const projectId = projectIdRef.current;
+      if (!projectId || edits.length === 0) return;
+      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);
+      } catch (error) {
+        showToast(error instanceof Error ? error.message : "Could not save the clips", "error");
+      }
+    },
+    [
+      projectIdRef,
+      activeCompPath,
+      showToast,
+      writeProjectFile,
+      recordEdit,
+      previewIframeRef,
+      pendingTimelineEditPathRef,
+    ],
+  );
+}
diff --git a/packages/studio/src/hooks/useAppHotkeys.test.ts b/packages/studio/src/hooks/useAppHotkeys.test.ts
index f02e3e0551..2d3a850470 100644
--- a/packages/studio/src/hooks/useAppHotkeys.test.ts
+++ b/packages/studio/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);
+  });
+});
diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.ts
index 87d4d7a657..b677c531a4 100644
--- a/packages/studio/src/hooks/useRenderClipContent.ts
+++ b/packages/studio/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,
diff --git a/packages/studio/src/hooks/useTimelineEditing.ts b/packages/studio/src/hooks/useTimelineEditing.ts
index c4103daad8..e2a7fd403d 100644
--- a/packages/studio/src/hooks/useTimelineEditing.ts
+++ b/packages/studio/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,16 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
+  const setElementsAttribute = useSetElementsAttribute({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+  });
+
   const setAudioGroupAttribute = useSetAudioGroupAttribute({
     projectIdRef,
     activeCompPath,
@@ -532,6 +543,7 @@ export function useTimelineEditing({
     },
     setElementFxAttribute: {
       ...setElementFxAttribute,
+      setMany: track(guard((edits) => edits.map((edit) => edit.element), setElementsAttribute)),
       setQuiet: track(
         guard(
           (element) => [element],
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index b891063737..da6e19ce2a 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/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,
diff --git a/packages/studio/src/player/components/AudioGainDialog.test.tsx b/packages/studio/src/player/components/AudioGainDialog.test.tsx
new file mode 100644
index 0000000000..c70e8214db
--- /dev/null
+++ b/packages/studio/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);
+  });
+});
diff --git a/packages/studio/src/player/components/AudioGainDialog.tsx b/packages/studio/src/player/components/AudioGainDialog.tsx
new file mode 100644
index 0000000000..e4ace82162
--- /dev/null
+++ b/packages/studio/src/player/components/AudioGainDialog.tsx
@@ -0,0 +1,226 @@
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { audioGainToDb } from "@hyperframes/core/audio-gain";
+import type { TimelineElement } from "../store/timelineElement";
+import { usePlayerStore } from "../store/playerStore";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { measureClipSourcePeak } from "./clipPeakMap";
+import { AUDIO_GAIN_LABEL, normalizeClipsLoudness, writeClipGains } from "./audioGainApply";
+import { useAudioGainDialogStore } from "./audioGainDialogStore";
+import {
+  peakAmplitudeDb,
+  planAudioGain,
+  type AudioGainClip,
+  type AudioGainMode,
+} from "./audioGainPlan";
+
+type DialogMode = AudioGainMode | "loudness";
+
+const PEAK_MODES: ReadonlySet<DialogMode> = new Set(["normalize-max", "normalize-all"]);
+
+const ROWS: ReadonlyArray<{ mode: AudioGainMode; label: string }> = [
+  { mode: "set", label: "Set Gain to" },
+  { mode: "adjust", label: "Adjust Gain by" },
+  { mode: "normalize-max", label: "Normalize Max Peak to" },
+  { mode: "normalize-all", label: "Normalize All Peaks to" },
+];
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+const currentGainDb = (el: TimelineElement | undefined) => {
+  const gain = el?.volume ?? 1;
+  return gain > 0 ? Math.round(audioGainToDb(gain) * 10) / 10 : -60;
+};
+const dbText = (db: number) => `${db < 0 ? "−" : ""}${Math.abs(db).toFixed(1)} dB`;
+
+function useSourcePeaks(elements: readonly TimelineElement[], projectId: string | null) {
+  const [peaks, setPeaks] = useState<Map<string, number | null> | null>(null);
+  useEffect(() => {
+    if (!projectId) return;
+    let live = true;
+    void Promise.all(elements.map((el) => measureClipSourcePeak(el, projectId))).then((found) => {
+      if (live) setPeaks(new Map(elements.map((el, i) => [keyOf(el), found[i] ?? null])));
+    });
+    return () => {
+      live = false;
+    };
+  }, [elements, projectId]);
+  return peaks;
+}
+
+function Row({
+  checked,
+  disabled,
+  label,
+  onSelect,
+  children,
+}: {
+  checked: boolean;
+  disabled?: boolean;
+  label: string;
+  onSelect: () => void;
+  children?: ReactNode;
+}) {
+  return (
+    <label
+      className={`flex items-center justify-between gap-3 py-1 ${disabled ? "opacity-40" : ""}`}
+    >
+      <span className="flex items-center gap-2">
+        <input
+          type="radio"
+          name="audio-gain-mode"
+          checked={checked}
+          disabled={disabled}
+          onChange={onSelect}
+        />
+        {label}
+      </span>
+      {children}
+    </label>
+  );
+}
+
+/** Premiere's Audio Gain dialog for the clips the store names. */
+export function AudioGainDialog({
+  elements,
+  onClose,
+}: {
+  elements: readonly TimelineElement[];
+  onClose: () => void;
+}) {
+  const shell = useStudioShellContextOptional();
+  const edit = useTimelineEditContextOptional();
+  const sessionProjectId = usePlayerStore((s) => s.timelineProjectId);
+  const projectId = shell?.projectId ?? sessionProjectId;
+  const showToast = shell?.showToast ?? edit.onNotice;
+  const peaks = useSourcePeaks(elements, projectId);
+  const [mode, setMode] = useState<DialogMode>("adjust");
+  const [values, setValues] = useState<Record<AudioGainMode, number>>(() => ({
+    set: currentGainDb(elements[0]),
+    adjust: 0,
+    "normalize-max": 0,
+    "normalize-all": 0,
+  }));
+  const clips: AudioGainClip[] = elements.map((el) => ({
+    key: keyOf(el),
+    gain: el.volume ?? 1,
+    sourcePeak: peaks?.get(keyOf(el)) ?? null,
+  }));
+  const peakDb = peakAmplitudeDb(clips);
+  const outOfRange = PEAK_MODES.has(mode) && mode !== "loudness" && values[mode] > 0;
+  const canApply = !outOfRange && !(PEAK_MODES.has(mode) && peakDb === null);
+
+  const apply = async () => {
+    if (!canApply) return;
+    onClose();
+    try {
+      if (mode === "loudness") {
+        if (!projectId) return;
+        showToast?.(await normalizeClipsLoudness(projectId, elements, edit), "info");
+        return;
+      }
+      const byKey = new Map(elements.map((el) => [keyOf(el), el]));
+      const plan = planAudioGain(clips, { mode, db: values[mode] });
+      const edits = plan.flatMap(({ key, gain }) => {
+        const element = byKey.get(key);
+        return element ? [{ element, gain }] : [];
+      });
+      await writeClipGains(edits, edit, AUDIO_GAIN_LABEL);
+    } catch (error) {
+      showToast?.(error instanceof Error ? error.message : String(error), "error");
+    }
+  };
+
+  const field = (rowMode: AudioGainMode) => (
+    <span className="flex items-center gap-1">
+      <input
+        type="number"
+        step={0.1}
+        max={PEAK_MODES.has(rowMode) ? 0 : undefined}
+        aria-label={`${ROWS.find((row) => row.mode === rowMode)?.label ?? ""} dB`}
+        value={values[rowMode]}
+        disabled={mode !== rowMode}
+        className="w-16 rounded border border-neutral-700 bg-neutral-950 px-1 text-right disabled:opacity-50"
+        onChange={(event) =>
+          setValues((prev) => ({ ...prev, [rowMode]: Number(event.target.value) || 0 }))
+        }
+      />
+      dB
+    </span>
+  );
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[300] flex items-center justify-center bg-black/50"
+      onPointerDown={(event) => event.target === event.currentTarget && onClose()}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={AUDIO_GAIN_LABEL}
+        className="w-[340px] rounded-md border border-neutral-700 bg-neutral-900 p-4 text-xs text-neutral-200 shadow-xl"
+        onKeyDown={(event) => {
+          event.stopPropagation();
+          if (event.key === "Escape") onClose();
+          if (event.key !== "Enter") return;
+          event.preventDefault();
+          void apply();
+        }}
+      >
+        <div className="mb-3 text-sm font-medium">{AUDIO_GAIN_LABEL}</div>
+        {ROWS.map((row) => (
+          <Row
+            key={row.mode}
+            label={row.label}
+            checked={mode === row.mode}
+            disabled={PEAK_MODES.has(row.mode) && peaks !== null && peakDb === null}
+            onSelect={() => setMode(row.mode)}
+          >
+            {field(row.mode)}
+          </Row>
+        ))}
+        <Row
+          label="Normalize loudness to −16 LUFS"
+          checked={mode === "loudness"}
+          onSelect={() => setMode("loudness")}
+        />
+        <div className="mt-3 text-neutral-400" data-testid="audio-gain-peak">
+          Peak Amplitude: {peaks === null ? "measuring…" : peakDb === null ? "—" : dbText(peakDb)}
+        </div>
+        {outOfRange && <div className="mt-1 text-red-400">Peak targets must be 0 dB or lower.</div>}
+        <div className="mt-4 flex justify-end gap-2">
+          <button
+            type="button"
+            className="rounded px-3 py-1 text-neutral-300 hover:bg-neutral-800"
+            onClick={onClose}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            disabled={!canApply}
+            autoFocus
+            className="rounded bg-blue-600 px-3 py-1 text-white disabled:opacity-40"
+            onClick={() => void apply()}
+          >
+            OK
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+/** Mounted in the timeline's overlays so Studio and embedders that mount the Timeline both get it. */
+export function TimelineAudioGainOverlay() {
+  const targetKeys = useAudioGainDialogStore((s) => s.targetKeys);
+  const close = useAudioGainDialogStore((s) => s.close);
+  const elements = usePlayerStore((s) => s.elements);
+  const targets = useMemo(() => {
+    const wanted = new Set(targetKeys ?? []);
+    return elements.filter((el) => wanted.has(keyOf(el)));
+  }, [elements, targetKeys]);
+  if (!targetKeys || targets.length === 0) return null;
+  return <AudioGainDialog key={targetKeys.join("\n")} elements={targets} onClose={close} />;
+}
diff --git a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx
index dd3f660b49..c0ac08d96e 100644
--- a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx
@@ -84,7 +84,7 @@ describe("ClipContextMenu order", () => {
     const expected = [
       "Split at 2.00s",
       "Freeze frame",
-      "Normalize loudness",
+      "Audio Gain…",
       "Voice",
       "Detach audio",
       "Unlink from audio",
diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsx
index 438b09def5..37bddac8fa 100644
--- a/packages/studio/src/player/components/ClipContextMenu.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.tsx
@@ -175,7 +175,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
       </div>
 
       <div role="group" aria-label="Sound" className={GROUP_CLASS}>
-        <ClipMenuAudioItems part="normalize" element={element} onClose={onClose} />
+        <ClipMenuAudioItems part="gain" element={element} onClose={onClose} />
         <ClipMenuToolItems
           group="sound"
           element={element}
diff --git a/packages/studio/src/player/components/ClipPeakMarks.tsx b/packages/studio/src/player/components/ClipPeakMarks.tsx
index e8af8cc59c..064a436866 100644
--- a/packages/studio/src/player/components/ClipPeakMarks.tsx
+++ b/packages/studio/src/player/components/ClipPeakMarks.tsx
@@ -1,18 +1,6 @@
 import { useEffect, useState, type ReactNode } from "react";
-import { clipPeakRuns, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";
-
-const peakMapRequests = new Map<string, Promise<PeakMap | null>>();
-
-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;
-}
+import { clipPeakRuns, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";
+import { loadPeakMap } from "./clipPeakMap";
 
 const dbText = (db: number) => `${db < 0 ? "−" : "+"}${Math.abs(db).toFixed(1)} dBFS`;
 
diff --git a/packages/studio/src/player/components/TimelineOverlays.tsx b/packages/studio/src/player/components/TimelineOverlays.tsx
index 561b1b6522..97fa10d70c 100644
--- a/packages/studio/src/player/components/TimelineOverlays.tsx
+++ b/packages/studio/src/player/components/TimelineOverlays.tsx
@@ -1,3 +1,4 @@
+import { TimelineAudioGainOverlay } from "./AudioGainDialog";
 import { useEffect, useMemo } from "react";
 import type { TimelineElement } from "../store/playerStore";
 import { EditPopover } from "./EditModal";
@@ -222,6 +223,7 @@ export function TimelineOverlays() {
       <TimelineKeyframeMenuOverlay />
       <TimelineClipMenuOverlay />
       <TimelineGapMenuOverlay />
+      <TimelineAudioGainOverlay />
     </>
   );
 }
diff --git a/packages/studio/src/player/components/audioGainApply.ts b/packages/studio/src/player/components/audioGainApply.ts
new file mode 100644
index 0000000000..796facca7a
--- /dev/null
+++ b/packages/studio/src/player/components/audioGainApply.ts
@@ -0,0 +1,45 @@
+import { formatAudioGain } from "@hyperframes/core/audio-gain";
+import type { TimelineElement } from "../store/timelineElement";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { normalizeToastText, requestNormalizePlan } from "./clipMenuNormalize";
+
+export const AUDIO_GAIN_LABEL = "Audio Gain";
+
+type VolumeWriters = Pick<
+  TimelineEditCallbacks,
+  "onSetElementAttributeQuiet" | "onSetElementsAttributeQuiet"
+>;
+
+/** Every clip's new gain as `data-volume`, one undo step when the host can save them together. */
+export async function writeClipGains(
+  edits: ReadonlyArray<{ element: TimelineElement; gain: number }>,
+  writers: VolumeWriters,
+  label = AUDIO_GAIN_LABEL,
+): Promise<void> {
+  const values = edits.map(({ element, gain }) => ({ element, value: formatAudioGain(gain) }));
+  if (values.length > 1 && writers.onSetElementsAttributeQuiet) {
+    await writers.onSetElementsAttributeQuiet(values, "data-volume", label);
+    return;
+  }
+  for (const { element, value } of values) {
+    await writers.onSetElementAttributeQuiet?.(element, "data-volume", value, label);
+  }
+}
+
+/** Measure each clip against −16 LUFS, write the gains, and say what happened. */
+export async function normalizeClipsLoudness(
+  projectId: string,
+  elements: readonly TimelineElement[],
+  writers: VolumeWriters,
+): Promise<string> {
+  const plans = await Promise.all(elements.map((el) => requestNormalizePlan(projectId, el)));
+  await writeClipGains(
+    elements.map((element, index) => ({ element, gain: plans[index]?.volume ?? 1 })),
+    writers,
+    "Normalize loudness",
+  );
+  const [only] = plans;
+  return plans.length === 1 && only
+    ? normalizeToastText(only)
+    : `Normalized ${plans.length} clips to −16 LUFS`;
+}
diff --git a/packages/studio/src/player/components/audioGainDialogStore.ts b/packages/studio/src/player/components/audioGainDialogStore.ts
new file mode 100644
index 0000000000..af0bc397c2
--- /dev/null
+++ b/packages/studio/src/player/components/audioGainDialogStore.ts
@@ -0,0 +1,36 @@
+import { create } from "zustand";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { clipHasSound } from "./clipMenuNormalize";
+
+interface AudioGainDialogState {
+  targetKeys: readonly string[] | null;
+  open: (keys: readonly string[]) => void;
+  close: () => void;
+}
+
+/** Which clips the Audio Gain dialog (G) is open for. */
+export const useAudioGainDialogStore = create<AudioGainDialogState>((set) => ({
+  targetKeys: null,
+  open: (keys) => set({ targetKeys: keys }),
+  close: () => set({ targetKeys: null }),
+}));
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+
+/** The selected clips with sound, or just `clicked` when it is outside the selection. */
+function audioGainTargetKeys(clicked?: TimelineElement): string[] {
+  const { elements, selectedElementId, selectedElementIds } = usePlayerStore.getState();
+  const selected = new Set(selectedElementIds);
+  if (selectedElementId) selected.add(selectedElementId);
+  if (clicked && !selected.has(keyOf(clicked)))
+    return clipHasSound(clicked) ? [keyOf(clicked)] : [];
+  return elements.filter((el) => selected.has(keyOf(el)) && clipHasSound(el)).map(keyOf);
+}
+
+/** Open Audio Gain for the selection (or the clicked clip); false when none of it has sound. */
+export function openAudioGainDialog(clicked?: TimelineElement): boolean {
+  const keys = audioGainTargetKeys(clicked);
+  if (keys.length === 0) return false;
+  useAudioGainDialogStore.getState().open(keys);
+  return true;
+}
diff --git a/packages/studio/src/player/components/audioGainPlan.test.ts b/packages/studio/src/player/components/audioGainPlan.test.ts
new file mode 100644
index 0000000000..b55594efbc
--- /dev/null
+++ b/packages/studio/src/player/components/audioGainPlan.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { audioGainToDb, MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
+import { peakAmplitudeDb, planAudioGain, type AudioGainClip } from "./audioGainPlan";
+
+const clip = (key: string, gain: number, sourcePeak: number | null): AudioGainClip => ({
+  key,
+  gain,
+  sourcePeak,
+});
+const db = (gain: number | undefined) => audioGainToDb(gain ?? Number.NaN);
+const gainOf = (plan: ReturnType<typeof planAudioGain>, key: string) =>
+  plan.find((edit) => edit.key === key)?.gain;
+
+describe("planAudioGain", () => {
+  it("Set Gain to puts every clip at the same gain", () => {
+    const plan = planAudioGain([clip("a", 2, 0.5), clip("b", 0.5, null)], { mode: "set", db: -6 });
+    expect(db(gainOf(plan, "a"))).toBeCloseTo(-6, 6);
+    expect(db(gainOf(plan, "b"))).toBeCloseTo(-6, 6);
+  });
+
+  it("Adjust Gain by moves each clip by the same dB from where it is", () => {
+    const plan = planAudioGain([clip("a", 2, null), clip("b", 0.5, null)], {
+      mode: "adjust",
+      db: 3,
+    });
+    expect(db(gainOf(plan, "a"))).toBeCloseTo(db(2) + 3, 6);
+    expect(db(gainOf(plan, "b"))).toBeCloseTo(db(0.5) + 3, 6);
+  });
+
+  it("Normalize Max Peak moves all clips together until the loudest peak hits the target", () => {
+    const plan = planAudioGain([clip("loud", 1, 0.5), clip("quiet", 1, 0.25)], {
+      mode: "normalize-max",
+      db: -1,
+    });
+    expect(db(0.5 * (gainOf(plan, "loud") ?? 0))).toBeCloseTo(-1, 6);
+    expect(db(gainOf(plan, "loud")) - db(gainOf(plan, "quiet"))).toBeCloseTo(0, 6);
+  });
+
+  it("Normalize Max Peak counts each clip's current gain", () => {
+    const plan = planAudioGain([clip("a", 0.5, 0.8), clip("b", 2, 0.25)], {
+      mode: "normalize-max",
+      db: -3,
+    });
+    expect(db(0.25 * (gainOf(plan, "b") ?? 0))).toBeCloseTo(-3, 6);
+  });
+
+  it("Normalize All Peaks brings each clip's own peak to the target", () => {
+    const plan = planAudioGain([clip("a", 1, 0.5), clip("b", 3, 0.25)], {
+      mode: "normalize-all",
+      db: -3,
+    });
+    expect(db(0.5 * (gainOf(plan, "a") ?? 0))).toBeCloseTo(-3, 6);
+    expect(db(0.25 * (gainOf(plan, "b") ?? 0))).toBeCloseTo(-3, 6);
+  });
+
+  it("leaves clips it could not measure out of a normalize", () => {
+    const plan = planAudioGain([clip("a", 1, 0.5), clip("b", 1, null), clip("c", 1, 0)], {
+      mode: "normalize-all",
+      db: -1,
+    });
+    expect(plan.map((edit) => edit.key)).toEqual(["a"]);
+  });
+
+  it("clamps to the +12 dB ceiling and to silence", () => {
+    const loud = planAudioGain([clip("a", 1, 0.001)], { mode: "normalize-all", db: 0 });
+    expect(gainOf(loud, "a")).toBe(MAX_AUDIO_GAIN);
+    expect(gainOf(planAudioGain([clip("a", 1, null)], { mode: "set", db: 40 }), "a")).toBe(
+      MAX_AUDIO_GAIN,
+    );
+    expect(gainOf(planAudioGain([clip("a", 0, null)], { mode: "adjust", db: 6 }), "a")).toBe(0);
+  });
+});
+
+describe("peakAmplitudeDb", () => {
+  it("is the loudest peak across the selection at each clip's gain", () => {
+    expect(peakAmplitudeDb([clip("a", 1, 0.5), clip("b", 2, 0.5)])).toBeCloseTo(0, 6);
+  });
+
+  it("is null when nothing was measured", () => {
+    expect(peakAmplitudeDb([clip("a", 1, null)])).toBeNull();
+  });
+});
diff --git a/packages/studio/src/player/components/audioGainPlan.ts b/packages/studio/src/player/components/audioGainPlan.ts
new file mode 100644
index 0000000000..b0b4c898f5
--- /dev/null
+++ b/packages/studio/src/player/components/audioGainPlan.ts
@@ -0,0 +1,53 @@
+import { audioDbToGain, audioGainToDb, clampAudioGain } from "@hyperframes/core/audio-gain";
+
+export type AudioGainMode = "set" | "adjust" | "normalize-max" | "normalize-all";
+
+export interface AudioGainChoice {
+  mode: AudioGainMode;
+  db: number;
+}
+
+/** A selected clip: its `data-volume` gain and its source's linear sample peak over the played window. */
+export interface AudioGainClip {
+  key: string;
+  gain: number;
+  sourcePeak: number | null;
+}
+
+export interface AudioGainEdit {
+  key: string;
+  gain: number;
+}
+
+function isMeasured(clip: AudioGainClip): clip is AudioGainClip & { sourcePeak: number } {
+  return clip.sourcePeak !== null && clip.sourcePeak > 0;
+}
+
+const heardPeak = (clip: AudioGainClip & { sourcePeak: number }) => clip.sourcePeak * clip.gain;
+
+/** Premiere's Audio Gain options as new `data-volume` gains, clamped to silence..+12 dB. */
+export function planAudioGain(
+  clips: readonly AudioGainClip[],
+  choice: AudioGainChoice,
+): AudioGainEdit[] {
+  const target = audioDbToGain(choice.db);
+  const edit = (clip: AudioGainClip, gain: number) => ({
+    key: clip.key,
+    gain: clampAudioGain(gain),
+  });
+  if (choice.mode === "set") return clips.map((clip) => edit(clip, target));
+  if (choice.mode === "adjust") return clips.map((clip) => edit(clip, clip.gain * target));
+  const measured = clips.filter(isMeasured);
+  if (choice.mode === "normalize-all") {
+    return measured.map((clip) => edit(clip, target / clip.sourcePeak));
+  }
+  const loudest = Math.max(0, ...measured.map(heardPeak));
+  if (loudest <= 0) return [];
+  return measured.map((clip) => edit(clip, (clip.gain * target) / loudest));
+}
+
+/** The loudest peak the selection plays at its current gains, in dBFS. */
+export function peakAmplitudeDb(clips: readonly AudioGainClip[]): number | null {
+  const loudest = Math.max(0, ...clips.filter(isMeasured).map(heardPeak));
+  return loudest > 0 ? audioGainToDb(loudest) : null;
+}
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx
index a91d2e4768..63665b7ed2 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx
@@ -3,6 +3,7 @@ import { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import { AudioGainDialog } from "./AudioGainDialog";
 import { usePlayerStore } from "../store/playerStore";
 import { usePreviewIframeStore } from "../store/previewIframeStore";
 import type { TimelineElement } from "../store/timelineElement";
@@ -38,7 +39,7 @@ function mountPreview(): void {
   usePreviewIframeStore.getState().setIframe(iframe);
 }
 
-function render(part: "normalize" | "duck") {
+function render(part: "gain" | "duck") {
   const host = document.createElement("div");
   document.body.appendChild(host);
   act(() =>
@@ -55,23 +56,30 @@ afterEach(() => {
 });
 
 describe("ClipMenuAudioItems in a host without Studio's shell", () => {
-  it("offers Normalize and Duck from the timeline session and the live preview", () => {
+  it("offers Audio Gain and Duck from the timeline session and the live preview", () => {
     usePlayerStore.getState().beginTimelineSession("p1");
     mountPreview();
-    expect(render("normalize").textContent).toContain("Normalize loudness");
+    expect(render("gain").textContent).toContain("Audio Gain…");
     expect(render("duck").textContent).toContain("Duck under voice");
   });
 
-  it("normalizes through the session's project and reports through onNotice", async () => {
+  it("the dialog's loudness row normalizes through the session's project and onNotice", async () => {
     usePlayerStore.getState().beginTimelineSession("p1");
-    mountPreview();
     const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
     const fetchSpy = vi.fn(async (_url: string) => Response.json({ plan }));
     vi.stubGlobal("fetch", fetchSpy);
-    const button = render("normalize").querySelector("button");
-    await act(async () => button?.click());
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    act(() => harness.mount(host).render(<AudioGainDialog elements={[tour]} onClose={() => {}} />));
+    const loudness = [...document.querySelectorAll("label")].find((l) =>
+      l.textContent?.includes("−16 LUFS"),
+    );
+    act(() => loudness?.querySelector("input")?.click());
+    const ok = [...document.querySelectorAll("button")].find((b) => b.textContent === "OK");
+    await act(async () => ok?.click());
     await vi.waitFor(() => expect(onNotice).toHaveBeenCalled());
-    expect(String(fetchSpy.mock.calls[0]?.[0])).toContain("/api/projects/p1/loudness/normalize");
+    const urls = fetchSpy.mock.calls.map((call) => String(call[0]));
+    expect(urls).toContain("/api/projects/p1/loudness/normalize");
     expect(setQuiet).toHaveBeenCalledWith(tour, "data-volume", "2", "Normalize loudness");
     expect(onNotice).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
   });
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
index a73119a647..39fe3cbbda 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { ClipMenuAudioItems } from "./clipMenuAudioItems";
 import type { TimelineElement } from "../store/timelineElement";
+import { useAudioGainDialogStore } from "./audioGainDialogStore";
 
 const showToast = vi.fn();
 const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});
@@ -27,7 +28,7 @@ vi.mock("../../contexts/TimelineEditContext", () => ({
 
 const harness = createHappyDomRootHarness();
 
-function render(element: TimelineElement, part: "normalize" | "duck" = "normalize") {
+function render(element: TimelineElement, part: "gain" | "duck" = "gain") {
   const host = document.createElement("div");
   document.body.appendChild(host);
   act(() =>
@@ -95,12 +96,8 @@ describe("ClipMenuAudioItems", () => {
     });
   });
 
-  it("normalizes a video with sound by writing data-volume as one edit", async () => {
-    const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => Response.json({ plan })),
-    );
+  it("Audio Gain… opens the G dialog for the clicked clip", async () => {
+    useAudioGainDialogStore.getState().close();
     const element: TimelineElement = {
       ...base,
       id: "a-roll",
@@ -110,13 +107,12 @@ describe("ClipMenuAudioItems", () => {
     };
     const host = render(element);
     const button = [...host.querySelectorAll("button")].find((b) =>
-      b.textContent?.includes("Normalize loudness"),
+      b.textContent?.includes("Audio Gain…"),
     );
+    expect(button?.textContent).toBe("Audio Gain…G");
     await act(async () => button?.click());
-    await vi.waitFor(() => expect(setQuiet).toHaveBeenCalled());
-    expect(setQuiet).toHaveBeenCalledWith(element, "data-volume", "2", "Normalize loudness");
-    expect(showToast).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
-    vi.unstubAllGlobals();
+    expect(useAudioGainDialogStore.getState().targetKeys).toEqual(["a-roll"]);
+    expect(host.textContent).not.toContain("Normalize loudness");
   });
 
   it("refuses to normalize a clip whose volume lane owns its gain", async () => {
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsx
index 5488d84301..a543593416 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.tsx
+++ b/packages/studio/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>
     );
   }
diff --git a/packages/studio/src/player/components/clipPeakMap.ts b/packages/studio/src/player/components/clipPeakMap.ts
new file mode 100644
index 0000000000..e6eeaee6bb
--- /dev/null
+++ b/packages/studio/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;
+}
diff --git a/packages/studio/src/player/components/clipPeakRuns.test.ts b/packages/studio/src/player/components/clipPeakRuns.test.ts
index 5aed064218..5a7140e817 100644
--- a/packages/studio/src/player/components/clipPeakRuns.test.ts
+++ b/packages/studio/src/player/components/clipPeakRuns.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { clipPeakRuns } from "./clipPeakRuns";
+import { clipPeakRuns, clipSourcePeak } from "./clipPeakRuns";
 
 const map = (bins: number[]) => ({ binSeconds: 1, bins });
 
@@ -36,3 +36,16 @@ describe("clipPeakRuns", () => {
     expect(clipPeakRuns(map([1]), { mediaStart: 0, sourceSpan: 0 }, 1).runs).toEqual([]);
   });
 });
+
+describe("clipSourcePeak", () => {
+  it("is the loudest bin inside the played source window only", () => {
+    const bins = map([0.9, 0.2, 0.4, 0.3, 1]);
+    expect(clipSourcePeak(bins, { mediaStart: 1, sourceSpan: 3 })).toBe(0.4);
+    expect(clipSourcePeak(bins, { mediaStart: 0, sourceSpan: 5 })).toBe(1);
+  });
+
+  it("is null for an empty window or one past the file's end", () => {
+    expect(clipSourcePeak(map([0.5]), { mediaStart: 0, sourceSpan: 0 })).toBeNull();
+    expect(clipSourcePeak(map([0.5]), { mediaStart: 4, sourceSpan: 2 })).toBeNull();
+  });
+});
diff --git a/packages/studio/src/player/components/clipPeakRuns.ts b/packages/studio/src/player/components/clipPeakRuns.ts
index 5478d231fc..814e3eec8b 100644
--- a/packages/studio/src/player/components/clipPeakRuns.ts
+++ b/packages/studio/src/player/components/clipPeakRuns.ts
@@ -48,6 +48,18 @@ export function clipPeakRuns(
   return { runs, peakDbfs: runs.length > 0 ? 20 * Math.log10(loudest) : null };
 }
 
+/** The loudest source sample, linear, in the part of the file the clip plays; null outside it. */
+export function clipSourcePeak(map: PeakMap, window: ClipSourceWindow): number | null {
+  if (!(window.sourceSpan > 0) || !(map.binSeconds > 0)) return null;
+  const first = Math.max(0, Math.floor(window.mediaStart / map.binSeconds));
+  const last = Math.min(
+    map.bins.length,
+    Math.ceil((window.mediaStart + window.sourceSpan) / map.binSeconds),
+  );
+  if (last <= first) return null;
+  return map.bins.slice(first, last).reduce((loudest, bin) => Math.max(loudest, bin), 0);
+}
+
 export function isPeakMap(value: unknown): value is PeakMap {
   if (typeof value !== "object" || value === null) return false;
   const bins: unknown = Reflect.get(value, "bins");
diff --git a/packages/studio/src/player/components/studioShortcuts.ts b/packages/studio/src/player/components/studioShortcuts.ts
index 94334f302d..ea8216c0cb 100644
--- a/packages/studio/src/player/components/studioShortcuts.ts
+++ b/packages/studio/src/player/components/studioShortcuts.ts
@@ -4,6 +4,7 @@ export const STUDIO_PLAIN_KEYS = {
   split: "s",
   record: "r",
   addKeyframe: "k",
+  audioGain: "g",
 } as const;
 
 export interface ShortcutHint {
@@ -51,6 +52,7 @@ export const DEFAULT_SHORTCUT_SECTIONS: readonly ShortcutSection[] = [
       { key: "⌘V", label: "Paste element" },
       { key: "⌘X", label: "Cut element" },
       { key: hintKey(STUDIO_PLAIN_KEYS.split), label: "Split clip at playhead" },
+      { key: hintKey(STUDIO_PLAIN_KEYS.audioGain), label: "Audio Gain for clips with sound" },
       { key: "⇧Click", label: "Razor tool: split all tracks" },
       { key: "[", label: "Select clips starting before the playhead" },
       { key: "]", label: "Select clips running at or after the playhead" },
diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.ts
index 56b96dacc8..f546125e43 100644
--- a/packages/studio/src/player/components/timelineCallbacks.ts
+++ b/packages/studio/src/player/components/timelineCallbacks.ts
@@ -122,6 +122,12 @@ export interface TimelineEditCallbacks {
     value: string | null,
     label: string,
   ) => Promise<TimelineEditOutcome | void>;
+  /** One attribute on several clips, saved as one undo step. */
+  onSetElementsAttributeQuiet?: (
+    edits: ReadonlyArray<{ element: TimelineElement; value: string | null }>,
+    attr: string,
+    label: string,
+  ) => Promise<void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;
   onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;

From 0ab3e8816528745a5e7f8a8ce765bf18c390f7c8 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 16:24:45 -0700
Subject: [PATCH 04/20] fix(studio): use a theme blue for the audio gain OK
 button

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/studio/src/player/components/AudioGainDialog.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/studio/src/player/components/AudioGainDialog.tsx b/packages/studio/src/player/components/AudioGainDialog.tsx
index e4ace82162..3dceed07de 100644
--- a/packages/studio/src/player/components/AudioGainDialog.tsx
+++ b/packages/studio/src/player/components/AudioGainDialog.tsx
@@ -200,7 +200,7 @@ export function AudioGainDialog({
             type="button"
             disabled={!canApply}
             autoFocus
-            className="rounded bg-blue-600 px-3 py-1 text-white disabled:opacity-40"
+            className="rounded bg-blue-500 px-3 py-1 text-white disabled:opacity-40"
             onClick={() => void apply()}
           >
             OK

From 99273829458011bbdcfcb28f6c0f290cf9780f76 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 11:25:53 -0700
Subject: [PATCH 05/20] fix(studio): keep shortcuts out of the audio gain
 modal; refuse while recording

Keys pressed inside an aria-modal dialog no longer reach the global hotkeys,
so Delete on the focused OK button cannot delete the clips the dialog edits.
The multi-clip write refuses during a recording like the single-clip one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../hooks/timelineElementsAttribute.test.ts   | 25 +++++++++++++++++++
 .../src/hooks/timelineElementsAttribute.ts    | 11 ++++++--
 .../studio/src/hooks/useTimelineEditing.ts    |  1 +
 .../studio/src/utils/typingTarget.test.ts     |  8 ++++++
 packages/studio/src/utils/typingTarget.ts     |  1 +
 5 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/packages/studio/src/hooks/timelineElementsAttribute.test.ts b/packages/studio/src/hooks/timelineElementsAttribute.test.ts
index 8dfcf0362a..781dd10566 100644
--- a/packages/studio/src/hooks/timelineElementsAttribute.test.ts
+++ b/packages/studio/src/hooks/timelineElementsAttribute.test.ts
@@ -67,4 +67,29 @@ describe("useSetElementsAttribute", () => {
     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");
+  });
 });
diff --git a/packages/studio/src/hooks/timelineElementsAttribute.ts b/packages/studio/src/hooks/timelineElementsAttribute.ts
index 7141d53647..cf77d43f41 100644
--- a/packages/studio/src/hooks/timelineElementsAttribute.ts
+++ b/packages/studio/src/hooks/timelineElementsAttribute.ts
@@ -9,6 +9,7 @@ import {
   readFileContent,
 } from "./timelineEditingHelpers";
 import type { UseTimelineElementVisibilityEditingInput } from "./timelineTrackVisibility";
+import { projectForTimelineSave } from "./timelineEditPermission";
 
 type ElementAttributeEdits = Parameters<
   NonNullable<TimelineEditCallbacks["onSetElementsAttributeQuiet"]>
@@ -53,11 +54,16 @@ export function useSetElementsAttribute({
   recordEdit,
   previewIframeRef,
   pendingTimelineEditPathRef,
+  isRecordingRef,
 }: UseTimelineElementVisibilityEditingInput) {
   return useCallback(
     async (edits: ElementAttributeEdits, attr: string, label: string): Promise<void> => {
-      const projectId = projectIdRef.current;
-      if (!projectId || edits.length === 0) return;
+      const projectId = projectForTimelineSave(
+        isRecordingRef?.current,
+        projectIdRef.current,
+        showToast,
+      );
+      if (typeof projectId !== "string" || edits.length === 0) return;
       try {
         const byFile = editsByFile(edits, activeCompPath);
         const files = Object.fromEntries(
@@ -93,6 +99,7 @@ export function useSetElementsAttribute({
       recordEdit,
       previewIframeRef,
       pendingTimelineEditPathRef,
+      isRecordingRef,
     ],
   );
 }
diff --git a/packages/studio/src/hooks/useTimelineEditing.ts b/packages/studio/src/hooks/useTimelineEditing.ts
index e2a7fd403d..3471a11e3d 100644
--- a/packages/studio/src/hooks/useTimelineEditing.ts
+++ b/packages/studio/src/hooks/useTimelineEditing.ts
@@ -418,6 +418,7 @@ export function useTimelineEditing({
     recordEdit,
     previewIframeRef,
     pendingTimelineEditPathRef,
+    isRecordingRef,
   });
 
   const setAudioGroupAttribute = useSetAudioGroupAttribute({
diff --git a/packages/studio/src/utils/typingTarget.test.ts b/packages/studio/src/utils/typingTarget.test.ts
index d39528a5d6..86812349a9 100644
--- a/packages/studio/src/utils/typingTarget.test.ts
+++ b/packages/studio/src/utils/typingTarget.test.ts
@@ -54,6 +54,14 @@ describe("isTypingTarget", () => {
     expect(isTypingTarget(mount('<h1 contenteditable="false">Hi</h1>'))).toBe(false);
   });
 
+  it("keeps a modal dialog's buttons out of the global shortcuts", () => {
+    const host = mount('<div role="dialog" aria-modal="true"><button>OK</button></div>');
+    expect(isTypingTarget(host.querySelector("button"))).toBe(true);
+    expect(
+      isTypingTarget(mount('<div role="dialog"><button>OK</button></div>').querySelector("button")),
+    ).toBe(false);
+  });
+
   it("says no to nothing at all", () => {
     expect(isTypingTarget(null)).toBe(false);
     expect(isTypingTarget({} as EventTarget)).toBe(false);
diff --git a/packages/studio/src/utils/typingTarget.ts b/packages/studio/src/utils/typingTarget.ts
index 23d6c27008..a21094b69c 100644
--- a/packages/studio/src/utils/typingTarget.ts
+++ b/packages/studio/src/utils/typingTarget.ts
@@ -45,6 +45,7 @@ const TYPING_SELECTOR = [
   // `input` and matched above. Without this row the shared Toggle would let a
   // global shortcut claim Space instead of flipping the control (KTD13).
   "[role='switch']",
+  "[role='dialog'][aria-modal='true']",
   ".cm-editor",
 ].join(",");
 

From 5f523395bdbce8dbbdabfbce2724f7f3c7ccf5ac Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 12:24:49 -0700
Subject: [PATCH 06/20] fix(studio): offer link for any unlinked video and
 audio pair

Link no longer requires the same file and identical timing, matching Premiere.
Same-file pairs get a sync origin so a trimmed or moved audio shows its
offset; different files link without one. Merge back is disabled until the
pair is in sync. Linked moves keep the offset, and a trim only carries to a
partner whose edge is at the same time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/engine/mutate.ts             | 45 ++++++++++++++--
 packages/sdk/src/session.linked.test.ts       | 12 +++++
 .../components/editor/mediaLinkEdits.test.ts  | 16 +++++-
 .../src/components/editor/mediaLinkEdits.ts   | 52 ++++++++++++++-----
 .../src/hooks/timelineLinkEditPlan.test.ts    | 28 ++++++++++
 .../studio/src/hooks/timelineLinkEditPlan.ts  |  7 ++-
 .../player/components/audioClipLink.test.ts   | 13 +++++
 .../src/player/components/audioClipLink.ts    | 21 ++++++++
 .../components/clipMenuLinkItems.test.ts      | 39 ++++++++++++++
 .../player/components/clipMenuLinkItems.tsx   | 17 ++++--
 .../player/components/useTimelineClipDrag.ts  | 15 ++++--
 skills-manifest.json                          |  2 +-
 .../references/data-attributes.md             |  2 +-
 .../references/tracks-and-clips.md            |  3 +-
 14 files changed, 240 insertions(+), 32 deletions(-)

diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 4d5cc7f74d..4f2ac89bbc 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -298,16 +298,51 @@ function applySetTiming(
     const own = handleSetTiming(parsed, ids, timing);
     return concatResults(own, handleSetAttribute(parsed, unlink, MEDIA_LINK_ATTR, null));
   }
+  const before = new Map(
+    ids.map((id) => {
+      const el = resolveScoped(parsed.document, id);
+      return [el?.getAttribute(MEDIA_LINK_ATTR) ?? "", el ? readClipTiming(el) : null] as const;
+    }),
+  );
   const partners =
     op.start === undefined && op.duration === undefined
       ? []
       : linkedPartnerIds(parsed.document, ids);
   const own = handleSetTiming(parsed, ids, timing);
-  if (partners.length === 0) return own;
-  return concatResults(
-    own,
-    handleSetTiming(parsed, partners, { start: op.start, duration: op.duration }),
-  );
+  let result = own;
+  for (const partner of partners) {
+    const el = resolveScoped(parsed.document, partner);
+    const grabbed = before.get(el?.getAttribute(MEDIA_LINK_ATTR) ?? "");
+    if (!el || !grabbed) continue;
+    result = concatResults(
+      result,
+      handleSetTiming(parsed, [partner], partnerTiming(grabbed, readClipTiming(el), timing)),
+    );
+  }
+  return result;
+}
+
+type ClipWindow = { start: number | null; duration: number | null };
+const ALIGN_EPSILON_S = 1e-3;
+
+/**
+ * A partner follows the edit without resyncing: a start change shifts it by the
+ * same delta (keeping any offset); a duration change carries over only when the
+ * partner's end sat at the edited clip's end.
+ */
+function partnerTiming(
+  grabbed: ClipWindow,
+  partner: ClipWindow,
+  edit: { start?: number; duration?: number },
+): { start?: number; duration?: number } {
+  const timing: { start?: number; duration?: number } = {};
+  const [gStart, pStart] = [grabbed.start ?? 0, partner.start ?? 0];
+  if (edit.start !== undefined) timing.start = pStart + (edit.start - gStart);
+  const endsTogether =
+    Math.abs(pStart + (partner.duration ?? 0) - (gStart + (grabbed.duration ?? 0))) <
+    ALIGN_EPSILON_S;
+  if (edit.duration !== undefined && endsTogether) timing.duration = edit.duration;
+  return timing;
 }
 
 export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {
diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.ts
index 4baac66e70..e15b6ec76c 100644
--- a/packages/sdk/src/session.linked.test.ts
+++ b/packages/sdk/src/session.linked.test.ts
@@ -36,6 +36,18 @@ describe("setTiming on linked clips", () => {
     expect(attr(html, "hf-talk-audio", "data-duration")).toBe("6");
   });
 
+  it("moves a misaligned pair by the same delta, preserving the offset", async () => {
+    const html = LINKED_HTML.replace(
+      'src="talk.mp4" data-link="lk-1" data-start="2"',
+      'src="talk.mp4" data-link="lk-1" data-start="3"',
+    );
+    const comp = await openComposition(html);
+    comp.setTiming("hf-talk", { start: 5 });
+    const out = comp.serialize();
+    expect(attr(out, "hf-talk", "data-start")).toBe("5");
+    expect(attr(out, "hf-talk-audio", "data-start")).toBe("6");
+  });
+
   it("{ linked: false } edits one member and unlinks the pair", async () => {
     const comp = await openComposition(LINKED_HTML);
     comp.setTiming("hf-talk", { start: 5 }, { linked: false });
diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
index 5fbc15e534..5f171919e5 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.test.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
@@ -192,6 +192,15 @@ describe("linkInSource", () => {
   });
 });
 
+describe("linkInSource without a sync origin", () => {
+  it("writes only data-link", () => {
+    const src = '<video id="v"></video><audio id="a"></audio>';
+    expect(linkInSource(src, [{ id: "v" }, { id: "a" }], { syncOrigin: false })).toBe(
+      '<video id="v" data-link="lk-1"></video><audio id="a" data-link="lk-1"></audio>',
+    );
+  });
+});
+
 describe("setLinkInSource", () => {
   it("writes and removes data-link on every target", () => {
     const src = '<video id="v"></video><audio id="a"></audio>';
@@ -248,9 +257,12 @@ describe("predicates", () => {
     expect(findMergePair(v, [v, el("a", "audio", { src: "other.mp4" })])).toBeNull();
   });
 
-  it("links exactly one video and one audio of the same file and timing", () => {
+  it("links exactly one unlinked video and one audio, whatever their timing or file", () => {
     expect(canLinkPair([el("v", "video"), el("a", "audio")])).toBe(true);
-    expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3 })])).toBe(false);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3, duration: 2 })])).toBe(true);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { src: "other.mp3" })])).toBe(true);
+    expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio")])).toBe(false);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { link: "y" })])).toBe(false);
     expect(canLinkPair([el("v", "video"), el("w", "video")])).toBe(false);
     expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio", { link: "x" })])).toBe(
       false,
diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.ts
index 999895e721..e9538ce02c 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts
@@ -1,5 +1,10 @@
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
-import { MEDIA_LINK_ATTR, SYNC_ORIGIN_ATTR, mintLinkId } from "@hyperframes/core/media-link";
+import {
+  MEDIA_LINK_ATTR,
+  SYNC_ORIGIN_ATTR,
+  mintLinkId,
+  sourceZeroTime,
+} from "@hyperframes/core/media-link";
 import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";
 import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";
 import {
@@ -62,14 +67,20 @@ export function setLinkInSource(
   );
 }
 
-/** Link the targets under one freshly minted id, which is also their sync origin. */
-export function linkInSource(source: string, targets: readonly PatchTarget[]): string {
+/**
+ * Link the targets under one freshly minted id. Only a pair from one source file
+ * also gets that id as its sync origin, so a drifted pair shows its offset.
+ */
+export function linkInSource(
+  source: string,
+  targets: readonly PatchTarget[],
+  options: { syncOrigin: boolean } = { syncOrigin: true },
+): string {
   const linkId = mintLinkIdForSource(source);
-  return targets.reduce(
-    (html, target) =>
-      applyOps(html, target, [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]),
-    source,
-  );
+  const ops = options.syncOrigin
+    ? [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]
+    : [dataOp(LINK_PROPERTY, linkId)];
+  return targets.reduce((html, target) => applyOps(html, target, ops), source);
 }
 
 /** Remove one element (open tag through its matching close tag) and its line's indentation. */
@@ -242,15 +253,30 @@ export function findMergePair<T extends TimedElement>(
   return video.muted === true ? { video, audio } : null;
 }
 
-/** Exactly one video and one audio, same file, identical timing, not already linked together. */
+/** One video and one audio in one composition, neither linked: timing and file don't matter. */
 export function canLinkPair(selected: readonly TimedElement[]): boolean {
   if (selected.length !== 2) return false;
   const [a, b] = selected;
-  if (!a || !b) return false;
+  if (!a || !b || a.link || b.link) return false;
   const tags = new Set([tagOf(a), tagOf(b)]);
-  if (!tags.has("video") || !tags.has("audio")) return false;
-  if (sharesLinkGroup(a, b)) return false;
-  return sameAssetInScope(a, b) && hasIdenticalTiming(a, b);
+  return tags.has("video") && tags.has("audio") && sameCompositionScope(a, b);
+}
+
+/** Whether the pair comes from one source file, so the link can carry a sync origin. */
+export function sharesSourceFile(selected: readonly TimedElement[]): boolean {
+  const [a, b] = selected;
+  return selected.length === 2 && !!a && !!b && sameAssetInScope(a, b);
+}
+
+/** Both halves put source time zero at the same timeline moment, at the same rate. */
+export function isPairInSync(a: TimedElement, b: TimedElement): boolean {
+  const timing = (el: TimedElement) => ({
+    start: el.start,
+    mediaStart: el.playbackStart ?? 0,
+    playbackRate: el.playbackRate ?? 1,
+  });
+  const [x, y] = [timing(a), timing(b)];
+  return near(x.playbackRate, y.playbackRate) && near(sourceZeroTime(x), sourceZeroTime(y));
 }
 
 type TrackedElement = Pick<TimelineElement, "tag" | "track" | "start" | "duration"> & {
diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts
index 5c95035193..644e7e89ad 100644
--- a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts
+++ b/packages/studio/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");
+  });
+});
diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.ts b/packages/studio/src/hooks/timelineLinkEditPlan.ts
index c3d6bce414..56f293c816 100644
--- a/packages/studio/src/hooks/timelineLinkEditPlan.ts
+++ b/packages/studio/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);
diff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.ts
index c4e81bb248..d2fea52f60 100644
--- a/packages/studio/src/player/components/audioClipLink.test.ts
+++ b/packages/studio/src/player/components/audioClipLink.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   audioPillFlags,
   expandToLinkedMembers,
+  dropMisalignedTrimPartners,
   linkedGestureKeys,
   linkedMembersOf,
   mediaAssetIdentity,
@@ -229,3 +230,15 @@ describe("Linked Selection off", () => {
     }
   });
 });
+
+describe("dropMisalignedTrimPartners", () => {
+  const v = { id: "v", link: "lk", start: 2, duration: 6 };
+  const a = { id: "a", link: "lk", start: 3, duration: 5 };
+  const keys = new Set(["v", "a"]);
+  it("keeps a partner whose grabbed edge is at the same time", () => {
+    expect(dropMisalignedTrimPartners(keys, v, [v, a], "end")).toEqual(keys);
+  });
+  it("trims only the grabbed clip when the partner's edge is elsewhere", () => {
+    expect(dropMisalignedTrimPartners(keys, v, [v, a], "start")).toEqual(new Set(["v"]));
+  });
+});
diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.ts
index 355659d0b6..87623d5804 100644
--- a/packages/studio/src/player/components/audioClipLink.ts
+++ b/packages/studio/src/player/components/audioClipLink.ts
@@ -78,3 +78,24 @@ export function linkedGestureKeys(
   const base = selected.has(grabbedKey) ? selected : [grabbedKey];
   return expandToLinkedMembers(base, elements, linked);
 }
+
+type TimedLinked = LinkedElement & Pick<TimelineElement, "start" | "duration">;
+
+const edgeTime = (el: Pick<TimelineElement, "start" | "duration">, edge: "start" | "end") =>
+  edge === "start" ? el.start : el.start + el.duration;
+
+/** A trim drags a link partner along only when its edge sits at the grabbed clip's edge time. */
+export function dropMisalignedTrimPartners(
+  keys: ReadonlySet<string>,
+  grabbed: TimedLinked,
+  elements: readonly TimedLinked[],
+  edge: "start" | "end",
+): Set<string> {
+  const kept = new Set(keys);
+  if (!isLinked(grabbed)) return kept;
+  for (const el of elements) {
+    if (el.link !== grabbed.link || keyOf(el) === keyOf(grabbed)) continue;
+    if (Math.abs(edgeTime(el, edge) - edgeTime(grabbed, edge)) > 1e-3) kept.delete(keyOf(el));
+  }
+  return kept;
+}
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.ts
index 2c94db56b1..e76c6daa51 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.test.ts
+++ b/packages/studio/src/player/components/clipMenuLinkItems.test.ts
@@ -87,4 +87,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();
+  });
 });
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsx
index 4931b09d7e..43ef07e656 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx
+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx
@@ -2,12 +2,18 @@ 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,
+} from "../../components/editor/mediaLinkEdits";
 
 interface LinkMenuItem {
   label: string;
   shortcut?: string;
   destructive?: boolean;
+  disabledReason?: string;
   run: () => void;
 }
 
@@ -61,6 +67,7 @@ export function resolveLinkMenuItems(input: {
   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 +109,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();
diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.ts
index 327e1ca247..b8d50f1e3b 100644
--- a/packages/studio/src/player/components/useTimelineClipDrag.ts
+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts
@@ -27,7 +27,7 @@ import type {
   BlockedClipState,
 } from "./timelineClipDragTypes";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
-import { linkedGestureKeys } from "./audioClipLink";
+import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import {
@@ -242,12 +242,17 @@ export function useTimelineClipDrag({
         return;
       }
       beginGesture("resize", next.pointerId);
-      gestureSelectedKeysRef.current = linkedGestureKeys(
-        gestureSelectedKeysRef.current,
+      gestureSelectedKeysRef.current = dropMisalignedTrimPartners(
+        linkedGestureKeys(
+          gestureSelectedKeysRef.current,
+          next.element,
+          elementsRef.current,
+          next.altKey === true,
+          isLinkedSelectionOn(),
+        ),
         next.element,
         elementsRef.current,
-        next.altKey === true,
-        isLinkedSelectionOn(),
+        next.edge,
       );
       publishResizingClip(next);
     },
diff --git a/skills-manifest.json b/skills-manifest.json
index bfe3e58016..27cc9fe3c6 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -34,7 +34,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "539de2110ccdaa43",
+      "hash": "96756e9138ed43d9",
       "files": 11
     },
     "hyperframes-creative": {
diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.md
index 83d9943707..eb1b485f94 100644
--- a/skills/hyperframes-core/references/data-attributes.md
+++ b/skills/hyperframes-core/references/data-attributes.md
@@ -36,7 +36,7 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid
 | `data-volume`      | No                                                 | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`).                                                                                                                             |
 | `data-has-audio`   | Required on a timed `<video>` unless it is `muted` | `"true"` keeps the file's sound on this clip (the default for footage with sound). Silent footage uses `muted` instead; a video with neither fails lint (`video_missing_muted`).                                                                                                                                                                                   |
 | `data-link`        | No                                                 | Editing contract only (render ignores it): clips sharing an id, e.g. a video and the `<audio>` detached from it in Studio, are edited as one. Keep every member's `data-start`, `data-duration`, `data-media-start` and `data-playback-rate` equal; to unlink, remove the attribute from all members. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips). |
-| `data-sync-origin` | No                                                 | Editing contract only: a video and audio from one source file share it (written by Detach and Link, kept by Unlink). Studio flags the pair out of sync when their source-zero points differ. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips).                                                                                                          |
+| `data-sync-origin` | No                                                 | Editing contract only: a video and audio from one source file share it (written by Detach, and by Link for same-file pairs; kept by Unlink). Studio flags the pair out of sync when their source-zero points differ. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips).                                                                                  |
 
 **The visibility window is half-open: `[start, start + duration)`.** A clip shows while `start ≤ t < start + duration` and is hidden at exactly `t = start + duration`. Land an animation's resolved end state slightly **before** `data-duration`, not on it, or its last frame is never rendered. Two clips can therefore be authored back to back (`b.start === a.start + a.duration`) with no overlapping frame.
 
diff --git a/skills/hyperframes-core/references/tracks-and-clips.md b/skills/hyperframes-core/references/tracks-and-clips.md
index 72b1a51f49..2e9f3ffdde 100644
--- a/skills/hyperframes-core/references/tracks-and-clips.md
+++ b/skills/hyperframes-core/references/tracks-and-clips.md
@@ -76,11 +76,12 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio
 ></audio>
 ```
 
+- **Link offer.** Studio offers Link for exactly one video and one audio, neither already linked; their timing and source file don't matter. A linked pair that is offset moves together (the offset is kept), and a trim carries to the partner only when its edge sits at the same time. Merge back needs the same file and an in-sync pair.
 - **Keep members in sync.** Every member needs the same `data-start`, `data-duration`, `data-media-start` (absent = 0) and `data-playback-rate` (absent = 1). Track index, volume, fades and FX may differ. When you retime one member by hand, retime all of them, or `lint` warns `linked_clips_out_of_sync`.
 - **Unlink** by removing `data-link` from every member. Removing it from one leaves the other alone with the id, which `lint` flags as `linked_clip_orphan`.
 - The render ignores `data-link`: an out-of-sync pair still plays exactly what its timings say.
 - Prefer a single `<video data-has-audio="true">` for footage with sound. Link only when the sound needs its own clip (its own track, volume or FX); to undo a detach, move the audio attributes back onto the video and delete the `<audio>`.
-- **Sync origin.** `data-sync-origin="<id>"` marks a video and an audio from one source file; Detach and Link write it, and Unlink keeps it. When the pair drifts (their source-zero points, `data-start − data-media-start / data-playback-rate`, differ), Studio shows a red offset in frames on both halves with Move into Sync / Slip into Sync, `hyperframes timeline` prints `out-of-sync=±Nf`, and the SDK offers `syncOffset`, `moveIntoSync` and `slipIntoSync`. Leave it alone when retiming by hand; remove it only when the clips are no longer one source.
+- **Sync origin.** `data-sync-origin="<id>"` marks a video and an audio from one source file; Detach writes it, Link writes it only for a pair from one source file, and Unlink keeps it. When the pair drifts (their source-zero points, `data-start − data-media-start / data-playback-rate`, differ), Studio shows a red offset in frames on both halves with Move into Sync / Slip into Sync, `hyperframes timeline` prints `out-of-sync=±Nf`, and the SDK offers `syncOffset`, `moveIntoSync` and `slipIntoSync`. Leave it alone when retiming by hand; remove it only when the clips are no longer one source.
 - `@hyperframes/sdk` `setTiming` applies to link partners by default; pass `{ linked: false }` to edit one member, which unlinks it.
 
 ## Relative Timing

From 89482339f1203a69f461e2adc9e7e6473e660872 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 13:12:26 -0700
Subject: [PATCH 07/20] fix(studio): shift and cmd-click add timeline clips to
 the selection

A modifier click on a clip replaced the selection, so a video and an audio
could never both be selected and Link never appeared. Shift, Cmd and Ctrl
now toggle the clip (and its link partners unless Alt) in the selection;
Shift no longer turns a clip click into a time-range popover.

Right-clicking a lone unlinked video or audio offers Link when exactly one
opposite-kind clip from the same file sits on another track.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../player/components/TimelineLanes.test.tsx  | 25 ++++++++-
 .../src/player/components/TimelineLanes.tsx   |  2 -
 .../player/components/audioClipLink.test.ts   | 47 ++++++++++++++++
 .../components/clipMenuLinkItems.test.ts      | 45 +++++++++++++++
 .../player/components/clipMenuLinkItems.tsx   | 48 ++++++++++++++--
 .../components/timelineClipGestureHandlers.ts | 56 +++++++++----------
 .../player/components/timelineEditing.test.ts | 13 -----
 .../src/player/components/timelineEditing.ts  | 11 ----
 .../player/components/timelineLaneProps.ts    |  5 --
 .../components/timelineLinkSelection.ts       | 26 ++++++++-
 .../components/useTimelineOverlaysState.ts    |  3 -
 .../components/useTimelineProviderState.tsx   |  2 -
 .../components/useTimelineRangeSelection.ts   | 14 -----
 13 files changed, 207 insertions(+), 90 deletions(-)

diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx
index 6b374ea93f..ab04dd925a 100644
--- a/packages/studio/src/player/components/TimelineLanes.test.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx
@@ -163,7 +163,6 @@ function renderLanes(options: RenderLanesOptions = {}): {
           setResizingClip={vi.fn()}
           setDraggedClip={vi.fn()}
           setSelectedElementId={setSelectedElementId}
-          shiftClickClipRef={createRef()}
           getPreviewElement={(el) => el}
           getTrackStyle={getTrackStyle}
           gsapAnimations={gsapAnimations}
@@ -439,6 +438,30 @@ describe("TimelineLanes selection", () => {
     expect(view.onSelectElement).toHaveBeenCalledWith(selected);
     act(() => view.root.unmount());
   });
+
+  it.each([["shiftKey"], ["metaKey"], ["ctrlKey"]])(
+    "%s-click adds a clip to the selection instead of replacing it",
+    (modifier) => {
+      const first = element("clip-a", TRACK_A);
+      const second = element("clip-b", TRACK_B);
+      usePlayerStore.getState().setElements([first, second]);
+      usePlayerStore.getState().setSelection([first.id], first.id);
+      const view = renderLanes({ elements: [first, second] });
+      const clipB = view.host.querySelector('[data-el-id="clip-b"]');
+      const click = (init: MouseEventInit) =>
+        act(() => clipB?.dispatchEvent(new MouseEvent("click", { bubbles: true, ...init })));
+
+      click({ [modifier]: true });
+      expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a", "clip-b"]));
+      expect(view.setSelectedElementId).not.toHaveBeenCalled();
+      expect(view.onSelectElement).toHaveBeenLastCalledWith(second);
+
+      click({ [modifier]: true });
+      expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a"]));
+      expect(view.onSelectElement).toHaveBeenLastCalledWith(first);
+      act(() => view.root.unmount());
+    },
+  );
 });
 
 describe("TimelineLanes clip thumbnails", () => {
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index 6ccedb5856..5652419c09 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -77,7 +77,6 @@ export function TimelineLanes({
   setResizingClip,
   setDraggedClip,
   setSelectedElementId,
-  shiftClickClipRef,
   getPreviewElement,
   getTrackStyle,
   keyframeCache,
@@ -404,7 +403,6 @@ export function TimelineLanes({
                         onRazorSplit,
                         onRazorSplitAll,
                         blockedClipRef,
-                        shiftClickClipRef,
                         suppressClickRef,
                         scrollRef,
                         setShowPopover,
diff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.ts
index d2fea52f60..3a023cec66 100644
--- a/packages/studio/src/player/components/audioClipLink.test.ts
+++ b/packages/studio/src/player/components/audioClipLink.test.ts
@@ -205,6 +205,53 @@ describe("selectClipWithLinks", () => {
   });
 });
 
+describe("toggleClipWithLinks", () => {
+  const clips = [
+    { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },
+    { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },
+    { id: "title", tag: "div", start: 0, duration: 4, track: 2 },
+    { id: "music", tag: "audio", start: 0, duration: 4, track: 3 },
+  ];
+
+  async function store() {
+    const { usePlayerStore } = await import("../store/playerStore");
+    const { toggleClipWithLinks } = await import("./timelineLinkSelection");
+    usePlayerStore.getState().setElements(clips);
+    usePlayerStore.getState().setSelection(["title"], "title");
+    return { usePlayerStore, toggle: toggleClipWithLinks };
+  }
+
+  it("adds an unlinked clip to the selection and makes it primary", async () => {
+    const { usePlayerStore, toggle } = await store();
+    expect(toggle("music", false)?.id).toBe("music");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title", "music"]));
+    expect(usePlayerStore.getState().selectedElementId).toBe("music");
+  });
+
+  it("adding a linked clip adds its partner too", async () => {
+    const { usePlayerStore, toggle } = await store();
+    toggle("talk-audio", false);
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(
+      new Set(["title", "talk", "talk-audio"]),
+    );
+  });
+
+  it("toggling a selected clip removes it and its partner, keeping the rest", async () => {
+    const { usePlayerStore, toggle } = await store();
+    toggle("talk", false);
+    expect(toggle("talk", false)?.id).toBe("title");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title"]));
+    expect(toggle("title", false)).toBeNull();
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set());
+  });
+
+  it("Alt adds only the clicked member of a linked pair", async () => {
+    const { usePlayerStore, toggle } = await store();
+    toggle("talk", true);
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title", "talk"]));
+  });
+});
+
 describe("Linked Selection off", () => {
   const linkedPair = [
     { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.ts
index e76c6daa51..1a4c9e30ea 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.test.ts
+++ b/packages/studio/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" });
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsx
index 43ef07e656..abd02d8f31 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx
+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx
@@ -7,6 +7,7 @@ import {
   canLinkPair,
   findMergePair,
   isPairInSync,
+  sharesSourceFile,
 } from "../../components/editor/mediaLinkEdits";
 
 interface LinkMenuItem {
@@ -21,6 +22,23 @@ const keyOf = (el: TimelineElement) => el.key ?? el.id;
 
 const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();
 
+/** The one unlinked opposite-kind clip from the same file on another track, if exactly one exists. */
+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;
@@ -29,6 +47,27 @@ function partnerSuffix(element: TimelineElement, others: readonly TimelineElemen
   return pair === "audio+video" ? ` ${tagOf(partner)}` : "";
 }
 
+/** Link for an explicitly selected video+audio pair, else for the lone same-file partner of a sole selection. */
+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;
@@ -56,12 +95,9 @@ 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) {
diff --git a/packages/studio/src/player/components/timelineClipGestureHandlers.ts b/packages/studio/src/player/components/timelineClipGestureHandlers.ts
index 885d3692cf..2eb849851c 100644
--- a/packages/studio/src/player/components/timelineClipGestureHandlers.ts
+++ b/packages/studio/src/player/components/timelineClipGestureHandlers.ts
@@ -8,7 +8,7 @@ import {
 import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { CLIP_HANDLE_W } from "./timelineLayout";
-import { selectClipWithLinks } from "./timelineLinkSelection";
+import { selectClipWithLinks, toggleClipWithLinks } from "./timelineLinkSelection";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 
 export interface ClipGestureDeps {
@@ -18,11 +18,6 @@ export interface ClipGestureDeps {
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
   blockedClipRef: React.RefObject<BlockedClipState | null>;
-  shiftClickClipRef: React.RefObject<{
-    element: TimelineElement;
-    anchorX: number;
-    anchorY: number;
-  } | null>;
   suppressClickRef: React.RefObject<boolean>;
   scrollRef: React.RefObject<HTMLDivElement | null>;
   setShowPopover(v: boolean): void;
@@ -45,9 +40,11 @@ function canStartResize(
   return capabilities.canTrimEnd;
 }
 
+const isAdditiveClick = (e: { shiftKey: boolean; metaKey: boolean; ctrlKey: boolean }) =>
+  e.shiftKey || e.metaKey || e.ctrlKey;
+
 type PointerDownAction =
   | { kind: "ignore" }
-  | { kind: "arm-shift-click" }
   | { kind: "block"; intent: BlockedTimelineEditIntent; rect: DOMRect }
   | { kind: "move"; rect: DOMRect };
 
@@ -82,7 +79,7 @@ function resolvePointerDownAction(
 ): PointerDownAction {
   if (e.button !== 0) return { kind: "ignore" };
   if (usePlayerStore.getState().activeTool === "razor") return { kind: "ignore" };
-  if (e.shiftKey) return { kind: "arm-shift-click" };
+  if (isAdditiveClick(e)) return { kind: "ignore" };
 
   const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
   const intent = resolveBlockedTimelineEditIntent({
@@ -119,7 +116,6 @@ export function createClipGestureHandlers(
     onRazorSplit,
     onRazorSplitAll,
     blockedClipRef,
-    shiftClickClipRef,
     suppressClickRef,
     scrollRef,
     setShowPopover,
@@ -154,11 +150,6 @@ export function createClipGestureHandlers(
     const action = resolvePointerDownAction(e, capabilities, onResizeElement, onMoveElement);
     if (action.kind === "ignore") return;
 
-    if (action.kind === "arm-shift-click") {
-      shiftClickClipRef.current = { element: el, anchorX: e.clientX, anchorY: e.clientY };
-      return;
-    }
-
     if (action.kind === "block") {
       blockedClipRef.current = {
         pointerId: e.pointerId,
@@ -197,26 +188,29 @@ export function createClipGestureHandlers(
     });
   };
 
+  const razorSplit = (e: ReactMouseEvent, split: NonNullable<typeof onRazorSplit>): void => {
+    const clipRect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+    const splitTime = previewElement.start + (e.clientX - clipRect.left) / pps;
+    const clampedTime = Math.max(
+      previewElement.start + SPLIT_BOUNDARY_EPSILON_S,
+      Math.min(
+        previewElement.start + previewElement.duration - SPLIT_BOUNDARY_EPSILON_S,
+        splitTime,
+      ),
+    );
+    if (e.shiftKey && onRazorSplitAll) onRazorSplitAll(clampedTime);
+    else split(el, clampedTime);
+  };
+
   const onClick = (e: ReactMouseEvent): void => {
     e.stopPropagation();
     if (suppressClickRef.current) return;
-    const { activeTool } = usePlayerStore.getState();
-    if (activeTool === "razor" && onRazorSplit) {
-      const clipRect = (e.currentTarget as HTMLElement).getBoundingClientRect();
-      const clickOffsetX = e.clientX - clipRect.left;
-      const splitTime = previewElement.start + clickOffsetX / pps;
-      const clampedTime = Math.max(
-        previewElement.start + SPLIT_BOUNDARY_EPSILON_S,
-        Math.min(
-          previewElement.start + previewElement.duration - SPLIT_BOUNDARY_EPSILON_S,
-          splitTime,
-        ),
-      );
-      if (e.shiftKey && onRazorSplitAll) {
-        onRazorSplitAll(clampedTime);
-      } else {
-        onRazorSplit(el, clampedTime);
-      }
+    if (usePlayerStore.getState().activeTool === "razor" && onRazorSplit) {
+      razorSplit(e, onRazorSplit);
+      return;
+    }
+    if (isAdditiveClick(e)) {
+      onSelectElement?.(toggleClipWithLinks(elementKey, e.altKey));
       return;
     }
     // Clip selection is idempotent; empty timeline space owns deselection.
diff --git a/packages/studio/src/player/components/timelineEditing.test.ts b/packages/studio/src/player/components/timelineEditing.test.ts
index 638ab1f6de..534163f047 100644
--- a/packages/studio/src/player/components/timelineEditing.test.ts
+++ b/packages/studio/src/player/components/timelineEditing.test.ts
@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import {
-  buildClipRangeSelection,
   buildPromptCopyText,
   buildTimelineElementAgentPrompt,
   buildTimelineAgentPrompt,
@@ -607,18 +606,6 @@ describe("resolveBlockedTimelineEditIntent", () => {
   });
 });
 
-describe("buildClipRangeSelection", () => {
-  it("anchors the full clip range at the click position", () => {
-    expect(
-      buildClipRangeSelection({ start: 1.25, duration: 3.5 }, { anchorX: 320, anchorY: 180 }),
-    ).toEqual({
-      start: 1.25,
-      end: 4.75,
-      anchorX: 320,
-      anchorY: 180,
-    });
-  });
-});
 describe("resolveTimelineAutoScroll", () => {
   it("does not scroll when the pointer stays away from the edges", () => {
     expect(
diff --git a/packages/studio/src/player/components/timelineEditing.ts b/packages/studio/src/player/components/timelineEditing.ts
index c5d471db0c..e6cea2885a 100644
--- a/packages/studio/src/player/components/timelineEditing.ts
+++ b/packages/studio/src/player/components/timelineEditing.ts
@@ -382,17 +382,6 @@ export function resolveBlockedTimelineEditIntent(input: {
   return "move";
 }
 
-export function buildClipRangeSelection(
-  clip: { start: number; duration: number },
-  anchor: { anchorX: number; anchorY: number },
-): TimelineRangeSelection {
-  return {
-    start: clip.start,
-    end: clip.start + clip.duration,
-    anchorX: anchor.anchorX,
-    anchorY: anchor.anchorY,
-  };
-}
 export function buildTimelineAgentPrompt({
   rangeStart,
   rangeEnd,
diff --git a/packages/studio/src/player/components/timelineLaneProps.ts b/packages/studio/src/player/components/timelineLaneProps.ts
index f0299256cc..a2893929d5 100644
--- a/packages/studio/src/player/components/timelineLaneProps.ts
+++ b/packages/studio/src/player/components/timelineLaneProps.ts
@@ -66,11 +66,6 @@ export interface TimelineLaneBaseProps {
   setResizingClip: (v: ResizingClipState | null) => void;
   setDraggedClip: (v: DraggedClipState | null) => void;
   setSelectedElementId: (id: string | null) => void;
-  shiftClickClipRef: React.RefObject<{
-    element: TimelineElement;
-    anchorX: number;
-    anchorY: number;
-  } | null>;
   getPreviewElement: (element: TimelineElement) => TimelineElement;
   getTrackStyle: (tag: string) => TrackVisualStyle;
   keyframeCache?: Map<string, KeyframeCacheEntry>;
diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.ts
index 231ee2df94..ca4d52ec16 100644
--- a/packages/studio/src/player/components/timelineLinkSelection.ts
+++ b/packages/studio/src/player/components/timelineLinkSelection.ts
@@ -1,5 +1,5 @@
-import { usePlayerStore } from "../store/playerStore";
-import { expandToLinkedMembers } from "./audioClipLink";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { expandToLinkedMembers, linkedMembersOf } from "./audioClipLink";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 
 /**
@@ -21,3 +21,25 @@ export function selectClipWithLinks(
   const expanded = expandToLinkedMembers(selectedElementIds, elements);
   if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);
 }
+
+/**
+ * Shift/Cmd-click: toggle `key` in the selection, taking its link partners along
+ * unless Alt (or Linked Selection off) singles it out. Returns the new primary.
+ */
+export function toggleClipWithLinks(key: string, altKey: boolean): TimelineElement | null {
+  const state = usePlayerStore.getState();
+  const element = state.elements.find((el) => (el.key ?? el.id) === key);
+  const members = element
+    ? linkedMembersOf(element, state.elements, !altKey && isLinkedSelectionOn())
+    : [];
+  const memberKeys = members.length > 0 ? members.map((el) => el.key ?? el.id) : [key];
+  const next = new Set(state.selectedElementIds);
+  const removing = next.has(key);
+  for (const memberKey of memberKeys) {
+    if (removing) next.delete(memberKey);
+    else next.add(memberKey);
+  }
+  state.setSelection(next, removing ? state.selectedElementId : key);
+  const primary = usePlayerStore.getState().selectedElementId;
+  return state.elements.find((el) => (el.key ?? el.id) === primary) ?? null;
+}
diff --git a/packages/studio/src/player/components/useTimelineOverlaysState.ts b/packages/studio/src/player/components/useTimelineOverlaysState.ts
index 15acbdc36c..dbdc498e29 100644
--- a/packages/studio/src/player/components/useTimelineOverlaysState.ts
+++ b/packages/studio/src/player/components/useTimelineOverlaysState.ts
@@ -32,7 +32,6 @@ type OverlayStateInputs = Omit<
 
 export type TimelineOverlaysStateResult = {
   overlays: TimelineOverlaysState;
-  shiftClickClipRef: ReturnType<typeof useTimelineRangeSelection>["shiftClickClipRef"];
   marqueeRect: ReturnType<typeof useTimelineRangeSelection>["marqueeRect"];
   isScrubbing: ReturnType<typeof useTimelineRangeSelection>["isScrubbing"];
   handlePointerDown: ReturnType<typeof useTimelineRangeSelection>["handlePointerDown"];
@@ -55,7 +54,6 @@ export function useTimelineOverlaysState({
   const {
     rangeSelection,
     setRangeSelection,
-    shiftClickClipRef,
     marqueeRect,
     isScrubbing,
     handlePointerDown,
@@ -86,7 +84,6 @@ export function useTimelineOverlaysState({
       onCloseAllTrackGaps: gap.closeAllTrackGaps,
       onHoverGapAction: gap.setHoveredGapAction,
     },
-    shiftClickClipRef,
     marqueeRect,
     isScrubbing,
     handlePointerDown,
diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsx
index bb67de3585..d5c9d461a5 100644
--- a/packages/studio/src/player/components/useTimelineProviderState.tsx
+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx
@@ -420,7 +420,6 @@ export function useTimelineProviderState({
     gapHighlight,
     openGapMenu,
     onContextMenuClip,
-    shiftClickClipRef,
     marqueeRect,
     isScrubbing,
     handlePointerDown,
@@ -503,7 +502,6 @@ export function useTimelineProviderState({
     setResizingClip,
     setDraggedClip,
     setSelectedElementId,
-    shiftClickClipRef,
     getPreviewElement,
     getTrackStyle,
     keyframeCache,
diff --git a/packages/studio/src/player/components/useTimelineRangeSelection.ts b/packages/studio/src/player/components/useTimelineRangeSelection.ts
index 3213548a99..efa232698f 100644
--- a/packages/studio/src/player/components/useTimelineRangeSelection.ts
+++ b/packages/studio/src/player/components/useTimelineRangeSelection.ts
@@ -1,6 +1,5 @@
 import { useRef, useState, useCallback, useEffect } from "react";
 import {
-  buildClipRangeSelection,
   applyTimelineAutoScrollStep,
   resolveTimelineAutoScrollLoopAction,
   type TimelineRangeSelection,
@@ -149,11 +148,6 @@ export function useTimelineRangeSelection({
   // rendering). Drives the playhead head's filled-vs-hollow state.
   const [isScrubbing, setIsScrubbing] = useState(false);
   const [rangeSelection, setRangeSelection] = useState<TimelineRangeSelection | null>(null);
-  const shiftClickClipRef = useRef<{
-    element: TimelineElement;
-    anchorX: number;
-    anchorY: number;
-  } | null>(null);
 
   const seekRafRef = useRef(0);
   const pendingClientXRef = useRef(0);
@@ -322,7 +316,6 @@ export function useTimelineRangeSelection({
         beginRangeSelection(e);
         return;
       }
-      shiftClickClipRef.current = null;
       if ((e.target as HTMLElement).closest("[data-clip]")) return;
       (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
       activePointerIdRef.current = e.pointerId;
@@ -427,13 +420,7 @@ export function useTimelineRangeSelection({
   // clip range), otherwise clear it.
   const finishRangeSelection = useCallback(() => {
     isRangeSelecting.current = false;
-    const pendingShiftClick = shiftClickClipRef.current;
-    shiftClickClipRef.current = null;
     setRangeSelection((prev) => {
-      if (prev && pendingShiftClick && Math.abs(prev.end - prev.start) <= 0.2) {
-        setShowPopover(true);
-        return buildClipRangeSelection(pendingShiftClick.element, pendingShiftClick);
-      }
       if (prev && Math.abs(prev.end - prev.start) > 0.2) {
         setShowPopover(true);
         return prev;
@@ -589,7 +576,6 @@ export function useTimelineRangeSelection({
   return {
     rangeSelection,
     setRangeSelection,
-    shiftClickClipRef,
     marqueeRect,
     isScrubbing,
     handlePointerDown,

From 5f3cac7879e20c7e79e0c490e5b820348569e743 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 13:51:47 -0700
Subject: [PATCH 08/20] fix(studio): keep audio inside its partner video and
 make cmd-click add in every host

A modifier click passed the toggle as an argument to an optional
onSelectElement call, so hosts without that handler (desktop) never ran it.

An audio clip linked to a video, or sharing its sync origin, now stays
inside that video's span while dragged or trimmed, Alt edits included,
unless the video moves or trims in the same gesture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../player/components/TimelineLanes.test.tsx  | 22 +++++-
 .../src/player/components/audioClipLink.ts    | 50 ++++++++++++
 .../timelineClipDragPreview.test.ts           | 78 +++++++++++++++++++
 .../components/timelineClipDragPreview.ts     | 29 +++++--
 .../components/timelineClipGestureHandlers.ts |  3 +-
 .../player/components/useTimelineClipDrag.ts  |  2 +
 6 files changed, 176 insertions(+), 8 deletions(-)

diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx
index ab04dd925a..8a2e6834f9 100644
--- a/packages/studio/src/player/components/TimelineLanes.test.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx
@@ -83,8 +83,14 @@ interface RenderLanesOptions {
   hoveredClip?: string | null;
   renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];
   snapGuide?: { time: number; type: "beat" | "clip-edge" | "playhead" } | null;
+  withoutSelectHandler?: boolean;
 }
 
+const selectHandlerFor = (
+  options: RenderLanesOptions,
+  handler: (element: TimelineElement | null) => void,
+) => (options.withoutSelectHandler ? undefined : handler);
+
 function renderLanes(options: RenderLanesOptions = {}): {
   host: HTMLDivElement;
   root: Root;
@@ -173,7 +179,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
           onTogglePropertyGroupKeyframe={vi.fn()}
           onResizeElement={vi.fn()}
           onMoveElement={vi.fn()}
-          onSelectElement={onSelectElement}
+          onSelectElement={selectHandlerFor(next, onSelectElement)}
           onRazorSplit={vi.fn()}
           onRazorSplitAll={vi.fn()}
         />,
@@ -462,6 +468,20 @@ describe("TimelineLanes selection", () => {
       act(() => view.root.unmount());
     },
   );
+  it("Cmd-click adds a clip in a host that passes no onSelectElement", () => {
+    const first = element("clip-a", TRACK_A);
+    const second = element("clip-b", TRACK_B);
+    usePlayerStore.getState().setElements([first, second]);
+    usePlayerStore.getState().setSelection([first.id], first.id);
+    const view = renderLanes({ elements: [first, second], withoutSelectHandler: true });
+    act(() =>
+      view.host
+        .querySelector('[data-el-id="clip-b"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true, metaKey: true })),
+    );
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a", "clip-b"]));
+    act(() => view.root.unmount());
+  });
 });
 
 describe("TimelineLanes clip thumbnails", () => {
diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.ts
index 87623d5804..8d33ea55de 100644
--- a/packages/studio/src/player/components/audioClipLink.ts
+++ b/packages/studio/src/player/components/audioClipLink.ts
@@ -1,4 +1,5 @@
 import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";
+import { syncPartnerOf } from "./clipSync";
 
 type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;
 type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;
@@ -99,3 +100,52 @@ export function dropMisalignedTrimPartners(
   }
   return kept;
 }
+
+type BoundedElement = Pick<
+  TimelineElement,
+  | "id"
+  | "key"
+  | "tag"
+  | "start"
+  | "duration"
+  | "link"
+  | "syncOrigin"
+  | "playbackStart"
+  | "playbackRate"
+>;
+
+const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
+
+/** The timeline span of an audio clip's video: linked to it, else from the same source (sync origin). */
+function partnerVideoBounds(
+  audio: BoundedElement,
+  elements: readonly BoundedElement[],
+): { videoKey: string; start: number; end: number } | null {
+  if (tagOf(audio) !== "audio") return null;
+  const linkedVideo = isLinked(audio)
+    ? elements.find((el) => el.link === audio.link && tagOf(el) === "video")
+    : undefined;
+  const video = linkedVideo ?? syncPartnerOf(audio, elements);
+  return video
+    ? { videoKey: keyOf(video), start: video.start, end: video.start + video.duration }
+    : null;
+}
+
+/** `start` moved so a clip of `duration` sits inside `bounds`; a clip longer than them pins to their start. */
+export function clampStartIntoBounds(
+  start: number,
+  duration: number,
+  bounds: { start: number; end: number },
+): number {
+  return Math.max(bounds.start, Math.min(start, bounds.end - duration));
+}
+
+/** The partner video's span, unless that video moves in the same gesture. */
+export function heldPartnerVideoBounds(
+  audio: BoundedElement,
+  elements: readonly BoundedElement[],
+  gestureKeys: ReadonlySet<string>,
+): { start: number; end: number } | null {
+  const bounds = partnerVideoBounds(audio, elements);
+  return bounds && !gestureKeys.has(bounds.videoKey) ? bounds : null;
+}
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.test.ts b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
index f1be7cbb43..cd869d13b7 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.test.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
@@ -726,3 +726,81 @@ describe("a nested clip's drop stops at its host's start in the preview", () =>
     expect(await saved(early, 1)).toBe(1);
   });
 });
+
+describe("an audio clip stays inside its partner video", () => {
+  const video = (extra: Partial<TimelineElement> = {}) => ({
+    ...clip("v", 0, 10, 20, 1),
+    syncOrigin: "lk-1",
+    ...extra,
+  });
+  const audio = (extra: Partial<TimelineElement> = {}) => ({
+    ...clip("a", 1, 12, 8, 0, "audio"),
+    syncOrigin: "lk-1",
+    ...extra,
+  });
+  const audioCtx = (elements: TimelineElement[], selected: string[] = []) => ({
+    ...ctx(undefined, elements),
+    trackOrder: [0, 1],
+    audioTracks: new Set([1]),
+    selectedKeys: new Set(selected),
+  });
+
+  it("a drag past the video's end stops with the audio's end on it", () => {
+    const a = audio();
+    const { drag, clientX, clientY } = horizontalDrag(a, 1.5, 30);
+    expect(computeDragPreview(drag, clientX, clientY, audioCtx([video(), a])).previewStart).toBe(
+      22,
+    );
+  });
+
+  it("a drag before the video's start stops at it, linked or same-source", () => {
+    const linked = audio({ syncOrigin: undefined, link: "lk-9" });
+    const { drag, clientX, clientY } = horizontalDrag(linked, 1.5, -10);
+    const elements = [video({ syncOrigin: undefined, link: "lk-9" }), linked];
+    expect(computeDragPreview(drag, clientX, clientY, audioCtx(elements)).previewStart).toBe(10);
+  });
+
+  it("moves freely with no partner video, or when the video moves with it", () => {
+    const loose = audio({ syncOrigin: undefined });
+    const free = horizontalDrag(loose, 1.5, 30);
+    expect(
+      computeDragPreview(free.drag, free.clientX, free.clientY, audioCtx([video(), loose]))
+        .previewStart,
+    ).toBe(42);
+    const a = audio();
+    const both = horizontalDrag(a, 1.5, 30);
+    expect(
+      computeDragPreview(both.drag, both.clientX, both.clientY, audioCtx([video(), a], ["v", "a"]))
+        .previewStart,
+    ).toBe(42);
+  });
+
+  const trim = (edge: "start" | "end", deltaSeconds: number, gestureKeys: string[] = []) =>
+    computeResizePreview(
+      {
+        element: audio({ sourceDuration: 100, playbackStart: 20 }),
+        edge,
+        originClientX: 0,
+        previewStart: 12,
+        previewDuration: 8,
+        started: true,
+      },
+      deltaSeconds * 100,
+      {
+        scroll: fakeScroll(),
+        pps: 100,
+        buildSnapTargets: () => [],
+        elements: [video(), audio()],
+        gestureKeys: new Set(["a", ...gestureKeys]),
+      },
+    );
+
+  it("a trim cannot extend past the video's start or end", () => {
+    expect(trim("end", 50)).toMatchObject({ previewStart: 12, previewDuration: 18 });
+    expect(trim("start", -10)).toMatchObject({ previewStart: 10, previewDuration: 10 });
+  });
+
+  it("a trim carried by the video too is not held to the video's old span", () => {
+    expect(trim("end", 50, ["v"]).previewDuration).toBe(58);
+  });
+});
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.ts
index 52668e7af7..456a50c1ed 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts
@@ -23,6 +23,7 @@ import {
 import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";
 import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
 import { STUDIO_PREVIEW_FPS } from "../lib/time";
+import { clampStartIntoBounds, heldPartnerVideoBounds } from "./audioClipLink";
 
 /** Snap-target builder closure supplied by the hook (closes over refs + store). */
 type BuildSnapTargets = (
@@ -111,6 +112,8 @@ interface GroupDrag {
   obstacles: TimelineElement[];
   /** Lowest start the grabbed clip may take (see groupMoveFloor). */
   floor: number;
+  /** Every clip the gesture moves, the grabbed one included. */
+  moving: ReadonlySet<string>;
 }
 
 function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): GroupDrag {
@@ -119,11 +122,15 @@ function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): Grou
     ctx.selectedKeys,
     drag.element.key ?? drag.element.id,
   );
-  if (!movers) return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []) };
+  if (!movers) {
+    const moving = new Set([drag.element.key ?? drag.element.id]);
+    return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []), moving };
+  }
   const moving = new Set(movers.map((e) => e.key ?? e.id));
   return {
     obstacles: ctx.elements.filter((e) => !moving.has(e.key ?? e.id)),
     floor: groupMoveFloor(drag.element, movers),
+    moving,
   };
 }
 
@@ -179,7 +186,11 @@ export function computeDragPreview(
   );
   // A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
   const group = resolveGroupDrag(drag, ctx);
-  const previewStart = Math.max(snap.start, group.floor);
+  const video = heldPartnerVideoBounds(drag.element, ctx.elements, group.moving);
+  const floored = Math.max(snap.start, group.floor);
+  const previewStart = video
+    ? clampStartIntoBounds(floored, drag.element.duration, video)
+    : floored;
   const placement = resolveDropPlacement(drag, clientY, previewStart, nextMove.track, ctx, group);
   const { track: previewTrack, insertRow } = placement;
   return {
@@ -210,6 +221,9 @@ export interface ResizePreviewContext {
   scroll: HTMLDivElement | null;
   pps: number;
   buildSnapTargets: BuildSnapTargets;
+  /** With them, an audio trim stays inside its partner video unless the video trims with it. */
+  elements?: readonly TimelineElement[];
+  gestureKeys?: ReadonlySet<string>;
 }
 
 export interface ResizePreviewResult {
@@ -253,14 +267,18 @@ export function computeResizePreview(
   // rightward and, after a far move, collapsed a clip to the sliver between its
   // start and the comp end (the 8s→0.95s audio incident). Images/text/shapes
   // have no source, so they extend freely.
-  const maxEnd = resize.element.start + sourceRemaining;
+  const video = ctx.elements
+    ? heldPartnerVideoBounds(resize.element, ctx.elements, ctx.gestureKeys ?? new Set())
+    : null;
+  const minStart = Math.max(clampToHostStart(resize.element, 0), video?.start ?? 0);
+  const maxEnd = Math.min(resize.element.start + sourceRemaining, video?.end ?? Infinity);
   let nextResize = resolveTimelineResize(
     {
       start: resize.element.start,
       duration: resize.element.duration,
       originClientX: resize.originClientX,
       pixelsPerSecond: pps,
-      minStart: clampToHostStart(resize.element, 0),
+      minStart,
       maxEnd,
       playbackStart:
         resize.edge === "start" && canSeedPlaybackStart
@@ -303,8 +321,7 @@ export function computeResizePreview(
       const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);
       const clip = { ...nextResize, playbackRate: resize.element.playbackRate };
       const delta = snapped - nextResize.start;
-      const floor = clampToHostStart(resize.element, 0);
-      const bounds = clipStartTrimDeltaBounds(clip, floor, resolveTimelineMinDuration());
+      const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());
       if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {
         if (snapped !== nextResize.start) nextResize = applyClipStartTrimDelta(clip, delta);
         snap = target;
diff --git a/packages/studio/src/player/components/timelineClipGestureHandlers.ts b/packages/studio/src/player/components/timelineClipGestureHandlers.ts
index 2eb849851c..4d69d460fb 100644
--- a/packages/studio/src/player/components/timelineClipGestureHandlers.ts
+++ b/packages/studio/src/player/components/timelineClipGestureHandlers.ts
@@ -210,7 +210,8 @@ export function createClipGestureHandlers(
       return;
     }
     if (isAdditiveClick(e)) {
-      onSelectElement?.(toggleClipWithLinks(elementKey, e.altKey));
+      const primary = toggleClipWithLinks(elementKey, e.altKey);
+      onSelectElement?.(primary);
       return;
     }
     // Clip selection is idempotent; empty timeline space owns deselection.
diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.ts
index b8d50f1e3b..65772912a5 100644
--- a/packages/studio/src/player/components/useTimelineClipDrag.ts
+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts
@@ -329,6 +329,8 @@ export function useTimelineClipDrag({
         scroll: scrollRef.current,
         pps: ppsRef.current,
         buildSnapTargets,
+        elements: elementsRef.current,
+        gestureKeys: gestureSelectedKeysRef.current,
       });
       trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
       const setResizeState = (v: ResizePreviewResult) => {

From e318770101879fa6fda14f478fd5ead3a08e667e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 14:04:57 -0700
Subject: [PATCH 09/20] fix(studio): hold the drag actor at the partner-video
 clamp

The dragged audio's ghost followed the pointer past the video's end while
the landing stayed clamped; it now stops where the clip will land.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/player/components/timelineClipDragPreview.test.ts   | 6 +++---
 .../studio/src/player/components/timelineClipDragPreview.ts | 3 ++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/studio/src/player/components/timelineClipDragPreview.test.ts b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
index cd869d13b7..2e0e7184f8 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.test.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
@@ -748,9 +748,9 @@ describe("an audio clip stays inside its partner video", () => {
   it("a drag past the video's end stops with the audio's end on it", () => {
     const a = audio();
     const { drag, clientX, clientY } = horizontalDrag(a, 1.5, 30);
-    expect(computeDragPreview(drag, clientX, clientY, audioCtx([video(), a])).previewStart).toBe(
-      22,
-    );
+    const next = computeDragPreview(drag, clientX, clientY, audioCtx([video(), a]));
+    expect(next.previewStart).toBe(22);
+    expect(next.pointerClientX).toBe(drag.originClientX + 10 * PPS);
   });
 
   it("a drag before the video's start stops at it, linked or same-source", () => {
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.ts
index 456a50c1ed..5a5db5233b 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts
@@ -196,7 +196,8 @@ export function computeDragPreview(
   return {
     ...drag,
     started: true,
-    pointerClientX: clientX,
+    // The drag actor follows the pointer, so a partner-video clamp holds it back by the same amount.
+    pointerClientX: clientX - (floored - previewStart) * pps,
     pointerClientY: clientY,
     previewStart: placement.start,
     previewTrack,

From 4a00bf6420a08e896d9a55d6b491e823044ce465 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 14:54:07 -0700
Subject: [PATCH 10/20] feat(studio): preview a look on hover in the clip menu
 before applying it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/clipMenuToolItems.test.tsx     | 134 +++++++++++++++++-
 .../player/components/clipMenuToolItems.tsx   |  85 ++++++++++-
 2 files changed, 209 insertions(+), 10 deletions(-)

diff --git a/packages/studio/src/player/components/clipMenuToolItems.test.tsx b/packages/studio/src/player/components/clipMenuToolItems.test.tsx
index 72230c4b3c..b1219588a6 100644
--- a/packages/studio/src/player/components/clipMenuToolItems.test.tsx
+++ b/packages/studio/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();
+    });
+  });
 });
diff --git a/packages/studio/src/player/components/clipMenuToolItems.tsx b/packages/studio/src/player/components/clipMenuToolItems.tsx
index 4acffdca5a..0348514a66 100644
--- a/packages/studio/src/player/components/clipMenuToolItems.tsx
+++ b/packages/studio/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"

From d4fbd0c32c9b3a4b8a1eb3f9799a92d2e4f3d210 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 15:18:22 -0700
Subject: [PATCH 11/20] refactor(studio): trim comments the clip-link names
 already carry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/studio/src/player/components/audioClipLink.ts         | 2 --
 .../studio/src/player/components/timelineClipDragPreview.ts    | 3 ---
 2 files changed, 5 deletions(-)

diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.ts
index 8d33ea55de..d9b7ece7c4 100644
--- a/packages/studio/src/player/components/audioClipLink.ts
+++ b/packages/studio/src/player/components/audioClipLink.ts
@@ -116,7 +116,6 @@ type BoundedElement = Pick<
 
 const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
 
-/** The timeline span of an audio clip's video: linked to it, else from the same source (sync origin). */
 function partnerVideoBounds(
   audio: BoundedElement,
   elements: readonly BoundedElement[],
@@ -140,7 +139,6 @@ export function clampStartIntoBounds(
   return Math.max(bounds.start, Math.min(start, bounds.end - duration));
 }
 
-/** The partner video's span, unless that video moves in the same gesture. */
 export function heldPartnerVideoBounds(
   audio: BoundedElement,
   elements: readonly BoundedElement[],
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.ts
index 5a5db5233b..188a2e3415 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts
@@ -112,7 +112,6 @@ interface GroupDrag {
   obstacles: TimelineElement[];
   /** Lowest start the grabbed clip may take (see groupMoveFloor). */
   floor: number;
-  /** Every clip the gesture moves, the grabbed one included. */
   moving: ReadonlySet<string>;
 }
 
@@ -196,7 +195,6 @@ export function computeDragPreview(
   return {
     ...drag,
     started: true,
-    // The drag actor follows the pointer, so a partner-video clamp holds it back by the same amount.
     pointerClientX: clientX - (floored - previewStart) * pps,
     pointerClientY: clientY,
     previewStart: placement.start,
@@ -222,7 +220,6 @@ export interface ResizePreviewContext {
   scroll: HTMLDivElement | null;
   pps: number;
   buildSnapTargets: BuildSnapTargets;
-  /** With them, an audio trim stays inside its partner video unless the video trims with it. */
   elements?: readonly TimelineElement[];
   gestureKeys?: ReadonlySet<string>;
 }

From 3f7bb31bb4e5105b71d74ef2f1fecdcfbc468235 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 16:16:18 -0700
Subject: [PATCH 12/20] fix(studio): unlinking clears the timeline selection

After Unlink both clips stayed selected, so the next edge trim ran the
multi-select group resize and the former partner still followed. Unlink
from the menu, the shortcut or an Alt edit now leaves nothing selected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../studio/src/hooks/useTimelineLinkEditing.test.tsx | 12 ++++++++++++
 packages/studio/src/hooks/useTimelineLinkEditing.ts  |  5 +++++
 2 files changed, 17 insertions(+)

diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx
index de7d0cd473..8cc1398e0f 100644
--- a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx
+++ b/packages/studio/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();
+  });
 });
diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.ts b/packages/studio/src/hooks/useTimelineLinkEditing.ts
index 6423e3acee..df5377030b 100644
--- a/packages/studio/src/hooks/useTimelineLinkEditing.ts
+++ b/packages/studio/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(() =>

From b8692382f019f660e48605cac89138e767040c23 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 22:36:02 -0700
Subject: [PATCH 13/20] fix(sdk): keep a linked partner's end when a trim
 changes the grabbed duration

Copying the grabbed clip's duration to a partner that starts later pushed the
partner's end past the clip both ended on. The partner's duration is now the
shared new end minus its own start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/engine/mutate.ts       |  6 +++++-
 packages/sdk/src/session.linked.test.ts | 13 +++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 4f2ac89bbc..b25f4d09bc 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -341,7 +341,11 @@ function partnerTiming(
   const endsTogether =
     Math.abs(pStart + (partner.duration ?? 0) - (gStart + (grabbed.duration ?? 0))) <
     ALIGN_EPSILON_S;
-  if (edit.duration !== undefined && endsTogether) timing.duration = edit.duration;
+  if (edit.duration !== undefined && endsTogether) {
+    const end = (edit.start ?? gStart) + edit.duration;
+    const duration = end - (timing.start ?? pStart);
+    if (duration > 0) timing.duration = duration;
+  }
   return timing;
 }
 
diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.ts
index e15b6ec76c..598485176f 100644
--- a/packages/sdk/src/session.linked.test.ts
+++ b/packages/sdk/src/session.linked.test.ts
@@ -48,6 +48,19 @@ describe("setTiming on linked clips", () => {
     expect(attr(out, "hf-talk-audio", "data-start")).toBe("6");
   });
 
+  it("keeps a common end when partners start at different times", async () => {
+    const offset = LINKED_HTML.replace(
+      'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',
+      'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',
+    );
+    const comp = await openComposition(offset);
+    comp.setTiming("hf-talk", { duration: 4 });
+    const html = comp.serialize();
+    expect(attr(html, "hf-talk", "data-duration")).toBe("4");
+    expect(attr(html, "hf-talk-audio", "data-start")).toBe("3");
+    expect(attr(html, "hf-talk-audio", "data-duration")).toBe("3");
+  });
+
   it("{ linked: false } edits one member and unlinks the pair", async () => {
     const comp = await openComposition(LINKED_HTML);
     comp.setTiming("hf-talk", { start: 5 }, { linked: false });

From e9f4cef37134d70ab328110555c17385faa239cc Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 22:36:02 -0700
Subject: [PATCH 14/20] fix(studio): keep every moving detached audio inside
 its video, after placement too

The containment clamp ran before collision placement and only for the
grabbed clip, so a drop pushed past an obstacle, or audio carried along in a
multi-selection, could land outside its video. The allowed shift is now the
intersection over every moving audio, and a placement outside it is
rejected. Link partners are matched within their source file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/player/components/audioClipLink.ts    | 28 ++++++++++++-------
 .../timelineClipDragPreview.test.ts           | 18 ++++++++++++
 .../components/timelineClipDragPreview.ts     | 20 +++++++++----
 3 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.ts
index d9b7ece7c4..b5e8e322cf 100644
--- a/packages/studio/src/player/components/audioClipLink.ts
+++ b/packages/studio/src/player/components/audioClipLink.ts
@@ -85,7 +85,6 @@ type TimedLinked = LinkedElement & Pick<TimelineElement, "start" | "duration">;
 const edgeTime = (el: Pick<TimelineElement, "start" | "duration">, edge: "start" | "end") =>
   edge === "start" ? el.start : el.start + el.duration;
 
-/** A trim drags a link partner along only when its edge sits at the grabbed clip's edge time. */
 export function dropMisalignedTrimPartners(
   keys: ReadonlySet<string>,
   grabbed: TimedLinked,
@@ -95,7 +94,7 @@ export function dropMisalignedTrimPartners(
   const kept = new Set(keys);
   if (!isLinked(grabbed)) return kept;
   for (const el of elements) {
-    if (el.link !== grabbed.link || keyOf(el) === keyOf(grabbed)) continue;
+    if (!sharesLinkGroup(el, grabbed) || keyOf(el) === keyOf(grabbed)) continue;
     if (Math.abs(edgeTime(el, edge) - edgeTime(grabbed, edge)) > 1e-3) kept.delete(keyOf(el));
   }
   return kept;
@@ -112,6 +111,7 @@ type BoundedElement = Pick<
   | "syncOrigin"
   | "playbackStart"
   | "playbackRate"
+  | "sourceFile"
 >;
 
 const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
@@ -122,7 +122,7 @@ function partnerVideoBounds(
 ): { videoKey: string; start: number; end: number } | null {
   if (tagOf(audio) !== "audio") return null;
   const linkedVideo = isLinked(audio)
-    ? elements.find((el) => el.link === audio.link && tagOf(el) === "video")
+    ? elements.find((el) => sharesLinkGroup(el, audio) && tagOf(el) === "video")
     : undefined;
   const video = linkedVideo ?? syncPartnerOf(audio, elements);
   return video
@@ -130,13 +130,21 @@ function partnerVideoBounds(
     : null;
 }
 
-/** `start` moved so a clip of `duration` sits inside `bounds`; a clip longer than them pins to their start. */
-export function clampStartIntoBounds(
-  start: number,
-  duration: number,
-  bounds: { start: number; end: number },
-): number {
-  return Math.max(bounds.start, Math.min(start, bounds.end - duration));
+export function heldAudioShiftRange(
+  movers: readonly BoundedElement[],
+  elements: readonly BoundedElement[],
+  moving: ReadonlySet<string>,
+): { min: number; max: number } {
+  let min = Number.NEGATIVE_INFINITY;
+  let max = Number.POSITIVE_INFINITY;
+  for (const mover of movers) {
+    const bounds = heldPartnerVideoBounds(mover, elements, moving);
+    if (!bounds) continue;
+    const low = bounds.start - mover.start;
+    min = Math.max(min, low);
+    max = Math.min(max, Math.max(low, bounds.end - mover.duration - mover.start));
+  }
+  return { min, max };
 }
 
 export function heldPartnerVideoBounds(
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.test.ts b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
index 2e0e7184f8..1b0b18b8f4 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.test.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
@@ -775,6 +775,24 @@ describe("an audio clip stays inside its partner video", () => {
     ).toBe(42);
   });
 
+  it("rejects a drop that collision placement would push outside the video", () => {
+    const a = audio();
+    const obstacle = clip("o", 1, 20, 10, 0, "audio");
+    const { drag, clientX, clientY } = horizontalDrag(a, 1.5, 10);
+    const next = computeDragPreview(drag, clientX, clientY, audioCtx([video(), a, obstacle]));
+    expect(next.previewStart).toBeGreaterThanOrEqual(10);
+    expect(next.previewStart + a.duration).toBeLessThanOrEqual(30);
+  });
+
+  it("keeps an audio carried in a multi-selection inside its video", () => {
+    const a = audio();
+    const title = clip("t", 0, 40, 4, 0, "text");
+    const { drag, clientX, clientY } = horizontalDrag(title, 0.5, 30);
+    const elements = [video(), a, title];
+    const next = computeDragPreview(drag, clientX, clientY, audioCtx(elements, ["t", "a"]));
+    expect(next.previewStart).toBe(50);
+  });
+
   const trim = (edge: "start" | "end", deltaSeconds: number, gestureKeys: string[] = []) =>
     computeResizePreview(
       {
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.ts
index 188a2e3415..8275c78b95 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts
@@ -23,7 +23,7 @@ import {
 import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";
 import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
 import { STUDIO_PREVIEW_FPS } from "../lib/time";
-import { clampStartIntoBounds, heldPartnerVideoBounds } from "./audioClipLink";
+import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
 
 /** Snap-target builder closure supplied by the hook (closes over refs + store). */
 type BuildSnapTargets = (
@@ -133,6 +133,8 @@ function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): Grou
   };
 }
 
+const SHIFT_EPSILON_S = 1e-6;
+
 /** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */
 export function computeDragPreview(
   drag: DraggedClipState,
@@ -185,12 +187,20 @@ export function computeDragPreview(
   );
   // A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
   const group = resolveGroupDrag(drag, ctx);
-  const video = heldPartnerVideoBounds(drag.element, ctx.elements, group.moving);
+  const dragKey = drag.element.key ?? drag.element.id;
+  const passengers = ctx.elements.filter(
+    (el) => (el.key ?? el.id) !== dragKey && group.moving.has(el.key ?? el.id),
+  );
+  const movers = [drag.element, ...passengers];
+  const shift = heldAudioShiftRange(movers, ctx.elements, group.moving);
+  const origin = drag.element.start;
   const floored = Math.max(snap.start, group.floor);
-  const previewStart = video
-    ? clampStartIntoBounds(floored, drag.element.duration, video)
-    : floored;
+  const previewStart = origin + Math.max(shift.min, Math.min(floored - origin, shift.max));
   const placement = resolveDropPlacement(drag, clientY, previewStart, nextMove.track, ctx, group);
+  const placedShift = placement.start - origin;
+  if (placedShift < shift.min - SHIFT_EPSILON_S || placedShift > shift.max + SHIFT_EPSILON_S) {
+    return { ...drag, started: true };
+  }
   const { track: previewTrack, insertRow } = placement;
   return {
     ...drag,

From bb5ce4e7960b8a46b21e0835988572dbc1facf20 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 22:36:03 -0700
Subject: [PATCH 15/20] fix(studio): carry the normalize refusal and save
 outcomes into the gain dialog

Normalize moved from the clip menu into the Audio Gain dialog here, so the
volume-lane refusal and the saved/refused/failed checks go with it: a lane
owned clip is refused, and a failed single or multi-clip save rejects instead
of reporting success.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/editor/mediaLinkEdits.test.ts  |  9 +-
 .../src/hooks/timelineElementsAttribute.ts    | 16 +++-
 .../player/components/audioGainApply.test.ts  | 87 +++++++++++++++++++
 .../src/player/components/audioGainApply.ts   | 18 +++-
 .../components/clipMenuAudioItems.test.tsx    | 30 -------
 .../player/components/timelineCallbacks.ts    |  2 +-
 6 files changed, 120 insertions(+), 42 deletions(-)
 create mode 100644 packages/studio/src/player/components/audioGainApply.test.ts

diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
index 5f171919e5..5e9da0df07 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.test.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
@@ -10,6 +10,7 @@ import {
   pickDetachedAudioTrack,
   removeElementInSource,
   setLinkInSource,
+  sharesSourceFile,
 } from "./mediaLinkEdits";
 
 const automation = JSON.stringify({
@@ -278,16 +279,16 @@ describe("predicates compare the whole asset path", () => {
     const v = el("v", "video", { muted: true, ...one });
     const a = el("a", "audio", two);
     expect(findMergePair(v, [v, a])).toBeNull();
-    expect(canLinkPair([el("v", "video", one), el("a", "audio", two)])).toBe(false);
+    expect(sharesSourceFile([el("v", "video", one), el("a", "audio", two)])).toBe(false);
   });
 
   it("resolves each src against its own source file, and links only inside one", () => {
     const v = el("v", "video", { src: "../assets/talk.mp4", sourceFile: "scenes/a.html" });
     const a = el("a", "audio", { src: "./assets/talk.mp4", sourceFile: "index.html" });
     expect(canLinkPair([v, a])).toBe(false);
-    expect(
-      canLinkPair([v, { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" }]),
-    ).toBe(true);
+    expect(sharesSourceFile([v, a])).toBe(false);
+    const sameFileAudio = { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" };
+    expect(sharesSourceFile([v, sameFileAudio])).toBe(true);
   });
 
   it("does not take a same-id link from another source file as the merge partner", () => {
diff --git a/packages/studio/src/hooks/timelineElementsAttribute.ts b/packages/studio/src/hooks/timelineElementsAttribute.ts
index cf77d43f41..9254339ce9 100644
--- a/packages/studio/src/hooks/timelineElementsAttribute.ts
+++ b/packages/studio/src/hooks/timelineElementsAttribute.ts
@@ -9,7 +9,7 @@ import {
   readFileContent,
 } from "./timelineEditingHelpers";
 import type { UseTimelineElementVisibilityEditingInput } from "./timelineTrackVisibility";
-import { projectForTimelineSave } from "./timelineEditPermission";
+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
 
 type ElementAttributeEdits = Parameters<
   NonNullable<TimelineEditCallbacks["onSetElementsAttributeQuiet"]>
@@ -57,13 +57,18 @@ export function useSetElementsAttribute({
   isRecordingRef,
 }: UseTimelineElementVisibilityEditingInput) {
   return useCallback(
-    async (edits: ElementAttributeEdits, attr: string, label: string): Promise<void> => {
+    async (
+      edits: ElementAttributeEdits,
+      attr: string,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
       const projectId = projectForTimelineSave(
         isRecordingRef?.current,
         projectIdRef.current,
         showToast,
       );
-      if (typeof projectId !== "string" || edits.length === 0) return;
+      if (typeof projectId !== "string") return projectId;
+      if (edits.length === 0) return { status: "saved" };
       try {
         const byFile = editsByFile(edits, activeCompPath);
         const files = Object.fromEntries(
@@ -87,8 +92,11 @@ export function useSetElementsAttribute({
           recordEdit,
         });
         patchLive(previewIframeRef.current, edits, attr, activeCompPath);
+        return { status: "saved" };
       } catch (error) {
-        showToast(error instanceof Error ? error.message : "Could not save the clips", "error");
+        const reason = error instanceof Error ? error.message : "Could not save the clips";
+        showToast(reason, "error");
+        return { status: "failed", reason };
       }
     },
     [
diff --git a/packages/studio/src/player/components/audioGainApply.test.ts b/packages/studio/src/player/components/audioGainApply.test.ts
new file mode 100644
index 0000000000..5bdb60bd5b
--- /dev/null
+++ b/packages/studio/src/player/components/audioGainApply.test.ts
@@ -0,0 +1,87 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/timelineElement";
+import { normalizeClipsLoudness, writeClipGains } from "./audioGainApply";
+
+const clip = (id: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({
+  id,
+  domId: id,
+  tag: "audio",
+  src: `${id}.mp3`,
+  start: 0,
+  duration: 4,
+  track: 0,
+  ...extra,
+});
+
+const volumeLane = JSON.stringify({
+  version: 1,
+  lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],
+});
+const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("normalizeClipsLoudness", () => {
+  it("refuses a clip whose volume lane owns its gain, before measuring or writing", async () => {
+    const fetchSpy = vi.fn(async () => Response.json({ plan }));
+    vi.stubGlobal("fetch", fetchSpy);
+    const onSetElementAttributeQuiet = vi.fn(async () => ({ status: "saved" as const }));
+    await expect(
+      normalizeClipsLoudness("p1", [clip("vo", { automation: volumeLane })], {
+        onSetElementAttributeQuiet,
+      }),
+    ).rejects.toThrow(/volume is automated/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(onSetElementAttributeQuiet).not.toHaveBeenCalled();
+  });
+
+  it("rejects instead of claiming success when the save fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => Response.json({ plan })),
+    );
+    const onSetElementAttributeQuiet = vi.fn(async () => ({
+      status: "failed" as const,
+      reason: "disk full",
+    }));
+    await expect(
+      normalizeClipsLoudness("p1", [clip("vo")], { onSetElementAttributeQuiet }),
+    ).rejects.toThrow("disk full");
+  });
+});
+
+describe("writeClipGains", () => {
+  it("stops at the first refused single save", async () => {
+    const onSetElementAttributeQuiet = vi.fn(async () => ({
+      status: "refused" as const,
+      reason: "Cannot edit timeline while recording",
+    }));
+    await expect(
+      writeClipGains(
+        [
+          { element: clip("a"), gain: 2 },
+          { element: clip("b"), gain: 2 },
+        ],
+        { onSetElementAttributeQuiet },
+      ),
+    ).rejects.toThrow("Cannot edit timeline while recording");
+    expect(onSetElementAttributeQuiet).toHaveBeenCalledTimes(1);
+  });
+
+  it("surfaces a failed multi-clip save", async () => {
+    const onSetElementsAttributeQuiet = vi.fn(async () => ({
+      status: "failed" as const,
+      reason: "disk full",
+    }));
+    await expect(
+      writeClipGains(
+        [
+          { element: clip("a"), gain: 2 },
+          { element: clip("b"), gain: 2 },
+        ],
+        { onSetElementsAttributeQuiet },
+      ),
+    ).rejects.toThrow("disk full");
+  });
+});
diff --git a/packages/studio/src/player/components/audioGainApply.ts b/packages/studio/src/player/components/audioGainApply.ts
index 796facca7a..081e08a746 100644
--- a/packages/studio/src/player/components/audioGainApply.ts
+++ b/packages/studio/src/player/components/audioGainApply.ts
@@ -1,7 +1,13 @@
 import { formatAudioGain } from "@hyperframes/core/audio-gain";
 import type { TimelineElement } from "../store/timelineElement";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
-import { normalizeToastText, requestNormalizePlan } from "./clipMenuNormalize";
+import {
+  normalizeToastText,
+  requestNormalizePlan,
+  throwUnlessSaved,
+  VOLUME_LANE_REFUSAL,
+  volumeLaneOwnsGain,
+} from "./clipMenuNormalize";
 
 export const AUDIO_GAIN_LABEL = "Audio Gain";
 
@@ -16,13 +22,18 @@ export async function writeClipGains(
   writers: VolumeWriters,
   label = AUDIO_GAIN_LABEL,
 ): Promise<void> {
+  if (edits.some(({ element }) => volumeLaneOwnsGain(element))) {
+    throw new Error(VOLUME_LANE_REFUSAL);
+  }
   const values = edits.map(({ element, gain }) => ({ element, value: formatAudioGain(gain) }));
   if (values.length > 1 && writers.onSetElementsAttributeQuiet) {
-    await writers.onSetElementsAttributeQuiet(values, "data-volume", label);
+    throwUnlessSaved(await writers.onSetElementsAttributeQuiet(values, "data-volume", label));
     return;
   }
   for (const { element, value } of values) {
-    await writers.onSetElementAttributeQuiet?.(element, "data-volume", value, label);
+    throwUnlessSaved(
+      await writers.onSetElementAttributeQuiet?.(element, "data-volume", value, label),
+    );
   }
 }
 
@@ -32,6 +43,7 @@ export async function normalizeClipsLoudness(
   elements: readonly TimelineElement[],
   writers: VolumeWriters,
 ): Promise<string> {
+  if (elements.some(volumeLaneOwnsGain)) throw new Error(VOLUME_LANE_REFUSAL);
   const plans = await Promise.all(elements.map((el) => requestNormalizePlan(projectId, el)));
   await writeClipGains(
     elements.map((element, index) => ({ element, gain: plans[index]?.volume ?? 1 })),
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
index 39fe3cbbda..50dccc2780 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -40,7 +40,6 @@ function render(element: TimelineElement, part: "gain" | "duck" = "gain") {
 }
 
 const base = { start: 0, duration: 4, track: 0 };
-const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
 const clickItem = async (host: HTMLElement, label: string) => {
   const button = [...host.querySelectorAll("button")].find((b) => b.textContent?.includes(label));
   await act(async () => button?.click());
@@ -115,35 +114,6 @@ describe("ClipMenuAudioItems", () => {
     expect(host.textContent).not.toContain("Normalize loudness");
   });
 
-  it("refuses to normalize a clip whose volume lane owns its gain", async () => {
-    const fetchSpy = vi.fn(async () => Response.json({ plan }));
-    vi.stubGlobal("fetch", fetchSpy);
-    const automation = JSON.stringify({
-      version: 1,
-      lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],
-    });
-    const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3", automation });
-    await clickItem(host, "Normalize loudness");
-    await vi.waitFor(() => expect(showToast).toHaveBeenCalled());
-    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("volume is automated"), "error");
-    expect(setQuiet).not.toHaveBeenCalled();
-    expect(fetchSpy).not.toHaveBeenCalled();
-    vi.unstubAllGlobals();
-  });
-
-  it("reports a failed save instead of claiming the clip was normalized", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => Response.json({ plan })),
-    );
-    setQuiet.mockResolvedValue({ status: "failed", reason: "disk full" });
-    const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3" });
-    await clickItem(host, "Normalize loudness");
-    await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("disk full", "error"));
-    expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Normalized"), "info");
-    vi.unstubAllGlobals();
-  });
-
   it("stops ducking at the first refused save and says why", async () => {
     previewDoc = document.implementation.createHTMLDocument("c");
     previewDoc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.ts
index f546125e43..bfaf084270 100644
--- a/packages/studio/src/player/components/timelineCallbacks.ts
+++ b/packages/studio/src/player/components/timelineCallbacks.ts
@@ -127,7 +127,7 @@ export interface TimelineEditCallbacks {
     edits: ReadonlyArray<{ element: TimelineElement; value: string | null }>,
     attr: string,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome | void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;
   onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;

From 8bf70fc9f0c53083b9bffbbadc000823245df05e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 22:36:03 -0700
Subject: [PATCH 16/20] refactor(studio): trim comments the gain and
 multiselect layer added

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/studio/src/components/editor/mediaLinkEdits.ts    | 7 +------
 .../studio/src/player/components/clipMenuLinkItems.tsx     | 2 --
 packages/studio/src/player/components/clipPeakRuns.ts      | 1 -
 packages/studio/src/player/components/clipToolAttrs.ts     | 1 -
 .../studio/src/player/components/timelineLinkSelection.ts  | 4 ----
 5 files changed, 1 insertion(+), 14 deletions(-)

diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.ts
index e9538ce02c..10113c77be 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts
@@ -67,10 +67,7 @@ export function setLinkInSource(
   );
 }
 
-/**
- * Link the targets under one freshly minted id. Only a pair from one source file
- * also gets that id as its sync origin, so a drifted pair shows its offset.
- */
+/** Link the targets under one fresh id, also their sync origin when they share a source file. */
 export function linkInSource(
   source: string,
   targets: readonly PatchTarget[],
@@ -262,13 +259,11 @@ export function canLinkPair(selected: readonly TimedElement[]): boolean {
   return tags.has("video") && tags.has("audio") && sameCompositionScope(a, b);
 }
 
-/** Whether the pair comes from one source file, so the link can carry a sync origin. */
 export function sharesSourceFile(selected: readonly TimedElement[]): boolean {
   const [a, b] = selected;
   return selected.length === 2 && !!a && !!b && sameAssetInScope(a, b);
 }
 
-/** Both halves put source time zero at the same timeline moment, at the same rate. */
 export function isPairInSync(a: TimedElement, b: TimedElement): boolean {
   const timing = (el: TimedElement) => ({
     start: el.start,
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsx
index abd02d8f31..3c46a314d8 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx
+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx
@@ -22,7 +22,6 @@ const keyOf = (el: TimelineElement) => el.key ?? el.id;
 
 const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();
 
-/** The one unlinked opposite-kind clip from the same file on another track, if exactly one exists. */
 function loneSameFilePartner(
   element: TimelineElement,
   elements: readonly TimelineElement[],
@@ -47,7 +46,6 @@ function partnerSuffix(element: TimelineElement, others: readonly TimelineElemen
   return pair === "audio+video" ? ` ${tagOf(partner)}` : "";
 }
 
-/** Link for an explicitly selected video+audio pair, else for the lone same-file partner of a sole selection. */
 function linkItem(
   element: TimelineElement,
   elements: readonly TimelineElement[],
diff --git a/packages/studio/src/player/components/clipPeakRuns.ts b/packages/studio/src/player/components/clipPeakRuns.ts
index 814e3eec8b..fdb5088f6f 100644
--- a/packages/studio/src/player/components/clipPeakRuns.ts
+++ b/packages/studio/src/player/components/clipPeakRuns.ts
@@ -48,7 +48,6 @@ export function clipPeakRuns(
   return { runs, peakDbfs: runs.length > 0 ? 20 * Math.log10(loudest) : null };
 }
 
-/** The loudest source sample, linear, in the part of the file the clip plays; null outside it. */
 export function clipSourcePeak(map: PeakMap, window: ClipSourceWindow): number | null {
   if (!(window.sourceSpan > 0) || !(map.binSeconds > 0)) return null;
   const first = Math.max(0, Math.floor(window.mediaStart / map.binSeconds));
diff --git a/packages/studio/src/player/components/clipToolAttrs.ts b/packages/studio/src/player/components/clipToolAttrs.ts
index 088412bbce..47c782ea47 100644
--- a/packages/studio/src/player/components/clipToolAttrs.ts
+++ b/packages/studio/src/player/components/clipToolAttrs.ts
@@ -150,7 +150,6 @@ export interface ClipToolState {
   carve: string | null;
 }
 
-/** The volume badge text, or null at 100% and on clips with no sound. */
 export function clipVolumeBadge(state: ClipToolState): string | null {
   if (state.tag !== "audio" && !state.hasSound) return null;
   if (state.muted) return "Muted";
diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.ts
index ca4d52ec16..3d5db3de61 100644
--- a/packages/studio/src/player/components/timelineLinkSelection.ts
+++ b/packages/studio/src/player/components/timelineLinkSelection.ts
@@ -22,10 +22,6 @@ export function selectClipWithLinks(
   if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);
 }
 
-/**
- * Shift/Cmd-click: toggle `key` in the selection, taking its link partners along
- * unless Alt (or Linked Selection off) singles it out. Returns the new primary.
- */
 export function toggleClipWithLinks(key: string, altKey: boolean): TimelineElement | null {
   const state = usePlayerStore.getState();
   const element = state.elements.find((el) => (el.key ?? el.id) === key);

From 32ba961d06329c82c130186f1da7df3398270d66 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 30 Sep 2026 23:38:50 -0700
Subject: [PATCH 17/20] refactor(sdk): split the linked partner's duration out
 of partnerTiming

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/engine/mutate.ts | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index b25f4d09bc..635b786e92 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -338,17 +338,26 @@ function partnerTiming(
   const timing: { start?: number; duration?: number } = {};
   const [gStart, pStart] = [grabbed.start ?? 0, partner.start ?? 0];
   if (edit.start !== undefined) timing.start = pStart + (edit.start - gStart);
-  const endsTogether =
-    Math.abs(pStart + (partner.duration ?? 0) - (gStart + (grabbed.duration ?? 0))) <
-    ALIGN_EPSILON_S;
-  if (edit.duration !== undefined && endsTogether) {
-    const end = (edit.start ?? gStart) + edit.duration;
-    const duration = end - (timing.start ?? pStart);
-    if (duration > 0) timing.duration = duration;
-  }
+  const duration = partnerDuration(grabbed, partner, edit, timing.start ?? pStart);
+  if (duration !== undefined) timing.duration = duration;
   return timing;
 }
 
+function partnerDuration(
+  grabbed: ClipWindow,
+  partner: ClipWindow,
+  edit: { start?: number; duration?: number },
+  partnerStart: number,
+): number | undefined {
+  if (edit.duration === undefined) return undefined;
+  const grabbedStart = grabbed.start ?? 0;
+  const grabbedEnd = grabbedStart + (grabbed.duration ?? 0);
+  const partnerEnd = (partner.start ?? 0) + (partner.duration ?? 0);
+  if (Math.abs(partnerEnd - grabbedEnd) >= ALIGN_EPSILON_S) return undefined;
+  const duration = (edit.start ?? grabbedStart) + edit.duration - partnerStart;
+  return duration > 0 ? duration : undefined;
+}
+
 export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {
   const gsap = applyGsapOp(parsed, op);
   if (gsap !== undefined) return gsap;

From e0bccd6c7b8ff917d189b89ddb8c3a45803903d0 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 1 Oct 2026 01:04:18 -0700
Subject: [PATCH 18/20] fix(sdk): refuse a linked trim whose new end would
 cross the partner's start
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With linked video [2,8] and audio [3,8], setTiming(video, {duration: 0.5})
computed a partner duration of -0.5, skipped it, and committed the video alone,
leaving the audio outside its video. The partner edits are now planned before
any mutation; a non-positive partner duration throws ("Linked audio would start
after the new end — unlink or trim the audio first.") and can() reports
E_LINKED_PARTNER_CROSSED, so nothing is written and the undo stack is
untouched. In Studio the refusal fails the cutover (never declines into the
legacy path) and the timeline resize toast shows the reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/engine/mutate.ts             | 58 +++++++++++++------
 packages/sdk/src/session.linked.test.ts       | 42 ++++++++++++++
 .../src/utils/sdkCutover.linkedTiming.test.ts | 52 +++++++++++++++++
 3 files changed, 134 insertions(+), 18 deletions(-)
 create mode 100644 packages/studio/src/utils/sdkCutover.linkedTiming.test.ts

diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 635b786e92..23acf1f6bb 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -298,28 +298,47 @@ function applySetTiming(
     const own = handleSetTiming(parsed, ids, timing);
     return concatResults(own, handleSetAttribute(parsed, unlink, MEDIA_LINK_ATTR, null));
   }
-  const before = new Map(
+  const plan = planLinkedTiming(parsed, ids, timing);
+  if (plan.refusal) throw new Error(plan.refusal);
+  let result = handleSetTiming(parsed, ids, timing);
+  for (const partner of plan.partners) {
+    result = concatResults(result, handleSetTiming(parsed, [partner.id], partner.timing));
+  }
+  return result;
+}
+
+type PartnerEdit = { id: HfId; timing: { start?: number; duration?: number } };
+
+function planLinkedTiming(
+  parsed: ParsedDocument,
+  ids: HfId[],
+  timing: { start?: number; duration?: number },
+): { partners: PartnerEdit[]; refusal: string | null } {
+  if (timing.start === undefined && timing.duration === undefined) {
+    return { partners: [], refusal: null };
+  }
+  const grabbedByLink = new Map(
     ids.map((id) => {
       const el = resolveScoped(parsed.document, id);
       return [el?.getAttribute(MEDIA_LINK_ATTR) ?? "", el ? readClipTiming(el) : null] as const;
     }),
   );
-  const partners =
-    op.start === undefined && op.duration === undefined
-      ? []
-      : linkedPartnerIds(parsed.document, ids);
-  const own = handleSetTiming(parsed, ids, timing);
-  let result = own;
-  for (const partner of partners) {
-    const el = resolveScoped(parsed.document, partner);
-    const grabbed = before.get(el?.getAttribute(MEDIA_LINK_ATTR) ?? "");
+  const partners: PartnerEdit[] = [];
+  for (const id of linkedPartnerIds(parsed.document, ids)) {
+    const el = resolveScoped(parsed.document, id);
+    const grabbed = grabbedByLink.get(el?.getAttribute(MEDIA_LINK_ATTR) ?? "");
     if (!el || !grabbed) continue;
-    result = concatResults(
-      result,
-      handleSetTiming(parsed, [partner], partnerTiming(grabbed, readClipTiming(el), timing)),
-    );
+    const partnerEdit = partnerTiming(grabbed, readClipTiming(el), timing);
+    if (partnerEdit.duration !== undefined && partnerEdit.duration <= 0) {
+      const tag = el.tagName.toLowerCase();
+      return {
+        partners: [],
+        refusal: `Linked ${tag} would start after the new end — unlink or trim the ${tag} first.`,
+      };
+    }
+    partners.push({ id, timing: partnerEdit });
   }
-  return result;
+  return { partners, refusal: null };
 }
 
 type ClipWindow = { start: number | null; duration: number | null };
@@ -354,8 +373,7 @@ function partnerDuration(
   const grabbedEnd = grabbedStart + (grabbed.duration ?? 0);
   const partnerEnd = (partner.start ?? 0) + (partner.duration ?? 0);
   if (Math.abs(partnerEnd - grabbedEnd) >= ALIGN_EPSILON_S) return undefined;
-  const duration = (edit.start ?? grabbedStart) + edit.duration - partnerStart;
-  return duration > 0 ? duration : undefined;
+  return (edit.start ?? grabbedStart) + edit.duration - partnerStart;
 }
 
 export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {
@@ -1715,7 +1733,11 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
           `Element(s) not found: ${missing.join(", ")}.`,
           "Verify the id against comp.getElements() or comp.find().",
         );
-      return CAN_OK;
+      const refusal =
+        op.type === "setTiming" && op.linked !== false
+          ? planLinkedTiming(parsed, ids, op).refusal
+          : null;
+      return refusal ? canErr("E_LINKED_PARTNER_CROSSED", refusal) : CAN_OK;
     }
     case "addElement": {
       if (op.parent !== null && resolveScoped(parsed.document, op.parent) === null)
diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.ts
index 598485176f..bb48e67e88 100644
--- a/packages/sdk/src/session.linked.test.ts
+++ b/packages/sdk/src/session.linked.test.ts
@@ -152,4 +152,46 @@ describe("setTiming on linked clips", () => {
     );
     expect(comp.serialize()).toBe((await openComposition(html)).serialize());
   });
+
+  describe("a duration edit whose new end would cross a linked partner's start", () => {
+    const OFFSET_HTML = LINKED_HTML.replace(
+      'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',
+      'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',
+    );
+
+    it.each([1, 0.5])("refuses duration %s atomically, before any mutation", async (duration) => {
+      const comp = await openComposition(OFFSET_HTML);
+      comp.setTiming("hf-music", { start: 1 });
+      const before = comp.serialize();
+      expect(comp.can({ type: "setTiming", target: "hf-talk", duration })).toMatchObject({
+        ok: false,
+        code: "E_LINKED_PARTNER_CROSSED",
+      });
+      expect(() => comp.setTiming("hf-talk", { duration })).toThrow(
+        /linked audio would start after the new end/i,
+      );
+      expect(comp.serialize()).toBe(before);
+      comp.undo();
+      expect(attr(comp.serialize(), "hf-music", "data-start")).toBe("0");
+      expect(comp.canUndo()).toBe(false);
+    });
+
+    it("trims the partner to the shared end while that end stays after its start", async () => {
+      const comp = await openComposition(OFFSET_HTML);
+      expect(comp.can({ type: "setTiming", target: "hf-talk", duration: 1.5 }).ok).toBe(true);
+      comp.setTiming("hf-talk", { duration: 1.5 });
+      const html = comp.serialize();
+      expect(attr(html, "hf-talk", "data-duration")).toBe("1.5");
+      expect(attr(html, "hf-talk-audio", "data-start")).toBe("3");
+      expect(attr(html, "hf-talk-audio", "data-duration")).toBe("0.5");
+    });
+
+    it("allows the same edit once the pair is unlinked", async () => {
+      const comp = await openComposition(OFFSET_HTML);
+      comp.setTiming("hf-talk", { duration: 0.5 }, { linked: false });
+      const html = comp.serialize();
+      expect(attr(html, "hf-talk", "data-duration")).toBe("0.5");
+      expect(attr(html, "hf-talk-audio", "data-duration")).toBe("5");
+    });
+  });
 });
diff --git a/packages/studio/src/utils/sdkCutover.linkedTiming.test.ts b/packages/studio/src/utils/sdkCutover.linkedTiming.test.ts
new file mode 100644
index 0000000000..414b43f04d
--- /dev/null
+++ b/packages/studio/src/utils/sdkCutover.linkedTiming.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import { cutoverCommittedOrThrow, sdkTimingBatchPersist } from "./sdkCutover";
+import { getStudioSaveErrorMessage } from "./studioSaveDiagnostics";
+
+vi.mock("../components/editor/manualEditingAvailability", () => ({
+  STUDIO_SDK_CUTOVER_ENABLED: true,
+  STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,
+}));
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: vi.fn(),
+}));
+
+const OFFSET_LINKED_HTML = `
+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
+  <video data-hf-id="hf-talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>
+  <audio data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5" data-track-index="2"></audio>
+</div>
+`.trim();
+
+describe("a linked trim the SDK refuses", () => {
+  it("fails the cutover with the SDK's reason, which the resize toast shows, and writes nothing", async () => {
+    const session = await openComposition(OFFSET_LINKED_HTML);
+    const before = session.serialize();
+    const deps = {
+      editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+      writeProjectFile: vi.fn().mockResolvedValue(undefined),
+      reloadPreview: vi.fn(),
+      publishSession: vi.fn(),
+      createCandidateSession: async () => session,
+    };
+    const result = await sdkTimingBatchPersist(
+      [{ hfId: "hf-talk", timingUpdate: { start: 2, duration: 0.5 } }],
+      "index.html",
+      session,
+      deps,
+    );
+    expect(result.status).toBe("failed");
+    let thrown: unknown;
+    try {
+      cutoverCommittedOrThrow(result);
+    } catch (error) {
+      thrown = error;
+    }
+    expect(getStudioSaveErrorMessage(thrown)).toBe(
+      "Linked audio would start after the new end — unlink or trim the audio first.",
+    );
+    expect(deps.writeProjectFile).not.toHaveBeenCalled();
+    expect(deps.editHistory.recordEdit).not.toHaveBeenCalled();
+    expect(session.serialize()).toBe(before);
+  });
+});

From d6de0e872b65d832d5c4a91b9150d743fb4ee7d4 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 1 Oct 2026 08:28:04 -0700
Subject: [PATCH 19/20] fix(sdk): key a linked edit's grabbed baselines by
 composition scope

planLinkedTiming stored each target's timing under its raw data-link id, while
linkedPartnerIds scopes link ids to their host composition. One setTiming naming
a root video and a nested video that both use lk-1 kept only the nested baseline,
so the root audio was skipped and left past its trimmed video. Baselines are now
keyed by host scope and link id, the same rule linkedPartnerIds uses, for both
the partner trim and the crossing refusal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/engine/mutate.ts       | 30 +++++++++++-----
 packages/sdk/src/session.linked.test.ts | 48 +++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 8 deletions(-)

diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 23acf1f6bb..4cd3676df2 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -17,7 +17,7 @@ import type {
   JsonPatchOp,
 } from "../types.js";
 import type { ParsedDocument } from "./model.js";
-import { MEDIA_LINK_ATTR } from "@hyperframes/core/media-link";
+import { MEDIA_LINK_ATTR, linkScopeOf } from "@hyperframes/core/media-link";
 import { idsToUnlink, linkedPartnerIds } from "./linkedTiming.js";
 import {
   resolveScoped,
@@ -317,16 +317,11 @@ function planLinkedTiming(
   if (timing.start === undefined && timing.duration === undefined) {
     return { partners: [], refusal: null };
   }
-  const grabbedByLink = new Map(
-    ids.map((id) => {
-      const el = resolveScoped(parsed.document, id);
-      return [el?.getAttribute(MEDIA_LINK_ATTR) ?? "", el ? readClipTiming(el) : null] as const;
-    }),
-  );
+  const grabbedFor = grabbedBaselines(parsed, ids);
   const partners: PartnerEdit[] = [];
   for (const id of linkedPartnerIds(parsed.document, ids)) {
     const el = resolveScoped(parsed.document, id);
-    const grabbed = grabbedByLink.get(el?.getAttribute(MEDIA_LINK_ATTR) ?? "");
+    const grabbed = el ? grabbedFor(el) : undefined;
     if (!el || !grabbed) continue;
     const partnerEdit = partnerTiming(grabbed, readClipTiming(el), timing);
     if (partnerEdit.duration !== undefined && partnerEdit.duration <= 0) {
@@ -342,6 +337,25 @@ function planLinkedTiming(
 }
 
 type ClipWindow = { start: number | null; duration: number | null };
+
+function grabbedBaselines(
+  parsed: ParsedDocument,
+  ids: HfId[],
+): (partner: Element) => ClipWindow | undefined {
+  const byScope = new Map<Element | null, Map<string, ClipWindow>>();
+  for (const id of ids) {
+    const el = resolveScoped(parsed.document, id);
+    const link = el?.getAttribute(MEDIA_LINK_ATTR);
+    if (!el || !link) continue;
+    const byLink = byScope.get(linkScopeOf(el)) ?? new Map<string, ClipWindow>();
+    byLink.set(link, readClipTiming(el));
+    byScope.set(linkScopeOf(el), byLink);
+  }
+  return (partner) => {
+    const link = partner.getAttribute(MEDIA_LINK_ATTR);
+    return link ? byScope.get(linkScopeOf(partner))?.get(link) : undefined;
+  };
+}
 const ALIGN_EPSILON_S = 1e-3;
 
 /**
diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.ts
index bb48e67e88..c91e80501f 100644
--- a/packages/sdk/src/session.linked.test.ts
+++ b/packages/sdk/src/session.linked.test.ts
@@ -194,4 +194,52 @@ describe("setTiming on linked clips", () => {
       expect(attr(html, "hf-talk-audio", "data-duration")).toBe("5");
     });
   });
+
+  describe("one edit naming linked clips in two compositions that reuse a link id", () => {
+    const TWO_SCOPES_HTML = `
+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
+  <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>
+  <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-track-index="1"></audio>
+  <div data-hf-id="hf-host" data-composition-id="child" data-composition-file="child.html" data-start="0" data-duration="10" data-track-index="2">
+    <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>
+    <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>
+  </div>
+</div>`.trim();
+
+    it("trims each audio against its own video's baseline", async () => {
+      const comp = await openComposition(TWO_SCOPES_HTML);
+      comp.dispatch({ type: "setTiming", target: ["hf-v", "hf-host/hf-cv"], duration: 0.5 });
+      const html = comp.serialize();
+      expect([attr(html, "hf-v", "data-start"), attr(html, "hf-v", "data-duration")]).toEqual([
+        "2",
+        "0.5",
+      ]);
+      expect([attr(html, "hf-a", "data-start"), attr(html, "hf-a", "data-duration")]).toEqual([
+        "2",
+        "0.5",
+      ]);
+      expect([attr(html, "hf-cv", "data-start"), attr(html, "hf-cv", "data-duration")]).toEqual([
+        "0",
+        "0.5",
+      ]);
+      expect([attr(html, "hf-ca", "data-start"), attr(html, "hf-ca", "data-duration")]).toEqual([
+        "0",
+        "0.5",
+      ]);
+    });
+
+    it("refuses against the scoped baseline when one scope's audio would cross its video's end", async () => {
+      const crossing = TWO_SCOPES_HTML.replace(
+        'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',
+        'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',
+      );
+      const comp = await openComposition(crossing);
+      const before = comp.serialize();
+      const op = { type: "setTiming" as const, target: ["hf-v", "hf-host/hf-cv"], duration: 0.5 };
+      expect(comp.can(op)).toMatchObject({ ok: false, code: "E_LINKED_PARTNER_CROSSED" });
+      expect(() => comp.dispatch(op)).toThrow(/linked audio would start after the new end/i);
+      expect(comp.serialize()).toBe(before);
+      expect(comp.canUndo()).toBe(false);
+    });
+  });
 });

From 258b833a87f059049494af915c9f079c72c6195c Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 1 Oct 2026 11:51:53 -0700
Subject: [PATCH 20/20] test(sdk): run the two-scope grabbed-baseline cases on
 an inline composition too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/sdk/src/session.linked.test.ts | 82 +++++++++++++------------
 1 file changed, 44 insertions(+), 38 deletions(-)

diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.ts
index c91e80501f..7829f284b5 100644
--- a/packages/sdk/src/session.linked.test.ts
+++ b/packages/sdk/src/session.linked.test.ts
@@ -195,51 +195,57 @@ describe("setTiming on linked clips", () => {
     });
   });
 
-  describe("one edit naming linked clips in two compositions that reuse a link id", () => {
-    const TWO_SCOPES_HTML = `
+  describe.each([
+    { host: 'data-composition-id="child" data-composition-file="child.html"', cv: "hf-host/hf-cv" },
+    { host: 'data-composition-id="child"', cv: "hf-cv" },
+  ])(
+    "one edit naming linked clips in two compositions that reuse a link id ($host)",
+    ({ host, cv }) => {
+      const TWO_SCOPES_HTML = `
 <div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
   <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>
   <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-track-index="1"></audio>
-  <div data-hf-id="hf-host" data-composition-id="child" data-composition-file="child.html" data-start="0" data-duration="10" data-track-index="2">
+  <div data-hf-id="hf-host" ${host} data-start="0" data-duration="10" data-track-index="2">
     <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>
     <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>
   </div>
 </div>`.trim();
 
-    it("trims each audio against its own video's baseline", async () => {
-      const comp = await openComposition(TWO_SCOPES_HTML);
-      comp.dispatch({ type: "setTiming", target: ["hf-v", "hf-host/hf-cv"], duration: 0.5 });
-      const html = comp.serialize();
-      expect([attr(html, "hf-v", "data-start"), attr(html, "hf-v", "data-duration")]).toEqual([
-        "2",
-        "0.5",
-      ]);
-      expect([attr(html, "hf-a", "data-start"), attr(html, "hf-a", "data-duration")]).toEqual([
-        "2",
-        "0.5",
-      ]);
-      expect([attr(html, "hf-cv", "data-start"), attr(html, "hf-cv", "data-duration")]).toEqual([
-        "0",
-        "0.5",
-      ]);
-      expect([attr(html, "hf-ca", "data-start"), attr(html, "hf-ca", "data-duration")]).toEqual([
-        "0",
-        "0.5",
-      ]);
-    });
+      it("trims each audio against its own video's baseline", async () => {
+        const comp = await openComposition(TWO_SCOPES_HTML);
+        comp.dispatch({ type: "setTiming", target: ["hf-v", cv], duration: 0.5 });
+        const html = comp.serialize();
+        expect([attr(html, "hf-v", "data-start"), attr(html, "hf-v", "data-duration")]).toEqual([
+          "2",
+          "0.5",
+        ]);
+        expect([attr(html, "hf-a", "data-start"), attr(html, "hf-a", "data-duration")]).toEqual([
+          "2",
+          "0.5",
+        ]);
+        expect([attr(html, "hf-cv", "data-start"), attr(html, "hf-cv", "data-duration")]).toEqual([
+          "0",
+          "0.5",
+        ]);
+        expect([attr(html, "hf-ca", "data-start"), attr(html, "hf-ca", "data-duration")]).toEqual([
+          "0",
+          "0.5",
+        ]);
+      });
 
-    it("refuses against the scoped baseline when one scope's audio would cross its video's end", async () => {
-      const crossing = TWO_SCOPES_HTML.replace(
-        'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',
-        'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',
-      );
-      const comp = await openComposition(crossing);
-      const before = comp.serialize();
-      const op = { type: "setTiming" as const, target: ["hf-v", "hf-host/hf-cv"], duration: 0.5 };
-      expect(comp.can(op)).toMatchObject({ ok: false, code: "E_LINKED_PARTNER_CROSSED" });
-      expect(() => comp.dispatch(op)).toThrow(/linked audio would start after the new end/i);
-      expect(comp.serialize()).toBe(before);
-      expect(comp.canUndo()).toBe(false);
-    });
-  });
+      it("refuses against the scoped baseline when one scope's audio would cross its video's end", async () => {
+        const crossing = TWO_SCOPES_HTML.replace(
+          'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',
+          'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',
+        );
+        const comp = await openComposition(crossing);
+        const before = comp.serialize();
+        const op = { type: "setTiming" as const, target: ["hf-v", cv], duration: 0.5 };
+        expect(comp.can(op)).toMatchObject({ ok: false, code: "E_LINKED_PARTNER_CROSSED" });
+        expect(() => comp.dispatch(op)).toThrow(/linked audio would start after the new end/i);
+        expect(comp.serialize()).toBe(before);
+        expect(comp.canUndo()).toBe(false);
+      });
+    },
+  );
 });