feat(studio): revamps Studio + improves code quality (#2291)

* feat(studio): glue API coexistence layer for the NLE swap What: extends 21 glue files so the OLD timeline/canvas engine and the NEW NLE components type-check side by side: playerStore (multi-select setters, zoom pin, snap toggle, non-reactive scale scratch), drag-state types gain optional NLE fields, timelineLayout/timelineAssetDrop/timelineEditingHelpers/ timelineEditing/timelineElementHelpers/studioHelpers/assetHelpers gain the NLE exports, DomEditOverlay + gestures + AssetContextMenu + Timeline props gain optional callbacks/params, contexts gain *Optional hooks, and TimelineEditCallbacks.onMoveElements becomes a bivariant method accepting both engines' change shapes. patchDocumentRootDuration's test rides along. Why: this is the keystone that dissolves the old "welded glue" problem — every symbol the NLE components need is ADDED next to what the old engine still uses, so the engine components and the swaps can land as separate reviewable PRs. How: 15 authored intermediate files (main content + additive symbols; no behavior changes — new fields optional, new callbacks unused until wired) plus 6 files whose final content is already purely additive. New exports without consumers yet carry TEMP(studio-dnd) ignoreExports entries, removed by the app-shell swap. Test plan: tsc --noEmit in studio + studio-server (verifies BOTH engines compile); bunx vitest run (full suite green incl. the 6 new patchDocumentRootDuration tests); fallow audit clean. * feat(studio): timeline interaction hooks and lanes component (unwired) What: the timeline-side wiring layer, unwired: TimelineLanes (the lane renderer driving drag/resize/marquee), timelineMarquee (+tests), useTimelineStackingSync, useTimelineGeometry, useTimelineEditPinning, useTimelineEditingDrops. Why: everything between the pure drag math and <Timeline> itself; the timeline-glue swap PR then only rewires Timeline/TimelineCanvas onto these. How: new files, tsc-clean against the coexistence layer. Unwired components carry TEMP(studio-dnd) entry registrations, removed at the app-shell swap. Test plan: bunx vitest run timelineMarquee.test.ts; tsc --noEmit; fallow audit clean. * feat(studio): NLE shell assembly (unwired) What: EditorShell (the full editor layout replacing NLELayout + StudioPreviewArea), TimelinePane (timeline host with sub-comp rebasing) and useTimelineEditCallbacks (the callback bag bridging store edits to the timeline), all unwired. Why: the shell that App swaps to in the final step; reviewing it standalone keeps that swap PR small. How: new files against the coexistence layer; TEMP(studio-dnd) entries until App mounts EditorShell in the app-shell swap. Test plan: tsc --noEmit; bunx vitest run (suite unchanged); fallow audit clean. * feat(studio): timeline glue swap — Timeline/TimelineCanvas onto the NLE engine What: flips the timeline glue to its final form (23 files): Timeline and TimelineCanvas rebuilt on TimelineLanes/TimelineOverlays, useTimelineClipDrag drives preview/commit through the new drag engine, range selection goes multi-select, playback loop moves to useTimelinePlayerLoop. Deletes the 9 old-engine files this orphans (group drag, marquee selection, snap targets, layer gutter, selection overlays + their suites) — each is compile- or gate-forced by this swap, verified by probe. Why: second swap step; timeline-only, canvas and App untouched. How: modified files to final content + forced deletions. playerStore/timelineEditing/timelineCallbacks stay at their coexistence form until the app swap (the old App still runs on them). Test plan: tsc --noEmit; bunx vitest run (full suite); fallow audit clean. * feat(studio): clip thumbnail modules What: ImageThumbnail (+tests) and thumbnailUtils (+tests) — frame decode with SVG/AVIF format fallbacks and rounded-corner clipping — plus VideoThumbnail updates. Why: the decode layer for timeline clip thumbnails, ahead of the visual refresh that renders them. How: new modules + one modified file; purely presentational. Test plan: bunx vitest run on both test files; tsc --noEmit; fallow audit clean. * feat(studio): assets/blocks panel behaviors + preview helpers What: blocks tab install flow, right-panel and global drag-overlay polish, music beat analysis and clip-content rendering hooks, and the preview-helper utilities backing asset preview. Why: completes the studio NLE stack on top of the visual refresh. How: modified files only (kept as one PR: splitting further would produce sub-150-LOC fragments of interdependent panel glue). Test plan: bunx vitest run studioPreviewHelpers/studioUrlState suites; tsc --noEmit; fallow audit clean. * fix(studio): restore timeline playback loop * fix(studio): restore missing GSAP helpers module * refactor(studio): split timeline GSAP helpers * style(studio): keep timeline helper under size limit * fix(studio): restore timeline overlays module * fix(studio): remove stale GSAP import * fix(studio): restore canonical timeline dependencies * style(studio): format restored timeline helpers * style(studio): satisfy helper line limit * fix(studio): repair rebuilt timeline integration * feat(studio): complete rebuilt NLE cutover * fix(studio): guard project and timeline race boundaries * fix(studio): preserve graded resize and crop geometry * fix(studio): log resize/rotate commit failures, move anchor accumulator to resize-local * fix(studio): treat duration-0 tweens as static holds and settle resize position before persist Instant holds (to()/fromTo() with duration 0) were classified as animated tweens by every commit route, so resizing or rotating them converted the hold into a corrupt duration-0 keyframes tween (new value at 0%, old at 100%) that GSAP drops; panel edits appended a losing set. A shared isInstantHold() now routes them through the static replace-in-place path, and percentage math guards zero-duration windows. Separately, anchored-corner resizes painted 3-5 frames at the new size but old position while the offset persist round-tripped the server. The commit path now applies the corrected GSAP position synchronously before awaiting the offset persist, mirroring the scale route's settle. * feat(studio): gesture-transaction seam with commit observability Introduce runGestureTransaction — one owner for a gesture commit's settle -> persist -> record lifecycle. It settles the live DOM synchronously before any async persist, folds every mutation into one undo entry via a per-transaction coalesceKey, restores pre-gesture state exactly once on failure, and asserts (dev console) + reports (PostHog: commit_transaction / commit_invariant_violation / commit_transaction_failed) that a persist never changes pixels. The box-size resize path is migrated onto it; the ad hoc per-route coalesceKey/reload handling is removed. Extract the resize draft-rect math into resizeDraft.ts to keep the gesture-handler file under the size cap. Also: keep url_hash telemetry to the route slug only (drop the query string, which carried the user's selected element id/selector), and gate the [hf-resize] diagnostics behind localStorage hf-resize-debug so they ship as opt-in tracing rather than console noise. * fix(studio): transaction owns the undo label The coalesced history entry took the last sub-mutation's label, so a resize surfaced as "Move layer" (the offset persist) in undo/redo. The seam now stamps tx.label on every wrapped mutation, so the folded entry reads as the gesture. * fix(studio): atomic static size/position commits (no data loss) Static resize/position holds updated an existing set via delete+add — two undo entries, and a delete that succeeded before a failed add lost the hold on disk. Use one in-place update-properties mutation when a set exists (one undo entry, no partial-failure window). The keyframed-hold heal that can't be expressed as a property update now adds before it deletes, so any single failure leaves a recoverable duplicate, never a lost hold. Transaction-owned commits are tracked via a WeakSet so the heal path never double-wraps an already-wrapped gesture. * fix(core): restore timed-clip visibility after a forced timeline rebind __hfForceTimelineRebind force-rendered the re-registered timeline but never re-ran the per-[data-start] visibility pass, so after undo or soft reload every clip rendered regardless of its time window until a full page reload. Extract the visibility loop into syncTimedElementVisibility and call it from both syncMediaForCurrentState (unchanged) and the rebind. * fix(studio): atomic z-order/keyframe/split commits, one undo entry each Three edit-commit paths hardened onto the one-transaction invariant: - Z-order reorder (useElementLifecycleOps): N per-element writes now fold into one undo entry (coalesceMs Infinity) and, on a failed persist, restore already-written files to disk so no partial reorder survives. - Enable-keyframes (useEnableKeyframes/useGsapKeyframeOps): the intermediate convert phase no longer full-reloads the preview (skipReload), killing the black-flash remount; convert + edit share one coalesce key = one undo entry. - Razor split-all (useRazorSplit): snapshot before the batch and restore on any failure, so a mid-batch error never leaves un-revertable partial splits. Shared file-history helpers (RecordEditInput, DomEditCommitBaseParams, readProjectFileContent, restoreFilesToOriginal) dedupe the rollback/commit logic across these paths. Commit options thread as one partial object rather than field-by-field. Test setup extracted into colocated helpers. * fix(studio): fold multi-step edits into one undo entry; guard text revert - Gesture recording (useGestureCommit): the per-property-group commits now share one coalesce key and only the last reloads, so a recording is one undo entry and one preview reload instead of up to four. - Delete selected keyframes (deleteSelectedKeyframes, split out of timelineEditingHelpers): N removals fold into one coalesced undo entry with a single reload. - Text-field commit (useDomEditTextCommits): commitDomTextFields now uses the same version-guarded revert as handleDomTextCommit, so a stale failed commit can no longer stomp a newer successful one. * feat(studio): batch a gesture's mutations into one atomic server write A transaction that emits N mutations previously did N sequential POSTs, each rewriting the file and soft-reloading — the root of the multi-phase persist window. Add a gsap-mutations-batch endpoint that validates every mutation up front, applies them in one in-memory rewrite chain, and writes the file once (all-or-nothing: an invalid entry rejects the whole batch, no partial write). The seam buffers a transaction's commits and, when more than one targets the same file, dispatches a single batch — one write, one history entry, one reload. The batch capability rides on the existing commit-function reference; no option fields are threaded through callers. * fix(studio): soften off-canvas indicator outline to 30% opacity The dashed off-canvas selection outline at 60% was noisy with many protruding elements on screen; drop the resting opacity to 30% (hover still restores full opacity so it stays discoverable). * fix(studio): drop off-canvas indicator outline to 10% opacity Follow-up to the 30% softening — 10% resting opacity reads much calmer with many protruding elements; hover still restores full opacity. * fix(studio): gate [hf-commit] console traces to dev only The start/settled/persisted/restore lifecycle traces logged on every gesture commit in all environments — console noise for end users. Route them through a dev-only traceCommit helper (matching the pixel-violation error's existing DEV gate). The commit_* PostHog events stay always on; they are the production observability, the console lines are a dev aid. * fix(studio): count actual reloads, not softReload requests, in commit telemetry A resize's size and offset persists both request softReload; the seam counted each request, so a batched gesture reported reload_count 2 even though the batch is one write and one reload. Compute the count from what dispatchBufferedCommits actually did — one for a batch, the request count for the sequential fallback. * fix(studio): rotate hover + off-canvas overlays with the element; flicker-free crop - Hover overlay applied the element's rotation only to the selection chrome, not the hover box; it now rotates about center like the selection, via a shared orientedGroupAwareOverlayRect router (one owner for rotation-aware overlay geometry across hover/selection/off-canvas). - Off-canvas indicator was axis-aligned; it now rotates with the element and inverse-rotates the canvas-exclusion clip into the element's local frame, so the protruding-sliver clip stays correct for rotated elements. - Crop commit re-lifted the element only in the commit's .then(), so one frame painted the cropped state (the flicker). Re-lift synchronously right after onStyleCommit (which applies the clip before its first await), so the cropped state never paints; the persisted file value is unchanged. * fix(studio): address code-review findings across the commit-hardening campaign Correctness (would ship green, bite under latency): - Enable-keyframes phase 2 now carries coalesceMs: Infinity, so the convert folds into one undo entry instead of splitting past the 300ms default. - The SDK keyframe persist path forwards coalesceMs (CutoverOptions gains the field); multi-keyframe delete and convert coalesce correctly when SDK-routed. - Razor split-all's rollback is guarded so a failing restore can't swallow the error toast that tells the user the split failed. Simplification (single source of truth / no dead flexibility): - Decompose resolveResizeDraftRect (drops a fallow-ignore suppression). - Delegate the third readProjectFileContent copy to the shared helper. - Inline setPatchFromUpdateProperties (its only caller passes one mutation). - One toSdkPersistOptions translates gesture overrides to SDK options. - Bundle the reorder-rollback deps into one object (was 7-9 positional args). - Dedupe the 'last group reloads' ternary; type gesture options as CommitMutationOptions; drop a Map+array wrapper around a single write. * feat(studio): atomic z-order reorder via batch patch-element endpoint Z-order reorder issued N per-element inline-style patches (one server write each), so a mid-chain failure could leave a partial reorder on disk. Add a patch-elements-batch endpoint that validates every patch, folds them over the file in one in-memory rewrite, and writes once (all-or-nothing; unsafe input rejects with no write). The reorder now sends one batch per source file and records one undo entry. Because a failed atomic write persists nothing, the interim disk-write-back rollback (restoreReorderedFile / restoreFulfilledReorderFiles / ReorderRollbackDeps) is deleted — failure rolls back only live DOM/store state. Closes the last disk-atomicity gap. * fix(studio): razor-split undo no longer silently no-ops The split clone was written to disk without a data-hf-id, so the split endpoint recorded that unstamped HTML as the undo entry's afterHash. The next reloadPreview() ran the preview route's ensureHfIds write-back, which minted a fresh id and persisted DIFFERENT bytes — so at undo time the disk hash no longer matched afterHash and editHistory's content-mismatch guard silently refused the undo (no write, no network, no error). Stamp the split output via ensureHfIds in splitElementInHtml before it is written/returned, so the preview write-back is a no-op and the recorded afterHash always equals the final on-disk bytes. Fixes at the source rather than relaxing the mismatch guard. Corrects the stale comment that credited forceReloadSdkSession. * feat(studio): closed-hand grab cursor on the rotate handle The rotate handle used the default arrow cursor; show a grabbing (closed-hand) cursor on hover to signal it's grabbed and dragged to rotate. * fix(studio): dropping a dragged element over another no longer selects it A moved drag's release fired the box click, which re-selected whatever now sat under the pointer via the hover cache — so dropping an element over a higher-z one selected the drop target instead of keeping the dragged element selected. The drag-move branch now suppresses the next box click, mirroring the resize branch. * fix(studio): group drag is one undo entry, not one per element Dragging a multi-selected group committed each member's position write as its own undo entry, so reverting took N Cmd+Z presses. Force a shared coalesceKey (infinite window) across every member's commit so they fold into a single undo entry, like the other multi-step commit paths. * fix(studio): undo of a split no longer leaves a ghost clip in the timeline The file and the composition iframe revert correctly on undo, but the timeline panel kept a ghost node for the split clone. The element-merge that repopulates the timeline preserves elements the fresh scan dropped — intended for enriched sub-composition children a bare DOM re-scan misses, but it also preserved a genuinely-removed TOP-LEVEL element (the split clone after undo), leaving a phantom clip. Restrict the preserve to elements with a compositionSrc (the enriched sub-comp children); a top-level element missing from the fresh scan was truly removed. --------- Co-authored-by: ukimsanov <ular.kimsanov@heygen.com>
2026-09-11 23:00:03 +00:00 · 2026-07-13 02:55:36 -04:00
parent 9940503102
commit df29fa7a5e
228 changed files with 18774 additions and 7332 deletions
@@ -1,8 +1,21 @@
-import { useRef, useState, useCallback } from "react";
-import { buildClipRangeSelection, type TimelineRangeSelection } from "./timelineEditing";
+import { useRef, useState, useCallback, useEffect } from "react";
+import {
+  buildClipRangeSelection,
+  applyTimelineAutoScrollStep,
+  resolveTimelineAutoScrollLoopAction,
+  type TimelineRangeSelection,
+} from "./timelineEditing";
 import type { TimelineElement } from "../store/playerStore";
-import { liveTime } from "../store/playerStore";
+import { liveTime, usePlayerStore } from "../store/playerStore";
 import { GUTTER } from "./timelineLayout";
+import {
+  computeMarqueeSelection,
+  getMarqueeRect,
+  isMarqueeDrag,
+  isTimelineRulerPress,
+  type MarqueeClipInput,
+} from "./timelineMarquee";
+import type { Rect } from "../../utils/marqueeGeometry";

 interface UseTimelineRangeSelectionInput {
  scrollRef: React.RefObject<HTMLDivElement | null>;
@@ -15,11 +28,69 @@ interface UseTimelineRangeSelectionInput {
  dragScrollRaf: React.RefObject<number>;
  isDragging: React.RefObject<boolean>;
  setShowPopover: (v: boolean) => void;
+  elementsRef: React.RefObject<TimelineElement[]>;
+  trackOrderRef: React.RefObject<number[]>;
+  onSelectElement?: (element: TimelineElement | null) => void;
+}
+
+interface MarqueeDragState {
+  originX: number;
+  originY: number;
+  /** Pre-drag selection, restored on Escape-cancel. */
+  baseIds: Set<string>;
+  basePrimary: string | null;
+  /** Union new hits with baseIds (shift/cmd/ctrl at pointerdown). */
+  additive: boolean;
+  /** True once the pointer travelled past the click threshold. */
+  active: boolean;
+}
+
+function snapshotSelection(): { ids: Set<string>; primary: string | null } {
+  const s = usePlayerStore.getState();
+  const ids = new Set(s.selectedElementIds);
+  if (s.selectedElementId) ids.add(s.selectedElementId);
+  return { ids, primary: s.selectedElementId };
+}
+
+function toMarqueeClips(elements: TimelineElement[]): MarqueeClipInput[] {
+  return elements.map((el) => ({
+    id: el.key ?? el.id,
+    start: el.start,
+    duration: el.duration,
+    track: el.track,
+  }));
+}
+
+/**
+ * Compute the live selection for a marquee rect and commit it to the store.
+ * Shift held mid-drag (or cmd/ctrl at pointerdown) unions the new hits with the
+ * pre-drag selection (marquee.baseIds / basePrimary).
+ */
+function commitMarqueeSelection(
+  rect: Rect,
+  additive: boolean,
+  marquee: MarqueeDragState,
+  elements: TimelineElement[],
+  trackOrder: number[],
+  pps: number,
+): void {
+  const { ids, primaryId } = computeMarqueeSelection({
+    clips: toMarqueeClips(elements),
+    trackOrder,
+    pps,
+    marquee: rect,
+    baseSelection: additive ? marquee.baseIds : undefined,
+  });
+  const store = usePlayerStore.getState();
+  // Primary FIRST: setSelectedElementId collapses the multi-select set, so the set
+  // must be written after it or the marquee selection would be wiped every frame.
+  store.setSelectedElementId(primaryId ?? (additive ? marquee.basePrimary : null));
+  store.setSelectedElementIds(ids);
 }

 export function useTimelineRangeSelection({
  scrollRef,
-  ppsRef: _ppsRef,
+  ppsRef,
  effectiveDuration: _effectiveDuration,
  pps,
  onSeek: _onSeek,
@@ -28,9 +99,15 @@ export function useTimelineRangeSelection({
  dragScrollRaf,
  isDragging,
  setShowPopover,
+  elementsRef,
+  trackOrderRef,
+  onSelectElement,
 }: UseTimelineRangeSelectionInput) {
  const isRangeSelecting = useRef(false);
  const rangeAnchorTime = useRef(0);
+  // Reactive mirror of the scrub gesture (isDragging is a ref, so it can't drive
+  // rendering). Drives the playhead head's filled-vs-hollow state.
+  const [isScrubbing, setIsScrubbing] = useState(false);
  const [rangeSelection, setRangeSelection] = useState<TimelineRangeSelection | null>(null);
  const shiftClickClipRef = useRef<{
    element: TimelineElement;
@@ -41,31 +118,190 @@ export function useTimelineRangeSelection({
  const seekRafRef = useRef(0);
  const pendingClientXRef = useRef(0);

+  // Marquee (rubber-band) multi-select on the empty timeline body.
+  const marqueeRef = useRef<MarqueeDragState | null>(null);
+  const [marqueeRect, setMarqueeRect] = useState<Rect | null>(null);
+  // Edge auto-scroll during a marquee drag: last pointer position (client-space)
+  // + shift flag, re-applied each RAF frame while the view scrolls under a
+  // stationary pointer, so the marquee can extend past the visible area.
+  const marqueePointerRef = useRef<{ clientX: number; clientY: number; shiftKey: boolean } | null>(
+    null,
+  );
+  const marqueeScrollRaf = useRef(0);
+
+  /** Pointer position → canvas/content coordinates (same space as clip rects). */
+  const toContentPoint = useCallback(
+    (clientX: number, clientY: number): { x: number; y: number } | null => {
+      const el = scrollRef.current;
+      if (!el) return null;
+      const rect = el.getBoundingClientRect();
+      return {
+        x: clientX - rect.left + el.scrollLeft,
+        y: clientY - rect.top + el.scrollTop,
+      };
+    },
+    [scrollRef],
+  );
+
+  // Recompute the marquee rect + live selection for a client-space pointer.
+  // Content-space (folds in scrollLeft/scrollTop), so re-running it after the
+  // view scrolls naturally extends the rect toward the newly revealed area.
+  // Shared by the pointermove handler and the edge auto-scroll stepper.
+  const applyMarqueeAtClient = useCallback(
+    (clientX: number, clientY: number, shiftKey: boolean) => {
+      const marquee = marqueeRef.current;
+      if (!marquee) return;
+      const point = toContentPoint(clientX, clientY);
+      if (!point) return;
+      if (!marquee.active && !isMarqueeDrag(marquee.originX, marquee.originY, point.x, point.y)) {
+        return;
+      }
+      marquee.active = true;
+      const rect = getMarqueeRect(marquee.originX, marquee.originY, point.x, point.y);
+      setMarqueeRect(rect);
+      // Live selection: every clip the box currently covers. Shift held
+      // mid-drag (or cmd/ctrl at pointerdown) adds to the prior selection.
+      const additive = marquee.additive || shiftKey;
+      commitMarqueeSelection(
+        rect,
+        additive,
+        marquee,
+        elementsRef.current ?? [],
+        trackOrderRef.current ?? [],
+        ppsRef.current,
+      );
+    },
+    [toContentPoint, elementsRef, trackOrderRef, ppsRef],
+  );
+
+  const stopMarqueeAutoScroll = useCallback(() => {
+    marqueePointerRef.current = null;
+    if (marqueeScrollRaf.current) {
+      cancelAnimationFrame(marqueeScrollRaf.current);
+      marqueeScrollRaf.current = 0;
+    }
+  }, []);
+
+  // Edge auto-scroll while marquee-dragging: mirrors stepClipDragAutoScroll —
+  // scroll the container toward the edge zone the pointer is in, then re-run the
+  // marquee at the (unchanged) client pointer so the rect + selection extend
+  // under the scroll delta. Self-perpetuating RAF until the pointer leaves the
+  // edge zones or the gesture ends.
+  const stepMarqueeAutoScroll = useCallback(() => {
+    marqueeScrollRaf.current = 0;
+    const marquee = marqueeRef.current;
+    const pointer = marqueePointerRef.current;
+    const scroll = scrollRef.current;
+    if (!marquee || !pointer || !scroll) return;
+    if (!applyTimelineAutoScrollStep(scroll, pointer.clientX, pointer.clientY)) return;
+
+    // Re-run at the SAME client point: toContentPoint folds in the new scroll, so
+    // the marquee's moving corner tracks the revealed content.
+    applyMarqueeAtClient(pointer.clientX, pointer.clientY, pointer.shiftKey);
+    marqueeScrollRaf.current = requestAnimationFrame(stepMarqueeAutoScroll);
+  }, [scrollRef, applyMarqueeAtClient]);
+
+  const syncMarqueeAutoScroll = useCallback(
+    (clientX: number, clientY: number, shiftKey: boolean) => {
+      marqueePointerRef.current = { clientX, clientY, shiftKey };
+      const action = resolveTimelineAutoScrollLoopAction(
+        scrollRef.current,
+        clientX,
+        clientY,
+        marqueeScrollRaf.current !== 0,
+      );
+      if (action === "stop") {
+        cancelAnimationFrame(marqueeScrollRaf.current);
+        marqueeScrollRaf.current = 0;
+      } else if (action === "start") {
+        marqueeScrollRaf.current = requestAnimationFrame(stepMarqueeAutoScroll);
+      }
+    },
+    [scrollRef, stepMarqueeAutoScroll],
+  );
+
+  // Shift-press → start a time-range selection anchored at the pressed x.
+  const beginRangeSelection = useCallback(
+    (e: React.PointerEvent) => {
+      (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+      isRangeSelecting.current = true;
+      setShowPopover(false);
+      const rect = scrollRef.current?.getBoundingClientRect();
+      if (rect) {
+        const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER;
+        const time = Math.max(0, x / pps);
+        rangeAnchorTime.current = time;
+        setRangeSelection({ start: time, end: time, anchorX: e.clientX, anchorY: e.clientY });
+      }
+    },
+    [scrollRef, pps, setShowPopover],
+  );
+
  const handlePointerDown = useCallback(
    (e: React.PointerEvent) => {
      if (e.button !== 0) return;
      if (e.shiftKey) {
-        (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
-        isRangeSelecting.current = true;
-        setShowPopover(false);
-        const rect = scrollRef.current?.getBoundingClientRect();
-        if (rect) {
-          const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER;
-          const time = Math.max(0, x / pps);
-          rangeAnchorTime.current = time;
-          setRangeSelection({ start: time, end: time, anchorX: e.clientX, anchorY: e.clientY });
-        }
+        beginRangeSelection(e);
        return;
      }
      shiftClickClipRef.current = null;
      if ((e.target as HTMLElement).closest("[data-clip]")) return;
      (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
-      isDragging.current = true;
      setRangeSelection(null);
      setShowPopover(false);
-      seekFromX(e.clientX);
+      const point = toContentPoint(e.clientX, e.clientY);
+      // Ruler press → scrub the playhead (the standard scrub surface). The
+      // ruler is sticky, so this decision uses VIEWPORT-space y — content-space
+      // y (which folds in scrollTop) breaks once the body is scrolled down and
+      // the stuck ruler visually overlays scrolled-away track rows.
+      const scrollRect = scrollRef.current?.getBoundingClientRect();
+      if (!point || !scrollRect || isTimelineRulerPress(e.clientY, scrollRect.top)) {
+        isDragging.current = true;
+        setIsScrubbing(true);
+        seekFromX(e.clientX);
+        return;
+      }
+      // Empty body press → pending marquee. A plain click (no drag past the
+      // threshold) deselects on pointerup; a drag draws the marquee. Never scrubs.
+      const base = snapshotSelection();
+      marqueeRef.current = {
+        originX: point.x,
+        originY: point.y,
+        baseIds: base.ids,
+        basePrimary: base.primary,
+        additive: e.metaKey || e.ctrlKey,
+        active: false,
+      };
    },
-    [seekFromX, pps, scrollRef, isDragging, setShowPopover],
+    [beginRangeSelection, seekFromX, scrollRef, isDragging, setShowPopover, toContentPoint],
+  );
+
+  // Scrub-drag update: live playhead feedback (liveTime) + RAF-throttled seek.
+  const updateScrubDrag = useCallback(
+    (clientX: number) => {
+      pendingClientXRef.current = clientX;
+      // Update the playhead visual immediately via liveTime for smooth feedback,
+      // then RAF-throttle the full seek (adapter + React state sync).
+      const el = scrollRef.current;
+      if (el) {
+        const rect = el.getBoundingClientRect();
+        const x = clientX - rect.left + el.scrollLeft - GUTTER;
+        if (x >= 0) {
+          const dur = el.scrollWidth / pps;
+          liveTime.notify(Math.max(0, Math.min(dur, x / pps)));
+        }
+      }
+      if (!seekRafRef.current) {
+        seekRafRef.current = requestAnimationFrame(() => {
+          seekRafRef.current = 0;
+          if (isDragging.current) {
+            seekFromX(pendingClientXRef.current);
+            autoScrollDuringDrag(pendingClientXRef.current);
+          }
+        });
+      }
+    },
+    [scrollRef, pps, seekFromX, autoScrollDuringDrag, isDragging],
  );

  const handlePointerMove = useCallback(
@@ -82,63 +318,118 @@ export function useTimelineRangeSelection({
        }
        return;
      }
+      const marquee = marqueeRef.current;
+      if (marquee) {
+        applyMarqueeAtClient(e.clientX, e.clientY, e.shiftKey);
+        // Edge auto-scroll: once the drag is live, scroll when the pointer nears
+        // a viewport edge so the marquee can extend past the visible area.
+        if (marquee.active) syncMarqueeAutoScroll(e.clientX, e.clientY, e.shiftKey);
+        return;
+      }
      if (!isDragging.current) return;
-      pendingClientXRef.current = e.clientX;
-      // Update the playhead visual immediately via liveTime for smooth feedback,
-      // then RAF-throttle the full seek (adapter + React state sync).
-      const el = scrollRef.current;
-      if (el) {
-        const rect = el.getBoundingClientRect();
-        const x = e.clientX - rect.left + el.scrollLeft - GUTTER;
-        if (x >= 0) {
-          const dur = el.scrollWidth / pps;
-          liveTime.notify(Math.max(0, Math.min(dur, x / pps)));
-        }
-      }
-      if (!seekRafRef.current) {
-        seekRafRef.current = requestAnimationFrame(() => {
-          seekRafRef.current = 0;
-          if (isDragging.current) {
-            seekFromX(pendingClientXRef.current);
-            autoScrollDuringDrag(pendingClientXRef.current);
-          }
-        });
-      }
+      updateScrubDrag(e.clientX);
    },
-    [seekFromX, autoScrollDuringDrag, pps, scrollRef, isDragging],
+    [pps, scrollRef, isDragging, applyMarqueeAtClient, syncMarqueeAutoScroll, updateScrubDrag],
+  );
+
+  // Release of a shift time-range gesture: keep a real range (or a shift-click
+  // clip range), otherwise clear it.
+  const finishRangeSelection = useCallback(() => {
+    isRangeSelecting.current = false;
+    const pendingShiftClick = shiftClickClipRef.current;
+    shiftClickClipRef.current = null;
+    setRangeSelection((prev) => {
+      if (prev && pendingShiftClick && Math.abs(prev.end - prev.start) <= 0.2) {
+        setShowPopover(true);
+        return buildClipRangeSelection(pendingShiftClick.element, pendingShiftClick);
+      }
+      if (prev && Math.abs(prev.end - prev.start) > 0.2) {
+        setShowPopover(true);
+        return prev;
+      }
+      return null;
+    });
+  }, [setShowPopover]);
+
+  // Release of a marquee gesture: plain click deselects; a real drag keeps the
+  // live selection and notifies the primary element.
+  const finishMarquee = useCallback(
+    (marquee: MarqueeDragState) => {
+      marqueeRef.current = null;
+      stopMarqueeAutoScroll();
+      setMarqueeRect(null);
+      const store = usePlayerStore.getState();
+      if (!marquee.active) {
+        // Plain click on empty body (click-away): deselect everything.
+        store.setSelectedElementId(null);
+        store.clearSelectedElementIds();
+        onSelectElement?.(null);
+        return;
+      }
+      const primaryKey = store.selectedElementId;
+      const primary =
+        (elementsRef.current ?? []).find((el) => (el.key ?? el.id) === primaryKey) ?? null;
+      onSelectElement?.(primary);
+    },
+    [stopMarqueeAutoScroll, elementsRef, onSelectElement],
  );

  const handlePointerUp = useCallback(() => {
    if (isRangeSelecting.current) {
-      isRangeSelecting.current = false;
-      const pendingShiftClick = shiftClickClipRef.current;
-      shiftClickClipRef.current = null;
-      setRangeSelection((prev) => {
-        if (prev && pendingShiftClick && Math.abs(prev.end - prev.start) <= 0.2) {
-          setShowPopover(true);
-          return buildClipRangeSelection(pendingShiftClick.element, pendingShiftClick);
-        }
-        if (prev && Math.abs(prev.end - prev.start) > 0.2) {
-          setShowPopover(true);
-          return prev;
-        }
-        return null;
-      });
+      finishRangeSelection();
      return;
    }
+    const marquee = marqueeRef.current;
+    if (marquee) {
+      finishMarquee(marquee);
+      return;
+    }
+    if (!isDragging.current) return;
    if (seekRafRef.current) {
      cancelAnimationFrame(seekRafRef.current);
      seekRafRef.current = 0;
    }
    seekFromX(pendingClientXRef.current);
    isDragging.current = false;
+    setIsScrubbing(false);
    cancelAnimationFrame(dragScrollRaf.current);
-  }, [isDragging, dragScrollRaf, setShowPopover, seekFromX]);
+  }, [isDragging, dragScrollRaf, seekFromX, finishRangeSelection, finishMarquee]);
+
+  // Escape: cancel an in-flight marquee (restores the pre-drag selection);
+  // otherwise clear any lingering multi-selection.
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      const store = usePlayerStore.getState();
+      const marquee = marqueeRef.current;
+      if (marquee) {
+        marqueeRef.current = null;
+        stopMarqueeAutoScroll();
+        setMarqueeRect(null);
+        if (marquee.active) {
+          // Primary FIRST (see commitMarqueeSelection): it collapses the set, so
+          // restore the pre-drag primary before repopulating the base ids.
+          store.setSelectedElementId(marquee.basePrimary);
+          store.setSelectedElementIds(marquee.baseIds);
+        }
+        return;
+      }
+      // Escape with no marquee clears the whole selection — primary AND set.
+      // setSelectedElementId(null) also collapses the multi-select set.
+      if (store.selectedElementId || store.selectedElementIds.size > 0) {
+        store.setSelectedElementId(null);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [stopMarqueeAutoScroll]);

  return {
    rangeSelection,
    setRangeSelection,
    shiftClickClipRef,
+    marqueeRect,
+    isScrubbing,
    handlePointerDown,
    handlePointerMove,
    handlePointerUp,