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
@@ -112,17 +112,14 @@ import timber.log.Timber
112
112
  class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
113
113
 
114
114
  /**
115
- * Nitro calls this only when JS calls `dispose()` explicitly — never on runtime teardown, which
116
- * is what [AudioBrowserLifecycleModule] is for. Both routes land here.
115
+ * Runs on an explicit JS `dispose()` and, through [disposeCurrent], on runtime teardown, which
116
+ * Nitro itself never reports.
117
117
  *
118
- * The Service outlives this object, so everything registered in `init` or on connect has to be
119
- * undone. Left alone, the running [Player] goes on invoking callbacks into a dead JSI runtime,
120
- * and every reload strands another ServiceConnection and lifecycle observer, each retaining a
121
- * BrowserManager.
122
- *
123
- * Runs the teardown on main: the state below is written from main-thread coroutines
124
- * ([onServiceConnected], [onServiceDisconnected]), while dispose itself arrives on the JS thread
125
- * or the teardown callback's thread.
118
+ * The Service outlives this object, so everything registered in `init` or on connect is undone
119
+ * here; left alone, the running [Player] calls into a dead JSI runtime and each reload strands a
120
+ * ServiceConnection and lifecycle observer. The teardown is posted to main, where
121
+ * [onServiceConnected] and [onServiceDisconnected] write the same state; dispose itself arrives
122
+ * on the JS thread or the teardown callback's thread.
126
123
  */
127
124
  override fun dispose() {
128
125
  current.compareAndSet(this, null)
@@ -131,10 +128,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
131
128
  // Only when still ours: on a reload the replacement may already own the slot.
132
129
  carConnectionTarget.compareAndSet(onCarConnectedChanged, null)
133
130
 
134
- // The runtime behind the config's JS functions is going away, but anything still holding
135
- // this instance (an in-flight browse coroutine, the running player) can invoke them after
136
- // it's gone — each invoke then throws instead of answering, so browse takes its error path
137
- // rather than its fallback.
138
131
  dropStaleJSCallbacks()
139
132
 
140
133
  handler.post {
@@ -145,9 +138,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
145
138
  if (service.player.browser === this) {
146
139
  service.player.browser = null
147
140
  service.player.forgetBrowserRegistration()
148
- // The formatter wraps a JS callback from this instance's runtime (installed by our
149
- // setup(); browser still being ours means no replacement has run setup yet). Without
150
- // this, every track change until the next setup() throws into the updater's fallback.
141
+ // It wraps a JS callback from this runtime: left set, every track change throws into the
142
+ // now-playing updater's fallback until the next setup().
151
143
  service.player.nowPlaying.formatter = null
152
144
  }
153
145
  if (service.onBatteryWarningPendingChanged === onBatteryWarningPending) {
@@ -156,7 +148,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
156
148
  }
157
149
  connectedService = null
158
150
 
159
- // Dropping the reference disconnects nothing — the controller stays in the session's
151
+ // Dropping the reference disconnects nothing: the controller stays in the session's
160
152
  // connected list, holding a binder and a listener.
161
153
  mediaBrowserFuture?.let { MediaBrowser.releaseFuture(it) }
162
154
  mediaBrowserFuture = null
@@ -165,7 +157,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
165
157
  serviceBinding.unbind(this)
166
158
 
167
159
  ProcessLifecycleOwner.get().lifecycle.removeObserver(lifecycleObserver)
168
- // After the observer removal, so this post is not the one dropped.
160
+ // Inside this post: run from dispose() after the post, it would drop the teardown itself.
169
161
  handler.removeCallbacksAndMessages(null)
170
162
  mainScope.cancel()
171
163
  }
@@ -173,11 +165,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
173
165
  }
174
166
 
175
167
  /**
176
- * Demotes the config to data-only (deep strip of every JS function field) and reverts the JS
177
- * callbacks stored outside the config tree ([resolveGate]; the now-playing formatter is cleared
178
- * in [dispose]'s service block, identity-guarded). Stale paths then degrade the same way as a
179
- * config that never had callbacks — static request/browse layers, default error copy, fail-closed
180
- * gate — instead of throwing into the error path. Mirrors iOS `dropStaleJSCallbacks`, where the
168
+ * Strips every JS function from the config, at every depth, and reverts [resolveGate]: anything
169
+ * still holding this instance (an in-flight browse, the running player) can invoke them after the
170
+ * runtime is gone. Those paths then degrade like a config that never had callbacks (static
171
+ * layers, default error copy, fail-closed gate) instead of throwing into the error path. The
172
+ * now-playing formatter is cleared in [dispose]. Mirrors iOS `dropStaleJSCallbacks`, where the
181
173
  * same invoke is fatal rather than a throw.
182
174
  */
183
175
  private fun dropStaleJSCallbacks() {
@@ -229,26 +221,24 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
229
221
  private var updateOptions: PlayerUpdateOptions = PlayerUpdateOptions()
230
222
  private var mediaBrowserFuture: ListenableFuture<MediaBrowser>? = null
231
223
  private var setupOptions = PlayerSetupOptions()
232
- // Written only on the main thread (ServiceConnection callbacks, dispose); read from main or,
233
- // in a few places, straight from the JS thread. @Volatile gives those reads visibility — they
234
- // must still tolerate staleness in both directions (a just-detached service, or null while
235
- // onServiceConnected is pending). Keep writes on main; no read-modify-write.
224
+ // Written only on main (ServiceConnection callbacks, dispose); read on main and, in places,
225
+ // straight from the JS thread, where it may be stale either way: a just-detached service, or
226
+ // null while onServiceConnected is pending. Keep writes on main; no read-modify-write.
236
227
  @Volatile private var connectedService: Service? = null
237
228
 
238
229
  private val serviceBinding = ServiceBinding(context)
239
230
 
240
- /** Held rather than inlined so [dispose] can tell its own wiring from a replacement's. */
231
+ // Held rather than inlined so [dispose] can tell its own wiring from a replacement's.
241
232
  private val onBatteryWarningPending: (Boolean) -> Unit = { pending ->
242
233
  post { onBatteryWarningPendingChanged(BatteryWarningPendingChangedEvent(pending)) }
243
234
  }
244
235
  private var setupPromise: ((Unit) -> Unit)? = null
245
236
 
246
- // Initial player state staged before the player exists — from setup options or the imperative
247
- // setters called pre-bind. Strict last-write-wins; consumed when the player comes up.
237
+ // Staged by setup options or by setters called before the player exists; last write wins, and
238
+ // [applyPendingPlayerState] consumes them.
248
239
  private var pendingPlayWhenReady: Boolean? = null
249
240
  private var pendingRepeatMode: RepeatMode? = null
250
241
 
251
- /** Post callback to main handler for consistent async delivery to JS - avoids deadlocks */
252
242
  private fun post(block: () -> Unit) = handler.post(block)
253
243
 
254
244
  // MARK: Browser callbacks
@@ -259,12 +249,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
259
249
  override var onFormattedNavigationError: (FormattedNavigationError?) -> Unit = {}
260
250
 
261
251
  // MARK: Gate callbacks (native→JS; set from JS, native CALLS them)
262
- // Default resolver: only reachable while hasResolver=true but no live runtime has the real
263
- // `resolveGate` bound — the init window before JS assigns it, or after [dispose] reverts a dead
264
- // runtime's resolver. It DENIES by default
265
- // (gated=true) so an active gate never serves content during that window — same fail-closed
266
- // direction as the resolver-error path in [gateDecision]. The static-gate fast path skips it
267
- // entirely once a resolver-less gate is set.
252
+ // Denies by default: it is reached only while a resolver is declared but none from a live
253
+ // runtime is bound (before JS assigns one, or after [dispose] reverts it), and an active gate
254
+ // must not serve content in that window.
268
255
  override var resolveGate: (request: NativeGateRequest) -> Promise<Promise<GateDecision>> =
269
256
  defaultResolveGate
270
257
  override var onGate: (event: GateEvent) -> Unit = {}
@@ -321,7 +308,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
321
308
  override var handleRemoteSkip: (() -> Unit)? = null
322
309
  override var handleRemoteStop: (() -> Unit)? = null
323
310
 
324
- /** Lifecycle observer to check battery status when app comes to foreground */
325
311
  private val lifecycleObserver =
326
312
  object : DefaultLifecycleObserver {
327
313
  override fun onStart(owner: LifecycleOwner) {
@@ -332,7 +318,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
332
318
  init {
333
319
  current.set(this)
334
320
 
335
- // Auto-bind to service if it's already running
336
321
  launchInScope {
337
322
  try {
338
323
  Timber.d("Attempting to auto-bind to existing AudioBrowserService from AudioBrowser")
@@ -348,18 +333,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
348
333
  }
349
334
  }
350
335
 
351
- // Observe app lifecycle to check battery status on foreground
352
- // Must run on main thread as required by LifecycleRegistry.addObserver
336
+ // LifecycleRegistry.addObserver asserts the main thread.
353
337
  handler.post { ProcessLifecycleOwner.get().lifecycle.addObserver(lifecycleObserver) }
354
338
 
355
- // Observe system volume changes
356
339
  systemVolumeMonitor.setOnVolumeChanged { volume -> post { onSystemVolumeChanged(volume) } }
357
340
 
358
- // Observe current audio output changes (active media route via AudioManager)
359
341
  outputMonitor.setOnOutputChanged { output -> post { onOutputChanged(output) } }
360
342
  outputMonitor.start()
361
343
 
362
- // Observe the car connection (Android Auto / Android Automotive)
363
344
  startCarConnectionObserver(context, handler)
364
345
  }
365
346
 
@@ -384,10 +365,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
384
365
  }
385
366
 
386
367
  /**
387
- * Media URL transformation for [com.audiobrowser.player.TransformingDataSource]. Resolution lives
388
- * in [resolveMediaUrl] (browser/BrowserUrlResolution.kt); this shell owns only the blocking
389
- * bridge: it runs on ExoPlayer's IO thread (TransformingDataSource.open), so blocking here is
390
- * safe and intentional.
368
+ * The request config for [originalUrl], or null when resolution fails. Blocks: it is called from
369
+ * [com.audiobrowser.player.TransformingDataSource.open] on ExoPlayer's loading thread, never main
370
+ * or JS.
391
371
  */
392
372
  fun getMediaRequestConfig(originalUrl: String, track: Track): MediaRequestConfig? {
393
373
  return try {
@@ -399,15 +379,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
399
379
  }
400
380
 
401
381
  private fun hasValidConfiguration(): Boolean {
402
- // Need at least one browsable route (not just search)
403
382
  return _configuration.routes?.any { it.path != BrowserManager.SEARCH_ROUTE_PATH } == true
404
383
  }
405
384
 
406
- // Suspending on purpose: queryTabs() resolves tabs by invoking JS callbacks,
407
- // which can only run on the JS thread. Callers MUST invoke this from a
408
- // coroutine (off the JS thread) — never via runBlocking on a synchronous Nitro
409
- // setter, which runs on the JS thread and would deadlock (the JS thread blocks
410
- // waiting for callbacks that need that same thread to run).
385
+ // Suspends because queryTabs() invokes JS callbacks, which run on the JS thread. Never call it
386
+ // through runBlocking from a Nitro setter: that runs on the JS thread and deadlocks waiting for
387
+ // callbacks that need it.
411
388
  private suspend fun getDefaultPath(): String? {
412
389
  return try {
413
390
  browserManager.config = buildConfig()
@@ -420,7 +397,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
420
397
  "/"
421
398
  }
422
399
  } catch (e: CancellationException) {
423
- throw e // Rethrow so cooperative cancellation isn't swallowed
400
+ throw e
424
401
  } catch (e: Exception) {
425
402
  Timber.e(e, "Failed to get default path, falling back to /")
426
403
  "/"
@@ -438,19 +415,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
438
415
  browserManager.config = buildConfig()
439
416
  clearNavigationError()
440
417
 
441
- // Cancel previous navigation to avoid race conditions
442
418
  navigationJob?.cancel()
443
419
 
444
- // Resolve the default path inside the coroutine (getDefaultPath queries
445
- // tabs via JS callbacks) so it never blocks the JS thread this setter
446
- // runs on.
447
420
  navigationJob =
448
421
  mainScope.launch {
449
422
  val path = value ?: getDefaultPath() ?: return@launch
450
423
  try {
451
424
  browserManager.navigate(path)
452
425
  } catch (e: CancellationException) {
453
- throw e // Rethrow to properly cancel
426
+ throw e
454
427
  } catch (e: Exception) {
455
428
  handleBrowserException(e, path, "setting path: $path")
456
429
  }
@@ -468,33 +441,22 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
468
441
  _configuration = value
469
442
  browserManager.config = buildConfig()
470
443
 
471
- // Notify player that browser configuration is ready (routes/tabs available)
472
- // This allows Android Auto to start browsing content.
473
- // This reaches MediaSession.getConnectedControllers, which asserts the
474
- // main thread, and this setter runs on the JS thread. Hop without
475
- // blocking -- runBlockingOnMain would deadlock here for the same reason
476
- // described for the navigation below (JS callbacks can't run while the
477
- // JS thread waits). Ordering with navigationJob is preserved: both are
478
- // queued on mainScope.
444
+ // Reaches MediaSession, which asserts the main thread, from this JS-thread setter. Launched,
445
+ // not blocked: what it triggers can wait on JS callbacks, which cannot run while the JS
446
+ // thread waits. Queued on mainScope ahead of navigationJob, so the two stay ordered.
479
447
  launchInScope { connectedService?.player?.notifyBrowserConfigurationReady() }
480
448
 
481
449
  clearNavigationError()
482
450
 
483
- // Cancel previous navigation to avoid race conditions
484
451
  navigationJob?.cancel()
485
452
 
486
- // Navigate to the initial path, or default to the first tab. The default
487
- // path is resolved inside the coroutine (getDefaultPath queries tabs via
488
- // JS callbacks) so it never blocks the JS thread this setter runs on —
489
- // doing it synchronously here via runBlocking deadlocked: the JS callbacks
490
- // can't run because the JS thread is blocked waiting for them.
491
453
  navigationJob =
492
454
  mainScope.launch {
493
455
  val path = value.path ?: getDefaultPath() ?: return@launch
494
456
  try {
495
457
  browserManager.navigate(path)
496
458
  } catch (e: CancellationException) {
497
- throw e // Rethrow to properly cancel
459
+ throw e
498
460
  } catch (e: Exception) {
499
461
  handleBrowserException(e, path, "setting configuration path: $path")
500
462
  }
@@ -509,9 +471,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
509
471
  override fun getFormattedNavigationError(): FormattedNavigationError? = formattedNavigationError
510
472
 
511
473
  /**
512
- * Resolves a navigation error to its display form: the app's `formatNavigationError` for the
513
- * given [path] when one is configured, else the built-in default. Shared by [setNavigationError]
514
- * and the Android Auto empty tile so in-app and in-car copy cannot drift (ADR 0001).
474
+ * The display form of [error] at [path]: the app's `formatNavigationError` when configured, else
475
+ * the built-in default. Shared with the Android Auto empty tile so in-app and in-car copy cannot
476
+ * drift (ADR 0001).
515
477
  */
516
478
  internal suspend fun resolveFormattedError(
517
479
  error: NavigationError,
@@ -536,9 +498,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
536
498
  navigationError = navError
537
499
  onNavigationError(NavigationErrorEvent(navigationError))
538
500
 
539
- // No formatter means no hop, and the field and event land in this turn: a same-turn
540
- // getFormattedNavigationError, or a clearNavigationError right after, must not race a
541
- // launch that has yet to run.
501
+ // Without a formatter the field and event land in this turn, so a same-turn
502
+ // getFormattedNavigationError or clearNavigationError cannot race a launch yet to run.
542
503
  if (_configuration.formatNavigationError == null) {
543
504
  val default = defaultFormattedError(navError)
544
505
  formattedNavigationError = default
@@ -553,7 +514,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
553
514
  }
554
515
  }
555
516
 
556
- /** Raises the navigation error [e] maps to, for a failed navigation to [path]. */
557
517
  private fun handleBrowserException(e: Exception, path: String, logContext: String) {
558
518
  val navError = navigationErrorFor(e)
559
519
  Timber.e(e, "${navError.code} $logContext")
@@ -576,7 +536,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
576
536
  override fun navigatePath(path: String) {
577
537
  clearNavigationError()
578
538
 
579
- // Cancel previous navigation to avoid race conditions
580
539
  navigationJob?.cancel()
581
540
 
582
541
  navigationJob =
@@ -585,7 +544,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
585
544
  Timber.d("Navigating to path: $path")
586
545
  browserManager.navigate(path)
587
546
  } catch (e: CancellationException) {
588
- throw e // Rethrow to properly cancel
547
+ throw e
589
548
  } catch (e: Exception) {
590
549
  handleBrowserException(e, path, "navigating to path: $path")
591
550
  }
@@ -593,11 +552,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
593
552
  }
594
553
 
595
554
  override fun navigateTrack(track: Track) {
596
- // A disabled track is unavailable — it never plays, whichever surface or
597
- // stale resume path delivered the selection (Track.disabled; mirrors iOS
598
- // TrackSelector.select). Refused before any state changes: an inert tap
599
- // must not clear an unrelated navigation error or cancel an in-flight
600
- // navigation.
555
+ // A disabled track never plays, whichever surface delivered it (mirrors iOS
556
+ // TrackSelector.select). Refused before any state changes: an inert tap must not clear an
557
+ // unrelated navigation error or cancel an in-flight navigation.
601
558
  if (track.disabled == true) {
602
559
  Timber.d("Ignoring selection of disabled track: ${track.title}")
603
560
  return
@@ -605,7 +562,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
605
562
 
606
563
  clearNavigationError()
607
564
 
608
- // Cancel previous navigation to avoid race conditions
609
565
  navigationJob?.cancel()
610
566
 
611
567
  val path = track.path
@@ -613,16 +569,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
613
569
  mainScope.launch {
614
570
  try {
615
571
  when {
616
- // Check if this is a contextual path (playable-only track with queue context)
617
572
  path != null && BrowserPathHelper.isContextual(path) -> {
618
573
  Timber.d("Navigating to contextual track path: $path")
619
574
 
620
575
  val parentPath = BrowserPathHelper.stripTrackId(path)
621
576
  val trackId = BrowserPathHelper.extractTrackId(path)
622
577
 
623
- // Check if queue already came from this parent path - just skip
624
- // to the tapped surface (exact path first, identity for
625
- // index-less paths — see indexOfTappedTrack)
626
578
  if (trackId != null && parentPath == player.queueSourcePath) {
627
579
  val index = player.tracks.indexOfTappedTrack(path, trackId)
628
580
  if (index >= 0) {
@@ -642,7 +594,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
642
594
  }
643
595
  }
644
596
 
645
- // Expand the queue from the contextual path
646
597
  val expanded = browserManager.expandQueueFromContextualPath(path)
647
598
 
648
599
  if (expanded != null) {
@@ -657,15 +608,13 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
657
608
  startIndex.toDouble(),
658
609
  intercepted = {},
659
610
  defaultBehavior = {
660
- // Replace queue and seek to selected track
661
- // Use internal player methods directly to avoid blocking on main thread
611
+ // The Player itself: this class's overrides block on main, where this runs.
662
612
  player.setQueue(tracks, startIndex, sourcePath = parentPath)
663
613
  player.play()
664
614
  },
665
615
  )
666
616
  return@launch
667
617
  } else {
668
- // Fallback: just load the single track
669
618
  Timber.w("Queue expansion failed, loading single track")
670
619
  handleTrackLoad(
671
620
  _configuration.handleTrackLoad,
@@ -677,12 +626,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
677
626
  )
678
627
  }
679
628
  }
680
- // Navigate to browsable track to show browsing UI
681
629
  path != null -> {
682
630
  Timber.d("Navigating to browsable track: $path")
683
631
  browserManager.navigate(path)
684
632
  }
685
- // If track is playable (has src), load it into player
686
633
  track.src != null -> {
687
634
  Timber.d("Loading playable track into player: ${track.title}")
688
635
  handleTrackLoad(
@@ -699,7 +646,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
699
646
  }
700
647
  }
701
648
  } catch (e: CancellationException) {
702
- throw e // Rethrow to properly cancel
649
+ throw e
703
650
  } catch (e: Exception) {
704
651
  handleBrowserException(e, path ?: track.src ?: "", "navigating to track: ${track.title}")
705
652
  }
@@ -709,9 +656,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
709
656
  override fun search(query: String): Promise<Array<Track>> {
710
657
  return Promise.async(mainScope) {
711
658
  Timber.d("Searching for: $query")
712
- // Rejects with the error the browse surface would raise, but leaves the navigation error
713
- // itself unset: a search is not a navigation, and its failure must not replace the
714
- // displayed page's state (mirrors HybridAudioBrowser.search).
659
+ // Rejects with the error a browse would raise but leaves the navigation error unset: a failed
660
+ // search must not replace the displayed page's state (mirrors iOS HybridAudioBrowser.search).
715
661
  val searchResults =
716
662
  try {
717
663
  browserManager.search(query)
@@ -721,9 +667,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
721
667
  Timber.e(e, "Search failed for query: $query")
722
668
  throw NavigationErrorException(navigationErrorFor(e))
723
669
  }
724
- // Flattened, not `children`: a resolved page carries its rows in
725
- // `sections` (ADR 0010) and search builds exactly one untitled section,
726
- // so `children` is always null here and this returned nothing at all.
670
+ // Not `children`: search builds one untitled section (ADR 0010), so `children` is null.
727
671
  searchResults.flattenedChildren?.toTypedArray() ?: emptyArray()
728
672
  }
729
673
  }
@@ -735,14 +679,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
735
679
  override fun notifyContentChanged(path: String) {
736
680
  Timber.d("Notifying content changed for path: $path")
737
681
 
738
- // Invalidate cached content so future navigations fetch fresh data
739
682
  browserManager.invalidateContentCache(path)
740
683
 
741
- // Notify external media controllers (Android Auto). Reaches MediaSession,
742
- // which asserts the main thread; this override runs on the JS thread.
684
+ // MediaSession asserts the main thread; this override runs on the JS thread.
743
685
  launchInScope { connectedService?.player?.notifyContentChanged(path) }
744
686
 
745
- // If we're currently viewing this path, refresh the content
746
687
  if (browserManager.getPath() == path) {
747
688
  mainScope.launch { browserManager.refresh() }
748
689
  }
@@ -751,15 +692,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
751
692
  override fun invalidateAllContent() {
752
693
  Timber.d("Invalidating all content")
753
694
 
754
- // Clear all cached content so every path re-fetches fresh data
755
695
  browserManager.clearContentCache()
756
696
 
757
- // Notify external media controllers (Android Auto) to refresh subscribed paths.
758
- // Reaches MediaSession, which asserts the main thread; this override runs on
759
- // the JS thread.
697
+ // MediaSession asserts the main thread; this override runs on the JS thread.
760
698
  launchInScope { connectedService?.player?.invalidateAllContent() }
761
699
 
762
- // Refresh whatever the browser is currently viewing
763
700
  mainScope.launch { browserManager.refresh() }
764
701
  }
765
702
 
@@ -769,74 +706,47 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
769
706
 
770
707
  // MARK: Gate
771
708
 
772
- /** A gate decision for one request: whether to gate, and which chrome to render. */
709
+ /** [chrome] is non-null whenever [gated] is true: the serve sites force-unwrap it. */
773
710
  data class GateOutcome(val gated: Boolean, val chrome: Gate?)
774
711
 
775
- // The minimal chrome rendered when a gate is active but no override or stored
776
- // default chrome exists (the resolver-only setGate overload).
777
712
  private val builtInGate = Gate("Unavailable", null)
778
713
 
779
- /**
780
- * The three gate fields as one immutable triple so [gateDecision] reads them as a unit. Written
781
- * from the JS thread, read from the Media3 application thread (the enforcement sites in
782
- * MediaSessionCallback consult it) — hence the single field is @Volatile.
783
- *
784
- * Folding the three former @Volatile fields into one reference is what makes the read atomic:
785
- *
786
- * @Volatile gives per-field visibility but NO atomicity across a compound read, so reading three
787
- * separate volatiles in [gateDecision] could interleave with a concurrent [clearGate] and yield
788
- * a torn `(active=true, chrome=null)` state that crashed the force-unwrap at the serve sites.
789
- * One volatile reference read once cannot tear.
790
- */
714
+ // One volatile reference, so [gateDecision] reads all three fields at once: separate volatiles
715
+ // could tear against [clearGate] into an active gate with no chrome. Written on the JS thread,
716
+ // read on the Media3 application thread.
791
717
  private data class GateState(val active: Boolean, val chrome: Gate?, val hasResolver: Boolean)
792
718
 
793
719
  @Volatile private var gateState = GateState(active = false, chrome = null, hasResolver = false)
794
720
 
795
721
  override fun setGate(gate: Gate?, hasResolver: Boolean) {
796
- // Single atomic assignment — readers never see a half-updated triple.
797
722
  gateState = GateState(active = true, chrome = gate, hasResolver = hasResolver)
798
- // Re-query every subscribed parent so a connected controller (Android
799
- // Auto) swaps its lists for the gate tile without reconnecting. Notify
800
- // only — the content cache stays warm for when the gate clears.
723
+ // Re-queries every subscribed parent so a connected controller swaps its lists for the gate
724
+ // tile without reconnecting; the content cache stays warm for when the gate clears.
801
725
  // MediaSession asserts the main thread; this override runs on the JS thread.
802
726
  launchInScope { connectedService?.player?.invalidateAllContent() }
803
727
  }
804
728
 
805
729
  override fun clearGate() {
806
730
  if (!gateState.active) return
807
- // Single atomic assignment — readers never see a half-cleared triple.
808
731
  gateState = GateState(active = false, chrome = null, hasResolver = false)
809
732
  // MediaSession asserts the main thread; this override runs on the JS thread.
810
733
  launchInScope { connectedService?.player?.invalidateAllContent() }
811
734
  }
812
735
 
813
736
  /**
814
- * The single gate choke point. Each enforcement site (browse / search) calls this for the current
815
- * request and serves the gate chrome when [GateOutcome.gated] is true. Structurally similar to
816
- * the iOS `gateDecision(for:)` helper, but note the concurrency model differs: iOS confines gate
817
- * state to `@MainActor`; here the consistent read comes from snapshotting the single [gateState]
818
- * reference once (see [GateState]).
819
- * - No active gate → allow.
820
- * - Active gate, no resolver → static fast path: gate with the stored default chrome (or built-in
821
- * if none), no JS hop.
822
- * - Active gate with a resolver → ask JS per request. A resolver that throws / rejects / times
823
- * out FAILS CLOSED by design: while a gate is active the consumer has declared content blocked,
824
- * so the only safe fallback when we cannot compute the per-request decision is the gate's own
825
- * chrome — never the content. A *successful* `gated:false` still allows. Chrome order on a
826
- * gated decision: override → stored default → built-in.
827
- *
828
- * Every gated return guards chrome against null (`?: builtInGate`) so a gated outcome always
829
- * carries a renderable chrome — the serve sites force-unwrap it.
737
+ * Whether [request] is gated, and with which chrome. No active gate allows; a gate without a
738
+ * resolver gates with its stored chrome and never asks JS. A resolver that throws, rejects or
739
+ * times out fails closed, gating rather than serving content; only a successful `gated: false`
740
+ * allows. Chrome falls back from the resolver's to the stored one to [builtInGate].
830
741
  */
831
742
  suspend fun gateDecision(request: NativeGateRequest): GateOutcome {
832
- // Read the whole gate triple once; a single volatile reference can't tear (see [GateState]).
833
743
  val s = gateState
834
744
  if (!s.active) return GateOutcome(false, null)
835
- if (!s.hasResolver) return GateOutcome(true, s.chrome ?: builtInGate) // static fast path
745
+ if (!s.hasResolver) return GateOutcome(true, s.chrome ?: builtInGate)
836
746
  val decision =
837
747
  runCatching { resolveGate(request).await().await() }.getOrNull()
838
- ?: return GateOutcome(true, s.chrome ?: builtInGate) // fail CLOSED on resolver error
839
- if (!decision.gated) return GateOutcome(false, null) // explicit allow
748
+ ?: return GateOutcome(true, s.chrome ?: builtInGate)
749
+ if (!decision.gated) return GateOutcome(false, null)
840
750
  return GateOutcome(true, decision.gate ?: s.chrome ?: builtInGate)
841
751
  }
842
752
 
@@ -848,8 +758,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
848
758
  set(value) {
849
759
  field = value
850
760
  carConnectionTarget.set(value)
851
- // Immediately notify current state (the car may have connected before
852
- // this JS runtime subscribed) — mirrors the iOS behavior.
761
+ // The car may have connected before this runtime subscribed (mirrors iOS).
853
762
  value(carConnected)
854
763
  }
855
764
 
@@ -860,9 +769,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
860
769
  override fun setupPlayer(options: NativeSetupPlayerOptions): Promise<Unit> {
861
770
  return Promise.async(mainScope) {
862
771
  setupOptions.update(options)
863
- // The bundled runtime options and initial state are part of the atomic launch
864
- // description: stage them here, apply them together with the engine below (or at
865
- // service connect). Last-write-wins with their imperative counterparts.
772
+ // Staged to apply together with the engine below, or at service connect. Last write wins
773
+ // against the imperative setters.
866
774
  options.options?.let { updateOptions.updateFromBridge(it) }
867
775
  options.repeatMode?.let { pendingRepeatMode = it }
868
776
  options.playWhenReady?.let { pendingPlayWhenReady = it }
@@ -874,7 +782,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
874
782
  return@async
875
783
  }
876
784
 
877
- // Service not connected yet, bind to service
878
785
  suspendCoroutine<Unit> { continuation ->
879
786
  Timber.d("Binding to AudioBrowserService")
880
787
  val bound = serviceBinding.bind(Intent(context, Service::class.java), this@AudioBrowser)
@@ -884,7 +791,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
884
791
  RuntimeException("Failed to bind to AudioBrowserService")
885
792
  )
886
793
  } else {
887
- // Service will resolve the promise in onServiceConnected
888
794
  setupPromise = { continuation.resume(Unit) }
889
795
  }
890
796
  }
@@ -893,22 +799,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
893
799
 
894
800
  override fun updateOptions(options: NativeUpdateOptions) {
895
801
  updateOptions.updateFromBridge(options)
896
- // Only update the options if the service is around.
897
- // applyOptions touches the Media3 player, which asserts it is only ever
898
- // driven from the main thread ("Player callback method is called from a
899
- // wrong thread"). Nitro invokes this from the JS thread, so hop.
900
- //
901
- // The hop blocks rather than launching because `updateOptions` is a single
902
- // mutable holder: updateFromBridge mutates it in place on the JS thread and
903
- // applyOptions reads it on main. Blocking is what keeps the two ordered.
802
+ // Blocks rather than launches: updateFromBridge mutates the holder in place on the JS thread
803
+ // and applyOptions reads it on main (Media3 asserts main), so blocking keeps the two ordered.
904
804
  connectedService?.let { service ->
905
805
  runBlockingOnMain { service.player.applyOptions(updateOptions) }
906
806
  }
907
807
  }
908
808
 
909
809
  override fun getOptions(): Options {
910
- // The holder is the source of truth whether or not the player exists yet — updateOptions
911
- // merges into it and setup/connect applies it to the player.
912
810
  return updateOptions.toNitro()
913
811
  }
914
812
 
@@ -926,8 +824,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
926
824
  commandPlayer("reset") { player ->
927
825
  player.stop()
928
826
  player.clear()
929
- // clear() while IDLE emits no engine event, so the state machine never
930
- // leaves STOPPED — a reset queue is "nothing loaded".
827
+ // clear() while idle emits no engine event, so the state would otherwise stay STOPPED.
931
828
  player.setPlaybackState(PlaybackState.NONE)
932
829
  }
933
830
 
@@ -940,7 +837,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
940
837
  override fun stop() = commandPlayer("stop") { it.stop() }
941
838
 
942
839
  override fun setPlayWhenReady(playWhenReady: Boolean) = runBlockingOnMain {
943
- // Pre-setup this stages the intent for the player to come up with — never throws.
944
840
  connectedService?.player?.let { it.playWhenReady = playWhenReady }
945
841
  ?: run { pendingPlayWhenReady = playWhenReady }
946
842
  }
@@ -990,7 +886,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
990
886
  }
991
887
 
992
888
  override fun setRepeatMode(mode: RepeatMode) = runBlockingOnMain {
993
- // Pre-setup this stages the mode for the player to come up with — never throws.
994
889
  connectedService?.player?.let { it.repeatMode = mode } ?: run { pendingRepeatMode = mode }
995
890
  }
996
891
 
@@ -1064,7 +959,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1064
959
 
1065
960
  override fun setActiveTrackFavorited(favorited: Boolean): Unit =
1066
961
  commandPlayer("setActiveTrackFavorited") { player ->
1067
- // Applied-result is for MediaSession honesty; the JS API stays fire-and-forget.
962
+ // The applied result serves MediaSession; the JS API is fire-and-forget.
1068
963
  player.setActiveTrackFavorited(favorited)
1069
964
  }
1070
965
 
@@ -1165,14 +1060,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1165
1060
  // MARK: Battery Optimization (Android only)
1166
1061
  // ============================================================================
1167
1062
 
1168
- /** Track last known status for change detection */
1169
1063
  private var lastKnownBatteryStatus: BatteryOptimizationHelper.Status? = null
1170
1064
 
1171
1065
  override fun getBatteryWarningPending(): Boolean {
1172
1066
  val rawPending = BatteryWarningStore.isWarningPending(context)
1173
1067
  val status = BatteryOptimizationHelper.getStatus(context)
1174
1068
 
1175
- // Auto-clear if status is now unrestricted
1176
1069
  return if (rawPending && status == BatteryOptimizationHelper.Status.UNRESTRICTED) {
1177
1070
  BatteryWarningStore.clearWarning(context)
1178
1071
  post { onBatteryWarningPendingChanged(BatteryWarningPendingChangedEvent(false)) }
@@ -1195,10 +1088,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1195
1088
  BatteryOptimizationHelper.openSettings(context)
1196
1089
  }
1197
1090
 
1198
- /**
1199
- * Check if battery status changed since last check and fire events if so. Called automatically
1200
- * when app comes to foreground via ProcessLifecycleOwner.
1201
- */
1202
1091
  private fun checkBatteryStatusChange() {
1203
1092
  val currentStatus = BatteryOptimizationHelper.getStatus(context)
1204
1093
  if (lastKnownBatteryStatus != null && lastKnownBatteryStatus != currentStatus) {
@@ -1208,7 +1097,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1208
1097
  )
1209
1098
  }
1210
1099
 
1211
- // Auto-clear warning if now unrestricted
1212
1100
  if (
1213
1101
  currentStatus == BatteryOptimizationHelper.Status.UNRESTRICTED &&
1214
1102
  BatteryWarningStore.isWarningPending(context)
@@ -1240,19 +1128,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1240
1128
  player.applyOptions(updateOptions)
1241
1129
  player.setup(setupOptions)
1242
1130
  applyPendingPlayerState(player)
1243
- // Start observing network connectivity changes
1244
1131
  player.observeNetworkConnectivity(mainScope)
1245
- // Set browser reference for media URL transformation
1246
1132
  player.browser = this@AudioBrowser
1247
1133
 
1248
- // If configuration was already set before service connected,
1249
- // notify player now so Android Auto can start browsing
1134
+ // The configuration setter's notify finds no service when it runs before connect.
1250
1135
  if (_configuration.routes?.isNotEmpty() == true) {
1251
1136
  player.notifyBrowserConfigurationReady()
1252
1137
  }
1253
1138
  }
1254
1139
 
1255
- // Wire up battery warning callback from service
1256
1140
  connectedService?.onBatteryWarningPendingChanged = onBatteryWarningPending
1257
1141
 
1258
1142
  val sessionToken = SessionToken(context, ComponentName(context, Service::class.java))
@@ -1263,10 +1147,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1263
1147
  }
1264
1148
  }
1265
1149
 
1266
- /**
1267
- * Applies initial player state staged before the player existed. Consumed on apply so a later
1268
- * re-setup doesn't replay stale state.
1269
- */
1150
+ // Consumes what it applies, so a later re-setup does not replay stale state.
1270
1151
  private fun applyPendingPlayerState(player: Player) {
1271
1152
  pendingRepeatMode?.let {
1272
1153
  player.repeatMode = it
@@ -1293,6 +1174,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1293
1174
  mainScope.launch { block() }
1294
1175
  }
1295
1176
 
1177
+ // For calls arriving on the JS thread: called on main it waits on itself and deadlocks.
1296
1178
  private fun <T> runBlockingOnMain(block: suspend () -> T): T {
1297
1179
  return runBlocking(mainScope.coroutineContext) { block() }
1298
1180
  }
@@ -1300,10 +1182,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1300
1182
  private val service: Service
1301
1183
  get() = connectedService ?: throw Exception("Player not initialized")
1302
1184
 
1303
- /**
1304
- * The player while its service is connected: not before setupPlayer, nor while the service
1305
- * restarts.
1306
- */
1307
1185
  private val connectedPlayer: Player?
1308
1186
  get() = connectedService?.player
1309
1187
 
@@ -1400,7 +1278,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1400
1278
  true
1401
1279
  } ?: false
1402
1280
 
1403
- // Defer notification until after play operation completes
1404
1281
  post { this@AudioBrowser.onRemotePlay() }
1405
1282
 
1406
1283
  return handled
@@ -1413,7 +1290,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1413
1290
  true
1414
1291
  } ?: false
1415
1292
 
1416
- // Defer notification until after pause operation completes
1417
1293
  post { this@AudioBrowser.onRemotePause() }
1418
1294
 
1419
1295
  return handled
@@ -1426,7 +1302,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1426
1302
  true
1427
1303
  } ?: false
1428
1304
 
1429
- // Defer notification until after stop operation completes
1430
1305
  post { this@AudioBrowser.onRemoteStop() }
1431
1306
 
1432
1307
  return handled
@@ -1439,7 +1314,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1439
1314
  true
1440
1315
  } ?: false
1441
1316
 
1442
- // Defer notification until after next operation completes
1443
1317
  post { this@AudioBrowser.onRemoteNext() }
1444
1318
 
1445
1319
  return handled
@@ -1452,7 +1326,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1452
1326
  true
1453
1327
  } ?: false
1454
1328
 
1455
- // Defer notification until after previous operation completes
1456
1329
  post { this@AudioBrowser.onRemotePrevious() }
1457
1330
 
1458
1331
  return handled
@@ -1465,7 +1338,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1465
1338
  true
1466
1339
  } ?: false
1467
1340
 
1468
- // Defer notification until after jump forward operation completes
1469
1341
  post { this@AudioBrowser.onRemoteJumpForward(event) }
1470
1342
 
1471
1343
  return handled
@@ -1478,7 +1350,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1478
1350
  true
1479
1351
  } ?: false
1480
1352
 
1481
- // Defer notification until after jump backward operation completes
1482
1353
  post { this@AudioBrowser.onRemoteJumpBackward(event) }
1483
1354
 
1484
1355
  return handled
@@ -1491,7 +1362,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1491
1362
  true
1492
1363
  } ?: false
1493
1364
 
1494
- // Defer notification until after seek operation completes
1495
1365
  post { this@AudioBrowser.onRemoteSeek(event) }
1496
1366
 
1497
1367
  return handled
@@ -1523,23 +1393,16 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1523
1393
  }
1524
1394
 
1525
1395
  companion object {
1526
- // Process-wide car-connection state, from the androidx.car.app
1527
- // CarConnection provider — the documented Android Auto / Automotive
1528
- // connection signal, served by the car system app. Observed ONCE per
1529
- // process: AudioBrowser instances are re-created on a JS reload, and a
1530
- // per-instance observeForever would leak each one. The latest instance's
1531
- // callback registers as the single notification target (mirrors the iOS
1532
- // static + shared-instance pattern).
1396
+ // Process-wide, from androidx.car.app CarConnection, observed once per process: instances are
1397
+ // re-created on each JS reload, and a per-instance observeForever would leak each one. The
1398
+ // latest instance's callback is the single target (mirrors iOS).
1533
1399
  @Volatile private var carConnected = false
1534
1400
  // Compare-and-set, not @Volatile: a disposing instance clears the slot only if it still owns
1535
1401
  // it, and a replacement may be claiming it at the same moment.
1536
1402
  private val carConnectionTarget = AtomicReference<((Boolean) -> Unit)?>(null)
1537
1403
  private var carConnectionObserverStarted = false
1538
1404
 
1539
- /**
1540
- * The instance the current JS runtime is using. Nitro hands out no registry, and the teardown
1541
- * callback has nothing to dispose without one.
1542
- */
1405
+ // The instance the current JS runtime uses: Nitro keeps no registry for teardown to find it in.
1543
1406
  private val current = AtomicReference<AudioBrowser?>(null)
1544
1407
 
1545
1408
  /** Called by [AudioBrowserLifecycleModule] when the React instance is torn down. */
@@ -1547,14 +1410,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1547
1410
  current.getAndSet(null)?.dispose()
1548
1411
  }
1549
1412
 
1550
- /** Shared by the [resolveGate] initializer and [dispose], which reverts to it. */
1551
1413
  private val defaultResolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = {
1552
1414
  Promise.resolved(Promise.resolved(GateDecision(gated = true, gate = null)))
1553
1415
  }
1554
1416
 
1555
1417
  private fun startCarConnectionObserver(context: Context, handler: Handler) {
1556
- // Posted to main: LiveData observation is main-thread only, and the
1557
- // single-start guard is then only ever touched from one thread.
1418
+ // LiveData observation is main-thread only, which also keeps the start guard on one thread.
1558
1419
  handler.post {
1559
1420
  if (carConnectionObserverStarted) return@post
1560
1421
  carConnectionObserverStarted = true
@@ -1570,7 +1431,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
1570
1431
  }
1571
1432
 
1572
1433
  // MARK: Deep JS-callback stripping (used by dispose)
1573
- // Functions live at every level of the config, not just the top; each type's strip nils its own.
1434
+ // A JS function field added at any level of the config must be nulled by its type's strip.
1574
1435
 
1575
1436
  private fun NativeBrowserConfiguration.strippingJSCallbacks() =
1576
1437
  copy(
@@ -1607,16 +1468,13 @@ private fun NativeRouteEntry.strippingJSCallbacks() =
1607
1468
  artwork = artwork?.strippingJSCallbacks(),
1608
1469
  )
1609
1470
 
1610
- /**
1611
- * Ceiling on the app's `formatNavigationError` hop. Same budget [Player.awaitBrowser] gives the JS
1612
- * side, the only other JS wait a browse serve already blocks on.
1613
- */
1471
+ // The budget [Player.awaitBrowser] gives JS, the other JS wait a browse serve blocks on.
1614
1472
  private val FORMATTER_TIMEOUT = 10.seconds
1615
1473
 
1616
1474
  /**
1617
- * The navigation error an exception raises. Shared by [AudioBrowser]'s failed navigations, the
1618
- * rejection [AudioBrowser.search] hands JS, and the Android Auto browse-error tile, so one failure
1619
- * is named one way wherever it surfaces.
1475
+ * The navigation error [e] raises, shared by failed navigations, the rejection
1476
+ * [AudioBrowser.search] hands JS and the Android Auto browse-error tile, so one failure is named
1477
+ * one way wherever it surfaces.
1620
1478
  */
1621
1479
  internal fun navigationErrorFor(e: Exception): NavigationError =
1622
1480
  when (e) {
@@ -1660,37 +1518,33 @@ internal fun navigationErrorFor(e: Exception): NavigationError =
1660
1518
  /** Carries a [NavigationError] across a rejected Promise, whose JS error keeps its message. */
1661
1519
  class NavigationErrorException(val error: NavigationError) : Exception(error.message)
1662
1520
 
1663
- /**
1664
- * The built-in display copy for a navigation error, and the fallback when the app's is unusable.
1665
- */
1521
+ /** The built-in display copy for [error], and the fallback when the app's formatter fails. */
1666
1522
  internal fun defaultFormattedError(error: NavigationError): FormattedNavigationError {
1667
1523
  val title =
1668
1524
  when (error.code) {
1669
1525
  NavigationErrorType.CONTENT_NOT_FOUND -> "Content Not Found"
1670
1526
  NavigationErrorType.NETWORK_ERROR -> "Network Error"
1671
1527
  NavigationErrorType.HTTP_ERROR -> {
1672
- // Use system-localized HTTP status text (e.g., "Not Found", "Service Unavailable")
1673
1528
  error.statusCode?.let { httpStatusText(it.toInt()) } ?: "Server Error"
1674
1529
  }
1675
1530
  NavigationErrorType.CALLBACK_ERROR -> "Error"
1676
1531
  NavigationErrorType.UNKNOWN_ERROR -> "Error"
1677
- // Not a failure — a container that resolved with no children. Neutral copy. See ADR 0001.
1532
+ // Not a failure: a container that resolved with no children (ADR 0001).
1678
1533
  NavigationErrorType.EMPTY_CONTENT -> "Nothing here"
1679
1534
  NavigationErrorType.TIMEOUT -> "Couldn't load"
1680
1535
  }
1681
- // Omit an empty message so it renders as title-only (e.g. the empty-content case).
1536
+ // An empty message is omitted so it renders title-only.
1682
1537
  return FormattedNavigationError(title, error.message.takeIf { it.isNotEmpty() })
1683
1538
  }
1684
1539
 
1685
1540
  /**
1686
- * The formatter hop's fallback rule: the app's answer when it produces one, [default] when it
1687
- * answers null, throws, or outruns [FORMATTER_TIMEOUT]. Kept off the JS edge so the rule is
1688
- * exercisable without a Nitro Promise.
1541
+ * The app's formatted error from [format], or [default] when it returns null, throws, or outruns
1542
+ * [FORMATTER_TIMEOUT].
1689
1543
  *
1690
- * The hop runs in [scope] and is awaited through its [kotlinx.coroutines.Deferred], because Nitro's
1691
- * `Promise.await` parks in a plain `suspendCoroutine`: cancelling it does not unpark it. Awaiting
1692
- * the Deferred is cancellable, so the timeout leaves the orphan to finish unobserved instead of
1693
- * holding the caller open until JS answers — which for a browse serve would be forever.
1544
+ * [format] runs in [scope] and is awaited through the Deferred because Nitro's `Promise.await`
1545
+ * parks in a plain `suspendCoroutine` that cancellation does not unpark; awaiting the Deferred is
1546
+ * cancellable, so the timeout releases the caller instead of holding it until JS answers, which for
1547
+ * a browse serve may be never.
1694
1548
  */
1695
1549
  internal suspend fun formattedOrDefault(
1696
1550
  scope: CoroutineScope,
@@ -1701,7 +1555,6 @@ internal suspend fun formattedOrDefault(
1701
1555
  return withTimeoutOrNull(FORMATTER_TIMEOUT) { hop.await() } ?: default
1702
1556
  }
1703
1557
 
1704
- /** Returns localized HTTP status text for the given status code */
1705
1558
  private fun httpStatusText(statusCode: Int): String {
1706
1559
  return when (statusCode) {
1707
1560
  400 -> "Bad Request"