Merge pull request #127 from FluxxField/dev

Selection handlers & pipeline-modifying support

Author: FluxxField

README.md

@@ -424,6 +424,12 @@ SmartMotion wouldn't exist without these plugins. See [Why SmartMotion](https://
   search_idle_timeout_ms = 2000,     -- exit search with no input
   yank_highlight_duration = 150,     -- yank flash duration (ms)
   history_max_age_days = 30,         -- prune history entries older than this
+  selection_keys = {                  -- key-action map during label selection
+    ["<CR>"]  = "select_first",      -- Enter picks the first target
+    ["<M-d>"] = "toggle_direction",  -- Flip search direction
+    ["<M-w>"] = "toggle_multi_window", -- Toggle single/multi-window
+    ["<M-e>"] = "expand_search_scope", -- Double the search scope
+  },
 }
 ```
 

docs/Advanced-Features.md

@@ -84,6 +84,118 @@ ds + ... = delete via search    df + .. = delete via 2-char find
 
 ---
 
+## Selection Handlers
+
+During label selection, special keys can trigger **selection handlers** — registered actions that modify the selection flow. Three built-in handlers ship with SmartMotion.
+
+### Select First / Select Last
+
+Press `<CR>` during label selection to instantly select the first target. This bridges the gap between SmartMotion's label-based selection and vanilla Vim behavior.
+
+Search motions like `f`, `t`, and `s` always require reading and pressing a label, even when you want the closest match. Unlike `dww` (repeat the motion key) or flow state (`jj`), there's no quick shortcut for "just give me the first one."
+
+```
+fa<CR>    jump to the first "a" (vanilla f behavior)
+ta<CR>    jump to just before the first "a" (vanilla t behavior)
+sa<CR>    jump to the first "a" search match
+dw<CR>    delete to the first word target
+```
+
+`select_last` does the inverse — selects the furthest target. Not mapped by default; add it to your config:
+
+```lua
+selection_keys = {
+    ["<CR>"] = "select_first",
+    ["<S-CR>"] = "select_last",
+}
+```
+
+### Toggle Hint Position
+
+Flips hint labels between the start and end of each target. Useful when a hint overlaps text you're trying to read. Not mapped by default:
+
+```lua
+selection_keys = {
+    ["<CR>"] = "select_first",
+    ["<M-h>"] = "toggle_hint_position",
+}
+```
+
+Press the toggle key during label selection — hints re-render at the opposite end of each target. Press it again to flip back. Then pick your label as usual.
+
+### Pipeline-Modifying Handlers
+
+Some selection handlers can re-run the entire motion pipeline during label selection.
+This lets you change the search context without cancelling and re-triggering the motion.
+
+**Built-in pipeline-modifying handlers:**
+
+- `toggle_direction` (`<M-d>`) — Flip between forward and backward search. Press during
+  `w` labels to switch to backward words, or during `s` results to search the other direction.
+
+- `toggle_multi_window` (`<M-w>`) — Toggle between single-window and multi-window target
+  collection. Expand a word motion to show targets across all visible windows.
+
+- `expand_search_scope` (`<M-e>`) — Double the search scope (max_lines). Press multiple
+  times to progressively expand. Useful when the target you want is just outside the
+  initial scope.
+
+**How it works:** When these handlers are triggered, the plugin:
+1. Resets targets and labels
+2. Re-runs the pipeline with the modified `motion_state`
+3. Regenerates and renders new hint labels
+4. Returns to the selection loop for your next keypress
+
+If the re-run produces no targets (e.g., toggling direction when nothing is behind the
+cursor), the motion cancels gracefully.
+
+### Relationship to Other Shortcuts
+
+SmartMotion has several ways to "skip" or modify label selection:
+
+| Method | How | Best for |
+|--------|-----|----------|
+| **Flow state** | Press motion key quickly after a previous motion | Chaining motions (`w` → `w` → `j`) |
+| **Repeat motion key** | Press motion key during labels (`dww`) | Acting on cursor target |
+| **Select first target** | Press `<CR>` during labels | Picking the closest match |
+| **Toggle hint position** | Press configured key during labels | Reading obscured text |
+| **Toggle direction** | Press `<M-d>` during labels | Flipping search direction |
+| **Toggle multi-window** | Press `<M-w>` during labels | Expanding to all windows |
+| **Expand search scope** | Press `<M-e>` during labels | Reaching further targets |
+
+All coexist. Selection handlers are checked after the motion-key-repeat check, so `dww` still works as expected.
+
+### Configuration
+
+Enabled by default with four mappings. The `selection_keys` config maps keys to registered handlers:
+
+```lua
+-- Default
+selection_keys = {
+    ["<CR>"]  = "select_first",
+    ["<M-d>"] = "toggle_direction",
+    ["<M-w>"] = "toggle_multi_window",
+    ["<M-e>"] = "expand_search_scope",
+}
+
+-- Full example
+selection_keys = {
+    ["<CR>"]  = "select_first",
+    ["<S-CR>"] = "select_last",
+    ["<M-h>"] = "toggle_hint_position",
+    ["<M-d>"] = "toggle_direction",
+    ["<M-w>"] = "toggle_multi_window",
+    ["<M-e>"] = "expand_search_scope",
+}
+
+-- Disable
+selection_keys = false
+```
+
+See **[Configuration: Selection Keys](Configuration.md#selection-keys)** for details.
+
+---
+
 ## Operator-Pending Mode
 
 SmartMotion motions work with **any vim operator**.

docs/Configuration.md

@@ -67,6 +67,14 @@ Complete guide to configuring SmartMotion.
 
   -- Prune history entries older than this many days
   history_max_age_days = 30,
+
+  -- Key-action map for label selection (press key to trigger action)
+  selection_keys = {
+    ["<CR>"]  = "select_first",       -- Enter selects the first target
+    ["<M-d>"] = "toggle_direction",   -- Flip search direction
+    ["<M-w>"] = "toggle_multi_window", -- Toggle single/multi-window
+    ["<M-e>"] = "expand_search_scope", -- Double the search scope
+  },
 }
 ```
 
@@ -452,6 +460,98 @@ See **[Advanced Features: Motion History](Advanced-Features.md#motion-history)**
 
 ---
 
+## Selection Keys
+
+Configure special keys that trigger actions during label selection:
+
+```lua
+selection_keys = {
+    ["<CR>"]  = "select_first",
+    ["<M-d>"] = "toggle_direction",
+    ["<M-w>"] = "toggle_multi_window",
+    ["<M-e>"] = "expand_search_scope",
+}
+```
+
+**How it works:**
+1. A motion triggers and labels appear
+2. Instead of pressing a label, press a configured key
+3. The corresponding handler runs
+
+### Built-in Handlers
+
+| Handler Name | Default Key | Return | Description |
+|---|---|---|---|
+| `select_first` | `<CR>` | exits | Selects the first (closest) target |
+| `select_last` | (none) | exits | Selects the last (furthest) target |
+| `toggle_hint_position` | (none) | stays | Toggles hint labels between start/end of targets |
+| `toggle_direction` | `<M-d>` | re-runs | Flips search direction (forward/backward) |
+| `toggle_multi_window` | `<M-w>` | re-runs | Toggles single/multi-window target collection |
+| `expand_search_scope` | `<M-e>` | re-runs | Doubles the search scope (max_lines) |
+
+Add others as needed:
+
+```lua
+selection_keys = {
+    ["<CR>"]  = "select_first",
+    ["<S-CR>"] = "select_last",
+    ["<M-h>"] = "toggle_hint_position",
+    ["<M-d>"] = "toggle_direction",
+    ["<M-w>"] = "toggle_multi_window",
+    ["<M-e>"] = "expand_search_scope",
+}
+```
+
+### Examples
+
+```
+fa<CR>      jump to the first "a" (same as vanilla f)
+sa<CR>      jump to the first "a" match
+dw<CR>      delete to the first word target
+w<M-h>      toggle hints to end-of-word, then pick a label
+w<M-d>      flip to backward words, then pick a label
+s<M-w>      toggle multi-window search, then pick a label
+w<M-e>      double the search scope, then pick a label
+```
+
+### Handler Return Values
+
+Handlers return a value that controls the selection flow:
+
+- **`true`** — accept the selection and exit (like `select_first`, `select_last`)
+- **`false`** — stay in the selection loop and wait for the next keypress (like `toggle_hint_position`)
+- **`"rerun"`** — re-run the full pipeline with modified state, then return to selection (like `toggle_direction`, `toggle_multi_window`, `expand_search_scope`)
+
+### Disable
+
+```lua
+selection_keys = false
+```
+
+### Custom Handlers
+
+Selection handlers are registered modules, just like collectors, extractors, and actions:
+
+```lua
+require("smart-motion").selection_handlers.register("my_handler", {
+    run = function(ctx, cfg, motion_state)
+        -- Modify motion_state, re-render hints, etc.
+        -- Return true to exit selection, false to stay
+        return true
+    end,
+})
+
+-- Then reference it in config:
+selection_keys = {
+    ["<CR>"] = "select_first",
+    ["<Tab>"] = "my_handler",
+}
+```
+
+Keys are normalized via Vim's key notation, so `<CR>`, `<Tab>`, `<M-h>` all work.
+
+---
+
 ## Complete Example
 
 ```lua
@@ -522,6 +622,9 @@ See **[Advanced Features: Motion History](Advanced-Features.md#motion-history)**
 
     -- Keep history for 90 days
     history_max_age_days = 90,
+
+    -- Disable select-first-target (prefer explicit label selection)
+    -- selection_keys = false,
   },
 }
 ```

lua/smart-motion/config.lua

@@ -37,6 +37,12 @@ M.defaults = {
 	search_idle_timeout_ms = 2000,
 	yank_highlight_duration = 150,
 	history_max_age_days = 30,
+	selection_keys = {
+		["<CR>"] = "select_first",
+		["<M-d>"] = "toggle_direction",
+		["<M-w>"] = "toggle_multi_window",
+		["<M-e>"] = "expand_search_scope",
+	},
 }
 
 ---@type SmartMotionConfig
@@ -214,6 +220,27 @@ function M.validate(user_config)
 		config.history_max_age_days = 30
 	end
 
+	--
+	-- Validate selection_keys
+	--
+	if config.selection_keys ~= false then
+		if config.selection_keys ~= nil and type(config.selection_keys) ~= "table" then
+			config.selection_keys = M.defaults.selection_keys
+		end
+
+		if type(config.selection_keys) == "table" then
+			local normalized = {}
+			for key, action in pairs(config.selection_keys) do
+				if type(key) == "string" and type(action) == "string" then
+					normalized[vim.fn.keytrans(key)] = action
+				else
+					log.warn("selection_keys: skipping invalid entry (key=" .. tostring(key) .. ", action=" .. tostring(action) .. ")")
+				end
+			end
+			config.selection_keys = normalized
+		end
+	end
+
 	M.validated = config
 
 	return config

lua/smart-motion/core/registries.lua

@@ -8,6 +8,7 @@ local log = require("smart-motion.core.log")
 --- @field visualizers boolean
 --- @field actions boolean
 --- @field pipeline_wrappers boolean
+--- @field selection_handlers boolean
 --- @field motions boolean
 
 --- @type RegistryConstructors
@@ -19,6 +20,7 @@ local default_registry_constructors = {
 	visualizers = true,
 	actions = true,
 	pipeline_wrappers = true,
+	selection_handlers = true,
 	motions = true,
 }
 

lua/smart-motion/core/selection.lua

@@ -3,9 +3,52 @@ local highlight = require("smart-motion.core.highlight")
 local consts = require("smart-motion.consts")
 local flow_state = require("smart-motion.core.flow_state")
 local targets = require("smart-motion.core.targets")
+local exit_event = require("smart-motion.core.events.exit")
+local pipeline = require("smart-motion.core.engine.pipeline")
+local module_loader = require("smart-motion.utils.module_loader")
 
 local M = {}
 
+--- Re-runs the full pipeline after a selection handler modified motion_state.
+--- Resets state, clears highlights, runs pipeline + visualizer, then recurses to selection.
+--- Mirrors the search-mode re-run pattern in loop.lua.
+---@param ctx SmartMotionContext
+---@param cfg SmartMotionConfig
+---@param motion_state SmartMotionMotionState
+function M._rerun_pipeline(ctx, cfg, motion_state)
+	local state = require("smart-motion.core.state")
+
+	-- Reset selection state (targets, labels, counts)
+	state.reset(motion_state)
+	highlight.clear(ctx, cfg, motion_state)
+
+	-- Re-run pipeline (wrapped to catch exit events like EARLY_EXIT)
+	local exit_type = exit_event.wrap(function()
+		pipeline.run(ctx, cfg, motion_state)
+	end)
+
+	-- If pipeline threw an exit event (e.g., no targets), cancel gracefully
+	if exit_type then
+		log.debug("Pipeline re-run exited with: " .. tostring(exit_type))
+		motion_state.selected_jump_target = nil
+		return
+	end
+
+	local targets_list = motion_state.jump_targets or {}
+	if #targets_list == 0 then
+		log.debug("Pipeline re-run produced no targets")
+		motion_state.selected_jump_target = nil
+		return
+	end
+
+	-- Re-run visualizer to regenerate and render hint labels
+	local visualizer = module_loader.get_module(ctx, cfg, motion_state, "visualizer")
+	visualizer.run(ctx, cfg, motion_state)
+
+	-- Recurse back into selection
+	return M.wait_for_hint_selection(ctx, cfg, motion_state)
+end
+
 --- Waits for the user to press a hint key and handles both single and double character hints.
 ---@param ctx SmartMotionContext
 ---@param cfg SmartMotionConfig
@@ -50,6 +93,31 @@ function M.wait_for_hint_selection(ctx, cfg, motion_state)
 		end
 	end
 
+	-- Selection action keys (e.g., <CR> = select_first, <M-h> = toggle_hint_position)
+	-- Handlers are registered in the selection_handlers registry.
+	-- Return true = accept selection and exit. Return false = stay in selection loop.
+	if cfg.selection_keys then
+		local key_name = vim.fn.keytrans(char)
+		local handler_name = cfg.selection_keys[key_name]
+		if handler_name then
+			local registries = require("smart-motion.core.registries"):get()
+			local handler = registries.selection_handlers.get_by_name(handler_name)
+			if handler then
+				local result = handler.run(ctx, cfg, motion_state)
+				log.debug("Selection handler '" .. handler_name .. "' triggered via " .. key_name)
+
+				if result == "rerun" then
+					return M._rerun_pipeline(ctx, cfg, motion_state)
+				elseif result then
+					return
+				end
+
+				-- Handler returned false: stay in selection, wait for next key
+				return M.wait_for_hint_selection(ctx, cfg, motion_state)
+			end
+		end
+	end
+
 	if flow_state.evaluate_flow_at_selection() and motion_state.selection_mode ~= consts.SELECTION_MODE.SECOND then
 		log.debug("Selection is jumping early")
 		return