@_deep4wee/agent-lens 1.0.1

package/skills/agent-lens/examples/02-dev-server-live-testing.md

@@ -0,0 +1,62 @@
+# Example 2: Live Dev Server Workflow
+
+Test complex user flows and route transitions on an active Vite, Next.js, Webpack, or Full-Stack dev server.
+
+## Use Cases
+- Testing forms, multi-step wizards, and client-side navigation.
+- Verifying client-server interactions against real endpoints.
+- Running scripted tests against Hot Module Replacement (HMR) during agent development.
+
+## 1. Writing the Scenario (`scenarios/user-flow.scenario.ts`)
+
+```typescript
+import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+
+export default defineVisualTest({
+  id: 'user-registration-flow',
+  title: 'User Registration & Onboarding Flow',
+  route: '/register',
+  viewports: [VIEWPORT_PRESETS.DEFAULT, VIEWPORT_PRESETS.WIDE],
+  run: async (ctx) => {
+    // 1. Initial State
+    ctx.log('Checking registration form initial render');
+    await ctx.capture('01_register_empty');
+
+    // 2. Form Interaction
+    ctx.log('Filling registration inputs');
+    await ctx.type('input[name="email"]', 'agent@example.com');
+    await ctx.type('input[name="password"]', 'SecureP@ssw0rd!');
+    await ctx.click('input[type="checkbox"]');
+    await ctx.capture('02_register_filled');
+
+    // 3. Form Submission
+    await ctx.click('button[type="submit"]');
+    await ctx.waitForSelector('.welcome-banner', 5000);
+    await ctx.capture('03_onboarding_welcome');
+
+    // 4. Assertions
+    const welcomeText = await ctx.readText('.welcome-banner h1');
+    ctx.log(`Welcome banner title: "${welcomeText}"`);
+    
+    const errors = ctx.getConsoleErrors();
+    if (errors.length > 0) {
+      ctx.log(`⚠️ Warning: Detected ${errors.length} console errors!`);
+    }
+  }
+});
+```
+
+## 2. Running Against an Already Running Server
+```bash
+npx agent-lens --scenario=user-registration-flow --url=http://localhost:5173
+```
+
+## 3. Running with Managed Process Lifecycle
+AgentLens launches `npm run dev`, waits for `http://localhost:5173` to be healthy, executes the scenario, and reliably shuts down the dev server process tree:
+```bash
+npx agent-lens \
+  --scenario=user-registration-flow \
+  --start="npm run dev" \
+  --url=http://localhost:5173 \
+  --folder=visual-reports
+```

package/skills/agent-lens/examples/03-component-isolation-and-animations.md

@@ -0,0 +1,53 @@
+# Example 3: Component Isolation & Animation Bursts
+
+Inspect single UI components without background clutter and capture frame-by-frame sequences of CSS/JS animations.
+
+## Use Cases
+- Verifying UI cards, tooltips, dropdown menus, and modal dialogs.
+- Inspecting micro-interactions, fade-ins, and spring animations.
+- Ensuring popups and dropdowns do not clip outside viewport bounds.
+
+## Writing the Scenario (`scenarios/components.scenario.ts`)
+
+```typescript
+import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+
+export default defineVisualTest({
+  id: 'component-inspection',
+  title: 'Component Isolation & Micro-Interactions',
+  route: '/components',
+  run: async (ctx) => {
+    // 1. Dynamic Auto-Resize to Fit a Specific Component
+    ctx.log('Focusing strictly on the navigation navbar');
+    await ctx.resizeToFit('header.navbar', 10);
+    await ctx.capture('01_navbar_isolated');
+
+    // 2. Return to standard desktop dimensions
+    await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
+
+    // 3. Hover Micro-Interaction with Burst Animation
+    ctx.log('Triggering dropdown menu hover animation');
+    await ctx.hover('.dropdown-trigger');
+    
+    // Captures multiple consecutive frames over a 300ms duration at 50ms intervals
+    await ctx.captureBurst('02_dropdown_opening_animation', {
+      durationMs: 300,
+      intervalMs: 50,
+      selector: '.dropdown-menu'
+    });
+
+    // 4. Final Stabilized State
+    await ctx.capture('03_dropdown_open_final', { selector: '.dropdown-menu' });
+
+    // 5. Scroll Interaction
+    ctx.log('Scrolling table down by 400px');
+    await ctx.scroll('.data-table-container', 400);
+    await ctx.capture('04_data_table_scrolled');
+  }
+});
+```
+
+## Running the Scenario
+```bash
+npx agent-lens --scenario=component-inspection --url=http://localhost:5173
+```

package/skills/agent-lens/examples/04-desktop-native-testing.md

@@ -0,0 +1,68 @@
+# Example 4: Native Desktop Application Testing (.exe / WebView2 / Electron)
+
+Test real compiled native desktop binaries in production conditions, interacting with the real backend and rendering engine over Chrome DevTools Protocol (CDP).
+
+## Use Cases
+- Verifying desktop applications (Photino .NET, Electron, Tauri, WPF WebView2).
+- Testing real system interactions, filesystem writes, and native process IPC.
+- Verifying the app builds and boots up cleanly without missing DLLs or native crashes.
+
+## 1. Writing the Scenario (`scenarios/desktop-app.scenario.ts`)
+
+```typescript
+import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+import fs from 'fs';
+import path from 'path';
+
+export default defineVisualTest({
+  id: 'desktop-smoke-test',
+  title: 'Native Desktop Application Production Verification',
+  run: async (ctx) => {
+    ctx.log('1. Waiting for native backend and UI initialization');
+    await ctx.wait(2500);
+
+    // Initial desktop screenshot
+    await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
+    await ctx.capture('01_desktop_main_window');
+
+    // Test minimal window size constraints
+    await ctx.setPreset(VIEWPORT_PRESETS.MIN_SUPPORTED);
+    await ctx.capture('02_desktop_min_window');
+    await ctx.setPreset(VIEWPORT_PRESETS.DEFAULT);
+
+    // Click native action button that triggers backend work
+    ctx.log('2. Triggering native save action');
+    await ctx.click('button#save-preferences');
+    await ctx.wait(500);
+    await ctx.capture('03_saved_state');
+
+    // Verify file written to disk by real native backend
+    const savedConfig = path.resolve(process.cwd(), 'config', 'user-prefs.json');
+    if (fs.existsSync(savedConfig)) {
+      ctx.log('✅ Real backend successfully created config file on disk!');
+    } else {
+      ctx.log('⚠️ Config file was not written to disk.');
+    }
+  }
+});
+```
+
+## 2. Running with Automated Build and Binary Launch
+
+```bash
+npx agent-lens \
+  --scenario=desktop-smoke-test \
+  --mode=desktop \
+  --build="dotnet build -c Release" \
+  --exe="bin/Release/net8.0-windows/MyApp.exe" \
+  --port=9222 \
+  --folder=visual-reports
+```
+
+### How AgentLens Handles Native Apps:
+1. Runs the specified build command (`--build`).
+2. Spawns `MyApp.exe` with remote debugging flags.
+3. If the executable crashes on launch (e.g. missing runtime, segfault), AgentLens immediately catches the exit code and stderr, printing the exact crash log.
+4. Once the CDP port is listening, Playwright attaches directly to the native window.
+5. Runs the test and takes snapshots.
+6. Gracefully terminates the process tree on completion.

package/skills/agent-lens/examples/05-clean-teardown-and-sandboxing.md

@@ -0,0 +1,68 @@
+# Example 5: Clean Teardown & Auto-Cleanup Lifecycle
+
+Prevent test pollution, corrupted databases, and "buggy" leftover artifacts when running end-to-end tests.
+
+## The Problem
+When testing actions like "Create Project", "Download Asset", or "Save Profile", test artifacts are created on the real filesystem. If the test crashes halfway, corrupted files remain, causing future test runs to fail mysteriously.
+
+## The Solution
+AgentLens provides two lines of defense:
+1. **`teardown()` hook**: Guaranteed to execute in a `finally` block, even if the scenario throws an uncaught error.
+2. **`--clean=<paths>` CLI flag**: Automatically deletes specified folders or files after the test completes.
+
+## Writing the Scenario (`scenarios/isolated-data.scenario.ts`)
+
+```typescript
+import { defineVisualTest } from 'agent-lens';
+import fs from 'fs';
+import path from 'path';
+
+const TEST_SANDBOX_DIR = path.resolve(process.cwd(), '.tmp_test_sandbox');
+
+export default defineVisualTest({
+  id: 'isolated-creation-flow',
+  title: 'Data Creation with Guaranteed Cleanup',
+  route: '/projects',
+
+  // 1. Setup: Prepare a clean workspace before testing begins
+  setup: async () => {
+    if (fs.existsSync(TEST_SANDBOX_DIR)) {
+      fs.rmSync(TEST_SANDBOX_DIR, { recursive: true, force: true });
+    }
+    fs.mkdirSync(TEST_SANDBOX_DIR, { recursive: true });
+  },
+
+  // 2. Main Test Run
+  run: async (ctx) => {
+    ctx.log('Creating a new test project');
+    await ctx.click('button#new-project');
+    await ctx.type('input#project-name', 'Temporary_Test_Project');
+    await ctx.click('button#confirm');
+
+    await ctx.wait(800);
+    await ctx.capture('01_project_created');
+
+    // Perform verification assertions
+    const count = await ctx.getElementCount('.project-item');
+    ctx.log(`Current project count: ${count}`);
+  },
+
+  // 3. Teardown: ALWAYS executes, even if run() fails!
+  teardown: async () => {
+    console.log('[Teardown] Purging sandbox test directory');
+    if (fs.existsSync(TEST_SANDBOX_DIR)) {
+      fs.rmSync(TEST_SANDBOX_DIR, { recursive: true, force: true });
+    }
+  }
+});
+```
+
+## Running with Auto-Cleanup Flags
+
+You can also pass additional paths to clean up directly from the CLI:
+```bash
+npx agent-lens \
+  --scenario=isolated-creation-flow \
+  --clean="./cache,./tmp_data,.tmp_test_sandbox"
+```
+AgentLens ensures all specified targets are purged on completion.

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

@@ -0,0 +1,62 @@
+# Example 6: State Testing with 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.
+
+## Writing the Scenario (`scenarios/states.scenario.ts`)
+
+```typescript
+import { defineVisualTest, VIEWPORT_PRESETS } from 'agent-lens';
+
+export default defineVisualTest({
+  id: 'ui-state-verification',
+  title: 'Empty State vs Populated State Verification',
+  route: '/users',
+  
+  // 1. Initial State: Populated list
+  mockIpc: [
+    {
+      action: 'GET_USERS',
+      data: [
+        { id: 1, name: 'Alice Cooper', role: 'Administrator' },
+        { id: 2, name: 'Bob Marley', role: 'Editor' }
+      ]
+    }
+  ],
+
+  run: async (ctx) => {
+    // Check populated table
+    ctx.log('1. Checking populated users table');
+    await ctx.capture('01_users_populated');
+
+    // 2. Dynamically swap mock data to Empty State during the test
+    ctx.log('2. Updating mock to empty list');
+    await ctx.setMockIpc('GET_USERS', []);
+    
+    // Re-navigate or trigger refresh
+    await ctx.navigate('/users');
+    await ctx.wait(300);
+    await ctx.capture('02_users_empty_state');
+
+    // Verify empty state message in DOM
+    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' });
+    await ctx.navigate('/users');
+    await ctx.wait(300);
+    await ctx.capture('03_users_error_state');
+  }
+});
+```
+
+## Running the Scenario
+```bash
+npx agent-lens --scenario=ui-state-verification --mode=preview
+```