Roadmap: add common annotation system features

[elmisback]

The annotation interface should provide features users are known to like and expect from annotation systems. Claude Opus 4.7 suggests the following:

Here's a breakdown of features that tend to show up across popular annotation tools (Hypothesis, PDF annotators, GitHub PR reviews, Notion/Google Docs comments, Figma, Readwise, etc.), organized by category. I've flagged what's essential vs. nice-to-have and called out code-specific considerations.

Core annotation mechanics

• Selection granularity: line, line-range, token/expression, and block (function/class). Users expect to attach notes at the most natural unit — for code, that usually means all three tiers.
• Annotation types: comment, question, TODO, bug, suggestion, bookmark, highlight-only. Distinct types enable downstream filtering and different visual treatments.
• Rich note content: markdown, code blocks with syntax highlighting, images, links, and @mentions. Plain text alone feels limiting fast.
• Threaded replies on each annotation, with resolve/unresolve state.
• Draft / private vs. shared visibility per annotation.

Organization & retrieval (your "filtering and tagging" bucket)

• Tags/labels, ideally with autocomplete from existing tags and support for hierarchical or namespaced tags (security/auth, perf/memory).
• Filters combining: tag, author, type, status (open/resolved), date range, file/path, language.
• Full-text search across annotation bodies and the anchored code.
• Saved views / smart filters (e.g., "my open TODOs in /src/auth").
• Color coding tied to tags or types.
• Sorting by recency, file location, thread activity, priority.

Anchoring & persistence (disproportionately important for code)

• Robust anchors that survive edits — most tools combine line number + content hash + surrounding context (fuzzy match fallback).
• Orphan handling: when an anchor can't be located, surface the annotation rather than silently drop it, and let the user re-anchor.
• Version/commit awareness: annotations tied to a commit SHA, with a strategy for how they migrate across commits (pin to commit, follow HEAD, or explicit rebase).
• Branch awareness: annotations visible on one branch vs. all branches.
• Diff annotations: comment on a specific change, not just a line.

Display & navigation

• Inline markers + sidebar/gutter panel — the two-view pattern is near-universal because inline shows context and the panel enables scanning.
• Toggle visibility by type, tag, or author (reduces clutter in dense files).
• Overlap/stacking handling when multiple annotations hit the same line.
• Next/previous annotation navigation with keyboard shortcuts.
• Minimap/overview showing annotation density across a file.
• Jump-to-annotation from a global list back into the code.

Collaboration

• Attribution with user avatars and timestamps; edit history for transparency.
• Notifications (new replies, @mentions, resolved threads), ideally with digest options.
• Permissions: read-only, comment-only, edit — sometimes per-repo or per-branch.
• Real-time updates so two people annotating the same file don't clobber each other.
• Shareable deep links to a specific annotation.

UX niceties that drive adoption

• Keyboard-first creation (select + shortcut, no mouse dance).
• Quick annotation without forcing a tag/type up front — add metadata later.
• Templates for recurring comment patterns (code review checklists, etc.).
• Bulk operations (tag many, resolve many, reassign).
• Undo for destructive actions.

Integration & data portability

• Export to JSON, Markdown, CSV; per-file and whole-project.
• Import from other tools or from inline // TODO comments.
• API / webhook access for custom workflows.
• IDE/editor integration (VS Code, JetBrains) — for a code annotation system, this is probably table-stakes rather than optional.
• VCS integration: link to PRs/issues, convert annotation → issue, reference commits.

Analytics & insight (often overlooked, often loved)

• Heatmaps of annotation density per file/module.
• Stale annotation detection (old, unresolved, on frequently-changed code).
• Per-author activity and unresolved-by-author views.
• Exportable reports for code review sessions or onboarding.

Code-specific features worth considering

• Symbol-aware anchoring: attach to a function/class by name so the annotation follows renames/moves when possible.
• Language-aware display: collapse annotations inside folded regions, respect comment syntax when exporting inline.
• Inline vs. overlay modes: overlay keeps source files untouched (important for read-only or third-party code); inline can write // @note comments into the source for teams that want that.
• Read-only source support — annotating vendored/library code without modifying it is a common use case.

Suggested MVP priority for a code annotation system

If you're scoping a v1, the features that deliver outsized value early are: selection + comment + threaded replies, tags + filter, robust anchoring with orphan handling, sidebar + inline display, keyboard shortcuts, and export. Collaboration, analytics, and IDE integration tend to be v2+ depending on whether you're building for solo learners, teams, or reviewers.