vector-framework 1.2.0 → 1.2.1

package/dist/cli.js

@@ -5,29 +5,164 @@
 import { watch } from "fs";
 import { parseArgs } from "util";
 
-// src/auth/protected.ts
-class AuthManager {
-  protectedHandler = null;
-  setProtectedHandler(handler) {
-    this.protectedHandler = handler;
+// src/cli/option-resolution.ts
+function resolveRoutesDir(configRoutesDir, hasRoutesOption, cliRoutes) {
+  if (hasRoutesOption) {
+    return cliRoutes;
   }
-  async authenticate(request) {
-    if (!this.protectedHandler) {
-      throw new Error("Protected handler not configured. Use vector.protected() to set authentication handler.");
+  return configRoutesDir ?? cliRoutes;
+}
+function parseAndValidatePort(value) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    throw new Error(`Invalid port value: ${String(value)}`);
+  }
+  return parsed;
+}
+function resolvePort(configPort, hasPortOption, cliPort) {
+  if (hasPortOption) {
+    return parseAndValidatePort(cliPort);
+  }
+  const resolved = configPort ?? cliPort;
+  return parseAndValidatePort(resolved);
+}
+function resolveHost(configHost, hasHostOption, cliHost) {
+  const resolved = hasHostOption ? cliHost : configHost ?? cliHost;
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new Error(`Invalid host value: ${String(resolved)}`);
+  }
+  return resolved;
+}
+
+// src/cli/graceful-shutdown.ts
+function installGracefulShutdownHandlers(options) {
+  const on = options.on ?? ((event, listener) => process.on(event, listener));
+  const off = options.off ?? ((event, listener) => process.off(event, listener));
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const logError = options.logError ?? console.error;
+  let shuttingDown = false;
+  const handleSignal = async (signal) => {
+    if (shuttingDown) {
+      return;
     }
+    shuttingDown = true;
     try {
-      const authUser = await this.protectedHandler(request);
-      request.authUser = authUser;
-      return authUser;
+      const target = options.getTarget();
+      if (target) {
+        if (typeof target.shutdown === "function") {
+          await target.shutdown();
+        } else if (typeof target.stop === "function") {
+          target.stop();
+        }
+      }
+      exit(0);
     } catch (error) {
-      throw new Error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+      logError(`[vector] Graceful shutdown failed after ${signal}:`, error);
+      exit(1);
+    }
+  };
+  const onSigint = () => {
+    handleSignal("SIGINT");
+  };
+  const onSigterm = () => {
+    handleSignal("SIGTERM");
+  };
+  on("SIGINT", onSigint);
+  on("SIGTERM", onSigterm);
+  return () => {
+    off("SIGINT", onSigint);
+    off("SIGTERM", onSigterm);
+  };
+}
+
+// src/core/config-loader.ts
+import { existsSync } from "fs";
+import { resolve, isAbsolute } from "path";
+
+// src/utils/path.ts
+function toFileUrl(path) {
+  return process.platform === "win32" ? `file:///${path.replace(/\\/g, "/")}` : path;
+}
+function buildRouteRegex(path) {
+  return RegExp(`^${path.replace(/\/+(\/|$)/g, "$1").replace(/(\/?\.?):(\w+)\+/g, "($1(?<$2>[\\s\\S]+))").replace(/(\/?\.?):(\w+)/g, "($1(?<$2>[^$1/]+?))").replace(/\./g, "\\.").replace(/(\/?)\*/g, "($1.*)?")}/*$`);
+}
+
+// src/core/config-loader.ts
+class ConfigLoader {
+  configPath;
+  config = null;
+  configSource = "default";
+  constructor(configPath) {
+    const path = configPath || "vector.config.ts";
+    this.configPath = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  }
+  async load() {
+    if (existsSync(this.configPath)) {
+      try {
+        const userConfigPath = toFileUrl(this.configPath);
+        const userConfig = await import(userConfigPath);
+        this.config = userConfig.default || userConfig;
+        this.configSource = "user";
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`[vector] Failed to load config from ${this.configPath}: ${msg}`);
+        console.error("[vector] Server is using default configuration. Fix your config file and restart.");
+        this.config = {};
+      }
+    } else {
+      this.config = {};
     }
+    return await this.buildLegacyConfig();
   }
-  isAuthenticated(request) {
-    return !!request.authUser;
+  getConfigSource() {
+    return this.configSource;
   }
-  getUser(request) {
-    return request.authUser || null;
+  async buildLegacyConfig() {
+    const config = {};
+    if (this.config) {
+      config.port = this.config.port;
+      config.hostname = this.config.hostname;
+      config.reusePort = this.config.reusePort;
+      config.development = this.config.development;
+      config.routesDir = this.config.routesDir || "./routes";
+      config.routeExcludePatterns = this.config.routeExcludePatterns;
+      config.idleTimeout = this.config.idleTimeout;
+      config.defaults = this.config.defaults;
+      config.openapi = this.config.openapi;
+      config.startup = this.config.startup;
+      config.shutdown = this.config.shutdown;
+    }
+    config.autoDiscover = true;
+    if (this.config?.cors) {
+      if (typeof this.config.cors === "boolean") {
+        config.cors = this.config.cors ? {
+          origin: "*",
+          credentials: true,
+          allowHeaders: "Content-Type, Authorization",
+          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+          exposeHeaders: "Authorization",
+          maxAge: 86400
+        } : undefined;
+      } else {
+        config.cors = this.config.cors;
+      }
+    }
+    if (this.config?.before) {
+      config.before = this.config.before;
+    }
+    if (this.config?.after) {
+      config.finally = this.config.after;
+    }
+    return config;
+  }
+  async loadAuthHandler() {
+    return this.config?.auth || null;
+  }
+  async loadCacheHandler() {
+    return this.config?.cache || null;
+  }
+  getConfig() {
+    return this.config;
   }
 }
 
@@ -113,6 +248,35 @@ var STATIC_RESPONSES = {
   })
 };
 
+// src/auth/protected.ts
+class AuthManager {
+  protectedHandler = null;
+  setProtectedHandler(handler) {
+    this.protectedHandler = handler;
+  }
+  clearProtectedHandler() {
+    this.protectedHandler = null;
+  }
+  async authenticate(request) {
+    if (!this.protectedHandler) {
+      throw new Error("Protected handler not configured. Use vector.protected() to set authentication handler.");
+    }
+    try {
+      const authUser = await this.protectedHandler(request);
+      request.authUser = authUser;
+      return authUser;
+    } catch (error) {
+      throw new Error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  isAuthenticated(request) {
+    return !!request.authUser;
+  }
+  getUser(request) {
+    return request.authUser || null;
+  }
+}
+
 // src/cache/manager.ts
 class CacheManager {
   cacheHandler = null;
@@ -122,6 +286,9 @@ class CacheManager {
   setCacheHandler(handler) {
     this.cacheHandler = handler;
   }
+  clearCacheHandler() {
+    this.cacheHandler = null;
+  }
   async get(key, factory, ttl = DEFAULT_CONFIG.CACHE_TTL) {
     if (ttl <= 0) {
       return factory();
@@ -294,8 +461,8 @@ ${routeEntries.join(`,
 }
 
 // src/dev/route-scanner.ts
-import { existsSync, promises as fs2 } from "fs";
-import { join, relative as relative2, resolve, sep } from "path";
+import { existsSync as existsSync2, promises as fs2 } from "fs";
+import { join, relative as relative2, resolve as resolve2, sep } from "path";
 
 class RouteScanner {
   routesDir;
@@ -317,12 +484,12 @@ class RouteScanner {
     "*.d.ts"
   ];
   constructor(routesDir = "./routes", excludePatterns) {
-    this.routesDir = resolve(process.cwd(), routesDir);
+    this.routesDir = resolve2(process.cwd(), routesDir);
     this.excludePatterns = excludePatterns || RouteScanner.DEFAULT_EXCLUDE_PATTERNS;
   }
   async scan() {
     const routes = [];
-    if (!existsSync(this.routesDir)) {
+    if (!existsSync2(this.routesDir)) {
       return [];
     }
     try {
@@ -465,14 +632,6 @@ class MiddlewareManager {
   }
 }
 
-// src/utils/path.ts
-function toFileUrl(path) {
-  return process.platform === "win32" ? `file:///${path.replace(/\\/g, "/")}` : path;
-}
-function buildRouteRegex(path) {
-  return RegExp(`^${path.replace(/\/+(\/|$)/g, "$1").replace(/(\/?\.?):(\w+)\+/g, "($1(?<$2>[\\s\\S]+))").replace(/(\/?\.?):(\w+)/g, "($1(?<$2>[^$1/]+?))").replace(/\./g, "\\.").replace(/(\/?)\*/g, "($1.*)?")}/*$`);
-}
-
 // src/http.ts
 function stringifyData(data) {
   const val = data ?? null;
@@ -1143,7 +1302,7 @@ class VectorRouter {
 }
 
 // src/core/server.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { join as join2 } from "path";
 
 // src/utils/cors.ts
@@ -1231,16 +1390,26 @@ function cors(config) {
 }
 
 // src/openapi/docs-ui.ts
-function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
+function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPath, logoWhitePath, appleTouchIconPath, favicon32Path, favicon16Path, webManifestPath) {
   const specJson = JSON.stringify(spec).replace(/<\/script/gi, "<\\/script");
   const openapiPathJson = JSON.stringify(openapiPath);
   const tailwindScriptPathJson = JSON.stringify(tailwindScriptPath);
+  const logoDarkPathJson = JSON.stringify(logoDarkPath);
+  const logoWhitePathJson = JSON.stringify(logoWhitePath);
+  const appleTouchIconPathJson = JSON.stringify(appleTouchIconPath);
+  const favicon32PathJson = JSON.stringify(favicon32Path);
+  const favicon16PathJson = JSON.stringify(favicon16Path);
+  const webManifestPathJson = JSON.stringify(webManifestPath);
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Vector API Documentation</title>
+  <link rel="apple-touch-icon" sizes="180x180" href=${appleTouchIconPathJson}>
+  <link rel="icon" type="image/png" sizes="32x32" href=${favicon32PathJson}>
+  <link rel="icon" type="image/png" sizes="16x16" href=${favicon16PathJson}>
+  <link rel="manifest" href=${webManifestPathJson}>
   <script>
     if (localStorage.getItem('theme') === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
       document.documentElement.classList.add('dark');
@@ -1256,7 +1425,12 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       theme: {
         extend: {
           colors: {
-            brand: '#6366F1',
+            brand: {
+              DEFAULT: '#00A1FF',
+              mint: '#00FF8F',
+              soft: '#E4F5FF',
+              deep: '#007BC5',
+            },
             dark: { bg: '#0A0A0A', surface: '#111111', border: '#1F1F1F', text: '#EDEDED' },
             light: { bg: '#FFFFFF', surface: '#F9F9F9', border: '#E5E5E5', text: '#111111' }
           },
@@ -1323,32 +1497,44 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       from { opacity: 0; transform: translateX(-6px); }
       to { opacity: 1; transform: translateX(0); }
     }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+    .button-spinner {
+      display: inline-block;
+      width: 0.875rem;
+      height: 0.875rem;
+      border: 2px solid currentColor;
+      border-right-color: transparent;
+      border-radius: 9999px;
+      animation: spin 700ms linear infinite;
+    }
     @media (prefers-reduced-motion: reduce) {
       *, *::before, *::after {
         animation: none !important;
         transition: none !important;
       }
     }
-    .json-key { color: #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; }
+    .json-key { color: #007bc5; }
+    .json-string { color: #334155; }
+    .json-number { color: #00a1ff; }
+    .json-boolean { color: #475569; }
+    .json-null { color: #64748b; }
+    .dark .json-key { color: #7dc9ff; }
+    .dark .json-string { color: #d1d9e6; }
+    .dark .json-number { color: #7dc9ff; }
+    .dark .json-boolean { color: #93a4bf; }
+    .dark .json-null { color: #7c8ba3; }
   </style>
 </head>
 <body class="bg-light-bg text-light-text dark:bg-dark-bg dark:text-dark-text font-sans antialiased flex h-screen overflow-hidden">
   <div id="mobile-backdrop" class="fixed inset-0 z-30 bg-black/40 opacity-0 pointer-events-none transition-opacity duration-300 md:hidden"></div>
   <aside id="docs-sidebar" class="fixed inset-y-0 left-0 z-40 w-72 md:w-64 border-r border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface flex flex-col flex-shrink-0 transition-transform duration-300 ease-out -translate-x-full md:translate-x-0 md:static md:z-auto transition-colors duration-150">
     <div class="h-14 flex items-center px-5 border-b border-light-border dark:border-dark-border">
-      <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>
+      <div class="flex items-center">
+        <img src=${logoDarkPathJson} alt="Vector" class="h-6 w-auto block dark:hidden" />
+        <img src=${logoWhitePathJson} alt="Vector" class="h-6 w-auto hidden dark:block" />
+      </div>
       <button id="sidebar-close" class="ml-auto p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 transition md:hidden" aria-label="Close Menu" title="Close Menu">
         <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
@@ -1379,8 +1565,8 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
             <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>
+        <img src=${logoDarkPathJson} alt="Vector" class="h-5 w-auto block dark:hidden" />
+        <img src=${logoWhitePathJson} alt="Vector" class="h-5 w-auto hidden dark:block" />
       </div>
       <div class="flex-1"></div>
       <button id="theme-toggle" class="p-2 rounded-md hover:bg-black/5 dark:hover:bg-white/5 transition-colors" aria-label="Toggle Dark Mode">
@@ -1405,17 +1591,22 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
           <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 class="rounded-lg border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-hidden group">
+                <div class="flex items-center justify-between px-4 py-2 border-b border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface">
+                   <span class="text-xs font-mono text-light-text/70 dark:text-dark-text/70">cURL</span>
+                   <button class="text-xs text-light-text/50 hover:text-light-text dark:text-dark-text/50 dark:hover:text-dark-text transition-colors" id="copy-curl">Copy</button>
                 </div>
-                <pre class="p-4 text-sm font-mono text-light-text dark:text-[#EDEDED] overflow-x-auto leading-relaxed"><code id="curl-code"></code></pre>
+                <pre class="p-4 text-sm font-mono text-light-text dark:text-dark-text overflow-x-auto leading-relaxed"><code id="curl-code"></code></pre>
               </div>
               <div class="mt-4 p-4 rounded-lg border border-light-border dark:border-dark-border bg-light-surface dark:bg-dark-surface">
                 <div class="flex items-center justify-between mb-3">
                   <h4 class="text-sm font-medium">Try it out</h4>
-                  <button id="send-btn" class="px-4 py-1.5 bg-teal-600 text-white text-sm font-semibold rounded hover:bg-teal-500 transition-colors">Submit</button>
+                  <button id="send-btn" class="px-4 py-1.5 bg-brand text-white text-sm font-semibold rounded hover:bg-brand-deep transition-colors">
+                    <span class="inline-flex items-center gap-2">
+                      <span id="send-btn-spinner" class="button-spinner hidden" aria-hidden="true"></span>
+                      <span id="send-btn-label">Submit</span>
+                    </span>
+                  </button>
                 </div>
                 <div class="space-y-4">
                   <div>
@@ -1449,7 +1640,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
                     </div>
                   </div>
 
-                  <div>
+                  <div id="response-section">
                     <div class="flex items-center justify-between mb-2">
                       <p class="text-xs font-semibold uppercase tracking-wider opacity-60">Response</p>
                     </div>
@@ -1476,7 +1667,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       <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-apply" class="hidden text-sm px-3 py-1.5 rounded bg-brand text-white font-semibold hover:bg-brand-deep transition-colors">Apply</button>
           <button id="expand-close" class="p-1.5 rounded-full border border-light-border dark:border-dark-border bg-light-bg/90 dark:bg-dark-bg/90 opacity-90 hover:opacity-100 hover:border-brand/60 transition-colors" aria-label="Close Modal" title="Close Modal">
             <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
               <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
@@ -1495,12 +1686,13 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
   <script>
     const spec = ${specJson};
     const openapiPath = ${openapiPathJson};
+    const methodBadgeDefault = "bg-black/5 text-light-text/80 dark:bg-white/10 dark:text-dark-text/80";
     const methodBadge = {
-      GET: "bg-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",
+      GET: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      POST: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      PUT: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      PATCH: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
+      DELETE: "bg-brand-soft text-brand-deep dark:bg-brand/20 dark:text-brand",
     };
 
     function getOperations() {
@@ -1754,6 +1946,16 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
         return;
       }
       for (const [tag, ops] of groups.entries()) {
+        ops.sort((a, b) => {
+          const byName = a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+          if (byName !== 0) return byName;
+
+          const byPath = a.path.localeCompare(b.path, undefined, { sensitivity: "base" });
+          if (byPath !== 0) return byPath;
+
+          return a.method.localeCompare(b.method, undefined, { sensitivity: "base" });
+        });
+
         const block = document.createElement("div");
         block.innerHTML = '<h3 class="px-2 mb-2 font-semibold text-xs uppercase tracking-wider opacity-50"></h3><ul class="space-y-0.5"></ul>';
         block.querySelector("h3").textContent = tag;
@@ -1765,14 +1967,14 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
           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 bg-brand-soft/70 dark:bg-brand/20 text-brand-deep dark:text-brand font-medium transition-colors"
             : "block px-2 py-1.5 rounded-md hover:bg-black/5 dark:hover:bg-white/5 transition-colors";
 
           const row = document.createElement("span");
           row.className = "flex items-center gap-2";
 
           const method = document.createElement("span");
-          method.className = "px-1.5 py-0.5 rounded text-[10px] font-mono font-semibold " + (methodBadge[op.method] || "bg-zinc-100 text-zinc-700 dark:bg-zinc-500/10 dark:text-zinc-400");
+          method.className = "px-1.5 py-0.5 rounded text-[10px] font-mono font-semibold " + (methodBadge[op.method] || methodBadgeDefault);
           method.textContent = op.method;
 
           const name = document.createElement("span");
@@ -1911,6 +2113,55 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       );
     }
 
+    function renderResponseSchemasSection(responses) {
+      if (!responses || typeof responses !== "object") return "";
+
+      const statusCodes = Object.keys(responses).sort((a, b) => {
+        const aNum = Number(a);
+        const bNum = Number(b);
+        if (Number.isInteger(aNum) && Number.isInteger(bNum)) return aNum - bNum;
+        if (Number.isInteger(aNum)) return -1;
+        if (Number.isInteger(bNum)) return 1;
+        return a.localeCompare(b);
+      });
+
+      let sections = "";
+      for (const statusCode of statusCodes) {
+        const responseDef = responses[statusCode];
+        if (!responseDef || typeof responseDef !== "object") continue;
+
+        const jsonSchema =
+          responseDef.content &&
+          responseDef.content["application/json"] &&
+          responseDef.content["application/json"].schema;
+
+        if (!jsonSchema || typeof jsonSchema !== "object") continue;
+
+        const rootChildren = buildSchemaChildren(jsonSchema);
+        if (!rootChildren.length) continue;
+
+        let rows = "";
+        for (const child of rootChildren) {
+          rows += renderSchemaFieldNode(child, 0);
+        }
+
+        sections +=
+          '<div class="mb-4"><h4 class="text-xs font-mono uppercase tracking-wider opacity-70 mb-2">Status ' +
+          escapeHtml(statusCode) +
+          "</h4>" +
+          rows +
+          "</div>";
+      }
+
+      if (!sections) return "";
+
+      return (
+        '<div><h3 class="text-sm font-semibold mb-3 flex items-center border-b border-light-border dark:border-dark-border pb-2">Response Schemas</h3>' +
+        sections +
+        "</div>"
+      );
+    }
+
     function renderTryItParameterInputs(pathParams, queryParams) {
       const container = document.getElementById("request-param-inputs");
       if (!container || !selected) return;
@@ -2194,6 +2445,19 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       }
     }
 
+    function setSubmitLoading(isLoading) {
+      const sendButton = document.getElementById("send-btn");
+      const spinner = document.getElementById("send-btn-spinner");
+      const label = document.getElementById("send-btn-label");
+      if (!sendButton) return;
+
+      sendButton.disabled = isLoading;
+      sendButton.classList.toggle("opacity-80", isLoading);
+      sendButton.classList.toggle("cursor-wait", isLoading);
+      if (spinner) spinner.classList.toggle("hidden", !isLoading);
+      if (label) label.textContent = isLoading ? "Sending..." : "Submit";
+    }
+
     function updateRequestPreview() {
       if (!selected) return;
 
@@ -2257,7 +2521,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       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");
+      methodNode.className = "px-2.5 py-0.5 rounded-full text-xs font-mono font-medium " + (methodBadge[selected.method] || methodBadgeDefault);
       document.getElementById("endpoint-title").textContent = selected.name;
       document.getElementById("endpoint-path").textContent = selected.path;
 
@@ -2270,6 +2534,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
       html += renderParamSection("Header Parameters", headers);
 
       html += renderRequestBodySchemaSection(reqSchema);
+      html += renderResponseSchemasSection(op.responses);
       document.getElementById("params-column").innerHTML = html || '<div class="text-sm opacity-70">No parameters</div>';
       renderTryItParameterInputs(path, query);
       renderHeaderInputs();
@@ -2320,14 +2585,18 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
         headers["Content-Type"] = "application/json";
       }
 
+      setSubmitLoading(true);
       try {
+        const requestStart = performance.now();
         const response = await fetch(requestPath, { method: selected.method, headers, body: body || undefined });
         const text = await response.text();
+        const responseTimeMs = Math.round(performance.now() - requestStart);
         const contentType = response.headers.get("content-type") || "unknown";
         const formattedResponse = formatResponseText(text);
         const headerText =
           "Status: " + response.status + " " + response.statusText + "\\n" +
-          "Content-Type: " + contentType + "\\n\\n";
+          "Content-Type: " + contentType + "\\n" +
+          "Response Time: " + responseTimeMs + " ms\\n\\n";
         setResponseContent(
           headerText,
           formattedResponse.text,
@@ -2335,6 +2604,8 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath) {
         );
       } catch (error) {
         setResponseContent("", "Request failed: " + String(error), false);
+      } finally {
+        setSubmitLoading(false);
       }
     });
 
@@ -2635,8 +2906,9 @@ function convertInputSchema(routePath, inputSchema, target, warnings) {
   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;
+    warnings.push(`[OpenAPI] Failed input schema conversion for ${routePath}: ${error instanceof Error ? error.message : String(error)}. Falling back to a permissive JSON Schema.`);
+    const fallback = buildFallbackJSONSchema(inputSchema);
+    return isEmptyObjectSchema(fallback) ? null : fallback;
   }
 }
 function convertOutputSchema(routePath, statusCode, outputSchema, target, warnings) {
@@ -2646,13 +2918,233 @@ function convertOutputSchema(routePath, statusCode, outputSchema, target, warnin
   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;
+    warnings.push(`[OpenAPI] Failed output schema conversion for ${routePath} (${statusCode}): ${error instanceof Error ? error.message : String(error)}. Falling back to a permissive JSON Schema.`);
+    return buildFallbackJSONSchema(outputSchema);
   }
 }
 function isRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function isEmptyObjectSchema(value) {
+  return isRecord(value) && Object.keys(value).length === 0;
+}
+function getValidatorSchemaDef(schema) {
+  if (!schema || typeof schema !== "object")
+    return null;
+  const value = schema;
+  if (isRecord(value._def))
+    return value._def;
+  if (isRecord(value._zod) && isRecord(value._zod.def)) {
+    return value._zod.def;
+  }
+  return null;
+}
+function getSchemaKind(def) {
+  if (!def)
+    return null;
+  const typeName = def.typeName;
+  if (typeof typeName === "string")
+    return typeName;
+  const type = def.type;
+  if (typeof type === "string")
+    return type;
+  return null;
+}
+function pickSchemaChild(def) {
+  const candidates = ["innerType", "schema", "type", "out", "in", "left", "right"];
+  for (const key of candidates) {
+    if (key in def)
+      return def[key];
+  }
+  return;
+}
+function pickSchemaObjectCandidate(def, keys) {
+  for (const key of keys) {
+    const value = def[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return value;
+    }
+  }
+  return;
+}
+function isOptionalWrapperKind(kind) {
+  if (!kind)
+    return false;
+  const lower = kind.toLowerCase();
+  return lower.includes("optional") || lower.includes("default") || lower.includes("catch");
+}
+function unwrapOptionalForRequired(schema) {
+  let current = schema;
+  let optional = false;
+  let guard = 0;
+  while (guard < 8) {
+    guard += 1;
+    const def = getValidatorSchemaDef(current);
+    const kind = getSchemaKind(def);
+    if (!def || !isOptionalWrapperKind(kind))
+      break;
+    optional = true;
+    const inner = pickSchemaChild(def);
+    if (!inner)
+      break;
+    current = inner;
+  }
+  return { schema: current, optional };
+}
+function getObjectShape(def) {
+  const rawShape = def.shape;
+  if (typeof rawShape === "function") {
+    try {
+      const resolved = rawShape();
+      return isRecord(resolved) ? resolved : {};
+    } catch {
+      return {};
+    }
+  }
+  return isRecord(rawShape) ? rawShape : {};
+}
+function mapPrimitiveKind(kind) {
+  const lower = kind.toLowerCase();
+  if (lower.includes("string"))
+    return { type: "string" };
+  if (lower.includes("number"))
+    return { type: "number" };
+  if (lower.includes("boolean"))
+    return { type: "boolean" };
+  if (lower.includes("bigint"))
+    return { type: "string" };
+  if (lower.includes("null"))
+    return { type: "null" };
+  if (lower.includes("any") || lower.includes("unknown") || lower.includes("never"))
+    return {};
+  if (lower.includes("date"))
+    return { type: "string", format: "date-time" };
+  if (lower.includes("custom"))
+    return { type: "object", additionalProperties: true };
+  return null;
+}
+function buildIntrospectedFallbackJSONSchema(schema, seen = new WeakSet) {
+  if (!schema || typeof schema !== "object")
+    return {};
+  if (seen.has(schema))
+    return {};
+  seen.add(schema);
+  const def = getValidatorSchemaDef(schema);
+  const kind = getSchemaKind(def);
+  if (!def || !kind)
+    return {};
+  const primitive = mapPrimitiveKind(kind);
+  if (primitive)
+    return primitive;
+  const lower = kind.toLowerCase();
+  if (lower.includes("object")) {
+    const shape = getObjectShape(def);
+    const properties = {};
+    const required = [];
+    for (const [key, child2] of Object.entries(shape)) {
+      const unwrapped = unwrapOptionalForRequired(child2);
+      properties[key] = buildIntrospectedFallbackJSONSchema(unwrapped.schema, seen);
+      if (!unwrapped.optional)
+        required.push(key);
+    }
+    const out = {
+      type: "object",
+      properties,
+      additionalProperties: true
+    };
+    if (required.length > 0) {
+      out.required = required;
+    }
+    return out;
+  }
+  if (lower.includes("array")) {
+    const itemSchema = pickSchemaObjectCandidate(def, ["element", "items", "innerType", "type"]) ?? {};
+    return {
+      type: "array",
+      items: buildIntrospectedFallbackJSONSchema(itemSchema, seen)
+    };
+  }
+  if (lower.includes("record")) {
+    const valueType = def.valueType ?? def.valueSchema;
+    return {
+      type: "object",
+      additionalProperties: valueType ? buildIntrospectedFallbackJSONSchema(valueType, seen) : true
+    };
+  }
+  if (lower.includes("tuple")) {
+    const items = Array.isArray(def.items) ? def.items : [];
+    const prefixItems = items.map((item) => buildIntrospectedFallbackJSONSchema(item, seen));
+    return {
+      type: "array",
+      prefixItems,
+      minItems: prefixItems.length,
+      maxItems: prefixItems.length
+    };
+  }
+  if (lower.includes("union")) {
+    const options = def.options ?? def.schemas ?? [];
+    if (!Array.isArray(options) || options.length === 0)
+      return {};
+    return {
+      anyOf: options.map((option) => buildIntrospectedFallbackJSONSchema(option, seen))
+    };
+  }
+  if (lower.includes("intersection")) {
+    const left = def.left;
+    const right = def.right;
+    if (!left || !right)
+      return {};
+    return {
+      allOf: [buildIntrospectedFallbackJSONSchema(left, seen), buildIntrospectedFallbackJSONSchema(right, seen)]
+    };
+  }
+  if (lower.includes("enum")) {
+    const values = def.values;
+    if (Array.isArray(values))
+      return { enum: values };
+    if (values && typeof values === "object")
+      return { enum: Object.values(values) };
+    return {};
+  }
+  if (lower.includes("literal")) {
+    const value = def.value;
+    if (value === undefined)
+      return {};
+    const valueType = value === null ? "null" : typeof value;
+    if (valueType === "string" || valueType === "number" || valueType === "boolean" || valueType === "null") {
+      return { type: valueType, const: value };
+    }
+    return { const: value };
+  }
+  if (lower.includes("nullable")) {
+    const inner = pickSchemaChild(def);
+    if (!inner)
+      return {};
+    return {
+      anyOf: [buildIntrospectedFallbackJSONSchema(inner, seen), { type: "null" }]
+    };
+  }
+  if (lower.includes("lazy")) {
+    const getter = def.getter;
+    if (typeof getter !== "function")
+      return {};
+    try {
+      return buildIntrospectedFallbackJSONSchema(getter(), seen);
+    } catch {
+      return {};
+    }
+  }
+  const child = pickSchemaChild(def);
+  if (child)
+    return buildIntrospectedFallbackJSONSchema(child, seen);
+  return {};
+}
+function buildFallbackJSONSchema(schema) {
+  const def = getValidatorSchemaDef(schema);
+  if (!def)
+    return {};
+  return buildIntrospectedFallbackJSONSchema(schema);
+}
 function addStructuredInputToOperation(operation, inputJSONSchema) {
   if (!isRecord(inputJSONSchema))
     return;
@@ -2803,38 +3295,155 @@ function generateOpenAPIDocument(routes, options) {
 
 // src/core/server.ts
 var OPENAPI_TAILWIND_ASSET_PATH = "/_vector/openapi/tailwindcdn.js";
+var OPENAPI_LOGO_DARK_ASSET_PATH = "/_vector/openapi/logo_dark.svg";
+var OPENAPI_LOGO_WHITE_ASSET_PATH = "/_vector/openapi/logo_white.svg";
+var OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH = "/_vector/openapi/favicon/apple-touch-icon.png";
+var OPENAPI_FAVICON_32_ASSET_PATH = "/_vector/openapi/favicon/favicon-32x32.png";
+var OPENAPI_FAVICON_16_ASSET_PATH = "/_vector/openapi/favicon/favicon-16x16.png";
+var OPENAPI_FAVICON_ICO_ASSET_PATH = "/_vector/openapi/favicon/favicon.ico";
+var OPENAPI_WEBMANIFEST_ASSET_PATH = "/_vector/openapi/favicon/site.webmanifest";
+var OPENAPI_ANDROID_192_ASSET_PATH = "/_vector/openapi/favicon/android-chrome-192x192.png";
+var OPENAPI_ANDROID_512_ASSET_PATH = "/_vector/openapi/favicon/android-chrome-512x512.png";
 var OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES = [
   "../openapi/assets/tailwindcdn.js",
   "../src/openapi/assets/tailwindcdn.js",
   "../../src/openapi/assets/tailwindcdn.js"
 ];
+var OPENAPI_LOGO_DARK_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/logo_dark.svg",
+  "../src/openapi/assets/logo_dark.svg",
+  "../../src/openapi/assets/logo_dark.svg"
+];
+var OPENAPI_LOGO_WHITE_ASSET_RELATIVE_CANDIDATES = [
+  "../openapi/assets/logo_white.svg",
+  "../src/openapi/assets/logo_white.svg",
+  "../../src/openapi/assets/logo_white.svg"
+];
 var OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES = [
   "src/openapi/assets/tailwindcdn.js",
   "openapi/assets/tailwindcdn.js",
   "dist/openapi/assets/tailwindcdn.js"
 ];
+var OPENAPI_LOGO_DARK_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/logo_dark.svg",
+  "openapi/assets/logo_dark.svg",
+  "dist/openapi/assets/logo_dark.svg"
+];
+var OPENAPI_LOGO_WHITE_ASSET_CWD_CANDIDATES = [
+  "src/openapi/assets/logo_white.svg",
+  "openapi/assets/logo_white.svg",
+  "dist/openapi/assets/logo_white.svg"
+];
+var OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES = [
+  "../openapi/assets/favicon",
+  "../src/openapi/assets/favicon",
+  "../../src/openapi/assets/favicon"
+];
+var OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES = [
+  "src/openapi/assets/favicon",
+  "openapi/assets/favicon",
+  "dist/openapi/assets/favicon"
+];
 var OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK = "/* OpenAPI docs runtime asset missing: tailwind disabled */";
-function resolveOpenAPITailwindAssetFile() {
-  for (const relativePath of OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES) {
+function buildOpenAPIAssetCandidatePaths(bases, filename) {
+  return bases.map((base) => `${base}/${filename}`);
+}
+function resolveOpenAPIAssetFile(relativeCandidates, cwdCandidates) {
+  for (const relativePath of relativeCandidates) {
     try {
       const fileUrl = new URL(relativePath, import.meta.url);
-      if (existsSync2(fileUrl)) {
+      if (existsSync3(fileUrl)) {
         return Bun.file(fileUrl);
       }
     } catch {}
   }
   const cwd = process.cwd();
-  for (const relativePath of OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES) {
+  for (const relativePath of cwdCandidates) {
     const absolutePath = join2(cwd, relativePath);
-    if (existsSync2(absolutePath)) {
+    if (existsSync3(absolutePath)) {
       return Bun.file(absolutePath);
     }
   }
   return null;
 }
-var OPENAPI_TAILWIND_ASSET_FILE = resolveOpenAPITailwindAssetFile();
+var OPENAPI_TAILWIND_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES, OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES);
+var OPENAPI_LOGO_DARK_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_LOGO_DARK_ASSET_RELATIVE_CANDIDATES, OPENAPI_LOGO_DARK_ASSET_CWD_CANDIDATES);
+var OPENAPI_LOGO_WHITE_ASSET_FILE = resolveOpenAPIAssetFile(OPENAPI_LOGO_WHITE_ASSET_RELATIVE_CANDIDATES, OPENAPI_LOGO_WHITE_ASSET_CWD_CANDIDATES);
+var OPENAPI_APPLE_TOUCH_ICON_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "apple-touch-icon.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "apple-touch-icon.png"));
+var OPENAPI_FAVICON_32_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon-32x32.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon-32x32.png"));
+var OPENAPI_FAVICON_16_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon-16x16.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon-16x16.png"));
+var OPENAPI_FAVICON_ICO_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "favicon.ico"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "favicon.ico"));
+var OPENAPI_WEBMANIFEST_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "site.webmanifest"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "site.webmanifest"));
+var OPENAPI_ANDROID_192_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "android-chrome-192x192.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "android-chrome-192x192.png"));
+var OPENAPI_ANDROID_512_ASSET_FILE = resolveOpenAPIAssetFile(buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_RELATIVE_BASE_CANDIDATES, "android-chrome-512x512.png"), buildOpenAPIAssetCandidatePaths(OPENAPI_FAVICON_ASSET_CWD_BASE_CANDIDATES, "android-chrome-512x512.png"));
+var OPENAPI_FAVICON_ASSETS = [
+  {
+    path: OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH,
+    file: OPENAPI_APPLE_TOUCH_ICON_ASSET_FILE,
+    contentType: "image/png",
+    filename: "apple-touch-icon.png"
+  },
+  {
+    path: OPENAPI_FAVICON_32_ASSET_PATH,
+    file: OPENAPI_FAVICON_32_ASSET_FILE,
+    contentType: "image/png",
+    filename: "favicon-32x32.png"
+  },
+  {
+    path: OPENAPI_FAVICON_16_ASSET_PATH,
+    file: OPENAPI_FAVICON_16_ASSET_FILE,
+    contentType: "image/png",
+    filename: "favicon-16x16.png"
+  },
+  {
+    path: OPENAPI_FAVICON_ICO_ASSET_PATH,
+    file: OPENAPI_FAVICON_ICO_ASSET_FILE,
+    contentType: "image/x-icon",
+    filename: "favicon.ico"
+  },
+  {
+    path: OPENAPI_WEBMANIFEST_ASSET_PATH,
+    file: OPENAPI_WEBMANIFEST_ASSET_FILE,
+    contentType: "application/manifest+json; charset=utf-8",
+    filename: "site.webmanifest"
+  },
+  {
+    path: OPENAPI_ANDROID_192_ASSET_PATH,
+    file: OPENAPI_ANDROID_192_ASSET_FILE,
+    contentType: "image/png",
+    filename: "android-chrome-192x192.png"
+  },
+  {
+    path: OPENAPI_ANDROID_512_ASSET_PATH,
+    file: OPENAPI_ANDROID_512_ASSET_FILE,
+    contentType: "image/png",
+    filename: "android-chrome-512x512.png"
+  }
+];
 var DOCS_HTML_CACHE_CONTROL = "public, max-age=0, must-revalidate";
 var DOCS_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
+var DOCS_ASSET_ERROR_CACHE_CONTROL = "no-store";
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function wildcardPatternToRegex(pattern) {
+  let regexSource = "^";
+  for (const char of pattern) {
+    if (char === "*") {
+      regexSource += ".*";
+      continue;
+    }
+    regexSource += escapeRegex(char);
+  }
+  regexSource += "$";
+  return new RegExp(regexSource);
+}
+function matchesExposePath(path, exposePathPattern) {
+  if (!exposePathPattern.includes("*")) {
+    return path === exposePathPattern;
+  }
+  return wildcardPatternToRegex(exposePathPattern).test(path);
+}
 
 class VectorServer {
   server = null;
@@ -2845,6 +3454,8 @@ class VectorServer {
   openapiDocsHtmlCache = null;
   openapiWarningsLogged = false;
   openapiTailwindMissingLogged = false;
+  openapiLogoDarkMissingLogged = false;
+  openapiLogoWhiteMissingLogged = false;
   corsHandler = null;
   corsHeadersEntries = null;
   constructor(router, config) {
@@ -2894,9 +3505,10 @@ class VectorServer {
     }
     const openapiObject = openapi || {};
     const docsValue = openapiObject.docs;
-    const docs = typeof docsValue === "boolean" ? { enabled: docsValue, path: "/docs" } : {
+    const docs = typeof docsValue === "boolean" ? { enabled: docsValue, path: "/docs", exposePaths: undefined } : {
       enabled: docsValue?.enabled === true,
-      path: docsValue?.path || "/docs"
+      path: docsValue?.path || "/docs",
+      exposePaths: Array.isArray(docsValue?.exposePaths) ? docsValue.exposePaths.map((path) => typeof path === "string" ? path.trim() : "").filter((path) => path.length > 0) : undefined
     };
     return {
       enabled: openapiObject.enabled ?? defaultEnabled,
@@ -2927,11 +3539,29 @@ class VectorServer {
     this.openapiDocCache = result.document;
     return this.openapiDocCache;
   }
+  getOpenAPIDocumentForDocs() {
+    const exposePaths = this.openapiConfig.docs.exposePaths;
+    const document = this.getOpenAPIDocument();
+    if (!Array.isArray(exposePaths) || exposePaths.length === 0) {
+      return document;
+    }
+    const existingPaths = document.paths && typeof document.paths === "object" && !Array.isArray(document.paths) ? document.paths : {};
+    const filteredPaths = {};
+    for (const [path, value] of Object.entries(existingPaths)) {
+      if (exposePaths.some((pattern) => matchesExposePath(path, pattern))) {
+        filteredPaths[path] = value;
+      }
+    }
+    return {
+      ...document,
+      paths: filteredPaths
+    };
+  }
   getOpenAPIDocsHtmlCacheEntry() {
     if (this.openapiDocsHtmlCache) {
       return this.openapiDocsHtmlCache;
     }
-    const html = renderOpenAPIDocsHtml(this.getOpenAPIDocument(), this.openapiConfig.path, OPENAPI_TAILWIND_ASSET_PATH);
+    const html = renderOpenAPIDocsHtml(this.getOpenAPIDocumentForDocs(), this.openapiConfig.path, OPENAPI_TAILWIND_ASSET_PATH, OPENAPI_LOGO_DARK_ASSET_PATH, OPENAPI_LOGO_WHITE_ASSET_PATH, OPENAPI_APPLE_TOUCH_ICON_ASSET_PATH, OPENAPI_FAVICON_32_ASSET_PATH, OPENAPI_FAVICON_16_ASSET_PATH, OPENAPI_WEBMANIFEST_ASSET_PATH);
     const gzip = Bun.gzipSync(html);
     const etag = `"${Bun.hash(html).toString(16)}"`;
     this.openapiDocsHtmlCache = { html, gzip, etag };
@@ -2949,6 +3579,11 @@ class VectorServer {
     if (this.openapiConfig.docs.enabled) {
       reserved.add(this.openapiConfig.docs.path);
       reserved.add(OPENAPI_TAILWIND_ASSET_PATH);
+      reserved.add(OPENAPI_LOGO_DARK_ASSET_PATH);
+      reserved.add(OPENAPI_LOGO_WHITE_ASSET_PATH);
+      for (const asset of OPENAPI_FAVICON_ASSETS) {
+        reserved.add(asset.path);
+      }
     }
     const methodConflicts = this.router.getRouteDefinitions().filter((route) => reserved.has(route.path)).map((route) => `${route.method} ${route.path}`);
     const staticConflicts = Object.entries(this.router.getRouteTable()).filter(([path, value]) => reserved.has(path) && value instanceof Response).map(([path]) => `STATIC ${path}`);
@@ -3021,6 +3656,71 @@ class VectorServer {
         }
       });
     }
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_LOGO_DARK_ASSET_PATH) {
+      if (!OPENAPI_LOGO_DARK_ASSET_FILE) {
+        if (!this.openapiLogoDarkMissingLogged) {
+          this.openapiLogoDarkMissingLogged = true;
+          console.warn('[OpenAPI] Missing docs runtime asset "logo_dark.svg".');
+        }
+        return new Response("OpenAPI docs runtime asset missing: logo_dark.svg", {
+          status: 404,
+          headers: {
+            "content-type": "text/plain; charset=utf-8",
+            "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+          }
+        });
+      }
+      return new Response(OPENAPI_LOGO_DARK_ASSET_FILE, {
+        status: 200,
+        headers: {
+          "content-type": "image/svg+xml; charset=utf-8",
+          "cache-control": DOCS_ASSET_CACHE_CONTROL
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_LOGO_WHITE_ASSET_PATH) {
+      if (!OPENAPI_LOGO_WHITE_ASSET_FILE) {
+        if (!this.openapiLogoWhiteMissingLogged) {
+          this.openapiLogoWhiteMissingLogged = true;
+          console.warn('[OpenAPI] Missing docs runtime asset "logo_white.svg".');
+        }
+        return new Response("OpenAPI docs runtime asset missing: logo_white.svg", {
+          status: 404,
+          headers: {
+            "content-type": "text/plain; charset=utf-8",
+            "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+          }
+        });
+      }
+      return new Response(OPENAPI_LOGO_WHITE_ASSET_FILE, {
+        status: 200,
+        headers: {
+          "content-type": "image/svg+xml; charset=utf-8",
+          "cache-control": DOCS_ASSET_CACHE_CONTROL
+        }
+      });
+    }
+    if (this.openapiConfig.docs.enabled) {
+      const faviconAsset = OPENAPI_FAVICON_ASSETS.find((asset) => asset.path === pathname);
+      if (faviconAsset) {
+        if (!faviconAsset.file) {
+          return new Response(`OpenAPI docs runtime asset missing: ${faviconAsset.filename}`, {
+            status: 404,
+            headers: {
+              "content-type": "text/plain; charset=utf-8",
+              "cache-control": DOCS_ASSET_ERROR_CACHE_CONTROL
+            }
+          });
+        }
+        return new Response(faviconAsset.file, {
+          status: 200,
+          headers: {
+            "content-type": faviconAsset.contentType,
+            "cache-control": DOCS_ASSET_CACHE_CONTROL
+          }
+        });
+      }
+    }
     return null;
   }
   normalizeCorsOptions(options) {
@@ -3071,7 +3771,7 @@ class VectorServer {
         reusePort: this.config.reusePort !== false,
         routes: this.router.getRouteTable(),
         fetch: fallbackFetch,
-        idleTimeout: this.config.idleTimeout || 60,
+        idleTimeout: this.config.idleTimeout ?? 60,
         error: (error, request) => {
           console.error("[ERROR] Server error:", error);
           return this.applyCors(new Response("Internal Server Error", { status: 500 }), request);
@@ -3134,6 +3834,7 @@ class Vector {
   routeGenerator = null;
   _protectedHandler = null;
   _cacheHandler = null;
+  shutdownPromise = null;
   constructor() {
     this.middlewareManager = new MiddlewareManager;
     this.authManager = new AuthManager;
@@ -3148,14 +3849,22 @@ class Vector {
   }
   setProtectedHandler(handler) {
     this._protectedHandler = handler;
-    this.authManager.setProtectedHandler(handler);
+    if (handler) {
+      this.authManager.setProtectedHandler(handler);
+      return;
+    }
+    this.authManager.clearProtectedHandler();
   }
   getProtectedHandler() {
     return this._protectedHandler;
   }
   setCacheHandler(handler) {
     this._cacheHandler = handler;
-    this.cacheManager.setCacheHandler(handler);
+    if (handler) {
+      this.cacheManager.setCacheHandler(handler);
+      return;
+    }
+    this.cacheManager.clearCacheHandler();
   }
   getCacheHandler() {
     return this._cacheHandler;
@@ -3178,6 +3887,9 @@ class Vector {
     if (config?.finally) {
       this.middlewareManager.addFinally(...config.finally);
     }
+    if (typeof this.config.startup === "function") {
+      await this.config.startup();
+    }
     if (this.config.autoDiscover !== false) {
       await this.discoverRoutes();
     }
@@ -3260,6 +3972,22 @@ class Vector {
       this.server = null;
     }
   }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      return this.shutdownPromise;
+    }
+    this.shutdownPromise = (async () => {
+      this.stop();
+      if (typeof this.config.shutdown === "function") {
+        await this.config.shutdown();
+      }
+    })();
+    try {
+      await this.shutdownPromise;
+    } finally {
+      this.shutdownPromise = null;
+    }
+  }
   getServer() {
     return this.server;
   }
@@ -3278,111 +4006,40 @@ class Vector {
 }
 var getVectorInstance = Vector.getInstance;
 
-// src/core/config-loader.ts
-import { existsSync as existsSync3 } from "fs";
-import { resolve as resolve2, isAbsolute } from "path";
-class ConfigLoader {
-  configPath;
-  config = null;
-  configSource = "default";
-  constructor(configPath) {
-    const path = configPath || "vector.config.ts";
-    this.configPath = isAbsolute(path) ? path : resolve2(process.cwd(), path);
-  }
-  async load() {
-    if (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 msg = error instanceof Error ? error.message : String(error);
-        console.error(`[Vector] Failed to load config from ${this.configPath}: ${msg}`);
-        console.error("[Vector] Server is using default configuration. Fix your config file and restart.");
-        this.config = {};
-      }
-    } else {
-      this.config = {};
-    }
-    return await this.buildLegacyConfig();
-  }
-  getConfigSource() {
-    return this.configSource;
-  }
-  async buildLegacyConfig() {
-    const config = {};
-    if (this.config) {
-      config.port = this.config.port;
-      config.hostname = this.config.hostname;
-      config.reusePort = this.config.reusePort;
-      config.development = this.config.development;
-      config.routesDir = this.config.routesDir || "./routes";
-      config.idleTimeout = this.config.idleTimeout;
-      config.defaults = this.config.defaults;
-      config.openapi = this.config.openapi;
-    }
-    config.autoDiscover = true;
-    if (this.config?.cors) {
-      if (typeof this.config.cors === "boolean") {
-        config.cors = this.config.cors ? {
-          origin: "*",
-          credentials: true,
-          allowHeaders: "Content-Type, Authorization",
-          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-          exposeHeaders: "Authorization",
-          maxAge: 86400
-        } : undefined;
-      } else {
-        config.cors = this.config.cors;
-      }
-    }
-    if (this.config?.before) {
-      config.before = this.config.before;
-    }
-    if (this.config?.after) {
-      config.finally = this.config.after;
-    }
-    return config;
-  }
-  async loadAuthHandler() {
-    return this.config?.auth || null;
-  }
-  async loadCacheHandler() {
-    return this.config?.cache || null;
-  }
-  getConfig() {
-    return this.config;
-  }
-}
-
-// 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/start-vector.ts
+async function startVector(options = {}) {
+  const configLoader = new ConfigLoader(options.configPath);
+  const loadedConfig = await configLoader.load();
+  const configSource = configLoader.getConfigSource();
+  let config = { ...loadedConfig };
+  if (options.mutateConfig) {
+    config = await options.mutateConfig(config, { configSource });
+  }
+  if (options.config) {
+    config = { ...config, ...options.config };
+  }
+  if (options.autoDiscover !== undefined) {
+    config.autoDiscover = options.autoDiscover;
+  }
+  const vector = getVectorInstance();
+  const resolvedProtectedHandler = options.protectedHandler !== undefined ? options.protectedHandler : await configLoader.loadAuthHandler();
+  const resolvedCacheHandler = options.cacheHandler !== undefined ? options.cacheHandler : await configLoader.loadCacheHandler();
+  vector.setProtectedHandler(resolvedProtectedHandler ?? null);
+  vector.setCacheHandler(resolvedCacheHandler ?? null);
+  const server = await vector.startServer(config);
+  const effectiveConfig = {
+    ...config,
+    port: server.port ?? config.port ?? DEFAULT_CONFIG.PORT,
+    hostname: server.hostname || config.hostname || DEFAULT_CONFIG.HOSTNAME,
+    reusePort: config.reusePort !== false,
+    idleTimeout: config.idleTimeout ?? 60
+  };
+  return {
+    server,
+    config: effectiveConfig,
+    stop: () => vector.stop(),
+    shutdown: () => vector.shutdown()
+  };
 }
 
 // src/cli/index.ts
@@ -3429,7 +4086,8 @@ var hasPortOption = args.some((arg) => arg === "--port" || arg === "-p" || arg.s
 async function runDev() {
   const isDev = command === "dev";
   let server = null;
-  let vector = null;
+  let app = null;
+  let removeShutdownHandlers = null;
   async function startServer() {
     const timeoutPromise = new Promise((_, reject) => {
       setTimeout(() => {
@@ -3438,34 +4096,30 @@ async function runDev() {
     });
     const serverStartPromise = (async () => {
       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) {
-        config.cors = {
-          origin: "*",
-          credentials: true,
-          allowHeaders: "Content-Type, Authorization",
-          allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-          exposeHeaders: "Authorization",
-          maxAge: 86400
-        };
-      }
-      vector = getVectorInstance();
-      const authHandler = await configLoader.loadAuthHandler();
-      if (authHandler) {
-        vector.setProtectedHandler(authHandler);
-      }
-      const cacheHandler = await configLoader.loadCacheHandler();
-      if (cacheHandler) {
-        vector.setCacheHandler(cacheHandler);
-      }
-      server = await vector.startServer(config);
+      app = await startVector({
+        configPath: explicitConfigPath,
+        mutateConfig: (loadedConfig) => {
+          const config2 = { ...loadedConfig };
+          config2.port = resolvePort(config2.port, hasPortOption, values.port);
+          config2.hostname = resolveHost(config2.hostname, hasHostOption, values.host);
+          config2.routesDir = resolveRoutesDir(config2.routesDir, hasRoutesOption, values.routes);
+          config2.development = config2.development ?? isDev;
+          config2.autoDiscover = true;
+          if (config2.cors === undefined && values.cors) {
+            config2.cors = {
+              origin: "*",
+              credentials: true,
+              allowHeaders: "Content-Type, Authorization",
+              allowMethods: "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+              exposeHeaders: "Authorization",
+              maxAge: 86400
+            };
+          }
+          return config2;
+        }
+      });
+      server = app.server;
+      const config = app.config;
       if (!server || !server.port) {
         throw new Error("Server started but is not responding correctly");
       }
@@ -3474,13 +4128,18 @@ async function runDev() {
       console.log(`
 Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
 `);
-      return { server, vector, config };
+      return { server, app, config };
     })();
     return await Promise.race([serverStartPromise, timeoutPromise]);
   }
   try {
     const result = await startServer();
     server = result.server;
+    if (!removeShutdownHandlers) {
+      removeShutdownHandlers = installGracefulShutdownHandlers({
+        getTarget: () => app
+      });
+    }
     if (isDev && values.watch) {
       try {
         let reloadTimeout = null;
@@ -3504,14 +4163,14 @@ Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
               isReloading = true;
               lastReloadTime = Date.now();
               changedFiles.clear();
-              if (vector) {
-                vector.stop();
+              if (app) {
+                app.stop();
               }
               await new Promise((resolve3) => setTimeout(resolve3, 100));
               try {
                 const result2 = await startServer();
                 server = result2.server;
-                vector = result2.vector;
+                app = result2.app;
               } catch (error) {
                 console.error(`
 [Reload Error]`, error.message || error);