preview — serving VFS content in the browser

SYNOPSIS

serve [--entry <file>] [--project] <directory>   Serve a VFS directory in a new tab
open [--download|-d] [--view|-v] <path|url>      Open a VFS file or URL in a new tab

DESCRIPTION

SLICC has no real HTTP server. All file previewing is handled by a preview service worker that intercepts /preview/* requests and serves content directly from the VFS. This works entirely in-browser with no network traffic. There are no long-running servers, no background daemons, and no package managers — serve and open are the only way to preview files.

Do not attempt to start servers with npm install, python -m http.server, or any other external tool. They are unavailable. The preview service worker is all you need.

COMMANDS

serve

Serves a VFS directory in a new browser tab. Defaults to index.html as the entry file. Use --entry <file> to override with a different file inside the directory.

serve /workspace/myapp                      Serve with index.html
serve --entry app.html /workspace/myapp     Serve with app.html as entry
serve --project /workspace/myapp            Project mode: root-relative paths resolve against dir

The --project flag enables project serve mode, where root-relative requests (e.g., /styles/main.css, /scripts/app.js) resolve against the served directory. Use this for frameworks that expect a local dev server.

open

Opens a single VFS file or URL in a new browser tab. For app directories with multiple files, prefer serve instead.

open /workspace/myapp/index.html            Open a VFS file
open https://example.com                    Open a URL
open --view /workspace/screenshot.png       Return image inline for agent vision
open --download /workspace/report.pdf       Force download instead of opening

Files ending in .shtml are routed to the sprinkle system, not opened as browser tabs. They open as interactive sprinkle panels instead.

CRITICAL RULES

Always use the output URL. Both serve and open print a preview URL in their output. Always use that URL — never manually construct preview URLs.
Do not open duplicates. serve and open already open a browser tab. Do NOT use playwright-cli open with the same URL — that creates a duplicate tab.
To screenshot a served page: Use playwright-cli tab-list to find the tab by URL, note the targetId, then use playwright-cli screenshot --tab=<targetId>.
No package managers. Do not run npm install, pip install, python -m http.server, or any external server. They are not available. Use serve and open.
No long-running servers. You cannot start background daemons. The preview service worker handles everything.

WORKFLOW EXAMPLE

# Build an app in VFS
write_file /workspace/myapp/index.html "<html>...</html>"
write_file /workspace/myapp/style.css "body { ... }"

# Serve the app directory
serve /workspace/myapp
# Output: serving /workspace/myapp → http://localhost:5710/preview/workspace/myapp/index.html

# Find the tab and screenshot it
playwright-cli tab-list
# Find the tab matching the preview URL, note its targetId
playwright-cli screenshot --tab=<targetId>

HOW IT WORKS

The preview service worker (preview-sw.ts) is registered at the /preview/ scope. It intercepts fetch requests matching /preview/*, strips the /preview prefix to get the VFS path, and reads the file content directly from LightningFS (IndexedDB). For mounted directories (File System Access API), the SW falls back to asking the main page via BroadcastChannel, since service workers cannot access directory handles.

When a directory path is requested, the SW automatically looks for index.html inside that directory.

INTERNAL API

toPreviewUrl(vfsPath) from packages/webapp/src/shell/supplemental-commands/shared.ts is the canonical function for generating preview URLs. It returns the correct URL for both CLI mode (using window.location.origin) and extension mode (using chrome.runtime.getURL()). The serve and open commands use this internally — you should never need to call it directly.