@_deep4wee/agent-lens 1.0.1 → 1.2.0

package/dist/plugins/mock-ipc/index.mjs

@@ -0,0 +1,181 @@
+// src/shared/api/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// src/plugins/mock-ipc/registry.ts
+var MockIpcRegistry = class {
+  mocks = /* @__PURE__ */ new Map();
+  set(action, data, options) {
+    this.mocks.set(action, {
+      action,
+      data,
+      type: options?.type ?? "SUCCESS",
+      delayMs: options?.delayMs ?? 20
+    });
+  }
+  setBatch(entries) {
+    for (const entry of entries) {
+      this.set(entry.action, entry.data, { type: entry.type, delayMs: entry.delayMs });
+    }
+  }
+  remove(action) {
+    this.mocks.delete(action);
+  }
+  clear() {
+    this.mocks.clear();
+  }
+  get(action) {
+    return this.mocks.get(action) ?? null;
+  }
+  toSerializable() {
+    const result = {};
+    for (const [action, entry] of this.mocks.entries()) {
+      result[action] = {
+        data: entry.data,
+        type: entry.type ?? "SUCCESS",
+        delayMs: entry.delayMs ?? 20
+      };
+    }
+    return result;
+  }
+  get size() {
+    return this.mocks.size;
+  }
+};
+function generateMockIpcScript(registry) {
+  const mocksJson = JSON.stringify(registry.toSerializable());
+  return `
+    (() => {
+      const __mockTable = ${mocksJson};
+
+      window.__visualRunnerMocks = __mockTable;
+
+      // Generic IPC mock bridge for modern web applications
+      window.__mockIpc = {
+        invoke: (action, payload) => {
+          return new Promise((resolve, reject) => {
+            const mock = window.__visualRunnerMocks[action];
+
+            if (mock) {
+              setTimeout(() => {
+                if (mock.type === 'ERROR') {
+                  reject(new Error(mock.data));
+                } else {
+                  resolve(mock.data);
+                }
+              }, mock.delayMs || 20);
+            } else {
+              console.warn('[Mock IPC] No mock for action:', action, '\u2014 returning empty SUCCESS');
+              setTimeout(() => resolve(null), 20);
+            }
+          });
+        }
+      };
+
+      // Safe fallback bridge for hybrid webviews (Photino / CEF / WebView2)
+      try {
+        if (!window.external) {
+          window.external = {};
+        }
+        window.external.sendMessage = (msg) => {
+          try {
+            const parsed = typeof msg === 'string' ? JSON.parse(msg) : msg;
+            const action = parsed.Action || parsed.action;
+            const id = parsed.Id || parsed.id;
+            const mock = window.__visualRunnerMocks[action];
+
+            if (mock) {
+              const response = { Id: id, Type: mock.type || 'SUCCESS', Data: mock.data };
+              setTimeout(() => {
+                const cb = window.__mockCallback;
+                if (typeof cb === 'function') cb(JSON.stringify(response));
+              }, mock.delayMs || 20);
+            } else {
+              setTimeout(() => {
+                const cb = window.__mockCallback;
+                if (typeof cb === 'function') cb(JSON.stringify({ Id: id, Type: 'SUCCESS', Data: null }));
+              }, 20);
+            }
+          } catch (e) {
+            console.error('[Mock IPC] Failed to process message:', e);
+          }
+        };
+
+        window.external.receiveMessage = (callback) => {
+          window.__mockCallback = callback;
+        };
+      } catch {
+        // Ignored if window.external is read-only in strict Chromium sandboxes
+      }
+
+      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');
+    })();
+  `;
+}
+
+// src/plugins/mock-ipc/index.ts
+var STATE_KEY = "mockIpcRegistry";
+var mockIpcPlugin = definePlugin({
+  name: "mock-ipc",
+  version: "1.0.0",
+  setup: (hookContext) => {
+    const registry = new MockIpcRegistry();
+    hookContext.state.set(STATE_KEY, registry);
+    const scenarioMocks = hookContext.scenario?.mockIpc || [];
+    const globalMocks = hookContext.cliOptions?.globalMocks || [];
+    const allMocks = [...globalMocks, ...scenarioMocks];
+    if (allMocks.length > 0) {
+      console.log(`\u{1F4E6} [Plugin:mock-ipc] Pre-loading ${allMocks.length} initial IPC mocks`);
+      registry.setBatch(allMocks);
+    }
+  },
+  onContextCreated: async (context, hookContext) => {
+    const registry = hookContext.state.get(STATE_KEY) || new MockIpcRegistry();
+    const script = generateMockIpcScript(registry);
+    await context.addInitScript(script);
+    console.log(`\u{1F50C} [Plugin:mock-ipc] Injected window.__mockIpc & window.external bridge into browser context`);
+  },
+  extendContext: (_ctx, page, hookContext) => {
+    const registry = hookContext.state.get(STATE_KEY) || new MockIpcRegistry();
+    return {
+      setMockIpc: async (action, data, options) => {
+        const preview = typeof data === "string" ? data : JSON.stringify(data).slice(0, 80);
+        console.log(`\u{1F4E6} [Plugin:mock-ipc] Dynamic set: ${action} -> ${preview}`);
+        registry.set(action, data, options);
+        await page.evaluate(
+          ({ action: action2, mock }) => {
+            const w = window;
+            if (!w.__visualRunnerMocks) {
+              w.__visualRunnerMocks = {};
+            }
+            w.__visualRunnerMocks[action2] = mock;
+          },
+          {
+            action,
+            mock: {
+              data,
+              type: options?.type ?? "SUCCESS",
+              delayMs: options?.delayMs ?? 20
+            }
+          }
+        );
+      }
+    };
+  },
+  teardown: (hookContext) => {
+    const registry = hookContext.state.get(STATE_KEY);
+    if (registry) {
+      registry.clear();
+      hookContext.state.delete(STATE_KEY);
+    }
+  }
+});
+var mock_ipc_default = mockIpcPlugin;
+export {
+  MockIpcRegistry,
+  mock_ipc_default as default,
+  generateMockIpcScript,
+  mockIpcPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/plugins/mock-ipc/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/shared/api/plugin.ts","../../../src/plugins/mock-ipc/registry.ts","../../../src/plugins/mock-ipc/index.ts"],"sourcesContent":["import type { Page, BrowserContext, Browser } from 'playwright';\nimport type { TestContext, VisualScenario } from './dsl';\nimport type { ReportData } from '../types/report';\n\nexport interface DriverLaunchResult {\n  page: Page;\n  context: BrowserContext;\n  browser?: Browser;\n  stop?: () => Promise<void>;\n}\n\nexport interface PluginHookContext {\n  scenario?: VisualScenario;\n  targetMode: 'desktop' | 'preview' | string;\n  artifactsDir: string;\n  cliOptions?: Record<string, unknown>;\n  state: Map<string, unknown>;\n}\n\nexport interface AgentLensPlugin {\n  /** Unique plugin identifier (e.g. 'desktop-webview2', 'live-controller', 'mock-ipc') */\n  name: string;\n  version?: string;\n\n  /** Lifecycle hook: initial setup before drivers and scenarios start */\n  setup?: (context: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Microkernel driver hook: allows a plugin to provide a custom browser/page session\n   * (e.g., desktop WebView2 CDP connection, custom remote browser).\n   */\n  launchSession?: (\n    options: { currentViewport: { width: number; height: number }; headed?: boolean },\n    hookContext: PluginHookContext\n  ) => Promise<DriverLaunchResult | undefined>;\n\n  /** Lifecycle hook: called when browser context is ready */\n  onContextCreated?: (context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: called when the test page is created/navigated */\n  onPageCreated?: (page: Page, context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Context extension: inject custom methods or properties directly into TestContext (ctx)\n   */\n  extendContext?: (\n    ctx: TestContext,\n    page: Page,\n    hookContext: PluginHookContext\n  ) => Record<string, any> | Promise<Record<string, any>>;\n\n  /** Lifecycle hook: called after scenario runs and report data is calculated */\n  onAfterRun?: (reportData: ReportData, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: teardown and cleanup guaranteed to run */\n  teardown?: (hookContext: PluginHookContext) => Promise<void> | void;\n}\n\nexport function definePlugin(plugin: AgentLensPlugin): AgentLensPlugin {\n  return plugin;\n}","import type { MockIpcResponseType, MockIpcEntry } from '../../shared/types/ipc';\n\nexport class MockIpcRegistry {\n  private mocks = new Map<string, MockIpcEntry>();\n\n  public set(action: string, data: any, options?: { type?: MockIpcResponseType; delayMs?: number }): void {\n    this.mocks.set(action, {\n      action,\n      data,\n      type: options?.type ?? 'SUCCESS',\n      delayMs: options?.delayMs ?? 20\n    });\n  }\n\n  public setBatch(entries: Array<{ action: string; data: any; type?: MockIpcResponseType; delayMs?: number }>): void {\n    for (const entry of entries) {\n      this.set(entry.action, entry.data, { type: entry.type, delayMs: entry.delayMs });\n    }\n  }\n\n  public remove(action: string): void {\n    this.mocks.delete(action);\n  }\n\n  public clear(): void {\n    this.mocks.clear();\n  }\n\n  public get(action: string): MockIpcEntry | null {\n    return this.mocks.get(action) ?? null;\n  }\n\n  public toSerializable(): Record<string, { data: any; type: string; delayMs: number }> {\n    const result: Record<string, { data: any; type: string; delayMs: number }> = {};\n    for (const [action, entry] of this.mocks.entries()) {\n      result[action] = {\n        data: entry.data,\n        type: entry.type ?? 'SUCCESS',\n        delayMs: entry.delayMs ?? 20\n      };\n    }\n    return result;\n  }\n\n  public get size(): number {\n    return this.mocks.size;\n  }\n}\n\nexport function generateMockIpcScript(registry: MockIpcRegistry): string {\n  const mocksJson = JSON.stringify(registry.toSerializable());\n\n  return `\n    (() => {\n      const __mockTable = ${mocksJson};\n\n      window.__visualRunnerMocks = __mockTable;\n\n      // Generic IPC mock bridge for modern web applications\n      window.__mockIpc = {\n        invoke: (action, payload) => {\n          return new Promise((resolve, reject) => {\n            const mock = window.__visualRunnerMocks[action];\n\n            if (mock) {\n              setTimeout(() => {\n                if (mock.type === 'ERROR') {\n                  reject(new Error(mock.data));\n                } else {\n                  resolve(mock.data);\n                }\n              }, mock.delayMs || 20);\n            } else {\n              console.warn('[Mock IPC] No mock for action:', action, '— returning empty SUCCESS');\n              setTimeout(() => resolve(null), 20);\n            }\n          });\n        }\n      };\n\n      // Safe fallback bridge for hybrid webviews (Photino / CEF / WebView2)\n      try {\n        if (!window.external) {\n          window.external = {};\n        }\n        window.external.sendMessage = (msg) => {\n          try {\n            const parsed = typeof msg === 'string' ? JSON.parse(msg) : msg;\n            const action = parsed.Action || parsed.action;\n            const id = parsed.Id || parsed.id;\n            const mock = window.__visualRunnerMocks[action];\n\n            if (mock) {\n              const response = { Id: id, Type: mock.type || 'SUCCESS', Data: mock.data };\n              setTimeout(() => {\n                const cb = window.__mockCallback;\n                if (typeof cb === 'function') cb(JSON.stringify(response));\n              }, mock.delayMs || 20);\n            } else {\n              setTimeout(() => {\n                const cb = window.__mockCallback;\n                if (typeof cb === 'function') cb(JSON.stringify({ Id: id, Type: 'SUCCESS', Data: null }));\n              }, 20);\n            }\n          } catch (e) {\n            console.error('[Mock IPC] Failed to process message:', e);\n          }\n        };\n\n        window.external.receiveMessage = (callback) => {\n          window.__mockCallback = callback;\n        };\n      } catch {\n        // Ignored if window.external is read-only in strict Chromium sandboxes\n      }\n\n      console.log('[Visual Runner] Mock IPC bridge initialized with', Object.keys(window.__visualRunnerMocks).length, 'mocked actions');\n    })();\n  `;\n}\n","import { definePlugin, type AgentLensPlugin } from '../../shared/api/plugin';\nimport { MockIpcRegistry, generateMockIpcScript } from './registry';\nimport type { MockIpcResponseType } from '../../shared/types/ipc';\n\nexport { MockIpcRegistry, generateMockIpcScript };\n\nconst STATE_KEY = 'mockIpcRegistry';\n\nexport const mockIpcPlugin: AgentLensPlugin = definePlugin({\n  name: 'mock-ipc',\n  version: '1.0.0',\n\n  setup: (hookContext) => {\n    const registry = new MockIpcRegistry();\n    hookContext.state.set(STATE_KEY, registry);\n\n    const scenarioMocks = hookContext.scenario?.mockIpc || [];\n    const globalMocks = (hookContext.cliOptions?.globalMocks as Array<{ action: string; data: unknown; type?: MockIpcResponseType; delayMs?: number }>) || [];\n    const allMocks = [...globalMocks, ...scenarioMocks];\n\n    if (allMocks.length > 0) {\n      console.log(`📦 [Plugin:mock-ipc] Pre-loading ${allMocks.length} initial IPC mocks`);\n      registry.setBatch(allMocks);\n    }\n  },\n\n  onContextCreated: async (context, hookContext) => {\n    const registry = (hookContext.state.get(STATE_KEY) as MockIpcRegistry) || new MockIpcRegistry();\n    const script = generateMockIpcScript(registry);\n    await context.addInitScript(script);\n    console.log(`🔌 [Plugin:mock-ipc] Injected window.__mockIpc & window.external bridge into browser context`);\n  },\n\n  extendContext: (_ctx, page, hookContext) => {\n    const registry = (hookContext.state.get(STATE_KEY) as MockIpcRegistry) || new MockIpcRegistry();\n\n    return {\n      setMockIpc: async (\n        action: string,\n        data: unknown,\n        options?: { type?: MockIpcResponseType; delayMs?: number }\n      ) => {\n        const preview = typeof data === 'string' ? data : JSON.stringify(data).slice(0, 80);\n        console.log(`📦 [Plugin:mock-ipc] Dynamic set: ${action} -> ${preview}`);\n        registry.set(action, data, options);\n\n        await page.evaluate(\n          ({ action, mock }) => {\n            const w = window as unknown as { __visualRunnerMocks?: Record<string, unknown> };\n            if (!w.__visualRunnerMocks) {\n              w.__visualRunnerMocks = {};\n            }\n            w.__visualRunnerMocks[action] = mock;\n          },\n          {\n            action,\n            mock: {\n              data,\n              type: options?.type ?? 'SUCCESS',\n              delayMs: options?.delayMs ?? 20\n            }\n          }\n        );\n      }\n    };\n  },\n\n  teardown: (hookContext) => {\n    const registry = hookContext.state.get(STATE_KEY) as MockIpcRegistry | undefined;\n    if (registry) {\n      registry.clear();\n      hookContext.state.delete(STATE_KEY);\n    }\n  }\n});\n\nexport default mockIpcPlugin;\n"],"mappings":"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","names":["action"]}

package/dist/plugins/visual-diff/index.d.mts

@@ -0,0 +1,30 @@
+import { A as AgentLensPlugin } from '../../dsl-BIjVN1M0.mjs';
+import 'playwright';
+
+interface VisualDiffOptions {
+    threshold?: number;
+    includeAA?: boolean;
+    diffColor?: [number, number, number];
+}
+interface VisualDiffResult {
+    diffPixels: number;
+    totalPixels: number;
+    diffPercent: number;
+    diffImagePath: string;
+    isMatch: boolean;
+}
+/**
+ * Compare two PNG images pixel-by-pixel using pixelmatch and generate a highlighted diff image.
+ */
+declare function comparePngImages(img1Path: string, img2Path: string, outDiffPath: string, options?: VisualDiffOptions): Promise<VisualDiffResult>;
+
+interface RecordedDiffEntry {
+    name: string;
+    baselinePath: string;
+    currentPath: string;
+    diffPath: string;
+    result: VisualDiffResult;
+}
+declare const visualDiffPlugin: AgentLensPlugin;
+
+export { type RecordedDiffEntry, type VisualDiffOptions, type VisualDiffResult, comparePngImages, visualDiffPlugin as default, visualDiffPlugin };

package/dist/plugins/visual-diff/index.d.ts

@@ -0,0 +1,30 @@
+import { A as AgentLensPlugin } from '../../dsl-BIjVN1M0.js';
+import 'playwright';
+
+interface VisualDiffOptions {
+    threshold?: number;
+    includeAA?: boolean;
+    diffColor?: [number, number, number];
+}
+interface VisualDiffResult {
+    diffPixels: number;
+    totalPixels: number;
+    diffPercent: number;
+    diffImagePath: string;
+    isMatch: boolean;
+}
+/**
+ * Compare two PNG images pixel-by-pixel using pixelmatch and generate a highlighted diff image.
+ */
+declare function comparePngImages(img1Path: string, img2Path: string, outDiffPath: string, options?: VisualDiffOptions): Promise<VisualDiffResult>;
+
+interface RecordedDiffEntry {
+    name: string;
+    baselinePath: string;
+    currentPath: string;
+    diffPath: string;
+    result: VisualDiffResult;
+}
+declare const visualDiffPlugin: AgentLensPlugin;
+
+export { type RecordedDiffEntry, type VisualDiffOptions, type VisualDiffResult, comparePngImages, visualDiffPlugin as default, visualDiffPlugin };

package/dist/plugins/visual-diff/index.js

@@ -0,0 +1,163 @@
+"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)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugins/visual-diff/index.ts
+var visual_diff_exports = {};
+__export(visual_diff_exports, {
+  comparePngImages: () => comparePngImages,
+  default: () => visual_diff_default,
+  visualDiffPlugin: () => visualDiffPlugin
+});
+module.exports = __toCommonJS(visual_diff_exports);
+var import_path = __toESM(require("path"));
+
+// src/shared/api/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// src/plugins/visual-diff/diff.ts
+var import_fs = __toESM(require("fs"));
+var import_pngjs = require("pngjs");
+var import_pixelmatch = __toESM(require("pixelmatch"));
+async function comparePngImages(img1Path, img2Path, outDiffPath, options) {
+  if (!import_fs.default.existsSync(img1Path)) {
+    throw new Error(`[visual-diff] Baseline image not found: ${img1Path}`);
+  }
+  if (!import_fs.default.existsSync(img2Path)) {
+    throw new Error(`[visual-diff] Target image not found: ${img2Path}`);
+  }
+  const img1Data = import_fs.default.readFileSync(img1Path);
+  const img2Data = import_fs.default.readFileSync(img2Path);
+  const img1 = import_pngjs.PNG.sync.read(img1Data);
+  const img2 = import_pngjs.PNG.sync.read(img2Data);
+  const width = Math.max(img1.width, img2.width);
+  const height = Math.max(img1.height, img2.height);
+  const padded1 = padImage(img1, width, height);
+  const padded2 = padImage(img2, width, height);
+  const diff = new import_pngjs.PNG({ width, height });
+  const diffPixels = (0, import_pixelmatch.default)(
+    padded1.data,
+    padded2.data,
+    diff.data,
+    width,
+    height,
+    {
+      threshold: options?.threshold ?? 0.1,
+      includeAA: options?.includeAA ?? false,
+      diffColor: options?.diffColor ?? [255, 0, 80]
+    }
+  );
+  const totalPixels = width * height;
+  const diffPercent = totalPixels > 0 ? diffPixels / totalPixels * 100 : 0;
+  import_fs.default.writeFileSync(outDiffPath, import_pngjs.PNG.sync.write(diff));
+  return {
+    diffPixels,
+    totalPixels,
+    diffPercent: Number(diffPercent.toFixed(2)),
+    diffImagePath: outDiffPath,
+    isMatch: diffPixels === 0
+  };
+}
+function padImage(src, width, height) {
+  if (src.width === width && src.height === height) {
+    return src;
+  }
+  const padded = new import_pngjs.PNG({ width, height });
+  padded.data.fill(255);
+  import_pngjs.PNG.bitblt(src, padded, 0, 0, src.width, src.height, 0, 0);
+  return padded;
+}
+
+// src/plugins/visual-diff/index.ts
+var STATE_DIFFS_KEY = "recordedVisualDiffs";
+var visualDiffPlugin = definePlugin({
+  name: "visual-diff",
+  version: "1.0.0",
+  setup: (hookContext) => {
+    hookContext.state.set(STATE_DIFFS_KEY, []);
+  },
+  extendContext: (ctx, page, hookContext) => {
+    const diffRecords = hookContext.state.get(STATE_DIFFS_KEY) || [];
+    return {
+      compareSnapshots: async (currentPath, baselinePath, options) => {
+        const artifactsDir = hookContext.artifactsDir;
+        const baseName = import_path.default.basename(currentPath, ".png");
+        const diffFileName = `${baseName}_diff.png`;
+        const diffPath = import_path.default.join(artifactsDir, diffFileName);
+        console.log(`\u{1F3A8} [visual-diff] Comparing ${import_path.default.basename(currentPath)} against baseline...`);
+        const result = await comparePngImages(baselinePath, currentPath, diffPath, options);
+        console.log(
+          `\u{1F3A8} [visual-diff] Result: ${result.diffPixels} px changed (${result.diffPercent}%) | Diff: ${diffFileName}`
+        );
+        diffRecords.push({
+          name: baseName,
+          baselinePath,
+          currentPath,
+          diffPath,
+          result
+        });
+        return result;
+      },
+      captureAndCompare: async (name, baselinePath, captureOptions, diffOptions) => {
+        const snap = await ctx.capture(name, captureOptions);
+        return await ctx.compareSnapshots(snap.filePath, baselinePath, diffOptions);
+      }
+    };
+  },
+  onAfterRun: (reportData, hookContext) => {
+    const diffs = hookContext.state.get(STATE_DIFFS_KEY) || [];
+    if (diffs.length === 0 || !reportData.customSections) return;
+    let table = `| Test Step | Baseline | Current | Diff Image | Changed Pixels | Status |
+`;
+    table += `| :--- | :--- | :--- | :--- | :-: | :-: |
+`;
+    for (const d of diffs) {
+      const relBaseline = import_path.default.relative(reportData.outputDir, d.baselinePath).replace(/\\/g, "/");
+      const relCurrent = import_path.default.relative(reportData.outputDir, d.currentPath).replace(/\\/g, "/");
+      const relDiff = import_path.default.relative(reportData.outputDir, d.diffPath).replace(/\\/g, "/");
+      const status = d.result.diffPercent === 0 ? "\u2705 Perfect Match" : d.result.diffPercent < 1 ? `\u{1F7E1} Minor Shift (${d.result.diffPercent}%)` : `\u{1F534} Regressed (${d.result.diffPercent}%)`;
+      table += `| **${d.name}** | [Baseline](${relBaseline}) | [Current](${relCurrent}) | [Diff](${relDiff}) | ${d.result.diffPixels} px | ${status} |
+`;
+    }
+    reportData.customSections.push({
+      title: "\u{1F3A8} Visual Regression Diff (Pixelmatch)",
+      content: `> Automated pixel-by-pixel visual difference detector.
+
+${table}`
+    });
+  }
+});
+var visual_diff_default = visualDiffPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  comparePngImages,
+  visualDiffPlugin
+});
+//# sourceMappingURL=index.js.map

package/dist/plugins/visual-diff/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/plugins/visual-diff/index.ts","../../../src/shared/api/plugin.ts","../../../src/plugins/visual-diff/diff.ts"],"sourcesContent":["import path from 'path';\nimport { definePlugin, type AgentLensPlugin } from '../../shared/api/plugin';\nimport { comparePngImages, type VisualDiffOptions, type VisualDiffResult } from './diff';\nimport type { CaptureOptions } from '../../shared/api/dsl';\n\nexport { comparePngImages, type VisualDiffOptions, type VisualDiffResult };\n\nconst STATE_DIFFS_KEY = 'recordedVisualDiffs';\n\nexport interface RecordedDiffEntry {\n  name: string;\n  baselinePath: string;\n  currentPath: string;\n  diffPath: string;\n  result: VisualDiffResult;\n}\n\nexport const visualDiffPlugin: AgentLensPlugin = definePlugin({\n  name: 'visual-diff',\n  version: '1.0.0',\n\n  setup: (hookContext) => {\n    hookContext.state.set(STATE_DIFFS_KEY, [] as RecordedDiffEntry[]);\n  },\n\n  extendContext: (ctx, page, hookContext) => {\n    const diffRecords = (hookContext.state.get(STATE_DIFFS_KEY) as RecordedDiffEntry[]) || [];\n\n    return {\n      compareSnapshots: async (\n        currentPath: string,\n        baselinePath: string,\n        options?: VisualDiffOptions\n      ): Promise<VisualDiffResult> => {\n        const artifactsDir = hookContext.artifactsDir;\n        const baseName = path.basename(currentPath, '.png');\n        const diffFileName = `${baseName}_diff.png`;\n        const diffPath = path.join(artifactsDir, diffFileName);\n\n        console.log(`🎨 [visual-diff] Comparing ${path.basename(currentPath)} against baseline...`);\n        const result = await comparePngImages(baselinePath, currentPath, diffPath, options);\n\n        console.log(\n          `🎨 [visual-diff] Result: ${result.diffPixels} px changed (${result.diffPercent}%) | Diff: ${diffFileName}`\n        );\n\n        diffRecords.push({\n          name: baseName,\n          baselinePath,\n          currentPath,\n          diffPath,\n          result\n        });\n\n        return result;\n      },\n\n      captureAndCompare: async (\n        name: string,\n        baselinePath: string,\n        captureOptions?: CaptureOptions,\n        diffOptions?: VisualDiffOptions\n      ): Promise<VisualDiffResult> => {\n        const snap = await ctx.capture(name, captureOptions);\n        return await ctx.compareSnapshots(snap.filePath, baselinePath, diffOptions);\n      }\n    };\n  },\n\n  onAfterRun: (reportData, hookContext) => {\n    const diffs = (hookContext.state.get(STATE_DIFFS_KEY) as RecordedDiffEntry[]) || [];\n    if (diffs.length === 0 || !reportData.customSections) return;\n\n    let table = `| Test Step | Baseline | Current | Diff Image | Changed Pixels | Status |\\n`;\n    table += `| :--- | :--- | :--- | :--- | :-: | :-: |\\n`;\n\n    for (const d of diffs) {\n      const relBaseline = path.relative(reportData.outputDir, d.baselinePath).replace(/\\\\/g, '/');\n      const relCurrent = path.relative(reportData.outputDir, d.currentPath).replace(/\\\\/g, '/');\n      const relDiff = path.relative(reportData.outputDir, d.diffPath).replace(/\\\\/g, '/');\n\n      const status = d.result.diffPercent === 0\n        ? '✅ Perfect Match'\n        : d.result.diffPercent < 1.0\n        ? `🟡 Minor Shift (${d.result.diffPercent}%)`\n        : `🔴 Regressed (${d.result.diffPercent}%)`;\n\n      table += `| **${d.name}** | [Baseline](${relBaseline}) | [Current](${relCurrent}) | [Diff](${relDiff}) | ${d.result.diffPixels} px | ${status} |\\n`;\n    }\n\n    reportData.customSections.push({\n      title: '🎨 Visual Regression Diff (Pixelmatch)',\n      content: `> Automated pixel-by-pixel visual difference detector.\\n\\n${table}`\n    });\n  }\n});\n\nexport default visualDiffPlugin;\n","import type { Page, BrowserContext, Browser } from 'playwright';\nimport type { TestContext, VisualScenario } from './dsl';\nimport type { ReportData } from '../types/report';\n\nexport interface DriverLaunchResult {\n  page: Page;\n  context: BrowserContext;\n  browser?: Browser;\n  stop?: () => Promise<void>;\n}\n\nexport interface PluginHookContext {\n  scenario?: VisualScenario;\n  targetMode: 'desktop' | 'preview' | string;\n  artifactsDir: string;\n  cliOptions?: Record<string, unknown>;\n  state: Map<string, unknown>;\n}\n\nexport interface AgentLensPlugin {\n  /** Unique plugin identifier (e.g. 'desktop-webview2', 'live-controller', 'mock-ipc') */\n  name: string;\n  version?: string;\n\n  /** Lifecycle hook: initial setup before drivers and scenarios start */\n  setup?: (context: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Microkernel driver hook: allows a plugin to provide a custom browser/page session\n   * (e.g., desktop WebView2 CDP connection, custom remote browser).\n   */\n  launchSession?: (\n    options: { currentViewport: { width: number; height: number }; headed?: boolean },\n    hookContext: PluginHookContext\n  ) => Promise<DriverLaunchResult | undefined>;\n\n  /** Lifecycle hook: called when browser context is ready */\n  onContextCreated?: (context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: called when the test page is created/navigated */\n  onPageCreated?: (page: Page, context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Context extension: inject custom methods or properties directly into TestContext (ctx)\n   */\n  extendContext?: (\n    ctx: TestContext,\n    page: Page,\n    hookContext: PluginHookContext\n  ) => Record<string, any> | Promise<Record<string, any>>;\n\n  /** Lifecycle hook: called after scenario runs and report data is calculated */\n  onAfterRun?: (reportData: ReportData, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: teardown and cleanup guaranteed to run */\n  teardown?: (hookContext: PluginHookContext) => Promise<void> | void;\n}\n\nexport function definePlugin(plugin: AgentLensPlugin): AgentLensPlugin {\n  return plugin;\n}","import fs from 'fs';\nimport { PNG } from 'pngjs';\nimport pixelmatch from 'pixelmatch';\n\nexport interface VisualDiffOptions {\n  threshold?: number; // 0 to 1 (default 0.1)\n  includeAA?: boolean; // include anti-aliasing pixels\n  diffColor?: [number, number, number]; // RGB\n}\n\nexport interface VisualDiffResult {\n  diffPixels: number;\n  totalPixels: number;\n  diffPercent: number;\n  diffImagePath: string;\n  isMatch: boolean;\n}\n\n/**\n * Compare two PNG images pixel-by-pixel using pixelmatch and generate a highlighted diff image.\n */\nexport async function comparePngImages(\n  img1Path: string,\n  img2Path: string,\n  outDiffPath: string,\n  options?: VisualDiffOptions\n): Promise<VisualDiffResult> {\n  if (!fs.existsSync(img1Path)) {\n    throw new Error(`[visual-diff] Baseline image not found: ${img1Path}`);\n  }\n  if (!fs.existsSync(img2Path)) {\n    throw new Error(`[visual-diff] Target image not found: ${img2Path}`);\n  }\n\n  const img1Data = fs.readFileSync(img1Path);\n  const img2Data = fs.readFileSync(img2Path);\n\n  const img1 = PNG.sync.read(img1Data);\n  const img2 = PNG.sync.read(img2Data);\n\n  const width = Math.max(img1.width, img2.width);\n  const height = Math.max(img1.height, img2.height);\n\n  // Resize / pad images to match dimensions if they differ\n  const padded1 = padImage(img1, width, height);\n  const padded2 = padImage(img2, width, height);\n\n  const diff = new PNG({ width, height });\n\n  const diffPixels = pixelmatch(\n    padded1.data,\n    padded2.data,\n    diff.data,\n    width,\n    height,\n    {\n      threshold: options?.threshold ?? 0.1,\n      includeAA: options?.includeAA ?? false,\n      diffColor: options?.diffColor ?? [255, 0, 80]\n    }\n  );\n\n  const totalPixels = width * height;\n  const diffPercent = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;\n\n  fs.writeFileSync(outDiffPath, PNG.sync.write(diff));\n\n  return {\n    diffPixels,\n    totalPixels,\n    diffPercent: Number(diffPercent.toFixed(2)),\n    diffImagePath: outDiffPath,\n    isMatch: diffPixels === 0\n  };\n}\n\nfunction padImage(src: PNG, width: number, height: number): PNG {\n  if (src.width === width && src.height === height) {\n    return src;\n  }\n\n  const padded = new PNG({ width, height });\n  // Fill with white background\n  padded.data.fill(255);\n\n  PNG.bitblt(src, padded, 0, 0, src.width, src.height, 0, 0);\n  return padded;\n}\n"],"mappings":"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","names":["fs","pixelmatch","path"]}

package/dist/plugins/visual-diff/index.mjs

@@ -0,0 +1,127 @@
+// src/plugins/visual-diff/index.ts
+import path from "path";
+
+// src/shared/api/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// src/plugins/visual-diff/diff.ts
+import fs from "fs";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+async function comparePngImages(img1Path, img2Path, outDiffPath, options) {
+  if (!fs.existsSync(img1Path)) {
+    throw new Error(`[visual-diff] Baseline image not found: ${img1Path}`);
+  }
+  if (!fs.existsSync(img2Path)) {
+    throw new Error(`[visual-diff] Target image not found: ${img2Path}`);
+  }
+  const img1Data = fs.readFileSync(img1Path);
+  const img2Data = fs.readFileSync(img2Path);
+  const img1 = PNG.sync.read(img1Data);
+  const img2 = PNG.sync.read(img2Data);
+  const width = Math.max(img1.width, img2.width);
+  const height = Math.max(img1.height, img2.height);
+  const padded1 = padImage(img1, width, height);
+  const padded2 = padImage(img2, width, height);
+  const diff = new PNG({ width, height });
+  const diffPixels = pixelmatch(
+    padded1.data,
+    padded2.data,
+    diff.data,
+    width,
+    height,
+    {
+      threshold: options?.threshold ?? 0.1,
+      includeAA: options?.includeAA ?? false,
+      diffColor: options?.diffColor ?? [255, 0, 80]
+    }
+  );
+  const totalPixels = width * height;
+  const diffPercent = totalPixels > 0 ? diffPixels / totalPixels * 100 : 0;
+  fs.writeFileSync(outDiffPath, PNG.sync.write(diff));
+  return {
+    diffPixels,
+    totalPixels,
+    diffPercent: Number(diffPercent.toFixed(2)),
+    diffImagePath: outDiffPath,
+    isMatch: diffPixels === 0
+  };
+}
+function padImage(src, width, height) {
+  if (src.width === width && src.height === height) {
+    return src;
+  }
+  const padded = new PNG({ width, height });
+  padded.data.fill(255);
+  PNG.bitblt(src, padded, 0, 0, src.width, src.height, 0, 0);
+  return padded;
+}
+
+// src/plugins/visual-diff/index.ts
+var STATE_DIFFS_KEY = "recordedVisualDiffs";
+var visualDiffPlugin = definePlugin({
+  name: "visual-diff",
+  version: "1.0.0",
+  setup: (hookContext) => {
+    hookContext.state.set(STATE_DIFFS_KEY, []);
+  },
+  extendContext: (ctx, page, hookContext) => {
+    const diffRecords = hookContext.state.get(STATE_DIFFS_KEY) || [];
+    return {
+      compareSnapshots: async (currentPath, baselinePath, options) => {
+        const artifactsDir = hookContext.artifactsDir;
+        const baseName = path.basename(currentPath, ".png");
+        const diffFileName = `${baseName}_diff.png`;
+        const diffPath = path.join(artifactsDir, diffFileName);
+        console.log(`\u{1F3A8} [visual-diff] Comparing ${path.basename(currentPath)} against baseline...`);
+        const result = await comparePngImages(baselinePath, currentPath, diffPath, options);
+        console.log(
+          `\u{1F3A8} [visual-diff] Result: ${result.diffPixels} px changed (${result.diffPercent}%) | Diff: ${diffFileName}`
+        );
+        diffRecords.push({
+          name: baseName,
+          baselinePath,
+          currentPath,
+          diffPath,
+          result
+        });
+        return result;
+      },
+      captureAndCompare: async (name, baselinePath, captureOptions, diffOptions) => {
+        const snap = await ctx.capture(name, captureOptions);
+        return await ctx.compareSnapshots(snap.filePath, baselinePath, diffOptions);
+      }
+    };
+  },
+  onAfterRun: (reportData, hookContext) => {
+    const diffs = hookContext.state.get(STATE_DIFFS_KEY) || [];
+    if (diffs.length === 0 || !reportData.customSections) return;
+    let table = `| Test Step | Baseline | Current | Diff Image | Changed Pixels | Status |
+`;
+    table += `| :--- | :--- | :--- | :--- | :-: | :-: |
+`;
+    for (const d of diffs) {
+      const relBaseline = path.relative(reportData.outputDir, d.baselinePath).replace(/\\/g, "/");
+      const relCurrent = path.relative(reportData.outputDir, d.currentPath).replace(/\\/g, "/");
+      const relDiff = path.relative(reportData.outputDir, d.diffPath).replace(/\\/g, "/");
+      const status = d.result.diffPercent === 0 ? "\u2705 Perfect Match" : d.result.diffPercent < 1 ? `\u{1F7E1} Minor Shift (${d.result.diffPercent}%)` : `\u{1F534} Regressed (${d.result.diffPercent}%)`;
+      table += `| **${d.name}** | [Baseline](${relBaseline}) | [Current](${relCurrent}) | [Diff](${relDiff}) | ${d.result.diffPixels} px | ${status} |
+`;
+    }
+    reportData.customSections.push({
+      title: "\u{1F3A8} Visual Regression Diff (Pixelmatch)",
+      content: `> Automated pixel-by-pixel visual difference detector.
+
+${table}`
+    });
+  }
+});
+var visual_diff_default = visualDiffPlugin;
+export {
+  comparePngImages,
+  visual_diff_default as default,
+  visualDiffPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/plugins/visual-diff/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/plugins/visual-diff/index.ts","../../../src/shared/api/plugin.ts","../../../src/plugins/visual-diff/diff.ts"],"sourcesContent":["import path from 'path';\nimport { definePlugin, type AgentLensPlugin } from '../../shared/api/plugin';\nimport { comparePngImages, type VisualDiffOptions, type VisualDiffResult } from './diff';\nimport type { CaptureOptions } from '../../shared/api/dsl';\n\nexport { comparePngImages, type VisualDiffOptions, type VisualDiffResult };\n\nconst STATE_DIFFS_KEY = 'recordedVisualDiffs';\n\nexport interface RecordedDiffEntry {\n  name: string;\n  baselinePath: string;\n  currentPath: string;\n  diffPath: string;\n  result: VisualDiffResult;\n}\n\nexport const visualDiffPlugin: AgentLensPlugin = definePlugin({\n  name: 'visual-diff',\n  version: '1.0.0',\n\n  setup: (hookContext) => {\n    hookContext.state.set(STATE_DIFFS_KEY, [] as RecordedDiffEntry[]);\n  },\n\n  extendContext: (ctx, page, hookContext) => {\n    const diffRecords = (hookContext.state.get(STATE_DIFFS_KEY) as RecordedDiffEntry[]) || [];\n\n    return {\n      compareSnapshots: async (\n        currentPath: string,\n        baselinePath: string,\n        options?: VisualDiffOptions\n      ): Promise<VisualDiffResult> => {\n        const artifactsDir = hookContext.artifactsDir;\n        const baseName = path.basename(currentPath, '.png');\n        const diffFileName = `${baseName}_diff.png`;\n        const diffPath = path.join(artifactsDir, diffFileName);\n\n        console.log(`🎨 [visual-diff] Comparing ${path.basename(currentPath)} against baseline...`);\n        const result = await comparePngImages(baselinePath, currentPath, diffPath, options);\n\n        console.log(\n          `🎨 [visual-diff] Result: ${result.diffPixels} px changed (${result.diffPercent}%) | Diff: ${diffFileName}`\n        );\n\n        diffRecords.push({\n          name: baseName,\n          baselinePath,\n          currentPath,\n          diffPath,\n          result\n        });\n\n        return result;\n      },\n\n      captureAndCompare: async (\n        name: string,\n        baselinePath: string,\n        captureOptions?: CaptureOptions,\n        diffOptions?: VisualDiffOptions\n      ): Promise<VisualDiffResult> => {\n        const snap = await ctx.capture(name, captureOptions);\n        return await ctx.compareSnapshots(snap.filePath, baselinePath, diffOptions);\n      }\n    };\n  },\n\n  onAfterRun: (reportData, hookContext) => {\n    const diffs = (hookContext.state.get(STATE_DIFFS_KEY) as RecordedDiffEntry[]) || [];\n    if (diffs.length === 0 || !reportData.customSections) return;\n\n    let table = `| Test Step | Baseline | Current | Diff Image | Changed Pixels | Status |\\n`;\n    table += `| :--- | :--- | :--- | :--- | :-: | :-: |\\n`;\n\n    for (const d of diffs) {\n      const relBaseline = path.relative(reportData.outputDir, d.baselinePath).replace(/\\\\/g, '/');\n      const relCurrent = path.relative(reportData.outputDir, d.currentPath).replace(/\\\\/g, '/');\n      const relDiff = path.relative(reportData.outputDir, d.diffPath).replace(/\\\\/g, '/');\n\n      const status = d.result.diffPercent === 0\n        ? '✅ Perfect Match'\n        : d.result.diffPercent < 1.0\n        ? `🟡 Minor Shift (${d.result.diffPercent}%)`\n        : `🔴 Regressed (${d.result.diffPercent}%)`;\n\n      table += `| **${d.name}** | [Baseline](${relBaseline}) | [Current](${relCurrent}) | [Diff](${relDiff}) | ${d.result.diffPixels} px | ${status} |\\n`;\n    }\n\n    reportData.customSections.push({\n      title: '🎨 Visual Regression Diff (Pixelmatch)',\n      content: `> Automated pixel-by-pixel visual difference detector.\\n\\n${table}`\n    });\n  }\n});\n\nexport default visualDiffPlugin;\n","import type { Page, BrowserContext, Browser } from 'playwright';\nimport type { TestContext, VisualScenario } from './dsl';\nimport type { ReportData } from '../types/report';\n\nexport interface DriverLaunchResult {\n  page: Page;\n  context: BrowserContext;\n  browser?: Browser;\n  stop?: () => Promise<void>;\n}\n\nexport interface PluginHookContext {\n  scenario?: VisualScenario;\n  targetMode: 'desktop' | 'preview' | string;\n  artifactsDir: string;\n  cliOptions?: Record<string, unknown>;\n  state: Map<string, unknown>;\n}\n\nexport interface AgentLensPlugin {\n  /** Unique plugin identifier (e.g. 'desktop-webview2', 'live-controller', 'mock-ipc') */\n  name: string;\n  version?: string;\n\n  /** Lifecycle hook: initial setup before drivers and scenarios start */\n  setup?: (context: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Microkernel driver hook: allows a plugin to provide a custom browser/page session\n   * (e.g., desktop WebView2 CDP connection, custom remote browser).\n   */\n  launchSession?: (\n    options: { currentViewport: { width: number; height: number }; headed?: boolean },\n    hookContext: PluginHookContext\n  ) => Promise<DriverLaunchResult | undefined>;\n\n  /** Lifecycle hook: called when browser context is ready */\n  onContextCreated?: (context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: called when the test page is created/navigated */\n  onPageCreated?: (page: Page, context: BrowserContext, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /**\n   * Context extension: inject custom methods or properties directly into TestContext (ctx)\n   */\n  extendContext?: (\n    ctx: TestContext,\n    page: Page,\n    hookContext: PluginHookContext\n  ) => Record<string, any> | Promise<Record<string, any>>;\n\n  /** Lifecycle hook: called after scenario runs and report data is calculated */\n  onAfterRun?: (reportData: ReportData, hookContext: PluginHookContext) => Promise<void> | void;\n\n  /** Lifecycle hook: teardown and cleanup guaranteed to run */\n  teardown?: (hookContext: PluginHookContext) => Promise<void> | void;\n}\n\nexport function definePlugin(plugin: AgentLensPlugin): AgentLensPlugin {\n  return plugin;\n}","import fs from 'fs';\nimport { PNG } from 'pngjs';\nimport pixelmatch from 'pixelmatch';\n\nexport interface VisualDiffOptions {\n  threshold?: number; // 0 to 1 (default 0.1)\n  includeAA?: boolean; // include anti-aliasing pixels\n  diffColor?: [number, number, number]; // RGB\n}\n\nexport interface VisualDiffResult {\n  diffPixels: number;\n  totalPixels: number;\n  diffPercent: number;\n  diffImagePath: string;\n  isMatch: boolean;\n}\n\n/**\n * Compare two PNG images pixel-by-pixel using pixelmatch and generate a highlighted diff image.\n */\nexport async function comparePngImages(\n  img1Path: string,\n  img2Path: string,\n  outDiffPath: string,\n  options?: VisualDiffOptions\n): Promise<VisualDiffResult> {\n  if (!fs.existsSync(img1Path)) {\n    throw new Error(`[visual-diff] Baseline image not found: ${img1Path}`);\n  }\n  if (!fs.existsSync(img2Path)) {\n    throw new Error(`[visual-diff] Target image not found: ${img2Path}`);\n  }\n\n  const img1Data = fs.readFileSync(img1Path);\n  const img2Data = fs.readFileSync(img2Path);\n\n  const img1 = PNG.sync.read(img1Data);\n  const img2 = PNG.sync.read(img2Data);\n\n  const width = Math.max(img1.width, img2.width);\n  const height = Math.max(img1.height, img2.height);\n\n  // Resize / pad images to match dimensions if they differ\n  const padded1 = padImage(img1, width, height);\n  const padded2 = padImage(img2, width, height);\n\n  const diff = new PNG({ width, height });\n\n  const diffPixels = pixelmatch(\n    padded1.data,\n    padded2.data,\n    diff.data,\n    width,\n    height,\n    {\n      threshold: options?.threshold ?? 0.1,\n      includeAA: options?.includeAA ?? false,\n      diffColor: options?.diffColor ?? [255, 0, 80]\n    }\n  );\n\n  const totalPixels = width * height;\n  const diffPercent = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;\n\n  fs.writeFileSync(outDiffPath, PNG.sync.write(diff));\n\n  return {\n    diffPixels,\n    totalPixels,\n    diffPercent: Number(diffPercent.toFixed(2)),\n    diffImagePath: outDiffPath,\n    isMatch: diffPixels === 0\n  };\n}\n\nfunction padImage(src: PNG, width: number, height: number): PNG {\n  if (src.width === width && src.height === height) {\n    return src;\n  }\n\n  const padded = new PNG({ width, height });\n  // Fill with white background\n  padded.data.fill(255);\n\n  PNG.bitblt(src, padded, 0, 0, src.width, src.height, 0, 0);\n  return padded;\n}\n"],"mappings":"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","names":[]}