@_deep4wee/agent-lens 1.0.1 → 1.2.0

package/dist/cli.mjs

@@ -1,18 +1,119 @@
-#!/usr/bin/env node
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var __commonJS = (cb, mod) => function __require2() {
+var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 
+// src/shared/lib/config.ts
+import path from "path";
+import fs from "fs";
+function loadConfig(cwd = process.cwd()) {
+  const jsonConfigPath = path.join(cwd, "agent-lens.json");
+  if (fs.existsSync(jsonConfigPath)) {
+    try {
+      const raw = fs.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 = path.join(cwd, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const raw = fs.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 = path.resolve(process.cwd(), providedCwd);
+    if (fs.existsSync(resolved)) {
+      return providedCwd;
+    }
+  }
+  const rootPkgPath = path.join(process.cwd(), "package.json");
+  let rootHasDevScript = false;
+  if (fs.existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(fs.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 = path.join(process.cwd(), candidate, "package.json");
+    if (fs.existsSync(candidatePkg)) {
+      return `./${candidate}`;
+    }
+  }
+  return void 0;
+}
+function resolveWwwrootDir(customDir) {
+  if (customDir) {
+    return path.resolve(process.cwd(), customDir);
+  }
+  const candidates = [
+    "dist",
+    "build",
+    "out",
+    "wwwroot",
+    "Frontend/dist",
+    "frontend/dist",
+    "client/dist"
+  ];
+  for (const c of candidates) {
+    const candidatePath = path.resolve(process.cwd(), c);
+    if (fs.existsSync(candidatePath) && fs.existsSync(path.join(candidatePath, "index.html"))) {
+      return candidatePath;
+    }
+  }
+  for (const c of candidates) {
+    const candidatePath = path.resolve(process.cwd(), c);
+    if (fs.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+  return path.resolve(process.cwd(), "dist");
+}
+var init_config = __esm({
+  "src/shared/lib/config.ts"() {
+    "use strict";
+  }
+});
+
+// src/shared/api/plugin.ts
+var init_plugin = __esm({
+  "src/shared/api/plugin.ts"() {
+    "use strict";
+  }
+});
+
+// src/shared/types/console.ts
+var init_console = __esm({
+  "src/shared/types/console.ts"() {
+    "use strict";
+  }
+});
+
+// src/shared/types/ipc.ts
+var init_ipc = __esm({
+  "src/shared/types/ipc.ts"() {
+    "use strict";
+  }
+});
+
 // src/shared/api/dsl.ts
 function defineVisualTest(scenario) {
   return scenario;
@@ -21,10 +122,13 @@ var VIEWPORT_PRESETS;
 var init_dsl = __esm({
   "src/shared/api/dsl.ts"() {
     "use strict";
+    init_plugin();
+    init_console();
+    init_ipc();
     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 },
@@ -35,8 +139,8 @@ var init_dsl = __esm({
 });
 
 // src/features/capture/capture.ts
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path2 from "path";
 var CaptureEngine;
 var init_capture = __esm({
   "src/features/capture/capture.ts"() {
@@ -47,8 +151,8 @@ var init_capture = __esm({
       recordedSnapshots = [];
       constructor(outputDir) {
         this.outputDir = outputDir;
-        if (!fs.existsSync(this.outputDir)) {
-          fs.mkdirSync(this.outputDir, { recursive: true });
+        if (!fs2.existsSync(this.outputDir)) {
+          fs2.mkdirSync(this.outputDir, { recursive: true });
         }
       }
       getSnapshots() {
@@ -64,7 +168,7 @@ var init_capture = __esm({
         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 = path.join(this.outputDir, fileName);
+        const filePath = path2.join(this.outputDir, fileName);
         if (options?.selector) {
           const element = await page.waitForSelector(options.selector, { timeout: 5e3 });
           await element.screenshot({ path: filePath });
@@ -100,7 +204,7 @@ var init_capture = __esm({
           const elapsedMs = frame * interval;
           const paddedFrame = String(frame + 1).padStart(2, "0");
           const fileName = `${paddedIndex}_burst_${sanitizedName}_f${paddedFrame}_${elapsedMs}ms.png`;
-          const filePath = path.join(this.outputDir, fileName);
+          const filePath = path2.join(this.outputDir, fileName);
           if (options.selector) {
             const element = await page.$(options.selector);
             if (element) {
@@ -137,8 +241,8 @@ var init_capture = __esm({
 });
 
 // src/features/reporter/reporter.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 var VisualReporter;
 var init_reporter = __esm({
   "src/features/reporter/reporter.ts"() {
@@ -154,8 +258,8 @@ var init_reporter = __esm({
           targetMode,
           durationMs
         } = data;
-        const manifestPath = path2.join(outputDir, "manifest.json");
-        const reportPath = path2.join(outputDir, "report.md");
+        const manifestPath = path3.join(outputDir, "manifest.json");
+        const reportPath = path3.join(outputDir, "report.md");
         const manifest = {
           scenarioId: scenario.id,
           title: scenario.title,
@@ -170,7 +274,7 @@ var init_reporter = __esm({
           errors: consoleErrors,
           warnings: consoleWarnings
         };
-        fs2.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+        fs3.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
         const rows = [];
         const regularSnapshots = snapshots.filter((s) => !s.isBurstFrame);
         const burstGroups = /* @__PURE__ */ new Map();
@@ -180,9 +284,9 @@ var init_reporter = __esm({
           burstGroups.set(s.burstGroup, list);
         });
         for (const snap of regularSnapshots) {
-          const fileUri = `file:///${snap.filePath.replace(/\\/g, "/")}`;
+          const relativeLink = snap.relativeUri || `./${snap.fileName}`;
           rows.push(
-            `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${fileUri}) |`
+            `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${relativeLink}) |`
           );
         }
         let burstSections = "";
@@ -199,8 +303,8 @@ var init_reporter = __esm({
 | :--- | :--- | :--- | :--- |
 `;
             for (const frame of frames) {
-              const fileUri = `file:///${frame.filePath.replace(/\\/g, "/")}`;
-              burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${fileUri}) | ![](${fileUri}) |
+              const relativeLink = frame.relativeUri || `./${frame.fileName}`;
+              burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${relativeLink}) | ![](${relativeLink}) |
 `;
             }
             burstSections += `
@@ -263,6 +367,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}
+
 `;
           }
         }
@@ -285,18 +400,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").
 
 `;
-        fs2.writeFileSync(reportPath, reportContent, "utf-8");
+        fs3.writeFileSync(reportPath, reportContent, "utf-8");
         return reportPath;
       }
       static getHealthStatus(errors, warnings) {
@@ -320,8 +438,6 @@ var init_consoleTracker = __esm({
     ConsoleTracker = class {
       entries = [];
       attached = false;
-      /**
-       */
       attach(page) {
         if (this.attached) return;
         this.attached = true;
@@ -390,8 +506,6 @@ var init_consoleTracker = __esm({
             return "log";
         }
       }
-      /**
-       */
       isIgnoredWarning(text) {
         const ignoredPatterns = [
           "findDOMNode is deprecated",
@@ -411,394 +525,42 @@ var init_consoleTracker = __esm({
 });
 
 // src/shared/lib/playwrightLoader.ts
-import { chromium } from "playwright";
+import { chromium as baseChromium } from "playwright";
+var chromium;
 var init_playwrightLoader = __esm({
   "src/shared/lib/playwrightLoader.ts"() {
     "use strict";
-  }
-});
-
-// src/shared/drivers/desktopDriver.ts
-import { spawn } from "child_process";
-import http from "http";
-import path3 from "path";
-import fs3 from "fs";
-var DesktopDriver;
-var init_desktopDriver = __esm({
-  "src/shared/drivers/desktopDriver.ts"() {
-    "use strict";
-    init_playwrightLoader();
-    DesktopDriver = class {
-      port;
-      executablePath;
-      autoLaunch;
-      args;
-      env;
-      cwd;
-      childProcess = null;
-      browser = null;
-      context = null;
-      page = null;
-      processStderr = "";
-      processExited = false;
-      exitCode = null;
-      constructor(options) {
-        this.port = options?.port || 9222;
-        this.autoLaunch = options?.autoLaunch ?? true;
-        this.executablePath = options?.executablePath;
-        this.args = options?.args || [];
-        this.env = options?.env || {};
-        this.cwd = options?.cwd;
-      }
-      async isPortAvailable() {
-        return new Promise((resolve) => {
-          const req = http.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 = path3.resolve(process.cwd(), this.executablePath);
-          if (!fs3.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 = spawn(resolvedExe, this.args, {
-            env: mergedEnv,
-            cwd: this.cwd || path3.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 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) {
-              spawn("taskkill", ["/pid", String(this.childProcess.pid), "/T", "/F"], { stdio: "ignore" });
-            } else {
-              this.childProcess.kill("SIGTERM");
-            }
-          } catch {
-          }
-          this.childProcess = null;
-        }
-      }
-    };
-  }
-});
-
-// src/features/mock-ipc/mockIpc.ts
-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);
+    chromium = new Proxy(baseChromium, {
+      get(target, prop, receiver) {
+        if (prop === "launch") {
+          return async (...args) => {
+            try {
+              return await target.launch(...args);
+            } catch (err) {
+              if (err.message?.includes("Executable doesn't exist") || err.message?.includes("playwright install") || err.message?.includes("browser has not been downloaded")) {
+                console.error("\n\u274C [AgentLens] Playwright Chromium browser binary is missing!");
+                console.error("\u{1F449} Please install it by running: npx playwright install chromium\n");
+              }
+              throw err;
             }
-          });
-        }
-      };
-
-      // Legacy fallback for generic window.external
-      if (!window.external) {
-        window.external = {};
-      }
-      
-      window.external.sendMessage = (msg) => {
-        try {
-          const parsed = JSON.parse(msg);
-          const action = parsed.Action || parsed.action;
-          const id = parsed.Id || parsed.id;
-
-          const mock = window.__visualRunnerMocks[action];
-
-          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);
-          }
-        } catch (e) {
-          console.error('[Mock IPC] Failed to process legacy message:', e);
-        }
-      };
-
-      window.external.receiveMessage = (callback) => {
-        window.__mockCallback = callback;
-      };
-
-      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');
-    })();
-  `;
-}
-var MockIpcRegistry;
-var init_mockIpc = __esm({
-  "src/features/mock-ipc/mockIpc.ts"() {
-    "use strict";
-    MockIpcRegistry = class {
-      mocks = /* @__PURE__ */ new Map();
-      set(action, data, options) {
-        this.mocks.set(action, {
-          action,
-          data,
-          type: options?.type ?? "SUCCESS",
-          delayMs: options?.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;
+        const val = Reflect.get(target, prop, receiver);
+        return typeof val === "function" ? val.bind(target) : val;
       }
-    };
+    });
   }
 });
 
-// src/shared/lib/config.ts
+// src/shared/drivers/previewDriver.ts
+import http from "http";
 import fs4 from "fs";
 import path4 from "path";
-function loadConfig(cwd = process.cwd()) {
-  const configPath = path4.join(cwd, "agent-lens.json");
-  if (fs4.existsSync(configPath)) {
-    try {
-      const raw = fs4.readFileSync(configPath, "utf8");
-      return JSON.parse(raw);
-    } catch (e) {
-      console.warn(`\u26A0\uFE0F Warning: Failed to parse agent-lens.json:`, e);
-    }
-  }
-  const pkgPath = path4.join(cwd, "package.json");
-  if (fs4.existsSync(pkgPath)) {
-    try {
-      const raw = fs4.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 path4.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 = path4.resolve(cwd, rel);
-    if (fs4.existsSync(candidate) && fs4.existsSync(path4.join(candidate, "index.html"))) {
-      return candidate;
-    }
-  }
-  const foundDeepWwwroot = findDeepIndexHtmlDir(cwd, 4);
-  if (foundDeepWwwroot) {
-    return foundDeepWwwroot;
-  }
-  for (const rel of standardDirs) {
-    const candidate = path4.resolve(cwd, rel);
-    if (fs4.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  return path4.resolve(cwd, "dist");
-}
-function detectStartCwd(customCwd, rootCwd = process.cwd()) {
-  if (customCwd) {
-    return path4.resolve(rootCwd, customCwd);
-  }
-  const subdirectories = ["Frontend", "frontend", "client", "web", "ui", "app"];
-  for (const sub of subdirectories) {
-    const subPkg = path4.join(rootCwd, sub, "package.json");
-    if (fs4.existsSync(subPkg)) {
-      try {
-        const json = JSON.parse(fs4.readFileSync(subPkg, "utf8"));
-        if (json.scripts && (json.scripts.dev || json.scripts.start || json.scripts.build)) {
-          return path4.join(rootCwd, sub);
-        }
-      } catch {
-      }
-    }
-  }
-  return rootCwd;
-}
-function findDeepIndexHtmlDir(dir, maxDepth, currentDepth = 0) {
-  if (currentDepth > maxDepth || !fs4.existsSync(dir)) return null;
-  try {
-    const entries = fs4.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "artifacts") {
-          continue;
-        }
-        const subDir = path4.join(dir, entry.name);
-        if (entry.name === "wwwroot" && fs4.existsSync(path4.join(subDir, "index.html"))) {
-          return subDir;
-        }
-        const found = findDeepIndexHtmlDir(subDir, maxDepth, currentDepth + 1);
-        if (found) return found;
-      }
-    }
-  } catch {
-    return null;
-  }
-  return null;
-}
-var init_config = __esm({
-  "src/shared/lib/config.ts"() {
-    "use strict";
-  }
-});
-
-// src/shared/drivers/previewDriver.ts
-import http2 from "http";
-import fs5 from "fs";
-import path5 from "path";
 var MIME_TYPES, PreviewDriver;
 var init_previewDriver = __esm({
   "src/shared/drivers/previewDriver.ts"() {
     "use strict";
     init_playwrightLoader();
-    init_mockIpc();
     init_config();
     MIME_TYPES = {
       ".html": "text/html; charset=utf-8",
@@ -823,13 +585,12 @@ var init_previewDriver = __esm({
       serverPort = 0;
       options;
       _baseUrl = "";
-      mockRegistry;
+      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;
@@ -837,25 +598,25 @@ var init_previewDriver = __esm({
       async start(initialViewport = { width: 1200, height: 800 }) {
         let targetUrl = this.options.url;
         if (!targetUrl) {
-          if (!fs5.existsSync(this.options.wwwrootDir)) {
+          if (!fs4.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 = http2.createServer((req, res) => {
+            this.server = http.createServer((req, res) => {
               let reqUrl = req.url?.split("?")[0] || "/";
               if (reqUrl === "/") reqUrl = "/index.html";
-              let safePath = path5.normalize(path5.join(this.options.wwwrootDir, reqUrl));
+              let safePath = path4.normalize(path4.join(this.options.wwwrootDir, reqUrl));
               if (!safePath.startsWith(this.options.wwwrootDir)) {
                 res.writeHead(403);
                 return res.end("Forbidden");
               }
-              if (!fs5.existsSync(safePath) || fs5.statSync(safePath).isDirectory()) {
-                safePath = path5.join(this.options.wwwrootDir, "index.html");
+              if (!fs4.existsSync(safePath) || fs4.statSync(safePath).isDirectory()) {
+                safePath = path4.join(this.options.wwwrootDir, "index.html");
               }
-              const ext = path5.extname(safePath).toLowerCase();
+              const ext = path4.extname(safePath).toLowerCase();
               const contentType = MIME_TYPES[ext] || "application/octet-stream";
               try {
-                const content = fs5.readFileSync(safePath);
+                const content = fs4.readFileSync(safePath);
                 res.writeHead(200, { "Content-Type": contentType });
                 res.end(content);
               } catch (e) {
@@ -887,35 +648,41 @@ var init_previewDriver = __esm({
           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, options) {
+      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, options);
-        await this.page.evaluate(
-          ({ action: action2, mock }) => {
-            if (!window.__visualRunnerMocks) {
-              window.__visualRunnerMocks = {};
-            }
-            window.__visualRunnerMocks[action2] = mock;
-          },
-          {
-            action,
-            mock: {
-              data,
-              type: options?.type ?? "SUCCESS",
-              delayMs: options?.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) {
@@ -940,141 +707,540 @@ var init_previewDriver = __esm({
 });
 
 // src/shared/lib/processManager.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn } from "child_process";
 import treeKill from "tree-kill";
 var ProcessManager;
 var init_processManager = __esm({
   "src/shared/lib/processManager.ts"() {
     "use strict";
     ProcessManager = class {
-      child = null;
-      stderrOutput = "";
-      stdoutOutput = "";
-      hasExited = false;
-      exitCode = null;
-      /**
-       * Spawns a background process (e.g. dev server, backend, or app)
-       */
+      childProcess = null;
+      isStopped = false;
       async start(command, options) {
-        this.stderrOutput = "";
-        this.stdoutOutput = "";
-        this.hasExited = false;
-        this.exitCode = null;
         const cwd = options?.cwd || process.cwd();
-        const env = { ...process.env, ...options?.env };
         console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
-        this.child = spawn2(command, {
+        this.childProcess = spawn(command, {
           cwd,
-          env,
-          shell: options?.shell ?? true,
+          env: { ...process.env, ...options?.env },
+          shell: true,
           stdio: ["ignore", "pipe", "pipe"]
         });
-        this.child.stdout?.on("data", (chunk) => {
-          const str = chunk.toString();
-          this.stdoutOutput += str;
-        });
-        this.child.stderr?.on("data", (chunk) => {
-          const str = chunk.toString();
-          this.stderrOutput += str;
+        this.childProcess.stdout?.on("data", (chunk) => {
+          const line = chunk.toString().trim();
+          if (line) {
+          }
         });
-        this.child.on("exit", (code) => {
-          this.hasExited = true;
-          this.exitCode = code;
+        this.childProcess.stderr?.on("data", (chunk) => {
+          const line = chunk.toString().trim();
+          if (line && !line.includes("ExperimentalWarning")) {
+          }
         });
-        this.child.on("error", (err) => {
-          console.error(`\u274C [ProcessManager] Failed to start command: "${command}":`, err.message);
+        this.childProcess.on("exit", (code, signal) => {
+          if (!this.isStopped && code !== 0 && code !== null) {
+            console.warn(`\u26A0\uFE0F [ProcessManager] Subprocess exited prematurely with code ${code}, signal ${signal}`);
+          }
         });
       }
-      /**
-       * Polls a URL until it starts responding or until timeout is reached.
-       */
       async waitForUrl(url, timeoutMs = 3e4) {
+        console.log(`\u23F3 [ProcessManager] Waiting for ${url} to respond...`);
         const startTime = Date.now();
-        console.log(`\u23F3 [ProcessManager] Waiting for URL to become available: ${url} (timeout: ${timeoutMs / 1e3}s)...`);
         while (Date.now() - startTime < timeoutMs) {
-          if (this.hasExited && this.exitCode !== 0) {
+          if (this.childProcess && this.childProcess.exitCode !== null) {
             throw new Error(
-              `[ProcessManager] Process exited prematurely with code ${this.exitCode}.
-Stderr:
-${this.stderrOutput.trim() || "(no stderr)"}
-Stdout:
-${this.stdoutOutput.slice(-500).trim()}`
+              `[ProcessManager] Server process exited with code ${this.childProcess.exitCode} while waiting for ${url}`
             );
           }
           try {
-            const response = await fetch(url, { method: "GET", signal: AbortSignal.timeout(2e3) });
+            const response = await fetch(url, { signal: AbortSignal.timeout(1e3) });
             if (response.status) {
-              console.log(`\u2705 [ProcessManager] Server responded with status ${response.status} at ${url}`);
-              return;
+              console.log(`\u2705 [ProcessManager] Target ${url} is ready (status: ${response.status})!`);
+              return true;
             }
           } catch {
           }
-          await new Promise((resolve) => setTimeout(resolve, 350));
+          await new Promise((r) => setTimeout(r, 500));
         }
-        throw new Error(
-          `[ProcessManager] Timeout (${timeoutMs / 1e3}s) waiting for server at ${url}.
-Last stdout:
-${this.stdoutOutput.slice(-500).trim()}
-Last stderr:
-${this.stderrOutput.trim()}`
-        );
+        throw new Error(`[ProcessManager] Timeout after ${timeoutMs}ms waiting for ${url} to respond.`);
       }
-      /**
-       * Gracefully and forcefully kills the process and all its children.
-       */
       async stop() {
-        if (!this.child || !this.child.pid || this.hasExited) {
-          this.child = null;
+        if (this.isStopped || !this.childProcess || !this.childProcess.pid) {
           return;
         }
-        const pid = this.child.pid;
-        console.log(`\u{1F6D1} [ProcessManager] Terminating process tree (PID: ${pid})...`);
+        this.isStopped = true;
+        const pid = this.childProcess.pid;
+        console.log(`\u{1F6D1} [ProcessManager] Terminating process tree for PID ${pid}...`);
         await new Promise((resolve) => {
-          treeKill(pid, "SIGKILL", (err) => {
+          treeKill(pid, "SIGTERM", (err) => {
             if (err) {
-              if (process.platform === "win32") {
-                try {
-                  spawn2("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
-                } catch {
-                }
+              try {
+                treeKill(pid, "SIGKILL");
+              } catch {
               }
             }
             resolve();
           });
         });
-        this.child = null;
+        this.childProcess = null;
       }
     };
   }
 });
 
-// src/features/runner/runner.ts
-import path6 from "path";
+// src/shared/lib/pluginLoader.ts
+import path5 from "path";
+import fs5 from "fs";
+import { createJiti } from "jiti";
+function findPackageRoot() {
+  let cur = __dirname;
+  while (cur !== path5.dirname(cur)) {
+    const pkgPath = path5.join(cur, "package.json");
+    if (fs5.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+        if (pkg.name === "@_deep4wee/agent-lens" || pkg.name === "agent-lens") {
+          return cur;
+        }
+      } catch {
+      }
+    }
+    cur = path5.dirname(cur);
+  }
+  return path5.resolve(__dirname, "..");
+}
+var PluginManager;
+var init_pluginLoader = __esm({
+  "src/shared/lib/pluginLoader.ts"() {
+    "use strict";
+    PluginManager = class {
+      plugins = [];
+      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 = path5.resolve(process.cwd(), pluginNameOrPath);
+          await this.loadFromFile(resolvedPath);
+          return;
+        }
+        const localCandidates = [
+          path5.resolve(process.cwd(), ".agent-lens", "plugins", `${pluginNameOrPath}.ts`),
+          path5.resolve(process.cwd(), ".agent-lens", "plugins", `${pluginNameOrPath}.js`),
+          path5.resolve(process.cwd(), "plugins", `${pluginNameOrPath}.ts`),
+          path5.resolve(process.cwd(), "plugins", `${pluginNameOrPath}.js`),
+          path5.resolve(process.cwd(), ".agent-lens", "plugins", pluginNameOrPath, "index.ts"),
+          path5.resolve(process.cwd(), ".agent-lens", "plugins", pluginNameOrPath, "index.js"),
+          path5.resolve(process.cwd(), "plugins", pluginNameOrPath, "index.ts"),
+          path5.resolve(process.cwd(), "plugins", pluginNameOrPath, "index.js")
+        ];
+        for (const candidate of localCandidates) {
+          if (fs5.existsSync(candidate)) {
+            await this.loadFromFile(candidate);
+            return;
+          }
+        }
+        const pkgRoot = findPackageRoot();
+        const builtInCandidates = [
+          path5.join(pkgRoot, "src", "plugins", pluginNameOrPath, "index.ts"),
+          path5.join(pkgRoot, "src", "plugins", pluginNameOrPath, "index.js"),
+          path5.join(pkgRoot, "dist", "plugins", pluginNameOrPath, "index.js"),
+          path5.join(pkgRoot, "plugins", pluginNameOrPath, "index.ts"),
+          path5.join(pkgRoot, "plugins", pluginNameOrPath, "index.js"),
+          path5.resolve(__dirname, "../../plugins", pluginNameOrPath, "index.ts"),
+          path5.resolve(__dirname, "../../plugins", pluginNameOrPath, "index.js"),
+          path5.resolve(__dirname, "../plugins", pluginNameOrPath, "index.ts"),
+          path5.resolve(__dirname, "../plugins", pluginNameOrPath, "index.js")
+        ];
+        for (const builtIn of builtInCandidates) {
+          if (fs5.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 (!fs5.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);
+  };
+}
+var init_navigation = __esm({
+  "src/features/runner/lib/navigation.ts"() {
+    "use strict";
+  }
+});
+
+// src/features/runner/lib/artifactsSync.ts
 import fs6 from "fs";
+import path6 from "path";
+function syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots) {
+  try {
+    const latestDir = path6.join(artifactsRoot, "latest");
+    if (fs6.existsSync(latestDir)) {
+      fs6.rmSync(latestDir, { recursive: true, force: true });
+    }
+    fs6.mkdirSync(latestDir, { recursive: true });
+    if (fs6.existsSync(reportPath)) {
+      fs6.copyFileSync(reportPath, path6.join(latestDir, "report.md"));
+    }
+    const manifestSrc = path6.join(scenarioArtifactsDir, "manifest.json");
+    if (fs6.existsSync(manifestSrc)) {
+      fs6.copyFileSync(manifestSrc, path6.join(latestDir, "manifest.json"));
+    }
+    for (const snap of snapshots) {
+      if (snap.filePath && fs6.existsSync(snap.filePath)) {
+        fs6.copyFileSync(snap.filePath, path6.join(latestDir, snap.fileName));
+      }
+    }
+    return path6.join(latestDir, "report.md");
+  } catch {
+    return void 0;
+  }
+}
+var init_artifactsSync = __esm({
+  "src/features/runner/lib/artifactsSync.ts"() {
+    "use strict";
+  }
+});
+
+// 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
+  };
+}
+var init_contextBuilder = __esm({
+  "src/features/runner/lib/contextBuilder.ts"() {
+    "use strict";
+  }
+});
+
+// src/features/runner/runner.ts
+import path7 from "path";
+import fs7 from "fs";
 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 || path6.resolve(process.cwd(), "artifacts");
-  if (options.cleanArtifacts && fs6.existsSync(artifactsRoot)) {
+  const artifactsRoot = options.artifactsRoot || path7.resolve(process.cwd(), "artifacts");
+  if (options.cleanArtifacts && fs7.existsSync(artifactsRoot)) {
     console.log(`\u{1F9F9} [Clean Artifacts] Purging previous artifact runs in ${artifactsRoot}...`);
-    const entries = fs6.readdirSync(artifactsRoot, { withFileTypes: true });
+    const entries = fs7.readdirSync(artifactsRoot, { withFileTypes: true });
     for (const entry of entries) {
-      fs6.rmSync(path6.join(artifactsRoot, entry.name), { recursive: true, force: true });
+      fs7.rmSync(path7.join(artifactsRoot, entry.name), { recursive: true, force: true });
     }
   }
-  const scenarioArtifactsDir = path6.join(artifactsRoot, `${scenario.id}_${timestamp}`);
-  if (!fs6.existsSync(scenarioArtifactsDir)) {
-    fs6.mkdirSync(scenarioArtifactsDir, { recursive: true });
+  const scenarioArtifactsDir = path7.join(artifactsRoot, `${scenario.id}_${timestamp}`);
+  if (!fs7.existsSync(scenarioArtifactsDir)) {
+    fs7.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;
@@ -1091,205 +1257,63 @@ async function runVisualScenario(options) {
       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: options.port || 9222,
-        autoLaunch: options.autoLaunchDesktop ?? true,
-        executablePath: options.executablePath,
-        args: options.desktopArgs,
-        env: options.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: options.wwwrootDir,
         url: options.url,
         headed: options.headed
       });
-      const mergedMocks = [...options.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 && options.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();
@@ -1304,38 +1328,19 @@ async function runVisualScenario(options) {
       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 = path6.join(artifactsRoot, "latest");
-        if (fs6.existsSync(latestDir)) {
-          fs6.rmSync(latestDir, { recursive: true, force: true });
-        }
-        fs6.mkdirSync(latestDir, { recursive: true });
-        fs6.copyFileSync(repPath, path6.join(latestDir, "report.md"));
-        const manifestSrc = path6.join(scenarioArtifactsDir, "manifest.json");
-        if (fs6.existsSync(manifestSrc)) {
-          fs6.copyFileSync(manifestSrc, path6.join(latestDir, "manifest.json"));
-        }
-        for (const snap of snaps) {
-          if (snap.filePath && fs6.existsSync(snap.filePath)) {
-            fs6.copyFileSync(snap.filePath, path6.join(latestDir, snap.fileName));
-          }
-        }
-        return path6.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}`);
@@ -1362,7 +1367,7 @@ async function runVisualScenario(options) {
     const snapshots = captureEngine.getSnapshots();
     const consoleErrors = consoleTracker.getErrors();
     const consoleWarnings = consoleTracker.getWarnings();
-    const reportPath = VisualReporter.generateReport({
+    const reportData = {
       scenario,
       snapshots,
       consoleErrors,
@@ -1370,16 +1375,9 @@ async function runVisualScenario(options) {
       outputDir: scenarioArtifactsDir,
       targetMode,
       durationMs
-    });
-    try {
-      const latestDir = path6.join(artifactsRoot, "latest");
-      if (fs6.existsSync(latestDir)) {
-        fs6.rmSync(latestDir, { recursive: true, force: true });
-      }
-      fs6.mkdirSync(latestDir, { recursive: true });
-      fs6.copyFileSync(reportPath, path6.join(latestDir, "report.md"));
-    } catch {
-    }
+    };
+    const reportPath = VisualReporter.generateReport(reportData);
+    syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots);
     return {
       scenarioId: scenario.id,
       targetMode,
@@ -1392,6 +1390,7 @@ async function runVisualScenario(options) {
       error: err.message
     };
   } finally {
+    await pluginManager.runTeardown(hookContext);
     if (typeof scenario.teardown === "function") {
       try {
         console.log(`\u{1F9F9} [Scenario Teardown] Executing teardown hook...`);
@@ -1403,10 +1402,10 @@ async function runVisualScenario(options) {
     if (options.cleanPaths && options.cleanPaths.length > 0) {
       for (const cleanTarget of options.cleanPaths) {
         try {
-          const resolvedCleanPath = path6.resolve(process.cwd(), cleanTarget);
-          if (fs6.existsSync(resolvedCleanPath)) {
+          const resolvedCleanPath = path7.resolve(process.cwd(), cleanTarget);
+          if (fs7.existsSync(resolvedCleanPath)) {
             console.log(`\u{1F9F9} [Auto-Cleanup] Removing: ${resolvedCleanPath}`);
-            fs6.rmSync(resolvedCleanPath, { recursive: true, force: true });
+            fs7.rmSync(resolvedCleanPath, { recursive: true, force: true });
           }
         } catch (cleanErr) {
           console.error(`\u26A0\uFE0F [Auto-Cleanup] Failed to remove ${cleanTarget}:`, cleanErr.message);
@@ -1414,7 +1413,7 @@ async function runVisualScenario(options) {
       }
     }
     if (!options.detach) {
-      if (desktopDriver) await desktopDriver.stop();
+      if (customDriverStop) await customDriverStop();
       if (previewDriver) await previewDriver.stop();
       if (processManager) await processManager.stop();
     } else {
@@ -1429,15 +1428,29 @@ var init_runner = __esm({
     init_capture();
     init_reporter();
     init_consoleTracker();
-    init_desktopDriver();
     init_previewDriver();
     init_processManager();
+    init_pluginLoader();
+    init_navigation();
+    init_artifactsSync();
+    init_contextBuilder();
+  }
+});
+
+// src/features/runner/index.ts
+var init_runner2 = __esm({
+  "src/features/runner/index.ts"() {
+    "use strict";
+    init_runner();
+    init_navigation();
+    init_artifactsSync();
+    init_contextBuilder();
   }
 });
 
 // src/features/snap/snap.ts
-import path7 from "path";
-import fs7 from "fs";
+import path8 from "path";
+import fs8 from "fs";
 function parseViewportPresets(raw) {
   if (!raw || raw.length === 0) {
     return [VIEWPORT_PRESETS.DEFAULT, PRESET_MAP.mobile];
@@ -1464,26 +1477,33 @@ async function isPortResponding(url) {
     return false;
   }
 }
+async function detectActiveDevServer() {
+  for (const port of CANDIDATE_PORTS) {
+    const url = `http://localhost:${port}`;
+    if (await isPortResponding(url)) {
+      return url;
+    }
+  }
+  return null;
+}
 async function runQuickSnap(options) {
   let targetUrl = options.url;
   let useStaticPreview = false;
   let wwwrootDir;
   if (!targetUrl && !options.start) {
-    if (await isPortResponding("http://localhost:5173")) {
-      targetUrl = "http://localhost:5173";
-      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:5173`);
-    } else if (await isPortResponding("http://localhost:3000")) {
-      targetUrl = "http://localhost:3000";
-      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:3000`);
+    const activeUrl = await detectActiveDevServer();
+    if (activeUrl) {
+      targetUrl = activeUrl;
+      console.log(`\u{1F310} [Quick Snap] Detected active dev server on ${targetUrl}`);
     } else {
       const candidateDir = resolveWwwrootDir();
-      if (fs7.existsSync(candidateDir) && fs7.existsSync(path7.join(candidateDir, "index.html"))) {
+      if (fs8.existsSync(candidateDir) && fs8.existsSync(path8.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`);
@@ -1519,7 +1539,7 @@ async function runQuickSnap(options) {
         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 (options.selector) {
         ctx.log(`Focusing on selector: "${options.selector}"`);
@@ -1552,7 +1572,8 @@ async function runQuickSnap(options) {
     port: options.port,
     headed: options.headed,
     detach: options.detach,
-    artifactsRoot: options.outDir ? path7.resolve(process.cwd(), options.outDir) : void 0
+    artifactsRoot: options.outDir ? path8.resolve(process.cwd(), options.outDir) : void 0,
+    plugins: options.plugins
   });
   console.log(`
 ========================================`);
@@ -1565,7 +1586,7 @@ async function runQuickSnap(options) {
 `);
   return result.success && result.consoleErrors === 0;
 }
-var PRESET_MAP;
+var PRESET_MAP, CANDIDATE_PORTS;
 var init_snap = __esm({
   "src/features/snap/snap.ts"() {
     "use strict";
@@ -1582,107 +1603,122 @@ var init_snap = __esm({
       tablet: { name: "tablet", width: 768, height: 1024 },
       "full-hd": VIEWPORT_PRESETS.FULL_HD
     };
+    CANDIDATE_PORTS = [5173, 3e3, 4321, 4200, 8080, 8e3, 3001];
   }
 });
 
-// src/app/cli.ts
-import path8 from "path";
-import fs8 from "fs";
-import { createJiti } from "jiti";
-var require_cli = __commonJS({
-  "src/app/cli.ts"() {
-    init_runner();
-    init_config();
-    init_snap();
-    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];
-      }
-    }
-    if (options.start && !options.startCwd) {
-      options.startCwd = detectStartCwd(options.startCwd);
+// 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;
     }
-    function printHelp() {
-      console.log(`
+  }
+  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
+  };
+}
+var init_argsParser = __esm({
+  "src/app/lib/argsParser.ts"() {
+    "use strict";
+    init_config();
+  }
+});
+
+// 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:
@@ -1690,6 +1726,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]
@@ -1701,6 +1738,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]
@@ -1708,15 +1746,24 @@ Options:
   --folder=<path>      Directory to save visual artifacts/reports (also --outDir)
   --help, -h           Show this help message
   `);
-    }
-    function initScenarioTemplate() {
-      const targetDir = path8.resolve(process.cwd(), "scenarios");
-      if (!fs8.existsSync(targetDir)) {
-        fs8.mkdirSync(targetDir, { recursive: true });
-      }
-      const templatePath = path8.join(targetDir, "template.scenario.ts");
-      if (!fs8.existsSync(templatePath)) {
-        const templateContent = `import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+}
+var init_help = __esm({
+  "src/app/lib/help.ts"() {
+    "use strict";
+  }
+});
+
+// src/app/lib/templateInit.ts
+import path9 from "path";
+import fs9 from "fs";
+function initScenarioTemplate() {
+  const targetDir = path9.resolve(process.cwd(), "scenarios");
+  if (!fs9.existsSync(targetDir)) {
+    fs9.mkdirSync(targetDir, { recursive: true });
+  }
+  const templatePath = path9.join(targetDir, "template.scenario.ts");
+  if (!fs9.existsSync(templatePath)) {
+    const templateContent = `import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
 
 export default defineVisualTest({
   id: 'template-check',
@@ -1746,14 +1793,14 @@ export default defineVisualTest({
   }
 });
 `;
-        fs8.writeFileSync(templatePath, templateContent, "utf8");
-        console.log(`\u2705 Starter scenario generated at: ${templatePath}`);
-      } else {
-        console.log(`\u2139\uFE0F Template already exists at: ${templatePath}`);
-      }
-      const mocksPath = path8.join(targetDir, "mocks.ts");
-      if (!fs8.existsSync(mocksPath)) {
-        const mocksContent = `/**
+    fs9.writeFileSync(templatePath, templateContent, "utf8");
+    console.log(`\u2705 Starter scenario generated at: ${templatePath}`);
+  } else {
+    console.log(`\u2139\uFE0F Template already exists at: ${templatePath}`);
+  }
+  const mocksPath = path9.join(targetDir, "mocks.ts");
+  if (!fs9.existsSync(mocksPath)) {
+    const mocksContent = `/**
  * Global IPC & API Mocks
  * 
  * Export an array of base mocks to satisfy root application state on boot.
@@ -1763,161 +1810,408 @@ export default [
   { action: 'GET_USER_PROFILE', data: { id: 1, name: 'Agent', role: 'admin' } }
 ];
 `;
-        fs8.writeFileSync(mocksPath, mocksContent, "utf8");
-        console.log(`\u2705 Base global mocks generated at: ${mocksPath}`);
+    fs9.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`);
+}
+var init_templateInit = __esm({
+  "src/app/lib/templateInit.ts"() {
+    "use strict";
+  }
+});
+
+// src/app/lib/scenarioFinder.ts
+import path10 from "path";
+import fs10 from "fs";
+async function findScenarios(dir, specificName) {
+  const results = [];
+  if (!fs10.existsSync(dir)) return results;
+  const items = fs10.readdirSync(dir, { withFileTypes: true });
+  for (const item of items) {
+    const fullPath = path10.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")) {
+      if (!specificName || item.name.startsWith(specificName)) {
+        results.push(fullPath);
       }
-      console.log(`\u{1F449} Run tests with: npx agent-lens --scenario=template --mode=preview`);
     }
-    if (options.help) {
-      printHelp();
-      process.exit(0);
+  }
+  return results;
+}
+function resolveScenariosDirectory(customDir) {
+  if (customDir) {
+    return path10.resolve(process.cwd(), customDir);
+  }
+  const candidates = [
+    "scenarios",
+    "tests/visual",
+    "tests/scenarios",
+    "test/scenarios",
+    "src/scenarios"
+  ];
+  for (const c of candidates) {
+    const p = path10.resolve(process.cwd(), c);
+    if (fs10.existsSync(p)) {
+      return p;
     }
-    async function findScenarios(dir, specificName) {
-      const results = [];
-      if (!fs8.existsSync(dir)) return results;
-      const items = fs8.readdirSync(dir, { withFileTypes: true });
-      for (const item of items) {
-        const fullPath = path8.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")) {
-          if (!specificName || item.name.startsWith(specificName)) {
-            results.push(fullPath);
-          }
-        }
-      }
-      return results;
+  }
+  return path10.resolve(process.cwd(), "scenarios");
+}
+var init_scenarioFinder = __esm({
+  "src/app/lib/scenarioFinder.ts"() {
+    "use strict";
+  }
+});
+
+// src/plugins/live-controller/session.ts
+import fs11 from "fs";
+import path11 from "path";
+import treeKill2 from "tree-kill";
+function getLiveArtifactsDir() {
+  if (!fs11.existsSync(LIVE_ARTIFACTS_DIR)) {
+    fs11.mkdirSync(LIVE_ARTIFACTS_DIR, { recursive: true });
+  }
+  return LIVE_ARTIFACTS_DIR;
+}
+function readLiveSession() {
+  if (!fs11.existsSync(SESSION_FILE)) return null;
+  try {
+    return JSON.parse(fs11.readFileSync(SESSION_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveLiveSession(info) {
+  if (!fs11.existsSync(SESSION_DIR)) {
+    fs11.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+  fs11.writeFileSync(SESSION_FILE, JSON.stringify(info, null, 2), "utf-8");
+}
+function clearLiveSession() {
+  if (fs11.existsSync(SESSION_FILE)) {
+    try {
+      fs11.unlinkSync(SESSION_FILE);
+    } catch {
     }
-    function resolveScenariosDirectory(customDir) {
-      if (customDir) {
-        return path8.resolve(process.cwd(), customDir);
-      }
-      const candidates = [
-        "scenarios",
-        "tests/visual",
-        "tests/scenarios",
-        "test/scenarios",
-        "src/scenarios"
-      ];
-      for (const c of candidates) {
-        const p = path8.resolve(process.cwd(), c);
-        if (fs8.existsSync(p)) {
-          return p;
-        }
-      }
-      return path8.resolve(process.cwd(), "scenarios");
+  }
+}
+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 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(() => {
+    });
+  } catch {
+  }
+  if (session.pid) {
+    await new Promise((resolve) => {
+      treeKill2(session.pid, "SIGTERM", () => resolve());
+    });
+  }
+  clearLiveSession();
+  console.log(`\u{1F6D1} [Live] Session stopped and cleaned up.`);
+  return true;
+}
+var SESSION_DIR, SESSION_FILE, LIVE_ARTIFACTS_DIR;
+var init_session = __esm({
+  "src/plugins/live-controller/session.ts"() {
+    "use strict";
+    init_playwrightLoader();
+    SESSION_DIR = path11.resolve(process.cwd(), ".agent-lens");
+    SESSION_FILE = path11.join(SESSION_DIR, "live-session.json");
+    LIVE_ARTIFACTS_DIR = path11.resolve(process.cwd(), "artifacts", "live");
+  }
+});
+
+// src/plugins/live-controller/actions.ts
+import path12 from "path";
+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 = path12.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 });
+  }
+  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;
     }
-    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
-        });
-        process.exit(snapSuccess ? 0 : 1);
+    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;
       }
-      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);
+      await snapLive(page, { name: "current" });
+      return true;
+    }
+    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 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`);
+      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;
+    }
+  }
+}
+var init_actions = __esm({
+  "src/plugins/live-controller/actions.ts"() {
+    "use strict";
+    init_session();
+    init_playwrightLoader();
+  }
+});
+
+// src/app/cli.ts
+import path13 from "path";
+import fs12 from "fs";
+import { execSync } from "child_process";
+import { createJiti as createJiti2 } from "jiti";
+var require_cli = __commonJS({
+  "src/app/cli.ts"() {
+    init_config();
+    init_runner2();
+    init_snap();
+    init_argsParser();
+    init_help();
+    init_templateInit();
+    init_scenarioFinder();
+    init_actions();
+    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);
       }
-      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);
-        }
-      } 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 = createJiti(process.cwd());
-      let globalMocks = [];
-      const mockCandidates = [
-        path8.join(scenariosDir, "mocks.ts"),
-        path8.join(scenariosDir, "mocks.js"),
-        path8.join(process.cwd(), "mocks.ts"),
-        path8.join(process.cwd(), "mocks.js")
-      ];
-      for (const mocksPath of mockCandidates) {
-        if (fs8.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 ${path8.basename(mocksPath)}`);
-            break;
-          } catch (err) {
-            console.warn(`\u26A0\uFE0F Failed to load global mocks from ${mocksPath}:`, err);
-          }
-        }
+      if (options.help) {
+        printHelp();
+        process.exit(0);
       }
-      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 ${path8.basename(scenarioPath)} does not export a VisualScenario object by default.`);
-            continue;
-          }
-          const result = await runVisualScenario({
-            scenario,
-            targetMode: options.mode,
+      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 ? path8.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 {
+            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 = createJiti2(process.cwd());
+        let globalMocks = [];
+        const mockCandidates = [
+          path13.join(scenariosDir, "mocks.ts"),
+          path13.join(scenariosDir, "mocks.js"),
+          path13.join(process.cwd(), "mocks.ts"),
+          path13.join(process.cwd(), "mocks.js")
+        ];
+        for (const mocksPath of mockCandidates) {
+          if (fs12.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 ${path13.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 ${path13.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 ? path13.resolve(process.cwd(), options.outDir) : void 0,
+              globalMocks,
+              plugins: scenarioPlugins
+            });
+            if (!result.success) {
+              allSuccess = false;
+            }
+          } catch (err) {
+            console.error(`\u274C Failed to load scenario ${path13.basename(scenarioPath)}:`, err);
             allSuccess = false;
           }
-        } catch (err) {
-          console.error(`\u274C Failed to load scenario ${path8.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);
-    });
   }
 });
 export default require_cli();