vector-framework 1.0.0 → 1.2.0

package/dist/cli.js

@@ -1,244 +1,5 @@
 #!/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";
-
-class RouteGenerator {
-  outputPath;
-  constructor(outputPath = "./.vector/routes.generated.ts") {
-    this.outputPath = outputPath;
-  }
-  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(`,
-`)}
-  ]);
-};`;
-  }
-}
-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 [];
-      }
-      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, "[^/]*").replace(/\*\*/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/cli/index.ts
 import { watch } from "fs";
@@ -345,12 +106,19 @@ 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/cache/manager.ts
 class CacheManager {
   cacheHandler = null;
   memoryCache = new Map;
   cleanupInterval = null;
+  inflight = new Map;
   setCacheHandler(handler) {
     this.cacheHandler = handler;
   }
@@ -369,9 +137,20 @@ class CacheManager {
     if (this.isCacheValid(cached, now)) {
       return cached.value;
     }
-    const value = await factory();
-    this.setInMemoryCache(key, value, ttl);
-    return value;
+    if (this.inflight.has(key)) {
+      return await this.inflight.get(key);
+    }
+    const promise = (async () => {
+      const value = await factory();
+      this.setInMemoryCache(key, value, ttl);
+      return value;
+    })();
+    this.inflight.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      this.inflight.delete(key);
+    }
   }
   isCacheValid(entry, now) {
     return entry !== undefined && entry.expires > now;
@@ -431,20 +210,212 @@ class CacheManager {
     return true;
   }
   generateKey(request, options) {
-    const url = new URL(request.url);
-    const parts = [
-      request.method,
-      url.pathname,
-      url.search,
-      options?.authUser?.id || "anonymous"
-    ];
-    return parts.join(":");
+    const url = request._parsedUrl ?? new URL(request.url);
+    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";
+
+class RouteGenerator {
+  outputPath;
+  constructor(outputPath = "./.vector/routes.generated.ts") {
+    this.outputPath = outputPath;
+  }
+  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, promises as fs2 } from "fs";
+import { join, relative as relative2, resolve, 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 = resolve(process.cwd(), routesDir);
+    this.excludePatterns = excludePatterns || RouteScanner.DEFAULT_EXCLUDE_PATTERNS;
+  }
+  async scan() {
+    const routes = [];
+    if (!existsSync(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 {
@@ -457,6 +428,8 @@ class MiddlewareManager {
     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);
@@ -468,6 +441,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 {
@@ -494,51 +469,21 @@ class MiddlewareManager {
 function toFileUrl(path) {
   return process.platform === "win32" ? `file:///${path.replace(/\\/g, "/")}` : path;
 }
-
-// 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 w = (e) => {
-  e.cookies = (e.headers.get("Cookie") || "").split(/;\s*/).map((e2) => e2.split(/=(.+)/)).reduce((e2, [t, r2]) => r2 ? (e2[t] = r2, e2) : e2, {});
-};
-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 });
-    }
-  } };
-};
+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.*)?")}/*$`);
+}
 
 // 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 stringifyData(data) {
-  return JSON.stringify(data ?? null, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+  const val = data ?? null;
+  try {
+    return JSON.stringify(val);
+  } 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 = {
@@ -602,248 +547,2481 @@ function createResponse(statusCode, data, contentType = CONTENT_TYPES.JSON) {
   });
 }
 
-// src/core/router.ts
-class VectorRouter {
-  middlewareManager;
-  authManager;
-  cacheManager;
-  routes = [];
-  constructor(middlewareManager, authManager, cacheManager) {
-    this.middlewareManager = middlewareManager;
-    this.authManager = authManager;
-    this.cacheManager = cacheManager;
-  }
-  getRouteSpecificity(path) {
-    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;
+// 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;
+  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;
+  }
+  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];
+      }
+    }
+    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
+    });
+  }
+  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
+      }
+    });
+  }
+  bulkAddRoutes(entries) {
+    for (const entry of entries) {
+      this.addRoute(entry);
+    }
+  }
+  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);
+  }
+  getRouteTable() {
+    return this.routeTable;
+  }
+  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;
+  }
+  getRouteDefinitions() {
+    return [...this.routeDefinitions];
+  }
+  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 = {};
+    }
+    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;
+    }
+    if (options?.metadata !== undefined) {
+      request.metadata = options.metadata;
+    }
+    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 {}
+      }
+    }
+    if (!Object.getOwnPropertyDescriptor(request, "cookies")) {
+      Object.defineProperty(request, "cookies", {
+        get() {
+          const cookieHeader = this.headers.get("cookie") ?? "";
+          const cookies = {};
+          if (cookieHeader) {
+            for (const pair of cookieHeader.split(";")) {
+              const idx = pair.indexOf("=");
+              if (idx > 0) {
+                cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+              }
+            }
+          }
+          Object.defineProperty(this, "cookies", {
+            value: cookies,
+            writable: true,
+            configurable: true,
+            enumerable: true
+          });
+          return cookies;
+        },
+        configurable: true,
+        enumerable: true
+      });
+    }
+  }
+  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
+      });
+      try {
+        if (options.expose === false) {
+          return APIError.forbidden("Forbidden");
+        }
+        const beforeResult = await this.middlewareManager.executeBefore(vectorRequest);
+        if (beforeResult instanceof Response) {
+          return beforeResult;
+        }
+        const req = beforeResult;
+        if (options.auth) {
+          try {
+            await this.authManager.authenticate(req);
+          } catch (error) {
+            return APIError.unauthorized(error instanceof Error ? error.message : "Authentication failed", options.responseContentType);
+          }
+        }
+        if (!options.rawRequest && req.method !== "GET" && req.method !== "HEAD") {
+          let parsedContent = null;
+          try {
+            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 {
+              parsedContent = await req.text();
+            }
+          } catch {
+            parsedContent = null;
+          }
+          this.setContentAndBodyAlias(req, parsedContent);
+        }
+        const inputValidationResponse = await this.validateInputSchema(req, options);
+        if (inputValidationResponse) {
+          return inputValidationResponse;
+        }
+        let result;
+        const cacheOptions = options.cache;
+        if (cacheOptions && typeof cacheOptions === "number" && cacheOptions > 0) {
+          const cacheKey = this.cacheManager.generateKey(req, {
+            authUser: req.authUser
+          });
+          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(req, {
+            authUser: req.authUser
+          });
+          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(req);
+        }
+        if (result && typeof result === "object" && result._isResponse === true) {
+          result = new Response(result.body, {
+            status: result.status,
+            headers: result.headers
+          });
+        }
+        let response;
+        if (options.rawResponse || result instanceof Response) {
+          response = result instanceof Response ? result : new Response(result);
+        } else {
+          response = createResponse(200, result, options.responseContentType);
+        }
+        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) {
+          return error;
+        }
+        console.error("Route handler error:", error);
+        return APIError.internalServerError(error instanceof Error ? error.message : String(error), options.responseContentType);
+      }
+    };
+  }
+  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 existsSync2 } 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) {
+  const specJson = JSON.stringify(spec).replace(/<\/script/gi, "<\\/script");
+  const openapiPathJson = JSON.stringify(openapiPath);
+  const tailwindScriptPathJson = JSON.stringify(tailwindScriptPath);
+  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>
+  <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: '#6366F1',
+            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); }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      *, *::before, *::after {
+        animation: none !important;
+        transition: none !important;
+      }
+    }
+    .json-key { color: #0f766e; }
+    .json-string { color: #0369a1; }
+    .json-number { color: #7c3aed; }
+    .json-boolean { color: #b45309; }
+    .json-null { color: #be123c; }
+    .dark .json-key { color: #5eead4; }
+    .dark .json-string { color: #7dd3fc; }
+    .dark .json-number { color: #c4b5fd; }
+    .dark .json-boolean { color: #fcd34d; }
+    .dark .json-null { color: #fda4af; }
+  </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">
+      <svg class="w-5 h-5 text-brand" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <polygon points="3 21 12 2 21 21 12 15 3 21"></polygon>
+      </svg>
+      <span class="ml-2.5 font-bold tracking-tight text-lg">Vector</span>
+      <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>
+        <svg class="w-5 h-5 text-brand" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="3 21 12 2 21 21 12 15 3 21"></polygon></svg>
+        <span class="font-bold tracking-tight">Vector</span>
+      </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-[#1F1F1F] bg-light-bg dark:bg-[#111111] overflow-hidden group">
+                <div class="flex items-center justify-between px-4 py-2 border-b border-light-border dark:border-[#1F1F1F] bg-light-surface dark:bg-[#0A0A0A]">
+                   <span class="text-xs font-mono text-light-text/70 dark:text-[#EDEDED]/70">cURL</span>
+                   <button class="text-xs text-light-text/50 hover:text-light-text dark:text-[#EDEDED]/50 dark:hover:text-[#EDEDED] transition-colors" id="copy-curl">Copy</button>
+                </div>
+                <pre class="p-4 text-sm font-mono text-light-text dark:text-[#EDEDED] 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-teal-600 text-white text-sm font-semibold rounded hover:bg-teal-500 transition-colors">Submit</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>
+                    <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-teal-600 text-white font-semibold hover:bg-teal-500 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 methodBadge = {
+      GET: "bg-green-100 text-green-700 dark:bg-green-500/10 dark:text-green-400",
+      POST: "bg-blue-100 text-blue-700 dark:bg-blue-500/10 dark:text-blue-400",
+      PUT: "bg-amber-100 text-amber-700 dark:bg-amber-500/10 dark:text-amber-400",
+      PATCH: "bg-amber-100 text-amber-700 dark:bg-amber-500/10 dark:text-amber-400",
+      DELETE: "bg-red-100 text-red-700 dark:bg-red-500/10 dark:text-red-400",
+    };
+
+    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()) {
+        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-black/5 dark:bg-white/5 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] || "bg-zinc-100 text-zinc-700 dark:bg-zinc-500/10 dark:text-zinc-400");
+          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 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 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] || "bg-zinc-100 text-zinc-700 dark:bg-zinc-500/10 dark:text-zinc-400");
+      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);
+      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";
+      }
+
+      try {
+        const response = await fetch(requestPath, { method: selected.method, headers, body: body || undefined });
+        const text = await response.text();
+        const contentType = response.headers.get("content-type") || "unknown";
+        const formattedResponse = formatResponseText(text);
+        const headerText =
+          "Status: " + response.status + " " + response.statusText + "\\n" +
+          "Content-Type: " + contentType + "\\n\\n";
+        setResponseContent(
+          headerText,
+          formattedResponse.text,
+          formattedResponse.isJson,
+        );
+      } catch (error) {
+        setResponseContent("", "Request failed: " + String(error), 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]}}`;
     }
-    score += path.length;
-    if (this.isExactPath(path)) {
-      score += EXACT_MATCH_BONUS;
+    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 score;
-  }
-  isStaticSegment(segment) {
-    return !segment.startsWith(":") && !segment.includes("*");
-  }
-  isParamSegment(segment) {
-    return segment.startsWith(":");
   }
-  isWildcardSegment(segment) {
-    return segment.includes("*");
+  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" }
+    });
   }
-  isExactPath(path) {
-    return !path.includes(":") && !path.includes("*");
+}
+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;
   }
-  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;
-    });
+  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)}`);
+    return null;
   }
-  extractPath(route) {
-    const PATH_INDEX = 3;
-    return route[PATH_INDEX] || "";
+}
+function convertOutputSchema(routePath, statusCode, outputSchema, target, warnings) {
+  if (!isJSONSchemaCapable(outputSchema)) {
+    return null;
   }
-  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 RegExp(`^${path.replace(/\/+(\/|$)/g, "$1").replace(/(\/?\.?):(\w+)\+/g, "($1(?<$2>*))").replace(/(\/?\.?):(\w+)/g, "($1(?<$2>[^$1/]+?))").replace(/\./g, "\\.").replace(/(\/?)\*/g, "($1.*)?")}/*$`);
+  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)}`);
+    return null;
   }
-  prepareRequest(request, options) {
-    if (!request.context) {
-      request.context = {};
-    }
-    if (options?.params !== undefined) {
-      request.params = options.params;
-    }
-    if (options?.route !== undefined) {
-      request.route = options.route;
-    }
-    if (options?.metadata !== undefined) {
-      request.metadata = options.metadata;
-    }
-    if (!request.query && request.url) {
-      const url = 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;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function addStructuredInputToOperation(operation, inputJSONSchema) {
+  if (!isRecord(inputJSONSchema))
+    return;
+  if (inputJSONSchema.type !== "object" || !isRecord(inputJSONSchema.properties)) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        "application/json": {
+          schema: inputJSONSchema
         }
       }
-      request.query = query;
-    }
-    if (!request.cookies) {
-      w(request);
+    };
+    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 : {}
+      });
     }
   }
-  wrapHandler(options, handler) {
-    return async (request) => {
-      const vectorRequest = request;
-      this.prepareRequest(vectorRequest, {
-        metadata: options.metadata
-      });
-      request = vectorRequest;
-      try {
-        if (options.expose === false) {
-          return APIError.forbidden("Forbidden");
-        }
-        const beforeResult = await this.middlewareManager.executeBefore(request);
-        if (beforeResult instanceof Response) {
-          return beforeResult;
+  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 : {}
         }
-        request = beforeResult;
-        if (options.auth) {
-          try {
-            await this.authManager.authenticate(request);
-          } catch (error) {
-            return APIError.unauthorized(error instanceof Error ? error.message : "Authentication failed", options.responseContentType);
+      }
+    };
+  }
+}
+function addOutputSchemasToOperation(operation, routePath, routeSchema, target, warnings) {
+  const output = routeSchema.output;
+  if (!output) {
+    operation.responses = {
+      200: { description: "OK" }
+    };
+    return;
+  }
+  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
           }
         }
-        if (!options.rawRequest && request.method !== "GET" && request.method !== "HEAD") {
-          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();
-            } else {
-              request.content = await request.text();
+      };
+    } 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
             }
-          } catch {
-            request.content = null;
-          }
-        }
-        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
-          });
-          result = await this.cacheManager.get(cacheKey, cacheFactory, cacheOptions);
-        } else if (cacheOptions && typeof cacheOptions === "object" && cacheOptions.ttl) {
-          const cacheKey = cacheOptions.key || this.cacheManager.generateKey(request, {
-            authUser: request.authUser
-          });
-          result = await this.cacheManager.get(cacheKey, cacheFactory, cacheOptions.ttl);
-        } else {
-          result = await handler(request);
-        }
-        if (result && typeof result === "object" && result._isResponse === true) {
-          result = new Response(result.body, {
-            status: result.status,
-            headers: result.headers
-          });
-        }
-        let response;
-        if (options.rawResponse || result instanceof Response) {
-          response = result instanceof Response ? result : new Response(result);
-        } else {
-          response = createResponse(200, result, options.responseContentType);
-        }
-        response = await this.middlewareManager.executeFinally(response, request);
-        return response;
-      } catch (error) {
-        if (error instanceof Response) {
-          return error;
-        }
-        console.error("Route handler error:", error);
-        return APIError.internalServerError(error instanceof Error ? error.message : String(error), options.responseContentType);
+      } else {
+        responses[status] = {
+          description
+        };
       }
-    };
-  }
-  addRoute(routeEntry) {
-    this.routes.push(routeEntry);
-    this.sortRoutes();
+    }
   }
-  getRoutes() {
-    return this.routes;
+  if (Object.keys(responses).length === 0) {
+    responses["200"] = { description: "OK" };
   }
-  async handle(request) {
-    const url = new URL(request.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;
-          }
-        }
-      }
+  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);
     }
-    return APIError.notFound("Route not found");
+    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_TAILWIND_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/tailwindcdn.js",
+  "../src/openapi/assets/tailwindcdn.js",
+  "../../src/openapi/assets/tailwindcdn.js"
+];
+var OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/tailwindcdn.js",
+  "openapi/assets/tailwindcdn.js",
+  "dist/openapi/assets/tailwindcdn.js"
+];
+var OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK = "/* OpenAPI docs runtime asset missing: tailwind disabled */";
+function resolveOpenAPITailwindAssetFile() {
+  for (const relativePath of OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES) {
+    try {
+      const fileUrl = new URL(relativePath, import.meta.url);
+      if (existsSync2(fileUrl)) {
+        return Bun.file(fileUrl);
+      }
+    } catch {}
   }
-  clearRoutes() {
-    this.routes = [];
+  const cwd = process.cwd();
+  for (const relativePath of OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES) {
+    const absolutePath = join2(cwd, relativePath);
+    if (existsSync2(absolutePath)) {
+      return Bun.file(absolutePath);
+    }
   }
+  return null;
 }
+var OPENAPI_TAILWIND_ASSET_FILE = resolveOpenAPITailwindAssetFile();
+var DOCS_HTML_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+var DOCS_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
 
-// src/core/server.ts
 class VectorServer {
   server = null;
   router;
   config;
-  corsHandler;
+  openapiConfig;
+  openapiDocCache = null;
+  openapiDocsHtmlCache = null;
+  openapiWarningsLogged = false;
+  openapiTailwindMissingLogged = 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 { preflight: preflight2, corsify: corsify2 } = y(this.normalizeCorsOptions(config.cors));
-      this.corsHandler = { preflight: preflight2, corsify: corsify2 };
+      const opts = this.normalizeCorsOptions(config.cors);
+      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,
+          "access-control-expose-headers": opts.exposeHeaders,
+          "access-control-max-age": String(opts.maxAge)
+        };
+        if (opts.credentials) {
+          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" } : {
+      enabled: docsValue?.enabled === true,
+      path: docsValue?.path || "/docs"
+    };
+    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;
+  }
+  getOpenAPIDocsHtmlCacheEntry() {
+    if (this.openapiDocsHtmlCache) {
+      return this.openapiDocsHtmlCache;
+    }
+    const html = renderOpenAPIDocsHtml(this.getOpenAPIDocument(), this.openapiConfig.path, OPENAPI_TAILWIND_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);
+    }
+    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
+        }
+      });
     }
+    return null;
   }
   normalizeCorsOptions(options) {
     return {
@@ -855,22 +3033,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.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 {
@@ -878,11 +3069,12 @@ class VectorServer {
         port,
         hostname,
         reusePort: this.config.reusePort !== false,
-        fetch,
+        routes: this.router.getRouteTable(),
+        fetch: fallbackFetch,
         idleTimeout: this.config.idleTimeout || 60,
-        error: (error) => {
+        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) {
@@ -907,6 +3099,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");
     }
   }
@@ -914,7 +3109,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";
@@ -966,10 +3161,13 @@ class Vector {
     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();
@@ -1007,9 +3205,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);
@@ -1022,7 +3219,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") {
@@ -1033,14 +3229,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);
           }
         }
@@ -1048,10 +3244,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() {
@@ -1079,7 +3279,7 @@ class Vector {
 var getVectorInstance = Vector.getInstance;
 
 // src/core/config-loader.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { resolve as resolve2, isAbsolute } from "path";
 class ConfigLoader {
   configPath;
@@ -1090,16 +3290,16 @@ class ConfigLoader {
     this.configPath = isAbsolute(path) ? path : resolve2(process.cwd(), path);
   }
   async load() {
-    if (existsSync2(this.configPath)) {
+    if (existsSync3(this.configPath)) {
       try {
         const userConfigPath = toFileUrl(this.configPath);
         const userConfig = await import(userConfigPath);
         this.config = userConfig.default || userConfig;
         this.configSource = "user";
       } catch (error) {
-        const red = "\x1B[31m";
-        const reset = "\x1B[0m";
-        console.error(`${red}Error loading config: ${error.message || error}${reset}`);
+        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 {
@@ -1119,6 +3319,8 @@ class ConfigLoader {
       config.development = this.config.development;
       config.routesDir = this.config.routesDir || "./routes";
       config.idleTimeout = this.config.idleTimeout;
+      config.defaults = this.config.defaults;
+      config.openapi = this.config.openapi;
     }
     config.autoDiscover = true;
     if (this.config?.cors) {
@@ -1154,6 +3356,35 @@ class ConfigLoader {
   }
 }
 
+// src/cli/option-resolution.ts
+function resolveRoutesDir(configRoutesDir, hasRoutesOption, cliRoutes) {
+  if (hasRoutesOption) {
+    return cliRoutes;
+  }
+  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/index.ts
 var args = typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2);
 var { values, positionals } = parseArgs({
@@ -1192,6 +3423,9 @@ 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;
@@ -1203,11 +3437,13 @@ 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;
+      const explicitConfigPath = values.config;
+      const configLoader = new ConfigLoader(explicitConfigPath);
+      const loadedConfig = await configLoader.load();
+      const config = { ...loadedConfig };
+      config.port = resolvePort(config.port, hasPortOption, values.port);
+      config.hostname = resolveHost(config.hostname, hasHostOption, values.host);
+      config.routesDir = resolveRoutesDir(config.routesDir, hasRoutesOption, values.routes);
       config.development = config.development ?? isDev;
       config.autoDiscover = true;
       if (config.cors === undefined && values.cors) {
@@ -1255,7 +3491,9 @@ Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
           const now = Date.now();
           if (isReloading || now - lastReloadTime < 1000)
             return;
-          if (filename && (filename.endsWith(".ts") || filename.endsWith(".js") || filename.endsWith(".json")) && !filename.includes("node_modules") && !filename.includes(".git") && !filename.includes(".vector") && !filename.includes("dist") && !filename.includes("bun.lockb") && !filename.endsWith(".generated.ts")) {
+          const segments = filename ? filename.split(/[/\\]/) : [];
+          const excluded = segments.some((s) => ["node_modules", ".git", ".vector", "dist"].includes(s));
+          if (filename && (filename.endsWith(".ts") || filename.endsWith(".js") || filename.endsWith(".json")) && !excluded && !filename.includes("bun.lockb") && !filename.endsWith(".generated.ts")) {
             changedFiles.add(filename);
             if (reloadTimeout) {
               clearTimeout(reloadTimeout);
@@ -1270,13 +3508,6 @@ Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
                 vector.stop();
               }
               await new Promise((resolve3) => setTimeout(resolve3, 100));
-              if (__require.cache) {
-                for (const key in __require.cache) {
-                  if (!key.includes("node_modules")) {
-                    delete __require.cache[key];
-                  }
-                }
-              }
               try {
                 const result2 = await startServer();
                 server = result2.server;
@@ -1308,70 +3539,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(`
@@ -1379,15 +3555,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);