0.19.0

CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to PlayolaPlayer are documented here. This project follows
 [Semantic Versioning](https://semver.org/). Versions correspond to git tags,
 which Swift Package Manager consumers pin to.
 
+## 0.19.0
+
+### Added
+
+- **Bounded retry/backoff on the initial schedule fetch.** `play(stationId:)`
+  now retries a failed initial `GET /v1/stations/{id}/schedule` up to 3 times
+  with exponential backoff (0.5s / 1s / 2s) before giving up, matching the
+  recovery behavior the player already used for spin loading and the ongoing
+  schedule poll. Only transient failures are retried — server `5xx` responses
+  and an explicit allow-list of connectivity `URLError`s (timeouts, host/DNS,
+  connection-lost, etc.). Permanent failures (`404`, decode errors, empty
+  schedules, and non-connectivity `URLError`s such as `.badURL`) still fail
+  fast. This means a transient backend outage no longer instantly fails a
+  station start with no automatic recovery.
+
+### Changed
+
+- **`PlayolaStationPlayer.State` gained a terminal `.error(StationPlayerError)`
+  case.** A failed `play(...)` now emits `.loading(0)` when the attempt begins
+  and `.error(_)` when it fails terminally (instead of throwing without ever
+  changing `state`, which could leave consumers stuck on a loading spinner with
+  no signal). `play(...)` still `throws` as before — the new state is emitted
+  *in addition to* the thrown error. Cancellation does not produce an `.error`
+  state.
+
+  **Source-breaking for consumers** that `switch` exhaustively over `State`:
+  add a `case .error` (or `default`) arm. A typical handler treats `.error` as
+  a recoverable, retry-able state (show the message, let the user tap play
+  again). `StationPlayerError` is now `Sendable`.
+
+- **State transitions are now supersession-safe (last `play()` wins).** Each
+  `play(...)`/`stop()` takes a new internal generation; work from a prior
+  attempt (its scheduling loop, or a spin whose audio starts later) can no
+  longer publish state into a newer attempt. This closes a race where a
+  lingering session could overwrite a freshly-emitted `.error` (or `.idle`)
+  with `.playing`. Behavioral note: starting a new `play()` supersedes the
+  previous session immediately, so a *failed* station switch lands on `.error`
+  rather than rolling back to the previously-playing station.
+
 ## 0.18.0
 
 ### Added

PlayolaPlayerExample/PlayolaPlayerExample/ContentView.swift

@@ -129,6 +129,18 @@ struct ContentView: View {
                   .font(.caption)
                   .foregroundColor(.white.opacity(0.6))
               }
+            } else if case .error(let error) = player.state {
+              VStack(spacing: 8) {
+                Image(systemName: "exclamationmark.triangle.fill")
+                  .foregroundColor(.yellow)
+                Text(error.errorDescription ?? "Couldn't start the station")
+                  .font(.subheadline)
+                  .multilineTextAlignment(.center)
+                  .foregroundColor(.white.opacity(0.8))
+                Text("Tap play to try again")
+                  .font(.caption)
+                  .foregroundColor(.white.opacity(0.6))
+              }
             } else {
               Text("Ready to Play")
                 .font(.title3)
@@ -237,12 +249,13 @@ struct ContentView: View {
       case .playing:
         // Stop playing
         await player.stop()
-      case .idle:
-        // Start playing
+      case .idle, .error:
+        // Start (or retry after a failed start)
         do {
           try await player.play(stationId: selectedStationId)
         } catch {
-          // Handle errors gracefully (including cancellation during loading)
+          // Handle errors gracefully (including cancellation during loading).
+          // The terminal .error state is surfaced via player.state above.
           print("Failed to start playback: \(error)")
         }
       }
@@ -493,6 +506,8 @@ func buttonColor(for state: PlayolaStationPlayer.State) -> Color {
     return Color.red
   case .idle:
     return Color.green
+  case .error:
+    return Color.green
   }
 }
 
@@ -504,6 +519,8 @@ func buttonIcon(for state: PlayolaStationPlayer.State) -> String {
     return "stop.fill"
   case .idle:
     return "play.fill"
+  case .error:
+    return "arrow.clockwise"
   }
 }