# WoW Forever Map without a browser: write a link, then look at it

For agents that can run code but can't drive a browser, and for any agent that wants to see a link before handing it over. Start from [AGENTS.md](https://foreverwowmap.com/AGENTS.md): it says which game data to trust and how links are written.

1. **Write the link** by hand from the [link format](https://foreverwowmap.com/AGENTS.md#link-format).
2. **Render it to a PNG** with [preview.py](https://foreverwowmap.com/preview.py), a script you run on your own machine. It opens the real page in a private headless browser, so the picture is exactly what the user will see, auto-routed paths included ([how](#2-look-at-it)).
3. **Check the picture and the summary**, fix the link, render again ([checklist](#3-check-it)).

There is no image endpoint on the server: the site is static, so the rendering runs where you are.

## 2. Look at it

With [uv](https://docs.astral.sh/uv/) there is nothing to install by hand:

```sh
uv run https://foreverwowmap.com/preview.py "https://foreverwowmap.com/#r=1420q:31.98,64.98:Deathknell;1420t:60.97,52.7:Brill" -o route.png
```

Without uv: `pip install playwright`, download [preview.py](https://foreverwowmap.com/preview.py) and run `python preview.py "<link>" -o route.png`.

It writes the PNG and prints a JSON summary of what the page understood:

```json
{
 "images": ["route.png"],
 "complete": true,
 "view": {"uiMapID": 1420, "name": "Tirisfal Glades", "center": {"x": 46.48, "y": 58.84}, "zoom": 5.45, "bounds": {"x0": 26.17, "y0": 38.53, "x1": 66.75, "y1": 79.11}},
 "route": {"waypoints": [{"number": 1, "uiMapID": 1420, "mapName": "Tirisfal Glades", "x": 31.98, "y": 64.98, "label": "Deathknell", "type": "quest"}],
           "legs": [{"from": 0, "to": 1, "mode": "auto", "kind": "walk", "yards": 1462, "straightYards": 1361}], "totalYards": 1462, "pendingLegs": 0},
 "shareUrl": "https://foreverwowmap.com/#r=1420q:31.98,64.98:Deathknell;1420t:60.97,52.7:Brill&o=..."
}
```

(Shortened. The fields are those of `getState()` in [API.md](https://foreverwowmap.com/API.md#reading-the-state).)

| Option | Does |
|---|---|
| `-o route.png` | Where to write the picture. A route on two continents also writes `route-2.png`, one per continent. |
| `--grid` | The agent debug view: a cyan coordinate grid over the zone, big magenta waypoint numbers and a state panel listing the waypoints. Use it to read coordinates off the picture. |
| `--size 1600x1000` | Viewport in CSS pixels (default 1200x800). |
| `--scale 2` | Sharper picture for a person to look at. |
| `--browser PATH` | Use this Chrome or Chromium. Otherwise the script uses Playwright's Chromium, then an installed Chrome or Edge, and only then downloads Chromium once (about 150 MB). |
| `--base URL` | Render on another copy of the site, such as a local one. |

The link can also be just its fragment: `"#m=1420"`, `"#d=wailing-caverns"`. If the page couldn't read part of the link (a map name it doesn't know, a stop without coordinates), the summary has `linkWarnings` saying which part and why. The picture shows the map alone (no sidebar or buttons), framed the way the page frames the link: a route fits its pins, a view link keeps its centre and zoom.

**In a browser?** Open the link with `?agent=1` and screenshot it instead, or use the [in-page API](https://foreverwowmap.com/API.md). `https://foreverwowmap.com/?preview=1#...` is the same map-alone view the script captures.

## 3. Check it

- The summary lists every waypoint you meant, in order, on the map IDs you meant, and has no `linkWarnings`. Each link warning names the part of the link it couldn't read (or read with a guess, such as a misspelt map name) and what it did instead.
- `route.warnings` is absent. Each warning says what is wrong and how to fix it: a ride that skips a step (a flight that doesn't land at a flight master), a leg with no walking path, a route pin off walkable ground.
- `complete` is true and `pendingLegs` is 0.
- In the picture, the path goes where a player would walk. If it detours around a mountain they can cross, through one they can't, or across country beside a road a player would take, bend it with a route pin ([Fixing a route](https://foreverwowmap.com/AGENTS.md#fixing-a-route)).
- With `--grid`, the pins sit on the coordinates you wrote.
- Give the user the link you wrote (or `shareUrl`).
