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:

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

Or execute remotely via MCP:

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:

// 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:

// 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:

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	9	Get element properties, styles, layout
Tree Walking	3	Navigate DOM hierarchy
Visual State	3	Check visibility and overlap
Layout Diagnostics	3	Find layout issues
Visual Overlays	3	Highlight and debug visually
Interactive	4	User interaction and waiting
State Capture	4	Capture DOM, styles, storage
Accessibility	5	A11y inspection and auditing
Composite	3	High-level analysis
Layout Robustness	3	Text fragility, responsive risks, performance
Quality Auditing	4	Core Web Vitals, DOM complexity, page quality, auditAll (8 scored audits)
Responsive Mode	5	Interactive width-driving workbench with live shift detection
CSS Evaluation	1	auditCSS — architecture, containment, Tailwind, consistency
Security & Validation	2	auditSecurity (CSP, XSS, forms, SRI), detectFramework

Quick Reference

Most Used Functions

// 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

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

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

Debugging

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

User Interaction

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

CSS Analysis

window.__devtool.auditCSS()               // Full CSS audit with grade
// One call returns architecture, containment, responsive strategy,
// consistency, content areas, and Tailwind usage as a graded report.

Quality & Performance

window.__devtool.auditPageQuality()       // Comprehensive quality audit
window.__devtool.auditPerformance()       // Core Web Vitals, CLS, TBT, resources
window.__devtool.auditDOMComplexity()     // DOM node count, depth, heavy parents
window.__devtool.checkTextFragility()     // Text truncation issues
window.__devtool.checkResponsiveRisk()    // Responsive breakage
window.__devtool.auditAll()               // Eight scored audits, one grade

Security & Validation

window.__devtool.auditSecurity()          // Comprehensive security audit
window.__devtool.detectFramework()        // Detect React, Vue, Angular, etc.
// auditSecurity covers headers, DOM security, forms, framework quality,
// external resources, and prototype pollution in one graded report.

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:

// 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:

window.__devtool.isConnected()
→ true

window.__devtool.getStatus()
→ "connected"   // or "connecting", "closing", "closed", "not_initialized"

window.__devtool.transport.getConnectionState()
→ {connected: true, readyState: 1, readyStateLabel: "OPEN", reconnectAttempts: 0,
   maxReconnectAttempts: null, reconnectPending: false, reconnectMaxDelayMs: 30000, wsUrl: "..."}

Auto-reconnects with exponential backoff if disconnected: 1s, 2s, 4s, ... capped at 30s, with no attempt limit. Coming back online or showing the tab again reconnects immediately.

Custom Logging

Send logs to the proxy:

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:

proxylog {proxy_id: "app", types: ["custom"]}

Error Handling

All functions handle errors gracefully:

// 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 - Basic element info
• Accessibility - A11y auditing
• Composite Functions - High-level analysis