@_deep4wee/agent-lens 1.1.0 → 1.2.0

package/skills/agent-lens/SKILL.md

@@ -1,36 +1,72 @@
 ---
 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.
+description: Visual UI self-verification platform for AI agents. Take responsive multi-viewport snapshots of live URLs, drive interactive real-time browser sessions, inspect semantic accessibility trees, detect visual regressions with pixel diffing, or run scripted interaction scenarios in Chromium or native desktop WebView2.
 ---
 
-# 👁️ AgentLens
+# 👁️ AgentLens (Microkernel Agentic UI Platform)
 
-**AgentLens** is a visual self-verification tool designed specifically for autonomous AI coding agents.
+**AgentLens** gives AI coding agents **eyes** and **hands** to test and verify user interfaces before reporting back to humans.
 
-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.
+Instead of writing frontend code and blindly guessing if it looks right or works properly, AgentLens allows you to:
+1. Capture multi-viewport screenshots of your running app with one-shot `snap`.
+2. Inspect entire scrollable pages with `--full`.
+3. Drive interactive step-by-step browser sessions via persistent `live` commands (`click`, `type`, `snap`) without cold-start browser restarts.
+4. "Read" the exact semantic hierarchy and interactive states using the `a11y-tree` plugin (essential for text-only LLMs or accessibility audits).
+5. Detect pixel-level visual regressions using the `visual-diff` plugin.
+6. Intercept silent JavaScript runtime errors, unhandled promise rejections, and missing assets.
+7. Author your own 1-file plugins on-the-fly in `.agent-lens/plugins/` to solve novel project constraints.
 
 ---
 
-## ⚡ Two Modes of Agent Verification
+## ⚡ 3 Ways for an Agent to Interact
 
-### 1. Instant Verification (`snap`) — No test files needed!
-Ideal for 90% of tasks when you just modified a page, component, or layout:
+### 1. Instant One-Shot Verification (`snap`)
+Ideal for 90% of tasks when you just modified a page, component, or responsive layout:
 ```bash
-# Verify a live dev server across desktop & mobile viewports:
+# Verify live dev server across desktop & mobile viewports:
 npx agent-lens snap --url=http://localhost:5173
 
+# Capture entire scrollable page height:
+npx agent-lens snap --url=http://localhost:5173 --full
+
 # 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"
+
+# Extract semantic accessibility tree during snap:
+npx agent-lens snap --url=http://localhost:5173 --plugin=a11y-tree
 ```
 
-### 2. Scripted Scenarios (`npx agent-lens --scenario=<name>`)
-For multi-step flows, form submissions, state mocks, and complex assertions:
+---
+
+### 2. Interactive Live Controller Loop (`live`)
+Ideal for multi-step flows, debugging interactions, or iterative visual tuning without restarting the browser on each action:
+
+```bash
+# Step 1: Start background session (launches browser on CDP port 9223)
+npx agent-lens live start --url=http://localhost:5173
+
+# Step 2: Click via Vision physical coordinates or CSS selector
+npx agent-lens live click 450 180
+npx agent-lens live click "button.open-modal"
+
+# Step 3: Fill inputs
+npx agent-lens live type "input[name='email']" "agent@example.com"
+
+# Step 4: Capture current screen or full scrollable page
+npx agent-lens live snap step_02 --full
+
+# Step 5: Stop session when done
+npx agent-lens live stop
+```
+> 💡 *Every live action automatically updates `artifacts/live/current.png` in ~50ms, allowing instant visual feedback.*
+
+---
+
+### 3. Scripted Scenarios (`scenarios/*.scenario.ts`)
+For reproducible test suites, state mocking, animations, and regression diffing:
 ```bash
 npx agent-lens --scenario=checkout-flow --url=http://localhost:5173
 ```
@@ -39,24 +75,58 @@ 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 synchronizes the most recent run to:
-     `artifacts/latest/report.md`
-   - **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.
-        
+```mermaid
+flowchart TD
+    Edit["1. Edit Code (UI / CSS / Logic)"] --> Choose["2. Choose Verification Mode"]
+    Choose -->|Quick check| Snap["npx agent-lens snap --url=..."]
+    Choose -->|Step-by-step flow| Live["npx agent-lens live start -> click -> type -> stop"]
+    Choose -->|Regression / Scenarios| Scenario["npx agent-lens --scenario=..."]
+
+    Snap --> Inspect["3. Inspect Output"]
+    Live --> Inspect
+    Scenario --> Inspect
+
+    Inspect --> CheckLog["Check artifacts/latest/report.md for console errors"]
+    CheckLog --> VisionCheck{"Do you have Vision tools?"}
+    VisionCheck -->|Yes| ViewImg["View artifacts/latest/*.png or artifacts/live/current.png"]
+    VisionCheck -->|No| ReadA11y["Read artifacts/latest/a11y-tree.md (Roles, Names, Focus)"]
+
+    ViewImg --> Iterate["4. Fix errors or regressions & iterate"]
+    ReadA11y --> Iterate
+```
+
+1. **Check Logs First**: Always inspect `artifacts/latest/report.md`. If there are any **Console Errors**, fix the JavaScript / React exceptions first.
+2. **If You Have Vision (`view_image`)**: Inspect the latest generated PNGs:
+   - `artifacts/latest/01_quick_snap_desktop.png`
+   - `artifacts/latest/02_quick_snap_mobile.png`
+   - Look for clipped text, unexpected wrapping, broken flex/grid columns, or overlay bugs.
+3. **If You Are Text-Only**: Run with `--plugin=a11y-tree` and inspect:
+   - `artifacts/latest/a11y-tree.md`
+   - Verify that buttons, form inputs, headings, and dialogs are rendered with expected text and states.
+
+---
+
+## 🔌 Built-In Plugins & Extensibility
+
+AgentLens is built around a lightweight **Microkernel architecture**. The core engine is decoupled from drivers, mocks, and tooling plugins:
+
+| Plugin | Primary Purpose | How to Activate |
+| :--- | :--- | :--- |
+| `live-controller` | Background CDP session for coordinate clicks, drag-and-drop, interactive CLI loop | CLI `live` command or `--plugin=live-controller` |
+| `a11y-tree` | Semantic accessibility tree extraction into clean Markdown | `--plugin=a11y-tree` or in scenario `plugins: ['a11y-tree']` |
+| `visual-diff` | Pixel-by-pixel regression diffing with `pixelmatch` | `--plugin=visual-diff` or in scenario `plugins: ['visual-diff']` |
+| `desktop-webview2` | Windows native `.exe` testing via CDP remote port | Auto-activated on `--mode=desktop` or `--exe=path/to/app.exe` |
+| `mock-ipc` | Desktop IPC bridge mocking (`window.__mockIpc`) | Auto-activated if `scenarios/mocks.ts` exists |
+
+### 🛠️ Writing Custom Plugins On-The-Fly
+If you encounter a project constraint that cannot be handled by default options (e.g. custom authentication headers, pre-populating `localStorage`, WebSocket mocking, or database seeding), **write a 1-file plugin**:
+
+1. Create `.agent-lens/plugins/<name>.ts`.
+2. Export `definePlugin({ name: '<name>', ... })` as `default`.
+3. Use lifecycle hooks (`onContextCreated`, `extendContext`, `onAfterRun`, `teardown`).
+4. Execute via `npx agent-lens snap --plugin=<name>`.
+
+*Full instructions & examples:* [Plugin Development Reference](references/plugin-development.md) and [docs/plugins.md](file:///E:/github/agent-lens/docs/plugins.md).
 
 ---
 
@@ -77,7 +147,7 @@ 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')`.
+When your app mounts, root components (Navbar, AuthContext, Layout) often query 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!
 
@@ -104,6 +174,7 @@ npx agent-lens [command] [options]
 
 ### Commands:
 - `snap`: Instant one-shot snapshot & console check of a URL or static build.
+- `live`: Interactive session (`start`, `click`, `type`, `snap`, `stop`).
 - `init`: Generate starter template in `scenarios/template.scenario.ts` and `scenarios/mocks.ts`.
 - *(default)*: Runs matching scenarios from `scenarios/`.
 
@@ -114,9 +185,11 @@ npx agent-lens [command] [options]
 | `--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` |
+| `--full` | Capture full scrollable page height instead of viewport | `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` |
+| `--plugin=<list>` | Comma-separated plugins to load (e.g. `--plugin=a11y-tree,visual-diff`) | *(none)* |
 | `--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` |
@@ -134,16 +207,16 @@ npx agent-lens [command] [options]
 
 ```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
+  route: '/dashboard',
   viewports: [VIEWPORT_PRESETS.DEFAULT, VIEWPORT_PRESETS.MIN_SUPPORTED],
 
+  // Load plugins for this scenario:
+  plugins: ['a11y-tree', 'visual-diff'],
+
   // HTTP REST / GraphQL Network Mocks (Vite / Next.js / Web SPA)
   mockRoutes: [
     { url: '**/api/v1/user', body: { id: 1, name: 'Agent', role: 'admin' } },
@@ -165,12 +238,11 @@ export default defineVisualTest({
   teardown: async () => {}
 });
 ```
-        
 
 ### Available `ctx` Methods:
 
 #### 📸 Capturing
-- `await ctx.capture('01_name', options?)`: Capture full page or element snapshot.
+- `await ctx.capture('01_name', options?)`: Capture snapshot (supports `{ fullPage: true, selector: '...' }`).
 - `await ctx.captureBurst('02_anim', { durationMs: 300, intervalMs: 50, selector? })`: Capture animation frames.
 
 #### 📐 Viewport Control
@@ -200,19 +272,34 @@ export default defineVisualTest({
 - `ctx.getConsoleErrors()`: Array of caught errors with stack traces.
 - `ctx.getConsoleWarnings()`: Array of caught warnings.
 
-#### 🌐 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.
+#### 🌐 Network Route & Mock IPC
+- `await ctx.setMockRoute('**/api/users', payload, options?)`: Dynamically intercepts HTTP/REST API endpoints.
 - `await ctx.setMockIpc('ACTION_NAME', payload, { type: 'SUCCESS' | 'ERROR', delayMs?: number })`: Dynamically alters mock data for hybrid IPC bridges.
-        
+
+#### 🔌 Plugin Extensions (When Plugins Are Loaded)
+- **live-controller**:
+  - `await ctx.clickCoords(x, y, options?)`
+  - `await ctx.dragAndDrop(fromX, fromY, toX, toY, steps?)`
+  - `await ctx.scrollPercent(percent)`
+  - `await ctx.snapLive(options?)`
+- **a11y-tree**:
+  - `await ctx.dumpAccessibilityTree({ selector?: string, compact?: boolean })`
+- **visual-diff**:
+  - `await ctx.compareSnapshots(currentPath, baselinePath, options?)`
+  - `await ctx.captureAndCompare(name, baselinePath, captureOptions?, diffOptions?)`
 
 ---
 
-## 📚 Detailed Examples & Use Cases
+## 📚 Complete Walkthroughs & Examples
 
-Check the dedicated example guides in `examples/` for complete walk-throughs:
+Check the dedicated example guides in `examples/`:
 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.
+7. [Live Controller Interactive Loop](examples/07-live-controller-interactive-loop.md) — Low-latency real-time control via CLI commands.
+8. [Semantic Accessibility Tree Inspection](examples/08-accessibility-semantic-inspection.md) — Extracting UI hierarchies for text LLMs.
+9. [Visual Regression & Pixel Diffing](examples/09-visual-regression-and-pixel-diffing.md) — Automated pixelmatch difference masks.
+10. [Authoring Custom Agent Plugins](examples/10-authoring-custom-agent-plugins.md) — Writing 1-file plugins on-the-fly.

package/skills/agent-lens/examples/07-live-controller-interactive-loop.md

@@ -0,0 +1,108 @@
+# 🚀 Example 07: Live Controller Interactive Loop
+
+The **Live Controller** plugin turns AgentLens into an interactive command-line browser remote. Instead of restarting the browser on every single change, an agent can keep a background session alive, execute actions step-by-step with sub-50ms latency, and inspect the state in real-time.
+
+---
+
+## 🎯 Use Case
+
+You are debugging a multi-step user flow (e.g. multi-page signup, complex drawer, or modal wizard) and want to:
+1. Open the page once.
+2. Click specific buttons or coordinates.
+3. Fill in form values.
+4. Capture full-page screenshots (`--full`).
+5. Close the session when done.
+
+---
+
+## 🛠️ Step-by-Step CLI Walkthrough
+
+### 1. Start the Live Background Session
+```bash
+npx agent-lens live start --url=http://localhost:5173
+```
+*Output:*
+```text
+🚀 [Live] Starting background browser for http://localhost:5173 on CDP port 9223...
+📸 [LiveController] Snapshot saved: artifacts/live/current.png
+✅ [Live] Session active! You can now send live commands:
+```
+
+The browser is now running in the background. The initial screen is saved to `artifacts/live/current.png`.
+
+---
+
+### 2. Click Elements (Coordinates or CSS Selectors)
+
+#### Vision-Based Coordinate Click (for Multimodal LLMs)
+If your vision model identified a button at physical coordinates `(450, 210)`:
+```bash
+npx agent-lens live click 450 210
+```
+
+#### Semantic Selector Click
+```bash
+npx agent-lens live click "button[type='submit']"
+```
+
+AgentLens immediately executes the click and updates `artifacts/live/current.png`.
+
+---
+
+### 3. Type into Form Fields
+```bash
+npx agent-lens live type "input[name='search']" "AgentLens Microkernel"
+```
+
+---
+
+### 4. Capture Full Scrollable Page (`--full`)
+To capture the entire scrollable height of the page (beyond the 1200x800 viewport):
+```bash
+npx agent-lens live snap dashboard_full --full
+```
+*Output:*
+```text
+📸 [LiveController] Snapshot saved: artifacts/live/dashboard_full.png (Full Page)
+```
+
+---
+
+### 5. Terminate the Session
+When your test flow is complete, stop the live browser:
+```bash
+npx agent-lens live stop
+```
+*Output:*
+```text
+🛑 [Live] Session stopped and browser closed.
+```
+
+---
+
+## 💡 Using `live-controller` Inside Scenarios
+
+You can also use Live Controller methods directly inside scripted scenarios:
+
+```typescript
+import { defineVisualTest } from 'agent-lens';
+import liveControllerPlugin from '@_deep4wee/agent-lens/plugins/live-controller';
+
+export default defineVisualTest({
+  id: 'canvas-drawing-test',
+  plugins: [liveControllerPlugin],
+  run: async (ctx) => {
+    // 1. Precise coordinate click
+    await (ctx as any).clickCoords(350, 420);
+
+    // 2. Drag-and-drop simulation
+    await (ctx as any).dragAndDrop(100, 100, 300, 300, 15);
+
+    // 3. Smooth percentage scroll
+    await (ctx as any).scrollPercent(50);
+
+    // 4. Live snapshot with full page capture
+    await (ctx as any).snapLive({ name: 'canvas_final', fullPage: true });
+  }
+});
+```

package/skills/agent-lens/examples/08-accessibility-semantic-inspection.md

@@ -0,0 +1,80 @@
+# ♿ Example 08: Semantic Accessibility Tree Inspection
+
+Not every AI agent operates with multimodal vision tools enabled, and even vision models can miss subtle details like whether an element is marked `disabled`, `required`, or properly focused.
+
+The **`a11y-tree`** plugin extracts the live semantic accessibility tree of the page and outputs a clean, indented Markdown outline.
+
+---
+
+## 🎯 Use Case
+
+1. **Text-Only LLMs**: The agent lacks vision/image tools but needs to know what is rendered on screen.
+2. **Form Validation**: Checking whether the submit button is `[disabled]` or input is `[required]`.
+3. **Hierarchy Verification**: Verifying heading levels (`h1`, `h2`), navigation landmarks, and dialog focus.
+
+---
+
+## 🛠️ Step-by-Step Walkthrough
+
+### 1. Enabling `a11y-tree` via CLI
+You can enable the plugin directly on quick snap checks:
+```bash
+npx agent-lens snap --url=http://localhost:5173 --plugin=a11y-tree
+```
+
+---
+
+### 2. Inspecting the Generated Tree
+AgentLens outputs:
+1. `artifacts/latest/a11y-tree.md`
+2. An embedded section in `artifacts/latest/report.md`
+
+#### Example Output (`a11y-tree.md`):
+```markdown
+- [banner]
+  - [heading] "AgentLens Dashboard" (level 1)
+  - [navigation]
+    - [link] "Overview"
+    - [link] "Settings"
+- [main]
+  - [heading] "Active Sessions" (level 2)
+  - [textbox] "Search scenarios..." (focused)
+  - [button] "Run All"
+  - [button] "Cancel" (disabled)
+  - [list]
+    - [listitem] "checkout-flow.scenario.ts"
+    - [listitem] "auth-smoke.scenario.ts"
+```
+
+---
+
+### 3. Using `a11y-tree` Inside a Scenario
+
+```typescript
+import { defineVisualTest } from 'agent-lens';
+import a11yTreePlugin from '@_deep4wee/agent-lens/plugins/a11y-tree';
+
+export default defineVisualTest({
+  id: 'a11y-inspection-flow',
+  title: 'Accessibility Hierarchy Check',
+  plugins: [a11yTreePlugin],
+  run: async (ctx) => {
+    // Navigate and interact
+    await ctx.click('button.open-dialog');
+    await ctx.wait(300);
+
+    // Capture semantic tree of entire page or isolated modal
+    const tree = await (ctx as any).dumpAccessibilityTree({
+      selector: '.dialog-content',
+      compact: true
+    });
+
+    // Custom assertion in scenario
+    if (!tree.includes('[button] "Confirm"')) {
+      throw new Error('Expected Confirm button in accessibility tree!');
+    }
+
+    ctx.log('Accessibility tree verified successfully!');
+  }
+});
+```

package/skills/agent-lens/examples/09-visual-regression-and-pixel-diffing.md

@@ -0,0 +1,66 @@
+# 🎨 Example 09: Visual Regression & Pixel Diffing
+
+The **`visual-diff`** plugin adds automated, pixel-by-pixel regression testing using `pixelmatch` and `pngjs`. It detects unintended visual shifts, color alterations, font changes, and layout regressions down to individual pixels.
+
+---
+
+## 🎯 Use Case
+
+You are refactoring CSS styles or upgrading a component library (e.g. Tailwind, Shadcn, MUI) and need to guarantee that the UI did not unintentionally change from a known baseline.
+
+---
+
+## 🛠️ Step-by-Step Walkthrough
+
+### 1. Establish Baseline Screenshots
+Run your scenario once to generate reference screenshots, and commit them to a baseline directory (e.g. `fixtures/baselines/`):
+```bash
+mkdir -p fixtures/baselines
+cp artifacts/latest/01_homepage_default.png fixtures/baselines/homepage_baseline.png
+```
+
+---
+
+### 2. Write Scenario with Visual Diffing
+
+```typescript
+import path from 'path';
+import { defineVisualTest } from 'agent-lens';
+import visualDiffPlugin from '@_deep4wee/agent-lens/plugins/visual-diff';
+
+export default defineVisualTest({
+  id: 'homepage-regression',
+  title: 'Homepage Visual Regression Check',
+  plugins: [visualDiffPlugin],
+  run: async (ctx) => {
+    const baselinePath = path.resolve(process.cwd(), 'fixtures/baselines/homepage_baseline.png');
+
+    // Capture current view and compare against baseline in a single step:
+    const diff = await (ctx as any).captureAndCompare(
+      '01_homepage_check',
+      baselinePath,
+      { fullPage: false },
+      { threshold: 0.1 } // Sensitivity threshold (0 to 1, default 0.1)
+    );
+
+    ctx.log(`Diff result: ${diff.diffPixels} pixels (${diff.diffPercent}%)`);
+
+    // Strict assertion: Fail if more than 0.5% of pixels changed
+    if (diff.diffPercent > 0.5) {
+      throw new Error(`Visual regression detected! Diff is ${diff.diffPercent}% (${diff.diffPixels} px).`);
+    }
+  }
+});
+```
+
+---
+
+### 3. Inspecting the Report
+
+When the scenario runs, `visual-diff` generates:
+- `artifacts/<timestamp>/01_homepage_check_diff.png` (visual difference mask in bright red)
+- A comparison table in `artifacts/latest/report.md`:
+
+| Test Step | Baseline | Current | Diff Image | Changed Pixels | Status |
+| :--- | :--- | :--- | :--- | :-: | :-: |
+| **01_homepage_check** | [Baseline](fixtures/baselines/homepage_baseline.png) | [Current](01_homepage_check.png) | [Diff](01_homepage_check_diff.png) | 48 px | 🟡 Minor Shift (0.04%) |

package/skills/agent-lens/examples/10-authoring-custom-agent-plugins.md

@@ -0,0 +1,85 @@
+# 🛠️ Example 10: Authoring Custom Agent Plugins
+
+When testing real-world applications, AI coding agents frequently hit barriers that standard testing tools cannot handle out of the box — such as bypassing mock single-sign-on (SSO), pre-populating browser IndexedDB databases, or simulating unstable network throttles.
+
+This example shows how an agent can solve this autonomously by creating a 1-file plugin.
+
+---
+
+## 🎯 Use Case
+
+Your application checks for an active tenant ID in `window.__TENANT_CONFIG__` and crashes if it is missing:
+```javascript
+// App code (main.tsx)
+const tenant = window.__TENANT_CONFIG__.activeId; // Crashes if undefined!
+```
+
+Instead of modifying production code or struggling with complex setup scripts, the agent authors a custom plugin to inject this state before React hydrates.
+
+---
+
+## 🛠️ Step-by-Step Walkthrough
+
+### 1. Agent Creates the 1-File Plugin
+Create `.agent-lens/plugins/tenant-seeder.ts`:
+
+```typescript
+import { definePlugin } from 'agent-lens';
+
+export default definePlugin({
+  name: 'tenant-seeder',
+  version: '1.0.0',
+
+  onContextCreated: async (context) => {
+    // Inject global tenant configuration before page scripts execute
+    await context.addInitScript(() => {
+      (window as any).__TENANT_CONFIG__ = {
+        activeId: 'tenant-enterprise-99',
+        name: 'Acme Global Corp',
+        tier: 'ENTERPRISE',
+        features: {
+          analyticsDashboard: true,
+          auditLogs: true
+        }
+      };
+    });
+  },
+
+  onAfterRun: (reportData) => {
+    if (!reportData.customSections) return;
+    reportData.customSections.push({
+      title: '🏢 Tenant Seeder Status',
+      content: 'Successfully injected enterprise tenant mock: `tenant-enterprise-99`.'
+    });
+  }
+});
+```
+
+---
+
+### 2. Run with Quick Snap or Scenarios
+
+#### Quick Snap
+```bash
+npx agent-lens snap --url=http://localhost:5173 --plugin=tenant-seeder
+```
+
+#### Scripted Scenario
+```typescript
+import { defineVisualTest } from 'agent-lens';
+
+export default defineVisualTest({
+  id: 'enterprise-dashboard',
+  plugins: ['tenant-seeder'], // Auto-resolved from .agent-lens/plugins/tenant-seeder.ts!
+  run: async (ctx) => {
+    await ctx.capture('01_enterprise_dashboard');
+    const headerText = await ctx.readText('.tenant-banner');
+    ctx.log(`Banner verified: ${headerText}`);
+  }
+});
+```
+
+---
+
+### 3. Verification & Cleanup
+The agent reviews `artifacts/latest/report.md`. If the custom plugin was only needed for temporary testing, the agent can delete `.agent-lens/plugins/tenant-seeder.ts` or keep it committed in the repository for future test runs.