From 8210925f85470b3f09cb454b9586c3577832e237 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 04:25:36 -0400
Subject: [PATCH 01/26] perf(studio): coalesce timeline zoom to one write per
 frame and zoom to a range

---
 .../src/components/TimelineToolbar.test.tsx   |  14 +-
 .../studio/src/components/TimelineToolbar.tsx |  23 +--
 packages/studio/src/index.ts                  |   1 +
 .../src/player/components/AudioWaveform.tsx   |  93 +++++++---
 .../player/components/TimelineClipFades.tsx   |   7 +-
 .../src/player/components/VideoThumbnail.tsx  |   8 +-
 .../src/player/components/timelineMotion.ts   |  46 +++++
 .../player/components/timelineShellMeta.tsx   |   2 +
 .../components/timelineZoomInput.test.ts      | 139 +++++++++++++++
 .../player/components/timelineZoomInput.ts    | 160 ++++++++++++++++++
 .../player/components/useTimelineGeometry.ts  |   3 -
 .../components/useTimelinePlayhead.test.tsx   |  89 +++++++---
 .../player/components/useTimelinePlayhead.ts  |  87 ++++------
 .../components/useTimelineProviderState.tsx   |  37 ++--
 .../src/player/components/useTimelineZoom.ts  |  12 +-
 15 files changed, 562 insertions(+), 159 deletions(-)
 create mode 100644 packages/studio/src/player/components/timelineMotion.ts
 create mode 100644 packages/studio/src/player/components/timelineZoomInput.test.ts
 create mode 100644 packages/studio/src/player/components/timelineZoomInput.ts

diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index a120f34acec..3b85e4382d2 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -2,7 +2,7 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { makeSelection } from "../hooks/domSelectionTestHarness";
@@ -239,6 +239,16 @@ describe("TimelineToolbar snap key", () => {
 });
 
 describe("TimelineToolbar Fit", () => {
+  // A zoom lands on the next frame; these tests step frames instead of waiting for them.
+  beforeEach(() => {
+    vi.useFakeTimers({
+      toFake: ["requestAnimationFrame", "cancelAnimationFrame", "setTimeout", "clearTimeout"],
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   it("shows Fit as a named icon and says whether fit is on", () => {
     const { host, root } = renderToolbar();
     const fit = () => host.querySelector('button[aria-label="Fit timeline to width"]');
@@ -251,6 +261,7 @@ describe("TimelineToolbar Fit", () => {
         .querySelector('button[aria-label="Zoom in"]')
         ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
     );
+    act(() => vi.advanceTimersToNextFrame());
     expect(fit()?.getAttribute("aria-pressed")).toBe("false");
     act(() => root.unmount());
   });
@@ -263,6 +274,7 @@ describe("TimelineToolbar Fit", () => {
         .querySelector('button[aria-label="Zoom in"]')
         ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
     );
+    act(() => vi.advanceTimersToNextFrame());
     expect(usePlayerStore.getState().userZoomCount).toBe(before + 1);
     act(() => root.unmount());
   });
diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index f4d0a18d1de..8906a9175e7 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -14,12 +14,12 @@ import {
 import { computeElementPercentage, playsNear } from "../hooks/gsapShared";
 import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
 import {
-  getNextTimelineZoomPercent,
   getTimelineZoomPercent,
   timelineZoomPercentToSlider,
   timelineSliderToZoomPercent,
 } from "../player/components/timelineZoom";
 import { useTimelineZoom } from "../player/components/useTimelineZoom";
+import { zoomTimelineStep } from "../player/components/timelineZoomInput";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { Tooltip } from "./ui";
 import { AudioMetersIcon } from "./icons/AudioMetersIcon";
@@ -510,12 +510,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
             <button
               type="button"
               aria-label="Zoom out"
-              onClick={() => {
-                setZoomMode("manual");
-                setManualZoomPercent(
-                  getNextTimelineZoomPercent("out", zoomMode, manualZoomPercent, timelineFitPps),
-                );
-              }}
+              onClick={() => zoomTimelineStep("out")}
               className={flatIdle}
             >
               <MagnifyingGlassMinus size={16} aria-hidden="true" />
@@ -528,12 +523,11 @@ export const TimelineToolbar = memo(function TimelineToolbar({
             value={timelineZoomPercentToSlider(displayedTimelineZoomPercent, timelineFitPps)}
             title={`${displayedTimelineZoomPercent}%`}
             aria-label="Timeline zoom"
-            onChange={(e) => {
-              setZoomMode("manual");
+            onChange={(e) =>
               setManualZoomPercent(
                 timelineSliderToZoomPercent(Number(e.target.value), timelineFitPps),
-              );
-            }}
+              )
+            }
             // h-6 on the input is the 24x24 WCAG 2.2 (2.5.8) target: the visible
             // track stays 2px and the thumb 10px, only the pointer box grows.
             className="mx-1 h-6 w-[96px] cursor-pointer appearance-none bg-transparent [&::-webkit-slider-runnable-track]:h-[2px] [&::-webkit-slider-runnable-track]:rounded-full [&::-webkit-slider-runnable-track]:bg-neutral-700 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-[10px] [&::-webkit-slider-thumb]:h-[10px] [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-text-0 [&::-webkit-slider-thumb]:-mt-1 [&::-webkit-slider-thumb]:shadow-[0_0_0_2px_#0a0a0a,0_1px_3px_rgba(0,0,0,0.5)] [&::-webkit-slider-thumb]:cursor-grab [&::-webkit-slider-thumb:active]:cursor-grabbing"
@@ -542,12 +536,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
             <button
               type="button"
               aria-label="Zoom in"
-              onClick={() => {
-                setZoomMode("manual");
-                setManualZoomPercent(
-                  getNextTimelineZoomPercent("in", zoomMode, manualZoomPercent, timelineFitPps),
-                );
-              }}
+              onClick={() => zoomTimelineStep("in")}
               className={flatIdle}
             >
               <MagnifyingGlassPlus size={16} aria-hidden="true" />
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 1c1696b7102..3b4262d4c1e 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -63,6 +63,7 @@ export {
 export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
 export type { TimelineTheme } from "./player/components/timelineTheme";
 export { TRACK_H } from "./player/components/timelineLayout";
+export { zoomTimelineToRange } from "./player/components/timelineZoomInput";
 export type { TimelineTrackPadding } from "./player/components/timelineLayout";
 export { displayTrackOrder } from "./player/components/useTimelineTrackDerivations";
 export { fadeHandleBoxes } from "./player/components/timelineClipFadeGeometry";
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 043f381be25..71706034b55 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -5,6 +5,7 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
+import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface AudioWaveformProps {
@@ -30,6 +31,25 @@ export const WAVEFORM_LAYER_Z = 10;
 
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
+/** A stretch of the clip as fractions of its width. */
+export type ClipSpan = { from: number; to: number };
+const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
+// Drawn past the viewport by this many widths each side, so a short scroll shows bars already drawn.
+const OVERSCAN_VIEWPORTS = 1;
+
+/** The part of the clip on screen, with overscan; a long clip never draws past it. */
+function visibleClipSpan(root: HTMLElement): ClipSpan {
+  const box = root.getBoundingClientRect();
+  if (box.width <= 0) return WHOLE_CLIP;
+  const scroller = root.closest("[data-timeline-scroll-viewport]");
+  const view = scroller?.getBoundingClientRect() ?? { left: 0, right: window.innerWidth };
+  const margin = (view.right - view.left) * OVERSCAN_VIEWPORTS;
+  const clamp = (x: number) => Math.max(0, Math.min(1, x));
+  const from = clamp((view.left - margin - box.left) / box.width);
+  const to = clamp((view.right + margin - box.left) / box.width);
+  return { from, to: Math.max(from, to) };
+}
+
 function paintWaveformBars(
   context: CanvasRenderingContext2D,
   bars: readonly BarGeometry[],
@@ -61,6 +81,7 @@ export function drawWaveformCanvas(
   trimStartFraction: number,
   trimEndFraction: number,
   fades: ClipFadeShape | null = null,
+  span: ClipSpan = WHOLE_CLIP,
 ) {
   const width = Math.max(1, canvas.clientWidth);
   const height = Math.max(1, canvas.clientHeight);
@@ -71,19 +92,20 @@ export function drawWaveformCanvas(
   if (!context) return;
   context.scale(scale, scale);
   context.clearRect(0, 0, width, height);
+  const trim = trimEndFraction - trimStartFraction;
   const amplitudes = decimatePeaks(
     peaks,
-    trimStartFraction,
-    trimEndFraction,
+    trimStartFraction + trim * span.from,
+    trimStartFraction + trim * span.to,
     Math.max(1, Math.ceil(width / BAR_STEP)),
   );
+  const clipFraction = (index: number) =>
+    span.from + ((index + 0.5) / amplitudes.length) * (span.to - span.from);
   const bars = amplitudes.map((amplitude, index) => ({
     x: (index * width) / amplitudes.length,
     width: Math.max(1, width / amplitudes.length),
     height: Math.max(3, amplitude * height),
-    gain: fades
-      ? fadeGain(((index + 0.5) / amplitudes.length) * fades.duration, fades.duration, fades)
-      : 1,
+    gain: fades ? fadeGain(clipFraction(index) * fades.duration, fades.duration, fades) : 1,
   }));
   const channelToken = muted ? "--timeline-waveform-muted-rgb" : "--timeline-waveform-bar-rgb";
   const waveformBarRgb = getComputedStyle(canvas).getPropertyValue(channelToken);
@@ -172,7 +194,6 @@ export const AudioWaveform = memo(function AudioWaveform({
 }: AudioWaveformProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const observerRef = useRef<ResizeObserver | null>(null);
   const cacheKey = waveformUrl ?? audioUrl;
   const request = useMemo(
     () => ({
@@ -199,21 +220,42 @@ export const AudioWaveform = memo(function AudioWaveform({
   const fades = useContext(ClipFadesContext);
   const draw = useCallback(() => {
     const canvas = canvasRef.current;
-    if (!canvas || !peaks) return;
-    drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1, fades);
+    const root = rootRef.current;
+    if (!canvas || !root || !peaks) return;
+    const span = visibleClipSpan(root);
+    // Placed in fractions of the clip, so a zoom stretches the drawn bars with time until the redraw.
+    canvas.style.left = `${span.from * 100}%`;
+    canvas.style.width = `${(span.to - span.from) * 100}%`;
+    if (span.to <= span.from) return;
+    drawWaveformCanvas(
+      canvas,
+      peaks,
+      muted,
+      trimStartFraction ?? 0,
+      trimEndFraction ?? 1,
+      fades,
+      span,
+    );
   }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
+  const drawRef = useRef(draw);
+  drawRef.current = draw;
+  useEffect(draw, [draw]);
 
-  const setCanvasRef = useCallback(
-    (canvas: HTMLCanvasElement | null) => {
-      observerRef.current?.disconnect();
-      canvasRef.current = canvas;
-      if (!canvas) return;
-      draw();
-      observerRef.current = new ResizeObserver(draw);
-      observerRef.current.observe(canvas);
-    },
-    [draw],
-  );
+  // Redrawn when the clip resizes or the timeline comes to rest after a zoom or scroll, never
+  // per step: a step only stretches what is drawn.
+  useMountEffect(() => {
+    const root = rootRef.current;
+    const redrawAtRest = () => {
+      if (!isTimelineMoving()) drawRef.current();
+    };
+    const observer = root ? new ResizeObserver(redrawAtRest) : null;
+    if (root) observer?.observe(root);
+    const unsubscribe = subscribeTimelineMotion(redrawAtRest);
+    return () => {
+      observer?.disconnect();
+      unsubscribe();
+    };
+  });
 
   useEffect(() => {
     const root = document.documentElement;
@@ -225,8 +267,6 @@ export const AudioWaveform = memo(function AudioWaveform({
     return () => observer.disconnect();
   }, [draw]);
 
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
   useEffect(() => {
     const clip = rootRef.current?.closest(".timeline-clip");
     if (!(clip instanceof HTMLElement)) return;
@@ -239,9 +279,14 @@ export const AudioWaveform = memo(function AudioWaveform({
     <div ref={rootRef} className="absolute inset-0">
       <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
         <canvas
-          ref={setCanvasRef}
-          className="absolute inset-x-0 bottom-0 w-full"
-          style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
+          ref={canvasRef}
+          className="absolute bottom-0"
+          style={{
+            left: 0,
+            width: "100%",
+            top: labelInset,
+            height: `calc(100% - ${labelInset}px)`,
+          }}
         />
         {snapshot.status === "loading" && (
           <div
diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsx
index 2d35771eec2..5a05f0dbea9 100644
--- a/packages/studio/src/player/components/TimelineClipFades.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.tsx
@@ -139,10 +139,12 @@ export function TimelineClipFades({
     radius: 0,
     toolsLeft: null,
   });
+  const handlesVisible = showHandles || dragging !== null || focused !== null;
+  // Measured only while the handles show: a zoom step must not force a layout per clip.
   useLayoutEffect(() => {
     const root = rootRef.current;
     const clip = root?.parentElement;
-    if (!root || !clip) return;
+    if (!handlesVisible || !root || !clip) return;
     const radius = parseFloat(getComputedStyle(clip).borderTopLeftRadius) || 0;
     const { clientHeight: height, clientWidth: width } = root;
     const fx = clip.querySelector('[data-badge="fx"]');
@@ -157,7 +159,7 @@ export function TimelineClipFades({
         ? box
         : { height, width, radius, toolsLeft },
     );
-  }, [widthPx, visible]);
+  }, [widthPx, handlesVisible]);
 
   const gesture = useRef<{
     edge: FadeEdge;
@@ -342,7 +344,6 @@ export function TimelineClipFades({
 
   const showIn = fades.fadeIn > 0;
   const showOut = fades.fadeOut > 0;
-  const handlesVisible = showHandles || dragging !== null || focused !== null;
   if (!visible) return null;
 
   // A handle with no 0.01 s step to move is not drawn, unless in use: its twin owns the spot.
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 9d42c11421b..188876bc597 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -9,6 +9,7 @@ import {
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
+import { useValueAtRest } from "./timelineMotion";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -87,8 +88,11 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   priority = "visible",
 }: VideoThumbnailProps) {
   const [container, setContainerRef, watchGap] = useThumbnailStripSize();
-  const requestFrameCount = quantizeThumbnailFrameCount(
-    computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+  // A zoom changes the width every step; decode the strip it settles on, not each step's.
+  const requestFrameCount = useValueAtRest(
+    quantizeThumbnailFrameCount(
+      computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+    ),
   );
   const requestProps = useMemo(
     () => ({
diff --git a/packages/studio/src/player/components/timelineMotion.ts b/packages/studio/src/player/components/timelineMotion.ts
new file mode 100644
index 00000000000..2380f08340e
--- /dev/null
+++ b/packages/studio/src/player/components/timelineMotion.ts
@@ -0,0 +1,46 @@
+import { useState, useSyncExternalStore } from "react";
+
+/** How long the timeline must hold still, after its last zoom or scroll, to count as at rest. */
+const TIMELINE_REST_MS = 150;
+
+let moving = false;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+const listeners = new Set<() => void>();
+
+const emit = () => listeners.forEach((listener) => listener());
+
+/** A zoom or scroll step: work that only matters at rest (redraws, decodes) waits for it to end. */
+export function markTimelineMotion(): void {
+  if (!moving) {
+    moving = true;
+    emit();
+  }
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = setTimeout(() => {
+    restTimer = null;
+    moving = false;
+    emit();
+  }, TIMELINE_REST_MS);
+}
+
+export function isTimelineMoving(): boolean {
+  return moving;
+}
+
+export function subscribeTimelineMotion(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** True while the timeline zooms or scrolls; re-renders only when that starts and when it rests. */
+function useTimelineMoving(): boolean {
+  return useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
+}
+
+/** `value` at rest; while the timeline moves, the value it had when it last rested. */
+export function useValueAtRest<T>(value: T): T {
+  const moving = useTimelineMoving();
+  const [held, setHeld] = useState(value);
+  if (!moving && !Object.is(held, value)) setHeld(value);
+  return moving ? held : value;
+}
diff --git a/packages/studio/src/player/components/timelineShellMeta.tsx b/packages/studio/src/player/components/timelineShellMeta.tsx
index fb8a6677ec7..0b04e676953 100644
--- a/packages/studio/src/player/components/timelineShellMeta.tsx
+++ b/packages/studio/src/player/components/timelineShellMeta.tsx
@@ -10,6 +10,7 @@ import {
 } from "./timelineProviderStateBuilders";
 import { TimelineRazorGuideOverlay } from "./TimelineRazorInteraction";
 import { LABEL_COL_W } from "./timelineLayout";
+import { markTimelineMotion } from "./timelineMotion";
 import type { TimelineTheme } from "./timelineTheme";
 
 type ViewportHandlers = Pick<
@@ -73,6 +74,7 @@ export function buildTimelineShellMeta(input: TimelineShellMetaInputs): Timeline
       contentOrigin: input.contentOrigin,
       zoomMode: input.zoomMode,
       onScroll: (e) => {
+        markTimelineMotion();
         input.lastScrollLeftRef.current = e.currentTarget.scrollLeft;
         input.recordTimelineScroll(e.currentTarget);
         input.syncScrollViewport(e.currentTarget, true);
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
new file mode 100644
index 00000000000..dd1fc3fb77f
--- /dev/null
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -0,0 +1,139 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  requestTimelineZoom,
+  setTimelineZoomViewport,
+  takeTimelineZoomAnchor,
+  zoomTimelineStep,
+  zoomTimelineToRange,
+} from "./timelineZoomInput";
+
+beforeEach(() => {
+  vi.useFakeTimers({
+    toFake: [
+      "requestAnimationFrame",
+      "cancelAnimationFrame",
+      "setTimeout",
+      "clearTimeout",
+      "performance",
+    ],
+  });
+  usePlayerStore.setState({
+    zoomMode: "fit",
+    manualZoomPercent: 100,
+    timelineFitPps: 10,
+    timelinePps: 10,
+    userZoomCount: 0,
+  });
+});
+afterEach(() => {
+  setTimelineZoomViewport(null);
+  takeTimelineZoomAnchor();
+  vi.useRealTimers();
+});
+
+describe("requestTimelineZoom", () => {
+  it("writes the store once per frame with the last zoom asked for", () => {
+    const writes = vi.fn();
+    const unsubscribe = usePlayerStore.subscribe(writes);
+    requestTimelineZoom(150);
+    requestTimelineZoom(200, { time: 4, x: 100 });
+    requestTimelineZoom(300, { time: 5, x: 120 });
+    expect(writes).not.toHaveBeenCalled();
+    vi.advanceTimersToNextFrame();
+    unsubscribe();
+    expect(writes).toHaveBeenCalledTimes(1);
+    expect(usePlayerStore.getState()).toMatchObject({
+      zoomMode: "manual",
+      manualZoomPercent: 300,
+      timelinePps: 30,
+      userZoomCount: 1,
+    });
+    expect(takeTimelineZoomAnchor()).toEqual({ time: 5, x: 120 });
+    expect(takeTimelineZoomAnchor()).toBeNull();
+  });
+});
+
+describe("zoomTimelineToRange", () => {
+  function viewport(clientWidth: number, scrollLeft = 0) {
+    const scroll = document.createElement("div");
+    Object.defineProperties(scroll, {
+      clientWidth: { value: clientWidth },
+      scrollLeft: { value: scrollLeft, writable: true },
+    });
+    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+  }
+
+  it("fills the width with the range and puts its start at the left margin", () => {
+    viewport(1080);
+    zoomTimelineToRange(100, 150, { smooth: false });
+    vi.advanceTimersToNextFrame();
+    // 1080 - (32 + 24) - 24 = 1000px for 50s is 20 pps.
+    expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
+    expect(takeTimelineZoomAnchor()).toEqual({ time: 100, x: 56 });
+  });
+
+  it("eases there over several frames and ends exactly on the range", () => {
+    viewport(1080);
+    zoomTimelineToRange(10, 20);
+    vi.advanceTimersToNextFrame();
+    vi.advanceTimersToNextFrame();
+    const midway = usePlayerStore.getState().timelinePps;
+    expect(midway).toBeGreaterThan(10);
+    expect(midway).toBeLessThan(100);
+    for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
+    const anchor = takeTimelineZoomAnchor();
+    // The range's start lands at the left margin, 32 + 24 px in.
+    expect(anchor && anchor.x + (10 - anchor.time) * 100).toBeCloseTo(56);
+  });
+
+  it("stops easing when a person zooms during it", () => {
+    viewport(1080);
+    zoomTimelineToRange(10, 20);
+    vi.advanceTimersToNextFrame();
+    vi.advanceTimersToNextFrame();
+    requestTimelineZoom(150);
+    for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().manualZoomPercent).toBe(150);
+  });
+});
+
+describe("zoomTimelineStep", () => {
+  function viewport(scrollLeft: number) {
+    const scroll = document.createElement("div");
+    Object.defineProperties(scroll, {
+      clientWidth: { value: 1080 },
+      scrollLeft: { value: scrollLeft, writable: true },
+    });
+    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+  }
+  const run = () => {
+    for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+  };
+  const screenX = (time: number) => {
+    const anchor = takeTimelineZoomAnchor();
+    return anchor && anchor.x + (time - anchor.time) * usePlayerStore.getState().timelinePps;
+  };
+
+  it("doubles the scale and keeps an on-screen playhead where it is", () => {
+    usePlayerStore.setState({ currentTime: 40 });
+    viewport(0);
+    // At 10 pps the playhead sits at 32 + 400 = 432px.
+    zoomTimelineStep("in");
+    run();
+    expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
+    expect(screenX(40)).toBeCloseTo(432);
+  });
+
+  it("centres an off-screen playhead", () => {
+    usePlayerStore.setState({ currentTime: 300 });
+    viewport(0);
+    zoomTimelineStep("in");
+    run();
+    // The range's middle, 56 + 1000 / 2, is the playhead.
+    expect(screenX(300)).toBeCloseTo(556);
+  });
+});
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
new file mode 100644
index 00000000000..a54d5a5a99e
--- /dev/null
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -0,0 +1,160 @@
+import { usePlayerStore } from "../store/playerStore";
+import { markTimelineMotion } from "./timelineMotion";
+import {
+  clampTimelineZoomPercent,
+  getNextTimelineZoomPercent,
+  getTimelineZoomPercent,
+} from "./timelineZoom";
+
+/** Where a zoom holds its place: `time` stays `x` px from the viewport's left edge. */
+export interface TimelineZoomAnchor {
+  time: number;
+  x: number;
+}
+
+/** The mounted timeline's scroll viewport, which zoom-to-range measures against. */
+export interface TimelineZoomViewport {
+  scroll: HTMLDivElement;
+  contentOrigin: number;
+}
+
+const RANGE_MARGIN_PX = 24;
+const SMOOTH_ZOOM_MS = 220;
+
+let pending: { percent: number; anchor: TimelineZoomAnchor | null } | null = null;
+let frame = 0;
+let anchorForCommit: TimelineZoomAnchor | null = null;
+let viewport: TimelineZoomViewport | null = null;
+let animation = 0;
+let easingTo: number | null = null;
+
+/** The percent the timeline is showing, or will show next frame. */
+export function currentTimelineZoomPercent(): number {
+  if (pending) return pending.percent;
+  const s = usePlayerStore.getState();
+  return getTimelineZoomPercent(s.zoomMode, s.manualZoomPercent, s.timelineFitPps);
+}
+
+function flush() {
+  frame = 0;
+  const next = pending;
+  pending = null;
+  if (!next) return;
+  anchorForCommit = next.anchor;
+  // One store write per frame: percent, mode and the published scale together, so every reader
+  // of the scale renders once with the clips instead of once more after them.
+  usePlayerStore.setState((s) => {
+    const percent = clampTimelineZoomPercent(next.percent, s.timelineFitPps);
+    return {
+      zoomMode: "manual",
+      manualZoomPercent: percent,
+      userZoomCount: s.userZoomCount + 1,
+      timelinePps: (s.timelineFitPps * percent) / 100,
+    };
+  });
+}
+
+function request(percent: number, anchor: TimelineZoomAnchor | null) {
+  pending = { percent, anchor };
+  markTimelineMotion();
+  if (!frame) frame = requestAnimationFrame(flush);
+}
+
+/** Every zoom input's one door: requests in the same frame collapse to the last, drawn once. */
+export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
+  stopEase();
+  request(percent, anchor);
+}
+
+function stopEase() {
+  cancelAnimationFrame(animation);
+  animation = 0;
+  easingTo = null;
+}
+
+/** The anchor of the zoom being committed; read once by the timeline as it lays the zoom out. */
+export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
+  const anchor = anchorForCommit;
+  anchorForCommit = null;
+  return anchor;
+}
+
+export function setTimelineZoomViewport(next: TimelineZoomViewport | null): void {
+  viewport = next;
+}
+
+const reducedMotion = () =>
+  typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/**
+ * Zooms and scrolls so `start`..`end` fills the timeline's width, easing there unless
+ * `smooth` is false or the person prefers reduced motion.
+ */
+export function zoomTimelineToRange(
+  start: number,
+  end: number,
+  options: { smooth?: boolean } = {},
+): void {
+  const view = viewport;
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  if (!view || !(end > start) || !(fitPps > 0)) return;
+  const x = view.contentOrigin + RANGE_MARGIN_PX;
+  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
+  const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
+  stopEase();
+  if (options.smooth === false || reducedMotion()) {
+    request(toPercent, { time: start, x });
+    return;
+  }
+  const fromPercent = currentTimelineZoomPercent();
+  const fromPps = (fitPps * fromPercent) / 100;
+  const toPps = (fitPps * toPercent) / 100;
+  const fromStart = (view.scroll.scrollLeft + x - view.contentOrigin) / fromPps;
+  // The one point both views put at the same place on screen; zooming about it, in log space,
+  // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
+  const shift = fromPps === toPps ? null : (start - fromStart) / (1 / fromPps - 1 / toPps);
+  const anchorAt = (k: number): TimelineZoomAnchor =>
+    shift === null
+      ? { time: fromStart + (start - fromStart) * k, x }
+      : { time: fromStart + shift / fromPps, x: x + shift };
+  const began = performance.now();
+  easingTo = toPercent;
+  const step = (now: number) => {
+    const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
+    const k = 1 - (1 - t) ** 3;
+    request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k));
+    if (t < 1) animation = requestAnimationFrame(step);
+    else stopEase();
+  };
+  animation = requestAnimationFrame(step);
+}
+
+/**
+ * A zoom button: twice or half the scale, eased, keeping the playhead where it is on screen,
+ * or centring it when it is off screen.
+ */
+export function zoomTimelineStep(direction: "in" | "out"): void {
+  const { timelineFitPps: fitPps, currentTime } = usePlayerStore.getState();
+  const nextPercent = getNextTimelineZoomPercent(
+    direction,
+    "manual",
+    easingTo ?? currentTimelineZoomPercent(),
+    fitPps,
+  );
+  const view = viewport;
+  if (!view || !(fitPps > 0)) {
+    requestTimelineZoom(nextPercent);
+    return;
+  }
+  const x = view.contentOrigin + RANGE_MARGIN_PX;
+  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
+  const nextPps = (fitPps * nextPercent) / 100;
+  const span = width / nextPps;
+  const playheadX =
+    view.contentOrigin +
+    currentTime * ((fitPps * currentTimelineZoomPercent()) / 100) -
+    view.scroll.scrollLeft;
+  const onScreen = playheadX >= view.contentOrigin && playheadX <= view.scroll.clientWidth;
+  const start = onScreen ? currentTime - (playheadX - x) / nextPps : currentTime - span / 2;
+  zoomTimelineToRange(start, start + span);
+}
diff --git a/packages/studio/src/player/components/useTimelineGeometry.ts b/packages/studio/src/player/components/useTimelineGeometry.ts
index 19ed8d181e9..ba4f1cd28cd 100644
--- a/packages/studio/src/player/components/useTimelineGeometry.ts
+++ b/packages/studio/src/player/components/useTimelineGeometry.ts
@@ -77,8 +77,6 @@ export function useTimelineGeometry({
   const displayDuration = pps > 0 ? displayContentWidth / pps : effectiveDuration;
   const zoomModeRef = useRef(zoomMode);
   zoomModeRef.current = zoomMode;
-  const manualZoomPercentRef = useRef(manualZoomPercent);
-  manualZoomPercentRef.current = manualZoomPercent;
   fitPpsRef.current = fitPps;
 
   // Restore the horizontal scroll offset after an edit re-derives the elements
@@ -133,6 +131,5 @@ export function useTimelineGeometry({
     displayDuration,
     clipStateVersion: expandedElements,
     zoomModeRef,
-    manualZoomPercentRef,
   };
 }
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 33dcde8973f..0e0f42c67fd 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -2,7 +2,7 @@
 
 import { act, useRef } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 
@@ -22,20 +22,16 @@ function scrollBox(scrollLeft: number) {
 }
 
 interface HarnessProps {
-  pps: number;
+  /** Omitted: the scale the store publishes, as the timeline reads it. */
+  pps?: number;
   scroll: HTMLDivElement;
-  percent?: number;
   dragging?: boolean;
   zoomMode?: ZoomMode;
 }
 
-function Harness({
-  pps,
-  scroll,
-  percent = 100,
-  dragging = false,
-  zoomMode = "manual",
-}: HarnessProps) {
+function Harness({ pps: fixedPps, scroll, dragging = false, zoomMode = "manual" }: HarnessProps) {
+  const storePps = usePlayerStore((s) => s.timelinePps);
+  const pps = fixedPps ?? storePps;
   const scrollRef = useRef(scroll);
   const durationRef = useRef(60);
   useTimelinePlayhead({
@@ -46,17 +42,13 @@ function Harness({
     isDragging: { current: dragging },
     currentTime: 0,
     zoomMode,
-    manualZoomPercent: percent,
     zoomModeRef: { current: zoomMode },
-    manualZoomPercentRef: { current: percent },
     fitPps: pps,
     fitPpsRef: { current: pps },
     effectiveDuration: 60,
     pps,
     timelineReady: true,
     elementsLength: 1,
-    setZoomMode: () => {},
-    setManualZoomPercent: () => {},
     contentOrigin: ORIGIN,
   });
   return null;
@@ -115,13 +107,13 @@ describe("useTimelinePlayhead zoom anchor", () => {
     usePlayerStore.setState({ currentTime: 6 });
     const scroll = scrollBox(400);
     const before = onScreenX(scroll, 6, 100);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    mount({ pps: 100, scroll })({ pps: 200 }, true);
     expect(onScreenX(scroll, 6, 200)).toBeCloseTo(before);
   });
 
   it("stays at 00:00 when a zoom is set with the playhead at 0, as a zoom restored on open is", () => {
     const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 250, percent: 250 }, true);
+    mount({ pps: 100, scroll })({ pps: 250 }, true);
     expect(scroll.scrollLeft).toBe(0);
   });
 
@@ -137,7 +129,7 @@ describe("useTimelinePlayhead zoom anchor", () => {
   it("brings an off-screen playhead into view when the toolbar zooms", () => {
     usePlayerStore.setState({ currentTime: 30 });
     const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    mount({ pps: 100, scroll })({ pps: 200 }, true);
     expectVisible(scroll, 30, 200);
   });
 });
@@ -146,18 +138,18 @@ describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", ()
   it("keeps 00:00 when the window resizes after an edit pinned the zoom", () => {
     usePlayerStore.setState({ currentTime: 6 });
     const scroll = scrollBox(0);
-    const update = mount({ pps: 100, scroll, percent: 200 });
-    update({ percent: 100 });
-    update({ pps: 130, percent: 100 });
+    const update = mount({ pps: 100, scroll });
+    update({});
+    update({ pps: 130 });
     expect(scroll.scrollLeft).toBe(0);
   });
 
   it("leaves an off-screen playhead alone when a length change re-pins the zoom", () => {
     usePlayerStore.setState({ currentTime: 30 });
     const scroll = scrollBox(400);
-    const update = mount({ pps: 100, scroll, percent: 150 });
-    update({ pps: 90, percent: 150 });
-    update({ pps: 101, percent: 168 });
+    const update = mount({ pps: 100, scroll });
+    update({ pps: 90 });
+    update({ pps: 101 });
     const x = onScreenX(scroll, 30, 101);
     expect(x > 800 || x < ORIGIN).toBe(true);
   });
@@ -165,7 +157,7 @@ describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", ()
   it("anchors a person's zoom that lands on the percent already stored", () => {
     usePlayerStore.setState({ currentTime: 30 });
     const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 200 })({ pps: 200, percent: 200 }, true);
+    mount({ pps: 100, scroll })({ pps: 200 }, true);
     expectVisible(scroll, 30, 200);
   });
 });
@@ -252,3 +244,52 @@ describe("useTimelinePlayhead follow while paused", () => {
     expect(scroll.scrollLeft).toBe(0);
   });
 });
+
+describe("useTimelinePlayhead wheel zoom", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({
+      toFake: ["requestAnimationFrame", "cancelAnimationFrame", "setTimeout", "clearTimeout"],
+    });
+    usePlayerStore.setState({
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      timelineFitPps: 100,
+      timelinePps: 100,
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const wheel = (scroll: HTMLDivElement, init: WheelEventInit) =>
+    act(() => {
+      const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true, ...init });
+      // happy-dom's WheelEvent drops the MouseEvent fields of its init.
+      Object.defineProperties(event, {
+        clientX: { value: 432 },
+        ctrlKey: { value: Boolean(init.ctrlKey) },
+        metaKey: { value: Boolean(init.metaKey) },
+      });
+      scroll.dispatchEvent(event);
+      vi.advanceTimersToNextFrame();
+    });
+
+  it("zooms on Cmd+wheel as on a pinch, and leaves a plain wheel to scroll", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    wheel(scroll, {});
+    expect(usePlayerStore.getState().manualZoomPercent).toBe(100);
+    wheel(scroll, { metaKey: true });
+    expect(usePlayerStore.getState().manualZoomPercent).toBeGreaterThan(100);
+  });
+
+  it("keeps the time under the pointer in place as a pinch lays out", () => {
+    const scroll = scrollBox(400);
+    mount({ scroll });
+    // Pointer 432px in: (400 + 432 - 32) / 100 = 8s sits there before and after.
+    wheel(scroll, { ctrlKey: true });
+    const pps = usePlayerStore.getState().timelinePps;
+    expect(pps).toBeGreaterThan(100);
+    expect(ORIGIN + 8 * pps - scroll.scrollLeft).toBeCloseTo(432);
+  });
+});
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 17704001124..6bda8030d06 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -2,6 +2,12 @@ import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
+import {
+  currentTimelineZoomPercent,
+  requestTimelineZoom,
+  setTimelineZoomViewport,
+  takeTimelineZoomAnchor,
+} from "./timelineZoomInput";
 import {
   getTimelinePlaybackFollowScrollLeft,
   getTimelineScrubTime,
@@ -36,17 +42,13 @@ interface UseTimelinePlayheadInput {
   isDragging: React.RefObject<boolean>;
   currentTime: number;
   zoomMode: ZoomMode;
-  manualZoomPercent: number;
   zoomModeRef: React.RefObject<ZoomMode>;
-  manualZoomPercentRef: React.RefObject<number>;
   fitPps: number;
   fitPpsRef: React.RefObject<number>;
   effectiveDuration: number;
   pps: number;
   timelineReady: boolean;
   elementsLength: number;
-  setZoomMode: (mode: ZoomMode) => void;
-  setManualZoomPercent: (percent: number) => void;
   onSeek?: (time: number) => void;
   contentOrigin: number;
 }
@@ -60,28 +62,24 @@ export function useTimelinePlayhead({
   currentTime,
   zoomMode,
   zoomModeRef,
-  manualZoomPercentRef,
   fitPps: _fitPps,
   fitPpsRef,
   effectiveDuration,
   pps,
   timelineReady,
   elementsLength,
-  setZoomMode,
-  setManualZoomPercent,
   onSeek,
   contentOrigin,
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
-  // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  // A zoom that names an anchor (pinch, zoom-to-range) keeps that time where it was; a toolbar zoom
+  // keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
   const previousAnchorPpsRef = useRef(pps);
   const userZoomCount = usePlayerStore((s) => s.userZoomCount);
   const previousZoomCountRef = useRef(userZoomCount);
   const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
   const lastSeekCountRef = useRef(liveTime.seekCount());
-  const skipCenterAnchorRef = useRef(false);
   const contentOriginRef = useRef(contentOrigin);
   contentOriginRef.current = contentOrigin;
 
@@ -91,12 +89,16 @@ export function useTimelinePlayhead({
     previousAnchorPpsRef.current = pps;
     const prevZoomCount = previousZoomCountRef.current;
     previousZoomCountRef.current = userZoomCount;
-    // Always consume the skip flag, even when pps didn't change — otherwise a
-    // pinch that produced no pps change (already at the zoom clamp) would strand
-    // it true and the next toolbar zoom would wrongly skip center-anchoring.
-    const skip = skipCenterAnchorRef.current;
-    skipCenterAnchorRef.current = false;
-    if (!scroll || pps === prevPps || skip) return;
+    // Always consume the anchor, even when pps didn't change (a zoom at its clamp), so it never
+    // lingers for a later zoom that named none.
+    const anchor = takeTimelineZoomAnchor();
+    if (!scroll || pps === prevPps) return;
+    if (anchor) {
+      const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+      const left = anchor.time * pps + contentOrigin - anchor.x;
+      scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, left));
+      return;
+    }
     const zoomed = userZoomCount !== prevZoomCount;
     if (!zoomed && scroll.scrollLeft < 1) return;
     const time = Math.max(0, lastLiveTimeRef.current);
@@ -237,62 +239,39 @@ export function useTimelinePlayhead({
     [scrollRef, isDragging, zoomModeRef, seekFromX],
   );
 
+  // Trackpad pinch arrives as ctrl+wheel; Cmd+wheel zooms too, as Mac editors do.
   const handlePinchWheel = useCallback(
     (e: WheelEvent) => {
-      if (!e.ctrlKey) return;
+      if (!e.ctrlKey && !e.metaKey) return;
       const scroll = scrollRef.current;
       if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0)
         return;
       e.preventDefault();
       e.stopPropagation();
-      const rect = scroll.getBoundingClientRect();
-      const nextZoomPercent = getPinchTimelineZoomPercent(
-        e.deltaY,
-        zoomModeRef.current,
-        manualZoomPercentRef.current,
-        fitPpsRef.current,
+      const x = e.clientX - scroll.getBoundingClientRect().left;
+      requestTimelineZoom(
+        getPinchTimelineZoomPercent(
+          e.deltaY,
+          "manual",
+          currentTimelineZoomPercent(),
+          fitPpsRef.current,
+        ),
+        { time: Math.max(0, (scroll.scrollLeft + x - contentOrigin) / ppsRef.current), x },
       );
-      if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual")
-        return;
-      const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
-      const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
-        pointerX: e.clientX - rect.left,
-        currentScrollLeft: scroll.scrollLeft,
-        contentOrigin,
-        currentPixelsPerSecond: ppsRef.current,
-        nextPixelsPerSecond: nextPps,
-        duration: durationRef.current,
-      });
-      // Pinch anchors at the cursor (below), so skip the center-anchor effect.
-      skipCenterAnchorRef.current = true;
-      setZoomMode("manual");
-      setManualZoomPercent(nextZoomPercent);
-      requestAnimationFrame(() => {
-        const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
-        scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
-      });
     },
-    [
-      scrollRef,
-      durationRef,
-      fitPpsRef,
-      ppsRef,
-      zoomModeRef,
-      manualZoomPercentRef,
-      setManualZoomPercent,
-      setZoomMode,
-      contentOrigin,
-    ],
+    [scrollRef, durationRef, fitPpsRef, ppsRef, contentOrigin],
   );
 
   useEffect(() => {
     const scroll = scrollRef.current;
     if (!scroll) return;
     scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    setTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+      setTimelineZoomViewport(null);
     };
-  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength]);
+  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
 
   return { seekFromX, autoScrollDuringDrag, dragScrollRaf };
 }
diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsx
index 5bef3ac3387..96c441381ad 100644
--- a/packages/studio/src/player/components/useTimelineProviderState.tsx
+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx
@@ -131,7 +131,7 @@ export function useTimelineProviderState({
   const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   const sessionEpoch = sessionEpochProp ?? timelineSessionEpoch;
   const setFocusedEaseSegment = usePlayerStore((s) => s.setFocusedEaseSegment);
-  const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+  const { zoomMode, manualZoomPercent } = useTimelineZoom();
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -258,22 +258,21 @@ export function useTimelineProviderState({
       timelineElements.length,
       displayLayout.totalH,
     ]);
-  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef, manualZoomPercentRef } =
-    useTimelineGeometry({
-      viewportWidth: viewport.clientWidth,
-      effectiveDuration,
-      zoomMode,
-      manualZoomPercent,
-      ppsRef,
-      fitPpsRef,
-      draggedClip,
-      resizingClip,
-      expandedElements: timelineElements,
-      isDragging,
-      scrollRef,
-      lastScrollLeftRef,
-      contentOrigin,
-    });
+  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef } = useTimelineGeometry({
+    viewportWidth: viewport.clientWidth,
+    effectiveDuration,
+    zoomMode,
+    manualZoomPercent,
+    ppsRef,
+    fitPpsRef,
+    draggedClip,
+    resizingClip,
+    expandedElements: timelineElements,
+    isDragging,
+    scrollRef,
+    lastScrollLeftRef,
+    contentOrigin,
+  });
   const timelineFocus = useTimelineLogicalFocus({
     scrollRef,
     tracks,
@@ -342,17 +341,13 @@ export function useTimelineProviderState({
     isDragging,
     currentTime,
     zoomMode,
-    manualZoomPercent,
     zoomModeRef,
-    manualZoomPercentRef,
     fitPps,
     fitPpsRef,
     effectiveDuration,
     pps,
     timelineReady,
     elementsLength: timelineElements.length,
-    setZoomMode,
-    setManualZoomPercent,
     onSeek,
     contentOrigin,
   });
diff --git a/packages/studio/src/player/components/useTimelineZoom.ts b/packages/studio/src/player/components/useTimelineZoom.ts
index f452e5af9fe..9d6f51ac0c1 100644
--- a/packages/studio/src/player/components/useTimelineZoom.ts
+++ b/packages/studio/src/player/components/useTimelineZoom.ts
@@ -1,6 +1,6 @@
 // fallow-ignore-file dead-code
-import { useCallback } from "react";
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
+import { requestTimelineZoom } from "./timelineZoomInput";
 
 export interface TimelineZoomState {
   zoomMode: ZoomMode;
@@ -14,13 +14,5 @@ export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
-  const setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
-  const setManualZoomPercent = useCallback(
-    (percent: number) => {
-      usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
-      setStorePercent(percent);
-    },
-    [setStorePercent],
-  );
-  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
+  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent: requestTimelineZoom };
 }

From 9230c8d147580c3a666b8539775acbdedff3132b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 04:26:33 -0400
Subject: [PATCH 02/26] perf(studio): coalesce timeline zoom to one write per
 frame and zoom to a range

Every zoom input goes through one owner that writes the store once per frame.

zoomTimelineToRange eases to a time range; the zoom buttons use it.
---
 .../src/player/components/useTimelinePlayhead.test.tsx     | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 0e0f42c67fd..68892b90415 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -153,13 +153,6 @@ describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", ()
     const x = onScreenX(scroll, 30, 101);
     expect(x > 800 || x < ORIGIN).toBe(true);
   });
-
-  it("anchors a person's zoom that lands on the percent already stored", () => {
-    usePlayerStore.setState({ currentTime: 30 });
-    const scroll = scrollBox(0);
-    mount({ pps: 100, scroll })({ pps: 200 }, true);
-    expectVisible(scroll, 30, 200);
-  });
 });
 
 describe("useTimelinePlayhead follow while paused", () => {

From e09471b7810221bc54b8409fe090e62bcdd800df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 06:40:09 -0400
Subject: [PATCH 03/26] feat(studio): zoom-to-range reports done or cancelled
 and is not a person zoom

---
 .../components/timelineZoomInput.test.ts      | 36 +++++++++-
 .../player/components/timelineZoomInput.ts    | 66 +++++++++++++------
 2 files changed, 81 insertions(+), 21 deletions(-)

diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index dd1fc3fb77f..2e743cccf16 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -29,6 +29,8 @@ beforeEach(() => {
   });
 });
 afterEach(() => {
+  // Run out any ease and pending write, so the next test starts with nothing scheduled.
+  for (let i = 0; i < 40; i++) vi.advanceTimersToNextFrame();
   setTimelineZoomViewport(null);
   takeTimelineZoomAnchor();
   vi.useRealTimers();
@@ -90,14 +92,37 @@ describe("zoomTimelineToRange", () => {
     expect(anchor && anchor.x + (10 - anchor.time) * 100).toBeCloseTo(56);
   });
 
-  it("stops easing when a person zooms during it", () => {
+  it("stops easing when a person zooms during it, and says it was cancelled", async () => {
     viewport(1080);
-    zoomTimelineToRange(10, 20);
+    const result = zoomTimelineToRange(10, 20);
     vi.advanceTimersToNextFrame();
     vi.advanceTimersToNextFrame();
     requestTimelineZoom(150);
     for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
     expect(usePlayerStore.getState().manualZoomPercent).toBe(150);
+    await expect(result).resolves.toBe("cancelled");
+  });
+
+  it("resolves done once the range is laid out, without counting as a person's zoom", async () => {
+    viewport(1080);
+    let settled: string | null = null;
+    void zoomTimelineToRange(10, 20).then((r) => (settled = r));
+    for (let i = 0; i < 30 && settled === null; i++) {
+      vi.advanceTimersToNextFrame();
+      await Promise.resolve();
+    }
+    expect(settled).toBe("done");
+    expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
+    expect(usePlayerStore.getState().userZoomCount).toBe(0);
+  });
+
+  it("cancels when the caller aborts", async () => {
+    viewport(1080);
+    const abort = new AbortController();
+    const result = zoomTimelineToRange(10, 20, { signal: abort.signal });
+    vi.advanceTimersToNextFrame();
+    abort.abort();
+    await expect(result).resolves.toBe("cancelled");
   });
 });
 
@@ -118,6 +143,13 @@ describe("zoomTimelineStep", () => {
     return anchor && anchor.x + (time - anchor.time) * usePlayerStore.getState().timelinePps;
   };
 
+  it("counts as a person's zoom", () => {
+    viewport(0);
+    zoomTimelineStep("in");
+    run();
+    expect(usePlayerStore.getState().userZoomCount).toBeGreaterThan(0);
+  });
+
   it("doubles the scale and keeps an on-screen playhead where it is", () => {
     usePlayerStore.setState({ currentTime: 40 });
     viewport(0);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index a54d5a5a99e..0b957c24a81 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -21,12 +21,17 @@ export interface TimelineZoomViewport {
 const RANGE_MARGIN_PX = 24;
 const SMOOTH_ZOOM_MS = 220;
 
-let pending: { percent: number; anchor: TimelineZoomAnchor | null } | null = null;
+/** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
+export type TimelineZoomResult = "done" | "cancelled";
+
+let pending: { percent: number; anchor: TimelineZoomAnchor | null; byPerson: boolean } | null =
+  null;
 let frame = 0;
 let anchorForCommit: TimelineZoomAnchor | null = null;
 let viewport: TimelineZoomViewport | null = null;
 let animation = 0;
 let easingTo: number | null = null;
+let settle: ((result: TimelineZoomResult) => void) | null = null;
 
 /** The percent the timeline is showing, or will show next frame. */
 export function currentTimelineZoomPercent(): number {
@@ -48,28 +53,32 @@ function flush() {
     return {
       zoomMode: "manual",
       manualZoomPercent: percent,
-      userZoomCount: s.userZoomCount + 1,
+      // Only a person's zoom counts: the timeline and its host read it as the person taking over.
+      userZoomCount: s.userZoomCount + (next.byPerson ? 1 : 0),
       timelinePps: (s.timelineFitPps * percent) / 100,
     };
   });
 }
 
-function request(percent: number, anchor: TimelineZoomAnchor | null) {
-  pending = { percent, anchor };
+function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+  pending = { percent, anchor, byPerson: byPerson || pending?.byPerson === true };
   markTimelineMotion();
   if (!frame) frame = requestAnimationFrame(flush);
 }
 
-/** Every zoom input's one door: requests in the same frame collapse to the last, drawn once. */
+/** A person's zoom input; requests in the same frame collapse to the last, drawn once. */
 export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
   stopEase();
-  request(percent, anchor);
+  request(percent, anchor, true);
 }
 
-function stopEase() {
+function stopEase(result: TimelineZoomResult = "cancelled") {
   cancelAnimationFrame(animation);
   animation = 0;
   easingTo = null;
+  const done = settle;
+  settle = null;
+  done?.(result);
 }
 
 /** The anchor of the zoom being committed; read once by the timeline as it lays the zoom out. */
@@ -87,24 +96,42 @@ const reducedMotion = () =>
   typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
 
 /**
- * Zooms and scrolls so `start`..`end` fills the timeline's width, easing there unless
- * `smooth` is false or the person prefers reduced motion.
+ * Zooms and scrolls so `start`..`end` (seconds) fills the timeline's width, easing there unless
+ * `smooth` is false or the person prefers reduced motion. Resolves once the last step is laid
+ * out, or as "cancelled" when a person zooms, `signal` aborts, or another range zoom starts.
  */
 export function zoomTimelineToRange(
   start: number,
   end: number,
-  options: { smooth?: boolean } = {},
-): void {
+  options: { smooth?: boolean; signal?: AbortSignal } = {},
+): Promise<TimelineZoomResult> {
+  return easeToRange(start, end, options, false);
+}
+
+function easeToRange(
+  start: number,
+  end: number,
+  { smooth = true, signal }: { smooth?: boolean; signal?: AbortSignal },
+  byPerson: boolean,
+): Promise<TimelineZoomResult> {
   const view = viewport;
   const fitPps = usePlayerStore.getState().timelineFitPps;
-  if (!view || !(end > start) || !(fitPps > 0)) return;
+  stopEase();
+  if (!view || !(end > start) || !(fitPps > 0) || signal?.aborted)
+    return Promise.resolve("cancelled");
+  const result = new Promise<TimelineZoomResult>((resolve) => (settle = resolve));
+  signal?.addEventListener("abort", () => settle && stopEase(), { once: true });
   const x = view.contentOrigin + RANGE_MARGIN_PX;
   const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
   const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
-  stopEase();
-  if (options.smooth === false || reducedMotion()) {
-    request(toPercent, { time: start, x });
-    return;
+  // Resolved a frame after the last request: its write and layout have run by then.
+  const finish = () => {
+    animation = requestAnimationFrame(() => stopEase("done"));
+  };
+  if (!smooth || reducedMotion()) {
+    request(toPercent, { time: start, x }, byPerson);
+    finish();
+    return result;
   }
   const fromPercent = currentTimelineZoomPercent();
   const fromPps = (fitPps * fromPercent) / 100;
@@ -122,11 +149,12 @@ export function zoomTimelineToRange(
   const step = (now: number) => {
     const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
     const k = 1 - (1 - t) ** 3;
-    request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k));
+    request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);
     if (t < 1) animation = requestAnimationFrame(step);
-    else stopEase();
+    else finish();
   };
   animation = requestAnimationFrame(step);
+  return result;
 }
 
 /**
@@ -156,5 +184,5 @@ export function zoomTimelineStep(direction: "in" | "out"): void {
     view.scroll.scrollLeft;
   const onScreen = playheadX >= view.contentOrigin && playheadX <= view.scroll.clientWidth;
   const start = onScreen ? currentTime - (playheadX - x) / nextPps : currentTime - span / 2;
-  zoomTimelineToRange(start, start + span);
+  void easeToRange(start, start + span, {}, true);
 }

From 1af85d3870adc8598cf8dd5d7f6cbd134ce36e64 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 07:12:17 -0400
Subject: [PATCH 04/26] perf(studio): place clips in percent of a one-second
 layer so zoom restyles nothing

A zoom step rewrites one width per row; clip thumbnails start decoding at rest.
---
 .../src/player/components/Timeline.test.ts    |   4 +-
 .../src/player/components/TimelineClip.tsx    |   8 +-
 .../player/components/TimelineClipJoins.tsx   |  41 +-
 .../components/TimelineGestureOverlay.tsx     |  57 +--
 .../player/components/TimelineLanes.test.tsx  |  12 +-
 .../src/player/components/TimelineLanes.tsx   | 354 +++++++++---------
 .../player/components/TimelineTimeLayer.tsx   |  26 ++
 .../player/components/VideoThumbnail.test.tsx |  47 +++
 .../src/player/components/VideoThumbnail.tsx  |   3 +-
 9 files changed, 325 insertions(+), 227 deletions(-)
 create mode 100644 packages/studio/src/player/components/TimelineTimeLayer.tsx

diff --git a/packages/studio/src/player/components/Timeline.test.ts b/packages/studio/src/player/components/Timeline.test.ts
index d8702d8a64c..6c532c6b25a 100644
--- a/packages/studio/src/player/components/Timeline.test.ts
+++ b/packages/studio/src/player/components/Timeline.test.ts
@@ -208,7 +208,9 @@ describe("Timeline provider boundary", () => {
       renderTimelineGeometry("clip-1");
 
     expect(trackHeader.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
-    expect(clip.style.left).toBe("1000px");
+    // 10 s at 100 px/s: 1000% of a one-second layer 100px wide.
+    expect(clip.style.left).toBe("1000%");
+    expect((clip.closest("[data-timeline-time-layer]") as HTMLElement).style.width).toBe("100px");
     expect(clip.style.height).toBe("");
     expect(clip.style.bottom).toBe(`${CLIP_Y}px`);
     expect(rulerOrigin.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 29aed434a9c..e43b35af283 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -17,6 +17,7 @@ import { linkLabelColor } from "./linkLabelColor";
 import { OutOfSyncBadge } from "./OutOfSyncBadge";
 import { clipSpeedSuffix } from "./clipToolAttrs";
 import { ClipPeakTooltip } from "./ClipPeakTooltip";
+import { timeLayerPercent } from "./TimelineTimeLayer";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -70,7 +71,6 @@ export const TimelineClip = memo(function TimelineClip({
   onContextMenu,
   children,
 }: TimelineClipProps) {
-  const leftPx = el.start * pps;
   const widthPx = Math.max(el.duration * pps, 4);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
   const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;
@@ -110,9 +110,11 @@ export const TimelineClip = memo(function TimelineClip({
   ]
     .filter((className) => className.length > 0)
     .join(" ");
+  // In percent of the row's TimelineTimeLayer: a zoom step leaves this style as it is.
   const style: CSSProperties = {
-    left: leftPx,
-    width: widthPx,
+    left: timeLayerPercent(el.start),
+    width: timeLayerPercent(el.duration),
+    minWidth: 4,
     top: clipY,
     ...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
     borderRadius: isAudioClip ? theme.audioClipRadius : theme.clipRadius,
diff --git a/packages/studio/src/player/components/TimelineClipJoins.tsx b/packages/studio/src/player/components/TimelineClipJoins.tsx
index 623a667c36d..c3e86823ac2 100644
--- a/packages/studio/src/player/components/TimelineClipJoins.tsx
+++ b/packages/studio/src/player/components/TimelineClipJoins.tsx
@@ -1,6 +1,7 @@
 import { CLIP_Y } from "./timelineLayout";
 import { sortedLaneClips, TRACK_GAP_EPSILON_S } from "./timelineGaps";
 import type { TimelineElement } from "../store/playerStore";
+import { TimelineTimeLayer, timeLayerPercent } from "./TimelineTimeLayer";
 
 /** Times where one clip on a row ends exactly where the next begins. */
 export function deriveTimelineClipJoins(elements: readonly TimelineElement[]): number[] {
@@ -31,22 +32,26 @@ export function TimelineClipJoins({
   color,
 }: TimelineClipJoinsProps) {
   const height = clipBarHeight ?? rowHeight - 2 * CLIP_Y;
-  return deriveTimelineClipJoins(elements).map((time) => (
-    <div
-      key={time}
-      data-timeline-clip-join=""
-      aria-hidden="true"
-      className="absolute pointer-events-none"
-      style={{
-        left: time * pixelsPerSecond,
-        top: CLIP_Y,
-        width: 1,
-        height,
-        transform: "translateX(-50%)",
-        background: color,
-        // Over an idle or hovered clip, under the diamonds (6) and a selected clip (10).
-        zIndex: 5,
-      }}
-    />
-  ));
+  return (
+    <TimelineTimeLayer pixelsPerSecond={pixelsPerSecond}>
+      {deriveTimelineClipJoins(elements).map((time) => (
+        <div
+          key={time}
+          data-timeline-clip-join=""
+          aria-hidden="true"
+          className="absolute pointer-events-none"
+          style={{
+            left: timeLayerPercent(time),
+            top: CLIP_Y,
+            width: 1,
+            height,
+            transform: "translateX(-50%)",
+            background: color,
+            // Over an idle or hovered clip, under the diamonds (6) and a selected clip (10).
+            zIndex: 5,
+          }}
+        />
+      ))}
+    </TimelineTimeLayer>
+  );
 }
diff --git a/packages/studio/src/player/components/TimelineGestureOverlay.tsx b/packages/studio/src/player/components/TimelineGestureOverlay.tsx
index bb1b89a2f3d..1e957f771cd 100644
--- a/packages/studio/src/player/components/TimelineGestureOverlay.tsx
+++ b/packages/studio/src/player/components/TimelineGestureOverlay.tsx
@@ -10,6 +10,7 @@ import type { DraggedClipState } from "./timelineClipDragTypes";
 import type { TrackVisualStyle } from "./timelineIcons";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
 import type { TimelineProps } from "./TimelineTypes";
+import { TimelineTimeLayer } from "./TimelineTimeLayer";
 
 interface TimelineGestureOverlayProps {
   drag: DraggedClipState | null;
@@ -103,33 +104,35 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
               + New track<span className="sr-only">, before track {insertRow + 1}</span>
             </span>
           )}
-          <TimelineClip
-            el={{ ...element, start: 0 }}
-            pps={pixelsPerSecond}
-            clipY={0}
-            isSelected={selectedElementId === (element.key ?? element.id)}
-            isHovered={false}
-            isDragging
-            isGestureActor
-            isActive={isTimelineClipActive(element, currentTime)}
-            hasCustomContent={!!renderClipContent}
-            capabilities={getTimelineEditCapabilities(element)}
-            theme={theme}
-            isComposition={!!element.compositionSrc}
-            onHoverStart={() => {}}
-            onHoverEnd={() => {}}
-            onResizeStart={() => {}}
-            onClick={() => {}}
-            onDoubleClick={() => {}}
-          >
-            {renderClipChildren(
-              element,
-              getTrackStyle(element.tag),
-              renderClipContent,
-              renderClipOverlay,
-              { priority: "interaction", rich: false },
-            )}
-          </TimelineClip>
+          <TimelineTimeLayer pixelsPerSecond={pixelsPerSecond}>
+            <TimelineClip
+              el={{ ...element, start: 0 }}
+              pps={pixelsPerSecond}
+              clipY={0}
+              isSelected={selectedElementId === (element.key ?? element.id)}
+              isHovered={false}
+              isDragging
+              isGestureActor
+              isActive={isTimelineClipActive(element, currentTime)}
+              hasCustomContent={!!renderClipContent}
+              capabilities={getTimelineEditCapabilities(element)}
+              theme={theme}
+              isComposition={!!element.compositionSrc}
+              onHoverStart={() => {}}
+              onHoverEnd={() => {}}
+              onResizeStart={() => {}}
+              onClick={() => {}}
+              onDoubleClick={() => {}}
+            >
+              {renderClipChildren(
+                element,
+                getTrackStyle(element.tag),
+                renderClipContent,
+                renderClipOverlay,
+                { priority: "interaction", rich: false },
+              )}
+            </TimelineClip>
+          </TimelineTimeLayer>
         </div>
       )}
     </div>
diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx
index deab4d5721a..4c3d5541aef 100644
--- a/packages/studio/src/player/components/TimelineLanes.test.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx
@@ -586,12 +586,18 @@ describe("TimelineLanes clip joins", () => {
 
     const joins = view.host.querySelectorAll<HTMLElement>("[data-timeline-clip-join]");
     expect(joins).toHaveLength(1);
-    expect(joins[0]?.style.left).toBe("200px");
+    // Both sit in one-second layers 100px wide: 200% is 200px, at the 2 s join.
+    const layerWidth = (el: Element | null | undefined) =>
+      (el?.closest("[data-timeline-time-layer]") as HTMLElement | null)?.style.width;
+    expect(joins[0]?.style.left).toBe("200%");
+    expect(layerWidth(joins[0])).toBe("100px");
     expect(joins[0]?.style.width).toBe("1px");
     expect(joins[0]?.style.background).toBe(defaultTimelineTheme.rowBackground);
     const clipB = view.host.querySelector<HTMLElement>('[data-el-id="clip-b"]');
-    expect(clipB?.style.left).toBe("200px");
-    expect(clipB?.style.width).toBe("150px");
+    expect(clipB?.style.left).toBe("200%");
+    expect(clipB?.style.width).toBe("150%");
+    expect(clipB?.style.minWidth).toBe("4px");
+    expect(layerWidth(clipB)).toBe("100px");
     act(() => view.root.unmount());
   });
 
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index b9a22f610f8..5027900a010 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -10,6 +10,7 @@ import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { TimelineGroupRow } from "./TimelineGroupRow";
 import { useTimelineLaneRowIndexes, useTimelineGroupDisclosure } from "./useTimelineLaneRowIndexes";
 import { useTimelineClipDisclosure } from "./useTimelineClipDisclosure";
+import { TimelineTimeLayer } from "./TimelineTimeLayer";
 import {
   isTrackRowExpanded,
   resolveTrackKeyframeClip,
@@ -368,181 +369,186 @@ export function TimelineLanes({
                     renderTimeRange={rowsVirtualized ? renderTimeRange : undefined}
                   />
                 )}
-                {
-                  // fallow-ignore-next-line complexity
-                  renderElements.map((el) => {
-                    const clipStyle = getTrackStyle(el.tag);
-                    const elementKey = getTimelineElementIdentity(el);
-                    // Only the track's active keyframe clip shows expanded lanes;
-                    // other clips (incl. siblings on a shared track) show compact
-                    // diamonds on their own bar instead.
-                    const isTrackKeyframeClip = elementKey === keyframeClipKey;
-                    const showsLanes = isTrackKeyframeClip && rowExpanded;
-                    const capabilities = getClipCapabilities(el);
-                    const isSelected =
-                      selectedElementId === elementKey || selectedElementIds.has(elementKey);
-                    const isComposition = !!el.compositionSrc;
-                    // Element identity stays stable across clip splices and reorders.
-                    const clipKey = elementKey;
-                    const isDraggingClip =
-                      draggedClip?.started === true &&
-                      draggedElement != null &&
-                      getTimelineElementIdentity(draggedElement) === elementKey;
-                    if (isDraggingClip) return null;
-                    const previewElement = getPreviewElement(el);
-                    const renderContext = resolveClipRenderContext(
-                      previewElement,
-                      visibleTimeRange,
-                      isSelected || hoveredClip === clipKey || pinnedClipIdentities.has(clipKey),
-                    );
-                    // Passenger of a live multi-drag: preserve the formation without changing
-                    // the passenger's timeline data until the owning drag commits.
-                    const isPassenger =
-                      multiDragPreview != null && isMultiDragPassenger(clipKey, multiDragPreview);
-                    const passengerStyle = isPassenger
-                      ? passengerStyleAt(multiDragPassengerOffsetPx(clipKey, pps, multiDragPreview))
-                      : undefined;
-                    const clipGestures = createClipGestureHandlers(
-                      el,
-                      elementKey,
-                      previewElement,
-                      capabilities,
-                      {
-                        pps,
-                        onResizeElement,
-                        onMoveElement,
-                        onRazorSplit,
-                        onRazorSplitAll,
-                        blockedClipRef,
-                        suppressClickRef,
-                        scrollRef,
-                        setShowPopover,
-                        setRangeSelection,
-                        setResizingClip,
-                        setDraggedClip,
-                        setSelectedElementId,
-                        onSelectElement,
-                      },
-                    );
-                    const clip = (
-                      <TimelineClip
-                        key={clipKey}
-                        onContextMenu={(e: React.MouseEvent) => {
-                          e.preventDefault();
-                          onContextMenuClip?.(e, el);
-                        }}
-                        el={previewElement}
-                        pps={pps}
-                        passengerStyle={passengerStyle}
-                        clipY={CLIP_Y}
-                        clipHeight={clipBarHeight}
-                        isSelected={isSelected}
-                        isHovered={hoveredClip === clipKey}
-                        isDragging={false}
-                        isActive={isTimelineClipActive(previewElement, currentTime)}
-                        hasCustomContent={!!renderClipContent}
-                        capabilities={capabilities}
-                        theme={theme}
-                        isComposition={isComposition}
-                        tabIndex={
-                          keyboard.rovingTargetId === timelineClipFocusId(elementKey) ? 0 : -1
-                        }
-                        onHoverStart={() => setHoveredClip(clipKey)}
-                        onHoverEnd={() => setHoveredClip(null)}
-                        onResizeStart={clipGestures.onResizeStart}
-                        onPointerDown={clipGestures.onPointerDown}
-                        onClick={clipGestures.onClick}
-                        onDoubleClick={(e) => {
-                          e.stopPropagation();
-                          if (suppressClickRef.current) return;
-                          if (isComposition && onDrillDown) onDrillDown(el);
-                        }}
-                      >
-                        {renderClipChildren(
-                          previewElement,
-                          clipStyle,
-                          renderClipContent,
-                          renderClipOverlay,
-                          renderContext,
-                        )}
-                      </TimelineClip>
-                    );
-                    const compactKeyframes = keyframeCache?.get(elementKey);
-                    const compactDiamonds = !showsLanes && compactKeyframes && (
-                      <TimelineCompactDiamonds
-                        key={`${clipKey}-diamonds`}
-                        element={previewElement}
-                        elementId={elementKey}
-                        keyframesData={compactKeyframes}
-                        pixelsPerSecond={pps}
-                        rowHeight={rowHeight}
-                        beatsActive={beatStripOnTrack}
-                        accentColor={clipStyle.accent}
-                        isSelected={isSelected}
-                        passengerStyle={passengerStyle}
-                        currentTime={currentTime}
-                        selectedKeyframes={selectedKeyframes}
-                        rovingTargetId={keyboard.rovingTargetId}
-                        onClickKeyframe={onClickKeyframe}
-                        onShiftClickKeyframe={onShiftClickKeyframe}
-                        onContextMenuKeyframe={onContextMenuKeyframe}
-                        onMoveKeyframe={onMoveKeyframe}
-                        onSelectSegment={onSelectSegment}
-                        suppressClickRef={suppressClickRef}
-                      />
-                    );
-                    // Keep this shell mounted while collapsed so aria-controls stays valid
-                    // and multi-drag cannot remount the subtree mid-gesture.
-                    const propertyLanes = isTrackKeyframeClip && (
-                      <TimelinePropertyLanes
-                        key={`${clipKey}-property-lanes`}
-                        id={lanesId}
-                        animations={showsLanes ? (gsapAnimations.get(elementKey) ?? []) : []}
-                        // clipTimingStart, not the raw start: an expanded sub-comp
-                        // child's start is host-absolute while its tweens are
-                        // local to its own file.
-                        clipStart={clipTimingStart(previewElement)}
-                        clipDuration={previewElement.duration}
-                        clipLeftPx={previewElement.start * pps}
-                        clipWidthPx={Math.max(previewElement.duration * pps, 4)}
-                        passengerStyle={passengerStyle}
-                        accentColor={clipStyle.accent}
-                        isSelected={isSelected}
-                        currentPercentage={
-                          previewElement.duration > 0
-                            ? ((currentTime - previewElement.start) / previewElement.duration) * 100
-                            : 0
-                        }
-                        elementId={elementKey}
-                        selectedKeyframes={selectedKeyframes}
-                        rovingTargetId={keyboard.rovingTargetId}
-                        onSelectSegment={(target) => onSelectSegment?.(elementKey, target)}
-                        onClickKeyframe={(target) => onClickKeyframe?.(previewElement, target)}
-                        onShiftClickKeyframe={(target) =>
-                          onShiftClickKeyframe?.(elementKey, target)
-                        }
-                        onContextMenuKeyframe={(e, target) =>
-                          onContextMenuKeyframe?.(e, elementKey, target)
-                        }
-                        onMoveKeyframe={(target, toClipPercentage) =>
-                          onMoveKeyframe?.(elementKey, target, toClipPercentage) ??
-                          Promise.resolve(false)
-                        }
-                        suppressClickRef={suppressClickRef}
-                      />
-                    );
+                <TimelineTimeLayer pixelsPerSecond={pps}>
+                  {
+                    // fallow-ignore-next-line complexity
+                    renderElements.map((el) => {
+                      const clipStyle = getTrackStyle(el.tag);
+                      const elementKey = getTimelineElementIdentity(el);
+                      // Only the track's active keyframe clip shows expanded lanes;
+                      // other clips (incl. siblings on a shared track) show compact
+                      // diamonds on their own bar instead.
+                      const isTrackKeyframeClip = elementKey === keyframeClipKey;
+                      const showsLanes = isTrackKeyframeClip && rowExpanded;
+                      const capabilities = getClipCapabilities(el);
+                      const isSelected =
+                        selectedElementId === elementKey || selectedElementIds.has(elementKey);
+                      const isComposition = !!el.compositionSrc;
+                      // Element identity stays stable across clip splices and reorders.
+                      const clipKey = elementKey;
+                      const isDraggingClip =
+                        draggedClip?.started === true &&
+                        draggedElement != null &&
+                        getTimelineElementIdentity(draggedElement) === elementKey;
+                      if (isDraggingClip) return null;
+                      const previewElement = getPreviewElement(el);
+                      const renderContext = resolveClipRenderContext(
+                        previewElement,
+                        visibleTimeRange,
+                        isSelected || hoveredClip === clipKey || pinnedClipIdentities.has(clipKey),
+                      );
+                      // Passenger of a live multi-drag: preserve the formation without changing
+                      // the passenger's timeline data until the owning drag commits.
+                      const isPassenger =
+                        multiDragPreview != null && isMultiDragPassenger(clipKey, multiDragPreview);
+                      const passengerStyle = isPassenger
+                        ? passengerStyleAt(
+                            multiDragPassengerOffsetPx(clipKey, pps, multiDragPreview),
+                          )
+                        : undefined;
+                      const clipGestures = createClipGestureHandlers(
+                        el,
+                        elementKey,
+                        previewElement,
+                        capabilities,
+                        {
+                          pps,
+                          onResizeElement,
+                          onMoveElement,
+                          onRazorSplit,
+                          onRazorSplitAll,
+                          blockedClipRef,
+                          suppressClickRef,
+                          scrollRef,
+                          setShowPopover,
+                          setRangeSelection,
+                          setResizingClip,
+                          setDraggedClip,
+                          setSelectedElementId,
+                          onSelectElement,
+                        },
+                      );
+                      const clip = (
+                        <TimelineClip
+                          key={clipKey}
+                          onContextMenu={(e: React.MouseEvent) => {
+                            e.preventDefault();
+                            onContextMenuClip?.(e, el);
+                          }}
+                          el={previewElement}
+                          pps={pps}
+                          passengerStyle={passengerStyle}
+                          clipY={CLIP_Y}
+                          clipHeight={clipBarHeight}
+                          isSelected={isSelected}
+                          isHovered={hoveredClip === clipKey}
+                          isDragging={false}
+                          isActive={isTimelineClipActive(previewElement, currentTime)}
+                          hasCustomContent={!!renderClipContent}
+                          capabilities={capabilities}
+                          theme={theme}
+                          isComposition={isComposition}
+                          tabIndex={
+                            keyboard.rovingTargetId === timelineClipFocusId(elementKey) ? 0 : -1
+                          }
+                          onHoverStart={() => setHoveredClip(clipKey)}
+                          onHoverEnd={() => setHoveredClip(null)}
+                          onResizeStart={clipGestures.onResizeStart}
+                          onPointerDown={clipGestures.onPointerDown}
+                          onClick={clipGestures.onClick}
+                          onDoubleClick={(e) => {
+                            e.stopPropagation();
+                            if (suppressClickRef.current) return;
+                            if (isComposition && onDrillDown) onDrillDown(el);
+                          }}
+                        >
+                          {renderClipChildren(
+                            previewElement,
+                            clipStyle,
+                            renderClipContent,
+                            renderClipOverlay,
+                            renderContext,
+                          )}
+                        </TimelineClip>
+                      );
+                      const compactKeyframes = keyframeCache?.get(elementKey);
+                      const compactDiamonds = !showsLanes && compactKeyframes && (
+                        <TimelineCompactDiamonds
+                          key={`${clipKey}-diamonds`}
+                          element={previewElement}
+                          elementId={elementKey}
+                          keyframesData={compactKeyframes}
+                          pixelsPerSecond={pps}
+                          rowHeight={rowHeight}
+                          beatsActive={beatStripOnTrack}
+                          accentColor={clipStyle.accent}
+                          isSelected={isSelected}
+                          passengerStyle={passengerStyle}
+                          currentTime={currentTime}
+                          selectedKeyframes={selectedKeyframes}
+                          rovingTargetId={keyboard.rovingTargetId}
+                          onClickKeyframe={onClickKeyframe}
+                          onShiftClickKeyframe={onShiftClickKeyframe}
+                          onContextMenuKeyframe={onContextMenuKeyframe}
+                          onMoveKeyframe={onMoveKeyframe}
+                          onSelectSegment={onSelectSegment}
+                          suppressClickRef={suppressClickRef}
+                        />
+                      );
+                      // Keep this shell mounted while collapsed so aria-controls stays valid
+                      // and multi-drag cannot remount the subtree mid-gesture.
+                      const propertyLanes = isTrackKeyframeClip && (
+                        <TimelinePropertyLanes
+                          key={`${clipKey}-property-lanes`}
+                          id={lanesId}
+                          animations={showsLanes ? (gsapAnimations.get(elementKey) ?? []) : []}
+                          // clipTimingStart, not the raw start: an expanded sub-comp
+                          // child's start is host-absolute while its tweens are
+                          // local to its own file.
+                          clipStart={clipTimingStart(previewElement)}
+                          clipDuration={previewElement.duration}
+                          clipLeftPx={previewElement.start * pps}
+                          clipWidthPx={Math.max(previewElement.duration * pps, 4)}
+                          passengerStyle={passengerStyle}
+                          accentColor={clipStyle.accent}
+                          isSelected={isSelected}
+                          currentPercentage={
+                            previewElement.duration > 0
+                              ? ((currentTime - previewElement.start) / previewElement.duration) *
+                                100
+                              : 0
+                          }
+                          elementId={elementKey}
+                          selectedKeyframes={selectedKeyframes}
+                          rovingTargetId={keyboard.rovingTargetId}
+                          onSelectSegment={(target) => onSelectSegment?.(elementKey, target)}
+                          onClickKeyframe={(target) => onClickKeyframe?.(previewElement, target)}
+                          onShiftClickKeyframe={(target) =>
+                            onShiftClickKeyframe?.(elementKey, target)
+                          }
+                          onContextMenuKeyframe={(e, target) =>
+                            onContextMenuKeyframe?.(e, elementKey, target)
+                          }
+                          onMoveKeyframe={(target, toClipPercentage) =>
+                            onMoveKeyframe?.(elementKey, target, toClipPercentage) ??
+                            Promise.resolve(false)
+                          }
+                          suppressClickRef={suppressClickRef}
+                        />
+                      );
 
-                    // No wrapper node per clip, and the same Fragment whether or not it rides a
-                    // drag, so joining or leaving one restyles it, never remounts it.
-                    return (
-                      <Fragment key={clipKey}>
-                        {clip}
-                        {compactDiamonds}
-                        {propertyLanes}
-                      </Fragment>
-                    );
-                  })
-                }
+                      // No wrapper node per clip, and the same Fragment whether or not it rides a
+                      // drag, so joining or leaving one restyles it, never remounts it.
+                      return (
+                        <Fragment key={clipKey}>
+                          {clip}
+                          {compactDiamonds}
+                          {propertyLanes}
+                        </Fragment>
+                      );
+                    })
+                  }
+                </TimelineTimeLayer>
                 <TimelineTransitionOverlays
                   seams={transitionSeamsByTrack.get(trackNum) ?? []}
                   rowElements={draggedClip?.started ? [] : automationElements}
diff --git a/packages/studio/src/player/components/TimelineTimeLayer.tsx b/packages/studio/src/player/components/TimelineTimeLayer.tsx
new file mode 100644
index 00000000000..def9adefb53
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineTimeLayer.tsx
@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+
+/**
+ * A box one second wide at the current zoom. What sits in it places itself in percent of it
+ * (`left: start * 100%`), so a zoom step rewrites this one width and no clip's style changes.
+ */
+export function TimelineTimeLayer({
+  pixelsPerSecond,
+  children,
+}: {
+  pixelsPerSecond: number;
+  children: ReactNode;
+}) {
+  return (
+    <div
+      data-timeline-time-layer=""
+      className="absolute inset-y-0 left-0"
+      style={{ width: pixelsPerSecond }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** A time, in seconds, as a position inside a TimelineTimeLayer. */
+export const timeLayerPercent = (seconds: number) => `${seconds * 100}%`;
diff --git a/packages/studio/src/player/components/VideoThumbnail.test.tsx b/packages/studio/src/player/components/VideoThumbnail.test.tsx
index 4dcd72ca153..3f1801f438d 100644
--- a/packages/studio/src/player/components/VideoThumbnail.test.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.test.tsx
@@ -6,6 +6,7 @@ import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { VideoThumbnail } from "./VideoThumbnail";
+import { markTimelineMotion } from "./timelineMotion";
 
 vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
 
@@ -249,3 +250,49 @@ describe("VideoThumbnail", () => {
     expect(host.querySelector("img")).toBeNull();
   });
 });
+
+describe("VideoThumbnail during a zoom", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+      weight: 256,
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const rest = () =>
+    act(async () => {
+      vi.runOnlyPendingTimers();
+      await Promise.resolve();
+    });
+
+  it("decodes a clip that scrolls in mid-zoom only once the timeline rests", async () => {
+    markTimelineMotion();
+    await render(440);
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 1 }),
+      expect.any(AbortSignal),
+    );
+  });
+
+  it("keeps its filmstrip while the zoom resizes it, and decodes the new width at rest", async () => {
+    await render(440);
+    vi.mocked(decodeVideoThumbnail).mockClear();
+    await act(async () => {
+      markTimelineMotion();
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 16 }),
+      expect.any(AbortSignal),
+    );
+  });
+});
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 188876bc597..9f78b0f41e8 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -114,7 +114,8 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  const measured = container.width > 0;
+  // A clip that scrolls in mid-zoom starts decoding once the timeline rests.
+  const measured = useValueAtRest(container.width > 0);
   const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
   const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
   const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);

From 7b180b396b8bd47379e52e1f42d4ffb191a83f04 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 07:31:40 -0400
Subject: [PATCH 05/26] perf(studio): a zoom step re-renders only clips whose
 drawing it changes

Clip handlers read the lane callbacks when pressed, so a skipped clip never acts on a stale zoom.
---
 .../src/player/components/TimelineClip.tsx    |  20 ++-
 .../player/components/TimelineLaneClip.tsx    | 127 ++++++++++++++++++
 .../player/components/TimelineLanes.test.tsx  |  45 ++++++-
 .../src/player/components/TimelineLanes.tsx   |  98 ++++++--------
 4 files changed, 226 insertions(+), 64 deletions(-)
 create mode 100644 packages/studio/src/player/components/TimelineLaneClip.tsx

diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index e43b35af283..dd545577f91 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -45,6 +45,22 @@ interface TimelineClipProps {
   children?: ReactNode;
 }
 
+/** Narrower clips show trim handles only while selected. */
+const HANDLES_MIN_PX = 32;
+
+const clipWidthPx = (el: TimelineElement, pps: number) => Math.max(el.duration * pps, 4);
+
+/**
+ * What a clip draws that depends on the zoom, as one value: its width tier and whether its trim
+ * handles fit, or the scale itself while its fade handles are live (hovered, selected or set).
+ */
+export function clipZoomKey(el: TimelineElement, pps: number, interacting: boolean) {
+  const fadesLive = interacting || (el.fadeIn ?? 0) > 0 || (el.fadeOut ?? 0) > 0;
+  if (fadesLive) return pps;
+  const widthPx = clipWidthPx(el, pps);
+  return `${clipWidthLadder(widthPx)}${widthPx >= HANDLES_MIN_PX ? "+handles" : ""}`;
+}
+
 // fallow-ignore-next-line complexity
 export const TimelineClip = memo(function TimelineClip({
   el,
@@ -71,12 +87,12 @@ export const TimelineClip = memo(function TimelineClip({
   onContextMenu,
   children,
 }: TimelineClipProps) {
-  const widthPx = Math.max(el.duration * pps, 4);
+  const widthPx = clipWidthPx(el, pps);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
   const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;
   const isAudioClip = isAudioTimelineElement(el);
   const ladder = clipWidthLadder(widthPx);
-  const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);
+  const showHandles = handleOpacity > 0.01 && (widthPx >= HANDLES_MIN_PX || isSelected);
   const showLabel = !isAudioClip || ladder === "labeled";
   const showDefaultText = !hasCustomContent && ladder === "labeled";
   const startLabel = el.start.toFixed(1);
diff --git a/packages/studio/src/player/components/TimelineLaneClip.tsx b/packages/studio/src/player/components/TimelineLaneClip.tsx
new file mode 100644
index 00000000000..81f55b44d6f
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineLaneClip.tsx
@@ -0,0 +1,127 @@
+import { memo, type CSSProperties, type RefObject } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import type { ThumbnailPriority } from "../lib/thumbnailScheduler";
+import { TimelineClip, clipZoomKey } from "./TimelineClip";
+import { createClipGestureHandlers, type ClipGestureDeps } from "./timelineClipGestureHandlers";
+import { renderClipChildren } from "./timelineClipChildren";
+import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
+import type { TrackVisualStyle } from "./timelineIcons";
+import { CLIP_Y } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineProps } from "./TimelineTypes";
+
+/** The lane's callbacks as of its last render, read when a clip is pressed rather than drawn. */
+export interface TimelineLaneClipActions {
+  gestures: ClipGestureDeps;
+  setHoveredClip(key: string | null): void;
+  onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
+  onDrillDown?: (element: TimelineElement) => void;
+}
+
+interface TimelineLaneClipProps {
+  el: TimelineElement;
+  previewElement: TimelineElement;
+  elementKey: string;
+  capabilities: TimelineEditCapabilities;
+  pps: number;
+  passengerStyle?: CSSProperties;
+  clipBarHeight?: number;
+  isSelected: boolean;
+  isHovered: boolean;
+  isActive: boolean;
+  tabIndex: 0 | -1;
+  priority: ThumbnailPriority;
+  rich: boolean;
+  theme: TimelineTheme;
+  clipStyle: TrackVisualStyle;
+  renderClipContent: TimelineProps["renderClipContent"];
+  renderClipOverlay: TimelineProps["renderClipOverlay"];
+  actions: RefObject<TimelineLaneClipActions>;
+}
+
+const sameCapabilities = (a: TimelineEditCapabilities, b: TimelineEditCapabilities) =>
+  a.canMove === b.canMove &&
+  a.canTrimStart === b.canTrimStart &&
+  a.canTrimEnd === b.canTrimEnd &&
+  a.readOnly === b.readOnly;
+
+const zoomKey = (p: TimelineLaneClipProps) =>
+  clipZoomKey(p.previewElement, p.pps, p.isSelected || p.isHovered);
+
+/** A zoom step re-renders only the clips whose drawing it changes. */
+function sameClip(prev: TimelineLaneClipProps, next: TimelineLaneClipProps): boolean {
+  for (const key of Object.keys(next) as (keyof TimelineLaneClipProps)[]) {
+    if (key === "pps" || key === "capabilities" || prev[key] === next[key]) continue;
+    return false;
+  }
+  return sameCapabilities(prev.capabilities, next.capabilities) && zoomKey(prev) === zoomKey(next);
+}
+
+/** One clip bar in a lane; its handlers read the lane's current callbacks when pressed. */
+export const TimelineLaneClip = memo(function TimelineLaneClip({
+  el,
+  previewElement,
+  elementKey,
+  capabilities,
+  pps,
+  passengerStyle,
+  clipBarHeight,
+  isSelected,
+  isHovered,
+  isActive,
+  tabIndex,
+  priority,
+  rich,
+  theme,
+  clipStyle,
+  renderClipContent,
+  renderClipOverlay,
+  actions,
+}: TimelineLaneClipProps) {
+  const gestures = () =>
+    createClipGestureHandlers(
+      el,
+      elementKey,
+      previewElement,
+      capabilities,
+      actions.current.gestures,
+    );
+  const isComposition = !!el.compositionSrc;
+  return (
+    <TimelineClip
+      onContextMenu={(e: React.MouseEvent) => {
+        e.preventDefault();
+        actions.current.onContextMenuClip?.(e, el);
+      }}
+      el={previewElement}
+      pps={pps}
+      passengerStyle={passengerStyle}
+      clipY={CLIP_Y}
+      clipHeight={clipBarHeight}
+      isSelected={isSelected}
+      isHovered={isHovered}
+      isDragging={false}
+      isActive={isActive}
+      hasCustomContent={!!renderClipContent}
+      capabilities={capabilities}
+      theme={theme}
+      isComposition={isComposition}
+      tabIndex={tabIndex}
+      onHoverStart={() => actions.current.setHoveredClip(elementKey)}
+      onHoverEnd={() => actions.current.setHoveredClip(null)}
+      onResizeStart={(edge, e) => gestures().onResizeStart(edge, e)}
+      onPointerDown={(e) => gestures().onPointerDown(e)}
+      onClick={(e) => gestures().onClick(e)}
+      onDoubleClick={(e) => {
+        e.stopPropagation();
+        if (actions.current.gestures.suppressClickRef.current) return;
+        if (isComposition) actions.current.onDrillDown?.(el);
+      }}
+    >
+      {renderClipChildren(previewElement, clipStyle, renderClipContent, renderClipOverlay, {
+        priority,
+        rich,
+      })}
+    </TimelineClip>
+  );
+}, sameClip);
diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx
index 4c3d5541aef..9fadb5506c9 100644
--- a/packages/studio/src/player/components/TimelineLanes.test.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx
@@ -89,8 +89,11 @@ interface RenderLanesOptions {
   renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];
   snapGuide?: { time: number; type: "beat" | "clip-edge" | "playhead" } | null;
   withoutSelectHandler?: boolean;
+  pps?: number;
 }
 
+const lanePps = (options: RenderLanesOptions) => options.pps ?? 100;
+
 const selectHandlerFor = (
   options: RenderLanesOptions,
   handler: (element: TimelineElement | null) => void,
@@ -102,12 +105,14 @@ function renderLanes(options: RenderLanesOptions = {}): {
   rerender: (next: RenderLanesOptions) => void;
   setSelectedElementId: ReturnType<typeof vi.fn>;
   onSelectElement: ReturnType<typeof vi.fn>;
+  onRazorSplit: ReturnType<typeof vi.fn>;
 } {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
   const setSelectedElementId = vi.fn();
   const onSelectElement = vi.fn();
+  const onRazorSplit = vi.fn();
   const render = (next: RenderLanesOptions) => {
     const elements = next.elements ?? [element("clip-a", TRACK_A)];
     const gsapAnimations = next.animations ?? new Map<string, GsapAnimation[]>();
@@ -124,7 +129,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
       usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
       root.render(
         <TimelineLanes
-          pps={100}
+          pps={lanePps(next)}
           contentOrigin={232}
           contentGutter={32}
           trackContentWidth={800}
@@ -186,14 +191,14 @@ function renderLanes(options: RenderLanesOptions = {}): {
           onResizeElement={vi.fn()}
           onMoveElement={vi.fn()}
           onSelectElement={selectHandlerFor(next, onSelectElement)}
-          onRazorSplit={vi.fn()}
+          onRazorSplit={onRazorSplit}
           onRazorSplitAll={vi.fn()}
         />,
       );
     });
   };
   render(options);
-  return { host, root, rerender: render, setSelectedElementId, onSelectElement };
+  return { host, root, rerender: render, setSelectedElementId, onSelectElement, onRazorSplit };
 }
 
 function visibilityLabels(host: HTMLElement): (string | null)[] {
@@ -630,3 +635,37 @@ describe("TimelineLanes transition seams", () => {
     act(() => view.root.unmount());
   });
 });
+
+describe("TimelineLanes clips during a zoom", () => {
+  afterEach(() => {
+    usePlayerStore.setState({ activeTool: "select" });
+  });
+
+  it("leaves a clip unrendered by a zoom step that does not change what it draws", () => {
+    const renderClipContent = vi.fn(() => null);
+    const clip = { ...element("clip-a", TRACK_A), start: 0, duration: 2 };
+    const view = renderLanes({ elements: [clip], renderClipContent, pps: 100 });
+    const drawn = renderClipContent.mock.calls.length;
+    // 200px to 220px: still a labelled clip with handles.
+    view.rerender({ elements: [clip], renderClipContent, pps: 110 });
+    expect(renderClipContent.mock.calls.length).toBe(drawn);
+    // 40px: the clip drops its label, so it draws again.
+    view.rerender({ elements: [clip], renderClipContent, pps: 20 });
+    expect(renderClipContent.mock.calls.length).toBeGreaterThan(drawn);
+    act(() => view.root.unmount());
+  });
+
+  it("splits with the razor at the time under the pointer at the current zoom", () => {
+    usePlayerStore.setState({ activeTool: "razor" });
+    const clip = { ...element("clip-a", TRACK_A), start: 0, duration: 2 };
+    const view = renderLanes({ elements: [clip], pps: 100 });
+    view.rerender({ elements: [clip], pps: 105 });
+    act(() => {
+      view.host
+        .querySelector('[data-el-id="clip-a"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true, clientX: 105 }));
+    });
+    expect(view.onRazorSplit).toHaveBeenCalledWith(expect.objectContaining({ id: "clip-a" }), 1);
+    act(() => view.root.unmount());
+  });
+});
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index 5027900a010..ceb4e3ddbf9 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -1,6 +1,6 @@
-import { Fragment, useId, useMemo, type CSSProperties } from "react";
+import { Fragment, useId, useMemo, useRef, type CSSProperties } from "react";
 import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
-import { TimelineClip } from "./TimelineClip";
+import { TimelineLaneClip, type TimelineLaneClipActions } from "./TimelineLaneClip";
 import { TimelineCompactDiamonds } from "./TimelineCompactDiamonds";
 import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { TimelineAutomationLaneSlot } from "./TimelineAutomationLaneSlot";
@@ -25,8 +25,7 @@ import { isMultiDragPassenger, multiDragPassengerOffsetPx } from "./timelineMult
 import { useTimelineMultiDragActorWindows } from "./useTimelineMultiDragActorWindows";
 import type { TimelineLanesProps } from "./timelineLaneProps";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
-import { createClipGestureHandlers } from "./timelineClipGestureHandlers";
-import { renderClipChildren, resolveClipRenderContext } from "./timelineClipChildren";
+import { resolveClipRenderContext } from "./timelineClipChildren";
 import { TimelineTrackRow } from "./TimelineTrackRow";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
 import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
@@ -144,6 +143,28 @@ export function TimelineLanes({
     onToggleRow: (row) => row.elementId && toggleClipExpandedTracked(row.elementId),
     onDrillDown,
   });
+  const clipActions = useRef<TimelineLaneClipActions>(null!);
+  clipActions.current = {
+    gestures: {
+      pps,
+      onResizeElement,
+      onMoveElement,
+      onRazorSplit,
+      onRazorSplitAll,
+      blockedClipRef,
+      suppressClickRef,
+      scrollRef,
+      setShowPopover,
+      setRangeSelection,
+      setResizingClip,
+      setDraggedClip,
+      setSelectedElementId,
+      onSelectElement,
+    },
+    setHoveredClip,
+    onContextMenuClip,
+    onDrillDown,
+  };
   return (
     <div
       role="treegrid"
@@ -383,7 +404,6 @@ export function TimelineLanes({
                       const capabilities = getClipCapabilities(el);
                       const isSelected =
                         selectedElementId === elementKey || selectedElementIds.has(elementKey);
-                      const isComposition = !!el.compositionSrc;
                       // Element identity stays stable across clip splices and reorders.
                       const clipKey = elementKey;
                       const isDraggingClip =
@@ -406,70 +426,30 @@ export function TimelineLanes({
                             multiDragPassengerOffsetPx(clipKey, pps, multiDragPreview),
                           )
                         : undefined;
-                      const clipGestures = createClipGestureHandlers(
-                        el,
-                        elementKey,
-                        previewElement,
-                        capabilities,
-                        {
-                          pps,
-                          onResizeElement,
-                          onMoveElement,
-                          onRazorSplit,
-                          onRazorSplitAll,
-                          blockedClipRef,
-                          suppressClickRef,
-                          scrollRef,
-                          setShowPopover,
-                          setRangeSelection,
-                          setResizingClip,
-                          setDraggedClip,
-                          setSelectedElementId,
-                          onSelectElement,
-                        },
-                      );
                       const clip = (
-                        <TimelineClip
+                        <TimelineLaneClip
                           key={clipKey}
-                          onContextMenu={(e: React.MouseEvent) => {
-                            e.preventDefault();
-                            onContextMenuClip?.(e, el);
-                          }}
-                          el={previewElement}
+                          el={el}
+                          previewElement={previewElement}
+                          elementKey={elementKey}
+                          capabilities={capabilities}
                           pps={pps}
                           passengerStyle={passengerStyle}
-                          clipY={CLIP_Y}
-                          clipHeight={clipBarHeight}
+                          clipBarHeight={clipBarHeight}
                           isSelected={isSelected}
                           isHovered={hoveredClip === clipKey}
-                          isDragging={false}
                           isActive={isTimelineClipActive(previewElement, currentTime)}
-                          hasCustomContent={!!renderClipContent}
-                          capabilities={capabilities}
-                          theme={theme}
-                          isComposition={isComposition}
                           tabIndex={
                             keyboard.rovingTargetId === timelineClipFocusId(elementKey) ? 0 : -1
                           }
-                          onHoverStart={() => setHoveredClip(clipKey)}
-                          onHoverEnd={() => setHoveredClip(null)}
-                          onResizeStart={clipGestures.onResizeStart}
-                          onPointerDown={clipGestures.onPointerDown}
-                          onClick={clipGestures.onClick}
-                          onDoubleClick={(e) => {
-                            e.stopPropagation();
-                            if (suppressClickRef.current) return;
-                            if (isComposition && onDrillDown) onDrillDown(el);
-                          }}
-                        >
-                          {renderClipChildren(
-                            previewElement,
-                            clipStyle,
-                            renderClipContent,
-                            renderClipOverlay,
-                            renderContext,
-                          )}
-                        </TimelineClip>
+                          priority={renderContext.priority}
+                          rich={renderContext.rich}
+                          theme={theme}
+                          clipStyle={clipStyle}
+                          renderClipContent={renderClipContent}
+                          renderClipOverlay={renderClipOverlay}
+                          actions={clipActions}
+                        />
                       );
                       const compactKeyframes = keyframeCache?.get(elementKey);
                       const compactDiamonds = !showsLanes && compactKeyframes && (

From 48fb920cd0a29d17fd9bfd94d810981ed863e804 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 11:41:57 -0400
Subject: [PATCH 06/26] refactor(studio): move at-rest waveform and thumbnail
 work to its own change

---
 .../src/player/components/AudioWaveform.tsx   | 93 +++++--------------
 .../player/components/VideoThumbnail.test.tsx | 47 ----------
 .../src/player/components/VideoThumbnail.tsx  | 11 +--
 .../src/player/components/timelineMotion.ts   | 46 ---------
 .../player/components/timelineShellMeta.tsx   |  2 -
 .../player/components/timelineZoomInput.ts    |  2 -
 6 files changed, 27 insertions(+), 174 deletions(-)
 delete mode 100644 packages/studio/src/player/components/timelineMotion.ts

diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 71706034b55..043f381be25 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -5,7 +5,6 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
-import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface AudioWaveformProps {
@@ -31,25 +30,6 @@ export const WAVEFORM_LAYER_Z = 10;
 
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
-/** A stretch of the clip as fractions of its width. */
-export type ClipSpan = { from: number; to: number };
-const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
-// Drawn past the viewport by this many widths each side, so a short scroll shows bars already drawn.
-const OVERSCAN_VIEWPORTS = 1;
-
-/** The part of the clip on screen, with overscan; a long clip never draws past it. */
-function visibleClipSpan(root: HTMLElement): ClipSpan {
-  const box = root.getBoundingClientRect();
-  if (box.width <= 0) return WHOLE_CLIP;
-  const scroller = root.closest("[data-timeline-scroll-viewport]");
-  const view = scroller?.getBoundingClientRect() ?? { left: 0, right: window.innerWidth };
-  const margin = (view.right - view.left) * OVERSCAN_VIEWPORTS;
-  const clamp = (x: number) => Math.max(0, Math.min(1, x));
-  const from = clamp((view.left - margin - box.left) / box.width);
-  const to = clamp((view.right + margin - box.left) / box.width);
-  return { from, to: Math.max(from, to) };
-}
-
 function paintWaveformBars(
   context: CanvasRenderingContext2D,
   bars: readonly BarGeometry[],
@@ -81,7 +61,6 @@ export function drawWaveformCanvas(
   trimStartFraction: number,
   trimEndFraction: number,
   fades: ClipFadeShape | null = null,
-  span: ClipSpan = WHOLE_CLIP,
 ) {
   const width = Math.max(1, canvas.clientWidth);
   const height = Math.max(1, canvas.clientHeight);
@@ -92,20 +71,19 @@ export function drawWaveformCanvas(
   if (!context) return;
   context.scale(scale, scale);
   context.clearRect(0, 0, width, height);
-  const trim = trimEndFraction - trimStartFraction;
   const amplitudes = decimatePeaks(
     peaks,
-    trimStartFraction + trim * span.from,
-    trimStartFraction + trim * span.to,
+    trimStartFraction,
+    trimEndFraction,
     Math.max(1, Math.ceil(width / BAR_STEP)),
   );
-  const clipFraction = (index: number) =>
-    span.from + ((index + 0.5) / amplitudes.length) * (span.to - span.from);
   const bars = amplitudes.map((amplitude, index) => ({
     x: (index * width) / amplitudes.length,
     width: Math.max(1, width / amplitudes.length),
     height: Math.max(3, amplitude * height),
-    gain: fades ? fadeGain(clipFraction(index) * fades.duration, fades.duration, fades) : 1,
+    gain: fades
+      ? fadeGain(((index + 0.5) / amplitudes.length) * fades.duration, fades.duration, fades)
+      : 1,
   }));
   const channelToken = muted ? "--timeline-waveform-muted-rgb" : "--timeline-waveform-bar-rgb";
   const waveformBarRgb = getComputedStyle(canvas).getPropertyValue(channelToken);
@@ -194,6 +172,7 @@ export const AudioWaveform = memo(function AudioWaveform({
 }: AudioWaveformProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const observerRef = useRef<ResizeObserver | null>(null);
   const cacheKey = waveformUrl ?? audioUrl;
   const request = useMemo(
     () => ({
@@ -220,42 +199,21 @@ export const AudioWaveform = memo(function AudioWaveform({
   const fades = useContext(ClipFadesContext);
   const draw = useCallback(() => {
     const canvas = canvasRef.current;
-    const root = rootRef.current;
-    if (!canvas || !root || !peaks) return;
-    const span = visibleClipSpan(root);
-    // Placed in fractions of the clip, so a zoom stretches the drawn bars with time until the redraw.
-    canvas.style.left = `${span.from * 100}%`;
-    canvas.style.width = `${(span.to - span.from) * 100}%`;
-    if (span.to <= span.from) return;
-    drawWaveformCanvas(
-      canvas,
-      peaks,
-      muted,
-      trimStartFraction ?? 0,
-      trimEndFraction ?? 1,
-      fades,
-      span,
-    );
+    if (!canvas || !peaks) return;
+    drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1, fades);
   }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
-  const drawRef = useRef(draw);
-  drawRef.current = draw;
-  useEffect(draw, [draw]);
 
-  // Redrawn when the clip resizes or the timeline comes to rest after a zoom or scroll, never
-  // per step: a step only stretches what is drawn.
-  useMountEffect(() => {
-    const root = rootRef.current;
-    const redrawAtRest = () => {
-      if (!isTimelineMoving()) drawRef.current();
-    };
-    const observer = root ? new ResizeObserver(redrawAtRest) : null;
-    if (root) observer?.observe(root);
-    const unsubscribe = subscribeTimelineMotion(redrawAtRest);
-    return () => {
-      observer?.disconnect();
-      unsubscribe();
-    };
-  });
+  const setCanvasRef = useCallback(
+    (canvas: HTMLCanvasElement | null) => {
+      observerRef.current?.disconnect();
+      canvasRef.current = canvas;
+      if (!canvas) return;
+      draw();
+      observerRef.current = new ResizeObserver(draw);
+      observerRef.current.observe(canvas);
+    },
+    [draw],
+  );
 
   useEffect(() => {
     const root = document.documentElement;
@@ -267,6 +225,8 @@ export const AudioWaveform = memo(function AudioWaveform({
     return () => observer.disconnect();
   }, [draw]);
 
+  useMountEffect(() => () => observerRef.current?.disconnect());
+
   useEffect(() => {
     const clip = rootRef.current?.closest(".timeline-clip");
     if (!(clip instanceof HTMLElement)) return;
@@ -279,14 +239,9 @@ export const AudioWaveform = memo(function AudioWaveform({
     <div ref={rootRef} className="absolute inset-0">
       <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
         <canvas
-          ref={canvasRef}
-          className="absolute bottom-0"
-          style={{
-            left: 0,
-            width: "100%",
-            top: labelInset,
-            height: `calc(100% - ${labelInset}px)`,
-          }}
+          ref={setCanvasRef}
+          className="absolute inset-x-0 bottom-0 w-full"
+          style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
         />
         {snapshot.status === "loading" && (
           <div
diff --git a/packages/studio/src/player/components/VideoThumbnail.test.tsx b/packages/studio/src/player/components/VideoThumbnail.test.tsx
index 3f1801f438d..4dcd72ca153 100644
--- a/packages/studio/src/player/components/VideoThumbnail.test.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.test.tsx
@@ -6,7 +6,6 @@ import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { VideoThumbnail } from "./VideoThumbnail";
-import { markTimelineMotion } from "./timelineMotion";
 
 vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
 
@@ -250,49 +249,3 @@ describe("VideoThumbnail", () => {
     expect(host.querySelector("img")).toBeNull();
   });
 });
-
-describe("VideoThumbnail during a zoom", () => {
-  beforeEach(() => {
-    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
-    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
-      value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
-      weight: 256,
-    });
-  });
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  const rest = () =>
-    act(async () => {
-      vi.runOnlyPendingTimers();
-      await Promise.resolve();
-    });
-
-  it("decodes a clip that scrolls in mid-zoom only once the timeline rests", async () => {
-    markTimelineMotion();
-    await render(440);
-    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
-    await rest();
-    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
-      expect.objectContaining({ frameCount: 1 }),
-      expect.any(AbortSignal),
-    );
-  });
-
-  it("keeps its filmstrip while the zoom resizes it, and decodes the new width at rest", async () => {
-    await render(440);
-    vi.mocked(decodeVideoThumbnail).mockClear();
-    await act(async () => {
-      markTimelineMotion();
-      reportResize(880, 40);
-      await Promise.resolve();
-    });
-    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
-    await rest();
-    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
-      expect.objectContaining({ frameCount: 16 }),
-      expect.any(AbortSignal),
-    );
-  });
-});
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 9f78b0f41e8..9d42c11421b 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -9,7 +9,6 @@ import {
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
-import { useValueAtRest } from "./timelineMotion";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -88,11 +87,8 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   priority = "visible",
 }: VideoThumbnailProps) {
   const [container, setContainerRef, watchGap] = useThumbnailStripSize();
-  // A zoom changes the width every step; decode the strip it settles on, not each step's.
-  const requestFrameCount = useValueAtRest(
-    quantizeThumbnailFrameCount(
-      computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
-    ),
+  const requestFrameCount = quantizeThumbnailFrameCount(
+    computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
   );
   const requestProps = useMemo(
     () => ({
@@ -114,8 +110,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  // A clip that scrolls in mid-zoom starts decoding once the timeline rests.
-  const measured = useValueAtRest(container.width > 0);
+  const measured = container.width > 0;
   const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
   const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
   const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
diff --git a/packages/studio/src/player/components/timelineMotion.ts b/packages/studio/src/player/components/timelineMotion.ts
deleted file mode 100644
index 2380f08340e..00000000000
--- a/packages/studio/src/player/components/timelineMotion.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { useState, useSyncExternalStore } from "react";
-
-/** How long the timeline must hold still, after its last zoom or scroll, to count as at rest. */
-const TIMELINE_REST_MS = 150;
-
-let moving = false;
-let restTimer: ReturnType<typeof setTimeout> | null = null;
-const listeners = new Set<() => void>();
-
-const emit = () => listeners.forEach((listener) => listener());
-
-/** A zoom or scroll step: work that only matters at rest (redraws, decodes) waits for it to end. */
-export function markTimelineMotion(): void {
-  if (!moving) {
-    moving = true;
-    emit();
-  }
-  if (restTimer) clearTimeout(restTimer);
-  restTimer = setTimeout(() => {
-    restTimer = null;
-    moving = false;
-    emit();
-  }, TIMELINE_REST_MS);
-}
-
-export function isTimelineMoving(): boolean {
-  return moving;
-}
-
-export function subscribeTimelineMotion(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-/** True while the timeline zooms or scrolls; re-renders only when that starts and when it rests. */
-function useTimelineMoving(): boolean {
-  return useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
-}
-
-/** `value` at rest; while the timeline moves, the value it had when it last rested. */
-export function useValueAtRest<T>(value: T): T {
-  const moving = useTimelineMoving();
-  const [held, setHeld] = useState(value);
-  if (!moving && !Object.is(held, value)) setHeld(value);
-  return moving ? held : value;
-}
diff --git a/packages/studio/src/player/components/timelineShellMeta.tsx b/packages/studio/src/player/components/timelineShellMeta.tsx
index 0b04e676953..fb8a6677ec7 100644
--- a/packages/studio/src/player/components/timelineShellMeta.tsx
+++ b/packages/studio/src/player/components/timelineShellMeta.tsx
@@ -10,7 +10,6 @@ import {
 } from "./timelineProviderStateBuilders";
 import { TimelineRazorGuideOverlay } from "./TimelineRazorInteraction";
 import { LABEL_COL_W } from "./timelineLayout";
-import { markTimelineMotion } from "./timelineMotion";
 import type { TimelineTheme } from "./timelineTheme";
 
 type ViewportHandlers = Pick<
@@ -74,7 +73,6 @@ export function buildTimelineShellMeta(input: TimelineShellMetaInputs): Timeline
       contentOrigin: input.contentOrigin,
       zoomMode: input.zoomMode,
       onScroll: (e) => {
-        markTimelineMotion();
         input.lastScrollLeftRef.current = e.currentTarget.scrollLeft;
         input.recordTimelineScroll(e.currentTarget);
         input.syncScrollViewport(e.currentTarget, true);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 0b957c24a81..baa27a08299 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -1,5 +1,4 @@
 import { usePlayerStore } from "../store/playerStore";
-import { markTimelineMotion } from "./timelineMotion";
 import {
   clampTimelineZoomPercent,
   getNextTimelineZoomPercent,
@@ -62,7 +61,6 @@ function flush() {
 
 function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
   pending = { percent, anchor, byPerson: byPerson || pending?.byPerson === true };
-  markTimelineMotion();
   if (!frame) frame = requestAnimationFrame(flush);
 }
 

From ba62650a04d53ef25481300d6ba55169626c016c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 11:43:53 -0400
Subject: [PATCH 07/26] perf(studio): draw waveforms and decode thumbnails when
 the timeline rests

Waveforms draw only the visible span of a clip.

A zoom or scroll step stretches what is drawn until the timeline rests.
---
 .../src/player/components/AudioWaveform.tsx   | 93 ++++++++++++++-----
 .../player/components/VideoThumbnail.test.tsx | 47 ++++++++++
 .../src/player/components/VideoThumbnail.tsx  | 11 ++-
 .../src/player/components/timelineMotion.ts   | 46 +++++++++
 .../player/components/timelineShellMeta.tsx   |  2 +
 .../player/components/timelineZoomInput.ts    |  2 +
 6 files changed, 174 insertions(+), 27 deletions(-)
 create mode 100644 packages/studio/src/player/components/timelineMotion.ts

diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 043f381be25..71706034b55 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -5,6 +5,7 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
+import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface AudioWaveformProps {
@@ -30,6 +31,25 @@ export const WAVEFORM_LAYER_Z = 10;
 
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
+/** A stretch of the clip as fractions of its width. */
+export type ClipSpan = { from: number; to: number };
+const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
+// Drawn past the viewport by this many widths each side, so a short scroll shows bars already drawn.
+const OVERSCAN_VIEWPORTS = 1;
+
+/** The part of the clip on screen, with overscan; a long clip never draws past it. */
+function visibleClipSpan(root: HTMLElement): ClipSpan {
+  const box = root.getBoundingClientRect();
+  if (box.width <= 0) return WHOLE_CLIP;
+  const scroller = root.closest("[data-timeline-scroll-viewport]");
+  const view = scroller?.getBoundingClientRect() ?? { left: 0, right: window.innerWidth };
+  const margin = (view.right - view.left) * OVERSCAN_VIEWPORTS;
+  const clamp = (x: number) => Math.max(0, Math.min(1, x));
+  const from = clamp((view.left - margin - box.left) / box.width);
+  const to = clamp((view.right + margin - box.left) / box.width);
+  return { from, to: Math.max(from, to) };
+}
+
 function paintWaveformBars(
   context: CanvasRenderingContext2D,
   bars: readonly BarGeometry[],
@@ -61,6 +81,7 @@ export function drawWaveformCanvas(
   trimStartFraction: number,
   trimEndFraction: number,
   fades: ClipFadeShape | null = null,
+  span: ClipSpan = WHOLE_CLIP,
 ) {
   const width = Math.max(1, canvas.clientWidth);
   const height = Math.max(1, canvas.clientHeight);
@@ -71,19 +92,20 @@ export function drawWaveformCanvas(
   if (!context) return;
   context.scale(scale, scale);
   context.clearRect(0, 0, width, height);
+  const trim = trimEndFraction - trimStartFraction;
   const amplitudes = decimatePeaks(
     peaks,
-    trimStartFraction,
-    trimEndFraction,
+    trimStartFraction + trim * span.from,
+    trimStartFraction + trim * span.to,
     Math.max(1, Math.ceil(width / BAR_STEP)),
   );
+  const clipFraction = (index: number) =>
+    span.from + ((index + 0.5) / amplitudes.length) * (span.to - span.from);
   const bars = amplitudes.map((amplitude, index) => ({
     x: (index * width) / amplitudes.length,
     width: Math.max(1, width / amplitudes.length),
     height: Math.max(3, amplitude * height),
-    gain: fades
-      ? fadeGain(((index + 0.5) / amplitudes.length) * fades.duration, fades.duration, fades)
-      : 1,
+    gain: fades ? fadeGain(clipFraction(index) * fades.duration, fades.duration, fades) : 1,
   }));
   const channelToken = muted ? "--timeline-waveform-muted-rgb" : "--timeline-waveform-bar-rgb";
   const waveformBarRgb = getComputedStyle(canvas).getPropertyValue(channelToken);
@@ -172,7 +194,6 @@ export const AudioWaveform = memo(function AudioWaveform({
 }: AudioWaveformProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const observerRef = useRef<ResizeObserver | null>(null);
   const cacheKey = waveformUrl ?? audioUrl;
   const request = useMemo(
     () => ({
@@ -199,21 +220,42 @@ export const AudioWaveform = memo(function AudioWaveform({
   const fades = useContext(ClipFadesContext);
   const draw = useCallback(() => {
     const canvas = canvasRef.current;
-    if (!canvas || !peaks) return;
-    drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1, fades);
+    const root = rootRef.current;
+    if (!canvas || !root || !peaks) return;
+    const span = visibleClipSpan(root);
+    // Placed in fractions of the clip, so a zoom stretches the drawn bars with time until the redraw.
+    canvas.style.left = `${span.from * 100}%`;
+    canvas.style.width = `${(span.to - span.from) * 100}%`;
+    if (span.to <= span.from) return;
+    drawWaveformCanvas(
+      canvas,
+      peaks,
+      muted,
+      trimStartFraction ?? 0,
+      trimEndFraction ?? 1,
+      fades,
+      span,
+    );
   }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
+  const drawRef = useRef(draw);
+  drawRef.current = draw;
+  useEffect(draw, [draw]);
 
-  const setCanvasRef = useCallback(
-    (canvas: HTMLCanvasElement | null) => {
-      observerRef.current?.disconnect();
-      canvasRef.current = canvas;
-      if (!canvas) return;
-      draw();
-      observerRef.current = new ResizeObserver(draw);
-      observerRef.current.observe(canvas);
-    },
-    [draw],
-  );
+  // Redrawn when the clip resizes or the timeline comes to rest after a zoom or scroll, never
+  // per step: a step only stretches what is drawn.
+  useMountEffect(() => {
+    const root = rootRef.current;
+    const redrawAtRest = () => {
+      if (!isTimelineMoving()) drawRef.current();
+    };
+    const observer = root ? new ResizeObserver(redrawAtRest) : null;
+    if (root) observer?.observe(root);
+    const unsubscribe = subscribeTimelineMotion(redrawAtRest);
+    return () => {
+      observer?.disconnect();
+      unsubscribe();
+    };
+  });
 
   useEffect(() => {
     const root = document.documentElement;
@@ -225,8 +267,6 @@ export const AudioWaveform = memo(function AudioWaveform({
     return () => observer.disconnect();
   }, [draw]);
 
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
   useEffect(() => {
     const clip = rootRef.current?.closest(".timeline-clip");
     if (!(clip instanceof HTMLElement)) return;
@@ -239,9 +279,14 @@ export const AudioWaveform = memo(function AudioWaveform({
     <div ref={rootRef} className="absolute inset-0">
       <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
         <canvas
-          ref={setCanvasRef}
-          className="absolute inset-x-0 bottom-0 w-full"
-          style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
+          ref={canvasRef}
+          className="absolute bottom-0"
+          style={{
+            left: 0,
+            width: "100%",
+            top: labelInset,
+            height: `calc(100% - ${labelInset}px)`,
+          }}
         />
         {snapshot.status === "loading" && (
           <div
diff --git a/packages/studio/src/player/components/VideoThumbnail.test.tsx b/packages/studio/src/player/components/VideoThumbnail.test.tsx
index 4dcd72ca153..3f1801f438d 100644
--- a/packages/studio/src/player/components/VideoThumbnail.test.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.test.tsx
@@ -6,6 +6,7 @@ import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { VideoThumbnail } from "./VideoThumbnail";
+import { markTimelineMotion } from "./timelineMotion";
 
 vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
 
@@ -249,3 +250,49 @@ describe("VideoThumbnail", () => {
     expect(host.querySelector("img")).toBeNull();
   });
 });
+
+describe("VideoThumbnail during a zoom", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+      weight: 256,
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const rest = () =>
+    act(async () => {
+      vi.runOnlyPendingTimers();
+      await Promise.resolve();
+    });
+
+  it("decodes a clip that scrolls in mid-zoom only once the timeline rests", async () => {
+    markTimelineMotion();
+    await render(440);
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 1 }),
+      expect.any(AbortSignal),
+    );
+  });
+
+  it("keeps its filmstrip while the zoom resizes it, and decodes the new width at rest", async () => {
+    await render(440);
+    vi.mocked(decodeVideoThumbnail).mockClear();
+    await act(async () => {
+      markTimelineMotion();
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 16 }),
+      expect.any(AbortSignal),
+    );
+  });
+});
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 9d42c11421b..9f78b0f41e8 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -9,6 +9,7 @@ import {
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
+import { useValueAtRest } from "./timelineMotion";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -87,8 +88,11 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   priority = "visible",
 }: VideoThumbnailProps) {
   const [container, setContainerRef, watchGap] = useThumbnailStripSize();
-  const requestFrameCount = quantizeThumbnailFrameCount(
-    computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+  // A zoom changes the width every step; decode the strip it settles on, not each step's.
+  const requestFrameCount = useValueAtRest(
+    quantizeThumbnailFrameCount(
+      computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+    ),
   );
   const requestProps = useMemo(
     () => ({
@@ -110,7 +114,8 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  const measured = container.width > 0;
+  // A clip that scrolls in mid-zoom starts decoding once the timeline rests.
+  const measured = useValueAtRest(container.width > 0);
   const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
   const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
   const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
diff --git a/packages/studio/src/player/components/timelineMotion.ts b/packages/studio/src/player/components/timelineMotion.ts
new file mode 100644
index 00000000000..2380f08340e
--- /dev/null
+++ b/packages/studio/src/player/components/timelineMotion.ts
@@ -0,0 +1,46 @@
+import { useState, useSyncExternalStore } from "react";
+
+/** How long the timeline must hold still, after its last zoom or scroll, to count as at rest. */
+const TIMELINE_REST_MS = 150;
+
+let moving = false;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+const listeners = new Set<() => void>();
+
+const emit = () => listeners.forEach((listener) => listener());
+
+/** A zoom or scroll step: work that only matters at rest (redraws, decodes) waits for it to end. */
+export function markTimelineMotion(): void {
+  if (!moving) {
+    moving = true;
+    emit();
+  }
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = setTimeout(() => {
+    restTimer = null;
+    moving = false;
+    emit();
+  }, TIMELINE_REST_MS);
+}
+
+export function isTimelineMoving(): boolean {
+  return moving;
+}
+
+export function subscribeTimelineMotion(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** True while the timeline zooms or scrolls; re-renders only when that starts and when it rests. */
+function useTimelineMoving(): boolean {
+  return useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
+}
+
+/** `value` at rest; while the timeline moves, the value it had when it last rested. */
+export function useValueAtRest<T>(value: T): T {
+  const moving = useTimelineMoving();
+  const [held, setHeld] = useState(value);
+  if (!moving && !Object.is(held, value)) setHeld(value);
+  return moving ? held : value;
+}
diff --git a/packages/studio/src/player/components/timelineShellMeta.tsx b/packages/studio/src/player/components/timelineShellMeta.tsx
index fb8a6677ec7..0b04e676953 100644
--- a/packages/studio/src/player/components/timelineShellMeta.tsx
+++ b/packages/studio/src/player/components/timelineShellMeta.tsx
@@ -10,6 +10,7 @@ import {
 } from "./timelineProviderStateBuilders";
 import { TimelineRazorGuideOverlay } from "./TimelineRazorInteraction";
 import { LABEL_COL_W } from "./timelineLayout";
+import { markTimelineMotion } from "./timelineMotion";
 import type { TimelineTheme } from "./timelineTheme";
 
 type ViewportHandlers = Pick<
@@ -73,6 +74,7 @@ export function buildTimelineShellMeta(input: TimelineShellMetaInputs): Timeline
       contentOrigin: input.contentOrigin,
       zoomMode: input.zoomMode,
       onScroll: (e) => {
+        markTimelineMotion();
         input.lastScrollLeftRef.current = e.currentTarget.scrollLeft;
         input.recordTimelineScroll(e.currentTarget);
         input.syncScrollViewport(e.currentTarget, true);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index baa27a08299..0b957c24a81 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -1,4 +1,5 @@
 import { usePlayerStore } from "../store/playerStore";
+import { markTimelineMotion } from "./timelineMotion";
 import {
   clampTimelineZoomPercent,
   getNextTimelineZoomPercent,
@@ -61,6 +62,7 @@ function flush() {
 
 function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
   pending = { percent, anchor, byPerson: byPerson || pending?.byPerson === true };
+  markTimelineMotion();
   if (!frame) frame = requestAnimationFrame(flush);
 }
 

From d688e40dc60b782e01d29f7c3c02ebc4319bcc87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 11:48:48 -0400
Subject: [PATCH 08/26] test(studio): fade handles measure the clip only while
 they show

---
 .../src/player/components/TimelineClipFades.test.tsx  | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/studio/src/player/components/TimelineClipFades.test.tsx b/packages/studio/src/player/components/TimelineClipFades.test.tsx
index 37936b3d972..8137d465e21 100644
--- a/packages/studio/src/player/components/TimelineClipFades.test.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.test.tsx
@@ -129,6 +129,17 @@ describe("TimelineClipFades", () => {
     act(() => root.unmount());
   });
 
+  it("measures the clip only while its handles show, so a zoom step forces no layout", () => {
+    const measure = vi.spyOn(window, "getComputedStyle");
+    const { rerender } = render(clip, { showHandles: false });
+    rerender({ ...clip, duration: 11 });
+    expect(measure).not.toHaveBeenCalled();
+    act(() => mounted[0]?.unmount());
+    render(clip, { showHandles: true });
+    expect(measure).toHaveBeenCalled();
+    measure.mockRestore();
+  });
+
   it("renders nothing for a clip without fades when the handles are hidden", () => {
     const { host, root } = render(
       { ...clip, fadeIn: undefined, fadeOut: undefined },

From 14297e5524a139951a85acdec0392646f9e21172 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 11:52:06 -0400
Subject: [PATCH 09/26] test(studio): waveforms draw their visible span and
 redraw at rest

---
 .../player/components/AudioWaveform.test.tsx  | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index 89f6a8e813a..edcdd654a17 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -12,6 +12,7 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
 }));
 
 import { AudioWaveform, drawWaveformCanvas } from "./AudioWaveform";
+import { markTimelineMotion } from "./timelineMotion";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -51,6 +52,51 @@ describe("AudioWaveform", () => {
     ]);
   });
 
+  it("draws only the span of the clip it is given", () => {
+    const { canvas, fills } = recordingCanvas();
+    // The clip's second half holds the loud peak only.
+    drawWaveformCanvas(canvas, [0.25, 1], false, 0, 1, null, { from: 0.5, to: 1 });
+    const bars = fills.filter(([, , y, , height]) => !(y === 18 && height === 2));
+    expect(bars.map(([, , y, , height]) => [y, height])).toEqual([
+      [0, 20],
+      [0, 20],
+    ]);
+  });
+
+  it("redraws when the timeline comes to rest, not at each zoom step", () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    leaseSpy.mockImplementation(
+      () => ({ status: "ready", value: { kind: "waveform", peaks: [0.5, 1] } }) as never,
+    );
+    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <AudioWaveform
+          audioUrl="/media/voice.wav"
+          label=""
+          labelColor="#fff"
+          projectId="project-a"
+          sessionEpoch={1}
+          priority="visible"
+        />,
+      );
+    });
+    const drawn = getContext.mock.calls.length;
+    expect(drawn).toBeGreaterThan(0);
+    act(() => markTimelineMotion());
+    expect(getContext.mock.calls.length).toBe(drawn);
+    act(() => vi.runOnlyPendingTimers());
+    expect(getContext.mock.calls.length).toBe(drawn + 1);
+    act(() => root.unmount());
+    getContext.mockRestore();
+    leaseSpy.mockReset();
+    leaseSpy.mockImplementation(() => ({ status: "loading" as const }));
+    vi.useRealTimers();
+  });
+
   it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
     const { canvas, fills } = recordingCanvas();
     // A 1 s fade-in on a 2 s clip: the first bar's centre (0.5 s) plays at half gain.

From 7c485b4942534b94e418a5469b6875d0ee9c7694 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 12:11:23 -0400
Subject: [PATCH 10/26] feat(studio): export currentTimelineRange, the inverse
 of zoomTimelineToRange

---
 packages/studio/src/index.ts                  |  2 +-
 .../components/timelineZoomInput.test.ts      | 24 +++++++++++++++++++
 .../player/components/timelineZoomInput.ts    | 12 ++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 3b4262d4c1e..211061a3530 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -63,7 +63,7 @@ export {
 export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
 export type { TimelineTheme } from "./player/components/timelineTheme";
 export { TRACK_H } from "./player/components/timelineLayout";
-export { zoomTimelineToRange } from "./player/components/timelineZoomInput";
+export { currentTimelineRange, zoomTimelineToRange } from "./player/components/timelineZoomInput";
 export type { TimelineTrackPadding } from "./player/components/timelineLayout";
 export { displayTrackOrder } from "./player/components/useTimelineTrackDerivations";
 export { fadeHandleBoxes } from "./player/components/timelineClipFadeGeometry";
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 2e743cccf16..616c9168190 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -3,6 +3,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
 import {
+  currentTimelineRange,
   requestTimelineZoom,
   setTimelineZoomViewport,
   takeTimelineZoomAnchor,
@@ -126,6 +127,29 @@ describe("zoomTimelineToRange", () => {
   });
 });
 
+describe("currentTimelineRange", () => {
+  it("reads back the range zoomTimelineToRange filled", () => {
+    const scroll = document.createElement("div");
+    Object.defineProperties(scroll, {
+      clientWidth: { value: 1080 },
+      scrollLeft: { value: 0, writable: true },
+    });
+    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+    zoomTimelineToRange(100, 150, { smooth: false });
+    vi.advanceTimersToNextFrame();
+    // The timeline lays the anchor out: 100 s at 20 px/s lands at the left margin, 56px in.
+    const anchor = takeTimelineZoomAnchor()!;
+    scroll.scrollLeft = anchor.time * 20 + 32 - anchor.x;
+    const range = currentTimelineRange()!;
+    expect(range.start).toBeCloseTo(100);
+    expect(range.end).toBeCloseTo(150);
+  });
+
+  it("is null with no timeline mounted", () => {
+    expect(currentTimelineRange()).toBeNull();
+  });
+});
+
 describe("zoomTimelineStep", () => {
   function viewport(scrollLeft: number) {
     const scroll = document.createElement("div");
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index baa27a08299..5a989910bc6 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -93,6 +93,18 @@ export function setTimelineZoomViewport(next: TimelineZoomViewport | null): void
 const reducedMotion = () =>
   typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
 
+/** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
+export function currentTimelineRange(): { start: number; end: number } | null {
+  const view = viewport;
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  if (!view || !(fitPps > 0)) return null;
+  const pps = (fitPps * currentTimelineZoomPercent()) / 100;
+  const x = view.contentOrigin + RANGE_MARGIN_PX;
+  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
+  const start = (view.scroll.scrollLeft + x - view.contentOrigin) / pps;
+  return { start, end: start + width / pps };
+}
+
 /**
  * Zooms and scrolls so `start`..`end` (seconds) fills the timeline's width, easing there unless
  * `smooth` is false or the person prefers reduced motion. Resolves once the last step is laid

From 94b4917ec0f0f6dfec497817b8183207735cd62d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 12:47:33 -0400
Subject: [PATCH 11/26] perf(studio): zoom gestures scale the drawn timeline
 and lay it out once at rest

No layout or render per gesture frame; past 0.67x or 2x the preview is laid out and continues.
---
 .../player/components/TimelineGroupRow.tsx    |   1 +
 .../src/player/components/TimelineLanes.tsx   |   1 +
 .../src/player/components/TimelineRuler.tsx   |   2 +
 .../components/timelineZoomInput.test.ts      | 146 ++++++------
 .../player/components/timelineZoomInput.ts    | 209 ++++++++++++++----
 .../components/useTimelinePlayhead.test.tsx   |   2 +
 .../player/components/useTimelinePlayhead.ts  |  25 ++-
 7 files changed, 278 insertions(+), 108 deletions(-)

diff --git a/packages/studio/src/player/components/TimelineGroupRow.tsx b/packages/studio/src/player/components/TimelineGroupRow.tsx
index 3ed097eed04..a12bef8dfbd 100644
--- a/packages/studio/src/player/components/TimelineGroupRow.tsx
+++ b/packages/studio/src/player/components/TimelineGroupRow.tsx
@@ -201,6 +201,7 @@ export function TimelineGroupRow({
         // from x=0.
         <div
           role="gridcell"
+          data-timeline-zoom-scale=""
           aria-colindex={2}
           style={{ width: trackContentWidth, marginLeft: contentGutter }}
           className="relative"
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index ceb4e3ddbf9..fa8a2ff10d3 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -352,6 +352,7 @@ export function TimelineLanes({
               <div
                 role="gridcell"
                 aria-colindex={2}
+                data-timeline-zoom-scale=""
                 style={{
                   width: trackContentWidth,
                   marginLeft: contentGutter, // room for a 0% diamond left of t=0
diff --git a/packages/studio/src/player/components/TimelineRuler.tsx b/packages/studio/src/player/components/TimelineRuler.tsx
index 0f2a7bcd716..5d944c5c8dd 100644
--- a/packages/studio/src/player/components/TimelineRuler.tsx
+++ b/packages/studio/src/player/components/TimelineRuler.tsx
@@ -107,6 +107,7 @@ export const TimelineRuler = memo(function TimelineRuler({
       {/* Background SVG — beat lines only; major-tick gridlines removed so only
           the ruler's own small ticks mark intervals (no full-height lines). */}
       <svg
+        data-timeline-zoom-scale=""
         className="absolute pointer-events-none"
         style={{ left: contentOrigin, width: trackContentWidth, zIndex: 0 }}
         height={totalH}
@@ -152,6 +153,7 @@ export const TimelineRuler = memo(function TimelineRuler({
         {/* Breathing pad before 00:00 is folded into contentOrigin (see
             Timeline.tsx: GUTTER + TRACKS_LEFT_PAD), so no separate pad div. */}
         <div
+          data-timeline-zoom-scale=""
           className="relative overflow-hidden"
           style={{
             height: RULER_H,
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 616c9168190..354bb61a80d 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -4,9 +4,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
 import {
   currentTimelineRange,
+  currentTimelineZoomPercent,
   requestTimelineZoom,
   setTimelineZoomViewport,
   takeTimelineZoomAnchor,
+  timelineZoomMapping,
   zoomTimelineStep,
   zoomTimelineToRange,
 } from "./timelineZoomInput";
@@ -27,74 +29,105 @@ beforeEach(() => {
     timelineFitPps: 10,
     timelinePps: 10,
     userZoomCount: 0,
+    currentTime: 0,
   });
 });
 afterEach(() => {
-  // Run out any ease and pending write, so the next test starts with nothing scheduled.
+  // Run out any ease, preview and rest, so the next test starts with nothing scheduled.
   for (let i = 0; i < 40; i++) vi.advanceTimersToNextFrame();
   setTimelineZoomViewport(null);
   takeTimelineZoomAnchor();
   vi.useRealTimers();
 });
 
+/** A 1080px timeline viewport with 32px of track headers, holding one scaled row. */
+function viewport(scrollLeft = 0) {
+  const scroll = document.createElement("div");
+  Object.defineProperties(scroll, {
+    clientWidth: { value: 1080 },
+    scrollWidth: { value: 20_000 },
+    scrollLeft: { value: scrollLeft, writable: true },
+  });
+  const row = scroll.appendChild(document.createElement("div"));
+  row.setAttribute("data-timeline-zoom-scale", "");
+  setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+  return { scroll, row };
+}
+
+/** Where `time` lands on screen once the committed zoom is laid out. */
+const laidOutX = (time: number) => {
+  const anchor = takeTimelineZoomAnchor();
+  return anchor && anchor.x + (time - anchor.time) * usePlayerStore.getState().timelinePps;
+};
+
 describe("requestTimelineZoom", () => {
-  it("writes the store once per frame with the last zoom asked for", () => {
+  it("scales the drawn rows during a gesture and lays the zoom out once it rests", () => {
+    const { row } = viewport();
     const writes = vi.fn();
     const unsubscribe = usePlayerStore.subscribe(writes);
-    requestTimelineZoom(150);
-    requestTimelineZoom(200, { time: 4, x: 100 });
-    requestTimelineZoom(300, { time: 5, x: 120 });
-    expect(writes).not.toHaveBeenCalled();
+    requestTimelineZoom(120, { time: 4, x: 100 });
+    requestTimelineZoom(150, { time: 4, x: 100 });
     vi.advanceTimersToNextFrame();
+    expect(writes).not.toHaveBeenCalled();
+    expect(currentTimelineZoomPercent()).toBe(150);
+    // 4 s stays at 100px: 32 + 4 * 15 - left = 100, left = -8 clamps to 0, translated by 0.
+    expect(row.style.transform).toBe("translateX(0px) scaleX(1.5)");
+    vi.advanceTimersByTime(150);
     unsubscribe();
     expect(writes).toHaveBeenCalledTimes(1);
     expect(usePlayerStore.getState()).toMatchObject({
       zoomMode: "manual",
-      manualZoomPercent: 300,
-      timelinePps: 30,
+      manualZoomPercent: 150,
+      timelinePps: 15,
       userZoomCount: 1,
     });
-    expect(takeTimelineZoomAnchor()).toEqual({ time: 5, x: 120 });
-    expect(takeTimelineZoomAnchor()).toBeNull();
+    expect(row.style.transform).toBe("");
+  });
+
+  it("keeps the time under the pointer while previewing, then lays it out there", () => {
+    const { scroll, row } = viewport(400);
+    // 432px in: (400 + 432 - 32) / 10 = 80 s.
+    requestTimelineZoom(150, { time: 80, x: 432 });
+    vi.advanceTimersToNextFrame();
+    const mapping = timelineZoomMapping(10, 32);
+    expect(mapping.pps).toBe(15);
+    expect(mapping.contentOrigin + 80 * mapping.pps - scroll.scrollLeft).toBeCloseTo(432);
+    expect(row.style.transform).toContain("scaleX(1.5)");
+    vi.advanceTimersByTime(150);
+    expect(laidOutX(80)).toBeCloseTo(432);
+  });
+
+  it("lays the zoom out mid-gesture once the preview has scaled too far", () => {
+    viewport();
+    requestTimelineZoom(300);
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(30);
   });
 });
 
 describe("zoomTimelineToRange", () => {
-  function viewport(clientWidth: number, scrollLeft = 0) {
-    const scroll = document.createElement("div");
-    Object.defineProperties(scroll, {
-      clientWidth: { value: clientWidth },
-      scrollLeft: { value: scrollLeft, writable: true },
-    });
-    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
-  }
-
   it("fills the width with the range and puts its start at the left margin", () => {
-    viewport(1080);
-    zoomTimelineToRange(100, 150, { smooth: false });
-    vi.advanceTimersToNextFrame();
+    viewport();
+    void zoomTimelineToRange(100, 150, { smooth: false });
     // 1080 - (32 + 24) - 24 = 1000px for 50s is 20 pps.
     expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
-    expect(takeTimelineZoomAnchor()).toEqual({ time: 100, x: 56 });
+    expect(laidOutX(100)).toBeCloseTo(56);
   });
 
   it("eases there over several frames and ends exactly on the range", () => {
-    viewport(1080);
-    zoomTimelineToRange(10, 20);
+    viewport();
+    void zoomTimelineToRange(10, 20);
     vi.advanceTimersToNextFrame();
     vi.advanceTimersToNextFrame();
-    const midway = usePlayerStore.getState().timelinePps;
-    expect(midway).toBeGreaterThan(10);
-    expect(midway).toBeLessThan(100);
+    expect(currentTimelineZoomPercent()).toBeGreaterThan(100);
+    expect(currentTimelineZoomPercent()).toBeLessThan(1000);
     for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
     expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
-    const anchor = takeTimelineZoomAnchor();
-    // The range's start lands at the left margin, 32 + 24 px in.
-    expect(anchor && anchor.x + (10 - anchor.time) * 100).toBeCloseTo(56);
+    expect(laidOutX(10)).toBeCloseTo(56);
   });
 
   it("stops easing when a person zooms during it, and says it was cancelled", async () => {
-    viewport(1080);
+    viewport();
     const result = zoomTimelineToRange(10, 20);
     vi.advanceTimersToNextFrame();
     vi.advanceTimersToNextFrame();
@@ -105,7 +138,7 @@ describe("zoomTimelineToRange", () => {
   });
 
   it("resolves done once the range is laid out, without counting as a person's zoom", async () => {
-    viewport(1080);
+    const { row } = viewport();
     let settled: string | null = null;
     void zoomTimelineToRange(10, 20).then((r) => (settled = r));
     for (let i = 0; i < 30 && settled === null; i++) {
@@ -115,10 +148,11 @@ describe("zoomTimelineToRange", () => {
     expect(settled).toBe("done");
     expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
     expect(usePlayerStore.getState().userZoomCount).toBe(0);
+    expect(row.style.transform).toBe("");
   });
 
   it("cancels when the caller aborts", async () => {
-    viewport(1080);
+    viewport();
     const abort = new AbortController();
     const result = zoomTimelineToRange(10, 20, { signal: abort.signal });
     vi.advanceTimersToNextFrame();
@@ -129,46 +163,34 @@ describe("zoomTimelineToRange", () => {
 
 describe("currentTimelineRange", () => {
   it("reads back the range zoomTimelineToRange filled", () => {
-    const scroll = document.createElement("div");
-    Object.defineProperties(scroll, {
-      clientWidth: { value: 1080 },
-      scrollLeft: { value: 0, writable: true },
-    });
-    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
-    zoomTimelineToRange(100, 150, { smooth: false });
-    vi.advanceTimersToNextFrame();
-    // The timeline lays the anchor out: 100 s at 20 px/s lands at the left margin, 56px in.
-    const anchor = takeTimelineZoomAnchor()!;
-    scroll.scrollLeft = anchor.time * 20 + 32 - anchor.x;
+    viewport();
+    void zoomTimelineToRange(100, 150, { smooth: false });
     const range = currentTimelineRange()!;
     expect(range.start).toBeCloseTo(100);
     expect(range.end).toBeCloseTo(150);
   });
 
+  it("reads the range a gesture shows before it is laid out", () => {
+    viewport();
+    requestTimelineZoom(150, { time: 0, x: 32 });
+    const range = currentTimelineRange()!;
+    // 1000px between the margins at 15 px/s, from 24px in.
+    expect(range.start).toBeCloseTo(24 / 15);
+    expect(range.end - range.start).toBeCloseTo(1000 / 15);
+  });
+
   it("is null with no timeline mounted", () => {
     expect(currentTimelineRange()).toBeNull();
   });
 });
 
 describe("zoomTimelineStep", () => {
-  function viewport(scrollLeft: number) {
-    const scroll = document.createElement("div");
-    Object.defineProperties(scroll, {
-      clientWidth: { value: 1080 },
-      scrollLeft: { value: scrollLeft, writable: true },
-    });
-    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
-  }
   const run = () => {
     for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
   };
-  const screenX = (time: number) => {
-    const anchor = takeTimelineZoomAnchor();
-    return anchor && anchor.x + (time - anchor.time) * usePlayerStore.getState().timelinePps;
-  };
 
   it("counts as a person's zoom", () => {
-    viewport(0);
+    viewport();
     zoomTimelineStep("in");
     run();
     expect(usePlayerStore.getState().userZoomCount).toBeGreaterThan(0);
@@ -176,20 +198,20 @@ describe("zoomTimelineStep", () => {
 
   it("doubles the scale and keeps an on-screen playhead where it is", () => {
     usePlayerStore.setState({ currentTime: 40 });
-    viewport(0);
+    viewport();
     // At 10 pps the playhead sits at 32 + 400 = 432px.
     zoomTimelineStep("in");
     run();
     expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
-    expect(screenX(40)).toBeCloseTo(432);
+    expect(laidOutX(40)).toBeCloseTo(432);
   });
 
   it("centres an off-screen playhead", () => {
     usePlayerStore.setState({ currentTime: 300 });
-    viewport(0);
+    viewport();
     zoomTimelineStep("in");
     run();
     // The range's middle, 56 + 1000 / 2, is the playhead.
-    expect(screenX(300)).toBeCloseTo(556);
+    expect(laidOutX(300)).toBeCloseTo(556);
   });
 });
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 5a989910bc6..1d4b3007951 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -1,3 +1,4 @@
+import { flushSync } from "react-dom";
 import { usePlayerStore } from "../store/playerStore";
 import {
   clampTimelineZoomPercent,
@@ -17,54 +18,178 @@ export interface TimelineZoomViewport {
   contentOrigin: number;
 }
 
-const RANGE_MARGIN_PX = 24;
-const SMOOTH_ZOOM_MS = 220;
-
 /** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
 export type TimelineZoomResult = "done" | "cancelled";
 
-let pending: { percent: number; anchor: TimelineZoomAnchor | null; byPerson: boolean } | null =
-  null;
+/**
+ * A zoom drawn by scaling what is already laid out, on the compositor, until it is committed.
+ * `shift` is the scrollLeft minus the scrollLeft the zoom will have: the translate that places it.
+ */
+interface ZoomPreview {
+  percent: number;
+  pps: number;
+  shift: number;
+  basePps: number;
+  baseWidth: number;
+  byPerson: boolean;
+}
+
+const RANGE_MARGIN_PX = 24;
+const SMOOTH_ZOOM_MS = 220;
+/** How long a gesture holds still before its zoom is laid out for real. */
+const REST_MS = 150;
+// Past these a preview would show clips that are not mounted, or soft scaled-up raster.
+const MIN_PREVIEW_SCALE = 0.67;
+const MAX_PREVIEW_SCALE = 2;
+const SCALED = "[data-timeline-zoom-scale]";
+
+let viewport: TimelineZoomViewport | null = null;
+let preview: ZoomPreview | null = null;
 let frame = 0;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
 let anchorForCommit: TimelineZoomAnchor | null = null;
-let viewport: TimelineZoomViewport | null = null;
 let animation = 0;
 let easingTo: number | null = null;
 let settle: ((result: TimelineZoomResult) => void) | null = null;
+const previewListeners = new Set<() => void>();
 
-/** The percent the timeline is showing, or will show next frame. */
+/** The percent the timeline is showing. */
 export function currentTimelineZoomPercent(): number {
-  if (pending) return pending.percent;
+  if (preview) return preview.percent;
   const s = usePlayerStore.getState();
   return getTimelineZoomPercent(s.zoomMode, s.manualZoomPercent, s.timelineFitPps);
 }
 
-function flush() {
-  frame = 0;
-  const next = pending;
-  pending = null;
-  if (!next) return;
-  anchorForCommit = next.anchor;
-  // One store write per frame: percent, mode and the published scale together, so every reader
-  // of the scale renders once with the clips instead of once more after them.
+/** The scale the timeline shows and the scrollLeft that scale would have. */
+function shown(scroll: HTMLDivElement): { pps: number; left: number } {
+  if (preview) return { pps: preview.pps, left: scroll.scrollLeft - preview.shift };
+  return { pps: usePlayerStore.getState().timelinePps, left: scroll.scrollLeft };
+}
+
+/** The time under `x` px from the timeline viewport's left edge, as it is drawn now. */
+export function timelineTimeAtX(x: number): number | null {
+  if (!viewport) return null;
+  const { pps, left } = shown(viewport.scroll);
+  return pps > 0 ? (left + x - viewport.contentOrigin) / pps : null;
+}
+
+/** The scale and time-zero position to place something at a time by, while a zoom is previewed. */
+export function timelineZoomMapping(pps: number, contentOrigin: number) {
+  return preview
+    ? { pps: preview.pps, contentOrigin: contentOrigin + preview.shift }
+    : { pps, contentOrigin };
+}
+
+/** Called each frame a zoom preview moves, and once when it is laid out. */
+export function subscribeTimelineZoomPreview(listener: () => void): () => void {
+  previewListeners.add(listener);
+  return () => previewListeners.delete(listener);
+}
+
+function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+  anchorForCommit = anchor;
   usePlayerStore.setState((s) => {
-    const percent = clampTimelineZoomPercent(next.percent, s.timelineFitPps);
+    const clamped = clampTimelineZoomPercent(percent, s.timelineFitPps);
     return {
       zoomMode: "manual",
-      manualZoomPercent: percent,
+      manualZoomPercent: clamped,
       // Only a person's zoom counts: the timeline and its host read it as the person taking over.
-      userZoomCount: s.userZoomCount + (next.byPerson ? 1 : 0),
-      timelinePps: (s.timelineFitPps * percent) / 100,
+      userZoomCount: s.userZoomCount + (byPerson ? 1 : 0),
+      timelinePps: (s.timelineFitPps * clamped) / 100,
     };
   });
 }
 
+function clearScaled(scroll: HTMLElement) {
+  scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+    el.style.transform = "";
+    el.style.transformOrigin = "";
+    el.style.willChange = "";
+  });
+}
+
+function drawPreview() {
+  frame = 0;
+  const view = viewport;
+  if (!preview || !view) return;
+  const scale = preview.pps / preview.basePps;
+  if (scale < MIN_PREVIEW_SCALE || scale > MAX_PREVIEW_SCALE) {
+    commitPreview();
+    return;
+  }
+  const transform = `translateX(${preview.shift}px) scaleX(${scale})`;
+  view.scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+    el.style.transformOrigin = "0 0";
+    el.style.willChange = "transform";
+    el.style.transform = transform;
+  });
+  previewListeners.forEach((listener) => listener());
+}
+
+/** Lays the previewed zoom out for real and drops the scaling in the same frame. */
+function commitPreview() {
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = null;
+  cancelAnimationFrame(frame);
+  frame = 0;
+  const view = viewport;
+  const done = preview;
+  if (!view || !done) return;
+  const left = view.scroll.scrollLeft - done.shift;
+  flushSync(() =>
+    writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
+  );
+  preview = null;
+  if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
+  clearScaled(view.scroll);
+  previewListeners.forEach((listener) => listener());
+}
+
+/** The playhead's place if on screen, else the middle with the playhead brought to it. */
+function defaultAnchor(view: TimelineZoomViewport, pps: number, left: number): TimelineZoomAnchor {
+  const { currentTime } = usePlayerStore.getState();
+  const x = view.contentOrigin + currentTime * pps - left;
+  const onScreen = x >= view.contentOrigin && x <= view.scroll.clientWidth;
+  return {
+    time: currentTime,
+    x: onScreen ? x : (view.contentOrigin + view.scroll.clientWidth) / 2,
+  };
+}
+
 function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
-  pending = { percent, anchor, byPerson: byPerson || pending?.byPerson === true };
-  if (!frame) frame = requestAnimationFrame(flush);
+  const view = viewport;
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  if (!view || !(fitPps > 0)) {
+    writeZoom(percent, anchor, byPerson);
+    return;
+  }
+  const clamped = clampTimelineZoomPercent(percent, fitPps);
+  const pps = (fitPps * clamped) / 100;
+  const { scroll, contentOrigin } = view;
+  const now = shown(scroll);
+  const at = anchor ?? defaultAnchor(view, now.pps, now.left);
+  preview ??= {
+    percent: clamped,
+    pps,
+    shift: 0,
+    basePps: now.pps,
+    baseWidth: scroll.scrollWidth,
+    byPerson,
+  };
+  // The content's width at this scale, from its width when the preview began.
+  const width = contentOrigin + ((preview.baseWidth - contentOrigin) * pps) / preview.basePps;
+  const maxLeft = Math.max(0, width - scroll.clientWidth);
+  const left = Math.max(0, Math.min(maxLeft, at.time * pps + contentOrigin - at.x));
+  preview.percent = clamped;
+  preview.pps = pps;
+  preview.shift = scroll.scrollLeft - left;
+  preview.byPerson ||= byPerson;
+  if (!frame) frame = requestAnimationFrame(drawPreview);
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = setTimeout(commitPreview, REST_MS);
 }
 
-/** A person's zoom input; requests in the same frame collapse to the last, drawn once. */
+/** A person's zoom input: previewed each frame, laid out once it rests. */
 export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
   stopEase();
   request(percent, anchor, true);
@@ -87,6 +212,14 @@ export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
 }
 
 export function setTimelineZoomViewport(next: TimelineZoomViewport | null): void {
+  if (!next && viewport && preview) {
+    if (restTimer) clearTimeout(restTimer);
+    restTimer = null;
+    cancelAnimationFrame(frame);
+    frame = 0;
+    clearScaled(viewport.scroll);
+    preview = null;
+  }
   viewport = next;
 }
 
@@ -96,19 +229,19 @@ const reducedMotion = () =>
 /** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
 export function currentTimelineRange(): { start: number; end: number } | null {
   const view = viewport;
-  const fitPps = usePlayerStore.getState().timelineFitPps;
-  if (!view || !(fitPps > 0)) return null;
-  const pps = (fitPps * currentTimelineZoomPercent()) / 100;
+  if (!view) return null;
+  const { pps, left } = shown(view.scroll);
+  if (!(pps > 0)) return null;
   const x = view.contentOrigin + RANGE_MARGIN_PX;
   const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
-  const start = (view.scroll.scrollLeft + x - view.contentOrigin) / pps;
+  const start = (left + x - view.contentOrigin) / pps;
   return { start, end: start + width / pps };
 }
 
 /**
  * Zooms and scrolls so `start`..`end` (seconds) fills the timeline's width, easing there unless
- * `smooth` is false or the person prefers reduced motion. Resolves once the last step is laid
- * out, or as "cancelled" when a person zooms, `signal` aborts, or another range zoom starts.
+ * `smooth` is false or the person prefers reduced motion. Resolves once the range is laid out,
+ * or as "cancelled" when a person zooms, `signal` aborts, or another range zoom starts.
  */
 export function zoomTimelineToRange(
   start: number,
@@ -134,9 +267,9 @@ function easeToRange(
   const x = view.contentOrigin + RANGE_MARGIN_PX;
   const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
   const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
-  // Resolved a frame after the last request: its write and layout have run by then.
   const finish = () => {
-    animation = requestAnimationFrame(() => stopEase("done"));
+    commitPreview();
+    stopEase("done");
   };
   if (!smooth || reducedMotion()) {
     request(toPercent, { time: start, x }, byPerson);
@@ -144,16 +277,16 @@ function easeToRange(
     return result;
   }
   const fromPercent = currentTimelineZoomPercent();
-  const fromPps = (fitPps * fromPercent) / 100;
+  const from = shown(view.scroll);
   const toPps = (fitPps * toPercent) / 100;
-  const fromStart = (view.scroll.scrollLeft + x - view.contentOrigin) / fromPps;
+  const fromStart = (from.left + x - view.contentOrigin) / from.pps;
   // The one point both views put at the same place on screen; zooming about it, in log space,
   // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
-  const shift = fromPps === toPps ? null : (start - fromStart) / (1 / fromPps - 1 / toPps);
+  const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
   const anchorAt = (k: number): TimelineZoomAnchor =>
     shift === null
       ? { time: fromStart + (start - fromStart) * k, x }
-      : { time: fromStart + shift / fromPps, x: x + shift };
+      : { time: fromStart + shift / from.pps, x: x + shift };
   const began = performance.now();
   easingTo = toPercent;
   const step = (now: number) => {
@@ -188,10 +321,8 @@ export function zoomTimelineStep(direction: "in" | "out"): void {
   const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
   const nextPps = (fitPps * nextPercent) / 100;
   const span = width / nextPps;
-  const playheadX =
-    view.contentOrigin +
-    currentTime * ((fitPps * currentTimelineZoomPercent()) / 100) -
-    view.scroll.scrollLeft;
+  const now = shown(view.scroll);
+  const playheadX = view.contentOrigin + currentTime * now.pps - now.left;
   const onScreen = playheadX >= view.contentOrigin && playheadX <= view.scroll.clientWidth;
   const start = onScreen ? currentTime - (playheadX - x) / nextPps : currentTime - span / 2;
   void easeToRange(start, start + span, {}, true);
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 68892b90415..2bb971e0e2c 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -264,7 +264,9 @@ describe("useTimelinePlayhead wheel zoom", () => {
         metaKey: { value: Boolean(init.metaKey) },
       });
       scroll.dispatchEvent(event);
+      // The preview's frame, then its rest, when the zoom is laid out.
       vi.advanceTimersToNextFrame();
+      vi.advanceTimersByTime(200);
     });
 
   it("zooms on Cmd+wheel as on a pinch, and leaves a plain wheel to scroll", () => {
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 6bda8030d06..f71d1917478 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -6,7 +6,10 @@ import {
   currentTimelineZoomPercent,
   requestTimelineZoom,
   setTimelineZoomViewport,
+  subscribeTimelineZoomPreview,
   takeTimelineZoomAnchor,
+  timelineTimeAtX,
+  timelineZoomMapping,
 } from "./timelineZoomInput";
 import {
   getTimelinePlaybackFollowScrollLeft,
@@ -123,10 +126,11 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
+      const at = timelineZoomMapping(ppsRef.current, contentOrigin);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         time,
-        ppsRef.current,
-        contentOrigin,
+        at.pps,
+        at.contentOrigin,
         !usePlayerStore.getState().isPlaying,
       );
     },
@@ -160,14 +164,19 @@ export function useTimelinePlayhead({
   useMountEffect(() => {
     const place = (t: number, atRest: boolean) => {
       if (!playheadRef.current || durationRef.current <= 0) return false;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
-        ppsRef.current,
-        contentOriginRef.current,
+        at.pps,
+        at.contentOrigin,
         atRest,
       );
       return true;
     };
+    // A zoom preview moves the playhead with the scaled clips.
+    const unsubPreview = subscribeTimelineZoomPreview(() =>
+      place(lastLiveTimeRef.current, !usePlayerStore.getState().isPlaying),
+    );
     const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
     const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
       if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
@@ -179,7 +188,8 @@ export function useTimelinePlayhead({
       lastLiveTimeRef.current = t;
       const playing = usePlayerStore.getState().isPlaying;
       if (!place(t, !playing)) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
+      const playheadX = at.contentOrigin + Math.max(0, t) * at.pps;
       const scroll = scrollRef.current;
       // Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
       if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
@@ -199,6 +209,7 @@ export function useTimelinePlayhead({
     return () => {
       unsub();
       unsubPlaying();
+      unsubPreview();
     };
   });
 
@@ -256,10 +267,10 @@ export function useTimelinePlayhead({
           currentTimelineZoomPercent(),
           fitPpsRef.current,
         ),
-        { time: Math.max(0, (scroll.scrollLeft + x - contentOrigin) / ppsRef.current), x },
+        { time: Math.max(0, timelineTimeAtX(x) ?? 0), x },
       );
     },
-    [scrollRef, durationRef, fitPpsRef, ppsRef, contentOrigin],
+    [scrollRef, durationRef, fitPpsRef, ppsRef],
   );
 
   useEffect(() => {

From 560644c471433d19a1c684aad2925ea7ceb560fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 13:29:44 -0400
Subject: [PATCH 12/26] perf(studio): rebase a zoom preview only past 0.5x or
 4x

Clips stay mounted half a viewport each side, so a zoom-out preview to 0.5x shows no gaps.
---
 .../studio/src/player/components/timelineLayout.test.ts    | 6 +++---
 .../studio/src/player/components/timelineZoomInput.test.ts | 5 ++++-
 packages/studio/src/player/components/timelineZoomInput.ts | 7 ++++---
 .../studio/src/player/lib/timelineViewportBudgets.test.ts  | 2 +-
 packages/studio/src/player/lib/timelineViewportBudgets.ts  | 2 +-
 5 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/packages/studio/src/player/components/timelineLayout.test.ts b/packages/studio/src/player/components/timelineLayout.test.ts
index 14f4d525e20..3a5c11c0416 100644
--- a/packages/studio/src/player/components/timelineLayout.test.ts
+++ b/packages/studio/src/player/components/timelineLayout.test.ts
@@ -27,13 +27,13 @@ import { resolveInsertRow } from "./timelineCollision";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 
 describe("horizontal timeline window", () => {
-  it("adds the shared quarter-viewport overscan on each side and clamps to duration", () => {
+  it("adds the shared half-viewport overscan on each side and clamps to duration", () => {
     expect(getTimelineRenderTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20)).toEqual(
-      { start: 0, end: 7.25 },
+      { start: 0, end: 8.5 },
     );
     expect(
       getTimelineRenderTimeRange({ scrollLeft: 1_900, clientWidth: 500 }, 100, 200, 20),
-    ).toEqual({ start: 15.75, end: 20 });
+    ).toEqual({ start: 14.5, end: 20 });
   });
 
   it("generates globally aligned ticks directly inside the bounded window", () => {
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 354bb61a80d..c8481b24651 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -101,7 +101,10 @@ describe("requestTimelineZoom", () => {
     viewport();
     requestTimelineZoom(300);
     vi.advanceTimersToNextFrame();
-    expect(usePlayerStore.getState().timelinePps).toBe(30);
+    expect(usePlayerStore.getState().timelinePps).toBe(10);
+    requestTimelineZoom(500);
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(50);
   });
 });
 
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 1d4b3007951..25a4bd2d5fc 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -1,4 +1,5 @@
 import { flushSync } from "react-dom";
+import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
 import { usePlayerStore } from "../store/playerStore";
 import {
   clampTimelineZoomPercent,
@@ -38,9 +39,9 @@ const RANGE_MARGIN_PX = 24;
 const SMOOTH_ZOOM_MS = 220;
 /** How long a gesture holds still before its zoom is laid out for real. */
 const REST_MS = 150;
-// Past these a preview would show clips that are not mounted, or soft scaled-up raster.
-const MIN_PREVIEW_SCALE = 0.67;
-const MAX_PREVIEW_SCALE = 2;
+// Below this a preview would show past the clips mounted around the view; above, soft raster.
+const MIN_PREVIEW_SCALE = 1 / (1 + 2 * TIMELINE_VIEWPORT_BUDGETS.timeOverscanViewportRatio);
+const MAX_PREVIEW_SCALE = 4;
 const SCALED = "[data-timeline-zoom-scale]";
 
 let viewport: TimelineZoomViewport | null = null;
diff --git a/packages/studio/src/player/lib/timelineViewportBudgets.test.ts b/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
index 3c8a56496c0..9972db441cb 100644
--- a/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
+++ b/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
@@ -9,7 +9,7 @@ describe("timeline viewport budgets", () => {
     expect(TIMELINE_VIEWPORT_BUDGETS).toMatchObject({
       directScrollSafetyPx: 8_000_000,
       rowOverscanPerSide: 2,
-      timeOverscanViewportRatio: 0.25,
+      timeOverscanViewportRatio: 0.5,
       maxMountedRows: 64,
       maxMountedClipRoots: 512,
       maxMountedClipRootsPerRow: 128,
diff --git a/packages/studio/src/player/lib/timelineViewportBudgets.ts b/packages/studio/src/player/lib/timelineViewportBudgets.ts
index 4e4c2e3e1c5..d51ac9baec9 100644
--- a/packages/studio/src/player/lib/timelineViewportBudgets.ts
+++ b/packages/studio/src/player/lib/timelineViewportBudgets.ts
@@ -61,7 +61,7 @@ export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); /
 export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Object.freeze({
   directScrollSafetyPx: 8_000_000,
   rowOverscanPerSide: 2,
-  timeOverscanViewportRatio: 0.25,
+  timeOverscanViewportRatio: 0.5,
   maxMountedRows: 64,
   maxMountedClipRoots: 512,
   maxMountedClipRootsPerRow: 128,

From 2ad3661d989014cb009ab9eaba6c77036243fef9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 14:10:35 -0400
Subject: [PATCH 13/26] fix(studio): keep the zoom readout, edges and Fit right
 during a preview

The slider and its percent follow a zoom while it is previewed. A zoom in
from below Fit no longer jumps when it lands: the preview now uses the
width the timeline will really have. A zoom-out lays out as soon as it
would show time with no clips mounted, so edges never show empty strips.
Fit, a press or a scroll on the timeline end a pending zoom first. An
older abort no longer cancels a newer zoom-to-range, and an instant one
lands on the next frame instead of inside its caller. Range selection and
gap tints scale with the preview.
---
 .../src/components/TimelineToolbar.test.tsx   |  66 +++++++++++-
 .../studio/src/components/TimelineToolbar.tsx |  18 ++--
 .../src/player/components/TimelineCanvas.tsx  |   4 +
 .../components/timelineZoomInput.test.ts      | 102 +++++++++++++++---
 .../player/components/timelineZoomInput.ts    |  90 ++++++++++++----
 .../components/useTimelinePlayhead.test.tsx   |  30 +++++-
 .../player/components/useTimelinePlayhead.ts  |   6 ++
 .../src/player/components/useTimelineZoom.ts  |   9 +-
 8 files changed, 276 insertions(+), 49 deletions(-)

diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index 3b85e4382d2..4a603fa0ebc 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -11,6 +11,7 @@ import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 import { dispatchPlainKey, type HotkeyCallbacks } from "../hooks/appHotkeysDispatch";
 import { AudioMeterStrip } from "./nle/AudioMeterStrip";
 import { TimelineToolbar } from "./TimelineToolbar";
+import { setTimelineZoomViewport } from "../player/components/timelineZoomInput";
 
 vi.mock("../contexts/StudioContext", () => ({
   useStudioShellContextOptional: () => ({
@@ -242,13 +243,76 @@ describe("TimelineToolbar Fit", () => {
   // A zoom lands on the next frame; these tests step frames instead of waiting for them.
   beforeEach(() => {
     vi.useFakeTimers({
-      toFake: ["requestAnimationFrame", "cancelAnimationFrame", "setTimeout", "clearTimeout"],
+      toFake: [
+        "requestAnimationFrame",
+        "cancelAnimationFrame",
+        "setTimeout",
+        "clearTimeout",
+        "performance",
+      ],
     });
   });
   afterEach(() => {
     vi.useRealTimers();
   });
 
+  /** A mounted timeline for the zoom to preview on: 1080px wide, 32px of headers. */
+  function mountTimelineViewport() {
+    const scroll = document.createElement("div");
+    Object.defineProperties(scroll, {
+      clientWidth: { value: 1080 },
+      scrollLeft: { value: 0, writable: true },
+    });
+    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+    usePlayerStore.setState({
+      zoomMode: "fit",
+      manualZoomPercent: 100,
+      timelineFitPps: 10,
+      timelinePps: 10,
+    });
+  }
+
+  it("moves the slider and its readout with a zoom while it is previewed", () => {
+    mountTimelineViewport();
+    const { host, root } = renderToolbar();
+    const slider = host.querySelector<HTMLInputElement>('input[aria-label="Timeline zoom"]')!;
+    const before = slider.value;
+    act(() => {
+      Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(
+        slider,
+        String(Number(before) + 5),
+      );
+      slider.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    act(() => vi.advanceTimersToNextFrame());
+    // Not laid out yet: the store still holds Fit, but the toolbar shows the zoom on screen.
+    expect(usePlayerStore.getState().zoomMode).toBe("fit");
+    expect(slider.value).not.toBe(before);
+    expect(host.querySelector('[aria-label="Timeline zoom level"]')?.textContent).not.toBe("Fit");
+    act(() => root.unmount());
+    act(() => setTimelineZoomViewport(null));
+  });
+
+  it("keeps Fit when it is picked while a zoom waits to be laid out", () => {
+    mountTimelineViewport();
+    const { host, root } = renderToolbar();
+    act(() =>
+      host
+        .querySelector('button[aria-label="Zoom in"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+    );
+
+    act(() =>
+      host
+        .querySelector('button[aria-label="Fit timeline to width"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+    );
+    act(() => vi.advanceTimersByTime(1000));
+    expect(usePlayerStore.getState().zoomMode).toBe("fit");
+    act(() => root.unmount());
+    act(() => setTimelineZoomViewport(null));
+  });
+
   it("shows Fit as a named icon and says whether fit is on", () => {
     const { host, root } = renderToolbar();
     const fit = () => host.querySelector('button[aria-label="Fit timeline to width"]');
diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index 8906a9175e7..b5b5f657f73 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -19,7 +19,10 @@ import {
   timelineSliderToZoomPercent,
 } from "../player/components/timelineZoom";
 import { useTimelineZoom } from "../player/components/useTimelineZoom";
-import { zoomTimelineStep } from "../player/components/timelineZoomInput";
+import {
+  useShownTimelineZoomPercent,
+  zoomTimelineStep,
+} from "../player/components/timelineZoomInput";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { Tooltip } from "./ui";
 import { AudioMetersIcon } from "./icons/AudioMetersIcon";
@@ -176,11 +179,12 @@ export const TimelineToolbar = memo(function TimelineToolbar({
   const elements = usePlayerStore((s) => s.elements);
   const timelineFitPps = usePlayerStore((s) => s.timelineFitPps);
   const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
-  const displayedTimelineZoomPercent = getTimelineZoomPercent(
-    zoomMode,
-    manualZoomPercent,
-    timelineFitPps,
-  );
+  // Follows a zoom while it is previewed, before it is laid out and stored.
+  const displayedTimelineZoomPercent = useShownTimelineZoomPercent();
+  const showsFit =
+    zoomMode === "fit" &&
+    displayedTimelineZoomPercent ===
+      getTimelineZoomPercent("fit", manualZoomPercent, timelineFitPps);
   const {
     state: keyframeState,
     isMotionPath: keyframeIsMotionPath,
@@ -547,7 +551,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
             className="ml-1 w-[38px] text-right font-mono text-[11px] tabular-nums text-neutral-500 select-none"
             aria-label="Timeline zoom level"
           >
-            {zoomMode === "fit" ? "Fit" : `${displayedTimelineZoomPercent}%`}
+            {showsFit ? "Fit" : `${displayedTimelineZoomPercent}%`}
           </span>
         </div>
       </div>
diff --git a/packages/studio/src/player/components/TimelineCanvas.tsx b/packages/studio/src/player/components/TimelineCanvas.tsx
index 923844a59b5..3929162034a 100644
--- a/packages/studio/src/player/components/TimelineCanvas.tsx
+++ b/packages/studio/src/player/components/TimelineCanvas.tsx
@@ -116,6 +116,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         return visibleIntervals.map((gap) => (
           <div
             key={`gap-${strip.kind}-${strip.track}-${gap.start}`}
+            data-timeline-zoom-scale={-gap.start * props.pps}
             className="pointer-events-none absolute"
             style={{
               top: props.rowGeometry.getRowTop(rowIndex) + CLIP_Y,
@@ -246,6 +247,9 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
       {/* Range highlight */}
       {props.rangeSelection && (
         <div
+          data-timeline-zoom-scale={
+            -Math.min(props.rangeSelection.start, props.rangeSelection.end) * props.pps
+          }
           className="absolute pointer-events-none"
           style={{
             left:
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index c8481b24651..294a0599913 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -3,8 +3,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
 import {
+  cancelTimelineZoom,
   currentTimelineRange,
   currentTimelineZoomPercent,
+  settleTimelineZoom,
+  timelineTimeAtX,
   requestTimelineZoom,
   setTimelineZoomViewport,
   takeTimelineZoomAnchor,
@@ -30,6 +33,7 @@ beforeEach(() => {
     timelinePps: 10,
     userZoomCount: 0,
     currentTime: 0,
+    duration: 0,
   });
 });
 afterEach(() => {
@@ -45,7 +49,6 @@ function viewport(scrollLeft = 0) {
   const scroll = document.createElement("div");
   Object.defineProperties(scroll, {
     clientWidth: { value: 1080 },
-    scrollWidth: { value: 20_000 },
     scrollLeft: { value: scrollLeft, writable: true },
   });
   const row = scroll.appendChild(document.createElement("div"));
@@ -85,16 +88,66 @@ describe("requestTimelineZoom", () => {
   });
 
   it("keeps the time under the pointer while previewing, then lays it out there", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 400, timelinePps: 40 });
     const { scroll, row } = viewport(400);
-    // 432px in: (400 + 432 - 32) / 10 = 80 s.
-    requestTimelineZoom(150, { time: 80, x: 432 });
+    // 432px in: (400 + 432 - 32) / 40 = 20 s.
+    requestTimelineZoom(600, { time: 20, x: 432 });
     vi.advanceTimersToNextFrame();
-    const mapping = timelineZoomMapping(10, 32);
-    expect(mapping.pps).toBe(15);
-    expect(mapping.contentOrigin + 80 * mapping.pps - scroll.scrollLeft).toBeCloseTo(432);
+    const mapping = timelineZoomMapping(40, 32);
+    expect(mapping.pps).toBe(60);
+    expect(mapping.contentOrigin + 20 * mapping.pps - scroll.scrollLeft).toBeCloseTo(432);
     expect(row.style.transform).toContain("scaleX(1.5)");
     vi.advanceTimersByTime(150);
-    expect(laidOutX(80)).toBeCloseTo(432);
+    expect(laidOutX(20)).toBeCloseTo(432);
+  });
+
+  it("never previews a scroll the laid-out zoom cannot reach, zooming in from below Fit", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 50, timelinePps: 5 });
+    viewport();
+    // 90 s sits 482px in at 5 px/s. At 110% the content is 32 + 1046 * 1.1 wide,
+    // so the view can scroll at most 102.6px.
+    requestTimelineZoom(110, { time: 90, x: 482 });
+    expect(timelineTimeAtX(32)! * 11).toBeLessThanOrEqual(102.6 + 1e-6);
+  });
+
+  it("lays a zoom-out about the left edge out at once, before it shows unmounted time", () => {
+    usePlayerStore.setState({ duration: 1000 });
+    viewport();
+    // Mounted to (1080 - 32 + 540) / 10 = 158.8 s; at 5 px/s the view reaches 209.6 s.
+    requestTimelineZoom(50, { time: 0, x: 32 });
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(5);
+  });
+
+  it("previews a zoom-out about the middle that stays within what is mounted", () => {
+    usePlayerStore.setState({
+      duration: 100,
+      zoomMode: "manual",
+      manualZoomPercent: 1000,
+      timelinePps: 100,
+    });
+    viewport(5000);
+    // Mounted 44.28..65.88 s; at 60 px/s about 55.24 s the view shows 46.5..63.97 s.
+    requestTimelineZoom(600, { time: 55.24, x: 556 });
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+  });
+
+  it("lays a pending zoom out at once when settled, as a press does", () => {
+    viewport();
+    requestTimelineZoom(150);
+    settleTimelineZoom();
+    expect(usePlayerStore.getState().timelinePps).toBe(15);
+  });
+
+  it("drops a pending zoom when cancelled, as Fit does", () => {
+    const { row } = viewport();
+    requestTimelineZoom(150);
+    vi.advanceTimersToNextFrame();
+    cancelTimelineZoom();
+    vi.advanceTimersByTime(300);
+    expect(usePlayerStore.getState().timelinePps).toBe(10);
+    expect(row.style.transform).toBe("");
   });
 
   it("lays the zoom out mid-gesture once the preview has scaled too far", () => {
@@ -111,10 +164,13 @@ describe("requestTimelineZoom", () => {
 describe("zoomTimelineToRange", () => {
   it("fills the width with the range and puts its start at the left margin", () => {
     viewport();
-    void zoomTimelineToRange(100, 150, { smooth: false });
+    void zoomTimelineToRange(40, 90, { smooth: false });
+    // Laid out on the next frame, never inside the caller's own render or effect.
+    expect(usePlayerStore.getState().timelinePps).toBe(10);
+    vi.advanceTimersToNextFrame();
     // 1080 - (32 + 24) - 24 = 1000px for 50s is 20 pps.
     expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
-    expect(laidOutX(100)).toBeCloseTo(56);
+    expect(laidOutX(40)).toBeCloseTo(56);
   });
 
   it("eases there over several frames and ends exactly on the range", () => {
@@ -154,6 +210,17 @@ describe("zoomTimelineToRange", () => {
     expect(row.style.transform).toBe("");
   });
 
+  it("leaves a newer zoom alone when an older one's signal aborts", async () => {
+    viewport();
+    const abort = new AbortController();
+    const older = zoomTimelineToRange(10, 20, { signal: abort.signal });
+    const newer = zoomTimelineToRange(30, 40);
+    abort.abort();
+    for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+    await expect(older).resolves.toBe("cancelled");
+    await expect(newer).resolves.toBe("done");
+  });
+
   it("cancels when the caller aborts", async () => {
     viewport();
     const abort = new AbortController();
@@ -167,10 +234,11 @@ describe("zoomTimelineToRange", () => {
 describe("currentTimelineRange", () => {
   it("reads back the range zoomTimelineToRange filled", () => {
     viewport();
-    void zoomTimelineToRange(100, 150, { smooth: false });
+    void zoomTimelineToRange(40, 90, { smooth: false });
+    vi.advanceTimersToNextFrame();
     const range = currentTimelineRange()!;
-    expect(range.start).toBeCloseTo(100);
-    expect(range.end).toBeCloseTo(150);
+    expect(range.start).toBeCloseTo(40);
+    expect(range.end).toBeCloseTo(90);
   });
 
   it("reads the range a gesture shows before it is laid out", () => {
@@ -210,11 +278,17 @@ describe("zoomTimelineStep", () => {
   });
 
   it("centres an off-screen playhead", () => {
-    usePlayerStore.setState({ currentTime: 300 });
+    usePlayerStore.setState({
+      currentTime: 60,
+      zoomMode: "manual",
+      manualZoomPercent: 400,
+      timelinePps: 40,
+    });
+    // 0..26.2 s on screen at 40 px/s.
     viewport();
     zoomTimelineStep("in");
     run();
     // The range's middle, 56 + 1000 / 2, is the playhead.
-    expect(laidOutX(300)).toBeCloseTo(556);
+    expect(laidOutX(60)).toBeCloseTo(556);
   });
 });
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 25a4bd2d5fc..a069bc83f64 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -1,6 +1,8 @@
+import { useSyncExternalStore } from "react";
 import { flushSync } from "react-dom";
-import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 import { usePlayerStore } from "../store/playerStore";
+import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 import {
   clampTimelineZoomPercent,
   getNextTimelineZoomPercent,
@@ -31,7 +33,8 @@ interface ZoomPreview {
   pps: number;
   shift: number;
   basePps: number;
-  baseWidth: number;
+  /** The times with clips mounted when the preview began; past them it would show gaps. */
+  mounted: TimelineTimeRange;
   byPerson: boolean;
 }
 
@@ -39,8 +42,7 @@ const RANGE_MARGIN_PX = 24;
 const SMOOTH_ZOOM_MS = 220;
 /** How long a gesture holds still before its zoom is laid out for real. */
 const REST_MS = 150;
-// Below this a preview would show past the clips mounted around the view; above, soft raster.
-const MIN_PREVIEW_SCALE = 1 / (1 + 2 * TIMELINE_VIEWPORT_BUDGETS.timeOverscanViewportRatio);
+/** Past this the scaled-up preview turns soft. */
 const MAX_PREVIEW_SCALE = 4;
 const SCALED = "[data-timeline-zoom-scale]";
 
@@ -87,6 +89,20 @@ export function subscribeTimelineZoomPreview(listener: () => void): () => void {
   return () => previewListeners.delete(listener);
 }
 
+const subscribeShownZoom = (listener: () => void) => {
+  const unsubscribePreview = subscribeTimelineZoomPreview(listener);
+  const unsubscribeStore = usePlayerStore.subscribe(listener);
+  return () => {
+    unsubscribePreview();
+    unsubscribeStore();
+  };
+};
+
+/** The zoom percent the timeline shows, kept current through a preview. */
+export function useShownTimelineZoomPercent(): number {
+  return useSyncExternalStore(subscribeShownZoom, currentTimelineZoomPercent);
+}
+
 function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
   anchorForCommit = anchor;
   usePlayerStore.setState((s) => {
@@ -109,18 +125,32 @@ function clearScaled(scroll: HTMLElement) {
   });
 }
 
+/** Whether the preview shows time outside what was mounted, or is scaled up too far. */
+function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigin: number) {
+  if (p.pps / p.basePps > MAX_PREVIEW_SCALE) return true;
+  const left = scroll.scrollLeft - p.shift;
+  const start = left / p.pps;
+  const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
+  const duration = usePlayerStore.getState().duration || Number.POSITIVE_INFINITY;
+  return (
+    (p.mounted.start > 0 && start < p.mounted.start) ||
+    (p.mounted.end < duration && end > p.mounted.end)
+  );
+}
+
 function drawPreview() {
   frame = 0;
   const view = viewport;
   if (!preview || !view) return;
-  const scale = preview.pps / preview.basePps;
-  if (scale < MIN_PREVIEW_SCALE || scale > MAX_PREVIEW_SCALE) {
+  if (previewNeedsLayout(preview, view.scroll, view.contentOrigin)) {
     commitPreview();
     return;
   }
+  const scale = preview.pps / preview.basePps;
   const transform = `translateX(${preview.shift}px) scaleX(${scale})`;
   view.scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
-    el.style.transformOrigin = "0 0";
+    // The attribute's value is where time zero sits in the element, when not at its left edge.
+    el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
     el.style.willChange = "transform";
     el.style.transform = transform;
   });
@@ -169,16 +199,18 @@ function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: b
   const { scroll, contentOrigin } = view;
   const now = shown(scroll);
   const at = anchor ?? defaultAnchor(view, now.pps, now.left);
+  const duration = usePlayerStore.getState().duration || Number.POSITIVE_INFINITY;
   preview ??= {
     percent: clamped,
     pps,
     shift: 0,
     basePps: now.pps,
-    baseWidth: scroll.scrollWidth,
+    mounted: getTimelineRenderTimeRange(scroll, now.pps, contentOrigin, duration),
     byPerson,
   };
-  // The content's width at this scale, from its width when the preview began.
-  const width = contentOrigin + ((preview.baseWidth - contentOrigin) * pps) / preview.basePps;
+  // The content's width at this scale: the fit track (getTimelineFitPps), never narrower.
+  const fitTrack = scroll.clientWidth - contentOrigin - 2;
+  const width = contentOrigin + fitTrack * Math.max(1, pps / fitPps);
   const maxLeft = Math.max(0, width - scroll.clientWidth);
   const left = Math.max(0, Math.min(maxLeft, at.time * pps + contentOrigin - at.x));
   preview.percent = clamped;
@@ -196,6 +228,26 @@ export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor
   request(percent, anchor, true);
 }
 
+/** Lays out a pending zoom now, so what comes next (a press, a scroll) meets the real layout. */
+export function settleTimelineZoom(): void {
+  if (preview) commitPreview();
+}
+
+/** Drops any pending or easing zoom without laying it out, as Fit does. */
+export function cancelTimelineZoom(): void {
+  stopEase();
+  dropPreview();
+}
+
+function dropPreview() {
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = null;
+  cancelAnimationFrame(frame);
+  frame = 0;
+  if (viewport && preview) clearScaled(viewport.scroll);
+  preview = null;
+}
+
 function stopEase(result: TimelineZoomResult = "cancelled") {
   cancelAnimationFrame(animation);
   animation = 0;
@@ -213,14 +265,7 @@ export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
 }
 
 export function setTimelineZoomViewport(next: TimelineZoomViewport | null): void {
-  if (!next && viewport && preview) {
-    if (restTimer) clearTimeout(restTimer);
-    restTimer = null;
-    cancelAnimationFrame(frame);
-    frame = 0;
-    clearScaled(viewport.scroll);
-    preview = null;
-  }
+  if (!next) cancelTimelineZoom();
   viewport = next;
 }
 
@@ -263,8 +308,10 @@ function easeToRange(
   stopEase();
   if (!view || !(end > start) || !(fitPps > 0) || signal?.aborted)
     return Promise.resolve("cancelled");
-  const result = new Promise<TimelineZoomResult>((resolve) => (settle = resolve));
-  signal?.addEventListener("abort", () => settle && stopEase(), { once: true });
+  let resolveThis: (result: TimelineZoomResult) => void = () => {};
+  const result = new Promise<TimelineZoomResult>((resolve) => (resolveThis = resolve));
+  settle = resolveThis;
+  signal?.addEventListener("abort", () => settle === resolveThis && stopEase(), { once: true });
   const x = view.contentOrigin + RANGE_MARGIN_PX;
   const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
   const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
@@ -274,7 +321,8 @@ function easeToRange(
   };
   if (!smooth || reducedMotion()) {
     request(toPercent, { time: start, x }, byPerson);
-    finish();
+    // Laid out next frame, never inside a caller's render or effect.
+    animation = requestAnimationFrame(finish);
     return result;
   }
   const fromPercent = currentTimelineZoomPercent();
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 2bb971e0e2c..1be6e6324cb 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -278,13 +278,35 @@ describe("useTimelinePlayhead wheel zoom", () => {
     expect(usePlayerStore.getState().manualZoomPercent).toBeGreaterThan(100);
   });
 
+  it("lays a pending pinch out at once when the timeline is pressed", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    act(() => {
+      const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true });
+      Object.defineProperties(event, {
+        clientX: { value: 432 },
+        ctrlKey: { value: true },
+        metaKey: { value: false },
+      });
+      scroll.dispatchEvent(event);
+      vi.advanceTimersToNextFrame();
+    });
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+    act(() => {
+      scroll.dispatchEvent(new Event("pointerdown"));
+    });
+    expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+  });
+
   it("keeps the time under the pointer in place as a pinch lays out", () => {
-    const scroll = scrollBox(400);
+    // Zoomed to 150%, so a 300px scroll is one the content allows.
+    usePlayerStore.setState({ manualZoomPercent: 150, timelinePps: 150 });
+    const scroll = scrollBox(300);
     mount({ scroll });
-    // Pointer 432px in: (400 + 432 - 32) / 100 = 8s sits there before and after.
+    // Pointer 432px in: (300 + 432 - 32) / 150 s sits there before and after.
     wheel(scroll, { ctrlKey: true });
     const pps = usePlayerStore.getState().timelinePps;
-    expect(pps).toBeGreaterThan(100);
-    expect(ORIGIN + 8 * pps - scroll.scrollLeft).toBeCloseTo(432);
+    expect(pps).toBeGreaterThan(150);
+    expect(ORIGIN + (700 / 150) * pps - scroll.scrollLeft).toBeCloseTo(432);
   });
 });
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index f71d1917478..c2166240aef 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -6,6 +6,7 @@ import {
   currentTimelineZoomPercent,
   requestTimelineZoom,
   setTimelineZoomViewport,
+  settleTimelineZoom,
   subscribeTimelineZoomPreview,
   takeTimelineZoomAnchor,
   timelineTimeAtX,
@@ -277,9 +278,14 @@ export function useTimelinePlayhead({
     const scroll = scrollRef.current;
     if (!scroll) return;
     scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    // A press or scroll meets the zoom it sees, not the one still waiting to be laid out.
+    scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
+    scroll.addEventListener("scroll", settleTimelineZoom, { passive: true });
     setTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+      scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
+      scroll.removeEventListener("scroll", settleTimelineZoom);
       setTimelineZoomViewport(null);
     };
   }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
diff --git a/packages/studio/src/player/components/useTimelineZoom.ts b/packages/studio/src/player/components/useTimelineZoom.ts
index 9d6f51ac0c1..d5e07bc1d77 100644
--- a/packages/studio/src/player/components/useTimelineZoom.ts
+++ b/packages/studio/src/player/components/useTimelineZoom.ts
@@ -1,6 +1,6 @@
 // fallow-ignore-file dead-code
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
-import { requestTimelineZoom } from "./timelineZoomInput";
+import { cancelTimelineZoom, requestTimelineZoom } from "./timelineZoomInput";
 
 export interface TimelineZoomState {
   zoomMode: ZoomMode;
@@ -13,6 +13,11 @@ export interface TimelineZoomState {
 export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
-  const setZoomMode = usePlayerStore((s) => s.setZoomMode);
+  const setStoreZoomMode = usePlayerStore((s) => s.setZoomMode);
+  // A mode picked now (Fit) wins over a zoom still easing or waiting to be laid out.
+  const setZoomMode = (mode: ZoomMode) => {
+    cancelTimelineZoom();
+    setStoreZoomMode(mode);
+  };
   return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent: requestTimelineZoom };
 }

From 5cb8785d7ec88287a177912aa8fdf9cde64b31b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 14:27:38 -0400
Subject: [PATCH 14/26] fix(studio): keep a pending zoom when the timeline
 re-registers its view

The timeline registers its scroll view again whenever clips are added or
removed, which used to drop a zoom still waiting to be laid out. Now only
a real unmount drops it, and unmounting one timeline leaves a newer
timeline's registration alone.
---
 .../src/components/TimelineToolbar.test.tsx   | 12 ++++----
 .../components/timelineZoomInput.test.ts      | 28 +++++++++++++++++--
 .../player/components/timelineZoomInput.ts    | 12 ++++++--
 .../player/components/useTimelinePlayhead.ts  |  6 ++--
 4 files changed, 44 insertions(+), 14 deletions(-)

diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index 4a603fa0ebc..faae99f5a18 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -11,7 +11,7 @@ import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 import { dispatchPlainKey, type HotkeyCallbacks } from "../hooks/appHotkeysDispatch";
 import { AudioMeterStrip } from "./nle/AudioMeterStrip";
 import { TimelineToolbar } from "./TimelineToolbar";
-import { setTimelineZoomViewport } from "../player/components/timelineZoomInput";
+import { registerTimelineZoomViewport } from "../player/components/timelineZoomInput";
 
 vi.mock("../contexts/StudioContext", () => ({
   useStudioShellContextOptional: () => ({
@@ -263,17 +263,17 @@ describe("TimelineToolbar Fit", () => {
       clientWidth: { value: 1080 },
       scrollLeft: { value: 0, writable: true },
     });
-    setTimelineZoomViewport({ scroll, contentOrigin: 32 });
     usePlayerStore.setState({
       zoomMode: "fit",
       manualZoomPercent: 100,
       timelineFitPps: 10,
       timelinePps: 10,
     });
+    return registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
   }
 
   it("moves the slider and its readout with a zoom while it is previewed", () => {
-    mountTimelineViewport();
+    const unregister = mountTimelineViewport();
     const { host, root } = renderToolbar();
     const slider = host.querySelector<HTMLInputElement>('input[aria-label="Timeline zoom"]')!;
     const before = slider.value;
@@ -290,11 +290,11 @@ describe("TimelineToolbar Fit", () => {
     expect(slider.value).not.toBe(before);
     expect(host.querySelector('[aria-label="Timeline zoom level"]')?.textContent).not.toBe("Fit");
     act(() => root.unmount());
-    act(() => setTimelineZoomViewport(null));
+    act(() => unregister());
   });
 
   it("keeps Fit when it is picked while a zoom waits to be laid out", () => {
-    mountTimelineViewport();
+    const unregister = mountTimelineViewport();
     const { host, root } = renderToolbar();
     act(() =>
       host
@@ -310,7 +310,7 @@ describe("TimelineToolbar Fit", () => {
     act(() => vi.advanceTimersByTime(1000));
     expect(usePlayerStore.getState().zoomMode).toBe("fit");
     act(() => root.unmount());
-    act(() => setTimelineZoomViewport(null));
+    act(() => unregister());
   });
 
   it("shows Fit as a named icon and says whether fit is on", () => {
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 294a0599913..86293c3623a 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -9,7 +9,7 @@ import {
   settleTimelineZoom,
   timelineTimeAtX,
   requestTimelineZoom,
-  setTimelineZoomViewport,
+  registerTimelineZoomViewport,
   takeTimelineZoomAnchor,
   timelineZoomMapping,
   zoomTimelineStep,
@@ -39,11 +39,13 @@ beforeEach(() => {
 afterEach(() => {
   // Run out any ease, preview and rest, so the next test starts with nothing scheduled.
   for (let i = 0; i < 40; i++) vi.advanceTimersToNextFrame();
-  setTimelineZoomViewport(null);
+  unregisterViewport();
   takeTimelineZoomAnchor();
   vi.useRealTimers();
 });
 
+let unregisterViewport = () => {};
+
 /** A 1080px timeline viewport with 32px of track headers, holding one scaled row. */
 function viewport(scrollLeft = 0) {
   const scroll = document.createElement("div");
@@ -53,7 +55,7 @@ function viewport(scrollLeft = 0) {
   });
   const row = scroll.appendChild(document.createElement("div"));
   row.setAttribute("data-timeline-zoom-scale", "");
-  setTimelineZoomViewport({ scroll, contentOrigin: 32 });
+  unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
   return { scroll, row };
 }
 
@@ -150,6 +152,26 @@ describe("requestTimelineZoom", () => {
     expect(row.style.transform).toBe("");
   });
 
+  it("keeps a pending zoom when the timeline registers again, as a re-render does", async () => {
+    const { scroll } = viewport();
+    requestTimelineZoom(150);
+    unregisterViewport();
+    unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+    await Promise.resolve();
+    vi.advanceTimersByTime(200);
+    expect(usePlayerStore.getState().timelinePps).toBe(15);
+  });
+
+  it("keeps a newer timeline's registration when an older one unmounts", () => {
+    const unregisterOlder = registerTimelineZoomViewport({
+      scroll: document.createElement("div"),
+      contentOrigin: 32,
+    });
+    viewport();
+    unregisterOlder();
+    expect(currentTimelineRange()).not.toBeNull();
+  });
+
   it("lays the zoom out mid-gesture once the preview has scaled too far", () => {
     viewport();
     requestTimelineZoom(300);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index a069bc83f64..9fe75ef4463 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -264,9 +264,17 @@ export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
   return anchor;
 }
 
-export function setTimelineZoomViewport(next: TimelineZoomViewport | null): void {
-  if (!next) cancelTimelineZoom();
+export function registerTimelineZoomViewport(next: TimelineZoomViewport): () => void {
   viewport = next;
+  return () => {
+    // Another timeline mounted since keeps its registration.
+    if (viewport !== next) return;
+    viewport = null;
+    // A re-render registers again in the same commit; only a real unmount drops the zoom.
+    queueMicrotask(() => {
+      if (!viewport) cancelTimelineZoom();
+    });
+  };
 }
 
 const reducedMotion = () =>
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index c2166240aef..2af840b34ea 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -5,7 +5,7 @@ import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   currentTimelineZoomPercent,
   requestTimelineZoom,
-  setTimelineZoomViewport,
+  registerTimelineZoomViewport,
   settleTimelineZoom,
   subscribeTimelineZoomPreview,
   takeTimelineZoomAnchor,
@@ -281,12 +281,12 @@ export function useTimelinePlayhead({
     // A press or scroll meets the zoom it sees, not the one still waiting to be laid out.
     scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
     scroll.addEventListener("scroll", settleTimelineZoom, { passive: true });
-    setTimelineZoomViewport({ scroll, contentOrigin });
+    const unregisterZoomViewport = registerTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
       scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
       scroll.removeEventListener("scroll", settleTimelineZoom);
-      setTimelineZoomViewport(null);
+      unregisterZoomViewport();
     };
   }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
 

From 7cde9fbb6f12d90b7d88ba9be9608b6cf9ff3067 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 14:52:47 -0400
Subject: [PATCH 15/26] refactor(studio): share the zoom geometry helpers the
 timeline already has

Zoom scales come from getTimelinePixelsPerSecond, the range margins from one
helper, and a zoom step starts from the same playhead anchor every zoom uses.
The clip minimum width is named and shared with the drag ghost.
---
 .../studio/src/components/TimelineToolbar.tsx |  9 +--
 .../src/player/components/TimelineClip.tsx    |  7 +-
 .../src/player/components/TimelineLanes.tsx   |  3 +-
 .../player/components/timelineZoomInput.ts    | 81 ++++++++++---------
 .../components/useTimelinePlayhead.test.tsx   | 22 +++--
 .../player/components/useTimelinePlayhead.ts  |  4 +-
 6 files changed, 65 insertions(+), 61 deletions(-)

diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index b5b5f657f73..f70fd1ec253 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -14,7 +14,6 @@ import {
 import { computeElementPercentage, playsNear } from "../hooks/gsapShared";
 import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
 import {
-  getTimelineZoomPercent,
   timelineZoomPercentToSlider,
   timelineSliderToZoomPercent,
 } from "../player/components/timelineZoom";
@@ -178,13 +177,11 @@ export const TimelineToolbar = memo(function TimelineToolbar({
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const elements = usePlayerStore((s) => s.elements);
   const timelineFitPps = usePlayerStore((s) => s.timelineFitPps);
-  const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+  const { zoomMode, setZoomMode, setManualZoomPercent } = useTimelineZoom();
   // Follows a zoom while it is previewed, before it is laid out and stored.
   const displayedTimelineZoomPercent = useShownTimelineZoomPercent();
-  const showsFit =
-    zoomMode === "fit" &&
-    displayedTimelineZoomPercent ===
-      getTimelineZoomPercent("fit", manualZoomPercent, timelineFitPps);
+  // Fit is 100%; anything else on screen is a zoom still being previewed.
+  const showsFit = zoomMode === "fit" && displayedTimelineZoomPercent === 100;
   const {
     state: keyframeState,
     isMotionPath: keyframeIsMotionPath,
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index dd545577f91..d1213f49ee7 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -48,7 +48,10 @@ interface TimelineClipProps {
 /** Narrower clips show trim handles only while selected. */
 const HANDLES_MIN_PX = 32;
 
-const clipWidthPx = (el: TimelineElement, pps: number) => Math.max(el.duration * pps, 4);
+/** The narrowest a clip is drawn, so a very short one stays visible and grabbable. */
+const CLIP_MIN_WIDTH_PX = 4;
+export const clipWidthPx = (el: TimelineElement, pps: number) =>
+  Math.max(el.duration * pps, CLIP_MIN_WIDTH_PX);
 
 /**
  * What a clip draws that depends on the zoom, as one value: its width tier and whether its trim
@@ -130,7 +133,7 @@ export const TimelineClip = memo(function TimelineClip({
   const style: CSSProperties = {
     left: timeLayerPercent(el.start),
     width: timeLayerPercent(el.duration),
-    minWidth: 4,
+    minWidth: CLIP_MIN_WIDTH_PX,
     top: clipY,
     ...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
     borderRadius: isAudioClip ? theme.audioClipRadius : theme.clipRadius,
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index fa8a2ff10d3..a02fa648c11 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -11,6 +11,7 @@ import { TimelineGroupRow } from "./TimelineGroupRow";
 import { useTimelineLaneRowIndexes, useTimelineGroupDisclosure } from "./useTimelineLaneRowIndexes";
 import { useTimelineClipDisclosure } from "./useTimelineClipDisclosure";
 import { TimelineTimeLayer } from "./TimelineTimeLayer";
+import { clipWidthPx } from "./TimelineClip";
 import {
   isTrackRowExpanded,
   resolveTrackKeyframeClip,
@@ -489,7 +490,7 @@ export function TimelineLanes({
                           clipStart={clipTimingStart(previewElement)}
                           clipDuration={previewElement.duration}
                           clipLeftPx={previewElement.start * pps}
-                          clipWidthPx={Math.max(previewElement.duration * pps, 4)}
+                          clipWidthPx={clipWidthPx(previewElement, pps)}
                           passengerStyle={passengerStyle}
                           accentColor={clipStyle.accent}
                           isSelected={isSelected}
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 9fe75ef4463..ca5741ddcb8 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -6,6 +6,7 @@ import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 import {
   clampTimelineZoomPercent,
   getNextTimelineZoomPercent,
+  getTimelinePixelsPerSecond,
   getTimelineZoomPercent,
 } from "./timelineZoom";
 
@@ -15,7 +16,7 @@ export interface TimelineZoomAnchor {
   x: number;
 }
 
-/** The mounted timeline's scroll viewport, which zoom-to-range measures against. */
+/** The mounted timeline's scroll viewport, which every zoom measures and previews against. */
 export interface TimelineZoomViewport {
   scroll: HTMLDivElement;
   contentOrigin: number;
@@ -53,7 +54,7 @@ let restTimer: ReturnType<typeof setTimeout> | null = null;
 let anchorForCommit: TimelineZoomAnchor | null = null;
 let animation = 0;
 let easingTo: number | null = null;
-let settle: ((result: TimelineZoomResult) => void) | null = null;
+let resolveEase: ((result: TimelineZoomResult) => void) | null = null;
 const previewListeners = new Set<() => void>();
 
 /** The percent the timeline is showing. */
@@ -112,11 +113,21 @@ function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson:
       manualZoomPercent: clamped,
       // Only a person's zoom counts: the timeline and its host read it as the person taking over.
       userZoomCount: s.userZoomCount + (byPerson ? 1 : 0),
-      timelinePps: (s.timelineFitPps * clamped) / 100,
+      timelinePps: getTimelinePixelsPerSecond(s.timelineFitPps, "manual", clamped),
     };
   });
 }
 
+const emitPreview = () => previewListeners.forEach((listener) => listener());
+
+/** Stops the pending preview frame and rest timer. */
+function cancelPending() {
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = null;
+  cancelAnimationFrame(frame);
+  frame = 0;
+}
+
 function clearScaled(scroll: HTMLElement) {
   scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
     el.style.transform = "";
@@ -154,15 +165,12 @@ function drawPreview() {
     el.style.willChange = "transform";
     el.style.transform = transform;
   });
-  previewListeners.forEach((listener) => listener());
+  emitPreview();
 }
 
 /** Lays the previewed zoom out for real and drops the scaling in the same frame. */
 function commitPreview() {
-  if (restTimer) clearTimeout(restTimer);
-  restTimer = null;
-  cancelAnimationFrame(frame);
-  frame = 0;
+  cancelPending();
   const view = viewport;
   const done = preview;
   if (!view || !done) return;
@@ -173,7 +181,7 @@ function commitPreview() {
   preview = null;
   if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
   clearScaled(view.scroll);
-  previewListeners.forEach((listener) => listener());
+  emitPreview();
 }
 
 /** The playhead's place if on screen, else the middle with the playhead brought to it. */
@@ -195,7 +203,7 @@ function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: b
     return;
   }
   const clamped = clampTimelineZoomPercent(percent, fitPps);
-  const pps = (fitPps * clamped) / 100;
+  const pps = getTimelinePixelsPerSecond(fitPps, "manual", clamped);
   const { scroll, contentOrigin } = view;
   const now = shown(scroll);
   const at = anchor ?? defaultAnchor(view, now.pps, now.left);
@@ -240,10 +248,7 @@ export function cancelTimelineZoom(): void {
 }
 
 function dropPreview() {
-  if (restTimer) clearTimeout(restTimer);
-  restTimer = null;
-  cancelAnimationFrame(frame);
-  frame = 0;
+  cancelPending();
   if (viewport && preview) clearScaled(viewport.scroll);
   preview = null;
 }
@@ -252,8 +257,8 @@ function stopEase(result: TimelineZoomResult = "cancelled") {
   cancelAnimationFrame(animation);
   animation = 0;
   easingTo = null;
-  const done = settle;
-  settle = null;
+  const done = resolveEase;
+  resolveEase = null;
   done?.(result);
 }
 
@@ -280,15 +285,19 @@ export function registerTimelineZoomViewport(next: TimelineZoomViewport): () =>
 const reducedMotion = () =>
   typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
 
+/** The stretch a range zoom fills: from `x` px in, `width` px wide, inside the margins. */
+function rangeBox(view: TimelineZoomViewport): { x: number; width: number } {
+  const x = view.contentOrigin + RANGE_MARGIN_PX;
+  return { x, width: Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX) };
+}
+
 /** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
 export function currentTimelineRange(): { start: number; end: number } | null {
   const view = viewport;
-  if (!view) return null;
-  const { pps, left } = shown(view.scroll);
-  if (!(pps > 0)) return null;
-  const x = view.contentOrigin + RANGE_MARGIN_PX;
-  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
-  const start = (left + x - view.contentOrigin) / pps;
+  const pps = view ? shown(view.scroll).pps : 0;
+  if (!view || !(pps > 0)) return null;
+  const { x, width } = rangeBox(view);
+  const start = timelineTimeAtX(x)!;
   return { start, end: start + width / pps };
 }
 
@@ -318,10 +327,11 @@ function easeToRange(
     return Promise.resolve("cancelled");
   let resolveThis: (result: TimelineZoomResult) => void = () => {};
   const result = new Promise<TimelineZoomResult>((resolve) => (resolveThis = resolve));
-  settle = resolveThis;
-  signal?.addEventListener("abort", () => settle === resolveThis && stopEase(), { once: true });
-  const x = view.contentOrigin + RANGE_MARGIN_PX;
-  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
+  resolveEase = resolveThis;
+  signal?.addEventListener("abort", () => resolveEase === resolveThis && stopEase(), {
+    once: true,
+  });
+  const { x, width } = rangeBox(view);
   const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
   const finish = () => {
     commitPreview();
@@ -335,8 +345,8 @@ function easeToRange(
   }
   const fromPercent = currentTimelineZoomPercent();
   const from = shown(view.scroll);
-  const toPps = (fitPps * toPercent) / 100;
-  const fromStart = (from.left + x - view.contentOrigin) / from.pps;
+  const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
+  const fromStart = timelineTimeAtX(x)!;
   // The one point both views put at the same place on screen; zooming about it, in log space,
   // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
   const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
@@ -362,7 +372,7 @@ function easeToRange(
  * or centring it when it is off screen.
  */
 export function zoomTimelineStep(direction: "in" | "out"): void {
-  const { timelineFitPps: fitPps, currentTime } = usePlayerStore.getState();
+  const fitPps = usePlayerStore.getState().timelineFitPps;
   const nextPercent = getNextTimelineZoomPercent(
     direction,
     "manual",
@@ -374,13 +384,10 @@ export function zoomTimelineStep(direction: "in" | "out"): void {
     requestTimelineZoom(nextPercent);
     return;
   }
-  const x = view.contentOrigin + RANGE_MARGIN_PX;
-  const width = Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX);
-  const nextPps = (fitPps * nextPercent) / 100;
-  const span = width / nextPps;
+  const { x, width } = rangeBox(view);
+  const nextPps = getTimelinePixelsPerSecond(fitPps, "manual", nextPercent);
   const now = shown(view.scroll);
-  const playheadX = view.contentOrigin + currentTime * now.pps - now.left;
-  const onScreen = playheadX >= view.contentOrigin && playheadX <= view.scroll.clientWidth;
-  const start = onScreen ? currentTime - (playheadX - x) / nextPps : currentTime - span / 2;
-  void easeToRange(start, start + span, {}, true);
+  const at = defaultAnchor(view, now.pps, now.left);
+  const start = at.time - (at.x - x) / nextPps;
+  void easeToRange(start, start + width / nextPps, {}, true);
 }
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 1be6e6324cb..67b752976c0 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -254,7 +254,8 @@ describe("useTimelinePlayhead wheel zoom", () => {
     vi.useRealTimers();
   });
 
-  const wheel = (scroll: HTMLDivElement, init: WheelEventInit) =>
+  /** A wheel step 432px in, previewed for one frame. */
+  const previewWheel = (scroll: HTMLDivElement, init: WheelEventInit) =>
     act(() => {
       const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true, ...init });
       // happy-dom's WheelEvent drops the MouseEvent fields of its init.
@@ -264,11 +265,15 @@ describe("useTimelinePlayhead wheel zoom", () => {
         metaKey: { value: Boolean(init.metaKey) },
       });
       scroll.dispatchEvent(event);
-      // The preview's frame, then its rest, when the zoom is laid out.
       vi.advanceTimersToNextFrame();
-      vi.advanceTimersByTime(200);
     });
 
+  /** A wheel step, then the rest at which its zoom is laid out. */
+  const wheel = (scroll: HTMLDivElement, init: WheelEventInit) => {
+    previewWheel(scroll, init);
+    act(() => vi.advanceTimersByTime(200));
+  };
+
   it("zooms on Cmd+wheel as on a pinch, and leaves a plain wheel to scroll", () => {
     const scroll = scrollBox(0);
     mount({ scroll });
@@ -281,16 +286,7 @@ describe("useTimelinePlayhead wheel zoom", () => {
   it("lays a pending pinch out at once when the timeline is pressed", () => {
     const scroll = scrollBox(0);
     mount({ scroll });
-    act(() => {
-      const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true });
-      Object.defineProperties(event, {
-        clientX: { value: 432 },
-        ctrlKey: { value: true },
-        metaKey: { value: false },
-      });
-      scroll.dispatchEvent(event);
-      vi.advanceTimersToNextFrame();
-    });
+    previewWheel(scroll, { ctrlKey: true });
     expect(usePlayerStore.getState().timelinePps).toBe(100);
     act(() => {
       scroll.dispatchEvent(new Event("pointerdown"));
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 2af840b34ea..6496778e568 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -77,8 +77,8 @@ export function useTimelinePlayhead({
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // A zoom that names an anchor (pinch, zoom-to-range) keeps that time where it was; a toolbar zoom
-  // keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
+  // A zoom keeps its anchor's time where it was (pinch: the pointer; buttons and slider: the
+  // playhead); a resize keeps the centre, or 00:00 at the start.
   const previousAnchorPpsRef = useRef(pps);
   const userZoomCount = usePlayerStore((s) => s.userZoomCount);
   const previousZoomCountRef = useRef(userZoomCount);

From 84178970a92ac0ca32d80b618f75258923179cce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 15:02:29 -0400
Subject: [PATCH 16/26] fix(studio): keep a zoom preview through scrolls and
 past the content end

A scroll during a zoom preview, including the one a laid-out zoom makes
itself, used to lay the next preview out at once, so a pinch or eased zoom
fell back to a full layout every frame. A scroll now only rescales what it
mounted. Zooming out also lays out before the preview shows past where the
ruler and beat lines are drawn, not only past the mounted clips.
---
 .../src/components/TimelineToolbar.test.tsx   |  2 ++
 .../components/timelineZoomInput.test.ts      | 25 ++++++++++++++++-
 .../player/components/timelineZoomInput.ts    | 28 +++++++++++++------
 .../components/useTimelinePlayhead.test.tsx   | 13 +++++++++
 .../player/components/useTimelinePlayhead.ts  |  7 +++--
 5 files changed, 62 insertions(+), 13 deletions(-)

diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index faae99f5a18..b35d299c4b7 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -261,6 +261,8 @@ describe("TimelineToolbar Fit", () => {
     const scroll = document.createElement("div");
     Object.defineProperties(scroll, {
       clientWidth: { value: 1080 },
+      // At Fit the content is as wide as the view.
+      scrollWidth: { value: 1080 },
       scrollLeft: { value: 0, writable: true },
     });
     usePlayerStore.setState({
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 86293c3623a..735082ec8aa 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
 import {
   cancelTimelineZoom,
+  redrawTimelineZoomPreview,
   currentTimelineRange,
   currentTimelineZoomPercent,
   settleTimelineZoom,
@@ -47,10 +48,11 @@ afterEach(() => {
 let unregisterViewport = () => {};
 
 /** A 1080px timeline viewport with 32px of track headers, holding one scaled row. */
-function viewport(scrollLeft = 0) {
+function viewport(scrollLeft = 0, scrollWidth = 20_000) {
   const scroll = document.createElement("div");
   Object.defineProperties(scroll, {
     clientWidth: { value: 1080 },
+    scrollWidth: { value: scrollWidth },
     scrollLeft: { value: scrollLeft, writable: true },
   });
   const row = scroll.appendChild(document.createElement("div"));
@@ -135,6 +137,27 @@ describe("requestTimelineZoom", () => {
     expect(usePlayerStore.getState().timelinePps).toBe(100);
   });
 
+  it("lays a zoom-out out at once before it shows past where the ruler is drawn", () => {
+    // 50 s of clips at Fit: the ruler and lanes are drawn to the viewport's edge, 104.8 s.
+    usePlayerStore.setState({ duration: 50 });
+    viewport(0, 1080);
+    requestTimelineZoom(50, { time: 0, x: 32 });
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(5);
+  });
+
+  it("keeps previewing through a scroll, and scales the rows the scroll mounted", () => {
+    const { scroll } = viewport();
+    requestTimelineZoom(150);
+    vi.advanceTimersToNextFrame();
+    const mountedRow = scroll.appendChild(document.createElement("div"));
+    mountedRow.setAttribute("data-timeline-zoom-scale", "");
+    redrawTimelineZoomPreview();
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(10);
+    expect(mountedRow.style.transform).toContain("scaleX(1.5)");
+  });
+
   it("lays a pending zoom out at once when settled, as a press does", () => {
     viewport();
     requestTimelineZoom(150);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index ca5741ddcb8..82cebe72919 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -34,8 +34,8 @@ interface ZoomPreview {
   pps: number;
   shift: number;
   basePps: number;
-  /** The times with clips mounted when the preview began; past them it would show gaps. */
-  mounted: TimelineTimeRange;
+  /** The times laid out (clips mounted, ruler drawn) when it began; past them it shows gaps. */
+  drawn: TimelineTimeRange;
   byPerson: boolean;
 }
 
@@ -142,11 +142,17 @@ function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigi
   const left = scroll.scrollLeft - p.shift;
   const start = left / p.pps;
   const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
+  return start < p.drawn.start || end > p.drawn.end;
+}
+
+/** The times laid out now: the clips mounted, and the ruler and beat lines to the content's end. */
+function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
   const duration = usePlayerStore.getState().duration || Number.POSITIVE_INFINITY;
-  return (
-    (p.mounted.start > 0 && start < p.mounted.start) ||
-    (p.mounted.end < duration && end > p.mounted.end)
-  );
+  const mounted = getTimelineRenderTimeRange(scroll, pps, contentOrigin, duration);
+  const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
+  // Past the last clip only the ruler matters, and it is drawn to the content's end.
+  const end = mounted.end < duration ? Math.min(mounted.end, contentEnd) : contentEnd;
+  return { start: mounted.start, end };
 }
 
 function drawPreview() {
@@ -207,13 +213,12 @@ function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: b
   const { scroll, contentOrigin } = view;
   const now = shown(scroll);
   const at = anchor ?? defaultAnchor(view, now.pps, now.left);
-  const duration = usePlayerStore.getState().duration || Number.POSITIVE_INFINITY;
   preview ??= {
     percent: clamped,
     pps,
     shift: 0,
     basePps: now.pps,
-    mounted: getTimelineRenderTimeRange(scroll, now.pps, contentOrigin, duration),
+    drawn: drawnRange(scroll, now.pps, contentOrigin),
     byPerson,
   };
   // The content's width at this scale: the fit track (getTimelineFitPps), never narrower.
@@ -236,11 +241,16 @@ export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor
   request(percent, anchor, true);
 }
 
-/** Lays out a pending zoom now, so what comes next (a press, a scroll) meets the real layout. */
+/** Lays out a pending zoom now, so a press meets the real layout. */
 export function settleTimelineZoom(): void {
   if (preview) commitPreview();
 }
 
+/** After a scroll: scales what it mounted, or lays the zoom out if it shows past what is drawn. */
+export function redrawTimelineZoomPreview(): void {
+  if (preview && !frame) frame = requestAnimationFrame(drawPreview);
+}
+
 /** Drops any pending or easing zoom without laying it out, as Fit does. */
 export function cancelTimelineZoom(): void {
   stopEase();
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 67b752976c0..528f3fb43a5 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -283,6 +283,19 @@ describe("useTimelinePlayhead wheel zoom", () => {
     expect(usePlayerStore.getState().manualZoomPercent).toBeGreaterThan(100);
   });
 
+  it("keeps previewing a pinch through a scroll, laying it out only at rest", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    previewWheel(scroll, { ctrlKey: true });
+    act(() => {
+      scroll.dispatchEvent(new Event("scroll"));
+      vi.advanceTimersToNextFrame();
+    });
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+    act(() => vi.advanceTimersByTime(200));
+    expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+  });
+
   it("lays a pending pinch out at once when the timeline is pressed", () => {
     const scroll = scrollBox(0);
     mount({ scroll });
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 6496778e568..0d10fc28de1 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -6,6 +6,7 @@ import {
   currentTimelineZoomPercent,
   requestTimelineZoom,
   registerTimelineZoomViewport,
+  redrawTimelineZoomPreview,
   settleTimelineZoom,
   subscribeTimelineZoomPreview,
   takeTimelineZoomAnchor,
@@ -278,14 +279,14 @@ export function useTimelinePlayhead({
     const scroll = scrollRef.current;
     if (!scroll) return;
     scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
-    // A press or scroll meets the zoom it sees, not the one still waiting to be laid out.
+    // A press meets the zoom it sees, not the one still waiting to be laid out.
     scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
-    scroll.addEventListener("scroll", settleTimelineZoom, { passive: true });
+    scroll.addEventListener("scroll", redrawTimelineZoomPreview, { passive: true });
     const unregisterZoomViewport = registerTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
       scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
-      scroll.removeEventListener("scroll", settleTimelineZoom);
+      scroll.removeEventListener("scroll", redrawTimelineZoomPreview);
       unregisterZoomViewport();
     };
   }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);

From d6f41bb0195729c5b4d23ae594ecee057aa6706d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 15:13:13 -0400
Subject: [PATCH 17/26] fix(studio): keep a moved audio clip's waveform drawn
 where it shows

A waveform now draws the stretch of its clip that the shared strip tracker
reports near the screen, the tracker the filmstrip already uses. It follows
scrolls, resizes and moves (a drag or ripple that shifts the clip), so a
moved clip no longer shows a blank stretch, and a zoom redraws it once.
---
 .../player/components/AudioWaveform.test.tsx  | 78 +++++++++----------
 .../src/player/components/AudioWaveform.tsx   | 72 ++++-------------
 .../src/player/components/timelineMotion.ts   | 10 +--
 .../components/timelineZoomInput.test.ts      |  2 +-
 .../player/components/timelineZoomInput.ts    |  8 +-
 5 files changed, 63 insertions(+), 107 deletions(-)

diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index b0f2f0f12cb..1dfb18929f2 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -11,8 +11,34 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
   useThumbnailLease: leaseSpy,
 }));
 
+const EMPTY_STRIP = { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 };
+const strip = vi.hoisted(() => ({
+  size: { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 },
+  listeners: new Set<() => void>(),
+}));
+// The strip hook's own tests cover scrolls and moves; here it reports what the test sets.
+vi.mock("../../hooks/useThumbnailStripSize", async () => {
+  const { useSyncExternalStore } = await import("react");
+  const subscribe = (listener: () => void) => {
+    strip.listeners.add(listener);
+    return () => strip.listeners.delete(listener);
+  };
+  return {
+    useThumbnailStripSize: () => [
+      useSyncExternalStore(subscribe, () => strip.size),
+      () => {},
+      () => {},
+    ],
+  };
+});
+
+const setStrip = (size: typeof EMPTY_STRIP) =>
+  act(() => {
+    strip.size = size;
+    strip.listeners.forEach((listener) => listener());
+  });
+
 import { AudioWaveform, drawWaveformCanvas } from "./AudioWaveform";
-import { markTimelineMotion } from "./timelineMotion";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -24,6 +50,7 @@ afterEach(() => {
   vi.useRealTimers();
   leaseSpy.mockReset();
   leaseSpy.mockImplementation(() => ({ status: "loading" as const }));
+  strip.size = EMPTY_STRIP;
   document.body.innerHTML = "";
 });
 
@@ -92,45 +119,18 @@ describe("AudioWaveform", () => {
     ]);
   });
 
-  it("redraws when the timeline comes to rest, not at each zoom step", () => {
-    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
-    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+  it("draws only the stretch of a long clip near the screen, and follows it as the clip moves", () => {
+    vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
     renderReadyWaveform();
-    const drawn = getContext.mock.calls.length;
-    expect(drawn).toBeGreaterThan(0);
-    act(() => markTimelineMotion());
-    expect(getContext.mock.calls.length).toBe(drawn);
-    act(() => vi.runOnlyPendingTimers());
-    expect(getContext.mock.calls.length).toBe(drawn + 1);
-  });
-
-  it("redraws on scroll only once the view leaves the drawn stretch, as playback follows", () => {
-    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
-    const scroller = document.createElement("div");
-    scroller.setAttribute("data-timeline-scroll-viewport", "");
-    document.body.append(scroller);
-    // A 10000px clip in a 1000px view; the clip's left edge moves as the view scrolls.
-    let clipLeft = 0;
-    vi.spyOn(Element.prototype, "getBoundingClientRect").mockImplementation(
-      function (this: Element) {
-        return (
-          this === scroller
-            ? { left: 0, right: 1000, width: 1000 }
-            : { left: clipLeft, right: clipLeft + 10_000, width: 10_000 }
-        ) as DOMRect;
-      },
-    );
-    renderReadyWaveform(scroller);
-    const drawn = getContext.mock.calls.length;
-    const scrollTo = (left: number) => {
-      clipLeft = -left;
-      act(() => scroller.dispatchEvent(new Event("scroll")));
-    };
-    // Drawn to 2000px, one view past the screen: 500..1500 is still drawn.
-    scrollTo(500);
-    expect(getContext.mock.calls.length).toBe(drawn);
-    scrollTo(1500);
-    expect(getContext.mock.calls.length).toBe(drawn + 1);
+    const canvas = document.querySelector("canvas")!;
+    const placed = () => [parseFloat(canvas.style.left), parseFloat(canvas.style.width)];
+    expect(placed()[0]).toBeCloseTo(20.48);
+    expect(placed()[1]).toBeCloseTo(20.48);
+    // A move or scroll carries the clip: the hook reports a new stretch and the bars follow.
+    setStrip({ width: 10_000, height: 40, inViewStart: 4096, inViewEnd: 6144 });
+    expect(placed()[0]).toBeCloseTo(40.96);
+    expect(placed()[1]).toBeCloseTo(20.48);
   });
 
   it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index f32d31b6ca5..009e261bb66 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -1,11 +1,10 @@
 import { memo, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 import { fadeGain } from "@hyperframes/core/audio-fade";
-import { useMountEffect } from "../../hooks/useMountEffect";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
-import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface AudioWaveformProps {
@@ -32,24 +31,8 @@ export const WAVEFORM_LAYER_Z = 10;
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
 /** A stretch of the clip as fractions of its width. */
-export type ClipSpan = { from: number; to: number };
+type ClipSpan = { from: number; to: number };
 const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
-// Drawn past the viewport by this many widths each side, so a short scroll shows bars already drawn.
-const OVERSCAN_VIEWPORTS = 1;
-
-/** The part of the clip on screen, with overscan; a long clip never draws past it. */
-function visibleClipSpan(root: HTMLElement, overscan = OVERSCAN_VIEWPORTS): ClipSpan {
-  const box = root.getBoundingClientRect();
-  if (box.width <= 0) return WHOLE_CLIP;
-  const scroller = root.closest("[data-timeline-scroll-viewport]");
-  const view = scroller?.getBoundingClientRect() ?? { left: 0, right: window.innerWidth };
-  const margin = (view.right - view.left) * overscan;
-  const clamp = (x: number) => Math.max(0, Math.min(1, x));
-  const from = clamp((view.left - margin - box.left) / box.width);
-  const to = clamp((view.right + margin - box.left) / box.width);
-  return { from, to: Math.max(from, to) };
-}
-
 function paintWaveformBars(
   context: CanvasRenderingContext2D,
   bars: readonly BarGeometry[],
@@ -218,14 +201,15 @@ export const AudioWaveform = memo(function AudioWaveform({
     snapshot.status === "ready" && snapshot.value.kind === "waveform" ? snapshot.value.peaks : null;
 
   const fades = useContext(ClipFadesContext);
-  const drawnSpan = useRef<ClipSpan | null>(null);
+  // The clip's size and the stretch of it near the screen, kept current through scrolls and moves.
+  const [strip, setStripRef] = useThumbnailStripSize();
+  const from = strip.width > 0 ? strip.inViewStart / strip.width : 0;
+  const to = strip.width > 0 ? strip.inViewEnd / strip.width : 1;
   const draw = useCallback(() => {
     const canvas = canvasRef.current;
-    const root = rootRef.current;
-    if (!canvas || !root || !peaks) return;
-    const span = visibleClipSpan(root);
-    drawnSpan.current = span;
-    // Placed in fractions of the clip, so a zoom stretches the drawn bars with time until the redraw.
+    if (!canvas || !peaks) return;
+    const span = { from, to };
+    // Placed in fractions of the clip, so a zoom preview stretches the drawn bars with time.
     canvas.style.left = `${span.from * 100}%`;
     canvas.style.width = `${(span.to - span.from) * 100}%`;
     if (span.to <= span.from) return;
@@ -238,35 +222,9 @@ export const AudioWaveform = memo(function AudioWaveform({
       fades,
       span,
     );
-  }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
-  const drawRef = useRef(draw);
-  drawRef.current = draw;
-  useEffect(draw, [draw]);
-
-  // Redrawn when the clip resizes or a zoom comes to rest, never per zoom step: a step only
-  // stretches what is drawn. A scroll redraws only once the view leaves the drawn stretch.
-  useMountEffect(() => {
-    const root = rootRef.current;
-    const redrawAtRest = () => {
-      if (!isTimelineMoving()) drawRef.current();
-    };
-    const redrawIfUncovered = () => {
-      const drawn = drawnSpan.current;
-      if (!root || !drawn || isTimelineMoving()) return;
-      const seen = visibleClipSpan(root, 0);
-      if (seen.from < drawn.from || seen.to > drawn.to) drawRef.current();
-    };
-    const observer = root ? new ResizeObserver(redrawAtRest) : null;
-    if (root) observer?.observe(root);
-    const scroller = root?.closest("[data-timeline-scroll-viewport]");
-    scroller?.addEventListener("scroll", redrawIfUncovered, { passive: true });
-    const unsubscribe = subscribeTimelineMotion(redrawAtRest);
-    return () => {
-      observer?.disconnect();
-      scroller?.removeEventListener("scroll", redrawIfUncovered);
-      unsubscribe();
-    };
-  });
+  }, [fades, from, muted, peaks, to, trimEndFraction, trimStartFraction]);
+  // Also on a height change: the bars are drawn at the canvas size, which follows the clip.
+  useEffect(draw, [draw, strip.height]);
 
   useEffect(() => {
     const root = document.documentElement;
@@ -288,7 +246,11 @@ export const AudioWaveform = memo(function AudioWaveform({
 
   return (
     <div ref={rootRef} className="absolute inset-0">
-      <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
+      <div
+        ref={setStripRef}
+        className="absolute inset-0 overflow-hidden"
+        style={{ zIndex: WAVEFORM_LAYER_Z }}
+      >
         <canvas
           ref={canvasRef}
           className="absolute bottom-0"
diff --git a/packages/studio/src/player/components/timelineMotion.ts b/packages/studio/src/player/components/timelineMotion.ts
index 9d88c3f2892..2fda7a3b527 100644
--- a/packages/studio/src/player/components/timelineMotion.ts
+++ b/packages/studio/src/player/components/timelineMotion.ts
@@ -1,7 +1,7 @@
 import { useState, useSyncExternalStore } from "react";
 
 /** How long the timeline must go without a zoom step to count as at rest. */
-const TIMELINE_REST_MS = 150;
+export const TIMELINE_REST_MS = 150;
 
 let moving = false;
 let restTimer: ReturnType<typeof setTimeout> | null = null;
@@ -32,14 +32,10 @@ export function subscribeTimelineMotion(listener: () => void): () => void {
   return () => listeners.delete(listener);
 }
 
-/** True while the timeline zooms; re-renders only when that starts and when it rests. */
-function useTimelineMoving(): boolean {
-  return useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
-}
-
 /** `value` at rest; while the timeline moves, the value it had when it last rested. */
 export function useValueAtRest<T>(value: T): T {
-  const moving = useTimelineMoving();
+  // Re-renders only when a zoom starts and when it rests.
+  const moving = useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
   const [held, setHeld] = useState(value);
   if (!moving && !Object.is(held, value)) setHeld(value);
   return moving ? held : value;
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 0afcd741273..0ed2cc874ab 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -1,8 +1,8 @@
 // @vitest-environment happy-dom
 
-import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
+import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
 import {
   cancelTimelineZoom,
   redrawTimelineZoomPreview,
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index ad6edb80222..dca87856eee 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -2,7 +2,7 @@ import { useSyncExternalStore } from "react";
 import { flushSync } from "react-dom";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 import { usePlayerStore } from "../store/playerStore";
-import { markTimelineMotion } from "./timelineMotion";
+import { markTimelineMotion, TIMELINE_REST_MS } from "./timelineMotion";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 import {
   clampTimelineZoomPercent,
@@ -42,8 +42,6 @@ interface ZoomPreview {
 
 const RANGE_MARGIN_PX = 24;
 const SMOOTH_ZOOM_MS = 220;
-/** How long a gesture holds still before its zoom is laid out for real. */
-const REST_MS = 150;
 /** Past this the scaled-up preview turns soft. */
 const MAX_PREVIEW_SCALE = 4;
 const SCALED = "[data-timeline-zoom-scale]";
@@ -233,8 +231,8 @@ function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: b
   preview.byPerson ||= byPerson;
   if (!frame) frame = requestAnimationFrame(drawPreview);
   if (restTimer) clearTimeout(restTimer);
-  restTimer = setTimeout(commitPreview, REST_MS);
-  // After the commit timer, so the zoom is laid out before the timeline counts as at rest.
+  restTimer = setTimeout(commitPreview, TIMELINE_REST_MS);
+  // After the commit timer of the same delay, so the zoom is laid out before the timeline rests.
   markTimelineMotion();
 }
 

From 582652efef7f32180b0835810c16d2ae26cf8444 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 16:25:15 -0400
Subject: [PATCH 18/26] perf(studio): lay a zoom-out step out once, at its
 start

An eased zoom-out (a Zoom out click, or zooming out to a range) used to
lay out partway, once the shrinking preview reached time with nothing
mounted, and again at the end. It now lays the target out first and eases
by scaling that layout down from the old view, so each click lays out
once. Each eased frame also draws its preview in that frame.
---
 .../components/timelineZoomInput.test.ts      | 24 +++++++++++++++++++
 .../player/components/timelineZoomInput.ts    | 24 ++++++++++++++++++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 735082ec8aa..388cb374722 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -322,6 +322,30 @@ describe("zoomTimelineStep", () => {
     expect(laidOutX(40)).toBeCloseTo(432);
   });
 
+  it("lays a zoom-out step out once, at its start, then eases by scaling", () => {
+    usePlayerStore.setState({
+      currentTime: 110,
+      duration: 1000,
+      zoomMode: "manual",
+      manualZoomPercent: 400,
+      timelinePps: 40,
+    });
+    // 100..126 s on screen at 40 px/s, the playhead at 110 s among it.
+    const { row } = viewport(4000);
+    const laidOut: number[] = [];
+    const unsubscribe = usePlayerStore.subscribe((s, prev) => {
+      if (s.timelinePps !== prev.timelinePps) laidOut.push(s.timelinePps);
+    });
+    zoomTimelineStep("out");
+    expect(laidOut).toEqual([20]);
+    vi.advanceTimersToNextFrame();
+    // Near the old view, drawn in the first frame by scaling the new layout up.
+    expect(Number(/scaleX\(([\d.]+)\)/.exec(row.style.transform)?.[1])).toBeGreaterThan(1.5);
+    run();
+    unsubscribe();
+    expect(laidOut).toEqual([20]);
+  });
+
   it("centres an off-screen playhead", () => {
     usePlayerStore.setState({
       currentTime: 60,
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 82cebe72919..c529b407e2c 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -156,6 +156,7 @@ function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number):
 }
 
 function drawPreview() {
+  cancelAnimationFrame(frame);
   frame = 0;
   const view = viewport;
   if (!preview || !view) return;
@@ -353,6 +354,20 @@ function easeToRange(
     animation = requestAnimationFrame(finish);
     return result;
   }
+  easeZoom(view, fitPps, toPercent, { time: start, x }, byPerson, finish);
+  return result;
+}
+
+/** Eases from the zoom shown now to `toPercent`, landing `to.time` at `to.x`, then `finish`es. */
+function easeZoom(
+  view: TimelineZoomViewport,
+  fitPps: number,
+  toPercent: number,
+  to: TimelineZoomAnchor,
+  byPerson: boolean,
+  finish: () => void,
+) {
+  const { time: start, x } = to;
   const fromPercent = currentTimelineZoomPercent();
   const from = shown(view.scroll);
   const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
@@ -364,17 +379,24 @@ function easeToRange(
     shift === null
       ? { time: fromStart + (start - fromStart) * k, x }
       : { time: fromStart + shift / from.pps, x: x + shift };
+  // Zooming out shows time the current layout never mounted, so lay the target out once now and
+  // ease by scaling it down from the old view, instead of laying out again partway.
+  if (toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE) {
+    request(toPercent, { time: start, x }, byPerson);
+    commitPreview();
+  }
   const began = performance.now();
   easingTo = toPercent;
   const step = (now: number) => {
     const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
     const k = 1 - (1 - t) ** 3;
     request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);
+    // Drawn in this frame, not the next: the first one would otherwise paint a laid-out zoom-out bare.
+    drawPreview();
     if (t < 1) animation = requestAnimationFrame(step);
     else finish();
   };
   animation = requestAnimationFrame(step);
-  return result;
 }
 
 /**

From 518881f54a73567857f0ea7e49a4a7a13a512e90 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 16:35:25 -0400
Subject: [PATCH 19/26] fix(studio): keep previewing a zoom at the content's
 end and over new rows

The preview now lays out only once it would show past the window the
timeline draws clips, ruler ticks and beat lines in, with two pixels of
slack, so rounding at the content's end no longer lays out every frame.
Rows mounted into the timeline during a preview are scaled before they
paint.
---
 .../components/timelineZoomInput.test.ts      | 19 +++++--
 .../player/components/timelineZoomInput.ts    | 52 +++++++++++++------
 2 files changed, 52 insertions(+), 19 deletions(-)

diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 388cb374722..becbc2734bb 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -146,14 +146,27 @@ describe("requestTimelineZoom", () => {
     expect(usePlayerStore.getState().timelinePps).toBe(5);
   });
 
-  it("keeps previewing through a scroll, and scales the rows the scroll mounted", () => {
+  it("previews a zoom-out at the content's end without laying out each frame", () => {
+    // At 330% the content is 32 + 1046 * 3.3 = 3483.8px, reported whole as 3483; the view is
+    // scrolled to its end, and a zoom-out lands that end a fraction of a pixel past it.
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 330, timelinePps: 33 });
+    viewport(2403, 3483);
+    requestTimelineZoom(300, { time: 100, x: 800 });
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(33);
+  });
+
+  it("keeps previewing through a scroll, and scales the rows the scroll mounted", async () => {
     const { scroll } = viewport();
     requestTimelineZoom(150);
     vi.advanceTimersToNextFrame();
-    const mountedRow = scroll.appendChild(document.createElement("div"));
-    mountedRow.setAttribute("data-timeline-zoom-scale", "");
+    // React mounts the row after the scroll's redraw frame; it is scaled before it paints.
     redrawTimelineZoomPreview();
     vi.advanceTimersToNextFrame();
+    const mountedRow = document.createElement("div");
+    mountedRow.setAttribute("data-timeline-zoom-scale", "");
+    scroll.appendChild(document.createElement("div")).appendChild(mountedRow);
+    await Promise.resolve();
     expect(usePlayerStore.getState().timelinePps).toBe(10);
     expect(mountedRow.style.transform).toContain("scaleX(1.5)");
   });
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index c529b407e2c..2046031a79c 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -45,9 +45,13 @@ const SMOOTH_ZOOM_MS = 220;
 const REST_MS = 150;
 /** Past this the scaled-up preview turns soft. */
 const MAX_PREVIEW_SCALE = 4;
+/** Rounding at a drawn edge (whole-pixel content width, the fit track's 2px) is not a gap. */
+const EDGE_SLACK_PX = 2;
 const SCALED = "[data-timeline-zoom-scale]";
 
 let viewport: TimelineZoomViewport | null = null;
+/** While a preview shows, scales rows and strips React mounts into the timeline before they paint. */
+let mounts: MutationObserver | null = null;
 let preview: ZoomPreview | null = null;
 let frame = 0;
 let restTimer: ReturnType<typeof setTimeout> | null = null;
@@ -120,8 +124,10 @@ function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson:
 
 const emitPreview = () => previewListeners.forEach((listener) => listener());
 
-/** Stops the pending preview frame and rest timer. */
+/** Stops the pending preview frame, rest timer and mount watch. */
 function cancelPending() {
+  mounts?.disconnect();
+  mounts = null;
   if (restTimer) clearTimeout(restTimer);
   restTimer = null;
   cancelAnimationFrame(frame);
@@ -142,17 +148,37 @@ function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigi
   const left = scroll.scrollLeft - p.shift;
   const start = left / p.pps;
   const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
-  return start < p.drawn.start || end > p.drawn.end;
+  const slack = EDGE_SLACK_PX / p.pps;
+  return start < p.drawn.start - slack || end > p.drawn.end + slack;
 }
 
-/** The times laid out now: the clips mounted, and the ruler and beat lines to the content's end. */
+/** The times laid out now: the render window clips, ruler ticks and beat lines are drawn in. */
 function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
-  const duration = usePlayerStore.getState().duration || Number.POSITIVE_INFINITY;
-  const mounted = getTimelineRenderTimeRange(scroll, pps, contentOrigin, duration);
+  // The timeline clamps that window to its content's end, as wide as the scroll content.
   const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
-  // Past the last clip only the ruler matters, and it is drawn to the content's end.
-  const end = mounted.end < duration ? Math.min(mounted.end, contentEnd) : contentEnd;
-  return { start: mounted.start, end };
+  return getTimelineRenderTimeRange(scroll, pps, contentOrigin, contentEnd);
+}
+
+function scalePreview(scroll: HTMLElement) {
+  if (!preview) return;
+  const transform = `translateX(${preview.shift}px) scaleX(${preview.pps / preview.basePps})`;
+  scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+    // The attribute's value is where time zero sits in the element, when not at its left edge.
+    el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
+    el.style.willChange = "transform";
+    el.style.transform = transform;
+  });
+}
+
+const holdsScaled = (node: Node) =>
+  node instanceof Element && (node.matches(SCALED) || node.querySelector(SCALED) !== null);
+
+function watchMounts(scroll: HTMLElement): MutationObserver {
+  const observer = new MutationObserver((records) => {
+    if (records.some((record) => [...record.addedNodes].some(holdsScaled))) scalePreview(scroll);
+  });
+  observer.observe(scroll, { childList: true, subtree: true });
+  return observer;
 }
 
 function drawPreview() {
@@ -164,14 +190,8 @@ function drawPreview() {
     commitPreview();
     return;
   }
-  const scale = preview.pps / preview.basePps;
-  const transform = `translateX(${preview.shift}px) scaleX(${scale})`;
-  view.scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
-    // The attribute's value is where time zero sits in the element, when not at its left edge.
-    el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
-    el.style.willChange = "transform";
-    el.style.transform = transform;
-  });
+  scalePreview(view.scroll);
+  mounts ??= watchMounts(view.scroll);
   emitPreview();
 }
 

From 25933445db5c53322a8188b35140b66e9feaa099 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 16:44:14 -0400
Subject: [PATCH 20/26] fix(studio): redraw a waveform when its clip's width
 changes or it moves

A waveform drawn whole kept its old bars, stretched, after a zoom changed
its clip's width; it now redraws on any resize. A long clip also marks
its undrawn ends for the strip tracker, so a move without a scroll (a
ripple, a drop, an undo) re-measures it instead of leaving a blank
stretch.
---
 .../player/components/AudioWaveform.test.tsx  | 31 ++++++++++++++++---
 .../src/player/components/AudioWaveform.tsx   | 17 ++++++++--
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index 1dfb18929f2..e4f224871f3 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -12,6 +12,7 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
 }));
 
 const EMPTY_STRIP = { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 };
+const watchGap = vi.hoisted(() => vi.fn());
 const strip = vi.hoisted(() => ({
   size: { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 },
   listeners: new Set<() => void>(),
@@ -27,7 +28,7 @@ vi.mock("../../hooks/useThumbnailStripSize", async () => {
     useThumbnailStripSize: () => [
       useSyncExternalStore(subscribe, () => strip.size),
       () => {},
-      () => {},
+      watchGap,
     ],
   };
 });
@@ -51,14 +52,15 @@ afterEach(() => {
   leaseSpy.mockReset();
   leaseSpy.mockImplementation(() => ({ status: "loading" as const }));
   strip.size = EMPTY_STRIP;
+  watchGap.mockClear();
   document.body.innerHTML = "";
 });
 
 /** Renders a ready waveform for a two-peak sound into `parent`. */
 function renderReadyWaveform(parent: HTMLElement = document.body) {
-  leaseSpy.mockImplementation(
-    () => ({ status: "ready", value: { kind: "waveform", peaks: [0.5, 1] } }) as never,
-  );
+  // One snapshot, as the lease returns, so a re-render alone does not redraw.
+  const ready = { status: "ready", value: { kind: "waveform", peaks: [0.5, 1] } } as never;
+  leaseSpy.mockImplementation(() => ready);
   const host = document.createElement("div");
   parent.append(host);
   const root = createRoot(host);
@@ -133,6 +135,27 @@ describe("AudioWaveform", () => {
     expect(placed()[1]).toBeCloseTo(20.48);
   });
 
+  it("redraws a short clip, drawn whole, when a zoom changes its width", () => {
+    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+    renderReadyWaveform();
+    const drawn = getContext.mock.calls.length;
+    setStrip({ width: 2000, height: 40, inViewStart: 0, inViewEnd: 2000 });
+    expect(getContext.mock.calls.length).toBe(drawn + 1);
+  });
+
+  it("watches both undrawn ends of a long clip, so a move without a scroll re-measures it", () => {
+    setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
+    renderReadyWaveform();
+    const gaps = [
+      ...new Set(watchGap.mock.calls.map(([gap]) => gap).filter(Boolean)),
+    ] as HTMLElement[];
+    expect(gaps.map((gap) => [gap.style.width, gap.style.left])).toEqual([
+      ["20.48%", ""],
+      ["", "40.96%"],
+    ]);
+  });
+
   it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
     const { canvas, fills } = recordingCanvas();
     // A 1 s fade-in on a 2 s clip: the first bar's centre (0.5 s) plays at half gain.
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 009e261bb66..77ecd674473 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -202,7 +202,7 @@ export const AudioWaveform = memo(function AudioWaveform({
 
   const fades = useContext(ClipFadesContext);
   // The clip's size and the stretch of it near the screen, kept current through scrolls and moves.
-  const [strip, setStripRef] = useThumbnailStripSize();
+  const [strip, setStripRef, watchGap] = useThumbnailStripSize();
   const from = strip.width > 0 ? strip.inViewStart / strip.width : 0;
   const to = strip.width > 0 ? strip.inViewEnd / strip.width : 1;
   const draw = useCallback(() => {
@@ -223,8 +223,8 @@ export const AudioWaveform = memo(function AudioWaveform({
       span,
     );
   }, [fades, from, muted, peaks, to, trimEndFraction, trimStartFraction]);
-  // Also on a height change: the bars are drawn at the canvas size, which follows the clip.
-  useEffect(draw, [draw, strip.height]);
+  // Also on a resize: the bars are drawn at the canvas size, which follows the clip.
+  useEffect(draw, [draw, strip.width, strip.height]);
 
   useEffect(() => {
     const root = document.documentElement;
@@ -251,6 +251,17 @@ export const AudioWaveform = memo(function AudioWaveform({
         className="absolute inset-0 overflow-hidden"
         style={{ zIndex: WAVEFORM_LAYER_Z }}
       >
+        {/* The undrawn ends: one coming near the screen, as a move carries the clip, re-measures. */}
+        <div
+          ref={watchGap}
+          className="pointer-events-none absolute inset-y-0 left-0"
+          style={{ width: `${from * 100}%` }}
+        />
+        <div
+          ref={watchGap}
+          className="pointer-events-none absolute inset-y-0 right-0"
+          style={{ left: `${to * 100}%` }}
+        />
         <canvas
           ref={canvasRef}
           className="absolute bottom-0"

From c28f051ba71095760c4aef62bd29883b782649fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 17:00:44 -0400
Subject: [PATCH 21/26] perf(studio): skip the layout when a zoom preview ends
 on its own scale

An eased zoom-out lays its target out first, so its preview ends on the
scale already laid out. Landing it now only sets the scroll, instead of
writing the same zoom again and counting the person's zoom twice.
---
 .../src/player/components/timelineZoomInput.test.ts      | 2 ++
 .../studio/src/player/components/timelineZoomInput.ts    | 9 ++++++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index becbc2734bb..22994da385d 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -357,6 +357,8 @@ describe("zoomTimelineStep", () => {
     run();
     unsubscribe();
     expect(laidOut).toEqual([20]);
+    // Counted once as the person's zoom: the end of the ease writes nothing more.
+    expect(usePlayerStore.getState().userZoomCount).toBe(1);
   });
 
   it("centres an off-screen playhead", () => {
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 2046031a79c..18b9c7fef8e 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -202,9 +202,12 @@ function commitPreview() {
   const done = preview;
   if (!view || !done) return;
   const left = view.scroll.scrollLeft - done.shift;
-  flushSync(() =>
-    writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
-  );
+  // Ending at the scale already laid out (an eased zoom-out) needs a scroll, not a layout.
+  if (done.pps !== done.basePps) {
+    flushSync(() =>
+      writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
+    );
+  }
   preview = null;
   if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
   clearScaled(view.scroll);

From 92f96f2d3ca5ecb845016ffe9583bee2e2620e12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 17:20:58 -0400
Subject: [PATCH 22/26] fix(studio): measure filmstrips and waveforms after a
 zoom preview ends

The strip tracker measured clip boxes while a zoom preview scaled them,
so after a Zoom out click a long clip's filmstrip or waveform could stay
blank across part of the screen. Reads during a preview now wait, and the
tracker re-measures every strip once the preview ends. A zoom-out lays its
target out in its first frame rather than inside the caller, and only when
the new view holds the old one.
---
 .../src/hooks/useThumbnailStripSize.test.tsx  | 39 +++++++++++++++++++
 .../studio/src/hooks/useThumbnailStripSize.ts | 31 +++++++++++++++
 .../components/timelineZoomInput.test.ts      | 13 ++++++-
 .../player/components/timelineZoomInput.ts    | 26 +++++++++----
 4 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
index 5c6709c519a..6908d76298f 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
+++ b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
@@ -7,6 +7,15 @@ import { NearScreenIntersectionObserver } from "./intersectionObserverTestUtils"
 import { MockResizeObserver, reportResize } from "./resizeObserverTestUtils";
 import { useThumbnailStripSize } from "./useThumbnailStripSize";
 
+const zoom = vi.hoisted(() => ({ previewing: false, listeners: new Set<() => void>() }));
+vi.mock("../player/components/timelineZoomInput", () => ({
+  isTimelineZoomPreviewing: () => zoom.previewing,
+  subscribeTimelineZoomPreview: (listener: () => void) => {
+    zoom.listeners.add(listener);
+    return () => zoom.listeners.delete(listener);
+  },
+}));
+
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
 it("does not re-render the strip when the observer reports the size it already holds", () => {
@@ -48,6 +57,36 @@ it("does not re-render the strip when the observer reports the size it already h
   }
 });
 
+it("measures a strip once a zoom preview ends, not while the preview scales it", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const host = document.createElement("div");
+  document.body.append(host);
+  let width = 300;
+  Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+  const root = createRoot(host);
+  function Harness() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    zoom.previewing = true;
+    width = 600;
+    act(() => reportResize(600, 40));
+    expect(host.textContent).toBe("300x40");
+    zoom.previewing = false;
+    act(() => zoom.listeners.forEach((listener) => listener()));
+    expect(host.textContent).toBe("600x40");
+  } finally {
+    zoom.previewing = false;
+    act(() => root.unmount());
+    host.remove();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
 describe("on a scroll", () => {
   const originalResizeObserver = globalThis.ResizeObserver;
   const originalIntersectionObserver = globalThis.IntersectionObserver;
diff --git a/packages/studio/src/hooks/useThumbnailStripSize.ts b/packages/studio/src/hooks/useThumbnailStripSize.ts
index d000c90ea9c..4558ff26e87 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.ts
+++ b/packages/studio/src/hooks/useThumbnailStripSize.ts
@@ -1,5 +1,9 @@
 import { useCallback, useState } from "react";
 import { flushSync } from "react-dom";
+import {
+  isTimelineZoomPreviewing,
+  subscribeTimelineZoomPreview,
+} from "../player/components/timelineZoomInput";
 
 export interface StripSize {
   width: number;
@@ -62,6 +66,7 @@ let shared: {
   resize: ResizeObserver;
   presence: IntersectionObserver | null;
   gaps: IntersectionObserver | null;
+  stopZoomWatch: () => void;
 } | null = null;
 
 const offsetOf = (scroller: Element | null) =>
@@ -97,8 +102,31 @@ const read = (target: Element, strip: Strip) => {
 const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
   flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
 
+// A zoom preview scales the strips, so a box read then is wrong; reads wait for it to end.
+let staleSincePreview = false;
+const previewing = () => {
+  if (!isTimelineZoomPreviewing()) return false;
+  staleSincePreview = true;
+  return true;
+};
+
+const remeasureAfterPreview = () => {
+  if (!staleSincePreview || isTimelineZoomPreviewing()) return;
+  staleSincePreview = false;
+  commit(
+    [...strips].map(
+      ([target, strip]) =>
+        [
+          strip.apply,
+          { width: target.clientWidth, height: target.clientHeight, ...read(target, strip) },
+        ] as const,
+    ),
+  );
+};
+
 const refresh = () => {
   frame = 0;
+  if (previewing()) return;
   const offsetsNow = new Map<Element | null, { x: number; y: number }>();
   const updates: (readonly [Apply, Partial<StripSize>])[] = [];
   for (const [target, strip] of strips) {
@@ -122,6 +150,7 @@ const scheduleRefresh = () => {
 };
 
 const measure = (entries: { target: Element; size?: { width: number; height: number } }[]) =>
+  previewing() ||
   commit(
     entries.flatMap(({ target, size }) => {
       const strip = strips.get(target);
@@ -153,6 +182,7 @@ function acquire() {
       gaps: observeIntersections(
         (entries) => entries.some((entry) => entry.isIntersecting) && scheduleRefresh(),
       ),
+      stopZoomWatch: subscribeTimelineZoomPreview(remeasureAfterPreview),
     };
     window.addEventListener("scroll", scheduleRefresh, { capture: true, passive: true });
   }
@@ -164,6 +194,7 @@ function release() {
   shared?.resize.disconnect();
   shared?.presence?.disconnect();
   shared?.gaps?.disconnect();
+  shared?.stopZoomWatch();
   shared = null;
   window.removeEventListener("scroll", scheduleRefresh, { capture: true });
   cancelAnimationFrame(frame);
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 22994da385d..0026d292a73 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -137,6 +137,15 @@ describe("requestTimelineZoom", () => {
     expect(usePlayerStore.getState().timelinePps).toBe(100);
   });
 
+  it("lays out a zoom-out before it shows past the window ruler ticks are drawn in", () => {
+    // 50 s of clips in content 1996 s wide: ticks are drawn to 157 s, a view and a half in.
+    usePlayerStore.setState({ duration: 50 });
+    viewport();
+    requestTimelineZoom(60, { time: 0, x: 32 });
+    vi.advanceTimersToNextFrame();
+    expect(usePlayerStore.getState().timelinePps).toBe(6);
+  });
+
   it("lays a zoom-out out at once before it shows past where the ruler is drawn", () => {
     // 50 s of clips at Fit: the ruler and lanes are drawn to the viewport's edge, 104.8 s.
     usePlayerStore.setState({ duration: 50 });
@@ -350,8 +359,10 @@ describe("zoomTimelineStep", () => {
       if (s.timelinePps !== prev.timelinePps) laidOut.push(s.timelinePps);
     });
     zoomTimelineStep("out");
-    expect(laidOut).toEqual([20]);
+    // Laid out in the first frame, never inside the caller (a host's effect, a click).
+    expect(laidOut).toEqual([]);
     vi.advanceTimersToNextFrame();
+    expect(laidOut).toEqual([20]);
     // Near the old view, drawn in the first frame by scaling the new layout up.
     expect(Number(/scaleX\(([\d.]+)\)/.exec(row.style.transform)?.[1])).toBeGreaterThan(1.5);
     run();
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 18b9c7fef8e..798a56ff386 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -88,7 +88,10 @@ export function timelineZoomMapping(pps: number, contentOrigin: number) {
     : { pps, contentOrigin };
 }
 
-/** Called each frame a zoom preview moves, and once when it is laid out. */
+/** Whether a zoom is drawn scaled right now, so boxes read off the page are scaled too. */
+export const isTimelineZoomPreviewing = (): boolean => preview !== null;
+
+/** Called each frame a zoom preview moves, and once when it is laid out or dropped. */
 export function subscribeTimelineZoomPreview(listener: () => void): () => void {
   previewListeners.add(listener);
   return () => previewListeners.delete(listener);
@@ -283,8 +286,10 @@ export function cancelTimelineZoom(): void {
 
 function dropPreview() {
   cancelPending();
-  if (viewport && preview) clearScaled(viewport.scroll);
+  if (!preview) return;
+  if (viewport) clearScaled(viewport.scroll);
   preview = null;
+  emitPreview();
 }
 
 function stopEase(result: TimelineZoomResult = "cancelled") {
@@ -395,6 +400,7 @@ function easeZoom(
   const from = shown(view.scroll);
   const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
   const fromStart = timelineTimeAtX(x)!;
+  const old = currentTimelineRange()!;
   // The one point both views put at the same place on screen; zooming about it, in log space,
   // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
   const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
@@ -402,15 +408,19 @@ function easeZoom(
     shift === null
       ? { time: fromStart + (start - fromStart) * k, x }
       : { time: fromStart + shift / from.pps, x: x + shift };
-  // Zooming out shows time the current layout never mounted, so lay the target out once now and
-  // ease by scaling it down from the old view, instead of laying out again partway.
-  if (toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE) {
-    request(toPercent, { time: start, x }, byPerson);
-    commitPreview();
-  }
+  // Zooming out to a view that holds the old one: lay the target out once, in the first frame,
+  // and ease by scaling it down from the old view, instead of laying out again partway.
+  const holdsOld =
+    old.start >= start && old.end <= start + (old.end - old.start) * (from.pps / toPps);
+  let layoutFirst = toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE && holdsOld;
   const began = performance.now();
   easingTo = toPercent;
   const step = (now: number) => {
+    if (layoutFirst) {
+      layoutFirst = false;
+      request(toPercent, to, byPerson);
+      commitPreview();
+    }
     const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
     const k = 1 - (1 - t) ** 3;
     request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);

From 0cb4d307acadde6f5ed686f6a4d43ddfb74e5eef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 17:27:36 -0400
Subject: [PATCH 23/26] perf(studio): watch a waveform's undrawn ends only when
 it has some

A clip drawn whole has no undrawn ends, so it no longer mounts the two
empty markers the strip tracker watches; with hundreds of short audio
clips that saved an observer entry each.
---
 .../player/components/AudioWaveform.test.tsx  |  6 +++++
 .../src/player/components/AudioWaveform.tsx   | 24 +++++++++++--------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index e4f224871f3..1652e04b9ab 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -135,6 +135,12 @@ describe("AudioWaveform", () => {
     expect(placed()[1]).toBeCloseTo(20.48);
   });
 
+  it("watches no ends of a clip drawn whole", () => {
+    setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+    renderReadyWaveform();
+    expect(watchGap.mock.calls.filter(([gap]) => gap)).toEqual([]);
+  });
+
   it("redraws a short clip, drawn whole, when a zoom changes its width", () => {
     const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
     setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 77ecd674473..2c04b3fc6b9 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -252,16 +252,20 @@ export const AudioWaveform = memo(function AudioWaveform({
         style={{ zIndex: WAVEFORM_LAYER_Z }}
       >
         {/* The undrawn ends: one coming near the screen, as a move carries the clip, re-measures. */}
-        <div
-          ref={watchGap}
-          className="pointer-events-none absolute inset-y-0 left-0"
-          style={{ width: `${from * 100}%` }}
-        />
-        <div
-          ref={watchGap}
-          className="pointer-events-none absolute inset-y-0 right-0"
-          style={{ left: `${to * 100}%` }}
-        />
+        {from > 0 && (
+          <div
+            ref={watchGap}
+            className="pointer-events-none absolute inset-y-0 left-0"
+            style={{ width: `${from * 100}%` }}
+          />
+        )}
+        {to < 1 && (
+          <div
+            ref={watchGap}
+            className="pointer-events-none absolute inset-y-0 right-0"
+            style={{ left: `${to * 100}%` }}
+          />
+        )}
         <canvas
           ref={canvasRef}
           className="absolute bottom-0"

From bec0f3fb40ca20e38391155989875a077c14effa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 17:41:33 -0400
Subject: [PATCH 24/26] fix(studio): measure strips each time a zoom preview is
 laid out

A zoom-out lays its target out partway into the ease, after which the
strip tracker kept the stretch it measured before the zoom, so a long
filmstrip or waveform went partly blank near the end of the ease. Every
layout of a preview now re-measures the strips.
---
 .../src/hooks/useThumbnailStripSize.test.tsx  | 26 ++++++++++++++
 .../studio/src/hooks/useThumbnailStripSize.ts | 17 +++------
 .../components/timelineZoomInput.test.ts      | 35 +++++++++++++++++++
 3 files changed, 66 insertions(+), 12 deletions(-)

diff --git a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
index 6908d76298f..0e81d61a3d3 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
+++ b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
@@ -87,6 +87,32 @@ it("measures a strip once a zoom preview ends, not while the preview scales it",
   }
 });
 
+it("measures again each time a preview is laid out, though nothing was read during it", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const host = document.createElement("div");
+  document.body.append(host);
+  let width = 300;
+  Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+  const root = createRoot(host);
+  function Harness() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    // A zoom-out lays its target out mid-ease; the resize is reported only later.
+    width = 600;
+    act(() => zoom.listeners.forEach((listener) => listener()));
+    expect(host.textContent).toBe("600x40");
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
 describe("on a scroll", () => {
   const originalResizeObserver = globalThis.ResizeObserver;
   const originalIntersectionObserver = globalThis.IntersectionObserver;
diff --git a/packages/studio/src/hooks/useThumbnailStripSize.ts b/packages/studio/src/hooks/useThumbnailStripSize.ts
index 4558ff26e87..ad98ebc695e 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.ts
+++ b/packages/studio/src/hooks/useThumbnailStripSize.ts
@@ -102,17 +102,10 @@ const read = (target: Element, strip: Strip) => {
 const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
   flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
 
-// A zoom preview scales the strips, so a box read then is wrong; reads wait for it to end.
-let staleSincePreview = false;
-const previewing = () => {
-  if (!isTimelineZoomPreviewing()) return false;
-  staleSincePreview = true;
-  return true;
-};
-
+// A zoom preview scales the strips, so a box read then is wrong: reads wait, and every strip is
+// measured again each time a preview is laid out (also mid-ease, as a zoom-out lays out first).
 const remeasureAfterPreview = () => {
-  if (!staleSincePreview || isTimelineZoomPreviewing()) return;
-  staleSincePreview = false;
+  if (isTimelineZoomPreviewing()) return;
   commit(
     [...strips].map(
       ([target, strip]) =>
@@ -126,7 +119,7 @@ const remeasureAfterPreview = () => {
 
 const refresh = () => {
   frame = 0;
-  if (previewing()) return;
+  if (isTimelineZoomPreviewing()) return;
   const offsetsNow = new Map<Element | null, { x: number; y: number }>();
   const updates: (readonly [Apply, Partial<StripSize>])[] = [];
   for (const [target, strip] of strips) {
@@ -150,7 +143,7 @@ const scheduleRefresh = () => {
 };
 
 const measure = (entries: { target: Element; size?: { width: number; height: number } }[]) =>
-  previewing() ||
+  isTimelineZoomPreviewing() ||
   commit(
     entries.flatMap(({ target, size }) => {
       const strip = strips.get(target);
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
index 0026d292a73..6230dd7edb8 100644
--- a/packages/studio/src/player/components/timelineZoomInput.test.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -4,6 +4,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../store/playerStore";
 import {
   cancelTimelineZoom,
+  isTimelineZoomPreviewing,
+  subscribeTimelineZoomPreview,
   redrawTimelineZoomPreview,
   currentTimelineRange,
   currentTimelineZoomPercent,
@@ -187,6 +189,19 @@ describe("requestTimelineZoom", () => {
     expect(usePlayerStore.getState().timelinePps).toBe(15);
   });
 
+  it("tells listeners when a pending zoom is dropped", () => {
+    viewport();
+    requestTimelineZoom(150);
+    vi.advanceTimersToNextFrame();
+    let shownAfterDrop: boolean | null = null;
+    const unsubscribe = subscribeTimelineZoomPreview(() => {
+      shownAfterDrop = isTimelineZoomPreviewing();
+    });
+    cancelTimelineZoom();
+    unsubscribe();
+    expect(shownAfterDrop).toBe(false);
+  });
+
   it("drops a pending zoom when cancelled, as Fit does", () => {
     const { row } = viewport();
     requestTimelineZoom(150);
@@ -372,6 +387,26 @@ describe("zoomTimelineStep", () => {
     expect(usePlayerStore.getState().userZoomCount).toBe(1);
   });
 
+  it("eases a zoom-out that pans away without laying its target out first", () => {
+    // 100..126 s on screen at 40 px/s; the playhead at 0 s is off screen, so the new view
+    // (centred on it) does not hold the old one.
+    usePlayerStore.setState({
+      duration: 1000,
+      zoomMode: "manual",
+      manualZoomPercent: 400,
+      timelinePps: 40,
+    });
+    viewport(4000);
+    const laidOut: number[] = [];
+    const unsubscribe = usePlayerStore.subscribe((s, prev) => {
+      if (s.timelinePps !== prev.timelinePps) laidOut.push(s.timelinePps);
+    });
+    zoomTimelineStep("out");
+    vi.advanceTimersToNextFrame();
+    unsubscribe();
+    expect(laidOut[0]).not.toBe(20);
+  });
+
   it("centres an off-screen playhead", () => {
     usePlayerStore.setState({
       currentTime: 60,

From b91b342ee68bbad5c587cd2f057ff53ca9fba0a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 17:52:46 -0400
Subject: [PATCH 25/26] docs(studio): keep the zoom-to-range doc comment within
 four lines

---
 packages/studio/src/player/components/timelineZoomInput.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 798a56ff386..70fc3956472 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -341,9 +341,8 @@ export function currentTimelineRange(): { start: number; end: number } | null {
 }
 
 /**
- * Zooms and scrolls so `start`..`end` (seconds) fills the timeline's width, easing there unless
- * `smooth` is false or the person prefers reduced motion. Resolves once the range is laid out,
- * or as "cancelled" when a person zooms, `signal` aborts, or another range zoom starts.
+ * Zooms and scrolls so `start`..`end` (seconds) fills the timeline, eased unless `smooth` is false
+ * or motion is reduced. Resolves on landing; "cancelled" on a person's zoom, abort, or a newer one.
  */
 export function zoomTimelineToRange(
   start: number,

From 97966f58223f1960b396314616a5b52a46b33589 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 6 Oct 2026 19:47:01 -0400
Subject: [PATCH 26/26] docs(studio): keep the zoom files' comment share at or
 under main's

The comment ratchet failed on ten files this branch touches. Comments are
cut or folded into one line; no code changes.
---
 packages/studio/src/components/TimelineToolbar.tsx     |  7 +------
 packages/studio/src/hooks/useThumbnailStripSize.ts     |  4 +---
 .../studio/src/player/components/AudioWaveform.tsx     | 10 ++--------
 packages/studio/src/player/components/TimelineClip.tsx |  9 +--------
 .../studio/src/player/components/TimelineClipFades.tsx |  1 -
 .../studio/src/player/components/TimelineTimeLayer.tsx |  1 -
 .../studio/src/player/components/VideoThumbnail.tsx    |  2 --
 .../studio/src/player/components/timelineZoomInput.ts  |  2 --
 .../src/player/components/useTimelinePlayhead.ts       |  7 ++-----
 .../studio/src/player/components/useTimelineZoom.ts    |  2 --
 10 files changed, 7 insertions(+), 38 deletions(-)

diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index f70fd1ec253..3cfd9258033 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -172,15 +172,12 @@ export const TimelineToolbar = memo(function TimelineToolbar({
   // Subscribe so the add-beat button reacts to playhead movement and analysis load.
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
-  // Subscribe (not getState) so the split button enables/disables the moment
-  // the selection changes, not only on the next playhead tick.
+  // Subscribed, so the split button follows the selection, not only playhead ticks.
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const elements = usePlayerStore((s) => s.elements);
   const timelineFitPps = usePlayerStore((s) => s.timelineFitPps);
   const { zoomMode, setZoomMode, setManualZoomPercent } = useTimelineZoom();
-  // Follows a zoom while it is previewed, before it is laid out and stored.
   const displayedTimelineZoomPercent = useShownTimelineZoomPercent();
-  // Fit is 100%; anything else on screen is a zoom still being previewed.
   const showsFit = zoomMode === "fit" && displayedTimelineZoomPercent === 100;
   const {
     state: keyframeState,
@@ -216,8 +213,6 @@ export const TimelineToolbar = memo(function TimelineToolbar({
   }, []);
 
   return (
-    // The "TIMELINE" label is dropped for CapCut-like density — the pane's
-    // position (tracks right below) makes it self-evident.
     <div className="border-b border-neutral-800/60">
       <div className="flex items-center justify-between px-2 py-0.5">
         <div className="flex items-center gap-0.5">
diff --git a/packages/studio/src/hooks/useThumbnailStripSize.ts b/packages/studio/src/hooks/useThumbnailStripSize.ts
index ad98ebc695e..ba44f4faa97 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.ts
+++ b/packages/studio/src/hooks/useThumbnailStripSize.ts
@@ -28,7 +28,6 @@ const GAP_WARNING: IntersectionObserverInit & { scrollMargin: string } = {
   scrollMargin: `0px ${IN_VIEW_CHUNK_PX / 2}px`,
 };
 
-// A short strip keeps every tile, as before, so only long clips do work on a scroll.
 const SHORT_STRIP_MAX_PX = 8 * IN_VIEW_CHUNK_PX;
 const isShort = (width: number) => width <= SHORT_STRIP_MAX_PX;
 
@@ -102,8 +101,7 @@ const read = (target: Element, strip: Strip) => {
 const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
   flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
 
-// A zoom preview scales the strips, so a box read then is wrong: reads wait, and every strip is
-// measured again each time a preview is laid out (also mid-ease, as a zoom-out lays out first).
+// A zoom preview scales the strips: reads wait, and each preview's layout re-measures them all.
 const remeasureAfterPreview = () => {
   if (isTimelineZoomPreviewing()) return;
   commit(
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 2c04b3fc6b9..d7e226ba1b5 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -30,7 +30,6 @@ export const WAVEFORM_LAYER_Z = 10;
 
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
-/** A stretch of the clip as fractions of its width. */
 type ClipSpan = { from: number; to: number };
 const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
 function paintWaveformBars(
@@ -120,11 +119,8 @@ async function loadWaveform(
   waveformUrl: string | undefined,
   signal: AbortSignal,
 ): Promise<number[]> {
-  // Failures propagate. Synthesised peaks are worse than an honest gap: an
-  // author trims and beat-aligns against this waveform, and a plausible
-  // fabrication is indistinguishable from the real thing while being wrong.
-  // The scheduler caches the failure (metadataFailureTtlMs) so the degraded
-  // state neither refetch-loops nor pins itself past a transient error.
+  // Failures propagate: authors trim and beat-align against this, so made-up peaks beat no gap.
+  // The scheduler caches the failure (metadataFailureTtlMs): no refetch loop, no stuck state.
   return waveformUrl
     ? await fetchWaveformPeaks(waveformUrl, signal)
     : await decodeWaveformPeaks(audioUrl, signal);
@@ -201,7 +197,6 @@ export const AudioWaveform = memo(function AudioWaveform({
     snapshot.status === "ready" && snapshot.value.kind === "waveform" ? snapshot.value.peaks : null;
 
   const fades = useContext(ClipFadesContext);
-  // The clip's size and the stretch of it near the screen, kept current through scrolls and moves.
   const [strip, setStripRef, watchGap] = useThumbnailStripSize();
   const from = strip.width > 0 ? strip.inViewStart / strip.width : 0;
   const to = strip.width > 0 ? strip.inViewEnd / strip.width : 1;
@@ -223,7 +218,6 @@ export const AudioWaveform = memo(function AudioWaveform({
       span,
     );
   }, [fades, from, muted, peaks, to, trimEndFraction, trimStartFraction]);
-  // Also on a resize: the bars are drawn at the canvas size, which follows the clip.
   useEffect(draw, [draw, strip.width, strip.height]);
 
   useEffect(() => {
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index d1213f49ee7..c63a3c41e7e 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -45,18 +45,13 @@ interface TimelineClipProps {
   children?: ReactNode;
 }
 
-/** Narrower clips show trim handles only while selected. */
 const HANDLES_MIN_PX = 32;
 
-/** The narrowest a clip is drawn, so a very short one stays visible and grabbable. */
 const CLIP_MIN_WIDTH_PX = 4;
 export const clipWidthPx = (el: TimelineElement, pps: number) =>
   Math.max(el.duration * pps, CLIP_MIN_WIDTH_PX);
 
-/**
- * What a clip draws that depends on the zoom, as one value: its width tier and whether its trim
- * handles fit, or the scale itself while its fade handles are live (hovered, selected or set).
- */
+/** Zoom-dependent drawing as one value: width tier and trim fit, or the scale while fades show. */
 export function clipZoomKey(el: TimelineElement, pps: number, interacting: boolean) {
   const fadesLive = interacting || (el.fadeIn ?? 0) > 0 || (el.fadeOut ?? 0) > 0;
   if (fadesLive) return pps;
@@ -129,7 +124,6 @@ export const TimelineClip = memo(function TimelineClip({
   ]
     .filter((className) => className.length > 0)
     .join(" ");
-  // In percent of the row's TimelineTimeLayer: a zoom step leaves this style as it is.
   const style: CSSProperties = {
     left: timeLayerPercent(el.start),
     width: timeLayerPercent(el.duration),
@@ -139,7 +133,6 @@ export const TimelineClip = memo(function TimelineClip({
     borderRadius: isAudioClip ? theme.audioClipRadius : theme.clipRadius,
     ...themeVariables,
     zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
-    // Regular cursor over clips (CapCut-style, user preference) — no grab hand.
     cursor: "default",
     appearance: "none",
     color: "inherit",
diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsx
index 5a05f0dbea9..6dc23dd9c13 100644
--- a/packages/studio/src/player/components/TimelineClipFades.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.tsx
@@ -207,7 +207,6 @@ export function TimelineClipFades({
     const g = gesture.current;
     if (!g) return 0;
     const deltaSeconds = (clientX - g.originClientX) / Math.max(pps, 1e-6);
-    // Fade-in grows to the right, fade-out grows to the left.
     const raw = g.edge === "in" ? g.originSeconds + deltaSeconds : g.originSeconds - deltaSeconds;
     const limit = dragLimit(g);
     const clamped = Math.min(limit, Math.max(0, raw));
diff --git a/packages/studio/src/player/components/TimelineTimeLayer.tsx b/packages/studio/src/player/components/TimelineTimeLayer.tsx
index def9adefb53..8c417aef92e 100644
--- a/packages/studio/src/player/components/TimelineTimeLayer.tsx
+++ b/packages/studio/src/player/components/TimelineTimeLayer.tsx
@@ -22,5 +22,4 @@ export function TimelineTimeLayer({
   );
 }
 
-/** A time, in seconds, as a position inside a TimelineTimeLayer. */
 export const timeLayerPercent = (seconds: number) => `${seconds * 100}%`;
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 9f78b0f41e8..a5e00b8a4b5 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -88,7 +88,6 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   priority = "visible",
 }: VideoThumbnailProps) {
   const [container, setContainerRef, watchGap] = useThumbnailStripSize();
-  // A zoom changes the width every step; decode the strip it settles on, not each step's.
   const requestFrameCount = useValueAtRest(
     quantizeThumbnailFrameCount(
       computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
@@ -114,7 +113,6 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  // A clip that scrolls in mid-zoom starts decoding once the timeline rests.
   const measured = useValueAtRest(container.width > 0);
   const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
   const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
index 6dbce6edad1..a2e82866f06 100644
--- a/packages/studio/src/player/components/timelineZoomInput.ts
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -60,7 +60,6 @@ let easingTo: number | null = null;
 let resolveEase: ((result: TimelineZoomResult) => void) | null = null;
 const previewListeners = new Set<() => void>();
 
-/** The percent the timeline is showing. */
 export function currentTimelineZoomPercent(): number {
   if (preview) return preview.percent;
   const s = usePlayerStore.getState();
@@ -156,7 +155,6 @@ function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigi
 
 /** The times laid out now: the render window clips, ruler ticks and beat lines are drawn in. */
 function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
-  // The timeline clamps that window to its content's end, as wide as the scroll content.
   const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
   return getTimelineRenderTimeRange(scroll, pps, contentOrigin, contentEnd);
 }
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 0d10fc28de1..6310fb537e1 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -78,8 +78,7 @@ export function useTimelinePlayhead({
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // A zoom keeps its anchor's time where it was (pinch: the pointer; buttons and slider: the
-  // playhead); a resize keeps the centre, or 00:00 at the start.
+  // A zoom keeps its anchor (pinch: pointer, else playhead) in place; a resize keeps the centre.
   const previousAnchorPpsRef = useRef(pps);
   const userZoomCount = usePlayerStore((s) => s.userZoomCount);
   const previousZoomCountRef = useRef(userZoomCount);
@@ -94,8 +93,7 @@ export function useTimelinePlayhead({
     previousAnchorPpsRef.current = pps;
     const prevZoomCount = previousZoomCountRef.current;
     previousZoomCountRef.current = userZoomCount;
-    // Always consume the anchor, even when pps didn't change (a zoom at its clamp), so it never
-    // lingers for a later zoom that named none.
+    // Consumed even when pps didn't change (at the clamp), so it never lingers for a later zoom.
     const anchor = takeTimelineZoomAnchor();
     if (!scroll || pps === prevPps) return;
     if (anchor) {
@@ -175,7 +173,6 @@ export function useTimelinePlayhead({
       );
       return true;
     };
-    // A zoom preview moves the playhead with the scaled clips.
     const unsubPreview = subscribeTimelineZoomPreview(() =>
       place(lastLiveTimeRef.current, !usePlayerStore.getState().isPlaying),
     );
diff --git a/packages/studio/src/player/components/useTimelineZoom.ts b/packages/studio/src/player/components/useTimelineZoom.ts
index d5e07bc1d77..2a35d99661a 100644
--- a/packages/studio/src/player/components/useTimelineZoom.ts
+++ b/packages/studio/src/player/components/useTimelineZoom.ts
@@ -9,12 +9,10 @@ export interface TimelineZoomState {
   setManualZoomPercent: (percent: number) => void;
 }
 
-/** Shared zoom-related store selectors used by Timeline and TimelineToolbar. */
 export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setStoreZoomMode = usePlayerStore((s) => s.setZoomMode);
-  // A mode picked now (Fit) wins over a zoom still easing or waiting to be laid out.
   const setZoomMode = (mode: ZoomMode) => {
     cancelTimelineZoom();
     setStoreZoomMode(mode);