Merge branch dev into published

Author: PEZ

.github/copilot-instructions.md

@@ -0,0 +1,35 @@
+## Design Context
+
+### Users
+
+VS Code developers adopting or practicing Clojure/ClojureScript. The audience spans from **complete Clojure beginners** (the explicit growth mission) to **experienced Clojurians** who chose VS Code as their editor. They arrive with VS Code muscle memory and expectations — syntax highlighting, command palette, familiar keybindings — and need the REPL to feel like a natural extension of that, not a foreign system bolted on.
+
+The context of use is deep-focus programming: long sessions, high cognitive load, frequent context-switching between code and REPL output. The interface must never compete for attention with the code itself.
+
+### Brand Personality
+
+**Approachable, precise, alive.**
+
+Calva is named after Calvados — a spirit that gains its character from what it's distilled from (CIDER/nREPL) and what it matures in (VS Code). The brand voice is that of a master distiller: confident but unhurried, opinionated but welcoming, spartan but *not* poor. As the Tao states: "VS Code and Clojure brought together has the capacity to create something amazingly rich and luxurious."
+
+The emotional goals are **confidence** (I know what's happening), **flow** (nothing breaks my concentration), and **precision** (sharp, exact, professional). The anti-reference is GitLens — invasive, attention-grabbing, too much visual presence in the editor.
+
+### Aesthetic Direction
+
+- **Theme**: Native VS Code. Custom surfaces (webviews, output panels) should feel like they belong to the user's chosen VS Code theme, not to Calva's own visual system. Use `var(--vscode-*)` CSS custom properties as the primary palette.
+- **Brand color**: Golden amber `#db9550` — core brand accent. Use sparingly: status indicators, the Calva logo, moments of identity. Never as a dominant surface color.
+- **Font**: Fira Code is the bundled code font for webviews. Body/UI text inherits from VS Code's editor font family.
+- **Tone**: Quiet competence. The interface should feel like a well-made tool — present when needed, invisible when not. Spartan in the Halloway sense: few features, each done right.
+- **Anti-patterns**: Invasive decorations, unsolicited overlays, attention-competing UI, feature clutter. Calva should never make the user aware of Calva when they're trying to think about Clojure.
+
+### Design Principles
+
+1. **The VS Code way is Calva's way.** Leverage existing VS Code patterns and conventions. What's old is old; what's new should be as easy as possible to pick up. Don't invent new interaction patterns when VS Code already has one.
+
+2. **Remove obstacles to the REPL.** Every UI decision should be evaluated by: does this help or hinder the developer's path to evaluating code and understanding results? The REPL connection is the critical moment; evaluation results are the critical data.
+
+3. **Spartan, not poor.** Resist feature creep. Few knobs, sane defaults. But the knobs that exist should feel luxurious — well-considered, well-placed, well-documented. Quality over quantity.
+
+4. **Simplify the complex.** Calva has organic complexity (multiple output destinations, REPL window maintenance, session routing). Design should actively work to reduce cognitive load around these areas rather than expose the underlying complexity.
+
+5. **Invisible when working, present when needed.** Status information, connection state, session routing — these should be discoverable but not intrusive. The developer's attention belongs to their code, not to Calva's UI.

.impeccable.md

@@ -0,0 +1,35 @@
+# Calva Design Context
+
+## Users
+
+VS Code developers adopting or practicing Clojure/ClojureScript. The audience spans from **complete Clojure beginners** (the explicit growth mission) to **experienced Clojurians** who chose VS Code as their editor. They arrive with VS Code muscle memory and expectations — syntax highlighting, command palette, familiar keybindings — and need the REPL to feel like a natural extension of that, not a foreign system bolted on.
+
+The context of use is deep-focus programming: long sessions, high cognitive load, frequent context-switching between code and REPL output. The interface must never compete for attention with the code itself.
+
+## Brand Personality
+
+**Approachable, precise, alive.**
+
+Calva is named after Calvados — a spirit that gains its character from what it's distilled from (CIDER/nREPL) and what it matures in (VS Code). The brand voice is that of a master distiller: confident but unhurried, opinionated but welcoming, spartan but *not* poor. As the Tao states: "VS Code and Clojure brought together has the capacity to create something amazingly rich and luxurious."
+
+The emotional goals are **confidence** (I know what's happening), **flow** (nothing breaks my concentration), and **precision** (sharp, exact, professional). The anti-reference is GitLens — invasive, attention-grabbing, too much visual presence in the editor.
+
+## Aesthetic Direction
+
+- **Theme**: Native VS Code. Custom surfaces (webviews, output panels) should feel like they belong to the user's chosen VS Code theme, not to Calva's own visual system. Use `var(--vscode-*)` CSS custom properties as the primary palette.
+- **Brand color**: Golden amber `#db9550` — core brand accent. Use sparingly: status indicators, the Calva logo, moments of identity. Never as a dominant surface color.
+- **Font**: Fira Code is the bundled code font for webviews. Body/UI text inherits from VS Code's editor font family.
+- **Tone**: Quiet competence. The interface should feel like a well-made tool — present when needed, invisible when not. Spartan in the Halloway sense: few features, each done right.
+- **Anti-patterns**: Invasive decorations, unsolicited overlays, attention-competing UI, feature clutter. Calva should never make the user aware of Calva when they're trying to think about Clojure.
+
+## Design Principles
+
+1. **The VS Code way is Calva's way.** Leverage existing VS Code patterns and conventions. What's old is old; what's new should be as easy as possible to pick up. Don't invent new interaction patterns when VS Code already has one.
+
+2. **Remove obstacles to the REPL.** Every UI decision should be evaluated by: does this help or hinder the developer's path to evaluating code and understanding results? The REPL connection is the critical moment; evaluation results are the critical data.
+
+3. **Spartan, not poor.** Resist feature creep. Few knobs, sane defaults. But the knobs that exist should feel luxurious — well-considered, well-placed, well-documented. Quality over quantity.
+
+4. **Simplify the complex.** Calva has organic complexity (multiple output destinations, REPL window maintenance, session routing). Design should actively work to reduce cognitive load around these areas rather than expose the underlying complexity.
+
+5. **Invisible when working, present when needed.** Status information, connection state, session routing — these should be discoverable but not intrusive. The developer's attention belongs to their code, not to Calva's UI.

CHANGELOG.md

@@ -4,6 +4,11 @@ Changes to Calva.
 
 ## [Unreleased]
 
+## [2.0.583] - 2026-05-04
+
+- [Enable renaming of REPL sessions](https://github.com/BetterThanTomorrow/calva/issues/3197)
+- Fix: [Calva disconnects and closed the WebSocket server when connecting a websocket REPL configured for the same port](https://github.com/BetterThanTomorrow/calva/issues/3198)
+
 ## [2.0.582] - 2026-05-03
 
 - [Make Orphaned/dicsonnected WebSocket servers closable](https://github.com/BetterThanTomorrow/calva/issues/3195)

docs/site/repl-ui.md

@@ -25,6 +25,8 @@ Calva keeps every nREPL connection alive until you explicitly disconnect it. Thi
 
   E.g. connect three Babashka repls and you will have one session named `bb` another named `bb:2`, and a third named `bb:3`. If you then connect two Clojure + ClojureScript repls using default session names, you will have four more sessions named: `clj`, `cljs`, `clj:4`, `cljs:4`.
 
+- You can rename any session by clicking the pencil icon next to it in the sessions menu. This lets you give sessions meaningful names like `epupp-youtube` instead of the auto-generated `epupp:2`. Renames take effect immediately for routing and evaluation, but do not persist across reconnection.
+
 ![REPL Sessions Menu](images/repl-ui/repl-sessions-menu.png)
 
 ## UI Components Overview

package-lock.json

@@ -3,7 +3,7 @@
   "displayName": "Calva: Clojure & ClojureScript Interactive Programming",
   "description": "Integrated REPL, formatter, Paredit, and more. Powered by cider-nrepl and clojure-lsp.",
   "icon": "assets/calva.png",
-  "version": "2.0.582",
+  "version": "2.0.583",
   "publisher": "betterthantomorrow",
   "author": {
     "name": "Better Than Tomorrow",

package.json

@@ -103,30 +103,18 @@ async function connectViaWebSocket(
   const projectRoot = state.getProjectRootUri().toString();
   const useSecondarySession = secondarySession.shouldUseSecondarySession(connectSequence);
 
+  // WebSocket connections skip reconnection candidate detection entirely.
+  // Each WS server is single-client, so multiple browser tabs require separate
+  // servers on different ports. The port-in-use prompt handles conflicts naturally.
   const resolution = sessionNameResolver.resolveSessionNames(
     baseSessionNames,
     projectRoot,
     wsHost,
-    isJackIn ? null : wsPort
+    wsPort,
+    { skipReconnect: true }
   );
   const sessionRoleKeys = resolution.finalNames;
 
-  if (resolution.reconnectClientKey) {
-    output.appendLineOtherOut(
-      `Reconnecting: disconnecting existing client for sessions: ${Object.values(sessionRoleKeys)
-        .filter(Boolean)
-        .join(', ')}`
-    );
-    if (isJackIn) {
-      await jackIn.stopJackInProcessesByClientKey(resolution.reconnectClientKey, {
-        preserveSuffix: true,
-      });
-    }
-    if (clientRegistry.getClient(resolution.reconnectClientKey)) {
-      await disconnectClientByKey(resolution.reconnectClientKey, { preserveSuffix: true });
-    }
-  }
-
   const sessionGlobMap = sessionRoleUtils.deriveSessionGlobMap(
     connectSequence,
     sessionRoleKeys,

src/connector.ts

@@ -2,12 +2,14 @@ import * as expectLib from 'expect';
 import type * as nrepl from '../../../../src/nrepl';
 import * as sessionRegistry from '../../../../src/nrepl/session-registry';
 import * as clientRegistry from '../../../../src/nrepl/client-registry';
+import * as sessionNameSuffix from '../../../../src/nrepl/session-name-suffix';
 
 describe('session registry', () => {
   afterEach(() => {
     sessionRegistry._testUtility_registeredSessions.clear();
     sessionRegistry.setClojureDocsSessionKey(null);
     clientRegistry._testUtility_registeredClients.clear();
+    sessionNameSuffix.resetPool();
   });
 
   describe('resolveSessionKey', () => {
@@ -148,4 +150,88 @@ describe('session registry', () => {
       expectLib.expect((mainForB as any)?._calvaSessionMetadata?.key).toBe('clj-b');
     });
   });
+
+  describe('renameSession', () => {
+    const createSession = (clientKey: string): nrepl.NReplSession =>
+      ({ client: { clientKey } } as unknown as nrepl.NReplSession);
+
+    const createMockClient = (clientKey: string) =>
+      ({ clientKey } as unknown as Parameters<typeof clientRegistry.registerClient>[0]);
+
+    it('renames session: accessible under new key, not under old', () => {
+      sessionRegistry.registerSession('epupp', createSession('client-a'), {});
+
+      const result = sessionRegistry.renameSession('epupp', 'epupp-youtube');
+
+      expectLib.expect(result).toBe(true);
+      expectLib.expect(sessionRegistry.getSession('epupp-youtube')).toBeDefined();
+      expectLib.expect(sessionRegistry.getSession('epupp')).toBeUndefined();
+    });
+
+    it('returns false if old key not found', () => {
+      const result = sessionRegistry.renameSession('nonexistent', 'new-name');
+
+      expectLib.expect(result).toBe(false);
+    });
+
+    it('returns false if new key already exists', () => {
+      sessionRegistry.registerSession('alpha', createSession('client-a'), {});
+      sessionRegistry.registerSession('beta', createSession('client-b'), {});
+
+      const result = sessionRegistry.renameSession('alpha', 'beta');
+
+      expectLib.expect(result).toBe(false);
+      expectLib.expect(sessionRegistry.getSession('alpha')).toBeDefined();
+    });
+
+    it('updates sessionRoleKeys for primary session', () => {
+      clientRegistry.registerClient(createMockClient('client-a'), {
+        connectionState: {
+          sessionRoleKeys: { primary: 'clj', secondary: 'cljs' },
+        },
+      });
+      sessionRegistry.registerSession('clj', createSession('client-a'), {});
+      sessionRegistry.registerSession('cljs', createSession('client-a'), { isSecondary: true });
+
+      sessionRegistry.renameSession('clj', 'my-clj');
+
+      const state = clientRegistry.getConnectionState('client-a');
+      expectLib.expect(state?.sessionRoleKeys?.primary).toBe('my-clj');
+      expectLib.expect(state?.sessionRoleKeys?.secondary).toBe('cljs');
+    });
+
+    it('updates sessionRoleKeys for secondary session', () => {
+      clientRegistry.registerClient(createMockClient('client-a'), {
+        connectionState: {
+          sessionRoleKeys: { primary: 'clj', secondary: 'cljs' },
+        },
+      });
+      sessionRegistry.registerSession('clj', createSession('client-a'), {});
+      sessionRegistry.registerSession('cljs', createSession('client-a'), { isSecondary: true });
+
+      sessionRegistry.renameSession('cljs', 'my-cljs');
+
+      const state = clientRegistry.getConnectionState('client-a');
+      expectLib.expect(state?.sessionRoleKeys?.primary).toBe('clj');
+      expectLib.expect(state?.sessionRoleKeys?.secondary).toBe('my-cljs');
+    });
+
+    it('releases suffix when renaming away from suffixed name', () => {
+      const suffix = sessionNameSuffix.acquireNextAvailableSuffix();
+      expectLib.expect(suffix).toBe('2');
+
+      clientRegistry.registerClient(createMockClient('client-a'), {
+        connectionState: {
+          sessionRoleKeys: { primary: 'epupp:2' },
+        },
+      });
+      sessionRegistry.registerSession('epupp:2', createSession('client-a'), {});
+
+      sessionRegistry.renameSession('epupp:2', 'epupp-youtube');
+
+      // Suffix "2" should be released back to the pool
+      const nextSuffix = sessionNameSuffix.acquireNextAvailableSuffix();
+      expectLib.expect(nextSuffix).toBe('2');
+    });
+  });
 });

src/extension-test/unit/nrepl/session-registry-test.ts

@@ -285,6 +285,61 @@ describe('session-name-resolver', () => {
       });
     });
 
+    describe('skipReconnect option', () => {
+      it('skips reconnection and treats as conflict when skipReconnect is true', () => {
+        const baseNames = { primary: 'clj', secondary: 'cljs' };
+        const projectRoot = '/project-a';
+
+        // Register existing client that would normally trigger reconnection
+        clientRegistry.registerClient(createMockClient('client-a'), {
+          projectRoot,
+          host: 'localhost',
+          port: 3340,
+          connectionState: {
+            baseSessionNames: baseNames,
+          },
+        });
+        sessionRegistry.registerSession('clj', createSession('client-a'), {});
+
+        const resolution = sessionNameResolver.resolveSessionNames(
+          baseNames,
+          projectRoot,
+          'localhost',
+          3340,
+          { skipReconnect: true }
+        );
+
+        expectLib.expect(resolution.reconnectClientKey).toBeUndefined();
+        expectLib.expect(resolution.suffix).toBeDefined();
+        expectLib.expect(resolution.finalNames.primary).toMatch(/^clj:\w+$/);
+        expectLib.expect(resolution.finalNames.secondary).toMatch(/^cljs:\w+$/);
+      });
+
+      it('still finds reconnection candidate when skipReconnect is false', () => {
+        const baseNames = { primary: 'clj', secondary: 'cljs' };
+        const projectRoot = '/project-a';
+
+        clientRegistry.registerClient(createMockClient('client-a'), {
+          projectRoot,
+          host: 'localhost',
+          port: 3340,
+          connectionState: {
+            baseSessionNames: baseNames,
+          },
+        });
+
+        const resolution = sessionNameResolver.resolveSessionNames(
+          baseNames,
+          projectRoot,
+          'localhost',
+          3340,
+          { skipReconnect: false }
+        );
+
+        expectLib.expect(resolution.reconnectClientKey).toBe('client-a');
+      });
+    });
+
     describe('reconnection scenario (port-unaware, e.g. jack-in)', () => {
       it('detects reconnection when baseNames and projectRoot match (port is null)', () => {
         const baseNames = { primary: 'bb' };

src/extension-test/unit/session-name-resolver-test.ts

@@ -138,9 +138,12 @@ export function resolveSessionNames(
   baseNames: sessionRoleUtils.SessionRoleKeys,
   projectRoot: string,
   host: string,
-  port: number | null
+  port: number | null,
+  options?: { skipReconnect?: boolean }
 ): SessionNameResolution {
-  const reconnectClientKey = findReconnectionCandidate(baseNames, projectRoot, host, port);
+  const reconnectClientKey = options?.skipReconnect
+    ? undefined
+    : findReconnectionCandidate(baseNames, projectRoot, host, port);
   if (reconnectClientKey) {
     const existingState = clientRegistry.getConnectionState(reconnectClientKey);
     const existingSuffix = existingState?.suffix;