rouzer 3.0.2 → 3.2.0

package/dist/response.d.ts

@@ -0,0 +1,49 @@
+import type { Promisable } from './common.js';
+import type { RouteRequest } from './types/request.js';
+/** Runtime key carried by response plugin markers. */
+export declare const responsePluginMarker: unique symbol;
+/**
+ * Compile-time response marker handled by a client/router response plugin pair.
+ *
+ * @remarks `TClient` is the value returned by generated client action
+ * functions. `TRouter` is the non-`Response` value accepted from route handlers.
+ * Plugin markers may be used directly as an action response or as success
+ * entries in a status-keyed response map.
+ */
+export type ResponsePluginMarker<TClient, TRouter = TClient, TId extends string = string> = Record<number, unknown> & {
+    readonly [responsePluginMarker]: {
+        readonly id: TId;
+        readonly client: TClient;
+        readonly router: TRouter;
+    };
+};
+/** Client-side response plugin used by `createClient({ plugins })`. */
+export type ClientResponsePlugin = {
+    /** Stable response codec id matched against route response markers. */
+    readonly id: string;
+    /** Decode a successful `Response` into the client action result. */
+    decode(response: Response, context: {
+        marker: ResponsePluginMarker<any, any>;
+        request: RouteRequest;
+    }): Promisable<unknown>;
+};
+/** Router-side response plugin used by `createRouter({ plugins })`. */
+export type RouterResponsePlugin = {
+    /** Stable response codec id matched against route response markers. */
+    readonly id: string;
+    /** Encode a handler result into the HTTP response. */
+    encode(value: unknown, context: {
+        marker: ResponsePluginMarker<any, any>;
+        request: Request;
+    }): Promisable<Response>;
+};
+/** Create a response marker for a response plugin. */
+export declare function createResponsePluginMarker<TClient, TRouter = TClient, const TId extends string = string>(id: TId): ResponsePluginMarker<TClient, TRouter, TId>;
+/** Get the response plugin id from a plugin marker, if present. */
+export declare function getResponsePluginMarkerId(value: unknown): string | undefined;
+/** Return true when a route response marker is handled by a response plugin. */
+export declare function isResponsePluginMarker(value: unknown): value is ResponsePluginMarker<unknown, unknown>;
+/** Create a plugin lookup map and reject duplicate plugin ids. */
+export declare function createResponsePluginMap<TPlugin extends {
+    readonly id: string;
+}>(plugins?: readonly TPlugin[], label?: string): Map<string, TPlugin>;

package/dist/response.js

@@ -0,0 +1,33 @@
+/** Runtime key carried by response plugin markers. */
+export const responsePluginMarker = Symbol.for('rouzer.response-plugin');
+/** Create a response marker for a response plugin. */
+export function createResponsePluginMarker(id) {
+    return {
+        [responsePluginMarker]: {
+            id,
+            client: undefined,
+            router: undefined,
+        },
+    };
+}
+/** Get the response plugin id from a plugin marker, if present. */
+export function getResponsePluginMarkerId(value) {
+    return isResponsePluginMarker(value)
+        ? value[responsePluginMarker].id
+        : undefined;
+}
+/** Return true when a route response marker is handled by a response plugin. */
+export function isResponsePluginMarker(value) {
+    return (typeof value === 'object' && value !== null && responsePluginMarker in value);
+}
+/** Create a plugin lookup map and reject duplicate plugin ids. */
+export function createResponsePluginMap(plugins = [], label = 'response') {
+    const map = new Map();
+    for (const plugin of plugins) {
+        if (map.has(plugin.id)) {
+            throw new Error(`Duplicate ${label} plugin: ${plugin.id}`);
+        }
+        map.set(plugin.id, plugin);
+    }
+    return map;
+}

package/dist/server/router.d.ts

@@ -1,6 +1,7 @@
 import type { HattipHandler } from '@hattip/core';
 import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
 import type { HttpRouteTree } from '../http.js';
+import { type RouterResponsePlugin } from '../response.js';
 import type { RouteRequestHandlerMap } from '../types/server.js';
 export { chain };
 /** Configuration for `createRouter`. */
@@ -25,6 +26,8 @@ export type RouterConfig = {
      * and logs missing route handlers to the console.
      */
     debug?: boolean;
+    /** Response codec plugins used for route handler results. */
+    plugins?: readonly RouterResponsePlugin[];
     /** CORS configuration for requests with an `Origin` header. */
     cors?: {
         /**
@@ -67,8 +70,8 @@ export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T
 /**
  * Create a Rouzer router that can be mounted by any Hattip adapter.
  *
- * @param config Optional router configuration for base path, debug behavior, and
- * CORS origin restrictions.
+ * @param config Optional router configuration for base path, debug behavior,
+ * response plugins, and CORS origin restrictions.
  * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */

package/dist/server/router.js

@@ -3,15 +3,19 @@ import { createMatcher } from '@remix-run/route-pattern/match';
 import { chain, MiddlewareChain, } from 'alien-middleware';
 import * as z from 'zod';
 import { mapValues } from '../common.js';
+import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
+import { getDefaultSuccessStatus, getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
 export { chain };
 // Internal prototype for the router instance.
 class RouterObject extends MiddlewareChain {
     config;
     basePath;
+    responsePlugins;
     constructor(config) {
         super();
         this.config = config;
         this.basePath = config.basePath?.replace(/\/?$/, '/');
+        this.responsePlugins = createResponsePluginMap(config.plugins, 'router response');
         const allowOrigins = config.cors?.allowOrigins?.map(createOriginPattern);
         if (allowOrigins) {
             super.use(((ctx) => {
@@ -31,14 +35,15 @@ class RouterObject extends MiddlewareChain {
     }
     /** @internal */
     useRoutes(routeSchemas, handlers) {
-        const { config, basePath } = this;
+        const { config, basePath, responsePlugins } = this;
         const routes = flattenRoutes(routeSchemas, handlers, basePath ?? '', config.debug);
+        validateRouterResponsePlugins(routes, responsePlugins);
         const addDebugHeaders = config.debug
             ? (context, route) => {
                 context.setHeader('X-Route-Name', route.name);
             }
             : null;
-        return super.use((async function (context) {
+        return super.use(async function (context) {
             const request = context.request;
             const origin = request.headers.get('Origin');
             const url = (context.url ??= new URL(request.url));
@@ -105,21 +110,41 @@ class RouterObject extends MiddlewareChain {
                         return httpClientError(error, 'Invalid request body', config);
                     }
                 }
+                if (isResponseMap(schema.response)) {
+                    ;
+                    context.error = createResponseHelper(schema.response, request, responsePlugins, true);
+                    context.success = createResponseHelper(schema.response, request, responsePlugins, false);
+                }
                 const result = await handler(context);
                 addDebugHeaders?.(context, route);
                 if (result instanceof Response) {
                     return result;
                 }
+                const pluginId = getResponsePluginMarkerId(schema.response);
+                if (pluginId) {
+                    const plugin = responsePlugins.get(pluginId);
+                    if (!plugin) {
+                        throw missingRouterResponsePlugin(pluginId);
+                    }
+                    return plugin.encode(result, {
+                        marker: schema.response,
+                        request,
+                    });
+                }
+                if (isResponseMap(schema.response)) {
+                    const status = getDefaultSuccessStatus(schema.response);
+                    return encodeResponseMapResult(schema.response, status, result, request, responsePlugins);
+                }
                 return Response.json(result);
             }
-        }));
+        });
     }
 }
 /**
  * Create a Rouzer router that can be mounted by any Hattip adapter.
  *
- * @param config Optional router configuration for base path, debug behavior, and
- * CORS origin restrictions.
+ * @param config Optional router configuration for base path, debug behavior,
+ * response plugins, and CORS origin restrictions.
  * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */
@@ -152,6 +177,21 @@ function flattenRoutes(tree, handlers, prefix, debug) {
     }
     return routes;
 }
+function validateRouterResponsePlugins(routes, plugins) {
+    for (const route of routes) {
+        const pluginIds = isResponseMap(route.schema.response)
+            ? getResponseMapPluginIds(route.schema.response)
+            : [getResponsePluginMarkerId(route.schema.response)].filter(pluginId => pluginId !== undefined);
+        for (const pluginId of pluginIds) {
+            if (!plugins.has(pluginId)) {
+                throw missingRouterResponsePlugin(pluginId);
+            }
+        }
+    }
+}
+function missingRouterResponsePlugin(pluginId) {
+    return new Error(`Missing router response plugin for ${pluginId}`);
+}
 function joinPaths(left, right) {
     return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
 }
@@ -252,3 +292,39 @@ function createOriginPattern(origin) {
     }
     return new ExactPattern(origin);
 }
+/** Create `ctx.error(status, body)` or `ctx.success(status, body)`. */
+function createResponseHelper(responseMap, request, responsePlugins, error) {
+    return (status, body) => {
+        const marker = responseMap[status];
+        if (!marker || isErrorMarker(marker) !== error) {
+            throw new Error(`Undeclared ${error ? 'error' : 'success'} response status: ${status}`);
+        }
+        return encodeResponseMapResult(responseMap, status, body, request, responsePlugins);
+    };
+}
+async function encodeResponseMapResult(responseMap, status, value, request, responsePlugins) {
+    const marker = responseMap[status];
+    if (!marker) {
+        throw new Error(`Undeclared response status: ${status}`);
+    }
+    if (isErrorMarker(marker)) {
+        return Response.json(value, { status });
+    }
+    const pluginId = getResponsePluginMarkerId(marker);
+    if (!pluginId) {
+        return Response.json(value, { status });
+    }
+    const plugin = responsePlugins.get(pluginId);
+    if (!plugin) {
+        throw missingRouterResponsePlugin(pluginId);
+    }
+    const response = await plugin.encode(value, {
+        marker: marker,
+        request,
+    });
+    return new Response(response.body, {
+        status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}

package/dist/type.d.ts

@@ -1,10 +1,13 @@
-import { Unchecked } from './common.js';
+import type { Unchecked, UncheckedError } from './common.js';
 /**
  * Create a compile-time-only marker for an action's JSON response payload type.
  *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client action functions for HTTP actions
- * whose responses are expected to be JSON.
+ * @remarks `$type<T>()` does not validate handler return values at the server
+ * boundary. It lets Rouzer type server handler return values and client action
+ * functions for HTTP actions whose responses are expected to be JSON. Use it
+ * directly as `response` for one JSON success shape, or as a success entry in a
+ * status-keyed response map. Validate response data where it enters your server
+ * or client code when runtime integrity is required.
  *
  * @example
  * ```ts
@@ -20,3 +23,29 @@ export declare function $type<T>(): Unchecked<T>;
 export declare namespace $type {
     var symbol: symbol;
 }
+/**
+ * Create a compile-time-only marker for a declared error response type.
+ *
+ * @remarks `$error<T>()` marks a non-success response branch in a status-keyed
+ * response map. It is a type contract, not a runtime validator. On the server,
+ * handlers use `ctx.error(status, body)` to return declared errors. On the
+ * client, declared error responses resolve as `[error, null, status]` tuple
+ * entries instead of rejecting the promise.
+ *
+ * @example
+ * ```ts
+ * import { $type, $error } from 'rouzer'
+ * import * as http from 'rouzer/http'
+ *
+ * const getUser = http.get('users/:id', {
+ *   response: {
+ *     200: $type<User>(),
+ *     404: $error<{ code: string; message: string }>(),
+ *   },
+ * })
+ * ```
+ */
+export declare function $error<T>(): UncheckedError<T>;
+export declare namespace $error {
+    var symbol: symbol;
+}

package/dist/type.js

@@ -1,9 +1,12 @@
 /**
  * Create a compile-time-only marker for an action's JSON response payload type.
  *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client action functions for HTTP actions
- * whose responses are expected to be JSON.
+ * @remarks `$type<T>()` does not validate handler return values at the server
+ * boundary. It lets Rouzer type server handler return values and client action
+ * functions for HTTP actions whose responses are expected to be JSON. Use it
+ * directly as `response` for one JSON success shape, or as a success entry in a
+ * status-keyed response map. Validate response data where it enters your server
+ * or client code when runtime integrity is required.
  *
  * @example
  * ```ts
@@ -19,3 +22,29 @@ export function $type() {
     return $type.symbol;
 }
 $type.symbol = Symbol();
+/**
+ * Create a compile-time-only marker for a declared error response type.
+ *
+ * @remarks `$error<T>()` marks a non-success response branch in a status-keyed
+ * response map. It is a type contract, not a runtime validator. On the server,
+ * handlers use `ctx.error(status, body)` to return declared errors. On the
+ * client, declared error responses resolve as `[error, null, status]` tuple
+ * entries instead of rejecting the promise.
+ *
+ * @example
+ * ```ts
+ * import { $type, $error } from 'rouzer'
+ * import * as http from 'rouzer/http'
+ *
+ * const getUser = http.get('users/:id', {
+ *   response: {
+ *     200: $type<User>(),
+ *     404: $error<{ code: string; message: string }>(),
+ *   },
+ * })
+ * ```
+ */
+export function $error() {
+    return $error.symbol;
+}
+$error.symbol = Symbol();

package/dist/types/handler.d.ts

@@ -3,11 +3,41 @@ import type { AnyMiddlewareChain, MiddlewareContext } from 'alien-middleware';
 import type * as z from 'zod';
 import { Promisable } from '../common.js';
 import type { HttpAction } from '../http.js';
-import type { InferRouteResponse } from './response.js';
-import type { RouteSchema } from './schema.js';
+import type { InferRouteHandlerResult, InferResponseMapErrors, InferResponseMapSuccesses } from './response.js';
+import type { RouteResponseMap, RouteSchema } from './schema.js';
 type RequestContext<TMiddleware extends AnyMiddlewareChain> = MiddlewareContext<TMiddleware>;
-export type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult> = (context: RequestContext<TMiddleware> & TArgs) => Promisable<TResult | Response>;
-export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction extends HttpAction, TPath extends string> = TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
+/**
+ * Error response returned by `ctx.error(status, body)` in route handlers.
+ *
+ * @remarks This is an opaque branded type returned by the error helper. Route
+ * handlers may return it to signal a declared error response.
+ */
+export type RouteErrorResponse = Response & {
+    __routeError__: true;
+};
+/** Response returned by `ctx.success(status, body)` in route handlers. */
+export type RouteSuccessResponse = Response & {
+    __routeSuccess__: true;
+};
+export type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult, TErrors = never, TSuccesses = never> = (context: RequestContext<TMiddleware> & TArgs & ([TErrors] extends [never] ? {} : {
+    /**
+     * Return a declared error response.
+     *
+     * @remarks Only statuses declared with `$error<T>()` in the response
+     * map are accepted.
+     */
+    error: <TEntry extends TErrors>(...args: TEntry extends [infer S extends number, infer B] ? [status: S, body: B] : never) => RouteErrorResponse;
+}) & ([TSuccesses] extends [never] ? {} : {
+    /**
+     * Return a declared success response with an explicit status.
+     *
+     * @remarks Useful when a response map declares multiple 2xx statuses.
+     */
+    success: <TEntry extends TSuccesses>(...args: TEntry extends [infer S extends number, infer B] ? [status: S, body: B] : never) => RouteSuccessResponse;
+})) => Promisable<TResult | Response>;
+export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction extends HttpAction, TPath extends string> = TAction['schema'] extends {
+    response: infer R extends RouteResponseMap;
+} ? TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
@@ -17,7 +47,7 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;
-}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>> : RouteRequestHandler<TMiddleware, {
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>, InferResponseMapErrors<R>, InferResponseMapSuccesses<R>> : RouteRequestHandler<TMiddleware, {
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
@@ -27,5 +57,25 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;
-}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>>;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>, InferResponseMapErrors<R>, InferResponseMapSuccesses<R>> : TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
+        path: any;
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    query: TAction['schema'] extends {
+        query: any;
+    } ? z.infer<TAction['schema']['query']> : undefined;
+    headers: TAction['schema'] extends {
+        headers: any;
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>> : RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
+        path: any;
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    body: TAction['schema'] extends {
+        body: any;
+    } ? z.infer<TAction['schema']['body']> : undefined;
+    headers: TAction['schema'] extends {
+        headers: any;
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>>;
 export {};

package/dist/types/request.d.ts

@@ -30,6 +30,6 @@ export type RouteRequestFactory<T extends RouteSchema, P extends string> = {
     (...p: RouteArgs<T, P> extends infer TArgs ? {} extends TArgs ? [args?: TArgs] : [args: TArgs] : never): RouteRequest<InferRouteResponse<T>>;
     /** Inferred argument type for this request factory. */
     $args: RouteArgs<T, P>;
-    /** Inferred JSON response type for this request factory. */
+    /** Inferred response type for this request factory. */
     $response: InferRouteResponse<T>;
 };

package/dist/types/response.d.ts

@@ -1,9 +1,57 @@
-import type { Unchecked, RouteSchema } from './schema.js';
+import type { Unchecked, UncheckedError } from '../common.js';
+import type { ResponsePluginMarker } from '../response.js';
+import type { RouteResponseMap, RouteSchema } from './schema.js';
 /** `Response` whose `.json()` method resolves to a known payload type. */
 export type RouteResponse<TResult = any> = Response & {
     json(): Promise<TResult>;
 };
-/** Infer the JSON response payload type from an action schema. */
+/**
+ * Helper: given a status-keyed response map, produce the discriminated tuple
+ * union for the client.
+ *
+ * Each entry becomes:
+ * - `$type<T>()` → `[null, T, Status]`
+ * - `$error<T>()` → `[T, null, Status]`
+ */
+type InferResponseMapClient<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends UncheckedError<infer TError> ? [TError, null, K] : T[K] extends Unchecked<infer TSuccess> ? [null, TSuccess, K] : T[K] extends ResponsePluginMarker<infer TClient, any> ? [null, TClient, K] : never;
+}[keyof T & number];
+/**
+ * Infer the generated client action result type from an action schema.
+ *
+ * @remarks Direct JSON markers infer their payload type, plugin markers infer
+ * their client result type, and status-keyed response maps infer a tuple union
+ * of `[null, value, status]` success entries and `[error, null, status]` error
+ * entries.
+ */
 export type InferRouteResponse<T extends RouteSchema> = T extends {
-    response: Unchecked<infer TResponse>;
-} ? TResponse : void;
+    response: infer R;
+} ? R extends ResponsePluginMarker<infer TClient, any> ? TClient : R extends Unchecked<infer TResponse> ? TResponse : R extends RouteResponseMap ? InferResponseMapClient<R> : void : void;
+/**
+ * Helper: given a status-keyed response map, produce the union of handler
+ * result types (success values the handler can return directly).
+ */
+type InferResponseMapHandlerResult<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends Unchecked<infer TSuccess> ? TSuccess : T[K] extends ResponsePluginMarker<any, infer TRouter> ? TRouter : never;
+}[keyof T & number];
+/**
+ * Infer the non-`Response` handler result type from an action schema.
+ *
+ * @remarks For status-keyed response maps, this includes only success result
+ * values. Declared error responses are returned with `ctx.error(status, body)`.
+ */
+export type InferRouteHandlerResult<T extends RouteSchema> = T extends {
+    response: infer R;
+} ? R extends ResponsePluginMarker<any, infer TRouter> ? TRouter : R extends Unchecked<infer TResponse> ? TResponse : R extends RouteResponseMap ? InferResponseMapHandlerResult<R> : void : void;
+/**
+ * Helper: given a status-keyed response map, extract error entries as a union
+ * of `[status, body]` pairs for typing `ctx.error(status, body)`.
+ */
+export type InferResponseMapErrors<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends UncheckedError<infer TError> ? [K, TError] : never;
+}[keyof T & number];
+/** Extract success entries as a union of `[status, body]` pairs. */
+export type InferResponseMapSuccesses<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends Unchecked<infer TSuccess> ? [K, TSuccess] : T[K] extends ResponsePluginMarker<any, infer TRouter> ? [K, TRouter] : never;
+}[keyof T & number];
+export {};

package/dist/types/schema.d.ts

@@ -1,12 +1,28 @@
 import * as z from 'zod';
-import { Unchecked } from '../common.js';
+import type { Unchecked, UncheckedError } from '../common.js';
+import type { ResponsePluginMarker } from '../response.js';
 /**
- * Compile-time-only marker used by `$type<T>()` for unchecked response types.
+ * Compile-time-only marker used by `$type<T>()` for unchecked JSON response
+ * types.
  *
  * @remarks Application code should usually call `$type<T>()` instead of naming
  * this marker directly.
  */
-export type { Unchecked };
+export type { ResponsePluginMarker, Unchecked, UncheckedError };
+/** Single response marker accepted by status-keyed response maps. */
+export type RouteResponseMarker = Unchecked<any> | UncheckedError<any> | ResponsePluginMarker<any, any>;
+/**
+ * Status-keyed response map for declaring multiple response types.
+ *
+ * @remarks Numeric keys are HTTP status codes. Use `$type<T>()` or a response
+ * plugin marker for success responses and `$error<T>()` for declared error
+ * JSON responses.
+ */
+export type RouteResponseMap = {
+    [status: number]: RouteResponseMarker;
+};
+/** Response marker accepted by HTTP action schemas. */
+export type RouteResponseSchema = Unchecked<any> | ResponsePluginMarker<any, any> | RouteResponseMap;
 /** Schema shape for `GET` route methods. */
 export type QueryRouteSchema = {
     /** Optional Zod object used to validate path params. */
@@ -17,8 +33,8 @@ export type QueryRouteSchema = {
     body?: never;
     /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
-    /** Optional compile-time-only JSON response type marker. */
-    response?: Unchecked<any>;
+    /** Optional compile-time-only JSON or plugin response type marker. */
+    response?: RouteResponseSchema;
 };
 /** Schema shape for mutation route methods. */
 export type MutationRouteSchema = {
@@ -30,8 +46,8 @@ export type MutationRouteSchema = {
     body?: z.ZodType<any, any>;
     /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
-    /** Optional compile-time-only JSON response type marker. */
-    response?: Unchecked<any>;
+    /** Optional compile-time-only JSON or plugin response type marker. */
+    response?: RouteResponseSchema;
 };
 /** Any HTTP action schema Rouzer can execute. */
 export type RouteSchema = QueryRouteSchema | MutationRouteSchema;