[vitofico]

Summary

Adds the first highlighting increment for #143. Readers can enter Highlight mode, save a selection in Yellow, Green or Pink, recolour or remove a saved passage, and use the native selection menu to Copy as quote with the book title and author.

Room 9 → 10 stores UUIDs, exact locator JSON, selected text, book identity and metadata, update timestamps and soft-deletion tombstones. Highlights survive download deletion and reimport. Readium restores exact structural ranges so identical quotations anchor to the selected occurrence; invalid or changed chapter content preserves the quote without guessing a location. Decoration updates remove deleted UUIDs across page lifecycles.

This PR connects storage, Readium rendering and the selection UI. The exported Room schema, regression tests and translations account for much of its size. A highlights list and jump navigation remain PR 2; server sync and notes remain later work.

Component(s)

• Android app
• Sync server
• Documentation
• CI / build

Validation

• Android: debug and optimized R8 release APKs, all 1,582 test executions (zero failures/errors/skips), and lint passed with scripts/dgradle :app:assembleDebug :app:assembleRelease test lint --max-workers=2 --no-watch-fs. Both APKs contain the frozen production adapter and exclude the spike Activity/test EPUB.
• Browser: all 18 regressions passed against the exact locked Playwright package; the new Android CI step also passed.
• Server: all 990 tests passed; Ruff check and formatting check passed. Server sources are unchanged.
• Repository checks: 20 release-tooling tests, AboutLibraries release JSON drift check, rename guard/self-test, and pre-commit on all 52 PR files passed.
• Independent review: source, migration, CI/lockfile and UI test review found no blocking findings. Robolectric dialog cases verify public accessibility clicks; physical native taps independently verify the control wiring.
• Native API 36 workflows: Room 9 → 10 preserves the original book and every progress field; native selection handles; all three colours; cancel; recolour with stable UUID; soft deletion with only the removed overlay disappearing; Done/Back; mode tap suppression and forward/reverse swipes; exact clipboard paste of Copy as quote including title/author. Rotation, repeated reopening, process relaunch and actual book deletion/reimport preserve the surviving UUID and never restore tombstones. Reimport creates a new document ID.
• Production rendering matrix: six persisted ranges across initial rendering, reopening, actual 120% font reflow and Dark theme (24 checks). Includes the second identical paragraph and second identical cross-paragraph pair. Every UUID has one container and exact intended endpoints/text; painted rectangles match live DOM range rectangles within 2 CSS pixels.
• Invalid anchors: missing range, invalid path, stale fingerprint and malformed locator JSON retain their saved quotes, draw no invalid items/overlays and leave valid peers correctly rendered. Restoring valid inputs clears rejection diagnostics.
• GitHub CI: Android build and both CodeQL analyses passed on e2dbeb8; the release job is skipped for this PR.

The rendering adapter uses the pinned Readium 3.0 decoration-group shape and fails closed if that contract changes. Toolkit upgrades must rerun the browser regressions documented in docs/reader-highlights.md.

Screenshots

Before	Highlight mode	Edit a highlight

All screenshots use the original synthetic test EPUB committed under reader test resources.

Checklist

• Tests added or updated
• Docs updated in the same PR
• Android UI screenshots attached
• Server schema migration: N/A, server unchanged
• core/identity algorithm and shared fixtures: unchanged; consumes existing normalization
• No new production SDKs, analytics or telemetry; Playwright is a locked test-only dependency
• Commit messages follow gitmoji + conventional commits

Related issues

Refs #143. This is PR 1; it deliberately leaves the issue open for the remaining increments.