@_deep4wee/agent-lens 1.0.1 → 1.2.0

package/dist/cli.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -24,18 +23,102 @@ 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_path13 = __toESM(require("path"));
+var import_fs12 = __toESM(require("fs"));
+var import_child_process2 = require("child_process");
+var import_jiti2 = require("jiti");
+
+// src/shared/lib/config.ts
+var import_path = __toESM(require("path"));
+var import_fs = __toESM(require("fs"));
+function loadConfig(cwd = process.cwd()) {
+  const jsonConfigPath = import_path.default.join(cwd, "agent-lens.json");
+  if (import_fs.default.existsSync(jsonConfigPath)) {
+    try {
+      const raw = import_fs.default.readFileSync(jsonConfigPath, "utf-8");
+      return JSON.parse(raw);
+    } catch (e) {
+      console.warn(`\u26A0\uFE0F [Config] Failed to parse agent-lens.json: ${e.message}`);
+    }
+  }
+  const packageJsonPath = import_path.default.join(cwd, "package.json");
+  if (import_fs.default.existsSync(packageJsonPath)) {
+    try {
+      const raw = import_fs.default.readFileSync(packageJsonPath, "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.agentLens && typeof pkg.agentLens === "object") {
+        return pkg.agentLens;
+      }
+    } catch {
+    }
+  }
+  return {};
+}
+function detectStartCwd(providedCwd) {
+  if (providedCwd) {
+    const resolved = import_path.default.resolve(process.cwd(), providedCwd);
+    if (import_fs.default.existsSync(resolved)) {
+      return providedCwd;
+    }
+  }
+  const rootPkgPath = import_path.default.join(process.cwd(), "package.json");
+  let rootHasDevScript = false;
+  if (import_fs.default.existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(import_fs.default.readFileSync(rootPkgPath, "utf-8"));
+      rootHasDevScript = Boolean(rootPkg.scripts?.dev || rootPkg.scripts?.start);
+    } catch {
+    }
+  }
+  if (rootHasDevScript) {
+    return void 0;
+  }
+  const candidates = ["Frontend", "frontend", "client", "web", "ui", "apps/web", "src/frontend"];
+  for (const candidate of candidates) {
+    const candidatePkg = import_path.default.join(process.cwd(), candidate, "package.json");
+    if (import_fs.default.existsSync(candidatePkg)) {
+      return `./${candidate}`;
+    }
+  }
+  return void 0;
+}
+function resolveWwwrootDir(customDir) {
+  if (customDir) {
+    return import_path.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_path.default.resolve(process.cwd(), c);
+    if (import_fs.default.existsSync(candidatePath) && import_fs.default.existsSync(import_path.default.join(candidatePath, "index.html"))) {
+      return candidatePath;
+    }
+  }
+  for (const c of candidates) {
+    const candidatePath = import_path.default.resolve(process.cwd(), c);
+    if (import_fs.default.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+  return import_path.default.resolve(process.cwd(), "dist");
+}
 
 // src/features/runner/runner.ts
-var import_path6 = __toESM(require("path"));
-var import_fs6 = __toESM(require("fs"));
+var import_path7 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
 
 // src/shared/api/dsl.ts
 var VIEWPORT_PRESETS = {
-  /** Minimum supported window size (e.g., ) */
+  /** Minimum supported window size */
   MIN_SUPPORTED: { name: "min-supported", width: 1024, height: 768 },
-  /** Standard default window size (e.g., ) */
+  /** Standard default window size */
   DEFAULT: { name: "default", width: 1200, height: 800 },
   /** Wide screen for checking grids and tables */
   WIDE: { name: "wide", width: 1600, height: 900 },
@@ -47,16 +130,16 @@ function defineVisualTest(scenario) {
 }
 
 // src/features/capture/capture.ts
-var import_fs = __toESM(require("fs"));
-var import_path = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
 var CaptureEngine = class {
   outputDir;
   currentStepIndex = 0;
   recordedSnapshots = [];
   constructor(outputDir) {
     this.outputDir = outputDir;
-    if (!import_fs.default.existsSync(this.outputDir)) {
-      import_fs.default.mkdirSync(this.outputDir, { recursive: true });
+    if (!import_fs2.default.existsSync(this.outputDir)) {
+      import_fs2.default.mkdirSync(this.outputDir, { recursive: true });
     }
   }
   getSnapshots() {
@@ -67,17 +150,17 @@ var CaptureEngine = class {
   }
   /**
    */
-  async takeSnapshot(page, name, viewport, options2) {
+  async takeSnapshot(page, name, viewport, options) {
     this.currentStepIndex += 1;
     const paddedIndex = String(this.currentStepIndex).padStart(2, "0");
     const sanitizedName = name.replace(/[^a-zA-Z0-9_\-]/g, "_");
     const fileName = `${paddedIndex}_${sanitizedName}_${viewport.width}x${viewport.height}.png`;
-    const filePath = import_path.default.join(this.outputDir, fileName);
-    if (options2?.selector) {
-      const element = await page.waitForSelector(options2.selector, { timeout: 5e3 });
+    const filePath = import_path2.default.join(this.outputDir, fileName);
+    if (options?.selector) {
+      const element = await page.waitForSelector(options.selector, { timeout: 5e3 });
       await element.screenshot({ path: filePath });
     } else {
-      await page.screenshot({ path: filePath, fullPage: options2?.fullPage ?? false });
+      await page.screenshot({ path: filePath, fullPage: options?.fullPage ?? false });
     }
     const metadata = {
       index: this.currentStepIndex,
@@ -87,20 +170,20 @@ var CaptureEngine = class {
       relativeUri: `./${fileName}`,
       viewport,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      selector: options2?.selector
+      selector: options?.selector
     };
     this.recordedSnapshots.push(metadata);
     return metadata;
   }
   /**
    */
-  async takeBurst(page, name, viewport, options2) {
+  async takeBurst(page, name, viewport, options) {
     this.currentStepIndex += 1;
     const stepIndex = this.currentStepIndex;
     const paddedIndex = String(stepIndex).padStart(2, "0");
     const sanitizedName = name.replace(/[^a-zA-Z0-9_\-]/g, "_");
-    const duration = Math.max(options2.durationMs, 50);
-    const interval = Math.max(options2.intervalMs ?? 80, 20);
+    const duration = Math.max(options.durationMs, 50);
+    const interval = Math.max(options.intervalMs ?? 80, 20);
     const totalFrames = Math.ceil(duration / interval);
     const burstSnapshots = [];
     const burstGroup = sanitizedName;
@@ -108,9 +191,9 @@ var CaptureEngine = class {
       const elapsedMs = frame * interval;
       const paddedFrame = String(frame + 1).padStart(2, "0");
       const fileName = `${paddedIndex}_burst_${sanitizedName}_f${paddedFrame}_${elapsedMs}ms.png`;
-      const filePath = import_path.default.join(this.outputDir, fileName);
-      if (options2.selector) {
-        const element = await page.$(options2.selector);
+      const filePath = import_path2.default.join(this.outputDir, fileName);
+      if (options.selector) {
+        const element = await page.$(options.selector);
         if (element) {
           await element.screenshot({ path: filePath });
         } else {
@@ -130,7 +213,7 @@ var CaptureEngine = class {
         isBurstFrame: true,
         burstGroup,
         frameIndex: frame + 1,
-        selector: options2.selector
+        selector: options.selector
       };
       burstSnapshots.push(meta);
       this.recordedSnapshots.push(meta);
@@ -143,8 +226,8 @@ var CaptureEngine = class {
 };
 
 // src/features/reporter/reporter.ts
-var import_fs2 = __toESM(require("fs"));
-var import_path2 = __toESM(require("path"));
+var import_fs3 = __toESM(require("fs"));
+var import_path3 = __toESM(require("path"));
 var VisualReporter = class {
   static generateReport(data) {
     const {
@@ -156,8 +239,8 @@ var VisualReporter = class {
       targetMode,
       durationMs
     } = data;
-    const manifestPath = import_path2.default.join(outputDir, "manifest.json");
-    const reportPath = import_path2.default.join(outputDir, "report.md");
+    const manifestPath = import_path3.default.join(outputDir, "manifest.json");
+    const reportPath = import_path3.default.join(outputDir, "report.md");
     const manifest = {
       scenarioId: scenario.id,
       title: scenario.title,
@@ -172,7 +255,7 @@ var VisualReporter = class {
       errors: consoleErrors,
       warnings: consoleWarnings
     };
-    import_fs2.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    import_fs3.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
     const rows = [];
     const regularSnapshots = snapshots.filter((s) => !s.isBurstFrame);
     const burstGroups = /* @__PURE__ */ new Map();
@@ -182,9 +265,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 +284,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 += `
@@ -265,6 +348,17 @@ ${err.stack}
       if (consoleWarnings.length > 20) {
         consoleSections += `
 *...and ${consoleWarnings.length - 20} more warnings (full list in manifest.json)*
+`;
+      }
+    }
+    let pluginSections = "";
+    if (data.customSections && data.customSections.length > 0) {
+      for (const sec of data.customSections) {
+        pluginSections += `
+## ${sec.title}
+
+${sec.content}
+
 `;
       }
     }
@@ -287,18 +381,21 @@ ${rows.join("\n")}
 
 ${burstSections}
 ${consoleSections}
+${pluginSections}
 ---
 
 ## \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).
 - [ ] **Localization**: Verify that there are no raw i18n keys (text with dots like \`sidebar.home\` instead of "Home").
 
 `;
-    import_fs2.default.writeFileSync(reportPath, reportContent, "utf-8");
+    import_fs3.default.writeFileSync(reportPath, reportContent, "utf-8");
     return reportPath;
   }
   static getHealthStatus(errors, warnings) {
@@ -316,8 +413,6 @@ ${consoleSections}
 var ConsoleTracker = class {
   entries = [];
   attached = false;
-  /**
-   */
   attach(page) {
     if (this.attached) return;
     this.attached = true;
@@ -386,8 +481,6 @@ var ConsoleTracker = class {
         return "log";
     }
   }
-  /**
-   */
   isIgnoredWarning(text) {
     const ignoredPatterns = [
       "findDOMNode is deprecated",
@@ -404,368 +497,32 @@ var ConsoleTracker = class {
   }
 };
 
-// src/shared/drivers/desktopDriver.ts
-var import_child_process = require("child_process");
+// src/shared/drivers/previewDriver.ts
 var import_http = __toESM(require("http"));
-var import_path3 = __toESM(require("path"));
-var import_fs3 = __toESM(require("fs"));
+var import_fs4 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
 
 // src/shared/lib/playwrightLoader.ts
 var import_playwright = require("playwright");
-
-// src/shared/drivers/desktopDriver.ts
-var DesktopDriver = class {
-  port;
-  executablePath;
-  autoLaunch;
-  args;
-  env;
-  cwd;
-  childProcess = null;
-  browser = null;
-  context = null;
-  page = null;
-  processStderr = "";
-  processExited = false;
-  exitCode = null;
-  constructor(options2) {
-    this.port = options2?.port || 9222;
-    this.autoLaunch = options2?.autoLaunch ?? true;
-    this.executablePath = options2?.executablePath;
-    this.args = options2?.args || [];
-    this.env = options2?.env || {};
-    this.cwd = options2?.cwd;
-  }
-  async isPortAvailable() {
-    return new Promise((resolve) => {
-      const req = import_http.default.get(`http://127.0.0.1:${this.port}/json/version`, (res) => {
-        resolve(res.statusCode === 200);
-      });
-      req.on("error", () => resolve(false));
-      req.setTimeout(800, () => {
-        req.destroy();
-        resolve(false);
-      });
-    });
-  }
-  async waitForPort(timeoutMs = 25e3) {
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeoutMs) {
-      if (this.processExited) {
-        throw new Error(
-          `[DesktopDriver] Process terminated prematurely with exit code ${this.exitCode}.
-Stderr: ${this.processStderr.trim() || "(none)"}`
-        );
-      }
-      if (await this.isPortAvailable()) {
-        return;
-      }
-      await new Promise((r) => setTimeout(r, 400));
-    }
-    throw new Error(
-      `Timeout waiting for WebView2/Chromium CDP port ${this.port}. Last stderr:
-${this.processStderr.trim() || "(no stderr output)"}`
-    );
-  }
-  async start(initialViewport = { width: 1200, height: 800 }) {
-    const alreadyRunning = await this.isPortAvailable();
-    if (!alreadyRunning) {
-      if (!this.autoLaunch) {
-        throw new Error(
-          `App is not running on port ${this.port} and autoLaunch is false. Start app with WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=${this.port}`
-        );
-      }
-      if (!this.executablePath) {
-        throw new Error(
-          `[DesktopDriver] No executablePath provided and nothing is running on port ${this.port}. Specify --exe=<path> in CLI or executablePath in config.`
-        );
-      }
-      const resolvedExe = import_path3.default.resolve(process.cwd(), this.executablePath);
-      if (!import_fs3.default.existsSync(resolvedExe)) {
-        throw new Error(
-          `[DesktopDriver] Desktop executable not found at: ${resolvedExe}. Please build your native project first.`
-        );
-      }
-      console.log(`[DesktopDriver] Launching: ${resolvedExe}`);
-      const mergedEnv = {
-        ...process.env,
-        ...this.env,
-        WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: `--remote-debugging-port=${this.port}`
-      };
-      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),
-        stdio: ["ignore", "ignore", "pipe"],
-        detached: false
-      });
-      this.childProcess.stderr?.on("data", (chunk) => {
-        this.processStderr += chunk.toString();
-      });
-      this.childProcess.on("exit", (code) => {
-        this.processExited = true;
-        this.exitCode = code;
-      });
-      this.childProcess.on("error", (err) => {
-        console.error("[DesktopDriver] Failed to spawn process:", err);
-      });
-      console.log(`[DesktopDriver] Waiting for CDP debugging port on ${this.port}...`);
-      await this.waitForPort();
-    } else {
-      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}`);
-    const contexts = this.browser.contexts();
-    this.context = contexts[0] || await this.browser.newContext();
-    const pages = this.context.pages();
-    if (pages.length > 0) {
-      this.page = pages[0];
-    } else {
-      this.page = await this.context.waitForEvent("page", { timeout: 1e4 });
-    }
-    if (initialViewport) {
-      await this.page.setViewportSize(initialViewport).catch(() => {
-      });
-    }
-    return { page: this.page, context: this.context, browser: this.browser };
-  }
-  async stop() {
-    if (this.browser) {
-      await this.browser.close().catch(() => {
-      });
-      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 {
-      }
-      this.childProcess = null;
-    }
-  }
-};
-
-// src/shared/drivers/previewDriver.ts
-var import_http2 = __toESM(require("http"));
-var import_fs5 = __toESM(require("fs"));
-var import_path5 = __toESM(require("path"));
-
-// src/features/mock-ipc/mockIpc.ts
-var MockIpcRegistry = class {
-  mocks = /* @__PURE__ */ new Map();
-  set(action, data, options2) {
-    this.mocks.set(action, {
-      action,
-      data,
-      type: options2?.type ?? "SUCCESS",
-      delayMs: options2?.delayMs ?? 20
-    });
-  }
-  setBatch(entries) {
-    for (const entry of entries) {
-      this.set(entry.action, entry.data, { type: entry.type, delayMs: entry.delayMs });
-    }
-  }
-  remove(action) {
-    this.mocks.delete(action);
-  }
-  clear() {
-    this.mocks.clear();
-  }
-  get(action) {
-    return this.mocks.get(action) ?? null;
-  }
-  toSerializable() {
-    const result = {};
-    for (const [action, entry] of this.mocks.entries()) {
-      result[action] = {
-        data: entry.data,
-        type: entry.type ?? "SUCCESS",
-        delayMs: entry.delayMs ?? 20
-      };
-    }
-    return result;
-  }
-  get size() {
-    return this.mocks.size;
-  }
-};
-function generateMockIpcScript(registry) {
-  const mocksJson = JSON.stringify(registry.toSerializable());
-  return `
-    (() => {
-      const __mockTable = ${mocksJson};
-
-      window.__visualRunnerMocks = __mockTable;
-
-      // Generic IPC mock bridge for modern web applications
-      window.__mockIpc = {
-        invoke: (action, payload) => {
-          return new Promise((resolve, reject) => {
-            const mock = window.__visualRunnerMocks[action];
-
-            if (mock) {
-              setTimeout(() => {
-                if (mock.type === 'ERROR') {
-                  reject(new Error(mock.data));
-                } else {
-                  resolve(mock.data);
-                }
-              }, mock.delayMs || 20);
-            } else {
-              console.warn('[Mock IPC] No mock for action:', action, '\u2014 returning empty SUCCESS');
-              setTimeout(() => resolve(null), 20);
-            }
-          });
-        }
-      };
-
-      // Legacy fallback for generic window.external
-      if (!window.external) {
-        window.external = {};
-      }
-      
-      window.external.sendMessage = (msg) => {
+var chromium = new Proxy(import_playwright.chromium, {
+  get(target, prop, receiver) {
+    if (prop === "launch") {
+      return async (...args) => {
         try {
-          const parsed = JSON.parse(msg);
-          const action = parsed.Action || parsed.action;
-          const id = parsed.Id || parsed.id;
-
-          const mock = window.__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);
+          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");
           }
-        } catch (e) {
-          console.error('[Mock IPC] Failed to process legacy message:', e);
+          throw err;
         }
       };
-
-      window.external.receiveMessage = (callback) => {
-        window.__mockCallback = callback;
-      };
-
-      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');
-    })();
-  `;
-}
-
-// src/shared/lib/config.ts
-var import_fs4 = __toESM(require("fs"));
-var import_path4 = __toESM(require("path"));
-function loadConfig(cwd = process.cwd()) {
-  const configPath = import_path4.default.join(cwd, "agent-lens.json");
-  if (import_fs4.default.existsSync(configPath)) {
-    try {
-      const raw = import_fs4.default.readFileSync(configPath, "utf8");
-      return JSON.parse(raw);
-    } catch (e) {
-      console.warn(`\u26A0\uFE0F Warning: Failed to parse agent-lens.json:`, e);
-    }
-  }
-  const pkgPath = import_path4.default.join(cwd, "package.json");
-  if (import_fs4.default.existsSync(pkgPath)) {
-    try {
-      const raw = import_fs4.default.readFileSync(pkgPath, "utf8");
-      const pkg = JSON.parse(raw);
-      if (pkg.agentLens && typeof pkg.agentLens === "object") {
-        return pkg.agentLens;
-      }
-    } catch {
-    }
-  }
-  return {};
-}
-function resolveWwwrootDir(customPath, cwd = process.cwd()) {
-  if (customPath) {
-    return import_path4.default.resolve(cwd, customPath);
-  }
-  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 val = Reflect.get(target, prop, receiver);
+    return typeof val === "function" ? val.bind(target) : val;
   }
-  const foundDeepWwwroot = findDeepIndexHtmlDir(cwd, 4);
-  if (foundDeepWwwroot) {
-    return foundDeepWwwroot;
-  }
-  for (const rel of standardDirs) {
-    const candidate = import_path4.default.resolve(cwd, rel);
-    if (import_fs4.default.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  return import_path4.default.resolve(cwd, "dist");
-}
-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 {
-      }
-    }
-  }
-  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;
-      }
-    }
-  } catch {
-    return null;
-  }
-  return null;
-}
+});
 
 // src/shared/drivers/previewDriver.ts
 var MIME_TYPES = {
@@ -791,13 +548,12 @@ var PreviewDriver = class {
   serverPort = 0;
   options;
   _baseUrl = "";
-  mockRegistry;
-  constructor(options2) {
-    this.options = options2 || {};
+  initialRouteMocks = [];
+  constructor(options) {
+    this.options = options || {};
     if (!this.options.url) {
       this.options.wwwrootDir = resolveWwwrootDir(this.options.wwwrootDir);
     }
-    this.mockRegistry = new MockIpcRegistry();
   }
   get baseUrl() {
     return this._baseUrl;
@@ -805,25 +561,25 @@ var PreviewDriver = class {
   async start(initialViewport = { width: 1200, height: 800 }) {
     let targetUrl = this.options.url;
     if (!targetUrl) {
-      if (!import_fs5.default.existsSync(this.options.wwwrootDir)) {
+      if (!import_fs4.default.existsSync(this.options.wwwrootDir)) {
         throw new Error(`Directory not found at: ${this.options.wwwrootDir}. Please build your frontend project first or pass --url=<url>.`);
       }
       await new Promise((resolve, reject) => {
-        this.server = import_http2.default.createServer((req, res) => {
+        this.server = import_http.default.createServer((req, res) => {
           let reqUrl = req.url?.split("?")[0] || "/";
           if (reqUrl === "/") reqUrl = "/index.html";
-          let safePath = import_path5.default.normalize(import_path5.default.join(this.options.wwwrootDir, reqUrl));
+          let safePath = import_path4.default.normalize(import_path4.default.join(this.options.wwwrootDir, reqUrl));
           if (!safePath.startsWith(this.options.wwwrootDir)) {
             res.writeHead(403);
             return res.end("Forbidden");
           }
-          if (!import_fs5.default.existsSync(safePath) || import_fs5.default.statSync(safePath).isDirectory()) {
-            safePath = import_path5.default.join(this.options.wwwrootDir, "index.html");
+          if (!import_fs4.default.existsSync(safePath) || import_fs4.default.statSync(safePath).isDirectory()) {
+            safePath = import_path4.default.join(this.options.wwwrootDir, "index.html");
           }
-          const ext = import_path5.default.extname(safePath).toLowerCase();
+          const ext = import_path4.default.extname(safePath).toLowerCase();
           const contentType = MIME_TYPES[ext] || "application/octet-stream";
           try {
-            const content = import_fs5.default.readFileSync(safePath);
+            const content = import_fs4.default.readFileSync(safePath);
             res.writeHead(200, { "Content-Type": contentType });
             res.end(content);
           } catch (e) {
@@ -847,7 +603,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"]
     });
@@ -855,35 +611,41 @@ var PreviewDriver = class {
       viewport: initialViewport,
       deviceScaleFactor: 1
     });
-    if (this.mockRegistry.size > 0) {
-      const mockScript = generateMockIpcScript(this.mockRegistry);
-      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 updateMockIpc(action, data, options2) {
+  async addRouteMock(entry) {
     if (!this.page) {
-      throw new Error("PreviewDriver not started. Call start() first.");
+      this.initialRouteMocks.push(entry);
+      return;
     }
-    this.mockRegistry.set(action, data, options2);
-    await this.page.evaluate(
-      ({ action: action2, mock }) => {
-        if (!window.__visualRunnerMocks) {
-          window.__visualRunnerMocks = {};
-        }
-        window.__visualRunnerMocks[action2] = mock;
-      },
-      {
-        action,
-        mock: {
-          data,
-          type: options2?.type ?? "SUCCESS",
-          delayMs: options2?.delayMs ?? 20
-        }
+    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 stop() {
     if (this.context) {
@@ -906,133 +668,511 @@ var PreviewDriver = class {
 };
 
 // src/shared/lib/processManager.ts
-var import_child_process2 = require("child_process");
+var import_child_process = require("child_process");
 var import_tree_kill = __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)
-   */
-  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 };
+  childProcess = null;
+  isStopped = false;
+  async start(command, options) {
+    const cwd = options?.cwd || process.cwd();
     console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
-    this.child = (0, import_child_process2.spawn)(command, {
+    this.childProcess = (0, import_child_process.spawn)(command, {
       cwd,
-      env,
-      shell: options2?.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) => {
-      (0, import_tree_kill.default)(pid, "SIGKILL", (err) => {
+      (0, import_tree_kill.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_kill.default)(pid, "SIGKILL");
+          } catch {
           }
         }
         resolve();
       });
     });
-    this.child = null;
+    this.childProcess = null;
   }
 };
 
-// src/features/runner/runner.ts
-async function runVisualScenario(options2) {
-  const { scenario } = options2;
-  const targetMode = options2.targetMode || "preview";
-  const startTime = Date.now();
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  const artifactsRoot = options2.artifactsRoot || import_path6.default.resolve(process.cwd(), "artifacts");
-  if (options2.cleanArtifacts && import_fs6.default.existsSync(artifactsRoot)) {
-    console.log(`\u{1F9F9} [Clean Artifacts] Purging previous artifact runs in ${artifactsRoot}...`);
-    const entries = import_fs6.default.readdirSync(artifactsRoot, { withFileTypes: true });
-    for (const entry of entries) {
-      import_fs6.default.rmSync(import_path6.default.join(artifactsRoot, entry.name), { recursive: true, force: true });
+// src/shared/lib/pluginLoader.ts
+var import_path5 = __toESM(require("path"));
+var import_fs5 = __toESM(require("fs"));
+var import_jiti = require("jiti");
+function findPackageRoot() {
+  let cur = __dirname;
+  while (cur !== import_path5.default.dirname(cur)) {
+    const pkgPath = import_path5.default.join(cur, "package.json");
+    if (import_fs5.default.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(import_fs5.default.readFileSync(pkgPath, "utf-8"));
+        if (pkg.name === "@_deep4wee/agent-lens" || pkg.name === "agent-lens") {
+          return cur;
+        }
+      } catch {
+      }
     }
+    cur = import_path5.default.dirname(cur);
   }
-  const scenarioArtifactsDir = import_path6.default.join(artifactsRoot, `${scenario.id}_${timestamp}`);
-  if (!import_fs6.default.existsSync(scenarioArtifactsDir)) {
-    import_fs6.default.mkdirSync(scenarioArtifactsDir, { recursive: true });
+  return import_path5.default.resolve(__dirname, "..");
+}
+var PluginManager = class {
+  plugins = [];
+  jiti = (0, import_jiti.createJiti)(process.cwd());
+  register(plugin) {
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      return;
+    }
+    this.plugins.push(plugin);
+    console.log(`\u{1F50C} [Plugin] Registered: ${plugin.name}${plugin.version ? ` (v${plugin.version})` : ""}`);
+  }
+  async load(pluginSpec) {
+    if (typeof pluginSpec === "object" && pluginSpec !== null) {
+      this.register(pluginSpec);
+      return;
+    }
+    const pluginNameOrPath = pluginSpec.trim();
+    if (!pluginNameOrPath) return;
+    if (pluginNameOrPath.startsWith(".") || pluginNameOrPath.startsWith("/") || pluginNameOrPath.includes("/") || pluginNameOrPath.includes("\\")) {
+      const resolvedPath = import_path5.default.resolve(process.cwd(), pluginNameOrPath);
+      await this.loadFromFile(resolvedPath);
+      return;
+    }
+    const localCandidates = [
+      import_path5.default.resolve(process.cwd(), ".agent-lens", "plugins", `${pluginNameOrPath}.ts`),
+      import_path5.default.resolve(process.cwd(), ".agent-lens", "plugins", `${pluginNameOrPath}.js`),
+      import_path5.default.resolve(process.cwd(), "plugins", `${pluginNameOrPath}.ts`),
+      import_path5.default.resolve(process.cwd(), "plugins", `${pluginNameOrPath}.js`),
+      import_path5.default.resolve(process.cwd(), ".agent-lens", "plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.resolve(process.cwd(), ".agent-lens", "plugins", pluginNameOrPath, "index.js"),
+      import_path5.default.resolve(process.cwd(), "plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.resolve(process.cwd(), "plugins", pluginNameOrPath, "index.js")
+    ];
+    for (const candidate of localCandidates) {
+      if (import_fs5.default.existsSync(candidate)) {
+        await this.loadFromFile(candidate);
+        return;
+      }
+    }
+    const pkgRoot = findPackageRoot();
+    const builtInCandidates = [
+      import_path5.default.join(pkgRoot, "src", "plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.join(pkgRoot, "src", "plugins", pluginNameOrPath, "index.js"),
+      import_path5.default.join(pkgRoot, "dist", "plugins", pluginNameOrPath, "index.js"),
+      import_path5.default.join(pkgRoot, "plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.join(pkgRoot, "plugins", pluginNameOrPath, "index.js"),
+      import_path5.default.resolve(__dirname, "../../plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.resolve(__dirname, "../../plugins", pluginNameOrPath, "index.js"),
+      import_path5.default.resolve(__dirname, "../plugins", pluginNameOrPath, "index.ts"),
+      import_path5.default.resolve(__dirname, "../plugins", pluginNameOrPath, "index.js")
+    ];
+    for (const builtIn of builtInCandidates) {
+      if (import_fs5.default.existsSync(builtIn)) {
+        await this.loadFromFile(builtIn);
+        return;
+      }
+    }
+    try {
+      const mod = await this.jiti.import(pluginNameOrPath);
+      const plugin = mod.default || mod.plugin || mod;
+      if (plugin && plugin.name) {
+        this.register(plugin);
+      } else {
+        console.warn(`\u26A0\uFE0F [Plugin] Package "${pluginNameOrPath}" did not export a valid AgentLensPlugin.`);
+      }
+    } catch (err) {
+      console.warn(`\u26A0\uFE0F [Plugin] Could not load plugin '${pluginNameOrPath}': ${err.message}`);
+    }
+  }
+  async loadFromFile(filePath) {
+    if (!import_fs5.default.existsSync(filePath)) {
+      console.warn(`\u26A0\uFE0F [Plugin] Plugin file not found: ${filePath}`);
+      return;
+    }
+    try {
+      const mod = await this.jiti.import(filePath);
+      const plugin = mod.default || mod.plugin || mod;
+      if (plugin && plugin.name) {
+        this.register(plugin);
+      } else {
+        console.warn(`\u26A0\uFE0F [Plugin] File "${filePath}" does not export a valid AgentLensPlugin by default.`);
+      }
+    } catch (err) {
+      console.error(`\u274C [Plugin] Failed to import plugin from ${filePath}:`, err.message);
+    }
+  }
+  async loadAll(specs) {
+    for (const spec of specs) {
+      await this.load(spec);
+    }
+  }
+  async runSetup(hookContext) {
+    for (const p of this.plugins) {
+      if (p.setup) await p.setup(hookContext);
+    }
+  }
+  async launchSession(options, hookContext) {
+    for (const p of this.plugins) {
+      if (p.launchSession) {
+        const session = await p.launchSession(options, hookContext);
+        if (session) {
+          return session;
+        }
+      }
+    }
+    return void 0;
+  }
+  async runOnContextCreated(context, hookContext) {
+    for (const p of this.plugins) {
+      if (p.onContextCreated) await p.onContextCreated(context, hookContext);
+    }
+  }
+  async runOnPageCreated(page, context, hookContext) {
+    for (const p of this.plugins) {
+      if (p.onPageCreated) await p.onPageCreated(page, context, hookContext);
+    }
+  }
+  async extendContext(ctx, page, hookContext) {
+    for (const p of this.plugins) {
+      if (p.extendContext) {
+        const extensions = await p.extendContext(ctx, page, hookContext);
+        if (extensions && typeof extensions === "object") {
+          Object.assign(ctx, extensions);
+        }
+      }
+    }
+  }
+  async runOnAfterRun(reportData, hookContext) {
+    for (const p of this.plugins) {
+      if (p.onAfterRun) await p.onAfterRun(reportData, hookContext);
+    }
+  }
+  async runTeardown(hookContext) {
+    for (const p of this.plugins) {
+      if (p.teardown) {
+        try {
+          await p.teardown(hookContext);
+        } catch (e) {
+          console.error(`\u26A0\uFE0F [Plugin] Error in ${p.name}.teardown:`, e.message);
+        }
+      }
+    }
+  }
+  get loadedPlugins() {
+    return [...this.plugins];
+  }
+};
+
+// src/features/runner/lib/navigation.ts
+function createNavigator(page, baseUrl, targetUrl) {
+  return async (route) => {
+    if (route.startsWith("http://") || route.startsWith("https://")) {
+      await page.goto(route, { waitUntil: "domcontentloaded" });
+      await page.waitForTimeout(300);
+      return;
+    }
+    if (route.startsWith("#")) {
+      await page.evaluate((r) => {
+        window.location.hash = r;
+      }, route);
+      await page.waitForTimeout(300);
+      return;
+    }
+    if (baseUrl && targetUrl) {
+      try {
+        const fullUrl = new URL(route, baseUrl).toString();
+        await page.goto(fullUrl, { waitUntil: "domcontentloaded" });
+        await page.waitForTimeout(300);
+        return;
+      } catch {
+      }
+    }
+    const routePath = route.startsWith("/") ? route : `/${route}`;
+    await page.evaluate((r) => {
+      if (window.location.hash !== void 0) {
+        window.location.hash = r;
+      }
+    }, routePath);
+    await page.waitForTimeout(300);
+  };
+}
+
+// src/features/runner/lib/artifactsSync.ts
+var import_fs6 = __toESM(require("fs"));
+var import_path6 = __toESM(require("path"));
+function syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots) {
+  try {
+    const latestDir = import_path6.default.join(artifactsRoot, "latest");
+    if (import_fs6.default.existsSync(latestDir)) {
+      import_fs6.default.rmSync(latestDir, { recursive: true, force: true });
+    }
+    import_fs6.default.mkdirSync(latestDir, { recursive: true });
+    if (import_fs6.default.existsSync(reportPath)) {
+      import_fs6.default.copyFileSync(reportPath, import_path6.default.join(latestDir, "report.md"));
+    }
+    const manifestSrc = import_path6.default.join(scenarioArtifactsDir, "manifest.json");
+    if (import_fs6.default.existsSync(manifestSrc)) {
+      import_fs6.default.copyFileSync(manifestSrc, import_path6.default.join(latestDir, "manifest.json"));
+    }
+    for (const snap of snapshots) {
+      if (snap.filePath && import_fs6.default.existsSync(snap.filePath)) {
+        import_fs6.default.copyFileSync(snap.filePath, import_path6.default.join(latestDir, snap.fileName));
+      }
+    }
+    return import_path6.default.join(latestDir, "report.md");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/features/runner/lib/contextBuilder.ts
+function buildTestContext(options) {
+  const {
+    page,
+    context,
+    targetMode,
+    initialViewport,
+    captureEngine,
+    consoleTracker,
+    previewDriver,
+    doNavigate
+  } = options;
+  let currentViewport = { ...initialViewport };
+  const ctx = {
+    page,
+    context,
+    targetMode,
+    currentViewport,
+    // --- Snapshots ---
+    capture: async (name, opts) => {
+      console.log(`\u{1F4F8} [Snapshot] ${name} (${currentViewport.width}x${currentViewport.height})`);
+      return await captureEngine.takeSnapshot(page, name, currentViewport, opts);
+    },
+    captureBurst: async (name, opts) => {
+      console.log(`\u{1F3AC} [Burst] ${name} (duration: ${opts.durationMs}ms, interval: ${opts.intervalMs ?? 80}ms)`);
+      return await captureEngine.takeBurst(page, name, currentViewport, opts);
+    },
+    // --- Navigation ---
+    navigate: async (route) => {
+      console.log(`\u{1F9ED} [Navigate] ${route}`);
+      await doNavigate(route);
+    },
+    // --- Viewport Management ---
+    resize: async (width, height) => {
+      console.log(`\u{1F4D0} [Resize] ${width}x${height}`);
+      currentViewport = { width, height };
+      ctx.currentViewport = currentViewport;
+      await page.setViewportSize(currentViewport);
+      await page.waitForTimeout(200);
+    },
+    setPreset: async (preset) => {
+      console.log(`\u{1F4D0} [Preset] ${preset.name} (${preset.width}x${preset.height})`);
+      await ctx.resize(preset.width, preset.height);
+    },
+    resizeToFit: async (selector, padding = 0) => {
+      let boundingBox;
+      if (selector) {
+        const el = await page.$(selector);
+        if (el) {
+          boundingBox = await el.boundingBox();
+        }
+      } else {
+        boundingBox = await page.evaluate(() => ({
+          width: document.documentElement.scrollWidth,
+          height: document.documentElement.scrollHeight
+        }));
+      }
+      if (boundingBox) {
+        const newWidth = Math.ceil(boundingBox.width) + padding * 2;
+        const newHeight = Math.ceil(boundingBox.height) + padding * 2;
+        console.log(`\u{1F4D0} [ResizeToFit] ${selector || "body"} -> ${newWidth}x${newHeight}`);
+        await ctx.resize(newWidth, newHeight);
+      } else {
+        console.log(`\u26A0\uFE0F [ResizeToFit] Element ${selector} not found or has no bounding box.`);
+      }
+    },
+    // --- Waiting & DOM Observation ---
+    wait: async (ms) => {
+      await page.waitForTimeout(ms);
+    },
+    waitForSelector: async (selector, timeoutMs = 5e3) => {
+      await page.waitForSelector(selector, { timeout: timeoutMs });
+    },
+    // --- Interaction ---
+    click: async (selector) => {
+      console.log(`\u{1F5B1}\uFE0F [Click] ${selector}`);
+      await page.click(selector);
+    },
+    rightClick: async (selector) => {
+      console.log(`\u{1F5B1}\uFE0F [RightClick] ${selector}`);
+      await page.click(selector, { button: "right" });
+    },
+    type: async (selector, text) => {
+      console.log(`\u2328\uFE0F [Type] ${selector} -> "${text}"`);
+      await page.fill(selector, text);
+    },
+    selectOption: async (selector, value) => {
+      console.log(`\u2705 [Select] ${selector} -> "${value}"`);
+      await page.selectOption(selector, value);
+    },
+    hover: async (selector) => {
+      console.log(`\u{1F446} [Hover] ${selector}`);
+      await page.hover(selector);
+    },
+    scroll: async (selector, deltaY) => {
+      console.log(`\u{1F4DC} [Scroll] ${selector} by ${deltaY}px`);
+      await page.evaluate(
+        ({ sel, dY }) => {
+          const el = document.querySelector(sel);
+          if (el) {
+            el.scrollTop += dY;
+          } else {
+            window.scrollBy(0, dY);
+          }
+        },
+        { sel: selector, dY: deltaY }
+      );
+      await page.waitForTimeout(100);
+    },
+    // --- Logging ---
+    log: (msg) => {
+      console.log(`\u2139\uFE0F [Scenario] ${msg}`);
+    },
+    // --- Mock IPC (delegated or stubbed if plugin not loaded) ---
+    setMockIpc: async (action, data, mockOptions) => {
+      console.log(`\u26A0\uFE0F [Mock IPC] setMockIpc called for "${action}". Ensure --plugin=mock-ipc is enabled.`);
+    },
+    // --- HTTP Route Mocking ---
+    setMockRoute: async (url, body, routeOptions) => {
+      if (!previewDriver) {
+        console.log(`\u26A0\uFE0F [Mock Route] setMockRoute ignored (no preview driver running)`);
+        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
+      });
+    },
+    // --- Console Errors ---
+    getConsoleErrors: () => consoleTracker.getErrors(),
+    getConsoleWarnings: () => consoleTracker.getWarnings(),
+    hasConsoleErrors: () => consoleTracker.hasErrors,
+    // --- DOM Assertions ---
+    readText: async (selector) => {
+      const text = await page.textContent(selector);
+      return text ? text.trim() : null;
+    },
+    getPageText: async () => {
+      return await page.evaluate(() => document.body.innerText || "");
+    },
+    isVisible: async (selector) => {
+      try {
+        const element = await page.$(selector);
+        if (!element) return false;
+        return await element.isVisible();
+      } catch {
+        return false;
+      }
+    },
+    getElementCount: async (selector) => {
+      const elements = await page.$$(selector);
+      return elements.length;
+    }
+  };
+  return {
+    ctx,
+    getCurrentViewport: () => currentViewport
+  };
+}
+
+// src/features/runner/runner.ts
+async function runVisualScenario(options) {
+  const { scenario } = options;
+  const targetMode = options.targetMode || "preview";
+  const startTime = Date.now();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const artifactsRoot = options.artifactsRoot || import_path7.default.resolve(process.cwd(), "artifacts");
+  if (options.cleanArtifacts && import_fs7.default.existsSync(artifactsRoot)) {
+    console.log(`\u{1F9F9} [Clean Artifacts] Purging previous artifact runs in ${artifactsRoot}...`);
+    const entries = import_fs7.default.readdirSync(artifactsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      import_fs7.default.rmSync(import_path7.default.join(artifactsRoot, entry.name), { recursive: true, force: true });
+    }
+  }
+  const scenarioArtifactsDir = import_path7.default.join(artifactsRoot, `${scenario.id}_${timestamp}`);
+  if (!import_fs7.default.existsSync(scenarioArtifactsDir)) {
+    import_fs7.default.mkdirSync(scenarioArtifactsDir, { recursive: true });
   }
   const captureEngine = new CaptureEngine(scenarioArtifactsDir);
   const consoleTracker = new ConsoleTracker();
   const defaultViewport = scenario.viewports?.[0] || VIEWPORT_PRESETS.DEFAULT;
-  let currentViewport = { width: defaultViewport.width, height: defaultViewport.height };
-  let desktopDriver = null;
+  const currentViewport = { width: defaultViewport.width, height: defaultViewport.height };
   let previewDriver = null;
   let processManager = null;
+  let customDriverStop = null;
+  const pluginManager = new PluginManager();
+  const pluginSpecs = [...options.plugins || [], ...scenario.plugins || []];
+  if (pluginSpecs.length > 0) {
+    await pluginManager.loadAll(pluginSpecs);
+  }
+  const hookContext = {
+    scenario,
+    targetMode,
+    artifactsDir: scenarioArtifactsDir,
+    cliOptions: options,
+    state: /* @__PURE__ */ new Map()
+  };
   try {
     let page;
     let context;
@@ -1043,211 +1183,69 @@ async function runVisualScenario(options2) {
     console.log(`\u{1F4C1} Artifacts: ${scenarioArtifactsDir}`);
     console.log(`========================================
 `);
-    if (options2.startCommand) {
+    if (options.startCommand) {
       processManager = new ProcessManager();
-      await processManager.start(options2.startCommand, { cwd: options2.startCwd });
-      const waitTarget = options2.url || "http://localhost:5173";
+      await processManager.start(options.startCommand, { cwd: options.startCwd });
+      const waitTarget = options.url || "http://localhost:5173";
       await processManager.waitForUrl(waitTarget);
     }
+    await pluginManager.runSetup(hookContext);
     if (typeof scenario.setup === "function") {
       console.log(`\u{1F527} [Scenario Setup] Executing setup hook...`);
       await scenario.setup();
     }
-    if (targetMode === "desktop") {
-      desktopDriver = new DesktopDriver({
-        port: options2.port || 9222,
-        autoLaunch: options2.autoLaunchDesktop ?? true,
-        executablePath: options2.executablePath,
-        args: options2.desktopArgs,
-        env: options2.desktopEnv
-      });
-      const res = await desktopDriver.start(currentViewport);
-      page = res.page;
-      context = res.context;
+    const customSession = await pluginManager.launchSession(
+      { currentViewport, headed: options.headed },
+      hookContext
+    );
+    if (customSession) {
+      page = customSession.page;
+      context = customSession.context;
+      if (customSession.stop) {
+        customDriverStop = customSession.stop;
+      }
+    } else if (targetMode === "desktop") {
+      throw new Error(
+        `[AgentLens] Target mode is 'desktop', but no desktop plugin is registered. Please add --plugin=desktop-webview2 to your command or configuration.`
+      );
     } else {
       previewDriver = new PreviewDriver({
-        wwwrootDir: options2.wwwrootDir,
-        url: options2.url,
-        headed: options2.headed
+        wwwrootDir: options.wwwrootDir,
+        url: options.url,
+        headed: options.headed
       });
-      const mergedMocks = [...options2.globalMocks || [], ...scenario.mockIpc || []];
-      if (mergedMocks.length > 0) {
-        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);
+      }
     }
+    await pluginManager.runOnContextCreated(context, hookContext);
+    await pluginManager.runOnPageCreated(page, context, hookContext);
     consoleTracker.attach(page);
     console.log(`\u{1F50D} [Console Tracker] Attached \u2014 errors and warnings will be captured
 `);
-    const doNavigate = async (route) => {
-      if (route.startsWith("http://") || route.startsWith("https://")) {
-        await page.goto(route, { waitUntil: "domcontentloaded" });
-        await page.waitForTimeout(300);
-        return;
-      }
-      if (route.startsWith("#")) {
-        await page.evaluate((r) => {
-          window.location.hash = r;
-        }, route);
-        await page.waitForTimeout(300);
-        return;
-      }
-      if (previewDriver?.baseUrl && options2.url) {
-        try {
-          const fullUrl = new URL(route, previewDriver.baseUrl).toString();
-          await page.goto(fullUrl, { waitUntil: "domcontentloaded" });
-          await page.waitForTimeout(300);
-          return;
-        } catch {
-        }
-      }
-      const routePath = route.startsWith("/") ? route : `/${route}`;
-      await page.evaluate((r) => {
-        if (window.location.hash !== void 0) {
-          window.location.hash = r;
-        }
-      }, routePath);
-      await page.waitForTimeout(300);
-    };
+    const doNavigate = createNavigator(page, previewDriver?.baseUrl, options.url);
     if (scenario.route) {
-      console.log(`[Runner] Navigating to route: ${scenario.route}`);
+      console.log(`\u{1F9ED} [Runner] Navigating to initial route: ${scenario.route}`);
       await doNavigate(scenario.route);
     }
-    const ctx = {
+    const { ctx } = buildTestContext({
       page,
       context,
       targetMode,
-      currentViewport,
-      capture: async (name, opts) => {
-        console.log(`\u{1F4F8} [Snapshot] ${name} (${currentViewport.width}x${currentViewport.height})`);
-        return await captureEngine.takeSnapshot(page, name, currentViewport, opts);
-      },
-      captureBurst: async (name, opts) => {
-        console.log(`\u{1F3AC} [Burst] ${name} (duration: ${opts.durationMs}ms, interval: ${opts.intervalMs ?? 80}ms)`);
-        return await captureEngine.takeBurst(page, name, currentViewport, opts);
-      },
-      navigate: async (route) => {
-        console.log(`\u{1F9ED} [Navigate] ${route}`);
-        await doNavigate(route);
-      },
-      // ─── Viewport ───
-      resize: async (width, height) => {
-        console.log(`\u{1F4D0} [Resize] ${width}x${height}`);
-        currentViewport = { width, height };
-        ctx.currentViewport = currentViewport;
-        await page.setViewportSize(currentViewport);
-        await page.waitForTimeout(200);
-      },
-      setPreset: async (preset) => {
-        console.log(`\u{1F4D0} [Preset] ${preset.name} (${preset.width}x${preset.height})`);
-        await ctx.resize(preset.width, preset.height);
-      },
-      resizeToFit: async (selector, padding = 0) => {
-        let boundingBox;
-        if (selector) {
-          const el = await page.$(selector);
-          if (el) {
-            boundingBox = await el.boundingBox();
-          }
-        } else {
-          boundingBox = await page.evaluate(() => {
-            return {
-              width: document.documentElement.scrollWidth,
-              height: document.documentElement.scrollHeight
-            };
-          });
-        }
-        if (boundingBox) {
-          const newWidth = Math.ceil(boundingBox.width) + padding * 2;
-          const newHeight = Math.ceil(boundingBox.height) + padding * 2;
-          console.log(`\u{1F4D0} [ResizeToFit] ${selector || "body"} -> ${newWidth}x${newHeight}`);
-          await ctx.resize(newWidth, newHeight);
-        } else {
-          console.log(`\u26A0\uFE0F [ResizeToFit] Element ${selector} not found or has no bounding box.`);
-        }
-      },
-      wait: async (ms) => {
-        await page.waitForTimeout(ms);
-      },
-      waitForSelector: async (selector, timeoutMs = 5e3) => {
-        await page.waitForSelector(selector, { timeout: timeoutMs });
-      },
-      click: async (selector) => {
-        console.log(`\u{1F5B1}\uFE0F [Click] ${selector}`);
-        await page.click(selector);
-      },
-      rightClick: async (selector) => {
-        console.log(`\u{1F5B1}\uFE0F [RightClick] ${selector}`);
-        await page.click(selector, { button: "right" });
-      },
-      type: async (selector, text) => {
-        console.log(`\u2328\uFE0F [Type] ${selector} -> "${text}"`);
-        await page.fill(selector, text);
-      },
-      selectOption: async (selector, value) => {
-        console.log(`\u2705 [Select] ${selector} -> "${value}"`);
-        await page.selectOption(selector, value);
-      },
-      hover: async (selector) => {
-        console.log(`\u{1F446} [Hover] ${selector}`);
-        await page.hover(selector);
-      },
-      scroll: async (selector, deltaY) => {
-        console.log(`\u{1F4DC} [Scroll] ${selector} by ${deltaY}px`);
-        await page.evaluate(({ sel, dY }) => {
-          const el = document.querySelector(sel);
-          if (el) {
-            el.scrollTop += dY;
-          } else {
-            window.scrollBy(0, dY);
-          }
-        }, { sel: selector, dY: deltaY });
-        await page.waitForTimeout(100);
-      },
-      log: (msg) => {
-        console.log(`\u2139\uFE0F [Scenario] ${msg}`);
-      },
-      // ─── Mock IPC ───
-      setMockIpc: async (action, data, mockOptions) => {
-        if (targetMode === "desktop") {
-          console.log(`\u26A0\uFE0F [Mock IPC] setMockIpc ignored in desktop mode (real backend handles IPC)`);
-          return;
-        }
-        if (!previewDriver) {
-          console.log(`\u26A0\uFE0F [Mock IPC] PreviewDriver not available`);
-          return;
-        }
-        console.log(`\u{1F4E6} [Mock IPC] Set ${action} -> ${typeof data === "string" ? data : JSON.stringify(data).slice(0, 80)}...`);
-        await previewDriver.updateMockIpc(action, data, mockOptions);
-      },
-      getConsoleErrors: () => consoleTracker.getErrors(),
-      getConsoleWarnings: () => consoleTracker.getWarnings(),
-      hasConsoleErrors: () => consoleTracker.hasErrors,
-      // ─── DOM Assertions ───
-      readText: async (selector) => {
-        const text = await page.textContent(selector);
-        return text ? text.trim() : null;
-      },
-      getPageText: async () => {
-        return await page.evaluate(() => document.body.innerText || "");
-      },
-      isVisible: async (selector) => {
-        try {
-          const element = await page.$(selector);
-          if (!element) return false;
-          return await element.isVisible();
-        } catch {
-          return false;
-        }
-      },
-      getElementCount: async (selector) => {
-        const elements = await page.$$(selector);
-        return elements.length;
-      }
-    };
+      initialViewport: currentViewport,
+      captureEngine,
+      consoleTracker,
+      previewDriver,
+      doNavigate
+    });
+    await pluginManager.extendContext(ctx, page, hookContext);
     await scenario.run(ctx);
     const durationMs = Date.now() - startTime;
     const snapshots = captureEngine.getSnapshots();
@@ -1262,38 +1260,19 @@ async function runVisualScenario(options2) {
       console.log(`
 \u{1F7E1} Console Warnings: ${consoleWarnings.length}`);
     }
-    const reportPath = VisualReporter.generateReport({
+    const reportData = {
       scenario,
       snapshots,
       consoleErrors,
       consoleWarnings,
       outputDir: scenarioArtifactsDir,
       targetMode,
-      durationMs
-    });
-    const syncLatest = (repPath, snaps) => {
-      try {
-        const latestDir = import_path6.default.join(artifactsRoot, "latest");
-        if (import_fs6.default.existsSync(latestDir)) {
-          import_fs6.default.rmSync(latestDir, { recursive: true, force: true });
-        }
-        import_fs6.default.mkdirSync(latestDir, { recursive: true });
-        import_fs6.default.copyFileSync(repPath, import_path6.default.join(latestDir, "report.md"));
-        const manifestSrc = import_path6.default.join(scenarioArtifactsDir, "manifest.json");
-        if (import_fs6.default.existsSync(manifestSrc)) {
-          import_fs6.default.copyFileSync(manifestSrc, import_path6.default.join(latestDir, "manifest.json"));
-        }
-        for (const snap of snaps) {
-          if (snap.filePath && import_fs6.default.existsSync(snap.filePath)) {
-            import_fs6.default.copyFileSync(snap.filePath, import_path6.default.join(latestDir, snap.fileName));
-          }
-        }
-        return import_path6.default.join(latestDir, "report.md");
-      } catch {
-        return void 0;
-      }
+      durationMs,
+      customSections: []
     };
-    const latestReport = syncLatest(reportPath, snapshots);
+    await pluginManager.runOnAfterRun(reportData, hookContext);
+    const reportPath = VisualReporter.generateReport(reportData);
+    const latestReport = syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots);
     console.log(`
 \u2705 Visual Test Completed Successfully!`);
     console.log(`\u{1F4CA} Captured Snapshots: ${snapshots.length}`);
@@ -1320,7 +1299,7 @@ async function runVisualScenario(options2) {
     const snapshots = captureEngine.getSnapshots();
     const consoleErrors = consoleTracker.getErrors();
     const consoleWarnings = consoleTracker.getWarnings();
-    const reportPath = VisualReporter.generateReport({
+    const reportData = {
       scenario,
       snapshots,
       consoleErrors,
@@ -1328,16 +1307,9 @@ async function runVisualScenario(options2) {
       outputDir: scenarioArtifactsDir,
       targetMode,
       durationMs
-    });
-    try {
-      const latestDir = import_path6.default.join(artifactsRoot, "latest");
-      if (import_fs6.default.existsSync(latestDir)) {
-        import_fs6.default.rmSync(latestDir, { recursive: true, force: true });
-      }
-      import_fs6.default.mkdirSync(latestDir, { recursive: true });
-      import_fs6.default.copyFileSync(reportPath, import_path6.default.join(latestDir, "report.md"));
-    } catch {
-    }
+    };
+    const reportPath = VisualReporter.generateReport(reportData);
+    syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots);
     return {
       scenarioId: scenario.id,
       targetMode,
@@ -1350,6 +1322,7 @@ async function runVisualScenario(options2) {
       error: err.message
     };
   } finally {
+    await pluginManager.runTeardown(hookContext);
     if (typeof scenario.teardown === "function") {
       try {
         console.log(`\u{1F9F9} [Scenario Teardown] Executing teardown hook...`);
@@ -1358,21 +1331,21 @@ async function runVisualScenario(options2) {
         console.error(`\u26A0\uFE0F [Scenario Teardown] Error during teardown:`, teardownErr.message);
       }
     }
-    if (options2.cleanPaths && options2.cleanPaths.length > 0) {
-      for (const cleanTarget of options2.cleanPaths) {
+    if (options.cleanPaths && options.cleanPaths.length > 0) {
+      for (const cleanTarget of options.cleanPaths) {
         try {
-          const resolvedCleanPath = import_path6.default.resolve(process.cwd(), cleanTarget);
-          if (import_fs6.default.existsSync(resolvedCleanPath)) {
+          const resolvedCleanPath = import_path7.default.resolve(process.cwd(), cleanTarget);
+          if (import_fs7.default.existsSync(resolvedCleanPath)) {
             console.log(`\u{1F9F9} [Auto-Cleanup] Removing: ${resolvedCleanPath}`);
-            import_fs6.default.rmSync(resolvedCleanPath, { recursive: true, force: true });
+            import_fs7.default.rmSync(resolvedCleanPath, { recursive: true, force: true });
           }
         } catch (cleanErr) {
           console.error(`\u26A0\uFE0F [Auto-Cleanup] Failed to remove ${cleanTarget}:`, cleanErr.message);
         }
       }
     }
-    if (!options2.detach) {
-      if (desktopDriver) await desktopDriver.stop();
+    if (!options.detach) {
+      if (customDriverStop) await customDriverStop();
       if (previewDriver) await previewDriver.stop();
       if (processManager) await processManager.stop();
     } else {
@@ -1381,12 +1354,9 @@ async function runVisualScenario(options2) {
   }
 }
 
-// src/app/cli.ts
-var import_jiti = require("jiti");
-
 // src/features/snap/snap.ts
-var import_path7 = __toESM(require("path"));
-var import_fs7 = __toESM(require("fs"));
+var import_path8 = __toESM(require("path"));
+var import_fs8 = __toESM(require("fs"));
 var PRESET_MAP = {
   default: VIEWPORT_PRESETS.DEFAULT,
   desktop: VIEWPORT_PRESETS.DEFAULT,
@@ -1415,6 +1385,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,26 +1394,33 @@ async function isPortResponding(url) {
     return false;
   }
 }
-async function runQuickSnap(options2) {
-  let targetUrl = options2.url;
+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 && !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`);
+  if (!targetUrl && !options.start) {
+    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"))) {
+      if (import_fs8.default.existsSync(candidateDir) && import_fs8.default.existsSync(import_path8.default.join(candidateDir, "index.html"))) {
         useStaticPreview = true;
         wwwrootDir = candidateDir;
         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`);
@@ -1451,17 +1429,17 @@ async function runQuickSnap(options2) {
         return false;
       }
     }
-  } else if (!targetUrl && options2.start) {
+  } else if (!targetUrl && options.start) {
     targetUrl = "http://localhost:5173";
   }
-  const waitMs = options2.waitMs ?? 1e3;
-  const snapshotPrefix = options2.name || "quick_snap";
-  const targetViewports = parseViewportPresets(options2.viewports);
+  const waitMs = options.waitMs ?? 1e3;
+  const snapshotPrefix = options.name || "quick_snap";
+  const targetViewports = parseViewportPresets(options.viewports);
   console.log(`
 \u{1F4F8} [Quick Snap] Preparing instant verification for: ${targetUrl || wwwrootDir}`);
   console.log(`\u{1F4D0} [Quick Snap] Testing ${targetViewports.length} viewports: ${targetViewports.map((v) => `${v.name} (${v.width}x${v.height})`).join(", ")}`);
-  if (options2.selector) {
-    console.log(`\u{1F3AF} [Quick Snap] Focused element selector: "${options2.selector}"`);
+  if (options.selector) {
+    console.log(`\u{1F3AF} [Quick Snap] Focused element selector: "${options.selector}"`);
   }
   const snapScenario = defineVisualTest({
     id: "quick-snap",
@@ -1478,16 +1456,16 @@ async function runQuickSnap(options2) {
         ctx.log(`Switching viewport to: ${vp.name} (${vp.width}x${vp.height})`);
         await ctx.setPreset(vp);
         await ctx.wait(200);
-        await ctx.capture(`${stepNum}_${snapshotPrefix}_${vp.name}`);
+        await ctx.capture(`${stepNum}_${snapshotPrefix}_${vp.name}`, { fullPage: options.fullPage });
       }
-      if (options2.selector) {
-        ctx.log(`Focusing on selector: "${options2.selector}"`);
+      if (options.selector) {
+        ctx.log(`Focusing on selector: "${options.selector}"`);
         try {
           await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
-          await ctx.resizeToFit(options2.selector, 15);
-          await ctx.capture(`99_${snapshotPrefix}_element_focus`, { selector: options2.selector });
+          await ctx.resizeToFit(options.selector, 15);
+          await ctx.capture(`99_${snapshotPrefix}_element_focus`, { selector: options.selector });
         } catch (err) {
-          ctx.log(`\u26A0\uFE0F Could not isolate selector "${options2.selector}": ${err.message}`);
+          ctx.log(`\u26A0\uFE0F Could not isolate selector "${options.selector}": ${err.message}`);
         }
       }
       const errors = ctx.getConsoleErrors();
@@ -1500,18 +1478,19 @@ async function runQuickSnap(options2) {
   });
   const result = await runVisualScenario({
     scenario: snapScenario,
-    targetMode: options2.mode || "preview",
+    targetMode: options.mode || "preview",
     url: useStaticPreview ? void 0 : targetUrl,
     wwwrootDir: useStaticPreview ? wwwrootDir : void 0,
-    startCommand: options2.start,
-    startCwd: options2.startCwd,
-    executablePath: options2.exe,
-    cleanPaths: options2.clean,
-    cleanArtifacts: options2.cleanArtifacts,
-    port: options2.port,
-    headed: options2.headed,
-    detach: options2.detach,
-    artifactsRoot: options2.outDir ? import_path7.default.resolve(process.cwd(), options2.outDir) : void 0
+    startCommand: options.start,
+    startCwd: options.startCwd,
+    executablePath: options.exe,
+    cleanPaths: options.clean,
+    cleanArtifacts: options.cleanArtifacts,
+    port: options.port,
+    headed: options.headed,
+    detach: options.detach,
+    artifactsRoot: options.outDir ? import_path8.default.resolve(process.cwd(), options.outDir) : void 0,
+    plugins: options.plugins
   });
   console.log(`
 ========================================`);
@@ -1525,96 +1504,112 @@ async function runQuickSnap(options2) {
   return result.success && result.consoleErrors === 0;
 }
 
-// src/app/cli.ts
-var fileConfig = loadConfig();
-var args = process.argv.slice(2);
-if (args[0] === "init") {
-  initScenarioTemplate();
-  process.exit(0);
-}
-var isSnapCommand = args[0] === "snap";
-var effectiveArgs = isSnapCommand ? args.slice(1) : args;
-var options = {
-  mode: fileConfig.mode || "preview",
-  port: fileConfig.port || 9222,
-  headed: fileConfig.headed ?? false,
-  detach: fileConfig.detach ?? false,
-  build: fileConfig.buildCommand || false,
-  start: fileConfig.startCommand,
-  startCwd: fileConfig.startCwd,
-  cleanArtifacts: fileConfig.cleanArtifacts ?? false,
-  url: fileConfig.url,
-  exe: fileConfig.executablePath,
-  clean: Array.isArray(fileConfig.clean) ? fileConfig.clean : fileConfig.clean ? [fileConfig.clean] : void 0,
-  dir: fileConfig.scenarios,
-  wwwroot: fileConfig.wwwroot,
-  outDir: fileConfig.outDir
-};
-for (const arg of effectiveArgs) {
-  if (arg === "--help" || arg === "-h") {
-    options.help = true;
-  } else if (arg.startsWith("--scenario=")) {
-    options.scenario = arg.split("=")[1];
-  } else if (arg === "--all") {
-    options.all = true;
-  } else if (arg.startsWith("--mode=")) {
-    const mode = arg.split("=")[1].toLowerCase();
-    if (mode === "desktop" || mode === "preview") {
-      options.mode = mode;
-    }
-  } else if (arg.startsWith("--port=")) {
-    options.port = parseInt(arg.split("=")[1], 10) || 9222;
-  } else if (arg === "--headed") {
-    options.headed = true;
-  } else if (arg === "--detach") {
-    options.detach = true;
-  } else if (arg === "--build") {
-    options.build = true;
-  } else if (arg.startsWith("--build=")) {
-    options.build = arg.slice("--build=".length);
-  } else if (arg.startsWith("--start=")) {
-    options.start = arg.slice("--start=".length);
-  } else if (arg.startsWith("--start-cwd=") || arg.startsWith("--cwd=")) {
-    options.startCwd = arg.split("=")[1];
-  } else if (arg === "--clean-artifacts") {
-    options.cleanArtifacts = true;
-  } else if (arg.startsWith("--url=")) {
-    options.url = arg.split("=")[1];
-  } 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);
-  } else if (arg.startsWith("--wait=")) {
-    options.waitMs = parseInt(arg.split("=")[1], 10);
-  } else if (arg.startsWith("--name=")) {
-    options.name = arg.split("=")[1];
-  } else if (arg.startsWith("--exe=") || arg.startsWith("--executable=")) {
-    options.exe = arg.split("=")[1];
-  } else if (arg.startsWith("--clean=") || arg.startsWith("--cleanup=")) {
-    const rawPaths = arg.split("=")[1];
-    options.clean = rawPaths.split(",").map((p) => p.trim()).filter(Boolean);
-  } else if (arg.startsWith("--dir=")) {
-    options.dir = arg.split("=")[1];
-  } else if (arg.startsWith("--wwwroot=")) {
-    options.wwwroot = arg.split("=")[1];
-  } else if (arg.startsWith("--outDir=") || arg.startsWith("--folder=")) {
-    options.outDir = arg.split("=")[1];
+// src/app/lib/argsParser.ts
+function parseCliArgs(argv, fileConfig) {
+  const isInitCommand = argv[0] === "init";
+  const isSnapCommand = argv[0] === "snap";
+  const effectiveArgs = isSnapCommand ? argv.slice(1) : argv;
+  const options = {
+    mode: fileConfig.mode || "preview",
+    port: fileConfig.port || 9222,
+    headed: fileConfig.headed ?? false,
+    detach: fileConfig.detach ?? false,
+    build: fileConfig.buildCommand || false,
+    start: fileConfig.startCommand,
+    startCwd: fileConfig.startCwd,
+    cleanArtifacts: fileConfig.cleanArtifacts ?? false,
+    url: fileConfig.url,
+    exe: fileConfig.executablePath,
+    clean: Array.isArray(fileConfig.clean) ? fileConfig.clean : fileConfig.clean ? [fileConfig.clean] : void 0,
+    dir: fileConfig.scenarios,
+    wwwroot: fileConfig.wwwroot,
+    outDir: fileConfig.outDir,
+    plugins: fileConfig.plugins ? [...fileConfig.plugins] : []
+  };
+  for (const arg of effectiveArgs) {
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg.startsWith("--scenario=")) {
+      options.scenario = arg.split("=")[1];
+    } else if (arg === "--all") {
+      options.all = true;
+    } else if (arg.startsWith("--mode=")) {
+      options.mode = arg.split("=")[1].toLowerCase();
+    } else if (arg.startsWith("--port=")) {
+      options.port = parseInt(arg.split("=")[1], 10) || 9222;
+    } else if (arg === "--headed") {
+      options.headed = true;
+    } else if (arg === "--detach") {
+      options.detach = true;
+    } else if (arg === "--build") {
+      options.build = true;
+    } else if (arg.startsWith("--build=")) {
+      options.build = arg.slice("--build=".length);
+    } else if (arg.startsWith("--start=")) {
+      options.start = arg.slice("--start=".length);
+    } else if (arg.startsWith("--start-cwd=") || arg.startsWith("--cwd=")) {
+      options.startCwd = arg.split("=")[1];
+    } else if (arg === "--clean-artifacts") {
+      options.cleanArtifacts = true;
+    } else if (arg.startsWith("--url=")) {
+      options.url = arg.split("=")[1];
+    } else if (arg.startsWith("--selector=")) {
+      options.selector = arg.split("=")[1];
+    } else if (arg.startsWith("--viewports=")) {
+      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.slice("--wait=".length), 10);
+    } else if (arg.startsWith("--name=")) {
+      options.name = arg.slice("--name=".length);
+    } else if (arg.startsWith("--exe=") || arg.startsWith("--executable=")) {
+      const prefix = arg.startsWith("--exe=") ? "--exe=" : "--executable=";
+      options.exe = arg.slice(prefix.length);
+    } else if (arg.startsWith("--clean=") || arg.startsWith("--cleanup=")) {
+      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];
+    } else if (arg.startsWith("--wwwroot=")) {
+      options.wwwroot = arg.split("=")[1];
+    } else if (arg.startsWith("--outDir=") || arg.startsWith("--folder=")) {
+      options.outDir = arg.split("=")[1];
+    } else if (arg.startsWith("--plugin=") || arg.startsWith("--plugins=")) {
+      const raw = arg.split("=")[1] || "";
+      const items = raw.split(",").map((p) => p.trim()).filter(Boolean);
+      options.plugins = [...options.plugins || [], ...items];
+    } else if (arg === "--full" || arg === "--full-page") {
+      options.fullPage = true;
+    }
   }
+  if (options.start && !options.startCwd) {
+    options.startCwd = detectStartCwd(options.startCwd);
+  }
+  if ((options.mode === "desktop" || options.exe) && !options.plugins?.includes("desktop-webview2")) {
+    options.plugins = ["desktop-webview2", ...options.plugins || []];
+  }
+  return {
+    isSnapCommand,
+    isInitCommand,
+    options
+  };
 }
-if (options.start && !options.startCwd) {
-  options.startCwd = detectStartCwd(options.startCwd);
-}
+
+// src/app/lib/help.ts
 function printHelp() {
   console.log(`
 \u{1F441}\uFE0F AgentLens - Visual UI Self-Verification for AI Agents
 
 Usage:
   npx agent-lens snap [options]      Instant one-shot visual & console check (no test files needed)
+  npx agent-lens live [action]       Interactive live session (start, click, type, snap, stop)
   npx agent-lens [options]           Run scripted scenario tests from scenarios/
   npx agent-lens init                Generate starter scenario template & mocks
 
 Commands:
   snap                 Take immediate multi-viewport screenshots of a URL & check console errors
+  live                 Interactive control: click coordinates/selectors, type text, snap --full
   init                 Generate starter template in scenarios/template.scenario.ts and mocks.ts
 
 Options:
@@ -1622,6 +1617,7 @@ Options:
   --start="<cmd>"      Launch dev server or backend process before testing (e.g. --start="npm run dev")
   --start-cwd=<path>   Directory to execute --start command in (e.g. --start-cwd=./Frontend)
   --clean-artifacts    Purge previous test artifacts to prevent folder bloat
+  --full               Capture full scrollable page instead of only the viewport
   --selector=<css>     Target a specific element to focus on / resize-to-fit
   --viewports=<list>   Comma-separated viewport presets (default: desktop,mobile; or 1200x800,375x667)
   --wait=<ms>          Wait time in milliseconds after loading before snapshotting [default: 1000]
@@ -1633,6 +1629,7 @@ Options:
   --port=<port>        CDP remote debugging port [default: 9222]
   --build[=<cmd>]      Run build command before testing (e.g. --build="dotnet build" or npm run build)
   --clean=<paths>      Comma-separated paths to safely delete upon test exit (e.g. --clean="./temp,./cache")
+  --plugin=<names>     Comma-separated plugins (e.g. --plugin=desktop-webview2,mock-ipc)
   --headed             Show Chromium browser window
   --detach             Keep browser/app open after finishing
   --dir=<path>         Custom scenarios directory [default: scenarios]
@@ -1641,13 +1638,17 @@ Options:
   --help, -h           Show this help message
   `);
 }
+
+// src/app/lib/templateInit.ts
+var import_path9 = __toESM(require("path"));
+var import_fs9 = __toESM(require("fs"));
 function initScenarioTemplate() {
-  const targetDir = import_path8.default.resolve(process.cwd(), "scenarios");
-  if (!import_fs8.default.existsSync(targetDir)) {
-    import_fs8.default.mkdirSync(targetDir, { recursive: true });
+  const targetDir = import_path9.default.resolve(process.cwd(), "scenarios");
+  if (!import_fs9.default.existsSync(targetDir)) {
+    import_fs9.default.mkdirSync(targetDir, { recursive: true });
   }
-  const templatePath = import_path8.default.join(targetDir, "template.scenario.ts");
-  if (!import_fs8.default.existsSync(templatePath)) {
+  const templatePath = import_path9.default.join(targetDir, "template.scenario.ts");
+  if (!import_fs9.default.existsSync(templatePath)) {
     const templateContent = `import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
 
 export default defineVisualTest({
@@ -1678,13 +1679,13 @@ export default defineVisualTest({
   }
 });
 `;
-    import_fs8.default.writeFileSync(templatePath, templateContent, "utf8");
+    import_fs9.default.writeFileSync(templatePath, templateContent, "utf8");
     console.log(`\u2705 Starter scenario generated at: ${templatePath}`);
   } else {
     console.log(`\u2139\uFE0F Template already exists at: ${templatePath}`);
   }
-  const mocksPath = import_path8.default.join(targetDir, "mocks.ts");
-  if (!import_fs8.default.existsSync(mocksPath)) {
+  const mocksPath = import_path9.default.join(targetDir, "mocks.ts");
+  if (!import_fs9.default.existsSync(mocksPath)) {
     const mocksContent = `/**
  * Global IPC & API Mocks
  * 
@@ -1695,21 +1696,21 @@ export default [
   { action: 'GET_USER_PROFILE', data: { id: 1, name: 'Agent', role: 'admin' } }
 ];
 `;
-    import_fs8.default.writeFileSync(mocksPath, mocksContent, "utf8");
+    import_fs9.default.writeFileSync(mocksPath, mocksContent, "utf8");
     console.log(`\u2705 Base global mocks generated at: ${mocksPath}`);
   }
   console.log(`\u{1F449} Run tests with: npx agent-lens --scenario=template --mode=preview`);
 }
-if (options.help) {
-  printHelp();
-  process.exit(0);
-}
+
+// src/app/lib/scenarioFinder.ts
+var import_path10 = __toESM(require("path"));
+var import_fs10 = __toESM(require("fs"));
 async function findScenarios(dir, specificName) {
   const results = [];
-  if (!import_fs8.default.existsSync(dir)) return results;
-  const items = import_fs8.default.readdirSync(dir, { withFileTypes: true });
+  if (!import_fs10.default.existsSync(dir)) return results;
+  const items = import_fs10.default.readdirSync(dir, { withFileTypes: true });
   for (const item of items) {
-    const fullPath = import_path8.default.join(dir, item.name);
+    const fullPath = import_path10.default.join(dir, item.name);
     if (item.isDirectory()) {
       results.push(...await findScenarios(fullPath, specificName));
     } else if (item.name.endsWith(".scenario.ts") || item.name.endsWith(".scenario.js")) {
@@ -1722,7 +1723,7 @@ async function findScenarios(dir, specificName) {
 }
 function resolveScenariosDirectory(customDir) {
   if (customDir) {
-    return import_path8.default.resolve(process.cwd(), customDir);
+    return import_path10.default.resolve(process.cwd(), customDir);
   }
   const candidates = [
     "scenarios",
@@ -1732,122 +1733,333 @@ function resolveScenariosDirectory(customDir) {
     "src/scenarios"
   ];
   for (const c of candidates) {
-    const p = import_path8.default.resolve(process.cwd(), c);
-    if (import_fs8.default.existsSync(p)) {
+    const p = import_path10.default.resolve(process.cwd(), c);
+    if (import_fs10.default.existsSync(p)) {
       return p;
     }
   }
-  return import_path8.default.resolve(process.cwd(), "scenarios");
+  return import_path10.default.resolve(process.cwd(), "scenarios");
+}
+
+// src/plugins/live-controller/actions.ts
+var import_path12 = __toESM(require("path"));
+
+// src/plugins/live-controller/session.ts
+var import_fs11 = __toESM(require("fs"));
+var import_path11 = __toESM(require("path"));
+var import_tree_kill2 = __toESM(require("tree-kill"));
+var SESSION_DIR = import_path11.default.resolve(process.cwd(), ".agent-lens");
+var SESSION_FILE = import_path11.default.join(SESSION_DIR, "live-session.json");
+var LIVE_ARTIFACTS_DIR = import_path11.default.resolve(process.cwd(), "artifacts", "live");
+function getLiveArtifactsDir() {
+  if (!import_fs11.default.existsSync(LIVE_ARTIFACTS_DIR)) {
+    import_fs11.default.mkdirSync(LIVE_ARTIFACTS_DIR, { recursive: true });
+  }
+  return LIVE_ARTIFACTS_DIR;
+}
+function readLiveSession() {
+  if (!import_fs11.default.existsSync(SESSION_FILE)) return null;
+  try {
+    return JSON.parse(import_fs11.default.readFileSync(SESSION_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveLiveSession(info) {
+  if (!import_fs11.default.existsSync(SESSION_DIR)) {
+    import_fs11.default.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+  import_fs11.default.writeFileSync(SESSION_FILE, JSON.stringify(info, null, 2), "utf-8");
+}
+function clearLiveSession() {
+  if (import_fs11.default.existsSync(SESSION_FILE)) {
+    try {
+      import_fs11.default.unlinkSync(SESSION_FILE);
+    } catch {
+    }
+  }
+}
+async function connectToLiveSession() {
+  const session = readLiveSession();
+  if (!session) {
+    throw new Error(
+      `No active live session found. Start one with: npx agent-lens live start --url=http://localhost:5173`
+    );
+  }
+  const browser = await chromium.connectOverCDP(`http://127.0.0.1:${session.port}`);
+  const contexts = browser.contexts();
+  const context = contexts[0] || await browser.newContext();
+  const pages = context.pages();
+  const page = pages[0] || await context.waitForEvent("page", { timeout: 5e3 });
+  return { browser, context, page };
 }
-async function main() {
-  if (isSnapCommand || options.url && !options.scenario && !options.all) {
-    const snapSuccess = await runQuickSnap({
-      url: options.url,
-      start: options.start,
-      startCwd: options.startCwd,
-      selector: options.selector,
-      viewports: options.viewports,
-      waitMs: options.waitMs,
-      name: options.name,
-      clean: options.clean,
-      cleanArtifacts: options.cleanArtifacts,
-      headed: options.headed,
-      detach: options.detach,
-      outDir: options.outDir,
-      mode: options.mode,
-      exe: options.exe,
-      port: options.port
+async function stopLiveSession() {
+  const session = readLiveSession();
+  if (!session) {
+    console.log(`\u2139\uFE0F [Live] No active session to stop.`);
+    return false;
+  }
+  try {
+    const { browser } = await connectToLiveSession();
+    await browser.close().catch(() => {
     });
-    process.exit(snapSuccess ? 0 : 1);
+  } catch {
   }
-  if (!options.scenario && !options.all) {
-    console.error("\u274C Please specify a scenario (--scenario=name), run --all, or use: npx agent-lens snap --url=http://localhost:5173");
-    printHelp();
-    process.exit(1);
+  if (session.pid) {
+    await new Promise((resolve) => {
+      (0, import_tree_kill2.default)(session.pid, "SIGTERM", () => resolve());
+    });
   }
-  const scenariosDir = resolveScenariosDirectory(options.dir);
-  const scenarioPaths = await findScenarios(scenariosDir, options.scenario);
-  if (scenarioPaths.length === 0) {
-    console.error(`\u274C No scenarios found in ${scenariosDir}`);
-    console.log(`\u{1F4A1} Generate a template with: npx agent-lens init`);
-    process.exit(1);
+  clearLiveSession();
+  console.log(`\u{1F6D1} [Live] Session stopped and cleaned up.`);
+  return true;
+}
+
+// src/plugins/live-controller/actions.ts
+async function clickCoords(page, x, y, options) {
+  console.log(`\u{1F5B1}\uFE0F [LiveController] Clicking coordinates: (${x}, ${y})`);
+  await page.mouse.click(x, y, options);
+  await page.waitForTimeout(200);
+}
+async function snapLive(page, options) {
+  const artifactsDir = getLiveArtifactsDir();
+  const fileName = options?.name ? `${options.name}.png` : "current.png";
+  const filePath = import_path12.default.join(artifactsDir, fileName);
+  if (options?.selector) {
+    const el = await page.waitForSelector(options.selector, { timeout: 5e3 });
+    await el.screenshot({ path: filePath });
+  } else {
+    await page.screenshot({ path: filePath, fullPage: options?.fullPage ?? false });
   }
-  const shouldBuild = options.build || fileConfig.autoBuild;
-  if (shouldBuild) {
-    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) {
-      console.error(`\u274C Build failed: ${buildCmd}`);
-      process.exit(1);
+  console.log(`\u{1F4F8} [LiveController] Snapshot saved: ${filePath}${options?.fullPage ? " (Full Page)" : ""}`);
+  return filePath;
+}
+async function handleLiveCli(argv) {
+  const action = argv[0]?.toLowerCase();
+  switch (action) {
+    case "start": {
+      const urlArg = argv.find((a) => a.startsWith("--url="))?.split("=")[1] || "http://localhost:5173";
+      const portArg = parseInt(argv.find((a) => a.startsWith("--port="))?.split("=")[1] || "9223", 10);
+      const isHeaded = argv.includes("--headed");
+      console.log(`\u{1F680} [Live] Starting background browser for ${urlArg} on CDP port ${portArg}...`);
+      const browser = await chromium.launch({
+        headless: !isHeaded,
+        args: [`--remote-debugging-port=${portArg}`, "--no-sandbox"]
+      });
+      const context = await browser.newContext({ viewport: { width: 1200, height: 800 } });
+      const page = await context.newPage();
+      await page.goto(urlArg, { waitUntil: "domcontentloaded" });
+      await page.waitForTimeout(500);
+      saveLiveSession({
+        port: portArg,
+        url: urlArg,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      await snapLive(page, { name: "current" });
+      console.log(`\u2705 [Live] Session active! You can now send live commands:
+`);
+      console.log(`   npx agent-lens live click 450 120`);
+      console.log(`   npx agent-lens live type "input" "hello"`);
+      console.log(`   npx agent-lens live snap --full`);
+      console.log(`   npx agent-lens live stop
+`);
+      return true;
     }
-  } else if (options.mode === "preview" && !options.url && !options.start) {
-    console.log(`\u26A0\uFE0F  Warning: Running without --build or --url flag. Make sure your frontend is built!`);
-  }
-  console.log(`\u{1F4CB} Found ${scenarioPaths.length} scenario(s) in: ${scenariosDir}`);
-  const jiti = (0, import_jiti.createJiti)(process.cwd());
-  let globalMocks = [];
-  const mockCandidates = [
-    import_path8.default.join(scenariosDir, "mocks.ts"),
-    import_path8.default.join(scenariosDir, "mocks.js"),
-    import_path8.default.join(process.cwd(), "mocks.ts"),
-    import_path8.default.join(process.cwd(), "mocks.js")
-  ];
-  for (const mocksPath of mockCandidates) {
-    if (import_fs8.default.existsSync(mocksPath)) {
-      try {
-        const m = await jiti.import(mocksPath);
-        globalMocks = m.default || m.mocks || [];
-        console.log(`\u{1F30D} Loaded ${globalMocks.length} global mock(s) from ${import_path8.default.basename(mocksPath)}`);
-        break;
-      } catch (err) {
-        console.warn(`\u26A0\uFE0F Failed to load global mocks from ${mocksPath}:`, err);
+    case "click": {
+      const { page, browser } = await connectToLiveSession();
+      const firstArg = argv[1];
+      const secondArg = argv[2];
+      const x = parseInt(firstArg, 10);
+      const y = parseInt(secondArg, 10);
+      if (!isNaN(x) && !isNaN(y)) {
+        await clickCoords(page, x, y);
+      } else if (firstArg) {
+        console.log(`\u{1F5B1}\uFE0F [Live] Clicking selector: "${firstArg}"`);
+        await page.click(firstArg);
+      } else {
+        console.error(`\u274C Usage: npx agent-lens live click <x> <y> OR npx agent-lens live click <selector>`);
+        await browser.close();
+        return false;
       }
+      await snapLive(page, { name: "current" });
+      return true;
     }
-  }
-  let allSuccess = true;
-  for (const scenarioPath of scenarioPaths) {
-    try {
-      const scenarioModule = await jiti.import(scenarioPath);
-      const scenario = scenarioModule.default || scenarioModule.scenario;
-      if (!scenario || typeof scenario.run !== "function") {
-        console.error(`\u26A0\uFE0F Skipped: file ${import_path8.default.basename(scenarioPath)} does not export a VisualScenario object by default.`);
-        continue;
+    case "type": {
+      const { page, browser } = await connectToLiveSession();
+      const selector = argv[1];
+      const text = argv[2];
+      if (!selector || text === void 0) {
+        console.error(`\u274C Usage: npx agent-lens live type <selector> <text>`);
+        await browser.close();
+        return false;
       }
-      const result = await runVisualScenario({
-        scenario,
-        targetMode: options.mode,
+      console.log(`\u2328\uFE0F [Live] Typing into "${selector}": "${text}"`);
+      await page.fill(selector, text);
+      await snapLive(page, { name: "current" });
+      return true;
+    }
+    case "snap": {
+      const { page } = await connectToLiveSession();
+      const isFull = argv.includes("--full");
+      const nameArg = argv.find((a) => !a.startsWith("--") && a !== "snap");
+      await snapLive(page, { name: nameArg || "current", fullPage: isFull });
+      return true;
+    }
+    case "stop": {
+      return await stopLiveSession();
+    }
+    default: {
+      console.log(`
+\u2139\uFE0F AgentLens Live Controller:
+  npx agent-lens live start --url=<url>   Start background live session
+  npx agent-lens live click <x> <y>       Click at pixel coordinates
+  npx agent-lens live click <selector>    Click CSS selector
+  npx agent-lens live type <sel> <text>   Fill input field
+  npx agent-lens live snap [name] [--full] Capture current or full-page screenshot
+  npx agent-lens live stop                Close live browser and finish
+      `);
+      return true;
+    }
+  }
+}
+
+// src/app/cli.ts
+var rawArgs = process.argv.slice(2);
+if (rawArgs[0] === "live") {
+  handleLiveCli(rawArgs.slice(1)).then((success) => process.exit(success ? 0 : 1)).catch((err) => {
+    console.error("\u274C Live command failed:", err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+} else {
+  const fileConfig = loadConfig();
+  const { isSnapCommand, isInitCommand, options } = parseCliArgs(rawArgs, fileConfig);
+  if (isInitCommand) {
+    initScenarioTemplate();
+    process.exit(0);
+  }
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+  async function main() {
+    if (isSnapCommand || options.url && !options.scenario && !options.all) {
+      const snapSuccess = await runQuickSnap({
         url: options.url,
-        startCommand: options.start,
+        start: options.start,
         startCwd: options.startCwd,
+        selector: options.selector,
+        viewports: options.viewports,
+        waitMs: options.waitMs,
+        name: options.name,
+        clean: options.clean,
         cleanArtifacts: options.cleanArtifacts,
-        port: options.port,
         headed: options.headed,
         detach: options.detach,
-        executablePath: options.exe,
-        cleanPaths: options.clean,
-        desktopEnv: fileConfig.env,
-        wwwrootDir: options.wwwroot ? resolveWwwrootDir(options.wwwroot) : void 0,
-        artifactsRoot: options.outDir ? import_path8.default.resolve(process.cwd(), options.outDir) : void 0,
-        globalMocks
+        outDir: options.outDir,
+        mode: options.mode,
+        exe: options.exe,
+        port: options.port,
+        plugins: options.plugins,
+        fullPage: options.fullPage
       });
-      if (!result.success) {
+      process.exit(snapSuccess ? 0 : 1);
+    }
+    if (!options.scenario && !options.all) {
+      console.error("\u274C Please specify a scenario (--scenario=name), run --all, or use: npx agent-lens snap --url=http://localhost:5173");
+      printHelp();
+      process.exit(1);
+    }
+    const scenariosDir = resolveScenariosDirectory(options.dir);
+    const scenarioPaths = await findScenarios(scenariosDir, options.scenario);
+    if (scenarioPaths.length === 0) {
+      console.error(`\u274C No scenarios found in ${scenariosDir}`);
+      console.log(`\u{1F4A1} Generate a template with: npx agent-lens init`);
+      process.exit(1);
+    }
+    const shouldBuild = options.build || fileConfig.autoBuild;
+    if (shouldBuild) {
+      const buildCmd = typeof options.build === "string" ? options.build : fileConfig.buildCommand || "npm run build";
+      console.log(`
+\u{1F528} [Build] Running build process: "${buildCmd}"...`);
+      try {
+        (0, import_child_process2.execSync)(buildCmd, { stdio: "inherit", cwd: options.startCwd || process.cwd() });
+      } catch (e) {
+        console.error(`\u274C Build failed: ${buildCmd}`);
+        process.exit(1);
+      }
+    } else if (options.mode === "preview" && !options.url && !options.start) {
+      console.log(`\u26A0\uFE0F  Warning: Running without --build or --url flag. Make sure your frontend is built!`);
+    }
+    console.log(`\u{1F4CB} Found ${scenarioPaths.length} scenario(s) in: ${scenariosDir}`);
+    const jiti = (0, import_jiti2.createJiti)(process.cwd());
+    let globalMocks = [];
+    const mockCandidates = [
+      import_path13.default.join(scenariosDir, "mocks.ts"),
+      import_path13.default.join(scenariosDir, "mocks.js"),
+      import_path13.default.join(process.cwd(), "mocks.ts"),
+      import_path13.default.join(process.cwd(), "mocks.js")
+    ];
+    for (const mocksPath of mockCandidates) {
+      if (import_fs12.default.existsSync(mocksPath)) {
+        try {
+          const m = await jiti.import(mocksPath);
+          globalMocks = m.default || m.mocks || [];
+          console.log(`\u{1F30D} Loaded ${globalMocks.length} global mock(s) from ${import_path13.default.basename(mocksPath)}`);
+          break;
+        } catch (err) {
+          console.warn(`\u26A0\uFE0F Failed to load global mocks from ${mocksPath}:`, err);
+        }
+      }
+    }
+    if (globalMocks.length > 0 && !options.plugins?.includes("mock-ipc")) {
+      options.plugins = ["mock-ipc", ...options.plugins || []];
+    }
+    let allSuccess = true;
+    for (const scenarioPath of scenarioPaths) {
+      try {
+        const scenarioModule = await jiti.import(scenarioPath);
+        const scenario = scenarioModule.default || scenarioModule.scenario;
+        if (!scenario || typeof scenario.run !== "function") {
+          console.error(`\u26A0\uFE0F Skipped: file ${import_path13.default.basename(scenarioPath)} does not export a VisualScenario object by default.`);
+          continue;
+        }
+        const scenarioPlugins = [...options.plugins || []];
+        if (scenario.mockIpc && scenario.mockIpc.length > 0 && !scenarioPlugins.includes("mock-ipc")) {
+          scenarioPlugins.push("mock-ipc");
+        }
+        const result = await runVisualScenario({
+          scenario,
+          targetMode: options.mode,
+          url: options.url,
+          startCommand: options.start,
+          startCwd: options.startCwd,
+          cleanArtifacts: options.cleanArtifacts,
+          port: options.port,
+          headed: options.headed,
+          detach: options.detach,
+          executablePath: options.exe,
+          cleanPaths: options.clean,
+          desktopEnv: fileConfig.env,
+          wwwrootDir: options.wwwroot ? resolveWwwrootDir(options.wwwroot) : void 0,
+          artifactsRoot: options.outDir ? import_path13.default.resolve(process.cwd(), options.outDir) : void 0,
+          globalMocks,
+          plugins: scenarioPlugins
+        });
+        if (!result.success) {
+          allSuccess = false;
+        }
+      } catch (err) {
+        console.error(`\u274C Failed to load scenario ${import_path13.default.basename(scenarioPath)}:`, err);
         allSuccess = false;
       }
-    } catch (err) {
-      console.error(`\u274C Failed to load scenario ${import_path8.default.basename(scenarioPath)}:`, err);
-      allSuccess = false;
+    }
+    if (!allSuccess) {
+      process.exit(1);
     }
   }
-  if (!allSuccess) {
+  main().catch((err) => {
+    console.error("Fatal error:", err);
     process.exit(1);
-  }
+  });
 }
-main().catch((err) => {
-  console.error("Fatal error:", err);
-  process.exit(1);
-});
 //# sourceMappingURL=cli.js.map