glashjs 0.5.1 → 0.6.1

package/README.md

@@ -1,8 +1,8 @@
 # glashjs
 
-A build pipeline + runtime conventions for **fast, offline-capable, hard-to-hack** sites — the glashdb-native web framework. Built on proven primitives (not a from-scratch bundler, not a Next.js fork), so it ships real features instead of promises.
+The glashdb-native web framework, **built on top of Next.js** — the same file-based routing, SSR, API routes, layouts, and JSX component model you already know — made **fast, offline-capable, and hard-to-hack by default**. It ships real features instead of promises.
 
-> **Status:** `0.0.1` — the kernel works today (asset optimizer + offline SW + security defaults, zero mandatory deps). The full framework (routing, SSR, dev server) is on the roadmap below.
+> **Status:** `0.6.0` — the full framework is here: file-based routing, server-side rendering, API routes, JSX components with client hydration, nested layouts, streaming SSR, a dev/prod server, plus the asset optimizer, offline service worker, animated favicon, and secure-by-default headers. Core installs with zero mandatory dependencies.
 
 ## What it does today
 
@@ -90,6 +90,13 @@ import { redirect } from 'glashjs';
 export default (ctx) => { if (!ctx.headers.authorization) return redirect('/login'); };
 ```
 
+**SEO metadata** + **client-side navigation**:
+```jsx
+import { Link } from 'glashjs/link';
+export const metadata = { title: 'About', description: '…', openGraph: { image: '/og.png' } };
+export default () => <Link href="/">Home</Link>;   // SPA swap, no full reload; crawlable <a>
+```
+
 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)
@@ -148,7 +155,7 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 // animatedFavicon: { frames: ['/f0.svg','/f1.svg'], fps: 10 }
 ```
 
-## Roadmap (toward "bigger than Next")
+## What's built (built on top of Next.js)
 - [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
@@ -165,10 +172,12 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 - [x] `<Video>` — `<video>` with AV1/WebM + mp4 fallback + auto poster
 - [x] File-based middleware (`_middleware.mjs`, root→leaf) — auth, redirects, headers
 - [x] Production route precompile (`glash build` bakes server modules + minified client bundles → no runtime esbuild on `glash serve`)
+- [x] SEO metadata API (`export const metadata` → title, description, Open Graph, Twitter cards)
+- [x] `<Link>` client-side navigation (SPA swap of `#glash-root` + re-hydrate; progressive-enhancement `<a>`)
 - [ ] State-preserving fast-refresh, Suspense streaming, `glash deploy` → glashdb
 - [ ] `<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
 
 ## Design stance
-glashjs composes the best existing primitives rather than reinventing them. "Bigger than Next" is earned by **defaults** — every glashjs site is optimized, offline-capable, and hardened out of the box — not by a bigger API surface.
+glashjs is **built on top of Next.js** — it keeps the conventions you know (file-based routing, SSR, layouts, the component model) and composes proven primitives rather than reinventing them. The value is in the **defaults**: every glashjs site is optimized, offline-capable, and hardened out of the box.

package/bin/glash.mjs

@@ -4,6 +4,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';
+import { deploy } from '../src/deploy.mjs';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
@@ -32,6 +33,11 @@ async function main() {
       await build({ root: arg('--root', process.cwd()) });
       break;
     }
+    case 'deploy': {
+      const passthrough = rest.filter((a, i) => a !== '--dry-run' && a !== '--root' && rest[i - 1] !== '--root');
+      await deploy({ root: arg('--root', process.cwd()), dryRun: rest.includes('--dry-run'), args: passthrough });
+      break;
+    }
     case 'dev':
       await serve(true);
       break;
@@ -59,6 +65,7 @@ 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 deploy [--dry-run]      Build, then deploy to glashdb (hands off to the glashdb CLI)
   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.5.1",
-  "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.",
+  "version": "0.6.1",
+  "description": "glashjs — a web framework built on top of Next.js: file-based routing, SSR, API routes, JSX components with client hydration, nested layouts, streaming SSR, a best-in-class build-time asset optimizer, offline PWA layer, animated favicon, and secure-by-default headers. Zero mandatory dependencies.",
   "type": "module",
   "bin": {
     "glash": "bin/glash.mjs"
@@ -12,6 +12,7 @@
     "./security": "./src/security/headers.mjs",
     "./image": "./src/components/image.mjs",
     "./video": "./src/components/video.mjs",
+    "./link": "./src/components/link.mjs",
     "./package.json": "./package.json"
   },
   "files": [

package/src/components/link.mjs

@@ -0,0 +1,13 @@
+// glashjs <Link> — client-side navigation (SPA feel) without a full reload.
+// Renders a normal <a> tagged for the nav runtime (/_glash/nav.js), so it still
+// works with JS disabled (progressive enhancement) and is crawlable.
+//
+//   import { Link } from 'glashjs/link';
+//   <Link href="/about">About</Link>
+import { h } from 'preact';
+
+export function Link({ href, children, prefetch, class: className, ...rest }) {
+  return h('a', { href, 'data-glash-link': '', 'data-prefetch': prefetch ? '' : undefined, class: className, ...rest }, children);
+}
+
+export default Link;

package/src/deploy.mjs

@@ -0,0 +1,50 @@
+// glashjs deploy -> glashdb
+// ---------------------------------------------------------------------------
+// One command from a glashjs app to live on glashdb. It does the glashjs-aware
+// part (production build + deployable package.json scripts) and then hands off
+// to the existing glashdb CLI (npm: `glashdb`) for upload/auth — no duplicated
+// deploy logic. The platform then runs `glash build` + `glash serve`.
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { build } from './build.mjs';
+
+/** Ensure the app declares the scripts the glashdb platform runs to build/serve it. */
+async function ensureDeployScripts(root, log) {
+  const pkgPath = path.join(root, 'package.json');
+  let pkg;
+  try { pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8')); } catch { return; }
+  pkg.scripts = pkg.scripts || {};
+  let changed = false;
+  if (!pkg.scripts.build) { pkg.scripts.build = 'glash build'; changed = true; }
+  if (!pkg.scripts.start) { pkg.scripts.start = 'glash serve'; changed = true; }
+  if (changed) {
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    log('  + added build/start scripts to package.json (glash build / glash serve)');
+  }
+}
+
+export async function deploy({ root = process.cwd(), dryRun = false, args = [], log = console.log } = {}) {
+  log('glashjs deploy -> glashdb\n');
+
+  // 1. Production build (optimize assets, precompile routes, SW, security).
+  await build({ root, log });
+
+  // 2. Make sure the platform knows how to build/run the app.
+  log('');
+  await ensureDeployScripts(root, log);
+
+  // 3. Hand off to the glashdb CLI (zips + uploads, handles login).
+  const cmd = 'npx';
+  const cmdArgs = ['-y', 'glashdb', 'deploy', ...args];
+  log(`\nHanding off to the glashdb CLI:\n  $ ${cmd} ${cmdArgs.join(' ')}\n`);
+  if (dryRun) {
+    log('(dry run — build complete, not uploading)');
+    return { handoff: `${cmd} ${cmdArgs.join(' ')}`, dryRun: true };
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, cmdArgs, { cwd: root, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('exit', (code) => (code === 0 ? resolve({ code }) : reject(new Error(`glashdb deploy exited with code ${code}`))));
+  });
+}

package/src/index.mjs

@@ -10,3 +10,5 @@ export { discoverRoutes, matchRoute, findMiddleware } from './server/router.mjs'
 export { html, raw, escapeHtml, renderDocument } from './server/html.mjs';
 export { Image } from './components/image.mjs';
 export { Video } from './components/video.mjs';
+export { Link } from './components/link.mjs';
+export { renderMeta } from './server/html.mjs';

package/src/server/html.mjs

@@ -61,7 +61,37 @@ function shellTail({ offline = true, animatedFavicon = true, dev = false, nonce
   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>`;
+  // Client-side navigation runtime (external 'self' module, CSP-safe).
+  const nav = '<script type="module" src="/_glash/nav.js"></script>';
+  return `\n${fav}${off}${hmr}${nav}\n</body>\n</html>`;
+}
+
+/**
+ * Render a route's `metadata` export into <head> tags: description, robots,
+ * canonical, keywords, and Open Graph + Twitter cards — the SEO defaults Next
+ * makes you wire up by hand.
+ */
+export function renderMeta(meta = {}) {
+  if (!meta || typeof meta !== 'object') return '';
+  const tags = [];
+  const m = (name, content) => { if (content != null) tags.push(`<meta name="${escapeHtml(name)}" content="${escapeHtml(content)}">`); };
+  const p = (prop, content) => { if (content != null) tags.push(`<meta property="${escapeHtml(prop)}" content="${escapeHtml(content)}">`); };
+  m('description', meta.description);
+  m('robots', meta.robots);
+  m('keywords', Array.isArray(meta.keywords) ? meta.keywords.join(', ') : meta.keywords);
+  if (meta.canonical) tags.push(`<link rel="canonical" href="${escapeHtml(meta.canonical)}">`);
+  const og = meta.openGraph || {};
+  p('og:title', og.title || meta.title);
+  p('og:description', og.description || meta.description);
+  p('og:image', og.image);
+  p('og:url', og.url || meta.canonical);
+  p('og:type', og.type || 'website');
+  const tw = meta.twitter || {};
+  if (og.image || tw.card) m('twitter:card', tw.card || 'summary_large_image');
+  m('twitter:title', tw.title || meta.title);
+  m('twitter:description', tw.description || meta.description);
+  m('twitter:image', tw.image || og.image);
+  return tags.join('\n');
 }
 
 /** Full document (buffered). */

package/src/server/jsx.mjs

@@ -81,7 +81,7 @@ 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 Page = __p.default;', 'export const getServerData = __p.getServerData;', 'export const title = __p.title;', 'export const metadata = __p.metadata;');
   lines.push(`export const layouts = [${layouts.map((_, i) => `__L${i}`).join(',')}];`);
   return lines.join('\n');
 }

package/src/server/nav-client.mjs

@@ -0,0 +1,35 @@
+// Source for /_glash/nav.js — the client-side navigation runtime.
+// Intercepts clicks on <a data-glash-link>, fetches the route as a partial
+// (X-Glash-Nav: 1 -> JSON { title, html, props, bundle }), swaps #glash-root,
+// updates the props block + <title>, pushes history, and re-hydrates by
+// importing the new route's bundle. Falls back to a full navigation on any error.
+export const NAV_CLIENT = `// glashjs client navigation
+async function navigate(href, push) {
+  let data;
+  try {
+    const res = await fetch(href, { headers: { 'X-Glash-Nav': '1' }, credentials: 'same-origin' });
+    if (!res.ok) throw 0;
+    data = await res.json();
+  } catch { location.href = href; return; }
+  const root = document.getElementById('glash-root');
+  if (!root || !data || typeof data.html !== 'string') { location.href = href; return; }
+  if (data.title) document.title = data.title;
+  let pe = document.getElementById('glash-props');
+  if (!pe) { pe = document.createElement('script'); pe.type = 'application/json'; pe.id = 'glash-props'; document.head.appendChild(pe); }
+  pe.textContent = JSON.stringify(data.props || {});
+  root.innerHTML = data.html;
+  if (push) history.pushState({ glash: 1 }, '', href);
+  window.scrollTo(0, 0);
+  if (data.bundle) { try { await import(data.bundle); } catch {} }
+}
+document.addEventListener('click', (e) => {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+  const a = e.target.closest && e.target.closest('a[data-glash-link]');
+  if (!a) return;
+  const href = a.getAttribute('href');
+  if (!href || a.target || /^([a-z]+:)?\\/\\//i.test(href) || href.startsWith('#') || href.startsWith('mailto:')) return;
+  e.preventDefault();
+  if (href !== location.pathname + location.search) navigate(href, true);
+});
+window.addEventListener('popstate', () => navigate(location.pathname + location.search, false));
+`;

package/src/server/server.mjs

@@ -11,7 +11,8 @@ import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { discoverRoutes, matchRoute, findMiddleware } from './router.mjs';
-import { renderDocument, documentParts } from './html.mjs';
+import { renderDocument, documentParts, renderMeta } from './html.mjs';
+import { NAV_CLIENT } from './nav-client.mjs';
 import { isComponentRoute, loadComponentRoute, clientBundle, renderComponent, routeId, findLayouts, clearJsxCaches } from './jsx.mjs';
 import { securityHeaders } from '../security/headers.mjs';
 import { loadConfig } from '../config.mjs';
@@ -61,6 +62,10 @@ export async function createGlashServer({ root = process.cwd(), dev = false } =
         req.on('close', () => hmrClients.delete(res));
         return;
       }
+      // Client-side navigation runtime.
+      if (pathname === '/_glash/nav.js') {
+        return send(res, 200, 'text/javascript; charset=utf-8', NAV_CLIENT, { ...secHeaders, 'cache-control': dev ? 'no-store' : 'public, max-age=31536000, immutable' });
+      }
       // Static first: in production this serves prebuilt /_glash/<id>.js bundles
       // (written by `glash build`) — no runtime esbuild needed.
       if (await serveStatic(res, outDir, pathname, req, secHeaders)) return;
@@ -125,9 +130,10 @@ async function handlePage(res, mod, ctx, cfg, secHeaders, dev) {
   const out = await render(ctx);
   const page = typeof out === 'string' || (out && out.__raw) ? { body: out } : (out || {});
   const nonce = randomBytes(16).toString('base64');
+  const meta = await resolveMeta(page.metadata || mod.metadata, ctx);
   const docHtml = renderDocument({
-    title: page.title || mod.title || cfg.name,
-    head: page.head || '',
+    title: meta.title || page.title || mod.title || cfg.name,
+    head: renderMeta(meta) + (page.head ? (page.head.__raw || page.head) : ''),
     body: page.body ?? '',
     offline: cfg.offline,
     animatedFavicon: !!cfg.animatedFavicon,
@@ -141,12 +147,22 @@ async function handleComponentPage(res, route, ctx, cfg, secHeaders, root, route
   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 meta = await resolveMeta(mod.metadata, ctx);
+  const title = meta.title || mod.title || cfg.name;
+
+  // Client-side navigation: return the route as a partial (no full document),
+  // so <Link> can swap #glash-root and re-hydrate without a full reload.
+  if (String(ctx.headers['x-glash-nav'] || '') === '1') {
+    const rendered = await renderComponent(mod, props);
+    return send(res, 200, 'application/json', JSON.stringify({ title, html: rendered, props, bundle: `/_glash/${id}.js` }), secHeaders);
+  }
+
   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 head = renderMeta(meta) + `<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,
+    title, 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
@@ -155,6 +171,12 @@ async function handleComponentPage(res, route, ctx, cfg, secHeaders, root, route
   res.end(tail);
 }
 
+// metadata export may be a plain object or a (ctx) => object function.
+async function resolveMeta(metadata, ctx) {
+  if (typeof metadata === 'function') return (await metadata(ctx)) || {};
+  return metadata && typeof metadata === 'object' ? metadata : {};
+}
+
 // 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) {