1---
2name: browser-preview
3version: 1.1.1
4description: |
5  Preview panel and iframe diagnostics: registry, ports, paths, blank screens.
6 
7  Use when a preview tab is broken or missing (e.g. white screen, tab disappeared, 404 on assets, preview not loading, list running services).
8 
9metadata:
10  starchild:
11    emoji: "🌐"
12    skillKey: browser-preview
13 
14user-invocable: true
15disable-model-invocation: false
16 
17---
18 
19# Browser Preview
20 
21You 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.
22 
23## What is the Preview Panel
24 
25The 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.
26 
27Key facts:
28- Each `preview_serve` call creates one Preview tab
29- URL format: `https://<host>/preview/{id}/`
30- Preview panel has a **⋮ menu** (top-right) showing "RUNNING SERVICES" list
31- Preview tab can be **closed by the user** without stopping the backend service
32- Backend service stopping → Preview tab shows an error page
33 
34## ⚠️ CRITICAL: Never Tell Users to Access localhost
35 
36**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**:
37 
38```
39User's Browser → https://<host>/preview/{id}/path → (reverse proxy) → 127.0.0.1:{port}/path
40```
41 
42Rules:
43- **NEVER** tell the user to visit `http://localhost:{port}` or `http://127.0.0.1:{port}` — they cannot reach it
44- **ALWAYS** direct users to the preview URL: `/preview/{id}/` (or the full URL `https://<host>/preview/{id}/`)
45- `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
46- When a preview is running, tell the user: "Check the Preview panel, or refresh the Preview panel"
47- If you need to give the user a URL, use the `url` field returned by `preview_serve` (format: `/preview/{id}/`)
48 
49## ⚠️ Static Assets Must Use Relative Paths
50 
51Because 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.
52 
53Example of the problem:
54```html
55<!-- ❌ BROKEN: browser requests https://host/static/app.js → 404 (bypasses preview proxy) -->
56<script src="/static/app.js"></script>
57 
58<!-- ✅ WORKS: browser requests https://host/preview/{id}/static/app.js → proxied correctly -->
59<script src="static/app.js"></script>
60<script src="./static/app.js"></script>
61```
62 
63Common patterns to fix:
64| Broken (absolute) | Fixed (relative) |
65|---|---|
66| `"/static/app.js"` | `"static/app.js"` or `"./static/app.js"` |
67| `"/api/users"` | `"api/users"` or `"./api/users"` |
68| `"/images/logo.png"` | `"images/logo.png"` or `"./images/logo.png"` |
69| `url('/fonts/x.woff')` | `url('./fonts/x.woff')` |
70| `fetch('/data.json')` | `fetch('data.json')` |
71 
72**Check ALL places** where paths appear:
731. HTML `src`, `href` attributes
742. JavaScript `fetch()`, `XMLHttpRequest`, dynamic imports
753. CSS `url()` references
764. JavaScript string literals (e.g., `'/static/'` in template strings or concatenation)
775. Framework config files (e.g., `publicPath`, `base`, `assetPrefix`)
78 
79⚠️ 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.
80 
81## ⚠️ Do NOT Browse Filesystem to Debug Previews
82 
83**Never** look at workspace directories like `preview/`, `output/`, or random folders to understand preview state. Those are user data, not preview service state.
84 
85The **only** sources of truth:
861. Registry file: `/data/previews.json` (running services)
872. History file: `/data/preview_history.json` (all past services)
883. `preview_serve` / `preview_stop` tools
894. Port checks via `curl` (server-side only, for your diagnostics)
90 
91Do NOT use `ls`/`find` on workspace directories to diagnose preview issues. Do NOT call unrelated tools like `list_scheduled_tasks`. Stay focused.
92 
93## Step-by-Step: Diagnosing Preview Issues
94 
95When a user reports any Preview panel problem, follow this exact sequence:
96 
97### Step 1: Read the registry (running services)
98 
99```bash
100cat /data/previews.json 2>/dev/null || echo "NO_REGISTRY"
101```
102 
103⚠️ Your bash CWD is `/data/workspace/`. The registry is at `/data/previews.json` (absolute path, one level up). Always use the absolute path.
104 
105JSON structure:
106```json
107{
108  "previews": [
109    {"id": "f343befc", "title": "My App", "dir": "/data/workspace/my-project", "command": "npm run dev", "port": 9080, "is_builtin": false}
110  ]
111}
112```
113 
114### Step 2: Branch based on registry state
115 
116**If registry has entries** → Go to Step 3 (verify services)
117**If registry is empty or missing** → Go to Step 4 (check history)
118 
119### Step 3: Registry has entries — verify and fix
120 
121For each preview in the registry, check if the port is responding **server-side** (this is your diagnostic, not for the user):
122```bash
123curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}
124```
125 
126**If port responds (200):**
127- The service IS running. Tell the user:
128  - "You have a running service: {title}"
129  - "Click the ⋮ menu at the top-right of the Preview panel, then click it in the RUNNING SERVICES list to reopen"
130  - Preview URL: `/preview/{id}/`
131- **If user says the ⋮ menu is empty or doesn't show the service** → frontend lost sync. Fix by recreating: `preview_stop(id)` then `preview_serve(dir, title, command)` using the info from the registry. This forces the frontend to re-register the tab.
132 
133**If port does NOT respond:**
134- Process crashed but registry entry remains. Recreate:
135  ```
136  preview_stop(id="{id}")
137  preview_serve(dir="{dir}", title="{title}", command="{command}")
138  ```
139 
140### Step 4: No running services — check history first, then scan workspace
141 
142When there are no running services, use a **two-tier lookup** to find projects the user can preview:
143 
144#### Tier 1: Read preview history (preferred — fast and accurate)
145 
146```bash
147cat /data/preview_history.json 2>/dev/null || echo "NO_HISTORY"
148```
149 
150JSON structure:
151```json
152{
153  "history": [
154    {
155      "id": "f343befc",
156      "title": "Trading System",
157      "dir": "/data/workspace/my-project",
158      "command": "python main.py",
159      "port": 8000,
160      "is_builtin": false,
161      "created_at": 1709100000.0,
162      "last_started_at": 1709200000.0
163    }
164  ]
165}
166```
167 
168History entries are **never removed by `preview_stop`** — they persist across restarts. Entries are automatically pruned only when the project directory no longer exists.
169 
170**If history has entries:**
171- List all history entries to the user with title, directory, and last started time
172- Ask which one they want to restart
173- Call `preview_serve` with the `dir`, `title`, and `command` from the history entry
174 
175**If user says a project is missing from history** → fall through to Tier 2.
176 
177#### Tier 2: Scan workspace (fallback — when history is empty or incomplete)
178 
179```bash
180find /data/workspace -maxdepth 2 \( -name "package.json" -o -name "index.html" -o -name "*.html" -o -name "app.py" -o -name "main.py" -o -name "vite.config.*" \) -not -path "*/node_modules/*" -not -path "*/skills/*" -not -path "*/memory/*" -not -path "*/prompt/*" -not -path "*/.git/*" 2>/dev/null
181```
182 
183Then:
1841. List discovered projects with brief descriptions
1852. Ask the user which one to preview
1863. Call `preview_serve` with the appropriate directory
187 
188**Don't just say "no services running" and stop.** Always check history first, then scan, and offer options.
189 
190## Quick Reference
191 
192| User says | You do |
193|-----------|--------|
194| "tab disappeared" / "tab 不见了" | Step 1 → 2 → 3 or 4 |
195| "blank page" / "白屏" | Check port (server-side), if dead → recreate; if alive → check for absolute path issues |
196| "not updating" / "内容没更新" | Suggest refresh button in Preview tab, or recreate preview |
197| "port conflict" / "端口冲突" | `preview_stop` old → `preview_serve` new |
198| "can't see service" / "⋮ menu empty" | `preview_stop` + `preview_serve` to force re-register |
199| "where's my project" / "what did I build" | Read `/data/preview_history.json` and list entries |
200| "resource load failed" / "JS/CSS 404" | Check for absolute paths (`/static/`, `/api/`), fix to relative paths |
201 
202## What You Cannot Do
203 
204- Cannot directly open/close/refresh Preview tabs (frontend UI)
205- Cannot force-refresh the iframe
206- Cannot read what the iframe displays
207 
208When you can't do something, tell the user the manual action (e.g., "click refresh in Preview tab"). If manual action doesn't work, recreate the preview with `preview_stop` + `preview_serve`.
209 
210## Common Mistakes to Avoid
211 
2121. ❌ Telling user to "visit http://localhost:18791/" — user cannot access localhost
2132. ❌ Saying "refresh the page at localhost" — meaningless to the user
2143. ❌ Only fixing CSS `url()` paths but missing JS string literals with absolute paths
2154. ❌ Forgetting to check ALL file types (HTML, JS, CSS, config) for absolute paths
2165. ✅ Always use `/preview/{id}/` as the user-facing URL
2176. ✅ Always use `curl localhost:{port}` only for your own server-side diagnostics
2187. ✅ After fixing paths, call `preview_stop` + `preview_serve` to restart, then tell user to check Preview panel
219