From 333bbc56f92cf652888af08856d70fb6cd8874fe Mon Sep 17 00:00:00 2001
From: loveuer <loveuer@live.com>
Date: Wed, 3 Dec 2025 10:26:38 +0800
Subject: [PATCH] chore: add KEY_MAPPING.md, update README.md

---
 KEY_MAPPING.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md      |   4 +-
 2 files changed, 151 insertions(+), 1 deletion(-)
 create mode 100644 KEY_MAPPING.md

diff --git a/KEY_MAPPING.md b/KEY_MAPPING.md
new file mode 100644
index 0000000..fdeb3f1
--- /dev/null
+++ b/KEY_MAPPING.md
@@ -0,0 +1,148 @@
+# macOS Key Code Reference
+
+This document lists common macOS key codes for keyboard remapping configuration.
+
+## Alphanumeric Keys
+
+| Key | Code | Description |
+|-----|------|-------------|
+| A | 0 | Letter A |
+| S | 1 | Letter S |
+| D | 2 | Letter D |
+| F | 3 | Letter F |
+| H | 4 | Letter H |
+| G | 5 | Letter G |
+| Z | 6 | Letter Z |
+| X | 7 | Letter X |
+| C | 8 | Letter C |
+| V | 9 | Letter V |
+| B | 11 | Letter B |
+| Q | 12 | Letter Q |
+| W | 13 | Letter W |
+| E | 14 | Letter E |
+| R | 15 | Letter R |
+| Y | 16 | Letter Y |
+| T | 17 | Letter T |
+| 1 | 18 | Number 1 |
+| 2 | 19 | Number 2 |
+| 3 | 20 | Number 3 |
+| 4 | 21 | Number 4 |
+| 6 | 22 | Number 6 |
+| 5 | 23 | Number 5 |
+| = | 24 | Equal sign |
+| 9 | 25 | Number 9 |
+| 7 | 26 | Number 7 |
+| - | 27 | Minus/Hyphen |
+| 8 | 28 | Number 8 |
+| 0 | 29 | Number 0 |
+| ] | 30 | Right bracket |
+| O | 31 | Letter O |
+| U | 32 | Letter U |
+| [ | 33 | Left bracket |
+| I | 34 | Letter I |
+| P | 35 | Letter P |
+| L | 37 | Letter L |
+| J | 38 | Letter J |
+| ' | 39 | Quote/Apostrophe |
+| K | 40 | Letter K |
+| ; | 41 | Semicolon |
+| \ | 42 | Backslash |
+| , | 43 | Comma |
+| / | 44 | Slash |
+| N | 45 | Letter N |
+| M | 46 | Letter M |
+| . | 47 | Period/Dot |
+| ` | 50 | Grave accent/Backtick |
+
+## Function Keys
+
+| Key | Code | Description |
+|-----|------|-------------|
+| Return | 36 | Enter/Return key |
+| Tab | 48 | Tab key |
+| Space | 49 | Space bar |
+| Delete | 51 | Backspace/Delete |
+| Escape | 53 | Escape key |
+| Command | 55 | Command/Cmd key |
+| Shift | 56 | Shift key |
+| CapsLock | 57 | Caps Lock |
+| Option | 58 | Option/Alt key |
+| Control | 59 | Control key |
+| RightShift | 60 | Right Shift key |
+| RightOption | 61 | Right Option/Alt key |
+| RightControl | 62 | Right Control key |
+| Function | 63 | Function/Fn key |
+
+## Special Keys
+
+| Key | Code | Description |
+|-----|------|-------------|
+| F5 | 96 | F5 key |
+| F6 | 97 | F6 key |
+| F7 | 98 | F7 key |
+| F3 | 99 | F3 key |
+| F8 | 100 | F8 key |
+| F9 | 101 | F9 key |
+| F11 | 103 | F11 key |
+| F13 | 105 | F13 key |
+| F14 | 107 | F14 key |
+| F10 | 109 | F10 key |
+| F12 | 111 | F12 key |
+| F15 | 113 | F15 key |
+| Help | 114 | Help key |
+| Home | 115 | Home key |
+| PageUp | 116 | Page Up |
+| ForwardDelete | 117 | Forward Delete (Del) |
+| F4 | 118 | F4 key |
+| End | 119 | End key |
+| F2 | 120 | F2 key |
+| PageDown | 121 | Page Down |
+| F1 | 122 | F1 key |
+| LeftArrow | 123 | Left Arrow |
+| RightArrow | 124 | Right Arrow |
+| DownArrow | 125 | Down Arrow |
+| UpArrow | 126 | Up Arrow |
+
+## Numpad Keys
+
+| Key | Code | Description |
+|-----|------|-------------|
+| Keypad . | 65 | Decimal point |
+| Keypad * | 67 | Multiply |
+| Keypad + | 69 | Add |
+| Keypad Clear | 71 | Clear |
+| Keypad / | 75 | Divide |
+| Keypad Enter | 76 | Enter |
+| Keypad - | 78 | Subtract |
+| Keypad = | 81 | Equal |
+| Keypad 0 | 82 | Number 0 |
+| Keypad 1 | 83 | Number 1 |
+| Keypad 2 | 84 | Number 2 |
+| Keypad 3 | 85 | Number 3 |
+| Keypad 4 | 86 | Number 4 |
+| Keypad 5 | 87 | Number 5 |
+| Keypad 6 | 88 | Number 6 |
+| Keypad 7 | 89 | Number 7 |
+| Keypad 8 | 91 | Number 8 |
+| Keypad 9 | 92 | Number 9 |
+
+## Media and System Keys
+
+| Key | Code | Description |
+|-----|------|-------------|
+| Mute | 74 | Volume Mute |
+| VolumeUp | 72 | Volume Up |
+| VolumeDown | 73 | Volume Down |
+| Brightness Down | 145 | Display brightness down |
+| Brightness Up | 144 | Display brightness up |
+| Play/Pause | 16 | Media play/pause (F8) |
+| Previous Track | 17 | Previous track (F7) |
+| Next Track | 19 | Next track (F9) |
+
+## Notes
+
+- Key codes are decimal values used by macOS CGEvent API
+- Some media keys may require special handling or may not be remappable
+- Function keys (F1-F15) can have default system behaviors that may need to be overridden
+- Modifier keys (Command, Shift, Control, Option) can be combined with other keys
+- The codes listed are for US keyboard layout; other layouts may vary
diff --git a/README.md b/README.md
index 77377d7..04228a7 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,9 @@ The configuration file is automatically created at `~/.config/uskey/config.json`
 
 ### Key Codes
 
-Common macOS key codes:
+For a complete list of macOS key codes, see [KEY_MAPPING.md](KEY_MAPPING.md).
+
+Common examples:
 - Backspace: 51
 - Backslash `\`: 42
 - Enter: 36