react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/ios/Tests/LRUCacheTests.swift

@@ -0,0 +1,111 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("LRUCache")
+struct LRUCacheTests {
+  /// A class so the tests can observe release through a weak reference.
+  private final class Box {
+    let id: Int
+    init(_ id: Int) { self.id = id }
+  }
+
+  @Test func evictsTheLeastRecentlyUsed() {
+    let cache = LRUCache<String, Int>(maxSize: 2)
+    cache.set("a", value: 1)
+    cache.set("b", value: 2)
+    cache.set("c", value: 3)
+
+    #expect(cache.get("a") == nil)
+    #expect(cache.get("b") == 2)
+    #expect(cache.get("c") == 3)
+    #expect(cache.count == 2)
+  }
+
+  /// A read is a use: it must move the entry off the eviction end.
+  @Test func readingPromotesAnEntry() {
+    let cache = LRUCache<String, Int>(maxSize: 2)
+    cache.set("a", value: 1)
+    cache.set("b", value: 2)
+    _ = cache.get("a")
+    cache.set("c", value: 3)
+
+    #expect(cache.get("a") == 1)
+    #expect(cache.get("b") == nil)
+  }
+
+  @Test func removeDropsOnlyItsOwnEntry() {
+    let cache = LRUCache<String, Int>(maxSize: 3)
+    cache.set("a", value: 1)
+    cache.set("b", value: 2)
+    cache.set("c", value: 3)
+
+    cache.remove("b")
+
+    #expect(cache.get("b") == nil)
+    #expect(cache.get("a") == 1)
+    #expect(cache.get("c") == 3)
+    #expect(cache.count == 2)
+  }
+
+  /// The nodes form a doubly-linked list. If both directions were strong, adjacent nodes would
+  /// retain each other and clearing would drop only the dictionary and the two ends — the chain,
+  /// and everything it holds, would survive (#96).
+  @Test func clearReleasesEveryNode() {
+    let cache = LRUCache<String, Box>(maxSize: 10)
+    weak var first: Box?
+    weak var middle: Box?
+    weak var last: Box?
+
+    do {
+      let a = Box(1), b = Box(2), c = Box(3)
+      (first, middle, last) = (a, b, c)
+      cache.set("a", value: a)
+      cache.set("b", value: b)
+      cache.set("c", value: c)
+    }
+
+    #expect(first != nil, "the cache should still hold its entries")
+
+    cache.clear()
+
+    #expect(first == nil)
+    #expect(middle == nil)
+    #expect(last == nil)
+    #expect(cache.count == 0)
+  }
+
+  /// Same cycle, reached by dropping the cache itself rather than clearing it.
+  @Test func droppingTheCacheReleasesEveryNode() {
+    weak var first: Box?
+    weak var last: Box?
+
+    do {
+      let cache = LRUCache<String, Box>(maxSize: 10)
+      let a = Box(1), b = Box(2)
+      (first, last) = (a, b)
+      cache.set("a", value: a)
+      cache.set("b", value: b)
+      #expect(first != nil)
+    }
+
+    #expect(first == nil)
+    #expect(last == nil)
+  }
+
+  /// Eviction has always unlinked the node it drops; this pins that down alongside the rest.
+  @Test func evictionReleasesTheEvictedNode() {
+    let cache = LRUCache<String, Box>(maxSize: 1)
+    weak var evicted: Box?
+
+    do {
+      let a = Box(1)
+      evicted = a
+      cache.set("a", value: a)
+      cache.set("b", value: Box(2))
+    }
+
+    #expect(evicted == nil)
+  }
+}

package/ios/Tests/LoadSeekCoordinatorTests.swift

@@ -50,7 +50,7 @@ struct CaptureTests {
   @Test func setsStateToPendingSeek() {
     let c = makeCoordinator()
     c.capture(position: 42.0)
-    guard case .pendingSeek(let time) = c.state else {
+    guard case let .pendingSeek(time) = c.state else {
       Issue.record("expected .pendingSeek, got \(c.state)")
       return
     }
@@ -87,7 +87,7 @@ struct CaptureTests {
       return
     }
     c.capture(position: 30.0)
-    guard case .pendingSeek(let time) = c.state else {
+    guard case let .pendingSeek(time) = c.state else {
       Issue.record("expected .pendingSeek, got \(c.state)")
       return
     }
@@ -118,7 +118,7 @@ struct ExecuteIfPendingTests {
     let player = AVPlayer()
     c.capture(position: 15.0)
     _ = c.executeIfPending(on: player, delegate: nil)
-    guard case .seekInFlight(let time) = c.state else {
+    guard case let .seekInFlight(time) = c.state else {
       Issue.record("expected .seekInFlight, got \(c.state)")
       return
     }
@@ -170,7 +170,7 @@ struct SeekDidCompleteTests {
     c.capture(position: 20.0)
     // Complete the first seek — should re-execute
     #expect(c.seekDidComplete(on: player, delegate: nil) == false)
-    guard case .seekInFlight(let time) = c.state else {
+    guard case let .seekInFlight(time) = c.state else {
       Issue.record("expected .seekInFlight, got \(c.state)")
       return
     }
@@ -220,6 +220,39 @@ struct ResetTests {
       return
     }
   }
+
+  @Test func invalidatesTheGenerationOfSeeksInFlight() {
+    let c = makeCoordinator()
+    let issuedAgainst = c.generation
+    #expect(c.isCurrentGeneration(issuedAgainst))
+    c.reset()
+    #expect(!c.isCurrentGeneration(issuedAgainst))
+  }
+
+  /// The cross-item race: a seek is in flight when a queue change resets the
+  /// coordinator and captures the new track's start position. The old item's
+  /// cancelled completion (now a stale generation) must be dropped — not
+  /// delivered as a completion that would consume the fresh pending seek.
+  @Test func staleCompletionAfterResetIsDroppedAndKeepsThePendingSeek() async {
+    let c = makeCoordinator()
+    let player = AVPlayer()
+    let spy = SeekCompletionSpy()
+
+    c.capture(position: 10.0)
+    _ = c.executeIfPending(on: player, delegate: spy)
+
+    // Queue change: reset, then capture the new track's start position.
+    c.reset()
+    c.capture(position: 25.0)
+
+    // Let the (immediately-cancelled, itemless) seek completion drain.
+    for _ in 0 ..< 20 {
+      await Task.yield()
+    }
+
+    #expect(spy.calls.isEmpty)
+    #expect(c.pendingTime == 25.0)
+  }
 }
 
 // MARK: - Integration
@@ -260,7 +293,7 @@ struct IntegrationTests {
     // First seek
     c.capture(position: 10.0)
     _ = c.executeIfPending(on: player, delegate: nil)
-    guard case .seekInFlight(let t1) = c.state else {
+    guard case let .seekInFlight(t1) = c.state else {
       Issue.record("expected .seekInFlight")
       return
     }
@@ -268,7 +301,7 @@ struct IntegrationTests {
 
     // Override while in-flight
     c.capture(position: 50.0)
-    guard case .pendingSeek(let t2) = c.state else {
+    guard case let .pendingSeek(t2) = c.state else {
       Issue.record("expected .pendingSeek")
       return
     }
@@ -277,7 +310,7 @@ struct IntegrationTests {
     // First seek "completes" — should auto re-execute
     let done = c.seekDidComplete(on: player, delegate: nil)
     #expect(done == false)
-    guard case .seekInFlight(let t3) = c.state else {
+    guard case let .seekInFlight(t3) = c.state else {
       Issue.record("expected .seekInFlight after re-execute")
       return
     }

package/ios/Tests/MediaIntentCriteriaTests.swift

@@ -0,0 +1,170 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("MediaIntentCriteria")
+struct MediaIntentCriteriaTests {
+  @Test func emptyEverything_isResume() {
+    let c = MediaIntentCriteria(query: "", reference: .unknown, hasGenres: false, hasMediaType: false, matchesAppName: false)
+    #expect(c.isResume)
+  }
+
+  @Test func whitespaceQuery_isResume() {
+    let c = MediaIntentCriteria(query: "   ", reference: .unknown, hasGenres: false, hasMediaType: false, matchesAppName: false)
+    #expect(c.isResume)
+  }
+
+  // currentlyPlaying always resumes — "play this" makes the active track play.
+  @Test func currentlyPlaying_isResume() {
+    #expect(MediaIntentCriteria(query: "", reference: .currentlyPlaying, hasGenres: false, hasMediaType: false, matchesAppName: false).isResume)
+    // even with a stray query/filter, "play this" is a resume
+    #expect(MediaIntentCriteria(query: "jazz", reference: .currentlyPlaying, hasGenres: true, hasMediaType: true, matchesAppName: false).isResume)
+  }
+
+  // .my always searches — "play my favorites" goes to the consumer, never resume.
+  @Test func my_isNotResume() {
+    #expect(!MediaIntentCriteria(query: "", reference: .my, hasGenres: false, hasMediaType: false, matchesAppName: false).isResume)
+    #expect(!MediaIntentCriteria(query: "", reference: .my, hasGenres: false, hasMediaType: false, matchesAppName: true).isResume)
+  }
+
+  @Test func anyCriteria_isNotResume() {
+    #expect(!MediaIntentCriteria(query: "kcrw", reference: .unknown, hasGenres: false, hasMediaType: false, matchesAppName: false).isResume)
+    #expect(!MediaIntentCriteria(query: "", reference: .unknown, hasGenres: true, hasMediaType: false, matchesAppName: false).isResume)
+    #expect(!MediaIntentCriteria(query: "", reference: .unknown, hasGenres: false, hasMediaType: true, matchesAppName: false).isResume)
+  }
+
+  @Test func queryNamesApp_isResume() {
+    let c = MediaIntentCriteria(query: "Garden", reference: .unknown, hasGenres: false, hasMediaType: true, matchesAppName: true)
+    #expect(c.isResume)
+  }
+
+  @Test func queryNamesApp_withGenre_isNotResume() {
+    #expect(!MediaIntentCriteria(query: "Garden", reference: .unknown, hasGenres: true, hasMediaType: false, matchesAppName: true).isResume)
+  }
+
+  @Test func queryNotApp_isNotResume() {
+    #expect(!MediaIntentCriteria(query: "jazz", reference: .unknown, hasGenres: false, hasMediaType: false, matchesAppName: false).isResume)
+  }
+}
+
+@Suite("MediaIntentCriteria.from")
+struct MediaIntentCriteriaFromTests {
+  private func from(
+    mediaName: String? = nil,
+    genreNames: [String] = [],
+    artistName: String? = nil,
+    albumName: String? = nil,
+    mediaTypeMode: String? = nil,
+    reference: MediaIntentCriteria.Reference = .unknown,
+    hasMediaType: Bool = false,
+    appName: String? = "Radio Garden",
+  ) -> MediaIntentCriteria {
+    MediaIntentCriteria.from(
+      mediaName: mediaName, genreNames: genreNames, artistName: artistName,
+      albumName: albumName, mediaTypeMode: mediaTypeMode,
+      reference: reference, hasMediaType: hasMediaType, appName: appName,
+    )
+  }
+
+  // MARK: resume vs search
+
+  @Test func playAppName_resumes() {
+    let c = from(mediaName: "Garden", hasMediaType: true)
+    #expect(c.query == "Garden")
+    #expect(c.matchesAppName)
+    #expect(c.isResume)
+  }
+
+  @Test func emptyIntent_resumes() {
+    let c = from()
+    #expect(c.query == "")
+    #expect(c.isResume)
+  }
+
+  @Test func playMyFavorites_searches() {
+    let c = from(reference: .my)
+    #expect(!c.isResume)
+    #expect(c.reference == .my)
+  }
+
+  @Test func stationName_searches() {
+    let c = from(mediaName: "KCRW")
+    #expect(c.query == "KCRW")
+    #expect(!c.matchesAppName)
+    #expect(!c.isResume)
+    #expect(c.searchMode == nil)
+  }
+
+  // MARK: mode comes ONLY from mediaTypeMode (no field-derivation)
+
+  // "Play jazz" → genre is a FILTER, not a mode. mode stays nil; genre set.
+  @Test func genre_isFilterNotMode() {
+    let c = from(genreNames: ["jazz"], hasMediaType: true)
+    #expect(c.query == "jazz")
+    #expect(c.searchMode == nil)
+    #expect(c.genre == "jazz")
+    #expect(c.hasGenres)
+    #expect(!c.isResume)
+  }
+
+  @Test func multiWordGenre_joined_noMode() {
+    let c = from(mediaName: "   ", genreNames: ["classic", "rock"])
+    #expect(c.query == "classic rock")
+    #expect(c.genre == "classic rock")
+    #expect(c.searchMode == nil)
+  }
+
+  @Test func artist_isFilterNotMode() {
+    let c = from(artistName: "Michael Jackson")
+    #expect(c.query == "Michael Jackson")
+    #expect(c.searchMode == nil)
+    #expect(c.artist == "Michael Jackson")
+    #expect(!c.isResume)
+  }
+
+  @Test func albumAndArtist_areFiltersNotMode() {
+    let c = from(mediaName: "Thriller", artistName: "Michael Jackson", albumName: "Thriller")
+    #expect(c.searchMode == nil)
+    #expect(c.album == "Thriller")
+    #expect(c.artist == "Michael Jackson")
+    #expect(!c.query.isEmpty)
+  }
+
+  // A vertical mediaType DOES set the mode, and travels with its filters.
+  @Test func song_viaMediaTypeMode_setsTitle() {
+    let c = from(mediaName: "Billie Jean", mediaTypeMode: "song")
+    #expect(c.query == "Billie Jean")
+    #expect(c.searchMode == "song")
+    #expect(c.title == "Billie Jean")
+    #expect(c.playlist == nil)
+  }
+
+  @Test func playlist_viaMediaTypeMode_setsPlaylist() {
+    let c = from(mediaName: "Workout", mediaTypeMode: "playlist")
+    #expect(c.query == "Workout")
+    #expect(c.searchMode == "playlist")
+    #expect(c.playlist == "Workout")
+    #expect(c.title == nil)
+  }
+
+  // "Play jazz station" → vertical wins as mode; genre rides as a filter.
+  @Test func station_withGenreFilter() {
+    let c = from(genreNames: ["jazz"], mediaTypeMode: "station", hasMediaType: true)
+    #expect(c.searchMode == "station")
+    #expect(c.genre == "jazz")
+  }
+
+  @Test func podcast_setsMode() {
+    let c = from(mediaName: "Serial", mediaTypeMode: "podcast", hasMediaType: true)
+    #expect(c.searchMode == "podcast")
+    #expect(c.query == "Serial")
+  }
+
+  @Test func plainName_hasNoStructuredFields() {
+    let c = from(mediaName: "KCRW")
+    #expect(c.searchMode == nil)
+    #expect(c.genre == nil)
+    #expect(c.artist == nil)
+    #expect(c.album == nil)
+  }
+}

package/ios/Tests/MediaLoaderAssetOptionsTests.swift

@@ -0,0 +1,46 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("buildAssetOptions")
+struct BuildAssetOptionsTests {
+  private func headerFields(_ options: [String: Any]?) -> [String: String]? {
+    options?["AVURLAssetHTTPHeaderFieldsKey"] as? [String: String]
+  }
+
+  @Test func userAgentOnly_setsUserAgentHeader() {
+    let options = MediaLoader.buildAssetOptions(headers: nil, userAgent: "TestAgent/1.0")
+    #expect(headerFields(options)?["User-Agent"] == "TestAgent/1.0")
+  }
+
+  @Test func userAgentMergedWithHeaders() {
+    let options = MediaLoader.buildAssetOptions(
+      headers: ["X-Test": "1"], userAgent: "TestAgent/1.0",
+    )
+    #expect(headerFields(options)?["X-Test"] == "1")
+    #expect(headerFields(options)?["User-Agent"] == "TestAgent/1.0")
+  }
+
+  @Test func explicitUserAgentHeaderWins() {
+    let options = MediaLoader.buildAssetOptions(
+      headers: ["User-Agent": "Explicit"], userAgent: "TestAgent/1.0",
+    )
+    #expect(headerFields(options)?["User-Agent"] == "Explicit")
+  }
+
+  @Test func headersOnly_nilUserAgent_keepsHeaders() {
+    let options = MediaLoader.buildAssetOptions(headers: ["X-Test": "1"], userAgent: nil)
+    #expect(headerFields(options)?["X-Test"] == "1")
+    #expect(headerFields(options)?["User-Agent"] == nil)
+  }
+
+  @Test func emptyUserAgent_notApplied() {
+    let options = MediaLoader.buildAssetOptions(headers: nil, userAgent: "")
+    #expect(options == nil)
+  }
+
+  @Test func nilUserAgentNilHeaders_returnsNil() {
+    let options = MediaLoader.buildAssetOptions(headers: nil, userAgent: nil)
+    #expect(options == nil)
+  }
+}

package/ios/Tests/MediaLoaderTests.swift

@@ -68,6 +68,21 @@ struct MediaLoaderInitialStateTests {
   }
 }
 
+// MARK: - loadAsset
+
+@Suite("loadAsset")
+@MainActor
+struct LoadAssetTests {
+  /// A silent return here stranded the player: reload-from-terminal has
+  /// already transitioned to .loading, so no-oping leaves a spinner forever
+  /// with no load in flight and no error.
+  @Test func withoutResolvedUrl_reportsError() {
+    let (loader, spy) = makeLoader()
+    loader.loadAsset()
+    #expect(spy.playbackErrors.count == 1)
+  }
+}
+
 // MARK: - resolveAndLoad
 
 @Suite("resolveAndLoad")
@@ -77,7 +92,7 @@ struct ResolveAndLoadTests {
     let (loader, spy) = makeLoader()
     loader.resolveAndLoad(src: "")
     #expect(spy.playbackErrors.count == 1)
-    if case .invalidSourceUrl(let url) = spy.playbackErrors.first {
+    if case let .invalidSourceUrl(url) = spy.playbackErrors.first {
       #expect(url == "")
     } else {
       Issue.record("expected .invalidSourceUrl, got \(String(describing: spy.playbackErrors.first))")
@@ -102,34 +117,30 @@ struct ResolveAndLoadTests {
   @Test func withResolver_callsResolver() async {
     let (loader, _) = makeLoader()
     var resolverCalled = false
-    loader.mediaUrlResolver = { src in
+    loader.mediaUrlResolver = { src, _ in
       resolverCalled = true
       return MediaResolvedUrl(url: src, headers: nil, userAgent: nil)
     }
     loader.resolveAndLoad(src: "https://example.com/audio.mp3")
 
-    // Allow the resolver task to run
-    await Task.yield()
+    await loader.mediaResolverTask?.value
 
     #expect(resolverCalled == true)
   }
 
   @Test func withResolver_returningInvalidUrl_callsErrorDelegate() async {
     let (loader, spy) = makeLoader()
-    loader.mediaUrlResolver = { _ in
+    loader.mediaUrlResolver = { _, _ in
       MediaResolvedUrl(url: "", headers: nil, userAgent: nil)
     }
     loader.resolveAndLoad(src: "https://example.com/audio.mp3")
 
-    // The resolver runs in a Task that awaits the resolver then does MainActor.run,
-    // so we need multiple yields for the full chain to settle.
-    for _ in 0..<10 {
-      await Task.yield()
-      if !spy.playbackErrors.isEmpty { break }
-    }
+    // The task awaits the resolver then hops back to the main actor, so the
+    // delegate call has landed by the time the task itself completes.
+    await loader.mediaResolverTask?.value
 
     #expect(spy.playbackErrors.count == 1)
-    if case .invalidSourceUrl(let url) = spy.playbackErrors.first {
+    if case let .invalidSourceUrl(url) = spy.playbackErrors.first {
       #expect(url == "")
     } else {
       Issue.record("expected .invalidSourceUrl")
@@ -139,7 +150,7 @@ struct ResolveAndLoadTests {
   @Test func cancelsPreviousResolverTask() async {
     let (loader, _) = makeLoader()
     var callCount = 0
-    loader.mediaUrlResolver = { src in
+    loader.mediaUrlResolver = { src, _ in
       callCount += 1
       // Simulate slow resolution
       try? await Task.sleep(for: .milliseconds(100))
@@ -151,8 +162,8 @@ struct ResolveAndLoadTests {
     // Immediately start second — should cancel first
     loader.resolveAndLoad(src: "https://example.com/second.mp3")
 
-    // Wait for both to settle
-    try? await Task.sleep(for: .milliseconds(200))
+    // Await the surviving task; the cancelled one bailed before its resolver.
+    await loader.mediaResolverTask?.value
 
     // Only the second resolver should have run (first was cancelled before calling resolver)
     #expect(callCount == 1)
@@ -168,15 +179,16 @@ struct ResolveAndLoadTests {
 struct CancelAllTests {
   @Test func preventsDelegateCallbacksAfterResolveAndLoad() async {
     let (loader, spy) = makeLoader()
-    loader.mediaUrlResolver = { src in
+    loader.mediaUrlResolver = { src, _ in
       try? await Task.sleep(for: .milliseconds(50))
       return MediaResolvedUrl(url: src, headers: nil, userAgent: nil)
     }
     loader.resolveAndLoad(src: "https://example.com/audio.mp3")
+    // cancelAll() drops the handle, so grab it first to await the point where
+    // the callback would have fired.
+    let resolve = loader.mediaResolverTask
     loader.cancelAll()
-
-    // Wait for what would have been the callback
-    try? await Task.sleep(for: .milliseconds(100))
+    await resolve?.value
 
     #expect(spy.preparedItems.isEmpty)
     #expect(spy.playbackErrors.isEmpty)
@@ -214,7 +226,7 @@ struct AsyncLoadingTests {
     loader.resolveAndLoad(src: "file:///nonexistent/path.mp3")
 
     // Poll for delegate callback — asset loading is async
-    for _ in 0..<50 {
+    for _ in 0 ..< 50 {
       if !spy.retryableErrors.isEmpty || !spy.playbackErrors.isEmpty || !spy.preparedItems.isEmpty {
         break
       }

package/ios/Tests/MediaResolveTests.swift

@@ -0,0 +1,126 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+/// Tests for the media `resolve` layer composition: the variant unwrap (sync vs
+/// async arm) and the override-wins merge that layers the resolved config over
+/// the base. These mirror what `BrowserManager.resolveMediaTrackConfig` +
+/// `mergeRequestConfig` do in production, exercised here against the pure
+/// `MediaResolveComposer` (which the Nitro path delegates to / duplicates).
+@Suite("MediaResolve")
+struct MediaResolveTests {
+  typealias Config = MediaResolveComposer.RequestConfigLike
+
+  // MARK: - Variant unwrap
+
+  @Test("sync (.first) arm yields its config directly")
+  func unwrapSync() async throws {
+    let config = Config(userAgent: "RESOLVED")
+    let result = try await MediaResolveComposer.unwrap(.sync(config))
+    #expect(result == config)
+  }
+
+  @Test("async (.second) arm awaits and yields its config")
+  func unwrapAsync() async throws {
+    let config = Config(userAgent: "RESOLVED-ASYNC")
+    let result = try await MediaResolveComposer.unwrap(
+      .async {
+        // Simulate the Promise<RequestConfig> resolving after a hop.
+        await Task.yield()
+        return config
+      },
+    )
+    #expect(result == config)
+  }
+
+  @Test("async arm propagates errors (rejected promise)")
+  func unwrapAsyncThrows() async {
+    struct Boom: Error {}
+    await #expect(throws: Boom.self) {
+      _ = try await MediaResolveComposer.unwrap(
+        .async { throw Boom() } as MediaResolveComposer.ResolveVariant<Config>,
+      )
+    }
+  }
+
+  // MARK: - Merge as the final layer
+
+  @Test("resolve userAgent overrides base while keeping baseUrl and path")
+  func mergeOverridesUserAgent() {
+    let base = Config(path: "/audio.mp3", baseUrl: "https://base.example.com", userAgent: "BASE")
+    let resolve = Config(userAgent: "RESOLVED")
+
+    let merged = MediaResolveComposer.merge(base: base, override: resolve)
+
+    #expect(merged.userAgent == "RESOLVED")
+    #expect(merged.baseUrl == "https://base.example.com")
+    #expect(merged.path == "/audio.mp3")
+  }
+
+  @Test("async resolve result merges identically once unwrapped")
+  func mergeAfterAsyncUnwrap() async throws {
+    let base = Config(path: "/audio.mp3", baseUrl: "https://base.example.com", userAgent: "BASE")
+    let resolved = try await MediaResolveComposer.unwrap(
+      .async { Config(userAgent: "RESOLVED-ASYNC") },
+    )
+
+    let merged = MediaResolveComposer.merge(base: base, override: resolved)
+
+    #expect(merged.userAgent == "RESOLVED-ASYNC")
+    #expect(merged.baseUrl == "https://base.example.com")
+    #expect(merged.path == "/audio.mp3")
+  }
+
+  @Test("absent resolve is a no-op (base is returned unchanged)")
+  func absentResolveIsNoOp() {
+    let base = Config(path: "/audio.mp3", baseUrl: "https://base.example.com", userAgent: "BASE")
+
+    // Production guards `resolve == nil` and returns base untouched; modelled as
+    // merging an all-nil override, which must leave every field intact.
+    let merged = MediaResolveComposer.merge(base: base, override: Config())
+
+    #expect(merged == base)
+  }
+
+  @Test("headers and query merge per-key with override winning")
+  func mergeDictsPerKey() {
+    let base = Config(
+      headers: ["User-Agent": "BASE", "X-Base": "1"],
+      query: ["a": "1"],
+    )
+    let resolve = Config(
+      headers: ["User-Agent": "RESOLVED", "X-Resolve": "2"],
+      query: ["b": "2"],
+    )
+
+    let merged = MediaResolveComposer.merge(base: base, override: resolve)
+
+    #expect(merged.headers == ["User-Agent": "RESOLVED", "X-Base": "1", "X-Resolve": "2"])
+    #expect(merged.query == ["a": "1", "b": "2"])
+  }
+
+  @Test("mergeDicts is nil-safe on either side")
+  func mergeDictsNilSafe() {
+    #expect(MediaResolveComposer.mergeDicts(nil, nil) == nil)
+    #expect(MediaResolveComposer.mergeDicts(["a": "1"], nil) == ["a": "1"])
+    #expect(MediaResolveComposer.mergeDicts(nil, ["b": "2"]) == ["b": "2"])
+  }
+
+  // MARK: - Run-both resolve composition
+
+  @Test("resolve composition merges async then sync (sync wins); nil when neither")
+  func composeResolved() {
+    // Same `combine` production uses (mergeRequestConfig), here over the test type.
+    let combine: (Config, Config) -> Config = { MediaResolveComposer.merge(base: $0, override: $1) }
+    #expect(MediaResolveComposer.composeResolved(async: nil, sync: nil, combine: combine) == nil)
+
+    let a = Config(baseUrl: "https://async.example.com", userAgent: "ASYNC")
+    let s = Config(userAgent: "SYNC")
+    let merged = MediaResolveComposer.composeResolved(async: a, sync: s, combine: combine)
+    #expect(merged?.userAgent == "SYNC") // sync wins
+    #expect(merged?.baseUrl == "https://async.example.com") // async's baseUrl survives
+
+    #expect(MediaResolveComposer.composeResolved(async: a, sync: nil, combine: combine)?.userAgent == "ASYNC")
+    #expect(MediaResolveComposer.composeResolved(async: nil, sync: s, combine: combine)?.userAgent == "SYNC")
+  }
+}