Merge pull request #2111 from heygen-com/feat/timeline-multiselect

feat(studio): timeline multi-select (marquee) + relative group time editing
2026-09-08 02:36:10 +00:00 · 2026-07-09 17:38:37 -04:00
parent a8f86e653d 1265702edc
commit dff27cb1df
39 changed files with 3686 additions and 240 deletions
@@ -203,6 +203,40 @@ describe("Timeline provider boundary", () => {
    expect(onSeek).not.toHaveBeenCalled();
    act(() => root.unmount());
  });
+
+  it("marks every clip in selectedElementIds as selected", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    Object.defineProperty(host, "clientWidth", {
+      configurable: true,
+      value: 720,
+    });
+
+    usePlayerStore.setState({
+      duration: 6,
+      timelineReady: true,
+      selectedElementId: "clip-2",
+      selectedElementIds: new Set(["clip-1", "clip-2"]),
+      elements: [
+        { id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
+        { id: "clip-2", tag: "div", start: 1.5, duration: 1, track: 1 },
+        { id: "clip-3", tag: "div", start: 3, duration: 1, track: 2 },
+      ],
+    });
+
+    const root = createRoot(host);
+    act(() => {
+      root.render(React.createElement(Timeline));
+    });
+
+    const selectedClips = host.querySelectorAll(".timeline-clip.is-selected");
+    expect(selectedClips).toHaveLength(2);
+    expect(host.querySelector('[data-el-id="clip-3"]')?.classList.contains("is-selected")).toBe(
+      false,
+    );
+
+    act(() => root.unmount());
+  });
 });

 describe("generateTicks", () => {
@@ -8,6 +8,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { EditPopover } from "./EditModal";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { useTimelineMarqueeSelection } from "./useTimelineMarqueeSelection";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineActiveClips } from "./useTimelineActiveClips";
 import { type TrackVisualStyle, getTrackStyle } from "./timelineIcons";
@@ -21,6 +22,7 @@ import {
  type KeyframeDiamondContextMenuState,
 } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
+import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { ClipContextMenu } from "./ClipContextMenu";
 import { TimelineShortcutHint } from "./TimelineShortcutHint";
 import { buildStackingTimelineLayers, insertPreviewTrackOrder } from "./timelineTrackOrder";
@@ -36,7 +38,6 @@ import {
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";

-// Re-export pure utilities so existing imports from "./Timeline" still resolve.
 export {
  generateTicks,
  formatTimelineTickLabel,
@@ -70,6 +71,10 @@ export const Timeline = memo(function Timeline({
  const {
    onMoveElement,
    onResizeElement,
+    onMoveElements,
+    onResizeElements,
+    onPreviewMoveElements,
+    onPreviewResizeElements,
    onBlockedEditAttempt,
    onSplitElement,
    onRazorSplitAll,
@@ -103,14 +108,12 @@ export const Timeline = memo(function Timeline({
  const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();

  const playheadRef = useRef<HTMLDivElement>(null);
-  const containerRef = useRef<HTMLDivElement>(null);
  const scrollRef = useRef<HTMLDivElement>(null);
  const activeTool = usePlayerStore((s) => s.activeTool);
  const [hoveredClip, setHoveredClip] = useState<string | null>(null);
  const isDragging = useRef(false);
  const [shiftHeld, setShiftHeld] = useState(false);
  const [razorGuideX, setRazorGuideX] = useState<number | null>(null);
-
  useMountEffect(() => {
    const down = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(true);
    const up = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(false);
@@ -136,7 +139,6 @@ export const Timeline = memo(function Timeline({
  const [viewportWidth, setViewportWidth] = useState(0);
  const roRef = useRef<ResizeObserver | null>(null);
  const shortcutHintRafRef = useRef(0);
-
  const syncShortcutHintVisibility = useCallback(() => {
    const scroll = scrollRef.current;
    setShowShortcutHint(
@@ -152,10 +154,6 @@ export const Timeline = memo(function Timeline({
    });
  }, [syncShortcutHintVisibility]);

-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    containerRef.current = el;
-  }, []);
-
  const setScrollRef = useCallback(
    (el: HTMLDivElement | null) => {
      if (roRef.current) {
@@ -206,7 +204,6 @@ export const Timeline = memo(function Timeline({
  const ppsRef = useRef(100);
  const durationRef = useRef(Number.isFinite(duration) ? duration : 0);

-  // Stable ref so useTimelineClipDrag can clear rangeSelection without circular dep
  const setRangeSelectionRef = useRef<((sel: null) => void) | null>(null);

  const {
@@ -225,12 +222,15 @@ export const Timeline = memo(function Timeline({
    timelineElementsRef: expandedElementsRef,
    onMoveElement,
    onResizeElement,
+    onMoveElements,
+    onResizeElements,
+    onPreviewMoveElements,
+    onPreviewResizeElements,
    onBlockedEditAttempt,
    setShowPopover,
    setRangeSelectionRef,
  });

-  // basis drives the zoom (committed); effective adds the live preview (see timelineLayout).
  const basisDuration = useMemo(
    () =>
      computeTimelineBasisDuration(
@@ -269,6 +269,15 @@ export const Timeline = memo(function Timeline({
  const keyframeCache = usePlayerStore((s) => s.keyframeCache);
  const selectedKeyframes = usePlayerStore((s) => s.selectedKeyframes);
  const toggleSelectedKeyframe = usePlayerStore((s) => s.toggleSelectedKeyframe);
+  const keyframeHandlers = useTimelineKeyframeHandlers({
+    expandedElements,
+    keyframeCache,
+    onSelectElement,
+    onSeek,
+    setSelectedElementId,
+    setKfContextMenu,
+    toggleSelectedKeyframe,
+  });

  const selectedElement = useMemo(
    () =>
@@ -278,7 +287,6 @@ export const Timeline = memo(function Timeline({
  const selectedElementRef = useRef<TimelineElement | null>(selectedElement);
  selectedElementRef.current = selectedElement;

-  // Fit to basisDuration, not effectiveDuration, so a live drag can't rezoom.
  const fitPps =
    viewportWidth > GUTTER && basisDuration > 0
      ? (viewportWidth - GUTTER - 2) / basisDuration
@@ -346,8 +354,27 @@ export const Timeline = memo(function Timeline({
    isDragging,
    setShowPopover,
  });
-  // Wire setRangeSelection into the stable ref consumed by useTimelineClipDrag
+  const {
+    marqueeRect,
+    handlePointerDown: handleMarqueePointerDown,
+    handlePointerMove: handleMarqueePointerMove,
+    handlePointerUp: handleMarqueePointerUp,
+  } = useTimelineMarqueeSelection({
+    scrollRef,
+    ppsRef,
+    trackOrderRef,
+    timelineLayersRef,
+    disabled: activeTool === "razor",
+    setShowPopover,
+    setRangeSelectionRef,
+    seekFromX,
+  });
  setRangeSelectionRef.current = setRangeSelection;
+  // Pointer-up and lost-capture end a gesture identically (marquee-claims-first).
+  const releasePointer = (event: Parameters<typeof handleMarqueePointerUp>[0]) => {
+    if (handleMarqueePointerUp(event)) return;
+    handlePointerUp();
+  };

  const prevSelectedRef = useRef(selectedElementRef.current);
  // eslint-disable-next-line no-restricted-syntax, react-hooks/exhaustive-deps
@@ -414,7 +441,6 @@ export const Timeline = memo(function Timeline({

  return (
    <div
-      ref={setContainerRef}
      aria-label="Timeline"
      className={`relative border-t select-none h-full overflow-hidden ${activeTool === "razor" ? "cursor-crosshair" : shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
      onMouseMove={(e) => {
@@ -445,11 +471,15 @@ export const Timeline = memo(function Timeline({
            onRazorSplitAll?.(splitTime);
            return;
          }
+          if (handleMarqueePointerDown(e)) return;
          handlePointerDown(e);
        }}
-        onPointerMove={handlePointerMove}
-        onPointerUp={handlePointerUp}
-        onLostPointerCapture={handlePointerUp}
+        onPointerMove={(e) => {
+          if (handleMarqueePointerMove(e)) return;
+          handlePointerMove(e);
+        }}
+        onPointerUp={releasePointer}
+        onLostPointerCapture={releasePointer}
      >
        <TimelineCanvas
          major={major}
@@ -460,6 +490,7 @@ export const Timeline = memo(function Timeline({
          effectiveDuration={effectiveDuration}
          majorTickInterval={majorTickInterval}
          rangeSelection={rangeSelection}
+          marqueeRect={marqueeRect}
          theme={theme}
          displayTrackOrder={displayTrackOrder}
          trackOrder={trackOrder}
@@ -491,41 +522,10 @@ export const Timeline = memo(function Timeline({
          selectedKeyframes={selectedKeyframes}
          currentTime={currentTime}
          beatAnalysis={adjustedBeatAnalysis}
-          onClickKeyframe={(el, pct) => {
-            usePlayerStore.getState().clearSelectedKeyframes();
-            const elKey = el.key ?? el.id;
-            setSelectedElementId(elKey);
-            onSelectElement?.(el);
-            // Visually select the clicked diamond (matches shift-click / motion-path
-            // selection); cleared above so this single-selects it.
-            toggleSelectedKeyframe(`${elKey}:${pct}`);
-            const absTime = el.start + (pct / 100) * el.duration;
-            onSeek?.(absTime);
-            const kfData = keyframeCache?.get(elKey);
-            const kf = kfData?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.5);
-            usePlayerStore.getState().setActiveKeyframePct(kf?.tweenPercentage ?? null);
-          }}
-          onShiftClickKeyframe={(elId, pct) => {
-            toggleSelectedKeyframe(`${elId}:${pct}`);
-          }}
+          onClickKeyframe={keyframeHandlers.onClickKeyframe}
+          onShiftClickKeyframe={keyframeHandlers.onShiftClickKeyframe}
          onMoveKeyframe={onMoveKeyframe}
-          onContextMenuKeyframe={(e, elId, pct) => {
-            const el = expandedElements.find((x) => (x.key ?? x.id) === elId);
-            if (el) {
-              setSelectedElementId(elId);
-              onSelectElement?.(el);
-            }
-            const kfData = keyframeCache.get(elId);
-            const kf = kfData?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);
-            setKfContextMenu({
-              x: e.clientX + 4,
-              y: e.clientY + 2,
-              elementId: elId,
-              percentage: pct,
-              tweenPercentage: kf?.tweenPercentage,
-              currentEase: kf?.ease ?? kfData?.ease,
-            });
-          }}
+          onContextMenuKeyframe={keyframeHandlers.onContextMenuKeyframe}
          onContextMenuClip={(e, el) => {
            e.preventDefault();
            setSelectedElementId(el.key ?? el.id);
@@ -11,7 +11,7 @@ import {
  type TimelineRangeSelection,
 } from "./timelineEditing";
 import { getRenderedTimelineElement, type TimelineTheme } from "./timelineTheme";
-import { GUTTER, TRACK_H, RULER_H, CLIP_Y, CLIP_HANDLE_W } from "./timelineLayout";
+import { GUTTER, TRACK_H, CLIP_Y, CLIP_HANDLE_W } from "./timelineLayout";
 import {
  usePlayerStore,
  type TimelineElement,
@@ -32,6 +32,8 @@ import {
 import { resolveTimelineDropIndicator } from "./timelineDropIndicator";
 import { TimelineDropInsertionLine } from "./TimelineDropInsertionLine";
 import { TimelineDragGhost } from "./TimelineDragGhost";
+import { TimelineSelectionOverlays } from "./TimelineSelectionOverlays";
+import type { TimelineMarqueeOverlayRect } from "./useTimelineMarqueeSelection";

 function ClipLintDot({ element }: { element: TimelineElement }) {
  const lint = usePlayerStore((s) => s.lintFindingsByElement.get(element.key ?? element.id));
@@ -54,6 +56,7 @@ interface TimelineCanvasProps {
  effectiveDuration: number;
  majorTickInterval: number;
  rangeSelection: TimelineRangeSelection | null;
+  marqueeRect: TimelineMarqueeOverlayRect | null;
  theme: TimelineTheme;
  displayTrackOrder: TimelineLayerId[];
  trackOrder: TimelineLayerId[];
@@ -112,6 +115,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
  effectiveDuration,
  majorTickInterval,
  rangeSelection,
+  marqueeRect,
  theme,
  displayTrackOrder,
  trackOrder,
@@ -158,6 +162,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
    onRazorSplitAll,
  } = useTimelineEditContextOptional();
  const beatDragging = usePlayerStore((s) => s.beatDragging);
+  const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
  const activeSnapGuideTime = draggedClip?.started
    ? (draggedClip.snapBeatTime ?? draggedClip.snapGuideTime)
    : resizingClip?.started
@@ -359,7 +364,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                      const clipStyle = getTrackStyle(el.tag);
                      const elementKey = el.key ?? el.id;
                      const capabilities = getTimelineEditCapabilities(el);
-                      const isSelected = selectedElementId === elementKey;
+                      const isSelected = selectedElementIds.has(elementKey);
                      const isComposition = !!el.compositionSrc;
                      // elementKey (el.key ?? el.id) is already unique per clip; do NOT
                      // fold in the map index, or a splice/reorder remounts every clip
@@ -560,22 +565,12 @@ export const TimelineCanvas = memo(function TimelineCanvas({
        </TimelineDragGhost>
      )}

-      {/* Range highlight */}
-      {rangeSelection && (
-        <div
-          className="absolute pointer-events-none"
-          style={{
-            left: GUTTER + Math.min(rangeSelection.start, rangeSelection.end) * pps,
-            width: Math.abs(rangeSelection.end - rangeSelection.start) * pps,
-            top: RULER_H,
-            bottom: 0,
-            backgroundColor: "rgba(59, 130, 246, 0.12)",
-            borderLeft: "1px solid rgba(59, 130, 246, 0.4)",
-            borderRight: "1px solid rgba(59, 130, 246, 0.4)",
-            zIndex: 50,
-          }}
-        />
-      )}
+      <TimelineSelectionOverlays
+        rangeSelection={rangeSelection}
+        marqueeRect={marqueeRect}
+        pps={pps}
+        accentColor={getTrackStyle("").accent}
+      />

      {/* Playhead — hidden while dragging a beat so its guideline doesn't
          track the scrub and clutter the beat being moved. */}
@@ -102,4 +102,15 @@ describe("TimelineClip", () => {

    act(() => root.unmount());
  });
+
+  it("applies selected styling when rendered as selected", () => {
+    const { host, root } = renderClip({
+      element: { id: "selected", label: "Selected", tag: "div", start: 0, duration: 1, track: 0 },
+      isSelected: true,
+    });
+
+    expect(host.querySelector(".timeline-clip")?.classList.contains("is-selected")).toBe(true);
+
+    act(() => root.unmount());
+  });
 });
@@ -2,7 +2,7 @@ import type { TimelineTheme } from "./timelineTheme";
 import { GUTTER } from "./timelineLayout";
 import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";

-const TIMELINE_LAYER_GROUP_HEADER_H = 18;
+export const TIMELINE_LAYER_GROUP_HEADER_H = 18;

 export function shouldShowTimelineLayerGroupHeader(
  contextKey: string,
@@ -0,0 +1,55 @@
+import type { TimelineRangeSelection } from "./timelineEditing";
+import { GUTTER, RULER_H } from "./timelineLayout";
+import type { TimelineMarqueeOverlayRect } from "./useTimelineMarqueeSelection";
+
+interface TimelineSelectionOverlaysProps {
+  rangeSelection: TimelineRangeSelection | null;
+  marqueeRect: TimelineMarqueeOverlayRect | null;
+  pps: number;
+  /** Primary/accent color (hex) shared with the rest of the timeline chrome. */
+  accentColor: string;
+}
+
+export function TimelineSelectionOverlays({
+  rangeSelection,
+  marqueeRect,
+  pps,
+  accentColor,
+}: TimelineSelectionOverlaysProps) {
+  return (
+    <>
+      {rangeSelection && (
+        <div
+          className="absolute pointer-events-none"
+          style={{
+            left: GUTTER + Math.min(rangeSelection.start, rangeSelection.end) * pps,
+            width: Math.abs(rangeSelection.end - rangeSelection.start) * pps,
+            top: RULER_H,
+            bottom: 0,
+            backgroundColor: `${accentColor}1f`,
+            borderLeft: `1px solid ${accentColor}`,
+            borderRight: `1px solid ${accentColor}`,
+            zIndex: 50,
+          }}
+        />
+      )}
+      {marqueeRect && (
+        <div
+          aria-hidden="true"
+          className="absolute pointer-events-none"
+          data-timeline-marquee="true"
+          style={{
+            left: marqueeRect.left,
+            top: marqueeRect.top,
+            width: marqueeRect.width,
+            height: marqueeRect.height,
+            backgroundColor: `${accentColor}29`,
+            border: `1px solid ${accentColor}`,
+            boxShadow: "0 0 0 1px rgba(15, 23, 42, 0.35)",
+            zIndex: 60,
+          }}
+        />
+      )}
+    </>
+  );
+}
@@ -2,6 +2,11 @@
 // fallow-ignore-file dead-code
 import type { TimelineElement } from "../store/playerStore";
 import type { BlockedTimelineEditIntent, TimelineStackingReorderIntent } from "./timelineEditing";
+import type {
+  TimelineGroupCommitOptions,
+  TimelineGroupMoveChange,
+  TimelineGroupResizeChange,
+} from "../../hooks/useTimelineGroupEditing";

 /**
 * Shared callback signatures for timeline editing operations.
@@ -34,6 +39,16 @@ export interface TimelineEditCallbacks {
    element: TimelineElement,
    updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
  ) => Promise<void> | void;
+  onMoveElements?: (
+    changes: TimelineGroupMoveChange[],
+    options?: TimelineGroupCommitOptions,
+  ) => Promise<void> | void;
+  onResizeElements?: (
+    changes: TimelineGroupResizeChange[],
+    options?: TimelineGroupCommitOptions,
+  ) => Promise<void> | void;
+  onPreviewMoveElements?: (changes: TimelineGroupMoveChange[]) => void;
+  onPreviewResizeElements?: (changes: TimelineGroupResizeChange[]) => void;
  onToggleTrackHidden?: (track: number, hidden: boolean) => Promise<void> | void;
  onToggleElementHidden?: (elementKey: string, hidden: boolean) => Promise<void> | void;
  onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
@@ -0,0 +1,52 @@
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineStackingReorderIntent } from "./timelineEditing";
+import type { TimelineLayerId } from "./timelineTrackOrder";
+
+interface DragPreviewState {
+  element: Pick<TimelineElement, "track">;
+  previewLayerId: TimelineLayerId;
+  previewLayerIndex: number;
+}
+
+export interface TimelineMovePreview {
+  start: number;
+  track: number;
+  previewLayerId?: TimelineLayerId;
+  previewLayerIndex?: number;
+  stackingReorder?: TimelineStackingReorderIntent | null;
+}
+
+export interface TimelineGroupMovePreview {
+  active: boolean;
+  previewStart: number;
+}
+
+export function resolveDragPreviewPlacement(
+  drag: DragPreviewState,
+  nextMove: TimelineMovePreview,
+  groupMove: TimelineGroupMovePreview,
+): {
+  previewStart: number;
+  previewTrack: number;
+  previewLayerId: TimelineLayerId;
+  previewLayerIndex: number;
+  previewStackingReorder: TimelineStackingReorderIntent | null;
+} {
+  if (groupMove.active) {
+    return {
+      previewStart: groupMove.previewStart,
+      previewTrack: drag.element.track,
+      previewLayerId: drag.previewLayerId,
+      previewLayerIndex: drag.previewLayerIndex,
+      previewStackingReorder: null,
+    };
+  }
+
+  return {
+    previewStart: groupMove.previewStart,
+    previewTrack: nextMove.track,
+    previewLayerId: nextMove.previewLayerId ?? drag.previewLayerId,
+    previewLayerIndex: nextMove.previewLayerIndex ?? drag.previewLayerIndex,
+    previewStackingReorder: nextMove.stackingReorder ?? null,
+  };
+}
@@ -4,12 +4,15 @@ import {
  buildPromptCopyText,
  buildTimelineElementAgentPrompt,
  buildTimelineAgentPrompt,
+  clampTimelineGroupResizeDelta,
  getTimelineEditCapabilities,
  hasPatchableTimelineTarget,
  resolveBlockedTimelineEditIntent,
  resolveTimelineAutoScroll,
  resolveTimelineMove,
  resolveTimelineResize,
+  resolveTimelineGroupMove,
+  resolveTimelineGroupResize,
  snapKeyframePctToBeat,
  type TimelinePromptElement,
 } from "./timelineEditing";
@@ -220,6 +223,159 @@ describe("resolveTimelineMove", () => {
  });
 });

+describe("resolveTimelineGroupMove", () => {
+  it("applies an unclamped delta uniformly", () => {
+    const result = resolveTimelineGroupMove(
+      [
+        { start: 1, duration: 2 },
+        { start: 4, duration: 3 },
+      ],
+      1.25,
+    );
+
+    expect(result).toEqual({
+      delta: 1.25,
+      members: [
+        { start: 2.25, duration: 2 },
+        { start: 5.25, duration: 3 },
+      ],
+    });
+  });
+
+  it("clamps the whole group when the earliest start reaches zero", () => {
+    const result = resolveTimelineGroupMove(
+      [
+        { start: 1, duration: 2 },
+        { start: 5, duration: 3 },
+      ],
+      -3,
+    );
+
+    expect(result).toEqual({
+      delta: -1,
+      members: [
+        { start: 0, duration: 2 },
+        { start: 4, duration: 3 },
+      ],
+    });
+    expect(result.members[1]!.start - result.members[0]!.start).toBe(4);
+  });
+});
+
+describe("resolveTimelineGroupResize", () => {
+  it("returns the shared clamped delta without applying per-member starts", () => {
+    expect(
+      clampTimelineGroupResizeDelta(
+        1,
+        [
+          { start: 1, duration: 0.5 },
+          { start: 4, duration: 2 },
+        ],
+        "start",
+      ),
+    ).toBe(0.4);
+  });
+
+  it("applies an unclamped start-edge delta uniformly", () => {
+    const result = resolveTimelineGroupResize(
+      [
+        { start: 1, duration: 3 },
+        { start: 5, duration: 4 },
+      ],
+      "start",
+      1,
+    );
+
+    expect(result).toEqual({
+      delta: 1,
+      members: [
+        { start: 2, duration: 2, playbackStart: undefined },
+        { start: 6, duration: 3, playbackStart: undefined },
+      ],
+    });
+    expect(result.members[1]!.start - result.members[0]!.start).toBe(4);
+  });
+
+  it("clamps a start-edge delta when the earliest member reaches zero", () => {
+    const result = resolveTimelineGroupResize(
+      [
+        { start: 0.5, duration: 3 },
+        { start: 4, duration: 4 },
+      ],
+      "start",
+      -2,
+    );
+
+    expect(result).toEqual({
+      delta: -0.5,
+      members: [
+        { start: 0, duration: 3.5, playbackStart: undefined },
+        { start: 3.5, duration: 4.5, playbackStart: undefined },
+      ],
+    });
+    expect(result.members[1]!.start - result.members[0]!.start).toBe(3.5);
+  });
+
+  it("clamps a start-edge delta when any member reaches minimum duration", () => {
+    const result = resolveTimelineGroupResize(
+      [
+        { start: 1, duration: 0.5 },
+        { start: 4, duration: 2 },
+      ],
+      "start",
+      1,
+    );
+
+    expect(result).toEqual({
+      delta: 0.4,
+      members: [
+        { start: 1.4, duration: 0.1, playbackStart: undefined },
+        { start: 4.4, duration: 1.6, playbackStart: undefined },
+      ],
+    });
+    expect(result.members[1]!.start - result.members[0]!.start).toBeCloseTo(3);
+  });
+
+  it("clamps an end-edge delta when any member reaches minimum duration", () => {
+    const result = resolveTimelineGroupResize(
+      [
+        { start: 1, duration: 0.5 },
+        { start: 4, duration: 2 },
+      ],
+      "end",
+      -1,
+    );
+
+    expect(result).toEqual({
+      delta: -0.4,
+      members: [
+        { start: 1, duration: 0.1, playbackStart: undefined },
+        { start: 4, duration: 1.6, playbackStart: undefined },
+      ],
+    });
+    expect(result.members[1]!.start - result.members[0]!.start).toBe(3);
+  });
+
+  it("adjusts each start-edge playback start using the shared delta", () => {
+    const result = resolveTimelineGroupResize(
+      [
+        { start: 2, duration: 3, playbackStart: 1, playbackRate: 1 },
+        { start: 5, duration: 4, playbackStart: 2, playbackRate: 2 },
+      ],
+      "start",
+      0.5,
+    );
+
+    expect(result).toEqual({
+      delta: 0.5,
+      members: [
+        { start: 2.5, duration: 2.5, playbackStart: 1.5 },
+        { start: 5.5, duration: 3.5, playbackStart: 3 },
+      ],
+    });
+  });
+});
+
 describe("hasPatchableTimelineTarget", () => {
  it("returns true when the clip has a DOM id", () => {
    expect(hasPatchableTimelineTarget({ domId: "hero-card" })).toBe(true);
@@ -537,7 +693,7 @@ describe("buildTimelineAgentPrompt", () => {
      prompt: "Move the title later and lower the music",
    });

-    expect(text).toContain("Time range: 0:01 — 0:04");
+    expect(text).toContain("Time range: 0:01 - 0:04");
    expect(text).toContain("#title (div)");
    expect(text).toContain("#music (audio)");
    expect(text).toContain("Move the title later and lower the music");
@@ -2,8 +2,23 @@ import { formatTime } from "../lib/time";
 import { roundToCenti } from "../../utils/rounding";
 import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
 import { resolveTimelineLayerStackingMove } from "./timelineLayerDrag";
+import { shouldShowTimelineLayerGroupHeader } from "./TimelineLayerGroupHeader";
 import type { TimelineStackingElement, TimelineStackingReorderIntent } from "./timelineStacking";

+import {
+  applyClipStartTrimDelta,
+  clipStartTrimDeltaBounds,
+  resolveTimelineMinDuration,
+} from "./timelineGroupEditing";
+
+export {
+  clampTimelineGroupResizeDelta,
+  resolveTimelineGroupMove,
+  resolveTimelineGroupResize,
+  type TimelineGroupResizeEdge,
+  type TimelineGroupTimingMember,
+} from "./timelineGroupEditing";
+
 export {
  type TimelineStackingElement,
  type TimelineStackingReorderIntent,
@@ -109,7 +124,7 @@ export function resolveTimelineMove(

  // Stacking mode: the two axes never fight. Horizontal movement writes time
  // (nextStart); vertical movement writes z-index. Lane/overlap resolution
-  // uses the clip's authored time span, NOT the dragged start — otherwise a
+  // uses the clip's authored time span, NOT the dragged start, otherwise a
  // diagonal drag that drifts the clip out of overlap silently flips the
  // placement from "restack" to "join lane" and cancels the reorder.
  if (input.stackingElement) {
@@ -194,7 +209,7 @@ export function resolveTimelineResize(
  edge: "start" | "end",
  clientX: number,
 ): { start: number; duration: number; playbackStart?: number } {
-  const minDuration = Math.max(0.05, input.minDuration ?? 0.1);
+  const minDuration = resolveTimelineMinDuration(input.minDuration);
  const deltaTime = (clientX - input.originClientX) / Math.max(input.pixelsPerSecond, 1);

  if (edge === "end") {
@@ -210,23 +225,15 @@ export function resolveTimelineResize(
    };
  }

-  const playbackRate = Math.max(0.1, input.playbackRate ?? 1);
-  const maxLeftExtensionFromMedia =
-    input.playbackStart != null ? input.playbackStart / playbackRate : Number.POSITIVE_INFINITY;
-  const minDelta = -Math.min(input.start - input.minStart, maxLeftExtensionFromMedia);
-  const maxDelta = input.duration - minDuration;
+  const { minDelta, maxDelta } = clipStartTrimDeltaBounds(input, input.minStart, minDuration);
  const clampedDelta = clamp(deltaTime, minDelta, maxDelta);
-  const nextStart = roundToCentiseconds(input.start + clampedDelta);
-  const nextDuration = roundToCentiseconds(input.duration - clampedDelta);
-  const nextPlaybackStart =
-    input.playbackStart != null
-      ? roundToCentiseconds(Math.max(0, input.playbackStart + clampedDelta * playbackRate))
-      : undefined;
+  const trimmed = applyClipStartTrimDelta(input, clampedDelta);

  return {
-    start: nextStart,
-    duration: nextDuration,
-    playbackStart: nextPlaybackStart,
+    start: roundToCentiseconds(trimmed.start),
+    duration: roundToCentiseconds(trimmed.duration),
+    playbackStart:
+      trimmed.playbackStart != null ? roundToCentiseconds(trimmed.playbackStart) : undefined,
  };
 }

@@ -253,6 +260,108 @@ export interface TimelineRangeSelection {
  anchorY: number;
 }

+export interface TimelineMarqueeSelectionRect {
+  startTime: number;
+  endTime: number;
+  top: number;
+  bottom: number;
+}
+
+export interface TimelineMarqueeSelectionInput {
+  rect: TimelineMarqueeSelectionRect;
+  layers: readonly StackingTimelineLayer[];
+  layerOrder: readonly TimelineLayerId[];
+  rulerHeight: number;
+  trackHeight: number;
+  groupHeaderHeight?: number;
+}
+
+interface NormalizedTimelineMarqueeRect {
+  startTime: number;
+  endTime: number;
+  top: number;
+  bottom: number;
+}
+
+function timelineIntervalsOverlap(
+  startA: number,
+  endA: number,
+  startB: number,
+  endB: number,
+): boolean {
+  return startA < endB && startB < endA;
+}
+
+function normalizeTimelineMarqueeRect(
+  rect: TimelineMarqueeSelectionRect,
+): NormalizedTimelineMarqueeRect | null {
+  const normalized = {
+    startTime: Math.max(0, Math.min(rect.startTime, rect.endTime)),
+    endTime: Math.max(0, Math.max(rect.startTime, rect.endTime)),
+    top: Math.min(rect.top, rect.bottom),
+    bottom: Math.max(rect.top, rect.bottom),
+  };
+  if (normalized.endTime <= normalized.startTime || normalized.bottom <= normalized.top) {
+    return null;
+  }
+  return normalized;
+}
+
+function buildTimelineLayerMap(layers: readonly StackingTimelineLayer[]) {
+  const layerById = new Map<TimelineLayerId, StackingTimelineLayer>();
+  for (const layer of layers) layerById.set(layer.id, layer);
+  return layerById;
+}
+
+function appendMarqueeLayerSelection(
+  selected: string[],
+  layer: StackingTimelineLayer,
+  rect: NormalizedTimelineMarqueeRect,
+) {
+  for (const element of layer.elements) {
+    if (
+      timelineIntervalsOverlap(
+        rect.startTime,
+        rect.endTime,
+        element.start,
+        element.start + element.duration,
+      )
+    ) {
+      selected.push(element.key ?? element.id);
+    }
+  }
+}
+
+export function selectTimelineElementsInMarquee({
+  rect,
+  layers,
+  layerOrder,
+  rulerHeight,
+  trackHeight,
+  groupHeaderHeight = 0,
+}: TimelineMarqueeSelectionInput): string[] {
+  const normalized = normalizeTimelineMarqueeRect(rect);
+  if (!normalized) return [];
+  const layerById = buildTimelineLayerMap(layers);
+  const selected: string[] = [];
+  let previousContextKey = "";
+  let rowTop = rulerHeight;
+  for (const layerId of layerOrder) {
+    const layer = layerById.get(layerId);
+    if (!layer) continue;
+    if (shouldShowTimelineLayerGroupHeader(layer.contextKey, previousContextKey)) {
+      rowTop += groupHeaderHeight;
+    }
+    const rowBottom = rowTop + trackHeight;
+    if (timelineIntervalsOverlap(normalized.top, normalized.bottom, rowTop, rowBottom)) {
+      appendMarqueeLayerSelection(selected, layer, normalized);
+    }
+    previousContextKey = layer.contextKey;
+    rowTop = rowBottom;
+  }
+  return selected;
+}
+
 function isDeterministicTimelineWindow(input: {
  tag: string;
  compositionSrc?: string;
@@ -356,13 +465,13 @@ export function buildTimelineAgentPrompt({
  const elementLines = elements
    .map(
      (el) =>
-        `- #${el.id} (${el.tag}) — ${formatTime(el.start)} to ${formatTime(el.start + el.duration)}, track ${el.track}`,
+        `- #${el.id} (${el.tag}) - ${formatTime(el.start)} to ${formatTime(el.start + el.duration)}, track ${el.track}`,
    )
    .join("\n");

  return `Edit the following HyperFrames composition:

-Time range: ${formatTime(start)} — ${formatTime(end)}
+Time range: ${formatTime(start)} - ${formatTime(end)}

 Elements in range:
 ${elementLines || "(none)"}
@@ -0,0 +1,159 @@
+import { roundToCenti } from "../../utils/rounding";
+
+const DEFAULT_TIMELINE_MIN_DURATION = 0.1;
+const ABSOLUTE_TIMELINE_MIN_DURATION = 0.05;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function roundTimelineTime(value: number): number {
+  return roundToCenti(value);
+}
+
+export function resolveTimelineMinDuration(minDuration?: number): number {
+  return Math.max(ABSOLUTE_TIMELINE_MIN_DURATION, minDuration ?? DEFAULT_TIMELINE_MIN_DURATION);
+}
+
+/** Playback rate never drops to zero (would make media-in-point math divide by ~0). */
+function resolveTimelinePlaybackRate(rate?: number): number {
+  return Math.max(0.1, rate ?? 1);
+}
+
+interface TimelineStartTrimClip {
+  start: number;
+  duration: number;
+  playbackStart?: number;
+  playbackRate?: number;
+}
+
+/**
+ * Delta bounds for trimming a clip's START edge (shared by single-clip and group
+ * resize). Left-bounded by how far the start can move toward `minStart` and by the
+ * media in-point (`playbackStart / playbackRate`); right-bounded by `minDuration`.
+ * Returned deltas are unrounded — callers round with their own centisecond helper.
+ */
+export function clipStartTrimDeltaBounds(
+  clip: TimelineStartTrimClip,
+  minStart: number,
+  minDuration: number,
+): { minDelta: number; maxDelta: number } {
+  const playbackRate = resolveTimelinePlaybackRate(clip.playbackRate);
+  const maxLeftExtensionFromMedia =
+    clip.playbackStart != null ? clip.playbackStart / playbackRate : Number.POSITIVE_INFINITY;
+  return {
+    minDelta: -Math.min(clip.start - minStart, maxLeftExtensionFromMedia),
+    maxDelta: clip.duration - minDuration,
+  };
+}
+
+/**
+ * Apply a start-edge delta to one clip (unrounded): moves the start, shrinks the
+ * duration by the same amount, and shifts the media in-point by the delta scaled to
+ * the playback rate (clamped at 0).
+ */
+export function applyClipStartTrimDelta(
+  clip: TimelineStartTrimClip,
+  delta: number,
+): { start: number; duration: number; playbackStart?: number } {
+  const playbackRate = resolveTimelinePlaybackRate(clip.playbackRate);
+  return {
+    start: clip.start + delta,
+    duration: clip.duration - delta,
+    playbackStart:
+      clip.playbackStart != null
+        ? Math.max(0, clip.playbackStart + delta * playbackRate)
+        : undefined,
+  };
+}
+
+export interface TimelineGroupTimingMember {
+  start: number;
+  duration: number;
+  playbackStart?: number;
+  playbackRate?: number;
+}
+
+export type TimelineGroupResizeEdge = "start" | "end";
+
+export interface TimelineGroupMoveResult {
+  delta: number;
+  members: Array<Pick<TimelineGroupTimingMember, "start" | "duration">>;
+}
+
+export interface TimelineGroupResizeResult {
+  delta: number;
+  members: Array<Pick<TimelineGroupTimingMember, "start" | "duration" | "playbackStart">>;
+}
+
+function clampTimelineGroupMoveDelta(
+  rawDelta: number,
+  members: readonly TimelineGroupTimingMember[],
+): number {
+  if (members.length === 0) return 0;
+  const minDelta = Math.max(...members.map((member) => -member.start));
+  return roundTimelineTime(Math.max(rawDelta, minDelta));
+}
+
+export function resolveTimelineGroupMove(
+  members: readonly TimelineGroupTimingMember[],
+  rawDelta: number,
+): TimelineGroupMoveResult {
+  const delta = clampTimelineGroupMoveDelta(rawDelta, members);
+  return {
+    delta,
+    members: members.map((member) => ({
+      start: roundTimelineTime(member.start + delta),
+      duration: member.duration,
+    })),
+  };
+}
+
+export function clampTimelineGroupResizeDelta(
+  rawDelta: number,
+  members: readonly TimelineGroupTimingMember[],
+  edge: TimelineGroupResizeEdge,
+  minDuration = resolveTimelineMinDuration(),
+): number {
+  if (members.length === 0) return 0;
+
+  if (edge === "end") {
+    const minDelta = Math.max(...members.map((member) => minDuration - member.duration));
+    return roundTimelineTime(Math.max(rawDelta, minDelta));
+  }
+
+  // Rigid group: the applied delta is bounded by the most-constrained member.
+  const bounds = members.map((member) => clipStartTrimDeltaBounds(member, 0, minDuration));
+  const minDelta = Math.max(...bounds.map((b) => b.minDelta));
+  const maxDelta = Math.min(...bounds.map((b) => b.maxDelta));
+  return roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
+}
+
+export function resolveTimelineGroupResize(
+  members: readonly TimelineGroupTimingMember[],
+  edge: TimelineGroupResizeEdge,
+  rawDelta: number,
+  minDuration = resolveTimelineMinDuration(),
+): TimelineGroupResizeResult {
+  const delta = clampTimelineGroupResizeDelta(rawDelta, members, edge, minDuration);
+  return {
+    delta,
+    members: members.map((member) => {
+      if (edge === "end") {
+        return {
+          start: member.start,
+          duration: roundTimelineTime(member.duration + delta),
+          playbackStart: member.playbackStart,
+        };
+      }
+
+      const trimmed = applyClipStartTrimDelta(member, delta);
+      return {
+        start: roundTimelineTime(trimmed.start),
+        duration: roundTimelineTime(trimmed.duration),
+        playbackStart:
+          trimmed.playbackStart != null ? roundTimelineTime(trimmed.playbackStart) : undefined,
+      };
+    }),
+  };
+}
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { RULER_H, TRACK_H } from "./timelineLayout";
+import { selectTimelineElementsInMarquee } from "./timelineEditing";
+import type { StackingTimelineLayer } from "./timelineTrackOrder";
+
+function element(id: string, start: number, duration: number, track: number): TimelineElement {
+  return { id, tag: "div", start, duration, track };
+}
+
+function layer(id: string, elements: TimelineElement[]): StackingTimelineLayer {
+  return {
+    id,
+    kind: "visual",
+    contextKey: "",
+    zIndex: 0,
+    placementTrack: elements[0]?.track ?? 0,
+    elements,
+  };
+}
+
+describe("selectTimelineElementsInMarquee", () => {
+  it("selects clips intersecting both the marquee time span and lane span", () => {
+    const layers = [
+      layer("lane-0", [element("first-hit", 1, 1, 0), element("time-miss", 5, 1, 0)]),
+      layer("lane-1", [element("second-hit", 2.25, 1, 1)]),
+      layer("lane-2", [element("lane-miss", 1.5, 1, 2)]),
+    ];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0.5,
+          endTime: 3,
+          top: RULER_H,
+          bottom: RULER_H + TRACK_H * 2,
+        },
+        layers,
+        layerOrder: layers.map((item) => item.id),
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+      }),
+    ).toEqual(["first-hit", "second-hit"]);
+  });
+
+  it("returns no ids when the marquee intersects no clip", () => {
+    const layers = [layer("lane-0", [element("outside", 4, 1, 0)])];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0,
+          endTime: 1,
+          top: RULER_H,
+          bottom: RULER_H + TRACK_H,
+        },
+        layers,
+        layerOrder: ["lane-0"],
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+      }),
+    ).toEqual([]);
+  });
+
+  it("accounts for context group headers before row hit testing", () => {
+    const layers: StackingTimelineLayer[] = [
+      { ...layer("lane-0", [element("above", 0, 1, 0)]), contextKey: "root" },
+      { ...layer("lane-1", [element("below", 0, 1, 1)]), contextKey: "nested" },
+    ];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0,
+          endTime: 1,
+          top: RULER_H + 18 + TRACK_H,
+          bottom: RULER_H + 18 + TRACK_H + 18 + TRACK_H,
+        },
+        layers,
+        layerOrder: ["lane-0", "lane-1"],
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+        groupHeaderHeight: 18,
+      }),
+    ).toEqual(["below"]);
+  });
+});
@@ -34,7 +34,7 @@ describe("buildTimelineSnapTargets", () => {

    const targets = buildTimelineSnapTargets({
      elements: [dragged, other],
-      draggedKey: "dragged-key",
+      excludedKeys: new Set(["dragged-key"]),
      playhead: 8,
      compDuration: 10,
      beats: [1.5],
@@ -47,13 +47,36 @@ describe("buildTimelineSnapTargets", () => {
    expect(times).toContain(6);
  });

+  it("excludes every moving group member, not just the grabbed clip", () => {
+    const a = timelineElement({ id: "a", start: 1, duration: 1 });
+    const b = timelineElement({ id: "b", start: 3, duration: 1 });
+    const other = timelineElement({ id: "other", start: 6, duration: 1 });
+
+    const targets = buildTimelineSnapTargets({
+      elements: [a, b, other],
+      excludedKeys: new Set(["a", "b"]),
+      playhead: 9,
+      compDuration: 10,
+      beats: [],
+    });
+
+    const times = targets.map((target) => target.time);
+    // Both group members' edges are excluded; the non-member's edges remain.
+    expect(times).not.toContain(1);
+    expect(times).not.toContain(2);
+    expect(times).not.toContain(3);
+    expect(times).not.toContain(4);
+    expect(times).toContain(6);
+    expect(times).toContain(7);
+  });
+
  it("dedupes near-equal times from different sources", () => {
    const dragged = timelineElement({ id: "dragged", start: 2, duration: 2 });
    const other = timelineElement({ id: "other", start: 0.0004, duration: 10 });

    const targets = buildTimelineSnapTargets({
      elements: [dragged, other],
-      draggedKey: "dragged",
+      excludedKeys: new Set(["dragged"]),
      playhead: 5,
      compDuration: 10,
      beats: [0.0002, 10.0002],
@@ -43,7 +43,8 @@ function addTarget(targets: TimelineSnapTarget[], candidate: TimelineSnapTarget)

 export function buildTimelineSnapTargets(input: {
  elements: TimelineElement[];
-  draggedKey: string;
+  /** Keys of every clip moving in this gesture (the whole group), excluded as targets. */
+  excludedKeys: ReadonlySet<string>;
  playhead: number;
  compDuration: number;
  beats: number[];
@@ -56,7 +57,7 @@ export function buildTimelineSnapTargets(input: {

  for (const element of input.elements) {
    const elementKey = element.key ?? element.id;
-    if (elementKey === input.draggedKey || element.id === input.draggedKey) continue;
+    if (input.excludedKeys.has(elementKey) || input.excludedKeys.has(element.id)) continue;
    addTarget(targets, { time: element.start, kind: "edge" });
    addTarget(targets, { time: element.start + element.duration, kind: "edge" });
  }
@@ -14,19 +14,25 @@ import { useTimelineClipDrag } from "./useTimelineClipDrag";

 function timelineElement(input: {
  id: string;
+  tag?: string;
  track: number;
  zIndex: number;
  start?: number;
  duration?: number;
  sourceDuration?: number;
+  playbackStart?: number;
+  playbackRate?: number;
+  timelineLocked?: boolean;
 }): TimelineElement {
  return {
    id: input.id,
    domId: input.id,
-    tag: "div",
+    tag: input.tag ?? "div",
    start: input.start ?? 0,
    duration: input.duration ?? 2,
    sourceDuration: input.sourceDuration,
+    playbackStart: input.playbackStart,
+    playbackRate: input.playbackRate,
    track: input.track,
    zIndex: input.zIndex,
    stackingContextId: "root",
@@ -34,6 +40,7 @@ function timelineElement(input: {
    compositionAncestors: ["root"],
    sourceFile: "index.html",
    timingSource: "authored",
+    timelineLocked: input.timelineLocked,
  };
 }

@@ -43,11 +50,16 @@ afterEach(() => {
 });

 function renderDragHarness(elements: TimelineElement[]) {
+  usePlayerStore.getState().setElements(elements);
  const layers = buildStackingTimelineLayers(elements).rows;
  const scroll = document.createElement("div");
  document.body.append(scroll);
  const onMoveElement = vi.fn();
  const onResizeElement = vi.fn();
+  const onMoveElements = vi.fn();
+  const onResizeElements = vi.fn();
+  const onPreviewMoveElements = vi.fn();
+  const onPreviewResizeElements = vi.fn();
  let setDraggedClip: ((state: DraggedClipState | null) => void) | null = null;
  let setResizingClip: ((state: ResizingClipState | null) => void) | null = null;

@@ -60,6 +72,10 @@ function renderDragHarness(elements: TimelineElement[]) {
      timelineElementsRef: { current: elements },
      onMoveElement,
      onResizeElement,
+      onMoveElements,
+      onResizeElements,
+      onPreviewMoveElements,
+      onPreviewResizeElements,
      onBlockedEditAttempt: vi.fn(),
      setShowPopover: vi.fn(),
      setRangeSelectionRef: { current: vi.fn() },
@@ -84,7 +100,20 @@ function renderDragHarness(elements: TimelineElement[]) {
    layers,
    onMoveElement,
    onResizeElement,
+    onMoveElements,
+    onResizeElements,
+    onPreviewMoveElements,
+    onPreviewResizeElements,
+    storeElements() {
+      return usePlayerStore.getState().elements;
+    },
    startDrag(element: TimelineElement, layerIndex: number) {
+      const layer =
+        layers[layerIndex] ??
+        layers.find((candidate) =>
+          candidate.elements.some((candidateElement) => candidateElement.id === element.id),
+        ) ??
+        layers[0]!;
      act(() => {
        applyDraggedClip({
          element,
@@ -98,7 +127,7 @@ function renderDragHarness(elements: TimelineElement[]) {
          pointerOffsetY: 0,
          previewStart: element.start,
          previewTrack: element.track,
-          previewLayerId: layers[layerIndex]!.id,
+          previewLayerId: layer.id,
          previewLayerIndex: layerIndex,
          previewStackingReorder: null,
          snapBeatTime: null,
@@ -162,6 +191,114 @@ describe("useTimelineClipDrag", () => {
    harness.unmount();
  });

+  it("moves every selected clip body by the same delta", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 2 });
+    const second = timelineElement({ id: "second", track: 1, zIndex: 1, start: 4, duration: 2 });
+    const harness = renderDragHarness([first, second]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "second"], "first");
+    });
+
+    harness.startDrag(first, 0);
+    harness.movePointer(200, 0);
+
+    expect(harness.storeElements().map((element) => [element.id, element.start])).toEqual([
+      ["first", 3],
+      ["second", 6],
+    ]);
+    expect(harness.onPreviewMoveElements).toHaveBeenLastCalledWith([
+      { element: first, start: 3 },
+      { element: second, start: 6 },
+    ]);
+
+    await harness.dropPointer();
+
+    expect(harness.onMoveElement).not.toHaveBeenCalled();
+    expect(harness.onMoveElements).toHaveBeenCalledTimes(1);
+    expect(harness.onMoveElements).toHaveBeenCalledWith([
+      { element: first, start: 3 },
+      { element: second, start: 6 },
+    ]);
+
+    harness.unmount();
+  });
+
+  it("clamps a selected group move when the earliest member reaches zero", async () => {
+    const early = timelineElement({ id: "early", track: 0, zIndex: 1, start: 1, duration: 2 });
+    const grabbed = timelineElement({ id: "grabbed", track: 1, zIndex: 1, start: 4, duration: 2 });
+    const harness = renderDragHarness([early, grabbed]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["early", "grabbed"], "grabbed");
+    });
+
+    harness.startDrag(grabbed, 1);
+    harness.movePointer(-300, 0);
+    await harness.dropPointer();
+
+    expect(harness.onMoveElements).toHaveBeenCalledWith([
+      { element: early, start: 0 },
+      { element: grabbed, start: 3 },
+    ]);
+    expect(harness.onMoveElement).not.toHaveBeenCalled();
+
+    harness.unmount();
+  });
+
+  it("keeps body drag single-clip when the grabbed clip is not in the multi-selection", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 2 });
+    const second = timelineElement({ id: "second", track: 1, zIndex: 1, start: 4, duration: 2 });
+    const outside = timelineElement({ id: "outside", track: 2, zIndex: 1, start: 7, duration: 2 });
+    const harness = renderDragHarness([first, second, outside]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "second"], "first");
+    });
+
+    harness.startDrag(outside, 2);
+    harness.movePointer(200, 0);
+    await harness.dropPointer();
+
+    expect(harness.onMoveElements).not.toHaveBeenCalled();
+    expect(harness.onMoveElement).toHaveBeenCalledTimes(1);
+    expect(harness.onMoveElement).toHaveBeenCalledWith(
+      outside,
+      expect.objectContaining({ start: 9 }),
+    );
+
+    harness.unmount();
+  });
+
+  it("does not form a group when a selected member is locked (grabbed clip moves alone)", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 2 });
+    const locked = timelineElement({
+      id: "locked",
+      track: 1,
+      zIndex: 1,
+      start: 4,
+      duration: 2,
+      timelineLocked: true,
+    });
+    const harness = renderDragHarness([first, locked]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "locked"], "first");
+    });
+
+    harness.startDrag(first, 0);
+    harness.movePointer(200, 0);
+    await harness.dropPointer();
+
+    // The locked member forbids the op, so no group forms: the grabbed clip moves
+    // alone (single-clip path) and the locked clip is never touched.
+    expect(harness.onMoveElements).not.toHaveBeenCalled();
+    expect(harness.onMoveElement).toHaveBeenCalledTimes(1);
+    expect(harness.onMoveElement).toHaveBeenCalledWith(
+      first,
+      expect.objectContaining({ start: 3 }),
+    );
+    expect(harness.storeElements().find((el) => el.id === "locked")?.start).toBe(4);
+
+    harness.unmount();
+  });
+
  it("allows right-edge resize past the current composition duration", async () => {
    const clip = timelineElement({ id: "clip", track: 0, zIndex: 1, start: 6, duration: 2 });
    const harness = renderDragHarness([clip]);
@@ -178,6 +315,142 @@ describe("useTimelineClipDrag", () => {
    harness.unmount();
  });

+  it("resizes every selected start edge by the same delta", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 4 });
+    const second = timelineElement({ id: "second", track: 1, zIndex: 1, start: 5, duration: 3 });
+    const harness = renderDragHarness([first, second]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "second"], "first");
+    });
+
+    harness.startResize(first, "start");
+    harness.movePointer(100, 0);
+
+    expect(
+      harness.storeElements().map((element) => [element.id, element.start, element.duration]),
+    ).toEqual([
+      ["first", 2, 3],
+      ["second", 6, 2],
+    ]);
+    expect(harness.onPreviewResizeElements).toHaveBeenLastCalledWith([
+      { element: first, start: 2, duration: 3, playbackStart: undefined },
+      { element: second, start: 6, duration: 2, playbackStart: undefined },
+    ]);
+
+    await harness.dropPointer();
+
+    expect(harness.onResizeElement).not.toHaveBeenCalled();
+    expect(harness.onResizeElements).toHaveBeenCalledTimes(1);
+    expect(harness.onResizeElements).toHaveBeenCalledWith([
+      { element: first, start: 2, duration: 3, playbackStart: undefined },
+      { element: second, start: 6, duration: 2, playbackStart: undefined },
+    ]);
+
+    harness.unmount();
+  });
+
+  it("resizes every selected end edge by the same delta", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 4 });
+    const second = timelineElement({ id: "second", track: 1, zIndex: 1, start: 5, duration: 3 });
+    const harness = renderDragHarness([first, second]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "second"], "first");
+    });
+
+    harness.startResize(first, "end");
+    harness.movePointer(100, 0);
+    await harness.dropPointer();
+
+    expect(harness.onResizeElement).not.toHaveBeenCalled();
+    expect(harness.onResizeElements).toHaveBeenCalledWith([
+      { element: first, start: 1, duration: 5, playbackStart: undefined },
+      { element: second, start: 5, duration: 4, playbackStart: undefined },
+    ]);
+
+    harness.unmount();
+  });
+
+  it("clamps selected start-edge resize at the most constrained duration", async () => {
+    const short = timelineElement({ id: "short", track: 0, zIndex: 1, start: 1, duration: 0.5 });
+    const long = timelineElement({ id: "long", track: 1, zIndex: 1, start: 4, duration: 2 });
+    const harness = renderDragHarness([short, long]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["short", "long"], "short");
+    });
+
+    harness.startResize(short, "start");
+    harness.movePointer(100, 0);
+    await harness.dropPointer();
+
+    expect(harness.onResizeElements).toHaveBeenCalledWith([
+      { element: short, start: 1.4, duration: 0.1, playbackStart: undefined },
+      { element: long, start: 4.4, duration: 1.6, playbackStart: undefined },
+    ]);
+    expect(harness.onResizeElement).not.toHaveBeenCalled();
+
+    harness.unmount();
+  });
+
+  it("adjusts every selected media playback start during start-edge resize", async () => {
+    const audio = timelineElement({
+      id: "audio",
+      tag: "audio",
+      track: 0,
+      zIndex: 1,
+      start: 2,
+      duration: 3,
+      playbackStart: 1,
+      playbackRate: 1,
+    });
+    const video = timelineElement({
+      id: "video",
+      tag: "video",
+      track: 1,
+      zIndex: 1,
+      start: 5,
+      duration: 4,
+      playbackStart: 2,
+      playbackRate: 2,
+    });
+    const harness = renderDragHarness([audio, video]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["audio", "video"], "audio");
+    });
+
+    harness.startResize(audio, "start");
+    harness.movePointer(50, 0);
+    await harness.dropPointer();
+
+    expect(harness.onResizeElements).toHaveBeenCalledWith([
+      { element: audio, start: 2.5, duration: 2.5, playbackStart: 1.5 },
+      { element: video, start: 5.5, duration: 3.5, playbackStart: 3 },
+    ]);
+
+    harness.unmount();
+  });
+
+  it("keeps handle resize single-clip when the grabbed clip is not in the multi-selection", async () => {
+    const first = timelineElement({ id: "first", track: 0, zIndex: 1, start: 1, duration: 2 });
+    const second = timelineElement({ id: "second", track: 1, zIndex: 1, start: 4, duration: 2 });
+    const outside = timelineElement({ id: "outside", track: 2, zIndex: 1, start: 7, duration: 2 });
+    const harness = renderDragHarness([first, second, outside]);
+    act(() => {
+      usePlayerStore.getState().setSelection(["first", "second"], "first");
+    });
+
+    harness.startResize(outside, "end");
+    harness.movePointer(100, 0);
+    await harness.dropPointer();
+
+    expect(harness.onResizeElement).toHaveBeenCalledTimes(1);
+    expect(harness.onResizeElement).toHaveBeenCalledWith(
+      outside,
+      expect.objectContaining({ start: 7, duration: 3 }),
+    );
+
+    harness.unmount();
+  });
+
  it("passes a new-lane stacking intent when a vertical drag targets an overlapping lane", async () => {
    const front = timelineElement({ id: "front", track: 0, zIndex: 3 });
    const middle = timelineElement({ id: "middle", track: 1, zIndex: 2 });
@@ -13,12 +13,18 @@ import { TRACK_H } from "./timelineLayout";
 import { isMusicTrack } from "../../utils/timelineInspector";
 import { mergeUserBeats } from "../../utils/beatEditing";
 import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
+import type {
+  TimelineGroupMoveChange,
+  TimelineGroupResizeChange,
+} from "../../hooks/useTimelineGroupEditing";
 import {
  buildTimelineSnapTargets,
  snapEdgesToTargets,
  snapResizeEdgeToTargets,
  type TimelineSnapKind,
 } from "./timelineSnapTargets";
+import { resolveDragPreviewPlacement } from "./timelineClipDragPreview";
+import { useTimelineClipGroupDrag } from "./useTimelineClipGroupDrag";

 const EMPTY_BEAT_TIMES: number[] = [];

@@ -83,9 +89,13 @@ interface UseTimelineClipDragInput {
    element: TimelineElement,
    updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
  ) => Promise<void> | void;
+  onMoveElements?: (changes: TimelineGroupMoveChange[]) => Promise<void> | void;
+  onResizeElements?: (changes: TimelineGroupResizeChange[]) => Promise<void> | void;
+  onPreviewMoveElements?: (changes: TimelineGroupMoveChange[]) => void;
+  onPreviewResizeElements?: (changes: TimelineGroupResizeChange[]) => void;
  onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
  setShowPopover: (show: boolean) => void;
-  /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
+  /** Stable ref to the range selection setter, wired after mount to break circular dependency. */
  setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
 }

@@ -97,6 +107,10 @@ export function useTimelineClipDrag({
  timelineElementsRef,
  onMoveElement,
  onResizeElement,
+  onMoveElements,
+  onResizeElements,
+  onPreviewMoveElements,
+  onPreviewResizeElements,
  onBlockedEditAttempt,
  setShowPopover,
  setRangeSelectionRef,
@@ -140,14 +154,21 @@ export function useTimelineClipDrag({
  compositionDurationRef.current = compositionDuration;

  const buildSnapTargets = useCallback(
-    (element: TimelineElement) =>
-      buildTimelineSnapTargets({
+    (element: TimelineElement) => {
+      const draggedKey = element.key ?? element.id;
+      const selected = selectedElementIdsRef.current;
+      // In a group drag every selected clip moves together, so none of them may act
+      // as a snap target for the others; exclude the whole set, not just the grabbed clip.
+      const excludedKeys =
+        selected.size > 1 && selected.has(draggedKey) ? selected : new Set([draggedKey]);
+      return buildTimelineSnapTargets({
        elements: timelineElementsRef.current,
-        draggedKey: element.key ?? element.id,
+        excludedKeys,
        playhead: playheadRef.current,
        compDuration: compositionDurationRef.current,
        beats: isMusicTrack(element) ? EMPTY_BEAT_TIMES : beatTimesRef.current,
-      }),
+      });
+    },
    [timelineElementsRef],
  );

@@ -166,10 +187,35 @@ export function useTimelineClipDrag({
  onMoveElementRef.current = onMoveElement;
  const onResizeElementRef = useRef(onResizeElement);
  onResizeElementRef.current = onResizeElement;
+  const onMoveElementsRef = useRef(onMoveElements);
+  onMoveElementsRef.current = onMoveElements;
+  const onResizeElementsRef = useRef(onResizeElements);
+  onResizeElementsRef.current = onResizeElements;
+  const onPreviewMoveElementsRef = useRef(onPreviewMoveElements);
+  onPreviewMoveElementsRef.current = onPreviewMoveElements;
+  const onPreviewResizeElementsRef = useRef(onPreviewResizeElements);
+  onPreviewResizeElementsRef.current = onPreviewResizeElements;
+  const selectedElementIdsRef = useRef(usePlayerStore.getState().selectedElementIds);
+  selectedElementIdsRef.current = usePlayerStore((s) => s.selectedElementIds);

  const clipDragScrollRaf = useRef(0);
  const clipDragPointerRef = useRef<{ clientX: number; clientY: number } | null>(null);
+  const {
+    previewGroupMove,
+    previewGroupResize,
+    commitGroupMove,
+    commitGroupResize,
+    clearGroupDragSessions,
+  } = useTimelineClipGroupDrag({
+    timelineElementsRef,
+    updateElement,
+    onMoveElementsRef,
+    onResizeElementsRef,
+    onPreviewMoveElementsRef,
+    onPreviewResizeElementsRef,
+  });

+  // fallow-ignore-next-line complexity
  const updateDraggedClipPreview = useCallback(
    (drag: DraggedClipState, clientX: number, clientY: number): DraggedClipState => {
      const scroll = scrollRef.current;
@@ -203,22 +249,28 @@ export function useTimelineClipDrag({
        ppsRef.current,
        { maxStart: Number.POSITIVE_INFINITY },
      );
+      const groupMove = previewGroupMove(drag.element, selectedElementIdsRef.current, snap.start);
+      const placement = resolveDragPreviewPlacement(drag, nextMove, groupMove);
      return {
        ...drag,
        started: true,
        pointerClientX: clientX,
        pointerClientY: clientY,
-        previewStart: snap.start,
-        previewTrack: nextMove.track,
-        previewLayerId: nextMove.previewLayerId ?? drag.previewLayerId,
-        previewLayerIndex: nextMove.previewLayerIndex ?? drag.previewLayerIndex,
-        previewStackingReorder: nextMove.stackingReorder ?? null,
+        ...placement,
        snapBeatTime: snap.snapKind === "beat" ? snap.snapTime : null,
        snapGuideTime: snap.snapTime,
        snapGuideKind: snap.snapKind,
      };
    },
-    [scrollRef, ppsRef, trackOrderRef, timelineLayersRef, timelineElementsRef, buildSnapTargets],
+    [
+      scrollRef,
+      ppsRef,
+      trackOrderRef,
+      timelineLayersRef,
+      timelineElementsRef,
+      buildSnapTargets,
+      previewGroupMove,
+    ],
  );

  const stopClipDragAutoScroll = useCallback(() => {
@@ -277,6 +329,12 @@ export function useTimelineClipDrag({

  const updateDraggedClipPreviewRef = useRef(updateDraggedClipPreview);
  updateDraggedClipPreviewRef.current = updateDraggedClipPreview;
+  const commitGroupMoveRef = useRef(commitGroupMove);
+  commitGroupMoveRef.current = commitGroupMove;
+  const commitGroupResizeRef = useRef(commitGroupResize);
+  commitGroupResizeRef.current = commitGroupResize;
+  const clearGroupDragSessionsRef = useRef(clearGroupDragSessions);
+  clearGroupDragSessionsRef.current = clearGroupDragSessions;
  const syncClipDragAutoScrollRef = useRef(syncClipDragAutoScroll);
  syncClipDragAutoScrollRef.current = syncClipDragAutoScroll;
  const stopClipDragAutoScrollRef = useRef(stopClipDragAutoScroll);
@@ -360,7 +418,15 @@ export function useTimelineClipDrag({
            };
          }
        }
-
+        const groupResize = previewGroupResize(
+          resize.element,
+          selectedElementIdsRef.current,
+          resize.edge,
+          nextResize,
+        );
+        if (groupResize.active) {
+          nextResize = groupResize.updates;
+        }
        setResizingClip((prev) =>
          prev
            ? {
@@ -421,6 +487,8 @@ export function useTimelineClipDrag({
        suppressClickRef.current = true;
        clearSuppressedClick();

+        if (commitGroupResizeRef.current(resize.element)) return;
+
        const hasChanged =
          resize.previewStart !== resize.element.start ||
          resize.previewDuration !== resize.element.duration ||
@@ -467,6 +535,8 @@ export function useTimelineClipDrag({
      suppressClickRef.current = true;
      clearSuppressedClick();

+      if (commitGroupMoveRef.current(drag.element)) return;
+
      const hasStackingReorder =
        drag.previewStackingReorder != null && drag.previewStackingReorder.zIndexChanges.length > 0;
      const hasChanged = drag.previewStart !== drag.element.start || hasStackingReorder;
@@ -494,6 +564,7 @@ export function useTimelineClipDrag({
    window.addEventListener("pointerup", handleWindowPointerUp);
    window.addEventListener("pointercancel", handleWindowPointerUp);
    return () => {
+      clearGroupDragSessionsRef.current();
      stopClipDragAutoScrollRef.current();
      window.removeEventListener("pointermove", handleWindowPointerMove);
      window.removeEventListener("pointerup", handleWindowPointerUp);
@@ -0,0 +1,417 @@
+import { useCallback, useRef, type RefObject } from "react";
+import type {
+  TimelineGroupMoveChange,
+  TimelineGroupResizeChange,
+} from "../../hooks/useTimelineGroupEditing";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  getTimelineEditCapabilities,
+  resolveTimelineGroupMove,
+  resolveTimelineGroupResize,
+  type TimelineGroupResizeEdge,
+  type TimelineGroupTimingMember,
+} from "./timelineEditing";
+
+type TimelineResizeUpdates = Pick<TimelineElement, "start" | "duration" | "playbackStart">;
+
+type UpdateTimelineElement = (
+  elementId: string,
+  updates: Partial<Pick<TimelineElement, "start" | "duration" | "playbackStart">>,
+) => void;
+
+interface GroupTimingMember extends TimelineGroupTimingMember {
+  element: TimelineElement;
+  key: string;
+}
+
+interface MoveSession {
+  grabbedKey: string;
+  members: GroupTimingMember[];
+  changes: TimelineGroupMoveChange[];
+  hasChanged: boolean;
+}
+
+interface ResizeSession {
+  grabbedKey: string;
+  edge: TimelineGroupResizeEdge;
+  members: GroupTimingMember[];
+  changes: TimelineGroupResizeChange[];
+  hasChanged: boolean;
+}
+
+interface UseTimelineClipGroupDragInput {
+  timelineElementsRef: RefObject<TimelineElement[]>;
+  updateElement: UpdateTimelineElement;
+  onMoveElementsRef: RefObject<
+    ((changes: TimelineGroupMoveChange[]) => Promise<void> | void) | undefined
+  >;
+  onResizeElementsRef: RefObject<
+    ((changes: TimelineGroupResizeChange[]) => Promise<void> | void) | undefined
+  >;
+  onPreviewMoveElementsRef: RefObject<((changes: TimelineGroupMoveChange[]) => void) | undefined>;
+  onPreviewResizeElementsRef: RefObject<
+    ((changes: TimelineGroupResizeChange[]) => void) | undefined
+  >;
+}
+
+interface PreviewGroupMoveResult {
+  active: boolean;
+  previewStart: number;
+}
+
+interface PreviewGroupResizeResult {
+  active: boolean;
+  updates: TimelineResizeUpdates;
+}
+
+function elementKey(element: TimelineElement): string {
+  return element.key ?? element.id;
+}
+
+function isMediaElement(element: TimelineElement): boolean {
+  const normalizedTag = element.tag.toLowerCase();
+  return normalizedTag === "audio" || normalizedTag === "video";
+}
+
+function selectedElementSet(selectedElementIdsInput: Set<string>): Set<string> {
+  return selectedElementIdsInput instanceof Set ? selectedElementIdsInput : new Set<string>();
+}
+
+function selectedMembers(
+  grabbedElement: TimelineElement,
+  selectedElementIdsInput: Set<string>,
+  timelineElements: readonly TimelineElement[],
+  mapMember: (element: TimelineElement) => GroupTimingMember,
+  canEdit: (element: TimelineElement) => boolean,
+): GroupTimingMember[] | null {
+  const selectedElementIds = selectedElementSet(selectedElementIdsInput);
+  const grabbedKey = elementKey(grabbedElement);
+  if (selectedElementIds.size <= 1 || !selectedElementIds.has(grabbedKey)) return null;
+
+  const elements = timelineElements.filter((element) =>
+    selectedElementIds.has(elementKey(element)),
+  );
+  // A group edit must not touch a member that individually forbids this operation
+  // (e.g. a locked or implicitly-timed clip). If any member can't take it, don't form
+  // a group; the gesture degrades to a normal single-clip edit of the grabbed clip.
+  if (!elements.every(canEdit)) return null;
+  const members = elements.map(mapMember);
+  return members.length > 1 ? members : null;
+}
+
+function moveMember(element: TimelineElement): GroupTimingMember {
+  return {
+    element,
+    key: elementKey(element),
+    start: element.start,
+    duration: element.duration,
+  };
+}
+
+function resizeMember(edge: TimelineGroupResizeEdge, element: TimelineElement): GroupTimingMember {
+  const shouldSeedPlaybackStart = edge === "start" && isMediaElement(element);
+  return {
+    element,
+    key: elementKey(element),
+    start: element.start,
+    duration: element.duration,
+    playbackStart: shouldSeedPlaybackStart ? (element.playbackStart ?? 0) : element.playbackStart,
+    playbackRate: element.playbackRate,
+  };
+}
+
+function sameGesture(sessionKey: string, element: TimelineElement): boolean {
+  return sessionKey === elementKey(element);
+}
+
+function createMoveSession(
+  element: TimelineElement,
+  selectedElementIds: Set<string>,
+  timelineElements: readonly TimelineElement[],
+): MoveSession | null {
+  const members = selectedMembers(
+    element,
+    selectedElementIds,
+    timelineElements,
+    moveMember,
+    (candidate) => getTimelineEditCapabilities(candidate).canMove,
+  );
+  if (!members) return null;
+  return {
+    grabbedKey: elementKey(element),
+    members,
+    changes: [],
+    hasChanged: false,
+  };
+}
+
+function createResizeSession(
+  element: TimelineElement,
+  selectedElementIds: Set<string>,
+  timelineElements: readonly TimelineElement[],
+  edge: TimelineGroupResizeEdge,
+): ResizeSession | null {
+  const members = selectedMembers(
+    element,
+    selectedElementIds,
+    timelineElements,
+    (member) => resizeMember(edge, member),
+    (candidate) => {
+      const caps = getTimelineEditCapabilities(candidate);
+      return edge === "start" ? caps.canTrimStart : caps.canTrimEnd;
+    },
+  );
+  if (!members) return null;
+  return {
+    grabbedKey: elementKey(element),
+    edge,
+    members,
+    changes: [],
+    hasChanged: false,
+  };
+}
+
+function resolveMoveChanges(
+  session: MoveSession,
+  previewStart: number,
+): TimelineGroupMoveChange[] | null {
+  const grabbed = session.members.find((member) => member.key === session.grabbedKey);
+  if (!grabbed) return null;
+  const result = resolveTimelineGroupMove(session.members, previewStart - grabbed.start);
+  return result.members.map((member, index) => ({
+    element: session.members[index]!.element,
+    start: member.start,
+  }));
+}
+
+function resizeRawDelta(session: ResizeSession, updates: TimelineResizeUpdates): number | null {
+  const grabbed = session.members.find((member) => member.key === session.grabbedKey);
+  if (!grabbed) return null;
+  return session.edge === "start"
+    ? updates.start - grabbed.start
+    : updates.duration - grabbed.duration;
+}
+
+function resolveResizeChanges(
+  session: ResizeSession,
+  updates: TimelineResizeUpdates,
+): TimelineGroupResizeChange[] | null {
+  const rawDelta = resizeRawDelta(session, updates);
+  if (rawDelta == null) return null;
+  const result = resolveTimelineGroupResize(session.members, session.edge, rawDelta);
+  return result.members.map((member, index) => ({
+    element: session.members[index]!.element,
+    start: member.start,
+    duration: member.duration,
+    playbackStart: member.playbackStart,
+  }));
+}
+
+function moveSessionHasChanged(
+  session: MoveSession,
+  changes: readonly TimelineGroupMoveChange[],
+): boolean {
+  return changes.some((change, index) => change.start !== session.members[index]!.start);
+}
+
+function resizeSessionHasChanged(
+  session: ResizeSession,
+  changes: readonly TimelineGroupResizeChange[],
+): boolean {
+  return changes.some((change, index) => {
+    const member = session.members[index]!;
+    return (
+      change.start !== member.start ||
+      change.duration !== member.duration ||
+      change.playbackStart !== member.playbackStart
+    );
+  });
+}
+
+function previewStartForGrabbed(
+  session: MoveSession,
+  changes: readonly TimelineGroupMoveChange[],
+  fallback: number,
+): number {
+  const change = changes.find((candidate) => elementKey(candidate.element) === session.grabbedKey);
+  return change?.start ?? fallback;
+}
+
+function resizeUpdatesForGrabbed(
+  session: ResizeSession,
+  changes: readonly TimelineGroupResizeChange[],
+  fallback: TimelineResizeUpdates,
+): TimelineResizeUpdates {
+  const change = changes.find((candidate) => elementKey(candidate.element) === session.grabbedKey);
+  if (!change) return fallback;
+  return {
+    start: change.start,
+    duration: change.duration,
+    playbackStart: change.playbackStart,
+  };
+}
+
+export function useTimelineClipGroupDrag({
+  timelineElementsRef,
+  updateElement,
+  onMoveElementsRef,
+  onResizeElementsRef,
+  onPreviewMoveElementsRef,
+  onPreviewResizeElementsRef,
+}: UseTimelineClipGroupDragInput) {
+  const moveSessionRef = useRef<MoveSession | null>(null);
+  const resizeSessionRef = useRef<ResizeSession | null>(null);
+
+  const rollbackMove = useCallback(
+    (session: MoveSession) => {
+      const changes = session.members.map((member) => ({
+        element: member.element,
+        start: member.start,
+      }));
+      for (const change of changes) {
+        updateElement(elementKey(change.element), { start: change.start });
+      }
+      onPreviewMoveElementsRef.current?.(changes);
+    },
+    [onPreviewMoveElementsRef, updateElement],
+  );
+
+  const rollbackResize = useCallback(
+    (session: ResizeSession) => {
+      const changes = session.members.map((member) => ({
+        element: member.element,
+        start: member.start,
+        duration: member.duration,
+        playbackStart: member.playbackStart,
+      }));
+      for (const change of changes) {
+        updateElement(elementKey(change.element), {
+          start: change.start,
+          duration: change.duration,
+          playbackStart: change.playbackStart,
+        });
+      }
+      onPreviewResizeElementsRef.current?.(changes);
+    },
+    [onPreviewResizeElementsRef, updateElement],
+  );
+
+  const previewGroupMove = useCallback(
+    (
+      element: TimelineElement,
+      selectedElementIds: Set<string>,
+      previewStart: number,
+    ): PreviewGroupMoveResult => {
+      let session = moveSessionRef.current;
+      if (!session || !sameGesture(session.grabbedKey, element)) {
+        if (!onMoveElementsRef.current) return { active: false, previewStart };
+        session = createMoveSession(element, selectedElementIds, timelineElementsRef.current);
+        if (!session) return { active: false, previewStart };
+        moveSessionRef.current = session;
+      }
+
+      const changes = resolveMoveChanges(session, previewStart);
+      if (!changes) return { active: false, previewStart };
+      session.changes = changes;
+      session.hasChanged = moveSessionHasChanged(session, changes);
+
+      for (const change of changes) {
+        updateElement(elementKey(change.element), { start: change.start });
+      }
+      onPreviewMoveElementsRef.current?.(changes);
+
+      return {
+        active: true,
+        previewStart: previewStartForGrabbed(session, changes, previewStart),
+      };
+    },
+    [onMoveElementsRef, onPreviewMoveElementsRef, timelineElementsRef, updateElement],
+  );
+
+  const previewGroupResize = useCallback(
+    (
+      element: TimelineElement,
+      selectedElementIds: Set<string>,
+      edge: TimelineGroupResizeEdge,
+      updates: TimelineResizeUpdates,
+    ): PreviewGroupResizeResult => {
+      let session = resizeSessionRef.current;
+      if (!session || !sameGesture(session.grabbedKey, element) || session.edge !== edge) {
+        if (!onResizeElementsRef.current) return { active: false, updates };
+        session = createResizeSession(
+          element,
+          selectedElementIds,
+          timelineElementsRef.current,
+          edge,
+        );
+        if (!session) return { active: false, updates };
+        resizeSessionRef.current = session;
+      }
+
+      const changes = resolveResizeChanges(session, updates);
+      if (!changes) return { active: false, updates };
+      session.changes = changes;
+      session.hasChanged = resizeSessionHasChanged(session, changes);
+
+      for (const change of changes) {
+        updateElement(elementKey(change.element), {
+          start: change.start,
+          duration: change.duration,
+          playbackStart: change.playbackStart,
+        });
+      }
+      onPreviewResizeElementsRef.current?.(changes);
+
+      return {
+        active: true,
+        updates: resizeUpdatesForGrabbed(session, changes, updates),
+      };
+    },
+    [onPreviewResizeElementsRef, onResizeElementsRef, timelineElementsRef, updateElement],
+  );
+
+  const commitGroupMove = useCallback(
+    (element: TimelineElement): boolean => {
+      const session = moveSessionRef.current;
+      if (!session || !sameGesture(session.grabbedKey, element)) return false;
+      moveSessionRef.current = null;
+      if (!session.hasChanged) return true;
+
+      Promise.resolve(onMoveElementsRef.current?.(session.changes)).catch((error) => {
+        rollbackMove(session);
+        console.error("[Timeline] Failed to persist group clip move", error);
+      });
+      return true;
+    },
+    [onMoveElementsRef, rollbackMove],
+  );
+
+  const commitGroupResize = useCallback(
+    (element: TimelineElement): boolean => {
+      const session = resizeSessionRef.current;
+      if (!session || !sameGesture(session.grabbedKey, element)) return false;
+      resizeSessionRef.current = null;
+      if (!session.hasChanged) return true;
+
+      Promise.resolve(onResizeElementsRef.current?.(session.changes)).catch((error) => {
+        rollbackResize(session);
+        console.error("[Timeline] Failed to persist group clip resize", error);
+      });
+      return true;
+    },
+    [onResizeElementsRef, rollbackResize],
+  );
+
+  const clearGroupDragSessions = useCallback(() => {
+    moveSessionRef.current = null;
+    resizeSessionRef.current = null;
+  }, []);
+
+  return {
+    previewGroupMove,
+    previewGroupResize,
+    commitGroupMove,
+    commitGroupResize,
+    clearGroupDragSessions,
+  };
+}
@@ -0,0 +1,73 @@
+import { useCallback, type MouseEvent as ReactMouseEvent } from "react";
+import type { TimelineElement, KeyframeCacheEntry } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
+
+interface UseTimelineKeyframeHandlersInput {
+  expandedElements: TimelineElement[];
+  keyframeCache: Map<string, KeyframeCacheEntry>;
+  onSelectElement?: (element: TimelineElement | null) => void;
+  onSeek?: (time: number) => void;
+  setSelectedElementId: (id: string | null) => void;
+  setKfContextMenu: (state: KeyframeDiamondContextMenuState | null) => void;
+  toggleSelectedKeyframe: (key: string) => void;
+}
+
+export function useTimelineKeyframeHandlers({
+  expandedElements,
+  keyframeCache,
+  onSelectElement,
+  onSeek,
+  setSelectedElementId,
+  setKfContextMenu,
+  toggleSelectedKeyframe,
+}: UseTimelineKeyframeHandlersInput) {
+  const onClickKeyframe = useCallback(
+    (el: TimelineElement, pct: number) => {
+      usePlayerStore.getState().clearSelectedKeyframes();
+      const elKey = el.key ?? el.id;
+      setSelectedElementId(elKey);
+      onSelectElement?.(el);
+      toggleSelectedKeyframe(`${elKey}:${pct}`);
+      onSeek?.(el.start + (pct / 100) * el.duration);
+      const kfData = keyframeCache.get(elKey);
+      const kf = kfData?.keyframes.find((item) => Math.abs(item.percentage - pct) < 0.5);
+      usePlayerStore.getState().setActiveKeyframePct(kf?.tweenPercentage ?? null);
+    },
+    [keyframeCache, onSeek, onSelectElement, setSelectedElementId, toggleSelectedKeyframe],
+  );
+
+  const onShiftClickKeyframe = useCallback(
+    (elId: string, pct: number) => {
+      toggleSelectedKeyframe(`${elId}:${pct}`);
+    },
+    [toggleSelectedKeyframe],
+  );
+
+  const onContextMenuKeyframe = useCallback(
+    (e: ReactMouseEvent, elId: string, pct: number) => {
+      const el = expandedElements.find((item) => (item.key ?? item.id) === elId);
+      if (el) {
+        setSelectedElementId(elId);
+        onSelectElement?.(el);
+      }
+      const kfData = keyframeCache.get(elId);
+      const kf = kfData?.keyframes.find((item) => Math.abs(item.percentage - pct) < 0.2);
+      setKfContextMenu({
+        x: e.clientX + 4,
+        y: e.clientY + 2,
+        elementId: elId,
+        percentage: pct,
+        tweenPercentage: kf?.tweenPercentage,
+        currentEase: kf?.ease ?? kfData?.ease,
+      });
+    },
+    [expandedElements, keyframeCache, onSelectElement, setKfContextMenu, setSelectedElementId],
+  );
+
+  return {
+    onClickKeyframe,
+    onShiftClickKeyframe,
+    onContextMenuKeyframe,
+  };
+}
@@ -0,0 +1,231 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import { GUTTER, RULER_H, TRACK_H } from "./timelineLayout";
+import type { StackingTimelineLayer } from "./timelineTrackOrder";
+import { useTimelineMarqueeSelection } from "./useTimelineMarqueeSelection";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function element(id: string, start: number, duration: number, track: number): TimelineElement {
+  return { id, tag: "div", start, duration, track };
+}
+
+function layer(id: string, elements: TimelineElement[]): StackingTimelineLayer {
+  return {
+    id,
+    kind: "visual",
+    contextKey: "",
+    zIndex: 0,
+    placementTrack: elements[0]?.track ?? 0,
+    elements,
+  };
+}
+
+function pointerEvent(type: string, init: MouseEventInit & { pointerId?: number }) {
+  const event = new MouseEvent(type, { bubbles: true, cancelable: true, ...init });
+  Object.defineProperty(event, "pointerId", { value: init.pointerId ?? 1 });
+  return event;
+}
+
+function dispatchPointer(
+  target: HTMLElement,
+  type: "pointerdown" | "pointermove" | "pointerup",
+  point: { x: number; y: number },
+) {
+  target.dispatchEvent(pointerEvent(type, { button: 0, clientX: point.x, clientY: point.y }));
+}
+
+function dragMarquee(
+  harness: ReturnType<typeof renderMarqueeHarness>,
+  start: { x: number; y: number },
+  end: { x: number; y: number },
+  downTarget: HTMLElement = harness.scroll,
+) {
+  dispatchPointer(downTarget, "pointerdown", start);
+  dispatchPointer(harness.scroll, "pointermove", end);
+  dispatchPointer(harness.scroll, "pointerup", end);
+}
+
+function renderMarqueeHarness(layers: StackingTimelineLayer[]) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const layerOrder = layers.map((item) => item.id);
+  const setShowPopover = () => {};
+  const setRangeSelection = () => {};
+  const seekedX: number[] = [];
+
+  function Harness() {
+    const scrollRef = React.useRef<HTMLDivElement | null>(null);
+    const hook = useTimelineMarqueeSelection({
+      scrollRef,
+      ppsRef: { current: 100 },
+      trackOrderRef: { current: layerOrder },
+      timelineLayersRef: { current: layers },
+      setShowPopover,
+      setRangeSelectionRef: { current: setRangeSelection },
+      seekFromX: (clientX: number) => seekedX.push(clientX),
+    });
+    return (
+      <div
+        ref={scrollRef}
+        data-scroll="true"
+        onPointerDown={(event) => {
+          hook.handlePointerDown(event);
+        }}
+        onPointerMove={(event) => {
+          hook.handlePointerMove(event);
+        }}
+        onPointerUp={(event) => {
+          hook.handlePointerUp(event);
+        }}
+      >
+        <button data-clip="true">clip</button>
+        {hook.marqueeRect && <span data-marquee="true" />}
+      </div>
+    );
+  }
+
+  const root = createRoot(host);
+  act(() => {
+    root.render(<Harness />);
+  });
+  const scroll = host.querySelector<HTMLElement>("[data-scroll]");
+  if (!scroll) throw new Error("Expected scroll host");
+  Object.defineProperty(scroll, "clientWidth", { configurable: true, value: 160 });
+  Object.defineProperty(scroll, "clientHeight", { configurable: true, value: 160 });
+  Object.defineProperty(scroll, "scrollWidth", { configurable: true, value: 600 });
+  Object.defineProperty(scroll, "scrollHeight", { configurable: true, value: 260 });
+  scroll.getBoundingClientRect = () =>
+    ({
+      left: 0,
+      top: 0,
+      right: 160,
+      bottom: 160,
+      width: 160,
+      height: 160,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }) as DOMRect;
+
+  return {
+    host,
+    scroll,
+    root,
+    seekedX,
+    clip: host.querySelector<HTMLElement>("[data-clip]")!,
+    unmount() {
+      act(() => root.unmount());
+    },
+  };
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+describe("useTimelineMarqueeSelection", () => {
+  it("selects clips intersecting an empty-lane drag rectangle", () => {
+    const layers = [
+      layer("lane-0", [element("first", 0.5, 0.5, 0)]),
+      layer("lane-1", [element("second", 2, 0.5, 1)]),
+      layer("lane-2", [element("third", 0.5, 0.5, 2)]),
+    ];
+    const harness = renderMarqueeHarness(layers);
+    const start = { x: GUTTER + 10, y: RULER_H + 4 };
+    const end = { x: GUTTER + 260, y: RULER_H + TRACK_H * 2 - 2 };
+
+    act(() => {
+      dispatchPointer(harness.scroll, "pointerdown", start);
+      dispatchPointer(harness.scroll, "pointermove", end);
+    });
+    expect(harness.host.querySelector("[data-marquee]")).not.toBeNull();
+
+    act(() => {
+      dispatchPointer(harness.scroll, "pointerup", end);
+    });
+
+    expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["first", "second"]);
+    harness.unmount();
+  });
+
+  it("treats a sub-threshold empty-lane drag as a clear click that also seeks", () => {
+    usePlayerStore.getState().setSelection(["selected"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("selected", 0, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(harness, { x: GUTTER + 20, y: RULER_H + 4 }, { x: GUTTER + 21, y: RULER_H + 5 });
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    expect(harness.host.querySelector("[data-marquee]")).toBeNull();
+    // A sub-threshold press still scrubs the playhead to the click, like a plain lane click.
+    expect(harness.seekedX).toEqual([GUTTER + 20]);
+    harness.unmount();
+  });
+
+  it("does not start from clips or the ruler", () => {
+    usePlayerStore.getState().setSelection(["kept"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("kept", 0, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(
+        harness,
+        { x: GUTTER + 20, y: RULER_H + 4 },
+        { x: GUTTER + 80, y: RULER_H + 40 },
+        harness.clip,
+      );
+      dragMarquee(harness, { x: GUTTER + 20, y: RULER_H - 2 }, { x: GUTTER + 80, y: RULER_H + 40 });
+    });
+
+    expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["kept"]);
+    expect(harness.host.querySelector("[data-marquee]")).toBeNull();
+    harness.unmount();
+  });
+
+  it("clears selection when the released marquee hits no clips", () => {
+    usePlayerStore.getState().setSelection(["selected"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("selected", 4, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(harness, { x: GUTTER + 10, y: RULER_H + 4 }, { x: GUTTER + 80, y: RULER_H + 40 });
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    harness.unmount();
+  });
+
+  it("uses autoscroll position when resolving the released marquee", () => {
+    const originalRaf = window.requestAnimationFrame;
+    const originalCancel = window.cancelAnimationFrame;
+    const callbacks: FrameRequestCallback[] = [];
+    window.requestAnimationFrame = ((callback: FrameRequestCallback) => {
+      callbacks.push(callback);
+      return callbacks.length;
+    }) as typeof window.requestAnimationFrame;
+    window.cancelAnimationFrame = (() => {}) as typeof window.cancelAnimationFrame;
+    const harness = renderMarqueeHarness([layer("lane-0", [element("reachable", 1.28, 0.2, 0)])]);
+
+    try {
+      act(() => {
+        dispatchPointer(harness.scroll, "pointerdown", { x: GUTTER + 10, y: RULER_H + 4 });
+        dispatchPointer(harness.scroll, "pointermove", { x: 155, y: RULER_H + 40 });
+        callbacks.shift()?.(0);
+        dispatchPointer(harness.scroll, "pointerup", { x: 155, y: RULER_H + 40 });
+      });
+
+      expect(harness.scroll.scrollLeft).toBeGreaterThan(0);
+      expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["reachable"]);
+      harness.unmount();
+    } finally {
+      window.requestAnimationFrame = originalRaf;
+      window.cancelAnimationFrame = originalCancel;
+    }
+  });
+});
@@ -0,0 +1,276 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+} from "react";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  resolveTimelineAutoScroll,
+  selectTimelineElementsInMarquee,
+  type TimelineMarqueeSelectionRect,
+} from "./timelineEditing";
+import { GUTTER, RULER_H, TRACK_H } from "./timelineLayout";
+import { TIMELINE_LAYER_GROUP_HEADER_H } from "./TimelineLayerGroupHeader";
+import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
+
+const MARQUEE_THRESHOLD_PX = 4;
+
+export interface TimelineMarqueeOverlayRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+interface ActiveMarqueeGesture {
+  pointerId: number;
+  anchorClientX: number;
+  anchorClientY: number;
+  anchorX: number;
+  anchorY: number;
+  lastClientX: number;
+  lastClientY: number;
+  started: boolean;
+}
+
+interface UseTimelineMarqueeSelectionInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  ppsRef: RefObject<number>;
+  trackOrderRef: RefObject<TimelineLayerId[]>;
+  timelineLayersRef: RefObject<StackingTimelineLayer[]>;
+  disabled?: boolean;
+  setShowPopover: (show: boolean) => void;
+  setRangeSelectionRef: RefObject<((sel: null) => void) | null>;
+  /** Canonical playhead seek, used to keep empty-lane clicks scrubbing the playhead. */
+  seekFromX: (clientX: number) => void;
+}
+
+function getCanvasPoint(scroll: HTMLDivElement, clientX: number, clientY: number) {
+  const rect = scroll.getBoundingClientRect();
+  return {
+    x: clientX - rect.left + scroll.scrollLeft,
+    y: clientY - rect.top + scroll.scrollTop,
+  };
+}
+
+function getMarqueeStartPoint(
+  event: ReactPointerEvent<HTMLDivElement>,
+  scroll: HTMLDivElement | null,
+  disabled: boolean,
+) {
+  if (disabled || event.button !== 0 || event.shiftKey || !scroll) return null;
+  const target = event.target as HTMLElement;
+  if (target.closest("[data-clip]")) return null;
+  const point = getCanvasPoint(scroll, event.clientX, event.clientY);
+  if (point.x < GUTTER || point.y < RULER_H) return null;
+  return point;
+}
+
+function capturePointerIfAvailable(event: ReactPointerEvent<HTMLDivElement>) {
+  const currentTarget = event.currentTarget as HTMLElement;
+  if (typeof currentTarget.setPointerCapture === "function") {
+    currentTarget.setPointerCapture(event.pointerId);
+  }
+}
+
+function buildSelectionRect(
+  active: ActiveMarqueeGesture,
+  scroll: HTMLDivElement,
+  pps: number,
+): { overlay: TimelineMarqueeOverlayRect; selection: TimelineMarqueeSelectionRect } {
+  const current = getCanvasPoint(scroll, active.lastClientX, active.lastClientY);
+  const left = Math.min(active.anchorX, current.x);
+  const right = Math.max(active.anchorX, current.x);
+  const top = Math.min(active.anchorY, current.y);
+  const bottom = Math.max(active.anchorY, current.y);
+  const overlayLeft = Math.max(GUTTER, left);
+  const overlayTop = Math.max(RULER_H, top);
+  const overlayRight = Math.max(overlayLeft, right);
+  const overlayBottom = Math.max(overlayTop, bottom);
+
+  // Hit-test must use the SAME pixels-per-second the overlay is drawn at, or the
+  // selected time span diverges from the visible box at low zoom (pps < 1). Guard
+  // only against a non-finite/zero pps (would yield NaN/Infinity), never floor it.
+  const safePps = Number.isFinite(pps) && pps > 0 ? pps : 0;
+  const timeFromX = (x: number) => (safePps > 0 ? Math.max(0, (x - GUTTER) / safePps) : 0);
+
+  return {
+    overlay: {
+      left: overlayLeft,
+      top: overlayTop,
+      width: overlayRight - overlayLeft,
+      height: overlayBottom - overlayTop,
+    },
+    selection: {
+      startTime: timeFromX(left),
+      endTime: timeFromX(right),
+      top,
+      bottom,
+    },
+  };
+}
+
+export function useTimelineMarqueeSelection({
+  scrollRef,
+  ppsRef,
+  trackOrderRef,
+  timelineLayersRef,
+  disabled = false,
+  setShowPopover,
+  setRangeSelectionRef,
+  seekFromX,
+}: UseTimelineMarqueeSelectionInput) {
+  const activeRef = useRef<ActiveMarqueeGesture | null>(null);
+  const pointerRef = useRef<{ clientX: number; clientY: number } | null>(null);
+  const scrollRafRef = useRef(0);
+  const [marqueeRect, setMarqueeRect] = useState<TimelineMarqueeOverlayRect | null>(null);
+
+  const stopAutoScroll = useCallback(() => {
+    pointerRef.current = null;
+    if (scrollRafRef.current) {
+      cancelAnimationFrame(scrollRafRef.current);
+      scrollRafRef.current = 0;
+    }
+  }, []);
+
+  const updateMarqueeRect = useCallback(() => {
+    const active = activeRef.current;
+    const scroll = scrollRef.current;
+    if (!active || !scroll) return null;
+    const rects = buildSelectionRect(active, scroll, ppsRef.current);
+    setMarqueeRect(rects.overlay);
+    return rects;
+  }, [ppsRef, scrollRef]);
+
+  const stepAutoScroll = useCallback(() => {
+    scrollRafRef.current = 0;
+    const pointer = pointerRef.current;
+    const scroll = scrollRef.current;
+    if (!pointer || !scroll || !activeRef.current) return;
+
+    const delta = resolveTimelineAutoScroll(
+      scroll.getBoundingClientRect(),
+      pointer.clientX,
+      pointer.clientY,
+    );
+    if (delta.x === 0 && delta.y === 0) return;
+
+    const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+    const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
+    const nextScrollLeft = Math.max(0, Math.min(maxScrollLeft, scroll.scrollLeft + delta.x));
+    const nextScrollTop = Math.max(0, Math.min(maxScrollTop, scroll.scrollTop + delta.y));
+    if (nextScrollLeft === scroll.scrollLeft && nextScrollTop === scroll.scrollTop) return;
+
+    scroll.scrollLeft = nextScrollLeft;
+    scroll.scrollTop = nextScrollTop;
+    updateMarqueeRect();
+    scrollRafRef.current = requestAnimationFrame(stepAutoScroll);
+  }, [scrollRef, updateMarqueeRect]);
+
+  const syncAutoScroll = useCallback(
+    (clientX: number, clientY: number) => {
+      pointerRef.current = { clientX, clientY };
+      const scroll = scrollRef.current;
+      if (!scroll) return;
+      const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+      if (delta.x === 0 && delta.y === 0) {
+        if (scrollRafRef.current) {
+          cancelAnimationFrame(scrollRafRef.current);
+          scrollRafRef.current = 0;
+        }
+        return;
+      }
+      if (!scrollRafRef.current) {
+        scrollRafRef.current = requestAnimationFrame(stepAutoScroll);
+      }
+    },
+    [scrollRef, stepAutoScroll],
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const point = getMarqueeStartPoint(event, scrollRef.current, disabled);
+      if (!point) return false;
+      capturePointerIfAvailable(event);
+      activeRef.current = {
+        pointerId: event.pointerId,
+        anchorClientX: event.clientX,
+        anchorClientY: event.clientY,
+        anchorX: point.x,
+        anchorY: point.y,
+        lastClientX: event.clientX,
+        lastClientY: event.clientY,
+        started: false,
+      };
+      setShowPopover(false);
+      setRangeSelectionRef.current?.(null);
+      return true;
+    },
+    [disabled, scrollRef, setRangeSelectionRef, setShowPopover],
+  );
+
+  const handlePointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const active = activeRef.current;
+      if (!active || active.pointerId !== event.pointerId) return false;
+      active.lastClientX = event.clientX;
+      active.lastClientY = event.clientY;
+      const distance = Math.hypot(
+        event.clientX - active.anchorClientX,
+        event.clientY - active.anchorClientY,
+      );
+      if (!active.started && distance < MARQUEE_THRESHOLD_PX) return true;
+      active.started = true;
+      updateMarqueeRect();
+      syncAutoScroll(event.clientX, event.clientY);
+      return true;
+    },
+    [syncAutoScroll, updateMarqueeRect],
+  );
+
+  const handlePointerUp = useCallback(
+    (event?: ReactPointerEvent<HTMLDivElement>) => {
+      const active = activeRef.current;
+      if (!active || (event && active.pointerId !== event.pointerId)) return false;
+      activeRef.current = null;
+      stopAutoScroll();
+      setMarqueeRect(null);
+
+      if (!active.started) {
+        // A press that never crossed the marquee threshold is a plain empty-lane
+        // click: clear the selection AND scrub the playhead, matching the seek that
+        // the range/playhead handler would have run had the marquee not claimed it.
+        usePlayerStore.getState().clearSelection();
+        seekFromX(active.anchorClientX);
+        return true;
+      }
+
+      const scroll = scrollRef.current;
+      if (!scroll) return true;
+      const rects = buildSelectionRect(active, scroll, ppsRef.current);
+      const selectedIds = selectTimelineElementsInMarquee({
+        rect: rects.selection,
+        layers: timelineLayersRef.current,
+        layerOrder: trackOrderRef.current,
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+        groupHeaderHeight: TIMELINE_LAYER_GROUP_HEADER_H,
+      });
+      usePlayerStore.getState().setSelection(selectedIds);
+      return true;
+    },
+    [ppsRef, scrollRef, seekFromX, stopAutoScroll, timelineLayersRef, trackOrderRef],
+  );
+
+  useEffect(() => stopAutoScroll, [stopAutoScroll]);
+
+  return {
+    marqueeRect,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+  };
+}