feat(bankai): Phase 4 follow-ups — css convention, live titles, prerender, HTTP/2, size budget

- style.css convention: <entry dir>/style.css is imported by the virtual
  client entry (CSS is a client concern; server code never sees it — the
  v8 answer to sheetify), extracted and hashed by Vite, stylesheet-linked
  in the head and preloaded via Early Hints. Counter example styled.
- SSR <title> from state: the server reads the first stream chunk before
  writing the head, by which point stores and the first render slice have
  run — DOMTitleChange emits land in the document title. Counter emits.
- bankai build --prerender /,/about renders routes through the same
  toStream path to static <route>/index.html (precompressed, precached
  by the service worker, served with Early Hints).
- bankai serve --h2: HTTP/2 with a generated local cert (openssl,
  cached; allowHTTP1) — browsers only act on Early Hints over h2/h3.
  Tested with a real h2 client observing the 103 interim response.
- npm run size: the framework wire-size budget, enforced in CI. Whole
  framework (core + html engine + morph + hydrate) is 7.97 kB min+gzip /
  7.15 kB brotli; budget 8.5 kB with the v7 '4kb' context documented
  (that number excluded the html engine, which lived in the browserify
  transform).

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

packages/bankai/lib/build.js

@@ -4,28 +4,33 @@
 //   dist/assets/*            hashed client chunks + css
 //   dist/.vite/manifest.json Vite's build manifest
 //   dist/bankai.json         bankai's route/asset metadata for serving
+//   dist/**/index.html       prerendered routes (--prerender)
 //   dist/sw.js               service worker (if <entry dir>/sw.js exists),
 //                            with the precached asset list defined in
 //   *.br / *.gz              precompressed siblings for every text asset
 
-import { readFile, writeFile, readdir, stat, access } from 'node:fs/promises'
+import { readFile, writeFile, readdir, stat, access, mkdir } from 'node:fs/promises'
 import { join, dirname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { brotliCompress, gzip, constants } from 'node:zlib'
 import { promisify } from 'node:util'
 
-import bankaiPlugin, { CLIENT_ID } from './plugin.js'
+import bankaiPlugin, { findCss, CLIENT_ID } from './plugin.js'
+import { resolveApp } from './app.js'
+import { documentHead, documentTail } from './document.js'
 
 const brotli = promisify(brotliCompress)
 const gzipP = promisify(gzip)
 
-export default async function buildApp ({ entry, outDir = 'dist', title = 'choo' }) {
+export default async function buildApp ({ entry, outDir = 'dist', title = 'choo', prerender = [] }) {
   const { build } = await import('vite')
   entry = resolve(entry)
   outDir = resolve(outDir)
+  const css = await findCss(entry)
 
   await build({
     appType: 'custom',
-    plugins: [bankaiPlugin(entry)],
+    plugins: [bankaiPlugin(entry, { css })],
     logLevel: 'warn',
     build: {
       outDir,
@@ -48,11 +53,36 @@ export default async function buildApp ({ entry, outDir = 'dist', title = 'choo'
   const meta = { title, entry, assets, builtAt: new Date().toISOString() }
   await writeFile(join(outDir, 'bankai.json'), JSON.stringify(meta, null, 2))
 
+  // static prerender: routes rendered through the same toStream path the
+  // server uses, written as <route>/index.html
+  const prerendered = []
+  if (prerender.length) {
+    const mod = await import(pathToFileURL(entry))
+    for (const route of prerender) {
+      const app = resolveApp(mod, entry)
+      const state = {}
+      let body = ''
+      const decoder = new TextDecoder()
+      for await (const chunk of app.toStream(route, state)) {
+        body += decoder.decode(chunk, { stream: true })
+      }
+      const page = documentHead({ title: state.title || title, ...assets }) + body + documentTail(state)
+      const rel = route === '/' ? 'index.html' : join(route.replace(/^\//, '').replace(/\/$/, ''), 'index.html')
+      const target = join(outDir, rel)
+      await mkdir(dirname(target), { recursive: true })
+      await writeFile(target, page)
+      prerendered.push(route)
+    }
+  }
+
   // service worker: <entry dir>/sw.js, built standalone with the asset
   // list injected — the choo-service-worker convention, manifest edition
   const swSource = join(dirname(entry), 'sw.js')
   if (await exists(swSource)) {
-    const precache = ['/', ...assets.scripts, ...assets.modulepreload, ...assets.css]
+    const precache = [
+      ...(prerendered.length ? prerendered : ['/']),
+      ...assets.scripts, ...assets.modulepreload, ...assets.css
+    ]
     await build({
       appType: 'custom',
       logLevel: 'warn',
@@ -71,7 +101,7 @@ export default async function buildApp ({ entry, outDir = 'dist', title = 'choo'
   // precompress text assets so the server never compresses at request time
   const compressed = await precompress(outDir)
 
-  return { outDir, meta, compressed }
+  return { outDir, meta, compressed, prerendered }
 }
 
 function collectCss (manifest, entryChunk) {

packages/bankai/lib/dev.js

@@ -4,17 +4,18 @@
 
 import { createServer } from 'node:http'
 
-import bankaiPlugin, { CLIENT_URL } from './plugin.js'
+import bankaiPlugin, { findCss, CLIENT_URL } from './plugin.js'
 import { resolveApp } from './app.js'
 import { documentHead, documentTail } from './document.js'
 
 export default async function dev ({ entry, port = 8080, title = 'choo' }) {
   const { createServer: createViteServer } = await import('vite')
+  const css = await findCss(entry) // style.css convention; restart to add it
 
   const vite = await createViteServer({
     appType: 'custom',
     server: { middlewareMode: true },
-    plugins: [bankaiPlugin(entry)],
+    plugins: [bankaiPlugin(entry, { css })],
     logLevel: 'warn'
   })
 
@@ -26,14 +27,22 @@ export default async function dev ({ entry, port = 8080, title = 'choo' }) {
         const app = resolveApp(mod, entry)
         const state = {}
 
+        // Read the first chunk before writing the head: by then stores
+        // have run and the view has rendered up to its first async hole,
+        // so DOMTitleChange emits have landed in state.title.
+        const reader = app.toStream(req.url, state).getReader()
+        const first = await reader.read()
+
         res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
         res.write(documentHead({
-          title,
+          title: state.title || title,
           scripts: ['/@vite/client', CLIENT_URL]
         }))
-
-        for await (const chunk of app.toStream(req.url, state)) {
-          res.write(chunk)
+        if (!first.done) res.write(first.value)
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          res.write(value)
         }
         res.end(documentTail(state))
       } catch (err) {

packages/bankai/lib/plugin.js

@@ -9,7 +9,7 @@ const RESOLVED_CLIENT_ID = '\0' + CLIENT_ID
 // middleware ('\0' encodes as '__x00__')
 export const CLIENT_URL = '/@id/__x00__' + CLIENT_ID
 
-export default function bankaiPlugin (entry) {
+export default function bankaiPlugin (entry, { css } = {}) {
   return {
     name: 'bankai',
     resolveId (id) {
@@ -18,6 +18,10 @@ export default function bankaiPlugin (entry) {
     load (id) {
       if (id === RESOLVED_CLIENT_ID) {
         return [
+          // the style.css convention: CSS is a client concern, so the
+          // client glue imports it and server code never sees it — the
+          // v8 answer to what sheetify transforms did in v9
+          ...(css ? [`import ${JSON.stringify(css)}`] : []),
           `import create from ${JSON.stringify(entry)}`,
           'const app = typeof create === "function" && !create.mount ? create() : create',
           'app.mount(app.selector || "body")'
@@ -26,3 +30,16 @@ export default function bankaiPlugin (entry) {
     }
   }
 }
+
+// <entry dir>/style.css, when it exists
+export async function findCss (entry) {
+  const { access } = await import('node:fs/promises')
+  const { join, dirname } = await import('node:path')
+  const candidate = join(dirname(entry), 'style.css')
+  try {
+    await access(candidate)
+    return candidate
+  } catch (e) {
+    return null
+  }
+}

packages/bankai/lib/serve.js

@@ -1,18 +1,26 @@
 // bankai serve — the production server. Static assets from dist
 // (precompressed variants negotiated, hashed assets cached forever);
-// everything else is a page: 103 Early Hints from the build manifest,
-// then streaming SSR of the entry module — imported natively, because
-// the server side never needed a build.
+// prerendered routes served as static HTML; everything else is a page:
+// 103 Early Hints from the build manifest, then streaming SSR of the
+// entry module — imported natively, because the server side never
+// needed a build. `h2: true` serves HTTP/2 with a generated local cert
+// (allowHTTP1 for tools) — browsers only act on Early Hints over h2/h3,
+// so production deployments want this or a fronting h2 proxy.
 
-import { createServer } from 'node:http'
+import http from 'node:http'
+import http2 from 'node:http2'
+import { execFile } from 'node:child_process'
 import { createReadStream } from 'node:fs'
-import { readFile, stat } from 'node:fs/promises'
+import { readFile, stat, mkdir } from 'node:fs/promises'
 import { join, normalize, extname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
 
 import { resolveApp } from './app.js'
 import { documentHead, documentTail, assetLinks } from './document.js'
 
+const execFileP = promisify(execFile)
+
 const MIME = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
@@ -28,13 +36,13 @@ const MIME = {
   '.ico': 'image/x-icon'
 }
 
-export default async function serve ({ outDir = 'dist', port = 8080 }) {
+export default async function serve ({ outDir = 'dist', port = 8080, h2 = false }) {
   outDir = resolve(outDir)
   const meta = JSON.parse(await readFile(join(outDir, 'bankai.json'), 'utf8'))
   const mod = await import(pathToFileURL(meta.entry))
   const links = assetLinks(meta.assets)
 
-  const server = createServer(async (req, res) => {
+  async function handler (req, res) {
     const url = new URL(req.url, 'http://localhost')
     const pathname = decodeURIComponent(url.pathname)
 
@@ -49,7 +57,14 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) {
       }
     }
 
-    // page: hints first, then stream
+    // prerendered page?
+    const prerendered = normalize(join(outDir, pathname, 'index.html'))
+    if (prerendered.startsWith(outDir) && await isFile(prerendered)) {
+      if (links.length && res.writeEarlyHints) res.writeEarlyHints({ link: links })
+      return sendFile(req, res, prerendered, pathname, { link: links.join(', ') })
+    }
+
+    // live page: hints first, then stream
     try {
       const app = resolveApp(mod, meta.entry)
       const state = {}
@@ -57,13 +72,22 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) {
       if (links.length && res.writeEarlyHints) {
         res.writeEarlyHints({ link: links })
       }
+
+      // first chunk before the head: stores + the first render slice have
+      // run by then, so state.title is populated
+      const reader = app.toStream(req.url, state).getReader()
+      const first = await reader.read()
+
       res.writeHead(200, {
         'content-type': 'text/html; charset=utf-8',
         link: links.join(', ')
       })
-      res.write(documentHead({ title: meta.title, ...meta.assets }))
-      for await (const chunk of app.toStream(req.url, state)) {
-        res.write(chunk)
+      res.write(documentHead({ title: state.title || meta.title, ...meta.assets }))
+      if (!first.done) res.write(first.value)
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        res.write(value)
       }
       res.end(documentTail(state))
     } catch (err) {
@@ -71,17 +95,46 @@ export default async function serve ({ outDir = 'dist', port = 8080 }) {
       if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain' })
       res.end('bankai: render error')
     }
-  })
+  }
+
+  let server
+  if (h2) {
+    const { key, cert } = await localCert(outDir)
+    server = http2.createSecureServer({ key, cert, allowHTTP1: true }, handler)
+  } else {
+    server = http.createServer(handler)
+  }
 
   await new Promise((resolveListen) => server.listen(port, resolveListen))
   return {
     server,
     port: server.address().port,
-    origin: `http://localhost:${server.address().port}`,
+    origin: `${h2 ? 'https' : 'http'}://localhost:${server.address().port}`,
     close: () => new Promise((resolveClose) => server.close(resolveClose))
   }
 }
 
+// self-signed localhost cert, generated once via openssl and cached
+// alongside the build (never commit dist)
+async function localCert (outDir) {
+  const dir = join(outDir, '.bankai-cert')
+  const keyPath = join(dir, 'key.pem')
+  const certPath = join(dir, 'cert.pem')
+  if (!(await isFile(keyPath)) || !(await isFile(certPath))) {
+    await mkdir(dir, { recursive: true })
+    await execFileP('openssl', [
+      'req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '365',
+      '-subj', '/CN=localhost',
+      '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1',
+      '-keyout', keyPath, '-out', certPath
+    ])
+  }
+  return {
+    key: await readFile(keyPath),
+    cert: await readFile(certPath)
+  }
+}
+
 async function isFile (path) {
   try {
     return (await stat(path)).isFile()
@@ -90,8 +143,9 @@ async function isFile (path) {
   }
 }
 
-async function sendFile (req, res, file, pathname) {
+async function sendFile (req, res, file, pathname, extraHeaders = {}) {
   const headers = {
+    ...extraHeaders,
     'content-type': MIME[extname(file)] || 'application/octet-stream',
     // hashed build assets are immutable; everything else revalidates
     'cache-control': pathname.startsWith('/assets/')