shokupan 0.0.1 → 0.2.0

package/dist/index.js

@@ -1,24 +1,25 @@
-import { trace, SpanKind, SpanStatusCode, context } from "@opentelemetry/api";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { Eta } from "eta";
 import { stat, readdir } from "fs/promises";
 import { resolve, join, basename } from "path";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { trace, SpanKind, SpanStatusCode, context } from "@opentelemetry/api";
 import { OAuth2Client, Okta, Auth0, Apple, MicrosoftEntraId, Google, GitHub, generateState, generateCodeVerifier } from "arctic";
 import * as jose from "jose";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { plainToInstance } from "class-transformer";
+import { validateOrReject } from "class-validator";
+import { OpenAPIAnalyzer } from "./openapi-analyzer-BTExMLX4.js";
 import { randomUUID, createHmac } from "crypto";
 import { EventEmitter } from "events";
 class ShokupanResponse {
-  _headers = new Headers();
+  _headers = null;
   _status = 200;
   /**
    * Get the current headers
    */
   get headers() {
+    if (!this._headers) this._headers = new Headers();
     return this._headers;
   }
   /**
@@ -39,6 +40,7 @@ class ShokupanResponse {
    * @param value Header value
    */
   set(key, value) {
+    if (!this._headers) this._headers = new Headers();
     this._headers.set(key, value);
     return this;
   }
@@ -48,6 +50,7 @@ class ShokupanResponse {
    * @param value Header value
    */
   append(key, value) {
+    if (!this._headers) this._headers = new Headers();
     this._headers.append(key, value);
     return this;
   }
@@ -56,27 +59,58 @@ class ShokupanResponse {
    * @param key Header name
    */
   get(key) {
-    return this._headers.get(key);
+    return this._headers?.get(key) || null;
   }
   /**
    * Check if a header exists
    * @param key Header name
    */
   has(key) {
-    return this._headers.has(key);
+    return this._headers?.has(key) || false;
+  }
+  /**
+   * Internal: check if headers have been initialized/modified
+   */
+  get hasPopulatedHeaders() {
+    return this._headers !== null;
   }
 }
 class ShokupanContext {
-  constructor(request, state) {
+  constructor(request, server, state, app, enableMiddlewareTracking = false) {
     this.request = request;
-    this.url = new URL(request.url);
+    this.server = server;
+    this.app = app;
     this.state = state || {};
+    if (enableMiddlewareTracking) {
+      const self = this;
+      this.state = new Proxy(this.state, {
+        set(target, p, newValue, receiver) {
+          const result = Reflect.set(target, p, newValue, receiver);
+          const currentHandler = self.handlerStack[self.handlerStack.length - 1];
+          if (currentHandler) {
+            if (!currentHandler.stateChanges) currentHandler.stateChanges = {};
+            currentHandler.stateChanges[p] = newValue;
+          }
+          return result;
+        }
+      });
+    }
     this.response = new ShokupanResponse();
   }
-  url;
+  _url;
   params = {};
+  // Router assigns this, but default to empty object
   state;
+  handlerStack = [];
   response;
+  _finalResponse;
+  get url() {
+    if (!this._url) {
+      const urlString = this.request.url || "http://localhost/";
+      this._url = new URL(urlString);
+    }
+    return this._url;
+  }
   /**
    * Base request
    */
@@ -93,7 +127,26 @@ class ShokupanContext {
    * Request path
    */
   get path() {
-    return this.url.pathname;
+    if (this._url) return this._url.pathname;
+    const url = this.request.url;
+    let queryIndex = url.indexOf("?");
+    const end = queryIndex === -1 ? url.length : queryIndex;
+    let start = 0;
+    const protocolIndex = url.indexOf("://");
+    if (protocolIndex !== -1) {
+      const hostStart = protocolIndex + 3;
+      const pathStart = url.indexOf("/", hostStart);
+      if (pathStart !== -1 && pathStart < end) {
+        start = pathStart;
+      } else {
+        return "/";
+      }
+    } else {
+      if (url.charCodeAt(0) === 47) {
+        start = 0;
+      }
+    }
+    return url.substring(start, end);
   }
   /**
    * Request query params
@@ -101,12 +154,55 @@ class ShokupanContext {
   get query() {
     return Object.fromEntries(this.url.searchParams);
   }
+  /**
+   * Client IP address
+   */
+  get ip() {
+    return this.server?.requestIP(this.request);
+  }
+  /**
+   * Request hostname (e.g. "localhost")
+   */
+  get hostname() {
+    return this.url.hostname;
+  }
+  /**
+   * Request host (e.g. "localhost:3000")
+   */
+  get host() {
+    return this.url.host;
+  }
+  /**
+   * Request protocol (e.g. "http:", "https:")
+   */
+  get protocol() {
+    return this.url.protocol;
+  }
+  /**
+   * Whether request is secure (https)
+   */
+  get secure() {
+    return this.url.protocol === "https:";
+  }
+  /**
+   * Request origin (e.g. "http://localhost:3000")
+   */
+  get origin() {
+    return this.url.origin;
+  }
   /**
    * Request headers
    */
   get headers() {
     return this.request.headers;
   }
+  /**
+   * Get a request header
+   * @param name Header name
+   */
+  get(name) {
+    return this.request.headers.get(name);
+  }
   /**
    * Base response object
    */
@@ -115,6 +211,8 @@ class ShokupanContext {
   }
   /**
    * Helper to set a header on the response
+   * @param key Header key
+   * @param value Header value
    */
   set(key, value) {
     this.response.set(key, value);
@@ -145,9 +243,25 @@ class ShokupanContext {
     return this;
   }
   mergeHeaders(headers) {
-    const h = new Headers(this.response.headers);
+    let h;
+    if (this.response.hasPopulatedHeaders) {
+      h = new Headers(this.response.headers);
+    } else {
+      h = new Headers();
+    }
     if (headers) {
-      new Headers(headers).forEach((v, k) => h.set(k, v));
+      if (headers instanceof Headers) {
+        headers.forEach((v, k) => h.set(k, v));
+      } else if (Array.isArray(headers)) {
+        headers.forEach(([k, v]) => h.set(k, v));
+      } else {
+        const keys = Object.keys(headers);
+        for (let i = 0; i < keys.length; i++) {
+          const key = keys[i];
+          const val = headers[key];
+          h.set(key, val);
+        }
+      }
     }
     return h;
   }
@@ -160,7 +274,8 @@ class ShokupanContext {
   send(body, options) {
     const headers = this.mergeHeaders(options?.headers);
     const status = options?.status ?? this.response.status;
-    return new Response(body, { status, headers });
+    this._finalResponse = new Response(body, { status, headers });
+    return this._finalResponse;
   }
   /**
    * Read request body
@@ -179,19 +294,36 @@ class ShokupanContext {
    * Respond with a JSON object
    */
   json(data, status, headers) {
+    const finalStatus = status ?? this.response.status;
+    const jsonString = JSON.stringify(data);
+    if (!headers && !this.response.hasPopulatedHeaders) {
+      this._finalResponse = new Response(jsonString, {
+        status: finalStatus,
+        headers: { "content-type": "application/json" }
+      });
+      return this._finalResponse;
+    }
     const finalHeaders = this.mergeHeaders(headers);
     finalHeaders.set("content-type", "application/json");
-    const finalStatus = status ?? this.response.status;
-    return new Response(JSON.stringify(data), { status: finalStatus, headers: finalHeaders });
+    this._finalResponse = new Response(jsonString, { status: finalStatus, headers: finalHeaders });
+    return this._finalResponse;
   }
   /**
    * Respond with a text string
    */
   text(data, status, headers) {
+    const finalStatus = status ?? this.response.status;
+    if (!headers && !this.response.hasPopulatedHeaders) {
+      this._finalResponse = new Response(data, {
+        status: finalStatus,
+        headers: { "content-type": "text/plain" }
+      });
+      return this._finalResponse;
+    }
     const finalHeaders = this.mergeHeaders(headers);
     finalHeaders.set("content-type", "text/plain");
-    const finalStatus = status ?? this.response.status;
-    return new Response(data, { status: finalStatus, headers: finalHeaders });
+    this._finalResponse = new Response(data, { status: finalStatus, headers: finalHeaders });
+    return this._finalResponse;
   }
   /**
    * Respond with HTML content
@@ -200,7 +332,8 @@ class ShokupanContext {
     const finalHeaders = this.mergeHeaders(headers);
     finalHeaders.set("content-type", "text/html");
     const finalStatus = status ?? this.response.status;
-    return new Response(html, { status: finalStatus, headers: finalHeaders });
+    this._finalResponse = new Response(html, { status: finalStatus, headers: finalHeaders });
+    return this._finalResponse;
   }
   /**
    * Respond with a redirect
@@ -208,7 +341,8 @@ class ShokupanContext {
   redirect(url, status = 302) {
     const headers = this.mergeHeaders();
     headers.set("Location", url);
-    return new Response(null, { status, headers });
+    this._finalResponse = new Response(null, { status, headers });
+    return this._finalResponse;
   }
   /**
    * Respond with a status code
@@ -216,7 +350,8 @@ class ShokupanContext {
    */
   status(status) {
     const headers = this.mergeHeaders();
-    return new Response(null, { status, headers });
+    this._finalResponse = new Response(null, { status, headers });
+    return this._finalResponse;
   }
   /**
    * Respond with a file
@@ -224,7 +359,25 @@ class ShokupanContext {
   file(path, fileOptions, responseOptions) {
     const headers = this.mergeHeaders(responseOptions?.headers);
     const status = responseOptions?.status ?? this.response.status;
-    return new Response(Bun.file(path, fileOptions), { status, headers });
+    this._finalResponse = new Response(Bun.file(path, fileOptions), { status, headers });
+    return this._finalResponse;
+  }
+  /**
+   * JSX Rendering Function
+   */
+  renderer;
+  /**
+   * Render a JSX element
+   * @param element JSX Element
+   * @param status HTTP Status
+   * @param headers HTTP Headers
+   */
+  async jsx(element, args, status, headers) {
+    if (!this.renderer) {
+      throw new Error("No JSX renderer configured");
+    }
+    const html = await this.renderer(element, args);
+    return this.html(html, status, headers);
   }
 }
 const $isApplication = /* @__PURE__ */ Symbol.for("Shokupan.app");
@@ -240,6 +393,8 @@ const $childRouters = /* @__PURE__ */ Symbol.for("Shokupan.child-routers");
 const $childControllers = /* @__PURE__ */ Symbol.for("Shokupan.child-controllers");
 const $mountPath = /* @__PURE__ */ Symbol.for("Shokupan.mount-path");
 const $dispatch = /* @__PURE__ */ Symbol.for("Shokupan.dispatch");
+const $routes = /* @__PURE__ */ Symbol.for("Shokupan.routes");
+const $routeSpec = /* @__PURE__ */ Symbol.for("Shokupan.routeSpec");
 const HTTPMethods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "ALL"];
 var RouteParamType = /* @__PURE__ */ ((RouteParamType2) => {
   RouteParamType2["BODY"] = "BODY";
@@ -292,6 +447,14 @@ const Query = createParamDecorator(RouteParamType.QUERY);
 const Headers$1 = createParamDecorator(RouteParamType.HEADER);
 const Req = createParamDecorator(RouteParamType.REQUEST);
 const Ctx = createParamDecorator(RouteParamType.CONTEXT);
+function Spec(spec) {
+  return (target, propertyKey, descriptor) => {
+    if (!target[$routeSpec]) {
+      target[$routeSpec] = /* @__PURE__ */ new Map();
+    }
+    target[$routeSpec].set(propertyKey, spec);
+  };
+}
 function createMethodDecorator(method) {
   return (path = "/") => {
     return (target, propertyKey, descriptor) => {
@@ -346,83 +509,29 @@ function Inject(token) {
     });
   };
 }
-const provider = new NodeTracerProvider({
-  resource: resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: "basic-service"
-  }),
-  spanProcessors: [
-    new SimpleSpanProcessor(
-      new OTLPTraceExporter({
-        url: "http://localhost:4318/v1/traces"
-        // Default OTLP port
-      })
-    )
-  ]
-});
-provider.register();
-const tracer = trace.getTracer("shokupan.middleware");
-function traceMiddleware(fn, name) {
-  const middlewareName = fn.name || "anonymous middleware";
-  return async (ctx, next) => {
-    return tracer.startActiveSpan(`middleware - ${middlewareName}`, {
-      kind: SpanKind.INTERNAL,
-      attributes: {
-        "code.function": middlewareName,
-        "component": "shokupan.middleware"
-      }
-    }, async (span) => {
-      try {
-        const result = await fn(ctx, next);
-        return result;
-      } catch (err) {
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-        throw err;
-      } finally {
-        span.end();
-      }
-    });
-  };
-}
-function traceHandler(fn, name) {
-  return async function(...args) {
-    return tracer.startActiveSpan(`route handler - ${name}`, {
-      kind: SpanKind.INTERNAL,
-      attributes: {
-        "http.route": name,
-        "component": "shokupan.route"
+const compose = (middleware) => {
+  if (!middleware.length) {
+    return (context2, next) => {
+      return next ? next() : Promise.resolve();
+    };
+  }
+  return function dispatch(context2, next) {
+    let index = -1;
+    function runner(i) {
+      if (i <= index) return Promise.reject(new Error("next() called multiple times"));
+      index = i;
+      if (i >= middleware.length) {
+        return next ? next() : Promise.resolve();
       }
-    }, async (span) => {
+      const fn = middleware[i];
       try {
-        const result = await fn.apply(this, args);
-        return result;
+        return Promise.resolve(fn(context2, () => runner(i + 1)));
       } catch (err) {
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-        throw err;
-      } finally {
-        span.end();
+        return Promise.reject(err);
       }
-    });
-  };
-}
-const compose = (middleware) => {
-  function fn(context2, next) {
-    let runner = next || (async () => {
-    });
-    for (let i = middleware.length - 1; i >= 0; i--) {
-      const fn2 = traceMiddleware(middleware[i]);
-      const nextStep = runner;
-      let called = false;
-      runner = async () => {
-        if (called) throw new Error("next() called multiple times");
-        called = true;
-        return fn2(context2, nextStep);
-      };
     }
-    return runner();
-  }
-  return fn;
+    return runner(0);
+  };
 };
 class ShokupanRequestBase {
   method;
@@ -449,7 +558,6 @@ class ShokupanRequestBase {
   }
 }
 const ShokupanRequest = ShokupanRequestBase;
-const asyncContext = new AsyncLocalStorage();
 function isObject(item) {
   return item && typeof item === "object" && !Array.isArray(item);
 }
@@ -463,7 +571,17 @@ function deepMerge(target, ...sources) {
         deepMerge(target[key], source[key]);
       } else if (Array.isArray(source[key])) {
         if (!target[key]) Object.assign(target, { [key]: [] });
-        target[key] = target[key].concat(source[key]);
+        if (key === "tags") {
+          target[key] = source[key];
+          continue;
+        }
+        const mergedArray = target[key].concat(source[key]);
+        const isPrimitive = (item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean";
+        if (mergedArray.every(isPrimitive)) {
+          target[key] = Array.from(new Set(mergedArray));
+        } else {
+          target[key] = mergedArray;
+        }
       } else {
         Object.assign(target, { [key]: source[key] });
       }
@@ -471,98 +589,709 @@ function deepMerge(target, ...sources) {
   }
   return deepMerge(target, ...sources);
 }
-const eta$1 = new Eta();
-const RouterRegistry = /* @__PURE__ */ new Map();
-const ShokupanApplicationTree = {};
-class ShokupanRouter {
-  constructor(config) {
-    this.config = config;
+function analyzeHandler(handler) {
+  const handlerSource = handler.toString();
+  const inferredSpec = {};
+  if (handlerSource.includes("ctx.body") || handlerSource.includes("await ctx.req.json()")) {
+    inferredSpec.requestBody = {
+      content: { "application/json": { schema: { type: "object" } } }
+    };
   }
-  // Internal marker to identify Router vs. Application
-  [$isApplication] = false;
-  [$isMounted] = false;
-  [$isRouter] = true;
-  [$appRoot];
-  [$mountPath] = "/";
-  [$parent] = null;
-  [$childRouters] = [];
-  [$childControllers] = [];
-  get rootConfig() {
-    return this[$appRoot]?.applicationConfig;
+  const queryParams = /* @__PURE__ */ new Map();
+  const queryIntMatch = handlerSource.match(/parseInt\(ctx\.query\.(\w+)\)/g);
+  if (queryIntMatch) {
+    queryIntMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName) queryParams.set(paramName, { type: "integer", format: "int32" });
+    });
   }
-  get root() {
-    return this[$appRoot];
+  const queryFloatMatch = handlerSource.match(/parseFloat\(ctx\.query\.(\w+)\)/g);
+  if (queryFloatMatch) {
+    queryFloatMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName) queryParams.set(paramName, { type: "number", format: "float" });
+    });
   }
-  routes = [];
-  currentGuards = [];
-  isRouterInstance(target) {
-    return typeof target === "object" && target !== null && $isRouter in target;
+  const queryNumberMatch = handlerSource.match(/Number\(ctx\.query\.(\w+)\)/g);
+  if (queryNumberMatch) {
+    queryNumberMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "number" });
+      }
+    });
   }
-  /**
-   * Mounts a controller instance to a path prefix.
-   * 
-   * Controller can be a convection router or an arbitrary class.
-   * 
-   * Routes are derived from method names:
-   * - get(ctx) -> GET /prefix/
-   * - getUsers(ctx) -> GET /prefix/users
-   * - postCreate(ctx) -> POST /prefix/create
-   */
-  mount(prefix, controller) {
-    if (this.isRouterInstance(controller)) {
-      if (controller[$isMounted]) {
-        throw new Error("Router is already mounted");
+  const queryBoolMatch = handlerSource.match(/(?:Boolean\(ctx\.query\.(\w+)\)|!+ctx\.query\.(\w+))/g);
+  if (queryBoolMatch) {
+    queryBoolMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "boolean" });
       }
-      controller[$mountPath] = prefix;
-      this[$childRouters].push(controller);
-      controller[$parent] = this;
-      const setRouterContext = (router) => {
-        router[$appRoot] = this.root;
-        router[$childRouters].forEach((child) => setRouterContext(child));
-      };
-      setRouterContext(controller);
-      if (this[$appRoot]) ;
-      controller[$appRoot] = this.root;
-      controller[$isMounted] = true;
+    });
+  }
+  const queryMatch = handlerSource.match(/ctx\.query\.(\w+)/g);
+  if (queryMatch) {
+    queryMatch.forEach((match) => {
+      const paramName = match.split(".")[2];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "string" });
+      }
+    });
+  }
+  if (queryParams.size > 0) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    queryParams.forEach((schema, paramName) => {
+      inferredSpec.parameters.push({
+        name: paramName,
+        in: "query",
+        schema: { type: schema.type, ...schema.format ? { format: schema.format } : {} }
+      });
+    });
+  }
+  const pathParams = /* @__PURE__ */ new Map();
+  const paramIntMatch = handlerSource.match(/parseInt\(ctx\.params\.(\w+)\)/g);
+  if (paramIntMatch) {
+    paramIntMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.params\.(\w+)/)?.[1];
+      if (paramName) pathParams.set(paramName, { type: "integer", format: "int32" });
+    });
+  }
+  const paramFloatMatch = handlerSource.match(/parseFloat\(ctx\.params\.(\w+)\)/g);
+  if (paramFloatMatch) {
+    paramFloatMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.params\.(\w+)/)?.[1];
+      if (paramName) pathParams.set(paramName, { type: "number", format: "float" });
+    });
+  }
+  if (pathParams.size > 0) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    pathParams.forEach((schema, paramName) => {
+      inferredSpec.parameters.push({
+        name: paramName,
+        in: "path",
+        required: true,
+        schema: { type: schema.type, ...schema.format ? { format: schema.format } : {} }
+      });
+    });
+  }
+  const headerMatch = handlerSource.match(/ctx\.get\(['"](\w+)['"]\)/g);
+  if (headerMatch) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    headerMatch.forEach((match) => {
+      const headerName = match.match(/['"](\w+)['"]/)?.[1];
+      if (headerName) {
+        inferredSpec.parameters.push({
+          name: headerName,
+          in: "header",
+          schema: { type: "string" }
+        });
+      }
+    });
+  }
+  const responses = {};
+  if (handlerSource.includes("ctx.json(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "application/json": { schema: { type: "object" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.html(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "text/html": { schema: { type: "string" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.text(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "text/plain": { schema: { type: "string" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.file(")) {
+    responses["200"] = {
+      description: "File download",
+      content: {
+        "application/octet-stream": { schema: { type: "string", format: "binary" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.redirect(")) {
+    responses["302"] = {
+      description: "Redirect"
+    };
+  }
+  if (!responses["200"] && /return\s+\{/.test(handlerSource)) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "application/json": { schema: { type: "object" } }
+      }
+    };
+  }
+  const errorStatusMatch = handlerSource.match(/ctx\.(?:json|text|html)\([^)]+,\s*(\d{3,})\)/g);
+  if (errorStatusMatch) {
+    errorStatusMatch.forEach((match) => {
+      const statusCode = match.match(/,\s*(\d{3,})\)/)?.[1];
+      if (statusCode && statusCode !== "200") {
+        responses[statusCode] = {
+          description: `Error response (${statusCode})`
+        };
+      }
+    });
+  }
+  if (Object.keys(responses).length > 0) {
+    inferredSpec.responses = responses;
+  }
+  return { inferredSpec };
+}
+async function generateOpenApi(rootRouter, options = {}) {
+  const paths = {};
+  const tagGroups = /* @__PURE__ */ new Map();
+  const defaultTagGroup = options.defaultTagGroup || "General";
+  const defaultTagName = options.defaultTag || "Application";
+  let astRoutes = [];
+  try {
+    const { OpenAPIAnalyzer: OpenAPIAnalyzer2 } = await import("./openapi-analyzer-BTExMLX4.js");
+    const analyzer = new OpenAPIAnalyzer2(process.cwd());
+    const { applications } = await analyzer.analyze();
+    const appMap = /* @__PURE__ */ new Map();
+    applications.forEach((app) => {
+      appMap.set(app.name, app);
+      if (app.name !== app.className) {
+        appMap.set(app.className, app);
+      }
+    });
+    const getExpandedRoutes = (app, prefix = "", seen = /* @__PURE__ */ new Set()) => {
+      if (seen.has(app.name)) return [];
+      const newSeen = new Set(seen);
+      newSeen.add(app.name);
+      const expanded = [];
+      for (const route of app.routes) {
+        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+        const cleanPath = route.path.startsWith("/") ? route.path : "/" + route.path;
+        let joined = cleanPrefix + cleanPath;
+        if (joined.length > 1 && joined.endsWith("/")) {
+          joined = joined.slice(0, -1);
+        }
+        expanded.push({
+          ...route,
+          path: joined || "/"
+        });
+      }
+      if (app.mounted) {
+        for (const mount of app.mounted) {
+          const targetApp = appMap.get(mount.target);
+          if (targetApp) {
+            const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+            const mountPrefix = mount.prefix.startsWith("/") ? mount.prefix : "/" + mount.prefix;
+            expanded.push(...getExpandedRoutes(targetApp, cleanPrefix + mountPrefix, newSeen));
+          }
+        }
+      }
+      return expanded;
+    };
+    applications.forEach((app) => {
+      astRoutes.push(...getExpandedRoutes(app));
+    });
+    const dedupedRoutes = /* @__PURE__ */ new Map();
+    for (const route of astRoutes) {
+      const key = `${route.method.toUpperCase()}:${route.path}`;
+      let score = 0;
+      if (route.responseSchema) score += 10;
+      if (route.handlerSource) score += 5;
+      if (!dedupedRoutes.has(key) || score > dedupedRoutes.get(key).score) {
+        dedupedRoutes.set(key, { route, score });
+      }
+    }
+    astRoutes = Array.from(dedupedRoutes.values()).map((v) => v.route);
+  } catch (e) {
+    console.warn("OpenAPI AST analysis failed or skipped:", e);
+  }
+  const collect = (router, prefix = "", currentGroup = defaultTagGroup, defaultTag = defaultTagName) => {
+    let group = currentGroup;
+    let tag = defaultTag;
+    if (router.config?.group) group = router.config.group;
+    if (router.config?.name) {
+      tag = router.config.name;
     } else {
-      let instance = controller;
-      if (typeof controller === "function") {
-        instance = Container.resolve(controller);
-        const controllerPath = controller[$controllerPath];
-        if (controllerPath) {
-          const p1 = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-          const p2 = controllerPath.startsWith("/") ? controllerPath : "/" + controllerPath;
-          prefix = p1 + p2;
-          if (!prefix) prefix = "/";
+      const mountPath = router[$mountPath];
+      if (mountPath && mountPath !== "/") {
+        const segments = mountPath.split("/").filter(Boolean);
+        if (segments.length > 0) {
+          const lastSegment = segments[segments.length - 1];
+          tag = lastSegment.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
         }
       }
-      instance[$mountPath] = prefix;
-      this[$childControllers].push(instance);
-      const controllerMiddleware = (typeof controller === "function" ? controller[$middleware] : instance[$middleware]) || [];
-      const proto = Object.getPrototypeOf(instance);
-      const methods = /* @__PURE__ */ new Set();
-      let current = proto;
-      while (current && current !== Object.prototype) {
-        Object.getOwnPropertyNames(current).forEach((name) => methods.add(name));
-        current = Object.getPrototypeOf(current);
+    }
+    if (!tagGroups.has(group)) tagGroups.set(group, /* @__PURE__ */ new Set());
+    const routes = router[$routes] || [];
+    for (const route of routes) {
+      const routeGroup = route.group || group;
+      const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+      const cleanSubPath = route.path.startsWith("/") ? route.path : "/" + route.path;
+      let fullPath = cleanPrefix + cleanSubPath || "/";
+      fullPath = fullPath.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
+      if (fullPath.length > 1 && fullPath.endsWith("/")) {
+        fullPath = fullPath.slice(0, -1);
       }
-      Object.getOwnPropertyNames(instance).forEach((name) => methods.add(name));
-      const decoratedRoutes = instance[$routeMethods] || proto && proto[$routeMethods];
-      const decoratedArgs = instance[$routeArgs] || proto && proto[$routeArgs];
-      const methodMiddlewareMap = instance[$middleware] || proto && proto[$middleware];
-      let routesAttached = 0;
-      for (const name of methods) {
-        if (name === "constructor") continue;
-        if (["arguments", "caller", "callee"].includes(name)) continue;
-        const originalHandler = instance[name];
-        if (typeof originalHandler !== "function") continue;
-        let method;
-        let subPath = "";
-        if (decoratedRoutes && decoratedRoutes.has(name)) {
-          const config = decoratedRoutes.get(name);
-          method = config.method;
-          subPath = config.path;
-        } else {
+      if (!paths[fullPath]) paths[fullPath] = {};
+      const operation = {
+        responses: { "200": { description: "Successful response" } },
+        tags: [tag]
+      };
+      if (route.guards) {
+        for (const guard of route.guards) {
+          if (guard.spec) {
+            if (guard.spec.security) {
+              const existing = operation.security || [];
+              for (const req of guard.spec.security) {
+                const reqStr = JSON.stringify(req);
+                if (!existing.some((e) => JSON.stringify(e) === reqStr)) {
+                  existing.push(req);
+                }
+              }
+              operation.security = existing;
+            }
+            if (guard.spec.responses) {
+              operation.responses = { ...operation.responses, ...guard.spec.responses };
+            }
+          }
+        }
+      }
+      let astMatch = astRoutes.find(
+        (r) => r.method.toUpperCase() === route.method.toUpperCase() && r.path === fullPath
+      );
+      if (!astMatch) {
+        let runtimeSource = route.handler.toString();
+        if (route.handler.originalHandler) {
+          runtimeSource = route.handler.originalHandler.toString();
+        }
+        const runtimeHandlerSrc = runtimeSource.replace(/\s+/g, " ");
+        const sameMethodRoutes = astRoutes.filter((r) => r.method.toUpperCase() === route.method.toUpperCase());
+        astMatch = sameMethodRoutes.find((r) => {
+          const astHandlerSrc = (r.handlerSource || r.handlerName || "").replace(/\s+/g, " ");
+          if (!astHandlerSrc || astHandlerSrc.length < 20) return false;
+          const match = runtimeHandlerSrc.includes(astHandlerSrc) || astHandlerSrc.includes(runtimeHandlerSrc) || r.handlerSource && runtimeHandlerSrc.includes(r.handlerSource.substring(0, 50));
+          return match;
+        });
+      }
+      const potentialMatches = astRoutes.filter(
+        (r) => r.method.toUpperCase() === route.method.toUpperCase() && r.path === fullPath
+      );
+      if (potentialMatches.length > 1) {
+        const runtimeHandlerSrc = route.handler.toString().replace(/\s+/g, " ");
+        const preciseMatch = potentialMatches.find((r) => {
+          const astHandlerSrc = (r.handlerSource || r.handlerName || "").replace(/\s+/g, " ");
+          const match = runtimeHandlerSrc.includes(astHandlerSrc) || astHandlerSrc.includes(runtimeHandlerSrc) || r.handlerSource && runtimeHandlerSrc.includes(r.handlerSource.substring(0, 50));
+          return match;
+        });
+        if (preciseMatch) {
+          astMatch = preciseMatch;
+        }
+      }
+      if (astMatch) {
+        if (astMatch.summary) operation.summary = astMatch.summary;
+        if (astMatch.description) operation.description = astMatch.description;
+        if (astMatch.tags) operation.tags = astMatch.tags;
+        if (astMatch.operationId) operation.operationId = astMatch.operationId;
+        if (astMatch.requestTypes?.body) {
+          operation.requestBody = {
+            content: {
+              "application/json": { schema: astMatch.requestTypes.body }
+            }
+          };
+        }
+        if (astMatch.responseSchema) {
+          operation.responses["200"] = {
+            description: "Successful response",
+            content: {
+              "application/json": { schema: astMatch.responseSchema }
+            }
+          };
+        } else if (astMatch.responseType) {
+          const contentType = astMatch.responseType === "string" ? "text/plain" : "application/json";
+          operation.responses["200"] = {
+            description: "Successful response",
+            content: {
+              [contentType]: { schema: { type: astMatch.responseType } }
+            }
+          };
+        }
+        const params = [];
+        if (astMatch.requestTypes?.query) {
+          for (const [name, _type] of Object.entries(astMatch.requestTypes.query)) {
+            params.push({ name, in: "query", schema: { type: "string" } });
+          }
+        }
+        if (params.length > 0) {
+          operation.parameters = params;
+        }
+      }
+      if (route.keys.length > 0) {
+        const pathParams = route.keys.map((key) => ({
+          name: key,
+          in: "path",
+          required: true,
+          schema: { type: "string" }
+        }));
+        const existingParams = operation.parameters || [];
+        const mergedParams = [...existingParams];
+        pathParams.forEach((p) => {
+          const idx = mergedParams.findIndex((ep) => ep.in === "path" && ep.name === p.name);
+          if (idx >= 0) {
+            mergedParams[idx] = deepMerge(mergedParams[idx], p);
+          } else {
+            mergedParams.push(p);
+          }
+        });
+        operation.parameters = mergedParams;
+      }
+      const { inferredSpec } = analyzeHandler(route.handler);
+      if (inferredSpec) {
+        if (inferredSpec.parameters) {
+          const existingParams = operation.parameters || [];
+          const mergedParams = [...existingParams];
+          for (const p of inferredSpec.parameters) {
+            const idx = mergedParams.findIndex((ep) => ep.name === p.name && ep.in === p.in);
+            if (idx >= 0) {
+              mergedParams[idx] = deepMerge(mergedParams[idx], p);
+            } else {
+              mergedParams.push(p);
+            }
+          }
+          operation.parameters = mergedParams;
+          delete inferredSpec.parameters;
+        }
+        deepMerge(operation, inferredSpec);
+      }
+      if (route.handlerSpec) {
+        const spec = route.handlerSpec;
+        if (spec.summary) operation.summary = spec.summary;
+        if (spec.description) operation.description = spec.description;
+        if (spec.operationId) operation.operationId = spec.operationId;
+        if (spec.tags) operation.tags = spec.tags;
+        if (spec.security) operation.security = spec.security;
+        if (spec.responses) {
+          operation.responses = { ...operation.responses, ...spec.responses };
+        }
+      }
+      if (!operation.tags || operation.tags.length === 0) operation.tags = [tag];
+      if (operation.tags) {
+        operation.tags = Array.from(new Set(operation.tags));
+        for (const t of operation.tags) {
+          if (!tagGroups.has(routeGroup)) tagGroups.set(routeGroup, /* @__PURE__ */ new Set());
+          tagGroups.get(routeGroup)?.add(t);
+        }
+      }
+      const methodLower = route.method.toLowerCase();
+      if (methodLower === "all") {
+        ["get", "post", "put", "delete", "patch"].forEach((m) => {
+          if (!paths[fullPath][m]) paths[fullPath][m] = { ...operation };
+        });
+      } else {
+        paths[fullPath][methodLower] = operation;
+      }
+    }
+    for (const controller of router[$childControllers]) {
+      const controllerName = controller.constructor.name || "UnknownController";
+      tagGroups.get(group)?.add(controllerName);
+    }
+    for (const child of router[$childRouters]) {
+      const mountPath = child[$mountPath];
+      const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+      const cleanMount = mountPath.startsWith("/") ? mountPath : "/" + mountPath;
+      const nextPrefix = cleanPrefix + cleanMount || "/";
+      collect(child, nextPrefix, group, tag);
+    }
+  };
+  collect(rootRouter);
+  const xTagGroups = [];
+  for (const [name, tags] of tagGroups) {
+    xTagGroups.push({ name, tags: Array.from(tags).sort() });
+  }
+  return {
+    openapi: "3.1.0",
+    info: { title: "Shokupan API", version: "1.0.0", ...options.info },
+    paths,
+    components: options.components,
+    servers: options.servers,
+    tags: options.tags,
+    externalDocs: options.externalDocs,
+    "x-tagGroups": xTagGroups
+  };
+}
+const eta$1 = new Eta();
+function serveStatic(ctx, config, prefix) {
+  const rootPath = resolve(config.root || ".");
+  const normalizedPrefix = prefix.endsWith("/") && prefix !== "/" ? prefix.slice(0, -1) : prefix;
+  return async () => {
+    let relative = ctx.path.slice(normalizedPrefix.length);
+    if (!relative.startsWith("/") && relative.length > 0) relative = "/" + relative;
+    if (relative.length === 0) relative = "/";
+    relative = decodeURIComponent(relative);
+    const requestPath = join(rootPath, relative);
+    if (!requestPath.startsWith(rootPath)) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    if (requestPath.includes("\0")) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    if (config.hooks?.onRequest) {
+      const res = await config.hooks.onRequest(ctx);
+      if (res) return res;
+    }
+    if (config.exclude) {
+      for (const pattern of config.exclude) {
+        if (pattern instanceof RegExp) {
+          if (pattern.test(relative)) return ctx.json({ error: "Forbidden" }, 403);
+        } else if (typeof pattern === "string") {
+          if (relative.includes(pattern)) return ctx.json({ error: "Forbidden" }, 403);
+        }
+      }
+    }
+    if (basename(requestPath).startsWith(".")) {
+      const behavior = config.dotfiles || "ignore";
+      if (behavior === "deny") return ctx.json({ error: "Forbidden" }, 403);
+      if (behavior === "ignore") return ctx.json({ error: "Not Found" }, 404);
+    }
+    let finalPath = requestPath;
+    let stats;
+    try {
+      stats = await stat(requestPath);
+    } catch (e) {
+      if (config.extensions) {
+        for (const ext of config.extensions) {
+          const p = requestPath + (ext.startsWith(".") ? ext : "." + ext);
+          try {
+            const s = await stat(p);
+            if (s.isFile()) {
+              finalPath = p;
+              stats = s;
+              break;
+            }
+          } catch {
+          }
+        }
+      }
+      if (!stats) return ctx.json({ error: "Not Found" }, 404);
+    }
+    if (stats.isDirectory()) {
+      if (!ctx.path.endsWith("/")) {
+        const query = ctx.url.search;
+        return ctx.redirect(ctx.path + "/" + query, 302);
+      }
+      let indexes = [];
+      if (config.index === void 0) {
+        indexes = ["index.html", "index.htm"];
+      } else if (Array.isArray(config.index)) {
+        indexes = config.index;
+      } else if (config.index) {
+        indexes = [config.index];
+      }
+      let foundIndex = false;
+      for (const idx of indexes) {
+        const idxPath = join(finalPath, idx);
+        try {
+          const idxStats = await stat(idxPath);
+          if (idxStats.isFile()) {
+            finalPath = idxPath;
+            foundIndex = true;
+            break;
+          }
+        } catch {
+        }
+      }
+      if (!foundIndex) {
+        if (config.listDirectory) {
+          try {
+            const files = await readdir(requestPath);
+            const listing = eta$1.renderString(`
+                                <!DOCTYPE html>
+                                <html>
+                                <head>
+                                    <title>Index of <%= it.relative %></title>
+                                    <style>
+                                        body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+                                        ul { list-style: none; padding: 0; }
+                                        li { padding: 0.5rem 0; border-bottom: 1px solid #eee; }
+                                        a { text-decoration: none; color: #0066cc; }
+                                        a:hover { text-decoration: underline; }
+                                        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
+                                    </style>
+                                </head>
+                                <body>
+                                <h1>Index of <%= it.relative %></h1>
+                                <ul>
+                                    <% if (it.relative !== '/') { %>
+                                        <li><a href="../">../</a></li>
+                                    <% } %>
+                                    <% it.files.forEach(function(f) { %>
+                                        <li><a href="<%= f %>"><%= f %></a></li>
+                                    <% }) %>
+                                </ul>
+                                </body>
+                                </html>
+                            `, { relative, files, join });
+            return new Response(listing, { headers: { "Content-Type": "text/html" } });
+          } catch (e) {
+            return ctx.json({ error: "Internal Server Error" }, 500);
+          }
+        } else {
+          return ctx.json({ error: "Forbidden" }, 403);
+        }
+      }
+    }
+    const file = Bun.file(finalPath);
+    let response = new Response(file);
+    if (config.hooks?.onResponse) {
+      const hooked = await config.hooks.onResponse(ctx, response);
+      if (hooked) response = hooked;
+    }
+    return response;
+  };
+}
+const asyncContext = new AsyncLocalStorage();
+const tracer = trace.getTracer("shokupan.middleware");
+function traceHandler(fn, name) {
+  return async function(...args) {
+    return tracer.startActiveSpan(`route handler - ${name}`, {
+      kind: SpanKind.INTERNAL,
+      attributes: {
+        "http.route": name,
+        "component": "shokupan.route"
+      }
+    }, async (span) => {
+      try {
+        const result = await fn.apply(this, args);
+        return result;
+      } catch (err) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  };
+}
+const RouterRegistry = /* @__PURE__ */ new Map();
+const ShokupanApplicationTree = {};
+class ShokupanRouter {
+  constructor(config) {
+    this.config = config;
+    if (config?.requestTimeout) {
+      this.requestTimeout = config.requestTimeout;
+    }
+  }
+  // Internal marker to identify Router vs. Application
+  [$isApplication] = false;
+  [$isMounted] = false;
+  [$isRouter] = true;
+  [$appRoot];
+  [$mountPath] = "/";
+  // Public via Symbol for OpenAPI generator
+  [$parent] = null;
+  [$childRouters] = [];
+  [$childControllers] = [];
+  get rootConfig() {
+    return this[$appRoot]?.applicationConfig;
+  }
+  get root() {
+    return this[$appRoot];
+  }
+  [$routes] = [];
+  // Public via Symbol for OpenAPI generator
+  currentGuards = [];
+  isRouterInstance(target) {
+    return typeof target === "object" && target !== null && $isRouter in target;
+  }
+  /**
+   * Mounts a controller instance to a path prefix.
+   * 
+   * Controller can be a convection router or an arbitrary class.
+   * 
+   * Routes are derived from method names:
+   * - get(ctx) -> GET /prefix/
+   * - getUsers(ctx) -> GET /prefix/users
+   * - postCreate(ctx) -> POST /prefix/create
+   */
+  mount(prefix, controller) {
+    const isRouter = this.isRouterInstance(controller);
+    const isFunction = typeof controller === "function";
+    const controllersOnly = this.config?.controllersOnly ?? this.rootConfig?.controllersOnly ?? false;
+    if (controllersOnly && !isFunction && !isRouter) {
+      throw new Error(`[Shokupan] strict controller check failed: ${controller.constructor.name || typeof controller} is not a class constructor.`);
+    }
+    if (this.isRouterInstance(controller)) {
+      if (controller[$isMounted]) {
+        throw new Error("Router is already mounted");
+      }
+      controller[$mountPath] = prefix;
+      this[$childRouters].push(controller);
+      controller[$parent] = this;
+      const setRouterContext = (router) => {
+        router[$appRoot] = this.root;
+        router[$childRouters].forEach((child) => setRouterContext(child));
+      };
+      setRouterContext(controller);
+      if (this[$appRoot]) ;
+      controller[$appRoot] = this.root;
+      controller[$isMounted] = true;
+    } else {
+      let instance = controller;
+      if (typeof controller === "function") {
+        instance = Container.resolve(controller);
+        const controllerPath = controller[$controllerPath];
+        if (controllerPath) {
+          const p1 = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+          const p2 = controllerPath.startsWith("/") ? controllerPath : "/" + controllerPath;
+          prefix = p1 + p2;
+          if (!prefix) prefix = "/";
+        }
+      } else {
+        const ctor = instance.constructor;
+        const controllerPath = ctor[$controllerPath];
+        if (controllerPath) {
+          const p1 = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+          const p2 = controllerPath.startsWith("/") ? controllerPath : "/" + controllerPath;
+          prefix = p1 + p2;
+          if (!prefix) prefix = "/";
+        }
+      }
+      instance[$mountPath] = prefix;
+      this[$childControllers].push(instance);
+      const controllerMiddleware = (typeof controller === "function" ? controller[$middleware] : instance[$middleware]) || [];
+      const proto = Object.getPrototypeOf(instance);
+      const methods = /* @__PURE__ */ new Set();
+      let current = proto;
+      while (current && current !== Object.prototype) {
+        Object.getOwnPropertyNames(current).forEach((name) => methods.add(name));
+        current = Object.getPrototypeOf(current);
+      }
+      Object.getOwnPropertyNames(instance).forEach((name) => methods.add(name));
+      const decoratedRoutes = instance[$routeMethods] || proto && proto[$routeMethods];
+      const decoratedArgs = instance[$routeArgs] || proto && proto[$routeArgs];
+      const methodMiddlewareMap = instance[$middleware] || proto && proto[$middleware];
+      let routesAttached = 0;
+      for (const name of methods) {
+        if (name === "constructor") continue;
+        if (["arguments", "caller", "callee"].includes(name)) continue;
+        const originalHandler = instance[name];
+        if (typeof originalHandler !== "function") continue;
+        let method;
+        let subPath = "";
+        if (decoratedRoutes && decoratedRoutes.has(name)) {
+          const config = decoratedRoutes.get(name);
+          method = config.method;
+          subPath = config.path;
+        } else {
           for (const m of HTTPMethods) {
             if (name.toUpperCase().startsWith(m)) {
               method = m;
@@ -642,7 +1371,7 @@ class ShokupanRouter {
                 }
               }
             }
-            const tracedOriginalHandler = traceHandler(originalHandler, normalizedPath);
+            const tracedOriginalHandler = ctx.app?.applicationConfig.enableTracing ? traceHandler(originalHandler, normalizedPath) : originalHandler;
             return tracedOriginalHandler.apply(instance, args);
           };
           let finalHandler = wrappedHandler;
@@ -652,8 +1381,14 @@ class ShokupanRouter {
               return composed(ctx, () => wrappedHandler(ctx));
             };
           }
+          finalHandler.originalHandler = originalHandler;
+          if (finalHandler !== wrappedHandler) {
+            wrappedHandler.originalHandler = originalHandler;
+          }
           const tagName = instance.constructor.name;
-          const spec = { tags: [tagName] };
+          const decoratedSpecs = instance[$routeSpec] || proto && proto[$routeSpec];
+          const userSpec = decoratedSpecs && decoratedSpecs.get(name);
+          const spec = { tags: [tagName], ...userSpec };
           this.add({ method, path: normalizedPath, handler: finalHandler, spec });
         }
       }
@@ -668,7 +1403,7 @@ class ShokupanRouter {
    * Returns all routes attached to this router and its descendants.
    */
   getRoutes() {
-    const routes = this.routes.map((r) => ({
+    const routes = this[$routes].map((r) => ({
       method: r.method,
       path: r.path,
       handler: r.handler
@@ -769,6 +1504,31 @@ class ShokupanRouter {
       data: result
     };
   }
+  applyHooks(match) {
+    if (!this.config?.hooks) return match;
+    const hooks = this.config.hooks;
+    if (!hooks.onRequestStart && !hooks.onRequestEnd && !hooks.onError) return match;
+    const originalHandler = match.handler;
+    match.handler = async (ctx) => {
+      if (hooks.onRequestStart) await hooks.onRequestStart(ctx);
+      try {
+        const result = await originalHandler(ctx);
+        if (hooks.onRequestEnd) await hooks.onRequestEnd(ctx);
+        return result;
+      } catch (err) {
+        if (hooks.onError) {
+          try {
+            await hooks.onError(err, ctx);
+          } catch (e) {
+            console.error("Error in router onError hook:", e);
+          }
+        }
+        throw err;
+      }
+    };
+    match.handler.originalHandler = originalHandler.originalHandler || originalHandler;
+    return match;
+  }
   /**
    * Find a route matching the given method and path.
    * @param method HTTP method
@@ -776,29 +1536,38 @@ class ShokupanRouter {
    * @returns Route handler and parameters if found, otherwise null
    */
   find(method, path) {
-    for (const route of this.routes) {
-      if (route.method !== "ALL" && route.method !== method) continue;
-      const match = route.regex.exec(path);
-      if (match) {
-        const params = {};
-        route.keys.forEach((key, index) => {
-          params[key] = match[index + 1];
-        });
-        return { handler: route.handler, params };
+    const findInRoutes = (routes, m) => {
+      for (const route of routes) {
+        if (route.method !== "ALL" && route.method !== m) continue;
+        const match = route.regex.exec(path);
+        if (match) {
+          const params = {};
+          route.keys.forEach((key, index) => {
+            params[key] = match[index + 1];
+          });
+          return this.applyHooks({ handler: route.handler, params });
+        }
       }
+      return null;
+    };
+    let result = findInRoutes(this[$routes], method);
+    if (result) return result;
+    if (method === "HEAD") {
+      result = findInRoutes(this[$routes], "GET");
+      if (result) return result;
     }
     for (const child of this[$childRouters]) {
       const prefix = child[$mountPath];
       if (path === prefix || path.startsWith(prefix + "/")) {
         const subPath = path.slice(prefix.length) || "/";
         const match = child.find(method, subPath);
-        if (match) return match;
+        if (match) return this.applyHooks(match);
       }
       if (prefix.endsWith("/")) {
         if (path.startsWith(prefix)) {
           const subPath = path.slice(prefix.length) || "/";
           const match = child.find(method, subPath);
-          if (match) return match;
+          if (match) return this.applyHooks(match);
         }
       }
     }
@@ -816,6 +1585,7 @@ class ShokupanRouter {
     };
   }
   // --- Functional Routing ---
+  requestTimeout;
   /**
    * Adds a route to the router.
    * 
@@ -823,12 +1593,25 @@ class ShokupanRouter {
    * @param path - URL path
    * @param spec - OpenAPI specification for the route
    * @param handler - Route handler function
+   * @param requestTimeout - Timeout for this route in milliseconds
    */
-  add({ method, path, spec, handler, regex: customRegex, group }) {
+  add({ method, path, spec, handler, regex: customRegex, group, requestTimeout, renderer }) {
     const { regex, keys } = customRegex ? { regex: customRegex, keys: [] } : this.parsePath(path);
     let wrappedHandler = handler;
     const routeGuards = [...this.currentGuards];
+    const effectiveTimeout = requestTimeout ?? this.requestTimeout ?? this.rootConfig?.requestTimeout;
+    if (effectiveTimeout !== void 0 && effectiveTimeout > 0) {
+      const originalHandler = wrappedHandler;
+      wrappedHandler = async (ctx) => {
+        if (ctx.server) {
+          ctx.server.timeout(ctx.req, effectiveTimeout / 1e3);
+        }
+        return originalHandler(ctx);
+      };
+      wrappedHandler.originalHandler = originalHandler.originalHandler || originalHandler;
+    }
     if (routeGuards.length > 0) {
+      const innerHandler = wrappedHandler;
       wrappedHandler = async (ctx) => {
         for (const guard of routeGuards) {
           let guardPassed = false;
@@ -853,10 +1636,47 @@ class ShokupanRouter {
             return ctx.json({ error: "Forbidden" }, 403);
           }
         }
-        return handler(ctx);
+        return innerHandler(ctx);
+      };
+    }
+    const effectiveRenderer = renderer ?? this.config?.renderer ?? this.rootConfig?.renderer;
+    if (effectiveRenderer) {
+      const innerHandler = wrappedHandler;
+      wrappedHandler = async (ctx) => {
+        ctx.renderer = effectiveRenderer;
+        return innerHandler(ctx);
       };
     }
-    this.routes.push({
+    let file = "unknown";
+    let line = 0;
+    try {
+      const err = new Error();
+      const stack = err.stack?.split("\n") || [];
+      const callerLine = stack.find(
+        (l) => l.includes(":") && !l.includes("router.ts") && !l.includes("shokupan.ts") && !l.includes("node_modules") && !l.includes("bun:main")
+      );
+      if (callerLine) {
+        const match = callerLine.match(/\((.*):(\d+):(\d+)\)/) || callerLine.match(/at (.*):(\d+):(\d+)/);
+        if (match) {
+          file = match[1];
+          line = parseInt(match[2], 10);
+        }
+      }
+    } catch (e) {
+    }
+    const trackedHandler = wrappedHandler;
+    wrappedHandler = async (ctx) => {
+      if (ctx.app?.applicationConfig.enableMiddlewareTracking) {
+        ctx.handlerStack.push({
+          name: handler.name || "anonymous",
+          file,
+          line
+        });
+      }
+      return trackedHandler(ctx);
+    };
+    wrappedHandler.originalHandler = trackedHandler.originalHandler || trackedHandler;
+    this[$routes].push({
       method,
       path,
       regex,
@@ -864,7 +1684,9 @@ class ShokupanRouter {
       handler: wrappedHandler,
       handlerSpec: spec,
       group,
-      guards: routeGuards.length > 0 ? routeGuards : void 0
+      guards: routeGuards.length > 0 ? routeGuards : void 0,
+      requestTimeout: effectiveTimeout
+      // Save for inspection? Or just relying on closure
     });
     return this;
   }
@@ -899,7 +1721,35 @@ class ShokupanRouter {
   guard(specOrHandler, handler) {
     const spec = typeof specOrHandler === "function" ? void 0 : specOrHandler;
     const guardHandler = typeof specOrHandler === "function" ? specOrHandler : handler;
-    this.currentGuards.push({ handler: guardHandler, spec });
+    let file = "unknown";
+    let line = 0;
+    try {
+      const err = new Error();
+      const stack = err.stack?.split("\n") || [];
+      const callerLine = stack.find(
+        (l) => l.includes(":") && !l.includes("router.ts") && !l.includes("shokupan.ts") && !l.includes("node_modules") && !l.includes("bun:main")
+      );
+      if (callerLine) {
+        const match = callerLine.match(/\((.*):(\d+):(\d+)\)/) || callerLine.match(/at (.*):(\d+):(\d+)/);
+        if (match) {
+          file = match[1];
+          line = parseInt(match[2], 10);
+        }
+      }
+    } catch (e) {
+    }
+    const trackedGuard = async (ctx, next) => {
+      if (ctx.app?.applicationConfig.enableMiddlewareTracking) {
+        ctx.handlerStack.push({
+          name: guardHandler.name || "guard",
+          file,
+          line
+        });
+      }
+      return guardHandler(ctx, next);
+    };
+    trackedGuard.originalHandler = guardHandler.originalHandler || guardHandler;
+    this.currentGuards.push({ handler: trackedGuard, spec });
     return this;
   }
   /**
@@ -909,133 +1759,12 @@ class ShokupanRouter {
    */
   static(uriPath, options) {
     const config = typeof options === "string" ? { root: options } : options;
-    const rootPath = resolve(config.root || ".");
     const prefix = uriPath.startsWith("/") ? uriPath : "/" + uriPath;
     const normalizedPrefix = prefix.endsWith("/") && prefix !== "/" ? prefix.slice(0, -1) : prefix;
-    const handler = async (ctx) => {
-      let relative = ctx.path.slice(normalizedPrefix.length);
-      if (!relative.startsWith("/") && relative.length > 0) relative = "/" + relative;
-      if (relative.length === 0) relative = "/";
-      relative = decodeURIComponent(relative);
-      const requestPath = join(rootPath, relative);
-      if (!requestPath.startsWith(rootPath)) {
-        return ctx.json({ error: "Forbidden" }, 403);
-      }
-      if (requestPath.includes("\0")) {
-        return ctx.json({ error: "Forbidden" }, 403);
-      }
-      if (config.hooks?.onRequest) {
-        const res = await config.hooks.onRequest(ctx);
-        if (res) return res;
-      }
-      if (config.exclude) {
-        for (const pattern2 of config.exclude) {
-          if (pattern2 instanceof RegExp) {
-            if (pattern2.test(relative)) return ctx.json({ error: "Forbidden" }, 403);
-          } else if (typeof pattern2 === "string") {
-            if (relative.includes(pattern2)) return ctx.json({ error: "Forbidden" }, 403);
-          }
-        }
-      }
-      if (basename(requestPath).startsWith(".")) {
-        const behavior = config.dotfiles || "ignore";
-        if (behavior === "deny") return ctx.json({ error: "Forbidden" }, 403);
-        if (behavior === "ignore") return ctx.json({ error: "Not Found" }, 404);
-      }
-      let finalPath = requestPath;
-      let stats;
-      try {
-        stats = await stat(requestPath);
-      } catch (e) {
-        if (config.extensions) {
-          for (const ext of config.extensions) {
-            const p = requestPath + (ext.startsWith(".") ? ext : "." + ext);
-            try {
-              const s = await stat(p);
-              if (s.isFile()) {
-                finalPath = p;
-                stats = s;
-                break;
-              }
-            } catch {
-            }
-          }
-        }
-        if (!stats) return ctx.json({ error: "Not Found" }, 404);
-      }
-      if (stats.isDirectory()) {
-        if (!ctx.path.endsWith("/")) {
-          const query = ctx.url.search;
-          return ctx.redirect(ctx.path + "/" + query, 302);
-        }
-        let indexes = [];
-        if (config.index === void 0) {
-          indexes = ["index.html", "index.htm"];
-        } else if (Array.isArray(config.index)) {
-          indexes = config.index;
-        } else if (config.index) {
-          indexes = [config.index];
-        }
-        let foundIndex = false;
-        for (const idx of indexes) {
-          const idxPath = join(finalPath, idx);
-          try {
-            const idxStats = await stat(idxPath);
-            if (idxStats.isFile()) {
-              finalPath = idxPath;
-              foundIndex = true;
-              break;
-            }
-          } catch {
-          }
-        }
-        if (!foundIndex) {
-          if (config.listDirectory) {
-            try {
-              const files = await readdir(requestPath);
-              const listing = eta$1.renderString(`
-                                <!DOCTYPE html>
-                                <html>
-                                <head>
-                                    <title>Index of <%= it.relative %></title>
-                                    <style>
-                                        body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
-                                        ul { list-style: none; padding: 0; }
-                                        li { padding: 0.5rem 0; border-bottom: 1px solid #eee; }
-                                        a { text-decoration: none; color: #0066cc; }
-                                        a:hover { text-decoration: underline; }
-                                        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
-                                    </style>
-                                </head>
-                                <body>
-                                <h1>Index of <%= it.relative %></h1>
-                                <ul>
-                                    <% if (it.relative !== '/') { %>
-                                        <li><a href="../">../</a></li>
-                                    <% } %>
-                                    <% it.files.forEach(function(f) { %>
-                                        <li><a href="<%= f %>"><%= f %></a></li>
-                                    <% }) %>
-                                </ul>
-                                </body>
-                                </html>
-                            `, { relative, files, join });
-              return new Response(listing, { headers: { "Content-Type": "text/html" } });
-            } catch (e) {
-              return ctx.json({ error: "Internal Server Error" }, 500);
-            }
-          } else {
-            return ctx.json({ error: "Forbidden" }, 403);
-          }
-        }
-      }
-      const file = Bun.file(finalPath);
-      let response = new Response(file);
-      if (config.hooks?.onResponse) {
-        const hooked = await config.hooks.onResponse(ctx, response);
-        if (hooked) response = hooked;
-      }
-      return response;
+    serveStatic(null, config, prefix);
+    const routeHandler = async (ctx) => {
+      const runner = serveStatic(ctx, config, prefix);
+      return runner();
     };
     let groupName = "Static";
     const segments = normalizedPrefix.split("/").filter(Boolean);
@@ -1054,8 +1783,8 @@ class ShokupanRouter {
     const pattern = `^${normalizedPrefix}(/.*)?$`;
     const regex = new RegExp(pattern);
     const displayPath = normalizedPrefix === "/" ? "/*" : normalizedPrefix + "/*";
-    this.add({ method: "GET", path: displayPath, handler, spec, regex });
-    this.add({ method: "HEAD", path: displayPath, handler, spec, regex });
+    this.add({ method: "GET", path: displayPath, handler: routeHandler, spec, regex });
+    this.add({ method: "HEAD", path: displayPath, handler: routeHandler, spec, regex });
     return this;
   }
   /**
@@ -1090,138 +1819,25 @@ class ShokupanRouter {
   }
   /**
    * Generates an OpenAPI 3.1 Document by recursing through the router and its descendants.
+   * Now includes runtime analysis of handler functions to infer request/response types.
    */
   generateApiSpec(options = {}) {
-    const paths = {};
-    const tagGroups = /* @__PURE__ */ new Map();
-    const defaultTagGroup = options.defaultTagGroup || "General";
-    const defaultTagName = options.defaultTag || "Application";
-    const collect = (router, prefix = "", currentGroup = defaultTagGroup, defaultTag = defaultTagName) => {
-      let group = currentGroup;
-      let tag = defaultTag;
-      if (router.config?.group) {
-        group = router.config.group;
-      }
-      if (router.config?.name) {
-        tag = router.config.name;
-      } else {
-        const mountPath = router[$mountPath];
-        if (mountPath && mountPath !== "/") {
-          const segments = mountPath.split("/").filter(Boolean);
-          if (segments.length > 0) {
-            const lastSegment = segments[segments.length - 1];
-            const humanized = lastSegment.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-            tag = humanized;
-          }
-        }
-      }
-      if (!tagGroups.has(group)) {
-        tagGroups.set(group, /* @__PURE__ */ new Set());
-      }
-      for (const route of router.routes) {
-        const routeGroup = route.group || group;
-        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        const cleanSubPath = route.path.startsWith("/") ? route.path : "/" + route.path;
-        let fullPath = cleanPrefix + cleanSubPath || "/";
-        fullPath = fullPath.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
-        if (!paths[fullPath]) {
-          paths[fullPath] = {};
-        }
-        const operation = {
-          responses: {
-            200: { description: "OK" }
-          }
-        };
-        if (route.keys.length > 0) {
-          operation.parameters = route.keys.map((key) => ({
-            name: key,
-            in: "path",
-            required: true,
-            schema: { type: "string" }
-          }));
-        }
-        if (route.guards) {
-          for (const guard of route.guards) {
-            if (guard.spec) {
-              deepMerge(operation, guard.spec);
-            }
-          }
-        }
-        if (route.handlerSpec) {
-          deepMerge(operation, route.handlerSpec);
-        }
-        if (!operation.tags || operation.tags.length === 0) {
-          operation.tags = [tag];
-        }
-        if (operation.tags) {
-          operation.tags = Array.from(new Set(operation.tags));
-          for (const t of operation.tags) {
-            if (!tagGroups.has(routeGroup)) {
-              tagGroups.set(routeGroup, /* @__PURE__ */ new Set());
-            }
-            tagGroups.get(routeGroup)?.add(t);
-          }
-        }
-        const methodLower = route.method.toLowerCase();
-        if (methodLower === "all") {
-          ["get", "post", "put", "delete", "patch"].forEach((m) => {
-            if (!paths[fullPath][m]) {
-              paths[fullPath][m] = { ...operation };
-            }
-          });
-        } else {
-          paths[fullPath][methodLower] = operation;
-        }
-      }
-      for (const controller of router[$childControllers]) {
-        const mountPath = controller[$mountPath] || "";
-        prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        mountPath.startsWith("/") ? mountPath : "/" + mountPath;
-        const controllerName = controller.constructor.name || "UnknownController";
-        tagGroups.get(group)?.add(controllerName);
-      }
-      for (const child of router[$childRouters]) {
-        const mountPath = child[$mountPath];
-        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        const cleanMount = mountPath.startsWith("/") ? mountPath : "/" + mountPath;
-        const nextPrefix = cleanPrefix + cleanMount || "/";
-        collect(child, nextPrefix, group, tag);
-      }
-    };
-    collect(this);
-    const xTagGroups = [];
-    for (const [name, tags] of tagGroups) {
-      xTagGroups.push({
-        name,
-        tags: Array.from(tags).sort()
-      });
-    }
-    return {
-      openapi: "3.1.0",
-      info: {
-        title: "Shokupan API",
-        version: "1.0.0",
-        ...options.info
-      },
-      paths,
-      components: options.components,
-      servers: options.servers,
-      tags: options.tags,
-      externalDocs: options.externalDocs,
-      "x-tagGroups": xTagGroups
-    };
+    return generateOpenApi(this, options);
   }
 }
 const defaults = {
   port: 3e3,
   hostname: "localhost",
   development: process.env.NODE_ENV !== "production",
-  enableAsyncLocalStorage: false
+  enableAsyncLocalStorage: false,
+  reusePort: false
 };
 trace.getTracer("shokupan.application");
 class Shokupan extends ShokupanRouter {
   applicationConfig = {};
+  openApiSpec;
   middleware = [];
+  composedMiddleware;
   get logger() {
     return this.applicationConfig.logger;
   }
@@ -1232,10 +1848,48 @@ class Shokupan extends ShokupanRouter {
     Object.assign(this.applicationConfig, defaults, applicationConfig);
   }
   /**
-   * Adds middleware to the application.
+   * Adds middleware to the application.
+   */
+  use(middleware) {
+    let trackedMiddleware = middleware;
+    let file = "unknown";
+    let line = 0;
+    try {
+      const err = new Error();
+      const stack = err.stack?.split("\n") || [];
+      const callerLine = stack.find(
+        (l) => l.includes(":") && !l.includes("shokupan.ts") && !l.includes("router.ts") && // In case called from router?
+        !l.includes("node_modules") && !l.includes("bun:main")
+      );
+      if (callerLine) {
+        const match = callerLine.match(/\((.*):(\d+):(\d+)\)/) || callerLine.match(/at (.*):(\d+):(\d+)/);
+        if (match) {
+          file = match[1];
+          line = parseInt(match[2], 10);
+        }
+      }
+    } catch (e) {
+    }
+    trackedMiddleware = async (ctx, next) => {
+      const c = ctx;
+      if (c.handlerStack && c.app?.applicationConfig.enableMiddlewareTracking) {
+        c.handlerStack.push({
+          name: middleware.name || "middleware",
+          file,
+          line
+        });
+      }
+      return middleware(ctx, next);
+    };
+    this.middleware.push(trackedMiddleware);
+    return this;
+  }
+  startupHooks = [];
+  /**
+   * Registers a callback to be executed before the server starts listening.
    */
-  use(middleware) {
-    this.middleware.push(middleware);
+  onStart(callback) {
+    this.startupHooks.push(callback);
     return this;
   }
   /**
@@ -1244,18 +1898,46 @@ class Shokupan extends ShokupanRouter {
    * @param port - The port to listen on. If not specified, the port from the configuration is used. If that is not specified, port 3000 is used.
    * @returns The server instance.
    */
-  listen(port) {
+  async listen(port) {
     const finalPort = port ?? this.applicationConfig.port ?? 3e3;
     if (finalPort < 0 || finalPort > 65535) {
       throw new Error("Invalid port number");
     }
+    for (const hook of this.startupHooks) {
+      await hook();
+    }
+    if (this.applicationConfig.enableOpenApiGen) {
+      this.openApiSpec = await generateOpenApi(this);
+    }
     if (port === 0 && process.platform === "linux") ;
-    const server = Bun.serve({
+    const serveOptions = {
       port: finalPort,
       hostname: this.applicationConfig.hostname,
       development: this.applicationConfig.development,
-      fetch: this.fetch.bind(this)
-    });
+      fetch: this.fetch.bind(this),
+      reusePort: this.applicationConfig.reusePort,
+      idleTimeout: this.applicationConfig.readTimeout ? this.applicationConfig.readTimeout / 1e3 : void 0,
+      websocket: {
+        open(ws) {
+          ws.data?.handler?.open?.(ws);
+        },
+        message(ws, message) {
+          ws.data?.handler?.message?.(ws, message);
+        },
+        drain(ws) {
+          ws.data?.handler?.drain?.(ws);
+        },
+        close(ws, code, reason) {
+          ws.data?.handler?.close?.(ws, code, reason);
+        }
+      }
+    };
+    let factory = this.applicationConfig.serverFactory;
+    if (!factory && typeof Bun === "undefined") {
+      const { createHttpServer } = await import("./server-adapter-CnQFr4P7.js");
+      factory = createHttpServer();
+    }
+    const server = factory ? await factory(serveOptions) : Bun.serve(serveOptions);
     console.log(`Shokupan server listening on http://${server.hostname}:${server.port}`);
     return server;
   }
@@ -1306,65 +1988,122 @@ class Shokupan extends ShokupanRouter {
    * This logic contains the middleware chain and router dispatch.
    * 
    * @param req - The request to handle.
+   * @param server - The server instance.
    * @returns The response to send.
    */
-  async fetch(req) {
-    const tracer2 = trace.getTracer("shokupan.application");
-    const store = asyncContext.getStore();
-    const attrs = {
-      attributes: {
-        "http.url": req.url,
-        "http.method": req.method
-      }
-    };
-    const parent = store?.get("span");
-    const ctx = parent ? trace.setSpan(context.active(), parent) : void 0;
-    return tracer2.startActiveSpan(`${req.method} ${new URL(req.url).pathname}`, attrs, ctx, (span) => {
+  async fetch(req, server) {
+    if (this.applicationConfig.enableTracing) {
+      const tracer2 = trace.getTracer("shokupan.application");
+      const store = asyncContext.getStore();
+      const attrs = {
+        attributes: {
+          "http.url": req.url,
+          "http.method": req.method
+        }
+      };
+      const parent = store?.get("span");
+      const ctx = parent ? trace.setSpan(context.active(), parent) : void 0;
+      return tracer2.startActiveSpan(`${req.method} ${new URL(req.url).pathname}`, attrs, ctx, (span) => {
+        const ctxMap = /* @__PURE__ */ new Map();
+        ctxMap.set("span", span);
+        ctxMap.set("request", req);
+        return asyncContext.run(ctxMap, () => this.handleRequest(req, server).finally(() => span.end()));
+      });
+    }
+    if (this.applicationConfig.enableAsyncLocalStorage) {
       const ctxMap = /* @__PURE__ */ new Map();
-      ctxMap.set("span", span);
       ctxMap.set("request", req);
-      const runCallback = () => {
-        const request = req;
-        const handle = async () => {
-          const ctx2 = new ShokupanContext(request);
-          const fn = compose(this.middleware);
+      return asyncContext.run(ctxMap, () => this.handleRequest(req, server));
+    }
+    return this.handleRequest(req, server);
+  }
+  async handleRequest(req, server) {
+    const request = req;
+    const ctx = new ShokupanContext(request, server, void 0, this, this.applicationConfig.enableMiddlewareTracking);
+    const handle = async () => {
+      try {
+        if (this.applicationConfig.hooks?.onRequestStart) {
+          await this.applicationConfig.hooks.onRequestStart(ctx);
+        }
+        const fn = this.composedMiddleware ??= compose(this.middleware);
+        const result = await fn(ctx, async () => {
+          const match = this.find(req.method, ctx.path);
+          if (match) {
+            ctx.params = match.params;
+            return match.handler(ctx);
+          }
+          return null;
+        });
+        let response;
+        if (result instanceof Response) {
+          response = result;
+        } else if ((result === null || result === void 0) && ctx._finalResponse instanceof Response) {
+          response = ctx._finalResponse;
+        } else if ((result === null || result === void 0) && ctx.response.status === 404) {
+          const span = asyncContext.getStore()?.get("span");
+          if (span) span.setAttribute("http.status_code", 404);
+          response = ctx.text("Not Found", 404);
+        } else if (result === null || result === void 0) {
+          if (ctx._finalResponse) response = ctx._finalResponse;
+          else response = ctx.text("Not Found", 404);
+        } else if (typeof result === "object") {
+          response = ctx.json(result);
+        } else {
+          response = ctx.text(String(result));
+        }
+        if (this.applicationConfig.hooks?.onRequestEnd) {
+          await this.applicationConfig.hooks.onRequestEnd(ctx);
+        }
+        if (this.applicationConfig.hooks?.onResponseStart) {
+          await this.applicationConfig.hooks.onResponseStart(ctx, response);
+        }
+        return response;
+      } catch (err) {
+        console.error(err);
+        const span = asyncContext.getStore()?.get("span");
+        if (span) span.setStatus({ code: 2 });
+        const status = err.status || err.statusCode || 500;
+        const body = { error: err.message || "Internal Server Error" };
+        if (err.errors) body.errors = err.errors;
+        if (this.applicationConfig.hooks?.onError) {
           try {
-            const result = await fn(ctx2, async () => {
-              const match = this.find(req.method, ctx2.path);
-              if (match) {
-                ctx2.params = match.params;
-                return match.handler(ctx2);
-              }
-              return null;
-            });
-            if (result instanceof Response) {
-              return result;
-            }
-            if (result === null || result === void 0) {
-              span.setAttribute("http.status_code", 404);
-              return ctx2.text("Not Found", 404);
-            }
-            if (typeof result === "object") {
-              return ctx2.json(result);
+            await this.applicationConfig.hooks.onError(err, ctx);
+          } catch (hookErr) {
+            console.error("Error in onError hook:", hookErr);
+          }
+        }
+        return ctx.json(body, status);
+      }
+    };
+    let executionPromise = handle();
+    const timeoutMs = this.applicationConfig.requestTimeout;
+    if (timeoutMs && timeoutMs > 0 && this.applicationConfig.hooks?.onRequestTimeout) {
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(async () => {
+          try {
+            if (this.applicationConfig.hooks?.onRequestTimeout) {
+              await this.applicationConfig.hooks.onRequestTimeout(ctx);
             }
-            return ctx2.text(String(result));
-          } catch (err) {
-            console.error(err);
-            span.recordException(err);
-            span.setStatus({ code: 2 });
-            const status = err.status || err.statusCode || 500;
-            const body = { error: err.message || "Internal Server Error" };
-            if (err.errors) body.errors = err.errors;
-            return ctx2.json(body, status);
+          } catch (e) {
+            console.error("Error in onRequestTimeout hook:", e);
           }
-        };
-        return handle().finally(() => span.end());
-      };
-      if (this.applicationConfig.enableAsyncLocalStorage) {
-        return asyncContext.run(ctxMap, runCallback);
-      } else {
-        return runCallback();
+          reject(new Error("Request Timeout"));
+        }, timeoutMs);
+      });
+      executionPromise = Promise.race([executionPromise, timeoutPromise]).finally(() => clearTimeout(timeoutId));
+    }
+    return executionPromise.catch((err) => {
+      if (err.message === "Request Timeout") {
+        return ctx.text("Request Timeout", 408);
+      }
+      console.error("Unexpected error in request execution:", err);
+      return ctx.text("Internal Server Error", 500);
+    }).then(async (res) => {
+      if (this.applicationConfig.hooks?.onResponseEnd) {
+        await this.applicationConfig.hooks.onResponseEnd(ctx, res);
       }
+      return res;
     });
   }
 }
@@ -1416,8 +2155,8 @@ class AuthPlugin extends ShokupanRouter {
   init() {
     for (const [providerName, providerConfig] of Object.entries(this.authConfig.providers)) {
       if (!providerConfig) continue;
-      const provider2 = this.getProviderInstance(providerName, providerConfig);
-      if (!provider2) {
+      const provider = this.getProviderInstance(providerName, providerConfig);
+      if (!provider) {
         continue;
       }
       this.get(`/auth/${providerName}/login`, async (ctx) => {
@@ -1425,15 +2164,15 @@ class AuthPlugin extends ShokupanRouter {
         const codeVerifier = providerName === "google" || providerName === "microsoft" || providerName === "auth0" || providerName === "okta" ? generateCodeVerifier() : void 0;
         const scopes = providerConfig.scopes || [];
         let url;
-        if (provider2 instanceof GitHub) {
-          url = await provider2.createAuthorizationURL(state, scopes);
-        } else if (provider2 instanceof Google || provider2 instanceof MicrosoftEntraId || provider2 instanceof Auth0 || provider2 instanceof Okta) {
-          url = await provider2.createAuthorizationURL(state, codeVerifier, scopes);
-        } else if (provider2 instanceof Apple) {
-          url = await provider2.createAuthorizationURL(state, scopes);
-        } else if (provider2 instanceof OAuth2Client) {
+        if (provider instanceof GitHub) {
+          url = await provider.createAuthorizationURL(state, scopes);
+        } else if (provider instanceof Google || provider instanceof MicrosoftEntraId || provider instanceof Auth0 || provider instanceof Okta) {
+          url = await provider.createAuthorizationURL(state, codeVerifier, scopes);
+        } else if (provider instanceof Apple) {
+          url = await provider.createAuthorizationURL(state, scopes);
+        } else if (provider instanceof OAuth2Client) {
           if (!providerConfig.authUrl) return ctx.text("Config error: authUrl required for oauth2", 500);
-          url = await provider2.createAuthorizationURL(providerConfig.authUrl, state, scopes);
+          url = await provider.createAuthorizationURL(providerConfig.authUrl, state, scopes);
         } else {
           return ctx.text("Provider config error", 500);
         }
@@ -1456,19 +2195,19 @@ class AuthPlugin extends ShokupanRouter {
         try {
           let tokens;
           let idToken;
-          if (provider2 instanceof GitHub) {
-            tokens = await provider2.validateAuthorizationCode(code);
-          } else if (provider2 instanceof Google || provider2 instanceof MicrosoftEntraId) {
+          if (provider instanceof GitHub) {
+            tokens = await provider.validateAuthorizationCode(code);
+          } else if (provider instanceof Google || provider instanceof MicrosoftEntraId) {
             if (!storedVerifier) return ctx.text("Missing verifier", 400);
-            tokens = await provider2.validateAuthorizationCode(code, storedVerifier);
-          } else if (provider2 instanceof Auth0 || provider2 instanceof Okta) {
-            tokens = await provider2.validateAuthorizationCode(code, storedVerifier || "");
-          } else if (provider2 instanceof Apple) {
-            tokens = await provider2.validateAuthorizationCode(code);
+            tokens = await provider.validateAuthorizationCode(code, storedVerifier);
+          } else if (provider instanceof Auth0 || provider instanceof Okta) {
+            tokens = await provider.validateAuthorizationCode(code, storedVerifier || "");
+          } else if (provider instanceof Apple) {
+            tokens = await provider.validateAuthorizationCode(code);
             idToken = tokens.idToken;
-          } else if (provider2 instanceof OAuth2Client) {
+          } else if (provider instanceof OAuth2Client) {
             if (!providerConfig.tokenUrl) return ctx.text("Config error: tokenUrl required for oauth2", 500);
-            tokens = await provider2.validateAuthorizationCode(providerConfig.tokenUrl, code, null);
+            tokens = await provider.validateAuthorizationCode(providerConfig.tokenUrl, code, null);
           }
           const accessToken = tokens.accessToken || tokens.access_token;
           const user = await this.fetchUser(providerName, accessToken, providerConfig, idToken);
@@ -1485,9 +2224,9 @@ class AuthPlugin extends ShokupanRouter {
       });
     }
   }
-  async fetchUser(provider2, token, config, idToken) {
-    let user = { id: "unknown", provider: provider2 };
-    if (provider2 === "github") {
+  async fetchUser(provider, token, config, idToken) {
+    let user = { id: "unknown", provider };
+    if (provider === "github") {
       const res = await fetch("https://api.github.com/user", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1497,10 +2236,10 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name || data.login,
         email: data.email,
         picture: data.avatar_url,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "google") {
+    } else if (provider === "google") {
       const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1510,10 +2249,10 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name,
         email: data.email,
         picture: data.picture,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "microsoft") {
+    } else if (provider === "microsoft") {
       const res = await fetch("https://graph.microsoft.com/v1.0/me", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1522,12 +2261,12 @@ class AuthPlugin extends ShokupanRouter {
         id: data.id,
         name: data.displayName,
         email: data.mail || data.userPrincipalName,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "auth0" || provider2 === "okta") {
+    } else if (provider === "auth0" || provider === "okta") {
       const domain = config.domain.startsWith("http") ? config.domain : `https://${config.domain}`;
-      const endpoint = provider2 === "auth0" ? `${domain}/userinfo` : `${domain}/oauth2/v1/userinfo`;
+      const endpoint = provider === "auth0" ? `${domain}/userinfo` : `${domain}/oauth2/v1/userinfo`;
       const res = await fetch(endpoint, {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1537,20 +2276,20 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name,
         email: data.email,
         picture: data.picture,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "apple") {
+    } else if (provider === "apple") {
       if (idToken) {
         const payload = jose.decodeJwt(idToken);
         user = {
           id: payload.sub,
           email: payload["email"],
-          provider: provider2,
+          provider,
           raw: payload
         };
       }
-    } else if (provider2 === "oauth2") {
+    } else if (provider === "oauth2") {
       if (config.userInfoUrl) {
         const res = await fetch(config.userInfoUrl, {
           headers: { Authorization: `Bearer ${token}` }
@@ -1561,7 +2300,7 @@ class AuthPlugin extends ShokupanRouter {
           name: data.name,
           email: data.email,
           picture: data.picture,
-          provider: provider2,
+          provider,
           raw: data
         };
       }
@@ -1591,15 +2330,19 @@ class AuthPlugin extends ShokupanRouter {
   }
 }
 function Compression(options = {}) {
-  const threshold = options.threshold ?? 1024;
+  const threshold = options.threshold ?? 512;
   return async (ctx, next) => {
     const acceptEncoding = ctx.headers.get("accept-encoding") || "";
     let method = null;
     if (acceptEncoding.includes("br")) method = "br";
+    else if (acceptEncoding.includes("zstd")) method = "zstd";
     else if (acceptEncoding.includes("gzip")) method = "gzip";
     else if (acceptEncoding.includes("deflate")) method = "deflate";
     if (!method) return next();
-    const response = await next();
+    let response = await next();
+    if (!(response instanceof Response) && ctx._finalResponse instanceof Response) {
+      response = ctx._finalResponse;
+    }
     if (response instanceof Response) {
       if (response.headers.has("Content-Encoding")) return response;
       const body = await response.arrayBuffer();
@@ -1611,97 +2354,506 @@ function Compression(options = {}) {
         });
       }
       let compressed;
-      if (method === "br") {
-        compressed = require("node:zlib").brotliCompressSync(body);
-      } else if (method === "gzip") {
-        compressed = Bun.gzipSync(body);
-      } else {
-        compressed = Bun.deflateSync(body);
+      switch (method) {
+        case "br":
+          const zlib = require("node:zlib");
+          compressed = await new Promise((res, rej) => zlib.brotliCompress(body, {
+            params: {
+              [zlib.constants.BROTLI_PARAM_QUALITY]: 4
+            }
+          }, (err, data) => {
+            if (err) return rej(err);
+            res(data);
+          }));
+          break;
+        case "gzip":
+          compressed = Bun.gzipSync(body);
+          break;
+        case "zstd":
+          compressed = await Bun.zstdCompress(body);
+          break;
+        default:
+          compressed = Bun.deflateSync(body);
+          break;
       }
       const headers = new Headers(response.headers);
       headers.set("Content-Encoding", method);
       headers.set("Content-Length", String(compressed.length));
-      headers.delete("Content-Length");
       return new Response(compressed, {
         status: response.status,
         statusText: response.statusText,
         headers
       });
     }
-    return response;
+    return response;
+  };
+}
+function Cors(options = {}) {
+  const defaults2 = {
+    origin: "*",
+    methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
+    preflightContinue: false,
+    optionsSuccessStatus: 204
+  };
+  const opts = { ...defaults2, ...options };
+  return async (ctx, next) => {
+    const headers = new Headers();
+    const origin = ctx.headers.get("origin");
+    const set = (k, v) => headers.set(k, v);
+    const append = (k, v) => headers.append(k, v);
+    if (opts.origin === "*") {
+      set("Access-Control-Allow-Origin", "*");
+    } else if (typeof opts.origin === "string") {
+      set("Access-Control-Allow-Origin", opts.origin);
+    } else if (Array.isArray(opts.origin)) {
+      if (origin && opts.origin.includes(origin)) {
+        set("Access-Control-Allow-Origin", origin);
+        append("Vary", "Origin");
+      }
+    } else if (typeof opts.origin === "function") {
+      const allowed = opts.origin(ctx);
+      if (allowed === true && origin) {
+        set("Access-Control-Allow-Origin", origin);
+        append("Vary", "Origin");
+      } else if (typeof allowed === "string") {
+        set("Access-Control-Allow-Origin", allowed);
+        append("Vary", "Origin");
+      }
+    }
+    if (opts.credentials) {
+      set("Access-Control-Allow-Credentials", "true");
+    }
+    if (opts.exposedHeaders) {
+      const exposed = Array.isArray(opts.exposedHeaders) ? opts.exposedHeaders.join(",") : opts.exposedHeaders;
+      if (exposed) set("Access-Control-Expose-Headers", exposed);
+    }
+    if (ctx.method === "OPTIONS") {
+      if (opts.methods) {
+        const methods = Array.isArray(opts.methods) ? opts.methods.join(",") : opts.methods;
+        set("Access-Control-Allow-Methods", methods);
+      }
+      if (opts.allowedHeaders) {
+        const h = Array.isArray(opts.allowedHeaders) ? opts.allowedHeaders.join(",") : opts.allowedHeaders;
+        set("Access-Control-Allow-Headers", h);
+      } else {
+        const reqHeaders = ctx.headers.get("access-control-request-headers");
+        if (reqHeaders) {
+          set("Access-Control-Allow-Headers", reqHeaders);
+          append("Vary", "Access-Control-Request-Headers");
+        }
+      }
+      if (opts.maxAge) {
+        set("Access-Control-Max-Age", String(opts.maxAge));
+      }
+      return new Response(null, {
+        status: opts.optionsSuccessStatus || 204,
+        headers
+      });
+    }
+    const response = await next();
+    if (response instanceof Response) {
+      for (const [key, value] of headers.entries()) {
+        response.headers.set(key, value);
+      }
+    }
+    return response;
+  };
+}
+function useExpress(expressMiddleware) {
+  return async (ctx, next) => {
+    return new Promise((resolve2, reject) => {
+      const reqStore = {
+        method: ctx.method,
+        url: ctx.url.pathname + ctx.url.search,
+        path: ctx.url.pathname,
+        query: ctx.query,
+        headers: ctx.headers,
+        get: (name) => ctx.headers.get(name)
+      };
+      const req = new Proxy(ctx.request, {
+        get(target, prop) {
+          if (prop in reqStore) return reqStore[prop];
+          const val = target[prop];
+          if (typeof val === "function") return val.bind(target);
+          return val;
+        },
+        set(target, prop, value) {
+          reqStore[prop] = value;
+          ctx.state[prop] = value;
+          return true;
+        }
+      });
+      const res = {
+        locals: {},
+        statusCode: 200,
+        setHeader: (name, value) => {
+          ctx.response.headers.set(name, value);
+        },
+        set: (name, value) => {
+          ctx.response.headers.set(name, value);
+        },
+        end: (chunk) => {
+          resolve2(new Response(chunk, { status: res.statusCode }));
+        },
+        status: (code) => {
+          res.statusCode = code;
+          return res;
+        },
+        send: (body) => {
+          let content = body;
+          if (typeof body === "object") content = JSON.stringify(body);
+          resolve2(new Response(content, { status: res.statusCode }));
+        },
+        json: (body) => {
+          resolve2(Response.json(body, { status: res.statusCode }));
+        }
+      };
+      try {
+        expressMiddleware(req, res, (err) => {
+          if (err) return reject(err);
+          resolve2(next());
+        });
+      } catch (err) {
+        reject(err);
+      }
+    });
+  };
+}
+class ValidationError extends Error {
+  constructor(errors) {
+    super("Validation Error");
+    this.errors = errors;
+  }
+  status = 400;
+}
+function isZod(schema) {
+  return typeof schema?.safeParse === "function";
+}
+async function validateZod(schema, data) {
+  const result = await schema.safeParseAsync(data);
+  if (!result.success) {
+    throw new ValidationError(result.error.errors);
+  }
+  return result.data;
+}
+function isTypeBox(schema) {
+  return typeof schema?.Check === "function" && typeof schema?.Errors === "function";
+}
+function validateTypeBox(schema, data) {
+  if (!schema.Check(data)) {
+    throw new ValidationError([...schema.Errors(data)]);
+  }
+  return data;
+}
+function isAjv(schema) {
+  return typeof schema === "function" && "errors" in schema;
+}
+function validateAjv(schema, data) {
+  const valid = schema(data);
+  if (!valid) {
+    throw new ValidationError(schema.errors);
+  }
+  return data;
+}
+const valibot = (schema, parser) => {
+  return {
+    _valibot: true,
+    schema,
+    parser
+  };
+};
+function isValibotWrapper(schema) {
+  return schema?._valibot === true;
+}
+async function validateValibotWrapper(wrapper, data) {
+  const result = await wrapper.parser(wrapper.schema, data);
+  if (!result.success) {
+    throw new ValidationError(result.issues);
+  }
+  return result.output;
+}
+function isClass(schema) {
+  try {
+    if (typeof schema === "function" && /^\s*class\s+/.test(schema.toString())) {
+      return true;
+    }
+    return typeof schema === "function" && schema.prototype && schema.name;
+  } catch {
+    return false;
+  }
+}
+async function validateClassValidator(schema, data) {
+  const object = plainToInstance(schema, data);
+  try {
+    await validateOrReject(object);
+    return object;
+  } catch (errors) {
+    const formattedErrors = Array.isArray(errors) ? errors.map((err) => ({
+      property: err.property,
+      constraints: err.constraints,
+      children: err.children
+    })) : errors;
+    throw new ValidationError(formattedErrors);
+  }
+}
+const safelyGetBody = async (ctx) => {
+  const req = ctx.req;
+  if (req._bodyParsed) {
+    return req._bodyValue;
+  }
+  try {
+    let data;
+    if (typeof req.json === "function") {
+      data = await req.json();
+    } else {
+      data = req.body;
+      if (typeof data === "string") {
+        try {
+          data = JSON.parse(data);
+        } catch {
+        }
+      }
+    }
+    req._bodyParsed = true;
+    req._bodyValue = data;
+    Object.defineProperty(req, "json", {
+      value: async () => req._bodyValue,
+      configurable: true
+    });
+    return data;
+  } catch (e) {
+    return {};
+  }
+};
+function validate(config) {
+  return async (ctx, next) => {
+    const dataToValidate = {};
+    if (config.params) dataToValidate.params = ctx.params;
+    let queryObj;
+    if (config.query) {
+      const url = new URL(ctx.req.url);
+      queryObj = Object.fromEntries(url.searchParams.entries());
+      dataToValidate.query = queryObj;
+    }
+    if (config.headers) dataToValidate.headers = Object.fromEntries(ctx.req.headers.entries());
+    let body;
+    if (config.body) {
+      body = await safelyGetBody(ctx);
+      dataToValidate.body = body;
+    }
+    if (ctx.app?.applicationConfig.hooks?.beforeValidate) {
+      await ctx.app.applicationConfig.hooks.beforeValidate(ctx, dataToValidate);
+    }
+    if (config.params) {
+      ctx.params = await runValidation(config.params, ctx.params);
+    }
+    let validQuery;
+    if (config.query && queryObj) {
+      validQuery = await runValidation(config.query, queryObj);
+    }
+    if (config.headers) {
+      const headersObj = Object.fromEntries(ctx.req.headers.entries());
+      await runValidation(config.headers, headersObj);
+    }
+    let validBody;
+    if (config.body) {
+      const b = body ?? await safelyGetBody(ctx);
+      validBody = await runValidation(config.body, b);
+      const req = ctx.req;
+      req._bodyValue = validBody;
+      Object.defineProperty(req, "json", {
+        value: async () => validBody,
+        configurable: true
+      });
+      ctx.body = validBody;
+    }
+    if (ctx.app?.applicationConfig.hooks?.afterValidate) {
+      const validatedData = { ...dataToValidate };
+      if (config.params) validatedData.params = ctx.params;
+      if (config.query) validatedData.query = validQuery;
+      if (config.body) validatedData.body = validBody;
+      await ctx.app.applicationConfig.hooks.afterValidate(ctx, validatedData);
+    }
+    return next();
   };
 }
-function Cors(options = {}) {
-  const defaults2 = {
-    origin: "*",
-    methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
-    preflightContinue: false,
-    optionsSuccessStatus: 204
-  };
-  const opts = { ...defaults2, ...options };
+async function runValidation(schema, data) {
+  if (isZod(schema)) {
+    return validateZod(schema, data);
+  }
+  if (isTypeBox(schema)) {
+    return validateTypeBox(schema, data);
+  }
+  if (isAjv(schema)) {
+    return validateAjv(schema, data);
+  }
+  if (isValibotWrapper(schema)) {
+    return validateValibotWrapper(schema, data);
+  }
+  if (isClass(schema)) {
+    return validateClassValidator(schema, data);
+  }
+  if (isTypeBox(schema)) {
+    return validateTypeBox(schema, data);
+  }
+  if (isAjv(schema)) {
+    return validateAjv(schema, data);
+  }
+  if (isValibotWrapper(schema)) {
+    return validateValibotWrapper(schema, data);
+  }
+  if (typeof schema === "function") {
+    return schema(data);
+  }
+  throw new Error("Unknown validator type provided. Please use a supported library (Zod, Ajv, TypeBox) or a custom function.");
+}
+const ajv = new Ajv({ coerceTypes: true, allErrors: true });
+addFormats(ajv);
+const compiledValidators = /* @__PURE__ */ new WeakMap();
+function openApiValidator() {
   return async (ctx, next) => {
-    const headers = new Headers();
-    const origin = ctx.headers.get("origin");
-    const set = (k, v) => headers.set(k, v);
-    const append = (k, v) => headers.append(k, v);
-    if (opts.origin === "*") {
-      set("Access-Control-Allow-Origin", "*");
-    } else if (typeof opts.origin === "string") {
-      set("Access-Control-Allow-Origin", opts.origin);
-    } else if (Array.isArray(opts.origin)) {
-      if (origin && opts.origin.includes(origin)) {
-        set("Access-Control-Allow-Origin", origin);
-        append("Vary", "Origin");
-      }
-    } else if (typeof opts.origin === "function") {
-      const allowed = opts.origin(ctx);
-      if (allowed === true && origin) {
-        set("Access-Control-Allow-Origin", origin);
-        append("Vary", "Origin");
-      } else if (typeof allowed === "string") {
-        set("Access-Control-Allow-Origin", allowed);
-        append("Vary", "Origin");
+    const app = ctx.app;
+    if (!app || !app.openApiSpec) {
+      return next();
+    }
+    let cache = compiledValidators.get(app);
+    if (!cache) {
+      cache = compileValidators(app.openApiSpec);
+      compiledValidators.set(app, cache);
+    }
+    const method = ctx.req.method.toLowerCase();
+    let matchPath;
+    if (cache.has(ctx.path)) {
+      matchPath = ctx.path;
+    } else {
+      for (const specPath of cache.keys()) {
+        const regexStr = "^" + specPath.replace(/{([^}]+)}/g, "([^/]+)") + "$";
+        const regex = new RegExp(regexStr);
+        const match = regex.exec(ctx.path);
+        if (match) {
+          matchPath = specPath;
+          break;
+        }
       }
     }
-    if (opts.credentials) {
-      set("Access-Control-Allow-Credentials", "true");
+    if (!matchPath) {
+      return next();
     }
-    if (opts.exposedHeaders) {
-      const exposed = Array.isArray(opts.exposedHeaders) ? opts.exposedHeaders.join(",") : opts.exposedHeaders;
-      if (exposed) set("Access-Control-Expose-Headers", exposed);
+    const validators = cache.get(matchPath)?.[method];
+    if (!validators) {
+      return next();
     }
-    if (ctx.method === "OPTIONS") {
-      if (opts.methods) {
-        const methods = Array.isArray(opts.methods) ? opts.methods.join(",") : opts.methods;
-        set("Access-Control-Allow-Methods", methods);
+    const errors = [];
+    if (validators.body) {
+      let body;
+      try {
+        body = await ctx.req.json().catch(() => ({}));
+      } catch {
+        body = {};
       }
-      if (opts.allowedHeaders) {
-        const h = Array.isArray(opts.allowedHeaders) ? opts.allowedHeaders.join(",") : opts.allowedHeaders;
-        set("Access-Control-Allow-Headers", h);
-      } else {
-        const reqHeaders = ctx.headers.get("access-control-request-headers");
-        if (reqHeaders) {
-          set("Access-Control-Allow-Headers", reqHeaders);
-          append("Vary", "Access-Control-Request-Headers");
+      const valid = validators.body(body);
+      if (!valid && validators.body.errors) {
+        errors.push(...validators.body.errors.map((e) => ({ ...e, location: "body" })));
+      }
+    }
+    if (validators.query) {
+      const query = Object.fromEntries(new URL(ctx.req.url).searchParams.entries());
+      const valid = validators.query(query);
+      if (!valid && validators.query.errors) {
+        errors.push(...validators.query.errors.map((e) => ({ ...e, location: "query" })));
+      }
+    }
+    if (validators.params) {
+      let params = ctx.params;
+      if (Object.keys(params).length === 0 && matchPath) {
+        const paramNames = (matchPath.match(/{([^}]+)}/g) || []).map((s) => s.slice(1, -1));
+        if (paramNames.length > 0) {
+          const regexStr = "^" + matchPath.replace(/{([^}]+)}/g, "([^/]+)") + "$";
+          const regex = new RegExp(regexStr);
+          const match = regex.exec(ctx.path);
+          if (match) {
+            params = {};
+            paramNames.forEach((name, i) => {
+              params[name] = match[i + 1];
+            });
+          }
         }
       }
-      if (opts.maxAge) {
-        set("Access-Control-Max-Age", String(opts.maxAge));
+      const valid = validators.params(params);
+      if (!valid && validators.params.errors) {
+        errors.push(...validators.params.errors.map((e) => ({ ...e, location: "path" })));
       }
-      return new Response(null, {
-        status: opts.optionsSuccessStatus || 204,
-        headers
-      });
     }
-    const response = await next();
-    if (response instanceof Response) {
-      for (const [key, value] of headers.entries()) {
-        response.headers.set(key, value);
+    if (validators.headers) {
+      const headers = Object.fromEntries(ctx.req.headers.entries());
+      const valid = validators.headers(headers);
+      if (!valid && validators.headers.errors) {
+        errors.push(...validators.headers.errors.map((e) => ({ ...e, location: "header" })));
       }
     }
-    return response;
+    if (errors.length > 0) {
+      throw new ValidationError(errors);
+    }
+    return next();
   };
 }
+function compileValidators(spec) {
+  const cache = /* @__PURE__ */ new Map();
+  for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+    const pathValidators = {};
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (method === "parameters" || method === "summary" || method === "description") continue;
+      const oper = operation;
+      const validators = {};
+      if (oper.requestBody?.content?.["application/json"]?.schema) {
+        validators.body = ajv.compile(oper.requestBody.content["application/json"].schema);
+      }
+      const parameters = [...oper.parameters || [], ...pathItem.parameters || []];
+      const queryProps = {};
+      const pathProps = {};
+      const headerProps = {};
+      const queryRequired = [];
+      const pathRequired = [];
+      const headerRequired = [];
+      for (const param of parameters) {
+        if (param.in === "query") {
+          queryProps[param.name] = param.schema || {};
+          if (param.required) queryRequired.push(param.name);
+        } else if (param.in === "path") {
+          pathProps[param.name] = param.schema || {};
+          pathRequired.push(param.name);
+        } else if (param.in === "header") {
+          headerProps[param.name] = param.schema || {};
+          if (param.required) headerRequired.push(param.name);
+        }
+      }
+      if (Object.keys(queryProps).length > 0) {
+        validators.query = ajv.compile({
+          type: "object",
+          properties: queryProps,
+          required: queryRequired.length > 0 ? queryRequired : void 0
+        });
+      }
+      if (Object.keys(pathProps).length > 0) {
+        validators.params = ajv.compile({
+          type: "object",
+          properties: pathProps,
+          required: pathRequired.length > 0 ? pathRequired : void 0
+        });
+      }
+      if (Object.keys(headerProps).length > 0) {
+        validators.headers = ajv.compile({
+          type: "object",
+          properties: headerProps,
+          required: headerRequired.length > 0 ? headerRequired : void 0
+        });
+      }
+      pathValidators[method] = validators;
+    }
+    cache.set(path, pathValidators);
+  }
+  return cache;
+}
 function RateLimit(options = {}) {
   const windowMs = options.windowMs || 60 * 1e3;
   const max = options.max || 5;
@@ -1721,7 +2873,7 @@ function RateLimit(options = {}) {
       }
     }
   }, windowMs);
-  if (interval.unref) interval.unref();
+  interval.unref?.();
   return async (ctx, next) => {
     if (skip(ctx)) return next();
     const key = keyGenerator(ctx);
@@ -1792,10 +2944,43 @@ class ScalarPlugin extends ShokupanRouter {
     this.get("/scalar.js", (ctx) => {
       return ctx.file(__dirname + "/../../node_modules/@scalar/api-reference/dist/browser/standalone.js");
     });
-    this.get("/openapi.json", (ctx) => {
-      return (this.root || this).generateApiSpec();
+    this.get("/openapi.json", async (ctx) => {
+      let spec;
+      if (this.root.openApiSpec) {
+        try {
+          spec = structuredClone(this.root.openApiSpec);
+        } catch (e) {
+          spec = Object.assign({}, this.root.openApiSpec);
+        }
+      } else {
+        spec = await (this.root || this).generateApiSpec();
+      }
+      if (this.pluginOptions.baseDocument) {
+        deepMerge(spec, this.pluginOptions.baseDocument);
+      }
+      return ctx.json(spec);
     });
   }
+  // New lifecycle method to be called by router.mount
+  onMount(parent) {
+    if (parent.onStart) {
+      parent.onStart(async () => {
+        if (this.pluginOptions.enableStaticAnalysis) {
+          try {
+            const entrypoint = process.argv[1];
+            console.log(`[ScalarPlugin] Running eager static analysis on entrypoint: ${entrypoint}`);
+            const analyzer = new OpenAPIAnalyzer(process.cwd(), entrypoint);
+            let staticSpec = await analyzer.analyze();
+            if (!this.pluginOptions.baseDocument) this.pluginOptions.baseDocument = {};
+            deepMerge(this.pluginOptions.baseDocument, staticSpec);
+            console.log("[ScalarPlugin] Static analysis completed successfully.");
+          } catch (err) {
+            console.error("[ScalarPlugin] Failed to run static analysis:", err);
+          }
+        }
+      });
+    }
+  }
 }
 function SecurityHeaders(options = {}) {
   return async (ctx, next) => {
@@ -2102,134 +3287,6 @@ function Session(options) {
     return result;
   };
 }
-class ValidationError extends Error {
-  constructor(errors) {
-    super("Validation Error");
-    this.errors = errors;
-  }
-  status = 400;
-}
-function isZod(schema) {
-  return typeof schema?.safeParse === "function";
-}
-async function validateZod(schema, data) {
-  const result = await schema.safeParseAsync(data);
-  if (!result.success) {
-    throw new ValidationError(result.error.errors);
-  }
-  return result.data;
-}
-function isTypeBox(schema) {
-  return typeof schema?.Check === "function" && typeof schema?.Errors === "function";
-}
-function validateTypeBox(schema, data) {
-  if (!schema.Check(data)) {
-    throw new ValidationError([...schema.Errors(data)]);
-  }
-  return data;
-}
-function isAjv(schema) {
-  return typeof schema === "function" && "errors" in schema;
-}
-function validateAjv(schema, data) {
-  const valid = schema(data);
-  if (!valid) {
-    throw new ValidationError(schema.errors);
-  }
-  return data;
-}
-const valibot = (schema, parser) => {
-  return {
-    _valibot: true,
-    schema,
-    parser
-  };
-};
-function isValibotWrapper(schema) {
-  return schema?._valibot === true;
-}
-async function validateValibotWrapper(wrapper, data) {
-  const result = await wrapper.parser(wrapper.schema, data);
-  if (!result.success) {
-    throw new ValidationError(result.issues);
-  }
-  return result.output;
-}
-const safelyGetBody = async (ctx) => {
-  const req = ctx.req;
-  if (req._bodyParsed) {
-    return req._bodyValue;
-  }
-  try {
-    let data;
-    if (typeof req.json === "function") {
-      data = await req.json();
-    } else {
-      data = req.body;
-      if (typeof data === "string") {
-        try {
-          data = JSON.parse(data);
-        } catch {
-        }
-      }
-    }
-    req._bodyParsed = true;
-    req._bodyValue = data;
-    Object.defineProperty(req, "json", {
-      value: async () => req._bodyValue,
-      configurable: true
-    });
-    return data;
-  } catch (e) {
-    return {};
-  }
-};
-function validate(config) {
-  return async (ctx, next) => {
-    if (config.params) {
-      ctx.params = await runValidation(config.params, ctx.params);
-    }
-    if (config.query) {
-      const url = new URL(ctx.req.url);
-      const queryObj = Object.fromEntries(url.searchParams.entries());
-      await runValidation(config.query, queryObj);
-    }
-    if (config.headers) {
-      const headersObj = Object.fromEntries(ctx.req.headers.entries());
-      await runValidation(config.headers, headersObj);
-    }
-    if (config.body) {
-      const body = await safelyGetBody(ctx);
-      const validBody = await runValidation(config.body, body);
-      const req = ctx.req;
-      req._bodyValue = validBody;
-      Object.defineProperty(req, "json", {
-        value: async () => validBody,
-        configurable: true
-      });
-      ctx.body = validBody;
-    }
-    return next();
-  };
-}
-async function runValidation(schema, data) {
-  if (isZod(schema)) {
-    return validateZod(schema, data);
-  }
-  if (isTypeBox(schema)) {
-    return validateTypeBox(schema, data);
-  }
-  if (isAjv(schema)) {
-    return validateAjv(schema, data);
-  }
-  if (isValibotWrapper(schema)) {
-    return validateValibotWrapper(schema, data);
-  }
-  if (typeof schema === "function") {
-    return schema(data);
-  }
-  throw new Error("Unknown validator type provided. Please use a supported library (Zod, Ajv, TypeBox) or a custom function.");
-}
 export {
   $appRoot,
   $childControllers,
@@ -2244,6 +3301,8 @@ export {
   $parent,
   $routeArgs,
   $routeMethods,
+  $routeSpec,
+  $routes,
   All,
   AuthPlugin,
   Body,
@@ -2279,9 +3338,12 @@ export {
   ShokupanRequest,
   ShokupanResponse,
   ShokupanRouter,
+  Spec,
   Use,
   ValidationError,
   compose,
+  openApiValidator,
+  useExpress,
   valibot,
   validate
 };