react-native-audio-browser 0.2.0-next.12 → 0.2.0-next.14

package/ios/Player/NowPlayingUpdater.swift

@@ -30,17 +30,51 @@ final class NowPlayingUpdater {
     let album: String?
   }
 
+  /// Dedupe baseline for `applyFields`. Only meaningful while it describes the
+  /// controller's current info dict, so the two are cleared together in
+  /// `clearNowPlaying()` — never separately.
   private var lastPublished: Published?
 
+  /// Empties the now-playing surface and the dedupe baseline that describes it.
+  /// One call, because clearing the dict without the baseline makes the next
+  /// publish of the SAME track dedupe against a dict that no longer holds it —
+  /// artwork lands (never deduped) but the text doesn't, and `onChanged`
+  /// never fires.
+  func clearNowPlaying() {
+    nowPlayingInfoController.clear()
+    lastPublished = nil
+    formattedTrackId = nil
+  }
+
   /// Bumped on every `render`; an async formatter result applies only if its render is still the
   /// latest (latest-render-wins — drops a result whose track skipped or whose state moved on while
   /// the formatter was in flight).
   private var renderGeneration: UInt = 0
 
+  /// The track whose *formatted* line is currently on the surface. While this
+  /// matches the rendering track, `render` skips its interim default write — see
+  /// the comment at that site. Cleared whenever the surface stops showing a
+  /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
+  private var formattedTrackId: String?
+
   init(nowPlayingInfoController: NowPlayingInfoController) {
     self.nowPlayingInfoController = nowPlayingInfoController
   }
 
+  /// Pixel width to request now-playing artwork at: the active scene's screen
+  /// width in pixels, capped at `maxArtworkPixelWidth`. With no foreground
+  /// scene (headless CarPlay) the cap stands in — every current device exceeds
+  /// it anyway, and this only sizes a CDN request.
+  private static var artworkPixelWidth: CGFloat {
+    guard let screen = UIApplication.shared.activeWindowScene?.screen else {
+      return maxArtworkPixelWidth
+    }
+    return min(screen.bounds.width * screen.scale, maxArtworkPixelWidth)
+  }
+
+  /// Mirrored by the Kotlin twin's `artworkSizePx`.
+  private static let maxArtworkPixelWidth: CGFloat = 1200
+
   /// Publishes the static, per-track fields + artwork on a track change. The title/artist/album
   /// lines are owned by `render` (routed through `applyFields` here so it dedupes against later
   /// renders).
@@ -75,6 +109,8 @@ final class NowPlayingUpdater {
     let defaultSecondary = override?.artist ?? track.artist
     let defaultAlbum = override?.album ?? track.album
 
+    let trackId = track.identity ?? track.path
+
     if let flash {
       applyFields(
         track: track,
@@ -82,10 +118,22 @@ final class NowPlayingUpdater {
         artist: flash.artist ?? defaultSecondary,
         album: flash.album ?? defaultAlbum,
       )
+      // The flash replaced the formatter's line, so the surface no longer shows
+      // one: the render that follows the flash reverting must publish the default
+      // immediately rather than sit on stale flash text awaiting the formatter.
+      formattedTrackId = nil
       return
     }
 
-    applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    // Publish the raw default only while no formatter result is on screen for this
+    // track. `render` runs on EVERY playback transition (state change, playing/
+    // buffering flip, timed-metadata tick, connectivity change); writing the
+    // default each time would flash the track title over the formatter's line
+    // until the async result lands, since the two differ by construction on a live
+    // stream (station name vs. song line).
+    if formatter == nil || formattedTrackId != trackId {
+      applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    }
 
     guard let formatter else { return }
     let params = FormatNowPlayingParams(
@@ -111,6 +159,9 @@ final class NowPlayingUpdater {
             artist: formatted.artist ?? defaultSecondary,
             album: formatted.album ?? defaultAlbum,
           )
+          // A formatter result now owns the surface for this track, so later
+          // renders skip the interim default write.
+          self.formattedTrackId = trackId
         }
       }
       .catch { @Sendable [weak self] error in
@@ -152,10 +203,7 @@ final class NowPlayingUpdater {
     let artworkUrl = track.artworkSource?.uri ?? track.artwork?.url
     logger.debug("loadArtwork: \(track.title), artworkUrl: \(artworkUrl ?? "nil")")
 
-    // Now Playing artwork: use screen width in pixels, capped at 1200px
-    let screenScale = UIScreen.main.scale
-    let screenWidth = UIScreen.main.bounds.width * screenScale
-    let artworkSize = min(screenWidth, 1200)
+    let artworkSize = Self.artworkPixelWidth
     let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
 
     artworkLoadTask?.cancel()

package/ios/Player/PlaybackCoordinator.swift

@@ -526,14 +526,21 @@ class PlaybackCoordinator {
         let changed = queue.add([track], initialIndex: 0)
         if changed { handleCurrentTrackChanged() }
       } else {
-        queue.replace(queue.currentIndex, track)
-        handleCurrentTrackChanged()
+        // `currentIndex` is invariantly -1 or in bounds, and -1 took the branch
+        // above, so this cannot fail — but surface it rather than reloading the
+        // old track if that invariant is ever broken.
+        do {
+          try queue.replace(queue.currentIndex, track)
+          handleCurrentTrackChanged()
+        } catch {
+          logger.error("load: replace at \(self.queue.currentIndex) failed: \(error)")
+        }
       }
     }
   }
 
-  func replace(_ index: Int, _ track: Track) {
-    queue.replace(index, track)
+  func replace(_ index: Int, _ track: Track) throws {
+    try queue.replace(index, track)
   }
 
   func setQueue(

package/ios/Player/PlaybackTimer.swift

@@ -48,10 +48,16 @@ final class PlaybackTimer {
 
   private func start(_ interval: TimeInterval) {
     guard timer == nil else { return }
-    timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) {
-      [weak self] _ in
+    // `.common`, not the `.default` mode `Timer.scheduledTimer` installs: UIKit
+    // runs the main run loop in tracking mode while a list is being dragged, and
+    // a default-mode timer does not fire there. Missed repeats are dropped rather
+    // than replayed, so progress events would freeze and interval ticks would be
+    // lost for as long as the user scrolls. (VolumeFader already does this.)
+    let timer = Timer(timeInterval: interval, repeats: true) { [weak self] _ in
       MainActor.assumeIsolated { self?.onTick() }
     }
+    self.timer = timer
+    RunLoop.main.add(timer, forMode: .common)
   }
 
   private func stop() {

package/ios/Player/QueueManager.swift

@@ -225,11 +225,8 @@ class QueueManager {
     let wasEmpty = tracks.isEmpty
     let insertIndex = tracks.count
     tracks.append(contentsOf: newTracks)
+    if wasEmpty { return adoptInitialCurrent(initialIndex) }
     shuffleOrder.insert(at: insertIndex, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = max(0, min(initialIndex, tracks.count - 1))
-      return true
-    }
     return false
   }
 
@@ -250,14 +247,31 @@ class QueueManager {
       currentIndex += newTracks.count
     }
     tracks.insert(contentsOf: newTracks, at: index)
+    if wasEmpty { return adoptInitialCurrent(0) }
     shuffleOrder.insert(at: index, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = 0
-      return true
-    }
     return false
   }
 
+  /// The queue was empty: `index` becomes the current track AND leads the
+  /// shuffle order. One operation because the two must not be separable —
+  /// forgetting the second half is the bug this exists to prevent.
+  ///
+  /// `insert(at:count:)` drops new indices at *random* shuffle positions, so
+  /// without the pin the starting track can land last in the order, which reads
+  /// as `isLastInPlaybackOrder`: the queue "ends" (and fires
+  /// `playerDidEndQueue`) the moment the first track finishes. Pins
+  /// unconditionally, like `setQueue` — the order has to be sane whether or not
+  /// shuffle is on right now, since `shuffleEnabled`'s didSet only re-pins on
+  /// the off→on edge.
+  ///
+  /// Returns true, so callers can `return adoptInitialCurrent(…)` to report the
+  /// current track changed.
+  private func adoptInitialCurrent(_ index: Int) -> Bool {
+    currentIndex = max(0, min(index, tracks.count - 1))
+    shuffleOrder = ShuffleOrder(length: tracks.count, firstIndex: currentIndex)
+    return true
+  }
+
   /// Remove a track from the queue.
   /// Returns `true` if the current track changed.
   @discardableResult
@@ -288,8 +302,18 @@ class QueueManager {
     let insertion = min(newTracks.count, toIndex)
     newTracks.insert(track, at: insertion)
     tracks = newTracks
+    // Carry the moved track's shuffle position across the move. `insert(at:count:)`
+    // would drop it at a RANDOM position instead — reordering the queue would then
+    // silently reorder shuffled playback, and moving the playing track could land it
+    // last in the order, ending the queue at the next track boundary with tracks
+    // still unplayed (the failure `adoptInitialCurrent` guards against elsewhere).
+    // `remove` shifts every later position down by one, so re-inserting at the
+    // captured position restores the exact prior order.
+    let shufflePosition = shuffleOrder.shufflePosition(of: fromIndex)
     shuffleOrder.remove(from: fromIndex, to: fromIndex + 1)
-    shuffleOrder.insert(at: insertion, count: 1)
+    shuffleOrder.insert(
+      at: insertion, atShufflePosition: shufflePosition ?? shuffleOrder.count,
+    )
     // The pointer follows the playing track; its identity never changes on a
     // move, so no caller needs to reload (returning true reloads).
     if currentIndex == fromIndex {
@@ -317,7 +341,9 @@ class QueueManager {
   // MARK: - Other Mutations
 
   /// Replace the track at a specific index.
-  func replace(_ index: Int, _ track: Track) {
+  /// Throws like every other index-taking mutation here, rather than trapping.
+  func replace(_ index: Int, _ track: Track) throws {
+    try throwIfIndexInvalid(index: index)
     tracks[index] = track
   }
 

package/ios/Player/ShuffleOrder.swift

@@ -101,6 +101,13 @@ struct ShuffleOrder {
     return indexInShuffled[index] == 0
   }
 
+  /// The item's position in the shuffle order, or nil when it has none.
+  func shufflePosition(of index: Int) -> Int? {
+    guard index >= 0, index < indexInShuffled.count else { return nil }
+    let position = indexInShuffled[index]
+    return position >= 0 ? position : nil
+  }
+
   // MARK: - Mutation
 
   /// Inserts items at random positions in the shuffle order
@@ -125,6 +132,22 @@ struct ShuffleOrder {
     indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
   }
 
+  /// Inserts one item at `insertionIndex`, placing it at an explicit shuffle
+  /// position rather than a random one.
+  ///
+  /// Used by a queue `move`, which permutes positions but not identities: the
+  /// item already had a place in the playback order, and re-randomising it
+  /// silently reorders playback. For the *playing* track it can drop it at the
+  /// end of the order, which then reads as `isLastInPlaybackOrder` — the queue
+  /// reports itself over at the next track end, with tracks still unplayed.
+  mutating func insert(at insertionIndex: Int, atShufflePosition position: Int) {
+    for i in 0 ..< shuffled.count where shuffled[i] >= insertionIndex {
+      shuffled[i] += 1
+    }
+    shuffled.insert(insertionIndex, at: min(max(0, position), shuffled.count))
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
   /// Removes items in the specified range from the shuffle order
   mutating func remove(from indexFrom: Int, to indexToExclusive: Int) {
     let removeCount = indexToExclusive - indexFrom

package/ios/Player/SleepTimerHandling.swift

@@ -12,4 +12,17 @@ import Foundation
   @discardableResult func clear() -> Bool
   func onTrackChanged()
   func onTrackPlayedToEnd()
+
+  // Consumer-facing surface — HybridAudioBrowser drives these through
+  // TrackPlayer, so they belong here rather than behind a concrete downcast.
+
+  /// Invoked when the timer state changes (set, cleared, completed).
+  var onChanged: ((SleepTimerState) -> Void)? { get set }
+  /// The current timer state, or nil when no timer is active.
+  func get() -> SleepTimerState?
+  /// Sets a time-based timer, optionally fading out over the last
+  /// `fadeDuration` seconds.
+  func set(seconds: TimeInterval, fadeDuration: TimeInterval?)
+  /// Sets the timer to stop playback when the current track ends.
+  func setToEndOfTrack()
 }

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -281,24 +281,59 @@ class RemoteCommandController {
 
   // MARK: - Handlers
 
-  lazy var handlePlayCommand: RemoteCommandHandler = handlePlayCommandDefault
-  lazy var handlePauseCommand: RemoteCommandHandler = handlePauseCommandDefault
-  lazy var handleStopCommand: RemoteCommandHandler = handleStopCommandDefault
-  lazy var handleTogglePlayPauseCommand: RemoteCommandHandler =
-    handleTogglePlayPauseCommandDefault
-  lazy var handleSkipForwardCommand: RemoteCommandHandler = handleSkipForwardCommandDefault
-  lazy var handleSkipBackwardCommand: RemoteCommandHandler = handleSkipBackwardDefault
-  lazy var handleChangePlaybackPositionCommand: RemoteCommandHandler =
-    handleChangePlaybackPositionCommandDefault
-  lazy var handleNextTrackCommand: RemoteCommandHandler = handleNextTrackCommandDefault
-  lazy var handlePreviousTrackCommand: RemoteCommandHandler =
-    handlePreviousTrackCommandDefault
-  lazy var handleChangeRepeatModeCommand: RemoteCommandHandler =
-    handleChangeRepeatModeCommandDefault
-  lazy var handleChangeShuffleModeCommand: RemoteCommandHandler =
-    handleChangeShuffleModeCommandDefault
-  lazy var handleChangePlaybackRateCommand: RemoteCommandHandler =
-    handleChangePlaybackRateCommandDefault
+  // Each default is wrapped in a `[weak self]` closure rather than assigned as a
+  // bare method reference (`= handlePlayCommandDefault`): an unapplied instance
+  // method curries to `{ [self] in self.method($0) }`, which strongly captures
+  // self. Stored back onto self, that is a permanent cycle — `enable(command:)`
+  // forces every lazy init, so the controller would never deallocate, leaking one
+  // per player instance across JS reloads and re-setups.
+  lazy var handlePlayCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePlayCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handlePauseCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePauseCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleStopCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleStopCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleTogglePlayPauseCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleTogglePlayPauseCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleSkipForwardCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleSkipForwardCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleSkipBackwardCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleSkipBackwardDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangePlaybackPositionCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangePlaybackPositionCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleNextTrackCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleNextTrackCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handlePreviousTrackCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePreviousTrackCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangeRepeatModeCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangeRepeatModeCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangeShuffleModeCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangeShuffleModeCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangePlaybackRateCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangePlaybackRateCommandDefault(event: event) ?? .commandFailed
+  }
 
   private func handlePlayCommandDefault(event _: MPRemoteCommandEvent)
     -> MPRemoteCommandHandlerStatus

package/ios/Tests/InertStyleDiagnosticTests.swift

@@ -0,0 +1,200 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+// The dev diagnostic for declarations that can never render (ADR 0011): the
+// recovery for the compile-time invalid-combination errors the block model
+// deliberately gave up. Structural inertness only — a surface that can't draw
+// a property it understands is intended usage, never a finding.
+
+@Suite("InertStyleDiagnostic")
+struct InertStyleDiagnosticTests {
+  private func findings(
+    _ sections: [Section], page: SectionStyle? = nil, path: String = "/home",
+  ) -> [String] {
+    InertStyleDiagnostic.findings(path: path, pageStyle: page, sections: sections)
+  }
+
+  private func playable(_ src: String = "https://s/a.mp3", style: TrackStyle? = nil) -> Track {
+    Track(src: src, title: "T", style: style)
+  }
+
+  private func browsable(_ path: String = "/albums/1", style: TrackStyle? = nil) -> Track {
+    Track(path: path, title: "T", style: style)
+  }
+
+  // MARK: - Container properties
+
+  @Test func gridWrapOnAListSectionIsInert() {
+    let found = findings([Section(title: "Recent", style: SectionStyle(gridWrap: false), children: [])])
+    #expect(found.count == 1)
+    #expect(found[0].contains("section 'Recent'"))
+    #expect(found[0].contains("style.gridWrap"))
+    #expect(found[0].contains("display 'list'"))
+    #expect(found[0].contains("/home"))
+  }
+
+  @Test func gridWrapInAGridIsLive() {
+    let style = SectionStyle(gridWrap: false, display: .grid)
+    #expect(findings([Section(style: style, children: [])]).isEmpty)
+  }
+
+  @Test func aSectionInheritsThePagesGridDisplay() {
+    // `display` resolves by scope override, so the page's grid makes the
+    // section's `gridWrap` live without the section restating it.
+    let found = findings(
+      [Section(style: SectionStyle(gridWrap: false), children: [])],
+      page: SectionStyle(display: .grid),
+    )
+    #expect(found.isEmpty)
+  }
+
+  @Test func gridTileOnAListSectionIsInert() {
+    let found = findings([Section(style: SectionStyle(gridTile: .card), children: [])])
+    #expect(found.count == 1)
+    #expect(found[0].contains("style.gridTile"))
+    #expect(found[0].contains("section #1"))
+  }
+
+  // MARK: - Item properties
+
+  @Test func cardPropertiesNeedTheCardTreatment() {
+    let plainGrid = SectionStyle(display: .grid, cardTint: "#1e3a8a", cardImage: .background)
+    let found = findings([Section(title: "Featured", style: plainGrid, children: [])])
+    #expect(found.count == 2)
+    #expect(found.contains { $0.contains("style.cardTint") })
+    #expect(found.contains { $0.contains("style.cardImage") })
+    #expect(found.allSatisfy { $0.contains("display 'grid', gridTile 'plain'") })
+  }
+
+  @Test func cardPropertiesInACardGridAreLive() {
+    let cards = SectionStyle(gridTile: .card, display: .grid, cardTint: "#1e3a8a", cardImage: .background)
+    #expect(findings([Section(style: cards, children: [])]).isEmpty)
+  }
+
+  @Test func imageShapeNeedsAShapedTile() {
+    let list = SectionStyle(imageShape: .circular)
+    let cards = SectionStyle(gridTile: .card, display: .grid, imageShape: .circular)
+    let condensed = SectionStyle(gridTile: .condensed, display: .grid, imageShape: .circular)
+    #expect(findings([Section(style: list, children: [])]).count == 1)
+    #expect(findings([Section(style: cards, children: [])]).count == 1)
+    // Plain and condensed tiles both take a shape.
+    #expect(findings([Section(style: condensed, children: [])]).isEmpty)
+  }
+
+  @Test func accessorySymbolIsInertOnlyOnCards() {
+    let rows = SectionStyle(accessorySymbol: "lock.fill")
+    let cards = SectionStyle(gridTile: .card, display: .grid, accessorySymbol: "lock.fill")
+    // List rows draw accessories; card elements have no slot for one.
+    #expect(findings([Section(style: rows, children: [])]).isEmpty)
+    let found = findings([Section(style: cards, children: [])])
+    #expect(found.count == 1)
+    #expect(found[0].contains("no accessory slot"))
+  }
+
+  @Test func artworkRenderingIsNeverInert() {
+    let stencilled = SectionStyle(gridTile: .card, display: .grid, artworkRendering: .stencil)
+    #expect(findings([Section(style: stencilled, children: [])]).isEmpty)
+  }
+
+  // MARK: - Track-level declarations
+
+  @Test func trackDeclarationsAreReportedPerSection() {
+    let section = Section(
+      title: "Results", style: SectionStyle(display: .grid),
+      children: [
+        playable(style: TrackStyle(cardTint: "#111")),
+        playable("https://s/b.mp3", style: TrackStyle(cardTint: "#222")),
+        playable("https://s/c.mp3"),
+      ],
+    )
+    let found = findings([section])
+    #expect(found.count == 1)
+    #expect(found[0].contains("2 tracks in section 'Results'"))
+    #expect(found[0].contains("style.cardTint"))
+  }
+
+  @Test func aTracksOwnShapeIsLiveInAPlainGrid() {
+    let section = Section(
+      style: SectionStyle(display: .grid),
+      children: [playable(style: TrackStyle(imageShape: .circular))],
+    )
+    #expect(findings([section]).isEmpty)
+  }
+
+  // MARK: - The page block
+
+  @Test func aPageDeclarationLiveInOneSectionIsNotReported() {
+    // Card tint reaches both sections; one renders cards. Live is live.
+    let found = findings(
+      [
+        Section(style: SectionStyle(gridTile: .card, display: .grid), children: []),
+        Section(style: SectionStyle(display: .grid), children: []),
+      ],
+      page: SectionStyle(cardTint: "#1e3a8a"),
+    )
+    #expect(found.isEmpty)
+  }
+
+  @Test func aPageDeclarationNoSectionRendersIsReportedOnce() {
+    let found = findings(
+      [
+        Section(title: "A", style: SectionStyle(display: .grid), children: []),
+        Section(title: "B", children: []),
+      ],
+      page: SectionStyle(cardTint: "#1e3a8a"),
+    )
+    #expect(found.count == 1)
+    #expect(found[0].contains("the page block"))
+    #expect(found[0].contains("no section that inherits it"))
+  }
+
+  @Test func aSectionOverrideShadowsThePageValue() {
+    // Every section declares its own tint, so the page's is never resolved —
+    // shadowed, not inert; the diagnostic reports what can't render, not what
+    // isn't reached.
+    let found = findings(
+      [Section(style: SectionStyle(gridTile: .card, display: .grid, cardTint: "#000"), children: [])],
+      page: SectionStyle(cardTint: "#1e3a8a"),
+    )
+    #expect(found.isEmpty)
+  }
+
+  @Test func aPageWideGridMakesSectionDeclarationsLive() {
+    let found = findings(
+      [Section(style: SectionStyle(cardTint: "#111"), children: [])],
+      page: SectionStyle(gridTile: .card, display: .grid),
+    )
+    #expect(found.isEmpty)
+  }
+
+  // MARK: - The positional `display`
+
+  @Test func displayOnAPlayableTrackIsInert() {
+    let section = Section(
+      title: "Tracks",
+      children: [
+        playable(style: TrackStyle(display: .grid)),
+        browsable(style: TrackStyle(display: .grid)),
+      ],
+    )
+    let found = findings([section])
+    #expect(found.count == 1)
+    #expect(found[0].contains("1 track in section 'Tracks'"))
+    #expect(found[0].contains("style.display"))
+    #expect(found[0].contains("opens none"))
+  }
+
+  @Test func displayOnASectionOrPageIsNeverInert() {
+    let found = findings(
+      [Section(style: SectionStyle(display: .list), children: [browsable()])],
+      page: SectionStyle(display: .grid),
+    )
+    #expect(found.isEmpty)
+  }
+
+  @Test func anUnstyledPageIsSilent() {
+    #expect(findings([Section(children: [playable(), browsable()])]).isEmpty)
+    #expect(findings([]).isEmpty)
+  }
+}

package/ios/Tests/JsonModelsTests.swift

@@ -117,11 +117,70 @@ struct JsonStyleTests {
     #expect(track.disabled == true)
   }
 
+  @Test func decodesImageShapeAndAccessorySymbol() throws {
+    let json = Data(
+      """
+      {"title":"X","style":{"imageShape":"circular","accessorySymbol":"lock.fill"}}
+      """.utf8)
+    let track = try JSONDecoder().decode(JsonTrack.self, from: json).toNitro()
+    #expect(track.style?.imageShape == .circular)
+    #expect(track.style?.accessorySymbol == "lock.fill")
+  }
+
+  @Test func accessorySymbolNoneIsAValueNotEmptiness() throws {
+    // The inheritance-escape sentinel must survive the wire — collapsing it
+    // to "no declaration" would let the section value flow back in.
+    let json = Data(
+      """
+      {"title":"X","style":{"accessorySymbol":"none"}}
+      """.utf8)
+    let track = try JSONDecoder().decode(JsonTrack.self, from: json).toNitro()
+    #expect(track.style?.accessorySymbol == "none")
+  }
+
+  @Test func unknownImageShapeDecodesAsNoDeclaration() throws {
+    let json = Data(
+      """
+      {"title":"X","style":{"imageShape":"hexagonal"}}
+      """.utf8)
+    let track = try JSONDecoder().decode(JsonTrack.self, from: json).toNitro()
+    #expect(track.style == nil)
+  }
+
+  @Test func decodesTheCardFamily() throws {
+    let json = Data(
+      """
+      {"path":"/home","title":"Home","sections":[
+        {"style":{"display":"grid","gridTile":"card","cardTint":"#1e3a8a","cardImage":"background"},
+         "children":[{"title":"C","src":"s"}]}
+      ]}
+      """.utf8)
+    let resolved = try JSONDecoder().decode(JsonResolvedTrack.self, from: json).toNitro()
+    let style = resolved.sections?.first?.style
+    #expect(style?.gridTile == .card)
+    #expect(style?.cardTint == "#1e3a8a")
+    #expect(style?.cardImage == .background)
+  }
+
+  @Test func unknownGridTileDecodesAsNoDeclaration() throws {
+    let json = Data(
+      """
+      {"path":"/home","title":"Home","sections":[
+        {"style":{"gridTile":"hexagon"},"children":[{"title":"C","src":"s"}]}
+      ]}
+      """.utf8)
+    let resolved = try JSONDecoder().decode(JsonResolvedTrack.self, from: json).toNitro()
+    #expect(resolved.sections?.first?.style == nil)
+  }
+
   @Test func styleAndDisabledSurviveThePersistenceRoundTrip() throws {
     // Restored queues keep their visible fidelity across process death.
     let original = JsonTrack(
       title: "X", src: "s",
-      style: JsonStyle(display: "grid", artworkRendering: "stencil"),
+      style: JsonStyle(
+        display: "grid", artworkRendering: "stencil",
+        imageShape: "circular", accessorySymbol: "lock.fill",
+      ),
       disabled: true,
     )
     let encoded = try JSONEncoder().encode(original)
@@ -129,4 +188,20 @@ struct JsonStyleTests {
     #expect(decoded.style == original.style)
     #expect(decoded.disabled == true)
   }
+
+  @Test func liveBlockSnapshotsAllItemProperties() throws {
+    // The persistence snapshot (JsonStyle from a live TrackStyle) must not
+    // drop the newer item properties.
+    let snapshot = JsonStyle(
+      TrackStyle(
+        display: nil, artworkRendering: .stencil,
+        imageShape: .circular, accessorySymbol: "none",
+        cardTint: "#1e3a8a", cardImage: .background,
+      ))
+    #expect(snapshot?.artworkRendering == "stencil")
+    #expect(snapshot?.imageShape == "circular")
+    #expect(snapshot?.accessorySymbol == "none")
+    #expect(snapshot?.cardTint == "#1e3a8a")
+    #expect(snapshot?.cardImage == "background")
+  }
 }