arcway 0.1.23 → 0.1.24

package/client/page-loader.js

@@ -36,6 +36,50 @@ function readClientManifest() {
   }
 }
 
+function syncStylesForPath(manifest, pathname) {
+  if (typeof document === 'undefined' || !manifest) return;
+
+  const globalHref = manifest.cssBundle ?? null;
+  const matched = matchClientRoute(manifest, pathname);
+  const routeHrefs = matched?.route?.cssBundles ?? [];
+
+  const globalLinks = Array.from(
+    document.querySelectorAll('link[rel="stylesheet"][data-arcway-css="global"]'),
+  );
+  for (const link of globalLinks) {
+    if (!globalHref) continue;
+    const current = link.getAttribute('href')?.split('?')[0] ?? '';
+    if (current !== globalHref) link.setAttribute('href', globalHref);
+  }
+
+  const existingRouteLinks = Array.from(
+    document.querySelectorAll('link[rel="stylesheet"][data-arcway-css="route"]'),
+  );
+  const head = document.head || document.querySelector('head');
+  if (!head) return;
+
+  for (let i = 0; i < routeHrefs.length; i++) {
+    const href = routeHrefs[i];
+    const existing = existingRouteLinks[i];
+    if (existing) {
+      const current = existing.getAttribute('href')?.split('?')[0] ?? '';
+      if (current !== href) existing.setAttribute('href', href);
+      existing.setAttribute('data-arcway-css-index', String(i));
+      continue;
+    }
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.setAttribute('data-arcway-css', 'route');
+    link.setAttribute('data-arcway-css-index', String(i));
+    link.href = href;
+    head.appendChild(link);
+  }
+
+  for (let i = routeHrefs.length; i < existingRouteLinks.length; i++) {
+    existingRouteLinks[i].remove();
+  }
+}
+
 function matchClientRoute(manifest, pathname) {
   for (const route of manifest.routes) {
     let compiled = patternCache.get(route.pattern);
@@ -109,4 +153,5 @@ export {
   matchClientRoute,
   prefetchRoute,
   readClientManifest,
+  syncStylesForPath,
 };

package/client/router.js

@@ -15,6 +15,7 @@ import {
   matchClientRoute,
   loadLoadingComponents,
   prefetchRoute,
+  syncStylesForPath,
 } from './page-loader.js';
 import { parseQuery } from './query.js';
 
@@ -72,6 +73,7 @@ function useSearchParams() {
 function Router({
   initialPath,
   initialParams,
+  initialPattern,
   initialComponent,
   initialLayouts,
   initialLoadings,
@@ -81,6 +83,7 @@ function Router({
     () => initialPath ?? (typeof window !== 'undefined' ? window.location.pathname : '/'),
   );
   const [pageState, setPageState] = useState({
+    pattern: initialPattern ?? null,
     component: initialComponent ?? null,
     layouts: initialLayouts ?? [],
     loadings: initialLoadings ?? [],
@@ -96,12 +99,24 @@ function Router({
 
   useEffect(() => {
     manifestRef.current = readClientManifest();
+    if (manifestRef.current) {
+      syncStylesForPath(manifestRef.current, pathname);
+    }
     const onManifestUpdate = () => {
       manifestRef.current = readClientManifest();
+      if (manifestRef.current) {
+        syncStylesForPath(manifestRef.current, window.location.pathname);
+      }
     };
     window.addEventListener('manifest-update', onManifestUpdate);
     return () => window.removeEventListener('manifest-update', onManifestUpdate);
-  }, []);
+  }, [pathname]);
+
+  useEffect(() => {
+    if (manifestRef.current) {
+      syncStylesForPath(manifestRef.current, pathname);
+    }
+  }, [pathname]);
 
   // `bumpQuery` controls whether `queryVersion` is incremented atomically
   // with the page-state updates. It lives inside the same `startTransition`
@@ -116,6 +131,7 @@ function Router({
     startTransition(() => {
       setPathname(newPath);
       setPageState({
+        pattern: loaded.pattern ?? null,
         component: loaded.component,
         layouts: loaded.layouts,
         loadings: loaded.loadings,
@@ -177,6 +193,7 @@ function Router({
         setPathname(pathOnly);
         setPageState((prev) => ({
           ...prev,
+          pattern: matched.route.pattern,
           loadings: targetLoadings,
           params: matched.params,
         }));
@@ -217,7 +234,7 @@ function Router({
 
       if (!manifest) {
         setPathname(newPath);
-        setPageState((prev) => ({ ...prev, params: {} }));
+        setPageState((prev) => ({ ...prev, pattern: null, params: {} }));
         setQueryVersion((v) => v + 1);
         return;
       }
@@ -238,6 +255,12 @@ function Router({
     return () => window.removeEventListener('popstate', onPopState);
   }, [pathname, applyLoaded]);
 
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      window.__arcway_current_pattern__ = pageState.pattern ?? null;
+    }
+  }, [pageState.pattern]);
+
   const { component: PageComponent, layouts, loadings, params } = pageState;
 
   let content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -47,8 +47,10 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.987.0",
     "@babel/core": "^7.29.0",
+    "@vitejs/plugin-react": "^5.1.0",
     "@base-ui/react": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@tailwindcss/vite": "^4.1.18",
     "@tailwindcss/postcss": "^4.1.18",
     "arktype": "^2.1.29",
     "bcryptjs": "^3.0.3",
@@ -99,6 +101,7 @@
     "tailwind-merge": "^3.4.1",
     "tailwindcss": "^4.1.18",
     "vaul": "^1.1.2",
+    "vite": "^7.1.12",
     "ws": "^8.19.0",
     "zod": "^3.24.0"
   },

package/server/boot/index.js

@@ -14,6 +14,8 @@ import { StaticRouter } from '../static/index.js';
 import { WsRouter } from '../ws/ws-router.js';
 import { createWsBackplane } from '../ws/backplane.js';
 import { runHook } from './hooks.js';
+import { createViteDevRouter } from '../pages/vite-dev.js';
+import { resolvePagesOutDir } from '../pages/out-dir.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -85,6 +87,11 @@ async function boot(options) {
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
+  const pagesOutDir = resolvePagesOutDir(config, rootDir, mode);
+  const viteRouter =
+    mode === 'development' && config.pages?.vite?.enabled === true
+      ? await createViteDevRouter({ rootDir, log, config })
+      : null;
 
   const healthDeps = {
     db,
@@ -93,7 +100,7 @@ async function boot(options) {
   const systemRouter = new SystemRouter({ healthDeps });
 
   const staticRouter = new StaticRouter({
-    outDir: config.pages?.outDir ?? path.resolve(rootDir, '.build/pages'),
+    outDir: pagesOutDir,
     publicDir: path.join(rootDir, 'public'),
   });
 
@@ -113,6 +120,7 @@ async function boot(options) {
   webServer.use(systemRouter, '/_system');
   webServer.use(apiRouter, apiRouter.prefix);
   webServer.use(wsRouter, config.websocket.path);
+  if (viteRouter) webServer.use(viteRouter);
   webServer.use(staticRouter);
   webServer.use(pagesRouter);
 
@@ -130,6 +138,7 @@ async function boot(options) {
     if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();
     await apiRouter.close();
+    if (viteRouter) await viteRouter.close();
     await webServer.close();
     if (fileWatcher) await fileWatcher.close();
     await destroyInfrastructure(infrastructure);

package/server/build.js

@@ -1,5 +1,6 @@
 import { makeConfig } from './config/loader.js';
 import { buildPages } from './pages/build.js';
+import { resolvePagesOutDir } from './pages/out-dir.js';
 
 async function build(options) {
   const rootDir = options?.rootDir ?? process.cwd();
@@ -11,6 +12,7 @@ async function build(options) {
   if (pagesEnabled) {
     pages = await buildPages({
       rootDir,
+      outDir: resolvePagesOutDir(config, rootDir, 'production'),
       serverTarget: buildTarget,
       minify: true,
       fonts: config?.pages?.fonts,

package/server/config/modules/pages.js

@@ -4,16 +4,31 @@ const DEFAULTS = {
   enabled: true,
   dir: 'pages',
   outDir: '.build/pages',
+  devOutDir: '.build-dev/pages',
+  vite: {
+    enabled: false,
+  },
 };
 
 function resolve(config, { rootDir } = {}) {
-  const pages = { ...DEFAULTS, ...config.pages };
+  const rawPages = config.pages ?? {};
+  const pages = {
+    ...DEFAULTS,
+    ...rawPages,
+    vite: {
+      ...DEFAULTS.vite,
+      ...(rawPages.vite ?? {}),
+    },
+  };
   if (pages.dir && !path.isAbsolute(pages.dir)) {
     pages.dir = path.resolve(rootDir, pages.dir);
   }
   if (pages.outDir && !path.isAbsolute(pages.outDir)) {
     pages.outDir = path.resolve(rootDir, pages.outDir);
   }
+  if (pages.devOutDir && !path.isAbsolute(pages.devOutDir)) {
+    pages.devOutDir = path.resolve(rootDir, pages.devOutDir);
+  }
   return { ...config, pages };
 }
 

package/server/pages/build-cache.js

@@ -263,7 +263,7 @@ async function restoreMultiFileCache({ cacheDir, outputs, destDir }) {
       const src = path.join(cacheDir, rel);
       const dst = path.join(destDir, rel);
       await fs.mkdir(path.dirname(dst), { recursive: true });
-      await fs.cp(src, dst);
+      await cpAtomic(src, dst);
     }),
   );
 }

package/server/pages/build-client.js

@@ -35,7 +35,7 @@ function planHydrationEntries(pages, layouts, loadings, tempDir) {
     const outName = patternToFileName(page.pattern);
     const layoutChain = resolveLayoutChain(page.pattern, layouts);
     const loadingChain = resolveLoadingChain(page.pattern, loadings);
-    const content = generateHydrationEntry(page.filePath, layoutChain, loadingChain);
+    const content = generateHydrationEntry(page.filePath, layoutChain, loadingChain, page.pattern);
     const entryPath = path.join(tempDir, `${outName}.tsx`);
     files.push({ entryPath, content });
     entryPoints[outName] = entryPath;
@@ -284,6 +284,7 @@ async function collectStaleOutputs(metafile, clientDir) {
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       const abs = path.join(dir, entry.name);
+      if (shouldPreserveClientAsset(abs, clientDir)) continue;
       if (!currentOutputs.has(abs)) stale.add(abs);
     }
   }
@@ -295,6 +296,14 @@ async function collectStaleOutputs(metafile, clientDir) {
   return stale;
 }
 
+function shouldPreserveClientAsset(absPath, clientDir) {
+  const rel = path.relative(clientDir, absPath).replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..')) return false;
+  if (rel.startsWith('hmr/')) return true;
+  if (/^styles-[a-f0-9]+\.css$/i.test(rel)) return true;
+  return false;
+}
+
 async function tryRestoreClientFromCache({ rootDir, clientDir, coarseKey }) {
   const lookup = await lookupMultiFileCache({ rootDir, kind: 'client', coarseKey });
   if (!lookup.hit) return { hit: false, bucket: lookup.bucket };
@@ -459,7 +468,7 @@ function extractMetadata(result, plan, outDir) {
   return { bundles, navBundles, layoutNavBundles, loadingNavBundles, entryChunks, entryCssChunks };
 }
 
-function generateHydrationEntry(componentPath, layouts = [], loadings = []) {
+function generateHydrationEntry(componentPath, layouts = [], loadings = [], pattern = '/') {
   const importPath = componentPath.replace(/\\/g, '/');
   const imports = [
     `import { hydrateRoot } from 'react-dom/client';`,
@@ -485,8 +494,19 @@ function generateHydrationEntry(componentPath, layouts = [], loadings = []) {
 const container = document.getElementById('__app');
 const propsEl = document.getElementById('__app_props');
 const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+const ROOT_KEY = '__arcway_root__';
+const rootOwner = window;
+const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
 
-hydrateRoot(container!, <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>);
+if (!container) {
+  throw new Error('Arcway hydrate entry could not find #__app');
+}
+
+if (!rootOwner[ROOT_KEY]) {
+  rootOwner[ROOT_KEY] = hydrateRoot(container, element);
+} else {
+  rootOwner[ROOT_KEY].render(element);
+}
 `;
 }
 export { buildClientBundles, createClientBuildContext, generateHydrationEntry };

package/server/pages/handler.js

@@ -15,6 +15,7 @@ import {
 } from './ssr.js';
 import { MIME_TYPES } from './static.js';
 import { createArcwayDevEndpoint } from './arcway-endpoint.js';
+import { buildViteClientManifestJson, buildViteRoute } from './vite-dev.js';
 function createPagesHandler(options) {
   const rootDir = options.rootDir;
   const outDir = path.resolve(rootDir, options.outDir ?? '.build/pages');
@@ -23,6 +24,7 @@ function createPagesHandler(options) {
   const appContext = options.appContext ?? null;
   const mode = options.mode ?? 'production';
   const devMode = mode === 'development';
+  const viteDev = options.viteDev === true;
   const lazyContext = options.lazyContext ?? null;
   // Dev with a lazy context drives the handler off an in-memory manifest; no
   // disk `pages-manifest.json` is produced. Prod still reads from disk.
@@ -39,8 +41,12 @@ function createPagesHandler(options) {
   let manifest = lazyContext
     ? lazyContext.manifest
     : JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  let routes = compileRoutes(manifest);
-  let clientManifestJson = buildClientManifestJson(manifest);
+  let routes = compileRoutes(manifest, { rootDir, outDir, viteDev });
+  let clientManifestJson = buildClientManifestJson(manifest, {
+    rootDir,
+    outDir,
+    viteDev,
+  });
   let lastSeenVersion = lazyContext ? manifest.version : 0;
   const componentCache = new Map();
   let cacheVersion = 0;
@@ -60,8 +66,12 @@ function createPagesHandler(options) {
     if (!lazyContext) return;
     if (manifest.version === lastSeenVersion) return;
     lastSeenVersion = manifest.version;
-    routes = compileRoutes(manifest);
-    clientManifestJson = buildClientManifestJson(manifest);
+    routes = compileRoutes(manifest, { rootDir, outDir, viteDev });
+    clientManifestJson = buildClientManifestJson(manifest, {
+      rootDir,
+      outDir,
+      viteDev,
+    });
     componentCache.clear();
     cacheVersion++;
   }
@@ -79,8 +89,12 @@ function createPagesHandler(options) {
     }
     if (!fs.existsSync(manifestPath)) return;
     manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-    routes = compileRoutes(manifest);
-    clientManifestJson = buildClientManifestJson(manifest);
+    routes = compileRoutes(manifest, { rootDir, outDir, viteDev });
+    clientManifestJson = buildClientManifestJson(manifest, {
+      rootDir,
+      outDir,
+      viteDev,
+    });
     componentCache.clear();
     cacheVersion++;
   }
@@ -104,7 +118,11 @@ function createPagesHandler(options) {
       });
       res.write('data: connected\n\n');
       const onUpdate = (event) => {
-        res.write(`data: ${JSON.stringify(event)}
+        let payload = event;
+        if (event?.type === 'hmr-update' || event?.type === 'css-update') {
+          payload = { ...event, manifest: clientManifestJson };
+        }
+        res.write(`data: ${JSON.stringify(payload)}
 
 `);
       };
@@ -201,6 +219,7 @@ function createPagesHandler(options) {
         cacheVersion,
         projectReact,
         devMode,
+        viteDev,
       );
     } catch (err) {
       if (manifest.errorBundle && !res.headersSent) {
@@ -275,10 +294,10 @@ async function renderDevBuildError(
     res.end(`<h1>500 - Build Error</h1><pre>${escaped}</pre>`);
   }
 }
-function compileRoutes(manifest) {
+function compileRoutes(manifest, { rootDir, outDir, viteDev } = {}) {
   const routes = manifest.entries.map((entry) => {
     const { regex, paramNames, catchAllParam } = compilePattern(entry.pattern);
-    return {
+    let route = {
       pattern: entry.pattern,
       regex,
       paramNames,
@@ -290,6 +309,10 @@ function compileRoutes(manifest) {
       sharedChunks: entry.sharedChunks ?? [],
       sharedCssChunks: entry.sharedCssChunks ?? [],
     };
+    if (viteDev) {
+      route = buildViteRoute(route, { rootDir, outDir });
+    }
+    return route;
   });
   sortBySpecificity(routes);
   return routes;
@@ -350,8 +373,12 @@ async function runPageMiddleware(
   }
   return null;
 }
-function buildClientManifestJson(manifest) {
+function buildClientManifestJson(manifest, { rootDir, outDir, viteDev } = {}) {
+  if (viteDev) {
+    return buildViteClientManifestJson(manifest, rootDir);
+  }
   const clientManifest = {
+    cssBundle: manifest.cssBundle ? `/static/${manifest.cssBundle}` : null,
     routes: manifest.entries.map((entry) => {
       const route = {
         pattern: entry.pattern,
@@ -359,6 +386,7 @@ function buildClientManifestJson(manifest) {
         clientBundle: `/static/${entry.navBundle}`,
         layoutBundles: (entry.layoutClientBundles ?? []).map((b) => `/static/${b}`),
         loadingBundles: (entry.loadingClientBundles ?? []).map((b) => `/static/${b}`),
+        cssBundles: (entry.sharedCssChunks ?? []).map((b) => `/static/${b}`),
       };
       if (entry.catchAllParam) {
         route.catchAllParam = entry.catchAllParam;

package/server/pages/hmr.js

@@ -79,38 +79,65 @@ window.$RefreshReg$ = function() {};
 window.$RefreshSig$ = function() { return function(type) { return type; }; };
 window.__REACT_REFRESH__ = RefreshRuntime;
 
-var es = new EventSource('/__livereload');
-es.onmessage = function(e) {
-  if (e.data === 'connected') return;
-  var msg;
-  try { msg = JSON.parse(e.data); } catch { window.location.reload(); return; }
-  if (msg.type === 'reload') {
-    window.location.reload();
-  } else if (msg.type === 'hmr-update') {
-    var imports = msg.modules.map(function(m) {
-      return import('/static/' + m + '?t=' + msg.timestamp);
-    });
-    Promise.all(imports).then(function() {
-      RefreshRuntime.performReactRefresh();
-      if (msg.manifest) {
-        var el = document.getElementById('__app_manifest');
-        if (el) el.textContent = msg.manifest;
-        window.dispatchEvent(new CustomEvent('manifest-update'));
-      }
-    }).catch(function(err) {
-      console.warn('[HMR] Fast Refresh failed, doing full reload', err);
-      window.location.reload();
-    });
-  } else if (msg.type === 'css-update') {
-    var links = document.querySelectorAll('link[rel="stylesheet"][href*="/static/"]');
-    links.forEach(function(link) {
-      link.href = '/static/' + msg.cssBundle + '?t=' + msg.timestamp;
-    });
+var es = null;
+var reconnectTimer = null;
+
+function applyManifest(manifestJson) {
+  if (!manifestJson) return;
+  var el = document.getElementById('__app_manifest');
+  if (el) el.textContent = manifestJson;
+  window.dispatchEvent(new CustomEvent('manifest-update'));
+}
+
+function pickCurrentHmrModules(msg) {
+  var currentPattern = window.__arcway_current_pattern__;
+  if (currentPattern && msg.routeBundles && msg.routeBundles[currentPattern]) {
+    return ['/static/' + msg.routeBundles[currentPattern] + '?t=' + msg.timestamp];
   }
-};
-es.onerror = function() {
-  setTimeout(function() { es.close(); }, 5000);
-};
+  return (msg.modules || []).map(function(m) {
+    return '/static/' + m + '?t=' + msg.timestamp;
+  });
+}
+
+function connect() {
+  if (es) es.close();
+  es = new EventSource('/__livereload');
+  es.onmessage = function(e) {
+    if (e.data === 'connected') return;
+    var msg;
+    try { msg = JSON.parse(e.data); } catch { window.location.reload(); return; }
+    if (msg.type === 'reload') {
+      window.location.reload();
+    } else if (msg.type === 'hmr-update') {
+      var imports = pickCurrentHmrModules(msg).map(function(specifier) {
+        return import(specifier);
+      });
+      Promise.all(imports).then(function() {
+        RefreshRuntime.performReactRefresh();
+        applyManifest(msg.manifest);
+      }).catch(function(err) {
+        console.warn('[HMR] Fast Refresh failed, doing full reload', err);
+        window.location.reload();
+      });
+    } else if (msg.type === 'css-update') {
+      var links = document.querySelectorAll('link[rel="stylesheet"][data-arcway-css="global"]');
+      links.forEach(function(link) {
+        link.href = '/static/' + msg.cssBundle + '?t=' + msg.timestamp;
+      });
+      applyManifest(msg.manifest);
+    }
+  };
+  es.onerror = function() {
+    if (reconnectTimer) return;
+    try { es.close(); } catch {}
+    reconnectTimer = setTimeout(function() {
+      reconnectTimer = null;
+      connect();
+    }, 1000);
+  };
+}
+
+connect();
 </script>`;
 }
 function diffClientMetafiles(oldMeta, newMeta, outDir) {

package/server/pages/lazy-context.js

@@ -28,7 +28,8 @@ import {
 import { createClientBuildContext } from './build-client.js';
 import { buildCssBundle } from './build-css.js';
 import { resolveFonts } from './fonts.js';
-import { buildHmrRuntimeBundle } from './hmr.js';
+import { buildHmrRuntimeBundle, diffClientMetafiles } from './hmr.js';
+import { syncViteHydrationEntries } from './vite-dev.js';
 
 // Dev-mode build context that defers per-page/layout/middleware server-bundle
 // compilation to first request. Startup is cheap: discover routes, build the
@@ -50,6 +51,7 @@ async function createLazyPagesContext(options) {
   const clientTarget = options.clientTarget ?? 'es2022';
   const minify = options.minify ?? false;
   const devMode = options.devMode ?? true;
+  const viteDev = options.viteDev ?? false;
   const esbuildImpl = options.esbuild ?? esbuild;
   // Cap per-context server-bundle concurrency so a request burst after a
   // cold start can't spawn N pages × M esbuild Go workers simultaneously.
@@ -63,6 +65,7 @@ async function createLazyPagesContext(options) {
 
   let disposed = false;
   let clientCtx = null;
+  let currentClientMetafile = null;
   let fontFaceCss;
   let fontPreloadHtml;
 
@@ -101,6 +104,13 @@ async function createLazyPagesContext(options) {
         { srcPath: path.resolve(m.filePath), built: false, stale: false },
       ]),
     ),
+    loadings: new Map(
+      loadings.map((l) => [
+        l.dirPath,
+        { srcPath: path.resolve(l.filePath) },
+      ]),
+    ),
+    stylesPath: stylesPath ? path.resolve(stylesPath) : null,
     version: 0,
   };
 
@@ -120,11 +130,46 @@ async function createLazyPagesContext(options) {
     events.emit(event, payload);
   }
 
+  function applyClientResult(clientResult) {
+    for (const entry of manifest.entries) {
+      const clientBundle = clientResult.bundles.get(entry.pattern);
+      const navBundle = clientResult.navBundles.get(entry.pattern);
+      if (clientBundle) entry.clientBundle = clientBundle;
+      if (navBundle) entry.navBundle = navBundle;
+      entry.layoutClientBundles = entry.layoutDirs
+        .map((d) => clientResult.layoutNavBundles.get(d))
+        .filter((v) => v !== undefined);
+      entry.loadingClientBundles = entry.loadingDirs
+        .map((d) => clientResult.loadingNavBundles.get(d))
+        .filter((v) => v !== undefined);
+      entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
+      entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
+    }
+    currentClientMetafile = clientResult.metafile ?? currentClientMetafile;
+  }
+
   // Client bundle + CSS + error pages + HMR runtime are built eagerly at
   // startup. They're shared across every request and their compilation cost
   // is bounded (a single esbuild.context for the client, one esbuild.transform
   // for CSS), so there's no win in deferring them.
   async function eagerSharedBuilds() {
+    if (viteDev) {
+      const [errorBundles] = await Promise.all([
+        buildErrorPageBundles(errorPages, outDir, serverTarget, {
+          rootDir,
+          devMode,
+          minify,
+          limit,
+        }),
+        syncViteHydrationEntries({ manifest, outDir }),
+      ]);
+      if (errorBundles.error) manifest.errorBundle = errorBundles.error;
+      if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
+      bumpVersion();
+      emit('update', { type: 'startup', version: manifest.version });
+      return { clientMetafile: null };
+    }
+
     clientCtx = await createClientBuildContext(
       pages,
       layouts,
@@ -151,20 +196,7 @@ async function createLazyPagesContext(options) {
     // Fold client bundle output into the manifest so renderPage() can find
     // navBundle / layoutClientBundles / shared chunks immediately, the same
     // as it would from a disk-backed prod manifest.
-    for (const entry of manifest.entries) {
-      const clientBundle = clientResult.bundles.get(entry.pattern);
-      const navBundle = clientResult.navBundles.get(entry.pattern);
-      if (clientBundle) entry.clientBundle = clientBundle;
-      if (navBundle) entry.navBundle = navBundle;
-      entry.layoutClientBundles = entry.layoutDirs
-        .map((d) => clientResult.layoutNavBundles.get(d))
-        .filter((v) => v !== undefined);
-      entry.loadingClientBundles = entry.loadingDirs
-        .map((d) => clientResult.loadingNavBundles.get(d))
-        .filter((v) => v !== undefined);
-      entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
-      entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
-    }
+    applyClientResult(clientResult);
     if (cssBundle) manifest.cssBundle = cssBundle;
     if (errorBundles.error) manifest.errorBundle = errorBundles.error;
     if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
@@ -314,13 +346,55 @@ async function createLazyPagesContext(options) {
     });
   }
 
-  // Mark every manifest entry affected by a source change as stale. Does not
-  // trigger rebuilds directly — the next `ensurePageBuilt()` call (driven by
-  // an incoming request) handles the actual work. Structural changes
-  // (add/remove files) are not handled here; the watcher will re-init the
-  // context or extend the manifest in phase 5.
-  function invalidate(filePath) {
+  function markAllEntriesStale() {
+    let touched = false;
+    const affected = { pages: [], layouts: [], middlewares: [] };
+    for (const entry of manifest.entries) {
+      if (!entry.stale || entry.built) {
+        entry.stale = true;
+        entry.built = false;
+        touched = true;
+      }
+      affected.pages.push(entry.pattern);
+    }
+    for (const [dirPath, layout] of manifest.layouts.entries()) {
+      if (!layout.stale || layout.built) {
+        layout.stale = true;
+        layout.built = false;
+        touched = true;
+      }
+      affected.layouts.push(dirPath);
+    }
+    for (const [dirPath, mw] of manifest.middlewares.entries()) {
+      if (!mw.stale || mw.built) {
+        mw.stale = true;
+        mw.built = false;
+        touched = true;
+      }
+      affected.middlewares.push(dirPath);
+    }
+    return { touched, affected };
+  }
+
+  function shouldInvalidateWholeTree(filePath, affected) {
+    if (
+      affected.pages.length > 0 ||
+      affected.layouts.length > 0 ||
+      affected.middlewares.length > 0
+    ) {
+      return false;
+    }
+    const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) return false;
+    return /^(components|hooks|client|packages)\//.test(rel);
+  }
+
+  function markAffectedStale(filePath) {
     const affected = mapFileToAffected(filePath, manifest);
+    if (shouldInvalidateWholeTree(filePath, affected)) {
+      return markAllEntriesStale();
+    }
+
     let touched = false;
     for (const pattern of affected.pages) {
       const entry = findEntry(pattern);
@@ -346,6 +420,16 @@ async function createLazyPagesContext(options) {
         touched = true;
       }
     }
+    return { touched, affected };
+  }
+
+  // Mark every manifest entry affected by a source change as stale. Does not
+  // trigger rebuilds directly — the next `ensurePageBuilt()` call (driven by
+  // an incoming request) handles the actual work. Structural changes
+  // (add/remove files) are not handled here; the watcher will re-init the
+  // context or extend the manifest in phase 5.
+  function invalidate(filePath) {
+    const { touched, affected } = markAffectedStale(filePath);
     if (touched) {
       bumpVersion();
       emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
@@ -353,6 +437,87 @@ async function createLazyPagesContext(options) {
     return { touched, affected };
   }
 
+  let inFlightClientRefresh = null;
+
+  async function handleSourceChange(filePath) {
+    if (disposed) throw new Error('Lazy pages context is disposed');
+    const { touched, affected } = markAffectedStale(filePath);
+    if (!touched) return { touched: false, affected, hmr: null };
+    if (viteDev) {
+      bumpVersion();
+      emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
+      return { touched: true, affected, hmr: null };
+    }
+    if (inFlightClientRefresh) return inFlightClientRefresh;
+
+    const task = (async () => {
+      const previousMetafile = currentClientMetafile;
+      const previousCssBundle = manifest.cssBundle ?? null;
+      const timestamp = Date.now();
+
+      const [clientResult, cssBundle] = await Promise.all([
+        clientCtx?.rebuild() ?? Promise.resolve(null),
+        buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir),
+      ]);
+
+      if (clientResult) {
+        applyClientResult(clientResult);
+      }
+      if (cssBundle) manifest.cssBundle = cssBundle;
+
+      bumpVersion();
+      emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
+
+      let hmr = null;
+      if (clientResult && previousMetafile) {
+        const diff = diffClientMetafiles(previousMetafile, clientResult.metafile, outDir);
+        const modules = [...diff.changedHydrationBundles, ...diff.changedNavBundles];
+        const routeBundles = {};
+        for (const pattern of affected.pages) {
+          const entry = findEntry(pattern);
+          if (entry?.clientBundle) routeBundles[pattern] = entry.clientBundle;
+        }
+        if (diff.needsFullReload) {
+          hmr = { type: 'reload', timestamp };
+          emit('update', {
+            type: 'reload',
+            filePath,
+            reason: 'client-bundle-drift',
+            timestamp,
+            version: manifest.version,
+          });
+        } else if (modules.length > 0) {
+          hmr = { type: 'hmr-update', modules, routeBundles, timestamp };
+          emit('update', {
+            type: 'hmr-update',
+            filePath,
+            modules,
+            routeBundles,
+            timestamp,
+            version: manifest.version,
+          });
+        }
+      }
+
+      if (manifest.cssBundle) {
+        emit('update', {
+          type: 'css-update',
+          filePath,
+          cssBundle: manifest.cssBundle,
+          timestamp,
+          version: manifest.version,
+        });
+      }
+
+      return { touched: true, affected, hmr };
+    })().finally(() => {
+      inFlightClientRefresh = null;
+    });
+
+    inFlightClientRefresh = task;
+    return task;
+  }
+
   // ── Structural rediscovery ─────────────────────────────────────────────
   // `invalidate()` handles content edits to known files; `rediscover()`
   // handles add/delete of pages, layouts, and middlewares. Re-runs the same
@@ -385,6 +550,8 @@ async function createLazyPagesContext(options) {
       const result = {
         added: { pages: [], layouts: [], middlewares: [] },
         removed: { pages: [], layouts: [], middlewares: [] },
+        addedLoadings: [],
+        removedLoadings: [],
         staleByCascade: [],
         clientRebuilt: false,
         version: manifest.version,
@@ -406,13 +573,20 @@ async function createLazyPagesContext(options) {
       const addedMiddlewares = nextMiddlewares.filter((m) => !currentMwDirs.has(m.dirPath));
       const removedMiddlewares = [...currentMwDirs].filter((d) => !nextMwDirs.has(d));
 
+      const currentLoadingDirs = new Set(manifest.loadings.keys());
+      const nextLoadingDirs = new Set(nextLoadings.map((l) => l.dirPath));
+      const addedLoadings = nextLoadings.filter((l) => !currentLoadingDirs.has(l.dirPath));
+      const removedLoadings = [...currentLoadingDirs].filter((d) => !nextLoadingDirs.has(d));
+
       const noOp =
         addedPages.length === 0 &&
         removedPages.length === 0 &&
         addedLayouts.length === 0 &&
         removedLayouts.length === 0 &&
         addedMiddlewares.length === 0 &&
-        removedMiddlewares.length === 0;
+        removedMiddlewares.length === 0 &&
+        addedLoadings.length === 0 &&
+        removedLoadings.length === 0;
       if (noOp) return result;
 
       // ── Apply layout add/remove ──────────────────────────────────────
@@ -445,6 +619,17 @@ async function createLazyPagesContext(options) {
         result.removed.middlewares.push(dirPath);
       }
 
+      for (const loading of addedLoadings) {
+        manifest.loadings.set(loading.dirPath, {
+          srcPath: path.resolve(loading.filePath),
+        });
+        result.addedLoadings.push(loading.dirPath);
+      }
+      for (const dirPath of removedLoadings) {
+        manifest.loadings.delete(dirPath);
+        result.removedLoadings.push(dirPath);
+      }
+
       // ── Apply page add/remove ────────────────────────────────────────
       const addedPagePatterns = new Set();
       for (const page of addedPages) {
@@ -494,8 +679,10 @@ async function createLazyPagesContext(options) {
         result.added.pages.length > 0 ||
         result.removed.pages.length > 0 ||
         result.added.layouts.length > 0 ||
-        result.removed.layouts.length > 0;
-      if (needClientRebuild) {
+        result.removed.layouts.length > 0 ||
+        result.addedLoadings.length > 0 ||
+        result.removedLoadings.length > 0;
+      if (needClientRebuild && !viteDev) {
         if (clientCtx) {
           try {
             await clientCtx.dispose();
@@ -515,22 +702,14 @@ async function createLazyPagesContext(options) {
           devMode,
         );
         const clientResult = await clientCtx.rebuild();
-        for (const entry of manifest.entries) {
-          const clientBundle = clientResult.bundles.get(entry.pattern);
-          const navBundle = clientResult.navBundles.get(entry.pattern);
-          if (clientBundle) entry.clientBundle = clientBundle;
-          if (navBundle) entry.navBundle = navBundle;
-          entry.layoutClientBundles = entry.layoutDirs
-            .map((d) => clientResult.layoutNavBundles.get(d))
-            .filter((v) => v !== undefined);
-          entry.loadingClientBundles = entry.loadingDirs
-            .map((d) => clientResult.loadingNavBundles.get(d))
-            .filter((v) => v !== undefined);
-          entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
-          entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
-        }
+        applyClientResult(clientResult);
         result.clientRebuilt = true;
       }
+      if (viteDev) {
+        const nextStylesPath = await discoverStyles(pagesDir);
+        manifest.stylesPath = nextStylesPath ? path.resolve(nextStylesPath) : null;
+        await syncViteHydrationEntries({ manifest, outDir });
+      }
 
       // ── Version bump + event emission ────────────────────────────────
       bumpVersion();
@@ -553,6 +732,12 @@ async function createLazyPagesContext(options) {
       for (const dirPath of result.removed.middlewares) {
         emit('update', { type: 'remove-middleware', dirPath, version: manifest.version });
       }
+      for (const dirPath of result.addedLoadings) {
+        emit('update', { type: 'add-loading', dirPath, version: manifest.version });
+      }
+      for (const dirPath of result.removedLoadings) {
+        emit('update', { type: 'remove-loading', dirPath, version: manifest.version });
+      }
       if (result.clientRebuilt) {
         emit('update', { type: 'client-rebuilt', version: manifest.version });
       }
@@ -603,9 +788,11 @@ async function createLazyPagesContext(options) {
         stale: m.stale,
         ...(m.lastBuiltAt ? { lastBuiltAt: m.lastBuiltAt } : {}),
       })),
+      loadings: Array.from(manifest.loadings.keys()).map((dirPath) => ({ dirPath })),
       ...(manifest.errorBundle ? { errorBundle: manifest.errorBundle } : {}),
       ...(manifest.notFoundBundle ? { notFoundBundle: manifest.notFoundBundle } : {}),
       ...(manifest.cssBundle ? { cssBundle: manifest.cssBundle } : {}),
+      ...(manifest.stylesPath ? { stylesPath: manifest.stylesPath } : {}),
     };
   }
 
@@ -627,12 +814,13 @@ async function createLazyPagesContext(options) {
     ensureLayoutBuilt,
     ensureMiddlewareBuilt,
     invalidate,
+    handleSourceChange,
     rediscover,
     dispose,
     on,
     getManifestJson,
     get clientMetafile() {
-      return startup.clientMetafile;
+      return currentClientMetafile ?? startup.clientMetafile;
     },
   };
 }

package/server/pages/out-dir.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+
+function resolvePagesOutDir(config, rootDir, mode = 'production') {
+  const pages = config?.pages ?? {};
+  const isDev = mode === 'development';
+  const prodOutDir = pages.outDir ?? path.resolve(rootDir, '.build/pages');
+  const devOutDir = pages.devOutDir ?? path.resolve(rootDir, '.build-dev/pages');
+  return isDev ? devOutDir : prodOutDir;
+}
+
+export { resolvePagesOutDir };

package/server/pages/pages-router.js

@@ -1,6 +1,7 @@
 import { createPagesHandler } from './handler.js';
 import { createLazyPagesContext } from './lazy-context.js';
 import { createPagesWatcher } from './watcher.js';
+import { resolvePagesOutDir } from './out-dir.js';
 
 class PagesRouter {
   config;
@@ -24,6 +25,8 @@ class PagesRouter {
   async init() {
     const { config, rootDir, log, mode, fileWatcher } = this;
     const isDev = mode === 'development';
+    const viteDev = isDev && config.pages?.vite?.enabled === true;
+    const outDir = resolvePagesOutDir(config, rootDir, mode);
 
     if (isDev) {
       // Dev mode: `createLazyPagesContext()` builds only the shared bits
@@ -35,9 +38,11 @@ class PagesRouter {
         this.lazyContext = await createLazyPagesContext({
           rootDir,
           pagesDir: config.pages.dir,
+          outDir,
           fonts: config.pages?.fonts,
           minify: false,
           devMode: true,
+          viteDev,
         });
       } catch (err) {
         log.error('Pages lazy context init failed', { error: String(err) });
@@ -46,9 +51,11 @@ class PagesRouter {
 
     this.handler = createPagesHandler({
       rootDir,
+      outDir,
       session: config.session,
       appContext: this.appContext,
       mode,
+      viteDev,
       ...(this.lazyContext ? { lazyContext: this.lazyContext } : {}),
     });
 

package/server/pages/ssr.js

@@ -70,12 +70,14 @@ function wrapWithProviders(createElement, element, pathname, params) {
 }
 function buildCssLinkTag(manifest) {
   if (!manifest.cssBundle) return '';
-  return `<link rel="stylesheet" href="/static/${manifest.cssBundle}" />`;
+  return `<link rel="stylesheet" data-arcway-css="global" href="/static/${manifest.cssBundle}" />`;
 }
 function buildRouteCssLinkTags(route) {
   const chunks = route?.sharedCssChunks ?? [];
   if (chunks.length === 0) return '';
-  return chunks.map((c) => `<link rel="stylesheet" href="/static/${c}" />`).join('\n');
+  return chunks
+    .map((c) => `<link rel="stylesheet" data-arcway-css="route" href="/static/${c}" />`)
+    .join('\n');
 }
 function buildFontPreloadTags(manifest) {
   return manifest.fontPreloadHtml ?? '';
@@ -97,6 +99,19 @@ function buildScriptTags(route) {
   tags.push(`<script type="module" src="/static/${route.clientBundle}"></script>`);
   return tags.join('\n');
 }
+function buildViteScriptTags(route) {
+  return [
+    `<script type="module">
+import RefreshRuntime from "/@react-refresh";
+RefreshRuntime.injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.__vite_plugin_react_preamble_installed__ = true;
+</script>`,
+    `<script type="module" src="/@vite/client"></script>`,
+    `<script type="module" src="${route.clientBundle}"></script>`,
+  ].join('\n');
+}
 function buildHtmlShell({ headHtml, fontPreloadTags, cssLinkTag, bodysuffix }) {
   return {
     head: `<!DOCTYPE html>
@@ -128,6 +143,7 @@ async function renderPage(
   cacheVersion,
   react,
   devMode,
+  viteDev = false,
 ) {
   const { createElement, renderToPipeableStream } = react;
   const bundlePath = path.join(outDir, route.serverBundle);
@@ -155,14 +171,14 @@ async function renderPage(
       layoutComponents.push(Layout);
     }
   }
-  const scriptTags = buildScriptTags(route);
-  const manifestCssTag = buildCssLinkTag(manifest);
-  const routeCssTags = buildRouteCssLinkTags(route);
+  const scriptTags = viteDev ? buildViteScriptTags(route) : buildScriptTags(route);
+  const manifestCssTag = viteDev ? '' : buildCssLinkTag(manifest);
+  const routeCssTags = viteDev ? '' : buildRouteCssLinkTags(route);
   const cssLinkTag = [manifestCssTag, routeCssTags].filter(Boolean).join('\n');
   const fontPreloadTags = buildFontPreloadTags(manifest);
   const envScriptTag = buildEnvScriptTag(collectPublicEnv());
-  const hmrTag = devMode ? buildHmrScript() : '';
-  const liveReloadTag = devMode && !hmrTag ? buildLiveReloadScript() : '';
+  const hmrTag = devMode && !viteDev ? buildHmrScript() : '';
+  const liveReloadTag = devMode && !viteDev && !hmrTag ? buildLiveReloadScript() : '';
   const propsJson = JSON.stringify(params).replace(/</g, '\\u003c');
   const headData = { meta: [], links: [] };
   setSSRHeadData(headData);

package/server/pages/vite-dev.js

@@ -0,0 +1,246 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import reactPlugin from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { createServer as createViteServer } from 'vite';
+import { patternToFileName } from './build-server.js';
+
+function toPosixPath(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function toViteModuleUrl(rootDir, filePath) {
+  if (!filePath) return null;
+  const abs = path.resolve(filePath);
+  const rel = path.relative(rootDir, abs);
+  if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+    return `/${toPosixPath(rel)}`;
+  }
+  return `/@fs/${toPosixPath(abs)}`;
+}
+
+function getViteEntryPath(outDir, pattern) {
+  return path.join(outDir, '.vite-entries', `${patternToFileName(pattern)}.tsx`);
+}
+
+function buildViteHydrationEntry({
+  componentPath,
+  layouts = [],
+  loadings = [],
+  pattern = '/',
+  globalStylesPath,
+}) {
+  const imports = [
+    `import { hydrateRoot } from 'react-dom/client';`,
+    `import { ApiProvider, Router } from 'arcway/lib/client';`,
+  ];
+
+  if (globalStylesPath) {
+    imports.push(`import '${toPosixPath(path.resolve(globalStylesPath))}';`);
+  }
+
+  imports.push(`import Component from '${toPosixPath(path.resolve(componentPath))}';`);
+
+  const layoutNames = [];
+  for (let i = 0; i < layouts.length; i++) {
+    imports.push(`import Layout${i} from '${toPosixPath(path.resolve(layouts[i]))}';`);
+    layoutNames.push(`Layout${i}`);
+  }
+
+  const loadingNames = [];
+  for (let i = 0; i < loadings.length; i++) {
+    imports.push(`import Loading${i} from '${toPosixPath(path.resolve(loadings[i]))}';`);
+    loadingNames.push(`Loading${i}`);
+  }
+
+  const layoutsArray = layoutNames.length > 0 ? `[${layoutNames.join(', ')}]` : '[]';
+  const loadingsArray = loadingNames.length > 0 ? `[${loadingNames.join(', ')}]` : '[]';
+
+  return `${imports.join('\n')}
+
+const container = document.getElementById('__app');
+const propsEl = document.getElementById('__app_props');
+const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+const ROOT_KEY = '__arcway_root__';
+const rootOwner = window;
+const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
+
+if (!container) {
+  throw new Error('Arcway Vite hydrate entry could not find #__app');
+}
+
+if (!rootOwner[ROOT_KEY]) {
+  rootOwner[ROOT_KEY] = hydrateRoot(container, element);
+} else {
+  rootOwner[ROOT_KEY].render(element);
+}
+`;
+}
+
+async function syncViteHydrationEntries({ manifest, outDir }) {
+  const viteDir = path.join(outDir, '.vite-entries');
+  await fs.mkdir(viteDir, { recursive: true });
+
+  const expected = new Set();
+
+  for (const entry of manifest.entries) {
+    const entryPath = getViteEntryPath(outDir, entry.pattern);
+    const content = buildViteHydrationEntry({
+      componentPath: entry.srcPath,
+      layouts: entry.layoutDirs
+        .map((dirPath) => manifest.layouts.get(dirPath)?.srcPath)
+        .filter((value) => value !== undefined),
+      loadings: entry.loadingDirs
+        .map((dirPath) => manifest.loadings.get(dirPath)?.srcPath)
+        .filter((value) => value !== undefined),
+      pattern: entry.pattern,
+      globalStylesPath: manifest.stylesPath,
+    });
+    await fs.mkdir(path.dirname(entryPath), { recursive: true });
+    await fs.writeFile(entryPath, content);
+    expected.add(toPosixPath(path.relative(viteDir, entryPath)));
+  }
+
+  const existing = await listFiles(viteDir);
+  await Promise.all(
+    existing
+      .filter((name) => !expected.has(name))
+      .map((name) => fs.rm(path.join(viteDir, name), { force: true })),
+  );
+}
+
+async function listFiles(rootDir, currentDir = rootDir) {
+  const entries = await fs.readdir(currentDir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const abs = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listFiles(rootDir, abs);
+      files.push(...nested);
+      continue;
+    }
+    files.push(toPosixPath(path.relative(rootDir, abs)));
+  }
+  return files;
+}
+
+function buildViteClientManifestJson(manifest, rootDir) {
+  const clientManifest = {
+    cssBundle: null,
+    routes: manifest.entries.map((entry) => {
+      const route = {
+        pattern: entry.pattern,
+        paramNames: entry.paramNames,
+        clientBundle: toViteModuleUrl(rootDir, entry.srcPath),
+        layoutBundles: entry.layoutDirs
+          .map((dirPath) => manifest.layouts.get(dirPath)?.srcPath)
+          .filter(Boolean)
+          .map((filePath) => toViteModuleUrl(rootDir, filePath)),
+        loadingBundles: entry.loadingDirs
+          .map((dirPath) => manifest.loadings.get(dirPath)?.srcPath)
+          .filter(Boolean)
+          .map((filePath) => toViteModuleUrl(rootDir, filePath)),
+        cssBundles: [],
+      };
+      if (entry.catchAllParam) route.catchAllParam = entry.catchAllParam;
+      return route;
+    }),
+  };
+  return JSON.stringify(clientManifest).replace(/</g, '\\u003c');
+}
+
+function buildViteRoute(route, { rootDir, outDir }) {
+  return {
+    ...route,
+    clientBundle: toViteModuleUrl(rootDir, getViteEntryPath(outDir, route.pattern)),
+    sharedChunks: ['/@vite/client'],
+    sharedCssChunks: [],
+  };
+}
+
+function resolveAppAliases(rootDir) {
+  const appRequire = createRequire(path.join(rootDir, 'package.json'));
+  const aliases = [];
+
+  try {
+    const reactRoot = path.dirname(appRequire.resolve('react/package.json'));
+    aliases.push({ find: /^react$/, replacement: toPosixPath(path.join(reactRoot, 'index.js')) });
+    aliases.push({ find: /^react\/jsx-runtime$/, replacement: toPosixPath(path.join(reactRoot, 'jsx-runtime.js')) });
+    aliases.push({ find: /^react\/jsx-dev-runtime$/, replacement: toPosixPath(path.join(reactRoot, 'jsx-dev-runtime.js')) });
+  } catch {}
+
+  try {
+    const reactDomRoot = path.dirname(appRequire.resolve('react-dom/package.json'));
+    aliases.push({ find: /^react-dom$/, replacement: toPosixPath(path.join(reactDomRoot, 'index.js')) });
+    aliases.push({ find: /^react-dom\/client$/, replacement: toPosixPath(path.join(reactDomRoot, 'client.js')) });
+  } catch {}
+
+  try {
+    aliases.push({ find: /^swr$/, replacement: toPosixPath(appRequire.resolve('swr')) });
+  } catch {}
+
+  return aliases;
+}
+
+async function createViteDevRouter({ rootDir, log, config }) {
+  const appAliases = resolveAppAliases(rootDir);
+  const vite = await createViteServer({
+    root: rootDir,
+    appType: 'custom',
+    server: {
+      middlewareMode: true,
+    },
+    resolve: {
+      alias: appAliases,
+      dedupe: ['react', 'react-dom', 'swr'],
+    },
+    optimizeDeps: {
+      include: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'swr'],
+    },
+    plugins: [reactPlugin(), tailwindcss()],
+    clearScreen: false,
+  });
+
+  const internalPrefixes = ['/@vite/', '/@id/', '/@react-refresh', '/@fs/', '/node_modules/.vite/'];
+  const sourceExt = /\.(?:[cm]?[jt]sx?|css|pcss|postcss|json|svg)$/i;
+
+  async function handle(req, res) {
+    const url = req.url ?? '/';
+    const pathname = url.split('?')[0];
+    const shouldDelegate =
+      internalPrefixes.some((prefix) => pathname.startsWith(prefix)) ||
+      sourceExt.test(pathname) ||
+      pathname.startsWith('/.build/pages/.vite-entries/');
+
+    if (!shouldDelegate) return false;
+
+    return new Promise((resolve, reject) => {
+      vite.middlewares(req, res, (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(res.writableEnded || res.headersSent);
+      });
+    });
+  }
+
+  return {
+    vite,
+    handle,
+    async close() {
+      await vite.close();
+      log?.info?.('Vite dev server closed');
+    },
+  };
+}
+
+export {
+  buildViteClientManifestJson,
+  buildViteRoute,
+  createViteDevRouter,
+  getViteEntryPath,
+  syncViteHydrationEntries,
+  toViteModuleUrl,
+};

package/server/pages/watcher.js

@@ -36,7 +36,9 @@ function createPagesWatcher(options) {
       }
       for (const e of events) {
         if (e.event !== 'change') continue;
-        const result = lazyContext.invalidate(e.path);
+        const result = lazyContext.handleSourceChange
+          ? await lazyContext.handleSourceChange(e.path)
+          : lazyContext.invalidate(e.path);
         if (result.touched) {
           log.info(`Pages: invalidated ${e.relativePath} (${formatAffected(result.affected)})`);
         }

package/server/watcher.js

@@ -3,13 +3,9 @@ import path from 'node:path';
 function startWatcher(options) {
   const dirs = options.dirs ?? [
     'api',
-    'pages',
-    'components',
-    'hooks',
     'lib',
     'listeners',
     'jobs',
-    'packages',
     'server',
     'templates',
     'migrations',