Browser Preview

# Browser Preview

You already know `preview_serve` and `preview_stop`. This skill fills the gap: what happens **after** preview_serve returns a URL — how the user actually sees it.

## What is the Preview Panel

The frontend has a right-side panel with three tabs: **Files**, **Preview**, and **Jobs**. The Preview tab renders preview URLs inside an iframe. When you call `preview_serve`, the frontend automatically opens a Preview tab loading that URL.

Key facts:
- Each `preview_serve` call creates one Preview tab
- URL format: `https://<host>/preview/{id}/`
- Preview panel has a **⋮ menu** (top-right) showing "RUNNING SERVICES" list
- Preview tab can be **closed by the user** without stopping the backend service
- Backend service stopping → Preview tab shows an error page

## ⚠️ CRITICAL: Never Tell Users to Access localhost

**The user's browser CANNOT access `localhost` or `127.0.0.1`.** These addresses point to the server container, not the user's machine. The preview architecture uses a **reverse proxy**:

```
User's Browser → https://<host>/preview/{id}/path → (reverse proxy) → 127.0.0.1:{port}/path
```

Rules:
- **NEVER** tell the user to visit `http://localhost:{port}` or `http://127.0.0.1:{port}` — they cannot reach it
- **ALWAYS** direct users to the preview URL: `/preview/{id}/` (or the full URL `https://<host>/preview/{id}/`)
- `curl http://localhost:{port}` is for **your own server-side diagnostics only** — never suggest it to the user as a way to "test" the preview
- When a preview is running, tell the user: "Check the Preview panel, or refresh the Preview panel"
- If you need to give the user a URL, use the `url` field returned by `preview_serve` (format: `/preview/{id}/`)

## ⚠️ Static Assets Must Use Relative Paths

Because previews are served under `/preview/{id}/`, **absolute paths in HTML/JS/CSS will break**. The reverse proxy strips the `/preview/{id}` prefix before forwarding to the backend, but the browser resolves absolute paths from the domain root.

Example of the problem:
```html
<!-- ❌ BROKEN: browser requests https://host/static/app.js → 404 (bypasses preview proxy) -->
<script src="/static/app.js"></script>

<!-- ✅ WORKS: browser requests https://host/preview/{id}/static/app.js → proxied correctly -->
<script src="static/app.js"></script>
<script src="./static/app.js"></script>
```

Common patterns to fix:
| Broken (absolute) | Fixed (relative) |
|---|---|
| `"/static/app.js"` | `"static/app.js"` or `"./static/app.js"` |
| `"/api/users"` | `"api/users"` or `"./api/users"` |
| `"/images/logo.png"` | `"images/logo.png"` or `"./images/logo.png"` |
| `url('/fonts/x.woff')` | `url('./fonts/x.woff')` |
| `fetch('/data.json')` | `fetch('data.json')` |

**Check ALL places** where paths appear:
1. HTML `src`, `href` attributes
2. JavaScript `fetch()`, `XMLHttpRequest`, dynamic imports
3. CSS `url()` references
4. JavaScript string literals (e.g., `'/static/'` in template strings or concatenation)
5. Framework config files (e.g., `publicPath`, `base`, `assetPrefix`)

⚠️ Be thorough — it's common to fix CSS `url()` but miss JS string literals like `'/static/'` (with single quotes). Search for ALL occurrences of absolute paths across all file types.

## ⚠️ Do NOT Browse Filesystem to Debug Previews

**Never** look at workspace directories like `preview/`, `output/`, or random folders to understand preview state. Those are user data, not preview service state.

The **only** sources of truth:
1. Registry file: `/data/previews.json` (running services)
2. History file: `/data/preview_history.json` (all past servi