From 3b38bcfaa5993d78e819255e7f6d4814db09be98 Mon Sep 17 00:00:00 2001
From: Julian Dice <19397727+windoze95@users.noreply.github.com>
Date: Sat, 27 Jun 2026 22:35:15 -0500
Subject: [PATCH] feat: watch-later queue with optimistic add/remove and player
 auto-advance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire the iOS app up to the new queue API (POST/DELETE
/api/videos/{id}/queue, GET /api/queue).

- ApiService: addToQueue, removeFromQueue, getQueue — getQueue reuses the
  VideoPage cursor envelope, like search.
- queueProvider (Notifier): loads the queue, paginates, and applies
  add/remove optimistically with rollback + rethrow on failure.
  nextAfter() picks the auto-advance target without mutating state.
- Add/Remove-from-Queue actions on home video cards (long-press), search
  results, channel detail, and the player controls. A Queue screen reached
  from the Library app bar lists the queue with tap-to-play and a
  reorder-free remove; pull-to-refresh reloads it.
- Player auto-advance: when a video plays to the end (never on manual
  back-out) it consumes the finished item if queued and plays the next
  queued one. The incoming player re-asserts immersive/landscape so the
  replaced route's teardown can't reset the system UI.

Tests: queue provider — getQueue page parsing, optimistic add/remove with
revert, idempotent add, toggle, pagination, and nextAfter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RXMKM1rDWn8wNh93MMUtxY
---
 lib/config/constants.dart              |   2 +
 lib/config/routes.dart                 |   6 +
 lib/providers/queue_provider.dart      | 204 +++++++++++++++++
 lib/screens/channel_detail_screen.dart |   5 +
 lib/screens/library_screen.dart        |   5 +
 lib/screens/queue_screen.dart          | 217 +++++++++++++++++++
 lib/screens/search_screen.dart         |  14 ++
 lib/screens/video_player_screen.dart   | 113 +++++++++-
 lib/services/api_service.dart          |  27 +++
 lib/widgets/queue_action.dart          | 130 +++++++++++
 lib/widgets/video_card.dart            |  15 ++
 test/unit/queue_notifier_test.dart     | 289 +++++++++++++++++++++++++
 12 files changed, 1025 insertions(+), 2 deletions(-)
 create mode 100644 lib/providers/queue_provider.dart
 create mode 100644 lib/screens/queue_screen.dart
 create mode 100644 lib/widgets/queue_action.dart
 create mode 100644 test/unit/queue_notifier_test.dart

diff --git a/lib/config/constants.dart b/lib/config/constants.dart
index d92ca42..753790f 100644
--- a/lib/config/constants.dart
+++ b/lib/config/constants.dart
@@ -36,6 +36,7 @@ class AppConstants {
   static const String channelPollAll = '$apiBase/channels/poll';
   static const String videos = '$apiBase/videos';
   static const String activeDownloads = '$apiBase/videos/downloads';
+  static const String queue = '$apiBase/queue';
   static const String feedHome = '$apiBase/feed/home';
   static const String feedContinueWatching = '$apiBase/feed/continue-watching';
   static const String feedNewEpisodes = '$apiBase/feed/new-episodes';
@@ -60,6 +61,7 @@ class AppConstants {
   static String videoPreview(String id) => '$apiBase/videos/$id/preview';
   static String videoPreviewStream(String id) =>
       '$apiBase/videos/$id/preview-stream';
+  static String videoQueue(String id) => '$apiBase/videos/$id/queue';
   static String discoverDismiss(String id) => '$apiBase/discover/$id/dismiss';
   static String websocket(String userId) => '/ws/$userId';
 
diff --git a/lib/config/routes.dart b/lib/config/routes.dart
index f2fc299..d9d60f0 100644
--- a/lib/config/routes.dart
+++ b/lib/config/routes.dart
@@ -12,6 +12,7 @@ import '../screens/settings_screen.dart';
 import '../screens/channel_detail_screen.dart';
 import '../screens/video_player_screen.dart';
 import '../screens/search_screen.dart';
+import '../screens/queue_screen.dart';
 
 final _rootNavigatorKey = GlobalKey<NavigatorState>();
 final _shellNavigatorKey = GlobalKey<NavigatorState>();
@@ -105,6 +106,11 @@ final routerProvider = Provider<GoRouter>((ref) {
         parentNavigatorKey: _rootNavigatorKey,
         builder: (context, state) => const SearchScreen(),
       ),
+      GoRoute(
+        path: '/queue',
+        parentNavigatorKey: _rootNavigatorKey,
+        builder: (context, state) => const QueueScreen(),
+      ),
     ],
   );
   ref.onDispose(router.dispose);
diff --git a/lib/providers/queue_provider.dart b/lib/providers/queue_provider.dart
new file mode 100644
index 0000000..0fe8ac0
--- /dev/null
+++ b/lib/providers/queue_provider.dart
@@ -0,0 +1,204 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import '../models/video.dart';
+import '../services/api_service.dart';
+
+/// Immutable state for the watch-later queue: the loaded [videos] in play
+/// order (front first), the pagination cursor and total, plus the loading and
+/// error bookkeeping shared by the Queue screen and the per-video toggles.
+class QueueState {
+  final List<Video> videos;
+
+  /// Opaque cursor for the next queue page, or null when on the last page.
+  final String? nextCursor;
+
+  /// Total queued videos, independent of how many pages are loaded.
+  final int total;
+
+  /// The first page is loading (or reloading).
+  final bool isLoading;
+
+  /// A further page is being appended via [QueueNotifier.loadMore].
+  final bool isLoadingMore;
+
+  final String? error;
+
+  const QueueState({
+    this.videos = const [],
+    this.nextCursor,
+    this.total = 0,
+    this.isLoading = false,
+    this.isLoadingMore = false,
+    this.error,
+  });
+
+  bool get hasMore => nextCursor != null;
+  bool get isEmpty => videos.isEmpty;
+
+  /// Whether [videoId] is in the loaded queue. Membership is only known for
+  /// pages that have been fetched; an unloaded later page reads as absent,
+  /// which is harmless since adding is idempotent server-side.
+  bool isQueued(String videoId) => videos.any((v) => v.id == videoId);
+
+  QueueState copyWith({
+    List<Video>? videos,
+    String? nextCursor,
+    bool clearNextCursor = false,
+    int? total,
+    bool? isLoading,
+    bool? isLoadingMore,
+    String? error,
+    bool clearError = false,
+  }) {
+    return QueueState(
+      videos: videos ?? this.videos,
+      nextCursor: clearNextCursor ? null : (nextCursor ?? this.nextCursor),
+      total: total ?? this.total,
+      isLoading: isLoading ?? this.isLoading,
+      isLoadingMore: isLoadingMore ?? this.isLoadingMore,
+      error: clearError ? null : (error ?? this.error),
+    );
+  }
+}
+
+/// Owns the watch-later queue. Loads the first page on build, paginates on
+/// demand, and applies add/remove optimistically — the UI updates immediately
+/// and only rolls back if the server call fails.
+///
+/// A single non-autoDispose instance is shared app-wide, so the player can
+/// keep advancing through the queue across route replacements and every card's
+/// Add/Remove toggle reflects the same source of truth.
+class QueueNotifier extends Notifier<QueueState> {
+  /// Bumped on every [load] so a slow in-flight page can't overwrite a newer
+  /// reload's results.
+  int _requestId = 0;
+
+  @override
+  QueueState build() {
+    // Deferred so the synchronous part runs after build() returns and `state`
+    // exists.
+    Future.microtask(load);
+    return const QueueState(isLoading: true);
+  }
+
+  ApiService get _api => ref.read(apiServiceProvider);
+
+  /// Fetches the first page, replacing the loaded queue. Existing items stay on
+  /// screen while the request is in flight (the Queue screen only shows a
+  /// full-screen spinner when nothing is loaded yet).
+  Future<void> load() async {
+    final requestId = ++_requestId;
+    state = state.copyWith(isLoading: true, clearError: true);
+    try {
+      final page = await _api.getQueue();
+      if (requestId != _requestId) return;
+      state = state.copyWith(
+        videos: page.items,
+        nextCursor: page.nextCursor,
+        clearNextCursor: page.nextCursor == null,
+        total: page.total,
+        isLoading: false,
+        isLoadingMore: false,
+      );
+    } catch (e) {
+      if (requestId != _requestId) return;
+      state = state.copyWith(
+        isLoading: false,
+        error: e is ApiException ? e.message : 'Failed to load your queue.',
+      );
+    }
+  }
+
+  /// Re-runs the first-page load (pull-to-refresh, retry after error).
+  Future<void> refresh() => load();
+
+  /// Appends the next page. No-op while the first page loads, while already
+  /// appending, or once the last page has been reached.
+  Future<void> loadMore() async {
+    if (state.isLoading || state.isLoadingMore || state.nextCursor == null) {
+      return;
+    }
+    final requestId = _requestId;
+    final cursor = state.nextCursor;
+    state = state.copyWith(isLoadingMore: true);
+    try {
+      final page = await _api.getQueue(cursor: cursor);
+      // A reload started while this page was in flight — drop the result.
+      if (requestId != _requestId) return;
+      state = state.copyWith(
+        videos: [...state.videos, ...page.items],
+        nextCursor: page.nextCursor,
+        clearNextCursor: page.nextCursor == null,
+        total: page.total,
+        isLoadingMore: false,
+      );
+    } catch (_) {
+      if (requestId != _requestId) return;
+      // Keep what's loaded; just stop the footer spinner.
+      state = state.copyWith(isLoadingMore: false);
+    }
+  }
+
+  /// Adds [video] to the end of the queue optimistically, then persists. On
+  /// failure the optimistic change is rolled back and the error rethrown so
+  /// the caller can surface it. No-op (and no network call) if [video] is
+  /// already in the loaded queue, since adding is idempotent.
+  Future<void> add(Video video) async {
+    if (state.isQueued(video.id)) return;
+    final previous = state;
+    state = state.copyWith(
+      videos: [...state.videos, video],
+      total: state.total + 1,
+    );
+    try {
+      await _api.addToQueue(video.id);
+    } catch (_) {
+      state = previous;
+      rethrow;
+    }
+  }
+
+  /// Removes [videoId] from the queue optimistically, then persists, rolling
+  /// back and rethrowing on failure. If the video isn't in the loaded queue
+  /// (e.g. it lives on an unfetched page) the server is still told to remove
+  /// it — there's just nothing to roll back.
+  Future<void> remove(String videoId) async {
+    if (!state.isQueued(videoId)) {
+      await _api.removeFromQueue(videoId);
+      return;
+    }
+    final previous = state;
+    state = state.copyWith(
+      videos: state.videos.where((v) => v.id != videoId).toList(),
+      total: (state.total - 1).clamp(0, previous.total),
+    );
+    try {
+      await _api.removeFromQueue(videoId);
+    } catch (_) {
+      state = previous;
+      rethrow;
+    }
+  }
+
+  /// Toggles [video]'s membership — removes it when queued, adds it otherwise.
+  Future<void> toggle(Video video) =>
+      state.isQueued(video.id) ? remove(video.id) : add(video);
+
+  /// The id of the item to play after [finishedId] finishes, or null if the
+  /// queue can't advance. Pure — does not mutate the queue.
+  ///
+  /// When [finishedId] is in the queue, returns the item directly after it;
+  /// when it isn't (the video was opened from outside the queue), returns the
+  /// queue's head so a finished video still flows into a non-empty queue.
+  String? nextAfter(String finishedId) {
+    final q = state.videos;
+    if (q.isEmpty) return null;
+    final i = q.indexWhere((v) => v.id == finishedId);
+    if (i == -1) return q.first.id;
+    if (i + 1 < q.length) return q[i + 1].id;
+    return null;
+  }
+}
+
+final queueProvider = NotifierProvider<QueueNotifier, QueueState>(
+  QueueNotifier.new,
+);
diff --git a/lib/screens/channel_detail_screen.dart b/lib/screens/channel_detail_screen.dart
index 6cb96b0..156bed3 100644
--- a/lib/screens/channel_detail_screen.dart
+++ b/lib/screens/channel_detail_screen.dart
@@ -11,6 +11,7 @@ import '../providers/feed_provider.dart';
 import '../providers/settings_provider.dart';
 import '../services/api_service.dart';
 import '../services/storage_service.dart';
+import '../widgets/queue_action.dart';
 import '../widgets/video_list_tile.dart';
 import '../widgets/adaptive_layout.dart';
 import '../config/theme.dart';
@@ -480,6 +481,10 @@ class _ChannelDetailScreenState extends ConsumerState<ChannelDetailScreen> {
                 style: const TextStyle(color: NullFeedTheme.textMuted),
               ),
             ),
+            QueueActionTile(
+              video: video,
+              onTap: () => Navigator.pop(sheetContext),
+            ),
             if (video.status == VideoStatus.complete)
               ListTile(
                 leading: const Icon(Icons.download_rounded),
diff --git a/lib/screens/library_screen.dart b/lib/screens/library_screen.dart
index 84c0285..e5d472a 100644
--- a/lib/screens/library_screen.dart
+++ b/lib/screens/library_screen.dart
@@ -149,6 +149,11 @@ class _LibraryScreenState extends ConsumerState<LibraryScreen> {
               title: const Text('Library'),
               backgroundColor: NullFeedTheme.backgroundColor,
               actions: [
+                IconButton(
+                  icon: const Icon(Icons.playlist_play),
+                  tooltip: 'Queue',
+                  onPressed: () => context.push('/queue'),
+                ),
                 IconButton(
                   icon: const Icon(Icons.search),
                   tooltip: 'Search',
diff --git a/lib/screens/queue_screen.dart b/lib/screens/queue_screen.dart
new file mode 100644
index 0000000..0b0b793
--- /dev/null
+++ b/lib/screens/queue_screen.dart
@@ -0,0 +1,217 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+import '../models/video.dart';
+import '../providers/feed_provider.dart';
+import '../providers/queue_provider.dart';
+import '../widgets/queue_action.dart';
+import '../widgets/video_list_tile.dart';
+import '../config/theme.dart';
+
+/// The watch-later queue, reached from the Library app bar. Lists queued videos
+/// in play order; tapping one plays it, and each row's menu offers a
+/// reorder-free remove. Pages load as the list scrolls; pull-to-refresh reloads
+/// the queue from the server.
+class QueueScreen extends ConsumerStatefulWidget {
+  const QueueScreen({super.key});
+
+  @override
+  ConsumerState<QueueScreen> createState() => _QueueScreenState();
+}
+
+class _QueueScreenState extends ConsumerState<QueueScreen> {
+  final _scrollController = ScrollController();
+
+  @override
+  void initState() {
+    super.initState();
+    _scrollController.addListener(_onScroll);
+  }
+
+  @override
+  void dispose() {
+    _scrollController.removeListener(_onScroll);
+    _scrollController.dispose();
+    super.dispose();
+  }
+
+  void _onScroll() {
+    // Prefetch the next page a little before hitting the very bottom.
+    if (_scrollController.position.pixels >=
+        _scrollController.position.maxScrollExtent - 400) {
+      ref.read(queueProvider.notifier).loadMore();
+    }
+  }
+
+  Future<void> _openVideo(String id) async {
+    await context.push('/player/$id');
+    if (!mounted) return;
+    // Watch positions — and the queue itself, via player auto-advance — may
+    // have changed while the player was open.
+    invalidateFeedProviders(ref);
+  }
+
+  void _showMenu(Video video) {
+    showVideoActionsSheet(
+      context,
+      video: video,
+      onPlay: () => _openVideo(video.id),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final state = ref.watch(queueProvider);
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Queue'),
+        backgroundColor: NullFeedTheme.backgroundColor,
+      ),
+      body: RefreshIndicator(
+        color: NullFeedTheme.primaryColor,
+        onRefresh: () => ref.read(queueProvider.notifier).refresh(),
+        child: _QueueBody(
+          state: state,
+          scrollController: _scrollController,
+          onRetry: () => ref.read(queueProvider.notifier).refresh(),
+          onVideoTap: (video) => _openVideo(video.id),
+          onVideoMenu: _showMenu,
+        ),
+      ),
+    );
+  }
+}
+
+class _QueueBody extends StatelessWidget {
+  const _QueueBody({
+    required this.state,
+    required this.scrollController,
+    required this.onRetry,
+    required this.onVideoTap,
+    required this.onVideoMenu,
+  });
+
+  final QueueState state;
+  final ScrollController scrollController;
+  final VoidCallback onRetry;
+  final ValueChanged<Video> onVideoTap;
+  final ValueChanged<Video> onVideoMenu;
+
+  @override
+  Widget build(BuildContext context) {
+    // Always a scrollable so pull-to-refresh works in every state, including
+    // empty/error.
+    return CustomScrollView(
+      controller: scrollController,
+      physics: const AlwaysScrollableScrollPhysics(),
+      slivers: [_buildContent(context)],
+    );
+  }
+
+  Widget _buildContent(BuildContext context) {
+    if (state.isLoading && state.isEmpty) {
+      return const SliverFillRemaining(
+        hasScrollBody: false,
+        child: Center(child: CircularProgressIndicator()),
+      );
+    }
+    if (state.error != null && state.isEmpty) {
+      return SliverFillRemaining(
+        hasScrollBody: false,
+        child: _QueueMessage(
+          icon: Icons.error_outline,
+          iconColor: NullFeedTheme.errorColor,
+          title: 'Could not load your queue',
+          message: state.error!,
+          onRetry: onRetry,
+        ),
+      );
+    }
+    if (state.isEmpty) {
+      return const SliverFillRemaining(
+        hasScrollBody: false,
+        child: _QueueMessage(
+          icon: Icons.playlist_play,
+          iconColor: NullFeedTheme.textMuted,
+          title: 'Your queue is empty',
+          message:
+              'Add videos to watch later from any video’s menu, the '
+              'player, or a channel.',
+        ),
+      );
+    }
+
+    // Items + a footer that spins while the next page loads.
+    return SliverList(
+      delegate: SliverChildBuilderDelegate((context, index) {
+        if (index == state.videos.length) {
+          return SizedBox(
+            height: 64,
+            child: Center(
+              child: state.isLoadingMore
+                  ? const CircularProgressIndicator()
+                  : const SizedBox.shrink(),
+            ),
+          );
+        }
+        final video = state.videos[index];
+        return VideoListTile(
+          video: video,
+          // Always tappable: opening a not-yet-downloaded item starts its
+          // preview, matching how search results behave.
+          onTap: () => onVideoTap(video),
+          onMenu: () => onVideoMenu(video),
+        );
+      }, childCount: state.videos.length + 1),
+    );
+  }
+}
+
+/// Centered full-screen state (empty / error) with an optional Retry button.
+class _QueueMessage extends StatelessWidget {
+  const _QueueMessage({
+    required this.icon,
+    required this.iconColor,
+    required this.title,
+    required this.message,
+    this.onRetry,
+  });
+
+  final IconData icon;
+  final Color iconColor;
+  final String title;
+  final String message;
+  final VoidCallback? onRetry;
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 40),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(icon, size: 64, color: iconColor),
+            const SizedBox(height: 16),
+            Text(
+              title,
+              textAlign: TextAlign.center,
+              style: Theme.of(context).textTheme.headlineSmall,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              message,
+              textAlign: TextAlign.center,
+              style: Theme.of(context).textTheme.bodyMedium,
+            ),
+            if (onRetry != null) ...[
+              const SizedBox(height: 16),
+              OutlinedButton(onPressed: onRetry, child: const Text('Retry')),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+}
diff --git a/lib/screens/search_screen.dart b/lib/screens/search_screen.dart
index b30d831..f343596 100644
--- a/lib/screens/search_screen.dart
+++ b/lib/screens/search_screen.dart
@@ -3,8 +3,10 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:cached_network_image/cached_network_image.dart';
 import '../models/channel.dart';
+import '../models/video.dart';
 import '../providers/feed_provider.dart';
 import '../providers/search_provider.dart';
+import '../widgets/queue_action.dart';
 import '../widgets/video_list_tile.dart';
 import '../config/theme.dart';
 
@@ -55,6 +57,14 @@ class _SearchScreenState extends ConsumerState<SearchScreen> {
     invalidateFeedProviders(ref);
   }
 
+  void _showVideoMenu(Video video) {
+    showVideoActionsSheet(
+      context,
+      video: video,
+      onPlay: () => _openVideo(video.id),
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     final state = ref.watch(searchProvider);
@@ -101,6 +111,7 @@ class _SearchScreenState extends ConsumerState<SearchScreen> {
         scrollController: _scrollController,
         onRetry: notifier.retry,
         onVideoTap: _openVideo,
+        onVideoMenu: _showVideoMenu,
         onChannelTap: (id) => context.push('/channel/$id'),
       ),
     );
@@ -113,6 +124,7 @@ class _SearchBody extends StatelessWidget {
     required this.scrollController,
     required this.onRetry,
     required this.onVideoTap,
+    required this.onVideoMenu,
     required this.onChannelTap,
   });
 
@@ -120,6 +132,7 @@ class _SearchBody extends StatelessWidget {
   final ScrollController scrollController;
   final VoidCallback onRetry;
   final ValueChanged<String> onVideoTap;
+  final ValueChanged<Video> onVideoMenu;
   final ValueChanged<String> onChannelTap;
 
   @override
@@ -173,6 +186,7 @@ class _SearchBody extends StatelessWidget {
             return VideoListTile(
               video: video,
               onTap: () => onVideoTap(video.id),
+              onMenu: () => onVideoMenu(video),
             );
           }, childCount: state.videos.length),
         ),
diff --git a/lib/screens/video_player_screen.dart b/lib/screens/video_player_screen.dart
index e18e1f6..2e79130 100644
--- a/lib/screens/video_player_screen.dart
+++ b/lib/screens/video_player_screen.dart
@@ -3,9 +3,11 @@ import 'dart:io';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:video_player/video_player.dart';
 import 'package:wakelock_plus/wakelock_plus.dart';
 import '../models/video.dart';
+import '../providers/queue_provider.dart';
 import '../providers/websocket_provider.dart';
 import '../services/api_service.dart';
 import '../services/offline_service.dart';
@@ -13,6 +15,7 @@ import '../services/websocket_service.dart';
 import '../config/constants.dart';
 import '../config/theme.dart';
 import '../widgets/progress_bar.dart';
+import '../widgets/queue_action.dart';
 
 class VideoPlayerScreen extends ConsumerStatefulWidget {
   final String videoId;
@@ -36,6 +39,16 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
   bool _startingPlayback = false;
   bool _pendingHqSwitch = false;
   bool _progressSavedOnExit = false;
+
+  /// Set once auto-advance has fired so a stream of post-completion ticks can't
+  /// trigger it again.
+  bool _advancing = false;
+
+  /// The loaded video, once known. Backs the Add/Remove-from-Queue control and
+  /// the auto-advance bookkeeping. Null until the metadata fetch lands (it may
+  /// stay null for offline playback when the server is unreachable).
+  Video? _video;
+
   String? _error;
   late final ApiService _api;
   late final OfflineService _offline;
@@ -46,12 +59,23 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
     super.initState();
     _api = ref.read(apiServiceProvider);
     _offline = ref.read(offlineServiceProvider);
+    _applyImmersiveMode();
+    // Auto-advance replaces this route with the next player in the same frame,
+    // which disposes the previous player — and its dispose() resets the system
+    // UI to edge-to-edge / all-orientations. Re-assert after the frame so the
+    // incoming player always wins that race.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (mounted) _applyImmersiveMode();
+    });
+    _initPlayer();
+  }
+
+  void _applyImmersiveMode() {
     SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
-    SystemChrome.setPreferredOrientations([
+    SystemChrome.setPreferredOrientations(const [
       DeviceOrientation.landscapeLeft,
       DeviceOrientation.landscapeRight,
     ]);
-    _initPlayer();
   }
 
   Future<void> _initPlayer() async {
@@ -113,6 +137,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
     }
 
     _isOfflinePlayback = true;
+    controller.addListener(_onControllerUpdate);
 
     // Prefer the server's resume position (3s budget) but never block
     // playback on the network — fall back to the locally cached position.
@@ -121,6 +146,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
       final video = await _api
           .getVideo(widget.videoId)
           .timeout(const Duration(seconds: 3));
+      _video = video;
       resumeSeconds = video.watchPositionSeconds;
     } catch (_) {
       // Offline or slow server — use the local position.
@@ -175,6 +201,8 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
       return;
     }
 
+    controller.addListener(_onControllerUpdate);
+
     // Rewind 10s on resume so user can re-orient
     if (video.watchPositionSeconds > 0) {
       final resumePos = (video.watchPositionSeconds - 10).clamp(
@@ -196,6 +224,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
       _controller = controller;
       _isInitialized = true;
       _isPreviewMode = isPreview;
+      _video = video;
     });
     _startingPlayback = false;
     // Playback has started — keep the screen awake until the player closes.
@@ -336,6 +365,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
         Uri.parse(streamUrl),
       );
       await hqController.initialize();
+      hqController.addListener(_onControllerUpdate);
       await hqController.seekTo(currentPosition);
       await hqController.setPlaybackSpeed(currentSpeed);
       await hqController.play();
@@ -355,6 +385,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
       // with the HQ controller — disposing it synchronously can leave the
       // outgoing VideoPlayer reading a disposed controller mid-frame.
       WidgetsBinding.instance.addPostFrameCallback((_) {
+        oldController?.removeListener(_onControllerUpdate);
         oldController?.pause();
         oldController?.dispose();
       });
@@ -410,6 +441,52 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
     _scheduleHideControls();
   }
 
+  /// Controller listener that watches for end-of-video to drive queue
+  /// auto-advance. It fires on every value change, so the actual work is
+  /// guarded by [_advancing].
+  void _onControllerUpdate() {
+    final controller = _controller;
+    if (controller == null || !controller.value.isInitialized) return;
+    if (controller.value.isCompleted) _handleCompletion();
+  }
+
+  /// When the video plays through to the end, advance into the queue: consume
+  /// the finished video if it was queued, then play the next queued item.
+  /// Stays put when there's nothing to advance to. Only end-of-video reaches
+  /// here — manual back-out ([_navigateBack]) never auto-advances.
+  void _handleCompletion() {
+    if (_advancing) return;
+    _advancing = true;
+
+    final notifier = ref.read(queueProvider.notifier);
+    // Capture the next target before consuming the finished video, so removal
+    // can't shift it out from under us.
+    final nextId = notifier.nextAfter(widget.videoId);
+    final wasQueued = ref.read(queueProvider).isQueued(widget.videoId);
+
+    // Watch-later semantics: a queued video that finishes is consumed.
+    // Fire-and-forget — a failed removal must not block advancing.
+    if (wasQueued) {
+      unawaited(notifier.remove(widget.videoId).catchError((_) {}));
+    }
+
+    if (nextId == null) return; // Nothing queued after this — stay put.
+
+    // Persist the finished video's final position before moving on; the exit
+    // guard stops dispose() saving it a second time.
+    _progressSavedOnExit = true;
+    unawaited(_saveProgress());
+
+    if (!mounted) return;
+    context.pushReplacement('/player/$nextId');
+  }
+
+  void _toggleQueue() {
+    final video = _video;
+    if (video == null) return;
+    unawaited(toggleVideoQueue(context, ref, video));
+  }
+
   void _navigateBack() {
     // Fire-and-forget the final save so leaving is instant even on a slow or
     // dead network. The guard stops dispose() from saving a second time, so
@@ -497,6 +574,7 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
         );
       }
     }
+    controller?.removeListener(_onControllerUpdate);
     controller?.pause();
     controller?.dispose();
     // Re-allow the screen to sleep now that playback is over.
@@ -508,6 +586,12 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
 
   @override
   Widget build(BuildContext context) {
+    final video = _video;
+    // Drives the Add/Remove-from-Queue control; null hides it until the video
+    // metadata is known.
+    final isQueued = video == null
+        ? null
+        : ref.watch(queueProvider.select((s) => s.isQueued(video.id)));
     return Focus(
       autofocus: true,
       onKeyEvent: _handleKeyEvent,
@@ -637,6 +721,8 @@ class _VideoPlayerScreenState extends ConsumerState<VideoPlayerScreen> {
                   onSeekRelative: _seekRelative,
                   onPlayPause: _togglePlayPause,
                   onInteraction: _scheduleHideControls,
+                  isQueued: isQueued,
+                  onToggleQueue: video == null ? null : _toggleQueue,
                 ),
             ],
           ),
@@ -653,12 +739,19 @@ class _ControlsOverlay extends StatelessWidget {
   final VoidCallback onPlayPause;
   final VoidCallback onInteraction;
 
+  /// Whether the current video is in the watch-later queue. Null hides the
+  /// queue control (the video isn't known yet).
+  final bool? isQueued;
+  final VoidCallback? onToggleQueue;
+
   const _ControlsOverlay({
     required this.controller,
     required this.onBack,
     required this.onSeekRelative,
     required this.onPlayPause,
     required this.onInteraction,
+    this.isQueued,
+    this.onToggleQueue,
   });
 
   @override
@@ -691,6 +784,22 @@ class _ControlsOverlay extends StatelessWidget {
                     onPressed: onBack,
                   ),
                   const Spacer(),
+                  if (onToggleQueue != null)
+                    IconButton(
+                      icon: Icon(
+                        (isQueued ?? false)
+                            ? Icons.playlist_add_check
+                            : Icons.playlist_add,
+                        color: Colors.white,
+                      ),
+                      tooltip: (isQueued ?? false)
+                          ? 'Remove from Queue'
+                          : 'Add to Queue',
+                      onPressed: () {
+                        onToggleQueue!();
+                        onInteraction();
+                      },
+                    ),
                   _SpeedButton(
                     controller: controller,
                     onInteraction: onInteraction,
diff --git a/lib/services/api_service.dart b/lib/services/api_service.dart
index b960913..f1100ef 100644
--- a/lib/services/api_service.dart
+++ b/lib/services/api_service.dart
@@ -443,6 +443,33 @@ class ApiService {
         .toList();
   });
 
+  // Queue (watch-later)
+
+  /// Adds [videoId] to the caller's watch-later queue. Idempotent server-side,
+  /// so re-adding an already-queued video is a no-op rather than an error.
+  Future<void> addToQueue(String videoId) => _guard(() async {
+    await _dio.post('$_baseUrl${AppConstants.videoQueue(videoId)}');
+  });
+
+  /// Removes [videoId] from the queue. Idempotent — removing something that
+  /// isn't queued succeeds.
+  Future<void> removeFromQueue(String videoId) => _guard(() async {
+    await _dio.delete('$_baseUrl${AppConstants.videoQueue(videoId)}');
+  });
+
+  /// One page of the ordered watch-later queue. Uses the same cursor envelope
+  /// as [searchVideos]: pass [VideoPage.nextCursor] back as [cursor] for the
+  /// next page (null = last page). [items] are in play order, front first.
+  Future<VideoPage> getQueue({String? cursor, int limit = 20}) => _guard(
+    () async {
+      final response = await _dio.get(
+        '$_baseUrl${AppConstants.queue}',
+        queryParameters: {if (cursor != null) 'cursor': cursor, 'limit': limit},
+      );
+      return VideoPage.fromJson(response.data as Map<String, dynamic>);
+    },
+  );
+
   // Feed
 
   /// Unified home feed: continue-watching, new-episodes and recently-added in
diff --git a/lib/widgets/queue_action.dart b/lib/widgets/queue_action.dart
new file mode 100644
index 0000000..39a7108
--- /dev/null
+++ b/lib/widgets/queue_action.dart
@@ -0,0 +1,130 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import '../config/theme.dart';
+import '../models/video.dart';
+import '../providers/queue_provider.dart';
+import '../services/api_service.dart';
+
+/// Adds or removes [video] from the watch-later queue and reports the outcome
+/// with a snackbar via the nearest [ScaffoldMessenger].
+///
+/// The queue updates optimistically inside the notifier, so the change is on
+/// screen before this future completes; a failed server call rolls it back and
+/// the snackbar surfaces the error instead.
+Future<void> toggleVideoQueue(
+  BuildContext context,
+  WidgetRef ref,
+  Video video,
+) {
+  return _applyToggle(
+    ScaffoldMessenger.of(context),
+    ref.read(queueProvider.notifier),
+    video,
+    wasQueued: ref.read(queueProvider).isQueued(video.id),
+  );
+}
+
+Future<void> _applyToggle(
+  ScaffoldMessengerState messenger,
+  QueueNotifier notifier,
+  Video video, {
+  required bool wasQueued,
+}) async {
+  try {
+    await (wasQueued ? notifier.remove(video.id) : notifier.add(video));
+    messenger.showSnackBar(
+      SnackBar(
+        content: Text(wasQueued ? 'Removed from queue' : 'Added to queue'),
+      ),
+    );
+  } on ApiException catch (e) {
+    messenger.showSnackBar(SnackBar(content: Text(e.message)));
+  }
+}
+
+/// A bottom-sheet row that toggles [video]'s queue membership; its label and
+/// icon track the live queue state. Pass [onTap] to dismiss the surrounding
+/// sheet — it runs first, before the (optimistic) toggle is applied.
+class QueueActionTile extends ConsumerWidget {
+  const QueueActionTile({super.key, required this.video, this.onTap});
+
+  final Video video;
+  final VoidCallback? onTap;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final isQueued = ref.watch(
+      queueProvider.select((s) => s.isQueued(video.id)),
+    );
+    return ListTile(
+      leading: Icon(isQueued ? Icons.playlist_add_check : Icons.playlist_add),
+      title: Text(isQueued ? 'Remove from Queue' : 'Add to Queue'),
+      onTap: () {
+        // Capture everything that outlives this tile before the sheet pops —
+        // the messenger and notifier survive the dismissal, the element does
+        // not.
+        final messenger = ScaffoldMessenger.of(context);
+        final notifier = ref.read(queueProvider.notifier);
+        final wasQueued = ref.read(queueProvider).isQueued(video.id);
+        onTap?.call();
+        unawaited(
+          _applyToggle(messenger, notifier, video, wasQueued: wasQueued),
+        );
+      },
+    );
+  }
+}
+
+/// Shows the standard per-video actions sheet — an optional Play row, the queue
+/// toggle, and an optional "Go to channel" row — for surfaces without a bespoke
+/// menu of their own (video cards, search results).
+Future<void> showVideoActionsSheet(
+  BuildContext context, {
+  required Video video,
+  VoidCallback? onPlay,
+  VoidCallback? onOpenChannel,
+}) {
+  return showModalBottomSheet<void>(
+    context: context,
+    backgroundColor: NullFeedTheme.cardColor,
+    builder: (sheetContext) => SafeArea(
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          ListTile(
+            title: Text(
+              video.title,
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+              style: const TextStyle(color: NullFeedTheme.textMuted),
+            ),
+          ),
+          if (onPlay != null)
+            ListTile(
+              leading: const Icon(Icons.play_arrow),
+              title: const Text('Play'),
+              onTap: () {
+                Navigator.pop(sheetContext);
+                onPlay();
+              },
+            ),
+          QueueActionTile(
+            video: video,
+            onTap: () => Navigator.pop(sheetContext),
+          ),
+          if (onOpenChannel != null)
+            ListTile(
+              leading: const Icon(Icons.open_in_new),
+              title: const Text('Go to channel'),
+              onTap: () {
+                Navigator.pop(sheetContext);
+                onOpenChannel();
+              },
+            ),
+        ],
+      ),
+    ),
+  );
+}
diff --git a/lib/widgets/video_card.dart b/lib/widgets/video_card.dart
index 581c97e..82645d2 100644
--- a/lib/widgets/video_card.dart
+++ b/lib/widgets/video_card.dart
@@ -10,6 +10,7 @@ import '../config/constants.dart';
 import '../providers/feed_provider.dart';
 import '../providers/offline_provider.dart';
 import 'progress_bar.dart';
+import 'queue_action.dart';
 
 class VideoCard extends ConsumerStatefulWidget {
   final Video video;
@@ -64,6 +65,18 @@ class _VideoCardState extends ConsumerState<VideoCard> {
     context.push('/channel/${channel.id}');
   }
 
+  /// Long-press actions: play, toggle the watch-later queue, and (when known)
+  /// jump to the channel.
+  void _showMenu() {
+    HapticFeedback.selectionClick();
+    showVideoActionsSheet(
+      context,
+      video: widget.video,
+      onPlay: _onActivate,
+      onOpenChannel: widget.channel != null ? _openChannel : null,
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     const cardWidth = AppConstants.videoCardWidth;
@@ -85,10 +98,12 @@ class _VideoCardState extends ConsumerState<VideoCard> {
               label: _semanticLabel(offlineStatus),
               excludeSemantics: true,
               onTap: _onActivate,
+              onLongPress: _showMenu,
               child: Material(
                 type: MaterialType.transparency,
                 child: InkWell(
                   onTap: _onActivate,
+                  onLongPress: _showMenu,
                   onTapDown: (_) => setState(() => _isPressed = true),
                   onTapUp: (_) => setState(() => _isPressed = false),
                   onTapCancel: () => setState(() => _isPressed = false),
diff --git a/test/unit/queue_notifier_test.dart b/test/unit/queue_notifier_test.dart
new file mode 100644
index 0000000..a18b69e
--- /dev/null
+++ b/test/unit/queue_notifier_test.dart
@@ -0,0 +1,289 @@
+import 'dart:async';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:nullfeed/models/video.dart';
+import 'package:nullfeed/models/video_page.dart';
+import 'package:nullfeed/providers/queue_provider.dart';
+import 'package:nullfeed/services/api_service.dart';
+
+import '../helpers/test_helpers.dart';
+
+void main() {
+  late MockApiService api;
+
+  setUp(() {
+    api = MockApiService();
+  });
+
+  Video video(String id, {String title = 'A Video'}) =>
+      Video(id: id, youtubeVideoId: 'yt-$id', channelId: 'c1', title: title);
+
+  /// Lets [QueueNotifier.build]'s deferred first load and any awaited API calls
+  /// settle.
+  Future<void> settle() =>
+      Future<void>.delayed(const Duration(milliseconds: 20));
+
+  /// Builds a container whose queue has finished its initial load with
+  /// [initial] as the first page.
+  Future<ProviderContainer> seededContainer(
+    List<Video> initial, {
+    String? nextCursor,
+    int? total,
+  }) async {
+    when(() => api.getQueue()).thenAnswer(
+      (_) async => VideoPage(
+        items: initial,
+        total: total ?? initial.length,
+        nextCursor: nextCursor,
+      ),
+    );
+    final container = ProviderContainer(
+      overrides: [apiServiceProvider.overrideWithValue(api)],
+    );
+    addTearDown(container.dispose);
+    container.read(queueProvider);
+    await settle();
+    return container;
+  }
+
+  group('initial load', () {
+    test(
+      'maps the getQueue page (items, total, next_cursor) into state',
+      () async {
+        when(() => api.getQueue()).thenAnswer(
+          (_) async => VideoPage(
+            items: [video('v1'), video('v2')],
+            total: 5,
+            nextCursor: 'cursor-1',
+          ),
+        );
+        final container = ProviderContainer(
+          overrides: [apiServiceProvider.overrideWithValue(api)],
+        );
+        addTearDown(container.dispose);
+
+        container.read(queueProvider);
+        await settle();
+
+        final state = container.read(queueProvider);
+        expect(state.videos.map((v) => v.id), ['v1', 'v2']);
+        expect(state.total, 5);
+        expect(state.nextCursor, 'cursor-1');
+        expect(state.hasMore, isTrue);
+        expect(state.isLoading, isFalse);
+        expect(state.error, isNull);
+      },
+    );
+
+    test('reports an empty queue', () async {
+      final container = await seededContainer(const []);
+
+      final state = container.read(queueProvider);
+      expect(state.isEmpty, isTrue);
+      expect(state.hasMore, isFalse);
+      expect(state.error, isNull);
+    });
+
+    test('surfaces an ApiException message as the error', () async {
+      when(() => api.getQueue()).thenThrow(
+        const ApiException(message: 'Server exploded', statusCode: 500),
+      );
+      final container = ProviderContainer(
+        overrides: [apiServiceProvider.overrideWithValue(api)],
+      );
+      addTearDown(container.dispose);
+
+      container.read(queueProvider);
+      await settle();
+
+      final state = container.read(queueProvider);
+      expect(state.error, 'Server exploded');
+      expect(state.isLoading, isFalse);
+      expect(state.isEmpty, isTrue);
+    });
+  });
+
+  group('optimistic add', () {
+    test('appends to the end immediately, before the server responds', () async {
+      final container = await seededContainer([video('v1')], total: 1);
+      final notifier = container.read(queueProvider.notifier);
+
+      // A pending server call so the optimistic state is observable on its own.
+      final completer = Completer<void>();
+      when(() => api.addToQueue('v2')).thenAnswer((_) => completer.future);
+
+      final future = notifier.add(video('v2'));
+
+      // Optimistic: in the queue and counted before the call resolves.
+      final mid = container.read(queueProvider);
+      expect(mid.videos.map((v) => v.id), ['v1', 'v2']);
+      expect(mid.total, 2);
+
+      completer.complete();
+      await future;
+
+      expect(container.read(queueProvider).isQueued('v2'), isTrue);
+      verify(() => api.addToQueue('v2')).called(1);
+    });
+
+    test('reverts and rethrows when the server call fails', () async {
+      final container = await seededContainer([video('v1')], total: 1);
+      final notifier = container.read(queueProvider.notifier);
+
+      when(
+        () => api.addToQueue('v2'),
+      ).thenThrow(const ApiException(message: 'nope'));
+
+      await expectLater(
+        notifier.add(video('v2')),
+        throwsA(isA<ApiException>()),
+      );
+
+      final state = container.read(queueProvider);
+      expect(state.isQueued('v2'), isFalse);
+      expect(state.videos.map((v) => v.id), ['v1']);
+      expect(state.total, 1);
+    });
+
+    test('is a no-op (no network call) for an already-queued video', () async {
+      final container = await seededContainer([video('v1')], total: 1);
+      final notifier = container.read(queueProvider.notifier);
+
+      await notifier.add(video('v1'));
+
+      expect(container.read(queueProvider).total, 1);
+      verifyNever(() => api.addToQueue(any()));
+    });
+  });
+
+  group('optimistic remove', () {
+    test('removes immediately and persists on success', () async {
+      final container = await seededContainer([
+        video('v1'),
+        video('v2'),
+      ], total: 2);
+      final notifier = container.read(queueProvider.notifier);
+      when(() => api.removeFromQueue('v2')).thenAnswer((_) async {});
+
+      await notifier.remove('v2');
+
+      final state = container.read(queueProvider);
+      expect(state.videos.map((v) => v.id), ['v1']);
+      expect(state.total, 1);
+      verify(() => api.removeFromQueue('v2')).called(1);
+    });
+
+    test('reverts and rethrows when the server call fails', () async {
+      final container = await seededContainer([
+        video('v1'),
+        video('v2'),
+      ], total: 2);
+      final notifier = container.read(queueProvider.notifier);
+      when(
+        () => api.removeFromQueue('v1'),
+      ).thenThrow(const ApiException(message: 'nope'));
+
+      await expectLater(notifier.remove('v1'), throwsA(isA<ApiException>()));
+
+      final state = container.read(queueProvider);
+      expect(state.videos.map((v) => v.id), ['v1', 'v2']);
+      expect(state.total, 2);
+    });
+  });
+
+  group('toggle', () {
+    test('adds when absent, removes when present', () async {
+      final container = await seededContainer([video('v1')], total: 1);
+      final notifier = container.read(queueProvider.notifier);
+      when(() => api.addToQueue('v2')).thenAnswer((_) async {});
+      when(() => api.removeFromQueue('v2')).thenAnswer((_) async {});
+
+      await notifier.toggle(video('v2'));
+      expect(container.read(queueProvider).isQueued('v2'), isTrue);
+
+      await notifier.toggle(video('v2'));
+      expect(container.read(queueProvider).isQueued('v2'), isFalse);
+
+      verify(() => api.addToQueue('v2')).called(1);
+      verify(() => api.removeFromQueue('v2')).called(1);
+    });
+  });
+
+  group('pagination', () {
+    test(
+      'loadMore appends the next page and clears the final cursor',
+      () async {
+        final container = await seededContainer(
+          [video('v1')],
+          nextCursor: 'c1',
+          total: 3,
+        );
+        when(() => api.getQueue(cursor: 'c1')).thenAnswer(
+          (_) async => VideoPage(items: [video('v2'), video('v3')], total: 3),
+        );
+        expect(container.read(queueProvider).hasMore, isTrue);
+
+        await container.read(queueProvider.notifier).loadMore();
+
+        final state = container.read(queueProvider);
+        expect(state.videos.map((v) => v.id), ['v1', 'v2', 'v3']);
+        expect(state.nextCursor, isNull);
+        expect(state.hasMore, isFalse);
+        expect(state.isLoadingMore, isFalse);
+      },
+    );
+
+    test('loadMore is a no-op once on the last page', () async {
+      final container = await seededContainer([video('v1')], total: 1);
+
+      await container.read(queueProvider.notifier).loadMore();
+
+      // Only the initial load hit the API — no cursor page was fetched.
+      verify(() => api.getQueue()).called(1);
+      verifyNever(() => api.getQueue(cursor: any(named: 'cursor')));
+    });
+  });
+
+  group('nextAfter (auto-advance target)', () {
+    test('returns the item after the finished one', () async {
+      final container = await seededContainer([
+        video('v1'),
+        video('v2'),
+        video('v3'),
+      ], total: 3);
+      final notifier = container.read(queueProvider.notifier);
+
+      expect(notifier.nextAfter('v1'), 'v2');
+      expect(notifier.nextAfter('v2'), 'v3');
+    });
+
+    test('returns null after the last queued item', () async {
+      final container = await seededContainer([
+        video('v1'),
+        video('v2'),
+      ], total: 2);
+
+      expect(container.read(queueProvider.notifier).nextAfter('v2'), isNull);
+    });
+
+    test('returns the head when the finished video is not queued', () async {
+      final container = await seededContainer([
+        video('v1'),
+        video('v2'),
+      ], total: 2);
+
+      expect(
+        container.read(queueProvider.notifier).nextAfter('outsider'),
+        'v1',
+      );
+    });
+
+    test('returns null when the queue is empty', () async {
+      final container = await seededContainer(const []);
+
+      expect(container.read(queueProvider.notifier).nextAfter('v1'), isNull);
+    });
+  });
+}