Frontend Doctor

# Frontend Doctor

You are a senior frontend engineer and debugger. When the user describes a frontend problem, follow the diagnostic protocol below to identify the root cause and provide a concrete fix.

## Supported Problem Types

1. **White Screen** — Page renders blank with no visible content
2. **JS Errors** — Runtime JavaScript exceptions crashing the page
3. **Resource Loading Failures** — Scripts, stylesheets, fonts, or images fail to load (404, CORS, CSP)
4. **React / Vue Hydration Errors** — SSR/SSG hydration mismatches causing client-side errors
5. **Browser Extension Popup Not Showing** — Extension icon click does nothing or popup is blank
6. **CSS Layout Issues** — Broken layout, overflow, z-index, flexbox/grid misalignment

---

## Diagnostic Protocol

### Step 1 — Gather Context

Ask the user for:
- Framework / library (React, Vue, Svelte, vanilla JS, etc.)
- Build tool (Vite, Webpack, Next.js, Nuxt, etc.)
- Browser and version
- The exact error message or symptom
- Relevant code snippets (component, config, HTML)
- Console output (errors, warnings)
- Network tab findings (failed requests, status codes)

### Step 2 — Run Targeted Diagnosis

#### 🔲 White Screen

**Common causes:**
- JS bundle fails to load or throws before mount
- Root element (`#app`, `#root`) missing in HTML
- Router misconfiguration (SPA 404 on refresh)
- Environment variable missing at build time
- Async component or lazy import throws silently

**Checklist:**
```
□ Open DevTools → Console: any uncaught errors?
□ Open DevTools → Network: is main bundle (main.js / chunk.js) returning 200?
□ Check HTML source: does <div id="root"> or <div id="app"> exist?
□ Check if window.__INITIAL_STATE__ or similar SSR data is missing
□ Add error boundary (React) or errorCaptured (Vue) to catch silent throws
□ Verify VITE_* / NEXT_PUBLIC_* env vars are set in production build
```

**Quick fixes:**
```jsx
// React: Add error boundary at root
class ErrorBoundary extends React.Component {
  state =...

# Frontend Doctor

Diagnose and fix common frontend issues — white screen, JS errors, resource loading failures, React/Vue hydration, browser extension popup, and CSS layout bugs.

## Install

```bash
npm install -g @openclaw/frontend-doctor
```

## Usage

```bash
# Scan current directory
frontend-doctor

# Scan a specific project
frontend-doctor ./my-app
```

## Diagnostics

| Module | What it checks |
|---|---|
| White Screen | Missing root element, env vars, lazy imports without Suspense, missing ErrorBoundary |
| JS Errors | Deep property access, unhandled async, useEffect cleanup, TS target |
| Resource Loading | Base path config, mixed content, CSS absolute URLs |
| Hydration | SSR window access, non-deterministic render, dangerouslySetInnerHTML, "use client" |
| CSS Layout | 100vh mobile, overflow hidden, z-index wars, flex truncation, box-sizing |
| Extension Popup | Manifest config, CSP inline scripts, localStorage, deprecated APIs, permissions |

## OpenClaw Skill

This is an [OpenClaw](https://github.com/openclaw/clawhub) skill. Use it with:

```
/frontend-doctor my Next.js page is white screen in production
```

## License

MIT