Add live CEK stepper island — interactive stepping debugger

A defisland that lets users type an SX expression, step through CEK
evaluation one transition at a time, and see C/E/K registers update
live. Demonstrates that cek-step is pure data->data.

- cek.sx geography: add ~geography/cek/demo-stepper island with
  source input, step/run/reset buttons, state display, step history
- platform_js.py: register CEK stepping primitives (make-cek-state,
  cek-step, cek-terminal?, cek-value, make-env, sx-serialize) so
  island code can access them

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

shared/static/scripts/sx-browser.js

@@ -14,7 +14,7 @@
   // =========================================================================
 
   var NIL = Object.freeze({ _nil: true, toString: function() { return "nil"; } });
-  var SX_VERSION = "2026-03-14T10:44:25Z";
+  var SX_VERSION = "2026-03-14T13:46:35Z";
 
   function isNil(x) { return x === NIL || x === null || x === undefined; }
   function isSxTruthy(x) { return x !== false && !isNil(x); }
@@ -6547,6 +6547,16 @@ return (function() {
     return cekValue(state);
   };
 
+  // CEK stepping primitives — for debugger islands
+  PRIMITIVES["make-cek-state"] = makeCekState;
+  PRIMITIVES["cek-step"] = cekStep;
+  PRIMITIVES["cek-terminal?"] = cekTerminal_p;
+  PRIMITIVES["cek-value"] = cekValue;
+  PRIMITIVES["make-env"] = function() { return merge(PRIMITIVES); };
+  PRIMITIVES["sx-serialize"] = sxSerialize;
+  PRIMITIVES["lambda-name"] = lambdaName;
+  PRIMITIVES["callable?"] = isCallable;
+
 
   // =========================================================================
   // Async IO: Promise-aware rendering for client-side IO primitives

shared/sx/ref/platform_js.py

@@ -1508,6 +1508,16 @@ CEK_FIXUPS_JS = '''
     while (!cekTerminal_p(state)) { state = cekStep(state); }
     return cekValue(state);
   };
+
+  // CEK stepping primitives — for debugger islands
+  PRIMITIVES["make-cek-state"] = makeCekState;
+  PRIMITIVES["cek-step"] = cekStep;
+  PRIMITIVES["cek-terminal?"] = cekTerminal_p;
+  PRIMITIVES["cek-value"] = cekValue;
+  PRIMITIVES["make-env"] = function() { return merge(PRIMITIVES); };
+  PRIMITIVES["sx-serialize"] = sxSerialize;
+  PRIMITIVES["lambda-name"] = lambdaName;
+  PRIMITIVES["callable?"] = isCallable;
 '''
 
 

sx/sx/geography/cek.sx

@@ -148,6 +148,276 @@
         "lisp")))))
 
 
+;; ---------------------------------------------------------------------------
+;; CEK stepper: interactive stepping debugger
+;; ---------------------------------------------------------------------------
+
+(defisland ~geography/cek/demo-stepper (&key initial-expr)
+  (let ((source (signal (or initial-expr "(+ 1 (* 2 3))")))
+        (state (signal nil))
+        (steps (signal 0))
+        (history (signal (list)))
+        (error-msg (signal nil)))
+
+    ;; Parse and create initial CEK state
+    (define start-eval
+      (fn ()
+        (reset! error-msg nil)
+        (reset! history (list))
+        (reset! steps 0)
+        (let ((parsed (sx-parse (deref source))))
+          (if (empty? parsed)
+            (reset! error-msg "Parse error: empty expression")
+            (reset! state (make-cek-state (first parsed) (make-env) (list)))))))
+
+    ;; Single step
+    (define do-step
+      (fn ()
+        (when (and (deref state) (not (cek-terminal? (deref state))))
+          (let ((prev (deref state)))
+            (swap! history (fn (h) (append h (list prev))))
+            (swap! steps inc)
+            (reset! state (cek-step prev))))))
+
+    ;; Run to completion
+    (define do-run
+      (fn ()
+        (when (deref state)
+          (let run-loop ((n 0))
+            (when (and (not (cek-terminal? (deref state))) (< n 200))
+              (do-step)
+              (run-loop (+ n 1)))))))
+
+    ;; Reset
+    (define do-reset
+      (fn ()
+        (reset! state nil)
+        (reset! steps 0)
+        (reset! history (list))
+        (reset! error-msg nil)))
+
+    ;; Format control for display
+    (define fmt-control
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((c (get s "control")))
+            (if (nil? c) "\u2014"
+              (sx-serialize c))))))
+
+    ;; Format value
+    (define fmt-value
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((v (get s "value")))
+            (cond
+              (nil? v) "nil"
+              (callable? v) (str "\u03bb:" (or (lambda-name v) "fn"))
+              :else (sx-serialize v))))))
+
+    ;; Format kont
+    (define fmt-kont
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((k (get s "kont")))
+            (if (empty? k) "[]"
+              (str "[" (join " " (map (fn (f) (get f "type")) k)) "]"))))))
+
+    ;; Initialize on first render
+    (start-eval)
+
+    (div :class "space-y-4"
+      ;; Input
+      (div :class "flex gap-2 items-end"
+        (div :class "flex-1"
+          (label :class "text-xs text-stone-400 block mb-1" "Expression")
+          (input :type "text" :bind source
+                 :class "w-full px-3 py-1.5 rounded border border-stone-300 font-mono text-sm focus:outline-none focus:border-violet-400"
+                 :on-change (fn (e) (start-eval))))
+        (div :class "flex gap-1"
+          (button :on-click (fn (e) (start-eval))
+                  :class "px-3 py-1.5 rounded bg-stone-200 text-stone-700 text-sm hover:bg-stone-300" "Reset")
+          (button :on-click (fn (e) (do-step))
+                  :class "px-3 py-1.5 rounded bg-violet-500 text-white text-sm hover:bg-violet-600" "Step")
+          (button :on-click (fn (e) (do-run))
+                  :class "px-3 py-1.5 rounded bg-violet-700 text-white text-sm hover:bg-violet-800" "Run")))
+
+      ;; Error
+      (when (deref error-msg)
+        (div :class "text-red-600 text-sm" (deref error-msg)))
+
+      ;; Current state
+      (when (deref state)
+        (div :class "rounded border border-stone-200 bg-white p-3 font-mono text-sm space-y-1"
+          (div :class "flex gap-4"
+            (span :class "text-stone-400 w-16" "Step")
+            (span :class "font-bold" (deref steps)))
+          (div :class "flex gap-4"
+            (span :class "text-stone-400 w-16" "Phase")
+            (span :class (str "font-bold " (if (= (get (deref state) "phase") "eval") "text-blue-600" "text-green-600"))
+              (get (deref state) "phase")))
+          (div :class "flex gap-4"
+            (span :class "text-violet-500 w-16" "C")
+            (span (fmt-control (deref state))))
+          (div :class "flex gap-4"
+            (span :class "text-amber-600 w-16" "V")
+            (span (fmt-value (deref state))))
+          (div :class "flex gap-4"
+            (span :class "text-emerald-600 w-16" "K")
+            (span (fmt-kont (deref state))))
+          (when (cek-terminal? (deref state))
+            (div :class "mt-2 pt-2 border-t border-stone-200 text-stone-800 font-bold"
+              (str "Result: " (sx-serialize (cek-value (deref state))))))))
+
+      ;; Step history
+      (when (not (empty? (deref history)))
+        (div :class "rounded border border-stone-100 bg-stone-50 p-2"
+          (div :class "text-xs text-stone-400 mb-1" "History")
+          (div :class "space-y-0.5 font-mono text-xs max-h-48 overflow-y-auto"
+            (map-indexed (fn (i s)
+              (div :class "flex gap-2 text-stone-500"
+                (span :class "text-stone-300 w-6 text-right" (+ i 1))
+                (span :class (if (= (get s "phase") "eval") "text-blue-400" "text-green-400") (get s "phase"))
+                (span :class "text-violet-400 truncate" (fmt-control s))
+                (span :class "text-amber-400" (fmt-value s))
+                (span :class "text-emerald-400" (fmt-kont s))))
+              (deref history))))))))
+
+
+;; ---------------------------------------------------------------------------
+;; Render stepper: watch a component render itself
+;; ---------------------------------------------------------------------------
+
+(defisland ~geography/cek/demo-render-stepper (&key initial-expr)
+  (let ((source (signal (or initial-expr
+          "(div :class \"p-4 rounded border border-violet-200 bg-violet-50\"\n  (h2 :class \"font-bold text-violet-800\" \"Hello from CEK\")\n  (p :class \"text-stone-600\" \"This HTML was built by stepping.\"))")))
+        (state (signal nil))
+        (steps (signal 0))
+        (history (signal (list)))
+        (preview (signal ""))
+        (error-msg (signal nil)))
+
+    (define start-eval
+      (fn ()
+        (reset! error-msg nil)
+        (reset! history (list))
+        (reset! steps 0)
+        (reset! preview "")
+        (let ((parsed (sx-parse (deref source))))
+          (if (empty? parsed)
+            (reset! error-msg "Parse error")
+            (reset! state (make-cek-state (first parsed) (make-env) (list)))))))
+
+    (define do-step
+      (fn ()
+        (when (and (deref state) (not (cek-terminal? (deref state))))
+          (swap! history (fn (h) (append h (list (deref state)))))
+          (swap! steps inc)
+          (reset! state (cek-step (deref state)))
+          ;; When terminal, capture the result as HTML preview
+          (when (cek-terminal? (deref state))
+            (let ((result (cek-value (deref state))))
+              (when (string? result)
+                (reset! preview result)))))))
+
+    (define do-run
+      (fn ()
+        (when (deref state)
+          (let run-loop ((n 0))
+            (when (and (not (cek-terminal? (deref state))) (< n 500))
+              (do-step)
+              (run-loop (+ n 1)))))))
+
+    (define fmt-control
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((c (get s "control")))
+            (if (nil? c) "\u2014"
+              (let ((ser (sx-serialize c)))
+                (if (> (len ser) 80) (str (slice ser 0 77) "...") ser)))))))
+
+    (define fmt-value
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((v (get s "value")))
+            (cond
+              (nil? v) "nil"
+              (callable? v) (str "\u03bb:" (or (lambda-name v) "fn"))
+              (string? v) (if (> (len v) 60) (str (slice v 0 57) "...") v)
+              :else (sx-serialize v))))))
+
+    (define fmt-kont
+      (fn (s)
+        (if (nil? s) "\u2014"
+          (let ((k (get s "kont")))
+            (if (empty? k) "[]"
+              (str "[" (join " \u2192 " (map (fn (f) (get f "type")) k)) "]"))))))
+
+    (start-eval)
+
+    (div :class "space-y-4"
+      ;; Input
+      (div
+        (label :class "text-xs text-stone-400 block mb-1" "Component expression")
+        (textarea :bind source :rows 4
+          :class "w-full px-3 py-2 rounded border border-stone-300 font-mono text-xs focus:outline-none focus:border-violet-400"
+          :on-change (fn (e) (start-eval))))
+      (div :class "flex gap-1"
+        (button :on-click (fn (e) (start-eval))
+                :class "px-3 py-1.5 rounded bg-stone-200 text-stone-700 text-sm hover:bg-stone-300" "Reset")
+        (button :on-click (fn (e) (do-step))
+                :class "px-3 py-1.5 rounded bg-violet-500 text-white text-sm hover:bg-violet-600" "Step")
+        (button :on-click (fn (e) (do-run))
+                :class "px-3 py-1.5 rounded bg-violet-700 text-white text-sm hover:bg-violet-800" "Run"))
+
+      ;; Error
+      (when (deref error-msg)
+        (div :class "text-red-600 text-sm" (deref error-msg)))
+
+      ;; Two-pane: state + preview
+      (div :class "grid grid-cols-1 md:grid-cols-2 gap-4"
+        ;; Left: CEK state
+        (when (deref state)
+          (div :class "rounded border border-stone-200 bg-white p-3 font-mono text-xs space-y-1"
+            (div :class "text-stone-400 text-xs mb-2"
+              (str "Step " (deref steps)
+                   (if (cek-terminal? (deref state)) " \u2014 DONE" "")))
+            (div :class "flex gap-2"
+              (span :class (str "w-12 font-bold "
+                (if (= (get (deref state) "phase") "eval") "text-blue-600" "text-green-600"))
+                (get (deref state) "phase"))
+              (span :class "text-stone-500 truncate" (fmt-control (deref state))))
+            (div :class "flex gap-2"
+              (span :class "text-amber-600 w-12 font-bold" "value")
+              (span :class "text-stone-600 truncate" (fmt-value (deref state))))
+            (div :class "flex gap-2"
+              (span :class "text-emerald-600 w-12 font-bold" "kont")
+              (span :class "text-stone-500 truncate" (fmt-kont (deref state))))
+            (when (cek-terminal? (deref state))
+              (div :class "mt-2 pt-2 border-t border-stone-200 text-violet-700 font-bold text-sm"
+                "Render complete"))))
+
+        ;; Right: live HTML preview
+        (div :class "rounded border border-stone-200 bg-white p-3 min-h-24"
+          (div :class "text-xs text-stone-400 mb-2" "Live preview")
+          (if (empty? (deref preview))
+            (div :class "text-stone-300 text-sm italic" "Step to completion to see rendered output...")
+            (raw! (deref preview)))))
+
+      ;; Step history (collapsed)
+      (when (> (len (deref history)) 0)
+        (details :class "text-xs"
+          (summary :class "text-stone-400 cursor-pointer hover:text-stone-600"
+            (str (len (deref history)) " steps"))
+          (div :class "mt-1 space-y-0.5 font-mono max-h-48 overflow-y-auto"
+            (map-indexed (fn (i s)
+              (div :class "flex gap-2 text-stone-400"
+                (span :class "text-stone-300 w-4 text-right" (+ i 1))
+                (span :class (if (= (get s "phase") "eval") "text-blue-300" "text-green-300")
+                  (slice (get s "phase") 0 4))
+                (span :class "text-violet-300 flex-1 truncate" (fmt-control s))))
+              (deref history))))))))
+
+
 ;; ---------------------------------------------------------------------------
 ;; Demo page content
 ;; ---------------------------------------------------------------------------
@@ -157,39 +427,42 @@
 
     (~docs/section :title "What this demonstrates" :id "what"
       (p "These are " (strong "live islands") " evaluated by the CEK machine. Every " (code "eval-expr") " goes through " (code "cek-run") ". Every " (code "(deref sig)") " in an island creates a reactive DOM binding via continuation frames.")
-      (p "The CEK machine is defined in " (code "cek.sx") " (160 lines) and " (code "frames.sx") " (100 lines) — pure s-expressions, bootstrapped to both JavaScript and Python."))
+      (p "The CEK machine is defined in " (code "cek.sx") " and " (code "frames.sx") " — pure s-expressions, bootstrapped to both JavaScript and Python."))
+
+    (~docs/section :title "Stepper" :id "stepper"
+      (p "The CEK machine is pure data\u2192data. Each step takes a state dict and returns a new one. "
+         "Type an expression, click Step to advance one CEK transition.")
+      (~geography/cek/demo-stepper :initial-expr "(let ((x 10)) (+ x (* 2 3)))")
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-stepper") "lisp")))
+
+    (~docs/section :title "Render stepper" :id "render-stepper"
+      (p "Watch a component render itself. The CEK evaluates the expression — "
+         "when it encounters " (code "(div ...)") ", the render adapter produces HTML in one step. "
+         "Click Run to see the rendered output appear in the preview.")
+      (~geography/cek/demo-render-stepper)
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-render-stepper") "lisp")))
 
     (~docs/section :title "1. Counter" :id "demo-counter"
       (p (code "(deref count)") " in text position creates a reactive text node. " (code "(deref doubled)") " is a computed that updates when count changes.")
       (~geography/cek/demo-counter :initial 0)
-      (~docs/code :code (highlight
-        "(defisland ~demo-counter (&key initial)\n  (let ((count (signal (or initial 0)))\n        (doubled (computed (fn () (* 2 (deref count))))))\n    (div\n      (button :on-click (fn (e) (swap! count dec)) \"-\")\n      (span (deref count))\n      (button :on-click (fn (e) (swap! count inc)) \"+\")\n      (p (str \"doubled: \" (deref doubled))))))"
-        "lisp")))
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-counter") "lisp")))
 
     (~docs/section :title "2. Computed chain" :id "demo-chain"
       (p "Three levels of computed: base -> doubled -> quadrupled. Change base, all propagate.")
       (~geography/cek/demo-chain)
-      (~docs/code :code (highlight
-        "(let ((base (signal 1))\n      (doubled (computed (fn () (* (deref base) 2))))\n      (quadrupled (computed (fn () (* (deref doubled) 2)))))\n  (span (deref base))\n  (p (str \"doubled: \" (deref doubled)\n         \"  |  quadrupled: \" (deref quadrupled))))"
-        "lisp")))
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-chain") "lisp")))
 
     (~docs/section :title "3. Reactive attributes" :id "demo-attr"
       (p (code "(deref sig)") " in " (code ":class") " position. The CEK evaluates the " (code "str") " expression, and when the signal changes, the continuation re-evaluates and updates the attribute.")
       (~geography/cek/demo-reactive-attr)
-      (~docs/code :code (highlight
-        "(div :class (str \"p-3 rounded font-medium \"\n             (if (deref danger)\n               \"bg-red-100 text-red-800\"\n               \"bg-green-100 text-green-800\"))\n  (if (deref danger) \"DANGER\" \"SAFE\"))"
-        "lisp")))
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-reactive-attr") "lisp")))
 
     (~docs/section :title "4. Effect + cleanup" :id "demo-stopwatch"
       (p "Effects still work through CEK. This stopwatch uses " (code "effect") " with cleanup — toggling the signal clears the interval.")
       (~geography/cek/demo-stopwatch)
-      (~docs/code :code (highlight
-        "(effect (fn ()\n  (when (deref running)\n    (let ((id (set-interval (fn () (swap! elapsed inc)) 100)))\n      (fn () (clear-interval id))))))"
-        "lisp")))
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-stopwatch") "lisp")))
 
     (~docs/section :title "5. Batch coalescing" :id "demo-batch"
       (p "Two signals updated in " (code "batch") " — one notification cycle. Compare render counts between batch and no-batch.")
       (~geography/cek/demo-batch)
-      (~docs/code :code (highlight
-        "(batch (fn ()\n  (swap! first-sig inc)\n  (swap! second-sig inc)))\n;; One render pass, not two."
-        "lisp")))))
+      (~docs/code :code (highlight (component-source "~geography/cek/demo-batch") "lisp")))))