render-debugger

A CLI tool for profiling Chromium-based browsers via CDP and identifying rendering bottlenecks with actionable fixes.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLI Interface                           │
├─────────────────────────────────────────────────────────────────┤
│  init │ profile │ analyze │ compare │ fix │ monitor │ rules    │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                        Core Engine                              │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
│   Recorder  │  Analyzer   │  Suggester  │   Patcher   │ Monitor │
│             │             │             │             │         │
│  • CDP      │  • Layout   │  • CSS      │  • Diff     │ • Roll  │
│  • Trace    │  • GPU      │  • JS       │  • Git      │ • Alert │
│  • Scenario │  • Tasks    │  • Native   │  • Apply    │ • Trend │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                     Browser Adapters                            │
├─────────────────────────────┬───────────────────────────────────┤
│     Chromium CDP Adapter    │      WebKit Native Adapter        │
│  (Chrome, Edge, Arc, Dia)   │    (Safari via Swift SDK)         │
└─────────────────────────────┴───────────────────────────────────┘

Installation

npm install -g render-debugger

Quick Start

# Initialize workspace
render-debugger init --browser-path /path/to/chrome

# Profile a page
render-debugger p --url "https://example.com" --scenario scroll-heavy

# Analyze (auto-detects latest trace)
render-debugger a

# Compare baseline against latest trace
render-debugger c baseline.json

# Generate fixes
render-debugger f

CLI Commands

| Command | Alias | Description | |---------|-------|-------------| | analyze [trace] | a | Analyze trace (auto-detects latest if omitted) | | profile | p | Profile a web page under a specific scenario | | compare <base> [head] | c | Compare traces (uses latest for head if omitted) | | fix [trace] | f | Generate and optionally apply patches | | monitor | m | Continuous performance monitoring | | init | - | Initialize workspace with config and scenarios | | rules list | - | Display configured rules | | rules validate | - | Validate rules configuration |

Command Examples

Analyze

# Auto-detect and analyze latest trace
render-debugger a

# Analyze specific trace
render-debugger a trace.json

# With custom name and JSON output
render-debugger a trace.json --name "homepage" --json report.json

# Generate HTML report
render-debugger a trace.json --out report.html

Profile

# Basic profile
render-debugger p --url "https://example.com" --scenario scroll-heavy

# With options
render-debugger p \
  --url "https://example.com" \
  --scenario scroll-heavy \
  --profile-duration 30 \
  --fps-target 60 \
  --headless

Compare

# Compare baseline against latest trace
render-debugger c baseline.json

# Compare two specific traces
render-debugger c baseline.json current.json

# Fail CI on high severity regressions
render-debugger c baseline.json --fail-on high --json diff.json

Impact Score Interpretation:

• 0-40: Minor changes - Small optimizations or negligible regressions
• 41-70: Moderate impact - Noticeable improvements or concerning regressions
• 71-100: Major impact - Significant improvements or critical regressions

The impact score uses enterprise-grade weighted scoring:

• Critical metrics (FPS, dropped frames) weighted 2x
• Severity-based weighting for regressions (info: 1x, warning: 2x, high: 4x, critical: 8x)
• Normalized across all detected changes for consistent scoring

Fix

# Preview fixes for latest trace
render-debugger f

# Preview fixes for specific trace
render-debugger f trace.json --dry-run

# Auto-apply with Git
render-debugger f --auto-apply --git-branch perf/fixes

Monitor

# Basic monitoring
render-debugger m --url "https://example.com" --scenario scroll-heavy

# With rolling window and alerts
render-debugger m \
  --url "https://example.com" \
  --scenario scroll-heavy \
  --rolling 60 \
  --alert-cmd "notify-send 'Performance Alert'"

CI/CD Integration

# GitHub Actions
- name: Performance Check
  run: |
    npm install -g render-debugger
    render-debugger init --browser-path /usr/bin/chromium-browser
    render-debugger p --url "$APP_URL" --scenario scroll-heavy --headless
    render-debugger a --json report.json
    render-debugger c baseline.json --fail-on high

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1-9 | General errors | | 10-19 | CDP/Browser errors | | 20-29 | Git/Patch errors | | 30-39 | Trace errors | | 40-49 | Rule errors | | 50-59 | CI threshold exceeded |

Tech Stack

• Runtime: Node.js 18+
• Framework: NestJS
• Language: TypeScript
• CDP: chrome-remote-interface
• Testing: Jest

Browser Support

| Browser | Adapter | Method | |---------|---------|--------| | Chrome | CDP | Remote debugging | | Edge | CDP | Remote debugging | | Arc | CDP | Remote debugging | | Safari | WebKit | Swift SDK |

Requirements

• Node.js 18+
• npm 9+
• Chromium-based browser
• Git (for --auto-apply)

Documentation

• CLI Commands Reference
• Browser Setup
• Swift SDK

License

MIT © Aryan Yadav