# 7. Locators and annotations

> How a place in a book, and a highlight, is recorded so that every device finds it.

Canonical: https://boeks.app/docs/specs/locators

Locations in a book are [Readium Locators](https://readium.org/architecture/models/locators/), and annotations are modeled on [W3C Web Annotations](https://www.w3.org/TR/annotation-model/), with a Locator as their target and the note as a Markdown string, rather than the model's selectors and body resources. Exporting them as W3C annotations maps the Locator's quote to a `TextQuoteSelector`, as [Readium Annotations](https://github.com/readium/annotations) does.

Progress, as `progress.updated` logs it (§5.3). It's a point, so its quote is the text after it:

```json
{
  "edition": "01j9xk2m4n6p8q0r2s4t6v8w0y",
  "locator": {
    "href": "OEBPS/chapter-03.xhtml",
    "type": "application/xhtml+xml",
    "locations": {
      "progression": 0.42,
      "totalProgression": 0.18,
      "x-koreader-xpointer": "/body/DocFragment[5]/body/p[12]/text().0"
    },
    "text": {
      "before": "said the Reverend Mother. ",
      "highlight": "",
      "after": "He who controls the spice"
    }
  }
}
```

**Locators:**

- **Fields** are Readium's: `href`, `type`, `locations {progression, totalProgression, position, fragments, partialCfi, domRange}`, and `text {before, highlight, after}`.
- **Every stored Locator has** `href` and `progression`, and a `text` quote whenever there's text at the location (an image has none), and is stored with the ID of its `edition`. Everything else is optional.
- **The quote:** `highlight` is the selected text, empty or left out for a point, such as a bookmark, and `before` and `after` are up to 32 characters each, counted as below.
- **An audiobook's progress** is a Locator into its audio file, with its time in `fragments` as `t=` seconds, and no quote (§9).
- **A writer that can't get the quote from its renderer** takes the text at `progression` in the resource, from the first word that starts there or after.
- **Each reader converts its renderer's locations** to and from Locators.
- **A resource's text** is its `<body>`'s text as the DOM's `textContent` gives it, without `<script>` and `<style>`. `progression` is where the location is in it, in characters, divided by its length.
- **`href`** is the resource's path from the EPUB's root, without a leading `/`, percent-encoded as a URL path is: every byte but ASCII letters, digits, and `-._~/` as `%XX`, in uppercase hex. Readers decode it before comparing. An audiobook's is its file's name in the edition's folder (§9), encoded the same way.
- **Counting:** offsets and `progression` count the characters of a resource's text, with these rules:
  - a character is a Unicode scalar value (a code point that isn't a surrogate), not a UTF-16 unit or a byte: in JavaScript, count `[...text]`, not `text.length`
  - runs of whitespace collapsed to one space, and the ends trimmed. Whitespace is Unicode's `White_Space` property, so a no-break space (U+00A0) is whitespace too, which Lua's `%s` doesn't match
  - C1 control characters (U+0080–U+009F) read as the Windows-1252 characters they stand for, as HTML parsers read the reference `&#128;` as "€" where XML keeps the control character. This is the format's normalization, for counting; renderers needn't agree on it. The five with none (U+0081, U+008D, U+008F, U+0090, U+009D) stay as they are, one character each
- **The quote is what has to match,** not the offset: renderers extract text differently, so offsets from two renderers can differ for the same place. A web view's `textContent` has no break between `</p><p>`, for example, where crengine puts a newline.
- **Renderer extras** go in `locations` with an `x-` prefix: KOReader's crengine XPointers (`x-koreader-xpointer`, `x-koreader-xpointer-end`), the kepub span Kobo's reader saves (`x-kobo-span`, such as `kobo.108.1`), and a reader's own offsets. They're hints for the same edition: use one only if the text at it still matches the quote.
- **A page** is a Readium position, as Readium's `ArchiveEntryLength` strategy counts them, with 1,024 bytes: one for every 1,024 bytes of each resource in the reading order, as compressed in the EPUB, rounded up, or one per resource in a fixed-layout edition. Every resource in the spine counts, `linear="no"` ones too, each with at least one position and at most 100,000. They're numbered from 1 through the edition, as `position` has it. It's the same on every device and in any layout, though not after the EPUB is zipped again with other compression, and an edition's page count is its number of positions. A page a renderer lays out on screen is only shown, never stored or counted.

**Annotations:**

- **Shape:** `target` is a Locator into the annotation's `edition`; `body` is the note; and `motivation` is `highlighting` or `bookmarking`. A highlight with a note is still `highlighting`: the note is its `body`.
- **Re-anchoring** looks in the Locator's resource for each place its `highlight` is, or for a point, its `before` and `after` together, else either alone. Of those, the one whose surroundings agree with `before` and `after` over the most characters wins, then the one nearest `progression`; with none, it stays at `progression`, and isn't exact. Finding it by its quote, rather than its offset, is what lets an annotation find its place when the EPUB is replaced by a corrected one. An annotation that can't be anchored is flagged, never dropped.
- **Colors** are yellow, green, blue, pink, and purple. A reader with other colors maps them onto these: red to pink; orange and gray to yellow; olive to green; and cyan to blue.
