fix(player): hold the last frame through a software-path seek (#90)

SoftwarePlaybackHost.seek() flushed the renderer, and
SampleBufferRenderer.flush() unconditionally removed the displayed image
(modern: flush(removingDisplayedImage: true); legacy: flushAndRemoveImage()),
so the visible frame was cleared before the post-seek keyframe decoded, a
black flash on slow sources like MPEG-2. The native/AVPlayer path holds the
frame through a seek.

flush() now takes a removingDisplayedImage flag (default true for
stop/teardown); seek() passes false so the previous frame stays on screen
until the post-seek frame is enqueued. DisplayFlushOp is the pure decision
(modern rendererFlush vs legacy flushAndRemoveImage vs legacy hold) split out
so the contract is unit-testable without a live AVSampleBufferDisplayLayer; 4
tests cover the full truth table.

Confirmed on-device by the reporter: MPEG-2 episodes no longer flash black on
seek.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: superuser404notfound

Sources/AetherEngine/Native/SoftwarePlaybackHost.swift

@@ -436,7 +436,10 @@ final class SoftwarePlaybackHost {
 
         videoDecoder.flush()
         audioDecoder?.flush()
-        renderer.flush()
+        // Hold the last frame through the seek (don't blank the display) so the viewer sees the previous
+        // frame until the post-seek frame decodes, instead of a black flash (issue #90). Stop/teardown and
+        // background-return still clear via the default.
+        renderer.flush(removingDisplayedImage: false)
         audioOutput?.flush()
 
         // Live source is forward-only; DVR rewind reseeds decoders from the ring without touching the live demuxer's read position.

Sources/AetherEngine/Renderer/SampleBufferRenderer.swift

@@ -8,6 +8,25 @@ import CoreVideo
 /// Includes a small reorder buffer (4 frames) to handle B-frame decode
 /// order from VTDecompressionSession. Frames are sorted by PTS before
 /// being enqueued to the display layer in strict presentation order.
+/// Which display-layer flush operation a flush request maps to. Split out of SampleBufferRenderer.flush()
+/// as a pure value so the seek-holds-frame contract (issue #90) is testable without a live
+/// AVSampleBufferDisplayLayer.
+enum DisplayFlushOp: Equatable {
+    /// tvOS 18+/iOS 18+/macOS 15+: AVSampleBufferVideoRenderer.flush(removingDisplayedImage:).
+    case rendererFlush(removingDisplayedImage: Bool)
+    /// Legacy AVSampleBufferDisplayLayer.flushAndRemoveImage() — clears the visible frame.
+    case removeImage
+    /// Legacy AVSampleBufferDisplayLayer.flush() — keeps the last frame on screen (hold through seek).
+    case holdImage
+
+    static func resolve(removingDisplayedImage: Bool, modernRenderer: Bool) -> DisplayFlushOp {
+        if modernRenderer {
+            return .rendererFlush(removingDisplayedImage: removingDisplayedImage)
+        }
+        return removingDisplayedImage ? .removeImage : .holdImage
+    }
+}
+
 final class SampleBufferRenderer: @unchecked Sendable {
 
     private(set) var displayLayer: AVSampleBufferDisplayLayer
@@ -135,19 +154,28 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.unlock()
     }
 
-    /// Discard all buffered and displayed frames (seek/stop). Clears the currently visible frame immediately.
-    func flush() {
+    /// Discard all buffered frames. `removingDisplayedImage: true` (stop/teardown) also clears the visible
+    /// frame; `false` (seek) holds the last frame on screen until the post-seek frame is enqueued, so a seek
+    /// doesn't flash black between the old and new positions (matches the hardware path's hold-last-frame).
+    func flush(removingDisplayedImage: Bool = true) {
         reorderLock.lock()
         reorderBuffer.removeAll()
         // Invalidate the format description cache; the next load() may open a stream with different colorimetry at the same resolution.
         cachedFormatDesc = nil
         cachedFormatKey = nil
         reorderLock.unlock()
 
-        if #available(tvOS 18.0, iOS 18.0, macOS 15.0, *) {
-            displayLayer.sampleBufferRenderer.flush(removingDisplayedImage: true) { }
-        } else {
+        let modern: Bool
+        if #available(tvOS 18.0, iOS 18.0, macOS 15.0, *) { modern = true } else { modern = false }
+        switch DisplayFlushOp.resolve(removingDisplayedImage: removingDisplayedImage, modernRenderer: modern) {
+        case .rendererFlush(let remove):
+            if #available(tvOS 18.0, iOS 18.0, macOS 15.0, *) {
+                displayLayer.sampleBufferRenderer.flush(removingDisplayedImage: remove) { }
+            }
+        case .removeImage:
             displayLayer.flushAndRemoveImage()
+        case .holdImage:
+            displayLayer.flush()
         }
     }
 

Tests/AetherEngineTests/DisplayFlushOpTests.swift

@@ -0,0 +1,39 @@
+import XCTest
+@testable import AetherEngine
+
+/// Issue #90: the software-decode path blanked the display on every seek. SoftwarePlaybackHost.seek()
+/// flushed the renderer, and SampleBufferRenderer.flush() unconditionally removed the displayed image
+/// (modern: flush(removingDisplayedImage: true); legacy: flushAndRemoveImage()), so the visible frame
+/// was cleared before the post-seek keyframe decoded, a black flash on slow sources (MPEG-2). The
+/// hardware/AVPlayer path holds the last frame through a seek. DisplayFlushOp is the pure decision split
+/// out of flush() so the hold-vs-clear contract is unit-testable without a live AVSampleBufferDisplayLayer.
+final class DisplayFlushOpTests: XCTestCase {
+
+    // MARK: - Seek holds the last frame (the fix)
+
+    func testSeekOnModernRendererHoldsDisplayedImage() {
+        let op = DisplayFlushOp.resolve(removingDisplayedImage: false, modernRenderer: true)
+        XCTAssertEqual(op, .rendererFlush(removingDisplayedImage: false),
+            "a seek must forward removingDisplayedImage: false so the last frame stays on screen")
+    }
+
+    func testSeekOnLegacyRendererHoldsLastFrame() {
+        let op = DisplayFlushOp.resolve(removingDisplayedImage: false, modernRenderer: false)
+        XCTAssertEqual(op, .holdImage,
+            "the legacy path is the regression: a seek must call flush() (hold), not flushAndRemoveImage()")
+    }
+
+    // MARK: - Stop / teardown still clears the visible frame (unchanged default)
+
+    func testStopOnModernRendererRemovesDisplayedImage() {
+        let op = DisplayFlushOp.resolve(removingDisplayedImage: true, modernRenderer: true)
+        XCTAssertEqual(op, .rendererFlush(removingDisplayedImage: true),
+            "stop/teardown must forward removingDisplayedImage: true")
+    }
+
+    func testStopOnLegacyRendererRemovesImage() {
+        let op = DisplayFlushOp.resolve(removingDisplayedImage: true, modernRenderer: false)
+        XCTAssertEqual(op, .removeImage,
+            "stop/teardown on the legacy path must call flushAndRemoveImage()")
+    }
+}

docs/architecture.md

@@ -38,6 +38,8 @@ Source URL ──► Demuxer ──┬─► SoftwareVideoDecoder (dav1d) ──
                                               AVR / speakers
 ```
 
+A seek holds the last frame on screen rather than blanking it. `SampleBufferRenderer.flush()` takes a `removingDisplayedImage` flag (`DisplayFlushOp` is the pure decision split out for testing): stop/teardown clears the visible frame (the default), but `SoftwarePlaybackHost.seek()` passes `false`, so the previous frame stays up until the post-seek keyframe decodes instead of flashing black on slow sources like MPEG-2. This matches the native/AVPlayer path, which holds the frame through a seek (#90).
+
 `AudioDecoder` stamps each `CMSampleBuffer` from a running sample count anchored to the first frame (`AudioClockAnchor`), not from the container-quantized per-packet PTS. Container timebases are coarse (1 ms in MKV), so when a frame's duration is not an integer number of ticks (a 1536-sample AC-3 frame is 34.83 ms at 44.1 kHz but exactly 32 ms at 48 kHz) the quantized PTS leave a sub-millisecond gap or overlap at every buffer boundary, and `AVSampleBufferAudioRenderer` reconciles a discontinuity at each one (~29 clicks/sec, a continuous crackle). Anchoring to the sample clock makes consecutive buffers abut exactly; a real source discontinuity (> 100 ms off the predicted clock, i.e. a seek or edit) re-anchors so genuine gaps are not papered over, and `flush()` drops the anchor. The clock advances only on a successfully emitted buffer, so a dropped buffer injects no phantom samples.
 
 AV1+DV (Profile 10.0 / 10.1 / 10.4) routes through the native path on hardware-AV1 hosts via the `dav1` / `av01` track type plus the source's `dvvC` box. AV1+Atmos is genuinely rare in the wild (mastering still runs in HEVC overwhelmingly), so the SW pipeline's lack of Atmos passthrough is a theoretical limitation rather than a real one. The dispatch happens once at load time; hosts see a unified `@Published` state surface either way.
@@ -179,7 +181,7 @@ Sources/AetherEngine/
 ├── Network/
 │   └── HLSLocalServer.swift                 Native path: local HTTP server (127.0.0.1) serving playlist + segments
 ├── Renderer/
-│   └── SampleBufferRenderer.swift           SW path: AVSampleBufferDisplayLayer + B-frame reorder, HDR10+ attachments
+│   └── SampleBufferRenderer.swift           SW path: AVSampleBufferDisplayLayer + B-frame reorder, HDR10+ attachments; `flush(removingDisplayedImage:)` holds the last frame through a seek (`DisplayFlushOp`, #90)
 ├── Subtitles/
 │   ├── ASSScriptBuilder.swift               Reassembles raw ASS event cues + TrackInfo.assHeader into a complete script for whole-file renderers
 │   ├── MovTextSampleBuilder.swift           Stateless tx3g (mov_text) sample builder for the native legible-subtitle injection path (LoadOptions.prepareNativeSubtitles, #55)