vector-framework 1.1.1 → 1.2.1

package/dist/cli.js

@@ -1,272 +1,168 @@
 #!/usr/bin/env bun
 // @bun
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
 
-// src/dev/route-generator.ts
-var exports_route_generator = {};
-__export(exports_route_generator, {
-  RouteGenerator: () => RouteGenerator
-});
-import { promises as fs } from "fs";
-import { dirname, relative } from "path";
+// src/cli/index.ts
+import { watch } from "fs";
+import { parseArgs } from "util";
 
-class RouteGenerator {
-  outputPath;
-  constructor(outputPath = "./.vector/routes.generated.ts") {
-    this.outputPath = outputPath;
+// src/cli/option-resolution.ts
+function resolveRoutesDir(configRoutesDir, hasRoutesOption, cliRoutes) {
+  if (hasRoutesOption) {
+    return cliRoutes;
   }
-  async generate(routes) {
-    const outputDir = dirname(this.outputPath);
-    await fs.mkdir(outputDir, { recursive: true });
-    const imports = [];
-    const groupedByFile = new Map;
-    for (const route of routes) {
-      if (!groupedByFile.has(route.path)) {
-        groupedByFile.set(route.path, []);
-      }
-      groupedByFile.get(route.path).push(route);
+  return configRoutesDir ?? cliRoutes;
+}
+function parseAndValidatePort(value) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    throw new Error(`Invalid port value: ${String(value)}`);
+  }
+  return parsed;
+}
+function resolvePort(configPort, hasPortOption, cliPort) {
+  if (hasPortOption) {
+    return parseAndValidatePort(cliPort);
+  }
+  const resolved = configPort ?? cliPort;
+  return parseAndValidatePort(resolved);
+}
+function resolveHost(configHost, hasHostOption, cliHost) {
+  const resolved = hasHostOption ? cliHost : configHost ?? cliHost;
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new Error(`Invalid host value: ${String(resolved)}`);
+  }
+  return resolved;
+}
+
+// src/cli/graceful-shutdown.ts
+function installGracefulShutdownHandlers(options) {
+  const on = options.on ?? ((event, listener) => process.on(event, listener));
+  const off = options.off ?? ((event, listener) => process.off(event, listener));
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const logError = options.logError ?? console.error;
+  let shuttingDown = false;
+  const handleSignal = async (signal) => {
+    if (shuttingDown) {
+      return;
     }
-    let importIndex = 0;
-    const routeEntries = [];
-    for (const [filePath, fileRoutes] of groupedByFile) {
-      const relativePath = relative(dirname(this.outputPath), filePath).replace(/\\/g, "/").replace(/\.(ts|js)$/, "");
-      const importName = `route_${importIndex++}`;
-      const namedImports = fileRoutes.filter((r) => r.name !== "default").map((r) => r.name);
-      if (fileRoutes.some((r) => r.name === "default")) {
-        if (namedImports.length > 0) {
-          imports.push(`import ${importName}, { ${namedImports.join(", ")} } from '${relativePath}';`);
-        } else {
-          imports.push(`import ${importName} from '${relativePath}';`);
+    shuttingDown = true;
+    try {
+      const target = options.getTarget();
+      if (target) {
+        if (typeof target.shutdown === "function") {
+          await target.shutdown();
+        } else if (typeof target.stop === "function") {
+          target.stop();
         }
-      } else if (namedImports.length > 0) {
-        imports.push(`import { ${namedImports.join(", ")} } from '${relativePath}';`);
-      }
-      for (const route of fileRoutes) {
-        const routeVar = route.name === "default" ? importName : route.name;
-        routeEntries.push(`  ${routeVar},`);
       }
+      exit(0);
+    } catch (error) {
+      logError(`[vector] Graceful shutdown failed after ${signal}:`, error);
+      exit(1);
     }
-    const content = `// This file is auto-generated. Do not edit manually.
-// Generated at: ${new Date().toISOString()}
-
-${imports.join(`
-`)}
+  };
+  const onSigint = () => {
+    handleSignal("SIGINT");
+  };
+  const onSigterm = () => {
+    handleSignal("SIGTERM");
+  };
+  on("SIGINT", onSigint);
+  on("SIGTERM", onSigterm);
+  return () => {
+    off("SIGINT", onSigint);
+    off("SIGTERM", onSigterm);
+  };
+}
 
-export const routes = [
-${routeEntries.join(`
-`)}
-];
+// src/core/config-loader.ts
+import { existsSync } from "fs";
+import { resolve, isAbsolute } from "path";
 
-export default routes;
-`;
-    await fs.writeFile(this.outputPath, content, "utf-8");
-  }
-  async generateDynamic(routes) {
-    const routeEntries = [];
-    for (const route of routes) {
-      const routeObj = JSON.stringify({
-        method: route.method,
-        path: route.options.path,
-        options: route.options
-      });
-      routeEntries.push(`  await import('${route.path}').then(m => ({ 
-        ...${routeObj}, 
-        handler: m.${route.name === "default" ? "default" : route.name} 
-      }))`);
-    }
-    return `export const loadRoutes = async () => {
-  return Promise.all([
-${routeEntries.join(`,
-`)}
-  ]);
-};`;
-  }
+// src/utils/path.ts
+function toFileUrl(path) {
+  return process.platform === "win32" ? `file:///${path.replace(/\\/g, "/")}` : path;
+}
+function buildRouteRegex(path) {
+  return RegExp(`^${path.replace(/\/+(\/|$)/g, "$1").replace(/(\/?\.?):(\w+)\+/g, "($1(?<$2>[\\s\\S]+))").replace(/(\/?\.?):(\w+)/g, "($1(?<$2>[^$1/]+?))").replace(/\./g, "\\.").replace(/(\/?)\*/g, "($1.*)?")}/*$`);
 }
-var init_route_generator = () => {};
 
-// src/dev/route-scanner.ts
-var exports_route_scanner = {};
-__export(exports_route_scanner, {
-  RouteScanner: () => RouteScanner
-});
-import { existsSync, promises as fs2 } from "fs";
-import { join, relative as relative2, resolve, sep } from "path";
-var RouteScanner;
-var init_route_scanner = __esm(() => {
-  RouteScanner = class RouteScanner {
-    routesDir;
-    excludePatterns;
-    static DEFAULT_EXCLUDE_PATTERNS = [
-      "*.test.ts",
-      "*.test.js",
-      "*.test.tsx",
-      "*.test.jsx",
-      "*.spec.ts",
-      "*.spec.js",
-      "*.spec.tsx",
-      "*.spec.jsx",
-      "*.tests.ts",
-      "*.tests.js",
-      "**/__tests__/**",
-      "*.interface.ts",
-      "*.type.ts",
-      "*.d.ts"
-    ];
-    constructor(routesDir = "./routes", excludePatterns) {
-      this.routesDir = resolve(process.cwd(), routesDir);
-      this.excludePatterns = excludePatterns || RouteScanner.DEFAULT_EXCLUDE_PATTERNS;
-    }
-    async scan() {
-      const routes = [];
-      if (!existsSync(this.routesDir)) {
-        return [];
-      }
+// src/core/config-loader.ts
+class ConfigLoader {
+  configPath;
+  config = null;
+  configSource = "default";
+  constructor(configPath) {
+    const path = configPath || "vector.config.ts";
+    this.configPath = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  }
+  async load() {
+    if (existsSync(this.configPath)) {
       try {
-        await this.scanDirectory(this.routesDir, routes);
+        const userConfigPath = toFileUrl(this.configPath);
+        const userConfig = await import(userConfigPath);
+        this.config = userConfig.default || userConfig;
+        this.configSource = "user";
       } catch (error) {
-        if (error.code === "ENOENT") {
-          console.warn(`  \u2717 Routes directory not accessible: ${this.routesDir}`);
-          return [];
-        }
-        throw error;
-      }
-      return routes;
-    }
-    isExcluded(filePath) {
-      const relativePath = relative2(this.routesDir, filePath);
-      for (const pattern of this.excludePatterns) {
-        const regexPattern = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "__GLOBSTAR__").replace(/\*/g, "[^/]*").replace(/__GLOBSTAR__/g, ".*").replace(/\?/g, ".");
-        const regex = new RegExp(`^${regexPattern}$`);
-        const filename = relativePath.split(sep).pop() || "";
-        if (regex.test(relativePath) || regex.test(filename)) {
-          return true;
-        }
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`[vector] Failed to load config from ${this.configPath}: ${msg}`);
+        console.error("[vector] Server is using default configuration. Fix your config file and restart.");
+        this.config = {};
       }
-      return false;
+    } else {
+      this.config = {};
     }
-    async scanDirectory(dir, routes, basePath = "") {
-      const entries = await fs2.readdir(dir);
-      for (const entry of entries) {
-        const fullPath = join(dir, entry);
-        const stats = await fs2.stat(fullPath);
-        if (stats.isDirectory()) {
-          const newBasePath = basePath ? `${basePath}/${entry}` : entry;
-          await this.scanDirectory(fullPath, routes, newBasePath);
-        } else if (entry.endsWith(".ts") || entry.endsWith(".js")) {
-          if (this.isExcluded(fullPath)) {
-            continue;
-          }
-          const routePath = relative2(this.routesDir, fullPath).replace(/\.(ts|js)$/, "").split(sep).join("/");
-          try {
-            const importPath = process.platform === "win32" ? `file:///${fullPath.replace(/\\/g, "/")}` : fullPath;
-            const module = await import(importPath);
-            if (module.default && typeof module.default === "function") {
-              routes.push({
-                name: "default",
-                path: fullPath,
-                method: "GET",
-                options: {
-                  method: "GET",
-                  path: `/${routePath}`,
-                  expose: true
-                }
-              });
-            }
-            for (const [name, value] of Object.entries(module)) {
-              if (name === "default")
-                continue;
-              if (value && typeof value === "object" && "entry" in value && "options" in value && "handler" in value) {
-                const routeDef = value;
-                routes.push({
-                  name,
-                  path: fullPath,
-                  method: routeDef.options.method,
-                  options: routeDef.options
-                });
-              } else if (Array.isArray(value) && value.length >= 4) {
-                const [method, , , path] = value;
-                routes.push({
-                  name,
-                  path: fullPath,
-                  method,
-                  options: {
-                    method,
-                    path,
-                    expose: true
-                  }
-                });
-              }
-            }
-          } catch (error) {
-            console.error(`Failed to load route from ${fullPath}:`, error);
-          }
-        }
-      }
+    return await this.buildLegacyConfig();
+  }
+  getConfigSource() {
+    return this.configSource;
+  }
+  async buildLegacyConfig() {
+    const config = {};
+    if (this.config) {
+      config.port = this.config.port;
+      config.hostname = this.config.hostname;
+      config.reusePort = this.config.reusePort;
+      config.development = this.config.development;
+      config.routesDir = this.config.routesDir || "./routes";
+      config.routeExcludePatterns = this.config.routeExcludePatterns;
+      config.idleTimeout = this.config.idleTimeout;
+      config.defaults = this.config.defaults;
+      config.openapi = this.config.openapi;
+      config.startup = this.config.startup;
+      config.shutdown = this.config.shutdown;
     }
-    enableWatch(callback) {
-      if (typeof Bun !== "undefined" && Bun.env.NODE_ENV === "development") {
-        console.log(`Watching for route changes in ${this.routesDir}`);
-        setInterval(async () => {
-          await callback();
-        }, 1000);
+    config.autoDiscover = true;
+    if (this.config?.cors) {
+      if (typeof this.config.cors === "boolean") {
+        config.cors = this.config.cors ? {
+          origin: "*",
+          credentials: true,
+          allowHeaders: "Content-Type, Authorization",
+          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+          exposeHeaders: "Authorization",
+          maxAge: 86400
+        } : undefined;
+      } else {
+        config.cors = this.config.cors;
       }
     }
-  };
-});
-
-// src/cli/index.ts
-import { watch } from "fs";
-import { parseArgs } from "util";
-
-// src/auth/protected.ts
-class AuthManager {
-  protectedHandler = null;
-  setProtectedHandler(handler) {
-    this.protectedHandler = handler;
-  }
-  async authenticate(request) {
-    if (!this.protectedHandler) {
-      throw new Error("Protected handler not configured. Use vector.protected() to set authentication handler.");
+    if (this.config?.before) {
+      config.before = this.config.before;
     }
-    try {
-      const authUser = await this.protectedHandler(request);
-      request.authUser = authUser;
-      return authUser;
-    } catch (error) {
-      throw new Error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+    if (this.config?.after) {
+      config.finally = this.config.after;
     }
+    return config;
   }
-  isAuthenticated(request) {
-    return !!request.authUser;
+  async loadAuthHandler() {
+    return this.config?.auth || null;
   }
-  getUser(request) {
-    return request.authUser || null;
+  async loadCacheHandler() {
+    return this.config?.cache || null;
+  }
+  getConfig() {
+    return this.config;
   }
 }
 
@@ -345,6 +241,41 @@ var CONTENT_TYPES = {
   FORM_URLENCODED: "application/x-www-form-urlencoded",
   MULTIPART: "multipart/form-data"
 };
+var STATIC_RESPONSES = {
+  NOT_FOUND: new Response(JSON.stringify({ error: true, message: "Not Found", statusCode: 404 }), {
+    status: 404,
+    headers: { "content-type": "application/json" }
+  })
+};
+
+// src/auth/protected.ts
+class AuthManager {
+  protectedHandler = null;
+  setProtectedHandler(handler) {
+    this.protectedHandler = handler;
+  }
+  clearProtectedHandler() {
+    this.protectedHandler = null;
+  }
+  async authenticate(request) {
+    if (!this.protectedHandler) {
+      throw new Error("Protected handler not configured. Use vector.protected() to set authentication handler.");
+    }
+    try {
+      const authUser = await this.protectedHandler(request);
+      request.authUser = authUser;
+      return authUser;
+    } catch (error) {
+      throw new Error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  isAuthenticated(request) {
+    return !!request.authUser;
+  }
+  getUser(request) {
+    return request.authUser || null;
+  }
+}
 
 // src/cache/manager.ts
 class CacheManager {
@@ -355,6 +286,9 @@ class CacheManager {
   setCacheHandler(handler) {
     this.cacheHandler = handler;
   }
+  clearCacheHandler() {
+    this.cacheHandler = null;
+  }
   async get(key, factory, ttl = DEFAULT_CONFIG.CACHE_TTL) {
     if (ttl <= 0) {
       return factory();
@@ -444,33 +378,227 @@ class CacheManager {
   }
   generateKey(request, options) {
     const url = request._parsedUrl ?? new URL(request.url);
-    const parts = [
-      request.method,
-      url.pathname,
-      url.search,
-      options?.authUser?.id != null ? String(options.authUser.id) : "anonymous"
-    ];
-    return parts.join(":");
+    const userId = options?.authUser?.id != null ? String(options.authUser.id) : "anonymous";
+    return `${request.method}:${url.pathname}:${url.search}:${userId}`;
   }
 }
 
-// src/core/vector.ts
-init_route_generator();
-init_route_scanner();
+// src/dev/route-generator.ts
+import { promises as fs } from "fs";
+import { dirname, relative } from "path";
 
-// src/middleware/manager.ts
-class MiddlewareManager {
-  beforeHandlers = [];
-  finallyHandlers = [];
-  addBefore(...handlers) {
-    this.beforeHandlers.push(...handlers);
-  }
-  addFinally(...handlers) {
-    this.finallyHandlers.push(...handlers);
+class RouteGenerator {
+  outputPath;
+  constructor(outputPath = "./.vector/routes.generated.ts") {
+    this.outputPath = outputPath;
   }
-  async executeBefore(request) {
-    let currentRequest = request;
-    for (const handler of this.beforeHandlers) {
+  async generate(routes) {
+    const outputDir = dirname(this.outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+    const imports = [];
+    const groupedByFile = new Map;
+    for (const route of routes) {
+      if (!groupedByFile.has(route.path)) {
+        groupedByFile.set(route.path, []);
+      }
+      groupedByFile.get(route.path).push(route);
+    }
+    let importIndex = 0;
+    const routeEntries = [];
+    for (const [filePath, fileRoutes] of groupedByFile) {
+      const relativePath = relative(dirname(this.outputPath), filePath).replace(/\\/g, "/").replace(/\.(ts|js)$/, "");
+      const importName = `route_${importIndex++}`;
+      const namedImports = fileRoutes.filter((r) => r.name !== "default").map((r) => r.name);
+      if (fileRoutes.some((r) => r.name === "default")) {
+        if (namedImports.length > 0) {
+          imports.push(`import ${importName}, { ${namedImports.join(", ")} } from '${relativePath}';`);
+        } else {
+          imports.push(`import ${importName} from '${relativePath}';`);
+        }
+      } else if (namedImports.length > 0) {
+        imports.push(`import { ${namedImports.join(", ")} } from '${relativePath}';`);
+      }
+      for (const route of fileRoutes) {
+        const routeVar = route.name === "default" ? importName : route.name;
+        routeEntries.push(`  ${routeVar},`);
+      }
+    }
+    const content = `// This file is auto-generated. Do not edit manually.
+// Generated at: ${new Date().toISOString()}
+
+${imports.join(`
+`)}
+
+export const routes = [
+${routeEntries.join(`
+`)}
+];
+
+export default routes;
+`;
+    await fs.writeFile(this.outputPath, content, "utf-8");
+  }
+  async generateDynamic(routes) {
+    const routeEntries = [];
+    for (const route of routes) {
+      const routeObj = JSON.stringify({
+        method: route.method,
+        path: route.options.path,
+        options: route.options
+      });
+      routeEntries.push(`  await import('${route.path}').then(m => ({ 
+        ...${routeObj}, 
+        handler: m.${route.name === "default" ? "default" : route.name} 
+      }))`);
+    }
+    return `export const loadRoutes = async () => {
+  return Promise.all([
+${routeEntries.join(`,
+`)}
+  ]);
+};`;
+  }
+}
+
+// src/dev/route-scanner.ts
+import { existsSync as existsSync2, promises as fs2 } from "fs";
+import { join, relative as relative2, resolve as resolve2, sep } from "path";
+
+class RouteScanner {
+  routesDir;
+  excludePatterns;
+  static DEFAULT_EXCLUDE_PATTERNS = [
+    "*.test.ts",
+    "*.test.js",
+    "*.test.tsx",
+    "*.test.jsx",
+    "*.spec.ts",
+    "*.spec.js",
+    "*.spec.tsx",
+    "*.spec.jsx",
+    "*.tests.ts",
+    "*.tests.js",
+    "**/__tests__/**",
+    "*.interface.ts",
+    "*.type.ts",
+    "*.d.ts"
+  ];
+  constructor(routesDir = "./routes", excludePatterns) {
+    this.routesDir = resolve2(process.cwd(), routesDir);
+    this.excludePatterns = excludePatterns || RouteScanner.DEFAULT_EXCLUDE_PATTERNS;
+  }
+  async scan() {
+    const routes = [];
+    if (!existsSync2(this.routesDir)) {
+      return [];
+    }
+    try {
+      await this.scanDirectory(this.routesDir, routes);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        console.warn(`  \u2717 Routes directory not accessible: ${this.routesDir}`);
+        return [];
+      }
+      throw error;
+    }
+    return routes;
+  }
+  isExcluded(filePath) {
+    const relativePath = relative2(this.routesDir, filePath);
+    for (const pattern of this.excludePatterns) {
+      const regexPattern = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "__GLOBSTAR__").replace(/\*/g, "[^/]*").replace(/__GLOBSTAR__/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${regexPattern}$`);
+      const filename = relativePath.split(sep).pop() || "";
+      if (regex.test(relativePath) || regex.test(filename)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  async scanDirectory(dir, routes, basePath = "") {
+    const entries = await fs2.readdir(dir);
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      const stats = await fs2.stat(fullPath);
+      if (stats.isDirectory()) {
+        const newBasePath = basePath ? `${basePath}/${entry}` : entry;
+        await this.scanDirectory(fullPath, routes, newBasePath);
+      } else if (entry.endsWith(".ts") || entry.endsWith(".js")) {
+        if (this.isExcluded(fullPath)) {
+          continue;
+        }
+        const routePath = relative2(this.routesDir, fullPath).replace(/\.(ts|js)$/, "").split(sep).join("/");
+        try {
+          const importPath = process.platform === "win32" ? `file:///${fullPath.replace(/\\/g, "/")}` : fullPath;
+          const module = await import(importPath);
+          if (module.default && typeof module.default === "function") {
+            routes.push({
+              name: "default",
+              path: fullPath,
+              method: "GET",
+              options: {
+                method: "GET",
+                path: `/${routePath}`,
+                expose: true
+              }
+            });
+          }
+          for (const [name, value] of Object.entries(module)) {
+            if (name === "default")
+              continue;
+            if (value && typeof value === "object" && "entry" in value && "options" in value && "handler" in value) {
+              const routeDef = value;
+              routes.push({
+                name,
+                path: fullPath,
+                method: routeDef.options.method,
+                options: routeDef.options
+              });
+            } else if (Array.isArray(value) && value.length >= 4) {
+              const [method, , , path] = value;
+              routes.push({
+                name,
+                path: fullPath,
+                method,
+                options: {
+                  method,
+                  path,
+                  expose: true
+                }
+              });
+            }
+          }
+        } catch (error) {
+          console.error(`Failed to load route from ${fullPath}:`, error);
+        }
+      }
+    }
+  }
+  enableWatch(callback) {
+    if (typeof Bun !== "undefined" && Bun.env.NODE_ENV === "development") {
+      console.log(`Watching for route changes in ${this.routesDir}`);
+      setInterval(async () => {
+        await callback();
+      }, 1000);
+    }
+  }
+}
+
+// src/middleware/manager.ts
+class MiddlewareManager {
+  beforeHandlers = [];
+  finallyHandlers = [];
+  addBefore(...handlers) {
+    this.beforeHandlers.push(...handlers);
+  }
+  addFinally(...handlers) {
+    this.finallyHandlers.push(...handlers);
+  }
+  async executeBefore(request) {
+    if (this.beforeHandlers.length === 0)
+      return request;
+    let currentRequest = request;
+    for (const handler of this.beforeHandlers) {
       const result = await handler(currentRequest);
       if (result instanceof Response) {
         return result;
@@ -480,6 +608,8 @@ class MiddlewareManager {
     return currentRequest;
   }
   async executeFinally(response, request) {
+    if (this.finallyHandlers.length === 0)
+      return response;
     let currentResponse = response;
     for (const handler of this.finallyHandlers) {
       try {
@@ -502,69 +632,17 @@ class MiddlewareManager {
   }
 }
 
-// src/utils/path.ts
-function toFileUrl(path) {
-  return process.platform === "win32" ? `file:///${path.replace(/\\/g, "/")}` : path;
-}
-function buildRouteRegex(path) {
-  return RegExp(`^${path.replace(/\/+(\/|$)/g, "$1").replace(/(\/?\.?):(\w+)\+/g, "($1(?<$2>[\\s\\S]+))").replace(/(\/?\.?):(\w+)/g, "($1(?<$2>[^$1/]+?))").replace(/\./g, "\\.").replace(/(\/?)\*/g, "($1.*)?")}/*$`);
-}
-
-// node_modules/itty-router/index.mjs
-var r = (e = "text/plain; charset=utf-8", t) => (r2, o = {}) => {
-  if (r2 === undefined || r2 instanceof Response)
-    return r2;
-  const a = new Response(t?.(r2) ?? r2, o.url ? undefined : o);
-  return a.headers.set("content-type", e), a;
-};
-var o = r("application/json; charset=utf-8", JSON.stringify);
-var p = r("text/plain; charset=utf-8", String);
-var f = r("text/html");
-var u = r("image/jpeg");
-var h = r("image/png");
-var g = r("image/webp");
-var y = (e = {}) => {
-  const { origin: t = "*", credentials: r2 = false, allowMethods: o2 = "*", allowHeaders: a, exposeHeaders: s, maxAge: c } = e, n = (e2) => {
-    const o3 = e2?.headers.get("origin");
-    return t === true ? o3 : t instanceof RegExp ? t.test(o3) ? o3 : undefined : Array.isArray(t) ? t.includes(o3) ? o3 : undefined : t instanceof Function ? t(o3) : t == "*" && r2 ? o3 : t;
-  }, l = (e2, t2) => {
-    for (const [r3, o3] of Object.entries(t2))
-      o3 && e2.headers.append(r3, o3);
-    return e2;
-  };
-  return { corsify: (e2, t2) => e2?.headers?.get("access-control-allow-origin") || e2.status == 101 ? e2 : l(e2.clone(), { "access-control-allow-origin": n(t2), "access-control-allow-credentials": r2 }), preflight: (e2) => {
-    if (e2.method == "OPTIONS") {
-      const t2 = new Response(null, { status: 204 });
-      return l(t2, { "access-control-allow-origin": n(e2), "access-control-allow-methods": o2?.join?.(",") ?? o2, "access-control-expose-headers": s?.join?.(",") ?? s, "access-control-allow-headers": a?.join?.(",") ?? a ?? e2.headers.get("access-control-request-headers"), "access-control-max-age": c, "access-control-allow-credentials": r2 });
-    }
-  } };
-};
-
 // src/http.ts
-var { preflight, corsify } = y({
-  origin: "*",
-  credentials: true,
-  allowHeaders: "Content-Type, Authorization",
-  allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-  exposeHeaders: "Authorization",
-  maxAge: 86400
-});
-function hasBigInt(value, depth = 0) {
-  if (typeof value === "bigint")
-    return true;
-  if (depth > 4 || value === null || typeof value !== "object")
-    return false;
-  for (const v of Object.values(value)) {
-    if (hasBigInt(v, depth + 1))
-      return true;
-  }
-  return false;
-}
 function stringifyData(data) {
   const val = data ?? null;
-  if (!hasBigInt(val))
+  try {
     return JSON.stringify(val);
-  return JSON.stringify(val, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+  } catch (e) {
+    if (e instanceof TypeError && /\bbigint\b/i.test(e.message)) {
+      return JSON.stringify(val, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+    }
+    throw e;
+  }
 }
 function createErrorResponse(code, message, contentType) {
   const errorBody = {
@@ -628,90 +706,232 @@ function createResponse(statusCode, data, contentType = CONTENT_TYPES.JSON) {
   });
 }
 
+// src/utils/schema-validation.ts
+function isStandardRouteSchema(schema) {
+  const standard = schema?.["~standard"];
+  return !!standard && typeof standard === "object" && typeof standard.validate === "function" && standard.version === 1;
+}
+async function runStandardValidation(schema, value) {
+  const result = await schema["~standard"].validate(value);
+  const issues = result?.issues;
+  if (Array.isArray(issues) && issues.length > 0) {
+    return { success: false, issues };
+  }
+  return { success: true, value: result?.value };
+}
+function extractThrownIssues(error) {
+  if (Array.isArray(error)) {
+    return error;
+  }
+  if (error && typeof error === "object" && Array.isArray(error.issues)) {
+    return error.issues;
+  }
+  if (error && typeof error === "object" && error.cause && Array.isArray(error.cause.issues)) {
+    return error.cause.issues;
+  }
+  return null;
+}
+function normalizePath(path) {
+  if (!Array.isArray(path))
+    return [];
+  const normalized = [];
+  for (let i = 0;i < path.length; i++) {
+    const segment = path[i];
+    let value = segment;
+    if (segment && typeof segment === "object" && "key" in segment) {
+      value = segment.key;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+      normalized.push(value);
+    } else if (typeof value === "symbol") {
+      normalized.push(String(value));
+    } else if (value !== undefined && value !== null) {
+      normalized.push(String(value));
+    }
+  }
+  return normalized;
+}
+function normalizeValidationIssues(issues, includeRawIssues) {
+  const normalized = [];
+  for (let i = 0;i < issues.length; i++) {
+    const issue = issues[i];
+    const maybeIssue = issue;
+    const normalizedIssue = {
+      message: typeof maybeIssue?.message === "string" && maybeIssue.message.length > 0 ? maybeIssue.message : "Invalid value",
+      path: normalizePath(maybeIssue?.path)
+    };
+    if (typeof maybeIssue?.code === "string") {
+      normalizedIssue.code = maybeIssue.code;
+    }
+    if (includeRawIssues) {
+      normalizedIssue.raw = issue;
+    }
+    normalized.push(normalizedIssue);
+  }
+  return normalized;
+}
+function createValidationErrorPayload(target, issues) {
+  return {
+    error: true,
+    message: "Validation failed",
+    statusCode: 422,
+    source: "validation",
+    target,
+    issues,
+    timestamp: new Date().toISOString()
+  };
+}
+
 // src/core/router.ts
 class VectorRouter {
   middlewareManager;
   authManager;
   cacheManager;
-  routes = [];
-  specificityCache = new Map;
+  routeBooleanDefaults = {};
+  developmentMode = undefined;
+  routeDefinitions = [];
+  routeTable = Object.create(null);
+  routeMatchers = [];
+  corsHeadersEntries = null;
+  corsHandler = null;
   constructor(middlewareManager, authManager, cacheManager) {
     this.middlewareManager = middlewareManager;
     this.authManager = authManager;
     this.cacheManager = cacheManager;
   }
-  getRouteSpecificity(path) {
-    const cached = this.specificityCache.get(path);
-    if (cached !== undefined)
-      return cached;
-    const STATIC_SEGMENT_WEIGHT = 1000;
-    const PARAM_SEGMENT_WEIGHT = 10;
-    const WILDCARD_WEIGHT = 1;
-    const EXACT_MATCH_BONUS = 1e4;
-    let score = 0;
-    const segments = path.split("/").filter(Boolean);
-    for (const segment of segments) {
-      if (this.isStaticSegment(segment)) {
-        score += STATIC_SEGMENT_WEIGHT;
-      } else if (this.isParamSegment(segment)) {
-        score += PARAM_SEGMENT_WEIGHT;
-      } else if (this.isWildcardSegment(segment)) {
-        score += WILDCARD_WEIGHT;
+  setCorsHeaders(entries) {
+    this.corsHeadersEntries = entries;
+  }
+  setCorsHandler(handler) {
+    this.corsHandler = handler;
+  }
+  setRouteBooleanDefaults(defaults) {
+    this.routeBooleanDefaults = { ...defaults };
+  }
+  setDevelopmentMode(mode) {
+    this.developmentMode = mode;
+  }
+  applyRouteBooleanDefaults(options) {
+    const resolved = { ...options };
+    const defaults = this.routeBooleanDefaults;
+    const keys = ["auth", "expose", "rawRequest", "validate", "rawResponse"];
+    for (const key of keys) {
+      if (resolved[key] === undefined && defaults[key] !== undefined) {
+        resolved[key] = defaults[key];
       }
     }
-    score += path.length;
-    if (this.isExactPath(path)) {
-      score += EXACT_MATCH_BONUS;
-    }
-    this.specificityCache.set(path, score);
-    return score;
+    return resolved;
+  }
+  route(options, handler) {
+    const resolvedOptions = this.applyRouteBooleanDefaults(options);
+    const method = resolvedOptions.method.toUpperCase();
+    const path = resolvedOptions.path;
+    const wrappedHandler = this.wrapHandler(resolvedOptions, handler);
+    const methodMap = this.getOrCreateMethodMap(path);
+    methodMap[method] = wrappedHandler;
+    this.routeDefinitions.push({
+      method,
+      path,
+      options: resolvedOptions
+    });
   }
-  isStaticSegment(segment) {
-    return !segment.startsWith(":") && !segment.includes("*");
+  addRoute(entry) {
+    const [method, , handlers, path] = entry;
+    if (!path)
+      return;
+    const methodMap = this.getOrCreateMethodMap(path);
+    methodMap[method.toUpperCase()] = handlers[0];
+    const normalizedMethod = method.toUpperCase();
+    this.routeDefinitions.push({
+      method: normalizedMethod,
+      path,
+      options: {
+        method: normalizedMethod,
+        path,
+        expose: true
+      }
+    });
   }
-  isParamSegment(segment) {
-    return segment.startsWith(":");
+  bulkAddRoutes(entries) {
+    for (const entry of entries) {
+      this.addRoute(entry);
+    }
   }
-  isWildcardSegment(segment) {
-    return segment.includes("*");
+  addStaticRoute(path, response) {
+    const existing = this.routeTable[path];
+    if (existing && !(existing instanceof Response)) {
+      throw new Error(`Cannot register static route for path "${path}" because method routes already exist.`);
+    }
+    this.routeTable[path] = response;
+    this.removeRouteMatcher(path);
   }
-  isExactPath(path) {
-    return !path.includes(":") && !path.includes("*");
+  getRouteTable() {
+    return this.routeTable;
   }
-  sortRoutes() {
-    this.routes.sort((a, b) => {
-      const pathA = this.extractPath(a);
-      const pathB = this.extractPath(b);
-      const scoreA = this.getRouteSpecificity(pathA);
-      const scoreB = this.getRouteSpecificity(pathB);
-      return scoreB - scoreA;
-    });
+  getRoutes() {
+    const routes = [];
+    for (const matcher of this.routeMatchers) {
+      const value = this.routeTable[matcher.path];
+      if (!value || value instanceof Response)
+        continue;
+      for (const [method, handler] of Object.entries(value)) {
+        routes.push([method, matcher.regex, [handler], matcher.path]);
+      }
+    }
+    return routes;
   }
-  extractPath(route) {
-    const PATH_INDEX = 3;
-    return route[PATH_INDEX] || "";
+  getRouteDefinitions() {
+    return [...this.routeDefinitions];
   }
-  route(options, handler) {
-    const wrappedHandler = this.wrapHandler(options, handler);
-    const routeEntry = [
-      options.method.toUpperCase(),
-      this.createRouteRegex(options.path),
-      [wrappedHandler],
-      options.path
-    ];
-    this.routes.push(routeEntry);
-    this.sortRoutes();
-    return routeEntry;
-  }
-  createRouteRegex(path) {
-    return buildRouteRegex(path);
+  clearRoutes() {
+    this.routeTable = Object.create(null);
+    this.routeMatchers = [];
+    this.routeDefinitions = [];
+  }
+  sortRoutes() {}
+  async handle(request) {
+    let url;
+    try {
+      url = new URL(request.url);
+    } catch {
+      return APIError.badRequest("Malformed request URL");
+    }
+    request._parsedUrl = url;
+    const pathname = url.pathname;
+    for (const matcher of this.routeMatchers) {
+      const path = matcher.path;
+      const value = this.routeTable[path];
+      if (!value)
+        continue;
+      if (value instanceof Response)
+        continue;
+      const methodMap = value;
+      if (request.method === "OPTIONS" || request.method in methodMap) {
+        const match = pathname.match(matcher.regex);
+        if (match) {
+          try {
+            request.params = match.groups ?? {};
+          } catch {}
+          const handler = methodMap[request.method] ?? methodMap["GET"];
+          if (handler) {
+            const response = await handler(request);
+            if (response)
+              return response;
+          }
+        }
+      }
+    }
+    return STATIC_RESPONSES.NOT_FOUND.clone();
   }
   prepareRequest(request, options) {
     if (!request.context) {
       request.context = {};
     }
-    if (options?.params !== undefined) {
-      request.params = options.params;
+    const hasEmptyParamsObject = !!request.params && typeof request.params === "object" && !Array.isArray(request.params) && Object.keys(request.params).length === 0;
+    if (options?.params !== undefined && (request.params === undefined || hasEmptyParamsObject)) {
+      try {
+        request.params = options.params;
+      } catch {}
     }
     if (options?.route !== undefined) {
       request.route = options.route;
@@ -719,21 +939,37 @@ class VectorRouter {
     if (options?.metadata !== undefined) {
       request.metadata = options.metadata;
     }
-    if (!request.query && request.url) {
-      const url = request._parsedUrl ?? new URL(request.url);
-      const query = {};
-      for (const [key, value] of url.searchParams) {
-        if (key in query) {
-          if (Array.isArray(query[key])) {
-            query[key].push(value);
-          } else {
-            query[key] = [query[key], value];
-          }
-        } else {
-          query[key] = value;
-        }
+    if (request.query == null && request.url) {
+      try {
+        Object.defineProperty(request, "query", {
+          get() {
+            const url = this._parsedUrl ?? new URL(this.url);
+            const query = VectorRouter.parseQuery(url);
+            Object.defineProperty(this, "query", {
+              value: query,
+              writable: true,
+              configurable: true,
+              enumerable: true
+            });
+            return query;
+          },
+          set(value) {
+            Object.defineProperty(this, "query", {
+              value,
+              writable: true,
+              configurable: true,
+              enumerable: true
+            });
+          },
+          configurable: true,
+          enumerable: true
+        });
+      } catch {
+        const url = request._parsedUrl ?? new URL(request.url);
+        try {
+          request.query = VectorRouter.parseQuery(url);
+        } catch {}
       }
-      request.query = query;
     }
     if (!Object.getOwnPropertyDescriptor(request, "cookies")) {
       Object.defineProperty(request, "cookies", {
@@ -761,71 +997,111 @@ class VectorRouter {
       });
     }
   }
+  resolveFallbackParams(request, routeMatcher) {
+    if (!routeMatcher) {
+      return;
+    }
+    const currentParams = request.params;
+    if (currentParams && typeof currentParams === "object" && !Array.isArray(currentParams) && Object.keys(currentParams).length > 0) {
+      return;
+    }
+    let pathname;
+    try {
+      pathname = (request._parsedUrl ?? new URL(request.url)).pathname;
+    } catch {
+      return;
+    }
+    const matched = pathname.match(routeMatcher);
+    if (!matched?.groups) {
+      return;
+    }
+    return matched.groups;
+  }
   wrapHandler(options, handler) {
+    const routePath = options.path;
+    const routeMatcher = routePath.includes(":") ? buildRouteRegex(routePath) : null;
     return async (request) => {
       const vectorRequest = request;
+      const fallbackParams = this.resolveFallbackParams(request, routeMatcher);
       this.prepareRequest(vectorRequest, {
+        params: fallbackParams,
+        route: routePath,
         metadata: options.metadata
       });
-      request = vectorRequest;
       try {
         if (options.expose === false) {
           return APIError.forbidden("Forbidden");
         }
-        const beforeResult = await this.middlewareManager.executeBefore(request);
+        const beforeResult = await this.middlewareManager.executeBefore(vectorRequest);
         if (beforeResult instanceof Response) {
           return beforeResult;
         }
-        request = beforeResult;
+        const req = beforeResult;
         if (options.auth) {
           try {
-            await this.authManager.authenticate(request);
+            await this.authManager.authenticate(req);
           } catch (error) {
             return APIError.unauthorized(error instanceof Error ? error.message : "Authentication failed", options.responseContentType);
           }
         }
-        if (!options.rawRequest && request.method !== "GET" && request.method !== "HEAD") {
+        if (!options.rawRequest && req.method !== "GET" && req.method !== "HEAD") {
+          let parsedContent = null;
           try {
-            const contentType = request.headers.get("content-type");
-            if (contentType?.includes("application/json")) {
-              request.content = await request.json();
-            } else if (contentType?.includes("application/x-www-form-urlencoded")) {
-              request.content = Object.fromEntries(await request.formData());
-            } else if (contentType?.includes("multipart/form-data")) {
-              request.content = await request.formData();
+            const contentType = req.headers.get("content-type");
+            if (contentType?.startsWith("application/json")) {
+              parsedContent = await req.json();
+            } else if (contentType?.startsWith("application/x-www-form-urlencoded")) {
+              parsedContent = Object.fromEntries(await req.formData());
+            } else if (contentType?.startsWith("multipart/form-data")) {
+              parsedContent = await req.formData();
             } else {
-              request.content = await request.text();
+              parsedContent = await req.text();
             }
           } catch {
-            request.content = null;
+            parsedContent = null;
           }
+          this.setContentAndBodyAlias(req, parsedContent);
+        }
+        const inputValidationResponse = await this.validateInputSchema(req, options);
+        if (inputValidationResponse) {
+          return inputValidationResponse;
         }
         let result;
         const cacheOptions = options.cache;
-        const cacheFactory = async () => {
-          const res = await handler(request);
-          if (res instanceof Response) {
-            return {
-              _isResponse: true,
-              body: await res.text(),
-              status: res.status,
-              headers: Object.fromEntries(res.headers.entries())
-            };
-          }
-          return res;
-        };
         if (cacheOptions && typeof cacheOptions === "number" && cacheOptions > 0) {
-          const cacheKey = this.cacheManager.generateKey(request, {
-            authUser: request.authUser
+          const cacheKey = this.cacheManager.generateKey(req, {
+            authUser: req.authUser
           });
-          result = await this.cacheManager.get(cacheKey, cacheFactory, cacheOptions);
+          result = await this.cacheManager.get(cacheKey, async () => {
+            const res = await handler(req);
+            if (res instanceof Response) {
+              return {
+                _isResponse: true,
+                body: await res.text(),
+                status: res.status,
+                headers: Object.fromEntries(res.headers.entries())
+              };
+            }
+            return res;
+          }, cacheOptions);
         } else if (cacheOptions && typeof cacheOptions === "object" && cacheOptions.ttl) {
-          const cacheKey = cacheOptions.key || this.cacheManager.generateKey(request, {
-            authUser: request.authUser
+          const cacheKey = cacheOptions.key || this.cacheManager.generateKey(req, {
+            authUser: req.authUser
           });
-          result = await this.cacheManager.get(cacheKey, cacheFactory, cacheOptions.ttl);
+          result = await this.cacheManager.get(cacheKey, async () => {
+            const res = await handler(req);
+            if (res instanceof Response) {
+              return {
+                _isResponse: true,
+                body: await res.text(),
+                status: res.status,
+                headers: Object.fromEntries(res.headers.entries())
+              };
+            }
+            return res;
+          }, cacheOptions.ttl);
         } else {
-          result = await handler(request);
+          result = await handler(req);
         }
         if (result && typeof result === "object" && result._isResponse === true) {
           result = new Response(result.body, {
@@ -839,7 +1115,18 @@ class VectorRouter {
         } else {
           response = createResponse(200, result, options.responseContentType);
         }
-        response = await this.middlewareManager.executeFinally(response, request);
+        response = await this.middlewareManager.executeFinally(response, req);
+        const entries = this.corsHeadersEntries;
+        if (entries) {
+          for (const [k, v] of entries) {
+            response.headers.set(k, v);
+          }
+        } else {
+          const dynamicCors = this.corsHandler;
+          if (dynamicCors) {
+            response = dynamicCors(response, req);
+          }
+        }
         return response;
       } catch (error) {
         if (error instanceof Response) {
@@ -850,69 +1137,2338 @@ class VectorRouter {
       }
     };
   }
-  addRoute(routeEntry) {
-    this.routes.push(routeEntry);
-    this.sortRoutes();
+  isDevelopmentMode() {
+    if (this.developmentMode !== undefined) {
+      return this.developmentMode;
+    }
+    const nodeEnv = typeof Bun !== "undefined" ? Bun.env.NODE_ENV : "development";
+    return nodeEnv !== "production";
+  }
+  async buildInputValidationPayload(request, options) {
+    let body = request.content;
+    if (options.rawRequest && request.method !== "GET" && request.method !== "HEAD") {
+      try {
+        body = await request.clone().text();
+      } catch {
+        body = null;
+      }
+    }
+    return {
+      params: request.params ?? {},
+      query: request.query ?? {},
+      headers: Object.fromEntries(request.headers.entries()),
+      cookies: request.cookies ?? {},
+      body
+    };
+  }
+  applyValidatedInput(request, validatedValue) {
+    request.validatedInput = validatedValue;
+    if (!validatedValue || typeof validatedValue !== "object") {
+      return;
+    }
+    const validated = validatedValue;
+    if ("params" in validated) {
+      try {
+        request.params = validated.params;
+      } catch {}
+    }
+    if ("query" in validated) {
+      try {
+        request.query = validated.query;
+      } catch {}
+    }
+    if ("cookies" in validated) {
+      try {
+        request.cookies = validated.cookies;
+      } catch {}
+    }
+    if ("body" in validated) {
+      this.setContentAndBodyAlias(request, validated.body);
+    }
+  }
+  setContentAndBodyAlias(request, value) {
+    try {
+      request.content = value;
+    } catch {
+      return;
+    }
+    this.setBodyAlias(request, value);
+  }
+  setBodyAlias(request, value) {
+    try {
+      request.body = value;
+    } catch {}
+  }
+  async validateInputSchema(request, options) {
+    const inputSchema = options.schema?.input;
+    if (!inputSchema) {
+      return null;
+    }
+    if (options.validate === false) {
+      return null;
+    }
+    if (!isStandardRouteSchema(inputSchema)) {
+      return APIError.internalServerError("Invalid route schema configuration", options.responseContentType);
+    }
+    const includeRawIssues = this.isDevelopmentMode();
+    const payload = await this.buildInputValidationPayload(request, options);
+    try {
+      const validation = await runStandardValidation(inputSchema, payload);
+      if (validation.success === false) {
+        const issues = normalizeValidationIssues(validation.issues, includeRawIssues);
+        return createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType);
+      }
+      this.applyValidatedInput(request, validation.value);
+      return null;
+    } catch (error) {
+      const thrownIssues = extractThrownIssues(error);
+      if (thrownIssues) {
+        const issues = normalizeValidationIssues(thrownIssues, includeRawIssues);
+        return createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType);
+      }
+      return APIError.internalServerError(error instanceof Error ? error.message : "Validation failed", options.responseContentType);
+    }
+  }
+  getOrCreateMethodMap(path) {
+    const existing = this.routeTable[path];
+    if (existing instanceof Response) {
+      throw new Error(`Cannot register method route for path "${path}" because a static route already exists.`);
+    }
+    if (existing) {
+      return existing;
+    }
+    const methodMap = Object.create(null);
+    this.routeTable[path] = methodMap;
+    this.addRouteMatcher(path);
+    return methodMap;
+  }
+  addRouteMatcher(path) {
+    if (this.routeMatchers.some((matcher) => matcher.path === path)) {
+      return;
+    }
+    this.routeMatchers.push({
+      path,
+      regex: buildRouteRegex(path),
+      specificity: this.routeSpecificityScore(path)
+    });
+    this.routeMatchers.sort((a, b) => {
+      if (a.specificity !== b.specificity) {
+        return b.specificity - a.specificity;
+      }
+      return a.path.localeCompare(b.path);
+    });
+  }
+  removeRouteMatcher(path) {
+    this.routeMatchers = this.routeMatchers.filter((matcher) => matcher.path !== path);
+  }
+  static parseQuery(url) {
+    const query = {};
+    for (const [key, value] of url.searchParams) {
+      if (key in query) {
+        const existing = query[key];
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          query[key] = [existing, value];
+        }
+      } else {
+        query[key] = value;
+      }
+    }
+    return query;
+  }
+  routeSpecificityScore(path) {
+    const STATIC_SEGMENT_WEIGHT = 1000;
+    const PARAM_SEGMENT_WEIGHT = 10;
+    const WILDCARD_WEIGHT = 1;
+    const EXACT_MATCH_BONUS = 1e4;
+    const segments = path.split("/").filter(Boolean);
+    let score = 0;
+    for (const segment of segments) {
+      if (segment.includes("*")) {
+        score += WILDCARD_WEIGHT;
+      } else if (segment.startsWith(":")) {
+        score += PARAM_SEGMENT_WEIGHT;
+      } else {
+        score += STATIC_SEGMENT_WEIGHT;
+      }
+    }
+    score += path.length;
+    if (!path.includes(":") && !path.includes("*")) {
+      score += EXACT_MATCH_BONUS;
+    }
+    return score;
+  }
+}
+
+// src/core/server.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join2 } from "path";
+
+// src/utils/cors.ts
+function getAllowedOrigin(origin, config) {
+  if (!origin) {
+    if (typeof config.origin === "string") {
+      if (config.origin === "*" && config.credentials)
+        return null;
+      return config.origin;
+    }
+    return null;
+  }
+  if (typeof config.origin === "string") {
+    if (config.origin === "*") {
+      return config.credentials ? origin : "*";
+    }
+    return config.origin === origin ? origin : null;
+  }
+  if (Array.isArray(config.origin)) {
+    return config.origin.includes(origin) ? origin : null;
+  }
+  if (typeof config.origin === "function") {
+    return config.origin(origin) ? origin : null;
+  }
+  return null;
+}
+function shouldVaryByOrigin(config) {
+  return typeof config.origin === "string" && config.origin === "*" && config.credentials || Array.isArray(config.origin) || typeof config.origin === "function";
+}
+function buildCorsHeaders(origin, config, varyByOrigin) {
+  const headers = {};
+  if (origin) {
+    headers["access-control-allow-origin"] = origin;
+    headers["access-control-allow-methods"] = config.allowMethods;
+    headers["access-control-allow-headers"] = config.allowHeaders;
+    headers["access-control-expose-headers"] = config.exposeHeaders;
+    headers["access-control-max-age"] = String(config.maxAge);
+    if (config.credentials) {
+      headers["access-control-allow-credentials"] = "true";
+    }
+    if (varyByOrigin) {
+      headers.vary = "Origin";
+    }
+  }
+  return headers;
+}
+function mergeVary(existing, nextValue) {
+  if (!existing)
+    return nextValue;
+  const parts = existing.split(",").map((v) => v.trim()).filter(Boolean);
+  const lower = parts.map((v) => v.toLowerCase());
+  if (!lower.includes(nextValue.toLowerCase())) {
+    parts.push(nextValue);
+  }
+  return parts.join(", ");
+}
+function cors(config) {
+  return {
+    preflight(request) {
+      const origin = request.headers.get("origin") ?? undefined;
+      const allowed = getAllowedOrigin(origin, config);
+      const varyByOrigin = Boolean(origin && allowed && shouldVaryByOrigin(config));
+      return new Response(null, {
+        status: 204,
+        headers: buildCorsHeaders(allowed, config, varyByOrigin)
+      });
+    },
+    corsify(response, request) {
+      const origin = request.headers.get("origin") ?? undefined;
+      const allowed = getAllowedOrigin(origin, config);
+      if (!allowed)
+        return response;
+      const varyByOrigin = Boolean(origin && shouldVaryByOrigin(config));
+      const headers = buildCorsHeaders(allowed, config, varyByOrigin);
+      for (const [k, v] of Object.entries(headers)) {
+        if (k === "vary") {
+          response.headers.set("vary", mergeVary(response.headers.get("vary"), v));
+          continue;
+        }
+        response.headers.set(k, v);
+      }
+      return response;
+    }
+  };
+}
+
+// src/openapi/docs-ui.ts
+function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPath, logoWhitePath, appleTouchIconPath, favicon32Path, favicon16Path, webManifestPath) {
+  const specJson = JSON.stringify(spec).replace(/<\/script/gi, "<\\/script");
+  const openapiPathJson = JSON.stringify(openapiPath);
+  const tailwindScriptPathJson = JSON.stringify(tailwindScriptPath);
+  const logoDarkPathJson = JSON.stringify(logoDarkPath);
+  const logoWhitePathJson = JSON.stringify(logoWhitePath);
+  const appleTouchIconPathJson = JSON.stringify(appleTouchIconPath);
+  const favicon32PathJson = JSON.stringify(favicon32Path);
+  const favicon16PathJson = JSON.stringify(favicon16Path);
+  const webManifestPathJson = JSON.stringify(webManifestPath);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Vector API Documentation</title>
+  <link rel="apple-touch-icon" sizes="180x180" href=${appleTouchIconPathJson}>
+  <link rel="icon" type="image/png" sizes="32x32" href=${favicon32PathJson}>
+  <link rel="icon" type="image/png" sizes="16x16" href=${favicon16PathJson}>
+  <link rel="manifest" href=${webManifestPathJson}>
+  <script>
+    if (localStorage.getItem('theme') === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  </script>
+  <script src=${tailwindScriptPathJson}></script>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <script>
+    tailwind.config = {
+      darkMode: 'class',
+      theme: {
+        extend: {
+          colors: {
+            brand: {
+              DEFAULT: '#00A1FF',
+              mint: '#00FF8F',
+              soft: '#E4F5FF',
+              deep: '#007BC5',
+            },
+            dark: { bg: '#0A0A0A', surface: '#111111', border: '#1F1F1F', text: '#EDEDED' },
+            light: { bg: '#FFFFFF', surface: '#F9F9F9', border: '#E5E5E5', text: '#111111' }
+          },
+          fontFamily: {
+            sans: ['Inter', 'sans-serif'],
+            mono: ['JetBrains Mono', 'monospace'],
+          }
+        }
+      }
+    };
+  </script>
+  <style>
+    :root {
+      --motion-fast: 180ms;
+      --motion-base: 280ms;
+      --motion-slow: 420ms;
+      --motion-ease: cubic-bezier(0.22, 1, 0.36, 1);
+    }
+    ::-webkit-scrollbar { width: 8px; height: 8px; }
+    ::-webkit-scrollbar-track { background: transparent; }
+    ::-webkit-scrollbar-thumb { background: #333; border-radius: 4px; }
+    body { transition: background-color 150ms ease, color 150ms ease; }
+    #sidebar-nav a,
+    #send-btn,
+    #copy-curl,
+    #add-header-btn,
+    #expand-body-btn,
+    #expand-response-btn,
+    #expand-close,
+    #expand-apply {
+      transition:
+        transform var(--motion-fast) var(--motion-ease),
+        opacity var(--motion-fast) var(--motion-ease),
+        border-color var(--motion-fast) var(--motion-ease),
+        background-color var(--motion-fast) var(--motion-ease),
+        color var(--motion-fast) var(--motion-ease);
+      will-change: transform, opacity;
+    }
+    #sidebar-nav a:hover,
+    #send-btn:hover,
+    #add-header-btn:hover,
+    #expand-body-btn:hover,
+    #expand-response-btn:hover {
+      transform: translateY(-1px);
+    }
+    #endpoint-card {
+      transition:
+        box-shadow var(--motion-base) var(--motion-ease),
+        transform var(--motion-base) var(--motion-ease),
+        opacity var(--motion-base) var(--motion-ease);
+    }
+    .enter-fade-up {
+      animation: enterFadeUp var(--motion-base) var(--motion-ease) both;
+    }
+    .enter-stagger {
+      animation: enterStagger var(--motion-base) var(--motion-ease) both;
+      animation-delay: var(--stagger-delay, 0ms);
+    }
+    @keyframes enterFadeUp {
+      from { opacity: 0; transform: translateY(8px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    @keyframes enterStagger {
+      from { opacity: 0; transform: translateX(-6px); }
+      to { opacity: 1; transform: translateX(0); }
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+    .button-spinner {
+      display: inline-block;
+      width: 0.875rem;
+      height: 0.875rem;
+      border: 2px solid currentColor;
+      border-right-color: transparent;
+      border-radius: 9999px;
+      animation: spin 700ms linear infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      *, *::before, *::after {
+        animation: none !important;
+        transition: none !important;
+      }
+    }
+    .json-key { color: #007bc5; }
+    .json-string { color: #334155; }
+    .json-number { color: #00a1ff; }
+    .json-boolean { color: #475569; }
+    .json-null { color: #64748b; }
+    .dark .json-key { color: #7dc9ff; }
+    .dark .json-string { color: #d1d9e6; }
+    .dark .json-number { color: #7dc9ff; }
+    .dark .json-boolean { color: #93a4bf; }
+    .dark .json-null { color: #7c8ba3; }
+  </style>
+</head>
+<body class="bg-light-bg text-light-text dark:bg-dark-bg dark:text-dark-text font-sans antialiased flex h-screen overflow-hidden">
+  <div id="mobile-backdrop" class="fixed inset-0 z-30 bg-black/40 opacity-0 pointer-events-none transition-opacity duration-300 md:hidden"></div>
+  <aside id="docs-sidebar" class="fixed inset-y-0 left-0 z-40 w-72 md:w-64 border-r border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface flex flex-col flex-shrink-0 transition-transform duration-300 ease-out -translate-x-full md:translate-x-0 md:static md:z-auto transition-colors duration-150">
+    <div class="h-14 flex items-center px-5 border-b border-light-border dark:border-dark-border">
+      <div class="flex items-center">
+        <img src=${logoDarkPathJson} alt="Vector" class="h-6 w-auto block dark:hidden" />
+        <img src=${logoWhitePathJson} alt="Vector" class="h-6 w-auto hidden dark:block" />
+      </div>
+      <button id="sidebar-close" class="ml-auto p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 transition md:hidden" aria-label="Close Menu" title="Close Menu">
+        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
+        </svg>
+      </button>
+    </div>
+    <div class="p-4">
+      <div class="relative">
+        <svg class="w-4 h-4 absolute left-3 top-1/2 -translate-y-1/2 opacity-60" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
+        </svg>
+        <input
+          id="sidebar-search"
+          type="text"
+          placeholder="Search routes..."
+          class="w-full pl-9 pr-3 py-2 text-sm rounded-md border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors"
+        />
+      </div>
+    </div>
+    <nav class="flex-1 overflow-y-auto px-3 py-2 space-y-6 text-sm" id="sidebar-nav"></nav>
+  </aside>
+
+  <main class="flex-1 flex flex-col min-w-0 relative">
+    <header class="h-14 flex items-center justify-between px-6 border-b border-light-border dark:border-dark-border lg:border-none lg:bg-transparent absolute top-0 w-full z-10 bg-light-bg/80 dark:bg-dark-bg/80 backdrop-blur-sm transition-colors duration-150">
+      <div class="md:hidden flex items-center gap-2">
+        <button id="sidebar-open" class="p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 transition" aria-label="Open Menu" title="Open Menu">
+          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"></path>
+          </svg>
+        </button>
+        <img src=${logoDarkPathJson} alt="Vector" class="h-5 w-auto block dark:hidden" />
+        <img src=${logoWhitePathJson} alt="Vector" class="h-5 w-auto hidden dark:block" />
+      </div>
+      <div class="flex-1"></div>
+      <button id="theme-toggle" class="p-2 rounded-md hover:bg-black/5 dark:hover:bg-white/5 transition-colors" aria-label="Toggle Dark Mode">
+        <svg class="w-5 h-5 hidden dark:block text-dark-text" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"></path></svg>
+        <svg class="w-5 h-5 block dark:hidden text-light-text" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"></path></svg>
+      </button>
+    </header>
+
+    <div class="flex-1 overflow-y-auto pt-14 pb-24">
+      <div class="max-w-[860px] mx-auto px-6 py-12 lg:py-16">
+        <div class="mb-12">
+          <h1 class="text-4xl font-bold tracking-tight mb-4" id="tag-title">API</h1>
+          <p class="text-lg opacity-80 max-w-2xl leading-relaxed" id="tag-description">Interactive API documentation.</p>
+        </div>
+        <hr class="border-t border-light-border dark:border-dark-border mb-12">
+        <div class="mb-20" id="endpoint-card">
+          <div class="flex items-center gap-3 mb-4">
+             <span id="endpoint-method" class="px-2.5 py-0.5 rounded-full text-xs font-mono font-medium"></span>
+             <h2 class="text-xl font-semibold tracking-tight" id="endpoint-title">Operation</h2>
+          </div>
+          <p class="text-sm opacity-80 mb-8 font-mono" id="endpoint-path">/</p>
+          <div class="grid grid-cols-1 lg:grid-cols-12 gap-10">
+            <div class="lg:col-span-5 space-y-8" id="params-column"></div>
+            <div class="lg:col-span-7">
+              <div class="rounded-lg border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-hidden group">
+                <div class="flex items-center justify-between px-4 py-2 border-b border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface">
+                   <span class="text-xs font-mono text-light-text/70 dark:text-dark-text/70">cURL</span>
+                   <button class="text-xs text-light-text/50 hover:text-light-text dark:text-dark-text/50 dark:hover:text-dark-text transition-colors" id="copy-curl">Copy</button>
+                </div>
+                <pre class="p-4 text-sm font-mono text-light-text dark:text-dark-text overflow-x-auto leading-relaxed"><code id="curl-code"></code></pre>
+              </div>
+              <div class="mt-4 p-4 rounded-lg border border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface">
+                <div class="flex items-center justify-between mb-3">
+                  <h4 class="text-sm font-medium">Try it out</h4>
+                  <button id="send-btn" class="px-4 py-1.5 bg-brand text-white text-sm font-semibold rounded hover:bg-brand-deep transition-colors">
+                    <span class="inline-flex items-center gap-2">
+                      <span id="send-btn-spinner" class="button-spinner hidden" aria-hidden="true"></span>
+                      <span id="send-btn-label">Submit</span>
+                    </span>
+                  </button>
+                </div>
+                <div class="space-y-4">
+                  <div>
+                    <div id="request-param-inputs" class="space-y-3"></div>
+                  </div>
+
+                  <div>
+                    <div class="flex items-center justify-between mb-2">
+                      <p class="text-xs font-semibold uppercase tracking-wider opacity-60">Headers</p>
+                      <button id="add-header-btn" class="p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors" aria-label="Add Header" title="Add Header">
+                        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 5v14m-7-7h14"></path>
+                        </svg>
+                      </button>
+                    </div>
+                    <div id="header-inputs" class="space-y-2"></div>
+                  </div>
+
+                  <div id="request-body-section">
+                    <div class="flex items-center justify-between mb-2">
+                      <p class="text-xs font-semibold uppercase tracking-wider opacity-60">Request Body</p>
+                    </div>
+                    <div class="relative h-40 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-hidden">
+                      <pre id="body-highlight" class="absolute inset-0 m-0 p-3 pr-11 text-xs font-mono leading-5 overflow-auto whitespace-pre-wrap break-words pointer-events-none"></pre>
+                      <textarea id="body-input" class="absolute inset-0 w-full h-full p-3 pr-11 text-xs font-mono leading-5 bg-transparent text-transparent caret-black dark:caret-white resize-none focus:outline-none overflow-auto placeholder:text-light-text/50 dark:placeholder:text-dark-text/40" placeholder='{"key":"value"}' spellcheck="false" autocapitalize="off" autocorrect="off"></textarea>
+                      <button id="expand-body-btn" class="absolute bottom-2 right-2 p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-surface/95 dark:bg-dark-surface/95 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors" aria-label="Expand Request Body" title="Expand Request Body">
+                        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 9V4h5M20 15v5h-5M15 4h5v5M9 20H4v-5"></path>
+                        </svg>
+                      </button>
+                    </div>
+                  </div>
+
+                  <div id="response-section">
+                    <div class="flex items-center justify-between mb-2">
+                      <p class="text-xs font-semibold uppercase tracking-wider opacity-60">Response</p>
+                    </div>
+                    <div class="relative">
+                      <pre id="result" class="p-3 pr-11 text-xs font-mono rounded border border-light-border dark:border-dark-border overflow-x-auto min-h-[140px]"></pre>
+                      <button id="expand-response-btn" class="absolute bottom-2 right-2 p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-surface/95 dark:bg-dark-surface/95 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors" aria-label="Expand Response" title="Expand Response">
+                        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 9V4h5M20 15v5h-5M15 4h5v5M9 20H4v-5"></path>
+                        </svg>
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </main>
+
+  <div id="expand-modal" class="fixed inset-0 z-50 hidden items-center justify-center bg-black/60 p-4">
+    <div class="w-full max-w-5xl rounded-lg border border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface p-4">
+      <div class="flex items-center justify-between mb-3">
+        <h3 id="expand-modal-title" class="text-sm font-semibold">Expanded View</h3>
+        <div class="flex items-center gap-2">
+          <button id="expand-apply" class="hidden text-sm px-3 py-1.5 rounded bg-brand text-white font-semibold hover:bg-brand-deep transition-colors">Apply</button>
+          <button id="expand-close" class="p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors" aria-label="Close Modal" title="Close Modal">
+            <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
+            </svg>
+          </button>
+        </div>
+      </div>
+      <div id="expand-editor-shell" class="hidden relative w-full h-[70vh] rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-hidden">
+        <pre id="expand-editor-highlight" class="absolute inset-0 m-0 p-3 text-sm font-mono leading-6 overflow-auto whitespace-pre-wrap break-words pointer-events-none"></pre>
+        <textarea id="expand-editor" class="absolute inset-0 w-full h-full p-3 text-sm font-mono leading-6 bg-transparent text-transparent caret-black dark:caret-white resize-none focus:outline-none overflow-auto" spellcheck="false" autocapitalize="off" autocorrect="off"></textarea>
+      </div>
+      <pre id="expand-viewer" class="hidden w-full h-[70vh] text-sm p-3 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-auto font-mono"></pre>
+    </div>
+  </div>
+
+  <script>
+    const spec = ${specJson};
+    const openapiPath = ${openapiPathJson};
+    const methodBadgeDefault = "bg-black/5 text-light-text/80 dark:bg-white/10 dark:text-dark-text/80";
+    const methodBadge = {
+      GET: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      POST: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      PUT: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      PATCH: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      DELETE: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+    };
+
+    function getOperations() {
+      const httpMethods = new Set([
+        "get",
+        "post",
+        "put",
+        "patch",
+        "delete",
+        "head",
+        "options",
+      ]);
+
+      const humanizePath = (path) =>
+        path
+          .replace(/^\\/+/, "")
+          .replace(/[{}]/g, "")
+          .replace(/[\\/_]+/g, " ")
+          .trim() || "root";
+
+      const toTitleCase = (value) =>
+        value.replace(/\\w\\S*/g, (word) => word.charAt(0).toUpperCase() + word.slice(1));
+
+      const getDisplayName = (op, method, path) => {
+        if (typeof op.summary === "string" && op.summary.trim()) {
+          return op.summary.trim();
+        }
+
+        if (typeof op.operationId === "string" && op.operationId.trim()) {
+          const withoutPrefix = op.operationId.replace(
+            new RegExp("^" + method + "_+", "i"),
+            "",
+          );
+          const readable = withoutPrefix.replace(/_+/g, " ").trim();
+          if (readable) return toTitleCase(readable);
+        }
+
+        return toTitleCase(humanizePath(path));
+      };
+
+      const ops = [];
+      const paths = spec.paths || {};
+      for (const path of Object.keys(paths)) {
+        const methods = paths[path] || {};
+        for (const method of Object.keys(methods)) {
+          if (!httpMethods.has(method)) continue;
+          const op = methods[method];
+          ops.push({
+            path,
+            method: method.toUpperCase(),
+            operation: op,
+            tag: (op.tags && op.tags[0]) || "default",
+            name: getDisplayName(op, method, path),
+          });
+        }
+      }
+      return ops;
+    }
+
+    const operations = getOperations();
+    let selected = operations[0] || null;
+    const operationParamValues = new Map();
+    const operationBodyDrafts = new Map();
+    const requestHeaders = [{ key: "Authorization", value: "" }];
+    let expandModalMode = null;
+    let isMobileSidebarOpen = false;
+    let sidebarSearchQuery = "";
+
+    function setMobileSidebarOpen(open) {
+      const sidebar = document.getElementById("docs-sidebar");
+      const backdrop = document.getElementById("mobile-backdrop");
+      const openBtn = document.getElementById("sidebar-open");
+      if (!sidebar || !backdrop || !openBtn) return;
+
+      isMobileSidebarOpen = open;
+      sidebar.classList.toggle("-translate-x-full", !open);
+      backdrop.classList.toggle("opacity-0", !open);
+      backdrop.classList.toggle("pointer-events-none", !open);
+      openBtn.setAttribute("aria-expanded", open ? "true" : "false");
+      document.body.classList.toggle("overflow-hidden", open);
+    }
+
+    function getOperationKey(op) {
+      return op.method + " " + op.path;
+    }
+
+    function getOperationParameterGroups(op) {
+      const params =
+        op &&
+        op.operation &&
+        Array.isArray(op.operation.parameters)
+          ? op.operation.parameters
+          : [];
+
+      return {
+        all: params,
+        path: params.filter((p) => p.in === "path"),
+        query: params.filter((p) => p.in === "query"),
+        headers: params.filter((p) => p.in === "header"),
+      };
+    }
+
+    function getParameterValues(op) {
+      const key = getOperationKey(op);
+      if (!operationParamValues.has(key)) {
+        operationParamValues.set(key, {});
+      }
+      return operationParamValues.get(key);
+    }
+
+    function getBodyDraft(op) {
+      const key = getOperationKey(op);
+      return operationBodyDrafts.get(key);
+    }
+
+    function setBodyDraft(op, bodyValue) {
+      const key = getOperationKey(op);
+      operationBodyDrafts.set(key, bodyValue);
+    }
+
+    function resolvePath(pathTemplate, pathParams, values) {
+      let resolved = pathTemplate;
+      for (const param of pathParams) {
+        const rawValue = values[param.name];
+        if (rawValue === undefined || rawValue === null || rawValue === "") {
+          continue;
+        }
+        const placeholder = "{" + param.name + "}";
+        resolved = resolved
+          .split(placeholder)
+          .join(encodeURIComponent(String(rawValue)));
+      }
+      return resolved;
+    }
+
+    function buildRequestPath(op, pathParams, queryParams, values) {
+      const resolvedPath = resolvePath(op.path, pathParams, values);
+      const query = new URLSearchParams();
+
+      for (const param of queryParams) {
+        const rawValue = values[param.name];
+        if (rawValue === undefined || rawValue === null || rawValue === "") {
+          continue;
+        }
+        query.append(param.name, String(rawValue));
+      }
+
+      const queryString = query.toString();
+      return queryString ? resolvedPath + "?" + queryString : resolvedPath;
+    }
+
+    function schemaDefaultValue(schema) {
+      if (!schema || typeof schema !== "object") return null;
+      if (schema.default !== undefined) return schema.default;
+      if (schema.example !== undefined) return schema.example;
+      if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
+      if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+        return schemaDefaultValue(schema.oneOf[0]);
+      }
+      if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        return schemaDefaultValue(schema.anyOf[0]);
+      }
+      if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        return schemaDefaultValue(schema.allOf[0]);
+      }
+
+      switch (schema.type) {
+        case "string":
+          return "";
+        case "number":
+        case "integer":
+          return 0;
+        case "boolean":
+          return false;
+        case "array":
+          return [];
+        case "object": {
+          const required = Array.isArray(schema.required) ? schema.required : [];
+          const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+          const obj = {};
+          for (const fieldName of required) {
+            obj[fieldName] = schemaDefaultValue(properties[fieldName]);
+          }
+          return obj;
+        }
+        default:
+          return null;
+      }
+    }
+
+    function buildRequiredBodyPrefill(schema) {
+      if (!schema || typeof schema !== "object") return "";
+      const prefillValue = schemaDefaultValue(schema);
+      if (
+        prefillValue &&
+        typeof prefillValue === "object" &&
+        !Array.isArray(prefillValue) &&
+        Object.keys(prefillValue).length === 0
+      ) {
+        return "";
+      }
+      try {
+        return JSON.stringify(prefillValue, null, 2);
+      } catch {
+        return "";
+      }
+    }
+
+    function hasMeaningfulRequestBodySchema(schema) {
+      if (!schema || typeof schema !== "object") return false;
+      if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return true;
+      if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) return true;
+      if (Array.isArray(schema.allOf) && schema.allOf.length > 0) return true;
+      if (schema.type && schema.type !== "object") return true;
+      if (schema.additionalProperties !== undefined) return true;
+      if (Array.isArray(schema.required) && schema.required.length > 0) return true;
+      if (schema.properties && typeof schema.properties === "object") {
+        return Object.keys(schema.properties).length > 0;
+      }
+      return false;
+    }
+
+    function renderSidebar() {
+      const nav = document.getElementById("sidebar-nav");
+      const groups = new Map();
+      const query = sidebarSearchQuery.trim().toLowerCase();
+      const visibleOps = query
+        ? operations.filter((op) => {
+            const haystack = [
+              op.name,
+              op.path,
+              op.method,
+              op.tag,
+            ]
+              .join(" ")
+              .toLowerCase();
+            return haystack.includes(query);
+          })
+        : operations;
+
+      for (const op of visibleOps) {
+        if (!groups.has(op.tag)) groups.set(op.tag, []);
+        groups.get(op.tag).push(op);
+      }
+      nav.innerHTML = "";
+      if (visibleOps.length === 0) {
+        nav.innerHTML =
+          '<p class="px-2 text-xs opacity-60">No routes match your search.</p>';
+        return;
+      }
+      for (const [tag, ops] of groups.entries()) {
+        ops.sort((a, b) => {
+          const byName = a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+          if (byName !== 0) return byName;
+
+          const byPath = a.path.localeCompare(b.path, undefined, { sensitivity: "base" });
+          if (byPath !== 0) return byPath;
+
+          return a.method.localeCompare(b.method, undefined, { sensitivity: "base" });
+        });
+
+        const block = document.createElement("div");
+        block.innerHTML = '<h3 class="px-2 mb-2 font-semibold text-xs uppercase tracking-wider opacity-50"></h3><ul class="space-y-0.5"></ul>';
+        block.querySelector("h3").textContent = tag;
+        const list = block.querySelector("ul");
+        for (const op of ops) {
+          const li = document.createElement("li");
+          li.className = "enter-stagger";
+          li.style.setProperty("--stagger-delay", String(Math.min(list.children.length * 22, 180)) + "ms");
+          const a = document.createElement("a");
+          a.href = "#";
+          a.className = op === selected
+            ? "block px-2 py-1.5 rounded-md bg-brand-soft/70 dark:bg-brand/20 text-brand-deep dark:text-brand font-medium transition-colors"
+            : "block px-2 py-1.5 rounded-md hover:bg-black/5 dark:hover:bg-white/5 transition-colors";
+
+          const row = document.createElement("span");
+          row.className = "flex items-center gap-2";
+
+          const method = document.createElement("span");
+          method.className = "px-1.5 py-0.5 rounded text-[10px] font-mono font-semibold " + (methodBadge[op.method] || methodBadgeDefault);
+          method.textContent = op.method;
+
+          const name = document.createElement("span");
+          name.textContent = op.name;
+
+          row.appendChild(method);
+          row.appendChild(name);
+          a.appendChild(row);
+
+          a.onclick = (e) => {
+            e.preventDefault();
+            selected = op;
+            renderSidebar();
+            renderEndpoint();
+            if (window.innerWidth < 768) {
+              setMobileSidebarOpen(false);
+            }
+          };
+          li.appendChild(a);
+          list.appendChild(li);
+        }
+        nav.appendChild(block);
+      }
+    }
+
+    function renderParamSection(title, params) {
+      if (!params.length) return "";
+      let rows = "";
+      for (const p of params) {
+        const type = escapeHtml((p.schema && p.schema.type) || "unknown");
+        const name = escapeHtml(p.name || "");
+        rows += '<div class="py-2 flex justify-between border-b border-light-border/50 dark:border-dark-border/50"><div><code class="text-sm font-mono">' + name + '</code><span class="text-xs text-brand ml-2">' + (p.required ? "required" : "optional") + '</span></div><span class="text-xs font-mono opacity-60">' + type + '</span></div>';
+      }
+      return '<div><h3 class="text-sm font-semibold mb-3 flex items-center border-b border-light-border dark:border-dark-border pb-2">' + escapeHtml(title) + "</h3>" + rows + "</div>";
+    }
+
+    function getSchemaTypeLabel(schema) {
+      if (!schema || typeof schema !== "object") return "unknown";
+      if (Array.isArray(schema.type)) return schema.type.join(" | ");
+      if (schema.type) return String(schema.type);
+      if (schema.properties) return "object";
+      if (schema.items) return "array";
+      if (Array.isArray(schema.oneOf)) return "oneOf";
+      if (Array.isArray(schema.anyOf)) return "anyOf";
+      if (Array.isArray(schema.allOf)) return "allOf";
+      return "unknown";
+    }
+
+    function buildSchemaChildren(schema) {
+      if (!schema || typeof schema !== "object") return [];
+
+      const children = [];
+
+      if (schema.properties && typeof schema.properties === "object") {
+        const requiredSet = new Set(
+          Array.isArray(schema.required) ? schema.required : [],
+        );
+        for (const [name, childSchema] of Object.entries(schema.properties)) {
+          children.push({
+            name,
+            schema: childSchema || {},
+            required: requiredSet.has(name),
+          });
+        }
+      }
+
+      if (schema.items) {
+        children.push({
+          name: "items[]",
+          schema: schema.items,
+          required: true,
+        });
+      }
+
+      return children;
+    }
+
+    function renderSchemaFieldNode(field, depth) {
+      const schema = field.schema || {};
+      const name = escapeHtml(field.name || "field");
+      const requiredLabel = field.required ? "required" : "optional";
+      const type = escapeHtml(getSchemaTypeLabel(schema));
+      const children = buildSchemaChildren(schema);
+      const padding = depth * 14;
+
+      if (!children.length) {
+        return (
+          '<div class="py-2 border-b border-light-border/50 dark:border-dark-border/50" style="padding-left:' +
+          padding +
+          'px"><div class="flex justify-between"><div><code class="text-sm font-mono">' +
+          name +
+          '</code><span class="text-xs text-brand ml-2">' +
+          requiredLabel +
+          '</span></div><span class="text-xs font-mono opacity-60">' +
+          type +
+          "</span></div></div>"
+        );
+      }
+
+      let nested = "";
+      for (const child of children) {
+        nested += renderSchemaFieldNode(child, depth + 1);
+      }
+
+      return (
+        '<details class="border-b border-light-border/50 dark:border-dark-border/50" open>' +
+        '<summary class="list-none cursor-pointer py-2 flex justify-between items-center" style="padding-left:' +
+        padding +
+        'px"><div class="flex items-center gap-2"><span class="text-xs opacity-70">\u25BE</span><code class="text-sm font-mono">' +
+        name +
+        '</code><span class="text-xs text-brand">' +
+        requiredLabel +
+        '</span></div><span class="text-xs font-mono opacity-60">' +
+        type +
+        "</span></summary>" +
+        '<div class="pb-1">' +
+        nested +
+        "</div></details>"
+      );
+    }
+
+    function renderRequestBodySchemaSection(schema) {
+      if (!schema || typeof schema !== "object") return "";
+      const rootChildren = buildSchemaChildren(schema);
+      if (!rootChildren.length) return "";
+
+      let rows = "";
+      for (const child of rootChildren) {
+        rows += renderSchemaFieldNode(child, 0);
+      }
+
+      return (
+        '<div><h3 class="text-sm font-semibold mb-3 flex items-center border-b border-light-border dark:border-dark-border pb-2">Request Body</h3>' +
+        rows +
+        "</div>"
+      );
+    }
+
+    function renderResponseSchemasSection(responses) {
+      if (!responses || typeof responses !== "object") return "";
+
+      const statusCodes = Object.keys(responses).sort((a, b) => {
+        const aNum = Number(a);
+        const bNum = Number(b);
+        if (Number.isInteger(aNum) && Number.isInteger(bNum)) return aNum - bNum;
+        if (Number.isInteger(aNum)) return -1;
+        if (Number.isInteger(bNum)) return 1;
+        return a.localeCompare(b);
+      });
+
+      let sections = "";
+      for (const statusCode of statusCodes) {
+        const responseDef = responses[statusCode];
+        if (!responseDef || typeof responseDef !== "object") continue;
+
+        const jsonSchema =
+          responseDef.content &&
+          responseDef.content["application/json"] &&
+          responseDef.content["application/json"].schema;
+
+        if (!jsonSchema || typeof jsonSchema !== "object") continue;
+
+        const rootChildren = buildSchemaChildren(jsonSchema);
+        if (!rootChildren.length) continue;
+
+        let rows = "";
+        for (const child of rootChildren) {
+          rows += renderSchemaFieldNode(child, 0);
+        }
+
+        sections +=
+          '<div class="mb-4"><h4 class="text-xs font-mono uppercase tracking-wider opacity-70 mb-2">Status ' +
+          escapeHtml(statusCode) +
+          "</h4>" +
+          rows +
+          "</div>";
+      }
+
+      if (!sections) return "";
+
+      return (
+        '<div><h3 class="text-sm font-semibold mb-3 flex items-center border-b border-light-border dark:border-dark-border pb-2">Response Schemas</h3>' +
+        sections +
+        "</div>"
+      );
+    }
+
+    function renderTryItParameterInputs(pathParams, queryParams) {
+      const container = document.getElementById("request-param-inputs");
+      if (!container || !selected) return;
+
+      const values = getParameterValues(selected);
+      container.innerHTML = "";
+
+      const sections = [
+        { title: "Path Values", params: pathParams },
+        { title: "Query Values", params: queryParams },
+      ];
+
+      for (const section of sections) {
+        if (!section.params.length) continue;
+
+        const group = document.createElement("div");
+        group.className = "space-y-2";
+
+        const title = document.createElement("p");
+        title.className = "text-xs font-semibold uppercase tracking-wider opacity-60";
+        title.textContent = section.title;
+        group.appendChild(title);
+
+        for (const param of section.params) {
+          const field = document.createElement("div");
+          field.className = "space-y-1";
+
+          const label = document.createElement("label");
+          label.className = "text-xs opacity-80 flex items-center gap-2";
+
+          const labelName = document.createElement("span");
+          labelName.className = "font-mono";
+          labelName.textContent = param.name;
+
+          const required = document.createElement("span");
+          required.className = "text-[10px] text-brand";
+          required.textContent = param.required ? "required" : "optional";
+
+          label.appendChild(labelName);
+          label.appendChild(required);
+
+          const input = document.createElement("input");
+          input.type = "text";
+          input.value = values[param.name] || "";
+          input.placeholder =
+            section.title === "Path Values" ? param.name : "optional";
+          input.className =
+            "w-full text-sm px-3 py-2 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
+
+          input.addEventListener("input", () => {
+            values[param.name] = input.value;
+            updateRequestPreview();
+          });
+
+          field.appendChild(label);
+          field.appendChild(input);
+          group.appendChild(field);
+        }
+
+        container.appendChild(group);
+      }
+    }
+
+    function renderHeaderInputs() {
+      const container = document.getElementById("header-inputs");
+      if (!container) return;
+
+      container.innerHTML = "";
+      requestHeaders.forEach((entry, index) => {
+        const row = document.createElement("div");
+        row.className = "grid grid-cols-[1fr_1fr_auto] gap-2";
+
+        const keyInput = document.createElement("input");
+        keyInput.type = "text";
+        keyInput.value = entry.key || "";
+        keyInput.placeholder = "Header";
+        keyInput.className =
+          "w-full text-xs px-2.5 py-2 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
+        keyInput.addEventListener("input", () => {
+          entry.key = keyInput.value;
+          updateRequestPreview();
+        });
+
+        const valueInput = document.createElement("input");
+        valueInput.type = "text";
+        valueInput.value = entry.value || "";
+        valueInput.placeholder =
+          String(entry.key || "").toLowerCase() === "authorization"
+            ? "Bearer token"
+            : "Value";
+        valueInput.className =
+          "w-full text-xs px-2.5 py-2 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
+        valueInput.addEventListener("input", () => {
+          entry.value = valueInput.value;
+          updateRequestPreview();
+        });
+
+        const removeButton = document.createElement("button");
+        removeButton.type = "button";
+        removeButton.className =
+          "p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors";
+        removeButton.setAttribute("aria-label", "Remove Header");
+        removeButton.setAttribute("title", "Remove Header");
+        removeButton.innerHTML =
+          '<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 12h12"></path></svg>';
+        removeButton.addEventListener("click", () => {
+          requestHeaders.splice(index, 1);
+          renderHeaderInputs();
+          updateRequestPreview();
+        });
+
+        row.appendChild(keyInput);
+        row.appendChild(valueInput);
+        row.appendChild(removeButton);
+        container.appendChild(row);
+      });
+    }
+
+    function hasHeaderName(headers, expectedName) {
+      const target = expectedName.toLowerCase();
+      return Object.keys(headers).some((key) => key.toLowerCase() === target);
+    }
+
+    function getRequestHeadersObject() {
+      const headers = {};
+      for (const entry of requestHeaders) {
+        const key = String(entry.key || "").trim();
+        const value = String(entry.value || "").trim();
+        if (!key || !value) continue;
+        headers[key] = value;
+      }
+      return headers;
+    }
+
+    function buildCurl(op, headers, body, requestPath) {
+      const url = window.location.origin + requestPath;
+      const lines = ['curl -X ' + op.method + ' "' + url + '"'];
+
+      for (const [name, value] of Object.entries(headers)) {
+        const safeName = String(name).replace(/"/g, '\\"');
+        const safeValue = String(value).replace(/"/g, '\\"');
+        lines.push('  -H "' + safeName + ": " + safeValue + '"');
+      }
+
+      if (body) {
+        lines.push("  -d '" + body.replace(/'/g, "'\\\\''") + "'");
+      }
+
+      return lines.join(" \\\\\\n");
+    }
+
+    function formatBodyJsonInput() {
+      const bodyInput = document.getElementById("body-input");
+      if (!bodyInput) return;
+      const current = bodyInput.value.trim();
+      if (!current) return;
+      try {
+        bodyInput.value = JSON.stringify(JSON.parse(current), null, 2);
+      } catch {}
+    }
+
+    function escapeHtml(value) {
+      return String(value)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+    }
+
+    function toPrettyJson(value) {
+      const trimmed = (value || "").trim();
+      if (!trimmed) return null;
+      try {
+        return JSON.stringify(JSON.parse(trimmed), null, 2);
+      } catch {
+        return null;
+      }
+    }
+
+    function highlightJson(jsonText) {
+      const escaped = escapeHtml(jsonText);
+      return escaped.replace(
+        /("(\\\\u[a-zA-Z0-9]{4}|\\\\[^u]|[^\\\\"])*"(\\s*:)?|\\btrue\\b|\\bfalse\\b|\\bnull\\b|-?\\d+(?:\\.\\d+)?(?:[eE][+\\-]?\\d+)?)/g,
+        (match) => {
+          let cls = "json-number";
+          if (match.startsWith('"')) {
+            cls = match.endsWith(":") ? "json-key" : "json-string";
+          } else if (match === "true" || match === "false") {
+            cls = "json-boolean";
+          } else if (match === "null") {
+            cls = "json-null";
+          }
+          return '<span class="' + cls + '">' + match + "</span>";
+        },
+      );
+    }
+
+    function updateBodyJsonPresentation() {
+      const bodyInput = document.getElementById("body-input");
+      const highlight = document.getElementById("body-highlight");
+      const bodySection = document.getElementById("request-body-section");
+
+      if (!bodyInput || !highlight || !bodySection) return;
+      if (bodySection.classList.contains("hidden")) {
+        highlight.innerHTML = "";
+        return;
+      }
+
+      const raw = bodyInput.value || "";
+      if (!raw.trim()) {
+        const placeholder = bodyInput.getAttribute("placeholder") || "";
+        highlight.innerHTML = '<span class="opacity-40">' + escapeHtml(placeholder) + "</span>";
+        return;
+      }
+
+      const prettyJson = toPrettyJson(raw);
+      if (!prettyJson) {
+        highlight.innerHTML = escapeHtml(raw);
+        return;
+      }
+
+      highlight.innerHTML = highlightJson(raw);
+    }
+
+    function syncBodyEditorScroll() {
+      const bodyInput = document.getElementById("body-input");
+      const highlight = document.getElementById("body-highlight");
+      if (!bodyInput || !highlight) return;
+      highlight.scrollTop = bodyInput.scrollTop;
+      highlight.scrollLeft = bodyInput.scrollLeft;
+    }
+
+    function updateExpandEditorPresentation() {
+      const editor = document.getElementById("expand-editor");
+      const highlight = document.getElementById("expand-editor-highlight");
+      if (!editor || !highlight) return;
+      const raw = editor.value || "";
+      if (!raw.trim()) {
+        highlight.innerHTML = "";
+        return;
+      }
+      const prettyJson = toPrettyJson(raw);
+      highlight.innerHTML = prettyJson ? highlightJson(raw) : escapeHtml(raw);
+    }
+
+    function syncExpandEditorScroll() {
+      const editor = document.getElementById("expand-editor");
+      const highlight = document.getElementById("expand-editor-highlight");
+      if (!editor || !highlight) return;
+      highlight.scrollTop = editor.scrollTop;
+      highlight.scrollLeft = editor.scrollLeft;
+    }
+
+    function formatResponseText(responseText) {
+      const trimmed = (responseText || "").trim();
+      if (!trimmed) return { text: "(empty)", isJson: false };
+      try {
+        return {
+          text: JSON.stringify(JSON.parse(trimmed), null, 2),
+          isJson: true,
+        };
+      } catch {
+        return {
+          text: responseText,
+          isJson: false,
+        };
+      }
+    }
+
+    function setResponseContent(headerText, bodyText, isJson) {
+      const result = document.getElementById("result");
+      if (!result) return;
+      const fullText = String(headerText || "") + String(bodyText || "");
+      result.dataset.raw = fullText;
+      result.dataset.header = String(headerText || "");
+      result.dataset.body = String(bodyText || "");
+      result.dataset.isJson = isJson ? "true" : "false";
+      if (isJson) {
+        result.innerHTML = escapeHtml(String(headerText || "")) + highlightJson(String(bodyText || ""));
+      } else {
+        result.textContent = fullText;
+      }
+    }
+
+    function setSubmitLoading(isLoading) {
+      const sendButton = document.getElementById("send-btn");
+      const spinner = document.getElementById("send-btn-spinner");
+      const label = document.getElementById("send-btn-label");
+      if (!sendButton) return;
+
+      sendButton.disabled = isLoading;
+      sendButton.classList.toggle("opacity-80", isLoading);
+      sendButton.classList.toggle("cursor-wait", isLoading);
+      if (spinner) spinner.classList.toggle("hidden", !isLoading);
+      if (label) label.textContent = isLoading ? "Sending..." : "Submit";
+    }
+
+    function updateRequestPreview() {
+      if (!selected) return;
+
+      const { path, query } = getOperationParameterGroups(selected);
+      const values = getParameterValues(selected);
+      const requestPath = buildRequestPath(selected, path, query, values);
+      const bodyInput = document.getElementById("body-input");
+      const body = bodyInput ? bodyInput.value.trim() : "";
+      const headers = getRequestHeadersObject();
+      if (body && !hasHeaderName(headers, "Content-Type")) {
+        headers["Content-Type"] = "application/json";
+      }
+
+      document.getElementById("endpoint-path").textContent = requestPath;
+      document.getElementById("curl-code").textContent = buildCurl(
+        selected,
+        headers,
+        body,
+        requestPath,
+      );
+    }
+
+    function renderEndpoint() {
+      if (!selected) return;
+      const endpointCard = document.getElementById("endpoint-card");
+      if (endpointCard) {
+        endpointCard.classList.remove("enter-fade-up");
+        // Restart CSS animation for each operation switch
+        void endpointCard.offsetWidth;
+        endpointCard.classList.add("enter-fade-up");
+      }
+
+      const op = selected.operation || {};
+      const reqSchema = op.requestBody && op.requestBody.content && op.requestBody.content["application/json"] && op.requestBody.content["application/json"].schema;
+      const requestBodySection = document.getElementById("request-body-section");
+      const bodyInput = document.getElementById("body-input");
+      const expandBodyBtn = document.getElementById("expand-body-btn");
+      const supportsBody = hasMeaningfulRequestBodySchema(reqSchema);
+
+      if (requestBodySection) {
+        requestBodySection.classList.toggle("hidden", !supportsBody);
+      }
+      if (supportsBody && bodyInput) {
+        const existingDraft = getBodyDraft(selected);
+        if (typeof existingDraft === "string") {
+          bodyInput.value = existingDraft;
+        } else {
+          const prefill = buildRequiredBodyPrefill(reqSchema);
+          bodyInput.value = prefill;
+          setBodyDraft(selected, prefill);
+        }
+      } else if (!supportsBody && bodyInput) {
+        bodyInput.value = "";
+      }
+      if (expandBodyBtn) {
+        expandBodyBtn.disabled = !supportsBody;
+      }
+      setResponseContent("", "", false);
+
+      document.getElementById("tag-title").textContent = selected.tag;
+      document.getElementById("tag-description").textContent = op.description || "Interactive API documentation.";
+      const methodNode = document.getElementById("endpoint-method");
+      methodNode.textContent = selected.method;
+      methodNode.className = "px-2.5 py-0.5 rounded-full text-xs font-mono font-medium " + (methodBadge[selected.method] || methodBadgeDefault);
+      document.getElementById("endpoint-title").textContent = selected.name;
+      document.getElementById("endpoint-path").textContent = selected.path;
+
+      const { all: params, query, path, headers } =
+        getOperationParameterGroups(selected);
+
+      let html = "";
+      html += renderParamSection("Path Parameters", path);
+      html += renderParamSection("Query Parameters", query);
+      html += renderParamSection("Header Parameters", headers);
+
+      html += renderRequestBodySchemaSection(reqSchema);
+      html += renderResponseSchemasSection(op.responses);
+      document.getElementById("params-column").innerHTML = html || '<div class="text-sm opacity-70">No parameters</div>';
+      renderTryItParameterInputs(path, query);
+      renderHeaderInputs();
+      updateRequestPreview();
+      updateBodyJsonPresentation();
+      syncBodyEditorScroll();
+    }
+
+    document.getElementById("copy-curl").addEventListener("click", async () => {
+      try { await navigator.clipboard.writeText(document.getElementById("curl-code").textContent || ""); } catch {}
+    });
+    document.getElementById("sidebar-search").addEventListener("input", (event) => {
+      sidebarSearchQuery = event.currentTarget.value || "";
+      renderSidebar();
+    });
+
+    document.getElementById("send-btn").addEventListener("click", async () => {
+      if (!selected) return;
+      const { path, query } = getOperationParameterGroups(selected);
+      const values = getParameterValues(selected);
+      const missingPathParams = path.filter((param) => {
+        if (param.required === false) return false;
+        const value = values[param.name];
+        return value === undefined || value === null || String(value).trim() === "";
+      });
+
+      if (missingPathParams.length > 0) {
+        setResponseContent(
+          "",
+          "Missing required path parameter(s): " +
+            missingPathParams.map((param) => param.name).join(", "),
+          false,
+        );
+        return;
+      }
+
+      const requestPath = buildRequestPath(selected, path, query, values);
+      formatBodyJsonInput();
+      updateBodyJsonPresentation();
+      const op = selected.operation || {};
+      const reqSchema = op.requestBody && op.requestBody.content && op.requestBody.content["application/json"] && op.requestBody.content["application/json"].schema;
+      const supportsBody = hasMeaningfulRequestBodySchema(reqSchema);
+      const bodyInput = document.getElementById("body-input");
+      const body =
+        supportsBody && bodyInput ? bodyInput.value.trim() : "";
+      const headers = getRequestHeadersObject();
+      if (body && !hasHeaderName(headers, "Content-Type")) {
+        headers["Content-Type"] = "application/json";
+      }
+
+      setSubmitLoading(true);
+      try {
+        const requestStart = performance.now();
+        const response = await fetch(requestPath, { method: selected.method, headers, body: body || undefined });
+        const text = await response.text();
+        const responseTimeMs = Math.round(performance.now() - requestStart);
+        const contentType = response.headers.get("content-type") || "unknown";
+        const formattedResponse = formatResponseText(text);
+        const headerText =
+          "Status: " + response.status + " " + response.statusText + "\\n" +
+          "Content-Type: " + contentType + "\\n" +
+          "Response Time: " + responseTimeMs + " ms\\n\\n";
+        setResponseContent(
+          headerText,
+          formattedResponse.text,
+          formattedResponse.isJson,
+        );
+      } catch (error) {
+        setResponseContent("", "Request failed: " + String(error), false);
+      } finally {
+        setSubmitLoading(false);
+      }
+    });
+
+    function openExpandModal(mode) {
+      const modal = document.getElementById("expand-modal");
+      const title = document.getElementById("expand-modal-title");
+      const editorShell = document.getElementById("expand-editor-shell");
+      const editor = document.getElementById("expand-editor");
+      const viewer = document.getElementById("expand-viewer");
+      const apply = document.getElementById("expand-apply");
+      const bodyInput = document.getElementById("body-input");
+      const result = document.getElementById("result");
+      if (!modal || !title || !editorShell || !editor || !viewer || !apply) return;
+
+      expandModalMode = mode;
+      modal.classList.remove("hidden");
+      modal.classList.add("flex");
+
+      if (mode === "body") {
+        title.textContent = "Request Body";
+        editorShell.classList.remove("hidden");
+        viewer.classList.add("hidden");
+        apply.classList.remove("hidden");
+        editor.value = bodyInput ? bodyInput.value : "";
+        updateExpandEditorPresentation();
+        syncExpandEditorScroll();
+      } else {
+        title.textContent = "Response";
+        viewer.classList.remove("hidden");
+        editorShell.classList.add("hidden");
+        apply.classList.add("hidden");
+        const hasResponse = Boolean(result && result.dataset && result.dataset.raw);
+        if (!hasResponse) {
+          viewer.textContent = "(empty response yet)";
+          return;
+        }
+
+        const header = result.dataset.header || "";
+        const body = result.dataset.body || "";
+        const isJson = result.dataset.isJson === "true";
+        if (isJson) {
+          viewer.innerHTML = escapeHtml(header) + highlightJson(body);
+        } else {
+          viewer.textContent = result.dataset.raw || "(empty response yet)";
+        }
+      }
+    }
+
+    function closeExpandModal() {
+      const modal = document.getElementById("expand-modal");
+      if (!modal) return;
+      modal.classList.add("hidden");
+      modal.classList.remove("flex");
+      expandModalMode = null;
+    }
+
+    document.getElementById("add-header-btn").addEventListener("click", () => {
+      requestHeaders.push({ key: "", value: "" });
+      renderHeaderInputs();
+      updateRequestPreview();
+    });
+    document.getElementById("body-input").addEventListener("input", () => {
+      if (selected) {
+        setBodyDraft(selected, document.getElementById("body-input").value);
+      }
+      updateRequestPreview();
+      updateBodyJsonPresentation();
+      syncBodyEditorScroll();
+    });
+    document.getElementById("body-input").addEventListener("scroll", () => {
+      syncBodyEditorScroll();
+    });
+    document.getElementById("body-input").addEventListener("keydown", (event) => {
+      if (event.key !== "Tab") return;
+      event.preventDefault();
+      const input = event.currentTarget;
+      const start = input.selectionStart;
+      const end = input.selectionEnd;
+      const value = input.value;
+      const tab = "  ";
+      input.value = value.slice(0, start) + tab + value.slice(end);
+      input.selectionStart = input.selectionEnd = start + tab.length;
+      if (selected) {
+        setBodyDraft(selected, input.value);
+      }
+      updateRequestPreview();
+      updateBodyJsonPresentation();
+      syncBodyEditorScroll();
+    });
+    document.getElementById("body-input").addEventListener("blur", () => {
+      formatBodyJsonInput();
+      if (selected) {
+        setBodyDraft(selected, document.getElementById("body-input").value);
+      }
+      updateRequestPreview();
+      updateBodyJsonPresentation();
+      syncBodyEditorScroll();
+    });
+    document.getElementById("expand-editor").addEventListener("input", () => {
+      updateExpandEditorPresentation();
+      syncExpandEditorScroll();
+    });
+    document.getElementById("expand-editor").addEventListener("scroll", () => {
+      syncExpandEditorScroll();
+    });
+    document.getElementById("expand-editor").addEventListener("keydown", (event) => {
+      if (event.key !== "Tab") return;
+      event.preventDefault();
+      const editor = event.currentTarget;
+      const start = editor.selectionStart;
+      const end = editor.selectionEnd;
+      const value = editor.value;
+      const tab = "  ";
+      editor.value = value.slice(0, start) + tab + value.slice(end);
+      editor.selectionStart = editor.selectionEnd = start + tab.length;
+      updateExpandEditorPresentation();
+      syncExpandEditorScroll();
+    });
+    document.getElementById("expand-editor").addEventListener("blur", () => {
+      const editor = document.getElementById("expand-editor");
+      const current = editor.value.trim();
+      if (current) {
+        try {
+          editor.value = JSON.stringify(JSON.parse(current), null, 2);
+        } catch {}
+      }
+      updateExpandEditorPresentation();
+      syncExpandEditorScroll();
+    });
+    document.getElementById("expand-body-btn").addEventListener("click", () => {
+      openExpandModal("body");
+    });
+    document.getElementById("expand-response-btn").addEventListener("click", () => {
+      openExpandModal("response");
+    });
+    document.getElementById("expand-close").addEventListener("click", closeExpandModal);
+    document.getElementById("expand-apply").addEventListener("click", () => {
+      if (expandModalMode !== "body") {
+        closeExpandModal();
+        return;
+      }
+
+      const editor = document.getElementById("expand-editor");
+      const bodyInput = document.getElementById("body-input");
+      if (editor && bodyInput) {
+        bodyInput.value = editor.value;
+        formatBodyJsonInput();
+        if (selected) {
+          setBodyDraft(selected, bodyInput.value);
+        }
+        updateRequestPreview();
+        updateBodyJsonPresentation();
+        syncBodyEditorScroll();
+      }
+      closeExpandModal();
+    });
+    document.getElementById("expand-modal").addEventListener("click", (event) => {
+      if (event.target === event.currentTarget) {
+        closeExpandModal();
+      }
+    });
+    document.getElementById("sidebar-open").addEventListener("click", () => {
+      setMobileSidebarOpen(true);
+    });
+    document.getElementById("sidebar-close").addEventListener("click", () => {
+      setMobileSidebarOpen(false);
+    });
+    document.getElementById("mobile-backdrop").addEventListener("click", () => {
+      setMobileSidebarOpen(false);
+    });
+    window.addEventListener("resize", () => {
+      if (window.innerWidth >= 768 && isMobileSidebarOpen) {
+        setMobileSidebarOpen(false);
+      }
+    });
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        if (isMobileSidebarOpen) {
+          setMobileSidebarOpen(false);
+        }
+        closeExpandModal();
+      }
+    });
+
+    const themeToggleBtn = document.getElementById('theme-toggle');
+    const htmlElement = document.documentElement;
+    themeToggleBtn.addEventListener('click', () => {
+      htmlElement.classList.toggle('dark');
+      if (htmlElement.classList.contains('dark')) {
+        localStorage.setItem('theme', 'dark');
+      } else {
+        localStorage.setItem('theme', 'light');
+      }
+    });
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', e => {
+      if (!('theme' in localStorage)) {
+        if (e.matches) htmlElement.classList.add('dark');
+        else htmlElement.classList.remove('dark');
+      }
+    });
+
+    setMobileSidebarOpen(false);
+    renderSidebar();
+    renderEndpoint();
+  </script>
+</body>
+</html>`;
+}
+
+// src/openapi/generator.ts
+function isJSONSchemaCapable(schema) {
+  const standard = schema?.["~standard"];
+  const converter = standard?.jsonSchema;
+  return !!standard && typeof standard === "object" && standard.version === 1 && !!converter && typeof converter.input === "function" && typeof converter.output === "function";
+}
+function normalizeRoutePathForOpenAPI(path) {
+  let wildcardCount = 0;
+  const pathParamNames = [];
+  const segments = path.split("/").map((segment) => {
+    const greedyParamMatch = /^:([A-Za-z0-9_]+)\+$/.exec(segment);
+    if (greedyParamMatch?.[1]) {
+      pathParamNames.push(greedyParamMatch[1]);
+      return `{${greedyParamMatch[1]}}`;
+    }
+    const paramMatch = /^:([A-Za-z0-9_]+)$/.exec(segment);
+    if (paramMatch?.[1]) {
+      pathParamNames.push(paramMatch[1]);
+      return `{${paramMatch[1]}}`;
+    }
+    if (segment === "*") {
+      wildcardCount += 1;
+      const wildcardParamName = wildcardCount === 1 ? "wildcard" : `wildcard${wildcardCount}`;
+      pathParamNames.push(wildcardParamName);
+      return `{${wildcardParamName}}`;
+    }
+    return segment;
+  });
+  return {
+    openapiPath: segments.join("/"),
+    pathParamNames
+  };
+}
+function toOpenAPIPath(path) {
+  return normalizeRoutePathForOpenAPI(path).openapiPath;
+}
+function createOperationId(method, path) {
+  const normalized = `${method.toLowerCase()}_${path}`.replace(/[:{}]/g, "").replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+  return normalized || `${method.toLowerCase()}_operation`;
+}
+function inferTagFromPath(path) {
+  const segments = path.split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (!segment.startsWith(":") && segment !== "*") {
+      return segment.toLowerCase();
+    }
+  }
+  return "default";
+}
+function extractPathParamNames(path) {
+  return normalizeRoutePathForOpenAPI(path).pathParamNames;
+}
+function addMissingPathParameters(operation, routePath) {
+  const existingPathNames = new Set((operation.parameters || []).filter((p) => p.in === "path").map((p) => String(p.name)));
+  for (const pathName of extractPathParamNames(routePath)) {
+    if (existingPathNames.has(pathName))
+      continue;
+    (operation.parameters ||= []).push({
+      name: pathName,
+      in: "path",
+      required: true,
+      schema: { type: "string" }
+    });
+  }
+}
+function isNoBodyResponseStatus(status) {
+  const numericStatus = Number(status);
+  if (!Number.isInteger(numericStatus))
+    return false;
+  return numericStatus >= 100 && numericStatus < 200 || numericStatus === 204 || numericStatus === 205 || numericStatus === 304;
+}
+function getResponseDescription(status) {
+  if (status === "204")
+    return "No Content";
+  if (status === "205")
+    return "Reset Content";
+  if (status === "304")
+    return "Not Modified";
+  const numericStatus = Number(status);
+  if (Number.isInteger(numericStatus) && numericStatus >= 100 && numericStatus < 200) {
+    return "Informational";
+  }
+  return "OK";
+}
+function convertInputSchema(routePath, inputSchema, target, warnings) {
+  if (!isJSONSchemaCapable(inputSchema)) {
+    return null;
+  }
+  try {
+    return inputSchema["~standard"].jsonSchema.input({ target });
+  } catch (error) {
+    warnings.push(`[OpenAPI] Failed input schema conversion for ${routePath}: ${error instanceof Error ? error.message : String(error)}. Falling back to a permissive JSON Schema.`);
+    const fallback = buildFallbackJSONSchema(inputSchema);
+    return isEmptyObjectSchema(fallback) ? null : fallback;
+  }
+}
+function convertOutputSchema(routePath, statusCode, outputSchema, target, warnings) {
+  if (!isJSONSchemaCapable(outputSchema)) {
+    return null;
+  }
+  try {
+    return outputSchema["~standard"].jsonSchema.output({ target });
+  } catch (error) {
+    warnings.push(`[OpenAPI] Failed output schema conversion for ${routePath} (${statusCode}): ${error instanceof Error ? error.message : String(error)}. Falling back to a permissive JSON Schema.`);
+    return buildFallbackJSONSchema(outputSchema);
+  }
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isEmptyObjectSchema(value) {
+  return isRecord(value) && Object.keys(value).length === 0;
+}
+function getValidatorSchemaDef(schema) {
+  if (!schema || typeof schema !== "object")
+    return null;
+  const value = schema;
+  if (isRecord(value._def))
+    return value._def;
+  if (isRecord(value._zod) && isRecord(value._zod.def)) {
+    return value._zod.def;
+  }
+  return null;
+}
+function getSchemaKind(def) {
+  if (!def)
+    return null;
+  const typeName = def.typeName;
+  if (typeof typeName === "string")
+    return typeName;
+  const type = def.type;
+  if (typeof type === "string")
+    return type;
+  return null;
+}
+function pickSchemaChild(def) {
+  const candidates = ["innerType", "schema", "type", "out", "in", "left", "right"];
+  for (const key of candidates) {
+    if (key in def)
+      return def[key];
+  }
+  return;
+}
+function pickSchemaObjectCandidate(def, keys) {
+  for (const key of keys) {
+    const value = def[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return value;
+    }
+  }
+  return;
+}
+function isOptionalWrapperKind(kind) {
+  if (!kind)
+    return false;
+  const lower = kind.toLowerCase();
+  return lower.includes("optional") || lower.includes("default") || lower.includes("catch");
+}
+function unwrapOptionalForRequired(schema) {
+  let current = schema;
+  let optional = false;
+  let guard = 0;
+  while (guard < 8) {
+    guard += 1;
+    const def = getValidatorSchemaDef(current);
+    const kind = getSchemaKind(def);
+    if (!def || !isOptionalWrapperKind(kind))
+      break;
+    optional = true;
+    const inner = pickSchemaChild(def);
+    if (!inner)
+      break;
+    current = inner;
+  }
+  return { schema: current, optional };
+}
+function getObjectShape(def) {
+  const rawShape = def.shape;
+  if (typeof rawShape === "function") {
+    try {
+      const resolved = rawShape();
+      return isRecord(resolved) ? resolved : {};
+    } catch {
+      return {};
+    }
+  }
+  return isRecord(rawShape) ? rawShape : {};
+}
+function mapPrimitiveKind(kind) {
+  const lower = kind.toLowerCase();
+  if (lower.includes("string"))
+    return { type: "string" };
+  if (lower.includes("number"))
+    return { type: "number" };
+  if (lower.includes("boolean"))
+    return { type: "boolean" };
+  if (lower.includes("bigint"))
+    return { type: "string" };
+  if (lower.includes("null"))
+    return { type: "null" };
+  if (lower.includes("any") || lower.includes("unknown") || lower.includes("never"))
+    return {};
+  if (lower.includes("date"))
+    return { type: "string", format: "date-time" };
+  if (lower.includes("custom"))
+    return { type: "object", additionalProperties: true };
+  return null;
+}
+function buildIntrospectedFallbackJSONSchema(schema, seen = new WeakSet) {
+  if (!schema || typeof schema !== "object")
+    return {};
+  if (seen.has(schema))
+    return {};
+  seen.add(schema);
+  const def = getValidatorSchemaDef(schema);
+  const kind = getSchemaKind(def);
+  if (!def || !kind)
+    return {};
+  const primitive = mapPrimitiveKind(kind);
+  if (primitive)
+    return primitive;
+  const lower = kind.toLowerCase();
+  if (lower.includes("object")) {
+    const shape = getObjectShape(def);
+    const properties = {};
+    const required = [];
+    for (const [key, child2] of Object.entries(shape)) {
+      const unwrapped = unwrapOptionalForRequired(child2);
+      properties[key] = buildIntrospectedFallbackJSONSchema(unwrapped.schema, seen);
+      if (!unwrapped.optional)
+        required.push(key);
+    }
+    const out = {
+      type: "object",
+      properties,
+      additionalProperties: true
+    };
+    if (required.length > 0) {
+      out.required = required;
+    }
+    return out;
+  }
+  if (lower.includes("array")) {
+    const itemSchema = pickSchemaObjectCandidate(def, ["element", "items", "innerType", "type"]) ?? {};
+    return {
+      type: "array",
+      items: buildIntrospectedFallbackJSONSchema(itemSchema, seen)
+    };
+  }
+  if (lower.includes("record")) {
+    const valueType = def.valueType ?? def.valueSchema;
+    return {
+      type: "object",
+      additionalProperties: valueType ? buildIntrospectedFallbackJSONSchema(valueType, seen) : true
+    };
+  }
+  if (lower.includes("tuple")) {
+    const items = Array.isArray(def.items) ? def.items : [];
+    const prefixItems = items.map((item) => buildIntrospectedFallbackJSONSchema(item, seen));
+    return {
+      type: "array",
+      prefixItems,
+      minItems: prefixItems.length,
+      maxItems: prefixItems.length
+    };
+  }
+  if (lower.includes("union")) {
+    const options = def.options ?? def.schemas ?? [];
+    if (!Array.isArray(options) || options.length === 0)
+      return {};
+    return {
+      anyOf: options.map((option) => buildIntrospectedFallbackJSONSchema(option, seen))
+    };
+  }
+  if (lower.includes("intersection")) {
+    const left = def.left;
+    const right = def.right;
+    if (!left || !right)
+      return {};
+    return {
+      allOf: [buildIntrospectedFallbackJSONSchema(left, seen), buildIntrospectedFallbackJSONSchema(right, seen)]
+    };
+  }
+  if (lower.includes("enum")) {
+    const values = def.values;
+    if (Array.isArray(values))
+      return { enum: values };
+    if (values && typeof values === "object")
+      return { enum: Object.values(values) };
+    return {};
+  }
+  if (lower.includes("literal")) {
+    const value = def.value;
+    if (value === undefined)
+      return {};
+    const valueType = value === null ? "null" : typeof value;
+    if (valueType === "string" || valueType === "number" || valueType === "boolean" || valueType === "null") {
+      return { type: valueType, const: value };
+    }
+    return { const: value };
+  }
+  if (lower.includes("nullable")) {
+    const inner = pickSchemaChild(def);
+    if (!inner)
+      return {};
+    return {
+      anyOf: [buildIntrospectedFallbackJSONSchema(inner, seen), { type: "null" }]
+    };
+  }
+  if (lower.includes("lazy")) {
+    const getter = def.getter;
+    if (typeof getter !== "function")
+      return {};
+    try {
+      return buildIntrospectedFallbackJSONSchema(getter(), seen);
+    } catch {
+      return {};
+    }
+  }
+  const child = pickSchemaChild(def);
+  if (child)
+    return buildIntrospectedFallbackJSONSchema(child, seen);
+  return {};
+}
+function buildFallbackJSONSchema(schema) {
+  const def = getValidatorSchemaDef(schema);
+  if (!def)
+    return {};
+  return buildIntrospectedFallbackJSONSchema(schema);
+}
+function addStructuredInputToOperation(operation, inputJSONSchema) {
+  if (!isRecord(inputJSONSchema))
+    return;
+  if (inputJSONSchema.type !== "object" || !isRecord(inputJSONSchema.properties)) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        "application/json": {
+          schema: inputJSONSchema
+        }
+      }
+    };
+    return;
+  }
+  const rootRequired = new Set(Array.isArray(inputJSONSchema.required) ? inputJSONSchema.required : []);
+  const properties = inputJSONSchema.properties;
+  const parameters = Array.isArray(operation.parameters) ? operation.parameters : [];
+  const parameterSections = [
+    { key: "params", in: "path" },
+    { key: "query", in: "query" },
+    { key: "headers", in: "header" },
+    { key: "cookies", in: "cookie" }
+  ];
+  for (const section of parameterSections) {
+    const sectionSchema = properties[section.key];
+    if (!isRecord(sectionSchema))
+      continue;
+    if (sectionSchema.type !== "object" || !isRecord(sectionSchema.properties))
+      continue;
+    const sectionRequired = new Set(Array.isArray(sectionSchema.required) ? sectionSchema.required : []);
+    for (const [name, schema] of Object.entries(sectionSchema.properties)) {
+      parameters.push({
+        name,
+        in: section.in,
+        required: section.in === "path" ? true : sectionRequired.has(name),
+        schema: isRecord(schema) ? schema : {}
+      });
+    }
+  }
+  if (parameters.length > 0) {
+    const deduped = new Map;
+    for (const parameter of parameters) {
+      deduped.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+    operation.parameters = [...deduped.values()];
+  }
+  const bodySchema = properties.body;
+  if (bodySchema) {
+    operation.requestBody = {
+      required: rootRequired.has("body"),
+      content: {
+        "application/json": {
+          schema: isRecord(bodySchema) ? bodySchema : {}
+        }
+      }
+    };
+  }
+}
+function addOutputSchemasToOperation(operation, routePath, routeSchema, target, warnings) {
+  const output = routeSchema.output;
+  if (!output) {
+    operation.responses = {
+      200: { description: "OK" }
+    };
+    return;
   }
-  bulkAddRoutes(entries) {
-    for (const entry of entries) {
-      this.routes.push(entry);
+  const responses = {};
+  if (typeof output === "object" && output !== null && "~standard" in output) {
+    const outputSchema = convertOutputSchema(routePath, "200", output, target, warnings);
+    if (outputSchema) {
+      responses["200"] = {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: outputSchema
+          }
+        }
+      };
+    } else {
+      responses["200"] = { description: "OK" };
+    }
+  } else {
+    for (const [statusCode, schema] of Object.entries(output)) {
+      const status = String(statusCode);
+      const outputSchema = convertOutputSchema(routePath, status, schema, target, warnings);
+      const description = getResponseDescription(status);
+      if (outputSchema && !isNoBodyResponseStatus(status)) {
+        responses[status] = {
+          description,
+          content: {
+            "application/json": {
+              schema: outputSchema
+            }
+          }
+        };
+      } else {
+        responses[status] = {
+          description
+        };
+      }
     }
-    this.sortRoutes();
   }
-  getRoutes() {
-    return this.routes;
+  if (Object.keys(responses).length === 0) {
+    responses["200"] = { description: "OK" };
   }
-  async handle(request) {
-    let url;
-    try {
-      url = new URL(request.url);
-    } catch {
-      return APIError.badRequest("Malformed request URL");
+  operation.responses = responses;
+}
+function generateOpenAPIDocument(routes, options) {
+  const warnings = [];
+  const paths = {};
+  for (const route of routes) {
+    if (route.options.expose === false)
+      continue;
+    if (!route.method || !route.path)
+      continue;
+    const method = route.method.toLowerCase();
+    if (method === "options")
+      continue;
+    const openapiPath = toOpenAPIPath(route.path);
+    const operation = {
+      operationId: createOperationId(method, openapiPath),
+      tags: [route.options.schema?.tag || inferTagFromPath(route.path)]
+    };
+    const inputJSONSchema = convertInputSchema(route.path, route.options.schema?.input, options.target, warnings);
+    if (inputJSONSchema) {
+      addStructuredInputToOperation(operation, inputJSONSchema);
     }
-    request._parsedUrl = url;
-    const pathname = url.pathname;
-    for (const [method, regex, handlers, path] of this.routes) {
-      if (request.method === "OPTIONS" || request.method === method) {
-        const match = pathname.match(regex);
-        if (match) {
-          const req = request;
-          this.prepareRequest(req, {
-            params: match.groups || {},
-            route: path || pathname
-          });
-          for (const handler of handlers) {
-            const response = await handler(req);
-            if (response)
-              return response;
-          }
-        }
+    addMissingPathParameters(operation, route.path);
+    addOutputSchemasToOperation(operation, route.path, route.options.schema || {}, options.target, warnings);
+    paths[openapiPath] ||= {};
+    paths[openapiPath][method] = operation;
+  }
+  const openapiVersion = options.target === "openapi-3.0" ? "3.0.3" : "3.1.0";
+  const document = {
+    openapi: openapiVersion,
+    info: {
+      title: options.info?.title || "Vector API",
+      version: options.info?.version || "1.0.0",
+      ...options.info?.description ? { description: options.info.description } : {}
+    },
+    paths
+  };
+  return {
+    document,
+    warnings
+  };
+}
+
+// src/core/server.ts
+var OPENAPI_TAILWIND_ASSET_PATH = "/_vector/openapi/tailwindcdn.js";
+var OPENAPI_LOGO_DARK_ASSET_PATH = "/_vector/openapi/logo_dark.svg";
+var OPENAPI_LOGO_WHITE_ASSET_PATH = "/_vector/openapi/logo_white.svg";
+var OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH = "/_vector/openapi/favicon/apple-touch-icon.png";
+var OPENAPI_FAVICON_32_ASSET_PATH = "/_vector/openapi/favicon/favicon-32x32.png";
+var OPENAPI_FAVICON_16_ASSET_PATH = "/_vector/openapi/favicon/favicon-16x16.png";
+var OPENAPI_FAVICON_ICO_ASSET_PATH = "/_vector/openapi/favicon/favicon.ico";
+var OPENAPI_WEBMANIFEST_ASSET_PATH = "/_vector/openapi/favicon/site.webmanifest";
+var OPENAPI_ANDROID_192_ASSET_PATH = "/_vector/openapi/favicon/android-chrome-192x192.png";
+var OPENAPI_ANDROID_512_ASSET_PATH = "/_vector/openapi/favicon/android-chrome-512x512.png";
+var OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/tailwindcdn.js",
+  "../src/openapi/assets/tailwindcdn.js",
+  "../../src/openapi/assets/tailwindcdn.js"
+];
+var OPENAPI_LOGO_DARK_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/logo_dark.svg",
+  "../src/openapi/assets/logo_dark.svg",
+  "../../src/openapi/assets/logo_dark.svg"
+];
+var OPENAPI_LOGO_WHITE_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/logo_white.svg",
+  "../src/openapi/assets/logo_white.svg",
+  "../../src/openapi/assets/logo_white.svg"
+];
+var OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/tailwindcdn.js",
+  "openapi/assets/tailwindcdn.js",
+  "dist/openapi/assets/tailwindcdn.js"
+];
+var OPENAPI_LOGO_DARK_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/logo_dark.svg",
+  "openapi/assets/logo_dark.svg",
+  "dist/openapi/assets/logo_dark.svg"
+];
+var OPENAPI_LOGO_WHITE_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/logo_white.svg",
+  "openapi/assets/logo_white.svg",
+  "dist/openapi/assets/logo_white.svg"
+];
+var OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES = [
+  "../openapi/assets/favicon",
+  "../src/openapi/assets/favicon",
+  "../../src/openapi/assets/favicon"
+];
+var OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES = [
+  "src/openapi/assets/favicon",
+  "openapi/assets/favicon",
+  "dist/openapi/assets/favicon"
+];
+var OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK = "/* OpenAPI docs runtime asset missing: tailwind disabled */";
+function buildOpenAPIAssetCandidatePaths(bases, filename) {
+  return bases.map((base) => `${base}/${filename}`);
+}
+function resolveOpenAPIAssetFile(relativeCandidates, cwdCandidates) {
+  for (const relativePath of relativeCandidates) {
+    try {
+      const fileUrl = new URL(relativePath, import.meta.url);
+      if (existsSync3(fileUrl)) {
+        return Bun.file(fileUrl);
       }
+    } catch {}
+  }
+  const cwd = process.cwd();
+  for (const relativePath of cwdCandidates) {
+    const absolutePath = join2(cwd, relativePath);
+    if (existsSync3(absolutePath)) {
+      return Bun.file(absolutePath);
     }
-    return APIError.notFound("Route not found");
   }
-  clearRoutes() {
-    this.routes = [];
-    this.specificityCache.clear();
+  return null;
+}
+var OPENAPI_TAILWIND_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES, OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES);
+var OPENAPI_LOGO_DARK_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_LOGO_DARK_ASSET_RELATIVE_CANDIDATES, OPENAPI_LOGO_DARK_ASSET_CWD_CANDIDATES);
+var OPENAPI_LOGO_WHITE_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_LOGO_WHITE_ASSET_RELATIVE_CANDIDATES, OPENAPI_LOGO_WHITE_ASSET_CWD_CANDIDATES);
+var OPENAPI_APPLE_TOUCH_ICON_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "apple-touch-icon.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "apple-touch-icon.png"));
+var OPENAPI_FAVICON_32_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon-32x32.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon-32x32.png"));
+var OPENAPI_FAVICON_16_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon-16x16.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon-16x16.png"));
+var OPENAPI_FAVICON_ICO_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon.ico"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon.ico"));
+var OPENAPI_WEBMANIFEST_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "site.webmanifest"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "site.webmanifest"));
+var OPENAPI_ANDROID_192_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "android-chrome-192x192.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "android-chrome-192x192.png"));
+var OPENAPI_ANDROID_512_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "android-chrome-512x512.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "android-chrome-512x512.png"));
+var OPENAPI_FAVICON_ASSETS = [
+  {
+    path: OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH,
+    file: OPENAPI_APPLE_TOUCH_ICON_ASSET_FILE,
+    contentType: "image/png",
+    filename: "apple-touch-icon.png"
+  },
+  {
+    path: OPENAPI_FAVICON_32_ASSET_PATH,
+    file: OPENAPI_FAVICON_32_ASSET_FILE,
+    contentType: "image/png",
+    filename: "favicon-32x32.png"
+  },
+  {
+    path: OPENAPI_FAVICON_16_ASSET_PATH,
+    file: OPENAPI_FAVICON_16_ASSET_FILE,
+    contentType: "image/png",
+    filename: "favicon-16x16.png"
+  },
+  {
+    path: OPENAPI_FAVICON_ICO_ASSET_PATH,
+    file: OPENAPI_FAVICON_ICO_ASSET_FILE,
+    contentType: "image/x-icon",
+    filename: "favicon.ico"
+  },
+  {
+    path: OPENAPI_WEBMANIFEST_ASSET_PATH,
+    file: OPENAPI_WEBMANIFEST_ASSET_FILE,
+    contentType: "application/manifest+json; charset=utf-8",
+    filename: "site.webmanifest"
+  },
+  {
+    path: OPENAPI_ANDROID_192_ASSET_PATH,
+    file: OPENAPI_ANDROID_192_ASSET_FILE,
+    contentType: "image/png",
+    filename: "android-chrome-192x192.png"
+  },
+  {
+    path: OPENAPI_ANDROID_512_ASSET_PATH,
+    file: OPENAPI_ANDROID_512_ASSET_FILE,
+    contentType: "image/png",
+    filename: "android-chrome-512x512.png"
+  }
+];
+var DOCS_HTML_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+var DOCS_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
+var DOCS_ASSET_ERROR_CACHE_CONTROL = "no-store";
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function wildcardPatternToRegex(pattern) {
+  let regexSource = "^";
+  for (const char of pattern) {
+    if (char === "*") {
+      regexSource += ".*";
+      continue;
+    }
+    regexSource += escapeRegex(char);
+  }
+  regexSource += "$";
+  return new RegExp(regexSource);
+}
+function matchesExposePath(path, exposePathPattern) {
+  if (!exposePathPattern.includes("*")) {
+    return path === exposePathPattern;
   }
+  return wildcardPatternToRegex(exposePathPattern).test(path);
 }
 
-// src/core/server.ts
 class VectorServer {
   server = null;
   router;
   config;
-  corsHandler;
-  corsHeaders = null;
+  openapiConfig;
+  openapiDocCache = null;
+  openapiDocsHtmlCache = null;
+  openapiWarningsLogged = false;
+  openapiTailwindMissingLogged = false;
+  openapiLogoDarkMissingLogged = false;
+  openapiLogoWhiteMissingLogged = false;
+  corsHandler = null;
+  corsHeadersEntries = null;
   constructor(router, config) {
     this.router = router;
     this.config = config;
+    this.openapiConfig = this.normalizeOpenAPIConfig(config.openapi, config.development);
     if (config.cors) {
       const opts = this.normalizeCorsOptions(config.cors);
-      const { preflight: preflight2, corsify: corsify2 } = y(opts);
-      this.corsHandler = { preflight: preflight2, corsify: corsify2 };
-      if (typeof opts.origin === "string") {
-        this.corsHeaders = {
+      const { preflight, corsify } = cors(opts);
+      this.corsHandler = { preflight, corsify };
+      const canUseStaticCorsHeaders = typeof opts.origin === "string" && (opts.origin !== "*" || !opts.credentials);
+      if (canUseStaticCorsHeaders) {
+        const corsHeaders = {
           "access-control-allow-origin": opts.origin,
           "access-control-allow-methods": opts.allowMethods,
           "access-control-allow-headers": opts.allowHeaders,
@@ -920,10 +3476,252 @@ class VectorServer {
           "access-control-max-age": String(opts.maxAge)
         };
         if (opts.credentials) {
-          this.corsHeaders["access-control-allow-credentials"] = "true";
+          corsHeaders["access-control-allow-credentials"] = "true";
+        }
+        this.corsHeadersEntries = Object.entries(corsHeaders);
+      }
+      this.router.setCorsHeaders(this.corsHeadersEntries);
+      this.router.setCorsHandler(this.corsHeadersEntries ? null : this.corsHandler.corsify);
+    }
+  }
+  normalizeOpenAPIConfig(openapi, development) {
+    const isDev = development !== false && true;
+    const defaultEnabled = isDev;
+    if (openapi === false) {
+      return {
+        enabled: false,
+        path: "/openapi.json",
+        target: "openapi-3.0",
+        docs: { enabled: false, path: "/docs" }
+      };
+    }
+    if (openapi === true) {
+      return {
+        enabled: true,
+        path: "/openapi.json",
+        target: "openapi-3.0",
+        docs: { enabled: false, path: "/docs" }
+      };
+    }
+    const openapiObject = openapi || {};
+    const docsValue = openapiObject.docs;
+    const docs = typeof docsValue === "boolean" ? { enabled: docsValue, path: "/docs", exposePaths: undefined } : {
+      enabled: docsValue?.enabled === true,
+      path: docsValue?.path || "/docs",
+      exposePaths: Array.isArray(docsValue?.exposePaths) ? docsValue.exposePaths.map((path) => typeof path === "string" ? path.trim() : "").filter((path) => path.length > 0) : undefined
+    };
+    return {
+      enabled: openapiObject.enabled ?? defaultEnabled,
+      path: openapiObject.path || "/openapi.json",
+      target: openapiObject.target || "openapi-3.0",
+      docs,
+      info: openapiObject.info
+    };
+  }
+  isDocsReservedPath(path) {
+    return path === this.openapiConfig.path || this.openapiConfig.docs.enabled && path === this.openapiConfig.docs.path;
+  }
+  getOpenAPIDocument() {
+    if (this.openapiDocCache) {
+      return this.openapiDocCache;
+    }
+    const routes = this.router.getRouteDefinitions().filter((route) => !this.isDocsReservedPath(route.path));
+    const result = generateOpenAPIDocument(routes, {
+      target: this.openapiConfig.target,
+      info: this.openapiConfig.info
+    });
+    if (!this.openapiWarningsLogged && result.warnings.length > 0) {
+      for (const warning of result.warnings) {
+        console.warn(warning);
+      }
+      this.openapiWarningsLogged = true;
+    }
+    this.openapiDocCache = result.document;
+    return this.openapiDocCache;
+  }
+  getOpenAPIDocumentForDocs() {
+    const exposePaths = this.openapiConfig.docs.exposePaths;
+    const document = this.getOpenAPIDocument();
+    if (!Array.isArray(exposePaths) || exposePaths.length === 0) {
+      return document;
+    }
+    const existingPaths = document.paths && typeof document.paths === "object" && !Array.isArray(document.paths) ? document.paths : {};
+    const filteredPaths = {};
+    for (const [path, value] of Object.entries(existingPaths)) {
+      if (exposePaths.some((pattern) => matchesExposePath(path, pattern))) {
+        filteredPaths[path] = value;
+      }
+    }
+    return {
+      ...document,
+      paths: filteredPaths
+    };
+  }
+  getOpenAPIDocsHtmlCacheEntry() {
+    if (this.openapiDocsHtmlCache) {
+      return this.openapiDocsHtmlCache;
+    }
+    const html = renderOpenAPIDocsHtml(this.getOpenAPIDocumentForDocs(), this.openapiConfig.path, OPENAPI_TAILWIND_ASSET_PATH, OPENAPI_LOGO_DARK_ASSET_PATH, OPENAPI_LOGO_WHITE_ASSET_PATH, OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH, OPENAPI_FAVICON_32_ASSET_PATH, OPENAPI_FAVICON_16_ASSET_PATH, OPENAPI_WEBMANIFEST_ASSET_PATH);
+    const gzip = Bun.gzipSync(html);
+    const etag = `"${Bun.hash(html).toString(16)}"`;
+    this.openapiDocsHtmlCache = { html, gzip, etag };
+    return this.openapiDocsHtmlCache;
+  }
+  requestAcceptsGzip(request) {
+    const acceptEncoding = request.headers.get("accept-encoding");
+    return Boolean(acceptEncoding && /\bgzip\b/i.test(acceptEncoding));
+  }
+  validateReservedOpenAPIPaths() {
+    if (!this.openapiConfig.enabled) {
+      return;
+    }
+    const reserved = new Set([this.openapiConfig.path]);
+    if (this.openapiConfig.docs.enabled) {
+      reserved.add(this.openapiConfig.docs.path);
+      reserved.add(OPENAPI_TAILWIND_ASSET_PATH);
+      reserved.add(OPENAPI_LOGO_DARK_ASSET_PATH);
+      reserved.add(OPENAPI_LOGO_WHITE_ASSET_PATH);
+      for (const asset of OPENAPI_FAVICON_ASSETS) {
+        reserved.add(asset.path);
+      }
+    }
+    const methodConflicts = this.router.getRouteDefinitions().filter((route) => reserved.has(route.path)).map((route) => `${route.method} ${route.path}`);
+    const staticConflicts = Object.entries(this.router.getRouteTable()).filter(([path, value]) => reserved.has(path) && value instanceof Response).map(([path]) => `STATIC ${path}`);
+    const conflicts = [...methodConflicts, ...staticConflicts];
+    if (conflicts.length > 0) {
+      throw new Error(`OpenAPI reserved path conflict: ${conflicts.join(", ")}. Change your route path(s) or reconfigure openapi.path/docs.path.`);
+    }
+  }
+  tryHandleOpenAPIRequest(request) {
+    if (!this.openapiConfig.enabled || request.method !== "GET") {
+      return null;
+    }
+    const pathname = new URL(request.url).pathname;
+    if (pathname === this.openapiConfig.path) {
+      return Response.json(this.getOpenAPIDocument());
+    }
+    if (this.openapiConfig.docs.enabled && pathname === this.openapiConfig.docs.path) {
+      const { html, gzip, etag } = this.getOpenAPIDocsHtmlCacheEntry();
+      if (request.headers.get("if-none-match") === etag) {
+        return new Response(null, {
+          status: 304,
+          headers: {
+            etag,
+            "cache-control": DOCS_HTML_CACHE_CONTROL,
+            vary: "accept-encoding"
+          }
+        });
+      }
+      if (this.requestAcceptsGzip(request)) {
+        return new Response(gzip, {
+          status: 200,
+          headers: {
+            "content-type": "text/html; charset=utf-8",
+            "content-encoding": "gzip",
+            etag,
+            "cache-control": DOCS_HTML_CACHE_CONTROL,
+            vary: "accept-encoding"
+          }
+        });
+      }
+      return new Response(html, {
+        status: 200,
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          etag,
+          "cache-control": DOCS_HTML_CACHE_CONTROL,
+          vary: "accept-encoding"
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_TAILWIND_ASSET_PATH) {
+      if (!OPENAPI_TAILWIND_ASSET_FILE) {
+        if (!this.openapiTailwindMissingLogged) {
+          this.openapiTailwindMissingLogged = true;
+          console.warn('[OpenAPI] Missing docs runtime asset "tailwindcdn.js". Serving inline fallback script instead.');
+        }
+        return new Response(OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK, {
+          status: 200,
+          headers: {
+            "content-type": "application/javascript; charset=utf-8",
+            "cache-control": DOCS_ASSET_CACHE_CONTROL
+          }
+        });
+      }
+      return new Response(OPENAPI_TAILWIND_ASSET_FILE, {
+        status: 200,
+        headers: {
+          "content-type": "application/javascript; charset=utf-8",
+          "cache-control": DOCS_ASSET_CACHE_CONTROL
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_LOGO_DARK_ASSET_PATH) {
+      if (!OPENAPI_LOGO_DARK_ASSET_FILE) {
+        if (!this.openapiLogoDarkMissingLogged) {
+          this.openapiLogoDarkMissingLogged = true;
+          console.warn('[OpenAPI] Missing docs runtime asset "logo_dark.svg".');
+        }
+        return new Response("OpenAPI docs runtime asset missing: logo_dark.svg", {
+          status: 404,
+          headers: {
+            "content-type": "text/plain; charset=utf-8",
+            "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+          }
+        });
+      }
+      return new Response(OPENAPI_LOGO_DARK_ASSET_FILE, {
+        status: 200,
+        headers: {
+          "content-type": "image/svg+xml; charset=utf-8",
+          "cache-control": DOCS_ASSET_CACHE_CONTROL
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_LOGO_WHITE_ASSET_PATH) {
+      if (!OPENAPI_LOGO_WHITE_ASSET_FILE) {
+        if (!this.openapiLogoWhiteMissingLogged) {
+          this.openapiLogoWhiteMissingLogged = true;
+          console.warn('[OpenAPI] Missing docs runtime asset "logo_white.svg".');
+        }
+        return new Response("OpenAPI docs runtime asset missing: logo_white.svg", {
+          status: 404,
+          headers: {
+            "content-type": "text/plain; charset=utf-8",
+            "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+          }
+        });
+      }
+      return new Response(OPENAPI_LOGO_WHITE_ASSET_FILE, {
+        status: 200,
+        headers: {
+          "content-type": "image/svg+xml; charset=utf-8",
+          "cache-control": DOCS_ASSET_CACHE_CONTROL
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled) {
+      const faviconAsset = OPENAPI_FAVICON_ASSETS.find((asset) => asset.path === pathname);
+      if (faviconAsset) {
+        if (!faviconAsset.file) {
+          return new Response(`OpenAPI docs runtime asset missing: ${faviconAsset.filename}`, {
+            status: 404,
+            headers: {
+              "content-type": "text/plain; charset=utf-8",
+              "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+            }
+          });
         }
+        return new Response(faviconAsset.file, {
+          status: 200,
+          headers: {
+            "content-type": faviconAsset.contentType,
+            "cache-control": DOCS_ASSET_CACHE_CONTROL
+          }
+        });
       }
     }
+    return null;
   }
   normalizeCorsOptions(options) {
     return {
@@ -935,26 +3733,35 @@ class VectorServer {
       maxAge: options.maxAge || 86400
     };
   }
+  applyCors(response, request) {
+    if (this.corsHeadersEntries) {
+      for (const [k, v] of this.corsHeadersEntries) {
+        response.headers.set(k, v);
+      }
+      return response;
+    }
+    if (this.corsHandler && request) {
+      return this.corsHandler.corsify(response, request);
+    }
+    return response;
+  }
   async start() {
-    const port = this.config.port || 3000;
+    const port = this.config.port ?? 3000;
     const hostname = this.config.hostname || "localhost";
-    const fetch = async (request) => {
+    this.validateReservedOpenAPIPaths();
+    const fallbackFetch = async (request) => {
       try {
         if (this.corsHandler && request.method === "OPTIONS") {
           return this.corsHandler.preflight(request);
         }
-        let response = await this.router.handle(request);
-        if (this.corsHeaders) {
-          for (const [k, v] of Object.entries(this.corsHeaders)) {
-            response.headers.set(k, v);
-          }
-        } else if (this.corsHandler) {
-          response = this.corsHandler.corsify(response, request);
+        const openapiResponse = this.tryHandleOpenAPIRequest(request);
+        if (openapiResponse) {
+          return this.applyCors(openapiResponse, request);
         }
-        return response;
+        return this.applyCors(STATIC_RESPONSES.NOT_FOUND.clone(), request);
       } catch (error) {
         console.error("Server error:", error);
-        return new Response("Internal Server Error", { status: 500 });
+        return this.applyCors(new Response("Internal Server Error", { status: 500 }), request);
       }
     };
     try {
@@ -962,11 +3769,12 @@ class VectorServer {
         port,
         hostname,
         reusePort: this.config.reusePort !== false,
-        fetch,
-        idleTimeout: this.config.idleTimeout || 60,
-        error: (error) => {
+        routes: this.router.getRouteTable(),
+        fetch: fallbackFetch,
+        idleTimeout: this.config.idleTimeout ?? 60,
+        error: (error, request) => {
           console.error("[ERROR] Server error:", error);
-          return new Response("Internal Server Error", { status: 500 });
+          return this.applyCors(new Response("Internal Server Error", { status: 500 }), request);
         }
       });
       if (!this.server || !this.server.port) {
@@ -991,6 +3799,9 @@ class VectorServer {
     if (this.server) {
       this.server.stop();
       this.server = null;
+      this.openapiDocCache = null;
+      this.openapiDocsHtmlCache = null;
+      this.openapiWarningsLogged = false;
       console.log("Server stopped");
     }
   }
@@ -998,7 +3809,7 @@ class VectorServer {
     return this.server;
   }
   getPort() {
-    return this.server?.port || this.config.port || 3000;
+    return this.server?.port ?? this.config.port ?? 3000;
   }
   getHostname() {
     return this.server?.hostname || this.config.hostname || "localhost";
@@ -1023,6 +3834,7 @@ class Vector {
   routeGenerator = null;
   _protectedHandler = null;
   _cacheHandler = null;
+  shutdownPromise = null;
   constructor() {
     this.middlewareManager = new MiddlewareManager;
     this.authManager = new AuthManager;
@@ -1037,23 +3849,34 @@ class Vector {
   }
   setProtectedHandler(handler) {
     this._protectedHandler = handler;
-    this.authManager.setProtectedHandler(handler);
+    if (handler) {
+      this.authManager.setProtectedHandler(handler);
+      return;
+    }
+    this.authManager.clearProtectedHandler();
   }
   getProtectedHandler() {
     return this._protectedHandler;
   }
   setCacheHandler(handler) {
     this._cacheHandler = handler;
-    this.cacheManager.setCacheHandler(handler);
+    if (handler) {
+      this.cacheManager.setCacheHandler(handler);
+      return;
+    }
+    this.cacheManager.clearCacheHandler();
   }
   getCacheHandler() {
     return this._cacheHandler;
   }
   addRoute(options, handler) {
-    return this.router.route(options, handler);
+    this.router.route(options, handler);
   }
   async startServer(config) {
     this.config = { ...this.config, ...config };
+    const routeDefaults = { ...this.config.defaults?.route };
+    this.router.setRouteBooleanDefaults(routeDefaults);
+    this.router.setDevelopmentMode(this.config.development);
     this.middlewareManager.clear();
     if (this.config.autoDiscover !== false) {
       this.router.clearRoutes();
@@ -1064,6 +3887,9 @@ class Vector {
     if (config?.finally) {
       this.middlewareManager.addFinally(...config.finally);
     }
+    if (typeof this.config.startup === "function") {
+      await this.config.startup();
+    }
     if (this.config.autoDiscover !== false) {
       await this.discoverRoutes();
     }
@@ -1091,9 +3917,8 @@ class Vector {
             const exported = route.name === "default" ? module.default : module[route.name];
             if (exported) {
               if (this.isRouteDefinition(exported)) {
-                const routeDef = exported;
-                this.router.route(routeDef.options, routeDef.handler);
-                this.logRouteLoaded(routeDef.options);
+                this.router.route(exported.options, exported.handler);
+                this.logRouteLoaded(exported.options);
               } else if (this.isRouteEntry(exported)) {
                 this.router.addRoute(exported);
                 this.logRouteLoaded(exported);
@@ -1106,7 +3931,6 @@ class Vector {
             console.error(`Failed to load route ${route.name} from ${route.path}:`, error);
           }
         }
-        this.router.sortRoutes();
       }
     } catch (error) {
       if (error.code !== "ENOENT" && error.code !== "ENOTDIR") {
@@ -1117,14 +3941,14 @@ class Vector {
   async loadRoute(routeModule) {
     if (typeof routeModule === "function") {
       const routeEntry = routeModule();
-      if (Array.isArray(routeEntry)) {
+      if (this.isRouteEntry(routeEntry)) {
         this.router.addRoute(routeEntry);
       }
     } else if (routeModule && typeof routeModule === "object") {
       for (const [, value] of Object.entries(routeModule)) {
         if (typeof value === "function") {
           const routeEntry = value();
-          if (Array.isArray(routeEntry)) {
+          if (this.isRouteEntry(routeEntry)) {
             this.router.addRoute(routeEntry);
           }
         }
@@ -1132,10 +3956,14 @@ class Vector {
     }
   }
   isRouteEntry(value) {
-    return Array.isArray(value) && value.length >= 3;
+    if (!Array.isArray(value) || value.length < 3) {
+      return false;
+    }
+    const [method, matcher, handlers, path] = value;
+    return typeof method === "string" && matcher instanceof RegExp && Array.isArray(handlers) && handlers.length > 0 && handlers.every((handler) => typeof handler === "function") && (path === undefined || typeof path === "string");
   }
   isRouteDefinition(value) {
-    return value && typeof value === "object" && "entry" in value && "options" in value && "handler" in value;
+    return value !== null && typeof value === "object" && "entry" in value && "options" in value && "handler" in value && typeof value.handler === "function";
   }
   logRouteLoaded(_) {}
   stop() {
@@ -1144,6 +3972,22 @@ class Vector {
       this.server = null;
     }
   }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      return this.shutdownPromise;
+    }
+    this.shutdownPromise = (async () => {
+      this.stop();
+      if (typeof this.config.shutdown === "function") {
+        await this.config.shutdown();
+      }
+    })();
+    try {
+      await this.shutdownPromise;
+    } finally {
+      this.shutdownPromise = null;
+    }
+  }
   getServer() {
     return this.server;
   }
@@ -1162,80 +4006,40 @@ class Vector {
 }
 var getVectorInstance = Vector.getInstance;
 
-// src/core/config-loader.ts
-import { existsSync as existsSync2 } from "fs";
-import { resolve as resolve2, isAbsolute } from "path";
-class ConfigLoader {
-  configPath;
-  config = null;
-  configSource = "default";
-  constructor(configPath) {
-    const path = configPath || "vector.config.ts";
-    this.configPath = isAbsolute(path) ? path : resolve2(process.cwd(), path);
-  }
-  async load() {
-    if (existsSync2(this.configPath)) {
-      try {
-        const userConfigPath = toFileUrl(this.configPath);
-        const userConfig = await import(userConfigPath);
-        this.config = userConfig.default || userConfig;
-        this.configSource = "user";
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        console.error(`[Vector] Failed to load config from ${this.configPath}: ${msg}`);
-        console.error("[Vector] Server is using default configuration. Fix your config file and restart.");
-        this.config = {};
-      }
-    } else {
-      this.config = {};
-    }
-    return await this.buildLegacyConfig();
-  }
-  getConfigSource() {
-    return this.configSource;
-  }
-  async buildLegacyConfig() {
-    const config = {};
-    if (this.config) {
-      config.port = this.config.port;
-      config.hostname = this.config.hostname;
-      config.reusePort = this.config.reusePort;
-      config.development = this.config.development;
-      config.routesDir = this.config.routesDir || "./routes";
-      config.idleTimeout = this.config.idleTimeout;
-    }
-    config.autoDiscover = true;
-    if (this.config?.cors) {
-      if (typeof this.config.cors === "boolean") {
-        config.cors = this.config.cors ? {
-          origin: "*",
-          credentials: true,
-          allowHeaders: "Content-Type, Authorization",
-          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-          exposeHeaders: "Authorization",
-          maxAge: 86400
-        } : undefined;
-      } else {
-        config.cors = this.config.cors;
-      }
-    }
-    if (this.config?.before) {
-      config.before = this.config.before;
-    }
-    if (this.config?.after) {
-      config.finally = this.config.after;
-    }
-    return config;
-  }
-  async loadAuthHandler() {
-    return this.config?.auth || null;
+// src/start-vector.ts
+async function startVector(options = {}) {
+  const configLoader = new ConfigLoader(options.configPath);
+  const loadedConfig = await configLoader.load();
+  const configSource = configLoader.getConfigSource();
+  let config = { ...loadedConfig };
+  if (options.mutateConfig) {
+    config = await options.mutateConfig(config, { configSource });
   }
-  async loadCacheHandler() {
-    return this.config?.cache || null;
+  if (options.config) {
+    config = { ...config, ...options.config };
   }
-  getConfig() {
-    return this.config;
+  if (options.autoDiscover !== undefined) {
+    config.autoDiscover = options.autoDiscover;
   }
+  const vector = getVectorInstance();
+  const resolvedProtectedHandler = options.protectedHandler !== undefined ? options.protectedHandler : await configLoader.loadAuthHandler();
+  const resolvedCacheHandler = options.cacheHandler !== undefined ? options.cacheHandler : await configLoader.loadCacheHandler();
+  vector.setProtectedHandler(resolvedProtectedHandler ?? null);
+  vector.setCacheHandler(resolvedCacheHandler ?? null);
+  const server = await vector.startServer(config);
+  const effectiveConfig = {
+    ...config,
+    port: server.port ?? config.port ?? DEFAULT_CONFIG.PORT,
+    hostname: server.hostname || config.hostname || DEFAULT_CONFIG.HOSTNAME,
+    reusePort: config.reusePort !== false,
+    idleTimeout: config.idleTimeout ?? 60
+  };
+  return {
+    server,
+    config: effectiveConfig,
+    stop: () => vector.stop(),
+    shutdown: () => vector.shutdown()
+  };
 }
 
 // src/cli/index.ts
@@ -1276,10 +4080,14 @@ var { values, positionals } = parseArgs({
   allowPositionals: true
 });
 var command = positionals[0] || "dev";
+var hasRoutesOption = args.some((arg) => arg === "--routes" || arg === "-r" || arg.startsWith("--routes="));
+var hasHostOption = args.some((arg) => arg === "--host" || arg === "-h" || arg.startsWith("--host="));
+var hasPortOption = args.some((arg) => arg === "--port" || arg === "-p" || arg.startsWith("--port="));
 async function runDev() {
   const isDev = command === "dev";
   let server = null;
-  let vector = null;
+  let app = null;
+  let removeShutdownHandlers = null;
   async function startServer() {
     const timeoutPromise = new Promise((_, reject) => {
       setTimeout(() => {
@@ -1287,33 +4095,31 @@ async function runDev() {
       }, 1e4);
     });
     const serverStartPromise = (async () => {
-      const configLoader = new ConfigLoader(values.config);
-      const config = await configLoader.load();
-      config.port = config.port ?? Number.parseInt(values.port);
-      config.hostname = config.hostname ?? values.host;
-      config.routesDir = config.routesDir ?? values.routes;
-      config.development = config.development ?? isDev;
-      config.autoDiscover = true;
-      if (config.cors === undefined && values.cors) {
-        config.cors = {
-          origin: "*",
-          credentials: true,
-          allowHeaders: "Content-Type, Authorization",
-          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-          exposeHeaders: "Authorization",
-          maxAge: 86400
-        };
-      }
-      vector = getVectorInstance();
-      const authHandler = await configLoader.loadAuthHandler();
-      if (authHandler) {
-        vector.setProtectedHandler(authHandler);
-      }
-      const cacheHandler = await configLoader.loadCacheHandler();
-      if (cacheHandler) {
-        vector.setCacheHandler(cacheHandler);
-      }
-      server = await vector.startServer(config);
+      const explicitConfigPath = values.config;
+      app = await startVector({
+        configPath: explicitConfigPath,
+        mutateConfig: (loadedConfig) => {
+          const config2 = { ...loadedConfig };
+          config2.port = resolvePort(config2.port, hasPortOption, values.port);
+          config2.hostname = resolveHost(config2.hostname, hasHostOption, values.host);
+          config2.routesDir = resolveRoutesDir(config2.routesDir, hasRoutesOption, values.routes);
+          config2.development = config2.development ?? isDev;
+          config2.autoDiscover = true;
+          if (config2.cors === undefined && values.cors) {
+            config2.cors = {
+              origin: "*",
+              credentials: true,
+              allowHeaders: "Content-Type, Authorization",
+              allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+              exposeHeaders: "Authorization",
+              maxAge: 86400
+            };
+          }
+          return config2;
+        }
+      });
+      server = app.server;
+      const config = app.config;
       if (!server || !server.port) {
         throw new Error("Server started but is not responding correctly");
       }
@@ -1322,13 +4128,18 @@ async function runDev() {
       console.log(`
 Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
 `);
-      return { server, vector, config };
+      return { server, app, config };
     })();
     return await Promise.race([serverStartPromise, timeoutPromise]);
   }
   try {
     const result = await startServer();
     server = result.server;
+    if (!removeShutdownHandlers) {
+      removeShutdownHandlers = installGracefulShutdownHandlers({
+        getTarget: () => app
+      });
+    }
     if (isDev && values.watch) {
       try {
         let reloadTimeout = null;
@@ -1352,14 +4163,14 @@ Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
               isReloading = true;
               lastReloadTime = Date.now();
               changedFiles.clear();
-              if (vector) {
-                vector.stop();
+              if (app) {
+                app.stop();
               }
               await new Promise((resolve3) => setTimeout(resolve3, 100));
               try {
                 const result2 = await startServer();
                 server = result2.server;
-                vector = result2.vector;
+                app = result2.app;
               } catch (error) {
                 console.error(`
 [Reload Error]`, error.message || error);
@@ -1387,62 +4198,15 @@ ${red}Error: ${error.message || error}${reset}
     process.exit(1);
   }
 }
-async function runBuild() {
-  try {
-    const { RouteScanner: RouteScanner2 } = await Promise.resolve().then(() => (init_route_scanner(), exports_route_scanner));
-    const { RouteGenerator: RouteGenerator2 } = await Promise.resolve().then(() => (init_route_generator(), exports_route_generator));
-    const scanner = new RouteScanner2(values.routes);
-    const generator = new RouteGenerator2;
-    const routes = await scanner.scan();
-    await generator.generate(routes);
-    if (typeof Bun !== "undefined") {
-      const buildProcess = Bun.spawn([
-        "bun",
-        "build",
-        "src/cli/index.ts",
-        "--target",
-        "bun",
-        "--outfile",
-        "dist/server.js",
-        "--minify"
-      ]);
-      const exitCode = await buildProcess.exited;
-      if (exitCode !== 0) {
-        throw new Error(`Build failed with exit code ${exitCode}`);
-      }
-    } else {
-      const { spawnSync } = await import("child_process");
-      const result = spawnSync("bun", ["build", "src/cli/index.ts", "--target", "bun", "--outfile", "dist/server.js", "--minify"], {
-        stdio: "inherit",
-        shell: true
-      });
-      if (result.status !== 0) {
-        throw new Error(`Build failed with exit code ${result.status}`);
-      }
-    }
-    console.log(`
-Build complete: dist/server.js
-`);
-  } catch (error) {
-    const red = "\x1B[31m";
-    const reset = "\x1B[0m";
-    console.error(`
-${red}Error: ${error.message || error}${reset}
-`);
-    process.exit(1);
-  }
-}
 switch (command) {
   case "dev":
     await runDev();
     break;
-  case "build":
-    await runBuild();
-    break;
-  case "start":
+  case "start": {
     process.env.NODE_ENV = "production";
     await runDev();
     break;
+  }
   default:
     console.error(`Unknown command: ${command}`);
     console.log(`
@@ -1450,15 +4214,14 @@ Usage: vector [command] [options]
 
 Commands:
   dev     Start development server (default)
-  build   Build for production
   start   Start production server
 
 Options:
   -p, --port <port>      Port to listen on (default: 3000)
   -h, --host <host>      Hostname to bind to (default: localhost)
-  -r, --routes <dir>     Routes directory (default: ./routes)
+  -r, --routes <dir>     Routes directory (dev/start)
   -w, --watch            Watch for file changes (default: true)
-  -c, --config <path>    Path to config file (default: vector.config.ts)
+  -c, --config <path>    Path to config file (dev/start)
   --cors                 Enable CORS (default: true)
 `);
     process.exit(1);