feat(terminal)!: include cursor position in TermRequest event data (#31609)

When a plugin registers a TermRequest handler there is currently no way
for the handler to know where the terminal's cursor position was when
the sequence was received. This is often useful information, e.g. for
OSC 133 sequences which are used to annotate shell prompts.

Modify the event data for the TermRequest autocommand to be a table
instead of just a string. The "sequence" field of the table contains the
sequence string and the "cursor" field contains the cursor
position when the sequence was received.

To maintain consistency between TermRequest and TermResponse (and to
future proof the latter), TermResponse's event data is also updated to
be a table with a "sequence" field.

BREAKING CHANGE: event data for TermRequest and TermResponse is now a
table

3 files changed, 51 insertions, 15 deletions

diff --git a/test/functional/editor/defaults_spec.lua b/test/functional/editor/defaults_spec.lua
index 876810ce6f..9843238e35 100644
--- a/test/functional/editor/defaults_spec.lua
+++ b/test/functional/editor/defaults_spec.lua
@@ -10,7 +10,7 @@ local Screen = require('test.functional.ui.screen')
 
 describe('default', function()
   describe('autocommands', function()
-    it('nvim_terminal.TermClose closes terminal with default shell on success', function()
+    it('nvim.terminal.TermClose closes terminal with default shell on success', function()
       n.clear()
       n.api.nvim_set_option_value('shell', n.testprg('shell-test'), {})
       n.command('set shellcmdflag=EXIT shellredir= shellpipe= shellquote= shellxquote=')
diff --git a/test/functional/terminal/buffer_spec.lua b/test/functional/terminal/buffer_spec.lua
index f2d679bd5d..b134aa0225 100644
--- a/test/functional/terminal/buffer_spec.lua
+++ b/test/functional/terminal/buffer_spec.lua
@@ -373,7 +373,7 @@ describe(':terminal buffer', function()
       })
       vim.api.nvim_create_autocmd('TermRequest', {
         callback = function(args)
-          if args.data == '\027]11;?' then
+          if args.data.sequence == '\027]11;?' then
             table.insert(_G.input, '\027]11;rgb:0000/0000/0000\027\\')
           end
         end
@@ -389,6 +389,42 @@ describe(':terminal buffer', function()
     }, exec_lua('return _G.input'))
   end)
 
+  it('TermRequest includes cursor position #31609', function()
+    command('autocmd! nvim.terminal TermRequest')
+    local screen = Screen.new(50, 10)
+    local term = exec_lua([[
+      _G.cursor = {}
+      local term = vim.api.nvim_open_term(0, {})
+      vim.api.nvim_create_autocmd('TermRequest', {
+        callback = function(args)
+          _G.cursor = args.data.cursor
+        end
+      })
+      return term
+    ]])
+    -- Enter terminal mode so that the cursor follows the output
+    feed('a')
+
+    -- Put some lines into the scrollback. This tests the conversion from terminal line to buffer
+    -- line.
+    api.nvim_chan_send(term, string.rep('>\n', 20))
+    screen:expect([[
+      >                                                 |*8
+      ^                                                  |
+      {5:-- TERMINAL --}                                    |
+    ]])
+
+    -- Emit an OSC escape sequence
+    api.nvim_chan_send(term, 'Hello\nworld!\027]133;D\027\\')
+    screen:expect([[
+      >                                                 |*7
+      Hello                                             |
+      world!^                                            |
+      {5:-- TERMINAL --}                                    |
+    ]])
+    eq({ 22, 6 }, exec_lua('return _G.cursor'))
+  end)
+
   it('no heap-buffer-overflow when using jobstart("echo",{term=true}) #3161', function()
     local testfilename = 'Xtestfile-functional-terminal-buffers_spec'
     write_file(testfilename, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaa')
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index e2adcb66df..a2d5b39f84 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/test/functional/terminal/tui_spec.lua
@@ -215,7 +215,7 @@ describe('TUI', function()
       _G.termresponse = nil
       vim.api.nvim_create_autocmd('TermResponse', {
         once = true,
-        callback = function(ev) _G.termresponse = ev.data end,
+        callback = function(ev) _G.termresponse = ev.data.sequence end,
       })
     ]])
     feed_data('\027P0$r\027\\')
@@ -2199,7 +2199,7 @@ describe('TUI', function()
       vim.api.nvim_create_autocmd('TermRequest', {
         buffer = buf,
         callback = function(args)
-          local req = args.data
+          local req = args.data.sequence
           if not req then
             return
           end
@@ -3171,12 +3171,12 @@ describe('TUI', function()
     exec_lua([[
       vim.api.nvim_create_autocmd('TermRequest', {
         callback = function(args)
-          local req = args.data
-          local payload = req:match('^\027P%+q([%x;]+)$')
-          if payload then
+          local req = args.data.sequence
+          local sequence = req:match('^\027P%+q([%x;]+)$')
+          if sequence then
             local t = {}
-            for cap in vim.gsplit(payload, ';') do
-              local resp = string.format('\027P1+r%s\027\\', payload)
+            for cap in vim.gsplit(sequence, ';') do
+              local resp = string.format('\027P1+r%s\027\\', sequence)
               vim.api.nvim_chan_send(vim.bo[args.buf].channel, resp)
               t[vim.text.hexdecode(cap)] = true
             end
@@ -3222,7 +3222,7 @@ describe('TUI', function()
     exec_lua([[
       vim.api.nvim_create_autocmd('TermRequest', {
         callback = function(args)
-          local req = args.data
+          local req = args.data.sequence
           vim.g.termrequest = req
           local xtgettcap = req:match('^\027P%+q([%x;]+)$')
           if xtgettcap then
@@ -3274,10 +3274,10 @@ describe('TUI', function()
     exec_lua([[
       vim.api.nvim_create_autocmd('TermRequest', {
         callback = function(args)
-          local req = args.data
-          local payload = req:match('^\027P%+q([%x;]+)$')
-          if payload and vim.text.hexdecode(payload) == 'Ms' then
-            local resp = string.format('\027P1+r%s=%s\027\\', payload, vim.text.hexencode('\027]52;;\027\\'))
+          local req = args.data.sequence
+          local sequence = req:match('^\027P%+q([%x;]+)$')
+          if sequence and vim.text.hexdecode(sequence) == 'Ms' then
+            local resp = string.format('\027P1+r%s=%s\027\\', sequence, vim.text.hexencode('\027]52;;\027\\'))
             vim.api.nvim_chan_send(vim.bo[args.buf].channel, resp)
             return true
           end
@@ -3353,7 +3353,7 @@ describe('TUI bg color', function()
     exec_lua([[
       vim.api.nvim_create_autocmd('TermRequest', {
         callback = function(args)
-          local req = args.data
+          local req = args.data.sequence
           if req == '\027]11;?' then
             vim.g.oscrequest = true
             return true