@flexireact/core 2.0.1 → 2.1.0

package/cli/index.ts

@@ -856,10 +856,13 @@ ${pc.cyan('   ╰─────────────────────
 // Build Command
 // ============================================================================
 
-async function runBuild(): Promise<void> {
+async function runBuild(options: { analyze?: boolean } = {}): Promise<void> {
   console.log(MINI_LOGO);
   log.blank();
   log.info('Building for production...');
+  if (options.analyze) {
+    log.info('Bundle analysis enabled');
+  }
   log.blank();
 
   const spinner = ora({ text: 'Compiling...', color: 'cyan' }).start();
@@ -876,16 +879,50 @@ async function runBuild(): Promise<void> {
     const rawConfig = await configModule.loadConfig(projectRoot);
     const config = configModule.resolvePaths(rawConfig, projectRoot);
 
-    await buildModule.build({
+    const result = await buildModule.build({
       projectRoot,
       config,
-      mode: 'production'
+      mode: 'production',
+      analyze: options.analyze
     });
 
     spinner.succeed('Build complete!');
     log.blank();
     log.success(`Output: ${pc.cyan('.flexi/')}`);
 
+    // Show bundle analysis if enabled
+    if (options.analyze && result?.analysis) {
+      log.blank();
+      log.info('📊 Bundle Analysis:');
+      log.blank();
+      
+      const analysis = result.analysis;
+      
+      // Sort by size
+      const sorted = Object.entries(analysis.files || {})
+        .sort((a: any, b: any) => b[1].size - a[1].size);
+      
+      console.log(pc.dim('  ─────────────────────────────────────────────────'));
+      console.log(`  ${pc.bold('File')}${' '.repeat(35)}${pc.bold('Size')}`);
+      console.log(pc.dim('  ─────────────────────────────────────────────────'));
+      
+      for (const [file, info] of sorted.slice(0, 15) as any) {
+        const name = file.length > 35 ? '...' + file.slice(-32) : file;
+        const size = formatBytes(info.size);
+        const gzip = info.gzipSize ? pc.dim(` (${formatBytes(info.gzipSize)} gzip)`) : '';
+        console.log(`  ${name.padEnd(38)} ${pc.cyan(size)}${gzip}`);
+      }
+      
+      console.log(pc.dim('  ─────────────────────────────────────────────────'));
+      console.log(`  ${pc.bold('Total:')}${' '.repeat(31)} ${pc.green(formatBytes(analysis.totalSize || 0))}`);
+      
+      if (analysis.totalGzipSize) {
+        console.log(`  ${pc.dim('Gzipped:')}${' '.repeat(29)} ${pc.dim(formatBytes(analysis.totalGzipSize))}`);
+      }
+      
+      log.blank();
+    }
+
   } catch (error: any) {
     spinner.fail('Build failed');
     log.error(error.message);
@@ -893,6 +930,14 @@ async function runBuild(): Promise<void> {
   }
 }
 
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
 // ============================================================================
 // Start Command
 // ============================================================================
@@ -1078,7 +1123,8 @@ async function main(): Promise<void> {
       break;
 
     case 'build':
-      await runBuild();
+      const analyzeFlag = args.includes('--analyze') || args.includes('-a');
+      await runBuild({ analyze: analyzeFlag });
       break;
 
     case 'start':

package/core/build/index.ts

@@ -28,7 +28,8 @@ export async function build(options) {
   const {
     projectRoot,
     config,
-    mode = BuildMode.PRODUCTION
+    mode = BuildMode.PRODUCTION,
+    analyze = false
   } = options;
 
   const startTime = Date.now();
@@ -95,12 +96,79 @@ export async function build(options) {
   console.log(`  Server modules: ${serverResult.outputs.length}`);
   console.log('');
 
+  // Generate bundle analysis if requested
+  let analysis = null;
+  if (analyze) {
+    analysis = generateBundleAnalysis(clientResult, serverResult, outDir);
+  }
+
   return {
     success: true,
     duration,
     manifest,
     clientResult,
-    serverResult
+    serverResult,
+    analysis
+  };
+}
+
+/**
+ * Generates bundle analysis data
+ */
+function generateBundleAnalysis(clientResult, serverResult, outDir) {
+  const files: Record<string, { size: number; gzipSize?: number }> = {};
+  let totalSize = 0;
+  let totalGzipSize = 0;
+
+  // Analyze client outputs
+  for (const output of clientResult.outputs || []) {
+    if (output.path && fs.existsSync(output.path)) {
+      const stat = fs.statSync(output.path);
+      const relativePath = path.relative(outDir, output.path);
+      
+      // Estimate gzip size (roughly 30% of original for JS)
+      const gzipSize = Math.round(stat.size * 0.3);
+      
+      files[relativePath] = {
+        size: stat.size,
+        gzipSize
+      };
+      
+      totalSize += stat.size;
+      totalGzipSize += gzipSize;
+    }
+  }
+
+  // Analyze server outputs
+  for (const output of serverResult.outputs || []) {
+    if (output.path && fs.existsSync(output.path)) {
+      const stat = fs.statSync(output.path);
+      const relativePath = path.relative(outDir, output.path);
+      
+      files[relativePath] = {
+        size: stat.size
+      };
+      
+      totalSize += stat.size;
+    }
+  }
+
+  return {
+    files,
+    totalSize,
+    totalGzipSize,
+    clientSize: clientResult.outputs?.reduce((sum, o) => {
+      if (o.path && fs.existsSync(o.path)) {
+        return sum + fs.statSync(o.path).size;
+      }
+      return sum;
+    }, 0) || 0,
+    serverSize: serverResult.outputs?.reduce((sum, o) => {
+      if (o.path && fs.existsSync(o.path)) {
+        return sum + fs.statSync(o.path).size;
+      }
+      return sum;
+    }, 0) || 0
   };
 }
 

package/core/client/Link.tsx

@@ -0,0 +1,345 @@
+'use client';
+
+/**
+ * FlexiReact Link Component
+ * Enhanced link with prefetching, client-side navigation, and loading states
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  /** The URL to navigate to */
+  href: string;
+  /** Prefetch the page on hover/visibility */
+  prefetch?: boolean | 'hover' | 'viewport';
+  /** Replace the current history entry instead of pushing */
+  replace?: boolean;
+  /** Scroll to top after navigation */
+  scroll?: boolean;
+  /** Show loading indicator while navigating */
+  showLoading?: boolean;
+  /** Custom loading component */
+  loadingComponent?: React.ReactNode;
+  /** Callback when navigation starts */
+  onNavigationStart?: () => void;
+  /** Callback when navigation ends */
+  onNavigationEnd?: () => void;
+  /** Children */
+  children: React.ReactNode;
+}
+
+// Prefetch cache to avoid duplicate requests
+const prefetchCache = new Set<string>();
+
+// Prefetch a URL
+async function prefetchUrl(url: string): Promise<void> {
+  if (prefetchCache.has(url)) return;
+  
+  try {
+    // Mark as prefetched immediately to prevent duplicate requests
+    prefetchCache.add(url);
+    
+    // Use link preload for better browser optimization
+    const link = document.createElement('link');
+    link.rel = 'prefetch';
+    link.href = url;
+    link.as = 'document';
+    document.head.appendChild(link);
+    
+    // Also fetch the page to warm the cache
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+    
+    await fetch(url, {
+      method: 'GET',
+      credentials: 'same-origin',
+      signal: controller.signal,
+      headers: {
+        'X-Flexi-Prefetch': '1',
+        'Accept': 'text/html'
+      }
+    });
+    
+    clearTimeout(timeoutId);
+  } catch (error) {
+    // Remove from cache on error so it can be retried
+    prefetchCache.delete(url);
+  }
+}
+
+// Check if URL is internal
+function isInternalUrl(url: string): boolean {
+  if (url.startsWith('/')) return true;
+  if (url.startsWith('#')) return true;
+  
+  try {
+    const parsed = new URL(url, window.location.origin);
+    return parsed.origin === window.location.origin;
+  } catch {
+    return false;
+  }
+}
+
+// Navigate to a URL
+function navigate(url: string, options: { replace?: boolean; scroll?: boolean } = {}): void {
+  const { replace = false, scroll = true } = options;
+  
+  if (replace) {
+    window.history.replaceState({}, '', url);
+  } else {
+    window.history.pushState({}, '', url);
+  }
+  
+  // Dispatch popstate event to trigger any listeners
+  window.dispatchEvent(new PopStateEvent('popstate', { state: {} }));
+  
+  // Scroll to top if requested
+  if (scroll) {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  }
+}
+
+/**
+ * Link component with prefetching and client-side navigation
+ * 
+ * @example
+ * ```tsx
+ * import { Link } from '@flexireact/core/client';
+ * 
+ * // Basic usage
+ * <Link href="/about">About</Link>
+ * 
+ * // With prefetch on hover
+ * <Link href="/products" prefetch="hover">Products</Link>
+ * 
+ * // With prefetch on viewport visibility
+ * <Link href="/contact" prefetch="viewport">Contact</Link>
+ * 
+ * // Replace history instead of push
+ * <Link href="/login" replace>Login</Link>
+ * 
+ * // Disable scroll to top
+ * <Link href="/section#anchor" scroll={false}>Go to section</Link>
+ * ```
+ */
+export function Link({
+  href,
+  prefetch = true,
+  replace = false,
+  scroll = true,
+  showLoading = false,
+  loadingComponent,
+  onNavigationStart,
+  onNavigationEnd,
+  children,
+  className,
+  onClick,
+  onMouseEnter,
+  onFocus,
+  ...props
+}: LinkProps) {
+  const [isNavigating, setIsNavigating] = useState(false);
+  const linkRef = useRef<HTMLAnchorElement>(null);
+  const hasPrefetched = useRef(false);
+
+  // Prefetch on viewport visibility
+  useEffect(() => {
+    if (prefetch !== 'viewport' && prefetch !== true) return;
+    if (!isInternalUrl(href)) return;
+    if (hasPrefetched.current) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            prefetchUrl(href);
+            hasPrefetched.current = true;
+            observer.disconnect();
+          }
+        });
+      },
+      { rootMargin: '200px' }
+    );
+
+    if (linkRef.current) {
+      observer.observe(linkRef.current);
+    }
+
+    return () => observer.disconnect();
+  }, [href, prefetch]);
+
+  // Handle hover prefetch
+  const handleMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(e);
+      
+      if ((prefetch === 'hover' || prefetch === true) && isInternalUrl(href)) {
+        prefetchUrl(href);
+      }
+    },
+    [href, prefetch, onMouseEnter]
+  );
+
+  // Handle focus prefetch (for keyboard navigation)
+  const handleFocus = useCallback(
+    (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(e);
+      
+      if ((prefetch === 'hover' || prefetch === true) && isInternalUrl(href)) {
+        prefetchUrl(href);
+      }
+    },
+    [href, prefetch, onFocus]
+  );
+
+  // Handle click for client-side navigation
+  const handleClick = useCallback(
+    async (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(e);
+      
+      // Don't handle if default was prevented
+      if (e.defaultPrevented) return;
+      
+      // Don't handle if modifier keys are pressed (open in new tab, etc.)
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      
+      // Don't handle external URLs
+      if (!isInternalUrl(href)) return;
+      
+      // Don't handle if target is set
+      if (props.target && props.target !== '_self') return;
+      
+      // Prevent default navigation
+      e.preventDefault();
+      
+      // Start navigation
+      setIsNavigating(true);
+      onNavigationStart?.();
+      
+      try {
+        // Fetch the new page
+        const response = await fetch(href, {
+          method: 'GET',
+          credentials: 'same-origin',
+          headers: {
+            'X-Flexi-Navigation': '1',
+            'Accept': 'text/html'
+          }
+        });
+        
+        if (response.ok) {
+          const html = await response.text();
+          
+          // Parse and update the page
+          const parser = new DOMParser();
+          const doc = parser.parseFromString(html, 'text/html');
+          
+          // Update title
+          const newTitle = doc.querySelector('title')?.textContent;
+          if (newTitle) {
+            document.title = newTitle;
+          }
+          
+          // Update body content (or specific container)
+          const newContent = doc.querySelector('#root') || doc.body;
+          const currentContent = document.querySelector('#root') || document.body;
+          
+          if (newContent && currentContent) {
+            currentContent.innerHTML = newContent.innerHTML;
+          }
+          
+          // Update URL
+          navigate(href, { replace, scroll });
+        } else {
+          // Fallback to regular navigation on error
+          window.location.href = href;
+        }
+      } catch (error) {
+        // Fallback to regular navigation on error
+        window.location.href = href;
+      } finally {
+        setIsNavigating(false);
+        onNavigationEnd?.();
+      }
+    },
+    [href, replace, scroll, onClick, onNavigationStart, onNavigationEnd, props.target]
+  );
+
+  return (
+    <a
+      ref={linkRef}
+      href={href}
+      className={className}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      onFocus={handleFocus}
+      data-prefetch={prefetch}
+      data-navigating={isNavigating || undefined}
+      {...props}
+    >
+      {showLoading && isNavigating ? (
+        loadingComponent || (
+          <span className="flexi-link-loading">
+            <span className="flexi-link-spinner" />
+            {children}
+          </span>
+        )
+      ) : (
+        children
+      )}
+    </a>
+  );
+}
+
+/**
+ * Programmatic navigation function
+ * 
+ * @example
+ * ```tsx
+ * import { useRouter } from '@flexireact/core/client';
+ * 
+ * function MyComponent() {
+ *   const router = useRouter();
+ *   
+ *   const handleClick = () => {
+ *     router.push('/dashboard');
+ *   };
+ *   
+ *   return <button onClick={handleClick}>Go to Dashboard</button>;
+ * }
+ * ```
+ */
+export function useRouter() {
+  return {
+    push(url: string, options?: { scroll?: boolean }) {
+      navigate(url, { replace: false, scroll: options?.scroll ?? true });
+      // Trigger page reload for now (full SPA navigation requires more work)
+      window.location.href = url;
+    },
+    
+    replace(url: string, options?: { scroll?: boolean }) {
+      navigate(url, { replace: true, scroll: options?.scroll ?? true });
+      window.location.href = url;
+    },
+    
+    back() {
+      window.history.back();
+    },
+    
+    forward() {
+      window.history.forward();
+    },
+    
+    prefetch(url: string) {
+      if (isInternalUrl(url)) {
+        prefetchUrl(url);
+      }
+    },
+    
+    refresh() {
+      window.location.reload();
+    }
+  };
+}
+
+export default Link;

package/core/client/index.ts

@@ -4,5 +4,9 @@
  */
 
 export { hydrateIsland, hydrateApp } from './hydration.js';
-export { navigate, prefetch, Link } from './navigation.js';
+export { navigate, prefetch, Link as NavLink } from './navigation.js';
 export { useIsland, IslandBoundary } from './islands.js';
+
+// Enhanced Link component with prefetching
+export { Link, useRouter } from './Link.js';
+export type { LinkProps } from './Link.js';

package/core/helpers.ts

@@ -0,0 +1,494 @@
+/**
+ * FlexiReact Server Helpers
+ * Utility functions for server-side operations
+ */
+
+// ============================================================================
+// Response Helpers
+// ============================================================================
+
+/**
+ * Custom error classes for control flow
+ */
+export class RedirectError extends Error {
+  public readonly url: string;
+  public readonly statusCode: number;
+  public readonly type = 'redirect' as const;
+
+  constructor(url: string, statusCode: number = 307) {
+    super(`Redirect to ${url}`);
+    this.name = 'RedirectError';
+    this.url = url;
+    this.statusCode = statusCode;
+  }
+}
+
+export class NotFoundError extends Error {
+  public readonly type = 'notFound' as const;
+
+  constructor(message: string = 'Page not found') {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+/**
+ * Redirect to a different URL
+ * @param url - The URL to redirect to
+ * @param type - 'replace' (307) or 'push' (308) for permanent
+ * 
+ * @example
+ * ```tsx
+ * import { redirect } from '@flexireact/core';
+ * 
+ * export default function ProtectedPage() {
+ *   const user = getUser();
+ *   if (!user) {
+ *     redirect('/login');
+ *   }
+ *   return <Dashboard user={user} />;
+ * }
+ * ```
+ */
+export function redirect(url: string, type: 'replace' | 'permanent' = 'replace'): never {
+  const statusCode = type === 'permanent' ? 308 : 307;
+  throw new RedirectError(url, statusCode);
+}
+
+/**
+ * Trigger a 404 Not Found response
+ * 
+ * @example
+ * ```tsx
+ * import { notFound } from '@flexireact/core';
+ * 
+ * export default function ProductPage({ params }) {
+ *   const product = getProduct(params.id);
+ *   if (!product) {
+ *     notFound();
+ *   }
+ *   return <Product data={product} />;
+ * }
+ * ```
+ */
+export function notFound(message?: string): never {
+  throw new NotFoundError(message);
+}
+
+/**
+ * Create a JSON response
+ * 
+ * @example
+ * ```ts
+ * // In API route
+ * export function GET() {
+ *   return json({ message: 'Hello' });
+ * }
+ * 
+ * export function POST() {
+ *   return json({ error: 'Bad request' }, { status: 400 });
+ * }
+ * ```
+ */
+export function json<T>(
+  data: T,
+  options: {
+    status?: number;
+    headers?: Record<string, string>;
+  } = {}
+): Response {
+  const { status = 200, headers = {} } = options;
+  
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+}
+
+/**
+ * Create an HTML response
+ */
+export function html(
+  content: string,
+  options: {
+    status?: number;
+    headers?: Record<string, string>;
+  } = {}
+): Response {
+  const { status = 200, headers = {} } = options;
+  
+  return new Response(content, {
+    status,
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      ...headers
+    }
+  });
+}
+
+/**
+ * Create a text response
+ */
+export function text(
+  content: string,
+  options: {
+    status?: number;
+    headers?: Record<string, string>;
+  } = {}
+): Response {
+  const { status = 200, headers = {} } = options;
+  
+  return new Response(content, {
+    status,
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+      ...headers
+    }
+  });
+}
+
+// ============================================================================
+// Cookies API
+// ============================================================================
+
+export interface CookieOptions {
+  /** Max age in seconds */
+  maxAge?: number;
+  /** Expiration date */
+  expires?: Date;
+  /** Cookie path */
+  path?: string;
+  /** Cookie domain */
+  domain?: string;
+  /** Secure flag (HTTPS only) */
+  secure?: boolean;
+  /** HttpOnly flag */
+  httpOnly?: boolean;
+  /** SameSite policy */
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+
+/**
+ * Cookie utilities for server-side operations
+ */
+export const cookies = {
+  /**
+   * Parse cookies from a cookie header string
+   */
+  parse(cookieHeader: string): Record<string, string> {
+    const cookies: Record<string, string> = {};
+    if (!cookieHeader) return cookies;
+
+    cookieHeader.split(';').forEach(cookie => {
+      const [name, ...rest] = cookie.split('=');
+      if (name) {
+        const value = rest.join('=');
+        cookies[name.trim()] = decodeURIComponent(value.trim());
+      }
+    });
+
+    return cookies;
+  },
+
+  /**
+   * Get a cookie value from request headers
+   */
+  get(request: Request, name: string): string | undefined {
+    const cookieHeader = request.headers.get('cookie') || '';
+    const parsed = this.parse(cookieHeader);
+    return parsed[name];
+  },
+
+  /**
+   * Get all cookies from request
+   */
+  getAll(request: Request): Record<string, string> {
+    const cookieHeader = request.headers.get('cookie') || '';
+    return this.parse(cookieHeader);
+  },
+
+  /**
+   * Serialize a cookie for Set-Cookie header
+   */
+  serialize(name: string, value: string, options: CookieOptions = {}): string {
+    let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+
+    if (options.maxAge !== undefined) {
+      cookie += `; Max-Age=${options.maxAge}`;
+    }
+    if (options.expires) {
+      cookie += `; Expires=${options.expires.toUTCString()}`;
+    }
+    if (options.path) {
+      cookie += `; Path=${options.path}`;
+    }
+    if (options.domain) {
+      cookie += `; Domain=${options.domain}`;
+    }
+    if (options.secure) {
+      cookie += '; Secure';
+    }
+    if (options.httpOnly) {
+      cookie += '; HttpOnly';
+    }
+    if (options.sameSite) {
+      cookie += `; SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`;
+    }
+
+    return cookie;
+  },
+
+  /**
+   * Create a Set-Cookie header value
+   */
+  set(name: string, value: string, options: CookieOptions = {}): string {
+    return this.serialize(name, value, {
+      path: '/',
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      ...options
+    });
+  },
+
+  /**
+   * Create a cookie deletion header
+   */
+  delete(name: string, options: Omit<CookieOptions, 'maxAge' | 'expires'> = {}): string {
+    return this.serialize(name, '', {
+      ...options,
+      path: '/',
+      maxAge: 0
+    });
+  }
+};
+
+// ============================================================================
+// Headers API
+// ============================================================================
+
+/**
+ * Headers utilities for server-side operations
+ */
+export const headers = {
+  /**
+   * Create a new Headers object with common defaults
+   */
+  create(init?: HeadersInit): Headers {
+    return new Headers(init);
+  },
+
+  /**
+   * Get a header value from request
+   */
+  get(request: Request, name: string): string | null {
+    return request.headers.get(name);
+  },
+
+  /**
+   * Get all headers as an object
+   */
+  getAll(request: Request): Record<string, string> {
+    const result: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  },
+
+  /**
+   * Check if request has a specific header
+   */
+  has(request: Request, name: string): boolean {
+    return request.headers.has(name);
+  },
+
+  /**
+   * Get content type from request
+   */
+  contentType(request: Request): string | null {
+    return request.headers.get('content-type');
+  },
+
+  /**
+   * Check if request accepts JSON
+   */
+  acceptsJson(request: Request): boolean {
+    const accept = request.headers.get('accept') || '';
+    return accept.includes('application/json') || accept.includes('*/*');
+  },
+
+  /**
+   * Check if request is AJAX/fetch
+   */
+  isAjax(request: Request): boolean {
+    return request.headers.get('x-requested-with') === 'XMLHttpRequest' ||
+           this.acceptsJson(request);
+  },
+
+  /**
+   * Get authorization header
+   */
+  authorization(request: Request): { type: string; credentials: string } | null {
+    const auth = request.headers.get('authorization');
+    if (!auth) return null;
+
+    const [type, ...rest] = auth.split(' ');
+    return {
+      type: type.toLowerCase(),
+      credentials: rest.join(' ')
+    };
+  },
+
+  /**
+   * Get bearer token from authorization header
+   */
+  bearerToken(request: Request): string | null {
+    const auth = this.authorization(request);
+    if (auth?.type === 'bearer') {
+      return auth.credentials;
+    }
+    return null;
+  },
+
+  /**
+   * Common security headers
+   */
+  security(): Record<string, string> {
+    return {
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'DENY',
+      'X-XSS-Protection': '1; mode=block',
+      'Referrer-Policy': 'strict-origin-when-cross-origin',
+      'Permissions-Policy': 'camera=(), microphone=(), geolocation=()'
+    };
+  },
+
+  /**
+   * CORS headers
+   */
+  cors(options: {
+    origin?: string;
+    methods?: string[];
+    headers?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+  } = {}): Record<string, string> {
+    const {
+      origin = '*',
+      methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+      headers: allowHeaders = ['Content-Type', 'Authorization'],
+      credentials = false,
+      maxAge = 86400
+    } = options;
+
+    const corsHeaders: Record<string, string> = {
+      'Access-Control-Allow-Origin': origin,
+      'Access-Control-Allow-Methods': methods.join(', '),
+      'Access-Control-Allow-Headers': allowHeaders.join(', '),
+      'Access-Control-Max-Age': String(maxAge)
+    };
+
+    if (credentials) {
+      corsHeaders['Access-Control-Allow-Credentials'] = 'true';
+    }
+
+    return corsHeaders;
+  },
+
+  /**
+   * Cache control headers
+   */
+  cache(options: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    private?: boolean;
+    noStore?: boolean;
+  } = {}): Record<string, string> {
+    if (options.noStore) {
+      return { 'Cache-Control': 'no-store, no-cache, must-revalidate' };
+    }
+
+    const directives: string[] = [];
+    
+    if (options.private) {
+      directives.push('private');
+    } else {
+      directives.push('public');
+    }
+
+    if (options.maxAge !== undefined) {
+      directives.push(`max-age=${options.maxAge}`);
+    }
+
+    if (options.sMaxAge !== undefined) {
+      directives.push(`s-maxage=${options.sMaxAge}`);
+    }
+
+    if (options.staleWhileRevalidate !== undefined) {
+      directives.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+    }
+
+    return { 'Cache-Control': directives.join(', ') };
+  }
+};
+
+// ============================================================================
+// Request Helpers
+// ============================================================================
+
+/**
+ * Parse JSON body from request
+ */
+export async function parseJson<T = unknown>(request: Request): Promise<T> {
+  try {
+    return await request.json();
+  } catch {
+    throw new Error('Invalid JSON body');
+  }
+}
+
+/**
+ * Parse form data from request
+ */
+export async function parseFormData(request: Request): Promise<FormData> {
+  return await request.formData();
+}
+
+/**
+ * Parse URL search params
+ */
+export function parseSearchParams(request: Request): URLSearchParams {
+  const url = new URL(request.url);
+  return url.searchParams;
+}
+
+/**
+ * Get request method
+ */
+export function getMethod(request: Request): string {
+  return request.method.toUpperCase();
+}
+
+/**
+ * Get request pathname
+ */
+export function getPathname(request: Request): string {
+  const url = new URL(request.url);
+  return url.pathname;
+}
+
+/**
+ * Check if request method matches
+ */
+export function isMethod(request: Request, method: string | string[]): boolean {
+  const reqMethod = getMethod(request);
+  if (Array.isArray(method)) {
+    return method.map(m => m.toUpperCase()).includes(reqMethod);
+  }
+  return reqMethod === method.toUpperCase();
+}

package/core/index.ts

@@ -70,8 +70,33 @@ export {
   builtinPlugins 
 } from './plugins/index.js';
 
+// Server Helpers
+export {
+  // Response helpers
+  redirect,
+  notFound,
+  json,
+  html,
+  text,
+  // Error classes
+  RedirectError,
+  NotFoundError,
+  // Cookies API
+  cookies,
+  // Headers API
+  headers,
+  // Request helpers
+  parseJson,
+  parseFormData,
+  parseSearchParams,
+  getMethod,
+  getPathname,
+  isMethod
+} from './helpers.js';
+export type { CookieOptions } from './helpers.js';
+
 // Version
-export const VERSION = '2.0.1';
+export const VERSION = '2.1.0';
 
 // Default export
 export default {

package/core/render/index.ts

@@ -32,7 +32,23 @@ export async function renderPage(options) {
 
   try {
     // Build the component tree - start with the page component
-    let element = React.createElement(Component, props);
+    let element: any = React.createElement(Component, props);
+    
+    // Wrap with error boundary if error component exists
+    if (error) {
+      element = React.createElement(ErrorBoundaryWrapper as any, {
+        fallback: error,
+        children: element
+      });
+    }
+
+    // Wrap with Suspense if loading component exists (for streaming/async)
+    if (loading) {
+      element = React.createElement(React.Suspense as any, {
+        fallback: React.createElement(loading),
+        children: element
+      });
+    }
     
     // Wrap with layouts (innermost to outermost)
     // Each layout receives children as a prop

package/core/router/index.ts

@@ -96,13 +96,14 @@ export function buildRouteTree(pagesDir, layoutsDir, appDir = null, routesDir =
  * - api/hello.ts → /api/hello (API route)
  * - dashboard/layout.tsx → layout for /dashboard/*
  */
-function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], parentLayout = null) {
+function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], parentLayout = null, parentMiddleware = null) {
   const entries = fs.readdirSync(currentDir, { withFileTypes: true });
   
   // Find special files in current directory
   let layoutFile = null;
   let loadingFile = null;
   let errorFile = null;
+  let middlewareFile = null;
   
   for (const entry of entries) {
     if (entry.isFile()) {
@@ -114,9 +115,10 @@ function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], p
       if (name === 'layout') layoutFile = fullPath;
       if (name === 'loading') loadingFile = fullPath;
       if (name === 'error') errorFile = fullPath;
+      if (name === '_middleware' || name === 'middleware') middlewareFile = fullPath;
       
       // Skip special files and non-route files
-      if (['layout', 'loading', 'error', 'not-found'].includes(name)) continue;
+      if (['layout', 'loading', 'error', 'not-found', '_middleware', 'middleware'].includes(name)) continue;
       if (!['.tsx', '.jsx', '.ts', '.js'].includes(ext)) continue;
       
       // API routes (in api/ folder or .ts/.js files in api/)
@@ -171,6 +173,7 @@ function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], p
           layout: layoutFile || parentLayout,
           loading: loadingFile,
           error: errorFile,
+          middleware: middlewareFile || parentMiddleware,
           isFlexiRouter: true,
           isServerComponent: isServerComponent(fullPath),
           isClientComponent: isClientComponent(fullPath),
@@ -205,8 +208,9 @@ function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], p
       
       const newSegments = isGroup ? parentSegments : [...parentSegments, segmentName];
       const newLayout = layoutFile || parentLayout;
+      const newMiddleware = middlewareFile || parentMiddleware;
       
-      scanRoutesDirectory(baseDir, fullPath, routes, newSegments, newLayout);
+      scanRoutesDirectory(baseDir, fullPath, routes, newSegments, newLayout, newMiddleware);
     }
   }
 }
@@ -215,17 +219,18 @@ function scanRoutesDirectory(baseDir, currentDir, routes, parentSegments = [], p
  * Scans app directory for Next.js style routing
  * Supports: page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx
  */
-function scanAppDirectory(baseDir, currentDir, routes, parentSegments = [], parentLayout = null) {
+function scanAppDirectory(baseDir, currentDir, routes, parentSegments = [], parentLayout = null, parentMiddleware = null) {
   const entries = fs.readdirSync(currentDir, { withFileTypes: true });
   
   // Find special files in current directory
-  const specialFiles = {
+  const specialFiles: Record<string, string | null> = {
     page: null,
     layout: null,
     loading: null,
     error: null,
     notFound: null,
-    template: null
+    template: null,
+    middleware: null
   };
 
   for (const entry of entries) {
@@ -239,6 +244,7 @@ function scanAppDirectory(baseDir, currentDir, routes, parentSegments = [], pare
       if (name === 'error') specialFiles.error = fullPath;
       if (name === 'not-found') specialFiles.notFound = fullPath;
       if (name === 'template') specialFiles.template = fullPath;
+      if (name === 'middleware' || name === '_middleware') specialFiles.middleware = fullPath;
     }
   }
 
@@ -257,6 +263,7 @@ function scanAppDirectory(baseDir, currentDir, routes, parentSegments = [], pare
       error: specialFiles.error,
       notFound: specialFiles.notFound,
       template: specialFiles.template,
+      middleware: specialFiles.middleware || parentMiddleware,
       isAppRouter: true,
       isServerComponent: isServerComponent(specialFiles.page),
       isClientComponent: isClientComponent(specialFiles.page),
@@ -289,8 +296,9 @@ function scanAppDirectory(baseDir, currentDir, routes, parentSegments = [], pare
       
       const newSegments = isGroup ? parentSegments : [...parentSegments, segmentName];
       const newLayout = specialFiles.layout || parentLayout;
+      const newMiddleware = specialFiles.middleware || parentMiddleware;
       
-      scanAppDirectory(baseDir, fullPath, routes, newSegments, newLayout);
+      scanAppDirectory(baseDir, fullPath, routes, newSegments, newLayout, newMiddleware);
     }
   }
 }

package/core/server/index.ts

@@ -15,6 +15,7 @@ import { loadPlugins, pluginManager, PluginHooks } from '../plugins/index.js';
 import { getRegisteredIslands, generateAdvancedHydrationScript } from '../islands/index.js';
 import { createRequestContext, RequestContext, RouteContext } from '../context.js';
 import { logger } from '../logger.js';
+import { RedirectError, NotFoundError } from '../helpers.js';
 import React from 'react';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -157,7 +158,21 @@ export async function createServer(options: CreateServerOptions = {}) {
       res.writeHead(404, { 'Content-Type': 'text/html' });
       res.end(renderError(404, 'Page not found'));
 
-    } catch (error) {
+    } catch (error: any) {
+      // Handle redirect() calls
+      if (error instanceof RedirectError) {
+        res.writeHead(error.statusCode, { 'Location': error.url });
+        res.end();
+        return;
+      }
+
+      // Handle notFound() calls
+      if (error instanceof NotFoundError) {
+        res.writeHead(404, { 'Content-Type': 'text/html' });
+        res.end(renderError(404, error.message));
+        return;
+      }
+
       console.error('Server Error:', error);
 
       if (!res.headersSent) {
@@ -360,6 +375,37 @@ function createApiResponse(res) {
  */
 async function handlePageRoute(req, res, route, routes, config, loadModule, url) {
   try {
+    // Run route-specific middleware if exists
+    if (route.middleware) {
+      try {
+        const middlewareModule = await loadModule(route.middleware);
+        const middlewareFn = middlewareModule.default || middlewareModule.middleware;
+        
+        if (typeof middlewareFn === 'function') {
+          const result = await middlewareFn(req, res, { route, params: route.params });
+          
+          // If middleware returns a response, use it
+          if (result?.redirect) {
+            res.writeHead(result.statusCode || 307, { 'Location': result.redirect });
+            res.end();
+            return;
+          }
+          
+          if (result?.rewrite) {
+            // Rewrite to different path
+            req.url = result.rewrite;
+          }
+          
+          if (result === false || result?.stop) {
+            // Middleware stopped the request
+            return;
+          }
+        }
+      } catch (middlewareError: any) {
+        console.error('Route middleware error:', middlewareError.message);
+      }
+    }
+
     // Load page module
     const pageModule = await loadModule(route.filePath);
     const Component = pageModule.default;

package/core/tsconfig.json

@@ -4,6 +4,7 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
     "outDir": "./dist",
     "rootDir": ".",
     "strict": false,
@@ -22,7 +23,8 @@
   },
   "include": [
     "*.ts",
-    "**/*.ts"
+    "**/*.ts",
+    "**/*.tsx"
   ],
   "exclude": ["node_modules", "dist"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flexireact/core",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "The Modern React Framework v2 - SSR, SSG, Islands, App Router, TypeScript, Tailwind",
   "main": "core/index.ts",
   "types": "core/types.ts",