docs(book): 📝 updated docs and added new information on a few things

Closes #46.

docs/0.3.x/en-US/SUMMARY.md

@@ -36,6 +36,7 @@
     -   [Fantoccini Basics](/docs/testing/fantoccini-basics)
     -   [Manual Testing](/docs/testing/manual)
 -   [Styling](/docs/styling)
+-   [Communicating with a Server](/docs/server-communication)
 -   [Stores](/docs/stores)
 -   [Static Exporting](/docs/exporting)
 -   [Deploying](/docs/deploying/intro)

docs/0.3.x/en-US/deploying/relative-paths.md

@@ -2,7 +2,7 @@
 
 There are many instances where you'll want to deploy a Perseus website not to the root of a domain (e.g. <https://arctic-hen7.github.io>) but to a relative path under it (e.g. <https://arctic-hen7.github.io/perseus>). This is difficult because Perseus expects all its internal assets (under the URL `/.perseus`) to be at the root of the domain. However, this is easily solved with the `PERSEUS_BASE_PATH` environment variable, which you should set to be the full URL you intend to deploy your app at.
 
-For example, if we wanted to deploy an existing app to the URL <https://arctic-hen7.github.io/perseus> (where you're reading this right now), we'd set `PERSEUS_BASE_PATH=https://arctic-hen7.github.io/perseus` before running `perseus export` (note that relative path prefixing is designed for exported apps, though it could be used for apps run with `perseus serve` as well in theory). This will tell Perseus where to expect things to be, and it will also automatically set your apps _base URI_ with the HTML `<base>` tag (if you're familiar with this, don't worry about trailing slashes, Perseus does this for you).
+For example, if we wanted to deploy an existing app to the URL <https://arctic-hen7.github.io/perseus> (where you're reading this right now), we'd set `PERSEUS_BASE_PATH=https://arctic-hen7.github.io/perseus` before running `perseus export` (note that relative path prefixing is designed for exported apps, though it could be used for apps run with `perseus serve` as well in theory). This will tell Perseus where to expect things to be, and it will also automatically set your app's _base URI_ with the HTML `<base>` tag (if you're familiar with this, don't worry about trailing slashes, Perseus does this for you).
 
 ## Code Changes
 

docs/0.3.x/en-US/server-communication.md

@@ -0,0 +1,28 @@
+# Communicating with a Server
+
+So far, we've described how to use Perseus to build powerful and performant frontend apps, but we've mostly left out the backend. If you want to fetch data from a database, authenticate users, perform server-side calculations or the like, you'll almost certainly want a backend of some kind.
+
+<details>
+<summary>Frontend? Backend?</summary>
+
+In web development, we typically refer to a project as having a *frontend*, which is the thing users see (i.e. your web app, with all its styling and the like), and a *backend*, which is a server or serverless function (see below) that performs server-side work. A classic example would be a server that communicates with a database to fetch some data, but it needs to authenticate against the database. If you're new to web dev, you might well be thinking we could just query the database from the web app, but that would mean we'd have to store the access token in our frontend code, which can be easily inspected by the user (albeit less easily with Wasm, but still definitely doable). For that reason, we communicate with a server and ask it to get the data from the database for us.
+
+Of course, a much simpler way of doing the above would be to make the database not need authentication in the first place, but the point stands.
+
+</details>
+
+## The Perseus Server
+
+Perseus has an inbuilt server that serves your app and its data, and this can be extended by your own code. However, this requires [ejecting](/docs/ejecting), which can be brittle, because you'll have to redo everything every time there's a major update.
+
+## Your Own Server
+
+Instead, it's recommended that you create a server separate from Perseus that you control completely. You might do this with [Actix Web](https://actix.rs) or similar software.
+
+### Serverless Functions
+
+In the last few years, a new technology has sprung up that allows you to run individual *functions* (which might be single API routes) whenever they're requested. Infinitely many functions can be spawned simultaneously, and none will be active if none are being requested, which significantly reduces costs and increases scalability. This is provided by services like [AWS Lambda](https://aws.amazon.com/lambda/), and can be used with Rust via [this library](https://docs.rs/netlify_lambda_http). 
+
+## Querying a Server
+
+You have a few options if you want to query a server from client-side code. You can use an high-level module, like [reqwest](https://docs.rs/reqwest) (which supports Wasm), or you can use the underlying browser Fetch API directly (which entails turning JavaScript types into Rust types). We recommend the first approach, but an example of the second can be found in the Perseus code [here](https://github.com/arctic-hen7/perseus/blob/61dac01b838df23cc0f33b0d65fcb7bf5f252770/packages/perseus/src/shell.rs#L19-L65).

docs/0.3.x/en-US/templates/metadata-modification.md

@@ -11,3 +11,11 @@ Here's an example of modifying a page's metadata (taken from [here](https://gith
 ```rust
 {{#lines_include ../../../../examples/basic/src/templates/index.rs:32:36}}
 ```
+
+## Script Loading
+
+One unfortunate caveat with Perseus' current approach to modifying the `<head>` is that any new `<script>`s you add will fail to load. This is because browsers only run new new scripts if they're appended as individual nodes, and Perseus sets the entire new `<head>` in bulk. for this reason, you should put `<script>`s at the top of the rest of your template instead. That way, they'll still load before your code, but they'll also actually load!
+
+If you really need to put a `<script>` in the `<head>` for some reason, you could append it directly using [`web_sys`](https://docs.rs/web-sys), though you should make sure that it doesn't work with the rest of your code first.
+
+Note that any scripts in your `index.html` are constant across all pages, and will load correctly.

docs/0.3.x/en-US/what-is-perseus.md

@@ -62,7 +62,16 @@ To our knowledge, the only other framework in the world right now that supports
 
 [Benchmarks show](https://rawgit.com/krausest/js-framework-benchmark/master/webdriver-ts-results/table.html) that [Sycamore](https://sycamore-rs.netlify.app) is slightly faster than [Svelte](https://svelte.dev) in places, one of the fastest JS frameworks ever. Perseus uses it and [Actix Web](https://actix.rs), one of the fastest web servers in the world. Essentially, Perseus is built on the fastest tech and is itself made to be fast.
 
-Right now, Perseus is undergoing major improvements to make it even faster and to introduce new features, like support for internationalization (making your app available in many languages) out of the box, which involves significant changes to the code. Once these are ready, benchmarks for Perseus itself will be written to show how fast Perseus really is, but right now none exist.
+The speed of web frameworks is often measured by [Lighthouse] scores, which are scores out of 100 (higher is better) that measure a whole host of things, like *total blocking time*, *first contentful paint*, and *time to interactive*. These are then aggregated into a final score and grouped into three brackets: 0-49 (slow), 50-89 (medium), and 90-100 (fast). This website, which is built with Perseus, using [static exporting](:exporting) and [size optimizations](:deploying/size), consistently scores a 100 on desktop and above 90 for mobile. You can see this for yourself [here](https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Farctic-hen7.github.io%2Fperseus%2Fen-US%2F&tab=desktop) on Google's PageSpeed Insights tool.
+
+<details>
+<summary>Why not 100 on mobile?</summary>
+
+The only issue that prevents Perseus from achieving a consistent perfect score on mobile is *total blocking time*, which measures the time between when the first content appears on the page and wehn that content is interactive. Of course, WebAssembly code is used for this part (compiled from Rust), which isn't completely optimized for yet on many mobile devices. As mobile browsers get better at parsing WebAssembly, TBT will likely decrease further from the medium range to the green range (which we see for more poerful desktop systems).
+
+</details>
+
+If you're interested in seeing how Perseus compares on speed and a number of other features to other frameworks, check out the [comparisons page](comparisons).
 
 ## How convenient is it?
 
@@ -77,7 +86,7 @@ Basically, here's your workflow:
 
 ## How stable is it?
 
-Okay, there had to be one caveat! Perseus is _very_ new, and as such can't be recommended for _production_ usage yet. However, we're aiming to get it ready for that really soon, which will hopefully include even being able to deploy Perseus with [serverless functions](https://en.wikipedia.org/wiki/Serverless_computing), the step beyond a server!
+Perseus is considered reasonably stable at this point, though it still can't be recommended for *production* usage just yet. That said, this very website is built entirely with Perseus and Sycamore, and it works pretty well!
 
 For now though, Perseus is perfect for anything that doesn't face the wider internet, like internal tools, personal projects, or the like. Just don't use it to run a nuclear power plant, okay?