Add explanations to the Scilttle nRepl notebook (#271)

* clean show-expression

* Add explanations to notebook on Scittle nRepl

Author: kloimhardt

src/mentat_collective/emmy/appendix_scittlerepl.clj

@@ -2,17 +2,19 @@
   :clay             {:title  "The Scittle Repl"
                      :quarto {:author   :kloimhardt
                               :type     :post
+                              :description "This Clay notebook has its Scittle nRepl built in, so you can connect your editor to its ClojureScript side."
                               :date     "2025-12-04"
                               :image    "appendix_scittlerepl.png"
                               :category :libs
                               :tags     [:scittle :repl]}}}
 (ns mentat-collective.emmy.appendix-scittlerepl
   (:require
+   [nrepl.core :as repl]
    [sci.nrepl.browser-server :as nrepl]
    [scicloj.kindly.v4.api :as kindly]
    [scicloj.kindly.v4.kind :as kind]))
 
-;; This Clay notebook has its Scittle nrepl built in, so you can connect your editor to its ClojureScript side.
+;; This HTML page, as any Civitas notebook, is hosted by [Clay](https://github.com/scicloj/clay). The notebook is meant to be changed in a local Civitas instance. This is because it is all about connecting your local editor to the browser, i.e. the ClojureScript side of this notebook.It is about sending code from your editor to an in browser process.
 
 ;; ## Starting the Scittle Repl of this Clay Notebook
 
@@ -22,9 +24,25 @@
 ;; (nrepl/start! {:nrepl-port 1339 :websocket-port 1340})
 ;;```
 
-;; ... and (re)load this notebook within your local Clay instance.
+;; ... and (re)load this notebook within your local Clay instance. Then again, comment the line above and reload the notebook (again).
 
-;; Then open an arbitrary (not .clj but) .cljs ClojureScript file.
+;; Below you should see a hash-map that contains the entry `:value "3"`
+
+(defn connect-and-eval
+  [host port code]
+  (with-open [conn (repl/connect :host host :port port)] ; Establishes the connection
+    (-> (repl/client conn 1000) ; Creates a client with a message timeout
+        (repl/message {:op "eval" :code code}) ; Sends an "eval" message
+        (doall)
+        (clojure.pprint/pprint)
+        #_(repl/response-values))))
+
+(if (not @@#'nrepl/!socket)
+  "not connected"
+  (connect-and-eval "localhost" 1339 "(+ 1 2)"))
+
+
+;; Next, open an arbitrary (not .clj but) .cljs ClojureScript file.
 
 ;; In your local editor, open a Repl connection. For example in Emacs/Cider, this means the following 5 steps: (I) *(sesman-start)* (II) choose cider-connect-cljs (III) select localhost (IV) port 1339, followed by (V) the REPL type nbb.
 
@@ -34,6 +52,12 @@
 (kind/hiccup
   [:img {:src "GClef.svg"}])
 
+;; ## Some Explanations
+
+;; - Scittle is the ClojureScript runtime executing in the browser
+;; - `browser-server` is a "broker" process that receives instructions from your editor (send form, send file), sends it to Scittle, and returns the result.
+;; - The reason browser-server exists is because editors have nRepl integrations, but nothing to talk to Scittle directly.
+;; - Scittle is listening on a websocket which is different from an nRepl socket. Nontheless, it performs the same function.
 
 ;; ## The Scittle State
 
@@ -44,7 +68,6 @@
   {"Action"              ["Reload browser" "Save this very notebook .clj file" "Save any .cljs file"]
    "Clean Scittle state" ["yes" "yes" "no"]})
 
-
 ;; The Scittle Repl looses its state when the browser window is reloaded. This also means that the Scittle Repl looses its state when this very notebook .clj file is reloaded. As opposed to that, the Clojure/JVM state persists in any case. In fact, this very notebook, in using defonce, relies on a persistent Clojure/JVM state. But the possibility to produce a clean Scittle slate via browser reload can be of great advantage especially for the (domain-expert but) Repl-novice.
 
 ;; This notebook works best when Clay is started in file-watcher mode via `clojure -M:clay`. It is not a good idea to open, next to the Scittle Repl, also a Clojure/JVM Repl connection. At least in my setup, opening more than one Repl connection leads to unstable behaviour. Act at your own discretion.
@@ -53,6 +76,10 @@
 
 ;; In sum, while saving a .cljs file keeps the Scittle state, saving this very notebook .clj file cleans the Scittle state. But as I can only want you to happily repl in .cljs files exclusively, further changing and loading of this very notebook is not necessary. Of course, you are free to change and save this very notebook .clj file as often as you like, but make sure all your .cljs files are saved before you do so. Any unsaved Scittle .cljs file keeps this very notebook from reloading on change.
 
+;; ## With Clay, you can talk to Scittle without nRepl, but it won't answer (yet)
+;; Clay already has a websocket connection from the Clojure process to the HTML page (and therefore Scittle). This is how Clay loads .cljs files when in live-reload mode. It sends the code over the websocket and calls Scittle. `scicloj.clay.v2.server/scittle-eval-string!` is called when a cljs file is changed, and `scicloj.clay.v2.server/communication-script` contains the JavaScript that does `window.scittle.core.eval_string(code);`
+;; So there is already a direct bridge from the Clojure Clay process to the Scittle process. However the current implementation does not send a result back to Clay.
+
 ;; ## The inner workings of Scittle and sci.nrepl
 
 ;; The following code is just to reveal the inner workings, you should already be able to happily repl in your .cljs file.
@@ -66,13 +93,13 @@
    ;;[:script {:src "https://cdn.jsdelivr.net/npm/scittle@0.6.22/dist/scittle.nrepl.js"}]
    ])
 
-;; ## Also with Babashka
+;; ## Connect to Scittle and the browser without Java
 
-;; It is possible to start the nrepl server entirely without Java.
+;; The main advantage of this nRepl method is that it is possible to start the nRepl server entirely without Java (and thus entirely without Clay).
 
 ;; Make sure that, in your local directory, there exists the file [browser_server.clj](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/src/mentat_collective/emmy/browser_server.clj)
 
-;; Then in the terminal, start babashka in the following way
+;; Then in the terminal, start [Babashka](https://babashka.org) in the following way
 
 ^:kindly/hide-code
 (kind/code

src/mentat_collective/emmy/sicm_ch01.clj

@@ -16,12 +16,17 @@
             [mentat-collective.emmy.scheme :refer [define-1 let-scheme lambda]]
             [civitas.repl :as repl]))
 
+;; The following examples are taken from the MIT open-access book [Structure and Interpretation of Classical Mechanics (SICM)](https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/9579/sicm_edition_2.zip/chapter001.html).
+
+^:kindly/hide-code
+(do
+  "if you `prod` to `false`, the browser will be busy calculating, be patient"
+  (def prod true))
+
 ^:kindly/hide-code
 (def md
   (comp kindly/hide-code kind/md))
 
-(md "The following examples are taken from the MIT open-access book [Structure and Interpretation of Classical Mechanics (SICM)](https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/9579/sicm_edition_2.zip/chapter001.html).")
-
 (md "Another notebook can be found on the [Road to Reality website](https://reality.mentat.org/essays/reality/introduction#welcome-to-the-road-to-reality!) by [Sam Ritchie](https://roadtoreality.substack.com/p/the-first-executable-essay-is-live), the author (along with [Colin Smith](https://github.com/littleredcomputer)) of [Emmy, the Computer Algebra System](https://emmy.mentat.org).")
 
 ;; For interactivity, I have some
@@ -73,45 +78,44 @@
      (require emmy-mn)))
 
 ^:kindly/hide-code
-(define show-exp (comp str simplify))
+(kind/scittle
+  '(defn show-expression [e]
+     (simplify e)))
 
 ^:kindly/hide-code
 (kind/scittle
-  '(defn show-expression [b & c]
-     (if (keyword? b)
-       (show-exp (first c))
-       (show-exp b))))
+  '(def show-tex-expression show-expression))
 
 ^:kindly/hide-code
 (def tex (comp kind/tex emmy.expression.render/->TeX simplify))
 
 ^:kindly/hide-code
-(defmacro show-expression [b & c]
-  (let [prod      true ;; if you set this to false, the browser will be busy calculating, be patient
-        reag-comp (fn [b] (let [server-erg (show-exp (eval b))]
-                            (list 'kind/reagent
-                                  [:div (list 'quote
-                                              (list 'let ['a (list 'show-exp b)]
-                                                    (list 'if 'false #_(list '= server-erg 'a)
-                                                          [:tt 'a]
-                                                          [:div
-                                                           (when (not prod)
-                                                             [:div
-                                                              [:tt 'a]
-                                                              [:p]])
-                                                           [:tt server-erg]])))])))]
-    (case b
-      :tex
-      (if prod
-        (list 'tex (first c))
-        (reag-comp (first c)))
-      (if prod
-        (list 'simplify b)
-        (reag-comp b)))))
+(define show-exp (comp str simplify))
+
+^:kindly/hide-code
+(defn reag-comp [b]
+  (let [server-erg (show-exp (eval b))]
+    (list 'kind/reagent
+          [:div (list 'quote
+                      (list 'let ['a (list 'show-exp b)]
+                            [:div
+                             (when (not prod)
+                               [:div
+                                [:tt 'a]
+                                [:p (list 'str (list '= server-erg 'a))]])
+                             [:tt server-erg]]))])))
+
+^:kindly/hide-code
+(defmacro show-expression [e]
+  (if prod
+    (list 'simplify e)
+    (reag-comp e)))
 
 ^:kindly/hide-code
 (defmacro show-tex-expression [e]
-  (list 'show-expression :tex e))
+  (if prod
+    (list 'tex e)
+    (reag-comp e)))
 
 ^:kindly/hide-code
 (define velocities velocity)