Emit a single disconnected event when connecting fails (#1126)

## Summary

Follow-up to #1065. Ensures the SDK emits exactly one
`RoomDisconnectedEvent` per failed connection attempt.

Previously a failed initial connect produced two
`EngineDisconnectedEvent`s, and therefore two `RoomDisconnectedEvent`s
and two room cleanups:

1. The signal client emits
`SignalDisconnectedEvent(signalingConnectionFailure)` while `connect()`
is failing (the validate path has done this since #406, and the
certificate pinning path in #1065 follows the same pattern), which the
engine relayed as `EngineDisconnectedEvent`.
2. `Engine.connect`'s catch then emits
`EngineDisconnectedEvent(joinFailure)` for the same failure.

## Changes

- `Engine.connect`'s catch is now the single emitter for initial connect
failures. It picks the reason by error type:
`signalingConnectionFailure` for `CertificatePinningException`,
`joinFailure` otherwise.
- The `signalingConnectionFailure` relay in the engine's signal listener
is removed (with a comment explaining why). During reconnects the
engine's reconnect handling already owns disconnect emission, so the
relay only ever produced duplicates. This also removes the
`_isReconnecting`/`_attemptingReconnect` guard that #1065 added to
suppress the relay during reconnects, since there is no longer anything
to suppress.
- `SignalDisconnectedEvent` at the signal level is unchanged, only the
engine-level relay is removed.

## Behavior change

Apps listening for `RoomDisconnectedEvent` now receive one event per
failed connect instead of two. The reasons are unchanged for the common
case (`joinFailure`); certificate pinning failures surface as
`signalingConnectionFailure`. Apps that specifically depended on
receiving both events for a single failure would see one.

## Testing

Added room-level tests through the mock e2e container asserting exactly
one `RoomDisconnectedEvent` per failed initial connect, for both a
certificate pinning failure (`signalingConnectionFailure`) and a generic
websocket failure (`joinFailure`). Both tests fail against the previous
code (two events observed) and pass with this change.

Author: hiroshihorie

.changes/single-disconnect-event

@@ -0,0 +1 @@
+patch type="fixed" "Emit a single disconnected event when connecting fails"

lib/src/core/engine.dart

@@ -268,9 +268,16 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
     } catch (error) {
       logger.fine('Connect Error $error');
 
-      events.emit(EngineDisconnectedEvent(
-        reason: DisconnectReason.joinFailure,
-      ));
+      // during a reconnect this connect() runs inside restartConnection and
+      // attemptReconnect owns disconnect emission, emitting here as well
+      // would produce two events for one failure
+      if (!_isReconnecting && !_attemptingReconnect) {
+        events.emit(EngineDisconnectedEvent(
+          reason: error is CertificatePinningException
+              ? DisconnectReason.signalingConnectionFailure
+              : DisconnectReason.joinFailure,
+        ));
+      }
       rethrow;
     }
   }
@@ -1367,18 +1374,12 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
       if (event.reason == DisconnectReason.disconnected && !_isClosed) {
         await handleReconnect(ClientDisconnectReason.signal,
             reconnectReason: lk_models.ReconnectReason.RR_SIGNAL_DISCONNECTED);
-      } else if (event.reason == DisconnectReason.signalingConnectionFailure) {
-        // while reconnecting, attemptReconnect owns disconnect handling and
-        // emits EngineDisconnectedEvent itself, relaying here as well would
-        // race it with a duplicate event. _attemptingReconnect covers the
-        // window where cleanUp() has already reset _isReconnecting but
-        // attemptReconnect has not finished its error handling yet
-        if (!_isReconnecting && !_attemptingReconnect) {
-          events.emit(EngineDisconnectedEvent(
-            reason: event.reason,
-          ));
-        }
       }
+      // signalingConnectionFailure is intentionally not relayed as
+      // EngineDisconnectedEvent here. The signal client emits it while the
+      // connect() call is failing, so connect()'s own catch (initial connect)
+      // or attemptReconnect (reconnect) already emits the engine event, and
+      // relaying here produced a duplicate disconnect per failure.
     })
     ..on<SignalOfferEvent>((event) async {
       if (subscriber == null) {

test/core/disconnect_event_test.dart

@@ -0,0 +1,114 @@
+// Copyright 2026 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+@Timeout(Duration(seconds: 5))
+library;
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:livekit_client/livekit_client.dart';
+import 'package:livekit_client/src/internal/events.dart';
+import 'package:livekit_client/src/support/websocket.dart';
+import 'package:livekit_client/src/types/internal.dart';
+import '../mock/e2e_container.dart';
+
+const exampleUri = 'ws://www.example.com';
+const token = 'token';
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  late E2EContainer container;
+
+  setUp(() {
+    container = E2EContainer();
+  });
+
+  tearDown(() async {
+    await container.dispose();
+  });
+
+  test('emits exactly one disconnected event when pinning fails on initial connect', () async {
+    container.wsConnector.connectError =
+        CertificatePinningException('Certificate pin mismatch', host: 'www.example.com');
+
+    final disconnectedEvents = <RoomDisconnectedEvent>[];
+    container.room.events.listen((event) {
+      if (event is RoomDisconnectedEvent) {
+        disconnectedEvents.add(event);
+      }
+    });
+
+    await expectLater(
+      container.room.connect(exampleUri, token),
+      throwsA(isA<CertificatePinningException>()),
+    );
+
+    // allow all pending event deliveries to complete
+    await Future<void>.delayed(const Duration(milliseconds: 100));
+
+    expect(disconnectedEvents, hasLength(1));
+    expect(disconnectedEvents.single.reason, DisconnectReason.signalingConnectionFailure);
+  });
+
+  test('emits exactly one disconnected event when initial connect fails', () async {
+    container.wsConnector.connectError = WebSocketException('Failed to connect');
+
+    final disconnectedEvents = <RoomDisconnectedEvent>[];
+    container.room.events.listen((event) {
+      if (event is RoomDisconnectedEvent) {
+        disconnectedEvents.add(event);
+      }
+    });
+
+    await expectLater(
+      container.room.connect(exampleUri, token),
+      throwsA(isA<Exception>()),
+    );
+
+    await Future<void>.delayed(const Duration(milliseconds: 100));
+
+    expect(disconnectedEvents, hasLength(1));
+    expect(disconnectedEvents.single.reason, DisconnectReason.joinFailure);
+  });
+
+  test('emits exactly one disconnected event when pinning fails during a full reconnect', () async {
+    await container.connectRoom();
+
+    final engineDisconnectedEvents = <EngineDisconnectedEvent>[];
+    container.engine.events.listen((event) {
+      if (event is EngineDisconnectedEvent) {
+        engineDisconnectedEvents.add(event);
+      }
+    });
+    final roomDisconnectedEvents = <RoomDisconnectedEvent>[];
+    container.room.events.listen((event) {
+      if (event is RoomDisconnectedEvent) {
+        roomDisconnectedEvents.add(event);
+      }
+    });
+
+    container.wsConnector.connectError =
+        CertificatePinningException('Certificate pin mismatch', host: 'www.example.com');
+    container.engine.fullReconnectOnNext = true;
+    await container.engine.attemptReconnect(ClientDisconnectReason.reconnectRetry);
+
+    await Future<void>.delayed(const Duration(milliseconds: 100));
+
+    expect(engineDisconnectedEvents, hasLength(1));
+    expect(engineDisconnectedEvents.single.reason, DisconnectReason.signalingConnectionFailure);
+    expect(roomDisconnectedEvents, hasLength(1));
+    expect(roomDisconnectedEvents.single.reason, DisconnectReason.signalingConnectionFailure);
+  });
+}