Shell integration: Allow sending click events to shells using y co-ordinates relative to prompts

Note that I havent actually tested the implementation, I leave that to
@okapia.

Fixes #9500

docs/changelog.rst

@@ -222,6 +222,9 @@ Detailed list of changes
 - :ac:`goto_session`: Add a ``--active-only`` option to select from only active
   sessions (:pull:`9503`)
 
+- Shell integration: Allow sending click events to shells using y co-ordinates
+  relative to prompts (:iss:`9500`)
+
 
 0.45.0 [2025-12-24]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/shell-integration.rst

@@ -468,13 +468,21 @@ to control its behavior, separated by semi-colons. They are:
     this tells kitty that the secondary (PS2) prompt is starting at the
     current line.
 
-``click_events=1``
+``click_events=1|2``
     this tells kitty that the shell is capable of handling
     mouse click events. kitty will thus send a click event to the shell when
     the user clicks somewhere in the prompt. The shell can then move the cursor
     to that position or perform some other appropriate action. Without this,
     kitty will instead generate a number of fake key events to move the cursor
-    to the clicked location, which is not fully robust.
+    to the clicked location, which is not fully robust. A value of ``1`` will
+    cause the click events to have absolute y co-ordinates, a value of ``2``
+    will cause them to have y-coordinates relative to the top line of the
+    current prompt. In relative mode, y is zero for cells on the top line of
+    the current prompt. The current prompt here is either the secondary (PS2) or
+    primary prompt. If the secondary prompt is on the same line or above the
+    mouse position, then the reported y will be with respect to that, otherwise
+    with respect to the primary prompt. The click event is encoded in the SGR
+    encoding from xterm.
 
 kitty also optionally supports sending the cmdline going to be executed with ``<OSC>133;C`` as: