# page.cavu.highlight

> Published by [cavu.page](https://lexicon.garden/identity/did:plc:citulkqjdzbnf7wd5xb6lled)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:citulkqjdzbnf7wd5xb6lled/page.cavu.highlight)
- [Documentation](https://lexicon.garden/lexicon/did:plc:citulkqjdzbnf7wd5xb6lled/page.cavu.highlight/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:citulkqjdzbnf7wd5xb6lled/page.cavu.highlight/examples)

## Definitions

### `page.cavu.highlight`

**Type**: `record`

A reader's highlight of a passage in a book, written to the reader's own repo. The passage is anchored by text quote (exact string plus surrounding context), not by DOM position: quotes survive re-rendering, mode switches, and small edits to the chunk, and the strongRef cid marks the text *as highlighted* so drift is detectable. Selector field names and limits deliberately mirror the W3C Web Annotation TextQuoteSelector as used by at.margin.note, so a highlight translates 1:1 into a margin.at annotation target. The book AT-URI makes highlights discoverable by backlink index. Like page.cavu.progress, records are public: clients must disclose that highlights are saved to the reader's own repo.

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `book` | `string` (at-uri) | Yes | AT-URI of the book's site.standard.publication record — the backlink target, and the key clients list by. |
| `note` | `string` | No | The reader's own note on the passage. |
| `color` | `string` | No | Client-chosen highlight color name or hex value. Clients without an opinion omit it. |
| `document` | `ref` → `com.atproto.repo.strongRef` | Yes | Spine document containing the passage, at the cid the reader was seeing. A cid that no longer matches the live record marks a highlight whose ground may have shifted. |
| `selector` | `ref` → `#textQuoteSelector` | Yes | Where in the document's text the highlight lives. |
| `createdAt` | `string` (datetime) | Yes |  |
| `thousandths` | `integer` | No | Coarse position of the passage within the document, in thousandths of its text — page.cavu.progress's position grammar. A jump-to hint only; the selector is authoritative. |

### `page.cavu.highlight#textQuoteSelector`

**Type**: `object`

W3C Web Annotation TextQuoteSelector shape (field names and limits match at.margin.note): the exact quoted text, disambiguated by up to 150 graphemes of context on each side. Offsets are into the document's rendered text content with whitespace as rendered.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `exact` | `string` | Yes | The highlighted text itself. |
| `prefix` | `string` | No | Text immediately before the quote, for disambiguating repeated passages. |
| `suffix` | `string` | No | Text immediately after the quote. |

## Raw Schema

```json
{
  "id": "page.cavu.highlight",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "book",
          "document",
          "selector",
          "createdAt"
        ],
        "properties": {
          "book": {
            "type": "string",
            "format": "at-uri",
            "description": "AT-URI of the book's site.standard.publication record — the backlink target, and the key clients list by."
          },
          "note": {
            "type": "string",
            "maxLength": 10000,
            "description": "The reader's own note on the passage.",
            "maxGraphemes": 3000
          },
          "color": {
            "type": "string",
            "maxLength": 32,
            "description": "Client-chosen highlight color name or hex value. Clients without an opinion omit it."
          },
          "document": {
            "ref": "com.atproto.repo.strongRef",
            "type": "ref",
            "description": "Spine document containing the passage, at the cid the reader was seeing. A cid that no longer matches the live record marks a highlight whose ground may have shifted."
          },
          "selector": {
            "ref": "#textQuoteSelector",
            "type": "ref",
            "description": "Where in the document's text the highlight lives."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "thousandths": {
            "type": "integer",
            "maximum": 1000,
            "minimum": 0,
            "description": "Coarse position of the passage within the document, in thousandths of its text — page.cavu.progress's position grammar. A jump-to hint only; the selector is authoritative."
          }
        }
      },
      "description": "A reader's highlight of a passage in a book, written to the reader's own repo. The passage is anchored by text quote (exact string plus surrounding context), not by DOM position: quotes survive re-rendering, mode switches, and small edits to the chunk, and the strongRef cid marks the text *as highlighted* so drift is detectable. Selector field names and limits deliberately mirror the W3C Web Annotation TextQuoteSelector as used by at.margin.note, so a highlight translates 1:1 into a margin.at annotation target. The book AT-URI makes highlights discoverable by backlink index. Like page.cavu.progress, records are public: clients must disclose that highlights are saved to the reader's own repo."
    },
    "textQuoteSelector": {
      "type": "object",
      "required": [
        "exact"
      ],
      "properties": {
        "exact": {
          "type": "string",
          "maxLength": 5000,
          "description": "The highlighted text itself.",
          "maxGraphemes": 1500
        },
        "prefix": {
          "type": "string",
          "maxLength": 500,
          "description": "Text immediately before the quote, for disambiguating repeated passages.",
          "maxGraphemes": 150
        },
        "suffix": {
          "type": "string",
          "maxLength": 500,
          "description": "Text immediately after the quote.",
          "maxGraphemes": 150
        }
      },
      "description": "W3C Web Annotation TextQuoteSelector shape (field names and limits match at.margin.note): the exact quoted text, disambiguated by up to 150 graphemes of context on each side. Offsets are into the document's rendered text content with whitespace as rendered."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```