feat(config): configurable primary modifiers (#1854)

Author: y3owk1n

configs/default-config.toml

@@ -20,6 +20,12 @@ hide_overlay_in_screen_share = false
 # exec_shell = "/bin/bash"                   # e.g. "/bin/dash", "/bin/zsh"
 # exec_shell_args = ["-lc"]                  # last argument receives the command string
 
+# What a Primary hotkey means on each platform, so one file serves every machine
+[general.primary_modifier]
+darwin = "Cmd"
+linux = "Ctrl"
+windows = "Ctrl"
+
 # Theme palette
 # See https://github.com/y3owk1n/neru/blob/main/docs/reference/configuration.md#theme
 [theme.light]

docs/guide/getting-started.md

@@ -60,7 +60,7 @@ edits.
 Neru ships a launcher for every mode except monitor select, which is disabled
 and unbound, and the modes you declare yourself. Hints is
 `Primary+Shift+Space`, where `Primary` is `Cmd` on macOS and `Ctrl` on
-Windows. The [default hotkeys](../reference/configuration.md#global-hotkeys)
+Windows by default. The [default hotkeys](../reference/configuration.md#global-hotkeys)
 list the rest. Go on to [Try it](#try-it).
 
 ### Linux

docs/reference/configuration.md

@@ -75,7 +75,7 @@ see [Getting started](../guide/getting-started.md#bind-your-first-hotkey).
 | `Ctrl`    | `Control`                               |
 | `Alt`     | `Option`                                |
 | `Shift`   |                                         |
-| `Primary` | `Cmd` on macOS, `Ctrl` on Linux/Windows |
+| `Primary` | Set per platform by [`general.primary_modifier`](#general), `Cmd` on macOS and `Ctrl` on Linux/Windows by default |
 
 | Category   | Keys                                                                                                  |
 | ---------- | ----------------------------------------------------------------------------------------------------- |
@@ -429,10 +429,25 @@ passthrough_unbounded_keys = true
 | `passthrough_unbounded_keys_blacklist` | array  | `[]`          | Shortcuts to keep consumed when passthrough is on                                           |
 | `exec_shell`                           | string | `"/bin/bash"` | Shell binary used for `exec` hotkey commands. Windows default below                         |
 | `exec_shell_args`                      | array  | `["-lc"]`     | Shell arguments, with the command string appended last. Windows default below               |
+| `primary_modifier`                     | table  | see below     | The modifier `Primary` stands for on each platform. See below                               |
 
 On Windows, `exec_shell` defaults to `%SystemRoot%\System32\cmd.exe`
 (usually `C:\Windows\System32\cmd.exe`) and `exec_shell_args` to `["/c"]`.
 
+`primary_modifier` names the modifier a `Primary` hotkey uses, with one entry
+per platform, so one config file can serve every machine:
+
+```toml
+[general]
+primary_modifier = { darwin = "Cmd", linux = "Super", windows = "Ctrl" }
+```
+
+Each entry is one of `Cmd`, `Ctrl` or `Alt`, or an alias of one from the
+[modifier table](#global-hotkeys). An entry left out keeps its default (`Cmd`
+on macOS, `Ctrl` on Linux and Windows). Platforms other than macOS and Windows
+read `linux`. A reload or `neru config set` applies a change at once, to every
+`Primary` hotkey in every table.
+
 `kb_layout_to_use` decides which physical key a binding answers. Empty picks a
 layout with Latin letters, so bindings stay put while you type in another
 language. To force one, use your platform's name for it:

docs/reference/platform-support.md

@@ -5,7 +5,7 @@ implements it is in the contributor docs.
 
 ## Platform status
 
-| Platform | Status     | Primary modifier | Ships as                          |
+| Platform | Status     | Default `Primary` | Ships as                          |
 | -------- | ---------- | ---------------- | --------------------------------- |
 | macOS 14+     | **Stable** | `Cmd`            | `Neru.app`, codesigned            |
 | Linux    | **Beta**   | `Ctrl`           | Binary and install script         |

internal/adapter/eventtap/linux/global_hotkey_keys.go

@@ -5,6 +5,8 @@ package linux
 import (
 	"sort"
 	"strings"
+
+	"github.com/y3owk1n/neru/internal/domain/action"
 )
 
 // Canonicalizes hotkey chord strings into a stable, order-independent signature
@@ -87,13 +89,16 @@ func chordSignature(chord string, baseKey func(string) string) string {
 }
 
 // canonicalModifierToken maps the many modifier spellings Neru and the various
-// platforms use down to one of four canonical tokens. "Primary" resolves to
-// ctrl here because it is already Ctrl on Linux by the time hotkeys register.
+// platforms use down to one of four canonical tokens. Hotkeys register with
+// Primary already resolved. A "primary" that still reaches this function
+// resolves to the modifier general.primary_modifier set.
 func canonicalModifierToken(token string) string {
 	switch strings.ToLower(strings.TrimSpace(token)) {
+	case "primary":
+		return canonicalModifierToken(action.PrimaryModifier().Canonical())
 	case evdevModifierShift:
 		return evdevModifierShift
-	case evdevModifierCtrl, evdevModifierAliasControl, "primary":
+	case evdevModifierCtrl, evdevModifierAliasControl:
 		return evdevModifierCtrl
 	case evdevModifierAlt, evdevModifierAliasOption, "opt":
 		return evdevModifierAlt

internal/app/config.go

@@ -180,6 +180,10 @@ func (a *App) restoreHotkeysAfterFailedReload() {
 }
 
 func (a *App) updateConfigSnapshot(loadResult *config.LoadResult) {
+	// Publish before the swap, so nothing reads the new configuration's keys
+	// under the old meaning of Primary.
+	config.UsePrimaryModifier(loadResult.Config.General.PrimaryModifier)
+
 	a.configMu.Lock()
 	a.config = loadResult.Config
 	a.ConfigPath = loadResult.ConfigPath

internal/app/ipcctrl/info_health.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/y3owk1n/neru/internal/adapter/ipc"
 	"github.com/y3owk1n/neru/internal/adapter/platform"
+	"github.com/y3owk1n/neru/internal/domain/action"
 	"github.com/y3owk1n/neru/internal/ports"
 )
 
@@ -240,7 +241,7 @@ func capabilitiesMap(capabilities ports.PlatformCapabilities) map[string]any {
 func profileMap(profile platform.Profile) map[string]any {
 	return map[string]any{
 		"os":                          string(profile.OS),
-		"primary_modifier":            profile.PrimaryModifier,
+		"primary_modifier":            action.PrimaryModifier().Canonical(),
 		"display_server":              string(profile.DisplayServer),
 		"accessibility_backend":       profile.Accessibility.Name,
 		"accessibility_build_mode":    string(profile.Accessibility.BuildMode),

internal/app/new.go

@@ -28,6 +28,10 @@ func New(opts ...Option) (*App, error) {
 		app.config = config.DefaultConfig()
 	}
 
+	// Publish before anything binds a hotkey or builds a keymap, since every
+	// key comparison from here on reads it.
+	config.UsePrimaryModifier(app.config.General.PrimaryModifier)
+
 	if app.logger == nil {
 		logger, err := initializeLogger(app.config)
 		if err != nil {

internal/config/config.go

@@ -116,6 +116,10 @@ const (
 	modifierNameCtrl     = "ctrl"
 	modifierNameAlt      = "alt"
 	modifierNameShift    = "shift"
+	modifierDisplayCmd   = "Cmd"
+	modifierDisplayCtrl  = "Ctrl"
+	modifierDisplayAlt   = "Alt"
+	modifierDisplaySuper = "Super"
 )
 
 // Config is the complete application configuration structure.
@@ -167,14 +171,25 @@ type ThemeConfig struct {
 
 // GeneralConfig defines general application-wide settings.
 type GeneralConfig struct {
-	ExcludedApps                      []string `json:"excludedApps"                      toml:"excluded_apps"`
-	PassthroughUnboundedKeys          bool     `json:"passthroughUnboundedKeys"          toml:"passthrough_unbounded_keys"`
-	ShouldExitAfterPassthrough        bool     `json:"shouldExitAfterPassthrough"        toml:"should_exit_after_passthrough"`
-	PassthroughUnboundedKeysBlacklist []string `json:"passthroughUnboundedKeysBlacklist" toml:"passthrough_unbounded_keys_blacklist"`
-	HideOverlayInScreenShare          bool     `json:"hideOverlayInScreenShare"          toml:"hide_overlay_in_screen_share"`
-	KBLayoutToUse                     string   `json:"kbLayoutToUse"                     toml:"kb_layout_to_use"`
-	ExecShell                         string   `json:"execShell"                         toml:"exec_shell"`
-	ExecShellArgs                     []string `json:"execShellArgs"                     toml:"exec_shell_args"`
+	ExcludedApps                      []string              `json:"excludedApps"                      toml:"excluded_apps"`
+	PassthroughUnboundedKeys          bool                  `json:"passthroughUnboundedKeys"          toml:"passthrough_unbounded_keys"`
+	ShouldExitAfterPassthrough        bool                  `json:"shouldExitAfterPassthrough"        toml:"should_exit_after_passthrough"`
+	PassthroughUnboundedKeysBlacklist []string              `json:"passthroughUnboundedKeysBlacklist" toml:"passthrough_unbounded_keys_blacklist"`
+	HideOverlayInScreenShare          bool                  `json:"hideOverlayInScreenShare"          toml:"hide_overlay_in_screen_share"`
+	KBLayoutToUse                     string                `json:"kbLayoutToUse"                     toml:"kb_layout_to_use"`
+	ExecShell                         string                `json:"execShell"                         toml:"exec_shell"`
+	ExecShellArgs                     []string              `json:"execShellArgs"                     toml:"exec_shell_args"`
+	PrimaryModifier                   PrimaryModifierConfig `json:"primaryModifier"                   toml:"primary_modifier"`
+}
+
+// PrimaryModifierConfig names the modifier a hotkey written with Primary means
+// on each platform, so one shared config file can bind Cmd on macOS and Ctrl
+// or Super elsewhere. Every platform that is neither darwin nor windows reads
+// the linux entry.
+type PrimaryModifierConfig struct {
+	Darwin  string `json:"darwin"  toml:"darwin"`
+	Linux   string `json:"linux"   toml:"linux"`
+	Windows string `json:"windows" toml:"windows"`
 }
 
 // ModeIndicatorUI defines the visual/appearance settings for the mode indicator.

internal/config/config_defaults.go

@@ -355,6 +355,17 @@ func defaultGeneral() GeneralConfig {
 		KBLayoutToUse:                     "",
 		ExecShell:                         DefaultExecShell,
 		ExecShellArgs:                     []string{DefaultExecShellFlag},
+		PrimaryModifier:                   defaultPrimaryModifier(),
+	}
+}
+
+// defaultPrimaryModifier is Cmd on macOS, where it is the shortcut modifier,
+// and Ctrl elsewhere, where Super usually belongs to the desktop.
+func defaultPrimaryModifier() PrimaryModifierConfig {
+	return PrimaryModifierConfig{
+		Darwin:  modifierDisplayCmd,
+		Linux:   modifierDisplayCtrl,
+		Windows: modifierDisplayCtrl,
 	}
 }