Update DESIGN.md

DESIGN.md

@@ -16,12 +16,28 @@ However, we don't have any VS Code API to capture keystrokes directly.
 
 ## Capturing keystrokes
 
-We have keybindings. Using that we can associate keystrokes with commands.
+We have keybindings. Using that feature we can associate keystrokes with commands.
 
 However, we can't associate every possible keystroke by defining a single keybinding rule (imagine kind of using wildcard `"key": "*"`).
 
 So we end up defining a bunch of wrapper keybindings to capture the whole set of the default keybindings of VS Code.
 
+# Wrapper keybindings
+
+A wrapper keybinding associates a particular combination of `key` and `when` with the `kb-macro.wrap` command with `args` parameter that specifies the target command to be invoked. The `kb-macro.wrap` command executes the target command. This indirect execution makes it possible to capture the command that has been triggered by user's keystrokes.
+
+We use the wrapper command only when the macro recording is ongoing. So we add the `kb-macro.recording` context to the original `when` value.
+
+Why don't we use the wrapper keybindings always to simplify things? Because we want to keep the original behavior of each command for the keybindings as much as possible. It is not clear but the indirect execution may not be perfectly transparent.
+
+## Default wrapper keybindings
+
+This extension defines a large set of keybindins to capture all the default keyboard shortcuts of VS Code.
+
+The list of default wrapper keybindings is defined in the `package.json` of this extension. The list is automatically generated by a script `generator/gen-wrapper.js`. The script takes JSON files that contain the default keybindings of VS Code for Windows, Linux, and macOS, and combines all the keybindings in them with additional context such as `isWindows`, `isLinux`, or `isMac` as needed, and convert them to wrappers and write them into `keybindings` section of the `package.json`.
+
+The script also performs some optimization work to reduce the amount of wrapper keybinding rules.
+
 ## Capturing typed characters
 
 On VS Code, typed characters in text editors are treated differently than other keystrokes. We don't put every possible character in the keybindings. When you type characters in a text editor, for each character, the `type` build-in command is invoked internally. The `type` command performs inserting each character into the document.