glashjs 0.2.0 → 0.4.0

package/README.md

@@ -77,6 +77,19 @@ glash dev      # dev server: routing + SSR + API, live route reload
 glash serve    # production server over routes/ + built assets (Brotli-negotiated)
 ```
 
+**`<Image>`** (better than `next/image` — no runtime image server, uses the build's AVIF/WebP):
+```jsx
+import { Image } from 'glashjs/image';
+<Image src="/hero.png" alt="Hero" width={1200} height={630} />
+// -> <picture><source …avif><source …webp><img loading=lazy decoding=async></picture>
+```
+
+**File-based middleware** (`_middleware.mjs`, runs root→leaf before the route):
+```js
+import { redirect } from 'glashjs';
+export default (ctx) => { if (!ctx.headers.authorization) return redirect('/login'); };
+```
+
 Every response carries the secure-by-default headers; static files are served from the build with Brotli negotiation.
 
 ### JSX components + client hydration (new in 0.2)
@@ -92,7 +105,9 @@ export default function Counter({ start = 0 }) {
 }
 ```
 
-Hydration is **CSP-safe**: server props ride in a non-executed `<script type="application/json">` and the hydration bundle is an external `'self'` module with a per-request **nonce** — so the strict CSP stays intact (no `'unsafe-inline'`). **Honest scope:** uses Preact (React-compatible via `preact/compat`), not React itself; nested layouts, HMR, and streaming are still ahead.
+Hydration is **CSP-safe**: server props ride in a non-executed `<script type="application/json">` and the hydration bundle is an external `'self'` module with a per-request **nonce** — so the strict CSP stays intact (no `'unsafe-inline'`).
+
+**Nested layouts** (`_layout.jsx` in any routes dir wrap pages root→leaf, server + hydration), **streaming SSR** (the shell flushes before the component renders — `Transfer-Encoding: chunked`), and **dev live-reload** (`glash dev` auto-refreshes on save over SSE) are all in. **Honest scope:** uses Preact (React-compatible via `preact/compat`), not React; live-reload is auto-refresh, not yet state-preserving fast-refresh; streaming is shell-flush, not Suspense-chunked.
 
 ## Usage
 
@@ -143,7 +158,12 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 - [x] Dev/prod server with live route reload + Brotli-negotiated static serving
 - [x] JSX components + client-side hydration (Preact + esbuild) — CSP-safe with nonces
 - [x] Client-JS bundling (esbuild) per route
-- [ ] Nested layouts, streaming SSR, HMR (fast refresh)
+- [x] Nested layouts (`_layout.jsx` composing root→leaf, server + hydration)
+- [x] Streaming SSR (shell flushed before the component renders)
+- [x] Dev live-reload over SSE (auto-refresh on save)
+- [x] `<Image>` — zero-config `<picture>` with AVIF/WebP from the optimizer (beats next/image: no runtime image server)
+- [x] File-based middleware (`_middleware.mjs`, root→leaf) — auth, redirects, headers
+- [ ] State-preserving fast-refresh, Suspense streaming, `<Video>`, `glash deploy`
 - [ ] `<Image>` / `<Video>` components that emit `<picture>`/`<source>` from the manifest
 - [ ] Edge adapter for the glashdb Worker (serve `.br`/`.avif` by `Accept`)
 - [ ] `glash deploy` → glashdb hosting in one command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glashjs",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "glashjs — a web framework with file-based routing, SSR, API routes, a best-in-class asset optimizer, offline PWA layer, animated favicon, and secure-by-default headers. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   "exports": {
     ".": "./src/index.mjs",
     "./config": "./src/config.mjs",
-    "./security": "./src/security/headers.mjs"
+    "./security": "./src/security/headers.mjs",
+    "./image": "./src/components/image.mjs",
+    "./package.json": "./package.json"
   },
   "files": [
     "bin",

package/src/components/image.mjs

@@ -0,0 +1,42 @@
+// glashjs <Image> — a zero-config image component that's better than next/image
+// out of the box: it emits a <picture> that prefers the AVIF/WebP variants the
+// glashjs asset optimizer already produced at build time, with no runtime image
+// server, no signed URLs, and no config. Width/height are required-by-habit to
+// prevent layout shift (CLS), and images lazy-load + async-decode by default.
+//
+//   import { Image } from 'glashjs/image';
+//   <Image src="/hero.png" alt="Hero" width={1200} height={630} />
+//
+// After `glash build`, /hero.avif and /hero.webp exist next to /hero.png, so
+// the browser downloads the smallest format it supports. Deterministic output
+// (same on server + during hydration), so it never causes a hydration mismatch.
+import { h } from 'preact';
+
+const RASTER = /\.(png|jpe?g|webp|avif)$/i;
+
+export function Image({ src, alt = '', width, height, sizes, loading = 'lazy', fetchpriority, class: className, style, ...rest }) {
+  if (!src || !RASTER.test(src)) {
+    // SVG/unknown: render a plain <img>, nothing to transcode.
+    return h('img', { src, alt, width, height, loading, decoding: 'async', class: className, style, ...rest });
+  }
+  const base = src.replace(RASTER, '');
+  return h(
+    'picture',
+    { class: className, style },
+    h('source', { srcset: `${base}.avif`, type: 'image/avif', sizes }),
+    h('source', { srcset: `${base}.webp`, type: 'image/webp', sizes }),
+    h('img', {
+      src,
+      alt,
+      width,
+      height,
+      sizes,
+      loading,
+      fetchpriority,
+      decoding: 'async',
+      ...rest,
+    }),
+  );
+}
+
+export default Image;

package/src/index.mjs

@@ -5,6 +5,7 @@ export { optimizeAssets } from './assets/optimize.mjs';
 export { generateAnimatedFavicon } from './assets/animated-favicon.mjs';
 export { generateServiceWorker } from './offline/generate-sw.mjs';
 export { securityHeaders, buildCsp, sri, glashSecurity } from './security/headers.mjs';
-export { createGlashServer, json } from './server/server.mjs';
-export { discoverRoutes, matchRoute } from './server/router.mjs';
+export { createGlashServer, json, redirect } from './server/server.mjs';
+export { discoverRoutes, matchRoute, findMiddleware } from './server/router.mjs';
 export { html, raw, escapeHtml, renderDocument } from './server/html.mjs';
+export { Image } from './components/image.mjs';

package/src/server/html.mjs

@@ -33,25 +33,8 @@ export function html(strings, ...values) {
  * The runtime imports are resilient (try/catch) so pages still render in `dev`
  * before a `glash build` has produced those files.
  */
-export function renderDocument({
-  title = 'glashjs',
-  head = '',
-  body = '',
-  lang = 'en',
-  favicon = '/favicon.svg',
-  offline = true,
-  animatedFavicon = true,
-  nonce = '',
-} = {}) {
+function shellOpen({ title = 'glashjs', head = '', lang = 'en', favicon = '/favicon.svg' }) {
   const headHtml = typeof head === 'object' && head?.__raw ? head.__raw : String(head ?? '');
-  const bodyHtml = typeof body === 'object' && body?.__raw ? body.__raw : String(body ?? '');
-  const n = nonce ? ` nonce="${escapeHtml(nonce)}"` : '';
-  const fav = animatedFavicon
-    ? `<script type="module"${n}>try{const m=await import("/glash-favicon.mjs");m.startGlashFavicon&&m.startGlashFavicon();}catch{}</script>`
-    : '';
-  const off = offline
-    ? `<script type="module"${n}>try{const m=await import("/glash-offline.mjs");m.registerGlashOffline&&m.registerGlashOffline();}catch{}</script>`
-    : '';
   return `<!doctype html>
 <html lang="${escapeHtml(lang)}">
 <head>
@@ -63,8 +46,31 @@ export function renderDocument({
 ${headHtml}
 </head>
 <body>
-${bodyHtml}
-${fav}${off}
-</body>
-</html>`;
+`;
+}
+
+function shellTail({ offline = true, animatedFavicon = true, dev = false, nonce = '' }) {
+  const n = nonce ? ` nonce="${escapeHtml(nonce)}"` : '';
+  const fav = animatedFavicon
+    ? `<script type="module"${n}>try{const m=await import("/glash-favicon.mjs");m.startGlashFavicon&&m.startGlashFavicon();}catch{}</script>`
+    : '';
+  const off = offline
+    ? `<script type="module"${n}>try{const m=await import("/glash-offline.mjs");m.registerGlashOffline&&m.registerGlashOffline();}catch{}</script>`
+    : '';
+  // Dev live-reload: a nonce'd inline script (CSP-safe) that reloads on change.
+  const hmr = dev
+    ? `<script${n}>try{new EventSource("/_glash/hmr").onmessage=function(e){if(e.data==="reload")location.reload();};}catch(e){}</script>`
+    : '';
+  return `\n${fav}${off}${hmr}\n</body>\n</html>`;
+}
+
+/** Full document (buffered). */
+export function renderDocument(opts = {}) {
+  const bodyHtml = typeof opts.body === 'object' && opts.body?.__raw ? opts.body.__raw : String(opts.body ?? '');
+  return shellOpen(opts) + bodyHtml + shellTail(opts);
+}
+
+/** Streaming document: `open` flushed before the body renders, `tail` after. */
+export function documentParts(opts = {}) {
+  return { open: shellOpen(opts), tail: shellTail(opts) };
 }

package/src/server/jsx.mjs

@@ -13,7 +13,7 @@
 // A `.jsx`/`.tsx` route exports a default component and (optionally) an async
 // `getServerData(ctx)` that returns props for SSR + hydration. Plain `.mjs`
 // HTML-render routes keep working with zero deps.
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync } from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { pathToFileURL } from 'node:url';
@@ -49,65 +49,102 @@ export function routeId(file) {
 const serverCache = new Map();
 const clientCache = new Map();
 
-/** Compile a JSX/TSX route for the server and import it (default component + getServerData). */
-export async function loadComponentRoute(file, root, dev) {
+/** Clear compiled-route caches (used by dev live-reload on file change). */
+export function clearJsxCaches() {
+  serverCache.clear();
+  clientCache.clear();
+}
+
+/**
+ * Nested layouts: collect `_layout.{jsx,tsx}` from the routes root down to the
+ * page's directory (root-first). Each wraps its children, Next-style.
+ */
+export function findLayouts(routesDir, pageFile) {
+  const root = path.resolve(routesDir);
+  const pageDir = path.dirname(path.resolve(pageFile));
+  const rel = path.relative(root, pageDir);
+  const dirs = [root];
+  let acc = root;
+  for (const part of rel ? rel.split(path.sep) : []) { acc = path.join(acc, part); dirs.push(acc); }
+  const layouts = [];
+  for (const d of dirs) {
+    for (const name of ['_layout.jsx', '_layout.tsx']) {
+      const f = path.join(d, name);
+      if (existsSync(f)) { layouts.push(f); break; }
+    }
+  }
+  return layouts;
+}
+
+const compId = (pageFile, layouts) => routeId(pageFile + '|' + layouts.join('|'));
+
+function serverEntry(pageFile, layouts) {
+  const lines = [`import * as __p from ${JSON.stringify(pageFile)};`];
+  layouts.forEach((f, i) => lines.push(`import __L${i} from ${JSON.stringify(f)};`));
+  lines.push('export const Page = __p.default;', 'export const getServerData = __p.getServerData;', 'export const title = __p.title;');
+  lines.push(`export const layouts = [${layouts.map((_, i) => `__L${i}`).join(',')}];`);
+  return lines.join('\n');
+}
+
+function clientEntry(pageFile, layouts) {
+  const imports = [`import { hydrate, h } from 'preact';`, `import Page from ${JSON.stringify(pageFile)};`];
+  layouts.forEach((f, i) => imports.push(`import __L${i} from ${JSON.stringify(f)};`));
+  return `${imports.join('\n')}
+const layouts = [${layouts.map((_, i) => `__L${i}`).join(',')}];
+const el = document.getElementById('glash-root');
+const pe = document.getElementById('glash-props');
+let props = {};
+try { props = pe ? JSON.parse(pe.textContent) : {}; } catch {}
+let tree = h(Page, props);
+for (let i = layouts.length - 1; i >= 0; i--) tree = h(layouts[i], props, tree);
+if (el) hydrate(tree, el);`;
+}
+
+/** Compile page + its layout chain into a server module ({ Page, layouts, getServerData, title }). */
+export async function loadComponentRoute(pageFile, layouts, root, dev) {
   const eb = await esbuild();
   if (!eb) throw new Error(MISSING);
-  if (!dev && serverCache.has(file)) return serverCache.get(file);
-  const out = path.join(root, '.glash', 'server', routeId(file) + '.mjs');
+  const id = compId(pageFile, layouts);
+  if (!dev && serverCache.has(id)) return serverCache.get(id);
+  const out = path.join(root, '.glash', 'server', id + '.mjs');
   await fs.mkdir(path.dirname(out), { recursive: true });
   await eb.build({
-    entryPoints: [file],
-    bundle: true,
-    platform: 'node',
-    format: 'esm',
-    jsx: 'automatic',
-    jsxImportSource: 'preact',
-    // Keep preact external so the route shares the framework's preact instance
-    // (vnodes from the route and renderToString must come from the same preact).
+    stdin: { contents: serverEntry(pageFile, layouts), resolveDir: path.dirname(pageFile), loader: 'js', sourcefile: 'glash-server-entry.js' },
+    bundle: true, platform: 'node', format: 'esm', jsx: 'automatic', jsxImportSource: 'preact',
     external: ['preact', 'preact/*', 'preact-render-to-string'],
-    outfile: out,
-    logLevel: 'silent',
+    outfile: out, logLevel: 'silent',
   });
   const mod = await import(pathToFileURL(out).href + (dev ? `?t=${Date.now()}` : ''));
-  if (!dev) serverCache.set(file, mod);
+  if (!dev) serverCache.set(id, mod);
   return mod;
 }
 
-/** Build the browser hydration bundle for a route (preact bundled in). */
-export async function clientBundle(file, dev) {
+/** Build the browser hydration bundle for page + layouts (preact bundled in). */
+export async function clientBundle(pageFile, layouts, dev) {
   const eb = await esbuild();
   if (!eb) throw new Error(MISSING);
-  if (!dev && clientCache.has(file)) return clientCache.get(file);
-  // Props arrive in a non-executed <script type="application/json"> block, so
-  // hydration works under glashjs's strict CSP (no inline executable scripts).
-  const entry = `import { hydrate, h } from 'preact';
-import Page from ${JSON.stringify(file)};
-const el = document.getElementById('glash-root');
-const pe = document.getElementById('glash-props');
-let props = {};
-try { props = pe ? JSON.parse(pe.textContent) : {}; } catch {}
-if (el) hydrate(h(Page, props), el);`;
+  const id = compId(pageFile, layouts);
+  if (!dev && clientCache.has(id)) return clientCache.get(id);
   const res = await eb.build({
-    stdin: { contents: entry, resolveDir: path.dirname(file), loader: 'jsx', sourcefile: 'glash-client-entry.jsx' },
-    bundle: true,
-    platform: 'browser',
-    format: 'esm',
-    minify: !dev,
-    jsx: 'automatic',
-    jsxImportSource: 'preact',
-    write: false,
-    logLevel: 'silent',
+    stdin: { contents: clientEntry(pageFile, layouts), resolveDir: path.dirname(pageFile), loader: 'jsx', sourcefile: 'glash-client-entry.jsx' },
+    bundle: true, platform: 'browser', format: 'esm', minify: !dev, jsx: 'automatic', jsxImportSource: 'preact',
+    write: false, logLevel: 'silent',
   });
   const js = res.outputFiles[0].text;
-  if (!dev) clientCache.set(file, js);
+  if (!dev) clientCache.set(id, js);
   return js;
 }
 
-/** Server-render a route component to an HTML string. */
+function compose(h, layouts, Page, props) {
+  let tree = h(Page, props);
+  for (let i = layouts.length - 1; i >= 0; i--) tree = h(layouts[i], props, tree);
+  return tree;
+}
+
+/** Server-render page + layouts to an HTML string. */
 export async function renderComponent(mod, props) {
   const rt = await preactRuntime();
   if (!rt) throw new Error(MISSING);
-  if (typeof mod.default !== 'function') throw new Error('JSX route must default-export a component');
-  return rt.renderToString(rt.h(mod.default, props));
+  if (typeof mod.Page !== 'function') throw new Error('JSX route must default-export a component');
+  return rt.renderToString(compose(rt.h, mod.layouts || [], mod.Page, props));
 }

package/src/server/router.mjs

@@ -7,15 +7,40 @@
 //   routes/docs/[...path].mjs -> /docs/*path       (catch-all)
 //   routes/api/hello.mjs      -> /api/hello        (API route — exports GET/POST/…)
 // Anything under routes/api/ is an API route; everything else is a page (SSR).
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync } from 'node:fs';
 import path from 'node:path';
 
+/**
+ * File-based middleware: `_middleware.{mjs,js}` in any routes dir runs before
+ * the route, root→leaf. Each default-exports `(ctx) => Response | void` — return
+ * a value to short-circuit (redirect/auth/json), or nothing to continue. The
+ * root middleware runs for every request; `dash/_middleware` only for /dash/*.
+ */
+export function findMiddleware(routesDir, routeFile) {
+  const root = path.resolve(routesDir);
+  const dir = path.dirname(path.resolve(routeFile));
+  const rel = path.relative(root, dir);
+  const dirs = [root];
+  let acc = root;
+  for (const part of rel ? rel.split(path.sep) : []) { acc = path.join(acc, part); dirs.push(acc); }
+  const files = [];
+  for (const d of dirs) {
+    for (const name of ['_middleware.mjs', '_middleware.js']) {
+      const f = path.join(d, name);
+      if (existsSync(f)) { files.push(f); break; }
+    }
+  }
+  return files;
+}
+
 export async function discoverRoutes(routesDir) {
   const root = path.resolve(routesDir);
   const files = [];
   await walk(root, root, files);
   const routes = files
     .filter((f) => /\.(mjs|js|jsx|tsx)$/.test(f.rel))
+    // `_`-prefixed files are private (layouts, helpers) — not routes.
+    .filter((f) => !f.rel.split('/').some((seg) => seg.startsWith('_')))
     .map((f) => toRoute(f.rel, f.file));
   // Most specific first: static segments beat params beat catch-all.
   routes.sort((a, b) => b.score - a.score);

package/src/server/server.mjs

@@ -6,13 +6,13 @@
 //                 service worker, favicons) with Brotli negotiation.
 // Every response carries the secure-by-default headers.
 import http from 'node:http';
-import { promises as fs, existsSync, statSync } from 'node:fs';
+import { promises as fs, existsSync, statSync, watch } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { discoverRoutes, matchRoute } from './router.mjs';
-import { renderDocument } from './html.mjs';
-import { isComponentRoute, loadComponentRoute, clientBundle, renderComponent, routeId } from './jsx.mjs';
+import { discoverRoutes, matchRoute, findMiddleware } from './router.mjs';
+import { renderDocument, documentParts } from './html.mjs';
+import { isComponentRoute, loadComponentRoute, clientBundle, renderComponent, routeId, findLayouts, clearJsxCaches } from './jsx.mjs';
 import { securityHeaders } from '../security/headers.mjs';
 import { loadConfig } from '../config.mjs';
 
@@ -36,32 +36,60 @@ export async function createGlashServer({ root = process.cwd(), dev = false } =
   const importRoute = (file) =>
     import(pathToFileURL(file).href + (dev ? `?t=${Date.now()}` : ''));
 
+  // Dev live-reload: watch routes/, drop compiled caches, and push a reload
+  // event to every connected browser over Server-Sent Events.
+  const hmrClients = new Set();
+  if (dev) {
+    try {
+      watch(routesDir, { recursive: true }, () => {
+        clearJsxCaches();
+        for (const c of hmrClients) c.write('data: reload\n\n');
+      });
+    } catch { /* fs.watch recursive may be unsupported on some platforms */ }
+  }
+
   const server = http.createServer(async (req, res) => {
     const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
     const pathname = safeDecode(url.pathname);
     try {
       if (dev) routes = await discoverRoutes(routesDir);
+      // Dev live-reload SSE channel.
+      if (dev && pathname === '/_glash/hmr') {
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+        res.write('retry: 1000\n\n');
+        hmrClients.add(res);
+        req.on('close', () => hmrClients.delete(res));
+        return;
+      }
       // Client hydration bundles: /_glash/<routeId>.js
       if (pathname.startsWith('/_glash/')) {
         const id = pathname.slice('/_glash/'.length).replace(/\.js$/, '');
         const comp = routes.find((r) => isComponentRoute(r.file) && routeId(r.file) === id);
         if (!comp) return send(res, 404, 'text/plain', 'not found', secHeaders);
-        const js = await clientBundle(comp.file, dev);
+        const js = await clientBundle(comp.file, findLayouts(routesDir, comp.file), dev);
         return send(res, 200, 'text/javascript; charset=utf-8', js, { ...secHeaders, 'cache-control': dev ? 'no-store' : 'public, max-age=31536000, immutable' });
       }
       if (await serveStatic(res, outDir, pathname, req, secHeaders)) return;
       const match = matchRoute(routes, pathname);
       if (!match) return send(res, 404, 'text/plain; charset=utf-8', 'Not found', secHeaders);
-      const ctx = makeCtx(req, url, match.params);
+      const ctx = makeCtx(req, res, url, match.params);
+      // Run the middleware chain (root -> leaf). Any return value short-circuits.
+      for (const mwFile of findMiddleware(routesDir, match.route.file)) {
+        const mwMod = await importRoute(mwFile);
+        const mw = mwMod.default || mwMod.middleware;
+        if (typeof mw !== 'function') continue;
+        const result = await mw(ctx);
+        if (result) return sendMiddlewareResult(res, result, secHeaders);
+      }
       if (match.route.isApi) {
         const mod = await importRoute(match.route.file);
         return await handleApi(res, mod, req, ctx, secHeaders);
       }
       if (isComponentRoute(match.route.file)) {
-        return await handleComponentPage(res, match.route, ctx, cfg, secHeaders, root, dev);
+        return await handleComponentPage(res, match.route, ctx, cfg, secHeaders, root, routesDir, dev);
       }
       const mod = await importRoute(match.route.file);
-      return await handlePage(res, mod, ctx, cfg, secHeaders);
+      return await handlePage(res, mod, ctx, cfg, secHeaders, dev);
     } catch (err) {
       const msg = dev ? `glashjs error:\n${err?.stack || err}` : 'Internal Server Error';
       send(res, 500, 'text/plain; charset=utf-8', msg, secHeaders);
@@ -89,7 +117,7 @@ async function handleApi(res, mod, req, ctx, secHeaders) {
   send(res, 200, 'application/json', JSON.stringify(result ?? null), secHeaders);
 }
 
-async function handlePage(res, mod, ctx, cfg, secHeaders) {
+async function handlePage(res, mod, ctx, cfg, secHeaders, dev) {
   const render = mod.default;
   if (typeof render !== 'function') return send(res, 500, 'text/plain', 'route has no default export', secHeaders);
   const out = await render(ctx);
@@ -101,30 +129,28 @@ async function handlePage(res, mod, ctx, cfg, secHeaders) {
     body: page.body ?? '',
     offline: cfg.offline,
     animatedFavicon: !!cfg.animatedFavicon,
-    nonce,
+    nonce, dev,
   });
   send(res, page.status || 200, 'text/html; charset=utf-8', docHtml, { ...pageHeaders(cfg, secHeaders, nonce), ...(page.headers || {}) });
 }
 
-async function handleComponentPage(res, route, ctx, cfg, secHeaders, root, dev) {
-  const mod = await loadComponentRoute(route.file, root, dev);
+async function handleComponentPage(res, route, ctx, cfg, secHeaders, root, routesDir, dev) {
+  const layouts = findLayouts(routesDir, route.file);
+  const mod = await loadComponentRoute(route.file, layouts, root, dev);
   const props = (typeof mod.getServerData === 'function' ? await mod.getServerData(ctx) : {}) || {};
-  const rendered = await renderComponent(mod, props);
   const id = routeId(route.file);
   const nonce = randomBytes(16).toString('base64');
   // Props in a non-executed JSON block (CSP-safe); hydration bundle is an
   // external 'self' module — both pass the strict CSP without 'unsafe-inline'.
   const head = `<script type="application/json" id="glash-props">${safeJson(props)}</script>`;
-  const body = `<div id="glash-root">${rendered}</div><script type="module" src="/_glash/${id}.js"></script>`;
-  const docHtml = renderDocument({
-    title: mod.title || cfg.name,
-    head,
-    body,
-    offline: cfg.offline,
-    animatedFavicon: !!cfg.animatedFavicon,
-    nonce,
+  const { open, tail } = documentParts({
+    title: mod.title || cfg.name, head, offline: cfg.offline, animatedFavicon: !!cfg.animatedFavicon, nonce, dev,
   });
-  send(res, 200, 'text/html; charset=utf-8', docHtml, pageHeaders(cfg, secHeaders, nonce));
+  res.writeHead(200, { ...pageHeaders(cfg, secHeaders, nonce), 'content-type': 'text/html; charset=utf-8' });
+  res.write(open); // flush the shell first, before rendering the component
+  const rendered = await renderComponent(mod, props);
+  res.write(`<div id="glash-root">${rendered}</div><script type="module" src="/_glash/${id}.js"></script>`);
+  res.end(tail);
 }
 
 // Per-request page headers: a fresh CSP carrying this request's script nonce, so
@@ -160,9 +186,10 @@ async function serveStatic(res, outDir, pathname, req, secHeaders) {
   return false;
 }
 
-function makeCtx(req, url, params) {
+function makeCtx(req, res, url, params) {
   return {
     req,
+    res,
     method: req.method,
     url,
     path: url.pathname,
@@ -195,3 +222,22 @@ function safeDecode(p) {
 export function json(body, { status = 200, headers } = {}) {
   return { __response: true, status, contentType: 'application/json', body, headers };
 }
+
+/** Middleware/handler helper: redirect to another path. */
+export function redirect(location, { status = 302 } = {}) {
+  return { __redirect: location, status };
+}
+
+function sendMiddlewareResult(res, result, secHeaders) {
+  if (result.__redirect) {
+    res.writeHead(result.status || 302, { ...secHeaders, location: result.__redirect });
+    return res.end();
+  }
+  if (result.__response) {
+    return send(res, result.status || 200, result.contentType || 'application/json',
+      typeof result.body === 'string' ? result.body : JSON.stringify(result.body), { ...secHeaders, ...(result.headers || {}) });
+  }
+  // A bare object/string from middleware is treated as a JSON/text body.
+  if (typeof result === 'string') return send(res, 200, 'text/plain; charset=utf-8', result, secHeaders);
+  return send(res, 200, 'application/json', JSON.stringify(result), secHeaders);
+}