---
sidebar_position: 1
---

# Frontend API Overview

The proxy injects `window.__devtool` into all HTML pages, providing ~50 primitive functions for DOM inspection, layout debugging, visual debugging, and accessibility auditing.

## Accessing the API

When browsing through the proxy, access functions directly in the browser console:

```javascript
window.__devtool.inspect('#my-element')
```

Or execute remotely via MCP:

```json
proxy {action: "exec", id: "app", code: "window.__devtool.inspect('#my-element')"}
```

## Design Principles

### 1. Primitives Over Monoliths

Small, focused functions (~20-30 lines each) that do one thing well:

```javascript
// Good: focused primitives
getPosition('#el')  // Just position
getBox('#el')       // Just box model
getComputed('#el', ['display'])  // Just specific styles

// Also available: composite functions when needed
inspect('#el')  // Combines 8+ primitives
```

### 2. Composability

Functions return rich data structures for chaining:

```javascript
// Get position, then check if visible
const pos = window.__devtool.getPosition('#tooltip')
const visible = window.__devtool.isInViewport('#tooltip')
```

### 3. Error Resilient

Return `{error: ...}` instead of throwing exceptions:

```javascript
window.__devtool.getPosition('.nonexistent')
→ {error: "Element not found", selector: ".nonexistent"}

// Never throws - safe to chain
```

### 4. ES5 Compatible

Works in all modern browsers without transpilation. No external dependencies.

## Function Categories

| Category | Count | Purpose |
|----------|-------|---------|
| [Element Inspection](/api/frontend/element-inspection) | 9 | Get element properties, styles, layout |
| [Tree Walking](/api/frontend/tree-walking) | 3 | Navigate DOM hierarchy |
| [Visual State](/api/frontend/visual-state) | 3 | Check visibility and overlap |
| [Layout Diagnostics](/api/frontend/layout-diagnostics) | 3 | Find layout issues |
| [Visual Overlays](/api/frontend/visual-overlays) | 3 | Highlight and debug visually |
| [Interactive](/api/frontend/interactive) | 4 | User interaction and waiting |
| [State Capture](/api/frontend/state-capture) | 4 | Capture DOM, styles, storage |
| [Accessibility](/api/frontend/accessibility) | 5 | A11y inspection and auditing |
| [Composite](/api/frontend/composite) | 3 | High-level analysis |
| [Layout Robustness](/api/frontend/layout-robustness) | 7 | Text fragility, responsive risks, performance |
| [Quality Auditing](/api/frontend/quality-auditing) | 10 | Frame rate, jank, Core Web Vitals, memory, `auditAll` (8 scored audits) |
| [Responsive Mode](/api/frontend/responsive-mode) | 5 | Interactive width-driving workbench with live shift detection |
| [CSS Evaluation](/api/frontend/css-evaluation) | 7 | Architecture, containment, Tailwind, consistency |
| [Security & Validation](/api/frontend/security-validation) | 12 | CSP, XSS, frameworks, forms, SRI |

## Quick Reference

### Most Used Functions

```javascript
// Comprehensive element analysis
window.__devtool.inspect('#element')

// Take a screenshot
window.__devtool.screenshot('name')

// Interactive element picker
window.__devtool.selectElement()

// Accessibility audit
window.__devtool.auditAccessibility()

// Find layout problems
window.__devtool.diagnoseLayout()

// Highlight an element
window.__devtool.highlight('#element', {color: 'red'})
```

### Element Information

```javascript
window.__devtool.getElementInfo('#el')    // Basic info
window.__devtool.getPosition('#el')       // Position/dimensions
window.__devtool.getBox('#el')            // Box model
window.__devtool.getComputed('#el', [...])  // Computed styles
window.__devtool.getLayout('#el')         // Layout properties
window.__devtool.getStacking('#el')       // Z-index context
```

### Visibility Checks

```javascript
window.__devtool.isVisible('#el')         // Is it visible?
window.__devtool.isInViewport('#el')      // Is it on screen?
window.__devtool.checkOverlap('#a', '#b') // Do elements overlap?
```

### Debugging

```javascript
window.__devtool.findOverflows()          // Find all overflows
window.__devtool.findStackingContexts()   // Find z-index contexts
window.__devtool.findOffscreen()          // Find hidden elements
```

### User Interaction

```javascript
window.__devtool.selectElement()          // Click to select
window.__devtool.ask('Question?', ['A', 'B'])  // Ask user
window.__devtool.waitForElement('.loading-done')  // Wait for element
```

### CSS Analysis

```javascript
window.__devtool.auditCSS()               // Full CSS audit with grade
window.__devtool.auditTailwind()          // Tailwind-specific analysis
window.__devtool.auditCSSArchitecture()   // Specificity and selectors
window.__devtool.auditCSSConsistency()    // Colors, fonts, spacing
window.__devtool.detectContentAreas()     // CMS vs app vs layout
```

### Quality & Performance

```javascript
window.__devtool.auditPageQuality()       // Comprehensive quality audit
window.__devtool.checkTextFragility()     // Text truncation issues
window.__devtool.checkResponsiveRisk()    // Responsive breakage
window.__devtool.capturePerformanceMetrics()  // CLS, resources, paint
window.__devtool.observeFrameRate()       // Real-time FPS monitoring
```

### Security & Validation

```javascript
window.__devtool.auditSecurity()          // Comprehensive security audit
window.__devtool.detectFramework()        // Detect React, Vue, Angular, etc.
window.__devtool.auditFormSecurity()      // CSRF, validation, sensitive fields
window.__devtool.checkXSSRisk(input)      // Check string for XSS patterns
window.__devtool.sanitizeHTML(dirty)      // Sanitize with DOMPurify
```

## Async Functions

Most functions are synchronous. These return Promises:

| Function | Why Async |
|----------|-----------|
| `selectElement()` | Waits for user click |
| `ask(question, options)` | Waits for user input |
| `waitForElement(selector, timeout)` | Waits for DOM change |
| `screenshot(name)` | Async canvas operations |

Example:
```javascript
// In browser console
const result = await window.__devtool.selectElement()

// Via MCP exec (automatically awaits)
proxy {action: "exec", id: "app", code: "window.__devtool.selectElement()"}
```

## Performance

- All primitives complete in under 10ms on typical pages
- Synchronous operations are instant (under 1ms)
- No memory leaks - overlays are cleaned up
- Minimal DOM impact - read-only where possible

## Connection Status

The frontend connects via WebSocket to send metrics:

```javascript
window.__devtool.isConnected()
→ true

window.__devtool.getStatus()
→ {connected: true, reconnectAttempts: 0, lastMessage: "..."}
```

Auto-reconnects with exponential backoff if disconnected.

## Custom Logging

Send logs to the proxy:

```javascript
window.__devtool.log('message', 'info', {extra: 'data'})
window.__devtool.debug('debug message')
window.__devtool.info('info message')
window.__devtool.warn('warning')
window.__devtool.error('error', {stack: '...'})
```

Query via:
```json
proxylog {proxy_id: "app", types: ["custom"]}
```

## Error Handling

All functions handle errors gracefully:

```javascript
// Element not found
window.__devtool.getPosition('.missing')
→ {error: "Element not found", selector: ".missing"}

// Invalid selector
window.__devtool.getPosition('###invalid')
→ {error: "Invalid selector", selector: "###invalid"}

// Cannot compute
window.__devtool.getContrast('.gradient-bg')
→ {error: "Cannot compute contrast for gradient background"}
```

## Testing

Use `test-diagnostics.html` in the repository for interactive testing:
- Test buttons for each category
- Various layout patterns for testing
- Console examples

## Next Steps

- [Element Inspection](/api/frontend/element-inspection) - Basic element info
- [Accessibility](/api/frontend/accessibility) - A11y auditing
- [Composite Functions](/api/frontend/composite) - High-level analysis
