npm - blumenjs - Versions diffs - 0.1.7 → 0.2.1 - Mend

blumenjs 0.1.7 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/dist/cli/blumen.js +270 -15
package/dist/cli/commands/build.js +25 -6
package/dist/cli/commands/create.js +1 -1
package/dist/cli/commands/dev.js +1 -1
package/dist/cli/commands/fonts.js +232 -0
package/dist/cli/commands/start.js +1 -1
package/dist/templates/app/client/entry.tsx +3 -1
package/dist/templates/app/pages/BlumenStarter.tsx +1 -1
package/dist/templates/app/shared/DefaultDocument.tsx +49 -4
package/dist/templates/app/shared/Link.tsx +60 -6
package/dist/templates/app/shared/RouterContext.tsx +81 -18
package/dist/templates/app/shared/router.ts +2 -1
package/dist/templates/go-server/cache.go +147 -0
package/dist/templates/go-server/image.go +200 -0
package/dist/templates/go-server/main.go +394 -39
package/dist/templates/go-server/middleware.go +546 -0
package/dist/templates/go-server/websocket.go +430 -0
package/dist/templates/node-ssr/server.ts +364 -8
package/dist/templates/scripts/generate-routes.ts +355 -7
package/package.json +12 -6

package/dist/cli/commands/start.js CHANGED Viewed

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

package/dist/templates/app/client/entry.tsx CHANGED Viewed

@@ -19,7 +19,8 @@ function init() {
 	const initialProps = propsText ? JSON.parse(propsText) : {};
 	// Hydrate the app with the RouterProvider.
-	// The provider handles route matching, page rendering, and SPA navigation.
+	// Error boundaries are handled inside RouterProvider to ensure
+	// the DOM tree matches what the SSR server produces.
 	hydrateRoot(
 		container,
 		<RouterProvider
@@ -39,3 +40,4 @@ if (document.readyState === "loading") {
 } else {
 	init();
 }

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -16,6 +16,10 @@ import React, {
 	useRef,
 } 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 ──────────────────────────────────────────────
@@ -73,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).
@@ -109,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);
 				});
 			});
@@ -141,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);
 				});
 			});
@@ -164,13 +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"}`}
-			>
-				<App Component={PageComponent} pageProps={pageProps} />
-			</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 CHANGED Viewed

@@ -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;

package/dist/templates/go-server/cache.go ADDED Viewed

@@ -0,0 +1,147 @@
+package main
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"sync"
+	"time"
+)
+// CacheEntry represents a single cached page response.
+type CacheEntry struct {
+	HTML       string
+	ETag       string
+	CreatedAt  time.Time
+	Revalidate int // TTL in seconds; 0 = cache forever until evicted
+	Stale      bool
+}
+// PageCache is a thread-safe in-memory LRU cache for rendered HTML pages.
+// It uses sync.RWMutex for maximum concurrent read performance —
+// thousands of goroutines can read simultaneously while writes are serialized.
+type PageCache struct {
+	mu       sync.RWMutex
+	entries  map[string]*CacheEntry
+	order    []string // LRU order: most recently used at end
+	maxSize  int
+}
+// NewPageCache creates a new cache with the given maximum number of entries.
+func NewPageCache(maxSize int) *PageCache {
+	return &PageCache{
+		entries: make(map[string]*CacheEntry),
+		order:   make([]string, 0, maxSize),
+		maxSize: maxSize,
+	}
+}
+// Get retrieves a cached page. Returns the entry and whether it was found.
+// Also returns whether the entry is stale (past its revalidate TTL).
+func (c *PageCache) Get(key string) (entry *CacheEntry, found bool, stale bool) {
+	c.mu.RLock()
+	e, ok := c.entries[key]
+	c.mu.RUnlock()
+	if !ok {
+		return nil, false, false
+	}
+	// Check if the entry has expired
+	if e.Revalidate > 0 {
+		age := time.Since(e.CreatedAt).Seconds()
+		if age > float64(e.Revalidate) {
+			return e, true, true // Found but stale
+		}
+	}
+	// Move to end of LRU order (most recently used)
+	c.mu.Lock()
+	c.moveToEnd(key)
+	c.mu.Unlock()
+	return e, true, false
+}
+// Set stores a page in the cache with the given revalidation TTL.
+func (c *PageCache) Set(key string, html string, revalidate int) {
+	etag := generateETag(html)
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	// If entry exists, update it
+	if _, exists := c.entries[key]; exists {
+		c.entries[key] = &CacheEntry{
+			HTML:       html,
+			ETag:       etag,
+			CreatedAt:  time.Now(),
+			Revalidate: revalidate,
+		}
+		c.moveToEnd(key)
+		return
+	}
+	// Evict LRU entry if at capacity
+	if len(c.entries) >= c.maxSize && len(c.order) > 0 {
+		oldest := c.order[0]
+		c.order = c.order[1:]
+		delete(c.entries, oldest)
+	}
+	// Add new entry
+	c.entries[key] = &CacheEntry{
+		HTML:       html,
+		ETag:       etag,
+		CreatedAt:  time.Now(),
+		Revalidate: revalidate,
+	}
+	c.order = append(c.order, key)
+}
+// Invalidate removes a specific key from the cache.
+func (c *PageCache) Invalidate(key string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.entries, key)
+	for i, k := range c.order {
+		if k == key {
+			c.order = append(c.order[:i], c.order[i+1:]...)
+			break
+		}
+	}
+}
+// Clear removes all entries from the cache.
+func (c *PageCache) Clear() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.entries = make(map[string]*CacheEntry)
+	c.order = make([]string, 0, c.maxSize)
+}
+// Size returns the current number of cached entries.
+func (c *PageCache) Size() int {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return len(c.entries)
+}
+// moveToEnd moves a key to the end of the LRU order (most recently used).
+// Must be called with the write lock held.
+func (c *PageCache) moveToEnd(key string) {
+	for i, k := range c.order {
+		if k == key {
+			c.order = append(c.order[:i], c.order[i+1:]...)
+			c.order = append(c.order, key)
+			return
+		}
+	}
+}
+// generateETag creates an ETag from the HTML content.
+func generateETag(content string) string {
+	hash := sha256.Sum256([]byte(content))
+	return `"` + hex.EncodeToString(hash[:8]) + `"`
+}