Merge pull request #74 from MrAlders0n/copilot/include-debug-logging-guidelines

Fix connection status message timing and preserve error states during disconnect

Author: MrAlders0n

STATUS_MESSAGES.md

@@ -25,55 +25,57 @@ Status messages follow these consistent conventions:
 - **Message**: `"Connecting"`
 - **Color**: Sky blue (info)
 - **Used in**: `connect()`
-- **Source**: `content/wardrive.js:1916`
-- **Context**: When user clicks Connect button
-- **Minimum Visibility**: Natural async timing during BLE pairing (typically 2-5 seconds)
+- **Source**: `content/wardrive.js:2005`
+- **Context**: When user clicks Connect button; remains visible during entire connection process (BLE pairing, channel setup, and capacity check)
+- **Minimum Visibility**: Natural async timing during full connection process (typically 3-8 seconds including capacity check)
 
 #### Connected
 - **Message**: `"Connected"`
 - **Color**: Green (success)
 - **Used in**: `connect()`
-- **Source**: `content/wardrive.js:1926`
-- **Context**: After BLE device successfully pairs
-- **Minimum Visibility**: 500ms minimum enforced
+- **Source**: `content/wardrive.js:2060`
+- **Context**: After full connection process completes successfully (BLE paired, channel setup, and capacity check passed)
+- **Minimum Visibility**: Persists until user interacts with app buttons (send ping, start auto mode)
+- **Note**: This message now only appears after the complete connection handshake, not just after BLE pairing
 
 #### Disconnecting
 - **Message**: `"Disconnecting"`
 - **Color**: Sky blue (info)
 - **Used in**: `disconnect()`
-- **Source**: `content/wardrive.js:1988`
-- **Context**: When user clicks Disconnect button
+- **Source**: `content/wardrive.js:2118`
+- **Context**: When user clicks Disconnect button or when automatic disconnect is triggered
 - **Minimum Visibility**: 500ms minimum enforced
 
 #### Disconnected
 - **Message**: `"Disconnected"`
 - **Color**: Red (error)
 - **Used in**: `connect()`, `disconnect()`, event handlers
-- **Source**: `content/wardrive.js:1950`, `content/wardrive.js:2046`
-- **Context**: Initial state and when BLE device disconnects
+- **Source**: `content/wardrive.js:2073`, `content/wardrive.js:2177`
+- **Context**: Initial state and when BLE device disconnects normally (user-initiated or device-initiated)
 - **Minimum Visibility**: N/A (persists until connection is established)
+- **Note**: Only shown for normal disconnections; error disconnections (e.g., app down, capacity full) preserve their specific error message
 
 #### Connection failed
 - **Message**: `"Connection failed"` (or error message)
 - **Color**: Red (error)
 - **Used in**: `connect()`, event handlers
-- **Source**: `content/wardrive.js:1976`, `content/wardrive.js:2059`
+- **Source**: `content/wardrive.js:2096`, `content/wardrive.js:2190`
 - **Context**: BLE connection fails or connection button error
 - **Minimum Visibility**: N/A (error state persists)
 
 #### Channel setup failed
 - **Message**: `"Channel setup failed"` (or error message)
 - **Color**: Red (error)
 - **Used in**: `connect()`
-- **Source**: `content/wardrive.js:1944`
+- **Source**: `content/wardrive.js:2063`
 - **Context**: Channel creation or lookup fails during connection
 - **Minimum Visibility**: N/A (error state persists)
 
 #### Disconnect failed
 - **Message**: `"Disconnect failed"` (or error message)
 - **Color**: Red (error)
 - **Used in**: `disconnect()`
-- **Source**: `content/wardrive.js:2018`
+- **Source**: `content/wardrive.js:2149`
 - **Context**: Error during disconnect operation
 - **Minimum Visibility**: N/A (error state persists)
 
@@ -89,23 +91,23 @@ Status messages follow these consistent conventions:
 - **Context**: When connecting to device and checking if a wardriving slot is available
 - **Minimum Visibility**: 500ms minimum enforced (or until API response received)
 
-#### WarDriving app has reached capacity
-- **Message**: `"WarDriving app has reached capacity"`
+#### Disconnected: WarDriving app has reached capacity
+- **Message**: `"Disconnected: WarDriving app has reached capacity"`
 - **Color**: Red (error)
 - **Used in**: `checkCapacity()`, `postToMeshMapperAPI()`
-- **Source**: `content/wardrive.js:1061`, `content/wardrive.js:1116`
+- **Source**: `content/wardrive.js:1063`, `content/wardrive.js:1120`
 - **Context**: Capacity check API denies slot on connect (returns allowed=false), or wardriving API returns allowed=false during active session
-- **Minimum Visibility**: N/A (error state persists until disconnect)
-- **Notes**: Displayed when the API successfully responds but indicates capacity is full
+- **Minimum Visibility**: N/A (error state persists; message is preserved during automatic disconnect)
+- **Notes**: Displayed when the API successfully responds but indicates capacity is full. When this error occurs during connection, the automatic disconnect flow preserves this status message instead of showing "Disconnected". Message format standardized with "Disconnected: " prefix to clearly indicate disconnect state.
 
-#### WarDriving app is down
-- **Message**: `"WarDriving app is down"`
+#### Disconnected: WarDriving app is down
+- **Message**: `"Disconnected: WarDriving app is down"`
 - **Color**: Red (error)
 - **Used in**: `checkCapacity()`
-- **Source**: `content/wardrive.js:1050`, `content/wardrive.js:1072`
+- **Source**: `content/wardrive.js:1050`, `content/wardrive.js:1074`
 - **Context**: Capacity check API returns error status or network is unreachable during connect
-- **Minimum Visibility**: N/A (error state persists until disconnect)
-- **Notes**: Implements fail-closed policy - connection is denied if API fails or is unreachable
+- **Minimum Visibility**: N/A (error state persists; message is preserved during automatic disconnect)
+- **Notes**: Implements fail-closed policy - connection is denied if API fails or is unreachable. When this error occurs, the automatic disconnect flow preserves this status message instead of showing "Disconnected". Message format standardized with "Disconnected: " prefix to clearly indicate disconnect state.
 
 #### Unable to read device public key; try again
 - **Message**: `"Unable to read device public key; try again"`
@@ -277,10 +279,11 @@ These messages use a hybrid approach: **first display respects 500ms minimum**,
 #### Idle
 - **Message**: `"Idle"`
 - **Color**: Slate (idle)
-- **Used in**: `connect()`, `postApiAndRefreshMap()`
-- **Source**: `content/wardrive.js:2060`, `content/wardrive.js:1091`
-- **Context**: Initial connection complete after capacity check succeeds, or manual mode after API post completes
+- **Used in**: `postApiAndRefreshMap()`
+- **Source**: `content/wardrive.js:1091`
+- **Context**: Manual mode after API post completes
 - **Minimum Visibility**: 500ms minimum enforced
+- **Note**: No longer shown after initial connection; "Connected" status is displayed instead and persists until user action
 
 ---
 

content/wardrive.js

@@ -123,6 +123,7 @@ const state = {
   distanceUpdateTimer: null, // Timer for updating distance display
   capturedPingCoords: null, // { lat, lon, accuracy } captured at ping time, used for API post after 7s delay
   devicePublicKey: null, // Hex string of device's public key (used for capacity check)
+  disconnectReason: null, // Tracks the reason for disconnection (e.g., "app_down", "capacity_full", "error", "normal")
   repeaterTracking: {
     isListening: false,           // Whether we're currently listening for echoes
     sentTimestamp: null,          // Timestamp when the ping was sent
@@ -1047,7 +1048,8 @@ async function checkCapacity(reason) {
       // Fail closed on network errors for connect
       if (reason === "connect") {
         debugError("Failing closed (denying connection) due to API error");
-        setStatus("WarDriving app is down", STATUS_COLORS.error);
+        setStatus("Disconnected: WarDriving app is down", STATUS_COLORS.error);
+        state.disconnectReason = "app_down"; // Track disconnect reason
         return false;
       }
       return true; // Always allow disconnect to proceed
@@ -1058,7 +1060,8 @@ async function checkCapacity(reason) {
 
     // Handle capacity full vs. allowed cases separately
     if (data.allowed === false && reason === "connect") {
-      setStatus("WarDriving app has reached capacity", STATUS_COLORS.error);
+      setStatus("Disconnected: WarDriving app has reached capacity", STATUS_COLORS.error);
+      state.disconnectReason = "capacity_full"; // Track disconnect reason
     }
 
     return data.allowed === true;
@@ -1069,7 +1072,8 @@ async function checkCapacity(reason) {
     // Fail closed on network errors for connect
     if (reason === "connect") {
       debugError("Failing closed (denying connection) due to network error");
-      setStatus("WarDriving app is down", STATUS_COLORS.error);
+      setStatus("Disconnected: WarDriving app is down", STATUS_COLORS.error);
+      state.disconnectReason = "app_down"; // Track disconnect reason
       return false;
     }
 
@@ -1113,7 +1117,8 @@ async function postToMeshMapperAPI(lat, lon, heardRepeats) {
         const data = await response.json();
         if (data.allowed === false) {
           debugWarn("MeshMapper API returned allowed=false, disconnecting");
-          setStatus("WarDriving app has reached capacity", STATUS_COLORS.error);
+          setStatus("Disconnected: WarDriving app has reached capacity", STATUS_COLORS.error);
+          state.disconnectReason = "capacity_full"; // Track disconnect reason
           // Disconnect after a brief delay to ensure user sees the message
           setTimeout(() => {
             disconnect().catch(err => debugError(`Disconnect after capacity denial failed: ${err.message}`));
@@ -2012,7 +2017,8 @@ async function connect() {
 
     conn.on("connected", async () => {
       debugLog("BLE connected event fired");
-      setStatus("Connected", STATUS_COLORS.success);
+      // Keep "Connecting" status visible during the full connection process
+      // Don't show "Connected" until everything is complete
       setConnectButton(true);
       connectBtn.disabled = false;
       const selfInfo = await conn.getSelfInfo();
@@ -2022,6 +2028,7 @@ async function connect() {
       if (!selfInfo?.publicKey || selfInfo.publicKey.length !== 32) {
         debugError("Missing or invalid public key from device", selfInfo?.publicKey);
         setStatus("Unable to read device public key; try again", STATUS_COLORS.error);
+        state.disconnectReason = "error"; // Mark as error disconnect
         // Disconnect after a brief delay to ensure user sees the error message
         setTimeout(() => {
           disconnect().catch(err => debugError(`Disconnect after public key error failed: ${err.message}`));
@@ -2050,28 +2057,40 @@ async function connect() {
         if (!allowed) {
           debugWarn("Capacity check denied, disconnecting");
           // Status message already set by checkCapacity()
+          // disconnectReason already set by checkCapacity()
           // Disconnect after a brief delay to ensure user sees the message
           setTimeout(() => {
             disconnect().catch(err => debugError(`Disconnect after capacity denial failed: ${err.message}`));
           }, 1500);
         } else {
-          // Connection complete, set status to Idle
-          setStatus("Idle", STATUS_COLORS.idle);
+          // Connection complete, show Connected status
+          setStatus("Connected", STATUS_COLORS.success);
+          debugLog("Full connection process completed successfully");
         }
       } catch (e) {
         debugError(`Channel setup failed: ${e.message}`, e);
         setStatus(e.message || "Channel setup failed", STATUS_COLORS.error);
+        state.disconnectReason = "error"; // Mark as error disconnect
       }
     });
 
     conn.on("disconnected", () => {
       debugLog("BLE disconnected event fired");
-      setStatus("Disconnected", STATUS_COLORS.error);
+      
+      // Only set "Disconnected" status for normal disconnections
+      // Preserve error messages (app_down, capacity_full, error) instead of overwriting
+      if (state.disconnectReason === "normal" || state.disconnectReason === null || state.disconnectReason === undefined) {
+        setStatus("Disconnected", STATUS_COLORS.error);
+      } else {
+        debugLog(`Preserving disconnect status for reason: ${state.disconnectReason}`);
+      }
+      
       setConnectButton(false);
       deviceInfoEl.textContent = "—";
       state.connection = null;
       state.channel = null;
       state.devicePublicKey = null; // Clear public key
+      state.disconnectReason = null; // Reset disconnect reason
       stopAutoPing(true); // Ignore cooldown check on disconnect
       enableControls(false);
       updateAutoButton();
@@ -2105,6 +2124,12 @@ async function disconnect() {
   }
 
   connectBtn.disabled = true;
+  
+  // Set disconnectReason to "normal" if not already set (for user-initiated disconnects)
+  if (state.disconnectReason === null || state.disconnectReason === undefined) {
+    state.disconnectReason = "normal";
+  }
+  
   setStatus("Disconnecting", STATUS_COLORS.info);
 
   // Release capacity slot if we have a public key
@@ -2147,6 +2172,7 @@ async function disconnect() {
   } catch (e) {
     debugError(`BLE disconnect failed: ${e.message}`, e);
     setStatus(e.message || "Disconnect failed", STATUS_COLORS.error);
+    state.disconnectReason = "error"; // Mark as error disconnect
   } finally {
     connectBtn.disabled = false;
   }