From 5e946bbe3aa7fe9e8b38b716cef55109bb36e763 Mon Sep 17 00:00:00 2001
From: baiqing <lbx12309@icloud.com>
Date: Wed, 24 Jun 2026 14:08:45 +0800
Subject: [PATCH] fix(preview): hold the played frame on pause until the exact
 stop-frame composite lands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After timeline playback stops (user pause OR end-of-timeline) the preview
sometimes jumped to an EARLIER frame than the real pause position, then snapped
forward. Root cause is the two-surface switch: on pause the composite <img>
became visible immediately, but useTimelineFrame held the PRE-PLAYBACK composite
(it was disabled during playback and intentionally never clears its dataUrl), and
the true stop frame was only requested ~140ms later (the scrub debounce timer was
reset on every rAF activeFrame write) plus an async ffmpeg/wgpu/PNG round-trip —
so the stale frame showed first, then the correct one. Intermittent because it is
a timing race; sometimes the held frame was already close enough.

Upstream (VideoEngine.swift / PreviewView.swift) has ONE surface: a single
AVPlayerLayer parked on the player's current CMTime, so pause() just freezes the
current frame — the displayed frame always equals the player position, never an
earlier one. The WebView can't run that, so faithfulness means the play→pause
SWITCH between our two surfaces must be frame-consistent.

Fix (minimal, no self-invented opacity/debounce hacks):
- Split the debounce by intent: targetFrame (immediate, rounded/clamped stop
  frame) vs scrubFrame (debounced 140ms, paused scrubbing only). On the
  play→pause settle, request targetFrame at once — no 140ms delay.
- useTimelineFrame now returns { dataUrl, readyFrame }; readyFrame is the frame
  the current dataUrl was composited for, so Preview can gate the surface swap on
  "composite == exact stop frame".
- Hold the already-paused <video>'s last decoded frame visible (its frame IS the
  true stop frame) through a short "settle" window; only swap to the composite
  <img> once readyFrame === targetFrame. A bounded 800ms ceiling falls back to the
  <img> path if the composite never resolves (e.g. outside Tauri).
- TimelinePlaybackLayer gains a holdVisible prop driving PAINT only; the clock
  still releases and elements still pause on !playing, so no motion/audio resumes.

No pause-black (a correct frame is always painted), no backward flash (swap only
on exact-frame match), no composite storm (debounce retained for scrubbing). The
full faithful endpoint remains the single-surface streaming engine (#53).
---
 web/src/components/preview/Preview.tsx        | 53 ++++++++++++++++---
 .../preview/TimelinePlaybackLayer.tsx         | 26 +++++++--
 .../components/preview/useTimelineFrame.ts    | 25 +++++++--
 3 files changed, 90 insertions(+), 14 deletions(-)

diff --git a/web/src/components/preview/Preview.tsx b/web/src/components/preview/Preview.tsx
index bf83a80..97db0b1 100644
--- a/web/src/components/preview/Preview.tsx
+++ b/web/src/components/preview/Preview.tsx
@@ -93,16 +93,50 @@ export function Preview() {
   // The playhead still moves instantly; the composite is fetched only once the
   // playhead has settled for ~140ms (i.e. you stop scrubbing). See the perf
   // issue for the proper fix (a streaming playback/scrub engine).
-  const composeFrame = useDebounced(
-    Math.min(Math.round(activeFrame), Math.max(0, timelineTotal - 1)),
-    140,
-  );
-  const timelineFrameUrl = useTimelineFrame(
+  //
+  // The frame the composite should show: rounded, clamped playhead. Computed once
+  // and shared by the request AND the readiness gate so `readyFrame === targetFrame`
+  // can actually match.
+  const targetFrame = Math.min(Math.round(activeFrame), Math.max(0, timelineTotal - 1));
+  // Debounce ONLY for paused scrubbing. The play→pause settle bypasses it below.
+  const scrubFrame = useDebounced(targetFrame, 140);
+
+  // Settle window: spans the play→pause edge until the composite for the EXACT
+  // stop frame is ready. During it we keep the played <video> frame painted (the
+  // browser holds a paused element's last decoded frame = the true stop frame) and
+  // request that frame immediately (no 140ms debounce), so the preview never
+  // flashes the earlier/stale pre-playback composite before snapping to the real
+  // pause frame — the WebView analog of upstream's single AVPlayerLayer staying
+  // parked on the player's current CMTime when paused.
+  const [settling, setSettling] = useState(false);
+  const prevPlaying = useRef(isPlaying);
+  if (prevPlaying.current !== isPlaying) {
+    // Set-state-during-render to adjust on the isPlaying edge with no wasted commit
+    // (React re-renders before painting): entering pause → settle; (re)play → end.
+    prevPlaying.current = isPlaying;
+    setSettling(!isPlaying);
+  }
+
+  const composeFrame = settling ? targetFrame : scrubFrame;
+  const { dataUrl: timelineFrameUrl, readyFrame } = useTimelineFrame(
     composeFrame,
     !previewing && timeline.tracks.length > 0 && !isPlaying,
     timeline,
     0,
   );
+
+  // End the settle once the composite has caught up to the exact stop frame, OR
+  // after a short ceiling so a failed/never-resolving composite (e.g. outside
+  // Tauri) can't pin the held video frame forever — fall back to the <img> path.
+  useEffect(() => {
+    if (!settling) return;
+    if (!isPlaying && timelineFrameUrl !== null && readyFrame === targetFrame) {
+      setSettling(false);
+      return;
+    }
+    const id = window.setTimeout(() => setSettling(false), 800);
+    return () => window.clearTimeout(id);
+  }, [settling, isPlaying, timelineFrameUrl, readyFrame, targetFrame]);
   const fps = timeline.fps;
   const total = previewing
     ? Math.max(0, Math.round(mediaDuration * fps))
@@ -162,7 +196,12 @@ export function Preview() {
              it stays mounted even when paused so audio/video elements
              survive the pause→play transition (upstream VideoEngine model). */}
         {!previewItem && timelineHasContent && (
-          <TimelinePlayback timeline={timeline} fps={fps} playing={isPlaying} />
+          <TimelinePlayback
+            timeline={timeline}
+            fps={fps}
+            playing={isPlaying}
+            holdVisible={isPlaying || settling}
+          />
         )}
         {previewItem ? (
           <MediaPreview
@@ -172,7 +211,7 @@ export function Preview() {
             onDuration={setMediaDuration}
             onPlayingChange={setMediaPlaying}
           />
-        ) : isPlaying ? null : timelineFrameUrl ? (
+        ) : isPlaying || settling ? null : timelineFrameUrl ? (
           // Rust GPU composite of the timeline at the current playhead (#47).
           <img
             src={timelineFrameUrl}
diff --git a/web/src/components/preview/TimelinePlaybackLayer.tsx b/web/src/components/preview/TimelinePlaybackLayer.tsx
index bcf9d86..3a17e00 100644
--- a/web/src/components/preview/TimelinePlaybackLayer.tsx
+++ b/web/src/components/preview/TimelinePlaybackLayer.tsx
@@ -44,7 +44,27 @@ const SEEK_EPSILON_FRAMES = 2;
  *  yet (just mounted/seeked); advance by dt and nudge it rather than snapping. */
 const MASTER_ALIGN_FRAMES = 15;
 
-export function TimelinePlayback({ timeline, fps, playing }: { timeline: Timeline; fps: number; playing: boolean }) {
+/**
+ * `playing` drives the clock/effect (claim, advance the playhead, pause elements
+ * on stop). `holdVisible` drives only PAINT: it stays true through the brief
+ * play→pause "settle" so the already-paused <video> keeps showing its last
+ * decoded frame — the true stop frame — until the composite <img> for that exact
+ * frame is ready (Preview swaps then). This is the WebView analog of upstream's
+ * single AVPlayerLayer staying parked on the player's CMTime: no backward flash
+ * to an earlier composite, no black. The element is still paused (no motion/audio)
+ * whenever `playing` is false; `holdVisible` only keeps the frozen frame painted.
+ */
+export function TimelinePlayback({
+  timeline,
+  fps,
+  playing,
+  holdVisible,
+}: {
+  timeline: Timeline;
+  fps: number;
+  playing: boolean;
+  holdVisible: boolean;
+}) {
   // Subscribe to activeFrame so the right clips stay mounted as the playhead moves.
   const activeFrame = useEditorUiStore((s) => s.activeFrame);
   const items = useMediaStore((s) => s.items);
@@ -255,7 +275,7 @@ export function TimelinePlayback({ timeline, fps, playing }: { timeline: Timelin
           playsInline
           preload="auto"
           onLoadedData={seekOnLoad(visual.clip)}
-          style={{ ...fill, opacity: playing ? clipOpacity(visual.clip) : 0 }}
+          style={{ ...fill, opacity: holdVisible ? clipOpacity(visual.clip) : 0 }}
         />
       )}
       {visual && visualUrl && visual.clip.mediaType === "image" && (
@@ -264,7 +284,7 @@ export function TimelinePlayback({ timeline, fps, playing }: { timeline: Timelin
           src={visualUrl}
           alt=""
           draggable={false}
-          style={{ ...fill, opacity: playing ? clipOpacity(visual.clip) : 0 }}
+          style={{ ...fill, opacity: holdVisible ? clipOpacity(visual.clip) : 0 }}
         />
       )}
       {audios.map((a) => {
diff --git a/web/src/components/preview/useTimelineFrame.ts b/web/src/components/preview/useTimelineFrame.ts
index c000fa9..96bec28 100644
--- a/web/src/components/preview/useTimelineFrame.ts
+++ b/web/src/components/preview/useTimelineFrame.ts
@@ -12,19 +12,33 @@
  *
  * `enabled` gates fetching (Timeline tab active, not single-media preview).
  * `refreshKey` forces a refetch when the document changes (pass the timeline
- * snapshot). Returns null outside Tauri and before the first frame resolves.
+ * snapshot). Returns `{ dataUrl, readyFrame }`; both are null outside Tauri and
+ * before the first frame resolves. `readyFrame` is the frame the current
+ * `dataUrl` was composited for, so callers can tell when the composite has
+ * caught up to the frame they actually want.
  */
 
 import { useEffect, useRef, useState } from "react";
 import { compositeFrame, isTauri } from "../../lib/api";
 
+export interface TimelineFrameResult {
+  /** Composited PNG data URL for `readyFrame`, or null before the first resolves. */
+  dataUrl: string | null;
+  /** The `frame` argument that produced the current `dataUrl`. Lets callers gate
+   *  a surface swap on "the composite now equals the exact frame I want" (used by
+   *  Preview to hold the played video frame until the stop-frame composite lands,
+   *  instead of flashing a stale earlier frame). */
+  readyFrame: number | null;
+}
+
 export function useTimelineFrame(
   frame: number,
   enabled: boolean,
   refreshKey: unknown,
   minIntervalMs = 0,
-): string | null {
+): TimelineFrameResult {
   const [dataUrl, setDataUrl] = useState<string | null>(null);
+  const [readyFrame, setReadyFrame] = useState<number | null>(null);
   const inFlight = useRef(false);
   const pending = useRef<number | null>(null);
   const lastStart = useRef(0);
@@ -44,7 +58,10 @@ export function useTimelineFrame(
     lastStart.current = performance.now();
     void compositeFrame(f)
       .then((res) => {
-        if (res && enabledRef.current) setDataUrl(res.dataUrl);
+        if (res && enabledRef.current) {
+          setDataUrl(res.dataUrl);
+          setReadyFrame(f);
+        }
       })
       .catch(() => {
         // A failed composite leaves the last good frame.
@@ -99,5 +116,5 @@ export function useTimelineFrame(
     [],
   );
 
-  return dataUrl;
+  return { dataUrl, readyFrame };
 }