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/cli.js

@@ -9,6 +9,9 @@
 //   bankai inspect         size report for the built output
 //
 // options: --port <n>  --out <dir>  --title <text>
+//          --prerender </,/about>  (build: comma-separated routes)
+//          --h2                    (serve: HTTP/2 + local cert, so
+//                                   browsers act on the Early Hints)
 
 import { parseArgs } from 'node:util'
 
@@ -17,7 +20,9 @@ const { values, positionals } = parseArgs({
   options: {
     port: { type: 'string' },
     out: { type: 'string', default: 'dist' },
-    title: { type: 'string', default: 'choo' }
+    title: { type: 'string', default: 'choo' },
+    prerender: { type: 'string' },
+    h2: { type: 'boolean', default: false }
   }
 })
 
@@ -33,11 +38,13 @@ try {
   } else if (command === 'build') {
     requireEntry(entry)
     const { default: build } = await import('./lib/build.js')
-    const { outDir, compressed } = await build({ entry, outDir: values.out, title: values.title })
-    console.log(`bankai: built to ${outDir} (${compressed} asset(s) precompressed) — bankai serve to run it`)
+    const prerender = values.prerender ? values.prerender.split(',').map((r) => r.trim()).filter(Boolean) : []
+    const { outDir, compressed, prerendered } = await build({ entry, outDir: values.out, title: values.title, prerender })
+    const extra = prerendered.length ? `, ${prerendered.length} route(s) prerendered` : ''
+    console.log(`bankai: built to ${outDir} (${compressed} asset(s) precompressed${extra}) — bankai serve to run it`)
   } else if (command === 'serve') {
     const { default: serve } = await import('./lib/serve.js')
-    const { origin } = await serve({ outDir: values.out, port })
+    const { origin } = await serve({ outDir: values.out, port, h2: values.h2 })
     console.log(`bankai: production server on ${origin}`)
   } else if (command === 'inspect') {
     const { default: inspect } = await import('./lib/inspect.js')

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/')

packages/bankai/test/build-serve.test.js

@@ -16,11 +16,11 @@ import serve from '../lib/serve.js'
 const repo = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
 const entry = join(repo, 'examples', 'counter', 'app.js')
 
-let outDir, meta, srv
+let outDir, meta, prerendered, srv
 
 before(async () => {
   outDir = await mkdtemp(join(tmpdir(), 'bankai-test-'))
-  ;({ meta } = await build({ entry, outDir, title: 'counter' }))
+  ;({ meta, prerendered } = await build({ entry, outDir, title: 'counter', prerender: ['/'] }))
   srv = await serve({ outDir, port: 0 })
 })
 
@@ -58,16 +58,38 @@ test('build produced manifest, metadata and precompressed assets', async () => {
   await access(join(outDir, chunk.slice(1) + '.gz'))
 })
 
-test('pages get 103 Early Hints carrying the route assets', async () => {
+test('the style.css convention bundles css the server never imports', async () => {
+  assert.strictEqual(meta.assets.css.length, 1, 'extracted css asset')
+  const res = await get('/some/page')
+  const text = res.body.toString()
+  assert.match(text, /<link rel="stylesheet" href="\/assets\/.*\.css">/)
+  assert.match(String(res.headers.link), /as=style/, 'stylesheet in the Link header')
+})
+
+test('prerendered routes are written and served statically with hints', async () => {
+  assert.deepStrictEqual(prerendered, ['/'])
+  await access(join(outDir, 'index.html'))
   const res = await get('/')
+  assert.strictEqual(res.status, 200)
+  assert.match(res.body.toString(), /count is 0/)
+  assert.strictEqual(res.interim[0]?.statusCode, 103, 'prerendered pages still send Early Hints')
+})
+
+test('the SSR <title> comes from state (DOMTitleChange during render)', async () => {
+  const res = await get('/some/page')
+  assert.match(res.body.toString(), /<title>count is 0<\/title>/)
+})
+
+test('live pages get 103 Early Hints carrying the route assets', async () => {
+  const res = await get('/some/page')
   assert.strictEqual(res.interim.length, 1, 'one interim response')
   assert.strictEqual(res.interim[0].statusCode, 103)
   assert.match(String(res.interim[0].headers.link), /rel=modulepreload/)
   assert.match(String(res.headers.link), /rel=modulepreload/, 'Link header repeated on the final response')
 })
 
-test('pages stream SSR html with a filtered initialState tail', async () => {
-  const res = await get('/')
+test('live pages stream SSR html with a filtered initialState tail', async () => {
+  const res = await get('/some/page')
   const text = res.body.toString()
   assert.strictEqual(res.status, 200)
   assert.match(text, /<h1>count is 0<\/h1>/, 'server-rendered view')
@@ -76,6 +98,38 @@ test('pages stream SSR html with a filtered initialState tail', async () => {
   assert.ok(!/initialState=.*"events"/.test(text), 'internals filtered from state')
 })
 
+test('h2: HTTP/2 server sends Early Hints and streams the page', async (t) => {
+  const { default: http2 } = await import('node:http2')
+  let h2srv
+  try {
+    h2srv = await serve({ outDir, port: 0, h2: true })
+  } catch (err) {
+    t.skip('openssl unavailable: ' + err.message)
+    return
+  }
+
+  const session = http2.connect(`https://localhost:${h2srv.port}`, { rejectUnauthorized: false })
+  const result = await new Promise((resolve, reject) => {
+    const req = session.request({ ':path': '/some/page' })
+    let interim = null
+    let status = null
+    let body = ''
+    req.on('headers', (headers) => { interim = headers })
+    req.on('response', (headers) => { status = headers[':status'] })
+    req.on('data', (d) => { body += d })
+    req.on('end', () => resolve({ interim, status, body }))
+    req.on('error', reject)
+    req.end()
+  })
+  session.close()
+  await h2srv.close()
+
+  assert.strictEqual(result.status, 200)
+  assert.strictEqual(result.interim?.[':status'], 103, '103 interim over h2')
+  assert.match(String(result.interim?.link), /rel=modulepreload/)
+  assert.match(result.body, /count is 0/)
+})
+
 test('hashed assets are immutable and served precompressed on request', async () => {
   const chunk = meta.assets.scripts[0]