webspresso 0.0.97 → 0.0.99

package/src/file-router.js

@@ -8,14 +8,28 @@ const path = require('path');
 const { ZodError } = require('zod');
 const { compileSchema, invalidateSchema } = require('../core/compileSchema');
 const { applySchema } = require('../core/applySchema');
-const { createHelpers } = require('./helpers');
+const { createHelpers, getAssetManager } = require('./helpers');
 const {
   loadNjkRouteTemplate,
   parseNjkFrontmatter,
   frontmatterToPatches,
   clearNjkFrontmatterCaches,
+  registerClearHook,
 } = require('./njk-frontmatter');
 const { renderStream } = require('../core/ssr/stream');
+const {
+  loadCascadingMiddlewares,
+  runMiddlewareChain,
+  findCascadingLayouts,
+  executeCascadingLayoutLoads,
+  applyCascadingLayouts,
+  templateHasExtends,
+} = require('./routing/cascading');
+const {
+  isMiddlewareFactory,
+  resolveNamedMiddleware,
+  resolveMiddlewares,
+} = require('./routing/middleware-resolver');
 
 const NOOP = () => {};
 const EMPTY_OBJECT = Object.freeze({});
@@ -27,12 +41,30 @@ const i18nCache = new Map();
 // Cache for merged i18n (key: `${pagesDir}::${routeDir}::${locale}`, value: { globalMtime, routeMtime, data })
 const mergedI18nCache = new Map();
 
+// Cache for translator instances in production
+const translatorCache = new Map();
+
+function clearTranslatorCache() {
+  translatorCache.clear();
+}
+
 // Cache for route configs in production
 const configCache = new Map();
 
 // Dev-only: avoid require() on every SSR request when the .js file is unchanged (mtime)
 const routeConfigDevCache = new Map();
 
+// Cache for compiled frontmatter string templates (key: fullPath, value: compiled Template)
+const compiledStringTemplateCache = new Map();
+
+function clearCompiledStringTemplateCache() {
+  compiledStringTemplateCache.clear();
+}
+
+if (typeof registerClearHook === 'function') {
+  registerClearHook(clearCompiledStringTemplateCache);
+}
+
 // Cache for API filename -> { method, baseName } (basename keys; stable per process)
 const methodFromFilenameCache = new Map();
 
@@ -43,6 +75,8 @@ const MAX_LOCALE_LEN = 16;
 
 let cachedSupportedLocalesRaw = null;
 let cachedSupportedLocaleSet = null;
+let cachedDefaultLocaleKey = null;
+let cachedDefaultLocale = 'en';
 
 /** @returns {Set<string>} */
 function parseSupportedLocaleSet() {
@@ -57,6 +91,27 @@ function parseSupportedLocaleSet() {
   return cachedSupportedLocaleSet;
 }
 
+/**
+ * Get default locale matching supported set
+ * @param {Set<string>} [supported]
+ * @returns {string}
+ */
+function getDefaultLocale(supported = parseSupportedLocaleSet()) {
+  const rawDef = process.env.DEFAULT_LOCALE || 'en';
+  const rawSupp = process.env.SUPPORTED_LOCALES || 'en';
+  const key = rawDef + '|' + rawSupp;
+  if (key === cachedDefaultLocaleKey && cachedDefaultLocale) {
+    return cachedDefaultLocale;
+  }
+  cachedDefaultLocaleKey = key;
+  const defaultCand = normalizeLocaleCandidate(rawDef);
+  cachedDefaultLocale =
+    pickMatchingLocale(defaultCand, supported)
+    ?? (supported.has('en') ? 'en' : [...supported][0])
+    ?? 'en';
+  return cachedDefaultLocale;
+}
+
 /**
  * @param {string} raw
  * @returns {string|null}
@@ -131,6 +186,73 @@ function escapeRegExp(s) {
   return String(s).replace(/[\\^$*+?.()|[\]{}]/g, '\\$&');
 }
 
+/**
+ * Checks if a path segment is a route group, e.g. '(marketing)', '(auth)'.
+ * Route groups are enclosed in parentheses and do not affect the public URL path.
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isRouteGroupSegment(segment) {
+  return (
+    typeof segment === 'string' &&
+    segment.length > 2 &&
+    segment.charCodeAt(0) === 40 /* '(' */ &&
+    segment.charCodeAt(segment.length - 1) === 41 /* ')' */
+  );
+}
+
+/**
+ * Strips route group segments from a slash-separated route path.
+ * E.g., '(marketing)/about' -> 'about'
+ *       '/(auth)/login' -> '/login'
+ *       '/(marketing)/(sub)/page' -> '/page'
+ *       '(marketing)/index' -> 'index'
+ * @param {string} route
+ * @returns {string}
+ */
+function stripRouteGroups(route) {
+  if (!route || typeof route !== 'string' || !route.includes('(')) {
+    return route;
+  }
+  const hadLeadingSlash = route.startsWith('/');
+  const rawSegments = route.split('/');
+  const filtered = rawSegments.filter((seg) => !isRouteGroupSegment(seg));
+
+  if (filtered.length === 0 || (filtered.length === 1 && filtered[0] === '')) {
+    return hadLeadingSlash ? '/' : '';
+  }
+
+  let res = filtered.join('/');
+  if (hadLeadingSlash && !res.startsWith('/')) {
+    res = '/' + res;
+  }
+  return res;
+}
+
+/**
+ * Checks if a file path belongs to an API route, accounting for optional parent route groups.
+ * E.g., 'api/users.get.js' -> true
+ *       'api/(v1)/users.get.js' -> true
+ *       '(marketing)/api/newsletter.post.js' -> true
+ *       'about.njk' -> false
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isApiRouteFile(file) {
+  if (!file || typeof file !== 'string') return false;
+  const normalized = file.split(/[/\\]/).join('/');
+  if (normalized.startsWith('api/')) return true;
+  const parts = normalized.split('/');
+  const apiIndex = parts.indexOf('api');
+  if (apiIndex > 0) {
+    const prefix = parts.slice(0, apiIndex);
+    if (prefix.every(isRouteGroupSegment)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Convert a file path to an Express route pattern
  * @param {string} filePath - Relative path from pages/
@@ -144,11 +266,14 @@ function filePathToRoute(filePath, ext) {
   // Normalize path separators to forward slashes (handle both / and \)
   route = route.split(path.sep).join('/');
   route = route.split('\\').join('/'); // Also handle literal backslashes
+
+  // Strip route group segments (e.g. (marketing), (auth), (dashboard))
+  route = stripRouteGroups(route);
   
   // Handle index files
   if (route.endsWith('/index')) {
     route = route.slice(0, -6) || '/';
-  } else if (route === 'index') {
+  } else if (route === 'index' || route === '') {
     route = '/';
   }
   
@@ -271,29 +396,31 @@ function extractMethodFromFilename(filename) {
 
 /**
  * Whether `load()` return values for `stylesheets` and `scripts` are promoted to
- * `pageHead` in Nunjucks (see `createApp({ pageAssets })`).
- * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean}|null|undefined} raw
- * @returns {{ enabled: boolean, stylesheets: boolean, scripts: boolean }}
+ * `pageHead` in Nunjucks (see `createApp({ pageAssets })`), with optional automatic
+ * per-route script/stylesheet discovery.
+ * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean, auto?: boolean}|null|undefined} raw
+ * @returns {{ enabled: boolean, stylesheets: boolean, scripts: boolean, auto: boolean }}
  */
 function resolvePageAssets(raw) {
   if (raw === true) {
-    return { enabled: true, stylesheets: true, scripts: true };
+    return { enabled: true, stylesheets: true, scripts: true, auto: true };
   }
   if (raw == null || raw === false) {
-    return { enabled: false, stylesheets: false, scripts: false };
+    return { enabled: false, stylesheets: false, scripts: false, auto: false };
   }
   if (typeof raw === 'object') {
     const on = raw.enabled !== false;
     if (!on) {
-      return { enabled: false, stylesheets: false, scripts: false };
+      return { enabled: false, stylesheets: false, scripts: false, auto: false };
     }
     return {
       enabled: true,
       stylesheets: raw.stylesheets !== false,
       scripts: raw.scripts !== false,
+      auto: raw.auto !== false,
     };
   }
-  return { enabled: false, stylesheets: false, scripts: false };
+  return { enabled: false, stylesheets: false, scripts: false, auto: false };
 }
 
 /**
@@ -306,11 +433,13 @@ function toList(v) {
 }
 
 /**
- * @param {{ enabled: boolean, stylesheets: boolean, scripts: boolean }} cfg
+ * @param {{ enabled: boolean, stylesheets: boolean, scripts: boolean, auto?: boolean }} cfg
  * @param {Object} data
+ * @param {{ file?: string, routePath?: string }} [routeInfo={}]
+ * @param {Object|null} [assetManager=null]
  * @returns {{ data: Object, pageHead: { stylesheets: unknown[], scripts: unknown[] }|null, pageAssets: boolean }}
  */
-function applyPageAssetsToTemplateData(cfg, data) {
+function applyPageAssetsToTemplateData(cfg, data, routeInfo = {}, assetManager = null) {
   if (!cfg || !cfg.enabled) {
     return { data, pageHead: null, pageAssets: false };
   }
@@ -325,6 +454,40 @@ function applyPageAssetsToTemplateData(cfg, data) {
     scriptItems = toList(out.scripts);
     delete out.scripts;
   }
+
+  // Auto-discover page assets from route if enabled
+  if (cfg.auto && assetManager && (routeInfo.file || routeInfo.routePath)) {
+    const candidates = typeof assetManager.getRouteAssetCandidates === 'function'
+      ? assetManager.getRouteAssetCandidates(routeInfo.file, routeInfo.routePath)
+      : [];
+
+    if (cfg.stylesheets) {
+      for (const cand of candidates) {
+        if (typeof assetManager.hasPageCss === 'function' && assetManager.hasPageCss(cand)) {
+          const cssUrl = assetManager.pageCssUrl(cand);
+          const already = styles.some((s) => (typeof s === 'string' ? s === cssUrl : s?.href === cssUrl));
+          if (!already) {
+            styles.push(cssUrl);
+          }
+          break;
+        }
+      }
+    }
+
+    if (cfg.scripts) {
+      for (const cand of candidates) {
+        if (typeof assetManager.hasPageJs === 'function' && assetManager.hasPageJs(cand)) {
+          const jsUrl = assetManager.pageJsUrl(cand);
+          const already = scriptItems.some((s) => (typeof s === 'string' ? s === jsUrl : s?.src === jsUrl));
+          if (!already) {
+            scriptItems.push({ src: jsUrl, defer: true });
+          }
+          break;
+        }
+      }
+    }
+  }
+
   return {
     data: out,
     pageHead: { stylesheets: styles, scripts: scriptItems },
@@ -492,15 +655,25 @@ function getPluralRules(locale) {
   return pr;
 }
 
+const KEY_PARTS_CACHE = new Map();
+
 function resolveTranslationValue(dict, key) {
-  if (!dict || typeof dict !== 'object') return undefined;
+  if (!dict || typeof dict !== 'object' || typeof key !== 'string') return undefined;
   if (dict[key] !== undefined) return dict[key];
+  if (!key.includes('.')) return undefined;
+
+  let parts = KEY_PARTS_CACHE.get(key);
+  if (!parts) {
+    parts = key.split('.');
+    if (KEY_PARTS_CACHE.size < 1000) {
+      KEY_PARTS_CACHE.set(key, parts);
+    }
+  }
 
-  const parts = key.split('.');
   let curr = dict;
-  for (const part of parts) {
+  for (let i = 0; i < parts.length; i++) {
     if (curr && typeof curr === 'object') {
-      curr = curr[part];
+      curr = curr[parts[i]];
     } else {
       return undefined;
     }
@@ -726,25 +899,37 @@ function loadGlobalHooks(pagesDir, isDev) {
  * @param {string} hookName - Hook name
  * @param {Object} ctx - Context object
  */
-async function executeHook(hooks, hookName, ctx, ...extra) {
-  if (hooks && typeof hooks[hookName] === 'function') {
-    await hooks[hookName](ctx, ...extra);
+function executeHook(hooks, hookName, ctx, ...extra) {
+  if (!hooks || typeof hooks[hookName] !== 'function') {
+    return;
   }
+  return hooks[hookName](ctx, ...extra);
+}
+
+function runHooks(globalHooks, routeHooks, hookName, ctx, ...extra) {
+  const gFn = globalHooks ? globalHooks[hookName] : undefined;
+  const rFn = routeHooks ? routeHooks[hookName] : undefined;
+  if (typeof gFn !== 'function' && typeof rFn !== 'function') return;
+  return (async () => {
+    if (typeof gFn === 'function') {
+      const gRes = gFn(ctx, ...extra);
+      if (gRes && typeof gRes.then === 'function') await gRes;
+    }
+    if (typeof rFn === 'function') {
+      const rRes = rFn(ctx, ...extra);
+      if (rRes && typeof rRes.then === 'function') await rRes;
+    }
+  })();
 }
 
 /**
  * Detect locale from request
  * @param {Object} req - Express request
+ * @param {Set<string>} [supported] - Optional precomputed supported locales set
+ * @param {string} [def] - Optional precomputed default locale
  * @returns {string} Locale code
  */
-function detectLocale(req) {
-  const supported = parseSupportedLocaleSet();
-  const defaultCand = normalizeLocaleCandidate(process.env.DEFAULT_LOCALE || 'en');
-  const def =
-    pickMatchingLocale(defaultCand, supported)
-    ?? (supported.has('en') ? 'en' : [...supported][0])
-    ?? 'en';
-
+function detectLocale(req, supported = parseSupportedLocaleSet(), def = getDefaultLocale(supported)) {
   if (req.query && req.query.lang != null && req.query.lang !== '') {
     const q = normalizeLocaleCandidate(String(req.query.lang));
     const hit = pickMatchingLocale(q, supported);
@@ -768,86 +953,6 @@ function detectLocale(req) {
   return def;
 }
 
-/**
- * True when the registry entry is (options) => (req, res, next) => …
- * Express handlers typically have length >= 2 (req, res) or 3 (req, res, next).
- */
-function isMiddlewareFactory(fn) {
-  return typeof fn === 'function' && fn.length <= 1;
-}
-
-/**
- * Resolve a named middleware from createApp({ middlewares }).
- * @param {string} name
- * @param {Function} entry
- * @param {boolean} fromTuple - true when route used ['name', options]
- * @param {unknown} tupleOptions - second element of the tuple (only when fromTuple)
- * @param {Object} middlewareRegistry - for error messages
- * @returns {Function} Express middleware
- */
-function resolveNamedMiddleware(name, entry, fromTuple, tupleOptions, middlewareRegistry) {
-  if (!entry) {
-    throw new Error(`Middleware "${name}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
-  }
-  if (typeof entry !== 'function') {
-    throw new Error(`Middleware "${name}" must be a function`);
-  }
-
-  if (fromTuple) {
-    if (!isMiddlewareFactory(entry)) {
-      throw new Error(
-        `Middleware "${name}" must be a factory (options) => (req, res, next) => … when using ["${name}", options] tuple form`
-      );
-    }
-    const produced = entry(tupleOptions);
-    if (typeof produced !== 'function') {
-      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
-    }
-    return produced;
-  }
-
-  if (isMiddlewareFactory(entry)) {
-    const produced = entry({});
-    if (typeof produced !== 'function') {
-      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
-    }
-    return produced;
-  }
-
-  return entry;
-}
-
-/**
- * Resolve middleware from config — functions, string names, or [name, options] tuples
- * @param {Array} middlewareConfig - middleware functions, names, or ['name', options] tuples
- * @param {Object} middlewareRegistry - Named middleware registry (plain handlers or option factories)
- * @returns {Array} Array of resolved middleware functions
- */
-function resolveMiddlewares(middlewareConfig, middlewareRegistry = EMPTY_OBJECT) {
-  if (!middlewareConfig || !Array.isArray(middlewareConfig) || middlewareConfig.length === 0) {
-    return EMPTY_ARRAY;
-  }
-  
-  return middlewareConfig.map((mw, index) => {
-    if (typeof mw === 'function') {
-      return mw;
-    }
-    
-    if (typeof mw === 'string') {
-      return resolveNamedMiddleware(mw, middlewareRegistry[mw], false, undefined, middlewareRegistry);
-    }
-
-    if (Array.isArray(mw) && mw.length === 2 && typeof mw[0] === 'string') {
-      const name = mw[0];
-      return resolveNamedMiddleware(name, middlewareRegistry[name], true, mw[1], middlewareRegistry);
-    }
-    
-    throw new Error(
-      `Invalid middleware at index ${index}: must be a function, string name, or [name, options] tuple`
-    );
-  });
-}
-
 /**
  * Mount all pages as routes on the Express app
  * @param {Object} app - Express app
@@ -971,7 +1076,7 @@ function mountPages(app, options) {
   
   for (const file of files) {
     const ext = path.extname(file);
-    const isApi = file.startsWith('api' + path.sep) || file.startsWith('api/');
+    const isApi = isApiRouteFile(file);
     
     if (isApi && ext === '.js') {
       // API route
@@ -1064,10 +1169,10 @@ function mountPages(app, options) {
             }
           }
           // Same instance as createApp({ db }) / getAppContext().db — available to handler & route middleware
-          if (db != null) {
+          if (db != null && !req.db) {
             req.db = db;
           }
-          if (serviceRegistry != null) {
+          if (serviceRegistry != null && !req.service) {
             req.service = (name, input, opts) =>
               serviceRegistry.call(name, input, { req, res, db }, opts);
           }
@@ -1107,19 +1212,32 @@ function mountPages(app, options) {
             throw err;
           }
           
+          // Run cascading folder middlewares (_middleware.js)
+          const cascadingMw = loadCascadingMiddlewares(absolutePagesDir, route.file, middlewares, isDev);
+          if (cascadingMw.length) {
+            await runMiddlewareChain(cascadingMw, req, res);
+            if (res.headersSent) return;
+          }
+
           // Run middleware if defined (resolved at route registration — required for stateful middleware like express-rate-limit)
           if (preResolvedMw.length) {
-            for (const mw of preResolvedMw) {
-              await new Promise((resolve, reject) => {
-                mw(req, res, (err) => {
-                  if (err) reject(err);
-                  else resolve();
-                });
-              });
-            }
+            await runMiddlewareChain(preResolvedMw, req, res);
+            if (res.headersSent) return;
           }
-          
-          await fn(req, res, next);
+          const apiCtx = Object.assign((err) => next(err), {
+            req,
+            res,
+            next,
+            params: req.params || {},
+            query: req.query || {},
+            body: req.body || {},
+            input: req.input,
+            service: req.service,
+            db,
+            sse: res.sse,
+          });
+
+          await fn(req, res, apiCtx);
         } catch (err) {
           console.error(`API error ${route.routePath}:`, err);
           const hookCtx = { req, res, error: err };
@@ -1159,20 +1277,38 @@ function mountPages(app, options) {
             }
           }
           // Detect locale
-          const locale = detectLocale(req);
-          const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
+          const supported = parseSupportedLocaleSet();
+          const defaultLocale = getDefaultLocale(supported);
+          const locale = detectLocale(req, supported, defaultLocale);
           
           // Load translations (primary + fallback)
-          const translations = loadI18n(absolutePagesDir, route.routeDir, locale, isDev);
-          const fallbackTranslations = (locale !== defaultLocale)
-            ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale, isDev)
-            : EMPTY_OBJECT;
-
-          const t = createTranslator(translations, {
-            locale,
-            fallbackTranslations,
-            fallbackLocale: defaultLocale,
-          });
+          let t;
+          if (!isDev) {
+            const transKey = `${absolutePagesDir}::${route.routeDir}::${locale}::${defaultLocale}`;
+            t = translatorCache.get(transKey);
+            if (!t) {
+              const translations = loadI18n(absolutePagesDir, route.routeDir, locale, false);
+              const fallbackTranslations = (locale !== defaultLocale)
+                ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale, false)
+                : EMPTY_OBJECT;
+              t = createTranslator(translations, {
+                locale,
+                fallbackTranslations,
+                fallbackLocale: defaultLocale,
+              });
+              translatorCache.set(transKey, t);
+            }
+          } else {
+            const translations = loadI18n(absolutePagesDir, route.routeDir, locale, true);
+            const fallbackTranslations = (locale !== defaultLocale)
+              ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale, true)
+              : EMPTY_OBJECT;
+            t = createTranslator(translations, {
+              locale,
+              fallbackTranslations,
+              fallbackLocale: defaultLocale,
+            });
+          }
           
           // Load route config
           const config = isDev ? loadRouteConfig(route.configPath, true) : mountConfig;
@@ -1190,6 +1326,8 @@ function mountPages(app, options) {
         }
         
         const njkTpl = loadNjkRouteTemplate(route.fullPath, isDev);
+        const metaTitle = t('meta.title');
+        const metaDesc = t('meta.description');
 
         const ctx = {
           req,
@@ -1208,8 +1346,8 @@ function mountPages(app, options) {
           },
           data: { ...njkTpl.dataPatch },
           meta: {
-            title: t('meta.title') !== 'meta.title' ? t('meta.title') : null,
-            description: t('meta.description') !== 'meta.description' ? t('meta.description') : null,
+            title: metaTitle !== 'meta.title' ? metaTitle : null,
+            description: metaDesc !== 'meta.description' ? metaDesc : null,
             indexable: true,
             canonical: null,
             ...njkTpl.metaPatch,
@@ -1221,32 +1359,33 @@ function mountPages(app, options) {
         req.context = ctx;
         
         // Execute hooks: onRequest
-        await executeHook(globalHooks, 'onRequest', ctx);
-        await executeHook(routeHooks, 'onRequest', ctx);
+        let hookPromise = runHooks(globalHooks, routeHooks, 'onRequest', ctx);
+        if (hookPromise) await hookPromise;
         
         // Execute hooks: onRoute
-        await executeHook(globalHooks, 'onRoute', ctx);
-        await executeHook(routeHooks, 'onRoute', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'onRoute', ctx);
+        if (hookPromise) await hookPromise;
         
         // Execute hooks: beforeMiddleware
-        await executeHook(globalHooks, 'beforeMiddleware', ctx);
-        await executeHook(routeHooks, 'beforeMiddleware', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'beforeMiddleware', ctx);
+        if (hookPromise) await hookPromise;
         
+        // Run cascading folder middlewares (_middleware.js)
+        const cascadingMw = loadCascadingMiddlewares(absolutePagesDir, route.file, middlewares, isDev);
+        if (cascadingMw.length) {
+          await runMiddlewareChain(cascadingMw, req, res);
+          if (res.headersSent) return;
+        }
+
         // Run route middleware (chain fixed at route registration; edit middleware in dev → restart)
         if (preResolvedPageMw.length) {
-          for (const mw of preResolvedPageMw) {
-            await new Promise((resolve, reject) => {
-              mw(req, res, (err) => {
-                if (err) reject(err);
-                else resolve();
-              });
-            });
-          }
+          await runMiddlewareChain(preResolvedPageMw, req, res);
+          if (res.headersSent) return;
         }
         
         // Execute hooks: afterMiddleware
-        await executeHook(globalHooks, 'afterMiddleware', ctx);
-        await executeHook(routeHooks, 'afterMiddleware', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'afterMiddleware', ctx);
+        if (hookPromise) await hookPromise;
         
         // Execute hooks: beforeLoad
         if (pluginManager && db) {
@@ -1255,9 +1394,17 @@ function mountPages(app, options) {
             ctx.content = contentApi.getContentService(db);
           }
         }
-        await executeHook(globalHooks, 'beforeLoad', ctx);
-        await executeHook(routeHooks, 'beforeLoad', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'beforeLoad', ctx);
+        if (hookPromise) await hookPromise;
         
+        // Find cascading layouts (_layout.njk)
+        const cascadingLayouts = findCascadingLayouts(absolutePagesDir, route.file, isDev);
+
+        // Run cascading _layout.js load() functions in top-down order (outermost first)
+        if (cascadingLayouts.length > 0) {
+          await executeCascadingLayoutLoads(cascadingLayouts, req, ctx, isDev);
+        }
+
         // Run load function
         if (config?.load && typeof config.load === 'function') {
           const loadData = await config.load(req, ctx);
@@ -1267,8 +1414,8 @@ function mountPages(app, options) {
         }
         
         // Execute hooks: afterLoad
-        await executeHook(globalHooks, 'afterLoad', ctx);
-        await executeHook(routeHooks, 'afterLoad', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'afterLoad', ctx);
+        if (hookPromise) await hookPromise;
         
         // Run meta function
         if (config?.meta && typeof config.meta === 'function') {
@@ -1279,10 +1426,18 @@ function mountPages(app, options) {
         }
         
         // Execute hooks: beforeRender
-        await executeHook(globalHooks, 'beforeRender', ctx);
-        await executeHook(routeHooks, 'beforeRender', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'beforeRender', ctx);
+        if (hookPromise) await hookPromise;
         
-        const pageAssetBundle = applyPageAssetsToTemplateData(pageAssetsResolved, ctx.data);
+        const pageAssetBundle = applyPageAssetsToTemplateData(
+          pageAssetsResolved,
+          ctx.data,
+          {
+            file: route.file,
+            routePath: route.routePath,
+          },
+          ctx.fsy?.assetManager || getAssetManager()
+        );
         ctx.data = pageAssetBundle.data;
         const renderContext = {
           ...ctx.data,
@@ -1316,10 +1471,34 @@ function mountPages(app, options) {
           });
         }
 
-        let html =
-          njkTpl.useStringRender && njkTpl.templateBody != null
-            ? nunjucks.renderString(njkTpl.templateBody, renderContext, { path: route.fullPath })
-            : nunjucks.render(templatePath, renderContext);
+        let html;
+        if (njkTpl.useStringRender && njkTpl.templateBody != null) {
+          if (typeof nunjucks.Template === 'function') {
+            let compiled = isDev ? null : compiledStringTemplateCache.get(route.fullPath);
+            if (!compiled || (isDev && compiled._templateBody !== njkTpl.templateBody)) {
+              compiled = new nunjucks.Template(njkTpl.templateBody, nunjucks, route.fullPath);
+              compiled._templateBody = njkTpl.templateBody;
+              compiledStringTemplateCache.set(route.fullPath, compiled);
+            }
+            html = compiled.render(renderContext);
+          } else if (typeof nunjucks.renderString === 'function') {
+            html = nunjucks.renderString(njkTpl.templateBody, renderContext, { path: route.fullPath });
+          } else {
+            html = nunjucks.render(templatePath, renderContext);
+          }
+        } else {
+          html = nunjucks.render(templatePath, renderContext);
+        }
+
+        // Apply cascading nested layouts if not opted-out and template does not extend another template
+        const shouldApplyLayout = config?.layout !== false &&
+          ctx.data?.layout !== false &&
+          ctx.meta?.layout !== false &&
+          !templateHasExtends(njkTpl.templateBody, route.fullPath);
+
+        if (shouldApplyLayout && cascadingLayouts.length > 0) {
+          html = applyCascadingLayouts(nunjucks, cascadingLayouts, html, renderContext, isDev);
+        }
 
         if (pluginManager) {
           const contentApi = pluginManager.getPluginAPI('content');
@@ -1330,8 +1509,8 @@ function mountPages(app, options) {
         
         // Execute hooks: afterRender
         ctx.html = html;
-        await executeHook(globalHooks, 'afterRender', ctx);
-        await executeHook(routeHooks, 'afterRender', ctx);
+        hookPromise = runHooks(globalHooks, routeHooks, 'afterRender', ctx);
+        if (hookPromise) await hookPromise;
         
         if (route.routePath === '/404' || route.file === '404.njk') {
           res.status(404);
@@ -1391,6 +1570,8 @@ module.exports = {
   mountPages,
   filePathToRoute,
   extractMethodFromFilename,
+  isRouteGroupSegment,
+  stripRouteGroups,
   scanDirectory,
   loadI18n,
   createTranslator,
@@ -1404,5 +1585,9 @@ module.exports = {
   frontmatterToPatches,
   loadNjkRouteTemplate,
   clearNjkFrontmatterCaches,
+  compiledStringTemplateCache,
+  clearCompiledStringTemplateCache,
+  translatorCache,
+  clearTranslatorCache,
 };