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, 7 insertions, 1 deletions

diff --git a/include/term/term_input.h b/include/term/term_input.h
index 4b0a8d9..c317bea 100644
--- a/include/term/term_input.h
+++ b/include/term/term_input.h
@@ -118,11 +118,11 @@ enum term_mouse_button {
     TERM_MOUSE_BUTTON_MIDDLE,
     TERM_MOUSE_BUTTON_SECONDARY,
     TERM_MOUSE_BUTTON_NONE,
+    /* Extra buttons 8 through 11 in xterm mouse reporting (encoded as 128..131). */
     TERM_MOUSE_BUTTON_EXTRA_1,
     TERM_MOUSE_BUTTON_EXTRA_2,
     TERM_MOUSE_BUTTON_EXTRA_3,
     TERM_MOUSE_BUTTON_EXTRA_4,
-    TERM_MOUSE_BUTTON_EXTRA_5,
     TERM_MOUSE_WHEEL_UP = 16,
     TERM_MOUSE_WHEEL_DOWN,
     TERM_MOUSE_WHEEL_LEFT,
@@ -152,6 +152,12 @@ struct term_key_event {
 struct term_mouse_event {
     struct term_vector2i pos;   /* Grid cell coordinates (col, row) */
     struct term_vector2i pixel; /* Absolute pixel position in terminal grid */
+    /*
+     * Button identifier:
+     * - Press and release: the button that changed state (TERM_MOUSE_BUTTON_*).
+     * - Motion: the held button for drag events, or TERM_MOUSE_BUTTON_NONE for hover.
+     * - Scroll: the wheel direction (TERM_MOUSE_WHEEL_*).
+     */
     int button;
     unsigned mods;
     int scroll_lines;