react-native-queue-player 1.0.0

package/ios/Tests/NowPlayingFormatExtractorTests.swift

@@ -0,0 +1,158 @@
+import AVFoundation
+import CoreMedia
+import XCTest
+@testable import QueuePlayer
+
+/// Pure-mapping coverage for `NowPlayingFormatExtractor`. The async
+/// `extract(item:)` path is exercised end-to-end through the demo
+/// suites; these tests pin the codec / container / MIME tables so a
+/// future contributor can't drift the JS-visible enum without a test
+/// failure.
+final class NowPlayingFormatExtractorTests: XCTestCase {
+
+  func testMapCodecCoversAACFamily() {
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEG4AAC), .aac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEG4AAC_HE), .aac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEG4AAC_HE_V2), .aac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEG4AAC_LD), .aac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEG4AAC_ELD), .aac)
+  }
+
+  func testMapCodecCoversCommonFormats() {
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatMPEGLayer3), .mp3)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatFLAC), .flac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatAppleLossless), .alac)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatOpus), .opus)
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: kAudioFormatLinearPCM), .pcm)
+  }
+
+  func testMapCodecUnknownForUnmappedFormat() {
+    let madeUpFourCC: AudioFormatID = 0x66616B65 // 'fake'
+    XCTAssertEqual(NowPlayingFormatExtractor.mapCodec(formatID: madeUpFourCC), .unknown)
+  }
+
+  func testMapContainerByExtension() {
+    XCTAssertEqual(extractContainer("song.mp3"), .mp3)
+    XCTAssertEqual(extractContainer("song.m4a"), .mp4)
+    XCTAssertEqual(extractContainer("song.m4b"), .mp4)
+    XCTAssertEqual(extractContainer("song.mp4"), .mp4)
+    XCTAssertEqual(extractContainer("song.flac"), .flac)
+    XCTAssertEqual(extractContainer("song.ogg"), .ogg)
+    XCTAssertEqual(extractContainer("song.opus"), .ogg)
+    XCTAssertEqual(extractContainer("song.wav"), .wav)
+    XCTAssertEqual(extractContainer("song.aac"), .aacAdts)
+    XCTAssertEqual(extractContainer("playlist.m3u8"), .hls)
+  }
+
+  func testMapContainerCaseInsensitive() {
+    XCTAssertEqual(extractContainer("SONG.MP3"), .mp3)
+    XCTAssertEqual(extractContainer("Song.M4A"), .mp4)
+  }
+
+  func testMapContainerUnknownForUnknownExtension() {
+    XCTAssertEqual(extractContainer("song.xyz"), .unknown)
+    XCTAssertEqual(extractContainer("song"), .unknown)
+  }
+
+  func testMapContainerUnknownForNilURL() {
+    XCTAssertEqual(NowPlayingFormatExtractor.mapContainer(url: nil), .unknown)
+  }
+
+  func testMapMimeTypeMatchesCodec() {
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .aac), "audio/mp4a-latm")
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .mp3), "audio/mpeg")
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .flac), "audio/flac")
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .alac), "audio/alac")
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .opus), "audio/opus")
+    XCTAssertEqual(NowPlayingFormatExtractor.mapMimeType(codec: .pcm), "audio/L16")
+  }
+
+  func testMapMimeTypeNilForUnknownCodec() {
+    XCTAssertNil(NowPlayingFormatExtractor.mapMimeType(codec: .unknown))
+  }
+
+  // MARK: - readLocalMP3Bitrate
+
+  /// CBR MP3 frame parser returns approximately the encoder's nominal
+  /// rate. ±5% tolerance covers Core Audio's averaging across frames
+  /// (the bitrate field is computed from a running sum, not from the
+  /// first-frame header).
+  func testReadLocalMP3Bitrate_CBR_returnsApproximateNominal() async throws {
+    let url = try requireFixture(name: "silence-cbr-128", ext: "mp3")
+    let bitrate = await NowPlayingFormatExtractor.readLocalMP3Bitrate(url: url)
+    let resolved = try XCTUnwrap(bitrate)
+    let nominal: Double = 128_000.0
+    let tolerance: Double = nominal * 0.05
+    XCTAssertEqual(resolved, nominal, accuracy: tolerance,
+                   "CBR 128 kbps fixture resolved to \(resolved) bps")
+  }
+
+  /// VBR MP3 with a XING/LAME header returns a non-nil bitrate inside
+  /// a plausible range. Tolerance is wide because libmp3lame `-q:a 4`
+  /// targets ~165 kbps but a one-second silence track sits well below
+  /// that nominal — the test only asserts the value is sensible.
+  func testReadLocalMP3Bitrate_VBR_returnsAverage() async throws {
+    let url = try requireFixture(name: "silence-vbr", ext: "mp3")
+    let bitrate = await NowPlayingFormatExtractor.readLocalMP3Bitrate(url: url)
+    let resolved = try XCTUnwrap(bitrate)
+    XCTAssertGreaterThan(resolved, 8_000.0,
+                         "VBR fixture bitrate suspiciously low: \(resolved)")
+    XCTAssertLessThan(resolved, 320_000.0,
+                      "VBR fixture bitrate above MP3 max: \(resolved)")
+  }
+
+  func testReadLocalMP3Bitrate_NonExistentFileReturnsNil() async {
+    let url = URL(fileURLWithPath: "/tmp/__rnqp-does-not-exist__.mp3")
+    let bitrate = await NowPlayingFormatExtractor.readLocalMP3Bitrate(url: url)
+    XCTAssertNil(bitrate)
+  }
+
+  func testReadLocalMP3Bitrate_MalformedMP3ReturnsNil() async throws {
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-malformed-\(UUID().uuidString).mp3")
+    let junk = Data(repeating: 0x00, count: 1024)
+    try junk.write(to: tmp)
+    defer { try? FileManager.default.removeItem(at: tmp) }
+    let bitrate = await NowPlayingFormatExtractor.readLocalMP3Bitrate(url: tmp)
+    XCTAssertNil(bitrate, "all-zero buffer must not parse as MP3")
+  }
+
+  /// Non-MP3 audio passed to the local-MP3 helper returns nil. The
+  /// `kAudioFileMP3Type` argument to `AudioFileOpenURL` is only a hint —
+  /// Core Audio's content sniffing opens the AAC/.m4a fixture
+  /// successfully. The helper's `mFormatID == kAudioFormatMPEGLayer3`
+  /// ASBD check is what rejects the non-MP3 ASBD and returns nil.
+  func testReadLocalMP3Bitrate_NotMP3FallthroughReturnsNil() async throws {
+    let url = try requireFixture(name: "silence-aac-128", ext: "m4a")
+    let bitrate = await NowPlayingFormatExtractor.readLocalMP3Bitrate(url: url)
+    XCTAssertNil(bitrate)
+  }
+
+  // MARK: - helpers
+
+  private func extractContainer(_ path: String) -> AudioContainer {
+    NowPlayingFormatExtractor.mapContainer(url: URL(fileURLWithPath: "/tmp/\(path)"))
+  }
+
+  private func requireFixture(name: String, ext: String) throws -> URL {
+    let bundle = Bundle(for: type(of: self))
+    if let url = bundle.url(forResource: name, withExtension: ext) {
+      return url
+    }
+    // CocoaPods test_spec resources land in a nested bundle named
+    // `QueuePlayer-Unit-Tests.bundle` or under the test bundle's
+    // `Resources` directory depending on platform — fall back to a
+    // recursive search before giving up.
+    let candidates = bundle.urls(forResourcesWithExtension: ext, subdirectory: nil) ?? []
+    if let match = candidates.first(where: { $0.deletingPathExtension().lastPathComponent == name }) {
+      return match
+    }
+    // Fixtures are bundled via `test_spec.resources` in QueuePlayer.podspec.
+    // A miss means the test-harness pod install regressed — that's a real
+    // infrastructure failure, not a conditionally-inapplicable test.
+    return try XCTUnwrap(
+      nil as URL?,
+      "fixture \(name).\(ext) not bundled — pod install regression in tests-harness"
+    )
+  }
+}

package/ios/Tests/NowPlayingInfoTests.swift

@@ -0,0 +1,292 @@
+import MediaPlayer
+import XCTest
+@testable import QueuePlayer
+
+/// `NowPlayingInfo` writes the `MPNowPlayingInfoCenter.default()`
+/// dictionary that drives the lock-screen / control-center surface.
+/// Tests construct the real `TrackItem` Nitro struct via the same
+/// initializer call sites use, then drive the public refresh /
+/// position / artwork / clear methods and assert dictionary contents.
+///
+/// `MPNowPlayingInfoCenter.default()` is process-global, so each test
+/// nils the dictionary in setUp + tearDown.
+final class NowPlayingInfoTests: XCTestCase {
+
+  private var nowPlaying: NowPlayingInfo!
+
+  override func setUp() {
+    super.setUp()
+    nowPlaying = NowPlayingInfo()
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+  }
+
+  override func tearDown() {
+    nowPlaying.clear()
+    nowPlaying = nil
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    super.tearDown()
+  }
+
+  // MARK: - refreshAll
+
+  func testRefreshAllClearsDictWhenSnapshotProviderReturnsNil() {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "existing"]
+    nowPlaying.snapshotProvider = nil
+    nowPlaying.refreshAll()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  func testRefreshAllClearsDictWhenSnapshotHasNoTrack() {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "existing"]
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  func testRefreshAllPopulatesTitleArtistAlbum() {
+    let track = makeTrack(title: "Song", artist: "Artist", album: "Album")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 12, durationSeconds: 180, rate: 1)
+    }
+    nowPlaying.refreshAll()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "Song")
+    XCTAssertEqual(info?[MPMediaItemPropertyArtist] as? String, "Artist")
+    XCTAssertEqual(info?[MPMediaItemPropertyAlbumTitle] as? String, "Album")
+  }
+
+  func testRefreshAllEmptyStringCoercesNilTitleArtistAlbum() {
+    let track = makeTrack(title: nil, artist: nil, album: nil)
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "")
+    XCTAssertEqual(info?[MPMediaItemPropertyArtist] as? String, "")
+    XCTAssertEqual(info?[MPMediaItemPropertyAlbumTitle] as? String, "")
+  }
+
+  func testRefreshAllOmitsDurationWhenZeroOrNegativeOrNonFinite() {
+    let track = makeTrack(title: "T")
+    let omitted: [Double] = [0, -1, .nan, .infinity, -.infinity]
+    for d in omitted {
+      MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+      nowPlaying.snapshotProvider = {
+        NowPlayingInfo.Snapshot(
+          track: track, elapsedSeconds: 0, durationSeconds: d, rate: 0)
+      }
+      nowPlaying.refreshAll()
+      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+      XCTAssertNil(info?[MPMediaItemPropertyPlaybackDuration],
+                   "duration must be omitted for value \(d)")
+    }
+  }
+
+  func testRefreshAllSetsDurationWhenFinitePositive() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 240, rate: 1)
+    }
+    nowPlaying.refreshAll()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(info?[MPMediaItemPropertyPlaybackDuration] as? Double, 240)
+  }
+
+  func testRefreshAllSetsAudioMediaType() {
+    let track = makeTrack()
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(
+      info?[MPNowPlayingInfoPropertyMediaType] as? UInt,
+      MPNowPlayingInfoMediaType.audio.rawValue
+    )
+  }
+
+  func testRefreshAllPlacesArtworkPlaceholder() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertNotNil(info?[MPMediaItemPropertyArtwork])
+    XCTAssertTrue(info?[MPMediaItemPropertyArtwork] is MPMediaItemArtwork)
+  }
+
+  func testRefreshAllElapsedCoercesNonFiniteToZero() {
+    let track = makeTrack(title: "T")
+    let bad: [Double] = [.nan, .infinity, -.infinity, -5]
+    for e in bad {
+      nowPlaying.snapshotProvider = {
+        NowPlayingInfo.Snapshot(
+          track: track, elapsedSeconds: e, durationSeconds: 60, rate: 1)
+      }
+      nowPlaying.refreshAll()
+      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+      XCTAssertEqual(
+        info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 0,
+        "elapsed must be 0 for value \(e)")
+    }
+  }
+
+  func testRefreshAllRateCoercesNonFiniteToZero() {
+    let track = makeTrack(title: "T")
+    let bad: [Float] = [.nan, .infinity, -.infinity]
+    for r in bad {
+      nowPlaying.snapshotProvider = {
+        NowPlayingInfo.Snapshot(
+          track: track, elapsedSeconds: 0, durationSeconds: 60, rate: r)
+      }
+      nowPlaying.refreshAll()
+      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+      XCTAssertEqual(
+        info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0,
+        "rate must be 0 for value \(r)")
+    }
+  }
+
+  // MARK: - refreshPositionAndRate
+
+  func testRefreshPositionAndRateNoOpWhenSnapshotHasNoTrack() {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "value"]
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: nil, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
+    }
+    nowPlaying.refreshPositionAndRate()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(info?["pre"] as? String, "value")
+    XCTAssertNil(info?[MPNowPlayingInfoPropertyElapsedPlaybackTime])
+  }
+
+  func testRefreshPositionAndRateNoOpWhenDictNeverPopulated() {
+    let track = makeTrack(title: "T")
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
+    }
+    nowPlaying.refreshPositionAndRate()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  func testRefreshPositionAndRateNoOpAfterRefreshAllCleared() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
+    }
+    nowPlaying.refreshAll()
+    XCTAssertNotNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 1)
+    }
+    nowPlaying.refreshPositionAndRate()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  func testRefreshPositionAndRateUpdatesElapsedAndRate() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
+    }
+    nowPlaying.refreshAll()
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 0)
+    }
+    nowPlaying.refreshPositionAndRate()
+    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 30)
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0)
+    XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "T")
+  }
+
+  // MARK: - applyArtwork
+
+  func testApplyArtworkUpdatesDictWhenPopulated() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    let placeholder = MPNowPlayingInfoCenter.default().nowPlayingInfo?[MPMediaItemPropertyArtwork]
+    let size = CGSize(width: 8, height: 8)
+    let renderer = UIGraphicsImageRenderer(size: size)
+    let custom = renderer.image { ctx in
+      UIColor.red.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 8, height: 8))
+    }
+    nowPlaying.applyArtwork(custom)
+    let after = MPNowPlayingInfoCenter.default()
+      .nowPlayingInfo?[MPMediaItemPropertyArtwork] as? MPMediaItemArtwork
+    XCTAssertNotNil(after)
+    XCTAssertFalse((after as AnyObject) === (placeholder as AnyObject))
+    let resolvedImage = after?.image(at: size)
+    XCTAssertNotNil(resolvedImage)
+    XCTAssertEqual(resolvedImage?.size, size,
+                   "applyArtwork must surface the supplied UIImage at its natural size")
+  }
+
+  func testApplyArtworkNoOpWhenDictNil() {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 8, height: 8))
+    let custom = renderer.image { ctx in UIColor.red.setFill(); ctx.fill(CGRect(x: 0, y: 0, width: 8, height: 8)) }
+    nowPlaying.applyArtwork(custom)
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  // MARK: - clear
+
+  func testClearNilsTheDict() {
+    let track = makeTrack(title: "T")
+    nowPlaying.snapshotProvider = {
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
+    }
+    nowPlaying.refreshAll()
+    XCTAssertNotNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+    nowPlaying.clear()
+    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  }
+
+  // MARK: - Helpers
+
+  private func makeTrack(
+    id: String = "t1",
+    url: String = "https://example.com/track.mp3",
+    title: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    duration: Double? = nil,
+    artworkUrl: String? = nil
+  ) -> TrackItem {
+    return TrackItem(
+      id: id, url: url, title: title, artist: artist, album: album,
+      duration: duration, artworkUrl: artworkUrl, extras: nil
+    )
+  }
+}

package/ios/Tests/PendingBrowseRequestsTests.swift

@@ -0,0 +1,69 @@
+import XCTest
+@testable import QueuePlayer
+
+/// iOS mirror of the Android `PendingBrowseRequestsTest`. Same shape,
+/// same contract assertions.
+final class PendingBrowseRequestsTests: XCTestCase {
+
+  func testDrainAllOnFreshQueueReturnsEmpty() {
+    let q = PendingBrowseRequests()
+    XCTAssertTrue(q.drainAll().isEmpty)
+  }
+
+  func testEnqueueRecordsTheParentId() {
+    let q = PendingBrowseRequests()
+    q.enqueue("root")
+    XCTAssertEqual(q.snapshotForTest(), ["root"])
+  }
+
+  func testDuplicateEnqueuesCollapse() {
+    let q = PendingBrowseRequests()
+    q.enqueue("root")
+    q.enqueue("root")
+    q.enqueue("section-a")
+    q.enqueue("section-a")
+    XCTAssertEqual(q.drainAll(), ["root", "section-a"])
+  }
+
+  func testDrainAllEmptiesTheQueue() {
+    let q = PendingBrowseRequests()
+    q.enqueue("root")
+    q.enqueue("section-a")
+    let drained = q.drainAll()
+    XCTAssertEqual(drained, ["root", "section-a"])
+    XCTAssertTrue(q.drainAll().isEmpty)
+    XCTAssertTrue(q.snapshotForTest().isEmpty)
+  }
+
+  func testClearEmptiesWithoutReturning() {
+    let q = PendingBrowseRequests()
+    q.enqueue("root")
+    q.enqueue("section-a")
+    q.clear()
+    XCTAssertTrue(q.drainAll().isEmpty)
+  }
+
+  func testReEnqueueAfterDrainAccumulatesFreshEntries() {
+    let q = PendingBrowseRequests()
+    q.enqueue("a")
+    q.drainAll()
+    q.enqueue("b")
+    q.enqueue("c")
+    XCTAssertEqual(q.drainAll(), ["b", "c"])
+  }
+
+  func testConcurrentEnqueuesPreserveEveryUniqueParent() {
+    let q = PendingBrowseRequests()
+    let parents = (0..<200).map { "parent-\($0)" }
+    let group = DispatchGroup()
+    for p in parents {
+      group.enter()
+      DispatchQueue.global().async {
+        q.enqueue(p)
+        group.leave()
+      }
+    }
+    group.wait()
+    XCTAssertEqual(q.drainAll(), Set(parents))
+  }
+}

package/ios/Tests/PendingIntentBufferTests.swift

@@ -0,0 +1,164 @@
+import Foundation
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for the single-slot pending intent buffer. Drives
+/// `push` / `drain` / `peek` / `clear` / `isEmpty` directly with a
+/// synthetic `Sendable` payload so the generic shape is exercised
+/// without dragging Nitrogen-bridged request types into the test
+/// target.
+final class PendingIntentBufferTests: XCTestCase {
+
+  private struct Sample: Sendable, Equatable {
+    let payload: String
+  }
+
+  /// Synchronously-controllable clock for deterministic TTL tests.
+  private final class FakeClock: @unchecked Sendable {
+    private let lock = NSLock()
+    private var current: Date
+    init(_ start: Date) { self.current = start }
+    func now() -> Date {
+      lock.lock()
+      defer { lock.unlock() }
+      return current
+    }
+    func advance(by seconds: TimeInterval) {
+      lock.lock()
+      defer { lock.unlock() }
+      current = current.addingTimeInterval(seconds)
+    }
+  }
+
+  private func makeBuffer(
+    ttl: TimeInterval = 20,
+    clock: FakeClock
+  ) -> PendingIntentBuffer<Sample> {
+    return PendingIntentBuffer<Sample>(ttl: ttl, clock: { [clock] in clock.now() })
+  }
+
+  func testEmptyBufferDrainsNil() {
+    let buffer = PendingIntentBuffer<Sample>()
+    XCTAssertNil(buffer.drain())
+    XCTAssertNil(buffer.peek())
+    XCTAssertTrue(buffer.isEmpty)
+  }
+
+  func testPushThenDrainReturnsRequest() {
+    let buffer = PendingIntentBuffer<Sample>()
+    buffer.push(Sample(payload: "first"))
+    XCTAssertEqual(buffer.drain(), Sample(payload: "first"))
+  }
+
+  func testDrainEmptiesTheBuffer() {
+    let buffer = PendingIntentBuffer<Sample>()
+    buffer.push(Sample(payload: "first"))
+    _ = buffer.drain()
+    XCTAssertNil(buffer.drain())
+    XCTAssertTrue(buffer.isEmpty)
+  }
+
+  func testSecondPushReplacesFirst() {
+    let buffer = PendingIntentBuffer<Sample>()
+    buffer.push(Sample(payload: "first"))
+    buffer.push(Sample(payload: "second"))
+    XCTAssertEqual(buffer.drain(), Sample(payload: "second"))
+    XCTAssertNil(buffer.drain())
+  }
+
+  func testPeekDoesNotEmpty() {
+    let buffer = PendingIntentBuffer<Sample>()
+    buffer.push(Sample(payload: "first"))
+    XCTAssertEqual(buffer.peek(), Sample(payload: "first"))
+    XCTAssertEqual(buffer.peek(), Sample(payload: "first"))
+    XCTAssertEqual(buffer.drain(), Sample(payload: "first"))
+  }
+
+  func testExpiredEntryDrainsNil() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 20, clock: clock)
+    buffer.push(Sample(payload: "stale"))
+    clock.advance(by: 21)
+    XCTAssertNil(buffer.drain())
+  }
+
+  func testExpiredEntryPeeksNilAndClears() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 20, clock: clock)
+    buffer.push(Sample(payload: "stale"))
+    clock.advance(by: 25)
+    XCTAssertNil(buffer.peek())
+    XCTAssertTrue(buffer.isEmpty)
+    XCTAssertNil(buffer.drain())
+  }
+
+  func testJustBeforeTtlBoundaryStillDrains() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 20, clock: clock)
+    buffer.push(Sample(payload: "fresh"))
+    clock.advance(by: 19.9)
+    XCTAssertEqual(buffer.drain(), Sample(payload: "fresh"))
+  }
+
+  func testZeroTtlSameInstantDrains() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 0, clock: clock)
+    buffer.push(Sample(payload: "now"))
+    XCTAssertEqual(buffer.drain(), Sample(payload: "now"))
+  }
+
+  func testZeroTtlAfterAdvanceDropsEntry() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 0, clock: clock)
+    buffer.push(Sample(payload: "now"))
+    clock.advance(by: 0.001)
+    XCTAssertNil(buffer.drain())
+  }
+
+  func testNegativeClockSkewClampsToZeroElapsed() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 20, clock: clock)
+    buffer.push(Sample(payload: "fresh"))
+    clock.advance(by: -10)
+    XCTAssertEqual(buffer.drain(), Sample(payload: "fresh"))
+  }
+
+  func testPushAfterPeekClearedExpiredSlotReturnsFreshEntry() {
+    let clock = FakeClock(Date(timeIntervalSince1970: 1_000))
+    let buffer = makeBuffer(ttl: 20, clock: clock)
+    buffer.push(Sample(payload: "stale"))
+    clock.advance(by: 25)
+    XCTAssertNil(buffer.peek())
+    XCTAssertTrue(buffer.isEmpty)
+    buffer.push(Sample(payload: "fresh"))
+    XCTAssertEqual(buffer.drain(), Sample(payload: "fresh"))
+  }
+
+  func testClearEmptiesWithoutReturn() {
+    let buffer = PendingIntentBuffer<Sample>()
+    buffer.push(Sample(payload: "first"))
+    buffer.clear()
+    XCTAssertNil(buffer.drain())
+    XCTAssertTrue(buffer.isEmpty)
+  }
+
+  func testInterleavedPushAndDrainSerialiseSafely() {
+    let buffer = PendingIntentBuffer<Sample>()
+    let pushQueue = DispatchQueue(label: "push", attributes: .concurrent)
+    let drainQueue = DispatchQueue(label: "drain", attributes: .concurrent)
+    let group = DispatchGroup()
+    for i in 0..<200 {
+      group.enter()
+      pushQueue.async {
+        buffer.push(Sample(payload: "p-\(i)"))
+        group.leave()
+      }
+      group.enter()
+      drainQueue.async {
+        _ = buffer.drain()
+        group.leave()
+      }
+    }
+    XCTAssertEqual(group.wait(timeout: .now() + .seconds(2)), .success)
+  }
+}