Fix extra mouse button encoding collision with Alt bit and document API gaps

- Encode buttons 8 through 11 (EXTRA_1..4) with offset 128 (128..131)
  per xterm mouse tracking, resolving collisions with the Alt modifier bit (8)
- Drop EXTRA_5 from enum term_mouse_button since xterm mouse tracking defines
  four extra buttons (8 to 11) and codes beyond 131 collide with modifier bits
- Replace literal 3 with TERM_MOUSE_BUTTON_NONE for hover motion check in mode 1002
- Document button field semantics in struct term_mouse_event for press, release,
  motion, and scroll events
- Document OSC 52 target buffer selections ("c", "p", "q", "s", "0".."7") in term.h
- Add unit tests for extra button encoding, SGR release, hover motion suppression
  in mode 1002, and non-collision with Alt modifiers

1 files changed, 16 insertions, 5 deletions

diff --git a/tests/input_test.c b/tests/input_test.c
index 1a44f42..78dad07 100644
--- a/tests/input_test.c
+++ b/tests/input_test.c
@@ -234,14 +234,15 @@ int main(void)
     m.mouse_encoding = TERM_MOUSE_ENC_X10;
 
     m.mouse = TERM_MOUSE_BUTTON;
-    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = 3); expect("");
-    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = 0);
+    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = TERM_MOUSE_BUTTON_NONE); expect("");
+    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = TERM_MOUSE_BUTTON_PRIMARY);
     expect("\033[M\100\043\042");
     m.mouse_encoding = TERM_MOUSE_ENC_SGR;
-    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = 0, .mods = TERM_MOD_CTRL);
+    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = TERM_MOUSE_BUTTON_NONE); expect("");
+    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = TERM_MOUSE_BUTTON_PRIMARY, .mods = TERM_MOD_CTRL);
     expect("\033[<48;3;2M");
     m.mouse = TERM_MOUSE_ANY;
-    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = 3); expect("\033[<35;3;2M");
+    MOUSE(2, 1, .kind = TERM_MOUSE_MOTION, .button = TERM_MOUSE_BUTTON_NONE); expect("\033[<35;3;2M");
     m.mouse_encoding = TERM_MOUSE_ENC_X10;
     MOUSE(2, 1, .button = TERM_MOUSE_WHEEL_UP); expect("\033[M\140\043\042");
 
@@ -336,10 +337,20 @@ int main(void)
     }
     m.mouse = TERM_MOUSE_ANY;
     m.mouse_encoding = TERM_MOUSE_ENC_SGR;
-    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_1); expect("\033[<8;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_1); expect("\033[<128;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_2); expect("\033[<129;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_3); expect("\033[<130;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_4); expect("\033[<131;3;2M");
     MOUSE(2, 1, .button = TERM_MOUSE_WHEEL_LEFT); expect("\033[<66;3;2M");
     MOUSE(2, 1, .button = TERM_MOUSE_WHEEL_RIGHT); expect("\033[<67;3;2M");
 
+    /* Ensure Alt modifier does not collide with extra buttons */
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_PRIMARY, .mods = TERM_MOD_ALT); expect("\033[<8;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_1, .mods = TERM_MOD_ALT); expect("\033[<136;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_MIDDLE, .mods = TERM_MOD_ALT); expect("\033[<9;3;2M");
+    MOUSE(2, 1, .button = TERM_MOUSE_BUTTON_EXTRA_2, .mods = TERM_MOD_ALT); expect("\033[<137;3;2M");
+    MOUSE(2, 1, .kind = TERM_MOUSE_RELEASE, .button = TERM_MOUSE_BUTTON_EXTRA_1); expect("\033[<128;3;2m");
+
     {
         /* A host sizes the paste buffer from the text alone. */
         static const char text[] = "ls\r\n\033[31m\u202erm\x7f\t\xe4\xb8\xad";