page.cavu.highlight Documentation (EN)

main 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.

Record Key tid Timestamp-based ID

Properties

book string at-uri Required

AT-URI of the book's site.standard.publication record — the backlink target, and the key clients list by.

color string Optional

Client-chosen highlight color name or hex value. Clients without an opinion omit it.

maxLength: 32 bytes

createdAt string datetime Required

An RFC 3339 formatted timestamp.

document ref com.atproto.repo.strongRef Required

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.

note string Optional

The reader's own note on the passage.

maxLength: 10000 bytesmaxGraphemes: 3000 graphemes

selector ref #textQuoteSelector Required

Where in the document's text the highlight lives.

thousandths integer Optional

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.

minimum: 0maximum: 1000

View raw schema

{
  "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 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.

Properties

exact string Required

The highlighted text itself.

maxLength: 5000 bytesmaxGraphemes: 1500 graphemes

prefix string Optional

Text immediately before the quote, for disambiguating repeated passages.

maxLength: 500 bytesmaxGraphemes: 150 graphemes

suffix string Optional

Text immediately after the quote.

maxLength: 500 bytesmaxGraphemes: 150 graphemes

View raw schema

{
  "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."
}