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

package/android/src/test/java/com/audiobrowser/player/ShuffleOrderLedByTest.kt

@@ -0,0 +1,79 @@
+package com.audiobrowser.player
+
+import androidx.media3.common.C
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Media3's `ShuffleOrder.cloneAndSet(insertionCount, startIndex)` discards the start index (the
+ * interface default clears and re-inserts from 0, and `DefaultShuffleOrder` does not override it),
+ * so `setMediaItems(items, startIndex, …)` leaves the starting track at a random shuffle position —
+ * last, for a 1-in-N share of queues, which reads as end-of-queue from the very first track.
+ */
+class ShuffleOrderLedByTest {
+  @Test
+  fun `the start index leads the order`() {
+    for (start in 0 until 6) {
+      val order = shuffleOrderLedBy(startIndex = start, count = 6)
+      assertEquals("start index must be at shuffle position 0", start, order.firstIndex)
+      assertNotEquals(
+        "a queue of 6 must have somewhere to advance to from its start track",
+        C.INDEX_UNSET.toLong(),
+        order.getNextIndex(start).toLong(),
+      )
+    }
+  }
+
+  @Test
+  fun `every index appears exactly once`() {
+    val order = shuffleOrderLedBy(startIndex = 3, count = 8)
+    assertEquals(8, order.length)
+    val seen = mutableListOf<Int>()
+    var index = order.firstIndex
+    while (index != C.INDEX_UNSET) {
+      seen.add(index)
+      index = order.getNextIndex(index)
+    }
+    assertEquals((0 until 8).toList(), seen.sorted())
+  }
+
+  @Test
+  fun `a single-track queue leads with its only track and ends there`() {
+    val order = shuffleOrderLedBy(startIndex = 0, count = 1)
+    assertEquals(0, order.firstIndex)
+    assertEquals(C.INDEX_UNSET, order.getNextIndex(0))
+  }
+
+  @Test
+  fun `an out-of-range start index is clamped rather than throwing`() {
+    assertEquals(4, shuffleOrderLedBy(startIndex = 99, count = 5).firstIndex)
+    assertEquals(0, shuffleOrderLedBy(startIndex = -3, count = 5).firstIndex)
+  }
+
+  @Test
+  fun `an empty queue produces an empty order`() {
+    assertEquals(0, shuffleOrderLedBy(startIndex = 0, count = 0).length)
+  }
+
+  @Test
+  fun `the tail is actually shuffled`() {
+    // Not a strict guarantee of any single draw — but across many draws an
+    // unshuffled tail would be impossible to miss.
+    val tails =
+      (0 until 50)
+        .map { shuffleOrderLedBy(startIndex = 0, count = 8) }
+        .map { order ->
+          buildList {
+            var index = order.getNextIndex(order.firstIndex)
+            while (index != C.INDEX_UNSET) {
+              add(index)
+              index = order.getNextIndex(index)
+            }
+          }
+        }
+        .toSet()
+    assertTrue("50 draws produced one identical tail — the order is not shuffled", tails.size > 1)
+  }
+}

package/android/src/test/java/com/audiobrowser/util/MediaExtrasBuilderTest.kt

@@ -2,10 +2,10 @@ package com.audiobrowser.util
 
 import androidx.media.utils.MediaConstants
 import com.audiobrowser.TestFixtures
+import com.audiobrowser.TestFixtures.sectionStyle
+import com.audiobrowser.TestFixtures.trackStyle
 import com.audiobrowser.browser.styleResolvedSections
-import com.margelo.nitro.audiobrowser.SectionStyle
 import com.margelo.nitro.audiobrowser.StyleDisplay
-import com.margelo.nitro.audiobrowser.TrackStyle
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Test
@@ -23,7 +23,7 @@ class MediaExtrasBuilderTest {
   private val track = TestFixtures.track()
 
   private fun sectionStyle(display: StyleDisplay?) =
-    SectionStyle(display = display, artworkRendering = null, gridWrap = null)
+    sectionStyle(display = display, artworkRendering = null, gridWrap = null)
 
   @Test
   fun `owning section title stamps the group-title hint`() {
@@ -65,7 +65,7 @@ class MediaExtrasBuilderTest {
   @Test
   fun `a track's own display never sets its item hint - display is positional`() {
     val gridPromiseTrack =
-      track.copy(style = TrackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+      track.copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
     val section = TestFixtures.section(arrayOf(gridPromiseTrack), style = null)
     val extras = MediaExtrasBuilder.build(gridPromiseTrack, section)
     assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM))
@@ -75,7 +75,7 @@ class MediaExtrasBuilderTest {
   fun `a browsable track's declared display emits the parent-level promise`() {
     val handle =
       TestFixtures.browseTrack()
-        .copy(style = TrackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+        .copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
     val extras = MediaExtrasBuilder.build(handle)
     val expected = MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM
     assertEquals(
@@ -99,7 +99,7 @@ class MediaExtrasBuilderTest {
   @Test
   fun `a playable track's display is inert - playables open no page`() {
     val playable =
-      track.copy(style = TrackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+      track.copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
     val extras = MediaExtrasBuilder.build(playable)
     assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE))
     assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE))
@@ -128,7 +128,7 @@ class MediaExtrasBuilderTest {
         arrayOf(track),
         title = "Popular",
         path = "/popular",
-        style = SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = false),
+        style = sectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = false),
       )
     val navigation = TrackFactory.navigationTrack(section)
     assertEquals(StyleDisplay.GRID, navigation.style?.display)
@@ -147,7 +147,7 @@ class MediaExtrasBuilderTest {
     // narrower unit test stays green while the page tier goes dark.
     val page =
       TestFixtures.resolvedTrack(
-        style = SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = null),
+        style = sectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = null),
         sections = arrayOf(TestFixtures.section(arrayOf(track))),
       )
 

package/ios/Browser/BrowserManager.swift

@@ -67,8 +67,8 @@ final class BrowserManager {
   // LRU cache for resolved content - keyed by path
   private let contentCache = LRUCache<String, ResolvedTrack>(maxSize: 20)
 
-  // Cache for search results
-  private var lastSearchQuery: String?
+  // Most recent search, keyed by `searchCacheKey`.
+  private var lastSearchKey: String?
   private var lastSearchResults: [Track]?
 
   // Resolver caching: request/browse thunks resolve once per content generation.
@@ -171,8 +171,8 @@ final class BrowserManager {
   /// Optimistically reflects a local favorite toggle in the favorite set, keyed
   /// by the track's identity (id when non-blank, else src). The consumer
   /// reconciles `favoriteIds` to its canonical set on the next `setFavorites`;
-  /// `isFavorite` gives the same answer before and after, so the now-playing
-  /// heart stays responsive.
+  /// `hydrateFavorite` gives the same answer before and after, so the
+  /// now-playing heart stays responsive.
   func setFavorited(identity: String, favorited: Bool) {
     if favorited {
       favoriteIds.insert(identity)
@@ -188,13 +188,10 @@ final class BrowserManager {
   /// caller-set `favorited` wins — API/consumer-provided values are never
   /// overwritten (matches Android and web).
   func hydrateFavorite(_ track: Track) -> Track {
-    guard favoriteEnabled, track.favorited == nil, track.identity != nil else { return track }
-    return track.copying(favorited: isFavorite(track))
-  }
-
-  /// Whether the track's identity is in the favorite set.
-  private func isFavorite(_ track: Track) -> Bool {
-    track.identity.map(favoriteIds.contains) ?? false
+    // `identity` bridges a std::string out of the C++ track, so it is bound
+    // once here rather than computed again to answer "is it favorited".
+    guard favoriteEnabled, track.favorited == nil, let identity = track.identity else { return track }
+    return track.copying(favorited: favoriteIds.contains(identity))
   }
 
   /// Hydrates favorites on all tracks of a resolved page. Pages reach
@@ -221,12 +218,21 @@ final class BrowserManager {
     self.path = path
     content = nil // Clear for loading state
 
-    let resolved = try await resolve(path)
+    do {
+      let resolved = try await resolve(path)
 
-    // Only apply result if this is still the current navigation
-    guard navigationId == currentNavigationId else { return }
+      // Only apply result if this is still the current navigation
+      guard navigationId == currentNavigationId else { return }
 
-    content = resolved
+      content = resolved
+    } catch {
+      // A superseded navigation's failure is not the current page's failure.
+      // Every caller reports a throw unconditionally (and CarPlay presents it as
+      // a modal action sheet), so without this a slow /a that fails after a fast
+      // /b succeeded would show /a's error over /b's content.
+      guard navigationId == currentNavigationId else { return }
+      throw error
+    }
   }
 
   /// Resolves content for a path with optional caching.
@@ -248,7 +254,18 @@ final class BrowserManager {
   }
 
   /// Invalidates the content cache for a specific path.
-  func invalidateContentCache(_ path: String) {
+  ///
+  /// Expects a *container* path. A contextual path (`…?__trackId=…`) addresses
+  /// a child, not a cache entry — entries are keyed by the stripped parent — so
+  /// passing one used to remove nothing at all, silently. Android `require`s the
+  /// same precondition; this throws so the misuse surfaces identically on both
+  /// platforms instead of no-opping on one.
+  func invalidateContentCache(_ path: String) throws {
+    guard !BrowserPathHelper.isContextual(path) else {
+      throw BrowserError.invalidConfiguration(
+        "invalidateContentCache() expects a container path, not a contextual path: \(path)",
+      )
+    }
     contentCache.remove(path)
   }
 
@@ -257,6 +274,11 @@ final class BrowserManager {
   func clearContentCache() {
     contentCache.clear()
     layerGeneration += 1
+    // The search slot is content too: a locale switch or a re-auth changes
+    // titles, src, artwork and availability, and nothing else ever evicts it,
+    // so a repeated query returned pre-invalidation results forever.
+    lastSearchKey = nil
+    lastSearchResults = nil
   }
 
   /// Refreshes the current path by invalidating cache and re-resolving.
@@ -269,12 +291,19 @@ final class BrowserManager {
 
     let currentPath = path
     contentCache.remove(currentPath)
-    let resolved = try await resolve(currentPath, useCache: false)
 
-    // Only apply result if this is still the current navigation
-    guard navigationId == currentNavigationId else { return }
+    do {
+      let resolved = try await resolve(currentPath, useCache: false)
 
-    content = resolved
+      // Only apply result if this is still the current navigation
+      guard navigationId == currentNavigationId else { return }
+
+      content = resolved
+    } catch {
+      // Superseded refreshes stay silent, for the same reason as `navigate`.
+      guard navigationId == currentNavigationId else { return }
+      throw error
+    }
   }
 
   private func resolveUncached(_ path: String) async throws -> ResolvedTrack {
@@ -295,6 +324,10 @@ final class BrowserManager {
     // untitled section — ADR 0010), then validate and transform. The output
     // never carries `children`.
     if let sections = resolvedTrack.normalizedSections {
+      // Dev diagnostic (ADR 0011) — before the blocks are folded, while each
+      // level is still attributable. Every page passes here whatever its
+      // source, and only on a cache miss. No-op outside debug builds.
+      InertStyleDiagnostic.warn(path: path, pageStyle: resolvedTrack.style, sections: sections)
       let transformed = try await transformSections(
         sections, parentPath: path, routeEntry: routeEntry?.0,
       )
@@ -574,16 +607,49 @@ final class BrowserManager {
     )
   }
 
-  /// Structured search. Emits `q` plus any of `mode`/`genre`/`artist`/`album`/
-  /// `title`/`playlist` that are set, mirroring Android's `executeSearchApiRequest`
-  /// and the web stub. Cached by `query`.
+  /// The query params a structured search sends: `q` plus whichever filters are
+  /// set. Mirrors Android's `executeSearchApiRequest` and the web stub.
+  ///
+  /// Single source of truth for "what distinguishes one search from another" —
+  /// the request sends exactly this, and the cache keys on exactly this, so a
+  /// field added here can't be forgotten in one place and silently serve one
+  /// search's results for another.
+  private static func searchQueryParams(_ params: SearchParams) -> [String: String] {
+    var query: [String: String] = ["q": params.query]
+    if let mode = params.mode { query["mode"] = mode.stringValue }
+    if params.reference == .my { query["reference"] = "my" }
+    if let genre = params.genre { query["genre"] = genre }
+    if let artist = params.artist { query["artist"] = artist }
+    if let album = params.album { query["album"] = album }
+    if let title = params.title { query["title"] = title }
+    if let playlist = params.playlist { query["playlist"] = playlist }
+    return query
+  }
+
+  /// The cache identity of a search. Sorted so key order is stable, and
+  /// `\u{1}`-delimited so two different param sets can't serialize alike.
+  private static func searchCacheKey(_ params: SearchParams) -> String {
+    searchQueryParams(params)
+      .sorted { $0.key < $1.key }
+      .map { "\($0.key)=\($0.value)" }
+      .joined(separator: "\u{1}")
+  }
+
+  /// Structured search, cached by the full parameter set.
+  ///
+  /// Voice intents reuse `query` across different structures —
+  /// `MediaIntentCriteria` falls back to the structured value when there is no
+  /// spoken name, so "play jazz" (genre) and a text search for "jazz" arrive
+  /// with an identical `query` — hence `searchCacheKey` rather than `query`.
   func search(_ params: SearchParams) async throws -> ResolvedTrack {
     let query = params.query
+    let cacheKey = Self.searchCacheKey(params)
 
-    // Check cache - re-hydrate favorites since they may have changed
-    if query == lastSearchQuery, let results = lastSearchResults {
-      let hydratedResults = results.map { hydrateFavorite($0) }
-      return makeSearchResult(query: query, results: hydratedResults)
+    // Check cache - hydrate favorites on the way out, since they may have
+    // changed since the search ran (the slot holds the raw results for exactly
+    // this reason — see below).
+    if cacheKey == lastSearchKey, let results = lastSearchResults {
+      return makeSearchResult(query: query, results: results)
     }
 
     guard let routes = config.routes else {
@@ -608,18 +674,9 @@ final class BrowserManager {
       // Seed the search config's static path onto the base — a layer's static
       // path never applies (carried from the base; only a transform may change
       // it). Matches the web stub's fetchSearchResults and Android.
-      var queryParams: [String: String] = ["q": query]
-      if let mode = params.mode { queryParams["mode"] = mode.stringValue }
-      if params.reference == .my { queryParams["reference"] = "my" }
-      if let genre = params.genre { queryParams["genre"] = genre }
-      if let artist = params.artist { queryParams["artist"] = artist }
-      if let album = params.album { queryParams["album"] = album }
-      if let title = params.title { queryParams["title"] = title }
-      if let playlist = params.playlist { queryParams["playlist"] = playlist }
-
       let request = try await buildApiRequest(
         kind: nil, searchConfig, path: searchConfig.path ?? "", params: ["q": query],
-        initialQuery: queryParams,
+        initialQuery: Self.searchQueryParams(params),
       )
       logger.debug("Searching via API: \(request.url)")
       let jsonTracks: [JsonTrack] = try await httpClient.requestJson(request, as: [JsonTrack].self)
@@ -628,14 +685,15 @@ final class BrowserManager {
       throw BrowserError.contentNotFound(path: Self.searchRoutePath)
     }
 
-    // Hydrate favorites in results
-    let hydratedResults = results.map { hydrateFavorite($0) }
-
-    // Cache results
-    lastSearchQuery = query
-    lastSearchResults = hydratedResults
+    // Cache the RAW results, never the hydrated ones: hydration is one-shot
+    // (`hydrateFavorite` skips a track whose `favorited` is already set), so a
+    // hydrated slot would serve the favorites as they were at first search
+    // forever. The content cache keys on the same rule — it stores the
+    // unhydrated resolve and hydrates in `resolve()`.
+    lastSearchKey = cacheKey
+    lastSearchResults = results
 
-    return makeSearchResult(query: query, results: hydratedResults)
+    return makeSearchResult(query: query, results: results)
   }
 
   /// Search and return playable tracks for "play «X»" voice intents, drilling
@@ -653,13 +711,16 @@ final class BrowserManager {
     }
   }
 
+  /// Wraps raw search results as a resolved page, hydrating favorites on the
+  /// way out — the single exit for `search`, so an unhydrated search page can't
+  /// be emitted (the same funnel `resolve()` gets from `hydrateChildren`).
   private func makeSearchResult(query: String, results: [Track]) -> ResolvedTrack {
     // Search results are a flat list; as a resolved page they are one
     // untitled section (ADR 0010).
     ResolvedTrack(
       path: BrowserPathHelper.createSearchPath(query),
       style: nil,
-      sections: [.untitled(results)],
+      sections: [.untitled(results.map { hydrateFavorite($0) })],
       children: nil,
       carPlaySiriListButton: nil,
       id: nil,

package/ios/Browser/InertStyleDiagnostic.swift

@@ -0,0 +1,279 @@
+import os.log
+
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// Dev diagnostic (ADR 0011): the declarations on a resolved page that can
+/// never render.
+///
+/// The block model deliberately gave up compile-time invalid-combination
+/// errors — combinations are not invalid, they are *inert*, the way
+/// `grid-template` on a non-grid element is inert in CSS. This is the
+/// recovery: at page resolution every declaration its own block makes
+/// unreadable is reported once, with the effective context and the fix.
+///
+/// The line it draws, and never crosses: only **structural** inertness — a
+/// declaration the resolved block itself renders unreadable, on every surface
+/// (`gridWrap` outside a grid, `cardTint` with no card treatment in scope).
+/// *Surface* inertness is never reported, because declarations are
+/// aspirational: `imageShape` on Android Auto, or a card treatment on a
+/// pre-26 CarPlay, is intended usage — the renderer drops what it can't draw.
+///
+/// Runs where every page passes regardless of its source (static config,
+/// route callback, or fetched browse JSON), and only on a cache miss, so a
+/// mistake is reported once per resolution rather than once per serve.
+///
+/// Debug builds only: `warn` is the whole seam, so a release build never even
+/// walks the page (the trade is that a page served only to a Release build —
+/// TestFlight, production browse JSON — reports nothing; reproduce it against
+/// a debug build).
+enum InertStyleDiagnostic {
+  /// Reports every inert declaration on a resolved page. The one gate — the
+  /// `#if` is here rather than at the call sites so callers read
+  /// unconditionally and the rule set stays free of build-configuration
+  /// knowledge.
+  static func warn(path: String, pageStyle: SectionStyle?, sections: [Section]) {
+    #if DEBUG
+      let logger = Logger(subsystem: "com.audiobrowser", category: "InertStyleDiagnostic")
+      for finding in findings(path: path, pageStyle: pageStyle, sections: sections) {
+        logger.warning("\(finding, privacy: .public)")
+      }
+    #endif
+  }
+
+  /// The declarations that carry a structural inertness condition.
+  ///
+  /// Two keys of the block are deliberately absent — `display` and
+  /// `artworkRendering`, dispositioned below instead.
+  private enum Property: String, CaseIterable {
+    case gridWrap
+    case gridTile
+    case imageShape
+    case accessorySymbol
+    case cardTint
+    case cardImage
+
+    /// Item properties inherit (`track ?? section ?? page`) and so may also
+    /// be declared per track; container properties resolve by scope override
+    /// (`section ?? page`) and never reach an item.
+    var isItemProperty: Bool {
+      switch self {
+      case .gridWrap, .gridTile: false
+      case .imageShape, .accessorySymbol, .cardTint, .cardImage: true
+      }
+    }
+
+    /// Whether a value of this property, resolved into `context`, has any
+    /// rendering to affect. Each case is the spec's own "inert unless" clause.
+    func isInert(in context: Context) -> Bool {
+      switch self {
+      case .gridWrap, .gridTile: !context.isGrid
+      case .imageShape: !context.isGrid || context.isCard
+      case .accessorySymbol: context.isCard
+      case .cardTint, .cardImage: !context.isCard
+      }
+    }
+
+    /// The rule the declaration falls foul of, stated positively.
+    var rule: String {
+      switch self {
+      case .gridWrap, .gridTile: "`\(rawValue)` renders only in a grid"
+      case .imageShape: "only plain and condensed tiles have a shape"
+      case .accessorySymbol: "card tiles have no accessory slot"
+      case .cardTint, .cardImage: "the card properties render only under `gridTile: 'card'`"
+      }
+    }
+
+    var hint: String {
+      switch self {
+      case .gridWrap, .gridTile:
+        "Declare `display: 'grid'` on the section or the page, or drop `\(rawValue)`."
+      case .imageShape:
+        "Render the items as plain or condensed grid tiles, or drop `imageShape`."
+      case .accessorySymbol:
+        "Use `gridTile: 'plain'` or `'condensed'`, or drop `accessorySymbol`."
+      case .cardTint, .cardImage:
+        "Declare `display: 'grid'` with `gridTile: 'card'`, or drop `\(rawValue)`."
+      }
+    }
+  }
+
+  /// Iterated per section; `allCases` is computed, so read it once.
+  private static let allProperties = Property.allCases
+
+  /// The rest of the block's keys, dispositioned rather than ruled on:
+  /// `artworkRendering` has no structural inertness condition (artwork renders
+  /// in every layout), and `display` is positional — inert only in the one
+  /// position that opens no page (see `playableDisplayFinding`). Declared here
+  /// so the spec-level completeness test can hold this file to the whole
+  /// vocabulary: every key of the block is a rule, always renderable, or
+  /// positional, and a newly added property is a decision rather than an
+  /// omission.
+  static let alwaysRenderable = ["artworkRendering"]
+  static let positional = ["display"]
+
+  /// A section's effective container context: the two container values every
+  /// inertness condition is stated against.
+  private struct Context {
+    let isGrid: Bool
+    let tile: GridTile
+
+    /// Folded through `StyleResolver` rather than re-deriving the scope
+    /// override: the diagnostic predicts what a renderer will do with these
+    /// declarations, so it has to resolve them the way the renderers do.
+    init(section: SectionStyle?, page: SectionStyle?) {
+      let folded = StyleResolver.sectionStyle(section: section, page: page)
+      isGrid = folded.display == .grid
+      tile = folded.gridTile ?? .plain
+    }
+
+    /// Whether the card treatment is what this container renders — the
+    /// condition the `card*` family is named after.
+    var isCard: Bool { isGrid && tile == .card }
+
+    /// The effective style, for the message — in the wire spelling the author
+    /// types (`stringValue` is the generated enum's own mapping). `gridTile`
+    /// is quoted only where a grid gives it meaning: naming it on a list would
+    /// be advice to fix the wrong property.
+    var described: String {
+      isGrid ? "display 'grid', gridTile '\(tile.stringValue)'" : "display 'list'"
+    }
+  }
+
+  /// Every inert declaration on a resolved page, as ready-to-log messages —
+  /// pure, so the whole rule set is testable off-device; the caller logs.
+  ///
+  /// - Parameters:
+  ///   - path: the resolved path, named in every message.
+  ///   - pageStyle: the page's own block (`ResolvedTrack.style`).
+  ///   - sections: the page's normalized sections, blocks *unfolded* — the
+  ///     diagnostic attributes each finding to the level that declared it, so
+  ///     it must see the levels before `StyleResolver` merges them.
+  static func findings(path: String, pageStyle: SectionStyle?, sections: [Section]) -> [String] {
+    var findings: [String] = []
+    // A page-level declaration is judged across the whole page: it is live if
+    // it renders in any section it reaches, however many others ignore it.
+    var pageReached: Set<Property> = []
+    var pageRendered: Set<Property> = []
+
+    for (index, section) in sections.enumerated() {
+      let context = Context(section: section.style, page: pageStyle)
+      let sectionLabel = label(section, index: index)
+
+      for property in allProperties {
+        let inert = property.isInert(in: context)
+
+        if declared(property, in: section.style) {
+          if inert {
+            findings.append(
+              message(
+                property, path: path, owner: sectionLabel,
+                scope: "its effective style is \(context.described)",
+              ))
+          }
+        } else if declared(property, in: pageStyle) {
+          // The section takes the page's value (nothing closer overrode it).
+          pageReached.insert(property)
+          if !inert { pageRendered.insert(property) }
+        }
+
+        guard property.isItemProperty, inert else { continue }
+        let tracks = section.children.count(where: { declared(property, in: $0.style) })
+        if tracks > 0 {
+          findings.append(
+            message(
+              property, path: path, owner: "\(trackCount(tracks)) in \(sectionLabel)",
+              scope: "the section's effective style is \(context.described)",
+            ))
+        }
+      }
+
+      if let finding = playableDisplayFinding(section, path: path, label: sectionLabel) {
+        findings.append(finding)
+      }
+    }
+
+    for property in allProperties
+      where pageReached.contains(property) && !pageRendered.contains(property)
+    {
+      findings.append(
+        message(
+          property, path: path, owner: "the page block",
+          scope: "no section that inherits it renders one",
+        ))
+    }
+
+    return findings
+  }
+
+  /// `display` is positional, so it is never inert *in* a container — but on
+  /// a track that renders playable (`src` wins the rendering) it promises the
+  /// layout of a page that never opens.
+  private static func playableDisplayFinding(
+    _ section: Section, path: String, label: String,
+  ) -> String? {
+    let tracks = section.children.count(where: { $0.src != nil && $0.style?.display != nil })
+    guard tracks > 0 else { return nil }
+    return message(
+      path: path, owner: "\(trackCount(tracks)) in \(label)", key: "display",
+      reason: "`display` is the layout promise for the page a track opens, and a track "
+        + "rendered playable opens none",
+      hint: "Drop `display`, or give the track a `path` if it should be browsable.",
+    )
+  }
+
+  private static func message(
+    _ property: Property, path: String, owner: String, scope: String,
+  ) -> String {
+    message(
+      path: path, owner: owner, key: property.rawValue,
+      reason: "\(property.rule), but \(scope)", hint: property.hint,
+    )
+  }
+
+  /// The one message skeleton — every finding names the page, the declaration,
+  /// who declared it, why it can't render, and what to do about it.
+  private static func message(
+    path: String, owner: String, key: String, reason: String, hint: String,
+  ) -> String {
+    "Inert style declaration on page '\(path)': `style.\(key)` on \(owner) "
+      + "never renders — \(reason). \(hint)"
+  }
+
+  private static func label(_ section: Section, index: Int) -> String {
+    if let title = section.title, !title.isEmpty { return "section '\(title)'" }
+    return "section #\(index + 1)"
+  }
+
+  private static func trackCount(_ count: Int) -> String {
+    "\(count) track\(count == 1 ? "" : "s")"
+  }
+
+  // Nitro flattens the spec's `extends`, so the two blocks share no type —
+  // hence two lookups over the same key set rather than one protocol.
+
+  private static func declared(_ property: Property, in style: SectionStyle?) -> Bool {
+    guard let style else { return false }
+    switch property {
+    case .gridWrap: return style.gridWrap != nil
+    case .gridTile: return style.gridTile != nil
+    case .imageShape: return style.imageShape != nil
+    case .accessorySymbol: return style.accessorySymbol != nil
+    case .cardTint: return style.cardTint != nil
+    case .cardImage: return style.cardImage != nil
+    }
+  }
+
+  private static func declared(_ property: Property, in style: TrackStyle?) -> Bool {
+    guard let style else { return false }
+    switch property {
+    // Container properties have no Track slot to be declared in.
+    case .gridWrap, .gridTile: return false
+    case .imageShape: return style.imageShape != nil
+    case .accessorySymbol: return style.accessorySymbol != nil
+    case .cardTint: return style.cardTint != nil
+    case .cardImage: return style.cardImage != nil
+    }
+  }
+}