feat: Debounce lifecycle, network, and setMode signals in flutter SDK (#292)

## Summary

Wires `StateDebounceManager` (from `launchdarkly_common_client`) into
the Flutter `ConnectionManager`. Lifecycle and network events feed the
debouncer rather than driving `_handleState()` directly; the debouncer's
stream emits a reconciled snapshot after the configurable window closes
(default 1s), at which point `_handleState()` runs once.

Implements CSFDV2 CONNMODE section 3.5 for the Flutter SDK.

### Notable behaviour

- `ConnectionManagerConfig` gains `debounceWindow` and
`initialApplicationState`.
- Foreground -> background flush remains synchronous (CONNMODE 3.3.1).
- Network availability propagation to the destination remains
synchronous; only the mode-resolution decision is debounced.
- `setMode(mode)` sets the override synchronously so subsequent
automatic transitions are suppressed immediately; applying the resolved
mode is debounced (CONNMODE 2.0.3 / 3.5.5).
- `FlutterStateDetector` exposes `initialApplicationState`, read
synchronously at construction time from
`SchedulerBinding.instance.lifecycleState`, so the SDK seeds the correct
lifecycle assumption when launched in background.
- `LDClient` wires the seed and substitutes `foreground` when the user
opts out of lifecycle handling
(`applicationEvents.backgrounding=false`).

## Blocked on

Depends on #291 (StateDebounceManager in common_client). After #291
merges and `launchdarkly_common_client` is released, the pin in
`packages/flutter_client_sdk/pubspec.yaml` will be bumped to that
version and this PR can be marked ready for review.

Split out of #281 to enable incremental merge / release per the
dependency-order workflow in RELEASING.md.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes when streaming/polling/offline modes apply during rapid
lifecycle and network churn; mis-seeded `initialApplicationState` could
mis-resolve mode on background launch, though behavior is heavily
tested.
> 
> **Overview**
> Wires **`StateDebounceManager`** from `launchdarkly_common_client`
into Flutter **`ConnectionManager`** so lifecycle, network, and
**`setMode`** signals coalesce before **`_handleState()`** runs (default
**1s** `debounceWindow`; **`Duration.zero`** keeps prior synchronous
behavior for tests).
> 
> **`ConnectionManagerConfig`** adds **`debounceWindow`** and
**`initialApplicationState`**. Foreground→background **flush** and
destination **network availability** updates stay synchronous; explicit
**`offline`** still bypasses debouncing. **`setMode`** records the
override immediately but debounces applying the resolved mode.
> 
> **`FlutterStateDetector`** exposes **`initialApplicationState`** from
**`SchedulerBinding.instance.lifecycleState`**. **`LDClient`** reuses
one detector instance, seeds lifecycle when backgrounding is enabled,
and stops folding **`config.offline`** into the automatic
background/network disable flags (offline is applied via
**`_connectionManager.offline`** after construction). Bumps
**`launchdarkly_common_client`** to **1.13.0** and extends
**`connection_manager_test`** with **`fake_async`** debounce and
background-launch regression coverage.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
b51ade7. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: tanderson-ld

packages/flutter_client_sdk/lib/src/connection_manager.dart

@@ -101,12 +101,31 @@ final class ConnectionManagerConfig {
   /// retry logic.
   final bool disableAutomaticBackgroundHandling;
 
+  /// Window across which lifecycle, network, and user-mode-override signals
+  /// are debounced before automatic resolution runs. A value of
+  /// [Duration.zero] disables debouncing (signals apply synchronously).
+  /// Defaults to one second.
+  final Duration debounceWindow;
+
+  /// The application's lifecycle state at construction time. Used to seed
+  /// the manager's initial lifecycle assumption so the SDK doesn't default
+  /// to foreground when the host platform already knows the app launched
+  /// into the background. Callers that can query the platform synchronously
+  /// (e.g. via [SchedulerBinding.instance.lifecycleState]) should pass the
+  /// resolved value here; callers without that information should leave
+  /// the default.
+  ///
+  /// Defaults to [ApplicationState.foreground].
+  final ApplicationState initialApplicationState;
+
   ConnectionManagerConfig({
     this.initialConnectionMode = ConnectionMode.streaming,
     this.backgroundConnectionMode = const FDv2Offline(),
     this.runInBackground = true,
     this.disableAutomaticBackgroundHandling = false,
     this.disableAutomaticNetworkHandling = false,
+    this.debounceWindow = const Duration(seconds: 1),
+    this.initialApplicationState = ApplicationState.foreground,
   });
 }
 
@@ -127,6 +146,8 @@ final class ConnectionManager {
   final StateDetector _detector;
   final ConnectionDestination _destination;
   final List<ModeResolutionEntry> _resolutionTable;
+  late final StateDebounceManager _debouncer;
+  late final StreamSubscription<DebouncedState> _debounceSub;
 
   StreamSubscription<ApplicationState>? _applicationStateSub;
   StreamSubscription<NetworkState>? _networkStateSub;
@@ -140,6 +161,11 @@ final class ConnectionManager {
 
   bool _offline = false;
 
+  /// Whether the SDK has been explicitly placed in the offline state.
+  ///
+  /// Assigning this property synchronously drives the resolved mode to
+  /// offline (or back to automatic resolution when set to `false`). It
+  /// intentionally bypasses the debounce window.
   bool get offline => _offline;
 
   set offline(bool offline) {
@@ -157,31 +183,60 @@ final class ConnectionManager {
         _config = config,
         _destination = destination,
         _resolutionTable = resolutionTable ?? flutterDefaultResolutionTable(),
-        _applicationState = ApplicationState.foreground,
+        _applicationState = config.initialApplicationState,
+        // Network has no synchronous platform API; start optimistic. If
+        // the network is actually unavailable, the first detector emission
+        // will trigger a debounced reconcile that flips us to offline.
+        // The common case (network available) is the best performing default.
         _networkState = NetworkState.available,
         _detector = detector {
+    _debouncer = StateDebounceManager(
+      initialState: DebouncedState(
+        networkAvailable: true,
+        inForeground:
+            config.initialApplicationState == ApplicationState.foreground,
+        requestedMode: null,
+      ),
+      debounceWindow: config.debounceWindow,
+    );
+    _debounceSub = _debouncer.stream.listen(_onDebounceReconcile);
+
     if (!_config.disableAutomaticBackgroundHandling) {
       _applicationStateSub =
-          detector.applicationState.listen((applicationState) {
-        // TODO (SDK-2187): plumb in debouncer here
-
-        _applicationState = applicationState;
-        _handleState();
-      });
+          detector.applicationState.listen(_onApplicationStateChanged);
     }
 
     if (!_config.disableAutomaticNetworkHandling) {
-      _networkStateSub = detector.networkState.listen((networkState) {
-        // TODO (SDK-2187): plumb in debouncer here
-
-        _networkState = networkState;
-        _destination
-            .setNetworkAvailability(networkState == NetworkState.available);
-        _handleState();
-      });
+      _networkStateSub = detector.networkState.listen(_onNetworkStateChanged);
     }
   }
 
+  void _onApplicationStateChanged(ApplicationState newState) {
+    // Flushing on transition to background must not be debounced
+    if (newState == ApplicationState.background &&
+        _applicationState == ApplicationState.foreground &&
+        !_offline) {
+      _destination.flush();
+    }
+    _applicationState = newState;
+    _debouncer.setInForeground(newState == ApplicationState.foreground);
+  }
+
+  void _onNetworkStateChanged(NetworkState newState) {
+    _networkState = newState;
+    // Network-availability propagation to the destination is not debounced.
+    // It informs the underlying client's analytics-sending state, separate
+    // from the mode-resolution decision that the debouncer governs.
+    _destination.setNetworkAvailability(newState == NetworkState.available);
+    _debouncer.setNetworkAvailable(newState == NetworkState.available);
+  }
+
+  void _onDebounceReconcile(DebouncedState _) {
+    // The debouncer's snapshot is intentionally ignored; this manager owns
+    // the canonical view of lifecycle, network, override, and offline state.
+    _handleState();
+  }
+
   void _handleState() {
     _logger.debug('Handling state: $_applicationState:$_networkState');
 
@@ -228,14 +283,18 @@ final class ConnectionManager {
   void dispose() {
     _applicationStateSub?.cancel();
     _networkStateSub?.cancel();
+    _debounceSub.cancel();
+    _debouncer.close();
     _detector.dispose();
   }
 
-  /// Set the desired connection mode for the SDK. Passing null clears the
-  /// override and resumes automatic mode resolution.
+  /// Set the desired connection mode for the SDK. Setting an override takes
+  /// effect synchronously so subsequent automatic transitions are suppressed
+  /// immediately; applying the resolved mode is debounced. Passing null
+  /// clears the override and resumes automatic mode resolution.
   void setMode(FDv2ConnectionMode? mode) {
     _modeOverride = mode;
-    _handleState();
+    _debouncer.setRequestedMode(mode);
   }
 }
 

packages/flutter_client_sdk/lib/src/flutter_state_detector.dart

@@ -22,10 +22,22 @@ final class FlutterStateDetector implements StateDetector {
   @override
   Stream<NetworkState> get networkState => _networkStateController.stream;
 
+  /// The application lifecycle state read synchronously at construction
+  /// time. Suitable for seeding [ConnectionManagerConfig.initialApplicationState].
+  ///
+  /// [SchedulerBinding.instance.lifecycleState] returns a cached value
+  /// populated by the framework when the OS pushes lifecycle messages.
+  /// The read is synchronous and depends only on
+  /// [WidgetsFlutterBinding.ensureInitialized] having been called -- which
+  /// the SDK already requires for [FlutterStateDetector] to function.
+  final ApplicationState initialApplicationState;
+
   late final LDAppLifecycleListener _lifecycleListener;
   late final StreamSubscription<dynamic> _connectivitySubscription;
 
-  FlutterStateDetector() {
+  FlutterStateDetector()
+      : initialApplicationState =
+            _resolveLifecycleState(SchedulerBinding.instance.lifecycleState) {
     final initialState = SchedulerBinding.instance.lifecycleState;
     if (initialState != null) {
       _handleApplicationLifecycle(initialState);
@@ -41,6 +53,18 @@ final class FlutterStateDetector implements StateDetector {
         Connectivity().onConnectivityChanged.listen(_setConnectivity);
   }
 
+  static ApplicationState _resolveLifecycleState(AppLifecycleState? state) =>
+      switch (state) {
+        AppLifecycleState.resumed => ApplicationState.foreground,
+        AppLifecycleState.hidden ||
+        AppLifecycleState.paused =>
+          ApplicationState.background,
+        AppLifecycleState.detached ||
+        AppLifecycleState.inactive ||
+        null =>
+          ApplicationState.foreground,
+      };
+
   void _setConnectivity(dynamic connectivityResult) {
     // TODO: This is a temporary fix to handle the breaking change in
     // connectivity_plus v6

packages/flutter_client_sdk/lib/src/ld_client.dart

@@ -77,6 +77,7 @@ interface class LDClient {
     _client = LDCommonClient(config, platformImplementation, context,
         DiagnosticSdkData(name: sdkName, version: sdkVersion),
         hooks: combined);
+    final stateDetector = FlutterStateDetector();
     _connectionManager = ConnectionManager(
         logger: _client.logger,
         config: ConnectionManagerConfig(
@@ -85,13 +86,16 @@ interface class LDClient {
             backgroundConnectionMode:
                 FlutterDefaultConfig.defaultBackgroundConnectionMode,
             disableAutomaticBackgroundHandling:
-                config.offline || !config.applicationEvents.backgrounding,
+                !config.applicationEvents.backgrounding,
             disableAutomaticNetworkHandling:
-                config.offline || !config.applicationEvents.networkAvailability,
+                !config.applicationEvents.networkAvailability,
             runInBackground:
-                FlutterDefaultConfig.connectionManagerConfig.runInBackground),
+                FlutterDefaultConfig.connectionManagerConfig.runInBackground,
+            initialApplicationState: !config.applicationEvents.backgrounding
+                ? ApplicationState.foreground
+                : stateDetector.initialApplicationState),
         destination: DartClientAdapter(_client),
-        detector: FlutterStateDetector());
+        detector: stateDetector);
 
     if (config.offline) {
       _connectionManager.offline = true;

packages/flutter_client_sdk/pubspec.yaml

@@ -13,7 +13,7 @@ dependencies:
     sdk: flutter
   package_info_plus: ">=4.2.0 <11.0.0"
   device_info_plus: ">=9.1.1 <14.0.0"
-  launchdarkly_common_client: 1.12.0
+  launchdarkly_common_client: 1.13.0
   shared_preferences: ^2.2.2
   connectivity_plus: ">=5.0.2 <8.0.0"
   web: ^1.1.1
@@ -24,6 +24,7 @@ dev_dependencies:
   test: ^1.24.3
   lints: ^3.0.0
   mocktail: ^1.0.1
+  fake_async: ^1.3.1
 
 # The following section is specific to Flutter.
 flutter: