From 1f4775515c648e98ed26ebcf13be7b8e80023518 Mon Sep 17 00:00:00 2001
From: Claas <claas@claas.dev>
Date: Wed, 8 Jul 2026 17:47:06 +0200
Subject: [PATCH] Add generated streaming

---
 CLAUDE.md                       |  52 +++++
 Cargo.lock                      |  21 ++
 Cargo.toml                      |   8 +-
 afterglow-macros/Cargo.toml     |  14 ++
 afterglow-macros/src/lib.rs     | 330 ++++++++++++++++++++++++++++++++
 afterglow/Cargo.toml            |  16 ++
 afterglow/README.md             |  76 ++++++++
 afterglow/examples/axum_demo.rs |  86 +++++++++
 afterglow/src/escape.rs         |  45 +++++
 afterglow/src/lib.rs            |  35 ++++
 afterglow/src/node.rs           | 184 ++++++++++++++++++
 afterglow/src/render.rs         | 197 +++++++++++++++++++
 afterglow/src/shell.rs          | 186 ++++++++++++++++++
 afterglow/src/stream.rs         |  97 ++++++++++
 afterglow/tests/macro.rs        | 173 +++++++++++++++++
 afterglow/tests/streaming.rs    | 168 ++++++++++++++++
 app/src/App.tsx                 |  27 ++-
 17 files changed, 1708 insertions(+), 7 deletions(-)
 create mode 100644 CLAUDE.md
 create mode 100644 afterglow-macros/Cargo.toml
 create mode 100644 afterglow-macros/src/lib.rs
 create mode 100644 afterglow/Cargo.toml
 create mode 100644 afterglow/README.md
 create mode 100644 afterglow/examples/axum_demo.rs
 create mode 100644 afterglow/src/escape.rs
 create mode 100644 afterglow/src/lib.rs
 create mode 100644 afterglow/src/node.rs
 create mode 100644 afterglow/src/render.rs
 create mode 100644 afterglow/src/shell.rs
 create mode 100644 afterglow/src/stream.rs
 create mode 100644 afterglow/tests/macro.rs
 create mode 100644 afterglow/tests/streaming.rs

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7579509
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository layout
+
+Cargo workspace (`afterglow`, `afterglow-macros`, `supernova`, `supernovi`, `web-shove`) plus a standalone frontend in `app/` that is **not** part of the workspace.
+
+- **`afterglow/`** + **`afterglow-macros/`** — Suspense-style streaming HTML templating: trees with `Node::Pending` futures render as a shell with `<?marker>`/`<?start>…<?end>` placeholders, backfilled by streamed `<template for="N">` chunks (Chrome declarative partial updates wire format). `render_stream` fills in completion order, `render_stream_ordered` in registration order. The `html!{}` proc macro (in `afterglow-macros`) supports `@{future} else { fallback }` for async widgets. Widget futures are driven by the response stream itself — never `tokio::spawn` them, or drop-based cancellation breaks. See `afterglow/README.md` and `cargo run --example axum_demo`.
+- **`web-shove/`** — Library crate implementing Web Push from scratch: RFC 8291 message encryption (ECDH P-256 key exchange, HKDF key derivation, AES-128-GCM, `aes128gcm` content-coding header) in `src/lib.rs`, VAPID key handling in `src/vapid.rs`, and the VAPID JWT `Authorization` header in `src/authorization_header.rs`. Also has a small binary (`src/main.rs`) that generates and prints a new base64url-encoded VAPID private key. Tests use `rstest` fixtures and assert against the RFC 8291 Appendix A test vectors.
+- **`supernova/`** — Axum web server (binds `127.0.0.1:3000`). Routes: `GET /` (server-rendered page from `templates/`), `POST /signin`, `POST /notifications/subscriptions`, `POST /notifications/push`. Static files served from `supernova/public/` (includes the service worker and push-subscription JS). Depends on `web-shove` for push payload encryption. Push subscriptions are held in-memory (`Arc<Mutex<Vec<Subscription>>>` in `AppState`) — nothing is persisted yet.
+- **`supernovi/`** — Minimal scratch binary that only tests Bitwarden Secrets Manager login.
+- **`app/`** — SolidJS + Vite + Tailwind CSS v4 frontend (pnpm), currently a prototype calendar/time-grid UI in `src/App.tsx`. Its dev server proxies `/api` to the Rust server at `http://127.0.0.1:3000`.
+
+## Secrets & startup
+
+The server loads secrets from **Bitwarden Secrets Manager** at startup (`supernova/src/secrets.rs`). It needs a `.env` file (gitignored, loaded via `dotenvy` in debug builds only) with:
+
+- `BWS_TOKEN` — Bitwarden Secrets Manager access token
+- `USER_SECRET_ID`, `VAPID_PRIVATE_KEY_ID` — UUIDs of the secrets to fetch
+
+Note: `secrets::setup()` currently ends in `todo!()` after fetching, so the server panics at startup until that is finished.
+
+Auth model: single-user. `POST /signin` compares a form secret against the Bitwarden-stored user secret and sets an encrypted private session cookie (`axum-extra` `PrivateCookieJar`); the cookie key is regenerated on every server start.
+
+## Commands
+
+### Rust (run from repo root)
+
+```bash
+cargo check                          # type-check workspace
+cargo clippy --all-targets           # lint
+cargo test                           # all tests (most live in web-shove)
+cargo test -p web-shove can_create_nonce   # single test by name
+cargo run -p supernova               # run the server
+```
+
+`bacon` is configured (`bacon.toml`) for watch-mode development: `bacon dev` runs the supernova server with kill-then-restart on change; `bacon test` and `bacon clippy-all` (bound to `c`) are also set up.
+
+### Frontend (`app/`, uses pnpm)
+
+```bash
+pnpm dev            # dev server at http://localhost:5173, proxies /api to :3000
+pnpm build          # tsc -b && vite build
+pnpm format         # oxfmt (format:check to verify)
+```
+
+The frontend has no test runner or linter configured; `tsc -b` (via `pnpm build`) is the type check.
+
+### Server-rendered CSS (`supernova/`)
+
+The `supernova` crate has its own `package.json`: `pnpm start` runs the Tailwind CLI to compile `app.css` into `public/app.css` for the server-rendered templates.
diff --git a/Cargo.lock b/Cargo.lock
index 75ad9ba..70f4f60 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -45,6 +45,27 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "afterglow"
+version = "0.1.0"
+dependencies = [
+ "afterglow-macros",
+ "async-stream",
+ "axum 0.8.9",
+ "bytes",
+ "futures",
+ "tokio",
+]
+
+[[package]]
+name = "afterglow-macros"
+version = "0.1.0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "ahash"
 version = "0.8.12"
diff --git a/Cargo.toml b/Cargo.toml
index e7160d5..e52644b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,3 +1,9 @@
 [workspace]
 resolver = "2"
-members = ["supernova", "supernovi", "web-shove"]
+members = [
+    "afterglow",
+    "afterglow-macros",
+    "supernova",
+    "supernovi",
+    "web-shove",
+]
diff --git a/afterglow-macros/Cargo.toml b/afterglow-macros/Cargo.toml
new file mode 100644
index 0000000..aee48ea
--- /dev/null
+++ b/afterglow-macros/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "afterglow-macros"
+version = "0.1.0"
+edition = "2024"
+description = "html! templating macro for the afterglow crate."
+license = "Apache-2.0"
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1"
+quote = "1"
+syn = { version = "2", features = ["full"] }
diff --git a/afterglow-macros/src/lib.rs b/afterglow-macros/src/lib.rs
new file mode 100644
index 0000000..bbae4c5
--- /dev/null
+++ b/afterglow-macros/src/lib.rs
@@ -0,0 +1,330 @@
+//! Proc-macro backend for the `afterglow` crate. Use `afterglow::html!`, not
+//! this crate directly.
+
+use proc_macro2::{Delimiter, Span, TokenStream, TokenTree};
+use quote::quote;
+
+/// JSX-like templating macro producing an `afterglow::Node`.
+///
+/// # Syntax
+///
+/// - **Elements**: `<div class="card">...</div>`, self-closing `<br/>`. Tag
+///   and attribute names may contain hyphens (`data-id`, `my-widget`).
+/// - **Attributes**: `name="literal"`, `name={expr}` (the expression is
+///   converted with `ToString` and escaped on render), or bare boolean
+///   attributes like `disabled`.
+/// - **Text**: string literals in child position, escaped on render:
+///   `<p>"a < b"</p>`.
+/// - **Interpolation**: `{expr}` in child position converts the expression
+///   via `afterglow::Render` (strings and numbers render as escaped text).
+/// - **Async widgets**: `@{expr}` where `expr` is a future. Renders a
+///   `<?marker id="N">` placeholder in the shell; the resolved value is
+///   converted via `Render` (so `Result<impl Render, E: Display>` works and
+///   an `Err` renders as an error slot).
+/// - **Fallback form**: `@{expr} else { <span>"loading…"</span> }` renders
+///   the fallback markup between `<?start id="N">` and `<?end>` until the
+///   future resolves. The fallback may itself contain `@{...}` widgets.
+///
+/// # Example
+///
+/// ```ignore
+/// let page = html! {
+///     <main>
+///         <h1>{title}</h1>
+///         @{load_articles()} else { <p class="spinner">"loading…"</p> }
+///     </main>
+/// };
+/// ```
+#[proc_macro]
+pub fn html(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    match Parser::new(input.into()).parse_root() {
+        Ok(output) => output.into(),
+        Err(error) => error.to_compile_error().into(),
+    }
+}
+
+struct Parser {
+    tokens: Vec<TokenTree>,
+    position: usize,
+}
+
+impl Parser {
+    fn new(stream: TokenStream) -> Self {
+        Parser {
+            tokens: stream.into_iter().collect(),
+            position: 0,
+        }
+    }
+
+    fn peek(&self) -> Option<&TokenTree> {
+        self.tokens.get(self.position)
+    }
+
+    fn peek_second(&self) -> Option<&TokenTree> {
+        self.tokens.get(self.position + 1)
+    }
+
+    fn advance(&mut self) -> Option<TokenTree> {
+        let token = self.tokens.get(self.position).cloned();
+        if token.is_some() {
+            self.position += 1;
+        }
+        token
+    }
+
+    fn error_here(&self, message: &str) -> syn::Error {
+        let span = self
+            .peek()
+            .map(TokenTree::span)
+            .or_else(|| self.tokens.last().map(TokenTree::span))
+            .unwrap_or_else(Span::call_site);
+        syn::Error::new(span, message)
+    }
+
+    fn expect_punct(&mut self, expected: char) -> syn::Result<()> {
+        match self.peek() {
+            Some(TokenTree::Punct(punct)) if punct.as_char() == expected => {
+                self.advance();
+                Ok(())
+            }
+            _ => Err(self.error_here(&format!("expected `{expected}`"))),
+        }
+    }
+
+    fn peek_is_punct(&self, expected: char) -> bool {
+        matches!(self.peek(), Some(TokenTree::Punct(punct)) if punct.as_char() == expected)
+    }
+
+    fn parse_root(mut self) -> syn::Result<TokenStream> {
+        let nodes = self.parse_nodes()?;
+        if self.peek().is_some() {
+            return Err(self.error_here("unexpected token after markup"));
+        }
+        Ok(combine_nodes(nodes))
+    }
+
+    /// Parses child nodes until a closing tag (`</`) or end of input. The
+    /// closing tag itself is left for the caller.
+    fn parse_nodes(&mut self) -> syn::Result<Vec<TokenStream>> {
+        let mut nodes = Vec::new();
+        loop {
+            match self.peek() {
+                None => break,
+                Some(TokenTree::Punct(punct)) if punct.as_char() == '<' => {
+                    let closing = matches!(
+                        self.peek_second(),
+                        Some(TokenTree::Punct(second)) if second.as_char() == '/'
+                    );
+                    if closing {
+                        break;
+                    }
+                    nodes.push(self.parse_element()?);
+                }
+                Some(TokenTree::Literal(_)) => nodes.push(self.parse_text()?),
+                Some(TokenTree::Group(group)) if group.delimiter() == Delimiter::Brace => {
+                    nodes.push(self.parse_interpolation()?);
+                }
+                Some(TokenTree::Punct(punct)) if punct.as_char() == '@' => {
+                    nodes.push(self.parse_pending()?);
+                }
+                Some(_) => {
+                    return Err(self.error_here(
+                        "expected an element, a quoted string, `{expr}`, or `@{future}`",
+                    ));
+                }
+            }
+        }
+        Ok(nodes)
+    }
+
+    /// Parses `name` or `name-with-dashes` (used for tags and attributes).
+    fn parse_name(&mut self) -> syn::Result<(String, Span)> {
+        let Some(TokenTree::Ident(ident)) = self.peek() else {
+            return Err(self.error_here("expected a name"));
+        };
+        let span = ident.span();
+        let mut name = ident.to_string();
+        self.advance();
+
+        while self.peek_is_punct('-') {
+            let Some(TokenTree::Ident(ident)) = self.peek_second() else {
+                return Err(self.error_here("expected a name segment after `-`"));
+            };
+            name.push('-');
+            name.push_str(&ident.to_string());
+            self.advance();
+            self.advance();
+        }
+
+        Ok((name, span))
+    }
+
+    fn parse_element(&mut self) -> syn::Result<TokenStream> {
+        self.expect_punct('<')?;
+        let (tag, tag_span) = self.parse_name()?;
+
+        let mut attributes = Vec::new();
+        loop {
+            match self.peek() {
+                Some(TokenTree::Punct(punct)) if punct.as_char() == '/' => {
+                    self.advance();
+                    self.expect_punct('>')?;
+                    return Ok(build_element(&tag, attributes, Vec::new()));
+                }
+                Some(TokenTree::Punct(punct)) if punct.as_char() == '>' => {
+                    self.advance();
+                    break;
+                }
+                Some(TokenTree::Ident(_)) => attributes.push(self.parse_attribute()?),
+                _ => return Err(self.error_here("expected an attribute name, `/>`, or `>`")),
+            }
+        }
+
+        let children = self.parse_nodes()?;
+
+        self.expect_punct('<')?;
+        self.expect_punct('/')?;
+        let (closing_tag, closing_span) = self.parse_name()?;
+        if closing_tag != tag {
+            let mut error = syn::Error::new(
+                closing_span,
+                format!("mismatched closing tag `</{closing_tag}>`; expected `</{tag}>`"),
+            );
+            error.combine(syn::Error::new(tag_span, "element opened here"));
+            return Err(error);
+        }
+        self.expect_punct('>')?;
+
+        Ok(build_element(&tag, attributes, children))
+    }
+
+    fn parse_attribute(&mut self) -> syn::Result<TokenStream> {
+        let (name, _) = self.parse_name()?;
+
+        let value = if self.peek_is_punct('=') {
+            self.advance();
+            match self.advance() {
+                Some(TokenTree::Literal(literal)) => {
+                    let syn::Lit::Str(string) = syn::Lit::new(literal.clone()) else {
+                        return Err(syn::Error::new(
+                            literal.span(),
+                            "attribute values must be string literals or `{expr}`",
+                        ));
+                    };
+                    quote! {
+                        ::std::option::Option::Some(::std::string::String::from(#string))
+                    }
+                }
+                Some(TokenTree::Group(group)) if group.delimiter() == Delimiter::Brace => {
+                    let expression: syn::Expr = syn::parse2(group.stream())?;
+                    quote! {
+                        ::std::option::Option::Some(
+                            ::std::string::ToString::to_string(&(#expression)),
+                        )
+                    }
+                }
+                _ => {
+                    return Err(
+                        self.error_here("expected a string literal or `{expr}` after `=`")
+                    );
+                }
+            }
+        } else {
+            quote! { ::std::option::Option::None }
+        };
+
+        Ok(quote! { (::std::borrow::Cow::Borrowed(#name), #value) })
+    }
+
+    fn parse_text(&mut self) -> syn::Result<TokenStream> {
+        let Some(TokenTree::Literal(literal)) = self.advance() else {
+            unreachable!("parse_text is only called when peeking a literal");
+        };
+        let syn::Lit::Str(string) = syn::Lit::new(literal.clone()) else {
+            return Err(syn::Error::new(
+                literal.span(),
+                "text content must be a quoted string; interpolate other values with `{expr}`",
+            ));
+        };
+        Ok(quote! { ::afterglow::Node::text(#string) })
+    }
+
+    fn parse_interpolation(&mut self) -> syn::Result<TokenStream> {
+        let Some(TokenTree::Group(group)) = self.advance() else {
+            unreachable!("parse_interpolation is only called when peeking a brace group");
+        };
+        let expression: syn::Expr = syn::parse2(group.stream())?;
+        Ok(quote! { ::afterglow::Render::into_node(#expression) })
+    }
+
+    /// Parses `@{future}` with an optional `else { fallback markup }`.
+    fn parse_pending(&mut self) -> syn::Result<TokenStream> {
+        self.expect_punct('@')?;
+        let Some(TokenTree::Group(group)) = self.peek() else {
+            return Err(self.error_here("expected `{future}` after `@`"));
+        };
+        if group.delimiter() != Delimiter::Brace {
+            return Err(self.error_here("expected `{future}` after `@`"));
+        }
+        let Some(TokenTree::Group(group)) = self.advance() else {
+            unreachable!("peeked above");
+        };
+        let expression: syn::Expr = syn::parse2(group.stream())?;
+
+        let fallback = match self.peek() {
+            Some(TokenTree::Ident(ident)) if ident == "else" => {
+                self.advance();
+                let Some(TokenTree::Group(group)) = self.peek() else {
+                    return Err(self.error_here("expected `{ fallback markup }` after `else`"));
+                };
+                if group.delimiter() != Delimiter::Brace {
+                    return Err(self.error_here("expected `{ fallback markup }` after `else`"));
+                }
+                let Some(TokenTree::Group(group)) = self.advance() else {
+                    unreachable!("peeked above");
+                };
+                let mut fallback_parser = Parser::new(group.stream());
+                let nodes = fallback_parser.parse_nodes()?;
+                if fallback_parser.peek().is_some() {
+                    return Err(fallback_parser.error_here("unexpected token in fallback markup"));
+                }
+                Some(combine_nodes(nodes))
+            }
+            _ => None,
+        };
+
+        Ok(match fallback {
+            None => quote! {
+                ::afterglow::Node::pending(async move { (#expression).await })
+            },
+            Some(fallback) => quote! {
+                ::afterglow::Node::pending_with_fallback(
+                    async move { (#expression).await },
+                    #fallback,
+                )
+            },
+        })
+    }
+}
+
+fn combine_nodes(mut nodes: Vec<TokenStream>) -> TokenStream {
+    match nodes.len() {
+        0 => quote! { ::afterglow::Node::Fragment(::std::vec::Vec::new()) },
+        1 => nodes.pop().expect("length checked above"),
+        _ => quote! { ::afterglow::Node::fragment(::std::vec![#(#nodes),*]) },
+    }
+}
+
+fn build_element(
+    tag: &str,
+    attributes: Vec<TokenStream>,
+    children: Vec<TokenStream>,
+) -> TokenStream {
+    quote! {
+        ::afterglow::Node::element(
+            #tag,
+            ::std::vec![#(#attributes),*],
+            ::std::vec![#(#children),*],
+        )
+    }
+}
diff --git a/afterglow/Cargo.toml b/afterglow/Cargo.toml
new file mode 100644
index 0000000..2d35cea
--- /dev/null
+++ b/afterglow/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "afterglow"
+version = "0.1.0"
+edition = "2024"
+description = "Suspense-style streaming HTML rendering: emit a shell immediately, backfill pending subtrees as their futures resolve."
+license = "Apache-2.0"
+
+[dependencies]
+afterglow-macros = { path = "../afterglow-macros" }
+async-stream = "0.3"
+bytes = "1"
+futures = "0.3"
+
+[dev-dependencies]
+axum = "0.8.9"
+tokio = { version = "1.52.1", features = ["macros", "rt-multi-thread", "time", "test-util"] }
diff --git a/afterglow/README.md b/afterglow/README.md
new file mode 100644
index 0000000..0eb030d
--- /dev/null
+++ b/afterglow/README.md
@@ -0,0 +1,76 @@
+# afterglow
+
+Suspense-style streaming HTML rendering for Rust servers. Render trees where
+some subtrees are futures: the renderer emits a **shell** immediately with
+placeholder markers for the pending parts, then streams filled-in content as
+each future resolves. The wire format is the one from Chrome's
+[declarative partial updates](https://developer.chrome.com/blog/declarative-partial-updates)
+feature: `<?marker id="N">` / `<?start id="N">fallback<?end>` placeholders,
+filled later by `<template for="N">...</template>` blocks.
+
+This is a one-shot streaming model — no client-side state, no re-renders.
+Write the parts you have now, backfill the rest as they arrive.
+
+## Example
+
+```rust
+use afterglow::{html, render_stream};
+
+async fn weather() -> Result<Node, &'static str> { /* slow fetch */ }
+
+let page = html! {
+    <section>
+        <h2>"Weather"</h2>
+        @{weather()} else { <p>"checking the sky…"</p> }
+    </section>
+};
+
+// impl Stream<Item = io::Result<Bytes>> — feed it straight into
+// axum::body::Body::from_stream with content-type text/html; charset=utf-8.
+let body = render_stream(page);
+```
+
+- `@{future}` renders a bare `<?marker id="N">` placeholder; add
+  `else { markup }` for fallback content between `<?start id="N">` and
+  `<?end>`.
+- Async widgets return `Result<impl Render, E: Display>`; an `Err` renders as
+  `<span class="afterglow-error">…</span>` in the slot instead of killing the
+  stream.
+- `render_stream` fills slots in **completion order**;
+  `render_stream_ordered` fills in **registration order** (deterministic, for
+  snapshot tests). Resolved subtrees may contain further `@{...}` widgets —
+  nesting is unbounded.
+- Cancellation is free: dropping the stream (client disconnect) drops all
+  pending widget futures. For that to work, **never `tokio::spawn` widget
+  futures** — let the render stream drive them.
+
+## Streaming demo
+
+```sh
+cargo run --example axum_demo
+```
+
+then, in another terminal:
+
+```sh
+curl --no-buffer localhost:3210/
+```
+
+`--no-buffer` makes curl print each chunk as it arrives. You will see the
+shell immediately:
+
+```html
+<html><head><title>afterglow demo</title></head><body><h1>Dashboard</h1>
+<section><h2>Weather</h2><?start id="0"><p>checking the sky…</p><?end></section>
+<section><h2>News</h2><?start id="1"><p>fetching headlines…</p><?end></section>
+<section><h2>Stocks</h2><?marker id="2"></section></body></html>
+```
+
+followed by the widget fills as their (artificial) delays elapse, in
+completion order:
+
+```html
+<template for="0"><p>21 °C, clear skies</p></template>          <!-- t+0.8s -->
+<template for="2"><span class="afterglow-error">stock service unavailable</span></template>  <!-- t+1.5s -->
+<template for="1"><ul><li>Streaming HTML lands in afterglow</li>…</ul></template>  <!-- t+2.5s -->
+```
diff --git a/afterglow/examples/axum_demo.rs b/afterglow/examples/axum_demo.rs
new file mode 100644
index 0000000..3ec9549
--- /dev/null
+++ b/afterglow/examples/axum_demo.rs
@@ -0,0 +1,86 @@
+//! Streaming HTML demo. Run with:
+//!
+//! ```sh
+//! cargo run --example axum_demo
+//! curl --no-buffer localhost:3210/
+//! ```
+//!
+//! The shell arrives immediately with spinners; the widget `<template>`
+//! chunks trickle in over the next ~2.5 seconds.
+
+use std::net::Ipv4Addr;
+use std::time::Duration;
+
+use axum::Router;
+use axum::body::Body;
+use axum::http::header;
+use axum::response::{IntoResponse, Response};
+use axum::routing::get;
+use tokio::time::sleep;
+
+use afterglow::{Node, html, render_stream};
+
+async fn weather() -> Result<Node, &'static str> {
+    sleep(Duration::from_millis(800)).await;
+    Ok(html! { <p>"21 °C, clear skies"</p> })
+}
+
+async fn news() -> Result<Node, &'static str> {
+    sleep(Duration::from_millis(2500)).await;
+    Ok(html! {
+        <ul>
+            <li>"Streaming HTML lands in afterglow"</li>
+            <li>"Shell rendered " {2500} "ms before this item"</li>
+        </ul>
+    })
+}
+
+async fn stock_ticker() -> Result<Node, &'static str> {
+    sleep(Duration::from_millis(1500)).await;
+    // Widgets can fail without taking down the response: this renders as an
+    // error slot inside its placeholder.
+    Err("stock service unavailable")
+}
+
+async fn index() -> Response {
+    let page = html! {
+        <html>
+            <head><title>"afterglow demo"</title></head>
+            <body>
+                <h1>"Dashboard"</h1>
+                <section>
+                    <h2>"Weather"</h2>
+                    @{weather()} else { <p>"checking the sky…"</p> }
+                </section>
+                <section>
+                    <h2>"News"</h2>
+                    @{news()} else { <p>"fetching headlines…"</p> }
+                </section>
+                <section>
+                    <h2>"Stocks"</h2>
+                    @{stock_ticker()}
+                </section>
+            </body>
+        </html>
+    };
+
+    (
+        [(header::CONTENT_TYPE, "text/html; charset=utf-8")],
+        Body::from_stream(render_stream(page)),
+    )
+        .into_response()
+}
+
+#[tokio::main]
+async fn main() {
+    let app = Router::new().route("/", get(index));
+    let listener = tokio::net::TcpListener::bind((Ipv4Addr::LOCALHOST, 3210))
+        .await
+        .unwrap();
+
+    println!(
+        "listening on http://{} — try: curl --no-buffer localhost:3210/",
+        listener.local_addr().unwrap()
+    );
+    axum::serve(listener, app).await.unwrap();
+}
diff --git a/afterglow/src/escape.rs b/afterglow/src/escape.rs
new file mode 100644
index 0000000..2f433c0
--- /dev/null
+++ b/afterglow/src/escape.rs
@@ -0,0 +1,45 @@
+/// Escapes text content: `&`, `<`, `>`.
+pub(crate) fn escape_text(input: &str, out: &mut String) {
+    for character in input.chars() {
+        match character {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            character => out.push(character),
+        }
+    }
+}
+
+/// Escapes attribute values: text escapes plus both quote characters, so the
+/// value is safe inside single- or double-quoted attributes.
+pub(crate) fn escape_attribute(input: &str, out: &mut String) {
+    for character in input.chars() {
+        match character {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '"' => out.push_str("&quot;"),
+            '\'' => out.push_str("&#39;"),
+            character => out.push(character),
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn escapes_text_metacharacters() {
+        let mut out = String::new();
+        escape_text("a < b && c > \"d\"", &mut out);
+        assert_eq!("a &lt; b &amp;&amp; c &gt; \"d\"", out);
+    }
+
+    #[test]
+    fn escapes_attribute_quotes() {
+        let mut out = String::new();
+        escape_attribute("say \"hi\" & 'bye' <now>", &mut out);
+        assert_eq!("say &quot;hi&quot; &amp; &#39;bye&#39; &lt;now&gt;", out);
+    }
+}
diff --git a/afterglow/src/lib.rs b/afterglow/src/lib.rs
new file mode 100644
index 0000000..391da74
--- /dev/null
+++ b/afterglow/src/lib.rs
@@ -0,0 +1,35 @@
+//! Suspense-style streaming HTML rendering.
+//!
+//! Render trees where some subtrees are futures ([`Node::Pending`]). The
+//! renderer emits a "shell" immediately with placeholder markers for the
+//! pending subtrees, then streams filled-in content as each future resolves,
+//! using the wire format from Chrome's declarative partial updates feature:
+//! `<?marker id="N">` / `<?start id="N">fallback<?end>` placeholders, filled
+//! later by `<template for="N">...</template>` blocks.
+//!
+//! This is a one-shot streaming model, not a reactive or resumable one: write
+//! the parts you have now, backfill the rest as they arrive.
+//!
+//! # Cancellation
+//!
+//! Widget futures are driven inside the returned stream and are dropped when
+//! the stream is dropped (for example when the client disconnects and the
+//! server drops the response body). To keep that free cancellation, do **not**
+//! `tokio::spawn` widget futures and hand their `JoinHandle`s to the tree —
+//! spawned tasks detach from drop-based cancellation and keep running after
+//! the response is gone.
+
+// Allows macro-generated `::afterglow::...` paths to resolve inside this
+// crate's own tests and examples.
+extern crate self as afterglow;
+
+mod escape;
+mod node;
+mod render;
+mod shell;
+mod stream;
+
+pub use afterglow_macros::html;
+pub use node::{Node, Render};
+pub use render::render_to_string;
+pub use stream::{render_stream, render_stream_ordered};
diff --git a/afterglow/src/node.rs b/afterglow/src/node.rs
new file mode 100644
index 0000000..286fef7
--- /dev/null
+++ b/afterglow/src/node.rs
@@ -0,0 +1,184 @@
+use std::borrow::Cow;
+use std::fmt::Display;
+
+use futures::future::BoxFuture;
+
+/// An attribute name paired with its value. `None` renders as a bare
+/// (boolean) attribute, e.g. `disabled`.
+pub type Attribute = (Cow<'static, str>, Option<String>);
+
+/// A tree of HTML content where subtrees may still be pending futures.
+pub enum Node {
+    /// Pre-escaped HTML written to the output verbatim. All `Html` content is
+    /// assumed trusted / already escaped (the `html!` macro only produces
+    /// escaped content; use [`Node::raw`] deliberately).
+    Html(String),
+    /// Text content, escaped when rendered.
+    Text(String),
+    /// An element with attributes and children. Void elements (`br`, `img`,
+    /// ...) render without a closing tag and their children are ignored.
+    Element {
+        tag: Cow<'static, str>,
+        attributes: Vec<Attribute>,
+        children: Vec<Node>,
+    },
+    /// A sequence of nodes with no wrapper element.
+    Fragment(Vec<Node>),
+    /// A subtree that is not available yet. The shell renders the `fallback`
+    /// (or a bare marker if there is none) and the resolved node is streamed
+    /// later. The resolved node may itself contain further `Pending` nodes.
+    Pending {
+        future: BoxFuture<'static, Node>,
+        fallback: Option<Box<Node>>,
+    },
+}
+
+impl Node {
+    /// Creates a raw, pre-escaped HTML node. The content is written verbatim;
+    /// the caller is responsible for it being safe.
+    pub fn raw(html: impl Into<String>) -> Node {
+        Node::Html(html.into())
+    }
+
+    /// Creates a text node; the content is escaped when rendered.
+    pub fn text(text: impl Into<String>) -> Node {
+        Node::Text(text.into())
+    }
+
+    /// Creates an element node.
+    pub fn element(
+        tag: impl Into<Cow<'static, str>>,
+        attributes: Vec<Attribute>,
+        children: Vec<Node>,
+    ) -> Node {
+        Node::Element {
+            tag: tag.into(),
+            attributes,
+            children,
+        }
+    }
+
+    /// Creates a fragment node from anything renderable.
+    pub fn fragment(children: Vec<Node>) -> Node {
+        Node::Fragment(children)
+    }
+
+    /// Creates a pending node without fallback content; the shell renders a
+    /// bare `<?marker id="N">` in its place.
+    ///
+    /// The future is driven by the render stream itself and dropped with it —
+    /// do not `tokio::spawn` it (see the crate docs on cancellation).
+    pub fn pending<F, T>(future: F) -> Node
+    where
+        F: Future<Output = T> + Send + 'static,
+        T: Render,
+    {
+        Node::Pending {
+            future: Box::pin(async move { future.await.into_node() }),
+            fallback: None,
+        }
+    }
+
+    /// Creates a pending node with fallback content; the shell renders
+    /// `<?start id="N">fallback<?end>` in its place. The fallback may itself
+    /// contain further pending nodes.
+    pub fn pending_with_fallback<F, T>(future: F, fallback: Node) -> Node
+    where
+        F: Future<Output = T> + Send + 'static,
+        T: Render,
+    {
+        Node::Pending {
+            future: Box::pin(async move { future.await.into_node() }),
+            fallback: Some(Box::new(fallback)),
+        }
+    }
+}
+
+/// Conversion into a [`Node`]. This is what interpolated values in the `html!`
+/// macro and async widget results go through.
+pub trait Render {
+    fn into_node(self) -> Node;
+}
+
+impl Render for Node {
+    fn into_node(self) -> Node {
+        self
+    }
+}
+
+impl Render for String {
+    fn into_node(self) -> Node {
+        Node::Text(self)
+    }
+}
+
+impl Render for &str {
+    fn into_node(self) -> Node {
+        Node::Text(self.to_owned())
+    }
+}
+
+impl Render for Cow<'_, str> {
+    fn into_node(self) -> Node {
+        Node::Text(self.into_owned())
+    }
+}
+
+impl Render for char {
+    fn into_node(self) -> Node {
+        Node::Text(self.to_string())
+    }
+}
+
+impl Render for () {
+    fn into_node(self) -> Node {
+        Node::Fragment(Vec::new())
+    }
+}
+
+macro_rules! impl_render_via_display {
+    ($($type:ty),+ $(,)?) => {
+        $(
+            impl Render for $type {
+                fn into_node(self) -> Node {
+                    Node::Text(self.to_string())
+                }
+            }
+        )+
+    };
+}
+
+impl_render_via_display!(
+    bool, i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize, f32, f64
+);
+
+impl<T: Render> Render for Vec<T> {
+    fn into_node(self) -> Node {
+        Node::Fragment(self.into_iter().map(Render::into_node).collect())
+    }
+}
+
+impl<T: Render> Render for Option<T> {
+    fn into_node(self) -> Node {
+        match self {
+            Some(value) => value.into_node(),
+            None => Node::Fragment(Vec::new()),
+        }
+    }
+}
+
+/// Async widgets return `Result<impl Render, E>`; an `Err` renders as an
+/// error slot instead of panicking the stream, so one failed widget cannot
+/// take down the whole response.
+impl<T: Render, E: Display> Render for Result<T, E> {
+    fn into_node(self) -> Node {
+        match self {
+            Ok(value) => value.into_node(),
+            Err(error) => Node::element(
+                "span",
+                vec![(Cow::Borrowed("class"), Some("afterglow-error".to_owned()))],
+                vec![Node::text(error.to_string())],
+            ),
+        }
+    }
+}
diff --git a/afterglow/src/render.rs b/afterglow/src/render.rs
new file mode 100644
index 0000000..31cf7c6
--- /dev/null
+++ b/afterglow/src/render.rs
@@ -0,0 +1,197 @@
+use crate::escape::{escape_attribute, escape_text};
+use crate::node::{Attribute, Node, Render};
+
+/// Elements that never have a closing tag; their children are ignored.
+const VOID_ELEMENTS: &[&str] = &[
+    "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source",
+    "track", "wbr",
+];
+
+pub(crate) fn is_void_element(tag: &str) -> bool {
+    VOID_ELEMENTS.contains(&tag)
+}
+
+pub(crate) fn write_open_tag(tag: &str, attributes: &[Attribute], out: &mut String) {
+    out.push('<');
+    out.push_str(tag);
+    for (name, value) in attributes {
+        out.push(' ');
+        out.push_str(name);
+        if let Some(value) = value {
+            out.push_str("=\"");
+            escape_attribute(value, out);
+            out.push('"');
+        }
+    }
+    out.push('>');
+}
+
+pub(crate) fn write_close_tag(tag: &str, out: &mut String) {
+    out.push_str("</");
+    out.push_str(tag);
+    out.push('>');
+}
+
+/// Renders a fully resolved tree to a string.
+///
+/// # Panics
+///
+/// Panics if the tree contains a [`Node::Pending`] node — those need the
+/// streaming renderer (`render_stream`).
+pub fn render_to_string(root: impl Render) -> String {
+    let mut out = String::new();
+    write_resolved(root.into_node(), &mut out);
+    out
+}
+
+fn write_resolved(node: Node, out: &mut String) {
+    match node {
+        Node::Html(html) => out.push_str(&html),
+        Node::Text(text) => escape_text(&text, out),
+        Node::Element {
+            tag,
+            attributes,
+            children,
+        } => {
+            write_open_tag(&tag, &attributes, out);
+            if !is_void_element(&tag) {
+                for child in children {
+                    write_resolved(child, out);
+                }
+                write_close_tag(&tag, out);
+            }
+        }
+        Node::Fragment(children) => {
+            for child in children {
+                write_resolved(child, out);
+            }
+        }
+        Node::Pending { .. } => {
+            panic!("render_to_string cannot render Node::Pending; use render_stream instead")
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use std::borrow::Cow;
+
+    use super::*;
+
+    fn attr(name: &'static str, value: &str) -> Attribute {
+        (Cow::Borrowed(name), Some(value.to_owned()))
+    }
+
+    #[test]
+    fn renders_nested_elements() {
+        let tree = Node::element(
+            "div",
+            vec![attr("class", "outer")],
+            vec![
+                Node::element(
+                    "ul",
+                    vec![],
+                    vec![
+                        Node::element("li", vec![], vec![Node::text("one")]),
+                        Node::element("li", vec![], vec![Node::text("two")]),
+                    ],
+                ),
+                Node::text("tail"),
+            ],
+        );
+
+        assert_eq!(
+            "<div class=\"outer\"><ul><li>one</li><li>two</li></ul>tail</div>",
+            render_to_string(tree)
+        );
+    }
+
+    #[test]
+    fn escapes_text_content() {
+        let tree = Node::element(
+            "p",
+            vec![],
+            vec![Node::text("<script>alert(1)</script> & more")],
+        );
+
+        assert_eq!(
+            "<p>&lt;script&gt;alert(1)&lt;/script&gt; &amp; more</p>",
+            render_to_string(tree)
+        );
+    }
+
+    #[test]
+    fn escapes_attribute_values() {
+        let tree = Node::element("input", vec![attr("value", "\"quoted\" & <tagged>")], vec![]);
+
+        assert_eq!(
+            "<input value=\"&quot;quoted&quot; &amp; &lt;tagged&gt;\">",
+            render_to_string(tree)
+        );
+    }
+
+    #[test]
+    fn renders_boolean_attributes_bare() {
+        let tree = Node::element(
+            "input",
+            vec![attr("type", "checkbox"), (Cow::Borrowed("checked"), None)],
+            vec![],
+        );
+
+        assert_eq!("<input type=\"checkbox\" checked>", render_to_string(tree));
+    }
+
+    #[test]
+    fn renders_empty_children() {
+        assert_eq!(
+            "<div></div>",
+            render_to_string(Node::element("div", vec![], vec![]))
+        );
+        assert_eq!("", render_to_string(Node::Fragment(Vec::new())));
+    }
+
+    #[test]
+    fn void_elements_have_no_closing_tag() {
+        let tree = Node::element(
+            "div",
+            vec![],
+            vec![Node::element("br", vec![], vec![]), Node::text("after")],
+        );
+
+        assert_eq!("<div><br>after</div>", render_to_string(tree));
+    }
+
+    #[test]
+    fn raw_html_is_written_verbatim() {
+        let tree = Node::fragment(vec![Node::raw("<b>bold</b>"), Node::text("<i>")]);
+
+        assert_eq!("<b>bold</b>&lt;i&gt;", render_to_string(tree));
+    }
+
+    #[test]
+    fn render_trait_converts_common_types() {
+        assert_eq!("42", render_to_string(42));
+        assert_eq!("a&amp;b", render_to_string("a&b"));
+        assert_eq!("", render_to_string(Option::<&str>::None));
+        assert_eq!(
+            "onetwo",
+            render_to_string(vec![Node::text("one"), Node::text("two")])
+        );
+    }
+
+    #[test]
+    fn err_result_renders_error_slot() {
+        let result: Result<&str, &str> = Err("db timeout & <panic>");
+
+        assert_eq!(
+            "<span class=\"afterglow-error\">db timeout &amp; &lt;panic&gt;</span>",
+            render_to_string(result)
+        );
+    }
+
+    #[test]
+    #[should_panic(expected = "cannot render Node::Pending")]
+    fn pending_nodes_panic_in_sync_render() {
+        render_to_string(Node::pending(futures::future::ready(Node::text("late"))));
+    }
+}
diff --git a/afterglow/src/shell.rs b/afterglow/src/shell.rs
new file mode 100644
index 0000000..dc5cb57
--- /dev/null
+++ b/afterglow/src/shell.rs
@@ -0,0 +1,186 @@
+use futures::future::BoxFuture;
+
+use crate::escape::escape_text;
+use crate::node::Node;
+use crate::render::{is_void_element, write_close_tag, write_open_tag};
+
+pub(crate) type SlotId = u64;
+
+/// The synchronous part of a render pass: everything already resolved is in
+/// `html` (with placeholder markers where `Pending` nodes were), and the
+/// extracted futures wait in `slots` to be driven by the stream.
+pub(crate) struct Shell {
+    pub(crate) html: String,
+    pub(crate) slots: Vec<(SlotId, BoxFuture<'static, Node>)>,
+}
+
+/// Renders a tree without awaiting anything. Each `Pending` node gets a
+/// unique id from `next_id` and renders as `<?marker id="N">` (no fallback)
+/// or `<?start id="N">fallback<?end>`; its future is pulled out into the
+/// returned queue. Fallbacks are walked too, so a pending node nested inside
+/// another pending node's fallback is registered as its own slot.
+pub(crate) fn render_shell(node: Node, next_id: &mut SlotId) -> Shell {
+    let mut shell = Shell {
+        html: String::new(),
+        slots: Vec::new(),
+    };
+    write_shell(node, next_id, &mut shell);
+    shell
+}
+
+fn write_shell(node: Node, next_id: &mut SlotId, shell: &mut Shell) {
+    match node {
+        Node::Html(html) => shell.html.push_str(&html),
+        Node::Text(text) => escape_text(&text, &mut shell.html),
+        Node::Element {
+            tag,
+            attributes,
+            children,
+        } => {
+            write_open_tag(&tag, &attributes, &mut shell.html);
+            if !is_void_element(&tag) {
+                for child in children {
+                    write_shell(child, next_id, shell);
+                }
+                write_close_tag(&tag, &mut shell.html);
+            }
+        }
+        Node::Fragment(children) => {
+            for child in children {
+                write_shell(child, next_id, shell);
+            }
+        }
+        Node::Pending { future, fallback } => {
+            let id = *next_id;
+            *next_id += 1;
+            shell.slots.push((id, future));
+            match fallback {
+                None => {
+                    shell.html.push_str(&format!("<?marker id=\"{id}\">"));
+                }
+                Some(fallback) => {
+                    shell.html.push_str(&format!("<?start id=\"{id}\">"));
+                    write_shell(*fallback, next_id, shell);
+                    shell.html.push_str("<?end>");
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use futures::FutureExt;
+    use futures::future::ready;
+
+    use super::*;
+
+    #[test]
+    fn single_pending_node_renders_marker_and_queues_future() {
+        let tree = Node::element(
+            "div",
+            vec![],
+            vec![Node::pending(ready(Node::text("late")))],
+        );
+
+        let mut next_id = 0;
+        let shell = render_shell(tree, &mut next_id);
+
+        assert_eq!("<div><?marker id=\"0\"></div>", shell.html);
+        assert_eq!(1, shell.slots.len());
+        assert_eq!(0, shell.slots[0].0);
+        assert_eq!(1, next_id);
+    }
+
+    #[test]
+    fn queued_future_resolves_to_the_wrapped_node() {
+        let tree = Node::pending(ready(Node::text("late & escaped")));
+
+        let mut next_id = 0;
+        let mut shell = render_shell(tree, &mut next_id);
+
+        let (_, future) = shell.slots.pop().unwrap();
+        let resolved = future
+            .now_or_never()
+            .expect("ready future should resolve immediately");
+        assert_eq!("late &amp; escaped", crate::render_to_string(resolved));
+    }
+
+    #[test]
+    fn sibling_pending_nodes_get_distinct_ids() {
+        let tree = Node::element(
+            "div",
+            vec![],
+            vec![
+                Node::pending(ready(Node::text("a"))),
+                Node::text("between"),
+                Node::pending(ready(Node::text("b"))),
+                Node::pending(ready(Node::text("c"))),
+            ],
+        );
+
+        let mut next_id = 0;
+        let shell = render_shell(tree, &mut next_id);
+
+        assert_eq!(
+            "<div><?marker id=\"0\">between<?marker id=\"1\"><?marker id=\"2\"></div>",
+            shell.html
+        );
+        let ids: Vec<_> = shell.slots.iter().map(|(id, _)| *id).collect();
+        assert_eq!(vec![0, 1, 2], ids);
+    }
+
+    #[test]
+    fn fallback_renders_between_start_and_end_markers() {
+        let tree = Node::pending_with_fallback(
+            ready(Node::text("content")),
+            Node::element("span", vec![], vec![Node::text("loading…")]),
+        );
+
+        let mut next_id = 0;
+        let shell = render_shell(tree, &mut next_id);
+
+        assert_eq!(
+            "<?start id=\"0\"><span>loading…</span><?end>",
+            shell.html
+        );
+        assert_eq!(1, shell.slots.len());
+    }
+
+    #[test]
+    fn pending_nested_inside_fallback_registers_its_own_slot() {
+        let tree = Node::pending_with_fallback(
+            ready(Node::text("outer content")),
+            Node::element(
+                "div",
+                vec![],
+                vec![
+                    Node::text("outer fallback with "),
+                    Node::pending(ready(Node::text("inner content"))),
+                ],
+            ),
+        );
+
+        let mut next_id = 0;
+        let shell = render_shell(tree, &mut next_id);
+
+        assert_eq!(
+            "<?start id=\"0\"><div>outer fallback with <?marker id=\"1\"></div><?end>",
+            shell.html
+        );
+        let ids: Vec<_> = shell.slots.iter().map(|(id, _)| *id).collect();
+        assert_eq!(vec![0, 1], ids);
+    }
+
+    #[test]
+    fn tree_without_pending_nodes_produces_empty_queue() {
+        let tree = Node::element("p", vec![], vec![Node::text("done")]);
+
+        let mut next_id = 0;
+        let shell = render_shell(tree, &mut next_id);
+
+        assert_eq!("<p>done</p>", shell.html);
+        assert!(shell.slots.is_empty());
+        assert_eq!(0, next_id);
+    }
+}
diff --git a/afterglow/src/stream.rs b/afterglow/src/stream.rs
new file mode 100644
index 0000000..23f6ab2
--- /dev/null
+++ b/afterglow/src/stream.rs
@@ -0,0 +1,97 @@
+use std::collections::BTreeMap;
+use std::io;
+
+use async_stream::stream;
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use futures::stream::{FuturesUnordered, Stream, StreamExt};
+
+use crate::node::{Node, Render};
+use crate::shell::{Shell, SlotId, render_shell};
+
+/// A slot's future tagged with its id so we know which placeholder to fill.
+type TaggedFuture = BoxFuture<'static, (SlotId, Node)>;
+
+fn tag(id: SlotId, future: BoxFuture<'static, Node>) -> TaggedFuture {
+    Box::pin(async move { (id, future.await) })
+}
+
+fn template_chunk(id: SlotId, html: &str) -> Bytes {
+    Bytes::from(format!("<template for=\"{id}\">{html}</template>"))
+}
+
+/// Renders `root` as a byte stream: the shell (with placeholder markers for
+/// pending subtrees) is yielded first, then each resolved subtree is yielded
+/// as a `<template for="N">...</template>` chunk **in completion order** —
+/// whichever future resolves first is streamed first.
+///
+/// Resolved subtrees may themselves contain pending nodes; those are
+/// registered as new slots and filled by later chunks, to any nesting depth.
+///
+/// Dropping the stream (e.g. because the client disconnected) drops all
+/// still-pending widget futures — cancellation is free as long as widget
+/// futures are not `tokio::spawn`ed (see the crate docs).
+///
+/// The stream never yields `Err`; the item type is `io::Result<Bytes>` so it
+/// can feed `axum::body::Body::from_stream` directly.
+pub fn render_stream(root: impl Render) -> impl Stream<Item = io::Result<Bytes>> + Send + 'static {
+    let root = root.into_node();
+    stream! {
+        let mut next_id: SlotId = 0;
+        let shell = render_shell(root, &mut next_id);
+        let mut pending: FuturesUnordered<TaggedFuture> = shell
+            .slots
+            .into_iter()
+            .map(|(id, future)| tag(id, future))
+            .collect();
+
+        yield Ok(Bytes::from(shell.html));
+
+        while let Some((id, node)) = pending.next().await {
+            let Shell { html, slots } = render_shell(node, &mut next_id);
+            for (new_id, future) in slots {
+                pending.push(tag(new_id, future));
+            }
+            yield Ok(template_chunk(id, &html));
+        }
+    }
+}
+
+/// Like [`render_stream`], but fills slots **in registration order** (slot 0
+/// first, then 1, ...) regardless of which future resolves first. Futures
+/// still run concurrently; completed chunks are buffered until it is their
+/// turn. Useful for deterministic snapshot testing.
+///
+/// Slots registered by resolved subtrees always get higher ids than the slot
+/// that produced them, so waiting for ids in ascending order cannot deadlock.
+pub fn render_stream_ordered(
+    root: impl Render,
+) -> impl Stream<Item = io::Result<Bytes>> + Send + 'static {
+    let root = root.into_node();
+    stream! {
+        let mut next_id: SlotId = 0;
+        let shell = render_shell(root, &mut next_id);
+        let mut pending: FuturesUnordered<TaggedFuture> = shell
+            .slots
+            .into_iter()
+            .map(|(id, future)| tag(id, future))
+            .collect();
+
+        yield Ok(Bytes::from(shell.html));
+
+        let mut buffered: BTreeMap<SlotId, String> = BTreeMap::new();
+        let mut emit_next: SlotId = 0;
+        while let Some((id, node)) = pending.next().await {
+            let Shell { html, slots } = render_shell(node, &mut next_id);
+            for (new_id, future) in slots {
+                pending.push(tag(new_id, future));
+            }
+            buffered.insert(id, html);
+
+            while let Some(html) = buffered.remove(&emit_next) {
+                yield Ok(template_chunk(emit_next, &html));
+                emit_next += 1;
+            }
+        }
+    }
+}
diff --git a/afterglow/tests/macro.rs b/afterglow/tests/macro.rs
new file mode 100644
index 0000000..40def01
--- /dev/null
+++ b/afterglow/tests/macro.rs
@@ -0,0 +1,173 @@
+//! Verifies `html!` expansion produces trees matching what the earlier
+//! phases' tests built by hand, by comparing rendered output.
+
+use std::io;
+use std::time::Duration;
+
+use bytes::Bytes;
+use futures::stream::{Stream, StreamExt};
+use tokio::time::sleep;
+
+use afterglow::{Node, Render, html, render_stream, render_to_string};
+
+async fn collect_chunks(stream: impl Stream<Item = io::Result<Bytes>>) -> Vec<String> {
+    stream
+        .map(|chunk| String::from_utf8(chunk.unwrap().to_vec()).unwrap())
+        .collect()
+        .await
+}
+
+#[test]
+fn elements_attributes_and_text_match_hand_built_tree() {
+    let by_macro = html! {
+        <div class="outer" data-count="3">
+            <ul>
+                <li>"one"</li>
+                <li>"two"</li>
+            </ul>
+            "tail"
+            <br/>
+        </div>
+    };
+
+    let by_hand = Node::element(
+        "div",
+        vec![
+            ("class".into(), Some("outer".to_owned())),
+            ("data-count".into(), Some("3".to_owned())),
+        ],
+        vec![
+            Node::element(
+                "ul",
+                vec![],
+                vec![
+                    Node::element("li", vec![], vec![Node::text("one")]),
+                    Node::element("li", vec![], vec![Node::text("two")]),
+                ],
+            ),
+            Node::text("tail"),
+            Node::element("br", vec![], vec![]),
+        ],
+    );
+
+    assert_eq!(render_to_string(by_hand), render_to_string(by_macro));
+}
+
+#[test]
+fn interpolated_expressions_are_escaped() {
+    let name = "Ada <script>";
+    let count = 2 + 2;
+
+    let tree = html! {
+        <p title={format!("{name}!")}>{name} " has " {count} " items"</p>
+    };
+
+    assert_eq!(
+        "<p title=\"Ada &lt;script&gt;!\">Ada &lt;script&gt; has 4 items</p>",
+        render_to_string(tree)
+    );
+}
+
+#[test]
+fn boolean_attributes_render_bare() {
+    let tree = html! { <input type="checkbox" checked/> };
+
+    assert_eq!("<input type=\"checkbox\" checked>", render_to_string(tree));
+}
+
+#[test]
+fn empty_macro_renders_nothing() {
+    assert_eq!("", render_to_string(html! {}));
+}
+
+#[test]
+fn multiple_top_level_nodes_form_a_fragment() {
+    let tree = html! {
+        <dt>"term"</dt>
+        <dd>"definition"</dd>
+    };
+
+    assert_eq!("<dt>term</dt><dd>definition</dd>", render_to_string(tree));
+}
+
+struct Article {
+    title: String,
+}
+
+impl Render for Article {
+    fn into_node(self) -> Node {
+        html! { <article><h2>{self.title}</h2></article> }
+    }
+}
+
+async fn load_article() -> Result<Article, std::convert::Infallible> {
+    sleep(Duration::from_millis(10)).await;
+    Ok(Article {
+        title: "Streaming HTML".to_owned(),
+    })
+}
+
+async fn load_score() -> u32 {
+    sleep(Duration::from_millis(20)).await;
+    9001
+}
+
+#[tokio::test(start_paused = true)]
+async fn async_widgets_stream_through_the_phase_3_driver() {
+    let page = html! {
+        <main>
+            @{load_article()} else { <p class="spinner">"loading article…"</p> }
+            <aside>"score: " @{load_score()}</aside>
+        </main>
+    };
+
+    let chunks = collect_chunks(render_stream(page)).await;
+
+    assert_eq!(
+        vec![
+            "<main><?start id=\"0\"><p class=\"spinner\">loading article…</p><?end>\
+             <aside>score: <?marker id=\"1\"></aside></main>",
+            "<template for=\"0\"><article><h2>Streaming HTML</h2></article></template>",
+            "<template for=\"1\">9001</template>",
+        ],
+        chunks
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn failing_widget_written_with_macro_renders_error_slot() {
+    async fn broken() -> Result<Node, &'static str> {
+        sleep(Duration::from_millis(5)).await;
+        Err("upstream unavailable")
+    }
+
+    let page = html! { <div>@{broken()}</div> };
+
+    let chunks = collect_chunks(render_stream(page)).await;
+
+    assert_eq!(
+        vec![
+            "<div><?marker id=\"0\"></div>",
+            "<template for=\"0\"><span class=\"afterglow-error\">upstream unavailable</span></template>",
+        ],
+        chunks
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn pending_widget_inside_fallback_matches_hand_built_tree() {
+    let by_macro = html! {
+        @{load_score()} else { <span>"waiting for " @{load_score()}</span> }
+    };
+
+    let chunks = collect_chunks(render_stream(by_macro)).await;
+
+    assert_eq!(
+        vec![
+            "<?start id=\"0\"><span>waiting for <?marker id=\"1\"></span><?end>",
+            "<template for=\"0\">9001</template>",
+            "<template for=\"1\">9001</template>",
+        ],
+        chunks
+    );
+}
diff --git a/afterglow/tests/streaming.rs b/afterglow/tests/streaming.rs
new file mode 100644
index 0000000..acc97d3
--- /dev/null
+++ b/afterglow/tests/streaming.rs
@@ -0,0 +1,168 @@
+use std::io;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+
+use bytes::Bytes;
+use futures::stream::{Stream, StreamExt};
+use tokio::time::sleep;
+
+use afterglow::{Node, render_stream, render_stream_ordered};
+
+async fn delayed(milliseconds: u64, text: &'static str) -> Node {
+    sleep(Duration::from_millis(milliseconds)).await;
+    Node::text(text)
+}
+
+/// A tree with three pending slots resolving after different delays:
+/// slot 0 → 30ms, slot 1 → 10ms, slot 2 → 20ms.
+fn three_slot_tree() -> Node {
+    Node::element(
+        "div",
+        vec![],
+        vec![
+            Node::pending(delayed(30, "slowest")),
+            Node::pending(delayed(10, "fastest")),
+            Node::pending(delayed(20, "middle")),
+        ],
+    )
+}
+
+async fn collect_chunks(stream: impl Stream<Item = io::Result<Bytes>>) -> Vec<String> {
+    stream
+        .map(|chunk| String::from_utf8(chunk.unwrap().to_vec()).unwrap())
+        .collect()
+        .await
+}
+
+#[tokio::test(start_paused = true)]
+async fn render_stream_fills_slots_in_completion_order() {
+    let chunks = collect_chunks(render_stream(three_slot_tree())).await;
+
+    assert_eq!(
+        vec![
+            "<div><?marker id=\"0\"><?marker id=\"1\"><?marker id=\"2\"></div>",
+            "<template for=\"1\">fastest</template>",
+            "<template for=\"2\">middle</template>",
+            "<template for=\"0\">slowest</template>",
+        ],
+        chunks
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn render_stream_ordered_fills_slots_in_registration_order() {
+    let chunks = collect_chunks(render_stream_ordered(three_slot_tree())).await;
+
+    assert_eq!(
+        vec![
+            "<div><?marker id=\"0\"><?marker id=\"1\"><?marker id=\"2\"></div>",
+            "<template for=\"0\">slowest</template>",
+            "<template for=\"1\">fastest</template>",
+            "<template for=\"2\">middle</template>",
+        ],
+        chunks
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn nested_pending_nodes_are_registered_and_filled() {
+    // The outer slot resolves to a subtree that itself contains a pending
+    // node — the driver must register it as a new slot and fill it later.
+    let tree = Node::pending_with_fallback(
+        async {
+            sleep(Duration::from_millis(10)).await;
+            Node::element(
+                "section",
+                vec![],
+                vec![
+                    Node::text("outer resolved, inner "),
+                    Node::pending(delayed(10, "inner resolved")),
+                ],
+            )
+        },
+        Node::text("loading outer…"),
+    );
+
+    let chunks = collect_chunks(render_stream(tree)).await;
+
+    assert_eq!(
+        vec![
+            "<?start id=\"0\">loading outer…<?end>",
+            "<template for=\"0\"><section>outer resolved, inner <?marker id=\"1\"></section></template>",
+            "<template for=\"1\">inner resolved</template>",
+        ],
+        chunks
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn failed_widget_renders_error_slot_without_killing_the_stream() {
+    let tree = Node::element(
+        "div",
+        vec![],
+        vec![
+            Node::pending(async {
+                sleep(Duration::from_millis(10)).await;
+                Result::<Node, &str>::Err("widget exploded")
+            }),
+            Node::pending(delayed(20, "still fine")),
+        ],
+    );
+
+    let chunks = collect_chunks(render_stream(tree)).await;
+
+    assert_eq!(
+        vec![
+            "<div><?marker id=\"0\"><?marker id=\"1\"></div>",
+            "<template for=\"0\"><span class=\"afterglow-error\">widget exploded</span></template>",
+            "<template for=\"1\">still fine</template>",
+        ],
+        chunks
+    );
+}
+
+/// Records on drop whether the future it lives in ever completed.
+struct DropGuard {
+    dropped: Arc<AtomicBool>,
+    completed: Arc<AtomicBool>,
+}
+
+impl Drop for DropGuard {
+    fn drop(&mut self) {
+        self.dropped.store(true, Ordering::SeqCst);
+    }
+}
+
+#[tokio::test]
+async fn dropping_the_stream_cancels_pending_widget_futures() {
+    let dropped = Arc::new(AtomicBool::new(false));
+    let completed = Arc::new(AtomicBool::new(false));
+
+    let guard = DropGuard {
+        dropped: Arc::clone(&dropped),
+        completed: Arc::clone(&completed),
+    };
+    let tree = Node::pending(async move {
+        futures::future::pending::<()>().await;
+        guard.completed.store(true, Ordering::SeqCst);
+        Node::text("unreachable")
+    });
+
+    let mut stream = Box::pin(render_stream(tree));
+    let shell = stream.next().await.expect("shell chunk").unwrap();
+    assert_eq!(Bytes::from("<?marker id=\"0\">"), shell);
+    // The widget future is now owned by the stream and still pending.
+    assert!(!dropped.load(Ordering::SeqCst));
+
+    drop(stream);
+
+    assert!(
+        dropped.load(Ordering::SeqCst),
+        "widget future must be dropped with the stream"
+    );
+    assert!(
+        !completed.load(Ordering::SeqCst),
+        "widget future must have been cancelled, not run to completion"
+    );
+}
diff --git a/app/src/App.tsx b/app/src/App.tsx
index ed8b562..9432790 100644
--- a/app/src/App.tsx
+++ b/app/src/App.tsx
@@ -111,8 +111,12 @@ function App() {
                 }}
               >
                 <time class="row-span-full block">
-                  <span>{weekday}</span>
-                  <span class="block">{date.toLocaleString(undefined, { day: "2-digit" })}</span>
+                  <span class="block text-end text-xl font-semibold tracking-wide text-slate-50">
+                    {weekday}
+                  </span>
+                  <span class="block text-end text-5xl font-bold tracking-tight text-slate-50">
+                    {date.toLocaleString(undefined, { day: "2-digit" })}
+                  </span>
                 </time>
                 <For each={item.entries}>
                   {([from, to]) => {
@@ -121,10 +125,21 @@ function App() {
 
                     const duration = toTime.since(fromTime);
                     return (
-                      <section class="col-start-2">
-                        <input type="time" value={from} step="900" />
-                        <input type="time" value={to} step="900" />
-                        <time>
+                      <section class="col-start-2 flex max-h-min items-center gap-2 text-lg">
+                        <input
+                          type="time"
+                          value={from}
+                          step="900"
+                          class="rounded-4xl bg-slate-50/75 py-1 pr-1.5 pl-3"
+                        />
+                        <span class="font-black text-slate-50">&ndash;</span>
+                        <input
+                          type="time"
+                          value={to}
+                          step="900"
+                          class="rounded-4xl bg-slate-50/75 py-1 pr-1.5 pl-3"
+                        />
+                        <time class="rounded-4xl bg-slate-50/75 px-3 py-1">
                           {duration.toLocaleString(undefined, {
                             style: "digital",
                             hours: "2-digit",
-- 
2.51.2