Merge branch dev into published

Author: PEZ

CHANGELOG.md

@@ -4,6 +4,10 @@ Changes to Calva.
 
 ## [Unreleased]
 
+## [2.0.530] - 2025-09-22
+
+- [Make shadow-cljs runtimes status update with connection status](https://github.com/BetterThanTomorrow/calva/issues/2928)
+
 ## [2.0.529] - 2025-09-21
 
 - Fix: [No `node-repl` and `browser-repl` builds available with **deps.edn + shadow-cljs** project types](https://github.com/BetterThanTomorrow/calva/issues/2929)

docs/site/shadow-cljs.md

@@ -5,10 +5,9 @@ search:
   boost: 7
 ---
 
-Calva supports most any JVM hosted ClojureScript environment (and some others, including SCI based, too), but shadow-cljs gets some special treatment to try make it extra convenient to use.
-
-With many shadow-cljs projects, Calva's _connect project type_ **shadow-cljs**, is the right choice. Projects that use Leiningen or deps.edn can be used both with the **Leiningen/deps.edn** _and_ **shadow-cljs** type, depending on configuration see [below](#shadow-cljs-in-full-stack-projects) for more on this.
+Calva supports most any JVM hosted ClojureScript environment (and some others, including SCI based, too), but [shadow-cljs](https://github.com/thheller/shadow-cljs) gets some special treatment to try to make it extra convenient to use.
 
+With many shadow-cljs projects, Calva's _connect project type_ **shadow-cljs**, is the right choice. Projects that use Leiningen or deps.edn can be used both with the **Leiningen/deps.edn** _and_ **shadow-cljs** type, depending on configuration, see [below](#shadow-cljs-in-full-stack-projects) for more on this.
 
 # shadow-cljs - browser quickstart
 
@@ -29,30 +28,69 @@ Here's how you start a shadow-cljs ClojureScript REPL and connect Calva with the
 1. Open http://localhost:8020/ in the browser
 1. Open browser.cljs file and load it in the REPL: **Calva: Load/Evaluate Current File and Dependencies**
 
-Now you can should be able to evaluate forms, e.g.:
+Now you should be able to evaluate forms, e.g.:
 
 * The current form or selection with <kbd>ctrl</kbd>+<kbd>enter</kbd>, or
 * Top-level forms with <kbd>alt/option</kbd>+<kbd>enter</kbd>.
 
 (See [Code Evaluation](evaluation.md))
 
-# Runtime Selection
+# shadow-cljs Runtimes
+
+A shadow-cljs Runtime is an instance of your app that connects to shadow-cljs. When Calva connects to a runtime, that's where your ClojureScript REPL evaluations run.
+
+```
+Calva <-talks to-> shadow-cljs server <-talks-to-> App (Runtime)
+```
 
-When working with shadow-cljs projects you often have multiple runtimes running in different browser tabs, browsers, and phones, simultaneously. Calva will automatically connect to one of these (whichever runtime shadow-cljs connects when selecting a build). And you can then also switch between different JavaScript runtimes without reconnecting the REPL.
+We call the **App (Runtime)** in this diagram *the currently connected runtime*, and sometimes *the active runtime*.
 
-## Available Runtimes
+When working with shadow-cljs projects you often have multiple runtimes running simultaneously across different browsers, tabs, and devices. Calva automatically connects to one runtime initially and lets you switch between them. It also detects when runtimes connect or disconnect.
 
-Use the command **Calva: Select Shadow CLJS Runtime** to see all currently connected runtimes, presented in a VS Code quick-pick menu. The status bar will also display the active runtime when connected to a shadow-cljs project, and clicking this indicator will open the runtimes menu.
+## Available runtimes
 
-## Switching Runtimes
+Use the command **Calva: Select Shadow CLJS Runtime** to see all runtimes that are currently connected to shadow-cljs. The runtimes will be presented in a VS Code quick-pick menu. The status bar will also display the active runtime, and clicking this indicator will open the runtimes menu.
+
+## Switching runtimes
 
 The **Calva: Select Shadow CLJS Runtime** menu will also let you select which runtime the `cljs` repl is connected to.
 
 ![shadow-cljs-runtimes-menu](/images/shadow-cljs/runtimes-menu.png)
 
+## Automatic tracking of current runtime
+
+Calva reacts to notifications from shadow-cljs about runtimes that connect to the server:
+
+If no runtime is connected to Calva and a new runtime connects to shadow-cljs:
+
+* *Calva will connect to this new runtime*
+
+If Calva is connected to a runtime that disconnects from shadow-cljs:
+
+* *Calva will have no connected runtime*. Even if there are more runtimes connected to shadow-cljs, you'll need to initiate a connection and select a new runtime manually.
+
+!!! Note "Reload scenarios supported"
+
+    Note that this means that if you have the app running in browser tabs **A**, **B**, and **C**, with Calva connected to **A**, and you reload browser tab **A**:
+
+    * *Calva will “reconnect” to **A***
+
+    But if you just close **A**:
+
+    * *Calva will not automatically connect to **B**, nor **C***
+
+    And if you, while disconnected, start the app on the iPhone **D**:
+
+    * *Calva will connect **D***
+
+!!! Note "Code hot reload"
+
+    Also note that the connection we're talking about here is Calva's connection to the app's REPL. shadow-cljs hot reloading of code when a file is saved always happens in all runtimes for all apps that are built from the code of that file. Calva is not involved in this mechanism.
+
+
 # shadow-cljs in full stack projects
 
-**shadow-cljs** is a bit special in regards to Calva REPL connection. Mainly because you can start **shadow-cljs** and it's nREPL server in two ways:
+**shadow-cljs** is a bit special in regards to Calva REPL connection. Mainly because you can start **shadow-cljs** and its nREPL server in two ways:
 
 1. Using the **shadow-cljs** npm executable
 2. Via the Clojure REPL in your Leiningen or **deps.edn** project
@@ -62,7 +100,7 @@ These options show up as **project types** when connecting or jacking in:
 1. Project type: **shadow-cljs**
 2. Project type: **deps.edn + shadow-cljs** or **Leiningen + shadow-cljs**
 
-The technical difference here is wether you let **shadow-cljs** start **clojure**/**Leiningen** (the first option) or if you let Calva do it (the second option). If you let Calva do it, Calva will then start the **shadow-cljs** watcher from the Clojure process. From a usage perspective the two approaches will result in different channeling of **shadow-cljs** output, e.g. test runner results. With the first option (the **shadow-cljs** project type), **shadow-cljs** output will be channeled to the **Jack-in** terminal. With the **deps.edn**/**Leiningen** option, that output will be channeled to the Output/REPL window.
+The technical difference here is whether you let **shadow-cljs** start **clojure**/**Leiningen** (the first option) or if you let Calva do it (the second option). If you let Calva do it, Calva will then start the **shadow-cljs** watcher from the Clojure process. From a usage perspective the two approaches will result in different channeling of **shadow-cljs** output, e.g. test runner results. With the first option (the **shadow-cljs** project type), **shadow-cljs** output will be channeled to the **Jack-in** terminal. With the **deps.edn**/**Leiningen** option, that output will be channeled to the Output/REPL window.
 
 See [shadow-cljs + Clojure with Calva: The basics](https://blog.agical.se/en/posts/shadow-cljs-clojure-cljurescript-calva-nrepl-basics/) for some more discussion on how the REPL connection works.
 

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.529",
+  "version": "2.0.530",
   "publisher": "betterthantomorrow",
   "author": {
     "name": "Better Than Tomorrow",

package.json

@@ -7,7 +7,7 @@ import * as open from 'open';
 import status from './status';
 import * as projectTypes from './nrepl/project-types';
 import { NReplClient, NReplSession } from './nrepl';
-import { detectInitialRuntime } from './shadow-cljs-runtime';
+import * as shadowCljsRuntime from './shadow-cljs-runtime';
 import {
   CljsTypeConfig,
   ReplConnectSequence,
@@ -154,6 +154,12 @@ async function connectToHost(hostname: string, port: number, connectSequence: Re
         const cljsType: CljsTypeConfig = isBuiltinType
           ? getDefaultCljsType(connectSequence.cljsType as string)
           : (connectSequence.cljsType as CljsTypeConfig);
+
+        // Initialize shadow-cljs remote notifications if we're connecting to shadow-cljs
+        if (isShadowCljsReplType(cljsType)) {
+          await shadowCljsRuntime.initializeShadowRemoteNotifications();
+        }
+
         translatedReplType = createCLJSReplType(
           cljsType,
           projectTypes.getCljsTypeName(connectSequence),
@@ -513,7 +519,7 @@ function createCLJSReplType(
       }
       const runtimesConnected = await waitForShadowCljsRuntimes();
       if (runtimesConnected) {
-        await detectInitialRuntime();
+        await shadowCljsRuntime.detectInitialRuntime();
       }
       return runtimesConnected;
     } else {

src/connector.ts

@@ -20,6 +20,7 @@ import { getConfig } from '../config';
 import { log, Direction } from './logging';
 import * as string from '../util/string';
 import * as output from '../results-output/output';
+import { handleShadowRemoteMessage } from '../shadow-cljs-runtime';
 
 function hasStatus(res: any, status: string): boolean {
   return res.status && res.status.indexOf(status) > -1;
@@ -293,6 +294,11 @@ export class NReplSession {
   }
 
   _defaultMessageHandler(msgData: any) {
+    if (msgData.op === 'shadow-remote-msg') {
+      void handleShadowRemoteMessage(msgData);
+      return;
+    }
+
     if (msgData['repl-type']) {
       this.replType = msgData['repl-type'];
     }
@@ -972,6 +978,38 @@ export class NReplSession {
       }
     });
   }
+
+  shadowCljsRemoteInit() {
+    return new Promise<any>((resolve, reject) => {
+      const id = this.client.nextId;
+      const msg = {
+        op: 'shadow-remote-init',
+        id: id,
+        session: this.sessionId,
+        'data-type': 'edn',
+      };
+      // shadow-cljs remote messages do not respond with an acknowledging response
+      // so we can't bind a messagehandler the usual way. Fire-and-forget!
+      this.client.write(msg);
+      resolve(null);
+    });
+  }
+
+  shadowCljsRemoteRegisterNotify() {
+    return new Promise<any>((resolve, reject) => {
+      const id = this.client.nextId;
+      const msg = {
+        op: 'shadow-remote-msg',
+        id: id,
+        session: this.sessionId,
+        data: '{:op :request-clients :notify true :query [:eq :type :runtime]}',
+      };
+      // shadow-cljs remote messages do not respond with an acknowledging response
+      // so we can't bind a messagehandler the usual way. Fire-and-forget!
+      this.client.write(msg);
+      resolve(null);
+    });
+  }
 }
 
 /**