Redesign WebSocket status bar: student-friendly by default, diagnostics in developer mode (#328)

Predixx · web-flow · commit c84890e536f1 · 2026-06-26T01:28:40.000+02:00
Gate the WebSocket status bar on artemis.developerMode (removes the artemis.showWebSocketStatusBar setting): plain-language label and help tooltip for students, technical label and full diagnostics for developers, live re-render on developerMode toggle, click resets and reconnects. Closes #320
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to the Artemis VS Code extension will be documented in this
 
 ## [Unreleased]
 
+### Changed
+
+- **WebSocket status bar:** Removed the `artemis.showWebSocketStatusBar` setting. The connection indicator now appears automatically only when there is a problem; enable `artemis.developerMode` to keep it always visible with full diagnostics on hover. When the connection drops, students now see a plain-language explanation (no "WS" jargon) instead of a technical label.
+
 ## [0.4.8] - 2026-06-24
 
 ### Changed
diff --git a/README.md b/README.md
@@ -103,8 +103,7 @@ Configure the extension through VS Code settings (`Cmd+,` or `Ctrl+,`):
 - `artemis.showSetDefaultClonePathPrompt` - Ask to set a default clone folder on first clone
 - `artemis.startPage` - Which page to show after logging in
 - `artemis.showStartPageSuggestion` - Suggest configuring the start page when an exercise is detected
-- `artemis.showWebSocketStatusBar` - Show the WebSocket connection status in the status bar
-- `artemis.developerMode` - Enable developer mode (debug tools and extra diagnostics)
+- `artemis.developerMode` - Enable developer mode (debug tools, extra diagnostics, and an always-visible WebSocket status indicator)
 
 ## About Artemis
 
diff --git a/docs/superpowers/specs/2026-06-24-ws-statusbar-button-design.md b/docs/superpowers/specs/2026-06-24-ws-statusbar-button-design.md
@@ -0,0 +1,145 @@
+# WebSocket Status Bar Button Redesign
+
+**Issue:** #320 — Re-evaluate: does the WebSocket status-bar item need the `artemis.showWebSocketStatusBar` setting?
+**Date:** 2026-06-24
+**Branch:** `worktree-ws-statusbar-dev-hover` (off `dev`)
+**Status:** Approved design, pending implementation plan
+
+## Context
+
+The WebSocket connection-status item in the status bar
+(`extension/src/extension/services/websocket/websocketStatusBar.ts`,
+`WebSocketStatusBarService`) is currently gated by a user setting
+`artemis.showWebSocketStatusBar` (boolean, default `false`).
+
+Today's behavior:
+- On disconnect / reconnecting → item is **always shown** (red/yellow), setting ignored.
+- During connected operation → shown **only** when `showWebSocketStatusBar` is `true`.
+- Logged out → hidden unless the setting is `true`.
+- After reconnection with the setting off → 2s flash, then hidden.
+- Tooltip: a plain one-line string. Click: reset + reconnect (no-op while connecting/reconnecting).
+
+A previous, richer version (commit `ec5f6d0d`, before a 588→165 line simplification)
+had a Markdown hover tooltip with full debug info and a QuickPick action menu. That
+was stripped out. This redesign brings back a focused, audience-aware version of the
+hover info and resolves #320.
+
+#320 asks whether the dedicated setting earns its place. The genuinely useful signal
+(a connection problem) already surfaces automatically, independent of the setting. The
+only thing the setting adds is a permanent "connected" indicator during normal
+operation — niche, defaults off, and arguably clutter for students.
+
+## Goals
+
+- Remove the `artemis.showWebSocketStatusBar` configuration knob (resolves #320 as "remove").
+- Fold "always show the item" into the existing `artemis.developerMode` setting, which
+  already governs status-bar diagnostics (e.g. the live struggle-detection score).
+- Give students a clear, plain-language explanation when the connection fails (the only
+  moment a non-developer sees the item).
+- Give developers full WebSocket diagnostics on hover.
+
+## Non-Goals
+
+- No change to the click action (stays reset + reconnect).
+- No QuickPick / action-menu (Disconnect / Reset / Copy debug) — low value for a niche
+  diagnostic, not worth the surface. Reconnect is the one in-context action and is the click.
+- No auth diagnostics (Cookie / JWT presence) in the dev hover — `getDiagnostics()` does
+  not expose them today and they are not needed now (YAGNI). Can be added later if a
+  real debugging need arises.
+
+## Design
+
+### 1. Visibility
+
+`developerMode` replaces `showWebSocketStatusBar` 1:1 in the visibility logic:
+
+- **developerMode ON** → item always visible (including the connected steady state, and
+  while logged out — diagnostics).
+- **developerMode OFF** → visible only on problems (`disconnected` / `reconnecting`),
+  plus the existing 2s flash after a successful reconnect; otherwise hidden. Logged out → hidden.
+
+The "always show on problems" override and the logged-out gate are unchanged in shape;
+only the gating field switches from `_showStatusBar` to a developer-mode flag.
+
+### 2. Button text (mode-dependent)
+
+| State | Normal (student) | Developer |
+|-------|------------------|-----------|
+| connected | `$(plug) Artemis: connected` | `$(plug) WS Connected` |
+| connecting | `$(sync~spin) Artemis: connecting…` | `$(sync~spin) WS Connecting…` |
+| reconnecting | `$(sync~spin) Artemis: reconnecting (3/20)…` | `$(sync~spin) WS Reconnecting (3/20)…` |
+| disconnected | `$(debug-disconnect) Artemis: offline` | `$(debug-disconnect) WS Disconnected` |
+
+Background colors unchanged: error (red) when disconnected, warning (yellow) when reconnecting.
+
+### 3. Hover (tooltip) — three tiers
+
+- **Normal + connected:** simple one-liner (e.g. "Connected to Artemis. Click to reconnect.").
+  Rarely seen, since the item is hidden when connected in normal mode.
+- **Normal + reconnecting:**
+  > **Reconnecting to Artemis… (3/20)**
+  > Live updates are paused and will resume automatically.
+- **Normal + disconnected:**
+  > **Connection to Artemis lost**
+  > Live updates (build results, submission status, Iris) are paused.
+  > Click to reconnect. If it keeps failing, check your internet connection or sign in again.
+- **Developer (all states):** rich `MarkdownString` built from
+  `ArtemisWebsocketService.getDiagnostics()`:
+  status, `clientConnected` / `clientActive`, reconnect `(attempts/max)`,
+  `subscriptionCount` + subscription topics, `sessionId`, `serverUrl`, `websocketUrl`.
+
+### 4. Click action
+
+Unchanged: `resetConnectionState()` + `connect()`, no-op while `connecting` / `reconnecting`.
+Same in both modes.
+
+### 5. Setting removal (#320)
+
+Remove `artemis.showWebSocketStatusBar` everywhere:
+- `extension/package.json` — `contributes.configuration` entry (~line 179).
+- `extension/src/extension/utils/constants.ts` — `SHOW_WEBSOCKET_STATUS_BAR_KEY` (line 37).
+- `README.md` — the bullet listing the setting (line 106).
+- `websocketStatusBar.ts` — `_showStatusBar`, `_updateVisibilitySetting`, and the
+  config-change listener; switch the listener to watch `DEVELOPER_MODE_KEY`.
+- `CHANGELOG.md` — new entry under `## [Unreleased]` (do not rename that heading).
+
+CHANGELOG history (lines mentioning the setting in past releases) is left untouched.
+
+## Affected Files
+
+| File | Change |
+|------|--------|
+| `extension/src/extension/services/websocket/websocketStatusBar.ts` | Swap setting→developerMode; mode-dependent text; three-tier tooltip incl. dev diagnostics |
+| `extension/src/extension/utils/constants.ts` | Remove `SHOW_WEBSOCKET_STATUS_BAR_KEY` |
+| `extension/package.json` | Remove `artemis.showWebSocketStatusBar` config contribution |
+| `README.md` | Remove the setting's documentation bullet |
+| `CHANGELOG.md` | Add `[Unreleased]` entry |
+| `extension/test/unit/services/websocketStatusBar.test.ts` | Re-point setting tests to `developerMode`; add new tests |
+
+No change required to `ArtemisWebsocketService` — `getDiagnostics()` already provides the
+data for the dev hover.
+
+## Testing
+
+`extension/test/unit/services/websocketStatusBar.test.ts` (mocha/vscode-test):
+
+- Re-point existing `showWebSocketStatusBar`-based visibility tests to `developerMode`.
+- Keep: always-shown-on-problem, 2s reconnect flash, auth-gate, dispose tests.
+- Add:
+  - developerMode ON → item visible while connected (and while logged out).
+  - Dev hover tooltip contains diagnostics (e.g. `serverUrl`, subscription count).
+  - Normal-mode button text uses plain-language labels ("Artemis: offline", etc.).
+  - Normal-mode disconnected/reconnecting tooltip contains the friendly explanation.
+
+All `extension/` checks must pass before completion: `npm test`, `npm run lint`,
+`npm run check-types` (tsc --noEmit catches unused locals that lint misses).
+
+## Open Decisions
+
+- **Auth diagnostics in dev hover:** OUT (YAGNI). Revisit only on a concrete need.
+
+## Out of Scope / Future
+
+- QuickPick action menu (Disconnect / Reset / Copy debug / Show debug doc).
+- Clickable command links inside the hover tooltip.
+- Exposing auth (Cookie/JWT) state via `getDiagnostics()`.
diff --git a/extension/package.json b/extension/package.json
@@ -2,7 +2,7 @@
   "name": "iris-thaumantias",
   "displayName": "Artemis - TUM",
   "description": "Artemis brings interactive learning to life with instant, individual feedback on programming exercises, quizzes, modeling tasks, and more. This VS Code extension integrates Iris, an LLM-based virtual assistant that supports students with instant answers about exercises, lectures, and learning performance. Iris provides context-aware, personalized assistance for programming exercises, encouraging independent problem-solving through subtle hints and guiding questions instead of giving full solutions.",
-  "version": "0.4.8",
+  "version": "0.4.9-dev",
   "publisher": "aet-tum",
   "license": "MIT",
   "icon": "media/artemis-blue.png",
@@ -174,12 +174,7 @@
         "artemis.developerMode": {
           "type": "boolean",
           "default": false,
-          "markdownDescription": "Enable developer mode to show debugging tools, including debug buttons in views and live struggle detection score in the status bar."
-        },
-        "artemis.showWebSocketStatusBar": {
-          "type": "boolean",
-          "default": false,
-          "description": "Show the WebSocket connection status in the status bar during normal operation. When a connection failure occurs, the status bar item is always shown regardless of this setting."
+          "markdownDescription": "Enable developer mode to show debugging tools, including debug buttons in views, the live struggle detection score, and the WebSocket connection status (with diagnostics on hover) in the status bar."
         },
         "artemis.defaultCommitMessage": {
           "type": "string",
diff --git a/extension/src/extension/services/websocket/websocketStatusBar.ts b/extension/src/extension/services/websocket/websocketStatusBar.ts
@@ -11,26 +11,23 @@ import { ArtemisWebsocketService } from './artemisWebsocketService';
  * StatusBar item showing WebSocket connection status.
  *
  * Visibility rules:
- * - When logged out: hidden unless `artemis.showWebSocketStatusBar` is true
- *   (no WebSocket exists, so the default "needs attention on disconnect" rule
- *   would surface a misleading red error indicator)
- * - When logged in:
- *   - ALWAYS shown when disconnected or reconnecting
- *   - Otherwise shown only when `artemis.showWebSocketStatusBar` is true
- *   - After reconnection with setting off: 2s flash then hidden
+ * - developerMode ON: always shown (any state, including connected and while
+ *   logged out) — diagnostics.
+ * - developerMode OFF:
+ *   - shown when disconnected or reconnecting (a problem the user can act on)
+ *   - 2s flash after a successful reconnect, then hidden
+ *   - otherwise hidden (incl. logged out)
  *
- * Auth state is supplied externally via {@link setAuthenticated}; the service
- * does not own auth lifecycle.
- *
- * Click action: always reconnect (reset + connect). No-op while connecting.
+ * Auth state is supplied externally via {@link setAuthenticated}.
+ * Click action: reset + reconnect. No-op while connecting/reconnecting.
  */
 export class WebSocketStatusBarService implements vscode.Disposable {
     private readonly _statusBarItem: vscode.StatusBarItem;
     private readonly _websocketService: ArtemisWebsocketService;
     private readonly _disposables: vscode.Disposable[] = [];
     private _stateSubscription?: vscode.Disposable;
     private _currentStatus: WebSocketDisplayStatus = 'disconnected';
-    private _showStatusBar = false;
+    private _isDevMode = false;
     private _isAuthenticated = false;
     private _reconnectHideTimeout?: ReturnType<typeof setTimeout>;
 
@@ -56,7 +53,7 @@ export class WebSocketStatusBarService implements vscode.Disposable {
 
         this._disposables.push(
             vscode.workspace.onDidChangeConfiguration(event => {
-                if (event.affectsConfiguration(`${VSCODE_CONFIG.ARTEMIS_SECTION}.${VSCODE_CONFIG.SHOW_WEBSOCKET_STATUS_BAR_KEY}`)) {
+                if (event.affectsConfiguration(`${VSCODE_CONFIG.ARTEMIS_SECTION}.${VSCODE_CONFIG.DEVELOPER_MODE_KEY}`)) {
                     this._updateVisibilitySetting();
                 }
             })
@@ -71,8 +68,8 @@ export class WebSocketStatusBarService implements vscode.Disposable {
 
     private _updateVisibilitySetting(): void {
         const config = vscode.workspace.getConfiguration(VSCODE_CONFIG.ARTEMIS_SECTION);
-        this._showStatusBar = config.get<boolean>(VSCODE_CONFIG.SHOW_WEBSOCKET_STATUS_BAR_KEY, false);
-        this._applyVisibility();
+        this._isDevMode = config.get<boolean>(VSCODE_CONFIG.DEVELOPER_MODE_KEY, false);
+        this._updateStatusBarItem();
     }
 
     private _refreshStatus(): void {
@@ -82,7 +79,7 @@ export class WebSocketStatusBarService implements vscode.Disposable {
         if (
             this._currentStatus === 'connected'
             && previousStatus === 'reconnecting'
-            && !this._showStatusBar
+            && !this._isDevMode
         ) {
             if (this._reconnectHideTimeout) {
                 clearTimeout(this._reconnectHideTimeout);
@@ -110,10 +107,8 @@ export class WebSocketStatusBarService implements vscode.Disposable {
     }
 
     private _applyVisibility(): void {
-        // Logged out: there is no WebSocket to surface a state for. Honor the
-        // explicit "always show" setting for diagnostics, otherwise hide.
         if (!this._isAuthenticated) {
-            if (this._showStatusBar) {
+            if (this._isDevMode) {
                 this._statusBarItem.show();
             } else {
                 this._statusBarItem.hide();
@@ -127,7 +122,7 @@ export class WebSocketStatusBarService implements vscode.Disposable {
 
         if (needsAttention) {
             this._statusBarItem.show();
-        } else if (this._showStatusBar) {
+        } else if (this._isDevMode) {
             this._statusBarItem.show();
         } else if (this._reconnectHideTimeout) {
             this._statusBarItem.show();
@@ -139,31 +134,89 @@ export class WebSocketStatusBarService implements vscode.Disposable {
     private _updateStatusBarItem(): void {
         this._applyVisibility();
 
+        const attempts = this._websocketService.reconnectAttempts;
+
         switch (this._currentStatus) {
             case 'connected':
-                this._statusBarItem.text = '$(plug) WS Connected';
-                this._statusBarItem.tooltip = 'WebSocket connected. Click to reconnect.';
+                this._statusBarItem.text = this._isDevMode
+                    ? '$(plug) WS Connected'
+                    : '$(plug) Artemis: connected';
                 this._statusBarItem.backgroundColor = undefined;
                 break;
-            case 'reconnecting': {
-                const attempts = this._websocketService.reconnectAttempts;
-                this._statusBarItem.text = `$(sync~spin) Reconnecting (${attempts}/20)...`;
-                this._statusBarItem.tooltip = 'WebSocket reconnecting...';
+            case 'reconnecting':
+                this._statusBarItem.text = this._isDevMode
+                    ? `$(sync~spin) WS Reconnecting (${attempts}/20)...`
+                    : `$(sync~spin) Artemis: reconnecting (${attempts}/20)...`;
                 this._statusBarItem.backgroundColor = new vscode.ThemeColor('statusBarItem.warningBackground');
                 break;
-            }
             case 'connecting':
-                this._statusBarItem.text = '$(sync~spin) WS Connecting...';
-                this._statusBarItem.tooltip = 'WebSocket connecting...';
+                this._statusBarItem.text = this._isDevMode
+                    ? '$(sync~spin) WS Connecting...'
+                    : '$(sync~spin) Artemis: connecting...';
                 this._statusBarItem.backgroundColor = undefined;
                 break;
             case 'disconnected':
             default:
-                this._statusBarItem.text = '$(debug-disconnect) WS Disconnected';
-                this._statusBarItem.tooltip = 'WebSocket disconnected. Click to reconnect.';
+                this._statusBarItem.text = this._isDevMode
+                    ? '$(debug-disconnect) WS Disconnected'
+                    : '$(debug-disconnect) Artemis: offline';
                 this._statusBarItem.backgroundColor = new vscode.ThemeColor('statusBarItem.errorBackground');
                 break;
         }
+
+        this._statusBarItem.tooltip = this._buildTooltip();
+    }
+
+    private _buildTooltip(): string | vscode.MarkdownString {
+        if (this._isDevMode) {
+            return this._buildDevTooltip();
+        }
+        switch (this._currentStatus) {
+            case 'reconnecting': {
+                const md = new vscode.MarkdownString();
+                const attempts = this._websocketService.reconnectAttempts;
+                md.appendMarkdown(
+                    `**Reconnecting to Artemis... (${attempts}/20)**\n\n`
+                    + `Live updates are paused and will resume automatically.`
+                );
+                return md;
+            }
+            case 'disconnected': {
+                const md = new vscode.MarkdownString();
+                md.appendMarkdown(
+                    `**Connection to Artemis lost**\n\n`
+                    + `Live updates (build results, submission status, Iris) are paused.\n\n`
+                    + `Click to reconnect. If it keeps failing, check your internet connection or sign in again.`
+                );
+                return md;
+            }
+            case 'connecting':
+                return 'Connecting to Artemis...';
+            case 'connected':
+            default:
+                return 'Connected to Artemis. Click to reconnect.';
+        }
+    }
+
+    private _buildDevTooltip(): vscode.MarkdownString {
+        const d = this._websocketService.getDiagnostics();
+        const md = new vscode.MarkdownString();
+        md.appendMarkdown(`## WebSocket (dev)\n\n`);
+        md.appendMarkdown(`**Status:** ${this._currentStatus}\n\n`);
+        md.appendMarkdown(`**Connection:**\n`);
+        md.appendMarkdown(`- clientConnected: ${d.clientConnected}\n`);
+        md.appendMarkdown(`- clientActive: ${d.clientActive}\n`);
+        md.appendMarkdown(`- reconnect: ${d.reconnectAttempts}/${d.maxReconnectAttempts}\n\n`);
+        md.appendMarkdown(`**Subscriptions (${d.subscriptionCount}):**\n`);
+        if (d.subscriptions.length > 0) {
+            d.subscriptions.forEach(s => md.appendMarkdown(`- \`${s}\`\n`));
+        } else {
+            md.appendMarkdown(`- *none*\n`);
+        }
+        md.appendMarkdown(`\n**Session:** \`${d.sessionId}\`\n\n`);
+        md.appendMarkdown(`**Server:** \`${d.serverUrl}\`\n\n`);
+        md.appendMarkdown(`**WebSocket:** \`${d.websocketUrl}\`\n`);
+        return md;
     }
 
     private _clickInFlight = false;
diff --git a/extension/src/extension/utils/constants.ts b/extension/src/extension/utils/constants.ts
@@ -34,7 +34,6 @@ export const VSCODE_CONFIG = {
     DEFAULT_CLONE_PATH_KEY: 'defaultClonePath',
     SHOW_SET_DEFAULT_CLONE_PATH_PROMPT_KEY: 'showSetDefaultClonePathPrompt',
     DEVELOPER_MODE_KEY: 'developerMode',
-    SHOW_WEBSOCKET_STATUS_BAR_KEY: 'showWebSocketStatusBar',
     START_PAGE_KEY: 'startPage',
     SHOW_START_PAGE_SUGGESTION_KEY: 'showStartPageSuggestion',
     DATA_COLLECTION_CONSENT_KEY: 'dataCollectionConsent',
diff --git a/extension/test/unit/services/websocketStatusBar.test.ts b/extension/test/unit/services/websocketStatusBar.test.ts
