better public interface and doxygen

6 files changed, 538 insertions, 17 deletions

diff --git a/src/common/backend.c b/src/common/backend.c
index ccb9c27..23275d6 100644
--- a/src/common/backend.c
+++ b/src/common/backend.c
@@ -81,10 +81,18 @@ uint32_t yasl_display_caps(const struct yasl_display *d)
 
 int yasl_display_dispatch(struct yasl_display *d, int timeout_ms)
 {
-    if (!d) return -1;
-    if (d->ops->display_dispatch_timeout)
-        return d->ops->display_dispatch_timeout(d, timeout_ms);
-    return -1;
+    if (!d) {
+        errno = EINVAL;
+        return -1;
+    }
+    if (!d->ops->display_dispatch_timeout) {
+        errno = ENOTSUP;
+        return -1;
+    }
+    errno = 0;
+    int result = d->ops->display_dispatch_timeout(d, timeout_ms);
+    if (result < 0 && !errno) errno = EIO;
+    return result;
 }
 
 void yasl_display_flush(struct yasl_display *d)
@@ -127,7 +135,12 @@ bool yasl_display_drag_start(struct yasl_display *d, struct yasl_surface *origin
         return 0;
     if (!origin || origin->display != d)
         return false;
-    return d->ops->display_drag_start(d, origin, image, l, ud);
+    if (image && (!image->pixels || image->size.x <= 0 || image->size.y <= 0 ||
+        image->size.x > 32767 || image->size.y > 32767 ||
+        (int64_t)image->size.x * image->size.y * 4 > INT32_MAX))
+        return false;
+    const struct yasl_drag_listener empty = {0};
+    return d->ops->display_drag_start(d, origin, image, l ? l : &empty, ud);
 }
 
 void yasl_display_drag_cancel(struct yasl_display *d)
@@ -151,7 +164,10 @@ struct yasl_surface *yasl_create_toplevel(struct yasl_display *d,
         errno = ENOTSUP;
         return NULL;
     }
-    return d->ops->surface_create_toplevel(d, spec, graphics_device);
+    errno = 0;
+    struct yasl_surface *s = d->ops->surface_create_toplevel(d, spec, graphics_device);
+    if (!s && !errno) errno = ENODEV;
+    return s;
 }
 
 struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d,
@@ -160,18 +176,50 @@ struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d,
     return yasl_create_toplevel(d, spec, NULL);
 }
 
+static bool popup_spec_valid(const struct yasl_popup_spec *spec)
+{
+    return spec && spec->size.x > 0 && spec->size.y > 0 &&
+        spec->size.x <= 32767 && spec->size.y <= 32767 &&
+        (int64_t)spec->size.x * spec->size.y * 4 <= INT32_MAX &&
+        spec->anchor.width >= 0 && spec->anchor.height >= 0 &&
+        spec->content_offset.x >= 0 && spec->content_offset.y >= 0 &&
+        spec->content_size.x >= 0 && spec->content_size.y >= 0 &&
+        (int64_t)spec->content_offset.x + spec->content_size.x <= spec->size.x &&
+        (int64_t)spec->content_offset.y + spec->content_size.y <= spec->size.y;
+}
+
 struct yasl_surface *yasl_surface_create_popup(struct yasl_surface *parent, const struct yasl_popup_spec *spec)
 {
-    if (!parent || !parent->display->ops->surface_create_popup)
-        return 0;
-    return parent->display->ops->surface_create_popup(parent, spec);
+    if (!parent || !popup_spec_valid(spec)) {
+        errno = EINVAL;
+        return NULL;
+    }
+    if (!(yasl_display_caps(parent->display) & YASL_CAP_POPUPS) ||
+        !parent->display->ops->surface_create_popup) {
+        errno = ENOTSUP;
+        return NULL;
+    }
+    errno = 0;
+    struct yasl_surface *s = parent->display->ops->surface_create_popup(parent, spec);
+    if (!s && !errno) errno = ENODEV;
+    return s;
 }
 
 bool yasl_surface_popup_reposition(struct yasl_surface *popup, const struct yasl_popup_spec *spec)
 {
-    if (!popup || !popup->display->ops->surface_popup_reposition)
-        return 0;
-    return popup->display->ops->surface_popup_reposition(popup, spec);
+    if (!popup || !popup_spec_valid(spec)) {
+        errno = EINVAL;
+        return false;
+    }
+    if (!(yasl_display_caps(popup->display) & YASL_CAP_POPUPS) ||
+        !popup->display->ops->surface_popup_reposition) {
+        errno = ENOTSUP;
+        return false;
+    }
+    errno = 0;
+    bool result = popup->display->ops->surface_popup_reposition(popup, spec);
+    if (!result && !errno) errno = ENODEV;
+    return result;
 }
 
 void yasl_surface_destroy(struct yasl_surface *s)
diff --git a/src/common/keyboard.c b/src/common/keyboard.c
new file mode 100644
index 0000000..80c6702
--- /dev/null
+++ b/src/common/keyboard.c
@@ -0,0 +1,399 @@
+#include "keyboard.h"
+#include "cocoa/keycodes.h"
+#include <string.h>
+
+/* Numeric Linux evdev codes; no platform headers are needed by this table. */
+enum yasl_key yasl_key_from_evdev(uint32_t code)
+{
+    switch (code) {
+    case 1: return YASL_KEY_ESCAPE; /* KEY_ESC */
+    case 2: return YASL_KEY_1; /* KEY_1 */
+    case 3: return YASL_KEY_2; /* KEY_2 */
+    case 4: return YASL_KEY_3; /* KEY_3 */
+    case 5: return YASL_KEY_4; /* KEY_4 */
+    case 6: return YASL_KEY_5; /* KEY_5 */
+    case 7: return YASL_KEY_6; /* KEY_6 */
+    case 8: return YASL_KEY_7; /* KEY_7 */
+    case 9: return YASL_KEY_8; /* KEY_8 */
+    case 10: return YASL_KEY_9; /* KEY_9 */
+    case 11: return YASL_KEY_0; /* KEY_0 */
+    case 12: return YASL_KEY_MINUS; /* KEY_MINUS */
+    case 13: return YASL_KEY_EQUAL; /* KEY_EQUAL */
+    case 14: return YASL_KEY_BACKSPACE; /* KEY_BACKSPACE */
+    case 15: return YASL_KEY_TAB; /* KEY_TAB */
+    case 16: return YASL_KEY_Q; /* KEY_Q */
+    case 17: return YASL_KEY_W; /* KEY_W */
+    case 18: return YASL_KEY_E; /* KEY_E */
+    case 19: return YASL_KEY_R; /* KEY_R */
+    case 20: return YASL_KEY_T; /* KEY_T */
+    case 21: return YASL_KEY_Y; /* KEY_Y */
+    case 22: return YASL_KEY_U; /* KEY_U */
+    case 23: return YASL_KEY_I; /* KEY_I */
+    case 24: return YASL_KEY_O; /* KEY_O */
+    case 25: return YASL_KEY_P; /* KEY_P */
+    case 26: return YASL_KEY_LEFT_BRACKET; /* KEY_LEFTBRACE */
+    case 27: return YASL_KEY_RIGHT_BRACKET; /* KEY_RIGHTBRACE */
+    case 28: return YASL_KEY_ENTER; /* KEY_ENTER */
+    case 29: return YASL_KEY_LEFT_CONTROL; /* KEY_LEFTCTRL */
+    case 30: return YASL_KEY_A; /* KEY_A */
+    case 31: return YASL_KEY_S; /* KEY_S */
+    case 32: return YASL_KEY_D; /* KEY_D */
+    case 33: return YASL_KEY_F; /* KEY_F */
+    case 34: return YASL_KEY_G; /* KEY_G */
+    case 35: return YASL_KEY_H; /* KEY_H */
+    case 36: return YASL_KEY_J; /* KEY_J */
+    case 37: return YASL_KEY_K; /* KEY_K */
+    case 38: return YASL_KEY_L; /* KEY_L */
+    case 39: return YASL_KEY_SEMICOLON; /* KEY_SEMICOLON */
+    case 40: return YASL_KEY_APOSTROPHE; /* KEY_APOSTROPHE */
+    case 41: return YASL_KEY_GRAVE; /* KEY_GRAVE */
+    case 42: return YASL_KEY_LEFT_SHIFT; /* KEY_LEFTSHIFT */
+    case 43: return YASL_KEY_BACKSLASH; /* KEY_BACKSLASH */
+    case 44: return YASL_KEY_Z; /* KEY_Z */
+    case 45: return YASL_KEY_X; /* KEY_X */
+    case 46: return YASL_KEY_C; /* KEY_C */
+    case 47: return YASL_KEY_V; /* KEY_V */
+    case 48: return YASL_KEY_B; /* KEY_B */
+    case 49: return YASL_KEY_N; /* KEY_N */
+    case 50: return YASL_KEY_M; /* KEY_M */
+    case 51: return YASL_KEY_COMMA; /* KEY_COMMA */
+    case 52: return YASL_KEY_PERIOD; /* KEY_DOT */
+    case 53: return YASL_KEY_SLASH; /* KEY_SLASH */
+    case 54: return YASL_KEY_RIGHT_SHIFT; /* KEY_RIGHTSHIFT */
+    case 55: return YASL_KEY_KP_MULTIPLY; /* KEY_KPASTERISK */
+    case 56: return YASL_KEY_LEFT_ALT; /* KEY_LEFTALT */
+    case 57: return YASL_KEY_SPACE; /* KEY_SPACE */
+    case 58: return YASL_KEY_CAPS_LOCK; /* KEY_CAPSLOCK */
+    case 59: return YASL_KEY_F1; /* KEY_F1 */
+    case 60: return YASL_KEY_F2; /* KEY_F2 */
+    case 61: return YASL_KEY_F3; /* KEY_F3 */
+    case 62: return YASL_KEY_F4; /* KEY_F4 */
+    case 63: return YASL_KEY_F5; /* KEY_F5 */
+    case 64: return YASL_KEY_F6; /* KEY_F6 */
+    case 65: return YASL_KEY_F7; /* KEY_F7 */
+    case 66: return YASL_KEY_F8; /* KEY_F8 */
+    case 67: return YASL_KEY_F9; /* KEY_F9 */
+    case 68: return YASL_KEY_F10; /* KEY_F10 */
+    case 69: return YASL_KEY_NUM_LOCK; /* KEY_NUMLOCK */
+    case 70: return YASL_KEY_SCROLL_LOCK; /* KEY_SCROLLLOCK */
+    case 71: return YASL_KEY_KP_7; /* KEY_KP7 */
+    case 72: return YASL_KEY_KP_8; /* KEY_KP8 */
+    case 73: return YASL_KEY_KP_9; /* KEY_KP9 */
+    case 74: return YASL_KEY_KP_SUBTRACT; /* KEY_KPMINUS */
+    case 75: return YASL_KEY_KP_4; /* KEY_KP4 */
+    case 76: return YASL_KEY_KP_5; /* KEY_KP5 */
+    case 77: return YASL_KEY_KP_6; /* KEY_KP6 */
+    case 78: return YASL_KEY_KP_ADD; /* KEY_KPPLUS */
+    case 79: return YASL_KEY_KP_1; /* KEY_KP1 */
+    case 80: return YASL_KEY_KP_2; /* KEY_KP2 */
+    case 81: return YASL_KEY_KP_3; /* KEY_KP3 */
+    case 82: return YASL_KEY_KP_0; /* KEY_KP0 */
+    case 83: return YASL_KEY_KP_DECIMAL; /* KEY_KPDOT */
+    case 86: return YASL_KEY_ISO_BACKSLASH; /* KEY_102ND */
+    case 87: return YASL_KEY_F11; /* KEY_F11 */
+    case 88: return YASL_KEY_F12; /* KEY_F12 */
+    case 89: return YASL_KEY_RO; /* KEY_RO */
+    case 92: return YASL_KEY_CONVERT; /* KEY_HENKAN */
+    case 93: return YASL_KEY_KANA; /* KEY_KATAKANAHIRAGANA */
+    case 94: return YASL_KEY_NONCONVERT; /* KEY_MUHENKAN */
+    case 96: return YASL_KEY_KP_ENTER; /* KEY_KPENTER */
+    case 97: return YASL_KEY_RIGHT_CONTROL; /* KEY_RIGHTCTRL */
+    case 98: return YASL_KEY_KP_DIVIDE; /* KEY_KPSLASH */
+    case 99: return YASL_KEY_PRINT_SCREEN; /* KEY_SYSRQ */
+    case 100: return YASL_KEY_RIGHT_ALT; /* KEY_RIGHTALT */
+    case 102: return YASL_KEY_HOME; /* KEY_HOME */
+    case 103: return YASL_KEY_UP; /* KEY_UP */
+    case 104: return YASL_KEY_PAGE_UP; /* KEY_PAGEUP */
+    case 105: return YASL_KEY_LEFT; /* KEY_LEFT */
+    case 106: return YASL_KEY_RIGHT; /* KEY_RIGHT */
+    case 107: return YASL_KEY_END; /* KEY_END */
+    case 108: return YASL_KEY_DOWN; /* KEY_DOWN */
+    case 109: return YASL_KEY_PAGE_DOWN; /* KEY_PAGEDOWN */
+    case 110: return YASL_KEY_INSERT; /* KEY_INSERT */
+    case 111: return YASL_KEY_DELETE; /* KEY_DELETE */
+    case 113: return YASL_KEY_MUTE; /* KEY_MUTE */
+    case 114: return YASL_KEY_VOLUME_DOWN; /* KEY_VOLUMEDOWN */
+    case 115: return YASL_KEY_VOLUME_UP; /* KEY_VOLUMEUP */
+    case 117: return YASL_KEY_KP_EQUAL; /* KEY_KPEQUAL */
+    case 119: return YASL_KEY_PAUSE; /* KEY_PAUSE */
+    case 121: return YASL_KEY_KP_COMMA; /* KEY_KPCOMMA */
+    case 124: return YASL_KEY_YEN; /* KEY_YEN */
+    case 125: return YASL_KEY_LEFT_SUPER; /* KEY_LEFTMETA */
+    case 126: return YASL_KEY_RIGHT_SUPER; /* KEY_RIGHTMETA */
+    case 127: return YASL_KEY_MENU; /* KEY_COMPOSE */
+    case 183: return YASL_KEY_F13; /* KEY_F13 */
+    case 184: return YASL_KEY_F14; /* KEY_F14 */
+    case 185: return YASL_KEY_F15; /* KEY_F15 */
+    case 186: return YASL_KEY_F16; /* KEY_F16 */
+    case 187: return YASL_KEY_F17; /* KEY_F17 */
+    case 188: return YASL_KEY_F18; /* KEY_F18 */
+    case 189: return YASL_KEY_F19; /* KEY_F19 */
+    case 190: return YASL_KEY_F20; /* KEY_F20 */
+    case 191: return YASL_KEY_F21; /* KEY_F21 */
+    case 192: return YASL_KEY_F22; /* KEY_F22 */
+    case 193: return YASL_KEY_F23; /* KEY_F23 */
+    case 194: return YASL_KEY_F24; /* KEY_F24 */
+    default: return YASL_KEY_UNKNOWN;
+    }
+}
+
+enum yasl_key yasl_key_from_cocoa(uint32_t code)
+{
+    switch (code) {
+    case kVK_ANSI_A: return YASL_KEY_A;
+    case kVK_ANSI_B: return YASL_KEY_B;
+    case kVK_ANSI_C: return YASL_KEY_C;
+    case kVK_ANSI_D: return YASL_KEY_D;
+    case kVK_ANSI_E: return YASL_KEY_E;
+    case kVK_ANSI_F: return YASL_KEY_F;
+    case kVK_ANSI_G: return YASL_KEY_G;
+    case kVK_ANSI_H: return YASL_KEY_H;
+    case kVK_ANSI_I: return YASL_KEY_I;
+    case kVK_ANSI_J: return YASL_KEY_J;
+    case kVK_ANSI_K: return YASL_KEY_K;
+    case kVK_ANSI_L: return YASL_KEY_L;
+    case kVK_ANSI_M: return YASL_KEY_M;
+    case kVK_ANSI_N: return YASL_KEY_N;
+    case kVK_ANSI_O: return YASL_KEY_O;
+    case kVK_ANSI_P: return YASL_KEY_P;
+    case kVK_ANSI_Q: return YASL_KEY_Q;
+    case kVK_ANSI_R: return YASL_KEY_R;
+    case kVK_ANSI_S: return YASL_KEY_S;
+    case kVK_ANSI_T: return YASL_KEY_T;
+    case kVK_ANSI_U: return YASL_KEY_U;
+    case kVK_ANSI_V: return YASL_KEY_V;
+    case kVK_ANSI_W: return YASL_KEY_W;
+    case kVK_ANSI_X: return YASL_KEY_X;
+    case kVK_ANSI_Y: return YASL_KEY_Y;
+    case kVK_ANSI_Z: return YASL_KEY_Z;
+    case kVK_ANSI_0: return YASL_KEY_0;
+    case kVK_ANSI_1: return YASL_KEY_1;
+    case kVK_ANSI_2: return YASL_KEY_2;
+    case kVK_ANSI_3: return YASL_KEY_3;
+    case kVK_ANSI_4: return YASL_KEY_4;
+    case kVK_ANSI_5: return YASL_KEY_5;
+    case kVK_ANSI_6: return YASL_KEY_6;
+    case kVK_ANSI_7: return YASL_KEY_7;
+    case kVK_ANSI_8: return YASL_KEY_8;
+    case kVK_ANSI_9: return YASL_KEY_9;
+    case kVK_Return: return YASL_KEY_ENTER;
+    case kVK_Tab: return YASL_KEY_TAB;
+    case kVK_Space: return YASL_KEY_SPACE;
+    case kVK_Escape: return YASL_KEY_ESCAPE;
+    case kVK_Home: return YASL_KEY_HOME;
+    case kVK_End: return YASL_KEY_END;
+    case kVK_Delete: return YASL_KEY_BACKSPACE;
+    case kVK_ForwardDelete: return YASL_KEY_DELETE;
+    case kVK_PageUp: return YASL_KEY_PAGE_UP;
+    case kVK_PageDown: return YASL_KEY_PAGE_DOWN;
+    case kVK_Help: return YASL_KEY_INSERT;
+    case kVK_LeftArrow: return YASL_KEY_LEFT;
+    case kVK_RightArrow: return YASL_KEY_RIGHT;
+    case kVK_DownArrow: return YASL_KEY_DOWN;
+    case kVK_UpArrow: return YASL_KEY_UP;
+    case kVK_Command: return YASL_KEY_LEFT_SUPER;
+    case kVK_Shift: return YASL_KEY_LEFT_SHIFT;
+    case kVK_CapsLock: return YASL_KEY_CAPS_LOCK;
+    case kVK_Option: return YASL_KEY_LEFT_ALT;
+    case kVK_Control: return YASL_KEY_LEFT_CONTROL;
+    case kVK_RightCommand: return YASL_KEY_RIGHT_SUPER;
+    case kVK_RightShift: return YASL_KEY_RIGHT_SHIFT;
+    case kVK_RightOption: return YASL_KEY_RIGHT_ALT;
+    case kVK_RightControl: return YASL_KEY_RIGHT_CONTROL;
+    case kVK_ContextualMenu: return YASL_KEY_MENU;
+    case kVK_VolumeUp: return YASL_KEY_VOLUME_UP;
+    case kVK_VolumeDown: return YASL_KEY_VOLUME_DOWN;
+    case kVK_Mute: return YASL_KEY_MUTE;
+    case kVK_ISO_Section: return YASL_KEY_ISO_BACKSLASH;
+    case kVK_JIS_Yen: return YASL_KEY_YEN;
+    case kVK_JIS_Underscore: return YASL_KEY_RO;
+    case kVK_JIS_Eisu: return YASL_KEY_EISU;
+    case kVK_JIS_Kana: return YASL_KEY_KANA;
+    case kVK_JIS_KeypadComma: return YASL_KEY_KP_COMMA;
+    case kVK_ANSI_Equal: return YASL_KEY_EQUAL;
+    case kVK_ANSI_Minus: return YASL_KEY_MINUS;
+    case kVK_ANSI_LeftBracket: return YASL_KEY_LEFT_BRACKET;
+    case kVK_ANSI_RightBracket: return YASL_KEY_RIGHT_BRACKET;
+    case kVK_ANSI_Quote: return YASL_KEY_APOSTROPHE;
+    case kVK_ANSI_Semicolon: return YASL_KEY_SEMICOLON;
+    case kVK_ANSI_Backslash: return YASL_KEY_BACKSLASH;
+    case kVK_ANSI_Comma: return YASL_KEY_COMMA;
+    case kVK_ANSI_Slash: return YASL_KEY_SLASH;
+    case kVK_ANSI_Period: return YASL_KEY_PERIOD;
+    case kVK_ANSI_Grave: return YASL_KEY_GRAVE;
+    case kVK_F1: return YASL_KEY_F1;
+    case kVK_F2: return YASL_KEY_F2;
+    case kVK_F3: return YASL_KEY_F3;
+    case kVK_F4: return YASL_KEY_F4;
+    case kVK_F5: return YASL_KEY_F5;
+    case kVK_F6: return YASL_KEY_F6;
+    case kVK_F7: return YASL_KEY_F7;
+    case kVK_F8: return YASL_KEY_F8;
+    case kVK_F9: return YASL_KEY_F9;
+    case kVK_F10: return YASL_KEY_F10;
+    case kVK_F11: return YASL_KEY_F11;
+    case kVK_F12: return YASL_KEY_F12;
+    case kVK_F13: return YASL_KEY_F13;
+    case kVK_F14: return YASL_KEY_F14;
+    case kVK_F15: return YASL_KEY_F15;
+    case kVK_F16: return YASL_KEY_F16;
+    case kVK_F17: return YASL_KEY_F17;
+    case kVK_F18: return YASL_KEY_F18;
+    case kVK_F19: return YASL_KEY_F19;
+    case kVK_F20: return YASL_KEY_F20;
+    case kVK_ANSI_Keypad0: return YASL_KEY_KP_0;
+    case kVK_ANSI_Keypad1: return YASL_KEY_KP_1;
+    case kVK_ANSI_Keypad2: return YASL_KEY_KP_2;
+    case kVK_ANSI_Keypad3: return YASL_KEY_KP_3;
+    case kVK_ANSI_Keypad4: return YASL_KEY_KP_4;
+    case kVK_ANSI_Keypad5: return YASL_KEY_KP_5;
+    case kVK_ANSI_Keypad6: return YASL_KEY_KP_6;
+    case kVK_ANSI_Keypad7: return YASL_KEY_KP_7;
+    case kVK_ANSI_Keypad8: return YASL_KEY_KP_8;
+    case kVK_ANSI_Keypad9: return YASL_KEY_KP_9;
+    case kVK_ANSI_KeypadDecimal: return YASL_KEY_KP_DECIMAL;
+    case kVK_ANSI_KeypadMultiply: return YASL_KEY_KP_MULTIPLY;
+    case kVK_ANSI_KeypadPlus: return YASL_KEY_KP_ADD;
+    case kVK_ANSI_KeypadClear: return YASL_KEY_KP_CLEAR;
+    case kVK_ANSI_KeypadDivide: return YASL_KEY_KP_DIVIDE;
+    case kVK_ANSI_KeypadEnter: return YASL_KEY_KP_ENTER;
+    case kVK_ANSI_KeypadMinus: return YASL_KEY_KP_SUBTRACT;
+    case kVK_ANSI_KeypadEquals: return YASL_KEY_KP_EQUAL;
+    default: return YASL_KEY_UNKNOWN;
+    }
+}
+
+/* XKB standard physical key names, independent of server numeric keycodes. */
+enum yasl_key yasl_key_from_xkb_name(const char name[4])
+{
+    static const struct { char name[4]; enum yasl_key key; } keys[] = {
+        {{'T', 'L', 'D', 'E'}, YASL_KEY_GRAVE},
+        {{'A', 'E', '0', '1'}, YASL_KEY_1},
+        {{'A', 'E', '0', '2'}, YASL_KEY_2},
+        {{'A', 'E', '0', '3'}, YASL_KEY_3},
+        {{'A', 'E', '0', '4'}, YASL_KEY_4},
+        {{'A', 'E', '0', '5'}, YASL_KEY_5},
+        {{'A', 'E', '0', '6'}, YASL_KEY_6},
+        {{'A', 'E', '0', '7'}, YASL_KEY_7},
+        {{'A', 'E', '0', '8'}, YASL_KEY_8},
+        {{'A', 'E', '0', '9'}, YASL_KEY_9},
+        {{'A', 'E', '1', '0'}, YASL_KEY_0},
+        {{'A', 'E', '1', '1'}, YASL_KEY_MINUS},
+        {{'A', 'E', '1', '2'}, YASL_KEY_EQUAL},
+        {{'B', 'K', 'S', 'P'}, YASL_KEY_BACKSPACE},
+        {{'T', 'A', 'B', 0}, YASL_KEY_TAB},
+        {{'A', 'D', '0', '1'}, YASL_KEY_Q},
+        {{'A', 'D', '0', '2'}, YASL_KEY_W},
+        {{'A', 'D', '0', '3'}, YASL_KEY_E},
+        {{'A', 'D', '0', '4'}, YASL_KEY_R},
+        {{'A', 'D', '0', '5'}, YASL_KEY_T},
+        {{'A', 'D', '0', '6'}, YASL_KEY_Y},
+        {{'A', 'D', '0', '7'}, YASL_KEY_U},
+        {{'A', 'D', '0', '8'}, YASL_KEY_I},
+        {{'A', 'D', '0', '9'}, YASL_KEY_O},
+        {{'A', 'D', '1', '0'}, YASL_KEY_P},
+        {{'A', 'D', '1', '1'}, YASL_KEY_LEFT_BRACKET},
+        {{'A', 'D', '1', '2'}, YASL_KEY_RIGHT_BRACKET},
+        {{'B', 'K', 'S', 'L'}, YASL_KEY_BACKSLASH},
+        {{'R', 'T', 'R', 'N'}, YASL_KEY_ENTER},
+        {{'C', 'A', 'P', 'S'}, YASL_KEY_CAPS_LOCK},
+        {{'A', 'C', '0', '1'}, YASL_KEY_A},
+        {{'A', 'C', '0', '2'}, YASL_KEY_S},
+        {{'A', 'C', '0', '3'}, YASL_KEY_D},
+        {{'A', 'C', '0', '4'}, YASL_KEY_F},
+        {{'A', 'C', '0', '5'}, YASL_KEY_G},
+        {{'A', 'C', '0', '6'}, YASL_KEY_H},
+        {{'A', 'C', '0', '7'}, YASL_KEY_J},
+        {{'A', 'C', '0', '8'}, YASL_KEY_K},
+        {{'A', 'C', '0', '9'}, YASL_KEY_L},
+        {{'A', 'C', '1', '0'}, YASL_KEY_SEMICOLON},
+        {{'A', 'C', '1', '1'}, YASL_KEY_APOSTROPHE},
+        {{'L', 'F', 'S', 'H'}, YASL_KEY_LEFT_SHIFT},
+        {{'L', 'S', 'G', 'T'}, YASL_KEY_ISO_BACKSLASH},
+        {{'A', 'B', '0', '1'}, YASL_KEY_Z},
+        {{'A', 'B', '0', '2'}, YASL_KEY_X},
+        {{'A', 'B', '0', '3'}, YASL_KEY_C},
+        {{'A', 'B', '0', '4'}, YASL_KEY_V},
+        {{'A', 'B', '0', '5'}, YASL_KEY_B},
+        {{'A', 'B', '0', '6'}, YASL_KEY_N},
+        {{'A', 'B', '0', '7'}, YASL_KEY_M},
+        {{'A', 'B', '0', '8'}, YASL_KEY_COMMA},
+        {{'A', 'B', '0', '9'}, YASL_KEY_PERIOD},
+        {{'A', 'B', '1', '0'}, YASL_KEY_SLASH},
+        {{'R', 'T', 'S', 'H'}, YASL_KEY_RIGHT_SHIFT},
+        {{'L', 'C', 'T', 'L'}, YASL_KEY_LEFT_CONTROL},
+        {{'L', 'W', 'I', 'N'}, YASL_KEY_LEFT_SUPER},
+        {{'L', 'A', 'L', 'T'}, YASL_KEY_LEFT_ALT},
+        {{'S', 'P', 'C', 'E'}, YASL_KEY_SPACE},
+        {{'R', 'A', 'L', 'T'}, YASL_KEY_RIGHT_ALT},
+        {{'R', 'W', 'I', 'N'}, YASL_KEY_RIGHT_SUPER},
+        {{'C', 'O', 'M', 'P'}, YASL_KEY_MENU},
+        {{'R', 'C', 'T', 'L'}, YASL_KEY_RIGHT_CONTROL},
+        {{'E', 'S', 'C', 0}, YASL_KEY_ESCAPE},
+        {{'F', 'K', '0', '1'}, YASL_KEY_F1},
+        {{'F', 'K', '0', '2'}, YASL_KEY_F2},
+        {{'F', 'K', '0', '3'}, YASL_KEY_F3},
+        {{'F', 'K', '0', '4'}, YASL_KEY_F4},
+        {{'F', 'K', '0', '5'}, YASL_KEY_F5},
+        {{'F', 'K', '0', '6'}, YASL_KEY_F6},
+        {{'F', 'K', '0', '7'}, YASL_KEY_F7},
+        {{'F', 'K', '0', '8'}, YASL_KEY_F8},
+        {{'F', 'K', '0', '9'}, YASL_KEY_F9},
+        {{'F', 'K', '1', '0'}, YASL_KEY_F10},
+        {{'F', 'K', '1', '1'}, YASL_KEY_F11},
+        {{'F', 'K', '1', '2'}, YASL_KEY_F12},
+        {{'P', 'R', 'S', 'C'}, YASL_KEY_PRINT_SCREEN},
+        {{'S', 'C', 'L', 'K'}, YASL_KEY_SCROLL_LOCK},
+        {{'P', 'A', 'U', 'S'}, YASL_KEY_PAUSE},
+        {{'I', 'N', 'S', 0}, YASL_KEY_INSERT},
+        {{'H', 'O', 'M', 'E'}, YASL_KEY_HOME},
+        {{'P', 'G', 'U', 'P'}, YASL_KEY_PAGE_UP},
+        {{'D', 'E', 'L', 'E'}, YASL_KEY_DELETE},
+        {{'E', 'N', 'D', 0}, YASL_KEY_END},
+        {{'P', 'G', 'D', 'N'}, YASL_KEY_PAGE_DOWN},
+        {{'U', 'P', 0, 0}, YASL_KEY_UP},
+        {{'L', 'E', 'F', 'T'}, YASL_KEY_LEFT},
+        {{'D', 'O', 'W', 'N'}, YASL_KEY_DOWN},
+        {{'R', 'G', 'H', 'T'}, YASL_KEY_RIGHT},
+        {{'N', 'M', 'L', 'K'}, YASL_KEY_NUM_LOCK},
+        {{'K', 'P', 'D', 'V'}, YASL_KEY_KP_DIVIDE},
+        {{'K', 'P', 'M', 'U'}, YASL_KEY_KP_MULTIPLY},
+        {{'K', 'P', 'S', 'U'}, YASL_KEY_KP_SUBTRACT},
+        {{'K', 'P', '7', 0}, YASL_KEY_KP_7},
+        {{'K', 'P', '8', 0}, YASL_KEY_KP_8},
+        {{'K', 'P', '9', 0}, YASL_KEY_KP_9},
+        {{'K', 'P', 'A', 'D'}, YASL_KEY_KP_ADD},
+        {{'K', 'P', '4', 0}, YASL_KEY_KP_4},
+        {{'K', 'P', '5', 0}, YASL_KEY_KP_5},
+        {{'K', 'P', '6', 0}, YASL_KEY_KP_6},
+        {{'K', 'P', '1', 0}, YASL_KEY_KP_1},
+        {{'K', 'P', '2', 0}, YASL_KEY_KP_2},
+        {{'K', 'P', '3', 0}, YASL_KEY_KP_3},
+        {{'K', 'P', 'E', 'N'}, YASL_KEY_KP_ENTER},
+        {{'K', 'P', '0', 0}, YASL_KEY_KP_0},
+        {{'K', 'P', 'D', 'L'}, YASL_KEY_KP_DECIMAL},
+        {{'K', 'P', 'E', 'Q'}, YASL_KEY_KP_EQUAL},
+        {{'F', 'K', '1', '3'}, YASL_KEY_F13},
+        {{'F', 'K', '1', '4'}, YASL_KEY_F14},
+        {{'F', 'K', '1', '5'}, YASL_KEY_F15},
+        {{'F', 'K', '1', '6'}, YASL_KEY_F16},
+        {{'F', 'K', '1', '7'}, YASL_KEY_F17},
+        {{'F', 'K', '1', '8'}, YASL_KEY_F18},
+        {{'F', 'K', '1', '9'}, YASL_KEY_F19},
+        {{'F', 'K', '2', '0'}, YASL_KEY_F20},
+        {{'F', 'K', '2', '1'}, YASL_KEY_F21},
+        {{'F', 'K', '2', '2'}, YASL_KEY_F22},
+        {{'F', 'K', '2', '3'}, YASL_KEY_F23},
+        {{'F', 'K', '2', '4'}, YASL_KEY_F24},
+        {{'H', 'K', 'T', 'G'}, YASL_KEY_KANA},
+        {{'A', 'B', '1', '1'}, YASL_KEY_RO},
+        {{'H', 'E', 'N', 'K'}, YASL_KEY_CONVERT},
+        {{'M', 'U', 'H', 'E'}, YASL_KEY_NONCONVERT},
+        {{'A', 'E', '1', '3'}, YASL_KEY_YEN},
+        {{'M', 'U', 'T', 'E'}, YASL_KEY_MUTE},
+        {{'I', '1', '2', '9'}, YASL_KEY_KP_COMMA},
+    };
+    for (size_t i = 0; i < sizeof(keys) / sizeof(keys[0]); i++)
+        if (memcmp(keys[i].name, name, 4) == 0) return keys[i].key;
+    return YASL_KEY_UNKNOWN;
+}
diff --git a/src/common/keyboard.h b/src/common/keyboard.h
new file mode 100644
index 0000000..50ddbb3
--- /dev/null
+++ b/src/common/keyboard.h
@@ -0,0 +1,18 @@
+#ifndef YASL_COMMON_KEYBOARD_H
+#define YASL_COMMON_KEYBOARD_H
+
+#include "yasl/yasl.h"
+
+enum yasl_key yasl_key_from_evdev(uint32_t code);
+enum yasl_key yasl_key_from_xkb_name(const char name[4]);
+enum yasl_key yasl_key_from_cocoa(uint32_t code);
+
+/* Layout labels omit controls, invalid Unicode, and Cocoa function-key PUA. */
+static inline uint32_t yasl_key_label(uint32_t cp)
+{
+    return cp >= 0x20 && cp != 0x7f && cp <= 0x10ffff &&
+        !(cp >= 0x80 && cp <= 0x9f) && !(cp >= 0xd800 && cp <= 0xdfff) &&
+        !(cp >= 0xf700 && cp <= 0xf7ff) ? cp : 0;
+}
+
+#endif
diff --git a/src/common/meson.build b/src/common/meson.build
index ddd0194..1247ff5 100644
--- a/src/common/meson.build
+++ b/src/common/meson.build
@@ -1 +1 @@
-sources += files('backend.c', 'input.c', 'loop.c', 'native.c', 'timing.c', 'utf8.c')
+sources += files('backend.c', 'input.c', 'keyboard.c', 'loop.c', 'native.c', 'timing.c', 'utf8.c')
diff --git a/src/common/utf8.c b/src/common/utf8.c
index 1d4cf13..78a5d8e 100644
--- a/src/common/utf8.c
+++ b/src/common/utf8.c
@@ -1,3 +1,4 @@
+#include "utf8.h"
 #include <stdlib.h>
 #include <string.h>
 #include <stdbool.h>
@@ -12,11 +13,12 @@
 
 bool yasl_utf8_validate(const char *str, size_t len)
 {
+    if (!str) return len == 0;
     const unsigned char *p = (const unsigned char *)str;
     const unsigned char *end = p + len;
 
     while (p < end) {
-        while (p + 8 <= end) {
+        while ((size_t)(end - p) >= 8) {
             uint64_t v;
             memcpy(&v, p, 8);
             if (v & 0x8080808080808080ull)
@@ -28,18 +30,18 @@ bool yasl_utf8_validate(const char *str, size_t len)
         if (likely(*p < 0x80)) {
             p++;
         } else if ((*p & 0xe0) == 0xc0) {
-            if (unlikely(p + 1 >= end || (p[1] & 0xc0) != 0x80 || (*p & 0x1e) == 0))
+            if (unlikely(end - p < 2 || (p[1] & 0xc0) != 0x80 || (*p & 0x1e) == 0))
                 return false;
             p += 2;
         } else if ((*p & 0xf0) == 0xe0) {
-            if (unlikely(p + 2 >= end || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80))
+            if (unlikely(end - p < 3 || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80))
                 return false;
             uint32_t cp = ((p[0] & 0x0f) << 12) | ((p[1] & 0x3f) << 6) | (p[2] & 0x3f);
             if (unlikely(cp < 0x800 || (cp >= 0xd800 && cp <= 0xdfff)))
                 return false;
             p += 3;
         } else if ((*p & 0xf8) == 0xf0) {
-            if (unlikely(p + 3 >= end || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80 || (p[3] & 0xc0) != 0x80))
+            if (unlikely(end - p < 4 || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80 || (p[3] & 0xc0) != 0x80))
                 return false;
             uint32_t cp = ((p[0] & 0x07) << 18) | ((p[1] & 0x3f) << 12) | ((p[2] & 0x3f) << 6) | (p[3] & 0x3f);
             if (unlikely(cp < 0x10000 || cp > 0x10ffff))
@@ -52,6 +54,46 @@ bool yasl_utf8_validate(const char *str, size_t len)
     return true;
 }
 
+char *yasl_utf8_from_latin1(const char *str, size_t len, size_t *out_len)
+{
+    if (len > (SIZE_MAX - 1) / 2) return NULL;
+    char *out = malloc(len * 2 + 1);
+    if (!out) return NULL;
+    size_t n = 0;
+    for (size_t i = 0; i < len; i++) {
+        unsigned char ch = (unsigned char)str[i];
+        if (ch < 0x80) out[n++] = (char)ch;
+        else {
+            out[n++] = (char)(0xc0 | (ch >> 6));
+            out[n++] = (char)(0x80 | (ch & 0x3f));
+        }
+    }
+    out[n] = '\0';
+    *out_len = n;
+    return out;
+}
+
+char *yasl_utf8_to_latin1(const char *str, size_t *out_len)
+{
+    char *out = malloc(strlen(str) + 1);
+    if (!out) return NULL;
+    const unsigned char *p = (const unsigned char *)str;
+    size_t n = 0;
+    while (*p) {
+        if (*p < 0x80) out[n++] = (char)*p++;
+        else if ((*p == 0xc2 || *p == 0xc3) && (p[1] & 0xc0) == 0x80) {
+            out[n++] = (char)(((*p & 3) << 6) | (p[1] & 0x3f));
+            p += 2;
+        } else {
+            free(out);
+            return NULL;
+        }
+    }
+    out[n] = '\0';
+    *out_len = n;
+    return out;
+}
+
 char *yasl_utf8_sanitize_dup(const char *str)
 {
     if (unlikely(!str)) return NULL;
diff --git a/src/common/utf8.h b/src/common/utf8.h
new file mode 100644
index 0000000..f31c99d
--- /dev/null
+++ b/src/common/utf8.h
@@ -0,0 +1,14 @@
+#ifndef YASL_COMMON_UTF8_H
+#define YASL_COMMON_UTF8_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+bool yasl_utf8_validate(const char *str, size_t len);
+char *yasl_utf8_sanitize_dup(const char *str);
+/* Owned conversions for X11 STRING interoperability. to_latin1 rejects text
+ * outside Latin-1; byte lengths exclude the allocated NUL terminator. */
+char *yasl_utf8_from_latin1(const char *str, size_t len, size_t *out_len);
+char *yasl_utf8_to_latin1(const char *str, size_t *out_len);
+
+#endif