fix: offline video preferences after ClientOnly hydration (#576)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: kentcdodds

packages/workshop-app/app/components/epic-video.tsx

@@ -33,6 +33,7 @@ import { useIsOnline } from '#app/utils/online.ts'
 import { useRootLoaderData } from '#app/utils/root-loader.ts'
 import { Icon } from './icons.tsx'
 import { Loading } from './loading.tsx'
+import { useApplyNativeVideoPreferences } from './native-video-preferences.ts'
 import { OfflineVideoActionButtons } from './offline-video-actions.tsx'
 import { useOptionalUser } from './user.tsx'
 import { useWorkshopConfig } from './workshop-config.tsx'
@@ -465,6 +466,8 @@ function EpicVideo({
 }) {
 	const muxPlayerRef = React.useRef<MuxPlayerRefAttributes>(null)
 	const nativeVideoRef = React.useRef<HTMLVideoElement>(null)
+	const [nativeVideoElement, setNativeVideoElement] =
+		React.useState<HTMLVideoElement | null>(null)
 	const isOnline = useIsOnline()
 	const playerPreferences = usePlayerPreferences()
 	const rootData = useRootLoaderData()
@@ -539,6 +542,13 @@ function EpicVideo({
 	const [offlineStartTime, setOfflineStartTime] = React.useState<number | null>(
 		null,
 	)
+	const setNativeVideoRef = React.useCallback(
+		(element: HTMLVideoElement | null) => {
+			nativeVideoRef.current = element
+			setNativeVideoElement(element)
+		},
+		[],
+	)
 	const timestampRegex = /(\d+:\d+)/g
 	// turn the transcript into an array of React elements
 	const transcriptElements: Array<React.ReactNode> = []
@@ -596,19 +606,11 @@ function EpicVideo({
 		)
 	}
 
-	React.useEffect(() => {
-		if (!nativeVideoRef.current) return
-		if (typeof playerPreferences?.playbackRate === 'number') {
-			nativeVideoRef.current.playbackRate = playerPreferences.playbackRate
-		}
-		if (typeof playerPreferences?.volumeRate === 'number') {
-			nativeVideoRef.current.volume = playerPreferences.volumeRate
-		}
-	}, [
-		playerPreferences?.playbackRate,
-		playerPreferences?.volumeRate,
-		shouldUseOfflineVideo,
-	])
+	useApplyNativeVideoPreferences({
+		shouldApply: shouldUseOfflineVideo,
+		videoElement: nativeVideoElement,
+		playerPreferences,
+	})
 
 	React.useEffect(() => {
 		if (!shouldUseOfflineVideo) return
@@ -801,7 +803,7 @@ function EpicVideo({
 									}
 								>
 									<video
-										ref={nativeVideoRef}
+										ref={setNativeVideoRef}
 										slot="media"
 										aria-label={title}
 										className="h-full w-full"

packages/workshop-app/app/components/native-video-preferences.ts

@@ -0,0 +1,36 @@
+import * as React from 'react'
+
+type NativeVideoPlayerPreferences =
+	| {
+			playbackRate?: number | null
+			volumeRate?: number | null
+	  }
+	| null
+	| undefined
+
+export function useApplyNativeVideoPreferences({
+	shouldApply,
+	videoElement,
+	playerPreferences,
+}: {
+	shouldApply: boolean
+	videoElement: HTMLVideoElement | null
+	playerPreferences: NativeVideoPlayerPreferences
+}) {
+	React.useEffect(() => {
+		if (!shouldApply || !videoElement) return
+
+		if (typeof playerPreferences?.playbackRate === 'number') {
+			videoElement.playbackRate = playerPreferences.playbackRate
+		}
+
+		if (typeof playerPreferences?.volumeRate === 'number') {
+			videoElement.volume = playerPreferences.volumeRate
+		}
+	}, [
+		playerPreferences?.playbackRate,
+		playerPreferences?.volumeRate,
+		shouldApply,
+		videoElement,
+	])
+}

packages/workshop-app/tests/native-video-preferences.browser.test.tsx

@@ -0,0 +1,103 @@
+import * as React from 'react'
+import { expect, test } from 'vitest'
+import { page } from 'vitest/browser'
+import { render } from 'vitest-browser-react'
+import { useApplyNativeVideoPreferences } from '#app/components/native-video-preferences.ts'
+
+function LegacyHydrationDelayedVideoPreferences() {
+	const playbackRate = 1.75
+	const volumeRate = 0.25
+	const shouldUseOfflineVideo = true
+	const nativeVideoRef = React.useRef<HTMLVideoElement>(null)
+	const [isHydrated, setIsHydrated] = React.useState(false)
+	const [snapshot, setSnapshot] = React.useState('legacy:pending')
+
+	React.useEffect(() => {
+		setIsHydrated(true)
+	}, [])
+
+	React.useEffect(() => {
+		if (!nativeVideoRef.current) return
+		if (typeof playbackRate === 'number') {
+			nativeVideoRef.current.playbackRate = playbackRate
+		}
+		if (typeof volumeRate === 'number') {
+			nativeVideoRef.current.volume = volumeRate
+		}
+	}, [playbackRate, volumeRate, shouldUseOfflineVideo])
+
+	React.useEffect(() => {
+		if (!isHydrated || !nativeVideoRef.current) return
+		setSnapshot(
+			`legacy:${nativeVideoRef.current.playbackRate.toFixed(2)}|${nativeVideoRef.current.volume.toFixed(2)}`,
+		)
+	}, [isHydrated])
+
+	return (
+		<div>
+			{isHydrated ? (
+				<video ref={nativeVideoRef} aria-label="legacy-video" />
+			) : (
+				<span>legacy-fallback</span>
+			)}
+			<span>{snapshot}</span>
+		</div>
+	)
+}
+
+function FixedHydrationDelayedVideoPreferences() {
+	const playerPreferences = { playbackRate: 1.75, volumeRate: 0.25 }
+	const shouldUseOfflineVideo = true
+	const nativeVideoRef = React.useRef<HTMLVideoElement>(null)
+	const [nativeVideoElement, setNativeVideoElement] =
+		React.useState<HTMLVideoElement | null>(null)
+	const [isHydrated, setIsHydrated] = React.useState(false)
+	const [snapshot, setSnapshot] = React.useState('fixed:pending')
+	const setNativeVideoRef = React.useCallback(
+		(element: HTMLVideoElement | null) => {
+			nativeVideoRef.current = element
+			setNativeVideoElement(element)
+		},
+		[],
+	)
+
+	useApplyNativeVideoPreferences({
+		shouldApply: shouldUseOfflineVideo,
+		videoElement: nativeVideoElement,
+		playerPreferences,
+	})
+
+	React.useEffect(() => {
+		setIsHydrated(true)
+	}, [])
+
+	React.useEffect(() => {
+		if (!nativeVideoElement || !nativeVideoRef.current) return
+		setSnapshot(
+			`fixed:${nativeVideoRef.current.playbackRate.toFixed(2)}|${nativeVideoRef.current.volume.toFixed(2)}`,
+		)
+	}, [nativeVideoElement])
+
+	return (
+		<div>
+			{isHydrated ? (
+				<video ref={setNativeVideoRef} aria-label="fixed-video" />
+			) : (
+				<span>fixed-fallback</span>
+			)}
+			<span>{snapshot}</span>
+		</div>
+	)
+}
+
+test('legacy ref-only effect misses preferences after hydration (aha)', async () => {
+	await render(<LegacyHydrationDelayedVideoPreferences />)
+
+	await expect.element(page.getByText('legacy:1.00|1.00')).toBeVisible()
+})
+
+test('applies preferences when delayed video element mounts', async () => {
+	await render(<FixedHydrationDelayedVideoPreferences />)
+
+	await expect.element(page.getByText('fixed:1.75|0.25')).toBeVisible()
+})