@tyndall/build 0.0.1 → 0.0.2

package/dist/build.js

@@ -1,8 +1,8 @@
 import { copyFile, mkdir, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { createRouteGraph, loadConfig, renderClientRouterBootstrap, resolvePageModule, resolveUIAdapter, serializeProps, } from "@tyndall/core";
-import { buildModuleGraphSnapshot, computeGraphKey, computeCacheRootKey, getBunVersion, getOsArch, hash, normalizePath, readFileSafe, readModuleGraphCache, resolveCacheRoot, stableStringify, writeModuleGraphCache, } from "@tyndall/shared";
+import { createRouteGraph, loadConfig, resolveLayoutRouteId, routeDataKeyForLayout, routeDataKeyForPage, ROUTE_DATA_ERROR_KEY, ROUTE_DATA_INIT_KEY, SPECIAL_ROUTE_IDS, collectRouteLayouts, renderClientRouterBootstrap, resolvePageModule, resolveUIAdapter, runBeforeBundleHooks, runGetRouteData, runInitServer, serializeProps, } from "@tyndall/core";
+import { buildModuleGraphSnapshot, computeGraphKey, computeCacheRootKey, DEFAULT_IMPORT_EXTENSIONS, getBunVersion, getOsArch, hash, normalizePath, readFileSafe, readModuleGraphCache, resolveCacheRoot, stableStringify, writeModuleGraphCache, } from "@tyndall/shared";
 import { bundleClient, bundleServer, } from "./bundler.js";
 import { build as esbuild } from "esbuild";
 import { transform } from "@swc/core";
@@ -61,6 +61,16 @@ const resolveHyperVersion = async (rootDir) => {
         return "unknown";
     }
 };
+const STYLE_MODULE_EXTENSIONS = new Set([".css", ".scss", ".sass"]);
+const STYLE_MODULE_SUFFIXES = [".css.ts", ".css.tsx"];
+const isStyleModule = (filePath) => {
+    const lower = filePath.toLowerCase();
+    if (STYLE_MODULE_SUFFIXES.some((suffix) => lower.endsWith(suffix))) {
+        return true;
+    }
+    return STYLE_MODULE_EXTENSIONS.has(extname(lower));
+};
+const MODULE_GRAPH_EXTENSIONS = [...DEFAULT_IMPORT_EXTENSIONS, ".css", ".scss", ".sass"];
 const isStaticRoute = (route) => route.segments.every((segment) => segment.type === "static");
 const isDynamicRoute = (route) => route.segments.some((segment) => segment.type === "dynamic" || segment.type === "catchAll");
 const routeIdToPath = (routeId, params) => {
@@ -87,6 +97,183 @@ const writeFileSafe = async (filePath, contents) => {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, contents, "utf-8");
 };
+const resolveSpecialRouteRecords = (routeGraph, routesDir) => {
+    const specialFiles = routeGraph.specialFiles;
+    const records = {
+        notFound: null,
+        error: null,
+    };
+    if (specialFiles?.notFound) {
+        const resolution = collectRouteLayouts(specialFiles.notFound, routesDir);
+        records.notFound = {
+            id: SPECIAL_ROUTE_IDS.notFound,
+            filePath: specialFiles.notFound,
+            layoutFiles: resolution.layoutFiles,
+        };
+    }
+    if (specialFiles?.error) {
+        const resolution = collectRouteLayouts(specialFiles.error, routesDir);
+        records.error = {
+            id: SPECIAL_ROUTE_IDS.error,
+            filePath: specialFiles.error,
+            layoutFiles: resolution.layoutFiles,
+        };
+    }
+    return records;
+};
+const resolveInitServerHook = (module) => {
+    if (module && typeof module === "object") {
+        const record = module;
+        if (typeof record.initServer === "function") {
+            return record.initServer;
+        }
+        if (typeof record.default === "function") {
+            return record.default;
+        }
+    }
+    return undefined;
+};
+const resolveRouteDataHook = (module) => {
+    if (module && typeof module === "object" && typeof module.getRouteData === "function") {
+        return module.getRouteData;
+    }
+    return undefined;
+};
+const normalizeRedirect = (redirect) => {
+    if (!redirect) {
+        return null;
+    }
+    if (typeof redirect === "string") {
+        return { destination: redirect };
+    }
+    return {
+        destination: redirect.destination,
+        status: redirect.status,
+        replace: redirect.replace,
+    };
+};
+const normalizeError = (error) => {
+    if (!error) {
+        return null;
+    }
+    if (typeof error === "string") {
+        return { message: error };
+    }
+    return {
+        status: error.status,
+        message: error.message,
+    };
+};
+const collectRouteDataForRoute = async (input) => {
+    const dataMap = {};
+    const headers = {};
+    let status;
+    let redirect;
+    let error;
+    let initData;
+    let parentData;
+    if (input.initServerHook) {
+        const initResult = await runInitServer(input.initServerHook, {
+            routeId: input.routeId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+        });
+        if (initResult.data !== undefined) {
+            initData = initResult.data;
+            dataMap[ROUTE_DATA_INIT_KEY] = initResult.data;
+        }
+        if (initResult.headers) {
+            Object.assign(headers, initResult.headers);
+        }
+        if (initResult.status !== undefined) {
+            status = initResult.status;
+        }
+        if (initResult.redirect) {
+            redirect = initResult.redirect;
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+        if (initResult.error) {
+            error = initResult.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+    }
+    const layoutFiles = input.layoutFiles ?? [];
+    for (const layoutFile of layoutFiles) {
+        const layoutModule = await input.loadLayoutModule(layoutFile);
+        const hook = resolveRouteDataHook(layoutModule);
+        if (!hook) {
+            continue;
+        }
+        const layoutId = resolveLayoutRouteId(layoutFile, input.routesDir);
+        const result = await runGetRouteData(hook, {
+            routeId: layoutId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+            init: initData,
+            routeData: dataMap,
+            parentData,
+        });
+        if (result.data !== undefined) {
+            dataMap[routeDataKeyForLayout(layoutId)] = result.data;
+            parentData = result.data;
+        }
+        if (result.headers) {
+            Object.assign(headers, result.headers);
+        }
+        if (result.status !== undefined) {
+            status = result.status;
+        }
+        if (result.redirect) {
+            redirect = result.redirect;
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+        if (result.error) {
+            error = result.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+    }
+    if (input.pageModule?.getRouteData) {
+        const result = await runGetRouteData(input.pageModule.getRouteData, {
+            routeId: input.routeId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+            init: initData,
+            routeData: dataMap,
+            parentData,
+        });
+        if (result.data !== undefined) {
+            dataMap[routeDataKeyForPage(input.routeId)] = result.data;
+        }
+        if (result.headers) {
+            Object.assign(headers, result.headers);
+        }
+        if (result.status !== undefined) {
+            status = result.status;
+        }
+        if (result.redirect) {
+            redirect = result.redirect;
+        }
+        if (result.error) {
+            error = result.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+        }
+    }
+    return { data: dataMap, initData, headers, status, redirect, error };
+};
 const toPosixPath = (value) => value.split(sep).join("/");
 const toImportSpecifier = (fromDir, targetPath) => {
     const relativePath = toPosixPath(relative(fromDir, targetPath));
@@ -114,6 +301,40 @@ const appendBuildVersion = (value, buildVersion) => {
     const separator = value.includes("?") ? "&" : "?";
     return `${value}${separator}v=${encodeURIComponent(buildVersion)}`;
 };
+const escapeHtml = (value) => value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;");
+const renderStaticRedirectDocument = (destination) => {
+    const safe = escapeHtml(destination);
+    return [
+        "<!doctype html>",
+        "<html>",
+        "<head>",
+        `<meta http-equiv=\"refresh\" content=\"0;url=${safe}\">`,
+        `<script>window.location.replace(${JSON.stringify(destination)});</script>`,
+        "</head>",
+        "<body>",
+        `<a href=\"${safe}\">Redirecting...</a>`,
+        "</body>",
+        "</html>",
+    ].join("");
+};
+const renderStaticErrorDocument = (message) => {
+    const safe = escapeHtml(message);
+    return [
+        "<!doctype html>",
+        "<html>",
+        "<head>",
+        "<title>Route data error</title>",
+        "</head>",
+        "<body>",
+        `<main>${safe}</main>`,
+        "</body>",
+        "</html>",
+    ].join("");
+};
 const resolveBundleScripts = (bundle, routeId, basePath, assetsDir, buildVersion) => {
     const entryKey = bundle.entryChunks[routeId];
     if (!entryKey) {
@@ -138,6 +359,20 @@ const resolveBundleScripts = (bundle, routeId, basePath, assetsDir, buildVersion
     walk(entryKey);
     return scripts;
 };
+const resolveBundleStyleFile = (bundle, routeId) => {
+    const entryKey = bundle.entryChunks[routeId];
+    if (!entryKey) {
+        return null;
+    }
+    const chunk = bundle.chunks[entryKey];
+    if (!chunk) {
+        return null;
+    }
+    if (chunk.file.endsWith(".js")) {
+        return chunk.file.replace(/\.js$/, ".css");
+    }
+    return `${chunk.file}.css`;
+};
 const LEGACY_AUTO_POLYFILLS_FILE = "hyper-legacy-polyfills.js";
 const renderLegacyClientBootstrap = () => [
     "(function () {",
@@ -268,12 +503,20 @@ const resolveHyperCoreBrowserShimSource = async () => {
     const propsPath = await resolveCoreShimModulePath(entryDir, "props");
     const renderPolicyPath = await resolveCoreShimModulePath(entryDir, "render-policy");
     const resolverFallbackPath = await resolveCoreShimModulePath(entryDir, "resolver-fallback");
+    const routeDataPath = await resolveCoreShimModulePath(entryDir, "route-data");
     hyperCoreBrowserShimSource = {
         source: [
             `export { mergeHeadDescriptors } from ${JSON.stringify(headPath)};`,
             `export { serializeProps } from ${JSON.stringify(propsPath)};`,
             `export { evaluateRenderPolicy } from ${JSON.stringify(renderPolicyPath)};`,
             `export { shouldForceDynamicFallback } from ${JSON.stringify(resolverFallbackPath)};`,
+            `export {`,
+            `  ROUTE_DATA_SCRIPT_ID,`,
+            `  ROUTE_DATA_INIT_KEY,`,
+            `  ROUTE_DATA_ERROR_KEY,`,
+            `  routeDataKeyForPage,`,
+            `  routeDataKeyForLayout,`,
+            `} from ${JSON.stringify(routeDataPath)};`,
         ].join("\n"),
         // Required so esbuild resolves filesystem imports from a virtual namespace.
         resolveDir: entryDir,
@@ -287,6 +530,8 @@ const emitBundleAssets = async (bundle, outDir, assetsDir, chunkSource) => {
     }
 };
 const buildChunkFile = async (entryPath, outputPath, options) => {
+    const bundlerPlugins = options.plugins ?? [];
+    const shouldEmitCss = Boolean(options.emitCss && options.cssOutputPath);
     const shimSource = options.shimHyperCore ? await resolveHyperCoreBrowserShimSource() : null;
     const shimPlugin = shimSource
         ? {
@@ -309,6 +554,7 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
         : null;
     if (options.syntaxTarget === "es5") {
         try {
+            const plugins = shimPlugin ? [shimPlugin, ...bundlerPlugins] : [...bundlerPlugins];
             const bundled = await esbuild({
                 entryPoints: [entryPath],
                 bundle: true,
@@ -320,10 +566,13 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
                 minify: false,
                 logLevel: "silent",
                 jsx: "automatic",
-                plugins: shimPlugin ? [shimPlugin] : undefined,
+                plugins: plugins.length > 0 ? plugins : undefined,
                 write: false,
             });
-            const outputText = bundled.outputFiles?.[0]?.text;
+            const outputFiles = bundled.outputFiles ?? [];
+            const jsOutput = outputFiles.find((file) => file.path.endsWith(".js") || file.path.endsWith(".mjs")) ??
+                outputFiles[0];
+            const outputText = jsOutput?.text;
             if (!outputText) {
                 throw new Error("ES5 bundling produced no output.");
             }
@@ -338,6 +587,15 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
             });
             await mkdir(dirname(outputPath), { recursive: true });
             await writeFile(outputPath, transformed.code, "utf-8");
+            if (shouldEmitCss && options.cssOutputPath) {
+                const cssChunks = outputFiles
+                    .filter((file) => file.path.endsWith(".css"))
+                    .map((file) => file.text)
+                    .filter((text) => typeof text === "string" && text.length > 0);
+                if (cssChunks.length > 0) {
+                    await writeFileSafe(options.cssOutputPath, cssChunks.join("\n"));
+                }
+            }
         }
         catch (error) {
             const messages = typeof error === "object" && error !== null && "errors" in error
@@ -355,6 +613,7 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
     }
     const tempOutDir = join(dirname(outputPath), `.@tyndall/build-tmp-${hash(`${outputPath}-${Date.now()}`)}`);
     await mkdir(tempOutDir, { recursive: true });
+    const plugins = shimPlugin ? [shimPlugin, ...bundlerPlugins] : [...bundlerPlugins];
     const result = await bun.build({
         entrypoints: [entryPath],
         outdir: tempOutDir,
@@ -364,7 +623,7 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
         splitting: false,
         sourcemap: "none",
         minify: false,
-        plugins: shimPlugin ? [shimPlugin] : undefined,
+        plugins: plugins.length > 0 ? plugins : undefined,
     });
     if (!result.success) {
         const errors = (result.logs ?? [])
@@ -380,10 +639,59 @@ const buildChunkFile = async (entryPath, outputPath, options) => {
         await rm(tempOutDir, { recursive: true, force: true }).catch(() => { });
         throw new Error(`Build chunk output is missing (${entryPath}).`);
     }
+    if (shouldEmitCss && options.cssOutputPath) {
+        const cssOutputs = (result.outputs ?? [])
+            .map((output) => output.path)
+            .filter((path) => typeof path === "string" && path.endsWith(".css"));
+        if (cssOutputs.length > 0) {
+            const cssChunks = [];
+            const ordered = [...cssOutputs].sort((left, right) => left.localeCompare(right));
+            for (const cssPath of ordered) {
+                const content = await readFileSafe(cssPath, "utf-8");
+                if (typeof content === "string" && content.length > 0) {
+                    cssChunks.push(content);
+                }
+                else if (content instanceof Uint8Array && content.length > 0) {
+                    cssChunks.push(Buffer.from(content).toString("utf-8"));
+                }
+            }
+            if (cssChunks.length > 0) {
+                await writeFileSafe(options.cssOutputPath, cssChunks.join("\n"));
+            }
+        }
+    }
     await mkdir(dirname(outputPath), { recursive: true });
     await copyFile(emittedPath, outputPath);
     await rm(tempOutDir, { recursive: true, force: true }).catch(() => { });
 };
+const SERVER_ONLY_MODULE_PATTERN = /\.server\.[cm]?[jt]sx?$/i;
+const collectServerOnlyModules = (modules) => modules.filter((modulePath) => SERVER_ONLY_MODULE_PATTERN.test(modulePath));
+const assertNoServerOnlyClientImports = async (snapshot, appModule) => {
+    const offenders = [];
+    const routeIds = Object.keys(snapshot.routeToModules).sort((a, b) => a.localeCompare(b));
+    for (const routeId of routeIds) {
+        const modules = snapshot.routeToModules[routeId] ?? [];
+        const hits = collectServerOnlyModules(modules);
+        if (hits.length > 0) {
+            offenders.push({ scope: `route "${routeId}"`, modules: hits });
+        }
+    }
+    if (appModule) {
+        const appSnapshot = buildModuleGraphSnapshot([{ id: "__hyper_app__", filePath: appModule }]);
+        const appModules = appSnapshot.routeToModules["__hyper_app__"] ?? [];
+        const hits = collectServerOnlyModules(appModules);
+        if (hits.length > 0) {
+            offenders.push({ scope: "app", modules: hits });
+        }
+    }
+    if (offenders.length === 0) {
+        return;
+    }
+    const details = offenders
+        .map((entry) => `${entry.scope}: ${entry.modules.join(", ")}`)
+        .join(" | ");
+    throw new Error(`Server-only modules (.server.*) cannot be imported into client bundles. Found ${details}.`);
+};
 const dynamicImportPattern = /import\s*\(/;
 const findDynamicImportModules = async (modulePaths) => {
     const offenders = [];
@@ -406,6 +714,7 @@ export const build = async (options) => {
     const outDir = resolvePath(rootDir, options.outDir ?? "dist");
     const mode = options.mode ?? "ssg";
     const config = await loadConfig(rootDir);
+    const hyperPlugins = config.plugins;
     const buildVersion = config.build.version.trim();
     const adapterRegistry = options.adapterRegistry ?? {};
     const ssrClientRoutingEnabled = mode === "ssr" && config.routing.ssrClientRouting;
@@ -414,6 +723,7 @@ export const build = async (options) => {
         navigationMode: resolvedNavigationMode,
         clientRenderMode: config.routing.clientRender,
         linkInterceptionMode: ssrClientRoutingEnabled ? "all" : "marked",
+        scrollRestoration: config.routing.scrollRestoration,
     });
     const legacyBootstrapChunk = renderLegacyClientBootstrap();
     const legacyEnabled = config.legacy.enabled;
@@ -445,19 +755,36 @@ export const build = async (options) => {
         ? await resolveGraphKey(rootDir, {
             client: { format: "esm", target: modernTarget },
             server: mode === "ssr" ? { format: "cjs", target: serverTarget } : null,
+            moduleGraphExtensions: MODULE_GRAPH_EXTENSIONS,
         })
         : null;
     const envHash = cache.enabled ? hash(stableStringify(process.env)) : "disabled";
     let depsHashByEntry = null;
     let legacyBundle = null;
+    let routeHasStyles = {};
     const routeModules = new Map();
     const routeById = new Map();
     const clientRuntimeEntries = new Map();
     const serverRuntimeEntries = new Map();
+    const layoutModuleCache = new Map();
+    let specialRouteFiles = null;
+    let specialRouteRecords = {
+        notFound: null,
+        error: null,
+    };
+    let initServerHook;
+    let documentRenderers = null;
     const entryWorkspaceRoot = join(cacheRoot, "build-runtime-entries", hash(`${Date.now()}-${Math.random()}`).slice(0, 12));
     // Important: clear output to avoid stale HTML/chunks when route render policy changes.
     await rm(outDir, { recursive: true, force: true }).catch(() => { });
     await mkdir(outDir, { recursive: true });
+    const computeRouteStyleMap = (snapshot) => {
+        const map = {};
+        for (const [routeId, modules] of Object.entries(snapshot.routeToModules)) {
+            map[routeId] = modules.some((modulePath) => isStyleModule(modulePath));
+        }
+        routeHasStyles = map;
+    };
     const assertLegacyChunkingSafe = async (snapshot) => {
         if (!legacyEnabled || config.legacy.chunking !== "safe") {
             return;
@@ -489,6 +816,48 @@ export const build = async (options) => {
         }
         return result;
     };
+    const loadLayoutModule = async (filePath) => {
+        const cached = layoutModuleCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        const loaded = await import(`${pathToFileURL(filePath).href}?build=${Date.now()}-${hash(filePath).slice(0, 6)}`);
+        layoutModuleCache.set(filePath, loaded);
+        return loaded;
+    };
+    const resolveInitServer = async () => {
+        if (initServerHook !== undefined) {
+            return initServerHook;
+        }
+        if (!specialRouteFiles?.initServer) {
+            initServerHook = undefined;
+            return undefined;
+        }
+        const loaded = await import(`${pathToFileURL(specialRouteFiles.initServer).href}?build=${Date.now()}-${hash("init").slice(0, 6)}`);
+        initServerHook = resolveInitServerHook(loaded);
+        return initServerHook;
+    };
+    const resolveDocumentRenderers = async () => {
+        if (documentRenderers) {
+            return documentRenderers;
+        }
+        if (!specialRouteFiles?.document) {
+            documentRenderers = { renderDocument: undefined, renderDocumentFragments: undefined };
+            return documentRenderers;
+        }
+        const loaded = await import(`${pathToFileURL(specialRouteFiles.document).href}?build=${Date.now()}-${hash("document").slice(0, 6)}`);
+        const record = loaded;
+        const renderDocument = typeof record.renderDocument === "function"
+            ? record.renderDocument
+            : typeof record.default === "function"
+                ? record.default
+                : undefined;
+        const renderDocumentFragments = typeof record.renderDocumentFragments === "function"
+            ? record.renderDocumentFragments
+            : undefined;
+        documentRenderers = { renderDocument, renderDocumentFragments };
+        return documentRenderers;
+    };
     try {
         const result = await runBuildPipeline({ rootDir, routesDir, outDir, publicDir, cache }, {
             scanRoutes: () => createRouteGraph({
@@ -498,14 +867,33 @@ export const build = async (options) => {
             }),
             analyzeGraph: async (_ctx, state) => {
                 const routes = state.routeGraph?.routes ?? [];
+                specialRouteFiles = state.routeGraph?.specialFiles ?? null;
+                specialRouteRecords = state.routeGraph
+                    ? resolveSpecialRouteRecords(state.routeGraph, routesDir)
+                    : { notFound: null, error: null };
                 routeById.clear();
                 for (const route of routes) {
                     routeById.set(route.id, route);
                 }
                 const entries = routes.map((route) => ({ id: route.id, filePath: route.filePath }));
+                if (specialRouteRecords.notFound) {
+                    entries.push({
+                        id: SPECIAL_ROUTE_IDS.notFound,
+                        filePath: specialRouteRecords.notFound.filePath,
+                    });
+                }
+                if (specialRouteRecords.error) {
+                    entries.push({
+                        id: SPECIAL_ROUTE_IDS.error,
+                        filePath: specialRouteRecords.error.filePath,
+                    });
+                }
                 if (!cache.enabled || !graphKey) {
-                    const snapshot = buildModuleGraphSnapshot(entries);
+                    const snapshot = buildModuleGraphSnapshot(entries, { extensions: MODULE_GRAPH_EXTENSIONS });
+                    // Guard: client bundles must never include server-only modules.
+                    await assertNoServerOnlyClientImports(snapshot, specialRouteFiles?.app);
                     await assertLegacyChunkingSafe(snapshot);
+                    computeRouteStyleMap(snapshot);
                     depsHashByEntry = cache.enabled ? await computeDepsHashByEntry(snapshot) : null;
                     return snapshot;
                 }
@@ -514,12 +902,16 @@ export const build = async (options) => {
                     // Important: cached graph must cover all current routes to be valid.
                     const hasAllRoutes = entries.every((route) => cached.routeToModules[route.id]);
                     if (hasAllRoutes) {
+                        await assertNoServerOnlyClientImports(cached, specialRouteFiles?.app);
                         await assertLegacyChunkingSafe(cached);
+                        computeRouteStyleMap(cached);
                         depsHashByEntry = await computeDepsHashByEntry(cached);
                         return cached;
                     }
                 }
-                const snapshot = buildModuleGraphSnapshot(entries);
+                const snapshot = buildModuleGraphSnapshot(entries, { extensions: MODULE_GRAPH_EXTENSIONS });
+                await assertNoServerOnlyClientImports(snapshot, specialRouteFiles?.app);
+                computeRouteStyleMap(snapshot);
                 await writeModuleGraphCache(cacheRoot, graphKey, snapshot);
                 await assertLegacyChunkingSafe(snapshot);
                 depsHashByEntry = await computeDepsHashByEntry(snapshot);
@@ -535,11 +927,15 @@ export const build = async (options) => {
                     navigationMode: resolvedNavigationMode,
                     clientRenderMode: config.routing.clientRender,
                 }, adapterRegistry);
-                if (typeof entryAdapter.createClientEntry !== "function") {
+                const createClientEntry = entryAdapter.createClientEntry;
+                if (typeof createClientEntry !== "function") {
                     throw new Error(`UI adapter \"${entryAdapter.name}\" does not support createClientEntry.`);
                 }
                 const clientEntryDir = join(entryWorkspaceRoot, "client");
                 await mkdir(clientEntryDir, { recursive: true });
+                const appModule = specialRouteFiles?.app
+                    ? toImportSpecifier(clientEntryDir, specialRouteFiles.app)
+                    : undefined;
                 const buildClientRouteModules = routeGraph.routes.reduce((acc, route) => {
                     acc[route.id] = toImportSpecifier(clientEntryDir, route.filePath);
                     return acc;
@@ -549,25 +945,30 @@ export const build = async (options) => {
                 for (const route of routeGraph.routes) {
                     const entryFilePath = join(clientEntryDir, `entry-${hash(route.id).slice(0, 12)}.tsx`);
                     const pageModule = toImportSpecifier(clientEntryDir, route.filePath);
-                    const entrySource = entryAdapter.createClientEntry({
+                    const entrySource = createClientEntry({
                         routeId: route.id,
                         routeGraph,
                         basePath: config.basePath,
                         rootDir,
                         entryDir: clientEntryDir,
+                        entryLayoutFiles: route.layoutFiles,
                         uiOptions: {
                             ...config.ui.options,
                             pageModule,
+                            appModule,
                             navigationMode: resolvedNavigationMode,
                             clientRenderMode: config.routing.clientRender,
+                            scrollRestoration: config.routing.scrollRestoration,
                             clientRouteModules: buildClientRouteModules,
                             nestedLayouts: config.routing.nestedLayouts,
                         },
                         adapterOptions: {
                             ...config.ui.options,
                             pageModule,
+                            appModule,
                             navigationMode: resolvedNavigationMode,
                             clientRenderMode: config.routing.clientRender,
+                            scrollRestoration: config.routing.scrollRestoration,
                             clientRouteModules: buildClientRouteModules,
                             nestedLayouts: config.routing.nestedLayouts,
                         },
@@ -579,6 +980,49 @@ export const build = async (options) => {
                     clientRuntimeEntries.set(route.id, entryFilePath);
                     entries.push({ id: route.id, input: entryFilePath });
                 }
+                const addSpecialClientEntry = async (record) => {
+                    if (!record) {
+                        return;
+                    }
+                    const entryFilePath = join(clientEntryDir, `entry-${hash(record.id).slice(0, 12)}.tsx`);
+                    const pageModule = toImportSpecifier(clientEntryDir, record.filePath);
+                    const entrySource = createClientEntry({
+                        routeId: record.id,
+                        routeGraph,
+                        basePath: config.basePath,
+                        rootDir,
+                        entryDir: clientEntryDir,
+                        entryLayoutFiles: record.layoutFiles,
+                        uiOptions: {
+                            ...config.ui.options,
+                            pageModule,
+                            appModule,
+                            navigationMode: resolvedNavigationMode,
+                            clientRenderMode: config.routing.clientRender,
+                            scrollRestoration: config.routing.scrollRestoration,
+                            clientRouteModules: buildClientRouteModules,
+                            nestedLayouts: config.routing.nestedLayouts,
+                        },
+                        adapterOptions: {
+                            ...config.ui.options,
+                            pageModule,
+                            appModule,
+                            navigationMode: resolvedNavigationMode,
+                            clientRenderMode: config.routing.clientRender,
+                            scrollRestoration: config.routing.scrollRestoration,
+                            clientRouteModules: buildClientRouteModules,
+                            nestedLayouts: config.routing.nestedLayouts,
+                        },
+                    });
+                    if (typeof entrySource !== "string" || entrySource.trim().length === 0) {
+                        throw new Error(`Client entry generation failed for route ${record.id}`);
+                    }
+                    await writeFileSafe(entryFilePath, `${entrySource}\n\n${clientBootstrapChunk}\n`);
+                    clientRuntimeEntries.set(record.id, entryFilePath);
+                    entries.push({ id: record.id, input: entryFilePath });
+                };
+                await addSpecialClientEntry(specialRouteRecords.notFound);
+                await addSpecialClientEntry(specialRouteRecords.error);
                 const clientFormat = isEs5Target ? "iife" : "esm";
                 const modernBundle = await bundleWithCache("client", entries, clientFormat, bundleClient, modernTarget);
                 if (legacyEnabled && !isEs5Target) {
@@ -597,18 +1041,28 @@ export const build = async (options) => {
                         navigationMode: resolvedNavigationMode,
                         clientRenderMode: config.routing.clientRender,
                     }, adapterRegistry);
-                    if (typeof entryAdapter.createServerEntry !== "function") {
+                    const createServerEntry = entryAdapter.createServerEntry;
+                    if (typeof createServerEntry !== "function") {
                         throw new Error(`UI adapter \"${entryAdapter.name}\" does not support createServerEntry.`);
                     }
                     const serverEntryDir = join(entryWorkspaceRoot, "server");
                     await mkdir(serverEntryDir, { recursive: true });
                     const entries = [];
                     serverRuntimeEntries.clear();
+                    const appModule = specialRouteFiles?.app
+                        ? toImportSpecifier(serverEntryDir, specialRouteFiles.app)
+                        : undefined;
+                    const documentModule = specialRouteFiles?.document
+                        ? toImportSpecifier(serverEntryDir, specialRouteFiles.document)
+                        : undefined;
+                    const initServerModule = specialRouteFiles?.initServer
+                        ? toImportSpecifier(serverEntryDir, specialRouteFiles.initServer)
+                        : undefined;
                     for (const route of routeGraph.routes) {
                         const pageModule = toImportSpecifier(serverEntryDir, route.filePath);
                         const rawEntryFilePath = join(serverEntryDir, `entry-${hash(route.id).slice(0, 12)}.raw.tsx`);
                         const wrappedEntryFilePath = join(serverEntryDir, `entry-${hash(route.id).slice(0, 12)}.ts`);
-                        const serverEntrySource = entryAdapter.createServerEntry({
+                        const serverEntrySource = createServerEntry({
                             routeId: route.id,
                             routeGraph,
                             basePath: config.basePath,
@@ -617,6 +1071,7 @@ export const build = async (options) => {
                             uiOptions: {
                                 ...config.ui.options,
                                 pageModule,
+                                appModule,
                                 navigationMode: resolvedNavigationMode,
                                 clientRenderMode: config.routing.clientRender,
                                 nestedLayouts: config.routing.nestedLayouts,
@@ -624,6 +1079,7 @@ export const build = async (options) => {
                             adapterOptions: {
                                 ...config.ui.options,
                                 pageModule,
+                                appModule,
                                 navigationMode: resolvedNavigationMode,
                                 clientRenderMode: config.routing.clientRender,
                                 nestedLayouts: config.routing.nestedLayouts,
@@ -634,9 +1090,27 @@ export const build = async (options) => {
                         }
                         await writeFileSafe(rawEntryFilePath, serverEntrySource);
                         const rawSpecifier = toImportSpecifier(serverEntryDir, rawEntryFilePath);
+                        const layoutFiles = route.layoutFiles ?? [];
+                        const layoutImports = layoutFiles.map((layoutFile, index) => {
+                            const specifier = toImportSpecifier(serverEntryDir, layoutFile);
+                            return `import * as layoutModule${index} from ${JSON.stringify(specifier)};`;
+                        });
+                        const layoutEntries = layoutFiles.map((layoutFile, index) => {
+                            const layoutId = resolveLayoutRouteId(layoutFile, routesDir);
+                            return `  { key: ${JSON.stringify(routeDataKeyForLayout(layoutId))}, routeId: ${JSON.stringify(layoutId)}, hook: typeof layoutModule${index}.getRouteData === \"function\" ? layoutModule${index}.getRouteData : undefined },`;
+                        });
+                        const initServerImport = initServerModule
+                            ? `import * as initServerModule from ${JSON.stringify(initServerModule)};`
+                            : "";
+                        const documentImport = documentModule
+                            ? `import * as documentModule from ${JSON.stringify(documentModule)};`
+                            : "";
                         const wrapperSource = [
                             `import * as pageModule from ${JSON.stringify(pageModule)};`,
                             `import * as serverEntryModule from ${JSON.stringify(rawSpecifier)};`,
+                            initServerImport,
+                            documentImport,
+                            ...layoutImports,
                             "export const renderToHtml = serverEntryModule.renderToHtml;",
                             "export const renderToStream = serverEntryModule.renderToStream;",
                             "export const hydration =",
@@ -647,12 +1121,118 @@ export const build = async (options) => {
                             "  typeof pageModule.getServerProps === \"function\" ? pageModule.getServerProps : undefined;",
                             "export const getServerSideProps =",
                             "  typeof pageModule.getServerSideProps === \"function\" ? pageModule.getServerSideProps : undefined;",
+                            "export const getRouteData =",
+                            "  typeof pageModule.getRouteData === \"function\" ? pageModule.getRouteData : undefined;",
+                            initServerModule
+                                ? "export const initServer = typeof initServerModule.initServer === \"function\" ? initServerModule.initServer : (typeof initServerModule.default === \"function\" ? initServerModule.default : undefined);"
+                                : "export const initServer = undefined;",
+                            documentModule
+                                ? "export const renderDocument = typeof documentModule.renderDocument === \"function\" ? documentModule.renderDocument : (typeof documentModule.default === \"function\" ? documentModule.default : undefined);"
+                                : "export const renderDocument = undefined;",
+                            documentModule
+                                ? "export const renderDocumentFragments = typeof documentModule.renderDocumentFragments === \"function\" ? documentModule.renderDocumentFragments : undefined;"
+                                : "export const renderDocumentFragments = undefined;",
+                            "export const routeDataEntries = [",
+                            ...layoutEntries,
+                            `  { key: ${JSON.stringify(routeDataKeyForPage(route.id))}, routeId: ${JSON.stringify(route.id)}, hook: typeof pageModule.getRouteData === \"function\" ? pageModule.getRouteData : undefined },`,
+                            "];",
                             "",
                         ].join("\n");
                         await writeFileSafe(wrappedEntryFilePath, wrapperSource);
                         serverRuntimeEntries.set(route.id, wrappedEntryFilePath);
                         entries.push({ id: route.id, input: wrappedEntryFilePath });
                     }
+                    const addSpecialServerEntry = async (record) => {
+                        if (!record) {
+                            return;
+                        }
+                        const pageModule = toImportSpecifier(serverEntryDir, record.filePath);
+                        const rawEntryFilePath = join(serverEntryDir, `entry-${hash(record.id).slice(0, 12)}.raw.tsx`);
+                        const wrappedEntryFilePath = join(serverEntryDir, `entry-${hash(record.id).slice(0, 12)}.ts`);
+                        const serverEntrySource = createServerEntry({
+                            routeId: record.id,
+                            routeGraph,
+                            basePath: config.basePath,
+                            rootDir,
+                            entryDir: serverEntryDir,
+                            uiOptions: {
+                                ...config.ui.options,
+                                pageModule,
+                                appModule,
+                                entryLayoutFiles: record.layoutFiles,
+                                navigationMode: resolvedNavigationMode,
+                                clientRenderMode: config.routing.clientRender,
+                                nestedLayouts: config.routing.nestedLayouts,
+                            },
+                            adapterOptions: {
+                                ...config.ui.options,
+                                pageModule,
+                                appModule,
+                                entryLayoutFiles: record.layoutFiles,
+                                navigationMode: resolvedNavigationMode,
+                                clientRenderMode: config.routing.clientRender,
+                                nestedLayouts: config.routing.nestedLayouts,
+                            },
+                        });
+                        if (typeof serverEntrySource !== "string" || serverEntrySource.trim().length === 0) {
+                            throw new Error(`Server entry generation failed for route ${record.id}`);
+                        }
+                        await writeFileSafe(rawEntryFilePath, serverEntrySource);
+                        const rawSpecifier = toImportSpecifier(serverEntryDir, rawEntryFilePath);
+                        const layoutFiles = record.layoutFiles ?? [];
+                        const layoutImports = layoutFiles.map((layoutFile, index) => {
+                            const specifier = toImportSpecifier(serverEntryDir, layoutFile);
+                            return `import * as layoutModule${index} from ${JSON.stringify(specifier)};`;
+                        });
+                        const layoutEntries = layoutFiles.map((layoutFile, index) => {
+                            const layoutId = resolveLayoutRouteId(layoutFile, routesDir);
+                            return `  { key: ${JSON.stringify(routeDataKeyForLayout(layoutId))}, routeId: ${JSON.stringify(layoutId)}, hook: typeof layoutModule${index}.getRouteData === \"function\" ? layoutModule${index}.getRouteData : undefined },`;
+                        });
+                        const initServerImport = initServerModule
+                            ? `import * as initServerModule from ${JSON.stringify(initServerModule)};`
+                            : "";
+                        const documentImport = documentModule
+                            ? `import * as documentModule from ${JSON.stringify(documentModule)};`
+                            : "";
+                        const wrapperSource = [
+                            `import * as pageModule from ${JSON.stringify(pageModule)};`,
+                            `import * as serverEntryModule from ${JSON.stringify(rawSpecifier)};`,
+                            initServerImport,
+                            documentImport,
+                            ...layoutImports,
+                            "export const renderToHtml = serverEntryModule.renderToHtml;",
+                            "export const renderToStream = serverEntryModule.renderToStream;",
+                            "export const hydration =",
+                            "  serverEntryModule.hydration === \"full\" || serverEntryModule.hydration === \"islands\"",
+                            "    ? serverEntryModule.hydration",
+                            "    : \"islands\";",
+                            "export const getServerProps =",
+                            "  typeof pageModule.getServerProps === \"function\" ? pageModule.getServerProps : undefined;",
+                            "export const getServerSideProps =",
+                            "  typeof pageModule.getServerSideProps === \"function\" ? pageModule.getServerSideProps : undefined;",
+                            "export const getRouteData =",
+                            "  typeof pageModule.getRouteData === \"function\" ? pageModule.getRouteData : undefined;",
+                            initServerModule
+                                ? "export const initServer = typeof initServerModule.initServer === \"function\" ? initServerModule.initServer : (typeof initServerModule.default === \"function\" ? initServerModule.default : undefined);"
+                                : "export const initServer = undefined;",
+                            documentModule
+                                ? "export const renderDocument = typeof documentModule.renderDocument === \"function\" ? documentModule.renderDocument : (typeof documentModule.default === \"function\" ? documentModule.default : undefined);"
+                                : "export const renderDocument = undefined;",
+                            documentModule
+                                ? "export const renderDocumentFragments = typeof documentModule.renderDocumentFragments === \"function\" ? documentModule.renderDocumentFragments : undefined;"
+                                : "export const renderDocumentFragments = undefined;",
+                            "export const routeDataEntries = [",
+                            ...layoutEntries,
+                            `  { key: ${JSON.stringify(routeDataKeyForPage(record.id))}, routeId: ${JSON.stringify(record.id)}, hook: typeof pageModule.getRouteData === \"function\" ? pageModule.getRouteData : undefined },`,
+                            "];",
+                            "",
+                        ].join("\n");
+                        await writeFileSafe(wrappedEntryFilePath, wrapperSource);
+                        serverRuntimeEntries.set(record.id, wrappedEntryFilePath);
+                        entries.push({ id: record.id, input: wrappedEntryFilePath });
+                    };
+                    await addSpecialServerEntry(specialRouteRecords.notFound);
+                    await addSpecialServerEntry(specialRouteRecords.error);
                     return bundleWithCache("server", entries, "cjs", bundleServer, serverTarget);
                 }
                 : undefined,
@@ -741,37 +1321,160 @@ export const build = async (options) => {
                     return {};
                 }
                 const outputs = {};
-                for (const entry of entries) {
-                    const route = routeById.get(entry.routeId);
-                    const pageModule = routeModules.get(entry.routeId);
-                    if (!route || !pageModule) {
-                        continue;
-                    }
-                    const depsHash = depsHashByEntry?.[entry.routeId] ?? "missing";
-                    const propsHash = computePropsHash(entry.props);
-                    const scripts = resolveBundleScripts(clientBundle, entry.routeId, config.basePath, assetsDir, buildVersion);
+                const initServer = await resolveInitServer();
+                const errorRecord = specialRouteRecords.error;
+                const notFoundRecord = specialRouteRecords.notFound;
+                let errorPageModule = null;
+                if (errorRecord) {
+                    const loaded = await import(`${pathToFileURL(errorRecord.filePath).href}?build=${Date.now()}-${hash("error").slice(0, 6)}`);
+                    errorPageModule = resolvePageModule(loaded);
+                }
+                let notFoundPageModule = null;
+                if (notFoundRecord) {
+                    const loaded = await import(`${pathToFileURL(notFoundRecord.filePath).href}?build=${Date.now()}-${hash("not-found").slice(0, 6)}`);
+                    notFoundPageModule = resolvePageModule(loaded);
+                }
+                const resolveAssetsForRoute = (routeId) => {
+                    const scripts = resolveBundleScripts(clientBundle, routeId, config.basePath, assetsDir, buildVersion);
+                    const styleFile = routeHasStyles[routeId]
+                        ? resolveBundleStyleFile(clientBundle, routeId)
+                        : null;
+                    const styles = styleFile
+                        ? [appendBuildVersion(resolveAssetUrl(config.basePath, assetsDir, styleFile), buildVersion)]
+                        : [];
                     const legacyPolyfillScripts = legacyEnabled
                         ? legacyPolyfillPlan.scripts.map((script) => appendBuildVersion(script, buildVersion))
                         : [];
                     const legacyBundleScripts = legacyEnabled && legacyBundle
-                        ? resolveBundleScripts(legacyBundle, entry.routeId, config.basePath, assetsDir, buildVersion)
+                        ? resolveBundleScripts(legacyBundle, routeId, config.basePath, assetsDir, buildVersion)
                         : [];
                     const legacyScripts = legacyEnabled && !isEs5Target
                         ? [...legacyPolyfillScripts, ...legacyBundleScripts]
                         : [];
-                    const assets = {
-                        scripts: isEs5Target ? [...legacyPolyfillScripts, ...scripts] : scripts,
-                        legacyScripts,
-                        scriptType: clientScriptType,
-                        buildVersion,
+                    return {
+                        scripts,
+                        assets: {
+                            scripts: isEs5Target ? [...legacyPolyfillScripts, ...scripts] : scripts,
+                            legacyScripts,
+                            styles,
+                            scriptType: clientScriptType,
+                            buildVersion,
+                        },
                     };
-                    const templateHash = computeTemplateHash(defaultHtmlTemplate, assets);
+                };
+                const documentRenderers = await resolveDocumentRenderers();
+                const documentTemplate = documentRenderers.renderDocument || documentRenderers.renderDocumentFragments
+                    ? (ctx) => {
+                        if (documentRenderers.renderDocument) {
+                            try {
+                                const custom = documentRenderers.renderDocument(ctx);
+                                if (typeof custom === "string") {
+                                    return custom;
+                                }
+                            }
+                            catch {
+                                // Fall back to default template if custom document fails.
+                            }
+                        }
+                        if (documentRenderers.renderDocumentFragments) {
+                            try {
+                                const fragments = documentRenderers.renderDocumentFragments(ctx);
+                                if (fragments &&
+                                    typeof fragments.prefix === "string" &&
+                                    typeof fragments.suffix === "string") {
+                                    return `${fragments.prefix}${ctx.html}${fragments.suffix}`;
+                                }
+                            }
+                            catch {
+                                // Fall back to default template if fragments fail.
+                            }
+                        }
+                        return defaultHtmlTemplate(ctx);
+                    }
+                    : defaultHtmlTemplate;
+                for (const entry of entries) {
+                    const route = routeById.get(entry.routeId);
+                    const pageModule = routeModules.get(entry.routeId);
+                    if (!route || !pageModule) {
+                        continue;
+                    }
+                    const routeDataResult = await collectRouteDataForRoute({
+                        routeId: entry.routeId,
+                        routesDir,
+                        params: entry.params,
+                        layoutFiles: route.layoutFiles,
+                        pageModule,
+                        initServerHook: initServer,
+                        loadLayoutModule,
+                    });
+                    const redirect = normalizeRedirect(routeDataResult.redirect);
+                    if (redirect) {
+                        const redirectHtml = renderStaticRedirectDocument(redirect.destination);
+                        const routePath = routeIdToPath(entry.routeId, entry.params);
+                        const htmlPath = routePath
+                            ? join(outDir, routePath, "index.html")
+                            : join(outDir, "index.html");
+                        await writeFileSafe(htmlPath, redirectHtml);
+                        outputs[routePath || "/"] = redirectHtml;
+                        continue;
+                    }
+                    if (routeDataResult.error) {
+                        const normalizedError = normalizeError(routeDataResult.error);
+                        if (normalizedError && errorRecord && errorPageModule) {
+                            const errorAdapter = resolveUIAdapter(config.ui.adapter, {
+                                ...config.ui.options,
+                                navigationMode: resolvedNavigationMode,
+                                clientRenderMode: config.routing.clientRender,
+                                nestedLayouts: config.routing.nestedLayouts,
+                                routeGraph,
+                                rootDir,
+                                appModule: specialRouteFiles?.app,
+                                routeRender: (props) => errorPageModule.default(props),
+                                routeHead: errorPageModule.head
+                                    ? (props) => errorPageModule.head(props)
+                                    : undefined,
+                            }, adapterRegistry);
+                            const { assets } = resolveAssetsForRoute(errorRecord.id);
+                            const errorRendered = await renderHtml({
+                                renderToHtml: (ctx) => errorAdapter.renderToHtml(ctx),
+                                serializeProps: errorAdapter.serializeProps ?? serializeProps,
+                            }, {
+                                routeId: errorRecord.id,
+                                props: {
+                                    error: normalizedError,
+                                    routeId: entry.routeId,
+                                },
+                                routeData: routeDataResult.data,
+                            }, documentTemplate, assets);
+                            const routePath = routeIdToPath(entry.routeId, entry.params);
+                            const htmlPath = routePath
+                                ? join(outDir, routePath, "index.html")
+                                : join(outDir, "index.html");
+                            await writeFileSafe(htmlPath, errorRendered.finalHtml);
+                            outputs[routePath || "/"] = errorRendered.finalHtml;
+                            continue;
+                        }
+                        const fallbackHtml = renderStaticErrorDocument(normalizedError?.message ?? "Route data error");
+                        const routePath = routeIdToPath(entry.routeId, entry.params);
+                        const htmlPath = routePath
+                            ? join(outDir, routePath, "index.html")
+                            : join(outDir, "index.html");
+                        await writeFileSafe(htmlPath, fallbackHtml);
+                        outputs[routePath || "/"] = fallbackHtml;
+                        continue;
+                    }
+                    const depsHash = depsHashByEntry?.[entry.routeId] ?? "missing";
+                    const propsHash = computePropsHash(entry.props);
+                    const { assets } = resolveAssetsForRoute(entry.routeId);
+                    const templateHash = computeTemplateHash(documentTemplate, assets);
+                    const routeDataHash = computePropsHash(routeDataResult.data);
                     const renderKey = computeRenderKey({
                         routeId: entry.routeId,
                         paramsKey: entry.paramsKey,
                         templateHash,
                         depsHash,
                         propsHash,
+                        routeDataHash,
                     });
                     if (renderCacheEnabled) {
                         const cached = await readRenderCache(cacheRoot, {
@@ -780,6 +1483,7 @@ export const build = async (options) => {
                             templateHash,
                             depsHash,
                             propsHash,
+                            routeDataHash,
                         });
                         if (cached) {
                             const routePath = routeIdToPath(entry.routeId, entry.params);
@@ -798,6 +1502,7 @@ export const build = async (options) => {
                         nestedLayouts: config.routing.nestedLayouts,
                         routeGraph,
                         rootDir,
+                        appModule: specialRouteFiles?.app,
                         routeRender: (props) => pageModule.default(props),
                         routeHead: pageModule.head
                             ? (props) => pageModule.head(props)
@@ -809,7 +1514,12 @@ export const build = async (options) => {
                     const rendered = await renderHtml({
                         renderToHtml: (ctx) => routeAdapter.renderToHtml(ctx),
                         serializeProps: routeAdapter.serializeProps ?? serializeProps,
-                    }, { routeId: entry.routeId, params: entry.params, props: entry.props }, defaultHtmlTemplate, assets);
+                    }, {
+                        routeId: entry.routeId,
+                        params: entry.params,
+                        props: entry.props,
+                        routeData: routeDataResult.data,
+                    }, documentTemplate, assets);
                     const routePath = routeIdToPath(entry.routeId, entry.params);
                     const htmlPath = routePath
                         ? join(outDir, routePath, "index.html")
@@ -823,22 +1533,124 @@ export const build = async (options) => {
                             renderKey,
                             templateHash: rendered.templateHash,
                             propsHash,
+                            routeDataHash,
                             depsHash,
                             generatedAt: Date.now(),
                             head: rendered.head,
                             propsPayload: rendered.propsPayload,
+                            routeDataPayload: rendered.routeDataPayload,
                             status: rendered.status,
                             headers: rendered.headers,
                             finalHtml: rendered.finalHtml,
                         });
                     }
                 }
+                if (notFoundRecord && notFoundPageModule) {
+                    const notFoundData = await collectRouteDataForRoute({
+                        routeId: notFoundRecord.id,
+                        routesDir,
+                        layoutFiles: notFoundRecord.layoutFiles,
+                        pageModule: notFoundPageModule,
+                        initServerHook: initServer,
+                        loadLayoutModule,
+                    });
+                    const notFoundAdapter = resolveUIAdapter(config.ui.adapter, {
+                        ...config.ui.options,
+                        navigationMode: resolvedNavigationMode,
+                        clientRenderMode: config.routing.clientRender,
+                        nestedLayouts: config.routing.nestedLayouts,
+                        routeGraph,
+                        rootDir,
+                        appModule: specialRouteFiles?.app,
+                        routeRender: (props) => notFoundPageModule.default(props),
+                        routeHead: notFoundPageModule.head
+                            ? (props) => notFoundPageModule.head(props)
+                            : undefined,
+                    }, adapterRegistry);
+                    const { assets } = resolveAssetsForRoute(notFoundRecord.id);
+                    const rendered = await renderHtml({
+                        renderToHtml: (ctx) => notFoundAdapter.renderToHtml(ctx),
+                        serializeProps: notFoundAdapter.serializeProps ?? serializeProps,
+                    }, {
+                        routeId: notFoundRecord.id,
+                        props: {},
+                        routeData: notFoundData.data,
+                    }, documentTemplate, assets);
+                    await writeFileSafe(join(outDir, "404.html"), rendered.finalHtml);
+                    outputs["/404"] = rendered.finalHtml;
+                }
                 return outputs;
             },
             emitManifest: async (_ctx, state) => {
                 const routeGraph = state.routeGraph;
                 const clientBundle = state.clientBundle;
                 const serverBundle = state.serverBundle;
+                const collectBundlerPlugins = async (input) => {
+                    if (!hyperPlugins.length) {
+                        return [];
+                    }
+                    const plugins = [];
+                    await runBeforeBundleHooks(hyperPlugins, {
+                        phase: "build",
+                        entryId: input.entryId,
+                        entryPath: input.entryPath,
+                        target: input.target,
+                        format: input.format,
+                        syntaxTarget: input.syntaxTarget,
+                        bundler: input.syntaxTarget === "es5" ? "esbuild" : "bun",
+                        bundleType: input.bundleType,
+                        bundlerPlugins: plugins,
+                        addBundlerPlugin: (plugin) => {
+                            plugins.push(plugin);
+                        },
+                    });
+                    return plugins;
+                };
+                const special = {};
+                if (specialRouteRecords.notFound) {
+                    const clientEntry = clientBundle.entryChunks[specialRouteRecords.notFound.id];
+                    if (!clientEntry) {
+                        throw new Error("Missing client entry for special notFound route.");
+                    }
+                    special.notFound = {
+                        clientEntry,
+                        serverEntry: serverBundle?.entryChunks[specialRouteRecords.notFound.id],
+                        html: "404.html",
+                    };
+                }
+                if (specialRouteRecords.error) {
+                    const clientEntry = clientBundle.entryChunks[specialRouteRecords.error.id];
+                    if (!clientEntry) {
+                        throw new Error("Missing client entry for special error route.");
+                    }
+                    special.error = {
+                        clientEntry,
+                        serverEntry: serverBundle?.entryChunks[specialRouteRecords.error.id],
+                    };
+                }
+                const routeStyles = {};
+                for (const route of routeGraph.routes) {
+                    if (!routeHasStyles[route.id]) {
+                        continue;
+                    }
+                    const styleFile = resolveBundleStyleFile(clientBundle, route.id);
+                    if (styleFile) {
+                        routeStyles[route.id] = [styleFile];
+                    }
+                }
+                const specialStyles = {};
+                if (specialRouteRecords.notFound && routeHasStyles[specialRouteRecords.notFound.id]) {
+                    const styleFile = resolveBundleStyleFile(clientBundle, specialRouteRecords.notFound.id);
+                    if (styleFile) {
+                        specialStyles.notFound = [styleFile];
+                    }
+                }
+                if (specialRouteRecords.error && routeHasStyles[specialRouteRecords.error.id]) {
+                    const styleFile = resolveBundleStyleFile(clientBundle, specialRouteRecords.error.id);
+                    if (styleFile) {
+                        specialStyles.error = [styleFile];
+                    }
+                }
                 const manifest = generateManifest({
                     version: buildVersion,
                     basePath: config.basePath,
@@ -849,6 +1661,9 @@ export const build = async (options) => {
                         assetsDir,
                         scriptType: clientScriptType,
                     },
+                    routeStyles: Object.keys(routeStyles).length > 0 ? routeStyles : undefined,
+                    specialStyles: Object.keys(specialStyles).length > 0 ? specialStyles : undefined,
+                    special: Object.keys(special).length > 0 ? special : undefined,
                 });
                 await mkdir(join(outDir, assetsDir), { recursive: true });
                 for (const route of routeGraph.routes) {
@@ -861,13 +1676,84 @@ export const build = async (options) => {
                     if (!clientChunk || !clientEntryPath) {
                         throw new Error(`Missing client runtime metadata for route ${route.id}`);
                     }
+                    const styleFile = routeHasStyles[route.id]
+                        ? resolveBundleStyleFile(clientBundle, route.id)
+                        : null;
+                    const cssOutputPath = styleFile ? join(outDir, assetsDir, styleFile) : undefined;
+                    const bundlerPlugins = await collectBundlerPlugins({
+                        entryId: route.id,
+                        entryPath: clientEntryPath,
+                        target: "browser",
+                        format: clientScriptType === "classic" ? "iife" : "esm",
+                        syntaxTarget: isEs5Target ? "es5" : "modern",
+                        bundleType: "client",
+                    });
                     await buildChunkFile(clientEntryPath, join(outDir, assetsDir, clientChunk.file), {
                         target: "browser",
                         format: clientScriptType === "classic" ? "iife" : "esm",
                         shimHyperCore: true,
                         syntaxTarget: isEs5Target ? "es5" : "modern",
+                        plugins: bundlerPlugins,
+                        emitCss: Boolean(cssOutputPath),
+                        cssOutputPath,
                     });
                 }
+                if (specialRouteRecords.notFound) {
+                    const clientEntryKey = clientBundle.entryChunks[specialRouteRecords.notFound.id];
+                    const clientChunk = clientEntryKey ? clientBundle.chunks[clientEntryKey] : null;
+                    const clientEntryPath = clientRuntimeEntries.get(specialRouteRecords.notFound.id);
+                    if (clientChunk && clientEntryPath) {
+                        const styleFile = routeHasStyles[specialRouteRecords.notFound.id]
+                            ? resolveBundleStyleFile(clientBundle, specialRouteRecords.notFound.id)
+                            : null;
+                        const cssOutputPath = styleFile ? join(outDir, assetsDir, styleFile) : undefined;
+                        const bundlerPlugins = await collectBundlerPlugins({
+                            entryId: specialRouteRecords.notFound.id,
+                            entryPath: clientEntryPath,
+                            target: "browser",
+                            format: clientScriptType === "classic" ? "iife" : "esm",
+                            syntaxTarget: isEs5Target ? "es5" : "modern",
+                            bundleType: "client",
+                        });
+                        await buildChunkFile(clientEntryPath, join(outDir, assetsDir, clientChunk.file), {
+                            target: "browser",
+                            format: clientScriptType === "classic" ? "iife" : "esm",
+                            shimHyperCore: true,
+                            syntaxTarget: isEs5Target ? "es5" : "modern",
+                            plugins: bundlerPlugins,
+                            emitCss: Boolean(cssOutputPath),
+                            cssOutputPath,
+                        });
+                    }
+                }
+                if (specialRouteRecords.error) {
+                    const clientEntryKey = clientBundle.entryChunks[specialRouteRecords.error.id];
+                    const clientChunk = clientEntryKey ? clientBundle.chunks[clientEntryKey] : null;
+                    const clientEntryPath = clientRuntimeEntries.get(specialRouteRecords.error.id);
+                    if (clientChunk && clientEntryPath) {
+                        const styleFile = routeHasStyles[specialRouteRecords.error.id]
+                            ? resolveBundleStyleFile(clientBundle, specialRouteRecords.error.id)
+                            : null;
+                        const cssOutputPath = styleFile ? join(outDir, assetsDir, styleFile) : undefined;
+                        const bundlerPlugins = await collectBundlerPlugins({
+                            entryId: specialRouteRecords.error.id,
+                            entryPath: clientEntryPath,
+                            target: "browser",
+                            format: clientScriptType === "classic" ? "iife" : "esm",
+                            syntaxTarget: isEs5Target ? "es5" : "modern",
+                            bundleType: "client",
+                        });
+                        await buildChunkFile(clientEntryPath, join(outDir, assetsDir, clientChunk.file), {
+                            target: "browser",
+                            format: clientScriptType === "classic" ? "iife" : "esm",
+                            shimHyperCore: true,
+                            syntaxTarget: isEs5Target ? "es5" : "modern",
+                            plugins: bundlerPlugins,
+                            emitCss: Boolean(cssOutputPath),
+                            cssOutputPath,
+                        });
+                    }
+                }
                 if (serverBundle) {
                     for (const route of routeGraph.routes) {
                         const serverEntryKey = serverBundle.entryChunks[route.id];
@@ -879,13 +1765,66 @@ export const build = async (options) => {
                         if (!serverChunk || !serverEntryPath) {
                             throw new Error(`Missing server runtime metadata for route ${route.id}`);
                         }
+                        const bundlerPlugins = await collectBundlerPlugins({
+                            entryId: route.id,
+                            entryPath: serverEntryPath,
+                            target: "node",
+                            format: "cjs",
+                            syntaxTarget: isEs5Target ? "es5" : "modern",
+                            bundleType: "server",
+                        });
                         await buildChunkFile(serverEntryPath, join(outDir, assetsDir, serverChunk.file), {
                             target: "node",
                             format: "cjs",
                             shimHyperCore: false,
                             syntaxTarget: isEs5Target ? "es5" : "modern",
+                            plugins: bundlerPlugins,
                         });
                     }
+                    if (specialRouteRecords.notFound) {
+                        const serverEntryKey = serverBundle.entryChunks[specialRouteRecords.notFound.id];
+                        const serverChunk = serverEntryKey ? serverBundle.chunks[serverEntryKey] : null;
+                        const serverEntryPath = serverRuntimeEntries.get(specialRouteRecords.notFound.id);
+                        if (serverChunk && serverEntryPath) {
+                            const bundlerPlugins = await collectBundlerPlugins({
+                                entryId: specialRouteRecords.notFound.id,
+                                entryPath: serverEntryPath,
+                                target: "node",
+                                format: "cjs",
+                                syntaxTarget: isEs5Target ? "es5" : "modern",
+                                bundleType: "server",
+                            });
+                            await buildChunkFile(serverEntryPath, join(outDir, assetsDir, serverChunk.file), {
+                                target: "node",
+                                format: "cjs",
+                                shimHyperCore: false,
+                                syntaxTarget: isEs5Target ? "es5" : "modern",
+                                plugins: bundlerPlugins,
+                            });
+                        }
+                    }
+                    if (specialRouteRecords.error) {
+                        const serverEntryKey = serverBundle.entryChunks[specialRouteRecords.error.id];
+                        const serverChunk = serverEntryKey ? serverBundle.chunks[serverEntryKey] : null;
+                        const serverEntryPath = serverRuntimeEntries.get(specialRouteRecords.error.id);
+                        if (serverChunk && serverEntryPath) {
+                            const bundlerPlugins = await collectBundlerPlugins({
+                                entryId: specialRouteRecords.error.id,
+                                entryPath: serverEntryPath,
+                                target: "node",
+                                format: "cjs",
+                                syntaxTarget: isEs5Target ? "es5" : "modern",
+                                bundleType: "server",
+                            });
+                            await buildChunkFile(serverEntryPath, join(outDir, assetsDir, serverChunk.file), {
+                                target: "node",
+                                format: "cjs",
+                                shimHyperCore: false,
+                                syntaxTarget: isEs5Target ? "es5" : "modern",
+                                plugins: bundlerPlugins,
+                            });
+                        }
+                    }
                 }
                 await writeFileSafe(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
                 if (legacyEnabled && legacyBundle) {