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

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -46,11 +46,24 @@ class RemoteCommandController {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "RemoteCommandController")
   private var center: MPRemoteCommandCenter
 
-  weak var callbacks: TrackPlayerCallbacks?
+  weak var callbacks: RemoteCommandCallbacks?
 
   var commandTargetPointers: [String: Any] = [:]
   private var enabledCommands: [RemoteCommand] = []
 
+  /// Whether there's a next/previous track to skip to. Stored so it survives
+  /// command (re)enable and iOS-16 command-center switches; the next/previous
+  /// commands are enabled in this state rather than unconditionally.
+  private var canNext = true
+  private var canPrevious = true
+
+  /// Shuffle/repeat display state, stored so it survives a command-center switch
+  /// (iOS-16 MPNowPlayingSession re-creation). A new center defaults these to
+  /// off; without re-applying, the CarPlay/lock-screen shuffle & repeat buttons
+  /// flash off on every switch.
+  private var shuffleEnabled = false
+  private var repeatMode: RepeatMode = .off
+
   /**
    Create a new RemoteCommandController.
 
@@ -59,7 +72,7 @@ class RemoteCommandController {
    */
   init(
     remoteCommandCenter: MPRemoteCommandCenter = MPRemoteCommandCenter.shared(),
-    callbacks: TrackPlayerCallbacks? = nil,
+    callbacks: RemoteCommandCallbacks? = nil,
   ) {
     center = remoteCommandCenter
     self.callbacks = callbacks
@@ -90,17 +103,25 @@ class RemoteCommandController {
     // Re-enable commands on the new center
     enable(commands: commandsToReEnable)
 
+    // Restore shuffle/repeat display state — the new center defaults them to off,
+    // so without this the shuffle & repeat buttons flash off on every switch.
+    center.changeShuffleModeCommand.currentShuffleType = shuffleEnabled.mpShuffleType
+    center.changeRepeatModeCommand.currentRepeatType = repeatMode.mpRepeatType
+
     logger.info("Switched command center, re-enabled \(commandsToReEnable.count) commands")
   }
 
   func enable(commands: [RemoteCommand]) {
-    let commandsToDisable = enabledCommands.filter { command in
-      !commands.contains(command)
-    }
+    let commandsToDisable = RemoteCommand.commandsToDisable(
+      enabled: enabledCommands, replacedBy: commands,
+    )
 
     enabledCommands = commands
-    commands.forEach { self.enable(command: $0) }
+    // Disable first. The key diff already makes the two sets disjoint, so this
+    // is belt-and-braces: it keeps a disable from tearing down a command the
+    // enable pass just configured should the two ever overlap again.
     disable(commands: commandsToDisable)
+    commands.forEach { self.enable(command: $0) }
   }
 
   func disable(commands: [RemoteCommand]) {
@@ -156,12 +177,14 @@ class RemoteCommandController {
         key: command.key,
         handler: handleNextTrackCommand,
       )
+      center.nextTrackCommand.isEnabled = canNext
     case .previous:
       enableRemoteCommand(
         center.previousTrackCommand,
         key: command.key,
         handler: handlePreviousTrackCommand,
       )
+      center.previousTrackCommand.isEnabled = canPrevious
     case .changePlaybackPosition:
       enableRemoteCommand(
         center.changePlaybackPositionCommand,
@@ -182,11 +205,6 @@ class RemoteCommandController {
         key: command.key,
         handler: handleSkipBackwardCommand,
       )
-    case let .like(isActive, localizedTitle, localizedShortTitle):
-      center.likeCommand.isActive = isActive
-      center.likeCommand.localizedTitle = localizedTitle
-      center.likeCommand.localizedShortTitle = localizedShortTitle
-      enableRemoteCommand(center.likeCommand, key: command.key, handler: handleLikeCommand)
     case .changeRepeatMode:
       enableRemoteCommand(
         center.changeRepeatModeCommand,
@@ -229,8 +247,6 @@ class RemoteCommandController {
       disableRemoteCommand(center.skipForwardCommand, key: command.key)
     case .skipBackward:
       disableRemoteCommand(center.skipBackwardCommand, key: command.key)
-    case .like:
-      disableRemoteCommand(center.likeCommand, key: command.key)
     case .changeRepeatMode:
       disableRemoteCommand(center.changeRepeatModeCommand, key: command.key)
     case .changeShuffleMode:
@@ -244,14 +260,25 @@ class RemoteCommandController {
 
   /// Updates the repeat mode state shown on CarPlay and lock screen
   func updateRepeatMode(_ mode: RepeatMode) {
+    repeatMode = mode
     center.changeRepeatModeCommand.currentRepeatType = mode.mpRepeatType
   }
 
   /// Updates the shuffle mode state shown on CarPlay and lock screen
   func updateShuffleMode(_ enabled: Bool) {
+    shuffleEnabled = enabled
     center.changeShuffleModeCommand.currentShuffleType = enabled.mpShuffleType
   }
 
+  /// Greys out next/previous (lock screen / Control Center / CarPlay) when the
+  /// queue has nowhere to skip. Applied live when those commands are configured.
+  func setSkipAvailability(canNext: Bool, canPrevious: Bool) {
+    self.canNext = canNext
+    self.canPrevious = canPrevious
+    if enabledCommands.contains(.next) { center.nextTrackCommand.isEnabled = canNext }
+    if enabledCommands.contains(.previous) { center.previousTrackCommand.isEnabled = canPrevious }
+  }
+
   // MARK: - Handlers
 
   lazy var handlePlayCommand: RemoteCommandHandler = handlePlayCommandDefault
@@ -266,7 +293,6 @@ class RemoteCommandController {
   lazy var handleNextTrackCommand: RemoteCommandHandler = handleNextTrackCommandDefault
   lazy var handlePreviousTrackCommand: RemoteCommandHandler =
     handlePreviousTrackCommandDefault
-  lazy var handleLikeCommand: RemoteCommandHandler = handleLikeCommandDefault
   lazy var handleChangeRepeatModeCommand: RemoteCommandHandler =
     handleChangeRepeatModeCommandDefault
   lazy var handleChangeShuffleModeCommand: RemoteCommandHandler =
@@ -352,13 +378,6 @@ class RemoteCommandController {
     return MPRemoteCommandHandlerStatus.success
   }
 
-  private func handleLikeCommandDefault(event _: MPRemoteCommandEvent)
-    -> MPRemoteCommandHandlerStatus
-  {
-    callbacks?.remoteLike()
-    return MPRemoteCommandHandlerStatus.success
-  }
-
   private func handleChangeRepeatModeCommandDefault(event: MPRemoteCommandEvent)
     -> MPRemoteCommandHandlerStatus
   {

package/ios/Tests/AirPlayStallJudgementTests.swift

@@ -0,0 +1,52 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("AirPlayStallJudgement")
+struct AirPlayStallJudgementTests {
+  /// The exact transition Pocket Casts recovers from: over AirPlay, AVPlayer
+  /// drops .waitingToPlayAtSpecifiedRate(.noItemToPlay) → .paused while still
+  /// meant to play. That, and only that, should nudge.
+  private func judge(
+    previous: PlayerTimeControlStatus? = .waitingToPlayAtSpecifiedRate,
+    current: PlayerTimeControlStatus = .paused,
+    reasonWasNoItemToPlay: Bool = true,
+    isAirPlay: Bool = true,
+    playWhenReady: Bool = true,
+  ) -> AirPlayStallJudgement {
+    AirPlayStallJudgement(
+      previous: previous,
+      current: current,
+      previousWaitingReasonWasNoItemToPlay: reasonWasNoItemToPlay,
+      isAirPlay: isAirPlay,
+      playWhenReady: playWhenReady,
+    )
+  }
+
+  @Test func exactTransition_nudges() {
+    #expect(judge().shouldNudge)
+  }
+
+  @Test func notAirPlay_doesNotNudge() {
+    #expect(!judge(isAirPlay: false).shouldNudge)
+  }
+
+  @Test func notPlayWhenReady_doesNotNudge() {
+    #expect(!judge(playWhenReady: false).shouldNudge)
+  }
+
+  @Test func previousNotWaiting_doesNotNudge() {
+    #expect(!judge(previous: .playing).shouldNudge)
+    #expect(!judge(previous: nil).shouldNudge)
+  }
+
+  @Test func currentNotPaused_doesNotNudge() {
+    #expect(!judge(current: .playing).shouldNudge)
+    #expect(!judge(current: .waitingToPlayAtSpecifiedRate).shouldNudge)
+  }
+
+  @Test func reasonNotNoItemToPlay_doesNotNudge() {
+    // A normal stall (.toMinimizeStalls etc.) landing in paused isn't the bug.
+    #expect(!judge(reasonWasNoItemToPlay: false).shouldNudge)
+  }
+}

package/ios/Tests/BrowserPathHelperTests.swift

@@ -29,6 +29,14 @@ import Testing
   #expect(result == "http://example.com/api")
 }
 
+@Test func buildUrlEmptyPathReturnsBaseWithoutTrailingSlash() {
+  // An endpoint whose baseUrl already includes the full path (e.g. search,
+  // `https://host/api/search`) passes an empty path — the base IS the URL, and
+  // must not gain a dangling trailing slash.
+  let result = BrowserPathHelper.buildUrl(baseUrl: "http://example.com/api/search", path: "")
+  #expect(result == "http://example.com/api/search")
+}
+
 // MARK: - appendQuery
 
 @Test func appendQueryAddsParamsWithQuestionMark() {
@@ -108,3 +116,23 @@ import Testing
 @Test func isContextualReturnsTrueWithAmpersandSeparator() {
   #expect(BrowserPathHelper.isContextual("/lib?q=1&__trackId=x") == true)
 }
+
+// MARK: - containsSegment
+
+@Test func containsSegmentMatchesFullSegments() {
+  let path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
+  #expect(BrowserPathHelper.containsSegment(path, "Gw0LGB8j"))
+  #expect(BrowserPathHelper.containsSegment(path, "amsterdam-funk-channel"))
+  #expect(BrowserPathHelper.containsSegment(path, "listen"))
+  #expect(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j?hl=en", "Gw0LGB8j"))
+  #expect(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j#frag", "Gw0LGB8j"))
+}
+
+@Test func containsSegmentRejectsPartialAndMissing() {
+  let path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
+  #expect(!BrowserPathHelper.containsSegment(path, "Gw0LGB8"))
+  #expect(!BrowserPathHelper.containsSegment(path, "funk"))
+  #expect(!BrowserPathHelper.containsSegment(path, "msterdam-funk-channe"))
+  #expect(!BrowserPathHelper.containsSegment(path, "NopeNope"))
+  #expect(!BrowserPathHelper.containsSegment(path, ""))
+}

package/ios/Tests/CarPlayArtworkResolverTests.swift

@@ -13,7 +13,7 @@ struct SFSymbolTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .sfSymbol(artwork: "sf:heart.fill", width: 40, height: 40))
   }
@@ -25,7 +25,7 @@ struct SFSymbolTests {
       artworkCarPlayTinted: nil,
       targetWidth: 24, targetHeight: 24,
       displayScale: 3.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .sfSymbol(artwork: "sf:play.circle?bg=#000&fg=#fff", width: 24, height: 24))
   }
@@ -41,7 +41,7 @@ struct SFSymbolTests {
       urlResolver: { _, _ in
         resolverCalled = true
         return ArtworkResolvedImage(uri: "https://example.com/img.jpg", headers: nil)
-      }
+      },
     )
     #expect(action == .sfSymbol(artwork: "sf:music.note", width: 40, height: 40))
     #expect(!resolverCalled)
@@ -54,7 +54,7 @@ struct SFSymbolTests {
       artworkCarPlayTinted: nil,
       targetWidth: 20, targetHeight: 20,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .sfSymbol(artwork: "sf:star.fill", width: 20, height: 20))
   }
@@ -71,7 +71,7 @@ struct NoArtworkTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .none)
   }
@@ -83,7 +83,7 @@ struct NoArtworkTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: { _, _ in nil }
+      urlResolver: { _, _ in nil },
     )
     #expect(action == .none)
   }
@@ -105,15 +105,15 @@ struct URLResolutionTests {
         #expect(pixelHeight == 80)
         return ArtworkResolvedImage(
           uri: "https://cdn.example.com/art_80x80.jpg",
-          headers: ["Authorization": "Bearer token"]
+          headers: ["Authorization": "Bearer token"],
         )
-      }
+      },
     )
     #expect(action == .fetch(
       uri: "https://cdn.example.com/art_80x80.jpg",
       headers: ["Authorization": "Bearer token"],
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -126,13 +126,13 @@ struct URLResolutionTests {
       displayScale: 3.0,
       urlResolver: { _, _ in
         ArtworkResolvedImage(uri: "https://cdn.example.com/resized.jpg", headers: nil)
-      }
+      },
     )
     #expect(action == .fetch(
       uri: "https://cdn.example.com/resized.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -143,13 +143,13 @@ struct URLResolutionTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: { _, _ in nil }
+      urlResolver: { _, _ in nil },
     )
     #expect(action == .fetch(
       uri: "https://example.com/art.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -163,14 +163,14 @@ struct URLResolutionTests {
       urlResolver: { _, _ in
         // Return an invalid URI that URL(string:) would reject
         ArtworkResolvedImage(uri: "", headers: nil)
-      }
+      },
     )
     // Should fall back to direct artwork URL
     #expect(action == .fetch(
       uri: "https://example.com/fallback.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -187,7 +187,7 @@ struct URLResolutionTests {
         receivedWidth = w
         receivedHeight = h
         return ArtworkResolvedImage(uri: "https://cdn.example.com/art.jpg", headers: nil)
-      }
+      },
     )
     #expect(receivedWidth == 125) // 50 * 2.5
     #expect(receivedHeight == 75) // 30 * 2.5
@@ -205,13 +205,13 @@ struct DirectFallbackTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/artwork.png",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -222,13 +222,13 @@ struct DirectFallbackTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/source.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -239,13 +239,13 @@ struct DirectFallbackTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/artwork.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -256,7 +256,7 @@ struct DirectFallbackTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .none)
   }
@@ -273,13 +273,13 @@ struct SVGDetectionTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/icon.svg",
       headers: nil,
       shouldTint: false,
-      isSvg: true
+      isSvg: true,
     ))
   }
 
@@ -290,13 +290,13 @@ struct SVGDetectionTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/icon.SVG",
       headers: nil,
       shouldTint: false,
-      isSvg: true
+      isSvg: true,
     ))
   }
 
@@ -309,13 +309,13 @@ struct SVGDetectionTests {
       displayScale: 2.0,
       urlResolver: { _, _ in
         ArtworkResolvedImage(uri: "https://cdn.example.com/icon.svg", headers: nil)
-      }
+      },
     )
     #expect(action == .fetch(
       uri: "https://cdn.example.com/icon.svg",
       headers: nil,
       shouldTint: false,
-      isSvg: true
+      isSvg: true,
     ))
   }
 
@@ -326,13 +326,13 @@ struct SVGDetectionTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/photo.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 }
@@ -348,13 +348,13 @@ struct TintingTests {
       artworkCarPlayTinted: true,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/icon.png",
       headers: nil,
       shouldTint: true,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -365,13 +365,13 @@ struct TintingTests {
       artworkCarPlayTinted: false,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/photo.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -382,13 +382,13 @@ struct TintingTests {
       artworkCarPlayTinted: nil,
       targetWidth: 40, targetHeight: 40,
       displayScale: 2.0,
-      urlResolver: nil
+      urlResolver: nil,
     )
     #expect(action == .fetch(
       uri: "https://example.com/photo.jpg",
       headers: nil,
       shouldTint: false,
-      isSvg: false
+      isSvg: false,
     ))
   }
 
@@ -401,13 +401,13 @@ struct TintingTests {
       displayScale: 2.0,
       urlResolver: { _, _ in
         ArtworkResolvedImage(uri: "https://cdn.example.com/icon.png", headers: nil)
-      }
+      },
     )
     #expect(action == .fetch(
       uri: "https://cdn.example.com/icon.png",
       headers: nil,
       shouldTint: true,
-      isSvg: false
+      isSvg: false,
     ))
   }
 }

package/ios/Tests/ChapterMetadataAVFoundationTests.swift

@@ -10,11 +10,11 @@ import Testing
 private func makeTimedMetadataGroup(
   start: Double,
   duration: Double,
-  title: String? = nil
+  title: String? = nil,
 ) -> AVTimedMetadataGroup {
   let timeRange = CMTimeRange(
     start: CMTime(seconds: start, preferredTimescale: 1000),
-    duration: CMTime(seconds: duration, preferredTimescale: 1000)
+    duration: CMTime(seconds: duration, preferredTimescale: 1000),
   )
 
   var items: [AVMetadataItem] = []

package/ios/Tests/EndOfTrackJudgementTests.swift

@@ -0,0 +1,35 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("EndOfTrackJudgement")
+struct EndOfTrackJudgementTests {
+  // Live streams are infinite — an end-of-item is always a dropped connection,
+  // never a real end, regardless of the reported position/duration.
+  @Test func live_isAlwaysStalled() {
+    #expect(EndOfTrackJudgement(isLive: true, currentTime: 0, duration: 0).outcome == .stalled)
+    #expect(EndOfTrackJudgement(isLive: true, currentTime: 100, duration: 100).outcome == .stalled)
+    #expect(EndOfTrackJudgement(isLive: true, currentTime: 5, duration: .nan).outcome == .stalled)
+  }
+
+  // On-demand reaching the end is a genuine finish.
+  @Test func onDemand_atEnd_isEnded() {
+    #expect(EndOfTrackJudgement(isLive: false, currentTime: 300, duration: 300).outcome == .ended)
+  }
+
+  // Within the 5% tail still counts as a real finish (decoder rarely lands exactly).
+  @Test func onDemand_withinFivePercentOfEnd_isEnded() {
+    #expect(EndOfTrackJudgement(isLive: false, currentTime: 291, duration: 300).outcome == .ended)
+  }
+
+  // More than 5% short of the end → a mid-stream stall reported as EOF.
+  @Test func onDemand_wellShortOfEnd_isStalled() {
+    #expect(EndOfTrackJudgement(isLive: false, currentTime: 120, duration: 300).outcome == .stalled)
+  }
+
+  // Unknown/indefinite duration can't be validated — trust the notification.
+  @Test func onDemand_indefiniteDuration_isEnded() {
+    #expect(EndOfTrackJudgement(isLive: false, currentTime: 0, duration: .nan).outcome == .ended)
+    #expect(EndOfTrackJudgement(isLive: false, currentTime: 0, duration: 0).outcome == .ended)
+  }
+}

package/ios/Tests/JsonModelsTests.swift

@@ -0,0 +1,58 @@
+@testable import AudioBrowserTestable
+import Foundation
+import Testing
+
+@Suite("JsonTrack.request")
+struct JsonTrackRequestTests {
+  @Test func decodesRequestOntoTrack() throws {
+    let json = """
+    { "title": "X", "src": "/s", "request": { "userAgent": "UA-X",
+      "headers": { "Referer": "https://e.example" }, "query": { "t": "1" } } }
+    """.data(using: .utf8)!
+    let jsonTrack = try JSONDecoder().decode(JsonTrack.self, from: json)
+    let track = jsonTrack.toNitro()
+    #expect(track.request?.userAgent == "UA-X")
+    #expect(track.request?.headers?["Referer"] == "https://e.example")
+    #expect(track.request?.query?["t"] == "1")
+  }
+}
+
+@Suite("JsonTrack.artwork")
+struct JsonTrackArtworkTests {
+  @Test func decodesASingleUrl() throws {
+    let json = #"{ "title": "X", "artwork": "https://e.example/a.png" }"#.data(using: .utf8)!
+    let track = try JSONDecoder().decode(JsonTrack.self, from: json).toNitro()
+    #expect(track.artwork == .first("https://e.example/a.png"))
+  }
+
+  @Test func decodesAPerAppearancePair() throws {
+    let json = """
+    { "title": "X", "artwork": { "light": "https://e.example/l.png", "dark": "https://e.example/d.png" } }
+    """.data(using: .utf8)!
+    let track = try JSONDecoder().decode(JsonTrack.self, from: json).toNitro()
+    #expect(track.artwork?.variants?.light == "https://e.example/l.png")
+    #expect(track.artwork?.variants?.dark == "https://e.example/d.png")
+    // Callers that cannot express appearance get the dark one.
+    #expect(track.artwork?.url == "https://e.example/d.png")
+  }
+
+  @Test func decodesAPairNestedInChildren() throws {
+    // The shape that shipped broken: a container decodes its children eagerly,
+    // so one unparseable row rejected the whole page rather than losing an image.
+    let json = """
+    { "url": "/favorites", "title": "Favorites", "children": [
+      { "title": "Playlist", "artwork": { "light": "https://e.example/l.png", "dark": "https://e.example/d.png" } }
+    ] }
+    """.data(using: .utf8)!
+    let resolved = try JSONDecoder().decode(JsonResolvedTrack.self, from: json).toNitro()
+    #expect(resolved.children?.first?.artwork?.variants?.dark == "https://e.example/d.png")
+  }
+
+  @Test func roundTripsBothShapes() throws {
+    for artwork: JsonArtwork in [.single("a.png"), .variants(light: "l.png", dark: "d.png")] {
+      let encoded = try JSONEncoder().encode(JsonTrack(title: "X", artwork: artwork))
+      let decoded = try JSONDecoder().decode(JsonTrack.self, from: encoded)
+      #expect(decoded.artwork == artwork)
+    }
+  }
+}