Skip to content

Add PDF box annotations with hover preview and click-to-edit - #196

Open
jlongvalRobotiq wants to merge 3 commits into
bugzmanov:mainfrom
jlongvalRobotiq:rect-annotations
Open

Add PDF box annotations with hover preview and click-to-edit#196
jlongvalRobotiq wants to merge 3 commits into
bugzmanov:mainfrom
jlongvalRobotiq:rect-annotations

Conversation

@jlongvalRobotiq

Copy link
Copy Markdown

Summary

Add rectangular PDF annotations for figures, diagrams, and other regions that cannot be anchored conveniently to a text selection. Region comments use the existing comment editor, YAML persistence, comments viewer, and Markdown export; the PDF itself is not modified.

Interaction

  • b in standard PDF mode or Space+B starts box drawing. Space+b retains upstream's zen-border toggle.
  • Move with hjkl/arrows, set a corner with v/Space, then confirm with Enter; alternatively left-drag a box and release.
  • Type a comment and press Esc to save. Esc during drawing cancels; viewport resize/layout changes cancel unfinished geometry.
  • Hover inside a saved box to preview its comment. A stationary click opens the editor on release; dragging inside the box still selects text.
  • Drawing-mode shortcuts use the configurable pdf_box keybinding context. Ctrl+click/right-click retain SyncTeX behavior.

Implementation and compatibility

  • Add an optional-on-disk region flag to PDF comment targets. Missing flags default to text annotations, and false is omitted when serializing. Existing storage locations and text annotation behavior are retained.
  • Persist rectangles in PDF points with a top-left origin. Boxes are restricted to a single page. Text inside a box is captured as quoted context when available.
  • Render outlines as four edge bars before tile clipping, preserving existing underlines, link outlines, and transparent-page rendering.
  • Reuse the existing page-scoped invalidation interface rather than copying rectangle collections.
  • Include each rectangle's own 1-based page and point coordinates in Markdown exports, including multi-page text annotations.
  • Update README and built-in help.

Integrated current upstream main (824cc7b), including per-page enhancement/zoom geometry and pixel-precision mouse handling. Deferred selection preserves the original mouse-down position.

Verification

  • cargo test --lib: 577 passed.
  • cargo test --test svg_snapshots: 92 passed, 2 ignored; no golden updates.
  • cargo check --all-targets
  • cargo build --release
  • cargo clippy --all-targets completes with warnings. Strict -D warnings is not clean on the local Rust 1.98 toolchain; for example, it flags the existing wildcard pattern in src/parsing/markdown_renderer.rs:540.

Added focused regressions for viewport-edge boxes, zoom/pan and differently enhanced pages in scroll mode, resize cancellation, click-versus-drag behavior, legacy YAML compatibility, disk-backed region persistence, text/box coexistence, per-page export locations, and outline/underline tile clipping.

Manual testing on Linux/Kitty covered drawing, saved comment preview, leaving a box/divider, and click-versus-drag editing. After integrating current main, a separate live smoke check confirmed the configurable drawing keys open the box comment editor. Cross-terminal VHS goldens were not regenerated; additional terminal coverage would be useful during review.

jorlong and others added 3 commits September 10, 2026 10:09
- CommentTarget::Pdf gains a region flag (serde: region: true only when set;
  legacy files load unchanged)
- b / Space+b enters box mode: hjkl/arrows move, HJKL fast, v/Space sets a
  corner, Enter opens the comment editor, Esc cancels; mouse drag also works
- region comments render as an outline (converter), text comments unchanged
- overlap rule: regions and text anchors may coexist
- Markdown export emits 'page N · box|text x0,y0 – x1,y1 pt' per PDF comment
- text inside the box becomes quoted_text
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant