# Lightpanda Browser Evaluation
**Date:** 2025-12-07
**Evaluator:** Claude
**Repository:** https://github.com/lightpanda-io/browser
**Status:** Beta
## Executive Summary
**Recommendation: NOT RECOMMENDED for production use at this time.**
Lightpanda is a promising open-source headless browser written in Zig that claims significant performance improvements (11x faster, 9x less memory) over Chrome. However, its beta status, incomplete Web API coverage, and unknown compatibility with our specific Disney session extraction requirements make it unsuitable for our production use case.
## Current Playwright Usage Analysis
Our `SessionManager` (src/clients/session-manager.ts) uses the following Playwright features:
| Feature | Usage | Lightpanda Support |
|---------|-------|-------------------|
| `chromium.launch({ headless })` | Start browser | ✅ Via CDP |
| `browser.newContext()` with userAgent, viewport, locale, timezoneId | Configure session | ⚠️ Partial |
| `page.goto(url, { waitUntil, timeout })` | Navigate to Disney | ✅ Likely |
| `page.$(selector)` | Query DOM | ✅ Supported |
| `element.click()` | Click consent banner | ✅ Supported |
| `page.waitForTimeout()` | Fixed delays | ⚠️ Unknown |
| `context.cookies()` | Extract auth cookies | ⚠️ Unknown |
| `context.storageState()` | Get cookies + localStorage | ❌ Unknown |
| JavaScript execution (client-side JWT generation) | Critical for `__d` cookie | ✅ Uses V8 |
### Critical Dependency: Client-Side JWT Generation
Disney's authentication cookie (`__d`) is generated by JavaScript after page load. This is the most critical requirement. Lightpanda uses V8 for JavaScript execution, which should theoretically support this, but Disney's JS may use Web APIs that Lightpanda doesn't fully implement.
## Lightpanda Capabilities
### Confirmed Features
- JavaScript execution via V8 engine
- DOM APIs (createElement, querySelector, etc.)
- Ajax support (XHR and Fetch)
- Click actions and form input
- Cookie and custom header support
- Proxy support and network interception
- CDP/WebSocket server (Playwright-compatible)
### Limitations
- **Beta status** with explicit warning: "You may still encounter errors or crashes"
- Incomplete Web API coverage ("There are hundreds of Web APIs")
- Playwright compatibility has caveats about "different code paths"
- No GUI mode (headless only) - can't debug visually
## Performance Claims
From Lightpanda benchmarks (100-page Puppeteer test on AWS m5.large):
| Metric | Chrome/Puppeteer | Lightpanda | Improvement |
|--------|-----------------|------------|-------------|
| Memory | ~110 MB avg | ~12 MB avg | 9x less |
| Speed | ~900ms/page | ~80ms/page | 11x faster |
| Startup | ~2-3 seconds | Instant | Significant |
These improvements are impressive but less relevant for our use case where:
1. Sessions are refreshed every 8 hours (not high-frequency)
2. Only 2 destinations (WDW, DLR) need sessions
3. Memory/speed aren't bottlenecks currently
## Risk Assessment
### High Risk ⛔
1. **Web API Coverage Gaps**: Disney's website uses modern JS features. Unknown if Lightpanda implements all required APIs.
2. **Cookie/Storage Extraction**: Our exact usage of `context.storageState()` may not work identically.
3. **No Fallback**: If Lightpanda fails, we lose Disney API access entirely.
4. **Debugging Difficulty**: No visual browser mode makes troubleshooting harder.
### Medium Risk ⚠️
1. **OneTrust Compatibility**: Cookie consent handling requires DOM interaction; may behave differently.
2. **Timezone/Locale**: Configuration options may not match Playwright's API.
3. **Maintenance Burden**: Beta software requires more frequent updates and fixes.
### Low Risk ✅
1. **V8 JavaScript Engine**: Same engine as Chrome, so core JS should work.
2. **CDP Protocol**: Standard protocol with good compatibility.
## Implementation (Experimental)
We've implemented experimental Lightpanda support as an optional backend:
### Browser Backend Abstraction
New files in `src/clients/browser-backends/`:
- `types.ts` - Backend interface definition
- `playwright-backend.ts` - Default Playwright implementation
- `lightpanda-backend.ts` - CDP-based Lightpanda connector
- `index.ts` - Factory functions
### Configuration
```bash
# Use Lightpanda (requires running Lightpanda server)
MOUSE_MCP_BROWSER=lightpanda
# Auto-detect: use Lightpanda if available, else Playwright
MOUSE_MCP_BROWSER=auto
# Custom CDP endpoint (default: http://127.0.0.1:9222)
MOUSE_MCP_CDP_ENDPOINT=http://localhost:9222
```
### Testing Script
Run comparison tests with:
```bash
# Start Lightpanda first
./lightpanda serve --host 127.0.0.1 --port 9222
# Run comparison
npx tsx scripts/test-lightpanda.ts
```
The script compares:
- Browser startup time
- Navigation performance
- Cookie extraction success
- Auth token detection (`__d`, `finderPublicTokenExpireTime`, `SWID`)
### How to Test
1. **Download Lightpanda**:
```bash
curl -L -o lightpanda \
"https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux"
chmod +x lightpanda
```
2. **Start Lightpanda CDP server**:
```bash
./lightpanda serve --host 127.0.0.1 --port 9222
```
3. **Run comparison test**:
```bash
npx tsx scripts/test-lightpanda.ts
```
4. **Enable in production** (if tests pass):
```bash
MOUSE_MCP_BROWSER=lightpanda npm start
```
## Actual Test Results (2025-12-07)
We ran the test script against Lightpanda nightly build `cdd73990` on macOS ARM64.
### Results
| Test | Playwright | Lightpanda |
|------|------------|------------|
| Connection | ✅ Works | ❌ Hangs |
| CDP Discovery (`/json/version`) | ✅ Works | ⚠️ Partial (no trailing slash) |
| `connectOverCDP()` | ✅ Works | ❌ 404 error |
| `connect(wsEndpoint)` | N/A | ❌ Hangs indefinitely |
| Navigation | ⚠️ Transient errors | N/A (never reached) |
### Key Findings
1. **CDP Discovery Incompatibility**: Lightpanda's `/json/version` endpoint doesn't support the trailing slash that Playwright's `connectOverCDP()` expects. Returns 404 for `/json/version/`.
2. **WebSocket Connection Hangs**: Even when fetching the WebSocket URL directly and using `chromium.connect()`, Playwright hangs indefinitely. This is because Playwright's `connect()` expects a Playwright Server protocol, not raw CDP.
3. **Puppeteer Required**: Lightpanda's documentation recommends Puppeteer, not Playwright. Their CDP implementation is compatible with Puppeteer's lower-level CDP bindings but not Playwright's high-level API.
4. **Not Playwright-Compatible**: Our entire codebase uses Playwright. Switching to Puppeteer would require significant refactoring of `SessionManager` and all browser-related code.
### Conclusion
**Lightpanda is NOT compatible with Playwright** for our use case. The CDP implementation works with Puppeteer but not with Playwright's connection methods (`connectOverCDP` or `connect`).
## Alternatives Considered
| Alternative | Pros | Cons |
|-------------|------|------|
| **Keep Playwright** | Battle-tested, full API | Higher memory/CPU |
| **Puppeteer** | Lighter than Playwright, works with Lightpanda | Would require codebase refactor |
| **Lightpanda** | Fastest, lowest memory | Not Playwright-compatible |
| **Direct API Auth** | No browser needed | Disney doesn't expose auth endpoints |
## Decision
**Stick with Playwright** for the following reasons:
1. **Reliability over performance**: Session management is critical infrastructure. Downtime = no Disney API access.
2. **Low session frequency**: We refresh sessions every 8 hours, not per-request. Browser overhead is negligible.
3. **Production readiness**: Playwright is battle-tested; Lightpanda explicitly warns of crashes.
4. **Debugging capability**: Playwright's `MOUSE_MCP_SHOW_BROWSER=true` enables visual debugging.
5. **No compelling ROI**: The memory/speed gains don't justify the risk for our use case.
## Future Reconsideration
Revisit this decision when:
- Lightpanda adds native Playwright compatibility (not just Puppeteer)
- Lightpanda reaches stable release (v1.0+)
- We decide to migrate from Playwright to Puppeteer for other reasons
- Web API coverage significantly expands
- Someone validates Disney.com specifically works with Puppeteer + Lightpanda
## References
- [Lightpanda GitHub](https://github.com/lightpanda-io/browser)
- [Lightpanda Website](https://lightpanda.io)
- [CDP Protocol Spec](https://chromedevtools.github.io/devtools-protocol/)
- [Playwright CDP Docs](https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp)
