feat(core): toStream() and lazy() routes — the answer to choojs/choo#653

toStream(location, state) renders to a web-standard ReadableStream of
UTF-8 bytes: pass it to new Response() on web servers or
Readable.fromWeb().pipe(res) on Node. It awaits store prefetch promises
(state.prefetch, the pattern the #653 thread wanted standardized) and
lazy route views before rendering, then flushes template output
progressively through async holes.

lazy(loader, loadingView?) wraps a dynamic import as a route handler:
loads once, caches forever, renders the loading view (or holds the
current tree via a placeholder) while in flight, emits render on arrival.
toString() refuses lazy routes and prefetching stores with pointers to
toStream() — both halves of the async-route story ship together, unlike
the original PR.

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

packages/core/test/lazy-browser.test.js

@@ -0,0 +1,82 @@
+// Lazy routes in the browser (happy-dom): loading view while the module
+// is in flight, morph to the real view on arrival, PENDING keeps the
+// current tree during route changes, view cached after first load.
+
+import { test, before } from 'node:test'
+import assert from 'node:assert'
+import { Window } from 'happy-dom'
+
+let choo, lazy, html
+
+before(async () => {
+  const win = new Window({ url: 'http://localhost/' })
+  globalThis.window = win
+  globalThis.document = win.document
+  globalThis.requestAnimationFrame = win.requestAnimationFrame.bind(win)
+  ;({ default: choo, lazy } = await import('@choojs/core'))
+  ;({ default: html } = await import('@choojs/html/browser'))
+})
+
+const tick = (ms = 30) => new Promise((resolve) => setTimeout(resolve, ms))
+
+test('lazy route with a loading view: loading first, real view after', async () => {
+  let resolveLoader
+  const loaderDone = new Promise((resolve) => { resolveLoader = resolve })
+
+  const app = choo()
+  app.route('/', lazy(
+    () => loaderDone,
+    () => html`<div><p>loading…</p></div>`
+  ))
+
+  const tree = app.start()
+  assert.strictEqual(tree.textContent, 'loading…', 'loading view rendered while in flight')
+
+  resolveLoader({ default: (state) => html`<div><p>arrived</p></div>` })
+  await tick()
+  assert.strictEqual(tree.textContent, 'arrived', 'real view morphed in over the loading view')
+})
+
+test('lazy route without a loading view: placeholder, then wholesale replace', async () => {
+  let resolveLoader
+  const loaderDone = new Promise((resolve) => { resolveLoader = resolve })
+
+  const app = choo()
+  app.route('/', lazy(() => loaderDone))
+
+  const tree = app.start()
+  assert.ok(tree.hasAttribute('data-choo-pending'), 'placeholder holds the spot')
+  document.body.appendChild(tree)
+
+  resolveLoader({ default: (state) => html`<main><h1>real</h1></main>` })
+  await tick()
+
+  assert.strictEqual(document.querySelector('main h1').textContent, 'real', 'real view replaced the placeholder in the DOM')
+  assert.strictEqual(document.querySelector('[data-choo-pending]'), null, 'placeholder gone')
+  document.querySelector('main').remove()
+})
+
+test('loaded lazy views render synchronously ever after', async () => {
+  const view = (state) => html`<div>cached ${state.count}</div>`
+  const wrapped = lazy(() => Promise.resolve({ default: view }))
+
+  const app = choo()
+  app.use((state, emitter) => {
+    state.count = 0
+    emitter.on('bump', () => { state.count++; emitter.emit('render') })
+  })
+  app.route('/', wrapped)
+
+  // no loading view: the placeholder must live in the DOM to be replaced
+  const holder = document.createElement('section')
+  document.body.appendChild(holder)
+  holder.appendChild(app.start())
+  await tick() // let the loader resolve + re-render
+
+  assert.strictEqual(holder.textContent, 'cached 0')
+
+  app.emit('bump')
+  await tick()
+  assert.strictEqual(holder.textContent, 'cached 1', 'subsequent renders are sync through the cache')
+  holder.remove()
+})