range: extmarks/tsquery; renderer: text-change

lua/u/renderer.lua

@@ -1,12 +1,33 @@
+function _G.URendererOpFuncSwallow() end
+
+local ENABLE_LOG = false
+
+local function log(...)
+  if not ENABLE_LOG then return end
+
+  local f = assert(io.open(vim.fs.joinpath(vim.fn.stdpath 'log', 'u.renderer.log'), 'a+'))
+  f:write(os.date() .. '\t' .. vim.inspect { ... } .. '\n')
+  f:close()
+end
+
 local M = {}
 local H = {}
 
---- @alias u.renderer.Tag { kind: 'tag'; name: string, attributes: table<string, unknown>, children: u.renderer.Tree }
+--- @alias u.renderer.TagEventHandler fun(tag: u.renderer.Tag, mode: string, lhs: string): string
+
+--- @alias u.renderer.TagAttributes { [string]?: unknown; imap?: table<string, u.renderer.TagEventHandler>; nmap?: table<string, u.renderer.TagEventHandler>; vmap?: table<string, u.renderer.TagEventHandler>; xmap?: table<string, u.renderer.TagEventHandler>; omap?: table<string, u.renderer.TagEventHandler>, on_change?: fun(text: string): unknown }
+
+--- @class u.renderer.Tag
+--- @field kind 'tag'
+--- @field name string
+--- @field attributes u.renderer.TagAttributes
+--- @field children u.renderer.Tree
+
 --- @alias u.renderer.Node nil | boolean | string | u.renderer.Tag
 --- @alias u.renderer.Tree u.renderer.Node | u.renderer.Node[]
 
 -- luacheck: ignore
---- @type table<string, fun(attributes: table<string, any>, children: u.renderer.Tree): u.renderer.Tag> & fun(name: string, attributes: table<string, any>, children: u.renderer.Tree): u.renderer.Tag>
+--- @type table<string, fun(attributes: u.renderer.TagAttributes, children: u.renderer.Tree): u.renderer.Tag> & fun(name: string, attributes: u.renderer.TagAttributes, children: u.renderer.Tree): u.renderer.Tag>
 M.h = setmetatable({}, {
   __call = function(_, name, attributes, children)
     return {
@@ -17,7 +38,6 @@ M.h = setmetatable({}, {
     }
   end,
   __index = function(_, name)
-    -- vim.print('dynamic hl ' .. name)
     return function(attributes, children)
       return M.h('text', vim.tbl_deep_extend('force', { hl = name }, attributes), children)
     end
@@ -25,14 +45,19 @@ M.h = setmetatable({}, {
 })
 
 -- Renderer {{{
---- @alias RendererExtmark { id?: number; start: [number, number]; stop: [number, number]; opts: any; tag: any }
+--- @class u.renderer.RendererExtmark
+--- @field id? number
+--- @field start [number, number]
+--- @field stop [number, number]
+--- @field opts vim.api.keyset.set_extmark
+--- @field tag u.renderer.Tag
 
---- @class u.Renderer
+--- @class u.renderer.Renderer
 --- @field bufnr number
 --- @field ns number
 --- @field changedtick number
---- @field old { lines: string[]; extmarks: RendererExtmark[] }
---- @field curr { lines: string[]; extmarks: RendererExtmark[] }
+--- @field old { lines: string[]; extmarks: u.renderer.RendererExtmark[] }
+--- @field curr { lines: string[]; extmarks: u.renderer.RendererExtmark[] }
 local Renderer = {}
 Renderer.__index = Renderer
 M.Renderer = Renderer
@@ -51,7 +76,7 @@ function Renderer.is_tag_arr(x)
 end
 --- @param bufnr number|nil
 function Renderer.new(bufnr) -- {{{
-  if bufnr == nil then bufnr = vim.api.nvim_get_current_buf() end
+  if bufnr == nil or bufnr == 0 then bufnr = vim.api.nvim_get_current_buf() end
 
   if vim.b[bufnr]._renderer_ns == nil then
     vim.b[bufnr]._renderer_ns = vim.api.nvim_create_namespace('my.renderer:' .. tostring(bufnr))
@@ -64,6 +89,12 @@ function Renderer.new(bufnr) -- {{{
     old = { lines = {}, extmarks = {} },
     curr = { lines = {}, extmarks = {} },
   }, Renderer)
+
+  vim.api.nvim_create_autocmd({ 'TextChanged', 'TextChangedI', 'TextChangedP' }, {
+    buffer = bufnr,
+    callback = function() self:_on_text_changed() end,
+  })
+
   return self
 end -- }}}
 
@@ -128,7 +159,7 @@ function Renderer.markup_to_lines(opts) -- {{{
 end -- }}}
 
 --- @param opts {
----   tree: string;
+---   tree: u.renderer.Tree;
 ---   format_tag?: fun(tag: u.renderer.Tag): string;
 --- }
 function Renderer.markup_to_string(opts) return table.concat(Renderer.markup_to_lines(opts), '\n') end
@@ -136,7 +167,7 @@ function Renderer.markup_to_string(opts) return table.concat(Renderer.markup_to_
 --- @param bufnr number
 --- @param old_lines string[] | nil
 --- @param new_lines string[]
-function Renderer.patch_lines(bufnr, old_lines, new_lines)
+function Renderer.patch_lines(bufnr, old_lines, new_lines) -- {{{
   --
   -- Helpers:
   --
@@ -189,7 +220,7 @@ function Renderer.patch_lines(bufnr, old_lines, new_lines)
       -- No change
     end
   end
-end
+end -- }}}
 
 --- @param tree u.renderer.Tree
 function Renderer:render(tree) -- {{{
@@ -199,7 +230,7 @@ function Renderer:render(tree) -- {{{
     self.changedtick = changedtick
   end
 
-  --- @type RendererExtmark[]
+  --- @type u.renderer.RendererExtmark[]
   local extmarks = {}
 
   --- @type string[]
@@ -214,31 +245,40 @@ function Renderer:render(tree) -- {{{
           tag.attributes.extmark.hl_group = tag.attributes.extmark.hl_group or hl
         end
 
-        local extmark = tag.attributes.extmark
+        local extmark_opts = tag.attributes.extmark or {}
 
         -- Set any necessary keymaps:
         for _, mode in ipairs { 'i', 'n', 'v', 'x', 'o' } do
           for lhs, _ in pairs(tag.attributes[mode .. 'map'] or {}) do
             -- Force creating an extmark if there are key handlers. To accurately
             -- sense the bounds of the text, we need an extmark:
-            extmark = extmark or {}
-            vim.keymap.set(
-              'n',
-              lhs,
-              function() return self:_expr_map_callback('n', lhs) end,
-              { buffer = self.bufnr, expr = true, replace_keycodes = true }
-            )
+            vim.keymap.set(mode, lhs, function()
+              local result = self:_expr_map_callback(mode, lhs)
+              -- If the handler indicates that it wants to swallow the event,
+              -- we have to convert that intention into something compatible
+              -- with expr-mappings, which don't support '<Nop>' (they try to
+              -- execute the literal characters). We'll use the 'g@' operator
+              -- to do that, forwarding the event to an operatorfunc that does
+              -- nothing:
+              if result == '' then
+                if mode == 'i' then
+                  return ''
+                else
+                  vim.go.operatorfunc = 'v:lua.URendererOpFuncSwallow'
+                  return 'g@ '
+                end
+              end
+              return result
+            end, { buffer = self.bufnr, expr = true, replace_keycodes = true })
           end
         end
 
-        if extmark then
-          table.insert(extmarks, {
-            start = start0,
-            stop = stop0,
-            opts = extmark,
-            tag = tag,
-          })
-        end
+        table.insert(extmarks, {
+          start = start0,
+          stop = stop0,
+          opts = extmark_opts,
+          tag = tag,
+        })
       end
     end, -- }}}
   }
@@ -246,27 +286,9 @@ function Renderer:render(tree) -- {{{
   self.old = self.curr
   self.curr = { lines = lines, extmarks = extmarks }
   self:_reconcile()
+  vim.cmd.doautocmd { args = { 'User', 'Renderer:' .. tostring(self.bufnr) .. ':render' } }
 end -- }}}
 
---- @private
---- @param start integer
---- @param end_ integer
---- @param strict_indexing boolean
---- @param replacement string[]
-function Renderer:_set_lines(start, end_, strict_indexing, replacement)
-  vim.api.nvim_buf_set_lines(self.bufnr, start, end_, strict_indexing, replacement)
-end
-
---- @private
---- @param start_row integer
---- @param start_col integer
---- @param end_row integer
---- @param end_col integer
---- @param replacement string[]
-function Renderer:_set_text(start_row, start_col, end_row, end_col, replacement)
-  vim.api.nvim_buf_set_text(self.bufnr, start_row, start_col, end_row, end_col, replacement)
-end
-
 --- @private
 function Renderer:_reconcile() -- {{{
   --
@@ -277,10 +299,15 @@ function Renderer:_reconcile() -- {{{
 
   --
   -- Step 2: reconcile extmarks:
+  -- You may be tempted to try to keep track of which extmarks are needed, and
+  -- only delete those that are not needed. However, each time a tree is
+  -- rendered, brand new extmarks are created. For simplicity, it is better to
+  -- just delete all extmarks, and recreate them.
   --
 
   -- Clear current extmarks:
   vim.api.nvim_buf_clear_namespace(self.bufnr, self.ns, 0, -1)
+
   -- Set current extmarks:
   for _, extmark in ipairs(self.curr.extmarks) do
     extmark.id = vim.api.nvim_buf_set_extmark(
@@ -292,6 +319,13 @@ function Renderer:_reconcile() -- {{{
         id = extmark.id,
         end_row = extmark.stop[1],
         end_col = extmark.stop[2],
+        -- If we change the text starting from the beginning (where the extmark
+        -- is), we don't want the extmark to move to the right.
+        right_gravity = false,
+        -- If we change the text starting from the end (where the end extmark
+        -- is), we don't want the extmark to stay stationary: we want it to
+        -- move to the right.
+        end_right_gravity = true,
       }, extmark.opts)
     )
   end
@@ -306,7 +340,9 @@ function Renderer:_expr_map_callback(mode, lhs) -- {{{
   -- find the tag with the smallest intersection that contains the cursor:
   local pos0 = vim.api.nvim_win_get_cursor(0)
   pos0[1] = pos0[1] - 1 -- make it actually 0-based
-  local pos_infos = self:get_pos_infos(pos0)
+  log('_expr_map_callback: pos0:', pos0)
+  local pos_infos = self:get_tags_at(pos0)
+  log('_expr_map_callback: pos_infos:', pos_infos)
 
   if #pos_infos == 0 then return lhs end
 
@@ -316,9 +352,10 @@ function Renderer:_expr_map_callback(mode, lhs) -- {{{
     local tag = pos_info.tag
 
     -- is the tag listening?
+    --- @type u.renderer.TagEventHandler?
     local f = vim.tbl_get(tag.attributes, mode .. 'map', lhs)
     if type(f) == 'function' then
-      local result = f()
+      local result = f(tag, mode, lhs)
       if result == '' then
         -- bubble-up to the next tag, but set cancel to true, in case there are
         -- no more tags to bubble up to:
@@ -333,31 +370,197 @@ function Renderer:_expr_map_callback(mode, lhs) -- {{{
   return cancel and '' or lhs
 end -- }}}
 
+function Renderer:_on_text_changed() -- {{{
+  -- Reset changedtick, so that the reconciler knows to refresh its cached
+  -- buffer-content before computing the diff:
+  self.changedtick = 0
+
+  --- @type integer, integer
+  local l, c = unpack(vim.api.nvim_win_get_cursor(0))
+  l = l - 1 -- make it actually 0-based
+  local pos_infos = self:get_tags_at({ l, c }, 'i')
+  log('_on_text_changed', { cursor_0_0 = { l, c }, pos_infos = pos_infos })
+  for _, pos_info in ipairs(pos_infos) do
+    local extmark_inf = pos_info.extmark
+    local tag = pos_info.tag
+
+    local on_change = tag.attributes.on_change
+    if on_change and type(on_change) == 'function' then
+      local extmark =
+        vim.api.nvim_buf_get_extmark_by_id(self.bufnr, self.ns, extmark_inf.id, { details = true })
+
+      --- @type integer, integer, vim.api.keyset.extmark_details
+      local start_row0, start_col0, details = unpack(extmark)
+      local end_row0, end_col0 = details.end_row, details.end_col
+      log('_on_text_changed: fetched current extmark for pos_info', {
+        pos_info = pos_info,
+        curr_extmark = {
+          start_row0 = start_row0,
+          start_col0 = start_col0,
+          end_row0 = end_row0,
+          end_col0 = end_col0,
+          details = details,
+        },
+      })
+
+      if start_row0 == end_row0 and start_col0 == end_col0 then
+        on_change ''
+        return
+      end
+
+      local buf_max_line0 = math.max(1, vim.api.nvim_buf_line_count(self.bufnr) - 1)
+      if end_row0 > buf_max_line0 then
+        end_row0 = buf_max_line0
+        local last_line = vim.api.nvim_buf_get_lines(self.bufnr, end_row0, end_row0 + 1, false)[1]
+          or ''
+        end_col0 = last_line:len()
+      end
+      if end_col0 == 0 then
+        end_row0 = end_row0 - 1
+        local last_line = vim.api.nvim_buf_get_lines(self.bufnr, end_row0, end_row0 + 1, false)[1]
+          or ''
+        end_col0 = last_line:len()
+      end
+      log('_on_text_changed: after position correction', {
+        curr_extmark = {
+          start_row0 = start_row0,
+          start_col0 = start_col0,
+          end_row0 = end_row0,
+          end_col0 = end_col0,
+        },
+      })
+
+      if start_row0 == end_row0 and start_col0 == end_col0 then
+        on_change ''
+        return
+      end
+
+      local pos1 = { self.bufnr, start_row0 + 1, start_col0 + 1 }
+      local pos2 = { self.bufnr, end_row0 + 1, end_col0 }
+      local ok, lines = pcall(vim.fn.getregion, pos1, pos2, { type = 'v' })
+      if not ok then
+        log('_on_text_changed: getregion: invalid-pos ', {
+          { pos1, pos2 },
+        })
+        vim.api.nvim_echo({
+          { '(u.nvim:getregion:invalid-pos) ', 'ErrorMsg' },
+          {
+            '{ start, end } = ' .. vim.inspect({ pos1, pos2 }, { newline = ' ', indent = '' }),
+          },
+        }, true, {})
+        error(lines)
+      end
+      local text = table.concat(lines, '\n')
+      on_change(text)
+    end
+  end
+end -- }}}
+
+--- @private
+function Renderer:_debug() -- {{{
+  local prev_w = vim.api.nvim_get_current_win()
+  vim.cmd.vnew()
+  local info_bufnr = vim.api.nvim_get_current_buf()
+  vim.bo.bufhidden = 'delete'
+  vim.bo.buflisted = false
+  vim.bo.buftype = 'nowrite'
+
+  local ids = {}
+  local function cleanup()
+    for _, id in ipairs(ids) do
+      vim.api.nvim_del_autocmd(id)
+    end
+    vim.api.nvim_buf_delete(info_bufnr, { force = true })
+  end
+
+  local function autocmd_callback()
+    if vim.api.nvim_get_current_win() ~= prev_w then return end
+
+    local l, c = unpack(vim.api.nvim_win_get_cursor(0))
+    l = l - 1 -- make it actually 0-based
+
+    local info = {
+      cursor = {
+        pos = { l, c },
+        tags = self:get_tags_at { l, c },
+        extmarks = vim.api.nvim_buf_get_extmarks(
+          self.bufnr,
+          self.ns,
+          { l, c },
+          { l, c },
+          { details = true, overlap = true }
+        ),
+      },
+      computed = {
+        extmarks = self.curr.extmarks,
+      },
+    }
+    vim.api.nvim_buf_set_lines(info_bufnr, 0, -1, true, vim.split(vim.inspect(info), '\n'))
+  end
+
+  table.insert(
+    ids,
+    vim.api.nvim_create_autocmd({ 'CursorMoved', 'CursorMovedI' }, {
+      callback = autocmd_callback,
+    })
+  )
+  table.insert(
+    ids,
+    vim.api.nvim_create_autocmd({ 'User' }, {
+      pattern = 'Renderer:' .. tostring(self.bufnr) .. ':render',
+      callback = autocmd_callback,
+    })
+  )
+  table.insert(
+    ids,
+    vim.api.nvim_create_autocmd('WinClosed', {
+      pattern = tostring(vim.api.nvim_get_current_win()),
+      callback = cleanup,
+    })
+  )
+  table.insert(
+    ids,
+    vim.api.nvim_create_autocmd('WinClosed', {
+      pattern = tostring(prev_w),
+      callback = cleanup,
+    })
+  )
+
+  vim.api.nvim_set_current_win(prev_w)
+end -- }}}
+
 --- Returns pairs of extmarks and tags associate with said extmarks. The
 --- returned tags/extmarks are sorted smallest (innermost) to largest
 --- (outermost).
 ---
 --- @private (private for now)
 --- @param pos0 [number; number]
---- @return { extmark: RendererExtmark; tag: u.renderer.Tag; }[]
-function Renderer:get_pos_infos(pos0) -- {{{
+--- @param mode string?
+--- @return { extmark: u.renderer.RendererExtmark; tag: u.renderer.Tag; }[]
+function Renderer:get_tags_at(pos0, mode) -- {{{
   local cursor_line0, cursor_col0 = pos0[1], pos0[2]
+  if not mode then mode = vim.api.nvim_get_mode().mode end
+  mode = mode:sub(1, 1) -- we don't care about sub-modes
+
+  local raw_overlapping_extmarks = vim.api.nvim_buf_get_extmarks(
+    self.bufnr,
+    self.ns,
+    pos0,
+    pos0,
+    { details = true, overlap = true }
+  )
+  log(
+    'get_tags_at: context:',
+    { pos0 = pos0, mode = mode, raw_overlapping_extmarks = raw_overlapping_extmarks }
+  )
 
   -- The cursor (block) occupies **two** extmark spaces: one for it's left
   -- edge, and one for it's right. We need to do our own intersection test,
   -- because the NeoVim API is over-inclusive in what it returns:
-  --- @type RendererExtmark[]
-  local intersecting_extmarks = vim
-    .iter(
-      vim.api.nvim_buf_get_extmarks(
-        self.bufnr,
-        self.ns,
-        pos0,
-        pos0,
-        { details = true, overlap = true }
-      )
-    )
-    --- @return RendererExtmark
+  --- @type u.renderer.RendererExtmark[]
+  local mapped_extmarks = vim
+    .iter(raw_overlapping_extmarks)
+    --- @return u.renderer.RendererExtmark
     :map(function(ext)
       --- @type number, number, number, { end_row?: number; end_col?: number }|nil
       local id, line0, col0, details = unpack(ext)
@@ -368,13 +571,43 @@ function Renderer:get_pos_infos(pos0) -- {{{
       end
       return { id = id, start = start, stop = stop, opts = details }
     end)
-    --- @param ext RendererExtmark
+    :totable()
+
+  local intersecting_extmarks = vim
+    .iter(mapped_extmarks)
+    --- @param ext u.renderer.RendererExtmark
     :filter(function(ext)
       if ext.stop[1] ~= nil and ext.stop[2] ~= nil then
-        return cursor_line0 >= ext.start[1]
-          and cursor_col0 >= ext.start[2]
-          and cursor_line0 <= ext.stop[1]
-          and cursor_col0 < ext.stop[2]
+        -- If we've "ciw" and "collapsed" an extmark onto the cursor,
+        -- the cursor pos will equal the exmark's start AND end. In this
+        -- case, we want to include the extmark.
+        if
+          cursor_line0 == ext.start[1]
+          and cursor_col0 == ext.start[2]
+          and cursor_line0 == ext.stop[1]
+          and cursor_col0 == ext.stop[2]
+        then
+          return true
+        end
+
+        return
+          -- START: line check
+          cursor_line0 >= ext.start[1]
+            -- START: column check
+            and (cursor_line0 ~= ext.start[1] or cursor_col0 >= ext.start[2])
+            -- STOP: line check
+            and cursor_line0 <= ext.stop[1]
+            -- STOP: column check
+            and (
+              cursor_line0 ~= ext.stop[1]
+              or (
+                mode == 'i'
+                  -- In insert mode, the cursor is "thin", so <= to compensate:
+                  and cursor_col0 <= ext.stop[2]
+                -- In normal mode, the cursor is "wide", so < to compensate:
+                or cursor_col0 < ext.stop[2]
+              )
+            )
       else
         return true
       end
@@ -384,8 +617,8 @@ function Renderer:get_pos_infos(pos0) -- {{{
   -- Sort the tags into smallest (inner) to largest (outer):
   table.sort(
     intersecting_extmarks,
-    --- @param x1 RendererExtmark
-    --- @param x2 RendererExtmark
+    --- @param x1 u.renderer.RendererExtmark
+    --- @param x2 u.renderer.RendererExtmark
     function(x1, x2)
       if
         x1.start[1] == x2.start[1]
@@ -407,10 +640,10 @@ function Renderer:get_pos_infos(pos0) -- {{{
   -- created extmarks in self.curr.extmarks, which also has which tag each
   -- extmark is associated with. Cross-reference with that list to get a list
   -- of tags that we need to fire events for:
-  --- @type { extmark: RendererExtmark; tag: u.renderer.Tag }[]
+  --- @type { extmark: u.renderer.RendererExtmark; tag: u.renderer.Tag }[]
   local matching_tags = vim
     .iter(intersecting_extmarks)
-    --- @param ext RendererExtmark
+    --- @param ext u.renderer.RendererExtmark
     :map(function(ext)
       for _, extmark_cache in ipairs(self.curr.extmarks) do
         if extmark_cache.id == ext.id then return { extmark = ext, tag = extmark_cache.tag } end
@@ -420,10 +653,23 @@ function Renderer:get_pos_infos(pos0) -- {{{
 
   return matching_tags
 end -- }}}
+
+--- @private
+--- @param tag_or_id string | u.renderer.Tag
+--- @return { start: [number, number]; stop: [number, number] } | nil
+function Renderer:get_tag_bounds(tag_or_id) -- {{{
+  for _, x in ipairs(self.curr.extmarks) do
+    local pos = { start = x.start, stop = x.stop }
+    local does_tag_match = type(tag_or_id) == 'string' and x.tag.attributes.id == tag_or_id
+      or x.tag == tag_or_id
+    if does_tag_match then return pos end
+  end
+end -- }}}
+
 -- }}}
 
 -- TreeBuilder {{{
---- @class u.TreeBuilder
+--- @class u.renderer.TreeBuilder
 --- @field private nodes u.renderer.Node[]
 local TreeBuilder = {}
 TreeBuilder.__index = TreeBuilder
@@ -435,7 +681,7 @@ function TreeBuilder.new()
 end
 
 --- @param nodes u.renderer.Tree
---- @return u.TreeBuilder
+--- @return u.renderer.TreeBuilder
 function TreeBuilder:put(nodes)
   table.insert(self.nodes, nodes)
   return self
@@ -444,15 +690,15 @@ end
 --- @param name string
 --- @param attributes? table<string, any>
 --- @param children? u.renderer.Node | u.renderer.Node[]
---- @return u.TreeBuilder
+--- @return u.renderer.TreeBuilder
 function TreeBuilder:put_h(name, attributes, children)
   local tag = M.h(name, attributes, children)
   table.insert(self.nodes, tag)
   return self
 end
 
---- @param fn fun(TreeBuilder): any
---- @return u.TreeBuilder
+--- @param fn fun(tb: u.renderer.TreeBuilder): any
+--- @return u.renderer.TreeBuilder
 function TreeBuilder:nest(fn)
   local nested_writer = TreeBuilder.new()
   fn(nested_writer)
@@ -460,19 +706,40 @@ function TreeBuilder:nest(fn)
   return self
 end
 
+--- @generic T
+--- @param arr T[]
+--- @param f fun(tb: u.renderer.TreeBuilder, item: T, idx: number): any
+function TreeBuilder:ipairs(arr, f)
+  return self:nest(function(tb)
+    for idx, item in ipairs(arr) do
+      f(tb, item, idx)
+    end
+  end)
+end
+
+--- @param tab table
+--- @param f fun(tb: u.renderer.TreeBuilder, key: any, value: any): any
+function TreeBuilder:pairs(tab, f)
+  return self:nest(function(tb)
+    for k, v in pairs(tab) do
+      f(tb, k, v)
+    end
+  end)
+end
+
 --- @return u.renderer.Tree
 function TreeBuilder:tree() return self.nodes end
 -- }}}
 
 -- Levenshtein utility {{{
 -- luacheck: ignore
---- @alias LevenshteinChange<T> ({ kind: 'add'; item: T; index: number; } | { kind: 'delete'; item: T; index: number; } | { kind: 'change'; from: T; to: T; index: number; })
+--- @alias u.renderer.LevenshteinChange<T> ({ kind: 'add'; item: T; index: number; } | { kind: 'delete'; item: T; index: number; } | { kind: 'change'; from: T; to: T; index: number; })
 --- @private
 --- @generic T
 --- @param x `T`[]
 --- @param y T[]
 --- @param cost? { of_delete?: fun(x: T): number; of_add?: fun(x: T): number; of_change?: fun(x: T, y: T): number; }
---- @return LevenshteinChange<T>[] The changes, from last (greatest index) to first (smallest index).
+--- @return u.renderer.LevenshteinChange<T>[] The changes, from last (greatest index) to first (smallest index).
 function H.levenshtein(x, y, cost)
   -- At the moment, this whole `cost` plumbing is not used. Deletes have the
   -- same cost as Adds or Changes. I can imagine a future, however, where
@@ -523,7 +790,7 @@ function H.levenshtein(x, y, cost)
   -- Backtrack to find the changes
   local i = m
   local j = n
-  --- @type LevenshteinChange[]
+  --- @type u.renderer.LevenshteinChange[]
   local changes = {}
 
   while i > 0 or j > 0 do
@@ -540,7 +807,7 @@ function H.levenshtein(x, y, cost)
     if is_first_min(cost_of_change, cost_of_add, cost_of_delete) then
       -- potential change
       if x[i] ~= y[j] then
-        --- @type LevenshteinChange
+        --- @type u.renderer.LevenshteinChange
         local change = { kind = 'change', from = x[i], index = i, to = y[j] }
         table.insert(changes, change)
       end
@@ -548,13 +815,13 @@ function H.levenshtein(x, y, cost)
       j = j - 1
     elseif is_first_min(cost_of_add, cost_of_change, cost_of_delete) then
       -- addition
-      --- @type LevenshteinChange
+      --- @type u.renderer.LevenshteinChange
       local change = { kind = 'add', item = y[j], index = i + 1 }
       table.insert(changes, change)
       j = j - 1
     elseif is_first_min(cost_of_delete, cost_of_change, cost_of_add) then
       -- deletion
-      --- @type LevenshteinChange
+      --- @type u.renderer.LevenshteinChange
       local change = { kind = 'delete', item = x[i], index = i }
       table.insert(changes, change)
       i = i - 1