@_deep4wee/agent-lens 1.0.1 → 1.1.0

package/dist/cli.mjs

@@ -1,15 +1,8 @@
-#!/usr/bin/env node
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var __commonJS = (cb, mod) => function __require2() {
+var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 
@@ -180,9 +173,9 @@ var init_reporter = __esm({
           burstGroups.set(s.burstGroup, list);
         });
         for (const snap of regularSnapshots) {
-          const fileUri = `file:///${snap.filePath.replace(/\\/g, "/")}`;
+          const relativeLink = snap.relativeUri || `./${snap.fileName}`;
           rows.push(
-            `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${fileUri}) |`
+            `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${relativeLink}) |`
           );
         }
         let burstSections = "";
@@ -199,8 +192,8 @@ var init_reporter = __esm({
 | :--- | :--- | :--- | :--- |
 `;
             for (const frame of frames) {
-              const fileUri = `file:///${frame.filePath.replace(/\\/g, "/")}`;
-              burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${fileUri}) | ![](${fileUri}) |
+              const relativeLink = frame.relativeUri || `./${frame.fileName}`;
+              burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${relativeLink}) | ![](${relativeLink}) |
 `;
             }
             burstSections += `
@@ -289,7 +282,9 @@ ${consoleSections}
 
 ## \u{1F4CB} AI Agent Verification Checklist:
 - [ ] **Console Errors**: ${consoleErrors.length === 0 ? "\u2705 No errors found" : `\u274C ${consoleErrors.length} errors \u2014 MUST REVIEW`}
+- [ ] **Visual Layout Check**: Inspect snapshots (e.g. view_image on \`./01_${regularSnapshots[0]?.fileName || "quick_snap"}\`) for layout shifts or clipped elements.
 - [ ] **Responsiveness at \`1024x768\`**: Elements do not overflow the screen, no unwanted horizontal scroll.
+        
 - [ ] **Typography & Spacing**: Spacing matches the design system and layout grids.
 - [ ] **Color Palette & Theme**: Background tints and button accent colors match the concept.
 - [ ] **Component States**: Modals open centered, dropdowns do not overlap with other layers (z-index).
@@ -320,8 +315,6 @@ var init_consoleTracker = __esm({
     ConsoleTracker = class {
       entries = [];
       attached = false;
-      /**
-       */
       attach(page) {
         if (this.attached) return;
         this.attached = true;
@@ -390,8 +383,6 @@ var init_consoleTracker = __esm({
             return "log";
         }
       }
-      /**
-       */
       isIgnoredWarning(text) {
         const ignoredPatterns = [
           "findDOMNode is deprecated",
@@ -411,10 +402,30 @@ var init_consoleTracker = __esm({
 });
 
 // src/shared/lib/playwrightLoader.ts
-import { chromium } from "playwright";
+import { chromium as baseChromium } from "playwright";
+var chromium;
 var init_playwrightLoader = __esm({
   "src/shared/lib/playwrightLoader.ts"() {
     "use strict";
+    chromium = new Proxy(baseChromium, {
+      get(target, prop, receiver) {
+        if (prop === "launch") {
+          return async (...args) => {
+            try {
+              return await target.launch(...args);
+            } catch (err) {
+              if (err.message?.includes("Executable doesn't exist") || err.message?.includes("playwright install") || err.message?.includes("browser has not been downloaded")) {
+                console.error("\n\u274C [AgentLens] Playwright Chromium browser binary is missing!");
+                console.error("\u{1F449} Please install it by running: npx playwright install chromium\n");
+              }
+              throw err;
+            }
+          };
+        }
+        const val = Reflect.get(target, prop, receiver);
+        return typeof val === "function" ? val.bind(target) : val;
+      }
+    });
   }
 });
 
@@ -423,6 +434,7 @@ import { spawn } from "child_process";
 import http from "http";
 import path3 from "path";
 import fs3 from "fs";
+import treeKill from "tree-kill";
 var DesktopDriver;
 var init_desktopDriver = __esm({
   "src/shared/drivers/desktopDriver.ts"() {
@@ -501,6 +513,11 @@ ${this.processStderr.trim() || "(no stderr output)"}`
             );
           }
           console.log(`[DesktopDriver] Launching: ${resolvedExe}`);
+          const finalArgs = [...this.args];
+          const hasDebugPort = finalArgs.some((a) => a.startsWith("--remote-debugging-port="));
+          if (!hasDebugPort) {
+            finalArgs.push(`--remote-debugging-port=${this.port}`);
+          }
           const mergedEnv = {
             ...process.env,
             ...this.env,
@@ -509,6 +526,16 @@ ${this.processStderr.trim() || "(no stderr output)"}`
           this.processStderr = "";
           this.processExited = false;
           this.exitCode = null;
+          this.childProcess = spawn(resolvedExe, finalArgs, {
+            env: mergedEnv,
+            cwd: this.cwd || path3.dirname(resolvedExe),
+            stdio: ["ignore", "ignore", "pipe"],
+            detached: false
+          });
+          ;
+          this.processStderr = "";
+          this.processExited = false;
+          this.exitCode = null;
           this.childProcess = spawn(resolvedExe, this.args, {
             env: mergedEnv,
             cwd: this.cwd || path3.dirname(resolvedExe),
@@ -552,16 +579,12 @@ ${this.processStderr.trim() || "(no stderr output)"}`
           });
           this.browser = null;
         }
-        if (this.childProcess && !this.childProcess.killed) {
-          console.log("[DesktopDriver] Terminating spawned desktop process...");
-          try {
-            if (process.platform === "win32" && this.childProcess.pid) {
-              spawn("taskkill", ["/pid", String(this.childProcess.pid), "/T", "/F"], { stdio: "ignore" });
-            } else {
-              this.childProcess.kill("SIGTERM");
-            }
-          } catch {
-          }
+        if (this.childProcess && !this.childProcess.killed && this.childProcess.pid) {
+          console.log("[DesktopDriver] Terminating spawned desktop process tree...");
+          const pid = this.childProcess.pid;
+          await new Promise((resolve) => {
+            treeKill(pid, "SIGTERM", () => resolve());
+          });
           this.childProcess = null;
         }
       }
@@ -600,42 +623,45 @@ function generateMockIpcScript(registry) {
         }
       };
 
-      // Legacy fallback for generic window.external
-      if (!window.external) {
-        window.external = {};
-      }
-      
-      window.external.sendMessage = (msg) => {
-        try {
-          const parsed = JSON.parse(msg);
-          const action = parsed.Action || parsed.action;
-          const id = parsed.Id || parsed.id;
-
-          const mock = window.__visualRunnerMocks[action];
+            // Safe fallback bridge for hybrid webviews (Photino / CEF / WebView2)
+      try {
+        if (!window.external) {
+          (window as any).external = {};
+        }
+        (window.external as any).sendMessage = (msg) => {
+          try {
+            const parsed = typeof msg === 'string' ? JSON.parse(msg) : msg;
+            const action = parsed.Action || parsed.action;
+            const id = parsed.Id || parsed.id;
+            const mock = (window as any).__visualRunnerMocks[action];
 
-          if (mock) {
-            const response = { Id: id, Type: mock.type || 'SUCCESS', Data: mock.data };
-            setTimeout(() => {
-              const cb = window.__mockCallback;
-              if (cb) cb(JSON.stringify(response));
-            }, mock.delayMs || 20);
-          } else {
-            setTimeout(() => {
-              const cb = window.__mockCallback;
-              if (cb) cb(JSON.stringify({ Id: id, Type: 'SUCCESS', Data: null }));
-            }, 20);
+            if (mock) {
+              const response = { Id: id, Type: mock.type || 'SUCCESS', Data: mock.data };
+              setTimeout(() => {
+                const cb = (window as any).__mockCallback;
+                if (typeof cb === 'function') cb(JSON.stringify(response));
+              }, mock.delayMs || 20);
+            } else {
+              setTimeout(() => {
+                const cb = (window as any).__mockCallback;
+                if (typeof cb === 'function') cb(JSON.stringify({ Id: id, Type: 'SUCCESS', Data: null }));
+              }, 20);
+            }
+          } catch (e) {
+            console.error('[Mock IPC] Failed to process message:', e);
           }
-        } catch (e) {
-          console.error('[Mock IPC] Failed to process legacy message:', e);
-        }
-      };
+        };
 
-      window.external.receiveMessage = (callback) => {
-        window.__mockCallback = callback;
-      };
+        (window.external as any).receiveMessage = (callback) => {
+          (window as any).__mockCallback = callback;
+        };
+      } catch {
+        // Ignored if window.external is read-only in strict Chromium sandboxes
+      }
 
-      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');
+      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys((window as any).__visualRunnerMocks).length, 'mocked actions');
     })();
+        
   `;
 }
 var MockIpcRegistry;
@@ -685,22 +711,22 @@ var init_mockIpc = __esm({
 });
 
 // src/shared/lib/config.ts
-import fs4 from "fs";
 import path4 from "path";
+import fs4 from "fs";
 function loadConfig(cwd = process.cwd()) {
-  const configPath = path4.join(cwd, "agent-lens.json");
-  if (fs4.existsSync(configPath)) {
+  const jsonConfigPath = path4.join(cwd, "agent-lens.json");
+  if (fs4.existsSync(jsonConfigPath)) {
     try {
-      const raw = fs4.readFileSync(configPath, "utf8");
+      const raw = fs4.readFileSync(jsonConfigPath, "utf-8");
       return JSON.parse(raw);
     } catch (e) {
-      console.warn(`\u26A0\uFE0F Warning: Failed to parse agent-lens.json:`, e);
+      console.warn(`\u26A0\uFE0F [Config] Failed to parse agent-lens.json: ${e.message}`);
     }
   }
-  const pkgPath = path4.join(cwd, "package.json");
-  if (fs4.existsSync(pkgPath)) {
+  const packageJsonPath = path4.join(cwd, "package.json");
+  if (fs4.existsSync(packageJsonPath)) {
     try {
-      const raw = fs4.readFileSync(pkgPath, "utf8");
+      const raw = fs4.readFileSync(packageJsonPath, "utf-8");
       const pkg = JSON.parse(raw);
       if (pkg.agentLens && typeof pkg.agentLens === "object") {
         return pkg.agentLens;
@@ -710,78 +736,60 @@ function loadConfig(cwd = process.cwd()) {
   }
   return {};
 }
-function resolveWwwrootDir(customPath, cwd = process.cwd()) {
-  if (customPath) {
-    return path4.resolve(cwd, customPath);
+function detectStartCwd(providedCwd) {
+  if (providedCwd) {
+    const resolved = path4.resolve(process.cwd(), providedCwd);
+    if (fs4.existsSync(resolved)) {
+      return providedCwd;
+    }
   }
-  const standardDirs = [
-    "dist",
-    "build",
-    "wwwroot",
-    "Frontend/dist",
-    "frontend/dist",
-    "client/dist",
-    "web/dist",
-    "ui/dist"
-  ];
-  for (const rel of standardDirs) {
-    const candidate = path4.resolve(cwd, rel);
-    if (fs4.existsSync(candidate) && fs4.existsSync(path4.join(candidate, "index.html"))) {
-      return candidate;
+  const rootPkgPath = path4.join(process.cwd(), "package.json");
+  let rootHasDevScript = false;
+  if (fs4.existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(fs4.readFileSync(rootPkgPath, "utf-8"));
+      rootHasDevScript = Boolean(rootPkg.scripts?.dev || rootPkg.scripts?.start);
+    } catch {
     }
   }
-  const foundDeepWwwroot = findDeepIndexHtmlDir(cwd, 4);
-  if (foundDeepWwwroot) {
-    return foundDeepWwwroot;
+  if (rootHasDevScript) {
+    return void 0;
   }
-  for (const rel of standardDirs) {
-    const candidate = path4.resolve(cwd, rel);
-    if (fs4.existsSync(candidate)) {
-      return candidate;
+  const candidates = ["Frontend", "frontend", "client", "web", "ui", "apps/web", "src/frontend"];
+  for (const candidate of candidates) {
+    const candidatePkg = path4.join(process.cwd(), candidate, "package.json");
+    if (fs4.existsSync(candidatePkg)) {
+      return `./${candidate}`;
     }
   }
-  return path4.resolve(cwd, "dist");
+  return void 0;
 }
-function detectStartCwd(customCwd, rootCwd = process.cwd()) {
-  if (customCwd) {
-    return path4.resolve(rootCwd, customCwd);
+function resolveWwwrootDir(customDir) {
+  if (customDir) {
+    return path4.resolve(process.cwd(), customDir);
   }
-  const subdirectories = ["Frontend", "frontend", "client", "web", "ui", "app"];
-  for (const sub of subdirectories) {
-    const subPkg = path4.join(rootCwd, sub, "package.json");
-    if (fs4.existsSync(subPkg)) {
-      try {
-        const json = JSON.parse(fs4.readFileSync(subPkg, "utf8"));
-        if (json.scripts && (json.scripts.dev || json.scripts.start || json.scripts.build)) {
-          return path4.join(rootCwd, sub);
-        }
-      } catch {
-      }
+  const candidates = [
+    "dist",
+    "build",
+    "out",
+    "wwwroot",
+    "Frontend/dist",
+    "frontend/dist",
+    "client/dist"
+  ];
+  for (const c of candidates) {
+    const candidatePath = path4.resolve(process.cwd(), c);
+    if (fs4.existsSync(candidatePath) && fs4.existsSync(path4.join(candidatePath, "index.html"))) {
+      return candidatePath;
     }
   }
-  return rootCwd;
-}
-function findDeepIndexHtmlDir(dir, maxDepth, currentDepth = 0) {
-  if (currentDepth > maxDepth || !fs4.existsSync(dir)) return null;
-  try {
-    const entries = fs4.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "artifacts") {
-          continue;
-        }
-        const subDir = path4.join(dir, entry.name);
-        if (entry.name === "wwwroot" && fs4.existsSync(path4.join(subDir, "index.html"))) {
-          return subDir;
-        }
-        const found = findDeepIndexHtmlDir(subDir, maxDepth, currentDepth + 1);
-        if (found) return found;
-      }
+  for (const c of candidates) {
+    const candidatePath = path4.resolve(process.cwd(), c);
+    if (fs4.existsSync(candidatePath)) {
+      return candidatePath;
     }
-  } catch {
-    return null;
   }
-  return null;
+  return path4.resolve(process.cwd(), "dist");
 }
 var init_config = __esm({
   "src/shared/lib/config.ts"() {
@@ -823,6 +831,7 @@ var init_previewDriver = __esm({
       serverPort = 0;
       options;
       _baseUrl = "";
+      initialRouteMocks = [];
       mockRegistry;
       constructor(options) {
         this.options = options || {};
@@ -892,9 +901,41 @@ var init_previewDriver = __esm({
           await this.context.addInitScript(mockScript);
         }
         this.page = await this.context.newPage();
+        if (this.initialRouteMocks.length > 0) {
+          for (const entry of this.initialRouteMocks) {
+            await this.addRouteMock(entry);
+          }
+        }
         await this.page.goto(targetUrl, { waitUntil: "domcontentloaded" });
         return { page: this.page, context: this.context, browser: this.browser };
       }
+      async addRouteMock(entry) {
+        if (!this.page) {
+          this.initialRouteMocks.push(entry);
+          return;
+        }
+        await this.page.route(entry.url, async (route) => {
+          const req = route.request();
+          if (entry.method && req.method().toUpperCase() !== entry.method.toUpperCase()) {
+            return route.continue();
+          }
+          if (entry.delayMs) {
+            await new Promise((r) => setTimeout(r, entry.delayMs));
+          }
+          const isJson = typeof entry.body === "object" && entry.body !== null;
+          await route.fulfill({
+            status: entry.status ?? 200,
+            contentType: isJson ? "application/json" : "text/plain; charset=utf-8",
+            body: isJson ? JSON.stringify(entry.body) : String(entry.body ?? ""),
+            headers: entry.headers
+          });
+        });
+      }
+      async setupRouteMocks(routes) {
+        for (const r of routes) {
+          await this.addRouteMock(r);
+        }
+      }
       async updateMockIpc(action, data, options) {
         if (!this.page) {
           throw new Error("PreviewDriver not started. Call start() first.");
@@ -941,108 +982,79 @@ var init_previewDriver = __esm({
 
 // src/shared/lib/processManager.ts
 import { spawn as spawn2 } from "child_process";
-import treeKill from "tree-kill";
+import treeKill2 from "tree-kill";
 var ProcessManager;
 var init_processManager = __esm({
   "src/shared/lib/processManager.ts"() {
     "use strict";
     ProcessManager = class {
-      child = null;
-      stderrOutput = "";
-      stdoutOutput = "";
-      hasExited = false;
-      exitCode = null;
-      /**
-       * Spawns a background process (e.g. dev server, backend, or app)
-       */
+      childProcess = null;
+      isStopped = false;
       async start(command, options) {
-        this.stderrOutput = "";
-        this.stdoutOutput = "";
-        this.hasExited = false;
-        this.exitCode = null;
         const cwd = options?.cwd || process.cwd();
-        const env = { ...process.env, ...options?.env };
         console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
-        this.child = spawn2(command, {
+        this.childProcess = spawn2(command, {
           cwd,
-          env,
-          shell: options?.shell ?? true,
+          env: { ...process.env, ...options?.env },
+          shell: true,
           stdio: ["ignore", "pipe", "pipe"]
         });
-        this.child.stdout?.on("data", (chunk) => {
-          const str = chunk.toString();
-          this.stdoutOutput += str;
-        });
-        this.child.stderr?.on("data", (chunk) => {
-          const str = chunk.toString();
-          this.stderrOutput += str;
+        this.childProcess.stdout?.on("data", (chunk) => {
+          const line = chunk.toString().trim();
+          if (line) {
+          }
         });
-        this.child.on("exit", (code) => {
-          this.hasExited = true;
-          this.exitCode = code;
+        this.childProcess.stderr?.on("data", (chunk) => {
+          const line = chunk.toString().trim();
+          if (line && !line.includes("ExperimentalWarning")) {
+          }
         });
-        this.child.on("error", (err) => {
-          console.error(`\u274C [ProcessManager] Failed to start command: "${command}":`, err.message);
+        this.childProcess.on("exit", (code, signal) => {
+          if (!this.isStopped && code !== 0 && code !== null) {
+            console.warn(`\u26A0\uFE0F [ProcessManager] Subprocess exited prematurely with code ${code}, signal ${signal}`);
+          }
         });
       }
-      /**
-       * Polls a URL until it starts responding or until timeout is reached.
-       */
       async waitForUrl(url, timeoutMs = 3e4) {
+        console.log(`\u23F3 [ProcessManager] Waiting for ${url} to respond...`);
         const startTime = Date.now();
-        console.log(`\u23F3 [ProcessManager] Waiting for URL to become available: ${url} (timeout: ${timeoutMs / 1e3}s)...`);
         while (Date.now() - startTime < timeoutMs) {
-          if (this.hasExited && this.exitCode !== 0) {
+          if (this.childProcess && this.childProcess.exitCode !== null) {
             throw new Error(
-              `[ProcessManager] Process exited prematurely with code ${this.exitCode}.
-Stderr:
-${this.stderrOutput.trim() || "(no stderr)"}
-Stdout:
-${this.stdoutOutput.slice(-500).trim()}`
+              `[ProcessManager] Server process exited with code ${this.childProcess.exitCode} while waiting for ${url}`
             );
           }
           try {
-            const response = await fetch(url, { method: "GET", signal: AbortSignal.timeout(2e3) });
+            const response = await fetch(url, { signal: AbortSignal.timeout(1e3) });
             if (response.status) {
-              console.log(`\u2705 [ProcessManager] Server responded with status ${response.status} at ${url}`);
-              return;
+              console.log(`\u2705 [ProcessManager] Target ${url} is ready (status: ${response.status})!`);
+              return true;
             }
           } catch {
           }
-          await new Promise((resolve) => setTimeout(resolve, 350));
+          await new Promise((r) => setTimeout(r, 500));
         }
-        throw new Error(
-          `[ProcessManager] Timeout (${timeoutMs / 1e3}s) waiting for server at ${url}.
-Last stdout:
-${this.stdoutOutput.slice(-500).trim()}
-Last stderr:
-${this.stderrOutput.trim()}`
-        );
+        throw new Error(`[ProcessManager] Timeout after ${timeoutMs}ms waiting for ${url} to respond.`);
       }
-      /**
-       * Gracefully and forcefully kills the process and all its children.
-       */
       async stop() {
-        if (!this.child || !this.child.pid || this.hasExited) {
-          this.child = null;
+        if (this.isStopped || !this.childProcess || !this.childProcess.pid) {
           return;
         }
-        const pid = this.child.pid;
-        console.log(`\u{1F6D1} [ProcessManager] Terminating process tree (PID: ${pid})...`);
+        this.isStopped = true;
+        const pid = this.childProcess.pid;
+        console.log(`\u{1F6D1} [ProcessManager] Terminating process tree for PID ${pid}...`);
         await new Promise((resolve) => {
-          treeKill(pid, "SIGKILL", (err) => {
+          treeKill2(pid, "SIGTERM", (err) => {
             if (err) {
-              if (process.platform === "win32") {
-                try {
-                  spawn2("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
-                } catch {
-                }
+              try {
+                treeKill2(pid, "SIGKILL");
+              } catch {
               }
             }
             resolve();
           });
         });
-        this.child = null;
+        this.childProcess = null;
       }
     };
   }
@@ -1117,9 +1129,16 @@ async function runVisualScenario(options) {
         console.log(`\u{1F4E6} [Mock IPC] Applying ${mergedMocks.length} mocks`);
         previewDriver.mockRegistry.setBatch(mergedMocks);
       }
+      if (scenario.mockRoutes && scenario.mockRoutes.length > 0) {
+        console.log(`\u{1F310} [Mock Network] Queuing ${scenario.mockRoutes.length} route mock(s)`);
+        await previewDriver.setupRouteMocks(scenario.mockRoutes);
+      }
       const res = await previewDriver.start(currentViewport);
       page = res.page;
       context = res.context;
+      if (scenario.mockRoutes && scenario.mockRoutes.length > 0) {
+        await previewDriver.setupRouteMocks(scenario.mockRoutes);
+      }
     }
     consoleTracker.attach(page);
     console.log(`\u{1F50D} [Console Tracker] Attached \u2014 errors and warnings will be captured
@@ -1265,6 +1284,25 @@ async function runVisualScenario(options) {
         console.log(`\u{1F4E6} [Mock IPC] Set ${action} -> ${typeof data === "string" ? data : JSON.stringify(data).slice(0, 80)}...`);
         await previewDriver.updateMockIpc(action, data, mockOptions);
       },
+      setMockRoute: async (url, body, routeOptions) => {
+        if (targetMode === "desktop") {
+          console.log(`\u26A0\uFE0F [Mock Route] setMockRoute ignored in desktop mode`);
+          return;
+        }
+        if (!previewDriver) {
+          console.log(`\u26A0\uFE0F [Mock Route] PreviewDriver not available`);
+          return;
+        }
+        console.log(`\u{1F310} [Mock Route] Intercepting ${routeOptions?.method || "ALL"} ${url} -> ${routeOptions?.status ?? 200}`);
+        await previewDriver.addRouteMock({
+          url,
+          body,
+          method: routeOptions?.method,
+          status: routeOptions?.status,
+          delayMs: routeOptions?.delayMs,
+          headers: routeOptions?.headers
+        });
+      },
       getConsoleErrors: () => consoleTracker.getErrors(),
       getConsoleWarnings: () => consoleTracker.getWarnings(),
       hasConsoleErrors: () => consoleTracker.hasErrors,
@@ -1464,17 +1502,24 @@ async function isPortResponding(url) {
     return false;
   }
 }
+async function detectActiveDevServer() {
+  for (const port of CANDIDATE_PORTS) {
+    const url = `http://localhost:${port}`;
+    if (await isPortResponding(url)) {
+      return url;
+    }
+  }
+  return null;
+}
 async function runQuickSnap(options) {
   let targetUrl = options.url;
   let useStaticPreview = false;
   let wwwrootDir;
   if (!targetUrl && !options.start) {
-    if (await isPortResponding("http://localhost:5173")) {
-      targetUrl = "http://localhost:5173";
-      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:5173`);
-    } else if (await isPortResponding("http://localhost:3000")) {
-      targetUrl = "http://localhost:3000";
-      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:3000`);
+    const activeUrl = await detectActiveDevServer();
+    if (activeUrl) {
+      targetUrl = activeUrl;
+      console.log(`\u{1F310} [Quick Snap] Detected active dev server on ${targetUrl}`);
     } else {
       const candidateDir = resolveWwwrootDir();
       if (fs7.existsSync(candidateDir) && fs7.existsSync(path7.join(candidateDir, "index.html"))) {
@@ -1483,7 +1528,7 @@ async function runQuickSnap(options) {
         console.log(`\u{1F4E6} [Quick Snap] No active server found. Detected built static directory at "${candidateDir}". Launching static preview...`);
       } else {
         console.error(`
-\u274C [Quick Snap] No active server found on http://localhost:5173 or :3000, and no static build found.`);
+\u274C [Quick Snap] No active server found on common ports (${CANDIDATE_PORTS.join(", ")}), and no static build found.`);
         console.log(`\u{1F4A1} Suggested actions:`);
         console.log(`   1. Pass a start command:  npx agent-lens snap --start="npm run dev"`);
         console.log(`   2. Specify your URL:      npx agent-lens snap --url=http://localhost:8080`);
@@ -1565,7 +1610,7 @@ async function runQuickSnap(options) {
 `);
   return result.success && result.consoleErrors === 0;
 }
-var PRESET_MAP;
+var PRESET_MAP, CANDIDATE_PORTS;
 var init_snap = __esm({
   "src/features/snap/snap.ts"() {
     "use strict";
@@ -1582,12 +1627,14 @@ var init_snap = __esm({
       tablet: { name: "tablet", width: 768, height: 1024 },
       "full-hd": VIEWPORT_PRESETS.FULL_HD
     };
+    CANDIDATE_PORTS = [5173, 3e3, 4321, 4200, 8080, 8e3, 3001];
   }
 });
 
 // src/app/cli.ts
 import path8 from "path";
 import fs8 from "fs";
+import { execSync } from "child_process";
 import { createJiti } from "jiti";
 var require_cli = __commonJS({
   "src/app/cli.ts"() {
@@ -1651,15 +1698,19 @@ var require_cli = __commonJS({
       } else if (arg.startsWith("--selector=")) {
         options.selector = arg.split("=")[1];
       } else if (arg.startsWith("--viewports=")) {
-        options.viewports = arg.split("=")[1].split(",").map((v) => v.trim()).filter(Boolean);
+        const raw = arg.slice("--viewports=".length);
+        options.viewports = raw.split(",").map((v) => v.trim()).filter(Boolean);
       } else if (arg.startsWith("--wait=")) {
-        options.waitMs = parseInt(arg.split("=")[1], 10);
+        options.waitMs = parseInt(arg.slice("--wait=".length), 10);
       } else if (arg.startsWith("--name=")) {
-        options.name = arg.split("=")[1];
-      } else if (arg.startsWith("--exe=") || arg.startsWith("--executable=")) {
-        options.exe = arg.split("=")[1];
+        options.name = arg.slice("--name=".length);
+      } else if (arg.startsWith("--exe=")) {
+        options.exe = arg.slice("--exe=".length);
+      } else if (arg.startsWith("--executable=")) {
+        options.exe = arg.slice("--executable=".length);
       } else if (arg.startsWith("--clean=") || arg.startsWith("--cleanup=")) {
-        const rawPaths = arg.split("=")[1];
+        const prefix = arg.startsWith("--clean=") ? "--clean=" : "--cleanup=";
+        const rawPaths = arg.slice(prefix.length);
         options.clean = rawPaths.split(",").map((p) => p.trim()).filter(Boolean);
       } else if (arg.startsWith("--dir=")) {
         options.dir = arg.split("=")[1];
@@ -1845,7 +1896,6 @@ export default [
         const buildCmd = typeof options.build === "string" ? options.build : fileConfig.buildCommand || "npm run build";
         console.log(`
 \u{1F528} [Build] Running build process: "${buildCmd}"...`);
-        const { execSync } = __require("child_process");
         try {
           execSync(buildCmd, { stdio: "inherit", cwd: options.startCwd || process.cwd() });
         } catch (e) {