@catmint/vite 0.0.0-prealpha.2 → 0.0.0-prealpha.20

package/dist/dev-server.js

@@ -12,10 +12,19 @@
 //                → 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 { join, dirname, relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { deterministicHash, toPosixPath, CLIENT_NAVIGATION_RUNTIME, } from "./utils.js";
+/**
+ * Runtime context APIs — dynamically imported from `catmint/runtime/context`
+ * in `configureServer` so the module is resolved via SSR externals (Node.js
+ * resolution) rather than Vite's module graph. The functions are stored in
+ * these module-level variables after initialisation.
+ */
+let createRequestStore;
+let runWithRequestContext;
 import { errorPageHtml } from "./error-page.js";
 import { scanStatusPages } from "./build-entries.js";
 import { buildPreflightHeaders } from "./cors-utils.js";
@@ -94,7 +103,7 @@ 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"]) {
+        for (const name of ["layout.tsx", "layout.ts"]) {
             const layoutPath = join(dir, name);
             if (existsSync(layoutPath)) {
                 layouts.unshift(layoutPath);
@@ -107,6 +116,154 @@ function collectLayouts(pageFilePath, appDir) {
     }
     return layouts;
 }
+/**
+ * File names checked for middleware, in priority order.
+ */
+const MIDDLEWARE_FILENAMES = ["middleware.ts", "middleware.tsx"];
+/**
+ * Resolve the middleware chain for a given route directory.
+ * Walks from the page's directory up to appDir, collecting middleware files.
+ * Returns paths in root-to-tip execution order.
+ */
+function collectMiddleware(pageFilePath, appDir) {
+    const middlewareFiles = [];
+    let dir = dirname(pageFilePath);
+    while (dir.startsWith(appDir)) {
+        for (const name of MIDDLEWARE_FILENAMES) {
+            const middlewarePath = join(dir, name);
+            if (existsSync(middlewarePath)) {
+                middlewareFiles.unshift(middlewarePath); // prepend for root-to-tip order
+                break; // Only one middleware file per directory
+            }
+        }
+        if (dir === appDir)
+            break;
+        dir = dirname(dir);
+    }
+    return middlewareFiles;
+}
+/**
+ * Convert a Node.js IncomingMessage to a Web Request object.
+ */
+function nodeReqToWebRequest(req) {
+    const protocol = "http";
+    const host = req.headers.host ?? "localhost";
+    const url = new URL(req.originalUrl ?? req.url ?? "/", `${protocol}://${host}`);
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value) {
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    headers.append(key, v);
+                }
+            }
+            else {
+                headers.set(key, value);
+            }
+        }
+    }
+    return new Request(url.href, {
+        method: req.method ?? "GET",
+        headers,
+    });
+}
+/**
+ * Send a Web Response back through a Node.js ServerResponse.
+ */
+async function sendWebResponse(res, webResponse) {
+    res.statusCode = webResponse.status;
+    webResponse.headers.forEach((value, key) => {
+        res.setHeader(key, value);
+    });
+    const body = await webResponse.text();
+    res.end(body);
+}
+/**
+ * Execute the middleware chain for a route. Returns a Response from middleware
+ * if middleware short-circuits (e.g., 401), or null if middleware calls next()
+ * and page rendering should proceed. Also returns any response headers that
+ * middleware added (e.g., X-Response-Time) so they can be merged into the
+ * final page response.
+ */
+async function executeMiddleware(server, req, pageFilePath, appDir) {
+    const middlewarePaths = collectMiddleware(pageFilePath, appDir);
+    if (middlewarePaths.length === 0) {
+        return { shortCircuit: null, headers: new Headers() };
+    }
+    const handlers = [];
+    for (const mwPath of middlewarePaths) {
+        try {
+            const importPath = "/" + relative(server.config.root, mwPath);
+            const mod = await server.ssrLoadModule(importPath);
+            const handler = mod.default;
+            if (typeof handler === "function") {
+                handlers.push(handler);
+            }
+        }
+        catch (err) {
+            server.config.logger.warn(`[catmint] Failed to load middleware ${mwPath}: ${err}`);
+        }
+    }
+    if (handlers.length === 0) {
+        return { shortCircuit: null, headers: new Headers() };
+    }
+    // Apply inherit boundary: walk backwards to find inherit: false
+    let boundaryIndex = 0;
+    for (let i = handlers.length - 1; i >= 0; i--) {
+        const opts = handlers[i].__catmintMiddleware;
+        if (opts && opts.inherit === false) {
+            boundaryIndex = i;
+            break;
+        }
+    }
+    const effectiveHandlers = handlers.slice(boundaryIndex);
+    // Create the Web Request
+    const webRequest = nodeReqToWebRequest(req);
+    // Compose and execute middleware chain
+    let middlewareCalledNext = false;
+    const capturedHeaders = new Headers();
+    const executeChain = (index) => {
+        if (index >= effectiveHandlers.length) {
+            // End of chain — middleware called next(), page rendering should proceed
+            middlewareCalledNext = true;
+            return Promise.resolve(new Response(null, { status: 200 }));
+        }
+        const handler = effectiveHandlers[index];
+        return Promise.resolve(handler(webRequest, () => {
+            const nextResult = executeChain(index + 1);
+            return nextResult.then((response) => {
+                // Capture headers from inner middleware/next
+                response.headers.forEach((value, key) => {
+                    capturedHeaders.set(key, value);
+                });
+                return response;
+            });
+        })).then((response) => {
+            // Capture headers from this middleware
+            response.headers.forEach((value, key) => {
+                capturedHeaders.set(key, value);
+            });
+            return response;
+        });
+    };
+    try {
+        const response = await executeChain(0);
+        if (!middlewareCalledNext) {
+            // Middleware short-circuited (returned a response without calling next)
+            return { shortCircuit: response, headers: capturedHeaders };
+        }
+        // Middleware called next() — proceed with page rendering
+        // but pass along any headers middleware added
+        return { shortCircuit: null, headers: capturedHeaders };
+    }
+    catch (err) {
+        server.config.logger.error(`[catmint] Middleware error: ${err}`);
+        return {
+            shortCircuit: new Response("Internal Server Error", { status: 500 }),
+            headers: new Headers(),
+        };
+    }
+}
 /**
  * CSS file extensions that Vite processes.
  */
@@ -349,6 +506,52 @@ const SERVER_FN_PREFIX = "/__catmint/fn/";
  * RSC flight stream prefix for client-side navigation.
  */
 const RSC_NAVIGATION_PREFIX = "/__catmint/rsc";
+// ---------------------------------------------------------------------------
+// Server function error detection helpers (duck-typing)
+//
+// The dev-server cannot import from `catmint` directly (it's in the
+// `@catmint/vite` package). Instead, we detect error types by checking
+// for characteristic properties — this matches instances loaded at
+// runtime via Vite's SSR module loader.
+// ---------------------------------------------------------------------------
+/**
+ * Check if a value looks like a ClientSafeError (duck-typing).
+ * Matches: instance has `name === "ClientSafeError"` OR has `statusCode`
+ * property and the constructor chain includes a class with name "ClientSafeError".
+ */
+function isClientSafeErrorLike(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    // Direct instance check by name (supports subclasses via prototype chain)
+    if (value instanceof Error && typeof value.statusCode === "number") {
+        let proto = Object.getPrototypeOf(value);
+        while (proto && proto !== Error.prototype) {
+            if (proto.constructor?.name === "ClientSafeError")
+                return true;
+            proto = Object.getPrototypeOf(proto);
+        }
+    }
+    return false;
+}
+/**
+ * Check if a value looks like a RedirectError (duck-typing).
+ */
+function isRedirectErrorLike(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return (value instanceof Error &&
+        value.name === "RedirectError" &&
+        typeof value.url === "string" &&
+        typeof value.status === "number");
+}
+/**
+ * Generate a short correlation hash for error tracking.
+ * Used in production to link client error messages to server logs.
+ */
+function errorRef(err) {
+    const content = `${Date.now()}:${err instanceof Error ? err.message : String(err)}`;
+    return createHash("sha256").update(content).digest("hex").slice(0, 8);
+}
 /**
  * Handle a server function RPC call.
  *
@@ -441,17 +644,63 @@ async function handleServerFn(server, req, res, pathname) {
     // Call the server function
     try {
         const result = await matchedFn(input);
+        // Check if the result IS a ClientSafeError (returned, not thrown).
+        // Use duck-typing since we can't import from `catmint` directly.
+        if (isClientSafeErrorLike(result)) {
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                __clientSafeError: true,
+                error: result.message,
+                statusCode: result.statusCode,
+                data: result.data,
+            }));
+            return;
+        }
         res.statusCode = 200;
         res.setHeader("Content-Type", "application/json");
         res.end(JSON.stringify(result));
     }
     catch (err) {
+        // Always log the full error server-side
         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",
-        }));
+        // RedirectError — send redirect envelope to client
+        if (isRedirectErrorLike(err)) {
+            res.statusCode = 200;
+            res.end(JSON.stringify({
+                __redirect: true,
+                url: err.url,
+                status: err.status,
+            }));
+            return;
+        }
+        // ClientSafeError — developer opted in, expose to client
+        if (isClientSafeErrorLike(err)) {
+            res.statusCode = err.statusCode;
+            res.end(JSON.stringify({
+                error: err.message,
+                data: err.data,
+            }));
+            return;
+        }
+        // Default: sanitize error — in dev mode, leak with warning;
+        // in prod mode, use generic message with correlation hash
+        const isDev = server.config.mode === "development" || !server.config.isProduction;
+        res.statusCode = 500;
+        if (isDev) {
+            const originalMessage = err instanceof Error ? err.message : String(err);
+            res.end(JSON.stringify({
+                error: `[DEV ONLY] ${originalMessage}`,
+            }));
+        }
+        else {
+            const ref = errorRef(err);
+            server.config.logger.error(`[catmint] Error reference [ref: ${ref}] — see above for full error`);
+            res.end(JSON.stringify({
+                error: `Internal Server Error [ref: ${ref}]`,
+            }));
+        }
     }
 }
 /**
@@ -493,7 +742,26 @@ async function handleEndpoint(server, req, res, match, method) {
     }
     const webRequest = new Request(fullUrl, requestInit);
     const ctx = { params: match.params };
-    const response = await handler(webRequest, ctx);
+    let response;
+    try {
+        response = await handler(webRequest, ctx);
+    }
+    catch (err) {
+        // redirect() throws a RedirectError — convert it to a real HTTP redirect
+        if (isRedirectErrorLike(err)) {
+            const re = err;
+            res.statusCode = re.status;
+            res.setHeader("Location", re.url);
+            if (re.headers) {
+                for (const [k, v] of Object.entries(re.headers)) {
+                    res.setHeader(k, v);
+                }
+            }
+            res.end();
+            return;
+        }
+        throw err;
+    }
     res.statusCode = response.status;
     response.headers.forEach((value, key) => {
         res.setHeader(key, value);
@@ -543,8 +811,10 @@ const RESOLVED_CLIENT_HYDRATE_ID = "\0" + CLIENT_HYDRATE_ID;
 export function devServerPlugin(options) {
     const softNav = options?.softNavigation ?? true;
     const i18nConfig = options?.i18n ?? null;
+    const adapter = options?.adapter ?? null;
     let server;
     let appDir;
+    let devPlatform = null;
     let pageMatcher = null;
     let endpointMatcher = null;
     // Pre-scanned status pages sorted by most-specific (longest prefix) first.
@@ -784,6 +1054,71 @@ export function devServerPlugin(options) {
             return null;
         }
     }
+    /**
+     * Read `compilerOptions.paths` from the project's `tsconfig.json` and
+     * convert them to Vite `resolve.alias` entries so that path aliases like
+     * `@/*` or `~/*` work at runtime without extra user configuration.
+     *
+     * - Strips JSON comments (JSONC) before parsing.
+     * - Respects `compilerOptions.baseUrl` (defaults to tsconfig directory).
+     * - Wildcard patterns (`"@/*": ["./app/*"]`) become regex aliases.
+     * - Exact patterns (`"@/utils": ["./src/utils"]`) become string aliases.
+     */
+    function buildTsconfigAliases(root) {
+        const aliases = [];
+        // Look for tsconfig.json in the project root
+        const tsconfigPath = join(root, "tsconfig.json");
+        if (!existsSync(tsconfigPath))
+            return aliases;
+        let raw;
+        try {
+            raw = readFileSync(tsconfigPath, "utf-8");
+        }
+        catch {
+            return aliases;
+        }
+        // Strip single-line and multi-line comments (JSONC → JSON)
+        const stripped = raw
+            .replace(/\/\/.*$/gm, "")
+            .replace(/\/\*[\s\S]*?\*\//g, "");
+        let parsed;
+        try {
+            parsed = JSON.parse(stripped);
+        }
+        catch {
+            return aliases;
+        }
+        const paths = parsed.compilerOptions?.paths;
+        if (!paths)
+            return aliases;
+        const baseUrl = parsed.compilerOptions?.baseUrl
+            ? resolve(dirname(tsconfigPath), parsed.compilerOptions.baseUrl)
+            : dirname(tsconfigPath);
+        for (const [pattern, targets] of Object.entries(paths)) {
+            const target = targets?.[0];
+            if (!target)
+                continue;
+            if (pattern.endsWith("/*") && target.endsWith("/*")) {
+                // Wildcard pattern: "@/*" → ["./app/*"]
+                // Convert to regex so Vite matches any subpath
+                const prefix = pattern.slice(0, -2); // "@"
+                const targetDir = resolve(baseUrl, target.slice(0, -2)); // abs path to "./app"
+                const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                aliases.push({
+                    find: new RegExp(`^${escaped}\\/(.+)$`),
+                    replacement: `${targetDir}/$1`,
+                });
+            }
+            else {
+                // Exact pattern: "@/utils" → ["./src/utils"]
+                aliases.push({
+                    find: pattern,
+                    replacement: resolve(baseUrl, target),
+                });
+            }
+        }
+        return aliases;
+    }
     /**
      * Build resolve.alias entries so that all Vite environments can find
      * @vitejs/plugin-rsc subpaths and rsc-html-stream subpaths regardless
@@ -838,14 +1173,20 @@ export function devServerPlugin(options) {
     return {
         name: "catmint:dev-server",
         enforce: "post",
-        config() {
-            const aliases = buildRscAliases();
+        config(userConfig) {
+            const root = userConfig.root ?? process.cwd();
+            const rscAliases = buildRscAliases();
+            const tsconfigAliases = buildTsconfigAliases(root);
             return {
                 resolve: {
-                    alias: aliases,
+                    alias: [...tsconfigAliases, ...rscAliases],
                 },
                 ssr: {
-                    external: ["catmint/routing", "catmint/status"],
+                    external: [
+                        "catmint/routing",
+                        "catmint/status",
+                        "catmint/runtime/context",
+                    ],
                 },
                 optimizeDeps: {
                     include: [
@@ -894,6 +1235,61 @@ export function devServerPlugin(options) {
             server = viteServer;
             appDir = join(server.config.root, "app");
             statusPages = scanStatusPages(appDir);
+            // Load request context APIs from catmint/runtime/context via SSR
+            // module resolution (not a static import) so the module is resolved
+            // through Node.js resolution at dev time, not Vite's module graph.
+            const contextReady = server
+                .ssrLoadModule("catmint/runtime/context")
+                .then((mod) => {
+                createRequestStore = mod.createRequestStore;
+                runWithRequestContext = mod.runWithRequestContext;
+            });
+            // Store the promise so the first request can await it
+            server.__catmintContextReady = contextReady;
+            // Initialize adapter dev platform (e.g. Cloudflare getPlatformProxy).
+            // This is async but we can't await in configureServer, so we kick it
+            // off and store the promise. The first request will await it.
+            if (adapter?.dev) {
+                const initPromise = Promise.resolve(adapter.dev());
+                initPromise
+                    .then((helper) => {
+                    devPlatform = helper;
+                    server.config.logger.info(`[catmint] Adapter "${adapter.name}" dev platform initialized`);
+                })
+                    .catch((err) => {
+                    server.config.logger.error(`[catmint] Failed to initialize adapter dev platform: ${err instanceof Error ? err.message : String(err)}`);
+                });
+                // Store the promise so requests can await it
+                server.__catmintDevPlatformInit = initPromise;
+                // Clean up on server close
+                server.httpServer?.on("close", () => {
+                    if (devPlatform?.close) {
+                        Promise.resolve(devPlatform.close()).catch(() => { });
+                    }
+                });
+            }
+            // Invalidate route matchers when route files are added or removed.
+            // Vite's handleHotUpdate only fires for files already in the module
+            // graph, so newly created or deleted files need this watcher to
+            // trigger a re-scan on the next request.
+            const isRouteFile = (f) => f.includes("/app/") &&
+                (f.endsWith("page.tsx") ||
+                    f.endsWith("page.mdx") ||
+                    f.endsWith("endpoint.ts"));
+            server.watcher.on("add", (file) => {
+                if (isRouteFile(file)) {
+                    pageMatcher = null;
+                    endpointMatcher = null;
+                    server.config.logger.info(`[catmint] Route file added: ${file} — invalidating route cache`);
+                }
+            });
+            server.watcher.on("unlink", (file) => {
+                if (isRouteFile(file)) {
+                    pageMatcher = null;
+                    endpointMatcher = null;
+                    server.config.logger.info(`[catmint] Route file removed: ${file} — invalidating route cache`);
+                }
+            });
             return () => {
                 server.middlewares.use(async (req, res, next) => {
                     const url = req.originalUrl ?? req.url ?? "/";
@@ -919,142 +1315,222 @@ export function devServerPlugin(options) {
                     if (shouldSkip(url)) {
                         return next();
                     }
-                    // --- Server function RPC handling ---
-                    const pathname = url.split("?")[0];
-                    if (pathname.startsWith(SERVER_FN_PREFIX)) {
+                    // --- Establish request context for all server-side handlers ---
+                    // This enables cookies(), headers(), getPlatform() during dev.
+                    const webRequest = nodeReqToWebRequest(req);
+                    // Ensure runtime context APIs are loaded before first use
+                    const contextReady = server.__catmintContextReady;
+                    if (contextReady) {
+                        await contextReady;
+                    }
+                    // Wait for adapter dev platform initialization if still pending
+                    const initPromise = server.__catmintDevPlatformInit;
+                    if (initPromise && !devPlatform) {
                         try {
-                            await handleServerFn(server, req, res, pathname);
+                            devPlatform = await initPromise;
                         }
-                        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" }));
-                            }
+                        catch {
+                            // Already logged during init
                         }
-                        return;
                     }
-                    // --- RSC flight stream for client-side navigation ---
-                    if (pathname === RSC_NAVIGATION_PREFIX) {
+                    // Get platform context from adapter (e.g. Cloudflare { env, ctx })
+                    // or fall back to Node.js platform shape
+                    let platform;
+                    if (devPlatform) {
                         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);
+                            platform = await devPlatform.getPlatform(webRequest, req, res);
                         }
-                        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" }));
-                            }
+                        catch (err) {
+                            server.config.logger.warn(`[catmint] Adapter getPlatform() failed, falling back to Node.js platform: ${err instanceof Error ? err.message : String(err)}`);
+                            platform = { req, res };
                         }
-                        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;
+                    else {
+                        platform = { req, res };
+                    }
+                    const store = createRequestStore(webRequest, platform);
+                    /**
+                     * Flush pending Set-Cookie headers and accumulated response headers
+                     * onto the Node.js ServerResponse before it's sent.
+                     */
+                    const flushHeaders = () => {
+                        if (res.headersSent)
+                            return;
+                        store.responseHeaders.forEach((value, key) => {
+                            res.setHeader(key, value);
+                        });
+                        for (const pending of store.pendingCookies.values()) {
+                            res.appendHeader("Set-Cookie", pending.serialized);
+                        }
+                    };
+                    return runWithRequestContext(store, async () => {
+                        // --- Server function RPC handling ---
+                        const pathname = url.split("?")[0];
+                        if (pathname.startsWith(SERVER_FN_PREFIX)) {
+                            try {
+                                await handleServerFn(server, req, res, pathname);
                             }
-                            if (hasHandler) {
-                                return await handleEndpoint(server, req, res, endpointMatch, method);
+                            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" }));
+                                }
                             }
-                            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`);
+                            flushHeaders();
                             return;
                         }
-                        // --- Page handling (GET only) ---
-                        if (method !== "GET") {
-                            return next();
-                        }
-                        const match = pageMatcher.matchRoute(url);
-                        if (!match) {
-                            await sendStatusPage(res, 404, url);
+                        // --- 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;
+                                }
+                                // Execute middleware for the TARGET page path (not /__catmint/rsc)
+                                const middlewareResult = await executeMiddleware(server, req, match.route.filePath, appDir);
+                                if (middlewareResult.shortCircuit) {
+                                    // Middleware short-circuited (e.g., returned 401)
+                                    flushHeaders();
+                                    await sendWebResponse(res, middlewareResult.shortCircuit);
+                                    return;
+                                }
+                                // Apply middleware response headers (e.g., X-Response-Time)
+                                middlewareResult.headers.forEach((value, key) => {
+                                    res.setHeader(key, value);
+                                });
+                                flushHeaders();
+                                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;
                         }
-                        // 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);
+                        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) {
+                                    flushHeaders();
+                                    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;
+                            }
+                            // --- Execute middleware chain for this route ---
+                            const routeDir = dirname(match.route.filePath);
+                            const middlewareResult = await executeMiddleware(server, req, match.route.filePath, appDir);
+                            if (middlewareResult.shortCircuit) {
+                                // Middleware short-circuited (e.g., returned 401)
+                                flushHeaders();
+                                await sendWebResponse(res, middlewareResult.shortCircuit);
+                                return;
+                            }
+                            // Apply middleware response headers (e.g., X-Response-Time)
+                            // These will be set on the response before page rendering streams
+                            middlewareResult.headers.forEach((value, key) => {
+                                res.setHeader(key, value);
+                            });
+                            // Flush pending cookie/response headers before page rendering
+                            flushHeaders();
+                            // 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);
                             }
                         }
-                        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),
-                                });
+                        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) {
+                                    flushHeaders();
+                                    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),
+                                    });
+                                }
                             }
                         }
-                    }
+                    }); // end runWithRequestContext
                 });
             };
         },
         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"))) {
+                    file.endsWith("endpoint.ts"))) {
                 pageMatcher = null;
                 endpointMatcher = null;
             }
@@ -1064,7 +1540,7 @@ export function devServerPlugin(options) {
             // 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)) {
+                if (/^\d{3}\.(tsx|ts)$/.test(basename)) {
                     statusPages = scanStatusPages(appDir);
                     hmrServer.config.logger.info(`[catmint] Status page changed: ${basename} — triggering reload`);
                     hmrServer.hot.send({ type: "full-reload", path: "*" });
@@ -1144,7 +1620,11 @@ async function handlePageWithRsc(server, req, res, match, appDir, softNavigation
     // 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);
+    const pageProps = {};
+    if (match.params && Object.keys(match.params).length > 0) {
+        pageProps.params = match.params;
+    }
+    let element = createElement(PageComponent, Object.keys(pageProps).length > 0 ? pageProps : null);
     // Resolve loading.tsx from the page directory for Suspense fallback
     const loadingPath = resolveLoadingComponent(match.route.filePath);
     if (loadingPath) {
@@ -1172,10 +1652,24 @@ async function handlePageWithRsc(server, req, res, match, appDir, softNavigation
         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 });
+            const ErrorFallbackComponent = errorMod.default;
+            if (ErrorFallbackComponent) {
+                // Import the ErrorBoundary class component to properly catch errors
+                const errorBoundaryMod = await rscEnv.runner.import("catmint/error");
+                const ErrorBoundary = errorBoundaryMod.ErrorBoundary ??
+                    errorBoundaryMod.default?.ErrorBoundary;
+                if (ErrorBoundary) {
+                    element = createElement(ErrorBoundary, {
+                        fallback: ErrorFallbackComponent,
+                        children: element,
+                    });
+                }
+                else {
+                    // Fallback: wrap page with error fallback component directly
+                    element = createElement(ErrorFallbackComponent, {
+                        children: element,
+                    });
+                }
             }
         }
         catch {
@@ -1348,7 +1842,11 @@ async function handleRscNavigation(server, _req, res, match, appDir, i18nConfig
     // 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);
+    const navPageProps = {};
+    if (match.params && Object.keys(match.params).length > 0) {
+        navPageProps.params = match.params;
+    }
+    let element = createElement(PageComponent, Object.keys(navPageProps).length > 0 ? navPageProps : null);
     // Resolve loading.tsx from the page directory for Suspense fallback
     const loadingPath = resolveLoadingComponent(match.route.filePath);
     if (loadingPath) {
@@ -1376,10 +1874,24 @@ async function handleRscNavigation(server, _req, res, match, appDir, i18nConfig
         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 });
+            const ErrorFallbackComponent = errorMod.default;
+            if (ErrorFallbackComponent) {
+                // Import the ErrorBoundary class component to properly catch errors
+                const errorBoundaryMod = await rscEnv.runner.import("catmint/error");
+                const ErrorBoundary = errorBoundaryMod.ErrorBoundary ??
+                    errorBoundaryMod.default?.ErrorBoundary;
+                if (ErrorBoundary) {
+                    element = createElement(ErrorBoundary, {
+                        fallback: ErrorFallbackComponent,
+                        children: element,
+                    });
+                }
+                else {
+                    // Fallback: wrap page with error fallback component directly
+                    element = createElement(ErrorFallbackComponent, {
+                        children: element,
+                    });
+                }
             }
         }
         catch {
@@ -1459,7 +1971,9 @@ async function handlePageLegacy(server, _req, res, match, appDir, hydrScripts, h
     }
     // Resolve generateMetadata exports from page + layout modules
     const headConfig = await resolveGenerateMetadata(pageMod, layoutMods, match.params ?? {}, url);
-    let element = React.createElement(PageComponent, null);
+    let element = React.createElement(PageComponent, match.params && Object.keys(match.params).length > 0
+        ? { params: match.params }
+        : null);
     for (let i = layoutComponents.length - 1; i >= 0; i--) {
         element = React.createElement(layoutComponents[i], null, element);
     }
@@ -1629,6 +2143,31 @@ hydrate().then(() => {
     setupClientNavigation(root);
   }
 });
+
+// HMR: When server components (page.tsx, layout.tsx) are edited, the RSC
+// plugin sends an "rsc:update" event.  Re-fetch the flight stream for the
+// current page and re-render so the update appears without a full reload.
+if (import.meta.hot) {
+  import.meta.hot.on("rsc:update", async () => {
+    if (!root) return;
+    try {
+      var rscUrl = "/__catmint/rsc?path=" + encodeURIComponent(
+        window.location.pathname + window.location.search
+      );
+      var response = await fetch(rscUrl);
+      if (!response.ok) {
+        window.location.reload();
+        return;
+      }
+      var { createFromReadableStream } = await import("@vitejs/plugin-rsc/browser");
+      var newRoot = await createFromReadableStream(response.body);
+      root.render(newRoot);
+    } catch (err) {
+      console.error("[catmint] HMR update failed, reloading:", err);
+      window.location.reload();
+    }
+  });
+}
 `;
 }
 // --------------------------------------------------------------------------