@hyperframes/studio 0.7.90 → 0.7.92

package/src/player/components/useTimelineKeyframeHandlers.ts

@@ -1,13 +1,475 @@
-import { useCallback, type MouseEvent as ReactMouseEvent } from "react";
+import {
+  useCallback,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
+import { clipToTweenPercentage } from "../../components/editor/KeyframeNavigation";
+import {
+  KEYFRAME_DRAG_THRESHOLD_PX,
+  previewClipPct,
+  resolveKeyframeDrag,
+} from "../../components/editor/keyframeDrag";
 import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
+import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
 import type { TimelineElement, KeyframeCacheEntry } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
 import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
+import {
+  applyTimelineHorizontalAutoScrollStep,
+  resolveTimelineAutoScrollLoopAction,
+} from "./timelineEditing";
 import {
   timelineKeyframeSelectionKey,
   type TimelineKeyframeTarget,
 } from "./timelineKeyframeIdentity";
 
+interface TimelineRetimeKeyframe {
+  percentage: number;
+  tweenPercentage?: number;
+  propertyGroup?: string;
+  animationId?: string;
+  collidingAnimationTargets?: AnimationKeyframeTarget[];
+}
+
+interface TimelineKeyframeRetimeInput {
+  event: ReactPointerEvent<HTMLElement>;
+  elementId: string;
+  keyframeKey: string;
+  target: TimelineKeyframeTarget;
+  keyframes: readonly TimelineRetimeKeyframe[];
+  clipWidthPx: number;
+  draggedIndex: number;
+  sortedClipPercentages: readonly number[];
+  onMove: (target: TimelineKeyframeTarget, toClipPercentage: number) => Promise<boolean>;
+  onSelect: (target: TimelineKeyframeTarget, additive: boolean) => void;
+  suppressNextClick: () => void;
+  /**
+   * Selection key of a cache keyframe, used to retire a pending entry once the
+   * authoritative cache reflects THAT keyframe at its destination. Without it a
+   * bare "some keyframe is near that %" test retires the entry whenever an
+   * unrelated sibling happens to sit there, which is easy to hit on an evenly
+   * spaced row.
+   */
+  keyframeKeyOf: (keyframe: TimelineRetimeKeyframe) => string;
+}
+
+interface PendingTimelineKeyframeRetime {
+  elementId: string;
+  clipPercentage: number;
+  tweenPercentage: number;
+  destinationKeyframeKey: string;
+  sessionEpoch: number;
+}
+
+interface TimelineKeyframeRetimePreview {
+  keyframeKey: string;
+  clipPercentage: number;
+}
+
+interface TimelineKeyframeRetimeActor extends TimelineKeyframeRetimeInput {
+  phase: "active" | "committing" | "cancelled" | "complete";
+  pointerId: number | null;
+  pointerDownX: number;
+  lastClientX: number;
+  lastClientY: number;
+  originScrollLeft: number;
+  fromClipPercentage: number;
+  moved: boolean;
+  sessionEpoch: number;
+  sourceWasPresent: boolean;
+  scrollRaf: number;
+  unsubscribeStore: (() => void) | null;
+  teardownListeners: (() => void) | null;
+}
+
+interface TimelineKeyframeRetimeCoordinator {
+  actor: TimelineKeyframeRetimeActor | null;
+  pending: Map<string, PendingTimelineKeyframeRetime>;
+  preview: TimelineKeyframeRetimePreview | null;
+  previewListeners: Set<(preview: TimelineKeyframeRetimePreview | null) => void>;
+  /**
+   * The most recent retime dispatched through this viewport, whichever diamond
+   * it came from. Selection is viewport-wide, so "is my revert still relevant"
+   * is a viewport-wide question, not a per-keyframe one.
+   */
+  latest: PendingTimelineKeyframeRetime | null;
+}
+
+type TimelineRetimePointerEvent = Pick<
+  PointerEvent,
+  "clientX" | "clientY" | "pointerId" | "shiftKey"
+>;
+
+const keyframeRetimeCoordinators = new WeakMap<EventTarget, TimelineKeyframeRetimeCoordinator>();
+
+function getRetimeOwner(target: HTMLElement): EventTarget {
+  return target.closest<HTMLElement>("[data-timeline-scroll-viewport]") ?? target.ownerDocument;
+}
+
+function getRetimeCoordinator(owner: EventTarget): TimelineKeyframeRetimeCoordinator {
+  const existing = keyframeRetimeCoordinators.get(owner);
+  if (existing) return existing;
+  const coordinator: TimelineKeyframeRetimeCoordinator = {
+    actor: null,
+    pending: new Map(),
+    preview: null,
+    previewListeners: new Set(),
+    latest: null,
+  };
+  keyframeRetimeCoordinators.set(owner, coordinator);
+  return coordinator;
+}
+
+function stablePointerId(pointerId: number): number | null {
+  return Number.isFinite(pointerId) ? pointerId : null;
+}
+
+/**
+ * The retime destinations already dispatched from `source`'s viewport but not
+ * yet reflected in the keyframe cache. A renderer clamping a drag against its
+ * neighbours has to compose these in, or a second drag can cross a neighbour
+ * that already moved past it.
+ */
+export function readPendingTimelineKeyframeRetimes(
+  source: HTMLElement | null | undefined,
+): ReadonlyMap<string, { clipPercentage: number; tweenPercentage: number }> {
+  if (!source) return EMPTY_PENDING_RETIMES;
+  return keyframeRetimeCoordinators.get(getRetimeOwner(source))?.pending ?? EMPTY_PENDING_RETIMES;
+}
+
+const EMPTY_PENDING_RETIMES: ReadonlyMap<
+  string,
+  { clipPercentage: number; tweenPercentage: number }
+> = new Map();
+
+function publishRetimePreview(
+  coordinator: TimelineKeyframeRetimeCoordinator,
+  preview: TimelineKeyframeRetimePreview | null,
+): void {
+  coordinator.preview = preview;
+  for (const listener of coordinator.previewListeners) listener(preview);
+}
+
+export function subscribeTimelineKeyframeRetimePreview(
+  source: HTMLElement,
+  listener: (preview: TimelineKeyframeRetimePreview | null) => void,
+): () => void {
+  const coordinator = getRetimeCoordinator(getRetimeOwner(source));
+  coordinator.previewListeners.add(listener);
+  listener(coordinator.preview);
+  return () => coordinator.previewListeners.delete(listener);
+}
+
+function resolveRetimeTweenPercentage(
+  actor: TimelineKeyframeRetimeActor,
+  toClipPercentage: number,
+): number {
+  const animationKeyframes =
+    actor.target.animationId === undefined
+      ? actor.keyframes
+      : actor.keyframes.filter((keyframe) => keyframe.animationId === actor.target.animationId);
+  const tweenPercentages = animationKeyframes
+    .map((keyframe) => keyframe.tweenPercentage)
+    .filter((value): value is number => typeof value === "number");
+  const mapped = clipToTweenPercentage(animationKeyframes, toClipPercentage);
+  if (tweenPercentages.length === 0) return mapped;
+  return Math.max(Math.min(...tweenPercentages), Math.min(Math.max(...tweenPercentages), mapped));
+}
+
+export interface TimelineKeyframeRetimeHandle {
+  update: (event: ReactPointerEvent<HTMLElement>) => void;
+  commit: (event: ReactPointerEvent<HTMLElement>) => void;
+  cancel: (event: ReactPointerEvent<HTMLElement>) => void;
+}
+
+/**
+ * Starts a keyframe retime on the stable timeline viewport. The row/button is
+ * only an entry point: window listeners own the gesture through virtualization.
+ */
+export function beginTimelineKeyframeRetime(
+  input: TimelineKeyframeRetimeInput,
+): TimelineKeyframeRetimeHandle {
+  const source = input.event.currentTarget;
+  const owner = getRetimeOwner(source);
+  const viewport = owner instanceof HTMLElement ? owner : null;
+  const coordinator = getRetimeCoordinator(owner);
+  const sessionEpoch = usePlayerStore.getState().timelineSessionEpoch;
+
+  const cancel = (actor: TimelineKeyframeRetimeActor) => {
+    if (actor.phase !== "active") return;
+    actor.phase = "cancelled";
+    publishRetimePreview(coordinator, null);
+    if (actor.scrollRaf) cancelAnimationFrame(actor.scrollRaf);
+    actor.unsubscribeStore?.();
+    actor.teardownListeners?.();
+    if (viewport && actor.pointerId !== null) {
+      try {
+        viewport.releasePointerCapture(actor.pointerId);
+      } catch {
+        // Window listeners remain the native fallback when capture is unavailable.
+      }
+    }
+    if (coordinator.actor === actor) {
+      coordinator.actor = null;
+    }
+    actor.phase = "complete";
+  };
+
+  if (coordinator.actor) cancel(coordinator.actor);
+
+  for (const [key, pending] of coordinator.pending) {
+    if (pending.sessionEpoch !== sessionEpoch) coordinator.pending.delete(key);
+  }
+
+  for (const [key, pending] of coordinator.pending) {
+    // Tolerance, not equality: cache writers round clip %s, so an exact check
+    // would leak an entry after every successful retime.
+    if (
+      pending.elementId === input.elementId &&
+      input.keyframes.some(
+        (keyframe) =>
+          input.keyframeKeyOf(keyframe) === pending.destinationKeyframeKey &&
+          Math.abs(keyframe.percentage - pending.clipPercentage) < 0.2,
+      )
+    ) {
+      coordinator.pending.delete(key);
+    }
+  }
+
+  const pending = coordinator.pending.get(input.keyframeKey);
+  const actor: TimelineKeyframeRetimeActor = {
+    ...input,
+    phase: "active",
+    pointerId: stablePointerId(input.event.pointerId),
+    pointerDownX: input.event.clientX,
+    lastClientX: input.event.clientX,
+    lastClientY: input.event.clientY,
+    originScrollLeft: viewport?.scrollLeft ?? 0,
+    fromClipPercentage: pending?.clipPercentage ?? input.target.percentage,
+    moved: false,
+    sessionEpoch,
+    sourceWasPresent: usePlayerStore
+      .getState()
+      .elements.some((element) => (element.key ?? element.id) === input.elementId),
+    scrollRaf: 0,
+    unsubscribeStore: null,
+    teardownListeners: null,
+  };
+  coordinator.actor = actor;
+
+  const matchesPointer = (event: TimelineRetimePointerEvent) =>
+    actor.pointerId === null || event.pointerId === actor.pointerId;
+  const pointerXWithScroll = () =>
+    actor.lastClientX + (viewport?.scrollLeft ?? 0) - actor.originScrollLeft;
+  const publishPreview = () => {
+    publishRetimePreview(coordinator, {
+      keyframeKey: actor.keyframeKey,
+      clipPercentage: previewClipPct({
+        pointerDownX: actor.pointerDownX,
+        pointerMoveX: pointerXWithScroll(),
+        clipWidthPx: actor.clipWidthPx,
+        draggedClipPct: actor.fromClipPercentage,
+        draggedIndex: actor.draggedIndex,
+        sortedClipPcts: actor.sortedClipPercentages,
+      }),
+    });
+  };
+  const stopAutoScroll = () => {
+    if (actor.scrollRaf) cancelAnimationFrame(actor.scrollRaf);
+    actor.scrollRaf = 0;
+  };
+  const stepAutoScroll = () => {
+    actor.scrollRaf = 0;
+    if (
+      actor.phase !== "active" ||
+      !viewport ||
+      !applyTimelineHorizontalAutoScrollStep(viewport, actor.lastClientX)
+    ) {
+      return;
+    }
+    publishPreview();
+    actor.scrollRaf = requestAnimationFrame(stepAutoScroll);
+  };
+  const syncAutoScroll = () => {
+    if (!viewport || !actor.moved) return;
+    const action = resolveTimelineAutoScrollLoopAction(
+      viewport,
+      actor.lastClientX,
+      actor.lastClientY,
+      actor.scrollRaf !== 0,
+    );
+    if (action === "stop") stopAutoScroll();
+    else if (action === "start") actor.scrollRaf = requestAnimationFrame(stepAutoScroll);
+  };
+  const teardown = () => {
+    stopAutoScroll();
+    actor.unsubscribeStore?.();
+    actor.unsubscribeStore = null;
+    actor.teardownListeners?.();
+    actor.teardownListeners = null;
+  };
+  const releaseCapture = () => {
+    if (!viewport || actor.pointerId === null) return;
+    try {
+      viewport.releasePointerCapture(actor.pointerId);
+    } catch {
+      // Capture may already have been released by the browser.
+    }
+  };
+
+  const claimActorForCommit = (event: TimelineRetimePointerEvent): boolean => {
+    if (actor.phase !== "active" || !matchesPointer(event)) return false;
+    if (actor.sessionEpoch !== usePlayerStore.getState().timelineSessionEpoch) {
+      cancel(actor);
+      return false;
+    }
+    actor.phase = "committing";
+    actor.lastClientX = event.clientX;
+    actor.lastClientY = event.clientY;
+    teardown();
+    releaseCapture();
+    publishRetimePreview(coordinator, null);
+    if (coordinator.actor === actor) {
+      coordinator.actor = null;
+    }
+    actor.suppressNextClick();
+    return true;
+  };
+
+  const commitMove = (toClipPercentage: number) => {
+    const newTweenPercentage = resolveRetimeTweenPercentage(actor, toClipPercentage);
+    const pendingBefore = coordinator.pending.get(actor.keyframeKey);
+    const fromTarget = pendingBefore
+      ? {
+          ...actor.target,
+          percentage: pendingBefore.clipPercentage,
+          tweenPercentage: pendingBefore.tweenPercentage,
+        }
+      : actor.target;
+    const nextPending = {
+      elementId: actor.elementId,
+      clipPercentage: toClipPercentage,
+      tweenPercentage: newTweenPercentage,
+      destinationKeyframeKey: timelineKeyframeSelectionKey(actor.elementId, {
+        ...actor.target,
+        percentage: toClipPercentage,
+        tweenPercentage: newTweenPercentage,
+      }),
+      sessionEpoch: actor.sessionEpoch,
+    };
+    coordinator.pending.set(actor.keyframeKey, nextPending);
+    coordinator.latest = nextPending;
+    const clearPending = () => {
+      if (coordinator.pending.get(actor.keyframeKey) === nextPending) {
+        coordinator.pending.delete(actor.keyframeKey);
+      }
+    };
+    // A rejected drop (the destination time is already occupied) snaps the
+    // diamond back to its source position, so the pending entry AND the
+    // selection have to revert with it: parking on the ghost drop position
+    // strands the playhead + selection on a keyframe that is not there.
+    const revertRetime = () => {
+      // Only the newest gesture owns the selection. A rejected first drag
+      // whose commit settles after a second one started would otherwise park
+      // the selection back on ITS source keyframe, undoing a retime the user
+      // has already made and moving the playhead with it.
+      const isLatest = coordinator.latest === nextPending;
+      clearPending();
+      if (isLatest) actor.onSelect(fromTarget, false);
+    };
+    void actor.onMove(fromTarget, toClipPercentage).then((committed) => {
+      if (!committed) revertRetime();
+    }, revertRetime);
+    actor.onSelect(
+      {
+        ...actor.target,
+        percentage: toClipPercentage,
+        tweenPercentage: newTweenPercentage,
+      },
+      false,
+    );
+  };
+
+  const finishCommit = (event: TimelineRetimePointerEvent) => {
+    if (!claimActorForCommit(event)) return;
+    const result = resolveKeyframeDrag({
+      pointerDownX: actor.pointerDownX,
+      pointerUpX: pointerXWithScroll(),
+      clipWidthPx: actor.clipWidthPx,
+      draggedClipPct: actor.fromClipPercentage,
+      draggedIndex: actor.draggedIndex,
+      sortedClipPcts: actor.sortedClipPercentages,
+    });
+    if (result.kind === "move" && result.toClipPct !== undefined) {
+      commitMove(result.toClipPct);
+    } else {
+      actor.onSelect(actor.target, event.shiftKey);
+    }
+    actor.phase = "complete";
+  };
+  const onPointerMove = (event: TimelineRetimePointerEvent) => {
+    if (actor.phase !== "active" || !matchesPointer(event)) return;
+    actor.lastClientX = event.clientX;
+    actor.lastClientY = event.clientY;
+    if (
+      !actor.moved &&
+      Math.abs(pointerXWithScroll() - actor.pointerDownX) >= KEYFRAME_DRAG_THRESHOLD_PX
+    ) {
+      actor.moved = true;
+    }
+    if (actor.moved) publishPreview();
+    syncAutoScroll();
+  };
+  const onPointerUp = (event: TimelineRetimePointerEvent) => finishCommit(event);
+  const onPointerCancel = (event: TimelineRetimePointerEvent) => {
+    if (actor.phase === "active" && matchesPointer(event)) cancel(actor);
+  };
+  const onLostPointerCapture = (event: PointerEvent) => {
+    if (actor.phase === "active" && matchesPointer(event)) cancel(actor);
+  };
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key === "Escape") cancel(actor);
+  };
+
+  window.addEventListener("pointermove", onPointerMove, true);
+  window.addEventListener("pointerup", onPointerUp, true);
+  window.addEventListener("pointercancel", onPointerCancel, true);
+  window.addEventListener("keydown", onKeyDown);
+  viewport?.addEventListener("lostpointercapture", onLostPointerCapture);
+  actor.teardownListeners = () => {
+    window.removeEventListener("pointermove", onPointerMove, true);
+    window.removeEventListener("pointerup", onPointerUp, true);
+    window.removeEventListener("pointercancel", onPointerCancel, true);
+    window.removeEventListener("keydown", onKeyDown);
+    viewport?.removeEventListener("lostpointercapture", onLostPointerCapture);
+  };
+  actor.unsubscribeStore = usePlayerStore.subscribe((state) => {
+    const sourceStillPresent = state.elements.some(
+      (element) => (element.key ?? element.id) === actor.elementId,
+    );
+    if (state.timelineSessionEpoch !== actor.sessionEpoch) {
+      coordinator.pending.clear();
+      coordinator.latest = null;
+      cancel(actor);
+    } else if (actor.sourceWasPresent && !sourceStillPresent) {
+      for (const [key, pending] of coordinator.pending) {
+        if (pending.elementId === actor.elementId) coordinator.pending.delete(key);
+      }
+      if (coordinator.latest?.elementId === actor.elementId) coordinator.latest = null;
+      cancel(actor);
+    }
+  });
+
+  if (viewport && actor.pointerId !== null) {
+    try {
+      viewport.setPointerCapture(actor.pointerId);
+    } catch {
+      // Window listeners are the native fallback when capture is unavailable.
+    }
+  }
+  return { update: onPointerMove, commit: onPointerUp, cancel: onPointerCancel };
+}
+
 interface UseTimelineKeyframeHandlersInput {
   expandedElements: TimelineElement[];
   keyframeCache: Map<string, KeyframeCacheEntry>;
@@ -88,12 +550,13 @@ export function useTimelineKeyframeHandlers({
       setKfContextMenu({
         x: e.clientX + 4,
         y: e.clientY + 2,
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+        element: el,
         elementId: elId,
         percentage: target.percentage,
         tweenPercentage: target.tweenPercentage ?? kf?.tweenPercentage,
         propertyGroup: target.propertyGroup,
         animationId: target.animationId,
-        element: el,
         currentEase: kf?.ease ?? kfData?.ease,
       });
     },

package/src/player/components/useTimelineLaneMoveRefresh.ts

@@ -0,0 +1,7 @@
+import { useCallback } from "react";
+import { useStudioPlaybackContextOptional } from "../../contexts/StudioContext";
+
+export function useTimelineLaneMoveRefresh(): () => void {
+  const setRefreshKey = useStudioPlaybackContextOptional()?.setRefreshKey;
+  return useCallback(() => setRefreshKey?.((key) => key + 1), [setRefreshKey]);
+}

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

@@ -0,0 +1,204 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { createTimelineRowGeometry, getTimelineRowTop } from "./timelineLayout";
+import { createTimelineClipIndex } from "../lib/timelineClipIndex";
+import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { configureTimelineTestViewport } from "./timelineTestViewport";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const elements: TimelineElement[] = [
+  { id: "first", tag: "div", start: 1, duration: 1, track: 0 },
+  { id: "offscreen", tag: "div", start: 2, duration: 1, track: 50 },
+  { id: "base", tag: "div", start: 8, duration: 1, track: 99 },
+];
+const tracks = Array.from({ length: 100 }, (_, index) => index);
+const geometry = createTimelineRowGeometry(
+  tracks,
+  tracks.map(() => 48),
+);
+const clipIndex = createTimelineClipIndex(
+  tracks.map((track) => [track, elements.filter((element) => element.track === track)]),
+);
+const FIRST_ROW_Y = getTimelineRowTop(0) + 4;
+const OFFSCREEN_ROW_Y = getTimelineRowTop(50) + 40;
+
+function pointer(
+  currentTarget: HTMLElement,
+  pointerId: number,
+  clientX: number,
+  clientY: number,
+  init: Partial<React.PointerEvent> = {},
+): React.PointerEvent {
+  return {
+    button: 0,
+    clientX,
+    clientY,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    pointerId,
+    currentTarget,
+    target: currentTarget,
+    ...init,
+  } as React.PointerEvent;
+}
+
+function renderHarness(sessionEpoch = 1) {
+  usePlayerStore.setState({ timelineSessionEpoch: sessionEpoch });
+  const host = document.createElement("div");
+  const scroll = document.createElement("div");
+  scroll.setPointerCapture = vi.fn();
+  configureTimelineTestViewport(scroll, geometry.canvasHeight);
+  host.append(scroll);
+  document.body.append(host);
+  const root = createRoot(host);
+  let api: ReturnType<typeof useTimelineRangeSelection> | null = null;
+  const ppsRef = { current: 100 };
+  const dragScrollRaf = { current: 0 };
+  const isDragging = { current: false };
+  const elementsRef = { current: elements };
+  const rowGeometryRef = { current: geometry };
+  const seekFromX = vi.fn();
+
+  function Probe({ epoch }: { epoch: number }) {
+    api = useTimelineRangeSelection({
+      scrollRef: { current: scroll },
+      ppsRef,
+      effectiveDuration: 60,
+      pps: 100,
+      seekFromX,
+      autoScrollDuringDrag: vi.fn(),
+      dragScrollRaf,
+      isDragging,
+      setShowPopover: vi.fn(),
+      elementsRef,
+      clipIndex,
+      rowGeometryRef,
+      contentOrigin: 0,
+      sessionEpoch: epoch,
+    });
+    return null;
+  }
+
+  act(() => root.render(<Probe epoch={sessionEpoch} />));
+  return {
+    scroll,
+    root,
+    get api() {
+      if (!api) throw new Error("selection harness did not render");
+      return api;
+    },
+    rerender(epoch: number) {
+      usePlayerStore.setState({ timelineSessionEpoch: epoch });
+      act(() => root.render(<Probe epoch={epoch} />));
+    },
+    seekFromX,
+  };
+}
+
+function dragMarquee(
+  view: ReturnType<typeof renderHarness>,
+  options: { secondPointer?: boolean; release?: boolean } = {},
+): void {
+  act(() => {
+    view.api.handlePointerDown(pointer(view.scroll, 7, 0, FIRST_ROW_Y));
+    if (options.secondPointer) {
+      view.api.handlePointerDown(pointer(view.scroll, 8, 500, FIRST_ROW_Y));
+    }
+    view.api.handlePointerMove(pointer(view.scroll, 7, 400, OFFSCREEN_ROW_Y));
+    if (options.release) {
+      view.api.handlePointerUp(pointer(view.scroll, 7, 400, OFFSCREEN_ROW_Y));
+    }
+  });
+}
+
+function expectSelectedIds(...ids: string[]): void {
+  expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(ids));
+}
+
+function unmountHarness(view: ReturnType<typeof renderHarness>): void {
+  act(() => view.root.unmount());
+}
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.innerHTML = "";
+});
+
+describe("useTimelineRangeSelection", () => {
+  it("marquee-selects model clips across unmounted virtual rows", () => {
+    const view = renderHarness();
+    dragMarquee(view);
+
+    expect(document.querySelectorAll("[data-clip]")).toHaveLength(0);
+    expectSelectedIds("first", "offscreen");
+    unmountHarness(view);
+  });
+
+  it("ignores another pointer and restores the pre-drag selection on cancellation", () => {
+    usePlayerStore.getState().setSelectedElementId("base");
+    const view = renderHarness();
+    dragMarquee(view);
+    act(() => view.api.handlePointerUp(pointer(view.scroll, 8, 400, OFFSCREEN_ROW_Y)));
+    expectSelectedIds("first", "offscreen");
+
+    act(() => view.api.handlePointerCancel(pointer(view.scroll, 7, 400, OFFSCREEN_ROW_Y)));
+    expect(usePlayerStore.getState().selectedElementId).toBe("base");
+    expectSelectedIds("base");
+    unmountHarness(view);
+  });
+
+  it("keeps the original pointer owner when a second pointer presses", () => {
+    const view = renderHarness();
+    dragMarquee(view, { secondPointer: true, release: true });
+
+    expectSelectedIds("first", "offscreen");
+    unmountHarness(view);
+  });
+
+  it("commits a ruler click at its pointerdown position without requiring pointer movement", () => {
+    const view = renderHarness();
+
+    act(() => {
+      view.api.handlePointerDown(pointer(view.scroll, 7, 375, 5));
+      view.api.handlePointerUp(pointer(view.scroll, 7, 375, 5));
+    });
+
+    expect(view.seekFromX).toHaveBeenNthCalledWith(1, 375);
+    expect(view.seekFromX).toHaveBeenNthCalledWith(2, 375);
+    unmountHarness(view);
+  });
+
+  it("does not clear a finalized range when capture is lost after pointerup", () => {
+    const view = renderHarness();
+
+    act(() => {
+      view.api.handlePointerDown(pointer(view.scroll, 7, 100, 80, { shiftKey: true }));
+      view.api.handlePointerMove(pointer(view.scroll, 7, 300, 80, { shiftKey: true }));
+      view.api.handlePointerUp(pointer(view.scroll, 7, 300, 80, { shiftKey: true }));
+    });
+    const finalized = view.api.rangeSelection;
+    expect(finalized).toMatchObject({ start: 1, end: 3 });
+
+    act(() => view.api.handlePointerCancel(pointer(view.scroll, 7, 300, 80)));
+    expect(view.api.rangeSelection).toEqual(finalized);
+    unmountHarness(view);
+  });
+
+  it("cancels a live marquee when the project session changes", () => {
+    usePlayerStore.getState().setSelectedElementId("base");
+    const view = renderHarness(1);
+    dragMarquee(view);
+    usePlayerStore.getState().setSelectedElementId("base");
+    view.rerender(2);
+
+    expect(usePlayerStore.getState().selectedElementId).toBe("base");
+    expectSelectedIds("base");
+    unmountHarness(view);
+  });
+});