blumenjs 0.2.5 → 0.2.6

package/dist/cli/blumen.js

@@ -838,11 +838,32 @@ function getTemplateFiles(projectName, template) {
     // Complex files — copied from the framework source
     ["app/shared/RouterContext.tsx", readProjectFile("app/shared/RouterContext.tsx")],
     ["app/shared/router.ts", readProjectFile("app/shared/router.ts")],
+    ["app/shared/ErrorBoundary.tsx", readProjectFile("app/shared/ErrorBoundary.tsx")],
+    ["app/shared/BlumenHead.tsx", readProjectFile("app/shared/BlumenHead.tsx")],
+    ["app/shared/prefetchCache.ts", readProjectFile("app/shared/prefetchCache.ts")],
+    ["app/shared/DefaultLoading.tsx", readProjectFile("app/shared/DefaultLoading.tsx")],
+    ["app/shared/serverAction.ts", readProjectFile("app/shared/serverAction.ts")],
+    ["app/shared/types.ts", readProjectFile("app/shared/types.ts")],
+    ["app/shared/useServerAction.ts", readProjectFile("app/shared/useServerAction.ts")],
+    ["app/shared/api.ts", readProjectFile("app/shared/api.ts")],
+    ["app/shared/useWebSocket.ts", readProjectFile("app/shared/useWebSocket.ts")],
+    ["app/shared/i18n.ts", readProjectFile("app/shared/i18n.ts")],
+    ["app/shared/blumenConfig.ts", readProjectFile("app/shared/blumenConfig.ts")],
+    ["app/shared/BlumenImage.tsx", readProjectFile("app/shared/BlumenImage.tsx")],
     ["app/client/entry.tsx", readProjectFile("app/client/entry.tsx")],
     ["node-ssr/server.ts", readProjectFile("node-ssr/server.ts")],
     ["go-server/main.go", readProjectFile("go-server/main.go")],
+    ["go-server/image.go", readProjectFile("go-server/image.go")],
+    ["go-server/cache.go", readProjectFile("go-server/cache.go")],
+    ["go-server/websocket.go", readProjectFile("go-server/websocket.go")],
+    ["go-server/middleware.go", readProjectFile("go-server/middleware.go")],
+    ["go-server/ssg.go", readProjectFile("go-server/ssg.go")],
+    ["go-server/redirects.go", readProjectFile("go-server/redirects.go")],
+    ["go-server/actions.go", readProjectFile("go-server/actions.go")],
     ["scripts/generate-routes.ts", readProjectFile("scripts/generate-routes.ts")],
     ["scripts/generate-api-routes.ts", readProjectFile("scripts/generate-api-routes.ts")],
+    ["go.mod", readProjectFile("go.mod")],
+    ["go.sum", readProjectFile("go.sum")],
     // Placeholder
     ["static/js/.gitkeep", ""],
     // Docker support (production deployment)

package/dist/cli/commands/create.js

@@ -522,11 +522,32 @@ function getTemplateFiles(projectName, template) {
     // Complex files — copied from the framework source
     ["app/shared/RouterContext.tsx", readProjectFile("app/shared/RouterContext.tsx")],
     ["app/shared/router.ts", readProjectFile("app/shared/router.ts")],
+    ["app/shared/ErrorBoundary.tsx", readProjectFile("app/shared/ErrorBoundary.tsx")],
+    ["app/shared/BlumenHead.tsx", readProjectFile("app/shared/BlumenHead.tsx")],
+    ["app/shared/prefetchCache.ts", readProjectFile("app/shared/prefetchCache.ts")],
+    ["app/shared/DefaultLoading.tsx", readProjectFile("app/shared/DefaultLoading.tsx")],
+    ["app/shared/serverAction.ts", readProjectFile("app/shared/serverAction.ts")],
+    ["app/shared/types.ts", readProjectFile("app/shared/types.ts")],
+    ["app/shared/useServerAction.ts", readProjectFile("app/shared/useServerAction.ts")],
+    ["app/shared/api.ts", readProjectFile("app/shared/api.ts")],
+    ["app/shared/useWebSocket.ts", readProjectFile("app/shared/useWebSocket.ts")],
+    ["app/shared/i18n.ts", readProjectFile("app/shared/i18n.ts")],
+    ["app/shared/blumenConfig.ts", readProjectFile("app/shared/blumenConfig.ts")],
+    ["app/shared/BlumenImage.tsx", readProjectFile("app/shared/BlumenImage.tsx")],
     ["app/client/entry.tsx", readProjectFile("app/client/entry.tsx")],
     ["node-ssr/server.ts", readProjectFile("node-ssr/server.ts")],
     ["go-server/main.go", readProjectFile("go-server/main.go")],
+    ["go-server/image.go", readProjectFile("go-server/image.go")],
+    ["go-server/cache.go", readProjectFile("go-server/cache.go")],
+    ["go-server/websocket.go", readProjectFile("go-server/websocket.go")],
+    ["go-server/middleware.go", readProjectFile("go-server/middleware.go")],
+    ["go-server/ssg.go", readProjectFile("go-server/ssg.go")],
+    ["go-server/redirects.go", readProjectFile("go-server/redirects.go")],
+    ["go-server/actions.go", readProjectFile("go-server/actions.go")],
     ["scripts/generate-routes.ts", readProjectFile("scripts/generate-routes.ts")],
     ["scripts/generate-api-routes.ts", readProjectFile("scripts/generate-api-routes.ts")],
+    ["go.mod", readProjectFile("go.mod")],
+    ["go.sum", readProjectFile("go.sum")],
     // Placeholder
     ["static/js/.gitkeep", ""],
     // Docker support (production deployment)

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

@@ -0,0 +1,157 @@
+/**
+ * BlumenHead — Client-side <head> tag manager.
+ *
+ * Updates document.title and manages <meta> tags on the client.
+ * Used internally by the router for SPA navigations, and available
+ * to developers as an escape hatch for imperative head control.
+ *
+ * On the server, this component renders nothing — the Document
+ * component handles <head> rendering during SSR.
+ *
+ * @example
+ * ```tsx
+ * import { BlumenHead } from '../shared/BlumenHead';
+ *
+ * export default function MyPage() {
+ *     return (
+ *         <>
+ *             <BlumenHead
+ *                 title="My Page | My App"
+ *                 description="A great page"
+ *             />
+ *             <div>Page content</div>
+ *         </>
+ *     );
+ * }
+ * ```
+ */
+
+import React, { useEffect } from "react";
+import type { BlumenMetadata } from "./types";
+
+// Marker attribute to identify tags managed by BlumenHead
+const BLUMEN_HEAD_ATTR = "data-blumen-head";
+
+/**
+ * Apply metadata to the document <head>.
+ * Can be called from React effects or from the router.
+ */
+export function applyMetadata(metadata: BlumenMetadata): void {
+	if (typeof document === "undefined") return;
+
+	// Update title
+	if (metadata.title) {
+		document.title = metadata.title;
+	}
+
+	// Remove all previously managed tags
+	const existing = document.querySelectorAll(`[${BLUMEN_HEAD_ATTR}]`);
+	existing.forEach((el) => el.remove());
+
+	const head = document.head;
+
+	// Helper to add a meta tag
+	const addMeta = (name: string, content: string) => {
+		const tag = document.createElement("meta");
+		tag.setAttribute("name", name);
+		tag.setAttribute("content", content);
+		tag.setAttribute(BLUMEN_HEAD_ATTR, "true");
+		head.appendChild(tag);
+	};
+
+	// Helper to add an OG/Twitter meta tag (uses property instead of name)
+	const addProperty = (property: string, content: string) => {
+		const tag = document.createElement("meta");
+		tag.setAttribute("property", property);
+		tag.setAttribute("content", content);
+		tag.setAttribute(BLUMEN_HEAD_ATTR, "true");
+		head.appendChild(tag);
+	};
+
+	// Description
+	if (metadata.description) {
+		addMeta("description", metadata.description);
+	}
+
+	// Keywords
+	if (metadata.keywords?.length) {
+		addMeta("keywords", metadata.keywords.join(", "));
+	}
+
+	// Robots
+	if (metadata.robots) {
+		addMeta("robots", metadata.robots);
+	}
+
+	// Canonical
+	if (metadata.canonical) {
+		const link = document.createElement("link");
+		link.setAttribute("rel", "canonical");
+		link.setAttribute("href", metadata.canonical);
+		link.setAttribute(BLUMEN_HEAD_ATTR, "true");
+		head.appendChild(link);
+	}
+
+	// Open Graph
+	if (metadata.openGraph) {
+		const og = metadata.openGraph;
+		if (og.title) addProperty("og:title", og.title);
+		if (og.description) addProperty("og:description", og.description);
+		if (og.image) addProperty("og:image", og.image);
+		if (og.url) addProperty("og:url", og.url);
+		if (og.type) addProperty("og:type", og.type);
+		if (og.siteName) addProperty("og:site_name", og.siteName);
+	}
+
+	// Twitter Card
+	if (metadata.twitter) {
+		const tw = metadata.twitter;
+		if (tw.card) addMeta("twitter:card", tw.card);
+		if (tw.title) addMeta("twitter:title", tw.title);
+		if (tw.description) addMeta("twitter:description", tw.description);
+		if (tw.image) addMeta("twitter:image", tw.image);
+		if (tw.creator) addMeta("twitter:creator", tw.creator);
+		if (tw.site) addMeta("twitter:site", tw.site);
+	}
+
+	// Custom meta tags
+	if (metadata.other) {
+		for (const [name, content] of Object.entries(metadata.other)) {
+			addMeta(name, content);
+		}
+	}
+}
+
+/**
+ * BlumenHead component — declarative head management.
+ *
+ * Accepts the same shape as BlumenMetadata. Updates <head> on mount
+ * and cleans up on unmount. SSR-safe (renders nothing on the server).
+ */
+export function BlumenHead(props: BlumenMetadata) {
+	useEffect(() => {
+		applyMetadata(props);
+
+		// Cleanup: remove managed tags when component unmounts
+		return () => {
+			if (typeof document === "undefined") return;
+			const managed = document.querySelectorAll(`[${BLUMEN_HEAD_ATTR}]`);
+			managed.forEach((el) => el.remove());
+		};
+	}, [
+		props.title,
+		props.description,
+		props.canonical,
+		props.robots,
+		props.keywords?.join(","),
+		props.openGraph?.title,
+		props.openGraph?.description,
+		props.openGraph?.image,
+		props.twitter?.card,
+		props.twitter?.title,
+		props.twitter?.image,
+	]);
+
+	// Render nothing — head mutations are side effects
+	return null;
+}

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

@@ -0,0 +1,209 @@
+import React, { useState, useRef, useEffect } from "react";
+
+/**
+ * BlumenImage - Optimized image component for BlumenJS.
+ *
+ * Features:
+ * - Automatic responsive srcset generation
+ * - Lazy loading by default (disable with `priority`)
+ * - WebP/AVIF format negotiation via the Go image endpoint
+ * - Blur placeholder (LQIP) fade-in effect
+ * - On-the-fly server-side resizing and caching
+ *
+ * @example
+ * ```tsx
+ * import { BlumenImage } from '../../shared/BlumenImage';
+ *
+ * <BlumenImage
+ *   src="/static/hero.jpg"
+ *   alt="Hero banner"
+ *   width={1200}
+ *   height={600}
+ *   quality={80}
+ *   priority  // Above-the-fold: skip lazy loading
+ * />
+ * ```
+ */
+
+// Default responsive breakpoints (matches common device widths)
+const DEFAULT_WIDTHS = [640, 750, 828, 1080, 1200, 1920, 2048];
+
+interface BlumenImageProps {
+	/** Source path relative to the project root (e.g. "/static/hero.jpg") */
+	src: string;
+	/** Alt text for accessibility */
+	alt: string;
+	/** Display width in pixels */
+	width: number;
+	/** Display height in pixels */
+	height: number;
+	/** Image quality (1-100, default: 80) */
+	quality?: number;
+	/** If true, disables lazy loading and loads immediately (use for above-the-fold images) */
+	priority?: boolean;
+	/** Object-fit CSS property (default: "cover") */
+	fit?: "cover" | "contain" | "fill" | "none";
+	/** Additional CSS class name */
+	className?: string;
+	/** Custom responsive widths for srcset generation */
+	sizes?: string;
+	/** Inline style overrides */
+	style?: React.CSSProperties;
+	/** Border radius */
+	borderRadius?: string | number;
+}
+
+/**
+ * Build the optimized image URL using the Go /_blumen/image endpoint.
+ */
+function buildImageUrl(
+	src: string,
+	width: number,
+	quality: number,
+): string {
+	// If src is already an external URL, return as-is
+	if (src.startsWith("http://") || src.startsWith("https://")) {
+		return src;
+	}
+	return `/_blumen/image?src=${encodeURIComponent(src)}&w=${width}&q=${quality}`;
+}
+
+/**
+ * Generate a tiny blur data URI for the placeholder.
+ * Uses the Go endpoint with a very small width.
+ */
+function buildBlurUrl(src: string): string {
+	if (src.startsWith("http://") || src.startsWith("https://")) {
+		return src;
+	}
+	return `/_blumen/image?src=${encodeURIComponent(src)}&w=20&q=30&blur=1`;
+}
+
+export function BlumenImage({
+	src,
+	alt,
+	width,
+	height,
+	quality = 80,
+	priority = false,
+	fit = "cover",
+	className = "",
+	sizes,
+	style,
+	borderRadius,
+}: BlumenImageProps) {
+	const [loaded, setLoaded] = useState(false);
+	const [error, setError] = useState(false);
+	const imgRef = useRef<HTMLImageElement>(null);
+
+	// Generate the primary optimized URL
+	const optimizedSrc = buildImageUrl(src, width, quality);
+
+	// Generate srcset for responsive images
+	const srcsetWidths = DEFAULT_WIDTHS.filter((w) => w <= width * 2);
+	if (!srcsetWidths.includes(width)) {
+		srcsetWidths.push(width);
+		srcsetWidths.sort((a, b) => a - b);
+	}
+
+	const srcset = srcsetWidths
+		.map((w) => `${buildImageUrl(src, w, quality)} ${w}w`)
+		.join(", ");
+
+	// Default sizes attribute if not provided
+	const defaultSizes =
+		sizes || `(max-width: ${width}px) 100vw, ${width}px`;
+
+	// Blur placeholder URL
+	const blurSrc = buildBlurUrl(src);
+
+	// Check if image is already loaded (SSR or cached)
+	useEffect(() => {
+		if (imgRef.current?.complete) {
+			setLoaded(true);
+		}
+	}, []);
+
+	const containerStyle: React.CSSProperties = {
+		position: "relative",
+		width: `${width}px`,
+		maxWidth: "100%",
+		aspectRatio: `${width} / ${height}`,
+		overflow: "hidden",
+		borderRadius: borderRadius || undefined,
+		...style,
+	};
+
+	const imgStyle: React.CSSProperties = {
+		display: "block",
+		width: "100%",
+		height: "100%",
+		objectFit: fit,
+		opacity: loaded ? 1 : 0,
+		transition: "opacity 0.4s ease-in-out",
+	};
+
+	const placeholderStyle: React.CSSProperties = {
+		position: "absolute",
+		inset: 0,
+		width: "100%",
+		height: "100%",
+		objectFit: fit,
+		filter: "blur(20px)",
+		transform: "scale(1.1)",
+		opacity: loaded ? 0 : 1,
+		transition: "opacity 0.4s ease-in-out",
+		pointerEvents: "none",
+	};
+
+	if (error) {
+		// Fallback: render a standard <img> without optimization
+		return (
+			<img
+				src={src}
+				alt={alt}
+				width={width}
+				height={height}
+				className={className}
+				style={{ objectFit: fit, maxWidth: "100%", ...style }}
+				loading={priority ? "eager" : "lazy"}
+			/>
+		);
+	}
+
+	return (
+		<div
+			className={`blumen-image ${className}`}
+			style={containerStyle}
+		>
+			{/* Blur placeholder */}
+			{!priority && (
+				<img
+					src={blurSrc}
+					alt=""
+					aria-hidden="true"
+					style={placeholderStyle}
+				/>
+			)}
+
+			{/* Main optimized image */}
+			<img
+				ref={imgRef}
+				src={optimizedSrc}
+				srcSet={srcset}
+				sizes={defaultSizes}
+				alt={alt}
+				width={width}
+				height={height}
+				loading={priority ? "eager" : "lazy"}
+				decoding={priority ? "sync" : "async"}
+				fetchPriority={priority ? "high" : "auto"}
+				onLoad={() => setLoaded(true)}
+				onError={() => setError(true)}
+				style={imgStyle}
+			/>
+		</div>
+	);
+}
+
+export default BlumenImage;

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

@@ -0,0 +1,78 @@
+/**
+ * Blumen Default Loading Component
+ *
+ * A beautiful shimmer/skeleton loading state shown automatically
+ * during SPA navigation when the target page has getServerProps
+ * and a loading.tsx file.
+ *
+ * Developers can create their own loading.tsx files per directory
+ * for custom loading states, or use this default.
+ */
+
+import React from "react";
+
+const shimmerStyle: React.CSSProperties = {
+	background: "linear-gradient(90deg, rgba(255,255,255,0) 0%, rgba(255,255,255,0.08) 50%, rgba(255,255,255,0) 100%)",
+	backgroundSize: "200% 100%",
+	animation: "blumen-shimmer 1.5s ease-in-out infinite",
+};
+
+const skeletonLine = (width: string, height: string = "14px", mb: string = "12px"): React.CSSProperties => ({
+	width,
+	height,
+	borderRadius: "6px",
+	backgroundColor: "rgba(255,255,255,0.06)",
+	marginBottom: mb,
+	position: "relative" as const,
+	overflow: "hidden" as const,
+});
+
+export default function DefaultLoading() {
+	return (
+		<div style={{ padding: "40px 24px", maxWidth: "680px", margin: "0 auto" }}>
+			<style>{`
+				@keyframes blumen-shimmer {
+					0% { background-position: 200% 0; }
+					100% { background-position: -200% 0; }
+				}
+			`}</style>
+			{/* Title skeleton */}
+			<div style={skeletonLine("60%", "28px", "24px")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			{/* Subtitle skeleton */}
+			<div style={skeletonLine("80%", "16px", "32px")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			{/* Content skeletons */}
+			<div style={skeletonLine("100%")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			<div style={skeletonLine("92%")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			<div style={skeletonLine("85%")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			<div style={skeletonLine("40%", "14px", "32px")}>
+				<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+			</div>
+			{/* Card skeletons */}
+			<div style={{ display: "flex", gap: "16px", marginTop: "8px" }}>
+				{[1, 2, 3].map((i) => (
+					<div key={i} style={{
+						flex: 1,
+						height: "120px",
+						borderRadius: "12px",
+						backgroundColor: "rgba(255,255,255,0.04)",
+						border: "1px solid rgba(255,255,255,0.06)",
+						position: "relative",
+						overflow: "hidden",
+					}}>
+						<div style={{ ...shimmerStyle, position: "absolute", inset: 0 }} />
+					</div>
+				))}
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,174 @@
+import React from "react";
+
+/**
+ * Blumen Error Boundary
+ *
+ * Wraps the client hydration root to catch React rendering errors
+ * and display a user-friendly fallback instead of a white screen.
+ *
+ * In development, shows the error message and stack trace.
+ * In production, shows a clean recovery UI.
+ */
+
+interface ErrorBoundaryProps {
+	children: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+}
+
+export class BlumenErrorBoundary extends React.Component<
+	ErrorBoundaryProps,
+	ErrorBoundaryState
+> {
+	constructor(props: ErrorBoundaryProps) {
+		super(props);
+		this.state = { hasError: false, error: null };
+	}
+
+	static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+		return { hasError: true, error };
+	}
+
+	componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+		console.error("[Blumen] Client-side rendering error:", error);
+		console.error("[Blumen] Component stack:", errorInfo.componentStack);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			const isDev =
+				typeof window !== "undefined" &&
+				window.location.hostname === "localhost";
+			return (
+				<div
+					style={{
+						minHeight: "100vh",
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "center",
+						background: isDev ? "#0d1117" : "#f9fafb",
+						fontFamily:
+							"'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+						padding: "2rem",
+					}}
+				>
+					<div
+						style={{
+							maxWidth: 560,
+							width: "100%",
+							textAlign: isDev ? "left" : "center",
+						}}
+					>
+						{isDev ? (
+							<>
+								<div
+									style={{
+										color: "#ff6b6b",
+										fontSize: "0.75rem",
+										fontWeight: 600,
+										textTransform: "uppercase",
+										letterSpacing: "0.05em",
+										marginBottom: 8,
+									}}
+								>
+									⚠ Client Rendering Error
+								</div>
+								<div
+									style={{
+										color: "#e2e8f0",
+										fontSize: "1.1rem",
+										fontWeight: 600,
+										marginBottom: 16,
+									}}
+								>
+									{this.state.error?.message || "An unexpected error occurred"}
+								</div>
+								<pre
+									style={{
+										background: "#161b22",
+										border: "1px solid rgba(255,255,255,0.08)",
+										borderRadius: 8,
+										padding: 16,
+										fontSize: "0.75rem",
+										color: "#8b949e",
+										overflow: "auto",
+										maxHeight: 300,
+										lineHeight: 1.6,
+									}}
+								>
+									{this.state.error?.stack}
+								</pre>
+								<button
+									onClick={() => window.location.reload()}
+									style={{
+										marginTop: 16,
+										padding: "8px 20px",
+										background: "#7c3aed",
+										color: "#fff",
+										border: "none",
+										borderRadius: 6,
+										fontSize: "0.85rem",
+										fontWeight: 600,
+										cursor: "pointer",
+									}}
+								>
+									Reload Page
+								</button>
+							</>
+						) : (
+							<>
+								<div
+									style={{
+										fontSize: "3rem",
+										marginBottom: 16,
+									}}
+								>
+									⚡
+								</div>
+								<h1
+									style={{
+										fontSize: "1.5rem",
+										fontWeight: 700,
+										color: "#1a202c",
+										marginBottom: 8,
+									}}
+								>
+									Something went wrong
+								</h1>
+								<p
+									style={{
+										color: "#6b7280",
+										fontSize: "0.95rem",
+										marginBottom: 24,
+									}}
+								>
+									An unexpected error occurred. Please try refreshing the page.
+								</p>
+								<button
+									onClick={() => window.location.reload()}
+									style={{
+										padding: "10px 24px",
+										background: "#7c3aed",
+										color: "#fff",
+										border: "none",
+										borderRadius: 8,
+										fontSize: "0.9rem",
+										fontWeight: 600,
+										cursor: "pointer",
+									}}
+								>
+									Refresh Page
+								</button>
+							</>
+						)}
+					</div>
+				</div>
+			);
+		}
+
+		return this.props.children;
+	}
+}