[mini.jump2d] Optimized jumping with jump2d

[pkazmier]

I've been experimenting with various configurations in jump2d to improve the perceived latency from initiating a jump to reaching the target destination. The default configuration of jump2d has always left me underwhelmed in this regard. Further, visually, it's rather busy and if you lose sight of your target in step one, it can be hard to find it again as labels obscure so much of the page.

Optimized

Fortunately, jump2d provides several options to tune that experience, so I'm sharing a configuration that feels faster in all regards to me.

require("mini.jump2d").setup({
  labels = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
  view = {
    dim = true,
    n_steps_ahead = 2,
  },
})
vim.keymap.set(
  { "o", "x", "n" },
  "<Cr>",
  "<Cmd>lua MiniJump2d.start(MiniJump2d.builtin_opts.single_character)<CR>",
  { desc = "Jump anywhere" }
)

Rationale

In the default configuration, there are two mental pauses required to reach locations—and not all locations are reachable requiring further movement post jump. By mental pause, I mean you need to wait for a label to appear, visually parse it, and then press the character. With the defaults, you need to do this twice, which feels slow compared to other similar plug-ins. For example, a typical jump sequence using the defaults:

1. Press trigger key.
2. Mental pause waiting, parsing, and pressing the 1st label.
3. Mental pause waiting, parsing, and pressing the 2nd label.
4. Destination reached.

With the optimized configuration above, there is only a single mental pause required thanks to the single_character built-in. A typical jump sequence works like this using the optimized configuration:

1. Press trigger key and target character, which can be done quickly as a sequence because you already know what to type. Effectively, the target character is the 1st label in the default sequence, but without the long mental pause. Further improvements include much less visualize noise with labels as well as the ability to target any location.
2. Mental pause waiting, parsing, and pressing the label(s). If the target character was the only instance of the character, then this step is skipped, making the jump extremely fast. Admittedly, that is rare, so let's talk the typical path. Depending on the frequency of the target character, you'll see one or two labels immediately (thanks to n_steps_ahead). In the case of one label, the number of keys pressed is the same as the default scenario, but with one less mental pauses, so it feels much faster. In the case of two labels, while there may be an additional key press over the default, it still feels faster as there is only one mental pause required because both labels are shown immediately. But, I reduce the chance of the two label scenario by including capital letters in the label set, which is still faster for me than two separate labels.
3. Destination reached.

Demos

Here are several demos showing the default (red bg) and the optimized (green bg) configurations. Below are the lines of code displayed in the videos. For each of demo below, I'll start with the cursor on line 1 and reference the line number that the target is on.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ config-selector.lua                                                                                    │
│────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   1 local wezterm = require("wezterm")                                                                 │
│   2 local sep = package.config:sub(1, 1)                                                               │
│   3                                                                                                    │
│   4 local H = {}                                                                                       │
│   5 local ConfigSelector = {}                                                                          │
│   6                                                                                                    │
│   7 ConfigSelector.new = function(opts)                                                                │
│   8   local self = setmetatable({}, { __index = ConfigSelector })                                      │
│   9   self.title = opts.title or "Config Selector"                                                     │
│  10   self.config_items = {}                                                                           │
│  11   self.active_item_name = nil                                                                      │
│  12                                                                                                    │
│  13   local dir = wezterm.config_dir .. sep .. opts.subdir                                             │
│  14   for _, path in ipairs(wezterm.read_dir(dir)) do                                                  │
│  15     self:register(H.path_to_module_name(path))                                                     │
│  16   end                                                                                              │
│  17                                                                                                    │
│  18   return self                                                                                      │
│  19 end                                                                                                │
│  20                                                                                                    │
│  21 ConfigSelector.register = function(self, module_name)                                              │
│  22   local module = require(module_name)                                                              │
│  23                                                                                                    │
│  24   -- The return value from `init` can be one of the following:                                     │
│  25   --                                                                                               │
│  26   -- 1. "item name"                                                                                │
│  27   -- 2. { label = "item name" }                                                                    │
│  28   -- 3. { label = "item name", value = "item value" }                                              │
│  29   -- 4. { "item name1", "item name2", "item name3" }                                               │
│  30   -- 5. { { label = "item name1" }, "item name2", { label = "item name3", value = "item value" }}  │
│  31   local result = module.init()                                                                     │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯

---

Fast path

Admittedly, it's not often that there is only a single instance of the target character, but it does happen sometimes.

Target: 5 on line 30.

Screen.Recording.2024-07-08.at.10.28.32.AM.mov

Screen.Recording.2024-07-08.at.10.27.52.AM.mov

---

Single label

Target: r in "[r]egister" on line 21.

Screen.Recording.2024-07-08.at.10.31.28.AM.mov

Screen.Recording.2024-07-08.at.10.31.02.AM.mov

---

Dual label

Target: e in "active_item_nam[e]" on line 11.

Screen.Recording.2024-07-08.at.10.36.25.AM.mov

Screen.Recording.2024-07-08.at.10.36.05.AM.mov

---

Unreachable target in default

Target: ( in "read_dir[(]dir)" on line 14.

Screen.Recording.2024-07-08.at.10.41.07.AM.mov

Screen.Recording.2024-07-08.at.10.40.49.AM.mov

---

Dual label with capital letter

This is one of the worst case scenarios, dual letters, with a capital letter. And while the actual number of key presses may be more with the optimized configuration, it still feels faster.

Target: e in "valu[e]" on line 24.

Screen.Recording.2024-07-08.at.10.54.53.AM.mov

Screen.Recording.2024-07-08.at.10.53.09.AM.mov

Conclusion

I absolutely love this new configuration. It's feels so much faster by eliminating that one extra mental pause, reducing visual clutter, and allowing me to target any location on the screen. I now found myself using jump2d more frequently due to these improvements—it's even faster than using f on a single line in all but the case where there is only one of the target character.

I hope others may find this useful as well.

[echasnovski]

Thank you for this PhD-level (in a good way :) ) comment.

I somewhat agree with you about mental pauses. If I remember correctly, the main reason to choose default as it is now was to ensure that any jump can be made only with configured labels. Typing first character can lead to certain inconveniences in some situations:

• Jumping to punctuation characters requires pressing Shift on most keyboard layouts, which I consider a no-go for "jump fast".
• Jumping to non-Latin character can be tricky with all keyboard layout change.

I think I'll try the "jump to single character" as default for a while. I doubt the default spotter in 'mini.jump2d' itself would change, but maybe my default will change :)

[abeldekat]

It took me a while to adapt mentally. Nowadays, I have to be careful to not type to "blazingly" fast, missing the third character...

[abeldekat]

I also tested the double character. Unfortunately, the third character only pops up after typing the second character instead of the first. That causes a slight delay in my typing.

[pkazmier]

So I spent several hours testing leap, jump2d single char, and our jump2d double char implementation above (which does not allow one to target chars at the end of a line). While these are obviously subjective opinions, I did at least measure the amount of time it took to execute jumps. This allowed me to get a better sense of which jumps took longer than others. I wrapped my bindings like this:

local function timeit(f)
  return function()
    local start = vim.loop.hrtime()
    f()
    local elapsed_ms = (vim.loop.hrtime() - start) / 1000000
    vim.notify(string.format("Took %dms", elapsed_ms))
  end
end
vim.keymap.set({"n", "o", "x"}, "<Cr>", timeit(function()
  require("leap").leap({ target_windows = { vim.api.nvim_get_current_win() }})
end))
-- vim.keymap.set({"n", "o", "x"}, "<Cr>", timeit(function()
--     MiniJump2d.start(MiniJump2d.builtin_opts.single_character)
-- end))

Overall Observations

• I find the double char modes problematic when jumping to braces, brackets, parens, backticks, and single/double quotes—especially when targeting either the ( or " in ("hello") for example. Single char mode in jump2d works best in these situations hands down. As such, I prefer my single char jump2 configuration I started this thread with when working with code. If I were writing a book, then I might consider the double char modes.
• As you stated, it did take some time to get accustomed to the two characters modes, but it did become more natural after a while. With a large body of text (non-code), most of my jumps took 700-900ms to complete. For comparison, my single char mode would take 700-900ms for single labels and 950-1100ms for double labels (targeting letters like e that appear everywhere). Leap has an advantage when jumping close to where your cursor is already located and the auto-jump gets you to your destination. Those jumps took around 300ms.
• The double char modes still feel "heavy" to me. The mental burden of having to type the two target characters is likely psychological, but it is very much real. There is an unmeasured mental delay that occurs even before you start a jump because you have to figure out the two characters you need to type. It doesn't show up in the measurements above because this pause is BEFORE the sequence is even activated. With the single char mode, there is no thinking at all. You see the spot where you want to go and press that character. It is very lightweight, as simple to initiate as a f or F. It takes very little mental effort to initiate. And while you may need a double label sometimes, having to press two label keys AFTER the initial key is less taxing to me than having to press two chars FIRST followed by one label key. In the former, there is no hesitation in starting jump, unlike the latter. I want to minimize overhead of initiating to encourage use as often as possible.
• The position of the labels in leap bothers me greatly as they are not placed at the spot of the jump, but two characters later. With jump2d I know where my cursor is going when I’m scanning labels to choose from. Not so with leap, as you need to look back two chars to see where you’ll land. In leap, the theory is that the label appears as soon as you type the first of the two character sequence (even though it’s shown you can’t use it yet), so by the time you enter the second and then the third, the label, you already know what to type. For me, a decent typer, I’ve found this theory useless as I type the first two characters very quickly, so I still need the mental pause to see/parse the label. I’d prefer the label on the target instead.
• Lastly, the jump2d is only 510 lines of Lua code while leap is 2056—that's 4x the size. I moved to mini because of echasnovski's strive for simplicity of implementation. For my use cases, I get a lot of value out of those 500 lines. While not a reason to not use a plug-in, I'm trying to go leaner with my Neovim configuration, so it's an added benefit that I'm able to stay within the mini ecosystem.

So, in conclusion, I'm very happy with the configuration I started this thread with: Jump2d with single char mode and n_steps_ahead for the win!

[ggandor]

@pkazmier I really enjoy these kinds of posts/discussions... even if I don't find some arguments convincing, they push me to collect my thoughts and question implicit assumptions from time to time. If I may join in:

And while you may need a double label sometimes, having to press two label keys AFTER the initial key is less taxing to me than having to press two chars FIRST followed by one label key. In the former, there is no hesitation in starting jump, unlike the latter. I want to minimize overhead of initiating to encourage use as often as possible.

The double char modes still feel "heavy" to me. The mental burden of having to type the two target characters is likely psychological, but it is very much real. There is an unmeasured mental delay that occurs even before you start a jump because you have to figure out the two characters you need to type

Designing a motion plugin, like most things, is all about priorities, there's obviously no one prefect method, without trade-offs, so the key thing is decinding what to optimize for in the first place.

I think it's definitely not sheer time, measured in milliseconds. More like being reasonably quick, while minimizing cognitive load. The latter is hard to measure objectively, yet we can all agree on certain trivialities, like (all other things being equal): inevitable pauses are bad, nonteremminism is bad, having choices is bad, having to react to things instantly is bad, having to read/type more characters is bad, etc.

However, among these, there are things that do reward practice, and things that users cannot improve on or eliminate, no matter what they do.

Typing a 2-character pattern, even typing "weird" bigrams is something you CAN practice for, and get better at with time, not to mention that one can use mappings/aliases (e.g. ' for all kinds of quotes) if this latter is a frequent issue. This also applies to non-Latin characters, mentioned by @echasnovski above.

On the other hand, if the labels appear "just in time", you will ALWAYS have to pause, and if the pattern length is not fixed (Flash), or if there are any choices present (using 1-char/2-char search on a per case basis), you will ALWAYS be in for annoying surprises ("shit, wrong guess, one more keystroke would have been better"). These things cannot be configured away or mitigated with practice, so we'd better eliminate them by design (and in exchange, might expect users to do some homework).

For me, a decent typer, I’ve found this theory useless as I type the first two characters very quickly, so I still need the mental pause to see/parse the label.

I could type quick enough so that the preview becomes useless most of the time, but I won't, exactly because then I can type without pause, keeping the flow. This is especially nice when leaping is part of a more complex operation, so I can keep concentrating on the big picture and the next step ("ultimately I'm copying that paragraph there, to append..."). After a short while, one gets used to typing at a certain (moderate) pace when leaping, instead of typing at maximum speed.

[pkazmier]

@ggandor Based on your comments, I've been testing your plug-in all morning again. One thing has become very apparent. All of these motion plug-ins are amazing pieces of software that make my editing experience so much better. I'm not sure one can go wrong with any choice.

I might have been hasty in stating that leap's pre-labels were not useful for me. I found myself appreciating them when I have to type slower due to difficult to type targets, which brings me to my appreciation of the equivalence classes. They have eliminated the challenges with targets that include brackets/braces/parens and single/double/backquotes.

I noticed that you've added support for treesitter node selection since I last tested leap. This is really nice as I've been struggling to find something I like. I was using treesitters plug-in built-in support for incremental selection, but it requires a lot of keystrokes to get me to the right node.

My preferred setup to minimize as much conflict as possible with the rest of my mini setup. The only mini change I had to make was move mini.surround to gz instead of s as I use leaping far more often than surround.

require("leap").opts.equivalence_classes = { " \t\r\n", "([{", ")]}", "'\"`" }
require("leap.user").set_repeat_keys("<enter>", "<backspace>")

-- I prefer bi-directional searches as the downsides are mostly compensated
-- for by the above set_repeat_keys. I lose dot-repeats, but I'm not using
-- them anyways because I don't want repeat.vim. The other downside is
-- that we don't get as many autojumps, but we'll see how that pans out.
--
-- I had to move mini.surround to gz to make room for this binding.
vim.keymap.set({ "x", "n", "o" }, "s", function()
  require("leap").leap({
    target_windows = { vim.api.nvim_get_current_win() },
  })
end)

-- With bi-directional searching enabled, I use this binding to search other
-- windows. I originally combined them all into one binding to search all
-- windows, but one of leap's benefites is that first autojump, so this helps
-- improve the odds by limiting matches.
vim.keymap.set({ "x", "n", "o" }, "S", function()
  require("leap").leap({
    target_windows = require("leap.util").get_enterable_windows(),
  })
end)

-- I only use remote operations via operating pending mode. This allows me to
-- save wasting another key in my normal mode mappings.
vim.keymap.set({ "o" }, "r", function()
  require("leap.remote").action()
end)

-- This mapping is what LazyVim uses for the built-in treesitter plugin
-- incremental selection, so using it doesn't waste another key in my
-- configuration as I already had this one bound to the same function..
vim.keymap.set({ "n", "x", "o" }, "<C-Space>", function()
  require("leap.treesitter").select()
end)

-- Automatically paste when doing a remote yank operation.
vim.api.nvim_create_augroup("LeapRemote", {})
vim.api.nvim_create_autocmd("User", {
  pattern = "RemoteOperationDone",
  group = "LeapRemote",
  callback = function(event)
    vim.notify(event.data.register)
    -- Do not paste if some special register was in use.
    if vim.v.operator == "y" and event.data.register == "+" then
      vim.cmd("normal! p")
    end
  end,
})

[abeldekat]

I would like to say that the quality of your posts is inspirational.

Following your example, I also put a lot of extra thought in the way I jump. I found a jump2d configuration that now replacesleap.nvim.

@echasnovski: That's number 22...;)

local Jump2d = require("mini.jump2d")

local function map(mode, rhs, opts) -- adapted from mini.jump2d
  local lhs = "<CR>" -- "s"
  opts = vim.tbl_deep_extend("force", { silent = true }, opts or {})
  vim.keymap.set(mode, lhs, rhs, opts)
end
local function start_in_normal_mode()
  local builtin = Jump2d.builtin_opts.word_start
  builtin.view = { n_steps_ahead = 10 }
  Jump2d.start(builtin)
end
local function start()
  local builtin = Jump2d.builtin_opts.single_character
  Jump2d.start(builtin)
end

Jump2d.setup({ mappings = { start_jumping = "" } }) -- no mappings
map("n", start_in_normal_mode, { desc = "Start 2d jumping" })
map({ "x", "o" }, start, { desc = "Start 2d jumping" })

Intent in normal mode using word_start

1. focus on target position
2. start_jumping: All word starts are visible showing all lowercase labels at once
3. insert the labels(mostly two)
4. reached destination
5. fine-tune location if needed using f/F/t/T

Note:

1. One short mental pause(label distribution is somewhat predictable though) after "start jumping"
2. Labels must be lowercase. Uppercase labels disturb the flow.

Intent in visual and operator pending mode using single_character

All characters must be reachable. Speed is less important. No need for n_steps_ahead

Other spotters

1. default: Too crowded. It is harder to correctly focus on the target
2. single_character with n_steps_ahead = 2: The first character needs to be typed as is(some chars are more difficult)

Remote

Leap remote is quite spectacular. However, an extra keymapping is needed. As mini.jump2d also jumps to other windows by default, I think I won't miss the remote functionality. After the remote operation, a manual <ctrl-w>w is not too much to ask

Demo

jumping_all.mp4

[echasnovski]

I remember trying word starts initiall during development, but it felt annoyingly scarce. Hence adding some common targets (word ends plus near punctuation plus camel case words) felt like the best outcome. And there were no n_steps_ahead as an option at the time, so having zero is assumed with default spotter.

[abeldekat]

I understand. Personally, in normal mode, I like that scarcity. Precision limits my speed, especially when being a little bit slow on capital letters. I find that in the exceptional case that I really need to jump to letters in the middle of a word, an extra f/F/t//t/w/b/e does a fine job. Those motions are ingrained in my typing.

[abeldekat]

@echasnovski, I am curious: What is your opinion on the remote jumping provided by both flash and leap?

[echasnovski]

@echasnovski, I am curious: What is your opinion on the remote jumping provided by both flash and leap?

Interesting concept, but I don't think extra mapping to remember and use worth it. (Although I was wrong about gr with similar reasoning ... 🤔 ).

[pkazmier]

I would like to say that the quality of your posts is inspirational.

Thank you! I'm on vacation this week, so I've got more time than usual on my hands 😄 Let's just say I've spent far more time playing with jumpers this week than I ever anticipated doing!

Following your example, I also put a lot of extra thought in the way I jump. I found a jump2d configuration that now replacesleap.nvim.

Welcome back to the club!

local function start_in_normal_mode()
  local builtin = Jump2d.builtin_opts.word_start
  builtin.view = { n_steps_ahead = 10 }
  Jump2d.start(builtin)
end
local function start()
  local builtin = Jump2d.builtin_opts.single_character
  Jump2d.start(builtin)
end
Jump2d.setup({ mappings = { start_jumping = "" } }) -- no mappings
map("n", start_in_normal_mode, { desc = "Start 2d jumping" })
map({ "x", "o" }, start, { desc = "Start 2d jumping" })

It certainly says a lot about @echasnovski's design that we are able to tune jump2d to such a degree, so it fits each of our needs.

[echasnovski]

With all these discussions around 'mini.jump2d', I've remembered a silly anecdote. One of the first things I did after there was a working prototype for narrowing down shown labels was playing around for good several minutes just navigating with binary labels. Something like this:

mini-jump2d_binary-labels.mp4

For some reason I found this amusing. Well, still do 🤣
How many mental pauses do you think this jumping causes on average? 😆

[abeldekat]

Nice! Unfortunately, my brain paused completely when I saw this...;)

[pkazmier]

It's kinda fun! I just tried it myself! Not very efficient, but fun indeed!

[pkazmier]

Oh, and if you're wondering, with single char mode using only j and k as labels, my average response times seem to be around 2000-3200ms!

[abeldekat]

Those labels and the consistency in which they are distributed are really awesome.

I "touch" type on a more than average level. However, my left wrist has restrictions, so the left hand "touch" types using only the pointing finger, like a drummer.

I practiced with mini.jump2d using two windows and quite some code. My guess: I am 25% faster than when using leap.nvim. The left hand, on full speed, does tend to error when using labels on the outer left of the keyboard. Solution: Remove qaz from the labels. Comparing to leap.nvim I now assume a 50% speed increase. Mini.animate has a hard time when I am flying over the words...;)

[drowning-cat]

Auto-confirm query:

local MiniJump2d = require("mini.jump2d")
MiniJump2d.setup({
  mappings = { start_jumping = "" },
  view = { dim = true },
  silent = true,
})
vim.keymap.set("n", "<Tab>", function()
  local timer = assert(vim.uv.new_timer())
  local bounce = 650
  local termcode = function(key)
    return vim.api.nvim_replace_termcodes(key, true, false, true)
  end
  local ns = vim.api.nvim_create_namespace('mini.jump2d_input')
  vim.on_key(function(_, key)
    -- if key == termcode("<Backspace>") then
    --   vim.on_key(nil, ns)
    --   timer:stop()
    --   return
    -- end
    timer:start(bounce, 0, function()
      timer:stop()
      vim.schedule(function()
        vim.api.nvim_feedkeys(termcode("<Enter>"), "n", false)
      end)
    end)
  end, ns)
  vim.ui.input({ prompt = "(mini.jump2d) Enter search query: " }, function(input)
    vim.on_key(nil, ns)
    timer:close()
    if input and input ~= "" then
      MiniJump2d.start({
        spotter = MiniJump2d.gen_spotter.vimpattern(string.format([[\v%s\c]], input)),
        allowed_lines = { blank = false },
      })
    end
  end)
end, { desc = "Jump2d" })

[drowning-cat]

Ideally, if I had access to input, I would check whether it is an empty string or whether the pattern is searchable before auto-confirming.

[drowning-cat]

There is also an interesting trick. By providing just a few characters, we narrow the search significantly. Since there are not many possible results, we can assign letters in an order that makes them easier to press on the keyboard. For example, you could use:

labels = "qwertyasdfghzxcvbuiopjklnm"
labels = "asdfjklghqwertyuiopzxcvbnm"
labels = "etaoinshrdlcumwfgypbvkjxqz"