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, 11 insertions, 1 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);