Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

89.6 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import {
	type CropRegion,
	DEFAULT_CROP_REGION,
	MAX_NATIVE_PLAYBACK_RATE,
} from "@/components/video-editor/types";
import {
	clickHitBuffers,
	playClickHits,
	resetClickPlayhead,
	takeCrossedClickHits,
} from "@/lib/ai-edition/clickSound";
import {
	resolveFadeSecs,
	takesByHeadFragment,
	trackGroupId,
} from "@/lib/ai-edition/document/audioTracks";
import {
	projectRawTimelineSecToPlayback,
	resolvePlaybackSegments,
} from "@/lib/ai-edition/document/timeline";
import type {
	AxcutAudioTrack,
	AxcutClip,
	AxcutTrimRange,
	AxcutZoomRegion,
} from "@/lib/ai-edition/schema";
import { audioGainScalar } from "@/lib/ai-edition/store/editorSettings";
import { useEditorSettings } from "@/lib/ai-edition/store/useEditorSettings";
import { removedRawSpans } from "@/lib/ai-edition/timeline/programme-time";
import { findActiveSpeedRegion, type SpeedRegion } from "@/lib/ai-edition/timeline/speed";
import {
	consumedSourceSec,
	type TakePiece,
	takePlaybackAt,
	takeProgramme,
} from "@/lib/ai-edition/timeline/take-programme";
import {
	clampVirtualTime,
	findNextKeptSegment,
	findRawClipForSegment,
	getRawVirtualStartTime,
	locateKeptSegment,
	locateSourcePosition,
	locateVirtualPosition,
	totalVirtualDuration,
} from "@/lib/ai-edition/timeline/virtual-preview";
import {
	computeZoomPreviewTransform,
	IDENTITY_ZOOM_TRANSFORM,
} from "@/lib/ai-edition/timeline/zoom-preview";
import {
	describeMediaError,
	formatMediaError,
	mediaErrorDisposition,
	pruneReloads,
	retryDelayMs,
} from "./mediaError";
import styles from "./VirtualPreview.module.css";
import { keepTimeByWallClock } from "./wallClock";

export interface VideoSource {
	id: string;
	src: string;
	/** Original filesystem path, used by the main process to expose the second audio track. */
	filePath?: string;
	label: string;
}

/** Drift tolerated before an audio element that is NOT free-running gets placed
 *  exactly. Nothing sustains a parked element's position, and placing it costs
 *  nothing because it is not playing. */
const AUDIO_PARKED_LEASH_SEC = 0.025;

/** How a PLAYING audio element that rides the video's clock (the recording's own sound) is held
 *  to the picture: by its `playbackRate`, not by seeks.
 *
 *  It used to be held by seeks, at `AUDIO_PARKED_LEASH_SEC`, on the grounds that the element
 *  syncs to the `<video>`'s own authoritative clock and so could be kept that tight. Measured
 *  in the shipped editor on a Snapdragon X Elite, during ordinary playback, it could not:
 *  157 `seeking` events in 20 s against a single `seeked`, and 87 `currentTime` writes in
 *  15 s — six a second, each stepping forward by ~0.1 s, which is exactly the time that had
 *  passed. The element was being sent to where it was already heading, and every write
 *  flushed its pipeline: the stutter.
 *
 *  The tight leash assumed the rAF tick runs close behind the video clock. It does not when
 *  the renderer main thread is loaded (measured ~44 % blocked during playback): ticks land
 *  100+ ms apart, the element has free-run past 25 ms by then, and gets yanked back. The
 *  yank stalls it, so it falls behind again — which is why the drift sat at a steady ~100 ms
 *  instead of decaying.
 *
 *  Widening the leash ends the storm and keeps the offset instead: a seek lands the audio
 *  BEHIND the picture by its own latency (that ~100 ms), and both elements then run at the
 *  same rate, so nothing ever closes it. Audio is noticed from about 45 ms when it leads and
 *  about 125 ms when it lags (ITU-R BT.1359), so an offset that stays is a defect, not a
 *  tolerance.
 *
 *  So the element is nudged. Once it drifts more than `AUDIO_NUDGE_START_SEC` its rate is
 *  trimmed by `AUDIO_NUDGE_FRACTION` toward the picture, and it goes back to the video's own
 *  rate within `AUDIO_NUDGE_STOP_SEC`; the gap between the two keeps an element at the edge
 *  from flipping its rate every frame. A rate change flushes nothing, and with
 *  `preservesPitch` (the default) it does not move the pitch. It closes ~50 ms a second, so a
 *  seek's 100 ms is gone in ~2 s and a free-running clock skew never builds up. */
export const AUDIO_NUDGE_START_SEC = 0.02;
export const AUDIO_NUDGE_STOP_SEC = 0.005;
export const AUDIO_NUDGE_FRACTION = 0.05;

/** Past this a nudge would take seconds and something else is wrong (a stalled or starved
 *  element): only then is a seek worth its flush. Kept above the ~100 ms a seek itself
 *  leaves, or the seek would be the thing that triggers the next one. */
export const AUDIO_SEEK_LEASH_SEC = 0.3;

/** Drift tolerated on an imported track (issue #350) while it plays. It syncs to
 *  `virtualTimeSec`, which is DERIVED from the video clock each frame and so is noisier than
 *  the recording's own audio, and it carries BGM or voiceover rather than lip sync, so it is
 *  left to free-run inside a wide leash. */
export const IMPORTED_AUDIO_PLAYING_LEASH_SEC = 0.3;

/** What the rAF tick should do to one of the recording's audio elements this frame. */
export interface AudioSteer {
	/** Write `currentTime`. */
	seek: boolean;
	/** `playbackRate` as a multiple of the video's own: 1 on target, nudged while catching up. */
	rateFactor: number;
}

/** Decide how to hold an audio element that rides the video's clock to the picture.
 *
 *  `driftSec` is the element's position minus where the picture is: positive means the audio
 *  is AHEAD. `freeRunning` means it is playing and is meant to be. `seeking` means a write is
 *  already in flight: another one restarts that seek instead of finishing it, so the element
 *  never arrives and the drift that triggered it never closes (issue #395, which the video
 *  path took and the audio path had not). `jumped` means the picture was MOVED, on purpose,
 *  since this element was last placed: a scrub, a skipped cut, a clip junction. That is
 *  indistinguishable from clock drift by size, since a cut can be 50 ms, so the caller says
 *  so, and the audio follows whatever the drift once it is not seeking. `nudged` is whether
 *  its rate is off the video's now, which is what makes the stop threshold apply. */
export function steerAudio(
	driftSec: number,
	freeRunning: boolean,
	seeking: boolean,
	jumped: boolean,
	nudged: boolean,
): AudioSteer {
	if (seeking) {
		return { seek: false, rateFactor: 1 };
	}
	if (jumped) {
		return { seek: true, rateFactor: 1 };
	}
	if (!freeRunning) {
		// Nothing sustains a parked element's position, and placing it costs nothing.
		return { seek: Math.abs(driftSec) > AUDIO_PARKED_LEASH_SEC, rateFactor: 1 };
	}
	const off = Math.abs(driftSec);
	if (off > AUDIO_SEEK_LEASH_SEC) {
		return { seek: true, rateFactor: 1 };
	}
	if (off > (nudged ? AUDIO_NUDGE_STOP_SEC : AUDIO_NUDGE_START_SEC)) {
		return { seek: false, rateFactor: 1 - Math.sign(driftSec) * AUDIO_NUDGE_FRACTION };
	}
	return { seek: false, rateFactor: 1 };
}

/** Whether an imported track's drift warrants a `currentTime` write.
 *
 *  `freeRunning` means the element is playing and is supposed to be: it holds its own
 *  position, so only a real discontinuity — a scrub, a trim jump, a first play — is worth
 *  the cost of a seek. See issue #395 and `VirtualPreview.seekStorm.test.tsx` for what
 *  happens when writes are issued per frame instead.
 *
 *  `seeking` is the other half of that lesson: a write onto an element that is still
 *  seeking restarts the seek rather than finishing it, so the element never arrives and
 *  the drift that triggered the write never closes. */
export function shouldResyncAudio(
	driftSec: number,
	freeRunning: boolean,
	playingLeashSec: number,
	seeking = false,
): boolean {
	if (seeking) {
		return false;
	}
	return Math.abs(driftSec) > (freeRunning ? playingLeashSec : AUDIO_PARKED_LEASH_SEC);
}

/** The track lists Chromium exposes on a media element under the `AudioVideoTracks` Blink
 *  feature, which the editor window turns on (`createEditorWindow`). Absent elsewhere. */
interface MediaTrackLists {
	audioTracks?: { length: number };
	videoTracks?: { length: number; [index: number]: { selected: boolean } };
}

/**
 * Stops Chromium decoding the picture of a media element that is only here for its clock or
 * its sound: the native compositor draws every pixel of the preview. Measured on a 1080p60
 * recording: a hidden `<video>` that plays keeps ~6.7 % of an RTX 4070 Ti's decode engine
 * busy, and an `<audio>` on the same mp4 decodes its picture just as much — a second and a
 * third decode of the recording next to the compositor's own. With the video track
 * deselected the element decodes no frame, and its clock, `playbackRate` and seeks behave
 * the same.
 *
 * Without a sound track the element has no stream left to keep time with once its picture
 * is deselected (measured: it jumps to its end on `play`), so it keeps time by the wall clock
 * instead (`keepTimeByWallClock`, issue #994). Returns whether the track was dropped.
 */
export function dropVideoTrack(element: HTMLMediaElement): boolean {
	const { audioTracks, videoTracks } = element as HTMLMediaElement & MediaTrackLists;
	if (!videoTracks?.length || !audioTracks) {
		return false;
	}
	if (audioTracks.length === 0) {
		keepTimeByWallClock(element);
	}
	for (let index = 0; index < videoTracks.length; index++) {
		videoTracks[index].selected = false;
	}
	return true;
}

/**
 * Where an audio element should sit to track the video, and whether it should be playing.
 *
 * The audio elements mirror the video's own time — there is no offset to apply, because the
 * only per-track difference that survives is length: the supplemental track is extracted
 * separately and can end before the video does. Past its end the element is parked at its
 * duration and paused rather than left seeking into nothing.
 *
 * Only an unusable duration falls back to Infinity — `NaN` before the element has its
 * metadata, or a negative value. Zero is a real length, and the shortest track that is
 * already over: an empty extraction has to read as ended, or the rAF loop below spends the
 * whole timeline seeking and calling `play()` on an element that has nothing to play.
 */
export function resolveAudioTrackPlayback(
	videoTimeSec: number,
	durationSec = Number.POSITIVE_INFINITY,
) {
	const finiteDuration = Number.isFinite(durationSec) && durationSec >= 0 ? durationSec : Infinity;
	return {
		targetTimeSec: Math.min(Math.max(0, videoTimeSec), finiteDuration),
		shouldPlay: videoTimeSec >= 0 && videoTimeSec < finiteDuration,
	};
}

/**
 * Where an imported audio track (issue #350) should sit against the playback
 * clock, and whether it should be playing there. Both arguments are in
 * trim-compressed OUTPUT-programme seconds: `outputTimeSec` is the playhead and
 * `outputStartSec` is the track's head, each already projected from raw through
 * the trims by `projectRawTimelineSecToPlayback` in the caller.
 *
 * The track plays as one CONTIGUOUS block: `[outputStartSec, outputStartSec +
 * (trimEnd - trimStart)]`, its source position `trimStart` plus how far the
 * playhead is past the head. Outside that span it parks at the nearer trim edge
 * and stays paused, the same discipline `resolveAudioTrackPlayback` uses so the
 * rAF never seeks an element into nothing.
 *
 * Working in output space is what keeps the preview identical to the export: the
 * native `audio::mix_external_tracks` overlays the decoded window
 * `[trimStart, trimEnd]` contiguously at its projected offset, so an interior
 * trim shortens the programme UNDER the track without cutting the track's own
 * content. Deriving `local` from the RAW playhead instead (which jumps across a
 * cut) made the element skip that much source and end early — the preview/export
 * desync this fixes.
 */
export function resolveTimelineAudioPlayback(
	outputTimeSec: number,
	outputStartSec: number,
	track: AxcutAudioTrack,
	/** The fragment's own span in seconds — how long it plays on the timeline,
	 *  which is independent of how much file is left after the offset. */
	spanSec: number,
) {
	const offset = Math.max(0, track.offsetMs / 1000);
	const sourceEnd = track.durationSec > 0 ? track.durationSec : offset + spanSec;
	// The window the file has left after the offset; the fragment stops at
	// whichever runs out first, its span or the file.
	const windowLen = Math.max(0, sourceEnd - offset);
	const local = outputTimeSec - outputStartSec;
	const active = local >= 0 && local < spanSec;
	if (track.loop && windowLen > 0) {
		// Fold into the repeating window, exactly as the export's per-repeat mix
		// entries do, so preview and render stay in phase.
		return {
			targetTimeSec: offset + (local > 0 ? local % windowLen : 0),
			shouldPlay: active,
		};
	}
	return {
		targetTimeSec: Math.min(Math.max(offset, offset + local), sourceEnd),
		// A file shorter than its span goes silent at the end rather than
		// restarting: seeking a finished element back would stutter it every frame.
		shouldPlay: active && local < windowLen,
	};
}

/** Fraction 0..1 of a track's volume `localSec` into its span, applying the
 *  ramps. Shares `resolveFadeSecs` with the export so a fade too long for its
 *  span is reduced the same way on both sides. */
export function timelineAudioFadeAt(
	track: AxcutAudioTrack,
	localSec: number,
	spanSec: number,
): number {
	if (track.muted) return 0;
	const { fadeInSec, fadeOutSec } = resolveFadeSecs(track.fadeInMs, track.fadeOutMs, spanSec);
	let v = 1;
	if (fadeInSec > 0 && localSec < fadeInSec) v = Math.min(v, Math.max(0, localSec / fadeInSec));
	if (fadeOutSec > 0) {
		const remaining = spanSec - localSec;
		if (remaining < fadeOutSec) v = Math.min(v, Math.max(0, remaining / fadeOutSec));
	}
	return v;
}

/**
 * The export's music ducking (`duck_curve` in audio.rs), mirrored for the preview: the same
 * depth, speech threshold, hold and release. One difference is structural: the export holds
 * the whole voice and looks ahead, so its dip is already complete when a word starts, while
 * the preview only hears the voice once it plays, so here the same ramp ends `attackSec`
 * into the word.
 */
export const MUSIC_DUCK = {
	depthDb: -10,
	thresholdDbfs: -35,
	holdSec: 0.5,
	attackSec: 0.25,
	releaseSec: 0.6,
} as const;

/** A music bed's ducking gain in dB, one preview frame of `frameSec` later, when the voice
 *  was last heard `sinceVoiceSec` ago. Straight ramps in dB, like the export's. */
export function nextMusicDuckDb(
	currentDb: number,
	sinceVoiceSec: number,
	frameSec: number,
): number {
	const { depthDb, holdSec, attackSec, releaseSec } = MUSIC_DUCK;
	return sinceVoiceSec <= holdSec
		? Math.max(depthDb, currentDb + (depthDb / attackSec) * frameSec)
		: Math.min(0, currentDb - (depthDb / releaseSec) * frameSec);
}

export interface PreviewAudioGraph {
	context: AudioContext;
	/** Output trim: everything the preview plays goes through it. */
	gain: GainNode;
	/** The recording's own audio (primary + supplemental elements), on its way to `gain`. */
	voice: GainNode;
	/** Listens to the voice — the recording and every voiceover — to duck the music. */
	analyser: AnalyserNode;
	/** Between `gain` and the speakers: `headroom` scales the mix into `ceiling`'s input range,
	 *  and `ceiling` keeps it under full scale (see `previewCeilingCurve`). */
	headroom: GainNode;
	ceiling: WaveShaperNode;
}

/** The export limiter's ceiling, `LIMITER_CEILING` in audio.rs: −1.5 dBFS. */
export const PREVIEW_AUDIO_CEILING = 0.841_395_1;
/** Loudest mix the ceiling stage reads, as a multiple of full scale: +24 dB, a full-scale file
 *  under the largest loudness boost and the largest output trim. Louder lands on the curve's
 *  flat end, which the curve has reached long before. */
export const PREVIEW_AUDIO_HEADROOM = 16;

/**
 * The curve of the WaveShaperNode in front of the preview's speakers. Without it, the loudness
 * boost (up to +12 dB) and the output trim push a loud take's peaks past full scale, and the
 * audio device clips them: the preview saturates where the export, whose limiter holds them
 * at −1.5 dBFS, does not (measured on a real take: a −7.1 dBFS peak raised 8.9 dB, 92 samples
 * over).
 *
 * It is the identity up to the export's ceiling, then a tanh knee that leaves the identity
 * with the same slope and rises towards full scale without reaching it. A curve, not a
 * limiter, because a curve has no state (see `applyPreviewAudioSettings`): everything under
 * the ceiling plays exactly as the export writes it, and only the peaks the export limits
 * are shaped, here by their own level rather than by a gain riding over 5 ms. A WaveShaper
 * reads its input on [−1, 1], so `headroom` divides the mix by `PREVIEW_AUDIO_HEADROOM` on
 * the way in and the curve's values are real levels. The point count is odd so that silence
 * is a point of its own.
 */
export function previewCeilingCurve(points = 8193): Float32Array<ArrayBuffer> {
	const knee = PREVIEW_AUDIO_CEILING;
	const curve = new Float32Array(points);
	for (let index = 0; index < points; index += 1) {
		const level = ((index / (points - 1)) * 2 - 1) * PREVIEW_AUDIO_HEADROOM;
		const magnitude = Math.abs(level);
		curve[index] =
			Math.sign(level) *
			(magnitude <= knee
				? magnitude
				: knee + (1 - knee) * Math.tanh((magnitude - knee) / (1 - knee)));
	}
	return curve;
}

/**
 * The preview's gains are static, and that is deliberate: each is the same
 * `10 ** (dB / 20)` scalar the export applies natively, so what the editor plays is what
 * the export writes.
 *
 * - `gainDb` is the output trim, `finish_audio`'s gain.
 * - `voiceGainDb` is the loudness normalisation of the recording being played. The
 *   compositor measures it over the whole file and applies it to every clip cut from that
 *   file at export (`loudness_gain_db`); the preview asks for the same number.
 *
 * Nothing with state belongs here. The export runs on the assembled timeline (trimmed,
 * speed-adjusted, concatenated); the preview runs on the untouched source file, seeked. A
 * filter or a compressor would see a different signal on each side and drift. That is why
 * the export's peak limiter has a stateless stand-in here, `previewCeilingCurve`, rather
 * than a compressor.
 */
export function applyPreviewAudioSettings(
	graph: PreviewAudioGraph | null,
	elements: Array<HTMLAudioElement | null>,
	gainDb: number,
	voiceGainDb = 0,
): void {
	const outputGain = audioGainScalar(gainDb);
	const voiceGain = audioGainScalar(voiceGainDb);
	if (!graph) {
		for (const element of elements) {
			if (element) element.volume = Math.min(1, outputGain * voiceGain);
		}
		return;
	}
	graph.gain.gain.value = outputGain;
	graph.voice.gain.value = voiceGain;
}

/** First clip (by timeline order) starting strictly after `afterTimelineStartSec` —
 *  independent of the `clips` array's own order, which is never guaranteed to match
 *  timeline order (a clip can be inserted/reordered at any array index; only
 *  `timelineStartSec` is authoritative). Shared by every clip-boundary-advance path
 *  (rAF tick, the `<video>` `ended` event) so they all agree on "the next clip". */
function findNextClipByTimelineOrder(
	clips: AxcutClip[],
	afterTimelineStartSec: number,
): AxcutClip | undefined {
	return clips
		.filter((clip) => clip.timelineStartSec > afterTimelineStartSec + 0.001)
		.sort((a, b) => a.timelineStartSec - b.timelineStartSec)[0];
}

interface VirtualPreviewProps {
	videoSources: VideoSource[];
	/** Imported audio tracks to mix over the video (issue #350), and the file URLs
	 *  their assets resolve to (keyed by assetId in `id`). Both default to empty, so
	 *  a project with no imported audio behaves exactly as before. */
	audioTracks?: AxcutAudioTrack[];
	audioSources?: VideoSource[];
	clips: AxcutClip[];
	zoomRegions?: AxcutZoomRegion[];
	speedRegions?: SpeedRegion[];
	trimRanges?: AxcutTrimRange[];
	/** Play the raw timeline continuously while capturing a voiceover. */
	playUneditedTimeline?: boolean;
	seekTarget?: {
		timeSec: number;
		isSource?: boolean;
		requestId: number;
		preservePlayback?: boolean;
	} | null;
	onTimeChange?: (timeSec: number) => void;
	onLoadedMetadata?: (
		durationSec: number,
		assetId: string,
		videoWidth: number,
		videoHeight: number,
	) => void;
	onVideoElement?: (element: HTMLVideoElement | null) => void;
	videoStyle?: React.CSSProperties;
	/** Called with the id of the asset that failed, not as a bare "the preview is
	 *  broken" signal: only ONE source is mounted at a time (`activeSource`), so
	 *  the caller has no other way to tell which of its sources is dead.
	 *  Fires only once the retry budget below is spent — a transient decode or
	 *  network blip is reloaded here and never reaches the caller. `detail`
	 *  carries the MediaError code for the card and for bug reports. */
	onVideoError?: (assetId: string, detail: string) => void;
	/** The mounted source produced a frame again — after a reload, or simply
	 *  because the playhead moved onto a healthy asset. The caller needs this to
	 *  drop a failure it is showing; without it, a card outlives its failure and
	 *  we are back to a latch, only quieter. */
	onVideoRecovered?: (assetId: string) => void;
	/** Bumped by the caller's Retry button. A user-initiated reload always runs:
	 *  it cancels any pending backoff and starts the budget over, because the
	 *  user clicked knowing something changed (they put the file back). */
	retryToken?: number;
	/** Crop of the active clip, as fractions (0-1) of the source frame. Absent/
	 * identity ({x:0,y:0,width:1,height:1}) renders the full frame, unchanged
	 * from before crop support existed. */
	cropRegion?: CropRegion | null;
}

const NO_TRIM_RANGES: AxcutTrimRange[] = [];
const NO_SPEED_REGIONS: SpeedRegion[] = [];

export function VirtualPreview({
	videoSources,
	audioTracks = [],
	audioSources = [],
	clips,
	zoomRegions = [],
	speedRegions = [],
	trimRanges = [],
	playUneditedTimeline = false,
	seekTarget,
	onTimeChange,
	onLoadedMetadata,
	onVideoElement,
	videoStyle,
	onVideoError,
	onVideoRecovered,
	retryToken,
	cropRegion,
}: VirtualPreviewProps) {
	const { settings } = useEditorSettings();
	const playbackTrimRanges = playUneditedTimeline ? NO_TRIM_RANGES : trimRanges;
	const playbackSpeedRegions = playUneditedTimeline ? NO_SPEED_REGIONS : speedRegions;
	// ponytail: an oversized, offset video inside .videoFrame's overflow:hidden
	// box — the same "scale + negative-position the full frame, let the
	// container clip the rest" technique the export renderer uses via a Pixi
	// sprite offset (frameRenderer.ts's updateLayout). Percentages here
	// resolve against .videoFrame's own (already crop-corrected, see
	// PreviewCanvas's screenSize) box, so this stays correct at any size
	// without measuring pixels. Identity crop reduces to 100%/100%/0/0 — the
	// exact same box the video rendered in before crop support existed.
	const region = cropRegion ?? DEFAULT_CROP_REGION;
	const isIdentityCrop =
		region.x === 0 && region.y === 0 && region.width === 1 && region.height === 1;
	const cropVideoStyle: React.CSSProperties = isIdentityCrop
		? {}
		: {
				position: "absolute",
				width: `${100 / region.width}%`,
				height: `${100 / region.height}%`,
				left: `${(-region.x * 100) / region.width}%`,
				top: `${(-region.y * 100) / region.height}%`,
			};
	const videoRef = useRef<HTMLVideoElement | null>(null);
	const primaryAudioRef = useRef<HTMLAudioElement | null>(null);
	const supplementalAudioRef = useRef<HTMLAudioElement | null>(null);
	// The audio elements that have not yet followed the last explicit move of the picture (see
	// `applySourceTime` and `steerAudio`).
	const audioJumpedRef = useRef(new WeakSet<HTMLAudioElement>());
	const [primaryAudioEl, setPrimaryAudioEl] = useState<HTMLAudioElement | null>(null);
	const [supplementalAudioEl, setSupplementalAudioEl] = useState<HTMLAudioElement | null>(null);
	const [supplementalAudioSrc, setSupplementalAudioSrc] = useState<string | null>(null);
	const [audioProbeComplete, setAudioProbeComplete] = useState(false);
	const audioGainDbRef = useRef(settings.audioGainDb);
	useEffect(() => {
		audioGainDbRef.current = settings.audioGainDb;
	}, [settings.audioGainDb]);
	const audioContextRef = useRef<AudioContext | null>(null);
	const audioContextCloseTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
	const audioSourceNodesRef = useRef(new WeakMap<HTMLAudioElement, MediaElementAudioSourceNode>());
	// Per-track gain nodes for imported audio (issue #350). Keyed by track id so the rAF
	// can set each track's level live (a boost past 0 dB, which `element.volume` can't do —
	// same reason the primary/supplemental sum through a gain node). The graph effect owns
	// their lifecycle; the map is cleared and rebuilt whenever the routing is torn down.
	const audioTrackGainNodesRef = useRef<Map<string, GainNode>>(new Map());
	const audioGraphRef = useRef<PreviewAudioGraph | null>(null);
	const videoFrameRef = useRef<HTMLDivElement | null>(null);

	const isProgrammaticSeekRef = useRef(false);
	// The seek that arrived while another was still running (see applySourceTime).
	const pendingScrubTargetRef = useRef<number | null>(null);
	const pendingSeekRef = useRef<{ sourceTimeSec: number; play: boolean } | null>(null);
	// When each AUTOMATIC reload happened. The budget is "reloads inside
	// RELOAD_WINDOW_MS", so it expires by itself: a dead file burns it in
	// seconds, while the occasional transient across a long editing session
	// never accumulates. A lifetime count could not tell those apart and would
	// eventually show a card on healthy media (see mediaError.ts).
	const reloadsRef = useRef<number[]>([]);
	// Set when we stop trying, so an expiring window cannot restart the cycle
	// behind the card. Cleared only by Retry or a media change.
	const gaveUpRef = useRef(false);
	const retryTimerRef = useRef<number | null>(null);
	// True from the moment a reload is scheduled until the element produces
	// metadata again. Read by the rAF tick, which must not steer a dead decoder.
	const recoveringRef = useRef(false);
	// The last position read off a healthy element. `video.currentTime` is 0
	// after load(), and 0 after a load that failed before decoding a frame, so
	// it cannot be the fallback resume point — that is a silent rewind.
	const lastGoodSourceTimeRef = useRef(0);
	// Which clip the rAF tick below believes is currently playing — set
	// whenever a seek unambiguously resolves one (via locateVirtualPosition,
	// timeline position → clip). Passed back into locateSourcePosition so
	// two clips that share the same source asset (and possibly the same
	// source range) don't get conflated: without this, resolving "current
	// clip" from (assetId, sourceTime) alone always picks the earliest
	// matching clip, even while a later one is the one actually playing.
	const activeClipIdRef = useRef<string | null>(null);
	const [virtualTimeSec, setVirtualTimeSec] = useState(0);
	const [loadState, setLoadState] = useState<"idle" | "loading" | "ready" | "error">("idle");
	const loadStateRef = useRef(loadState);
	loadStateRef.current = loadState;
	const updateLoadState = useCallback((nextState: "idle" | "loading" | "ready" | "error") => {
		loadStateRef.current = nextState;
		setLoadState(nextState);
	}, []);
	const [sourceIndex, setSourceIndex] = useState(0);

	const virtualDurationSec = useMemo(() => totalVirtualDuration(clips), [clips]);
	const activeSource = videoSources[sourceIndex] ?? null;

	useEffect(() => {
		let cancelled = false;
		setSupplementalAudioSrc(null);
		setAudioProbeComplete(false);
		if (!activeSource?.filePath || !window.electronAPI?.preparePreviewAudioTrack) {
			setAudioProbeComplete(true);
			return () => {
				cancelled = true;
			};
		}
		void window.electronAPI.preparePreviewAudioTrack(activeSource.filePath).then(
			(result) => {
				if (cancelled) return;
				setSupplementalAudioSrc(result.success ? (result.path ?? null) : null);
				setAudioProbeComplete(true);
			},
			() => {
				if (cancelled) return;
				setSupplementalAudioSrc(null);
				setAudioProbeComplete(true);
			},
		);
		return () => {
			cancelled = true;
		};
	}, [activeSource?.filePath]);

	// Loudness normalisation of every voice file the preview plays: the recording mounted now
	// and each voiceover take. The export levels them to −16 LUFS with a gain the compositor
	// measures over the whole file (`loudness_gain_db`), so asking it for that gain is what
	// makes the preview play the voice at the exported level. Keyed by path: the gain belongs
	// to the file, and the compositor caches it for the export that follows. Until it arrives
	// the file plays as recorded — the first second or two after a recording is opened.
	const [loudnessGainDbByPath, setLoudnessGainDbByPath] = useState<ReadonlyMap<string, number>>(
		() => new Map(),
	);
	const loudnessGainDbByPathRef = useRef(loudnessGainDbByPath);
	loudnessGainDbByPathRef.current = loudnessGainDbByPath;
	const requestedLoudnessRef = useRef(new Set<string>());
	const voicePathsKey = [
		activeSource?.filePath,
		...audioTracks
			.filter((track) => track.kind === "voiceover")
			.map((track) => audioSources.find((source) => source.id === track.assetId)?.filePath),
	]
		.filter((path): path is string => Boolean(path))
		.join("\n");
	const activeVoicePath = activeSource?.filePath;
	const measuredForRetryRef = useRef(retryToken);
	useEffect(() => {
		const getLoudnessGain = window.electronAPI?.getLoudnessGain;
		if (!getLoudnessGain) return;
		// Retry reloads the file after it was unavailable, and its first measurement may have
		// failed with it. Forget that answer and ask again; it plays at 0 dB until the new one.
		if (retryToken !== measuredForRetryRef.current) {
			measuredForRetryRef.current = retryToken;
			if (activeVoicePath) {
				requestedLoudnessRef.current.delete(activeVoicePath);
				setLoudnessGainDbByPath((previous) => {
					if (!previous.has(activeVoicePath)) return previous;
					const next = new Map(previous);
					next.delete(activeVoicePath);
					return next;
				});
			}
		}
		for (const path of voicePathsKey.split("\n")) {
			if (!path || requestedLoudnessRef.current.has(path)) continue;
			requestedLoudnessRef.current.add(path);
			void getLoudnessGain(path).then(
				(result) =>
					setLoudnessGainDbByPath((previous) =>
						new Map(previous).set(path, result.success ? result.gainDb : 0),
					),
				() => undefined,
			);
		}
	}, [voicePathsKey, retryToken, activeVoicePath]);
	const voiceGainDb = activeSource?.filePath
		? (loudnessGainDbByPath.get(activeSource.filePath) ?? 0)
		: 0;
	const voiceGainDbRef = useRef(voiceGainDb);
	voiceGainDbRef.current = voiceGainDb;

	// Which imported-track elements are actually mounted (a track is rendered only once its
	// asset URL resolves — see the JSX). Re-routing the graph is keyed on this set, NOT on the
	// tracks' gains: a level change is applied live on the existing node by the rAF, so it must
	// not tear the graph down. Joined ids change only on a real mount/unmount.
	const mountedAudioTrackKey = audioTracks
		.filter((track) => audioSources.some((source) => source.id === track.assetId))
		.map((track) => track.id)
		.join(",");

	// Sum the audio elements into one gain node so the output trim can boost past 0 dB,
	// which `element.volume` cannot do. The primary media element carries track 1; on macOS
	// the existing IPC helper extracts track 2 (normally the microphone) so both are audible
	// instead of Chromium silently choosing one. Imported tracks (issue #350) join the same
	// graph through a per-track gain node so their boost survives the preview too.
	// biome-ignore lint/correctness/useExhaustiveDependencies: mountedAudioTrackKey is the trigger for re-routing tracks; the elements are read from the ref.
	useEffect(() => {
		if (!primaryAudioEl || !audioProbeComplete) return;
		if (supplementalAudioSrc && !supplementalAudioEl) return;
		const elements = [primaryAudioEl, supplementalAudioEl].filter(
			(value): value is HTMLAudioElement => Boolean(value),
		);
		const graph = ((): PreviewAudioGraph | null => {
			try {
				let context = audioContextRef.current;
				if (!context || context.state === "closed") {
					context = new AudioContext();
					audioContextRef.current = context;
					audioSourceNodesRef.current = new WeakMap();
				}
				const ceiling = context.createWaveShaper();
				ceiling.curve = previewCeilingCurve();
				ceiling.connect(context.destination);
				const headroom = context.createGain();
				headroom.gain.value = 1 / PREVIEW_AUDIO_HEADROOM;
				headroom.connect(ceiling);
				const gain = context.createGain();
				gain.connect(headroom);
				const voice = context.createGain();
				voice.connect(gain);
				// 1024 samples: about 21 ms of voice per reading, one reading per frame.
				const analyser = context.createAnalyser();
				analyser.fftSize = 1024;
				voice.connect(analyser);
				return { context, gain, voice, analyser, headroom, ceiling };
			} catch {
				return null;
			}
		})();
		if (!graph) {
			// WebAudio can be unavailable in unit tests or under a denied audio policy. No source
			// node was created, so `volume` still reaches the output — capped at 0 dB.
			applyPreviewAudioSettings(null, elements, audioGainDbRef.current, voiceGainDbRef.current);
			return;
		}

		const connectedSources: MediaElementAudioSourceNode[] = [];
		for (const element of elements) {
			try {
				let source = audioSourceNodesRef.current.get(element);
				if (!source) {
					source = graph.context.createMediaElementSource(element);
					audioSourceNodesRef.current.set(element, source);
				}
				source.disconnect();
				source.connect(graph.voice);
				connectedSources.push(source);
			} catch {
				// Routing THIS element failed; leave the others alone. Once
				// createMediaElementSource has run for an element its audio no longer reaches
				// the default output, so tearing the whole graph down here would mute the
				// preview outright rather than degrade it.
			}
		}
		// Imported tracks (issue #350): each mounted element gets source → per-track gain →
		// the output gain, so the effective level is trackGain × outputGain — the same order
		// the exporter mixes in (mix_external_tracks applies the track gain, finish_audio the
		// output gain). The rAF sets each node's value; created here at unity as a safe default.
		const trackGainNodes: GainNode[] = [];
		audioTrackGainNodesRef.current = new Map();
		for (const [trackId, element] of audioTrackElsRef.current) {
			try {
				let source = audioSourceNodesRef.current.get(element);
				if (!source) {
					source = graph.context.createMediaElementSource(element);
					audioSourceNodesRef.current.set(element, source);
				}
				source.disconnect();
				const trackGain = graph.context.createGain();
				source.connect(trackGain);
				trackGain.connect(graph.gain);
				// A voiceover is voice: the music ducks under it as under the recording.
				if (audioTracksRef.current.find((track) => track.id === trackId)?.kind === "voiceover") {
					trackGain.connect(graph.analyser);
				}
				audioTrackGainNodesRef.current.set(trackId, trackGain);
				connectedSources.push(source);
				trackGainNodes.push(trackGain);
			} catch {
				// Same rationale as the primary/supplemental loop: routing THIS track failed, so
				// leave the rest connected. The rAF falls back to `element.volume` for a track
				// with no gain node (capped at 0 dB, but audible).
			}
		}
		audioGraphRef.current = graph;
		applyPreviewAudioSettings(graph, elements, audioGainDbRef.current, voiceGainDbRef.current);
		return () => {
			audioGraphRef.current = null;
			for (const source of connectedSources) source.disconnect();
			for (const trackGain of trackGainNodes) trackGain.disconnect();
			audioTrackGainNodesRef.current = new Map();
			graph.voice.disconnect();
			graph.analyser.disconnect();
			graph.gain.disconnect();
			graph.headroom.disconnect();
			graph.ceiling.disconnect();
		};
	}, [
		primaryAudioEl,
		supplementalAudioEl,
		supplementalAudioSrc,
		audioProbeComplete,
		mountedAudioTrackKey,
	]);

	// Keep one AudioContext for the component. Closing and recreating it on an effect rerun
	// permanently silences an HTMLAudioElement because createMediaElementSource may only be
	// called once for that element. Delay final cleanup by one task so React StrictMode's
	// intentional setup → cleanup → setup cycle can cancel the close and reuse the context.
	useEffect(() => {
		if (audioContextCloseTimerRef.current) {
			clearTimeout(audioContextCloseTimerRef.current);
			audioContextCloseTimerRef.current = null;
		}
		return () => {
			// Nothing to tear down means nothing to schedule. WebAudio is unavailable
			// under jsdom and under a denied audio policy, so this ref is often still
			// null — and an unmount that leaves a timer behind for a context that was
			// never created is both waste and a lie to anyone counting timers to prove
			// this component cleans up after itself (see VirtualPreview.mediaError).
			if (!audioContextRef.current) return;
			audioContextCloseTimerRef.current = setTimeout(() => {
				audioContextCloseTimerRef.current = null;
				const context = audioContextRef.current;
				audioContextRef.current = null;
				audioSourceNodesRef.current = new WeakMap();
				audioTrackGainNodesRef.current = new Map();
				if (context) void context.close();
			}, 0);
		};
	}, []);

	useEffect(() => {
		applyPreviewAudioSettings(
			audioGraphRef.current,
			[primaryAudioRef.current, supplementalAudioRef.current],
			settings.audioGainDb,
			voiceGainDb,
		);
	}, [settings.audioGainDb, voiceGainDb]);

	const setPrimaryAudioElement = useCallback((element: HTMLAudioElement | null) => {
		primaryAudioRef.current = element;
		setPrimaryAudioEl(element);
	}, []);
	const setSupplementalAudioElement = useCallback((element: HTMLAudioElement | null) => {
		supplementalAudioRef.current = element;
		setSupplementalAudioEl(element);
	}, []);

	// ponytail: the cursor overlay wants source-media time (the recorded
	// cursor samples live on the original mp4 timeline, not the edited
	// virtual timeline). `setSourceTimeSec` is called from the 60 Hz rAF
	// below so the cursor follows the playhead even when the user scrubs.
	const [sourceTimeSec, setSourceTimeSec] = useState(0);

	// Drive the virtual-time preview clock at 60 Hz (the <video> timeupdate
	// event only fires ~4×/s, which is too slow to keep the webcam <video>
	// and any future audio element in sync — a 4 Hz sync lets the webcam
	// drift up to ~250 ms between corrections and produces a visible
	// audio/video desync). The virtual-time read here mirrors what
	// handleTimeUpdate does on every timeupdate; running it 60×/s keeps
	// the drift under a single frame (~16 ms). Inlined here so the rAF
	// can also handle clip-end advancement and the !position fall-back
	// without a separate <video onTimeUpdate> event firing at ~4 Hz.
	const sourceTimeSecRef = useRef(0);
	sourceTimeSecRef.current = sourceTimeSec;
	// ponytail: the rAF closure captured the props at mount time. The
	// auto-created clip arrives a tick after the source swaps, so reads
	// from the closure would forever see `clips: []` and the rAF would
	// bail at the `clips.length === 0` guard — leaving the scrub thumb
	// stuck at 0% and the drag range at `max=1`. The refs let the rAF
	// always see the latest values without re-creating on every clip
	// mutation.
	const clipsRef = useRef(clips);
	clipsRef.current = clips;
	// Same reason as `clipsRef`: the rAF projects the playhead and each imported
	// audio track's head raw→output every frame (see the audio-track loop), and
	// must see the live trims, not the set captured when the loop was created.
	const trimRangesRef = useRef(playbackTrimRanges);
	trimRangesRef.current = playbackTrimRanges;
	// What the film no longer contains, recomputed only when the cuts move — the rAF asks
	// it once per voiceover per frame, and walking every trim there would be wasteful.
	// The film's pauses, placed on the raw ruler once. The projection needs them or every
	// track after a pause lands D seconds early — the bug this argument exists to close.
	// One walk per take, recomputed only when the cuts or the insertions move. The rAF asks
	// it every frame per track, and walking on each would be wasteful.
	const takePiecesRef = useRef<Map<string, TakePiece[]>>(new Map());
	// Each take keyed by the fragment whose element plays it, as the export mixes it.
	const takesRef = useRef<Map<string, AxcutAudioTrack>>(new Map());
	const removedRef = useRef(removedRawSpans(clips, playbackTrimRanges));
	removedRef.current = useMemo(
		() => removedRawSpans(clips, playbackTrimRanges),
		[clips, playbackTrimRanges],
	);
	const takeWalks = useMemo(() => {
		const pieces = new Map<string, TakePiece[]>();
		const removed = removedRawSpans(clips, playbackTrimRanges);
		const takes = takesByHeadFragment(audioTracks);
		for (const pill of takes.values()) {
			if (pill.kind !== "voiceover" || pill.loop) continue;
			pieces.set(trackGroupId(pill), takeProgramme(pill, removed));
		}
		return { pieces, takes };
	}, [audioTracks, clips, playbackTrimRanges]);
	takePiecesRef.current = takeWalks.pieces;
	takesRef.current = takeWalks.takes;
	// Trim-narrowed (`resolvePlaybackSegments`) — used ONLY to detect "has the <video>'s own
	// currentTime drifted into a trim" and where to jump it back out to. Everything ELSE in
	// this component (`clips`/`clipsRef` above, virtualTimeSec, zoom/speed region lookups,
	// what gets reported via `onTimeChange`) stays on the RAW/document timeline — the same
	// coordinate space the ruler, zoom/speed regions, and the trim marker itself use. Keeping
	// these two lists separate (rather than swapping `clips` itself to the trim-narrowed one)
	// is what makes the reported playhead jump OVER a trim marker instead of drifting out of
	// sync with it: `locateSourcePosition` below, fed RAW clips, maps the underlying video's
	// source time to a RAW virtual time that jumps discontinuously by exactly the trim's
	// width the moment the video itself jumps — matching the marker's own pixel span.
	const playbackClips = useMemo(
		() => resolvePlaybackSegments(clips, playbackTrimRanges),
		[clips, playbackTrimRanges],
	);
	const playbackClipsRef = useRef(playbackClips);
	playbackClipsRef.current = playbackClips;
	const videoSourcesRef = useRef(videoSources);
	videoSourcesRef.current = videoSources;
	const sourceIndexRef = useRef(sourceIndex);
	sourceIndexRef.current = sourceIndex;
	const virtualTimeSecRef = useRef(virtualTimeSec);
	virtualTimeSecRef.current = virtualTimeSec;
	const virtualDurationSecRef = useRef(virtualDurationSec);
	virtualDurationSecRef.current = virtualDurationSec;
	const speedRegionsRef = useRef(playbackSpeedRegions);
	speedRegionsRef.current = playbackSpeedRegions;
	// Imported audio tracks (issue #350): the rAF reads these through refs, same as
	// everything else it touches, so a track added/edited mid-playback is picked up
	// without re-creating the loop. `audioTrackElsRef` maps a track id to its mounted
	// <audio> element (registered by the ref callback on render).
	const audioTracksRef = useRef(audioTracks);
	audioTracksRef.current = audioTracks;
	const audioSourcesRef = useRef(audioSources);
	audioSourcesRef.current = audioSources;
	// Live state of the music ducking (see MUSIC_DUCK): the gain, when the voice was last
	// heard, and the analyser's reading buffer, reused every frame.
	const musicDuckRef = useRef({
		db: 0,
		voiceAt: Number.NEGATIVE_INFINITY,
		tickAt: 0,
		reading: new Float32Array(1024),
	});
	const audioTrackElsRef = useRef<Map<string, HTMLAudioElement>>(new Map());
	const registerAudioTrackEl = useCallback((trackId: string, element: HTMLAudioElement | null) => {
		if (element) audioTrackElsRef.current.set(trackId, element);
		else audioTrackElsRef.current.delete(trackId);
	}, []);
	// Same reasoning as `clipsRef` above, for the one thing the rAF calls rather than reads:
	// `seekToVirtualTime` is a `useCallback` whose deps include `clips`, so it takes a new
	// identity on every clip mutation — a REORDER included. The rAF below is deliberately
	// re-created only when the active source swaps, so calling that callback straight from
	// the closure pins it to the clip order current at the last asset swap. The tick would
	// then pick the RIGHT next clip (it reads `clipsRef.current`, always fresh) and hand its
	// timeline time to a `locateVirtualPosition` resolving against the STALE layout, landing
	// on whichever clip used to occupy that position — the one that just played. That is the
	// "playback stops at the junction and jumps back to the start of the clip it just
	// finished, but only after reordering" bug: with no reorder both arrays are identical, so
	// nothing shows. Assigned after the callback exists, below; read through the ref here so
	// the tick always invokes the latest closure.
	const seekToVirtualTimeRef = useRef<
		((nextVirtualTimeSec: number, preservePlayback?: boolean, forceResume?: boolean) => void) | null
	>(null);
	// biome-ignore lint/correctness/useExhaustiveDependencies: re-create the rAF when the active source swaps.
	useEffect(() => {
		let raf = 0;
		const tick = () => {
			raf = window.requestAnimationFrame(tick);
			const v = videoRef.current;
			if (!v || !Number.isFinite(v.currentTime)) {
				return;
			}
			for (const audio of [primaryAudioRef.current, supplementalAudioRef.current]) {
				if (!audio) continue;
				const target = resolveAudioTrackPlayback(v.currentTime, audio.duration);
				// A paused video is not a clock to free-run against: the audio is about to be
				// paused with it, and is placed exactly where the picture stopped.
				const steer = steerAudio(
					audio.currentTime - target.targetTimeSec,
					!v.paused && !audio.paused && target.shouldPlay,
					audio.seeking,
					audioJumpedRef.current.has(audio),
					audio.playbackRate !== v.playbackRate,
				);
				// Capped where the browser stops accepting it (it throws above 16, and that
				// would end this frame): a video already at the cap has nothing left to nudge.
				const rate = Math.min(v.playbackRate * steer.rateFactor, MAX_NATIVE_PLAYBACK_RATE);
				if (audio.playbackRate !== rate) audio.playbackRate = rate;
				if (steer.seek) {
					try {
						audio.currentTime = target.targetTimeSec;
						audioJumpedRef.current.delete(audio);
					} catch {
						// media metadata not ready yet
					}
				}
				if (!v.paused && target.shouldPlay && audio.paused) {
					if (audioGraphRef.current?.context.state === "suspended") {
						void audioGraphRef.current.context.resume();
					}
					const playback = audio.play();
					if (playback) void playback.catch(() => undefined);
				} else if ((v.paused || !target.shouldPlay) && !audio.paused) {
					audio.pause();
				}
			}
			// Imported audio tracks (issue #350): project the playhead raw→output
			// once, then position each track as a contiguous block against that
			// output clock (see `resolveTimelineAudioPlayback`) so an interior trim
			// shortens the programme without cutting the track — identical to the
			// export's `mix_external_tracks`. Play it only inside its window, and set
			// its level from the track gain. When the WebAudio graph is up the level
			// rides a per-track gain node (which CAN boost past 0 dB, and the output node
			// applies the global gain on top, matching the export); the `.volume` path is
			// the fallback for when the graph is unavailable — there a boost caps at 0 dB.
			const globalGain = audioGainScalar(audioGainDbRef.current);
			// Speed-aware: under a 2x region the raw playhead races, and a projection
			// blind to speed raced the audio's target position with it — the track
			// was never given a faster `playbackRate`, but seeking it twice as fast
			// amounts to the same thing. Dividing raw time by the rate turns that
			// back into 1x wall-clock, which is what the render does too.
			const outputTimeSec = projectRawTimelineSecToPlayback(
				clipsRef.current,
				trimRangesRef.current,
				virtualTimeSecRef.current,
				speedRegionsRef.current,
			);
			// Music ducking, heard live: one reading of the voice per frame (see MUSIC_DUCK).
			const duck = musicDuckRef.current;
			const now = performance.now();
			const frameSec = Math.min(0.1, Math.max(0, (now - duck.tickAt) / 1000));
			duck.tickAt = now;
			const analyser = audioGraphRef.current?.analyser;
			if (analyser && !v.paused) {
				analyser.getFloatTimeDomainData(duck.reading);
				let energy = 0;
				for (const sample of duck.reading) energy += sample * sample;
				if (10 * Math.log10(energy / duck.reading.length) > MUSIC_DUCK.thresholdDbfs) {
					duck.voiceAt = now;
				}
			}
			duck.db = nextMusicDuckDb(duck.db, (now - duck.voiceAt) / 1000, frameSec);
			for (const fragment of audioTracksRef.current) {
				const el = audioTrackElsRef.current.get(fragment.id);
				if (!el) continue;
				// A take plays once, from its head fragment's element, as its whole pill: the
				// document keeps one fragment per clip the take covers, and letting each play its
				// own slice put a bed back on the ruler under a speed region (see
				// `takesByHeadFragment`), and a voiceover on top of itself.
				const track = takesRef.current.get(fragment.id);
				if (!track) {
					if (!el.paused) el.pause();
					continue;
				}
				const outputStartSec = projectRawTimelineSecToPlayback(
					clipsRef.current,
					trimRangesRef.current,
					track.startMs / 1000,
					speedRegionsRef.current,
				);
				// Length is measured WITHOUT speed, position WITH it. A trim REMOVES
				// timeline — a track buried in one has zero length and stays silent,
				// rather than playing its full raw length parked at the cut. A speed
				// region only COMPRESSES: the track still holds all its audio and
				// still plays at 1x, so it must not be cut short because the video
				// under it was sped up.
				const spanSec = Math.max(
					0,
					projectRawTimelineSecToPlayback(
						clipsRef.current,
						trimRangesRef.current,
						track.endMs / 1000,
					) -
						projectRawTimelineSecToPlayback(
							clipsRef.current,
							trimRangesRef.current,
							track.startMs / 1000,
						),
				);
				// A voiceover follows the cuts AND its own insertions, through one walk over
				// its pill.
				//
				// A bed plays through a cut and ends early, on purpose. A looping voiceover
				// keeps the bed's treatment — step 6 of #560 refuses that combination, and
				// inventing semantics for it would be the worse answer.
				const takePieces =
					track.kind === "voiceover" && !track.loop
						? takePiecesRef.current.get(trackGroupId(track))
						: undefined;
				const trackTarget = takePieces
					? (takePlaybackAt(takePieces, virtualTimeSecRef.current) ?? {
							targetTimeSec: track.offsetMs / 1000,
							shouldPlay: false,
						})
					: resolveTimelineAudioPlayback(outputTimeSec, outputStartSec, track, spanSec);
				// Fades measure against the SOURCE the walk consumes, never the take's ruler
				// extent: an insertion grows the extent without adding a second of file, and
				// a fade-out measured on it would start early here and nowhere else.
				const fadeSpanSec = takePieces ? consumedSourceSec(takePieces) : spanSec;
				const fadeLocalSec = takePieces
					? Math.max(0, trackTarget.targetTimeSec - track.offsetMs / 1000)
					: outputTimeSec - outputStartSec;
				const fade = timelineAudioFadeAt(track, fadeLocalSec, fadeSpanSec);
				// Imported audio plays at its natural 1× rate, NOT the video's. The export
				// sums it into the programme at 1× — speed regions stretch clip PCM only,
				// never the imported track — so following `v.playbackRate` would pitch a
				// voiceover up under a 2× region and finish it early, diverging from export.
				if (el.playbackRate !== 1) el.playbackRate = 1;
				// A voiceover is voice: levelled like the recording, its own gain trimming from
				// there — the sum `mix_external_tracks` applies. A music bed is not levelled; it
				// ducks under the voice instead.
				let trackGainDb = track.gainDb;
				if (track.kind === "voiceover") {
					const path = audioSourcesRef.current.find(
						(source) => source.id === track.assetId,
					)?.filePath;
					trackGainDb += path ? (loudnessGainDbByPathRef.current.get(path) ?? 0) : 0;
				} else {
					trackGainDb += duck.db;
				}
				const trackGainNode = audioTrackGainNodesRef.current.get(fragment.id);
				if (trackGainNode) {
					trackGainNode.gain.value = audioGainScalar(trackGainDb) * fade;
					if (el.volume !== 1) el.volume = 1;
				} else {
					el.volume = Math.min(1, audioGainScalar(trackGainDb) * globalGain * fade);
				}
				// Only re-seek on a real discontinuity (a scrub, a trim jump, a first play),
				// NOT on the sub-frame drift of normal playback: at a tight leash this
				// re-seeks most frames, and each seek briefly stalls the element — the
				// jitter. A started element already plays at the right rate from the right
				// offset, so it free-runs in sync; the wide leash just catches the jumps.
				// BGM/voiceover tolerates it; frame-tight sync is the video's job.
				if (
					shouldResyncAudio(
						el.currentTime - trackTarget.targetTimeSec,
						!el.paused && trackTarget.shouldPlay,
						IMPORTED_AUDIO_PLAYING_LEASH_SEC,
						el.seeking,
					)
				) {
					try {
						el.currentTime = trackTarget.targetTimeSec;
					} catch {
						// media metadata not ready yet
					}
				}
				if (!v.paused && trackTarget.shouldPlay && el.paused) {
					// Resume a context suspended by autoplay policy, exactly as the primary
					// loop does above — otherwise a track that starts while the primary
					// element is silent (its span is over, or a recording with no separate
					// audio element) routes into a suspended context and plays nothing.
					if (audioGraphRef.current?.context.state === "suspended") {
						void audioGraphRef.current.context.resume();
					}
					const playback = el.play();
					if (playback) void playback.catch(() => undefined);
				} else if ((v.paused || !trackTarget.shouldPlay) && !el.paused) {
					el.pause();
				}
			}
			// A reload is in flight: the decoder is dead and `currentTime` is
			// frozen (or already reset to 0), so every decision below — trim
			// skipping, the clip-boundary advance, the unmapped-position
			// fallback — would be taken on a lie, and the seeks two of them fire
			// would clobber the resume queued for the reload. Deliberately BELOW
			// the clock publish: the webcam overlay freezes on the last good
			// position rather than jumping. Note this cannot ride on `v.paused`,
			// the gate the rest of the tick uses — an `error` does not fire
			// `pause`, so a failure mid-playback leaves `paused` false.
			// Same for in-flight pending seeks or loads: the element's currentTime is
			// stale or 0 and must not trigger clip boundary or trim fallbacks.
			if (
				recoveringRef.current ||
				v.seeking ||
				pendingSeekRef.current !== null ||
				loadStateRef.current === "loading"
			) {
				return;
			}
			const activeSourceId = videoSourcesRef.current[sourceIndexRef.current]?.id;
			if (isProgrammaticSeekRef.current) {
				isProgrammaticSeekRef.current = false;
				const pos = locateSourcePosition(
					clipsRef.current,
					v.currentTime,
					activeSourceId,
					0.05,
					activeClipIdRef.current ?? undefined,
				);
				if (pos) {
					activeClipIdRef.current = pos.clip.id;
					updateVirtualTime(clampVirtualTime(clipsRef.current, pos.virtualTimeSec));
				}
				return;
			}
			// Trims only trim ahead during actual playback — scrubbing/paused seeks are
			// intentionally NOT clamped, so the user can navigate freely into a trim while
			// editing; only Play/export treats it as a cut (mirrors the pre-existing intent
			// this replaces). Jump is on the SOURCE clock only: the RAW virtual-time report
			// below (locateSourcePosition against `clipsRef.current`, unchanged) naturally
			// jumps by the trim's exact width the instant `v.currentTime` does, so the ruler's
			// playhead visually skips the trim marker instead of drifting through it.
			if (!v.paused) {
				// Resolved against the segments of the clip we are ACTUALLY playing (see
				// `locateKeptSegment`). Asking the whole segment list — all this could do
				// before a trim named its clip — let a twin clip over the same recording
				// answer "yes, that stretch is kept" for a cut authored on this one, so the
				// cut was simply not skipped during playback.
				const inKeptSegment = locateKeptSegment(
					playbackClipsRef.current,
					clipsRef.current,
					v.currentTime,
					activeSourceId,
					activeClipIdRef.current ?? undefined,
				);
				if (!inKeptSegment) {
					const nextKeptSegment = findNextKeptSegment(
						playbackClipsRef.current,
						clipsRef.current,
						virtualTimeSecRef.current,
						activeSourceId,
						v.currentTime,
						activeClipIdRef.current ?? undefined,
					);
					if (nextKeptSegment) {
						// `findRawClipForSegment` is the ONE definition of the segment-id
						// convention `resolvePlaybackSegments` emits; this used to re-implement
						// it verbatim, which is precisely the second reader that definition
						// exists to prevent.
						const rawClip = findRawClipForSegment(nextKeptSegment, clipsRef.current);
						if (rawClip) {
							activeClipIdRef.current = rawClip.id;
						}
						const rawTargetTime = getRawVirtualStartTime(nextKeptSegment, clipsRef.current);
						seekToVirtualTimeRef.current?.(rawTargetTime, true);
						return;
					}
					v.pause();
					const endPos = locateVirtualPosition(clipsRef.current, virtualDurationSecRef.current);
					if (activeClipIdRef.current === endPos?.clip.id) {
						updateVirtualTime(virtualDurationSecRef.current);
					}
					return;
				}
			}
			// ponytail: also push setSourceTimeSec every frame (was previously
			// in a separate rAF effect). Cheap; <video>.readyState >= 2 guards
			// against drawing a black frame into the cursor overlay.
			if (v.readyState >= 2) {
				// One read, three uses: `currentTime` is a live accessor into the
				// media pipeline and this block runs 60×/s.
				const sourceTime = v.currentTime;
				setSourceTimeSec(sourceTime);
				// Sampled here, where the decoder is known good, because this is
				// where a reload has to put the playhead back if it cannot
				// resolve one from the timeline.
				lastGoodSourceTimeRef.current = sourceTime;
				// The click sound, heard live. Read off the SOURCE clock — the one the cursor sprite
				// above is sampled on — because a click is recorded in the take's own seconds: this
				// clock races with the picture under a 2x region, so a hit fired where it passes a
				// click lands on the click being drawn. Which clicks exist is the export's own
				// placement, narrowed to the clip on screen, so a cut cannot sound here and go
				// missing from the file — nor the other way round when a twin clip keeps that
				// stretch. A jump wider than the seek threshold — a scrub, a clip swap — is read as
				// one and fires nothing, and while stopped the anchor is dropped, so the next run
				// does not repay a stack of old clicks.
				// The cues are the primary take's, so they only belong over that take's picture.
				if (v.paused) {
					resetClickPlayhead();
				} else {
					const crossed = takeCrossedClickHits(
						sourceTime,
						videoSourcesRef.current[sourceIndexRef.current]?.filePath,
						activeClipIdRef.current,
					);
					const clickGraph = audioGraphRef.current;
					if (crossed.length && clickGraph) {
						playClickHits(
							clickGraph.context,
							clickGraph.gain,
							clickHitBuffers(clickGraph.context),
							crossed,
						);
					}
				}
			}
			// À L'ARRÊT, le `<video>` ne pilote PLUS la position de la timeline.
			//
			// Ce tick publie `updateVirtualTime(...)` dérivé de `v.currentTime`. Pendant la
			// lecture c'est la bonne source : le média avance, la tête le suit. À l'arrêt
			// c'est l'inverse — l'utilisateur possède la tête de lecture, et le `<video>`
			// doit la SUIVRE. Sans ce garde, un scrub était écrasé à chaque frame par la
			// position d'un élément encore en train de chercher ; et près d'une frontière de
			// clips, `locateSourcePosition` ne résolvait pas, si bien que le repli
			// `seekToVirtualTimeRef(nextClip.timelineStartSec)` plus bas renvoyait la tête au
			// DÉBUT du clip voisin — le tressaillement observé au passage d'un clip à l'autre.
			//
			// `setSourceTimeSec` ci-dessus continue d'être publié : le calque curseur a besoin du
			// temps source même à l'arrêt. Seule la position de la TIMELINE cesse d'être
			// dictée par le média.
			if (v.paused) {
				return;
			}
			if (clipsRef.current.length === 0) {
				// ponytail: no clip yet (auto-create runs from
				// handleLoadedMetadata on the next tick). Push the raw
				// source time as the virtual time so the scrub thumb
				// advances and the timecode shows real progress during
				// playback. The proper timeline-aware mapping kicks in
				// when the auto-created clip arrives.
				updateVirtualTime(v.currentTime);
				return;
			}
			const position = locateSourcePosition(
				clipsRef.current,
				v.currentTime,
				activeSourceId,
				0.05,
				activeClipIdRef.current ?? undefined,
			);
			if (!position) {
				// ponytail: fall back to timeline order so cross-asset / reordered
				// clips don't keep playing unmapped media.
				const nextClip = findNextClipByTimelineOrder(clipsRef.current, virtualTimeSecRef.current);
				if (nextClip) seekToVirtualTimeRef.current?.(nextClip.timelineStartSec, true);
				else {
					v.pause();
					const endPos = locateVirtualPosition(clipsRef.current, virtualDurationSecRef.current);
					if (activeClipIdRef.current === endPos?.clip.id) {
						updateVirtualTime(virtualDurationSecRef.current);
					}
				}
				return;
			}
			activeClipIdRef.current = position.clip.id;
			const reachedClipEnd = v.currentTime >= (position.clip.sourceEndSec ?? Infinity) - 0.04;
			if (reachedClipEnd) {
				// BUG corrigé : `clipsRef.current[position.clipIndex + 1]` supposait que le
				// tableau brut (`document.timeline.clips`, jamais trié) était déjà dans l'ordre
				// temporel — s'il ne l'était pas (clip ajouté/splitté à un index qui ne reflète
				// pas son `timelineStartSec`), ce lookup retournait `undefined` même quand un
				// clip suivant existait bel et bien, ce qui déclenchait un arrêt de la lecture
				// au lieu d'enchaîner — le "ça se stoppe en fin de clip" observé. Recherche par
				// temps de timeline (comme le fallback juste au-dessus et
				// `NativeCompositorOverlay`), indépendante de l'ordre du tableau.
				const nextClip = findNextClipByTimelineOrder(
					clipsRef.current,
					position.clip.timelineStartSec,
				);
				if (!nextClip) {
					v.pause();
					const endPos = locateVirtualPosition(clipsRef.current, virtualDurationSecRef.current);
					if (activeClipIdRef.current === endPos?.clip.id) {
						updateVirtualTime(virtualDurationSecRef.current);
					}
					return;
				}
				seekToVirtualTimeRef.current?.(nextClip.timelineStartSec, true);
				return;
			}
			updateVirtualTime(clampVirtualTime(clipsRef.current, position.virtualTimeSec));
		};
		raf = window.requestAnimationFrame(tick);
		return () => window.cancelAnimationFrame(raf);
		// re-create the rAF when the active source swaps (by asset id, not src —
		// two clips can point at distinct assets that resolve to the same URL).
	}, [activeSource?.id]);

	// report the video element up; re-notify (and clear) whenever the active
	// source changes so the parent doesn't keep a stale node after the keyed
	// <video> is swapped for a new asset.
	const activeSourceKey = activeSource?.id ?? null;
	// biome-ignore lint/correctness/useExhaustiveDependencies: re-run on source swap
	useEffect(() => {
		onVideoElement?.(videoRef.current);
		return () => onVideoElement?.(null);
	}, [onVideoElement, activeSourceKey]);

	const updateVirtualTime = useCallback(
		(nextTimeSec: number) => {
			setVirtualTimeSec(nextTimeSec);
			onTimeChange?.(nextTimeSec);
			// ponytail: mirrors main's per-frame `video.playbackRate = ...`
			// (videoEventHandlers.ts) — the browser does the actual time
			// warping, so this is the only thing speed regions need. No
			// virtual-timeline remap: a sped-up region still occupies its
			// original span on the ruler, it's just played through faster.
			const v = videoRef.current;
			if (v) {
				const activeRegion = findActiveSpeedRegion(
					speedRegionsRef.current,
					Math.round(nextTimeSec * 1000),
				);
				// Clamp to the browser's 16× playbackRate ceiling; >16× is rendered at
				// its true speed only on the offline export path, not the live preview.
				const rate = Math.min(activeRegion?.speed ?? 1, MAX_NATIVE_PLAYBACK_RATE);
				if (v.playbackRate !== rate) {
					v.playbackRate = rate;
					// The recording's audio rides this clock, so it takes the new rate in the same
					// breath. Left to the next tick it plays one whole frame gap at the old one,
					// 150 ms under load: the audio that far behind entering a 2x region, and
					// that far ahead leaving it.
					for (const audio of [primaryAudioRef.current, supplementalAudioRef.current]) {
						if (audio) audio.playbackRate = rate;
					}
				}
			}
		},
		[onTimeChange],
	);

	// Apply the zoom-region transform directly to the DOM (bypassing React
	// render) so it stays in lockstep with the 60 Hz virtual-time updates
	// above without adding a style-prop re-render on every frame.
	useEffect(() => {
		const frame = videoFrameRef.current;
		if (!frame) return;
		// Speed regions speed the footage up, not the zoom transitions: they are timed on
		// screen time, like the compositor that draws the picture this box stands in for.
		const transform =
			zoomRegions.length === 0
				? IDENTITY_ZOOM_TRANSFORM
				: computeZoomPreviewTransform(
						zoomRegions,
						virtualTimeSec * 1000,
						undefined,
						speedRegionsRef.current,
					);
		frame.style.transform = `translate(${transform.translateXPercent}%, ${transform.translateYPercent}%) scale(${transform.scale})`;
	}, [zoomRegions, virtualTimeSec]);

	/**
	 * Write a source position onto the element with AT MOST ONE demuxer seek in
	 * flight; a target that arrives while one is running replaces the queue and
	 * is applied on `seeked`. Latest wins — an intermediate scrub position is
	 * never a destination the user asked to see.
	 *
	 * This is the root cause of #395, not a mitigation of it. Dragging the
	 * playhead makes V4Timeline publish a new time every rAF (it already
	 * coalesces pointermove to that, "to avoid IPC flooding"), the shell mints a
	 * seekTarget per publish, and this component turned each one into a
	 * `currentTime` write: ~60 demuxer seeks a second on a 1080p H.264 file that
	 * the native compositor is decoding at the same time. Chromium eventually
	 * fails one — `PIPELINE_ERROR_READ: FFmpegDemuxer: demuxer seek failed`,
	 * reproduced on a file ffmpeg decodes end to end without a single defect —
	 * and before this branch, any media error emptied the editor.
	 */
	const applySourceTime = useCallback((video: HTMLVideoElement, sourceTimeSec: number) => {
		if (!Number.isFinite(sourceTimeSec)) return;
		if (Math.abs(video.currentTime - sourceTimeSec) <= 0.01) {
			pendingScrubTargetRef.current = null;
			return;
		}
		if (video.seeking) {
			pendingScrubTargetRef.current = sourceTimeSec;
			return;
		}
		pendingScrubTargetRef.current = null;
		// Flagged at the moment of the ACTUAL write: a deferred target must not
		// have its flag consumed by a frame on which no seek happened.
		isProgrammaticSeekRef.current = true;
		video.currentTime = sourceTimeSec;
		// The audio elements keep their own position, so a scrub, a skipped cut or a clip
		// junction moves the picture out from under them. The rAF tick cannot tell that from
		// clock drift by its size (a cut can be 50 ms), so it is told: each element follows
		// once it is not seeking, whatever the drift.
		for (const audio of [primaryAudioRef.current, supplementalAudioRef.current]) {
			if (audio) audioJumpedRef.current.add(audio);
		}
	}, []);

	const seekToVirtualTime = useCallback(
		(nextVirtualTimeSec: number, preservePlayback = false, forceResume = false) => {
			const position = locateVirtualPosition(clips, nextVirtualTimeSec);
			if (!position) {
				videoRef.current?.pause();
				updateVirtualTime(0);
				return;
			}
			activeClipIdRef.current = position.clip.id;

			const targetIndex = videoSources.findIndex((vs) => vs.id === position.clip.assetId);
			const isAssetSwitch = targetIndex >= 0 && targetIndex !== sourceIndex;
			// Read the live paused state, not the captured `isPlaying` prop. The prop is the
			// parent's playback state as of the last render, and a boundary advance can fire
			// on the very frame playback starts or stops — before that state has round-tripped
			// back down. Only the DOM's own `paused` flag is guaranteed current at call time.
			// (This used to be strictly worse: the rAF invoked a closure captured when the rAF
			// was created, before playback started, so `isPlaying` was permanently stale-false
			// and the cross-asset resume never fired at all. The rAF now calls through
			// `seekToVirtualTimeRef`, so the closure itself is fresh — see its declaration.)
			//
			// `forceResume` bypasses that live check for the ONE caller where it's
			// actively wrong: the `<video>` `ended` handler. The browser sets
			// `.paused = true` synchronously before firing `ended`, so by the time
			// that handler runs and calls us, `!videoRef.current?.paused` is always
			// false — even though playback was genuinely still going and should
			// continue into the next clip. Without this, a non-trimmed clip (whose
			// file's real end coincides with its timeline window's end) would win a
			// race against the rAF tick's own boundary check: the native `ended`
			// event fires first, stops playback outright, and the multi-clip
			// timeline never advances — the "stops at clip end" bug.
			const shouldContinuePlayback = preservePlayback && (forceResume || !videoRef.current?.paused);

			if (isAssetSwitch) {
				if (!shouldContinuePlayback) {
					videoRef.current?.pause();
				}
				setSourceIndex(targetIndex);
				updateLoadState("loading");
				updateVirtualTime(position.virtualTimeSec);
				pendingSeekRef.current = {
					sourceTimeSec: position.sourceTimeSec,
					play: shouldContinuePlayback,
				};
				return;
			}

			const video = videoRef.current;
			if (!video) return;

			if (pendingSeekRef.current) {
				// A load is in flight (a reload, or a source that has just been
				// swapped in), so the seek below is a no-op — assigning
				// `currentTime` before metadata only sets the default playback
				// start position, and `onLoadedMetadata` is about to apply the
				// queued resume over the top of it. Re-aim that resume instead:
				// it is older intent than the gesture the user just made.
				pendingSeekRef.current = {
					sourceTimeSec: position.sourceTimeSec,
					play: shouldContinuePlayback,
				};
			}
			updateVirtualTime(position.virtualTimeSec);
			applySourceTime(video, position.sourceTimeSec);
			if (shouldContinuePlayback) {
				// A rejection here means playback never actually started, so the browser
				// never fired 'play' — nothing to reconcile, just avoid an unhandled
				// rejection warning.
				void video.play()?.catch(() => {
					// swallow: rejection just means playback never started
				});
			}
		},
		[applySourceTime, clips, videoSources, sourceIndex, updateLoadState, updateVirtualTime],
	);

	const seekToSourceTime = useCallback(
		(sourceTimeSec: number) => {
			const video = videoRef.current;
			if (!video) return;
			// A load is in flight, so this write would be a no-op that
			// `onLoadedMetadata` then overwrites — re-aim the queued resume instead.
			if (pendingSeekRef.current) {
				pendingSeekRef.current = { sourceTimeSec, play: pendingSeekRef.current.play };
				return;
			}
			applySourceTime(video, sourceTimeSec);
		},
		[applySourceTime],
	);

	/**
	 * Re-run the media load algorithm on the mounted element after a delay, and
	 * queue the position to come back to. Everything is read through refs, so the
	 * callback is stable and the scheduled work always sees current state.
	 */
	const reloadActiveSource = useCallback(
		(play: boolean, delayMs: number) => {
			if (retryTimerRef.current !== null) {
				window.clearTimeout(retryTimerRef.current);
				retryTimerRef.current = null;
			}
			recoveringRef.current = true;
			updateLoadState("loading");
			retryTimerRef.current = window.setTimeout(() => {
				retryTimerRef.current = null;
				const video = videoRef.current;
				if (!video) return;
				// Resolved HERE rather than when the error fired: the user can scrub
				// during the backoff, and the position they left the playhead on is
				// the one that has to come back. An asset switch queued in the
				// meantime is newer intent still, so it wins outright.
				if (!pendingSeekRef.current) {
					const position = locateVirtualPosition(clipsRef.current, virtualTimeSecRef.current);
					// `locateVirtualPosition` answers for whatever clip the playhead
					// is on, which after a boundary advance can belong to a DIFFERENT
					// asset — its source time would be a meaningless offset into the
					// file we are about to reload. The mounted source is read from the
					// same two mirrors the rAF tick uses, rather than kept in a third.
					const clipIsOnThisSource =
						position?.clip.assetId === videoSourcesRef.current[sourceIndexRef.current]?.id;
					if (position && clipIsOnThisSource) {
						// The rAF resumes against this; leaving it stale would resolve
						// the next tick against the clip we were on before the failure.
						activeClipIdRef.current = position.clip.id;
					}
					const resumeSec =
						position && clipIsOnThisSource ? position.sourceTimeSec : lastGoodSourceTimeRef.current;
					pendingSeekRef.current = {
						sourceTimeSec: Number.isFinite(resumeSec) ? resumeSec : 0,
						play,
					};
				}
				// The restore itself rides the cross-asset path `onLoadedMetadata`
				// already implements — one resume path in this component, not two.
				//
				// load() and nothing else: per spec it unconditionally re-runs the
				// media load algorithm. Re-assigning `src` first (the obvious
				// alternative) starts a SECOND load that aborts the first, which
				// surfaces as a spurious MEDIA_ERR_ABORTED.
				video.load();
			}, delayMs);
		},
		[updateLoadState],
	);

	/** The element is loaded again, so the reload is over and any failure the
	 *  caller is showing can go. Note what this does NOT do: re-arm the retry
	 *  budget. `loadedmetadata`/`canplay` prove the container header parsed and
	 *  the decoder is willing — not that the bytes that killed us are readable.
	 *  A truncated recording (intact header, unreadable data — the case the error
	 *  card exists for) re-fires both on every reload, so re-arming here would
	 *  hand back the budget faster than failures could spend it: a 400 ms reload
	 *  loop, forever, with nothing ever shown to the user. Getting PAST the
	 *  failure point is the only honest evidence, and the rAF tick below owns it. */
	const markSourceLoaded = useCallback(() => {
		recoveringRef.current = false;
		const id = videoSourcesRef.current[sourceIndexRef.current]?.id;
		if (id) onVideoRecovered?.(id);
	}, [onVideoRecovered]);

	// Reload bookkeeping belongs to the MOUNTED MEDIA, so it is keyed on the URL
	// as well as the asset id — the element is keyed on the id alone (see the
	// <video> below), so re-pointing an asset at a different file re-runs the
	// load algorithm on the SAME element, and a budget spent on the old file
	// must not be charged to the new one. Nothing re-points an asset today; the
	// relink this card's copy invites would be the first, and it is the exact
	// case where a fresh budget is the whole point.
	// The cleanup matters for the swap that IS reachable: a reload scheduled for
	// the old element must never fire against its replacement. React runs it
	// before any queued macrotask can.
	// biome-ignore lint/correctness/useExhaustiveDependencies: re-run when the mounted media changes
	useEffect(() => {
		reloadsRef.current = [];
		gaveUpRef.current = false;
		recoveringRef.current = false;
		return () => {
			if (retryTimerRef.current !== null) {
				window.clearTimeout(retryTimerRef.current);
				retryTimerRef.current = null;
			}
		};
	}, [activeSourceKey, activeSource?.src]);

	// The caller's Retry button. Same path as an automatic reload so the two
	// cannot drift, but with a fresh budget and no delay: the user clicked
	// because they know something changed.
	// biome-ignore lint/correctness/useExhaustiveDependencies: the token bump IS the request
	useEffect(() => {
		if (!retryToken) return;
		// Deliberately does NOT record a reload: the user's click must not spend
		// one of the recoveries it is meant to restore.
		reloadsRef.current = [];
		gaveUpRef.current = false;
		reloadActiveSource(false, 0);
	}, [retryToken]);

	// BUG corrigé : cet effet listait `seekToVirtualTime`/`seekToSourceTime` en dépendances
	// — mais `seekToVirtualTime` change d'identité (nouveau `useCallback`) à chaque fois que
	// `sourceIndex` change, y compris quand CE MÊME effet vient de le faire changer (switch
	// d'asset lors d'un enchaînement de clip). Résultat : l'effet se redéclenchait alors
	// qu'AUCUN nouveau seek n'avait été demandé, et réappliquait l'ANCIEN `seekTarget` (la
	// position du dernier scrub manuel) — rebasculant sur le clip d'origine et figeant la
	// lecture pile à cette position. D'où le "ça se fige à la fin du 1er clip, uniquement si
	// la tête de lecture avait été déplacée avant" : sans scrub préalable, `seekTarget` reste
	// `null` et l'effet est un no-op, masquant le bug. Seul `seekTarget` (son `requestId`)
	// doit déclencher un nouveau seek ; les fonctions elles-mêmes sont lues via des refs
	// tenues à jour à chaque rendu, pour ne jamais rejouer un ancien seek par accident.
	// (`seekToVirtualTimeRef` is declared above the rAF effect — see the comment there — so
	// the boundary-advance path reads the same always-fresh closure this effect does.)
	seekToVirtualTimeRef.current = seekToVirtualTime;
	const seekToSourceTimeRef = useRef(seekToSourceTime);
	seekToSourceTimeRef.current = seekToSourceTime;
	useEffect(() => {
		if (!seekTarget) return;
		if (seekTarget.isSource) {
			seekToSourceTimeRef.current(seekTarget.timeSec);
		} else {
			seekToVirtualTimeRef.current?.(
				seekTarget.timeSec,
				seekTarget.preservePlayback,
				seekTarget.preservePlayback,
			);
		}
	}, [seekTarget]);

	return (
		// The load state no longer paints anything here (Preview owns failure UI
		// now), but it is still the honest read of what the decode clock is doing —
		// worth one attribute for tests and for a screenshot in a bug report.
		<div className={styles.container} data-load-state={loadState}>
			{activeSource ? (
				<>
					<div ref={videoFrameRef} className={styles.videoFrame}>
						<video
							// Key on the asset id, not the URL: distinct assets that resolve
							// to the same file URL must still remount the <video> on switch so
							// onLoadedMetadata refires and the pending cross-asset seek/resume
							// runs (otherwise playback stalls at the clip boundary).
							key={activeSource.id}
							ref={videoRef}
							src={activeSource.src}
							className={`${styles.video}${isIdentityCrop ? "" : ` ${styles.videoCropped}`}`}
							// When a synthetic cursor is being drawn on top (CursorPreviewLayer),
							// hide the real OS pointer here so it doesn't compete with it.
							style={{
								...cropVideoStyle,
								...videoStyle,
								cursor: settings.cursorShow ? "none" : undefined,
							}}
							preload="metadata"
							muted
							playsInline
							onLoadedMetadata={(e) => {
								updateLoadState("ready");
								markSourceLoaded();
								// ponytail: forward the raw duration (possibly NaN for
								// MediaRecorder WebMs) to the parent. handleLoadedMetadata
								// falls back to a 60s seed when it isn't finite so the
								// timeline gets a populated clip even before the EBML fix
								// lands. Previously this gate skipped the callback for
								// non-finite durations and stranded the editor on
								// "No clips yet" until manual intervention. The assetId is
								// forwarded so the parent only ever corrects clips that
								// belong to the asset which actually fired this event —
								// without it, switching between clips of different assets
								// during multi-clip playback clobbered clip[0]'s duration
								// with whichever asset's video happened to load last.
								onLoadedMetadata?.(
									e.currentTarget.duration,
									activeSource.id,
									e.currentTarget.videoWidth,
									e.currentTarget.videoHeight,
								);
								// Its size is read: from here on only its clock is needed.
								dropVideoTrack(e.currentTarget);
								if (pendingSeekRef.current) {
									const { sourceTimeSec, play } = pendingSeekRef.current;
									pendingSeekRef.current = null;
									e.currentTarget.currentTime = sourceTimeSec;
									if (play) {
										// See the other video.play() catch above: a rejection means
										// playback never started, so there's no state to reconcile.
										void e.currentTarget.play().catch(() => {
											// swallow: rejection just means playback never started
										});
									}
								} else if (clips.length > 0) {
									seekToVirtualTime(virtualTimeSec);
								}
							}}
							onSeeked={(e) => {
								isProgrammaticSeekRef.current = false;
								// The demuxer is free again: apply the newest target that
								// arrived while it was busy, if the playhead has moved on.
								const queued = pendingScrubTargetRef.current;
								if (queued !== null) {
									pendingScrubTargetRef.current = null;
									applySourceTime(e.currentTarget, queued);
								}
							}}
							onWaiting={() => updateLoadState("loading")}
							onCanPlay={() => {
								updateLoadState("ready");
								markSourceLoaded();
							}}
							onError={(e) => {
								const el = e.currentTarget;
								const description = describeMediaError(el.error);
								// An element whose source was torn out from under it reports a
								// "load failure" that says nothing about the media (Chromium
								// calls it "Empty src attribute"). Never act on that.
								const hasSource = Boolean(el.getAttribute("src")) || Boolean(el.currentSrc);
								const nowMs = Date.now();
								reloadsRef.current = pruneReloads(reloadsRef.current, nowMs);
								const reloadsInWindow = reloadsRef.current.length;
								const disposition = hasSource
									? mediaErrorDisposition(description.code, reloadsInWindow, gaveUpRef.current)
									: "ignore";
								const detail = formatMediaError(description);
								// The code is the whole diagnosis, and it used to be thrown
								// away — which is why issue #395 could only ever be reported
								// as "the preview disappeared". Keep it, whatever we decide.
								const context = {
									assetId: activeSource.id,
									src: activeSource.src,
									detail,
									networkState: el.networkState,
									readyState: el.readyState,
									currentTime: el.currentTime,
									reloadsInWindow,
									gaveUp: gaveUpRef.current,
									disposition,
								};
								if (disposition === "ignore") {
									// Routine: every cross-asset clip boundary remounts this
									// element mid-load. `debug`, not `warn` — this fires during
									// ordinary playback and must not read as a problem.
									console.debug(
										"[preview] ignoring a <video> error from a cancelled load",
										context,
									);
									return;
								}
								if (disposition === "retry") {
									console.warn("[preview] <video> failed, reloading", context);
									reloadsRef.current.push(nowMs);
									// Deliberately no pause(): a 400 ms reload should be a blip
									// the user never sees, and pausing here would flip the
									// shell's transport for it. What keeps the rAF from
									// steering the dead decoder in the meantime is
									// `recoveringRef`, set by reloadActiveSource.
									reloadActiveSource(!el.paused, retryDelayMs(reloadsInWindow));
									return;
								}
								// ponytail: don't blindly advance to the next source — if
								// the failed source owns the current virtual clip, the
								// next sourceIndex will seekToVirtualTime right back into
								// the same failed asset, looping. Fail the preview.
								console.error("[preview] <video> failed for good", context);
								pendingSeekRef.current = null;
								recoveringRef.current = false;
								// Latched so an expiring window cannot restart the cycle behind
								// the card. Only Retry or a media change lifts it.
								gaveUpRef.current = true;
								updateLoadState("error");
								// An 'error' doesn't itself fire 'pause', so make sure the shell's
								// transport state (single source of truth, see NewEditorShell's
								// own play/pause/ended listener) actually learns playback stopped.
								el.pause();
								onVideoError?.(activeSource.id, detail);
							}}
							onPlay={() => {
								// The edited timeline can end before the underlying file. A
								// plain play() would hit that same boundary and pause again.
								// Resolve the rewind here so cross-asset restarts also carry
								// playback intent through the pending metadata load.
								const duration = virtualDurationSecRef.current;
								const vTime = virtualTimeSecRef.current;
								const endPos = locateVirtualPosition(clipsRef.current, duration);
								const currentPos = locateVirtualPosition(clipsRef.current, vTime);
								const hasNextClip = clipsRef.current.some((c) => c.timelineStartSec > vTime + 0.1);
								if (
									duration > 0 &&
									vTime >= duration - 0.05 &&
									!hasNextClip &&
									currentPos?.clip.id === endPos?.clip.id
								) {
									seekToVirtualTimeRef.current?.(0, true, true);
								}
							}}
							onEnded={(e) => {
								if (!e.currentTarget.paused || pendingSeekRef.current !== null) {
									return;
								}
								// BUG corrigé : ce handler stoppait TOUJOURS la lecture dès que le
								// <video> brut atteignait SA PROPRE fin de fichier — une course
								// avec la boucle rAF (reachedClipEnd, plus haut) qui gère
								// l'enchaînement multi-clip. Pour un clip NON trimé, la fin réelle
								// du fichier coïncide avec la fin de sa fenêtre timeline, et
								// l'événement navigateur 'ended' gagnait quasi systématiquement
								// cette course (déclenché par le navigateur dès la dernière frame,
								// avant le prochain tick rAF) : la lecture s'arrêtait au lieu
								// d'enchaîner sur le clip suivant — le "ça s'arrête en fin de clip"
								// qui persistait malgré les fixes de la boucle rAF elle-même.
								// `forceResume` (voir seekToVirtualTime) est nécessaire ici : le
								// navigateur a déjà mis `.paused = true` avant de déclencher
								// 'ended', donc le check `!video.paused` habituel empêcherait
								// toujours la reprise de la lecture sur le clip suivant. Si aucun
								// clip suivant n'existe, on publie la fin de timeline : le navigateur
								// a déjà mis la vidéo en pause, et NewEditorShell (seule source de
								// vérité pour l'état de lecture) l'apprend via son propre listener
								// 'ended'/'pause' sur ce même élément.
								const current = clipsRef.current.find(
									(clip) => clip.id === activeClipIdRef.current,
								);
								const nextClip = current
									? findNextClipByTimelineOrder(clipsRef.current, current.timelineStartSec)
									: undefined;
								if (nextClip) {
									seekToVirtualTime(nextClip.timelineStartSec, true, true);
								} else {
									const endPos = locateVirtualPosition(
										clipsRef.current,
										virtualDurationSecRef.current,
									);
									if (current && current.id === endPos?.clip.id) {
										updateVirtualTime(virtualDurationSecRef.current);
									}
								}
							}}
							// ponytail: handleTimeUpdate is now driven by the rAF loop
							// above (60 Hz) instead of the <video> onTimeUpdate event
							// (~4 Hz) — the 4 Hz sync was too slow to keep the webcam
							// <video> and any audio in sync. The rAF tick also
							// handles clip-end advancement, so dropping the event
							// handler here is safe.
						/>
						<audio
							key={`${activeSource.id}:primary-audio`}
							ref={setPrimaryAudioElement}
							src={activeSource.src}
							preload="metadata"
							aria-hidden="true"
							data-testid="preview-audio-primary"
							// The recording's own mp4: without this its picture is decoded too.
							onLoadedMetadata={(e) => dropVideoTrack(e.currentTarget)}
						/>
						{supplementalAudioSrc ? (
							<audio
								key={`${activeSource.id}:supplemental-audio`}
								ref={setSupplementalAudioElement}
								src={supplementalAudioSrc}
								preload="metadata"
								aria-hidden="true"
								onLoadedMetadata={(e) => dropVideoTrack(e.currentTarget)}
								data-testid="preview-audio-supplemental"
							/>
						) : null}
						{/* Imported audio tracks (issue #350). One element per track, kept in
						    sync by the rAF loop above via audioTrackElsRef. A track whose asset
						    URL isn't resolved yet is skipped rather than mounted src-less. */}
						{audioTracks.map((track) => {
							const src = audioSources.find((s) => s.id === track.assetId)?.src;
							if (!src) return null;
							return (
								<audio
									key={`audio-track:${track.id}`}
									ref={(element) => registerAudioTrackEl(track.id, element)}
									src={src}
									preload="metadata"
									aria-hidden="true"
									data-testid={`preview-audio-track-${track.id}`}
								/>
							);
						})}
						{/* Plus d'overlay ici du tout. « Loading preview… » reflétait l'état du
						    <video> CACHÉ (source horloge/audio), pas la preview RÉELLE — le canvas
						    natif, qui montre déjà une image valide pendant que le <video> re-seek.
						    L'overlay d'erreur, lui, est parti chez Preview (#395) : il vivait dans
						    .videoFrame, sur lequel l'effet de zoom écrit `style.transform`, donc à
						    3× il partait hors cadre ; il n'était pas traduit ; et surtout il ne
						    proposait rien — l'échec est désormais une carte avec un bouton
						    Réessayer, rendue au-dessus de la dernière image composée. */}
					</div>
					{/* The native D3D canvas already draws the recorded-cursor sprite as part
					    of the composited frame (same cursor sidecar file, single source of
					    truth) — this CPU-rendered duplicate (CursorPreviewLayer) is removed. */}
				</>
			) : (
				<div className={styles.placeholder}>Attach a video to start previewing.</div>
			)}
		</div>
	);
}