@lolyjs/core 0.2.0-alpha.14 → 0.2.0-alpha.16

package/dist/index.cjs

@@ -116,7 +116,7 @@ module.exports = __toCommonJS(src_exports);
 
 // src/server.ts
 var import_fs18 = __toESM(require("fs"));
-var import_path22 = __toESM(require("path"));
+var import_path25 = __toESM(require("path"));
 
 // modules/server/utils/server-dir.ts
 var import_fs = __toESM(require("fs"));
@@ -246,7 +246,7 @@ function loadLayoutsForDir(pageDir, appDir) {
   };
 }
 
-// modules/router/loader.ts
+// modules/router/server-hook.ts
 var import_fs3 = __toESM(require("fs"));
 var import_path3 = __toESM(require("path"));
 var NAMING = {
@@ -258,14 +258,16 @@ var NAMING = {
   // Files
   SERVER_HOOK: "server.hook"
 };
-function loadLoaderForDir(currentDir) {
-  const loaderTs = import_path3.default.join(currentDir, `${NAMING.SERVER_HOOK}.ts`);
-  const loaderJs = import_path3.default.join(currentDir, `${NAMING.SERVER_HOOK}.js`);
-  const file = import_fs3.default.existsSync(loaderTs) ? loaderTs : import_fs3.default.existsSync(loaderJs) ? loaderJs : null;
+function loadServerHookForDir(currentDir) {
+  const pageServerHookTs = import_path3.default.join(currentDir, `page.server.hook.ts`);
+  const pageServerHookJs = import_path3.default.join(currentDir, `page.server.hook.js`);
+  const serverHookTs = import_path3.default.join(currentDir, `${NAMING.SERVER_HOOK}.ts`);
+  const serverHookJs = import_path3.default.join(currentDir, `${NAMING.SERVER_HOOK}.js`);
+  const file = import_fs3.default.existsSync(pageServerHookTs) ? pageServerHookTs : import_fs3.default.existsSync(pageServerHookJs) ? pageServerHookJs : import_fs3.default.existsSync(serverHookTs) ? serverHookTs : import_fs3.default.existsSync(serverHookJs) ? serverHookJs : null;
   if (!file) {
     return {
       middlewares: [],
-      loader: null,
+      serverHook: null,
       dynamic: "auto",
       generateStaticParams: null
     };
@@ -281,31 +283,119 @@ function loadLoaderForDir(currentDir) {
     mod = require(file);
   } catch (error) {
     console.error(
-      `[framework][loader] Error loading server hook from ${file}:`,
+      `[framework][server-hook] Error loading server hook from ${file}:`,
       error
     );
     return {
       middlewares: [],
-      loader: null,
+      serverHook: null,
       dynamic: "auto",
       generateStaticParams: null
     };
   }
-  const middlewares = Array.isArray(
-    mod?.[NAMING.BEFORE_MIDDLEWARES]
-  ) ? mod[NAMING.BEFORE_MIDDLEWARES] : [];
-  const loader = typeof mod?.[NAMING.GET_SERVER_DATA_FN] === "function" ? mod[NAMING.GET_SERVER_DATA_FN] : null;
+  let middlewares = [];
+  const rawMiddlewares = mod?.[NAMING.BEFORE_MIDDLEWARES];
+  if (rawMiddlewares !== void 0) {
+    if (!Array.isArray(rawMiddlewares)) {
+      console.warn(
+        `[framework][server-hook] ${NAMING.BEFORE_MIDDLEWARES} must be an array in ${file}, ignoring invalid value`
+      );
+    } else {
+      for (let i = 0; i < rawMiddlewares.length; i++) {
+        const mw = rawMiddlewares[i];
+        if (typeof mw !== "function") {
+          console.warn(
+            `[framework][server-hook] Middleware at index ${i} in ${NAMING.BEFORE_MIDDLEWARES} is not a function in ${file}, skipping`
+          );
+          continue;
+        }
+        middlewares.push(mw);
+      }
+    }
+  }
+  const serverHook = typeof mod?.[NAMING.GET_SERVER_DATA_FN] === "function" ? mod[NAMING.GET_SERVER_DATA_FN] : null;
   const dynamic = mod?.[NAMING.RENDER_TYPE_CONST] === "force-static" || mod?.[NAMING.RENDER_TYPE_CONST] === "force-dynamic" ? mod.dynamic : "auto";
   const generateStaticParams = typeof mod?.[NAMING.GENERATE_SSG_PARAMS] === "function" ? mod[NAMING.GENERATE_SSG_PARAMS] : null;
   return {
     middlewares,
-    loader,
+    serverHook,
     dynamic,
     generateStaticParams
   };
 }
+function loadLayoutServerHook(layoutFile) {
+  const layoutDir = import_path3.default.dirname(layoutFile);
+  const layoutBasename = import_path3.default.basename(layoutFile, import_path3.default.extname(layoutFile));
+  const serverHookTs = import_path3.default.join(layoutDir, `${layoutBasename}.server.hook.ts`);
+  const serverHookJs = import_path3.default.join(layoutDir, `${layoutBasename}.server.hook.js`);
+  const file = import_fs3.default.existsSync(serverHookTs) ? serverHookTs : import_fs3.default.existsSync(serverHookJs) ? serverHookJs : null;
+  if (!file) {
+    return null;
+  }
+  if (file.endsWith(".ts") || file.endsWith(".tsx")) {
+    try {
+      require("tsx/cjs");
+    } catch (e) {
+    }
+  }
+  try {
+    const mod = require(file);
+    const serverHook = typeof mod?.getServerSideProps === "function" ? mod.getServerSideProps : null;
+    return serverHook;
+  } catch (error) {
+    console.error(
+      `[framework][server-hook] Error loading layout server hook from ${file}:`,
+      error
+    );
+    return null;
+  }
+}
 
 // modules/router/loader-pages.ts
+function validateRoutes(routes, appDir) {
+  const routePatterns = /* @__PURE__ */ new Map();
+  const errors = [];
+  const warnings = [];
+  for (const route of routes) {
+    const existing = routePatterns.get(route.pattern) || [];
+    existing.push(route);
+    routePatterns.set(route.pattern, existing);
+  }
+  for (const [pattern, duplicateRoutes] of routePatterns.entries()) {
+    if (duplicateRoutes.length > 1) {
+      const files = duplicateRoutes.map(
+        (r) => r.pageFile ? import_path4.default.relative(appDir, r.pageFile) : "unknown"
+      ).join(", ");
+      errors.push(
+        `Duplicate route pattern "${pattern}" found in multiple files:
+  ${files}
+  \u{1F4A1} Suggestion: Ensure each route has a unique path pattern`
+      );
+    }
+  }
+  for (const route of routes) {
+    if (!route.pageFile || !import_fs4.default.existsSync(route.pageFile)) {
+      warnings.push(
+        `Route pattern "${route.pattern}" references a missing page file`
+      );
+    }
+  }
+  if (errors.length > 0) {
+    const errorMessage = [
+      "\u274C Route validation failed:",
+      "",
+      ...errors,
+      "",
+      "\u{1F4A1} Please fix the errors above before starting the server."
+    ].join("\n");
+    throw new Error(errorMessage);
+  }
+  if (warnings.length > 0 && process.env.NODE_ENV === "development") {
+    console.warn("\n\u26A0\uFE0F  Route warnings:");
+    warnings.forEach((warning) => console.warn(`  \u2022 ${warning}`));
+    console.warn("");
+  }
+}
 function loadRoutes(appDir) {
   if (!import_fs4.default.existsSync(appDir)) {
     return [];
@@ -335,7 +425,12 @@ function loadRoutes(appDir) {
         currentDir,
         appDir
       );
-      const { middlewares, loader, dynamic, generateStaticParams } = loadLoaderForDir(currentDir);
+      const layoutServerHooks = [];
+      for (const layoutFile of layoutFiles) {
+        const layoutServerHook = loadLayoutServerHook(layoutFile);
+        layoutServerHooks.push(layoutServerHook);
+      }
+      const { middlewares, serverHook, dynamic, generateStaticParams } = loadServerHookForDir(currentDir);
       routes.push({
         pattern: routePath,
         regex,
@@ -345,13 +440,17 @@ function loadRoutes(appDir) {
         pageFile: fullPath,
         layoutFiles,
         middlewares,
-        loader,
+        loader: serverHook,
+        // Keep 'loader' field name for backward compatibility
+        layoutServerHooks,
+        // Server hooks for each layout (same order as layouts)
         dynamic,
         generateStaticParams
       });
     }
   }
   walk(appDir);
+  validateRoutes(routes, appDir);
   return routes;
 }
 
@@ -715,9 +814,12 @@ function writeClientBoostrapManifest(projectRoot) {
   lines.push("");
   lines.push(`import { bootstrapClient } from "@lolyjs/core/runtime"`);
   lines.push("");
-  lines.push(
-    "bootstrapClient(routes as ClientRouteLoaded[], notFoundRoute, errorRoute);"
-  );
+  lines.push(`try {`);
+  lines.push(`  bootstrapClient(routes as ClientRouteLoaded[], notFoundRoute, errorRoute);`);
+  lines.push(`} catch (error) {`);
+  lines.push(`  console.error("[bootstrap] Fatal error during bootstrap:", error);`);
+  lines.push(`  throw error;`);
+  lines.push(`}`);
   import_fs7.default.writeFileSync(manifestPath, lines.join("\n"), "utf-8");
 }
 function writeRoutesManifest({
@@ -864,7 +966,12 @@ function loadRoutesFromManifest(projectRoot) {
       (f) => import_path10.default.join(projectRoot, f)
     );
     const pageDir = import_path10.default.dirname(pageFile);
-    const { middlewares, loader, dynamic, generateStaticParams } = loadLoaderForDir(pageDir);
+    const layoutServerHooks = [];
+    for (const layoutFile of layoutFiles) {
+      const layoutServerHook = loadLayoutServerHook(layoutFile);
+      layoutServerHooks.push(layoutServerHook);
+    }
+    const { middlewares, serverHook, dynamic, generateStaticParams } = loadServerHookForDir(pageDir);
     pageRoutes.push({
       pattern: entry.pattern,
       regex,
@@ -874,7 +981,10 @@ function loadRoutesFromManifest(projectRoot) {
       pageFile,
       layoutFiles,
       middlewares,
-      loader,
+      loader: serverHook,
+      // Keep 'loader' field name for backward compatibility
+      layoutServerHooks,
+      // Server hooks for each layout (same order as layouts)
       dynamic: entry.dynamic ?? dynamic,
       generateStaticParams
     });
@@ -1047,24 +1157,210 @@ function loadWssRoutes(appDir) {
 }
 
 // modules/router/route-loader.ts
+var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".loly",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "coverage",
+  ".vscode",
+  ".idea",
+  ".turbo",
+  ".swc"
+]);
+function getRelevantFiles(appDir, projectRoot) {
+  const files = [];
+  const projectRootNormalized = import_path12.default.resolve(projectRoot);
+  function walk(currentDir) {
+    if (!import_fs10.default.existsSync(currentDir)) {
+      return;
+    }
+    const entries = import_fs10.default.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = import_path12.default.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        if (entry.name.startsWith(".")) {
+          continue;
+        }
+        walk(fullPath);
+      } else {
+        const ext = import_path12.default.extname(entry.name);
+        if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+  walk(projectRootNormalized);
+  return files;
+}
+function hasFilesChanged(appDir, projectRoot, cachedStats) {
+  const currentFiles = getRelevantFiles(appDir, projectRoot);
+  const currentFilesSet = new Set(currentFiles);
+  for (const [filePath] of cachedStats.entries()) {
+    if (!currentFilesSet.has(filePath)) {
+      return true;
+    }
+  }
+  for (const filePath of currentFiles) {
+    if (!import_fs10.default.existsSync(filePath)) {
+      continue;
+    }
+    const stats = import_fs10.default.statSync(filePath);
+    const cachedStat = cachedStats.get(filePath);
+    if (!cachedStat) {
+      return true;
+    }
+    if (stats.mtimeMs !== cachedStat.mtime || stats.size !== cachedStat.size) {
+      return true;
+    }
+  }
+  return false;
+}
+function buildFileStats(files) {
+  const statsMap = /* @__PURE__ */ new Map();
+  for (const filePath of files) {
+    if (import_fs10.default.existsSync(filePath)) {
+      const stats = import_fs10.default.statSync(filePath);
+      statsMap.set(filePath, {
+        mtime: stats.mtimeMs,
+        size: stats.size
+      });
+    }
+  }
+  return statsMap;
+}
 var FilesystemRouteLoader = class {
-  constructor(appDir) {
+  // Maximum cache age in ms (1 second fallback)
+  constructor(appDir, projectRoot = appDir) {
     this.appDir = appDir;
+    this.projectRoot = projectRoot;
+    this.cache = null;
+    this.cacheMaxAge = 1e3;
+    if (this.projectRoot === this.appDir) {
+      let current = import_path12.default.resolve(this.appDir);
+      while (current !== import_path12.default.dirname(current)) {
+        if (import_fs10.default.existsSync(import_path12.default.join(current, "package.json"))) {
+          this.projectRoot = current;
+          break;
+        }
+        current = import_path12.default.dirname(current);
+      }
+    }
+  }
+  /**
+   * Invalidates the cache, forcing a reload on next access.
+   */
+  invalidateCache() {
+    this.cache = null;
+  }
+  /**
+   * Checks if cache is still valid, invalidates if files changed.
+   */
+  ensureCacheValid() {
+    if (!this.cache) {
+      return;
+    }
+    const now = Date.now();
+    if (now - this.cache.timestamp > this.cacheMaxAge) {
+      if (hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats)) {
+        this.cache = null;
+      } else {
+        this.cache.timestamp = now;
+      }
+    }
   }
   loadRoutes() {
-    return loadRoutes(this.appDir);
+    this.ensureCacheValid();
+    if (!this.cache || hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats)) {
+      const routes = loadRoutes(this.appDir);
+      const files = getRelevantFiles(this.appDir, this.projectRoot);
+      const fileStats = buildFileStats(files);
+      this.cache = {
+        routes,
+        apiRoutes: this.cache?.apiRoutes || [],
+        wssRoutes: this.cache?.wssRoutes || [],
+        notFoundRoute: this.cache?.notFoundRoute ?? null,
+        errorRoute: this.cache?.errorRoute ?? null,
+        fileStats,
+        timestamp: Date.now()
+      };
+    }
+    return this.cache.routes;
   }
   loadApiRoutes() {
-    return loadApiRoutes(this.appDir);
+    this.ensureCacheValid();
+    if (!this.cache) {
+      this.loadRoutes();
+    }
+    if (!this.cache) {
+      throw new Error("Failed to initialize route cache");
+    }
+    if (hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats) || this.cache.apiRoutes.length === 0) {
+      const files = getRelevantFiles(this.appDir, this.projectRoot);
+      const fileStats = buildFileStats(files);
+      this.cache.apiRoutes = loadApiRoutes(this.appDir);
+      this.cache.fileStats = fileStats;
+      this.cache.timestamp = Date.now();
+    }
+    return this.cache.apiRoutes;
   }
   loadWssRoutes() {
-    return loadWssRoutes(this.appDir);
+    this.ensureCacheValid();
+    if (!this.cache) {
+      this.loadRoutes();
+    }
+    if (!this.cache) {
+      throw new Error("Failed to initialize route cache");
+    }
+    if (hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats) || this.cache.wssRoutes.length === 0) {
+      const files = getRelevantFiles(this.appDir, this.projectRoot);
+      const fileStats = buildFileStats(files);
+      this.cache.wssRoutes = loadWssRoutes(this.appDir);
+      this.cache.fileStats = fileStats;
+      this.cache.timestamp = Date.now();
+    }
+    return this.cache.wssRoutes;
   }
   loadNotFoundRoute() {
-    return loadNotFoundRouteFromFilesystem(this.appDir);
+    this.ensureCacheValid();
+    if (!this.cache) {
+      this.loadRoutes();
+    }
+    if (!this.cache) {
+      throw new Error("Failed to initialize route cache");
+    }
+    if (hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats) || this.cache.notFoundRoute === void 0) {
+      const files = getRelevantFiles(this.appDir, this.projectRoot);
+      const fileStats = buildFileStats(files);
+      this.cache.notFoundRoute = loadNotFoundRouteFromFilesystem(this.appDir);
+      this.cache.fileStats = fileStats;
+      this.cache.timestamp = Date.now();
+    }
+    return this.cache.notFoundRoute;
   }
   loadErrorRoute() {
-    return loadErrorRouteFromFilesystem(this.appDir);
+    this.ensureCacheValid();
+    if (!this.cache) {
+      this.loadRoutes();
+    }
+    if (!this.cache) {
+      throw new Error("Failed to initialize route cache");
+    }
+    if (hasFilesChanged(this.appDir, this.projectRoot, this.cache.fileStats) || this.cache.errorRoute === void 0) {
+      const files = getRelevantFiles(this.appDir, this.projectRoot);
+      const fileStats = buildFileStats(files);
+      this.cache.errorRoute = loadErrorRouteFromFilesystem(this.appDir);
+      this.cache.fileStats = fileStats;
+      this.cache.timestamp = Date.now();
+    }
+    return this.cache.errorRoute;
   }
   loadRouteChunks() {
     return {};
@@ -1073,27 +1369,67 @@ var FilesystemRouteLoader = class {
 var ManifestRouteLoader = class {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
+    this.cache = {};
+  }
+  /**
+   * Gets the manifest, using cache if available.
+   * The manifest is read once and cached for the lifetime of the loader.
+   */
+  getManifest() {
+    if (this.cache.manifest !== void 0) {
+      return this.cache.manifest;
+    }
+    const manifest = readManifest(this.projectRoot);
+    this.cache.manifest = manifest;
+    return manifest;
   }
   loadRoutes() {
+    if (this.cache.routes) {
+      return this.cache.routes;
+    }
     const { routes } = loadRoutesFromManifest(this.projectRoot);
+    this.cache.routes = routes;
     return routes;
   }
   loadApiRoutes() {
+    if (this.cache.apiRoutes) {
+      return this.cache.apiRoutes;
+    }
     const { apiRoutes } = loadRoutesFromManifest(this.projectRoot);
+    this.cache.apiRoutes = apiRoutes;
     return apiRoutes;
   }
   loadWssRoutes() {
+    if (this.cache.wssRoutes) {
+      return this.cache.wssRoutes;
+    }
     const { wssRoutes } = loadRoutesFromManifest(this.projectRoot);
+    this.cache.wssRoutes = wssRoutes;
     return wssRoutes;
   }
   loadNotFoundRoute() {
-    return loadNotFoundFromManifest(this.projectRoot);
+    if (this.cache.notFoundRoute !== void 0) {
+      return this.cache.notFoundRoute;
+    }
+    const route = loadNotFoundFromManifest(this.projectRoot);
+    this.cache.notFoundRoute = route;
+    return route;
   }
   loadErrorRoute() {
-    return loadErrorFromManifest(this.projectRoot);
+    if (this.cache.errorRoute !== void 0) {
+      return this.cache.errorRoute;
+    }
+    const route = loadErrorFromManifest(this.projectRoot);
+    this.cache.errorRoute = route;
+    return route;
   }
   loadRouteChunks() {
-    return loadChunksFromManifest(this.projectRoot);
+    if (this.cache.routeChunks) {
+      return this.cache.routeChunks;
+    }
+    const chunks = loadChunksFromManifest(this.projectRoot);
+    this.cache.routeChunks = chunks;
+    return chunks;
   }
 };
 function loadNotFoundRouteFromFilesystem(appDir) {
@@ -1128,7 +1464,12 @@ function loadNotFoundRouteFromFilesystem(appDir) {
     notFoundDir,
     appDir
   );
-  const { middlewares, loader, dynamic, generateStaticParams } = loadLoaderForDir(notFoundDir);
+  const layoutServerHooks = [];
+  for (const layoutFile of layoutFiles) {
+    const layoutServerHook = loadLayoutServerHook(layoutFile);
+    layoutServerHooks.push(layoutServerHook);
+  }
+  const { middlewares, serverHook, dynamic, generateStaticParams } = loadServerHookForDir(notFoundDir);
   return {
     pattern: NOT_FOUND_PATTERN,
     regex: new RegExp(`^${NOT_FOUND_PATTERN}/?$`),
@@ -1138,7 +1479,10 @@ function loadNotFoundRouteFromFilesystem(appDir) {
     pageFile: notFoundFile,
     layoutFiles,
     middlewares,
-    loader,
+    loader: serverHook,
+    // Keep 'loader' field name for backward compatibility
+    layoutServerHooks,
+    // Server hooks for each layout (same order as layouts)
     dynamic,
     generateStaticParams
   };
@@ -1169,7 +1513,12 @@ function loadErrorRouteFromFilesystem(appDir) {
     appDir,
     appDir
   );
-  const { middlewares, loader, dynamic, generateStaticParams } = loadLoaderForDir(appDir);
+  const layoutServerHooks = [];
+  for (const layoutFile of layoutFiles) {
+    const layoutServerHook = loadLayoutServerHook(layoutFile);
+    layoutServerHooks.push(layoutServerHook);
+  }
+  const { middlewares, serverHook, dynamic, generateStaticParams } = loadServerHookForDir(appDir);
   return {
     pattern: ERROR_PATTERN,
     regex: new RegExp(`^${ERROR_PATTERN}/?$`),
@@ -1179,7 +1528,10 @@ function loadErrorRouteFromFilesystem(appDir) {
     pageFile: errorFile,
     layoutFiles,
     middlewares,
-    loader,
+    loader: serverHook,
+    // Keep 'loader' field name for backward compatibility
+    layoutServerHooks,
+    // Server hooks for each layout (same order as layouts)
     dynamic,
     generateStaticParams
   };
@@ -1210,7 +1562,8 @@ function loadAliasesFromTsconfig(projectRoot) {
   try {
     tsconfig = JSON.parse(import_fs11.default.readFileSync(tsconfigPath, "utf-8"));
   } catch (err) {
-    console.warn("[framework] Could not read tsconfig.json:", err);
+    console.warn("\u26A0\uFE0F  [framework] Could not read tsconfig.json:", err instanceof Error ? err.message : String(err));
+    console.warn("\u{1F4A1} Using default path aliases. For custom aliases, ensure tsconfig.json is valid.");
     aliases["@app"] = import_path13.default.resolve(projectRoot, "app");
     return aliases;
   }
@@ -1264,7 +1617,7 @@ function copyStaticAssets(projectRoot, outDir) {
     }
   }
 }
-function generateAssetManifest(outDir) {
+function generateAssetManifest(outDir, stats) {
   const manifest = {
     client: {
       js: "client.js",
@@ -1276,27 +1629,128 @@ function generateAssetManifest(outDir) {
     return manifest;
   }
   const files = import_fs11.default.readdirSync(outDir);
-  const clientJsMatch = files.find((f) => /^client\.[\w-]+\.js$/.test(f) || f === "client.js");
-  if (clientJsMatch) {
-    manifest.client.js = clientJsMatch;
+  if (stats) {
+    try {
+      const statsJson = stats.toJson({
+        all: false,
+        entrypoints: true,
+        assets: true,
+        chunks: true,
+        chunkRelations: true
+        // Include chunk dependencies
+      });
+      const clientEntrypoint = statsJson.entrypoints?.client;
+      if (clientEntrypoint?.assets) {
+        const clientJsFiles = clientEntrypoint.assets.map((asset) => typeof asset === "string" ? asset : asset.name).filter((name) => name.endsWith(".js"));
+        if (statsJson.chunks && clientEntrypoint.chunks) {
+          const entrypointChunkIds = new Set(
+            Array.isArray(clientEntrypoint.chunks) ? clientEntrypoint.chunks : [clientEntrypoint.chunks]
+          );
+          const dependencyChunks = [];
+          for (const chunk of statsJson.chunks) {
+            if (chunk.id && entrypointChunkIds.has(chunk.id)) {
+              if (chunk.files) {
+                const jsFiles = chunk.files.filter((f) => f.endsWith(".js")).filter((f) => !clientJsFiles.includes(f));
+                dependencyChunks.push(...jsFiles);
+              }
+            }
+          }
+          const visitedChunkIds = new Set(entrypointChunkIds);
+          const chunksToCheck = Array.from(entrypointChunkIds);
+          while (chunksToCheck.length > 0) {
+            const chunkId = chunksToCheck.shift();
+            if (!chunkId) continue;
+            const chunk = statsJson.chunks?.find((c) => c.id === chunkId);
+            if (chunk?.children) {
+              const children = Array.isArray(chunk.children) ? chunk.children : [chunk.children];
+              for (const childId of children) {
+                if (!visitedChunkIds.has(childId)) {
+                  visitedChunkIds.add(childId);
+                  chunksToCheck.push(childId);
+                  const childChunk = statsJson.chunks?.find((c) => c.id === childId);
+                  if (childChunk?.files) {
+                    const jsFiles = childChunk.files.filter((f) => f.endsWith(".js")).filter((f) => !clientJsFiles.includes(f) && !dependencyChunks.includes(f));
+                    dependencyChunks.push(...jsFiles);
+                  }
+                }
+              }
+            }
+          }
+          if (dependencyChunks.length > 0) {
+            clientJsFiles.splice(-1, 0, ...dependencyChunks);
+          }
+        }
+        if (clientJsFiles.length > 0) {
+          manifest.entrypoints = {
+            client: clientJsFiles
+          };
+          manifest.client.js = clientJsFiles[clientJsFiles.length - 1];
+          const clientCssFiles = clientEntrypoint.assets.map((asset) => typeof asset === "string" ? asset : asset.name).filter((name) => name.endsWith(".css"));
+          if (clientCssFiles.length > 0) {
+            manifest.client.css = clientCssFiles[0];
+          }
+        }
+      }
+    } catch (err) {
+      console.warn("[framework] Failed to extract entrypoints from stats, falling back to file scanning:", err);
+    }
+  }
+  if (!manifest.client.js) {
+    const clientJsMatch = files.find((f) => /^client\.[\w-]+\.js$/.test(f) || f === "client.js");
+    if (clientJsMatch) {
+      manifest.client.js = clientJsMatch;
+    }
   }
-  const clientCssMatch = files.find((f) => /^client\.[\w-]+\.css$/.test(f) || f === "client.css");
-  if (clientCssMatch) {
-    manifest.client.css = clientCssMatch;
+  if (!manifest.client.css) {
+    const clientCssMatch = files.find((f) => /^client\.[\w-]+\.css$/.test(f) || f === "client.css");
+    if (clientCssMatch) {
+      manifest.client.css = clientCssMatch;
+    }
   }
+  const sharedChunksToAdd = [];
   for (const file of files) {
     if (!file.endsWith(".js")) continue;
     if (file === manifest.client.js) continue;
+    if (manifest.entrypoints?.client?.includes(file)) continue;
     const routeMatch = file.match(/^(route-[^.]+)(\.[\w-]+)?\.js$/);
     if (routeMatch) {
       const chunkName = routeMatch[1];
       manifest.chunks[chunkName] = file;
       continue;
     }
+    const vendorMatch = file.match(/^(vendor)(\.[\w-]+)?\.js$/);
+    if (vendorMatch) {
+      const chunkName = vendorMatch[1];
+      manifest.chunks[chunkName] = file;
+      sharedChunksToAdd.push(file);
+      continue;
+    }
+    const vendorCommonsMatch = file.match(/^(vendor-commons)(\.[\w-]+)?\.js$/);
+    if (vendorCommonsMatch) {
+      const chunkName = vendorCommonsMatch[1];
+      manifest.chunks[chunkName] = file;
+      sharedChunksToAdd.push(file);
+      continue;
+    }
     const numericMatch = file.match(/^(\d+)(\.[\w-]+)?\.js$/);
     if (numericMatch) {
       const chunkName = numericMatch[1];
       manifest.chunks[chunkName] = file;
+      sharedChunksToAdd.push(file);
+      continue;
+    }
+  }
+  if (sharedChunksToAdd.length > 0 && manifest.entrypoints?.client) {
+    const entrypoints = manifest.entrypoints.client;
+    const mainEntry = entrypoints[entrypoints.length - 1];
+    const uniqueShared = sharedChunksToAdd.filter((f) => !entrypoints.includes(f));
+    entrypoints.splice(-1, 0, ...uniqueShared);
+    if (entrypoints[entrypoints.length - 1] !== mainEntry) {
+      const mainIndex = entrypoints.indexOf(mainEntry);
+      if (mainIndex >= 0) {
+        entrypoints.splice(mainIndex, 1);
+      }
+      entrypoints.push(mainEntry);
     }
   }
   return manifest;
@@ -1336,9 +1790,7 @@ function createClientConfig(projectRoot, mode) {
   const outDir = import_path14.default.join(buildDir, "client");
   const envPath2 = import_path14.default.join(projectRoot, ".env");
   if (import_fs12.default.existsSync(envPath2)) {
-    import_dotenv.default.config({
-      path: envPath2
-    });
+    import_dotenv.default.config({ path: envPath2 });
   }
   const publicEnv = {};
   for (const [key, value] of Object.entries(process.env)) {
@@ -1397,14 +1849,57 @@ function createClientConfig(projectRoot, mode) {
     },
     plugins: [
       new import_core.rspack.DefinePlugin({
-        // Always define NODE_ENV, using mode as fallback if not set
-        "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || mode),
+        // Use mode directly to ensure development mode is correctly set
+        // This replaces process.env.NODE_ENV in the client bundle with the literal string value
+        "process.env.NODE_ENV": JSON.stringify(mode),
         ...publicEnv
       }),
       new import_core.rspack.CssExtractRspackPlugin({
         filename: mode === "production" ? "client.[contenthash].css" : "client.css"
       })
     ],
+    optimization: mode === "production" ? {
+      usedExports: true,
+      sideEffects: false,
+      // More aggressive tree shaking - assume no side effects
+      providedExports: true,
+      concatenateModules: true,
+      // Better for tree shaking
+      minimize: true,
+      removeEmptyChunks: true,
+      mergeDuplicateChunks: true,
+      // Improved code splitting: separate vendor chunks for better caching
+      splitChunks: {
+        chunks: "all",
+        cacheGroups: {
+          // Separate React/React-DOM into dedicated vendor chunk
+          // This improves caching: React rarely changes, so users don't need to re-download it
+          vendor: {
+            test: /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/,
+            name: "vendor",
+            priority: 30,
+            enforce: true,
+            // Force separation even if only used once
+            reuseExistingChunk: true
+          },
+          // Other node_modules dependencies in a separate chunk
+          vendorCommons: {
+            test: /[\\/]node_modules[\\/](?!(react|react-dom|scheduler)[\\/])/,
+            name: "vendor-commons",
+            priority: 10,
+            minChunks: 2,
+            // Only create if used in 2+ chunks
+            reuseExistingChunk: true
+          },
+          // Default: shared application code (not in node_modules)
+          default: {
+            minChunks: 2,
+            priority: 5,
+            reuseExistingChunk: true
+          }
+        }
+      }
+    } : void 0,
     infrastructureLogging: {
       level: "error"
     },
@@ -1433,7 +1928,13 @@ function startClientBundler(projectRoot, mode = "development") {
   });
   compiler.watch({}, (err, stats) => {
     if (err) {
-      console.error("[framework][client] Rspack error:", err);
+      console.error("\n\u274C [framework][client] Rspack compilation error:");
+      console.error(err);
+      console.error("\n\u{1F4A1} Suggestions:");
+      console.error("  \u2022 Check for syntax errors in your code");
+      console.error("  \u2022 Verify all imports are correct");
+      console.error("  \u2022 Ensure all dependencies are installed");
+      console.error("  \u2022 Try deleting .loly folder and rebuilding\n");
       isBuilding = false;
       lastBuildTime = Date.now();
       if (buildResolve) {
@@ -1444,17 +1945,20 @@ function startClientBundler(projectRoot, mode = "development") {
       return;
     }
     if (!stats) {
+      console.warn("\u26A0\uFE0F  [framework][client] Build completed but no stats available");
       isBuilding = false;
       lastBuildTime = Date.now();
       return;
     }
     if (stats.hasErrors()) {
-      console.error(
-        "[framework][client] Build with errors:\n",
-        stats.toString("errors-only")
-      );
+      console.error("\n\u274C [framework][client] Build failed with errors:\n");
+      console.error(stats.toString("errors-only"));
+      console.error("\n\u{1F4A1} Common fixes:");
+      console.error("  \u2022 Fix syntax errors shown above");
+      console.error("  \u2022 Check for missing imports or dependencies");
+      console.error("  \u2022 Verify TypeScript types are correct\n");
     } else {
-      console.log("[framework][client] \u2713 Client bundle rebuilt successfully");
+      console.log("\u2705 [framework][client] Client bundle rebuilt successfully");
     }
     isBuilding = false;
     lastBuildTime = Date.now();
@@ -1489,23 +1993,33 @@ function buildClientBundle(projectRoot) {
       compiler.close(() => {
       });
       if (err) {
-        console.error("[framework][client] Build error:", err);
+        console.error("\n\u274C [framework][client] Production build error:");
+        console.error(err);
+        console.error("\n\u{1F4A1} Suggestions:");
+        console.error("  \u2022 Check for syntax errors in your code");
+        console.error("  \u2022 Verify all imports are correct");
+        console.error("  \u2022 Ensure all dependencies are installed");
+        console.error("  \u2022 Review the error details above\n");
         return reject(err);
       }
       if (!stats) {
-        const error = new Error("No stats from Rspack");
-        console.error("[framework][client] Build error:", error);
+        const error = new Error("No stats from Rspack - build may have failed silently");
+        console.error("\n\u274C [framework][client] Build error:", error.message);
+        console.error("\u{1F4A1} Try rebuilding or check Rspack configuration\n");
         return reject(error);
       }
       if (stats.hasErrors()) {
-        console.error(
-          "[framework][client] Build with errors:\n",
-          stats.toString("errors-only")
-        );
-        return reject(new Error("Client build failed"));
+        console.error("\n\u274C [framework][client] Production build failed:\n");
+        console.error(stats.toString("errors-only"));
+        console.error("\n\u{1F4A1} Common fixes:");
+        console.error("  \u2022 Fix syntax errors shown above");
+        console.error("  \u2022 Check for missing imports or dependencies");
+        console.error("  \u2022 Verify TypeScript types are correct");
+        console.error("  \u2022 Review build configuration\n");
+        return reject(new Error("Client build failed - see errors above"));
       }
       copyStaticAssets(projectRoot, outDir);
-      const assetManifest = generateAssetManifest(outDir);
+      const assetManifest = generateAssetManifest(outDir, stats);
       const manifestPath = import_path15.default.join(projectRoot, BUILD_FOLDER_NAME, "asset-manifest.json");
       import_fs13.default.writeFileSync(manifestPath, JSON.stringify(assetManifest, null, 2), "utf-8");
       resolve3({ outDir });
@@ -1589,7 +2103,7 @@ var ReaddirpStream = class extends import_node_stream.Readable {
     this._directoryFilter = normalizeFilter(opts.directoryFilter);
     const statMethod = opts.lstat ? import_promises.lstat : import_promises.stat;
     if (wantBigintFsStats) {
-      this._stat = (path25) => statMethod(path25, { bigint: true });
+      this._stat = (path28) => statMethod(path28, { bigint: true });
     } else {
       this._stat = statMethod;
     }
@@ -1614,8 +2128,8 @@ var ReaddirpStream = class extends import_node_stream.Readable {
         const par = this.parent;
         const fil = par && par.files;
         if (fil && fil.length > 0) {
-          const { path: path25, depth } = par;
-          const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path25));
+          const { path: path28, depth } = par;
+          const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path28));
           const awaited = await Promise.all(slice);
           for (const entry of awaited) {
             if (!entry)
@@ -1655,20 +2169,20 @@ var ReaddirpStream = class extends import_node_stream.Readable {
       this.reading = false;
     }
   }
-  async _exploreDir(path25, depth) {
+  async _exploreDir(path28, depth) {
     let files;
     try {
-      files = await (0, import_promises.readdir)(path25, this._rdOptions);
+      files = await (0, import_promises.readdir)(path28, this._rdOptions);
     } catch (error) {
       this._onError(error);
     }
-    return { files, depth, path: path25 };
+    return { files, depth, path: path28 };
   }
-  async _formatEntry(dirent, path25) {
+  async _formatEntry(dirent, path28) {
     let entry;
     const basename3 = this._isDirent ? dirent.name : dirent;
     try {
-      const fullPath = (0, import_node_path.resolve)((0, import_node_path.join)(path25, basename3));
+      const fullPath = (0, import_node_path.resolve)((0, import_node_path.join)(path28, basename3));
       entry = { path: (0, import_node_path.relative)(this._root, fullPath), fullPath, basename: basename3 };
       entry[this._statsProp] = this._isDirent ? dirent : await this._stat(fullPath);
     } catch (err) {
@@ -2068,16 +2582,16 @@ var delFromSet = (main, prop, item) => {
 };
 var isEmptySet = (val) => val instanceof Set ? val.size === 0 : !val;
 var FsWatchInstances = /* @__PURE__ */ new Map();
-function createFsWatchInstance(path25, options, listener, errHandler, emitRaw) {
+function createFsWatchInstance(path28, options, listener, errHandler, emitRaw) {
   const handleEvent = (rawEvent, evPath) => {
-    listener(path25);
-    emitRaw(rawEvent, evPath, { watchedPath: path25 });
-    if (evPath && path25 !== evPath) {
-      fsWatchBroadcast(sysPath.resolve(path25, evPath), KEY_LISTENERS, sysPath.join(path25, evPath));
+    listener(path28);
+    emitRaw(rawEvent, evPath, { watchedPath: path28 });
+    if (evPath && path28 !== evPath) {
+      fsWatchBroadcast(sysPath.resolve(path28, evPath), KEY_LISTENERS, sysPath.join(path28, evPath));
     }
   };
   try {
-    return (0, import_fs14.watch)(path25, {
+    return (0, import_fs14.watch)(path28, {
       persistent: options.persistent
     }, handleEvent);
   } catch (error) {
@@ -2093,12 +2607,12 @@ var fsWatchBroadcast = (fullPath, listenerType, val1, val2, val3) => {
     listener(val1, val2, val3);
   });
 };
-var setFsWatchListener = (path25, fullPath, options, handlers) => {
+var setFsWatchListener = (path28, fullPath, options, handlers) => {
   const { listener, errHandler, rawEmitter } = handlers;
   let cont = FsWatchInstances.get(fullPath);
   let watcher;
   if (!options.persistent) {
-    watcher = createFsWatchInstance(path25, options, listener, errHandler, rawEmitter);
+    watcher = createFsWatchInstance(path28, options, listener, errHandler, rawEmitter);
     if (!watcher)
       return;
     return watcher.close.bind(watcher);
@@ -2109,7 +2623,7 @@ var setFsWatchListener = (path25, fullPath, options, handlers) => {
     addAndConvert(cont, KEY_RAW, rawEmitter);
   } else {
     watcher = createFsWatchInstance(
-      path25,
+      path28,
       options,
       fsWatchBroadcast.bind(null, fullPath, KEY_LISTENERS),
       errHandler,
@@ -2124,7 +2638,7 @@ var setFsWatchListener = (path25, fullPath, options, handlers) => {
         cont.watcherUnusable = true;
       if (isWindows && error.code === "EPERM") {
         try {
-          const fd = await (0, import_promises2.open)(path25, "r");
+          const fd = await (0, import_promises2.open)(path28, "r");
           await fd.close();
           broadcastErr(error);
         } catch (err) {
@@ -2155,7 +2669,7 @@ var setFsWatchListener = (path25, fullPath, options, handlers) => {
   };
 };
 var FsWatchFileInstances = /* @__PURE__ */ new Map();
-var setFsWatchFileListener = (path25, fullPath, options, handlers) => {
+var setFsWatchFileListener = (path28, fullPath, options, handlers) => {
   const { listener, rawEmitter } = handlers;
   let cont = FsWatchFileInstances.get(fullPath);
   const copts = cont && cont.options;
@@ -2177,7 +2691,7 @@ var setFsWatchFileListener = (path25, fullPath, options, handlers) => {
         });
         const currmtime = curr.mtimeMs;
         if (curr.size !== prev.size || currmtime > prev.mtimeMs || currmtime === 0) {
-          foreach(cont.listeners, (listener2) => listener2(path25, curr));
+          foreach(cont.listeners, (listener2) => listener2(path28, curr));
         }
       })
     };
@@ -2205,13 +2719,13 @@ var NodeFsHandler = class {
    * @param listener on fs change
    * @returns closer for the watcher instance
    */
-  _watchWithNodeFs(path25, listener) {
+  _watchWithNodeFs(path28, listener) {
     const opts = this.fsw.options;
-    const directory = sysPath.dirname(path25);
-    const basename3 = sysPath.basename(path25);
+    const directory = sysPath.dirname(path28);
+    const basename3 = sysPath.basename(path28);
     const parent = this.fsw._getWatchedDir(directory);
     parent.add(basename3);
-    const absolutePath = sysPath.resolve(path25);
+    const absolutePath = sysPath.resolve(path28);
     const options = {
       persistent: opts.persistent
     };
@@ -2221,12 +2735,12 @@ var NodeFsHandler = class {
     if (opts.usePolling) {
       const enableBin = opts.interval !== opts.binaryInterval;
       options.interval = enableBin && isBinaryPath(basename3) ? opts.binaryInterval : opts.interval;
-      closer = setFsWatchFileListener(path25, absolutePath, options, {
+      closer = setFsWatchFileListener(path28, absolutePath, options, {
         listener,
         rawEmitter: this.fsw._emitRaw
       });
     } else {
-      closer = setFsWatchListener(path25, absolutePath, options, {
+      closer = setFsWatchListener(path28, absolutePath, options, {
         listener,
         errHandler: this._boundHandleError,
         rawEmitter: this.fsw._emitRaw
@@ -2248,7 +2762,7 @@ var NodeFsHandler = class {
     let prevStats = stats;
     if (parent.has(basename3))
       return;
-    const listener = async (path25, newStats) => {
+    const listener = async (path28, newStats) => {
       if (!this.fsw._throttle(THROTTLE_MODE_WATCH, file, 5))
         return;
       if (!newStats || newStats.mtimeMs === 0) {
@@ -2262,11 +2776,11 @@ var NodeFsHandler = class {
             this.fsw._emit(EV.CHANGE, file, newStats2);
           }
           if ((isMacos || isLinux || isFreeBSD) && prevStats.ino !== newStats2.ino) {
-            this.fsw._closeFile(path25);
+            this.fsw._closeFile(path28);
             prevStats = newStats2;
             const closer2 = this._watchWithNodeFs(file, listener);
             if (closer2)
-              this.fsw._addPathCloser(path25, closer2);
+              this.fsw._addPathCloser(path28, closer2);
           } else {
             prevStats = newStats2;
           }
@@ -2298,7 +2812,7 @@ var NodeFsHandler = class {
    * @param item basename of this item
    * @returns true if no more processing is needed for this entry.
    */
-  async _handleSymlink(entry, directory, path25, item) {
+  async _handleSymlink(entry, directory, path28, item) {
     if (this.fsw.closed) {
       return;
     }
@@ -2308,7 +2822,7 @@ var NodeFsHandler = class {
       this.fsw._incrReadyCount();
       let linkPath;
       try {
-        linkPath = await (0, import_promises2.realpath)(path25);
+        linkPath = await (0, import_promises2.realpath)(path28);
       } catch (e) {
         this.fsw._emitReady();
         return true;
@@ -2318,12 +2832,12 @@ var NodeFsHandler = class {
       if (dir.has(item)) {
         if (this.fsw._symlinkPaths.get(full) !== linkPath) {
           this.fsw._symlinkPaths.set(full, linkPath);
-          this.fsw._emit(EV.CHANGE, path25, entry.stats);
+          this.fsw._emit(EV.CHANGE, path28, entry.stats);
         }
       } else {
         dir.add(item);
         this.fsw._symlinkPaths.set(full, linkPath);
-        this.fsw._emit(EV.ADD, path25, entry.stats);
+        this.fsw._emit(EV.ADD, path28, entry.stats);
       }
       this.fsw._emitReady();
       return true;
@@ -2352,9 +2866,9 @@ var NodeFsHandler = class {
         return;
       }
       const item = entry.path;
-      let path25 = sysPath.join(directory, item);
+      let path28 = sysPath.join(directory, item);
       current.add(item);
-      if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path25, item)) {
+      if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path28, item)) {
         return;
       }
       if (this.fsw.closed) {
@@ -2363,8 +2877,8 @@ var NodeFsHandler = class {
       }
       if (item === target || !target && !previous.has(item)) {
         this.fsw._incrReadyCount();
-        path25 = sysPath.join(dir, sysPath.relative(dir, path25));
-        this._addToNodeFs(path25, initialAdd, wh, depth + 1);
+        path28 = sysPath.join(dir, sysPath.relative(dir, path28));
+        this._addToNodeFs(path28, initialAdd, wh, depth + 1);
       }
     }).on(EV.ERROR, this._boundHandleError);
     return new Promise((resolve3, reject) => {
@@ -2433,13 +2947,13 @@ var NodeFsHandler = class {
    * @param depth Child path actually targeted for watch
    * @param target Child path actually targeted for watch
    */
-  async _addToNodeFs(path25, initialAdd, priorWh, depth, target) {
+  async _addToNodeFs(path28, initialAdd, priorWh, depth, target) {
     const ready = this.fsw._emitReady;
-    if (this.fsw._isIgnored(path25) || this.fsw.closed) {
+    if (this.fsw._isIgnored(path28) || this.fsw.closed) {
       ready();
       return false;
     }
-    const wh = this.fsw._getWatchHelpers(path25);
+    const wh = this.fsw._getWatchHelpers(path28);
     if (priorWh) {
       wh.filterPath = (entry) => priorWh.filterPath(entry);
       wh.filterDir = (entry) => priorWh.filterDir(entry);
@@ -2455,8 +2969,8 @@ var NodeFsHandler = class {
       const follow = this.fsw.options.followSymlinks;
       let closer;
       if (stats.isDirectory()) {
-        const absPath = sysPath.resolve(path25);
-        const targetPath = follow ? await (0, import_promises2.realpath)(path25) : path25;
+        const absPath = sysPath.resolve(path28);
+        const targetPath = follow ? await (0, import_promises2.realpath)(path28) : path28;
         if (this.fsw.closed)
           return;
         closer = await this._handleDir(wh.watchPath, stats, initialAdd, depth, target, wh, targetPath);
@@ -2466,29 +2980,29 @@ var NodeFsHandler = class {
           this.fsw._symlinkPaths.set(absPath, targetPath);
         }
       } else if (stats.isSymbolicLink()) {
-        const targetPath = follow ? await (0, import_promises2.realpath)(path25) : path25;
+        const targetPath = follow ? await (0, import_promises2.realpath)(path28) : path28;
         if (this.fsw.closed)
           return;
         const parent = sysPath.dirname(wh.watchPath);
         this.fsw._getWatchedDir(parent).add(wh.watchPath);
         this.fsw._emit(EV.ADD, wh.watchPath, stats);
-        closer = await this._handleDir(parent, stats, initialAdd, depth, path25, wh, targetPath);
+        closer = await this._handleDir(parent, stats, initialAdd, depth, path28, wh, targetPath);
         if (this.fsw.closed)
           return;
         if (targetPath !== void 0) {
-          this.fsw._symlinkPaths.set(sysPath.resolve(path25), targetPath);
+          this.fsw._symlinkPaths.set(sysPath.resolve(path28), targetPath);
         }
       } else {
         closer = this._handleFile(wh.watchPath, stats, initialAdd);
       }
       ready();
       if (closer)
-        this.fsw._addPathCloser(path25, closer);
+        this.fsw._addPathCloser(path28, closer);
       return false;
     } catch (error) {
       if (this.fsw._handleError(error)) {
         ready();
-        return path25;
+        return path28;
       }
     }
   }
@@ -2531,26 +3045,26 @@ function createPattern(matcher) {
   }
   return () => false;
 }
-function normalizePath(path25) {
-  if (typeof path25 !== "string")
+function normalizePath(path28) {
+  if (typeof path28 !== "string")
     throw new Error("string expected");
-  path25 = sysPath2.normalize(path25);
-  path25 = path25.replace(/\\/g, "/");
+  path28 = sysPath2.normalize(path28);
+  path28 = path28.replace(/\\/g, "/");
   let prepend = false;
-  if (path25.startsWith("//"))
+  if (path28.startsWith("//"))
     prepend = true;
   const DOUBLE_SLASH_RE2 = /\/\//;
-  while (path25.match(DOUBLE_SLASH_RE2))
-    path25 = path25.replace(DOUBLE_SLASH_RE2, "/");
+  while (path28.match(DOUBLE_SLASH_RE2))
+    path28 = path28.replace(DOUBLE_SLASH_RE2, "/");
   if (prepend)
-    path25 = "/" + path25;
-  return path25;
+    path28 = "/" + path28;
+  return path28;
 }
 function matchPatterns(patterns, testString, stats) {
-  const path25 = normalizePath(testString);
+  const path28 = normalizePath(testString);
   for (let index = 0; index < patterns.length; index++) {
     const pattern = patterns[index];
-    if (pattern(path25, stats)) {
+    if (pattern(path28, stats)) {
       return true;
     }
   }
@@ -2590,19 +3104,19 @@ var toUnix = (string) => {
   }
   return str;
 };
-var normalizePathToUnix = (path25) => toUnix(sysPath2.normalize(toUnix(path25)));
-var normalizeIgnored = (cwd = "") => (path25) => {
-  if (typeof path25 === "string") {
-    return normalizePathToUnix(sysPath2.isAbsolute(path25) ? path25 : sysPath2.join(cwd, path25));
+var normalizePathToUnix = (path28) => toUnix(sysPath2.normalize(toUnix(path28)));
+var normalizeIgnored = (cwd = "") => (path28) => {
+  if (typeof path28 === "string") {
+    return normalizePathToUnix(sysPath2.isAbsolute(path28) ? path28 : sysPath2.join(cwd, path28));
   } else {
-    return path25;
+    return path28;
   }
 };
-var getAbsolutePath = (path25, cwd) => {
-  if (sysPath2.isAbsolute(path25)) {
-    return path25;
+var getAbsolutePath = (path28, cwd) => {
+  if (sysPath2.isAbsolute(path28)) {
+    return path28;
   }
-  return sysPath2.join(cwd, path25);
+  return sysPath2.join(cwd, path28);
 };
 var EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
 var DirEntry = class {
@@ -2657,10 +3171,10 @@ var DirEntry = class {
 var STAT_METHOD_F = "stat";
 var STAT_METHOD_L = "lstat";
 var WatchHelper = class {
-  constructor(path25, follow, fsw) {
+  constructor(path28, follow, fsw) {
     this.fsw = fsw;
-    const watchPath = path25;
-    this.path = path25 = path25.replace(REPLACER_RE, "");
+    const watchPath = path28;
+    this.path = path28 = path28.replace(REPLACER_RE, "");
     this.watchPath = watchPath;
     this.fullWatchPath = sysPath2.resolve(watchPath);
     this.dirParts = [];
@@ -2782,20 +3296,20 @@ var FSWatcher = class extends import_events.EventEmitter {
     this._closePromise = void 0;
     let paths = unifyPaths(paths_);
     if (cwd) {
-      paths = paths.map((path25) => {
-        const absPath = getAbsolutePath(path25, cwd);
+      paths = paths.map((path28) => {
+        const absPath = getAbsolutePath(path28, cwd);
         return absPath;
       });
     }
-    paths.forEach((path25) => {
-      this._removeIgnoredPath(path25);
+    paths.forEach((path28) => {
+      this._removeIgnoredPath(path28);
     });
     this._userIgnored = void 0;
     if (!this._readyCount)
       this._readyCount = 0;
     this._readyCount += paths.length;
-    Promise.all(paths.map(async (path25) => {
-      const res = await this._nodeFsHandler._addToNodeFs(path25, !_internal, void 0, 0, _origAdd);
+    Promise.all(paths.map(async (path28) => {
+      const res = await this._nodeFsHandler._addToNodeFs(path28, !_internal, void 0, 0, _origAdd);
       if (res)
         this._emitReady();
       return res;
@@ -2817,17 +3331,17 @@ var FSWatcher = class extends import_events.EventEmitter {
       return this;
     const paths = unifyPaths(paths_);
     const { cwd } = this.options;
-    paths.forEach((path25) => {
-      if (!sysPath2.isAbsolute(path25) && !this._closers.has(path25)) {
+    paths.forEach((path28) => {
+      if (!sysPath2.isAbsolute(path28) && !this._closers.has(path28)) {
         if (cwd)
-          path25 = sysPath2.join(cwd, path25);
-        path25 = sysPath2.resolve(path25);
+          path28 = sysPath2.join(cwd, path28);
+        path28 = sysPath2.resolve(path28);
       }
-      this._closePath(path25);
-      this._addIgnoredPath(path25);
-      if (this._watched.has(path25)) {
+      this._closePath(path28);
+      this._addIgnoredPath(path28);
+      if (this._watched.has(path28)) {
         this._addIgnoredPath({
-          path: path25,
+          path: path28,
           recursive: true
         });
       }
@@ -2891,38 +3405,38 @@ var FSWatcher = class extends import_events.EventEmitter {
    * @param stats arguments to be passed with event
    * @returns the error if defined, otherwise the value of the FSWatcher instance's `closed` flag
    */
-  async _emit(event, path25, stats) {
+  async _emit(event, path28, stats) {
     if (this.closed)
       return;
     const opts = this.options;
     if (isWindows)
-      path25 = sysPath2.normalize(path25);
+      path28 = sysPath2.normalize(path28);
     if (opts.cwd)
-      path25 = sysPath2.relative(opts.cwd, path25);
-    const args = [path25];
+      path28 = sysPath2.relative(opts.cwd, path28);
+    const args = [path28];
     if (stats != null)
       args.push(stats);
     const awf = opts.awaitWriteFinish;
     let pw;
-    if (awf && (pw = this._pendingWrites.get(path25))) {
+    if (awf && (pw = this._pendingWrites.get(path28))) {
       pw.lastChange = /* @__PURE__ */ new Date();
       return this;
     }
     if (opts.atomic) {
       if (event === EVENTS.UNLINK) {
-        this._pendingUnlinks.set(path25, [event, ...args]);
+        this._pendingUnlinks.set(path28, [event, ...args]);
         setTimeout(() => {
-          this._pendingUnlinks.forEach((entry, path26) => {
+          this._pendingUnlinks.forEach((entry, path29) => {
             this.emit(...entry);
             this.emit(EVENTS.ALL, ...entry);
-            this._pendingUnlinks.delete(path26);
+            this._pendingUnlinks.delete(path29);
           });
         }, typeof opts.atomic === "number" ? opts.atomic : 100);
         return this;
       }
-      if (event === EVENTS.ADD && this._pendingUnlinks.has(path25)) {
+      if (event === EVENTS.ADD && this._pendingUnlinks.has(path28)) {
         event = EVENTS.CHANGE;
-        this._pendingUnlinks.delete(path25);
+        this._pendingUnlinks.delete(path28);
       }
     }
     if (awf && (event === EVENTS.ADD || event === EVENTS.CHANGE) && this._readyEmitted) {
@@ -2940,16 +3454,16 @@ var FSWatcher = class extends import_events.EventEmitter {
           this.emitWithAll(event, args);
         }
       };
-      this._awaitWriteFinish(path25, awf.stabilityThreshold, event, awfEmit);
+      this._awaitWriteFinish(path28, awf.stabilityThreshold, event, awfEmit);
       return this;
     }
     if (event === EVENTS.CHANGE) {
-      const isThrottled = !this._throttle(EVENTS.CHANGE, path25, 50);
+      const isThrottled = !this._throttle(EVENTS.CHANGE, path28, 50);
       if (isThrottled)
         return this;
     }
     if (opts.alwaysStat && stats === void 0 && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
-      const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path25) : path25;
+      const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path28) : path28;
       let stats2;
       try {
         stats2 = await (0, import_promises3.stat)(fullPath);
@@ -2980,23 +3494,23 @@ var FSWatcher = class extends import_events.EventEmitter {
    * @param timeout duration of time to suppress duplicate actions
    * @returns tracking object or false if action should be suppressed
    */
-  _throttle(actionType, path25, timeout) {
+  _throttle(actionType, path28, timeout) {
     if (!this._throttled.has(actionType)) {
       this._throttled.set(actionType, /* @__PURE__ */ new Map());
     }
     const action = this._throttled.get(actionType);
     if (!action)
       throw new Error("invalid throttle");
-    const actionPath = action.get(path25);
+    const actionPath = action.get(path28);
     if (actionPath) {
       actionPath.count++;
       return false;
     }
     let timeoutObject;
     const clear = () => {
-      const item = action.get(path25);
+      const item = action.get(path28);
       const count = item ? item.count : 0;
-      action.delete(path25);
+      action.delete(path28);
       clearTimeout(timeoutObject);
       if (item)
         clearTimeout(item.timeoutObject);
@@ -3004,7 +3518,7 @@ var FSWatcher = class extends import_events.EventEmitter {
     };
     timeoutObject = setTimeout(clear, timeout);
     const thr = { timeoutObject, clear, count: 0 };
-    action.set(path25, thr);
+    action.set(path28, thr);
     return thr;
   }
   _incrReadyCount() {
@@ -3018,44 +3532,44 @@ var FSWatcher = class extends import_events.EventEmitter {
    * @param event
    * @param awfEmit Callback to be called when ready for event to be emitted.
    */
-  _awaitWriteFinish(path25, threshold, event, awfEmit) {
+  _awaitWriteFinish(path28, threshold, event, awfEmit) {
     const awf = this.options.awaitWriteFinish;
     if (typeof awf !== "object")
       return;
     const pollInterval = awf.pollInterval;
     let timeoutHandler;
-    let fullPath = path25;
-    if (this.options.cwd && !sysPath2.isAbsolute(path25)) {
-      fullPath = sysPath2.join(this.options.cwd, path25);
+    let fullPath = path28;
+    if (this.options.cwd && !sysPath2.isAbsolute(path28)) {
+      fullPath = sysPath2.join(this.options.cwd, path28);
     }
     const now = /* @__PURE__ */ new Date();
     const writes = this._pendingWrites;
     function awaitWriteFinishFn(prevStat) {
       (0, import_fs15.stat)(fullPath, (err, curStat) => {
-        if (err || !writes.has(path25)) {
+        if (err || !writes.has(path28)) {
           if (err && err.code !== "ENOENT")
             awfEmit(err);
           return;
         }
         const now2 = Number(/* @__PURE__ */ new Date());
         if (prevStat && curStat.size !== prevStat.size) {
-          writes.get(path25).lastChange = now2;
+          writes.get(path28).lastChange = now2;
         }
-        const pw = writes.get(path25);
+        const pw = writes.get(path28);
         const df = now2 - pw.lastChange;
         if (df >= threshold) {
-          writes.delete(path25);
+          writes.delete(path28);
           awfEmit(void 0, curStat);
         } else {
           timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval, curStat);
         }
       });
     }
-    if (!writes.has(path25)) {
-      writes.set(path25, {
+    if (!writes.has(path28)) {
+      writes.set(path28, {
         lastChange: now,
         cancelWait: () => {
-          writes.delete(path25);
+          writes.delete(path28);
           clearTimeout(timeoutHandler);
           return event;
         }
@@ -3066,8 +3580,8 @@ var FSWatcher = class extends import_events.EventEmitter {
   /**
    * Determines whether user has asked to ignore this path.
    */
-  _isIgnored(path25, stats) {
-    if (this.options.atomic && DOT_RE.test(path25))
+  _isIgnored(path28, stats) {
+    if (this.options.atomic && DOT_RE.test(path28))
       return true;
     if (!this._userIgnored) {
       const { cwd } = this.options;
@@ -3077,17 +3591,17 @@ var FSWatcher = class extends import_events.EventEmitter {
       const list = [...ignoredPaths.map(normalizeIgnored(cwd)), ...ignored];
       this._userIgnored = anymatch(list, void 0);
     }
-    return this._userIgnored(path25, stats);
+    return this._userIgnored(path28, stats);
   }
-  _isntIgnored(path25, stat4) {
-    return !this._isIgnored(path25, stat4);
+  _isntIgnored(path28, stat4) {
+    return !this._isIgnored(path28, stat4);
   }
   /**
    * Provides a set of common helpers and properties relating to symlink handling.
    * @param path file or directory pattern being watched
    */
-  _getWatchHelpers(path25) {
-    return new WatchHelper(path25, this.options.followSymlinks, this);
+  _getWatchHelpers(path28) {
+    return new WatchHelper(path28, this.options.followSymlinks, this);
   }
   // Directory helpers
   // -----------------
@@ -3119,63 +3633,63 @@ var FSWatcher = class extends import_events.EventEmitter {
    * @param item      base path of item/directory
    */
   _remove(directory, item, isDirectory) {
-    const path25 = sysPath2.join(directory, item);
-    const fullPath = sysPath2.resolve(path25);
-    isDirectory = isDirectory != null ? isDirectory : this._watched.has(path25) || this._watched.has(fullPath);
-    if (!this._throttle("remove", path25, 100))
+    const path28 = sysPath2.join(directory, item);
+    const fullPath = sysPath2.resolve(path28);
+    isDirectory = isDirectory != null ? isDirectory : this._watched.has(path28) || this._watched.has(fullPath);
+    if (!this._throttle("remove", path28, 100))
       return;
     if (!isDirectory && this._watched.size === 1) {
       this.add(directory, item, true);
     }
-    const wp = this._getWatchedDir(path25);
+    const wp = this._getWatchedDir(path28);
     const nestedDirectoryChildren = wp.getChildren();
-    nestedDirectoryChildren.forEach((nested) => this._remove(path25, nested));
+    nestedDirectoryChildren.forEach((nested) => this._remove(path28, nested));
     const parent = this._getWatchedDir(directory);
     const wasTracked = parent.has(item);
     parent.remove(item);
     if (this._symlinkPaths.has(fullPath)) {
       this._symlinkPaths.delete(fullPath);
     }
-    let relPath = path25;
+    let relPath = path28;
     if (this.options.cwd)
-      relPath = sysPath2.relative(this.options.cwd, path25);
+      relPath = sysPath2.relative(this.options.cwd, path28);
     if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
       const event = this._pendingWrites.get(relPath).cancelWait();
       if (event === EVENTS.ADD)
         return;
     }
-    this._watched.delete(path25);
+    this._watched.delete(path28);
     this._watched.delete(fullPath);
     const eventName = isDirectory ? EVENTS.UNLINK_DIR : EVENTS.UNLINK;
-    if (wasTracked && !this._isIgnored(path25))
-      this._emit(eventName, path25);
-    this._closePath(path25);
+    if (wasTracked && !this._isIgnored(path28))
+      this._emit(eventName, path28);
+    this._closePath(path28);
   }
   /**
    * Closes all watchers for a path
    */
-  _closePath(path25) {
-    this._closeFile(path25);
-    const dir = sysPath2.dirname(path25);
-    this._getWatchedDir(dir).remove(sysPath2.basename(path25));
+  _closePath(path28) {
+    this._closeFile(path28);
+    const dir = sysPath2.dirname(path28);
+    this._getWatchedDir(dir).remove(sysPath2.basename(path28));
   }
   /**
    * Closes only file-specific watchers
    */
-  _closeFile(path25) {
-    const closers = this._closers.get(path25);
+  _closeFile(path28) {
+    const closers = this._closers.get(path28);
     if (!closers)
       return;
     closers.forEach((closer) => closer());
-    this._closers.delete(path25);
+    this._closers.delete(path28);
   }
-  _addPathCloser(path25, closer) {
+  _addPathCloser(path28, closer) {
     if (!closer)
       return;
-    let list = this._closers.get(path25);
+    let list = this._closers.get(path28);
     if (!list) {
       list = [];
-      this._closers.set(path25, list);
+      this._closers.set(path28, list);
     }
     list.push(closer);
   }
@@ -3210,54 +3724,132 @@ init_globals();
 function setupHotReload({
   app,
   appDir,
+  projectRoot,
   route = "/__fw/hot",
   waitForBuild,
   onFileChange
 }) {
   const clients = /* @__PURE__ */ new Set();
   app.get(route, (req, res) => {
-    res.setHeader("Content-Type", "text/event-stream");
-    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
     res.setHeader("Connection", "keep-alive");
-    res.flushHeaders?.();
-    res.write(`event: ping
-data: connected
-
-`);
+    res.setHeader("X-Accel-Buffering", "no");
+    if (res.flushHeaders) {
+      res.flushHeaders();
+    } else {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no"
+      });
+    }
     clients.add(res);
+    const pingMessage = "event: ping\ndata: connected\n\n";
+    try {
+      res.write(pingMessage, "utf-8");
+    } catch (error) {
+      console.error(`[hot-reload-server] \u274C Error sending ping:`, error);
+      clients.delete(res);
+    }
     req.on("close", () => {
       clients.delete(res);
     });
+    req.on("aborted", () => {
+      clients.delete(res);
+    });
   });
-  const watcher = esm_default.watch(appDir, {
+  console.log(`[hot-reload-server] \u2705 SSE endpoint registered at ${route}`);
+  const resolvedProjectRoot = projectRoot ? import_path16.default.resolve(projectRoot) : import_path16.default.dirname(import_path16.default.resolve(appDir));
+  const watcher = esm_default.watch(resolvedProjectRoot, {
     ignoreInitial: true,
-    ignored: ["**/node_modules/**", `**/${BUILD_FOLDER_NAME}/**`, "**/.git/**"]
+    ignored: [
+      "**/node_modules/**",
+      `**/${BUILD_FOLDER_NAME}/**`,
+      "**/.loly/**",
+      // Ignore build output directory completely
+      "**/.git/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.next/**",
+      "**/.cache/**",
+      "**/.turbo/**",
+      "**/.swc/**",
+      "**/coverage/**",
+      // Ignore generated files that trigger unnecessary reloads
+      "**/*.map",
+      // Source maps
+      "**/*.log",
+      // Log files
+      "**/.DS_Store",
+      // macOS
+      "**/Thumbs.db"
+      // Windows
+    ],
+    persistent: true,
+    ignorePermissionErrors: true,
+    // Only watch relevant source files (TypeScript, JavaScript, CSS)
+    // Filter out JSON files in build directories
+    awaitWriteFinish: {
+      stabilityThreshold: 150,
+      // Wait 150ms after file change to trigger event (debounce)
+      pollInterval: 50
+      // Check every 50ms
+    }
   });
+  let broadcastTimeout = null;
+  const BROADCAST_DEBOUNCE_MS = 300;
   async function broadcastReload(reason, filePath) {
+    const normalizedPath = import_path16.default.normalize(filePath);
+    if (normalizedPath.includes(BUILD_FOLDER_NAME) || normalizedPath.includes(".loly") || normalizedPath.endsWith(".map") || normalizedPath.endsWith(".log") || normalizedPath.includes("route-chunks.json") || normalizedPath.includes("routes-client.ts") || normalizedPath.includes("/client/route-")) {
+      return;
+    }
     const rel = import_path16.default.relative(appDir, filePath);
     console.log(`[hot-reload] ${reason}: ${rel}`);
-    if (onFileChange) {
-      try {
-        await onFileChange(filePath);
-      } catch (error) {
-        console.warn("[hot-reload] Error in onFileChange callback:", error);
-      }
+    if (broadcastTimeout) {
+      clearTimeout(broadcastTimeout);
     }
-    if (waitForBuild) {
-      try {
-        console.log("[hot-reload] Waiting for client bundle to finish...");
-        await waitForBuild();
-        console.log("[hot-reload] Client bundle ready, sending reload event");
-      } catch (error) {
-        console.warn("[hot-reload] Error waiting for build:", error);
+    broadcastTimeout = setTimeout(async () => {
+      if (onFileChange) {
+        try {
+          await onFileChange(filePath);
+        } catch (error) {
+          console.warn("[hot-reload] Error in onFileChange callback:", error);
+        }
       }
-    }
-    for (const res of clients) {
-      res.write(`event: message
+      if (waitForBuild) {
+        try {
+          console.log("[hot-reload] Waiting for client bundle to finish...");
+          await waitForBuild();
+          console.log("[hot-reload] Client bundle ready, sending reload event");
+        } catch (error) {
+          console.warn("[hot-reload] Error waiting for build:", error);
+        }
+      }
+      const message = `event: message
 data: reload:${rel}
 
-`);
-    }
+`;
+      console.log(`[hot-reload-server] \u{1F4E4} Broadcasting reload event to ${clients.size} client(s)`);
+      let sentCount = 0;
+      for (const res of clients) {
+        try {
+          if (res.writableEnded || res.destroyed) {
+            clients.delete(res);
+            continue;
+          }
+          res.write(message, "utf-8");
+          sentCount++;
+        } catch (error) {
+          console.error(`[hot-reload-server] \u2717 Error sending to client:`, error);
+          clients.delete(res);
+        }
+      }
+      if (sentCount > 0) {
+        console.log(`[hot-reload-server] \u2705 Reload event sent to ${sentCount} client(s)`);
+      }
+    }, BROADCAST_DEBOUNCE_MS);
   }
   watcher.on("add", (filePath) => broadcastReload("add", filePath)).on("change", (filePath) => broadcastReload("change", filePath)).on("unlink", (filePath) => broadcastReload("unlink", filePath));
 }
@@ -3333,6 +3925,121 @@ function deepMerge(target, source) {
   }
   return result;
 }
+var ConfigValidationError = class extends Error {
+  constructor(message, errors = []) {
+    super(message);
+    this.errors = errors;
+    this.name = "ConfigValidationError";
+  }
+};
+function validateConfig(config, projectRoot) {
+  const errors = [];
+  if (!config.directories.app || typeof config.directories.app !== "string") {
+    errors.push("config.directories.app must be a non-empty string");
+  } else {
+    const appDir = import_path18.default.join(projectRoot, config.directories.app);
+    if (!import_fs16.default.existsSync(appDir) && process.env.NODE_ENV !== "test") {
+      errors.push(
+        `App directory not found: ${config.directories.app}
+  Expected at: ${appDir}
+  \u{1F4A1} Suggestion: Create the directory or update config.directories.app`
+      );
+    }
+  }
+  if (!config.directories.build || typeof config.directories.build !== "string") {
+    errors.push("config.directories.build must be a non-empty string");
+  }
+  if (!config.directories.static || typeof config.directories.static !== "string") {
+    errors.push("config.directories.static must be a non-empty string");
+  }
+  const conventionKeys = ["page", "layout", "notFound", "error", "api"];
+  for (const key of conventionKeys) {
+    if (!config.conventions[key] || typeof config.conventions[key] !== "string") {
+      errors.push(`config.conventions.${key} must be a non-empty string`);
+    }
+  }
+  if (!["always", "never", "ignore"].includes(config.routing.trailingSlash)) {
+    errors.push(
+      `config.routing.trailingSlash must be 'always', 'never', or 'ignore'
+  Received: ${JSON.stringify(config.routing.trailingSlash)}
+  \u{1F4A1} Suggestion: Use one of the valid values: 'always' | 'never' | 'ignore'`
+    );
+  }
+  if (typeof config.routing.caseSensitive !== "boolean") {
+    errors.push("config.routing.caseSensitive must be a boolean");
+  }
+  if (typeof config.routing.basePath !== "string") {
+    errors.push("config.routing.basePath must be a string");
+  } else if (config.routing.basePath && !config.routing.basePath.startsWith("/")) {
+    errors.push(
+      `config.routing.basePath must start with '/' (if not empty)
+  Received: ${JSON.stringify(config.routing.basePath)}
+  \u{1F4A1} Suggestion: Use an empty string '' or a path starting with '/', e.g., '/api'`
+    );
+  }
+  const validClientBundlers = ["rspack", "webpack", "vite"];
+  if (!validClientBundlers.includes(config.build.clientBundler)) {
+    errors.push(
+      `config.build.clientBundler must be one of: ${validClientBundlers.join(", ")}
+  Received: ${JSON.stringify(config.build.clientBundler)}`
+    );
+  }
+  const validServerBundlers = ["esbuild", "tsup", "swc"];
+  if (!validServerBundlers.includes(config.build.serverBundler)) {
+    errors.push(
+      `config.build.serverBundler must be one of: ${validServerBundlers.join(", ")}
+  Received: ${JSON.stringify(config.build.serverBundler)}`
+    );
+  }
+  if (!["cjs", "esm"].includes(config.build.outputFormat)) {
+    errors.push(
+      `config.build.outputFormat must be 'cjs' or 'esm'
+  Received: ${JSON.stringify(config.build.outputFormat)}`
+    );
+  }
+  const validAdapters = ["express", "fastify", "koa"];
+  if (!validAdapters.includes(config.server.adapter)) {
+    errors.push(
+      `config.server.adapter must be one of: ${validAdapters.join(", ")}
+  Received: ${JSON.stringify(config.server.adapter)}`
+    );
+  }
+  if (typeof config.server.port !== "number" || config.server.port < 1 || config.server.port > 65535) {
+    errors.push(
+      `config.server.port must be a number between 1 and 65535
+  Received: ${JSON.stringify(config.server.port)}`
+    );
+  }
+  if (!config.server.host || typeof config.server.host !== "string") {
+    errors.push("config.server.host must be a non-empty string");
+  }
+  const validFrameworks = ["react", "preact", "vue", "svelte"];
+  if (!validFrameworks.includes(config.rendering.framework)) {
+    errors.push(
+      `config.rendering.framework must be one of: ${validFrameworks.join(", ")}
+  Received: ${JSON.stringify(config.rendering.framework)}`
+    );
+  }
+  if (typeof config.rendering.streaming !== "boolean") {
+    errors.push("config.rendering.streaming must be a boolean");
+  }
+  if (typeof config.rendering.ssr !== "boolean") {
+    errors.push("config.rendering.ssr must be a boolean");
+  }
+  if (typeof config.rendering.ssg !== "boolean") {
+    errors.push("config.rendering.ssg must be a boolean");
+  }
+  if (errors.length > 0) {
+    const errorMessage = [
+      "\u274C Configuration validation failed:",
+      "",
+      ...errors.map((err, i) => `${i + 1}. ${err}`),
+      "",
+      "\u{1F4A1} Please check your loly.config.ts file and fix the errors above."
+    ].join("\n");
+    throw new ConfigValidationError(errorMessage, errors);
+  }
+}
 function loadConfig(projectRoot) {
   const configFiles = [
     import_path18.default.join(projectRoot, "loly.config.ts"),
@@ -3340,6 +4047,7 @@ function loadConfig(projectRoot) {
     import_path18.default.join(projectRoot, "loly.config.json")
   ];
   let userConfig = {};
+  let loadedConfigFile = null;
   for (const configFile of configFiles) {
     if (import_fs16.default.existsSync(configFile)) {
       try {
@@ -3353,16 +4061,31 @@ function loadConfig(projectRoot) {
           const mod = require(configFile);
           userConfig = typeof mod.default === "function" ? mod.default(process.env.NODE_ENV) : mod.default || mod.config || mod;
         }
+        loadedConfigFile = import_path18.default.relative(projectRoot, configFile);
         break;
       } catch (error) {
-        console.warn(`[framework] Failed to load config from ${configFile}:`, error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new ConfigValidationError(
+          `Failed to load configuration from ${import_path18.default.relative(projectRoot, configFile)}:
+  ${errorMessage}
+  \u{1F4A1} Suggestion: Check that your config file exports a valid configuration object`
+        );
       }
     }
   }
   const config = deepMerge(DEFAULT_CONFIG, userConfig);
-  const appDir = import_path18.default.join(projectRoot, config.directories.app);
-  if (!import_fs16.default.existsSync(appDir) && process.env.NODE_ENV !== "test") {
-    console.warn(`[framework] App directory not found: ${appDir}`);
+  try {
+    validateConfig(config, projectRoot);
+  } catch (error) {
+    if (error instanceof ConfigValidationError) {
+      if (loadedConfigFile) {
+        error.message = `[Configuration Error in ${loadedConfigFile}]
+
+${error.message}`;
+      }
+      throw error;
+    }
+    throw error;
   }
   return config;
 }
@@ -3379,14 +4102,14 @@ function getStaticDir(projectRoot, config) {
 // modules/server/setup.ts
 function setupServer(app, options) {
   const { projectRoot, appDir, isDev, config } = options;
-  const routeLoader = isDev ? new FilesystemRouteLoader(appDir) : new ManifestRouteLoader(projectRoot);
+  const routeLoader = isDev ? new FilesystemRouteLoader(appDir, projectRoot) : new ManifestRouteLoader(projectRoot);
   if (isDev) {
     let getRoutes2 = function() {
       clearAppRequireCache(appDir);
-      const loader = new FilesystemRouteLoader(appDir);
+      sharedLoader.invalidateCache();
       return {
-        routes: loader.loadRoutes(),
-        apiRoutes: loader.loadApiRoutes()
+        routes: sharedLoader.loadRoutes(),
+        apiRoutes: sharedLoader.loadApiRoutes()
       };
     };
     var getRoutes = getRoutes2;
@@ -3400,19 +4123,20 @@ function setupServer(app, options) {
         console.log(`[hot-reload] Cleared require cache for: ${rel}`);
       }
       if (isPageFile) {
-        const loader = new FilesystemRouteLoader(appDir);
+        const loader = new FilesystemRouteLoader(appDir, projectRoot);
         const newRoutes = loader.loadRoutes();
         writeClientRoutesManifest(newRoutes, projectRoot);
         console.log("[hot-reload] Client routes manifest reloaded");
       }
     };
-    setupHotReload({ app, appDir, waitForBuild, onFileChange });
+    setupHotReload({ app, appDir, projectRoot, waitForBuild, onFileChange });
     app.use("/static", import_express.default.static(outDir));
     const routes = routeLoader.loadRoutes();
     const wssRoutes = routeLoader.loadWssRoutes();
     const notFoundPage = routeLoader.loadNotFoundRoute();
     const errorPage = routeLoader.loadErrorRoute();
     writeClientRoutesManifest(routes, projectRoot);
+    const sharedLoader = new FilesystemRouteLoader(appDir, projectRoot);
     return {
       routes,
       wssRoutes,
@@ -3500,90 +4224,10 @@ function sanitizeQuery(query) {
 
 // modules/server/middleware/rate-limit.ts
 var import_express_rate_limit = __toESM(require("express-rate-limit"));
-function createRateLimiter(config = {}) {
-  const {
-    windowMs = 15 * 60 * 1e3,
-    // 15 minutes
-    max = 100,
-    // limit each IP to 100 requests per windowMs
-    message = "Too many requests from this IP, please try again later.",
-    standardHeaders = true,
-    legacyHeaders = false,
-    skipSuccessfulRequests = false,
-    skipFailedRequests = false
-  } = config;
-  return (0, import_express_rate_limit.default)({
-    windowMs,
-    max,
-    message: {
-      error: message
-    },
-    standardHeaders,
-    legacyHeaders,
-    skipSuccessfulRequests,
-    skipFailedRequests
-  });
-}
-var defaultRateLimiter = createRateLimiter({
-  windowMs: 15 * 60 * 1e3,
-  // 15 minutes
-  max: 100,
-  message: "Too many requests from this IP, please try again later."
-});
-var strictRateLimiter = createRateLimiter({
-  windowMs: 15 * 60 * 1e3,
-  // 15 minutes
-  max: 5,
-  message: "Too many authentication attempts, please try again later."
-});
-var lenientRateLimiter = createRateLimiter({
-  windowMs: 15 * 60 * 1e3,
-  // 15 minutes
-  max: 200,
-  message: "Too many requests from this IP, please try again later."
-});
-
-// modules/server/middleware/auto-rate-limit.ts
-function matchesStrictPattern(path25, patterns) {
-  for (const pattern of patterns) {
-    const regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/");
-    const regex = new RegExp(`^${regexPattern}$`);
-    if (regex.test(path25)) {
-      return true;
-    }
-  }
-  return false;
-}
-function isRateLimiter(mw) {
-  if (!mw) return false;
-  if (mw === strictRateLimiter || mw === defaultRateLimiter || mw === lenientRateLimiter) {
-    return true;
-  }
-  if (typeof mw === "function" && mw.name && mw.name.includes("rateLimit")) {
-    return true;
-  }
-  if (mw && typeof mw === "function" && mw.skip || mw.resetKey) {
-    return true;
-  }
-  return false;
-}
-function getAutoRateLimiter(route, strictPatterns = []) {
-  const hasRateLimiter = route.middlewares?.some(isRateLimiter) || Object.values(route.methodMiddlewares || {}).some(
-    (mws) => mws?.some(isRateLimiter)
-  );
-  if (hasRateLimiter) {
-    return null;
-  }
-  if (strictPatterns.length > 0 && matchesStrictPattern(route.pattern, strictPatterns)) {
-    console.log(`[rate-limit] Applying strict rate limiter to route: ${route.pattern}`);
-    return strictRateLimiter;
-  }
-  return null;
-}
-
-// modules/logger/index.ts
-var import_pino = __toESM(require("pino"));
-function createLogger(options = {}) {
+
+// modules/logger/index.ts
+var import_pino = __toESM(require("pino"));
+function createLogger(options = {}) {
   const {
     level = process.env.LOG_LEVEL || (process.env.NODE_ENV === "development" ? "debug" : "info"),
     enabled = process.env.LOG_ENABLED !== "false",
@@ -3639,8 +4283,8 @@ function resetLogger() {
   loggerInstance = null;
 }
 var Logger = class _Logger {
-  constructor(logger4, context = {}) {
-    this.pino = logger4 || getLogger();
+  constructor(logger5, context = {}) {
+    this.pino = logger5 || getLogger();
     this.context = context;
   }
   /**
@@ -3717,12 +4361,12 @@ var DEFAULT_IGNORED_PATHS = [
   /^\/sockjs-node/
   // Hot reload websocket
 ];
-function shouldIgnorePath(path25, ignoredPaths) {
+function shouldIgnorePath(path28, ignoredPaths) {
   return ignoredPaths.some((pattern) => {
     if (typeof pattern === "string") {
-      return path25 === pattern || path25.startsWith(pattern);
+      return path28 === pattern || path28.startsWith(pattern);
     }
-    return pattern.test(path25);
+    return pattern.test(path28);
   });
 }
 function requestLoggerMiddleware(options = {}) {
@@ -3773,6 +4417,151 @@ function getRequestLogger(req) {
   return req.logger || logger.child({ requestId: "unknown" });
 }
 
+// modules/server/middleware/rate-limit.ts
+var logger2 = createModuleLogger("rate-limit");
+function validateRateLimitConfig(config) {
+  if (config.windowMs !== void 0 && (config.windowMs < 1e3 || !Number.isInteger(config.windowMs))) {
+    throw new Error(
+      `Invalid rateLimit.windowMs: ${config.windowMs}. Must be an integer >= 1000 (milliseconds)`
+    );
+  }
+  if (config.max !== void 0 && (config.max < 1 || !Number.isInteger(config.max))) {
+    throw new Error(
+      `Invalid rateLimit.max: ${config.max}. Must be an integer >= 1`
+    );
+  }
+}
+function createRateLimiter(config = {}) {
+  validateRateLimitConfig(config);
+  const {
+    windowMs = 15 * 60 * 1e3,
+    // 15 minutes
+    max = 100,
+    // limit each IP to 100 requests per windowMs
+    message = "Too many requests from this IP, please try again later.",
+    standardHeaders = true,
+    legacyHeaders = false,
+    skipSuccessfulRequests = false,
+    skipFailedRequests = false,
+    keyGenerator,
+    skip
+  } = config;
+  const limiter = (0, import_express_rate_limit.default)({
+    windowMs,
+    max,
+    message: {
+      error: message,
+      retryAfter: Math.ceil(windowMs / 1e3)
+      // seconds until retry
+    },
+    standardHeaders,
+    legacyHeaders,
+    skipSuccessfulRequests,
+    skipFailedRequests,
+    keyGenerator,
+    skip
+  });
+  const wrappedLimiter = (req, res, next) => {
+    limiter(req, res, (err) => {
+      if (err && res.statusCode === 429) {
+        const ip = req.ip || req.connection?.remoteAddress || "unknown";
+        logger2.warn("Rate limit exceeded", {
+          ip,
+          path: req.path,
+          method: req.method,
+          limit: max,
+          windowMs,
+          retryAfter: Math.ceil(windowMs / 1e3)
+        });
+      }
+      if (err) {
+        return next(err);
+      }
+      next();
+    });
+  };
+  Object.setPrototypeOf(wrappedLimiter, limiter);
+  Object.assign(wrappedLimiter, limiter);
+  return wrappedLimiter;
+}
+var defaultRateLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1e3,
+  // 15 minutes
+  max: 100,
+  message: "Too many requests from this IP, please try again later."
+});
+var strictRateLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1e3,
+  // 15 minutes
+  max: 5,
+  message: "Too many authentication attempts, please try again later."
+});
+var lenientRateLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1e3,
+  // 15 minutes
+  max: 200,
+  message: "Too many requests from this IP, please try again later."
+});
+function createRateLimiterFromConfig(config, useApiMax = false) {
+  if (!config) return null;
+  const max = useApiMax ? config.apiMax ?? config.max ?? 100 : config.max ?? 100;
+  const windowMs = config.windowMs ?? 15 * 60 * 1e3;
+  return createRateLimiter({
+    windowMs,
+    max,
+    message: `Too many requests from this IP, please try again after ${Math.ceil(windowMs / 1e3)} seconds.`
+  });
+}
+function createStrictRateLimiterFromConfig(config) {
+  if (!config || config.strictMax === void 0) {
+    return strictRateLimiter;
+  }
+  const windowMs = config.windowMs ?? 15 * 60 * 1e3;
+  return createRateLimiter({
+    windowMs,
+    max: config.strictMax,
+    message: `Too many authentication attempts, please try again after ${Math.ceil(windowMs / 1e3)} seconds.`
+  });
+}
+
+// modules/server/middleware/auto-rate-limit.ts
+function matchesStrictPattern(path28, patterns) {
+  for (const pattern of patterns) {
+    const regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/");
+    const regex = new RegExp(`^${regexPattern}$`);
+    if (regex.test(path28)) {
+      return true;
+    }
+  }
+  return false;
+}
+function isRateLimiter(mw) {
+  if (!mw) return false;
+  if (mw === strictRateLimiter || mw === defaultRateLimiter || mw === lenientRateLimiter) {
+    return true;
+  }
+  if (typeof mw === "function" && mw.name && mw.name.includes("rateLimit")) {
+    return true;
+  }
+  if (mw && typeof mw === "function" && mw.skip || mw.resetKey) {
+    return true;
+  }
+  return false;
+}
+function getAutoRateLimiter(route, strictPatterns = [], rateLimitConfig) {
+  const hasRateLimiter = route.middlewares?.some(isRateLimiter) || Object.values(route.methodMiddlewares || {}).some(
+    (mws) => mws?.some(isRateLimiter)
+  );
+  if (hasRateLimiter) {
+    return null;
+  }
+  if (strictPatterns.length > 0 && matchesStrictPattern(route.pattern, strictPatterns)) {
+    const limiter = rateLimitConfig ? createStrictRateLimiterFromConfig(rateLimitConfig) : strictRateLimiter;
+    return limiter;
+  }
+  return null;
+}
+
 // modules/server/handlers/api.ts
 async function handleApiRequest(options) {
   const { apiRoutes, urlPath, req, res, env = "dev" } = options;
@@ -3804,7 +4593,8 @@ async function handleApiRequest(options) {
   try {
     const autoRateLimiter = getAutoRateLimiter(
       route,
-      options.strictRateLimitPatterns
+      options.strictRateLimitPatterns,
+      options.rateLimitConfig
     );
     const reqLogger = getRequestLogger(req);
     if (autoRateLimiter) {
@@ -3816,26 +4606,46 @@ async function handleApiRequest(options) {
     const globalMws = route.middlewares ?? [];
     const perMethodMws = route.methodMiddlewares?.[method] ?? [];
     const chain = autoRateLimiter ? [autoRateLimiter, ...globalMws, ...perMethodMws] : [...globalMws, ...perMethodMws];
-    for (const mw of chain) {
-      const isExpressRateLimit = mw && typeof mw === "function" && (mw.skip || mw.resetKey || mw.name?.includes("rateLimit"));
-      if (isExpressRateLimit) {
-        await new Promise((resolve3, reject) => {
-          const next = (err) => {
-            if (err) reject(err);
-            else resolve3();
-          };
-          try {
-            const result = mw(req, res, next);
-            if (result && typeof result.then === "function") {
-              result.then(() => resolve3()).catch(reject);
+    for (let i = 0; i < chain.length; i++) {
+      const mw = chain[i];
+      if (typeof mw !== "function") {
+        reqLogger.warn("Invalid middleware in chain", {
+          route: route.pattern,
+          method,
+          middlewareIndex: i,
+          middlewareType: typeof mw
+        });
+        continue;
+      }
+      try {
+        const isExpressRateLimit = mw.skip || mw.resetKey || mw.name?.includes("rateLimit");
+        if (isExpressRateLimit) {
+          await new Promise((resolve3, reject) => {
+            const next = (err) => {
+              if (err) reject(err);
+              else resolve3();
+            };
+            try {
+              const result = mw(req, res, next);
+              if (result && typeof result.then === "function") {
+                result.then(() => resolve3()).catch(reject);
+              }
+            } catch (err) {
+              reject(err);
             }
-          } catch (err) {
-            reject(err);
-          }
+          });
+        } else {
+          await Promise.resolve(mw(ctx, async () => {
+          }));
+        }
+      } catch (error) {
+        reqLogger.error("API middleware failed", error instanceof Error ? error : new Error(String(error)), {
+          route: route.pattern,
+          method,
+          middlewareIndex: i,
+          middlewareName: mw.name || "anonymous"
         });
-      } else {
-        await Promise.resolve(mw(ctx, async () => {
-        }));
+        throw error;
       }
       if (res.headersSent) {
         return;
@@ -3886,34 +4696,260 @@ function createDocumentTree(options) {
     titleFallback,
     descriptionFallback,
     chunkHref,
+    entrypointFiles = [],
     theme,
     clientJsPath = "/static/client.js",
     clientCssPath = "/static/client.css",
-    nonce
+    nonce,
+    includeInlineScripts = true
+    // Default true - scripts inline in body for both SSR and SSG
   } = options;
-  const metaObj = meta ?? {};
-  const title = metaObj.title ?? titleFallback ?? "My Framework Dev";
-  const lang = metaObj.lang ?? "en";
-  const description = metaObj.description ?? descriptionFallback ?? "Demo Loly framework";
+  const metaObj = meta ?? null;
+  const title = metaObj?.title ?? titleFallback ?? "My Framework Dev";
+  const lang = metaObj?.lang ?? "en";
+  const description = metaObj?.description ?? descriptionFallback ?? "Demo Loly framework";
   const extraMetaTags = [];
+  const linkTags = [];
   if (description) {
     extraMetaTags.push(
       import_react.default.createElement("meta", {
+        key: "meta-description",
         name: "description",
         content: description
       })
     );
   }
-  if (Array.isArray(metaObj.metaTags)) {
-    for (const tag of metaObj.metaTags) {
+  if (metaObj?.robots) {
+    extraMetaTags.push(
+      import_react.default.createElement("meta", {
+        key: "meta-robots",
+        name: "robots",
+        content: metaObj.robots
+      })
+    );
+  }
+  if (metaObj?.themeColor) {
+    extraMetaTags.push(
+      import_react.default.createElement("meta", {
+        key: "meta-theme-color",
+        name: "theme-color",
+        content: metaObj.themeColor
+      })
+    );
+  }
+  if (metaObj?.viewport) {
+    extraMetaTags.push(
+      import_react.default.createElement("meta", {
+        key: "meta-viewport",
+        name: "viewport",
+        content: metaObj.viewport
+      })
+    );
+  }
+  if (metaObj?.canonical) {
+    linkTags.push(
+      import_react.default.createElement("link", {
+        key: "link-canonical",
+        rel: "canonical",
+        href: metaObj.canonical
+      })
+    );
+  }
+  if (metaObj?.openGraph) {
+    const og = metaObj.openGraph;
+    if (og.title) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-title",
+          property: "og:title",
+          content: og.title
+        })
+      );
+    }
+    if (og.description) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-description",
+          property: "og:description",
+          content: og.description
+        })
+      );
+    }
+    if (og.type) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-type",
+          property: "og:type",
+          content: og.type
+        })
+      );
+    }
+    if (og.url) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-url",
+          property: "og:url",
+          content: og.url
+        })
+      );
+    }
+    if (og.image) {
+      if (typeof og.image === "string") {
+        extraMetaTags.push(
+          import_react.default.createElement("meta", {
+            key: "og-image",
+            property: "og:image",
+            content: og.image
+          })
+        );
+      } else {
+        extraMetaTags.push(
+          import_react.default.createElement("meta", {
+            key: "og-image",
+            property: "og:image",
+            content: og.image.url
+          })
+        );
+        if (og.image.width) {
+          extraMetaTags.push(
+            import_react.default.createElement("meta", {
+              key: "og-image-width",
+              property: "og:image:width",
+              content: String(og.image.width)
+            })
+          );
+        }
+        if (og.image.height) {
+          extraMetaTags.push(
+            import_react.default.createElement("meta", {
+              key: "og-image-height",
+              property: "og:image:height",
+              content: String(og.image.height)
+            })
+          );
+        }
+        if (og.image.alt) {
+          extraMetaTags.push(
+            import_react.default.createElement("meta", {
+              key: "og-image-alt",
+              property: "og:image:alt",
+              content: og.image.alt
+            })
+          );
+        }
+      }
+    }
+    if (og.siteName) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-site-name",
+          property: "og:site_name",
+          content: og.siteName
+        })
+      );
+    }
+    if (og.locale) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "og-locale",
+          property: "og:locale",
+          content: og.locale
+        })
+      );
+    }
+  }
+  if (metaObj?.twitter) {
+    const twitter = metaObj.twitter;
+    if (twitter.card) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-card",
+          name: "twitter:card",
+          content: twitter.card
+        })
+      );
+    }
+    if (twitter.title) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-title",
+          name: "twitter:title",
+          content: twitter.title
+        })
+      );
+    }
+    if (twitter.description) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-description",
+          name: "twitter:description",
+          content: twitter.description
+        })
+      );
+    }
+    if (twitter.image) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-image",
+          name: "twitter:image",
+          content: twitter.image
+        })
+      );
+    }
+    if (twitter.imageAlt) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-image-alt",
+          name: "twitter:image:alt",
+          content: twitter.imageAlt
+        })
+      );
+    }
+    if (twitter.site) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-site",
+          name: "twitter:site",
+          content: twitter.site
+        })
+      );
+    }
+    if (twitter.creator) {
+      extraMetaTags.push(
+        import_react.default.createElement("meta", {
+          key: "twitter-creator",
+          name: "twitter:creator",
+          content: twitter.creator
+        })
+      );
+    }
+  }
+  if (metaObj?.metaTags && Array.isArray(metaObj.metaTags)) {
+    metaObj.metaTags.forEach((tag, index) => {
       extraMetaTags.push(
         import_react.default.createElement("meta", {
+          key: `meta-custom-${index}`,
           name: tag.name,
           property: tag.property,
+          httpEquiv: tag.httpEquiv,
           content: tag.content
         })
       );
-    }
+    });
+  }
+  if (metaObj?.links && Array.isArray(metaObj.links)) {
+    metaObj.links.forEach((link, index) => {
+      linkTags.push(
+        import_react.default.createElement("link", {
+          key: `link-custom-${index}`,
+          rel: link.rel,
+          href: link.href,
+          as: link.as,
+          crossOrigin: link.crossorigin,
+          type: link.type
+        })
+      );
+    });
   }
   const serialized = JSON.stringify({
     ...initialData,
@@ -3922,6 +4958,27 @@ function createDocumentTree(options) {
   const routerSerialized = JSON.stringify({
     ...routerData
   });
+  const bodyChildren = [
+    import_react.default.createElement("div", { id: APP_CONTAINER_ID }, appTree)
+  ];
+  if (includeInlineScripts) {
+    bodyChildren.push(
+      import_react.default.createElement("script", {
+        key: "initial-data",
+        nonce,
+        dangerouslySetInnerHTML: {
+          __html: `window.${WINDOW_DATA_KEY} = ${serialized};`
+        }
+      }),
+      import_react.default.createElement("script", {
+        key: "router-data",
+        nonce,
+        dangerouslySetInnerHTML: {
+          __html: `window.${ROUTER_DATA_KEY} = ${routerSerialized};`
+        }
+      })
+    );
+  }
   const documentTree = import_react.default.createElement(
     "html",
     { lang },
@@ -3930,13 +4987,25 @@ function createDocumentTree(options) {
       null,
       import_react.default.createElement("meta", { charSet: "utf-8" }),
       import_react.default.createElement("title", null, title),
+      // Viewport: use custom if provided, otherwise default
       import_react.default.createElement("meta", {
         name: "viewport",
-        content: "width=device-width, initial-scale=1"
+        content: metaObj?.viewport ?? "width=device-width, initial-scale=1"
       }),
       ...extraMetaTags,
+      ...linkTags,
+      ...entrypointFiles.length > 0 ? entrypointFiles.slice(0, -1).map(
+        (file) => import_react.default.createElement("link", {
+          key: `preload-${file}`,
+          rel: "preload",
+          href: file,
+          as: "script"
+        })
+      ) : [],
+      // Preload route-specific chunk if available
       chunkHref && import_react.default.createElement("link", {
-        rel: "modulepreload",
+        key: `preload-${chunkHref}`,
+        rel: "preload",
         href: chunkHref,
         as: "script"
       }),
@@ -3949,33 +5018,34 @@ function createDocumentTree(options) {
         rel: "stylesheet",
         href: clientCssPath
       }),
-      import_react.default.createElement("script", {
-        src: clientJsPath,
-        defer: true
-      })
+      ...entrypointFiles.length > 0 ? entrypointFiles.map(
+        (file) => import_react.default.createElement("script", {
+          key: file,
+          src: file,
+          defer: true,
+          nonce
+          // CSP nonce for external scripts
+        })
+      ) : [
+        import_react.default.createElement("script", {
+          key: "client",
+          src: clientJsPath,
+          defer: true,
+          nonce
+          // CSP nonce for external scripts
+        })
+      ]
     ),
     import_react.default.createElement(
       "body",
       {
         style: { margin: 0 },
-        className: [initialData.className, theme].filter(Boolean).join(" "),
+        className: [initialData.className || "", theme].filter(Boolean).join(" "),
         suppressHydrationWarning: true
         // Allow theme class to differ between server and client initially
       },
-      import_react.default.createElement("div", { id: APP_CONTAINER_ID }, appTree)
-    ),
-    import_react.default.createElement("script", {
-      nonce,
-      dangerouslySetInnerHTML: {
-        __html: `window.${WINDOW_DATA_KEY} = ${serialized};`
-      }
-    }),
-    import_react.default.createElement("script", {
-      nonce,
-      dangerouslySetInnerHTML: {
-        __html: `window.${ROUTER_DATA_KEY} = ${routerSerialized};`
-      }
-    })
+      ...bodyChildren
+    )
   );
   return documentTree;
 }
@@ -3991,7 +5061,7 @@ function buildInitialData(urlPath, params, loaderResult) {
     params,
     props,
     metadata: loaderResult.metadata ?? null,
-    className: loaderResult.className ?? "",
+    className: loaderResult.className,
     error: false,
     notFound: false
   };
@@ -4007,24 +5077,83 @@ var buildRouterData = (req) => {
 };
 
 // modules/server/handlers/middleware.ts
+var import_path20 = __toESM(require("path"));
 async function runRouteMiddlewares(route, ctx) {
-  for (const mw of route.middlewares) {
-    await Promise.resolve(
-      mw(ctx, async () => {
-      })
-    );
+  for (let i = 0; i < route.middlewares.length; i++) {
+    const mw = route.middlewares[i];
+    try {
+      await Promise.resolve(
+        mw(ctx, async () => {
+        })
+      );
+    } catch (error) {
+      const reqLogger = getRequestLogger(ctx.req);
+      const relativePath = route.pageFile ? import_path20.default.relative(process.cwd(), route.pageFile) : route.pattern;
+      reqLogger.error("Route middleware failed", error instanceof Error ? error : new Error(String(error)), {
+        route: route.pattern,
+        middlewareIndex: i,
+        pageFile: relativePath
+      });
+      throw error;
+    }
     if (ctx.res.headersSent) {
       return;
     }
   }
 }
 
-// modules/server/handlers/loader.ts
-async function runRouteLoader(route, ctx) {
+// modules/server/handlers/server-hook.ts
+var import_path21 = __toESM(require("path"));
+function createServerHookErrorMessage(error, hookType, routePattern, filePath) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : void 0;
+  let message = `[${hookType.toUpperCase()} SERVER HOOK ERROR]
+`;
+  message += `Route: ${routePattern}
+`;
+  if (filePath) {
+    const relativePath = import_path21.default.relative(process.cwd(), filePath);
+    message += `File: ${relativePath}
+`;
+  }
+  message += `Error: ${errorMessage}
+`;
+  if (errorMessage.includes("Cannot find module")) {
+    message += `
+\u{1F4A1} Suggestion: Check that all imports in your ${hookType}.server.hook.ts are correct.
+`;
+  } else if (errorMessage.includes("is not defined") || errorMessage.includes("Cannot read property")) {
+    message += `
+\u{1F4A1} Suggestion: Verify that all variables and properties exist in your ${hookType}.server.hook.ts.
+`;
+  } else if (errorMessage.includes("async") || errorMessage.includes("await")) {
+    message += `
+\u{1F4A1} Suggestion: Make sure getServerSideProps is an async function and all promises are awaited.
+`;
+  }
+  if (errorStack) {
+    message += `
+Stack trace:
+${errorStack}`;
+  }
+  return message;
+}
+async function runRouteServerHook(route, ctx) {
   if (!route.loader) {
     return { props: {} };
   }
-  return await route.loader(ctx);
+  try {
+    return await route.loader(ctx);
+  } catch (error) {
+    const detailedError = new Error(
+      createServerHookErrorMessage(error, "page", route.pattern, route.pageFile)
+    );
+    if (error instanceof Error && error.stack) {
+      detailedError.stack = error.stack;
+    }
+    detailedError.originalError = error;
+    throw detailedError;
+  }
 }
 
 // modules/server/handlers/response.ts
@@ -4065,26 +5194,26 @@ function handleNotFound(res, urlPath) {
 
 // modules/server/handlers/ssg.ts
 var import_fs17 = __toESM(require("fs"));
-var import_path20 = __toESM(require("path"));
-var logger2 = createModuleLogger("ssg");
+var import_path22 = __toESM(require("path"));
+var logger3 = createModuleLogger("ssg");
 function getSsgDirForPath(baseDir, urlPath) {
   const clean = urlPath === "/" ? "" : urlPath.replace(/^\/+/, "");
-  return import_path20.default.join(baseDir, clean);
+  return import_path22.default.join(baseDir, clean);
 }
 function getSsgHtmlPath(baseDir, urlPath) {
   const dir = getSsgDirForPath(baseDir, urlPath);
-  return import_path20.default.join(dir, "index.html");
+  return import_path22.default.join(dir, "index.html");
 }
 function getSsgDataPath(baseDir, urlPath) {
   const dir = getSsgDirForPath(baseDir, urlPath);
-  return import_path20.default.join(dir, "data.json");
+  return import_path22.default.join(dir, "data.json");
 }
 function tryServeSsgHtml(res, ssgOutDir, urlPath) {
   const ssgHtmlPath = getSsgHtmlPath(ssgOutDir, urlPath);
   if (!import_fs17.default.existsSync(ssgHtmlPath)) {
     return false;
   }
-  logger2.info("Serving SSG HTML", { urlPath, ssgHtmlPath });
+  logger3.info("Serving SSG HTML", { urlPath, ssgHtmlPath });
   res.setHeader(
     "Content-Security-Policy",
     "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; script-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https:; font-src 'self' data: https://fonts.gstatic.com; object-src 'none'; media-src 'self' https:; frame-src 'none';"
@@ -4106,13 +5235,43 @@ function tryServeSsgData(res, ssgOutDir, urlPath) {
     res.status(200).end(raw);
     return true;
   } catch (err) {
-    logger2.error("Error reading SSG data", err, { urlPath, ssgDataPath });
+    logger3.error("Error reading SSG data", err, { urlPath, ssgDataPath });
     return false;
   }
 }
 
 // modules/server/handlers/pages.ts
 init_globals();
+var import_path23 = __toESM(require("path"));
+function mergeMetadata(base, override) {
+  if (!base && !override) return null;
+  if (!base) return override;
+  if (!override) return base;
+  return {
+    // Simple fields: override wins
+    title: override.title ?? base.title,
+    description: override.description ?? base.description,
+    lang: override.lang ?? base.lang,
+    canonical: override.canonical ?? base.canonical,
+    robots: override.robots ?? base.robots,
+    themeColor: override.themeColor ?? base.themeColor,
+    viewport: override.viewport ?? base.viewport,
+    // Nested objects: shallow merge (override wins for each field)
+    openGraph: override.openGraph ? {
+      ...base.openGraph,
+      ...override.openGraph,
+      // For image, if override has image, use it entirely (don't merge)
+      image: override.openGraph.image ?? base.openGraph?.image
+    } : base.openGraph,
+    twitter: override.twitter ? {
+      ...base.twitter,
+      ...override.twitter
+    } : base.twitter,
+    // Arrays: override replaces base entirely (not merged)
+    metaTags: override.metaTags ?? base.metaTags,
+    links: override.links ?? base.links
+  };
+}
 function isDataRequest(req) {
   return req.query && req.query.__fw_data === "1" || req.headers["x-fw-data"] === "1";
 }
@@ -4177,22 +5336,59 @@ async function handlePageRequestInternal(options) {
         pathname: urlPath,
         locals: {}
       };
-      let loaderResult2 = await runRouteLoader(notFoundPage, ctx2);
+      const layoutProps2 = {};
+      if (notFoundPage.layoutServerHooks && notFoundPage.layoutServerHooks.length > 0) {
+        for (let i = 0; i < notFoundPage.layoutServerHooks.length; i++) {
+          const layoutServerHook = notFoundPage.layoutServerHooks[i];
+          if (layoutServerHook) {
+            try {
+              const layoutResult = await layoutServerHook(ctx2);
+              if (layoutResult.props) {
+                Object.assign(layoutProps2, layoutResult.props);
+              }
+            } catch (error) {
+              const reqLogger2 = getRequestLogger(req);
+              const layoutFile = notFoundPage.layoutFiles[i];
+              const relativeLayoutPath = layoutFile ? import_path23.default.relative(projectRoot || process.cwd(), layoutFile) : "unknown";
+              reqLogger2.warn("Layout server hook failed for not-found page", {
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : void 0,
+                layoutFile: relativeLayoutPath,
+                layoutIndex: i
+              });
+            }
+          }
+        }
+      }
+      let loaderResult2 = await runRouteServerHook(notFoundPage, ctx2);
       if (!loaderResult2.theme) {
         loaderResult2.theme = theme;
       }
-      const initialData2 = buildInitialData(urlPath, {}, loaderResult2);
+      const combinedProps2 = {
+        ...layoutProps2,
+        ...loaderResult2.props || {}
+      };
+      const combinedLoaderResult2 = {
+        ...loaderResult2,
+        props: combinedProps2
+      };
+      const initialData2 = buildInitialData(urlPath, {}, combinedLoaderResult2);
       const appTree2 = buildAppTree(notFoundPage, {}, initialData2.props);
       initialData2.notFound = true;
       const nonce2 = res.locals.nonce || void 0;
+      const entrypointFiles2 = [];
+      if (assetManifest?.entrypoints?.client) {
+        entrypointFiles2.push(...assetManifest.entrypoints.client.map((file) => `${STATIC_PATH}/${file}`));
+      }
       const documentTree2 = createDocumentTree({
         appTree: appTree2,
         initialData: initialData2,
         routerData,
-        meta: loaderResult2.metadata ?? null,
+        meta: combinedLoaderResult2.metadata ?? null,
         titleFallback: "Not found",
         descriptionFallback: "Loly demo",
         chunkHref: null,
+        entrypointFiles: entrypointFiles2,
         theme,
         clientJsPath,
         clientCssPath,
@@ -4208,8 +5404,8 @@ async function handlePageRequestInternal(options) {
         },
         onShellError(err) {
           didError2 = true;
-          const reqLogger = getRequestLogger(req);
-          reqLogger.error("SSR shell error", err, { route: "not-found" });
+          const reqLogger2 = getRequestLogger(req);
+          reqLogger2.error("SSR shell error", err, { route: "not-found" });
           if (!res.headersSent && errorPage) {
             renderErrorPageWithStream(errorPage, req, res, err, routeChunks, theme, projectRoot, env);
           } else if (!res.headersSent) {
@@ -4221,8 +5417,8 @@ async function handlePageRequestInternal(options) {
         },
         onError(err) {
           didError2 = true;
-          const reqLogger = getRequestLogger(req);
-          reqLogger.error("SSR error", err, { route: "not-found" });
+          const reqLogger2 = getRequestLogger(req);
+          reqLogger2.error("SSR error", err, { route: "not-found" });
         }
       });
       req.on("close", () => abort2());
@@ -4244,17 +5440,62 @@ async function handlePageRequestInternal(options) {
   if (res.headersSent) {
     return;
   }
+  const layoutProps = {};
+  const layoutMetadata = [];
+  const reqLogger = getRequestLogger(req);
+  if (route.layoutServerHooks && route.layoutServerHooks.length > 0) {
+    for (let i = 0; i < route.layoutServerHooks.length; i++) {
+      const layoutServerHook = route.layoutServerHooks[i];
+      if (layoutServerHook) {
+        try {
+          const layoutResult = await layoutServerHook(ctx);
+          if (layoutResult.props) {
+            Object.assign(layoutProps, layoutResult.props);
+          }
+          if (layoutResult.metadata) {
+            layoutMetadata.push(layoutResult.metadata);
+          }
+        } catch (error) {
+          const layoutFile = route.layoutFiles[i];
+          const relativeLayoutPath = layoutFile ? import_path23.default.relative(projectRoot || process.cwd(), layoutFile) : "unknown";
+          reqLogger.warn("Layout server hook failed", {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : void 0,
+            layoutFile: relativeLayoutPath,
+            route: route.pattern,
+            layoutIndex: i,
+            suggestion: "Check your layout.server.hook.ts file for errors"
+          });
+        }
+      }
+    }
+  }
   let loaderResult;
   try {
-    loaderResult = await runRouteLoader(route, ctx);
+    loaderResult = await runRouteServerHook(route, ctx);
     if (!loaderResult.theme) {
       loaderResult.theme = theme;
     }
   } catch (error) {
+    const relativePagePath = route.pageFile ? import_path23.default.relative(projectRoot || process.cwd(), route.pageFile) : "unknown";
+    reqLogger.error("Page server hook failed", {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : void 0,
+      pageFile: relativePagePath,
+      route: route.pattern,
+      pathname: urlPath,
+      suggestion: "Check your page.server.hook.ts (or server.hook.ts) file for errors"
+    });
     if (isDataReq) {
       res.statusCode = 500;
       res.setHeader("Content-Type", "application/json; charset=utf-8");
-      res.end(JSON.stringify({ error: true, message: String(error) }));
+      const errorResponse = {
+        error: true,
+        message: error instanceof Error ? error.message : String(error),
+        route: route.pattern,
+        pageFile: relativePagePath
+      };
+      res.end(JSON.stringify(errorResponse, null, 2));
       return;
     } else {
       if (errorPage) {
@@ -4265,8 +5506,28 @@ async function handlePageRequestInternal(options) {
       }
     }
   }
+  const combinedProps = {
+    ...layoutProps,
+    // Props from layouts (stable)
+    ...loaderResult.props || {}
+    // Props from page (overrides layout)
+  };
+  let combinedMetadata = null;
+  for (const layoutMeta of layoutMetadata) {
+    if (layoutMeta) {
+      combinedMetadata = mergeMetadata(combinedMetadata, layoutMeta);
+    }
+  }
+  if (loaderResult.metadata) {
+    combinedMetadata = mergeMetadata(combinedMetadata, loaderResult.metadata);
+  }
+  const combinedLoaderResult = {
+    ...loaderResult,
+    props: combinedProps,
+    metadata: combinedMetadata
+  };
   if (isDataReq) {
-    handleDataResponse(res, loaderResult, theme);
+    handleDataResponse(res, combinedLoaderResult, theme);
     return;
   }
   if (loaderResult.redirect) {
@@ -4281,7 +5542,7 @@ async function handlePageRequestInternal(options) {
     }
     return;
   }
-  const initialData = buildInitialData(urlPath, params, loaderResult);
+  const initialData = buildInitialData(urlPath, params, combinedLoaderResult);
   const appTree = buildAppTree(route, params, initialData.props);
   const chunkName = routeChunks[route.pattern];
   let chunkHref = null;
@@ -4293,14 +5554,19 @@ async function handlePageRequestInternal(options) {
     }
   }
   const nonce = res.locals.nonce || void 0;
+  const entrypointFiles = [];
+  if (assetManifest?.entrypoints?.client) {
+    entrypointFiles.push(...assetManifest.entrypoints.client.map((file) => `${STATIC_PATH}/${file}`));
+  }
   const documentTree = createDocumentTree({
     appTree,
     initialData,
     routerData,
-    meta: loaderResult.metadata,
+    meta: combinedLoaderResult.metadata,
     titleFallback: "Loly framework",
     descriptionFallback: "Loly demo",
     chunkHref,
+    entrypointFiles,
     theme,
     clientJsPath,
     clientCssPath,
@@ -4318,8 +5584,17 @@ async function handlePageRequestInternal(options) {
     },
     onShellError(err) {
       didError = true;
-      const reqLogger = getRequestLogger(req);
-      reqLogger.error("SSR shell error", err, { route: matched?.route?.pattern || "unknown" });
+      const reqLogger2 = getRequestLogger(req);
+      const routePattern = matched?.route?.pattern || "unknown";
+      reqLogger2.error("SSR shell error", err, { route: routePattern });
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      console.error(`
+\u274C [framework][ssr] Shell error for route "${routePattern}":`);
+      console.error(`   ${errorMessage}`);
+      if (err instanceof Error && err.stack) {
+        console.error(`   Stack: ${err.stack.split("\n").slice(0, 3).join("\n   ")}`);
+      }
+      console.error("\u{1F4A1} This usually indicates a React rendering error\n");
       if (!res.headersSent && errorPage) {
         renderErrorPageWithStream(errorPage, req, res, err, routeChunks, theme, projectRoot, env);
       } else if (!res.headersSent) {
@@ -4331,8 +5606,12 @@ async function handlePageRequestInternal(options) {
     },
     onError(err) {
       didError = true;
-      const reqLogger = getRequestLogger(req);
-      reqLogger.error("SSR error", err, { route: matched?.route?.pattern || "unknown" });
+      const reqLogger2 = getRequestLogger(req);
+      const routePattern = matched?.route?.pattern || "unknown";
+      reqLogger2.error("SSR error", err, { route: routePattern });
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      console.error(`\u26A0\uFE0F  [framework][ssr] Error during streaming for route "${routePattern}":`);
+      console.error(`   ${errorMessage}`);
     }
   });
   req.on("close", () => {
@@ -4349,11 +5628,43 @@ async function renderErrorPageWithStream(errorPage, req, res, error, routeChunks
       pathname: req.path,
       locals: { error }
     };
-    let loaderResult = await runRouteLoader(errorPage, ctx);
+    const layoutProps = {};
+    const reqLogger = getRequestLogger(req);
+    if (errorPage.layoutServerHooks && errorPage.layoutServerHooks.length > 0) {
+      for (let i = 0; i < errorPage.layoutServerHooks.length; i++) {
+        const layoutServerHook = errorPage.layoutServerHooks[i];
+        if (layoutServerHook) {
+          try {
+            const layoutResult = await layoutServerHook(ctx);
+            if (layoutResult.props) {
+              Object.assign(layoutProps, layoutResult.props);
+            }
+          } catch (err) {
+            const layoutFile = errorPage.layoutFiles[i];
+            const relativeLayoutPath = layoutFile ? import_path23.default.relative(projectRoot || process.cwd(), layoutFile) : "unknown";
+            reqLogger.warn("Layout server hook failed for error page", {
+              error: err instanceof Error ? err.message : String(err),
+              stack: err instanceof Error ? err.stack : void 0,
+              layoutFile: relativeLayoutPath,
+              layoutIndex: i
+            });
+          }
+        }
+      }
+    }
+    let loaderResult = await runRouteServerHook(errorPage, ctx);
     if (!loaderResult.theme && theme) {
       loaderResult.theme = theme;
     }
-    const initialData = buildInitialData(req.path, { error: String(error) }, loaderResult);
+    const combinedProps = {
+      ...layoutProps,
+      ...loaderResult.props || {}
+    };
+    const combinedLoaderResult = {
+      ...loaderResult,
+      props: combinedProps
+    };
+    const initialData = buildInitialData(req.path, { error: String(error) }, combinedLoaderResult);
     const routerData = buildRouterData(req);
     initialData.error = true;
     if (isDataReq) {
@@ -4363,8 +5674,8 @@ async function renderErrorPageWithStream(errorPage, req, res, error, routeChunks
         error: true,
         message: String(error),
         props: initialData.props,
-        metadata: loaderResult.metadata ?? null,
-        theme: loaderResult.theme ?? theme ?? null
+        metadata: combinedLoaderResult.metadata ?? null,
+        theme: combinedLoaderResult.theme ?? theme ?? null
       }));
       return;
     }
@@ -4382,11 +5693,15 @@ async function renderErrorPageWithStream(errorPage, req, res, error, routeChunks
       }
     }
     const nonce = res.locals.nonce || void 0;
+    const entrypointFiles = [];
+    if (assetManifest?.entrypoints?.client) {
+      entrypointFiles.push(...assetManifest.entrypoints.client.map((file) => `${STATIC_PATH}/${file}`));
+    }
     const documentTree = createDocumentTree({
       appTree,
       initialData,
       routerData,
-      meta: loaderResult.metadata ?? null,
+      meta: combinedLoaderResult.metadata ?? null,
       titleFallback: "Error",
       descriptionFallback: "An error occurred",
       chunkHref,
@@ -4407,8 +5722,8 @@ async function renderErrorPageWithStream(errorPage, req, res, error, routeChunks
       },
       onShellError(err) {
         didError = true;
-        const reqLogger = getRequestLogger(req);
-        reqLogger.error("Error rendering error page", err, { type: "shellError" });
+        const reqLogger2 = getRequestLogger(req);
+        reqLogger2.error("Error rendering error page", err, { type: "shellError" });
         if (!res.headersSent) {
           res.statusCode = 500;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
@@ -4418,8 +5733,8 @@ async function renderErrorPageWithStream(errorPage, req, res, error, routeChunks
       },
       onError(err) {
         didError = true;
-        const reqLogger = getRequestLogger(req);
-        reqLogger.error("Error in error page", err);
+        const reqLogger2 = getRequestLogger(req);
+        reqLogger2.error("Error in error page", err);
       }
     });
     req.on("close", () => {
@@ -4507,7 +5822,7 @@ async function getServerConfig(projectRoot) {
 }
 
 // modules/server/routes.ts
-var import_path21 = __toESM(require("path"));
+var import_path24 = __toESM(require("path"));
 function setupRoutes(options) {
   const {
     app,
@@ -4522,21 +5837,23 @@ function setupRoutes(options) {
     config
   } = options;
   const routeChunks = routeLoader.loadRouteChunks();
-  const ssgOutDir = import_path21.default.join(
-    config ? getBuildDir(projectRoot, config) : import_path21.default.join(projectRoot, BUILD_FOLDER_NAME),
+  const ssgOutDir = import_path24.default.join(
+    config ? getBuildDir(projectRoot, config) : import_path24.default.join(projectRoot, BUILD_FOLDER_NAME),
     "ssg"
   );
   app.all("/api/*", async (req, res) => {
     const apiRoutes = isDev && getRoutes ? getRoutes().apiRoutes : initialApiRoutes;
     const serverConfig = await getServerConfig(projectRoot);
     const strictPatterns = serverConfig.rateLimit?.strictPatterns || [];
+    const rateLimitConfig = serverConfig.rateLimit;
     await handleApiRequest({
       apiRoutes,
       urlPath: req.path,
       req,
       res,
       env: isDev ? "dev" : "prod",
-      strictRateLimitPatterns: strictPatterns
+      strictRateLimitPatterns: strictPatterns,
+      rateLimitConfig
     });
   });
   app.get("*", async (req, res) => {
@@ -4789,12 +6106,29 @@ var setupApplication = async ({
     corsOptions.origin = process.env.NODE_ENV === "development";
   }
   app.use((0, import_cors.default)(corsOptions));
-  if (rateLimit2 && process.env.NODE_ENV !== "development") {
-    const generalLimiter = createRateLimiter({
-      windowMs: rateLimit2.windowMs,
-      max: rateLimit2.max
-    });
-    app.use(generalLimiter);
+  if (rateLimit2) {
+    const shouldApply = process.env.NODE_ENV !== "development" || process.env.ENABLE_RATE_LIMIT === "true";
+    if (shouldApply) {
+      try {
+        const generalLimiter = createRateLimiterFromConfig(rateLimit2, false);
+        if (generalLimiter) {
+          app.use(generalLimiter);
+          const logger5 = createModuleLogger("server");
+          logger5.info("Rate limiting enabled", {
+            windowMs: rateLimit2.windowMs ?? 15 * 60 * 1e3,
+            max: rateLimit2.max ?? 100,
+            apiMax: rateLimit2.apiMax,
+            strictMax: rateLimit2.strictMax,
+            strictPatterns: rateLimit2.strictPatterns?.length ?? 0
+          });
+        }
+      } catch (error) {
+        const logger5 = createModuleLogger("server");
+        logger5.error("Failed to setup rate limiting", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
   }
   app.use((0, import_cookie_parser.default)());
   app.use(import_express2.default.json({ limit: bodyLimit }));
@@ -4809,22 +6143,31 @@ var setupApplication = async ({
 
 // src/server.ts
 var import_dotenv2 = __toESM(require("dotenv"));
-var envPath = import_path22.default.join(process.cwd(), ".env");
+var envPath = import_path25.default.join(process.cwd(), ".env");
 if (import_fs18.default.existsSync(envPath)) {
   import_dotenv2.default.config({ path: envPath });
 } else {
   import_dotenv2.default.config();
 }
-var logger3 = createModuleLogger("server");
+var logger4 = createModuleLogger("server");
 async function startServer(options = {}) {
   const isDev = options.isDev ?? process.env.NODE_ENV === "development";
   const projectRoot = options.rootDir ?? process.cwd();
-  const config = options.config ?? loadConfig(projectRoot);
+  let config;
+  try {
+    config = options.config ?? loadConfig(projectRoot);
+  } catch (error) {
+    if (error instanceof ConfigValidationError) {
+      console.error("\n" + error.message + "\n");
+      process.exit(1);
+    }
+    throw error;
+  }
   const port = options.port ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : void 0) ?? config.server.port;
   const host = process.env.HOST ?? (!isDev ? "0.0.0.0" : void 0) ?? config.server.host;
-  const appDir = options.appDir ?? (isDev ? getAppDir(projectRoot, config) : import_path22.default.join(getBuildDir(projectRoot, config), "server"));
+  const appDir = options.appDir ?? (isDev ? getAppDir(projectRoot, config) : import_path25.default.join(getBuildDir(projectRoot, config), "server"));
   if (!isDev && !import_fs18.default.existsSync(appDir)) {
-    logger3.error("Compiled directory not found", void 0, {
+    logger4.error("Compiled directory not found", void 0, {
       buildDir: config.directories.build,
       appDir,
       environment: "production"
@@ -4841,7 +6184,7 @@ async function startServer(options = {}) {
     isDev,
     config
   });
-  const routeLoader = isDev ? new FilesystemRouteLoader(appDir) : new ManifestRouteLoader(projectRoot);
+  const routeLoader = isDev ? new FilesystemRouteLoader(appDir, projectRoot) : new ManifestRouteLoader(projectRoot);
   setupWssEvents({
     httpServer,
     wssRoutes
@@ -4893,10 +6236,10 @@ async function startProdServer(options = {}) {
 }
 
 // modules/build/ssg/builder.ts
-var import_path26 = __toESM(require("path"));
+var import_path29 = __toESM(require("path"));
 
 // modules/build/ssg/path.ts
-var import_path23 = __toESM(require("path"));
+var import_path26 = __toESM(require("path"));
 function buildPathFromPattern(pattern, params) {
   const segments = pattern.split("/").filter(Boolean);
   const parts = [];
@@ -4925,12 +6268,12 @@ function buildPathFromPattern(pattern, params) {
 }
 function pathToOutDir(baseDir, urlPath) {
   const clean = urlPath === "/" ? "" : urlPath.replace(/^\/+/, "");
-  return import_path23.default.join(baseDir, clean);
+  return import_path26.default.join(baseDir, clean);
 }
 
 // modules/build/ssg/renderer.ts
 var import_fs19 = __toESM(require("fs"));
-var import_path24 = __toESM(require("path"));
+var import_path27 = __toESM(require("path"));
 var import_server3 = require("react-dom/server");
 init_globals();
 async function renderStaticRoute(projectRoot, ssgOutDir, route, urlPath, params) {
@@ -4947,6 +6290,10 @@ async function renderStaticRoute(projectRoot, ssgOutDir, route, urlPath, params)
       chunkHref = `${STATIC_PATH}/${chunkName}.js`;
     }
   }
+  const entrypointFiles = [];
+  if (assetManifest?.entrypoints?.client) {
+    entrypointFiles.push(...assetManifest.entrypoints.client.map((file) => `${STATIC_PATH}/${file}`));
+  }
   const req = {
     method: "GET",
     headers: {},
@@ -4976,32 +6323,79 @@ async function renderStaticRoute(projectRoot, ssgOutDir, route, urlPath, params)
       })
     );
   }
+  const layoutProps = {};
+  const layoutMetadata = [];
+  if (route.layoutServerHooks && route.layoutServerHooks.length > 0) {
+    for (let i = 0; i < route.layoutServerHooks.length; i++) {
+      const layoutServerHook = route.layoutServerHooks[i];
+      if (layoutServerHook) {
+        try {
+          const layoutResult = await layoutServerHook(ctx);
+          if (layoutResult.props) {
+            Object.assign(layoutProps, layoutResult.props);
+          }
+          if (layoutResult.metadata) {
+            layoutMetadata.push(layoutResult.metadata);
+          }
+        } catch (error) {
+          console.warn(
+            `\u26A0\uFE0F  [framework][ssg] Layout server hook ${i} failed for route ${route.pattern}:`,
+            error instanceof Error ? error.message : String(error)
+          );
+          if (error instanceof Error && error.stack) {
+            console.warn(`   Stack: ${error.stack.split("\n").slice(0, 3).join("\n   ")}`);
+          }
+        }
+      }
+    }
+  }
   let loaderResult = { props: {} };
   if (route.loader) {
     loaderResult = await route.loader(ctx);
   }
-  if (loaderResult.redirect || loaderResult.notFound) {
+  const combinedProps = {
+    ...layoutProps,
+    ...loaderResult.props || {}
+  };
+  let combinedMetadata = null;
+  for (const layoutMeta of layoutMetadata) {
+    if (layoutMeta) {
+      combinedMetadata = mergeMetadata(combinedMetadata, layoutMeta);
+    }
+  }
+  if (loaderResult.metadata) {
+    combinedMetadata = mergeMetadata(combinedMetadata, loaderResult.metadata);
+  }
+  const combinedLoaderResult = {
+    ...loaderResult,
+    props: combinedProps,
+    metadata: combinedMetadata
+  };
+  if (combinedLoaderResult.redirect || combinedLoaderResult.notFound) {
     return;
   }
-  const initialData = buildInitialData(urlPath, params, loaderResult);
+  const initialData = buildInitialData(urlPath, params, combinedLoaderResult);
   const routerData = buildRouterData(req);
   const appTree = buildAppTree(route, params, initialData.props);
   const documentTree = createDocumentTree({
     appTree,
     initialData,
     routerData,
-    meta: loaderResult.metadata,
+    meta: combinedLoaderResult.metadata,
     titleFallback: "My Framework Dev",
     descriptionFallback: "Static page generated by @lolyjs/core.",
     chunkHref,
+    entrypointFiles,
     clientJsPath,
-    clientCssPath
+    clientCssPath,
+    includeInlineScripts: true
+    // SSG needs inline scripts (renderToString doesn't support bootstrapScripts)
   });
   const html = "<!DOCTYPE html>" + (0, import_server3.renderToString)(documentTree);
   const dir = pathToOutDir(ssgOutDir, urlPath);
   ensureDir(dir);
-  const htmlFile = import_path24.default.join(dir, "index.html");
-  const dataFile = import_path24.default.join(dir, "data.json");
+  const htmlFile = import_path27.default.join(dir, "index.html");
+  const dataFile = import_path27.default.join(dir, "data.json");
   import_fs19.default.writeFileSync(htmlFile, html, "utf-8");
   import_fs19.default.writeFileSync(dataFile, JSON.stringify(initialData, null, 2), "utf-8");
 }
@@ -5009,7 +6403,7 @@ async function renderStaticRoute(projectRoot, ssgOutDir, route, urlPath, params)
 // modules/build/ssg/builder.ts
 init_globals();
 async function buildStaticPages(projectRoot, routes) {
-  const ssgOutDir = import_path26.default.join(projectRoot, BUILD_FOLDER_NAME, "ssg");
+  const ssgOutDir = import_path29.default.join(projectRoot, BUILD_FOLDER_NAME, "ssg");
   ensureDir(ssgOutDir);
   for (const route of routes) {
     if (route.dynamic !== "force-static") continue;
@@ -5019,12 +6413,15 @@ async function buildStaticPages(projectRoot, routes) {
     } else {
       if (!route.generateStaticParams) {
         console.warn(
-          `[framework][ssg] Route ${route.pattern} is marked as force-static but has no generateStaticParams function. Skipping.`
+          `\u26A0\uFE0F  [framework][ssg] Route "${route.pattern}" is marked as force-static but has no generateStaticParams function`
         );
+        console.warn(`   \u{1F4A1} Add a generateStaticParams export to enable static generation for this route`);
+        console.warn(`   Skipping this route...
+`);
         continue;
       }
       try {
-        console.log(`[framework][ssg] Generating static params for route: ${route.pattern}`);
+        console.log(`\u{1F4E6} [framework][ssg] Generating static params for route: ${route.pattern}`);
         let timeoutId = null;
         const timeoutPromise = new Promise((_, reject) => {
           timeoutId = setTimeout(() => {
@@ -5039,12 +6436,16 @@ async function buildStaticPages(projectRoot, routes) {
           clearTimeout(timeoutId);
         }
         allParams = sp;
-        console.log(`[framework][ssg] Generated ${sp.length} static params for route: ${route.pattern}`);
+        console.log(`   \u2705 Generated ${sp.length} static params for route: ${route.pattern}`);
       } catch (error) {
-        console.error(
-          `[framework][ssg] Error generating static params for route ${route.pattern}:`,
-          error
-        );
+        console.error(`
+\u274C [framework][ssg] Error generating static params for route "${route.pattern}":`);
+        console.error(error instanceof Error ? error.message : String(error));
+        if (error instanceof Error && error.stack) {
+          console.error(`   Stack: ${error.stack.split("\n").slice(0, 3).join("\n   ")}`);
+        }
+        console.error(`\u{1F4A1} Check your generateStaticParams function for this route
+`);
         throw error;
       }
     }
@@ -5053,11 +6454,11 @@ async function buildStaticPages(projectRoot, routes) {
       await renderStaticRoute(projectRoot, ssgOutDir, route, urlPath, params);
     }
   }
-  console.log(`[framework][ssg] Finished building all static pages`);
+  console.log(`\u2705 [framework][ssg] Finished building all static pages`);
 }
 
 // modules/build/bundler/server.ts
-var import_path28 = __toESM(require("path"));
+var import_path31 = __toESM(require("path"));
 var import_fs20 = __toESM(require("fs"));
 var import_esbuild = __toESM(require("esbuild"));
 init_globals();
@@ -5067,7 +6468,7 @@ function collectAppSources(appDir) {
   function walk(dir) {
     const items = import_fs20.default.readdirSync(dir, { withFileTypes: true });
     for (const item of items) {
-      const full = import_path28.default.join(dir, item.name);
+      const full = import_path31.default.join(dir, item.name);
       if (item.isDirectory()) {
         walk(full);
         continue;
@@ -5084,7 +6485,7 @@ function collectAppSources(appDir) {
   return entries;
 }
 async function buildServerApp(projectRoot, appDir) {
-  const outDir = import_path28.default.join(projectRoot, BUILD_FOLDER_NAME, "server");
+  const outDir = import_path31.default.join(projectRoot, BUILD_FOLDER_NAME, "server");
   const entryPoints = collectAppSources(appDir);
   ensureDir(outDir);
   if (entryPoints.length === 0) {
@@ -5102,12 +6503,12 @@ async function buildServerApp(projectRoot, appDir) {
     bundle: true,
     splitting: false,
     logLevel: "info",
-    tsconfig: import_path28.default.join(projectRoot, "tsconfig.json"),
+    tsconfig: import_path31.default.join(projectRoot, "tsconfig.json"),
     packages: "external"
   });
   for (const fileName of SERVER_FILES) {
-    const initTS = import_path28.default.join(projectRoot, `${fileName}.ts`);
-    const initJS = import_path28.default.join(outDir, `${fileName}.js`);
+    const initTS = import_path31.default.join(projectRoot, `${fileName}.ts`);
+    const initJS = import_path31.default.join(outDir, `${fileName}.js`);
     if (import_fs20.default.existsSync(initTS)) {
       await import_esbuild.default.build({
         entryPoints: [initTS],
@@ -5119,7 +6520,7 @@ async function buildServerApp(projectRoot, appDir) {
         sourcemap: true,
         bundle: false,
         logLevel: "info",
-        tsconfig: import_path28.default.join(projectRoot, "tsconfig.json")
+        tsconfig: import_path31.default.join(projectRoot, "tsconfig.json")
       });
     }
   }
@@ -5262,22 +6663,158 @@ function matchRouteClient(pathWithSearch, routes) {
 }
 
 // modules/runtime/client/metadata.ts
+function getOrCreateMeta(selector, attributes) {
+  let meta = document.querySelector(selector);
+  if (!meta) {
+    meta = document.createElement("meta");
+    if (attributes.name) meta.name = attributes.name;
+    if (attributes.property) meta.setAttribute("property", attributes.property);
+    if (attributes.httpEquiv) meta.httpEquiv = attributes.httpEquiv;
+    document.head.appendChild(meta);
+  }
+  return meta;
+}
+function getOrCreateLink(rel, href) {
+  const selector = `link[rel="${rel}"]`;
+  let link = document.querySelector(selector);
+  if (!link) {
+    link = document.createElement("link");
+    link.rel = rel;
+    link.href = href;
+    document.head.appendChild(link);
+  } else {
+    link.href = href;
+  }
+  return link;
+}
 function applyMetadata(md) {
   if (!md) return;
   if (md.title) {
     document.title = md.title;
   }
   if (md.description) {
-    let meta = document.querySelector(
-      'meta[name="description"]'
-    );
-    if (!meta) {
-      meta = document.createElement("meta");
-      meta.name = "description";
-      document.head.appendChild(meta);
-    }
+    const meta = getOrCreateMeta('meta[name="description"]', { name: "description" });
     meta.content = md.description;
   }
+  if (md.robots) {
+    const meta = getOrCreateMeta('meta[name="robots"]', { name: "robots" });
+    meta.content = md.robots;
+  }
+  if (md.themeColor) {
+    const meta = getOrCreateMeta('meta[name="theme-color"]', { name: "theme-color" });
+    meta.content = md.themeColor;
+  }
+  if (md.viewport) {
+    const meta = getOrCreateMeta('meta[name="viewport"]', { name: "viewport" });
+    meta.content = md.viewport;
+  }
+  if (md.canonical) {
+    getOrCreateLink("canonical", md.canonical);
+  }
+  if (md.openGraph) {
+    const og = md.openGraph;
+    if (og.title) {
+      const meta = getOrCreateMeta('meta[property="og:title"]', { property: "og:title" });
+      meta.content = og.title;
+    }
+    if (og.description) {
+      const meta = getOrCreateMeta('meta[property="og:description"]', { property: "og:description" });
+      meta.content = og.description;
+    }
+    if (og.type) {
+      const meta = getOrCreateMeta('meta[property="og:type"]', { property: "og:type" });
+      meta.content = og.type;
+    }
+    if (og.url) {
+      const meta = getOrCreateMeta('meta[property="og:url"]', { property: "og:url" });
+      meta.content = og.url;
+    }
+    if (og.image) {
+      if (typeof og.image === "string") {
+        const meta = getOrCreateMeta('meta[property="og:image"]', { property: "og:image" });
+        meta.content = og.image;
+      } else {
+        const meta = getOrCreateMeta('meta[property="og:image"]', { property: "og:image" });
+        meta.content = og.image.url;
+        if (og.image.width) {
+          const metaWidth = getOrCreateMeta('meta[property="og:image:width"]', { property: "og:image:width" });
+          metaWidth.content = String(og.image.width);
+        }
+        if (og.image.height) {
+          const metaHeight = getOrCreateMeta('meta[property="og:image:height"]', { property: "og:image:height" });
+          metaHeight.content = String(og.image.height);
+        }
+        if (og.image.alt) {
+          const metaAlt = getOrCreateMeta('meta[property="og:image:alt"]', { property: "og:image:alt" });
+          metaAlt.content = og.image.alt;
+        }
+      }
+    }
+    if (og.siteName) {
+      const meta = getOrCreateMeta('meta[property="og:site_name"]', { property: "og:site_name" });
+      meta.content = og.siteName;
+    }
+    if (og.locale) {
+      const meta = getOrCreateMeta('meta[property="og:locale"]', { property: "og:locale" });
+      meta.content = og.locale;
+    }
+  }
+  if (md.twitter) {
+    const twitter = md.twitter;
+    if (twitter.card) {
+      const meta = getOrCreateMeta('meta[name="twitter:card"]', { name: "twitter:card" });
+      meta.content = twitter.card;
+    }
+    if (twitter.title) {
+      const meta = getOrCreateMeta('meta[name="twitter:title"]', { name: "twitter:title" });
+      meta.content = twitter.title;
+    }
+    if (twitter.description) {
+      const meta = getOrCreateMeta('meta[name="twitter:description"]', { name: "twitter:description" });
+      meta.content = twitter.description;
+    }
+    if (twitter.image) {
+      const meta = getOrCreateMeta('meta[name="twitter:image"]', { name: "twitter:image" });
+      meta.content = twitter.image;
+    }
+    if (twitter.imageAlt) {
+      const meta = getOrCreateMeta('meta[name="twitter:image:alt"]', { name: "twitter:image:alt" });
+      meta.content = twitter.imageAlt;
+    }
+    if (twitter.site) {
+      const meta = getOrCreateMeta('meta[name="twitter:site"]', { name: "twitter:site" });
+      meta.content = twitter.site;
+    }
+    if (twitter.creator) {
+      const meta = getOrCreateMeta('meta[name="twitter:creator"]', { name: "twitter:creator" });
+      meta.content = twitter.creator;
+    }
+  }
+  if (md.metaTags && Array.isArray(md.metaTags)) {
+    md.metaTags.forEach((tag) => {
+      let selector = "";
+      if (tag.name) {
+        selector = `meta[name="${tag.name}"]`;
+      } else if (tag.property) {
+        selector = `meta[property="${tag.property}"]`;
+      } else if (tag.httpEquiv) {
+        selector = `meta[http-equiv="${tag.httpEquiv}"]`;
+      }
+      if (selector) {
+        const meta = getOrCreateMeta(selector, {
+          name: tag.name,
+          property: tag.property,
+          httpEquiv: tag.httpEquiv
+        });
+        meta.content = tag.content;
+      }
+    });
+  }
+  if (md.links && Array.isArray(md.links)) {
+    md.links.forEach((link) => {
+      getOrCreateLink(link.rel, link.href);
+    });
+  }
 }
 
 // modules/runtime/client/AppShell.tsx
@@ -5494,10 +7031,15 @@ async function handleErrorRoute(nextUrl, json, errorRoute, setState) {
     });
     return true;
   } catch (loadError) {
-    console.error(
-      "[client] Error loading error route components:",
-      loadError
-    );
+    console.error("\n\u274C [client] Error loading error route components:");
+    console.error(loadError);
+    if (loadError instanceof Error) {
+      console.error(`   Message: ${loadError.message}`);
+      if (loadError.stack) {
+        console.error(`   Stack: ${loadError.stack.split("\n").slice(0, 3).join("\n   ")}`);
+      }
+    }
+    console.error("\u{1F4A1} Falling back to full page reload\n");
     window.location.href = nextUrl;
     return false;
   }
@@ -5602,7 +7144,11 @@ async function handleNormalRoute(nextUrl, json, routes, setState) {
     searchParams: Object.fromEntries(url.searchParams.entries())
   };
   setRouterData(routerData);
-  const components = await matched.route.load();
+  const prefetched = prefetchedRoutes.get(matched.route);
+  const components = prefetched ? await prefetched : await matched.route.load();
+  if (!prefetched) {
+    prefetchedRoutes.set(matched.route, Promise.resolve(components));
+  }
   window.scrollTo({
     top: 0,
     behavior: "smooth"
@@ -5641,7 +7187,7 @@ async function navigate(nextUrl, handlers, options) {
       }
     }
     if (!ok) {
-      if (json && json.redirect) {
+      if (json?.redirect) {
         window.location.href = json.redirect.destination;
         return;
       }
@@ -5662,6 +7208,47 @@ async function navigate(nextUrl, handlers, options) {
     window.location.href = nextUrl;
   }
 }
+var prefetchedRoutes = /* @__PURE__ */ new WeakMap();
+function prefetchRoute(url, routes, notFoundRoute) {
+  const [pathname] = url.split("?");
+  const matched = matchRouteClient(pathname, routes);
+  if (!matched) {
+    if (notFoundRoute) {
+      const existing2 = prefetchedRoutes.get(notFoundRoute);
+      if (!existing2) {
+        const promise = notFoundRoute.load();
+        prefetchedRoutes.set(notFoundRoute, promise);
+      }
+    }
+    return;
+  }
+  const existing = prefetchedRoutes.get(matched.route);
+  if (!existing) {
+    const promise = matched.route.load();
+    prefetchedRoutes.set(matched.route, promise);
+  }
+}
+function createHoverHandler(routes, notFoundRoute) {
+  return function handleHover(ev) {
+    try {
+      const target = ev.target;
+      if (!target) return;
+      const anchor = target.closest("a[href]");
+      if (!anchor) return;
+      const href = anchor.getAttribute("href");
+      if (!href) return;
+      if (href.startsWith("#")) return;
+      const url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return;
+      if (anchor.target && anchor.target !== "_self") return;
+      const nextUrl = url.pathname + url.search;
+      const currentUrl = window.location.pathname + window.location.search;
+      if (nextUrl === currentUrl) return;
+      prefetchRoute(nextUrl, routes, notFoundRoute);
+    } catch (error) {
+    }
+  };
+}
 function createClickHandler(navigate2) {
   return function handleClick(ev) {
     try {
@@ -5772,17 +7359,20 @@ function AppShell({
     }
     const handleClick = createClickHandler(handleNavigateInternal);
     const handlePopState = createPopStateHandler(handleNavigateInternal);
+    const handleHover = createHoverHandler(routes, notFoundRoute);
     window.addEventListener("click", handleClick, false);
     window.addEventListener("popstate", handlePopState, false);
+    window.addEventListener("mouseover", handleHover, false);
     return () => {
       isMounted = false;
       window.removeEventListener("click", handleClick, false);
       window.removeEventListener("popstate", handlePopState, false);
+      window.removeEventListener("mouseover", handleHover, false);
     };
-  }, []);
+  }, [routes, notFoundRoute]);
   (0, import_react3.useEffect)(() => {
     const handleDataRefresh = () => {
-      const freshData = window?.__FW_DATA__;
+      const freshData = window[WINDOW_DATA_KEY2];
       if (!freshData) return;
       const currentPathname = window.location.pathname;
       const freshPathname = freshData.pathname;
@@ -5809,6 +7399,91 @@ function AppShell({
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(RouterContext.Provider, { value: { navigate: handleNavigate }, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(RouterView, { state }, routeKey) });
 }
 
+// modules/runtime/client/hot-reload.ts
+function setupHotReload2() {
+  const nodeEnv = process.env.NODE_ENV || "production";
+  const isDev = nodeEnv === "development";
+  console.log(`[hot-reload] NODE_ENV: ${nodeEnv}, isDev: ${isDev}`);
+  if (!isDev) {
+    console.log("[hot-reload] Skipping hot reload setup (not in development mode)");
+    return;
+  }
+  console.log("[hot-reload] Setting up hot reload client...");
+  let eventSource = null;
+  let reloadTimeout = null;
+  let reconnectTimeout = null;
+  let reconnectAttempts = 0;
+  const MAX_RECONNECT_ATTEMPTS = 10;
+  const RECONNECT_DELAY = 1e3;
+  const RELOAD_DELAY = 100;
+  function connect() {
+    try {
+      if (eventSource) {
+        console.log("[hot-reload] Closing existing EventSource connection");
+        eventSource.close();
+      }
+      const endpoint = "/__fw/hot";
+      eventSource = new EventSource(endpoint);
+      eventSource.addEventListener("ping", (event) => {
+        if ("data" in event) {
+          console.log("[hot-reload] \u2705 Connected to hot reload server");
+        }
+        reconnectAttempts = 0;
+      });
+      eventSource.addEventListener("message", (event) => {
+        const data = event.data;
+        if (data && typeof data === "string" && data.startsWith("reload:")) {
+          const filePath = data.slice(7);
+          console.log(`[hot-reload] \u{1F4DD} File changed: ${filePath}, reloading...`);
+          if (reloadTimeout) {
+            clearTimeout(reloadTimeout);
+          }
+          reloadTimeout = setTimeout(() => {
+            try {
+              window.location.reload();
+            } catch (error) {
+              console.error("[hot-reload] \u274C Error reloading page:", error);
+              setTimeout(() => window.location.reload(), 100);
+            }
+          }, RELOAD_DELAY);
+        }
+      });
+      eventSource.onopen = () => {
+        reconnectAttempts = 0;
+      };
+      eventSource.onerror = (error) => {
+        const states = ["CONNECTING", "OPEN", "CLOSED"];
+        const state = states[eventSource?.readyState ?? 0] || "UNKNOWN";
+        if (eventSource?.readyState === EventSource.CONNECTING) {
+          console.log("[hot-reload] \u23F3 Still connecting...");
+          return;
+        } else if (eventSource?.readyState === EventSource.OPEN) {
+          console.warn("[hot-reload] \u26A0\uFE0F Connection error (but connection is open):", error);
+        } else {
+          console.warn(`[hot-reload] \u274C Connection closed (readyState: ${state})`);
+          if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
+            reconnectAttempts++;
+            const delay = RECONNECT_DELAY * reconnectAttempts;
+            if (reconnectTimeout) {
+              clearTimeout(reconnectTimeout);
+            }
+            reconnectTimeout = setTimeout(() => {
+              console.log(`[hot-reload] \u{1F504} Reconnecting... (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})`);
+              connect();
+            }, delay);
+          } else {
+            console.error("[hot-reload] \u274C Max reconnect attempts reached. Please refresh the page manually.");
+          }
+        }
+      };
+    } catch (error) {
+      console.error("[hot-reload] \u274C Failed to create EventSource:", error);
+      console.error("[hot-reload] EventSource may not be supported in this browser.");
+    }
+  }
+  connect();
+}
+
 // modules/runtime/client/bootstrap.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
 async function loadInitialRoute(initialUrl, initialData, routes, notFoundRoute, errorRoute) {
@@ -5850,101 +7525,91 @@ async function loadInitialRoute(initialUrl, initialData, routes, notFoundRoute,
     props: initialData?.props ?? {}
   };
 }
-function setupHotReload2() {
-  const nodeEnv = typeof process !== "undefined" && process.env?.NODE_ENV || "production";
-  const isDev = nodeEnv !== "production";
-  if (!isDev) {
-    return;
+function initializeRouterData(initialUrl, initialData) {
+  let routerData = getRouterData();
+  if (!routerData) {
+    const url = new URL(initialUrl, window.location.origin);
+    routerData = {
+      pathname: url.pathname,
+      params: initialData?.params || {},
+      searchParams: Object.fromEntries(url.searchParams.entries())
+    };
+    setRouterData(routerData);
   }
+}
+async function hydrateInitialRoute(container, initialUrl, initialData, routes, notFoundRoute, errorRoute) {
   try {
-    console.log("[hot-reload] Attempting to connect to /__fw/hot...");
-    const eventSource = new EventSource("/__fw/hot");
-    let reloadTimeout = null;
-    eventSource.addEventListener("message", (event) => {
-      const data = event.data;
-      if (data && data.startsWith("reload:")) {
-        const filePath = data.slice(7);
-        console.log(`[hot-reload] File changed: ${filePath}`);
-        if (reloadTimeout) {
-          clearTimeout(reloadTimeout);
-        }
-        reloadTimeout = setTimeout(() => {
-          console.log("[hot-reload] Reloading page...");
-          window.location.reload();
-        }, 500);
-      }
-    });
-    eventSource.addEventListener("ping", () => {
-      console.log("[hot-reload] \u2713 Connected to hot reload server");
-    });
-    eventSource.onopen = () => {
-      console.log("[hot-reload] \u2713 SSE connection opened");
-    };
-    eventSource.onerror = (error) => {
-      const states = ["CONNECTING", "OPEN", "CLOSED"];
-      const state = states[eventSource.readyState] || "UNKNOWN";
-      if (eventSource.readyState === EventSource.CONNECTING) {
-        console.log("[hot-reload] Connecting...");
-      } else if (eventSource.readyState === EventSource.OPEN) {
-        console.warn("[hot-reload] Connection error (but connection is open):", error);
-      } else {
-        console.log("[hot-reload] Connection closed (readyState:", state, ")");
+    const initialState = await loadInitialRoute(
+      initialUrl,
+      initialData,
+      routes,
+      notFoundRoute,
+      errorRoute
+    );
+    if (initialData?.metadata) {
+      try {
+        applyMetadata(initialData.metadata);
+      } catch (metadataError) {
+        console.warn("[client] Error applying metadata:", metadataError);
       }
-    };
+    }
+    (0, import_client5.hydrateRoot)(
+      container,
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        AppShell,
+        {
+          initialState,
+          routes,
+          notFoundRoute,
+          errorRoute
+        }
+      )
+    );
   } catch (error) {
-    console.log("[hot-reload] EventSource not supported or error:", error);
+    console.error(
+      "[client] Error loading initial route components for",
+      initialUrl,
+      error
+    );
+    throw error;
   }
 }
 function bootstrapClient(routes, notFoundRoute, errorRoute = null) {
-  console.log("[client] Bootstrap starting, setting up hot reload...");
   setupHotReload2();
-  (async function bootstrap() {
-    const container = document.getElementById(APP_CONTAINER_ID2);
-    const initialData = getWindowData();
-    if (!container) {
-      console.error(`Container #${APP_CONTAINER_ID2} not found for hydration`);
-      return;
-    }
-    const initialUrl = window.location.pathname + window.location.search;
-    let routerData = getRouterData();
-    if (!routerData) {
-      const url = new URL(initialUrl, window.location.origin);
-      routerData = {
-        pathname: url.pathname,
-        params: initialData?.params || {},
-        searchParams: Object.fromEntries(url.searchParams.entries())
-      };
-      setRouterData(routerData);
-    }
+  (async () => {
     try {
-      const initialState = await loadInitialRoute(
+      const container = document.getElementById(APP_CONTAINER_ID2);
+      if (!container) {
+        console.error(`
+\u274C [client] Hydration failed: Container #${APP_CONTAINER_ID2} not found`);
+        console.error("\u{1F4A1} This usually means:");
+        console.error("  \u2022 The HTML structure doesn't match what React expects");
+        console.error("  \u2022 The container was removed before hydration");
+        console.error("  \u2022 There's a mismatch between SSR and client HTML\n");
+        return;
+      }
+      const initialData = getWindowData();
+      const initialUrl = window.location.pathname + window.location.search;
+      initializeRouterData(initialUrl, initialData);
+      await hydrateInitialRoute(
+        container,
         initialUrl,
         initialData,
         routes,
         notFoundRoute,
         errorRoute
       );
-      if (initialData?.metadata) {
-        applyMetadata(initialData.metadata);
-      }
-      (0, import_client5.hydrateRoot)(
-        container,
-        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
-          AppShell,
-          {
-            initialState,
-            routes,
-            notFoundRoute,
-            errorRoute
-          }
-        )
-      );
     } catch (error) {
-      console.error(
-        "[client] Error loading initial route components for",
-        initialUrl,
-        error
-      );
+      console.error("\n\u274C [client] Fatal error during bootstrap:");
+      console.error(error);
+      if (error instanceof Error) {
+        console.error("\nError details:");
+        console.error(`  Message: ${error.message}`);
+        if (error.stack) {
+          console.error(`  Stack: ${error.stack}`);
+        }
+      }
+      console.error("\n\u{1F4A1} Attempting page reload to recover...\n");
       window.location.reload();
     }
   })();
@@ -5972,11 +7637,11 @@ var ValidationError = class extends Error {
   format() {
     const formatted = {};
     for (const error of this.errors) {
-      const path25 = error.path.join(".");
-      if (!formatted[path25]) {
-        formatted[path25] = [];
+      const path28 = error.path.join(".");
+      if (!formatted[path28]) {
+        formatted[path28] = [];
       }
-      formatted[path25].push(error.message);
+      formatted[path28].push(error.message);
     }
     return formatted;
   }