SmartMotion.nvim Week 2 – Crafting Motions, Recipes, and Experimental Inference

[FluxxField]

Hello everyone!

This is going to be my first update/discussion here on Github. I am planning on trying to do updates every week or so as the plugin grows. Especially right now in these early stages of development

Due to popular demand, I’m going to dive into how you craft your own motions using SmartMotion.nvim. I’ll walk you through how a motion is built, how each part fits together, and how simple changes can radically alter behavior.

We’ve also got a ton of new features to cover:

• modifiers are now part of the motion pipeline
• motion_state has been expanded with new fields for controlling flow and behavior
• The pipeline_wrapper is gone — replaced by a clean and powerful main loop
• And lastly, I’ll introduce inference — a very experimental system for context-aware motion selection

---

🧱 Anatomy of a Motion

Every SmartMotion motion is made up of 5–6 parts:

• Collector: Gathers raw text (usually lines or regions)
• Extractor: Extracts potential targets (e.g., words, characters, JSX tags)
• Filter: Includes or excludes targets based on cursor position or other logic
• Modifier: (Optional) Adds metadata to each target (like distance or weights)
• Visualizer: Determines where and how to show hint labels
• Action: What happens when a user selects a target

Each of these is pluggable, so you can mix and match for powerful custom behavior.

---

🧪 A Simple Example: Jump to Word After Cursor

Let’s say we want to recreate w — jump to the start of the next word.

collector = "lines"
extractor = "words"
filter = "filter_words_after_cursor"
visualizer = "hint_start"
action = "jump_centered"

Want to jump to words before the cursor? Just change the filter:

filter = "filter_words_before_cursor"

Want the hint label to appear at the end of each word? Just change the visualizer:

visualizer = "hint_end"

Don't want centered jumps?

action = "jump"

Same motion, totally different UX — and no new code required.

---

🛠 Recreating Hop, Leap, and Sneak

Here’s where it gets exciting. You can build versions of other popular motion plugins:

Hop-style 2-character search

extractor = "text_search_2_char"
visualizer = "hint_start"
action = "jump"

Sneak-style f/t motions

extractor = "text_search_2_char_until" or "text_search_1_char_until"
filter = "filter_after_cursor"
visualizer = "hint_start"
action = "delete" or "change"

Flash-style live search

extractor = "live_search" -- input grows as you type
modifier = "distance_metadata"
visualizer = "hint_start"
action = "jump"

---

🧠 What is motion_state?

motion_state is the shared state object passed between modules. It holds key data for:

Core Fields

--- @class SmartMotionMotionState
--- @field total_keys integer
--- @field max_lines integer
--- @field max_labels integer
--- @field direction Direction
--- @field hint_position HintPosition
--- @field target_type TargetType
--- @field ignore_whitespace boolean

Target Tracking

--- @field jump_target_count integer
--- @field jump_targets JumpTarget[]
--- @field selected_jump_target? JumpTarget

Hint Labeling

--- @field hint_labels string[]
--- @field assigned_hint_labels table<string, HintEntry>

Label Logic

--- @field single_label_count integer
--- @field double_label_count integer
--- @field sacrificed_keys_count integer

Selection Mode

--- @field selection_mode SelectionMode
--- @field selection_first_char? string

Motion-Specific Fields

These vary based on the extractor/filter:

motion_state.search_text
motion_state.num_of_char
motion_state.should_show_prefix
motion_state.exclude
motion_state.is_searching_mode
motion_state.timeout_after_input

Use motion_state to pass state between parts of your motion — whether it’s how many characters to search, whether to show prefixes, or something custom to your plugin.

---

🚪 Exit Types

Motions exit in different ways. SmartMotion supports the following:

if motion_state.exit_type == EXIT_TYPE.EARLY_EXIT then return end

if motion_state.exit_type == EXIT_TYPE.DIRECT_HINT or EXIT_TYPE.AUTO_SELECT then
  action.run(...)
elseif motion_state.exit_type == EXIT_TYPE.CONTINUE_TO_SELECTION then
  visualizer.run(...)
  selection.wait_for_hint_selection(...)
  action.run(...)
end

---

✨ What Is a Target?

Targets are the core data unit of SmartMotion:

--- @class Target
--- @field bufnr integer
--- @field winid integer
--- @field text? string
--- @field start_pos { row: integer, col: integer }
--- @field end_pos { row: integer, col: integer }
--- @field type string
--- @field filetype string
--- @field metadata? table

Every module works with these. In the future I plan to add more metadata like the motion that created this target. Allowing for powerful repeats and more with a SmartMotion history that is in the works!

---

🧩 Modifiers – Add Metadata, Don't Filter

Modifiers don’t change what targets exist — they just add info.
Example: distance_metadata adds sort_weight so the closest targets can be prioritized visually or logically.

You can write your own modifier to add weights, context, types, etc.

---

🔁 Coroutines for Modules

All modules (collector, extractor, modifier, filter) are coroutines. Why?

• They yield targets as they’re found
• This allows streaming + early exits
• You can handle large buffers efficiently

But don’t worry — you can use the provided module_wrapper to abstract this away. Just write a simple run() function that yields targets or returns a string exit type.

Below is an example of the filter_visible filter. It uses the module_wrapper under the hood. This way things are simple and you only need to write a simple function.

function M.run(ctx, cfg, motion_state, data)
	local top_line = vim.fn.line("w0", ctx.winid) - 1
	local bottom_line = vim.fn.line("w$", ctx.winid) - 1
	local row = data.start_pos.row

	if row >= top_line and row <= bottom_line then
		return data
	end
end

But! What if you need to return more than one target from the data you get? Let's say you recived a line and want to return words from it? Module wrapper can handle this as well. Just a little more complicated. The example below recieves one line at a time and yield multiple words

function M.run(ctx, cfg, motion_state, data)
	return coroutine.create(function()
		local line_text, line_number = data.text, data.line_number
		local search_start = 0

		while true do
			local match_data = vim.fn.matchstrpos(line_text, motion_state.word_pattern, search_start)
			local match_text, start_pos, end_pos = match_data[1], match_data[2], match_data[3]

			if start_pos == -1 then
				break
			end

			coroutine.yield({
				text = match_text,
				start_pos = { row = line_number, col = start_pos },
				end_pos = { row = line_number, col = end_pos },
				type = TARGET_TYPES.WORDS,
			})

			search_start = end_pos + 1
		end
	end)
end

---

🧱 Registering Your Own Modules

SmartMotion is built for plugin interop. Other plugins can register modules:

local my_filter = require("myplugin.smart_filter")
smart_motion.registries.filters.register("smart_before_cursor", my_filter)

You can then build motions using your modules, or expose them to users.

---

🔮 Experimental: Inference

This is still very early — but the goal is:

Press one key, and SmartMotion figures out the right modules based on context. This can make writting keymaps so much simpler

Example: Press d, this triggers smart-motion. It waits for your next key press. Lets say its w. It checks to see if there is an extractor mapped to w. There is! Its the word extractor. Now SmartMotion has everything it needs to do what you were thinking. d tells us the action, which is delete, and w tells us the extractor which is word.

This means, with things like "l" for a line extractor, f/t for a text_search extractor you only need to map SmartMotion to things like d, y, and c and you magically have dt, yf, cl, dw and more! All with 3 mappings

We’re just starting to prototype this, and feedback is welcome!

---

💬 Wrap-up

That’s it for Week 2!

If you’ve built a cool motion or have ideas for new modules, drop them in the comments! If you want to try inference, it’s opt-in — but available to test.

Thanks again for all the support and ideas. More to come in Week 3!