hypr-lens/CHANGELOG.md

Changelog

All notable changes to hypr-lens are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Conventional Commits.

Unreleased

Added

• Crop Mode - Press C (or the new Instant/Crop toolbar tabs) to switch the region selector into Crop mode: releasing a selection opens an adjustable editor (8 resize handles + interior move, min-size and screen clamping, live size label) instead of capturing immediately; Enter/Space or the confirm button captures, Escape returns to drawing. Crop implies rectangles: entering it from Freehand auto-swaps to Rect (Freehand is unselectable while Crop is active). Works for screenshots and recording alike; configurable via regionSelector.crop.minSize/handleSize
• R Hotkey - Toggles Rect/Freehand selection mode inside the overlay (the "Circle" tab is now labeled Freehand; config keys keep their circle names)
• Freehand True-Shape Capture - Freehand selections now capture only the pixels inside the drawn loop (transparent outside, via an ImageMagick polygon mask). OCR flattens onto white; recording and the crop editor remain rectangular (true-shape applies to Instant-mode freehand only)
• regionSelector.dragThreshold Config Key - Pixel dead-zone (default 6) for the region selector's click/drag discriminator; 0 disables it, restoring the previous per-pixel sensitivity (circle mode always uses 0 — every circle gesture is the drawn shape)

Changed

• Region Selector Click/Drag Dead-Zone - Press-to-release movements within dragThreshold (default 6 px) are now treated as clicks that select the whole hovered window/region, instead of snipping a tiny drag rectangle. This is a user-visible behavior change: if you relied on tiny deliberate drags to grab very small rectangles, lower or zero the threshold
• Region Selector Empty-Space Clicks - A click (or sub-threshold micro-drag) over empty space with no targetable region now dismisses the overlay cleanly instead of capturing a sliver
• Monitor Button Order - The toolbar's monitor capture buttons now follow left-to-right layout order automatically (ascending x, ties broken top-to-bottom, from Hyprland logical coordinates), re-read every time the selector opens — no configuration needed

Removed

• monitorOrder Config Key - The manual monitor button ordering array is gone; ordering is now automatic from the layout position. A leftover key in an existing config is ignored and dropped the next time the config is rewritten

Fixed

• Edge-Straddling Window Targeting - Clicking a window or layer that hangs off the monitor's left/top edge now selects it (matching its hover highlight) instead of dismissing the overlay; validity no longer sign-checks the region's origin. The capture is trimmed to the window's visible on-screen extent — screen clamping used to slide such regions fully on-screen at full size, which would have captured unrelated content beside the window
• Cross-Monitor Capture State - Monitor-button captures on another screen now honor the initiating screen's Crop mode (the target's crop editor opens instead of an instant snip) and right-click Edit (previously the capture silently went to the clipboard as Copy)
• Copy Failure Handling - A failed capture in Copy mode no longer clears the clipboard or reports a false "Copied to clipboard"; failures now show an explicit "Copy failed" notification and leave no zero-byte files behind
• Freehand Closed Loops - A freehand loop that ends precisely on its starting pixel is now captured as the drawn shape instead of being discarded as a click. Consequence: any Freehand gesture with 2+ motion samples counts as a draw even if it returns to its start pixel — a jittery click there now captures a tiny shape rather than selecting the content region under the cursor (matching how Freehand already treated jitter with any net drift)
• Invisible Region Selection - Clicks no longer select regions whose highlight type is disabled (regionSelector.targetRegions.*: false); hit-testing now follows the same gating as the visuals. Note this also changes Freehand mode: a stationary click on a window (never highlighted there) previously captured that window silently — it now dismisses the overlay unless the click lands inside a highlighted content region, which stays selectable in Freehand, consistent with what's on screen

---

1.6.0 - 2026-06-06

Added

• satty Annotation Tool - satty is now the default editor for the "edit" action (configurable via regionSelector.annotation.useSatty), with a bundled satty.toml and swappy as a fallback
• hypr-lens / hl Wrappers - Installer now provides launcher commands that detach on launch and run synchronously for IPC; removed on uninstall
• Dev Update Helper - dev-update.sh syncs scripts and ensures shell.qml integration during development

Changed

• Selection Rounding Matches Hyprland - Selection overlays now read decoration:rounding live via hyprctl getoption instead of a hardcoded value, so corners match real windows; updates on start and on Hyprland events
• Docs Use Wrapper Commands - README/MANUAL now reference hypr-lens/hl instead of raw qs --path ...

Fixed

• Config Docs - Removed the misleading killall quickshell; quickshell & tip; the JSON config hot-reloads and never needs a restart

---

1.5.0 - 2025-12-20

Added

• Developer Setup Script - New dev-setup.sh creates symlinks for live editing during development
• Development Wiki Page - Contributor guide with setup instructions and project structure

Changed

• Installer Cleanup - Removed dev-specific symlink detection; installer now always copies files (cleaner code path for users)

Documentation

• README - Added Development link to navigation bar
• Wiki Sidebar - Added Contributing section with Development page link

---

1.4.0 - 2025-12-19

Fixed

• Screenshot Save Path - Screenshots and edited images now properly save to configured savePath
• Tilde Expansion - ~/ paths now correctly expand in all save path configurations
• Swappy Integration - Edit mode (swappy) now respects copyAlsoSaves setting for consistent behavior
• Config Parsing - Changed config format from JSONC to JSON for reliable parsing

Added

• Default Save Paths - Screenshots default to ~/Pictures/hypr-lens, recordings to ~/Videos/hypr-lens
• Copy Also Saves Option - New copyAlsoSaves config option for users who want left-click to also save
• Screenshot Notifications - Visual feedback via notify-send for copy and save operations

Changed

• Copy Mode Behavior - Left-click (Copy) now only copies to clipboard by default; use Edit mode (right-click) or enable copyAlsoSaves to save files
• Code Quality - Extracted save path helpers to reduce duplication in screenshot commands

---

1.3.0 - 2025-12-16

Added

• Right-Click Edit on Monitor Buttons - Right-click monitor buttons to capture and edit with swappy

Fixed

• MonitorButton Tooltip - Fixed missing services import for tooltip functionality

Changed

• Documentation - Clarified compatibility notes for non-Arch distributions

---

1.2.0 - 2025-12-08

Added

• Demo Videos - Video demonstrations of screenshot, OCR, and screen recording features
• Security Documentation - Comprehensive SECURITY.md transparency document with line-by-line audit

Fixed

• Video Compatibility - Re-encoded demo videos to H.264 for GitHub compatibility

---

1.1.0 - 2025-12-08

Added

• One-Click Monitor Capture - Quick capture buttons for each monitor in the region selector UI

Changed

• Region Selector Refactor - Extracted utilities and reduced code duplication for better maintainability

Fixed

• Installer Recovery - Detect and recover missing shell integration during update mode
• Invalid Input Handling - Improved input validation in integration recovery flow

---

1.0.0 - 2025-12-08

Initial public release! 🎉

Added

• Core QML Region Selector - Polished region selection UI with window detection, custom region drawing, and visual feedback
• Screenshot Capture - Region, window, and fullscreen screenshot support with clipboard integration
• OCR Text Extraction - Tesseract-powered text extraction from selected screen regions
• Google Lens Integration - Quick image search workflow via clipboard + browser
• Screen Recording - Region-based screen recording with optional audio capture using wf-recorder
• Color Picker - Screen-wide color picking via hyprpicker integration
• OpenCV Content Detection - Intelligent region detection within screenshots using Python + OpenCV
• Window/Layer Detection - Automatic detection of Hyprland windows and layers for quick capture
• Installer Script - Interactive installer with dependency detection, automatic setup, and shell integration
• Example Keybinds - Pre-configured Hyprland keybinds for all features
• Default Configuration - JSONC config with sensible defaults for all options
• Matugen Theming Support - Dynamic Material You theming via matugen integration
• IPC Interface - Programmatic control via quickshell IPC commands
• Project Documentation - README, MANUAL, SECURITY audit, and wiki

Features in Detail

Feature	Keybind
Region Screenshot	Super+Shift+S
Image Search	Super+Shift+A
OCR Extraction	Super+Shift+X
Screen Recording	Super+Shift+R
Recording + Audio	Super+Shift+Alt+R
Color Picker	Super+Shift+C
Quick Fullscreen	Print

---

Version History Summary

Version	Date	Highlights
1.5.0	2025-12-20	Developer setup script, contributor docs
1.4.0	2025-12-19	Screenshot save fix, tilde expansion, swappy integration
1.3.0	2025-12-16	Right-click edit on monitor buttons
1.2.0	2025-12-08	Demo videos, security documentation
1.1.0	2025-12-08	Monitor capture buttons, installer recovery
1.0.0	2025-12-08	Initial release