@_deep4wee/agent-lens 1.0.1

package/dist/cli.js

@@ -0,0 +1,1853 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/app/cli.ts
+var import_path8 = __toESM(require("path"));
+var import_fs8 = __toESM(require("fs"));
+
+// src/features/runner/runner.ts
+var import_path6 = __toESM(require("path"));
+var import_fs6 = __toESM(require("fs"));
+
+// src/shared/api/dsl.ts
+var VIEWPORT_PRESETS = {
+  /** Minimum supported window size (e.g., ) */
+  MIN_SUPPORTED: { name: "min-supported", width: 1024, height: 768 },
+  /** Standard default window size (e.g., ) */
+  DEFAULT: { name: "default", width: 1200, height: 800 },
+  /** Wide screen for checking grids and tables */
+  WIDE: { name: "wide", width: 1600, height: 900 },
+  /** Full HD */
+  FULL_HD: { name: "full-hd", width: 1920, height: 1080 }
+};
+function defineVisualTest(scenario) {
+  return scenario;
+}
+
+// src/features/capture/capture.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __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 });
+    }
+  }
+  getSnapshots() {
+    return this.recordedSnapshots;
+  }
+  getOutputDir() {
+    return this.outputDir;
+  }
+  /**
+   */
+  async takeSnapshot(page, name, viewport, options2) {
+    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 });
+      await element.screenshot({ path: filePath });
+    } else {
+      await page.screenshot({ path: filePath, fullPage: options2?.fullPage ?? false });
+    }
+    const metadata = {
+      index: this.currentStepIndex,
+      name,
+      fileName,
+      filePath,
+      relativeUri: `./${fileName}`,
+      viewport,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      selector: options2?.selector
+    };
+    this.recordedSnapshots.push(metadata);
+    return metadata;
+  }
+  /**
+   */
+  async takeBurst(page, name, viewport, options2) {
+    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 totalFrames = Math.ceil(duration / interval);
+    const burstSnapshots = [];
+    const burstGroup = sanitizedName;
+    for (let frame = 0; frame <= totalFrames; frame++) {
+      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);
+        if (element) {
+          await element.screenshot({ path: filePath });
+        } else {
+          await page.screenshot({ path: filePath });
+        }
+      } else {
+        await page.screenshot({ path: filePath });
+      }
+      const meta = {
+        index: stepIndex,
+        name: `${name} (frame ${frame + 1}, +${elapsedMs}ms)`,
+        fileName,
+        filePath,
+        relativeUri: `./${fileName}`,
+        viewport,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        isBurstFrame: true,
+        burstGroup,
+        frameIndex: frame + 1,
+        selector: options2.selector
+      };
+      burstSnapshots.push(meta);
+      this.recordedSnapshots.push(meta);
+      if (frame < totalFrames) {
+        await new Promise((r) => setTimeout(r, interval));
+      }
+    }
+    return burstSnapshots;
+  }
+};
+
+// src/features/reporter/reporter.ts
+var import_fs2 = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+var VisualReporter = class {
+  static generateReport(data) {
+    const {
+      scenario,
+      snapshots,
+      consoleErrors,
+      consoleWarnings,
+      outputDir,
+      targetMode,
+      durationMs
+    } = data;
+    const manifestPath = import_path2.default.join(outputDir, "manifest.json");
+    const reportPath = import_path2.default.join(outputDir, "report.md");
+    const manifest = {
+      scenarioId: scenario.id,
+      title: scenario.title,
+      description: scenario.description,
+      targetMode,
+      durationMs,
+      totalSnapshots: snapshots.length,
+      consoleErrors: consoleErrors.length,
+      consoleWarnings: consoleWarnings.length,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      snapshots,
+      errors: consoleErrors,
+      warnings: consoleWarnings
+    };
+    import_fs2.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    const rows = [];
+    const regularSnapshots = snapshots.filter((s) => !s.isBurstFrame);
+    const burstGroups = /* @__PURE__ */ new Map();
+    snapshots.filter((s) => s.isBurstFrame && s.burstGroup).forEach((s) => {
+      const list = burstGroups.get(s.burstGroup) || [];
+      list.push(s);
+      burstGroups.set(s.burstGroup, list);
+    });
+    for (const snap of regularSnapshots) {
+      const fileUri = `file:///${snap.filePath.replace(/\\/g, "/")}`;
+      rows.push(
+        `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${fileUri}) |`
+      );
+    }
+    let burstSections = "";
+    if (burstGroups.size > 0) {
+      burstSections += `
+### \u{1F3AC} Animation Bursts
+
+`;
+      for (const [group, frames] of burstGroups.entries()) {
+        burstSections += `#### Animation: \`${group}\` (${frames.length} frames)
+
+`;
+        burstSections += `| Frame | Viewport | File | Preview |
+| :--- | :--- | :--- | :--- |
+`;
+        for (const frame of frames) {
+          const fileUri = `file:///${frame.filePath.replace(/\\/g, "/")}`;
+          burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${fileUri}) | ![](${fileUri}) |
+`;
+        }
+        burstSections += `
+`;
+      }
+    }
+    const healthStatus = this.getHealthStatus(consoleErrors, consoleWarnings);
+    let consoleSections = "";
+    if (consoleErrors.length > 0) {
+      consoleSections += `
+## \u{1F534} Console Errors (${consoleErrors.length})
+
+`;
+      consoleSections += `> [!CAUTION]
+> Found **${consoleErrors.length}** JavaScript errors during the test. This might indicate broken components, missing data, or unhandled exceptions.
+
+`;
+      consoleSections += `| # | Time | Error | URL |
+| :-: | :--- | :--- | :--- |
+`;
+      consoleErrors.forEach((err, i) => {
+        const time = err.timestamp.split("T")[1]?.slice(0, 8) || "";
+        const text = err.text.replace(/\|/g, "\\|").slice(0, 200);
+        const url = err.url.replace(/\|/g, "\\|");
+        consoleSections += `| ${i + 1} | \`${time}\` | ${text} | \`${url}\` |
+`;
+      });
+      const withStack = consoleErrors.filter((e) => e.stack);
+      if (withStack.length > 0) {
+        consoleSections += `
+<details>
+<summary>\u{1F4CB} Stack Traces (${withStack.length})</summary>
+
+`;
+        withStack.forEach((err, i) => {
+          consoleSections += `**Error ${i + 1}:** \`${err.text.slice(0, 100)}\`
+\`\`\`
+${err.stack}
+\`\`\`
+
+`;
+        });
+        consoleSections += `</details>
+`;
+      }
+    }
+    if (consoleWarnings.length > 0) {
+      consoleSections += `
+## \u{1F7E1} Console Warnings (${consoleWarnings.length})
+
+`;
+      consoleSections += `| # | Warning |
+| :-: | :--- |
+`;
+      consoleWarnings.slice(0, 20).forEach((warn, i) => {
+        const text = warn.text.replace(/\|/g, "\\|").slice(0, 200);
+        consoleSections += `| ${i + 1} | ${text} |
+`;
+      });
+      if (consoleWarnings.length > 20) {
+        consoleSections += `
+*...and ${consoleWarnings.length - 20} more warnings (full list in manifest.json)*
+`;
+      }
+    }
+    const reportContent = `# \u{1F4F8} Visual Test Report: ${scenario.title}
+
+> **Scenario ID:** \`${scenario.id}\`  
+> **Target Mode:** \`${targetMode.toUpperCase()}\` (${targetMode === "desktop" ? "Native Desktop App / WebView2" : "Fast Web Preview"})  
+> **Execution Duration:** ${(durationMs / 1e3).toFixed(2)} s  
+> **Total Snapshots Captured:** ${snapshots.length}  
+> **Health Status:** ${healthStatus}  
+> **Artifacts Folder:** \`${outputDir}\`
+
+---
+
+## \u{1F5BC}\uFE0F Primary Snapshot Overview
+
+| # | Viewport | Step Description | File Reference |
+| :-: | :--- | :--- | :--- |
+${rows.join("\n")}
+
+${burstSections}
+${consoleSections}
+---
+
+## \u{1F4CB} AI Agent Verification Checklist:
+- [ ] **Console Errors**: ${consoleErrors.length === 0 ? "\u2705 No errors found" : `\u274C ${consoleErrors.length} errors \u2014 MUST REVIEW`}
+- [ ] **Responsiveness at \`1024x768\`**: Elements do not overflow the screen, no unwanted horizontal scroll.
+- [ ] **Typography & Spacing**: Spacing matches the design system and layout grids.
+- [ ] **Color Palette & Theme**: Background tints and button accent colors match the concept.
+- [ ] **Component States**: Modals open centered, dropdowns do not overlap with other layers (z-index).
+- [ ] **Localization**: Verify that there are no raw i18n keys (text with dots like \`sidebar.home\` instead of "Home").
+
+`;
+    import_fs2.default.writeFileSync(reportPath, reportContent, "utf-8");
+    return reportPath;
+  }
+  static getHealthStatus(errors, warnings) {
+    if (errors.length === 0 && warnings.length === 0) {
+      return "\u2705 Healthy \u2014 no errors or warnings";
+    }
+    if (errors.length === 0 && warnings.length > 0) {
+      return `\u26A0\uFE0F Warnings (${warnings.length}) \u2014 no critical errors`;
+    }
+    return `\u274C ERRORS (${errors.length} errors, ${warnings.length} warnings) \u2014 requires attention`;
+  }
+};
+
+// src/features/console-tracker/consoleTracker.ts
+var ConsoleTracker = class {
+  entries = [];
+  attached = false;
+  /**
+   */
+  attach(page) {
+    if (this.attached) return;
+    this.attached = true;
+    page.on("console", (msg) => {
+      const type = msg.type();
+      const level = this.mapConsoleType(type);
+      const entry = {
+        level,
+        text: msg.text(),
+        url: page.url(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.entries.push(entry);
+      if (level === "error") {
+        console.log(`\u{1F534} [Console ERROR] ${msg.text()}`);
+      } else if (level === "warning") {
+        if (!this.isIgnoredWarning(msg.text())) {
+          console.log(`\u{1F7E1} [Console WARN] ${msg.text()}`);
+        }
+      }
+    });
+    page.on("pageerror", (error) => {
+      const entry = {
+        level: "error",
+        text: error.message,
+        url: page.url(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        stack: error.stack
+      };
+      this.entries.push(entry);
+      console.log(`\u{1F4A5} [Page ERROR] ${error.message}`);
+    });
+  }
+  getErrors() {
+    return this.entries.filter((e) => e.level === "error");
+  }
+  getWarnings() {
+    return this.entries.filter((e) => e.level === "warning").filter((e) => !this.isIgnoredWarning(e.text));
+  }
+  getAll() {
+    return [...this.entries];
+  }
+  get errorCount() {
+    return this.getErrors().length;
+  }
+  get warningCount() {
+    return this.getWarnings().length;
+  }
+  get hasErrors() {
+    return this.errorCount > 0;
+  }
+  clear() {
+    this.entries = [];
+  }
+  mapConsoleType(type) {
+    switch (type) {
+      case "error":
+        return "error";
+      case "warning":
+        return "warning";
+      case "info":
+        return "info";
+      case "debug":
+        return "debug";
+      default:
+        return "log";
+    }
+  }
+  /**
+   */
+  isIgnoredWarning(text) {
+    const ignoredPatterns = [
+      "findDOMNode is deprecated",
+      // Chromium DevTools
+      "DevTools",
+      // Playwright injection
+      "__playwright",
+      "[vite]",
+      // React 18 hydration warnings
+      "Extra attributes from the server",
+      "Download the React DevTools"
+    ];
+    return ignoredPatterns.some((pattern) => text.includes(pattern));
+  }
+};
+
+// src/shared/drivers/desktopDriver.ts
+var import_child_process = require("child_process");
+var import_http = __toESM(require("http"));
+var import_path3 = __toESM(require("path"));
+var import_fs3 = __toESM(require("fs"));
+
+// src/shared/lib/playwrightLoader.ts
+var import_playwright = require("playwright");
+
+// src/shared/drivers/desktopDriver.ts
+var DesktopDriver = class {
+  port;
+  executablePath;
+  autoLaunch;
+  args;
+  env;
+  cwd;
+  childProcess = null;
+  browser = null;
+  context = null;
+  page = null;
+  processStderr = "";
+  processExited = false;
+  exitCode = null;
+  constructor(options2) {
+    this.port = options2?.port || 9222;
+    this.autoLaunch = options2?.autoLaunch ?? true;
+    this.executablePath = options2?.executablePath;
+    this.args = options2?.args || [];
+    this.env = options2?.env || {};
+    this.cwd = options2?.cwd;
+  }
+  async isPortAvailable() {
+    return new Promise((resolve) => {
+      const req = import_http.default.get(`http://127.0.0.1:${this.port}/json/version`, (res) => {
+        resolve(res.statusCode === 200);
+      });
+      req.on("error", () => resolve(false));
+      req.setTimeout(800, () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+  async waitForPort(timeoutMs = 25e3) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      if (this.processExited) {
+        throw new Error(
+          `[DesktopDriver] Process terminated prematurely with exit code ${this.exitCode}.
+Stderr: ${this.processStderr.trim() || "(none)"}`
+        );
+      }
+      if (await this.isPortAvailable()) {
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 400));
+    }
+    throw new Error(
+      `Timeout waiting for WebView2/Chromium CDP port ${this.port}. Last stderr:
+${this.processStderr.trim() || "(no stderr output)"}`
+    );
+  }
+  async start(initialViewport = { width: 1200, height: 800 }) {
+    const alreadyRunning = await this.isPortAvailable();
+    if (!alreadyRunning) {
+      if (!this.autoLaunch) {
+        throw new Error(
+          `App is not running on port ${this.port} and autoLaunch is false. Start app with WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=${this.port}`
+        );
+      }
+      if (!this.executablePath) {
+        throw new Error(
+          `[DesktopDriver] No executablePath provided and nothing is running on port ${this.port}. Specify --exe=<path> in CLI or executablePath in config.`
+        );
+      }
+      const resolvedExe = import_path3.default.resolve(process.cwd(), this.executablePath);
+      if (!import_fs3.default.existsSync(resolvedExe)) {
+        throw new Error(
+          `[DesktopDriver] Desktop executable not found at: ${resolvedExe}. Please build your native project first.`
+        );
+      }
+      console.log(`[DesktopDriver] Launching: ${resolvedExe}`);
+      const mergedEnv = {
+        ...process.env,
+        ...this.env,
+        WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: `--remote-debugging-port=${this.port}`
+      };
+      this.processStderr = "";
+      this.processExited = false;
+      this.exitCode = null;
+      this.childProcess = (0, import_child_process.spawn)(resolvedExe, this.args, {
+        env: mergedEnv,
+        cwd: this.cwd || import_path3.default.dirname(resolvedExe),
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: false
+      });
+      this.childProcess.stderr?.on("data", (chunk) => {
+        this.processStderr += chunk.toString();
+      });
+      this.childProcess.on("exit", (code) => {
+        this.processExited = true;
+        this.exitCode = code;
+      });
+      this.childProcess.on("error", (err) => {
+        console.error("[DesktopDriver] Failed to spawn process:", err);
+      });
+      console.log(`[DesktopDriver] Waiting for CDP debugging port on ${this.port}...`);
+      await this.waitForPort();
+    } else {
+      console.log(`[DesktopDriver] Attached to already running process on port ${this.port}`);
+    }
+    console.log(`[DesktopDriver] Connecting Playwright CDP to http://127.0.0.1:${this.port}...`);
+    this.browser = await import_playwright.chromium.connectOverCDP(`http://127.0.0.1:${this.port}`);
+    const contexts = this.browser.contexts();
+    this.context = contexts[0] || await this.browser.newContext();
+    const pages = this.context.pages();
+    if (pages.length > 0) {
+      this.page = pages[0];
+    } else {
+      this.page = await this.context.waitForEvent("page", { timeout: 1e4 });
+    }
+    if (initialViewport) {
+      await this.page.setViewportSize(initialViewport).catch(() => {
+      });
+    }
+    return { page: this.page, context: this.context, browser: this.browser };
+  }
+  async stop() {
+    if (this.browser) {
+      await this.browser.close().catch(() => {
+      });
+      this.browser = null;
+    }
+    if (this.childProcess && !this.childProcess.killed) {
+      console.log("[DesktopDriver] Terminating spawned desktop process...");
+      try {
+        if (process.platform === "win32" && this.childProcess.pid) {
+          (0, import_child_process.spawn)("taskkill", ["/pid", String(this.childProcess.pid), "/T", "/F"], { stdio: "ignore" });
+        } else {
+          this.childProcess.kill("SIGTERM");
+        }
+      } catch {
+      }
+      this.childProcess = null;
+    }
+  }
+};
+
+// src/shared/drivers/previewDriver.ts
+var import_http2 = __toESM(require("http"));
+var import_fs5 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
+
+// src/features/mock-ipc/mockIpc.ts
+var MockIpcRegistry = class {
+  mocks = /* @__PURE__ */ new Map();
+  set(action, data, options2) {
+    this.mocks.set(action, {
+      action,
+      data,
+      type: options2?.type ?? "SUCCESS",
+      delayMs: options2?.delayMs ?? 20
+    });
+  }
+  setBatch(entries) {
+    for (const entry of entries) {
+      this.set(entry.action, entry.data, { type: entry.type, delayMs: entry.delayMs });
+    }
+  }
+  remove(action) {
+    this.mocks.delete(action);
+  }
+  clear() {
+    this.mocks.clear();
+  }
+  get(action) {
+    return this.mocks.get(action) ?? null;
+  }
+  toSerializable() {
+    const result = {};
+    for (const [action, entry] of this.mocks.entries()) {
+      result[action] = {
+        data: entry.data,
+        type: entry.type ?? "SUCCESS",
+        delayMs: entry.delayMs ?? 20
+      };
+    }
+    return result;
+  }
+  get size() {
+    return this.mocks.size;
+  }
+};
+function generateMockIpcScript(registry) {
+  const mocksJson = JSON.stringify(registry.toSerializable());
+  return `
+    (() => {
+      const __mockTable = ${mocksJson};
+
+      window.__visualRunnerMocks = __mockTable;
+
+      // Generic IPC mock bridge for modern web applications
+      window.__mockIpc = {
+        invoke: (action, payload) => {
+          return new Promise((resolve, reject) => {
+            const mock = window.__visualRunnerMocks[action];
+
+            if (mock) {
+              setTimeout(() => {
+                if (mock.type === 'ERROR') {
+                  reject(new Error(mock.data));
+                } else {
+                  resolve(mock.data);
+                }
+              }, mock.delayMs || 20);
+            } else {
+              console.warn('[Mock IPC] No mock for action:', action, '\u2014 returning empty SUCCESS');
+              setTimeout(() => resolve(null), 20);
+            }
+          });
+        }
+      };
+
+      // Legacy fallback for generic window.external
+      if (!window.external) {
+        window.external = {};
+      }
+      
+      window.external.sendMessage = (msg) => {
+        try {
+          const parsed = JSON.parse(msg);
+          const action = parsed.Action || parsed.action;
+          const id = parsed.Id || parsed.id;
+
+          const mock = window.__visualRunnerMocks[action];
+
+          if (mock) {
+            const response = { Id: id, Type: mock.type || 'SUCCESS', Data: mock.data };
+            setTimeout(() => {
+              const cb = window.__mockCallback;
+              if (cb) cb(JSON.stringify(response));
+            }, mock.delayMs || 20);
+          } else {
+            setTimeout(() => {
+              const cb = window.__mockCallback;
+              if (cb) cb(JSON.stringify({ Id: id, Type: 'SUCCESS', Data: null }));
+            }, 20);
+          }
+        } catch (e) {
+          console.error('[Mock IPC] Failed to process legacy message:', e);
+        }
+      };
+
+      window.external.receiveMessage = (callback) => {
+        window.__mockCallback = callback;
+      };
+
+      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');
+    })();
+  `;
+}
+
+// src/shared/lib/config.ts
+var import_fs4 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+function loadConfig(cwd = process.cwd()) {
+  const configPath = import_path4.default.join(cwd, "agent-lens.json");
+  if (import_fs4.default.existsSync(configPath)) {
+    try {
+      const raw = import_fs4.default.readFileSync(configPath, "utf8");
+      return JSON.parse(raw);
+    } catch (e) {
+      console.warn(`\u26A0\uFE0F Warning: Failed to parse agent-lens.json:`, e);
+    }
+  }
+  const pkgPath = import_path4.default.join(cwd, "package.json");
+  if (import_fs4.default.existsSync(pkgPath)) {
+    try {
+      const raw = import_fs4.default.readFileSync(pkgPath, "utf8");
+      const pkg = JSON.parse(raw);
+      if (pkg.agentLens && typeof pkg.agentLens === "object") {
+        return pkg.agentLens;
+      }
+    } catch {
+    }
+  }
+  return {};
+}
+function resolveWwwrootDir(customPath, cwd = process.cwd()) {
+  if (customPath) {
+    return import_path4.default.resolve(cwd, customPath);
+  }
+  const standardDirs = [
+    "dist",
+    "build",
+    "wwwroot",
+    "Frontend/dist",
+    "frontend/dist",
+    "client/dist",
+    "web/dist",
+    "ui/dist"
+  ];
+  for (const rel of standardDirs) {
+    const candidate = import_path4.default.resolve(cwd, rel);
+    if (import_fs4.default.existsSync(candidate) && import_fs4.default.existsSync(import_path4.default.join(candidate, "index.html"))) {
+      return candidate;
+    }
+  }
+  const foundDeepWwwroot = findDeepIndexHtmlDir(cwd, 4);
+  if (foundDeepWwwroot) {
+    return foundDeepWwwroot;
+  }
+  for (const rel of standardDirs) {
+    const candidate = import_path4.default.resolve(cwd, rel);
+    if (import_fs4.default.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return import_path4.default.resolve(cwd, "dist");
+}
+function detectStartCwd(customCwd, rootCwd = process.cwd()) {
+  if (customCwd) {
+    return import_path4.default.resolve(rootCwd, customCwd);
+  }
+  const subdirectories = ["Frontend", "frontend", "client", "web", "ui", "app"];
+  for (const sub of subdirectories) {
+    const subPkg = import_path4.default.join(rootCwd, sub, "package.json");
+    if (import_fs4.default.existsSync(subPkg)) {
+      try {
+        const json = JSON.parse(import_fs4.default.readFileSync(subPkg, "utf8"));
+        if (json.scripts && (json.scripts.dev || json.scripts.start || json.scripts.build)) {
+          return import_path4.default.join(rootCwd, sub);
+        }
+      } catch {
+      }
+    }
+  }
+  return rootCwd;
+}
+function findDeepIndexHtmlDir(dir, maxDepth, currentDepth = 0) {
+  if (currentDepth > maxDepth || !import_fs4.default.existsSync(dir)) return null;
+  try {
+    const entries = import_fs4.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "artifacts") {
+          continue;
+        }
+        const subDir = import_path4.default.join(dir, entry.name);
+        if (entry.name === "wwwroot" && import_fs4.default.existsSync(import_path4.default.join(subDir, "index.html"))) {
+          return subDir;
+        }
+        const found = findDeepIndexHtmlDir(subDir, maxDepth, currentDepth + 1);
+        if (found) return found;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+// src/shared/drivers/previewDriver.ts
+var MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf"
+};
+var PreviewDriver = class {
+  server = null;
+  browser = null;
+  context = null;
+  page = null;
+  serverPort = 0;
+  options;
+  _baseUrl = "";
+  mockRegistry;
+  constructor(options2) {
+    this.options = options2 || {};
+    if (!this.options.url) {
+      this.options.wwwrootDir = resolveWwwrootDir(this.options.wwwrootDir);
+    }
+    this.mockRegistry = new MockIpcRegistry();
+  }
+  get baseUrl() {
+    return this._baseUrl;
+  }
+  async start(initialViewport = { width: 1200, height: 800 }) {
+    let targetUrl = this.options.url;
+    if (!targetUrl) {
+      if (!import_fs5.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) => {
+          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));
+          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");
+          }
+          const ext = import_path5.default.extname(safePath).toLowerCase();
+          const contentType = MIME_TYPES[ext] || "application/octet-stream";
+          try {
+            const content = import_fs5.default.readFileSync(safePath);
+            res.writeHead(200, { "Content-Type": contentType });
+            res.end(content);
+          } catch (e) {
+            res.writeHead(500);
+            res.end(`Server error: ${e.message}`);
+          }
+        });
+        this.server.listen(0, "127.0.0.1", () => {
+          const addr = this.server?.address();
+          if (typeof addr === "object" && addr?.port) {
+            this.serverPort = addr.port;
+            this._baseUrl = `http://127.0.0.1:${this.serverPort}`;
+            resolve();
+          } else {
+            reject(new Error("Failed to acquire port for static preview server"));
+          }
+        });
+      });
+      targetUrl = `${this._baseUrl}/index.html`;
+    } else {
+      this._baseUrl = targetUrl;
+      console.log(`\u{1F310} [PreviewDriver] Connecting directly to live URL: ${targetUrl}`);
+    }
+    this.browser = await import_playwright.chromium.launch({
+      headless: !this.options.headed,
+      args: ["--no-sandbox", "--disable-setuid-sandbox"]
+    });
+    this.context = await this.browser.newContext({
+      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();
+    await this.page.goto(targetUrl, { waitUntil: "domcontentloaded" });
+    return { page: this.page, context: this.context, browser: this.browser };
+  }
+  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(() => {
+      });
+      this.context = null;
+    }
+    if (this.browser) {
+      await this.browser.close().catch(() => {
+      });
+      this.browser = null;
+    }
+    if (this.server) {
+      await new Promise((resolve) => {
+        this.server?.close(() => resolve());
+      });
+      this.server = null;
+    }
+  }
+};
+
+// src/shared/lib/processManager.ts
+var import_child_process2 = require("child_process");
+var import_tree_kill = __toESM(require("tree-kill"));
+var ProcessManager = class {
+  child = null;
+  stderrOutput = "";
+  stdoutOutput = "";
+  hasExited = false;
+  exitCode = null;
+  /**
+   * Spawns a background process (e.g. dev server, backend, or app)
+   */
+  async start(command, options2) {
+    this.stderrOutput = "";
+    this.stdoutOutput = "";
+    this.hasExited = false;
+    this.exitCode = null;
+    const cwd = options2?.cwd || process.cwd();
+    const env = { ...process.env, ...options2?.env };
+    console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
+    this.child = (0, import_child_process2.spawn)(command, {
+      cwd,
+      env,
+      shell: options2?.shell ?? true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    this.child.stdout?.on("data", (chunk) => {
+      const str = chunk.toString();
+      this.stdoutOutput += str;
+    });
+    this.child.stderr?.on("data", (chunk) => {
+      const str = chunk.toString();
+      this.stderrOutput += str;
+    });
+    this.child.on("exit", (code) => {
+      this.hasExited = true;
+      this.exitCode = code;
+    });
+    this.child.on("error", (err) => {
+      console.error(`\u274C [ProcessManager] Failed to start command: "${command}":`, err.message);
+    });
+  }
+  /**
+   * Polls a URL until it starts responding or until timeout is reached.
+   */
+  async waitForUrl(url, timeoutMs = 3e4) {
+    const startTime = Date.now();
+    console.log(`\u23F3 [ProcessManager] Waiting for URL to become available: ${url} (timeout: ${timeoutMs / 1e3}s)...`);
+    while (Date.now() - startTime < timeoutMs) {
+      if (this.hasExited && this.exitCode !== 0) {
+        throw new Error(
+          `[ProcessManager] Process exited prematurely with code ${this.exitCode}.
+Stderr:
+${this.stderrOutput.trim() || "(no stderr)"}
+Stdout:
+${this.stdoutOutput.slice(-500).trim()}`
+        );
+      }
+      try {
+        const response = await fetch(url, { method: "GET", signal: AbortSignal.timeout(2e3) });
+        if (response.status) {
+          console.log(`\u2705 [ProcessManager] Server responded with status ${response.status} at ${url}`);
+          return;
+        }
+      } catch {
+      }
+      await new Promise((resolve) => setTimeout(resolve, 350));
+    }
+    throw new Error(
+      `[ProcessManager] Timeout (${timeoutMs / 1e3}s) waiting for server at ${url}.
+Last stdout:
+${this.stdoutOutput.slice(-500).trim()}
+Last stderr:
+${this.stderrOutput.trim()}`
+    );
+  }
+  /**
+   * Gracefully and forcefully kills the process and all its children.
+   */
+  async stop() {
+    if (!this.child || !this.child.pid || this.hasExited) {
+      this.child = null;
+      return;
+    }
+    const pid = this.child.pid;
+    console.log(`\u{1F6D1} [ProcessManager] Terminating process tree (PID: ${pid})...`);
+    await new Promise((resolve) => {
+      (0, import_tree_kill.default)(pid, "SIGKILL", (err) => {
+        if (err) {
+          if (process.platform === "win32") {
+            try {
+              (0, import_child_process2.spawn)("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+            } catch {
+            }
+          }
+        }
+        resolve();
+      });
+    });
+    this.child = null;
+  }
+};
+
+// src/features/runner/runner.ts
+async function runVisualScenario(options2) {
+  const { scenario } = options2;
+  const targetMode = options2.targetMode || "preview";
+  const startTime = Date.now();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const artifactsRoot = options2.artifactsRoot || import_path6.default.resolve(process.cwd(), "artifacts");
+  if (options2.cleanArtifacts && import_fs6.default.existsSync(artifactsRoot)) {
+    console.log(`\u{1F9F9} [Clean Artifacts] Purging previous artifact runs in ${artifactsRoot}...`);
+    const entries = import_fs6.default.readdirSync(artifactsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      import_fs6.default.rmSync(import_path6.default.join(artifactsRoot, entry.name), { recursive: true, force: true });
+    }
+  }
+  const scenarioArtifactsDir = import_path6.default.join(artifactsRoot, `${scenario.id}_${timestamp}`);
+  if (!import_fs6.default.existsSync(scenarioArtifactsDir)) {
+    import_fs6.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;
+  let previewDriver = null;
+  let processManager = null;
+  try {
+    let page;
+    let context;
+    console.log(`
+========================================`);
+    console.log(`\u{1F680} Starting Visual Test: ${scenario.title}`);
+    console.log(`\u{1F3AF} Mode: ${targetMode.toUpperCase()}`);
+    console.log(`\u{1F4C1} Artifacts: ${scenarioArtifactsDir}`);
+    console.log(`========================================
+`);
+    if (options2.startCommand) {
+      processManager = new ProcessManager();
+      await processManager.start(options2.startCommand, { cwd: options2.startCwd });
+      const waitTarget = options2.url || "http://localhost:5173";
+      await processManager.waitForUrl(waitTarget);
+    }
+    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;
+    } else {
+      previewDriver = new PreviewDriver({
+        wwwrootDir: options2.wwwrootDir,
+        url: options2.url,
+        headed: options2.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);
+      }
+      const res = await previewDriver.start(currentViewport);
+      page = res.page;
+      context = res.context;
+    }
+    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);
+    };
+    if (scenario.route) {
+      console.log(`[Runner] Navigating to route: ${scenario.route}`);
+      await doNavigate(scenario.route);
+    }
+    const ctx = {
+      page,
+      context,
+      targetMode,
+      currentViewport,
+      capture: async (name, opts) => {
+        console.log(`\u{1F4F8} [Snapshot] ${name} (${currentViewport.width}x${currentViewport.height})`);
+        return await captureEngine.takeSnapshot(page, name, currentViewport, opts);
+      },
+      captureBurst: async (name, opts) => {
+        console.log(`\u{1F3AC} [Burst] ${name} (duration: ${opts.durationMs}ms, interval: ${opts.intervalMs ?? 80}ms)`);
+        return await captureEngine.takeBurst(page, name, currentViewport, opts);
+      },
+      navigate: async (route) => {
+        console.log(`\u{1F9ED} [Navigate] ${route}`);
+        await doNavigate(route);
+      },
+      // ─── Viewport ───
+      resize: async (width, height) => {
+        console.log(`\u{1F4D0} [Resize] ${width}x${height}`);
+        currentViewport = { width, height };
+        ctx.currentViewport = currentViewport;
+        await page.setViewportSize(currentViewport);
+        await page.waitForTimeout(200);
+      },
+      setPreset: async (preset) => {
+        console.log(`\u{1F4D0} [Preset] ${preset.name} (${preset.width}x${preset.height})`);
+        await ctx.resize(preset.width, preset.height);
+      },
+      resizeToFit: async (selector, padding = 0) => {
+        let boundingBox;
+        if (selector) {
+          const el = await page.$(selector);
+          if (el) {
+            boundingBox = await el.boundingBox();
+          }
+        } else {
+          boundingBox = await page.evaluate(() => {
+            return {
+              width: document.documentElement.scrollWidth,
+              height: document.documentElement.scrollHeight
+            };
+          });
+        }
+        if (boundingBox) {
+          const newWidth = Math.ceil(boundingBox.width) + padding * 2;
+          const newHeight = Math.ceil(boundingBox.height) + padding * 2;
+          console.log(`\u{1F4D0} [ResizeToFit] ${selector || "body"} -> ${newWidth}x${newHeight}`);
+          await ctx.resize(newWidth, newHeight);
+        } else {
+          console.log(`\u26A0\uFE0F [ResizeToFit] Element ${selector} not found or has no bounding box.`);
+        }
+      },
+      wait: async (ms) => {
+        await page.waitForTimeout(ms);
+      },
+      waitForSelector: async (selector, timeoutMs = 5e3) => {
+        await page.waitForSelector(selector, { timeout: timeoutMs });
+      },
+      click: async (selector) => {
+        console.log(`\u{1F5B1}\uFE0F [Click] ${selector}`);
+        await page.click(selector);
+      },
+      rightClick: async (selector) => {
+        console.log(`\u{1F5B1}\uFE0F [RightClick] ${selector}`);
+        await page.click(selector, { button: "right" });
+      },
+      type: async (selector, text) => {
+        console.log(`\u2328\uFE0F [Type] ${selector} -> "${text}"`);
+        await page.fill(selector, text);
+      },
+      selectOption: async (selector, value) => {
+        console.log(`\u2705 [Select] ${selector} -> "${value}"`);
+        await page.selectOption(selector, value);
+      },
+      hover: async (selector) => {
+        console.log(`\u{1F446} [Hover] ${selector}`);
+        await page.hover(selector);
+      },
+      scroll: async (selector, deltaY) => {
+        console.log(`\u{1F4DC} [Scroll] ${selector} by ${deltaY}px`);
+        await page.evaluate(({ sel, dY }) => {
+          const el = document.querySelector(sel);
+          if (el) {
+            el.scrollTop += dY;
+          } else {
+            window.scrollBy(0, dY);
+          }
+        }, { sel: selector, dY: deltaY });
+        await page.waitForTimeout(100);
+      },
+      log: (msg) => {
+        console.log(`\u2139\uFE0F [Scenario] ${msg}`);
+      },
+      // ─── Mock IPC ───
+      setMockIpc: async (action, data, mockOptions) => {
+        if (targetMode === "desktop") {
+          console.log(`\u26A0\uFE0F [Mock IPC] setMockIpc ignored in desktop mode (real backend handles IPC)`);
+          return;
+        }
+        if (!previewDriver) {
+          console.log(`\u26A0\uFE0F [Mock IPC] PreviewDriver not available`);
+          return;
+        }
+        console.log(`\u{1F4E6} [Mock IPC] Set ${action} -> ${typeof data === "string" ? data : JSON.stringify(data).slice(0, 80)}...`);
+        await previewDriver.updateMockIpc(action, data, mockOptions);
+      },
+      getConsoleErrors: () => consoleTracker.getErrors(),
+      getConsoleWarnings: () => consoleTracker.getWarnings(),
+      hasConsoleErrors: () => consoleTracker.hasErrors,
+      // ─── DOM Assertions ───
+      readText: async (selector) => {
+        const text = await page.textContent(selector);
+        return text ? text.trim() : null;
+      },
+      getPageText: async () => {
+        return await page.evaluate(() => document.body.innerText || "");
+      },
+      isVisible: async (selector) => {
+        try {
+          const element = await page.$(selector);
+          if (!element) return false;
+          return await element.isVisible();
+        } catch {
+          return false;
+        }
+      },
+      getElementCount: async (selector) => {
+        const elements = await page.$$(selector);
+        return elements.length;
+      }
+    };
+    await scenario.run(ctx);
+    const durationMs = Date.now() - startTime;
+    const snapshots = captureEngine.getSnapshots();
+    const consoleErrors = consoleTracker.getErrors();
+    const consoleWarnings = consoleTracker.getWarnings();
+    if (consoleErrors.length > 0) {
+      console.log(`
+\u{1F534} Console Errors: ${consoleErrors.length}`);
+      consoleErrors.forEach((err, i) => console.log(`   ${i + 1}. ${err.text.slice(0, 120)}`));
+    }
+    if (consoleWarnings.length > 0) {
+      console.log(`
+\u{1F7E1} Console Warnings: ${consoleWarnings.length}`);
+    }
+    const reportPath = VisualReporter.generateReport({
+      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;
+      }
+    };
+    const latestReport = syncLatest(reportPath, snapshots);
+    console.log(`
+\u2705 Visual Test Completed Successfully!`);
+    console.log(`\u{1F4CA} Captured Snapshots: ${snapshots.length}`);
+    console.log(`\u{1F534} Console Errors: ${consoleErrors.length}`);
+    console.log(`\u{1F7E1} Console Warnings: ${consoleWarnings.length}`);
+    console.log(`\u{1F4C4} Markdown Report: ${reportPath}`);
+    if (latestReport) {
+      console.log(`\u{1F4CC} Latest Report: ${latestReport}`);
+    }
+    return {
+      scenarioId: scenario.id,
+      targetMode,
+      success: true,
+      totalSnapshots: snapshots.length,
+      consoleErrors: consoleErrors.length,
+      consoleWarnings: consoleWarnings.length,
+      reportPath,
+      artifactsDir: scenarioArtifactsDir
+    };
+  } catch (err) {
+    console.error(`
+\u274C Visual Test Failed: ${err.message}`);
+    const durationMs = Date.now() - startTime;
+    const snapshots = captureEngine.getSnapshots();
+    const consoleErrors = consoleTracker.getErrors();
+    const consoleWarnings = consoleTracker.getWarnings();
+    const reportPath = VisualReporter.generateReport({
+      scenario,
+      snapshots,
+      consoleErrors,
+      consoleWarnings,
+      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 {
+    }
+    return {
+      scenarioId: scenario.id,
+      targetMode,
+      success: false,
+      totalSnapshots: snapshots.length,
+      consoleErrors: consoleErrors.length,
+      consoleWarnings: consoleWarnings.length,
+      reportPath,
+      artifactsDir: scenarioArtifactsDir,
+      error: err.message
+    };
+  } finally {
+    if (typeof scenario.teardown === "function") {
+      try {
+        console.log(`\u{1F9F9} [Scenario Teardown] Executing teardown hook...`);
+        await scenario.teardown();
+      } catch (teardownErr) {
+        console.error(`\u26A0\uFE0F [Scenario Teardown] Error during teardown:`, teardownErr.message);
+      }
+    }
+    if (options2.cleanPaths && options2.cleanPaths.length > 0) {
+      for (const cleanTarget of options2.cleanPaths) {
+        try {
+          const resolvedCleanPath = import_path6.default.resolve(process.cwd(), cleanTarget);
+          if (import_fs6.default.existsSync(resolvedCleanPath)) {
+            console.log(`\u{1F9F9} [Auto-Cleanup] Removing: ${resolvedCleanPath}`);
+            import_fs6.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 (previewDriver) await previewDriver.stop();
+      if (processManager) await processManager.stop();
+    } else {
+      console.log("\u{1F517} [Runner] Detach mode active, leaving browser/app open.");
+    }
+  }
+}
+
+// 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 PRESET_MAP = {
+  default: VIEWPORT_PRESETS.DEFAULT,
+  desktop: VIEWPORT_PRESETS.DEFAULT,
+  min: VIEWPORT_PRESETS.MIN_SUPPORTED,
+  "min-supported": VIEWPORT_PRESETS.MIN_SUPPORTED,
+  wide: VIEWPORT_PRESETS.WIDE,
+  mobile: { name: "mobile", width: 375, height: 667 },
+  tablet: { name: "tablet", width: 768, height: 1024 },
+  "full-hd": VIEWPORT_PRESETS.FULL_HD
+};
+function parseViewportPresets(raw) {
+  if (!raw || raw.length === 0) {
+    return [VIEWPORT_PRESETS.DEFAULT, PRESET_MAP.mobile];
+  }
+  const presets = [];
+  for (const item of raw) {
+    const lower = item.toLowerCase().trim();
+    if (PRESET_MAP[lower]) {
+      presets.push(PRESET_MAP[lower]);
+    } else if (lower.includes("x")) {
+      const [w, h] = lower.split("x").map((n) => parseInt(n, 10));
+      if (!isNaN(w) && !isNaN(h)) {
+        presets.push({ name: `${w}x${h}`, width: w, height: h });
+      }
+    }
+  }
+  return presets.length > 0 ? presets : [VIEWPORT_PRESETS.DEFAULT, PRESET_MAP.mobile];
+}
+async function isPortResponding(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(800) });
+    return Boolean(res.status);
+  } catch {
+    return false;
+  }
+}
+async function runQuickSnap(options2) {
+  let targetUrl = options2.url;
+  let useStaticPreview = false;
+  let wwwrootDir;
+  if (!targetUrl && !options2.start) {
+    if (await isPortResponding("http://localhost:5173")) {
+      targetUrl = "http://localhost:5173";
+      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:5173`);
+    } else if (await isPortResponding("http://localhost:3000")) {
+      targetUrl = "http://localhost:3000";
+      console.log(`\u{1F310} [Quick Snap] Detected active dev server on http://localhost:3000`);
+    } else {
+      const candidateDir = resolveWwwrootDir();
+      if (import_fs7.default.existsSync(candidateDir) && import_fs7.default.existsSync(import_path7.default.join(candidateDir, "index.html"))) {
+        useStaticPreview = true;
+        wwwrootDir = candidateDir;
+        console.log(`\u{1F4E6} [Quick Snap] No active server found. Detected built static directory at "${candidateDir}". Launching static preview...`);
+      } else {
+        console.error(`
+\u274C [Quick Snap] No active server found on http://localhost:5173 or :3000, and no static build found.`);
+        console.log(`\u{1F4A1} Suggested actions:`);
+        console.log(`   1. Pass a start command:  npx agent-lens snap --start="npm run dev"`);
+        console.log(`   2. Specify your URL:      npx agent-lens snap --url=http://localhost:8080`);
+        console.log(`   3. Build your static app: npm run build
+`);
+        return false;
+      }
+    }
+  } else if (!targetUrl && options2.start) {
+    targetUrl = "http://localhost:5173";
+  }
+  const waitMs = options2.waitMs ?? 1e3;
+  const snapshotPrefix = options2.name || "quick_snap";
+  const targetViewports = parseViewportPresets(options2.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}"`);
+  }
+  const snapScenario = defineVisualTest({
+    id: "quick-snap",
+    title: `Quick Verification: ${targetUrl || "Static Preview"}`,
+    description: `One-shot automated snapshot and console health check`,
+    route: targetUrl || "/",
+    viewports: targetViewports,
+    run: async (ctx) => {
+      ctx.log(`Waiting ${waitMs}ms for page stabilization...`);
+      await ctx.wait(waitMs);
+      for (let i = 0; i < targetViewports.length; i++) {
+        const vp = targetViewports[i];
+        const stepNum = String(i + 1).padStart(2, "0");
+        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}`);
+      }
+      if (options2.selector) {
+        ctx.log(`Focusing on selector: "${options2.selector}"`);
+        try {
+          await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
+          await ctx.resizeToFit(options2.selector, 15);
+          await ctx.capture(`99_${snapshotPrefix}_element_focus`, { selector: options2.selector });
+        } catch (err) {
+          ctx.log(`\u26A0\uFE0F Could not isolate selector "${options2.selector}": ${err.message}`);
+        }
+      }
+      const errors = ctx.getConsoleErrors();
+      if (errors.length > 0) {
+        ctx.log(`\u{1F6A8} Caught ${errors.length} console errors during snap check!`);
+      } else {
+        ctx.log(`\u2705 Clean run: No console errors detected.`);
+      }
+    }
+  });
+  const result = await runVisualScenario({
+    scenario: snapScenario,
+    targetMode: options2.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
+  });
+  console.log(`
+========================================`);
+  console.log(`\u{1F3C1} Quick Snap Finished!`);
+  console.log(`\u{1F4F8} Snapshots: ${result.totalSnapshots}`);
+  console.log(`\u{1F534} Console Errors: ${result.consoleErrors}`);
+  console.log(`\u{1F7E1} Console Warnings: ${result.consoleWarnings}`);
+  console.log(`\u{1F4C4} Report: ${result.reportPath}`);
+  console.log(`========================================
+`);
+  return result.success && result.consoleErrors === 0;
+}
+
+// src/app/cli.ts
+var fileConfig = loadConfig();
+var args = process.argv.slice(2);
+if (args[0] === "init") {
+  initScenarioTemplate();
+  process.exit(0);
+}
+var isSnapCommand = args[0] === "snap";
+var effectiveArgs = isSnapCommand ? args.slice(1) : args;
+var options = {
+  mode: fileConfig.mode || "preview",
+  port: fileConfig.port || 9222,
+  headed: fileConfig.headed ?? false,
+  detach: fileConfig.detach ?? false,
+  build: fileConfig.buildCommand || false,
+  start: fileConfig.startCommand,
+  startCwd: fileConfig.startCwd,
+  cleanArtifacts: fileConfig.cleanArtifacts ?? false,
+  url: fileConfig.url,
+  exe: fileConfig.executablePath,
+  clean: Array.isArray(fileConfig.clean) ? fileConfig.clean : fileConfig.clean ? [fileConfig.clean] : void 0,
+  dir: fileConfig.scenarios,
+  wwwroot: fileConfig.wwwroot,
+  outDir: fileConfig.outDir
+};
+for (const arg of effectiveArgs) {
+  if (arg === "--help" || arg === "-h") {
+    options.help = true;
+  } else if (arg.startsWith("--scenario=")) {
+    options.scenario = arg.split("=")[1];
+  } else if (arg === "--all") {
+    options.all = true;
+  } else if (arg.startsWith("--mode=")) {
+    const mode = arg.split("=")[1].toLowerCase();
+    if (mode === "desktop" || mode === "preview") {
+      options.mode = mode;
+    }
+  } else if (arg.startsWith("--port=")) {
+    options.port = parseInt(arg.split("=")[1], 10) || 9222;
+  } else if (arg === "--headed") {
+    options.headed = true;
+  } else if (arg === "--detach") {
+    options.detach = true;
+  } else if (arg === "--build") {
+    options.build = true;
+  } else if (arg.startsWith("--build=")) {
+    options.build = arg.slice("--build=".length);
+  } else if (arg.startsWith("--start=")) {
+    options.start = arg.slice("--start=".length);
+  } else if (arg.startsWith("--start-cwd=") || arg.startsWith("--cwd=")) {
+    options.startCwd = arg.split("=")[1];
+  } else if (arg === "--clean-artifacts") {
+    options.cleanArtifacts = true;
+  } else if (arg.startsWith("--url=")) {
+    options.url = arg.split("=")[1];
+  } else if (arg.startsWith("--selector=")) {
+    options.selector = arg.split("=")[1];
+  } else if (arg.startsWith("--viewports=")) {
+    options.viewports = arg.split("=")[1].split(",").map((v) => v.trim()).filter(Boolean);
+  } else if (arg.startsWith("--wait=")) {
+    options.waitMs = parseInt(arg.split("=")[1], 10);
+  } else if (arg.startsWith("--name=")) {
+    options.name = arg.split("=")[1];
+  } else if (arg.startsWith("--exe=") || arg.startsWith("--executable=")) {
+    options.exe = arg.split("=")[1];
+  } else if (arg.startsWith("--clean=") || arg.startsWith("--cleanup=")) {
+    const rawPaths = arg.split("=")[1];
+    options.clean = rawPaths.split(",").map((p) => p.trim()).filter(Boolean);
+  } else if (arg.startsWith("--dir=")) {
+    options.dir = arg.split("=")[1];
+  } else if (arg.startsWith("--wwwroot=")) {
+    options.wwwroot = arg.split("=")[1];
+  } else if (arg.startsWith("--outDir=") || arg.startsWith("--folder=")) {
+    options.outDir = arg.split("=")[1];
+  }
+}
+if (options.start && !options.startCwd) {
+  options.startCwd = detectStartCwd(options.startCwd);
+}
+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 [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
+  init                 Generate starter template in scenarios/template.scenario.ts and mocks.ts
+
+Options:
+  --url=<url>          Target URL to test (e.g. http://localhost:5173 or http://localhost:3000)
+  --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
+  --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]
+  --name=<prefix>      Custom name prefix for captured snapshots [default: quick_snap]
+  --scenario=<name>    Run specific scenario by name (e.g. --scenario=smoke)
+  --all                Run all discovered scenarios
+  --mode=<mode>        Engine mode: 'preview' (Web/Vite/Live) or 'desktop' (WebView2/CDP) [default: preview]
+  --exe=<path>         Path to native executable for desktop mode (e.g. --exe=bin/MyApp.exe)
+  --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")
+  --headed             Show Chromium browser window
+  --detach             Keep browser/app open after finishing
+  --dir=<path>         Custom scenarios directory [default: scenarios]
+  --wwwroot=<path>     Custom directory for static fallback mode [default: dist]
+  --folder=<path>      Directory to save visual artifacts/reports (also --outDir)
+  --help, -h           Show this help message
+  `);
+}
+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 templatePath = import_path8.default.join(targetDir, "template.scenario.ts");
+  if (!import_fs8.default.existsSync(templatePath)) {
+    const templateContent = `import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+
+export default defineVisualTest({
+  id: 'template-check',
+  title: 'Basic UI Smoke & Responsiveness Check',
+  route: '/',
+  // Optional setup hook before test runs
+  setup: async () => {
+    // prepare test files or folders
+  },
+  run: async (ctx) => {
+    ctx.log('Initial page render');
+    await ctx.capture('01_initial_state');
+
+    // Test adaptive layout
+    await ctx.setPreset(VIEWPORT_PRESETS.MIN_SUPPORTED);
+    await ctx.capture('02_compact_view');
+
+    // Check for JavaScript / React runtime errors
+    const errors = ctx.getConsoleErrors();
+    if (errors.length > 0) {
+      ctx.log(\`\u26A0\uFE0F Warning: Caught \${errors.length} console errors!\`);
+    }
+  },
+  // Optional teardown hook guaranteed to run on exit
+  teardown: async () => {
+    // clean up temporary test files or state
+  }
+});
+`;
+    import_fs8.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 mocksContent = `/**
+ * Global IPC & API Mocks
+ * 
+ * Export an array of base mocks to satisfy root application state on boot.
+ */
+export default [
+  { action: 'GET_PREFS', data: { theme: 'dark', language: 'en' } },
+  { action: 'GET_USER_PROFILE', data: { id: 1, name: 'Agent', role: 'admin' } }
+];
+`;
+    import_fs8.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);
+}
+async function findScenarios(dir, specificName) {
+  const results = [];
+  if (!import_fs8.default.existsSync(dir)) return results;
+  const items = import_fs8.default.readdirSync(dir, { withFileTypes: true });
+  for (const item of items) {
+    const fullPath = import_path8.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")) {
+      if (!specificName || item.name.startsWith(specificName)) {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+function resolveScenariosDirectory(customDir) {
+  if (customDir) {
+    return import_path8.default.resolve(process.cwd(), customDir);
+  }
+  const candidates = [
+    "scenarios",
+    "tests/visual",
+    "tests/scenarios",
+    "test/scenarios",
+    "src/scenarios"
+  ];
+  for (const c of candidates) {
+    const p = import_path8.default.resolve(process.cwd(), c);
+    if (import_fs8.default.existsSync(p)) {
+      return p;
+    }
+  }
+  return import_path8.default.resolve(process.cwd(), "scenarios");
+}
+async function main() {
+  if (isSnapCommand || options.url && !options.scenario && !options.all) {
+    const snapSuccess = await runQuickSnap({
+      url: options.url,
+      start: options.start,
+      startCwd: options.startCwd,
+      selector: options.selector,
+      viewports: options.viewports,
+      waitMs: options.waitMs,
+      name: options.name,
+      clean: options.clean,
+      cleanArtifacts: options.cleanArtifacts,
+      headed: options.headed,
+      detach: options.detach,
+      outDir: options.outDir,
+      mode: options.mode,
+      exe: options.exe,
+      port: options.port
+    });
+    process.exit(snapSuccess ? 0 : 1);
+  }
+  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}"...`);
+    const { execSync } = require("child_process");
+    try {
+      execSync(buildCmd, { stdio: "inherit", cwd: options.startCwd || process.cwd() });
+    } catch (e) {
+      console.error(`\u274C Build failed: ${buildCmd}`);
+      process.exit(1);
+    }
+  } else if (options.mode === "preview" && !options.url && !options.start) {
+    console.log(`\u26A0\uFE0F  Warning: Running without --build or --url flag. Make sure your frontend is built!`);
+  }
+  console.log(`\u{1F4CB} Found ${scenarioPaths.length} scenario(s) in: ${scenariosDir}`);
+  const jiti = (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);
+      }
+    }
+  }
+  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;
+      }
+      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_path8.default.resolve(process.cwd(), options.outDir) : void 0,
+        globalMocks
+      });
+      if (!result.success) {
+        allSuccess = false;
+      }
+    } catch (err) {
+      console.error(`\u274C Failed to load scenario ${import_path8.default.basename(scenarioPath)}:`, err);
+      allSuccess = false;
+    }
+  }
+  if (!allSuccess) {
+    process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map