@websublime/vite-plugin-open-api-server 0.24.0-next.0 → 0.24.0-next.10

package/dist/index.js

@@ -1,11 +1,13 @@
-import { existsSync } from 'fs';
 import { createRequire } from 'module';
-import path2, { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-import { createOpenApiServer, executeSeeds } from '@websublime/vite-plugin-open-api-core';
-export { defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
 import pc from 'picocolors';
+import { existsSync } from 'fs';
+import path, { dirname, join } from 'path';
+import { executeSeeds, createOpenApiServer, mountDevToolsRoutes, createWebSocketHub } from '@websublime/vite-plugin-open-api-core';
+export { defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
 import fg from 'fast-glob';
+import { fileURLToPath } from 'url';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
 
 // src/plugin.ts
 function printBanner(info, options) {
@@ -109,7 +111,7 @@ async function directoryExists(dirPath) {
 // src/handlers.ts
 async function loadHandlers(handlersDir, viteServer, cwd = process.cwd(), logger = console) {
   const handlers = /* @__PURE__ */ new Map();
-  const absoluteDir = path2.resolve(cwd, handlersDir);
+  const absoluteDir = path.resolve(cwd, handlersDir);
   const dirExists = await directoryExists(absoluteDir);
   if (!dirExists) {
     return {
@@ -126,7 +128,7 @@ async function loadHandlers(handlersDir, viteServer, cwd = process.cwd(), logger
     ignore: ["node_modules/**", "dist/**"]
   });
   for (const file of files) {
-    const absolutePath = path2.join(absoluteDir, file);
+    const absolutePath = path.join(absoluteDir, file);
     const fileHandlers = await loadHandlerFile(absolutePath, viteServer, logger);
     for (const [operationId, handler] of Object.entries(fileHandlers)) {
       if (handlers.has(operationId)) {
@@ -173,7 +175,7 @@ async function loadHandlerFile(filePath, viteServer, logger) {
   }
 }
 async function getHandlerFiles(handlersDir, cwd = process.cwd()) {
-  const absoluteDir = path2.resolve(cwd, handlersDir);
+  const absoluteDir = path.resolve(cwd, handlersDir);
   const dirExists = await directoryExists(absoluteDir);
   if (!dirExists) {
     return [];
@@ -187,6 +189,90 @@ async function getHandlerFiles(handlersDir, cwd = process.cwd()) {
   });
   return files;
 }
+async function loadSeeds(seedsDir, viteServer, cwd = process.cwd(), logger = console) {
+  const seeds = /* @__PURE__ */ new Map();
+  const absoluteDir = path.resolve(cwd, seedsDir);
+  const dirExists = await directoryExists(absoluteDir);
+  if (!dirExists) {
+    return {
+      seeds,
+      fileCount: 0,
+      files: []
+    };
+  }
+  const pattern = "**/*.seeds.{ts,js,mjs}";
+  const files = await fg(pattern, {
+    cwd: absoluteDir,
+    absolute: false,
+    onlyFiles: true,
+    ignore: ["node_modules/**", "dist/**"]
+  });
+  for (const file of files) {
+    const absolutePath = path.join(absoluteDir, file);
+    const fileSeeds = await loadSeedFile(absolutePath, viteServer, logger);
+    for (const [schemaName, seedFn] of Object.entries(fileSeeds)) {
+      if (seeds.has(schemaName)) {
+        logger.warn(
+          `[vite-plugin-open-api-server] Duplicate seed for schema "${schemaName}" in ${file}. Using last definition.`
+        );
+      }
+      seeds.set(schemaName, seedFn);
+    }
+  }
+  return {
+    seeds,
+    fileCount: files.length,
+    files
+  };
+}
+async function loadSeedFile(filePath, viteServer, logger) {
+  try {
+    const moduleNode = viteServer.moduleGraph.getModuleById(filePath);
+    if (moduleNode) {
+      viteServer.moduleGraph.invalidateModule(moduleNode);
+    }
+    const module = await viteServer.ssrLoadModule(filePath);
+    const seeds = module.default ?? module.seeds ?? module;
+    if (!seeds || typeof seeds !== "object") {
+      logger.warn(
+        `[vite-plugin-open-api-server] Invalid seed file ${filePath}: expected object export`
+      );
+      return {};
+    }
+    const validSeeds = {};
+    for (const [key, value] of Object.entries(seeds)) {
+      if (typeof value === "function") {
+        validSeeds[key] = value;
+      }
+    }
+    return validSeeds;
+  } catch (error) {
+    logger.error(
+      `[vite-plugin-open-api-server] Failed to load seed file ${filePath}:`,
+      error instanceof Error ? error.message : error
+    );
+    return {};
+  }
+}
+async function getSeedFiles(seedsDir, cwd = process.cwd()) {
+  const absoluteDir = path.resolve(cwd, seedsDir);
+  const dirExists = await directoryExists(absoluteDir);
+  if (!dirExists) {
+    return [];
+  }
+  const pattern = "**/*.seeds.{ts,js,mjs}";
+  const files = await fg(pattern, {
+    cwd: absoluteDir,
+    absolute: true,
+    onlyFiles: true,
+    ignore: ["node_modules/**", "dist/**"]
+  });
+  return files;
+}
+
+// src/hot-reload.ts
+var nodeModulesRe = /(^|[\\/])node_modules([\\/]|$)/;
+var distRe = /(^|[\\/])dist([\\/]|$)/;
 async function createFileWatcher(options) {
   const {
     handlersDir,
@@ -200,8 +286,8 @@ async function createFileWatcher(options) {
   const watchers = [];
   const readyPromises = [];
   let isWatching = true;
-  const handlerPattern = "**/*.handlers.{ts,js,mjs}";
-  const seedPattern = "**/*.seeds.{ts,js,mjs}";
+  const handlerRe = /\.handlers\.(ts|js|mjs)$/;
+  const seedRe = /\.seeds\.(ts|js|mjs)$/;
   const safeInvoke = (callback, filePath, context) => {
     Promise.resolve().then(() => callback(filePath)).catch((error) => {
       logger.error(
@@ -210,80 +296,103 @@ async function createFileWatcher(options) {
       );
     });
   };
-  if (handlersDir && onHandlerChange) {
-    const absoluteHandlersDir = path2.resolve(cwd, handlersDir);
-    const handlerWatcher = watch(handlerPattern, {
-      cwd: absoluteHandlersDir,
-      ignoreInitial: true,
-      ignored: ["**/node_modules/**", "**/dist/**"],
-      persistent: true,
-      awaitWriteFinish: {
-        stabilityThreshold: 100,
-        pollInterval: 50
+  const buildIgnored = (pattern) => {
+    return (filePath, stats) => {
+      if (nodeModulesRe.test(filePath) || distRe.test(filePath)) {
+        return true;
       }
-    });
-    handlerWatcher.on("add", (file) => {
-      const absolutePath = path2.join(absoluteHandlersDir, file);
-      safeInvoke(onHandlerChange, absolutePath, "Handler add");
-    });
-    handlerWatcher.on("change", (file) => {
-      const absolutePath = path2.join(absoluteHandlersDir, file);
-      safeInvoke(onHandlerChange, absolutePath, "Handler change");
-    });
-    handlerWatcher.on("unlink", (file) => {
-      const absolutePath = path2.join(absoluteHandlersDir, file);
-      safeInvoke(onHandlerChange, absolutePath, "Handler unlink");
-    });
-    handlerWatcher.on("error", (error) => {
-      logger.error("[vite-plugin-open-api-server] Handler watcher error:", error);
-    });
-    readyPromises.push(
-      new Promise((resolve) => {
-        handlerWatcher.on("ready", () => resolve());
-      })
-    );
-    watchers.push(handlerWatcher);
-  }
-  if (seedsDir && onSeedChange) {
-    const absoluteSeedsDir = path2.resolve(cwd, seedsDir);
-    const seedWatcher = watch(seedPattern, {
-      cwd: absoluteSeedsDir,
-      ignoreInitial: true,
-      ignored: ["**/node_modules/**", "**/dist/**"],
-      persistent: true,
-      awaitWriteFinish: {
-        stabilityThreshold: 100,
-        pollInterval: 50
+      if (!stats) {
+        return false;
       }
-    });
-    seedWatcher.on("add", (file) => {
-      const absolutePath = path2.join(absoluteSeedsDir, file);
-      safeInvoke(onSeedChange, absolutePath, "Seed add");
-    });
-    seedWatcher.on("change", (file) => {
-      const absolutePath = path2.join(absoluteSeedsDir, file);
-      safeInvoke(onSeedChange, absolutePath, "Seed change");
-    });
-    seedWatcher.on("unlink", (file) => {
-      const absolutePath = path2.join(absoluteSeedsDir, file);
-      safeInvoke(onSeedChange, absolutePath, "Seed unlink");
-    });
-    seedWatcher.on("error", (error) => {
-      logger.error("[vite-plugin-open-api-server] Seed watcher error:", error);
-    });
-    readyPromises.push(
-      new Promise((resolve) => {
-        seedWatcher.on("ready", () => resolve());
-      })
-    );
-    watchers.push(seedWatcher);
+      if (!stats.isFile()) {
+        return false;
+      }
+      return !pattern.test(filePath);
+    };
+  };
+  try {
+    if (handlersDir && onHandlerChange) {
+      const absoluteHandlersDir = path.resolve(cwd, handlersDir);
+      if (!existsSync(absoluteHandlersDir)) {
+        logger.warn(
+          `[vite-plugin-open-api-server] Handlers directory does not exist, skipping watcher: ${absoluteHandlersDir}`
+        );
+      } else {
+        const handlerWatcher = watch(absoluteHandlersDir, {
+          ignoreInitial: true,
+          ignored: buildIgnored(handlerRe),
+          persistent: true,
+          awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50
+          }
+        });
+        handlerWatcher.on("add", (file) => {
+          safeInvoke(onHandlerChange, file, "Handler add");
+        });
+        handlerWatcher.on("change", (file) => {
+          safeInvoke(onHandlerChange, file, "Handler change");
+        });
+        handlerWatcher.on("unlink", (file) => {
+          safeInvoke(onHandlerChange, file, "Handler unlink");
+        });
+        handlerWatcher.on("error", (error) => {
+          logger.error("[vite-plugin-open-api-server] Handler watcher error:", error);
+        });
+        readyPromises.push(
+          new Promise((resolve) => {
+            handlerWatcher.on("ready", () => resolve());
+          })
+        );
+        watchers.push(handlerWatcher);
+      }
+    }
+    if (seedsDir && onSeedChange) {
+      const absoluteSeedsDir = path.resolve(cwd, seedsDir);
+      if (!existsSync(absoluteSeedsDir)) {
+        logger.warn(
+          `[vite-plugin-open-api-server] Seeds directory does not exist, skipping watcher: ${absoluteSeedsDir}`
+        );
+      } else {
+        const seedWatcher = watch(absoluteSeedsDir, {
+          ignoreInitial: true,
+          ignored: buildIgnored(seedRe),
+          persistent: true,
+          awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50
+          }
+        });
+        seedWatcher.on("add", (file) => {
+          safeInvoke(onSeedChange, file, "Seed add");
+        });
+        seedWatcher.on("change", (file) => {
+          safeInvoke(onSeedChange, file, "Seed change");
+        });
+        seedWatcher.on("unlink", (file) => {
+          safeInvoke(onSeedChange, file, "Seed unlink");
+        });
+        seedWatcher.on("error", (error) => {
+          logger.error("[vite-plugin-open-api-server] Seed watcher error:", error);
+        });
+        readyPromises.push(
+          new Promise((resolve) => {
+            seedWatcher.on("ready", () => resolve());
+          })
+        );
+        watchers.push(seedWatcher);
+      }
+    }
+  } catch (error) {
+    await Promise.allSettled(watchers.map((w) => w.close()));
+    throw error;
   }
   const readyPromise = Promise.all(readyPromises).then(() => {
   });
   return {
     async close() {
       isWatching = false;
-      await Promise.all(watchers.map((w) => w.close()));
+      await Promise.allSettled(watchers.map((w) => w.close()));
     },
     get isWatching() {
       return isWatching;
@@ -297,9 +406,12 @@ function debounce(fn, delay) {
   let timeoutId = null;
   let isRunning = false;
   let pendingArgs = null;
+  let cancelled = false;
   const execute = async (...args) => {
-    if (isRunning) {
-      pendingArgs = args;
+    if (cancelled || isRunning) {
+      if (isRunning && !cancelled) {
+        pendingArgs = args;
+      }
       return;
     }
     isRunning = true;
@@ -310,14 +422,15 @@ function debounce(fn, delay) {
       }
     } finally {
       isRunning = false;
-      if (pendingArgs !== null) {
+      if (pendingArgs !== null && !cancelled) {
         const nextArgs = pendingArgs;
         pendingArgs = null;
         setTimeout(() => execute(...nextArgs), 0);
       }
     }
   };
-  return (...args) => {
+  const debouncedFn = (...args) => {
+    if (cancelled) return;
     if (timeoutId !== null) {
       clearTimeout(timeoutId);
     }
@@ -326,86 +439,478 @@ function debounce(fn, delay) {
       execute(...args);
     }, delay);
   };
+  debouncedFn.cancel = () => {
+    cancelled = true;
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    pendingArgs = null;
+  };
+  return debouncedFn;
 }
-async function loadSeeds(seedsDir, viteServer, cwd = process.cwd(), logger = console) {
-  const seeds = /* @__PURE__ */ new Map();
-  const absoluteDir = path2.resolve(cwd, seedsDir);
-  const dirExists = await directoryExists(absoluteDir);
-  if (!dirExists) {
-    return {
-      seeds,
-      fileCount: 0,
-      files: []
-    };
+async function createPerSpecFileWatchers(instances, vite, cwd, options) {
+  const watchers = [];
+  const allDebouncedFns = [];
+  try {
+    for (const instance of instances) {
+      const debouncedHandlerReload = debounce(
+        () => reloadSpecHandlers(instance, vite, cwd, options),
+        100
+      );
+      const debouncedSeedReload = debounce(
+        () => reloadSpecSeeds(instance, vite, cwd, options),
+        100
+      );
+      allDebouncedFns.push(debouncedHandlerReload, debouncedSeedReload);
+      const innerWatcher = await createFileWatcher({
+        handlersDir: instance.config.handlersDir,
+        seedsDir: instance.config.seedsDir,
+        cwd,
+        logger: options.logger,
+        onHandlerChange: debouncedHandlerReload,
+        onSeedChange: debouncedSeedReload
+      });
+      watchers.push({
+        async close() {
+          debouncedHandlerReload.cancel();
+          debouncedSeedReload.cancel();
+          await innerWatcher.close();
+        },
+        get isWatching() {
+          return innerWatcher.isWatching;
+        },
+        get ready() {
+          return innerWatcher.ready;
+        }
+      });
+    }
+  } catch (error) {
+    for (const fn of allDebouncedFns) fn.cancel();
+    await Promise.allSettled(watchers.map((w) => w.close()));
+    throw error;
   }
-  const pattern = "**/*.seeds.{ts,js,mjs}";
-  const files = await fg(pattern, {
-    cwd: absoluteDir,
-    absolute: false,
-    onlyFiles: true,
-    ignore: ["node_modules/**", "dist/**"]
-  });
-  for (const file of files) {
-    const absolutePath = path2.join(absoluteDir, file);
-    const fileSeeds = await loadSeedFile(absolutePath, viteServer, logger);
-    for (const [schemaName, seedFn] of Object.entries(fileSeeds)) {
-      if (seeds.has(schemaName)) {
-        logger.warn(
-          `[vite-plugin-open-api-server] Duplicate seed for schema "${schemaName}" in ${file}. Using last definition.`
+  return watchers;
+}
+async function reloadSpecHandlers(instance, vite, cwd, options) {
+  try {
+    const logger = options.logger ?? console;
+    const handlersResult = await loadHandlers(instance.config.handlersDir, vite, cwd, logger);
+    instance.server.updateHandlers(handlersResult.handlers);
+    printReloadNotification("handlers", handlersResult.handlers.size, options);
+  } catch (error) {
+    printError(`Failed to reload handlers for spec "${instance.id}"`, error, options);
+  }
+}
+async function reloadSpecSeeds(instance, vite, cwd, options) {
+  try {
+    const logger = options.logger ?? console;
+    const seedsResult = await loadSeeds(instance.config.seedsDir, vite, cwd, logger);
+    let broadcastCount = seedsResult.seeds.size;
+    instance.server.store.clearAll();
+    if (seedsResult.seeds.size > 0) {
+      try {
+        await executeSeeds(seedsResult.seeds, instance.server.store, instance.server.document);
+      } catch (execError) {
+        broadcastCount = 0;
+        printError(
+          `Seeds loaded but executeSeeds failed for spec "${instance.id}"; store is now empty`,
+          execError,
+          options
         );
       }
-      seeds.set(schemaName, seedFn);
     }
+    instance.server.wsHub.broadcast({
+      type: "seeds:updated",
+      data: { count: broadcastCount }
+    });
+    if (broadcastCount > 0) {
+      printReloadNotification("seeds", broadcastCount, options);
+    }
+  } catch (error) {
+    printError(`Failed to reload seeds for spec "${instance.id}"`, error, options);
   }
-  return {
-    seeds,
-    fileCount: files.length,
-    files
+}
+
+// src/multi-proxy.ts
+var DEVTOOLS_PROXY_PATH = "/_devtools";
+var API_PROXY_PATH = "/_api";
+var WS_PROXY_PATH = "/_ws";
+function getProxyConfig(vite) {
+  if (!vite.config.server) {
+    return null;
+  }
+  vite.config.server.proxy ??= {};
+  return vite.config.server.proxy;
+}
+function configureMultiProxy(vite, instances, port) {
+  const proxyConfig = getProxyConfig(vite);
+  if (!proxyConfig) {
+    return;
+  }
+  const httpTarget = `http://localhost:${port}`;
+  for (const instance of instances) {
+    const prefix = instance.config.proxyPath;
+    proxyConfig[prefix] = {
+      target: httpTarget,
+      changeOrigin: true,
+      rewrite: (path4) => {
+        if (path4 !== prefix && !path4.startsWith(`${prefix}/`) && !path4.startsWith(`${prefix}?`))
+          return path4;
+        const rest = path4.slice(prefix.length);
+        if (rest === "" || rest === "/") return "/";
+        if (rest.startsWith("?")) return `/${rest}`;
+        return rest;
+      },
+      headers: { "x-spec-id": instance.id }
+    };
+  }
+  proxyConfig[DEVTOOLS_PROXY_PATH] = {
+    target: httpTarget,
+    changeOrigin: true
+  };
+  proxyConfig[API_PROXY_PATH] = {
+    target: httpTarget,
+    changeOrigin: true
+  };
+  proxyConfig[WS_PROXY_PATH] = {
+    target: `ws://localhost:${port}`,
+    changeOrigin: true,
+    ws: true
   };
 }
-async function loadSeedFile(filePath, viteServer, logger) {
-  try {
-    const moduleNode = viteServer.moduleGraph.getModuleById(filePath);
-    if (moduleNode) {
-      viteServer.moduleGraph.invalidateModule(moduleNode);
-    }
-    const module = await viteServer.ssrLoadModule(filePath);
-    const seeds = module.default ?? module.seeds ?? module;
-    if (!seeds || typeof seeds !== "object") {
-      logger.warn(
-        `[vite-plugin-open-api-server] Invalid seed file ${filePath}: expected object export`
+
+// package.json
+var package_default = {
+  version: "0.24.0-next.9"};
+
+// src/multi-internal-api.ts
+var PACKAGE_VERSION = package_default.version;
+function mountMultiSpecInternalApi(app, instances) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const inst of instances) {
+    if (seen.has(inst.id)) {
+      throw new Error(
+        `[vite-plugin-open-api-server] Duplicate specId "${inst.id}" in instances array`
       );
-      return {};
     }
-    const validSeeds = {};
-    for (const [key, value] of Object.entries(seeds)) {
-      if (typeof value === "function") {
-        validSeeds[key] = value;
+    seen.add(inst.id);
+  }
+  const instanceMap = new Map(instances.map((i) => [i.id, i]));
+  app.get("/_api/specs", (c) => {
+    const specs = instances.map((i) => ({
+      id: i.id,
+      title: i.info.title,
+      version: i.info.version,
+      proxyPath: i.config.proxyPath,
+      color: i.info.color,
+      endpoints: i.server.registry.endpoints.size,
+      schemas: i.server.store.getSchemas().length,
+      simulations: i.server.simulationManager.count()
+    }));
+    return c.json({ specs, count: specs.length });
+  });
+  app.get("/_api/registry", (c) => {
+    const registries = instances.map((i) => ({
+      specId: i.id,
+      specTitle: i.info.title,
+      specColor: i.info.color,
+      endpoints: Array.from(i.server.registry.endpoints.entries()).map(([key, entry]) => ({
+        ...entry,
+        key
+      })),
+      stats: i.server.registry.stats
+    }));
+    const totalEndpoints = registries.reduce((sum, r) => sum + r.endpoints.length, 0);
+    return c.json({
+      specs: registries,
+      totalEndpoints,
+      totalSpecs: registries.length
+    });
+  });
+  app.get("/_api/health", (c) => {
+    const specs = instances.map((i) => ({
+      id: i.id,
+      endpoints: i.server.registry.endpoints.size,
+      schemas: i.server.store.getSchemas().length,
+      simulations: i.server.simulationManager.count()
+    }));
+    return c.json({
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      version: PACKAGE_VERSION,
+      totalSpecs: instances.length,
+      totalEndpoints: specs.reduce((s, i) => s + i.endpoints, 0),
+      specs
+    });
+  });
+  const specApi = new Hono();
+  specApi.use("/:specId/*", async (c, next) => {
+    const specId = c.req.param("specId");
+    const instance = instanceMap.get(specId);
+    if (!instance) {
+      return c.json({ error: `Unknown spec: ${specId}` }, 404);
+    }
+    c.set("specInstance", instance);
+    await next();
+  });
+  specApi.get("/:specId/registry", (c) => {
+    const instance = c.get("specInstance");
+    return c.json({
+      specId: instance.id,
+      endpoints: Array.from(instance.server.registry.endpoints.entries()).map(([key, entry]) => ({
+        ...entry,
+        key
+      })),
+      stats: instance.server.registry.stats
+    });
+  });
+  specApi.get("/:specId/store", (c) => {
+    const instance = c.get("specInstance");
+    const schemas = instance.server.store.getSchemas().map((schema) => ({
+      name: schema,
+      count: instance.server.store.getCount(schema),
+      idField: instance.server.store.getIdField(schema)
+    }));
+    return c.json({ specId: instance.id, schemas });
+  });
+  specApi.get("/:specId/store/:schema", (c) => {
+    const instance = c.get("specInstance");
+    const schema = c.req.param("schema");
+    const allItems = instance.server.store.list(schema);
+    const total = allItems.length;
+    const rawOffset = Number(c.req.query("offset"));
+    const offset = Number.isFinite(rawOffset) ? Math.max(Math.floor(rawOffset), 0) : 0;
+    const rawLimit = Number(c.req.query("limit"));
+    const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.floor(rawLimit), 0), 1e3) : Math.min(total, 1e3);
+    const items = limit === 0 ? [] : allItems.slice(offset, offset + limit);
+    return c.json({
+      specId: instance.id,
+      schema,
+      idField: instance.server.store.getIdField(schema),
+      items,
+      count: items.length,
+      total,
+      offset,
+      limit
+    });
+  });
+  specApi.get("/:specId/document", (c) => {
+    const instance = c.get("specInstance");
+    return c.json(instance.server.document);
+  });
+  specApi.get("/:specId/simulations", (c) => {
+    const instance = c.get("specInstance");
+    return c.json({
+      specId: instance.id,
+      simulations: instance.server.simulationManager.list(),
+      count: instance.server.simulationManager.count()
+    });
+  });
+  specApi.get("/:specId/timeline", (c) => {
+    const instance = c.get("specInstance");
+    const parsed = Number(c.req.query("limit"));
+    const limit = Number.isFinite(parsed) ? Math.min(Math.max(Math.floor(parsed), 0), 1e3) : 100;
+    const timeline = instance.server.getTimeline();
+    const entries = limit === 0 ? [] : timeline.slice(-limit);
+    return c.json({
+      specId: instance.id,
+      entries,
+      count: entries.length,
+      total: timeline.length,
+      limit
+    });
+  });
+  app.route("/_api/specs", specApi);
+}
+
+// src/multi-command.ts
+var SPEC_SCOPED_COMMANDS = /* @__PURE__ */ new Set([
+  "get:store",
+  "set:store",
+  "clear:store",
+  "set:simulation",
+  "clear:simulation",
+  "reseed"
+]);
+function sendError(hub, client, command, message) {
+  hub.sendTo(client, { type: "error", data: { command, message } });
+}
+function resolveInstance(specId, instanceMap, hub, client, commandType) {
+  if (!specId) return void 0;
+  const instance = instanceMap.get(specId);
+  if (!instance) {
+    sendError(hub, client, commandType, `Unknown spec: ${specId}`);
+  }
+  return instance;
+}
+function handleGetSpecs(hub, client, specsInfo, serverVersion) {
+  hub.sendTo(client, { type: "connected", data: { serverVersion, specs: specsInfo } });
+}
+function handleGetRegistry(cmd, hub, client, instances, instanceMap) {
+  const sendRegistry = (instance, id) => {
+    const registryEvent = {
+      type: "registry",
+      data: {
+        specId: id,
+        endpoints: Array.from(instance.server.registry.endpoints.entries()).map(([key, entry]) => ({
+          ...entry,
+          key
+        })),
+        stats: { ...instance.server.registry.stats }
       }
+    };
+    hub.sendTo(client, registryEvent);
+  };
+  const specId = cmd.data?.specId;
+  if (specId) {
+    const instance = resolveInstance(specId, instanceMap, hub, client, cmd.type);
+    if (!instance) return;
+    sendRegistry(instance, specId);
+  } else {
+    for (const instance of instances) {
+      sendRegistry(instance, instance.id);
     }
-    return validSeeds;
-  } catch (error) {
-    logger.error(
-      `[vite-plugin-open-api-server] Failed to load seed file ${filePath}:`,
-      error instanceof Error ? error.message : error
-    );
-    return {};
   }
 }
-async function getSeedFiles(seedsDir, cwd = process.cwd()) {
-  const absoluteDir = path2.resolve(cwd, seedsDir);
-  const dirExists = await directoryExists(absoluteDir);
-  if (!dirExists) {
-    return [];
+function handleGetTimeline(cmd, hub, client, instances, instanceMap) {
+  const specId = cmd.data?.specId;
+  const rawLimit = Number(cmd.data?.limit);
+  const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.floor(rawLimit), 0), 1e3) : 100;
+  const sendTimeline = (instance, id) => {
+    const timeline = instance.server.getTimeline();
+    const entries = limit === 0 ? [] : timeline.slice(-limit);
+    const timelineEvent = {
+      type: "timeline",
+      data: {
+        specId: id,
+        entries,
+        count: entries.length,
+        total: timeline.length
+      }
+    };
+    hub.sendTo(client, timelineEvent);
+  };
+  if (specId) {
+    const instance = resolveInstance(specId, instanceMap, hub, client, cmd.type);
+    if (!instance) return;
+    sendTimeline(instance, specId);
+  } else {
+    for (const instance of instances) {
+      sendTimeline(instance, instance.id);
+    }
   }
-  const pattern = "**/*.seeds.{ts,js,mjs}";
-  const files = await fg(pattern, {
-    cwd: absoluteDir,
-    absolute: true,
-    onlyFiles: true,
-    ignore: ["node_modules/**", "dist/**"]
+}
+function handleClearTimeline(cmd, hub, client, instances, instanceMap) {
+  const specId = cmd.data?.specId;
+  const clearAndNotify = (instance, id) => {
+    const count = instance.server.clearTimeline();
+    hub.sendTo(client, { type: "timeline:cleared", data: { specId: id, count } });
+  };
+  if (specId) {
+    const instance = resolveInstance(specId, instanceMap, hub, client, cmd.type);
+    if (!instance) return;
+    clearAndNotify(instance, specId);
+  } else {
+    for (const instance of instances) {
+      clearAndNotify(instance, instance.id);
+    }
+  }
+}
+function handleSpecScoped(cmd, hub, client, instanceMap) {
+  const specId = cmd.data?.specId;
+  if (!specId) {
+    sendError(hub, client, cmd.type, "specId is required for this command");
+    return;
+  }
+  const instance = resolveInstance(specId, instanceMap, hub, client, cmd.type);
+  if (!instance) return;
+  const { specId: _, ...coreData } = cmd.data ?? {};
+  const coreCommand = Object.keys(coreData).length > 0 ? { type: cmd.type, data: coreData } : { type: cmd.type };
+  instance.server.wsHub.handleMessage(client, JSON.stringify(coreCommand));
+}
+function createMultiSpecCommandHandler(deps) {
+  const { hub, instances, specsInfo, serverVersion } = deps;
+  const instanceMap = new Map(instances.map((i) => [i.id, i]));
+  return (client, command) => {
+    if (!command || typeof command !== "object" || !("type" in command)) {
+      return;
+    }
+    const cmd = command;
+    if (typeof cmd.type !== "string") {
+      return;
+    }
+    switch (cmd.type) {
+      case "get:specs":
+        handleGetSpecs(hub, client, specsInfo, serverVersion);
+        break;
+      case "get:registry":
+        handleGetRegistry(cmd, hub, client, instances, instanceMap);
+        break;
+      case "get:timeline":
+        handleGetTimeline(cmd, hub, client, instances, instanceMap);
+        break;
+      case "clear:timeline":
+        handleClearTimeline(cmd, hub, client, instances, instanceMap);
+        break;
+      default:
+        if (SPEC_SCOPED_COMMANDS.has(cmd.type)) {
+          handleSpecScoped(cmd, hub, client, instanceMap);
+        } else {
+          sendError(hub, client, cmd.type, `Unknown command type: ${cmd.type}`);
+        }
+        break;
+    }
+  };
+}
+
+// src/multi-ws.ts
+var PACKAGE_VERSION2 = package_default.version;
+var MULTI_SPEC_ONLY_COMMANDS = /* @__PURE__ */ new Set(["get:specs"]);
+function createMultiSpecWebSocketHub(instances, specsInfo) {
+  const hub = createWebSocketHub({ autoConnect: false });
+  const originalAddClient = hub.addClient.bind(hub);
+  hub.addClient = (ws) => {
+    originalAddClient(ws);
+    hub.sendTo(ws, {
+      type: "connected",
+      // biome-ignore lint/suspicious/noExplicitAny: MultiSpecServerEvent extends ServerEvent with specs[]
+      data: { serverVersion: PACKAGE_VERSION2, specs: specsInfo }
+    });
+  };
+  for (const instance of instances) {
+    instance.server.wsHub.broadcast = (event) => {
+      const enriched = { type: event.type, data: { ...event.data, specId: instance.id } };
+      hub.broadcast(enriched);
+    };
+    instance.server.wsHub.sendTo = (client, event) => {
+      const enriched = { type: event.type, data: { ...event.data, specId: instance.id } };
+      return hub.sendTo(client, enriched);
+    };
+  }
+  const commandHandler = createMultiSpecCommandHandler({
+    hub,
+    instances,
+    specsInfo,
+    serverVersion: PACKAGE_VERSION2
   });
-  return files;
+  hub.setCommandHandler(commandHandler);
+  const originalHandleMessage = hub.handleMessage.bind(hub);
+  hub.handleMessage = (client, message) => {
+    try {
+      const parsed = typeof message === "string" ? JSON.parse(message) : message;
+      if (parsed && typeof parsed === "object" && "type" in parsed) {
+        const cmd = parsed;
+        if (MULTI_SPEC_ONLY_COMMANDS.has(cmd.type)) {
+          commandHandler(client, cmd);
+          return;
+        }
+      }
+    } catch {
+    }
+    originalHandleMessage(client, message);
+  };
+  return hub;
 }
 
 // src/types.ts
@@ -426,6 +931,12 @@ function validateSpecs(specs) {
   }
   for (let i = 0; i < specs.length; i++) {
     const spec = specs[i];
+    if (!spec || typeof spec !== "object") {
+      throw new ValidationError(
+        "SPEC_NOT_FOUND",
+        `specs[${i}]: must be a SpecConfig object, got ${spec === null ? "null" : typeof spec}`
+      );
+    }
     if (!spec.spec || typeof spec.spec !== "string" || spec.spec.trim() === "") {
       const identifier = spec.id ? ` (id: "${spec.id}")` : "";
       throw new ValidationError(
@@ -440,9 +951,12 @@ function resolveOptions(options) {
   return {
     specs: options.specs.map((s) => ({
       spec: s.spec,
+      // Placeholder — populated by orchestrator after document processing
       id: s.id ?? "",
+      // Placeholder — populated by orchestrator after document processing
       proxyPath: s.proxyPath ?? "",
-      proxyPathSource: s.proxyPath ? "explicit" : "auto",
+      // Preliminary — overwritten by deriveProxyPath() during orchestration
+      proxyPathSource: s.proxyPath?.trim() ? "explicit" : "auto",
       handlersDir: s.handlersDir ?? "",
       seedsDir: s.seedsDir ?? "",
       idFields: s.idFields ?? {}
@@ -458,18 +972,468 @@ function resolveOptions(options) {
   };
 }
 
+// src/proxy-path.ts
+var RESERVED_PROXY_PATHS = [
+  DEVTOOLS_PROXY_PATH,
+  API_PROXY_PATH,
+  WS_PROXY_PATH
+];
+function deriveProxyPath(explicitPath, document, specId) {
+  if (explicitPath.trim()) {
+    return {
+      proxyPath: normalizeProxyPath(explicitPath.trim(), specId),
+      proxyPathSource: "explicit"
+    };
+  }
+  const servers = document.servers;
+  const serverUrl = servers?.[0]?.url?.trim();
+  if (!serverUrl) {
+    throw new ValidationError(
+      "PROXY_PATH_MISSING",
+      `[${specId}] Cannot derive proxyPath: no servers defined in the OpenAPI document. Set an explicit proxyPath in the spec configuration.`
+    );
+  }
+  let path4;
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(serverUrl);
+  } catch {
+  }
+  if (parsedUrl) {
+    try {
+      path4 = decodeURIComponent(parsedUrl.pathname);
+    } catch {
+      path4 = parsedUrl.pathname;
+    }
+  } else {
+    path4 = serverUrl;
+  }
+  return {
+    proxyPath: normalizeProxyPath(path4, specId),
+    proxyPathSource: "auto"
+  };
+}
+function normalizeProxyPath(path4, specId) {
+  path4 = path4.trim();
+  const queryIdx = path4.indexOf("?");
+  const hashIdx = path4.indexOf("#");
+  const cutIdx = Math.min(
+    queryIdx >= 0 ? queryIdx : path4.length,
+    hashIdx >= 0 ? hashIdx : path4.length
+  );
+  let normalized = path4.slice(0, cutIdx);
+  normalized = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  normalized = normalized.replace(/\/{2,}/g, "/");
+  const segments = normalized.split("/");
+  const resolved = [];
+  for (const segment of segments) {
+    if (segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (resolved.length > 1) {
+        resolved.pop();
+      }
+      continue;
+    }
+    resolved.push(segment);
+  }
+  normalized = resolved.join("/") || "/";
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (normalized === "/") {
+    throw new ValidationError(
+      "PROXY_PATH_TOO_BROAD",
+      `[${specId}] proxyPath "/" is too broad \u2014 it would capture all requests. Set a more specific proxyPath (e.g., "/api/v1").`
+    );
+  }
+  return normalized;
+}
+function validateUniqueProxyPaths(specs) {
+  const paths = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const path4 = spec.proxyPath?.trim();
+    if (!path4) {
+      continue;
+    }
+    validateNotReservedPath(path4, spec.id);
+    if (paths.has(path4)) {
+      throw new ValidationError(
+        "PROXY_PATH_DUPLICATE",
+        `Duplicate proxyPath "${path4}" used by specs "${paths.get(path4)}" and "${spec.id}". Each spec must have a unique proxyPath.`
+      );
+    }
+    paths.set(path4, spec.id);
+  }
+  validateNoPrefixOverlaps(paths);
+}
+function validateNotReservedPath(path4, specId) {
+  for (const reserved of RESERVED_PROXY_PATHS) {
+    if (path4 === reserved || path4.startsWith(`${reserved}/`) || reserved.startsWith(path4)) {
+      throw new ValidationError(
+        "PROXY_PATH_OVERLAP",
+        `[${specId}] proxyPath "${path4}" collides with reserved path "${reserved}" used by the shared DevTools/API/WebSocket service.`
+      );
+    }
+  }
+}
+function validateNoPrefixOverlaps(paths) {
+  const sortedPaths = Array.from(paths.entries()).sort(([a], [b]) => a.length - b.length);
+  for (let i = 0; i < sortedPaths.length; i++) {
+    for (let j = i + 1; j < sortedPaths.length; j++) {
+      const [shorter, shorterId] = sortedPaths[i];
+      const [longer, longerId] = sortedPaths[j];
+      if (longer.startsWith(`${shorter}/`)) {
+        throw new ValidationError(
+          "PROXY_PATH_OVERLAP",
+          `Overlapping proxyPaths: "${shorter}" (${shorterId}) is a prefix of "${longer}" (${longerId}). This would cause routing ambiguity.`
+        );
+      }
+      if (longer.startsWith(shorter)) {
+        throw new ValidationError(
+          "PROXY_PATH_PREFIX_COLLISION",
+          `Proxy path prefix collision: "${shorter}" (${shorterId}) is a string prefix of "${longer}" (${longerId}). Vite's proxy uses startsWith matching, so "${shorter}" would incorrectly capture requests meant for "${longer}".`
+        );
+      }
+    }
+  }
+}
+
+// src/spec-id.ts
+function slugify(input) {
+  return input.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function deriveSpecId(explicitId, document) {
+  if (explicitId.trim()) {
+    const id2 = slugify(explicitId);
+    if (!id2) {
+      throw new ValidationError(
+        "SPEC_ID_MISSING",
+        `Cannot derive spec ID: explicit id "${explicitId}" produces an empty slug. Please provide an id containing ASCII letters or numbers.`
+      );
+    }
+    return id2;
+  }
+  const title = document.info?.title;
+  if (!title || !title.trim()) {
+    throw new ValidationError(
+      "SPEC_ID_MISSING",
+      "Cannot derive spec ID: info.title is missing from the OpenAPI document. Please set an explicit id in the spec configuration."
+    );
+  }
+  const id = slugify(title);
+  if (!id) {
+    throw new ValidationError(
+      "SPEC_ID_MISSING",
+      `Cannot derive spec ID: info.title "${title}" produces an empty slug. Please set an explicit id in the spec configuration.`
+    );
+  }
+  return id;
+}
+function validateUniqueIds(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) {
+      duplicates.add(id);
+    }
+    seen.add(id);
+  }
+  if (duplicates.size > 0) {
+    const list = [...duplicates].join(", ");
+    throw new ValidationError(
+      "SPEC_ID_DUPLICATE",
+      `Duplicate spec IDs: ${list}. Each spec must have a unique ID. Set explicit ids in spec configuration to resolve.`
+    );
+  }
+}
+
+// src/orchestrator.ts
+var SPEC_COLORS = [
+  "#4ade80",
+  // green
+  "#60a5fa",
+  // blue
+  "#f472b6",
+  // pink
+  "#facc15",
+  // yellow
+  "#a78bfa",
+  // purple
+  "#fb923c",
+  // orange
+  "#2dd4bf",
+  // teal
+  "#f87171"
+  // red
+];
+async function processSpec(specConfig, index, options, vite, cwd, logger) {
+  const server = await createOpenApiServer({
+    spec: specConfig.spec,
+    port: options.port,
+    idFields: specConfig.idFields,
+    handlers: /* @__PURE__ */ new Map(),
+    seeds: /* @__PURE__ */ new Map(),
+    timelineLimit: options.timelineLimit,
+    cors: false,
+    // CORS handled at main app level
+    devtools: false,
+    // DevTools mounted at main app level
+    logger
+  });
+  const id = deriveSpecId(specConfig.id, server.document);
+  const handlersDir = specConfig.handlersDir || `./mocks/${id}/handlers`;
+  const seedsDir = specConfig.seedsDir || `./mocks/${id}/seeds`;
+  const handlersResult = await loadHandlers(handlersDir, vite, cwd, logger);
+  const seedsResult = await loadSeeds(seedsDir, vite, cwd, logger);
+  if (handlersResult.handlers.size > 0) {
+    server.updateHandlers(handlersResult.handlers, { silent: true });
+  }
+  if (seedsResult.seeds.size > 0) {
+    await executeSeeds(seedsResult.seeds, server.store, server.document);
+  }
+  const { proxyPath, proxyPathSource } = deriveProxyPath(specConfig.proxyPath, server.document, id);
+  const info = {
+    id,
+    title: server.document.info?.title ?? id,
+    version: server.document.info?.version ?? "unknown",
+    proxyPath,
+    color: SPEC_COLORS[index % SPEC_COLORS.length],
+    endpointCount: server.registry.endpoints.size,
+    schemaCount: server.store.getSchemas().length
+  };
+  return {
+    instance: { id, info, server, config: specConfig },
+    resolvedConfig: { id, proxyPath, proxyPathSource, handlersDir, seedsDir }
+  };
+}
+function buildCorsConfig(options) {
+  const isWildcardOrigin = options.corsOrigin === "*" || Array.isArray(options.corsOrigin) && options.corsOrigin.includes("*");
+  const effectiveCorsOrigin = isWildcardOrigin ? "*" : options.corsOrigin;
+  return {
+    origin: effectiveCorsOrigin,
+    allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
+    allowHeaders: ["Content-Type", "Authorization", "X-Requested-With", "X-Spec-Id"],
+    exposeHeaders: ["Content-Length", "X-Request-Id"],
+    maxAge: 86400,
+    credentials: !isWildcardOrigin
+  };
+}
+function mountDevToolsSpa(mainApp, logger) {
+  const pluginDir = dirname(fileURLToPath(import.meta.url));
+  const spaDir = join(pluginDir, "devtools-spa");
+  const devtoolsSpaDir = existsSync(spaDir) ? spaDir : void 0;
+  if (!devtoolsSpaDir) {
+    logger.warn?.(
+      "[vite-plugin-open-api-server] DevTools SPA not found at",
+      spaDir,
+      '- serving placeholder. Run "pnpm build" to include the SPA.'
+    );
+  }
+  mountDevToolsRoutes(mainApp, {
+    spaDir: devtoolsSpaDir,
+    logger
+  });
+}
+async function mountWebSocketRoute(mainApp, wsHub, logger) {
+  let nodeWsModule;
+  try {
+    nodeWsModule = await import('@hono/node-ws');
+  } catch (err) {
+    const isModuleNotFound = err instanceof Error && ("code" in err ? err.code === "ERR_MODULE_NOT_FOUND" : err.message.includes("@hono/node-ws"));
+    if (!isModuleNotFound) {
+      throw err;
+    }
+    mainApp.get("/_ws", (c) => {
+      return c.json(
+        {
+          message: "WebSocket endpoint - use ws:// protocol",
+          note: "Install @hono/node-ws to enable WebSocket support"
+        },
+        501
+      );
+    });
+    logger.debug?.(
+      "[vite-plugin-open-api-server] @hono/node-ws not available, WebSocket upgrade disabled"
+    );
+    return { injectWebSocket: null };
+  }
+  const nodeWs = nodeWsModule.createNodeWebSocket({ app: mainApp });
+  mainApp.get(
+    "/_ws",
+    nodeWs.upgradeWebSocket(() => ({
+      onOpen(_event, ws) {
+        wsHub.addClient(ws);
+      },
+      onMessage(event, ws) {
+        wsHub.handleMessage(ws, event.data);
+      },
+      onClose(_event, ws) {
+        wsHub.removeClient(ws);
+      }
+    }))
+  );
+  logger.debug?.("[vite-plugin-open-api-server] WebSocket upgrade enabled at /_ws");
+  return { injectWebSocket: nodeWs.injectWebSocket };
+}
+function createDispatchMiddleware(instanceMap) {
+  return async (c, next) => {
+    const rawSpecId = c.req.header("x-spec-id");
+    if (!rawSpecId) {
+      await next();
+      return;
+    }
+    const specId = slugify(rawSpecId.trim());
+    if (!specId) {
+      await next();
+      return;
+    }
+    const instance = instanceMap.get(specId);
+    if (!instance) {
+      return c.json({ error: `Unknown spec: ${specId}` }, 404);
+    }
+    return instance.server.app.fetch(c.req.raw);
+  };
+}
+async function createOrchestrator(options, vite, cwd) {
+  const logger = options.logger ?? console;
+  const instances = [];
+  for (let i = 0; i < options.specs.length; i++) {
+    const { instance, resolvedConfig } = await processSpec(
+      options.specs[i],
+      i,
+      options,
+      vite,
+      cwd,
+      logger
+    );
+    instance.config.id = resolvedConfig.id;
+    instance.config.proxyPath = resolvedConfig.proxyPath;
+    instance.config.proxyPathSource = resolvedConfig.proxyPathSource;
+    instance.config.handlersDir = resolvedConfig.handlersDir;
+    instance.config.seedsDir = resolvedConfig.seedsDir;
+    instances.push(instance);
+  }
+  validateUniqueIds(instances.map((inst) => inst.id));
+  validateUniqueProxyPaths(
+    instances.map((inst) => ({
+      id: inst.id,
+      proxyPath: inst.config.proxyPath
+    }))
+  );
+  const mainApp = new Hono();
+  const corsConfig = buildCorsConfig(options);
+  if (options.cors) {
+    mainApp.use("*", cors(corsConfig));
+    for (const inst of instances) {
+      inst.server.app.use("*", cors(corsConfig));
+    }
+  }
+  if (options.devtools) {
+    mountDevToolsSpa(mainApp, logger);
+  }
+  if (instances.length > 0) {
+    mountMultiSpecInternalApi(mainApp, instances);
+  }
+  const specsInfo = instances.map((inst) => inst.info);
+  const wsHub = createMultiSpecWebSocketHub(instances, specsInfo);
+  const { injectWebSocket } = await mountWebSocketRoute(mainApp, wsHub, logger);
+  const instanceMap = new Map(instances.map((inst) => [inst.id, inst]));
+  mainApp.use("*", createDispatchMiddleware(instanceMap));
+  let serverInstance = null;
+  let boundPort = 0;
+  async function startServerOnPort(fetchHandler, port) {
+    let createAdaptorServer;
+    try {
+      const nodeServer = await import('@hono/node-server');
+      createAdaptorServer = nodeServer.createAdaptorServer;
+    } catch {
+      throw new Error("@hono/node-server is required. Install with: npm install @hono/node-server");
+    }
+    const server = createAdaptorServer({ fetch: fetchHandler });
+    const actualPort = await new Promise((resolve, reject) => {
+      const onListening = () => {
+        server.removeListener("error", onError);
+        const addr = server.address();
+        resolve(typeof addr === "object" && addr ? addr.port : port);
+      };
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        server.close(() => {
+        });
+        if (err.code === "EADDRINUSE") {
+          reject(new Error(`[vite-plugin-open-api-server] Port ${port} is already in use.`));
+        } else {
+          reject(new Error(`[vite-plugin-open-api-server] Server error: ${err.message}`));
+        }
+      };
+      server.once("listening", onListening);
+      server.once("error", onError);
+      server.listen(port);
+    });
+    return { server, actualPort };
+  }
+  return {
+    app: mainApp,
+    instances,
+    specsInfo,
+    wsHub,
+    get port() {
+      return boundPort;
+    },
+    async start() {
+      if (serverInstance) {
+        throw new Error("[vite-plugin-open-api-server] Server already running. Call stop() first.");
+      }
+      const { server, actualPort } = await startServerOnPort(mainApp.fetch, options.port);
+      serverInstance = server;
+      boundPort = actualPort;
+      if (injectWebSocket) {
+        injectWebSocket(serverInstance);
+      }
+      logger.info(`[vite-plugin-open-api-server] Server started on http://localhost:${actualPort}`);
+    },
+    async stop() {
+      const server = serverInstance;
+      if (server) {
+        try {
+          wsHub.clear();
+          if (typeof server.closeAllConnections === "function") {
+            server.closeAllConnections();
+          }
+          await new Promise((resolve, reject) => {
+            server.close((err) => {
+              if (err) {
+                reject(err);
+              } else {
+                resolve();
+              }
+            });
+          });
+          logger.info("[vite-plugin-open-api-server] Server stopped");
+        } catch (err) {
+          logger.error?.("[vite-plugin-open-api-server] Error closing server:", err);
+          throw err;
+        } finally {
+          serverInstance = null;
+          boundPort = 0;
+        }
+      }
+    }
+  };
+}
+
 // src/plugin.ts
 var VIRTUAL_DEVTOOLS_TAB_ID = "virtual:open-api-devtools-tab";
 var RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID = `\0${VIRTUAL_DEVTOOLS_TAB_ID}`;
 function openApiServer(options) {
   const resolvedOptions = resolveOptions(options);
-  let server = null;
-  let vite = null;
-  let fileWatcher = null;
+  let orchestrator = null;
+  let fileWatchers = [];
   let cwd = process.cwd();
   return {
     name: "vite-plugin-open-api-server",
-    // Only active in dev mode
     apply: "serve",
     /**
      * Ensure @vue/devtools-api is available for the DevTools tab module
@@ -515,7 +1479,7 @@ import { addCustomTab } from '@vue/devtools-api';
 
 try {
   // Route through Vite's proxy so it works in all environments
-  const iframeSrc = window.location.origin + '/_devtools/';
+  const iframeSrc = window.location.origin + '${DEVTOOLS_PROXY_PATH}/';
 
   addCustomTab({
     name: 'vite-plugin-open-api-server',
@@ -538,78 +1502,50 @@ try {
      *
      * This hook is called when the dev server is created.
      * We use it to:
-     * 1. Start the OpenAPI mock server
-     * 2. Configure the Vite proxy to forward API requests
-     * 3. Set up file watching for hot reload
+     * 1. Create and start the multi-spec orchestrator
+     * 2. Configure Vite's multi-proxy for all specs
+     * 3. Set up per-spec file watchers for hot reload
+     * 4. Print startup banner
      */
     async configureServer(viteServer) {
-      vite = viteServer;
       cwd = viteServer.config.root;
       if (!resolvedOptions.enabled) {
         return;
       }
       try {
-        const handlersResult = await loadHandlers(resolvedOptions.handlersDir, viteServer, cwd);
-        const seedsResult = await loadSeeds(resolvedOptions.seedsDir, viteServer, cwd);
-        let devtoolsSpaDir;
-        if (resolvedOptions.devtools) {
-          const pluginDir = dirname(fileURLToPath(import.meta.url));
-          const spaDir = join(pluginDir, "devtools-spa");
-          if (existsSync(spaDir)) {
-            devtoolsSpaDir = spaDir;
-          } else {
-            resolvedOptions.logger?.warn?.(
-              "[vite-plugin-open-api-server] DevTools SPA not found at",
-              spaDir,
-              '- serving placeholder. Run "pnpm build" to include the SPA.'
-            );
-          }
-        }
-        const opts = resolvedOptions;
-        server = await createOpenApiServer({
-          spec: opts.spec,
-          port: opts.port,
-          idFields: opts.idFields,
-          handlers: handlersResult.handlers,
-          // Seeds are populated via executeSeeds, not directly
-          seeds: /* @__PURE__ */ new Map(),
-          timelineLimit: opts.timelineLimit,
-          devtools: opts.devtools,
-          devtoolsSpaDir,
-          cors: opts.cors,
-          corsOrigin: opts.corsOrigin,
-          logger: opts.logger
-        });
-        if (seedsResult.seeds.size > 0) {
-          await executeSeeds(seedsResult.seeds, server.store, server.document);
-        }
-        await server.start();
-        configureProxy(viteServer, resolvedOptions.proxyPath, resolvedOptions.port);
-        const bannerInfo = extractBannerInfo(
-          server.registry,
-          {
-            info: {
-              title: server.document.info?.title ?? "OpenAPI Server",
-              version: server.document.info?.version ?? "1.0.0"
-            }
-          },
-          handlersResult.handlers.size,
-          seedsResult.seeds.size,
+        orchestrator = await createOrchestrator(resolvedOptions, viteServer, cwd);
+        await orchestrator.start();
+        configureMultiProxy(viteServer, orchestrator.instances, orchestrator.port);
+        fileWatchers = await createPerSpecFileWatchers(
+          orchestrator.instances,
+          viteServer,
+          cwd,
           resolvedOptions
         );
-        printBanner(bannerInfo, resolvedOptions);
-        await setupFileWatching();
+        if (!resolvedOptions.silent && orchestrator.instances.length > 0) {
+          const firstInstance = orchestrator.instances[0];
+          const bannerInfo = extractBannerInfo(
+            firstInstance.server.registry,
+            {
+              info: {
+                title: firstInstance.server.document.info?.title ?? "OpenAPI Server",
+                version: firstInstance.server.document.info?.version ?? "1.0.0"
+              }
+            },
+            // Handler/seed counts are not tracked per-instance yet.
+            // Multi-spec banner (Epic 5, Task 5.1) will display proper per-spec counts.
+            0,
+            0,
+            resolvedOptions
+          );
+          printBanner(bannerInfo, resolvedOptions);
+        }
       } catch (error) {
+        await teardown();
         printError("Failed to start OpenAPI mock server", error, resolvedOptions);
         throw error;
       }
     },
-    /**
-     * Clean up when Vite server closes
-     */
-    async closeBundle() {
-      await cleanup();
-    },
     /**
      * Inject Vue DevTools custom tab registration script
      *
@@ -629,102 +1565,30 @@ try {
           injectTo: "head"
         }
       ];
+    },
+    /**
+     * Clean up when Vite server closes
+     *
+     * NOTE: closeBundle() is called by Vite when the dev server shuts down
+     * (e.g., Ctrl+C). This is the same lifecycle hook used in v0.x.
+     * While configureServer's viteServer.httpServer?.on('close', ...) is
+     * an alternative, closeBundle() is more reliable across Vite versions
+     * and is the established pattern in this codebase.
+     */
+    async closeBundle() {
+      await teardown();
     }
   };
-  function configureProxy(vite2, proxyPath, port) {
-    const serverConfig = vite2.config.server ?? {};
-    const proxyConfig = serverConfig.proxy ?? {};
-    const escapedPath = proxyPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pathPrefixRegex = new RegExp(`^${escapedPath}`);
-    proxyConfig[proxyPath] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true,
-      // Remove the proxy path prefix when forwarding
-      rewrite: (path4) => path4.replace(pathPrefixRegex, "")
-    };
-    proxyConfig["/_devtools"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true
-    };
-    proxyConfig["/_api"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true
-    };
-    proxyConfig["/_ws"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true,
-      ws: true
-    };
-    if (vite2.config.server) {
-      vite2.config.server.proxy = proxyConfig;
-    }
-  }
-  async function setupFileWatching() {
-    if (!server || !vite) return;
-    const debouncedHandlerReload = debounce(reloadHandlers, 100);
-    const debouncedSeedReload = debounce(reloadSeeds, 100);
-    const watchOpts = resolvedOptions;
-    fileWatcher = await createFileWatcher({
-      handlersDir: watchOpts.handlersDir,
-      seedsDir: watchOpts.seedsDir,
-      cwd,
-      onHandlerChange: debouncedHandlerReload,
-      onSeedChange: debouncedSeedReload
-    });
-  }
-  async function reloadHandlers() {
-    if (!server || !vite) return;
-    try {
-      const handlersResult = await loadHandlers(
-        // biome-ignore lint/suspicious/noExplicitAny: v0.x compat — plugin.ts rewritten in Task 1.7
-        resolvedOptions.handlersDir,
-        vite,
-        cwd
-      );
-      server.updateHandlers(handlersResult.handlers);
-      server.wsHub.broadcast({
-        type: "handlers:updated",
-        data: { count: handlersResult.handlers.size }
-      });
-      printReloadNotification("handlers", handlersResult.handlers.size, resolvedOptions);
-    } catch (error) {
-      printError("Failed to reload handlers", error, resolvedOptions);
-    }
-  }
-  async function reloadSeeds() {
-    if (!server || !vite) return;
-    try {
-      const seedsResult = await loadSeeds(
-        // biome-ignore lint/suspicious/noExplicitAny: v0.x compat — plugin.ts rewritten in Task 1.7
-        resolvedOptions.seedsDir,
-        vite,
-        cwd
-      );
-      if (seedsResult.seeds.size > 0) {
-        server.store.clearAll();
-        await executeSeeds(seedsResult.seeds, server.store, server.document);
-      } else {
-        server.store.clearAll();
+  async function teardown() {
+    await Promise.allSettled(fileWatchers.map((w) => w.close()));
+    fileWatchers = [];
+    if (orchestrator) {
+      try {
+        await orchestrator.stop();
+      } catch {
       }
-      server.wsHub.broadcast({
-        type: "seeds:updated",
-        data: { count: seedsResult.seeds.size }
-      });
-      printReloadNotification("seeds", seedsResult.seeds.size, resolvedOptions);
-    } catch (error) {
-      printError("Failed to reload seeds", error, resolvedOptions);
-    }
-  }
-  async function cleanup() {
-    if (fileWatcher) {
-      await fileWatcher.close();
-      fileWatcher = null;
-    }
-    if (server) {
-      await server.stop();
-      server = null;
+      orchestrator = null;
     }
-    vite = null;
   }
 }
 
@@ -758,12 +1622,12 @@ async function registerDevTools(app, options = {}) {
     console.warn("[OpenAPI DevTools] Failed to register with Vue DevTools:", error);
   }
 }
-function getDevToolsUrl(port = 3e3, host, protocol) {
+function getDevToolsUrl(port = 4e3, host, protocol) {
   const actualProtocol = protocol || (typeof window !== "undefined" ? window.location.protocol.replace(":", "") : "http");
   const actualHost = host || (typeof window !== "undefined" ? window.location.hostname : "localhost");
   return `${actualProtocol}://${actualHost}:${port}/_devtools/`;
 }
 
-export { ValidationError, createFileWatcher, debounce, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, openApiServer, registerDevTools };
+export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, SPEC_COLORS, ValidationError, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, createPerSpecFileWatchers, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, reloadSpecHandlers, reloadSpecSeeds, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map