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
2026-09-08 19:41:22 +02:00
parent 99f9da1e3b
commit b957b02410
5 changed files with 340 additions and 668 deletions
@@ -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.