@_deep4wee/agent-lens 1.0.1 → 1.2.0

package/dist/index.js

@@ -1,7 +1,9 @@
 "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 __export = (target, all) => {
   for (var name in all)
@@ -15,19 +17,44 @@ var __copyProps = (to, from, except, desc) => {
   }
   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
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/shared/api/dsl.ts
-var dsl_exports = {};
-__export(dsl_exports, {
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CaptureEngine: () => CaptureEngine,
+  ConsoleTracker: () => ConsoleTracker,
+  PluginManager: () => PluginManager,
   VIEWPORT_PRESETS: () => VIEWPORT_PRESETS,
-  defineVisualTest: () => defineVisualTest
+  VisualReporter: () => VisualReporter,
+  definePlugin: () => definePlugin,
+  defineVisualTest: () => defineVisualTest,
+  detectStartCwd: () => detectStartCwd,
+  loadConfig: () => loadConfig,
+  resolveWwwrootDir: () => resolveWwwrootDir,
+  runQuickSnap: () => runQuickSnap,
+  runVisualScenario: () => runVisualScenario
 });
-module.exports = __toCommonJS(dsl_exports);
+module.exports = __toCommonJS(src_exports);
+
+// src/shared/api/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// 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 },
@@ -37,9 +64,1480 @@ var VIEWPORT_PRESETS = {
 function defineVisualTest(scenario) {
   return scenario;
 }
+
+// src/features/runner/runner.ts
+var import_path7 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+
+// 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, 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 (options?.selector) {
+      const element = await page.waitForSelector(options.selector, { timeout: 5e3 });
+      await element.screenshot({ path: filePath });
+    } else {
+      await page.screenshot({ path: filePath, fullPage: options?.fullPage ?? false });
+    }
+    const metadata = {
+      index: this.currentStepIndex,
+      name,
+      fileName,
+      filePath,
+      relativeUri: `./${fileName}`,
+      viewport,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      selector: options?.selector
+    };
+    this.recordedSnapshots.push(metadata);
+    return metadata;
+  }
+  /**
+   */
+  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(options.durationMs, 50);
+    const interval = Math.max(options.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 (options.selector) {
+        const element = await page.$(options.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: options.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 relativeLink = snap.relativeUri || `./${snap.fileName}`;
+      rows.push(
+        `| **${String(snap.index).padStart(2, "0")}** | \`${snap.viewport.width}x${snap.viewport.height}\` | ${snap.name} | [${snap.fileName}](${relativeLink}) |`
+      );
+    }
+    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 relativeLink = frame.relativeUri || `./${frame.fileName}`;
+          burstSections += `| Frame ${frame.frameIndex} | \`${frame.viewport.width}x${frame.viewport.height}\` | [${frame.fileName}](${relativeLink}) | ![](${relativeLink}) |
+`;
+        }
+        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)*
+`;
+      }
+    }
+    let pluginSections = "";
+    if (data.customSections && data.customSections.length > 0) {
+      for (const sec of data.customSections) {
+        pluginSections += `
+## ${sec.title}
+
+${sec.content}
+
+`;
+      }
+    }
+    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}
+${pluginSections}
+---
+
+## \u{1F4CB} AI Agent Verification Checklist:
+- [ ] **Console Errors**: ${consoleErrors.length === 0 ? "\u2705 No errors found" : `\u274C ${consoleErrors.length} errors \u2014 MUST REVIEW`}
+- [ ] **Visual Layout Check**: Inspect snapshots (e.g. view_image on \`./01_${regularSnapshots[0]?.fileName || "quick_snap"}\`) for layout shifts or clipped elements.
+- [ ] **Responsiveness at \`1024x768\`**: Elements do not overflow the screen, no unwanted horizontal scroll.
+        
+- [ ] **Typography & Spacing**: Spacing matches the design system and layout grids.
+- [ ] **Color Palette & Theme**: Background tints and button accent colors match the concept.
+- [ ] **Component States**: Modals open centered, dropdowns do not overlap with other layers (z-index).
+- [ ] **Localization**: Verify that there are no raw i18n keys (text with dots like \`sidebar.home\` instead of "Home").
+
+`;
+    import_fs2.default.writeFileSync(reportPath, reportContent, "utf-8");
+    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/previewDriver.ts
+var import_http = __toESM(require("http"));
+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 (...args) => {
+        try {
+          return await target.launch(...args);
+        } catch (err) {
+          if (err.message?.includes("Executable doesn't exist") || err.message?.includes("playwright install") || err.message?.includes("browser has not been downloaded")) {
+            console.error("\n\u274C [AgentLens] Playwright Chromium browser binary is missing!");
+            console.error("\u{1F449} Please install it by running: npx playwright install chromium\n");
+          }
+          throw err;
+        }
+      };
+    }
+    const val = Reflect.get(target, prop, receiver);
+    return typeof val === "function" ? val.bind(target) : val;
+  }
+});
+
+// src/shared/lib/config.ts
+var import_path3 = __toESM(require("path"));
+var import_fs3 = __toESM(require("fs"));
+function loadConfig(cwd = process.cwd()) {
+  const jsonConfigPath = import_path3.default.join(cwd, "agent-lens.json");
+  if (import_fs3.default.existsSync(jsonConfigPath)) {
+    try {
+      const raw = import_fs3.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_path3.default.join(cwd, "package.json");
+  if (import_fs3.default.existsSync(packageJsonPath)) {
+    try {
+      const raw = import_fs3.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_path3.default.resolve(process.cwd(), providedCwd);
+    if (import_fs3.default.existsSync(resolved)) {
+      return providedCwd;
+    }
+  }
+  const rootPkgPath = import_path3.default.join(process.cwd(), "package.json");
+  let rootHasDevScript = false;
+  if (import_fs3.default.existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(import_fs3.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_path3.default.join(process.cwd(), candidate, "package.json");
+    if (import_fs3.default.existsSync(candidatePkg)) {
+      return `./${candidate}`;
+    }
+  }
+  return void 0;
+}
+function resolveWwwrootDir(customDir) {
+  if (customDir) {
+    return import_path3.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_path3.default.resolve(process.cwd(), c);
+    if (import_fs3.default.existsSync(candidatePath) && import_fs3.default.existsSync(import_path3.default.join(candidatePath, "index.html"))) {
+      return candidatePath;
+    }
+  }
+  for (const c of candidates) {
+    const candidatePath = import_path3.default.resolve(process.cwd(), c);
+    if (import_fs3.default.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+  return import_path3.default.resolve(process.cwd(), "dist");
+}
+
+// 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 = "";
+  initialRouteMocks = [];
+  constructor(options) {
+    this.options = options || {};
+    if (!this.options.url) {
+      this.options.wwwrootDir = resolveWwwrootDir(this.options.wwwrootDir);
+    }
+  }
+  get baseUrl() {
+    return this._baseUrl;
+  }
+  async start(initialViewport = { width: 1200, height: 800 }) {
+    let targetUrl = this.options.url;
+    if (!targetUrl) {
+      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_http.default.createServer((req, res) => {
+          let reqUrl = req.url?.split("?")[0] || "/";
+          if (reqUrl === "/") reqUrl = "/index.html";
+          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_fs4.default.existsSync(safePath) || import_fs4.default.statSync(safePath).isDirectory()) {
+            safePath = import_path4.default.join(this.options.wwwrootDir, "index.html");
+          }
+          const ext = import_path4.default.extname(safePath).toLowerCase();
+          const contentType = MIME_TYPES[ext] || "application/octet-stream";
+          try {
+            const content = import_fs4.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 chromium.launch({
+      headless: !this.options.headed,
+      args: ["--no-sandbox", "--disable-setuid-sandbox"]
+    });
+    this.context = await this.browser.newContext({
+      viewport: initialViewport,
+      deviceScaleFactor: 1
+    });
+    this.page = await this.context.newPage();
+    if (this.initialRouteMocks.length > 0) {
+      for (const entry of this.initialRouteMocks) {
+        await this.addRouteMock(entry);
+      }
+    }
+    await this.page.goto(targetUrl, { waitUntil: "domcontentloaded" });
+    return { page: this.page, context: this.context, browser: this.browser };
+  }
+  async addRouteMock(entry) {
+    if (!this.page) {
+      this.initialRouteMocks.push(entry);
+      return;
+    }
+    await this.page.route(entry.url, async (route) => {
+      const req = route.request();
+      if (entry.method && req.method().toUpperCase() !== entry.method.toUpperCase()) {
+        return route.continue();
+      }
+      if (entry.delayMs) {
+        await new Promise((r) => setTimeout(r, entry.delayMs));
+      }
+      const isJson = typeof entry.body === "object" && entry.body !== null;
+      await route.fulfill({
+        status: entry.status ?? 200,
+        contentType: isJson ? "application/json" : "text/plain; charset=utf-8",
+        body: isJson ? JSON.stringify(entry.body) : String(entry.body ?? ""),
+        headers: entry.headers
+      });
+    });
+  }
+  async setupRouteMocks(routes) {
+    for (const r of routes) {
+      await this.addRouteMock(r);
+    }
+  }
+  async 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_process = require("child_process");
+var import_tree_kill = __toESM(require("tree-kill"));
+var ProcessManager = class {
+  childProcess = null;
+  isStopped = false;
+  async start(command, options) {
+    const cwd = options?.cwd || process.cwd();
+    console.log(`\u{1F680} [ProcessManager] Starting command: "${command}" in ${cwd}`);
+    this.childProcess = (0, import_child_process.spawn)(command, {
+      cwd,
+      env: { ...process.env, ...options?.env },
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    this.childProcess.stdout?.on("data", (chunk) => {
+      const line = chunk.toString().trim();
+      if (line) {
+      }
+    });
+    this.childProcess.stderr?.on("data", (chunk) => {
+      const line = chunk.toString().trim();
+      if (line && !line.includes("ExperimentalWarning")) {
+      }
+    });
+    this.childProcess.on("exit", (code, signal) => {
+      if (!this.isStopped && code !== 0 && code !== null) {
+        console.warn(`\u26A0\uFE0F [ProcessManager] Subprocess exited prematurely with code ${code}, signal ${signal}`);
+      }
+    });
+  }
+  async waitForUrl(url, timeoutMs = 3e4) {
+    console.log(`\u23F3 [ProcessManager] Waiting for ${url} to respond...`);
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      if (this.childProcess && this.childProcess.exitCode !== null) {
+        throw new Error(
+          `[ProcessManager] Server process exited with code ${this.childProcess.exitCode} while waiting for ${url}`
+        );
+      }
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(1e3) });
+        if (response.status) {
+          console.log(`\u2705 [ProcessManager] Target ${url} is ready (status: ${response.status})!`);
+          return true;
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    throw new Error(`[ProcessManager] Timeout after ${timeoutMs}ms waiting for ${url} to respond.`);
+  }
+  async stop() {
+    if (this.isStopped || !this.childProcess || !this.childProcess.pid) {
+      return;
+    }
+    this.isStopped = true;
+    const pid = this.childProcess.pid;
+    console.log(`\u{1F6D1} [ProcessManager] Terminating process tree for PID ${pid}...`);
+    await new Promise((resolve) => {
+      (0, import_tree_kill.default)(pid, "SIGTERM", (err) => {
+        if (err) {
+          try {
+            (0, import_tree_kill.default)(pid, "SIGKILL");
+          } catch {
+          }
+        }
+        resolve();
+      });
+    });
+    this.childProcess = null;
+  }
+};
+
+// 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 = options.artifactsRoot || import_path7.default.resolve(process.cwd(), "artifacts");
+  if (options.cleanArtifacts && import_fs7.default.existsSync(artifactsRoot)) {
+    console.log(`\u{1F9F9} [Clean Artifacts] Purging previous artifact runs in ${artifactsRoot}...`);
+    const entries = import_fs7.default.readdirSync(artifactsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      import_fs7.default.rmSync(import_path7.default.join(artifactsRoot, entry.name), { recursive: true, force: true });
+    }
+  }
+  const scenarioArtifactsDir = import_path7.default.join(artifactsRoot, `${scenario.id}_${timestamp}`);
+  if (!import_fs7.default.existsSync(scenarioArtifactsDir)) {
+    import_fs7.default.mkdirSync(scenarioArtifactsDir, { recursive: true });
+  }
+  const captureEngine = new CaptureEngine(scenarioArtifactsDir);
+  const consoleTracker = new ConsoleTracker();
+  const defaultViewport = scenario.viewports?.[0] || VIEWPORT_PRESETS.DEFAULT;
+  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;
+    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 (options.startCommand) {
+      processManager = new ProcessManager();
+      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();
+    }
+    const customSession = await pluginManager.launchSession(
+      { currentViewport, headed: options.headed },
+      hookContext
+    );
+    if (customSession) {
+      page = customSession.page;
+      context = customSession.context;
+      if (customSession.stop) {
+        customDriverStop = customSession.stop;
+      }
+    } else if (targetMode === "desktop") {
+      throw new Error(
+        `[AgentLens] Target mode is 'desktop', but no desktop plugin is registered. Please add --plugin=desktop-webview2 to your command or configuration.`
+      );
+    } else {
+      previewDriver = new PreviewDriver({
+        wwwrootDir: options.wwwrootDir,
+        url: options.url,
+        headed: options.headed
+      });
+      if (scenario.mockRoutes && scenario.mockRoutes.length > 0) {
+        console.log(`\u{1F310} [Mock Network] Queuing ${scenario.mockRoutes.length} route mock(s)`);
+        await previewDriver.setupRouteMocks(scenario.mockRoutes);
+      }
+      const res = await previewDriver.start(currentViewport);
+      page = res.page;
+      context = res.context;
+      if (scenario.mockRoutes && scenario.mockRoutes.length > 0) {
+        await previewDriver.setupRouteMocks(scenario.mockRoutes);
+      }
+    }
+    await pluginManager.runOnContextCreated(context, hookContext);
+    await pluginManager.runOnPageCreated(page, context, hookContext);
+    consoleTracker.attach(page);
+    console.log(`\u{1F50D} [Console Tracker] Attached \u2014 errors and warnings will be captured
+`);
+    const doNavigate = createNavigator(page, previewDriver?.baseUrl, options.url);
+    if (scenario.route) {
+      console.log(`\u{1F9ED} [Runner] Navigating to initial route: ${scenario.route}`);
+      await doNavigate(scenario.route);
+    }
+    const { ctx } = buildTestContext({
+      page,
+      context,
+      targetMode,
+      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();
+    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 reportData = {
+      scenario,
+      snapshots,
+      consoleErrors,
+      consoleWarnings,
+      outputDir: scenarioArtifactsDir,
+      targetMode,
+      durationMs,
+      customSections: []
+    };
+    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}`);
+    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 reportData = {
+      scenario,
+      snapshots,
+      consoleErrors,
+      consoleWarnings,
+      outputDir: scenarioArtifactsDir,
+      targetMode,
+      durationMs
+    };
+    const reportPath = VisualReporter.generateReport(reportData);
+    syncLatestArtifacts(artifactsRoot, scenarioArtifactsDir, reportPath, snapshots);
+    return {
+      scenarioId: scenario.id,
+      targetMode,
+      success: false,
+      totalSnapshots: snapshots.length,
+      consoleErrors: consoleErrors.length,
+      consoleWarnings: consoleWarnings.length,
+      reportPath,
+      artifactsDir: scenarioArtifactsDir,
+      error: err.message
+    };
+  } finally {
+    await pluginManager.runTeardown(hookContext);
+    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 (options.cleanPaths && options.cleanPaths.length > 0) {
+      for (const cleanTarget of options.cleanPaths) {
+        try {
+          const resolvedCleanPath = import_path7.default.resolve(process.cwd(), cleanTarget);
+          if (import_fs7.default.existsSync(resolvedCleanPath)) {
+            console.log(`\u{1F9F9} [Auto-Cleanup] Removing: ${resolvedCleanPath}`);
+            import_fs7.default.rmSync(resolvedCleanPath, { recursive: true, force: true });
+          }
+        } catch (cleanErr) {
+          console.error(`\u26A0\uFE0F [Auto-Cleanup] Failed to remove ${cleanTarget}:`, cleanErr.message);
+        }
+      }
+    }
+    if (!options.detach) {
+      if (customDriverStop) await customDriverStop();
+      if (previewDriver) await previewDriver.stop();
+      if (processManager) await processManager.stop();
+    } else {
+      console.log("\u{1F517} [Runner] Detach mode active, leaving browser/app open.");
+    }
+  }
+}
+
+// src/features/snap/snap.ts
+var import_path8 = __toESM(require("path"));
+var import_fs8 = __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];
+}
+var CANDIDATE_PORTS = [5173, 3e3, 4321, 4200, 8080, 8e3, 3001];
+async function isPortResponding(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(800) });
+    return Boolean(res.status);
+  } catch {
+    return false;
+  }
+}
+async function detectActiveDevServer() {
+  for (const port of CANDIDATE_PORTS) {
+    const url = `http://localhost:${port}`;
+    if (await isPortResponding(url)) {
+      return url;
+    }
+  }
+  return null;
+}
+async function runQuickSnap(options) {
+  let targetUrl = options.url;
+  let useStaticPreview = false;
+  let wwwrootDir;
+  if (!targetUrl && !options.start) {
+    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_fs8.default.existsSync(candidateDir) && import_fs8.default.existsSync(import_path8.default.join(candidateDir, "index.html"))) {
+        useStaticPreview = true;
+        wwwrootDir = candidateDir;
+        console.log(`\u{1F4E6} [Quick Snap] No active server found. Detected built static directory at "${candidateDir}". Launching static preview...`);
+      } else {
+        console.error(`
+\u274C [Quick Snap] No active server found on common ports (${CANDIDATE_PORTS.join(", ")}), and no static build found.`);
+        console.log(`\u{1F4A1} Suggested actions:`);
+        console.log(`   1. Pass a start command:  npx agent-lens snap --start="npm run dev"`);
+        console.log(`   2. Specify your URL:      npx agent-lens snap --url=http://localhost:8080`);
+        console.log(`   3. Build your static app: npm run build
+`);
+        return false;
+      }
+    }
+  } else if (!targetUrl && options.start) {
+    targetUrl = "http://localhost:5173";
+  }
+  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 (options.selector) {
+    console.log(`\u{1F3AF} [Quick Snap] Focused element selector: "${options.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}`, { fullPage: options.fullPage });
+      }
+      if (options.selector) {
+        ctx.log(`Focusing on selector: "${options.selector}"`);
+        try {
+          await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
+          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 "${options.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: options.mode || "preview",
+    url: useStaticPreview ? void 0 : targetUrl,
+    wwwrootDir: useStaticPreview ? wwwrootDir : 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(`
+========================================`);
+  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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CaptureEngine,
+  ConsoleTracker,
+  PluginManager,
   VIEWPORT_PRESETS,
-  defineVisualTest
+  VisualReporter,
+  definePlugin,
+  defineVisualTest,
+  detectStartCwd,
+  loadConfig,
+  resolveWwwrootDir,
+  runQuickSnap,
+  runVisualScenario
 });
 //# sourceMappingURL=index.js.map