feat(player): add gapless queue handoff and SPA navigation

.agents/skills/playback-webview-debugging/SKILL.md

@@ -32,6 +32,10 @@ Use this skill when playback, auth recovery, queue sync, or hidden WebView state
 - `docs/playback.md`
 - `Sources/Kaset/Views/MiniPlayerWebView.swift`
 - `Sources/Kaset/Views/SingletonPlayerWebView+ObserverScript.swift`
+- `Sources/Kaset/Views/SingletonPlayerWebView+NavigationState.swift`
+- `Sources/Kaset/Views/SingletonPlayerWebView+QueueInjection.swift`
 - `Sources/Kaset/Services/Player/PlayerService.swift`
+- `Sources/Kaset/Services/Player/PlayerService+WebPlaybackIdentity.swift`
 - `Sources/Kaset/Services/Player/PlayerService+WebQueueSync.swift`
+- `Sources/Kaset/Services/Player/PlayerService+QueueNavigationRecovery.swift`
 - `Sources/Kaset/Services/WebKit/WebKitManager.swift`

.github/workflows/tests.yml

@@ -87,7 +87,7 @@ jobs:
         # (Xcode 26 + Sequoia) during XCTest discovery. The unit suite is
         # entirely Swift Testing; the only XCTest target is the manual
         # ParserPerformanceTests, which is invoked separately via xcodebuild.
-        run: swift test -q --skip KasetUITests --disable-xctest
+        run: swift test -q --skip KasetUITests --disable-xctest --no-parallel
 
   macos_ui_tests:
     name: macOS UI Tests (${{ matrix.os }})

Sources/APIExplorer/main.swift

@@ -858,6 +858,156 @@ func analyzeResponse(_ data: [String: Any], verbose: Bool = false) -> String {
     return output
 }
 
+// MARK: - QueueProbeSong
+
+private struct QueueProbeSong {
+    let videoId: String
+    let title: String
+    let artists: String
+}
+
+private func playlistPanelRenderer(in data: [String: Any]) -> [String: Any]? {
+    guard let contents = data["contents"] as? [String: Any],
+          let watchNextRenderer = contents["singleColumnMusicWatchNextResultsRenderer"] as? [String: Any],
+          let tabbedRenderer = watchNextRenderer["tabbedRenderer"] as? [String: Any],
+          let watchNextTabbedResults = tabbedRenderer["watchNextTabbedResultsRenderer"] as? [String: Any],
+          let tabs = watchNextTabbedResults["tabs"] as? [[String: Any]],
+          let firstTab = tabs.first,
+          let tabRenderer = firstTab["tabRenderer"] as? [String: Any],
+          let tabContent = tabRenderer["content"] as? [String: Any],
+          let musicQueueRenderer = tabContent["musicQueueRenderer"] as? [String: Any],
+          let queueContent = musicQueueRenderer["content"] as? [String: Any]
+    else {
+        return nil
+    }
+
+    return queueContent["playlistPanelRenderer"] as? [String: Any]
+}
+
+private func playlistPanelVideoRenderer(from item: [String: Any]) -> [String: Any]? {
+    if let direct = item["playlistPanelVideoRenderer"] as? [String: Any] {
+        return direct
+    }
+
+    if let wrapper = item["playlistPanelVideoWrapperRenderer"] as? [String: Any],
+       let primary = wrapper["primaryRenderer"] as? [String: Any],
+       let wrapped = primary["playlistPanelVideoRenderer"] as? [String: Any]
+    {
+        return wrapped
+    }
+
+    return nil
+}
+
+private func parseQueueProbeSongs(from data: [String: Any]) -> [QueueProbeSong] {
+    guard let renderer = playlistPanelRenderer(in: data),
+          let contents = renderer["contents"] as? [[String: Any]]
+    else { return [] }
+
+    return contents.compactMap { item in
+        guard let videoRenderer = playlistPanelVideoRenderer(from: item),
+              let videoId = videoRenderer["videoId"] as? String
+        else { return nil }
+
+        let title = joinedRunsText(videoRenderer["title"] as? [String: Any]) ?? "Unknown"
+        let artists = joinedRunsText(videoRenderer["longBylineText"] as? [String: Any]) ?? ""
+        return QueueProbeSong(videoId: videoId, title: title, artists: artists)
+    }
+}
+
+private func queueProbeContinuationToken(in data: [String: Any]) -> String? {
+    guard let renderer = playlistPanelRenderer(in: data),
+          let continuations = renderer["continuations"] as? [[String: Any]],
+          let firstContinuation = continuations.first,
+          let nextRadioData = firstContinuation["nextRadioContinuationData"] as? [String: Any]
+    else { return nil }
+
+    return nextRadioData["continuation"] as? String
+}
+
+private func queueProbeAutoplayVideoId(in data: [String: Any]) -> String? {
+    guard let autoplay = data["playerOverlays"] as? [String: Any],
+          let playerOverlayRenderer = autoplay["playerOverlayRenderer"] as? [String: Any],
+          let autoplayRenderer = playerOverlayRenderer["autoplay"] as? [String: Any],
+          let playerOverlayAutoplayRenderer = autoplayRenderer["playerOverlayAutoplayRenderer"] as? [String: Any],
+          let item = playerOverlayAutoplayRenderer["item"] as? [String: Any],
+          let compactVideoRenderer = item["compactVideoRenderer"] as? [String: Any]
+    else { return nil }
+
+    return compactVideoRenderer["videoId"] as? String
+}
+
+func probeQueue(videoId: String, playlistId: String? = nil, verbose: Bool = false, outputFile: String? = nil) async {
+    let resolvedPlaylistId = playlistId ?? "RDAMVM\(videoId)"
+    let body: [String: Any] = [
+        "videoId": videoId,
+        "playlistId": resolvedPlaylistId,
+        "enablePersistentPlaylistPanel": true,
+        "isAudioOnly": true,
+        "tunerSettingValue": "AUTOMIX_SETTING_NORMAL",
+    ]
+
+    print("🎧 Probing queue for videoId: \(videoId)")
+    print("   playlistId: \(resolvedPlaylistId)")
+    print("   endpoint: next")
+    if loadCookiesFromAppBackup() != nil, !forceUnauthenticatedRequests {
+        print("   auth: cookies available")
+    } else {
+        print("   auth: guest/no cookies")
+    }
+    print()
+
+    do {
+        let (data, statusCode) = try await makeRequest(endpoint: "next", body: body, authenticated: !forceUnauthenticatedRequests && loadCookiesFromAppBackup() != nil)
+        print("✅ HTTP \(statusCode)")
+        if statusCode == 401 || statusCode == 403 {
+            print("❌ Authentication required")
+            return
+        }
+
+        let songs = parseQueueProbeSongs(from: data)
+        let ids = songs.map(\.videoId)
+        let seedPositions = ids.enumerated().compactMap { index, id in id == videoId ? index : nil }
+        let firstPlayable = songs.first
+        let nextPlayable = songs.dropFirst().first
+        print("Queue summary:")
+        print("  • Parsed songs: \(songs.count)")
+        print("  • Seed positions: \(seedPositions.isEmpty ? "none" : seedPositions.map(String.init).joined(separator: ", "))")
+        print("  • First parsed id: \(firstPlayable?.videoId ?? "none")")
+        print("  • Second parsed id: \(nextPlayable?.videoId ?? "none")")
+        print("  • Autoplay overlay id: \(queueProbeAutoplayVideoId(in: data) ?? "none")")
+        print("  • Has continuation: \(queueProbeContinuationToken(in: data) == nil ? "no" : "yes")")
+
+        if !songs.isEmpty {
+            print("\nFirst songs:")
+            for (index, song) in songs.prefix(10).enumerated() {
+                let marker = song.videoId == videoId ? " ← seed" : ""
+                let artistSuffix = song.artists.isEmpty ? "" : " — \(song.artists)"
+                print("  [\(index)] \(song.videoId) :: \(song.title)\(artistSuffix)\(marker)")
+            }
+        }
+
+        if verbose {
+            print("\n📄 Raw response (pretty-printed):")
+            if let prettyData = try? JSONSerialization.data(withJSONObject: data, options: .prettyPrinted),
+               let prettyString = String(data: prettyData, encoding: .utf8)
+            {
+                print(prettyString)
+            }
+        }
+
+        if let outputFile {
+            if let prettyData = try? JSONSerialization.data(withJSONObject: data, options: .prettyPrinted) {
+                let url = URL(fileURLWithPath: outputFile)
+                try prettyData.write(to: url)
+                print("\n💾 Saved to: \(outputFile)")
+            }
+        }
+    } catch {
+        print("❌ Error: \(error.localizedDescription)")
+    }
+}
+
 // MARK: - Commands
 
 /// Known endpoints that require authentication
@@ -2102,6 +2252,8 @@ func showHelp() {
           browse <browseId> [params]     Explore a browse endpoint
           action <endpoint> <body>       Explore an action endpoint (body as JSON)
           continuation <token> [ep]      Explore a continuation (ep: 'browse' or 'next')
+          queue-probe <videoId> [playlistId]
+                                         Summarize the Music next/radio queue shape
           list                           List all known endpoints
           auth                           Check authentication status
           accounts                       Discover available accounts (via authuser)
@@ -2154,6 +2306,7 @@ func showHelp() {
           swift run api-explorer action search '{"query":"never gonna give you up"}'
           swift run api-explorer action player '{"videoId":"dQw4w9WgXcQ"}'
           swift run api-explorer action next '{"playlistId":"RDEM...","videoId":"abc123"}'
+          swift run api-explorer queue-probe dQw4w9WgXcQ
 
           # Continuation (for pagination / infinite mix)
           swift run api-explorer continuation <token>           # browse endpoint (default)
@@ -2278,6 +2431,16 @@ func runMain() async {
             token, endpoint: endpoint, verbose: verbose, outputFile: outputFile
         )
 
+    case "queue-probe":
+        guard filteredArgs.count >= 2 else {
+            print("❌ Usage: queue-probe <videoId> [playlistId]")
+            print("   playlistId defaults to RDAMVM<videoId>, matching YTMusicClient.getRadioQueue")
+            return
+        }
+        let videoId = filteredArgs[1]
+        let playlistId = filteredArgs.count >= 3 ? filteredArgs[2] : nil
+        await probeQueue(videoId: videoId, playlistId: playlistId, verbose: verbose, outputFile: outputFile)
+
     case "list":
         listEndpoints()
 

Sources/Kaset/Services/Audio/EqualizerService.swift

@@ -298,6 +298,11 @@ final class EqualizerService {
         }
     }
 
+    func awaitPendingPersistence() async {
+        let task = self.persistTask
+        await task?.value
+    }
+
     private func persist() {
         do {
             let data = try Self.encoder.encode(self.settings)

Sources/Kaset/Services/Player/AlbumPlaybackActions.swift

@@ -45,9 +45,14 @@ enum AlbumPlaybackActions {
         client: any YTMusicClientProtocol,
         playerService: PlayerService
     ) {
+        let requestGeneration = playerService.beginPendingPlaybackSelectionRequest()
         Task {
             do {
                 let response = try await client.getPlaylist(id: album.id)
+                guard playerService.isCurrentPendingPlaybackSelectionRequest(requestGeneration) else {
+                    DiagnosticsLogger.ui.info("Discarding stale album playback request")
+                    return
+                }
                 let songs = QueueSongMetadata.albumSongs(
                     response.detail.tracks,
                     album: album,

Sources/Kaset/Services/Player/PlayerQueueModels.swift

@@ -15,6 +15,42 @@ struct QueueEntry: Identifiable, Hashable {
     var source: Source = .queued
 }
 
+// MARK: - QueuePlaybackContext
+
+/// Identifies the queue occurrence and explicit playback generation that owns async navigation work.
+struct QueuePlaybackContext: Equatable {
+    let entryID: UUID?
+    let index: Int
+    let requestGeneration: Int
+    let navigationGeneration: Int
+}
+
+// MARK: - PlaybackNavigationContext
+
+struct PlaybackNavigationContext: Equatable {
+    let requestGeneration: Int
+    let navigationGeneration: Int
+}
+
+// MARK: - RadioQueueFetchOutcome
+
+enum RadioQueueFetchOutcome: Equatable {
+    case applied
+    case unavailable
+    case queueMutated
+    case superseded
+}
+
+// MARK: - PendingNativeQueueAdvance
+
+struct PendingNativeQueueAdvance: Equatable {
+    let sourceEntryID: UUID?
+    let sourceVideoId: String
+    let targetEntryID: UUID
+    let targetVideoId: String
+    let generation: Int
+}
+
 // MARK: - QueueState
 
 struct QueueState {

Sources/Kaset/Services/Player/PlayerService+Episodes.swift

@@ -18,6 +18,7 @@ extension PlayerService {
     /// thumbnail, then installs `currentEpisode` through the player so the UI
     /// can gate live behavior before metadata loading suspends.
     func playEpisode(_ episode: ArtistEpisode) async {
+        self.beginPlaybackRequest()
         self.logger.info("Playing artist episode: \(episode.title) (live=\(episode.isLive))")
 
         // A standalone episode is a new playback context that replaces the queue: supersede any

Sources/Kaset/Services/Player/PlayerService+ManualSeek.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+@MainActor
+extension PlayerService {
+    /// Distance from `duration` at which a manual seek is treated as the end of the track.
+    /// `video.currentTime = duration` does not reliably fire `ended` in WebKit, and a subsequent
+    /// play call would restart the same song from 0 instead of advancing.
+    static let seekToEndThreshold: TimeInterval = 0.5
+
+    /// Routes a manual seek that landed at the end of the track through the track-ended path so
+    /// repeat / queue / autoplay-suppression rules apply consistently with a natural end.
+    func handleManualSeekToEnd() async {
+        self.logger.info("Manual seek reached end of track; routing through track-ended path")
+        self.clearRestoredPlaybackSessionState()
+        self.progress = self.duration
+
+        if !self.queue.isEmpty,
+           self.repeatMode != .one,
+           self.canAdvanceNativeQueueAfterTrackEnd
+        {
+            SingletonPlayerWebView.shared.seekAndPause(to: self.duration)
+            self.clearWebQueueInjectionState()
+            self.clearPendingNativeQueueAdvance()
+            let previousNavigationContext = self.playbackNavigationContext
+            let previousEntryID = self.currentQueueEntryID
+            let didAdvance = await self.performNextNavigation()
+            if !didAdvance,
+               !Task.isCancelled,
+               self.playbackNavigationContext == previousNavigationContext
+            {
+                if await self.advanceToMaterializedNextQueueSongIfAvailable(after: previousEntryID) {
+                    return
+                }
+                await self.finishPlaybackAfterFailedQueueAdvance(
+                    reason: "manual seek continuation produced no next queue entry"
+                )
+            }
+            return
+        }
+
+        if self.shouldSynchronizeWebViewForTerminalManualSeekToEnd {
+            SingletonPlayerWebView.shared.seekAndPause(to: self.duration)
+        }
+
+        await self.handleTrackEnded(observedVideoId: self.currentTrack?.videoId)
+    }
+
+    private var shouldSynchronizeWebViewForTerminalManualSeekToEnd: Bool {
+        if self.queue.isEmpty {
+            return !(self.repeatMode == .one && (self.currentTrack != nil || self.pendingPlayVideoId != nil))
+        }
+
+        return !self.canAdvanceNativeQueueAfterTrackEnd
+    }
+}