browser-preview — Claude Code skill: preview and iframe diagnostics

What browser-preview does

This skill kicks in when the preview panel breaks: white screen, tab gone, assets returning 404, service not loading. It gives the agent a fixed order of steps. First read the running-service registry at /data/previews.json, then the history at /data/preview_history.json, then check the port with curl server-side. If the process died but the registry entry is still there, the skill says to recreate it with preview_stop and preview_serve.

The rule it drills hardest: users cannot reach localhost or 127.0.0.1. Previews go through a reverse proxy, so the only URL worth handing over is /preview/{id}/. The second common break is absolute paths in static files. Because everything is served under the /preview/{id}/ prefix, the browser asks for /static/app.js from the domain root and gets a 404. The skill tells the agent to check every place a path can hide: src and href attributes, fetch() calls, CSS url(), JS string literals, and bundler config like publicPath and base.

It also forbids poking around workspace folders such as preview/ or output/ with ls and find. Those hold user data, not service state. The registry, the history file, and the preview_serve and preview_stop tools are the only sources of truth. If the RUNNING SERVICES list looks empty while the port still answers, the frontend lost sync — recreating the service forces it to register the tab again.