From 5226e26e998f792641590b24b19cdd875b5edd84 Mon Sep 17 00:00:00 2001
From: Olivia Kinnear <git@superatomic.dev>
Date: Tue, 28 Jul 2026 06:21:45 -0500
Subject: [PATCH] feat(pos): vim.pos.cursor() without args returns curwin pos
 #40975

---
 runtime/doc/lua.txt              | 5 +++--
 runtime/doc/news.txt             | 2 ++
 runtime/lua/vim/pos.lua          | 9 +++++----
 test/functional/lua/pos_spec.lua | 5 +++--
 4 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 7d6ed03a89..851d25cb8a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -4582,7 +4582,8 @@ cursor({buf}, {pos})                                        *vim.pos.cursor()*
     Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 
     If {pos} is omitted, the first argument is treated as {win} instead of
-    {buf}, and the current cursor position of {win} is used.
+    {buf}, and the current cursor position of {win} is used. If {win} is also
+    omitted, it defaults to the current window.
 
     Example: >lua
         local buf = vim.api.nvim_win_get_buf(0)
@@ -4597,7 +4598,7 @@ cursor({buf}, {pos})                                        *vim.pos.cursor()*
       • {pos}  (`[integer, integer]`) (lnum, col) tuple
 
     Overloads: ~
-      • `fun(win: integer): vim.Pos`
+      • `fun(win?: integer): vim.Pos`
 
     Return: ~
         (`vim.Pos`) See |vim.Pos|.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 3b3914acf1..99e70b2f3c 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -332,6 +332,8 @@ LUA
   but returns `nil` on error.
 • |vim.pos| can now convert between positions and buffer offsets.
 • |vim.pos| and |vim.range| can now convert between mark positions.
+• |vim.pos.cursor()| without arguments returns the cursor position of the
+  current window.
 • |vim.ui.input()| now allows setting input scope.
 • |vim.log| provides a logging interface.
 • |vim.pack.get()| output includes revision of a pending update.
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
index df55e5e431..80ce0b6f9e 100644
--- a/runtime/lua/vim/pos.lua
+++ b/runtime/lua/vim/pos.lua
@@ -166,7 +166,8 @@ end
 --- Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 ---
 --- If {pos} is omitted, the first argument is treated as {win} instead of {buf},
---- and the current cursor position of {win} is used.
+--- and the current cursor position of {win} is used. If {win} is also omitted,
+--- it defaults to the current window.
 ---
 --- Example:
 --- ```lua
@@ -179,7 +180,7 @@ end
 ---@param buf integer
 ---@param pos [integer, integer] (lnum, col) tuple
 ---@return vim.Pos
----@overload fun(win: integer): vim.Pos
+---@overload fun(win?: integer): vim.Pos
 function M.cursor(buf, pos)
   validate('pos', pos, 'table', true)
 
@@ -190,8 +191,8 @@ function M.cursor(buf, pos)
     end
   else
     local win = buf
-    validate('win', win, 'number')
-    if win == 0 then
+    validate('win', win, 'number', true)
+    if win == 0 or win == nil then
       win = api.nvim_get_current_win()
     end
 
diff --git a/test/functional/lua/pos_spec.lua b/test/functional/lua/pos_spec.lua
index 03a9de0c21..a252702023 100644
--- a/test/functional/lua/pos_spec.lua
+++ b/test/functional/lua/pos_spec.lua
@@ -32,12 +32,13 @@ describe('vim.pos', function()
   end)
 
   it('creates a position from the window cursor', function()
-    local pos, buf = exec_lua(function()
+    local pos, pos_default, buf = exec_lua(function()
       vim.api.nvim_buf_set_lines(0, 0, -1, true, { 'first', 'second' })
       vim.api.nvim_win_set_cursor(0, { 2, 3 })
-      return vim.pos.cursor(0), vim.api.nvim_get_current_buf()
+      return vim.pos.cursor(0), vim.pos.cursor(), vim.api.nvim_get_current_buf()
     end)
     eq({ 1, 3, buf }, pos)
+    eq({ 1, 3, buf }, pos_default)
   end)
 
   it('comparisons by overloaded operators', function()