@hyperframes/studio 0.8.108 → 0.8.110

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { LINK_LABEL_COLORS, linkLabelColor } from "./linkLabelColor";
+
+describe("linkLabelColor", () => {
+  it("has no colour for an unlinked clip", () => {
+    expect(linkLabelColor(undefined)).toBeNull();
+    expect(linkLabelColor("")).toBeNull();
+  });
+
+  it("walks the palette in lk-N order, wrapping", () => {
+    expect(linkLabelColor("lk-1")).toBe(LINK_LABEL_COLORS[0]);
+    expect(linkLabelColor("lk-2")).toBe(LINK_LABEL_COLORS[1]);
+    expect(linkLabelColor(`lk-${LINK_LABEL_COLORS.length + 1}`)).toBe(LINK_LABEL_COLORS[0]);
+  });
+
+  it("is deterministic for hand-written ids", () => {
+    expect(linkLabelColor("talk-pair")).toBe(linkLabelColor("talk-pair"));
+    expect(LINK_LABEL_COLORS).toContain(linkLabelColor("talk-pair"));
+  });
+});

package/src/player/components/linkLabelColor.ts

@@ -0,0 +1,24 @@
+/** Link-group label colours; teal, violet, white and red belong to clips, selection and the sync badge. */
+export const LINK_LABEL_COLORS = [
+  "var(--color-amber-500)",
+  "var(--color-sky-400)",
+  "var(--color-green-400)",
+  "var(--color-pink-400)",
+  "var(--color-orange-400)",
+  "var(--color-amber-300)",
+] as const;
+
+function stableIndex(link: string): number {
+  const numbered = /^lk-(\d+)$/.exec(link);
+  if (numbered) return Number(numbered[1]) - 1;
+  let hash = 0;
+  for (const char of link) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+  return hash;
+}
+
+/** The same colour for every member of a link group, from its id alone. */
+export function linkLabelColor(link: string | undefined): string | null {
+  if (!link) return null;
+  const count = LINK_LABEL_COLORS.length;
+  return LINK_LABEL_COLORS[((stableIndex(link) % count) + count) % count] ?? null;
+}

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

package/src/player/components/timelineCallbacks.ts

@@ -39,6 +39,14 @@ export interface TimelineDropCallbacks {
   ) => Promise<void> | void;
 }
 
+export type TimelineLinkEdit =
+  | { kind: "unlink"; elements: readonly TimelineElement[] }
+  | { kind: "link"; elements: readonly TimelineElement[] }
+  | { kind: "detach"; element: TimelineElement }
+  | { kind: "merge"; video: TimelineElement; audio: TimelineElement }
+  | { kind: "move-into-sync"; element: TimelineElement; start: number }
+  | { kind: "slip-into-sync"; element: TimelineElement; mediaStart: number };
+
 export interface TimelineEditCallbacks {
   onMoveElement?: (
     element: TimelineElement,
@@ -114,11 +122,20 @@ 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<TimelineEditOutcome | void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
+  onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;
+  onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
   onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
+  onNotice?: (message: string, tone?: "error" | "info") => void;
   onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
   onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;
   onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -70,6 +70,7 @@ interface TimelineClipDragGestureLifecycleInput {
   onBlockedEditAttemptRef: RefObject<
     ((element: TimelineElement, intent: BlockedClipState["intent"]) => void) | undefined
   >;
+  onLinkEditRef: RefObject<TimelineEditCallbacks["onLinkEdit"]>;
   readZIndexRef: RefObject<((element: TimelineElement) => number) | undefined>;
   onStackingPatchesRef: RefObject<
     ((patches: StackingPatch[]) => Promise<unknown> | void) | undefined
@@ -107,6 +108,7 @@ export function mountTimelineClipDragGestureLifecycle({
   onResizeElementRef,
   onResizeElementsRef,
   onBlockedEditAttemptRef,
+  onLinkEditRef,
   readZIndexRef,
   onStackingPatchesRef,
   refreshAfterLaneMoveRef,
@@ -228,6 +230,11 @@ export function mountTimelineClipDragGestureLifecycle({
     if (drag && pointerMatchesGesture(event)) handleDragPointerMove(event, drag);
   };
 
+  const unlinkAltEdited = (gesture: { element: TimelineElement; altKey?: boolean }) => {
+    if (!gesture.altKey || !gesture.element.link) return;
+    void onLinkEditRef.current?.({ kind: "unlink", elements: [gesture.element] });
+  };
+
   const commitResizePointerUp = (
     resize: ResizingClipState,
     groupSession: TimelineGroupResizeSession | null,
@@ -271,6 +278,7 @@ export function mountTimelineClipDragGestureLifecycle({
       ]);
       console.error("[Timeline] Failed to persist clip resize", error);
     });
+    unlinkAltEdited(resize);
   };
 
   const finishBlockedPointerUp = (blocked: BlockedClipState) => {
@@ -293,6 +301,7 @@ export function mountTimelineClipDragGestureLifecycle({
       onStackingPatches: onStackingPatchesRef.current,
       refreshAfterLaneMove: refreshAfterLaneMoveRef.current,
     });
+    unlinkAltEdited(drag);
   };
 
   /** Group gestures commit atomically: one missing member cancels the whole resize. */

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

@@ -726,3 +726,99 @@ 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);
+    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", () => {
+    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);
+  });
+
+  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(
+      {
+        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);
+  });
+});

package/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 { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
 
 /** Snap-target builder closure supplied by the hook (closes over refs + store). */
 type BuildSnapTargets = (
@@ -111,6 +112,7 @@ interface GroupDrag {
   obstacles: TimelineElement[];
   /** Lowest start the grabbed clip may take (see groupMoveFloor). */
   floor: number;
+  moving: ReadonlySet<string>;
 }
 
 function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): GroupDrag {
@@ -119,14 +121,20 @@ 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,
   };
 }
 
+const SHIFT_EPSILON_S = 1e-6;
+
 /** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */
 export function computeDragPreview(
   drag: DraggedClipState,
@@ -179,13 +187,25 @@ 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 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 = 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,
     started: true,
-    pointerClientX: clientX,
+    pointerClientX: clientX - (floored - previewStart) * pps,
     pointerClientY: clientY,
     previewStart: placement.start,
     previewTrack,
@@ -210,6 +230,8 @@ export interface ResizePreviewContext {
   scroll: HTMLDivElement | null;
   pps: number;
   buildSnapTargets: BuildSnapTargets;
+  elements?: readonly TimelineElement[];
+  gestureKeys?: ReadonlySet<string>;
 }
 
 export interface ResizePreviewResult {
@@ -253,14 +275,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 +329,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;

package/src/player/components/timelineClipDragTypes.ts

@@ -33,6 +33,7 @@ export interface DraggedClipState {
   snapTime: number | null;
   snapType: TimelineSnapType | null;
   started: boolean;
+  altKey?: boolean;
 }
 
 export interface ResizingClipState {
@@ -63,6 +64,7 @@ export interface ResizingClipState {
     playbackStart?: number;
   }[];
   started: boolean;
+  altKey?: boolean;
 }
 
 export interface BlockedClipState {

package/src/player/components/timelineClipGestureHandlers.ts

@@ -8,6 +8,7 @@ import {
 import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { CLIP_HANDLE_W } from "./timelineLayout";
+import { selectClipWithLinks, toggleClipWithLinks } from "./timelineLinkSelection";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 
 export interface ClipGestureDeps {
@@ -17,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;
@@ -44,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 };
 
@@ -81,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({
@@ -118,7 +116,6 @@ export function createClipGestureHandlers(
     onRazorSplit,
     onRazorSplitAll,
     blockedClipRef,
-    shiftClickClipRef,
     suppressClickRef,
     scrollRef,
     setShowPopover,
@@ -145,6 +142,7 @@ export function createClipGestureHandlers(
       previewDuration: el.duration,
       previewPlaybackStart: el.playbackStart,
       started: false,
+      altKey: e.altKey,
     });
   };
 
@@ -152,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,
@@ -191,33 +184,38 @@ export function createClipGestureHandlers(
       snapTime: null,
       snapType: null,
       started: false,
+      altKey: e.altKey,
     });
   };
 
+  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)) {
+      const primary = toggleClipWithLinks(elementKey, e.altKey);
+      onSelectElement?.(primary);
       return;
     }
     // Clip selection is idempotent; empty timeline space owns deselection.
-    setSelectedElementId(elementKey);
+    selectClipWithLinks(elementKey, e.altKey, setSelectedElementId);
     onSelectElement?.(el);
   };
 

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

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

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

package/src/player/components/timelineLinkSelection.ts

@@ -0,0 +1,41 @@
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { expandToLinkedMembers, linkedMembersOf } from "./audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
+
+/**
+ * Select `key` the way a clip click does, then widen to link partners; Alt
+ * (or Linked Selection off) selects `key` alone, even inside a larger selection.
+ */
+export function selectClipWithLinks(
+  key: string,
+  altKey: boolean,
+  setSelectedElementId: (id: string) => void,
+): void {
+  const state = usePlayerStore.getState();
+  if (altKey || !isLinkedSelectionOn()) {
+    state.setSelection([key], key);
+    return;
+  }
+  setSelectedElementId(key);
+  const { selectedElementIds, elements } = usePlayerStore.getState();
+  const expanded = expandToLinkedMembers(selectedElementIds, elements);
+  if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);
+}
+
+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;
+}

package/src/player/components/timelineViewportGeometry.ts

@@ -40,7 +40,10 @@ export function getTimelineScrollTopForGeometryChange(
   previous: TimelineRowGeometry,
   next: TimelineRowGeometry,
   scrollTop: number,
+  dragAutoScrollOwnsScrollTop = false,
 ): number {
+  const atTopSoRowsAddedAboveStayShown = scrollTop <= 0;
+  if (dragAutoScrollOwnsScrollTop || atTopSoRowsAddedAboveStayShown) return scrollTop;
   const anchor = previous.getRowPositionFromY(scrollTop + RULER_H);
   if (anchor.row < 0 || anchor.row >= previous.rowKeys.length) return scrollTop;
   const anchorKey = previous.rowKeys[anchor.row];

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

package/src/player/components/useTimelineClipContextMenu.ts

@@ -1,6 +1,7 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { ClipContextMenuState } from "./TimelineProvider";
+import { selectClipWithLinks } from "./timelineLinkSelection";
 
 /** A clicked member of an active multi-selection keeps the whole group
  *  selected, so the context menu it opens acts on all of it. */
@@ -16,7 +17,7 @@ export function useClipContextMenu(
       e.preventDefault();
       const id = el.key ?? el.id;
       if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {
-        setSelectedElementId(id);
+        selectClipWithLinks(id, e.altKey, setSelectedElementId);
         onSelectElement?.(el);
       }
       dismissGapMenu();