# Previews and annotations

A run can share the app it is building, running on its machine, as a **preview** link on its card. Open it to try
the change before you merge it. Then **Annotate** a frame of it: drop pins and boxes where something should change,
and send them to the agent as one reply.

## Turn previews on for a machine

Previews, and the board's direct terminal, need a tunnel on the machine: **Tailscale** or a **Cloudflare quick
tunnel**. The machine's setup asks once; the default is no tunnel.

| | Tailscale | Cloudflare quick tunnel |
|---|---|---|
| Who can open a preview | devices on your tailnet. A phone or iPad needs the Tailscale app | anyone with the link. The link carries a token; without it the page refuses |
| Account | a Tailscale account, with HTTPS certificates on | none |
| Address | `https://<machine>.<tailnet>.ts.net:<port>`, the same every time | a new `https://<words>.trycloudflare.com` for each preview |
| Terminal | the board on a tailnet device opens it directly; elsewhere it goes through the server | the board opens it directly from anywhere |

On the machine:

1. Run `andon tunnel tailscale` or `andon tunnel cloudflare`.
   - **Tailscale**: install it and sign in first. Turn on MagicDNS and HTTPS certificates on the DNS page of the
     Tailscale admin console. On Linux, let your user configure serve once: `sudo tailscale set --operator=$USER`.
   - **Cloudflare**: the command installs `cloudflared` with Homebrew when it's missing. Quick tunnels need no
     account, and Cloudflare gives them no uptime guarantee.
2. Check it with `andon tunnel status` and `andon doctor`.

The board opens a terminal directly only on a machine whose agent is current; an older agent's terminal goes through
the server. Your sign-in never goes to the machine: the board asks the server for a one-time pass for each terminal
it opens.

`andon tunnel off` turns previews off. `--no-terminal` keeps previews but leaves the terminal off the tunnel. See
[The `andon` command](https://andon-docs.pages.dev/reference/cli.md) for every flag.

## Open a preview

When a run starts its app, the link shows on the card as *Preview · …*. Click it to open the app in a new tab. The
link closes when the run's session ends.

A run shares only its own app: a port a process it started listens on, one working in the run's workspace. The
machine's other servers, another run's app and a port Docker forwards stay off the tunnel. The machine tells whose
a port is with `lsof`, so a port preview needs a Mac or Linux machine.

The app is sent only the cookies it set itself. Your board sign-in, and other previews' links, never reach it, even
where the board and the machine share an address. A cookie the app's page sets in script alone isn't sent.

An app with no port to share, such as an iOS Simulator, an Android emulator or a macOS app window, shows as a picture
of its screen instead: *Preview · iOS Simulator*, *Preview · Android* or *Preview · <app> window*. It refreshes about
twice a second while someone has it open. You can look, but not click. A window shows only an app the run built in
its workspace or started itself, never another app on the machine.

## Annotate a preview

Only the card's owner annotates.

1. Click **Annotate** on the preview link. Andon asks the run's machine for a frame of the page, at the size of your
   window. **New frame** asks for another.
2. Click to drop a numbered pin, or drag to draw a box. On a phone or iPad, tap for a pin, or press and hold, then
   drag, for a box.
3. Type a note for each one. Paste an image into a note to add a reference picture.
4. Click **Request changes**. The open annotations go to the run as one reply, with the marked frame. A run that has
   ended continues in its session.

The notes sit beside the frame, or below it on a narrow screen, with who wrote them and when. Each has **Resolve**,
**Reopen** and delete, with Undo for 10 seconds.

When the agent has made its changes, take a **New frame**. Earlier pins show faded on it, marked *drawn on an earlier
frame*, so you can check each one. A frame of another size lists them without placing them.

### When the machine can't take a frame

The dialog says why: no Chrome or Chromium on the machine, the preview closed with its session, the machine offline
or its agent too old, or a machine someone else owns. Paste, drop or pick a screenshot instead and annotate that.

A web frame is the top of the page the link opens on. On a web preview, each pin also tells the agent which element
it is on, unless the app forbids inline scripts or refuses to be framed.

### Approve

**Approve** says the change looks right. It resolves the annotations that were sent. Ones you never sent stay as
they are, unless you tick them to make a follow-up card of each.

## Annotate a picture

An image the run made, or an image attached to the card, has **Annotate** in its lightbox too. It works the same way.

## Reviews look at the picture too

A review round of a change you can see can start the app, capture it, and report what's wrong on a frame. Its
findings show as pins on that frame, signed *Andon review · round 2*, beside yours. A blocked one is answered on the
board like any finding: **Fix it**, **I handled it**, **Leave as is** or **Follow-up card**. See
[Pull requests: review and merge](https://andon-docs.pages.dev/guide/review-and-merge.md#review-rounds).

The review's browser only reads the preview: it doesn't click, fill in forms, sign in or leave the preview's own
pages.
