@hyperframes/studio 0.8.108 → 0.8.110

package/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;
@@ -163,7 +169,6 @@ function renderLanes(options: RenderLanesOptions = {}): {
           setResizingClip={vi.fn()}
           setDraggedClip={vi.fn()}
           setSelectedElementId={setSelectedElementId}
-          shiftClickClipRef={createRef()}
           getPreviewElement={(el) => el}
           getTrackStyle={getTrackStyle}
           gsapAnimations={gsapAnimations}
@@ -174,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()}
         />,
@@ -439,6 +444,44 @@ 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());
+    },
+  );
+  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", () => {

package/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,

package/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 />
     </>
   );
 }

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

@@ -1,34 +1,291 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
-import { audioPillFlags, isLinkedVideoAudio } from "./audioClipLink";
-
-const audio = { id: "bed", tag: "audio", src: "assets/City Ride.mp4?v=2" };
-
-describe("isLinkedVideoAudio", () => {
-  it("links an audio pill to a video of the same file", () => {
-    expect(
-      isLinkedVideoAudio(audio, [
-        audio,
-        { id: "picture", tag: "video", src: "/preview/assets/city ride.mp4" },
-      ]),
-    ).toBe(true);
-  });
-
-  it("greys a hidden clip and a muted group without dropping the link", () => {
-    expect(audioPillFlags({ ...audio, hidden: true }, [])).toEqual({
-      muted: true,
-      linked: false,
-    });
-    expect(audioPillFlags({ ...audio, audioGroupHidden: true }, [])).toEqual({
-      muted: true,
-      linked: false,
-    });
-  });
-
-  it("leaves a standalone audio file unlinked", () => {
-    expect(
-      isLinkedVideoAudio({ id: "vo", tag: "audio", src: "assets/voice.wav" }, [
-        { id: "picture", tag: "video", src: "assets/city.mp4" },
-      ]),
-    ).toBe(false);
+import {
+  audioPillFlags,
+  expandToLinkedMembers,
+  dropMisalignedTrimPartners,
+  linkedGestureKeys,
+  linkedMembersOf,
+  mediaAssetIdentity,
+} from "./audioClipLink";
+import { createTimelineElementFromManifestClip, parseTimelineFromDOM } from "../lib/timelineDOM";
+
+const video = { id: "talk", link: "lk-1" };
+const audio = { id: "talk-audio", link: "lk-1" };
+const other = { id: "music", link: "lk-2" };
+const otherAudio = { id: "music-audio", link: "lk-2" };
+const plain = { id: "title" };
+const elements = [video, audio, other, otherAudio, plain];
+
+describe("audioPillFlags", () => {
+  it("greys a hidden clip and a muted group", () => {
+    expect(audioPillFlags({ hidden: true }).muted).toBe(true);
+    expect(audioPillFlags({ audioGroupHidden: true }).muted).toBe(true);
+  });
+});
+
+describe("mediaAssetIdentity", () => {
+  it("tells same-named files in different folders apart", () => {
+    expect(mediaAssetIdentity({ src: "assets/one/talk.mp4" })).not.toBe(
+      mediaAssetIdentity({ src: "assets/two/talk.mp4" }),
+    );
+  });
+
+  it("resolves a src against its own source file and drops query and hash", () => {
+    expect(mediaAssetIdentity({ src: "../assets/talk.mp4?v=2", sourceFile: "scenes/a.html" })).toBe(
+      mediaAssetIdentity({ src: "./assets/talk.mp4#t=1" }),
+    );
+    expect(mediaAssetIdentity({ src: "assets/City%20Ride.mp4" })).toBe(
+      mediaAssetIdentity({ src: "assets/City Ride.mp4" }),
+    );
+    expect(mediaAssetIdentity({ src: "" })).toBeNull();
+  });
+
+  it("keeps a remote url's query, since it can select a different file", () => {
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=2" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a%26x=b" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a&x=b" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4%3Fclip=a" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1#t=3" })).toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" }),
+    );
+  });
+});
+
+describe("expandToLinkedMembers", () => {
+  it("adds every partner of a linked clip", () => {
+    expect(expandToLinkedMembers(["talk"], elements)).toEqual(new Set(["talk", "talk-audio"]));
+  });
+
+  it("leaves unlinked clips alone and does not pull in other groups", () => {
+    expect(expandToLinkedMembers(["title"], elements)).toEqual(new Set(["title"]));
+    expect(expandToLinkedMembers(["talk-audio", "title"], elements)).toEqual(
+      new Set(["talk-audio", "talk", "title"]),
+    );
+  });
+
+  it("prefers the store key over the id", () => {
+    const keyed = [
+      { id: "a", key: "k-a", link: "lk-9" },
+      { id: "b", key: "k-b", link: "lk-9" },
+    ];
+    expect(expandToLinkedMembers(["k-a"], keyed)).toEqual(new Set(["k-a", "k-b"]));
+  });
+});
+
+describe("link groups stay inside their composition", () => {
+  const root = [
+    { id: "v", link: "lk-1", sourceFile: undefined },
+    { id: "a", link: "lk-1", sourceFile: undefined },
+  ];
+  const child = [
+    { id: "cv", key: "child.html#cv", link: "lk-1", sourceFile: "child.html" },
+    { id: "ca", key: "child.html#ca", link: "lk-1", sourceFile: "child.html" },
+  ];
+  const all = [...root, ...child];
+
+  it("does not pull a child file's same-id link into the root group", () => {
+    expect(linkedMembersOf(root[0] ?? video, all).map((el) => el.id)).toEqual(["v", "a"]);
+    expect(expandToLinkedMembers(["child.html#cv"], all)).toEqual(
+      new Set(["child.html#cv", "child.html#ca"]),
+    );
+  });
+
+  const media = (id: string, tag: string, start: number) =>
+    `<${tag} id="${id}" class="clip" src="${id}.mp4" data-link="lk-1" data-start="${start}" data-duration="4"></${tag}>`;
+  const inlineDoc = () => {
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = `<div data-composition-id="main" data-duration="20">
+      ${media("v", "video", 0)}${media("a", "audio", 0)}
+      <div id="child" data-composition-id="child" data-start="0" data-duration="10">
+        ${media("cv", "video", 5)}${media("ca", "audio", 5)}
+      </div>
+    </div>`;
+    return doc;
+  };
+
+  it("does not pull an inline composition's same-id link into the root group", () => {
+    const rows = parseTimelineFromDOM(inlineDoc(), 20).filter((row) => row.link);
+    const byId = (id: string) => rows.find((row) => row.domId === id) ?? video;
+    expect(linkedMembersOf(byId("v"), rows).map((row) => row.domId)).toEqual(["v", "a"]);
+    expect(linkedMembersOf(byId("cv"), rows).map((row) => row.domId)).toEqual(["cv", "ca"]);
+  });
+
+  it("keeps the inline composition apart on rows built from the runtime manifest", () => {
+    const doc = inlineDoc();
+    const rows = ["v", "a", "cv", "ca"].map((id, fallbackIndex) =>
+      createTimelineElementFromManifestClip({
+        clip: {
+          ...{ id, label: id, start: 0, duration: 4, track: 0, kind: "video", tagName: "video" },
+          ...{
+            compositionId: null,
+            parentCompositionId: null,
+            compositionSrc: null,
+            assetUrl: null,
+          },
+        },
+        fallbackIndex,
+        doc,
+        hostEl: doc.getElementById(id),
+      }),
+    );
+    const [rootVideo] = rows;
+    expect(linkedMembersOf(rootVideo ?? video, rows).map((row) => row.domId)).toEqual(["v", "a"]);
+  });
+});
+
+describe("linkedMembersOf", () => {
+  it("returns the group, or the clip alone when unlinked", () => {
+    expect(linkedMembersOf(video, elements).map((el) => el.id)).toEqual(["talk", "talk-audio"]);
+    expect(linkedMembersOf(plain, elements)).toEqual([plain]);
+  });
+});
+
+describe("linkedGestureKeys", () => {
+  it("drags an unselected linked clip with its partner", () => {
+    expect(linkedGestureKeys(new Set(["title"]), video, elements, false)).toEqual(
+      new Set(["talk", "talk-audio"]),
+    );
+  });
+
+  it("keeps a selection that holds the grabbed clip and adds partners", () => {
+    expect(linkedGestureKeys(new Set(["talk", "title"]), video, elements, false)).toEqual(
+      new Set(["talk", "talk-audio", "title"]),
+    );
+  });
+
+  it("Linked Selection off edits the grabbed clip alone without Alt", () => {
+    expect(linkedGestureKeys(new Set(["talk"]), video, elements, false, false)).toEqual(
+      new Set(["talk"]),
+    );
+  });
+
+  it("Alt edits the grabbed clip alone", () => {
+    expect(linkedGestureKeys(new Set(["talk", "talk-audio"]), video, elements, true)).toEqual(
+      new Set(["talk"]),
+    );
+  });
+});
+
+describe("selectClipWithLinks", () => {
+  const linkedPair = [
+    { 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 },
+  ];
+
+  async function store() {
+    const { usePlayerStore } = await import("../store/playerStore");
+    const { selectClipWithLinks } = await import("./timelineLinkSelection");
+    usePlayerStore.getState().setElements(linkedPair);
+    const click = (key: string, alt = false) =>
+      selectClipWithLinks(key, alt, usePlayerStore.getState().setSelectedElementId);
+    return { usePlayerStore, click };
+  }
+
+  it("a click selects the whole pair; Alt-click then narrows to one member", async () => {
+    const { usePlayerStore, click } = await store();
+    click("talk");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));
+    click("talk-audio", true);
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk-audio"]));
+  });
+
+  it("a plain click collapses a larger selection to the clicked clip's link group", async () => {
+    const { usePlayerStore, click } = await store();
+    usePlayerStore.getState().setSelection(["talk", "talk-audio", "title"], "title");
+    click("talk");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));
+    expect(usePlayerStore.getState().selectedElementId).toBe("talk");
+  });
+});
+
+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" },
+    { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },
+  ];
+
+  it("expands and lists nothing past the clip itself", () => {
+    expect(expandToLinkedMembers(["talk"], linkedPair, false)).toEqual(new Set(["talk"]));
+    expect(linkedMembersOf(linkedPair[0], linkedPair, false)).toEqual([linkedPair[0]]);
+  });
+
+  it("a click selects only the clicked clip", async () => {
+    const { usePlayerStore } = await import("../store/playerStore");
+    const { selectClipWithLinks } = await import("./timelineLinkSelection");
+    const { useLinkedClipPreferences } = await import("../../utils/linkedClipPreferences");
+    usePlayerStore.getState().setElements(linkedPair);
+    useLinkedClipPreferences.getState().setLinkedSelection(false);
+    try {
+      selectClipWithLinks("talk", false, usePlayerStore.getState().setSelectedElementId);
+      expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk"]));
+    } finally {
+      useLinkedClipPreferences.getState().setLinkedSelection(true);
+    }
+  });
+});
+
+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"]));
   });
 });

package/src/player/components/audioClipLink.ts

@@ -1,33 +1,157 @@
-import type { TimelineElement } from "../store/timelineElement";
+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";
+import { syncPartnerOf } from "./clipSync";
 
-function mediaFileKey(src: string | undefined): string | null {
+type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;
+type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;
+
+const keyOf = (element: Pick<TimelineElement, "id" | "key">) => element.key ?? element.id;
+
+const SOURCE_BASE = "https://project.invalid/";
+const SOURCE_ORIGIN = new URL(SOURCE_BASE).origin;
+
+export function mediaAssetIdentity(
+  element: Pick<TimelineElement, "src" | "sourceFile">,
+): string | null {
+  const src = element.src?.trim();
   if (!src) return null;
-  const path = src.split(/[?#]/, 1)[0] ?? "";
-  const segment = path.split(/[/\\]/).pop()?.trim().toLowerCase() ?? "";
-  return segment.length > 0 ? segment : null;
+  try {
+    const url = new URL(src, new URL(element.sourceFile ?? "index.html", SOURCE_BASE));
+    if (url.origin !== SOURCE_ORIGIN) return `${url.origin}${url.pathname}${url.search}`;
+    return decodeURIComponent(`${url.origin}${url.pathname}`);
+  } catch {
+    return null;
+  }
 }
 
-export function audioPillFlags(
-  audio: Pick<TimelineElement, "id" | "tag" | "src" | "hidden" | "audioGroupHidden">,
-  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
-): { muted: boolean; linked: boolean } {
-  return {
-    muted: audio.hidden === true || audio.audioGroupHidden === true,
-    linked: isLinkedVideoAudio(audio, elements),
-  };
-}
-
-/** An audio pill whose file is also a video clip on this timeline. */
-export function isLinkedVideoAudio(
-  audio: Pick<TimelineElement, "id" | "tag" | "src">,
-  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+function isLinked(element: Pick<TimelineElement, "link">): boolean {
+  return typeof element.link === "string" && element.link.length > 0;
+}
+
+export function sharesLinkGroup(
+  a: Pick<TimelineElement, "link"> & LinkScoped,
+  b: Pick<TimelineElement, "link"> & LinkScoped,
 ): boolean {
-  if (audio.tag.trim().toLowerCase() !== "audio") return false;
-  const key = mediaFileKey(audio.src);
-  if (!key) return false;
-  return elements.some((element) => {
-    if (element.id === audio.id) return false;
-    if (element.tag.trim().toLowerCase() !== "video") return false;
-    return mediaFileKey(element.src) === key;
-  });
+  return isLinked(a) && a.link === b.link && sameCompositionScope(a, b);
+}
+
+export function audioPillFlags(
+  audio: Pick<TimelineElement, "hidden" | "audioGroupHidden">,
+  _elements?: readonly unknown[],
+): { muted: boolean } {
+  return { muted: audio.hidden === true || audio.audioGroupHidden === true };
+}
+
+export function linkedMembersOf<T extends LinkedElement>(
+  element: T,
+  elements: readonly T[],
+  linked = true,
+): T[] {
+  if (!linked || !isLinked(element)) return [element];
+  const members = elements.filter((candidate) => sharesLinkGroup(candidate, element));
+  return members.some((member) => keyOf(member) === keyOf(element))
+    ? members
+    : [element, ...members];
+}
+
+export function expandToLinkedMembers(
+  keys: Iterable<string>,
+  elements: readonly LinkedElement[],
+  linked = true,
+): Set<string> {
+  const expanded = new Set(keys);
+  if (!linked) return expanded;
+  const seeds = elements.filter((el) => expanded.has(keyOf(el)) && isLinked(el));
+  for (const element of elements) {
+    if (seeds.some((seed) => sharesLinkGroup(seed, element))) expanded.add(keyOf(element));
+  }
+  return expanded;
+}
+
+export function linkedGestureKeys(
+  selected: ReadonlySet<string>,
+  grabbed: LinkedElement,
+  elements: readonly LinkedElement[],
+  altKey: boolean,
+  linked = true,
+): Set<string> {
+  const grabbedKey = keyOf(grabbed);
+  if (altKey) return new Set([grabbedKey]);
+  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;
+
+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 (!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;
+}
+
+type BoundedElement = Pick<
+  TimelineElement,
+  | "id"
+  | "key"
+  | "tag"
+  | "start"
+  | "duration"
+  | "link"
+  | "syncOrigin"
+  | "playbackStart"
+  | "playbackRate"
+  | "sourceFile"
+>;
+
+const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
+
+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) => sharesLinkGroup(el, audio) && tagOf(el) === "video")
+    : undefined;
+  const video = linkedVideo ?? syncPartnerOf(audio, elements);
+  return video
+    ? { videoKey: keyOf(video), start: video.start, end: video.start + video.duration }
+    : null;
+}
+
+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(
+  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;
 }