feat(modes): add support for user declared custom mode (#1629)

Author: y3owk1n

README.md

@@ -167,6 +167,7 @@ neru hints          # trigger hints mode
 neru grid           # trigger grid mode
 neru recursive_grid # trigger recursive grid mode
 neru scroll         # trigger scroll mode
+neru mode window    # enter a mode you declared in config
 neru config reload  # hot-reload config without restarting
 neru status         # check daemon state and permissions
 ```

configs/default-config.toml

@@ -60,6 +60,22 @@ text = "#E8EEFF"
 # [hints.hotkeys]
 # "Enter" = "macro click_and_exit"
 
+# Declared modes — a keymap with a name and an indicator, no logic of its own.
+# Enter one with "mode <name>" from a hotkey, a sequence step, or `neru mode
+# <name>`. Escape returns to idle unless the mode rebinds it.
+# See https://github.com/y3owk1n/neru/blob/main/docs/CONFIGURATION.md#modes
+#
+# [modes.window]
+# indicator = "Window"
+#
+# [modes.window.hotkeys]
+# "h" = "exec yabai -m window --focus west"
+# "l" = "exec yabai -m window --focus east"
+# "s" = "scroll"
+#
+# [hotkeys]
+# "Primary+Shift+W" = "mode window"
+
 # Hint mode
 # See https://github.com/y3owk1n/neru/blob/main/docs/CONFIGURATION.md#hints
 [hints]

docs/CLI.md

@@ -19,7 +19,7 @@ The same content is available as manpages (`man neru`) after installation.
 - [Global flags](#global-flags)
 - [Command index](#command-index)
 - [Daemon lifecycle](#daemon-lifecycle) — `launch` · `start` · `stop` · `idle` · `status` · `doctor`
-- [Navigation modes](#navigation-modes) — `hints` · `grid` · `recursive_grid` · `scroll` · `monitor_select`
+- [Navigation modes](#navigation-modes) — `hints` · `grid` · `recursive_grid` · `scroll` · `monitor_select` · `mode`
 - [Actions](#actions) — `action` and its subcommands
 - [Sequences](#sequences) — `run` · `macro`
 - [Configuration commands](#configuration-commands) — `config`
@@ -90,6 +90,7 @@ Accepted by every command.
 | [`recursive_grid`](#neru-recursive_grid)                     | Recursive cell navigation       | Yes | All |
 | [`scroll`](#neru-scroll)                                     | Vim-style scrolling             | Yes | All |
 | [`monitor_select`](#neru-monitor_select)                     | Jump the cursor to a display    | Yes | macOS · Linux |
+| [`mode`](#neru-mode)                                         | Enter a mode declared in config | Yes | All |
 | [`action`](#actions)                                         | One-shot mouse/scroll/key input | Yes | All ² |
 | [`run`](#neru-run)                                           | Run several actions in order    | Yes | All |
 | [`macro`](#neru-macro)                                       | Run a named sequence from config | Yes | All |
@@ -189,7 +190,7 @@ Requires a running daemon.
 | Field    | Values                                                  |
 | -------- | ------------------------------------------------------- |
 | `Status` | `running`, `disabled`                                   |
-| `Mode`   | `idle`, `hints`, `grid`, `recursive_grid`, `scroll`, `monitor_select` |
+| `Mode`   | `idle`, `hints`, `grid`, `recursive_grid`, `scroll`, `monitor_select`, or the name of the open [declared mode](CONFIGURATION.md#modes) |
 
 **JSON output**
 
@@ -270,8 +271,8 @@ the check. The full set is
 
 # Navigation modes
 
-Modes take over the keyboard until you select a target or exit. All five
-require a running daemon.
+Modes take over the keyboard until you select a target or exit. Every mode
+command requires a running daemon.
 
 ## Mode flag reference
 
@@ -295,7 +296,7 @@ nothing.
 | `--modifier` |  | value | `hints` · `grid` · `recursive_grid` | Comma-separated modifier keys to hold during action (cmd, super, meta, shift, alt, option, ctrl) (requires --action) |
 | `--on-exit` |  | value, repeatable | `hints` · `grid` · `recursive_grid` | Step to run after the action is fulfilled and the mode exits (same syntax as hotkeys, e.g. 'action left_click' or 'exec notify-send done'). Repeat the flag to run several steps in order. Requires --action; not run on manual escape/idle |
 | `--repeat` | `-r` | none | `hints` · `grid` · `recursive_grid` | Re-activate mode after performing the action (requires --action) |
-| `--toggle` | `-t` | none | `hints` · `grid` · `recursive_grid` · `scroll` · `monitor_select` | Toggle mode on/off (exit to idle if already active) |
+| `--toggle` | `-t` | none | `hints` · `grid` · `recursive_grid` · `scroll` · `monitor_select` · `mode` | Toggle mode on/off (exit to idle if already active) |
 | `--search` | `-s` | none | `hints` | Show search input when the mode is activated |
 | `--hide-on-empty-search` |  | none | `hints` | Hide all hints when search query is empty (requires --search) |
 | `--role` |  | value, repeatable | `hints` | Filter by element role (comma-separated: button,link — the hints.clickable_roles vocabulary, see 'neru roles'). Repeat the flag to add more |
@@ -522,6 +523,35 @@ neru monitor_select --toggle
 
 ---
 
+## neru mode
+
+Enter a mode you declared under [`[modes.<name>]`](CONFIGURATION.md#modes).
+
+```
+neru mode <name> [flags]
+```
+
+A declared mode has no logic of its own: it captures the keyboard, shows its
+indicator, and answers every key from its own `[modes.<name>.hotkeys]` table.
+`Escape` returns to idle unless the table rebinds it. The same command is a
+binding step, `"mode <name>"`, from any hotkey table or macro.
+
+**Flags** — every flag listed for `mode` in the
+[mode flag reference](#mode-flag-reference): `--toggle` and nothing else, since
+a declared mode makes no selection.
+
+A name nothing declares is refused with `ERR_INVALID_INPUT`, the same way a
+binding into one is refused at load.
+
+**Examples**
+
+```bash
+neru mode window
+neru mode window --toggle
+```
+
+---
+
 # Actions
 
 One-shot input that runs without entering a mode. All action subcommands
@@ -1631,8 +1661,9 @@ scripts are safe.
 ```
 
 `action` names either a mode command — `hints`, `grid`, `recursive_grid`,
-`scroll`, `monitor_select`, `idle` — or one of the standalone commands. `args`
-carries the same flags a user would type.
+`scroll`, `monitor_select`, `idle`, or `mode` with the declared name as the
+first entry of `args` — or one of the standalone commands. `args` carries the
+same flags a user would type.
 
 A mode command's flags are read exactly as the CLI reads them, and answered
 with the same message: an unknown flag, a flag the named mode does not accept,

docs/CONFIGURATION.md

@@ -31,6 +31,7 @@ keeps its default. "The daemon" below means the process started by
 | Section                                       | Controls                                     |
 | --------------------------------------------- | -------------------------------------------- |
 | [`[macros]`](#macros)                         | Named action sequences reused across bindings |
+| [`[modes]`](#modes)                           | Modes you declare: a keymap and an indicator  |
 | [`[general]`](#general)                       | Global behaviour, passthrough, `exec` shell   |
 | [`[theme]`](#theme)                           | Base palette all components derive from       |
 | [`[hints]`](#hints)                           | Hints mode and element discovery              |
@@ -710,6 +711,70 @@ shares the same definition rather than keeping its own copy:
 neru macro window_click 100 70
 ```
 
+---
+
+## [modes]
+
+Modes you declare yourself. A declared mode has no logic of its own: it is a
+name, an indicator label, and a hotkey table. While it is open Neru captures
+the keyboard, shows the indicator, and answers every key from that table, the
+way [scroll mode](#scroll) does with its own. Use one as a layer: a set of
+bare-letter bindings that only mean something after you enter the mode.
+
+```toml
+[modes.window]
+indicator = "Window"            # mode-indicator text; "" hides it
+
+[modes.window.hotkeys]
+"h" = "exec yabai -m window --focus west"
+"l" = "exec yabai -m window --focus east"
+"f" = ["exec yabai -m window --toggle zoom-fullscreen", "idle"]
+"s" = "scroll"                  # mode-to-mode transition, like any other
+
+[hotkeys]
+"Primary+Shift+W" = "mode window"
+```
+
+**Entering one.** The step is `mode <name>`, from a global hotkey, a macro, a
+`run`, or the command line as [`neru mode <name>`](CLI.md#neru-mode). It
+accepts `--toggle` and nothing else: a declared mode makes no selection, so
+none of the selection flags apply. A step naming a mode that is not declared
+is refused at load, like a typo'd flag.
+
+**Leaving one.** `Escape` is bound to `idle` by default, as it is in every
+mode, and `"Escape" = "__disabled__"` removes it. Any binding whose steps end
+in `idle` or another mode leaves too. While the mode is open, an unbound
+Ctrl/Alt/Cmd chord falls back to `[hotkeys]` under the
+[usual precedence](#per-mode-hotkeys); an unbound bare key is swallowed, as
+in scroll mode.
+
+### Options
+
+| Option      | Type   | Default | Description                                                 |
+| ----------- | ------ | ------- | ----------------------------------------------------------- |
+| `indicator` | string | `""`    | [Mode indicator](#mode_indicator) text while the mode is open; empty hides it |
+| `hotkeys`   | map    | `{ "Escape" = "idle" }` | The mode's [hotkeys](#per-mode-hotkeys), merged over the default |
+
+The name is the table key: letters, digits, `_` and `-`, starting with a
+letter. A built-in mode's name (`hints`, `grid`, `recursive_grid`, `scroll`,
+`monitor_select`, `idle`) and the word `mode` are refused.
+
+### Per-App Config
+
+| Field       | Type   | Description                                           |
+| ----------- | ------ | ----------------------------------------------------- |
+| `bundle_id` | string | App bundle ID                                         |
+| `hotkeys`   | map    | [per-app hotkey overrides](#per-app-hotkey-overrides) |
+
+```toml
+[[modes.window.app_configs]]
+bundle_id = "com.apple.Safari"
+hotkeys = { "h" = "action scroll_left", "l" = "action scroll_right" }
+```
+
+The indicator's style comes from [`[mode_indicator.ui]`](#mode_indicator),
+shared with the built-in modes.
+
 ## [general]
 
 Global behaviour that is not tied to a single mode: app exclusions, keyboard

internal/adapter/overlay/adapter.go

@@ -97,7 +97,7 @@ func (a *Adapter) ShowFrame(ctx context.Context, frame ports.Frame) error {
 		return err
 	}
 
-	mode, modeErr := overlayMode(frame.Mode())
+	mode, modeErr := frameSurface(frame)
 	if modeErr != nil {
 		return modeErr
 	}
@@ -128,7 +128,9 @@ func (a *Adapter) ShowFrame(ctx context.Context, frame ports.Frame) error {
 // Linux the mode and sticky-modifier indicators are badges painted on that
 // surface: the shared window's visibility is theirs. Deciding otherwise would
 // encode macOS's one-window-per-indicator model in shared code and leave a
-// Linux user in scroll mode with no indicator after a monitor move.
+// Linux user in scroll mode with no indicator after a monitor move. A declared
+// mode draws nothing of its own either, and needs the window for the same
+// reason.
 //
 // Every mode is named rather than defaulted, so a mode added without an answer
 // here fails the `exhaustive` linter instead of silently inheriting one. The
@@ -139,7 +141,7 @@ func drawsOnSharedWindow(frame ports.Frame) bool {
 	case domain.ModeMonitorSelect:
 		return false
 	case domain.ModeHints, domain.ModeGrid, domain.ModeRecursiveGrid,
-		domain.ModeScroll, domain.ModeIdle:
+		domain.ModeScroll, domain.ModeCustom, domain.ModeIdle:
 		return true
 	}
 
@@ -371,6 +373,20 @@ func (a *Adapter) UpdateGridPointer(mode domain.Mode, pointer ports.GridPointer)
 	)
 }
 
+// frameSurface names the overlay mode a frame is realized in.
+//
+// A declared mode's frame is the one case where the enum is not the name: every
+// declaration shares domain.ModeCustom, and the overlay tells them apart by the
+// declared name, which is what the indicator's label is looked up by. So the
+// surface is the name itself, and the built-in modes go through overlayMode.
+func frameSurface(frame ports.Frame) (Mode, error) {
+	if custom, isCustom := frame.(ports.CustomFrame); isCustom {
+		return Mode(custom.Name), nil
+	}
+
+	return overlayMode(frame.Mode())
+}
+
 // overlayMode translates a mode into the overlay's own name for it. The two
 // vocabularies share their spelling deliberately; a mode this overlay has none
 // for is reported rather than drawn in whatever mode happened to be current.

internal/adapter/overlay/manager/components.go

@@ -100,7 +100,12 @@ func (b *Base) BuildComponents(spec ComponentSpec) (Components, error) {
 		}
 	}
 
-	modeIndicator, err := modeindicator.NewOverlay(cfg.ModeIndicator, spec.Theme, logger)
+	modeIndicator, err := modeindicator.NewOverlay(
+		cfg.ModeIndicator,
+		cfg.CustomModeIndicators(),
+		spec.Theme,
+		logger,
+	)
 	if err != nil {
 		logger.Warn("Failed to build the mode indicator overlay", zap.Error(err))
 	} else {
@@ -193,7 +198,7 @@ func (b *Base) ConfigureComponents(cfg *config.Config, pointer PointerAppearance
 	}
 
 	if overlay := b.modeIndicatorOverlay; overlay != nil {
-		overlay.SetConfig(cfg.ModeIndicator)
+		overlay.SetConfig(cfg.ModeIndicator, cfg.CustomModeIndicators())
 	}
 
 	if overlay := b.stickyModifiersOverlay; overlay != nil {

internal/adapter/overlay/render/modeindicator/custom.go

@@ -0,0 +1,20 @@
+package modeindicator
+
+import "github.com/y3owk1n/neru/internal/config"
+
+// customModeConfig is the per-mode indicator config of a declared mode, or nil
+// for a name no declaration gave a label.
+//
+// A declared mode has no [mode_indicator.<name>] section: its text is the
+// declaration's, and its colors are left zero so every backend falls back to
+// [mode_indicator.ui] through the same override it applies to a built-in mode
+// without colors of its own. Enabled is what the non-darwin label resolution
+// checks, and a label that exists is one that is shown.
+func customModeConfig(customLabels map[string]string, mode string) *config.ModeIndicatorModeConfig {
+	label, declared := customLabels[mode]
+	if !declared {
+		return nil
+	}
+
+	return &config.ModeIndicatorModeConfig{Enabled: true, Text: label}
+}

internal/adapter/overlay/render/modeindicator/overlay_darwin.go

@@ -35,8 +35,12 @@ const (
 type Overlay struct {
 	window          C.OverlayWindow
 	indicatorConfig config.ModeIndicatorConfig
-	theme           config.ThemeProvider
-	logger          *zap.Logger
+	// customLabels is the indicator text of every declared mode that has one,
+	// by name. A declared mode has no per-mode section of its own: its label
+	// is the declaration's, and its colors are the shared UI defaults.
+	customLabels map[string]string
+	theme        config.ThemeProvider
+	logger       *zap.Logger
 
 	// styleCache holds cached C style strings for the currently drawn mode.
 	// It is shared across all modes and invalidated on mode change via
@@ -65,6 +69,7 @@ type Overlay struct {
 // NewOverlay creates a new mode indicator overlay instance with its own window.
 func NewOverlay(
 	indicatorCfg config.ModeIndicatorConfig,
+	customLabels map[string]string,
 	theme config.ThemeProvider,
 	logger *zap.Logger,
 ) (*Overlay, error) {
@@ -76,6 +81,7 @@ func NewOverlay(
 	return &Overlay{
 		window:          (C.OverlayWindow)(base.Window),
 		indicatorConfig: indicatorCfg,
+		customLabels:    customLabels,
 		theme:           theme,
 		logger:          logger,
 		styleCache:      base.StyleCache,
@@ -277,10 +283,15 @@ func (o *Overlay) DrawModeIndicator(mode string, xCoordinate, yCoordinate int) {
 	C.NeruDrawHints(o.window, &hint, 1, style)
 }
 
-// SetConfig sets the overlay configuration.
-func (o *Overlay) SetConfig(indicatorCfg config.ModeIndicatorConfig) {
+// SetConfig sets the overlay configuration, and the labels of the declared
+// modes alongside it.
+func (o *Overlay) SetConfig(
+	indicatorCfg config.ModeIndicatorConfig,
+	customLabels map[string]string,
+) {
 	o.configMu.Lock()
 	o.indicatorConfig = indicatorCfg
+	o.customLabels = customLabels
 	o.configMu.Unlock()
 	// Invalidate caches when config changes
 	o.freeAllCaches()
@@ -319,7 +330,7 @@ func (o *Overlay) resolveModeConfig(mode string) *config.ModeIndicatorModeConfig
 	case domain.ModeNameRecursiveGrid:
 		return &o.indicatorConfig.RecursiveGrid
 	default:
-		return nil
+		return customModeConfig(o.customLabels, mode)
 	}
 }