buuh/docs/rfc.md

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.

🚂🚋🚋🚋🚋🚋