blumenjs 0.2.0 → 0.2.1

package/dist/cli/blumen.js

@@ -243,7 +243,7 @@ async function dev() {
       label: " go",
       color: c.green,
       cmd: "go",
-      args: ["run", "go-server/main.go", "go-server/image.go", "go-server/cache.go"],
+      args: ["run", "./go-server/"],
       readyPattern: /Go server starting/
     }
   ];
@@ -341,7 +341,13 @@ async function build(args = []) {
     },
     {
       label: "Building SSR server",
-      cmd: "npx esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external"
+      cmd: "npx esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external --alias:@=./app"
+    },
+    {
+      label: "Pre-rendering static pages (SSG)",
+      cmd: "npx tsx scripts/ssg-prerender.ts",
+      optional: true
+      // Don't fail if no SSG pages exist
     }
   ];
   const startTime = Date.now();
@@ -356,8 +362,12 @@ async function build(args = []) {
       });
       log.success(step.label);
     } catch {
-      log.error(`Failed: ${step.label}`);
-      process.exit(1);
+      if (step.optional) {
+        log.success(step.label);
+      } else {
+        log.error(`Failed: ${step.label}`);
+        process.exit(1);
+      }
     }
   }
   const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
@@ -401,7 +411,7 @@ async function start() {
       label: " go",
       color: c.green,
       cmd: "go",
-      args: ["run", "go-server/main.go", "go-server/image.go", "go-server/cache.go"],
+      args: ["run", "./go-server/"],
       readyPattern: /Go server starting/
     }
   ];

package/dist/cli/commands/build.js

@@ -81,7 +81,13 @@ async function build(args = []) {
     },
     {
       label: "Building SSR server",
-      cmd: "npx esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external"
+      cmd: "npx esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external --alias:@=./app"
+    },
+    {
+      label: "Pre-rendering static pages (SSG)",
+      cmd: "npx tsx scripts/ssg-prerender.ts",
+      optional: true
+      // Don't fail if no SSG pages exist
     }
   ];
   const startTime = Date.now();
@@ -96,8 +102,12 @@ async function build(args = []) {
       });
       log.success(step.label);
     } catch {
-      log.error(`Failed: ${step.label}`);
-      process.exit(1);
+      if (step.optional) {
+        log.success(step.label);
+      } else {
+        log.error(`Failed: ${step.label}`);
+        process.exit(1);
+      }
     }
   }
   const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);

package/dist/cli/commands/dev.js

@@ -218,7 +218,7 @@ async function dev() {
       label: " go",
       color: c.green,
       cmd: "go",
-      args: ["run", "go-server/main.go", "go-server/image.go", "go-server/cache.go"],
+      args: ["run", "./go-server/"],
       readyPattern: /Go server starting/
     }
   ];

package/dist/cli/commands/start.js

@@ -87,7 +87,7 @@ async function start() {
       label: " go",
       color: c.green,
       cmd: "go",
-      args: ["run", "go-server/main.go", "go-server/image.go", "go-server/cache.go"],
+      args: ["run", "./go-server/"],
       readyPattern: /Go server starting/
     }
   ];

package/dist/templates/app/pages/BlumenStarter.tsx

@@ -316,7 +316,7 @@ const HomePage: React.FC<HomeProps> = () => {
 				<div className="blumen-content">
 					<div className="blumen-badge">
 						<span className="blumen-badge-dot" />
-						Framework v0.1.0
+						Framework v0.2.0
 					</div>
 
 					<h1 className="blumen-logo">🌸 Blumen</h1>

package/dist/templates/app/shared/DefaultDocument.tsx

@@ -1,5 +1,22 @@
 import React from "react";
 
+/**
+ * Sanitize data for safe embedding in a <script type="application/json"> tag.
+ * Escapes all characters that could break out of the JSON context:
+ * - `<` → `\u003c` (prevents </script> injection)
+ * - `>` → `\u003e` (prevents HTML entity injection)
+ * - `&` → `\u0026` (prevents HTML entity injection)
+ * - U+2028 → `\u2028` (line separator - breaks JS in some contexts)
+ * - U+2029 → `\u2029` (paragraph separator - breaks JS in some contexts)
+ */
+function sanitizeForHydration(data: any): string {
+    return JSON.stringify(data)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
 // HMR: In development, load the client bundle from Webpack Dev Server
 // so the HMR runtime + React Fast Refresh are active.
 const isDev = process.env.NODE_ENV === "development";
@@ -7,7 +24,7 @@ const BUNDLE_SRC = isDev
     ? "http://localhost:3100/static/js/bundle.js"
     : "/static/js/bundle.js";
 
-export function DefaultDocument({ children, initialProps }: any) {
+export function DefaultDocument({ children, initialProps, metadata }: any) {
     const css = `
         * { margin: 0; padding: 0; box-sizing: border-box; }
         body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif; line-height: 1.6; color: #e2e8f0; background: #1a1025; }
@@ -51,13 +68,41 @@ export function DefaultDocument({ children, initialProps }: any) {
         .page-transition-exit { opacity: 0; transition: opacity 150ms ease-out; }
     `;
 
+    // Resolve metadata with defaults
+    const meta = metadata || {};
+    const title = meta.title || "Blumen App";
+    const description = meta.description || "";
+    const og = meta.openGraph || {};
+    const tw = meta.twitter || {};
+
     return (
         <html lang="en">
             <head>
                 <meta charSet="UTF-8" />
                 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-                <meta name="description" content="SSR Go + React - Minimal Production-Quality SSR Engine" />
-                <title>SSR Go + React</title>
+                <title>{title}</title>
+                {description && <meta name="description" content={description} />}
+                {meta.keywords?.length && <meta name="keywords" content={meta.keywords.join(", ")} />}
+                {meta.robots && <meta name="robots" content={meta.robots} />}
+                {meta.canonical && <link rel="canonical" href={meta.canonical} />}
+                {/* Open Graph */}
+                {og.title && <meta property="og:title" content={og.title} />}
+                {og.description && <meta property="og:description" content={og.description} />}
+                {og.image && <meta property="og:image" content={og.image} />}
+                {og.url && <meta property="og:url" content={og.url} />}
+                {og.type && <meta property="og:type" content={og.type} />}
+                {og.siteName && <meta property="og:site_name" content={og.siteName} />}
+                {/* Twitter Card */}
+                {tw.card && <meta name="twitter:card" content={tw.card} />}
+                {tw.title && <meta name="twitter:title" content={tw.title} />}
+                {tw.description && <meta name="twitter:description" content={tw.description} />}
+                {tw.image && <meta name="twitter:image" content={tw.image} />}
+                {tw.creator && <meta name="twitter:creator" content={tw.creator} />}
+                {tw.site && <meta name="twitter:site" content={tw.site} />}
+                {/* Custom meta tags */}
+                {meta.other && Object.entries(meta.other).map(([name, content]: [string, any]) => (
+                    <meta key={name} name={name} content={content} />
+                ))}
                 <style dangerouslySetInnerHTML={{ __html: css }} />
             </head>
             <body>
@@ -66,7 +111,7 @@ export function DefaultDocument({ children, initialProps }: any) {
                     id="ssr-props"
                     type="application/json"
                     dangerouslySetInnerHTML={{
-                        __html: JSON.stringify(initialProps).replace(/</g, '\\u003c')
+                        __html: sanitizeForHydration(initialProps)
                     }}
                 />
                 <script src={BUNDLE_SRC} defer></script>

package/dist/templates/app/shared/Link.tsx

@@ -5,21 +5,26 @@
  * External links, new-tab links, and modified clicks (ctrl/cmd)
  * are passed through to the browser as normal.
  *
- * During SSR (no RouterProvider), renders a plain <a> tag.
+ * Prefetching:
+ *   - On hover: preloads page data so navigation is instant
+ *   - On viewport: uses IntersectionObserver to prefetch when visible
+ *   - Set prefetch={false} to disable for specific links
  *
- * @example
- * <Link href="/about" className="nav-link">About</Link>
+ * During SSR (no RouterProvider), renders a plain <a> tag.
  */
 
-import React, { useContext } from "react";
+import React, { useContext, useRef, useEffect, useCallback } from "react";
 
 // Import the context directly to do a safe check without throwing
 // We need the raw context object, not the hook
 import { RouterContextRef, useRouter } from "./RouterContext";
+import { prefetch as prefetchData } from "./prefetchCache";
 
 interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
 	/** The destination path */
 	href: string;
+	/** Enable/disable prefetching. Defaults to true. Set to false for rarely-visited links. */
+	prefetch?: boolean;
 }
 
 function isExternal(href: string): boolean {
@@ -30,9 +35,51 @@ function isModifiedClick(e: React.MouseEvent): boolean {
 	return e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0;
 }
 
-export function Link({ href, children, onClick, target, ...rest }: LinkProps) {
+export function Link({ href, children, onClick, target, prefetch = true, ...rest }: LinkProps) {
 	// Safe check: if we're in SSR (no provider), just render a plain <a>
 	const ctx = useContext(RouterContextRef);
+	const anchorRef = useRef<HTMLAnchorElement>(null);
+	const hasPrefetched = useRef(false);
+
+	// Determine if this is a local link that can be prefetched
+	const isLocal = !isExternal(href) && target !== "_blank";
+
+	// ── Hover prefetch ───────────────────────────────────────────
+	const handleMouseEnter = useCallback(() => {
+		if (!isLocal || !prefetch || hasPrefetched.current) return;
+		hasPrefetched.current = true;
+		prefetchData(href);
+	}, [href, isLocal, prefetch]);
+
+	// ── Viewport prefetch (IntersectionObserver) ─────────────────
+	useEffect(() => {
+		if (!isLocal || !prefetch || !anchorRef.current) return;
+		if (typeof IntersectionObserver === "undefined") return;
+
+		const el = anchorRef.current;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting && !hasPrefetched.current) {
+						hasPrefetched.current = true;
+						prefetchData(href);
+						observer.unobserve(el);
+					}
+				}
+			},
+			{
+				// Start prefetching when the link is within 200px of the viewport
+				rootMargin: "200px",
+			},
+		);
+
+		observer.observe(el);
+
+		return () => {
+			observer.unobserve(el);
+		};
+	}, [href, isLocal, prefetch]);
 
 	if (!ctx) {
 		// SSR fallback — no router available
@@ -64,7 +111,14 @@ export function Link({ href, children, onClick, target, ...rest }: LinkProps) {
 	};
 
 	return (
-		<a href={href} onClick={handleClick} target={target} {...rest}>
+		<a
+			ref={anchorRef}
+			href={href}
+			onClick={handleClick}
+			onMouseEnter={handleMouseEnter}
+			target={target}
+			{...rest}
+		>
 			{children}
 		</a>
 	);

package/dist/templates/app/shared/RouterContext.tsx

@@ -17,6 +17,9 @@ import React, {
 } from "react";
 import { matchRoute, type RouteDef } from "./router";
 import { BlumenErrorBoundary } from "./ErrorBoundary";
+import { applyMetadata } from "./BlumenHead";
+import { consumeCached } from "./prefetchCache";
+import DefaultLoading from "./DefaultLoading";
 
 // ── Context types ──────────────────────────────────────────────
 
@@ -74,6 +77,8 @@ export function RouterProvider({
 		() => window.location.pathname,
 	);
 	const [transitioning, setTransitioning] = useState(false);
+	const [isLoading, setIsLoading] = useState(false);
+	const [loadingComponent, setLoadingComponent] = useState<React.ComponentType<any> | null>(null);
 	const [dynamicProps, setDynamicProps] = useState<Record<string, any>>({});
 
 	// Track whether we're on the very first render (SSR hydration).
@@ -110,25 +115,48 @@ export function RouterProvider({
 			// Animate out → change route → animate in
 			setTransitioning(true);
 
-			// Fetch dynamic data from Go server
-			const fetchPromise = fetch(to, {
-				headers: { "X-Blumen-Data": "1" }
-			}).then(res => res.ok ? res.json() : {}).catch(err => {
-				console.error("Failed to fetch route data", err);
-				return {};
-			});
+			// Check prefetch cache first (populated by <Link> on hover)
+			const cached = consumeCached(to);
+
+			// Determine the loading component for the target route
+			const targetMatch = matchRoute(to, routes);
+			const targetLoading = targetMatch?.loading || null;
+
+			// If we don't have cached data and route has a loading component, show it
+			if (!cached && targetLoading) {
+				setLoadingComponent(() => targetLoading);
+				setIsLoading(true);
+			}
+
+			// Fetch dynamic data from Go server (or use cached data)
+			const fetchPromise = cached
+				? Promise.resolve(cached)
+				: fetch(to, {
+					headers: { "X-Blumen-Data": "1" }
+				}).then(res => res.ok ? res.json() : {}).catch(err => {
+					console.error("Failed to fetch route data", err);
+					return {};
+				});
 
 			// Allow the exit transition to play (150ms)
 			const delayPromise = new Promise(resolve => setTimeout(resolve, 150));
 
-			Promise.all([fetchPromise, delayPromise]).then(([newData]) => {
+			Promise.all([fetchPromise, delayPromise]).then(([newData]: any[]) => {
 				setDynamicProps(newData);
+
+				// Update <head> metadata for the new page
+				if (newData?.metadata) {
+					applyMetadata(newData.metadata);
+				}
+
 				window.history.pushState(null, "", to);
 				setPath(to);
 				window.scrollTo(0, 0);
 
-				// Small delay for the enter transition
+				// Clear loading state and transition
 				requestAnimationFrame(() => {
+					setIsLoading(false);
+					setLoadingComponent(null);
 					setTransitioning(false);
 				});
 			});
@@ -142,17 +170,38 @@ export function RouterProvider({
 			setTransitioning(true);
 			const to = window.location.pathname;
 
-			const fetchPromise = fetch(to, {
-				headers: { "X-Blumen-Data": "1" }
-			}).then(res => res.ok ? res.json() : {}).catch(() => ({}));
+			// Check prefetch cache for back/forward navigation
+			const cached = consumeCached(to);
+
+			// Show loading component if available
+			if (!cached) {
+				const targetMatch = matchRoute(to, routes);
+				if (targetMatch?.loading) {
+					setLoadingComponent(() => targetMatch.loading!);
+					setIsLoading(true);
+				}
+			}
+
+			const fetchPromise = cached
+				? Promise.resolve(cached)
+				: fetch(to, {
+					headers: { "X-Blumen-Data": "1" }
+				}).then(res => res.ok ? res.json() : {}).catch(() => ({}));
 			
 			const delayPromise = new Promise(resolve => setTimeout(resolve, 150));
 
-			Promise.all([fetchPromise, delayPromise]).then(([newData]) => {
+			Promise.all([fetchPromise, delayPromise]).then(([newData]: any[]) => {
 				setDynamicProps(newData);
 				setPath(to);
+
+				// Update <head> metadata for the new page
+				if (newData?.metadata) {
+					applyMetadata(newData.metadata);
+				}
 				
 				requestAnimationFrame(() => {
+					setIsLoading(false);
+					setLoadingComponent(null);
 					setTransitioning(false);
 				});
 			});
@@ -165,15 +214,26 @@ export function RouterProvider({
 	// ── Render ──────────────────────────────────────────────────
 	const contextValue: RouterContextValue = { path, params, navigate };
 
+	// Determine what to render:
+	// 1. If loading — show the loading component
+	// 2. Otherwise — show the page component
+	const LoadingComp = loadingComponent;
+
 	return (
 		<RouterContext.Provider value={contextValue}>
-			<div
-				className={`page-transition ${transitioning ? "page-transition-exit" : "page-transition-active"}`}
-			>
-				<BlumenErrorBoundary>
-					<App Component={PageComponent} pageProps={pageProps} />
-				</BlumenErrorBoundary>
-			</div>
+			{isLoading && LoadingComp ? (
+				<div className="page-transition page-transition-active">
+					<LoadingComp />
+				</div>
+			) : (
+				<div
+					className={`page-transition ${transitioning ? "page-transition-exit" : "page-transition-active"}`}
+				>
+					<BlumenErrorBoundary>
+						<App Component={PageComponent} pageProps={pageProps} />
+					</BlumenErrorBoundary>
+				</div>
+			)}
 		</RouterContext.Provider>
 	);
 }

package/dist/templates/app/shared/router.ts

@@ -3,6 +3,7 @@ export interface RouteDef {
 	pattern: RegExp;
 	keys: string[];
 	component: React.ComponentType<any>;
+	loading?: React.ComponentType<any>;
 }
 
 export function matchRoute(path: string, routes: RouteDef[]) {
@@ -16,7 +17,7 @@ export function matchRoute(path: string, routes: RouteDef[]) {
 			route.keys.forEach((key: string, index: number) => {
 				params[key] = match[index + 1];
 			});
-			return { component: route.component, params };
+			return { component: route.component, params, loading: route.loading };
 		}
 	}
 	return null;