@_deep4wee/agent-lens 1.0.1 → 1.1.0

package/dist/cli.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -26,6 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/app/cli.ts
 var import_path8 = __toESM(require("path"));
 var import_fs8 = __toESM(require("fs"));
+var import_child_process3 = require("child_process");
 
 // src/features/runner/runner.ts
 var import_path6 = __toESM(require("path"));
@@ -182,9 +182,9 @@ var VisualReporter = class {
       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 = "";
@@ -201,8 +201,8 @@ var VisualReporter = class {
 | :--- | :--- | :--- | :--- |
 `;
         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 += `
@@ -291,7 +291,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).
@@ -316,8 +318,6 @@ ${consoleSections}
 var ConsoleTracker = class {
   entries = [];
   attached = false;
-  /**
-   */
   attach(page) {
     if (this.attached) return;
     this.attached = true;
@@ -386,8 +386,6 @@ var ConsoleTracker = class {
         return "log";
     }
   }
-  /**
-   */
   isIgnoredWarning(text) {
     const ignoredPatterns = [
       "findDOMNode is deprecated",
@@ -412,8 +410,28 @@ var import_fs3 = __toESM(require("fs"));
 
 // src/shared/lib/playwrightLoader.ts
 var import_playwright = require("playwright");
+var chromium = new Proxy(import_playwright.chromium, {
+  get(target, prop, receiver) {
+    if (prop === "launch") {
+      return async (...args2) => {
+        try {
+          return await target.launch(...args2);
+        } 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;
+  }
+});
 
 // src/shared/drivers/desktopDriver.ts
+var import_tree_kill = __toESM(require("tree-kill"));
 var DesktopDriver = class {
   port;
   executablePath;
@@ -487,6 +505,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,
@@ -495,6 +518,16 @@ ${this.processStderr.trim() || "(no stderr output)"}`
       this.processStderr = "";
       this.processExited = false;
       this.exitCode = null;
+      this.childProcess = (0, import_child_process.spawn)(resolvedExe, finalArgs, {
+        env: mergedEnv,
+        cwd: this.cwd || import_path3.default.dirname(resolvedExe),
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: false
+      });
+      ;
+      this.processStderr = "";
+      this.processExited = false;
+      this.exitCode = null;
       this.childProcess = (0, import_child_process.spawn)(resolvedExe, this.args, {
         env: mergedEnv,
         cwd: this.cwd || import_path3.default.dirname(resolvedExe),
@@ -517,7 +550,7 @@ ${this.processStderr.trim() || "(no stderr output)"}`
       console.log(`[DesktopDriver] Attached to already running process on port ${this.port}`);
     }
     console.log(`[DesktopDriver] Connecting Playwright CDP to http://127.0.0.1:${this.port}...`);
-    this.browser = await import_playwright.chromium.connectOverCDP(`http://127.0.0.1:${this.port}`);
+    this.browser = await chromium.connectOverCDP(`http://127.0.0.1:${this.port}`);
     const contexts = this.browser.contexts();
     this.context = contexts[0] || await this.browser.newContext();
     const pages = this.context.pages();
@@ -538,16 +571,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) {
-          (0, import_child_process.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) => {
+        (0, import_tree_kill.default)(pid, "SIGTERM", () => resolve());
+      });
       this.childProcess = null;
     }
   }
@@ -628,62 +657,65 @@ 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');
     })();
+        
   `;
 }
 
 // src/shared/lib/config.ts
-var import_fs4 = __toESM(require("fs"));
 var import_path4 = __toESM(require("path"));
+var import_fs4 = __toESM(require("fs"));
 function loadConfig(cwd = process.cwd()) {
-  const configPath = import_path4.default.join(cwd, "agent-lens.json");
-  if (import_fs4.default.existsSync(configPath)) {
+  const jsonConfigPath = import_path4.default.join(cwd, "agent-lens.json");
+  if (import_fs4.default.existsSync(jsonConfigPath)) {
     try {
-      const raw = import_fs4.default.readFileSync(configPath, "utf8");
+      const raw = import_fs4.default.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 = import_path4.default.join(cwd, "package.json");
-  if (import_fs4.default.existsSync(pkgPath)) {
+  const packageJsonPath = import_path4.default.join(cwd, "package.json");
+  if (import_fs4.default.existsSync(packageJsonPath)) {
     try {
-      const raw = import_fs4.default.readFileSync(pkgPath, "utf8");
+      const raw = import_fs4.default.readFileSync(packageJsonPath, "utf-8");
       const pkg = JSON.parse(raw);
       if (pkg.agentLens && typeof pkg.agentLens === "object") {
         return pkg.agentLens;
@@ -693,78 +725,60 @@ function loadConfig(cwd = process.cwd()) {
   }
   return {};
 }
-function resolveWwwrootDir(customPath, cwd = process.cwd()) {
-  if (customPath) {
-    return import_path4.default.resolve(cwd, customPath);
+function detectStartCwd(providedCwd) {
+  if (providedCwd) {
+    const resolved = import_path4.default.resolve(process.cwd(), providedCwd);
+    if (import_fs4.default.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 = import_path4.default.resolve(cwd, rel);
-    if (import_fs4.default.existsSync(candidate) && import_fs4.default.existsSync(import_path4.default.join(candidate, "index.html"))) {
-      return candidate;
+  const rootPkgPath = import_path4.default.join(process.cwd(), "package.json");
+  let rootHasDevScript = false;
+  if (import_fs4.default.existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(import_fs4.default.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 = import_path4.default.resolve(cwd, rel);
-    if (import_fs4.default.existsSync(candidate)) {
-      return candidate;
+  const candidates = ["Frontend", "frontend", "client", "web", "ui", "apps/web", "src/frontend"];
+  for (const candidate of candidates) {
+    const candidatePkg = import_path4.default.join(process.cwd(), candidate, "package.json");
+    if (import_fs4.default.existsSync(candidatePkg)) {
+      return `./${candidate}`;
     }
   }
-  return import_path4.default.resolve(cwd, "dist");
+  return void 0;
 }
-function detectStartCwd(customCwd, rootCwd = process.cwd()) {
-  if (customCwd) {
-    return import_path4.default.resolve(rootCwd, customCwd);
-  }
-  const subdirectories = ["Frontend", "frontend", "client", "web", "ui", "app"];
-  for (const sub of subdirectories) {
-    const subPkg = import_path4.default.join(rootCwd, sub, "package.json");
-    if (import_fs4.default.existsSync(subPkg)) {
-      try {
-        const json = JSON.parse(import_fs4.default.readFileSync(subPkg, "utf8"));
-        if (json.scripts && (json.scripts.dev || json.scripts.start || json.scripts.build)) {
-          return import_path4.default.join(rootCwd, sub);
-        }
-      } catch {
-      }
+function resolveWwwrootDir(customDir) {
+  if (customDir) {
+    return import_path4.default.resolve(process.cwd(), customDir);
+  }
+  const candidates = [
+    "dist",
+    "build",
+    "out",
+    "wwwroot",
+    "Frontend/dist",
+    "frontend/dist",
+    "client/dist"
+  ];
+  for (const c of candidates) {
+    const candidatePath = import_path4.default.resolve(process.cwd(), c);
+    if (import_fs4.default.existsSync(candidatePath) && import_fs4.default.existsSync(import_path4.default.join(candidatePath, "index.html"))) {
+      return candidatePath;
     }
   }
-  return rootCwd;
-}
-function findDeepIndexHtmlDir(dir, maxDepth, currentDepth = 0) {
-  if (currentDepth > maxDepth || !import_fs4.default.existsSync(dir)) return null;
-  try {
-    const entries = import_fs4.default.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 = import_path4.default.join(dir, entry.name);
-        if (entry.name === "wwwroot" && import_fs4.default.existsSync(import_path4.default.join(subDir, "index.html"))) {
-          return subDir;
-        }
-        const found = findDeepIndexHtmlDir(subDir, maxDepth, currentDepth + 1);
-        if (found) return found;
-      }
+  for (const c of candidates) {
+    const candidatePath = import_path4.default.resolve(process.cwd(), c);
+    if (import_fs4.default.existsSync(candidatePath)) {
+      return candidatePath;
     }
-  } catch {
-    return null;
   }
-  return null;
+  return import_path4.default.resolve(process.cwd(), "dist");
 }
 
 // src/shared/drivers/previewDriver.ts
@@ -791,6 +805,7 @@ var PreviewDriver = class {
   serverPort = 0;
   options;
   _baseUrl = "";
+  initialRouteMocks = [];
   mockRegistry;
   constructor(options2) {
     this.options = options2 || {};
@@ -847,7 +862,7 @@ var PreviewDriver = class {
       this._baseUrl = targetUrl;
       console.log(`\u{1F310} [PreviewDriver] Connecting directly to live URL: ${targetUrl}`);
     }
-    this.browser = await import_playwright.chromium.launch({
+    this.browser = await chromium.launch({
       headless: !this.options.headed,
       args: ["--no-sandbox", "--disable-setuid-sandbox"]
     });
@@ -860,9 +875,41 @@ var PreviewDriver = class {
       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, options2) {
     if (!this.page) {
       throw new Error("PreviewDriver not started. Call start() first.");
@@ -907,104 +954,75 @@ var PreviewDriver = class {
 
 // src/shared/lib/processManager.ts
 var import_child_process2 = require("child_process");
-var import_tree_kill = __toESM(require("tree-kill"));
+var import_tree_kill2 = __toESM(require("tree-kill"));
 var 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, options2) {
-    this.stderrOutput = "";
-    this.stdoutOutput = "";
-    this.hasExited = false;
-    this.exitCode = null;
     const cwd = options2?.cwd || process.cwd();
-    const env = { ...process.env, ...options2?.env };
     console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
-    this.child = (0, import_child_process2.spawn)(command, {
+    this.childProcess = (0, import_child_process2.spawn)(command, {
       cwd,
-      env,
-      shell: options2?.shell ?? true,
+      env: { ...process.env, ...options2?.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) => {
-      (0, import_tree_kill.default)(pid, "SIGKILL", (err) => {
+      (0, import_tree_kill2.default)(pid, "SIGTERM", (err) => {
         if (err) {
-          if (process.platform === "win32") {
-            try {
-              (0, import_child_process2.spawn)("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
-            } catch {
-            }
+          try {
+            (0, import_tree_kill2.default)(pid, "SIGKILL");
+          } catch {
           }
         }
         resolve();
       });
     });
-    this.child = null;
+    this.childProcess = null;
   }
 };
 
@@ -1075,9 +1093,16 @@ async function runVisualScenario(options2) {
         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
@@ -1223,6 +1248,25 @@ async function runVisualScenario(options2) {
         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,
@@ -1415,6 +1459,7 @@ function parseViewportPresets(raw) {
   }
   return presets.length > 0 ? presets : [VIEWPORT_PRESETS.DEFAULT, PRESET_MAP.mobile];
 }
+var CANDIDATE_PORTS = [5173, 3e3, 4321, 4200, 8080, 8e3, 3001];
 async function isPortResponding(url) {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(800) });
@@ -1423,17 +1468,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(options2) {
   let targetUrl = options2.url;
   let useStaticPreview = false;
   let wwwrootDir;
   if (!targetUrl && !options2.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 (import_fs7.default.existsSync(candidateDir) && import_fs7.default.existsSync(import_path7.default.join(candidateDir, "index.html"))) {
@@ -1442,7 +1494,7 @@ async function runQuickSnap(options2) {
         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`);
@@ -1583,15 +1635,19 @@ for (const arg of effectiveArgs) {
   } 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];
@@ -1777,9 +1833,8 @@ async function main() {
     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() });
+      (0, import_child_process3.execSync)(buildCmd, { stdio: "inherit", cwd: options.startCwd || process.cwd() });
     } catch (e) {
       console.error(`\u274C Build failed: ${buildCmd}`);
       process.exit(1);