docs: update YouTube support documentation (#321)

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Author: sozercan

AGENTS.md

@@ -6,7 +6,7 @@ Guidance for AI coding assistants working on this repository.
 
 You are a Senior Swift Engineer specializing in SwiftUI, Swift Concurrency, and macOS development. Your code must adhere to Apple's Human Interface Guidelines. Target **Swift 6.0+** and **macOS 26.0+**.
 
-Kaset is a native macOS YouTube Music client (Swift/SwiftUI) using a hidden WebView for DRM playback and `YTMusicClient` API calls for all data fetching.
+Kaset is a native macOS client for YouTube Music and YouTube (Swift/SwiftUI). It uses WebViews only for DRM/playback/auth surfaces and uses `YTMusicClient` / `YouTubeClient` API calls for data fetching.
 
 ## Critical Rules
 
@@ -16,7 +16,7 @@ Kaset is a native macOS YouTube Music client (Swift/SwiftUI) using a hidden WebV
 
 > ⚠️ **No Third-Party Frameworks** — Do not introduce third-party dependencies without asking first.
 
-> ⚠️ **Prefer API over WebView** — Always use `YTMusicClient` API calls when functionality exists. Only use WebView for playback (DRM-protected audio) and authentication.
+> ⚠️ **Prefer API over WebView** — Always use `YTMusicClient` (YouTube Music) or `YouTubeClient` (YouTube) API calls when functionality exists. Only use WebView for playback (DRM-protected media) and authentication.
 
 > 🔧 **Improve API Explorer, Don't Write One-Off Scripts** — When exploring or debugging API-related functionality, **always enhance `Sources/APIExplorer/main.swift`** instead of writing temporary scripts.
 

CONTEXT.md

@@ -1,8 +1,24 @@
 # Kaset Domain Language
 
+## App Source
+
+The active content experience selected by the sidebar source toggle. `.music` is the YouTube Music experience and remains the default; `.video` is the regular YouTube experience. Source switches swap the visible navigation surface without merging the two data models.
+
+## Music Experience
+
+Kaset's YouTube Music surface: songs, albums, artists, playlists, podcasts, lyrics, queue management, and DRM audio playback through the hidden `SingletonPlayerWebView`. Data fetching belongs to `YTMusicClient` and music-specific parsers.
+
+## YouTube Experience
+
+Kaset's regular YouTube surface: recommendations, search, subscriptions, Shorts, channels, playlists, Watch Later, history, comments, and video playback through `YouTubeWatchWebView`. Data fetching belongs to `YouTubeClient` and YouTube-specific parsers under `Services/API/Parsers/YouTube/`.
+
+## Playback Arbiter
+
+The coordinator that keeps YouTube Music and regular YouTube from playing over each other. It pauses music when a YouTube video starts, pauses YouTube video when music starts, and lets media-key handling follow whichever source played most recently.
+
 ## Library
 
-The signed-in user's saved YouTube Music collection. Kaset surfaces Library content as playlists, followed artists, subscribed podcast shows, and uploaded songs.
+The signed-in user's saved YouTube Music collection. Kaset surfaces Music Library content as playlists, followed artists, subscribed podcast shows, and uploaded songs. Regular YouTube has separate library-like surfaces such as subscriptions, Watch Later, liked videos, history, and playlists.
 
 ## Library Content Identity
 

CONTRIBUTING.md

@@ -20,8 +20,8 @@ cd kaset
 # Build from command line
 swift build
 
-# Run tests
-swift test
+# Run unit tests (do not combine with UI tests)
+swift test --skip KasetUITests
 
 # Package and run the app
 Scripts/compile_and_run.sh
@@ -44,13 +44,13 @@ Sources/
   └── Kaset/            → Main app target
       ├── Models/       → Data models (Song, Playlist, Album, Artist, etc.)
       ├── Services/
-      │   ├── API/      → YTMusicClient (YouTube Music API calls)
+      │   ├── API/      → YTMusicClient + YouTubeClient (InnerTube API calls)
       │   ├── Auth/     → AuthService (login state machine)
       │   ├── Player/   → PlayerService, NowPlayingManager (playback, media keys)
       │   └── WebKit/   → WebKitManager (cookie store, persistent login)
-      ├── ViewModels/   → HomeViewModel, LibraryViewModel, SearchViewModel
+      ├── ViewModels/   → Music view models plus YouTube/ video-source view models
       ├── Utilities/    → DiagnosticsLogger, extensions
-      └── Views/        → SwiftUI views (MainWindow, Sidebar, PlayerBar, etc.)
+      └── Views/        → SwiftUI views (MainWindow, Sidebar, PlayerBar, YouTube views, etc.)
   └── APIExplorer/      → API explorer CLI tool
 Tests/                  → Unit tests (KasetTests/)
 Scripts/                → Build scripts
@@ -64,8 +64,12 @@ docs/                   → Detailed documentation
 | `Sources/Kaset/AppDelegate.swift`                   | Window lifecycle, background audio support |
 | `Sources/Kaset/Services/WebKit/WebKitManager.swift` | Cookie store & persistence                 |
 | `Sources/Kaset/Services/Auth/AuthService.swift`     | Login state machine                        |
+| `Sources/Kaset/Services/API/YTMusicClient.swift`    | YouTube Music API client                   |
+| `Sources/Kaset/Services/API/YouTubeClient.swift`    | Regular YouTube API client                 |
 | `Sources/Kaset/Services/Player/PlayerService.swift` | Playback state & control                   |
+| `Sources/Kaset/Services/Player/YouTubePlayerService.swift` | Regular YouTube playback state & control   |
 | `Sources/Kaset/Views/MiniPlayerWebView.swift`       | Singleton WebView, playback UI             |
+| `Sources/Kaset/Views/YouTube/YouTubeWatchWebView.swift` | Singleton WebView for regular YouTube watch playback |
 | `Sources/Kaset/Views/MainWindow.swift`              | Main app window                            |
 | `Sources/Kaset/Utilities/DiagnosticsLogger.swift`   | Logging                                    |
 
@@ -75,6 +79,7 @@ For detailed architecture documentation, see the `docs/` folder:
 
 - **[docs/architecture.md](docs/architecture.md)** — Services, state management, data flow
 - **[docs/playback.md](docs/playback.md)** — WebView playback system, background audio
+- **[docs/youtube.md](docs/youtube.md)** — Regular YouTube source, video playback, Shorts, comments, and parser strategy
 - **[docs/testing.md](docs/testing.md)** — Test commands, patterns, debugging
 
 ### High-Level Overview
@@ -83,11 +88,20 @@ The app uses a clean architecture with:
 
 - **Observable Pattern**: `@Observable` classes for reactive state management
 - **MainActor Isolation**: All UI and service classes are `@MainActor` for thread safety
-- **WebKit Integration**: Persistent `WKWebsiteDataStore` for cookie management
+- **Dual Source Model**: YouTube Music and regular YouTube are parallel experiences behind a sidebar source toggle
+- **WebKit Integration**: Persistent `WKWebsiteDataStore` for cookie management, authentication, and DRM playback
 - **Swift Concurrency**: `async`/`await` throughout, no `DispatchQueue`
 
 ### Playback Architecture
 
+Kaset has two playback paths. YouTube Music uses `PlayerService` plus the
+`SingletonPlayerWebView` at `music.youtube.com`; regular YouTube uses
+`YouTubePlayerService` plus `YouTubeWatchWebView` at `www.youtube.com`.
+`PlaybackArbiter` keeps one audio source active at a time and media keys route
+to the source that played most recently.
+
+#### YouTube Music
+
 ```
 User clicks Play
     │
@@ -111,6 +125,25 @@ PlayerService.play(videoId:)
             - duration
 ```
 
+#### Regular YouTube
+
+```
+User opens a YouTube video
+    │
+    ▼
+YouTubePlayerService.play(video:)
+    │
+    ├── Sets active video metadata
+    ├── Loads www.youtube.com/watch?v={id}
+    └── Hosts YouTubeWatchWebView inline or in the floating window
+            │
+            ▼
+    JavaScript bridge sends state, captions, quality, and ad updates
+            │
+            ▼
+    YouTubePlayerService updates playback state and YouTubePlayerBar
+```
+
 ### Authentication Flow
 
 ```
@@ -128,9 +161,9 @@ Observer detects cookie → Dismiss sheet
 ### Background Audio
 
 ```
-Close window (⌘W) → Window hides → Audio continues
-Click dock icon    → Window shows → Same WebView
-Quit app (⌘Q)     → App terminates → Audio stops
+Close window (⌘W) → Window hides → active playback continues
+Click dock icon    → Window shows → same Music/YouTube WebView state
+Quit app (⌘Q)     → App terminates → playback stops
 ```
 
 ## Coding Guidelines
@@ -198,7 +231,7 @@ final class MyServiceTests: XCTestCase {
 
 1. **No Third-Party Frameworks** — Do not introduce third-party dependencies without discussion first
 2. **Build Must Pass** — Run `swift build`
-3. **Tests Must Pass** — Run `swift test`
+3. **Tests Must Pass** — Run `swift test --skip KasetUITests` for unit tests
 4. **Linting** — Run `swiftlint --strict && swiftformat .` before submitting
 5. **Small PRs** — Keep changes focused and reviewable
 6. **Share AI Prompts** — If you used AI assistance, include the prompt in your PR (see below)
@@ -255,11 +288,11 @@ Reference: Sources/Kaset/Services/HapticService.swift for existing patterns
 ## Testing
 
 ```bash
-# Run all tests
-swift test
+# Run unit tests
+swift test --skip KasetUITests
 
-# Run specific test (use --filter)
-swift test --filter PlayerServiceTests
+# Run specific unit test (use --filter)
+swift test --skip KasetUITests --filter PlayerServiceTests
 ```
 
 See [docs/testing.md](docs/testing.md) for detailed testing patterns and debugging tips.

README.md

@@ -1,18 +1,19 @@
 # Kaset
 
-A native macOS YouTube Music client built with Swift and SwiftUI.
+A native macOS client for YouTube Music and YouTube, built with Swift and SwiftUI.
 
 <img src="docs/screenshot.png" alt="Kaset Screenshot">
 
 ## Features
 
-- 🎵 **Native macOS Experience** — Apple Music-style UI with Liquid Glass player bar and clean sidebar navigation
-- 🎧 **YouTube Music Premium Support** — Full playback of DRM-protected content via your existing subscription
+- 🎵 **Native macOS Experience** — Apple Music-style UI with Liquid Glass player bars, clean sidebar navigation, and a source toggle for Music ↔ YouTube
+- 🎧 **YouTube Music Support** — Full playback of DRM-protected YouTube Music content via your existing Premium subscription
+- ▶️ **[YouTube Support](docs/youtube.md)** — Browse regular YouTube recommendations, search, subscriptions, Shorts, Watch Later, history, comments, and video playback with native controls, captions, quality selection, and picture in picture
 - 🎛️ **System Integration** — Now Playing in Control Center, media key support, Dock menu controls
 - 📳 **Haptic Feedback** — Tactile feedback on Force Touch trackpads for player controls and navigation
 - 🎶 **Track Notifications** — Get notified when a new track starts playing
 - 🔊 **Background Audio** — Music continues playing when the window is closed; stops on quit
-- 🎚️ **Equalizer** — System-wide 6-band parametric EQ with Spotify-style presets, applied to YouTube Music output
+- 🎚️ **Equalizer** — System-wide 6-band parametric EQ with Spotify-style presets, applied to WebKit playback output
 - ⌨️ **[Keyboard Shortcuts](docs/keyboard-shortcuts.md)** — Full keyboard control for playback, navigation, and more
 - 🧭 **Explore** — Discover new releases, charts, and moods & genres
 - 🎙️ **Podcasts** — Browse and listen to podcasts with episode progress tracking
@@ -24,16 +25,15 @@ A native macOS YouTube Music client built with Swift and SwiftUI.
 - 📜 **Lyrics** — View plain and synced lyrics with line-by-line highlighting when timing data is available, plus AI-powered explanations and mood analysis on macOS 26+
 - 📃 **Queue Management** — View, reorder, shuffle, and clear your playback queue
 - 📣 **Share** — Share songs, playlists, albums, and artists via the native macOS share sheet
-- ▶️ **[YouTube Mode](docs/youtube.md)** — Flip the sidebar source toggle for a native regular-YouTube client: recommendations, search, subscriptions, Shorts, Watch Later, history, comments, and video playback with native controls, captions, quality selection, and picture in picture
-- 🔗 **[URL Scheme](docs/url-scheme.md)** — Open songs directly with `kaset://play?v=VIDEO_ID`; YouTube watch and `youtu.be` links play in YouTube mode
+- 🔗 **[URL Scheme](docs/url-scheme.md)** — Open songs directly with `kaset://play?v=VIDEO_ID`; app-targeted YouTube watch and `youtu.be` links play in YouTube mode
 - 🤖 **[AppleScript Support](docs/applescript.md)** — Automate playback with scripts, Raycast, Alfred, and Shortcuts
 - 🧩 **[Extensions](docs/extensions.md)** — Load WebKit Web Extensions, including [uBlock Origin Lite](https://github.com/uBlockOrigin/uBOL-home)
 
 ## Requirements
 
 - macOS 15.4 or later
 - Apple Intelligence features require macOS 26.0 or later
-- [Google](https://accounts.google.com) account
+- [Google](https://accounts.google.com) account for YouTube Music and YouTube personalization
 
 ## Installation