@@ -1,54 +1,71 @@
1−<meta charset="utf-8"/>
1+# `dodrio`
22
3−# 🦀🕸️ `wasm-pack-template`
3+`dodrio` is an **experimental** virtual DOM library for Rust and WebAssembly. It
4+is a proving ground for a bump allocation-based virtual DOM architecture, that I
5+believe is the best way to take advantage of WebAssembly's advantages in the
6+context of a virtual DOM library.
47
5−A template for kick starting a Rust and WebAssembly project using
6−[`wasm-pack`](https://github.com/rustwasm/wasm-pack).
8+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
710
8−This template is designed for compiling Rust libraries into WebAssembly and
9−publishing the resulting package to NPM.
1011
11−* Want to use the published NPM package in a Website? [Check out
12− `create-wasm-app`.](https://github.com/rustwasm/create-wasm-app)
13−* Want to make a monorepo-style Website without publishing to NPM? Check out
14− [`rust-webpack-template`](https://github.com/rustwasm/rust-webpack-template)
15− and/or
16− [`rust-parcel-template`](https://github.com/rustwasm/rust-parcel-template).
12+- [Warning](#warning)
13+- [Design](#design)
14+ - [Bump Allocation](#bump-allocation)
15+ - [Change List as Stack Machine](#change-list-as-stack-machine)
16+ - [Library — Not Framework](#library--not-framework)
1717
18−## 🔋 Batteries Included
18+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
1919
20−* [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) for communicating
21− between WebAssembly and JavaScript.
22−* [`console_error_panic_hook`](https://github.com/rustwasm/console_error_panic_hook)
23− for logging panic messages to the developer console.
24−* [`wee_alloc`](https://github.com/rustwasm/wee_alloc), an allocator optimized
25− for small code size.
20+## Warning
2621
27−## 🚴 Usage
22+I reiterate that `dodrio` is in a very **experimental** state. It has not
23+actually been profiled or tuned for performance yet, so while I think the design
24+should yield a very fast virtual DOM library, `dodrio` is almost certainly not
25+fast right now. Additionally, it is probably riddled with bugs, and is assuredly
26+missing features that are critical for actually building Web applications.
2827
29−### 🐑 Use `cargo generate` to Clone this Template
28+## Design
3029
31−[Learn more about `cargo generate` here.](https://github.com/ashleygwilliams/cargo-generate)
30+### Bump Allocation
3231
33−```
34−cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name my-project
35−cd my-project
36−```
32+Bump allocation is essentially the fastest method of allocating objects. It has
33+constraints, but works particularly well when allocation lifetimes match program
34+phases. And virtual DOMs are very phase oriented.
3735
38−### 🛠️ Build with `wasm-pack build`
36+`dodrio` maintains three bump allocation arenas:
3937
40−```
41−wasm-pack build
42−```
38+1. The newest, most up-to-date virtual DOM. The virtual DOM nodes themselves and
39+ any temporary containers needed while creating them are allocated into this
40+ arena.
41+2. The previous virtual DOM. This reflects the current state of the physical
42+ DOM.
43+3. The difference between (1) and (2). This is a sequence of DOM mutation
44+ operations — colloquially known as a "change list" — which if applied to
45+ the physical DOM, will make the physical DOM match (1).
4346
44−### 🔬 Test in Headless Browsers with `wasm-pack test`
47+Rendering happens as follows:
4548
46−```
47−wasm-pack test --headless --firefox
48−```
49+* The application state is rendered into bump allocation arena (1).
50+* (1) diffed with (2) to produce (3).
51+* JavaScript code applies (3) to the physical DOM.
52+* (1) and (2) are swapped, double-buffering style, and the new (1) has its bump
53+ allocation pointer reset.
54+* Rinse and repeat.
4955
50−### 🎁 Publish to NPM with `wasm-pack publish`
56+### Change List as Stack Machine
5157
52−```
53−wasm-pack publish
54−```
58+The change list that represents the difference between how the physical DOM
59+currently looks, and our ideal virtual DOM state is encoded in a tiny stack
60+machine language. A stack machine works particularly well for applying DOM
61+diffs, a task that is essentially a tree traversal.
62+
63+### Library — Not Framework
64+
65+`dodrio` is just a library. (And did I mention it is experimental?!) It is not a
66+full-fledged, complete, batteries-included solution for all frontend Web
67+development. And it never intends to become that either. Its highest ambition is
68+to prove that its bump allocation-based design is a good one, and maaaayyyyyybe
69+become a production-grade virtual DOM library that you could plug into a larger
70+application or toolkit eventually. But it will never be a complete,
71+batteries-included framework.