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

2 files changed, 18 insertions, 2 deletions

diff --git a/include/term/term.h b/include/term/term.h
index 4853ebf..9c6281b 100644
--- a/include/term/term.h
+++ b/include/term/term.h
@@ -120,7 +120,17 @@ struct term_callbacks {
     /* Bytes the terminal sends back to the program (replies to queries). */
     void (*reply)(void *ud, const char *bytes, size_t len);
     void (*title)(void *ud, const char *title);
-    /* OSC 52. selection names the target, such as "c". */
+    /*
+     * OSC 52 clipboard callback.
+     * selection names the target clipboard buffer(s), commonly:
+     *   "c" - clipboard (system clipboard)
+     *   "p" - primary selection (X11 primary)
+     *   "q" - secondary selection
+     *   "s" - select selection
+     *   "0".."7" - cut buffers 0 to 7
+     * A parameter may contain multiple targets (e.g. "cp").
+     * data contains decoded bytes of length len.
+     */
     void (*clipboard)(void *ud, const char *selection, const char *data, size_t len);
     void (*notify)(void *ud, const char *title, const char *body);
     void (*bell)(void *ud);
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;