# Web Preview

> A browser column beside your shards for the thing you are building. Click what looks wrong, type a note, and your agent gets the element, the picture, and the page's errors.

crystl has a built-in browser column that sits beside your shards and shows the thing you are building. It is made for local dev servers first: your agent starts the server, the page appears next to the terminal, and you watch each change land without switching windows. The column runs WebKit, the same engine as Safari, so sites load as they would in Safari.

The point is the loop. You see a layout bug, you click it, you type what you see, and your agent gets the element, a picture of it, and your note. No screenshot, no "it's the button on the left, no, the other one".

## Opening it

- **From the sidebar.** The web view is one of the right sidebar's views. `Cmd + ]` and `Cmd + [` cycle the views, and a first press opens the sidebar if it is closed. See [keyboard shortcuts](/docs/keyboard-shortcuts/).
- **From the address bar.** The picker at the end of the address bar lists the dev servers running on this Mac: the port, the command, and the shard that started it, with this gem's servers first. Click one and the column loads it. A new column with no URL shows the same list in the page area. Typing helps too: `5173` means `http://localhost:5173`, and a bare host gains `https://`.
- **From an agent.** `crystl web open <url>`, or `crystl web open --server <port>` for a listening port. It works only on the gem you are looking at, and it lands in the gem's first web column.

## Capture: point at what is wrong

The crosshair button in the column header arms capture. Move the pointer over the page and the element under it outlines, with a small label naming it. Click the one that is wrong. One click captures one element and disarms the crosshair; hold shift while clicking to keep it armed and capture several.

A small note field appears, asking **what's wrong here?** Type what you see, in your own words: "the price is clipped". Press Enter, or the send button beside the field.

Your agent receives two things. First, a one-line handoff naming the capture, like `Preview capture 3f9a2c1d: run crystl web capture 3f9a2c1d.` Second, when it runs that command, a markdown capture file: a cropped picture of the element, the element's outline (its selector, its HTML, its computed styles, and the source file and line when your framework reports them), and your note beside it. The agent reads the complaint next to the evidence.

Everything in a capture that came from the page is marked as data, not instructions. Your agent treats page text as evidence to read, never as a command to follow.

## Errors

A strip under the address bar counts what went wrong on the page: console errors, failed requests, and navigation failures. **show** expands the list, newest first. Click a row to copy it. **for agent** hands the whole list to your agent in one line.

From the agent's side, `crystl web errors` reads the list, and `--clear` removes the entries it printed. So an agent can check the console before it tells you a page works, which is the honest order to do it in.

## The instrumentation switch

Capture and the errors feed work through two small scripts crystl adds to the page. The **instrumentation** switch in the column header is on by default, and each column has its own. Turning it off removes both scripts and reloads the page, so it runs exactly as a plain browser would run it; form state is lost in that reload. Capture needs instrumentation on.

## For agents

Each command works on the gem's first web column, the same one `crystl web open` lands in, unless `--column` names another. All of them are free on every tier.

- `crystl web snapshot` writes a PNG of the live page and prints its path, so an agent can look at what shipped.
- `crystl web capture <id>` prints a capture: the note, the element, and the path to its picture. `crystl web capture list` lists this gem's captures.
- `crystl web errors` prints the page's error list; `--clear` removes the entries it printed.
- `crystl web reload` reloads the live page.

Full details are in the [CLI reference](/docs/cli/#web).

## Memory

A column you cannot see releases its page after a short while, which is what lets the system reclaim its memory. The URL and title stay, and the column reloads the page when you show it again; scroll position and form input are lost.

Login state is kept per gem. Each gem has its own cookies and site storage, so one project's staging login never shows up in another project's column. Closing a gem keeps its logins, and reopening the folder restores them.

## What it is not

The web column is not a replacement for your browser. There are no extensions, no devtools panel, and no tabs: a second page is a second column. Your logged-in sessions, your password manager, and Chrome's developer tools live in your browser, and **open in browser** is one click away in the column header.

---
Source: https://crystl.dev/docs/web-preview/
