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
- Define data model -- confirm multi-signal locator requirements (position + text + chapter + DOM fallback).
- Design anchors -- map DOM selections -->
{ position, selectedText, chapterRef, elementIndex, charOffset }. - Implement -- use rendering library APIs for annotations and navigation, ensure async cleanup.
- Resilience -- add re-anchoring strategy (exact match --> fuzzy text --> chapter fallback --> user notice).
- Performance -- lazy-load document assets, reuse single rendition, clean up listeners to avoid leaks.
- Testing -- add test cases for locator serialization + re-anchor helpers; capture regressions.
Checklist
- Position + text excerpt + chapterRef persisted together.
- Anchor serialization uses stable casing + schema.
- Re-anchoring warns user when falling back.
- Event handlers removed on unmount.
- Telemetry events logged for load failures with trace IDs.
Rationalizations
| Rationalization | Reality |
|---|---|
| "Exact match anchoring is always sufficient" | Documents change formatting across versions; multi-signal fallback prevents total anchor loss. |
| "Lazy loading complicates the code" | Eager loading wastes memory and blocks rendering; lazy loading is essential for large documents. |
| "Telemetry for load failures is overkill" | Without telemetry, silent anchor failures are invisible until users report them. |
Red Flags
- Relying on a single anchoring signal without fallback strategy
- Not cleaning up event handlers on unmount
- Skipping locator serialization tests
References
references/locator-patterns.md- Document locator strategiesreferences/anchoring.md- Annotation anchoring techniques