react-native-audio-browser 0.2.0-next.53 → 0.2.0-next.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (599) hide show
  1. package/README.md +32 -19
  2. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +8 -10
  3. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +96 -243
  4. package/android/src/main/java/com/audiobrowser/AudioBrowserLifecycleModule.kt +8 -12
  5. package/android/src/main/java/com/audiobrowser/AudioBrowserPackage.kt +1 -3
  6. package/android/src/main/java/com/audiobrowser/Callbacks.kt +1 -10
  7. package/android/src/main/java/com/audiobrowser/ForegroundStart.kt +13 -18
  8. package/android/src/main/java/com/audiobrowser/HeadlessTaskService.kt +3 -7
  9. package/android/src/main/java/com/audiobrowser/RemoteOutputs.kt +8 -10
  10. package/android/src/main/java/com/audiobrowser/Service.kt +20 -61
  11. package/android/src/main/java/com/audiobrowser/ServiceBinding.kt +9 -17
  12. package/android/src/main/java/com/audiobrowser/browser/ArtworkResolutionRegistry.kt +10 -9
  13. package/android/src/main/java/com/audiobrowser/browser/BrowseArtworkRegistry.kt +11 -8
  14. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +117 -448
  15. package/android/src/main/java/com/audiobrowser/browser/BrowserUrlResolution.kt +21 -60
  16. package/android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt +20 -80
  17. package/android/src/main/java/com/audiobrowser/browser/JsonArtwork.kt +6 -10
  18. package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt +7 -24
  19. package/android/src/main/java/com/audiobrowser/browser/RouteMatch.kt +2 -4
  20. package/android/src/main/java/com/audiobrowser/browser/SectionScope.kt +13 -31
  21. package/android/src/main/java/com/audiobrowser/browser/SimpleRouter.kt +12 -40
  22. package/android/src/main/java/com/audiobrowser/browser/StyleResolver.kt +15 -26
  23. package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt +5 -15
  24. package/android/src/main/java/com/audiobrowser/extension/EnumExtensions.kt +1 -0
  25. package/android/src/main/java/com/audiobrowser/extension/NumberExt.kt +2 -0
  26. package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt +4 -8
  27. package/android/src/main/java/com/audiobrowser/extension/TappedTrack.kt +4 -6
  28. package/android/src/main/java/com/audiobrowser/extension/TrackIdentity.kt +3 -7
  29. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +13 -22
  30. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +17 -38
  31. package/android/src/main/java/com/audiobrowser/model/IcyTitle.kt +5 -6
  32. package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt +4 -9
  33. package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt +18 -29
  34. package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt +6 -16
  35. package/android/src/main/java/com/audiobrowser/player/AutomaticBufferManager.kt +15 -45
  36. package/android/src/main/java/com/audiobrowser/player/CapabilityControls.kt +23 -59
  37. package/android/src/main/java/com/audiobrowser/player/CrossOriginHeaderStripper.kt +14 -26
  38. package/android/src/main/java/com/audiobrowser/player/DynamicLoadControl.kt +15 -43
  39. package/android/src/main/java/com/audiobrowser/player/EnginePlayback.kt +4 -4
  40. package/android/src/main/java/com/audiobrowser/player/EqualizerController.kt +15 -21
  41. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +14 -31
  42. package/android/src/main/java/com/audiobrowser/player/LocalEngine.kt +8 -8
  43. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +16 -27
  44. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +119 -237
  45. package/android/src/main/java/com/audiobrowser/player/MediaSessionCommandManager.kt +48 -145
  46. package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt +39 -100
  47. package/android/src/main/java/com/audiobrowser/player/PlaybackErrorClassifier.kt +16 -26
  48. package/android/src/main/java/com/audiobrowser/player/PlaybackStateMachine.kt +22 -28
  49. package/android/src/main/java/com/audiobrowser/player/PlaybackStateStore.kt +28 -64
  50. package/android/src/main/java/com/audiobrowser/player/PlaybackTimer.kt +8 -4
  51. package/android/src/main/java/com/audiobrowser/player/Player.kt +117 -405
  52. package/android/src/main/java/com/audiobrowser/player/PlayerCapabilitiesExt.kt +1 -1
  53. package/android/src/main/java/com/audiobrowser/player/PlayerEngineFactory.kt +11 -19
  54. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +30 -96
  55. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +39 -95
  56. package/android/src/main/java/com/audiobrowser/player/ShuffleOrderLedBy.kt +7 -13
  57. package/android/src/main/java/com/audiobrowser/player/SleepTimer.kt +13 -30
  58. package/android/src/main/java/com/audiobrowser/player/SleepTimerManager.kt +7 -11
  59. package/android/src/main/java/com/audiobrowser/player/StuckRecoveryPolicy.kt +9 -22
  60. package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt +22 -54
  61. package/android/src/main/java/com/audiobrowser/player/VolumeFader.kt +8 -15
  62. package/android/src/main/java/com/audiobrowser/remote/RemoteItem.kt +9 -8
  63. package/android/src/main/java/com/audiobrowser/remote/RemoteOutputsController.kt +13 -10
  64. package/android/src/main/java/com/audiobrowser/remote/RemotePlayback.kt +8 -8
  65. package/android/src/main/java/com/audiobrowser/remote/RemoteQueue.kt +12 -5
  66. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +28 -48
  67. package/android/src/main/java/com/audiobrowser/sonos/DeviceDescriptionParser.kt +11 -19
  68. package/android/src/main/java/com/audiobrowser/sonos/DidlLite.kt +2 -2
  69. package/android/src/main/java/com/audiobrowser/sonos/SoapClient.kt +6 -6
  70. package/android/src/main/java/com/audiobrowser/sonos/SoapEnvelopes.kt +8 -9
  71. package/android/src/main/java/com/audiobrowser/sonos/SoapResponseParser.kt +11 -18
  72. package/android/src/main/java/com/audiobrowser/sonos/SonosDiscoverer.kt +10 -10
  73. package/android/src/main/java/com/audiobrowser/sonos/SonosOutputs.kt +10 -10
  74. package/android/src/main/java/com/audiobrowser/sonos/SonosPlayer.kt +21 -33
  75. package/android/src/main/java/com/audiobrowser/sonos/SonosRemote.kt +4 -6
  76. package/android/src/main/java/com/audiobrowser/sonos/SonosRouteProviderService.kt +9 -10
  77. package/android/src/main/java/com/audiobrowser/sonos/SonosStreamUri.kt +7 -7
  78. package/android/src/main/java/com/audiobrowser/sonos/SonosTransport.kt +5 -4
  79. package/android/src/main/java/com/audiobrowser/sonos/SsdpDiscovery.kt +8 -3
  80. package/android/src/main/java/com/audiobrowser/sonos/SsdpMessages.kt +4 -6
  81. package/android/src/main/java/com/audiobrowser/sonos/ZoneGroupState.kt +13 -11
  82. package/android/src/main/java/com/audiobrowser/tls/AiaCertChaser.kt +34 -71
  83. package/android/src/main/java/com/audiobrowser/tls/AiaChasingExtendedTrustManager.kt +20 -37
  84. package/android/src/main/java/com/audiobrowser/tls/AiaChasingTrustManager.kt +18 -27
  85. package/android/src/main/java/com/audiobrowser/tls/AiaTls.kt +14 -29
  86. package/android/src/main/java/com/audiobrowser/tls/CachingCertificateFetcher.kt +68 -133
  87. package/android/src/main/java/com/audiobrowser/util/ArtworkContentProvider.kt +10 -22
  88. package/android/src/main/java/com/audiobrowser/util/ArtworkRoutes.kt +6 -6
  89. package/android/src/main/java/com/audiobrowser/util/ArtworkUris.kt +4 -3
  90. package/android/src/main/java/com/audiobrowser/util/ArtworkVariant.kt +2 -13
  91. package/android/src/main/java/com/audiobrowser/util/Automotive.kt +2 -4
  92. package/android/src/main/java/com/audiobrowser/util/BatteryOptimizationHelper.kt +3 -9
  93. package/android/src/main/java/com/audiobrowser/util/BatteryWarningStore.kt +4 -14
  94. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +21 -85
  95. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoader.kt +7 -7
  96. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoaderHolder.kt +5 -8
  97. package/android/src/main/java/com/audiobrowser/util/CoilBitmapLoader.kt +8 -24
  98. package/android/src/main/java/com/audiobrowser/util/EqualizerManager.kt +7 -39
  99. package/android/src/main/java/com/audiobrowser/util/MediaExtrasBuilder.kt +10 -14
  100. package/android/src/main/java/com/audiobrowser/util/MetadataAdapter.kt +5 -9
  101. package/android/src/main/java/com/audiobrowser/util/NetworkConnectivityMonitor.kt +5 -9
  102. package/android/src/main/java/com/audiobrowser/util/OutputMonitor.kt +21 -50
  103. package/android/src/main/java/com/audiobrowser/util/OutputSwitcher.kt +7 -20
  104. package/android/src/main/java/com/audiobrowser/util/PlayingStateFactory.kt +3 -5
  105. package/android/src/main/java/com/audiobrowser/util/RatingFavorites.kt +4 -5
  106. package/android/src/main/java/com/audiobrowser/util/StyleWire.kt +5 -5
  107. package/android/src/main/java/com/audiobrowser/util/SvgArtworkRenderer.kt +5 -9
  108. package/android/src/main/java/com/audiobrowser/util/SystemVolumeMonitor.kt +6 -9
  109. package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt +25 -47
  110. package/android/src/nocast/java/com/audiobrowser/cast/CastSupport.kt +0 -2
  111. package/android/src/test/java/com/audiobrowser/ForegroundStartTest.kt +1 -2
  112. package/android/src/test/java/com/audiobrowser/LegacyRatingTest.kt +3 -3
  113. package/android/src/test/java/com/audiobrowser/ServiceBindingTest.kt +0 -13
  114. package/android/src/test/java/com/audiobrowser/ServiceTaskRemovedTest.kt +2 -3
  115. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +5 -14
  116. package/android/src/test/java/com/audiobrowser/browser/BrowseArtworkRegistryTest.kt +1 -1
  117. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerBuildApiRequestTest.kt +2 -8
  118. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerFavoritesTest.kt +2 -12
  119. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt +5 -28
  120. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +11 -43
  121. package/android/src/test/java/com/audiobrowser/browser/BrowserUrlResolutionTest.kt +4 -13
  122. package/android/src/test/java/com/audiobrowser/browser/InertStyleDiagnosticTest.kt +2 -11
  123. package/android/src/test/java/com/audiobrowser/browser/JsonArtworkTest.kt +0 -2
  124. package/android/src/test/java/com/audiobrowser/browser/JsonStyleTest.kt +3 -8
  125. package/android/src/test/java/com/audiobrowser/browser/SectionScopeTest.kt +2 -14
  126. package/android/src/test/java/com/audiobrowser/browser/SimpleRouterTest.kt +1 -5
  127. package/android/src/test/java/com/audiobrowser/browser/StyleResolverTest.kt +2 -13
  128. package/android/src/test/java/com/audiobrowser/extension/TappedTrackTest.kt +1 -7
  129. package/android/src/test/java/com/audiobrowser/extension/TrackIdentityTest.kt +0 -5
  130. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +8 -16
  131. package/android/src/test/java/com/audiobrowser/model/IcyTitleTest.kt +1 -1
  132. package/android/src/test/java/com/audiobrowser/player/BrowseTilesTest.kt +12 -29
  133. package/android/src/test/java/com/audiobrowser/player/CapabilityControlsTest.kt +3 -12
  134. package/android/src/test/java/com/audiobrowser/player/CrossOriginHeaderStripperTest.kt +0 -7
  135. package/android/src/test/java/com/audiobrowser/player/DynamicLoadControlTest.kt +0 -1
  136. package/android/src/test/java/com/audiobrowser/player/EqualizerControllerTest.kt +0 -9
  137. package/android/src/test/java/com/audiobrowser/player/LiveSeekCommandTest.kt +1 -2
  138. package/android/src/test/java/com/audiobrowser/player/MediaSessionSlotMappingTest.kt +0 -9
  139. package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt +15 -22
  140. package/android/src/test/java/com/audiobrowser/player/PlaybackErrorClassifierTest.kt +1 -24
  141. package/android/src/test/java/com/audiobrowser/player/PlaybackStateMachineTest.kt +0 -20
  142. package/android/src/test/java/com/audiobrowser/player/PlaybackStateStoreTrackJsonTest.kt +1 -6
  143. package/android/src/test/java/com/audiobrowser/player/PlaybackTimerTest.kt +2 -4
  144. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +2 -2
  145. package/android/src/test/java/com/audiobrowser/player/PlayerEngineFactoryTest.kt +0 -3
  146. package/android/src/test/java/com/audiobrowser/player/PlayerInvalidTrackTest.kt +0 -1
  147. package/android/src/test/java/com/audiobrowser/player/PlayerSetupTest.kt +3 -2
  148. package/android/src/test/java/com/audiobrowser/player/PlayerSonosTest.kt +5 -1
  149. package/android/src/test/java/com/audiobrowser/player/PlayerSuppressionTest.kt +5 -7
  150. package/android/src/test/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicyTest.kt +4 -35
  151. package/android/src/test/java/com/audiobrowser/player/SessionErrorMaskTest.kt +0 -5
  152. package/android/src/test/java/com/audiobrowser/player/ShuffleOrderLedByTest.kt +1 -8
  153. package/android/src/test/java/com/audiobrowser/player/StandardSkipTest.kt +4 -6
  154. package/android/src/test/java/com/audiobrowser/player/StuckRecoveryPolicyTest.kt +11 -11
  155. package/android/src/test/java/com/audiobrowser/player/TransformingDataSourceTest.kt +2 -23
  156. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +9 -10
  157. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +0 -1
  158. package/android/src/test/java/com/audiobrowser/sonos/DeviceDescriptionParserTest.kt +1 -3
  159. package/android/src/test/java/com/audiobrowser/sonos/DidlLiteTest.kt +0 -1
  160. package/android/src/test/java/com/audiobrowser/sonos/SoapClientTest.kt +0 -3
  161. package/android/src/test/java/com/audiobrowser/sonos/SoapEnvelopesTest.kt +0 -1
  162. package/android/src/test/java/com/audiobrowser/sonos/SoapResponseParserTest.kt +0 -1
  163. package/android/src/test/java/com/audiobrowser/sonos/SonosDiscovererTest.kt +2 -0
  164. package/android/src/test/java/com/audiobrowser/sonos/SonosPlayerTest.kt +0 -1
  165. package/android/src/test/java/com/audiobrowser/sonos/SonosRemoteTest.kt +1 -1
  166. package/android/src/test/java/com/audiobrowser/sonos/SonosRoutesTest.kt +2 -0
  167. package/android/src/test/java/com/audiobrowser/sonos/SonosTransportTest.kt +2 -6
  168. package/android/src/test/java/com/audiobrowser/sonos/SsdpMessagesTest.kt +0 -2
  169. package/android/src/test/java/com/audiobrowser/tls/AiaCertChaserTest.kt +13 -37
  170. package/android/src/test/java/com/audiobrowser/tls/AiaChasingTrustManagerTest.kt +10 -24
  171. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherCallSiteTest.kt +15 -39
  172. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherTest.kt +4 -10
  173. package/android/src/test/java/com/audiobrowser/util/ArtworkContentProviderTest.kt +2 -11
  174. package/android/src/test/java/com/audiobrowser/util/ArtworkUrisTest.kt +0 -1
  175. package/android/src/test/java/com/audiobrowser/util/BrowserPathHelperTest.kt +0 -4
  176. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderHolderTest.kt +1 -1
  177. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderTest.kt +0 -5
  178. package/android/src/test/java/com/audiobrowser/util/FakeImageLoader.kt +2 -2
  179. package/android/src/test/java/com/audiobrowser/util/MediaExtrasBuilderTest.kt +4 -12
  180. package/android/src/test/java/com/audiobrowser/util/OutputMonitorTest.kt +1 -1
  181. package/android/src/test/java/com/audiobrowser/util/PlayingStateFactoryTest.kt +0 -4
  182. package/android/src/test/java/com/audiobrowser/util/TrackFactoryBrowseTest.kt +1 -1
  183. package/android/src/test/java/com/audiobrowser/util/TrackFactoryMediaIdTest.kt +4 -6
  184. package/android/src/testCast/java/com/audiobrowser/cast/CastEndsTest.kt +1 -1
  185. package/android/src/testCast/java/com/audiobrowser/cast/SendingMediaItemConverterTest.kt +1 -0
  186. package/ios/AVPlayerEngine.swift +13 -21
  187. package/ios/AVPlayerEngineCallbacks.swift +2 -4
  188. package/ios/Browser/BrowseGate.swift +7 -8
  189. package/ios/Browser/BrowserConfig.swift +19 -34
  190. package/ios/Browser/BrowserError.swift +0 -1
  191. package/ios/Browser/BrowserManager.swift +29 -75
  192. package/ios/Browser/BrowserPathHelper.swift +13 -93
  193. package/ios/Browser/FavoriteSet.swift +7 -10
  194. package/ios/Browser/InertStyleDiagnostic.swift +17 -82
  195. package/ios/Browser/JsonModels.swift +11 -51
  196. package/ios/Browser/NavigationErrorState.swift +3 -2
  197. package/ios/Browser/PageResolver.swift +13 -23
  198. package/ios/Browser/RequestLayer.swift +16 -20
  199. package/ios/Browser/RequestPipeline.swift +33 -43
  200. package/ios/Browser/SearchDrillIn.swift +7 -13
  201. package/ios/Browser/SectionScope.swift +14 -26
  202. package/ios/Browser/SimpleRouter.swift +8 -15
  203. package/ios/Browser/StyleResolver.swift +12 -29
  204. package/ios/Browser/TabBarEntries.swift +6 -11
  205. package/ios/Browser/TrackIdTemplate.swift +6 -14
  206. package/ios/CarPlay/CPInterfaceController+Safe.swift +19 -28
  207. package/ios/CarPlay/CarPlayArtworkResolver.swift +5 -9
  208. package/ios/CarPlay/CarPlayController.swift +4 -4
  209. package/ios/CarPlay/CarPlayImageLoader.swift +11 -26
  210. package/ios/CarPlay/CarPlayListItemFactory.swift +30 -80
  211. package/ios/CarPlay/CarPlayNowPlayingManager.swift +19 -54
  212. package/ios/CarPlay/CarPlaySession+Navigator.swift +10 -10
  213. package/ios/CarPlay/CarPlaySession+PageLoader.swift +6 -5
  214. package/ios/CarPlay/CarPlaySession+Refresher.swift +2 -2
  215. package/ios/CarPlay/CarPlaySession+TabBar.swift +19 -26
  216. package/ios/CarPlay/CarPlaySession.swift +13 -17
  217. package/ios/CarPlay/CarPlayTemplates.swift +6 -7
  218. package/ios/CarPlay/IntentHandlers.swift +3 -5
  219. package/ios/CarPlay/MediaIntentCriteria.swift +15 -29
  220. package/ios/CarPlay/MediaIntentHandler.swift +4 -7
  221. package/ios/CarPlay/MediaIntentPlayback.swift +9 -8
  222. package/ios/CarPlay/NowPlayingButtonRules.swift +3 -4
  223. package/ios/CarPlay/SectionPresentation.swift +18 -28
  224. package/ios/CarPlay/TopTemplateReplacer.swift +8 -9
  225. package/ios/Extension/Capability+RemoteCommand.swift +3 -3
  226. package/ios/Extension/ChapterMetadata+AVFoundation.swift +2 -5
  227. package/ios/Extension/CxxVectorConformances.swift +4 -16
  228. package/ios/Extension/NavigationError+Conversion.swift +4 -7
  229. package/ios/Extension/PlayerCapabilities+Favorite.swift +0 -1
  230. package/ios/Extension/RequestConfig+Copying.swift +2 -6
  231. package/ios/Extension/ResolvedTrack+Copying.swift +2 -8
  232. package/ios/Extension/SearchParams+Query.swift +4 -4
  233. package/ios/Extension/Section+Copying.swift +3 -6
  234. package/ios/Extension/String+IcyCharset.swift +5 -5
  235. package/ios/Extension/TimedMetadata+AVFoundation.swift +6 -12
  236. package/ios/Extension/Track+AVPlayer.swift +1 -2
  237. package/ios/Extension/Track+Copying.swift +2 -8
  238. package/ios/Extension/Track+Identity.swift +4 -9
  239. package/ios/Extension/TrackMetadata+AVFoundation.swift +10 -13
  240. package/ios/Extension/UIApplication+ActiveScene.swift +6 -14
  241. package/ios/Extension/Variant+Artwork.swift +8 -22
  242. package/ios/Http/HttpClient.swift +3 -3
  243. package/ios/HybridAudioBrowser+Browser.swift +10 -16
  244. package/ios/HybridAudioBrowser+Options.swift +6 -9
  245. package/ios/HybridAudioBrowser+Player.swift +8 -16
  246. package/ios/HybridAudioBrowser+PlayerCallbacks.swift +4 -5
  247. package/ios/HybridAudioBrowser+Stubs.swift +5 -7
  248. package/ios/HybridAudioBrowser.swift +54 -79
  249. package/ios/Model/NitroTypeStubs.swift +15 -22
  250. package/ios/Model/PlayerUpdateOptions.swift +6 -21
  251. package/ios/Model/RemoteCommand.swift +2 -2
  252. package/ios/Model/TrackPlayerError.swift +9 -22
  253. package/ios/NowPlayingInfo/NowPlayingInfoController.swift +21 -40
  254. package/ios/NowPlayingInfo/SilentAudioPrimer.swift +10 -16
  255. package/ios/Observer/ItemObserver.swift +7 -5
  256. package/ios/Observer/PlayerObserver.swift +5 -5
  257. package/ios/PlaybackEvent.swift +2 -2
  258. package/ios/Player/AirPlayStallJudgement.swift +7 -9
  259. package/ios/Player/AudioSessionController.swift +14 -15
  260. package/ios/Player/DeferredSeek.swift +2 -2
  261. package/ios/Player/EndOfTrackJudgement.swift +6 -13
  262. package/ios/Player/ErrorStatus.swift +8 -7
  263. package/ios/Player/MediaLoader.swift +20 -24
  264. package/ios/Player/NowPlayingLines.swift +1 -4
  265. package/ios/Player/NowPlayingUpdater.swift +35 -61
  266. package/ios/Player/PersistedPlaybackState.swift +1 -2
  267. package/ios/Player/PlaybackFailure.swift +20 -24
  268. package/ios/Player/PlaybackPersistence.swift +5 -6
  269. package/ios/Player/PlaybackStateMachine.swift +8 -11
  270. package/ios/Player/PlaybackTimer.swift +8 -11
  271. package/ios/Player/Player.swift +6 -13
  272. package/ios/Player/PlayerEngine.swift +20 -20
  273. package/ios/Player/PlayerStatusTypes.swift +1 -2
  274. package/ios/Player/QueueManager.swift +23 -67
  275. package/ios/Player/RetryLoop.swift +39 -50
  276. package/ios/Player/ShuffleOrder.swift +17 -57
  277. package/ios/Player/SleepTimerManager.swift +13 -28
  278. package/ios/Player/VolumeFader.swift +16 -16
  279. package/ios/RemoteCommand/RemoteCommandCallbacks.swift +6 -16
  280. package/ios/RemoteCommand/RemoteCommandController.swift +8 -10
  281. package/ios/Tests/AirPlayStallJudgementTests.swift +4 -4
  282. package/ios/Tests/BrowserPathHelperTests.swift +3 -6
  283. package/ios/Tests/DeferredSeekTests.swift +1 -3
  284. package/ios/Tests/EmitterTests.swift +0 -1
  285. package/ios/Tests/EndOfTrackJudgementTests.swift +1 -6
  286. package/ios/Tests/FavoriteSetTests.swift +1 -0
  287. package/ios/Tests/GenerationMemoTests.swift +2 -2
  288. package/ios/Tests/InertStyleDiagnosticTests.swift +4 -10
  289. package/ios/Tests/JsonModelsTests.swift +5 -12
  290. package/ios/Tests/LRUCacheTests.swift +1 -5
  291. package/ios/Tests/MediaIntentCriteriaTests.swift +2 -7
  292. package/ios/Tests/MediaLoaderTests.swift +3 -12
  293. package/ios/Tests/ObserverTests.swift +3 -3
  294. package/ios/Tests/PlaybackErrorTests.swift +7 -9
  295. package/ios/Tests/PlaybackFailureTests.swift +9 -17
  296. package/ios/Tests/PlaybackPersistenceTests.swift +1 -0
  297. package/ios/Tests/PlaybackStateMachineTests.swift +1 -16
  298. package/ios/Tests/PlaybackTimerTests.swift +2 -3
  299. package/ios/Tests/PlayerPolicyTests.swift +10 -26
  300. package/ios/Tests/PlayerTests.swift +53 -88
  301. package/ios/Tests/PlayingStateTests.swift +0 -1
  302. package/ios/Tests/QueueManagerTests.swift +30 -80
  303. package/ios/Tests/RemoteCommandControllerTests.swift +5 -13
  304. package/ios/Tests/ResolvedTrackCopyingTests.swift +0 -2
  305. package/ios/Tests/RetryLoopTests.swift +12 -35
  306. package/ios/Tests/SearchDrillInTests.swift +4 -5
  307. package/ios/Tests/SectionPresentationTests.swift +3 -16
  308. package/ios/Tests/SectionScopeTests.swift +3 -6
  309. package/ios/Tests/SimpleRouterTests.swift +1 -5
  310. package/ios/Tests/SleepTimerManagerTests.swift +8 -11
  311. package/ios/Tests/StyleResolverTests.swift +4 -13
  312. package/ios/Tests/Support/ManualSleepTimerScheduler.swift +3 -8
  313. package/ios/Tests/Support/TestTypes.swift +5 -15
  314. package/ios/Tests/TabBarEntriesTests.swift +0 -2
  315. package/ios/Tests/TimedMetadataAVFoundationTests.swift +2 -3
  316. package/ios/Tests/TopTemplateReplacerTests.swift +1 -1
  317. package/ios/Tests/TrackIdTemplateTests.swift +2 -6
  318. package/ios/Tests/TrackMetadataAVFoundationTests.swift +1 -4
  319. package/ios/Tests/TrackSelectorTests.swift +3 -15
  320. package/ios/TrackSelector.swift +13 -25
  321. package/ios/Util/ArtworkFreshness.swift +6 -6
  322. package/ios/Util/ArtworkImageFetcher.swift +19 -20
  323. package/ios/Util/ConcurrentMap.swift +2 -2
  324. package/ios/Util/Emitter.swift +8 -13
  325. package/ios/Util/NetworkMonitor.swift +4 -6
  326. package/ios/Util/OutputPicker.swift +1 -1
  327. package/ios/Util/ReadyValue.swift +3 -2
  328. package/ios/Util/SFSymbolRenderer.swift +17 -30
  329. package/ios/Util/SVGProcessor.swift +5 -9
  330. package/lib/commonjs/CLAUDE.md +7 -2
  331. package/lib/commonjs/features/battery.js +16 -12
  332. package/lib/commonjs/features/battery.js.map +1 -1
  333. package/lib/commonjs/features/browser-config.js +1 -1
  334. package/lib/commonjs/features/browser.js +74 -24
  335. package/lib/commonjs/features/browser.js.map +1 -1
  336. package/lib/commonjs/features/carConnection.js +3 -4
  337. package/lib/commonjs/features/carConnection.js.map +1 -1
  338. package/lib/commonjs/features/equalizer.js +9 -5
  339. package/lib/commonjs/features/equalizer.js.map +1 -1
  340. package/lib/commonjs/features/errors.js +35 -21
  341. package/lib/commonjs/features/errors.js.map +1 -1
  342. package/lib/commonjs/features/favorites.js +15 -13
  343. package/lib/commonjs/features/favorites.js.map +1 -1
  344. package/lib/commonjs/features/gate.js +12 -6
  345. package/lib/commonjs/features/gate.js.map +1 -1
  346. package/lib/commonjs/features/metadata.js +16 -14
  347. package/lib/commonjs/features/metadata.js.map +1 -1
  348. package/lib/commonjs/features/network.js +5 -1
  349. package/lib/commonjs/features/network.js.map +1 -1
  350. package/lib/commonjs/features/nowPlaying.js +28 -14
  351. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  352. package/lib/commonjs/features/output.js +8 -4
  353. package/lib/commonjs/features/output.js.map +1 -1
  354. package/lib/commonjs/features/playback/controls.js +10 -5
  355. package/lib/commonjs/features/playback/controls.js.map +1 -1
  356. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  357. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  358. package/lib/commonjs/features/playback/playing.js +5 -3
  359. package/lib/commonjs/features/playback/playing.js.map +1 -1
  360. package/lib/commonjs/features/playback/progress.js +11 -5
  361. package/lib/commonjs/features/playback/progress.js.map +1 -1
  362. package/lib/commonjs/features/playback/state.js +3 -3
  363. package/lib/commonjs/features/playback/state.js.map +1 -1
  364. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  365. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  366. package/lib/commonjs/features/playback/volume.js +6 -5
  367. package/lib/commonjs/features/playback/volume.js.map +1 -1
  368. package/lib/commonjs/features/player/options.js +20 -10
  369. package/lib/commonjs/features/player/options.js.map +1 -1
  370. package/lib/commonjs/features/player/setup.js +34 -38
  371. package/lib/commonjs/features/player/setup.js.map +1 -1
  372. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  373. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  374. package/lib/commonjs/features/queue/queue.js +48 -20
  375. package/lib/commonjs/features/queue/queue.js.map +1 -1
  376. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  377. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  378. package/lib/commonjs/features/queue/shuffle.js +0 -1
  379. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  380. package/lib/commonjs/features/remoteControls.js +59 -35
  381. package/lib/commonjs/features/remoteControls.js.map +1 -1
  382. package/lib/commonjs/features/sleepTimer.js +15 -6
  383. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  384. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  385. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  386. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  387. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  388. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  389. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  390. package/lib/commonjs/utils/useDebug.js +16 -3
  391. package/lib/commonjs/utils/useDebug.js.map +1 -1
  392. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  393. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  394. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  395. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  396. package/lib/commonjs/web/browser/sections.js +1 -1
  397. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  398. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  399. package/lib/module/CLAUDE.md +7 -2
  400. package/lib/module/features/battery.js +16 -12
  401. package/lib/module/features/battery.js.map +1 -1
  402. package/lib/module/features/browser-config.js +1 -1
  403. package/lib/module/features/browser.js +74 -24
  404. package/lib/module/features/browser.js.map +1 -1
  405. package/lib/module/features/carConnection.js +3 -4
  406. package/lib/module/features/carConnection.js.map +1 -1
  407. package/lib/module/features/equalizer.js +9 -5
  408. package/lib/module/features/equalizer.js.map +1 -1
  409. package/lib/module/features/errors.js +35 -21
  410. package/lib/module/features/errors.js.map +1 -1
  411. package/lib/module/features/favorites.js +15 -13
  412. package/lib/module/features/favorites.js.map +1 -1
  413. package/lib/module/features/gate.js +12 -6
  414. package/lib/module/features/gate.js.map +1 -1
  415. package/lib/module/features/metadata.js +16 -14
  416. package/lib/module/features/metadata.js.map +1 -1
  417. package/lib/module/features/network.js +5 -1
  418. package/lib/module/features/network.js.map +1 -1
  419. package/lib/module/features/nowPlaying.js +28 -14
  420. package/lib/module/features/nowPlaying.js.map +1 -1
  421. package/lib/module/features/output.js +8 -4
  422. package/lib/module/features/output.js.map +1 -1
  423. package/lib/module/features/playback/controls.js +10 -5
  424. package/lib/module/features/playback/controls.js.map +1 -1
  425. package/lib/module/features/playback/playWhenReady.js +6 -5
  426. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  427. package/lib/module/features/playback/playing.js +5 -3
  428. package/lib/module/features/playback/playing.js.map +1 -1
  429. package/lib/module/features/playback/progress.js +11 -5
  430. package/lib/module/features/playback/progress.js.map +1 -1
  431. package/lib/module/features/playback/state.js +3 -3
  432. package/lib/module/features/playback/state.js.map +1 -1
  433. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  434. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  435. package/lib/module/features/playback/volume.js +6 -5
  436. package/lib/module/features/playback/volume.js.map +1 -1
  437. package/lib/module/features/player/options.js +20 -10
  438. package/lib/module/features/player/options.js.map +1 -1
  439. package/lib/module/features/player/setup.js +34 -38
  440. package/lib/module/features/player/setup.js.map +1 -1
  441. package/lib/module/features/queue/activeTrack.js +0 -1
  442. package/lib/module/features/queue/activeTrack.js.map +1 -1
  443. package/lib/module/features/queue/queue.js +48 -20
  444. package/lib/module/features/queue/queue.js.map +1 -1
  445. package/lib/module/features/queue/repeatMode.js +2 -1
  446. package/lib/module/features/queue/repeatMode.js.map +1 -1
  447. package/lib/module/features/queue/shuffle.js +0 -1
  448. package/lib/module/features/queue/shuffle.js.map +1 -1
  449. package/lib/module/features/remoteControls.js +59 -35
  450. package/lib/module/features/remoteControls.js.map +1 -1
  451. package/lib/module/features/sleepTimer.js +15 -6
  452. package/lib/module/features/sleepTimer.js.map +1 -1
  453. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  454. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  455. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  456. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  457. package/lib/module/utils/getTrackIdentity.js +6 -4
  458. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  459. package/lib/module/utils/useDebug.js +16 -3
  460. package/lib/module/utils/useDebug.js.map +1 -1
  461. package/lib/module/web/NativeAudioBrowser.js +2 -4
  462. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  463. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  464. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  465. package/lib/module/web/browser/sections.js +1 -1
  466. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  467. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  468. package/lib/typescript/src/features/battery.d.ts +17 -12
  469. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  470. package/lib/typescript/src/features/browser.d.ts +64 -24
  471. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  472. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  473. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  474. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  475. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  476. package/lib/typescript/src/features/errors.d.ts +37 -22
  477. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  478. package/lib/typescript/src/features/favorites.d.ts +15 -13
  479. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  480. package/lib/typescript/src/features/gate.d.ts +14 -8
  481. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  482. package/lib/typescript/src/features/metadata.d.ts +37 -17
  483. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  484. package/lib/typescript/src/features/network.d.ts +5 -1
  485. package/lib/typescript/src/features/network.d.ts.map +1 -1
  486. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  487. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  488. package/lib/typescript/src/features/output.d.ts +8 -4
  489. package/lib/typescript/src/features/output.d.ts.map +1 -1
  490. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  491. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  492. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  493. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  494. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  495. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  496. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  497. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  498. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  499. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  500. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  501. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  502. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  503. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  504. package/lib/typescript/src/features/player/options.d.ts +52 -37
  505. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  506. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  507. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  508. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  509. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  510. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  511. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  512. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  513. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  514. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  515. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  516. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  517. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  518. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  519. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  520. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  521. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  522. package/lib/typescript/src/types/browser.d.ts +181 -144
  523. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  524. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  525. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  526. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  527. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  528. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  529. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  530. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  531. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  532. package/package.json +1 -1
  533. package/src/CLAUDE.md +7 -2
  534. package/src/docs-floors.test.ts +71 -0
  535. package/src/features/battery.ts +17 -13
  536. package/src/features/browser-config.ts +1 -1
  537. package/src/features/browser.ts +65 -24
  538. package/src/features/carConnection.ts +3 -4
  539. package/src/features/equalizer.ts +9 -5
  540. package/src/features/errors.ts +37 -22
  541. package/src/features/favorites.ts +15 -13
  542. package/src/features/gate.ts +14 -8
  543. package/src/features/metadata.ts +37 -17
  544. package/src/features/network.ts +5 -1
  545. package/src/features/nowPlaying.ts +28 -14
  546. package/src/features/output.ts +8 -4
  547. package/src/features/playback/controls.ts +10 -5
  548. package/src/features/playback/playWhenReady.ts +6 -5
  549. package/src/features/playback/playing.ts +16 -3
  550. package/src/features/playback/progress.ts +11 -5
  551. package/src/features/playback/state.ts +8 -3
  552. package/src/features/playback/trackPlaybackTime.ts +9 -2
  553. package/src/features/playback/volume.ts +6 -5
  554. package/src/features/player/options.ts +54 -43
  555. package/src/features/player/setup.ts +67 -61
  556. package/src/features/queue/activeTrack.ts +0 -1
  557. package/src/features/queue/queue.ts +48 -20
  558. package/src/features/queue/repeatMode.ts +1 -1
  559. package/src/features/queue/shuffle.ts +0 -1
  560. package/src/features/remoteControls.ts +59 -35
  561. package/src/features/sleepTimer.ts +15 -7
  562. package/src/types/browser-nodes.ts +54 -57
  563. package/src/types/browser.ts +183 -146
  564. package/src/utils/LazyNativeEmitter.ts +6 -9
  565. package/src/utils/NativeUpdatedValue.ts +13 -12
  566. package/src/utils/getTrackIdentity.ts +6 -4
  567. package/src/utils/useDebug.ts +16 -3
  568. package/src/web/NativeAudioBrowser.ts +2 -4
  569. package/src/web/browser/parseSearchResponse.ts +3 -4
  570. package/src/web/browser/sections.ts +1 -1
  571. package/src/web/util/BrowserPathHelper.ts +1 -3
  572. package/website/guide/android-auto.md +25 -13
  573. package/website/guide/android-certificates.md +199 -120
  574. package/website/guide/artwork.md +93 -48
  575. package/website/guide/audio-output.md +86 -68
  576. package/website/guide/automotive.md +15 -10
  577. package/website/guide/basic-usage.md +5 -2
  578. package/website/guide/battery.md +50 -23
  579. package/website/guide/browser.md +155 -68
  580. package/website/guide/carplay.md +132 -49
  581. package/website/guide/configuration.md +85 -49
  582. package/website/guide/equalizer.md +36 -32
  583. package/website/guide/errors.md +106 -64
  584. package/website/guide/favorites.md +41 -31
  585. package/website/guide/gate.md +24 -10
  586. package/website/guide/getting-started.md +55 -2
  587. package/website/guide/hooks.md +53 -47
  588. package/website/guide/live-streams.md +80 -49
  589. package/website/guide/metadata.md +87 -53
  590. package/website/guide/migrating-from-track-player.md +94 -49
  591. package/website/guide/native-callback-fetch.md +46 -36
  592. package/website/guide/network.md +36 -20
  593. package/website/guide/now-playing.md +72 -44
  594. package/website/guide/playback.md +112 -35
  595. package/website/guide/queue.md +77 -43
  596. package/website/guide/remote-controls.md +87 -29
  597. package/website/guide/search.md +37 -22
  598. package/website/guide/sleep-timer.md +35 -14
  599. package/website/guide/track.md +59 -35
@@ -2,7 +2,8 @@ import type { NavigationError } from '../features/errors'
2
2
  import type { ResolvedTrack, Track } from './browser-nodes.ts'
3
3
 
4
4
  /**
5
- * Event fired when a track is about to be loaded via navigateTrack.
5
+ * Event fired when a playable track is about to load: a browse-row tap or a
6
+ * `navigate(track)` call.
6
7
  */
7
8
  export interface TrackLoadEvent {
8
9
  /** The track that will be loaded */
@@ -22,6 +23,7 @@ export interface TrackLoadEvent {
22
23
  */
23
24
  export type HandleTrackLoadCallback = (event: TrackLoadEvent) => Promise<void>
24
25
 
26
+ /** What a browse callback receives: the path, and the params its route matched. */
25
27
  export type BrowserSourceCallbackParam = {
26
28
  path: string
27
29
  routeParams?: Record<string, string>
@@ -29,7 +31,9 @@ export type BrowserSourceCallbackParam = {
29
31
 
30
32
  /**
31
33
  * Return BrowseError from a browse callback to display an error to the user.
32
- * The error message will be shown in an error dialog in CarPlay and Android Auto.
34
+ * CarPlay and Android Auto show the error in place of the list: as the CarPlay
35
+ * list's message, and as an error row in Android Auto. The title comes from
36
+ * `formatNavigationError` (default "Error"), and your string is the message.
33
37
  *
34
38
  * On the app side, the error is surfaced as a `NavigationError` with
35
39
  * `code: 'callback-error'`. Use `useNavigationError()` to get the error details,
@@ -37,11 +41,13 @@ export type BrowserSourceCallbackParam = {
37
41
  *
38
42
  * @example
39
43
  * ```ts
40
- * browse: async ({ path }) => {
41
- * if (!user.subscribed) {
42
- * return { error: 'Please subscribe to access this content' }
44
+ * routes: {
45
+ * '/premium': async ({ path }) => {
46
+ * if (!user.subscribed) {
47
+ * return { error: 'Please subscribe to access this content' }
48
+ * }
49
+ * return fetchContent(path)
43
50
  * }
44
- * return fetchContent(path)
45
51
  * }
46
52
  * ```
47
53
  */
@@ -55,6 +61,7 @@ export type BrowseError = {
55
61
  */
56
62
  export type BrowseResult = ResolvedTrack | BrowseError
57
63
 
64
+ /** Browse callback: returns the page for a path, or a {@link BrowseError}. */
58
65
  export type BrowserSourceCallback = (
59
66
  param: BrowserSourceCallbackParam
60
67
  ) => BrowseResult | Promise<BrowseResult>
@@ -159,22 +166,30 @@ export interface SearchParams {
159
166
  reference: MediaReference
160
167
  }
161
168
 
169
+ /** Search callback: returns the result tracks for a search. */
162
170
  export type SearchSourceCallback = (params: SearchParams) => Promise<Track[]>
171
+
163
172
  // Sync and async transforms are SEPARATE fields (`transform` / `transformSync`),
164
173
  // never a `T | Promise<T>` union. A union lowers to a Nitro `variant<Struct,
165
174
  // Promise<Struct>>`, and an all-optional struct's `canConvert` also accepts a
166
175
  // Promise — so the async case is silently misread as an empty config. Two
167
176
  // single-typed fields keep both paths unambiguous, and the sync field allocates
168
177
  // no Promise. When both are set they run as a pipeline: async first, then sync.
178
+ /**
179
+ * Async `transform`: receives the merged request and the route's params, and
180
+ * returns the request to send.
181
+ */
169
182
  export type RequestConfigTransformer = (
170
183
  request: RequestConfig,
171
184
  routeParams?: Record<string, string>
172
185
  ) => Promise<RequestConfig>
186
+ /** Sync `transformSync`: the {@link RequestConfigTransformer} without a Promise. */
173
187
  export type RequestConfigTransformerSync = (
174
188
  request: RequestConfig,
175
189
  routeParams?: Record<string, string>
176
190
  ) => RequestConfig
177
191
 
192
+ /** HTTP method of a request. */
178
193
  export type HttpMethod =
179
194
  | 'GET'
180
195
  | 'POST'
@@ -184,26 +199,50 @@ export type HttpMethod =
184
199
  | 'HEAD'
185
200
  | 'OPTIONS'
186
201
 
202
+ /**
203
+ * One HTTP request's fields. When configs layer, `headers` and `query` merge
204
+ * by key, and every other set field overrides the one below it, unless the
205
+ * layer has a transform, which replaces the config outright.
206
+ */
187
207
  export interface RequestConfig {
208
+ /** HTTP method. Defaults to `'GET'`. */
188
209
  method?: HttpMethod
189
210
  /**
190
211
  * The request path.
191
212
  * - For browser requests, this is the track's `path`
192
213
  * - For media requests, this is the track's `src` value
193
214
  * - For artwork requests, this is the track's `artwork` URL
215
+ *
216
+ * A static value is ignored on `request`, `browse`, `media` and route
217
+ * layers; change it in a `transform`.
194
218
  */
195
219
  path?: string
220
+ /** URL that a relative `path` is appended to. */
196
221
  baseUrl?: string
222
+ /** Request headers, merged by key with the layers below. */
197
223
  headers?: Record<string, string>
224
+ /** Query parameters, merged by key with the layers below. */
198
225
  query?: Record<string, string>
226
+ /**
227
+ * Request body, sent for POST, PUT and PATCH (and DELETE when set) on iOS
228
+ * and Android; not sent on web.
229
+ */
199
230
  body?: string
231
+ /**
232
+ * Content type of the body on iOS and Android. Defaults to
233
+ * `'application/json'`; not sent on web.
234
+ */
200
235
  contentType?: string
236
+ /**
237
+ * Sent as `User-Agent` on iOS and Android (a `User-Agent` in `headers` wins
238
+ * on iOS); ignored on web.
239
+ */
201
240
  userAgent?: string
202
241
  }
203
242
 
204
243
  /**
205
244
  * Context for image loading requests.
206
- * Provides pixel dimensions and appearance info from Android Auto/CarPlay.
245
+ * Provides pixel dimensions from Android Auto/CarPlay.
207
246
  *
208
247
  * @example
209
248
  * ```typescript
@@ -273,10 +312,11 @@ export interface MediaTransformParams {
273
312
  * }
274
313
  * ```
275
314
  */
276
- // Split sync/async — see RequestConfigTransformer. Set `transform` and/or `transformSync`.
315
+ /** Async artwork `transform`: receives `{ request, context }`. */
277
316
  export type MediaRequestConfigTransformer = (
278
317
  params: MediaTransformParams
279
318
  ) => Promise<RequestConfig>
319
+ /** Sync artwork `transformSync`: the {@link MediaRequestConfigTransformer} without a Promise. */
280
320
  export type MediaRequestConfigTransformerSync = (
281
321
  params: MediaTransformParams
282
322
  ) => RequestConfig
@@ -349,66 +389,6 @@ export type RequestConfigResolver = () =>
349
389
  | TransformableRequestConfig
350
390
  | Promise<TransformableRequestConfig>
351
391
 
352
- /**
353
- * Configuration for artwork image requests
354
- *
355
- * ### Configuration Hierarchy
356
- *
357
- * When a request is made, configs are merged in this order (later overrides earlier):
358
- * 1. `request` (base config) - shared settings like user agent, common headers
359
- * 2. `artwork` config - resource-specific settings
360
- * 3. `resolve(track)` result - per-track overrides (if provided)
361
- * 4. `imageQueryParams` - automatic size query param injection (if configured)
362
- * 5. `transform(request, context)` result - final modifications (if provided)
363
- *
364
- * ### Usage Patterns
365
- *
366
- * **Simple CDN configuration:**
367
- * ```typescript
368
- * media: {
369
- * baseUrl: 'https://audio.cdn.example.com',
370
- * headers: { 'X-API-Key': 'your-api-key' }
371
- * }
372
- * ```
373
- *
374
- * **Per-track URL resolution:**
375
- * ```typescript
376
- * media: {
377
- * resolve: async (track) => ({
378
- * baseUrl: 'https://audio.cdn.example.com',
379
- * path: `/streams/${track.src}`,
380
- * query: { token: await getSignedToken(track.src) }
381
- * })
382
- * }
383
- * ```
384
- *
385
- * **Size-aware transformation (for artwork):**
386
- * ```typescript
387
- * artwork: {
388
- * baseUrl: 'https://images.cdn.example.com',
389
- * transform: async ({ request, context }) => ({
390
- * ...request,
391
- * query: {
392
- * ...request.query,
393
- * w: context?.width ? String(context.width) : '600',
394
- * sig: await signUrl(request.path)
395
- * }
396
- * })
397
- * }
398
- * ```
399
- *
400
- * **Simple size params (declarative alternative):**
401
- * ```typescript
402
- * artwork: {
403
- * baseUrl: 'https://images.cdn.example.com',
404
- * imageQueryParams: { width: 'w', height: 'h' }
405
- * }
406
- * ```
407
- *
408
- * @see BrowserConfiguration.media - Audio stream configuration
409
- * @see BrowserConfiguration.artwork - Image/artwork configuration
410
- */
411
-
412
392
  /**
413
393
  * Query parameter names for automatic context injection from CarPlay/Android Auto.
414
394
  * Maps ImageContext fields to query parameter names for your CDN.
@@ -421,11 +401,9 @@ export interface ImageQueryParams {
421
401
  }
422
402
 
423
403
  /**
424
- * Configuration for media resource requests (audio streams, artwork images).
404
+ * Configuration for audio stream requests: `media` in BrowserConfiguration.
425
405
  * Extends TransformableRequestConfig with per-track resolution capabilities.
426
- *
427
- * Used for both `media` (audio streaming) and `artwork` (image loading) configuration
428
- * in BrowserConfiguration.
406
+ * For `artwork`, see {@link ArtworkRequestConfig}.
429
407
  *
430
408
  * ### Configuration Hierarchy
431
409
  *
@@ -438,10 +416,8 @@ export interface ImageQueryParams {
438
416
  * per-track resolver is the most specific layer and wins over the
439
417
  * transform, on every platform
440
418
  *
441
- * The `media` order is deliberate: a resolver minting a per-track signed URL
442
- * must not be overwritten by the static layer that shaped the unsigned one. It
443
- * means a `media.transform` cannot sign what `resolve` produced — do that work
444
- * inside `resolve`, or move the signing to `transform` and drop `resolve`.
419
+ * So a `media.transform` cannot sign what `resolve` produced: sign inside
420
+ * `resolve`, or sign in `transform` and drop `resolve`.
445
421
  *
446
422
  * ### Usage Patterns
447
423
  *
@@ -466,10 +442,10 @@ export interface ImageQueryParams {
466
442
  *
467
443
  * **Dynamic request signing:**
468
444
  * ```typescript
469
- * artwork: {
470
- * baseUrl: 'https://images.cdn.example.com',
445
+ * media: {
471
446
  * transform: async (request) => ({
472
447
  * ...request,
448
+ * baseUrl: 'https://audio.cdn.example.com',
473
449
  * query: { ...request.query, sig: await signUrl(request.path) }
474
450
  * })
475
451
  * }
@@ -480,18 +456,18 @@ export interface ImageQueryParams {
480
456
  */
481
457
  export interface MediaRequestConfig extends TransformableRequestConfig {
482
458
  /**
483
- * Per-track request resolution callback.
459
+ * Async per-track request resolution.
484
460
  *
485
461
  * Called for each track to generate the final request configuration.
486
462
  * Receives the full Track object, allowing URL generation based on
487
463
  * track metadata (id, artist, album, src, etc.).
488
464
  *
489
465
  * Runs **last** for media — after `transform`, and winning over it on every
490
- * field including `path`. See the hierarchy note on this interface; artwork
491
- * runs them the other way round.
466
+ * field including `path`; artwork runs them the other way round (see
467
+ * {@link MediaRequestConfig}). When `resolveSync` is also set, both run and
468
+ * the `resolveSync` result merges over this one.
492
469
  *
493
470
  * @param track - The track being requested
494
- * @returns Request configuration for this specific track (sync or async)
495
471
  *
496
472
  * @example
497
473
  * ```typescript
@@ -501,21 +477,62 @@ export interface MediaRequestConfig extends TransformableRequestConfig {
501
477
  * })
502
478
  * ```
503
479
  */
504
- /** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
505
480
  resolve?: (track: Track) => Promise<RequestConfig>
506
481
  /** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
507
482
  resolveSync?: (track: Track) => RequestConfig
508
483
  }
509
484
 
485
+ /**
486
+ * Configuration for artwork image requests: `artwork` and `nowPlayingArtwork`
487
+ * in BrowserConfiguration.
488
+ *
489
+ * ### Configuration Hierarchy
490
+ *
491
+ * Configs merge in this order (later overrides earlier):
492
+ * 1. `request` (base config) - shared settings like user agent, common headers
493
+ * 2. `artwork` (or `nowPlayingArtwork`) config - resource-specific settings
494
+ * 3. `resolve(track)` result - per-track overrides (if provided)
495
+ * 4. `imageQueryParams` - automatic size query params (if configured)
496
+ * 5. `transform({ request, context })` result - final changes (if provided)
497
+ *
498
+ * ### Usage Patterns
499
+ *
500
+ * **Size-aware transformation:**
501
+ * ```typescript
502
+ * artwork: {
503
+ * baseUrl: 'https://images.cdn.example.com',
504
+ * transform: async ({ request, context }) => ({
505
+ * ...request,
506
+ * query: {
507
+ * ...request.query,
508
+ * w: context?.width ? String(context.width) : '600',
509
+ * sig: await signUrl(request.path)
510
+ * }
511
+ * })
512
+ * }
513
+ * ```
514
+ *
515
+ * **Simple size params (declarative alternative):**
516
+ * ```typescript
517
+ * artwork: {
518
+ * baseUrl: 'https://images.cdn.example.com',
519
+ * imageQueryParams: { width: 'w', height: 'h' }
520
+ * }
521
+ * ```
522
+ *
523
+ * @see BrowserConfiguration.artwork - Image/artwork configuration
524
+ * @see BrowserConfiguration.nowPlayingArtwork - Now-playing artwork
525
+ */
510
526
  export interface ArtworkRequestConfig extends RequestConfig {
511
527
  /**
512
- * Per-track request resolution callback.
528
+ * Async per-track request resolution.
513
529
  *
514
530
  * Called for each track to generate the request configuration based on
515
531
  * track metadata (id, artist, album, src, etc.).
516
532
  *
517
533
  * The returned config is merged with base configs, then passed to
518
- * `transform` if provided.
534
+ * `transform` if provided. When `resolveSync` is also set, both run and the
535
+ * `resolveSync` result merges over this one.
519
536
  *
520
537
  * @param track - The track being requested
521
538
  * @returns Request configuration for this specific track
@@ -530,24 +547,24 @@ export interface ArtworkRequestConfig extends RequestConfig {
530
547
  * }
531
548
  * ```
532
549
  */
533
- /** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
534
550
  resolve?: (track: Track) => Promise<RequestConfig>
535
551
  /** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
536
552
  resolveSync?: (track: Track) => RequestConfig
537
553
 
538
554
  /**
539
- * Final transformation callback for media/artwork requests.
555
+ * Async final transform for artwork requests.
540
556
  *
541
557
  * Called after `resolve` (if provided) with the merged request config.
542
558
  * Receives optional ImageContext with size hints from Android Auto/CarPlay.
559
+ * When `transformSync` is also set, it runs after this one on its result.
543
560
  *
544
561
  * Use this for:
545
562
  * - Adding size query params dynamically
546
563
  * - URL signing
547
564
  * - Adding authentication tokens
548
565
  *
549
- * @param request - The merged request configuration
550
- * @param context - Optional image context with size hints
566
+ * @param params - `{ request, context }`: the merged request configuration
567
+ * and the optional image context with size hints
551
568
  * @returns Modified request configuration
552
569
  *
553
570
  * @example
@@ -564,7 +581,6 @@ export interface ArtworkRequestConfig extends RequestConfig {
564
581
  * }
565
582
  * ```
566
583
  */
567
- /** Async final transform. When both are set, runs BEFORE `transformSync`. */
568
584
  transform?: MediaRequestConfigTransformer
569
585
  /** Sync final transform (no Promise allocation). When both are set, runs AFTER `transform`. */
570
586
  transformSync?: MediaRequestConfigTransformerSync
@@ -572,8 +588,9 @@ export interface ArtworkRequestConfig extends RequestConfig {
572
588
  /**
573
589
  * Query parameter names for automatic context injection from CarPlay/Android Auto.
574
590
  *
575
- * When configured, the image context (size, color scheme) from CarPlay/Android Auto
576
- * is automatically added as query parameters to artwork URLs.
591
+ * When configured, the image width and height from CarPlay/Android Auto are
592
+ * added as query parameters to artwork URLs, in whole pixels, when the
593
+ * display size is known.
577
594
  *
578
595
  * This is a simpler alternative to using `transform` for context-aware URLs.
579
596
  *
@@ -605,25 +622,29 @@ export interface ArtworkRequestConfig extends RequestConfig {
605
622
  * sub-container (`path`). A callback / static `ResolvedTrack` returns the same
606
623
  * page object directly.
607
624
  *
608
- * {@link SearchSource} and {@link TabsSource} HTTP endpoints return this same
609
- * page shape; only the meaning of `children` differs (results / tabs).
625
+ * A {@link TabsSource} HTTP endpoint returns this same page shape, with the
626
+ * tabs as its `children`. A {@link SearchSource} HTTP endpoint differs: it
627
+ * returns a bare `Track[]`.
610
628
  */
611
629
  export type BrowserSource =
612
630
  | ResolvedTrack
613
631
  | BrowserSourceCallback
614
632
  | TransformableRequestConfig
615
633
 
634
+ /**
635
+ * A callback or an HTTP request config. A route's `browse` takes the wider
636
+ * {@link BrowserSource}, which also accepts a static {@link ResolvedTrack}.
637
+ */
616
638
  export type RouteSource = BrowserSourceCallback | TransformableRequestConfig
617
639
 
618
640
  /**
619
- * Route configuration with per-route media and artwork overrides.
641
+ * Route configuration with per-route browse and artwork overrides.
620
642
  *
621
643
  * @example
622
644
  * ```typescript
623
645
  * routes: {
624
646
  * '/premium': {
625
647
  * browse: async () => fetchPremiumContent(),
626
- * media: { baseUrl: 'https://premium-audio.cdn.com' },
627
648
  * artwork: { baseUrl: 'https://premium-images.cdn.com' }
628
649
  * }
629
650
  * }
@@ -632,18 +653,25 @@ export type RouteSource = BrowserSourceCallback | TransformableRequestConfig
632
653
  export type RouteConfig = {
633
654
  /** Override browse config for this route. */
634
655
  browse?: BrowserSource
635
- /** Override media config for this route. */
656
+ /**
657
+ * Not applied on any platform: media always resolves from the top-level
658
+ * `media` config.
659
+ */
636
660
  media?: MediaRequestConfig
637
661
  /** Override artwork config for this route. */
638
662
  artwork?: ArtworkRequestConfig
639
663
  }
640
664
 
665
+ /** Tabs callback: returns the tab tracks. */
641
666
  export type TabsSourceCallback = () => Track[] | Promise<Track[]>
667
+
642
668
  /**
643
669
  * Tab source configuration for navigation tabs.
644
670
  *
645
- * When using API configuration (TransformableRequestConfig), the request path
646
- * defaults to '/' and the endpoint must return a page object
671
+ * When using API configuration (TransformableRequestConfig), the web requests
672
+ * path '/', but iOS and Android request an internal placeholder path instead.
673
+ * A static `path` is ignored, so set the path in a `transform` for the same
674
+ * request on every platform. The endpoint must return a page object
647
675
  * `{ title?, children: Track[] }` whose `children` are the tabs — the same
648
676
  * shape a browse endpoint returns. Callback/static sources provide `Track[]`
649
677
  * directly.
@@ -657,15 +685,19 @@ export type TabsSource =
657
685
  * Search source configuration for handling search requests.
658
686
  *
659
687
  * **Response shape (HTTP / `TransformableRequestConfig`):** the endpoint must
660
- * return a page object — `{ title?, children: Track[] }` — whose `children`
661
- * are the result rows, the same shape a browse endpoint returns. (The web
662
- * implementation additionally accepts a bare `Track[]` for back-compat;
663
- * iOS/Android do not.) Callback sources return `Track[]` directly.
688
+ * return a bare `Track[]` of result rows, not the page object a browse
689
+ * endpoint returns. (The web implementation also accepts a page object
690
+ * `{ children: Track[] }`; iOS and Android do not.) Callback sources return
691
+ * `Track[]` directly.
664
692
  *
665
693
  * @see BrowserConfiguration.search
666
694
  */
667
695
  export type SearchSource = SearchSourceCallback | TransformableRequestConfig
668
696
 
697
+ /**
698
+ * The browser's configuration: requests, routes, tabs, search and the car
699
+ * surfaces. Pass it to `configureBrowser`.
700
+ */
669
701
  export type BrowserConfiguration = {
670
702
  /**
671
703
  * Initial navigation path. Setting this triggers initial navigation to the
@@ -766,9 +798,9 @@ export type BrowserConfiguration = {
766
798
  * the result flows through the shared `request` layer (so a relative path gets `baseUrl`
767
799
  * prepended). For logic that can't be expressed as a template, use `resolve(track)`.
768
800
  *
769
- * The `{id}` templating is specific to `nowPlayingArtwork` — static values
770
- * in other configs are not templated. Not implemented by the web
771
- * implementation.
801
+ * The same `{id}` templating applies to every artwork config (`artwork`,
802
+ * a route's `artwork`, `nowPlayingArtwork`) on iOS and Android. Neither
803
+ * `{id}` nor `nowPlayingArtwork` is implemented by the web implementation.
772
804
  *
773
805
  * @example
774
806
  * // 302-redirect endpoint keyed by the track id:
@@ -811,8 +843,8 @@ export type BrowserConfiguration = {
811
843
  * expects different names, rename them in `transform` — it receives the params
812
844
  * already on `request.query`, e.g. `query: { search: request.query?.q }`.
813
845
  *
814
- * Response shape: the endpoint must return a page object
815
- * `{ children: Track[] }` — see {@link SearchSource}.
846
+ * Response shape: the endpoint must return a bare `Track[]` — see
847
+ * {@link SearchSource}.
816
848
  *
817
849
  * @example
818
850
  * ```typescript
@@ -822,11 +854,15 @@ export type BrowserConfiguration = {
822
854
  * if (params.reference === 'my') return await getFavorites();
823
855
  * // Filters are read directly from their props (not derived from `mode`)
824
856
  * if (params.album && params.artist) {
825
- * return await db.query('SELECT * FROM tracks WHERE album = ? AND artist = ?',
826
- * [params.album, params.artist]);
857
+ * return await db.query(
858
+ * 'SELECT * FROM tracks WHERE album = ? AND artist = ?',
859
+ * [params.album, params.artist]
860
+ * );
827
861
  * }
828
862
  * if (params.artist) {
829
- * return await db.query('SELECT * FROM tracks WHERE artist = ?', [params.artist]);
863
+ * return await db.query('SELECT * FROM tracks WHERE artist = ?', [
864
+ * params.artist,
865
+ * ]);
830
866
  * }
831
867
  * // `mode` is the container vertical — narrow by it when present
832
868
  * if (params.mode === 'podcast') return await searchPodcasts(params.query);
@@ -837,8 +873,8 @@ export type BrowserConfiguration = {
837
873
  * // API configuration - parameters automatically added to query string
838
874
  * search: {
839
875
  * baseUrl: 'https://api.example.com/search',
840
- * // GET /search?q=greens&mode=album&album=greens&artist=the+radishes&limit=20
841
- * transform(request) {
876
+ * // GET /search?q=greens&album=greens&artist=the+radishes&limit=20
877
+ * transformSync(request) {
842
878
  * return {
843
879
  * ...request,
844
880
  * query: { ...request.query, limit: '20' }
@@ -854,7 +890,11 @@ export type BrowserConfiguration = {
854
890
  * The first tab's path is automatically loaded when the browser starts.
855
891
  *
856
892
  * Optional - if not provided, no tab navigation will be available.
857
- * Limited to maximum 4 tabs for automotive platform compatibility (Android Auto/CarPlay).
893
+ * Car surfaces show only the first tabs: Android Auto shows 4, CarPlay
894
+ * shows up to `CPTabBarTemplate.maximumTabCount`. `getTabs` and `useTabs`
895
+ * still return every tab, and `configureBrowser` warns in development when
896
+ * a static array has more than Android Auto shows. See
897
+ * [Tabs and the initial path](/guide/browser#tabs-and-the-initial-path).
858
898
  *
859
899
  * Can provide static array of Track objects with paths as tabs, API configuration, or custom callback.
860
900
  */
@@ -889,13 +929,14 @@ export type BrowserConfiguration = {
889
929
  * which receives `routeParams` as its second argument.
890
930
  *
891
931
  * Values can be a `BrowserSource` (callback, request config, or static page
892
- * object) or a `RouteConfig` with per-route `media`/`artwork` overrides.
932
+ * object) or a `RouteConfig` with per-route `browse`/`artwork` overrides.
893
933
  *
894
934
  * @example
895
935
  * ```typescript
896
936
  * routes: {
897
937
  * '/favorites': async () => getFavoritesPage(),
898
- * '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
938
+ * '/albums/{id}': async ({ routeParams }) =>
939
+ * fetchAlbumPage(routeParams?.id),
899
940
  * '/premium': {
900
941
  * browse: { baseUrl: 'https://premium-api.example.com' },
901
942
  * artwork: { baseUrl: 'https://premium-images.example.com' }
@@ -919,7 +960,9 @@ export type BrowserConfiguration = {
919
960
 
920
961
  /**
921
962
  * Custom handler for track load events.
922
- * When set, navigateTrack() will call this handler instead of auto-loading/playing the track.
963
+ * When set, loading a playable track (a browse-row tap or a
964
+ * `navigate(track)` call) invokes this handler instead of auto-loading and
965
+ * playing the track.
923
966
  * Pass undefined to restore default behavior.
924
967
  *
925
968
  * @param event - The track load event containing the track, queue, and startIndex
@@ -941,28 +984,16 @@ export type BrowserConfiguration = {
941
984
  androidControllerOfflineError?: boolean
942
985
 
943
986
  /**
944
- * Titles the "view more" row appended to a `Section` that carries a
945
- * `Section.path` on surfaces whose section header cannot be tapped —
946
- * Android Auto, today the only one.
987
+ * Titles the "view more" row Android Auto appends to a `Section` that
988
+ * carries a `Section.path`, one string for every section.
947
989
  *
948
- * Leave it unset and the row is titled "View more" — the library's in-code
949
- * default, the same arrangement `formatNavigationError` has. Set this to
950
- * localize it: it is re-resolved once per content generation, so
990
+ * It is re-resolved once per content generation, so
951
991
  * `invalidateAllContent()` after an in-app language switch picks up the new
952
- * copy without reconfiguring the browser. That is why it is a callback rather
953
- * than a plain string — an app whose locale is its own, not the system's,
954
- * cannot express that with a value frozen at configure time.
955
- *
956
- * One string for every section by design — the row is a fallback for a
957
- * surface that cannot draw a link in its header, so per-section wording would
958
- * be ceremony most consumers never see rendered.
992
+ * copy without reconfiguring the browser.
959
993
  *
960
- * For wording that varies by section — "View all 42 albums", "See every
961
- * episode" — author the link yourself instead: append an ordinary browsable
962
- * {@link Track} to the section's `children`, titled however you like, and
963
- * leave `Section.path` unset so this row doesn't also appear. Since the
964
- * row is Android-only, that branch is an ordinary platform check on the
965
- * content you emit; CarPlay never sees the extra row.
994
+ * For wording that varies by section, leave `Section.path` unset and append
995
+ * your own browsable {@link Track} to `children`; that Track shows on every
996
+ * surface. See [Android Auto](https://audiobrowser.dev/guide/android-auto).
966
997
  *
967
998
  * @default 'View more'
968
999
  *
@@ -994,13 +1025,13 @@ export type BrowserConfiguration = {
994
1025
  carPlayLoadingTitle?: string
995
1026
 
996
1027
  /**
997
- * Called when the album line on the CarPlay Now Playing screen is tapped
998
- * and the active track has no {@link Track.albumPath}. Return a browse path
999
- * to navigate the CarPlay browse stack there, or `undefined` if the tap was
1000
- * handled (or should do nothing).
1028
+ * Called when the active track changes and it has no {@link Track.albumPath}.
1029
+ * Return a browse path to make the album line on the CarPlay Now Playing
1030
+ * screen tappable: a tap navigates the CarPlay browse stack there. Return
1031
+ * `undefined` to leave the album line untappable for this track.
1001
1032
  *
1002
- * The album line is tappable whenever the active track has an `albumPath`
1003
- * or this callback is configured.
1033
+ * The library calls it ahead of any tap, so the album line is tappable only
1034
+ * when there is somewhere to go.
1004
1035
  *
1005
1036
  * @example
1006
1037
  * ```typescript
@@ -1014,7 +1045,8 @@ export type BrowserConfiguration = {
1014
1045
 
1015
1046
  /**
1016
1047
  * Callback to customize error messages for navigation errors.
1017
- * Used by CarPlay and available via `useFormattedNavigationError()` for app UI.
1048
+ * Used by CarPlay and Android Auto, and available via
1049
+ * `useFormattedNavigationError()` for app UI.
1018
1050
  *
1019
1051
  * If not provided or returns undefined, default English messages are used.
1020
1052
  *
@@ -1079,8 +1111,13 @@ export type FormattedNavigationError = {
1079
1111
  * Default values:
1080
1112
  * - `'content-not-found'`: "Content Not Found" (English)
1081
1113
  * - `'network-error'`: "Network Error" (English)
1082
- * - `'http-error'`: System-localized status text (e.g., "Not Found", "Service Unavailable")
1114
+ * - `'http-error'`: the status text, system-localized on iOS (e.g. "Not
1115
+ * Found", "Service Unavailable"); on Android an English name for common
1116
+ * codes. "Server Error" when there is no status code, for codes Android
1117
+ * does not name, and always on web
1083
1118
  * - `'callback-error'`: "Error" (English)
1119
+ * - `'empty-content'`: "Nothing here" (English)
1120
+ * - `'timeout'`: "Couldn't load" (English)
1084
1121
  * - `'unknown-error'`: "Error" (English)
1085
1122
  */
1086
1123
  title: string
@@ -1141,8 +1178,8 @@ export type FormatNavigationErrorCallback = (
1141
1178
  ) => FormattedNavigationError | undefined
1142
1179
 
1143
1180
  /**
1144
- * Maps the tapped active track to a browse path for the CarPlay album line,
1145
- * or `undefined` to do nothing. See `resolveAlbumPath`.
1181
+ * Maps the active track to a browse path for the CarPlay album line, or
1182
+ * `undefined` to leave the line untappable. See {@link BrowserConfiguration.resolveAlbumPath | resolveAlbumPath}.
1146
1183
  */
1147
1184
  export type ResolveAlbumPathCallback = (track: Track) => string | undefined
1148
1185