Mouse-First v0.2: event-driven rewrite and drag/snap fixes

[DjaboDev]

Summary

This rewrites Mouse-First's internals. Every v0.1 feature is kept, and existing ~/.config/omarchy/mouse-first.json files keep working. See CHANGELOG.md for the user-facing list.

Architecture

• Service + thin bar widget. Omarchy creates one bar widget per monitor, so v0.1 drew one overlay and one set of controls per monitor. All state now lives in Service.qml, and BarWidget.qml only renders app icons.
• Compositor-side Lua module (src/lua/mousefirst.lua, loaded with hyprctl eval). It reports the active window, the monitor layout (with reserved space) and the left-button state as custom>>mousefirst>>… events. The shell no longer polls or spawns processes. The module is reinstalled after hyprctl reload, and a generation token keeps a stale shell instance from stopping a newer one's module.
• Explicit window state machine (src/WindowStates.qml): free / snapped / maximized, plus restore geometry. It replaces the old size caches and the browser-specific magic numbers.
• Drag controller in global coordinates (src/DragController.qml). Drags work across monitors, restore snapped or maximized windows under the cursor, and pause window animations while dragging.
• Pure, tested geometry (src/js/geometry.js + tests/).
• Hyprland command builders (src/js/hypr.js): every window-targeting command goes through a single place that validates the address.
• Theme through qs.Commons. Config through FileView/JsonAdapter (atomic writes, live reload).

Bugs fixed

• The controls lagged or detached during SUPER + drag and resizes. Cause: hyprctl polling every 120 ms, plus a 300 ms settle lock.
• Un-snapping with SUPER + drag left the window away from the cursor. The plugin resized the window during the compositor's drag. It now waits for the drop.
• Maximize and restore raced Hyprland (a toggle followed immediately by geometry).
• Coordinates on non-primary monitors were wrong, and reserved space was hard-coded (26 px top, 69 px bottom).
• "Disable tiling" floated windows after they had already opened tiled. It is now a Hyprland window rule.
• Focus was stolen whenever the active window was on a special workspace, which broke the scratchpad.
• Two minimize workspaces were in use, and v0.1's hid windows from omadock.
• The config was written through a bash heredoc, and some maps were never cleared.
• install.sh created a stray $tmp_cfg file and overwrote looknfeel.lua.

Removed: the bin/* Python/Bash helpers, install.sh (replaced by scripts/dev-link.sh for development) and the duplicated screenshot.

New: a language selector, and IPC actions for keybinds (qs -p /usr/share/omarchy/shell ipc call mousefirst snap left, …), including status for bug reports.

Test plan

Automated / scripted (done):

• node --test tests/: 14 geometry tests pass.
• luac -p src/lua/mousefirst.lua
• Via IPC on Hyprland 0.56.2: snap left and top-right, maximize, restore to the exact original geometry, minimize (window goes to special:minimized, focus moves to the next window, origin saved), restoreLast (window returns to its origin workspace), Hyprland-maximized window restored.
• The float rule toggles when mouse-first.json is edited by hand; the module and rule survive hyprctl reload.
• Bar icons resolve with the current icon theme; the settings panel renders.

Manual, needs a real mouse:

• Controls stay attached during SUPER + drag and border resizes.
• Drag by the top strip, including between monitors.
• Snap in all 8 zones with the preview shown.
• Un-snap and un-maximize from the top strip: the window stays under the cursor.
• Un-snap with SUPER + drag: the window resizes on drop and does not detach.
• Double-clicking the top strip maximizes and restores.
• Minimize and restore from the bar and from omadock.
• Moving the capsule by its handle; double-clicking the handle resets it.
• Settings toggles, button order, language.
• omarchy restart shell keeps settings and minimized origins.

🤖 Generated with Claude Code