# Plan: Playwright Debugging Features

## Phase 1: Core Debugging (Console & Errors)

### Description
Implement fundamental debugging capabilities: console message capture and uncaught exception handling. These form the foundation for debugging client-side issues.

### Steps

#### Step 1.1: Add Console Command
- **Objective**: Capture and retrieve console messages from browser
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Status**: COMPLETE
- **Implementation**:
  - Add `ConsoleCommand` type with `level` filter and `clear` option
  - Store messages via `page.on('console')` listener
  - Return messages with level, text, timestamp, location

#### Step 1.2: Add Page Errors Command
- **Objective**: Capture uncaught exceptions and unhandled promise rejections
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: Step 1.1
- **Implementation**:
  - Add `ErrorsCommand` type with `clear` option
  - Listen to `page.on('pageerror')` for uncaught exceptions
  - Store error message, stack trace, timestamp
  - Add `browser://errors` MCP resource

## Phase 2: Network Monitoring

### Description
Implement network request/response capture for debugging API calls, identifying failed requests, and inspecting payloads.

### Steps

#### Step 2.1: Add Network Logging
- **Objective**: Capture all network requests and responses
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `NetworkCommand` type with `filter` and `clear` options
  - Listen to `page.on('request')` and `page.on('response')`
  - Store: url, method, status, resourceType, timing, headers
  - Add optional body capture for XHR/fetch (with size limit)
  - Add `browser://network` MCP resource

#### Step 2.2: Add Failed Requests Filter
- **Objective**: Quick access to failed/error requests
- **Files**: `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: Step 2.1
- **Implementation**:
  - Add `failed` filter option to NetworkCommand
  - Include requests with status >= 400 or network errors
  - Add `browser://network/failed` MCP resource

#### Step 2.3: Add Request Interception
- **Objective**: Block or mock specific requests
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: Step 2.1
- **Implementation**:
  - Add `InterceptCommand` with `action: 'block' | 'mock' | 'clear'`
  - Support URL patterns (glob or regex)
  - For mock: allow custom response body/status
  - Use `page.route()` for interception

## Phase 3: Performance & Metrics

### Description
Add performance timing and metrics collection for identifying bottlenecks and measuring page load characteristics.

### Steps

#### Step 3.1: Add Performance Metrics
- **Objective**: Return page performance timing data
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `MetricsCommand` type
  - Collect via `performance.timing` and `performance.getEntriesByType()`
  - Return: domContentLoaded, load, firstPaint, firstContentfulPaint
  - Include DOM stats: nodeCount, scriptCount, styleCount

#### Step 3.2: Add Resource Timing
- **Objective**: Get timing breakdown for individual resources
- **Files**: `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: Step 3.1
- **Implementation**:
  - Add `resources` option to MetricsCommand
  - Use `performance.getEntriesByType('resource')`
  - Return: name, duration, transferSize, initiatorType

## Phase 4: Accessibility

### Description
Implement accessibility tree inspection for debugging screen reader and a11y issues.

### Steps

#### Step 4.1: Add Accessibility Snapshot
- **Objective**: Dump accessibility tree for page or element
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `A11yCommand` with optional `selector` for subtree
  - Use `page.accessibility.snapshot()`
  - Return tree with role, name, value, description
  - Add `browser://a11y` MCP resource

## Phase 5: Dialog Handling

### Description
Implement automatic handling of browser dialogs (alert, confirm, prompt) to prevent blocking during automation.

### Steps

#### Step 5.1: Add Dialog Command
- **Objective**: Configure how dialogs are handled
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `DialogCommand` with `action: 'accept' | 'dismiss' | 'status'`
  - Option to set default behavior for future dialogs
  - Option to provide text response for prompts
  - Store dialog history (type, message, response)
  - Listen to `page.on('dialog')`

## Phase 6: Storage & Cookies

### Description
Add commands for inspecting and manipulating browser storage, complementing the existing session save/restore.

### Steps

#### Step 6.1: Add Cookies Command
- **Objective**: Get, set, and clear cookies
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `CookiesCommand` with `action: 'get' | 'set' | 'delete' | 'clear'`
  - Use `context.cookies()` and `context.addCookies()`
  - Support filtering by name/domain
  - Add `browser://cookies` MCP resource

#### Step 6.2: Add Storage Command
- **Objective**: Inspect/modify localStorage and sessionStorage
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `StorageCommand` with `type: 'local' | 'session'`
  - Actions: get, set, delete, clear
  - Implement via `page.evaluate()`
  - Add `browser://storage/local` and `browser://storage/session` resources

## Phase 7: Advanced Interactions

### Description
Add additional interaction commands for comprehensive testing scenarios.

### Steps

#### Step 7.1: Add Hover Command
- **Objective**: Trigger hover state on elements
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `HoverCommand` with `selector`
  - Use `page.hover(selector)`

#### Step 7.2: Add Select Command
- **Objective**: Select options in dropdown elements
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `SelectCommand` with `selector` and `value` (or values array)
  - Use `page.selectOption()`

#### Step 7.3: Add Keys Command
- **Objective**: Send keyboard shortcuts and special keys
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `KeysCommand` with `keys` string (e.g., "Control+a", "Escape")
  - Use `page.keyboard.press()`

#### Step 7.4: Add Upload Command
- **Objective**: Set files on file input elements
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `UploadCommand` with `selector` and `files` array
  - Use `page.setInputFiles()`

#### Step 7.5: Add Scroll Command
- **Objective**: Scroll page or element into view
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `ScrollCommand` with optional `selector`, `x`, `y`
  - If selector: use `element.scrollIntoView()`
  - Otherwise: use `window.scrollTo()`

## Phase 8: Viewport & Emulation

### Description
Add device emulation and viewport manipulation for responsive testing.

### Steps

#### Step 8.1: Add Viewport Command
- **Objective**: Resize browser viewport dynamically
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: None
- **Implementation**:
  - Add `ViewportCommand` with `width` and `height`
  - Use `page.setViewportSize()`

#### Step 8.2: Add Emulate Command
- **Objective**: Emulate specific devices
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
- **Dependencies**: Step 8.1
- **Implementation**:
  - Add `EmulateCommand` with `device` name
  - Use Playwright's device descriptors
  - Apply viewport, userAgent, deviceScaleFactor, touch support

## Phase 9: Documentation

### Description
Update all documentation with new commands and examples.

### Steps

#### Step 9.1: Update README
- **Objective**: Document all commands with examples
- **Files**: `README.md`
- **Dependencies**: Phases 1-8
- **Implementation**:
  - Add command reference grouped by category
  - Include curl/MCP examples
  - Document response formats

#### Step 9.2: Update CLAUDE.md
- **Objective**: Update developer documentation
- **Files**: `CLAUDE.md`
- **Dependencies**: Step 9.1
- **Implementation**:
  - Update architecture notes
  - Document new command types