@_deep4wee/agent-lens 1.1.0 → 1.2.0

package/dist/cli.js

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