satset-react 0.2.6 → 0.2.7

package/dist/server/dev.js

@@ -13,6 +13,7 @@ const env_1 = require("./env");
 const error_overlay_1 = require("./error-overlay");
 const bundler_1 = require("./bundler");
 const response_1 = require("./response");
+const storage_1 = require("./storage");
 const translation_1 = require("../core/translation");
 const util_1 = __importDefault(require("util"));
 const tui_1 = require("./tui");
@@ -235,10 +236,32 @@ async function startDevServer(config = {}) {
     // Create HTTP server
     const server = http_1.default.createServer(async (req, res) => {
         const url = req.url || '/';
-        const rawPath = url.split('?')[0].split('#')[0] || '/';
-        const effectivePath = stripLocaleFromPath(rawPath);
+        // Parse cookies early for redirection
         const cookieStore = parseRequestCookies(req);
         (0, response_1.setCurrentRequestCookies)(cookieStore);
+        const rawPath = url.split('?')[0].split('#')[0] || '/';
+        // Virtual Routing / Locale Detection
+        let locale = 'en-US';
+        let effectivePath = rawPath;
+        const segments = rawPath.split('/').filter(Boolean);
+        const firstSegment = segments[0];
+        // 1. Detect from URL (Virtual Path)
+        if (firstSegment && /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/.test(firstSegment)) {
+            locale = firstSegment;
+            effectivePath = stripLocaleFromPath(rawPath);
+        }
+        else {
+            // 2. Detect from Cookie / Header
+            if (cookieStore && cookieStore['SATSET_LANG']) {
+                locale = cookieStore['SATSET_LANG'];
+            }
+            else if (req.headers['accept-language']) {
+                const accept = req.headers['accept-language'].split(',')[0].trim();
+                const match = accept.match(/^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?/);
+                if (match)
+                    locale = match[0];
+            }
+        }
         // Serve bundled JS files
         if (url.startsWith('/_satset/')) {
             // Remove query parameters from the URL before resolving file path
@@ -414,7 +437,7 @@ async function startDevServer(config = {}) {
         }
         const apiMatch = (0, file_system_1.matchRoute)(effectivePath, apiRoutes);
         if (apiMatch) {
-            await handleApiRoute(apiMatch.route, req, res, root, tempDir, apiMatch.params);
+            await handleApiRoute(apiMatch.route, req, res, root, tempDir, apiMatch.params, locale);
             return;
         }
         if (effectivePath.startsWith('/api/')) {
@@ -424,13 +447,13 @@ async function startDevServer(config = {}) {
         }
         const matched = (0, file_system_1.matchRoute)(effectivePath, routes);
         if (matched) {
-            await handlePageRoute(matched.route, req, res, root, tempDir, matched.params, routes, publicDir);
+            await handlePageRoute(matched.route, req, res, root, tempDir, matched.params, routes, publicDir, locale);
             return;
         }
         const notFoundRoute = routes.find(r => r.path === '/404') ||
             routes.find(r => r.path === '/not-found');
         if (notFoundRoute) {
-            await handlePageRoute(notFoundRoute, req, res, root, tempDir, {}, routes, publicDir);
+            await handlePageRoute(notFoundRoute, req, res, root, tempDir, {}, routes, publicDir, locale);
             return;
         }
         res.writeHead(404, { 'Content-Type': 'text/html' });
@@ -534,126 +557,124 @@ async function buildClientBundle(root, outdir, routes) {
         if (layoutRoute && layoutRoute.component) {
             const layoutRelative = path_1.default.relative(root, layoutRoute.component).replace(/\\/g, '/');
             layoutImport = `import Layout from '../../${layoutRelative}';`;
-            appCreationBlock = `
-    const pageElement = React.createElement(React.Suspense, { fallback: null }, React.createElement(PageComponent, props));
-    const withLayout = React.createElement(Layout, null, pageElement);
-    const App = React.createElement(
-      I18nProvider,
-      {
-        initialLocale,
-        dictionaries: window.__SATSET_DICTIONARIES__
-      },
-      withLayout
+            appCreationBlock = `
+    const pageElement = React.createElement(React.Suspense, { fallback: null }, React.createElement(PageComponent, props));
+    const withLayout = React.createElement(Layout, null, pageElement);
+    const App = React.createElement(
+      I18nProvider,
+      {
+        initialLocale,
+        dictionaries: window.__SATSET_DICTIONARIES__
+      },
+      withLayout
     );`;
         }
         else {
-            appCreationBlock = `
-    const App = React.createElement(
-      I18nProvider,
-      {
-        initialLocale,
-        dictionaries: window.__SATSET_DICTIONARIES__
-      },
-      React.createElement(React.Suspense, { fallback: null }, React.createElement(PageComponent, props))
+            appCreationBlock = `
+    const App = React.createElement(
+      I18nProvider,
+      {
+        initialLocale,
+        dictionaries: window.__SATSET_DICTIONARIES__
+      },
+      React.createElement(React.Suspense, { fallback: null }, React.createElement(PageComponent, props))
     );`;
         }
-        const entryContent = `
-import React from 'react';
-import { hydrateRoot, createRoot } from 'react-dom/client';
-import { I18nProvider } from 'satset-react';
-${layoutImport}
-
-// Import all page components
-${importLines.join('\n')}
-// Route definitions
-const routeDefs = [
-${routeDefLines.join('\n')}
-];
-
-function stripLocale(pathname) {
-  if (!pathname) return '/';
-  const raw = pathname.split('?')[0].split('#')[0];
-  const segments = raw.split('/').filter(Boolean);
-  if (!segments.length) return '/';
-  const first = segments[0];
-  const localePattern = /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/;
-  if (localePattern.test(first)) {
-    const rest = segments.slice(1);
-    return rest.length ? '/' + rest.join('/') : '/';
-  }
-  return raw.startsWith('/') ? raw : '/' + raw;
-}
-
-function matchPath(pathname) {
-  const normalized = stripLocale(pathname);
-  const pathSegments = normalized.split('/').filter(Boolean);
-  for (const r of routeDefs) {
-    const routeSegments = r.path.split('/').filter(Boolean);
-
-    // catch-all
-    if (r.path.includes('*')) {
-      const catchIndex = routeSegments.findIndex(s => s.startsWith('*'));
-      const paramName = routeSegments[catchIndex].slice(1);
-      const params = {};
-      params[paramName] = pathSegments.slice(catchIndex).join('/');
-      return { component: r.component, params };
-    }
-
-    if (routeSegments.length !== pathSegments.length) continue;
-
-    let matched = true;
-    const params = {};
-
-    for (let i = 0; i < routeSegments.length; i++) {
-      const rs = routeSegments[i];
-      const ps = pathSegments[i];
-
-      if (rs.startsWith(':')) {
-        params[rs.slice(1)] = ps;
-      } else if (rs !== ps) {
-        matched = false;
-        break;
-      }
-    }
-
-    if (matched) {
-      return { component: r.component, params };
-    }
-  }
-
-  // fallback to root route
-  return { component: routeDefs.find(r => r.path === '/')?.component, params: {} };
-}
-
-// Hydrate based on current path
-const currentPath = stripLocale(window.location.pathname);
-const match = matchPath(currentPath);
-// expose routes and params to Router
-window.__SATSET_ROUTES__ = routeDefs.map(r => r.path);
-window.__SATSET_PARAMS__ = match.params || {};
-window.__SATSET_DICTIONARIES__ = ${JSON.stringify(dictionaries)};
-
-const PageComponent = match.component;
-
-if (PageComponent) {
-  const root = document.getElementById('root');
-  if (root) {
-    const props = match.params ? { params: match.params } : undefined;
-    
-    const pathSegments = window.location.pathname.split('/').filter(Boolean);
-    const firstSegment = pathSegments[0];
-    const initialLocale = (firstSegment && /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/.test(firstSegment)) ? firstSegment : 'en-US';
-
-${appCreationBlock}
-
-    if (root.hasChildNodes()) {
-      hydrateRoot(root, App);
-    } else {
-      const rootInstance = createRoot(root);
-      rootInstance.render(App);
-    }
-  }
-}
+        const entryContent = `
+import React from 'react';
+import { hydrateRoot, createRoot } from 'react-dom/client';
+import { I18nProvider } from 'satset-react';
+${layoutImport}
+
+// Import all page components
+${importLines.join('\n')}
+// Route definitions
+const routeDefs = [
+${routeDefLines.join('\n')}
+];
+
+function stripLocale(pathname) {
+  if (!pathname) return '/';
+  const raw = pathname.split('?')[0].split('#')[0];
+  const segments = raw.split('/').filter(Boolean);
+  if (!segments.length) return '/';
+  const first = segments[0];
+  const localePattern = /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/;
+  if (localePattern.test(first)) {
+    const rest = segments.slice(1);
+    return rest.length ? '/' + rest.join('/') : '/';
+  }
+  return raw.startsWith('/') ? raw : '/' + raw;
+}
+
+function matchPath(pathname) {
+  const normalized = stripLocale(pathname);
+  const pathSegments = normalized.split('/').filter(Boolean);
+  for (const r of routeDefs) {
+    const routeSegments = r.path.split('/').filter(Boolean);
+
+    // catch-all
+    if (r.path.includes('*')) {
+      const catchIndex = routeSegments.findIndex(s => s.startsWith('*'));
+      const paramName = routeSegments[catchIndex].slice(1);
+      const params = {};
+      params[paramName] = pathSegments.slice(catchIndex).join('/');
+      return { component: r.component, params };
+    }
+
+    if (routeSegments.length !== pathSegments.length) continue;
+
+    let matched = true;
+    const params = {};
+
+    for (let i = 0; i < routeSegments.length; i++) {
+      const rs = routeSegments[i];
+      const ps = pathSegments[i];
+
+      if (rs.startsWith(':')) {
+        params[rs.slice(1)] = ps;
+      } else if (rs !== ps) {
+        matched = false;
+        break;
+      }
+    }
+
+    if (matched) {
+      return { component: r.component, params };
+    }
+  }
+
+  // fallback to root route
+  return { component: routeDefs.find(r => r.path === '/')?.component, params: {} };
+}
+
+// Hydrate based on current path
+const currentPath = stripLocale(window.location.pathname);
+const match = matchPath(currentPath);
+// expose routes and params to Router
+window.__SATSET_ROUTES__ = routeDefs.map(r => r.path);
+window.__SATSET_PARAMS__ = match.params || {};
+window.__SATSET_DICTIONARIES__ = ${JSON.stringify(dictionaries)};
+
+const PageComponent = match.component;
+
+if (PageComponent) {
+  const root = document.getElementById('root');
+  if (root) {
+    const props = match.params ? { params: match.params } : undefined;
+    
+    const initialLocale = window.__SATSET_LOCALE__ || 'en-US';
+
+${appCreationBlock}
+
+    if (root.hasChildNodes()) {
+      hydrateRoot(root, App);
+    } else {
+      const rootInstance = createRoot(root);
+      rootInstance.render(App);
+    }
+  }
+}
     `;
         const entryPath = path_1.default.join(outdir, '_entry.tsx');
         fs_1.default.writeFileSync(entryPath, entryContent);
@@ -697,745 +718,828 @@ ${appCreationBlock}
         console.error(`❌ ERROR [${formatTime()}] Client bundle failed:`, error && error.message ? error.message : String(error));
     }
 }
-async function handleApiRoute(route, req, res, root, tempDir, params = {}) {
-    try {
-        // Compile API module to CJS before requiring to support TS/ESM sources.
-        // Cache the compiled file between requests and only re-bundle when the
-        // source file is newer. Use a per-route file name derived from the
-        // component's relative path to avoid collisions between different API
-        // handlers that share the same base file name (e.g. multiple `route.ts`).
-        const relComponentPath = path_1.default
-            .relative(root, route.component)
-            .replace(/\\/g, '/')
-            .replace(/\.[^.]+$/, '');
-        const safeComponentKey = relComponentPath.replace(/[^a-zA-Z0-9_-]/g, '_');
-        const compiledApiPath = path_1.default.join(tempDir, safeComponentKey + '.api.server.js');
-        console.log('[API Debug] route:', route.path, 'component:', route.component);
-        console.log('[API Debug] safeKey:', safeComponentKey, 'compiledPath:', compiledApiPath);
-        let ApiModule = null;
-        async function safeBundleApi(entry, outfile) {
-            try {
-                await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: true });
+async function handleApiRoute(route, req, res, root, tempDir, params = {}, locale = 'en-US') {
+    const dictionaries = getDictionaries(root);
+    return storage_1.requestContext.run({ locale, dictionaries, params, pathname: req.url || '/' }, async () => {
+        try {
+            // Compile API module to CJS before requiring to support TS/ESM sources.
+            // Cache the compiled file between requests and only re-bundle when the
+            // source file is newer. Use a per-route file name derived from the
+            // component's relative path to avoid collisions between different API
+            // handlers that share the same base file name (e.g. multiple `route.ts`).
+            const relComponentPath = path_1.default
+                .relative(root, route.component)
+                .replace(/\\/g, '/')
+                .replace(/\.[^.]+$/, '');
+            const safeComponentKey = relComponentPath.replace(/[^a-zA-Z0-9_-]/g, '_');
+            const compiledApiPath = path_1.default.join(tempDir, safeComponentKey + '.api.server.js');
+            console.log('[API Debug] route:', route.path, 'component:', route.component);
+            console.log('[API Debug] safeKey:', safeComponentKey, 'compiledPath:', compiledApiPath);
+            let ApiModule = null;
+            async function safeBundleApi(entry, outfile) {
+                try {
+                    await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: true });
+                }
+                catch (err) {
+                    const msg = String(err && err.message ? err.message : err);
+                    if (/ENOSPC|not enough space|There is not enough space/i.test(msg)) {
+                        try {
+                            if (fs_1.default.existsSync(tempDir)) {
+                                fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+                            }
+                            fs_1.default.mkdirSync(tempDir, { recursive: true });
+                        }
+                        catch (cleanupErr) {
+                            console.error('Failed to cleanup temp dir:', cleanupErr);
+                        }
+                        await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: false });
+                        return;
+                    }
+                    throw err;
+                }
             }
-            catch (err) {
-                const msg = String(err && err.message ? err.message : err);
-                if (/ENOSPC|not enough space|There is not enough space/i.test(msg)) {
+            try {
+                let needsBundle = true;
+                if (fs_1.default.existsSync(compiledApiPath)) {
                     try {
-                        if (fs_1.default.existsSync(tempDir)) {
-                            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+                        const srcStat = fs_1.default.statSync(route.component);
+                        const outStat = fs_1.default.statSync(compiledApiPath);
+                        if (outStat.mtimeMs >= srcStat.mtimeMs) {
+                            needsBundle = false;
                         }
-                        fs_1.default.mkdirSync(tempDir, { recursive: true });
-                    }
-                    catch (cleanupErr) {
-                        console.error('Failed to cleanup temp dir:', cleanupErr);
                     }
-                    await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: false });
-                    return;
+                    catch (e) { }
+                }
+                if (needsBundle) {
+                    await safeBundleApi(route.component, compiledApiPath);
                 }
-                throw err;
-            }
-        }
-        try {
-            let needsBundle = true;
-            if (fs_1.default.existsSync(compiledApiPath)) {
                 try {
-                    const srcStat = fs_1.default.statSync(route.component);
-                    const outStat = fs_1.default.statSync(compiledApiPath);
-                    if (outStat.mtimeMs >= srcStat.mtimeMs) {
-                        needsBundle = false;
-                    }
+                    delete require.cache[require.resolve(compiledApiPath)];
                 }
                 catch (e) { }
+                ApiModule = require(compiledApiPath);
             }
-            if (needsBundle) {
-                await safeBundleApi(route.component, compiledApiPath);
-            }
-            try {
-                delete require.cache[require.resolve(compiledApiPath)];
+            catch (err) {
+                console.error('API bundling failed for', route.component, err);
+                const errMsg = String(err && err.message ? err.message : err);
+                const message = /ENOSPC|not enough space|There is not enough space/i.test(errMsg)
+                    ? 'API bundling failed: not enough disk space. Free disk space or delete .satset/temp'
+                    : 'API bundling failed';
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: { code: 500, message }, file: route.component }));
+                return;
             }
-            catch (e) { }
-            ApiModule = require(compiledApiPath);
-        }
-        catch (err) {
-            console.error('API bundling failed for', route.component, err);
-            const errMsg = String(err && err.message ? err.message : err);
-            const message = /ENOSPC|not enough space|There is not enough space/i.test(errMsg)
-                ? 'API bundling failed: not enough disk space. Free disk space or delete .satset/temp'
-                : 'API bundling failed';
-            res.writeHead(500, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: { code: 500, message }, file: route.component }));
-            return;
-        }
-        function resolveHandler(mod) {
-            if (!mod)
-                return null;
-            // default export function
-            if (typeof mod === 'function')
-                return { default: mod };
-            if (mod && typeof mod === 'object') {
-                if (typeof mod.default === 'function')
-                    return { default: mod.default };
-                // method-named exports (GET, POST, etc.)
-                const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
-                const out = {};
-                for (const m of methods) {
-                    if (typeof mod[m] === 'function')
-                        out[m] = mod[m];
+            function resolveHandler(mod) {
+                if (!mod)
+                    return null;
+                // default export function
+                if (typeof mod === 'function')
+                    return { default: mod };
+                if (mod && typeof mod === 'object') {
+                    if (typeof mod.default === 'function')
+                        return { default: mod.default };
+                    // method-named exports (GET, POST, etc.)
+                    const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+                    const out = {};
+                    for (const m of methods) {
+                        if (typeof mod[m] === 'function')
+                            out[m] = mod[m];
+                    }
+                    if (Object.keys(out).length)
+                        return out;
                 }
-                if (Object.keys(out).length)
-                    return out;
+                return null;
             }
-            return null;
-        }
-        const handlerObj = resolveHandler(ApiModule);
-        const method = (req.method || 'GET').toUpperCase();
-        async function callHandlerWithNodeStyle(fn) {
-            // If function declares at least two args, assume Node-style (req, res)
-            if (fn.length >= 2) {
-                const maybe = await fn(req, res, params);
-                // If the handler returns a SatsetResponse, send it
-                if (response_1.SatsetResponse.isSatsetResponse(maybe)) {
-                    (0, response_1.sendSatsetResponse)(res, maybe);
+            const handlerObj = resolveHandler(ApiModule);
+            const method = (req.method || 'GET').toUpperCase();
+            async function callHandlerWithNodeStyle(fn) {
+                // If function declares at least two args, assume Node-style (req, res)
+                if (fn.length >= 2) {
+                    // Inject locale into request object for Node-style handlers
+                    req.locale = locale;
+                    req.lang = locale;
+                    const maybe = await fn(req, res, params);
+                    // If the handler returns a SatsetResponse, send it
+                    if (response_1.SatsetResponse.isSatsetResponse(maybe)) {
+                        (0, response_1.sendSatsetResponse)(res, maybe);
+                    }
+                    // assume the handler handled the Node res
+                    return true;
                 }
-                // assume the handler handled the Node res
-                return true;
-            }
-            return false;
-        }
-        async function callHandlerWithWebStyle(fn) {
-            // Build a lightweight Request-like object for route handlers
-            const webReq = await (0, response_1.buildSatsetRequest)(req);
-            const result = await fn(webReq, { params });
-            if (response_1.SatsetResponse.isSatsetResponse(result)) {
-                (0, response_1.sendSatsetResponse)(res, result);
-                return true;
+                return false;
             }
-            // If result is a native Response-like object with json/text, try to handle
-            if (result && typeof result === 'object' && typeof result.status === 'number' && (result.headers || result.json)) {
-                // Try basic mapping
-                const status = result.status || 200;
-                // Normalize headers: support Headers instance, array of tuples, or plain object
-                let headers = {};
-                const rawHeaders = result.headers;
-                if (rawHeaders) {
-                    if (typeof rawHeaders.get === 'function' && typeof rawHeaders.entries === 'function') {
-                        headers = Object.fromEntries(rawHeaders.entries());
+            async function callHandlerWithWebStyle(fn) {
+                // Build a lightweight Request-like object for route handlers
+                const webReq = await (0, response_1.buildSatsetRequest)(req);
+                // Inject locale into context
+                const context = { params, locale, lang: locale };
+                const result = await fn(webReq, context);
+                if (response_1.SatsetResponse.isSatsetResponse(result)) {
+                    (0, response_1.sendSatsetResponse)(res, result);
+                    return true;
+                }
+                // If result is a native Response-like object with json/text, try to handle
+                if (result && typeof result === 'object' && typeof result.status === 'number' && (result.headers || result.json)) {
+                    // Try basic mapping
+                    const status = result.status || 200;
+                    // Normalize headers: support Headers instance, array of tuples, or plain object
+                    let headers = {};
+                    const rawHeaders = result.headers;
+                    if (rawHeaders) {
+                        if (typeof rawHeaders.get === 'function' && typeof rawHeaders.entries === 'function') {
+                            headers = Object.fromEntries(rawHeaders.entries());
+                        }
+                        else if (Array.isArray(rawHeaders)) {
+                            headers = Object.fromEntries(rawHeaders);
+                        }
+                        else if (typeof rawHeaders === 'object') {
+                            headers = rawHeaders;
+                        }
                     }
-                    else if (Array.isArray(rawHeaders)) {
-                        headers = Object.fromEntries(rawHeaders);
+                    let body = undefined;
+                    try {
+                        if (typeof result.json === 'function') {
+                            body = await result.json();
+                            res.writeHead(status, { 'Content-Type': 'application/json', ...headers });
+                            res.end(JSON.stringify(body));
+                            return true;
+                        }
+                        if (typeof result.text === 'function') {
+                            body = await result.text();
+                            res.writeHead(status, headers);
+                            res.end(body);
+                            return true;
+                        }
                     }
-                    else if (typeof rawHeaders === 'object') {
-                        headers = rawHeaders;
+                    catch (e) {
+                        // fallthrough
                     }
                 }
-                let body = undefined;
-                try {
-                    if (typeof result.json === 'function') {
-                        body = await result.json();
-                        res.writeHead(status, { 'Content-Type': 'application/json', ...headers });
-                        res.end(JSON.stringify(body));
-                        return true;
-                    }
-                    if (typeof result.text === 'function') {
-                        body = await result.text();
-                        res.writeHead(status, headers);
-                        res.end(body);
-                        return true;
-                    }
+                // If result is an object, return as JSON
+                if (result && typeof result === 'object') {
+                    const sat = response_1.SatsetResponse.json(result);
+                    (0, response_1.sendSatsetResponse)(res, sat);
+                    return true;
                 }
-                catch (e) {
-                    // fallthrough
+                // If result is string or number, send as text
+                if (result != null) {
+                    res.writeHead(200, { 'Content-Type': 'text/plain' });
+                    res.end(String(result));
+                    return true;
                 }
+                // undefined -> assume handler will manage res; if not, leave to caller
+                return false;
             }
-            // If result is an object, return as JSON
-            if (result && typeof result === 'object') {
-                const sat = response_1.SatsetResponse.json(result);
-                (0, response_1.sendSatsetResponse)(res, sat);
-                return true;
-            }
-            // If result is string or number, send as text
-            if (result != null) {
-                res.writeHead(200, { 'Content-Type': 'text/plain' });
-                res.end(String(result));
-                return true;
-            }
-            // undefined -> assume handler will manage res; if not, leave to caller
-            return false;
-        }
-        // Prefer method-named export for App-style handlers
-        if (handlerObj && typeof handlerObj[method] === 'function') {
-            const fn = handlerObj[method];
-            // Try node-style first
-            const nodeTook = await callHandlerWithNodeStyle(fn);
-            if (nodeTook)
+            // Prefer method-named export for App-style handlers
+            if (handlerObj && typeof handlerObj[method] === 'function') {
+                const fn = handlerObj[method];
+                // Try node-style first
+                const nodeTook = await callHandlerWithNodeStyle(fn);
+                if (nodeTook)
+                    return;
+                // Fallback to Web-style
+                const webTook = await callHandlerWithWebStyle(fn);
+                if (webTook)
+                    return;
+                // no response produced
+                res.writeHead(204);
+                res.end();
                 return;
-            // Fallback to Web-style
-            const webTook = await callHandlerWithWebStyle(fn);
-            if (webTook)
+            }
+            // Default export fallback
+            if (handlerObj && typeof handlerObj.default === 'function') {
+                const fn = handlerObj.default;
+                const nodeTook = await callHandlerWithNodeStyle(fn);
+                if (nodeTook)
+                    return;
+                const webTook = await callHandlerWithWebStyle(fn);
+                if (webTook)
+                    return;
+                res.writeHead(204);
+                res.end();
                 return;
-            // no response produced
-            res.writeHead(204);
-            res.end();
-            return;
+            }
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: 405, message: 'Method not allowed' } }));
         }
-        // Default export fallback
-        if (handlerObj && typeof handlerObj.default === 'function') {
-            const fn = handlerObj.default;
-            const nodeTook = await callHandlerWithNodeStyle(fn);
-            if (nodeTook)
-                return;
-            const webTook = await callHandlerWithWebStyle(fn);
-            if (webTook)
-                return;
-            res.writeHead(204);
-            res.end();
-            return;
+        catch (error) {
+            const errorPayload = {
+                code: 500,
+                message: error && error.message ? error.message : 'Internal Server Error',
+            };
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: errorPayload, file: route.component, stack: error && error.stack }));
         }
-        res.writeHead(405, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: { code: 405, message: 'Method not allowed' } }));
-    }
-    catch (error) {
-        const errorPayload = {
-            code: 500,
-            message: error && error.message ? error.message : 'Internal Server Error',
-        };
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: errorPayload, file: route.component, stack: error && error.stack }));
-    }
+    });
 }
-async function handlePageRoute(route, req, res, root, tempDir, initialParams = {}, allRoutes = [], publicDirName = 'public') {
-    try {
-        const env = (0, env_1.loadEnv)(root, 'development');
-        const envScript = (0, env_1.getPublicEnvScript)(env.publicVars);
-        if (isClientOnlyPage(route.component)) {
-            const routePaths = allRoutes.length ? allRoutes.map(r => r.path) : [];
-            let metaHtml = '';
-            let htmlLang = 'en';
-            let faviconLink = '';
-            try {
-                const urlSegments = req.url?.split('/').filter(Boolean) || [];
-                const firstSegment = urlSegments[0];
-                const locale = (firstSegment && /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/.test(firstSegment)) ? firstSegment : 'en-US';
-                const dictionaries = getDictionaries(root);
+async function handlePageRoute(route, req, res, root, tempDir, initialParams = {}, allRoutes = [], publicDirName = 'public', locale = 'en-US') {
+    const dictionaries = getDictionaries(root);
+    return storage_1.requestContext.run({ locale, dictionaries, params: initialParams, pathname: req.url || '/' }, async () => {
+        try {
+            const env = (0, env_1.loadEnv)(root, 'development');
+            const envScript = (0, env_1.getPublicEnvScript)(env.publicVars);
+            if (isClientOnlyPage(route.component)) {
+                const routePaths = allRoutes.length ? allRoutes.map(r => r.path) : [];
+                let metaHtml = '';
+                let htmlLang = locale;
+                let faviconLink = '';
                 try {
-                    const { renderMetaTags } = await import('../assets/metadata.js');
-                    const baseName = path_1.default.basename(route.component).replace(/\.[^.]+$/, '');
-                    const compiledMetaPath = path_1.default.join(tempDir, baseName + '.meta.server.js');
+                    // dictionaries already loaded in context
+                    // Auto-inject hreflang tags for SEO
                     try {
-                        await bundler_1.bundler.bundleServer({
-                            entryPoint: route.component,
-                            outfile: compiledMetaPath,
-                            minify: false,
-                            root,
-                            sourcemap: false,
-                        });
-                        try {
-                            delete require.cache[require.resolve(compiledMetaPath)];
-                        }
-                        catch (e) {
-                        }
-                        const PageModule = require(compiledMetaPath);
-                        let metaObj = null;
-                        if (PageModule && PageModule.metadata) {
-                            metaObj = PageModule.metadata;
-                        }
-                        else if (PageModule && typeof PageModule.getMetadata === 'function') {
-                            const t = (key, params) => {
-                                const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
-                                let text = dict[key] || key;
-                                if (params) {
-                                    Object.entries(params).forEach(([k, v]) => {
-                                        text = text.replace(new RegExp(`{${k}}`, 'g'), v);
-                                    });
+                        const supportedLocales = Object.keys(dictionaries);
+                        if (supportedLocales.length > 0) {
+                            const host = req.headers.host || 'localhost';
+                            // Determine protocol (assume http for dev, but honor x-forwarded-proto if present)
+                            const proto = req.headers['x-forwarded-proto'] || 'http';
+                            const origin = `${proto}://${host}`;
+                            const urlObj = new URL(req.url || '/', origin);
+                            const currentPath = urlObj.pathname;
+                            // Determine clean path (strip locale prefix if present in URL)
+                            let cleanPath = currentPath;
+                            if (currentPath === `/${locale}` || currentPath.startsWith(`/${locale}/`)) {
+                                cleanPath = currentPath.substring(locale.length + 1);
+                                if (!cleanPath.startsWith('/'))
+                                    cleanPath = '/' + cleanPath;
+                            }
+                            supportedLocales.forEach(lang => {
+                                let href = origin;
+                                if (lang !== 'en-US') { // Assuming en-US is default/root
+                                    href += `/${lang}`;
                                 }
-                                return text;
-                            };
+                                href += cleanPath === '/' ? '' : cleanPath;
+                                metaHtml += `<link rel="alternate" hreflang="${lang}" href="${href}" />\n`;
+                            });
+                            // Add x-default pointing to default language (en-US)
+                            const defaultHref = origin + (cleanPath === '/' ? '' : cleanPath);
+                            metaHtml += `<link rel="alternate" hreflang="x-default" href="${defaultHref}" />\n`;
+                        }
+                    }
+                    catch (e) {
+                        // ignore hreflang generation errors
+                    }
+                    try {
+                        const { renderMetaTags } = await import('../assets/metadata.js');
+                        const baseName = path_1.default.basename(route.component).replace(/\.[^.]+$/, '');
+                        const compiledMetaPath = path_1.default.join(tempDir, baseName + '.meta.server.js');
+                        try {
+                            await bundler_1.bundler.bundleServer({
+                                entryPoint: route.component,
+                                outfile: compiledMetaPath,
+                                minify: false,
+                                root,
+                                sourcemap: false,
+                            });
                             try {
-                                metaObj = await PageModule.getMetadata({ params: initialParams, locale, t });
+                                delete require.cache[require.resolve(compiledMetaPath)];
                             }
                             catch (e) {
-                                metaObj = null;
                             }
+                            const PageModule = require(compiledMetaPath);
+                            let metaObj = null;
+                            if (PageModule && PageModule.metadata) {
+                                metaObj = PageModule.metadata;
+                            }
+                            else if (PageModule && typeof PageModule.getMetadata === 'function') {
+                                const t = (key, params) => {
+                                    const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
+                                    let text = dict[key] || key;
+                                    if (params) {
+                                        Object.entries(params).forEach(([k, v]) => {
+                                            text = text.replace(new RegExp(`{${k}}`, 'g'), v);
+                                        });
+                                    }
+                                    return text;
+                                };
+                                try {
+                                    metaObj = await PageModule.getMetadata({ params: initialParams, locale, t });
+                                }
+                                catch (e) {
+                                    metaObj = null;
+                                }
+                            }
+                            if (metaObj && typeof metaObj.lang === 'string' && metaObj.lang.trim()) {
+                                htmlLang = metaObj.lang.trim();
+                            }
+                            metaHtml = renderMetaTags(metaObj);
                         }
-                        if (metaObj && typeof metaObj.lang === 'string' && metaObj.lang.trim()) {
-                            htmlLang = metaObj.lang.trim();
+                        catch (e) {
                         }
-                        metaHtml = renderMetaTags(metaObj);
                     }
                     catch (e) {
                     }
-                }
-                catch (e) {
-                }
-                try {
-                    let computedFavicon = null;
-                    const publicPath = path_1.default.join(root, publicDirName);
-                    if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.ico')))
-                        computedFavicon = '/favicon.ico';
-                    else if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.png')))
-                        computedFavicon = '/favicon.png';
-                    if (computedFavicon) {
-                        faviconLink = `<link rel="icon" href="${computedFavicon}" />`;
+                    try {
+                        let computedFavicon = null;
+                        const publicPath = path_1.default.join(root, publicDirName);
+                        if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.ico')))
+                            computedFavicon = '/favicon.ico';
+                        else if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.png')))
+                            computedFavicon = '/favicon.png';
+                        if (computedFavicon) {
+                            faviconLink = `<link rel="icon" href="${computedFavicon}" />`;
+                        }
+                    }
+                    catch (e) {
                     }
                 }
                 catch (e) {
                 }
-            }
-            catch (e) {
-            }
-            const initialParamsScript = `<script>
-      window.__SATSET_ROUTES__ = ${JSON.stringify(routePaths)};
-      window.__SATSET_PARAMS__ = ${JSON.stringify(initialParams)};
-      window.__SATSET_DICTIONARIES__ = ${JSON.stringify(getDictionaries(root))};
+                const initialParamsScript = `<script>
+      window.__SATSET_ROUTES__ = ${JSON.stringify(routePaths)};
+      window.__SATSET_PARAMS__ = ${JSON.stringify(initialParams)};
+      window.__SATSET_DICTIONARIES__ = ${JSON.stringify(getDictionaries(root))};
+      window.__SATSET_LOCALE__ = "${locale}";
     </script>`;
-            const html = `
-<!DOCTYPE html>
-<html lang="${htmlLang}">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    ${metaHtml}
-    ${faviconLink}
-    <link rel="stylesheet" href="/_satset/globals.css" />
-  </head>
-  <body>
-    <div id="root"></div>
-    <script>${envScript}</script>
-    ${initialParamsScript}
-    <script type="module" src="/_satset/_entry.js"></script>
-    <script src="/__hmr"></script>
-  </body>
-</html>
+                const html = `
+<!DOCTYPE html>
+<html lang="${htmlLang}" suppressHydrationWarning>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    ${metaHtml}
+    ${faviconLink}
+    <link rel="stylesheet" href="/_satset/globals.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script>${envScript}</script>
+    ${initialParamsScript}
+    <script type="module" src="/_satset/_entry.js"></script>
+    <script src="/__hmr"></script>
+  </body>
+</html>
       `;
-            res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end(html);
-            return;
-        }
-        // Server-side render the component
-        // Compile page module to a temporary server file so Node can require it (handles tsx/esm)
-        const baseName = path_1.default.basename(route.component).replace(/\.[^.]+$/, '');
-        const compiledServerPath = path_1.default.join(tempDir, baseName + '.server.js');
-        let PageModule = null;
-        // Helper: bundle server build with low-disk fallback
-        async function safeBundleServer(entry, outfile) {
-            try {
-                await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: true });
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(html);
+                return;
             }
-            catch (err) {
-                const msg = String(err && err.message ? err.message : err);
-                // detect low-disk / ENOSPC errors (esbuild reports "There is not enough space on the disk" in Windows)
-                if (/ENOSPC|not enough space|There is not enough space/i.test(msg)) {
-                    console.warn('Low disk space detected while bundling. Attempting to clear temp and retry without sourcemaps.');
-                    try {
-                        // clear temp dir to free space
-                        if (fs_1.default.existsSync(tempDir)) {
-                            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+            // Server-side render the component
+            // Compile page module to a temporary server file so Node can require it (handles tsx/esm)
+            const baseName = path_1.default.basename(route.component).replace(/\.[^.]+$/, '');
+            const compiledServerPath = path_1.default.join(tempDir, baseName + '.server.js');
+            let PageModule = null;
+            // Helper: bundle server build with low-disk fallback
+            async function safeBundleServer(entry, outfile) {
+                try {
+                    await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: true });
+                }
+                catch (err) {
+                    const msg = String(err && err.message ? err.message : err);
+                    // detect low-disk / ENOSPC errors (esbuild reports "There is not enough space on the disk" in Windows)
+                    if (/ENOSPC|not enough space|There is not enough space/i.test(msg)) {
+                        console.warn('Low disk space detected while bundling. Attempting to clear temp and retry without sourcemaps.');
+                        try {
+                            // clear temp dir to free space
+                            if (fs_1.default.existsSync(tempDir)) {
+                                fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+                            }
+                            fs_1.default.mkdirSync(tempDir, { recursive: true });
+                        }
+                        catch (cleanupErr) {
+                            console.error('Failed to cleanup temp dir:', cleanupErr);
+                        }
+                        try {
+                            await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: false });
+                            return;
+                        }
+                        catch (retryErr) {
+                            // still failed
+                            throw retryErr;
                         }
-                        fs_1.default.mkdirSync(tempDir, { recursive: true });
-                    }
-                    catch (cleanupErr) {
-                        console.error('Failed to cleanup temp dir:', cleanupErr);
-                    }
-                    try {
-                        await bundler_1.bundler.bundleServer({ entryPoint: entry, outfile, minify: false, root, sourcemap: false });
-                        return;
-                    }
-                    catch (retryErr) {
-                        // still failed
-                        throw retryErr;
                     }
+                    // Not a disk-space issue, rethrow
+                    throw err;
                 }
-                // Not a disk-space issue, rethrow
-                throw err;
             }
-        }
-        try {
-            // Bundle the page for Node (CJS)
-            await safeBundleServer(route.component, compiledServerPath);
             try {
-                delete require.cache[require.resolve(compiledServerPath)];
-            }
-            catch (e) {
-                // ignore
-            }
-            PageModule = require(compiledServerPath);
-        }
-        catch (err) {
-            // If bundling fails, show an overlay with the bundling error and do NOT require the original TSX (which would crash)
-            console.error('SSR bundling failed for', route.component, err);
-            let message = 'SSR bundling failed';
-            const errMsg = String(err && err.message ? err.message : err);
-            if (/ENOSPC|not enough space|There is not enough space/i.test(errMsg)) {
-                message = 'SSR bundling failed: not enough disk space. Try freeing disk space or deleting the .satset/temp folder.';
-            }
-            const errorInfo = {
-                message,
-                stack: err && err.stack ? err.stack : String(err),
-                file: route.component,
-            };
-            const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
-            res.writeHead(500, { 'Content-Type': 'text/html' });
-            res.end(overlayHTML);
-            return;
-        }
-        function resolveExportedComponent(mod) {
-            if (!mod)
-                return null;
-            if (typeof mod === 'function')
-                return mod;
-            if (mod && typeof mod === 'object') {
-                if (typeof mod.default === 'function')
-                    return mod.default;
-                if (mod.default && typeof mod.default === 'object' && typeof mod.default.default === 'function')
-                    return mod.default.default;
-                for (const key of Object.keys(mod)) {
-                    if (typeof mod[key] === 'function')
-                        return mod[key];
+                // Bundle the page for Node (CJS)
+                await safeBundleServer(route.component, compiledServerPath);
+                try {
+                    delete require.cache[require.resolve(compiledServerPath)];
                 }
+                catch (e) {
+                    // ignore
+                }
+                PageModule = require(compiledServerPath);
             }
-            return null;
-        }
-        const PageComponent = resolveExportedComponent(PageModule);
-        console.log('SSR: used component from', compiledServerPath, 'PageModule keys:', Object.keys(PageModule || {}), 'Resolved component type:', typeof PageComponent);
-        console.log('SSR: PageModule keys:', Object.keys(PageModule || {}), 'PageComponent type:', typeof PageComponent);
-        // Simple SSR with optional global layout composition
-        const React = require('react');
-        const { renderToString } = require('react-dom/server');
-        let pageHTML = '<div>Loading...</div>';
-        async function renderComponentToHtml(Comp, props = {}) {
-            if (!Comp || typeof Comp !== 'function') {
-                throw new Error('Invalid component to render');
-            }
-            const isAsync = Comp.constructor && Comp.constructor.name === 'AsyncFunction';
-            if (isAsync) {
-                const maybeNode = Comp(props);
-                const resolved = await Promise.resolve(maybeNode);
-                return renderToString(resolved);
-            }
-            return renderToString(React.createElement(Comp, props));
-        }
-        let statusCode = 200;
-        // Determine locale for SSR
-        const urlSegments = req.url?.split('/').filter(Boolean) || [];
-        const firstSegment = urlSegments[0];
-        const locale = (firstSegment && /^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$/.test(firstSegment)) ? firstSegment : 'en-US';
-        const dictionaries = getDictionaries(root);
-        try {
-            if (!PageComponent || typeof PageComponent !== 'function') {
-                console.error('SSR Error: resolved page component is not a function. PageModule:', util_1.default.inspect(PageModule, { depth: 2 }));
-                const diagHtml = `<!doctype html><html><body><h1>500 - Component export error</h1><pre>${util_1.default.format('PageModule keys: %o\nResolved: %o', Object.keys(PageModule || {}), PageComponent)}</pre></body></html>`;
+            catch (err) {
+                // If bundling fails, show an overlay with the bundling error and do NOT require the original TSX (which would crash)
+                console.error('SSR bundling failed for', route.component, err);
+                let message = 'SSR bundling failed';
+                const errMsg = String(err && err.message ? err.message : err);
+                if (/ENOSPC|not enough space|There is not enough space/i.test(errMsg)) {
+                    message = 'SSR bundling failed: not enough disk space. Try freeing disk space or deleting the .satset/temp folder.';
+                }
+                const errorInfo = {
+                    message,
+                    stack: err && err.stack ? err.stack : String(err),
+                    file: route.component,
+                };
+                const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
                 res.writeHead(500, { 'Content-Type': 'text/html' });
-                res.end(diagHtml);
+                res.end(overlayHTML);
                 return;
             }
-            let LayoutComponent = null;
-            try {
-                const layoutRoute = allRoutes.find(r => r.path === '/layout');
-                if (layoutRoute && layoutRoute.component) {
-                    const layoutBase = path_1.default.basename(layoutRoute.component).replace(/\.[^.]+$/, '');
-                    const layoutCompiled = path_1.default.join(tempDir, layoutBase + '.layout.server.js');
-                    await bundler_1.bundler.bundleServer({ entryPoint: layoutRoute.component, outfile: layoutCompiled, minify: false, root });
-                    try {
-                        delete require.cache[require.resolve(layoutCompiled)];
-                    }
-                    catch (e) { }
-                    const LayoutModule = require(layoutCompiled);
-                    function resolveExportedComp(mod) {
-                        if (!mod)
-                            return null;
-                        if (typeof mod === 'function')
-                            return mod;
-                        if (mod && typeof mod === 'object') {
-                            if (typeof mod.default === 'function')
-                                return mod.default;
-                            for (const key of Object.keys(mod)) {
-                                if (typeof mod[key] === 'function')
-                                    return mod[key];
-                            }
-                        }
-                        return null;
-                    }
-                    LayoutComponent = resolveExportedComp(LayoutModule);
-                    if (!LayoutComponent) {
-                        console.warn('Layout module found but no component exported:', layoutRoute.component);
-                    }
-                    else {
-                        console.log('Using layout module for SSR:', layoutRoute.component);
+            function resolveExportedComponent(mod) {
+                if (!mod)
+                    return null;
+                if (typeof mod === 'function')
+                    return mod;
+                if (mod && typeof mod === 'object') {
+                    if (typeof mod.default === 'function')
+                        return mod.default;
+                    if (mod.default && typeof mod.default === 'object' && typeof mod.default.default === 'function')
+                        return mod.default.default;
+                    for (const key of Object.keys(mod)) {
+                        if (typeof mod[key] === 'function')
+                            return mod[key];
                     }
                 }
+                return null;
             }
-            catch (e) {
-                const msg = e?.message ?? String(e);
-                console.warn('Could not load layout module:', msg);
-            }
-            const isPageAsync = PageComponent &&
-                PageComponent.constructor &&
-                PageComponent.constructor.name === 'AsyncFunction';
-            let pageNode;
-            if (isPageAsync) {
-                const maybeNode = PageComponent({ params: initialParams });
-                pageNode = await Promise.resolve(maybeNode);
-            }
-            else {
-                pageNode = React.createElement(PageComponent, { params: initialParams });
-            }
-            if (LayoutComponent) {
-                const Wrapper = () => React.createElement(translation_1.I18nProvider, { initialLocale: locale, dictionaries }, React.createElement(LayoutComponent, null, pageNode));
-                pageHTML = await renderComponentToHtml(Wrapper);
-            }
-            else {
-                const Wrapper = () => React.createElement(translation_1.I18nProvider, { initialLocale: locale, dictionaries }, pageNode);
-                pageHTML = await renderComponentToHtml(Wrapper);
-            }
-        }
-        catch (err) {
-            console.error('SSR Error:', err);
-            if (err && err.__SATSET_REDIRECT) {
-                const info = err.__SATSET_REDIRECT || {};
-                const url = typeof info.url === 'string' && info.url.length ? info.url : '/';
-                const status = typeof info.status === 'number' ? info.status : 307;
-                const sat = response_1.SatsetResponse.redirect(url, status);
-                (0, response_1.sendSatsetResponse)(res, sat);
-                return;
+            const PageComponent = resolveExportedComponent(PageModule);
+            console.log('SSR: used component from', compiledServerPath, 'PageModule keys:', Object.keys(PageModule || {}), 'Resolved component type:', typeof PageComponent);
+            console.log('SSR: PageModule keys:', Object.keys(PageModule || {}), 'PageComponent type:', typeof PageComponent);
+            // Simple SSR with optional global layout composition
+            const React = require('react');
+            const { renderToString } = require('react-dom/server');
+            let pageHTML = '<div>Loading...</div>';
+            async function renderComponentToHtml(Comp, props = {}) {
+                if (!Comp || typeof Comp !== 'function') {
+                    throw new Error('Invalid component to render');
+                }
+                const isAsync = Comp.constructor && Comp.constructor.name === 'AsyncFunction';
+                if (isAsync) {
+                    const maybeNode = Comp(props);
+                    const resolved = await Promise.resolve(maybeNode);
+                    return renderToString(resolved);
+                }
+                return renderToString(React.createElement(Comp, props));
             }
-            if (err && err.__SATSET_NOT_FOUND) {
-                statusCode = 404;
-                const errorPayload = { code: 404, message: 'Page not found' };
+            let statusCode = 200;
+            // Determine locale for SSR
+            // locale is now passed as argument
+            // const dictionaries = getDictionaries(root); // Already defined in outer scope and context
+            try {
+                if (!PageComponent || typeof PageComponent !== 'function') {
+                    console.error('SSR Error: resolved page component is not a function. PageModule:', util_1.default.inspect(PageModule, { depth: 2 }));
+                    const diagHtml = `<!doctype html><html><body><h1>500 - Component export error</h1><pre>${util_1.default.format('PageModule keys: %o\nResolved: %o', Object.keys(PageModule || {}), PageComponent)}</pre></body></html>`;
+                    res.writeHead(500, { 'Content-Type': 'text/html' });
+                    res.end(diagHtml);
+                    return;
+                }
+                // Recursive Layout Loading
+                const layouts = [];
                 try {
-                    const nf = allRoutes.find(r => r.path === '/404') ||
-                        allRoutes.find(r => r.path === '/not-found');
-                    if (nf && nf.component) {
-                        const nfBase = path_1.default.basename(nf.component).replace(/\.[^.]+$/, '');
-                        const nfCompiled = path_1.default.join(tempDir, nfBase + '.notfound.server.js');
-                        await bundler_1.bundler.bundleServer({ entryPoint: nf.component, outfile: nfCompiled, minify: false, root });
+                    const findLayoutFiles = (dir) => {
+                        const results = [];
+                        let current = dir;
+                        const rootSrc = path_1.default.join(root, 'src');
+                        // Go up until we reach the root
+                        while (current.startsWith(root)) {
+                            const extensions = ['.tsx', '.jsx', '.ts', '.js'];
+                            for (const ext of extensions) {
+                                const layoutPath = path_1.default.join(current, `layout${ext}`);
+                                if (fs_1.default.existsSync(layoutPath)) {
+                                    // Check if already added (to avoid duplicates if loop logic is flawed)
+                                    if (!results.includes(layoutPath))
+                                        results.unshift(layoutPath);
+                                    break;
+                                }
+                            }
+                            if (current === root)
+                                break;
+                            current = path_1.default.dirname(current);
+                        }
+                        return results;
+                    };
+                    const pageDir = path_1.default.dirname(route.component);
+                    const layoutFiles = findLayoutFiles(pageDir);
+                    for (const layoutFile of layoutFiles) {
+                        const layoutBase = path_1.default.basename(layoutFile).replace(/\.[^.]+$/, '');
+                        const crypto = require('crypto');
+                        const hash = crypto.createHash('md5').update(layoutFile).digest('hex').substring(0, 8);
+                        const layoutCompiled = path_1.default.join(tempDir, `${layoutBase}.${hash}.layout.server.js`);
+                        await bundler_1.bundler.bundleServer({ entryPoint: layoutFile, outfile: layoutCompiled, minify: false, root });
                         try {
-                            delete require.cache[require.resolve(nfCompiled)];
+                            delete require.cache[require.resolve(layoutCompiled)];
                         }
                         catch (e) { }
-                        const NfModule = require(nfCompiled);
-                        const NfComp = (typeof NfModule === 'function') ? NfModule : (NfModule && typeof NfModule.default === 'function') ? NfModule.default : null;
-                        if (NfComp) {
-                            pageHTML = await renderComponentToHtml(NfComp, { params: initialParams, error: errorPayload });
-                        }
-                        else {
-                            pageHTML = '<h1>404 - Page Not Found</h1>';
+                        const LayoutModule = require(layoutCompiled);
+                        let LayoutComp = null;
+                        if (typeof LayoutModule === 'function')
+                            LayoutComp = LayoutModule;
+                        else if (LayoutModule && typeof LayoutModule === 'object') {
+                            if (typeof LayoutModule.default === 'function')
+                                LayoutComp = LayoutModule.default;
+                            else {
+                                for (const key of Object.keys(LayoutModule)) {
+                                    if (typeof LayoutModule[key] === 'function') {
+                                        LayoutComp = LayoutModule[key];
+                                        break;
+                                    }
+                                }
+                            }
                         }
-                    }
-                    else {
-                        pageHTML = '<h1>404 - Page Not Found</h1>';
+                        if (LayoutComp)
+                            layouts.push(LayoutComp);
                     }
                 }
                 catch (e) {
-                    pageHTML = '<h1>404 - Page Not Found</h1>';
+                    console.warn('Could not load layout modules:', e);
                 }
-            }
-            else {
-                const maybeStatus = (err && err.statusCode) ??
-                    (err && err.status) ??
-                    (err && typeof err.code === 'number' ? err.code : undefined);
-                if (typeof maybeStatus === 'number' && maybeStatus >= 400 && maybeStatus <= 599) {
-                    statusCode = maybeStatus;
+                const isPageAsync = PageComponent &&
+                    PageComponent.constructor &&
+                    PageComponent.constructor.name === 'AsyncFunction';
+                let pageNode;
+                if (isPageAsync) {
+                    const maybeNode = PageComponent({ params: initialParams, searchParams: {} });
+                    pageNode = await Promise.resolve(maybeNode);
                 }
                 else {
-                    statusCode = 500;
+                    pageNode = React.createElement(PageComponent, { params: initialParams, searchParams: {} });
                 }
-                const errorPayload = {
-                    code: statusCode,
-                    message: (err && err.message) ? err.message : (statusCode === 404 ? 'Page not found' : 'Server error'),
-                };
-                const candidatePaths = [];
-                candidatePaths.push(`/${statusCode}`);
-                if (statusCode === 404)
-                    candidatePaths.push('/404', '/not-found');
-                if (statusCode === 500)
-                    candidatePaths.push('/500');
-                candidatePaths.push('/error');
-                let errorRoute = null;
-                for (const p of candidatePaths) {
-                    const found = allRoutes.find(r => r.path === p);
-                    if (found) {
-                        errorRoute = found;
-                        break;
-                    }
+                let appElement = pageNode;
+                // Wrap from inner to outer
+                for (let i = layouts.length - 1; i >= 0; i--) {
+                    appElement = React.createElement(layouts[i], { params: initialParams, locale }, appElement);
                 }
-                try {
-                    if (errorRoute && errorRoute.component) {
-                        const erBase = path_1.default.basename(errorRoute.component).replace(/\.[^.]+$/, '');
-                        const erCompiled = path_1.default.join(tempDir, erBase + '.error.server.js');
-                        await bundler_1.bundler.bundleServer({ entryPoint: errorRoute.component, outfile: erCompiled, minify: false, root });
-                        try {
-                            delete require.cache[require.resolve(erCompiled)];
-                        }
-                        catch (e) { }
-                        const ErModule = require(erCompiled);
-                        const ErComp = (typeof ErModule === 'function') ? ErModule : (ErModule && typeof ErModule.default === 'function') ? ErModule.default : null;
-                        if (ErComp) {
-                            pageHTML = await renderComponentToHtml(ErComp, { error: errorPayload, reset: () => { } });
+                const Wrapper = () => React.createElement(translation_1.I18nProvider, { initialLocale: locale, dictionaries }, appElement);
+                pageHTML = await renderComponentToHtml(Wrapper);
+            }
+            catch (err) {
+                console.error('SSR Error:', err);
+                if (err && err.__SATSET_REDIRECT) {
+                    const info = err.__SATSET_REDIRECT || {};
+                    const url = typeof info.url === 'string' && info.url.length ? info.url : '/';
+                    const status = typeof info.status === 'number' ? info.status : 307;
+                    const sat = response_1.SatsetResponse.redirect(url, status);
+                    (0, response_1.sendSatsetResponse)(res, sat);
+                    return;
+                }
+                if (err && err.__SATSET_NOT_FOUND) {
+                    statusCode = 404;
+                    const errorPayload = { code: 404, message: 'Page not found' };
+                    try {
+                        const nf = allRoutes.find(r => r.path === '/404') ||
+                            allRoutes.find(r => r.path === '/not-found');
+                        if (nf && nf.component) {
+                            const nfBase = path_1.default.basename(nf.component).replace(/\.[^.]+$/, '');
+                            const nfCompiled = path_1.default.join(tempDir, nfBase + '.notfound.server.js');
+                            await bundler_1.bundler.bundleServer({ entryPoint: nf.component, outfile: nfCompiled, minify: false, root });
+                            try {
+                                delete require.cache[require.resolve(nfCompiled)];
+                            }
+                            catch (e) { }
+                            const NfModule = require(nfCompiled);
+                            const NfComp = (typeof NfModule === 'function') ? NfModule : (NfModule && typeof NfModule.default === 'function') ? NfModule.default : null;
+                            if (NfComp) {
+                                pageHTML = await renderComponentToHtml(NfComp, { params: initialParams, error: errorPayload });
+                            }
+                            else {
+                                pageHTML = '<h1>404 - Page Not Found</h1>';
+                            }
                         }
                         else {
-                            throw err;
+                            pageHTML = '<h1>404 - Page Not Found</h1>';
                         }
                     }
-                    else {
-                        throw err;
+                    catch (e) {
+                        pageHTML = '<h1>404 - Page Not Found</h1>';
                     }
                 }
-                catch (e) {
-                    // Attempt to extract title from metadata for the error overlay
-                    let pageTitle;
+                else {
+                    const maybeStatus = (err && err.statusCode) ??
+                        (err && err.status) ??
+                        (err && typeof err.code === 'number' ? err.code : undefined);
+                    if (typeof maybeStatus === 'number' && maybeStatus >= 400 && maybeStatus <= 599) {
+                        statusCode = maybeStatus;
+                    }
+                    else {
+                        statusCode = 500;
+                    }
+                    const errorPayload = {
+                        code: statusCode,
+                        message: (err && err.message) ? err.message : (statusCode === 404 ? 'Page not found' : 'Server error'),
+                    };
+                    const candidatePaths = [];
+                    candidatePaths.push(`/${statusCode}`);
+                    if (statusCode === 404)
+                        candidatePaths.push('/404', '/not-found');
+                    if (statusCode === 500)
+                        candidatePaths.push('/500');
+                    candidatePaths.push('/error');
+                    let errorRoute = null;
+                    for (const p of candidatePaths) {
+                        const found = allRoutes.find(r => r.path === p);
+                        if (found) {
+                            errorRoute = found;
+                            break;
+                        }
+                    }
                     try {
-                        if (PageModule) {
-                            if (PageModule.metadata && PageModule.metadata.title) {
-                                pageTitle = PageModule.metadata.title;
+                        if (errorRoute && errorRoute.component) {
+                            const erBase = path_1.default.basename(errorRoute.component).replace(/\.[^.]+$/, '');
+                            const erCompiled = path_1.default.join(tempDir, erBase + '.error.server.js');
+                            await bundler_1.bundler.bundleServer({ entryPoint: errorRoute.component, outfile: erCompiled, minify: false, root });
+                            try {
+                                delete require.cache[require.resolve(erCompiled)];
                             }
-                            else if (typeof PageModule.getMetadata === 'function') {
-                                const t = (key, params) => {
-                                    const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
-                                    let text = dict[key] || key;
-                                    if (params) {
-                                        Object.entries(params).forEach(([k, v]) => {
-                                            text = text.replace(new RegExp(`{${k}}`, 'g'), v);
-                                        });
-                                    }
-                                    return text;
-                                };
-                                const meta = await PageModule.getMetadata({ params: initialParams, locale, t });
-                                if (meta && meta.title)
-                                    pageTitle = meta.title;
+                            catch (e) { }
+                            const ErModule = require(erCompiled);
+                            const ErComp = (typeof ErModule === 'function') ? ErModule : (ErModule && typeof ErModule.default === 'function') ? ErModule.default : null;
+                            if (ErComp) {
+                                pageHTML = await renderComponentToHtml(ErComp, { error: errorPayload, reset: () => { } });
+                            }
+                            else {
+                                throw err;
                             }
                         }
+                        else {
+                            throw err;
+                        }
                     }
-                    catch (metaErr) {
-                        // ignore metadata extraction errors during error handling
+                    catch (e) {
+                        // Attempt to extract title from metadata for the error overlay
+                        let pageTitle;
+                        try {
+                            if (PageModule) {
+                                if (PageModule.metadata && PageModule.metadata.title) {
+                                    pageTitle = PageModule.metadata.title;
+                                }
+                                else if (typeof PageModule.getMetadata === 'function') {
+                                    const t = (key, params) => {
+                                        const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
+                                        let text = dict[key] || key;
+                                        if (params) {
+                                            Object.entries(params).forEach(([k, v]) => {
+                                                text = text.replace(new RegExp(`{${k}}`, 'g'), v);
+                                            });
+                                        }
+                                        return text;
+                                    };
+                                    const meta = await PageModule.getMetadata({ params: initialParams, locale, t });
+                                    if (meta && meta.title)
+                                        pageTitle = meta.title;
+                                }
+                            }
+                        }
+                        catch (metaErr) {
+                            // ignore metadata extraction errors during error handling
+                        }
+                        const errorInfo = {
+                            message: err?.message || String(err),
+                            stack: err?.stack,
+                            file: route.component,
+                            title: pageTitle,
+                        };
+                        const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
+                        res.writeHead(500, { 'Content-Type': 'text/html' });
+                        res.end(overlayHTML);
+                        return;
                     }
-                    const errorInfo = {
-                        message: err?.message || String(err),
-                        stack: err?.stack,
-                        file: route.component,
-                        title: pageTitle,
-                    };
-                    const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
-                    res.writeHead(500, { 'Content-Type': 'text/html' });
-                    res.end(overlayHTML);
-                    return;
                 }
             }
-        }
-        // expose routes + initial params to client for Router
-        const routePaths = allRoutes.length ? allRoutes.map(r => r.path) : [];
-        // Check whether layout and CSS ended up in the rendered HTML for debugging
-        try {
-            const hasHeader = pageHTML.includes('<header');
-            const hasFooter = pageHTML.includes('<footer');
-            console.log(`SSR: rendered page includes header=${hasHeader} footer=${hasFooter}`);
-            const cssPath = path_1.default.join(tempDir, 'globals.css');
-            console.log('SSR: globals.css exists at', cssPath, fs_1.default.existsSync(cssPath));
-        }
-        catch (e) {
-            // ignore
-        }
-        // attempt to obtain metadata from the page module (static or via getMetadata)
-        let metaHtml = '';
-        let htmlLang = 'en';
-        try {
-            const { renderMetaTags } = await import('../assets/metadata.js');
-            // metadata may be exported as `metadata` or `getMetadata` function
-            let metaObj = null;
-            if (PageModule && PageModule.metadata) {
-                metaObj = PageModule.metadata;
+            // expose routes + initial params to client for Router
+            const routePaths = allRoutes.length ? allRoutes.map(r => r.path) : [];
+            // Check whether layout and CSS ended up in the rendered HTML for debugging
+            try {
+                const hasHeader = pageHTML.includes('<header');
+                const hasFooter = pageHTML.includes('<footer');
+                console.log(`SSR: rendered page includes header=${hasHeader} footer=${hasFooter}`);
+                const cssPath = path_1.default.join(tempDir, 'globals.css');
+                console.log('SSR: globals.css exists at', cssPath, fs_1.default.existsSync(cssPath));
             }
-            else if (PageModule && typeof PageModule.getMetadata === 'function') {
-                try {
-                    const t = (key, params) => {
-                        const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
-                        let text = dict[key] || key;
-                        if (params) {
-                            Object.entries(params).forEach(([k, v]) => {
-                                text = text.replace(new RegExp(`{${k}}`, 'g'), v);
-                            });
-                        }
-                        return text;
-                    };
-                    metaObj = await PageModule.getMetadata({ params: initialParams, locale, t });
+            catch (e) {
+                // ignore
+            }
+            // attempt to obtain metadata from the page module (static or via getMetadata)
+            let metaHtml = '';
+            let htmlLang = 'en';
+            try {
+                const { renderMetaTags } = await import('../assets/metadata.js');
+                // metadata may be exported as `metadata` or `getMetadata` function
+                let metaObj = null;
+                if (PageModule && PageModule.metadata) {
+                    metaObj = PageModule.metadata;
                 }
-                catch (e) {
-                    metaObj = null;
+                else if (PageModule && typeof PageModule.getMetadata === 'function') {
+                    try {
+                        const t = (key, params) => {
+                            const dict = dictionaries[locale] || dictionaries['en-US'] || dictionaries[Object.keys(dictionaries)[0]] || {};
+                            let text = dict[key] || key;
+                            if (params) {
+                                Object.entries(params).forEach(([k, v]) => {
+                                    text = text.replace(new RegExp(`{${k}}`, 'g'), v);
+                                });
+                            }
+                            return text;
+                        };
+                        metaObj = await PageModule.getMetadata({ params: initialParams, locale, t });
+                    }
+                    catch (e) {
+                        metaObj = null;
+                    }
+                }
+                // The `<Head>` component was removed; rely on exported `metadata` or `getMetadata` from the page/layout module.
+                // Detect html lang from metadata if provided
+                if (metaObj && typeof metaObj.lang === 'string' && metaObj.lang.trim()) {
+                    htmlLang = metaObj.lang.trim();
                 }
+                metaHtml = renderMetaTags(metaObj);
             }
-            // The `<Head>` component was removed; rely on exported `metadata` or `getMetadata` from the page/layout module.
-            // Detect html lang from metadata if provided
-            if (metaObj && typeof metaObj.lang === 'string' && metaObj.lang.trim()) {
-                htmlLang = metaObj.lang.trim();
+            catch (e) {
+                // ignore
             }
-            metaHtml = renderMetaTags(metaObj);
-        }
-        catch (e) {
-            // ignore
-        }
-        const initialParamsScript = `<script>
-      window.__SATSET_ROUTES__ = ${JSON.stringify(routePaths)};
-      window.__SATSET_PARAMS__ = ${JSON.stringify(initialParams)};
-      window.__SATSET_DICTIONARIES__ = ${JSON.stringify(getDictionaries(root))};
+            const initialParamsScript = `<script>
+      window.__SATSET_ROUTES__ = ${JSON.stringify(routePaths)};
+      window.__SATSET_PARAMS__ = ${JSON.stringify(initialParams)};
+      window.__SATSET_DICTIONARIES__ = ${JSON.stringify(getDictionaries(root))};
+      window.__SATSET_LOCALE__ = "${locale}";
     </script>`;
-        // Determine favicon at request time (in case it was created/changed)
-        let computedFavicon = null;
-        try {
-            const publicPath = path_1.default.join(root, publicDirName);
-            if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.ico')))
-                computedFavicon = '/favicon.ico';
-            else if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.png')))
-                computedFavicon = '/favicon.png';
-        }
-        catch (e) {
-            // ignore
-        }
-        const faviconLink = computedFavicon ? `<link rel="icon" href="${computedFavicon}" />` : '';
-        const html = `
-<!DOCTYPE html>
-<html lang="${htmlLang}">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    ${metaHtml}
-    ${faviconLink}
-    <link rel="stylesheet" href="/_satset/globals.css" />
-  </head>
-  <body>
-    <div id="root">${pageHTML}</div>
-    <script>${envScript}</script>
-    ${initialParamsScript}
-    <script type="module" src="/_satset/_entry.js"></script>
-    <script src="/__hmr"></script>
-    <!-- ... rest of scripts -->
-  </body>
-</html>
+            // Determine favicon at request time (in case it was created/changed)
+            let computedFavicon = null;
+            try {
+                const publicPath = path_1.default.join(root, publicDirName);
+                if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.ico')))
+                    computedFavicon = '/favicon.ico';
+                else if (fs_1.default.existsSync(path_1.default.join(publicPath, 'favicon.png')))
+                    computedFavicon = '/favicon.png';
+            }
+            catch (e) {
+                // ignore
+            }
+            const faviconLink = computedFavicon ? `<link rel="icon" href="${computedFavicon}" />` : '';
+            let html = '';
+            const trimmedPageHTML = pageHTML.trim();
+            if (trimmedPageHTML.toLowerCase().startsWith('<html')) {
+                html = '<!DOCTYPE html>\n' + trimmedPageHTML;
+                const headContent = `
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    ${metaHtml}
+    ${faviconLink}
+    <link rel="stylesheet" href="/_satset/globals.css" />`;
+                if (html.includes('</head>')) {
+                    html = html.replace('</head>', `${headContent}</head>`);
+                }
+                const bodyScripts = `
+    <script>${envScript}</script>
+    ${initialParamsScript}
+    <script type="module" src="/_satset/_entry.js"></script>
+    <script src="/__hmr"></script>`;
+                if (html.includes('</body>')) {
+                    html = html.replace('</body>', `${bodyScripts}</body>`);
+                }
+            }
+            else {
+                html = `
+<!DOCTYPE html>
+<html lang="${htmlLang}" suppressHydrationWarning>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    ${metaHtml}
+    ${faviconLink}
+    <link rel="stylesheet" href="/_satset/globals.css" />
+  </head>
+  <body>
+    <div id="root">${pageHTML}</div>
+    <script>${envScript}</script>
+    ${initialParamsScript}
+    <script type="module" src="/_satset/_entry.js"></script>
+    <script src="/__hmr"></script>
+  </body>
+</html>
     `;
-        res.writeHead(statusCode, { 'Content-Type': 'text/html' });
-        res.end(html);
-    }
-    catch (error) {
-        const errorInfo = {
-            message: error.message,
-            stack: error.stack,
-            file: route.component,
-        };
-        if (route.component && fs_1.default.existsSync(route.component)) {
-            const stackLines = error.stack?.split('\n') || [];
-            const lineMatch = stackLines[0]?.match(/:(\d+):(\d+)/);
-            if (lineMatch) {
-                const line = parseInt(lineMatch[1]);
-                errorInfo.line = line;
-                errorInfo.column = parseInt(lineMatch[2]);
-                errorInfo.code = (0, error_overlay_1.extractCodeSnippet)(route.component, line);
             }
+            res.writeHead(statusCode, { 'Content-Type': 'text/html' });
+            res.end(html);
         }
-        const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
-        res.writeHead(500, { 'Content-Type': 'text/html' });
-        res.end(overlayHTML);
-    }
-    finally {
-        (0, response_1.setCurrentRequestCookies)(null);
-    }
+        catch (error) {
+            const errorInfo = {
+                message: error.message,
+                stack: error.stack,
+                file: route.component,
+            };
+            if (route.component && fs_1.default.existsSync(route.component)) {
+                const stackLines = error.stack?.split('\n') || [];
+                const lineMatch = stackLines[0]?.match(/:(\d+):(\d+)/);
+                if (lineMatch) {
+                    const line = parseInt(lineMatch[1]);
+                    errorInfo.line = line;
+                    errorInfo.column = parseInt(lineMatch[2]);
+                    errorInfo.code = (0, error_overlay_1.extractCodeSnippet)(route.component, line);
+                }
+            }
+            const overlayHTML = (0, error_overlay_1.generateErrorOverlayHTML)(errorInfo);
+            res.writeHead(500, { 'Content-Type': 'text/html' });
+            res.end(overlayHTML);
+        }
+        finally {
+            (0, response_1.setCurrentRequestCookies)(null);
+        }
+    });
 }
 async function runMiddleware(root, tempDir, req, res, effectivePath) {
     try {