feat: Add StateDebounceManager to common_client (#291)

## Summary

Adds `StateDebounceManager` to `launchdarkly_common_client` per CSFDV2
CONNMODE section 3.5. Coalesces network availability, application
lifecycle, and user-requested mode signals into a debounced reconciled
snapshot delivered via a single-subscription `Stream<DebouncedState>`.
Per spec, `identify` calls do not participate.

The initial state is buffered on the stream during construction and
delivered asynchronously to the first subscriber, mirroring the
state-detector pattern. Subsequent reconciles fire after the
configurable debounce window closes. `Duration.zero` bypasses the timer.

## Scope

This PR ships only the debouncer primitive and its public exports from
`common_client`. The Flutter SDK consumer wiring lands in a follow-up PR
(#TBD) once this PR merges and `launchdarkly_common_client` is released.
Split out of #281 to enable incremental merge / release.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> New isolated library code with broad unit tests; no production
integration in this PR.
> 
> **Overview**
> Introduces **`StateDebounceManager`** in `launchdarkly_common_client`
as a standalone FDv2 connection-mode debouncing primitive (CONNMODE
§3.5). It coalesces **network availability**, **foreground lifecycle**,
and **user-requested `FDv2ConnectionMode`** into a `DebouncedState`
snapshot on a single-subscription stream; `identify` is explicitly out
of scope.
> 
> **`DebouncedState`** holds the three axes; setters no-op on unchanged
values and reset a configurable debounce timer (or emit immediately when
`debounceWindow` is `Duration.zero`). The initial state is buffered at
construction and delivered asynchronously to the first subscriber;
**`close()`** cancels pending timers and ignores further updates.
> 
> Public API is exported from `launchdarkly_common_client.dart`.
**`fake_async`** is added for tests covering timer coalescing, teardown,
and zero-window behavior. SDK wiring is deferred to a follow-up PR.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
bff223d. 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/common_client/lib/launchdarkly_common_client.dart

@@ -75,6 +75,8 @@ export 'src/data_sources/fdv2/mode_resolution.dart'
         ModeResolutionEntry,
         resolveMode,
         flutterDefaultResolutionTable;
+export 'src/data_sources/fdv2/state_debounce_manager.dart'
+    show DebouncedState, DebounceTimerFactory, StateDebounceManager;
 export 'src/data_sources/data_source_status.dart'
     show DataSourceStatusErrorInfo, DataSourceStatus, DataSourceState;
 

packages/common_client/lib/src/data_sources/fdv2/state_debounce_manager.dart

@@ -0,0 +1,140 @@
+import 'dart:async';
+
+import '../../fdv2_connection_mode.dart';
+
+/// Snapshot of the desired state accumulated within a debounce window.
+///
+/// Each field is one of the axes that participate in debouncing per the
+/// FDv2 connection-mode resolution spec: network availability, application
+/// lifecycle, and the user-requested mode (when set via the public
+/// `setMode` API). `identify` calls intentionally do not participate.
+final class DebouncedState {
+  final bool networkAvailable;
+  final bool inForeground;
+  final FDv2ConnectionMode? requestedMode;
+
+  static const _unset = Object();
+
+  const DebouncedState({
+    required this.networkAvailable,
+    required this.inForeground,
+    required this.requestedMode,
+  });
+
+  DebouncedState _copyWith({
+    bool? networkAvailable,
+    bool? inForeground,
+    Object? requestedMode = _unset,
+  }) {
+    return DebouncedState(
+      networkAvailable: networkAvailable ?? this.networkAvailable,
+      inForeground: inForeground ?? this.inForeground,
+      requestedMode: identical(requestedMode, _unset)
+          ? this.requestedMode
+          : requestedMode as FDv2ConnectionMode?,
+    );
+  }
+}
+
+/// Factory that produces a one-shot timer used to schedule the debounce
+/// fire. Exists primarily so tests can substitute a controllable
+/// implementation (e.g. via `fake_async`).
+typedef DebounceTimerFactory = Timer Function(
+    Duration duration, void Function() callback);
+
+Timer _defaultTimerFactory(Duration d, void Function() cb) => Timer(d, cb);
+
+/// Debounces network availability, lifecycle, and user-requested mode
+/// signals into a reconciled snapshot delivered through [stream].
+///
+/// The initial state is added to [stream] during construction and is
+/// buffered until the first subscriber attaches.
+///
+/// Each `setX` call updates the relevant component of the pending state
+/// and resets the debounce timer. When the timer fires, the accumulated
+/// state is pushed onto [stream]. Per-setter early-return suppresses
+/// unchanged values; the consumer is responsible for deciding whether
+/// the resolved state requires action.
+///
+/// A [debounceWindow] of [Duration.zero] bypasses the timer entirely:
+/// state changes are pushed onto [stream] from inside the setter
+/// that produced them.
+///
+/// [stream] is single-subscription. Subscribe exactly once and
+/// cancel the subscription as part of the same teardown that calls
+/// [close].
+final class StateDebounceManager {
+  final Duration _debounceWindow;
+  final DebounceTimerFactory _timerFactory;
+  final _controller = StreamController<DebouncedState>();
+
+  DebouncedState _pending;
+  Timer? _timer;
+  bool _closed = false;
+
+  StateDebounceManager({
+    required DebouncedState initialState,
+    required Duration debounceWindow,
+    DebounceTimerFactory? timerFactory,
+  })  : _pending = initialState,
+        _debounceWindow = debounceWindow,
+        _timerFactory = timerFactory ?? _defaultTimerFactory {
+    _controller.add(initialState);
+  }
+
+  /// Stream of debounced states. The initial state is buffered for the
+  /// first subscriber and delivered on a microtask after subscription;
+  /// subsequent reconciles fire after the debounce window closes.
+  Stream<DebouncedState> get stream => _controller.stream;
+
+  void setNetworkAvailable(bool available) {
+    if (_pending.networkAvailable == available) {
+      return;
+    }
+    _pending = _pending._copyWith(networkAvailable: available);
+    _scheduleOrFire();
+  }
+
+  void setInForeground(bool inForeground) {
+    if (_pending.inForeground == inForeground) {
+      return;
+    }
+    _pending = _pending._copyWith(inForeground: inForeground);
+    _scheduleOrFire();
+  }
+
+  void setRequestedMode(FDv2ConnectionMode? mode) {
+    if (_pending.requestedMode == mode) {
+      return;
+    }
+    _pending = _pending._copyWith(requestedMode: mode);
+    _scheduleOrFire();
+  }
+
+  void close() {
+    _closed = true;
+    _timer?.cancel();
+    _timer = null;
+    _controller.close();
+  }
+
+  void _scheduleOrFire() {
+    if (_closed) {
+      return;
+    }
+    if (_debounceWindow == Duration.zero) {
+      _controller.add(_pending);
+      return;
+    }
+    _timer?.cancel();
+    _timer = _timerFactory(_debounceWindow, _onTimer);
+  }
+
+  void _onTimer() {
+    _timer = null;
+    if (_closed) {
+      return;
+    }
+    _controller.add(_pending);
+  }
+}

packages/common_client/pubspec.yaml

@@ -18,3 +18,4 @@ dev_dependencies:
   test: ^1.24.3
   lints: ^3.0.0
   mocktail: ^1.0.1
+  fake_async: ^1.3.1