blumenjs 0.2.1 → 0.2.2

package/dist/cli/commands/build.js

@@ -1,5 +1,7 @@
 // cli/commands/build.ts
 import { execSync } from "child_process";
+import * as fs2 from "fs";
+import * as path2 from "path";
 
 // cli/utils.ts
 import * as fs from "fs";
@@ -61,6 +63,37 @@ function divider() {
 }
 
 // cli/commands/build.ts
+function generateChunkManifest() {
+  const jsDir = path2.resolve("static/js");
+  const chunksDir = path2.resolve("static/js/chunks");
+  const manifest = {};
+  if (fs2.existsSync(jsDir)) {
+    for (const file of fs2.readdirSync(jsDir)) {
+      if (!file.endsWith(".js") || file.endsWith(".map"))
+        continue;
+      const match = file.match(/^([^.]+)\.[a-f0-9]+\.js$/);
+      if (match) {
+        manifest[match[1]] = `/static/js/${file}`;
+      }
+    }
+  }
+  if (fs2.existsSync(chunksDir)) {
+    for (const file of fs2.readdirSync(chunksDir)) {
+      if (!file.endsWith(".js") || file.endsWith(".map"))
+        continue;
+      const match = file.match(/^([^.]+)\.[a-f0-9]+\.js$/);
+      if (match) {
+        manifest[match[1]] = `/static/js/chunks/${file}`;
+      }
+    }
+  }
+  fs2.mkdirSync("dist", { recursive: true });
+  fs2.writeFileSync("dist/chunk-manifest.json", JSON.stringify(manifest, null, 2));
+  const coreChunks = ["runtime", "vendor", "framework", "main"].filter((k) => manifest[k]);
+  const pageChunks = Object.keys(manifest).filter((k) => k.startsWith("page-"));
+  log.info(`  Core chunks: ${coreChunks.join(", ")} (${coreChunks.length})`);
+  log.info(`  Page chunks: ${pageChunks.length} page(s)`);
+}
 async function build(args = []) {
   banner();
   const analyze = args.includes("--analyze");
@@ -75,10 +108,14 @@ async function build(args = []) {
       cmd: "npx tsx scripts/generate-routes.ts"
     },
     {
-      label: "Building client bundle",
+      label: "Building client bundle (code splitting)",
       cmd: "npx webpack --mode production",
       env: analyze ? { BLUMEN_ANALYZE: "1" } : void 0
     },
+    {
+      label: "Generating chunk manifest",
+      fn: generateChunkManifest
+    },
     {
       label: "Building SSR server",
       cmd: "npx esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external --alias:@=./app"
@@ -95,11 +132,15 @@ async function build(args = []) {
     const step = steps[i];
     log.step(`[${i + 1}/${steps.length}] ${step.label}...`);
     try {
-      execSync(step.cmd, {
-        stdio: "inherit",
-        cwd: process.cwd(),
-        env: { ...process.env, ...step.env || {} }
-      });
+      if (step.fn) {
+        step.fn();
+      } else if (step.cmd) {
+        execSync(step.cmd, {
+          stdio: "inherit",
+          cwd: process.cwd(),
+          env: { ...process.env, ...step.env || {} }
+        });
+      }
       log.success(step.label);
     } catch {
       if (step.optional) {

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

@@ -3,9 +3,13 @@ import { hydrateRoot } from "react-dom/client";
 import NotFoundPage from "../pages/NotFound";
 
 // Auto-generated route map (run `npm run routes` to regenerate)
-import { routes, App } from "./generated-routes";
+import { routes, App, routeChunkMap } from "./generated-routes";
 import { RouterProvider } from "../shared/RouterContext";
 
+// Expose chunk map globally for the prefetch system
+// (prefetchCache.ts reads this to know which JS chunk to preload on hover)
+(window as any).__BLUMEN_CHUNK_MAP__ = routeChunkMap;
+
 function init() {
 	const container = document.getElementById("root");
 	if (!container) {

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

@@ -19,12 +19,19 @@ function sanitizeForHydration(data: any): string {
 }
 // HMR: In development, load the client bundle from Webpack Dev Server
 // so the HMR runtime + React Fast Refresh are active.
+// With code splitting, WDS serves multiple chunks instead of one bundle.js.
 const isDev = process.env.NODE_ENV === "development";
-const BUNDLE_SRC = isDev
-    ? "http://localhost:3100/static/js/bundle.js"
-    : "/static/js/bundle.js";
+const WDS_BASE = "http://localhost:3100/static/js";
 
-export function DefaultDocument({ children, initialProps, metadata }: any) {
+// Dev mode core scripts — loaded in dependency order
+const DEV_SCRIPTS = [
+    `${WDS_BASE}/runtime.js`,
+    `${WDS_BASE}/vendor.js`,
+    `${WDS_BASE}/framework.js`,
+    `${WDS_BASE}/main.js`,
+];
+
+export function DefaultDocument({ children, initialProps, metadata, scripts }: 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; }
@@ -114,7 +121,14 @@ export function DefaultDocument({ children, initialProps, metadata }: any) {
                         __html: sanitizeForHydration(initialProps)
                     }}
                 />
-                <script src={BUNDLE_SRC} defer></script>
+                {isDev
+                    ? DEV_SCRIPTS.map((src, i) => (
+                          <script key={i} src={src} defer></script>
+                      ))
+                    : (scripts || ['/static/js/main.js']).map((src: string, i: number) => (
+                          <script key={i} src={src} defer></script>
+                      ))
+                }
             </body>
         </html>
     );

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

@@ -14,6 +14,7 @@ import React, {
 	useCallback,
 	useEffect,
 	useRef,
+	Suspense,
 } from "react";
 import { matchRoute, type RouteDef } from "./router";
 import { BlumenErrorBoundary } from "./ErrorBoundary";
@@ -230,7 +231,9 @@ export function RouterProvider({
 					className={`page-transition ${transitioning ? "page-transition-exit" : "page-transition-active"}`}
 				>
 					<BlumenErrorBoundary>
-						<App Component={PageComponent} pageProps={pageProps} />
+						<Suspense fallback={LoadingComp ? <LoadingComp /> : <DefaultLoading />}>
+							<App Component={PageComponent} pageProps={pageProps} />
+						</Suspense>
 					</BlumenErrorBoundary>
 				</div>
 			)}

package/dist/templates/go-server/main.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
+	"io"
 	"log"
 	"net"
 	"net/http"
@@ -11,9 +12,10 @@ import (
 )
 
 const (
-	nodeSSRURL  = "http://localhost:4000/render"
-	nodeDataURL = "http://localhost:4000/data"
-	nodeAPIURL  = "http://localhost:4000/api"
+	nodeSSRURL       = "http://localhost:4000/render"
+	nodeStreamURL    = "http://localhost:4000/stream-render"
+	nodeDataURL      = "http://localhost:4000/data"
+	nodeAPIURL       = "http://localhost:4000/api"
 )
 
 // Global page cache — stores rendered HTML in Go memory for near-instant responses.
@@ -234,7 +236,23 @@ func PageHandler(loader DataLoader) http.HandlerFunc {
 			return
 		}
 
-		// CACHE MISS: render the page and cache the result
+		// CACHE MISS: try streaming SSR first for instant TTFB
+		// Streaming bypasses the cache — the HTML is sent directly to the browser.
+		// The next request will use renderPage and populate the cache.
+		if r.Header.Get("X-Blumen-Data") != "1" {
+			if streamRenderPage(w, r, loader) {
+				// Successfully streamed — also trigger a background cache fill
+				go func() {
+					html, revalidate := renderPage(r, loader)
+					if html != "" {
+						pageCache.Set(cacheKey, html, revalidate)
+					}
+				}()
+				return
+			}
+		}
+
+		// Streaming unavailable or SPA data request — fall back to renderPage
 		html, revalidate := renderPage(r, loader)
 		if html == "" {
 			// renderPage already wrote the error response
@@ -330,6 +348,91 @@ func renderPage(r *http.Request, loader DataLoader) (string, int) {
 	return ssrResp.HTML, revalidate
 }
 
+// streamRenderPage streams HTML from Node SSR directly to the client.
+// Uses chunked transfer encoding for instant TTFB.
+// Returns true if streaming succeeded, false if caller should fall back.
+func streamRenderPage(w http.ResponseWriter, r *http.Request, loader DataLoader) bool {
+	// Check if ResponseWriter supports flushing (required for streaming)
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		return false
+	}
+
+	var props map[string]interface{}
+	var err error
+
+	if loader != nil {
+		props, err = loader(r)
+		if err != nil {
+			log.Printf("Streaming: loader error: %v", err)
+			return false
+		}
+	} else {
+		tsProps, _, tsErr := fetchServerProps(r)
+		if tsErr != nil {
+			log.Printf("Streaming: getServerProps error: %v", tsErr)
+		} else if tsProps != nil {
+			props = tsProps
+		}
+	}
+
+	ssrReq := SSRRequest{
+		Path:  r.URL.Path,
+		Query: r.URL.Query(),
+		Params: map[string]interface{}{
+			"url":     r.URL.String(),
+			"headers": r.Header,
+		},
+		Data: props,
+	}
+
+	reqBody, err := json.Marshal(ssrReq)
+	if err != nil {
+		log.Printf("Streaming: marshal error: %v", err)
+		return false
+	}
+
+	resp, err := httpClient.Post(nodeStreamURL, "application/json", bytes.NewReader(reqBody))
+	if err != nil {
+		log.Printf("Streaming: node request error: %v", err)
+		return false
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		log.Printf("Streaming: node returned %d", resp.StatusCode)
+		return false
+	}
+
+	// Set response headers for streaming
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Transfer-Encoding", "chunked")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	w.Header().Set("X-Frame-Options", "DENY")
+	w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")
+	w.Header().Set("X-Blumen-Cache", "STREAM")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.WriteHeader(http.StatusOK)
+
+	// Stream chunks from Node to the browser
+	buf := make([]byte, 4096)
+	for {
+		n, readErr := resp.Body.Read(buf)
+		if n > 0 {
+			w.Write(buf[:n])
+			flusher.Flush()
+		}
+		if readErr != nil {
+			if readErr != io.EOF {
+				log.Printf("Streaming: read error: %v", readErr)
+			}
+			break
+		}
+	}
+
+	return true
+}
+
 // fetchServerProps calls the Node SSR /data endpoint to run getServerProps.
 // Returns nil if the page doesn't export getServerProps.
 // Also returns the revalidate TTL (0 = no caching from getServerProps).

package/dist/templates/go-server/middleware.go

@@ -423,7 +423,7 @@ type SecurityConfig struct {
 // DefaultSecurityConfig returns production-ready security header defaults.
 func DefaultSecurityConfig() SecurityConfig {
 	return SecurityConfig{
-		CSP:                   "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws: wss:;",
+		CSP:                   "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' http://localhost:3100; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com https://fonts.googleapis.com; connect-src 'self' ws: wss: http://localhost:3100 ws://localhost:3100;",
 		HSTSMaxAge:            31536000, // 1 year
 		HSTSIncludeSubdomains: true,
 		FrameOptions:          "DENY",

package/dist/templates/node-ssr/server.ts

@@ -1,15 +1,66 @@
 import * as http from "http";
-import { renderToString } from "react-dom/server";
+import * as fs from "fs";
+import * as path from "path";
+import { renderToString, renderToPipeableStream } from "react-dom/server";
 import React from "react";
 
 // Auto-generated route map (run `npm run routes` to regenerate)
-import { routes, App, Document, serverPropsMap, metadataMap, generateMetadataMap, layoutMetadataMap, layoutGenerateMetadataMap } from "./generated-routes";
+import { routes, App, Document, serverPropsMap, staticPropsMap, staticPathsMap, metadataMap, generateMetadataMap, layoutMetadataMap, layoutGenerateMetadataMap } from "./generated-routes";
 import { apiRoutes } from "./generated-api-routes";
 import { matchRoute } from "../app/shared/router";
 import { executeAction, getRegisteredActions } from "../app/shared/serverAction";
 import NotFoundPage from "../app/pages/NotFound";
 
 const NotFound = NotFoundPage;
+const isDev = process.env.NODE_ENV === "development";
+
+// ── Chunk Manifest (Production) ────────────────────────────────
+// Maps chunk names (e.g. "runtime", "vendor", "page-home") to their
+// hashed filenames (e.g. "/static/js/runtime.abc12345.js").
+// Generated by `blumen build` after the Webpack step.
+let chunkManifest: Record<string, string> = {};
+if (!isDev) {
+	try {
+		const manifestPath = path.resolve("dist/chunk-manifest.json");
+		if (fs.existsSync(manifestPath)) {
+			chunkManifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+			console.log(`Chunk manifest loaded: ${Object.keys(chunkManifest).length} chunks`);
+		}
+	} catch (err) {
+		console.warn("Could not load chunk manifest:", err);
+	}
+}
+
+/**
+ * Resolve the list of <script> src URLs for a given page.
+ * Order: runtime → vendor → framework → main → page chunk
+ */
+function getScriptsForPage(routePath: string): string[] {
+	if (isDev) return []; // Dev mode: DefaultDocument handles its own scripts
+
+	const scripts: string[] = [];
+	// Core chunks in dependency order
+	for (const name of ["runtime", "vendor", "framework", "main"]) {
+		if (chunkManifest[name]) {
+			scripts.push(chunkManifest[name]);
+		}
+	}
+
+	// Page-specific chunk
+	// Convert route path to chunk name: "/docs" → "page-docs", "/users/[id]" → "page-users-id"
+	const chunkName = "page-" + (routePath === "/" ? "home" : routePath
+		.replace(/^\//, "")
+		.replace(/\/index$/, "")
+		.replace(/\[([^\]]+)\]/g, "$1")
+		.replace(/\//g, "-")
+		.toLowerCase());
+
+	if (chunkManifest[chunkName]) {
+		scripts.push(chunkManifest[chunkName]);
+	}
+
+	return scripts;
+}
 
 interface SSRRequest {
 	path: string;
@@ -61,12 +112,16 @@ const server = http.createServer(async (req, res) => {
 	// Route to the correct handler
 	if (req.url === "/data") {
 		return handleData(req, res);
+	} else if (req.url === "/stream-render") {
+		return handleStreamRender(req, res);
 	} else if (req.url === "/render") {
 		return handleRender(req, res);
 	} else if (req.url === "/api") {
 		return handleAPI(req, res);
 	} else if (req.url === "/action") {
 		return handleAction(req, res);
+	} else if (req.url === "/static-paths") {
+		return handleStaticPaths(req, res);
 	} else {
 		res.writeHead(404);
 		res.end(JSON.stringify({ error: "Not Found" }));
@@ -313,6 +368,7 @@ async function handleRender(
 			initialProps: props,
 			children: appElement,
 			metadata,
+			scripts: getScriptsForPage(routeDef?.path || ssrReq.path),
 		});
 
 		const html = "<!doctype html>\n" + renderToString(documentElement);
@@ -337,6 +393,135 @@ async function handleRender(
 	}
 }
 
+/**
+ * POST /stream-render — Streaming SSR
+ *
+ * Uses React 18's renderToPipeableStream to send HTML progressively.
+ * The shell (everything outside <Suspense>) arrives immediately.
+ * Data-dependent sections stream in as they resolve.
+ *
+ * Props are sent via X-Blumen-Props header (JSON-encoded)
+ * so Go can extract them for caching without parsing the HTML stream.
+ *
+ * Go proxies this stream directly to the browser using chunked
+ * transfer encoding for instant Time to First Byte.
+ */
+async function handleStreamRender(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+) {
+	try {
+		const body = await readBody(req);
+		const ssrReq: SSRRequest = JSON.parse(body);
+
+		const match = matchRoute(ssrReq.path, routes);
+
+		if (!match) {
+			// No streaming for 404 — just use renderToString
+			const props = {
+				path: ssrReq.path,
+				status: 404,
+				serverRendered: true,
+			};
+			const element = React.createElement(
+				"div",
+				{ className: "page-transition page-transition-active" },
+				React.createElement(NotFound, props),
+			);
+			const html = renderToString(element);
+
+			res.writeHead(200, {
+				"Content-Type": "text/html; charset=utf-8",
+				"X-Blumen-Props": JSON.stringify(props),
+				"X-Blumen-Status": "404",
+			});
+			res.end("<!doctype html>\n" + html);
+			return;
+		}
+
+		// Prepare props
+		const props = {
+			...(ssrReq.data || {}),
+			path: ssrReq.path,
+			query: ssrReq.query,
+			params: { ...ssrReq.params, ...match.params },
+			timestamp: Date.now(),
+			serverRendered: true,
+		};
+
+		// Build the app element
+		const appElement = React.createElement(
+			"div",
+			{ className: "page-transition page-transition-active" },
+			React.createElement(App, {
+				Component: match.component,
+				pageProps: props,
+			}),
+		);
+
+		// Resolve metadata
+		const routeDef = routes.find(r => r.component === match.component);
+		const metadata = routeDef
+			? await resolveMetadata(routeDef.path, {
+					params: props.params || {},
+					query: ssrReq.query || {},
+					path: ssrReq.path,
+					headers: {},
+				})
+			: {};
+
+		// Build the full document element
+		const documentElement = React.createElement(Document, {
+			initialProps: props,
+			children: appElement,
+			metadata,
+			scripts: getScriptsForPage(routeDef?.path || ssrReq.path),
+		});
+
+		// Use renderToPipeableStream for progressive HTML streaming
+		const { pipe, abort } = renderToPipeableStream(documentElement, {
+			onShellReady() {
+				// Shell is ready — send headers and start streaming immediately.
+				// This is the key performance win: TTFB happens NOW,
+				// before data-dependent Suspense boundaries resolve.
+				res.writeHead(200, {
+					"Content-Type": "text/html; charset=utf-8",
+					"Transfer-Encoding": "chunked",
+					"X-Blumen-Props": JSON.stringify(props),
+					"X-Blumen-Streaming": "1",
+				});
+				// Write the doctype before piping React's output
+				res.write("<!doctype html>\n");
+				pipe(res);
+			},
+			onShellError(error) {
+				// Shell failed to render — fall back to error response
+				console.error("Streaming SSR shell error:", error);
+				res.writeHead(500, { "Content-Type": "text/html" });
+				res.end("<!doctype html><html><body><h1>Server Error</h1></body></html>");
+			},
+			onError(error) {
+				// Non-fatal error during streaming (e.g., a Suspense boundary failed)
+				// The stream continues — React will send the fallback UI
+				console.error("Streaming SSR error:", error);
+			},
+		});
+
+		// Safety timeout: abort streaming after 10 seconds
+		setTimeout(() => abort(), 10000);
+
+	} catch (error) {
+		console.error("Stream render error:", error);
+		if (!res.headersSent) {
+			res.writeHead(500);
+			res.end(JSON.stringify({
+				error: "Internal Server Error",
+				message: isDev ? String(error) : undefined,
+			}));
+		}
+	}
+}
+
 function readBody(req: http.IncomingMessage): Promise<string> {
 	return new Promise((resolve, reject) => {
 		let body = "";
@@ -469,6 +654,41 @@ async function handleAction(req: http.IncomingMessage, res: http.ServerResponse)
 	}
 }
 
+/**
+ * POST /static-paths — Resolve dynamic SSG routes.
+ *
+ * Called by the SSG prerender script to get the list of paths
+ * that a page with getStaticPaths should be pre-rendered for.
+ *
+ * Request:  { route: "/blog/[slug]" }
+ * Response: { paths: [{ params: { slug: "hello-world" } }, ...] }
+ */
+async function handleStaticPaths(req: http.IncomingMessage, res: http.ServerResponse) {
+	try {
+		const rawBody = await readBody(req);
+		const { route } = JSON.parse(rawBody) as { route: string };
+
+		const getStaticPaths = staticPathsMap[route];
+		if (!getStaticPaths) {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ paths: [] }));
+			return;
+		}
+
+		const result = await getStaticPaths();
+		const paths = result?.paths || [];
+
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ paths }));
+	} catch (error: any) {
+		console.error("getStaticPaths Error:", error);
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "getStaticPaths failed", message: error.message }));
+	}
+}
+
+// ─── Server Startup ──────────────────────────────────────────────
+
 server.listen(PORT, () => {
 	console.log(`Node SSR server running on http://localhost:${PORT}`);
 	const gspCount = Object.keys(serverPropsMap).length;