glashjs 0.0.3 → 0.2.0

package/README.md

@@ -49,6 +49,51 @@ Nothing is unhackable. glashjs ships strong, opinionated defaults so you're secu
 - **Subresource Integrity** helper (`sri()`) for build assets
 - Emitted to `glash-headers.json` for the edge, plus a `glashSecurity()` Express middleware
 
+## Routing, SSR & API (new in 0.1)
+glashjs now has a real server runtime — **file-based routing**, **server-side rendering**, and **API routes** — on Node built-ins, zero deps.
+
+```
+routes/
+  index.mjs          ->  /                 (SSR page)
+  about.mjs          ->  /about
+  blog/[slug].mjs    ->  /blog/:slug       (dynamic segment -> ctx.params.slug)
+  docs/[...path].mjs ->  /docs/*           (catch-all)
+  api/hello.mjs      ->  /api/hello        (API: export GET/POST/…)
+```
+
+```js
+// routes/index.mjs  — a server-rendered page (XSS-safe `html` template)
+import { html } from 'glashjs';
+export default (ctx) => ({ title: 'Home', body: html`<h1>Hello ${ctx.query.name}</h1>` });
+
+// routes/api/hello.mjs — an API route
+import { json } from 'glashjs';
+export const GET  = (ctx) => ({ ok: true, name: ctx.query.name });
+export const POST = (ctx) => json({ created: ctx.body }, { status: 201 });
+```
+
+```bash
+glash dev      # dev server: routing + SSR + API, live route reload
+glash serve    # production server over routes/ + built assets (Brotli-negotiated)
+```
+
+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)
+Author pages as **JSX components**, server-render them, and **hydrate** in the browser so hooks work — real interactivity, the Next-style model. Built on **Preact** (React-compatible) + **esbuild**, added as *optional peers* (`npm i preact preact-render-to-string esbuild`); glashjs core stays zero-dep.
+
+```jsx
+// routes/counter.jsx  — SSR + hydrated, the button is interactive
+import { useState } from 'preact/hooks';
+export function getServerData(ctx) { return { start: Number(ctx.query.start || 0) }; }  // server props
+export default function Counter({ start = 0 }) {
+  const [n, setN] = useState(start);
+  return <button onClick={() => setN(n + 1)}>count is {n}</button>;
+}
+```
+
+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.
+
 ## Usage
 
 ```js
@@ -92,10 +137,15 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 - [x] Asset optimizer (Brotli/Gzip real; AVIF/WebP/AV1 via optional sharp/ffmpeg)
 - [x] Offline Service Worker + PWA manifest
 - [x] Secure-by-default headers + CSP + SRI
+- [x] File-based routing (pages + `api/`, dynamic `[param]` & catch-all `[...path]`)
+- [x] Server-side rendering (XSS-safe `html` templates) + full-document runtime
+- [x] API routes (per-method handlers, JSON body parsing, typed `json()` responses)
+- [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)
 - [ ] `<Image>` / `<Video>` components that emit `<picture>`/`<source>` from the manifest
-- [ ] Dev server + HMR (on Vite/esbuild) and file-based routing
-- [ ] SSR / streaming + edge adapter for the glashdb Worker (serve `.br`/`.avif` by `Accept`)
-- [ ] Signed, immutable asset URLs + automatic SRI injection into HTML
+- [ ] Edge adapter for the glashdb Worker (serve `.br`/`.avif` by `Accept`)
 - [ ] `glash deploy` → glashdb hosting in one command
 
 ## Design stance

package/bin/glash.mjs

@@ -3,6 +3,7 @@
 import { readFileSync } from 'node:fs';
 import { build } from '../src/build.mjs';
 import { optimizeAssets } from '../src/assets/optimize.mjs';
+import { createGlashServer } from '../src/server/server.mjs';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
@@ -12,12 +13,32 @@ function arg(name, fallback) {
   return i >= 0 && rest[i + 1] ? rest[i + 1] : fallback;
 }
 
+async function serve(dev) {
+  const root = arg('--root', process.cwd());
+  const { listen, cfg, routes } = await createGlashServer({ root, dev });
+  const port = Number(arg('--port', cfg.port || 3000));
+  const { host } = await listen(port);
+  const pages = routes.filter((r) => !r.isApi).length;
+  const apis = routes.filter((r) => r.isApi).length;
+  console.log(`\nglashjs ${dev ? 'dev' : 'serve'} — "${cfg.name}"`);
+  console.log(`  ${pages} page route(s), ${apis} api route(s)`);
+  routes.forEach((r) => console.log(`    ${r.isApi ? 'api ' : 'page'}  ${r.pattern}`));
+  console.log(`\n  ▶ http://localhost:${port}${dev ? '   (live route reload)' : ''}\n`);
+}
+
 async function main() {
   switch (cmd) {
     case 'build': {
       await build({ root: arg('--root', process.cwd()) });
       break;
     }
+    case 'dev':
+      await serve(true);
+      break;
+    case 'serve':
+    case 'start':
+      await serve(false);
+      break;
     case 'optimize': {
       const dir = rest[0] && !rest[0].startsWith('--') ? rest[0] : 'public';
       console.log(`glashjs optimize — ${dir}\n`);
@@ -35,6 +56,8 @@ async function main() {
       console.log(`glashjs — fast, offline-capable, hard-to-hack sites
 
 Usage:
+  glash dev [--port 3000]       Run the dev server (file-based routing, SSR, API, live reload)
+  glash serve [--port 3000]     Run the production server over routes/ + built assets
   glash build [--root <dir>]    Optimize assets, generate offline SW + PWA + security manifests
   glash optimize [<dir>]        Just run the asset optimizer over a directory
   glash version                 Print version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glashjs",
-  "version": "0.0.3",
-  "description": "glashjs — a build pipeline + runtime conventions for fast, offline-capable, hard-to-hack sites. Built on proven primitives, with a best-in-class asset optimizer, PWA offline layer, and secure-by-default headers.",
+  "version": "0.2.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": {
     "glash": "bin/glash.mjs"
@@ -19,13 +19,24 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {},
   "peerDependencies": {
+    "esbuild": ">=0.20.0",
+    "preact": "^10.25.0",
+    "preact-render-to-string": "^6.5.0",
     "sharp": "^0.34.5"
   },
   "peerDependenciesMeta": {
     "sharp": {
       "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    },
+    "preact": {
+      "optional": true
+    },
+    "preact-render-to-string": {
+      "optional": true
     }
   },
   "keywords": [
@@ -37,7 +48,17 @@
     "asset-optimization",
     "avif",
     "brotli",
-    "security"
+    "security",
+    "routing",
+    "ssr",
+    "api",
+    "server",
+    "web-framework"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "preact": "^10.29.2",
+    "preact-render-to-string": "^6.7.0"
+  }
 }

package/src/config.mjs

@@ -17,6 +17,9 @@ export const DEFAULT_CONFIG = {
   // false disables it. Emits `glash-favicon.mjs` — call startGlashFavicon() once.
   animatedFavicon: true,
   publicDir: 'public',
+  // File-based routes (pages + api/) served by `glash dev` / `glash serve`.
+  routesDir: 'routes',
+  port: 3000,
   outDir: '.glash/out',
   themeColor: '#0b0d12',
   offline: true,

package/src/index.mjs

@@ -5,3 +5,6 @@ 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 { html, raw, escapeHtml, renderDocument } from './server/html.mjs';

package/src/server/html.mjs

@@ -0,0 +1,70 @@
+// glashjs SSR HTML layer
+// ---------------------------------------------------------------------------
+// A secure-by-default templating helper + full-document renderer. The `html`
+// tagged template ESCAPES every interpolation (so user data can't inject
+// markup — XSS-safe by default, matching the security pillar). Use `raw()` to
+// deliberately embed already-rendered HTML (e.g. a nested component).
+export function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+export function raw(value) {
+  return { __raw: String(value) };
+}
+
+function interpolate(v) {
+  if (v == null || v === false) return '';
+  if (Array.isArray(v)) return v.map(interpolate).join('');
+  if (typeof v === 'object' && '__raw' in v) return v.__raw;
+  return escapeHtml(v);
+}
+
+export function html(strings, ...values) {
+  let out = '';
+  strings.forEach((str, i) => { out += str + (i < values.length ? interpolate(values[i]) : ''); });
+  return raw(out);
+}
+
+/**
+ * Wrap a page body into a full HTML document with the glashjs runtime wired in:
+ * favicon, animated-favicon runtime, and offline service-worker registration.
+ * 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 = '',
+} = {}) {
+  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>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="icon" href="${escapeHtml(favicon)}" type="image/svg+xml">
+<link rel="manifest" href="/manifest.webmanifest">
+${headHtml}
+</head>
+<body>
+${bodyHtml}
+${fav}${off}
+</body>
+</html>`;
+}

package/src/server/jsx.mjs

@@ -0,0 +1,113 @@
+// glashjs JSX + hydration engine
+// ---------------------------------------------------------------------------
+// This is the layer that makes glashjs a real Next.js alternative: author
+// pages as JSX components, render them on the server, and HYDRATE them in the
+// browser so hooks (useState/useEffect) work — true interactivity.
+//
+// Built on proven primitives, added as OPTIONAL peers so glashjs core stays
+// zero-dependency:
+//   - esbuild                  -> compiles JSX/TSX (server module + client bundle)
+//   - preact                   -> the component runtime (React-compatible)
+//   - preact-render-to-string  -> server-side rendering
+//
+// 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 path from 'node:path';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+const MISSING = 'JSX/TSX routes need the optional peers: npm i esbuild preact preact-render-to-string';
+
+let _esbuild;
+async function esbuild() {
+  if (_esbuild !== undefined) return _esbuild;
+  try { _esbuild = await import('esbuild'); } catch { _esbuild = null; }
+  return _esbuild;
+}
+
+let _h, _renderToString;
+async function preactRuntime() {
+  if (_h) return { h: _h, renderToString: _renderToString };
+  const p = await import('preact').catch(() => null);
+  const r = await import('preact-render-to-string').catch(() => null);
+  if (!p || !r) return null;
+  _h = p.h;
+  _renderToString = r.renderToString || r.default;
+  return { h: _h, renderToString: _renderToString };
+}
+
+export function isComponentRoute(file) {
+  return /\.(jsx|tsx)$/.test(file);
+}
+
+export function routeId(file) {
+  return createHash('sha1').update(file).digest('hex').slice(0, 10);
+}
+
+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) {
+  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');
+  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).
+    external: ['preact', 'preact/*', 'preact-render-to-string'],
+    outfile: out,
+    logLevel: 'silent',
+  });
+  const mod = await import(pathToFileURL(out).href + (dev ? `?t=${Date.now()}` : ''));
+  if (!dev) serverCache.set(file, mod);
+  return mod;
+}
+
+/** Build the browser hydration bundle for a route (preact bundled in). */
+export async function clientBundle(file, 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 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',
+  });
+  const js = res.outputFiles[0].text;
+  if (!dev) clientCache.set(file, js);
+  return js;
+}
+
+/** Server-render a route component 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));
+}

package/src/server/router.mjs

@@ -0,0 +1,76 @@
+// glashjs file-based router
+// ---------------------------------------------------------------------------
+// Maps files under the routes/ dir to URL patterns, Next-style:
+//   routes/index.mjs          -> /
+//   routes/about.mjs          -> /about
+//   routes/blog/[slug].mjs    -> /blog/:slug      (dynamic segment)
+//   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 path from 'node:path';
+
+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))
+    .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);
+  return routes;
+}
+
+async function walk(root, dir, out) {
+  let entries;
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) await walk(root, full, out);
+    else if (e.isFile()) out.push({ file: full, rel: path.relative(root, full).split(path.sep).join('/') });
+  }
+}
+
+function toRoute(rel, file) {
+  const clean = rel.replace(/\.(mjs|js|jsx|tsx)$/, '');
+  const isApi = clean === 'api' || clean.startsWith('api/');
+  const segs = [];
+  for (const part of clean.split('/').filter(Boolean)) {
+    if (part === 'index') continue;
+    if (part.startsWith('[...') && part.endsWith(']')) segs.push({ type: 'catchall', name: part.slice(4, -1) });
+    else if (part.startsWith('[') && part.endsWith(']')) segs.push({ type: 'param', name: part.slice(1, -1) });
+    else segs.push({ type: 'static', value: part });
+  }
+  const pattern = '/' + segs.map((s) => (s.type === 'static' ? s.value : s.type === 'param' ? `:${s.name}` : `*${s.name}`)).join('/');
+  const score = segs.reduce((acc, s) => acc + (s.type === 'static' ? 3 : s.type === 'param' ? 2 : 1), 0) * 10 + segs.length;
+  return { file, isApi, segs, pattern: pattern === '/' ? '/' : pattern, score };
+}
+
+export function matchRoute(routes, pathname) {
+  const reqSegs = pathname.replace(/\/+$/, '').split('/').filter(Boolean);
+  for (const route of routes) {
+    const params = matchSegs(route.segs, reqSegs);
+    if (params) return { route, params };
+  }
+  return null;
+}
+
+function matchSegs(segs, reqSegs) {
+  const params = {};
+  let i = 0;
+  for (const seg of segs) {
+    if (seg.type === 'catchall') {
+      params[seg.name] = reqSegs.slice(i).map(decodeURIComponent).join('/');
+      return params;
+    }
+    if (i >= reqSegs.length) return null;
+    if (seg.type === 'static') {
+      if (reqSegs[i] !== seg.value) return null;
+    } else {
+      params[seg.name] = decodeURIComponent(reqSegs[i]);
+    }
+    i++;
+  }
+  return i === reqSegs.length ? params : null;
+}

package/src/server/server.mjs

@@ -0,0 +1,197 @@
+// glashjs server — routing, SSR, and API in one Node http server.
+// ---------------------------------------------------------------------------
+// `dev: true`  -> re-discovers routes and re-imports modules each request, so
+//                 edits show up without a restart (live reload of route code).
+// `dev: false` -> caches routes; serves the built `outDir` (optimized assets,
+//                 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 { 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 { securityHeaders } from '../security/headers.mjs';
+import { loadConfig } from '../config.mjs';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript',
+  '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+  '.avif': 'image/avif', '.webmanifest': 'application/manifest+json', '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8',
+};
+const mime = (file) => MIME[path.extname(file).toLowerCase()] || 'application/octet-stream';
+
+/** Build the glashjs server. Returns { server, listen, cfg }. */
+export async function createGlashServer({ root = process.cwd(), dev = false } = {}) {
+  const cfg = await loadConfig(root);
+  const routesDir = path.resolve(root, cfg.routesDir || 'routes');
+  const outDir = path.resolve(root, cfg.outDir);
+  const secHeaders = securityHeaders(cfg.security);
+  let routes = await discoverRoutes(routesDir);
+
+  const importRoute = (file) =>
+    import(pathToFileURL(file).href + (dev ? `?t=${Date.now()}` : ''));
+
+  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);
+      // 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);
+        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);
+      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);
+      }
+      const mod = await importRoute(match.route.file);
+      return await handlePage(res, mod, ctx, cfg, secHeaders);
+    } catch (err) {
+      const msg = dev ? `glashjs error:\n${err?.stack || err}` : 'Internal Server Error';
+      send(res, 500, 'text/plain; charset=utf-8', msg, secHeaders);
+    }
+  });
+
+  const listen = (port = cfg.port || 3000, host = '0.0.0.0') =>
+    new Promise((resolve) => server.listen(port, host, () => resolve({ port, host })));
+
+  return { server, listen, cfg, routes, routesDir, outDir };
+}
+
+async function handleApi(res, mod, req, ctx, secHeaders) {
+  const method = req.method.toUpperCase();
+  const handler = mod[method] || (method === 'GET' && mod.default) || mod.handler;
+  if (typeof handler !== 'function') {
+    return send(res, 405, 'application/json', JSON.stringify({ error: 'method not allowed' }), secHeaders);
+  }
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) ctx.body = await readJson(req);
+  const result = await handler(ctx);
+  if (result && 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 || {}) });
+  }
+  send(res, 200, 'application/json', JSON.stringify(result ?? null), secHeaders);
+}
+
+async function handlePage(res, mod, ctx, cfg, secHeaders) {
+  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);
+  const page = typeof out === 'string' || (out && out.__raw) ? { body: out } : (out || {});
+  const nonce = randomBytes(16).toString('base64');
+  const docHtml = renderDocument({
+    title: page.title || mod.title || cfg.name,
+    head: page.head || '',
+    body: page.body ?? '',
+    offline: cfg.offline,
+    animatedFavicon: !!cfg.animatedFavicon,
+    nonce,
+  });
+  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);
+  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,
+  });
+  send(res, 200, 'text/html; charset=utf-8', docHtml, pageHeaders(cfg, secHeaders, nonce));
+}
+
+// Per-request page headers: a fresh CSP carrying this request's script nonce, so
+// the framework's own inline <script>s run while injected scripts stay blocked.
+function pageHeaders(cfg, secHeaders, nonce) {
+  const csp = securityHeaders({ ...(cfg.security || {}), csp: { ...((cfg.security || {}).csp || {}), nonce } })['Content-Security-Policy'];
+  return { ...secHeaders, 'Content-Security-Policy': csp };
+}
+
+// Serialize props for inline injection without breaking out of the <script>.
+function safeJson(value) {
+  return JSON.stringify(value ?? {}).replace(/</g, '\\u003c').replace(/-->/g, '--\\u003e');
+}
+
+async function serveStatic(res, outDir, pathname, req, secHeaders) {
+  if (pathname === '/') return false; // let the index page route render
+  const rel = pathname.replace(/^\/+/, '');
+  const file = path.join(outDir, rel);
+  if (!file.startsWith(outDir + path.sep)) return false; // path traversal guard
+  const ae = String(req.headers['accept-encoding'] || '');
+  if (ae.includes('br') && existsSync(file + '.br')) {
+    const buf = await fs.readFile(file + '.br');
+    res.writeHead(200, { ...secHeaders, 'content-type': mime(file), 'content-encoding': 'br', 'cache-control': 'public, max-age=31536000, immutable' });
+    res.end(buf);
+    return true;
+  }
+  if (existsSync(file) && statSync(file).isFile()) {
+    const buf = await fs.readFile(file);
+    res.writeHead(200, { ...secHeaders, 'content-type': mime(file), 'cache-control': 'public, max-age=3600' });
+    res.end(buf);
+    return true;
+  }
+  return false;
+}
+
+function makeCtx(req, url, params) {
+  return {
+    req,
+    method: req.method,
+    url,
+    path: url.pathname,
+    params,
+    query: Object.fromEntries(url.searchParams),
+    headers: req.headers,
+    body: undefined,
+  };
+}
+
+function readJson(req) {
+  return new Promise((resolve) => {
+    let data = '';
+    req.on('data', (c) => { data += c; if (data.length > 2_000_000) req.destroy(); });
+    req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve({}); } });
+    req.on('error', () => resolve({}));
+  });
+}
+
+function send(res, status, contentType, body, headers = {}) {
+  res.writeHead(status, { ...headers, 'content-type': contentType });
+  res.end(body);
+}
+
+function safeDecode(p) {
+  try { return decodeURIComponent(p); } catch { return p; }
+}
+
+/** API helper: return a typed Response from a handler. */
+export function json(body, { status = 200, headers } = {}) {
+  return { __response: true, status, contentType: 'application/json', body, headers };
+}