react-native-audio-browser 0.2.0-next.28 → 0.2.0-next.29

package/ios/Player/DeferredSeek.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// A seek that arrives while an item loads. AVPlayer ignores `seek(to:)` without a loaded item,
+/// so the target is held until the item is ready, and the ready transition waits until it lands.
+/// Pure state: the caller issues the seek this hands out and reports when it lands.
+struct DeferredSeek {
+  enum State: Equatable {
+    case idle
+    case pending(TimeInterval)
+    case inFlight(TimeInterval)
+  }
+
+  /// What to do once an issued seek lands.
+  enum Landing: Equatable {
+    /// The target is reached: the load may become ready.
+    case done
+    /// A newer target arrived meanwhile: issue it.
+    case reseek(TimeInterval)
+    /// No deferred seek was in flight.
+    case none
+  }
+
+  private(set) var state: State = .idle
+
+  /// Identifies the item a seek was issued against. `reset()` bumps it, so the completion of a
+  /// seek against the previous item can tell it is stale.
+  private(set) var generation = 0
+
+  /// The target, pending or in flight; `seekBy` offsets from it.
+  var target: TimeInterval? {
+    switch state {
+    case let .pending(time), let .inFlight(time): time
+    case .idle: nil
+    }
+  }
+
+  var defersReady: Bool {
+    state != .idle
+  }
+
+  /// Holds `position` as the target, replacing a pending one or one in flight.
+  mutating func capture(_ position: TimeInterval) {
+    state = .pending(position)
+  }
+
+  /// Hands out the pending target to issue, marking it in flight; nil when none is pending.
+  mutating func begin() -> TimeInterval? {
+    guard case let .pending(time) = state else { return nil }
+    state = .inFlight(time)
+    return time
+  }
+
+  mutating func land() -> Landing {
+    switch state {
+    case .inFlight:
+      state = .idle
+      return .done
+    case .pending:
+      guard let time = begin() else { return .none }
+      return .reseek(time)
+    case .idle:
+      return .none
+    }
+  }
+
+  mutating func reset() {
+    state = .idle
+    generation += 1
+  }
+}

package/ios/Player/ErrorStatus.swift

@@ -0,0 +1,27 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The player's error: none, one the retry loop is still working on (shown over a non-terminal
+/// state, an Advisory error), or terminal (the `.error` state).
+enum ErrorStatus: Equatable {
+  case none
+  case retrying(TrackPlayerError.PlaybackError)
+  case terminal(TrackPlayerError.PlaybackError)
+
+  var error: TrackPlayerError.PlaybackError? {
+    switch self {
+    case .none: nil
+    case let .retrying(error), let .terminal(error): error
+    }
+  }
+
+  var isRetrying: Bool {
+    if case .retrying = self { true } else { false }
+  }
+
+  /// The JS-facing error, carrying the retrying flag.
+  var nitroError: PlaybackError? {
+    error?.toNitroError(retrying: isRetrying)
+  }
+}

package/ios/Player/MediaLoader.swift

@@ -17,13 +17,26 @@ final class MediaLoader {
   /// consumer-supplied `media.resolve(track)` as the final media layer.
   var mediaUrlResolver: ((String, Track?) async -> MediaResolvedUrl)?
 
-  /// Internal access so TrackPlayer can read it for observer guards.
+  /// Internal access so AVPlayerEngine can read it.
   private(set) var asset: AVURLAsset?
 
   /// Milliseconds; applied to AVPlayerItem's preferredForwardBufferDuration.
   var bufferDuration: Double = 0
 
-  weak var delegate: MediaLoaderDelegate?
+  enum Event {
+    case prepared(AVPlayerItem)
+    /// Loading failed; the retry loop decides whether another attempt could help.
+    case failed(Error)
+    /// The asset loaded but cannot play.
+    case unplayable
+    /// The source is not a URL, so no asset exists.
+    case invalidSource(String)
+    case commonMetadata([AVMetadataItem])
+    case chapterMetadata([AVTimedMetadataGroup])
+    case timedMetadata([AVTimedMetadataGroup])
+  }
+
+  var onEvent: (@MainActor (Event) -> Void)?
 
   /// The in-flight resolve. Readable so tests can await the resolve-then-load
   /// chain instead of sleeping past it; only this type starts and cancels it.
@@ -89,7 +102,7 @@ final class MediaLoader {
     guard let url else {
       // Callers (reload-from-terminal) have already transitioned to .loading;
       // a silent return would strand that state with no load in flight.
-      delegate?.mediaLoaderDidFailWithError(.invalidSourceUrl("nil"))
+      onEvent?(.invalidSource("nil"))
       return
     }
     let pendingAsset = AVURLAsset(url: url, options: urlOptions)
@@ -108,7 +121,7 @@ final class MediaLoader {
       guard isCurrent(pendingAsset) else { return }
 
       if !commonMetadata.isEmpty {
-        delegate?.mediaLoaderDidReceiveCommonMetadata(commonMetadata)
+        onEvent?(.commonMetadata(commonMetadata))
       }
 
       if !chapterLocales.isEmpty {
@@ -119,7 +132,7 @@ final class MediaLoader {
             containingItemsWithCommonKeys: [],
           ) {
             guard isCurrent(pendingAsset) else { return }
-            delegate?.mediaLoaderDidReceiveChapterMetadata(chapters)
+            onEvent?(.chapterMetadata(chapters))
           }
         }
       } else {
@@ -133,7 +146,7 @@ final class MediaLoader {
               end: duration,
             )
             let group = AVTimedMetadataGroup(items: metadata, timeRange: timeRange)
-            delegate?.mediaLoaderDidReceiveTimedMetadata([group])
+            onEvent?(.timedMetadata([group]))
           }
         }
       }
@@ -151,20 +164,20 @@ final class MediaLoader {
           guard pendingAsset == self.asset else { return }
 
           if !isPlayable {
-            self.delegate?.mediaLoaderDidFailWithUnplayableTrack()
+            self.onEvent?(.unplayable)
             return
           }
 
           let avItem = AVPlayerItem(asset: pendingAsset)
           avItem.preferredForwardBufferDuration = self.bufferDuration / 1000.0
-          self.delegate?.mediaLoaderDidPrepareItem(avItem)
+          self.onEvent?(.prepared(avItem))
         }
       } catch {
         guard !Task.isCancelled else { return }
 
         await MainActor.run {
           guard pendingAsset == self.asset else { return }
-          self.delegate?.mediaLoaderDidFailWithRetryableError(error)
+          self.onEvent?(.failed(error))
         }
       }
     }
@@ -207,7 +220,7 @@ final class MediaLoader {
 
   /// Builds AVURLAsset options, merging any explicit headers with a resolved
   /// User-Agent. An explicit `User-Agent` in `headers` wins (mirrors the artwork
-  /// path in BrowserManager+URLResolution). A nil/empty userAgent contributes
+  /// path in RequestPipeline). A nil/empty userAgent contributes
   /// nothing, so "no UA configured" still falls through to AVPlayer's default.
   nonisolated static func buildAssetOptions(
     headers: [String: String]?,
@@ -225,7 +238,7 @@ final class MediaLoader {
   private func loadWithResolvedUrl(_ resolved: MediaResolvedUrl) {
     guard let mediaUrl = URL(string: resolved.url) else {
       logger.error("Invalid media URL: \(resolved.url)")
-      delegate?.mediaLoaderDidFailWithError(.invalidSourceUrl(resolved.url))
+      onEvent?(.invalidSource(resolved.url))
       return
     }
 

package/ios/Player/NowPlayingUpdater.swift

@@ -3,46 +3,118 @@ import MediaPlayer
 import NitroModules
 import os.log
 
+/// What the now-playing surface renders from: the player's track and state.
+@MainActor
+protocol NowPlayingSource: AnyObject {
+  var currentTrack: Track? { get }
+  var currentTime: Double { get }
+  var playWhenReady: Bool { get }
+  var isStalled: Bool { get }
+  var nitroPlaybackError: PlaybackError? { get }
+}
+
 /// Owns the now-playing surface: publishes a track's static fields + artwork, and renders the
-/// title/artist line — the formatter's result, or the track/override default. The single writer of
-/// the title/artist fields, with a publish-dedupe so the frequent re-renders stay cheap.
-///
-/// Does not exclusively own NowPlayingInfoController -- other callers (e.g. HybridAudioBrowser for
-/// overrides) can still access it directly.
+/// title/artist line — a flash, else the formatter's result, else the override or the track's own
+/// fields. Holds that state (override, flash, latest timed metadata, formatter) and reports each
+/// change of the rendered lines through `onChanged`.
 @MainActor
 final class NowPlayingUpdater {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingUpdater")
   private let nowPlayingInfoController: NowPlayingInfoController
 
+  weak var source: NowPlayingSource?
   var artworkUrlResolver: ((Track, ImageContext?) async -> ImageSource?)?
-  /// Invoked when the published title/artist actually change, so the owner can emit the JS
-  /// `onNowPlayingChanged` event (which it shapes with elapsed time / artwork / etc.).
-  var onChanged: (@MainActor (_ track: Track, _ title: String, _ artist: String?, _ album: String?) -> Void)?
+  /// Called with the JS-facing metadata whenever the rendered lines or the track change.
+  var onChanged: ((NowPlayingMetadata) -> Void)?
+
+  /// When false the surface shows the track's own fields: the override and formatter are ignored.
+  var enabled = true
+  var formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?
+
+  /// Whether the device is online, which tells a stall apart: offline or buffering.
+  var isOnline = true {
+    didSet { if isOnline != oldValue { render() } }
+  }
+
+  private var override: NowPlayingUpdate?
+  private var timedMetadata: TimedMetadata?
+  /// A transient line (e.g. feedback for a refused remote command) that outranks the formatter
+  /// and the override, reverted by a native timer: JS timers pause in the background.
+  private var flash: NowPlayingUpdate?
+  private var flashRevert: DispatchWorkItem?
 
   private var artworkLoadTask: Task<Void, Never>?
-  private var artworkGeneration: UInt = 0
-
-  /// Last published text lines, to dedupe redundant writes (render runs on every transition).
-  private struct Published: Equatable {
-    let trackId: String?
-    let title: String?
-    let artist: String?
-    let album: String?
-  }
-
-  /// Dedupe baseline for `applyFields`. Only meaningful while it describes the
-  /// controller's current info dict, so the two are cleared together in
-  /// `clearNowPlaying()` — never separately.
-  private var lastPublished: Published?
-
-  /// Empties the now-playing surface and the dedupe baseline that describes it.
-  /// One call, because clearing the dict without the baseline makes the next
-  /// publish of the SAME track dedupe against a dict that no longer holds it —
-  /// artwork lands (never deduped) but the text doesn't, and `onChanged`
-  /// never fires.
+
+  /// The track `onChanged` last reported, so a new track with the same text still reports.
+  private var publishedTrackId: String?
+
+  func setOverride(_ update: NowPlayingUpdate?) {
+    override = update
+    render()
+  }
+
+  func flash(_ update: NowPlayingUpdate, durationMs: Double) {
+    flashRevert?.cancel()
+    flash = update
+    let revert = DispatchWorkItem { [weak self] in
+      self?.flash = nil
+      self?.flashRevert = nil
+      self?.render()
+    }
+    flashRevert = revert
+    DispatchQueue.main.asyncAfter(deadline: .now() + durationMs / 1000, execute: revert)
+    render()
+  }
+
+  func clearFlash() {
+    guard flash != nil else { return }
+    cancelFlash()
+    render()
+  }
+
+  func receivedTimedMetadata(_ metadata: TimedMetadata) {
+    timedMetadata = metadata
+    render()
+  }
+
+  /// A new track drops the override, flash and timed metadata of the last one.
+  func trackChanged() {
+    override = nil
+    cancelFlash()
+    timedMetadata = nil
+    render()
+  }
+
+  /// The metadata JS sees for the current track, before any formatter result.
+  var nowPlaying: NowPlayingMetadata? {
+    guard let track = source?.currentTrack else { return nil }
+    let lines = defaultLines(for: track)
+    return metadata(track: track, title: lines.title, artist: lines.artist, album: lines.album)
+  }
+
+  /// Re-renders the text lines for the current track and state. Called on every playback
+  /// transition; unchanged lines are not re-published.
+  func render() {
+    guard let source, let track = source.currentTrack else { return }
+    render(
+      track: track,
+      timedMetadata: timedMetadata,
+      playWhenReady: source.playWhenReady,
+      stalled: source.isStalled ? (isOnline ? .buffering : .offline) : nil,
+      error: source.nitroPlaybackError,
+      flash: flash,
+      override: enabled ? override : nil,
+      formatter: enabled ? formatter : nil,
+    )
+  }
+
+  /// Empties the now-playing surface and drops any artwork fetch or formatter result in flight.
   func clearNowPlaying() {
+    renderGeneration &+= 1
+    artworkLoadTask?.cancel()
+    artworkLoadTask = nil
     nowPlayingInfoController.clear()
-    lastPublished = nil
+    publishedTrackId = nil
     formattedTrackId = nil
   }
 
@@ -79,9 +151,7 @@ final class NowPlayingUpdater {
   /// lines are owned by `render` (routed through `applyFields` here so it dedupes against later
   /// renders).
   func loadMetaValues(for track: Track) {
-    nowPlayingInfoController.set(keyValues: [
-      NowPlayingInfoProperty.isLiveStream(track.live),
-    ])
+    nowPlayingInfoController.set([MPNowPlayingInfoPropertyIsLiveStream: track.live])
     applyFields(track: track, title: track.title, artist: track.artist, album: track.album)
     loadArtwork(for: track)
   }
@@ -92,13 +162,13 @@ final class NowPlayingUpdater {
   /// command) outranks both: while one is active the formatter pass is skipped entirely, so its
   /// async result can't land on top. Safe to call on every playback transition; redundant writes
   /// are deduped.
-  func render(
+  private func render(
     track: Track,
     timedMetadata: TimedMetadata?,
     playWhenReady: Bool,
     stalled: StallReason?,
     error: PlaybackError?,
-    flash: NowPlayingUpdate? = nil,
+    flash: NowPlayingUpdate?,
     override: NowPlayingUpdate?,
     formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?,
   ) {
@@ -174,27 +244,58 @@ final class NowPlayingUpdater {
 
   // MARK: - Private
 
-  /// Stamps the title/artist/album (each falling back to the track's own) onto
-  /// NowPlayingInfoCenter, deduped against the last publish, and notifies `onChanged`.
+  /// Stamps the title/artist/album (each falling back to the track's own) onto the now-playing
+  /// surface, and notifies `onChanged` when the text or the track changed.
   private func applyFields(track: Track, title: String?, artist: String?, album: String?) {
     let resolvedTitle = title ?? track.title
     let resolvedArtist = artist ?? track.artist
     let resolvedAlbum = album ?? track.album
-    let published = Published(
-      trackId: track.identity ?? track.path,
-      title: resolvedTitle,
-      artist: resolvedArtist,
-      album: resolvedAlbum,
+    let textChanged = nowPlayingInfoController.set([
+      MPMediaItemPropertyTitle: resolvedTitle,
+      MPMediaItemPropertyArtist: resolvedArtist,
+      MPMediaItemPropertyAlbumTitle: resolvedAlbum,
+    ])
+    let trackId = track.identity ?? track.path
+    guard textChanged || trackId != publishedTrackId else { return }
+    publishedTrackId = trackId
+    onChanged?(metadata(track: track, title: resolvedTitle, artist: resolvedArtist, album: resolvedAlbum))
+  }
+
+  private func cancelFlash() {
+    flashRevert?.cancel()
+    flashRevert = nil
+    flash = nil
+  }
+
+  /// Flash over override over the track's own fields.
+  private func defaultLines(for track: Track) -> (title: String, artist: String?, album: String?) {
+    (
+      flash?.title ?? override?.title ?? track.title,
+      flash?.artist ?? override?.artist ?? track.artist,
+      flash?.album ?? override?.album ?? track.album,
     )
-    guard published != lastPublished else { return }
-    lastPublished = published
+  }
 
-    nowPlayingInfoController.set(keyValues: [
-      MediaItemProperty.title(resolvedTitle),
-      MediaItemProperty.artist(resolvedArtist),
-      MediaItemProperty.albumTitle(resolvedAlbum),
-    ])
-    onChanged?(track, resolvedTitle, resolvedArtist, resolvedAlbum)
+  private func metadata(track: Track, title: String, artist: String?, album: String?) -> NowPlayingMetadata {
+    NowPlayingMetadata(
+      elapsedTime: source?.currentTime,
+      title: title,
+      album: album,
+      artist: artist,
+      duration: track.duration,
+      artwork: Self.jsArtwork(for: track),
+      description: track.description,
+      mediaId: track.src ?? track.path,
+      genre: track.genre,
+    )
+  }
+
+  /// The artwork URI JS can load: the resolved `artworkSource` (a rendered SF Symbol's `file://`
+  /// included), else the raw artwork unless it is an SF Symbol.
+  private static func jsArtwork(for track: Track) -> String? {
+    if let uri = track.artworkSource?.uri { return uri }
+    guard let artwork = track.artwork?.url else { return nil }
+    return SFSymbolRenderer.isSFSymbol(artwork) ? nil : artwork
   }
 
   private func loadArtwork(for track: Track) {
@@ -207,8 +308,6 @@ final class NowPlayingUpdater {
     let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
 
     artworkLoadTask?.cancel()
-    artworkGeneration &+= 1
-    let expectedGeneration = artworkGeneration
     artworkLoadTask = Task {
       let image: UIImage?
 
@@ -216,19 +315,19 @@ final class NowPlayingUpdater {
       if let resolver = artworkUrlResolver,
          let imageSource = await resolver(track, nowPlayingSize)
       {
-        guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+        guard !Task.isCancelled else { return }
         logger.debug("loadArtwork: using resolved URL: \(imageSource.uri)")
-        image = await ArtworkImageFetcher.fetchImage(from: imageSource)
+        image = await ArtworkImageFetcher.fetchImage(from: imageSource, waitsForConnectivity: true)
       } else {
-        guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+        guard !Task.isCancelled else { return }
         if let source = track.artworkImageSource {
-          image = await ArtworkImageFetcher.fetchImage(from: source)
+          image = await ArtworkImageFetcher.fetchImage(from: source, waitsForConnectivity: true)
         } else {
           image = nil
         }
       }
 
-      guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+      guard !Task.isCancelled else { return }
 
       if let image {
         logger.debug("loadArtwork: loaded image \(image.size.width)x\(image.size.height)")
@@ -237,10 +336,10 @@ final class NowPlayingUpdater {
         let artwork = MPMediaItemArtwork(boundsSize: image.size) { @Sendable requestedSize in
           return image
         }
-        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(artwork))
+        nowPlayingInfoController.set([MPMediaItemPropertyArtwork: artwork])
       } else {
         logger.debug("loadArtwork: no image loaded")
-        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(nil))
+        nowPlayingInfoController.set([MPMediaItemPropertyArtwork: nil])
       }
     }
   }

package/ios/Player/PlaybackFailure.swift

@@ -0,0 +1,125 @@
+import AVFoundation
+import Foundation
+
+/// What a playback failure is reported as, and whether another attempt could fix it: one table,
+/// so the error JS receives and the retry decision are read off the same evidence.
+enum PlaybackFailure {
+  struct Classification: Equatable {
+    /// The narrowest error the evidence supports, falling back to the context's error.
+    let error: TrackPlayerError.PlaybackError
+    let retryable: Bool
+  }
+
+  /// Classifies a failure. AVFoundation reports HTTP failures as opaque CoreMedia errors, so
+  /// `httpStatusCode` comes from the item's error log, passed in by the caller.
+  ///
+  /// Both read the error and the errors it wraps, but rank the evidence differently, on purpose:
+  /// - The error: a transport failure first (no response arrived, so a status left in the log
+  ///   describes an earlier attempt), then a non-2xx status, then media that cannot be decoded.
+  /// - Retrying: a status first (a retry cannot conjure content the server refused), then the
+  ///   error and the errors it wraps. An unrecognized failure is transient, bounded by the retry
+  ///   budgets, as on Android: AVFoundation reports most stream failures opaquely.
+  static func classify(
+    _ error: Error?,
+    httpStatusCode: Int?,
+    fallback: TrackPlayerError.PlaybackError,
+  ) -> Classification {
+    Classification(
+      error: reportedError(error, httpStatusCode: httpStatusCode, fallback: fallback),
+      retryable: isRetryable(error, httpStatusCode: httpStatusCode),
+    )
+  }
+
+  /// Picks the HTTP status out of an `AVPlayerItem` error log's status codes. The codes share
+  /// their space with negative OSStatus values, so only in-range values count, and the newest
+  /// wins: a live stream reconnects, and older entries describe earlier attempts.
+  static func httpStatusCode(fromErrorStatusCodes codes: [Int]) -> Int? {
+    codes.last { (100 ... 599).contains($0) }
+  }
+
+  // MARK: - The error
+
+  private static func reportedError(
+    _ error: Error?,
+    httpStatusCode: Int?,
+    fallback: TrackPlayerError.PlaybackError,
+  ) -> TrackPlayerError.PlaybackError {
+    let chain = error.map(errorChain) ?? []
+    // `as?` bridges a plain NSError in NSURLErrorDomain too, AVFoundation's usual form.
+    for case let urlError as URLError in chain {
+      switch urlError.code {
+      case .notConnectedToInternet:
+        return .notConnectedToInternet
+      case .timedOut, .cannotFindHost, .cannotConnectToHost, .networkConnectionLost, .dnsLookupFailed,
+           .secureConnectionFailed:
+        return .hostUnreachable
+      default:
+        continue
+      }
+    }
+    if let httpStatusCode, !(200 ... 299).contains(httpStatusCode) {
+      return .httpStatus(httpStatusCode)
+    }
+    let unplayable = chain.contains {
+      let nsError = $0 as NSError
+      return nsError.domain == AVFoundationErrorDomain && unplayableAVErrorCodes.contains(nsError.code)
+    }
+    return unplayable ? .trackWasUnplayable : fallback
+  }
+
+  /// The stream arrived but cannot be decoded: unknown container, unsupported codec, or no
+  /// decoder.
+  private static let unplayableAVErrorCodes: Set<Int> = [
+    AVError.fileFormatNotRecognized.rawValue,
+    AVError.failedToParse.rawValue,
+    AVError.decoderNotFound.rawValue,
+    AVError.decoderTemporarilyUnavailable.rawValue,
+    AVError.formatUnsupported.rawValue,
+    AVError.contentIsUnavailable.rawValue,
+  ]
+
+  // MARK: - Retrying
+
+  /// Beyond the 500–599 range. Android shares 408/429 but lists only 500/502/503/504 of 5xx.
+  private static let retryableHTTPStatusCodes: Set<Int> = [408, 429]
+
+  /// AVFoundation failures a retry cannot fix: the media is unusable, not the transport
+  /// unreliable. Every unplayable code but the temporary decoder shortage is here, so a failure
+  /// reported as unplayable is never also retried. `AVError.unknown` is absent on purpose: it
+  /// is the wrapper around opaque CoreMedia transport failures.
+  private static let fatalAVErrorCodes: Set<Int> = unplayableAVErrorCodes
+    .subtracting([AVError.decoderTemporarilyUnavailable.rawValue])
+    .union([
+      AVError.decodeFailed.rawValue,
+      AVError.contentIsProtected.rawValue,
+      AVError.contentIsNotAuthorized.rawValue,
+    ])
+
+  private static func isRetryable(_ error: Error?, httpStatusCode: Int?) -> Bool {
+    if let status = httpStatusCode {
+      return retryableHTTPStatusCodes.contains(status) || (500 ... 599).contains(status)
+    }
+    guard let error else { return false }
+    // AVFoundation routinely wraps the real cause (a URLError, a CoreMedia code) in an AVError.
+    for candidate in errorChain(error) {
+      if let urlError = candidate as? URLError { return urlError.isConnectivity }
+      let nsError = candidate as NSError
+      if nsError.domain == AVFoundationErrorDomain, fatalAVErrorCodes.contains(nsError.code) {
+        return false
+      }
+    }
+    return true
+  }
+
+  /// The error and its `NSUnderlyingError` ancestors, outermost first, bounded so a malformed
+  /// cycle cannot spin.
+  private static func errorChain(_ error: Error) -> [Error] {
+    var chain: [Error] = []
+    var current: Error? = error
+    while let error = current, chain.count < 8 {
+      chain.append(error)
+      current = (error as NSError).userInfo[NSUnderlyingErrorKey] as? Error
+    }
+    return chain
+  }
+}