@_deep4wee/agent-lens 1.0.1 → 1.1.0

package/dist/index.d.mts

@@ -30,6 +30,14 @@ declare const VIEWPORT_PRESETS: {
     /** Full HD */
     FULL_HD: ViewportPreset;
 };
+interface MockRouteEntry {
+    url: string;
+    method?: string;
+    status?: number;
+    body: any;
+    delayMs?: number;
+    headers?: Record<string, string>;
+}
 interface CaptureOptions {
     selector?: string;
     fullPage?: boolean;
@@ -105,17 +113,27 @@ interface TestContext {
     log: (message: string) => void;
     /**
      * Set a mock response for an IPC action.
-     * Changes the data returned by window.external.sendMessage in preview mode.
+     * Changes the data returned by window.__mockIpc.invoke or hybrid bridges 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>;
+    /**
+     * Mock an HTTP REST or GraphQL network request in preview mode.
+     * Intercepts fetch/axios calls matching the URL pattern and returns mock data.
+     *
+     * Example:
+     *   await ctx.setMockRoute('/api/user', { id: 1, name: 'Agent' });
+     *   await ctx.setMockRoute('**\/api/items*', [], { status: 200, delayMs: 50 });
+     */
+    setMockRoute: (url: string, body: any, options?: {
+        method?: string;
+        status?: number;
+        delayMs?: number;
+        headers?: Record<string, string>;
+    }) => Promise<void>;
     /** Return all intercepted console.error and pageerror logs */
     getConsoleErrors: () => ConsoleEntry[];
     /** Return all intercepted console.warn logs */
@@ -143,15 +161,20 @@ interface VisualScenario {
     /** List of viewport sizes to test */
     viewports?: ViewportPreset[];
     /**
-     * Initial IPC mock data for preview mode.
-     * Applied BEFORE navigation to the route.
-     */
+   * Initial IPC mock data for preview mode.
+   * Applied BEFORE navigation to the route.
+   */
     mockIpc?: Array<{
         action: string;
         data: any;
         type?: MockIpcResponseType;
         delayMs?: number;
     }>;
+    /**
+     * Initial HTTP REST/GraphQL route mocks for preview mode.
+     * Applied BEFORE navigation to the route.
+     */
+    mockRoutes?: MockRouteEntry[];
     /**
      * Optional setup hook: executed before the browser navigates and scenario runs.
      * Ideal for preparing mock files, test directories, or initial state.
@@ -167,4 +190,4 @@ interface VisualScenario {
 }
 declare function defineVisualTest(scenario: VisualScenario): VisualScenario;
 
-export { type CaptureBurstOptions, type CaptureOptions, type SnapshotMetadata, type TestContext, VIEWPORT_PRESETS, type ViewportPreset, type VisualScenario, defineVisualTest };
+export { type CaptureBurstOptions, type CaptureOptions, type MockRouteEntry, type SnapshotMetadata, type TestContext, VIEWPORT_PRESETS, type ViewportPreset, type VisualScenario, defineVisualTest };

package/dist/index.d.ts

@@ -30,6 +30,14 @@ declare const VIEWPORT_PRESETS: {
     /** Full HD */
     FULL_HD: ViewportPreset;
 };
+interface MockRouteEntry {
+    url: string;
+    method?: string;
+    status?: number;
+    body: any;
+    delayMs?: number;
+    headers?: Record<string, string>;
+}
 interface CaptureOptions {
     selector?: string;
     fullPage?: boolean;
@@ -105,17 +113,27 @@ interface TestContext {
     log: (message: string) => void;
     /**
      * Set a mock response for an IPC action.
-     * Changes the data returned by window.external.sendMessage in preview mode.
+     * Changes the data returned by window.__mockIpc.invoke or hybrid bridges 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>;
+    /**
+     * Mock an HTTP REST or GraphQL network request in preview mode.
+     * Intercepts fetch/axios calls matching the URL pattern and returns mock data.
+     *
+     * Example:
+     *   await ctx.setMockRoute('/api/user', { id: 1, name: 'Agent' });
+     *   await ctx.setMockRoute('**\/api/items*', [], { status: 200, delayMs: 50 });
+     */
+    setMockRoute: (url: string, body: any, options?: {
+        method?: string;
+        status?: number;
+        delayMs?: number;
+        headers?: Record<string, string>;
+    }) => Promise<void>;
     /** Return all intercepted console.error and pageerror logs */
     getConsoleErrors: () => ConsoleEntry[];
     /** Return all intercepted console.warn logs */
@@ -143,15 +161,20 @@ interface VisualScenario {
     /** List of viewport sizes to test */
     viewports?: ViewportPreset[];
     /**
-     * Initial IPC mock data for preview mode.
-     * Applied BEFORE navigation to the route.
-     */
+   * Initial IPC mock data for preview mode.
+   * Applied BEFORE navigation to the route.
+   */
     mockIpc?: Array<{
         action: string;
         data: any;
         type?: MockIpcResponseType;
         delayMs?: number;
     }>;
+    /**
+     * Initial HTTP REST/GraphQL route mocks for preview mode.
+     * Applied BEFORE navigation to the route.
+     */
+    mockRoutes?: MockRouteEntry[];
     /**
      * Optional setup hook: executed before the browser navigates and scenario runs.
      * Ideal for preparing mock files, test directories, or initial state.
@@ -167,4 +190,4 @@ interface VisualScenario {
 }
 declare function defineVisualTest(scenario: VisualScenario): VisualScenario;
 
-export { type CaptureBurstOptions, type CaptureOptions, type SnapshotMetadata, type TestContext, VIEWPORT_PRESETS, type ViewportPreset, type VisualScenario, defineVisualTest };
+export { type CaptureBurstOptions, type CaptureOptions, type MockRouteEntry, type SnapshotMetadata, type TestContext, VIEWPORT_PRESETS, type ViewportPreset, type VisualScenario, defineVisualTest };

package/dist/index.js.map

@@ -1 +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":[]}
+{"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 MockRouteEntry {\n  url: string;\n  method?: string;\n  status?: number;\n  body: any;\n  delayMs?: number;\n  headers?: Record<string, string>;\n}\n\nexport interface CaptureOptions {\n  selector?: string;\n  fullPage?: boolean;\n  mask?: string[];\n}\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 & Network Routes (preview mode only) ---\n\n  /**\n   * Set a mock response for an IPC action.\n   * Changes the data returned by window.__mockIpc.invoke or hybrid bridges in preview mode.\n   * Ignored in desktop mode (IPC goes through real backend).\n   */\n  setMockIpc: (action: string, data: any, options?: { type?: MockIpcResponseType; delayMs?: number }) => Promise<void>;\n\n  /**\n   * Mock an HTTP REST or GraphQL network request in preview mode.\n   * Intercepts fetch/axios calls matching the URL pattern and returns mock data.\n   *\n   * Example:\n   *   await ctx.setMockRoute('/api/user', { id: 1, name: 'Agent' });\n   *   await ctx.setMockRoute('**\\/api/items*', [], { status: 200, delayMs: 50 });\n   */\n  setMockRoute: (\n    url: string,\n    body: any,\n    options?: { method?: string; status?: number; delayMs?: number; headers?: Record<string, string> }\n  ) => Promise<void>;\n\n  // --- Console Errors ---\n        \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   * Initial HTTP REST/GraphQL route mocks for preview mode.\n   * Applied BEFORE navigation to the route.\n   */\n  mockRoutes?: MockRouteEntry[];\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        \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;AAoMO,SAAS,iBAAiB,UAA0C;AACzE,SAAO;AACT;","names":[]}

package/dist/index.mjs.map

@@ -1 +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":[]}
+{"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 MockRouteEntry {\n  url: string;\n  method?: string;\n  status?: number;\n  body: any;\n  delayMs?: number;\n  headers?: Record<string, string>;\n}\n\nexport interface CaptureOptions {\n  selector?: string;\n  fullPage?: boolean;\n  mask?: string[];\n}\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 & Network Routes (preview mode only) ---\n\n  /**\n   * Set a mock response for an IPC action.\n   * Changes the data returned by window.__mockIpc.invoke or hybrid bridges in preview mode.\n   * Ignored in desktop mode (IPC goes through real backend).\n   */\n  setMockIpc: (action: string, data: any, options?: { type?: MockIpcResponseType; delayMs?: number }) => Promise<void>;\n\n  /**\n   * Mock an HTTP REST or GraphQL network request in preview mode.\n   * Intercepts fetch/axios calls matching the URL pattern and returns mock data.\n   *\n   * Example:\n   *   await ctx.setMockRoute('/api/user', { id: 1, name: 'Agent' });\n   *   await ctx.setMockRoute('**\\/api/items*', [], { status: 200, delayMs: 50 });\n   */\n  setMockRoute: (\n    url: string,\n    body: any,\n    options?: { method?: string; status?: number; delayMs?: number; headers?: Record<string, string> }\n  ) => Promise<void>;\n\n  // --- Console Errors ---\n        \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   * Initial HTTP REST/GraphQL route mocks for preview mode.\n   * Applied BEFORE navigation to the route.\n   */\n  mockRoutes?: MockRouteEntry[];\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        \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;AAoMO,SAAS,iBAAiB,UAA0C;AACzE,SAAO;AACT;","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@_deep4wee/agent-lens",
-  "version": "1.0.1",
-  "description": "Visual self-check UI runner for AI coding agents",
+"version": "1.1.0",
+"description": "Visual self-check UI runner for AI coding agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -27,7 +27,7 @@
     "playwright": "^1.40.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.43",
     "playwright": "^1.63.0",
     "tsup": "^8.0.2",
     "typescript": "^5.0.0"

package/skills/agent-lens/SKILL.md

@@ -48,11 +48,15 @@ npx agent-lens --scenario=checkout-flow --url=http://localhost:5173
    npx agent-lens snap --url=http://localhost:5173
    ```
 4. **Inspect the Output**:
-   - AgentLens always writes the latest report to:
+   - AgentLens always synchronizes the most recent run 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.
+   - **Step 1 (Check Logs & Console)**: Use your file reading tool (`view_file`, `cat`) on `artifacts/latest/report.md`. If there are any **Console Errors**, fix the JavaScript / React exceptions first.
+   - **Step 2 (Vision Visual Check)**: If your environment supports multimodal / vision tools (e.g. `view_image`), inspect the latest generated screenshots directly:
+     `artifacts/latest/01_quick_snap_desktop.png`
+     `artifacts/latest/02_quick_snap_mobile.png`
+     Look for text overflow, unwanted horizontal scrolling, broken CSS flex/grid layouts, or misaligned elements.
+5. **Self-Correct & Iterate**: Re-run verification until the layout is visually solid and the console is clean.
+        
 
 ---
 
@@ -139,6 +143,17 @@ export default defineVisualTest({
   title: 'Feature Verification',
   route: '/dashboard', // Route or URL
   viewports: [VIEWPORT_PRESETS.DEFAULT, VIEWPORT_PRESETS.MIN_SUPPORTED],
+
+  // HTTP REST / GraphQL Network Mocks (Vite / Next.js / Web SPA)
+  mockRoutes: [
+    { url: '**/api/v1/user', body: { id: 1, name: 'Agent', role: 'admin' } },
+    { url: '**/api/v1/stats', body: { total: 42, active: 10 } }
+  ],
+
+  // Optional Hybrid / IPC mocks
+  mockIpc: [
+    { action: 'GET_PREFS', data: { theme: 'dark' } }
+  ],
   
   // Lifecycle Setup: prepare temporary state or mock folders
   setup: async () => {},
@@ -150,6 +165,7 @@ export default defineVisualTest({
   teardown: async () => {}
 });
 ```
+        
 
 ### Available `ctx` Methods:
 
@@ -184,8 +200,10 @@ export default defineVisualTest({
 - `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.
+#### 🌐 Network Route & Mock IPC (Preview mode)
+- `await ctx.setMockRoute('**/api/users', payload, options?)`: Dynamically intercepts HTTP/REST API endpoints and returns mock JSON or status codes.
+- `await ctx.setMockIpc('ACTION_NAME', payload, { type: 'SUCCESS' | 'ERROR', delayMs?: number })`: Dynamically alters mock data for hybrid IPC bridges.
+        
 
 ---
 

package/skills/agent-lens/examples/06-state-testing-with-mock-ipc.md

@@ -1,11 +1,11 @@
-# Example 6: State Testing with Mock IPC
+# Example 6: State Testing with Mock Routes & Mock IPC
 
 Simulate different application states (empty list, loading spinners, network errors, populated data) without running a real backend.
 
 ## Use Cases
-- Verifying Empty States ("No items found").
-- Testing Error Boundaries and error banners when an API fails.
-- Testing data table pagination and high volume data.
+- Verifying HTTP REST / GraphQL states (Empty state, Populated state, 500 Internal Error).
+- Testing React Error Boundaries and error banners when an API endpoint fails.
+- Testing data table pagination and high volume data without database seeding.
 
 ## Writing the Scenario (`scenarios/states.scenario.ts`)
 
@@ -17,11 +17,11 @@ export default defineVisualTest({
   title: 'Empty State vs Populated State Verification',
   route: '/users',
   
-  // 1. Initial State: Populated list
-  mockIpc: [
+  // 1. Initial HTTP Network Mocks (Works with fetch/axios in React, Vue, Next.js)
+  mockRoutes: [
     {
-      action: 'GET_USERS',
-      data: [
+      url: '**/api/users',
+      body: [
         { id: 1, name: 'Alice Cooper', role: 'Administrator' },
         { id: 2, name: 'Bob Marley', role: 'Editor' }
       ]
@@ -35,7 +35,7 @@ export default defineVisualTest({
 
     // 2. Dynamically swap mock data to Empty State during the test
     ctx.log('2. Updating mock to empty list');
-    await ctx.setMockIpc('GET_USERS', []);
+    await ctx.setMockRoute('**/api/users', []);
     
     // Re-navigate or trigger refresh
     await ctx.navigate('/users');
@@ -46,15 +46,16 @@ export default defineVisualTest({
     const hasEmptyMessage = await ctx.isVisible('text="No users found"');
     ctx.log(`Empty state text visible: ${hasEmptyMessage}`);
 
-    // 3. Dynamically simulate API Error
-    ctx.log('3. Simulating backend failure');
-    await ctx.setMockIpc('GET_USERS', 'Internal Server Error (500)', { type: 'ERROR' });
+    // 3. Dynamically simulate HTTP 500 Backend Failure
+    ctx.log('3. Simulating backend 500 failure');
+    await ctx.setMockRoute('**/api/users', { error: 'Internal Server Error' }, { status: 500 });
     await ctx.navigate('/users');
     await ctx.wait(300);
     await ctx.capture('03_users_error_state');
   }
 });
 ```
+        
 
 ## Running the Scenario
 ```bash