Breaking: Model the disconnect for hidden tabs explicitly (#72)

This has caused app-level issues because disconnected doesn't let the app understand that
a reconnect will automatically happen.

Author: microbit-matt-hillsdon

lib/device.ts

@@ -152,6 +152,12 @@ export enum ConnectionStatus {
    * a reconnection is attempted.
    */
   RECONNECTING = "RECONNECTING",
+  /**
+   * Paused due to tab visibility. The connection was temporarily suspended
+   * because the browser tab became hidden. Reconnection will be attempted
+   * automatically when the tab becomes visible again.
+   */
+  PAUSED = "PAUSED",
 }
 
 export interface ConnectOptions {

lib/usb-radio-bridge.ts

@@ -83,16 +83,25 @@ class MicrobitRadioBridgeConnectionImpl
     const currentStatus = this.status;
     if (e.status !== ConnectionStatus.CONNECTED) {
       this.setStatus(e.status);
-      if (this.serialSessionOpen) {
+      // Don't dispose the serial session when PAUSED - USB is temporarily
+      // unavailable due to tab visibility, but we'll reconnect when visible.
+      // Attempting dispose would fail anyway since USB is disconnected.
+      if (e.status === ConnectionStatus.PAUSED) {
+        // Clear timestamp so stale values don't trigger reconnection when resuming.
+        this.serialSession?.clearLastReceivedTimestamp();
+      } else if (this.serialSessionOpen) {
         // If the session is already closed we don't need to dispose.
         this.serialSession?.dispose();
       }
     } else {
       this.status = ConnectionStatus.DISCONNECTED;
-      if (
-        currentStatus === ConnectionStatus.DISCONNECTED &&
-        this.serialSessionOpen
-      ) {
+      // Reconnect the serial session if we were previously disconnected or paused.
+      // PAUSED means the USB connection was temporarily suspended due to tab
+      // visibility, and now the tab is visible again so we should reconnect.
+      const shouldReconnect =
+        currentStatus === ConnectionStatus.DISCONNECTED ||
+        currentStatus === ConnectionStatus.PAUSED;
+      if (shouldReconnect && this.serialSessionOpen) {
         this.serialSession?.connect();
       }
     }
@@ -412,6 +421,11 @@ class RadioBridgeSerialSession {
     // Check for connection lost
     if (this.connectionCheckIntervalId === undefined) {
       this.connectionCheckIntervalId = setInterval(async () => {
+        // Don't check connection while USB is paused/disconnected.
+        // The check will resume when USB reconnects.
+        if (this.delegate.status !== ConnectionStatus.CONNECTED) {
+          return;
+        }
         if (
           this.lastReceivedMessageTimestamp &&
           Date.now() - this.lastReceivedMessageTimestamp <= 1_000
@@ -457,6 +471,10 @@ class RadioBridgeSerialSession {
     this.lastReceivedMessageTimestamp = undefined;
   }
 
+  clearLastReceivedTimestamp() {
+    this.lastReceivedMessageTimestamp = undefined;
+  }
+
   private async handshake(): Promise<void> {
     // There is an issue where we cannot read data out from the micro:bit serial
     // buffer until the buffer has been filled.

lib/usb.ts

@@ -148,15 +148,10 @@ class MicrobitWebUSBConnectionImpl
 
   private flashing: boolean = false;
   private disconnectAfterFlash: boolean = false;
-  private visibilityReconnect: boolean = false;
   private visibilityChangeListener = () => {
     if (document.visibilityState === "visible") {
-      if (
-        this.visibilityReconnect &&
-        this.status !== ConnectionStatus.CONNECTED
-      ) {
+      if (this.status === ConnectionStatus.PAUSED) {
         this.disconnectAfterFlash = false;
-        this.visibilityReconnect = false;
         if (!this.flashing) {
           this.log("Reconnecting visible tab");
           this.connect();
@@ -165,10 +160,9 @@ class MicrobitWebUSBConnectionImpl
     } else {
       if (!this.unloading && this.status === ConnectionStatus.CONNECTED) {
         if (!this.flashing) {
-          this.log("Disconnecting hidden tab");
-          this.disconnect().then(() => {
-            this.visibilityReconnect = true;
-          });
+          this.log("Pausing connection for hidden tab");
+          // Transition to PAUSED not DISCONNECTED
+          this.disconnect(false, ConnectionStatus.PAUSED);
         } else {
           this.log("Scheduling disconnect of hidden tab for after flash");
           this.disconnectAfterFlash = true;
@@ -346,8 +340,7 @@ class MicrobitWebUSBConnectionImpl
       if (this.disconnectAfterFlash) {
         this.log("Disconnecting after flash due to tab visibility");
         this.disconnectAfterFlash = false;
-        await this.disconnect();
-        this.visibilityReconnect = true;
+        await this.disconnect(false, ConnectionStatus.PAUSED);
       } else {
         if (this.addedListeners.serialdata) {
           this.log("Reinstating serial after flash");
@@ -391,7 +384,10 @@ class MicrobitWebUSBConnectionImpl
     });
   }
 
-  async disconnect(quiet?: boolean): Promise<void> {
+  async disconnect(
+    quiet?: boolean,
+    finalStatus: ConnectionStatus = ConnectionStatus.DISCONNECTED,
+  ): Promise<void> {
     try {
       if (this.connection) {
         await this.stopSerialInternal();
@@ -407,7 +403,7 @@ class MicrobitWebUSBConnectionImpl
       }
     } finally {
       this.connection = undefined;
-      this.setStatus(ConnectionStatus.DISCONNECTED);
+      this.setStatus(finalStatus);
       if (!quiet) {
         this.logging.log("Disconnection complete");
         this.logging.event({
@@ -420,7 +416,6 @@ class MicrobitWebUSBConnectionImpl
 
   private setStatus(newStatus: ConnectionStatus) {
     this.status = newStatus;
-    this.visibilityReconnect = false;
     this.log("USB connection status " + newStatus);
     this.dispatchTypedEvent("status", new ConnectionStatusEvent(newStatus));
   }