almostnode 0.2.6 → 0.2.8

package/src/frameworks/next-dev-server.ts

@@ -8,6 +8,31 @@ import { VirtualFS } from '../virtual-fs';
 import { Buffer } from '../shims/stream';
 import { simpleHash } from '../utils/hash';
 import { loadTailwindConfig } from './tailwind-config-loader';
+import { parseNextConfigValue } from './next-config-parser';
+import {
+  redirectNpmImports as _redirectNpmImports,
+  stripCssImports as _stripCssImports,
+  addReactRefresh as _addReactRefresh,
+  transformEsmToCjsSimple,
+  type CssModuleContext,
+} from './code-transforms';
+import {
+  NEXT_LINK_SHIM,
+  NEXT_ROUTER_SHIM,
+  NEXT_NAVIGATION_SHIM,
+  NEXT_HEAD_SHIM,
+  NEXT_IMAGE_SHIM,
+  NEXT_DYNAMIC_SHIM,
+  NEXT_SCRIPT_SHIM,
+  NEXT_FONT_GOOGLE_SHIM,
+  NEXT_FONT_LOCAL_SHIM,
+} from './next-shims';
+import {
+  type AppRoute,
+  generateAppRouterHtml as _generateAppRouterHtml,
+  generatePageHtml as _generatePageHtml,
+  serve404Page as _serve404Page,
+} from './next-html-generator';
 
 // Check if we're in a real browser environment (not jsdom or Node.js)
 const isBrowser = typeof window !== 'undefined' &&
@@ -80,922 +105,10 @@ export interface NextDevServerOptions extends DevServerOptions {
   env?: Record<string, string>;
   /** Asset prefix for static files (e.g., '/marketing'). Auto-detected from next.config if not specified. */
   assetPrefix?: string;
+  /** Base path for the app (e.g., '/docs'). Auto-detected from next.config if not specified. */
+  basePath?: string;
 }
 
-/**
- * Tailwind CSS CDN script for runtime JIT compilation
- */
-const TAILWIND_CDN_SCRIPT = `<script src="https://cdn.tailwindcss.com"></script>`;
-
-/**
- * CORS Proxy script - provides proxyFetch function in the iframe
- * Reads proxy URL from localStorage (set by parent window)
- */
-const CORS_PROXY_SCRIPT = `
-<script>
-  // CORS Proxy support for external API calls
-  window.__getCorsProxy = function() {
-    return localStorage.getItem('__corsProxyUrl') || null;
-  };
-
-  window.__setCorsProxy = function(url) {
-    if (url) {
-      localStorage.setItem('__corsProxyUrl', url);
-    } else {
-      localStorage.removeItem('__corsProxyUrl');
-    }
-  };
-
-  window.__proxyFetch = async function(url, options) {
-    const proxyUrl = window.__getCorsProxy();
-    if (proxyUrl) {
-      const proxiedUrl = proxyUrl + encodeURIComponent(url);
-      return fetch(proxiedUrl, options);
-    }
-    return fetch(url, options);
-  };
-</script>
-`;
-
-/**
- * React Refresh preamble - MUST run before React is loaded
- */
-const REACT_REFRESH_PREAMBLE = `
-<script type="module">
-// Block until React Refresh is loaded and initialized
-const RefreshRuntime = await import('https://esm.sh/react-refresh@0.14.0/runtime').then(m => m.default || m);
-
-RefreshRuntime.injectIntoGlobalHook(window);
-window.$RefreshRuntime$ = RefreshRuntime;
-window.$RefreshRegCount$ = 0;
-
-window.$RefreshReg$ = (type, id) => {
-  window.$RefreshRegCount$++;
-  RefreshRuntime.register(type, id);
-};
-
-window.$RefreshSig$ = () => (type) => type;
-
-console.log('[HMR] React Refresh initialized');
-</script>
-`;
-
-/**
- * HMR client script for Next.js
- */
-const HMR_CLIENT_SCRIPT = `
-<script type="module">
-(function() {
-  const hotModules = new Map();
-  const pendingUpdates = new Map();
-
-  window.__vite_hot_context__ = function createHotContext(ownerPath) {
-    if (hotModules.has(ownerPath)) {
-      return hotModules.get(ownerPath);
-    }
-
-    const hot = {
-      data: {},
-      accept(callback) {
-        hot._acceptCallback = callback;
-      },
-      dispose(callback) {
-        hot._disposeCallback = callback;
-      },
-      invalidate() {
-        location.reload();
-      },
-      prune(callback) {
-        hot._pruneCallback = callback;
-      },
-      on(event, cb) {},
-      off(event, cb) {},
-      send(event, data) {},
-      _acceptCallback: null,
-      _disposeCallback: null,
-      _pruneCallback: null,
-    };
-
-    hotModules.set(ownerPath, hot);
-    return hot;
-  };
-
-  // Listen for HMR updates via postMessage (works with sandboxed iframes)
-  window.addEventListener('message', async (event) => {
-    // Filter for HMR messages only
-    if (!event.data || event.data.channel !== 'next-hmr') return;
-    const { type, path, timestamp } = event.data;
-
-    if (type === 'update') {
-      console.log('[HMR] Update:', path);
-
-      if (path.endsWith('.css')) {
-        const links = document.querySelectorAll('link[rel="stylesheet"]');
-        links.forEach(link => {
-          const href = link.getAttribute('href');
-          if (href && href.includes(path.replace(/^\\//, ''))) {
-            link.href = href.split('?')[0] + '?t=' + timestamp;
-          }
-        });
-
-        const styles = document.querySelectorAll('style[data-next-dev-id]');
-        styles.forEach(style => {
-          const id = style.getAttribute('data-next-dev-id');
-          if (id && id.includes(path.replace(/^\\//, ''))) {
-            import(path + '?t=' + timestamp).catch(() => {});
-          }
-        });
-      } else if (path.match(/\\.(jsx?|tsx?)$/)) {
-        await handleJSUpdate(path, timestamp);
-      }
-    } else if (type === 'full-reload') {
-      console.log('[HMR] Full reload');
-      location.reload();
-    }
-  });
-
-  async function handleJSUpdate(path, timestamp) {
-    const normalizedPath = path.startsWith('/') ? path : '/' + path;
-    const hot = hotModules.get(normalizedPath);
-
-    try {
-      if (hot && hot._disposeCallback) {
-        hot._disposeCallback(hot.data);
-      }
-
-      if (window.$RefreshRuntime$) {
-        pendingUpdates.set(normalizedPath, timestamp);
-
-        if (pendingUpdates.size === 1) {
-          setTimeout(async () => {
-            try {
-              for (const [modulePath, ts] of pendingUpdates) {
-                const moduleUrl = '.' + modulePath + '?t=' + ts;
-                await import(moduleUrl);
-              }
-
-              window.$RefreshRuntime$.performReactRefresh();
-              console.log('[HMR] Updated', pendingUpdates.size, 'module(s)');
-
-              pendingUpdates.clear();
-            } catch (error) {
-              console.error('[HMR] Failed to apply update:', error);
-              pendingUpdates.clear();
-              location.reload();
-            }
-          }, 30);
-        }
-      } else {
-        console.log('[HMR] React Refresh not available, reloading page');
-        location.reload();
-      }
-    } catch (error) {
-      console.error('[HMR] Update failed:', error);
-      location.reload();
-    }
-  }
-
-  console.log('[HMR] Next.js client ready');
-})();
-</script>
-`;
-
-/**
- * Next.js Link shim code
- */
-const NEXT_LINK_SHIM = `
-import React from 'react';
-
-const getVirtualBasePath = () => {
-  const match = window.location.pathname.match(/^\\/__virtual__\\/\\d+(?:\\/|$)/);
-  if (!match) return '';
-  return match[0].endsWith('/') ? match[0] : match[0] + '/';
-};
-
-const applyVirtualBase = (url) => {
-  if (typeof url !== 'string') return url;
-  if (!url || url.startsWith('#') || url.startsWith('?')) return url;
-  if (/^(https?:)?\\/\\//.test(url)) return url;
-
-  const base = getVirtualBasePath();
-  if (!base) return url;
-  if (url.startsWith(base)) return url;
-  if (url.startsWith('/')) return base + url.slice(1);
-  return base + url;
-};
-
-export default function Link({ href, children, ...props }) {
-  const handleClick = (e) => {
-    console.log('[Link] Click handler called, href:', href);
-
-    if (props.onClick) {
-      props.onClick(e);
-    }
-
-    // Allow cmd/ctrl click to open in new tab
-    if (e.metaKey || e.ctrlKey) {
-      console.log('[Link] Meta/Ctrl key pressed, allowing default behavior');
-      return;
-    }
-
-    if (typeof href !== 'string' || !href || href.startsWith('#') || href.startsWith('?')) {
-      console.log('[Link] Skipping navigation for href:', href);
-      return;
-    }
-
-    if (/^(https?:)?\\/\\//.test(href)) {
-      console.log('[Link] External URL, allowing default behavior:', href);
-      return;
-    }
-
-    e.preventDefault();
-    const resolvedHref = applyVirtualBase(href);
-    console.log('[Link] Navigating to:', resolvedHref);
-    window.history.pushState({}, '', resolvedHref);
-    window.dispatchEvent(new PopStateEvent('popstate'));
-  };
-
-  return React.createElement('a', { href, onClick: handleClick, ...props }, children);
-}
-
-export { Link };
-`;
-
-/**
- * Next.js Router shim code
- */
-const NEXT_ROUTER_SHIM = `
-import React, { useState, useEffect, createContext, useContext } from 'react';
-
-const RouterContext = createContext(null);
-
-const getVirtualBasePath = () => {
-  const match = window.location.pathname.match(/^\\/__virtual__\\/\\d+(?:\\/|$)/);
-  if (!match) return '';
-  return match[0].endsWith('/') ? match[0] : match[0] + '/';
-};
-
-const applyVirtualBase = (url) => {
-  if (typeof url !== 'string') return url;
-  if (!url || url.startsWith('#') || url.startsWith('?')) return url;
-  if (/^(https?:)?\\/\\//.test(url)) return url;
-
-  const base = getVirtualBasePath();
-  if (!base) return url;
-  if (url.startsWith(base)) return url;
-  if (url.startsWith('/')) return base + url.slice(1);
-  return base + url;
-};
-
-const stripVirtualBase = (pathname) => {
-  const match = pathname.match(/^\\/__virtual__\\/\\d+(?:\\/|$)/);
-  if (!match) return pathname;
-  return '/' + pathname.slice(match[0].length);
-};
-
-export function useRouter() {
-  const [pathname, setPathname] = useState(
-    typeof window !== 'undefined' ? stripVirtualBase(window.location.pathname) : '/'
-  );
-  const [query, setQuery] = useState({});
-
-  useEffect(() => {
-    const updateRoute = () => {
-      setPathname(stripVirtualBase(window.location.pathname));
-      setQuery(Object.fromEntries(new URLSearchParams(window.location.search)));
-    };
-
-    window.addEventListener('popstate', updateRoute);
-    updateRoute();
-
-    return () => window.removeEventListener('popstate', updateRoute);
-  }, []);
-
-  return {
-    pathname,
-    query,
-    asPath: pathname + window.location.search,
-    push: (url, as, options) => {
-      if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-        window.location.href = url;
-        return Promise.resolve(true);
-      }
-      const resolvedUrl = applyVirtualBase(url);
-      window.history.pushState({}, '', resolvedUrl);
-      window.dispatchEvent(new PopStateEvent('popstate'));
-      return Promise.resolve(true);
-    },
-    replace: (url, as, options) => {
-      if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-        window.location.href = url;
-        return Promise.resolve(true);
-      }
-      const resolvedUrl = applyVirtualBase(url);
-      window.history.replaceState({}, '', resolvedUrl);
-      window.dispatchEvent(new PopStateEvent('popstate'));
-      return Promise.resolve(true);
-    },
-    prefetch: () => Promise.resolve(),
-    back: () => window.history.back(),
-    forward: () => window.history.forward(),
-    reload: () => window.location.reload(),
-    events: {
-      on: () => {},
-      off: () => {},
-      emit: () => {},
-    },
-    isFallback: false,
-    isReady: true,
-    isPreview: false,
-  };
-}
-
-export const Router = {
-  events: {
-    on: () => {},
-    off: () => {},
-    emit: () => {},
-  },
-  push: (url) => {
-    if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-      window.location.href = url;
-      return Promise.resolve(true);
-    }
-    const resolvedUrl = applyVirtualBase(url);
-    window.history.pushState({}, '', resolvedUrl);
-    window.dispatchEvent(new PopStateEvent('popstate'));
-    return Promise.resolve(true);
-  },
-  replace: (url) => {
-    if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-      window.location.href = url;
-      return Promise.resolve(true);
-    }
-    const resolvedUrl = applyVirtualBase(url);
-    window.history.replaceState({}, '', resolvedUrl);
-    window.dispatchEvent(new PopStateEvent('popstate'));
-    return Promise.resolve(true);
-  },
-};
-
-export default { useRouter, Router };
-`;
-
-/**
- * Next.js Navigation shim code (App Router)
- *
- * This shim provides App Router-specific navigation hooks from 'next/navigation'.
- * These are DIFFERENT from the Pages Router hooks in 'next/router':
- *
- * Pages Router (next/router):
- *   - useRouter() returns { pathname, query, push, replace, events, ... }
- *   - Has router.events for route change subscriptions
- *   - query object contains URL params
- *
- * App Router (next/navigation):
- *   - useRouter() returns { push, replace, back, forward, refresh, prefetch }
- *   - usePathname() for current path
- *   - useSearchParams() for URL search params
- *   - useParams() for dynamic route segments
- *   - No events - use useEffect with pathname/searchParams instead
- *
- * @see https://nextjs.org/docs/app/api-reference/functions/use-router
- */
-const NEXT_NAVIGATION_SHIM = `
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-
-const getVirtualBasePath = () => {
-  const match = window.location.pathname.match(/^\\/__virtual__\\/\\d+(?:\\/|$)/);
-  if (!match) return '';
-  return match[0].endsWith('/') ? match[0] : match[0] + '/';
-};
-
-const applyVirtualBase = (url) => {
-  if (typeof url !== 'string') return url;
-  if (!url || url.startsWith('#') || url.startsWith('?')) return url;
-  if (/^(https?:)?\\/\\//.test(url)) return url;
-
-  const base = getVirtualBasePath();
-  if (!base) return url;
-  if (url.startsWith(base)) return url;
-  if (url.startsWith('/')) return base + url.slice(1);
-  return base + url;
-};
-
-const stripVirtualBase = (pathname) => {
-  const match = pathname.match(/^\\/__virtual__\\/\\d+(?:\\/|$)/);
-  if (!match) return pathname;
-  return '/' + pathname.slice(match[0].length);
-};
-
-/**
- * App Router's useRouter hook
- * Returns navigation methods only (no pathname, no query)
- * Use usePathname() and useSearchParams() for URL info
- */
-export function useRouter() {
-  const push = useCallback((url, options) => {
-    if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-      window.location.href = url;
-      return;
-    }
-    const resolvedUrl = applyVirtualBase(url);
-    window.history.pushState({}, '', resolvedUrl);
-    window.dispatchEvent(new PopStateEvent('popstate'));
-  }, []);
-
-  const replace = useCallback((url, options) => {
-    if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-      window.location.href = url;
-      return;
-    }
-    const resolvedUrl = applyVirtualBase(url);
-    window.history.replaceState({}, '', resolvedUrl);
-    window.dispatchEvent(new PopStateEvent('popstate'));
-  }, []);
-
-  const back = useCallback(() => window.history.back(), []);
-  const forward = useCallback(() => window.history.forward(), []);
-  const refresh = useCallback(() => window.location.reload(), []);
-  const prefetch = useCallback(() => Promise.resolve(), []);
-
-  return useMemo(() => ({
-    push,
-    replace,
-    back,
-    forward,
-    refresh,
-    prefetch,
-  }), [push, replace, back, forward, refresh, prefetch]);
-}
-
-/**
- * usePathname - Returns the current URL pathname
- * Reactively updates when navigation occurs
- * @example const pathname = usePathname(); // '/dashboard/settings'
- */
-export function usePathname() {
-  const [pathname, setPathname] = useState(
-    typeof window !== 'undefined' ? stripVirtualBase(window.location.pathname) : '/'
-  );
-
-  useEffect(() => {
-    const handler = () => setPathname(stripVirtualBase(window.location.pathname));
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  }, []);
-
-  return pathname;
-}
-
-/**
- * useSearchParams - Returns the current URL search parameters
- * @example const searchParams = useSearchParams();
- *          const query = searchParams.get('q'); // '?q=hello' -> 'hello'
- */
-export function useSearchParams() {
-  const [searchParams, setSearchParams] = useState(() => {
-    if (typeof window === 'undefined') return new URLSearchParams();
-    return new URLSearchParams(window.location.search);
-  });
-
-  useEffect(() => {
-    const handler = () => {
-      setSearchParams(new URLSearchParams(window.location.search));
-    };
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  }, []);
-
-  return searchParams;
-}
-
-/**
- * useParams - Returns dynamic route parameters
- * For route /users/[id]/page.jsx with URL /users/123:
- * @example const { id } = useParams(); // { id: '123' }
- *
- * NOTE: This simplified implementation returns empty object.
- * Full implementation would need route pattern matching.
- */
-export function useParams() {
-  // In a real implementation, this would parse the current route
-  // against the route pattern to extract params
-  // For now, return empty object - works for basic cases
-  return {};
-}
-
-/**
- * useSelectedLayoutSegment - Returns the active child segment one level below
- * Useful for styling active nav items in layouts
- * @example For /dashboard/settings, returns 'settings' in dashboard layout
- */
-export function useSelectedLayoutSegment() {
-  const pathname = usePathname();
-  const segments = pathname.split('/').filter(Boolean);
-  return segments[0] || null;
-}
-
-/**
- * useSelectedLayoutSegments - Returns all active child segments
- * @example For /dashboard/settings/profile, returns ['dashboard', 'settings', 'profile']
- */
-export function useSelectedLayoutSegments() {
-  const pathname = usePathname();
-  return pathname.split('/').filter(Boolean);
-}
-
-/**
- * redirect - Programmatic redirect (typically used in Server Components)
- * In this browser implementation, performs immediate navigation
- */
-export function redirect(url) {
-  if (typeof url === 'string' && /^(https?:)?\\/\\//.test(url)) {
-    window.location.href = url;
-    return;
-  }
-  window.location.href = applyVirtualBase(url);
-}
-
-/**
- * notFound - Trigger the not-found UI
- * In this browser implementation, throws an error
- */
-export function notFound() {
-  throw new Error('NEXT_NOT_FOUND');
-}
-
-// Re-export Link for convenience (can import from next/navigation or next/link)
-export { default as Link } from 'next/link';
-`;
-
-/**
- * Next.js Head shim code
- */
-const NEXT_HEAD_SHIM = `
-import React, { useEffect } from 'react';
-
-export default function Head({ children }) {
-  useEffect(() => {
-    // Process children and update document.head
-    React.Children.forEach(children, (child) => {
-      if (!React.isValidElement(child)) return;
-
-      const { type, props } = child;
-
-      if (type === 'title' && props.children) {
-        document.title = Array.isArray(props.children)
-          ? props.children.join('')
-          : props.children;
-      } else if (type === 'meta') {
-        const existingMeta = props.name
-          ? document.querySelector(\`meta[name="\${props.name}"]\`)
-          : props.property
-            ? document.querySelector(\`meta[property="\${props.property}"]\`)
-            : null;
-
-        if (existingMeta) {
-          Object.keys(props).forEach(key => {
-            existingMeta.setAttribute(key, props[key]);
-          });
-        } else {
-          const meta = document.createElement('meta');
-          Object.keys(props).forEach(key => {
-            meta.setAttribute(key, props[key]);
-          });
-          document.head.appendChild(meta);
-        }
-      } else if (type === 'link') {
-        const link = document.createElement('link');
-        Object.keys(props).forEach(key => {
-          link.setAttribute(key, props[key]);
-        });
-        document.head.appendChild(link);
-      }
-    });
-  }, [children]);
-
-  return null;
-}
-`;
-
-/**
- * Next.js Image shim code
- * Provides a simple img-based implementation of next/image
- */
-const NEXT_IMAGE_SHIM = `
-import React from 'react';
-
-function Image({
-  src,
-  alt = '',
-  width,
-  height,
-  fill,
-  loader,
-  quality = 75,
-  priority,
-  loading,
-  placeholder,
-  blurDataURL,
-  unoptimized,
-  onLoad,
-  onError,
-  style,
-  className,
-  sizes,
-  ...rest
-}) {
-  // Handle src - could be string or StaticImageData object
-  const imageSrc = typeof src === 'object' ? src.src : src;
-
-  // Build style object
-  const imgStyle = { ...style };
-  if (fill) {
-    imgStyle.position = 'absolute';
-    imgStyle.width = '100%';
-    imgStyle.height = '100%';
-    imgStyle.objectFit = imgStyle.objectFit || 'cover';
-    imgStyle.inset = '0';
-  }
-
-  return React.createElement('img', {
-    src: imageSrc,
-    alt,
-    width: fill ? undefined : width,
-    height: fill ? undefined : height,
-    loading: priority ? 'eager' : (loading || 'lazy'),
-    decoding: 'async',
-    style: imgStyle,
-    className,
-    onLoad,
-    onError,
-    ...rest
-  });
-}
-
-export default Image;
-export { Image };
-`;
-
-/**
- * next/dynamic shim - Dynamic imports with loading states
- */
-const NEXT_DYNAMIC_SHIM = `
-import React from 'react';
-
-function dynamic(importFn, options = {}) {
-  const {
-    loading: LoadingComponent,
-    ssr = true,
-  } = options;
-
-  // Create a lazy component
-  const LazyComponent = React.lazy(importFn);
-
-  // Wrapper component that handles loading state
-  function DynamicComponent(props) {
-    const fallback = LoadingComponent
-      ? React.createElement(LoadingComponent, { isLoading: true })
-      : null;
-
-    return React.createElement(
-      React.Suspense,
-      { fallback },
-      React.createElement(LazyComponent, props)
-    );
-  }
-
-  return DynamicComponent;
-}
-
-export default dynamic;
-export { dynamic };
-`;
-
-/**
- * next/script shim - Loads external scripts
- */
-const NEXT_SCRIPT_SHIM = `
-import React from 'react';
-
-function Script({
-  src,
-  strategy = 'afterInteractive',
-  onLoad,
-  onReady,
-  onError,
-  children,
-  dangerouslySetInnerHTML,
-  ...rest
-}) {
-  React.useEffect(function() {
-    if (!src && !children && !dangerouslySetInnerHTML) return;
-
-    var script = document.createElement('script');
-
-    if (src) {
-      script.src = src;
-      script.async = strategy !== 'beforeInteractive';
-    }
-
-    Object.keys(rest).forEach(function(key) {
-      script.setAttribute(key, rest[key]);
-    });
-
-    if (children) {
-      script.textContent = children;
-    } else if (dangerouslySetInnerHTML && dangerouslySetInnerHTML.__html) {
-      script.textContent = dangerouslySetInnerHTML.__html;
-    }
-
-    script.onload = function() {
-      if (onLoad) onLoad();
-      if (onReady) onReady();
-    };
-    script.onerror = onError;
-
-    document.head.appendChild(script);
-
-    return function() {
-      if (script.parentNode) {
-        script.parentNode.removeChild(script);
-      }
-    };
-  }, [src]);
-
-  return null;
-}
-
-export default Script;
-export { Script };
-`;
-
-/**
- * next/font/google shim - Loads Google Fonts via CDN
- * Uses a Proxy to dynamically handle ANY Google Font without hardcoding
- */
-const NEXT_FONT_GOOGLE_SHIM = `
-// Track loaded fonts to avoid duplicate style injections
-const loadedFonts = new Set();
-
-/**
- * Convert font function name to Google Fonts family name
- * Examples:
- *   DM_Sans -> DM Sans
- *   Open_Sans -> Open Sans
- *   Fraunces -> Fraunces
- */
-function toFontFamily(fontName) {
-  return fontName.replace(/_/g, ' ');
-}
-
-/**
- * Inject font CSS into document
- * - Adds preconnect links for faster font loading
- * - Loads the font from Google Fonts CDN
- * - Creates a CSS class that sets the CSS variable
- */
-function injectFontCSS(fontFamily, variableName, weight, style) {
-  const fontKey = fontFamily + '-' + (variableName || 'default');
-  if (loadedFonts.has(fontKey)) {
-    return;
-  }
-  loadedFonts.add(fontKey);
-
-  if (typeof document === 'undefined') {
-    return;
-  }
-
-  // Add preconnect links for faster loading (only once)
-  if (!document.querySelector('link[href="https://fonts.googleapis.com"]')) {
-    const preconnect1 = document.createElement('link');
-    preconnect1.rel = 'preconnect';
-    preconnect1.href = 'https://fonts.googleapis.com';
-    document.head.appendChild(preconnect1);
-
-    const preconnect2 = document.createElement('link');
-    preconnect2.rel = 'preconnect';
-    preconnect2.href = 'https://fonts.gstatic.com';
-    preconnect2.crossOrigin = 'anonymous';
-    document.head.appendChild(preconnect2);
-  }
-
-  // Build Google Fonts URL
-  const escapedFamily = fontFamily.replace(/ /g, '+');
-
-  // Build axis list based on options
-  let axisList = '';
-  const axes = [];
-
-  // Handle italic style
-  if (style === 'italic') {
-    axes.push('ital');
-  }
-
-  // Handle weight - use specific weight or variable range
-  if (weight && weight !== '400' && !Array.isArray(weight)) {
-    // Specific weight requested
-    axes.push('wght');
-    if (style === 'italic') {
-      axisList = ':ital,wght@1,' + weight;
-    } else {
-      axisList = ':wght@' + weight;
-    }
-  } else if (Array.isArray(weight)) {
-    // Multiple weights
-    axes.push('wght');
-    axisList = ':wght@' + weight.join(';');
-  } else {
-    // Default: request common weights for flexibility
-    axisList = ':wght@400;500;600;700';
-  }
-
-  const fontUrl = 'https://fonts.googleapis.com/css2?family=' +
-    escapedFamily + axisList + '&display=swap';
-
-  // Add link element for Google Fonts (if not already present)
-  if (!document.querySelector('link[href*="family=' + escapedFamily + '"]')) {
-    const link = document.createElement('link');
-    link.rel = 'stylesheet';
-    link.href = fontUrl;
-    document.head.appendChild(link);
-  }
-
-  // Create style element for CSS variable at :root level (globally available)
-  // This makes the variable work without needing to apply the class to body
-  if (variableName) {
-    const styleEl = document.createElement('style');
-    styleEl.setAttribute('data-font-var', variableName);
-    styleEl.textContent = ':root { ' + variableName + ': "' + fontFamily + '", ' + (fontFamily.includes('Serif') ? 'serif' : 'sans-serif') + '; }';
-    document.head.appendChild(styleEl);
-  }
-}
-
-/**
- * Create a font loader function for a specific font
- */
-function createFontLoader(fontName) {
-  const fontFamily = toFontFamily(fontName);
-
-  return function(options = {}) {
-    const {
-      weight,
-      style = 'normal',
-      subsets = ['latin'],
-      variable,
-      display = 'swap',
-      preload = true,
-      fallback = ['sans-serif'],
-      adjustFontFallback = true
-    } = options;
-
-    // Inject the font CSS
-    injectFontCSS(fontFamily, variable, weight, style);
-
-    // Generate class name from variable (--font-inter -> __font-inter)
-    const className = variable
-      ? variable.replace('--', '__')
-      : '__font-' + fontName.toLowerCase().replace(/_/g, '-');
-
-    return {
-      className,
-      variable: className,
-      style: {
-        fontFamily: '"' + fontFamily + '", ' + fallback.join(', ')
-      }
-    };
-  };
-}
-
-/**
- * Use a Proxy to dynamically create font loaders for ANY font name
- * This allows: import { AnyGoogleFont } from "next/font/google"
- */
-const fontProxy = new Proxy({}, {
-  get(target, prop) {
-    // Handle special properties
-    if (prop === '__esModule') return true;
-    if (prop === 'default') return fontProxy;
-    if (typeof prop !== 'string') return undefined;
-
-    // Create a font loader for this font name
-    return createFontLoader(prop);
-  }
-});
-
-// Export the proxy as both default and named exports
-export default fontProxy;
-
-// Re-export through proxy for named imports
-export const {
-  Fraunces, Inter, DM_Sans, DM_Serif_Text, Roboto, Open_Sans, Lato,
-  Montserrat, Poppins, Playfair_Display, Merriweather, Raleway, Nunito,
-  Ubuntu, Oswald, Quicksand, Work_Sans, Fira_Sans, Barlow, Mulish, Rubik,
-  Noto_Sans, Manrope, Space_Grotesk, Geist, Geist_Mono
-} = fontProxy;
-`;
-
 /**
  * NextDevServer - A lightweight Next.js-compatible development server
  *
@@ -1056,6 +169,9 @@ export class NextDevServer extends DevServer {
   /** Asset prefix for static files (e.g., '/marketing') */
   private assetPrefix: string = '';
 
+  /** Base path for the app (e.g., '/docs') */
+  private basePath: string = '';
+
   constructor(vfs: VirtualFS, options: NextDevServerOptions) {
     super(vfs, options);
     this.options = options;
@@ -1077,6 +193,9 @@ export class NextDevServer extends DevServer {
 
     // Load assetPrefix from options or auto-detect from next.config
     this.loadAssetPrefix(options.assetPrefix);
+
+    // Load basePath from options or auto-detect from next.config
+    this.loadBasePath(options.basePath);
   }
 
   /**
@@ -1114,50 +233,45 @@ export class NextDevServer extends DevServer {
   }
 
   /**
-   * Load assetPrefix from options or auto-detect from next.config.ts/js
-   * The assetPrefix is used to prefix static asset URLs (e.g., '/marketing')
+   * Load a string config value from options or auto-detect from next.config.ts/js
    */
-  private loadAssetPrefix(optionValue?: string): void {
-    // If explicitly provided in options, use it
+  private loadConfigStringValue(key: string, optionValue?: string): string {
     if (optionValue !== undefined) {
-      // Normalize: ensure it starts with / and doesn't end with /
-      this.assetPrefix = optionValue.startsWith('/') ? optionValue : `/${optionValue}`;
-      if (this.assetPrefix.endsWith('/')) {
-        this.assetPrefix = this.assetPrefix.slice(0, -1);
-      }
-      return;
+      let val = optionValue.startsWith('/') ? optionValue : `/${optionValue}`;
+      if (val.endsWith('/')) val = val.slice(0, -1);
+      return val;
     }
 
-    // Try to auto-detect from next.config.ts or next.config.js
     try {
-      const configFiles = ['/next.config.ts', '/next.config.js', '/next.config.mjs'];
-
-      for (const configPath of configFiles) {
-        if (!this.vfs.existsSync(configPath)) {
-          continue;
-        }
-
-        const content = this.vfs.readFileSync(configPath, 'utf-8');
-
-        // Extract assetPrefix from config using regex
-        // Matches: assetPrefix: "/marketing" or assetPrefix: '/marketing'
-        const match = content.match(/assetPrefix\s*:\s*["']([^"']+)["']/);
-        if (match) {
-          let prefix = match[1];
-          // Normalize: ensure it starts with / and doesn't end with /
-          if (!prefix.startsWith('/')) {
-            prefix = `/${prefix}`;
-          }
-          if (prefix.endsWith('/')) {
-            prefix = prefix.slice(0, -1);
-          }
-          this.assetPrefix = prefix;
-          return;
+      const configFiles: { path: string; isTs: boolean }[] = [
+        { path: '/next.config.ts', isTs: true },
+        { path: '/next.config.js', isTs: false },
+        { path: '/next.config.mjs', isTs: false },
+      ];
+
+      for (const { path, isTs } of configFiles) {
+        if (!this.vfs.existsSync(path)) continue;
+        const content = this.vfs.readFileSync(path, 'utf-8');
+        const value = parseNextConfigValue(content, key, isTs);
+        if (value) {
+          let normalized = value.startsWith('/') ? value : `/${value}`;
+          if (normalized.endsWith('/')) normalized = normalized.slice(0, -1);
+          return normalized;
         }
       }
-    } catch (e) {
+    } catch {
       // Silently ignore config parse errors
     }
+
+    return '';
+  }
+
+  private loadAssetPrefix(optionValue?: string): void {
+    this.assetPrefix = this.loadConfigStringValue('assetPrefix', optionValue);
+  }
+
+  private loadBasePath(optionValue?: string): void {
+    this.basePath = this.loadConfigStringValue('basePath', optionValue);
   }
 
   /**
@@ -1246,6 +360,8 @@ export class NextDevServer extends DevServer {
   window.process = window.process || {};
   window.process.env = window.process.env || {};
   Object.assign(window.process.env, ${JSON.stringify(publicEnvVars)});
+  // Next.js config values
+  window.__NEXT_BASE_PATH__ = ${JSON.stringify(this.basePath)};
 </script>`;
   }
 
@@ -1285,11 +401,30 @@ export class NextDevServer extends DevServer {
       // Check if /app directory exists and has a page file
       if (!this.exists(this.appDir)) return false;
 
-      // Check for root page
       const extensions = ['.jsx', '.tsx', '.js', '.ts'];
+
+      // Check for root page directly
       for (const ext of extensions) {
         if (this.exists(`${this.appDir}/page${ext}`)) return true;
       }
+
+      // Check for root page inside route groups (e.g., /app/(main)/page.tsx)
+      try {
+        const entries = this.vfs.readdirSync(this.appDir);
+        for (const entry of entries) {
+          if (/^\([^)]+\)$/.test(entry) && this.isDirectory(`${this.appDir}/${entry}`)) {
+            for (const ext of extensions) {
+              if (this.exists(`${this.appDir}/${entry}/page${ext}`)) return true;
+            }
+          }
+        }
+      } catch { /* ignore */ }
+
+      // Also check for any layout.tsx which indicates App Router usage
+      for (const ext of extensions) {
+        if (this.exists(`${this.appDir}/layout${ext}`)) return true;
+      }
+
       return false;
     } catch {
       return false;
@@ -1329,6 +464,14 @@ export class NextDevServer extends DevServer {
       }
     }
 
+    // Strip basePath if present (e.g., /docs/about -> /about)
+    if (this.basePath && pathname.startsWith(this.basePath)) {
+      const rest = pathname.slice(this.basePath.length);
+      if (rest === '' || rest.startsWith('/')) {
+        pathname = rest || '/';
+      }
+    }
+
     // Serve Next.js shims
     if (pathname.startsWith('/_next/shims/')) {
       return this.serveNextShim(pathname);
@@ -1354,7 +497,15 @@ export class NextDevServer extends DevServer {
       return this.serveStaticAsset(pathname);
     }
 
-    // API routes: /api/*
+    // App Router API routes (route.ts/route.js) - check before Pages Router API routes
+    if (this.useAppRouter) {
+      const appRouteFile = this.resolveAppRouteHandler(pathname);
+      if (appRouteFile) {
+        return this.handleAppRouteHandler(method, pathname, headers, body, appRouteFile, urlObj.search);
+      }
+    }
+
+    // Pages Router API routes: /api/*
     if (pathname.startsWith('/api/')) {
       return this.handleApiRoute(method, pathname, headers, body);
     }
@@ -1421,6 +572,9 @@ export class NextDevServer extends DevServer {
       case 'font/google':
         code = NEXT_FONT_GOOGLE_SHIM;
         break;
+      case 'font/local':
+        code = NEXT_FONT_LOCAL_SHIM;
+        break;
       default:
         return this.notFound(pathname);
     }
@@ -1503,12 +657,18 @@ export class NextDevServer extends DevServer {
    * Maps /_next/app/app/about/page.js → /app/about/page.tsx (transformed)
    */
   private async serveAppComponent(pathname: string): Promise<ResponseData> {
-    // Extract the file path from /_next/app/app/about/page.js → /app/about/page
-    const filePath = pathname
-      .replace('/_next/app', '')
-      .replace(/\.js$/, '');
+    // Extract the file path from /_next/app prefix
+    const rawFilePath = pathname.replace('/_next/app', '');
+
+    // First, try the path as-is (handles imports with explicit extensions like .tsx/.ts)
+    if (this.exists(rawFilePath) && !this.isDirectory(rawFilePath)) {
+      return this.transformAndServe(rawFilePath, rawFilePath);
+    }
+
+    // Strip .js extension and try different extensions
+    // e.g. /_next/app/app/about/page.js → /app/about/page → /app/about/page.tsx
+    const filePath = rawFilePath.replace(/\.js$/, '');
 
-    // Try different extensions
     const extensions = ['.tsx', '.jsx', '.ts', '.js'];
     for (const ext of extensions) {
       const fullPath = filePath + ext;
@@ -1539,32 +699,264 @@ export class NextDevServer extends DevServer {
         headers: { 'Content-Type': 'application/json; charset=utf-8' },
         body: Buffer.from(JSON.stringify({ error: 'API route not found' })),
       };
-    }
+    }
+
+    try {
+      // Read and transform the API handler to CJS for eval execution
+      const code = this.vfs.readFileSync(apiFile, 'utf8');
+      const transformed = await this.transformApiHandler(code, apiFile);
+
+      // Create mock req/res objects
+      const req = this.createMockRequest(method, pathname, headers, body);
+      const res = this.createMockResponse();
+
+      // Execute the handler
+      await this.executeApiHandler(transformed, req, res);
+
+      // Wait for async handlers (like those using https.get with callbacks)
+      // with a reasonable timeout
+      if (!res.isEnded()) {
+        const timeout = new Promise<void>((_, reject) => {
+          setTimeout(() => reject(new Error('API handler timeout')), 30000);
+        });
+        await Promise.race([res.waitForEnd(), timeout]);
+      }
+
+      return res.toResponse();
+    } catch (error) {
+      console.error('[NextDevServer] API error:', error);
+      return {
+        statusCode: 500,
+        statusMessage: 'Internal Server Error',
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+        body: Buffer.from(JSON.stringify({
+          error: error instanceof Error ? error.message : 'Internal Server Error'
+        })),
+      };
+    }
+  }
+
+  /**
+   * Resolve an App Router route handler (route.ts/route.js)
+   * Returns the file path if found, null otherwise
+   */
+  private resolveAppRouteHandler(pathname: string): string | null {
+    const extensions = ['.ts', '.js', '.tsx', '.jsx'];
+
+    // Build the directory path in the app dir
+    const segments = pathname === '/' ? [] : pathname.split('/').filter(Boolean);
+    let dirPath = this.appDir;
+
+    for (const segment of segments) {
+      dirPath = `${dirPath}/${segment}`;
+    }
+
+    // Check for route file
+    for (const ext of extensions) {
+      const routePath = `${dirPath}/route${ext}`;
+      if (this.exists(routePath)) {
+        return routePath;
+      }
+    }
+
+    // Try dynamic route resolution with route groups
+    return this.resolveAppRouteHandlerDynamic(segments);
+  }
+
+  /**
+   * Resolve dynamic App Router route handlers with route group support
+   */
+  private resolveAppRouteHandlerDynamic(segments: string[]): string | null {
+    const extensions = ['.ts', '.js', '.tsx', '.jsx'];
+
+    const tryPath = (dirPath: string, remainingSegments: string[]): string | null => {
+      if (remainingSegments.length === 0) {
+        for (const ext of extensions) {
+          const routePath = `${dirPath}/route${ext}`;
+          if (this.exists(routePath)) {
+            return routePath;
+          }
+        }
+
+        // Check route groups
+        try {
+          const entries = this.vfs.readdirSync(dirPath);
+          for (const entry of entries) {
+            if (/^\([^)]+\)$/.test(entry) && this.isDirectory(`${dirPath}/${entry}`)) {
+              for (const ext of extensions) {
+                const routePath = `${dirPath}/${entry}/route${ext}`;
+                if (this.exists(routePath)) {
+                  return routePath;
+                }
+              }
+            }
+          }
+        } catch { /* ignore */ }
+
+        return null;
+      }
+
+      const [current, ...rest] = remainingSegments;
+
+      // Try exact match
+      const exactPath = `${dirPath}/${current}`;
+      if (this.isDirectory(exactPath)) {
+        const result = tryPath(exactPath, rest);
+        if (result) return result;
+      }
+
+      // Try route groups and dynamic segments
+      try {
+        const entries = this.vfs.readdirSync(dirPath);
+        for (const entry of entries) {
+          // Route groups
+          if (/^\([^)]+\)$/.test(entry) && this.isDirectory(`${dirPath}/${entry}`)) {
+            const groupExact = `${dirPath}/${entry}/${current}`;
+            if (this.isDirectory(groupExact)) {
+              const result = tryPath(groupExact, rest);
+              if (result) return result;
+            }
+          }
+          // Dynamic segments
+          if (entry.startsWith('[') && entry.endsWith(']') && !entry.includes('.')) {
+            const dynamicPath = `${dirPath}/${entry}`;
+            if (this.isDirectory(dynamicPath)) {
+              const result = tryPath(dynamicPath, rest);
+              if (result) return result;
+            }
+          }
+          // Catch-all
+          if (entry.startsWith('[...') && entry.endsWith(']')) {
+            const dynamicPath = `${dirPath}/${entry}`;
+            if (this.isDirectory(dynamicPath)) {
+              const result = tryPath(dynamicPath, []);
+              if (result) return result;
+            }
+          }
+        }
+      } catch { /* ignore */ }
+
+      return null;
+    };
+
+    return tryPath(this.appDir, segments);
+  }
+
+  /**
+   * Handle App Router route handler (route.ts) requests
+   * These use the Web Request/Response API pattern
+   */
+  private async handleAppRouteHandler(
+    method: string,
+    pathname: string,
+    headers: Record<string, string>,
+    body: Buffer | undefined,
+    routeFile: string,
+    search?: string
+  ): Promise<ResponseData> {
+    try {
+      const code = this.vfs.readFileSync(routeFile, 'utf8');
+      const transformed = await this.transformApiHandler(code, routeFile);
+
+      // Create module context
+      const builtinModules: Record<string, unknown> = {
+        https: await import('../shims/https'),
+        http: await import('../shims/http'),
+        path: await import('../shims/path'),
+        url: await import('../shims/url'),
+        querystring: await import('../shims/querystring'),
+        util: await import('../shims/util'),
+        events: await import('../shims/events'),
+        stream: await import('../shims/stream'),
+        buffer: await import('../shims/buffer'),
+        crypto: await import('../shims/crypto'),
+      };
+
+      const require = (id: string): unknown => {
+        const modId = id.startsWith('node:') ? id.slice(5) : id;
+        if (builtinModules[modId]) return builtinModules[modId];
+        throw new Error(`Module not found: ${id}`);
+      };
+
+      const module = { exports: {} as Record<string, unknown> };
+      const exports = module.exports;
+      const process = {
+        env: { ...this.options.env },
+        cwd: () => '/',
+        platform: 'browser',
+        version: 'v18.0.0',
+        versions: { node: '18.0.0' },
+      };
 
-    try {
-      // Read and transform the API handler to CJS for eval execution
-      const code = this.vfs.readFileSync(apiFile, 'utf8');
-      const transformed = await this.transformApiHandler(code, apiFile);
+      const fn = new Function('exports', 'require', 'module', 'process', transformed);
+      fn(exports, require, module, process);
 
-      // Create mock req/res objects
-      const req = this.createMockRequest(method, pathname, headers, body);
-      const res = this.createMockResponse();
+      // Get the handler for the HTTP method
+      const methodUpper = method.toUpperCase();
+      const handler = module.exports[methodUpper] || module.exports[methodUpper.toLowerCase()];
 
-      // Execute the handler
-      await this.executeApiHandler(transformed, req, res);
+      if (typeof handler !== 'function') {
+        return {
+          statusCode: 405,
+          statusMessage: 'Method Not Allowed',
+          headers: { 'Content-Type': 'application/json; charset=utf-8' },
+          body: Buffer.from(JSON.stringify({ error: `Method ${method} not allowed` })),
+        };
+      }
 
-      // Wait for async handlers (like those using https.get with callbacks)
-      // with a reasonable timeout
-      if (!res.isEnded()) {
-        const timeout = new Promise<void>((_, reject) => {
-          setTimeout(() => reject(new Error('API handler timeout')), 30000);
+      // Create a Web API Request object
+      const requestUrl = new URL(pathname + (search || ''), 'http://localhost');
+      const requestInit: RequestInit = {
+        method: methodUpper,
+        headers: new Headers(headers),
+      };
+      if (body && methodUpper !== 'GET' && methodUpper !== 'HEAD') {
+        requestInit.body = body;
+      }
+      const request = new Request(requestUrl.toString(), requestInit);
+
+      // Extract route params
+      const route = this.resolveAppRoute(pathname);
+      const params = route?.params || {};
+
+      // Call the handler
+      const response = await handler(request, { params: Promise.resolve(params) });
+
+      // Convert Response to our format
+      if (response instanceof Response) {
+        const respHeaders: Record<string, string> = {};
+        response.headers.forEach((value: string, key: string) => {
+          respHeaders[key] = value;
         });
-        await Promise.race([res.waitForEnd(), timeout]);
+
+        const respBody = await response.text();
+        return {
+          statusCode: response.status,
+          statusMessage: response.statusText || 'OK',
+          headers: respHeaders,
+          body: Buffer.from(respBody),
+        };
       }
 
-      return res.toResponse();
+      // If the handler returned a plain object, serialize as JSON
+      if (response && typeof response === 'object') {
+        const json = JSON.stringify(response);
+        return {
+          statusCode: 200,
+          statusMessage: 'OK',
+          headers: { 'Content-Type': 'application/json; charset=utf-8' },
+          body: Buffer.from(json),
+        };
+      }
+
+      return {
+        statusCode: 200,
+        statusMessage: 'OK',
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+        body: Buffer.from(String(response || '')),
+      };
     } catch (error) {
-      console.error('[NextDevServer] API error:', error);
+      console.error('[NextDevServer] App Route handler error:', error);
       return {
         statusCode: 500,
         statusMessage: 'Internal Server Error',
@@ -2077,82 +1469,128 @@ export class NextDevServer extends DevServer {
   /**
    * Resolve App Router route to page and layout files
    */
-  private resolveAppRoute(pathname: string): { page: string; layouts: string[]; params: Record<string, string | string[]> } | null {
-    const extensions = ['.jsx', '.tsx', '.js', '.ts'];
+  private resolveAppRoute(pathname: string): AppRoute | null {
     const segments = pathname === '/' ? [] : pathname.split('/').filter(Boolean);
+    // Use the unified dynamic resolver which handles static, dynamic, and route groups
+    return this.resolveAppDynamicRoute(pathname, segments);
+  }
 
-    // Build the directory path
-    let dirPath = this.appDir;
-    const layouts: string[] = [];
+  /**
+   * Resolve App Router routes including static, dynamic, and route groups.
+   * Route groups are folders wrapped in parentheses like (marketing) that
+   * don't affect the URL path but can have their own layouts.
+   */
+  private resolveAppDynamicRoute(
+    _pathname: string,
+    segments: string[]
+  ): AppRoute | null {
+    const extensions = ['.jsx', '.tsx', '.js', '.ts'];
 
-    // Collect layouts from root to current directory
-    for (const ext of extensions) {
-      const rootLayout = `${this.appDir}/layout${ext}`;
-      if (this.exists(rootLayout)) {
-        layouts.push(rootLayout);
-        break;
+    /**
+     * Collect layout from a directory if it exists
+     */
+    const collectLayout = (dirPath: string, layouts: string[]): string[] => {
+      for (const ext of extensions) {
+        const layoutPath = `${dirPath}/layout${ext}`;
+        if (this.exists(layoutPath) && !layouts.includes(layoutPath)) {
+          return [...layouts, layoutPath];
+        }
       }
-    }
-
-    // Walk through segments to find page and collect layouts
-    for (const segment of segments) {
-      dirPath = `${dirPath}/${segment}`;
+      return layouts;
+    };
 
-      // Check for layout in this segment
+    /**
+     * Find page file in a directory
+     */
+    const findPage = (dirPath: string): string | null => {
       for (const ext of extensions) {
-        const layoutPath = `${dirPath}/layout${ext}`;
-        if (this.exists(layoutPath)) {
-          layouts.push(layoutPath);
-          break;
+        const pagePath = `${dirPath}/page${ext}`;
+        if (this.exists(pagePath)) {
+          return pagePath;
         }
       }
-    }
+      return null;
+    };
 
-    // Find the page file
-    for (const ext of extensions) {
-      const pagePath = `${dirPath}/page${ext}`;
-      if (this.exists(pagePath)) {
-        // Static route - no params
-        return { page: pagePath, layouts, params: {} };
+    /**
+     * Find a UI convention file (loading, error, not-found) in a directory
+     */
+    const findConventionFile = (dirPath: string, name: string): string | null => {
+      for (const ext of extensions) {
+        const filePath = `${dirPath}/${name}${ext}`;
+        if (this.exists(filePath)) {
+          return filePath;
+        }
       }
-    }
+      return null;
+    };
 
-    // Try dynamic segments
-    return this.resolveAppDynamicRoute(pathname, segments);
-  }
+    /**
+     * Find the nearest convention file by walking up from the page directory
+     */
+    const findNearestConventionFile = (dirPath: string, name: string): string | null => {
+      let current = dirPath;
+      while (current.startsWith(this.appDir)) {
+        const file = findConventionFile(current, name);
+        if (file) return file;
+        // Move up one directory
+        const parent = current.replace(/\/[^/]+$/, '');
+        if (parent === current) break;
+        current = parent;
+      }
+      return null;
+    };
 
-  /**
-   * Resolve dynamic App Router routes like /app/[id]/page.jsx
-   * Also extracts route params from dynamic segments
-   */
-  private resolveAppDynamicRoute(
-    pathname: string,
-    segments: string[]
-  ): { page: string; layouts: string[]; params: Record<string, string | string[]> } | null {
-    const extensions = ['.jsx', '.tsx', '.js', '.ts'];
+    /**
+     * Get route group directories (folders matching (name) pattern)
+     */
+    const getRouteGroups = (dirPath: string): string[] => {
+      try {
+        const entries = this.vfs.readdirSync(dirPath);
+        return entries.filter(e => /^\([^)]+\)$/.test(e) && this.isDirectory(`${dirPath}/${e}`));
+      } catch {
+        return [];
+      }
+    };
 
     const tryPath = (
       dirPath: string,
       remainingSegments: string[],
       layouts: string[],
       params: Record<string, string | string[]>
-    ): { page: string; layouts: string[]; params: Record<string, string | string[]> } | null => {
+    ): AppRoute | null => {
       // Check for layout at current level
-      for (const ext of extensions) {
-        const layoutPath = `${dirPath}/layout${ext}`;
-        if (this.exists(layoutPath) && !layouts.includes(layoutPath)) {
-          layouts = [...layouts, layoutPath];
-        }
-      }
+      layouts = collectLayout(dirPath, layouts);
 
       if (remainingSegments.length === 0) {
-        // Look for page file
-        for (const ext of extensions) {
-          const pagePath = `${dirPath}/page${ext}`;
-          if (this.exists(pagePath)) {
-            return { page: pagePath, layouts, params };
+        // Look for page file directly
+        const page = findPage(dirPath);
+        if (page) {
+          return {
+            page, layouts, params,
+            loading: findNearestConventionFile(dirPath, 'loading') || undefined,
+            error: findNearestConventionFile(dirPath, 'error') || undefined,
+            notFound: findNearestConventionFile(dirPath, 'not-found') || undefined,
+          };
+        }
+
+        // Look for page inside route groups at this level
+        // e.g., /app/(marketing)/page.tsx resolves to /
+        const groups = getRouteGroups(dirPath);
+        for (const group of groups) {
+          const groupPath = `${dirPath}/${group}`;
+          const groupLayouts = collectLayout(groupPath, layouts);
+          const page = findPage(groupPath);
+          if (page) {
+            return {
+              page, layouts: groupLayouts, params,
+              loading: findNearestConventionFile(groupPath, 'loading') || undefined,
+              error: findNearestConventionFile(groupPath, 'error') || undefined,
+              notFound: findNearestConventionFile(groupPath, 'not-found') || undefined,
+            };
           }
         }
+
         return null;
       }
 
@@ -2165,7 +1603,56 @@ export class NextDevServer extends DevServer {
         if (result) return result;
       }
 
-      // Try dynamic segments
+      // Try inside route groups - route groups are transparent in URL
+      // e.g., /about might match /app/(marketing)/about/page.tsx
+      const groups = getRouteGroups(dirPath);
+      for (const group of groups) {
+        const groupPath = `${dirPath}/${group}`;
+        const groupLayouts = collectLayout(groupPath, layouts);
+
+        // Try exact match inside group
+        const groupExactPath = `${groupPath}/${current}`;
+        if (this.isDirectory(groupExactPath)) {
+          const result = tryPath(groupExactPath, rest, groupLayouts, params);
+          if (result) return result;
+        }
+
+        // Try dynamic segments inside group
+        try {
+          const groupEntries = this.vfs.readdirSync(groupPath);
+          for (const entry of groupEntries) {
+            if (entry.startsWith('[...') && entry.endsWith(']')) {
+              const dynamicPath = `${groupPath}/${entry}`;
+              if (this.isDirectory(dynamicPath)) {
+                const paramName = entry.slice(4, -1);
+                const newParams = { ...params, [paramName]: [current, ...rest] };
+                const result = tryPath(dynamicPath, [], groupLayouts, newParams);
+                if (result) return result;
+              }
+            } else if (entry.startsWith('[[...') && entry.endsWith(']]')) {
+              const dynamicPath = `${groupPath}/${entry}`;
+              if (this.isDirectory(dynamicPath)) {
+                const paramName = entry.slice(5, -2);
+                const newParams = { ...params, [paramName]: [current, ...rest] };
+                const result = tryPath(dynamicPath, [], groupLayouts, newParams);
+                if (result) return result;
+              }
+            } else if (entry.startsWith('[') && entry.endsWith(']') && !entry.includes('.')) {
+              const dynamicPath = `${groupPath}/${entry}`;
+              if (this.isDirectory(dynamicPath)) {
+                const paramName = entry.slice(1, -1);
+                const newParams = { ...params, [paramName]: current };
+                const result = tryPath(dynamicPath, rest, groupLayouts, newParams);
+                if (result) return result;
+              }
+            }
+          }
+        } catch {
+          // Group directory read failed
+        }
+      }
+
+      // Try dynamic segments at current level
       try {
         const entries = this.vfs.readdirSync(dirPath);
         for (const entry of entries) {
@@ -2173,9 +1660,17 @@ export class NextDevServer extends DevServer {
           if (entry.startsWith('[...') && entry.endsWith(']')) {
             const dynamicPath = `${dirPath}/${entry}`;
             if (this.isDirectory(dynamicPath)) {
-              // Extract param name from [...slug]
               const paramName = entry.slice(4, -1);
-              // Catch-all captures all remaining segments
+              const newParams = { ...params, [paramName]: [current, ...rest] };
+              const result = tryPath(dynamicPath, [], layouts, newParams);
+              if (result) return result;
+            }
+          }
+          // Handle optional catch-all routes [[...slug]]
+          else if (entry.startsWith('[[...') && entry.endsWith(']]')) {
+            const dynamicPath = `${dirPath}/${entry}`;
+            if (this.isDirectory(dynamicPath)) {
+              const paramName = entry.slice(5, -2);
               const newParams = { ...params, [paramName]: [current, ...rest] };
               const result = tryPath(dynamicPath, [], layouts, newParams);
               if (result) return result;
@@ -2185,7 +1680,6 @@ export class NextDevServer extends DevServer {
           else if (entry.startsWith('[') && entry.endsWith(']') && !entry.includes('.')) {
             const dynamicPath = `${dirPath}/${entry}`;
             if (this.isDirectory(dynamicPath)) {
-              // Extract param name from [id]
               const paramName = entry.slice(1, -1);
               const newParams = { ...params, [paramName]: current };
               const result = tryPath(dynamicPath, rest, layouts, newParams);
@@ -2213,302 +1707,28 @@ export class NextDevServer extends DevServer {
     return tryPath(this.appDir, segments, layouts, {});
   }
 
+  /**
+   * Build context object for HTML generation functions
+   */
+  private htmlContext() {
+    return {
+      port: this.port,
+      exists: (path: string) => this.exists(path),
+      generateEnvScript: () => this.generateEnvScript(),
+      loadTailwindConfigIfNeeded: () => this.loadTailwindConfigIfNeeded(),
+    };
+  }
+
   /**
    * Generate HTML for App Router with nested layouts
    */
   private async generateAppRouterHtml(
-    route: { page: string; layouts: string[]; params: Record<string, string | string[]> },
+    route: AppRoute,
     pathname: string
   ): Promise<string> {
-    // Use virtual server prefix for all file imports so the service worker can intercept them
-    const virtualPrefix = `/__virtual__/${this.port}`;
-
-    // Check for global CSS files
-    const globalCssLinks: string[] = [];
-    const cssLocations = ['/app/globals.css', '/styles/globals.css', '/styles/global.css'];
-    for (const cssPath of cssLocations) {
-      if (this.exists(cssPath)) {
-        globalCssLinks.push(`<link rel="stylesheet" href="${virtualPrefix}${cssPath}">`);
-      }
-    }
-
-    // Build the nested component structure
-    // Layouts wrap the page from outside in
-    const pageModulePath = virtualPrefix + route.page; // route.page already starts with /
-    const layoutImports = route.layouts
-      .map((layout, i) => `import Layout${i} from '${virtualPrefix}${layout}';`)
-      .join('\n    ');
-
-    // Build nested JSX: Layout0 > Layout1 > ... > Page
-    let nestedJsx = 'React.createElement(Page)';
-    for (let i = route.layouts.length - 1; i >= 0; i--) {
-      nestedJsx = `React.createElement(Layout${i}, null, ${nestedJsx})`;
-    }
-
-    // Generate env script for NEXT_PUBLIC_* variables
-    const envScript = this.generateEnvScript();
-
-    // Load Tailwind config if available (must be injected BEFORE CDN script)
-    const tailwindConfigScript = await this.loadTailwindConfigIfNeeded();
-
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <base href="${virtualPrefix}/">
-  <title>Next.js App</title>
-  ${envScript}
-  ${TAILWIND_CDN_SCRIPT}
-  ${tailwindConfigScript}
-  ${CORS_PROXY_SCRIPT}
-  ${globalCssLinks.join('\n  ')}
-  ${REACT_REFRESH_PREAMBLE}
-  <script type="importmap">
-  {
-    "imports": {
-      "react": "https://esm.sh/react@18.2.0?dev",
-      "react/": "https://esm.sh/react@18.2.0&dev/",
-      "react-dom": "https://esm.sh/react-dom@18.2.0?dev",
-      "react-dom/": "https://esm.sh/react-dom@18.2.0&dev/",
-      "react-dom/client": "https://esm.sh/react-dom@18.2.0/client?dev",
-      "convex/react": "https://esm.sh/convex@1.21.0/react?external=react",
-      "convex/server": "https://esm.sh/convex@1.21.0/server",
-      "convex/values": "https://esm.sh/convex@1.21.0/values",
-      "convex/_generated/api": "${virtualPrefix}/convex/_generated/api.ts",
-      "ai": "https://esm.sh/ai@4?external=react",
-      "ai/react": "https://esm.sh/ai@4/react?external=react",
-      "@ai-sdk/openai": "https://esm.sh/@ai-sdk/openai@1",
-      "next/link": "${virtualPrefix}/_next/shims/link.js",
-      "next/router": "${virtualPrefix}/_next/shims/router.js",
-      "next/head": "${virtualPrefix}/_next/shims/head.js",
-      "next/navigation": "${virtualPrefix}/_next/shims/navigation.js",
-      "next/image": "${virtualPrefix}/_next/shims/image.js",
-      "next/dynamic": "${virtualPrefix}/_next/shims/dynamic.js",
-      "next/script": "${virtualPrefix}/_next/shims/script.js",
-      "next/font/google": "${virtualPrefix}/_next/shims/font/google.js"
-    }
+    return _generateAppRouterHtml(this.htmlContext(), route, pathname);
   }
-  </script>
-  ${HMR_CLIENT_SCRIPT}
-</head>
-<body>
-  <div id="__next"></div>
-  <script type="module">
-    import React from 'react';
-    import ReactDOM from 'react-dom/client';
-
-    const virtualBase = '${virtualPrefix}';
-
-    // Initial route params (embedded by server for initial page load)
-    const initialRouteParams = ${JSON.stringify(route.params)};
-    const initialPathname = '${pathname}';
-
-    // Route params cache for client-side navigation
-    const routeParamsCache = new Map();
-    routeParamsCache.set(initialPathname, initialRouteParams);
-
-    // Extract route params from server for client-side navigation
-    async function extractRouteParams(pathname) {
-      // Strip virtual base if present
-      let route = pathname;
-      if (route.startsWith(virtualBase)) {
-        route = route.slice(virtualBase.length);
-      }
-      route = route.replace(/^\\/+/, '/') || '/';
-
-      // Check cache first
-      if (routeParamsCache.has(route)) {
-        return routeParamsCache.get(route);
-      }
-
-      try {
-        const response = await fetch(virtualBase + '/_next/route-info?pathname=' + encodeURIComponent(route));
-        const info = await response.json();
-        routeParamsCache.set(route, info.params || {});
-        return info.params || {};
-      } catch (e) {
-        console.error('[Router] Failed to extract route params:', e);
-        return {};
-      }
-    }
-
-    // Convert URL path to app router page module path
-    function getAppPageModulePath(pathname) {
-      let route = pathname;
-      if (route.startsWith(virtualBase)) {
-        route = route.slice(virtualBase.length);
-      }
-      route = route.replace(/^\\/+/, '/') || '/';
-      // App Router: / -> /app/page, /about -> /app/about/page
-      const pagePath = route === '/' ? '/app/page' : '/app' + route + '/page';
-      return virtualBase + '/_next/app' + pagePath + '.js';
-    }
-
-    // Get layout paths for a route
-    function getLayoutPaths(pathname) {
-      let route = pathname;
-      if (route.startsWith(virtualBase)) {
-        route = route.slice(virtualBase.length);
-      }
-      route = route.replace(/^\\/+/, '/') || '/';
-
-      // Build layout paths from root to current route
-      const layouts = [virtualBase + '/_next/app/app/layout.js'];
-      if (route !== '/') {
-        const segments = route.split('/').filter(Boolean);
-        let currentPath = '/app';
-        for (const segment of segments) {
-          currentPath += '/' + segment;
-          layouts.push(virtualBase + '/_next/app' + currentPath + '/layout.js');
-        }
-      }
-      return layouts;
-    }
-
-    // Dynamic page loader
-    async function loadPage(pathname) {
-      const modulePath = getAppPageModulePath(pathname);
-      try {
-        const module = await import(/* @vite-ignore */ modulePath);
-        return module.default;
-      } catch (e) {
-        console.error('[Navigation] Failed to load page:', modulePath, e);
-        return null;
-      }
-    }
-
-    // Load layouts (with caching)
-    const layoutCache = new Map();
-    async function loadLayouts(pathname) {
-      const layoutPaths = getLayoutPaths(pathname);
-      const layouts = [];
-      for (const path of layoutPaths) {
-        if (layoutCache.has(path)) {
-          layouts.push(layoutCache.get(path));
-        } else {
-          try {
-            const module = await import(/* @vite-ignore */ path);
-            layoutCache.set(path, module.default);
-            layouts.push(module.default);
-          } catch (e) {
-            // Layout might not exist for this segment, skip
-          }
-        }
-      }
-      return layouts;
-    }
-
-    // Wrapper for async Server Components
-    function AsyncComponent({ component: Component, pathname, search }) {
-      const [content, setContent] = React.useState(null);
-      const [error, setError] = React.useState(null);
-
-      React.useEffect(() => {
-        let cancelled = false;
-        async function render() {
-          try {
-            // Create searchParams as a Promise (Next.js 15 pattern)
-            const url = new URL(window.location.href);
-            const searchParamsObj = Object.fromEntries(url.searchParams);
-            const searchParams = Promise.resolve(searchParamsObj);
-
-            // Extract route params from pathname (fetches from server for dynamic routes)
-            const routeParams = await extractRouteParams(pathname);
-            const params = Promise.resolve(routeParams);
-
-            // Call component with props like Next.js does for page components
-            const result = Component({ searchParams, params });
-            if (result && typeof result.then === 'function') {
-              // It's a Promise (async component)
-              const resolved = await result;
-              if (!cancelled) setContent(resolved);
-            } else {
-              // Synchronous component - result is already JSX
-              if (!cancelled) setContent(result);
-            }
-          } catch (e) {
-            console.error('[AsyncComponent] Error rendering:', e);
-            if (!cancelled) setError(e);
-          }
-        }
-        render();
-        return () => { cancelled = true; };
-      }, [Component, pathname, search]);
-
-      if (error) {
-        return React.createElement('div', { style: { color: 'red', padding: '20px' } },
-          'Error: ' + error.message
-        );
-      }
-      if (!content) {
-        return React.createElement('div', { style: { padding: '20px' } }, 'Loading...');
-      }
-      return content;
-    }
-
-    // Router component
-    function Router() {
-      const [Page, setPage] = React.useState(null);
-      const [layouts, setLayouts] = React.useState([]);
-      const [path, setPath] = React.useState(window.location.pathname);
-      const [search, setSearch] = React.useState(window.location.search);
-
-      React.useEffect(() => {
-        Promise.all([loadPage(path), loadLayouts(path)]).then(([P, L]) => {
-          if (P) setPage(() => P);
-          setLayouts(L);
-        });
-      }, []);
-
-      React.useEffect(() => {
-        const handleNavigation = async () => {
-          const newPath = window.location.pathname;
-          const newSearch = window.location.search;
-          console.log('[Router] handleNavigation called, newPath:', newPath, 'current path:', path);
 
-          // Always update search params
-          if (newSearch !== search) {
-            setSearch(newSearch);
-          }
-
-          if (newPath !== path) {
-            console.log('[Router] Path changed, loading new page...');
-            setPath(newPath);
-            const [P, L] = await Promise.all([loadPage(newPath), loadLayouts(newPath)]);
-            console.log('[Router] Page loaded:', !!P, 'Layouts:', L.length);
-            if (P) setPage(() => P);
-            setLayouts(L);
-          } else {
-            console.log('[Router] Path unchanged, skipping navigation');
-          }
-        };
-        window.addEventListener('popstate', handleNavigation);
-        console.log('[Router] Added popstate listener for path:', path);
-        return () => window.removeEventListener('popstate', handleNavigation);
-      }, [path, search]);
-
-      if (!Page) return null;
-
-      // Use AsyncComponent wrapper to handle async Server Components
-      // Pass search to force re-render when query params change
-      let content = React.createElement(AsyncComponent, { component: Page, pathname: path, search: search });
-      for (let i = layouts.length - 1; i >= 0; i--) {
-        content = React.createElement(layouts[i], null, content);
-      }
-      return content;
-    }
-
-    // Mark that we've initialized (for testing no-reload)
-    window.__NEXT_INITIALIZED__ = Date.now();
-
-    ReactDOM.createRoot(document.getElementById('__next')).render(
-      React.createElement(React.StrictMode, null, React.createElement(Router))
-    );
-  </script>
-</body>
-</html>`;
-  }
 
   /**
    * Resolve URL pathname to page file
@@ -2634,175 +1854,14 @@ export class NextDevServer extends DevServer {
    * Generate HTML shell for a page
    */
   private async generatePageHtml(pageFile: string, pathname: string): Promise<string> {
-    // Use virtual server prefix for all file imports so the service worker can intercept them
-    // Without this, /pages/index.jsx would go to localhost:5173/pages/index.jsx
-    // instead of /__virtual__/3001/pages/index.jsx
-    const virtualPrefix = `/__virtual__/${this.port}`;
-    const pageModulePath = virtualPrefix + pageFile; // pageFile already starts with /
-
-    // Check for global CSS files
-    const globalCssLinks: string[] = [];
-    const cssLocations = ['/styles/globals.css', '/styles/global.css', '/app/globals.css'];
-    for (const cssPath of cssLocations) {
-      if (this.exists(cssPath)) {
-        globalCssLinks.push(`<link rel="stylesheet" href="${virtualPrefix}${cssPath}">`);
-      }
-    }
-
-    // Generate env script for NEXT_PUBLIC_* variables
-    const envScript = this.generateEnvScript();
-
-    // Load Tailwind config if available (must be injected BEFORE CDN script)
-    const tailwindConfigScript = await this.loadTailwindConfigIfNeeded();
-
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <base href="${virtualPrefix}/">
-  <title>Next.js App</title>
-  ${envScript}
-  ${TAILWIND_CDN_SCRIPT}
-  ${tailwindConfigScript}
-  ${CORS_PROXY_SCRIPT}
-  ${globalCssLinks.join('\n  ')}
-  ${REACT_REFRESH_PREAMBLE}
-  <script type="importmap">
-  {
-    "imports": {
-      "react": "https://esm.sh/react@18.2.0?dev",
-      "react/": "https://esm.sh/react@18.2.0&dev/",
-      "react-dom": "https://esm.sh/react-dom@18.2.0?dev",
-      "react-dom/": "https://esm.sh/react-dom@18.2.0&dev/",
-      "react-dom/client": "https://esm.sh/react-dom@18.2.0/client?dev",
-      "next/link": "${virtualPrefix}/_next/shims/link.js",
-      "next/router": "${virtualPrefix}/_next/shims/router.js",
-      "next/head": "${virtualPrefix}/_next/shims/head.js",
-      "next/navigation": "${virtualPrefix}/_next/shims/navigation.js",
-      "next/image": "${virtualPrefix}/_next/shims/image.js",
-      "next/dynamic": "${virtualPrefix}/_next/shims/dynamic.js",
-      "next/script": "${virtualPrefix}/_next/shims/script.js",
-      "next/font/google": "${virtualPrefix}/_next/shims/font/google.js"
-    }
-  }
-  </script>
-  ${HMR_CLIENT_SCRIPT}
-</head>
-<body>
-  <div id="__next"></div>
-  <script type="module">
-    import React from 'react';
-    import ReactDOM from 'react-dom/client';
-
-    const virtualBase = '${virtualPrefix}';
-
-    // Convert URL path to page module path
-    function getPageModulePath(pathname) {
-      let route = pathname;
-      if (route.startsWith(virtualBase)) {
-        route = route.slice(virtualBase.length);
-      }
-      route = route.replace(/^\\/+/, '/') || '/';
-      const modulePath = route === '/' ? '/index' : route;
-      return virtualBase + '/_next/pages' + modulePath + '.js';
-    }
-
-    // Dynamic page loader
-    async function loadPage(pathname) {
-      const modulePath = getPageModulePath(pathname);
-      try {
-        const module = await import(/* @vite-ignore */ modulePath);
-        return module.default;
-      } catch (e) {
-        console.error('[Navigation] Failed to load:', modulePath, e);
-        return null;
-      }
-    }
-
-    // Router component
-    function Router() {
-      const [Page, setPage] = React.useState(null);
-      const [path, setPath] = React.useState(window.location.pathname);
-
-      React.useEffect(() => {
-        loadPage(path).then(C => C && setPage(() => C));
-      }, []);
-
-      React.useEffect(() => {
-        const handleNavigation = async () => {
-          const newPath = window.location.pathname;
-          if (newPath !== path) {
-            setPath(newPath);
-            const C = await loadPage(newPath);
-            if (C) setPage(() => C);
-          }
-        };
-        window.addEventListener('popstate', handleNavigation);
-        return () => window.removeEventListener('popstate', handleNavigation);
-      }, [path]);
-
-      if (!Page) return null;
-      return React.createElement(Page);
-    }
-
-    // Mark that we've initialized (for testing no-reload)
-    window.__NEXT_INITIALIZED__ = Date.now();
-
-    ReactDOM.createRoot(document.getElementById('__next')).render(
-      React.createElement(React.StrictMode, null, React.createElement(Router))
-    );
-  </script>
-</body>
-</html>`;
+    return _generatePageHtml(this.htmlContext(), pageFile, pathname);
   }
 
   /**
    * Serve a basic 404 page
    */
   private serve404Page(): ResponseData {
-    const virtualPrefix = `/__virtual__/${this.port}`;
-    const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <base href="${virtualPrefix}/">
-  <title>404 - Page Not Found</title>
-  <style>
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      display: flex;
-      flex-direction: column;
-      align-items: center;
-      justify-content: center;
-      min-height: 100vh;
-      margin: 0;
-      background: #fafafa;
-    }
-    h1 { font-size: 48px; margin: 0; }
-    p { color: #666; margin-top: 10px; }
-    a { color: #0070f3; text-decoration: none; }
-    a:hover { text-decoration: underline; }
-  </style>
-</head>
-<body>
-  <h1>404</h1>
-  <p>This page could not be found.</p>
-  <p><a href="/">Go back home</a></p>
-</body>
-</html>`;
-
-    const buffer = Buffer.from(html);
-    return {
-      statusCode: 404,
-      statusMessage: 'Not Found',
-      headers: {
-        'Content-Type': 'text/html; charset=utf-8',
-        'Content-Length': String(buffer.length),
-      },
-      body: buffer,
-    };
+    return _serve404Page(this.port);
   }
 
   /**
@@ -2874,8 +1933,12 @@ export class NextDevServer extends DevServer {
       // Use filePath (with extension) for transform so loader is correctly determined
       const transformed = await this.transformCode(content, filePath);
 
-      // Cache the transform result
+      // Cache the transform result (LRU eviction at 500 entries)
       this.transformCache.set(filePath, { code: transformed, hash });
+      if (this.transformCache.size > 500) {
+        const firstKey = this.transformCache.keys().next().value;
+        if (firstKey) this.transformCache.delete(firstKey);
+      }
 
       const buffer = Buffer.from(transformed);
       return {
@@ -2910,7 +1973,9 @@ export class NextDevServer extends DevServer {
    */
   private async transformCode(code: string, filename: string): Promise<string> {
     if (!isBrowser) {
-      return code;
+      // Even in non-browser mode, strip/transform CSS imports
+      // so CSS module imports get replaced with class name objects
+      return this.stripCssImports(code, filename);
     }
 
     await initEsbuild();
@@ -2922,7 +1987,7 @@ export class NextDevServer extends DevServer {
 
     // Remove CSS imports before transformation - they are handled via <link> tags
     // CSS imports in ESM would fail with MIME type errors
-    const codeWithoutCssImports = this.stripCssImports(code);
+    const codeWithoutCssImports = this.stripCssImports(code, filename);
 
     // Resolve path aliases (e.g., @/ -> /) before transformation
     const codeWithResolvedAliases = this.resolvePathAliases(codeWithoutCssImports, filename);
@@ -2953,81 +2018,19 @@ export class NextDevServer extends DevServer {
     return codeWithCdnImports;
   }
 
-  /**
-   * Redirect bare npm package imports to esm.sh CDN
-   * e.g., import { Crisp } from "crisp-sdk-web" -> import { Crisp } from "https://esm.sh/crisp-sdk-web?external=react"
-   *
-   * IMPORTANT: We redirect ALL npm packages to esm.sh URLs (including React)
-   * because import maps don't work reliably for dynamically imported modules.
-   */
   private redirectNpmImports(code: string): string {
-    // Explicit mappings for common packages (ensures correct esm.sh URLs)
-    const explicitMappings: Record<string, string> = {
-      'react': 'https://esm.sh/react@18.2.0?dev',
-      'react/jsx-runtime': 'https://esm.sh/react@18.2.0&dev/jsx-runtime',
-      'react/jsx-dev-runtime': 'https://esm.sh/react@18.2.0&dev/jsx-dev-runtime',
-      'react-dom': 'https://esm.sh/react-dom@18.2.0?dev',
-      'react-dom/client': 'https://esm.sh/react-dom@18.2.0/client?dev',
-    };
-
-    // Packages that are local or have custom shims (NOT npm packages)
-    const localPackages = new Set([
-      'next/link', 'next/router', 'next/head', 'next/navigation',
-      'next/dynamic', 'next/image', 'next/script', 'next/font/google',
-      'convex/_generated/api'
-    ]);
-
-    // Pattern to match import statements with bare package specifiers
-    // Matches: from "package" or from 'package' where package doesn't start with . / or http
-    const importPattern = /(from\s*['"])([^'"./][^'"]*?)(['"])/g;
-
-    return code.replace(importPattern, (match, prefix, packageName, suffix) => {
-      // Skip if already a URL or local virtual path
-      if (packageName.startsWith('http://') ||
-          packageName.startsWith('https://') ||
-          packageName.startsWith('/__virtual__')) {
-        return match;
-      }
-
-      // Check explicit mappings first
-      if (explicitMappings[packageName]) {
-        return `${prefix}${explicitMappings[packageName]}${suffix}`;
-      }
-
-      // Skip local/shimmed packages (they're handled via import map or virtual paths)
-      if (localPackages.has(packageName)) {
-        return match;
-      }
-
-      // Check if it's a subpath import of a local package
-      const basePkg = packageName.includes('/') ? packageName.split('/')[0] : packageName;
-
-      // Handle scoped packages (@org/pkg)
-      const isScoped = basePkg.startsWith('@');
-      const scopedBasePkg = isScoped && packageName.includes('/')
-        ? packageName.split('/').slice(0, 2).join('/')
-        : basePkg;
-
-      if (localPackages.has(scopedBasePkg)) {
-        return match;
-      }
+    return _redirectNpmImports(code);
+  }
 
-      // Redirect to esm.sh with external=react to avoid bundling React twice
-      const esmUrl = `https://esm.sh/${packageName}?external=react`;
-      return `${prefix}${esmUrl}${suffix}`;
-    });
+  private stripCssImports(code: string, currentFile?: string): string {
+    return _stripCssImports(code, currentFile, this.getCssModuleContext());
   }
 
-  /**
-   * Strip CSS imports from code (they are loaded via <link> tags instead)
-   * Handles: import './styles.css', import '../globals.css', etc.
-   */
-  private stripCssImports(code: string): string {
-    // Match import statements for CSS files (with or without semicolon)
-    // Handles: import './styles.css'; import "./globals.css" import '../path/file.css'
-    // NOTE: Don't match trailing whitespace (\s*) as it would consume newlines
-    // and break subsequent imports that start on the next line
-    return code.replace(/import\s+['"][^'"]+\.css['"]\s*;?/g, '');
+  private getCssModuleContext(): CssModuleContext {
+    return {
+      readFile: (path: string) => this.vfs.readFileSync(path, 'utf-8'),
+      exists: (path: string) => this.exists(path),
+    };
   }
 
   /**
@@ -3062,94 +2065,11 @@ export class NextDevServer extends DevServer {
       return result.code;
     }
 
-    // Simple ESM to CJS transform for Node.js/test environment
-    let transformed = codeWithResolvedAliases;
-
-    // Convert: import X from 'Y' -> const X = require('Y')
-    transformed = transformed.replace(
-      /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g,
-      'const $1 = require("$2")'
-    );
-
-    // Convert: import { X } from 'Y' -> const { X } = require('Y')
-    transformed = transformed.replace(
-      /import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g,
-      'const {$1} = require("$2")'
-    );
-
-    // Convert: export default function X -> module.exports = function X
-    transformed = transformed.replace(
-      /export\s+default\s+function\s+(\w+)/g,
-      'module.exports = function $1'
-    );
-
-    // Convert: export default function -> module.exports = function
-    transformed = transformed.replace(
-      /export\s+default\s+function\s*\(/g,
-      'module.exports = function('
-    );
-
-    // Convert: export default X -> module.exports = X
-    transformed = transformed.replace(
-      /export\s+default\s+/g,
-      'module.exports = '
-    );
-
-    return transformed;
+    return transformEsmToCjsSimple(codeWithResolvedAliases);
   }
 
-  /**
-   * Add React Refresh registration to transformed code
-   */
   private addReactRefresh(code: string, filename: string): string {
-    const components: string[] = [];
-
-    const funcDeclRegex = /(?:^|\n)(?:export\s+)?function\s+([A-Z][a-zA-Z0-9]*)\s*\(/g;
-    let match;
-    while ((match = funcDeclRegex.exec(code)) !== null) {
-      if (!components.includes(match[1])) {
-        components.push(match[1]);
-      }
-    }
-
-    const arrowRegex = /(?:^|\n)(?:export\s+)?(?:const|let|var)\s+([A-Z][a-zA-Z0-9]*)\s*=/g;
-    while ((match = arrowRegex.exec(code)) !== null) {
-      if (!components.includes(match[1])) {
-        components.push(match[1]);
-      }
-    }
-
-    if (components.length === 0) {
-      return `// HMR Setup
-import.meta.hot = window.__vite_hot_context__("${filename}");
-
-${code}
-
-if (import.meta.hot) {
-  import.meta.hot.accept();
-}
-`;
-    }
-
-    const registrations = components
-      .map(name => `  $RefreshReg$(${name}, "${filename} ${name}");`)
-      .join('\n');
-
-    return `// HMR Setup
-import.meta.hot = window.__vite_hot_context__("${filename}");
-
-${code}
-
-// React Refresh Registration
-if (import.meta.hot) {
-${registrations}
-  import.meta.hot.accept(() => {
-    if (window.$RefreshRuntime$) {
-      window.$RefreshRuntime$.performReactRefresh();
-    }
-  });
-}
-`;
+    return _addReactRefresh(code, filename);
   }
 
   /**