> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview

> Run your BRICKS application in an embedded preview pane

Preview your BRICKS application inside the chat window. The **Preview** tab in the [right panel](/ctor/reference/right-panel) runs the compiled project as an embedded webview, picks up file changes automatically, and exposes a Chrome DevTools Protocol (CDP) endpoint for the [BRICKS CLI](/cli).

## Open the preview

Add the **Preview** tab from the [right panel](/ctor/reference/right-panel)'s **+** (New tab) menu. The tab starts compiling your project in the background.

When the tab opens, CTOR runs `bun typecheck` followed by `bun compile.ts`, then loads the application into an embedded webview using the stage from your `application.json` (`production`, `beta`, or `development`).

<Info>
  Preview requires `bun` to be installed and available in your `PATH`.
</Info>

## Pane controls

The tab's toolbar has these buttons:

| Button       | Action                                         |
| ------------ | ---------------------------------------------- |
| **DevTools** | Dock the preview's inspector as a bottom panel |
| **Refresh**  | Reload the webview                             |
| **Pop out**  | Open the preview in a new in-app window        |

Close the preview from the **×** on its tab in the [right panel](/ctor/reference/right-panel); this stops the backend.

## Dock the preview's DevTools

Click **DevTools** in the tab's toolbar to dock the preview's own Chrome DevTools inspector as a resizable panel at the bottom of the tab. Drag the divider to adjust its height; click **DevTools** again to hide it.

The inspector connects to the preview's local CDP server, so no passcode is needed. Opening a device's DevTools from the **Local Devices** panel routes into this dock when that device is the foreground project's preview; other devices open as their own [DevTools tab](/ctor/reference/right-panel#devtools) instead.

## Layout in the right panel

The preview shares the [right panel](/ctor/reference/right-panel) with the Diff, Controller, and DevTools tabs. Only one tab is visible at a time — switch between them from the tab bar or with **Cmd+1..9**. Drag the handle on the panel's left edge to resize it against the chat area.

## Live recompile

The pane watches your project for changes:

* Saving any file under `subspaces/` triggers a debounced rebuild via `bun compile.ts`.
* Changes to `.bricks/build/application-config.json` are pushed into the running webview without a full reload.

## Pop-out window

Click **Pop out** to detach the preview into its own frameless in-app window. The new window keeps the backend session alive — closing the chat-side pane, switching sessions, or switching projects does not stop a popped-out preview. Close the pop-out window itself to release the session.

## Agent-driven preview

The agent uses the same preview runtime as the **Preview** tab to take screenshots and run [BRICKS Automation](/foundation/automations) tests, so what the agent sees matches what you see in the tab. If the tab isn't open when the agent needs a screenshot, it spins the preview up in the background instead of opening it on top of your chat — the input bar surfaces this with a **Preview** indicator (an accent dot and a tooltip noting the preview is running in the background). Click it to bring the preview tab forward.

Vision-capable models receive each screenshot inline; the image file is also written to the project so non-vision models can reference it by path. With a [fallback vision model](/ctor/reference/settings#fallback-vision-model) set, CTOR also describes each screenshot as text so a non-vision model can act on what it shows.

## Record interactions as an automation

As you interact with the running preview, CTOR records each step. Open the preview pane's menu (the **≡** button) and click **Record Events as Automations** to turn the recorded session into a [BRICKS Automation](/foundation/automations) (E2E test).

Rather than write the test silently, CTOR pre-fills the chat input with a request asking the agent to author the automation — review it and press send, the same way [Draw mode](#draw-mode) hands its result to the input bar. The request describes the recording for the agent:

* **Real timings** — each step carries the wall-clock time it fired and the gap from the previous step, so the agent can reproduce realistic timing between steps instead of uniform delays.
* **Named entries** — the subspaces, bricks, generators, and canvases referenced by each step are resolved to their editor alias (falling back to their title), so the request reads in terms of your project instead of opaque ids.

Edit the request before sending to trim or reorder steps. The agent writes the automation in the bricks-ctor format, then compiles and runs it in the preview to confirm it passes.

## Running multiple projects

Each open project keeps its own preview lifecycle, so a simulator started in one project keeps running while you work in another. Only one preview pane is visible at a time — whichever project is in the foreground — but background simulators stay alive for agent screenshots, CDP inspection, and pop-out windows.

## Draw mode

Click **Draw** in the pane header to overlay an annotation canvas on top of the running preview. A toolbar appears at the bottom of the pane with these tools:

| Tool          | Action                                                                            |
| ------------- | --------------------------------------------------------------------------------- |
| **Pen**       | Freehand stroke                                                                   |
| **Arrow**     | Straight arrow from where you start the drag to where you release                 |
| **Rectangle** | Outlined box                                                                      |
| **Text**      | Click to place re-editable, multiline text; double-click existing text to edit it |
| **Erase**     | Drag over shapes to remove them                                                   |

Pick a stroke color from the palette and set the line width with the slider. **Undo** and **Redo** step through your edits — or press **Cmd/Ctrl+Z** to undo and **Cmd/Ctrl+Shift+Z** (or **Cmd/Ctrl+Y**) to redo. **Clear** removes everything.

Annotate directly on the preview content — circle a misaligned element, mark a target area, or jot a quick note — then click **Save** to composite your strokes onto a preview screenshot and attach the single image to the chat input.

Draw mode works in both the inline pane and the popped-out preview window. From a popped-out window the saved image is forwarded to the main window's chat input automatically.

Because **Save** produces an image attachment, the **Draw** button is disabled when the selected chat model has no vision support — unless you've set a [fallback vision model](/ctor/reference/settings#fallback-vision-model), which describes the annotated screenshot as text.

## CDP and `bricks devtools`

While the preview is running, CTOR starts a CDP server and writes discovery info to `.bricks/devtools.json` in your project directory. The [BRICKS CLI](/cli) reads this file to inspect the running preview from a terminal.

From inside the project directory:

```bash theme={null}
bricks devtools scan        # auto-discover the local preview
bricks devtools brick tree  # walk the brick component tree
```

Run `bricks devtools --help` for the full subcommand list (`brick`, `input`, `network`, `runtime`, `screenshot`, `storage`).

The discovery file is removed when you close the pane.

## Session switching

Switching to a different chat session hides the preview pane if it belongs to another project or session, but does **not** stop the underlying simulator. The pane reappears when you return to the project and session that owns it. Use the pane's **Close** button to stop the simulator when you no longer need it running.