From 115ab2ac32b19bec7a384a3f61c62d29b1fa3c9e Mon Sep 17 00:00:00 2001
From: Etienne Lescot <etiennelescot@gmail.com>
Date: Sun, 19 Jul 2026 09:09:21 +0200
Subject: [PATCH 1/2] perf(timeline): decouple playhead from ancestor
 re-renders so it tracks playback

The timeline playhead read its position from `currentTime` React state, set
from VideoEditor (a ~3300-line component) on every rAF tick of video playback
and on every `seeking` event while dragging. Each tick forced a full re-render
of VideoEditor + VideoPlayback + TimelineEditor before the playhead's DOM
moved, so the visual position lagged behind actual video playback and felt
sluggish while scrubbing during playback.

- PlaybackCursor now reads the video element's currentTime directly via a
  `getPlaybackTimeMs` getter, in its own requestAnimationFrame loop and its
  own local `useState`. Only this small component re-renders per frame,
  independent of how long the ancestor tree's render takes.
- Coalesce the `onTimeUpdate` React state commit (still used by everything
  else that reads `currentTime`) to at most once per animation frame via a
  new `createRafCoalescer` helper, so a burst of `seeking` events from a fast
  timeline drag doesn't force one state commit per event.

Fixes #111
---
 src/components/video-editor/VideoEditor.tsx   | 11 +++
 src/components/video-editor/VideoPlayback.tsx | 40 ++++----
 .../video-editor/timeline/TimelineEditor.tsx  | 47 ++++++++-
 .../videoPlayback/rafCoalescer.test.ts        | 97 +++++++++++++++++++
 .../videoPlayback/rafCoalescer.ts             | 41 ++++++++
 .../videoPlayback/videoEventHandlers.ts       | 11 ++-
 6 files changed, 225 insertions(+), 22 deletions(-)
 create mode 100644 src/components/video-editor/videoPlayback/rafCoalescer.test.ts
 create mode 100644 src/components/video-editor/videoPlayback/rafCoalescer.ts

diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index b49197da4..b0a278c4c 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -1004,6 +1004,16 @@ export default function VideoEditor() {
 		video.currentTime = time;
 	}
 
+	// Reads the live playhead position directly off the <video> element, bypassing
+	// `currentTime` React state entirely. The timeline's playhead subscribes to this
+	// via its own rAF loop so it stays in lockstep with actual playback regardless of
+	// how long this (large) component's own re-render takes — see issue #111.
+	const getPlaybackTimeMs = useCallback(() => {
+		const video = videoPlaybackRef.current?.video;
+		if (video) return video.currentTime * 1000;
+		return currentTimeRef.current * 1000;
+	}, []);
+
 	const handleSelectZoom = useCallback((id: string | null) => {
 		setSelectedZoomId(id);
 		if (id) {
@@ -3213,6 +3223,7 @@ export default function VideoEditor() {
 								<TimelineEditor
 									videoDuration={duration}
 									currentTime={currentTime}
+									getPlaybackTimeMs={getPlaybackTimeMs}
 									onSeek={handleSeek}
 									zoomRegions={zoomRegions}
 									onZoomAdded={handleZoomAdded}
diff --git a/src/components/video-editor/VideoPlayback.tsx b/src/components/video-editor/VideoPlayback.tsx
index 11c9e4061..8b7f2e829 100644
--- a/src/components/video-editor/VideoPlayback.tsx
+++ b/src/components/video-editor/VideoPlayback.tsx
@@ -1308,25 +1308,26 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			layoutVideoContentRef.current?.();
 			video.pause();
 
-			const { handlePlay, handlePause, handleSeeked, handleSeeking } = createVideoEventHandlers({
-				video,
-				isSeekingRef,
-				isPlayingRef,
-				allowPlaybackRef,
-				currentTimeRef,
-				timeUpdateAnimationRef,
-				onPlayStateChange: (playing) => onPlayStateChangeRef.current(playing),
-				onTimeUpdate: (time) => onTimeUpdateRef.current(time),
-				trimRegionsRef,
-				speedRegionsRef,
-				isScrubbingRef,
-				scrubEndTimerRef,
-				onScrubChange: (scrubbing) => setIsScrubbing(scrubbing),
-				seekSteppingRef,
-				stepVirtualSecRef,
-				stepLastTsRef,
-				stepPrevMutedRef,
-			});
+			const { handlePlay, handlePause, handleSeeked, handleSeeking, dispose } =
+				createVideoEventHandlers({
+					video,
+					isSeekingRef,
+					isPlayingRef,
+					allowPlaybackRef,
+					currentTimeRef,
+					timeUpdateAnimationRef,
+					onPlayStateChange: (playing) => onPlayStateChangeRef.current(playing),
+					onTimeUpdate: (time) => onTimeUpdateRef.current(time),
+					trimRegionsRef,
+					speedRegionsRef,
+					isScrubbingRef,
+					scrubEndTimerRef,
+					onScrubChange: (scrubbing) => setIsScrubbing(scrubbing),
+					seekSteppingRef,
+					stepVirtualSecRef,
+					stepLastTsRef,
+					stepPrevMutedRef,
+				});
 
 			video.addEventListener("play", handlePlay);
 			video.addEventListener("pause", handlePause);
@@ -1344,6 +1345,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 				if (timeUpdateAnimationRef.current) {
 					cancelAnimationFrame(timeUpdateAnimationRef.current);
 				}
+				dispose();
 
 				if (videoSprite) {
 					videoContainer.removeChild(videoSprite);
diff --git a/src/components/video-editor/timeline/TimelineEditor.tsx b/src/components/video-editor/timeline/TimelineEditor.tsx
index b6e323a31..c2544bde8 100644
--- a/src/components/video-editor/timeline/TimelineEditor.tsx
+++ b/src/components/video-editor/timeline/TimelineEditor.tsx
@@ -58,6 +58,12 @@ interface TimelineEditorProps {
 	videoDuration: number;
 	hasVideoSource?: boolean;
 	currentTime: number;
+	/**
+	 * Reads the live playhead position (ms) directly, bypassing `currentTime` React
+	 * state. The playhead subscribes to this via its own rAF loop so it stays in sync
+	 * with actual playback regardless of how long an ancestor's re-render takes.
+	 */
+	getPlaybackTimeMs?: () => number;
 	onSeek?: (time: number) => void;
 	zoomRegions: ZoomRegion[];
 	onZoomAdded: (span: Span) => void;
@@ -284,6 +290,7 @@ function shouldStartTimelineScrub(target: EventTarget | null, timelineElement: H
 function PlaybackCursor({
 	currentTimeMs,
 	videoDurationMs,
+	getPlaybackTimeMs,
 	onSeek,
 	onRangeChange,
 	timelineRef,
@@ -291,6 +298,7 @@ function PlaybackCursor({
 }: {
 	currentTimeMs: number;
 	videoDurationMs: number;
+	getPlaybackTimeMs?: () => number;
 	onSeek?: (time: number) => void;
 	onRangeChange?: (updater: (previous: Range) => Range) => void;
 	timelineRef: React.RefObject<HTMLDivElement>;
@@ -301,6 +309,36 @@ function PlaybackCursor({
 	const [isDragging, setIsDragging] = useState(false);
 	const [dragPreviewTimeMs, setDragPreviewTimeMs] = useState<number | null>(null);
 
+	// Drives the playhead position from the video element every animation frame,
+	// isolated from the rest of the tree: this component's own `useState` call only
+	// re-renders this small subtree, not TimelineEditor/VideoEditor above it. That
+	// decoupling is what keeps the playhead glued to actual playback even while an
+	// ancestor's (much heavier) re-render is in flight — see issue #111.
+	const [liveTimeMs, setLiveTimeMs] = useState(currentTimeMs);
+	const getPlaybackTimeMsRef = useRef(getPlaybackTimeMs);
+	getPlaybackTimeMsRef.current = getPlaybackTimeMs;
+
+	useEffect(() => {
+		if (!getPlaybackTimeMsRef.current) {
+			return;
+		}
+
+		let rafId: number;
+		const tick = () => {
+			const getter = getPlaybackTimeMsRef.current;
+			if (getter) {
+				const latest = getter();
+				setLiveTimeMs((previous) => (previous === latest ? previous : latest));
+			}
+			rafId = requestAnimationFrame(tick);
+		};
+		rafId = requestAnimationFrame(tick);
+
+		return () => cancelAnimationFrame(rafId);
+	}, []);
+
+	const resolvedTimeMs = getPlaybackTimeMs ? liveTimeMs : currentTimeMs;
+
 	useEffect(() => {
 		if (!isDragging) return;
 
@@ -399,7 +437,7 @@ function PlaybackCursor({
 	]);
 
 	const displayTimeMs =
-		isDragging && dragPreviewTimeMs !== null ? dragPreviewTimeMs : currentTimeMs;
+		isDragging && dragPreviewTimeMs !== null ? dragPreviewTimeMs : resolvedTimeMs;
 
 	if (videoDurationMs <= 0 || displayTimeMs < 0) {
 		return null;
@@ -428,7 +466,7 @@ function PlaybackCursor({
 				}}
 				onMouseDown={(e) => {
 					e.stopPropagation(); // Prevent timeline click
-					setDragPreviewTimeMs(currentTimeMs);
+					setDragPreviewTimeMs(resolvedTimeMs);
 					setIsDragging(true);
 				}}
 			>
@@ -571,6 +609,7 @@ function Timeline({
 	items,
 	videoDurationMs,
 	currentTimeMs,
+	getPlaybackTimeMs,
 	onSeek,
 	onRangeChange,
 	onSelectZoom,
@@ -592,6 +631,7 @@ function Timeline({
 	items: TimelineRenderItem[];
 	videoDurationMs: number;
 	currentTimeMs: number;
+	getPlaybackTimeMs?: () => number;
 	onSeek?: (time: number) => void;
 	onRangeChange?: (updater: (previous: Range) => Range) => void;
 	onSelectZoom?: (id: string | null) => void;
@@ -797,6 +837,7 @@ function Timeline({
 			<PlaybackCursor
 				currentTimeMs={currentTimeMs}
 				videoDurationMs={videoDurationMs}
+				getPlaybackTimeMs={getPlaybackTimeMs}
 				onSeek={onSeek}
 				onRangeChange={onRangeChange}
 				timelineRef={localTimelineRef}
@@ -934,6 +975,7 @@ export default function TimelineEditor({
 	videoDuration,
 	hasVideoSource = false,
 	currentTime,
+	getPlaybackTimeMs,
 	onSeek,
 	zoomRegions,
 	onZoomAdded,
@@ -1803,6 +1845,7 @@ export default function TimelineEditor({
 						items={timelineItems}
 						videoDurationMs={totalMs}
 						currentTimeMs={currentTimeMs}
+						getPlaybackTimeMs={getPlaybackTimeMs}
 						onSeek={onSeek}
 						onRangeChange={setRange}
 						onSelectZoom={onSelectZoom}
diff --git a/src/components/video-editor/videoPlayback/rafCoalescer.test.ts b/src/components/video-editor/videoPlayback/rafCoalescer.test.ts
new file mode 100644
index 000000000..6f896081a
--- /dev/null
+++ b/src/components/video-editor/videoPlayback/rafCoalescer.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createRafCoalescer } from "./rafCoalescer";
+
+describe("createRafCoalescer", () => {
+	let rafCallbacks: FrameRequestCallback[];
+	let nextRafId: number;
+
+	beforeEach(() => {
+		rafCallbacks = [];
+		nextRafId = 1;
+		vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+			rafCallbacks.push(cb);
+			return nextRafId++;
+		});
+		vi.stubGlobal("cancelAnimationFrame", (id: number) => {
+			// Mark the callback as a no-op instead of removing it, to mirror the
+			// browser's index-stable semantics.
+			const index = id - 1;
+			if (rafCallbacks[index]) {
+				rafCallbacks[index] = () => {
+					// Cancelled: no-op.
+				};
+			}
+		});
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	function flushOneFrame(timeMs = 0) {
+		const callbacks = rafCallbacks;
+		rafCallbacks = [];
+		for (const cb of callbacks) cb(timeMs);
+	}
+
+	it("does not call flush until an animation frame runs", () => {
+		const flush = vi.fn();
+		const coalescer = createRafCoalescer<number>(flush);
+
+		coalescer.schedule(1);
+
+		expect(flush).not.toHaveBeenCalled();
+	});
+
+	it("collapses multiple schedule calls within the same frame into a single flush", () => {
+		const flush = vi.fn();
+		const coalescer = createRafCoalescer<number>(flush);
+
+		coalescer.schedule(1);
+		coalescer.schedule(2);
+		coalescer.schedule(3);
+
+		flushOneFrame();
+
+		expect(flush).toHaveBeenCalledTimes(1);
+		expect(flush).toHaveBeenCalledWith(3);
+	});
+
+	it("schedules a fresh frame for values reported after the previous frame flushed", () => {
+		const flush = vi.fn();
+		const coalescer = createRafCoalescer<number>(flush);
+
+		coalescer.schedule(1);
+		flushOneFrame();
+		coalescer.schedule(2);
+		flushOneFrame();
+
+		expect(flush).toHaveBeenCalledTimes(2);
+		expect(flush).toHaveBeenNthCalledWith(1, 1);
+		expect(flush).toHaveBeenNthCalledWith(2, 2);
+	});
+
+	it("cancel() prevents a pending flush from firing", () => {
+		const flush = vi.fn();
+		const coalescer = createRafCoalescer<number>(flush);
+
+		coalescer.schedule(1);
+		coalescer.cancel();
+		flushOneFrame();
+
+		expect(flush).not.toHaveBeenCalled();
+	});
+
+	it("a schedule() call after cancel() still flushes on the next frame", () => {
+		const flush = vi.fn();
+		const coalescer = createRafCoalescer<number>(flush);
+
+		coalescer.schedule(1);
+		coalescer.cancel();
+		coalescer.schedule(2);
+		flushOneFrame();
+
+		expect(flush).toHaveBeenCalledTimes(1);
+		expect(flush).toHaveBeenCalledWith(2);
+	});
+});
diff --git a/src/components/video-editor/videoPlayback/rafCoalescer.ts b/src/components/video-editor/videoPlayback/rafCoalescer.ts
new file mode 100644
index 000000000..be0b2f1a9
--- /dev/null
+++ b/src/components/video-editor/videoPlayback/rafCoalescer.ts
@@ -0,0 +1,41 @@
+/**
+ * Coalesces rapid-fire calls into at most one flush per animation frame.
+ *
+ * Used so a ref-backed value can be updated synchronously on every call (cheap),
+ * while an expensive side effect — e.g. a React state commit — is deferred to
+ * once per frame. Without this, a burst of calls within the same frame (many
+ * `seeking` events fired while dragging the timeline playhead) would otherwise
+ * force one state commit per call, saturating the main thread and making both
+ * the drag and the playhead's own rendering feel laggy.
+ */
+export function createRafCoalescer<T>(flush: (value: T) => void) {
+	let pendingValue: T | undefined;
+	let hasPending = false;
+	let rafId: number | null = null;
+
+	const schedule = (value: T) => {
+		pendingValue = value;
+		hasPending = true;
+		if (rafId !== null) return;
+		rafId = requestAnimationFrame(() => {
+			rafId = null;
+			if (hasPending) {
+				hasPending = false;
+				const valueToFlush = pendingValue as T;
+				pendingValue = undefined;
+				flush(valueToFlush);
+			}
+		});
+	};
+
+	const cancel = () => {
+		if (rafId !== null) {
+			cancelAnimationFrame(rafId);
+			rafId = null;
+		}
+		hasPending = false;
+		pendingValue = undefined;
+	};
+
+	return { schedule, cancel };
+}
diff --git a/src/components/video-editor/videoPlayback/videoEventHandlers.ts b/src/components/video-editor/videoPlayback/videoEventHandlers.ts
index 6d03e7692..aac2785cf 100644
--- a/src/components/video-editor/videoPlayback/videoEventHandlers.ts
+++ b/src/components/video-editor/videoPlayback/videoEventHandlers.ts
@@ -1,5 +1,6 @@
 import type React from "react";
 import { MAX_NATIVE_PLAYBACK_RATE, type SpeedRegion, type TrimRegion } from "../types";
+import { createRafCoalescer } from "./rafCoalescer";
 
 // Keep "scrub mode" on for a brief tail after `seeked`: rapid drag-scrubbing fires
 // `seeking`/`seeked` dozens of times a second and toggling effects each time would flicker.
@@ -77,9 +78,16 @@ export function createVideoEventHandlers(params: VideoEventHandlersParams) {
 		}
 	};
 
+	// currentTimeRef is updated synchronously on every call (cheap; other imperative
+	// consumers like the Pixi renderer read it directly). The React state commit
+	// (`onTimeUpdate`) is coalesced to at most once per animation frame so a burst of
+	// `seeking` events (fast timeline drag) or the per-frame rAF playback loop can't
+	// force more than one parent re-render per frame.
+	const timeUpdateCoalescer = createRafCoalescer<number>(onTimeUpdate);
+
 	const emitTime = (timeValue: number) => {
 		currentTimeRef.current = timeValue * 1000;
-		onTimeUpdate(timeValue);
+		timeUpdateCoalescer.schedule(timeValue);
 	};
 
 	const findActiveTrimRegion = (currentTimeMs: number): TrimRegion | null => {
@@ -331,5 +339,6 @@ export function createVideoEventHandlers(params: VideoEventHandlersParams) {
 		handlePause,
 		handleSeeked,
 		handleSeeking,
+		dispose: () => timeUpdateCoalescer.cancel(),
 	};
 }

From ca9c4162dcede8ec8b48a57d0ed3004476ef3745 Mon Sep 17 00:00:00 2001
From: Etienne Lescot <etiennelescot@gmail.com>
Date: Sun, 19 Jul 2026 10:57:12 +0200
Subject: [PATCH 2/2] fix(timeline): move getPlaybackTimeMs ref sync out of
 render phase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per CodeRabbit review on #120: PlaybackCursor wrote to
getPlaybackTimeMsRef.current directly in the render body instead of in an
effect. Writing to a ref during render is a React anti-pattern — it can leave
the ref holding a stale value from a discarded render pass under concurrent
rendering. Moved the assignment into a useEffect keyed on getPlaybackTimeMs,
matching the recommended pattern for "latest callback" refs.

Verified: tsc --noEmit clean, biome clean, rafCoalescer.test.ts and
zoomRegionUtils.test.ts pass (7/7).
---
 src/components/video-editor/timeline/TimelineEditor.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/components/video-editor/timeline/TimelineEditor.tsx b/src/components/video-editor/timeline/TimelineEditor.tsx
index c2544bde8..242714a86 100644
--- a/src/components/video-editor/timeline/TimelineEditor.tsx
+++ b/src/components/video-editor/timeline/TimelineEditor.tsx
@@ -316,7 +316,9 @@ function PlaybackCursor({
 	// ancestor's (much heavier) re-render is in flight — see issue #111.
 	const [liveTimeMs, setLiveTimeMs] = useState(currentTimeMs);
 	const getPlaybackTimeMsRef = useRef(getPlaybackTimeMs);
-	getPlaybackTimeMsRef.current = getPlaybackTimeMs;
+	useEffect(() => {
+		getPlaybackTimeMsRef.current = getPlaybackTimeMs;
+	}, [getPlaybackTimeMs]);
 
 	useEffect(() => {
 		if (!getPlaybackTimeMsRef.current) {