 ;; 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:
+;; Example usage (notice the ":flush-dom" metadata):
 ;;   (dispatch ^:flush-dom  [:event-id other params])
 ;;
 ;; router loop


;; -- router loop ---------------------------------------------------------------------------------
;;
;; In a 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

;; -- lookup and call -----------------------------------------------------------------------------

(defn- handle
  "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)]
