 ;; -- lookup and call -----------------------------------------------------------------------------
 
 (defn- handle
-  "Look up the handler for the given event, then call it, passing in 2 parameters."
+  "Given an event vector, look up the right handler, then call it.
+  By default, handlers are not assumed to be pure. They are called with
+  two paramters:
+  - the `app-db` atom and
+  - the event vector
+  The handler is assumed to side-effect on the atom, the return value is ignored.
+   To write handlers that are pure functions, use the \"pure\" middleware at handler
+   registration time."
   [event-v]
   (let [event-id    (first-in-vector event-v)
         handler-fn  (get @id->fn event-id)]

;; In odd cases, we need to pause for an entire annimationFrame, to ensure that
;; the DOM is fully flushed, before then calling a handler known to hog the CPU
;; for an extended period.  In such a case, the event should be laballed with metadata
;; Example usage:
;;   (dispatch ^:flush-dom  [:event-id other params])
;;
;; router loop


;; -- router loop ---------------------------------------------------------------------------------
;;
;; In a perpretual loop, read events from the dispatch channel, and route them
;; to the right handler.
;;
;; Because handlers occupy the CPU, before each event is handled, hand
