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, 24 insertions, 9 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 413802eea1..0e582ce0e7 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -1004,22 +1004,32 @@ TermClose			When a |terminal| job ends.
 				    status
 							*TermRequest*
 TermRequest			When a |:terminal| child process emits an OSC,
-				DCS or APC sequence. Sets |v:termrequest|. The
-				|event-data| is the request string.
+				DCS, or APC sequence. Sets |v:termrequest|. The
+				|event-data| is a table with the following
+				fields:
+
+				- sequence: the received sequence
+				- cursor: (1,0)-indexed, buffer-relative
+				  position of the cursor when the sequence was
+				  received
+
 							*TermResponse*
 TermResponse			When Nvim receives an OSC or DCS response from
 				the host terminal. Sets |v:termresponse|. The
-				|event-data| is the response string. May be
-				triggered during another event (file I/O,
-				a shell command, or anything else that takes
-				time). Example: >lua
+				|event-data| is a table with the following fields:
+
+				- sequence: the received sequence
+
+				May be triggered during another event (file
+				I/O, a shell command, or anything else that
+				takes time). Example: >lua
 
 				-- Query the terminal palette for the RGB value of color 1
 				-- (red) using OSC 4
 				vim.api.nvim_create_autocmd('TermResponse', {
 				  once = true,
 				  callback = function(args)
-				    local resp = args.data
+				    local resp = args.data.sequence
 				    local r, g, b = resp:match("\027%]4;1;rgb:(%w+)/(%w+)/(%w+)")
 				  end,
 				})
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 415a234254..4667af906f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -111,6 +111,9 @@ EVENTS
     • `history` argument indicating if the message was added to the history.
     • new message kinds: "bufwrite", "completion", "list_cmd", "lua_print",
       "search_cmd", "shell_out/err/ret", "undo", "verbose", wildlist".
+• |TermRequest| and |TermResponse| |event-data| is now a table. The "sequence"
+  field contains the received sequence. |TermRequest| also contains a "cursor"
+  field indicating the cursor's position when the sequence was received.
 
 HIGHLIGHTS
 
@@ -396,6 +399,8 @@ TERMINAL
   codes" mode is currently supported.
 • The |terminal| emits a |TermRequest| autocommand event when the child process
   emits an APC control sequence.
+• |TermRequest| has a "cursor" field in its |event-data| indicating the
+  cursor position when the sequence was received.
 
 TREESITTER
 
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 0ab7151728..4183bb8dcf 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -144,8 +144,8 @@ directory indicated in the request. >lua
   vim.api.nvim_create_autocmd({ 'TermRequest' }, {
     desc = 'Handles OSC 7 dir change requests',
     callback = function(ev)
-      if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then
-        local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '')
+      if string.sub(ev.data.sequence, 1, 4) == '\x1b]7;' then
+        local dir = string.gsub(ev.data.sequence, '\x1b]7;file://[^/]*', '')
         if vim.fn.isdirectory(dir) == 0 then
           vim.notify('invalid dir: '..dir)
           return