 ;; and produces a complete scene and an updated controller
 ;;}
 
-(defn register-ratoms-map [ratoms-map ratoms component]
-  (reduce (fn [rmap ratom]
-            (when (contains? ratoms-map ratom)
-              (throw (ex-info "Reactive atom has already a dependent parent component" {:ratom ratom
-                                                                                        :parent-component (get ratoms-map ratom)
-                                                                                        :child-component component})))
-            (assoc rmap ratom component)) ratoms-map ratoms))
-
-(defn unregister-ratoms-map [ratoms-map component]
-  (reduce (fn [rmap [ratom comp]]
-            (if (= comp component)
-              rmap
-              (assoc rmap ratom comp))) {} ratoms-map))
+;; auxiliary functions to maintain the `ratoms-map` in the component renderer
+(declare register-ratoms-map
+         unregister-ratoms-map)
 
 (defn render-component
+  "Renders the scene `component` in the context of the controller `ctrl`."
   [ctrl component]
-  (loop [elements (list component), ratoms-map {}, rendering [], rendered #{}, seen #{}, ctrl ctrl]
+  (loop [elements (list component)
+         , ratoms-map {}  ; we build a map associating each referenced ratom to the components that depend on it
+         , rendering []   ; this is finally the items to effectively render
+         , rendered #{}   ; we are careful note to render twice the same item
+         , seen #{}       ; we also track all the items we encountered
+         , ctrl ctrl]     ; the controller state is optionally updated at each step
+    ;; the loop proceeds for the component and all its subcomponents (if any)
     (if (seq elements)
       (cond
         ;; if the first element is a scene, splice it into the rest

;; just reuse its previous value.
;;}

;; CONTROLLER
;; ----------
;; Will be inside the the universe

;; (defn make-controller []
;;   (atom {:components {}}))

;; XXX: nested #(...) are not allowed ...
;; (defn register-component! [controller component]
;;   (swap! controller #(update % :components #(assoc % component {}))))

(defn register-component! [controller component]
  (swap! controller #(update % :components (fn [comps] (assoc comps component {})))))

(defn unregister-component! [controller component]

               ctrl))
      ;; no more elements to render
      [rendering rendered seen ctrl])))


(defn register-ratoms-map [ratoms-map ratoms component]
  (reduce (fn [rmap ratom]
            (when (contains? ratoms-map ratom)
              (throw (ex-info "Reactive atom has already a dependent parent component" {:ratom ratom
                                                                                        :parent-component (get ratoms-map ratom)
                                                                                        :child-component component})))
            (assoc rmap ratom component)) ratoms-map ratoms))

(defn unregister-ratoms-map [ratoms-map component]
  (reduce (fn [rmap [ratom comp]]
            (if (= comp component)
              rmap
              (assoc rmap ratom comp))) {} ratoms-map))



;;{
;; The main rendering function follows.
;;}
