Merge pull request #862 from pzuraq/docs/add-runtime-overview-docs

[DOCS] Adds runtime documentation

guides/01-introduction.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)
@@ -14,8 +14,8 @@
 # Introduction
 
 Glimmer is a flexible, low-level rendering pipeline for building a "live" DOM
-from [Handlebars][handlebars] templates that can subsequently be updated cheaply
-when data changes.
+from a superset of the [Handlebars][handlebars] templating language that can
+subsequently be updated cheaply when data changes.
 
 In addition to the basic Handlebars features such as helpers and partials,
 Glimmer also comes with built-in support for a very flexible and powerful
@@ -36,11 +36,11 @@ The code examples in this document are written in [TypeScript][typescript].
 
 ## Architecture
 
-The key insight of Glimmer is that Handlebars is a declarative programming
-language for building and updating DOM. By structuring web UI around Handlebars
-templates as the central abstraction, we can use advanced techniques from
-programming languages and compilers to significantly boost the performance of
-web applications in practice.
+The key insight of Glimmer is that templates represent a declarative programming
+language for building and updating DOM. By structuring web UI around templates
+as the central abstraction, we can use advanced techniques from programming
+languages and compilers to significantly boost the performance of web
+applications in practice.
 
 Because of this, Glimmer's architecture has more in common with compiler
 toolchains like clang/LLVM or javac/JVM than traditional JavaScript libraries.
@@ -53,8 +53,8 @@ At a high level, Glimmer is made up of two parts:
 
 ### Compiler
 
-The compiler is responsible for turning your program's Handlebars templates into
-Glimmer binary bytecode.
+The compiler is responsible for turning your program's templates into Glimmer
+binary bytecode.
 
 Because Glimmer is an optimizing compiler, it must know about all of the
 templates in a program in order to understand how they work together. This is in

guides/02-precompiler-overview.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/03-runtime-overview.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)
@@ -13,7 +13,37 @@
 
 # Runtime Overview
 
-TODO: add content here
+The Glimmer runtime takes the compiled bytecode discussed in the previous section and renders it in the browser. At a high level, the runtime begins by rendering a component tree, beginning with one root component and walking down through its templates. While doing this, it saves an optimized set of bytecodes which can be used later on when rerendering the application. These update codes ignore content which is purely static, such as DOM elements and helpers or components which have static inputs, and adds updating instructions for dynamic content.
+
+Glimmer simultaneously sets up a tree of _references_ and _validators_ for components, helpers, and values. These allow Glimmer to efficiently check if the state of a given subtree of the component hierarchy has changed, and rerender it if so.
+
+## Application Lifecycle
+
+At a high level, the runtime centers around around 3 main concepts:
+
+1. [Components](#component-glossary)
+2. [References](#reference-guide)
+3. [Validators](#validator-guide)
+
+**Components** as seen by Glimmer are a reusable unit of UI that encapsulates behavior and appearance. Because Glimmer VM is a highly configurable runtime, the exact meaning of "component" is determined by the host [environment](#environment) and one or more [component managers](#component-manager).
+
+**References** are stable objects that represents the result of a pure (side-effect-free) computation, where the result of the computation might change over time. Glimmer creates references to represent values used in templates so that they can be efficiently shared across multiple components and efficiently updated should the underlying value change.
+
+**Validators** are stable objects that provides certain guarantees about the freshness of a computation result. Validators can be combined, such that if any of a child validator's values have been changed, the parent will also be marked as changed.
+
+A Glimmer application consists of a tree of components, starting with one root component, and evaluating and rendering any references to values, helpers, and other components it may have in its template. You can think of this as the `main` component, similar to the `main` function in many programming languages. Unlike those languages however, the Glimmer VM is fairly low level and doesn't provide a convention for defining this component. This allows host environments to define their conventions and `main` component as they see fit, and render it using Glimmer's `renderMain` function.
+
+As it renders, Glimmer adds validators for every component and reference it creates. These validators are combined, such that the validator for a given  component represents the union of the validators for any references or components it contains, resulting in a tree of validators that matches the component tree.
+
+Host environments can then provide different methods for invalidating state (via the validators), such as Ember's `set()` function or `@tracked` from Glimmer.js. When rerendering, Glimmer traverses the tree of components, checking each component's validator to see if it needs to be rerendered. If so, it traverses the component's subtree, but if not, the component is skipped entirely. This results in very efficient rerenders as only the portions that have changed will be rerendered by default.
+
+[component-glossary]: ./11-glossary.md#component
+[reference-guide]: ./04-references.md
+[validator-guide]: ./05-validators.md
+
+## The Virtual Machine
+
+TODO
 
 * * *
 

guides/04-references.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/05-validators.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/06-runtime-compiler.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/07-initial-render.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/08-rerendering-updating.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/09-the-environment.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)

guides/10-optimizations.md

@@ -2,7 +2,7 @@
 
 1. [Introduction](./01-introduction.md)
 2. [Precompiler Overview](./02-precompiler-overview.md)
-3. [~~Runtime Overview~~](./03-runtime-overview.md)
+3. [Runtime Overview](./03-runtime-overview.md)
 4. [References](./04-references.md)
 5. [Validators](./05-validators.md)
 6. [~~Runtime Compiler~~](./06-runtime-compiler.md)