Rework pos types, add types for mark utils

DOC.md

@@ -4040,7 +4040,7 @@ Expand a snippet in the current buffer.
 * `opts?: LuaSnip.Opts.SnipExpand?` Optional additional arguments.  
   Valid keys are:
 
-  * `clear_region?: LuaSnip.BufferRegion?` A region of text to clear after populating env-variables,
+  * `clear_region?: LuaSnip.RawRegion00?` A region of text to clear after populating env-variables,
     but before jumping into `snip`. If `nil`, no clearing is performed. Being able to remove text at
     this point is useful as clearing before calling this function would populate `TM_CURRENT_LINE`
     and `TM_CURRENT_WORD` with wrong values (they would miss the snippet trigger). The actual values
@@ -4066,8 +4066,8 @@ Expand a snippet in the current buffer.
     * `captures?: string[]?` Set as the expanded snippets' captures (Defaults to `{}`).
     * `env_override?: { [string]: string }?` Set or override environment variables of the expanded
       snippet (Defaults to `{}`).
-  * `pos?: (integer,integer)?` Position at which the snippet should be inserted. Pass as
-    `(row,col)`, both 0-based, the `col` given in bytes.
+  * `pos?: LuaSnip.RawPos00?` Position at which the snippet should be inserted. Pass as `(row,col)`,
+    both 0-based, the `col` given in bytes.
   * `indent?: boolean?` Whether to prepend the current lines' indent to all lines of the snippet.
     (Defaults to `true`) Turning this off is a good idea when a LSP server already takes indents
     into consideration. In such cases, LuaSnip should not add additional indents. If you are using
@@ -4295,8 +4295,7 @@ Lookup a node by position and activate (ie. jump into) it.
   * `strict?: boolean?` Only activate nodes one could usually jump to. (Defaults to false)
   * `select?: boolean?` Whether to select the entire node, or leave the cursor at the position it is
     currently at. (Defaults to true)
-  * `pos?: LuaSnip.BytecolBufferPosition?` Where to look for the node. (Defaults to the position of
-    the cursor)
+  * `pos?: LuaSnip.RawPos00?` Where to look for the node. (Defaults to the position of the cursor)
 
 Not covered in this section are the various node-constructors exposed by
 the module, their usage is shown either previously in this file or in

doc/luasnip.txt

@@ -1,4 +1,4 @@
-*luasnip.txt*         For NeoVim 0.7-0.11         Last change: 2026 January 19
+*luasnip.txt*         For NeoVim 0.7-0.11         Last change: 2026 January 23
 
 ==============================================================================
 Table of Contents                                  *luasnip-table-of-contents*
@@ -3966,7 +3966,7 @@ Expand a snippet in the current buffer.
 - `snippet: LuaSnip.Snippet` The snippet.
 - `opts?: LuaSnip.Opts.SnipExpand?` Optional additional arguments.
   Valid keys are:
-  - `clear_region?: LuaSnip.BufferRegion?` A region of text to clear after
+  - `clear_region?: LuaSnip.RawRegion00?` A region of text to clear after
     populating env-variables, but before jumping into `snip`. If `nil`, no clearing
     is performed. Being able to remove text at this point is useful as clearing
     before calling this function would populate `TM_CURRENT_LINE` and
@@ -3993,7 +3993,7 @@ Expand a snippet in the current buffer.
       `{}`).
     - `env_override?: { [string]: string }?` Set or override environment
       variables of the expanded snippet (Defaults to `{}`).
-  - `pos?: (integer,integer)?` Position at which the snippet should be inserted.
+  - `pos?: LuaSnip.RawPos00?` Position at which the snippet should be inserted.
     Pass as `(row,col)`, both 0-based, the `col` given in bytes.
   - `indent?: boolean?` Whether to prepend the current lines’ indent to all lines
     of the snippet. (Defaults to `true`) Turning this off is a good idea when a LSP
@@ -4261,8 +4261,8 @@ Lookup a node by position and activate (ie. jump into) it.
     to false)
   - `select?: boolean?` Whether to select the entire node, or leave the cursor
     at the position it is currently at. (Defaults to true)
-  - `pos?: LuaSnip.BytecolBufferPosition?` Where to look for the node. (Defaults
-    to the position of the cursor)
+  - `pos?: LuaSnip.RawPos00?` Where to look for the node. (Defaults to the
+    position of the cursor)
 
 Not covered in this section are the various node-constructors exposed by the
 module, their usage is shown either previously in this file or in

lua/luasnip/_types.lua

@@ -1,18 +1,23 @@
+---@class LuaSnip.Pos00 A [row, col] position (e.g. in a buffer), (0,0)-indexed.
+---@field [1] integer
+---@field [2] integer
+
 ---@alias LuaSnip.Cursor {[1]: number, [2]: number}
 
----@class LuaSnip.MatchRegion 0-based region within a single line
+---@class LuaSnip.Region00InLine 0-based region within a single line
 ---@field row integer 0-based row
 ---@field col_range { [1]: integer, [2]: integer } 0-based column range, from-in, to-exclusive
 
+--- A raw (byte) [row, col] position in a buffer, (0,0)-indexed.
 --- Specifies a position in a buffer, or some other collection of lines. (0,0) is
 --- the first line, first character, and the column-position is specified in
 --- bytes, not visual columns (there are characters that are visually one column,
 --- but occupy several bytes).
----@class LuaSnip.BytecolBufferPosition
+---@class LuaSnip.RawPos00
 ---@field [1] integer
 ---@field [2] integer
 
---- 0-based region in a buffer.
----@class LuaSnip.BufferRegion
----@field from LuaSnip.BytecolBufferPosition Starting position, included.
----@field to LuaSnip.BytecolBufferPosition Ending position, excluded.
+--- 0-based region (end column excluded) in a buffer.
+---@class LuaSnip.RawRegion00
+---@field from LuaSnip.RawPos00 Starting position, included.
+---@field to LuaSnip.RawPos00 Ending position, excluded.

lua/luasnip/extras/_treesitter.lua

@@ -28,7 +28,7 @@ local function inspect_node(node)
 end
 
 ---@param bufnr number
----@param region LuaSnip.MatchRegion
+---@param region LuaSnip.Region00InLine
 ---@return vim.treesitter.LanguageTree, string
 local function reparse_buffer_after_removing_match(bufnr, region)
 	local lang = get_lang(bufnr)
@@ -56,11 +56,11 @@ end
 ---@class LuaSnip.extra.FixBufferContext
 ---@field ori_bufnr number
 ---@field ori_text string
----@field region LuaSnip.MatchRegion
+---@field region LuaSnip.Region00InLine
 local FixBufferContext = {}
 
 ---@param ori_bufnr number
----@param region LuaSnip.MatchRegion
+---@param region LuaSnip.Region00InLine
 ---@return LuaSnip.extra.FixBufferContext
 function FixBufferContext.new(ori_bufnr, region, region_content)
 	local o = {
@@ -291,10 +291,10 @@ function TSParser.new(bufnr, parser, source)
 	return o
 end
 
----@param pos { [1]: number, [2]: number }?
+---@param pos LuaSnip.RawPos00
 ---@return TSNode?
 function TSParser:get_node_at_pos(pos)
-	pos = vim.F.if_nil(pos, util.get_cursor_0ind())
+	local pos = pos or util.get_cursor_0ind()
 	local row, col = pos[1], pos[2]
 	assert(
 		row >= 0 and col >= 0,
@@ -308,7 +308,7 @@ function TSParser:get_node_at_pos(pos)
 end
 
 ---Get the root for the smallest tree containing `pos`.
----@param pos { [1]: number, [2]: number }
+---@param pos LuaSnip.RawPos00
 ---@return TSNode?
 function TSParser:root_at(pos)
 	local tree = self.parser:tree_for_range(
@@ -323,7 +323,7 @@ function TSParser:root_at(pos)
 end
 
 ---@param match_opts LuaSnip.extra.EffectiveMatchTSNodeOpts
----@param pos { [1]: number, [2]: number }
+---@param pos LuaSnip.RawPos00
 ---@return LuaSnip.extra.NamedTSMatch?, TSNode?
 function TSParser:match_at(match_opts, pos)
 	-- Since we want to find a match to the left of pos, and if we accept there

lua/luasnip/extras/treesitter_postfix.lua

@@ -43,7 +43,7 @@ local function generate_match_tsnode_func(opts)
 	end
 
 	---@param parser LuaSnip.extra.TSParser
-	---@param pos { [1]: number, [2]: number }
+	---@param pos LuaSnip.RawPos00
 	return function(parser, pos)
 		return parser:match_at(
 			match_opts, --[[@as LuaSnip.extra.MatchTSNodeOpts]]
@@ -140,7 +140,7 @@ local function generate_resolve_expand_param(match_tsnode, user_resolver)
 	---@param parser vim.treesitter.LanguageTree
 	---@param source number|string
 	---@param bufnr number
-	---@param pos { [1]: number, [2]: number }
+	---@param pos LuaSnip.RawPos00
 	return function(
 		snippet,
 		line_to_cursor,
@@ -227,7 +227,7 @@ local function generate_simple_parent_lookup_function(lookup_fun)
 	return function(types)
 		local type_checker = tbl.list_to_set(types)
 		---@param parser LuaSnip.extra.TSParser
-		---@param pos { [1]: number, [2]: number }
+		---@param pos LuaSnip.RawPos00
 		return function(parser, pos)
 			-- check node just before the position.
 			local root = parser:get_node_at_pos({ pos[1], pos[2] - 1 })
@@ -260,7 +260,7 @@ end
 ---@param n number
 local function find_nth_parent(n)
 	---@param parser LuaSnip.extra.TSParser
-	---@param pos { [1]: number, [2]: number }
+	---@param pos LuaSnip.RawPos00
 	return function(parser, pos)
 		local inner_node = parser:get_node_at_pos({ pos[1], pos[2] - 1 })
 

lua/luasnip/init.lua

@@ -542,7 +542,7 @@ end
 --This can also use `jump_into_func`.
 ---@class LuaSnip.Opts.SnipExpand: LuaSnip.Opts.Expand
 ---
----@field clear_region? LuaSnip.BufferRegion A region of text to clear after
+---@field clear_region? LuaSnip.RawRegion00 A region of text to clear after
 ---  populating env-variables, but before jumping into `snip`. If `nil`, no
 ---  clearing is performed.
 ---  Being able to remove text at this point is useful as clearing before calling
@@ -566,7 +566,7 @@ end
 ---  })
 ---  ```
 ---
----@field pos? [integer, integer] Position at which the snippet should be
+---@field pos? LuaSnip.RawPos00 Position at which the snippet should be
 ---  inserted. Pass as `(row,col)`, both 0-based, the `col` given in bytes.
 ---
 ---@field indent? boolean Whether to prepend the current lines' indent to all
@@ -1301,7 +1301,7 @@ end
 ---  (Defaults to false)
 ---@field select? boolean Whether to select the entire node, or leave the
 ---  cursor at the position it is currently at. (Defaults to true)
----@field pos? LuaSnip.BytecolBufferPosition Where to look for the node.
+---@field pos? LuaSnip.RawPos00 Where to look for the node.
 ---  (Defaults to the position of the cursor)
 
 --- Lookup a node by position and activate (ie. jump into) it.

lua/luasnip/nodes/choiceNode.lua

@@ -145,6 +145,7 @@ function ChoiceNode:make_args_absolute()
 	self.absolute_insert_position[last_indx] = last
 end
 
+---@param pos LuaSnip.RawPos00
 function ChoiceNode:put_initial(pos)
 	local old_pos = vim.deepcopy(pos)
 

lua/luasnip/nodes/dynamicNode.lua

@@ -80,6 +80,7 @@ function DynamicNode:get_docstring()
 end
 
 -- DynamicNode's don't have static text, only set as visible.
+---@param pos LuaSnip.RawPos00
 function DynamicNode:put_initial(pos)
 	-- if we generated a snippet before, insert it into the buffer now. This
 	-- can happen if this dynamicNode was removed (eg. because of a

lua/luasnip/nodes/insertNode.lua

@@ -442,6 +442,7 @@ function InsertNode:argnode_text()
 	return self.static_text
 end
 
+---@param pos LuaSnip.RawPos00
 function InsertNode:put_initial(pos)
 	self.static_text:put(pos)
 	self.visible = true

lua/luasnip/nodes/node.lua

@@ -73,6 +73,7 @@ function Node:get_docstring()
 	return self.static_text
 end
 
+---@param pos LuaSnip.RawPos00
 function Node:put_initial(pos)
 	-- access static text directly, get_static_text() won't work due to
 	-- static_visible not being set.

lua/luasnip/nodes/restoreNode.lua

@@ -86,6 +86,7 @@ function RestoreNode:expand_tabs(_) end
 
 -- will be called when before expansion but after snip.parent was initialized.
 -- Get the actual snippetNode here.
+---@param pos LuaSnip.RawPos00
 function RestoreNode:put_initial(pos)
 	local tmp = self.parent.snippet.stored[self.key]
 

lua/luasnip/nodes/snippet.lua

@@ -909,6 +909,7 @@ function Snippet:dump()
 	end
 end
 
+---@param pos LuaSnip.RawPos00
 function Snippet:put_initial(pos)
 	for _, node in ipairs(self.nodes) do
 		-- save pos to compare to later.
@@ -1603,6 +1604,7 @@ function Snippet:subtree_leave_entered()
 	end
 end
 
+---@param pos LuaSnip.RawPos00
 function Snippet:put(pos)
 	--- Put text-content of snippet into buffer and set marks.
 	local old_pos = vim.deepcopy(pos)

lua/luasnip/nodes/util.lua

@@ -868,12 +868,11 @@ end
 ---of more than one restore data, and the correct ones can be identified via
 ---store_id.
 ---@field node LuaSnip.Node The node the cursor will be stored relative to.
----@field cursor_start_relative LuaSnip.BytecolBufferPosition The position of
----the cursor, or beginning of selected area, relative to the beginning of
----`node`.
----@field selection_end_start_relative LuaSnip.BytecolBufferPosition The
----position of the cursor, or end of selected area, relative to the beginning of
----`node`. The column is one beyond the byte where the selection ends.
+---@field cursor_start_relative LuaSnip.RawPos00 The position of the cursor,
+---or beginning of selected area, relative to the beginning of `node`.
+---@field selection_end_start_relative LuaSnip.RawPos00 The position of the
+---cursor, or end of selected area, relative to the beginning of `node`. The
+---column is one beyond the byte where the selection ends.
 ---@field mode string The first character (see `vim.fn.mode()`) of the mode at
 ---the time of `store`.
 
@@ -1016,6 +1015,8 @@ local function store_cursor_node_relative(node, opts)
 	return data
 end
 
+---@param node LuaSnip.Node
+---@param data LuaSnip.SnippetCursorRestoreData
 local function restore_cursor_pos_relative(node, data)
 	local cursor_pos = data.cursor_start_relative
 	local cursor_pos_v = data.selection_end_start_relative

lua/luasnip/util/feedkeys.lua

@@ -75,7 +75,8 @@ function M.feedkeys_insert(keys)
 	end, next_id())
 end
 
--- pos: (0,0)-indexed.
+---@param pos LuaSnip.RawPos00
+---@param before? boolean
 local function cursor_set_keys(pos, before)
 	if before then
 		if pos[2] == 0 then
@@ -119,6 +120,9 @@ local function cursor_set_keys(pos, before)
 		.. "<cr><cmd>:silent! foldopen!<cr>"
 end
 
+--- Visual select between the given begin/end positions
+---@param b LuaSnip.RawPos00 Starting position
+---@param e LuaSnip.RawPos00 Ending position (inclusive)
 function M.select_range(b, e)
 	local id = next_id()
 	enqueued_cursor_state =
@@ -152,7 +156,8 @@ function M.select_range(b, e)
 	end, id)
 end
 
--- move the cursor to a position and enter insert-mode (or stay in it).
+--- Move the cursor to a position and enter insert-mode (or stay in it).
+---@param pos LuaSnip.RawPos00
 function M.insert_at(pos)
 	local id = next_id()
 	enqueued_cursor_state = { pos = pos, mode = "i", id = id }
@@ -205,12 +210,12 @@ function M.confirm(id)
 end
 
 ---@class LuaSnip.Feedkeys.LastState
----@field pos LuaSnip.BytecolBufferPosition Position of the cursor or beginning of visual
----area.
----@field pos_v LuaSnip.BytecolBufferPosition Position of the cursor or end of visual
----area.
----@field mode string Represents the current mode. Only the first character of
----`vim.fn.mode()`, so not completely exact.
+---@field pos LuaSnip.RawPos00 Position of the cursor or beginning of visual
+---  area.
+---@field pos_v LuaSnip.RawPos00 Position of the cursor or end of visual
+---  area.
+---@field mode string Represents the current mode.
+---  Only the first character of `vim.fn.mode()`, so not completely exact.
 
 ---if there are some operations that move the cursor enqueued, retrieve their
 ---target-state, otherwise return the current cursor state.