docs: Phase 5 — v8 README, migration guide, deploy recipes, RFC draft

README rewritten for the v8 branch: honest size claim (7.97 kB min+gzip
for the whole framework, with the v7 '4kb' context), the zero-build
story up front, bankai v10, package map, credits to yoshuawuyts, the
choojs contributors and the pirxpilot fork line.

docs/migrating-v7-to-v8.md: the codemod path, the specifier map, and
every deliberate behavior change spelled out. docs/deploy.md: plain
Node, Docker, proxy/CDN — including the HTTP/3 answer (h3 is
infrastructure's job; bankai's contract is the 103 + Link headers that
any hints-aware edge, h3 included, propagates; server push is dead
everywhere and never existed in h3) — and web-standard runtimes.

docs/rfc.md: the draft announcement for choojs/choo — continuation
framing, pings to yoshuawuyts and pirxpilot, the npm-rights ask, API
feedback questions, and a three-week comment window with a
silence-is-consent close.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd

docs/deploy.md

@@ -0,0 +1,83 @@
+# Deploying a choo v8 + bankai v10 app
+
+The server side of a v8 app is plain ESM — there is no server bundle.
+Deploy is: ship the source + `dist/`, run a server.
+
+## Plain Node (the blessed path)
+
+```console
+$ bankai build app.js --title "my app" --prerender /
+$ bankai serve --h2 --port 443
+```
+
+`bankai serve` does static assets (immutable + precompressed), 103 Early
+Hints, streaming SSR, and `window.initialState`. `--h2` matters:
+browsers only act on Early Hints over HTTP/2 or HTTP/3. For a public
+deployment use a real certificate (the built-in one is a generated
+localhost cert) or front it with a TLS-terminating proxy.
+
+## Docker
+
+```dockerfile
+FROM node:24-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+RUN npx bankai build app.js
+EXPOSE 8080
+CMD ["npx", "bankai", "serve"]
+```
+
+## Behind a proxy / CDN (and the HTTP/3 answer)
+
+Node has no production HTTP/3 server yet (QUIC support in core is still
+experimental and not exposed as an h3 listener), and that's fine: h3 is
+infrastructure's job. Run `bankai serve` on h1 or h2 behind:
+
+- **Caddy** — serves h2 + h3 by default, forwards to bankai:
+  ```
+  example.com {
+    reverse_proxy localhost:8080
+  }
+  ```
+- **nginx ≥ 1.29** — `listen 443 quic;` for h3 plus
+  `early_hints on;`-era support for forwarding the 103.
+- **Cloudflare / Fastly** — h3 at the edge automatically; both
+  understand and propagate Early Hints (Cloudflare has since 2021).
+
+bankai's contract with these layers is just headers: it emits the 103
+interim response and repeats the `Link` header on the final response, so
+any hints-aware edge can act on them — including over h3/QUIC, where
+Early Hints work exactly as on h2. What you should *not* expect is
+HTTP/2-style server push: it's removed from Chrome and Firefox and was
+never in HTTP/3. Hints + preload is the whole story now.
+
+## Web-standard runtimes (Deno, Bun, edge)
+
+`toStream()` returns a WHATWG `ReadableStream`, so the render half needs
+no adapter at all:
+
+```js
+import createApp from './app.js'
+import { documentHead, documentTail, resolveApp } from 'bankai'
+
+export default {
+  async fetch (req) {
+    const app = createApp()
+    const state = {}
+    const url = new URL(req.url)
+    const body = app.toStream(url.pathname + url.search, state)
+    // stream the body through a TransformStream that wraps head + tail,
+    // or buffer if the route is small — your call, it's a web stream
+    return new Response(body, {
+      headers: { 'content-type': 'text/html; charset=utf-8' }
+    })
+  }
+}
+```
+
+Serve `dist/` via the platform's static hosting and reuse
+`dist/bankai.json` for the asset links. A first-class edge adapter
+(head/tail wrapping + Early Hints via the platform APIs) is on the v8
+roadmap; the primitives are deliberately already web-standard.

docs/migrating-v7-to-v8.md

@@ -0,0 +1,65 @@
+# Migrating a choo v7 app to v8
+
+The API you know is intact: `choo()`, `app.use`, `app.route`,
+`app.mount`, `app.toString`, `emit`, stores, `state.events`. What changed
+is the plumbing: ESM everywhere, new package names, no compile step, and
+a platform baseline of Node ≥ 24 + Baseline Widely Available browsers.
+
+## The fast path
+
+```console
+$ npx @choojs/migrate .          # rewrite in place
+$ npx @choojs/migrate --dry .    # or report only
+```
+
+The codemod converts simple top-level CJS to ESM, remaps specifiers, and
+prints a note for everything it won't guess at. Then:
+
+1. Add `"type": "module"` to package.json.
+2. Swap dependencies for `@choojs/core`, `@choojs/html`, and friends.
+3. Run your app. Read the console: hydration now *tells you* when server
+   and client markup disagree.
+
+## Specifier map
+
+| v7 | v8 |
+|---|---|
+| `choo` | `@choojs/core` |
+| `choo/html`, `nanohtml` | `@choojs/html` |
+| `nanohtml/raw` | `@choojs/html/raw` |
+| `nanomorph` | `@choojs/html/morph` |
+| `nanocomponent`, `choo/component` | `@choojs/component` |
+| `choo-devtools` | `@choojs/devtools` |
+| `choo-lazy-route` | `lazy()` from `@choojs/core` |
+| `nanobus`, `nanorouter`, `nanohref`, `nanotiming` | built into `@choojs/core` |
+| `nanoquery` | built in (`state.query`); use `URLSearchParams` elsewhere |
+| `nanoraf`, `nanoassert`, `nanolru` | retired — platform/built-in |
+
+## Behavior changes to know about
+
+- **URLs decode once, and never crash.** A literal `%` in a path routed
+  v7 into a `URIError`; v8 keeps the raw segment. Params are no longer
+  double-decoded (`%2540` → `%40`, not `@`). Routes and locations are
+  NFC-normalized, so `café` matches however the é was composed.
+  `state.href` is decoded for reading.
+- **Event handlers never serialize.** v7's server renderer emitted
+  `onclick=""`; v8 emits nothing — handlers are behavior, not markup.
+- **Whitespace is preserved as authored** in browser renders (v7's
+  browser transform collapsed it). Server and browser output are now
+  byte-identical, which is what makes hydration adoption work.
+- **`mount()` hydrates.** First render adopts server DOM in place and
+  warns on real mismatches; `<script>` tags and whitespace are ignored.
+- **`toString()` got stricter, `toStream()` got capable.** Sync renders
+  behave exactly as v7. Async content — `state.prefetch` promises, lazy
+  routes, promise-valued template holes — requires `toStream()`, and
+  `toString()` says so instead of misrendering.
+- **Views can't return arrays** (unchanged from v7) and document-level
+  roots (`html\`<body>…\``) work in the browser renderer too.
+
+## Things that moved to bankai
+
+sheetify → put a `style.css` next to your entry (client-only by
+construction). `split-require` → native `import()` + `lazy()`.
+`bankai start/build/serve/inspect` replace the v9 pipeline; HTTP/2 push
+never shipped and is dead in browsers — bankai v10 sends 103 Early Hints
+instead.

docs/rfc.md

@@ -0,0 +1,84 @@
+# RFC: choo v8 — same soul, modern engine
+
+> Draft, to be posted as an issue on choojs/choo. Placeholders in
+> [brackets]. Tone check before posting: continuation, not correction.
+
+---
+
+Hi everyone — long-time choo user, org member, still shipping things
+with it. I'd like to propose (and have prototyped) a v8.
+
+**The short version:** choo's design aged beautifully. The toolchain
+around it didn't — browserify, the nanohtml transform, Babel 6, Travis.
+v8 keeps the API and the philosophy and replaces every dead dependency
+with either the platform or ~300 lines we own. I've built the whole
+thing on a branch to make this a concrete conversation rather than a
+wishlist: **[link to v8 branch]**.
+
+## What stays exactly the same
+
+The 7-line counter is still the 7-line counter. `choo()`, stores,
+`emit`, tagged template views, morphing re-renders, `toString()` on the
+server. `choo()` still works without `new`. A codemod
+(`npx @choojs/migrate`) moves v7 apps across — validated against this
+repo's own example app.
+
+## What changes
+
+- **ESM only, Node ≥ 24, Baseline browsers. Zero compile steps.** The
+  nanohtml browserify transform is replaced by a runtime template cache
+  (parse once per call site, clone per render — the µhtml technique,
+  adapted to our morph-based model). Consequence: **you can develop a
+  choo app with an import map and view-source**, no tooling at all.
+- **Twelve packages become six.** nanobus/nanorouter/nanohref/nanotiming
+  fold into `@choojs/core` as attributed ports; nanoquery/nanoraf/
+  nanoassert retire to the platform. Smaller maintenance surface is the
+  point — single-maintainer fatigue is what stalled v7, and I don't want
+  to rebuild that failure mode.
+- **SSR grows up: `toStream()`.** Web-standard `ReadableStream`,
+  progressive flushing through async template holes, `state.prefetch`
+  for store data, and hydration that *adopts* server DOM and warns on
+  real mismatches. Answers the async-route question too — #653 finally
+  gets both halves: `lazy(() => import('./view.js'))` in the browser,
+  awaited by `toStream` on the server.
+- **bankai v10** — same one-command soul, rebuilt as a thin shell over
+  Vite 8/Rolldown. Only the client bundles (v8 server code runs
+  as-authored — no server build to rot). 103 Early Hints replace the
+  HTTP/2 push story, `style.css`/`sw.js` conventions replace sheetify
+  and the env-var service-worker dance, `--prerender` and `--h2`
+  included.
+- **The size claim, honestly restated.** v7 said 4kb for choo alone
+  (templates compiled away by the transform). v8's *entire* framework —
+  core + html engine + morph + hydration — is 7.97 kB min+gzip
+  / 7.15 kB brotli, enforced by CI. Apples-to-apples it's smaller;
+  the README now says the true number.
+
+Numbers, tests, and the full decision log live on the branch:
+109 unit tests (the v7 suite among them, behavior preserved) + 7
+Playwright tests in real Chromium covering hydration, streaming, and
+bankai dev/prod. Also fixed along the way: the non-ASCII/`%` URL
+crashes (routing now parses with WHATWG URL, decodes once, and
+NFC-normalizes).
+
+## What I'm asking
+
+1. **@yoshuawuyts** — a blessing costs one emoji and would mean a lot.
+   Zero obligation beyond that; the credits already say what this
+   builds on.
+2. **@pirxpilot** — your ESM fork line is the only living continuation
+   of this code and v8's core started from that groundwork. I'd love to
+   co-maintain rather than fork-in-parallel; either way, thank you.
+3. **npm publish rights** for `choo`, `bankai`, and the nano*
+   packages, or a nod to ship under `@choojs/*` with the old names as
+   deprecation pointers after 8.0.0 exists (nothing gets deprecated
+   before then; master and v7 stay untouched).
+4. **API feedback**, especially: `lazy()` wrapper vs thenable route
+   handlers; the `state.prefetch` contract; anything in the migration
+   doc that reads as a betrayal rather than an upgrade.
+
+**Comment window: three weeks from posting.** After that I'll take
+silence as consent, keep working on the v8 branch in the open, and cut
+pre-releases under a `next` tag. If this lands wrong for anyone, say so
+— the plan bends.
+
+🚂🚋🚋🚋🚋🚋

docs/v8.md

@@ -108,11 +108,23 @@ Server string rendering is on par with nanohtml v1 (~13k ops/s, within
       All proven end-to-end in real Chromium: both dev and prod pages
       hydrate with zero console errors and zero mismatch warnings, and
       the 103 interim response is asserted at the HTTP level.
-- [ ] Phase 4 follow-ups: HTTP/2 dev server with local certs (browsers
-      only act on Early Hints over h2/h3), static prerender of
-      enumerable routes, SSR `<title>` from state (needs a head hook in
-      toStream), edge-runtime deploy recipe (`new Response(toStream())`
-      — the server core is already web-standard).
+- [x] Phase 4 follow-ups: `bankai serve --h2` (local certs via openssl,
+      103 verified with a real h2 client), `bankai build --prerender`,
+      SSR `<title>` from state (the server reads the first stream chunk
+      before writing the head), the `style.css` convention (client-only
+      CSS — the sheetify answer), and the CI wire-size budget
+      (`npm run size`: 7.97 kB min+gzip for the whole framework,
+      budget 8.5 kB).
+- [x] Phase 5: README rewritten for v8 (honest size claim, credits),
+      `docs/migrating-v7-to-v8.md`, `docs/deploy.md` (Node, Docker,
+      proxy/CDN with the HTTP/3 story — h3 is infrastructure's job,
+      bankai's contract is the 103 + Link headers any hints-aware edge
+      propagates — and web-standard runtimes), and `docs/rfc.md`: the
+      draft announcement to post on choojs/choo, with the pings, the
+      asks, and the three-week comment window.
+- [ ] Post-RFC: publish pre-releases under a next tag, refresh
+      choo.io/handbook (separate repos), deprecation pointers on retired
+      packages only after 8.0.0, first-class edge adapter for bankai.
 - [ ] Phase 4: bankai v10 (Vite 8/Rolldown shell, SSR middleware,
       103 Early Hints, service worker, precompression)
 - [ ] Phase 5: docs, examples, launch