@catmint/vite 0.0.0-prealpha.1

package/dist/dev-server.js

@@ -0,0 +1,1683 @@
+// @catmint/vite/dev-server — RSC dev server middleware
+//
+// Vite plugin that intercepts page route requests during development,
+// renders them via the RSC → SSR → HTML three-phase pipeline, and
+// injects the RSC payload into the HTML for client hydration.
+//
+// The rendering pipeline:
+// 1. RSC phase:  Load page+layouts in RSC environment, call
+//                renderToReadableStream → flight stream
+// 2. SSR phase:  Tee the flight stream. One fork → createFromReadableStream
+//                → React VDOM → renderToReadableStream → HTML. Other fork
+//                → injectRSCPayload → embedded in HTML as <script> tags
+// 3. Client:     Browser reads embedded payload via rsc-html-stream/client,
+//                calls createFromReadableStream → React VDOM → hydrateRoot
+import { join, dirname, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { deterministicHash, toPosixPath, CLIENT_NAVIGATION_RUNTIME, } from "./utils.js";
+import { errorPageHtml } from "./error-page.js";
+import { scanStatusPages } from "./build-entries.js";
+import { buildPreflightHeaders } from "./cors-utils.js";
+import { resolveErrorBoundary, resolveLoadingComponent, } from "./resolve-utils.js";
+/**
+ * File extensions that indicate a static asset request (skip SSR).
+ */
+const ASSET_EXTENSIONS = new Set([
+    ".js",
+    ".ts",
+    ".tsx",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".css",
+    ".scss",
+    ".sass",
+    ".less",
+    ".json",
+    ".wasm",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".webp",
+    ".avif",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".otf",
+    ".mp4",
+    ".webm",
+    ".ogg",
+    ".mp3",
+    ".wav",
+    ".map",
+]);
+/**
+ * Paths that Vite handles internally — never intercept these.
+ * NOTE: /__catmint/fn/ is NOT included here because the dev server
+ * must handle server function RPC calls itself.
+ */
+const VITE_INTERNAL_PREFIXES = [
+    "/@vite/",
+    "/@fs/",
+    "/@id/",
+    "/__vite_",
+    "/node_modules/",
+    "/__vite_rsc",
+];
+/**
+ * Check if a URL should be skipped by the SSR middleware.
+ */
+function shouldSkip(url) {
+    const pathname = url.split("?")[0];
+    for (const prefix of VITE_INTERNAL_PREFIXES) {
+        if (pathname.startsWith(prefix))
+            return true;
+    }
+    const lastDot = pathname.lastIndexOf(".");
+    if (lastDot !== -1) {
+        const ext = pathname.slice(lastDot);
+        if (ASSET_EXTENSIONS.has(ext))
+            return true;
+    }
+    return false;
+}
+/**
+ * Walk up from a page file's directory to the app root, collecting
+ * layout.tsx files in order from outermost (root) to innermost.
+ */
+function collectLayouts(pageFilePath, appDir) {
+    const layouts = [];
+    let dir = dirname(pageFilePath);
+    while (dir.startsWith(appDir)) {
+        for (const name of ["layout.tsx", "layout.jsx", "layout.ts", "layout.js"]) {
+            const layoutPath = join(dir, name);
+            if (existsSync(layoutPath)) {
+                layouts.unshift(layoutPath);
+                break;
+            }
+        }
+        if (dir === appDir)
+            break;
+        dir = dirname(dir);
+    }
+    return layouts;
+}
+/**
+ * CSS file extensions that Vite processes.
+ */
+const CSS_EXTENSIONS = [".css", ".scss", ".sass", ".less", ".styl", ".stylus"];
+/**
+ * Check if a module URL represents a CSS file.
+ */
+function isCssModule(url) {
+    const clean = url.split("?")[0];
+    return CSS_EXTENSIONS.some((ext) => clean.endsWith(ext));
+}
+/**
+ * Collect all CSS modules imported (directly or transitively) by the given
+ * entry module IDs. Walks the Vite module graph breadth-first to find every
+ * CSS dependency, then returns their transformed source as `<style>` tags.
+ */
+async function collectCss(server, entryIds) {
+    const visited = new Set();
+    const cssModules = [];
+    const queue = [];
+    for (const id of entryIds) {
+        // Try the SSR module graph first (RSC env populates this), then client
+        const mod = server.moduleGraph.getModuleById(id);
+        if (mod)
+            queue.push(mod);
+        const urlMod = await server.moduleGraph.getModuleByUrl(id);
+        if (urlMod && urlMod !== mod)
+            queue.push(urlMod);
+    }
+    while (queue.length > 0) {
+        const mod = queue.shift();
+        const key = mod.id ?? mod.url;
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        if (isCssModule(mod.url)) {
+            cssModules.push(mod);
+        }
+        for (const imported of mod.importedModules) {
+            const importedKey = imported.id ?? imported.url;
+            if (!visited.has(importedKey)) {
+                queue.push(imported);
+            }
+        }
+    }
+    if (cssModules.length === 0)
+        return "";
+    const styleTags = [];
+    for (const mod of cssModules) {
+        try {
+            const result = await server.transformRequest(mod.url);
+            if (result?.code) {
+                const directResult = await server.transformRequest(mod.url + (mod.url.includes("?") ? "&direct" : "?direct"));
+                if (directResult?.code) {
+                    styleTags.push(`<style data-vite-dev-id="${mod.url}">${directResult.code}</style>`);
+                    continue;
+                }
+                const cssMatch = result.code.match(/const __vite__css\s*=\s*"((?:[^"\\]|\\.)*)"/);
+                if (cssMatch) {
+                    const css = cssMatch[1]
+                        .replace(/\\n/g, "\n")
+                        .replace(/\\"/g, '"')
+                        .replace(/\\\\/g, "\\");
+                    styleTags.push(`<style data-vite-dev-id="${mod.url}">${css}</style>`);
+                }
+            }
+        }
+        catch {
+            // Skip — client will load via normal pipeline
+        }
+    }
+    return styleTags.join("\n");
+}
+/**
+ * Read the full request body as a buffer.
+ */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/** Escape a string for safe insertion into an HTML attribute. */
+function escapeHtmlAttr(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Merge multiple HeadConfig objects (last wins for title and meta keys).
+ * Mirrors mergeHeadConfigs from catmint/head/HeadContext.
+ */
+function mergeHeadConfigs(configs) {
+    const merged = {};
+    const metaMap = new Map();
+    const links = [];
+    for (const config of configs) {
+        if (config.title !== undefined)
+            merged.title = config.title;
+        if (config.meta) {
+            for (const meta of config.meta) {
+                const key = meta.name
+                    ? `name:${meta.name}`
+                    : meta.property
+                        ? `property:${meta.property}`
+                        : `content:${meta.content}`;
+                metaMap.set(key, meta);
+            }
+        }
+        if (config.link)
+            links.push(...config.link);
+    }
+    if (metaMap.size > 0)
+        merged.meta = Array.from(metaMap.values());
+    if (links.length > 0)
+        merged.link = links;
+    return merged;
+}
+/**
+ * Serialize a HeadConfig into HTML tags for injection into `<head>`.
+ */
+function renderHeadToString(config) {
+    const parts = [];
+    if (config.title !== undefined) {
+        parts.push(`<title>${escapeHtmlAttr(config.title)}</title>`);
+    }
+    if (config.meta) {
+        for (const meta of config.meta) {
+            const attrs = [];
+            if (meta.name)
+                attrs.push(`name="${escapeHtmlAttr(meta.name)}"`);
+            if (meta.property)
+                attrs.push(`property="${escapeHtmlAttr(meta.property)}"`);
+            attrs.push(`content="${escapeHtmlAttr(meta.content)}"`);
+            parts.push(`<meta ${attrs.join(" ")}>`);
+        }
+    }
+    if (config.link) {
+        for (const linkDef of config.link) {
+            const attrs = [
+                `rel="${escapeHtmlAttr(linkDef.rel)}"`,
+                `href="${escapeHtmlAttr(linkDef.href)}"`,
+            ];
+            for (const [key, value] of Object.entries(linkDef)) {
+                if (key !== "rel" && key !== "href") {
+                    attrs.push(`${key}="${escapeHtmlAttr(value)}"`);
+                }
+            }
+            parts.push(`<link ${attrs.join(" ")}>`);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Strip existing `<title>` and duplicate `<meta>` tags from SSR-rendered HTML
+ * so the framework-injected head tags from `generateMetadata` take precedence.
+ *
+ * Without this, the layout's `<title>` in JSX and the `generateMetadata` title
+ * both appear in `<head>`, and the browser uses the first one — ignoring the
+ * page-specific title.
+ */
+function stripExistingHeadTags(html, config) {
+    let result = html;
+    // Strip existing <title>...</title> when generateMetadata provides one
+    if (config.title !== undefined) {
+        result = result.replace(/<title>[^<]*<\/title>/i, "");
+    }
+    // Strip existing <meta> tags that will be replaced by generateMetadata
+    if (config.meta) {
+        for (const meta of config.meta) {
+            if (meta.name) {
+                const re = new RegExp(`<meta\\s+[^>]*name=["']${escapeRegExp(meta.name)}["'][^>]*>`, "i");
+                result = result.replace(re, "");
+            }
+            else if (meta.property) {
+                const re = new RegExp(`<meta\\s+[^>]*property=["']${escapeRegExp(meta.property)}["'][^>]*>`, "i");
+                result = result.replace(re, "");
+            }
+        }
+    }
+    return result;
+}
+/** Escape special regex characters in a string. */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Resolve generateMetadata exports from page and layout modules.
+ *
+ * Calls `generateMetadata({ params, search })` on each module that exports it,
+ * then merges the results (layout configs first, page config last — page wins).
+ *
+ * @returns Merged HeadConfig, or undefined if no modules export generateMetadata.
+ */
+async function resolveGenerateMetadata(pageMod, layoutMods, params, url) {
+    const urlObj = new URL(url, "http://localhost");
+    const search = {};
+    for (const [key, value] of urlObj.searchParams.entries()) {
+        search[key] = value;
+    }
+    const metadataArgs = { params: params ?? {}, search };
+    const configs = [];
+    // Layouts first (outermost to innermost) — page is last so it wins on conflict
+    for (const layoutMod of layoutMods) {
+        if (typeof layoutMod.generateMetadata === "function") {
+            try {
+                const config = await layoutMod.generateMetadata(metadataArgs);
+                if (config && typeof config === "object")
+                    configs.push(config);
+            }
+            catch {
+                // Skip — layout generateMetadata failed
+            }
+        }
+    }
+    // Page module last
+    if (typeof pageMod.generateMetadata === "function") {
+        try {
+            const config = await pageMod.generateMetadata(metadataArgs);
+            if (config && typeof config === "object")
+                configs.push(config);
+        }
+        catch {
+            // Skip — page generateMetadata failed
+        }
+    }
+    if (configs.length === 0)
+        return undefined;
+    return mergeHeadConfigs(configs);
+}
+/**
+ * Server function RPC prefix.
+ */
+const SERVER_FN_PREFIX = "/__catmint/fn/";
+/**
+ * RSC flight stream prefix for client-side navigation.
+ */
+const RSC_NAVIGATION_PREFIX = "/__catmint/rsc";
+/**
+ * Handle a server function RPC call.
+ *
+ * The URL format is `/__catmint/fn/<basePath>/<hash>` where:
+ * - `basePath` is the relative file path without the `.fn.ts` extension
+ * - `hash` is `deterministicHash(relativePath + ":" + fnName)`
+ *
+ * We resolve the `.fn.ts` file, load it via Vite's SSR module loader,
+ * iterate its exports to find the one matching the hash, and call it.
+ */
+async function handleServerFn(server, req, res, pathname) {
+    const root = server.config.root;
+    // Parse the URL: /__catmint/fn/<basePath>/<hash>
+    const fnPath = pathname.slice(SERVER_FN_PREFIX.length); // e.g. "app/examples/server-fn/actions/c875b945"
+    const lastSlash = fnPath.lastIndexOf("/");
+    if (lastSlash === -1) {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "Invalid server function path" }));
+        return;
+    }
+    const basePath = fnPath.slice(0, lastSlash); // e.g. "app/examples/server-fn/actions"
+    const hash = fnPath.slice(lastSlash + 1); // e.g. "c875b945"
+    // Try to find the .fn.ts file — try common extensions
+    const extensions = [".fn.ts", ".fn.tsx"];
+    let resolvedFilePath = null;
+    for (const ext of extensions) {
+        const candidate = join(root, basePath + ext);
+        if (existsSync(candidate)) {
+            resolvedFilePath = candidate;
+            break;
+        }
+    }
+    if (!resolvedFilePath) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({
+            error: `Server function module not found: ${basePath}.fn.ts`,
+        }));
+        return;
+    }
+    // Load the module via Vite's SSR module loader (server-side, no RPC transform)
+    let mod;
+    try {
+        mod = await server.ssrLoadModule(resolvedFilePath);
+    }
+    catch (err) {
+        server.config.logger.error(`[catmint] Failed to load server function module ${resolvedFilePath}: ${err instanceof Error ? err.message : String(err)}`);
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "Failed to load server function module" }));
+        return;
+    }
+    // Find the export whose hash matches
+    const relativePath = toPosixPath(resolvedFilePath.startsWith(root)
+        ? resolvedFilePath.slice(root.length + 1)
+        : resolvedFilePath);
+    let matchedFn = null;
+    for (const [exportName, exportValue] of Object.entries(mod)) {
+        if (exportName === "__esModule")
+            continue;
+        const candidateHash = deterministicHash(`${relativePath}:${exportName}`);
+        if (candidateHash === hash) {
+            if (typeof exportValue === "function") {
+                matchedFn = exportValue;
+            }
+            break;
+        }
+    }
+    if (!matchedFn) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({
+            error: `Server function with hash "${hash}" not found in ${relativePath}`,
+        }));
+        return;
+    }
+    // Read request body
+    const body = await readBody(req);
+    let input;
+    try {
+        input = body.length > 0 ? JSON.parse(body.toString("utf-8")) : undefined;
+    }
+    catch {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "Invalid JSON body" }));
+        return;
+    }
+    // Call the server function
+    try {
+        const result = await matchedFn(input);
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(result));
+    }
+    catch (err) {
+        server.config.logger.error(`[catmint] Server function error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({
+            error: err instanceof Error ? err.message : "Server function error",
+        }));
+    }
+}
+/**
+ * Handle an API endpoint request.
+ */
+async function handleEndpoint(server, req, res, match, method) {
+    const mod = await server.ssrLoadModule(match.route.filePath);
+    let handler;
+    if (mod[method]) {
+        handler = mod[method];
+    }
+    else if (mod.ANY) {
+        handler = mod.ANY;
+    }
+    else if (mod.default) {
+        handler = mod.default;
+    }
+    if (!handler) {
+        res.statusCode = 405;
+        res.setHeader("Content-Type", "text/plain");
+        res.end(`Method ${method} not allowed`);
+        return;
+    }
+    const protocol = "http";
+    const host = req.headers.host ?? "localhost";
+    const reqUrl = req.originalUrl ?? req.url ?? "/";
+    const fullUrl = `${protocol}://${host}${reqUrl}`;
+    const requestInit = {
+        method,
+        headers: Object.entries(req.headers).reduce((acc, [key, val]) => {
+            if (val)
+                acc[key] = Array.isArray(val) ? val.join(", ") : val;
+            return acc;
+        }, {}),
+    };
+    if (method !== "GET" && method !== "HEAD") {
+        const buf = await readBody(req);
+        requestInit.body = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    const webRequest = new Request(fullUrl, requestInit);
+    const ctx = { params: match.params };
+    const response = await handler(webRequest, ctx);
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+        res.setHeader(key, value);
+    });
+    if (response.body) {
+        const reader = response.body.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                res.write(value);
+            }
+        }
+        finally {
+            res.end();
+        }
+    }
+    else {
+        res.end();
+    }
+}
+// --------------------------------------------------------------------------
+// Virtual module IDs for RSC/SSR rendering entries
+// --------------------------------------------------------------------------
+/** Virtual module loaded in the RSC environment to render pages */
+const RSC_RENDERER_ID = "virtual:catmint/rsc-renderer";
+const RESOLVED_RSC_RENDERER_ID = "\0" + RSC_RENDERER_ID;
+/** Virtual module loaded in the SSR environment to convert RSC→HTML */
+const SSR_RENDERER_ID = "virtual:catmint/ssr-renderer";
+const RESOLVED_SSR_RENDERER_ID = "\0" + SSR_RENDERER_ID;
+/** Virtual module for browser hydration entry */
+const CLIENT_HYDRATE_ID = "virtual:catmint/client-hydrate";
+const RESOLVED_CLIENT_HYDRATE_ID = "\0" + CLIENT_HYDRATE_ID;
+/**
+ * Create the SSR dev server Vite plugin.
+ *
+ * With RSC enabled, this plugin implements a three-phase rendering pipeline:
+ * 1. RSC: renders page components in the RSC environment → flight stream
+ * 2. SSR: converts flight stream to HTML via react-dom SSR
+ * 3. Client: hydrates from embedded RSC payload
+ *
+ * The RSC and SSR rendering code runs inside Vite's environment runners
+ * (server.environments.rsc.runner and server.environments.ssr) so that the
+ * correct resolve conditions and module transforms apply.
+ */
+export function devServerPlugin(options) {
+    const softNav = options?.softNavigation ?? true;
+    const i18nConfig = options?.i18n ?? null;
+    let server;
+    let appDir;
+    let pageMatcher = null;
+    let endpointMatcher = null;
+    // Pre-scanned status pages sorted by most-specific (longest prefix) first.
+    // Populated in configureServer, rebuilt on HMR when status page files change.
+    let statusPages = [];
+    /**
+     * Find the best-matching status page file for the given status code and URL.
+     * Uses prefix matching (same logic as the production RSC entry) against the
+     * pre-scanned status page list. No filesystem calls per request.
+     */
+    function findStatusPage(statusCode, url) {
+        const pathname = url.split("?")[0].split("#")[0];
+        for (const sp of statusPages) {
+            if (sp.statusCode !== statusCode)
+                continue;
+            if (sp.urlPrefix === "/" ||
+                pathname === sp.urlPrefix ||
+                pathname.startsWith(sp.urlPrefix + "/")) {
+                return sp.filePath;
+            }
+        }
+        return null;
+    }
+    /**
+     * Lazily initialize route matchers.
+     */
+    async function ensureMatchers() {
+        if (pageMatcher && endpointMatcher)
+            return;
+        const routingMod = await server.ssrLoadModule("catmint/routing");
+        const routes = await routingMod.scanRoutes(appDir);
+        const pageRoutes = routes.filter((r) => r.type === "page");
+        pageMatcher = routingMod.createRouteMatcher(pageRoutes);
+        const epRoutes = routes.filter((r) => r.type === "endpoint");
+        endpointMatcher = routingMod.createRouteMatcher(epRoutes);
+    }
+    /**
+     * Check if an error is a StatusError (duck-typing to avoid cross-env
+     * instanceof issues — the error may come from the RSC environment).
+     */
+    function isStatusError(error) {
+        return (error instanceof Error &&
+            error.name === "StatusError" &&
+            typeof error.statusCode === "number");
+    }
+    /**
+     * Try to render a user-defined status page (e.g. 404.tsx) through the
+     * full RSC → SSR → HTML pipeline. Returns the rendered HTML string if
+     * a user status page was found, or null to signal fallback to the
+     * built-in error page.
+     *
+     * @param statusCode - HTTP status code (e.g. 404, 500)
+     * @param url - The request URL (for prefix matching and AppProviders pathname)
+     * @param statusData - Optional data payload to pass as props to the status page
+     */
+    async function tryRenderStatusPage(statusCode, url, statusData) {
+        try {
+            const statusPagePath = findStatusPage(statusCode, url);
+            if (!statusPagePath)
+                return null;
+            // Only render through RSC pipeline if environments are available
+            if (!hasRscEnvironments())
+                return null;
+            const root = server.config.root;
+            const rscEnv = server.environments.rsc;
+            const ssrEnv = server.environments.ssr;
+            if (!rscEnv?.runner || !ssrEnv?.runner)
+                return null;
+            // Import rendering utilities
+            const rscMod = await rscEnv.runner.import("@vitejs/plugin-rsc/rsc");
+            const { renderToReadableStream: rscRender } = rscMod;
+            // Import the status page component in RSC environment
+            const statusPageImportPath = "/" + relative(root, statusPagePath);
+            const statusPageMod = await rscEnv.runner.import(statusPageImportPath);
+            const StatusPageComponent = statusPageMod.default;
+            if (!StatusPageComponent)
+                return null;
+            // Collect layouts for the status page (same ancestor layout chain)
+            const layoutPaths = collectLayouts(statusPagePath, appDir);
+            const layoutImportPaths = layoutPaths.map((lp) => "/" + relative(root, lp));
+            const layoutComponents = [];
+            const layoutMods = [];
+            for (const lp of layoutImportPaths) {
+                const layoutMod = await rscEnv.runner.import(lp);
+                layoutMods.push(layoutMod);
+                if (layoutMod.default) {
+                    layoutComponents.push(layoutMod.default);
+                }
+            }
+            // Resolve generateMetadata exports from status page + layout modules
+            const headConfig = await resolveGenerateMetadata(statusPageMod, layoutMods, {}, url);
+            // Get React from the RSC environment
+            const reactMod = await rscEnv.runner.import("react");
+            const createElement = reactMod.createElement ?? reactMod.default?.createElement;
+            if (!createElement)
+                return null;
+            // Build component tree with status + message props
+            const statusProps = {
+                status: statusCode,
+                ...statusData,
+            };
+            let element = createElement(StatusPageComponent, statusProps);
+            // Wrap with layouts (outermost first)
+            for (let i = layoutComponents.length - 1; i >= 0; i--) {
+                element = createElement(layoutComponents[i], null, element);
+            }
+            // Wrap with AppProviders
+            const appProvidersMod = await rscEnv.runner.import("catmint/runtime/app-providers");
+            const AppProviders = appProvidersMod.AppProviders ?? appProvidersMod.default?.AppProviders;
+            if (AppProviders) {
+                const urlObj = new URL(url, "http://localhost");
+                const providerProps = {
+                    pathname: urlObj.pathname,
+                    params: {},
+                };
+                if (i18nConfig) {
+                    providerProps.i18nConfig = i18nConfig;
+                }
+                if (headConfig) {
+                    providerProps.headConfig = headConfig;
+                }
+                element = createElement(AppProviders, providerProps, element);
+            }
+            // RSC render → flight stream
+            const rscStream = rscRender(element);
+            // Tee: one for SSR, one for browser injection
+            const [rscForSsr, rscForBrowser] = rscStream.tee();
+            // SSR: flight stream → HTML
+            const ssrMod = await ssrEnv.runner.import("@vitejs/plugin-rsc/ssr");
+            const { createFromReadableStream: ssrCreate } = ssrMod;
+            const reactDomServer = await ssrEnv.runner.import("react-dom/server");
+            const { renderToReadableStream: htmlRender } = reactDomServer;
+            const ssrRoot = ssrCreate(rscForSsr);
+            const bootstrapScriptContent = `import("/@id/__x00__virtual:catmint/client-hydrate")`;
+            const htmlStream = await htmlRender(ssrRoot, {
+                bootstrapScriptContent,
+            });
+            // Inject RSC payload into HTML
+            const rscHtmlStream = await ssrEnv.runner.import("rsc-html-stream/server");
+            const { injectRSCPayload } = rscHtmlStream;
+            const injectionTransform = injectRSCPayload(rscForBrowser);
+            const finalStream = htmlStream.pipeThrough(injectionTransform);
+            // Collect CSS from the status page + layouts
+            const cssEntryIds = [statusPagePath, ...layoutPaths];
+            const cssStyles = await collectCss(server, cssEntryIds);
+            const headParts = [
+                `<script>window.__catmintSoftNav=false</script>`,
+                '<script type="module" src="/@vite/client"></script>',
+                cssStyles,
+            ];
+            if (headConfig) {
+                headParts.unshift(renderHeadToString(headConfig));
+            }
+            const headInjection = headParts.join("\n");
+            // Read the stream into a string, injecting head content
+            const reader = finalStream.getReader();
+            const decoder = new TextDecoder();
+            let injected = false;
+            let buffer = "";
+            let result = "";
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                const chunk = decoder.decode(value, {
+                    stream: true,
+                });
+                if (injected) {
+                    result += chunk;
+                    continue;
+                }
+                buffer += chunk;
+                const headCloseIdx = buffer.indexOf("</head>");
+                if (headCloseIdx !== -1) {
+                    injected = true;
+                    let before = buffer.slice(0, headCloseIdx);
+                    const after = buffer.slice(headCloseIdx);
+                    if (headConfig) {
+                        before = stripExistingHeadTags(before, headConfig);
+                    }
+                    result += before + headInjection + after;
+                    buffer = "";
+                }
+            }
+            if (!injected && buffer) {
+                result += buffer + headInjection;
+            }
+            else if (buffer) {
+                result += buffer;
+            }
+            return result;
+        }
+        catch (err) {
+            // If rendering the status page itself fails, log and fall back
+            server.config.logger.error(`[catmint] Failed to render status page for ${statusCode}: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Send an error response for a page request. Tries to render a user-defined
+     * status page first, falling back to the built-in error page HTML.
+     *
+     * @param res - The HTTP response
+     * @param statusCode - HTTP status code
+     * @param url - The request URL (for prefix matching and AppProviders pathname)
+     * @param options - Options for the built-in fallback (e.g. detail for dev errors)
+     * @param statusData - Optional data to pass as props to user status page
+     */
+    async function sendStatusPage(res, statusCode, url, options, statusData) {
+        const html = await tryRenderStatusPage(statusCode, url, statusData);
+        res.statusCode = statusCode;
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(html ?? errorPageHtml(statusCode, options));
+    }
+    /**
+     * Check if RSC environments are available (plugin-rsc is active).
+     */
+    function hasRscEnvironments() {
+        return !!(server.environments &&
+            server.environments.rsc &&
+            server.environments.ssr);
+    }
+    // Hydration virtual module support (fallback for non-RSC mode)
+    const hydrationScripts = new Map();
+    let hydrationCounter = 0;
+    const HYDRATE_VIRTUAL_PREFIX = "/@catmint/hydrate/";
+    // Resolve RSC-related packages from @catmint/vite's own node_modules.
+    // This is necessary because pnpm's strict isolation means these packages
+    // aren't accessible from the user's project root.
+    const catmintViteRequire = createRequire(import.meta.url);
+    /** Resolve a package specifier to its absolute file path, or null if not found. */
+    function resolveFromCatmintVite(specifier) {
+        try {
+            return catmintViteRequire.resolve(specifier);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Build resolve.alias entries so that all Vite environments can find
+     * @vitejs/plugin-rsc subpaths and rsc-html-stream subpaths regardless
+     * of pnpm's strict isolation.
+     */
+    function buildRscAliases() {
+        const aliases = [];
+        const rscMainPath = resolveFromCatmintVite("@vitejs/plugin-rsc");
+        if (rscMainPath) {
+            // Individual subpath aliases for the specific imports we need
+            const subpaths = [
+                "rsc",
+                "ssr",
+                "browser",
+                "react/rsc",
+                "react/ssr",
+                "react/browser",
+                "vendor/react-server-dom/server.edge",
+                "vendor/react-server-dom/client.edge",
+                "vendor/react-server-dom/client.browser",
+                "vendor/react-server-dom/server",
+                "vendor/react-server-dom/client",
+                "utils/encryption-runtime",
+            ];
+            for (const sub of subpaths) {
+                const resolved = resolveFromCatmintVite(`@vitejs/plugin-rsc/${sub}`);
+                if (resolved) {
+                    aliases.push({
+                        find: `@vitejs/plugin-rsc/${sub}`,
+                        replacement: resolved,
+                    });
+                }
+            }
+            // Also alias the main package
+            aliases.push({
+                find: "@vitejs/plugin-rsc",
+                replacement: rscMainPath,
+            });
+        }
+        // Map rsc-html-stream subpaths
+        for (const sub of ["server", "client"]) {
+            const resolved = resolveFromCatmintVite(`rsc-html-stream/${sub}`);
+            if (resolved) {
+                aliases.push({
+                    find: `rsc-html-stream/${sub}`,
+                    replacement: resolved,
+                });
+            }
+        }
+        return aliases;
+    }
+    return {
+        name: "catmint:dev-server",
+        enforce: "post",
+        config() {
+            const aliases = buildRscAliases();
+            return {
+                resolve: {
+                    alias: aliases,
+                },
+                ssr: {
+                    external: ["catmint/routing", "catmint/status"],
+                },
+                optimizeDeps: {
+                    include: [
+                        "react",
+                        "react/jsx-runtime",
+                        "react/jsx-dev-runtime",
+                        "react-dom/client",
+                    ],
+                },
+            };
+        },
+        resolveId(id) {
+            if (id === RSC_RENDERER_ID || id === RESOLVED_RSC_RENDERER_ID) {
+                return RESOLVED_RSC_RENDERER_ID;
+            }
+            if (id === SSR_RENDERER_ID || id === RESOLVED_SSR_RENDERER_ID) {
+                return RESOLVED_SSR_RENDERER_ID;
+            }
+            if (id === CLIENT_HYDRATE_ID || id === RESOLVED_CLIENT_HYDRATE_ID) {
+                return RESOLVED_CLIENT_HYDRATE_ID;
+            }
+            // Legacy hydration support
+            if (id.startsWith(HYDRATE_VIRTUAL_PREFIX)) {
+                return id;
+            }
+            return null;
+        },
+        load(id) {
+            if (id === RESOLVED_RSC_RENDERER_ID) {
+                return generateRscRendererModule();
+            }
+            if (id === RESOLVED_SSR_RENDERER_ID) {
+                return generateSsrRendererModule();
+            }
+            if (id === RESOLVED_CLIENT_HYDRATE_ID) {
+                return generateClientHydrateModule();
+            }
+            // Legacy hydration support
+            if (id.startsWith(HYDRATE_VIRTUAL_PREFIX)) {
+                const key = id.slice(HYDRATE_VIRTUAL_PREFIX.length);
+                return hydrationScripts.get(key) ?? null;
+            }
+            return null;
+        },
+        configureServer(viteServer) {
+            server = viteServer;
+            appDir = join(server.config.root, "app");
+            statusPages = scanStatusPages(appDir);
+            return () => {
+                server.middlewares.use(async (req, res, next) => {
+                    const url = req.originalUrl ?? req.url ?? "/";
+                    // Legacy hydration module requests
+                    if (url.startsWith(HYDRATE_VIRTUAL_PREFIX)) {
+                        try {
+                            const result = await server.transformRequest(url);
+                            if (result) {
+                                res.setHeader("Content-Type", "application/javascript");
+                                res.statusCode = 200;
+                                res.end(result.code);
+                                return;
+                            }
+                        }
+                        catch (e) {
+                            server.config.logger.error(`[catmint] Failed to transform hydration module ${url}: ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                        res.statusCode = 404;
+                        res.setHeader("Content-Type", "text/html; charset=utf-8");
+                        res.end(errorPageHtml(404));
+                        return;
+                    }
+                    if (shouldSkip(url)) {
+                        return next();
+                    }
+                    // --- Server function RPC handling ---
+                    const pathname = url.split("?")[0];
+                    if (pathname.startsWith(SERVER_FN_PREFIX)) {
+                        try {
+                            await handleServerFn(server, req, res, pathname);
+                        }
+                        catch (error) {
+                            server.ssrFixStacktrace(error);
+                            server.config.logger.error(`[catmint] Server function error for ${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                            if (!res.headersSent) {
+                                res.statusCode = 500;
+                                res.setHeader("Content-Type", "application/json");
+                                res.end(JSON.stringify({ error: "Internal server function error" }));
+                            }
+                        }
+                        return;
+                    }
+                    // --- RSC flight stream for client-side navigation ---
+                    if (pathname === RSC_NAVIGATION_PREFIX) {
+                        try {
+                            const parsedUrl = new URL(url, "http://localhost");
+                            const targetPath = parsedUrl.searchParams.get("path");
+                            if (!targetPath) {
+                                res.statusCode = 400;
+                                res.setHeader("Content-Type", "application/json");
+                                res.end(JSON.stringify({ error: "Missing ?path= parameter" }));
+                                return;
+                            }
+                            await ensureMatchers();
+                            const match = pageMatcher.matchRoute(targetPath);
+                            if (!match) {
+                                res.statusCode = 404;
+                                res.setHeader("Content-Type", "application/json");
+                                res.end(JSON.stringify({ error: "No matching route" }));
+                                return;
+                            }
+                            if (!hasRscEnvironments()) {
+                                // Without RSC, fall back to a full page reload signal
+                                res.statusCode = 406;
+                                res.setHeader("Content-Type", "application/json");
+                                res.end(JSON.stringify({ error: "RSC not available" }));
+                                return;
+                            }
+                            await handleRscNavigation(server, req, res, match, appDir, i18nConfig);
+                        }
+                        catch (error) {
+                            server.ssrFixStacktrace(error);
+                            server.config.logger.error(`[catmint] RSC navigation error for ${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                            if (!res.headersSent) {
+                                res.statusCode = 500;
+                                res.setHeader("Content-Type", "application/json");
+                                res.end(JSON.stringify({ error: "RSC navigation error" }));
+                            }
+                        }
+                        return;
+                    }
+                    try {
+                        await ensureMatchers();
+                        // --- API endpoint handling ---
+                        const method = (req.method ?? "GET").toUpperCase();
+                        const endpointMatch = endpointMatcher.matchRoute(url);
+                        if (endpointMatch) {
+                            const epMethods = endpointMatch.route.methods ?? [];
+                            const hasHandler = epMethods.includes(method) ||
+                                epMethods.includes("ANY") ||
+                                epMethods.includes("default");
+                            // CORS auto-preflight: when OPTIONS is requested but no
+                            // OPTIONS handler is exported, generate a sensible preflight
+                            // response (PRD §26.3). Safe by default — no Allow-Origin.
+                            if (method === "OPTIONS" && !hasHandler) {
+                                const headers = buildPreflightHeaders(epMethods);
+                                res.statusCode = 204;
+                                res.setHeader("Allow", headers.allow);
+                                res.setHeader("Access-Control-Allow-Methods", headers.accessControlAllowMethods);
+                                res.setHeader("Access-Control-Allow-Headers", headers.accessControlAllowHeaders);
+                                res.setHeader("Access-Control-Max-Age", headers.accessControlMaxAge);
+                                res.end();
+                                return;
+                            }
+                            if (hasHandler) {
+                                return await handleEndpoint(server, req, res, endpointMatch, method);
+                            }
+                            res.statusCode = 405;
+                            res.setHeader("Content-Type", "text/plain");
+                            res.setHeader("Allow", epMethods.filter((m) => m !== "default").join(", ") || "GET");
+                            res.end(`Method ${method} not allowed`);
+                            return;
+                        }
+                        // --- Page handling (GET only) ---
+                        if (method !== "GET") {
+                            return next();
+                        }
+                        const match = pageMatcher.matchRoute(url);
+                        if (!match) {
+                            await sendStatusPage(res, 404, url);
+                            return;
+                        }
+                        // Check if RSC environments are available
+                        if (hasRscEnvironments()) {
+                            await handlePageWithRsc(server, req, res, match, appDir, softNav, i18nConfig, sendStatusPage);
+                        }
+                        else {
+                            await handlePageLegacy(server, req, res, match, appDir, hydrationScripts, hydrationCounter++, HYDRATE_VIRTUAL_PREFIX, i18nConfig);
+                        }
+                    }
+                    catch (error) {
+                        server.ssrFixStacktrace(error);
+                        if (isStatusError(error)) {
+                            // User code threw statusResponse() — render the corresponding status page
+                            server.config.logger.info(`[catmint] Status ${error.statusCode} for ${url}`);
+                            if (!res.headersSent) {
+                                await sendStatusPage(res, error.statusCode, url, undefined, error.data);
+                            }
+                        }
+                        else {
+                            // Unexpected error — render 500 page
+                            server.config.logger.error(`[catmint] SSR error for ${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                            if (!res.headersSent) {
+                                await sendStatusPage(res, 500, url, {
+                                    detail: error instanceof Error
+                                        ? (error.stack ?? error.message)
+                                        : String(error),
+                                });
+                            }
+                        }
+                    }
+                });
+            };
+        },
+        handleHotUpdate({ file, server: hmrServer }) {
+            if (file.includes("/app/") &&
+                (file.endsWith("page.tsx") ||
+                    file.endsWith("page.jsx") ||
+                    file.endsWith("page.mdx") ||
+                    file.endsWith("endpoint.ts") ||
+                    file.endsWith("endpoint.js"))) {
+                pageMatcher = null;
+                endpointMatcher = null;
+            }
+            // Status page files (e.g. 404.tsx, 500.tsx) — trigger full page reload.
+            // These are rendered on-demand during error handling and aren't part of
+            // the React component HMR tree, so a full reload ensures the updated
+            // status page is picked up on the next error.
+            if (file.includes("/app/")) {
+                const basename = file.split("/").pop() ?? "";
+                if (/^\d{3}\.(tsx|jsx|ts|js)$/.test(basename)) {
+                    statusPages = scanStatusPages(appDir);
+                    hmrServer.config.logger.info(`[catmint] Status page changed: ${basename} — triggering reload`);
+                    hmrServer.hot.send({ type: "full-reload", path: "*" });
+                    return [];
+                }
+            }
+        },
+    };
+}
+// --------------------------------------------------------------------------
+// RSC rendering pipeline (three-phase)
+// --------------------------------------------------------------------------
+/**
+ * Handle a page request using the RSC three-phase pipeline.
+ *
+ * Phase 1: RSC environment renders the page → flight stream
+ * Phase 2: SSR environment converts flight stream → HTML stream
+ * Phase 3: Inject RSC payload into HTML for client hydration
+ */
+async function handlePageWithRsc(server, req, res, match, appDir, softNavigation = true, i18nConfig = null, sendStatusPage) {
+    const url = req.originalUrl ?? req.url ?? "/";
+    const root = server.config.root;
+    // Collect layout chain for this page
+    const layoutPaths = collectLayouts(match.route.filePath, appDir);
+    // Convert paths to Vite-resolvable import paths (relative to root)
+    const pageImportPath = "/" + relative(root, match.route.filePath);
+    const layoutImportPaths = layoutPaths.map((lp) => "/" + relative(root, lp));
+    // Collect CSS from the module graph
+    const cssEntryIds = [match.route.filePath, ...layoutPaths];
+    const cssStyles = await collectCss(server, cssEntryIds);
+    const rscEnv = server.environments.rsc;
+    const ssrEnv = server.environments.ssr;
+    if (!rscEnv?.runner || !ssrEnv?.runner) {
+        throw new Error("[catmint] RSC/SSR environment runners not available. " +
+            "Make sure @vitejs/plugin-rsc is configured.");
+    }
+    // Phase 1: RSC rendering — produce the flight stream
+    // We dynamically construct and evaluate code in the RSC environment
+    // that imports the page + layouts and calls renderToReadableStream
+    const rscMod = await rscEnv.runner.import("@vitejs/plugin-rsc/rsc");
+    const { renderToReadableStream: rscRender } = rscMod;
+    // Import page and layout modules in the RSC environment
+    const pageMod = await rscEnv.runner.import(pageImportPath);
+    const PageComponent = pageMod.default;
+    if (!PageComponent) {
+        server.config.logger.error(`[catmint] Page ${match.route.filePath} does not have a default export`);
+        if (sendStatusPage) {
+            await sendStatusPage(res, 404, url);
+        }
+        else {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(errorPageHtml(404));
+        }
+        return;
+    }
+    const layoutComponents = [];
+    const layoutMods = [];
+    for (const lp of layoutImportPaths) {
+        const layoutMod = await rscEnv.runner.import(lp);
+        layoutMods.push(layoutMod);
+        if (layoutMod.default) {
+            layoutComponents.push(layoutMod.default);
+        }
+    }
+    // Resolve generateMetadata exports from page + layout modules
+    const headConfig = await resolveGenerateMetadata(pageMod, layoutMods, match.params ?? {}, url);
+    // We need React from the RSC environment (with react-server condition)
+    const reactMod = await rscEnv.runner.import("react");
+    const createElement = reactMod.createElement ?? reactMod.default?.createElement;
+    if (!createElement) {
+        server.config.logger.error(`[catmint] React module from RSC environment has no createElement. ` +
+            `Available exports: ${Object.keys(reactMod).join(", ")}`);
+        throw new Error("[catmint] Cannot find React.createElement in RSC environment");
+    }
+    // Build component tree: Layout0(Layout1(ErrorBoundary(Suspense(Page))))
+    // If a loading.tsx is found, wrap the page with a Suspense boundary.
+    // If an error.tsx is found via walk-up resolution, wrap the page
+    // with the error boundary component inside the nearest layout.
+    let element = createElement(PageComponent, null);
+    // Resolve loading.tsx from the page directory for Suspense fallback
+    const loadingPath = resolveLoadingComponent(match.route.filePath);
+    if (loadingPath) {
+        const loadingImportPath = "/" + relative(root, loadingPath);
+        try {
+            const loadingMod = await rscEnv.runner.import(loadingImportPath);
+            const LoadingComponent = loadingMod.default;
+            if (LoadingComponent) {
+                const Suspense = reactMod.Suspense ?? reactMod.default?.Suspense;
+                if (Suspense) {
+                    element = createElement(Suspense, {
+                        fallback: createElement(LoadingComponent, null),
+                        children: element,
+                    });
+                }
+            }
+        }
+        catch {
+            server.config.logger.warn(`[catmint] Failed to load loading component ${loadingPath}`);
+        }
+    }
+    // Resolve error boundary via walk-up from page directory to app root
+    const errorBoundaryPath = resolveErrorBoundary(match.route.filePath, appDir);
+    if (errorBoundaryPath) {
+        const errorBoundaryImportPath = "/" + relative(root, errorBoundaryPath);
+        try {
+            const errorMod = await rscEnv.runner.import(errorBoundaryImportPath);
+            const ErrorBoundaryComponent = errorMod.default;
+            if (ErrorBoundaryComponent) {
+                // Wrap page with error boundary — it renders inside the nearest layout
+                element = createElement(ErrorBoundaryComponent, { children: element });
+            }
+        }
+        catch {
+            // If error boundary fails to load, skip it gracefully
+            server.config.logger.warn(`[catmint] Failed to load error boundary ${errorBoundaryPath}`);
+        }
+    }
+    for (let i = layoutComponents.length - 1; i >= 0; i--) {
+        element = createElement(layoutComponents[i], null, element);
+    }
+    // Wrap with AppProviders (client component — RSC sees it as a client reference)
+    const appProvidersMod = await rscEnv.runner.import("catmint/runtime/app-providers");
+    const AppProviders = appProvidersMod.AppProviders ?? appProvidersMod.default?.AppProviders;
+    if (AppProviders) {
+        const urlObj = new URL(url, "http://localhost");
+        const providerProps = {
+            pathname: urlObj.pathname,
+            params: match.params ?? {},
+        };
+        if (i18nConfig) {
+            providerProps.i18nConfig = i18nConfig;
+        }
+        if (headConfig) {
+            providerProps.headConfig = headConfig;
+        }
+        element = createElement(AppProviders, providerProps, element);
+    }
+    // Render to RSC flight stream
+    const rscStream = rscRender(element);
+    // Phase 2: Tee the RSC stream — one for SSR, one for browser injection
+    const [rscForSsr, rscForBrowser] = rscStream.tee();
+    // SSR: convert RSC flight stream → React VDOM → HTML
+    const ssrMod = await ssrEnv.runner.import("@vitejs/plugin-rsc/ssr");
+    const { createFromReadableStream: ssrCreate } = ssrMod;
+    const reactDomServer = await ssrEnv.runner.import("react-dom/server");
+    const { renderToReadableStream: htmlRender } = reactDomServer;
+    // createFromReadableStream returns a "thenable" that resolves to the React tree
+    const ssrRoot = ssrCreate(rscForSsr);
+    // Bootstrap script that loads the client hydration entry.
+    // This is passed to renderToReadableStream which injects it as a <script>
+    // tag in <body>, ensuring it runs after the HTML is parsed.
+    // The virtual module imports rsc-html-stream/client to read embedded RSC
+    // payload, @vitejs/plugin-rsc/browser to deserialize, and react-dom/client
+    // to hydrate.
+    const bootstrapScriptContent = `import("/@id/__x00__virtual:catmint/client-hydrate")`;
+    // Render the React tree to an HTML stream
+    // The SSR root is a thenable — React's renderToReadableStream handles it
+    const htmlStream = await htmlRender(ssrRoot, {
+        bootstrapScriptContent,
+    });
+    // Phase 3: Inject RSC payload into the HTML stream
+    const rscHtmlStream = await ssrEnv.runner.import("rsc-html-stream/server");
+    const { injectRSCPayload } = rscHtmlStream;
+    const injectionTransform = injectRSCPayload(rscForBrowser);
+    const finalStream = htmlStream.pipeThrough(injectionTransform);
+    // Build head injection (Vite client, CSS, soft nav config, metadata)
+    const headParts = [
+        `<script>window.__catmintSoftNav=${softNavigation ? "true" : "false"}</script>`,
+        '<script type="module" src="/@vite/client"></script>',
+        cssStyles,
+    ];
+    if (headConfig) {
+        headParts.unshift(renderHeadToString(headConfig));
+    }
+    const headInjection = headParts.join("\n");
+    // Stream the final HTML to the response, injecting our head content
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.statusCode = 200;
+    // We need to inject our scripts into <head>. Since we're dealing with a
+    // Web ReadableStream, we'll buffer and inject.
+    const reader = finalStream.getReader();
+    const decoder = new TextDecoder();
+    let injected = false;
+    let buffer = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = decoder.decode(value, {
+                stream: true,
+            });
+            if (injected) {
+                res.write(chunk);
+                continue;
+            }
+            buffer += chunk;
+            const headCloseIdx = buffer.indexOf("</head>");
+            if (headCloseIdx !== -1) {
+                injected = true;
+                let before = buffer.slice(0, headCloseIdx);
+                const after = buffer.slice(headCloseIdx);
+                if (headConfig) {
+                    before = stripExistingHeadTags(before, headConfig);
+                }
+                res.write(before + headInjection + after);
+                buffer = "";
+            }
+            else if (buffer.length > 7) {
+                const safe = buffer.slice(0, -7);
+                buffer = buffer.slice(-7);
+                res.write(safe);
+            }
+        }
+        // Flush remaining buffer
+        if (!injected && buffer) {
+            res.write(buffer + headInjection);
+        }
+        else if (buffer) {
+            res.write(buffer);
+        }
+    }
+    finally {
+        res.end();
+    }
+}
+// --------------------------------------------------------------------------
+// RSC flight stream for client-side navigation
+// --------------------------------------------------------------------------
+/**
+ * Handle an RSC navigation request.
+ *
+ * Returns the raw RSC flight stream for a page, without SSR-ing to HTML.
+ * This is used by the client-side navigation runtime to perform SPA-style
+ * page transitions: the browser fetches the flight stream, deserializes it
+ * with createFromReadableStream, and React reconciles the new tree.
+ */
+async function handleRscNavigation(server, _req, res, match, appDir, i18nConfig = null) {
+    const url = _req.originalUrl ?? _req.url ?? "/";
+    const root = server.config.root;
+    // Collect layout chain for this page
+    const layoutPaths = collectLayouts(match.route.filePath, appDir);
+    // Convert paths to Vite-resolvable import paths
+    const pageImportPath = "/" + relative(root, match.route.filePath);
+    const layoutImportPaths = layoutPaths.map((lp) => "/" + relative(root, lp));
+    const rscEnv = server.environments.rsc;
+    if (!rscEnv?.runner) {
+        throw new Error("[catmint] RSC environment runner not available for navigation.");
+    }
+    // Import RSC rendering utilities
+    const rscMod = await rscEnv.runner.import("@vitejs/plugin-rsc/rsc");
+    const { renderToReadableStream: rscRender } = rscMod;
+    // Import page and layout modules in the RSC environment
+    const pageMod = await rscEnv.runner.import(pageImportPath);
+    const PageComponent = pageMod.default;
+    if (!PageComponent) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "Page has no default export" }));
+        return;
+    }
+    const layoutComponents = [];
+    const layoutMods = [];
+    for (const lp of layoutImportPaths) {
+        const layoutMod = await rscEnv.runner.import(lp);
+        layoutMods.push(layoutMod);
+        if (layoutMod.default) {
+            layoutComponents.push(layoutMod.default);
+        }
+    }
+    // Resolve generateMetadata exports from page + layout modules
+    const headConfig = await resolveGenerateMetadata(pageMod, layoutMods, match.params ?? {}, url);
+    // Get React from the RSC environment
+    const reactMod = await rscEnv.runner.import("react");
+    const createElement = reactMod.createElement ?? reactMod.default?.createElement;
+    if (!createElement) {
+        throw new Error("[catmint] Cannot find React.createElement in RSC environment");
+    }
+    // Build component tree: Layout0(Layout1(ErrorBoundary(Suspense(Page))))
+    // If a loading.tsx is found, wrap the page with a Suspense boundary.
+    // If an error.tsx is found via walk-up resolution, wrap the page
+    // with the error boundary component inside the nearest layout.
+    let element = createElement(PageComponent, null);
+    // Resolve loading.tsx from the page directory for Suspense fallback
+    const loadingPath = resolveLoadingComponent(match.route.filePath);
+    if (loadingPath) {
+        const loadingImportPath = "/" + relative(root, loadingPath);
+        try {
+            const loadingMod = await rscEnv.runner.import(loadingImportPath);
+            const LoadingComponent = loadingMod.default;
+            if (LoadingComponent) {
+                const Suspense = reactMod.Suspense ?? reactMod.default?.Suspense;
+                if (Suspense) {
+                    element = createElement(Suspense, {
+                        fallback: createElement(LoadingComponent, null),
+                        children: element,
+                    });
+                }
+            }
+        }
+        catch {
+            server.config.logger.warn(`[catmint] Failed to load loading component ${loadingPath}`);
+        }
+    }
+    // Resolve error boundary via walk-up from page directory to app root
+    const errorBoundaryPath = resolveErrorBoundary(match.route.filePath, appDir);
+    if (errorBoundaryPath) {
+        const errorBoundaryImportPath = "/" + relative(root, errorBoundaryPath);
+        try {
+            const errorMod = await rscEnv.runner.import(errorBoundaryImportPath);
+            const ErrorBoundaryComponent = errorMod.default;
+            if (ErrorBoundaryComponent) {
+                // Wrap page with error boundary — it renders inside the nearest layout
+                element = createElement(ErrorBoundaryComponent, { children: element });
+            }
+        }
+        catch {
+            // If error boundary fails to load, skip it gracefully
+            server.config.logger.warn(`[catmint] Failed to load error boundary ${errorBoundaryPath}`);
+        }
+    }
+    for (let i = layoutComponents.length - 1; i >= 0; i--) {
+        element = createElement(layoutComponents[i], null, element);
+    }
+    // Wrap with AppProviders (client component — RSC sees it as a client reference)
+    const appProvidersMod = await rscEnv.runner.import("catmint/runtime/app-providers");
+    const AppProviders = appProvidersMod.AppProviders ?? appProvidersMod.default?.AppProviders;
+    if (AppProviders) {
+        const parsedUrl = new URL(url, "http://localhost");
+        const targetPath = parsedUrl.searchParams.get("path") ?? parsedUrl.pathname;
+        const providerProps = {
+            pathname: targetPath,
+            params: match.params ?? {},
+        };
+        if (i18nConfig) {
+            providerProps.i18nConfig = i18nConfig;
+        }
+        if (headConfig) {
+            providerProps.headConfig = headConfig;
+        }
+        element = createElement(AppProviders, providerProps, element);
+    }
+    // Render to RSC flight stream
+    const rscStream = rscRender(element);
+    // Stream the raw flight data to the client
+    res.setHeader("Content-Type", "text/x-component; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+    res.statusCode = 200;
+    const reader = rscStream.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            res.write(value);
+        }
+    }
+    finally {
+        res.end();
+    }
+}
+// --------------------------------------------------------------------------
+// Legacy SSR rendering (fallback when RSC plugin is not active)
+// --------------------------------------------------------------------------
+/**
+ * Handle a page request using traditional SSR (no RSC).
+ * Used as fallback when @vitejs/plugin-rsc is not configured.
+ */
+async function handlePageLegacy(server, _req, res, match, appDir, hydrScripts, hydrCounter, hydrPrefix, i18nConfig = null) {
+    const url = _req.originalUrl ?? _req.url ?? "/";
+    const { createRequire } = await import("node:module");
+    const { Transform } = await import("node:stream");
+    const userRequire = createRequire(join(server.config.root, "package.json"));
+    const React = userRequire("react");
+    const { renderToPipeableStream } = userRequire("react-dom/server");
+    const pageMod = await server.ssrLoadModule(match.route.filePath);
+    const PageComponent = pageMod.default;
+    if (!PageComponent) {
+        server.config.logger.error(`[catmint] Page ${match.route.filePath} does not have a default export`);
+        return;
+    }
+    const layoutPaths = collectLayouts(match.route.filePath, appDir);
+    const layoutComponents = [];
+    const layoutMods = [];
+    for (const layoutPath of layoutPaths) {
+        const layoutMod = await server.ssrLoadModule(layoutPath);
+        layoutMods.push(layoutMod);
+        if (layoutMod.default) {
+            layoutComponents.push(layoutMod.default);
+        }
+    }
+    // Resolve generateMetadata exports from page + layout modules
+    const headConfig = await resolveGenerateMetadata(pageMod, layoutMods, match.params ?? {}, url);
+    let element = React.createElement(PageComponent, null);
+    for (let i = layoutComponents.length - 1; i >= 0; i--) {
+        element = React.createElement(layoutComponents[i], null, element);
+    }
+    // Wrap with AppProviders (legacy mode: import directly via SSR)
+    const appProvidersMod = await server.ssrLoadModule("catmint/runtime/app-providers");
+    const AppProviders = appProvidersMod.AppProviders;
+    if (AppProviders) {
+        const urlObj = new URL(url, "http://localhost");
+        const providerProps = {
+            pathname: urlObj.pathname,
+            params: match.params ?? {},
+        };
+        if (i18nConfig) {
+            providerProps.i18nConfig = i18nConfig;
+        }
+        if (headConfig) {
+            providerProps.headConfig = headConfig;
+        }
+        element = React.createElement(AppProviders, providerProps, element);
+    }
+    const pageImportPath = "/" + relative(server.config.root, match.route.filePath);
+    const layoutImports = layoutPaths.map((lp, i) => {
+        const importPath = "/" + relative(server.config.root, lp);
+        return `import Layout${i} from '${importPath}'`;
+    });
+    const layoutVarNames = layoutPaths.map((_, i) => `Layout${i}`);
+    let hydrateTree = "createElement(Page, null)";
+    for (let i = layoutComponents.length - 1; i >= 0; i--) {
+        hydrateTree = `createElement(${layoutVarNames[i]}, null, ${hydrateTree})`;
+    }
+    // Build AppProviders props as a JSON-safe string for the hydration script
+    const providerPropsJson = JSON.stringify({
+        pathname: new URL(url, "http://localhost").pathname,
+        params: match.params ?? {},
+        ...(i18nConfig ? { i18nConfig } : {}),
+        ...(headConfig ? { headConfig } : {}),
+    });
+    const hydrationScript = [
+        `import { hydrateRoot } from 'react-dom/client'`,
+        `import { createElement } from 'react'`,
+        `import { AppProviders } from 'catmint/runtime/app-providers'`,
+        ...layoutImports,
+        `import Page from '${pageImportPath}'`,
+        `var __providerProps = ${providerPropsJson}`,
+        `hydrateRoot(document, createElement(AppProviders, __providerProps, ${hydrateTree}))`,
+    ].join("\n");
+    const hydrateId = `entry-${hydrCounter}.js`;
+    hydrScripts.set(hydrateId, hydrationScript);
+    const cssEntryIds = [match.route.filePath, ...layoutPaths];
+    const cssStyles = await collectCss(server, cssEntryIds);
+    const headParts = [
+        '<script type="module" src="/@vite/client"></script>',
+        cssStyles,
+        `<script type="module" src="${hydrPrefix}${hydrateId}"></script>`,
+    ];
+    if (headConfig) {
+        headParts.unshift(renderHeadToString(headConfig));
+    }
+    const headInjection = headParts.join("\n");
+    const { pipe } = renderToPipeableStream(element, {
+        onShellReady() {
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.statusCode = 200;
+            const transform = createInjectionTransform(headInjection, headConfig);
+            pipe(transform);
+            transform.pipe(res);
+        },
+        onShellError(error) {
+            server.config.logger.error(`[catmint] SSR shell error for ${url}:`);
+            server.config.logger.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(errorPageHtml(500, { detail: String(error) }));
+        },
+        onError(error) {
+            server.config.logger.error(`[catmint] SSR streaming error for ${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        },
+    });
+}
+// --------------------------------------------------------------------------
+// Virtual module generators
+// --------------------------------------------------------------------------
+/**
+ * Generate the RSC renderer virtual module.
+ * This module is loaded in the RSC environment via environment.runner.import().
+ * It exports a `renderPage(pagePath, layoutPaths)` function that:
+ * - Imports the page and layout modules
+ * - Builds the React element tree
+ * - Calls renderToReadableStream to produce an RSC flight stream
+ */
+function generateRscRendererModule() {
+    return `
+import { renderToReadableStream } from "@vitejs/plugin-rsc/rsc";
+import { createElement } from "react";
+import { AppProviders } from "catmint/runtime/app-providers";
+
+export async function renderPage(pagePath, layoutPaths, providerProps) {
+  const pageMod = await import(/* @vite-ignore */ pagePath);
+  const Page = pageMod.default;
+  if (!Page) throw new Error("Page " + pagePath + " has no default export");
+
+  const layouts = [];
+  for (const lp of layoutPaths) {
+    const mod = await import(/* @vite-ignore */ lp);
+    if (mod.default) layouts.push(mod.default);
+  }
+
+  let element = createElement(Page, null);
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    element = createElement(layouts[i], null, element);
+  }
+
+  // Wrap with framework providers
+  element = createElement(AppProviders, providerProps || {}, element);
+
+  return renderToReadableStream(element);
+}
+`;
+}
+/**
+ * Generate the SSR renderer virtual module.
+ * This module is loaded in the SSR environment. It exports a
+ * `renderToHtml(rscStream)` function that:
+ * - Calls createFromReadableStream to deserialize the RSC flight stream
+ * - Passes the result to react-dom/server.renderToReadableStream
+ * - Returns an HTML ReadableStream
+ */
+function generateSsrRendererModule() {
+    return `
+import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+import { renderToReadableStream } from "react-dom/server";
+import { injectRSCPayload } from "rsc-html-stream/server";
+
+export async function renderToHtml(rscStream) {
+  const [rscForSsr, rscForBrowser] = rscStream.tee();
+  const root = createFromReadableStream(rscForSsr);
+  const htmlStream = await renderToReadableStream(root);
+  return htmlStream.pipeThrough(injectRSCPayload(rscForBrowser));
+}
+`;
+}
+/**
+ * Generate the client hydration virtual module.
+ * This module runs in the browser. It:
+ * - Reads the embedded RSC payload from the HTML
+ * - Deserializes it via createFromReadableStream
+ * - Hydrates the document via hydrateRoot
+ * - Installs client-side navigation for relative links (when soft nav is enabled)
+ */
+function generateClientHydrateModule() {
+    return `
+import { rscStream } from "rsc-html-stream/client";
+import { createFromReadableStream } from "@vitejs/plugin-rsc/browser";
+import { hydrateRoot } from "react-dom/client";
+
+let root = null;
+
+async function hydrate() {
+  const initialRoot = await createFromReadableStream(rscStream);
+  root = hydrateRoot(document, initialRoot);
+}
+
+${CLIENT_NAVIGATION_RUNTIME}
+
+hydrate().then(() => {
+  if (window.__catmintSoftNav) {
+    setupClientNavigation(root);
+  }
+});
+`;
+}
+// --------------------------------------------------------------------------
+// Utilities
+// --------------------------------------------------------------------------
+function createInjectionTransform(injection, headConfig) {
+    const { Transform } = require("node:stream");
+    let injected = false;
+    let buffer = "";
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            if (injected) {
+                callback(null, chunk);
+                return;
+            }
+            buffer += chunk.toString();
+            const headCloseIdx = buffer.indexOf("</head>");
+            if (headCloseIdx !== -1) {
+                injected = true;
+                let before = buffer.slice(0, headCloseIdx);
+                const after = buffer.slice(headCloseIdx);
+                if (headConfig) {
+                    before = stripExistingHeadTags(before, headConfig);
+                }
+                callback(null, before + injection + after);
+                buffer = "";
+            }
+            else {
+                if (buffer.length > 7) {
+                    const safe = buffer.slice(0, -7);
+                    buffer = buffer.slice(-7);
+                    callback(null, safe);
+                }
+                else {
+                    callback();
+                }
+            }
+        },
+        flush(callback) {
+            if (!injected && buffer) {
+                callback(null, buffer + injection);
+            }
+            else if (buffer) {
+                callback(null, buffer);
+            }
+            else {
+                callback();
+            }
+        },
+    });
+}
+//# sourceMappingURL=dev-server.js.map