Merge manual video quality/dimensions with adaptive stream (#1047)

## Summary

Previously, `setVideoQuality` / `setVideoDimensions` on a remote track
were **ignored** (with a warning) whenever `adaptiveStream` was enabled.
This PR adopts the JS SDK's approach instead: the manual preference is
**merged** client-side with the dimensions derived from the visible
views, and the **smaller (more conservative)** of the two is sent to the
server.

Along the way it fixes a few related correctness issues in the
adaptive-stream path. The logic mirrors `client-sdk-js`'s
`RemoteTrackPublication` (`isEnabled`, `emitTrackUpdate`,
`areDimensionsSmaller`, `layerDimensionsFor`).

## Changes

**Manual quality + adaptive stream merge**
- `setVideoQuality` / `setVideoDimensions` / `setVideoFPS` are no longer
rejected when adaptive stream is on; the request is merged with the
visibility-derived dimensions, smaller area wins (matching JS
`areDimensionsSmaller`, strict `<`).
- When only a quality is requested, it's compared against that quality's
simulcast layer dimensions before deciding which to send.

**Explicit enable/disable overrides visibility**
- Enable/disable state is modeled as an internal tri-state
(`TrackEnabledPreference`: unset / enabled / disabled), mirroring JS's
`requestedDisabled`.
- An explicit `enable()` / `disable()` now always wins over
adaptive-stream visibility. Previously the visibility timer computed
`disabled` independently and silently ignored the user's request.

**Debounce correctness**
- A manual update cancels any pending debounced visibility update, and
the debounced send rebuilds settings from current state at fire time —
so a stale snapshot can't clobber a newer manual update.

**Misc**
- `fps` is now preserved across adaptive-stream visibility updates
(previously dropped).
- Adaptive-stream visibility state is reset when the track changes, so
stale dimensions can't leak into a later update.
- Merge/disable/build logic extracted into pure functions
(`resolveVideoSettings`, `resolveDisabled`, `buildUpdateTrackSettings`)
in `track_settings.dart`.

## Tests
- Unit tests for the pure resolution/build logic: merge precedence,
equal-area tie-break, tri-state disable, and proto building.
- Publication-level test asserting the `UpdateTrackSettings` actually
sent to the signal client for `enable()` / `disable()`.

Author: hiroshihorie

.changes/adaptive-stream-manual-quality-merge

@@ -0,0 +1 @@
+patch type="improved" "Allow manual video quality selection with adaptive stream enabled"

lib/src/publication/remote.dart

@@ -33,6 +33,7 @@ import '../types/other.dart';
 import '../types/video_dimensions.dart';
 import '../utils.dart';
 import 'track_publication.dart';
+import 'track_settings.dart';
 
 /// Represents a track publication from a RemoteParticipant. Provides methods to
 /// control if we should subscribe to the track, and its quality (for video).
@@ -41,18 +42,35 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
   @override
   final RemoteParticipant participant;
 
-  bool get enabled => _enabled;
-  bool _enabled = true;
+  bool get enabled => !resolveDisabled(
+        enabledPreference: _enabledPreference,
+        adaptiveStreamActive: _adaptiveStreamActive,
+        adaptiveStreamVisible: _adaptiveStreamVisible,
+      );
+
+  /// The user's explicit enable/disable request via [enable] / [disable].
+  /// [TrackEnabledPreference.unset] means no explicit request, in which case
+  /// adaptive-stream visibility decides. An explicit request takes precedence
+  /// over visibility.
+  TrackEnabledPreference _enabledPreference = TrackEnabledPreference.unset;
 
   /// The current desired FPS of the track. This is only available for video tracks that support SVC.
   int? _fps;
   int get fps => _fps ?? 0;
 
-  VideoQuality? _videoQuality = VideoQuality.HIGH;
-  VideoQuality get videoQuality => _videoQuality ?? VideoQuality.HIGH;
+  // Manual settings (set by user via setVideoQuality / setVideoDimensions)
+  VideoSettings? _userPreference;
+
+  // Adaptive stream state (set automatically by visibility observer)
+  VideoDimensions? _adaptiveStreamDimensions;
+  // Whether adaptive stream is active for this publication (room option on +
+  // remote video track). When false, view visibility never gates `disabled`.
+  bool _adaptiveStreamActive = false;
+  // Whether at least one view of this track is currently visible/sized.
+  bool _adaptiveStreamVisible = true;
 
-  VideoDimensions? _videoDimensions;
-  VideoDimensions? get videoDimensions => _videoDimensions;
+  VideoQuality get videoQuality => _userPreference?.quality ?? VideoQuality.HIGH;
+  VideoDimensions? get videoDimensions => _userPreference?.dimensions;
 
   /// The server may pause the track when they are bandwidth limitations and resume
   /// when there is more capacity. This property will be updated when the track is
@@ -144,11 +162,6 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
 
     final videoTrack = track as VideoTrack;
 
-    final settings = lk_rtc.UpdateTrackSettings(
-      trackSids: [sid],
-      disabled: true,
-    );
-
     // filter visible build contexts
     final viewSizes = videoTrack.viewKeys
         .map((e) => e.currentContext)
@@ -161,15 +174,19 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
     logger.finer('[Visibility] ${track?.sid} watching ${viewSizes.length} views...');
 
     if (viewSizes.isNotEmpty) {
-      // compute largest size
       final largestSize = viewSizes.reduce((value, element) => maxOfSizes(value, element));
-
-      settings
-        ..disabled = false
-        ..width = largestSize.width.ceil()
-        ..height = largestSize.height.ceil();
+      _adaptiveStreamDimensions = VideoDimensions(
+        largestSize.width.ceil(),
+        largestSize.height.ceil(),
+      );
+      _adaptiveStreamVisible = true;
+    } else {
+      _adaptiveStreamDimensions = null;
+      _adaptiveStreamVisible = false;
     }
 
+    final settings = _buildTrackSettings();
+
     // Only send new settings to server if it changed
     if (settings != _lastSentTrackSettings) {
       _lastSentTrackSettings = settings;
@@ -182,7 +199,13 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
     }
   }
 
-  void _sendPendingTrackSettingsUpdateRequest(lk_rtc.UpdateTrackSettings settings) {
+  void _sendPendingTrackSettingsUpdateRequest(lk_rtc.UpdateTrackSettings _) {
+    // Re-build from the current state at fire time instead of replaying the
+    // snapshot captured when the debounce was scheduled. Otherwise a stale
+    // snapshot could be sent after newer state (e.g. a manual setVideoQuality)
+    // has already been applied, clobbering it.
+    final settings = _buildTrackSettings();
+    _lastSentTrackSettings = settings;
     logger.fine('[Visibility] Sending... ${settings.toProto3Json()}');
     participant.room.engine.signalClient.sendUpdateTrackSettings(settings);
   }
@@ -198,8 +221,17 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
       _cancelPendingTrackSettingsUpdateRequest?.call();
       _visibilityTimer?.cancel();
 
+      // The track changed, so any adaptive-stream visibility computed for the
+      // previous track is stale. Reset to the construction defaults so it can't
+      // leak into a later _buildTrackSettings (e.g. via enable() / disable(),
+      // which emit regardless of visibility). Repopulated by the visibility
+      // observer below while adaptive stream is active.
+      _adaptiveStreamDimensions = null;
+      _adaptiveStreamVisible = true;
+
       final roomOptions = participant.room.roomOptions;
       if (roomOptions.adaptiveStream && newValue is RemoteVideoTrack) {
+        _adaptiveStreamActive = true;
         // Start monitoring visibility
         _visibilityTimer = Timer.periodic(
           const Duration(milliseconds: 300),
@@ -214,6 +246,10 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
             _computeVideoViewVisibility(quick: true);
           }
         };
+
+        _computeVideoViewVisibility(quick: true);
+      } else {
+        _adaptiveStreamActive = false;
       }
 
       if (newValue != null) {
@@ -229,7 +265,7 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
     return didUpdate;
   }
 
-  bool _canUpdateManualVideoSettings() {
+  bool _isManualOperationAllowed() {
     if (kind != TrackType.VIDEO) {
       logger.warning('Manual video setting updates are only supported for video tracks');
       return false;
@@ -240,55 +276,59 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
       return false;
     }
 
-    if (participant.room.roomOptions.adaptiveStream) {
-      logger.warning('Manual video setting update ignored because adaptive stream is enabled');
-      return false;
-    }
-
     return true;
   }
 
+  /// For tracks that support simulcasting, adjust subscribed quality.
+  ///
+  /// This indicates the highest quality the client can accept. If network
+  /// bandwidth does not allow, the server will automatically reduce quality to
+  /// optimize for uninterrupted video.
+  ///
+  /// When adaptive stream is active, this preference is merged client-side with
+  /// the dimensions computed from the visible views, and the smaller (more
+  /// conservative) of the two is sent to the server.
   Future<void> setVideoQuality(VideoQuality newValue) async {
-    if (newValue == _videoQuality) return;
-    if (!_canUpdateManualVideoSettings()) return;
-    _videoQuality = newValue;
-    _videoDimensions = null;
-    sendUpdateTrackSettings();
+    if (newValue == _userPreference?.quality) return;
+    if (!_isManualOperationAllowed()) return;
+    _userPreference = VideoSettings.quality(newValue);
+    _emitTrackUpdate();
   }
 
   /// Set preferred video dimensions for this track.
   ///
   /// Server will choose the appropriate layer based on these dimensions.
   /// Will override previous calls to [setVideoQuality].
+  ///
+  /// When adaptive stream is active, this preference is merged client-side with
+  /// the dimensions computed from the visible views, and the smaller (more
+  /// conservative) of the two is sent to the server.
   Future<void> setVideoDimensions(VideoDimensions newValue) async {
-    if (newValue.width == _videoDimensions?.width && newValue.height == _videoDimensions?.height) {
-      return;
-    }
-    if (!_canUpdateManualVideoSettings()) return;
-    _videoDimensions = newValue;
-    _videoQuality = null;
-    sendUpdateTrackSettings();
+    if (newValue == _userPreference?.dimensions) return;
+    if (!_isManualOperationAllowed()) return;
+    _userPreference = VideoSettings.dimensions(newValue);
+    _emitTrackUpdate();
   }
 
   /// Set desired FPS, server will do its best to return FPS close to this.
   /// It's only supported for video codecs that support SVC currently.
   Future<void> setVideoFPS(int newValue) async {
     if (newValue == _fps) return;
-    if (!_canUpdateManualVideoSettings()) return;
+    if (!_isManualOperationAllowed()) return;
     _fps = newValue;
-    sendUpdateTrackSettings();
+    _emitTrackUpdate();
   }
 
   Future<void> enable() async {
-    if (_enabled) return;
-    _enabled = true;
-    sendUpdateTrackSettings();
+    if (_enabledPreference == TrackEnabledPreference.enabled) return;
+    _enabledPreference = TrackEnabledPreference.enabled;
+    _emitTrackUpdate();
   }
 
   Future<void> disable() async {
-    if (!_enabled) return;
-    _enabled = false;
-    sendUpdateTrackSettings();
+    if (_enabledPreference == TrackEnabledPreference.disabled) return;
+    _enabledPreference = TrackEnabledPreference.disabled;
+    _emitTrackUpdate();
   }
 
   Future<void> subscribe() async {
@@ -333,26 +373,49 @@ class RemoteTrackPublication<T extends RemoteTrack> extends TrackPublication<T>
     participant.room.engine.signalClient.sendUpdateSubscription(subscription);
   }
 
-  @internal
-  void sendUpdateTrackSettings() {
-    final settings = lk_rtc.UpdateTrackSettings(
-      trackSids: [sid],
-      disabled: !_enabled,
+  lk_rtc.UpdateTrackSettings _buildTrackSettings() {
+    final isDisabled = resolveDisabled(
+      enabledPreference: _enabledPreference,
+      adaptiveStreamActive: _adaptiveStreamActive,
+      adaptiveStreamVisible: _adaptiveStreamVisible,
     );
-    if (kind == TrackType.VIDEO) {
-      if (_videoDimensions != null) {
-        settings.width = _videoDimensions!.width;
-        settings.height = _videoDimensions!.height;
-      } else if (_videoQuality != null) {
-        settings.quality = _videoQuality!.toPBType();
-      } else {
-        settings.quality = VideoQuality.HIGH.toPBType();
-      }
-      if (_fps != null) settings.fps = _fps!;
+
+    if (kind != TrackType.VIDEO) {
+      return buildUpdateTrackSettings(sid: sid, disabled: isDisabled);
     }
+
+    final resolved = resolveVideoSettings(
+      adaptiveStreamDimensions: _adaptiveStreamDimensions,
+      userPreference: _userPreference,
+      layerDimensionsForQuality: (quality) {
+        final pbQuality = quality.toPBType();
+        final layer = latestInfo?.layers.where((l) => l.quality == pbQuality).firstOrNull;
+        if (layer == null) return null;
+        return VideoDimensions(layer.width, layer.height);
+      },
+    );
+
+    return buildUpdateTrackSettings(
+      sid: sid,
+      disabled: isDisabled,
+      dimensions: resolved.dimensions,
+      quality: resolved.quality?.toPBType(),
+      fps: _fps,
+    );
+  }
+
+  void _emitTrackUpdate() {
+    // Cancel any pending debounced visibility update so its (now potentially
+    // stale) snapshot cannot fire after — and clobber — this immediate update.
+    _cancelPendingTrackSettingsUpdateRequest?.call();
+    final settings = _buildTrackSettings();
+    _lastSentTrackSettings = settings;
     participant.room.engine.signalClient.sendUpdateTrackSettings(settings);
   }
 
+  @internal
+  void sendUpdateTrackSettings() => _emitTrackUpdate();
+
   @internal
   // Update internal var and return true if changed
   Future<bool> updateSubscriptionAllowed(bool allowed) async {