glashjs 0.1.0 → 0.3.0

package/README.md

@@ -77,7 +77,24 @@ 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. **Honest scope:** this is real SSR of HTML (render functions) — React/JSX components with client hydration, layouts/nested routing, client-JS bundling, and HMR are the next milestones (below).
+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'`).
+
+**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
 
@@ -126,8 +143,12 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 - [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
-- [ ] React/JSX components + client hydration, nested layouts, streaming SSR
-- [ ] Client-JS bundling + HMR (on esbuild/Vite)
+- [x] JSX components + client-side hydration (Preact + esbuild) — CSP-safe with nonces
+- [x] Client-JS bundling (esbuild) per route
+- [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)
+- [ ] State-preserving fast-refresh (HMR), Suspense streaming, `<Image>`/`<Video>` components
 - [ ] `<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.1.0",
+  "version": "0.3.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": {
@@ -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": [
@@ -44,5 +55,10 @@
     "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/server/html.mjs

@@ -33,23 +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,
-} = {}) {
+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 fav = animatedFavicon
-    ? '<script type="module">try{const m=await import("/glash-favicon.mjs");m.startGlashFavicon&&m.startGlashFavicon();}catch{}</script>'
-    : '';
-  const off = offline
-    ? '<script type="module">try{const m=await import("/glash-offline.mjs");m.registerGlashOffline&&m.registerGlashOffline();}catch{}</script>'
-    : '';
   return `<!doctype html>
 <html lang="${escapeHtml(lang)}">
 <head>
@@ -61,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

@@ -0,0 +1,150 @@
+// 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, existsSync } 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();
+
+/** 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);
+  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({
+    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',
+  });
+  const mod = await import(pathToFileURL(out).href + (dev ? `?t=${Date.now()}` : ''));
+  if (!dev) serverCache.set(id, mod);
+  return mod;
+}
+
+/** 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);
+  const id = compId(pageFile, layouts);
+  if (!dev && clientCache.has(id)) return clientCache.get(id);
+  const res = await eb.build({
+    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(id, js);
+  return js;
+}
+
+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.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

@@ -15,7 +15,9 @@ export async function discoverRoutes(routesDir) {
   const files = [];
   await walk(root, root, files);
   const routes = files
-    .filter((f) => /\.(mjs|js)$/.test(f.rel))
+    .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);
@@ -33,7 +35,7 @@ async function walk(root, dir, out) {
 }
 
 function toRoute(rel, file) {
-  const clean = rel.replace(/\.(mjs|js)$/, '');
+  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)) {

package/src/server/server.mjs

@@ -6,11 +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 { 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';
 
@@ -34,19 +36,52 @@ 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 (await serveStatic(res, outDir, pathname, req, secHeaders)) return;
       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, 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 mod = await importRoute(match.route.file);
       const ctx = makeCtx(req, url, match.params);
-      return match.route.isApi
-        ? await handleApi(res, mod, req, ctx, secHeaders)
-        : await handlePage(res, mod, ctx, cfg, 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, routesDir, dev);
+      }
+      const mod = await importRoute(match.route.file);
+      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);
@@ -74,19 +109,52 @@ 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);
   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, dev,
   });
-  send(res, page.status || 200, 'text/html; charset=utf-8', docHtml, { ...secHeaders, ...(page.headers || {}) });
+  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, 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 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 { open, tail } = documentParts({
+    title: mod.title || cfg.name, head, offline: cfg.offline, animatedFavicon: !!cfg.animatedFavicon, nonce, dev,
+  });
+  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
+// 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) {