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