reduce vlc seek buffering with better cache priming

.beads/interactions.jsonl

@@ -44,3 +44,4 @@
 {"id":"int-b2667330","kind":"field_change","created_at":"2026-05-25T23:44:07.439593Z","actor":"dirtydishes","issue_id":"dreamio-9gw","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds."}}
 {"id":"int-6ca684f7","kind":"field_change","created_at":"2026-05-26T04:00:46.072019Z","actor":"dirtydishes","issue_id":"dreamio-42s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild."}}
 {"id":"int-176e3ad2","kind":"field_change","created_at":"2026-05-26T04:14:19.812849Z","actor":"dirtydishes","issue_id":"dreamio-meh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch."}}
+{"id":"int-56a87fde","kind":"field_change","created_at":"2026-05-26T04:35:35.693504Z","actor":"dirtydishes","issue_id":"dreamio-3pn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation."}}

.beads/issues.jsonl

@@ -1,5 +1,6 @@
 {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"dreamio-3pn","title":"reduce vlc seek buffering with range cache priming","description":"Improve VLC local range cache behavior after seek/jump by priming bytes behind the target, using stable global chunk boundaries, retaining useful cached ranges under a byte budget, and adding tests for the observed post-seek request pattern.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:31:46Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:35:36Z","started_at":"2026-05-26T04:31:51Z","closed_at":"2026-05-26T04:35:36Z","close_reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"dreamio-meh","title":"Use VLC range requests to reprioritize seek prefetch","description":"Jump logs show duration-based byteOffset estimates can be far behind VLC's actual post-seek range requests, so prefetch keeps warming stale bytes while VLC buffers on higher cache misses.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:11:38Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:14:20Z","started_at":"2026-05-26T04:11:40Z","closed_at":"2026-05-26T04:14:20Z","close_reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"dreamio-42s","title":"Reduce VLC range-cache buffering after seeks","description":"Logs show repeated local-cache misses and cancelled prefetch tasks after VLC jumps backward, causing buffering while the cache restarts speculative requests instead of preserving useful adjacent downloads.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T03:58:03Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:00:46Z","started_at":"2026-05-26T03:58:10Z","closed_at":"2026-05-26T04:00:46Z","close_reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"dreamio-9gw","title":"Cap VLC local range cache memory","description":"Playback can be killed for memory when VLC asks the loopback cache for a very large byte range. The local range cache should answer with bounded partial ranges and trim cached segments to the active window.","status":"closed","priority":1,"issue_type":"bug","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:38:08Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:44:07Z","closed_at":"2026-05-25T23:44:07Z","close_reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds.","dependency_count":0,"dependent_count":0,"comment_count":0}

Dreamio/ProgressiveHTTPRangeCache.swift

@@ -73,6 +73,12 @@ final class SparseHTTPByteRangeStore {
         }
     }
 
+    var cachedByteCount: Int64 {
+        lock.withLock {
+            segments.reduce(0) { $0 + Int64($1.data.count) }
+        }
+    }
+
     func insert(data: Data, at start: Int64) {
         guard !data.isEmpty else {
             return
@@ -117,6 +123,33 @@ final class SparseHTTPByteRangeStore {
         data(for: range) != nil
     }
 
+    func missingRanges(in range: HTTPByteRange) -> [HTTPByteRange] {
+        lock.withLock {
+            var cursor = range.start
+            var missing: [HTTPByteRange] = []
+
+            for segment in segments where segment.range.end >= cursor {
+                guard segment.range.start <= range.end else {
+                    break
+                }
+                if segment.range.start > cursor {
+                    missing.append(HTTPByteRange(start: cursor, end: min(range.end, segment.range.start - 1)))
+                }
+                if segment.range.end >= cursor {
+                    cursor = max(cursor, segment.range.end + 1)
+                }
+                if cursor > range.end {
+                    break
+                }
+            }
+
+            if cursor <= range.end {
+                missing.append(HTTPByteRange(start: cursor, end: range.end))
+            }
+            return missing
+        }
+    }
+
     func evict(keeping window: HTTPByteRange) {
         lock.withLock {
             segments = segments.compactMap { segment in
@@ -135,6 +168,61 @@ final class SparseHTTPByteRangeStore {
         }
     }
 
+    func evict(toByteBudget byteBudget: Int64, preserving protectedRanges: [HTTPByteRange]) -> [HTTPByteRange] {
+        lock.withLock {
+            guard byteBudget > 0 else {
+                let evicted = segments.map(\.range)
+                segments.removeAll()
+                return evicted
+            }
+
+            var totalBytes = segments.reduce(0) { $0 + Int64($1.data.count) }
+            guard totalBytes > byteBudget else {
+                return []
+            }
+
+            var evicted: [HTTPByteRange] = []
+            while totalBytes > byteBudget,
+                  let index = evictionCandidateIndex(protectedRanges: protectedRanges) {
+                let removed = segments.remove(at: index)
+                totalBytes -= Int64(removed.data.count)
+                evicted.append(removed.range)
+            }
+            return evicted
+        }
+    }
+
+    private func evictionCandidateIndex(protectedRanges: [HTTPByteRange]) -> Int? {
+        var bestIndex: Int?
+        var bestDistance: Int64 = .min
+
+        for (index, segment) in segments.enumerated() {
+            if protectedRanges.contains(where: { $0.overlapsOrTouches(segment.range) }) {
+                continue
+            }
+
+            let distance = protectedRanges
+                .map { rangeDistance(from: segment.range, to: $0) }
+                .min() ?? segment.range.start
+            if distance > bestDistance {
+                bestDistance = distance
+                bestIndex = index
+            }
+        }
+
+        return bestIndex
+    }
+
+    private func rangeDistance(from range: HTTPByteRange, to protectedRange: HTTPByteRange) -> Int64 {
+        if range.overlapsOrTouches(protectedRange) {
+            return 0
+        }
+        if range.end < protectedRange.start {
+            return protectedRange.start - range.end
+        }
+        return range.start - protectedRange.end
+    }
+
     private func mergeSegments() {
         guard !segments.isEmpty else {
             return
@@ -257,14 +345,24 @@ final class ProgressiveHTTPRangeCacheSession {
     let durationProvider: () -> TimeInterval
     private let prefetchChunkSize: Int64 = 1_048_576
     private let responseChunkSize: Int64 = 1_048_576
+    private let seekPrimeBehindBytes: Int64 = 4 * 1_048_576
+    private let cacheByteBudget: Int64
     private var prefetchTask: Task<Void, Never>?
     private var activePrefetchWindow: HTTPByteRange?
     private var activePrefetchPreferredOffset: Int64?
+    private var recentSeekRange: HTTPByteRange?
+    private var recentForegroundRange: HTTPByteRange?
 
-    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
+    init(
+        fetcher: HTTPRangeRemoteFetcher,
+        contentLength: Int64,
+        durationProvider: @escaping () -> TimeInterval,
+        cacheByteBudget: Int64 = 64 * 1_048_576
+    ) {
         self.fetcher = fetcher
         self.contentLength = contentLength
         self.durationProvider = durationProvider
+        self.cacheByteBudget = cacheByteBudget
     }
 
     deinit {
@@ -273,6 +371,7 @@ final class ProgressiveHTTPRangeCacheSession {
 
     func data(for requestedRange: HTTPByteRange) async throws -> Data {
         let bounded = clamp(requestedRange)
+        recentForegroundRange = bounded
         if let data = store.data(for: bounded) {
 #if DEBUG
             print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)")
@@ -280,14 +379,18 @@ final class ProgressiveHTTPRangeCacheSession {
             return data
         }
 
+        let missingRanges = store.missingRanges(in: bounded)
 #if DEBUG
-        print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)")
+        let missKind = missingRanges.count == 1 && missingRanges[0] == bounded ? "uncached" : "partial-miss"
+        print("[DreamioRangeCache] cache=\(missKind) range=\(bounded.start)-\(bounded.end) missing=\(missingRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))")
 #endif
         cancelPrefetchIfNeeded(forForegroundRange: bounded)
-        let data = try await fetcher.fetch(range: bounded)
-        store.insert(data: data, at: bounded.start)
+        for missingRange in missingRanges {
+            let data = try await fetcher.fetch(range: missingRange)
+            store.insert(data: data, at: missingRange.start)
+        }
         prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
-        return store.data(for: bounded) ?? data
+        return store.data(for: bounded) ?? Data()
     }
 
     func responseRange(for requestedRange: HTTPByteRange) -> HTTPByteRange {
@@ -299,30 +402,54 @@ final class ProgressiveHTTPRangeCacheSession {
     }
 
     func prefetch(aroundByteOffset offset: Int64) {
-        prefetch(aroundByteOffset: offset, forceRestart: false)
+        prefetch(aroundByteOffset: offset, forceRestart: false, startsAtWindowStart: false)
+    }
+
+    func prefetchForSeek(aroundByteOffset offset: Int64) {
+        let window = seekPrimeWindow(aroundByteOffset: offset)
+        recentSeekRange = window
+        prefetch(
+            aroundByteOffset: offset,
+            forceRestart: true,
+            explicitWindow: window,
+            startsAtWindowStart: true
+        )
+    }
+
+    func seekPrimeWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
+        targetWindow(aroundByteOffset: offset, minimumBehind: seekPrimeBehindBytes)
     }
 
     func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) {
+        prefetch(aroundByteOffset: offset, forceRestart: forceRestart, startsAtWindowStart: false)
+    }
+
+    private func prefetch(
+        aroundByteOffset offset: Int64,
+        forceRestart: Bool,
+        explicitWindow: HTTPByteRange? = nil,
+        startsAtWindowStart: Bool
+    ) {
         if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
             return
         }
 
         prefetchTask?.cancel()
-        let window = targetWindow(aroundByteOffset: offset)
+        let window = explicitWindow ?? targetWindow(aroundByteOffset: offset)
         activePrefetchWindow = window
         activePrefetchPreferredOffset = offset
-        store.evict(keeping: window)
+        evictOverBudget(protecting: window)
         guard !store.hasData(for: window) else {
             activePrefetchWindow = nil
             activePrefetchPreferredOffset = nil
             return
         }
 
-        prefetchTask = Task { [weak self] in
+        prefetchTask = Task(priority: startsAtWindowStart ? .userInitiated : .utility) { [weak self] in
             guard let self else {
                 return
             }
-            for chunk in self.prefetchChunks(in: window, preferredOffset: offset) {
+            for chunk in self.prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: startsAtWindowStart) {
                 guard !Task.isCancelled else {
                     return
                 }
@@ -330,6 +457,7 @@ final class ProgressiveHTTPRangeCacheSession {
                     do {
                         let data = try await fetcher.fetch(range: chunk)
                         store.insert(data: data, at: chunk.start)
+                        evictOverBudget(protecting: window)
 #if DEBUG
                         print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)")
 #endif
@@ -373,15 +501,25 @@ final class ProgressiveHTTPRangeCacheSession {
     }
 
     private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
+        targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize)
+    }
+
+    private func targetWindow(aroundByteOffset offset: Int64, minimumBehind: Int64) -> HTTPByteRange {
         let bytesPerSecond = estimatedBytesPerSecond()
-        let behind = max(prefetchChunkSize, bytesPerSecond * 30)
+        let behind = max(minimumBehind, bytesPerSecond * 30)
         let ahead = max(prefetchChunkSize * 2, bytesPerSecond * 60)
-        return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
+        let raw = clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
+        return HTTPByteRange(start: alignedChunkStart(for: raw.start), end: alignedChunkEnd(for: raw.end))
     }
 
     func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] {
+        prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: false)
+    }
+
+    func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64, startsAtWindowStart: Bool) -> [HTTPByteRange] {
         let boundedOffset = max(window.start, min(window.end, offset))
-        let preferredStart = window.start + ((boundedOffset - window.start) / prefetchChunkSize) * prefetchChunkSize
+        let windowStart = alignedChunkStart(for: window.start)
+        let preferredStart = startsAtWindowStart ? windowStart : alignedChunkStart(for: boundedOffset)
         var chunks: [HTTPByteRange] = []
 
         var cursor = preferredStart
@@ -391,7 +529,7 @@ final class ProgressiveHTTPRangeCacheSession {
             cursor = chunk.end + 1
         }
 
-        cursor = window.start
+        cursor = windowStart
         while cursor < preferredStart {
             let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1))
             chunks.append(chunk)
@@ -401,6 +539,27 @@ final class ProgressiveHTTPRangeCacheSession {
         return chunks
     }
 
+    private func evictOverBudget(protecting range: HTTPByteRange) {
+        let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1))
+        let tailStart = max(0, contentLength - (4 * prefetchChunkSize))
+        let tailRange = HTTPByteRange(start: tailStart, end: contentLength - 1)
+        let protectedRanges = [range, recentSeekRange, recentForegroundRange, activePrefetchWindow, headerRange, tailRange].compactMap { $0 }
+        let evicted = store.evict(toByteBudget: cacheByteBudget, preserving: protectedRanges)
+#if DEBUG
+        if !evicted.isEmpty {
+            print("[DreamioRangeCache] evicted reason=budget ranges=\(evicted.map { "\($0.start)-\($0.end)" }.joined(separator: ",")) protected=\(protectedRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))")
+        }
+#endif
+    }
+
+    private func alignedChunkStart(for offset: Int64) -> Int64 {
+        max(0, (offset / prefetchChunkSize) * prefetchChunkSize)
+    }
+
+    private func alignedChunkEnd(for offset: Int64) -> Int64 {
+        min(contentLength - 1, alignedChunkStart(for: offset) + prefetchChunkSize - 1)
+    }
+
     private func estimatedBytesPerSecond() -> Int64 {
         let duration = durationProvider()
         guard duration > 1 else {

Dreamio/VLCNativePlaybackBackend.swift

@@ -151,7 +151,7 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend {
             return
         }
         let clamped = max(0, min(1, position))
-        rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0)
+        rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0)
 #if DEBUG
         if let byteOffset = rangeCacheSession?.byteOffset(for: clamped) {
             print("[DreamioVLC] seek targetPosition=\(clamped) byteOffset=\(byteOffset) mode=local-cache")
@@ -171,7 +171,7 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend {
         let nextTime = max(0, min(duration, currentTime + seconds))
         if duration > 0 {
             let nextPosition = Float(nextTime / duration)
-            rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0)
+            rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0)
 #if DEBUG
             if let byteOffset = rangeCacheSession?.byteOffset(for: nextPosition) {
                 print("[DreamioVLC] jump seconds=\(seconds) target=\(nextTime) byteOffset=\(byteOffset) mode=local-cache")
@@ -604,6 +604,13 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend {
 #if canImport(MobileVLCKit)
 extension VLCNativePlaybackBackend: VLCMediaPlayerDelegate {
     func mediaPlayerStateChanged(_ aNotification: Notification) {
+        Task { @MainActor [weak self] in
+            self?.handleMediaPlayerStateChanged()
+        }
+    }
+
+    @MainActor
+    private func handleMediaPlayerStateChanged() {
 #if DEBUG
         logPlaybackStateIfNeeded(stateName(mediaPlayer.state))
 #endif

Tests/StreamResolverTests.swift

@@ -35,8 +35,11 @@ struct StreamResolverTests {
         testSparseRangeStoreHitPartialHitAndMiss()
         testSparseRangeStoreEvictsOutsideWindow()
         testSparseRangeStoreTrimsOverlappingWindow()
+        testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges()
         testRangeCacheSessionCapsResponseRange()
         testRangeCachePrefetchPrioritizesSeekOffset()
+        testRangeCacheSeekPrimingIncludesObservedVLCStart()
+        testRangeCachePrefetchUsesGlobalChunkBoundaries()
         await testRangeCacheForegroundMissReprioritizesPrefetch()
         await testRangeProbeFallsBackWhenServerIgnoresRange()
         await testRangeFetcherPreservesHeaders()
@@ -334,6 +337,28 @@ struct StreamResolverTests {
         assert(store.data(for: HTTPByteRange(start: 0, end: 5)) == nil, "Expected trimmed bytes outside the window to be evicted")
     }
 
+    private static func testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges() {
+        let store = SparseHTTPByteRangeStore()
+
+        store.insert(data: Data(repeating: 1, count: 4), at: 0)
+        store.insert(data: Data(repeating: 2, count: 4), at: 100)
+        store.insert(data: Data(repeating: 3, count: 4), at: 200)
+
+        let evicted = store.evict(
+            toByteBudget: 8,
+            preserving: [
+                HTTPByteRange(start: 0, end: 3),
+                HTTPByteRange(start: 190, end: 210)
+            ]
+        )
+
+        assertEqual(evicted, [HTTPByteRange(start: 100, end: 103)])
+        assertEqual(store.cachedRanges, [
+            HTTPByteRange(start: 0, end: 3),
+            HTTPByteRange(start: 200, end: 203)
+        ])
+    }
+
     private static func testRangeCacheSessionCapsResponseRange() {
         let session = ProgressiveHTTPRangeCacheSession(
             fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
@@ -368,6 +393,50 @@ struct StreamResolverTests {
         ])
     }
 
+    private static func testRangeCacheSeekPrimingIncludesObservedVLCStart() {
+        let session = ProgressiveHTTPRangeCacheSession(
+            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
+            contentLength: 711_080_522,
+            durationProvider: { 0 }
+        )
+
+        let estimatedOffset: Int64 = 213_615_760
+        let firstVLCRequest = HTTPByteRange(start: 212_942_432, end: 213_991_007)
+        let window = session.seekPrimeWindow(aroundByteOffset: estimatedOffset)
+        let chunks = session.prefetchChunks(
+            in: window,
+            preferredOffset: estimatedOffset,
+            startsAtWindowStart: true
+        )
+
+        let chunkContainingVLCStart = chunks.firstIndex { $0.contains(firstVLCRequest.start) }
+        let chunkContainingEstimatedOffset = chunks.firstIndex { $0.contains(estimatedOffset) }
+
+        assert(chunkContainingVLCStart != nil, "Expected seek priming to include VLC's first request start")
+        assert(chunkContainingEstimatedOffset != nil, "Expected seek priming to include the estimated offset")
+        assert(
+            chunkContainingVLCStart! <= chunkContainingEstimatedOffset!,
+            "Expected bytes behind the seek target to be primed before ahead chunks"
+        )
+        assertEqual(chunks[chunkContainingVLCStart!], HTTPByteRange(start: 212_860_928, end: 213_909_503))
+    }
+
+    private static func testRangeCachePrefetchUsesGlobalChunkBoundaries() {
+        let session = ProgressiveHTTPRangeCacheSession(
+            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
+            contentLength: 711_080_522,
+            durationProvider: { 0 }
+        )
+
+        let chunks = session.prefetchChunks(
+            in: HTTPByteRange(start: 213_278_260, end: 216_000_000),
+            preferredOffset: 213_615_760
+        )
+
+        assert(chunks.allSatisfy { $0.start % 1_048_576 == 0 }, "Expected prefetch chunk starts to use stable global 1 MB boundaries: \(chunks)")
+        assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503))
+    }
+
     private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
         let queue = DispatchQueue(label: "dreamio.range-cache-test")
         var requestedRanges: [String] = []
@@ -406,8 +475,8 @@ struct StreamResolverTests {
         let ranges = queue.sync { requestedRanges }
         assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
         assert(ranges.contains { range in
-            range.hasPrefix("bytes=51936225-")
-        }, "Expected prefetch to restart near VLC's foreground range, got \(ranges)")
+            range.hasPrefix("bytes=52428800-")
+        }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)")
         session.cancelPrefetch()
         MockURLProtocol.handler = nil
         try? await Task.sleep(nanoseconds: 50_000_000)