@_deep4wee/agent-lens 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { Page, BrowserContext } from 'playwright';
+
+interface ConsoleEntry {
+    level: 'error' | 'warning' | 'info' | 'log' | 'debug';
+    text: string;
+    url: string;
+    timestamp: string;
+    stack?: string;
+}
+
+/**
+ * Generic Mock IPC Registry for Preview Mode
+ *
+ * Injects a global `window.__mockIpc` that web apps or mocked electron/tauri APIs can call.
+ */
+type MockIpcResponseType = 'SUCCESS' | 'ERROR';
+
+interface ViewportPreset {
+    name: string;
+    width: number;
+    height: number;
+}
+declare const VIEWPORT_PRESETS: {
+    /** Minimum supported window size (e.g., ) */
+    MIN_SUPPORTED: ViewportPreset;
+    /** Standard default window size (e.g., ) */
+    DEFAULT: ViewportPreset;
+    /** Wide screen for checking grids and tables */
+    WIDE: ViewportPreset;
+    /** Full HD */
+    FULL_HD: ViewportPreset;
+};
+interface CaptureOptions {
+    selector?: string;
+    fullPage?: boolean;
+    mask?: string[];
+}
+interface CaptureBurstOptions {
+    /** Total duration of burst animation capture in milliseconds */
+    durationMs: number;
+    /** Interval between frames in milliseconds (default: 80ms) */
+    intervalMs?: number;
+    /** Restrict capture to a specific element */
+    selector?: string;
+}
+interface SnapshotMetadata {
+    index: number;
+    name: string;
+    fileName: string;
+    filePath: string;
+    relativeUri: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    timestamp: string;
+    isBurstFrame?: boolean;
+    burstGroup?: string;
+    frameIndex?: number;
+    selector?: string;
+}
+interface TestContext {
+    page: Page;
+    context: BrowserContext;
+    targetMode: 'desktop' | 'preview';
+    currentViewport: {
+        width: number;
+        height: number;
+    };
+    /** Capture a single high-quality snapshot of the window or element */
+    capture: (name: string, options?: CaptureOptions) => Promise<SnapshotMetadata>;
+    /** Capture a series of frames for animations (Framer Motion, modals, lists) */
+    captureBurst: (name: string, options: CaptureBurstOptions) => Promise<SnapshotMetadata[]>;
+    /**
+     * Dynamically navigate to another page during the test.
+     * Example: await ctx.navigate('/settings');
+     */
+    navigate: (route: string) => Promise<void>;
+    /** Change window / viewport size */
+    resize: (width: number, height: number) => Promise<void>;
+    /** Set one of the standard presets (MIN_SUPPORTED, DEFAULT, WIDE) */
+    setPreset: (preset: ViewportPreset) => Promise<void>;
+    /**
+     * Dynamically resize the window so it perfectly fits the specified element (or body).
+     * Useful when an agent wants to test an isolated component without background clutter.
+     */
+    resizeToFit: (selector?: string, padding?: number) => Promise<void>;
+    /** Wait the specified amount of milliseconds */
+    wait: (ms: number) => Promise<void>;
+    /** Wait for the selector to appear in the DOM */
+    waitForSelector: (selector: string, timeoutMs?: number) => Promise<void>;
+    /** Left-click the element */
+    click: (selector: string) => Promise<void>;
+    /** Right-click the element (Context Menu) */
+    rightClick: (selector: string) => Promise<void>;
+    /** Type text into an input field */
+    type: (selector: string, text: string) => Promise<void>;
+    /** Select an option in a <select> by its value */
+    selectOption: (selector: string, value: string) => Promise<void>;
+    /** Hover the cursor to check highlights / tooltips */
+    hover: (selector: string) => Promise<void>;
+    /** Scroll the element (or window) down by the specified number of pixels */
+    scroll: (selector: string, deltaY: number) => Promise<void>;
+    /** Log a step for the agent */
+    log: (message: string) => void;
+    /**
+     * Set a mock response for an IPC action.
+     * Changes the data returned by window.external.sendMessage in preview mode.
+     * Ignored in desktop mode (IPC goes through real backend).
+     *
+     * Example:
+     *   await ctx.setMockIpc('GET_INSTANCES', [{ id: '...', name: 'Test' }]);
+     *   await ctx.setMockIpc('CREATE_INSTANCE', 'Some error', { type: 'ERROR' });
+     */
+    setMockIpc: (action: string, data: any, options?: {
+        type?: MockIpcResponseType;
+        delayMs?: number;
+    }) => Promise<void>;
+    /** Return all intercepted console.error and pageerror logs */
+    getConsoleErrors: () => ConsoleEntry[];
+    /** Return all intercepted console.warn logs */
+    getConsoleWarnings: () => ConsoleEntry[];
+    /** Returns true if there are critical errors in the console */
+    hasConsoleErrors: () => boolean;
+    /** Get the visible text of a specific element */
+    readText: (selector: string) => Promise<string | null>;
+    /** Get ALL visible text on the page (useful for quick analysis without Vision) */
+    getPageText: () => Promise<string>;
+    /** Check if the element is visible on the screen */
+    isVisible: (selector: string) => Promise<boolean>;
+    /** Count the number of elements matching the selector */
+    getElementCount: (selector: string) => Promise<number>;
+}
+interface VisualScenario {
+    /** Unique scenario identifier (kebab-case) */
+    id: string;
+    /** Human-readable title for the report */
+    title: string;
+    /** Description of what is being tested */
+    description?: string;
+    /** Initial route to navigate to (e.g., '/instances', '/settings') */
+    route?: string;
+    /** List of viewport sizes to test */
+    viewports?: ViewportPreset[];
+    /**
+     * Initial IPC mock data for preview mode.
+     * Applied BEFORE navigation to the route.
+     */
+    mockIpc?: Array<{
+        action: string;
+        data: any;
+        type?: MockIpcResponseType;
+        delayMs?: number;
+    }>;
+    /**
+     * Optional setup hook: executed before the browser navigates and scenario runs.
+     * Ideal for preparing mock files, test directories, or initial state.
+     */
+    setup?: () => Promise<void> | void;
+    /** The main body of the scenario */
+    run: (ctx: TestContext) => Promise<void>;
+    /**
+     * Optional teardown hook: guaranteed to execute in finally, even if run() fails.
+     * Ideal for cleaning up test artifacts, cache directories, or temporary state.
+     */
+    teardown?: () => Promise<void> | void;
+}
+declare function defineVisualTest(scenario: VisualScenario): VisualScenario;
+
+export { type CaptureBurstOptions, type CaptureOptions, type SnapshotMetadata, type TestContext, VIEWPORT_PRESETS, type ViewportPreset, type VisualScenario, defineVisualTest };

package/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/shared/api/dsl.ts
+var dsl_exports = {};
+__export(dsl_exports, {
+  VIEWPORT_PRESETS: () => VIEWPORT_PRESETS,
+  defineVisualTest: () => defineVisualTest
+});
+module.exports = __toCommonJS(dsl_exports);
+var VIEWPORT_PRESETS = {
+  /** Minimum supported window size (e.g., ) */
+  MIN_SUPPORTED: { name: "min-supported", width: 1024, height: 768 },
+  /** Standard default window size (e.g., ) */
+  DEFAULT: { name: "default", width: 1200, height: 800 },
+  /** Wide screen for checking grids and tables */
+  WIDE: { name: "wide", width: 1600, height: 900 },
+  /** Full HD */
+  FULL_HD: { name: "full-hd", width: 1920, height: 1080 }
+};
+function defineVisualTest(scenario) {
+  return scenario;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VIEWPORT_PRESETS,
+  defineVisualTest
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/api/dsl.ts"],"sourcesContent":["import type { Page, BrowserContext } from 'playwright';\nimport type { ConsoleEntry } from '../../features/console-tracker/consoleTracker';\nimport type { MockIpcResponseType } from '../../features/mock-ipc/mockIpc';\n\nexport interface ViewportPreset {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport const VIEWPORT_PRESETS = {\n  /** Minimum supported window size (e.g., ) */\n  MIN_SUPPORTED: { name: 'min-supported', width: 1024, height: 768 } as ViewportPreset,\n  /** Standard default window size (e.g., ) */\n  DEFAULT: { name: 'default', width: 1200, height: 800 } as ViewportPreset,\n  /** Wide screen for checking grids and tables */\n  WIDE: { name: 'wide', width: 1600, height: 900 } as ViewportPreset,\n  /** Full HD */\n  FULL_HD: { name: 'full-hd', width: 1920, height: 1080 } as ViewportPreset,\n};\n\nexport interface CaptureOptions {\n  selector?: string;\n  fullPage?: boolean;\n  mask?: string[];\n}\n\nexport interface CaptureBurstOptions {\n  /** Total duration of burst animation capture in milliseconds */\n  durationMs: number;\n  /** Interval between frames in milliseconds (default: 80ms) */\n  intervalMs?: number;\n  /** Restrict capture to a specific element */\n  selector?: string;\n}\n\nexport interface SnapshotMetadata {\n  index: number;\n  name: string;\n  fileName: string;\n  filePath: string;\n  relativeUri: string;\n  viewport: { width: number; height: number };\n  timestamp: string;\n  isBurstFrame?: boolean;\n  burstGroup?: string;\n  frameIndex?: number;\n  selector?: string;\n}\n\nexport interface TestContext {\n  page: Page;\n  context: BrowserContext;\n  targetMode: 'desktop' | 'preview';\n  currentViewport: { width: number; height: number };\n  \n  // --- Snapshots ---\n\n  /** Capture a single high-quality snapshot of the window or element */\n  capture: (name: string, options?: CaptureOptions) => Promise<SnapshotMetadata>;\n  \n  /** Capture a series of frames for animations (Framer Motion, modals, lists) */\n  captureBurst: (name: string, options: CaptureBurstOptions) => Promise<SnapshotMetadata[]>;\n  \n  // --- Navigation ---\n\n  /** \n   * Dynamically navigate to another page during the test.\n   * Example: await ctx.navigate('/settings');\n   */\n  navigate: (route: string) => Promise<void>;\n\n  // --- Viewport ---\n\n  /** Change window / viewport size */\n  resize: (width: number, height: number) => Promise<void>;\n  \n  /** Set one of the standard presets (MIN_SUPPORTED, DEFAULT, WIDE) */\n  setPreset: (preset: ViewportPreset) => Promise<void>;\n\n  /** \n   * Dynamically resize the window so it perfectly fits the specified element (or body).\n   * Useful when an agent wants to test an isolated component without background clutter.\n   */\n  resizeToFit: (selector?: string, padding?: number) => Promise<void>;\n  \n  // --- Waiting ---\n\n  /** Wait the specified amount of milliseconds */\n  wait: (ms: number) => Promise<void>;\n  \n  /** Wait for the selector to appear in the DOM */\n  waitForSelector: (selector: string, timeoutMs?: number) => Promise<void>;\n  \n  // --- Interaction ---\n\n  /** Left-click the element */\n  click: (selector: string) => Promise<void>;\n  \n  /** Right-click the element (Context Menu) */\n  rightClick: (selector: string) => Promise<void>;\n  \n  /** Type text into an input field */\n  type: (selector: string, text: string) => Promise<void>;\n  \n  /** Select an option in a <select> by its value */\n  selectOption: (selector: string, value: string) => Promise<void>;\n  \n  /** Hover the cursor to check highlights / tooltips */\n  hover: (selector: string) => Promise<void>;\n  \n  /** Scroll the element (or window) down by the specified number of pixels */\n  scroll: (selector: string, deltaY: number) => Promise<void>;\n  \n  // --- Logging ---\n\n  /** Log a step for the agent */\n  log: (message: string) => void;\n\n  // --- Mock IPC (preview mode only) ---\n\n  /**\n   * Set a mock response for an IPC action.\n   * Changes the data returned by window.external.sendMessage in preview mode.\n   * Ignored in desktop mode (IPC goes through real backend).\n   *\n   * Example:\n   *   await ctx.setMockIpc('GET_INSTANCES', [{ id: '...', name: 'Test' }]);\n   *   await ctx.setMockIpc('CREATE_INSTANCE', 'Some error', { type: 'ERROR' });\n   */\n  setMockIpc: (action: string, data: any, options?: { type?: MockIpcResponseType; delayMs?: number }) => Promise<void>;\n\n  // --- Console Errors ---\n\n  /** Return all intercepted console.error and pageerror logs */\n  getConsoleErrors: () => ConsoleEntry[];\n\n  /** Return all intercepted console.warn logs */\n  getConsoleWarnings: () => ConsoleEntry[];\n\n  /** Returns true if there are critical errors in the console */\n  hasConsoleErrors: () => boolean;\n\n  // --- DOM Assertions ---\n\n  /** Get the visible text of a specific element */\n  readText: (selector: string) => Promise<string | null>;\n  \n  /** Get ALL visible text on the page (useful for quick analysis without Vision) */\n  getPageText: () => Promise<string>;\n  \n  /** Check if the element is visible on the screen */\n  isVisible: (selector: string) => Promise<boolean>;\n\n  /** Count the number of elements matching the selector */\n  getElementCount: (selector: string) => Promise<number>;\n}\n\nexport interface VisualScenario {\n  /** Unique scenario identifier (kebab-case) */\n  id: string;\n  /** Human-readable title for the report */\n  title: string;\n  /** Description of what is being tested */\n  description?: string;\n  /** Initial route to navigate to (e.g., '/instances', '/settings') */\n  route?: string;\n  /** List of viewport sizes to test */\n  viewports?: ViewportPreset[];\n  /**\n   * Initial IPC mock data for preview mode.\n   * Applied BEFORE navigation to the route.\n   */\n  mockIpc?: Array<{ action: string; data: any; type?: MockIpcResponseType; delayMs?: number }>;\n  /**\n   * Optional setup hook: executed before the browser navigates and scenario runs.\n   * Ideal for preparing mock files, test directories, or initial state.\n   */\n  setup?: () => Promise<void> | void;\n  /** The main body of the scenario */\n  run: (ctx: TestContext) => Promise<void>;\n  /**\n   * Optional teardown hook: guaranteed to execute in finally, even if run() fails.\n   * Ideal for cleaning up test artifacts, cache directories, or temporary state.\n   */\n  teardown?: () => Promise<void> | void;\n}\n\nexport function defineVisualTest(scenario: VisualScenario): VisualScenario {\n  return scenario;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,IAAM,mBAAmB;AAAA;AAAA,EAE9B,eAAe,EAAE,MAAM,iBAAiB,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAEjE,SAAS,EAAE,MAAM,WAAW,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAErD,MAAM,EAAE,MAAM,QAAQ,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAE/C,SAAS,EAAE,MAAM,WAAW,OAAO,MAAM,QAAQ,KAAK;AACxD;AAyKO,SAAS,iBAAiB,UAA0C;AACzE,SAAO;AACT;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,19 @@
+// src/shared/api/dsl.ts
+var VIEWPORT_PRESETS = {
+  /** Minimum supported window size (e.g., ) */
+  MIN_SUPPORTED: { name: "min-supported", width: 1024, height: 768 },
+  /** Standard default window size (e.g., ) */
+  DEFAULT: { name: "default", width: 1200, height: 800 },
+  /** Wide screen for checking grids and tables */
+  WIDE: { name: "wide", width: 1600, height: 900 },
+  /** Full HD */
+  FULL_HD: { name: "full-hd", width: 1920, height: 1080 }
+};
+function defineVisualTest(scenario) {
+  return scenario;
+}
+export {
+  VIEWPORT_PRESETS,
+  defineVisualTest
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/api/dsl.ts"],"sourcesContent":["import type { Page, BrowserContext } from 'playwright';\nimport type { ConsoleEntry } from '../../features/console-tracker/consoleTracker';\nimport type { MockIpcResponseType } from '../../features/mock-ipc/mockIpc';\n\nexport interface ViewportPreset {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport const VIEWPORT_PRESETS = {\n  /** Minimum supported window size (e.g., ) */\n  MIN_SUPPORTED: { name: 'min-supported', width: 1024, height: 768 } as ViewportPreset,\n  /** Standard default window size (e.g., ) */\n  DEFAULT: { name: 'default', width: 1200, height: 800 } as ViewportPreset,\n  /** Wide screen for checking grids and tables */\n  WIDE: { name: 'wide', width: 1600, height: 900 } as ViewportPreset,\n  /** Full HD */\n  FULL_HD: { name: 'full-hd', width: 1920, height: 1080 } as ViewportPreset,\n};\n\nexport interface CaptureOptions {\n  selector?: string;\n  fullPage?: boolean;\n  mask?: string[];\n}\n\nexport interface CaptureBurstOptions {\n  /** Total duration of burst animation capture in milliseconds */\n  durationMs: number;\n  /** Interval between frames in milliseconds (default: 80ms) */\n  intervalMs?: number;\n  /** Restrict capture to a specific element */\n  selector?: string;\n}\n\nexport interface SnapshotMetadata {\n  index: number;\n  name: string;\n  fileName: string;\n  filePath: string;\n  relativeUri: string;\n  viewport: { width: number; height: number };\n  timestamp: string;\n  isBurstFrame?: boolean;\n  burstGroup?: string;\n  frameIndex?: number;\n  selector?: string;\n}\n\nexport interface TestContext {\n  page: Page;\n  context: BrowserContext;\n  targetMode: 'desktop' | 'preview';\n  currentViewport: { width: number; height: number };\n  \n  // --- Snapshots ---\n\n  /** Capture a single high-quality snapshot of the window or element */\n  capture: (name: string, options?: CaptureOptions) => Promise<SnapshotMetadata>;\n  \n  /** Capture a series of frames for animations (Framer Motion, modals, lists) */\n  captureBurst: (name: string, options: CaptureBurstOptions) => Promise<SnapshotMetadata[]>;\n  \n  // --- Navigation ---\n\n  /** \n   * Dynamically navigate to another page during the test.\n   * Example: await ctx.navigate('/settings');\n   */\n  navigate: (route: string) => Promise<void>;\n\n  // --- Viewport ---\n\n  /** Change window / viewport size */\n  resize: (width: number, height: number) => Promise<void>;\n  \n  /** Set one of the standard presets (MIN_SUPPORTED, DEFAULT, WIDE) */\n  setPreset: (preset: ViewportPreset) => Promise<void>;\n\n  /** \n   * Dynamically resize the window so it perfectly fits the specified element (or body).\n   * Useful when an agent wants to test an isolated component without background clutter.\n   */\n  resizeToFit: (selector?: string, padding?: number) => Promise<void>;\n  \n  // --- Waiting ---\n\n  /** Wait the specified amount of milliseconds */\n  wait: (ms: number) => Promise<void>;\n  \n  /** Wait for the selector to appear in the DOM */\n  waitForSelector: (selector: string, timeoutMs?: number) => Promise<void>;\n  \n  // --- Interaction ---\n\n  /** Left-click the element */\n  click: (selector: string) => Promise<void>;\n  \n  /** Right-click the element (Context Menu) */\n  rightClick: (selector: string) => Promise<void>;\n  \n  /** Type text into an input field */\n  type: (selector: string, text: string) => Promise<void>;\n  \n  /** Select an option in a <select> by its value */\n  selectOption: (selector: string, value: string) => Promise<void>;\n  \n  /** Hover the cursor to check highlights / tooltips */\n  hover: (selector: string) => Promise<void>;\n  \n  /** Scroll the element (or window) down by the specified number of pixels */\n  scroll: (selector: string, deltaY: number) => Promise<void>;\n  \n  // --- Logging ---\n\n  /** Log a step for the agent */\n  log: (message: string) => void;\n\n  // --- Mock IPC (preview mode only) ---\n\n  /**\n   * Set a mock response for an IPC action.\n   * Changes the data returned by window.external.sendMessage in preview mode.\n   * Ignored in desktop mode (IPC goes through real backend).\n   *\n   * Example:\n   *   await ctx.setMockIpc('GET_INSTANCES', [{ id: '...', name: 'Test' }]);\n   *   await ctx.setMockIpc('CREATE_INSTANCE', 'Some error', { type: 'ERROR' });\n   */\n  setMockIpc: (action: string, data: any, options?: { type?: MockIpcResponseType; delayMs?: number }) => Promise<void>;\n\n  // --- Console Errors ---\n\n  /** Return all intercepted console.error and pageerror logs */\n  getConsoleErrors: () => ConsoleEntry[];\n\n  /** Return all intercepted console.warn logs */\n  getConsoleWarnings: () => ConsoleEntry[];\n\n  /** Returns true if there are critical errors in the console */\n  hasConsoleErrors: () => boolean;\n\n  // --- DOM Assertions ---\n\n  /** Get the visible text of a specific element */\n  readText: (selector: string) => Promise<string | null>;\n  \n  /** Get ALL visible text on the page (useful for quick analysis without Vision) */\n  getPageText: () => Promise<string>;\n  \n  /** Check if the element is visible on the screen */\n  isVisible: (selector: string) => Promise<boolean>;\n\n  /** Count the number of elements matching the selector */\n  getElementCount: (selector: string) => Promise<number>;\n}\n\nexport interface VisualScenario {\n  /** Unique scenario identifier (kebab-case) */\n  id: string;\n  /** Human-readable title for the report */\n  title: string;\n  /** Description of what is being tested */\n  description?: string;\n  /** Initial route to navigate to (e.g., '/instances', '/settings') */\n  route?: string;\n  /** List of viewport sizes to test */\n  viewports?: ViewportPreset[];\n  /**\n   * Initial IPC mock data for preview mode.\n   * Applied BEFORE navigation to the route.\n   */\n  mockIpc?: Array<{ action: string; data: any; type?: MockIpcResponseType; delayMs?: number }>;\n  /**\n   * Optional setup hook: executed before the browser navigates and scenario runs.\n   * Ideal for preparing mock files, test directories, or initial state.\n   */\n  setup?: () => Promise<void> | void;\n  /** The main body of the scenario */\n  run: (ctx: TestContext) => Promise<void>;\n  /**\n   * Optional teardown hook: guaranteed to execute in finally, even if run() fails.\n   * Ideal for cleaning up test artifacts, cache directories, or temporary state.\n   */\n  teardown?: () => Promise<void> | void;\n}\n\nexport function defineVisualTest(scenario: VisualScenario): VisualScenario {\n  return scenario;\n}\n"],"mappings":";AAUO,IAAM,mBAAmB;AAAA;AAAA,EAE9B,eAAe,EAAE,MAAM,iBAAiB,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAEjE,SAAS,EAAE,MAAM,WAAW,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAErD,MAAM,EAAE,MAAM,QAAQ,OAAO,MAAM,QAAQ,IAAI;AAAA;AAAA,EAE/C,SAAS,EAAE,MAAM,WAAW,OAAO,MAAM,QAAQ,KAAK;AACxD;AAyKO,SAAS,iBAAiB,UAA0C;AACzE,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@_deep4wee/agent-lens",
+  "version": "1.0.1",
+  "description": "Visual self-check UI runner for AI coding agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agent-lens": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"const fs = require('fs'); ['dist', 'artifacts'].forEach(d => fs.rmSync(d, {recursive: true, force: true})); const files = fs.readdirSync('.'); files.filter(f => f.endsWith('.tgz')).forEach(f => fs.unlinkSync(f));\"",
+    "build": "npm run clean && tsup",
+    "build:pack": "npm run build && npm pack",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "playwright": "^1.63.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "tree-kill": "^1.2.2"
+  },
+  "author": "deep4wee",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deep4wee/agent-lens.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "visual",
+    "testing",
+    "playwright",
+    "automation",
+    "screenshot",
+    "ui"
+  ],
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/deep4wee/agent-lens/issues"
+  },
+  "homepage": "https://github.com/deep4wee/agent-lens#readme"
+}

package/scripts/postinstall.js

@@ -0,0 +1,47 @@
+const fs = require('fs');
+const path = require('path');
+
+// When installed via npm, INIT_CWD is the root of the project installing this package.
+// If not available, fallback to process.cwd() (though usually that's the package dir itself).
+const targetProjectRoot = process.env.INIT_CWD || process.cwd();
+
+const skillSourceDir = path.join(__dirname, '../skills/agent-lens');
+const targetSkillDir = path.join(targetProjectRoot, '.agents', 'skills', 'agent-lens');
+
+function copySkillRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copySkillRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function copySkill() {
+  try {
+    if (!fs.existsSync(skillSourceDir)) {
+      return;
+    }
+
+    copySkillRecursive(skillSourceDir, targetSkillDir);
+    console.log(`[AgentLens] Successfully equipped AI skill at ${targetSkillDir}`);
+  } catch (error) {
+    console.warn('[AgentLens] Warning: Failed to copy SKILL.md automatically:', error.message);
+  }
+}
+
+// Don't run postinstall if we are developing inside the agent-lens repo itself
+if (path.resolve(targetProjectRoot) !== path.resolve(path.join(__dirname, '..'))) {
+  copySkill();
+}

package/skills/agent-lens/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: agent-lens
+description: Visual UI self-verification tool for AI agents. Take responsive multi-viewport snapshots of live URLs or run scripted interaction scenarios in Chromium or native desktop WebView2. Catches visual regressions, layout shifts, silent console errors, and runtime exceptions.
+---
+
+# 👁️ AgentLens
+
+**AgentLens** is a visual self-verification tool designed specifically for autonomous AI coding agents.
+
+Instead of writing frontend code and blindly guessing if it looks right, AgentLens gives you **eyes**. You can capture multi-viewport screenshots of your running app, focus on isolated components, test animations, intercept silent JavaScript errors, and inspect the resulting markdown report to iterate autonomously before showing the final result to the user.
+
+---
+
+## ⚡ Two Modes of Agent Verification
+
+### 1. Instant Verification (`snap`) — No test files needed!
+Ideal for 90% of tasks when you just modified a page, component, or layout:
+```bash
+# Verify a live dev server across desktop & mobile viewports:
+npx agent-lens snap --url=http://localhost:5173
+
+# Auto-start dev server in a monorepo (e.g. Frontend/), snap, and auto-terminate:
+npx agent-lens snap --start="npm run dev" --start-cwd=./Frontend
+
+# Zero-config smart snap (auto-detects active server or static build):
+npx agent-lens snap
+
+# Focus strictly on one component:
+npx agent-lens snap --url=http://localhost:5173/settings --selector=".pricing-card"
+```
+
+### 2. Scripted Scenarios (`npx agent-lens --scenario=<name>`)
+For multi-step flows, form submissions, state mocks, and complex assertions:
+```bash
+npx agent-lens --scenario=checkout-flow --url=http://localhost:5173
+```
+
+---
+
+## 🧭 The Agent Workflow
+
+1. **Write or Edit the Code**: Implement the requested UI changes or components.
+2. **Choose Your Verification Method**:
+   - **Quick check**: Run `npx agent-lens snap`.
+   - **Interactive check**: Write a scenario file in `scenarios/<name>.scenario.ts`.
+3. **Execute the Runner**:
+   ```bash
+   npx agent-lens snap --url=http://localhost:5173
+   ```
+4. **Inspect the Output**:
+   - AgentLens always writes the latest report to:
+     `artifacts/latest/report.md`
+   - Use `view_file` to read `artifacts/latest/report.md` immediately without worrying about timestamped folder names.
+   - Check the **Console Errors** section — if errors exist, fix them!
+5. **Self-Correct & Iterate**: Re-run verification until the layout is solid and the console is clean.
+
+---
+
+## ⚠️ Agent Best Practices & Pitfalls to Avoid
+
+### 1. Avoid Localized Text in Selectors (Localization Pitfall)
+❌ **Never write:**
+```typescript
+await ctx.type('input[placeholder*="Search"]', 'text'); // Fails if language is Ukrainian "Пошук"!
+await ctx.click('button:has-text("Save")');            // Fails on non-English UI!
+```
+✅ **Always use semantic attributes, test IDs, or structural CSS:**
+```typescript
+await ctx.type('input[type="search"]', 'text');
+await ctx.type('input[name="query"]', 'text');
+await ctx.click('button[type="submit"]');
+await ctx.click('[data-testid="save-button"]');
+```
+
+### 2. Base Mocks in `scenarios/mocks.ts` (Prevent Root Crashes)
+When your app mounts, the root component (Navbar, AuthContext, Layout) often queries base endpoints (e.g. `GET_USER`, `GET_SETTINGS`, `GET_ACCOUNTS`). If your scenario only mocks one sub-action, unmocked root actions may return empty and crash the app with `Cannot read properties of null (reading 'length')`.
+- Place common base mocks in `scenarios/mocks.ts`.
+- AgentLens automatically merges `scenarios/mocks.ts` with your scenario's specific `mockIpc: [...]` overrides!
+
+### 3. Monorepos & Subdirectories (`--start-cwd`)
+If your frontend lives in a subfolder like `Frontend/` or `client/`:
+- Pass `--start-cwd=./Frontend` (or configure `"startCwd": "./Frontend"` in `agent-lens.json`).
+- AgentLens automatically auto-detects `Frontend/`, `client/`, or `web/` if root `package.json` lacks a `dev` script.
+
+### 4. Preventing Artifact Folder Bloat
+To keep the workspace tidy across multiple test iterations, use:
+```bash
+npx agent-lens snap --clean-artifacts
+```
+Or always inspect the single persistent pointer:
+`artifacts/latest/report.md`
+
+---
+
+## 💻 CLI Flags & Options
+
+```bash
+npx agent-lens [command] [options]
+```
+
+### Commands:
+- `snap`: Instant one-shot snapshot & console check of a URL or static build.
+- `init`: Generate starter template in `scenarios/template.scenario.ts` and `scenarios/mocks.ts`.
+- *(default)*: Runs matching scenarios from `scenarios/`.
+
+### Options:
+| Flag | Description | Default |
+| :--- | :--- | :--- |
+| `--url=<url>` | Target URL to test (e.g. `http://localhost:5173`) | *Auto-detected* |
+| `--start="<cmd>"` | Auto-launch dev server / backend before test | *(none)* |
+| `--start-cwd=<path>` | Directory to run `--start` in (e.g. `--start-cwd=./Frontend`) | *Auto-detected* |
+| `--clean-artifacts` | Purge older test runs in `artifacts/` | `false` |
+| `--selector=<css>` | Focus and resize-to-fit a specific component | *(none)* |
+| `--viewports=<list>` | Viewports to capture (`desktop,mobile,tablet` or `1200x800`) | `desktop,mobile` |
+| `--wait=<ms>` | Wait time after page load before taking snapshots | `1000` |
+| `--scenario=<id>` | Name or prefix of scenario file to run | *(none)* |
+| `--all` | Run all discovered scenarios | `false` |
+| `--mode=preview\|desktop` | Engine: `preview` (Web / Live URL) or `desktop` (native .exe) | `preview` |
+| `--exe=<path>` | Path to compiled desktop executable for desktop mode | *(none)* |
+| `--port=<port>` | CDP remote debugging port for desktop mode | `9222` |
+| `--build[=<cmd>]` | Build command to run before testing | `npm run build` |
+| `--clean=<paths>` | Comma-separated paths to purge on exit | *(none)* |
+| `--folder=<path>` | Folder to store report & screenshots (also `--outDir`) | `artifacts` |
+| `--headed` | Open visible browser window | `false` |
+| `--detach` | Do not close browser or app on finish | `false` |
+
+---
+
+## 🛠️ DSL API Reference (`scenarios/*.scenario.ts`)
+
+```typescript
+import { defineVisualTest, VIEWPORT_PRESETS, type TestContext } from 'agent-lens';
+```
+
+### Scenario Definition Structure:
+```typescript
+export default defineVisualTest({
+  id: 'my-feature-check',
+  title: 'Feature Verification',
+  route: '/dashboard', // Route or URL
+  viewports: [VIEWPORT_PRESETS.DEFAULT, VIEWPORT_PRESETS.MIN_SUPPORTED],
+  
+  // Lifecycle Setup: prepare temporary state or mock folders
+  setup: async () => {},
+
+  // Test Body: interact and capture
+  run: async (ctx) => {},
+
+  // Lifecycle Teardown: ALWAYS executes, guaranteed cleanup
+  teardown: async () => {}
+});
+```
+
+### Available `ctx` Methods:
+
+#### 📸 Capturing
+- `await ctx.capture('01_name', options?)`: Capture full page or element snapshot.
+- `await ctx.captureBurst('02_anim', { durationMs: 300, intervalMs: 50, selector? })`: Capture animation frames.
+
+#### 📐 Viewport Control
+- `await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT)`: Standard desktop (1200x800).
+- `await ctx.setPreset(VIEWPORT_PRESETS.MIN_SUPPORTED)`: Compact viewport (1024x768).
+- `await ctx.setPreset(VIEWPORT_PRESETS.WIDE)`: Widescreen (1600x900).
+- `await ctx.resize(width, height)`: Custom dimensions.
+- `await ctx.resizeToFit('selector', padding?)`: Dynamically resize viewport to wrap an element tightly.
+
+#### 🖱️ Interactions
+- `await ctx.click('selector')` / `await ctx.rightClick('selector')`
+- `await ctx.type('selector', 'text')`
+- `await ctx.selectOption('selector', 'value')`
+- `await ctx.hover('selector')`
+- `await ctx.scroll('selector', deltaY)`
+
+#### 🕒 Waiting & Assertions
+- `await ctx.wait(ms)`
+- `await ctx.waitForSelector('selector', timeoutMs?)`
+- `const text = await ctx.readText('selector')`
+- `const pageText = await ctx.getPageText()`
+- `const isVisible = await ctx.isVisible('selector')`
+- `const count = await ctx.getElementCount('selector')`
+
+#### 🐛 Console & Logs
+- `ctx.log('Message')`: Writes custom log entry into the final markdown report.
+- `ctx.getConsoleErrors()`: Array of caught errors with stack traces.
+- `ctx.getConsoleWarnings()`: Array of caught warnings.
+
+#### 🎭 Dynamic Mock IPC (Web / Preview mode)
+- `await ctx.setMockIpc('ACTION_NAME', payload, { type: 'SUCCESS' | 'ERROR', delayMs?: number })`: Dynamically alters mock data during test execution.
+
+---
+
+## 📚 Detailed Examples & Use Cases
+
+Check the dedicated example guides in `examples/` for complete walk-throughs:
+1. [Instant Verification (`snap`)](examples/01-instant-verification-snap.md) — One-shot snapshotting without writing test files.
+2. [Live Dev Server Workflow](examples/02-dev-server-live-testing.md) — Testing active Vite/Next.js servers with `--start` or `--url`.
+3. [Component Isolation & Burst Animations](examples/03-component-isolation-and-animations.md) — Inspecting isolated components and CSS transitions.
+4. [Native Desktop App Testing](examples/04-desktop-native-testing.md) — Testing compiled `.exe` binaries with CDP and crash diagnostics.
+5. [Clean Teardown & Sandboxing](examples/05-clean-teardown-and-sandboxing.md) — Guaranteeing zero leftover test data using `teardown()` and `--clean`.
+6. [State Testing with Mock IPC](examples/06-state-testing-with-mock-ipc.md) — Testing empty states, errors, and data tables.

package/skills/agent-lens/examples/01-instant-verification-snap.md

@@ -0,0 +1,53 @@
+# Example 1: Instant Visual Self-Check (`snap`)
+
+The `snap` command is the fastest way for an AI agent to "see" its work immediately without writing any scenario files.
+
+## Use Cases
+- After generating or editing a component, web page, or modal.
+- Quickly verifying responsiveness across desktop and mobile screens.
+- Checking for silent console errors and runtime exceptions.
+
+## Basic Usage
+
+```bash
+# Check an already-running dev server
+npx agent-lens snap --url=http://localhost:5173
+```
+
+## Options & Combinations
+
+### 1. Test Multiple Viewports (Desktop, Tablet, Mobile)
+```bash
+npx agent-lens snap \
+  --url=http://localhost:3000/dashboard \
+  --viewports=desktop,tablet,mobile
+```
+
+### 2. Auto-Start Dev Server
+If your dev server is not running yet, AgentLens can start it automatically, wait until it's ready, take the snapshots, and cleanly terminate the server when finished:
+```bash
+npx agent-lens snap \
+  --start="npm run dev" \
+  --url=http://localhost:5173 \
+  --wait=1500
+```
+
+### 3. Focus on a Specific Component (`--selector`)
+Take responsive snapshots of the entire page AND an isolated, fitted snapshot of a single component:
+```bash
+npx agent-lens snap \
+  --url=http://localhost:5173/settings \
+  --selector=".pricing-card" \
+  --name="pricing_component"
+```
+
+### 4. Custom Output Directory
+Save visual reports directly to a project folder (make sure to add it to `.gitignore`):
+```bash
+npx agent-lens snap \
+  --url=http://localhost:5173 \
+  --folder=visual-reports
+```
+
+## Reading the Result
+AgentLens outputs the absolute path to `report.md`. Inspect the markdown report using your file reading tool to review the images and console logs.