clean up & hyprland experiments

- Cleaned up docs
- removed hyprglass
- added various ways to do scroll view
This commit is contained in:
ari committed 2026-08-28 12:58:27 -04:00
1 parent c304803fda
commit 3c86efa4ff
23 files changed
+443 -212

No files matched your search

+29 -13
View File
@@ -32,11 +32,20 @@ split under `conf/` and pulled in with `require()`.
inside quickshell-based apps fail silently (hyprwm/Hyprland#14844). There is
intentionally no waybar/hyprpanel.
- **Keybinds:** `conf/keybindings.lua` mirrors `configs/niri/shared/binds.kdl`
and `configs/niri/noctalia/binds.kdl` as closely as Hyprland allows.
- **Overview:** there is no native Hyprland overview, and no overview plugin that
reliably builds against current Hyprland (hyprexpo was retired from the
official plugins repo; the community fork chases `main`). `Mod+Tab` falls back
to `cyclenext` instead of niri's `toggle-overview`.
and `configs/niri/dms/binds.kdl` as closely as Hyprland allows.
- **Overview:** Pure-Lua workspace overview (`conf/overview.lua`), no plugin. It
enumerates workspaces via `hl.get_workspaces()` and presents them in a
`wofi --dmenu` picker, dispatching the chosen workspace with
`hyprctl dispatch workspace`. Hyprland's Lua API has no "render a workspace
to a texture" primitive, so this is a switcher-style overview (id, name,
window count, active/empty/urgent flags) rather than live scaled thumbnails.
Bound to `Mod+Tab` (niri parity) and `Mod+G`.
- **Overview (plugin, WIP):** ScrollOverview (`conf/scrolloverview.lua`), a
niri-like overview plugin (github.com/yayuuu/hyprland-scroll-overview), is
the live-thumbnail alternative. Currently **disabled** (commented out in
`hyprland.lua`) while it's being debugged; would load via `hl.plugin.load`
from the `SCROLLOVERVIEW_SO` session variable set in
`modules/nixos/desktop/tiler/hyprland.nix`.
## Files
@@ -44,20 +53,26 @@ split under `conf/` and pulled in with `require()`.
hypr/
├── hyprland.lua # entry point; require()s conf/*.lua in order
├── screen-record.sh # wf-recorder toggle (bound to Mod+R)
├── xdph.conf # xdph screencopy workaround (force_shm); hyprlang, read by xdph itself
├── stylua.toml # stylua formatter settings for the Lua files
├── .luarc.json # lua-language-server config (uses types/ as library)
├── dms/ # DMS-auto-generated Hyprland overrides (colors/layout/windowrules);
│ # not loaded by default — require() them from hyprland.lua to enable
├── types/
│ └── hl.lua # EmmyLua type stubs for the `hl` global (editor-only, never executed)
└── conf/
├── env.lua # cursor size + Wayland/Qt/Electron env hints (hl.env)
├── general.lua # scrolling layout, gaps/border/rounding (hl.config)
├── animations.lua # vertical workspace-switch animation (hl.animation)
├── animations.lua # vertical workspace slide (slidevert), niri-like (hl.animation):
`style = "slidevert"`) to mirror niri's vertically-stacked workspaces, instead of
Hyprland's default horizontal `slide`. Only the `workspaces` leaf is overridden;
everything else stays on Hyprland defaults. Other `workspaces` styles available:
`slide`, `fade`, `slidefade`, `slidefadevert`.
├── animations.lua # workspaces slide = "slidevert" (niri-like); only the `workspaces`
│ # leaf overridden — other styles: slide, fade, slidefade, slidefadevert
├── monitors.lua # hl.monitor per display (from configs/niri/.../outputs.kdl)
├── inputs.lua # touchpad tap + natural scroll, kb us, hl.gesture
├── window-rules.lua # hl.window_rule floats for small dialogs/utilities
├── keybindings.lua # niri + noctalia binds, scrolling dispatchers (hl.bind/hl.dsp)
└── autostart.lua # noctalia, hypridle via setpriv (hl.on hyprland.start; drops compositor caps)
├── autostart.lua # noctalia, hypridle via setpriv (hl.on hyprland.start; drops compositor caps)
├── overview.lua # pure-Lua workspace switcher overview (wofi picker, Mod+Tab/Mod+G)
└── scrolloverview.lua # ScrollOverview plugin (niri-like, live thumbnails) — WIP/disabled;
# loads via $SCROLLOVERVIEW_SO, require() commented out in hyprland.lua
```
## Bindings without a clean 1:1 niri mapping
@@ -65,7 +80,8 @@ everything else stays on Hyprland defaults. Other `workspaces` styles available:
- `Mod+Shift+H` (show-hotkey-overlay) — no native Hyprland equivalent; left commented.
- `Mod+Escape` (toggle-keyboard-shortcuts-inhibit) — no native equivalent; omitted.
- `Mod+W` (toggle-column-tabbed-display) — mapped to `hl.dsp.group.toggle()` as the nearest analog.
- `Mod+Tab` (toggle-overview) — no native overview / no buildable plugin; mapped to `cyclenext`.
- `Mod+Tab` (toggle-overview) — pure-Lua overview (`conf/overview.lua`);
previously the ScrollOverview plugin, and `cyclenext` before that existed.
## Touchpad gestures (niri parity)
-53
View File
@@ -1,53 +0,0 @@
-- =========================
-- Hyprgrass (Touchpad Gestures)
-- =========================
-- Hyprgrass plugin configuration for advanced touchpad gesture support.
-- Documentation: https://github.com/horriblename/hyprgrass
-- Config reference: docs/configuration.md
-- environment.systemPackages only puts libhyprgrass.so on disk -- Hyprland
-- doesn't load plugins on its own. HYPRGRASS_SO is set in
-- modules/nixos/desktop/tiler/hyprland.nix (sessionVariables) to the resolved
-- store path, since that path changes on every flake update. Must run before
-- anything below references plugin.hyprgrass config keys or hl.plugin.hyprgrass,
-- both of which only exist once the plugin is loaded.
hl.plugin.load(os.getenv("HYPRGRASS_SO"))
hl.config({
plugin = {
hyprgrass = {
-- The default sensitivity is probably too low on tablet screens,
-- I recommend turning it up to 4.0
sensitivity = 4.0,
-- in milliseconds
long_press_delay = 400,
-- resize windows by long-pressing on window borders and gaps.
resize_on_border_long_press = true,
-- in pixels, the distance from the edge that is considered an edge
edge_margin = 10,
},
},
})
-- =========================
-- Custom gesture bindings
-- =========================
-- -- -- 4-finger swipes to switch workspaces
hl.plugin.hyprgrass.gesture({
pattern = { kind = "swipe", fingers = 4, direction = "left" },
action = "workspace",
})
hl.plugin.hyprgrass.gesture({
pattern = { kind = "swipe", fingers = 4, direction = "right" },
action = "workspace",
})
-- 3-finger tap to toggle floating
hl.plugin.hyprgrass.bind({
pattern = { kind = "tap", fingers = 3 },
action = hl.dsp.window.float(),
})
+3 -2
View File
@@ -25,8 +25,9 @@ hl.bind(mod .. " + right", hl.dsp.focus({ direction = "right" }))
hl.bind(mod .. " + up", hl.dsp.focus({ workspace = "e-1" }))
hl.bind(mod .. " + down", hl.dsp.focus({ workspace = "e+1" }))
-- niri: toggle-overview — no native overview / no buildable plugin; cycle windows.
hl.bind(mod .. " + Tab", hl.dsp.window.cycle_next())
-- hl.bind(mod .. " + Tab", function()
-- hl.plugin.scrolloverview.overview("toggle all")
-- end)
-- niri: focus-monitor-next
hl.bind(mod .. " + SHIFT + Tab", hl.dsp.focus({ monitor = "+1" }))
+127
View File
@@ -0,0 +1,127 @@
-- =========================
-- Overview (pure Lua, wofi-driven)
-- =========================
-- A niri-style workspace overview built entirely from Hyprland's Lua API -- no
-- external plugin (.so). Because Hyprland's Lua API exposes no "render a
-- workspace to a texture" primitive, we can't draw live scaled thumbnails from
-- Lua alone. So this is the honest pure-Lua version: a workspace *switcher
-- overview* -- enumerate every workspace (id, name, window count, active/empty
-- state) with hl.get_workspaces(), present them in a wofi dmenu, and jump to
-- the one you pick.
--
-- Flow: the Lua side is the source of truth for the workspace list; it writes a
-- tiny picker script to /tmp and launches it with `sh <file>`. The script shows
-- wofi, extracts the leading workspace id from the chosen line, and dispatches
-- it with hyprctl.
--
-- Why the dispatch lives in the script (not in a Lua timer): a Lua keybind
-- callback runs on the compositor's main thread under a ~100ms watchdog, so it
-- can't block reading wofi's stdout, and an async poll-timer handoff (reading a
-- result file on a repeating hl.timer) proved fragile -- a dispatch error left
-- the poll timer leaked. Keeping the switch in the spawned shell is the simple,
-- robust path. The script is launched as `sh <file>` (not executed) so we never
-- need os.execute/chmod, which would also block the callback.
--
-- Bound to Mod+Tab (niri parity) and Mod+G. The old plugin-based
-- conf/scrolloverview.lua is left untouched and still commented out in
-- hyprland.lua.
local mod = "SUPER"
-- Where the generated picker script lives. /tmp is fine for a per-session
-- helper; it's rewritten on every toggle so it always reflects live state.
local script_path = "/tmp/hypr-overview.sh"
---Build the display lines fed to wofi.
---Each line starts with the numeric workspace id, which is what the picker
---dispatches on. Keeping the id first means we never have to round-trip a
---hidden selector column through wofi.
---@return string[] lines one human-readable label per workspace
local function workspace_lines()
local lines = {}
-- Stable ordering: numeric id ascending.
local ws = hl.get_workspaces() or {}
table.sort(ws, function(a, b)
return (a.id or 0) < (b.id or 0)
end)
for _, w in ipairs(ws) do
-- Skip special (scratchpad) workspaces; they aren't part of the tape.
if not w.special and w.id and w.id > 0 then
local name = (w.name and w.name ~= "") and w.name or ("workspace " .. w.id)
local count = w.windows or 0
local flags = {}
if w.active then
table.insert(flags, "active")
end
if count == 0 then
table.insert(flags, "empty")
end
if w.has_urgent then
table.insert(flags, "urgent")
end
local suffix = #flags > 0 and (" [" .. table.concat(flags, ", ") .. "]") or ""
-- Leading "<id>." is parsed back out by the picker; keep it first.
table.insert(
lines,
string.format("%d. %-24s %2d window(s)%s", w.id, name, count, suffix)
)
end
end
return lines
end
---Write the picker helper script. It feeds the display lines to wofi, extracts
---the leading workspace id from the chosen line, and dispatches it via hyprctl.
---@param lines string[]
---@return boolean ok
local function write_script(lines)
local f = io.open(script_path, "w")
if not f then
hl.print("overview: could not write", script_path)
return false
end
f:write("#!/bin/sh\n")
f:write("# Generated by conf/overview.lua -- do not edit by hand.\n")
-- No `set -e`: wofi exits non-zero on Escape/cancel; we just do nothing.
f:write("pick=$(cat <<'__DATA__' | wofi --dmenu --prompt 'Overview' --width 480 --lines 15)\n")
for _, line in ipairs(lines) do
-- Guard against a stray newline/heredoc terminator inside a name.
local safe = line:gsub("\n", " ")
f:write(safe .. "\n")
end
f:write("__DATA__\n")
f:write(")\n")
f:write('[ -z "$pick" ] && exit 0\n')
-- The chosen line begins with "<id>."; take the leading digits as the id.
f:write('id=$(printf %s "$pick" | cut -d. -f1 | tr -dc 0-9)\n')
f:write('[ -z "$id" ] && exit 0\n')
f:write('exec hyprctl dispatch workspace "$id"\n')
f:close()
return true
end
---Toggle the overview: regenerate the live workspace list and pop wofi.
---Writing a small file and spawning a process are both fast enough to run
---directly in the keybind callback (no blocking subprocess, no chmod).
local function show_overview()
local lines = workspace_lines()
if #lines == 0 then
return
end
if write_script(lines) then
hl.exec_cmd("sh " .. script_path)
end
end
-- Mod+Tab is niri's toggle-overview; Mod+G kept for muscle-memory parity with
-- the old scrolloverview bind.
hl.bind(mod .. " + Tab", show_overview)
hl.bind(mod .. " + g", show_overview)
@@ -0,0 +1,26 @@
-- =========================
-- ScrollOverview (niri-like overview)
-- =========================
-- ScrollOverview plugin: an overview just like niri's, based on the
-- scroll-overview branch of hyprexpo. Docs:
-- https://github.com/yayuuu/hyprland-scroll-overview
-- environment.systemPackages only puts libscrolloverview.so on disk -- Hyprland
-- doesn't load plugins on its own. SCROLLOVERVIEW_SO is set in
-- modules/nixos/desktop/tiler/hyprland.nix (sessionVariables) to the resolved
-- store path, since that path changes on every flake update. Must run before
-- anything below references plugin.scrolloverview config keys or
-- hl.plugin.scrolloverview, both of which only exist once the plugin is loaded.
hl.plugin.load(os.getenv("SCROLLOVERVIEW_SO"))
hl.config({
plugin = {
scrolloverview = {},
},
})
-- Toggle the overview with Mod+g (niri's toggle-overview lives on Mod+Tab in
-- conf/keybindings.lua, which now calls into this plugin too).
hl.bind("SUPER + g", function()
hl.plugin.scrolloverview.overview("toggle all")
end)
+2 -9
View File
@@ -1,14 +1,6 @@
-- =========================
-- Hyprland (fwbook)
-- =========================
-- Lua config (Hyprland 0.55+; hyprlang is deprecated). Mirrors the niri setup
-- in configs/niri, adapted to Hyprland's native scrolling layout + the noctalia
-- shell. This directory is symlinked to ~/.config/hypr by the skyg hyprland
-- module (skyg.nixos.desktop.tiler.hyprland), defaulting to
-- configs/${hostName}/hypr.
--
-- Split across conf/*.lua and pulled in with require(). The folder is named
-- `conf` (not `hyprland.d`) because require() treats `.` as a path separator.
require("conf/env")
require("conf/general")
@@ -18,4 +10,5 @@ require("conf/inputs")
require("conf/window-rules")
require("conf/keybindings")
require("conf/autostart")
require("conf/hyprgrass")
-- require("conf/overview")
require("conf/scrolloverview")
+62 -22
View File
@@ -28,8 +28,9 @@
---@class hl.dsp.FocusOpts
---@field direction? "left"|"right"|"up"|"down" Focus by direction
---@field workspace? string e.g. "e-1", "e+1", integer
---@field workspace? string|integer e.g. "e-1", "e+1", or a numeric id
---@field monitor? string e.g. "+1", "-1", name
---@field on_current_monitor? boolean Switch to the workspace on the current monitor
---@class hl.dsp.MoveOpts
---@field direction? "left"|"right"|"up"|"down"
@@ -141,8 +142,8 @@ dsp.workspace = dsp_workspace
---@field repeating? boolean Fire repeatedly while held (note: key is `repeating`, not `repeat`)
---Register a keybind. Returns a handle with a `:set_enabled(bool)` method.
---@param keys string Modifier + key string, e.g. "SUPER + T"
---@param action hl.DispatcherValue Return value of an hl.dsp.* factory
---@param keys string Modifier + key string, e.g. "SUPER + T"
---@param action hl.DispatcherValue | fun() An hl.dsp.* factory result, or a Lua callback
---@param opts? hl.BindOpts
---@return hl.BindHandle
function hl.bind(keys, action, opts) end
@@ -350,32 +351,71 @@ local plugin = {}
---Load a Hyprland plugin from its .so path.
---@param path string Absolute path to the shared library
function plugin.load(path) end
-- ---------------------------------------------------------------------------
-- hl.get_workspaces — runtime introspection
-- ---------------------------------------------------------------------------
---@class hl.plugin.hyprgrass
local plugin_hyprgrass = {}
---@class HL.Monitor
---@field id integer
---@field name string
---@field description? string
---@field width? integer
---@field height? integer
---@field x? integer
---@field y? integer
---@field scale? number
---@field focused? boolean
---@field active_workspace? HL.Workspace
---@class hl.HyprGrassPattern
---@field kind "swipe"|"tap"|"pinch"
---@field fingers number
---@field direction? "left"|"right"|"up"|"down"
---@class HL.Workspace
---@field id integer
---@field name string
---@field config_name? string Config-specified name (empty/absent for auto)
---@field windows? integer Number of windows on the workspace
---@field special? boolean Is a special (scratchpad) workspace
---@field active? boolean Is active on its monitor
---@field visible? boolean
---@field has_urgent? boolean
---@field is_empty? boolean
---@field monitor? HL.Monitor
---@class hl.HyprGrassGestureOpts
---@field pattern hl.HyprGrassPattern
---@field action string|hl.DispatcherValue
---All non-inert workspaces.
---@return HL.Workspace[]
function hl.get_workspaces() end
---@class hl.HyprGrassBindOpts
---@field pattern hl.HyprGrassPattern
---@field action hl.DispatcherValue
-- ---------------------------------------------------------------------------
-- hl.print — log to the Hyprland log
-- ---------------------------------------------------------------------------
---Register a hyprgrass gesture.
---@param opts hl.HyprGrassGestureOpts
function plugin_hyprgrass.gesture(opts) end
---@param ... any
function hl.print(...) end
---Register a hyprgrass tap/press bind.
---@param opts hl.HyprGrassBindOpts
function plugin_hyprgrass.bind(opts) end
-- ---------------------------------------------------------------------------
-- hl.dispatch — execute a dispatcher closure now
-- ---------------------------------------------------------------------------
plugin.hyprgrass = plugin_hyprgrass
---Run a dispatcher closure immediately (same as firing a bound key's action).
---@param action hl.DispatcherValue
function hl.dispatch(action) end
-- ---------------------------------------------------------------------------
-- hl.timer — deferred / repeating callbacks
-- ---------------------------------------------------------------------------
---@class hl.TimerOpts
---@field timeout number Interval / delay in milliseconds
---@field type? "repeat"|"oneshot"
---@class hl.TimerHandle
local TimerHandle = {}
---Cancel this timer.
function TimerHandle:cancel() end
---Schedule a callback on a repeating or one-shot timer.
---@param callback fun()
---@param opts hl.TimerOpts
---@return hl.TimerHandle
function hl.timer(callback, opts) end
-- ---------------------------------------------------------------------------
-- Global `hl` declaration