@flexireact/core 2.4.0 → 2.5.0

package/cli/generators.ts

@@ -0,0 +1,616 @@
+/**
+ * FlexiReact CLI Generators
+ * Scaffolding commands for rapid development
+ */
+
+import fs from 'fs';
+import path from 'path';
+import pc from 'picocolors';
+import prompts from 'prompts';
+
+const log = {
+  info: (msg: string) => console.log(`${pc.cyan('ℹ')} ${msg}`),
+  success: (msg: string) => console.log(`${pc.green('✓')} ${msg}`),
+  warn: (msg: string) => console.log(`${pc.yellow('⚠')} ${pc.yellow(msg)}`),
+  error: (msg: string) => console.log(`${pc.red('✗')} ${pc.red(msg)}`),
+  blank: () => console.log(''),
+};
+
+// ============================================================================
+// Templates
+// ============================================================================
+
+const templates = {
+  // Page template
+  page: (name: string, options: { client?: boolean }) => `${options.client ? "'use client';\n\n" : ''}import React from 'react';
+
+export default function ${toPascalCase(name)}Page() {
+  return (
+    <div className="min-h-screen p-8">
+      <h1 className="text-4xl font-bold">${toPascalCase(name)}</h1>
+      <p className="text-gray-400 mt-4">Welcome to ${name} page</p>
+    </div>
+  );
+}
+`,
+
+  // Layout template
+  layout: (name: string) => `import React from 'react';
+
+interface ${toPascalCase(name)}LayoutProps {
+  children: React.ReactNode;
+}
+
+export default function ${toPascalCase(name)}Layout({ children }: ${toPascalCase(name)}LayoutProps) {
+  return (
+    <div className="${name}-layout">
+      {/* Add your layout wrapper here */}
+      {children}
+    </div>
+  );
+}
+`,
+
+  // Component template
+  component: (name: string, options: { client?: boolean; props?: boolean }) => {
+    const propsInterface = options.props ? `
+interface ${toPascalCase(name)}Props {
+  className?: string;
+  children?: React.ReactNode;
+}
+` : '';
+    const propsType = options.props ? `{ className, children }: ${toPascalCase(name)}Props` : '{}';
+    
+    return `${options.client ? "'use client';\n\n" : ''}import React from 'react';
+import { cn } from '@/lib/utils';
+${propsInterface}
+export function ${toPascalCase(name)}(${propsType}) {
+  return (
+    <div className={cn('${toKebabCase(name)}', ${options.props ? 'className' : "''"})}>
+      ${options.props ? '{children}' : `{/* ${toPascalCase(name)} content */}`}
+    </div>
+  );
+}
+
+export default ${toPascalCase(name)};
+`;
+  },
+
+  // Hook template
+  hook: (name: string) => `import { useState, useEffect, useCallback } from 'react';
+
+export function use${toPascalCase(name)}() {
+  const [state, setState] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const execute = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      // Add your logic here
+      setState(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { state, loading, error, execute };
+}
+
+export default use${toPascalCase(name)};
+`,
+
+  // API route template
+  api: (name: string) => `import type { IncomingMessage, ServerResponse } from 'http';
+
+export default async function handler(req: IncomingMessage, res: ServerResponse) {
+  const method = req.method;
+
+  switch (method) {
+    case 'GET':
+      return handleGet(req, res);
+    case 'POST':
+      return handlePost(req, res);
+    default:
+      res.statusCode = 405;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ error: 'Method not allowed' }));
+  }
+}
+
+async function handleGet(req: IncomingMessage, res: ServerResponse) {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify({ message: '${name} API - GET' }));
+}
+
+async function handlePost(req: IncomingMessage, res: ServerResponse) {
+  // Parse body
+  let body = '';
+  for await (const chunk of req) {
+    body += chunk;
+  }
+  const data = body ? JSON.parse(body) : {};
+
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify({ message: '${name} API - POST', data }));
+}
+`,
+
+  // Server Action template
+  action: (name: string) => `'use server';
+
+import { revalidatePath } from '@flexireact/core';
+
+export async function ${toCamelCase(name)}Action(formData: FormData) {
+  // Validate input
+  const data = Object.fromEntries(formData);
+  
+  try {
+    // Add your server logic here
+    console.log('${toPascalCase(name)} action executed:', data);
+    
+    // Revalidate cache if needed
+    // revalidatePath('/');
+    
+    return { success: true, data };
+  } catch (error) {
+    return { 
+      success: false, 
+      error: error instanceof Error ? error.message : 'Unknown error' 
+    };
+  }
+}
+`,
+
+  // Middleware template
+  middleware: (name: string) => `import type { IncomingMessage, ServerResponse } from 'http';
+
+export interface ${toPascalCase(name)}MiddlewareOptions {
+  // Add your options here
+}
+
+export function ${toCamelCase(name)}Middleware(options: ${toPascalCase(name)}MiddlewareOptions = {}) {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: () => Promise<void>
+  ) => {
+    // Before request handling
+    console.log('[${toPascalCase(name)}] Request:', req.url);
+    
+    // Continue to next middleware/handler
+    await next();
+    
+    // After request handling (optional)
+  };
+}
+
+export default ${toCamelCase(name)}Middleware;
+`,
+
+  // Context template
+  context: (name: string) => `'use client';
+
+import React, { createContext, useContext, useState, useCallback } from 'react';
+
+interface ${toPascalCase(name)}State {
+  // Add your state properties here
+  value: string | null;
+}
+
+interface ${toPascalCase(name)}ContextValue extends ${toPascalCase(name)}State {
+  setValue: (value: string) => void;
+  reset: () => void;
+}
+
+const ${toPascalCase(name)}Context = createContext<${toPascalCase(name)}ContextValue | null>(null);
+
+export function ${toPascalCase(name)}Provider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState<${toPascalCase(name)}State>({
+    value: null,
+  });
+
+  const setValue = useCallback((value: string) => {
+    setState(prev => ({ ...prev, value }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setState({ value: null });
+  }, []);
+
+  return (
+    <${toPascalCase(name)}Context.Provider value={{ ...state, setValue, reset }}>
+      {children}
+    </${toPascalCase(name)}Context.Provider>
+  );
+}
+
+export function use${toPascalCase(name)}() {
+  const context = useContext(${toPascalCase(name)}Context);
+  if (!context) {
+    throw new Error('use${toPascalCase(name)} must be used within a ${toPascalCase(name)}Provider');
+  }
+  return context;
+}
+`,
+
+  // Loading template
+  loading: () => `import React from 'react';
+import { Spinner } from '@flexireact/flexi-ui';
+
+export default function Loading() {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <Spinner size="lg" />
+    </div>
+  );
+}
+`,
+
+  // Error template
+  error: () => `'use client';
+
+import React from 'react';
+import { Button, Alert } from '@flexireact/flexi-ui';
+
+interface ErrorProps {
+  error: Error;
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: ErrorProps) {
+  return (
+    <div className="min-h-screen flex flex-col items-center justify-center p-8">
+      <Alert variant="error" className="max-w-md mb-8">
+        <h2 className="font-bold text-lg mb-2">Something went wrong</h2>
+        <p className="text-sm">{error.message}</p>
+      </Alert>
+      <Button onClick={reset}>Try again</Button>
+    </div>
+  );
+}
+`,
+
+  // Not found template
+  notFound: () => `import React from 'react';
+import { Button } from '@flexireact/flexi-ui';
+
+export default function NotFound() {
+  return (
+    <div className="min-h-screen flex flex-col items-center justify-center p-8">
+      <h1 className="text-8xl font-bold text-primary mb-4">404</h1>
+      <p className="text-gray-400 text-xl mb-8">Page not found</p>
+      <Button asChild>
+        <a href="/">← Back Home</a>
+      </Button>
+    </div>
+  );
+}
+`,
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function toPascalCase(str: string): string {
+  return str
+    .replace(/[-_](.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (_, c) => c.toUpperCase());
+}
+
+function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_](.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+
+function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase();
+}
+
+function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function writeFile(filePath: string, content: string): void {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, content);
+}
+
+// ============================================================================
+// Generator Commands
+// ============================================================================
+
+export type GeneratorType = 
+  | 'page' 
+  | 'layout' 
+  | 'component' 
+  | 'hook' 
+  | 'api' 
+  | 'action' 
+  | 'middleware' 
+  | 'context'
+  | 'loading'
+  | 'error'
+  | 'not-found';
+
+export async function runGenerate(type?: string, name?: string): Promise<void> {
+  const cwd = process.cwd();
+  
+  // Check if we're in a FlexiReact project
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    log.error('Not in a FlexiReact project. Run this command in your project root.');
+    process.exit(1);
+  }
+
+  // Interactive mode if no type provided
+  if (!type) {
+    const response = await prompts([
+      {
+        type: 'select',
+        name: 'type',
+        message: 'What do you want to generate?',
+        choices: [
+          { title: '📄 Page', value: 'page', description: 'A new page in app/ or pages/' },
+          { title: '📐 Layout', value: 'layout', description: 'A layout wrapper component' },
+          { title: '🧩 Component', value: 'component', description: 'A reusable React component' },
+          { title: '🪝 Hook', value: 'hook', description: 'A custom React hook' },
+          { title: '🔌 API Route', value: 'api', description: 'An API endpoint' },
+          { title: '⚡ Server Action', value: 'action', description: 'A server action function' },
+          { title: '🛡️ Middleware', value: 'middleware', description: 'Request middleware' },
+          { title: '🌐 Context', value: 'context', description: 'React context provider' },
+          { title: '⏳ Loading', value: 'loading', description: 'Loading state component' },
+          { title: '❌ Error', value: 'error', description: 'Error boundary component' },
+          { title: '🔍 Not Found', value: 'not-found', description: '404 page component' },
+        ],
+      },
+      {
+        type: (prev) => ['loading', 'error', 'not-found'].includes(prev) ? null : 'text',
+        name: 'name',
+        message: 'Name:',
+        validate: (v: string) => v.length > 0 || 'Name is required',
+      },
+    ]);
+
+    if (!response.type) process.exit(0);
+    type = response.type;
+    name = response.name;
+  }
+
+  // Validate type
+  const validTypes: GeneratorType[] = [
+    'page', 'layout', 'component', 'hook', 'api', 
+    'action', 'middleware', 'context', 'loading', 'error', 'not-found'
+  ];
+  
+  if (!validTypes.includes(type as GeneratorType)) {
+    log.error(`Invalid type: ${type}`);
+    log.info(`Valid types: ${validTypes.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Special types that don't need a name
+  if (type && ['loading', 'error', 'not-found'].includes(type)) {
+    await generateSpecialFile(type as 'loading' | 'error' | 'not-found', cwd);
+    return;
+  }
+
+  // Get name if not provided
+  let finalName = name;
+  if (!finalName) {
+    const response = await prompts({
+      type: 'text',
+      name: 'name',
+      message: `${toPascalCase(type || 'item')} name:`,
+      validate: (v: string) => v.length > 0 || 'Name is required',
+    });
+    finalName = response.name;
+    if (!finalName) process.exit(0);
+  }
+
+  // Generate based on type
+  switch (type) {
+    case 'page':
+      await generatePage(finalName, cwd);
+      break;
+    case 'layout':
+      await generateLayout(finalName, cwd);
+      break;
+    case 'component':
+      await generateComponent(finalName, cwd);
+      break;
+    case 'hook':
+      await generateHook(finalName, cwd);
+      break;
+    case 'api':
+      await generateApi(finalName, cwd);
+      break;
+    case 'action':
+      await generateAction(finalName, cwd);
+      break;
+    case 'middleware':
+      await generateMiddleware(finalName, cwd);
+      break;
+    case 'context':
+      await generateContext(finalName, cwd);
+      break;
+  }
+}
+
+async function generatePage(name: string, cwd: string): Promise<void> {
+  const response = await prompts([
+    {
+      type: 'select',
+      name: 'directory',
+      message: 'Where to create the page?',
+      choices: [
+        { title: 'app/ (App Router)', value: 'app' },
+        { title: 'pages/ (Pages Router)', value: 'pages' },
+      ],
+    },
+    {
+      type: 'toggle',
+      name: 'client',
+      message: 'Client component? (use client)',
+      initial: false,
+      active: 'Yes',
+      inactive: 'No',
+    },
+  ]);
+
+  const fileName = response.directory === 'app' ? 'page.tsx' : `${toKebabCase(name)}.tsx`;
+  const filePath = response.directory === 'app' 
+    ? path.join(cwd, 'app', toKebabCase(name), fileName)
+    : path.join(cwd, 'pages', fileName);
+
+  writeFile(filePath, templates.page(name, { client: response.client }));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateLayout(name: string, cwd: string): Promise<void> {
+  const filePath = path.join(cwd, 'app', toKebabCase(name), 'layout.tsx');
+  writeFile(filePath, templates.layout(name));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateComponent(name: string, cwd: string): Promise<void> {
+  const response = await prompts([
+    {
+      type: 'select',
+      name: 'directory',
+      message: 'Where to create the component?',
+      choices: [
+        { title: 'components/', value: 'components' },
+        { title: 'app/components/', value: 'app/components' },
+      ],
+    },
+    {
+      type: 'toggle',
+      name: 'client',
+      message: 'Client component?',
+      initial: true,
+      active: 'Yes',
+      inactive: 'No',
+    },
+    {
+      type: 'toggle',
+      name: 'props',
+      message: 'Include props interface?',
+      initial: true,
+      active: 'Yes',
+      inactive: 'No',
+    },
+  ]);
+
+  const filePath = path.join(cwd, response.directory, `${toPascalCase(name)}.tsx`);
+  writeFile(filePath, templates.component(name, { client: response.client, props: response.props }));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateHook(name: string, cwd: string): Promise<void> {
+  const hookName = name.startsWith('use') ? name : `use-${name}`;
+  const filePath = path.join(cwd, 'hooks', `${toKebabCase(hookName)}.ts`);
+  writeFile(filePath, templates.hook(hookName.replace(/^use-?/, '')));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateApi(name: string, cwd: string): Promise<void> {
+  const filePath = path.join(cwd, 'pages', 'api', `${toKebabCase(name)}.ts`);
+  writeFile(filePath, templates.api(name));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateAction(name: string, cwd: string): Promise<void> {
+  const filePath = path.join(cwd, 'actions', `${toKebabCase(name)}.ts`);
+  writeFile(filePath, templates.action(name));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateMiddleware(name: string, cwd: string): Promise<void> {
+  const filePath = path.join(cwd, 'middleware', `${toKebabCase(name)}.ts`);
+  writeFile(filePath, templates.middleware(name));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateContext(name: string, cwd: string): Promise<void> {
+  const filePath = path.join(cwd, 'contexts', `${toPascalCase(name)}Context.tsx`);
+  writeFile(filePath, templates.context(name));
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+async function generateSpecialFile(type: 'loading' | 'error' | 'not-found', cwd: string): Promise<void> {
+  const response = await prompts({
+    type: 'text',
+    name: 'path',
+    message: 'Path (relative to app/):',
+    initial: '',
+  });
+
+  const basePath = response.path ? path.join(cwd, 'app', response.path) : path.join(cwd, 'app');
+  
+  let fileName: string;
+  let content: string;
+  
+  switch (type) {
+    case 'loading':
+      fileName = 'loading.tsx';
+      content = templates.loading();
+      break;
+    case 'error':
+      fileName = 'error.tsx';
+      content = templates.error();
+      break;
+    case 'not-found':
+      fileName = 'not-found.tsx';
+      content = templates.notFound();
+      break;
+  }
+
+  const filePath = path.join(basePath, fileName);
+  writeFile(filePath, content);
+  log.success(`Created ${pc.cyan(path.relative(cwd, filePath))}`);
+}
+
+// ============================================================================
+// List Generators
+// ============================================================================
+
+export function listGenerators(): void {
+  console.log(`
+${pc.bold('Available Generators:')}
+
+  ${pc.cyan('page')}        Create a new page (app/ or pages/)
+  ${pc.cyan('layout')}      Create a layout wrapper
+  ${pc.cyan('component')}   Create a React component
+  ${pc.cyan('hook')}        Create a custom hook
+  ${pc.cyan('api')}         Create an API route
+  ${pc.cyan('action')}      Create a server action
+  ${pc.cyan('middleware')}  Create request middleware
+  ${pc.cyan('context')}     Create a React context
+  ${pc.cyan('loading')}     Create a loading component
+  ${pc.cyan('error')}       Create an error boundary
+  ${pc.cyan('not-found')}   Create a 404 page
+
+${pc.bold('Usage:')}
+  ${pc.dim('$')} flexi generate ${pc.cyan('<type>')} ${pc.dim('[name]')}
+  ${pc.dim('$')} flexi g ${pc.cyan('<type>')} ${pc.dim('[name]')}
+
+${pc.bold('Examples:')}
+  ${pc.dim('$')} flexi g page dashboard
+  ${pc.dim('$')} flexi g component Button
+  ${pc.dim('$')} flexi g hook auth
+  ${pc.dim('$')} flexi g api users
+`);
+}

package/cli/index.ts

@@ -12,10 +12,11 @@ import { execSync, spawn } from 'child_process';
 import pc from 'picocolors';
 import prompts from 'prompts';
 import ora from 'ora';
+import { runGenerate, listGenerators } from './generators.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const VERSION = '2.1.0';
+const VERSION = '2.5.0';
 
 // ============================================================================
 // ASCII Logo & Branding
@@ -1090,18 +1091,26 @@ function showHelp(): void {
   log.blank();
   
   console.log(`  ${pc.bold('Commands:')}`);
-  console.log(`    ${pc.cyan('create')} ${pc.dim('<name>')}    Create a new FlexiReact project`);
-  console.log(`    ${pc.cyan('dev')}               Start development server`);
-  console.log(`    ${pc.cyan('build')}             Build for production`);
-  console.log(`    ${pc.cyan('start')}             Start production server`);
-  console.log(`    ${pc.cyan('doctor')}            Check project health`);
-  console.log(`    ${pc.cyan('help')}              Show this help message`);
+  console.log(`    ${pc.cyan('create')} ${pc.dim('<name>')}       Create a new FlexiReact project`);
+  console.log(`    ${pc.cyan('dev')}                  Start development server`);
+  console.log(`    ${pc.cyan('build')}                Build for production`);
+  console.log(`    ${pc.cyan('start')}                Start production server`);
+  console.log(`    ${pc.cyan('generate')} ${pc.dim('<type>')}     Generate component/page/hook/etc (alias: g)`);
+  console.log(`    ${pc.cyan('doctor')}               Check project health`);
+  console.log(`    ${pc.cyan('help')}                 Show this help message`);
+  log.blank();
+  
+  console.log(`  ${pc.bold('Generate Types:')}`);
+  console.log(`    ${pc.dim('page, layout, component, hook, api, action, middleware, context')}`);
+  console.log(`    ${pc.dim('loading, error, not-found')}`);
   log.blank();
   
   console.log(`  ${pc.bold('Examples:')}`);
   console.log(`    ${pc.dim('$')} flexi create my-app`);
   console.log(`    ${pc.dim('$')} flexi dev`);
-  console.log(`    ${pc.dim('$')} flexi build && flexi start`);
+  console.log(`    ${pc.dim('$')} flexi g component Button`);
+  console.log(`    ${pc.dim('$')} flexi g page dashboard`);
+  console.log(`    ${pc.dim('$')} flexi build --analyze`);
   log.blank();
 }
 
@@ -1135,6 +1144,16 @@ async function main(): Promise<void> {
       await runDoctor();
       break;
 
+    case 'generate':
+    case 'g':
+      await runGenerate(args[1], args[2]);
+      break;
+
+    case 'generate:list':
+    case 'g:list':
+      listGenerators();
+      break;
+
     case 'version':
     case '-v':
     case '--version':

package/core/devtools/index.ts

@@ -0,0 +1,644 @@
+/**
+ * FlexiReact DevTools
+ * Advanced development tools for debugging and performance monitoring
+ */
+
+import React from 'react';
+
+// ============================================================================
+// DevTools State
+// ============================================================================
+
+interface DevToolsState {
+  enabled: boolean;
+  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  expanded: boolean;
+  activeTab: 'routes' | 'components' | 'network' | 'performance' | 'state' | 'console';
+  theme: 'dark' | 'light';
+}
+
+interface RouteInfo {
+  path: string;
+  component: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  loadTime: number;
+}
+
+interface ComponentInfo {
+  name: string;
+  renderCount: number;
+  lastRenderTime: number;
+  props: Record<string, any>;
+  isIsland: boolean;
+}
+
+interface NetworkRequest {
+  id: string;
+  url: string;
+  method: string;
+  status: number;
+  duration: number;
+  size: number;
+  timestamp: number;
+  type: 'fetch' | 'xhr' | 'ssr' | 'action';
+}
+
+interface PerformanceMetric {
+  name: string;
+  value: number;
+  rating: 'good' | 'needs-improvement' | 'poor';
+}
+
+// Global DevTools state
+const devToolsState: {
+  routes: RouteInfo[];
+  components: Map<string, ComponentInfo>;
+  network: NetworkRequest[];
+  performance: PerformanceMetric[];
+  logs: Array<{ level: string; message: string; timestamp: number }>;
+  listeners: Set<() => void>;
+} = {
+  routes: [],
+  components: new Map(),
+  network: [],
+  performance: [],
+  logs: [],
+  listeners: new Set(),
+};
+
+// ============================================================================
+// DevTools API
+// ============================================================================
+
+export const devtools = {
+  // Track route navigation
+  trackRoute(info: RouteInfo): void {
+    devToolsState.routes.unshift(info);
+    if (devToolsState.routes.length > 50) {
+      devToolsState.routes.pop();
+    }
+    this.notify();
+  },
+
+  // Track component render
+  trackComponent(name: string, info: Partial<ComponentInfo>): void {
+    const existing = devToolsState.components.get(name) || {
+      name,
+      renderCount: 0,
+      lastRenderTime: 0,
+      props: {},
+      isIsland: false,
+    };
+    
+    devToolsState.components.set(name, {
+      ...existing,
+      ...info,
+      renderCount: existing.renderCount + 1,
+      lastRenderTime: Date.now(),
+    });
+    this.notify();
+  },
+
+  // Track network request
+  trackRequest(request: NetworkRequest): void {
+    devToolsState.network.unshift(request);
+    if (devToolsState.network.length > 100) {
+      devToolsState.network.pop();
+    }
+    this.notify();
+  },
+
+  // Track performance metric
+  trackMetric(metric: PerformanceMetric): void {
+    const existing = devToolsState.performance.findIndex(m => m.name === metric.name);
+    if (existing >= 0) {
+      devToolsState.performance[existing] = metric;
+    } else {
+      devToolsState.performance.push(metric);
+    }
+    this.notify();
+  },
+
+  // Log message
+  log(level: 'info' | 'warn' | 'error' | 'debug', message: string): void {
+    devToolsState.logs.unshift({
+      level,
+      message,
+      timestamp: Date.now(),
+    });
+    if (devToolsState.logs.length > 200) {
+      devToolsState.logs.pop();
+    }
+    this.notify();
+  },
+
+  // Get current state
+  getState() {
+    return {
+      routes: devToolsState.routes,
+      components: Array.from(devToolsState.components.values()),
+      network: devToolsState.network,
+      performance: devToolsState.performance,
+      logs: devToolsState.logs,
+    };
+  },
+
+  // Subscribe to changes
+  subscribe(listener: () => void): () => void {
+    devToolsState.listeners.add(listener);
+    return () => devToolsState.listeners.delete(listener);
+  },
+
+  // Notify listeners
+  notify(): void {
+    devToolsState.listeners.forEach(listener => listener());
+  },
+
+  // Clear all data
+  clear(): void {
+    devToolsState.routes = [];
+    devToolsState.components.clear();
+    devToolsState.network = [];
+    devToolsState.performance = [];
+    devToolsState.logs = [];
+    this.notify();
+  },
+};
+
+// ============================================================================
+// Performance Monitoring
+// ============================================================================
+
+export function initPerformanceMonitoring(): void {
+  if (typeof window === 'undefined') return;
+
+  // Core Web Vitals
+  try {
+    // LCP (Largest Contentful Paint)
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      const lastEntry = entries[entries.length - 1] as any;
+      devtools.trackMetric({
+        name: 'LCP',
+        value: lastEntry.startTime,
+        rating: lastEntry.startTime < 2500 ? 'good' : lastEntry.startTime < 4000 ? 'needs-improvement' : 'poor',
+      });
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+
+    // FID (First Input Delay)
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      entries.forEach((entry: any) => {
+        devtools.trackMetric({
+          name: 'FID',
+          value: entry.processingStart - entry.startTime,
+          rating: entry.processingStart - entry.startTime < 100 ? 'good' : 
+                  entry.processingStart - entry.startTime < 300 ? 'needs-improvement' : 'poor',
+        });
+      });
+    }).observe({ type: 'first-input', buffered: true });
+
+    // CLS (Cumulative Layout Shift)
+    let clsValue = 0;
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as any[]) {
+        if (!entry.hadRecentInput) {
+          clsValue += entry.value;
+        }
+      }
+      devtools.trackMetric({
+        name: 'CLS',
+        value: clsValue,
+        rating: clsValue < 0.1 ? 'good' : clsValue < 0.25 ? 'needs-improvement' : 'poor',
+      });
+    }).observe({ type: 'layout-shift', buffered: true });
+
+    // TTFB (Time to First Byte)
+    const navEntry = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+    if (navEntry) {
+      devtools.trackMetric({
+        name: 'TTFB',
+        value: navEntry.responseStart - navEntry.requestStart,
+        rating: navEntry.responseStart - navEntry.requestStart < 200 ? 'good' : 
+                navEntry.responseStart - navEntry.requestStart < 500 ? 'needs-improvement' : 'poor',
+      });
+    }
+  } catch (e) {
+    // Performance API not fully supported
+  }
+}
+
+// ============================================================================
+// Network Interceptor
+// ============================================================================
+
+export function initNetworkInterceptor(): void {
+  if (typeof window === 'undefined') return;
+
+  // Intercept fetch
+  const originalFetch = window.fetch;
+  window.fetch = async function(...args) {
+    const startTime = Date.now();
+    const url = typeof args[0] === 'string' ? args[0] : (args[0] as Request).url;
+    const method = typeof args[0] === 'string' ? (args[1]?.method || 'GET') : (args[0] as Request).method;
+    
+    try {
+      const response = await originalFetch.apply(this, args);
+      const clone = response.clone();
+      const size = (await clone.blob()).size;
+      
+      devtools.trackRequest({
+        id: Math.random().toString(36).slice(2),
+        url,
+        method,
+        status: response.status,
+        duration: Date.now() - startTime,
+        size,
+        timestamp: startTime,
+        type: url.includes('/_flexi/action') ? 'action' : 'fetch',
+      });
+      
+      return response;
+    } catch (error) {
+      devtools.trackRequest({
+        id: Math.random().toString(36).slice(2),
+        url,
+        method,
+        status: 0,
+        duration: Date.now() - startTime,
+        size: 0,
+        timestamp: startTime,
+        type: 'fetch',
+      });
+      throw error;
+    }
+  };
+}
+
+// ============================================================================
+// DevTools Overlay Component
+// ============================================================================
+
+export function DevToolsOverlay(): React.ReactElement | null {
+  const [state, setState] = React.useState<DevToolsState>({
+    enabled: true,
+    position: 'bottom-right',
+    expanded: false,
+    activeTab: 'routes',
+    theme: 'dark',
+  });
+
+  const [data, setData] = React.useState(devtools.getState());
+
+  React.useEffect(() => {
+    return devtools.subscribe(() => {
+      setData(devtools.getState());
+    });
+  }, []);
+
+  React.useEffect(() => {
+    initPerformanceMonitoring();
+    initNetworkInterceptor();
+  }, []);
+
+  // Keyboard shortcut (Ctrl+Shift+D)
+  React.useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.ctrlKey && e.shiftKey && e.key === 'D') {
+        setState(s => ({ ...s, expanded: !s.expanded }));
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, []);
+
+  if (!state.enabled) return null;
+
+  const positionStyles: Record<string, React.CSSProperties> = {
+    'bottom-right': { bottom: 16, right: 16 },
+    'bottom-left': { bottom: 16, left: 16 },
+    'top-right': { top: 16, right: 16 },
+    'top-left': { top: 16, left: 16 },
+  };
+
+  // Mini button when collapsed
+  if (!state.expanded) {
+    return React.createElement('button', {
+      onClick: () => setState(s => ({ ...s, expanded: true })),
+      style: {
+        position: 'fixed',
+        ...positionStyles[state.position],
+        zIndex: 99999,
+        width: 48,
+        height: 48,
+        borderRadius: 12,
+        background: 'linear-gradient(135deg, #00FF9C 0%, #00D68F 100%)',
+        border: 'none',
+        cursor: 'pointer',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        boxShadow: '0 4px 20px rgba(0, 255, 156, 0.3)',
+        transition: 'transform 0.2s',
+      },
+      onMouseEnter: (e: any) => e.target.style.transform = 'scale(1.1)',
+      onMouseLeave: (e: any) => e.target.style.transform = 'scale(1)',
+      title: 'FlexiReact DevTools (Ctrl+Shift+D)',
+    }, React.createElement('span', { style: { fontSize: 24 } }, '⚡'));
+  }
+
+  // Full panel
+  const tabs = [
+    { id: 'routes', label: '🗺️ Routes', count: data.routes.length },
+    { id: 'components', label: '🧩 Components', count: data.components.length },
+    { id: 'network', label: '🌐 Network', count: data.network.length },
+    { id: 'performance', label: '📊 Performance', count: data.performance.length },
+    { id: 'console', label: '📝 Console', count: data.logs.length },
+  ];
+
+  return React.createElement('div', {
+    style: {
+      position: 'fixed',
+      ...positionStyles[state.position],
+      zIndex: 99999,
+      width: 480,
+      maxHeight: '70vh',
+      background: '#0a0a0a',
+      border: '1px solid #222',
+      borderRadius: 12,
+      boxShadow: '0 8px 32px rgba(0, 0, 0, 0.5)',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      fontSize: 13,
+      color: '#fff',
+      overflow: 'hidden',
+    },
+  }, [
+    // Header
+    React.createElement('div', {
+      key: 'header',
+      style: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        padding: '12px 16px',
+        borderBottom: '1px solid #222',
+        background: '#111',
+      },
+    }, [
+      React.createElement('div', {
+        key: 'title',
+        style: { display: 'flex', alignItems: 'center', gap: 8 },
+      }, [
+        React.createElement('span', { key: 'icon' }, '⚡'),
+        React.createElement('span', { key: 'text', style: { fontWeight: 600 } }, 'FlexiReact DevTools'),
+      ]),
+      React.createElement('button', {
+        key: 'close',
+        onClick: () => setState(s => ({ ...s, expanded: false })),
+        style: {
+          background: 'none',
+          border: 'none',
+          color: '#666',
+          cursor: 'pointer',
+          fontSize: 18,
+        },
+      }, '×'),
+    ]),
+
+    // Tabs
+    React.createElement('div', {
+      key: 'tabs',
+      style: {
+        display: 'flex',
+        borderBottom: '1px solid #222',
+        background: '#0d0d0d',
+        overflowX: 'auto',
+      },
+    }, tabs.map(tab => 
+      React.createElement('button', {
+        key: tab.id,
+        onClick: () => setState(s => ({ ...s, activeTab: tab.id as any })),
+        style: {
+          padding: '10px 14px',
+          background: state.activeTab === tab.id ? '#1a1a1a' : 'transparent',
+          border: 'none',
+          borderBottom: state.activeTab === tab.id ? '2px solid #00FF9C' : '2px solid transparent',
+          color: state.activeTab === tab.id ? '#fff' : '#888',
+          cursor: 'pointer',
+          fontSize: 12,
+          whiteSpace: 'nowrap',
+        },
+      }, `${tab.label} (${tab.count})`)
+    )),
+
+    // Content
+    React.createElement('div', {
+      key: 'content',
+      style: {
+        padding: 16,
+        maxHeight: 'calc(70vh - 100px)',
+        overflowY: 'auto',
+      },
+    }, renderTabContent(state.activeTab, data)),
+  ]);
+}
+
+function renderTabContent(tab: string, data: ReturnType<typeof devtools.getState>): React.ReactElement {
+  switch (tab) {
+    case 'routes':
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8 } },
+        data.routes.length === 0 
+          ? React.createElement('div', { style: { color: '#666', textAlign: 'center', padding: 20 } }, 'No routes tracked yet')
+          : data.routes.map((route, i) => 
+              React.createElement('div', {
+                key: i,
+                style: {
+                  padding: 12,
+                  background: '#111',
+                  borderRadius: 8,
+                  border: '1px solid #222',
+                },
+              }, [
+                React.createElement('div', { key: 'path', style: { fontWeight: 600, color: '#00FF9C' } }, route.path),
+                React.createElement('div', { key: 'component', style: { fontSize: 11, color: '#888', marginTop: 4 } }, 
+                  `Component: ${route.component} • ${route.loadTime}ms`
+                ),
+              ])
+            )
+      );
+
+    case 'components':
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8 } },
+        data.components.length === 0
+          ? React.createElement('div', { style: { color: '#666', textAlign: 'center', padding: 20 } }, 'No components tracked')
+          : data.components.map((comp, i) =>
+              React.createElement('div', {
+                key: i,
+                style: {
+                  padding: 12,
+                  background: '#111',
+                  borderRadius: 8,
+                  border: '1px solid #222',
+                },
+              }, [
+                React.createElement('div', { 
+                  key: 'name',
+                  style: { display: 'flex', alignItems: 'center', gap: 8 } 
+                }, [
+                  React.createElement('span', { key: 'text', style: { fontWeight: 600 } }, comp.name),
+                  comp.isIsland && React.createElement('span', {
+                    key: 'island',
+                    style: {
+                      fontSize: 10,
+                      padding: '2px 6px',
+                      background: '#00FF9C20',
+                      color: '#00FF9C',
+                      borderRadius: 4,
+                    },
+                  }, 'Island'),
+                ]),
+                React.createElement('div', { key: 'info', style: { fontSize: 11, color: '#888', marginTop: 4 } },
+                  `Renders: ${comp.renderCount} • Last: ${new Date(comp.lastRenderTime).toLocaleTimeString()}`
+                ),
+              ])
+            )
+      );
+
+    case 'network':
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8 } },
+        data.network.length === 0
+          ? React.createElement('div', { style: { color: '#666', textAlign: 'center', padding: 20 } }, 'No requests yet')
+          : data.network.map((req, i) =>
+              React.createElement('div', {
+                key: i,
+                style: {
+                  padding: 12,
+                  background: '#111',
+                  borderRadius: 8,
+                  border: '1px solid #222',
+                },
+              }, [
+                React.createElement('div', { 
+                  key: 'url',
+                  style: { display: 'flex', alignItems: 'center', gap: 8 } 
+                }, [
+                  React.createElement('span', {
+                    key: 'method',
+                    style: {
+                      fontSize: 10,
+                      padding: '2px 6px',
+                      background: req.method === 'GET' ? '#3B82F620' : '#F59E0B20',
+                      color: req.method === 'GET' ? '#3B82F6' : '#F59E0B',
+                      borderRadius: 4,
+                      fontWeight: 600,
+                    },
+                  }, req.method),
+                  React.createElement('span', {
+                    key: 'status',
+                    style: {
+                      fontSize: 10,
+                      padding: '2px 6px',
+                      background: req.status >= 200 && req.status < 300 ? '#10B98120' : '#EF444420',
+                      color: req.status >= 200 && req.status < 300 ? '#10B981' : '#EF4444',
+                      borderRadius: 4,
+                    },
+                  }, req.status || 'ERR'),
+                  React.createElement('span', { 
+                    key: 'path',
+                    style: { fontSize: 12, color: '#fff', overflow: 'hidden', textOverflow: 'ellipsis' } 
+                  }, new URL(req.url, 'http://localhost').pathname),
+                ]),
+                React.createElement('div', { key: 'info', style: { fontSize: 11, color: '#888', marginTop: 4 } },
+                  `${req.duration}ms • ${formatBytes(req.size)}`
+                ),
+              ])
+            )
+      );
+
+    case 'performance':
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8 } },
+        data.performance.length === 0
+          ? React.createElement('div', { style: { color: '#666', textAlign: 'center', padding: 20 } }, 'Collecting metrics...')
+          : data.performance.map((metric, i) =>
+              React.createElement('div', {
+                key: i,
+                style: {
+                  padding: 12,
+                  background: '#111',
+                  borderRadius: 8,
+                  border: '1px solid #222',
+                  display: 'flex',
+                  justifyContent: 'space-between',
+                  alignItems: 'center',
+                },
+              }, [
+                React.createElement('span', { key: 'name', style: { fontWeight: 600 } }, metric.name),
+                React.createElement('div', { key: 'value', style: { display: 'flex', alignItems: 'center', gap: 8 } }, [
+                  React.createElement('span', { key: 'num' }, 
+                    metric.name === 'CLS' ? metric.value.toFixed(3) : `${Math.round(metric.value)}ms`
+                  ),
+                  React.createElement('span', {
+                    key: 'rating',
+                    style: {
+                      width: 8,
+                      height: 8,
+                      borderRadius: '50%',
+                      background: metric.rating === 'good' ? '#10B981' : 
+                                  metric.rating === 'needs-improvement' ? '#F59E0B' : '#EF4444',
+                    },
+                  }),
+                ]),
+              ])
+            )
+      );
+
+    case 'console':
+      return React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 4 } },
+        data.logs.length === 0
+          ? React.createElement('div', { style: { color: '#666', textAlign: 'center', padding: 20 } }, 'No logs yet')
+          : data.logs.map((log, i) =>
+              React.createElement('div', {
+                key: i,
+                style: {
+                  padding: '8px 12px',
+                  background: log.level === 'error' ? '#EF444410' : 
+                              log.level === 'warn' ? '#F59E0B10' : '#111',
+                  borderRadius: 6,
+                  fontSize: 12,
+                  fontFamily: 'monospace',
+                  color: log.level === 'error' ? '#EF4444' : 
+                         log.level === 'warn' ? '#F59E0B' : '#888',
+                },
+              }, [
+                React.createElement('span', { key: 'time', style: { color: '#444', marginRight: 8 } },
+                  new Date(log.timestamp).toLocaleTimeString()
+                ),
+                log.message,
+              ])
+            )
+      );
+
+    default:
+      return React.createElement('div', {}, 'Unknown tab');
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  devtools,
+  DevToolsOverlay,
+  initPerformanceMonitoring,
+  initNetworkInterceptor,
+};

package/core/index.ts

@@ -200,8 +200,16 @@ export {
 } from './helpers.js';
 export type { CookieOptions } from './helpers.js';
 
+// DevTools
+export {
+  devtools,
+  DevToolsOverlay,
+  initPerformanceMonitoring,
+  initNetworkInterceptor
+} from './devtools/index.js';
+
 // Version
-export const VERSION = '2.4.0';
+export const VERSION = '2.5.0';
 
 // Default export
 export default {

package/package.json

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