# Preview and headset

> Use the live preview, the Scene panel, the emulated headset and number scrubbing, and open your project on a real headset.

Source: https://graspable.dev/docs/preview-and-headset

## The preview

Choose **Preview** or **Split** at the top right of a project. Graspable starts the project's own dev server on your computer and shows it in the app. The preview updates as you or the agent change files. You can return to Code or Compare while it starts; finishing startup will not switch you away from that view.

For web projects, the round-arrow button reloads the preview. It also restarts the dev server if it has stopped. Repeated requests while a preview starts share the same server. Stopping the preview cancels startup too, so it cannot reopen in the background.

Native projects use the capture or simulator control inside their preview pane instead of a web reload.

Starting an agent check leaves an unchanged preview configuration alone, avoiding an unnecessary restart of the preview you are using.

Each preview gets an available local address. Graspable checks both IPv4 and IPv6 loopback ports so another preview does not prevent it from starting. An address already in use during either check is retried automatically. If an address becomes occupied after those checks, during startup, the error remains visible; use the round-arrow button to try a new address.

On Windows and Linux, the ⌥ key in this page is the Alt key.

## The Scene panel

Choose **Scene** in the bar above the preview. A panel lists every object in the running scene, as a tree.

- Click a row to outline that object in the preview and select the code that created it.
- Type in **filter objects…** to narrow the list.
- Hidden objects are dimmed.
- Tick **rig** to also show controllers, hands and pointers.
- Each row shows the file and line the object comes from. Objects that your project's code did not write have none.

## From an object to its code

Hold ⌥ and click an object in the preview. The editor opens the file and selects the code that created the object. The matching row is selected in the Scene panel.

Version 0.19.1 fixes selection when the object comes from a different file: the editor waits for that file before applying its source range. Invalid source coordinates are ignored instead of interrupting editing.

That selection goes with your next request, shown as a chip above the prompt box. So you can ⌥-click a planet and write "make this twice as big".

It works the other way too. Move the cursor in a `.jsx` or `.tsx` file and the objects written on that line are outlined in the preview.

## Scrub a number

In the editor, hold ⌥ over a number and drag left or right. The number changes and the preview follows while you drag. Hold Shift for steps ten times finer. The file is saved when you let go.

Use **Split** to see the code and the preview together.

## The emulated headset

The preview includes an emulated headset, so you can try AR and VR without one. Choose which in the bar above the preview: **Quest 3** (controllers and hands), or **Meta VR Glasses** (aim with your eyes, pinch to select, a narrower view, no controllers). Changing it reloads the preview.

1. Click **Enter AR** or **Enter VR** in the preview.
2. Use the on-screen controls to move the headset and controllers and press their buttons with mouse and keyboard.

For AR, the emulated headset stands in a synthetic room, so placing things on floors and walls works. Pick the room from the menu in the bar above the preview: living room, meeting room, music room, office large or office small.

In AR or VR, a **Talk to the agent** button sits low in front of you. Press it to talk with the agent while you look at the scene: it uses this computer's microphone and reads the agent's answers aloud. See [Voice](https://graspable.dev/docs/voice.md).

The emulated headset exists only in the preview. It is left out when the project is built.

## Captures and the project's picture

**Capture**, in the bar above the preview, takes a picture of what you see in the preview at that moment, from where you stand and look. It is always the same shape, 1280 × 720, whatever the size of the pane: the middle of the view is kept. It is the preview's own frame, not a picture of your screen, and it is instant.

The picture opens before anything is kept. From there you can:

- **Use as the project's picture.** This is the picture lists show for the project and your published app shows on the site. It can be changed once in ten seconds; a published app shows the new one the next time you publish.
- **Keep in Captures**, to have it later.
- **Download** it as a file.
- **Take it again**, after moving to a better spot in the preview.
- **Close**, and nothing is kept.

Until you choose one, the project's picture is taken by itself: it is the app as a person first sees it, from the check the agent runs when it finishes a request.

The **Captures** tab, beside Files and Assets, shows the project's picture and every capture you kept. Open one to download it, make it the project's picture, remove it, or share it: the app writes a short post with the project's name, its address when it is published, and "via graspable.dev", which you can copy or open in X or LinkedIn. Attach the downloaded picture to the post.

Captures are kept in the project on your computer and are sent nowhere. They are not part of the project's files: the agent does not see them and they are not published with the source.

A project made before version 0.13 says its preview cannot take pictures yet and offers **Update it**, which brings the preview's tools up to date.

## Record and replay

1. Enter AR or VR in the preview.
2. Choose **Record**, then use your app.
3. Choose **Stop & save**.

The recording is saved in the project as a file in `tests/xr/`. Choose **replay fixture…** to play one back. After the replay, the bar says whether the scene and the final image match the recording.

Recordings also work as tests. See [XR tests](https://graspable.dev/docs/xr-tests.md).

## Open on a real headset

Choose **Headset** in the bar above the preview. Edits keep hot-reloading on the headset. The headset uses its own WebXR, not the emulated one.

Headset preview is not available for cloud projects. Move the project back to this computer first.

### Same Wi-Fi

1. Choose **Share on Wi-Fi**.
2. Scan the QR code with the headset, or choose **Copy link** and open the link in the headset's browser.
3. The first time, the headset browser warns that the connection is not private. This is expected: the certificate is made on your computer. Choose **Advanced**, then **Proceed**.
4. Choose **Stop sharing** when you are done.

Anyone on your network who has the link sees the preview until you stop sharing. Only the preview is shared. Sharing also stops when the preview stops.

If your computer has more than one network address, a menu under the QR code lets you pick another.

To talk with the agent while you wear the headset, choose **Talk in the headset** under the QR code and scan the new code. In VR or AR, press **Talk to the agent** and speak. The headset listens with its own microphone and plays the agent's answers. See [Voice](https://graspable.dev/docs/voice.md).

### USB (Quest, Pico, Android XR)

USB avoids the certificate warning. It needs two things that Graspable does not install:

- Android platform-tools (`adb`) on your computer.
- Developer mode turned on in the headset.

Then:

1. Plug the headset in with USB.
2. Put the headset on and allow USB debugging for this computer.
3. In the **Headset** panel, choose **Open** next to the headset.

The preview opens in the headset's browser.

If the preview does not open on your headset, see [Troubleshooting](https://graspable.dev/docs/troubleshooting.md).
