Incorporating Tim's feedback.

foundations-high-performance-react.org

@@ -30,16 +30,14 @@ gain an understanding of the real React and how to build
 high-performance applications with it.
 
 This book is based on the first chapter of the book /High-Performance
-React/. If you enjoy /Foundations of High-Performance React
-Applications/ and you want to learn more practical ways to utilize the
-foundations we will learn here and get a more detailed blue-print for
-creating high performance React applications, then be sure to check
-out /High-Performance React/.
+React/. If you enjoy this book and you want to learn more practical
+ways to utilize the foundations we will learn here and get a more
+detailed blue-print for creating high performance React applications,
+then be sure to check out /High-Performance React/.
 
-/Foundations of High-Performance React Applications/ is not intended
-to be an introduction to React or JavaScript. While it might be useful
-to beginners, this book assumes familiarity with both JavaScript and
-React.
+This book is not intended to be an introduction to React or
+JavaScript. While it might be useful to beginners, this book assumes
+familiarity with both JavaScript and React.
 
 And while this book only specifically addresses React-DOM the
 foundations apply equally to React-Native and other React
@@ -109,11 +107,17 @@ does.
   :EXPORT_FILE_NAME: manuscript/components-of-react.markua
   :END:
 
-Conceptually React is very simple. It starts by walking a tree of
-components and building up a tree of their output. Then it compares
-that tree to the tree currently in the browser's DOM to find any
-differences between them. When it finds differences it updates the
-browser's DOM to match its internal tree.
+The primary elements that make up any React program are its
+components. A ~component~ in React maintains local state and "renders"
+output to eventually be included in the browser's DOM. A tree of
+components is then created whenever a component outputs other
+components.
+
+So, conceptually, React's core algorithm is very simple: it starts by
+walking a tree of components and building up a tree of their
+output. Then it compares that tree to the tree currently in the
+browser's DOM to find any differences between them. When it finds
+differences it updates the browser's DOM to match its internal tree.
 
 But what does that actually look like? If your app is janky does that
 explanation point you towards what is wrong? No. It might make you
@@ -291,8 +295,8 @@ are not relevant to our study here.
 
 #+BEGIN_SRC javascript
 function createElement(node) {
-   // if array (not text, number, or other primitive)
-   if (typeof node === 'object') {
+   // if array (our representation of an element)
+   if (Array.isArray(node)) {
       const [ tag, props, children ] = node;
       return {
          type: tag,
@@ -326,7 +330,7 @@ of ~elements~ (surprise).
 That's it. Now we have everything we need to actually begin the
 process of rendering our tree to the DOM!
 
-* Render
+* Render: Putting Elements on the Screen
   :PROPERTIES:
   :EXPORT_FILE_NAME: manuscript/render.markua
   :END:
@@ -403,7 +407,7 @@ tree in the browser's DOM! But so far we can only add things to our
 tree. To be able to remove and modify the tree we need one more part:
 reconciliation.
 
-* Reconciliation
+* Reconciliation, or How React Diffs
   :PROPERTIES:
   :EXPORT_FILE_NAME: manuscript/reconciliation.markua
   :END:
@@ -495,7 +499,11 @@ is the DOM element associated with our synthetic element and ~parent~
 is a reference to the parent DOM element.
 
 Here we begin by adding a global object that will store our last render
-tree, keyed by the ~container~.
+tree, keyed by the ~container~. ~container~ refers to the browser's
+DOM element that will be the parent for all of the React derived DOM
+elements. This parent DOM element can only be used to render one tree
+of elements at a time so it works well to use as a key for
+~renderTrees~.
 
 #+BEGIN_SRC javascript
 const renderTrees = {};
@@ -692,7 +700,7 @@ simulates, you'll be hitting a major performance bottleneck since
 React will not only be replacing DOM elements in the browser but also
 tearing down and rebuilding the trees of child components.
 
-* Fibers
+* Fibers: Splitting up Render
   :PROPERTIES:
   :EXPORT_FILE_NAME: manuscript/fibers.markua
   :END: