# WoW Forever Map in-page API (`window.forevermap`)

For agents that drive a browser (Playwright, Puppeteer, a browser tool, DevTools). The link format, pin types and UiMap IDs are in [AGENTS.md](https://foreverwowmap.com/AGENTS.md); this page is the JavaScript reference. Every call rewrites the link, so you can always hand the user `getShareUrl()`.

Open https://foreverwowmap.com (add `?agent=1` for the [debug view](#debug-view-and-self-test)) and call `window.forevermap`. The object is frozen, its version is `forevermap.version` (`"1.1.0"`), and `forevermap.help()` lists the methods. The Books layer has its own calls under `forevermap.books` ([Books](#books)), and My pins under `forevermap.pins` ([My pins](#my-pins)).

- **Wait first:** `await forevermap.ready` resolves when the map has started. The map container then has `data-ready="true"`, and a `forevermap:ready` event fires on `window`.
- **Coordinates** are in-game: `{uiMapID, x, y}` with x and y from 0 to 100, as in links. Wherever a `uiMapID` is asked for, a map's name also works (`"Tirisfal Glades"`, `"Undercity"`). A place inside a map, such as `"Brill"`, does not: look it up with `findPlace` or go there with `goTo`. Numbers may be passed as numeric strings (`"61"`). A zoom outside the map's range is clamped to `minZoom` to `maxZoom`.
- **Return values** are plain JSON. Methods marked *async* return a Promise.
- Methods that change the map (*async* or not) return the new **state**: the same object as `getState()`. Most other methods return data. When a change needs a remark, the state also has a `warnings` list of sentences, for example when a label is cleaned for the link. The key is there only when it has something in it.
- **Errors** are thrown as `ForeverMapError` (`forevermap.Error`) with a `code` and a message that says what to do. *Async* methods reject with the same error. The codes are `unknown_map`, `bad_map`, `bad_coords`, `bad_type`, `bad_waypoint`, `bad_index`, `bad_route`, `empty_route`, `bad_import`, `empty_import`, `bad_format`, `unknown_place`, `bad_target`, `unknown_dungeon`, `bad_dungeon`, `bad_floor`, `no_dungeon`, `unknown_layer`, `unavailable`, `bad_faction`, `bad_query`, `bad_scope`, `bad_points`, `bad_pixel`, `bad_mark`, `bad_leg`, `unknown_npc`, `bad_annotation`, `empty_annotations`, `bad_clear` and `unknown_tool`.
- **Waypoint indexes start at 0.** The pins on the map and the list in the sidebar count real stops from 1, and state gives both (`index` and `number`). Route pins (`via`) only bend a leg: they have no number (`number: null`) and the stop after one keeps the next number, so `index` and `number` can differ.

## Reading the state

**`getState()`** returns `{version, ready, url, shareUrl, view, faction, dungeon, route, annotations, pins, find, debug}`:

- `view`: `{uiMapID, name, type, continent, center: {x, y}, zoom, minZoom, maxZoom, bounds: {x0, y0, x1, y1}, size: {width, height}}`. `center` and `bounds` are in-game coordinates on the map shown. `bounds` runs from the top-left to the bottom-right corner of the screen and can go past 0 to 100 when the view is larger than the map.
- `dungeon`: `null`, or the open dungeon (the same shape as `listDungeons()`) with its current `floor`.
- `route`: `{waypoints, legs, warnings, totalYards, pendingLegs, complete, followTerrain, minutesOnFoot, minutesMounted, link}`. `complete` is true once no leg is `pending`. `totalYards` and the minutes leave out rides; the minutes assume Classic speeds: 7 yards a second on foot and 11.2 mounted.
  - `warnings`: sentences about what to fix, each with how: a ride that skips a step (a flight whose next pin is not at a flight master), a leg that found no walking path and why (a pin in water or on a cliff, an unreachable spot), a route pin off walkable ground ([Fixing a route](https://foreverwowmap.com/AGENTS.md#fixing-a-route)).
  - Each waypoint is `{index, number, uiMapID, mapName, x, y, label, type, leg, way}`, where `way` is its `/way` line and `leg` is `auto` or `straight` for the leg into it (`null` on the first).
  - Each leg is `{from, to, mode, kind, yards, straightYards, estimated}`, where `mode` is the leg's setting (`auto` or `straight`). While a leg is `pending` (or `straight`), `yards` is the straight-line distance and `estimated` is true, so call `waitForPaths()` before you trust lengths. A walked leg is measured along the walking grid, so for a short, clear leg it can come out a few yards under the straight line. `kind` is one of:
    - `walk`: follows the terrain.
    - `ride`: the leg out of a travel pin (`f`): the flight, boat or zeppelin, drawn dotted. `yards` is the straight line.
    - `straight`: the leg is set to straight, terrain following is off, or no path was found.
    - `pending`: the path is still being computed.
    - `other-continent`: the leg is a boat, zeppelin or flight between continents, drawn as a ride, and `yards` is `null`.
- `annotations`: the [annotations](#annotations) on the map shown, as `getAnnotations().annotations`.
- `pins`: the user's [pins](#my-pins), as `pins.list()`.
- `find`: `null`, or the NPC search currently shown, as `{label, all, count, only}`. `only` is the NPC name while `showOnlyNpc` (or `n=` in the link) shows just that NPC, else `null`.
- `shareUrl`: the link to give the user. It never includes `?agent=1` or `?preview=1`.

```js
await forevermap.ready;
const s = forevermap.getState();
console.log(s.view.name, s.view.center, s.route.totalYards);
```

## Moving the view

| Method | What it does | Returns |
|---|---|---|
| `goTo(target, {zoom?, open?})` *async* | Shows a map or a place. `target` can be a UiMap ID (`1420`), a name (`"Brill"`, `"Orgrimmar"`, `"Wailing Caverns"`) or `{uiMapID, x, y, zoom}`. A place name centres on it at zoom 5. With `open: true`, a dungeon name opens its map. | state |
| `setView({uiMapID, x?, y?, zoom?})` *async* | The exact view: the map, then optionally the centre (in-game x, y) and zoom. Without x and y it frames the whole map. | state |
| `fitTo(points \| "route" \| "annotations", {padding?, maxZoom?})` *async* | Frames a list of `{uiMapID, x, y}`, the route, or the world map's annotations. The view's map, and with it the coordinates of `center`, `bounds` and the debug grid, becomes the zone most of the points are in (a city counts as its zone unless every point is in that city). | state |
| `fitRoute()` *async* | The same as `fitTo("route")`. | state |
| `zoomIn(step = 0.75)`, `zoomOut(step = 0.75)` *async* | Zooms around the centre. | state |
| `listMaps({query?, type?, parent?})` | Maps with their IDs. `type` is `world`, `continent`, `zone`, `city` or `orphan`. | `[{uiMapID, name, type, parent}]` |
| `findPlace(query, {limit = 10})` | Searches places by name: zones, cities, towns, named caves, dungeons, raids and flight masters. Caves are found once their data has loaded, a few seconds after `ready`. | `[{name, kind, label, uiMapID, x, y, dungeonId, faction}]` (`x` and `y` are `null` for whole maps) |

```js
await forevermap.goTo("Brill");                                // Tirisfal Glades, centred on Brill
await forevermap.setView({ uiMapID: 1458, x: 63.1, y: 48.3, zoom: 6.5 });
forevermap.findPlace("razor hill")[0];                         // {name: "Razor Hill", uiMapID: 1411, x: 52.63, y: 42.43, ...}
```

## Dungeons and raids

| Method | What it does | Returns |
|---|---|---|
| `listDungeons({kind?})` | Every dungeon and raid. `kind` is `dungeon` or `raid`. `bosses` and `insideEntrances` carry [floor coordinates](#dungeon-marks): use them as landmarks. `spots` are hand-placed points such as the possible spawn spots of a quest item (Ruins of Lordaeron's Crest of Lordaeron, Lower Blackrock Spire's Important Blackrock Documents), the objects a quest or event needs (Molten Core's runes, Sunken Temple's statues in their order, Stratholme's postboxes, Dire Maul West's pylons) or a secret's steps (Scarlet Monastery's Scarlet Banner), with their world position in yards and a `confidence` (`high`, `medium`, `low`); `spotNotes` explains each group. | `[{id, name, kind, levels, zone, zoneName, entrance: {uiMapID, x, y}, floors: [{uiMapID, number, name, width, height, yards}], hasMap, bosses: [{name, order, floor, x, y}], insideEntrances: [{floor, x, y, note}], spots: [{group, title, n, name, floor, x, y, worldX, worldY, confidence, where}], spotNotes: {group: note}}]` |
| `openDungeon(idOrName, {floor?})` *async* | Opens a dungeon map (link `#d=<id>`). `floor` is a floor's uiMapID, its name, or its number counting from 1. Dungeons with `hasMap: false` show a "No map available" panel with their bosses. | state |
| `setFloor(floor)` *async* | Switches floors in the open dungeon. | state |
| `closeDungeon()` *async* | Goes back to the dungeon's zone. | state |


## Annotations

Areas, circles and paths drawn on the map: where quest mobs are, a spot with a radius, the path a mob or NPC patrols. They belong to **the map shown**: on the world map they use in-game coordinates on a `uiMapID`; while a dungeon is open they use its [floor coordinates](#dungeon-marks), and its marks (numbered pins joined by arrows) are annotations of kind `mark`. In the link they are the `a=` part (marks in a dungeon: `k=`) ([AGENTS.md](https://foreverwowmap.com/AGENTS.md#annotations-areas-circles-and-paths)).

| Method | What it does | Returns |
|---|---|---|
| `getAnnotations()` | The annotations on the map shown. In a dungeon the marks come first, in order, then the shapes. | `{on: "world" \| "dungeon", dungeon, floor, annotations, link}` |
| `setAnnotations(list, {dungeon?})` *async* | Replaces them. With `dungeon`, opens that dungeon first. | state |
| `addAnnotation(a, {index?})` | Adds one at the end, or before `index`. | state |
| `updateAnnotation(index, patch)` | Changes any of its fields. | state |
| `removeAnnotation(index)`, `clearAnnotations()` | Removes one, or all of them on the map shown. | state |

An annotation is one of:

| `kind` | Fields |
|---|---|
| `area` | `points: [{x, y}, ...]` (3 or more corners; `[x, y]` pairs also work) |
| `circle` | `center: {x, y}` (or `x`, `y`) and `radius`, in the same units as x (0 to 100 across the map) |
| `path` | `points` (2 or more), drawn with arrows in their order; `loop: true` goes back to the start (a patrol) |
| `mark` | Dungeons only: `{x, y, floor?, label?, type?, arrow?}` as in [Dungeon marks](#dungeon-marks) |

Every kind also takes `label`, and the shapes take `color` (`green`, `red`, `orange`, `gold`, `blue`, `purple`, `pink`, `teal`, `white`, `black` or 0-9; areas and circles are red by default, paths orange). On the world map, `uiMapID` (a zone, city or continent, by ID or name) is the map of the points, by default the zone or city shown; in a dungeon, `floor` defaults to the floor shown. Read back, each one also has its `index`, and `mapName` or `floorNumber`.

```js
await forevermap.setView({ uiMapID: 1420, x: 60, y: 51, zoom: 5.5 });
await forevermap.setAnnotations([
  { kind: "area", uiMapID: 1420, points: [{x: 58, y: 50}, {x: 62, y: 50}, {x: 62, y: 54}, {x: 58, y: 54}], label: "Zombies" },
  { kind: "path", uiMapID: 1420, points: [{x: 60, y: 48}, {x: 63, y: 49}, {x: 62, y: 52}], loop: true, color: "purple", label: "Patrol" },
]);
forevermap.getShareUrl();   // https://foreverwowmap.com/#m=1420&v=60,51,5.5&a=1420a:58,50,62,50,62,54,58,54:Zombies;1420l5:60,48,63,49,62,52:Patrol&o=... (then the layers)
```

## Dungeon marks

Marks use floor coordinates and the `k=` part of the link ([AGENTS.md](https://foreverwowmap.com/AGENTS.md#dungeon-marks-and-annotations)). The annotation methods above handle them (kind `mark`); these older calls work on the marks alone:

| Method | What it does | Returns |
|---|---|---|
| `getDungeonMarks()` | The marks on the open dungeon. | `{dungeon, floor, marks: [{index, number, floor, floorNumber, floorName, x, y, label, type, arrow, yards}], link}` |
| `setDungeonMarks(marks, {dungeon?})` *async* | Replaces the marks. Each is `{x, y, floor?, label?, type?, arrow?}`; `floor` defaults to the floor shown. With `dungeon`, opens that dungeon first. | state |
| `addDungeonMark(mark, {index?})` | Adds a mark at the end, or before `index`. | state |
| `updateDungeonMark(index, patch)` | Changes any of `x`, `y`, `floor`, `label`, `type`, `arrow`. | state |
| `removeDungeonMark(index)`, `clearDungeonMarks()` | Removes one mark, or all of them. | state |
| `dungeonPointToPixel({x, y, floor?})` | Where floor coordinates are on screen, on the floor shown (`pointToPixel` does the same while a dungeon is open). | `{x, y, pageX, pageY, visible}` |
| `dungeonPixelToPoint({x, y} \| {pageX, pageY})` | The floor coordinates under a screen position. | `{dungeon, floor, floorNumber, x, y, onFloor}` |

`getState().dungeon.marks` holds the same marks, and `getShareUrl()` returns the dungeon link with them and the dungeon's shapes.

**Placing marks accurately.** Floor coordinates are new, so check your marks against the picture instead of guessing:

1. Open the dungeon and turn on the [debug view](#debug-view-and-self-test) (`setDebug(true)` or `?agent=1`). It draws the floor's grid (x and y every 10, every 5 when zoomed in) over the map and shows the floor coordinates under the cursor.
2. Take a screenshot, find the spot (a room, a bridge, a boss), and read its coordinates off the grid, or pass its pixel position to `dungeonPixelToPoint`.
3. Set the marks, take another screenshot, and check that each one sits where you meant. Move it with `updateDungeonMark` if not.

## Routes

| Method | What it does | Returns |
|---|---|---|
| `getRoute()` | The route only. | `state.route` |
| `setRoute(waypoints, {fit = true})` | Replaces the route. Each waypoint is `{uiMapID, x, y, label?, type?, leg?, npc?}`: `type` is a [pin type](https://foreverwowmap.com/AGENTS.md#pin-types) name or letter, `leg` (`auto` or `straight`) is how the leg into it is drawn, and `npc` is an [NPC ID](https://foreverwowmap.com/AGENTS.md#npc-stops). `{npc, label?, type?, leg?}` without `uiMapID`, `x` and `y` puts the stop at that NPC. | state, or a Promise of it when an NPC stop has no coordinates |
| `addWaypoint(waypoint, {index?, fit?})` | Adds a waypoint at the end, or before `index`. Takes `{npc}` alone like `setRoute`. | as `setRoute` |
| `updateWaypoint(index, patch)` | Changes any of `uiMapID`, `x`, `y`, `label`, `type`, `leg`, `npc`. `{npc}` alone moves the stop to that NPC. | as `setRoute` |
| `setLeg(to, "auto" \| "straight")` | Draws the leg that ends at waypoint `to` (1 or more) as an auto route or a straight line. | state |
| `removeWaypoint(index)` | Removes one waypoint. | state |
| `moveWaypoint(from, to)` | Reorders. | state |
| `reverseRoute()`, `clearRoute()` | Reverses or empties the route. Reversing keeps each straight leg straight. | state |
| `importRoute(input, {append?, fit = true})` | Loads a route link, the `r=` form, `/way` lines, a JSON string, or a route object or array. | state |
| `exportRoute(format = "json")` | `"json"` (the route file object), `"link"` (full URL, with the [layers](https://foreverwowmap.com/AGENTS.md#layers-in-the-link)), `"hash"` (`#r=...` with the layers), `"way"` (`/way` lines), or `"readable"` (`r=...`, the route part alone). | object or string |
| `getShareUrl()` | The link to give the user: the open dungeon (with its marks and annotations), else the route, else the view. Route and view links carry the [annotations](#annotations) and the [layer selection](https://foreverwowmap.com/AGENTS.md#layers-in-the-link). | string |
| `clear(what)` | Clears any of `"route"`, `"annotations"` (on the map shown), `"pins"`, `"npcs"` (the NPC search) and `"layers"` (every layer off); a list, or `"all"`. | state |
| `waitForPaths({timeout = 20000})` *async* | Computes the walking path of every leg, on every continent, and waits for them. Call it before reading leg lengths. | `state.route` |
| `setFollowTerrain(on)` | Turns paths that follow the terrain on or off (straight lines). Auto legs prefer the roads the map knows; see [Fixing a route](https://foreverwowmap.com/AGENTS.md#fixing-a-route) for their limits. | state |
| `listPinTypes()` | The 9 pin types. | `[{type, code, label, symbol}]` |
| `setDebug(on = true)` | Turns the [debug view](#debug-view-and-self-test) on or off. | state |

Labels are stored in the link as letters, digits and spaces. Other characters are dropped, and the call adds a warning when that happens.

**NPC stops.** A waypoint with `npc` (the ID in `wowhead.com/forever/npc=<id>`) is that NPC: the route list and popup show its name and Wowhead link, and its `/way` line carries the name. Without coordinates the page places it at the NPC's spawn nearest the stop before it, and the call returns a Promise (always `await` route calls). In `state.route.waypoints` an NPC stop has `npc`, `npcName`, `wowhead` and `placedFromData`. An NPC the map's data can't place is left out, with a sentence in `warnings` saying so: then give its coordinates.

```js
await forevermap.setRoute([
  { npc: 1568, type: "quest" },                                  // Undertaker Mordo, placed from the data
  { uiMapID: 1420, x: 61.72, y: 52.05, label: "Brill inn", npc: 5688 },  // Innkeeper Renee, at these coordinates
]);
```

```js
await forevermap.ready;
forevermap.setRoute([
  { uiMapID: 1458, x: 63.10, y: 48.30, label: "Undercity" },
  { uiMapID: 1420, x: 60.97, y: 52.70, label: "Brill", type: "quest" },
  { uiMapID: 1421, x: 45.60, y: 42.40, label: "The Sepulcher" },
]);
const r = await forevermap.waitForPaths();
r.legs.map(l => `${l.from + 1}→${l.to + 1}: ${l.kind} ${l.yards} yd`);
forevermap.getShareUrl();   // https://foreverwowmap.com/#r=1458:63.1,48.3:Undercity;1420q:60.97,52.7:Brill;1421:45.6,42.4:The+Sepulcher&o=...
```

## Layers and faction

| Method | What it does | Returns |
|---|---|---|
| `listLayers({all?})` | The layer keys and whether each is on. | `[{key, label, on, group}]` |
| `setLayer(key, on = true)` *async* | Turns one layer on or off. | that layer, or `null` |
| `setLayers({key: bool, ...})` or `setLayers({only: [keys]})` *async* | Sets several layers at once, or shows only the ones listed. | all layers |
| `setFaction("both" \| "horde" \| "alliance")` | Filters flight masters, transport and NPCs by faction. | state |

Layers and faction go into the share link ([Layers in the link](https://foreverwowmap.com/AGENTS.md#layers-in-the-link)). To show a quest, for example: build the route (a `quest` waypoint marks the giver), then give the user `getShareUrl()`. To point at one quest giver, `showOnlyNpc(name)` puts `n=<name>` in the link.

The layer keys are:

- Overlays: `flight`, `boat` (boats, zeppelins and portals), `dungeon`, `raid`, `zones` (zone names), `places` (cities and towns) and `caves` (cave, mine, den, crypt and barrow entrances, one pin per entrance; off by default).
- The `boat` overlay draws each route as a line: colour by side (Horde red, Alliance blue, both gold), dash by ride (boat dashed, zeppelin dotted, portal dash-dot, tram solid). Boats follow the sea round the coasts.
- The Azeroth view (947) draws the two continents closer together than the game does. Coordinates on 947 that you pass in or get back are still the game's own; the page converts them.
- The user's own pin layers: `mine:<layer name>`.
- Services: `npc:<category>`, where the category is `inn`, `bank`, `auction`, `mail`, `battle`, `stable`, `spirit`, `classtrainer`, `proftrainer`, `repair`, `reagent`, `poison`, `food` or `vendor`. One selection applies everywhere, cities included. Quest givers are not a layer: find them with `findNpcs("Quest giver")` or by name with `showOnlyNpc(name)`. An old link with `quest` in its `--s` group still opens; that key is ignored.
- Mobs: `mob:elite`, `mob:rare` and `mob:rareelite`: elite, rare and rare elite mobs out in the world (not inside dungeons), one pin per group of spawns. Elites friendly to a faction (guards) are left out.
- Gathering: `gather:herbalism`, `gather:mining`, `gather:containers`, `gather:fishing`, `gather:fish_catch` and `gather:skyborne` (ley lines and elemental convergences, for the Skyborne racials), or a single node type from `listLayers({all: true})` once the gathering data has loaded.

## Finding NPCs

| Method | What it does | Returns |
|---|---|---|
| `listNpcSearches()` | The ready-made searches, the same list as the round finder button. | `[{group, option, name}]` |
| `findNpcs(query, {scope = "map", faction?, show = true, limit = 100})` | Finds NPCs by service (`"Cooking supplies"`, `"Innkeeper"`, `"Mage trainers"`, `"Alchemy supplies"`) or by part of a name or title. `scope` is `"map"` (the zone or city shown), `"continent"` or `"all"`. With `show`, they are marked on the map as the finder does. | `{query, matched, label, scope, faction, in, total, shown, results: [{name, title, category, npcId, wowhead, uiMapID, mapName, x, y, faction}]}` |
| `showOnlyNpc(nameOrId)` | Shows only one named NPC: every spawn with that name (or that NPC ID) is marked, the service layers are hidden, and the map flies there, switching continent if needed. The link gets `n=<name>`. Searching a service with `findNpcs` still shows every NPC of that kind. | `{name, token, total, shareUrl, results: [{name, title, npcId, uiMapID, mapName, x, y}]}` |
| `clearNpcs()` | Removes the markers and ends `showOnlyNpc`, so the layers show again. | state |

## Screen coordinates

| Method | What it does | Returns |
|---|---|---|
| `mapToPixel({uiMapID, x, y})` | Where in-game coordinates are on screen. `x` and `y` are pixels inside the map element. `pageX` and `pageY` are viewport pixels, ready for a mouse click. Returns `null` when the point is on another continent than the one shown. | `{x, y, pageX, pageY, inView}` |
| `pixelToMap({x, y} \| {pageX, pageY})` | The in-game coordinates under a screen position: the city or zone there, or the continent. | `{uiMapID, name, x, y}` |
| `pointToPixel(p)`, `pixelToPoint(p)` | The same for the map shown: `mapToPixel` and `pixelToMap` on the world map, `dungeonPointToPixel` and `dungeonPixelToPoint` while a dungeon is open. | as those |

## Tools, schema and WebMCP

The same features as tools with JSON input, for agents that call tools rather than write JavaScript. `forevermap.schema()` returns them as `[{name, description, inputSchema}]`, and `await forevermap.call(name, args)` runs one. The coordinates are those of the map shown: in-game on the world map, floor coordinates while a dungeon is open.

| Job | Tools |
|---|---|
| Read | `get_state`, `get_share_url` (the link to give the user) |
| Move and look up | `go_to` (a place, map, coordinates, or `fit: "route"` / `"annotations"`), `find_place`, `list_maps` |
| Dungeons | `list_dungeons`, `open_dungeon` (also switches floor), `close_dungeon` |
| Route | `set_route` (`waypoints`, or `input` to import a link, /way lines or JSON; `append`), `add_waypoint`, `update_waypoint` (also the leg: `auto` or `straight`), `remove_waypoint`, `move_waypoint` (or `reverse: true`), `wait_for_paths`, `export_route` |
| Annotations | `get_annotations`, `set_annotations`, `add_annotation`, `update_annotation`, `remove_annotation`: areas, circles and paths, and dungeon marks |
| My pins | `set_pins` (replace, or `append`) |
| Clear | `clear` with `what`: any of `route`, `annotations`, `pins`, `npcs`, `layers` |
| Layers | `list_layers`, `set_layers` (`on`, `off`, `only` lists of keys, and `faction`) |
| NPCs | `find_npcs`, `show_only_npc` |
| Screenshots | `point_to_pixel`, `pixel_to_point`, `set_debug` |

Tools return what the matching method returns, mostly the [state](#reading-the-state). Names from version 1.0 still work with `call`: `import_route`, `clear_route`, `set_leg`, `set_faction`, `map_to_pixel`, `pixel_to_map`, and the `*_dungeon_mark*` and `dungeon_*` tools; `set_layers` still takes `{changes}`.

**WebMCP:** when the browser exposes `navigator.modelContext` (or the older `document.modelContext`), the page registers the same tools there, prefixed `forevermap_` (for example `forevermap_set_route`). They return their result as JSON text, and errors come back as `isError` with `{error, message}`. Without WebMCP, nothing is registered.

## The page without the API

Every feature is also a real control, which you can find by its `data-testid`:

| Test id | Control |
|---|---|
| `map` | The map (carries `data-ready`) |
| `place-search`, `place-results` | Place search and its results |
| `tab-overlays`, `tab-routes` | The sidebar tabs |
| `route-add`, `route-list`, `route-summary`, `route-link` | The route: adding waypoints, the waypoint list with coordinates and leg lengths, the summary and the link |
| `route-copy-link`, `route-copy-json`, `route-copy-way` | Export: copy the link, the JSON or the `/way` lines |
| `route-import-text`, `route-import` | Import |
| `npc-finder`, `npc-search`, `npc-results`, `npc-status` | The NPC finder |
| `faction`, `zoom-in`, `zoom-out`, `map-up`, `breadcrumb`, `cursor-coords` | Faction filter, zoom and up buttons, map path, coordinates under the cursor |
| `dungeon`, `dungeon-floor`, `dungeon-back` | The dungeon map |

Each waypoint pin's `title` attribute holds its number, type, label, map and coordinates, and the route summary is an `aria-live` region.

## Debug view and self-test

Add `?agent=1` before the `#`, for example `https://foreverwowmap.com/?agent=1#m=1420`, or call `forevermap.setDebug(true)`. The view then shows:

- A cyan coordinate grid over the zone or city shown, every 10 (finer when zoomed in), labelled `x10`, `y20`, and so on along the edges.
- Large magenta numbers on the waypoint pins, and a thicker magenta path.
- A panel at the bottom left with the map, centre, zoom, visible coordinate range, the waypoints and coordinates, and the coordinates under the cursor.
- On a dungeon map: the floor's grid in [floor coordinates](#dungeon-marks), the marks in the panel, and the floor coordinates under the cursor.

To check your own work:

1. Build the route with the API (or open your link), then `await forevermap.waitForPaths()`.
2. Read back `getState().route`. Check the waypoint count, the order, that no leg is `pending`, and the `totalYards`.
3. Turn on the debug view, call `fitTo("route")`, and take a screenshot. The pins are numbered, and the grid is drawn over the zone that holds most of the pins, so you can read their coordinates off it. For pins in another zone, `setView({uiMapID})` to that zone first. The state panel sits at the bottom left, so allow some `padding` if a pin hides behind it.
4. Use `mapToPixel` to find where a waypoint should be drawn, and compare it with the screenshot. Waypoints at the same spot (a quest picked up and handed in at one NPC) are drawn side by side, or in a ring for three or more, each tethered to a dot at its true point; their coordinates are unchanged.
5. Give the user `getShareUrl()`. Open it in a fresh tab to confirm that it reproduces the route.

Without a browser, render the link with `preview.py` instead ([NO-BROWSER.md](https://foreverwowmap.com/NO-BROWSER.md)).

## My pins

The user's own markers ([link format](https://foreverwowmap.com/AGENTS.md#my-pins)). Every change rewrites the link.

| Call | Does |
|---|---|
| `list()` | Pins as `{uiMapID, x, y, note, layer, icon, color}`, with the colour as a name. |
| `add(pin, ...)` | Adds pins (only `uiMapID`, `x` and `y` required; `color` a name or 0-9). Returns the last pin's index. |
| `update(i, fields)` | Changes pin `i` (0-based). Returns the pin. |
| `remove(i)` | Removes pin `i`. Returns how many are left. |
| `set(pins)` / `clear()` | Replaces all pins, or removes them. |
| `icons(query?)` | Icon IDs: `{id, name, group, colorable}`, fuzzy-searched when given a query (`icons("lotus")`). |
| `colors()` | Colour names in digit order. |
| `link()` / `json()` | The share link, or `{format: "foreverwowmap-pins", version: 1, link, pins}`. |

Bad input throws a `ForeverMapError` with code `bad_pin`, `bad_pins`, `unknown_map`, `bad_coords`, `unknown_icon`, `unknown_color` or `bad_index`.

## Books

The Books layer (`o=books` in the link): 40 books and scrolls at 41 spots. Collected books are saved in the visitor's browser.

| Call | Does |
|---|---|
| `list()` | Every book: `{id, name, faction, collected, spots: [{uiMapID, x, y, kind, where}]}`. `where` says in a sentence where the book sits at that spot (building, floor, cave, nearby danger). `faction` is `alliance`, `horde` or `both`: the Season of Discovery faction, not confirmed in Forever, so the map shows every book whatever the Travel faction is; `kind` is `exact`, `reference` (approximate), `entrance` (cave entrance; the book is inside) or `uncertain` (not confirmed in Forever). |
| `collected()` | IDs of the collected books. |
| `setCollected(id, on = true)` | Mark a book collected or not. Returns `false` for an unknown ID. |
| `show(on = true)` | Turn the layer on or off. |
| `hideCollected(on = true)` | Hide or show collected books' pins. |
| `focus(id)` | Turn the layer on, fly to the book and open its popup. |
| `state()` | `{shown, hideCollected, collected, total, pinsOnMap}`. |

To send someone to books without the page, make a route link from `list()`'s spots, for example `#r=1452k:60.7,37.7:Ka-Boom` (Everlook, Winterspring).

## Import and export (JSON)

`importRoute` and the Route planner tab accept a route link, the `r=` form, TomTom `/way` lines (`/way #1420 60.97 52.70 Brill`), a bare array of waypoints, or the route file:

```json
{
  "type": "object",
  "required": ["waypoints"],
  "properties": {
    "format": {"const": "foreverwowmap-route"},
    "version": {"const": 1},
    "waypoints": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["uiMapID", "x", "y"],
        "properties": {
          "uiMapID": {"type": "integer"},
          "x": {"type": "number", "minimum": 0, "maximum": 100},
          "y": {"type": "number", "minimum": 0, "maximum": 100},
          "label": {"type": "string"},
          "type": {"enum": ["quest", "turnin", "goto", "kill", "interact", "travel", "hearth", "note", "via"], "default": "goto"},
          "leg": {"enum": ["auto", "straight"], "default": "auto", "description": "How the leg into this waypoint is drawn"}
        }
      }
    }
  }
}
```
