Document Rendering and Locators

Purpose: implement resilient document rendering, locator extraction, and annotation anchoring.

When to run

• Integrating document rendering library or reader-core changes.
• Working on TOC, locator, or highlight/comment anchoring logic.
• Debugging annotation drift or document loading regressions.

Workflow

1. Define data model -- confirm multi-signal locator requirements (position + text + chapter + DOM fallback).
2. Design anchors -- map DOM selections --> { position, selectedText, chapterRef, elementIndex, charOffset }.
3. Implement -- use rendering library APIs for annotations and navigation, ensure async cleanup.
4. Resilience -- add re-anchoring strategy (exact match --> fuzzy text --> chapter fallback --> user notice).
5. Performance -- lazy-load document assets, reuse single rendition, clean up listeners to avoid leaks.
6. Testing -- add test cases for locator serialization + re-anchor helpers; capture regressions.