bertui 1.2.8 → 1.2.9

package/README.md

@@ -2,14 +2,13 @@
 
 **Zero-config React framework powered by Bun. File-based routing, Server Islands, and a build system that gets out of your way.**
 
-[![Version](https://img.shields.io/badge/version-1.2.2-blue)](https://www.npmjs.com/package/bertui)
+[![Version](https://img.shields.io/badge/version-1.2.9-blue)](https://www.npmjs.com/package/bertui)
 [![Bun Powered](https://img.shields.io/badge/runtime-Bun-f472b6)](https://bun.sh)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 ---
 
 ## Quick Start
-
 ```bash
 bunx create-bertui my-app
 cd my-app
@@ -18,11 +17,51 @@ bun run dev
 
 ---
 
+## What's New in v1.2.9
+
+### Server Islands — Rebuilt from the Ground Up
+
+Server Islands are back and fully working. One export, zero config, pure HTML at build time.
+```jsx
+// src/pages/about.jsx
+export const render = "static"
+
+export default function About() {
+  return (
+    <div>
+      <h1>About Us</h1>
+      <p>Rendered at build time. Zero JS in the browser.</p>
+    </div>
+  )
+}
+```
+
+BertUI runs `renderToString` on your page at build time and writes pure HTML to `dist/`. No React runtime ships to the browser. No hydration. Just HTML.
+
+Three render modes, one export:
+```jsx
+// Pure HTML — zero JS, zero React in the browser
+export const render = "static"
+
+// SSR HTML + JS bundle — pre-rendered for instant load, hydrated for interactivity  
+export const render = "server"
+
+// Default — client-only React SPA (no export needed)
+export default function Page() {}
+```
+
+**Rules for static and server pages:**
+- No React hooks (`useState`, `useEffect`, etc.)
+- No event handlers (`onClick`, `onChange`, etc.)
+- No browser APIs (`window`, `document`, `localStorage`)
+- Violations are caught at build time with a clear error
+
+---
+
 ## What's New in v1.2.2
 
 ### Import Aliases (`importhow`)
 No more `../../../` chains. Define aliases in your config and import cleanly from anywhere.
-
 ```javascript
 // bertui.config.js
 export default {
@@ -32,7 +71,6 @@ export default {
   }
 }
 ```
-
 ```javascript
 // anywhere in your project
 import Button from 'amani/button';
@@ -43,7 +81,6 @@ Aliases are resolved at compile time — zero runtime overhead.
 
 ### Node Modules — Just Work
 Install a package, import it. That's it.
-
 ```javascript
 import { format } from 'date-fns';
 import confetti from 'canvas-confetti';
@@ -53,7 +90,6 @@ In dev, packages are served from your local filesystem. In production, only the
 
 ### CLI — New Look
 The build and dev output is now compact and step-based instead of verbose line-by-line logs.
-
 ```
   ██████╗ ███████╗██████╗ ████████╗██╗   ██╗██╗
   ██╔══██╗██╔════╝██╔══██╗╚══██╔══╝██║   ██║██║
@@ -64,7 +100,7 @@ The build and dev output is now compact and step-based instead of verbose line-b
   by Pease Ernest  ·  BUILD
 
   [ 1/10] ✓  Loading env
-  [ 2/10] ✓  Compiling           5 routes · 1 islands
+  [ 2/10] ✓  Compiling           5 routes
   [ 3/10] ⠸  Layouts             ...
   ...
   ✓ Done  0.54s
@@ -82,7 +118,6 @@ Run `bun add some-package` and the dev server picks it up automatically. The imp
 ## Features
 
 ### File-Based Routing
-
 ```
 src/pages/index.jsx          →  /
 src/pages/about.jsx          →  /about
@@ -92,31 +127,45 @@ src/pages/blog/[slug].jsx    →  /blog/:slug
 
 ### Server Islands
 
-Add one line to opt a page into static generation at build time.
-
+Three render modes. One export at the top of your page.
 ```jsx
-// src/pages/about.jsx
-export const render = "server";
-export const title = "About Us";
+// render = "static" — pure HTML, zero JS
+// Perfect for: marketing pages, blog posts, docs, any page without interactivity
+export const render = "static"
+export const title = "About Us"
 
 export default function About() {
   return (
     <div>
       <h1>About Us</h1>
-      <p>Pre-rendered as static HTML at build time.</p>
+      <p>Pre-rendered at build time. Instant load, perfect SEO.</p>
     </div>
-  );
+  )
+}
+```
+```jsx
+// render = "server" — SSR HTML in the body + JS bundle attached
+// Perfect for: pages that need fast first paint AND interactivity after load
+export const render = "server"
+
+export default function Dashboard() {
+  return <div><h1>Dashboard</h1></div>
+}
+```
+```jsx
+// default — client-only React (no export needed)
+// Perfect for: highly interactive pages, apps, anything with lots of state
+export default function Editor() {
+  const [value, setValue] = useState('')
+  return <textarea onChange={e => setValue(e.target.value)} />
 }
 ```
 
-- Static HTML embedded in the output for instant load and perfect SEO
-- Pages with hooks or event handlers are rejected at build time with a clear error
-- All other pages are client-only by default
+BertUI automatically detects the render mode and generates the right HTML for each page. Static pages get zero JS. Server pages get pre-rendered HTML with hydration. Default pages get the full SPA treatment.
 
 ### TypeScript
 
 `.tsx` and `.ts` files work with no setup. Mix them freely with `.jsx`.
-
 ```typescript
 // src/pages/blog/[slug].tsx
 import { useRouter } from 'bertui/router';
@@ -130,7 +179,6 @@ export default function BlogPost() {
 ### SEO
 
 `sitemap.xml` and `robots.txt` are generated automatically from your routes. Requires `baseUrl` in config.
-
 ```javascript
 export default {
   baseUrl: 'https://example.com',
@@ -148,7 +196,6 @@ Put your styles in `src/styles/`. They are combined and minified with LightningC
 ---
 
 ## Project Structure
-
 ```
 my-app/
 ├── src/
@@ -166,7 +213,6 @@ my-app/
 ---
 
 ## Configuration
-
 ```javascript
 // bertui.config.js
 export default {
@@ -209,6 +255,7 @@ Benchmarks on an Intel i3-2348M, 7.6GB RAM.
 
 - `bertui-elysia` — API routes, auth, database
 - `bertui-animate` — GPU-accelerated animations
+- Partial hydration — `<Island>` component for mixed static/interactive pages
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bertui",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Lightning-fast React dev server powered by Bun - Now with Rust image optimization (WASM, no Rust required for users)",
   "type": "module",
   "main": "./index.js",

package/src/build/generators/html-generator.js

@@ -1,117 +1,170 @@
 // bertui/src/build/generators/html-generator.js
-import { join, relative } from 'path';
-import { mkdirSync, existsSync, cpSync } from 'fs';
-import logger from '../../logger/logger.js';
-import { extractMetaFromSource } from '../../utils/meta-extractor.js';
+import { join, relative } from 'path'
+import { mkdirSync, existsSync, cpSync } from 'fs'
+import logger from '../../logger/logger.js'
+import { extractMetaFromSource } from '../../utils/meta-extractor.js'
+import { renderPageToHTML, getPageRenderMode } from '../ssr-renderer.js'
 
-export async function generateProductionHTML(root, outDir, buildResult, routes, config) {
+export async function generateProductionHTML(root, outDir, buildResult, routes, config, buildDir) {
   const mainBundle = buildResult.outputs.find(o =>
     o.path.includes('main') && o.kind === 'entry-point'
-  );
+  )
 
   if (!mainBundle) {
-    logger.error('Could not find main bundle');
-    return;
+    logger.error('Could not find main bundle')
+    return
   }
 
-  const bundlePath = relative(outDir, mainBundle.path).replace(/\\/g, '/');
-  const defaultMeta = config.meta || {};
-  const bertuiPackages = await copyBertuiPackagesToProduction(root, outDir);
+  const bundlePath = relative(outDir, mainBundle.path).replace(/\\/g, '/')
+  const defaultMeta = config.meta || {}
+  const bertuiPackages = await copyBertuiPackagesToProduction(root, outDir)
 
-  logger.info(`Generating HTML for ${routes.length} routes...`);
+
+  logger.info(`Generating HTML for ${routes.length} routes...`)
 
   for (const route of routes) {
-    await processSingleRoute(route, config, defaultMeta, bundlePath, outDir, bertuiPackages);
+    await processSingleRoute(route, config, defaultMeta, bundlePath, outDir, bertuiPackages, buildDir)
   }
 
-  logger.success(`HTML generation complete for ${routes.length} routes`);
+  logger.success(`HTML generation complete for ${routes.length} routes`)
 }
 
-async function copyBertuiPackagesToProduction(root, outDir) {
-  const nodeModulesDir = join(root, 'node_modules');
-  const packages = { bertuiIcons: false, bertuiAnimate: false, elysiaEden: false };
+async function processSingleRoute(route, config, defaultMeta, bundlePath, outDir, bertuiPackages, buildDir) {
+  try {
+    const sourceCode = await Bun.file(route.path).text()
+    const pageMeta = extractMetaFromSource(sourceCode)
+    const meta = { ...defaultMeta, ...pageMeta }
 
-  if (!existsSync(nodeModulesDir)) return packages;
+    // Determine render mode from source
+    const renderMode = await getPageRenderMode(route.path)
 
-  const bertuiIconsSource = join(nodeModulesDir, 'bertui-icons');
-  if (existsSync(bertuiIconsSource)) {
-    try {
-      const bertuiIconsDest = join(outDir, 'node_modules', 'bertui-icons');
-      mkdirSync(join(outDir, 'node_modules'), { recursive: true });
-      cpSync(bertuiIconsSource, bertuiIconsDest, { recursive: true });
-      packages.bertuiIcons = true;
-    } catch (error) {
-      logger.error(`Failed to copy bertui-icons: ${error.message}`);
-    }
-  }
+    let html
 
-  const bertuiAnimateSource = join(nodeModulesDir, 'bertui-animate', 'dist');
-  if (existsSync(bertuiAnimateSource)) {
-    try {
-      const bertuiAnimateDest = join(outDir, 'css');
-      mkdirSync(bertuiAnimateDest, { recursive: true });
-      const minCSSPath = join(bertuiAnimateSource, 'bertui-animate.min.css');
-      if (existsSync(minCSSPath)) {
-        cpSync(minCSSPath, join(bertuiAnimateDest, 'bertui-animate.min.css'));
-        packages.bertuiAnimate = true;
-      }
-    } catch (error) {
-      logger.error(`Failed to copy bertui-animate: ${error.message}`);
-    }
-  }
+    if (renderMode === 'server' || renderMode === 'static') {
+      // Find the compiled version of this page in buildDir
+      const compiledPath = findCompiledPath(route, buildDir)
 
-  const elysiaEdenSource = join(nodeModulesDir, '@elysiajs', 'eden');
-  if (existsSync(elysiaEdenSource)) {
-    try {
-      const elysiaEdenDest = join(outDir, 'node_modules', '@elysiajs', 'eden');
-      mkdirSync(join(outDir, 'node_modules', '@elysiajs'), { recursive: true });
-      cpSync(elysiaEdenSource, elysiaEdenDest, { recursive: true });
-      packages.elysiaEden = true;
-    } catch (error) {
-      logger.error(`Failed to copy @elysiajs/eden: ${error.message}`);
-    }
-  }
-
-  return packages;
-}
+      if (compiledPath && existsSync(compiledPath)) {
+        logger.info(`  SSR rendering: ${route.route}`)
+        const ssrHTML = await renderPageToHTML(compiledPath, buildDir)
 
-async function processSingleRoute(route, config, defaultMeta, bundlePath, outDir, bertuiPackages) {
-  try {
-    const sourceCode = await Bun.file(route.path).text();
-    const pageMeta = extractMetaFromSource(sourceCode);
-    const meta = { ...defaultMeta, ...pageMeta };
-
-    const html = generateHTML(meta, bundlePath, bertuiPackages);
+        if (ssrHTML) {
+          if (renderMode === 'static') {
+            // Pure static — no JS at all
+            html = generateStaticHTML({ ssrHTML, meta, bertuiPackages })
+          } else {
+            // Server island — SSR HTML + JS bundle for hydration
+            html = generateServerIslandHTML({ ssrHTML, meta, bundlePath, bertuiPackages })
+          }
+          logger.success(`  ✓ SSR: ${route.route} (${renderMode})`)
+        } else {
+          // SSR failed — fall back to client render with a warning
+          logger.warn(`  SSR failed for ${route.route}, falling back to client render`)
+          html = generateClientHTML({ meta, bundlePath, bertuiPackages })
+        }
+      } else {
+        logger.warn(`  Compiled path not found for ${route.route}, using client render`)
+        html = generateClientHTML({ meta, bundlePath, bertuiPackages })
+      }
+    } else {
+      // Default: client-only SPA
+      html = generateClientHTML({ meta, bundlePath, bertuiPackages })
+    }
 
-    let htmlPath;
+    // Write to dist/
+    let htmlPath
     if (route.route === '/') {
-      htmlPath = join(outDir, 'index.html');
+      htmlPath = join(outDir, 'index.html')
     } else {
-      const routeDir = join(outDir, route.route.replace(/^\//, ''));
-      mkdirSync(routeDir, { recursive: true });
-      htmlPath = join(routeDir, 'index.html');
+      const routeDir = join(outDir, route.route.replace(/^\//, ''))
+      mkdirSync(routeDir, { recursive: true })
+      htmlPath = join(routeDir, 'index.html')
     }
 
-    await Bun.write(htmlPath, html);
-    logger.success(`${route.route}`);
+    await Bun.write(htmlPath, html)
+    logger.success(`  ${route.route}`)
 
   } catch (error) {
-    logger.error(`Failed HTML for ${route.route}: ${error.message}`);
+    logger.error(`Failed HTML for ${route.route}: ${error.message}`)
   }
 }
 
-function generateHTML(meta, bundlePath, bertuiPackages = {}) {
-  const bertuiIconsImport = bertuiPackages.bertuiIcons
-    ? ',\n      "bertui-icons": "/node_modules/bertui-icons/generated/index.js"'
-    : '';
+/**
+ * Find the compiled .js path for a route's source file
+ */
+function findCompiledPath(route, buildDir) {
+  const compiledFile = route.file.replace(/\.(jsx|tsx|ts)$/, '.js')
+  return join(buildDir, 'pages', compiledFile)
+}
+// ─── HTML generators ──────────────────────────────────────────────────────────
 
+/**
+ * render = "static" → pure HTML, zero JS
+ */
+function generateStaticHTML({ ssrHTML, meta, bertuiPackages }) {
   const bertuiAnimateCSS = bertuiPackages.bertuiAnimate
-    ? '  <link rel="stylesheet" href="/css/bertui-animate.min.css">'
-    : '';
+    ? '<link rel="stylesheet" href="/css/bertui-animate.min.css">'
+    : ''
 
-  const elysiaEdenImport = bertuiPackages.elysiaEden
-    ? ',\n      "@elysiajs/eden": "/node_modules/@elysiajs/eden/dist/index.mjs"'
-    : '';
+  return `<!DOCTYPE html>
+<html lang="${meta.lang || 'en'}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${meta.title || 'BertUI App'}</title>
+  <meta name="description" content="${meta.description || ''}">
+  ${meta.keywords     ? `<meta name="keywords" content="${meta.keywords}">` : ''}
+  ${meta.author       ? `<meta name="author" content="${meta.author}">` : ''}
+  ${meta.themeColor   ? `<meta name="theme-color" content="${meta.themeColor}">` : ''}
+  <meta property="og:title" content="${meta.ogTitle || meta.title || 'BertUI App'}">
+  <meta property="og:description" content="${meta.ogDescription || meta.description || ''}">
+  ${meta.ogImage ? `<meta property="og:image" content="${meta.ogImage}">` : ''}
+  <link rel="stylesheet" href="/styles/bertui.min.css">
+  ${bertuiAnimateCSS}
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+</head>
+<body>
+  ${ssrHTML}
+</body>
+</html>`
+}
+
+/**
+ * render = "server" → SSR HTML + JS bundle for hydration
+ */
+function generateServerIslandHTML({ ssrHTML, meta, bundlePath, bertuiPackages }) {
+  const { importMapScript, bertuiAnimateCSS } = buildSharedAssets(meta, bertuiPackages)
+
+  return `<!DOCTYPE html>
+<html lang="${meta.lang || 'en'}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${meta.title || 'BertUI App'}</title>
+  <meta name="description" content="${meta.description || ''}">
+  ${meta.keywords     ? `<meta name="keywords" content="${meta.keywords}">` : ''}
+  ${meta.author       ? `<meta name="author" content="${meta.author}">` : ''}
+  ${meta.themeColor   ? `<meta name="theme-color" content="${meta.themeColor}">` : ''}
+  <meta property="og:title" content="${meta.ogTitle || meta.title || 'BertUI App'}">
+  <meta property="og:description" content="${meta.ogDescription || meta.description || ''}">
+  ${meta.ogImage ? `<meta property="og:image" content="${meta.ogImage}">` : ''}
+  <link rel="stylesheet" href="/styles/bertui.min.css">
+  ${bertuiAnimateCSS}
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  ${importMapScript}
+</head>
+<body>
+  <div id="root">${ssrHTML}</div>
+  <script type="module" src="/${bundlePath}"></script>
+</body>
+</html>`
+}
+
+/**
+ * default → client-only SPA (existing behavior)
+ */
+function generateClientHTML({ meta, bundlePath, bertuiPackages }) {
+  const { importMapScript, bertuiAnimateCSS } = buildSharedAssets(meta, bertuiPackages)
 
   return `<!DOCTYPE html>
 <html lang="${meta.lang || 'en'}">
@@ -119,17 +172,39 @@ function generateHTML(meta, bundlePath, bertuiPackages = {}) {
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${meta.title || 'BertUI App'}</title>
-  <meta name="description" content="${meta.description || 'Built with BertUI'}">
-  ${meta.keywords ? `<meta name="keywords" content="${meta.keywords}">` : ''}
-  ${meta.author ? `<meta name="author" content="${meta.author}">` : ''}
-  ${meta.themeColor ? `<meta name="theme-color" content="${meta.themeColor}">` : ''}
+  <meta name="description" content="${meta.description || ''}">
+  ${meta.keywords     ? `<meta name="keywords" content="${meta.keywords}">` : ''}
+  ${meta.author       ? `<meta name="author" content="${meta.author}">` : ''}
+  ${meta.themeColor   ? `<meta name="theme-color" content="${meta.themeColor}">` : ''}
   <meta property="og:title" content="${meta.ogTitle || meta.title || 'BertUI App'}">
-  <meta property="og:description" content="${meta.ogDescription || meta.description || 'Built with BertUI'}">
+  <meta property="og:description" content="${meta.ogDescription || meta.description || ''}">
   ${meta.ogImage ? `<meta property="og:image" content="${meta.ogImage}">` : ''}
   <link rel="stylesheet" href="/styles/bertui.min.css">
-${bertuiAnimateCSS}
+  ${bertuiAnimateCSS}
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
-  <script type="importmap">
+  ${importMapScript}
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/${bundlePath}"></script>
+</body>
+</html>`
+}
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+function buildSharedAssets(meta, bertuiPackages) {
+  const bertuiIconsImport = bertuiPackages.bertuiIcons
+    ? ',\n      "bertui-icons": "/node_modules/bertui-icons/generated/index.js"'
+    : ''
+  const elysiaEdenImport = bertuiPackages.elysiaEden
+    ? ',\n      "@elysiajs/eden": "/node_modules/@elysiajs/eden/dist/index.mjs"'
+    : ''
+  const bertuiAnimateCSS = bertuiPackages.bertuiAnimate
+    ? '<link rel="stylesheet" href="/css/bertui-animate.min.css">'
+    : ''
+
+  const importMapScript = `<script type="importmap">
   {
     "imports": {
       "react": "https://esm.sh/react@18.2.0",
@@ -137,15 +212,52 @@ ${bertuiAnimateCSS}
       "react-dom/client": "https://esm.sh/react-dom@18.2.0/client",
       "react/jsx-runtime": "https://esm.sh/react@18.2.0/jsx-runtime",
       "react/jsx-dev-runtime": "https://esm.sh/react@18.2.0/jsx-dev-runtime",
-      "@bunnyx/api": "/bunnyx-api/api-client.js",
-      "@elysiajs/eden": "/node_modules/@elysiajs/eden/dist/index.mjs"${bertuiIconsImport}${elysiaEdenImport}
+      "@bunnyx/api": "/bunnyx-api/api-client.js"${bertuiIconsImport}${elysiaEdenImport}
     }
   }
-  </script>
-</head>
-<body>
-  <div id="root"></div>
-  <script type="module" src="/${bundlePath}"></script>
-</body>
-</html>`;
+  </script>`
+
+  return { importMapScript, bertuiAnimateCSS }
+}
+
+async function copyBertuiPackagesToProduction(root, outDir) {
+  const nodeModulesDir = join(root, 'node_modules')
+  const packages = { bertuiIcons: false, bertuiAnimate: false, elysiaEden: false }
+
+  if (!existsSync(nodeModulesDir)) return packages
+
+  const bertuiIconsSrc = join(nodeModulesDir, 'bertui-icons')
+  if (existsSync(bertuiIconsSrc)) {
+    try {
+      const dest = join(outDir, 'node_modules', 'bertui-icons')
+      mkdirSync(join(outDir, 'node_modules'), { recursive: true })
+      cpSync(bertuiIconsSrc, dest, { recursive: true })
+      packages.bertuiIcons = true
+    } catch {}
+  }
+
+  const bertuiAnimateSrc = join(nodeModulesDir, 'bertui-animate', 'dist')
+  if (existsSync(bertuiAnimateSrc)) {
+    try {
+      const dest = join(outDir, 'css')
+      mkdirSync(dest, { recursive: true })
+      const minCSS = join(bertuiAnimateSrc, 'bertui-animate.min.css')
+      if (existsSync(minCSS)) {
+        cpSync(minCSS, join(dest, 'bertui-animate.min.css'))
+        packages.bertuiAnimate = true
+      }
+    } catch {}
+  }
+
+  const elysiaEdenSrc = join(nodeModulesDir, '@elysiajs', 'eden')
+  if (existsSync(elysiaEdenSrc)) {
+    try {
+      const dest = join(outDir, 'node_modules', '@elysiajs', 'eden')
+      mkdirSync(join(outDir, 'node_modules', '@elysiajs'), { recursive: true })
+      cpSync(elysiaEdenSrc, dest, { recursive: true })
+      packages.elysiaEden = true
+    } catch {}
+  }
+
+  return packages
 }

package/src/build/server-island-validator.js

@@ -1,12 +1,67 @@
 // bertui/src/build/server-island-validator.js
-// Server Islands removed — all pages are client-rendered.
+import logger from '../logger/logger.js'
+
+const BANNED_HOOKS = [
+  'useState', 'useEffect', 'useReducer', 'useCallback', 'useMemo',
+  'useRef', 'useContext', 'useLayoutEffect', 'useId',
+  'useImperativeHandle', 'useDebugValue', 'useDeferredValue',
+  'useTransition', 'useSyncExternalStore',
+]
+
+const BANNED_EVENTS = [
+  'onClick', 'onChange', 'onSubmit', 'onInput', 'onFocus',
+  'onBlur', 'onMouseEnter', 'onMouseLeave', 'onKeyDown', 'onKeyUp',
+]
 
 export function validateServerIsland(sourceCode, filePath) {
-  return { valid: true, errors: [] };
+  const errors = []
+
+  for (const hook of BANNED_HOOKS) {
+    if (new RegExp(`\\b${hook}\\s*\\(`).test(sourceCode)) {
+      errors.push(`Cannot use React hook "${hook}" in a static/server page — hooks need a browser runtime`)
+    }
+  }
+
+  for (const event of BANNED_EVENTS) {
+    if (sourceCode.includes(`${event}=`)) {
+      errors.push(`Cannot use event handler "${event}" in a static/server page — events need a browser runtime`)
+    }
+  }
+
+  if (/window\.|document\.|localStorage\.|sessionStorage\./.test(sourceCode)) {
+    errors.push('Cannot access browser APIs (window/document/localStorage) in a static/server page')
+  }
+
+  return { valid: errors.length === 0, errors }
 }
 
-export function displayValidationErrors(filePath, errors) {}
+export function displayValidationErrors(filePath, errors) {
+  logger.error(`\n❌ Static/Server page validation failed: ${filePath}`)
+  for (const err of errors) {
+    logger.error(`   · ${err}`)
+  }
+  logger.error(`   → Remove the above or switch to default render mode\n`)
+}
 
 export async function validateAllServerIslands(routes) {
-  return { serverIslands: [], validationResults: [] };
+  const serverIslands = []
+  const validationResults = []
+
+  for (const route of routes) {
+    try {
+      const src = await Bun.file(route.path).text()
+      const isStatic = /export\s+const\s+render\s*=\s*["'](server|static)["']/.test(src)
+      if (!isStatic) continue
+
+      const result = validateServerIsland(src, route.path)
+      serverIslands.push(route)
+      validationResults.push({ ...result, route: route.route, path: route.path })
+
+      if (!result.valid) {
+        displayValidationErrors(route.path, result.errors)
+      }
+    } catch {}
+  }
+
+  return { serverIslands, validationResults }
 }

package/src/build/ssr-renderer.js

@@ -0,0 +1,64 @@
+// bertui/src/build/ssr-renderer.js
+import { join } from 'path'
+import { existsSync, mkdirSync, rmSync } from 'fs'
+import logger from '../logger/logger.js'
+
+/**
+ * Render a static page to HTML string using renderToString.
+ * Forces both the page and renderToString to use the same React
+ * instance from the project's own node_modules.
+ */
+export async function renderPageToHTML(compiledPagePath, buildDir) {
+  try {
+    // Extract project root from compiled path
+    // e.g. /project/.bertuibuild/pages/about.js → /project/
+    const projectRoot = compiledPagePath.split('.bertuibuild')[0]
+
+    // Explicitly resolve React from the PROJECT's node_modules
+    // This prevents the two-React-instances problem when bertui is bun linked
+    const reactPath         = join(projectRoot, 'node_modules', 'react', 'index.js')
+    const reactDomServerPath = join(projectRoot, 'node_modules', 'react-dom', 'server.js')
+
+    if (!existsSync(reactPath)) {
+      logger.warn(`React not found in project node_modules: ${reactPath}`)
+      return null
+    }
+
+    if (!existsSync(reactDomServerPath)) {
+      logger.warn(`react-dom/server not found in project node_modules: ${reactDomServerPath}`)
+      return null
+    }
+
+    const React            = await import(reactPath)
+    const { renderToString } = await import(reactDomServerPath)
+
+    // Import the compiled page
+    const mod = await import(`${compiledPagePath}?t=${Date.now()}`)
+    const Component = mod.default
+
+    if (typeof Component !== 'function') {
+      logger.warn(`No default export found in ${compiledPagePath}`)
+      return null
+    }
+
+    return renderToString(React.createElement(Component))
+
+  } catch (err) {
+    logger.warn(`renderToString failed for ${compiledPagePath}: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Check if a route's source file has render = "server" or render = "static"
+ */
+export async function getPageRenderMode(sourcePath) {
+  try {
+    const src = await Bun.file(sourcePath).text()
+    if (/export\s+const\s+render\s*=\s*["']server["']/.test(src)) return 'server'
+    if (/export\s+const\s+render\s*=\s*["']static["']/.test(src)) return 'static'
+    return 'default'
+  } catch {
+    return 'default'
+  }
+}

package/src/build.js

@@ -43,11 +43,18 @@ export async function buildProduction(options = {}) {
     const importhow = config.importhow || {};
     logger.stepDone('Loading env', `${Object.keys(envVars).length} vars`);
 
+    // ── Step 2: Compile ──────────────────────────────────────────────────────
     // ── Step 2: Compile ──────────────────────────────────────────────────────
     logger.step(2, TOTAL_STEPS, 'Compiling');
     const { routes } = await compileForBuild(root, buildDir, envVars, config);
     logger.stepDone('Compiling', `${routes.length} routes`);
 
+    // TEMP DEBUG - remove after
+    const aboutPath = join(buildDir, 'pages', 'about.js')
+    if (existsSync(aboutPath)) {
+      const src = await Bun.file(aboutPath).text()
+      console.log('\n--- about.js compiled output ---\n', src.slice(0, 500), '\n---\n')
+    }
     // ── Step 3: Layouts ──────────────────────────────────────────────────────
     logger.step(3, TOTAL_STEPS, 'Layouts');
     const layouts = await compileLayouts(root, buildDir);
@@ -86,7 +93,7 @@ export async function buildProduction(options = {}) {
 
     // ── Step 9: HTML ─────────────────────────────────────────────────────────
     logger.step(9, TOTAL_STEPS, 'Generating HTML');
-    await generateProductionHTML(root, outDir, result, routes, config);
+    await generateProductionHTML(root, outDir, result, routes, config, buildDir)
     logger.stepDone('Generating HTML', `${routes.length} pages`);
 
     // ── Step 10: Sitemap + robots ────────────────────────────────────────────