diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000..6313b56c5
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+* text=auto eol=lf
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
deleted file mode 100644
index 19905a3b8..000000000
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: 'Bug: title_goes_here'
-labels: bug
-assignees: jtroo
-
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**Version**
-The kanata version prints in the log on startup, or you can also print it by passing the `--version` flag when running on the command line.
-
-**Relevant kanata configs**
-E.g. defcfg, defsrc, deflayer, defalias items. If in doubt, feel free to include your entire config.
-
-**To reproduce**
-Steps to reproduce the behaviour.
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Debug logs**
-If you think it might help with a non-obvious issue, run kanata from the command line and pass the `--debug` flag. This will print more info. Include the relevant log outputs this section if you did so.
-
-**Operating system**
-Linux or Windows?
-
-**Additional context**
-Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 000000000..35a58655d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,79 @@
+name: "Bug report"
+description: Create a report to help the project improve.
+labels: ["bug"]
+assignees: ["jtroo"]
+title: "Bug: title_goes_here"
+body:
+  - type: checkboxes
+    attributes:
+      label: Requirements
+      description: Before you create a bug report, please check the following
+      options:
+        - label: I've searched [platform-specific issues](https://github.com/jtroo/kanata/blob/main/docs/platform-known-issues.adoc), [issues](https://github.com/jtroo/kanata/issues) and [discussions](https://github.com/jtroo/kanata/discussions) to see if this has been reported before.
+          required: true
+        - label: My issue does not involve multiple simultaneous key presses, OR it does but I've confirmed it is not [key rollover or ghosting](https://github.com/jtroo/kanata/discussions/822).
+          required: true
+  - type: textarea
+    id: summary
+    attributes:
+      label: Describe the bug
+      description: |
+        A clear and concise description of what the bug is.
+        Ensure any config snippets are either in the next section or are code formatted.
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Relevant kanata config
+      render: text
+      description: E.g. defcfg, defsrc, deflayer, defalias items. If in doubt, feel free to include your entire config.
+    validations:
+      required: false
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: To Reproduce
+      description: |
+        Walk through the steps needed to reproduce the bug.
+        Use the simulator if it is not device/OS related: https://jtroo.github.io/.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Kanata version
+      description: The kanata version prints in the log on startup, or you can also print it by passing the `--version` flag when running on the command line.
+      placeholder: e.g. kanata 1.3.0
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Debug logs
+      description: If you think it might help with a non-obvious issue, run kanata from the command line and pass the `--debug` flag. This will print more info. Include the relevant log outputs this section if you did so.
+      render: text
+    validations:
+      required: false
+  - type: input
+    id: os
+    attributes:
+      label: Operating system and I/O mechanism
+      description: E.g. Linux, macOS, Windows 10, Windows 11 with Interception driver
+      placeholder: e.g. Linux
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other context about the problem here.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 000000000..8a1826f17
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discussions
+    url: https://github.com/jtroo/kanata/discussions
+    about: Ask for help or interact with the community.
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index a988ccbe9..000000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: 'Feature request: feature_summary_goes_here'
-labels: enhancement
-assignees: ''
-
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 000000000..f6f08c91c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,35 @@
+name: "Feature request"
+description: Suggest an idea for this project
+title: 'Feature request: feature_summary_goes_here'
+labels: ["enhancement"]
+assignees: []
+body:
+  - type: textarea
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: |
+        A clear and concise description of what the problem is.
+      placeholder: Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like.
+      description: |
+        A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe alternatives you've considered.
+      description: |
+        A clear and concise description of any alternative solutions or features you've considered.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: |
+        Add any other context or screenshots about the feature request here.
+    validations:
+      required: false
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 000000000..df26b4524
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,12 @@
+## Describe your changes. Use imperative present tense.
+
+## Checklist
+
+- Add documentation to docs/config.adoc
+  - [ ] Yes or N/A
+- Add example and basic docs to cfg_samples/kanata.kbd
+  - [ ] Yes or N/A
+- Update error messages
+  - [ ] Yes or N/A
+- Added tests, or did manual testing
+  - [ ] Yes
diff --git a/.github/workflows/build-everything.yml b/.github/workflows/build-everything.yml
new file mode 100644
index 000000000..3d839bb33
--- /dev/null
+++ b/.github/workflows/build-everything.yml
@@ -0,0 +1,17 @@
+name: build-everything
+
+on:
+  workflow_dispatch:
+    branches: [ "main" ]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: "-Dwarnings"
+
+jobs:
+  build-linux:
+    uses: ./.github/workflows/linux-build.yml
+  build-windows:
+    uses: ./.github/workflows/windows-build.yml
+  build-macos:
+    uses: ./.github/workflows/macos-build.yml
diff --git a/.github/workflows/linux-build.yml b/.github/workflows/linux-build.yml
new file mode 100644
index 000000000..81d8ec4a0
--- /dev/null
+++ b/.github/workflows/linux-build.yml
@@ -0,0 +1,32 @@
+name: linux-build
+
+on:
+  workflow_dispatch:
+    branches: [ "main" ]
+  workflow_call:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-linux-x64:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "persist-cross-job-linux-x64"
+      - name: Do the stuff on x64 ubuntu linux
+        shell: bash
+        run: |
+          mkdir -p artifacts-x64
+          cargo build --release
+          mv target/release/kanata artifacts-x64/kanata_linux_x64
+          cargo build --release --features cmd
+          mv target/release/kanata artifacts-x64/kanata_linux_cmd_allowed_x64
+      - uses: actions/upload-artifact@v7
+        with:
+          name: linux-binaries-x64
+          path: |
+            artifacts-x64/kanata_linux_x64
+            artifacts-x64/kanata_linux_cmd_allowed_x64
diff --git a/.github/workflows/macos-build.yml b/.github/workflows/macos-build.yml
new file mode 100644
index 000000000..d984626d3
--- /dev/null
+++ b/.github/workflows/macos-build.yml
@@ -0,0 +1,60 @@
+name: macos-build
+
+on:
+  workflow_dispatch:
+    branches: [ "main" ]
+  workflow_call:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-macos-arm64:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          target: aarch64-apple-darwin
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "persist-cross-job-macos-aarch64"
+      - name: Do the stuff on arm64
+        shell: bash
+        run: |
+          mkdir -p artifacts-arm64
+          cargo build --release --target aarch64-apple-darwin
+          mv target/aarch64-apple-darwin/release/kanata artifacts-arm64/kanata_macos_arm64
+          cargo build --release --features cmd --target aarch64-apple-darwin
+          mv target/aarch64-apple-darwin/release/kanata artifacts-arm64/kanata_macos_cmd_allowed_arm64
+      - uses: actions/upload-artifact@v7
+        with:
+          name: macos-binaries-arm64
+          path: |
+            artifacts-arm64/kanata_macos_arm64
+            artifacts-arm64/kanata_macos_cmd_allowed_arm64
+
+  build-macos-x64:
+    runs-on: macos-15-intel
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: Swatinem/rust-cache@v2
+      with:
+        shared-key: "persist-cross-job-macos-x64"
+    - name: Do the stuff on x64
+      shell: bash
+      run: |
+        mkdir -p artifacts
+        cargo build --release
+        mv target/release/kanata artifacts/kanata_macos_x64
+        cargo build --release --features cmd
+        mv target/release/kanata artifacts/kanata_macos_cmd_allowed_x64
+    - uses: actions/upload-artifact@v7
+      with:
+        name: macos-binaries-x64
+        path: |
+          artifacts/kanata_macos_x64
+          artifacts/kanata_macos_cmd_allowed_x64
+
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index b1567062e..ca0dc5f8b 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -6,18 +6,23 @@ on:
     paths:
       - Cargo.*
       - src/**/*
+      - keyberon/**/*
       - cfg_samples/**/*
-      - test_cfgs/**/*
-      - .github/workflows/**/*
+      - parser/**/*
+      - tcp_protocol/**/*
+      - wasm/**/*
+      - .github/workflows/rust.yml
   pull_request:
     branches: [ "main" ]
     paths:
       - Cargo.*
       - src/**/*
       - keyberon/**/*
+      - parser/**/*
       - cfg_samples/**/*
-      - test_cfgs/**/*
-      - .github/workflows/**/*
+      - tcp_protocol/**/*
+      - wasm/**/*
+      - .github/workflows/rust.yml
 
 env:
   CARGO_TERM_COLOR: always
@@ -28,46 +33,147 @@ jobs:
   fmt:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - name: Check fmt
       run: cargo fmt --all --check
 
+  build-android:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - build: linux
+            os: ubuntu-latest
+            target: aarch64-linux-android
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: Swatinem/rust-cache@v2
+      with:
+        shared-key: "persist-cross-job"
+        workspaces: ./
+    - run: rustup target add aarch64-linux-android
+
+    - name: Build for Android
+      run: cargo check --target aarch64-linux-android
+
   build-test-clippy-linux:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - build: linux
+            os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - uses: Swatinem/rust-cache@v2
       with:
         shared-key: "persist-cross-job"
         workspaces: ./
     - run: rustup component add clippy
-    - name: Run tests
-      run: cargo test --verbose
-    - name: Run tests all features
-      run: cargo test --all-features --verbose
+
+    - name: Run tests no features
+      run: cargo test --all --no-default-features
     - name: Run clippy no features
-      run: cargo clippy -- -D warnings
-    - name: Run clippy all features
-      run: cargo clippy --all-features -- -D warnings
+      run: cargo clippy --all --no-default-features -- -D warnings
+
+    - name: Run tests default features
+      run: cargo test --all
+    - name: Run clippy default features
+      run: cargo clippy --all -- -D warnings
+
+    - name: Run tests cmd
+      run: cargo test --all --features=cmd
+    - name: Run clippy cmd
+      run: cargo clippy --all --features=cmd -- -D warnings
+
+    - name: Run tests simulated output
+      run: cargo test --features=simulated_output -- sim_tests
+    - name: Run tests simulated output on_idle
+      run: cargo test --features=simulated_output -- must_be_single_threaded --ignored --test-threads=1
+    - name: Run clippy simulated output
+      run: cargo clippy --all --features=simulated_output,cmd -- -D warnings
+
+    - name: Run clippy for parser with lsp feature
+      run: cargo clippy -p kanata-parser --features=lsp -- -D warnings
 
   build-test-clippy-windows:
-    runs-on: windows-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        target:
-          - x86_64-pc-windows-msvc
+        include:
+          - build: windows
+            os: windows-latest
+            target: x86_64-pc-windows-msvc
+
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
     - uses: Swatinem/rust-cache@v2
       with:
         shared-key: "persist-cross-job"
         workspaces: ./
     - run: rustup component add clippy
-    - name: Run tests
-      run: cargo test --verbose
-    - name: Run tests all features
-      run: cargo test --all-features --verbose
+
+    - name: Run tests no features
+      run: cargo test --all --no-default-features
     - name: Run clippy no features
-      run: cargo clippy
+      run: cargo clippy --all --no-default-features -- -D warnings
+
+    - name: Run tests default features
+      run: cargo test --all
+    - name: Run clippy default features
+      run: cargo clippy --all -- -D warnings
+
+    - name: Run tests winIOv2
+      run: cargo test --all --features=cmd,win_llhook_read_scancodes,win_sendinput_send_scancodes
+    - name: Run clippy all winIOv2
+      run: cargo clippy --all --features=cmd,win_llhook_read_scancodes,win_sendinput_send_scancodes -- -D warnings
+
+    - name: Run tests all features
+      run: cargo test  -p kanata -p kanata-parser -p kanata-keyberon -p kanata-tcp-protocol --features=cmd,interception_driver,win_sendinput_send_scancodes
+    - name: Run clippy all features
+      run: cargo clippy --all --features=cmd,interception_driver,win_sendinput_send_scancodes -- -D warnings
+
+    - name: Run tests simulated output
+      run: cargo test --features=simulated_output -- sim_tests
+    - name: Run tests simulated output on_idle
+      run: cargo test --features=simulated_output -- sim_tests::vkey_sim_tests::on_idle --ignored
+    - name: Run clippy simulated output
+      run: cargo clippy --all --features=simulated_output,cmd -- -D warnings
+
+    - name: Run tests gui
+      run: cargo test --all --features=gui
+    - name: Run clippy gui
+      run: cargo clippy --all --features=gui -- -D warnings
+
+    - name: Check gui+cmd+interception
+      run: cargo check --features gui,cmd,interception_driver
+
+  build-test-clippy-macos:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - build: macos
+            os: macos-latest
+            target: x86_64-apple-darwin
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: Swatinem/rust-cache@v2
+      with:
+        shared-key: "persist-cross-job"
+        workspaces: ./
+    - run: rustup component add clippy
+
+    - name: Run tests default features
+      run: cargo test --all
+    - name: Run clippy default features
+      run: cargo clippy --all -- -D warnings
+
+    - name: Run tests cmd
+      run: cargo test --all --features=cmd
     - name: Run clippy all features
-      run: cargo clippy --all-features
+      run: cargo clippy --all --features=cmd -- -D warnings
diff --git a/.github/workflows/windows-build.yml b/.github/workflows/windows-build.yml
new file mode 100644
index 000000000..3046ce9ad
--- /dev/null
+++ b/.github/workflows/windows-build.yml
@@ -0,0 +1,83 @@
+name: windows-build
+
+on:
+  workflow_dispatch:
+    branches: [ "main" ]
+  workflow_call:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-windows-x64:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "persist-cross-job-win-x64"
+      - name: Build x64
+        shell: powershell
+        run: |
+          md artifacts
+          cargo build --release --features win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_winIOv2_x64.exe
+          cargo build --release --features win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes,cmd --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_winIOv2_cmd_allowed_x64.exe
+          cargo build --release --features win_manifest,interception_driver --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_wintercept_x64.exe
+          cargo build --release --features win_manifest,cmd,interception_driver --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_wintercept_cmd_allowed_x64.exe
+          cargo build --release --features gui,win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_winIOv2_x64.exe
+          cargo build --release --features gui,win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes,cmd --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_winIOv2_cmd_allowed_x64.exe
+          cargo build --release --features gui,win_manifest,interception_driver --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_wintercept_x64.exe
+          cargo build --release --features gui,win_manifest,cmd,interception_driver --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_wintercept_cmd_allowed_x64.exe
+          cargo build --release --features passthru_ahk --package=simulated_passthru --target x86_64-pc-windows-msvc
+          mv target/x86_64-pc-windows-msvc/release/kanata_passthru.dll artifacts/kanata_passthru_x64.dll
+      - uses: actions/upload-artifact@v7
+        with:
+          name: windows-binaries-x64
+          path: |
+            artifacts/kanata_windows_tty_winIOv2_x64.exe
+            artifacts/kanata_windows_tty_winIOv2_cmd_allowed_x64.exe
+            artifacts/kanata_windows_tty_wintercept_x64.exe
+            artifacts/kanata_windows_tty_wintercept_cmd_allowed_x64.exe
+            artifacts/kanata_windows_gui_winIOv2_x64.exe
+            artifacts/kanata_windows_gui_winIOv2_cmd_allowed_x64.exe
+            artifacts/kanata_windows_gui_wintercept_x64.exe
+            artifacts/kanata_windows_gui_wintercept_cmd_allowed_x64.exe
+            artifacts/kanata_passthru_x64.dll
+
+  build-windows-arm64:
+    runs-on: windows-11-arm
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "persist-cross-job-win-arm64"
+      - name: Build arm64
+        shell: powershell
+        run: |
+          md artifacts
+          cargo build --release --features win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes --target aarch64-pc-windows-msvc
+          mv target/aarch64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_winIOv2_arm64.exe
+          cargo build --release --features win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes,cmd --target aarch64-pc-windows-msvc
+          mv target/aarch64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_tty_winIOv2_cmd_allowed_arm64.exe
+          cargo build --release --features gui,win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes --target aarch64-pc-windows-msvc
+          mv target/aarch64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_winIOv2_arm64.exe
+          cargo build --release --features gui,win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes,cmd --target aarch64-pc-windows-msvc
+          mv target/aarch64-pc-windows-msvc/release/kanata.exe artifacts/kanata_windows_gui_winIOv2_cmd_allowed_arm64.exe
+      - uses: actions/upload-artifact@v7
+        with:
+          name: windows-binaries-arm64
+          path: |
+            artifacts/kanata_windows_tty_winIOv2_arm64.exe
+            artifacts/kanata_windows_tty_winIOv2_cmd_allowed_arm64.exe
+            artifacts/kanata_windows_gui_winIOv2_arm64.exe
+            artifacts/kanata_windows_gui_winIOv2_cmd_allowed_arm64.exe
diff --git a/.gitignore b/.gitignore
index dc4969608..c2d6d6a9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,10 @@
 **/target
 .vscode/
+CLAUDE.md
+.DS_Store
+PLAN.md
+
+# Manual testing files
+test_*.kbd
+manual_test/
+*.test.kbd
diff --git a/Cargo.lock b/Cargo.lock
index ec29f5ce8..18bca0ac5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1,88 +1,138 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 
 [[package]]
 name = "addr2line"
-version = "0.19.0"
+version = "0.24.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a76fd60b23679b7d19bd066031410fb7e458ccc5e958eb5c325888ce4baedc97"
+checksum = "dfbe277e56a376000877090da837660b4427aad530e3028d44e0bffe4f89a1c1"
 dependencies = [
  "gimli",
 ]
 
 [[package]]
-name = "adler"
-version = "1.0.2"
+name = "adler2"
+version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f26201604c87b1e01bd3d98f8d5d9a8fcbb815e8cedb41ffccbeb4bf593a35fe"
+checksum = "512761e0bb2578dd7380c6baaa0f4ce03e84f95e960231d1dec8bf4d7d6e2627"
 
 [[package]]
-name = "ahash"
-version = "0.7.6"
+name = "aho-corasick"
+version = "1.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fcb51a0695d8f838b1ee009b3fbf66bda078cd64590202a864a8f3e8c4315c47"
+checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916"
 dependencies = [
- "getrandom",
- "once_cell",
- "version_check",
+ "memchr",
 ]
 
 [[package]]
-name = "aho-corasick"
-version = "1.0.1"
+name = "anstream"
+version = "0.6.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67fc08ce920c31afb70f013dcce1bfc3a3195de6a228474e45e1f145b36f8d04"
+checksum = "23a1e53f0f5d86382dafe1cf314783b2044280f406e7e1506368220ad11b1338"
 dependencies = [
- "memchr",
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
 ]
 
 [[package]]
 name = "anstyle"
-version = "1.0.0"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8365de52b16c035ff4fcafe0092ba9390540e3e352870ac09933bebcaa2c8c56"
+
+[[package]]
+name = "anstyle-parse"
+version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41ed9a86bf92ae6580e0a31281f65a1b1d867c0cc68d5346e2ae128dddfa6a7d"
+checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c"
+dependencies = [
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2109dbce0e72be3ec00bed26e6a7479ca384ad226efdd66db8fa2e3a38c83125"
+dependencies = [
+ "anstyle",
+ "windows-sys 0.59.0",
+]
 
 [[package]]
 name = "anyhow"
-version = "1.0.71"
+version = "1.0.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9c7d0618f0e0b7e8ff11427422b64564d5fb0be1940354bfe2e0529b18a9d9b8"
+checksum = "c042108f3ed77fd83760a5fd79b53be043192bb3b9dba91d8c574c0ada7850c8"
+
+[[package]]
+name = "arboard"
+version = "3.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df099ccb16cd014ff054ac1bf392c67feeef57164b05c42f037cd40f5d4357f4"
+dependencies = [
+ "clipboard-win",
+ "core-graphics 0.23.2",
+ "image",
+ "log",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+ "parking_lot",
+ "windows-sys 0.48.0",
+ "x11rb",
+]
 
 [[package]]
 name = "arraydeque"
-version = "0.4.5"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0ffd3d69bd89910509a5d31d1f1353f38ccffdd116dd0099bbd6627f7bd8ad8"
+checksum = "7d902e3d592a523def97af8f317b08ce16b7ab854c1985a0c671e6f15cebc236"
 
 [[package]]
 name = "atomic-polyfill"
-version = "0.1.11"
+version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3ff7eb3f316534d83a8a2c3d1674ace8a5a71198eba31e2e2b597833f699b28"
+checksum = "8cf2bce30dfe09ef0bfaef228b9d414faaf7e563035494d7fe092dba54b300f4"
 dependencies = [
  "critical-section",
 ]
 
 [[package]]
 name = "autocfg"
-version = "1.1.0"
+version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa"
+checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26"
 
 [[package]]
 name = "backtrace"
-version = "0.3.67"
+version = "0.3.74"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "233d376d6d185f2a3093e58f283f60f880315b6c60075b01f36b3b85154564ca"
+checksum = "8d82cb332cdfaed17ae235a638438ac4d4839913cc2af585c3c6746e8f8bee1a"
 dependencies = [
  "addr2line",
- "cc",
  "cfg-if",
  "libc",
  "miniz_oxide",
  "object",
  "rustc-demangle",
+ "windows-targets 0.52.6",
 ]
 
 [[package]]
@@ -100,6 +150,12 @@ version = "1.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
+[[package]]
+name = "bitflags"
+version = "2.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b8e56985ec62d17e9c1001dc89c88ecd7dc08e47eba5ec7c29c7b5eeecde967"
+
 [[package]]
 name = "bitvec"
 version = "1.0.1"
@@ -112,17 +168,49 @@ dependencies = [
  "wyz",
 ]
 
+[[package]]
+name = "block2"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c132eebf10f5cad5289222520a4a058514204aed6d791f1cf4fe8088b82d15f"
+dependencies = [
+ "objc2",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46c5e41b57b8bba42a04676d81cb89e9ee8e859a1a66f80a5a72e1cb76b34d43"
+
+[[package]]
+name = "bytemuck"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8334215b81e418a0a7bdb8ef0849474f40bb10c8b71f1c4ed315cff49f32494d"
+
 [[package]]
 name = "byteorder"
-version = "1.4.3"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "14c189c53d098945499cdfa7ecc63567cf3886b3332b312a5b4585d8d3a6a610"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
 
 [[package]]
 name = "cc"
-version = "1.0.79"
+version = "1.1.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50d30906286121d95be3d479533b458f87493b30a4b5f79a607db8f5d11aa91f"
+checksum = "c2e7962b54006dcfcc61cb72735f4d89bb97061dd6a7ed882ec6b8ee53714c6f"
+dependencies = [
+ "jobserver",
+ "libc",
+ "shlex",
+]
 
 [[package]]
 name = "cfg-if"
@@ -130,34 +218,39 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
 [[package]]
 name = "clap"
-version = "4.3.0"
+version = "4.5.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "93aae7a4192245f70fe75dd9157fc7b4a5bf53e88d30bd4396f7d8f9284d5acc"
+checksum = "b97f376d85a664d5837dbae44bf546e6477a679ff6610010f17276f686d867e8"
 dependencies = [
  "clap_builder",
  "clap_derive",
- "once_cell",
 ]
 
 [[package]]
 name = "clap_builder"
-version = "4.3.0"
+version = "4.5.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f423e341edefb78c9caba2d9c7f7687d0e72e89df3ce3394554754393ac3990"
+checksum = "19bc80abd44e4bed93ca373a0704ccbd1b710dc5749406201bb018272808dc54"
 dependencies = [
+ "anstream",
  "anstyle",
- "bitflags",
  "clap_lex",
  "strsim",
 ]
 
 [[package]]
 name = "clap_derive"
-version = "4.3.0"
+version = "4.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "191d9573962933b4027f932c600cd252ce27a8ad5979418fe78e43c07996f27b"
+checksum = "4ac6a0c7b1a9e9a5186361f67dfa1b88213572f427fb9ab038efb2bd8c582dab"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -167,15 +260,132 @@ dependencies = [
 
 [[package]]
 name = "clap_lex"
-version = "0.5.0"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1462739cb27611015575c0c11df5df7601141071f07518d56fcc1be504cbec97"
+
+[[package]]
+name = "clipboard-win"
+version = "5.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15efe7a882b08f34e38556b14f2fb3daa98769d06c7f0c1b076dfd0d983bc892"
+dependencies = [
+ "error-code",
+]
+
+[[package]]
+name = "colorchoice"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990"
+
+[[package]]
+name = "console_error_panic_hook"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06aeb73f470f66dcdbf7223caeebb85984942f22f1adb2a088cf9668146bbbc"
+dependencies = [
+ "cfg-if",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "core-graphics"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c07782be35f9e1140080c6b96f0d44b739e2278479f64e02fdab4e32dfd8b081"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation 0.9.4",
+ "core-graphics-types 0.1.3",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics"
+version = "0.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa95a34622365fa5bbf40b20b75dba8dfa8c94c734aea8ac9a5ca38af14316f1"
+dependencies = [
+ "bitflags 2.9.1",
+ "core-foundation 0.10.1",
+ "core-graphics-types 0.2.0",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2da6da31387c7e4ef160ffab6d5e7f00c42626fe39aea70a7b0f1773f7dd6c1b"
+checksum = "45390e6114f68f718cc7a830514a96f903cccd70d02a8f6d9f643ac4ba45afaf"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation 0.9.4",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb"
+dependencies = [
+ "bitflags 2.9.1",
+ "core-foundation 0.10.1",
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a97769d94ddab943e4510d138150169a2758b5ef3eb191a9ee688de3e23ef7b3"
+dependencies = [
+ "cfg-if",
+]
 
 [[package]]
 name = "critical-section"
-version = "1.1.1"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "790eea4361631c5e7d22598ecd5723ff611904e3344ce8720784c93e3d83d40b"
+
+[[package]]
+name = "deranged"
+version = "0.5.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6548a0ad5d2549e111e1f6a11a6c2e2d00ce6a3dafe22948d67c2b443f775e52"
+checksum = "ececcb659e7ba858fb4f10388c250a7252eb0a27373f1a72b8748afdd248e587"
+dependencies = [
+ "powerfmt",
+]
 
 [[package]]
 name = "dirs"
@@ -198,6 +408,20 @@ dependencies = [
  "windows-sys 0.48.0",
 ]
 
+[[package]]
+name = "embed-resource"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4e24052d7be71f0efb50c201557f6fe7d237cfd5a64fd5bcd7fd8fe32dbbffa"
+dependencies = [
+ "cc",
+ "memchr",
+ "rustc_version",
+ "toml",
+ "vswhom",
+ "winreg",
+]
+
 [[package]]
 name = "encode_unicode"
 version = "0.3.6"
@@ -210,51 +434,107 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c34f04666d835ff5d62e058c3995147c06f42fe86ff053337632bca83e42702d"
 
+[[package]]
+name = "equivalent"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5"
+
 [[package]]
 name = "errno"
-version = "0.3.1"
+version = "0.3.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4bcfec3a70f97c962c307b2d2c56e358cf1d00b558d74262b5f929ee8cc7e73a"
+checksum = "33d852cb9b869c2a9b3df2f71a3074817f01e1844f839a144f5fcef059a4eb5d"
 dependencies = [
- "errno-dragonfly",
  "libc",
- "windows-sys 0.48.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
-name = "errno-dragonfly"
-version = "0.1.2"
+name = "error-code"
+version = "3.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aa68f1b12764fab894d2755d2518754e71b4fd80ecfb822714a1206c2aab39bf"
-dependencies = [
- "cc",
- "libc",
-]
+checksum = "a5d9305ccc6942a704f4335694ecd3de2ea531b114ac2d51f5f843750787a92f"
 
 [[package]]
 name = "evdev"
-version = "0.12.0"
+version = "0.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e78122445d7c3ce840f1a4f31eb7cee198b9004d03bfc161762d9b4a959d757c"
+checksum = "a3c10865aeab1a7399b3c2d6046e8dcc7f5227b656f235ed63ef5ee45a47b8f8"
 dependencies = [
  "bitvec",
  "cfg-if",
  "libc",
- "nix 0.23.2",
- "thiserror",
+ "nix 0.29.0",
 ]
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "flate2"
+version = "1.0.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c936bfdafb507ebbf50b8074c54fa31c5be9a1e7e5f467dd659697041407d07c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "foreign-types"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
+dependencies = [
+ "foreign-types-macros",
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-macros"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a5c6c585bc94aaf2c7b51dd4c2ba22680844aba4c687be581871a6f518c5742"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
+
 [[package]]
 name = "funty"
 version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
 
+[[package]]
+name = "gethostname"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0176e0459c2e4a1fe232f984bca6890e681076abb9934f6cea7c326f3fc47818"
+dependencies = [
+ "libc",
+ "windows-targets 0.48.5",
+]
+
 [[package]]
 name = "getrandom"
-version = "0.2.9"
+version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c85e1d9ab2eadba7e5040d4e09cbd6d072b76a557ad64e797c2cb9d4da21d7e4"
+checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7"
 dependencies = [
  "cfg-if",
  "libc",
@@ -263,9 +543,9 @@ dependencies = [
 
 [[package]]
 name = "gimli"
-version = "0.27.2"
+version = "0.31.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad0a93d233ebf96623465aad4046a8d3aa4da22d4f4beba5388838c8a434bbb4"
+checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f"
 
 [[package]]
 name = "hash32"
@@ -278,18 +558,15 @@ dependencies = [
 
 [[package]]
 name = "hashbrown"
-version = "0.12.3"
+version = "0.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
-dependencies = [
- "ahash",
-]
+checksum = "1e087f84d4f86bf4b218b927129862374b72199ae7d8657835f1e89000eea4fb"
 
 [[package]]
 name = "heapless"
-version = "0.7.16"
+version = "0.7.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "db04bc24a18b9ea980628ecf00e6c0264f3c1426dac36c00cb49b6fbad8b0743"
+checksum = "cdc6457c0eb62c71aac4bc17216026d8410337c4126773b9c5daba343f17964f"
 dependencies = [
  "atomic-polyfill",
  "hash32",
@@ -300,33 +577,52 @@ dependencies = [
 
 [[package]]
 name = "heck"
-version = "0.4.1"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "hermit-abi"
-version = "0.3.1"
+version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fed44880c466736ef9a5c5b5facefb5ed0785676d0c02d612db14e54f0d84286"
+checksum = "fbf6a919d6cf397374f7dfeeea91d974c7c0a7221d0d0f4f20d859d329e53fcc"
+
+[[package]]
+name = "image"
+version = "0.25.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd6f44aed642f18953a158afeb30206f4d50da59fbc66ecb53c66488de73563b"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "num-traits",
+ "png",
+ "tiff",
+]
 
 [[package]]
 name = "indexmap"
-version = "1.9.3"
+version = "2.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99"
+checksum = "707907fe3c25f5424cce2cb7e1cbcafee6bdbe735ca90ef77c29e84591e5b9da"
 dependencies = [
- "autocfg",
+ "equivalent",
  "hashbrown",
 ]
 
+[[package]]
+name = "indoc"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b248f5224d1d606005e02c97f5aa4e88eeb230488bcc03bc9ca4d7991399f2b5"
+
 [[package]]
 name = "inotify"
-version = "0.10.0"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abf888f9575c290197b2c948dc9e9ff10bd1a39ad1ea8585f734585fa6b9d3f9"
+checksum = "fdd168d97690d0b8c412d6b6c10360277f4d7ee495c5d0d5d5fe0854923255cc"
 dependencies = [
- "bitflags",
+ "bitflags 1.3.2",
  "inotify-sys",
  "libc",
 ]
@@ -347,77 +643,131 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "abe875cf6439eb5d98f0fdbcc6128fdef4870c47e0f898735105ff77685dfcd1"
 
 [[package]]
-name = "io-lifetimes"
-version = "1.0.10"
+name = "is-docker"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9c66c74d2ae7e79a5a8f7ac924adbe38ee42a859c6539ad869eb51f0b52dc220"
+checksum = "928bae27f42bc99b60d9ac7334e3a21d10ad8f1835a4e12ec3ec0464765ed1b3"
 dependencies = [
- "hermit-abi",
- "libc",
- "windows-sys 0.48.0",
+ "once_cell",
 ]
 
 [[package]]
 name = "is-terminal"
-version = "0.4.7"
+version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "adcf93614601c8129ddf72e2d5633df827ba6551541c6d8c59520a371475be1f"
+checksum = "261f68e344040fbd0edea105bef17c66edf46f984ddb1115b775ce31be948f4b"
 dependencies = [
  "hermit-abi",
- "io-lifetimes",
- "rustix",
- "windows-sys 0.48.0",
+ "libc",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "is-wsl"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "173609498df190136aa7dea1a91db051746d339e18476eed5ca40521f02d7aa5"
+dependencies = [
+ "is-docker",
+ "once_cell",
 ]
 
 [[package]]
 name = "is_ci"
-version = "1.1.1"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "616cde7c720bb2bb5824a224687d8f77bfd38922027f01d825cd7453be5099fb"
+checksum = "7655c9839580ee829dfacba1d1278c2b7883e50a277ff7541299489d6bdfdc45"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf"
 
 [[package]]
 name = "itoa"
-version = "1.0.6"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b"
+
+[[package]]
+name = "jobserver"
+version = "0.1.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48d1dbcbbeb6a7fec7e059840aa538bd62aaccf972c7346c4d9d2059312853d0"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "jpeg-decoder"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5d4a7da358eff58addd2877a45865158f0d78c911d43a5784ceb7bbf52833b0"
+
+[[package]]
+name = "js-sys"
+version = "0.3.77"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "453ad9f582a441959e5f0d088b02ce04cfe8d51a8eaf077f12ac6d3e94164ca6"
+checksum = "1cfaf33c695fc6e08064efbc1f72ec937429614f25eef83af942d0e227c3a28f"
+dependencies = [
+ "once_cell",
+ "wasm-bindgen",
+]
 
 [[package]]
 name = "kanata"
-version = "1.4.0-prerelease-2"
+version = "1.12.0-prerelease-2"
 dependencies = [
  "anyhow",
+ "arboard",
  "clap",
+ "core-foundation 0.10.1",
+ "core-graphics 0.24.0",
  "dirs",
+ "embed-resource",
  "encode_unicode",
  "evdev",
+ "indoc",
  "inotify",
  "kanata-interception",
  "kanata-keyberon",
  "kanata-parser",
+ "kanata-tcp-protocol",
+ "karabiner-driverkit",
+ "libc",
  "log",
  "miette",
  "mio",
+ "muldiv 1.0.1",
  "native-windows-gui",
- "nix 0.26.2",
+ "nix 0.26.4",
+ "objc",
  "once_cell",
+ "open",
+ "os_pipe",
  "parking_lot",
  "radix_trie",
+ "regex",
  "rustc-hash",
  "sd-notify",
- "serde",
  "serde_json",
  "signal-hook",
  "simplelog",
+ "strip-ansi-escapes",
+ "time",
+ "web-time",
  "winapi",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
 name = "kanata-interception"
-version = "0.2.0"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e43d8fef551ec7944871b21ad005f3728999fc1ebad09f9625db5c692d42f44e"
+checksum = "e2e57b9b964d19ac86906ea56e8a88001eb03c2b9cb96e4127225438750bb606"
 dependencies = [
- "bitflags",
+ "bitflags 1.3.2",
  "interception-sys",
  "num_enum",
  "serde",
@@ -425,11 +775,12 @@ dependencies = [
 
 [[package]]
 name = "kanata-keyberon"
-version = "0.18.0"
+version = "0.1120.1"
 dependencies = [
  "arraydeque",
  "heapless",
  "kanata-keyberon-macros",
+ "rustc-hash",
 ]
 
 [[package]]
@@ -444,43 +795,112 @@ dependencies = [
 
 [[package]]
 name = "kanata-parser"
-version = "0.1.0"
+version = "0.1120.1"
 dependencies = [
  "anyhow",
- "evdev",
+ "bitflags 2.9.1",
+ "bytemuck",
  "kanata-keyberon",
  "log",
  "miette",
  "once_cell",
+ "ordered-float",
  "parking_lot",
- "radix_trie",
+ "patricia_tree",
  "rustc-hash",
+ "simplelog",
  "thiserror",
 ]
 
+[[package]]
+name = "kanata-sim"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "dirs",
+ "kanata",
+ "log",
+ "simplelog",
+ "time",
+]
+
+[[package]]
+name = "kanata-tcp-protocol"
+version = "0.1120.1"
+dependencies = [
+ "serde",
+ "serde_derive",
+ "serde_json",
+]
+
+[[package]]
+name = "kanata-wasm"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "console_error_panic_hook",
+ "kanata",
+ "log",
+ "rustc-hash",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "kanata_example_tcp_client"
+version = "1.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "kanata-tcp-protocol",
+ "log",
+ "serde_json",
+ "simplelog",
+]
+
+[[package]]
+name = "karabiner-driverkit"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97e4fc764f78a4a5cbf705c9502a51a0ba4931dbee25f4fbc59654059f6ca9e9"
+dependencies = [
+ "cc",
+ "os_info",
+]
+
 [[package]]
 name = "lazy_static"
-version = "1.4.0"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
 name = "libc"
-version = "0.2.144"
+version = "0.2.161"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b00cc1c228a6782d0f076e7b232802e0c5689d41bb5df366f2a6b6621cfdfe1"
+checksum = "8e9489c2807c139ffd9c1794f4af0ebe86a828db53ecdc7fea2111d0fed085d1"
+
+[[package]]
+name = "libredox"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0ff37bd590ca25063e35af745c343cb7a0271906fb7b37e4813e8f79f00268d"
+dependencies = [
+ "bitflags 2.9.1",
+ "libc",
+]
 
 [[package]]
 name = "linux-raw-sys"
-version = "0.3.8"
+version = "0.4.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef53942eb7bf7ff43a617b3e2c1c4a5ecf5944a7c1bc12d7ee39bbb15e5c1519"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
 
 [[package]]
 name = "lock_api"
-version = "0.4.9"
+version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "435011366fe56583b16cf956f9df0095b405b82d76425bc8981c0e22e60ec4df"
+checksum = "07af8b9cdd281b7915f413fa73f29ebd5d55d0d3f0155584dade1ff18cea1b17"
 dependencies = [
  "autocfg",
  "scopeguard",
@@ -488,27 +908,24 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.17"
+version = "0.4.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abb12e687cfb44aa40f41fc3978ef76448f9b6038cad6aef4259d3c095a2382e"
-dependencies = [
- "cfg-if",
-]
+checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24"
 
 [[package]]
-name = "memchr"
-version = "2.5.0"
+name = "malloc_buf"
+version = "0.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d"
+checksum = "62bb907fe88d54d8d9ce32a3cceab4218ed2f6b7d35617cafe9adf84e43919cb"
+dependencies = [
+ "libc",
+]
 
 [[package]]
-name = "memoffset"
-version = "0.6.5"
+name = "memchr"
+version = "2.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce"
-dependencies = [
- "autocfg",
-]
+checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
 
 [[package]]
 name = "memoffset"
@@ -521,9 +938,9 @@ dependencies = [
 
 [[package]]
 name = "miette"
-version = "5.9.0"
+version = "5.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a236ff270093b0b67451bc50a509bd1bad302cb1d3c7d37d5efe931238581fa9"
+checksum = "59bb584eaeeab6bd0226ccf3509a69d7936d148cf3d036ad350abe35e8c6856e"
 dependencies = [
  "backtrace",
  "backtrace-ext",
@@ -542,9 +959,9 @@ dependencies = [
 
 [[package]]
 name = "miette-derive"
-version = "5.9.0"
+version = "5.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4901771e1d44ddb37964565c654a3223ba41a594d02b8da471cc4464912b5cfa"
+checksum = "49e7bc1560b95a3c4a25d03de42fe76ca718ab92d1a22a55b9b4cf67b3ae635c"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -553,33 +970,47 @@ dependencies = [
 
 [[package]]
 name = "miniz_oxide"
-version = "0.6.2"
+version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b275950c28b37e794e8c55d88aeb5e139d0ce23fdbbeda68f8d7174abdf9e8fa"
+checksum = "e2d80299ef12ff69b16a84bb182e3b9df68b5a91574d3d4fa6e41b65deec4df1"
 dependencies = [
- "adler",
+ "adler2",
+ "simd-adler32",
 ]
 
 [[package]]
 name = "mio"
-version = "0.8.6"
+version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b9d9a46eff5b4ff64b45a9e316a6d1e0bc719ef429cbec4dc630684212bfdf9"
+checksum = "a4a650543ca06a924e8b371db273b2756685faae30f8487da1b56505a8f78b0c"
 dependencies = [
  "libc",
  "log",
  "wasi",
- "windows-sys 0.45.0",
+ "windows-sys 0.48.0",
 ]
 
+[[package]]
+name = "muldiv"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0419348c027fa7be448d2ae7ea0e4e04c2334c31dc4e74ab29f00a2a7ca69204"
+
+[[package]]
+name = "muldiv"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "956787520e75e9bd233246045d19f42fb73242759cc57fba9611d940ae96d4b0"
+
 [[package]]
 name = "native-windows-gui"
 version = "1.0.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4f7003a669f68deb6b7c57d74fff4f8e533c44a3f0b297492440ef4ff5a28454"
 dependencies = [
- "bitflags",
+ "bitflags 1.3.2",
  "lazy_static",
+ "muldiv 0.2.1",
  "winapi",
  "winapi-build",
 ]
@@ -595,29 +1026,42 @@ dependencies = [
 
 [[package]]
 name = "nix"
-version = "0.23.2"
+version = "0.26.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f3790c00a0150112de0f4cd161e3d7fc4b2d8a5542ffc35f099a2562aecb35c"
+checksum = "598beaf3cc6fdd9a5dfb1630c2800c7acd31df7aaf0f565796fba2b53ca1af1b"
 dependencies = [
- "bitflags",
- "cc",
+ "bitflags 1.3.2",
  "cfg-if",
  "libc",
- "memoffset 0.6.5",
+ "memoffset",
+ "pin-utils",
 ]
 
 [[package]]
 name = "nix"
-version = "0.26.2"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfdda3d196821d6af13126e40375cdf7da646a96114af134d5f417a9a1dc8e1a"
+checksum = "71e2746dc3a24dd78b3cfcb7be93368c6de9963d30f43a6a73998a9cf4b17b46"
 dependencies = [
- "bitflags",
+ "bitflags 2.9.1",
  "cfg-if",
+ "cfg_aliases",
  "libc",
- "memoffset 0.7.1",
- "pin-utils",
- "static_assertions",
+]
+
+[[package]]
+name = "num-conv"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf97ec579c3c42f953ef76dbf8d55ac91fb219dde70e49aa4a6b7d74e9919050"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
 ]
 
 [[package]]
@@ -643,27 +1087,146 @@ dependencies = [
 
 [[package]]
 name = "num_threads"
-version = "0.1.6"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c7398b9c8b70908f6371f47ed36737907c87c52af34c268fed0bf0ceb92ead9"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "objc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "915b1b472bc21c53464d6c8461c9d3af805ba1ef837e1cac254428f4a77177b1"
+dependencies = [
+ "malloc_buf",
+]
+
+[[package]]
+name = "objc-sys"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdb91bdd390c7ce1a8607f35f3ca7151b65afc0ff5ff3b34fa350f7d7c7e4310"
+
+[[package]]
+name = "objc2"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46a785d4eeff09c14c487497c162e92766fbb3e4059a71840cecc03d9a50b804"
+dependencies = [
+ "objc-sys",
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2819ce041d2ee131036f4fc9d6ae7ae125a3a40e97ba64d04fe799ad9dabbb44"
+checksum = "e4e89ad9e3d7d297152b17d39ed92cd50ca8063a89a9fa569046d41568891eff"
 dependencies = [
+ "bitflags 2.9.1",
+ "block2",
  "libc",
+ "objc2",
+ "objc2-core-data",
+ "objc2-core-image",
+ "objc2-foundation",
+ "objc2-quartz-core",
+]
+
+[[package]]
+name = "objc2-core-data"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "617fbf49e071c178c0b24c080767db52958f716d9eabdf0890523aeae54773ef"
+dependencies = [
+ "bitflags 2.9.1",
+ "block2",
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-image"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55260963a527c99f1819c4f8e3b47fe04f9650694ef348ffd2227e8196d34c80"
+dependencies = [
+ "block2",
+ "objc2",
+ "objc2-foundation",
+ "objc2-metal",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8"
+dependencies = [
+ "bitflags 2.9.1",
+ "block2",
+ "libc",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-metal"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd0cba1276f6023976a406a14ffa85e1fdd19df6b0f737b063b95f6c8c7aadd6"
+dependencies = [
+ "bitflags 2.9.1",
+ "block2",
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-quartz-core"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e42bee7bff906b14b167da2bac5efe6b6a07e6f7c0a21a7308d40c960242dc7a"
+dependencies = [
+ "bitflags 2.9.1",
+ "block2",
+ "objc2",
+ "objc2-foundation",
+ "objc2-metal",
 ]
 
 [[package]]
 name = "object"
-version = "0.30.3"
+version = "0.36.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea86265d3d3dcb6a27fc51bd29a4bf387fae9d2986b823079d4986af253eb439"
+checksum = "aedf0a2d09c573ed1d8d85b30c119153926a2b36dce0ab28322c09a117a4683e"
 dependencies = [
  "memchr",
 ]
 
 [[package]]
 name = "once_cell"
-version = "1.17.1"
+version = "1.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7e5500299e16ebb147ae15a00a942af264cf3688f47923b8fc2cd5858f23ad3"
+checksum = "1261fe7e33c73b354eab43b1273a57c8f967d0391e80353e51f764ac02cf6775"
+
+[[package]]
+name = "open"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61a877bf6abd716642a53ef1b89fb498923a4afca5c754f9050b4d081c05c4b3"
+dependencies = [
+ "is-wsl",
+ "libc",
+ "pathdiff",
+]
 
 [[package]]
 name = "option-ext"
@@ -671,6 +1234,36 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "5.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f4779c6901a562440c3786d08192c6fbda7c1c2060edd10006b05ee35d10f2d"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "os_info"
+version = "3.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae99c7fa6dd38c7cafe1ec085e804f8f555a2f8659b0dbe03f1f9963a9b51092"
+dependencies = [
+ "log",
+ "serde",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "os_pipe"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ffd2b0a5634335b135d5728d84c5e0fd726954b87111f7506a61c502280d982"
+dependencies = [
+ "libc",
+ "windows-sys 0.59.0",
+]
+
 [[package]]
 name = "owo-colors"
 version = "3.5.0"
@@ -679,25 +1272,40 @@ checksum = "c1b04fb49957986fdce4d6ee7a65027d55d4b6d2265e5848bbb507b58ccfdb6f"
 
 [[package]]
 name = "parking_lot"
-version = "0.12.1"
+version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3742b2c103b9f06bc9fff0a37ff4912935851bee6d36f3c02bcc755bcfec228f"
+checksum = "f1bf18183cf54e8d6059647fc3063646a1801cf30896933ec2311622cc4b9a27"
 dependencies = [
  "lock_api",
  "parking_lot_core",
 ]
 
 [[package]]
-name = "parking_lot_core"
-version = "0.9.7"
+name = "parking_lot_core"
+version = "0.9.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e401f977ab385c9e4e3ab30627d6f26d00e2c73eef317493c4ec6d468726cf8"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "pathdiff"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d61c5ce1153ab5b689d0c074c4e7fc613e942dfb7dd9eea5ab202d2ad91fe361"
+
+[[package]]
+name = "patricia_tree"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9069cbb9f99e3a5083476ccb29ceb1de18b9118cafa53e90c9551235de2b9521"
+checksum = "edb45b6331bbdbb54c9a29413703e892ab94f83a31e4a546c778495a91e7fbca"
 dependencies = [
- "cfg-if",
- "libc",
- "redox_syscall",
- "smallvec",
- "windows-sys 0.45.0",
+ "bitflags 2.9.1",
 ]
 
 [[package]]
@@ -706,6 +1314,25 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
 
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "powerfmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
+
 [[package]]
 name = "proc-macro-crate"
 version = "1.3.1"
@@ -713,23 +1340,23 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f4c021e1093a56626774e81216a4ce732a735e5bad4868a03f3ed65ca0c3919"
 dependencies = [
  "once_cell",
- "toml_edit",
+ "toml_edit 0.19.15",
 ]
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.58"
+version = "1.0.89"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fa1fb82fc0c281dd9671101b66b771ebbe1eaf967b96ac8740dcba4b70005ca8"
+checksum = "f139b0662de085916d1fb67d2b4169d1addddda1919e696f3252b740b629986e"
 dependencies = [
  "unicode-ident",
 ]
 
 [[package]]
 name = "quote"
-version = "1.0.27"
+version = "1.0.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f4f29d145265ec1c483c7c654450edde0bfe043d3938d6972630663356d9500"
+checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af"
 dependencies = [
  "proc-macro2",
 ]
@@ -752,29 +1379,41 @@ dependencies = [
 
 [[package]]
 name = "redox_syscall"
-version = "0.2.16"
+version = "0.5.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fb5a58c1855b4b6819d59012155603f0b22ad30cad752600aadfcb695265519a"
+checksum = "9b6dfecf2c74bce2466cabf93f6664d6998a69eb21e39f4207930065b27b771f"
 dependencies = [
- "bitflags",
+ "bitflags 2.9.1",
 ]
 
 [[package]]
 name = "redox_users"
-version = "0.4.3"
+version = "0.4.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b033d837a7cf162d7993aded9304e30a83213c648b6e389db233191f891e5c2b"
+checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
 dependencies = [
  "getrandom",
- "redox_syscall",
+ "libredox",
  "thiserror",
 ]
 
 [[package]]
 name = "regex"
-version = "1.8.2"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d1a59b5d8e97dee33696bf13c5ba8ab85341c002922fba050069326b9c498974"
+checksum = "368758f23274712b504848e9d5a6f010445cc8b87a7cdb4d7cbee666c1288da3"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -783,15 +1422,15 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.7.2"
+version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "436b050e76ed2903236f032a59761c1eb99e1b0aead2c257922771dab1fc8c78"
+checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
 
 [[package]]
 name = "rustc-demangle"
-version = "0.1.23"
+version = "0.1.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d626bb9dae77e28219937af045c257c28bfd3f69333c512553507f5f9798cb76"
+checksum = "719b953e2095829ee67db738b3bfa9fa368c94900df327b3f07fe6e794d2fe1f"
 
 [[package]]
 name = "rustc-hash"
@@ -801,65 +1440,80 @@ checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
 
 [[package]]
 name = "rustc_version"
-version = "0.4.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfa0f585226d2e68097d4f95d113b15b83a82e819ab25717ec0590d9584ef366"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
 dependencies = [
  "semver",
 ]
 
 [[package]]
 name = "rustix"
-version = "0.37.19"
+version = "0.38.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "acf8729d8542766f1b2cf77eb034d52f40d375bb8b615d0b147089946e16613d"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
 dependencies = [
- "bitflags",
+ "bitflags 2.9.1",
  "errno",
- "io-lifetimes",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.48.0",
+ "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
 [[package]]
 name = "ryu"
-version = "1.0.13"
+version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f91339c0467de62360649f8d3e185ca8de4224ff281f66000de5eb2a77a79041"
+checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f"
 
 [[package]]
 name = "scopeguard"
-version = "1.1.0"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d29ab0c6d3fc0ee92fe66e2d99f700eab17a8d57d1c1d3b748380fb20baa78cd"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sd-notify"
-version = "0.4.1"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "621e3680f3e07db4c9c2c3fb07c6223ab2fab2e54bd3c04c3ae037990f428c32"
+checksum = "1be20c5f7f393ee700f8b2f28ea35812e4e212f40774b550cd2a93ea91684451"
 
 [[package]]
 name = "semver"
-version = "1.0.17"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bebd363326d05ec3e2f532ab7660680f3b02130d780c299bca73469d521bc0ed"
+checksum = "61697e0a1c7e512e84a621326239844a24d8207b4669b41bc18b32ea5cbf988b"
 
 [[package]]
 name = "serde"
-version = "1.0.163"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2113ab51b87a539ae008b5c6c02dc020ffa39afd2d83cffcb3f4eb2722cebec2"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.163"
+version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8c805777e3930c8883389c602315a24224bcc738b63905ef87cd1420353ea93e"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -868,20 +1522,36 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.96"
+version = "1.0.132"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "057d394a50403bcac12672b2b18fb387ab6d289d957dab67dd201875391e52f1"
+checksum = "d726bfaff4b320266d395898905d0eba0345aae23b54aee3a737e260fd46db03"
 dependencies = [
  "itoa",
+ "memchr",
  "ryu",
  "serde",
 ]
 
+[[package]]
+name = "serde_spanned"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87607cb1398ed59d48732e575a4c28a7a8ebf2454b964fe3f224f2afc07909e1"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
 [[package]]
 name = "signal-hook"
-version = "0.3.15"
+version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "732768f1176d21d09e076c23a93123d40bba92d50c4058da34d45c8de8e682b9"
+checksum = "8621587d4798caf8eb44879d42e56b9a93ea5dcd315a6487c357130095b62801"
 dependencies = [
  "libc",
  "signal-hook-registry",
@@ -889,35 +1559,59 @@ dependencies = [
 
 [[package]]
 name = "signal-hook-registry"
-version = "1.4.1"
+version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d8229b473baa5980ac72ef434c4415e70c4b5e71b423043adb4ba059f89c99a1"
+checksum = "a9e9e0b4211b72e7b8b6e85c807d36c212bdb33ea8587f7569562a84df5465b1"
 dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d66dc143e6b11c1eddc06d5c423cfc97062865baf299914ab64caa38182078fe"
+
 [[package]]
 name = "simplelog"
-version = "0.12.1"
+version = "0.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "acee08041c5de3d5048c8b3f6f13fafb3026b24ba43c6a695a0c76179b844369"
+checksum = "16257adbfaef1ee58b1363bdc0664c9b8e1e30aed86049635fb5f147d065a9c0"
 dependencies = [
  "log",
  "termcolor",
  "time",
 ]
 
+[[package]]
+name = "simulated_passthru"
+version = "0.0.1"
+dependencies = [
+ "anyhow",
+ "encode_unicode",
+ "kanata",
+ "kanata-interception",
+ "lazy_static",
+ "log",
+ "native-windows-gui",
+ "parking_lot",
+ "regex",
+ "widestring",
+ "win_dbg_logger",
+ "winapi",
+]
+
 [[package]]
 name = "smallvec"
-version = "1.10.0"
+version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a507befe795404456341dfab10cef66ead4c041f62b8b11bbb92bffe5d0953e0"
+checksum = "3c5e1a9a646d36c3599cd173a41282daf47c44583ad367b8e6837255952e5c67"
 
 [[package]]
 name = "smawk"
-version = "0.3.1"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f67ad224767faa3c7d8b6d91985b78e70a1324408abcb1cfcc2be4c06bc06043"
+checksum = "b7c388c1b5e93756d0c740965c41e8822f866621d41acbdf6336a6a168f8840c"
 
 [[package]]
 name = "spin"
@@ -935,22 +1629,25 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a8f112729512f8e442d81f95a8a7ddf2b7c6b8a1a6f509a95864142b30cab2d3"
 
 [[package]]
-name = "static_assertions"
-version = "1.1.0"
+name = "strip-ansi-escapes"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+checksum = "55ff8ef943b384c414f54aefa961dd2bd853add74ec75e7ac74cf91dba62bcfa"
+dependencies = [
+ "vte",
+]
 
 [[package]]
 name = "strsim"
-version = "0.10.0"
+version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "supports-color"
-version = "2.0.0"
+version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4950e7174bffabe99455511c39707310e7e9b440364a2fcb1cc21521be57b354"
+checksum = "d6398cde53adc3c4557306a96ce67b302968513830a77a95b2b17305d9719a89"
 dependencies = [
  "is-terminal",
  "is_ci",
@@ -967,18 +1664,18 @@ dependencies = [
 
 [[package]]
 name = "supports-unicode"
-version = "2.0.0"
+version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b6c2cb240ab5dd21ed4906895ee23fe5a48acdbd15a3ce388e7b62a9b66baf7"
+checksum = "f850c19edd184a205e883199a261ed44471c81e39bd95b1357f5febbef00e77a"
 dependencies = [
  "is-terminal",
 ]
 
 [[package]]
 name = "syn"
-version = "2.0.16"
+version = "2.0.85"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6f671d4b5ffdb8eadec19c0ae67fe2639df8684bd7bc4b83d986b8db549cf01"
+checksum = "5023162dfcd14ef8f32034d8bcd4cc5ddc61ef7a247c024a33e24e1f24d21b56"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -993,9 +1690,9 @@ checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
 
 [[package]]
 name = "termcolor"
-version = "1.1.3"
+version = "1.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bab24d30b911b2376f3a13cc2cd443142f0c81dda04c118693e35b3835757755"
+checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755"
 dependencies = [
  "winapi-util",
 ]
@@ -1023,97 +1720,176 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "1.0.40"
+version = "1.0.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "978c9a314bd8dc99be594bc3c175faaa9794be04a5a5e153caba6915336cebac"
+checksum = "5d11abd9594d9b38965ef50805c5e469ca9cc6f197f883f717e0269a3057b3d5"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "1.0.40"
+version = "1.0.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f9456a42c5b0d803c8cd86e73dd7cc9edd429499f37a3550d286d5e86720569f"
+checksum = "ae71770322cbd277e69d762a16c444af02aa0575ac0d174f0b9562d3b37f8602"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba1310fcea54c6a9a4fd1aad794ecc02c31682f6bfbecdf460bf19533eed1e3e"
+dependencies = [
+ "flate2",
+ "jpeg-decoder",
+ "weezl",
+]
+
 [[package]]
 name = "time"
-version = "0.3.21"
+version = "0.3.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f3403384eaacbca9923fa06940178ac13e4edb725486d70e8e15881d0c836cc"
+checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"
 dependencies = [
+ "deranged",
  "itoa",
  "libc",
+ "num-conv",
  "num_threads",
- "serde",
+ "powerfmt",
+ "serde_core",
  "time-core",
  "time-macros",
 ]
 
 [[package]]
 name = "time-core"
-version = "0.1.1"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7300fbefb4dadc1af235a9cef3737cea692a9d97e1b9cbcd4ebdae6f8868e6fb"
+checksum = "7694e1cfe791f8d31026952abf09c69ca6f6fa4e1a1229e18988f06a04a12dca"
 
 [[package]]
 name = "time-macros"
-version = "0.2.9"
+version = "0.2.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "372950940a5f07bf38dbe211d7283c9e6d7327df53794992d293e534c733d09b"
+checksum = "2e70e4c5a0e0a8a4823ad65dfe1a6930e4f4d756dcd9dd7939022b5e8c501215"
 dependencies = [
+ "num-conv",
  "time-core",
 ]
 
+[[package]]
+name = "toml"
+version = "0.8.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1ed1f98e3fdc28d6d910e6737ae6ab1a93bf1985935a1193e68f93eeb68d24e"
+dependencies = [
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_edit 0.22.22",
+]
+
 [[package]]
 name = "toml_datetime"
-version = "0.6.2"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0dd7358ecb8fc2f8d014bf86f6f638ce72ba252a2c3a2572f2a795f1d23efb41"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.19.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a76a9312f5ba4c2dec6b9161fdf25d87ad8a09256ccea5a556fef03c706a10f"
+checksum = "1b5bb770da30e5cbfde35a2d7b9b8a2c4b8ef89548a7a6aeab5c9a576e3e7421"
+dependencies = [
+ "indexmap",
+ "toml_datetime",
+ "winnow 0.5.40",
+]
 
 [[package]]
 name = "toml_edit"
-version = "0.19.9"
+version = "0.22.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "92d964908cec0d030b812013af25a0e57fddfadb1e066ecc6681d86253129d4f"
+checksum = "4ae48d6208a266e853d946088ed816055e556cc6028c5e8e2b84d9fa5dd7c7f5"
 dependencies = [
  "indexmap",
+ "serde",
+ "serde_spanned",
  "toml_datetime",
- "winnow",
+ "winnow 0.6.20",
 ]
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.8"
+version = "1.0.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e5464a87b239f13a63a501f2701565754bae92d243d4bb7eb12f6d57d2269bf4"
+checksum = "e91b56cd4cadaeb79bbf1a5645f6b4f8dc5bde8834ad5894a8db35fda9efa1fe"
 
 [[package]]
 name = "unicode-linebreak"
-version = "0.1.4"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f"
+
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "vswhom"
+version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c5faade31a542b8b35855fff6e8def199853b2da8da256da52f52f1316ee3137"
+checksum = "be979b7f07507105799e854203b470ff7c78a1639e330a58f183b5fea574608b"
 dependencies = [
- "hashbrown",
- "regex",
+ "libc",
+ "vswhom-sys",
 ]
 
 [[package]]
-name = "unicode-width"
-version = "0.1.10"
+name = "vswhom-sys"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3b17ae1f6c8a2b28506cd96d412eebf83b4a0ff2cbefeeb952f2f9dfa44ba18"
+dependencies = [
+ "cc",
+ "libc",
+]
+
+[[package]]
+name = "vte"
+version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c0edd1e5b14653f783770bce4a4dabb4a5108a5370a5f5d8cfe8710c361f6c8b"
+checksum = "f5022b5fbf9407086c180e9557be968742d839e68346af7792b8592489732197"
+dependencies = [
+ "utf8parse",
+ "vte_generate_state_changes",
+]
 
 [[package]]
-name = "version_check"
-version = "0.9.4"
+name = "vte_generate_state_changes"
+version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49874b5167b65d7193b8aba1567f5c7d93d001cafc34600cee003eda787e483f"
+checksum = "2e369bee1b05d510a7b4ed645f5faa90619e05437111783ea5848f28d97d3c2e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
 
 [[package]]
 name = "wasi"
@@ -1121,6 +1897,95 @@ version = "0.11.0+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
 
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1edc8929d7499fc4e8f0be2262a241556cfc54a0bea223790e71446f2aab1ef5"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+]
+
+[[package]]
+name = "wasm-bindgen-backend"
+version = "0.2.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f0a0651a5c2bc21487bde11ee802ccaf4c51935d0d3d42a6101f98161700bc6"
+dependencies = [
+ "bumpalo",
+ "log",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7fe63fc6d09ed3792bd0897b314f53de8e16568c2b3f7982f468c0bf9bd0b407"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ae87ea40c9f689fc23f209965b6fb8a99ad69aeeb0231408be24920604395de"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-backend",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a05d73b933a847d6cccdda8f838a22ff101ad9bf93e33684f39c1f5f0eece3d"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "weezl"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53a85b86a771b1c87058196170769dd264f66c0782acf1ae6cc51bfd64b39082"
+
+[[package]]
+name = "widestring"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7219d36b6eac893fa81e84ebe06485e7dcbb616177469b142df14f1f4deb1311"
+
+[[package]]
+name = "win_dbg_logger"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d1b4c22244dc27534d81e2f6fc3efd6b20e50c010f177efc20b719ec759a779"
+dependencies = [
+ "log",
+]
+
 [[package]]
 name = "winapi"
 version = "0.3.9"
@@ -1145,11 +2010,11 @@ checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
 
 [[package]]
 name = "winapi-util"
-version = "0.1.5"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70ec6ce85bb158151cae5e5c87f95a8e97d2c0c4b001223f33a334e3ce5de178"
+checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb"
 dependencies = [
- "winapi",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -1160,145 +2025,194 @@ checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
 [[package]]
 name = "windows-sys"
-version = "0.45.0"
+version = "0.48.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
 dependencies = [
- "windows-targets 0.42.2",
+ "windows-targets 0.48.5",
 ]
 
 [[package]]
 name = "windows-sys"
-version = "0.48.0"
+version = "0.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
 dependencies = [
- "windows-targets 0.48.0",
+ "windows-targets 0.52.6",
 ]
 
 [[package]]
 name = "windows-targets"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071"
+checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c"
 dependencies = [
- "windows_aarch64_gnullvm 0.42.2",
- "windows_aarch64_msvc 0.42.2",
- "windows_i686_gnu 0.42.2",
- "windows_i686_msvc 0.42.2",
- "windows_x86_64_gnu 0.42.2",
- "windows_x86_64_gnullvm 0.42.2",
- "windows_x86_64_msvc 0.42.2",
+ "windows_aarch64_gnullvm 0.48.5",
+ "windows_aarch64_msvc 0.48.5",
+ "windows_i686_gnu 0.48.5",
+ "windows_i686_msvc 0.48.5",
+ "windows_x86_64_gnu 0.48.5",
+ "windows_x86_64_gnullvm 0.48.5",
+ "windows_x86_64_msvc 0.48.5",
 ]
 
 [[package]]
 name = "windows-targets"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b1eb6f0cd7c80c79759c929114ef071b87354ce476d9d94271031c0497adfd5"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
 dependencies = [
- "windows_aarch64_gnullvm 0.48.0",
- "windows_aarch64_msvc 0.48.0",
- "windows_i686_gnu 0.48.0",
- "windows_i686_msvc 0.48.0",
- "windows_x86_64_gnu 0.48.0",
- "windows_x86_64_gnullvm 0.48.0",
- "windows_x86_64_msvc 0.48.0",
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
 ]
 
 [[package]]
 name = "windows_aarch64_gnullvm"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8"
+checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8"
 
 [[package]]
 name = "windows_aarch64_gnullvm"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91ae572e1b79dba883e0d315474df7305d12f569b400fcf90581b06062f7e1bc"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 
 [[package]]
 name = "windows_aarch64_msvc"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43"
+checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc"
 
 [[package]]
 name = "windows_aarch64_msvc"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b2ef27e0d7bdfcfc7b868b317c1d32c641a6fe4629c171b8928c7b08d98d7cf3"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 
 [[package]]
 name = "windows_i686_gnu"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f"
+checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e"
 
 [[package]]
 name = "windows_i686_gnu"
-version = "0.48.0"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "622a1962a7db830d6fd0a69683c80a18fda201879f0f447f065a3b7467daa241"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 
 [[package]]
 name = "windows_i686_msvc"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060"
+checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406"
 
 [[package]]
 name = "windows_i686_msvc"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4542c6e364ce21bf45d69fdd2a8e455fa38d316158cfd43b3ac1c5b1b19f8e00"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_key_tester"
+version = "0.3.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "kanata",
+ "kanata-interception",
+ "log",
+ "native-windows-gui",
+ "simplelog",
+ "winapi",
+]
 
 [[package]]
 name = "windows_x86_64_gnu"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36"
+checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e"
 
 [[package]]
 name = "windows_x86_64_gnu"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca2b8a661f7628cbd23440e50b05d705db3686f894fc9580820623656af974b1"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 
 [[package]]
 name = "windows_x86_64_gnullvm"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3"
+checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc"
 
 [[package]]
 name = "windows_x86_64_gnullvm"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7896dbc1f41e08872e9d5e8f8baa8fdd2677f29468c4e156210174edc7f7b953"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 
 [[package]]
 name = "windows_x86_64_msvc"
-version = "0.42.2"
+version = "0.48.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0"
+checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538"
 
 [[package]]
 name = "windows_x86_64_msvc"
-version = "0.48.0"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a515f5799fe4961cb532f983ce2b23082366b898e52ffbce459c86f67c8378a"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
 [[package]]
 name = "winnow"
-version = "0.4.6"
+version = "0.5.40"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f593a95398737aeed53e489c785df13f3618e41dbcd6718c6addbf1395aa6876"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "winnow"
+version = "0.6.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61de7bac303dc551fe038e2b3cef0f571087a47571ea6e79a87692ac99b99699"
+checksum = "36c1fec1a2bb5866f07c25f68c26e565c4c200aebb96d7e55710c19d3e8ac49b"
 dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "winreg"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a277a57398d4bfa075df44f501a17cfdf8542d224f0d36095a2adc7aee4ef0a5"
+dependencies = [
+ "cfg-if",
+ "windows-sys 0.48.0",
+]
+
 [[package]]
 name = "wyz"
 version = "0.5.1"
@@ -1307,3 +2221,20 @@ checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
 dependencies = [
  "tap",
 ]
+
+[[package]]
+name = "x11rb"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d91ffca73ee7f68ce055750bf9f6eca0780b8c85eff9bc046a3b0da41755e12"
+dependencies = [
+ "gethostname",
+ "rustix",
+ "x11rb-protocol",
+]
+
+[[package]]
+name = "x11rb-protocol"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec107c4503ea0b4a98ef47356329af139c0a4f7750e621cf2973cd3385ebcb3d"
diff --git a/Cargo.toml b/Cargo.toml
index e7cada242..cc2e1e632 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,44 +1,83 @@
+[workspace]
+members = [
+	"./",
+	"parser",
+	"keyberon",
+	"example_tcp_client",
+	"tcp_protocol",
+	"windows_key_tester",
+	"simulated_input",
+	"simulated_passthru",
+	"wasm",
+]
+exclude = [
+	"interception",
+	"key-sort-add",
+]
+resolver = "2"
+
 [package]
 name = "kanata"
-version = "1.4.0-prerelease-2"
+version = "1.12.0-prerelease-2"
 authors = ["jtroo <j.andreitabs@gmail.com>"]
 description = "Multi-layer keyboard customization"
-keywords = ["cli", "linux", "windows", "keyboard", "layout"]
+keywords = ["keyboard", "layout", "remapping"]
 categories = ["command-line-utilities"]
 homepage = "https://github.com/jtroo/kanata"
 repository = "https://github.com/jtroo/kanata"
 readme = "README.md"
-license = "LGPL-3.0"
-edition = "2021"
+license = "LGPL-3.0-only"
+edition = "2024"
+default-run = "kanata"
+
+[lib]
+name = "kanata_state_machine"
+path = "src/lib.rs"
+crate-type = ["rlib", "staticlib"]
+
+[[bin]]
+name = "kanata"
+path = "src/main.rs"
 
 [dependencies]
-clap = { version = "4.1.6", features = [ "std", "derive", "help", "suggestions" ], default_features = false }
-log = { version = "0.4.8", default_features = false }
-simplelog = "0.12.0"
 anyhow = "1"
-parking_lot = "0.12"
+clap = { version = "4", features = [ "std", "derive", "help", "suggestions" ], default-features = false }
+dirs = "5.0.1"
+indoc = { version = "2.0.4", optional = true }
+log = { version = "0.4.8", default-features = false }
+miette = { version = "5.7.0", features = ["fancy"] }
 once_cell = "1"
-serde = { version = "1", features = ["alloc", "derive"], default_features = false }
-serde_json = { version = "1", features = ["alloc"], default_features = false }
+parking_lot = "0.12"
 radix_trie = "0.2"
 rustc-hash = "1.1.0"
-miette = { version = "5.7.0", features = ["fancy"] }
-dirs = "5.0.1"
+simplelog = "0.12.0"
+serde_json = { version = "1", features = ["std"], default-features = false, optional = true }
+time = "0.3.47"
+web-time = "1.1.0"
 
-# kanata-keyberon = "0.17.0"
-# Uncomment below and comment out above for testing local keyberon changes.
-# Otherwise any changes to the local files will not reflect in the compiled
-# binary.
-kanata-keyberon = { path = "keyberon" }
+kanata-keyberon = { path = "keyberon", version = "0.1120.1" }
+kanata-parser =   { path = "parser", version = "0.1120.1" }
+kanata-tcp-protocol = { path = "tcp_protocol", version = "0.1120.1" }
 
-kanata-parser = { path = "parser" }
+[target.'cfg(not(any(target_arch = "wasm32", target_os = "android")))'.dependencies]
+arboard = "3.4"
 
-[target.'cfg(target_os = "linux")'.dependencies]
-evdev = "=0.12.0"
-signal-hook = "0.3.14"
-inotify = { version = "0.10.0", default_features = false }
-mio = { version = "0.8.4", features = ["os-poll", "os-ext"] }
+[target.'cfg(target_os = "macos")'.dependencies]
+karabiner-driverkit = "0.3.0"
+objc = "0.2.7"
+core-graphics = "0.24.0"
+open = { version = "5", optional = true }
+libc = "0.2"
+os_pipe = "1.2.1"
+core-foundation = "0.10.1"
+
+[target.'cfg(any(target_os = "linux", target_os = "android"))'.dependencies]
+evdev = "0.13.0"
+inotify = { version = "0.10.0", default-features = false }
+mio = { version = "0.8.11", features = ["os-poll", "os-ext"] }
 nix = { version = "0.26.1", features = ["ioctl"] }
+open = { version = "5", optional = true }
+signal-hook = "0.3.14"
 sd-notify = "0.4.1"
 
 [target.'cfg(target_os = "windows")'.dependencies]
@@ -47,14 +86,64 @@ winapi = { version = "0.3.9", features = [
     "wincon",
     "timeapi",
     "mmsystem",
+    "winuser",
+    "windef",
+    "minwindef",
 ] }
-native-windows-gui = { version = "1.0.12", default_features = false }
-kanata-interception = { version = "0.2.0", optional = true }
+windows-sys = { version = "0.52.0", features = [
+    "Win32_Devices_DeviceAndDriverInstallation",
+    "Win32_Devices_Usb",
+    "Win32_Foundation",
+    "Win32_Graphics_Gdi",
+    "Win32_Security",
+    "Win32_System_Diagnostics_Debug",
+    "Win32_System_Registry",
+    "Win32_System_Threading",
+    "Win32_UI_Controls",
+    "Win32_UI_Shell",
+    "Win32_UI_HiDpi",
+    "Win32_UI_WindowsAndMessaging",
+    "Win32_System_SystemInformation",
+    "Wdk",
+    "Wdk_System",
+    "Wdk_System_SystemServices",
+], optional=true }
+native-windows-gui = { version = "1.0.13", default-features = false}
+regex = { version = "1.10.4", optional = true }
+kanata-interception = { version = "0.3.0", optional = true }
+muldiv = { version = "1.0.1", optional = true }
+strip-ansi-escapes = { version = "0.2.0", optional = true }
+open = { version = "5", features = ["shellexecute-on-windows"], optional = true}
+# shellexecute fix allows opening files already opened for writing, needs _detached mode
+
+[build-dependencies]
+embed-resource = { version = "2.4.2", optional = true }
+indoc = { version = "2.0.4", optional = true }
+regex = { version = "1.10.4", optional = true }
 
 [features]
-cmd = []
+default = ["tcp_server","win_sendinput_send_scancodes", "zippychord"]
 perf_logging = []
-interception_driver = ["kanata-interception"]
+tcp_server = ["dep:serde_json", "kanata-keyberon/tap_hold_tracker"]
+win_sendinput_send_scancodes = ["kanata-parser/win_sendinput_send_scancodes"]
+win_llhook_read_scancodes = ["kanata-parser/win_llhook_read_scancodes"]
+winiov2 = ["win_llhook_read_scancodes","win_sendinput_send_scancodes"]
+win_manifest = ["dep:embed-resource", "dep:indoc", "dep:regex"]
+# delete cargo-clippy when the objc crate is replaced
+cargo-clippy = []
+cmd = ["kanata-parser/cmd"]
+interception_driver = ["dep:kanata-interception", "kanata-parser/interception_driver"]
+simulated_output = ["dep:indoc"]
+simulated_input = ["dep:indoc"]
+passthru_ahk = ["simulated_input","simulated_output"]
+gui = ["win_manifest","kanata-parser/gui",
+  "win_sendinput_send_scancodes","win_llhook_read_scancodes",
+  "dep:muldiv","dep:strip-ansi-escapes","dep:open",
+  "dep:windows-sys",
+  "winapi/processthreadsapi",
+  "native-windows-gui/tray-notification","native-windows-gui/message-window","native-windows-gui/menu","native-windows-gui/cursor","native-windows-gui/high-dpi","native-windows-gui/embed-resource","native-windows-gui/image-decoder","native-windows-gui/notice","native-windows-gui/animation-timer",
+]
+zippychord = ["kanata-parser/zippychord"]
 
 [profile.release]
 opt-level = "z"
diff --git a/EnableUIAccess/EnableUIAccess_launch.ahk b/EnableUIAccess/EnableUIAccess_launch.ahk
new file mode 100644
index 000000000..13e61ace4
--- /dev/null
+++ b/EnableUIAccess/EnableUIAccess_launch.ahk
@@ -0,0 +1,134 @@
+#requires AutoHotkey v2.0
+#SingleInstance Off ; Needed for elevation with *runas.
+/* v2 based on EnableUIAccess.ahk v1.01 by Lexikos USE AT YOUR OWN RISK
+  Enables the uiAccess flag in an application's embedded manifest and signs the file with a self-signed digital certificate. If the file is in a trusted location (A_ProgramFiles or A_WinDir), this allows the application to bypass UIPI (User Interface Privilege Isolation, a part of User Account Control in Vista/7). It also enables the journal playback hook (SendPlay).
+  Command line params (mutually exclusive):
+    SkipWarning     - don't display the initial warning
+    "<in>" "<out>"  - attempt to run silently using the given file(s)
+  This script and the provided Lib files may be used, modified, copied, etc. without restriction.
+*/
+#include <EnableUIAccess>
+
+in_file  := (A_Args.Has(1))?A_Args[1]:'' ; Command line args
+out_file := (A_Args.Has(2))?A_Args[2]:''
+
+if (in_file = ""){
+  msgResult := MsgBox("Enable the selected EXE to bypass UAC-UIPI security restrictions imposed by modifying 'UIAccess' attribute in the file's embedded manifest and signing the file using a self-signed digital certificate, which is then installed in the local machine's Trusted Root Certification Authorities store.`n`nThe resulting EXE is unusable on a system without this certificate installed!`n`nContinue at your own risk", "", 49)
+  if (msgResult = "Cancel"){
+    ExitApp()
+  }
+}
+
+if !A_IsAdmin {
+  if (in_file = "") {
+    in_file := "SkipWarning"
+  }
+  cmd := "`"" . A_ScriptFullPath . "`""
+  if !A_IsCompiled {   ; Use A_AhkPath in case the "runas" verb isn't registered for ahk files.
+    cmd := "`"" . A_AhkPath . "`" " . cmd
+  }
+  Try Run("*RunAs " cmd " `"" in_file "`" `"" out_file "`"", , "", )
+  ExitApp()
+}
+global user_specified_files := false
+if (in_file = "" || in_file = "SkipWarning") { ; Find AutoHotkey installation.
+  InstallDir := RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\AutoHotkey", "InstallDir")
+  if A_LastError && A_PtrSize=8 {
+    InstallDir := RegRead("HKLM\SOFTWARE\Wow6432Node\AutoHotkey", "InstallDir")
+  }
+  ; Let user confirm or select file(s).
+  in_file := FileSelect(1, InstallDir "\AutoHotkey.exe", "Select Source File", "Executable Files (*.exe)")
+  if A_LastError {
+    ExitApp()
+  }
+  out_file := FileSelect("S16", in_file, "Select Destination File", "Executable Files (*.exe)")
+  if A_LastError {
+    ExitApp()
+  }
+  user_specified_files := true
+}
+
+Loop in_file { ; Convert short paths to long paths
+  in_file := A_LoopFileFullPath
+}
+if (out_file = "") {   ; i.e. only one file was given via command line
+  out_file := in_file
+} else {
+  Loop out_file {
+    out_file := A_LoopFileFullPath
+  }
+}
+if Crypt.IsSigned(in_file) {
+  msgResult := MsgBox("Input file is already signed.  The script will now exit" in_file,"", 48)
+  ExitApp()
+}
+
+if user_specified_files && !IsTrustedLocation(out_file) {
+  msgResult := MsgBox("Target path is not a trusted location (Program Files or Windows\System32), so 'uiAccess'  will have no effect until the file is moved there","", 49)
+  if (msgResult = "Cancel") {
+    ExitApp()
+  }
+}
+
+if (in_file = out_file) { ; The following should typically work even if the file is in use
+  bak_file := in_file "~" A_Now ".bak"
+  FileMove(in_file, bak_file, 1)
+  if A_LastError {
+    Fail("Failed to rename selected file.")
+  }
+  in_file := bak_file
+}
+Try {
+  FileCopy(in_file, out_file, 1)
+} Catch as Err {
+  throw OSError(Err)
+}
+if A_LastError {
+  Fail("Failed to copy file to destination.")
+}
+
+if !EnableUIAccess(out_file) { ; Set the uiAccess attribute in the file's manifest
+  Fail("Failed to set uiAccess attribute in manifest")
+}
+
+
+if (user_specified_files && in_file != out_file) { ; in interactive mode, if not overwriting the original file, offer to create an additional context menu item for AHK files
+  uiAccessVerb := RegRead("HKCR\AutoHotkeyScript\Shell\uiAccess\Command")
+  if A_LastError {
+    msgResult := MsgBox("Register `"Run Script with UI Access`" context menu item?", "", 3)
+    if (msgResult = "Yes") {
+      RegWrite("Run with UI Access", "REG_SZ", "HKCR\AutoHotkeyScript\Shell\uiAccess")
+      RegWrite("`"" out_file "`" `"`%1`" `%*", "REG_SZ", "HKCR\AutoHotkeyScript\Shell\uiAccess\Command")
+    }
+    if (msgResult = "Cancel")
+      ExitApp()
+  }
+}
+
+IsTrustedLocation(path) { ; IsTrustedLocation  →true if path is a valid location for uiAccess="true"
+  ; http://msdn.microsoft.com/en-us/library/bb756929 "\Program Files\ and \windows\system32\ are currently 2 allowable protected locations." However, \Program Files (x86)\ also appears to be allowed
+  if InStr(path, A_ProgramFiles "\") = 1 {
+    return true
+  }
+  if InStr(path, A_WinDir "\System32\") = 1 {
+    return true
+  }
+  other := EnvGet(A_PtrSize=8 ? "ProgramFiles(x86)" : "ProgramW6432") ; On 64-bit systems, if this script is 32-bit, A_ProgramFiles is %ProgramFiles(x86)%, otherwise it is %ProgramW6432%. So check the opposite "Program Files" folder:
+  if (other != "" && InStr(path, other "\") = 1) {
+    return true
+  }
+  return   false
+}
+
+Fail(msg) {
+  ; if (%True% != "Silent") { ;???
+    MsgBox(msg "`nA_LastError: " A_LastError, "", 16)
+  ; }
+  ExitApp()
+}
+
+Warn(msg) {
+  msg .= " (Err " A_LastError ")`n"
+  OutputDebug(msg)
+  FileAppend(msg, "*")
+}
diff --git a/EnableUIAccess/Lib/EnableUIAccess.ahk b/EnableUIAccess/Lib/EnableUIAccess.ahk
new file mode 100644
index 000000000..13a180ac6
--- /dev/null
+++ b/EnableUIAccess/Lib/EnableUIAccess.ahk
@@ -0,0 +1,271 @@
+#requires AutoHotkey v2.0
+
+EnableUIAccess(ExePath) {
+  static CertName := "AutoHotkey"
+  hStore := DllCall("Crypt32\CertOpenStore", "ptr",10 ; STORE_PROV_SYSTEM_W
+    , "uint",0, "ptr",0, "uint",0x20000 ; SYSTEM_STORE_LOCAL_MACHINE
+    , "wstr","Root", "ptr")
+  if !hStore {
+    throw OSError()
+  }
+  store := CertStore(hStore)
+  cert := CertContext() ; Find or create certificate for signing.
+  while (cert.ptr := DllCall("Crypt32\CertFindCertificateInStore", "ptr",hStore
+      , "uint",0x10001 ; X509_ASN_ENCODING|PKCS_7_ASN_ENCODING
+      , "uint",0, "uint",0x80007 ; FIND_SUBJECT_STR
+      , "wstr", CertName, "ptr",cert.ptr, "ptr"))
+    && !(DllCall("Crypt32\CryptAcquireCertificatePrivateKey"
+      , "ptr",cert, "uint",5 ; CRYPT_ACQUIRE_CACHE_FLAG|CRYPT_ACQUIRE_COMPARE_KEY_FLAG
+      , "ptr",0, "ptr*", 0, "uint*", &keySpec:=0, "ptr",0)
+      && (keySpec & 2)) { ; AT_SIGNATURE ; Keep looking for a certificate with a private key.
+  }
+  if !cert.ptr {
+    cert := EnableUIAccess_CreateCert(CertName, hStore)
+  }
+  EnableUIAccess_SetManifest(ExePath)             	; Set uiAccess attribute in manifest
+  EnableUIAccess_SignFile(ExePath, cert, CertName)	; Sign the file (otherwise uiAccess attribute is ignored)
+  return true
+}
+
+EnableUIAccess_SetManifest(ExePath) {
+  xml := ComObject("Msxml2.DOMDocument")
+  xml.async := false
+  xml.setProperty("SelectionLanguage", "XPath")
+  xml.setProperty("SelectionNamespaces"
+    , "xmlns:v1='urn:schemas-microsoft-com:asm.v1' "
+    . "xmlns:v3='urn:schemas-microsoft-com:asm.v3'")
+  try {
+    if !xml.loadXML(EnableUIAccess_ReadManifest(ExePath)) {
+      throw Error("Invalid manifest")
+    }
+  } catch as e {
+    throw Error("Error loading manifest from " ExePath,, e.Message "`n  @ " e.File ":" e.Line)
+  }
+
+
+  node := xml.selectSingleNode("/v1:assembly/v3:trustInfo/v3:security"
+    .                          "/v3:requestedPrivileges/v3:requestedExecutionLevel")
+  if !node ; Not AutoHotkey?
+    throw Error("Manifest is missing required elements")
+
+  node.setAttribute("uiAccess", "true")
+  xml := RTrim(xml.xml, "`r`n")
+
+  data := Buffer(StrPut(xml, "utf-8") - 1)
+  StrPut(xml, data, "utf-8")
+
+  if !(hupd := DllCall("BeginUpdateResource", "str",ExePath, "int",false))
+    throw OSError()
+  r := DllCall("UpdateResource", "ptr",hupd, "ptr",24, "ptr",1
+          , "ushort", 1033, "ptr",data, "uint",data.size)
+
+  ; Retry loop to work around file locks (especially by antivirus)
+  for delay in [0, 100, 500, 1000, 3500] {
+    Sleep delay
+    if DllCall("EndUpdateResource", "ptr",hupd, "int",!r) || !r
+      return
+    if !(A_LastError = 5 || A_LastError = 110) ; ERROR_ACCESS_DENIED || ERROR_OPEN_FAILED
+      break
+  }
+  throw OSError(A_LastError, "EndUpdateResource")
+}
+
+EnableUIAccess_ReadManifest(ExePath) {
+  if !(hmod := DllCall("LoadLibraryEx", "str",ExePath, "ptr",0, "uint",2, "ptr"))
+    throw OSError()
+  try {
+    if !(hres := DllCall("FindResource", "ptr",hmod, "ptr",1, "ptr",24, "ptr")) {
+      throw OSError()
+    }
+    size := DllCall("SizeofResource", "ptr",hmod, "ptr",hres, "uint")
+    if !(hglb := DllCall("LoadResource", "ptr",hmod, "ptr",hres, "ptr")) {
+      throw OSError()
+    }
+    if !(pres := DllCall("LockResource", "ptr",hglb, "ptr")) {
+      throw OSError()
+    }
+    return StrGet(pres, size, "utf-8")
+  }
+  finally {
+    DllCall("FreeLibrary", "ptr",hmod)
+  }
+}
+
+EnableUIAccess_CreateCert(Name, hStore) {
+  prov := CryptContext() ; Here Name is used as the key container name.
+  if !DllCall("Advapi32\CryptAcquireContext", "ptr*", prov
+    , "str",Name, "ptr",0, "uint",1, "uint",0) { ; PROV_RSA_FULL=1, open existing=0
+    if !DllCall("Advapi32\CryptAcquireContext", "ptr*", prov
+      , "str",Name, "ptr",0, "uint",1, "uint",8) { ; PROV_RSA_FULL=1, CRYPT_NEWKEYSET=8
+      throw OSError()
+    }
+    if !DllCall("Advapi32\CryptGenKey", "ptr",prov
+        , "uint",2, "uint",0x4000001, "ptr*", CryptKey()) { ; AT_SIGNATURE=2, EXPORTABLE=..01
+      throw OSError()
+    }
+  }
+
+  ; Here Name is used as the certificate subject and name.
+  Loop 2 {
+    if A_Index = 1 {
+      pbName := cbName := 0
+    } else {
+      bName := Buffer(cbName), pbName := bName.ptr
+    }
+    if !DllCall("Crypt32\CertStrToName", "uint",1, "str","CN=" Name
+      , "uint",3, "ptr",0, "ptr",pbName, "uint*", &cbName, "ptr",0) ; X509_ASN_ENCODING=1, CERT_X500_NAME_STR=3
+      throw OSError()
+  }
+  cnb := Buffer(2*A_PtrSize), NumPut("ptr",cbName, "ptr",pbName, cnb)
+
+  ; Set expiry to 9999-01-01 12pm +0.
+  NumPut("short", 9999, "sort", 1, "short", 5, "short", 1, "short", 12, endTime := Buffer(16, 0))
+
+  StrPut("2.5.29.4", szOID_KEY_USAGE_RESTRICTION := Buffer(9),, "cp0")
+  StrPut("2.5.29.37", szOID_ENHANCED_KEY_USAGE := Buffer(10),, "cp0")
+  StrPut("1.3.6.1.5.5.7.3.3", szOID_PKIX_KP_CODE_SIGNING := Buffer(18),, "cp0")
+
+  ; CERT_KEY_USAGE_RESTRICTION_INFO key_usage;
+  key_usage := Buffer(6*A_PtrSize, 0)
+  NumPut('ptr', 0, 'ptr', 0, 'ptr', 1, 'ptr', key_usage.ptr + 5*A_PtrSize, 'ptr', 0
+    , 'uchar', (CERT_DATA_ENCIPHERMENT_KEY_USAGE := 0x10)
+         | (CERT_DIGITAL_SIGNATURE_KEY_USAGE := 0x80), key_usage)
+
+  ; CERT_ENHKEY_USAGE enh_usage;
+  enh_usage := Buffer(3*A_PtrSize)
+  NumPut("ptr",1, "ptr",enh_usage.ptr + 2*A_PtrSize, "ptr",szOID_PKIX_KP_CODE_SIGNING.ptr, enh_usage)
+
+  key_usage_data := EncodeObject(szOID_KEY_USAGE_RESTRICTION, key_usage)
+  enh_usage_data := EncodeObject(szOID_ENHANCED_KEY_USAGE, enh_usage)
+
+  EncodeObject(structType, structInfo) {
+    encoder := DllCall.Bind("Crypt32\CryptEncodeObject", "uint",X509_ASN_ENCODING := 1
+      , "ptr",structType, "ptr",structInfo)
+    if !encoder("ptr",0, "uint*", &enc_size := 0)
+      throw OSError()
+    enc_data := Buffer(enc_size)
+    if !encoder("ptr",enc_data, "uint*", &enc_size)
+      throw OSError()
+    enc_data.Size := enc_size
+    return enc_data
+  }
+
+  ; CERT_EXTENSION extension[2]; CERT_EXTENSIONS extensions;
+  NumPut("ptr",szOID_KEY_USAGE_RESTRICTION.ptr, "ptr",true, "ptr",key_usage_data.size, "ptr",key_usage_data.ptr
+    ,    "ptr",szOID_ENHANCED_KEY_USAGE.ptr   , "ptr",true, "ptr",enh_usage_data.size, "ptr",enh_usage_data.ptr
+    , extension := Buffer(8*A_PtrSize))
+  NumPut("ptr",2, "ptr",extension.ptr, extensions := Buffer(2*A_PtrSize))
+
+  if !hCert := DllCall("Crypt32\CertCreateSelfSignCertificate"
+    , "ptr",prov, "ptr",cnb, "uint",0, "ptr",0
+    , "ptr",0, "ptr",0, "ptr",endTime, "ptr",extensions, "ptr") {
+    throw OSError()
+  }
+  cert := CertContext(hCert)
+
+  if !DllCall("Crypt32\CertAddCertificateContextToStore", "ptr",hStore
+    , "ptr",hCert, "uint",1, "ptr",0) { ; STORE_ADD_NEW=1
+    throw OSError()
+  }
+
+  return cert
+}
+
+EnableUIAccess_DeleteCertAndKey(Name) {
+  ; This first call "acquires" the key container but also deletes it.
+  DllCall("Advapi32\CryptAcquireContext", "ptr*", 0, "str",Name
+    , "ptr",0, "uint",1, "uint",16) ; PROV_RSA_FULL=1, CRYPT_DELETEKEYSET=16
+  if !hStore := DllCall("Crypt32\CertOpenStore", "ptr",10 ; STORE_PROV_SYSTEM_W
+    , "uint",0, "ptr",0, "uint",0x20000 ; SYSTEM_STORE_LOCAL_MACHINE
+    , "wstr", "Root", "ptr")
+    throw OSError()
+  store := CertStore(hStore)
+  deleted := 0
+  ; Multiple certificates might be created over time as keys become inaccessible
+  while p := DllCall("Crypt32\CertFindCertificateInStore", "ptr",hStore
+    , "uint",0x10001 ; X509_ASN_ENCODING|PKCS_7_ASN_ENCODING
+    , "uint",0, "uint",0x80007 ; FIND_SUBJECT_STR
+    , "wstr", Name, "ptr",0, "ptr") {
+    if !DllCall("Crypt32\CertDeleteCertificateFromStore", "ptr",p) {
+      throw OSError()
+    }
+    deleted++
+  }
+  return deleted
+}
+
+class Crypt {
+  static IsSigned(FilePath) {
+    return DllCall("Crypt32\CryptQueryObject"
+      ,"uint" 	, CERT_QUERY_OBJECT_FILE := 1
+      ,"wstr" 	, FilePath
+      ,"uint" 	, CERT_QUERY_CONTENT_FLAG_PKCS7_SIGNED_EMBED := 1<<10
+      ,"uint" 	, CERT_QUERY_FORMAT_FLAG_BINARY := 2
+      ,"uint" 	, 0
+      ,"uint*"	, &dwEncoding:=0
+      ,"uint*"	, &dwContentType:=0
+      ,"uint*"	, &dwFormatType:=0
+      ,"ptr"  	, 0
+      ,"ptr"  	, 0
+      ,"ptr"  	, 0)
+  }
+}
+class CryptPtrBase {
+  __new(p:=0) => this.ptr := p
+  __delete() => this.ptr && this.Dispose()
+}
+class CryptContext extends CryptPtrBase {
+  Dispose() => DllCall("Advapi32\CryptReleaseContext", "ptr",this, "uint",0)
+}
+class CertContext extends CryptPtrBase {
+  Dispose() => DllCall("Crypt32\CertFreeCertificateContext", "ptr",this)
+}
+class CertStore extends CryptPtrBase {
+  Dispose() => DllCall("Crypt32\CertCloseStore", "ptr",this, "uint",0)
+}
+class CryptKey extends CryptPtrBase {
+  Dispose() => DllCall("Advapi32\CryptDestroyKey", "ptr",this)
+}
+
+EnableUIAccess_SignFile(ExePath, CertCtx, Name) {
+  file_info := struct( ; SIGNER_FILE_INFO
+    "ptr",A_PtrSize*3, "ptr",StrPtr(ExePath))
+  dwIndex := Buffer(4, 0) ; DWORD
+  subject_info := struct( ; SIGNER_SUBJECT_INFO
+    "ptr",A_PtrSize*4, "ptr",dwIndex.ptr, "ptr",SIGNER_SUBJECT_FILE:=1,
+    "ptr",file_info.ptr)
+  cert_store_info := struct( ; SIGNER_CERT_STORE_INFO
+    "ptr",A_PtrSize*4, "ptr",CertCtx.ptr, "ptr",SIGNER_CERT_POLICY_CHAIN:=2)
+  cert_info := struct( ; SIGNER_CERT
+    "uint",8+A_PtrSize*2, "uint",SIGNER_CERT_STORE:=2,
+    "ptr",cert_store_info.ptr)
+  authcode_attr := struct( ; SIGNER_ATTR_AUTHCODE
+    "uint",8+A_PtrSize*3, "int",false, "ptr",true, "ptr",StrPtr(Name))
+  sig_info := struct( ; SIGNER_SIGNATURE_INFO
+    "uint",8+A_PtrSize*4, "uint",CALG_SHA1:=0x8004,
+    "ptr",SIGNER_AUTHCODE_ATTR:=1, "ptr",authcode_attr.ptr)
+
+  hr := DllCall("MSSign32\SignerSign"
+    , "ptr",subject_info, "ptr",cert_info, "ptr",sig_info
+    , "ptr",0, "ptr",0, "ptr",0, "ptr",0, "hresult") ; pProviderInfo pwszHttpTimeStamp psRequest pSipData
+
+  struct(args*) => (
+    args.Push(b := Buffer(args[2], 0)),
+    NumPut(args*),
+    b
+  )
+}
+
+EnableUIAccess_Verify(ExePath) { ; Verifies a signed executable file.  Returns 0 on success, or a standard OS error number.
+  wfi := Buffer(4*A_PtrSize) ; WINTRUST_FILE_INFO
+  NumPut('ptr', wfi.size, 'ptr', StrPtr(ExePath), 'ptr', 0, 'ptr', 0, wfi)
+  NumPut('int64', 0x11d0cd4400aac56b, 'int64', 0xee95c24fc000c28c, actionID := Buffer(16)) ; WINTRUST_ACTION_GENERIC_VERIFY_V2
+
+  wtd := Buffer(9*A_PtrSize+16) ; WINTRUST_DATA
+  NumPut(
+    'ptr', wtd.Size, 'ptr', 0, 'ptr', 0, 'int', WTD_UI_NONE:=2, 'int', WTD_REVOKE_NONE:=0,
+    'ptr', WTD_CHOICE_FILE:=1, 'ptr', wfi.ptr, 'ptr', WTD_STATEACTION_VERIFY:=1,
+    'ptr', 0, 'ptr', 0, 'int', 0, 'int', 0, 'ptr', 0, wtd
+  )
+  return DllCall('wintrust\WinVerifyTrust', 'ptr', 0, 'ptr', actionID, 'ptr', wtd, 'int')
+}
diff --git a/EnableUIAccess/README.md b/EnableUIAccess/README.md
new file mode 100644
index 000000000..2e9494ae4
--- /dev/null
+++ b/EnableUIAccess/README.md
@@ -0,0 +1,3 @@
+# EnableUIAccess
+
+See [the guide documentation for context](https://github.com/jtroo/kanata/blob/main/docs/config.adoc#windows-only-work-elevated).
diff --git a/README.md b/README.md
index 8a45922dd..1090f9369 100644
--- a/README.md
+++ b/README.md
@@ -15,24 +15,30 @@
 
 ## What does this do?
 
-This is a software keyboard remapper for Linux and Windows. A short summary of
-the features:
+This is a cross-platform software keyboard remapper for Linux, macOS and Windows.
+A short summary of the features:
 
 - multiple layers of key functionality
 - advanced key behaviour customization (e.g. tap-hold, macros, unicode)
-- cross-platform human readable configuration file
 
 To see all of the features, see the [configuration guide](./docs/config.adoc).
 
-The most similar project is [kmonad](https://github.com/david-janssen/kmonad),
-which served as the inspiration for kanata. [Here's a comparison document](./docs/kmonad_comparison.md).
+You can find pre-built binaries in the [releases page](https://github.com/jtroo/kanata/releases)
+or read on for build instructions.
 
 You can see a [list of known issues here](./docs/platform-known-issues.adoc).
 
-### Demo video
+### Demo
+
+#### Demo video
 
 [Showcase of multi-layer functionality (30s, 1.7 MB)](https://user-images.githubusercontent.com/6634136/183001314-f64a7e26-4129-4f20-bf26-7165a6e02c38.mp4).
 
+#### Online simulator
+
+You can check out the [online simulator](https://jtroo.github.io)
+to test configuration validity and test input simulation.
+
 ## Why is this useful?
 
 Imagine if, instead of pressing Shift to type uppercase letters, we had giant
@@ -54,7 +60,8 @@ You will need to keep the window that starts kanata running to keep kanata activ
 Some tips for running kanata in the background:
 
 - Windows: https://github.com/jtroo/kanata/discussions/193
-- Linux: https://github.com/jtroo/kanata/discussions/130
+- Linux: https://github.com/jtroo/kanata/discussions/130#discussioncomment-10227272
+- Run from tray icon: [kanata-tray](https://github.com/rszyma/kanata-tray)
 
 ### Pre-built executables
 
@@ -76,7 +83,7 @@ Using `cargo install`:
 
     cargo install kanata
 
-    # On Linux, this may not work without `sudo`, see below
+    # On Linux and macOS, this may not work without `sudo`, see below
     kanata --cfg <your_configuration_file>
 
 Build and run yourself in Linux:
@@ -96,6 +103,20 @@ Build and run yourself in Windows.
     cargo build   # --release optional, not really perf sensitive
     target\debug\kanata --cfg <your_configuration_file>
 
+Build and run yourself in macOS:
+
+First install the Karabiner driver by following the macOS documentation
+in the [releases page](https://github.com/jtroo/kanata/releases/).
+
+Then you can compile and run with the instructions below:
+
+    git clone https://github.com/jtroo/kanata && cd kanata
+    cargo build   # --release optional, not really perf sensitive
+
+    # sudo is needed to gain permission to intercept the keyboard
+
+    sudo target/debug/kanata --cfg <your_configuration_file>
+
 The full configuration guide is [found here](./docs/config.adoc).
 
 Sample configuration files are found in [cfg_samples](./cfg_samples). The
@@ -103,7 +124,7 @@ Sample configuration files are found in [cfg_samples](./cfg_samples). The
 that is hopefully easy to understand but does not contain all features. The
 `kanata.kbd` contains an example of all features with documentation. The
 release assets also have a `kanata.kbd` file that is tested to work with that
-release. All key names can be found in the [keys module](./src/keys/mod.rs),
+release. All key names can be found in the [keys module](./parser/src/keys/mod.rs),
 and you can also define your own key names.
 
 </details>
@@ -145,15 +166,21 @@ For example:
 cargo build --release --features cmd,interception_driver
 cargo install --features cmd,interception_driver
 ```
+
 </details>
 
 ## Other installation methods
 
+<details>
+<summary>Repositories for kanata</summary>
+
 [![Packaging status](https://repology.org/badge/vertical-allrepos/kanata.svg)](https://repology.org/project/kanata/versions)
 
+</details>
+
 ## Notable features
 
-- Human readable configuration file.
+- Human-readable configuration file.
   - [Minimal example](./cfg_samples/minimal.kbd)
   - [Full guide](./docs/config.adoc)
   - [Simple example with explanations](./cfg_samples/simple.kbd)
@@ -164,7 +191,7 @@ cargo install --features cmd,interception_driver
 - Vim-like leader sequences to execute other actions
 - Optionally run a TCP server to interact with other programs
   - Other programs can respond to [layer changes or trigger layer changes](https://github.com/jtroo/kanata/issues/47)
-- [Interception driver](http://www.oblita.com/interception) support (use `kanata_wintercept.exe`)
+- [Interception driver](https://web.archive.org/web/20240209172129/http://www.oblita.com/interception) support (use `kanata_wintercept.exe`)
   - Note that this issue exists, which is outside the control of this project:
     https://github.com/oblitum/Interception/issues/25
 
@@ -175,20 +202,15 @@ Contributions are welcome!
 Unless explicitly stated otherwise, your contributions to kanata will be made
 under the LGPL-3.0-only[*] license.
 
-The exception to this is the code under the [keyberon](./keyberon) directory,
-which is licensed under the MIT license, and likewise, contributions to code
-in this directory will be made under the MIT license unless explicitly stated
-otherwise.
+Some directories are exceptions:
+
+- [keyberon](./keyberon): MIT License
+- [interception](./interception): MIT or Apache-2.0 Licenses
 
 [Here's a basic low-effort design doc of kanata](./docs/design.md)
 
 [*]: https://www.gnu.org/licenses/identify-licenses-clearly.html
 
-If you want to test changes in the keyberon library code,
-you should change the top-level `Cargo.toml` file.
-Look at the comments around the `kanata-keyberon` dependency
-to understand what changes to make.
-
 ## How you can help
 
 - Try it out and let me know what you think. Feel free to file an issue or
@@ -200,6 +222,22 @@ to understand what changes to make.
 - If you know anything about writing a keyboard driver for Windows, starting an
   open-source alternative to the Interception driver would be lovely.
 
+## Community projects related to kanata
+
+- [vscode-kanata](https://github.com/rszyma/vscode-kanata): Language support for kanata configuration files in VS Code
+- [komokana](https://github.com/LGUG2Z/komokana): Automatic application-aware layer switching for [`komorebi`](https://github.com/LGUG2Z/komorebi) (Windows)
+- [kanata-tray](https://github.com/rszyma/kanata-tray): Control kanata from a tray icon
+- [OverKeys](https://github.com/conventoangelo/overkeys): Visual layer display for kanata - see your active layers and keymaps in real-time (Windows)
+- Application-aware layer switching:
+  - [qanata (Linux)](https://github.com/veyxov/qanata)
+  - [kanawin (Windows)](https://github.com/Aqaao/kanawin)
+  - [window_tools (Windows)](https://github.com/reidprichard/window_tools)
+  - [nata (Linux)](https://github.com/mdSlash/nata)
+  - [kanata-vk-agent (macOS)](https://github.com/devsunb/kanata-vk-agent)
+  - [hyprkan (Linux)](https://github.com/mdSlash/hyprkan)
+  - [kanata-switcher (Linux, all DEs)](https://github.com/7mind/kanata-switcher)
+  - [kwanata (Linux-KDE)](https://github.com/jfsicilia/kwanata): A KDE Plasma companion for Kanata - Automatically activates Kanata's layers/virtualkeys and launches or raises apps.
+
 ## What does the name mean?
 
 I wanted a "k" word since this relates to keyboards. According to Wikipedia,
@@ -250,7 +288,7 @@ hardware, instead of having to purchase an enthusiast mechanical keyboard
 (which are admittedly very nice — I own a few — but can be costly).
 
 The best alternative solution that I found for keyboards that don't run QMK was
-[kmonad](https://github.com/david-janssen/kmonad). This is an excellent project
+[kmonad](https://github.com/kmonad/kmonad). This is an excellent project
 and I recommend it if you want to try something similar.
 
 The reason for this project's existence is that kmonad is written in Haskell
@@ -262,24 +300,29 @@ at the time of writing that make kmonad suboptimal for my personal workflows.
 This project is written in Rust because Rust is my favourite programming
 language and the prior work of the awesome [keyberon crate](https://github.com/TeXitoi/keyberon)
 exists.
+
 </details>
 
 ## Similar Projects
 
-- [kmonad](https://github.com/david-janssen/kmonad): The inspiration for kanata (Linux, Windows, Mac)
+The most similar project is [kmonad](https://github.com/kmonad/kmonad),
+which served as the inspiration for kanata. [Here's a comparison document](./docs/kmonad_comparison.md).
+Other similar projects:
+
 - [QMK](https://docs.qmk.fm/#/): Open source keyboard firmware
 - [keyberon](https://github.com/TeXitoi/keyberon): Rust `#[no_std]` library intended for keyboard firmware
 - [ktrl](https://github.com/ItayGarin/ktrl): Linux-only keyboard customizer with layers, a TCP server, and audio support
 - [kbremap](https://github.com/timokroeger/kbremap): Windows-only keyboard customizer with layers and unicode
-- [xcape](https://github.com/alols/xcape): Linux-only tap-hold modifiers
 - [karabiner-elements](https://karabiner-elements.pqrs.org/): Mac-only keyboard customizer
 - [capsicain](https://github.com/cajhin/capsicain): Windows-only key remapper with driver-level key interception
 - [keyd](https://github.com/rvaiya/keyd): Linux-only key remapper very similar to QMK, kmonad, and kanata
 - [xremap](https://github.com/k0kubun/xremap): Linux-only application-aware key remapper inspired more by Emacs key sequences vs. QMK layers/Vim modes
+- [keymapper](https://github.com/houmain/keymapper): Context-aware cross-platform key remapper with a different transformation model (Linux, Windows, Mac)
+- [mouseless](https://github.com/jbensmann/mouseless): Linux-only mouse-focused key remapper that also has layers, key combo and tap-hold capabilities
 
 ### Why the list?
 
-While kanata is the best tool for me (jtroo), it may not be the best tool for
+While kanata is the best tool for some, it may not be the best tool for
 you. I'm happy to introduce you to tools that may better suit your needs. This
 list is also useful as reference/inspiration for functionality that could be
 added to kanata.
diff --git a/assets/kanata.ico b/assets/kanata.ico
new file mode 100644
index 000000000..80838d3d6
Binary files /dev/null and b/assets/kanata.ico differ
diff --git a/assets/reload_32px.png b/assets/reload_32px.png
new file mode 100644
index 000000000..63601649d
Binary files /dev/null and b/assets/reload_32px.png differ
diff --git a/build.rs b/build.rs
new file mode 100644
index 000000000..3f73d35e4
--- /dev/null
+++ b/build.rs
@@ -0,0 +1,72 @@
+fn main() -> std::io::Result<()> {
+    #[cfg(feature = "win_manifest")]
+    {
+        windows::build()?;
+    }
+    Ok(())
+}
+
+#[cfg(feature = "win_manifest")]
+mod windows {
+    use indoc::formatdoc;
+    use regex::Regex;
+    use std::fs::File;
+    use std::io::Write;
+    extern crate embed_resource;
+
+    // println! during build
+    macro_rules! pb {
+      ($($tokens:tt)*) => {println!("cargo:warning={}", format!($($tokens)*))}}
+
+    pub(super) fn build() -> std::io::Result<()> {
+        let manifest_path: &str = "./target/kanata.exe.manifest";
+
+        // Note about expected version format:
+        // MS says "Use the four-part version format: mmmmm.nnnnn.ooooo.ppppp"
+        // https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests
+
+        let re_ver_build = Regex::new(r"^(?<vpre>(\d+\.){2}\d+)[-a-zA-Z]+(?<vpos>\d+)$").unwrap();
+        let re_ver_build2 = Regex::new(r"^(?<vpre>(\d+\.){2}\d+)[-a-zA-Z]+$").unwrap();
+        let re_version3 = Regex::new(r"^(\d+\.){2}\d+$").unwrap();
+        let mut version: String = env!("CARGO_PKG_VERSION").to_string();
+
+        if re_version3.find(&version).is_some() {
+            version = format!("{version}.0");
+        } else if re_ver_build.find(&version).is_some() {
+            version = re_ver_build
+                .replace_all(&version, r"$vpre.$vpos")
+                .to_string();
+        } else if re_ver_build2.find(&version).is_some() {
+            version = re_ver_build2.replace_all(&version, r"$vpre.0").to_string();
+        } else {
+            pb!("unknown version format '{}', using '0.0.0.0'", version);
+            version = "0.0.0.0".to_string();
+        }
+
+        let manifest_str = formatdoc!(
+            r#"<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+               <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:v3="urn:schemas-microsoft-com:asm.v3">
+                 <assemblyIdentity name="kanata.exe" version="{}" type="win32"></assemblyIdentity>
+                 <v3:trustInfo><v3:security>
+                   <v3:requestedPrivileges><v3:requestedExecutionLevel level="asInvoker" uiAccess="false"></v3:requestedExecutionLevel></v3:requestedPrivileges>
+                 </v3:security></v3:trustInfo>
+                 <v3:application>
+                   <v3:windowsSettings>
+                     <dpiAware     xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
+                     <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
+                   </v3:windowsSettings>
+                 </v3:application>
+                 <dependency><dependentAssembly>
+                   <assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls"
+                     version="6.0.0.0" processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"></assemblyIdentity></dependentAssembly>
+                 </dependency>
+               </assembly>
+            "#,
+            version
+        );
+        let mut manifest_f = File::create(manifest_path)?;
+        write!(manifest_f, "{manifest_str}")?;
+        embed_resource::compile("./src/kanata.exe.manifest.rc", embed_resource::NONE);
+        Ok(())
+    }
+}
diff --git a/cfg_samples/automousekeys-full-map.kbd b/cfg_samples/automousekeys-full-map.kbd
new file mode 100644
index 000000000..84b387f3d
--- /dev/null
+++ b/cfg_samples/automousekeys-full-map.kbd
@@ -0,0 +1,76 @@
+(defcfg
+  ;; F* keys and arrow keys are left unmapped
+  process-unmapped-keys yes
+
+  ;; you may wish to only capture a trackpoint and keyboard
+  ;; but not e.g. a trackpad or external mouse
+  ;;linux-dev-names-include (
+  ;;                         "AT Translated Set 2 keyboard"
+  ;;                         "TPPS/2 Elan TrackPoint"
+  ;;)
+  ;; optional, but useful with the trackpoint
+  ;;linux-use-trackpoint-property yes
+
+  mouse-movement-key mvmt
+)
+
+;; ANSI layout for eg thinkpad internal or external keyboard
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps a    s    d    f    g    h    j    k    l    ;    '    ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt menu rctl
+  mvmt
+)
+
+(defvirtualkeys
+  mouse (layer-while-held mouse-layer)
+)
+
+(defalias
+  mhld (hold-for-duration 750 mouse)
+
+  moff (on-press release-vkey mouse)
+
+  _ (multi
+     @moff
+     _
+  )
+
+   ;; mouse click extended time out for double tap
+  mdbt (hold-for-duration 500 mouse)
+  mbl (multi
+       mlft
+       @mdbt
+  )
+  mbm (multi
+       mmid
+       @mdbt
+  )
+  mbr (multi
+       mrgt
+       @mdbt
+  )
+)
+
+;; no mappings
+(deflayer qwerty
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps a    s    d    f    g    h    j    k    l    ;    '    ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt menu rctl
+  @mhld
+)
+
+;; places mouse keys on the row above the home row.
+;; pressing any other keys exits the mouse layer until mouse movement stops and restarts again.
+(deflayer mouse-layer
+  @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_
+  @_   @_   mrgt mmid @mbl @_   @_   @mbl mmid mrgt @_   @_   @_   @_
+  @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_
+  @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_   @_
+  @_   @_   @_             @_             @_   @_   @_
+  @mhld
+)
diff --git a/cfg_samples/automousekeys-only.kbd b/cfg_samples/automousekeys-only.kbd
new file mode 100644
index 000000000..5fbf90576
--- /dev/null
+++ b/cfg_samples/automousekeys-only.kbd
@@ -0,0 +1,66 @@
+(defcfg
+  ;; we are only mapping the keys we want to use for mouse keys
+  process-unmapped-keys yes
+
+  ;; you may wish to only capture a trackpoint and keyboard
+  ;; but not e.g. a trackpad or external mouse
+  ;;linux-dev-names-include (
+  ;;                         "Lenovo TrackPoint Keyboard II"
+  ;;)
+  ;; optional, but useful with the trackpoint
+  ;;linux-use-trackpoint-property yes
+
+  mouse-movement-key mvmt
+)
+
+(defsrc)
+
+(defvirtualkeys
+  mouse (layer-while-held mouse-layer)
+)
+
+(defalias
+  mhld (hold-for-duration 750 mouse)
+
+  moff (on-press release-vkey mouse)
+
+  _ (multi
+     @moff
+     _
+  )
+
+  ;; mouse click extended time out for double tap
+  mdbt (hold-for-duration 500 mouse)
+  mbl (multi
+       mlft
+       @mdbt
+  )
+  mbm (multi
+       mmid
+       @mdbt
+  )
+  mbr (multi
+       mrgt
+       @mdbt
+  )
+)
+
+;; no key mappings
+(deflayermap (base)
+             mvmt @mhld
+)
+
+;; places mouse keys on the row above the home row.
+;; pressing any other keys exits the mouse layer until mouse movement stops and restarts again.
+(deflayermap (mouse-layer)
+             w mrgt
+             e mmid
+             r @mbl
+
+             u @mbl
+             i mmid
+             o mrgt
+
+             mvmt @mhld
+             ___ @_
+)
diff --git a/cfg_samples/chords.tsv b/cfg_samples/chords.tsv
new file mode 100644
index 000000000..8805591bd
--- /dev/null
+++ b/cfg_samples/chords.tsv
@@ -0,0 +1,192 @@
+rus	rust
+col	cool
+nice	nice
+you	you
+th	the
+ a	a
+ an	an
+man	man
+name	name
+an	and
+as	as
+or	or
+bu	but
+if	if
+so	so
+dn	then
+bc	because
+
+to	to
+of	of
+in	in
+ f	for
+ w	with
+on	on
+at	at
+fm	from
+by	by
+abt	about
+up	up
+io	into
+ov	over
+af	after
+wo	without
+ i	I
+ me	me
+ my	my
+ou	you
+ur	your
+he	he
+hm	him
+his	his
+sh	she
+hr	her
+it	it
+ts	its
+we	we
+us	us
+our	our
+dz	they
+dr	their
+dm	them
+wc	which
+wn	when
+wt	what
+wr	where
+ho	who
+hw	how
+wz	why
+is	is
+ar	are
+wa	was
+er	were
+be	be
+hv	have
+hs	has
+hd	had
+nt	not
+cn	can
+do	do
+wl	will
+cd	could
+wd	would
+sd	should
+li	like
+bn	been
+ge	get
+maz	may
+mad	made
+mk	make
+ai	said
+wk	work
+uz	use
+sz	say
+ g	go
+kn	know
+tk	take
+ se	see
+lk	look
+cm	come
+thk	think
+wnt	want
+gi	give
+ct	cannot
+de	does
+di	did
+sem	seem
+cl	call
+tha	thank
+
+ im	I'm
+ id	I'd
+dt	that
+dis	this
+des	these
+tes	test
+al	all
+ o	one
+mo	more
+the	there
+out	out
+ao	also
+tm	time
+sm	some
+js	just
+ne	new
+odr	other
+pl	people
+ n	no
+dan	than
+oz	only
+ m	most
+ay	any
+may	many
+el	well
+fs	first
+vy	very
+much	much
+now	now
+ev	even
+go	good
+grt	great
+way	way
+ t	two
+yr	year
+bk	back
+day	day
+qn	question
+sc	second
+dg	thing
+ y	yes
+cn'	can't
+dif	different
+dgh	though
+tru	through
+sr	sorry
+mv	move
+dir	dir
+stop	stop
+tye	type
+nx	next
+sam	same
+tp	top
+cod	code
+git	git
+ to	TODO
+cls	class
+clus	cluster
+sure	sure
+lets	let's
+sup	super
+such	such
+thig	thing
+yet	yet
+don	done
+sem	seem
+ran	ran
+job	job
+bot	bot
+fx	effect
+nce	once
+rad	read
+ltr	later
+lot	lot
+brw	brew
+unst	uninstall
+rmv	remove
+ ad	add
+poe	problem
+buld	build
+ tol	tool
+got	got
+les	less
+ 0	zero
+ 1	one
+ 2	two
+ 3	three
+ 4	four
+ 5	five
+ 6	six
+ 7	seven
+ 8	eight
+ 9	nine
diff --git a/cfg_samples/colemak.kbd b/cfg_samples/colemak.kbd
new file mode 100644
index 000000000..b2d5ee2cf
--- /dev/null
+++ b/cfg_samples/colemak.kbd
@@ -0,0 +1,63 @@
+;;
+;;  Learn Colemak, a few keys at a time.
+;;
+;;  The "j" key moves around the keyboard each step,
+;;  until you reach the full Colemak layout.
+;;
+;;  To select the layout for your current step, press the
+;;  letter "m" and the number of your current step, as a chord.
+;;
+;;  Check out:  https://dreymar.colemak.org/tarmak-intro.html
+;;        and:  https://colemak.com
+;;
+
+(defsrc
+  q w e r t y u i o p
+  a s d f g h j k l ;
+  z x c v b n m
+)
+
+(deflayer colemak_j1
+  _ _ j _ _ _ _ _ _ _
+  _ _ _ _ _ _ n e _ _
+  _ _ _ _ _ k _
+)
+
+(deflayer colemak_j2
+  _ _ f _ g _ _ _ _ _
+  _ _ _ t j _ n e _ _
+  _ _ _ _ _ k _
+)
+
+(deflayer colemak_j3
+  _ _ f j g _ _ _ _ _
+  _ r s t d _ n e _ _
+  _ _ _ _ _ k _
+)
+
+(deflayer colemak_j4
+  _ _ f p g j _ _ y ;
+  _ r s t d _ n e _ o
+  _ _ _ _ _ k _
+)
+
+(deflayer colemak
+  _ _ f p g j l u y ;
+  _ r s t d _ n e i o
+  _ _ _ _ _ k _
+)
+
+(defcfg
+  process-unmapped-keys   yes
+  concurrent-tap-hold     yes
+  allow-hardware-repeat   no
+)
+
+(defchordsv2
+  (m 1) (layer-switch colemak_j1) 300 all-released ()
+  (m 2) (layer-switch colemak_j2) 300 all-released ()
+  (m 3) (layer-switch colemak_j3) 300 all-released ()
+  (m 4) (layer-switch colemak_j4) 300 all-released ()
+  (m 5) (layer-switch colemak) 300 all-released ()
+)
+
diff --git a/cfg_samples/deflayermap.kbd b/cfg_samples/deflayermap.kbd
new file mode 100644
index 000000000..62c082623
--- /dev/null
+++ b/cfg_samples/deflayermap.kbd
@@ -0,0 +1,26 @@
+;; A configuration showcasing deflayermap.
+;;
+;; The process-unmapped-keys defcfg item is not used
+;; and the lctl and ralt keys are unmapped
+;; because mapping them can cause problems on Windows
+;; with non-US layouts.
+
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps a    s    d    f    g    h    j    k    l    ;    '    ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+       lmet lalt           spc                 rmet rctl
+)
+
+(deflayermap (base)
+  caps (tap-hold 200 200 (caps-word 2000) lctl)
+  spc  (tap-hold 200 200 spc (layer-while-held nav))
+)
+
+(deflayermap (nav)
+  i up
+  j left
+  k down
+  l right
+)
diff --git a/cfg_samples/fancy_symbols.kbd b/cfg_samples/fancy_symbols.kbd
new file mode 100644
index 000000000..098a24224
--- /dev/null
+++ b/cfg_samples/fancy_symbols.kbd
@@ -0,0 +1,43 @@
+;; Turns   ⎇›            RightAlt into a symbol key to insert valid kanata unicode symbols for the pressed key
+;; Turns ⇧›⎇› RightShift+RightAlt into a symbol key to insert extra symbols for the same keys
+;; e.g., ⎇›Delete will print ␡
+(defcfg)
+(defalias
+   🔣 (layer-while-held fancy-symbol)
+  ⇧🔣 (layer-while-held ⇧fancy-symbol))
+(defsrc
+  ‹🖰	🖰›	🖰3	🖰4	🖰5
+  ▶⏸	◀◀	▶▶	🔇 	🔉	🔊	🔅	🔆	🎛	⌨💡+	⌨💡−
+  ⎋
+  ˋ 	  	1 	2	3	4	5	6	7	8 	9	0	- 	=	␈	⎀	⇤	⇞	⇭ 	🔢⁄	🔢∗	🔢₋
+  ⭾ 	  	q 	w	e	r	t	y	u	i 	o	p	[ 	]	\	␡	⇥	⇟	🔢₇	🔢₈	🔢₉	🔢₊
+  ⇪ 	  	a 	s	d	f	g	h	j	k 	l	;	' 	⏎	 	 	 	 	🔢₄	🔢₅	🔢₆
+  ‹⇧	  	z 	x	c	v	b	n	m	, 	.	/	⇧›	 	▲	 	 	 	🔢₁	🔢₂	🔢₃	🔢⏎
+  ‹⎈	‹◆	‹⎇	␠	 	 	 	 	 	⎇›	 	☰	⎈›	◀	▼	▶	 	 	🔢₀	🔢⸴           )
+(deflayer qwerty ;; =base with ⎇› as a fancy symbol key
+  ‗	‗	‗	‗	‗
+  ‗	‗	‗	‗	‗	‗	‗	‗	‗	‗	‗
+  ‗
+  ‗	‗	‗	‗	‗	‗	‗	‗	‗	‗ 	‗	‗	‗	‗	‗	‗	‗	‗	‗	‗	‗
+  ‗	‗	‗	‗	‗	‗	‗	‗	‗	‗ 	‗	‗	‗	‗	‗	‗	‗	‗	‗	‗	‗
+  ‗	‗	‗	‗	‗	‗	‗	‗	‗	‗ 	‗	‗	‗	 	 	 	 	‗	‗	‗
+  ‗	‗	‗	‗	‗	‗	‗	‗	‗	‗ 	‗	‗	 	‗	 	 	 	‗	‗	‗	‗
+  ‗	‗	‗	‗	 	 	 	 	 	@🔣	 	‗	‗	‗	‗	‗	 	‗	‗           )
+(deflayer  fancy-symbol ;; •block all other keys
+  🔣‹🖰	🔣🖰›	🔣🖰3	🔣🖰4	🔣🖰5
+  🔣▶⏸	🔣◀◀	🔣▶▶	🔣🔇 	🔣🔉	🔣🔊	🔣🔅	🔣🔆	🔣🎛	🔣⌨💡+	🔣⌨💡−
+  🔣⎋
+  🔣ˋ	  	• 	• 	•	•	•	•	•	• 	• 	• 	🔣‐ 	🔣₌	🔣␈	🔣⎀	🔣⇤	🔣⇞	🔣⇭   	🔣🔢⁄	🔣🔢∗	🔣🔢₋
+  🔣⭾	  	• 	• 	•	•	•	•	•	• 	• 	• 	🔣【 	🔣】	🔣⧵	🔣␡	🔣⇥	🔣⇟	🔣🔢₇  	🔣🔢₈	🔣🔢₉	🔣🔢₊
+  🔣⇪	  	• 	• 	•	•	•	•	•	• 	• 	🔣︔	'  	🔣⏎	  	  	  	  	  🔣🔢₄	🔣🔢₅	🔣🔢₆
+  🔣⇧	  	• 	• 	•	•	•	•	•	🔣⸴	🔣．	🔣⁄	@⇧🔣	  	🔣▲	  	  	  	  🔣🔢₁	🔣🔢₂	🔣🔢₃	🔣🔢⏎
+  🔣⎈	🔣◆	🔣⎇	🔣␠	 	 	 	 	 	• 	  	🔣☰	•  	🔣◀	🔣▼	🔣▶	  	  	  🔣🔢₀	🔣🔢⸴  )
+(deflayer ⇧fancy-symbol ;; •block all other keys
+  🔣🖰1	🔣🖰2	•	•    	•
+  •  	•  	•	🔣🔈⓪⓿₀	•	🔣🔈−➖₋⊖	🔣🔈+➕₊⊕	•	•	🔣⌨💡➕₊⊕	🔣⌨💡➖₋⊖
+  •
+  🔣˜	   	• 	• 	•	•	•	•	•	•  	•	•	-   	=   	🔣⌫	• 	🔣⤒↖	🔣🔢	•	•	•	•
+  🔣↹	   	• 	• 	•	•	•	•	•	•  	•	•	🔣「〔⎡	🔣」〕⎣	🔣＼	🔣⌦	🔣⤓↘	• 	•	•	•	•
+  • 	   	• 	• 	•	•	•	•	•	•  	•	•	•   	🔣↩⌤␤	  	  	   	  	 	•	•	•
+  • 	   	• 	• 	•	•	•	•	•	•  	•	/	•   	    	• 	  	   	  	 	•	•	•	🔣🔢↩⌤␤
+  🔣⌃	🔣❖⌘	🔣⌥	🔣␣	 	 	 	 	 	🔣▤𝌆	 	•	•   	•   	• 	• 	   	  	•	•   )
diff --git a/cfg_samples/home-row-mod-advanced.kbd b/cfg_samples/home-row-mod-advanced.kbd
new file mode 100644
index 000000000..9b793d0aa
--- /dev/null
+++ b/cfg_samples/home-row-mod-advanced.kbd
@@ -0,0 +1,67 @@
+;; Home row mods QWERTY example with more complexity.
+;; Some of the changes from the basic example:
+;; - when a home row mod activates tap, the home row mods are disabled
+;;   while continuing to type rapidly
+;; - tap-hold-release-keys helps make the hold action more responsive
+;; - pressing another key on the same half of the keyboard
+;;   as the home row mod will activate an early tap action
+;;
+;; Suggested further reading:
+;;
+;; GitHub discussion on more advanced tap-hold improvements:
+;;
+;;    https://github.com/jtroo/kanata/discussions/1455
+;;
+;; Configuration guide documentation on all tap-hold options:
+;;
+;;    https://github.com/jtroo/kanata/blob/main/docs/config.adoc#tap-hold
+
+(defcfg
+  process-unmapped-keys yes
+)
+(defsrc
+  a   s   d   f   j   k   l   ;
+)
+(defvar
+  ;; Note: consider using different time values for your different fingers.
+  ;; For example, your pinkies might be slower to release keys and index
+  ;; fingers faster.
+  tap-time 200
+  hold-time 150
+
+  left-hand-keys (
+    q w e r t
+    a s d f g
+    z x c v b
+  )
+  right-hand-keys (
+    y u i o p
+    h j k l ;
+    n m , . /
+  )
+)
+(deflayer base
+  @a  @s  @d  @f  @j  @k  @l  @;
+)
+
+(deflayer nomods
+  a   s   d   f   j   k   l   ;
+)
+(deffakekeys
+  to-base (layer-switch base)
+)
+(defalias
+  tap (multi
+    (layer-switch nomods)
+    (on-idle-fakekey to-base tap 20)
+  )
+
+  a (tap-hold-release-keys $tap-time $hold-time (multi a @tap) lmet $left-hand-keys)
+  s (tap-hold-release-keys $tap-time $hold-time (multi s @tap) lalt $left-hand-keys)
+  d (tap-hold-release-keys $tap-time $hold-time (multi d @tap) lctl $left-hand-keys)
+  f (tap-hold-release-keys $tap-time $hold-time (multi f @tap) lsft $left-hand-keys)
+  j (tap-hold-release-keys $tap-time $hold-time (multi j @tap) rsft $right-hand-keys)
+  k (tap-hold-release-keys $tap-time $hold-time (multi k @tap) rctl $right-hand-keys)
+  l (tap-hold-release-keys $tap-time $hold-time (multi l @tap) ralt $right-hand-keys)
+  ; (tap-hold-release-keys $tap-time $hold-time (multi ; @tap) rmet $right-hand-keys)
+)
diff --git a/cfg_samples/home-row-mod-basic.kbd b/cfg_samples/home-row-mod-basic.kbd
new file mode 100644
index 000000000..388e1bdab
--- /dev/null
+++ b/cfg_samples/home-row-mod-basic.kbd
@@ -0,0 +1,30 @@
+;; Basic home row mods example using QWERTY
+;; For a more complex but perhaps usable configuration,
+;; see home-row-mod-advanced.kbd
+
+(defcfg
+  process-unmapped-keys yes
+)
+(defsrc
+  a   s   d   f   j   k   l   ;
+)
+(defvar
+  ;; Note: consider using different time values for your different fingers.
+  ;; For example, your pinkies might be slower to release keys and index
+  ;; fingers faster.
+  tap-time 200
+  hold-time 150
+)
+(defalias
+  a (tap-hold $tap-time $hold-time a lmet)
+  s (tap-hold $tap-time $hold-time s lalt)
+  d (tap-hold $tap-time $hold-time d lctl)
+  f (tap-hold $tap-time $hold-time f lsft)
+  j (tap-hold $tap-time $hold-time j rsft)
+  k (tap-hold $tap-time $hold-time k rctl)
+  l (tap-hold $tap-time $hold-time l ralt)
+  ; (tap-hold $tap-time $hold-time ; rmet)
+)
+(deflayer base
+  @a  @s  @d  @f  @j  @k  @l  @;
+)
\ No newline at end of file
diff --git a/cfg_samples/home-row-mod-prior-idle.kbd b/cfg_samples/home-row-mod-prior-idle.kbd
new file mode 100644
index 000000000..86e391c34
--- /dev/null
+++ b/cfg_samples/home-row-mod-prior-idle.kbd
@@ -0,0 +1,52 @@
+;; Home row mods with tap-hold-require-prior-idle.
+;;
+;; This replaces the layer-switching workaround in home-row-mod-advanced.kbd
+;; with two native features:
+;;
+;;   tap-hold-require-prior-idle  — during fast typing, tap-hold keys resolve as tap
+;;                         immediately (no waiting state, no accidental holds)
+;;
+;;   tap-hold-opposite-hand — hold activates only when the next key is on
+;;                            the opposite hand; same-hand rolls always tap
+;;
+;; The result: no nomods layer, no fakekeys, no multi wrappers.
+;;
+;; Configuration guide:
+;;   https://github.com/jtroo/kanata/blob/main/docs/config.adoc#tap-hold-require-prior-idle
+;;   https://github.com/jtroo/kanata/blob/main/docs/config.adoc#tap-hold
+
+(defcfg
+  process-unmapped-keys yes
+  ;; If any key was pressed within 150ms, resolve tap-hold as tap immediately.
+  ;; Prevents accidental modifier activation during fast typing.
+  tap-hold-require-prior-idle 150
+)
+
+(defsrc
+  a   s   d   f   j   k   l   ;
+)
+
+;; Declare which keys belong to each hand.
+;; tap-hold-opposite-hand uses this to decide hold vs tap.
+(defhands
+  (left  q w e r t a s d f g z x c v b)
+  (right y u i o p h j k l ; n m , . /)
+)
+
+(deflayer base
+  @a  @s  @d  @f  @j  @k  @l  @;
+)
+
+(defalias
+  ;; Note: consider using different time values for your different fingers.
+  ;; For example, your pinkies might be slower to release keys and index
+  ;; fingers faster.
+  a (tap-hold-opposite-hand 150 a lmet)
+  s (tap-hold-opposite-hand 150 s lalt)
+  d (tap-hold-opposite-hand 150 d lctl)
+  f (tap-hold-opposite-hand 150 f lsft)
+  j (tap-hold-opposite-hand 150 j rsft)
+  k (tap-hold-opposite-hand 150 k rctl)
+  l (tap-hold-opposite-hand 150 l ralt)
+  ; (tap-hold-opposite-hand 150 ; rmet)
+)
diff --git a/cfg_samples/included-file.kbd b/cfg_samples/included-file.kbd
new file mode 100644
index 000000000..1c755703d
--- /dev/null
+++ b/cfg_samples/included-file.kbd
@@ -0,0 +1,3 @@
+(defalias
+  included-alias (macro i spc a m spc i n c l u d e d)
+)
diff --git a/cfg_samples/japanese_mac_eisu_kana.kbd b/cfg_samples/japanese_mac_eisu_kana.kbd
new file mode 100644
index 000000000..eed623ef6
--- /dev/null
+++ b/cfg_samples/japanese_mac_eisu_kana.kbd
@@ -0,0 +1,27 @@
+#|
+  Using meta keys as japanese eisu and kana on Mac with US keyboard.
+
+  | Source  | Tap          | Hold |
+  | ------- | ------------ | ---- |
+  | lmet    | lang2 (eisu) | lmet |
+  | rmet    | lang1 (kana) | rmet |
+
+|#
+
+(defcfg
+  process-unmapped-keys yes
+)
+
+(defsrc
+  lmet  rmet
+)
+
+(deflayer default
+  @lmet @rmet
+)
+
+(defalias
+  lmet (tap-hold-press 200 200 eisu lmet)
+  rmet (tap-hold-press 200 200 kana rmet)
+)
+
diff --git a/cfg_samples/kanata.kbd b/cfg_samples/kanata.kbd
index b96ce8ee6..9ea50615d 100644
--- a/cfg_samples/kanata.kbd
+++ b/cfg_samples/kanata.kbd
@@ -1,12 +1,24 @@
 #|
 This is a sample configuration file that showcases every feature in kanata.
+A more detailed and less terse configuration guide is found here:
+
+    https://github.com/jtroo/kanata/blob/main/docs/config.adoc
+
+Other configuration samples are found here:
+
+    https://github.com/jtroo/kanata/tree/main/cfg_samples
+
 If anything is confusing or hard to discover, please file an issue or
 contribute a pull request to help improve the document.
 
-This sample file has documentation but it is lower effort than the configuration
-guide. The configuration guide can be found at:
+Since it may be important for you to know, pressing and holding all of the
+three following keys together at the same time will cause kanata to exit:
+
+  Left Control, Space, Escape
+
+This is for the physical key input rather than after any remappings
+that are done by kanata.
 
-https://github.com/jtroo/kanata/blob/main/docs/config.adoc
 |#
 
 ;; Single-line comments are prefixed by double-semicolon. A single semicolon
@@ -27,12 +39,12 @@ be able to configure kanata.
 
 If you follow along with the examples, you should be fine. Kanata should
 also hopefully have helpful error messages in case something goes wrong.
-If you need help, you are welcome to ask.
+If you need help, please feel welcome to ask in the GitHub discussions.
 |#
 
 ;; One defcfg entry may be added if desired. This is used for configuration
 ;; key-value pairs that change kanata's behaviour at a global level.
-;; All configuration items are optional.
+;; All defcfg options are optional.
 (defcfg
   ;; Your keyboard device will likely differ from this. I believe /dev/input/by-id/
   ;; is preferable; I recall reading that it's less likely to change names on you,
@@ -48,6 +60,15 @@ If you need help, you are welcome to ask.
   ;; kanata does not parse it as multiple devices.
   ;; linux-dev /dev/input/path-to\:device
 
+  ;; Alternatively, you can use list syntax, where both backslashes and colons
+  ;; are parsed literally. List items are separated by spaces or newlines.
+  ;; Using quotation marks for each item is optional, and only required if an
+  ;; item contains spaces.
+  ;; linux-dev (
+  ;;   /dev/input/by-path/pci-0000:00:14.0-usb-0:1:1.0-event
+  ;;   /dev/input/by-id/usb-Dell_Dell_USB_Keyboard-event-kbd
+  ;; )
+
   ;; The linux-dev-names-include entry is parsed identically to linux-dev. It
   ;; defines a list of device names that should be included. This is only
   ;; used if linux-dev is omitted.
@@ -65,12 +86,31 @@ If you need help, you are welcome to ask.
   ;;
   ;; linux-continue-if-no-devs-found yes
 
+  ;; Kanata on Linux automatically detects and grabs input devices
+  ;; when none of the explicit device configurations are in use.
+  ;; In case kanata is undesirably grabbing mouse-like devices,
+  ;; you can use a configuration item to change detection behaviour.
+  ;;
+  ;; linux-device-detect-mode keyboard-only
+
   ;; On Linux, you can ask kanata to run `xset r rate <delay> <rate>` on startup
   ;; and on live reload via the config below. The first number is the delay in ms
   ;; and the second number is the repeat rate in repeats/second.
   ;;
   ;; linux-x11-repeat-delay-rate 400,50
 
+  ;; On linux, you can ask kanata to label itself as a trackpoint. This has several
+  ;; effects on libinput including enabling middle mouse button scrolling and using
+  ;; a different acceleration curve. Otherwise, a trackpoint intercepted by kanata
+  ;; may not behave as expected.
+  ;;
+  ;; If using this feature, it is recommended to filter out any non-trackpoint
+  ;; pointing devices using linux-only-linux-dev-names-include,
+  ;; linux-only-linux-dev-names-exclude or linux-only-linux-dev to avoid changing
+  ;; their behavior as well.
+  ;;
+  ;; linux-use-trackpoint-property yes
+
   ;; Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value,
   ;; then pressing Enter. However, if you do remapping in userspace, e.g. via
   ;; xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u"
@@ -99,6 +139,24 @@ If you need help, you are welcome to ask.
   ;;
   ;;   linux-unicode-termination space
 
+  ;; Kanata on Linux creates an evdev output device named "kanata".
+  ;; This name can be changed with this linux-output-device-name.
+  ;;
+  ;; Examples:
+  ;;
+  ;;   linux-output-device-name kanata_laptop
+  ;;   linux-output-device-name "kanata output device"
+
+  ;; Kanata on Linux needs to declare a "bus type" for its evdev output device.
+  ;; The options are USB and I8042. The default is I8042.
+  ;; Using USB can break disable-touchpad-while-typing on Wayland.
+  ;; But using I8042 appears to break some other scenarios. Thus it is configurable.
+  ;;
+  ;; Examples:
+  ;;
+  ;;   linux-output-device-bus-type USB
+  ;;   linux-output-device-bus-type I8042
+
   ;; There is an optional configuration entry for Windows to help mitigate strange
   ;; behaviour of AltGr if your layout uses that. Uncomment one of the items below
   ;; to change what kanata does with the key.
@@ -134,6 +192,17 @@ If you need help, you are welcome to ask.
   ;;
   ;; process-unmapped-keys yes
 
+  ;; We need to set it to yes in this kanata.kbd example config to allow the use of __ and ___
+  ;; in the deflayer-custom-map example below in the file
+
+  ;; This also accepts a list parameter (all-except key1 ... keyN)
+  ;; which behaves like "yes" but excludes the keys within the list.
+  process-unmapped-keys (all-except f19)
+
+  ;; Disable all keys not mapped in defsrc.
+  ;; Only works if process-unmapped-keys is also yes.
+  ;; block-unmapped-keys yes
+
   ;; Intercept mouse buttons for a specific mouse device.
   ;; The intended use case for this is for laptops such as a Thinkpad, which have
   ;; mouse buttons that may be useful to activate kanata actions with. This only
@@ -147,21 +216,132 @@ If you need help, you are welcome to ask.
   ;;
   ;; windows-interception-mouse-hwid "70, 0, 90, 0, 20"
 
+  ;; There is also a list version of windows-interception-mouse-hwid:
+  ;;
+  ;; windows-interception-mouse-hwids (
+  ;;   "70, 0, 60, 0"
+  ;;   "71, 0, 62, 0"
+  ;; )
+
+  ;; List configuration for kanata-wintercept variants
+  ;; that allows intercepting only some connected keyboards.
+  ;; Use similarly to mouse-hwid above.
+  ;;
+  ;; windows-interception-keyboard-hwids (
+  ;;   "90, 80, 11, 34"
+  ;;   "99, 88, 77, 66"
+  ;; )
+
+  ;; There are also exclude variants of the wintercept device configurations.
+  ;; These cannot be defined at the same time as the non-exclude variants.
+  ;;
+  ;; windows-interception-keyboard-hwids-exclude (
+  ;;   "90, 80, 11, 34"
+  ;;   "99, 88, 77, 66"
+  ;; )
+  ;;
+  ;; windows-interception-mouse-hwids-exclude (
+  ;;   "70, 0, 60, 0"
+  ;;   "71, 0, 62, 0"
+  ;; )
+
   ;; Transparent keys on layers will delegate to the corresponding defsrc key
   ;; when found on a layer activated by `layer-switch`. This config entry
   ;; changes the behaviour to delegate to the action of the first layer,
   ;; which is the layer active upon startup, that is in the same position.
   ;;
   ;; delegate-to-first-layer yes
+
+  ;; This config entry alters the behavior of movemouse-accel actions.
+  ;; By default, this setting is disabled - vertical and horizontal
+  ;; acceleration are independent. Enabling this setting will emulate QMK mouse
+  ;; move acceleration behavior, i.e. the acceleration state of new mouse
+  ;; movement actions are inherited if others are already being pressed.
+  ;;
+  ;; movemouse-inherit-accel-state yes
+
+  ;; This config entry alters the behavior of movemouseaccel actions.
+  ;; This makes diagonal movements simultaneous to mitigate choppiness in
+  ;; drawing apps, if you're using kanata mouse movements to draw for
+  ;; whatever reason.
+  ;;
+  ;; movemouse-smooth-diagonals yes
+
+  ;; This configuration allows you to customize the length limit on dynamic macros.
+  ;; The default limit is 128 keys.
+  ;;
+  ;; dynamic-macro-max-presses 1000
+
+  ;; This configuration makes multiple tap-hold actions that are activated near
+  ;; in time expire their timeout quicker. Without this, the timeout for the 2nd
+  ;; tap-hold onwards will start from 0ms after the previous tap-hold expires.
+  ;;
+  concurrent-tap-hold yes
+
+  ;; This configuration makes the release of one-shot-press and of the tap in a tap-hold
+  ;; by the defined number of milliseconds (approximate).
+  ;; The default value is 5.
+  ;; While the release is delayed, further processing of inputs is also paused.
+  ;; This means that there will be a minor input latency impact in the mentioned scenarios.
+  ;; The reason for this configuration existing is that some environments
+  ;; do not process the scenarios correctly due to the rapidity of the release.
+  ;; Kanata does send the events in the correct order,
+  ;; so the fault is more in the environment, but kanata provides a workaround anyway.
+  rapid-event-delay 5
+
+  ;; This setting defaults to yes but can be configured to no to save on
+  ;; logging. However, if --log-layer-changes is passed as a command line
+  ;; argument, a "no" in the configuration file will be overridden and layer
+  ;; changes will be logged.
+  ;;
+  ;; log-layer-changes no
+
+  ;; This configuration will press and then immediately release the non-modifier key
+  ;; as soon as the override activates, meaning you are unlikely as a human to ever
+  ;; release modifiers first, which can result in unintended behaviour.
+  ;;
+  ;; The downside of this configuration is that the non-modifier key
+  ;; does not remain held which is important to consider for your use cases.
+  override-release-on-activation yes
+
+  ;; Accepts a single key name.
+  ;; When configured, whenever a mouse cursor movement is received,
+  ;; the configured key name will be "tapped" by Kanata, activating
+  ;; the key's action.
+  ;;
+  ;; This enables reporting of every relative mouse movement, which
+  ;; corresponds to standard mice, trackballs, trackpads and
+  ;; trackpoints. Absolute movements, which can be generated by
+  ;; touchscreens, drawing tablets and some mouse replacement or
+  ;; accessibility software, are ignored. Scrolling events and mouse
+  ;; buttons are also ignored.
+  ;;
+  ;; The intended use of these events is to provide a way to
+  ;; automatically enable a mouse keys layer while mousing, which can
+  ;; be disabled by a timeout or typing on other keys, rather than
+  ;; explicit toggling. see cfg_examples/automousekeys-*.kbd for more.
+  ;;
+  ;; The `mvmt` key name is specially intended for this purpose. It
+  ;; has no output key mapping and cannot be supplied as an action;
+  ;; however, any key may be used.
+  ;;
+  ;; Supports live reload on Linux, but with Windows-interception,
+  ;; this option must be present on startup to enable mouse movement
+  ;; event collection, so restart is required to enable it. Changing
+  ;; the key name is always supported, however.
+  ;;
+  ;; mouse-movement-key mvmt
 )
 
 ;; deflocalkeys-* enables you to define and use key names that match your locale
 ;; by defining OS code number mappings for that character.
 ;;
-;; There are three variants of deflocalkeys-*:
+;; There are five variants of deflocalkeys-*:
 ;; - deflocalkeys-win
+;; - deflocalkeys-winiov2
 ;; - deflocalkeys-wintercept
 ;; - deflocalkeys-linux
+;; - deflocalkeys-macos
 ;;
 ;; Only one of each deflocalkeys-* variant is allowed. The variants that are
 ;; not applicable will be ignored, e.g. deflocalkeys-linux and deflocalkeys-wintercept
@@ -192,10 +372,18 @@ If you need help, you are welcome to ask.
   ì 187
 )
 
+(deflocalkeys-winiov2
+  ì 187
+)
+
 (deflocalkeys-linux
   ì 13
 )
 
+(deflocalkeys-macos
+  ì 13
+)
+
 ;; Only one defsrc is allowed.
 ;;
 ;; defsrc defines the keys that will be intercepted by kanata. The order of the
@@ -219,8 +407,6 @@ If you need help, you are welcome to ask.
 ;; The first layer defined is the layer that will be active by default when
 ;; kanata starts up. This layer is the standard QWERTY layout except for the
 ;; backtick/grave key (@grl) which is an alias for a tap-hold key.
-;;
-;; There are currently a maximum of 25 layers allowed.
 (deflayer qwerty
   @grl 1    2    3    4    5    6    7    8    9    0    -    =    bspc
   tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
@@ -239,17 +425,57 @@ If you need help, you are welcome to ask.
   lctl lmet lalt           spc           @ralt rmet @rcl
 )
 
+;; This is an alternative to deflayer and does not rely on defsrc.
+;; It has the advantage of simpler config if only remapping a few keys.
+;; You might still prefer the standard deflayer for its visual printing in
+;; the log as you are learning a new configuration.
+(deflayermap (custom-map-example)
+  caps esc
+  esc  caps
+
+  ;; You can use _ , __ or ___ instead of specifying a key name to map all
+  ;; keys that are not explicitly mapped in the layer.
+  ;; E.g. esc and caps above will not be overwritten.
+  ;;
+  ;; _    maps only keys that are in defsrc.
+  ;; __   excludes mapping keys that are in defsrc.
+  ;; ___  maps both, keys that are in `defsrc`, and keys that are not.
+  ;;
+  ;; The two- and three-underscore variants require
+  ;; "process-unmapped-keys yes" in defcfg to work.
+
+  ;; ___ XX ;; maps all keys that are not mapped explicitly in the layer
+  ;;          ;; (i.e. esc and caps above) to "no-op" to disable the key.
+  _ XX   ;; maps all keys that are in defsrc and are not mapped in the layer
+  __ XX  ;; maps all keys that are NOT in defsrc and are not mapped in the layer
+)
+
 ;; defvar can be used to declare commonly-used values
 (defvar
-  tap-timeout   100
-  hold-timeout  200
-  tt $tap-timeout
+  tap-repress-timeout   100
+  hold-timeout          200
+  tt $tap-repress-timeout
   ht $hold-timeout
+
+  ;; A list value in defvar that begins with concat behaves in a special manner
+  ;; where strings will be joined together.
+  ;;
+  ;; Below results in 100200
+  a "hello"
+  b "world"
+  ct (concat $a " " $b)
 )
 
 (defalias
   th1 (tap-hold $tt $ht caps lctl)
   th2 (tap-hold $tt $ht spc lsft)
+
+  ;; tap-hold-opposite-hand-release is a release-time variant of
+  ;; tap-hold-opposite-hand. It waits for the interrupting key to be pressed
+  ;; AND released before deciding, which avoids misfires on fast same-hand
+  ;; rolls. Requires defhands.
+  ;; actl (tap-hold-opposite-hand-release 200 a lctl
+  ;;   (same-hand tap) (unknown-hand hold) (timeout hold))
 )
 
 ;; defalias is used to declare a shortcut for a more complicated action to keep
@@ -277,9 +503,11 @@ If you need help, you are welcome to ask.
   fks (layer-while-held fakekeys)
 
   ;; tap-hold aliases with tap for dvorak key, and hold for toggle layers
+  ;; WARNING(Linux only): key repeat with tap-hold can behave unexpectedly.
+  ;; For full context, see https://github.com/jtroo/kanata/discussions/422
   ;;
   ;; tap-hold parameter order:
-  ;; 1. tap timeout
+  ;; 1. tap repress timeout
   ;; 2. hold timeout
   ;; 3. tap action
   ;; 4. hold action
@@ -287,11 +515,11 @@ If you need help, you are welcome to ask.
   ;; The hold timeout is the number of milliseconds after which the hold action
   ;; will activate.
   ;;
-  ;; The tap timeout is best explained in a roundabout way. When you press and
+  ;; The tap repress timeout is best explained in a roundabout way. When you press and
   ;; hold a standard key on your keyboard (e.g. 'a'), your operating system will
   ;; read that and keep sending 'a' to the active application. To be able to
   ;; replicate this behaviour with a tap-hold key, you must press-release-press
-  ;; the key within the tap timeout window (number is milliseconds). Simply
+  ;; the key within the tap repress timeout window (number is milliseconds). Simply
   ;; holding the key results in the hold action activating, which is why you
   ;; need to double-press for the tap action to stay pressed.
   ;;
@@ -325,13 +553,45 @@ If you need help, you are welcome to ask.
   oat (tap-hold-press-timeout   200 200 o @arr bspc)
   ;; tap: e    hold: chords layer    timeout: esc
   ect (tap-hold-release-timeout 200 200 e @chr esc)
+  ;; If you add reset-timeout-on-press to tap-hold-release-timeout,
+  ;; the timeout will reset on a press to give you more time to release
+  ;; a key to activate the hold.
+  ect2 (tap-hold-release-timeout 200 200 e @chr esc reset-timeout-on-press)
 
   ;; There is another variant of `tap-hold-release` that takes a 5th parameter
-  ;; that is a list of keys that will trigger an early tap.
+  ;; that is a list of keys that will trigger an early tap when pressed.
 
   ;; tap: u    hold: misc layer      early tap if any of: (a o e) are pressed
   umk (tap-hold-release-keys 200 200 u @msc (a o e))
 
+  ;; A variant of tap-hold-release-keys accepts another parameter,
+  ;; which is a list of keys that activates the tap
+  ;; on a press->release of a listed key.
+  umk2 (tap-hold-release-tap-keys-release 200 200 u @msc (a o e) (' , .))
+
+  ;; tap: u    hold: misc layer      always tap if any of: (a o e) are pressed
+  uek (tap-hold-except-keys 200 200 u @msc (a o e))
+
+  ;; tap: u    hold: misc layer      early tap if any of: (a o e) are pressed
+  ;; Unlike tap-hold-release-keys, other keys do NOT trigger early hold.
+  ;; This is useful for home row mods where fast typing should not trigger modifiers.
+  utk (tap-hold-tap-keys 200 200 u @msc (a o e))
+
+  ;; tap-hold-keys is a flexible tap-hold with named key list options.
+  ;; tap: u    hold: misc layer
+  ;; (tap-on-press a o e)         — tap immediately if a, o, or e are pressed
+  ;; (tap-on-press-release ' , .) — tap if ', ,, or . are pressed then released
+  ;; (hold-on-press 1 2 3)        — hold immediately if 1, 2, or 3 are pressed
+  ;; All list options are optional. Unlisted keys use PermissiveHold behavior.
+  uthk (tap-hold-keys 200 200 u @msc
+    (tap-on-press a o e)
+    (tap-on-press-release ' , .)
+    (hold-on-press 1 2 3))
+
+  ;; tap-hold-order resolves by release order instead of timeout.
+  ;; tap: a    hold: lctl    buffer: 50ms (fast typing grace period)
+  aor (tap-hold-order 200 50 a lctl)
+
   ;; tap for capslk, hold for lctl
   cap (tap-hold 200 200 caps lctl)
 
@@ -345,6 +605,20 @@ If you need help, you are welcome to ask.
   ralt (multi ralt (layer-toggle ralted))
 )
 
+;; Wrapping a top-level configuration item in a list beginning with
+;; (environment (env-var-name env-var-value) ...configuration...)
+;; will make the configuration only active if the environment variable matches.
+(environment (LAPTOP lp1)
+  (defalias met @lp1met)
+)
+
+(environment (LAPTOP lp2)
+  (defalias met @lp2met)
+)
+
+;; NOTE: the configuration below is an older and less general variant
+;; of the environment configuration above.
+;;
 ;; The defaliasenvcond variant of defalias is parsed similarly, but there must
 ;; be a list parameter first. The list must contain two strings. In order,
 ;; these strings are: an environment variable name, and the environment
@@ -384,9 +658,17 @@ If you need help, you are welcome to ask.
   ;; same and only one is allowed in a single chord. This chord can be useful for
   ;; international layouts.
   ;;
+  ;; A special behaviour of output chords is that if another key is pressed,
+  ;; all of the chord keys will be released. For the explanation about why
+  ;; this is the case, see the configuration guide.
+  ;;
   ;; This use case for multi is typing an all-caps string.
   alp (multi lsft a b c d e f g h i j k l m n o p q r s t u v w x y z)
 
+  ;; Within multi you can also include reverse-release-order to release keys
+  ;; from last-to-first order instead of first-to-last which is the default.
+  S-a-reversed (multi lsft a reverse-release-order)
+
   ;; Chords using the shortcut syntax. These ones are used for copying/pasting
   ;; from some Linux terminals.
   csv C-S-v
@@ -409,12 +691,16 @@ If you need help, you are welcome to ask.
   tbm (macro A-(tab 200 tab 200 tab) 200 S-A-(tab 200 tab 200 tab))
   hpy (macro S-i spc a m spc S-(h a p p y) spc m y S-f r S-i e S-n d @🙃)
 
-  rls (macro-release-cancel 1 500 bspc S-1 500 bspc S-2)
+  rls (macro-release-cancel Digit1 500 bspc S-1 500 bspc S-2)
+  cop (macro-cancel-on-press Digit1 500 bspc S-1 500 bspc S-2)
+  rlpr (macro-release-cancel-and-cancel-on-press Digit1 500 bspc S-1 500 bspc S-2)
 
   ;; repeat variants will repeat while held, once ALL macros have ended,
   ;; including the held macro.
   mr1 (macro-repeat mltp)
   mr2 (macro-repeat-release-cancel mltp)
+  mr3 (macro-repeat-cancel-on-press mltp)
+  mr4 (macro-repeat-release-cancel-and-cancel-on-press mltp)
 
   ;; Kanata also supports dynamic macros. Dynamic macros can be nested, but
   ;; cannot recurse.
@@ -427,16 +713,121 @@ If you need help, you are welcome to ask.
   dp1 (dynamic-macro-play 1)
   dp2 (dynamic-macro-play 2)
 
+  ;; unmod will release all modifiers temporarily and send the .
+  ;; So for example holding shift and tapping a @um1 key will still output 1.
+  um1 (unmod 1)
+  ;; dead keys é (as opposed to using AltGr) that outputs É when shifted
+  dké (macro (unmod ') e)
+
+  ;; unshift is like unmod but only releases shifts
+  ;; In ISO German QWERTZ, force unshifted symbols even if shift is held
+  de{ (unshift ralt 7)
+  de[ (unshift ralt 8)
+
+  ;; unmod can optionally take a list as the first parameter,
+  ;; and then will only temporarily remove
+  ;; the listed modifiers instead of all modifiers.
+  unalt-a (unmod (lalt ralt) a)
+
   ;; unicode accepts a single unicode character. The unicode character will
   ;; not be automatically repeated by holding the key down. The alias name
   ;; is the unicode character itself and is referenced by @🙁 in deflayer.
   🙁 (unicode 🙁)
 
+  ;; You may output parentheses or double quotes using unicode
+  ;; by quotes as well as special quoting syntax.
+  lp1 (unicode r#"("#)
+  rp1 (unicode r#")"#)
+  dq (unicode r#"""#)
+  lp2 (unicode "(")
+  rp2 (unicode ")")
+
   ;; fork accepts two actions and a key list. The first (left) action will
   ;; activate by default. The second (right) action will activate if any of
   ;; the keys in the third parameter (right-trigger-keys) are currently active.
   frk (fork @🙃 @🙁 (lsft rsft))
 
+  ;; switch accepts triples of keys check, action, and fallthrough|break.
+  ;; The default usage of keys check behaves similarly to fork.
+  ;; However, it also accepts boolean operators and|or to allow more
+  ;; complex use cases.
+  ;;
+  ;; The order of cases matters. If two different cases match the
+  ;; currently pressed keys, the case listed earlier in the configuration
+  ;; will activate first. If the early case uses break, the second case will
+  ;; not activate at all. Otherwise if fallthrough is used, the second case
+  ;; will also activate sequentially after the first case.
+  swt (switch
+    ;; If you have cmd enabled,
+    ;; you may choose to add `init-cmd` which will execute the program
+    ;; and you can later use `cmd-exit` to choose what to output based on exit code.
+    ;; (init-cmd powershell.exe -c "if (-not (Test-Path 'myfile')) { exit 1 }")
+
+    ;; translating this keys check to some other common languages
+    ;; this might look like:
+    ;;
+    ;;    (a && b && (c || d) && (e || f))
+    ((and a b (or c d) (or e f))) a break
+
+    ;; this case behaves like fork, i.e.
+    ;;
+    ;;    (or a b c)
+    ;;
+    ;; or for some other common languages:
+    ;;
+    ;;    a || b || c
+    (a b c) b fallthrough
+
+    ;; key-history evaluates to true if the n'th most recent typed key,
+    ;; {n | n ∈ [1, 8]}, matches the given key.
+    ((key-history a 1) (key-history b 8)) c break
+
+    ;; key-timing evaluates to true if the n'th most recent typed key,
+    ;; {n | n ∈ [1, 8]}, was typed at a time less-than/greater-than the
+    ;; given number of milliseconds.
+    ((key-timing 1 lt 3000)       (key-timing 2 gt 30000)        ) c break
+    ((key-timing 7 less-than 200) (key-timing 8 greater-than 500)) c break
+
+    ;; not means "not any of the list constituents".
+    ;; The example below behaves like:
+    ;;
+    ;;    !(a || b || c)
+    ;;
+    ;; and is equivalent to:
+    ;;
+    ;;    ((not (or a b c)))
+    ((not a b c)) c break
+
+    ;; input logic
+    ((input real lctl)) d break
+    ((input virtual sft)) e break
+    ((input-history real lsft 2)) f break
+    ((input-history virtual ctl 2)) g break
+
+    ;; layer evaluates to `true` if the active layer matches the given name
+    ((layer dvorak)) x break
+    ((layer qwerty)) y break
+
+    ;; base-layer evaluates to `true` if the base layer matches the given name
+    ;; The base layer is the most recent target of layer-switch.
+    ;; The base layer is not always the active layer.
+    ((base-layer dvorak)) x break
+    ((base-layer qwerty)) y break
+
+    ;; device-history evaluates to `true` if the Nth most recent device
+    ;; matches the given device ID defined in definputdevices. Currently macOS only.
+    ;; ((device-history 1 1)) x break
+    ;; ((device-history 2 1)) y break
+
+    ;; If you have cmd enabled, you can check on the
+    ;; exit code of the most recent `init-cmd` occurrence.
+    ;; ((cmd-exit 0)) a break
+
+    ;; default case, empty list always evaluates to true.
+    ;; break vs. fallthrough doesn't matter here
+    () c break
+  )
+
   ;; Having a cmd action in your configuration without explicitly enabling
   ;; `danger-enable-cmd` **and** using the cmd-enabled executable will make
   ;; kanata refuse to load your configuration. The aliases below are commented
@@ -451,29 +842,69 @@ If you need help, you are welcome to ask.
   ;;
   ;; cm1 (cmd bash -c "echo hello world")
   ;; cm2 (cmd rm -fr /tmp/testing)
+
+  ;; One variant of `cmd` is `cmd-log`, which lets you control how
+  ;; running command, stdout, stderr, and execution failure are logged.
+  ;;
+  ;; The command takes two extra arguments at the beginning `<log_level>`,
+  ;; and `<error_log_level>`. `<log_level>` controls where the name
+  ;; of the command is logged, as well as the success message and command
+  ;; stdout and stderr.
+  ;;
+  ;; `<error_log_level>` is only used if there is a failure executing the initial
+  ;; command. This can be if there is trouble spawning the command, or
+  ;; the command is not found. This means if you use `bash -c "thisisntacommand"`, as
+  ;; long as bash starts up correctly, nothing would be logged to this channel, but
+  ;; something like `thisisntacommand` would be.
+  ;;
+  ;; The log level can be `debug`, `info`, `warn`, `error`, or `none`.
+  ;;
+  ;; cmd-log info error bash -c "echo these are the default levels"
+  ;; cmd-log none none bash -c "echo nothing back in kanata logs"
+  ;; cmd-log none error bash -c "only if command fails"
+  ;; cmd-log debug debug bash -c "echo log, but require changing verbosity levels"
+  ;; cmd-log warn warn bash -c "echo this probably isn't helpful"
+
+  ;; Another variant of `cmd` is `cmd-output-keys`. This reads the output
+  ;; of the command and treats it as an S-Expression, similarly to `macro`.
+  ;; However, only delays, keys, chords, and chorded lists are supported.
+  ;; Other actions are not.
+  ;;
+  ;; bash: type date-time as YYYY-MM-DD HH:MM
+  ;; cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'"
 )
 
 ;; The underscore _ means transparent. The key on the base layer will be used
 ;; instead. XX means no-op. The key will do nothing.
+;;
+;; A similar concept to transparent, use-defsrc means the key will always
+;; behave as the key as defined by defsrc.
+(defalias src use-defsrc)
 (deflayer numbers
-  _    _    _    _    _    _    nlk  kp7  kp8  kp9  _    _    _    _
+  @src _    _    _    _    _    nlk  kp7  kp8  kp9  _    _    _    _
   _    _    _    _    _    XX   _    kp4  kp5  kp6  -    _    _    _
   _    _    C-z  _    _    XX   _    kp1  kp2  kp3  +    _    _
   _    C-z  C-x  C-c  C-v  XX   _    kp0  kp0  .    /    _
   _    _    _              _              _    _    _
 )
 
-;; The `lrld` action stands for "live reload". This will re-parse everything
-;; except for linux-dev. So in Linux, you cannot live reload and switch keyboard
-;; devices at the time of writing. The variants `lrpv` and `lrnx` will cycle
-;; between multiple configuration files, if they are specified in the startup.
-;; arguments.
+;; The `lrld` action stands for "live reload".
+;;
+;; NOTE: live reload does not read changes to device-related configurations,
+;; such as `linux-dev`, `macos-dev-names-include`,
+;; or `windows-only-windows-interception-keyboard-hwids`.
+;;
+;; The variants `lrpv` and `lrnx` will cycle between multiple configuration files
+;; if they are specified in the startup arguments.
+;; The list action variant `lrld-num` takes a number parameter and
+;; reloads the configuration file specified by the number, according to the
+;; order passed into the arguments on kanata startup.
 ;;
 ;; Upon a successful reload, the kanata state will begin on the default base layer
 ;; in the configuration. E.g. in this example configuration, you would start on
 ;; the qwerty layer.
 (deflayer layers
-  _    @qwr @dvk lrld lrpv lrnx _    _    _    _    _    _    _    _
+  _    @qwr @dvk lrld lrpv lrnx (lrld-num 1) _ _    _    _    _    _    _
   _    _    _    _    _    _    _    _    _    _    _    _    _    _
   _    _    _    _    _    _    _    _    _    _    _    _    _
   _    _    _    _    _    _    _    _    _    _    _    _
@@ -513,6 +944,13 @@ If you need help, you are welcome to ask.
   opp (one-shot-press-pcancel 500 lsft)
   orp (one-shot-release-pcancel 500 lsft)
 
+  ;; one-shot-pause-processing can be useful in some cases
+  ;; to preserve an activated one-shot state when it otherwise
+  ;; would get deactivated by some action that isn't intended
+  ;; to consume the one-shot.
+  ;; The unit is number of milliseconds.
+  ops (one-shot-pause-processing 5)
+
   ;; Alias for tap-dance which will activate one of the actions in the action
   ;; list depending on how many taps were done. Tapping once will output the
   ;; first action and tapping N times will output the N'th action.
@@ -565,10 +1003,21 @@ If you need help, you are welcome to ask.
   ;; This example is similar to the default caps-word behaviour but it moves the
   ;; 0-9 keys to capitalized key list from the extra non-terminating key list.
   cwc (caps-word-custom
-        2000
-        (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
-	(kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
-      )
+    2000
+    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
+    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
+  )
+)
+
+;; -toggle variants of caps-word will terminate caps-word on repress if it is
+;; currently active, otherwise caps-word will be activated.
+(defalias
+  cwt (caps-word-toggle 2000)
+  cct (caps-word-custom-toggle
+    2000
+    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
+    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
+  )
 )
 
 ;; Can see a new action `rpt` in this layer. This repeats the most recently
@@ -631,7 +1080,7 @@ If you need help, you are welcome to ask.
   _    @mwu @mwd @mwl @mwr _    _    _    _    _    @ma↑ _    _    _
   _    pgup bck  _    fwd  _    _    _    _    @ma← @ma↓ @ma→ _    _
   _    pgdn mlft _    mrgt mmid _    mbck mfwd _    @ms↑ _    _
-  _    _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
+  @fms _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
   _    _    _              _              _    _    _
 )
 
@@ -652,6 +1101,20 @@ If you need help, you are welcome to ask.
   mwl (mwheel-left 50 120)
   mwr (mwheel-right 50 120)
 
+  ;; There are similar wheel actions with `-accel` that have
+  ;; accelerating/inertial scrolling.
+  ;; The parameters are:
+  ;; 1. initial velocity
+  ;; 2. maximum velocity
+  ;; 3. acceleration multiplier
+  ;; 4. deceleration multiplier
+  ;; The units are arbitrary.
+  ;; The author finds the values in the example below
+  ;; to be a decent-feeling starting paint.
+  ;; Experiment to find your preference.
+  mau (mwheel-accel-up   3 1200 1.15 0.93)
+  mad (mwheel-accel-down 3 1200 1.15 0.93)
+
   ;; Mouse movement actions.The first number is the interval in milliseconds
   ;; between mouse actions. The second number is the distance traveled per interval
   ;; in pixels.
@@ -680,6 +1143,12 @@ If you need help, you are welcome to ask.
   ;; treated as one giant screen, which may make it a bit confusing for how to
   ;; set up the pixels. You will need to experiment.
   sm (setmouse 32228 32228)
+
+  ;; movemouse-speed takes a percentage by which it then scales all of the
+  ;; mouse movements while held. You can have as many of these active at a
+  ;; given time as you would like, but be warned that some values, such as 33
+  ;; may not have correct pixel distance representations.
+  fms (movemouse-speed 200)
 )
 
 (defalias
@@ -705,21 +1174,60 @@ If you need help, you are welcome to ask.
   _    _    _              _              _    _    _
 )
 
+;; Virtual key actions
+
+(defvirtualkeys
+  ;; Define some virtual keys that perform modifier actions
+  vkctl lctl
+  vksft lsft
+  vkmet lmet
+  vkalt lalt
+
+  ;; A virtual key that toggles all modifier virtual keys above
+  vktal (multi
+        (on-press toggle-virtualkey vkctl)
+        (on-press toggle-virtualkey vksft)
+        (on-press toggle-virtualkey vkmet)
+        (on-press toggle-virtualkey vkalt)
+      )
+
+  ;; Virtual key that activates a macro
+  vkmacro (macro h e l l o spc w o r l d)
+)
+
+(defalias
+  psfvk (on-press press-virtualkey   vksft)
+  rsfvk (on-press release-virtualkey vksft)
+
+  palvk (on-press tap-vkey vktal)
+  macvk (on-press tap-vkey vkmacro)
+
+  isfvk (on-idle 1000 tap-vkey vksft)
+  pisfvk (on-physical-idle 1000 tap-vkey vksft)
+)
+
 ;; Press and release fake keys.
 ;;
 ;; Fake keys can't be pressed by any physical keyboard buttons and can only be
-;; acted upon by the actions on-press-fakekey and on-release-fakekey. The
-;; purpose of fake keys is for a use case such as holding modifier keys for
-;; any number of keypresses and then releasing the modifiers when desired.
+;; acted upon by the actions:
+;; - on-press-fakekey
+;; - on-release-fakekey
+;; - on-idle-fakekey
+;;
+;; One use case of fake keys is for holding modifier keys
+;; for any number of keypresses and then releasing the modifiers when desired.
 ;;
 ;; The actions associated with fake keys in deffakekeys are parsed before
 ;; aliases, so you can't use aliases within deffakekeys. Other than the lack
 ;; of alias support, fake keys can do any action that a normal key can,
 ;; including doing operations on previously defined fake keys.
 ;;
-;; Operations on fake keys can occur either on press (on-press-fakekey) or
-;; on release (on-release-fakekey). The use cases for the on-release variant
-;; are left up to your own creativity.
+;; Operations on fake keys can occur either on press (on-press-fakekey),
+;; on release (on-release-fakekey), or on idle for a specified time
+;; (on-idle-fakekey).
+;;
+;; Fake keys are flexible in usage but can be obscure to discover how they
+;; can be useful to you.
 (deflayer fakekeys
   _    @fcp @fsp @fmp @pal _    _    _    _    _    _    _    _    _
   _    @fcr @fsr @fap @ral _    _    _    _    _    _    _    _    _
@@ -756,6 +1264,7 @@ If you need help, you are welcome to ask.
   fsp (on-release-fakekey sft press)
   fsr (on-release-fakekey sft release)
   fst (on-release-fakekey sft tap)
+  fsg (on-release-fakekey sft toggle)
   fmp (on-press-fakekey met press)
   fap (on-press-fakekey alt press)
   rma (multi
@@ -764,6 +1273,8 @@ If you need help, you are welcome to ask.
       )
   pal (on-press-fakekey pal tap)
   ral (on-press-fakekey ral tap)
+  rdl (on-idle-fakekey ral tap 1000)
+  hfd (hold-for-duration 1000 met)
 
   ;; Test of on-press-fakekey and on-release-fakekey in a macro
   t1 (macro-release-cancel @fsp 5 a b c @fsr 5 c b a)
@@ -793,6 +1304,11 @@ If you need help, you are welcome to ask.
 ;; You can add an entry to defcfg to change the sequence timeout (default is 1000):
 ;;     sequence-timeout <number(ms)>
 ;;
+;; If you want multiple timeouts with different leaders, you can also activate the
+;; sequence action:
+;;     (sequence <timeout>)
+;; This acts like `sldr` but uses a different timeout.
+;;
 ;; There is also an option to customize the key sequence input mode. Its default
 ;; value when not configured is `hidden-suppressed`.
 ;;
@@ -817,6 +1333,58 @@ If you need help, you are welcome to ask.
 (deffakekeys git-status (macro g i t spc s t a t u s))
 (defalias rcl (tap-hold-release 200 200 sldr rctl))
 
+(defseq
+    dotcom (. S-3)
+    dotorg (. S-4)
+)
+(deffakekeys
+    dotcom (macro . c o m)
+    dotorg (macro . o r g)
+)
+;; Enter sequence mode and input .
+(defalias dot-sequence (macro (sequence 250) 10 .))
+(defalias dot-sequence-inputmode (macro (sequence 250 hidden-delay-type) 10 .))
+
+;; There are special keys that you can assign in your actions which will
+;; never output events to your operating system, but which you can use
+;; in sequences. They are named: nop0-nop9.
+(defseq
+    dotcom (nop0 nop1)
+    dotorg (nop8 nop9)
+)
+
+;; A key list within O-(...) signifies simultaneous presses.
+(defseq
+    dotcom (O-(. c m))
+    dotorg (O-(. r g))
+)
+
+;; sequence-noerase
+;;
+;; When you have a keyboard locale that uses dead keys,
+;; you may be pressing two keys that only actually output one symbol.
+;; By default, when visible-backspaced does the backtracking backspace,
+;; it backspaces according to input count.
+;; With dead keys, this may result in too many backspaces.
+;;
+;; The sequence-noerase action is a no-output action
+;; that tells the sequences action to have one fewer backspace
+;; when backtracking with visible-backspaced.
+
+(deflayermap (base)
+  0 sldr
+  u (t! maybe-noerase u)
+)
+(deftemplate maybe-noerase (char)
+  (multi
+    (switch
+      ((key-history ' 1)) (sequence-noerase 1) fallthrough
+      () $char break
+   ))
+)
+(defvirtualkeys seq-output-1 (macro a b c d e f g))
+(defseq seq-output-1 (' u))
+
 ;; Input chording.
 ;;
 ;; Not to be confused with output chords (like C-S-a or the chords layer
@@ -871,9 +1439,205 @@ If you need help, you are welcome to ask.
   (  2 4 8) (multi 1 4)
   (1 2 4 8) (multi 1 5)
 )
+
 (defalias
   ch1 (chord binary 1)
   ch2 (chord binary 2)
   ch4 (chord binary 4)
   ch8 (chord binary 8)
 )
+
+;; The top-level action `include` will read a configuration from a new file.
+;; At the time of writing, includes can only be placed at the top level. The
+;; included files also cannot contain includes themselves.
+;;
+;; (include included-file.kbd)
+
+
+;; The top-level item `deftemplate` declares a template
+;; which can be expanded multiple times to reduce repetition.
+;;
+;; Expansion of a template is done via `expand-template`.
+
+;; This template defines a chord group and aliases that use the chord group.
+;; The purpose is to easily define the same chord position behaviour
+;; for multiple layers that have different underlying keys.
+(deftemplate left-hand-chords (chordgroupname k1 k2 k3 k4 alias1 alias2 alias3 alias4)
+  (defalias
+    $alias1 (chord $chordgroupname $k1)
+    $alias2 (chord $chordgroupname $k2)
+    $alias3 (chord $chordgroupname $k3)
+    $alias4 (chord $chordgroupname $k4)
+  )
+  (defchords $chordgroupname $chord-timeout
+    ($k1) $k1
+    ($k2) $k2
+    ($k3) $k3
+    ($k4) $k4
+    ($k1 $k2) lctl
+    ($k3 $k4) lsft
+  )
+)
+
+(defvar chord-timeout 200)
+
+(template-expand left-hand-chords qwerty a s d f qwa qws qwd qwf)
+;; You can use t! as a short form of template-expand
+(t! left-hand-chords dvorak a o e u dva dvo dve dvu)
+
+(deflayer template-example
+  _    _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    @qwa @qws @qwd @qwf _    _    _    _    _    _    _    _    _
+  _    @dva @dvo @dve @dvu _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _              _              _    _    _
+)
+
+;; Within a deftemplate you can use if-equal to conditionally insert content
+;; into the template.
+
+(deftemplate home-row (version)
+  a s d f g h
+  (if-equal $version v1 j)
+  (if-equal $version v2 (tap-hold 200 200 j lctl))
+   k l ; '
+)
+
+(deftemplate common-overrides ()
+  (lctl 7) (lctl lsft tab)
+  (lctl 9) (lctl tab)
+  (lalt 7) (lalt lsft tab)
+  (lalt 9) (lalt tab)
+)
+
+;; Wrapping a top-level configuration item in a list beginning with
+;; (platform (applicable-platforms...) ...configuration...)
+;; will make the configuration only active on a specific platform.
+(platform (macos)
+  ;; Only on macos, use command arrows to jump/delete words
+  ;; because command is used for so many other things
+  ;; and it's weird that these cases use alt.
+  (defoverrides
+    (lmet bspc)  (lalt bspc)
+    (lmet left)  (lalt left)
+    (lmet right) (lalt right)
+    (template-expand common-overrides)
+  )
+)
+(platform (win winiov2 wintercept linux)
+  (defoverrides
+    (template-expand common-overrides)
+  )
+)
+
+#|
+There is a more recent version of defoverrides that offers more customizability.
+Instead of 2 list items per override entry,
+`defoverridesv2` mandates 4, though the extra 2 can be empty.
+
+You cannot have both a v1 and v2 of `defoverrides` at the same time.
+
+The 3rd item is an "exclude modifiers list" which is composed of modifier key names
+(such as `lctl`, `lalt`) that, if held, will disable the override from activating.
+
+The 4th item is an "exclude layers" list which is composed of layer names
+that while active as the most recent `layer-switch` or `layer-while-held`,
+will disable the override from activating.
+
+(defoverridesv2
+  ;; lctl+a will become lalt+9
+  ;; except when lsft is held or other-layer is active.
+  (lctl a) (lalt 9) (lsft) (other-layer))
+
+  ;; lctl+b will always become lalt+0
+  (lctl b) (lalt 0) () ()
+)
+|#
+
+#|
+
+Global input chords.
+
+Syntax (5-tuples):
+
+    (defchordsv2
+      (participating-keys1) action1 timeout1 release-behaviour1 (disabled-layers1)
+        ...
+      (participating-keysN) actionN timeoutN release-behaviourN (disabled-layersN)
+    )
+
+|#
+
+(defchordsv2
+  (a b c)   (macro a l p h a b e t)  200 all-released  (qwerty arrows)
+  (h l o)   (macro h e l l o)        250 first-release (qwerty arrows)
+  (g b y e) (macro g o o d b y e)    400 first-release (qwerty arrows)
+)
+
+#|
+
+Yet another chording implementation - zippychord:
+
+
+;; This is a sample for US international layout.
+(defzippy
+  zippy.txt
+  on-first-press-chord-deadline 500
+  idle-reactivate-time          500
+  smart-space-punctuation (? ! . , ; :)
+  output-character-mappings (
+    ! S-1
+    ? S-/
+    % S-5
+    "(" S-9
+    ")" S-0
+    : S-;
+    < S-,
+    > S-.
+    r#"""# S-'
+    | S-\
+    _ S--
+    ® AG-r
+    ;; In case you use dead keys or compose keys
+    ;; where multiple keys are pressed
+    ;; to produce a single backspaceable symbol,
+    ;; use no-erase or single-output
+    ’ (no-erase `)
+    é (single-output ' e)
+  )
+)
+
+Example file content of zippy.txt:
+---
+dy	day
+dy 1	Monday
+ abc	Alphabet
+r df	recipient
+ w  a	Washington
+rq	request
+rqa	request assistance
+---
+
+You can read about zippychord in more detail in the configuration guide.
+
+|#
+
+#|
+
+Clipboard actions allow you to manipulate the clipboard.
+To paste, you should manually output C-v,
+or whatever key output is necessary to paste.
+E.g. S-ins might also work.
+
+|#
+
+(deflayermap (clip)
+ a (clipboard-set       clip)
+ b (clipboard-save      0)
+ c (clipboard-restore   0)
+ d (clipboard-save-swap 0 65535)
+ #| actions with cmd only works with the compilation flags and defcfg enablement.
+ e (clipboard-cmd-set powershell.exe -c "echo 'hello world'")
+ f (clipboard-save-cmd-set 0 bash -c "echo 'goodbye'")
+ |#
+)
diff --git a/cfg_samples/kanata.plist b/cfg_samples/kanata.plist
new file mode 100644
index 000000000..f8eb9ea7d
--- /dev/null
+++ b/cfg_samples/kanata.plist
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Sample LaunchDaemon for kanata on macOS.
+
+  This is a LaunchDaemon (runs as root at boot), not a LaunchAgent.
+  Kanata needs root because the Karabiner-DriverKit-VirtualHIDDevice
+  daemon exposes its IPC under
+  `/Library/Application Support/org.pqrs/tmp/rootonly/`, which is
+  mode 700 owned by root. See `src/oskbd/macos.rs` for the full
+  rationale.
+
+  Customize the two paths in `ProgramArguments` below for your install:
+    - kanata binary: e.g. `/usr/local/bin/kanata`,
+      `/opt/homebrew/bin/kanata`, or wherever you placed it
+    - config file: e.g. `/etc/kanata/kanata.kbd` or any root-readable
+      path
+
+  Install:
+    sudo cp cfg_samples/kanata.plist /Library/LaunchDaemons/dev.kanata.kanata.plist
+    sudo chown root:wheel /Library/LaunchDaemons/dev.kanata.kanata.plist
+    sudo launchctl bootstrap system /Library/LaunchDaemons/dev.kanata.kanata.plist
+
+  Reload after editing your kanata config (or this plist):
+    sudo launchctl kickstart -k system/dev.kanata.kanata
+
+  Uninstall:
+    sudo launchctl bootout system/dev.kanata.kanata
+    sudo rm /Library/LaunchDaemons/dev.kanata.kanata.plist
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>dev.kanata.kanata</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/kanata</string>
+        <string>-c</string>
+        <string>/etc/kanata/kanata.kbd</string>
+    </array>
+
+    <key>UserName</key>
+    <string>root</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>/var/log/kanata.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/var/log/kanata.log</string>
+</dict>
+</plist>
diff --git a/cfg_samples/karabiner-vhid-daemon.plist b/cfg_samples/karabiner-vhid-daemon.plist
new file mode 100644
index 000000000..c9be20a9b
--- /dev/null
+++ b/cfg_samples/karabiner-vhid-daemon.plist
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  LaunchDaemon for the Karabiner VirtualHIDDevice daemon.
+
+  Required only when using the standalone Karabiner-DriverKit-VirtualHIDDevice
+  package without Karabiner-Elements (which manages the daemon itself).
+
+  Install:
+    sudo cp cfg_samples/karabiner-vhid-daemon.plist \
+      /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+    sudo chown root:wheel \
+      /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+    sudo launchctl bootstrap system \
+      /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+
+  Uninstall:
+    sudo launchctl bootout system/org.pqrs.Karabiner-VirtualHIDDevice-Daemon
+    sudo rm /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>org.pqrs.Karabiner-VirtualHIDDevice-Daemon</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon</string>
+    </array>
+
+    <key>UserName</key>
+    <string>root</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/var/log/karabiner-vhid-daemon.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/var/log/karabiner-vhid-daemon.log</string>
+</dict>
+</plist>
diff --git a/cfg_samples/key-toggle_press-only_release-only.kbd b/cfg_samples/key-toggle_press-only_release-only.kbd
new file mode 100644
index 000000000..6e63e894c
--- /dev/null
+++ b/cfg_samples/key-toggle_press-only_release-only.kbd
@@ -0,0 +1,34 @@
+#|
+
+This configuration showcases all of:
+	- key toggle
+	- press-only
+	- release-only
+
+|#
+
+(deftemplate toggle-key (vkey-name output-key alias)
+	(defvirtualkeys $vkey-name $output-key)
+	(defalias $alias (on-press toggle-vkey $vkey-name))
+)
+
+(deftemplate press-only-release-only-pair
+		(vkey-name output-key press-alias release-alias)
+	(defvirtualkeys $vkey-name $output-key)
+	(defalias $press-alias (on-press press-vkey $vkey-name))
+	(defalias $release-alias (on-press release-vkey $vkey-name))
+)
+
+(template-expand toggle-key v-lctl lctl lcl)
+(template-expand toggle-key v-rctl rctl rcl)
+
+;; t! is a short form of template-expand
+(t! press-only-release-only-pair v-lalt lalt p-a r-a)
+
+(defsrc
+	lctl rctl lalt ralt
+)
+
+(deflayer base
+	@lcl @rcl @p-a @r-a
+)
diff --git a/cfg_samples/opposite-hand-hrm.kbd b/cfg_samples/opposite-hand-hrm.kbd
new file mode 100644
index 000000000..353aa2d95
--- /dev/null
+++ b/cfg_samples/opposite-hand-hrm.kbd
@@ -0,0 +1,47 @@
+;; Home row mods using tap-hold-opposite-hand
+;;
+;; Hold activates only when the next key is on the opposite hand,
+;; which substantially reduces misfires during fast same-hand rolls.
+;; Same-hand keys resolve as tap by default.
+;;
+;; Compare with home-row-mod-basic.kbd which uses plain tap-hold.
+
+(defcfg
+  process-unmapped-keys yes
+)
+
+;; Assign physical keys to hands. Keys not listed have no hand
+;; assignment and are governed by (unknown-hand <value>) (default: ignore).
+(defhands
+  (left  q w e r t a s d f g z x c v b)
+  (right y u i o p h j k l ; n m , . /))
+
+(defsrc
+  q   w   e   r   t   y   u   i   o   p
+  a   s   d   f   g   h   j   k   l   ;
+  z   x   c   v   b   n   m   ,   .   /
+                  spc
+)
+
+(defvar
+  tap-time 200
+  hold-time 180
+)
+
+(defalias
+  a (tap-hold-opposite-hand $hold-time a lmet)
+  s (tap-hold-opposite-hand $hold-time s lalt)
+  d (tap-hold-opposite-hand $hold-time d lctl)
+  f (tap-hold-opposite-hand $hold-time f lsft)
+  j (tap-hold-opposite-hand $hold-time j rsft)
+  k (tap-hold-opposite-hand $hold-time k rctl)
+  l (tap-hold-opposite-hand $hold-time l ralt)
+  ; (tap-hold-opposite-hand $hold-time ; rmet)
+)
+
+(deflayer base
+  q   w   e   r   t   y   u   i   o   p
+  @a  @s  @d  @f  g   h   @j  @k  @l  @;
+  z   x   c   v   b   n   m   ,   .   /
+                  spc
+)
diff --git a/cfg_samples/push-msg.kbd b/cfg_samples/push-msg.kbd
new file mode 100644
index 000000000..c4e25cd32
--- /dev/null
+++ b/cfg_samples/push-msg.kbd
@@ -0,0 +1,110 @@
+;; push-msg Sample Configuration
+;;
+;; This configuration demonstrates the push-msg action for sending
+;; messages to external tools via Kanata's TCP server.
+;;
+;; To use this config:
+;;   kanata -p 7070 -c push-msg.kbd
+;;
+;; Then connect a TCP client to localhost:7070 to receive messages.
+
+(defcfg
+  process-unmapped-keys yes
+)
+
+(defsrc
+  caps a s d f g h j k l ; '
+  z x c v b n m , . /
+)
+
+;; ==========================================================================
+;; Layer Definitions
+;; ==========================================================================
+
+(deflayer base
+  @caps a s d f g h j k l ; '
+  z x c v b n m , . /
+)
+
+(deflayer nav
+  @caps left down up right g h j k l ; '
+  z x c v b n m , . /
+)
+
+;; ==========================================================================
+;; Aliases with push-msg
+;; ==========================================================================
+
+(defalias
+  ;; Caps Lock: tap for Esc (with notification), hold for nav layer (with notification)
+  caps (tap-hold 200 200
+    (multi esc (push-msg "layer:base"))
+    (multi (layer-toggle nav) (push-msg "layer:nav:hold"))
+  )
+)
+
+;; ==========================================================================
+;; Virtual Keys - Triggerable via TCP ActOnFakeKey
+;; ==========================================================================
+;;
+;; External tools can trigger these using TCP commands:
+;;   {"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}
+;;   {"ActOnFakeKey":{"name":"switch-nav","action":"Tap"}}
+
+(defvirtualkeys
+  ;; Text expansion macro (S-x for shift+x to get capitals)
+  email-sig (macro
+    S-b e s t spc r e g a r d s , ret ret
+    S-j o h n spc S-d o e
+  )
+
+  ;; Layer switches that also push messages
+  switch-nav (multi
+    (layer-switch nav)
+    (push-msg "layer:nav:activated")
+  )
+
+  switch-base (multi
+    (layer-switch base)
+    (push-msg "layer:base:activated")
+  )
+
+  ;; Notify external tools (no keyboard action)
+  notify-ready (push-msg "status:ready")
+  notify-busy (push-msg "status:busy")
+)
+
+;; ==========================================================================
+;; Usage Examples for External Tools
+;; ==========================================================================
+;;
+;; Python TCP client example:
+;;
+;;   import socket
+;;   import json
+;;
+;;   sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+;;   sock.connect(('127.0.0.1', 7070))
+;;   buffer = ""
+;;
+;;   while True:
+;;       data = sock.recv(4096).decode()
+;;       buffer += data
+;;       while '\n' in buffer:
+;;           line, buffer = buffer.split('\n', 1)
+;;           if line:
+;;               msg = json.loads(line)
+;;               if 'MessagePush' in msg:
+;;                   print(f"Received: {msg['MessagePush']['message']}")
+;;               elif 'LayerChange' in msg:
+;;                   print(f"Layer: {msg['LayerChange']['new']}")
+;;
+;; Triggering virtual keys from external tools:
+;;
+;;   # Send this JSON to trigger the email-sig virtual key:
+;;   echo '{"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}' | nc localhost 7070
+;;
+;;   # Or trigger layer switch:
+;;   echo '{"ActOnFakeKey":{"name":"switch-nav","action":"Tap"}}' | nc localhost 7070
+;;
+;; ==========================================================================
diff --git a/cfg_samples/simple.kbd b/cfg_samples/simple.kbd
index 1208cdcd8..a6f67e0f1 100644
--- a/cfg_samples/simple.kbd
+++ b/cfg_samples/simple.kbd
@@ -26,8 +26,6 @@
 ;; The first layer defined is the layer that will be active by default when
 ;; kanata starts up. This layer is the standard QWERTY layout except for the
 ;; backtick/grave key (@grl) which is an alias for a tap-hold key.
-;;
-;; There are currently a maximum of 25 layers allowed.
 (deflayer qwerty
   @grl 1    2    3    4    5    6    7    8    9    0    -    =    bspc
   tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
diff --git a/cfg_samples/transparent_default.kbd b/cfg_samples/transparent_default.kbd
deleted file mode 100644
index edd4fcb70..000000000
--- a/cfg_samples/transparent_default.kbd
+++ /dev/null
@@ -1,16 +0,0 @@
-(defcfg
-  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
-)
-
-(defsrc
-       f13  f14  f15
-)
-
-(deflayer default
-       _ (layer-switch test) (layer-toggle test)
-)
-
-(deflayer test
-       (layer-switch default) (layer-toggle default) _
-)
-
diff --git a/cfg_samples/tray-icon/3trans.parent.png b/cfg_samples/tray-icon/3trans.parent.png
new file mode 100644
index 000000000..a199266de
Binary files /dev/null and b/cfg_samples/tray-icon/3trans.parent.png differ
diff --git a/cfg_samples/tray-icon/6name-match.png b/cfg_samples/tray-icon/6name-match.png
new file mode 100644
index 000000000..cd0a00efa
Binary files /dev/null and b/cfg_samples/tray-icon/6name-match.png differ
diff --git a/cfg_samples/tray-icon/_custom-icons/s.png b/cfg_samples/tray-icon/_custom-icons/s.png
new file mode 100644
index 000000000..4692a76f3
Binary files /dev/null and b/cfg_samples/tray-icon/_custom-icons/s.png differ
diff --git a/cfg_samples/tray-icon/icons/1symbols.png b/cfg_samples/tray-icon/icons/1symbols.png
new file mode 100644
index 000000000..f55da3329
Binary files /dev/null and b/cfg_samples/tray-icon/icons/1symbols.png differ
diff --git a/cfg_samples/tray-icon/img/2Nav Num.png b/cfg_samples/tray-icon/img/2Nav Num.png
new file mode 100644
index 000000000..b70b4415e
Binary files /dev/null and b/cfg_samples/tray-icon/img/2Nav Num.png differ
diff --git a/cfg_samples/tray-icon/license_icons.txt b/cfg_samples/tray-icon/license_icons.txt
new file mode 100644
index 000000000..e45a2e224
--- /dev/null
+++ b/cfg_samples/tray-icon/license_icons.txt
@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2024, Fred Vatin
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/cfg_samples/tray-icon/tray-icon.kbd b/cfg_samples/tray-icon/tray-icon.kbd
new file mode 100644
index 000000000..c52570411
--- /dev/null
+++ b/cfg_samples/tray-icon/tray-icon.kbd
@@ -0,0 +1,29 @@
+(defcfg
+  process-unmapped-keys		yes	;;|no| enable processing of keys that are not in defsrc, useful if mapping a few keys in defsrc instead of most of the keys on your keyboard. Without this, the tap-hold-release and tap-hold-press actions will not activate for keys that are not in defsrc. Disabled because some keys may not work correctly if they are intercepted. E.g. rctl/altgr on Windows; see the windows-altgr configuration item above for context.
+  log-layer-changes    		yes	;;|no| overhead
+  tray-icon "./_custom-icons/s.png" ;; should activate for layers without icons like '5no-icn'
+  ;;opt                   	val  	  |≝|
+  icon-match-layer-name   	yes  	;;|yes| match layer name to icon files even without an explicit (icon name.ico) config
+  tooltip-layer-changes   	yes  	;;|false|
+  tooltip-show-blank      	yes  	;;|no|
+  tooltip-duration        	500  	;;|500|
+  tooltip-size            	24,24	;;|24 24|
+  notify-cfg-reload       	yes  	;;|yes|
+  notify-cfg-reload-silent	no   	;;|no|
+  notify-error            	yes  	;;|yes|
+)
+(defalias l1 (layer-while-held 1emoji))
+(defalias l2 (layer-while-held 2icon-quote))
+(defalias l3 (layer-while-held 3emoji_alt))
+(defalias l4 (layer-while-held 4my-lmap))
+(defalias l5 (layer-while-held 5no-icn))
+(defalias l6 (layer-while-held 6name-match))
+
+(defsrc     	            	                            	1  	2  	3  	4  	5  	6)
+(deflayer   	(⌂          	icon base.png)              	@l1	@l2	@l3	@l4	@l5	@l6)	;; find in the 'icon'  subfolder
+(deflayer   	(1emoji     	🖻 1symbols.png)             	q  	q  	q  	q  	q  	q)  	;; find in the 'icons' subfolder
+(deflayer   	(2icon-quote	🖻 "2Nav Num.png")           	w  	w  	w  	w  	w  	w)  	;; find in the 'img'   subfolder
+(deflayer   	(3emoji_alt 	🖼 3trans.parent)            	e  	e  	e  	e  	e  	e)  	;; find '.png'
+(deflayermap	(4my-lmap   	🖻 "..\..\assets\kanata.ico")	1 r	2 r	3 r	4 r	5 r	6 r) ;; find in relative path
+(deflayer   	5no-icn     	                            	t  	t  	t  	t  	t  	t) ;; match file name from 'tray-icon' config, whithout which would fall back to 'tray-icon.png' as it's the only valid icon matching 'tray-icon.kbd' name
+(deflayer   	6name-match 	                            	y  	y  	y  	y  	y  	y) ;; uses '6name-match' with any valid extension since 'icon-match-layer-name' is set to 'yes'
diff --git a/cfg_samples/tray-icon/tray-icon.png b/cfg_samples/tray-icon/tray-icon.png
new file mode 100644
index 000000000..7508e5c82
Binary files /dev/null and b/cfg_samples/tray-icon/tray-icon.png differ
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..fad53bcb0
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,6 @@
+
+### Converting ".adoc" to html
+
+To generate html from the these documentation files, use ["asciidoctor"](https://asciidoctor.org)
+(they are not fully compatible with the separate "asciidoc" project)
+
diff --git a/docs/avoid-sudo-linux.md b/docs/avoid-sudo-linux.md
deleted file mode 100644
index 63dd41205..000000000
--- a/docs/avoid-sudo-linux.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Instructions
-
-In Linux, kanata needs to be able to access the input and uinput subsystem to inject events. To do this, your user needs to have permissions. Follow the steps in this page to obtain user permissions.
-
-### 1. If the uinput group does not exist, create a new group
-
-```bash
-sudo groupadd uinput
-```
-
-### 2. Add your user to the input and the uinput group
-
-```bash
-sudo usermod -aG input $USER
-sudo usermod -aG uinput $USER
-```
-
-Make sure that it's effective by running `groups`. You might have to logout and login.
-
-### 3. Make sure the uinput device file has the right permissions.
-
-Add a udev rule (in either `/etc/udev/rules.d` or `/lib/udev/rules.d`) with the following content:
-
-```
-KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"
-```
-
-### 4. Make sure the uinput drivers are loaded
-
-You may need to run this command whenever you start kanata for the first time:
-
-```
-sudo modprobe uinput
-```
-
-# Credits
-
-The original text was taken and adapted from: https://github.com/kmonad/kmonad/blob/master/doc/faq.md#linux
diff --git a/docs/config-stylesheet.css b/docs/config-stylesheet.css
new file mode 100644
index 000000000..fd8b46e0d
--- /dev/null
+++ b/docs/config-stylesheet.css
@@ -0,0 +1,543 @@
+html{font-family:sans-serif;-webkit-text-size-adjust:100%}
+a{background:none}
+a:focus{outline:thin dotted}
+a:active,a:hover{outline:0}
+h1{font-size:2em;margin:.67em 0}
+b,strong{font-weight:bold}
+abbr{font-size:.9em}
+abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
+dfn{font-style:italic}
+hr{height:0}
+mark{background:#ff0;color:#000}
+code,kbd,pre,samp{font-family:monospace;font-size:1em}
+pre{white-space:pre-wrap}
+q{quotes:"\201C" "\201D" "\2018" "\2019"}
+small{font-size:80%}
+sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
+sup{top:-.5em}
+sub{bottom:-.25em}
+img{border:0}
+svg:not(:root){overflow:hidden}
+figure{margin:0}
+audio,video{display:inline-block}
+audio:not([controls]){display:none;height:0}
+fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
+legend{border:0;padding:0}
+button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
+button,input{line-height:normal}
+button,select{text-transform:none}
+button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
+button[disabled],html input[disabled]{cursor:default}
+input[type=checkbox],input[type=radio]{padding:0}
+button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
+textarea{overflow:auto;vertical-align:top}
+table{border-collapse:collapse;border-spacing:0}
+*,::before,::after{box-sizing:border-box}
+html,body{font-size:100%}
+body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
+a:hover{cursor:pointer}
+img,object,embed{max-width:100%;height:auto}
+object,embed{height:100%}
+img{-ms-interpolation-mode:bicubic}
+.left{float:left!important}
+.right{float:right!important}
+.text-left{text-align:left!important}
+.text-right{text-align:right!important}
+.text-center{text-align:center!important}
+.text-justify{text-align:justify!important}
+.hide{display:none}
+img,object,svg{display:inline-block;vertical-align:middle}
+textarea{height:auto;min-height:50px}
+select{width:100%}
+.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
+div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
+a{color:#2156a5;text-decoration:underline;line-height:inherit}
+a:hover,a:focus{color:#1d4b8f}
+a img{border:0}
+p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
+p aside{font-size:.875em;line-height:1.35;font-style:italic}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
+h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
+h1{font-size:2.125em}
+h2{font-size:1.6875em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
+h4,h5{font-size:1.125em}
+h6{font-size:1em}
+hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
+em,i{font-style:italic;line-height:inherit}
+strong,b{font-weight:bold;line-height:inherit}
+small{font-size:60%;line-height:inherit}
+code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
+ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
+ul,ol{margin-left:1.5em}
+ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
+ul.circle{list-style-type:circle}
+ul.disc{list-style-type:disc}
+ul.square{list-style-type:square}
+ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
+ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
+dl dt{margin-bottom:.3125em;font-weight:bold}
+dl dd{margin-bottom:1.25em}
+blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
+blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
+@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
+h1{font-size:2.75em}
+h2{font-size:2.3125em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
+h4{font-size:1.4375em}}
+table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
+table thead,table tfoot{background:#f7f8f7}
+table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
+table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
+table tr.even,table tr.alt{background:#f8f8f7}
+table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
+h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
+.center{margin-left:auto;margin-right:auto}
+.stretch{width:100%}
+.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
+.clearfix::after,.float-group::after{clear:both}
+:not(pre).nobreak{word-wrap:normal}
+:not(pre).nowrap{white-space:nowrap}
+:not(pre).pre-wrap{white-space:pre-wrap}
+:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
+pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
+pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
+pre>code{display:block}
+pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
+em em{font-style:normal}
+strong strong{font-weight:400}
+.keyseq{color:rgba(51,51,51,.8)}
+kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
+.keyseq kbd:first-child{margin-left:0}
+.keyseq kbd:last-child{margin-right:0}
+.menuseq,.menuref{color:#000}
+.menuseq b:not(.caret),.menuref{font-weight:inherit}
+.menuseq{word-spacing:-.02em}
+.menuseq b.caret{font-size:1.25em;line-height:.8}
+.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
+b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
+b.button::before{content:"[";padding:0 3px 0 2px}
+b.button::after{content:"]";padding:0 2px 0 3px}
+p a>code:hover{color:rgba(0,0,0,.9)}
+#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
+#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
+#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
+#content{margin-top:1.25em}
+#content::before{content:none}
+#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
+#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
+#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
+#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
+#header .details span:first-child{margin-left:-.125em}
+#header .details span.email a{color:rgba(0,0,0,.85)}
+#header .details br{display:none}
+#header .details br+span::before{content:"\00a0\2013\00a0"}
+#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
+#header .details br+span#revremark::before{content:"\00a0|\00a0"}
+#header #revnumber{text-transform:capitalize}
+#header #revnumber::after{content:"\00a0"}
+#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
+#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
+#toc>ul{margin-left:.125em}
+#toc ul.sectlevel0>li>a{font-style:italic}
+#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
+#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
+#toc li{line-height:1.3334;margin-top:.3334em}
+#toc a{text-decoration:none}
+#toc a:active{text-decoration:underline}
+#toctitle{color:#7a2518;font-size:1.2em}
+@media screen and (min-width:768px){#toctitle{font-size:1.375em}
+body.toc2{padding-left:15em;padding-right:0}
+body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
+#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
+#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
+#toc.toc2>ul{font-size:.9em;margin-bottom:0}
+#toc.toc2 ul ul{margin-left:0;padding-left:1em}
+#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
+body.toc2.toc-right{padding-left:0;padding-right:15em}
+body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
+@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
+#toc.toc2{width:20em}
+#toc.toc2 #toctitle{font-size:1.375em}
+#toc.toc2>ul{font-size:.95em}
+#toc.toc2 ul ul{padding-left:1.25em}
+body.toc2.toc-right{padding-left:0;padding-right:20em}}
+#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
+#content #toc>:first-child{margin-top:0}
+#content #toc>:last-child{margin-bottom:0}
+#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
+#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
+#content{margin-bottom:.625em}
+.sect1{padding-bottom:.625em}
+@media screen and (min-width:768px){#content{margin-bottom:1.25em}
+.sect1{padding-bottom:1.25em}}
+.sect1:last-child{padding-bottom:0}
+.sect1+.sect1{border-top:1px solid #e7e7e9}
+#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
+#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
+#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
+#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
+#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
+details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
+details{margin-left:1.25rem}
+details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
+details>summary::-webkit-details-marker{display:none}
+details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
+details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
+details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
+.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
+table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
+.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
+.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
+.admonitionblock>table td.icon{text-align:center;width:80px}
+.admonitionblock>table td.icon img{max-width:none}
+.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
+.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
+.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
+.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
+.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
+.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
+.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
+.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
+.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
+@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
+@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
+.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
+.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
+.listingblock>.content{position:relative}
+.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
+.listingblock:hover code[data-lang]::before{display:block}
+.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
+.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
+.listingblock pre.highlightjs{padding:0}
+.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
+.listingblock pre.prettyprint{border-width:0}
+.prettyprint{background:#f7f7f8}
+pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
+pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
+pre.prettyprint li code[data-lang]::before{opacity:1}
+pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
+table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
+table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
+table.linenotable td.code{padding-left:.75em}
+table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
+pre.pygments span.linenos{display:inline-block;margin-right:.75em}
+.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
+.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
+.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
+.quoteblock blockquote{margin:0;padding:0;border:0}
+.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
+.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
+.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
+.verseblock{margin:0 1em 1.25em}
+.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
+.verseblock pre strong{font-weight:400}
+.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
+.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
+.quoteblock .attribution br,.verseblock .attribution br{display:none}
+.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
+.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
+.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
+.quoteblock.abstract{margin:0 1em 1.25em;display:block}
+.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
+.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
+.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
+.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
+.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
+p.tableblock:last-child{margin-bottom:0}
+td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
+td.tableblock>.content>:last-child{margin-bottom:-1.25em}
+table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
+table.grid-all>*>tr>*{border-width:1px}
+table.grid-cols>*>tr>*{border-width:0 1px}
+table.grid-rows>*>tr>*{border-width:1px 0}
+table.frame-all{border-width:1px}
+table.frame-ends{border-width:1px 0}
+table.frame-sides{border-width:0 1px}
+table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
+table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
+table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
+table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
+table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
+th.halign-left,td.halign-left{text-align:left}
+th.halign-right,td.halign-right{text-align:right}
+th.halign-center,td.halign-center{text-align:center}
+th.valign-top,td.valign-top{vertical-align:top}
+th.valign-bottom,td.valign-bottom{vertical-align:bottom}
+th.valign-middle,td.valign-middle{vertical-align:middle}
+table thead th,table tfoot th{font-weight:bold}
+tbody tr th{background:#f7f8f7}
+tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
+p.tableblock>code:only-child{background:none;padding:0}
+p.tableblock{font-size:1em}
+ol{margin-left:1.75em}
+ul li ol{margin-left:1.5em}
+dl dd{margin-left:1.125em}
+dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
+li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
+ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
+ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
+ul.unstyled,ol.unstyled{margin-left:0}
+li>p:empty:only-child::before{content:"";display:inline-block}
+ul.checklist>li>p:first-child{margin-left:-1em}
+ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
+ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
+ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
+ul.inline>li{margin-left:1.25em}
+.unstyled dl dt{font-weight:400;font-style:normal}
+ol.arabic{list-style-type:decimal}
+ol.decimal{list-style-type:decimal-leading-zero}
+ol.loweralpha{list-style-type:lower-alpha}
+ol.upperalpha{list-style-type:upper-alpha}
+ol.lowerroman{list-style-type:lower-roman}
+ol.upperroman{list-style-type:upper-roman}
+ol.lowergreek{list-style-type:lower-greek}
+.hdlist>table,.colist>table{border:0;background:none}
+.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
+td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
+td.hdlist1{font-weight:bold;padding-bottom:1.25em}
+td.hdlist2{word-wrap:anywhere}
+.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
+.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
+.colist td:not([class]):first-child img{max-width:none}
+.colist td:not([class]):last-child{padding:.25em 0}
+.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
+.imageblock.left{margin:.25em .625em 1.25em 0}
+.imageblock.right{margin:.25em 0 1.25em .625em}
+.imageblock>.title{margin-bottom:0}
+.imageblock.thumb,.imageblock.th{border-width:6px}
+.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
+.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
+.image.left{margin-right:.625em}
+.image.right{margin-left:.625em}
+a.image{text-decoration:none;display:inline-block}
+a.image object{pointer-events:none}
+sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
+sup.footnote a,sup.footnoteref a{text-decoration:none}
+sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
+#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
+#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
+#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
+#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
+#footnotes .footnote:last-of-type{margin-bottom:0}
+#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
+div.unbreakable{page-break-inside:avoid}
+.big{font-size:larger}
+.small{font-size:smaller}
+.underline{text-decoration:underline}
+.overline{text-decoration:overline}
+.line-through{text-decoration:line-through}
+.aqua{color:#00bfbf}
+.aqua-background{background:#00fafa}
+.black{color:#000}
+.black-background{background:#000}
+.blue{color:#0000bf}
+.blue-background{background:#0000fa}
+.fuchsia{color:#bf00bf}
+.fuchsia-background{background:#fa00fa}
+.gray{color:#606060}
+.gray-background{background:#7d7d7d}
+.green{color:#006000}
+.green-background{background:#007d00}
+.lime{color:#00bf00}
+.lime-background{background:#00fa00}
+.maroon{color:#600000}
+.maroon-background{background:#7d0000}
+.navy{color:#000060}
+.navy-background{background:#00007d}
+.olive{color:#606000}
+.olive-background{background:#7d7d00}
+.purple{color:#600060}
+.purple-background{background:#7d007d}
+.red{color:#bf0000}
+.red-background{background:#fa0000}
+.silver{color:#909090}
+.silver-background{background:#bcbcbc}
+.teal{color:#006060}
+.teal-background{background:#007d7d}
+.white{color:#bfbfbf}
+.white-background{background:#fafafa}
+.yellow{color:#bfbf00}
+.yellow-background{background:#fafa00}
+span.icon>.fa{cursor:default}
+a span.icon>.fa{cursor:inherit}
+.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
+.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
+.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
+.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
+.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
+.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
+.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
+.conum[data-value] *{color:#fff!important}
+.conum[data-value]+b{display:none}
+.conum[data-value]::after{content:attr(data-value)}
+pre .conum[data-value]{position:relative;top:-.125em}
+b.conum *{color:inherit!important}
+.conum:not([data-value]):empty{display:none}
+dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
+h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
+p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
+p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
+p{margin-bottom:1.25rem}
+.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
+.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
+.print-only{display:none!important}
+@page{margin:1.25cm .75cm}
+@media print{*{box-shadow:none!important;text-shadow:none!important}
+html{font-size:80%}
+a{color:inherit!important;text-decoration:underline!important}
+a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
+a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
+abbr[title]{border-bottom:1px dotted}
+abbr[title]::after{content:" (" attr(title) ")"}
+pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
+thead{display:table-header-group}
+svg{max-width:100%}
+p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
+h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
+#header,#content,#footnotes,#footer{max-width:none}
+#toc,.sidebarblock,.exampleblock>.content{background:none!important}
+#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
+body.book #header{text-align:center}
+body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
+body.book #header .details{border:0!important;display:block;padding:0!important}
+body.book #header .details span:first-child{margin-left:0!important}
+body.book #header .details br{display:block}
+body.book #header .details br+span::before{content:none!important}
+body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
+body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
+.listingblock code[data-lang]::before{display:block}
+#footer{padding:0 .9375em}
+.hide-on-print{display:none!important}
+.print-only{display:block!important}
+.hide-for-print{display:none!important}
+.show-for-print{display:inherit!important}}
+@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
+.sect1{padding:0!important}
+.sect1+.sect1{border:0}
+#footer{background:none}
+#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
+@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
+
+/* DARK MODE */
+
+@media (prefers-color-scheme: dark) {
+body,
+body .btn,
+body table,
+body th {
+	background-color: #222; !important
+	color: #e0e0e0; !important
+}
+
+body .btn {
+	box-shadow: 0 0 5px #616161; !important
+	border: 1px solid #222; !important
+}
+
+body .btn:focus {
+	box-shadow: 0 0 5px #9e9e9e; !important
+}
+
+body .theme-switcher {
+	background: url("../img/sun.svg") no-repeat center; !important
+}
+
+.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{
+color:#ff8a80;!important
+}
+.quoteblock blockquote::before{
+color:#ff8a80;!important
+}
+
+body h1,
+body h2,
+body h3,
+body h4,
+body h5,
+body h6,
+body #toctitle,
+body .sidebarblock .title,
+body .imageblock .title {
+	color: #ff8a80 !important;
+}
+
+body blockquote::before {
+	color: #d32f2f !important;
+}
+
+body code,
+body pre {
+	background-color: #2f2f2f !important;
+	color: #e0e0e0; !important
+}
+
+body .sectlevel1 li a {
+	color: #ff8a80 !important;
+}
+
+body a,
+body a code,
+body .sectlevel2 li a {
+	color: #90caf9 !important;
+}
+
+body a:hover,
+body a:hover code,
+body a code:hover,
+body .sectlevel2 li a:hover {
+	color: #42a5f5 !important;
+}
+
+body #toc,
+body .pwa-install-div {
+	background-color: #222 !important;
+}
+
+body #toc {
+	border-left-color: #212121; !important
+	border-right-color: #212121; !important
+}
+
+body .pwa-install-div {
+	box-shadow: 0 0 5px #2f2f2f; !important
+}
+
+body #pwa-install-btn {
+	box-shadow: 0 0 5px #2f2f2f; !important
+	background-color: #e0e0e0; !important
+	border: 1px solid #e0e0e0; !important
+	color: #222; !important
+}
+
+body li,
+body p,
+body .details,
+body details,
+body details summary,
+body td,
+body blockquote,
+body .attribution cite {
+	color: #e0e0e0 !important;
+}
+
+body .sidebarblock {
+	background-color: #222 !important;
+}
+
+* {
+	scrollbar-color: #818181 #333; !important
+}
+*::-webkit-scrollbar-track:hover {
+	scrollbar-color: #a1a181 #333; !important
+}
+
+
+/* code style */
+:not(pre):not([class^=L])>code{background:#2f2f2f;!important}
+kbd{background:#2f2f2f;!important}
+.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#2f2f2f;!important}
+.literalblock.output pre{color:#2f2f2f;!important}
+.prettyprint{background:#2f2f2f;!important}
+}
diff --git a/docs/config.adoc b/docs/config.adoc
index 05e58894c..c4dc4eb37 100644
--- a/docs/config.adoc
+++ b/docs/config.adoc
@@ -1,29 +1,91 @@
-= Configuration
-:toc:
-:toc-placement!:
-:toc-title!:
-
-This document describes how to create a kanata configuration file. The kanata
-configuration file will determine your keyboard behaviour upon running kanata.
+= Kanata Configuration Guide
+:last-update-label!:
+ifndef::env-github[]
+:toc: left
+endif::[]
+:stylesheet: config-stylesheet.css
+
+This document describes how to create a kanata configuration file.
+The kanata configuration file will determine your keyboard behaviour upon running kanata.
+
+== How to read the guide
+
+ifdef::env-github[]
+See the triple bullet-lines at the upper right
+to open or close a Table of Contents sidebar.
+
+You may want to view the guide rendered to HTML.
+https://jtroo.github.io/config.html[Link to guide].
+endif::[]
+
+The **Reference** sections are shorter
+and are intended for reviewing how precisely to configure different sections.
+The **Description** sections are longer
+and contain more details such as advice, motivation, and examples.
+
+The configuration guide you are reading
+may have content not applicable to the version you are using.
+See below for links to specific guide versions.
+
+ifdef::env-github[]
+* https://github.com/jtroo/kanata/blob/v1.11.0/docs/config.adoc[v1.11.0]
+* https://github.com/jtroo/kanata/blob/v1.10.1/docs/config.adoc[v1.10.1]
+* https://github.com/jtroo/kanata/blob/v1.10.0/docs/config.adoc[v1.10.0]
+* https://github.com/jtroo/kanata/blob/v1.9.0/docs/config.adoc[v1.9.0]
+* https://github.com/jtroo/kanata/blob/v1.8.1/docs/config.adoc[v1.8.1]
+* https://github.com/jtroo/kanata/blob/v1.8.0/docs/config.adoc[v1.8.0]
+endif::[]
+ifndef::env-github[]
+* link:/config-1.11.0.html[v1.11.0]
+* link:/config-1.10.1.html[v1.10.1]
+* link:/config-1.10.0.html[v1.10.0]
+* link:/config-1.9.0.html[v1.9.0]
+* link:/config-1.8.1.html[v1.8.1]
+* link:/config-1.8.0.html[v1.8.0]
+endif::[]
+
+== Preamble
 
 The configuration file uses S-expression syntax from Lisps. If you are not
 familiar with any Lisp-like programming language, do not be too worried. This
 document will hopefully be a sufficient guide to help you customize your
 keyboard behaviour to your exact liking.
 
-If you have any questions or confusions, feel free to file an issue or start a
-discussion. If you have ideas for how to improve this document or any other
-part of the project, please be welcome to make a pull request or file an issue.
+Useful terminology to learn early:
+[cols="1,5"]
+|===
+| string
+| A sequence of characters.
+Optionally surrounded by quotes.
+Examples: `backspace`, `"string with spaces and 1 number"`.
+
+| list
+| A sequence of strings or nested lists within round brackets.
+List items are separated by any amount of whitespace characters,
+or by round brackets.
+Examples: `(lrld-num 1)`, `(tap-dance 200 (f1(unicode 😀)f2(unicode 🙂)))`.
+|===
+
+If you have any questions, confusions, suggestions, etc., feel free to
+https://github.com/jtroo/kanata/discussions/new/choose[start a discussion]
+or https://github.com/jtroo/kanata/issues/new/choose[file an issue].
+If you have ideas for how to improve this document or any other part of the project,
+please be welcome to make a pull request or file an issue.
+
+== Forcefully exit kanata [[force-exit]]
 
-'''
+Though this isn't configuration-related,
+it may be important for you to know that pressing and holding all of the
+three following keys together at the same time will cause kanata to exit:
 
-[[table-of-contents]]
-== Table of contents
-toc::[]
+- Left Control
+- Space
+- Escape
+
+This mechanism works on the key input **before** any remappings done by kanata.
 
 [[comments]]
 == Comments
-<<table-of-contents,Back to ToC>>
 
 You can add comments to your configuration file. Comments are prefixed with two
 semicolons. E.g:
@@ -50,27 +112,58 @@ a multi-line comment block
 
 [[defsrc]]
 === defsrc
-<<table-of-contents,Back to ToC>>
 
-Your configuration file must have exactly one `defsrc` entry. This defines the
-order of keys that the `+deflayer+` entries will operate on.
+**Reference**
+
+Your configuration file must have exactly one `defsrc` list.
+This defines the order of keys that the `+deflayer+` entries will operate on.
+
+.Syntax:
+[source]
+----
+(defsrc $key1 $key2 ... $keyN)
+----
+
+[cols="1,6"]
+|===
+| `$key`
+| The name of a key. This can be a default key name or one defined in <<deflocalkeys>>.
+When physically pressing this input key, the action defined
+at the same order position on the active layer will activate.
+|===
+
+**Description**
 
-A `defsrc` entry is composed of `defsrc` followed by key names that are
-separated by whitespace.
+The `defsrc` configuration entry defines which of your key inputs
+will be processed by kanata and how the keys map to defined layers.
+Keys excluded from `defsrc` will not be processed by Kanata
+unless you have `process-unmapped-keys yes` in <<introduction-defcfg,defcfg>>.
 
-It should be noted that the `defsrc` entry is treated as a long sequence; the
-amount of whitespace (spaces, tabs, newlines) are not relevant. You may use
-spaces, tabs, or newlines however you like to visually format `defsrc` to your
-liking.
+Keys not processed by Kanata has implications on various actions.
+For example:
 
-The the primary source of all key names is the
-https://github.com/jtroo/kanata/blob/main/src/keys/mod.rs[str_to_oscode]
-function in the source code. Please feel free to file an issue if you're unable
-to find the key you're looking for.
+- Pressing an excluded key will type a letter
+while a prior `tap-hold` decision is still pending,
+resulting in potentially incorrect results.
+- Excluded keys do not trigger early activation
+in actions such as `tap-hold-press` or `tap-dance`
+- Excluded keys cannot be read by `fork` or `switch` logic.
+
+The `defsrc` entry is treated as a long sequence.
+The amount of whitespace (spaces, tabs, newlines) are not relevant.
+You may use spaces, tabs, or newlines however you like
+to visually format `defsrc` to your liking.
+
+The primary source of all key names are the
+`str_to_oscode` and `default_mappings` functions in
+https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[the source].
+Please feel welcome to file an issue
+if you're unable to find the key you're looking for.
 
 An example `defsrc` containing the US QWERTY keyboard keys as an
 approximately 60% keyboard layout:
 
+.Example:
 [source]
 ----
 (defsrc
@@ -82,15 +175,38 @@ approximately 60% keyboard layout:
 )
 ----
 
-For non-US keyboards, see <<non-us-keyboards,this section>>.
+Note that some keyboards have a Menu key instead of a right Meta key.
+In this case you can use `menu` instead of `rmet`.
+
+For non-US keyboards, see <<non-us-keyboards,the non-US keyboards section>>.
 
 [[deflayer]]
 === deflayer
-<<table-of-contents,Back to ToC>>
+
+**Reference**
 
 Your configuration file must have at least one `+deflayer+` entry. This defines
 how each physical key mapped in `+defsrc+` behaves when kanata runs.
 
+.Syntax:
+[source]
+----
+(deflayer $layer-name $action1 $action2 ... $actionN)
+----
+
+[cols="1,5"]
+|===
+| `$layer-name`
+| A string representing the layer name.
+This name is used to reference this layer in other actions.
+
+| `$action`
+| The action that activates while this layer is active
+when the corresponding `defsrc` input key is pressed.
+|===
+
+**Description**
+
 A `+deflayer+` configuration entry is followed by the layer name then a list of
 keys or actions. The usable key names are the same as in defsrc. Actions are
 explained further on in this document. The whitespace story is the same as with
@@ -99,11 +215,12 @@ physical key in the same sequence position defined in `+defsrc+`.
 
 The first layer defined in your configuration file will be the starting layer
 when kanata runs. Other layers can be temporarily activated or switched to
-using actions. There is currently a maximum of 25 layers allowed.
+using actions.
 
 An example `defsrc` and `deflayer` that remaps QWERTY to the Dvorak layout
 would be:
 
+.Example:
 [source]
 ----
 (defsrc
@@ -123,15 +240,114 @@ would be:
 )
 ----
 
+A <<windows-only-tray-icon,Windows tray menu build>> also allows specifying
+layer icons in `+deflayer+` and `+deflayermap+` to show in the tray menu on layer activation,
+see https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config]
+
+==== deflayermap
+
+**Reference**
+
+An alternative method for defining a layer exists: `deflayermap`.
+This method maps inputs to actions by defining input-output pairs,
+ignoring `defsrc` entirely.
+
+You will likely want to either enable <<process-unmapped-keys>>
+or define most of your keyboard keys within <<defsrc>> when using `deflayermap`.
+Otherwise many actions do not behave as intended.
+See one of the links for more context.
+
+.Syntax:
+[source]
+----
+(deflayermap ($layer-name)
+ $input1 $action1
+ $input2 $action2
+ ...
+ $inputN $actionN)
+----
+
+[cols="1,5"]
+|===
+| `$layer-name`
+| A string representing the layer name.
+This name is used to reference this layer in other actions.
+
+| `$input`
+| The input key mapped to the corresponding output.
+
+| `$action`
+| The action that activates while this layer is active
+when the corresponding input key is pressed.
+|===
+
+**Description**
+
+
+The `deflayermap` variant has the advantage of terser configuration
+when only a few keys on a layer need to be mapped.
+When practicing a new configuration, the standard `deflayer` has an advantage
+of looking more like a physical keyboard layout,
+which may be helpful to some.
+
+Within `deflayermap`, the very first item must be the layer name.
+The layer name must be in parentheses unlike with `deflayer`.
+After the layer name, the layer is configured via pairs of items:
+
+* input key
+* output action
+
+An example complete configuration that maps Caps Lock to Escape is:
+
+[source]
+----
+;; defsrc is still necessary
+(defsrc)
+(deflayermap (base-layer)
+  caps esc)
+----
+
+The input key takes the same role as `defsrc` keys.
+The output action takes the role that items in the normal `deflayer` have.
+
+As special input names,
+you can use one of `&#95;`, `&#95;&#95;`, or `&#95;&#95;&#95;` to map all
+the keys that are not explicitly mapped in the layer,
+e.g. in the example above, these affect keys other than `caps`.
+
+[cols="1,6"]
+|===
+| `&#95;`
+| Map all unmapped keys in this layer that are defined in `defsrc`.
+
+| `&#95;&#95;`
+| Map all unmapped keys in this layer that are not defined in `defsrc`.
+
+| `&#95;&#95;&#95;`
+| Map all unmapped keys in this layer.
+|===
+
+If a key is not mapped explicitly or through these wildcards, it will be implicitly mapped to a <<transparent-key,transparent key>>.
+
+**Key processing**
+
+The `$input` keys in all `deflayermap` sections will be processed by kanata, even if:
+
+* the layer is inactive
+* the key is omitted from `defsrc`
+* the `process-unmapped-keys` configuration is omitted, set to `no`, or the key is within `(all-except ...)`
+
+This is particularly relevant for the issue described in <<windows-only-windows-altgr>>.
+
 [[review-of-required-configuration-entries]]
 === Review of required configuration entries
-<<table-of-contents,Back to ToC>>
 
 If you're reading in order, you have now seen all of the required entries:
 
 * `+defsrc+`
 * `+deflayer+`
 
+[[minimal-config]]
 An example minimal configuration is:
 
 [source]
@@ -144,31 +360,115 @@ An example minimal configuration is:
 This will make kanata remap your `a b c` keys to `1 2 3`. This is almost
 certainly undesirable but is a valid configuration.
 
+NOTE: Please have a read through link:https://github.com/jtroo/kanata/blob/main/docs/platform-known-issues.adoc[the known platform issues]
+because they may have implications on what you should include/exclude in `defsrc`.
+The Windows LLHOOK I/O mechanism has the most issues by far.
+
+[[key-names]]
+== Key names for defsrc and deflayermap
+
+The source of truth for all default key names are the functions
+`str_to_oscode` and `add_default_str_osc_mappings`
+in the link:https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[keys/mod.rs file].
+
+https://www.toptal.com/developers/keycode[This online tool]
+will also work for most keys to tell you the key name.
+It will be shown as the `event.code` field in the web page
+after you press the key.
+
 [[non-us-keyboards]]
 == Non-US keyboards
-<<table-of-contents,Back to ToC>>
 
 For non-US keyboard users, you may have some keys on your keyboard with characters
-that are not allowed in `defsrc` by default, at least according to the symbol
-shown. You can use `deflocalkeys` to define additional key names that can be
-used in `defsrc`, `deflayer` and anywhere else in the configuration.
+that are not allowed in `defsrc` by default, at least according to the symbol shown
+on the physical keys.
+The two sections below can help you understand how to remap all your keys.
+
+=== Browser event.code
+
+Ensure kanata and other key remapping programs are **not** running.
+Then you can use https://www.toptal.com/developers/keycode[this online tool]
+and press the key.
+The `event.code` field tells you the key name to use in Kanata.
+Alternatively, you can read through
+https://www.w3.org/TR/uievents-code/[this reference].
+Due to the lengthy key names,
+you may want to use `deflayermap` if remapping using these key names.
+
+IMPORTANT: On Windows, you should use either `kanata_winIOv2.exe`
+or Interception when using key names according to the browser `event.code`.
+The default `kanata.exe` does not do mappings according to the browser `event.code`
+key names.
+
+NOTE: On macOS, the ISO "#" key to the left of Enter reports
+`event.code` as `Backslash` in the browser, but the operating system
+delivers it to kanata as a distinct HID usage that the regular
+`\`/`Backslash` name does not match. Use the name `non_us_pound`
+(aliases: `NonUSPound`, `nuhs`) for that physical key on macOS. If
+you want the same config to work on Linux as well, pair this with
+`deflocalkeys-linux` to map evdev code 43 to the same name.
+
+[[deflocalkeys]]
+=== deflocalkeys
+
+**Reference**
+
+You can use `deflocalkeys` to define additional key names that can be
+used in `defsrc`, `deflayer`, and anywhere else in the configuration.
+
+.Syntax:
+[source]
+----
+(deflocalkeys-$variant
+  $key-name1 $key-number1
+  $key-name2 $key-number2
+  ...
+  $key-nameN $key-numberN)
+----
 
-There are three variants of deflocalkeys:
+[cols="1,5"]
+|===
+| `$variant`
+| One of: `win winiov2 wintercept linux macos`
 
-- `deflocalkeys-win`
-- `deflocalkeys-wintercept`
-- `deflocalkeys-linux`
+| `$key-name`
+| A key name of your choice that can be used in the rest of the configuration.
 
+| `$key-number`
+| A key number that varies based on the kanata variant you are using.
+|===
 
 Only one of each deflocalkeys-* variant is allowed. The variants that are not
 applicable will be ignored, e.g. `deflocalkeys-linux` and `deflocalkeys-wintercept`
-are both ignored when using the default Windows kanata binary.
-
-You can find configurations that others have made in https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this
-document]. If you do not see your keyboard there and are not confident in using
-the available tools, please feel welcome to ask for help in a discussion or issue.
+are both ignored when using the default Windows `kanata.exe` binary.
+
+**Description**
+
+The `deflocalkeys` configurations are not strictly necessary.
+Their purpose is to help you match your physical keyboard's appearance
+to your kanata configuration,
+in the hopes it will be more readable and less confusing.
+In the underlying hardware, all keyboard positions send the same scan codes
+according to their position, regardless of what is printed on the key cap.
+The scan code names are typically referred to by the corresponding US layout name.
+It is the job of the operating system to translate the same scan code
+to the correct outputs according to the configured locale and layout.
+
+You can find configurations that others have made in
+https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this document].
+If you do not see your keyboard there and are not confident in using
+the available tools,
+please feel welcome to ask for help in a discussion or issue.
 Please contribute to the document if you are able!
 
+There are five variants of deflocalkeys:
+
+- `deflocalkeys-win`
+- `deflocalkeys-winiov2`
+- `deflocalkeys-wintercept`
+- `deflocalkeys-linux`
+- `deflocalkeys-macos`
+
 .Example:
 [source]
 ----
@@ -176,6 +476,10 @@ Please contribute to the document if you are able!
   ì 187
 )
 
+(deflocalkeys-winiov2
+  ì 187
+)
+
 (deflocalkeys-wintercept
   ì 187
 )
@@ -184,6 +488,10 @@ Please contribute to the document if you are able!
   ì 13
 )
 
+(deflocalkeys-macos
+  ì 13
+)
+
 (defsrc
   grv  1    2    3    4    5    6    7    8    9    0    -    ì    bspc
 )
@@ -192,34 +500,44 @@ Please contribute to the document if you are able!
 The number used for a custom key represents the converted value for an OsCode in
 base 10. This differs between Windows-hooks, Windows-interception, and Linux.
 
+Running kanata with the `--debug` flag lets you read the correct number,
+shown in parenthesis of `code` in the `KeyEvent` log lines.
+
+It also possible to use native tools, as described below.
+
 In Linux, `evtest` will give the correct number for the physical key you press.
 
 In Windows using the default hook mechanism, the non-interception version of the
-keyboard tester in the kanata repository will give the correct number.
-(https://github.com/jtroo/kanata/releases/tag/win-keycode-tester-v0.2.0[prebuilt binary])
+keyboard tester in the kanata repository will give the correct number
+in the `code: <number>` section.
+(https://github.com/jtroo/kanata/releases/tag/win-keycode-tester-v0.3.0[prebuilt binary])
+
+In Windows uning `winIOv2`, the winIOv2 executable variant
+will give the correct number in the `code: <number>` section.
 
 In Windows using Interception, the interception version of the keyboard tester
-will give the correct number. Between the hook and interception versions, some
+will give the correct number i the `num: <number>` section.
+Between the hook and interception versions, some
 keys may agree but others may not; do be aware that they are **not** compatible!
 
+However, Interception and winIOv2 should generally agree with each other.
+
 Ideas for improving the user-friendliness of this system are welcome! As
 mentioned before, please ask for help in an issue or discussion if needed, and
-help with https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this document] is very welcome so that future
-users can have an easier time 🙂.
-
-[[optional-defcfg-entries]]
-== Optional defcfg entries
+help with https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this document]
+is very welcome so that future users can have an easier time 🙂.
 
-[[defcfg]]
-=== defcfg
-<<table-of-contents,Back to ToC>>
+[[introduction-defcfg]]
+== Introduction to defcfg
 
 Your configuration file may include a single `defcfg` entry.
+The `defcfg` can be empty or omitted.
+There are options that change kanata's behaviour,
+but this introduction will introduce
+only the most prevalent entry: `process-unmapped-keys`.
+All other options can be found later in the <<optional-defcfg-options>> section.
 
-It can be empty but there are options that can change kanata's behaviour that
-will be described in this section.
-
-.Example:
+.Example of an empty defcfg:
 [source]
 ----
 (defcfg)
@@ -227,707 +545,625 @@ will be described in this section.
 
 [[process-unmapped-keys]]
 === process-unmapped-keys
-<<table-of-contents,Back to ToC>>
 
-Enabling this configuration makes kanata process keys that are not in defsrc.
-This is useful if you are only mapping a few keys in defsrc instead of most of
-the keys on your keyboard.
+The `process-unmapped-keys` option in `defcfg` is probably the most
+generally impactful option.
+Enabling this configuration makes kanata process keys
+that are not defined in `defsrc`.
+This might be useful
+if you are only mapping a few keys in defsrc
+instead of most of the keys on your keyboard.
 
-Without this, some actions like `+rpt+`, `+tap-hold-release+`, `+one-shot+`,
-will not work correctly for subsequent key presses that are not in defsrc.
+By default, keys excluded from `defsrc` will not work in various scenarios.
+Some examples:
 
-This is disabled by default. The reason this is not enabled by default is
-because some keys may not work correctly if they are intercepted. For example,
-see the <<windows-only-windows-altgr>> option below.
+- The early hold for prior `+tap-hold-press+` actions will not
+- Prior `+one-shot+` actions will not be released
+- `fork` and `switch` logic will not see the key
+
+This option is disabled by default.
+The reason this is not enabled by default
+is because some keys may not work correctly if they are intercepted.
+A known issue being AltGr/ralt/Right Alt; see <<windows-only-windows-altgr>>.
 
 .Example:
 [source]
 ----
-(defcfg
-  process-unmapped-keys yes
-)
+(defcfg process-unmapped-keys yes)
+(defcfg process-unmapped-keys (all-except lctl ralt))
 ----
 
-[[danger-enable-cmd]]
-=== danger-enable-cmd
-<<table-of-contents,Back to ToC>>
-
-This option can be used to enable the `cmd` action in your configuration. The
-`+cmd+` action allows kanata to execute programs with arguments passed to them.
-
-This requires using a kanata program that is compiled with the `cmd` action
-enabled. The reason for this is so that if you choose to, there is no way for
-kanata to execute arbitrary programs even if you download some random
-configuration from the internet.
+== Aliases and variables[[aliases-and-vars]]
 
-This configuration is disabled by default and can be enabled by giving it the
-value `yes`.
+Before learning about actions,
+it will be useful to first learn about aliases and variables.
 
-.Example:
-[source]
-----
-(defcfg
-  danger-enable-cmd yes
-)
-----
+[[aliases]]
+=== Aliases
 
-[[sequence-timeout]]
-=== sequence-timeout
-<<table-of-contents,Back to ToC>>
+**Reference**
 
-This option customizes the key sequence timeout (unit: ms). Its default value
-is 1000. The purpose of this item is explained in <<sequences>>.
+Using the `defalias` configuration entry, you can introduce a shortcut label
+for an action.
 
-.Example:
+.Syntax:
 [source]
 ----
-(defcfg
-  sequence-timeout 2000
-)
+(defalias
+  $alias-name1 $action1
+  $alias-name2 $action2
+  ...
+  $alias-nameN $actionN)
 ----
 
-[[sequence-input-mode]]
-=== sequence-input-mode
-<<table-of-contents,Back to ToC>>
-
-This option customizes the key sequence input mode. Its default value when not
-configured is `hidden-suppressed`.
+[cols="1,5"]
+|===
+| `$alias-name`
+| The chosen shortcut label for the action.
+This shortcut label can be used in the rest of
+the configuration by prefixing it with the `@`
+character.
 
-The options are:
+| `$action`
+| The ouput action used wherever the alias name is referenced.
+|===
 
-- `visible-backspaced`: types sequence characters as they are inputted. The
-  typed characters will be erased with backspaces for a valid sequence termination.
-- `hidden-suppressed`: hides sequence characters as they are typed. Does not
-  output the hidden characters for an invalid sequence termination.
-- `hidden-delay-type`: hides sequence characters as they are typed. Outputs the
-  hidden characters for an invalid sequence termination either after a
-  timeout or after a non-sequence key is typed.
+**Description**
 
-For `visible-backspaced` and `hidden-delay-type`, a sequence leader input will
-be ignored if a sequence is already active. For historical reasons, and in case
-it is desired behaviour, a sequence leader input using `hidden-suppressed` will
-reset the key sequence.
+The `defalias` entry reads pairs of items in a sequence
+where the first item in the pair is the alias name and the second item is the
+action it can be substituted for.
 
-See <<sequences>> for more about sequences.
+A list is a sequence of strings
+or nested lists separated by whitespace,
+surrounded by parentheses.
+All of the configuration entries we've looked at so far are lists;
+`defalias` is where we'll first see nested lists in this guide.
 
 .Example:
 [source]
 ----
-(defcfg
-  sequence-input-mode visible-backspaced
+(defalias
+  ;; tap for caps lock, hold for left control
+  cap (tap-hold 200 200 caps lctl)
 )
 ----
 
+This alias can be used in `deflayer` as a substitute for the long action. The
+alias name is prefixed with `@` to signify that it's an alias as opposed to a
+normal key.
 
-[[sequence-backtrack-modcancel]]
-=== sequence-backtrack-modcancel
-<<table-of-contents,Back to ToC>>
-
-This option customizes the behaviour of key sequences
-when modifiers are used.
-The default is `yes` and can be overridden to `no` if desired.
+[source]
+----
+(deflayer example
+  @cap a s d f
+)
+----
 
-Setting it to `yes` allows both `fk1` and `fk2` to be activated
-in the following configuration, but with `no`,
-`fk1` will be impossible to activate
+You may have multiple `defalias` entries and multiple aliases within a single
+`defalias`. Aliases may also refer to other aliases that were defined earlier
+in the configuration file.
 
+.Example:
+[source]
 ----
-(defseq
-  fk1 (lsft a b)
-  fk2 (S-(c d))
+(defalias one (tap-hold 200 200 caps lctl))
+(defalias two (tap-hold 200 200 esc lctl))
+(defalias
+  three C-A-del ;; Ctrl+Alt+Del
+  four (tap-hold 200 200 @three ralt)
 )
 ----
 
-See <<sequences>> for more about sequences and
-https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[this document]
-for more context about this specific configuration.
+You can choose to put actions without aliasing them right into `deflayer`.
+However, for long actions it is recommended not to do so to keep a nice visual
+alignment. Visually aligning your `deflayer` entries will hopefully make your
+configuration file easier to read.
 
 .Example:
 [source]
 ----
-(defcfg
-  sequence-backtrack-modcancel no
+(deflayer example
+  ;; this is equivalent to the previous deflayer example
+  (tap-hold 200 200 caps lctl) a s d f
 )
 ----
 
-[[log-layer-changes]]
-=== log-layer-changes
-<<table-of-contents,Back to ToC>>
+[[variables]]
+=== Variables
 
-By default, kanata will log layer changes. However, logging has some processing
-overhead. If you do not care for the logging, you can choose to disable it.
+**Reference**
 
-.Example:
+Using the `defvar` configuration entry,
+you can introduce a shortcut label for an arbitrary string or list.
+
+.Syntax:
 [source]
 ----
-(defcfg
-  log-layer-changes no
-)
+(defvar
+  $var-name1 $var-value1
+  $var-name2 $var-value2
+  ...
+  $var-nameN $var-valueN)
 ----
 
-[[delegate-to-first-layer]]
-== delegate-to-first-layer
-<<table-of-contents,Back to ToC>>
+[cols="1,5"]
+|===
+| `$var-name`
+| The chosen shortcut label for the string or list.
+This shortcut label can be used in the rest of the
+configuration by prefixing it with `$`.
 
+| `$var-value`
+| An arbitrary string or list that will be substituted
+wherever the variable is used.
 
-By default, transparent keys on layers
-will delegate to the corresponding defsrc key
-when found on a layer activated by `layer-switch`.
+|===
 
-This config entry changes the behaviour
-to delegate to the action in the same position on the first layer defined
-in the configuration, which is the active layer on startup.
+**Description**
 
-For more context, see https://github.com/jtroo/kanata/issues/435.
+Unlike an alias, a variable does not need to be a valid standalone action.
+In other words,
+a variable can be used as components of actions.
+
+The most common use case is to define common number strings
+for actions such as `tap-hold`, `tap-dance`, and `one-shot`.
+
+Similar to how `defalias` works,
+`defvar` reads pairs of items in a sequence
+where the first item in the pair is the variable name
+and the second item is a string or list.
+Variables are allowed to refer to previously defined variables.
+
+Variables can be used to substitute most values.
+Some notable exceptions are:
+
+- variables cannot be used in `defcfg`, `defsrc`, or `deflocalkeys`
+- variables cannot be used to substitute an action name
+
+Variables are referred to by prefixing their name with `$`.
 
 .Example:
 [source]
 ----
-(defcfg
-  delegate-to-first-layer yes
+(defvar
+  tap-repress-timeout   100
+  hold-timeout  200
+  tt $tap-repress-timeout
+  ht $hold-timeout
+)
+
+(defalias
+  th1 (tap-hold $tt $ht caps lctl)
+  th2 (tap-hold $tt $ht spc  lsft)
 )
 ----
 
-[[linux-only-linux-dev]]
-=== Linux only: linux-dev
-<<table-of-contents,Back to ToC>>
+[[concat-in-defvar]]
+==== concat in defvar
 
-By default, kanata will try to detect which input devices are keyboards and try
-to intercept them all. However, you may specify exact keyboard devices from the
-`/dev/input` directories using the `linux-dev` configuration.
+Within the second item of `defvar`,
+a list that begins with the special keyword `concat` will concatenate all
+subsequent items in the list together into a single string value.
+Without using `concat`, lists are saved as-is.
 
 .Example:
 [source]
 ----
-(defcfg
-  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
+(defvar
+  rootpath "/home/myuser/mysubdir"
+  ;; $otherpath will be the string: /home/myuser/mysubdir/helloworld
+  otherpath (concat $rootpath "/helloworld")
 )
 ----
 
-If you want to specify multiple keyboards, you can separate the paths with a
-colon `+:+`.
+[[actions]]
+== Actions
 
-.Example:
-[source]
-----
-(defcfg
-  linux-dev /dev/input/dev1:/dev/input/dev2
-)
-----
+The actions kanata provides are what make it truly customizable.
+This section explains the available actions.
 
-Due to using the colon to separate devices, if you have a device with colons in
-its file name, you must escape those colons with backslashes:
+[[live-reload]]
+=== Live reload
 
-[source]
-----
-(defcfg
-  linux-dev /dev/input/path-to\:device
-)
-----
+**Reference**
 
-[[linux-only-linux-dev-names-include]]
-=== Linux only: linux-dev-names-include
-<<table-of-contents,Back to ToC>>
+Live reload variants:
 
-In the case that `linux-dev` is omitted,
-this option defines a list of device names that should be included.
-Device names that do not exist in the list will be ignored.
-This option is parsed identically to `linux-dev`.
+[cols="1,5"]
+|===
+| `lrld`
+| String action that live-reloads the currently-used configuration file.
 
-Kanata will print device names on startup with log lines that look like below:
+| `lrld-next`
+| String action that live-reloads the configuration file specified
+consecutively later in the command line order.
+Cycles to the first-specified file
+if currently using the last file specified.
 
-----
-registering /dev/input/eventX: "Name goes here"
-----
+| `lrld-prev`
+| String action that live-reloads the configuration file specified
+consecutively earlier in the command line order.
+Cycles to the last-specified file
+if currently using the first file specified.
+
+| `(lrld-num $n)`
+| List action that live-reloads the n'th file
+as specified in the command line order.
+The first file specified is `n=1`.
+|===
+
+Live reload does not read or apply changes to device-related configurations.
+Examples of device-related configurations:
+`linux-dev`, `macos-dev-names-include`, `linux-use-trackpoint-property`,
+`windows-only-windows-interception-keyboard-hwids`.
+
+**Description**
+
+You can put the `+lrld+` action onto a key to live reload your configuration file.
+If kanata can't parse the file,
+the previous configuration will continue to be used.
+When live reload is activated,
+the active kanata layer will be the first `deflayer` defined in the configuration.
 
 .Example:
 [source]
 ----
-(defcfg
-  linux-dev-names-include "Device 1 name:Device \:2\: Name"
+(deflayer has-live-reload
+  lrld a s d f
 )
 ----
 
-[[linux-only-linux-dev-names-exclude]]
-=== Linux only: linux-dev-names-exclude
-<<table-of-contents,Back to ToC>>
-
-In the case that `linux-dev` is omitted,
-this option defines a list of device names that should be excluded.
-This option is parsed identically to `linux-dev`.
+There are variants of `lrld`: `lrld-prev` and `lrld-next`. These will cycle
+through different configuration files that you specify on kanata's startup.
+The first configuration file specified will be the one loaded on startup.
+The prev/next variants can be used with shortened names of `lrpv` and `lrnx` as
+well.
 
-The `linux-dev-names-include and `linux-dev-names-exclude` options
-are not mutually exclusive
-but in practice it probably only makes sense to use one and not both.
+Another variant is the list action `lrld-num`.
+This reloads the configuration file specified by the number,
+according to the order that the configuration file arguments
+are passed into kanata's startup command.
 
 .Example:
 [source]
 ----
-(defcfg
-  linux-dev-names-exclude "Device 1 name:Device \:2\: Name"
+(deflayer has-live-reloads
+  lrld lrpv lrnx (lrld-num 3)
 )
 ----
 
-[[linux-only-linux-continue-if-no-devs-found]]
-=== Linux only: linux-continue-if-no-devs-found
-<<table-of-contents,Back to ToC>>
-
-By default, kanata will crash if no input devices are found. You can change
-this behaviour by setting `linux-continue-if-no-devs-found`.
+Example specifying multiple config files in the command line:
 
-.Example:
 [source]
 ----
-(defcfg
-  linux-continue-if-no-devs-found yes
-)
+kanata -c startup.cfg -c 2nd.cfg -c 3rd.cfg
 ----
 
-[[linux-only-linux-unicode-u-code]]
-=== Linux only: linux-unicode-u-code
-<<table-of-contents,Back to ToC>>
+Given the above startup command,
+activating `(lrld-num 2)` would reload the `2nd.cfg` file.
 
-Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value,
-then pressing Enter. However, if you do remapping in userspace, e.g. via
-xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u"
-after the userspace remapping. This will be likely if you use non-US,
-non-European keyboards on top of kanata. For unicode to work, kanata needs to
-use the keycode that outputs the keysym "u", which might not be the keycode
-"U".
 
-You can use `evtest` or `kanata --debug`, set your userspace key remapping,
-then press the key that outputs the keysym "u" to see which underlying keycode
-is sent. Then you can use this configuration to change kanata's behaviour.
+[[layer-switch]]
+=== layer-switch
 
-.Example:
+**Reference**
+
+A list action that changes the active base layer.
+
+.Syntax:
 [source]
 ----
-(defcfg
-  linux-unicode-u-code v
-)
+(layer-switch $layer-name)
 ----
 
-[[linux-only-linux-unicode-termination]]
-=== Linux only: linux-unicode-termination
-<<table-of-contents,Back to ToC>>
+[cols="1,5"]
+|===
+| `$layer-name`
+| Layer name to switch to.
+|===
 
-Unicode on Linux terminates with the Enter key by default. This may not work in
-some applications. The termination is configurable with the following options:
 
-- `enter`
-- `space`
-- `enter-space`
-- `space-enter`
+**Description**
+
+This action allows you to switch to another "base" layer.
+This is permanent until a `layer-switch` to another layer is activated.
+The concept of a base layer makes more sense
+when looking at the next action: `layer-while-held`.
+
+This action accepts a single subsequent string which must be a layer name
+defined in a `deflayer` entry.
 
 .Example:
 [source]
 ----
-(defcfg
-  linux-unicode-termination space
-)
+(defalias dvk (layer-switch dvorak))
 ----
 
-[[linux-only-x11-repeat-rate]]
-=== Linux only: linux-x11-repeat-delay-rate
-<<table-of-contents,Back to ToC>>
+[[layer-while-held]]
+=== layer-while-held
 
-On Linux, you can tell kanata to run `xset r rate <delay> <rate>`
-on startup and on live reload
-via the configuration item `linux-only-x11-repeat-rate`.
-This takes two numbers separated by a comma.
-The first number is the delay in ms
-and the second number is the repeat rate in repeats/second.
+**Reference**
 
-This configuration item does not affect Wayland or no-desktop environments.
+A list action that changes the active layer while the key is held.
 
-.Example:
+.Syntax:
 [source]
 ----
-(defcfg
-  linux-x11-repeat-delay-rate 400,50
-)
+(layer-while-held $layer-name)
 ----
 
-[[windows-only-windows-altgr]]
-=== Windows only: windows-altgr
-<<table-of-contents,Back to ToC>>
+[cols="1,5"]
+|===
+| `$layer-name`
+| Layer name to activate while key is held.
+|===
 
-There is an option for Windows to help mitigate the strange behaviour of AltGr
-(ralt) if you're using that key in your defsrc. This is applicable for many
-non-US layouts. You can use one of the listed values to change what kanata does
-with the key:
+**Description**
 
-* `cancel-lctl-press`
-** This will remove the `lctl` press that is generated alonside `ralt`
-* `add-lctl-release`
-** This adds an `lctl` release when `ralt` is released
+This action allows you to temporarily change to another layer while the key
+remains held. When the key is released, you go back to the currently active
+"base" layer.
+
+This action accepts a single subsequent string which must be a layer name
+defined in a `deflayer` entry.
 
 .Example:
 [source]
 ----
-(defcfg
-  windows-altgr add-lctl-release
-)
+(defalias nav (layer-while-held navigation))
 ----
 
-For more context, see: https://github.com/jtroo/kanata/issues/55.
+You may also use `layer-toggle` in place of `layer-while-held`; they behave
+exactly the same. The `layer-toggle` name is slightly shorter but is a bit
+inaccurate with regards to its meaning.
 
-NOTE: Even with these workarounds, putting `+lctl+`+`+ralt+` in your defsrc may not
-work properly with other applications that also use keyboard interception.
-Known application with issues: GWSL/VcXsrv
+[[transparent-key]]
+=== Transparent key
 
-[[windows-only--windows-interception-mouse-hwid]]
-=== Windows only: windows-interception-mouse-hwid
-<<table-of-contents,Back to ToC>>
+**Reference**
 
-This defcfg item allows you to intercept mouse buttons for a specific mouse
-device. This only works with the Interception driver (the -wintercept variants
-of the binary).
+[cols="1,5"]
+|===
+| `+_+`
+| String action that activates the action of the layer "underneath" the active one.
+|===
 
-The intended use case for this is for laptops such as a Thinkpad, which have
-mouse buttons that may be desirable to activate kanata actions with.
+**Description**
 
-To know what numbers to put into the string, you can run the variant with this
-defcfg item defined with any numbers. Then when a button is first pressed on
-the mouse device, kanata will print its hwid in the log; you can then
-copy-paste that into this configuration entry. If this defcfg item is not
-defined, the log will not print.
+Kanata maintains a layer stack consisting in order of:
 
-https://github.com/jtroo/kanata/issues/108[Relevant issue].
+* a stack of temporary layers, where each `layer-while-held` adds one layer on top
+* the base layer, manipulated by `layer-switch`
+* if `delegate-to-first-layer` is enabled: the first layer defined by `deflayer` or `deflayermap`
+* `defsrc`
+
+A single underscore `+_+` acts as a "transparent" key in the current layer.
+It will invoke the action assigned to the same key position on the next layer in the stack.
+
+NOTE: If `delegate-to-first-layer` is enabled and the base layer is currently set to the first defined layer, a transparent key on the base layer will fall through directly to `defsrc`.
+
+[[use-defsrc]]
+=== use-defsrc
+
+**Reference**
+
+[cols="1,6"]
+|===
+| `use-defsrc`
+| String action that outputs the corresponding `defsrc` input key.
+|===
+
+**Description**
+
+A similar concept to transparent key is the `+use-defsrc+` action.
+When activated, the underlying `defsrc` key will be the output action.
 
 .Example:
 [source]
 ----
-(defcfg
-  windows-interception-mouse-hwid "70, 0, 60, 0"
-)
+(defsrc a b c d)
+(defalias src use-defsrc)
+(deflayer remap-only-c-to-d
+  _ _ d @src)
 ----
 
-[[using-multiple-defcfg-entries]]
-=== Using multiple defcfg entries
-<<table-of-contents,Back to ToC>>
+[[no-op]]
+=== No-op
+
+**Reference**
 
-The `defcfg` entry is treated as a list with pairs of strings. For example:
+[cols="1,6"]
+|===
+| `XX`
+| String action that will output nothing.
+|===
+
+**Description**
 
+You may use the action `+XX+` as a "no operation" key, meaning pressing the key
+will do nothing. This might be desirable in place of a transparent key on a
+layer that is not fully mapped so that a key that is intentionally not mapped
+will do nothing as opposed to typing a letter.
+
+Alternatively you can use `+✗+` `+∅+` `+•+` to mean no-op.
+
+.Example:
 [source]
 ----
-(defcfg a 1 b 2)
+(deflayer contains-no-ops
+  XX ✗ ∅ •)
 ----
 
-This will be treated as configuration `a` having value `1` and configuration
-`b` having value `2`.
+[[unicode]]
+=== Unicode
 
-An example defcfg containing all of the options is shown below. It should be
-noted options that are Linux-only or Windows-only will be ignored when used on
-a non-applicable operating system.
+**Reference**
+
+List action that outputs a single unicode codepoint.
+The unicode codepoint will not be repeatedly typed if you hold the key down.
 
+.Syntax:
 [source]
 ----
-;; Don't actually use this exact configuration,
-;; it's almost certainly not what you want.
-(defcfg
-  process-unmapped-keys yes
-  danger-enable-cmd yes
-  sequence-timeout 2000
-  sequence-input-mode visible-backspaced
-  sequence-backtrack-modcancel no
-  log-layer-changes no
-  delegate-to-first-layer yes
-  linux-dev /dev/input/dev1:/dev/input/dev2
-  linux-dev-names-include "Name 1:Name 2"
-  linux-dev-names-exclude "Name 3:Name 4"
-  linux-continue-if-no-dev-found yes
-  linux-unicode-u-code v
-  linux-unicode-termination space
-  linux-x11-repeat-delay-rate 400,50
-  windows-altgr add-lctl-release
-  windows-interception-mouse-hwid "70, 0, 60, 0"
-)
+(unicode $unicode-codepoint)
 ----
 
-[[aliases-and-vars]]
-== Aliases and variables
-<<table-of-contents,Back to ToC>>
+[cols="1,4"]
+|===
+| `$unicode-codepoint`
+| One unicode codepoint.
+Be warned that many emojis/glyphs/graphemes
+are composed of multiple codepoints.
+|===
 
-Before learning about actions,
-it will be useful to first learn about aliases and variables.
+**Description**
 
-[[aliases]]
-=== Aliases
-<<table-of-contents,Back to ToC>>
+NOTE: The <<clipboard-actions>> may output unicode characters more consistently.
 
-Using the `defalias` configuration entry, you can introduce a shortcut label
-for an action.
+The `+unicode+` (or `+🔣+`) action accepts a single unicode character (but not
+a composed character, so 🤲, but not 🤲🏿),
+or a single unicode number prefixed with `U+`.
+For example, both of these actions are the same:
+- `(unicode 🚆)`
+- `(unicode U+1F686)`
 
-Similar to how `defcfg` works, `defalias` reads pairs of items in a sequence
-where the first item in the pair is the alias name and the second item is the
-action it can be substituted for. However, unlike `+defcfg+`, the second item
-in `defalias` may be a "list" as opposed to a single string like it was in
-`defcfg`.
+If you want to output a glyph that is composed of multiple codepoints,
+you can use <<macro>> with multiple `unicode` actions.
 
-A list is a sequence of strings separated by whitespace, surrounded by
-parentheses. All of the configuration entries we've looked at so far are lists;
-`defalias` is where we'll first see nested lists in this guide.
+You may use a unicode character as an alias if desired or in its simplified form `+🔣😀+`
+(vs the usual `+(🔣 😀)+`).
+
+NOTE: The unicode action may not be correctly accepted by the active
+application.
+
+NOTE: If using Linux, make sure to look at the
+<<linux-only-linux-unicode-u-code,unicode behaviour customization>> in defcfg.
+Furthermore, on Wayland the unicode mechanism may be broken entirely.
+On Wayland you can install then use the `wtype` program,
+using <<cmd, cmd>> to execute it.
+For example: `(cmd wtype á)`
 
 .Example:
 [source]
 ----
 (defalias
-  ;; tap for caps lock, hold for left control
-  cap (tap-hold 200 200 caps lctl)
+  sml (unicode 😀)
+  😀 (🔣 😀)
+  🙁 (unicode 🙁)
+)
+(deflayer has-happy-sad
+  @sml @🙁 @😀 🔣😀 d f
 )
 ----
 
-This alias can be used in `deflayer` as a substitute for the long action. The
-alias name is prefixed with `@` to signify that it's an alias as opposed to a
-normal key.
+If you want output parentheses `+( )+` via unicode you can quote them.
 
+.Example with parentheses
 [source]
 ----
-(deflayer example
-  @cap a s d f
+(defalias
+  lp (unicode "(")
+  rp (unicode ")")
 )
 ----
 
-You may have multiple `defalias` entries and multiple aliases within a single
-`defalias`. Aliases may also refer to other aliases that were defined earlier
-in the configuration file.
+If you want to output double quotes via unicode
+you need a special quoting syntax.
 
-.Example:
+.Example use of double-quote within a string
 [source]
 ----
-(defalias one (tap-hold 200 200 caps lctl))
-(defalias two (tap-hold 200 200 esc lctl))
 (defalias
-  three C-A-del ;; Ctrl+Alt+Del
-  four (tap-hold 200 200 @three ralt)
+  dq (unicode r#"""#)
 )
 ----
 
-You can choose to put actions without aliasing them right into `deflayer`.
-However, for long actions it is recommended not to do so to keep a nice visual
-alignment. Visually aligning your `deflayer` entries will hopefully make your
-configuration file easier to read.
+[[output-chordscombos]]
+=== Output chords/combos
 
-.Example:
-[source]
-----
-(deflayer example
-  ;; this is equivalent to the previous deflayer example
-  (tap-hold 200 200 caps lctl) a s d f
-)
-----
+**Reference**
 
-[[variables]]
-=== Variables
-<<table-of-contents,Back to ToC>>
+Prefixing a known key name with the following strings
+will output the key alongside the specified modifier.
+Multiple prefixes can be combined to add more modifiers
+to the same key output.
+Duplicate prefixes are not allowed.
 
-Using the `defvar` configuration entry,
-you can introduce a shortcut label for an arbitrary string or list.
-Unlike an alias, a variable does not need to be a valid standalone action.
-In other words,
-a variable can be used as components of actions.
+[cols="1,6"]
+|===
+| `+C-+`
+| Left Control
 
-The most common use case is to define common number strings
-for actions such as `tap-hold`, `tap-dance`, and `one-shot`.
+| `+RC-+`
+| Right Control
 
-Similar to how `defalias` works,
-`defvar` reads pairs of items in a sequence
-where the first item in the pair is the variable name
-and the second item is a string or list.
-Variables are allowed to refer to previously defined variables.
+| `+A-+`
+| Left Alt
 
-Variables can be used to substitute most values.
-Some notable exceptions are:
+| `+RA-+`
+| Right Alt, also known as AltGr
 
-- variables cannot be used in `defcfg`, `defsrc`, or `deflocalkeys`
-- variables cannot be used to substitute a layer name
-- variables cannot be used to substitute an action name
+| `+AG-+`
+| Also means Right Alt/AltGr
 
-Variables are referred to by prefixing their name with `$`.
+| `+S-+`
+| Left Shift
 
-.Example:
-[source]
-----
-(defvar
-  tap-timeout   100
-  hold-timeout  200
-  tt $tap-timeout
-  ht $hold-timeout
-)
+| `+RS-+`
+| Right Shift
 
-(defalias
-  th1 (tap-hold $tt $ht caps lctl)
-  th2 (tap-hold $tt $ht spc  lsft)
-)
-----
-
-[[actions]]
-== Actions
-
-The actions kanata provides are what make it truly customizable. This section
-explains the available actions.
-
-[[live-reload]]
-=== Live reload
-<<table-of-contents,Back to ToC>>
-
-You can put the `+lrld+` action onto a key to live-reload your configuration
-file. If kanata can't parse the file, it will continue using the previous
-configuration.
-
-.Example:
-[source]
-----
-(deflayer has-live-reload
-  lrld a s d f
-)
-----
-
-There are variants of `lrld`: `lrld-prev` and `lrld-next`. These will cycle
-through different configuration files that you specify on kanata's startup.
-The first configuration file specified will be the one loaded on startup.
-The prev/next variants can be used with shortened names of `lrpv` and `lrnx` as
-well.
-
-.Example:
-[source]
-----
-(deflayer has-live-reloads
-  lrld lrpv lrnx
-)
-----
-
-Example specifying multiple config files in the command line:
-
-[source]
-----
-kanata -c startup.cfg -c 2nd.cfg -c 3rd.cfg
-----
-
-[[layer-switch]]
-=== layer-switch
-<<table-of-contents,Back to ToC>>
-
-This action allows you to switch to another "base" layer. This is permanent
-until a `layer-switch` to another layer is activated. The concept of a base
-layer makes more sense when looking at the next action: `layer-while-held`.
-
-This action accepts a single subsequent string which must be a layer name
-defined in a `deflayer` entry.
-
-.Example:
-[source]
-----
-(defalias dvk (layer-switch dvorak))
-----
-
-[[layer-while-held]]
-=== layer-while-held
-<<table-of-contents,Back to ToC>>
-
-This action allows you to temporarily change to another layer while the key
-remains held. When the key is released, you go back to the currently active
-"base" layer.
-
-This action accepts a single subsequent string which must be a layer name
-defined in a `deflayer` entry.
+| `+M-+`
+| Left Meta
 
-.Example:
-[source]
-----
-(defalias nav (layer-while-held navigation))
-----
-
-You may also use `layer-toggle` in place of `layer-while-held`; they behave
-exactly the same. The `layer-toggle` name is slightly shorter but is a bit
-inaccurate with regards to its meaning.
-
-[[transparent-key]]
-=== Transparent key
-<<table-of-contents,Back to ToC>>
-
-If you use a single underscore for a key `+_+` then it acts as a "transparent"
-key in a `+deflayer+`. The behaviour depends if `+_+` is on a base layer or a
-while-held layer. When `+_+` is pressed on the active base layer, the key will
-default to the corresponding `defsrc` key. If `+_+` is pressed on the active
-while-held layer, the base layer's behaviour will activate.
-
-.Example:
-[source]
-----
-(defsrc
-  a b c
-)
-
-(deflayer remap-only-c-to-d
-  _ _ d
-)
-----
-
-[[no-op]]
-=== No-op
-<<table-of-contents,Back to ToC>>
-
-You may use the action `+XX+` as a "no operation" key, meaning pressing the key
-will do nothing. This might be desirable in place of a transparent key on a
-layer that is not fully mapped so that a key that is intentionally not mapped
-will do nothing as opposed to typing a letter.
-
-.Example:
-[source]
-----
-(deflayer contains-no-op
-  XX a s d f
-)
-----
-
-[[unicode]]
-=== Unicode
-<<table-of-contents,Back to ToC>>
+| `+RM-+`
+| Right Meta
+|===
 
-The `+unicode+` action accepts a single unicode character. The character will
-not be repeatedly typed if you hold the key down.
+A special behaviour of output chords is that if another key is pressed,
+all of the chord keys will be released
+before the newly pressed key action activates.
+The modifier keys are often not desired for subsequent actions
+and without this behaviour,
+rapid typing can result in undesired modified key presses.
+If you want keys to remain pressed, use <<multi>> instead.
 
-You may use a unicode character as an alias if desired.
+**Description**
 
-NOTE: The unicode action may not be correctly accepted by the active
-application.
-
-NOTE: If using Linux, make sure to look at the
-<<linux-only-linux-unicode-u-code,unicode behaviour customization>> in defcfg.
+You may want to remap a key to automatically be pressed in combination with
+modifiers such as Control or Shift.
+Output chords are a way for you to achieve this.
 
-[source]
-----
-(defalias
-  sml (unicode 😀)
-  🙁 (unicode 🙁)
-)
-(deflayer has-happy-sad
-  @sml @🙁 a s d f
-)
-----
+Output chords are typically used do one-off actions such as:
 
-[[output-chords-combos]]
-=== Output chords/combos
-<<table-of-contents,Back to ToC>>
+- type a symbol, e.g. `S-1` to output `!` for the US layout.
+- type an accented character,
+e.g. `RA-a` to output `á` for the US international layout.
+- do a special action like `C-c` to send `SIGTERM` in the terminal
 
-You may want to remap a key to automatically be pressed in combination with
-modifiers such as Control or Shift. You can achieve this by prefixing the
-normal key name with one or more of:
+It should be noted that output chords are not usable in all configuration items.
+If you get an unknown key error where you expected an output chord to be usable,
+you must split the output chord into its component keys.
+For example, `+(unmod C-l)+` is an error;
+instead you should use `+(unmod lctl l)+`.
 
-* `+C-+`: Left Control
-* `+A-+`: Left Alt
-* `+S-+`: Left Shift
-* `+M-+`: Left Meta, a.k.a. Windows, GUI, Command, Super
-* `+RA-+` or `+AG+`: Right Alt, a.k.a. AltGr
+The output chord prefix strings are:
 
-These modifiers may be combined together if desired.
+* `+C-+`: Left Control (also `+‹⎈+` `+‹⌃+` or without the `+‹+` side indicator)
+* `+RC-+`: Right Control (also `+⎈›+` `+⌃›+`)
+* `+A-+`: Left Alt (also `+‹⎇+` `+‹⌥+` or without the `+‹+` side indicator))
+* `+RA-+`: Right Alt, a.k.a. AltGr (also `+AG+` `+⎇›+` `+⌥›+`)
+* `+S-+`: Left Shift (also `+‹⇧+` or without the `+‹+` side indicator))
+* `+RS-+`: Right Shift (also `+⇧›+`)
+* `+M-+`: Left Meta, a.k.a. Windows, GUI, Command, Super (also `+‹⌘+` `+‹❖+` `+‹◆+` or without the `+‹+` side indicator))
+* `+RM-+`: Right Meta (also `+⌘›+` `+❖›+` `+◆›+`)
 
 .Example:
 [source]
 ----
 (defalias
+  ;; Type exclamation mark (US layout)
+  ex! S-1
   ;; Ctrl+C: send SIGINT to a Linux terminal program
   int C-c
   ;; Win+Tab: open Windows' Task View
@@ -940,7 +1176,19 @@ These modifiers may be combined together if desired.
 
 [[repeat-key]]
 === Repeat key
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+[cols="1,5"]
+|===
+| `rpt`
+| String action that outputs the single most-recently typed key.
+
+| `rpt-any`
+| String action that outputs the most-recently outputted action.
+|===
+
+**Description**
 
 The action `+rpt+` repeats the most recently typed key. Holding down this key
 will not repeatedly send the key. The intended use case is to be able to use a
@@ -972,12 +1220,32 @@ and would output `ctrl+c` in the example case.
 
 [[release-a-key-or-layer]]
 === Release a key or layer
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+[cols="1,2"]
+|===
+| `(release-key $key)`
+| List action that releases the defined key from output actions.
+Notably this does not act on key inputs.
+
+| `(release-layer $layer-name)`
+| List action that releases `layer-while-held` activations
+for the given layer name.
+|===
+
+**Description**
 
 You can release a held key or layer via these actions:
 
-* `release-key`: release a key, accepts `defsrc` compatible names
-* `release-layer`: release a while-held layer
+* `release-key` or `key↑`: release a key, accepts `defsrc` compatible names
+* `release-layer` or `layer↑`: release a while-held layer
+
+A lower-level detail of these actions is that they operate on output states
+as opposed to virtually releasing an input key.
+This does have some practical significance.
+For example, if the action `(macro-repeat a 50)` were on the `a` key,
+activating `(release-key a)` will not stop the repeating macro.
 
 An example practical use case for `release-key` is seen in the `multi` section
 directly below.
@@ -987,7 +1255,24 @@ There is currently no known practical use case for
 
 [[multi]]
 === multi
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+Activate multiple actions in sequence.
+
+.Syntax:
+[source]
+----
+(multi $action1 $action2 ... $actionN)
+----
+
+[cols="1,3"]
+|===
+| `$action`
+| An output action.
+|===
+
+**Description**
 
 The `+multi+` action executes multiple keys or actions in order but also
 simultaneously. It accepts one or more actions.
@@ -1038,16 +1323,99 @@ and that would work as intended.
 It is recommended to avoid `multi` if it can be replaced
 with a different action like `macro` or an output chord.
 
+==== reverse-release-order
+
+**Reference**
+
+String item that can be used inside of `(multi ...)`
+to reverse the release order of any keys that were pressed
+as part of `multi`.
+
+.Syntax:
+[source]
+----
+(multi ... reverse-release-order)
+----
+
+**Description**
+
+Within `multi` you can use include `reverse-release-order`
+to do what the action states: reverse the typical release order from
+if you have multiple keys in multi.
+
+For example, pressing then releasing a key with the action:
+`(multi a b c)` would press a b c in the stated order
+and then release a b c in the stated order.
+Changing it to `(multi a b c reverse-release-order)`
+would press a b c in the stated order
+and then release c b a in the stated order.
+
+.Example:
+[source]
+----
+(defalias
+  S-a-reversed (multi lsft a reverse-release-order)
+)
+----
+
 [[mouse-actions]]
 === Mouse actions
-<<table-of-contents,Back to ToC>>
 
 You can click the left, middle, and right buttons using kanata actions, do
 vertical/horizontal scrolling, and move the mouse.
 
 [[mouse-buttons]]
 ==== Mouse buttons
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+You can activate mouse actions with the string actions below.
+
+[cols="1,5"]
+|===
+| `mlft`
+| Hold left mouse button.
+
+| `mmid`
+| Hold middle mouse button.
+
+| `mrgt`
+| Hold right mouse button.
+
+| `mfwd`
+| Hold forward mouse button.
+
+| `mbck`
+| Hold backward mouse button.
+
+| `mltp`
+| Tap left mouse button.
+
+| `mmtp`
+| Tap middle mouse button.
+
+| `mrtp`
+| Tap right mouse button.
+
+| `mftp`
+| Tap forward mouse button.
+
+| `mbtp`
+| Tap backward mouse button.
+|===
+
+In Linux and Windows,
+the hold actions can be used within `defsrc` and `deflayermap`
+to remap mouse buttons like keyboard keys.
+
+NOTE:
+On Windows, the Kanata process must be restarted
+for it to begin or to stop handling mouse events;
+changing defsrc then live-reloading will not
+begin handling mouse events
+if defsrc previously did not have any mouse events in defsrc.
+
+**Description**
 
 The mouse button actions are:
 
@@ -1058,6 +1426,10 @@ The mouse button actions are:
 * `mbck`: backward mouse button
 
 The mouse button will be held while the key mapped to it is held.
+On Linux, Windows, and macOS,
+the above actions are also usable in `defsrc`
+to enable remapping specified mouse actions in your layers,
+like you would with keyboard keys.
 
 If there are multiple mouse click actions within a single multi action, e.g.
 
@@ -1088,18 +1460,65 @@ The actions are as follows:
 
 [[mouse-wheel]]
 ==== Mouse wheel
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+The `mwheel-*` actions allow you to emulate a mouse wheel.
+Holding the action will repeatedly scroll
+according to the action configuration.
+
+.Syntax:
+[source]
+----
+(mwheel-$variant $interval $distance)
+----
+
+[cols="1,4"]
+|===
+| `$variant`
+| One of `up down left right` representing the scroll direction to use.
+
+| `$interval`
+| Number of milliseconds between scroll actions.
+
+| `$distance`
+| Distance to travel per activation.
+The number `120` represents a complete notch on
+standard resolution mice and in some environments,
+120 or a multiple of it should be what is used.
+|===
+
+You may use these key names within `defsrc`
+to remap scroll events as if they were keys,
+corresponding to up, down, left, right respectively:
+`mwu`, `mwd`, `mwl`, `mwr`.
+
+The remapping of mouse button and wheel events is effective on Linux, Windows, and macOS.
+
+NOTE:
+On Windows, the Kanata process must be restarted
+for it to begin or to stop handling mouse events;
+changing defsrc then live-reloading will not
+begin handling mouse events
+if defsrc previously did not have any mouse events in defsrc.
+On macOS, live-reload can install the mouse event tap on the fly
+when a new config introduces mouse keys, but stopping the tap
+once installed still requires a restart.
+Mouse input on macOS requires Accessibility or Input Monitoring
+permission in System Settings > Privacy & Security.
+
+**Description**
 
 The mouse wheel actions are:
 
-* `mwheel-up`: vertical scroll up
-* `mwheel-down`: vertical scroll down
-* `mwheel-left`: horizontal scroll left
-* `mwheel-right`: horizontal scroll right
+* `mwheel-up` or `🖱☸↑`: vertical scroll up
+* `mwheel-down` or `🖱☸↓`: vertical scroll down
+* `mwheel-left` or `🖱☸←`: horizontal scroll left
+* `mwheel-right` or `🖱☸→`: horizontal scroll right
 
 All of these actions accept two number strings. The first is the interval
 (unit: ms) between scroll actions. The second number is the distance
-(unit: arbitrary). In both Windows and Linux, 120 distance units is equivalent
+(unit: arbitrary). In both Linux and Windows, 120 distance units is equivalent
 to a notch movement on a physical wheel. You can play with the parameters to
 see what feels correct to you. Both numbers must be in the range [1,65535].
 
@@ -1107,16 +1526,138 @@ NOTE: In Linux, not all desktop environments support the `REL_WHEEL_HI_RES` even
 If this is the case for yours,
 it will likely be a better experience to use a distance value that is a multiple of 120.
 
+On Linux and Windows, you can also choose to read from a mouse device.
+When doing so, using the `mwu`, `mwd`, `mwl`, `mwr` key names in `defsrc`
+allow you to remap the mouse scroll up/down/left/right actions like you would
+with keyboard keys.
+
+NOTE: If you are using a high-resolution mouse in Linux,
+only a full "notch" of the scroll wheel will activate the action.
+
+NOTE: If you are using a high-resolution mouse with Interception,
+you will probably get way more events than you intended.
+
+[[mouse-wheel-inertial]]
+===== Mouse wheel: inertial variants
+
+**Reference**
+
+The `mwheel-accel-*` actions allow you to emulate a mouse wheel,
+with "inertial" properties,
+meaning scroll speed accelerates while active and decelerates when not.
+You can adjust factors of acceleration and deceleration.
+
+.Syntax:
+[source]
+----
+(mwheel-accel-$variant $initial-velocity $maximum-velocity $acceleration-multiplier $deceleration-multiplier)
+----
+
+[cols="2,3"]
+|===
+| `$variant`
+| One of `up down left right` representing the scroll direction to use.
+
+| `$initial-velocity`
+| Starting scroll speed, in arbitrary units.
+Suggested starting point: `3`.
+
+| `$maximum-velocity`
+| Starting scroll speed, in arbitrary units.
+Suggested starting point: `1200`.
+
+| `$acceleration-multiplier`
+| Determines acceleration rate of scroll speed.
+Suggested starting point: `1.15`.
+
+| `deceleration-multiplier`
+| Determines deceleration rate of scroll speed.
+Suggested starting point: `0.93`.
+Setting to 0 will make scroll stop abruptly.
+|===
+
+**Description**
+
+An alternative scrolling action can be used via `mwheel-accel-*`.
+This action has "inertial" behaviour which you may prefer.
+
+The recommended starting point for the parameters are as below:
+
+.Example configuration:
+[source]
+----
+(defvar
+  mw-initial-v 3
+  mw-maximum-v 1200
+  mw-accel 1.15
+  mw-decel 0.93)
+(defalias
+  mwu (mwheel-accel-up   $mw-initial-v $mw-maximum-v $mw-accel $mw-decel)
+  mwd (mwheel-accel-down $mw-initial-v $mw-maximum-v $mw-accel $mw-decel))
+----
+
 [[mouse-movement]]
 ==== Mouse movement
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+The `movemouse-*` actions allow you to move the mouse cursor.
+Holding the action will repeatedly move the cursor
+according to the configuration.
+
+.Syntax:
+[source]
+----
+(movemouse-$variant $interval $distance)
+----
+
+[cols="1,4"]
+|===
+| `$variant`
+| One of `up down left right` representing the direction to move.
+
+| `$interval`
+| Number of milliseconds between move activations.
+
+| `$distance`
+| Distance to travel per activation in unit of pixels.
+|===
+
+There is a move mouse variant that increases distance per activation
+at a constant rate until a maximum is reached.
+
+.Syntax:
+[source]
+----
+(movemouse-accel-$variant $interval $acceleration-time $min $max)
+----
+
+[cols="1,4"]
+|===
+| `$variant`
+| One of `up down left right` representing the direction to move.
+
+| `$interval`
+| Number of milliseconds between move activations.
+
+| `$acceleration-time`
+| Number of milliseconds until max distance per activation is reached.
+
+| `$min`
+| Initial distance to travel per activation in unit of pixels.
+
+| `$max`
+| Maximum distance to travel per activation in unit of pixels.
+|===
+
+**Description**
 
 The mouse movement actions are:
 
-* `movemouse-up`
-* `movemouse-down`
-* `movemouse-left`
-* `movemouse-right`
+* `movemouse-up` or `🖱↑`
+* `movemouse-down` or `🖱↓`
+* `movemouse-left` or `🖱←`
+* `movemouse-right` or `🖱→`
 
 Similar to the mouse wheel actions, all of these actions accept two number strings.
 The first is the interval (unit: ms) between movement actions and the second number
@@ -1125,10 +1666,10 @@ is the distance (unit: pixels) of each movement.
 The following are variants of the above mouse movements that apply linear mouse
 acceleration from the minimum distance to the maximum distance as the mapped key is held.
 
-* `movemouse-accel-up`
-* `movemouse-accel-down`
-* `movemouse-accel-left`
-* `movemouse-accel-right`
+* `movemouse-accel-up` or `🖱accel↑`
+* `movemouse-accel-down` or `🖱accel↓`
+* `movemouse-accel-left` or `🖱accel←`
+* `movemouse-accel-right` or `🖱accel→`
 
 All these actions accept four number strings. The first number is the
 interval (unit: ms) between movement actions. The second number is the time it
@@ -1136,30 +1677,54 @@ takes (unit: ms) to linearly ramp up from the minimum distance to the maximum
 distance. The third and fourth numbers are the minimum and maximum distances
 (unit: pixels) of each movement.
 
+There is a toggable defcfg option related to `movemouse-accel` - <<movemouse-inherit-accel-state>>. You might want to enable it, especially if you're coming from QMK.
+
 [[set-mouse]]
 ==== Set absolute mouse position
-<<table-of-contents,Back to ToC>>
 
-The action `setmouse` sets the absolute mouse position.
+The action `setmouse` or `set🖱` sets the absolute mouse position.
 
-WARNING: This is only supported in Windows right now.
+WARNING: This is not supported on Linux.
 For an interesting keyboard-centric mouse solution in Linux,
 try looking at
 https://github.com/rvaiya/warpd[warpd].
 
 This list action takes two parameters which are `x` and `y` positions
 of the absolute movement.
-The values go from 0,0 which is the upper-left corner of the screen
-to 65535,65535 which is the lower-right corner of the screen.
-If you have multiple monitors,
-`setmouse` treats them all as a single large screen.
-This can make it a little confusing for how to set the `x, y` values
-to get the positions that you want.
-Experimentation will be needed.
+
+The coordinate system is platform-specific:
+
+* **macOS**: Pixel coordinates. `0,0` is the top-left of the main display,
+  maximum values are your screen resolution (e.g., `1920,1080`).
+* **Windows**: Normalized coordinates from `0,0` (top-left)
+  to `65535,65535` (bottom-right). Multiple monitors are treated as one virtual desktop.
+
+Experimentation will be needed to find the correct values for your setup.
+
+[[mouse-speed]]
+==== Modify the speed of mouse movements
+
+The action `movemouse-speed` or `🖱speed` modifies the speed at which `movemouse` and
+`movemouse-accel` function at runtime. It does this by expanding or shrinking
+`min_distance` and `max_distance` while the action key is pressed.
+
+This action accepts one number (unit: percentage) by which the
+mouse movements will be accelerated.
+
+WARNING: Due to the nature of pixels being whole numbers, some values such as
+33 may not result in an exact third of the distance.
+
+.Example:
+[source]
+----
+(defalias
+  fst (movemouse-speed 200)
+  slw (movemouse-speed 50)
+)
+----
 
 [[mouse-all-actions-example]]
 ==== Mouse all actions example
-<<table-of-contents,Back to ToC>>
 
 [source]
 ----
@@ -1180,38 +1745,70 @@ Experimentation will be needed.
   ma→ (movemouse-accel-right 1 1000 1 5)
 
   sm (setmouse 32228 32228)
+
+  fst (movemouse-speed 200)
 )
 
 (deflayer mouse
   _    @mwu @mwd @mwl @mwr _    _    _    _    _    @ma↑ _    _    _
   _    pgup bck  _    fwd  _    _    _    _    @ma← @ma↓ @ma→ _    _
   _    pgdn mlft _    mrgt mmid _    mbck mfwd _    @ms↑ _    _
-  _    _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
+  @fst _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
   _    _    _              _              _    _    _
 )
 ----
 
 [[tap-dance]]
 === tap-dance
-<<table-of-contents,Back to ToC>>
-
-The `+tap-dance+` action allows repeated tapping of a key to result in
-different actions. It is followed by a timeout (unit: ms) and a list
-of keys or actions. Each time the key is pressed, its timeout will reset. The
-action will be chosen if one of the following events occur:
 
-* the timeout expires
-* a different key is pressed
-* the key is repeated up to the final action
+**Reference**
 
-You may put normal keys or other actions in `+tap-dance+`.
+The `tap-dance` action allows performing different actions
+based on number of consecutive taps of the same key.
 
-.Example:
+.Syntax:
 [source]
 ----
-(defalias
-  ;; 1 tap : "A" key
-  ;; 2 taps: Control+C
+(tap-dance $timeout $action-list)
+----
+
+[cols="1,4"]
+|===
+| `$timeout`
+| Number of milliseconds after which the tap-dance ends.
+
+| `$action-list`
+| A list of actions that can be selected, ordered by number of taps.
+|===
+
+The `tap-dance-eager` variant will eagerly perform actions.
+Use of `macro` and `bspc` can help to backtrack for the 2nd tap onwards.
+
+.Syntax:
+[source]
+----
+(tap-dance-eager $timeout $action-list)
+----
+
+**Description**
+
+The `+tap-dance+` action allows repeated tapping of a key to result in
+different actions. It is followed by a timeout (unit: ms) and a list
+of keys or actions. Each time the key is pressed, its timeout will reset. The
+action will be chosen if one of the following events occur:
+
+* the timeout expires
+* a different key is pressed
+* the key is repeated up to the final action
+
+You may put normal keys or other actions in `+tap-dance+`.
+
+.Example:
+[source]
+----
+(defalias
+  ;; 1 tap : "A" key
+  ;; 2 taps: Control+C
   ;; 3 taps: Switch to another layer
   ;; 4 taps: Escape key
   td (tap-dance 200 (a C-c (layer-switch l2) esc))
@@ -1241,7 +1838,55 @@ In the example below, repeated taps will, in order:
 
 [[one-shot]]
 === one-shot
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+Activate keys or layers for a time without keeping the input key held,
+for one subsequent key.
+Activating other one-shot actions,
+while one or more are already active,
+will reset the timeout,
+and overlap the one-shot actions.
+
+
+.Syntax:
+[source]
+----
+($one-shot-variant $timeout $action)
+----
+
+Values for `$variant`:
+[cols="1,3"]
+|===
+| `one-shot-press`
+| End on the first press of another key.
+This is also the variant selected by the name `one-shot`.
+
+| `+one-shot-release+`
+| End on the first release of a newly pressed key.
+
+| `+one-shot-press-pcancel+`
+| End on the first press of another key
+  or on re-press of this key, or of another active one-shot key
+
+| `+one-shot-release-pcancel+`
+| End on the first release of a newly pressed key
+  or on re-press of this key, or of another active one-shot key.
+|===
+
+Other items:
+[cols="1,3"]
+|===
+| `$timeout`
+| Number of milliseconds after which
+if not deactivated due to user input,
+one-shot will deactivate on its own.
+
+| `$action`
+| Layer action, key, or output chord.
+|===
+
+**Description**
 
 The `+one-shot+` action is similar to "sticky keys", if you know what that is.
 This activates an action or key until either the timeout expires or a different
@@ -1254,7 +1899,7 @@ Some of the intended use cases are:
 * switch to another layer for exactly one following key press
 
 If a `+one-shot+` key is held then it will act as the regular key. E.g. holding
-a key assigned with `+@os1+` in the example below will keep Left Shift held for
+a key assigned with `+@os2+` in the example below will keep Left Shift held for
 every key, not just one, as long as it's still physically pressed.
 
 Pressing multiple `+one-shot+` keys in a row within the timeout will combine
@@ -1263,14 +1908,14 @@ recently pressed `+one-shot+` key.
 
 There are four variants of the `+one-shot+` action:
 
-- `+one-shot-press+`:
+- `+one-shot-press+` or `+one-shot↓+`:
   end on the first press of another key
-- `+one-shot-release+`:
+- `+one-shot-release+` or `+one-shot↑+`:
   end on the first release of another key
-- `+one-shot-press-pcancel+`:
+- `+one-shot-press-pcancel+` or `+one-shot↓⤫+`:
   end on the first press of another key
   or on re-press of another active one-shot key
-- `+one-shot-release-pcancel+`:
+- `+one-shot-release-pcancel+` or `+one-shot↑⤫+`:
   end on the first release of another key
   or on re-press of another active one-shot key
 
@@ -1282,6 +1927,9 @@ than the initial key pressed.
 
 The default name `+one-shot+` corresponds to `+one-shot-press+`.
 
+NOTE: When using one-shot with keys that will trigger defoverrides,
+you will likely want to adjust <<override-release-on-activation>> to yes in `defcfg`.
+
 .Example:
 [source]
 ----
@@ -1294,35 +1942,270 @@ The default name `+one-shot+` corresponds to `+one-shot-press+`.
 )
 ----
 
+[[one-shot-pause-processing]]
+==== one-shot-pause-processing
+
+**Reference**
+
+Pause `one-shot` processing of new input keypresses for a time,
+to allow actions that are not intended to consume `one-shot`
+to take place.
+
+.Syntax:
+[source]
+----
+(one-shot-pause-processing $time)
+----
+
+[cols="1,5"]
+|===
+| `time`
+| Number of milliseconds to ignore processing.
+Something notable is that one virtual key press or releas
+(tap is a separate press and subsequent release)
+will take 1ms to process.
+If using virtual keys this number must be larger
+than the number of virtual key events that are taking place.
+|===
+
+**Description**
+
+The `one-shot-pause-processing` list action allows you to pause the
+key press processing of one-shot activations.
+An example of when this is useful the following sequence:
+
+- Activate a layer-while-held
+- Activate a one-shot action on that layer
+- Release the layer-while-held key, which has an `(on-release ...)` action
+  associated with it.
+- The on-release action is not intended to consume one-shot activations
+
+In the scenario above, by default the on-release activation
+would trigger deactivation of one-shot;
+thus the pause processing action must be used to stop this from happening.
 
 [[tap-hold]]
 === tap-hold
-<<table-of-contents,Back to ToC>>
+
+WARNING: The `tap-hold` action and all variants can behave unexpectedly on Linux
+with respect to repeat of antecedent key presses.
+The full context is in https://github.com/jtroo/kanata/discussions/422[discussion #422].
+In brief, the workaround is to use `tap-hold` inside of <<multi,multi>>,
+combined with another key action that behaves as a no-op like `f24`. +
+Example: `(multi f24 (tap-hold ...))`.
+If multiple `tap-hold` actions may be pressed subsequently,
+all using the `f24` workaround,
+you may need to release the `f24` within the same `multi`
+to avoid repeats from one double-tapped `tap-hold` action
+followed by another, different `tap-hold` action.
+Example:
+`(defvirtualkeys relf24 (release-key f24)) ... (multi f24 (tap-hold ...) (macro 5 (on-press tap-vkey relf24)))`
+
+**Reference**
+
+The `tap-hold` action lets you activate different actions
+depending if a key is tapped or held.
+
+.Syntax:
+[source]
+----
+(tap-hold $tap-repress-timeout $hold-timeout $tap-action $hold-action)
+----
+
+[cols="1,4"]
+|===
+| `$tap-repress-timeout`
+| Number of milliseconds for the window that a tap into re-press with hold
+results in the `$tap-action` being held.
+
+| `$hold-timeout`
+| Number of milliseconds after which the `$hold-action` activates.
+Releasing the key before this elapses
+results in `$tap-action` activating.
+
+| `$tap-action`
+| Action to activate when the input is determined to be a "tap".
+
+| `$hold-action`
+| Action to activate when the input is determined to be a "hold".
+|===
+
+.Variants:
+----
+(tap-hold-press $tap-repress-timeout $hold-timeout $tap-action $hold-action)
+(tap-hold-release $tap-repress-timeout $hold-timeout $tap-action $hold-action)
+(tap-hold-press-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action)
+(tap-hold-release-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action [?reset-timeout-on-press])
+(tap-hold-release-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
+(tap-hold-release-tap-keys-release $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-trigger-keys-on-press $tap-trigger-keys-on-press-then-release)
+(tap-hold-except-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
+(tap-hold-tap-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
+(tap-hold-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action [options...])
+(tap-hold-opposite-hand $timeout $tap-action $hold-action [options...])
+(tap-hold-opposite-hand-release $timeout $tap-action $hold-action [options...])
+(tap-hold-order $tap-repress-timeout $buffer-ms $tap-action $hold-action [options...])
+----
+
+[cols="1,2"]
+|===
+| `tap-hold-press`
+| Activate `$hold-action` early if held and another input key is pressed.
+
+| `tap-hold-release`
+| Activate `$hold-action` early if held and another input key is pressed and released.
+
+| `tap-hold-press-timeout`
+| Activate `$hold-action` if held and another input key is pressed.
+If the defined timeout elapses, `$timeout-action` will activate.
+
+| `tap-hold-release-timeout`
+| Activate `$hold-action` early if held and another input key is pressed and released.
+If the defined timeout elapses, `$timeout-action` will activate.
+Optionally include `reset-timeout-on-press` to reset timeout duration on a new press,
+giving more time for a subsequent release to activate hold instead of timeout.
+
+| `tap-hold-release-keys`
+| Activate `$hold-action` early if held and another input key is pressed and released.
+The `$tap-keys` parameter is a list of key names.
+Activates `$tap-action` early if a key within `$tap-keys` is pressed before hold activates.
+
+| `tap-hold-release-tap-keys-release`
+| Activate `$hold-action` early if held and another input key is pressed and released.
+The `$tap-keys-...` parameters are lists of key names.
+Activate `$tap-action` early
+if a key within `$tap-trigger-keys-on-press`
+is pressed before hold activates
+Activate `$tap-action` early
+if a key within `$tap-trigger-keys-on-press-then-release`
+is pressed then released before hold activates.
+
+| `tap-hold-except-keys`
+| The `$tap-keys` parameter is a list of key names.
+Activates `$tap-action` if a key within `$tap-keys` is pressed
+or if the action key is released before hold timeout.
+No key is ever output until the action key is released
+or another key is pressed,
+which differs from the default `tap-hold` behaviour.
+
+| `tap-hold-tap-keys`
+| The `$tap-keys` parameter is a list of key names.
+Activates `$tap-action` early if a key within `$tap-keys` is pressed before hold activates.
+Unlike `tap-hold-release-keys`, does NOT activate `$hold-action` early
+when other keys are pressed and released.
+Waits for full `$hold-timeout` before activating `$hold-action`.
+This is useful for home row mods where fast typing should not trigger modifiers.
+
+| `tap-hold-keys`
+| A flexible tap-hold variant with named key list options.
+Options are: `(tap-on-press <keys...>)` activates `$tap-action` early if a listed key is pressed;
+`(tap-on-press-release <keys...>)` activates `$tap-action` early if a listed key is pressed then released;
+`(hold-on-press <keys...>)` activates `$hold-action` early if a listed key is pressed.
+For any other key: if that key is pressed and released while this key is waiting,
+`$hold-action` is triggered early (PermissiveHold behavior).
+All list options are optional.
+
+| `tap-hold-opposite-hand`
+| Resolves to `$hold-action` when a key from the opposite hand (per `defhands`) is pressed.
+Requires a `defhands` directive. Supports list-form options for fine-grained control.
+See <<defhands and tap-hold-opposite-hand>> below.
+
+| `tap-hold-opposite-hand-release`
+| Like `tap-hold-opposite-hand` but waits for the interrupting key to be pressed AND released
+before committing. This avoids misfires on fast same-hand rolls where keystrokes briefly overlap.
+Requires a `defhands` directive. Supports the same options as `tap-hold-opposite-hand`.
+
+| `tap-hold-order`
+| Resolves purely by key release order, with no timeout.
+If the tap-hold key is released before the other key, activates `$tap-action`;
+if the other key is released first (while the tap-hold key is still held), activates `$hold-action`.
+`$buffer-ms` is a grace period after the tap-hold key is pressed during which
+release-order logic is ignored so that fast typing resolves as tap.
+Optionally, `(require-prior-idle <ms>)` can short-circuit to tap when a different key
+was pressed within that many milliseconds before the tap-hold key;
+`require-prior-idle` checks prior typing activity before release-order logic begins,
+whereas `buffer-ms` creates an unconditional tap-only window after the key is pressed.
+This option is available on all tap-hold variants; see <<tap-hold-require-prior-idle>>.
+|===
+
+All `tap-hold` variants support an optional trailing `(require-prior-idle <ms>)` option
+to override the global <<tap-hold-require-prior-idle>> setting for that specific action.
+Use `(require-prior-idle 0)` to disable idle detection for a specific key.
+
+**Description**
 
 The `+tap-hold+` action allows you to have one action/key for a "tap" and a
 different action/key for a "hold". A tap is a rapid press then release of the
 key whereas a hold is a long press.
 
+NOTE: for more discussion on tap-hold,
+you may want to have a look at this GitHub discussion:
+https://github.com/jtroo/kanata/discussions/1455[link to discussion].
+
 The action takes 4 parameters in the listed order:
 
-. tap timeout (unit: ms)
+. tap repress timeout (unit: ms)
 . hold timeout (unit: ms)
 . tap action
 . hold action
 
-The tap timeout is the number of milliseconds within which a rapid
+The tap repress timeout is the number of milliseconds within which a rapid
 press+release+press of a key will result in the tap action being held instead
 of the hold action activating.
 
+.Tap repress timeout in more detail
+[%collapsible,indent=4]
+====
+The way a `tap-hold` action works with respect to the tap repress timeout
+is often unclear to newcomers.
+To make it concrete, the output event sequence of the `tap-hold` action
+`(tap-hold $tap-repress-timeout 200 a lctl)`
+for varying values of `$tap-repress-timeout`
+with a fixed input event sequence will be described.
+
+The input event sequence is:
+
+- press
+- 50 ms elapses
+- release
+- 50 ms elapses
+- press
+- 300 ms elapses
+- release
+
+With `(defvar $tap-repress-timeout 0)`, the output event sequence is:
+
+- 50 ms elapses
+- press `a`
+- release `a`
+- 250 ms elapses
+- press `lctl`
+- 100 ms elapses
+- release `lctl`
+
+The above output sequence is the same for all `$tap-repress-timeout` values
+between and including `0` and `99`.
+
+For a value of `100` or greater for `$tap-repress-timeout`,
+the output event sequence is instead:
+
+- 50 ms elapses
+- press `a`
+- release `a`
+- 50 ms elapses
+- press `a`
+- 300 ms elapses
+- release `a`
+====
+
 The hold timeout is the number of milliseconds after which the hold action will
 activate.
 
 There are two additional variants of `+tap-hold+`:
 
-* `+tap-hold-press+`
+* `+tap-hold-press+` or `+tap⬓↓+`
 ** If there is a press of a different key, the hold action is activated even if
 the hold timeout hasn't expired yet
-* `+tap-hold-release+`
+* `+tap-hold-release+` or `+tap⬓↑+`
 ** If there is a press+release of a different key, the hold action is activated
 even if the hold timeout hasn't expired yet
 
@@ -1341,36 +2224,218 @@ but you should be wary of activating the hold action unintentionally.
 
 There are further additional variants of `tap-hold-press` and `tap-hold-release`:
 
-. `tap-hold-press-timeout`
-. `tap-hold-release-timeout`
+- `tap-hold-press-timeout` or `tap⬓↓timeout`
+- `tap-hold-release-timeout` or `tap⬓↑timeout`
 
 These variants take a 5th parameter, in addition to the same 4 as the other
 variants. The 5th parameter is another action, which will activate if the hold
 timeout expires as opposed to being triggered by other key actions, whereas the
 non `-timeout` variants will activate the hold action in both cases.
 
-- `tap-hold-release-keys`
+The `release` variant also accepts an optional 6th argument,
+`reset-timeout-on-press` which if included changes the timeout behaviour.
+This flag will make the timeout duration reset if a new key is pressed.
+This may result in longer timeouts,
+but can help with more consistent hold activations;
+because it may be challenging to release a key in time
+to activate the hold action instead of the timeout action.
+
+- `tap-hold-release-keys` or `tap⬓↑keys`
+
+This variant takes a 5th parameter which is a list of keys
+that trigger an early tap
+when they are pressed while the `tap-hold-release-keys` action is waiting.
+Otherwise this behaves as `tap-hold-release`.
 
-This variant takes a 5th parameter which is a list of keys that trigger an
-early tap when they are pressed while the `tap-hold-release-keys` action is
-waiting.
+The keys in the 5th parameter correspond to the physical input keys,
+or in other words the key that corresponds to `defsrc`.
+This is in contrast to the `fork` and `switch` actions
+which operates on outputted keys, or in other words the outputs
+that are in `deflayer`, `defalias`, etc. for the corresponding `defsrc` key.
 
 .Example:
 [source]
 ----
 (defalias
-  ;; tap: o    hold: arrows layer    timeout: backspace
-  oat (tap-hold-press-timeout   200 200 o @arr bspc)
-  ;; tap: e    hold: chords layer    timeout: esc
-  ect (tap-hold-release-timeout 200 200 e @chr esc)
   ;; tap: u    hold: misc layer      early tap if any of: (a o e) are pressed
   umk (tap-hold-release-keys 200 200 u @msc (a o e))
 )
 ----
 
+- `tap-hold-release-tap-keys-release`
+
+This variant behaves nearly the same as `tap-hold-release-keys`,
+but has another condition with respect to the eager tap.
+It accepts a second list that activates the eager tap
+if the any key listed within is pressed then released;
+as opposed to only on a press.
+
+The keys in the 5th and 6th parameters correspond to the physical input keys,
+or in other words the key that corresponds to `defsrc`.
+This is in contrast to the `fork` and `switch` actions
+which operates on outputted keys, or in other words the outputs
+that are in `deflayer`, `defalias`, etc. for the corresponding `defsrc` key.
+
+.Example:
+[source]
+----
+(defalias
+  ;; tap: u    hold: misc layer      early tap if any of:
+  ;;                                 (z x c v) are pressed, OR
+  ;;                                 (a s d f) are pressed THEN released
+  umk2 (tap-hold-release-tap-keys-release 200 200 u @msc (z x c v) (a s d f))
+)
+----
+
+- `tap-hold-except-keys` or `tap-hold⤫keys`
+
+This variant takes a 5th parameter which is a list of keys
+that always trigger a tap
+when they are pressed while the `tap-hold-except-keys` action is waiting.
+No key is ever output until there is either a release of the key or any other
+key is pressed. This differs from `tap-hold` behaviour.
+
+The keys in the 5th parameter correspond to the physical input keys,
+or in other words the key that corresponds to `defsrc`.
+This is in contrast to the `fork` and `switch` actions
+which operates on outputted keys, or in other words the outputs
+that are in `deflayer`, `defalias`, etc. for the corresponding `defsrc` key.
+
+.Example:
+[source]
+----
+(defalias
+  ;; tap: u    hold: misc layer      always tap if any of: (a o e) are pressed
+  umk (tap-hold-except-keys 200 200 u @msc (a o e))
+)
+----
+
+- `tap-hold-tap-keys` or `tap⬓tapkeys`
+
+This variant takes a 5th parameter which is a list of keys
+that trigger an early tap when they are pressed.
+Unlike `tap-hold-release-keys`, pressing and releasing other keys
+does NOT activate hold early - the full hold timeout is always waited.
+This is useful for home row mods where fast typing should not trigger modifiers.
+
+The keys in the 5th parameter correspond to the physical input keys,
+or in other words the key that corresponds to `defsrc`.
+
+.Example:
+[source]
+----
+(defalias
+  ;; tap: a    hold: lsft    early tap if any of: (s d f) are pressed
+  ;; other keys do NOT trigger early hold
+  ath (tap-hold-tap-keys 200 200 a lsft (s d f))
+)
+----
+
+==== defhands and tap-hold-opposite-hand
+
+`defhands` assigns physical keys to `left` / `right` hand groups.
+`tap-hold-opposite-hand` uses this to resolve hold when the next key
+is on the opposite hand — reducing misfires compared to manual key lists.
+
+[source]
+----
+(defhands
+  (left  q w e r t a s d f g z x c v b)
+  (right y u i o p h j k l ; n m , . /))
+
+(defalias
+  fctl (tap-hold-opposite-hand 180 f lctl))
+----
+
+`defhands` rules: at most one block; each group (`(left ...)`/`(right ...)`) at most once;
+a key cannot appear in both groups; partial definitions (only one hand) are allowed;
+unlisted keys have no hand assignment.
+
+`tap-hold-opposite-hand` takes `$timeout $tap-action $hold-action` followed by
+optional option lists. Most use `(name value)`, while `neutral-keys` uses
+followup key atoms: `(neutral-keys spc tab ...)`.
+It requires `defhands` to be defined.
+Internally it uses the same `HoldTapConfig::Custom` machinery as `tap-hold-release-keys`.
+
+[cols="1,1,1,2"]
+|===
+| Option | Values | Default | Description
+
+| `(timeout <value>)` | `tap`, `hold` | `tap` | Action when hold timeout elapses (optimized for home-row-mod behavior).
+| `(same-hand <value>)` | `tap`, `hold`, `ignore` | `tap` | Action when a same-hand key is pressed.
+| `(neutral-keys key ...)` | one or more key names | (empty) | Keys treated as neutral, overriding their `defhands` assignment.
+| `(neutral <value>)` | `tap`, `hold`, `ignore` | `ignore` | Action when a `neutral-keys` key is pressed.
+| `(unknown-hand <value>)` | `tap`, `hold`, `ignore` | `ignore` | Action when a key not in `defhands` is pressed.
+| `(require-prior-idle <ms>)` | `0`–`65535` | (disabled) | If a key was pressed within this many ms before the tap-hold key, resolve as tap immediately. Useful for avoiding accidental holds during fast typing.
+| `(tap-repress-timeout <ms>)` | `0`–`65535` | `0` | If the same key is re-pressed within this many ms after a tap, immediately tap again instead of entering the hold decision. `0` disables (every press enters the hold decision). See <<tap-hold,tap repress timeout>> for details.
+|===
+
+When a value is `ignore`, that key press is skipped and the action
+waits for the next key or timeout.
+
+Example with options:
+[source]
+----
+(defalias
+  fctl (tap-hold-opposite-hand 180 f lctl
+    (same-hand ignore)
+    (timeout hold)
+    (neutral-keys spc tab)
+    (neutral tap)))
+----
+
+See `cfg_samples/opposite-hand-hrm.kbd` for a full working example.
+
 [[macro]]
 === macro
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+The macro action taps the configured sequence of keys or actions.
+Numbers can be used to delay the sequence by the defined number of milliseconds.
+
+.Syntax:
+[source]
+----
+(macro $macro-action1 $macro-action2 ... $macro-actionN)
+----
+
+[cols="1,4"]
+|===
+| `$macro-action`
+| A delay, key, action within the subset allowed within macros,
+or an output-chord-prefixed list of more macro-actions.
+|===
+
+.Variants:
+----
+(macro-release-cancel ...)
+(macro-cancel-on-press ...)
+(macro-release-cancel-and-cancel-on-press ...)
+(macro-repeat ...)
+(macro-repeat-$cancel-variant ...)
+----
+[cols="1,2"]
+|===
+| `macro-release-cancel`
+| Cancel all active macros if the key is released.
+
+| `macro-cancel-on-press`
+| Cancel all active macros if a different key is pressed.
+
+| `macro-release-cancel-and-cancel-on-press`
+| Cancel all active macros if either the key is released or a different key is pressed.
+
+| `macro-repeat`
+| Repeat the macro while held.
+
+| `macro-repeat-$cancel-variant`
+| Repeat the macro while held.
+Cancels the final repeat according the behaviour of one of the variants:
+`release-cancel`, `cancel-on-press`, `release-cancel-and-cancel-on-press`.
+|===
+
+**Description**
 
 The `+macro+` action will tap a sequence of keys with optional
 delays. This is different from `+multi+` because in the `+multi+` action,
@@ -1380,9 +2445,13 @@ This means that with `+macro+` you can have some letters capitalized and others
 not. This is not possible with `+multi+`.
 
 The `+macro+` action accepts one or more keys, some actions, chords, and delays
-(unit: ms).  It also accepts a list prefixed with <<output-chords-combos,output chord>>
-modifiers where the list is subject to the aforementioned restrictions. The
-number keys will be parsed as delays, so they must be aliased to be used in a macro.
+(unit: ms).  It also accepts a list prefixed with <<output-chordscombos,output chord>>
+modifiers where the list is subject to the aforementioned restrictions.
+
+IMPORTANT: The number keys `0-9` will be parsed as millisecond delays
+whereas in other contexts they would be parsed as key names.
+To use the numbered keys they must be aliased
+or otherwise use the key names `Digit0-Digit9`.
 
 Up to 4 macros can be active at the same time.
 
@@ -1393,10 +2462,15 @@ The actions supported in `+macro+` are:
 * <<mouse-actions,mouse actions>>
 * <<repeat-key,repeat>>
 * <<live-reload,live reload>>
-* <<fake-keys,fake keys>>
+* <<virtual-keys,virtual key actions>>
 * <<sequences,sequence leader>>
 * <<arbitrary-code,arbitrary keycode>>
 * <<dynamic-macro,dynamic macro>>
+* <<unmod,unmod>>
+
+NOTE: Some of these actions may need short delays between.
+For example, `(macro a (unmod b) 5 (unmod c) d))`
+needs the delay of `5` to work correctly.
 
 .Example:
 [source]
@@ -1419,11 +2493,17 @@ The actions supported in `+macro+` are:
 )
 ----
 
-There is a variant of the `+macro+` action that will cancel all active macros
-upon releasing the key: `+macro-release-cancel+`. It is parsed identically to
-the non-cancelling version. An example use case for this action is holding down
-a key to get different outputs, similar to tap-dance but one can see which keys
-are being outputted.
+[[macro-release-cancel]]
+==== macro-release-cancel
+
+The `macro-release-cancel` variant of the `+macro+` action
+will cancel all active macros
+upon releasing the key.
+Shorter unicode variant: `+macro↑⤫+`.
+This variant is parsed identically to the non-cancelling version.
+An example use case for this action is holding down
+a key to get different outputs,
+similar to tap-dance but one can see which keys are being outputted.
 
 E.g. in the example below, when holding the key, first `1` is typed, then
 replaced by `!` after 500ms, and finally that is replaced by `@` after another
@@ -1441,7 +2521,43 @@ and the rest of the macro does not run.
 )
 ----
 
-There are further variants of the two `macro` actions which repeat while held.
+[[macro-cancel-on-press]]
+==== macro-cancel-on-press
+
+The `macro-cancel-on-press` variant of the `macro action`
+enables a cancellation trigger for all active macros including itself,
+which is activated when a physical press of any other key happens.
+The trigger is enabled while the macro is in progress.
+
+[source]
+----
+(defalias
+  1 1
+  1!@ (macro-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
+)
+----
+
+[[macro-release-cancel-and-cancel-on-press]]
+==== macro-release-cancel-and-cancel-on-press
+
+The `macro-release-cancel-and-cancel-on-press` variant
+combines the cancel behaviours
+of both the release-cancel and cancel-on-press.
+
+[source]
+----
+(defalias
+  1 1
+  1!@ (macro-release-cancel-and-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
+)
+----
+
+
+[[macro-repeat]]
+==== macro-repeat
+
+There are further `macro-repeat` variants of the three `macro` actions described previously.
+These variants repeat while held.
 The repeat will only occur once all macros have completed,
 including the held macro key.
 If multiple repeating macros are being held simulaneously,
@@ -1452,12 +2568,47 @@ only the most recently pressed macro will be repeated.
 (defalias
   mr1 (macro-repeat mltp)
   mr2 (macro-repeat-release-cancel mltp)
+  mr3 (macro-repeat-cancel-on-press mltp)
+  mr4 (macro-repeat-release-cancel-and-cancel-on-press mltp)
 )
 ----
 
 [[dynamic-macro]]
 === dynamic-macro
-<<table-of-contents,Back to ToC>>
+
+**Reference**
+
+Record and replay key inputs.
+
+.Syntax:
+[source]
+----
+(dynamic-macro-record $id)
+(dynamic-macro-play   $id)
+(dynamic-macro-record-stop)
+(dynamic-macro-record-stop-truncate $count)
+----
+
+[cols="1,3"]
+|===
+| `dynamic-macro-record`
+| Record a dynamicro macro which will be saved with the defined `$id`.
+
+| `dynamic-macro-play`
+| Play back a macro saved with the defined `$id`.
+
+| `dynamic-macro-record-stop`
+| Stop and save a macro recording.
+This can also be achieved by recording a new macro
+or re-pressing record with the same `$id`.
+
+| `dynamic-macro-record-stop-truncate`
+| Stop and save a macro recording while truncating `$count` events
+from the end of the recording.
+This can be useful if the record/stop button is on a different layer.
+|===
+
+**Description**
 
 The dynamic-macro actions allow for recording and playing key presses. The
 dynamic macro records physical key presses, as opposed to kanata's outputs.
@@ -1503,28 +2654,48 @@ while recording with `(dynamic-macro-record 0)` will be ignored.
 )
 ----
 
-[[fork]]
-=== fork
-<<table-of-contents,Back to ToC>>
+[[caps-word]]
+=== caps-word
 
-The fork action accepts two actions and a key list.
-The first (left) action will activate by default.
-The second (right) action will activate
-if any of the keys in the third parameter (right-trigger-keys) are currently active.
+**Reference**
 
-.Example:
+The `caps-word` action puts Kanata into a state where
+typed keys are automatically shifted by `lsft`.
+The state persists until terminated by timeout
+or by typing a key that ends the state.
+Typing a non-terminating key refreshes the timeout duration.
+
+The `-toggle` variants will end the caps-word state
+if pressed while caps-word is active,
+whereas the re-pressing the standard variants
+will keep the state active and refresh the timeout duration.
+
+.Syntax:
 [source]
 ----
-(defalias
-  frk (fork k @special (lalt ralt))
-)
+(caps-word $timeout)
+(caps-word-toggle $timeout)
+(caps-word-custom $timeout $shifted-list $non-terminal-list)
+(caps-word-custom-toggle $timeout $shifted-list $non-terminal-list)
 ----
 
-[[caps-word]]
-=== caps-word
-<<table-of-contents,Back to ToC>>
+[cols="1,4"]
+|===
+| `$timeout`
+| Number of milliseconds after which the caps-word state ends.
+The duration is refreshed upon typing a non-terminating character.
+
+| `$shifted-list`
+| List of keys that will be automatically shifted.
+
+| `$non-terminal-list`
+| List of keys that are not shifted
+but which do not terminate the caps-word state.
+|===
+
+**Description**
 
-The `caps-word` action triggers a state where the `lsft` key
+The `caps-word` or `word⇪` action triggers a state where the `lsft` key
 will be added to the active key list
 when a set of specific keys are active.
 The keys are: `a-z` and `-`, which will be outputted as `A-Z` and `_`
@@ -1553,145 +2724,3075 @@ and the extra keys in this list:
 - `bspc del`
 - `up down left rght`
 
-You can use `caps-word-custom` instead of `caps-word`
+You can use `caps-word-custom` or `word⇪-custom` instead of `caps-word`
 if you want to manually define which keys are capitalized (2nd parameter)
 and what the extra non-terminal+non-capitalized keys should be (3rd parameter).
 
+.Example:
 [source]
 ----
 (defalias
   cw (caps-word 2000)
 
-  ;; This example is similar to the default caps-word behaviour but it moves the
-  ;; 0-9 keys to the capitalized key list from the extra non-terminating key list.
-  cwc (caps-word-custom
-    2000
-    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
-    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
-  )
-)
-----
+  ;; This example is similar to the default caps-word behaviour but it moves the
+  ;; 0-9 keys to the capitalized key list from the extra non-terminating key list.
+  cwc (caps-word-custom
+    2000
+    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
+    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
+  )
+)
+----
+
+==== caps-word-toggle[[caps-word-toggle]]
+
+There are `-toggle` variants of the `caps-word` actions.
+By default re-pressing `caps-word` will keep `caps-word` active.
+The `-toggle` variants will end `caps-word` if it is currently active,
+otherwise `caps-word` will be activate as normal.
+
+.Example:
+[source]
+----
+(defalias
+  cwt (caps-word-toggle 2000)
+  cct (caps-word-custom-toggle
+    2000
+    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
+    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
+  )
+)
+----
+
+=== unmod[[unmod]]
+
+**Reference**
+
+The `unmod` action will deactivate modifier keys while outputting
+one or more defined keys.
+
+.Syntax:
+[source]
+----
+(unmod $key1 $key2 ... $keyN)
+(unmod ($mod1 $mod2 ... $modN) $key1 $key2 ... $keyN)
+----
+
+[cols="1,5"]
+|===
+| `$key`
+| A key name to output while unmodded.
+
+| `$mod`
+| By default `unmod` will deactivate all modifier keys.
+An optional list as the first parameter
+allows specfying a subset of modifiers to deactivate during the action.
+|===
+
+**Description**
+
+The `unmod` action will release all modifiers temporarily
+and send one or more keys.
+After the `unmod` key is released, the released modifiers are pressed again.
+The affected modifiers are: `lsft,rsft,lctl,rctl,lmet,rmet,lalt,ralt`.
+
+A variant of `unmod` is `unshift` or `un⇧`.
+This action only releases the `lsft,rsft` keys.
+This can be useful for forcing unshifted keys while AltGr is still held.
+
+NOTE: In case the modifiers to be undone are not part of `defsrc`,
+<<process-unmapped-keys>> needs to be enabled in `defcfg` in order for their
+states to be tracked correctly.
+
+.Example:
+[source]
+----
+(defalias
+  ;; holding shift and tapping a @um1 key will still output 1.
+  um1 (unmod 1)
+  ;; dead keys é (as opposed to using AltGr) that outputs É when shifted
+  dké (macro (unmod ') e)
+
+  ;; In ISO German QWERTZ, force unshifted symbols even if shift is held
+  { (unshift ralt 7)
+  [ (unshift ralt 8)
+)
+----
+
+A list may optionally be used as the first parameter of `unmod`.
+The list must be non-empty and must contain only modifier keys,
+which are the keys in the affected modifiers list from earlier in this document section.
+
+When this list exists, the action will temporarily release only the keys listed
+rather than all modifiers.
+
+.Example:
+[source]
+----
+(defalias
+	;; only unshift the alt keys
+	unalt-a (unmod (lalt ralt) a)
+)
+----
+
+[[fork]]
+=== fork
+
+**Reference**
+
+The `fork` action allows choosing between a default and an alternate action
+based on whether specific keys are active. `fork` is the equivalent of the
+basic key checks in `switch`, using none of the list logic items, i.e. virtual
+keys are not supported.
+
+.Syntax:
+[source]
+----
+(fork $left-action $right-action $right-trigger-keys)
+----
+
+[cols="1,3"]
+|===
+| `$left-action`
+| Action to activate by default.
+
+| `$right-action`
+| Action to activate if any of `$right-trigger-keys` are active.
+
+| `$right-trigger-keys`
+| List of keys that, if active when fork activates,
+causes `$right-action` to happen in place of `$left-action`.
+|===
+
+TIP: The keys `nop0-nop9` can be used as no-op outputs that
+can still be checked within `fork`, unlike what `XX` does.
+
+[[switch]]
+=== switch
+
+**Reference**
+
+The `switch` action allows conditionally activating 0 or more actions,
+depending on conditional checks.
+
+.Syntax:
+[source]
+----
+(switch
+  $logic-check1 $action1 $post-activate1
+  $logic-check2 $action2 $post-activate2
+  ...
+  $logic-checkN $actionN $post-activateN)
+----
+
+[cols="1,4"]
+|===
+| `$logic-check`
+| The condition, which if it evaluates to true,
+will trigger the corresponding action.
+
+| `$action`
+| Action to activate when logic evaluates to true.
+
+| `$post-activate`
+| Valid values are `fallthrough` and `break`.
+With `fallthrough`, when an action activates
+switch will continue evaluating further logic checks
+and potentially trigger more actions.
+With `break`, further actions will not activate.
+|===
+
+The logic check is a list.
+The items within the list can either be key names or a special list check.
+A key name item evaluates to true if that key name
+is a currently active key output of Kanata upon activating `switch`.
+The outer-most list evaluates to true
+if any of the items evaluates to true.
+
+.Syntax of logic check:
+[source]
+----
+($item1 $item2 ... $itemN)
+----
+
+.Syntax of special checks:
+[source]
+----
+(or  $item1 $item2 ... $itemN)
+(and $item1 $item2 ... $itemN)
+(not $item1 $item2 ... $itemN)
+(key-history $key-name $key-recency)
+(key-timing  $key-recency $comparator $time)
+(input         $input-type $key-name)
+(input-history $input-type $key-name $input-recency)
+(layer      $layer-name)
+(base-layer $layer-name)
+(device-history $device-id $device-recency)
+(cmd-exit   $exit-code)
+----
+
+[cols="1,4"]
+|===
+| `or`
+| Evaluates to true if any `$item` is true.
+
+| `and`
+| Evaluates to true if all of `$item` are true.
+
+| `not`
+| Evaluates to true if all of `$item` are false.
+
+| `key-history`
+| Evaluates to true if the key in the recency slot matches `$key-name`.
+A `$key-recency` of 1 is the most recent key pressed according to Kanata processing.
+The max recency is 8.
+
+| `key-timing`
+| The valid values for `$comparator` are `less-than` and `greater-than`,
+with `lt` and `gt` as shorthand if desired.
+This item evaluates to true if the key with the corresponding recency
+was pressed — for `lt` more recently than, or for `gt` later than —
+the defined `$time` with unit milliseconds.
+
+| `input`
+| Evaluates to true if the `$key-name` is currently pressed.
+The `$input-type` must be either `real` or `virtual`.
+If using `real`, this will check against the defsrc inputs.
+If using `virtual`, this will check against virtual key activations.
+
+| `input-history`
+| Evaluates to true if the input in the `$input-recency` slot matches `$key-name`.
+Two input types use the same history with respect to recency slots.
+A recency of 1 is the most recent input i.e. the input activating `switch` itself.
+The max recency is 8.
+
+| `layer`
+| Evaluates to true if the active layer matches `$layer-name`.
+
+| `base-layer`
+| Evaluates to true if the most-recently-switched-to layer
+from a `layer-switch` action matches `$layer-name`.
+
+| `device-history`
+| Evaluates to true if the device in the `$device-recency` slot
+matches `$device-id`. A recency of 1 is the most recent device
+that sent an event. The max recency is 8.
+Device IDs are defined via <<definputdevices,`definputdevices`>>.
+Currently supported on macOS only.
+
+| `cmd-exit`
+| Requires a binary compiled with `cmd` enabled.
+| Evaluates to true if the process exit code of the most recent `init-cmd` matches `$exit-code`.
+  The `$exit-code` parameter must be a 32 bit signed integer.
+|===
+
+.Syntax of optional `switch` argument `init-cmd`:
+[source]
+----
+(switch
+  (init-cmd $binary $arg1 $arg2 ... $argN)
+  $logic-check1 $action1 $post-activate1 ...)
+----
+
+**Description**
+
+Conceptually, the `switch` action is similar to <<fork>>
+but has more capabilities as well as more complexity.
+The `switch` action accepts multiple cases.
+One case is a triple of:
+
+- logic check
+- action: to activate if logic check evaluates to true
+- `fallthrough|break`: choose to continue vs. stop evaluating cases
+
+The default use of the logic check behaves similarly to fork.
+
+For example, the logic check `(a b c)` will activate the corresponding action
+if any of a, b, or c are currently pressed.
+
+TIP: the keys `nop0-nop9` can be used as no-op outputs that
+can still be checked within `switch`, unlike what `XX` does.
+
+The logic check also accepts the boolean operators `and|or|not` to allow more
+complex use cases.
+
+The order of cases matters.
+For example, if two different cases match the currently pressed keys,
+the case listed earlier in the configuration will activate first.
+If the early case uses break, the second case will not activate.
+Otherwise if fallthrough is used,
+the second case will activate sequentially after the first case.
+This idea generalizes to more than two cases,
+but the two case example is hopefully simple and effective enough.
+
+.Example:
+[source]
+----
+(defalias
+  swt (switch
+    ;; case 1
+    ((and a b (or c d) (or e f))) @ac1 break
+    ;; case 2
+    (a b c) @ac2 fallthrough
+    ;; case 3
+    () @ac3 break
+  )
+)
+----
+
+Below is a description of how this example behaves.
+
+==== Case 1
+
+----
+((and a b (or c d) (or e f))) a break
+----
+
+Translating case 1's logic check to some other common languages
+might look like:
+
+----
+(a && b && (c || d) && (e || f))
+----
+
+If the logic check passes, the action `@ac1` will activate.
+No other action will activate since `break` is used.
+
+==== Cases 2 and 3
+
+----
+(a b c) c fallthrough
+() b break
+----
+
+Case 2's key check behaves like that of `fork`, i.e.
+
+    (or a b c)
+
+or for some other common languages:
+
+    a || b || c
+
+If this logic check passes and the case 1 does not pass,
+the action `@ac2` will activate first.
+Since the logic check of case 3 always passes, `@ac3` will activate next.
+
+If neither case 1 or case 2 pass their logic checks,
+case 3 will always activate with `@ac3`.
+
+[[key-history-and-key-timing]]
+==== key-history and key-timing
+
+In addition to simple keys there are two list items
+that can be used within the case logic check
+that compare against your typed key history:
+
+* `key-history`
+* `key-timing`
+
+The `key-history` item compares the order that keys were typed.
+It accepts, in order:
+
+* a key
+* the key recency
+
+The key recency must be in the range 1-8,
+where 1 is the most recent key that was pressed
+and 8 is 8th most recent key pressed.
+
+.Example:
+[source]
+----
+(defalias
+  swh (switch
+    ((key-history a 1)) S-a break
+    ((key-history b 1)) S-b break
+    ((key-history c 1)) S-c break
+    ((key-history d 8)) (macro d d d) break
+    () XX break
+  )
+)
+----
+
+The `key-timing` compares how long ago recent key typing events occurred.
+It accepts, in order,
+
+* the key recency
+* a comparison string, which is one of: `less-than|greater-than|lt|gt`
+* number of milliseconds to compare against
+
+The key recency must be in the range 1-8,
+where 1 is the most recent key that was pressed
+and 8 is 8th most recent key pressed.
+Most use cases are expected to use a value of 1 for this parameter,
+but perhaps you can find a creative use for the other values.
+
+The comparison string determines how the actual key event timing
+will be compared to the provided timing.
+
+The number of milliseconds must be 0-65535.
+
+WARNING: The maximum milliseconds value of this configuration item
+across your whole configuration
+will be a lower bound of how long it takes for kanata to become idle
+and stop processing its state machine every approximately 1ms.
+
+.Example:
+[source]
+----
+(defalias
+  swh (switch
+    ((key-timing 1 less-than 200)) S-a break
+    ((key-timing 1 greater-than 500)) S-b break
+    ((key-timing 2 lt 1000)) S-c break
+    ((key-timing 8 gt 2000)) (macro d d d) break
+    () XX break
+  )
+)
+----
+
+==== not
+
+The examples presented so far have not included the `not` boolean operator.
+This operator will now be discussed.
+Syntactically, the `not` operator is used similarly to `or|and`.
+Functionally, it means "not **any** of" the list elements.
+
+.Example:
+[source]
+----
+(defalias
+  swn (switch
+    ((not x y z)) S-a break
+    ;; the above and below cases are equivalent in logic
+    ((not (or x y z))) S-a break
+  )
+)
+----
+
+In potentially more familiar notation, both cases have the logic:
+
+    !(x || y || z)
+
+==== input
+
+Until now, all `switch` logic has been associated to key code outputs.
+It is also possible to operate on inputs.
+Inputs can be either real keys or "virtual" (fake) keys.
+
+.Example:
+[source]
+----
+(defalias switch-input-example
+  (switch
+    ((input real lctl)) $ac1 break
+    ((input virtual vk1)) $ac2 break
+    () $ac3 break
+  )
+)
+----
+
+Similar to `key-history` for regular active keys, `input-history` also exists.
+A perhaps surprising, but hopefully logical, behaviour of input-history
+when compared to key-history is that, at the time of switch activation,
+the history of `input-history` for recency `1` will be the just-pressed input.
+In other words recency `1` is the input activating the `switch` action itself.
+Whereas with `key-history` for example, the key that will be next outputted
+may be determined by the switch logic itself, so is not in the history.
+The consequence of this is that you should use a recency of `2`
+when referring to the previously pressed input
+because the current input is in the recency `1` slot.
+
+.Example:
+[source]
+----
+(defalias switch-input-history-example
+  (switch
+    ((input-history real lsft 2)) $var1 break
+    ((input-history virtual vk2 2)) $var1 break
+    () $ac3 break
+  )
+)
+----
+
+==== layer
+
+The `layer` list item can be used in `switch` logic to operate on the active layer.
+It accepts a single layer name
+and evaluates to true if the configured layer name is the active layer,
+otherwise it evaluates to false.
+
+.Example:
+[source]
+----
+(defalias switch-layer-example
+  (switch
+     ((layer base)) x break
+    ((layer other)) y break
+                 () z break
+  )
+)
+----
+
+==== base-layer
+
+The `base-layer` list item evaluates to true
+if the configured layer name is the base layer.
+The base layer is the most recently switched-to layer
+from a `layer-switch` action,
+or the first layer defined in your configuration
+if `layer-switch` has never been activated.
+
+.Example:
+[source]
+----
+(defalias switch-layer-example
+  (switch
+     ((base-layer base)) x break
+    ((base-layer other)) y break
+                 () z break
+  )
+)
+----
+
+==== `init-cmd` and `cmd-exit`
+
+With a <<cmd,cmd-enabled>> Kanata variant
+you have access to the `init-cmd` optional switch parameter
+which goes before the normal switch syntax.
+This will execute a program synchronously,
+blocking the rest of Kanata's execution until it completes.
+What this enables is later use of `cmd-exit` logic item
+which can output different actions based on which exit code is returned by the command.
+
+.Example:
+[source]
+----
+(defalias
+  my-switch-with-cmd (switch
+    (init-cmd powershell.exe -c "if (-not (Test-Path 'myfile')) { exit 1 }")
+    ((cmd-exit 0)) a break
+    ((cmd-exit 1)) b break
+    () c break
+  ))
+----
+
+
+[[cmd]]
+=== cmd
+
+WARNING: This action does not work unless you use the appropriate binary
+or - if compiling yourself - the appropriate feature flag.
+Additionally you must add the <<danger-enable-cmd>> `defcfg` option.
+
+**Reference**
+
+The `cmd` action allows you to execute arbitrary binaries with arbitrary arguments.
+The `cmd-log` variant behaves similarly but allows customization
+of the stdout and stderr log levels within Kanata's output logging.
+The `cmd-output-keys` is like `cmd`, but stdout of the command
+will be parsed as a list of keys, output chords, and delays similar to <<macro>>
+and be typed as kanata outputs.
+
+.Syntax:
+[source]
+----
+(cmd $binary $arg1 $arg2 ... $argN)
+(cmd-log $stdout-log-level $stderr-log-level)
+(cmd-output-keys $binary $arg1 $arg2 ... $argN)
+----
+
+[cols="1,3"]
+|===
+| `$binary`
+| Executable binary to run.
+
+| `$arg`
+| Argument passed into the binary.
+
+| `$stdout-log-level`
+| Log level for stdout of the command. Must be `+debug+`, `+info+`, `+warn+`, `+error+`, or `+none+`.
+
+| `$stderr-log-level`
+| Log level for stderr of the command. Must be `+debug+`, `+info+`, `+warn+`, `+error+`, or `+none+`.
+|===
+
+**Description**
+
+The `+cmd+` action executes a program with arguments. It accepts one or more
+strings. The first string is the program that will be run and the following
+strings are arguments to that program. The arguments are provided to the
+program in the order written in the config file.
+Lists may also be used within `cmd`
+which you may desire to do for reuse via `defvar`.
+Lists will be flattened such that arguments are provided to the program
+in the order written in the config file, regardless of list nesting.
+To be technical, it would be a depth-first flattening (similar to DFS).
+
+Commands are executed directly and not via a shell, so you cannot make
+use of environment variables or symbols with special meaning.
+For example `+~+` or `+$HOME+` in Linux will not be
+substituted with your home directory.
+If you want to execute with a shell program
+use the shell as the first parameter, e.g. `bash` or `powershell.exe`.
+
+The user executing the command
+is the user that kanata was started with.
+For example, if kanata was started by root,
+the command will be run by the root user.
+If you need to execute as a different user,
+on Unix platforms you can use `sudo -u USER`
+before the rest of your command to achieve this.
+
+.Example:
+[source]
+----
+(defalias
+  cm1 (cmd rm -fr /tmp/testing)
+
+  ;; You can use bash -c and then a quoted string to execute arbitrary text in
+  ;; bash. All text within double-quotes is treated as a single string.
+  cm2 (cmd bash -c "echo hello world")
+
+  ;; You can prefix commands with sudo -u USER
+  ;; to execute commands as a different user.
+  cm3 (cmd sudo -u other_user bash -c "echo goodbye")
+)
+----
+
+By default, `+cmd+` logs start of command, completion of command, stdout, and stderr.
+Using the variant `+cmd-log+`, these log levels can be changed, and even disabled.
+It takes two arguments, `+<log_level>+` and `+<error_log_level>+`. `+<log_level>+`
+will be the level where the command to run, stdout, and stderr are logged.
+The error channel is logged only if there is a failure with running the
+command (typically if the command can't be found, or there is trouble spawning it).
+
+The valid levels are `+debug+`, `+info+`, `+warn+`, `+error+`, and `+none+`.
+
+.Example:
+[source]
+----
+(defalias
+  ;; The first two arguments are the log levels, then just the normal command
+  ;; This will only error if `bash` is not found or something else goes
+  ;; wrong with the initial execution. Any logs produced by bash will not
+  ;; be shown.
+  noisy-cmd (cmd-log none error bash -c "echo hello this produces a log")
+
+  ;; This will only log the output of the command, but it won't start
+  ;; because the command doesn't exist.
+  ignore-failure-cmd (cmd-log info none thiscmddoesnotexist)
+
+  verbose-only-log (cmd-log verbose verbose bash -c "echo yo")
+)
+----
+
+There is a variant of `cmd`: `cmd-output-keys`. This variant reads the output
+of the executed program and reads it as an S-expression, similarly to the
+<<macro, macro action>>. However — unlike macro — only delays, keys, chords, and
+chorded lists are supported. Other actions are not supported.
+
+[source]
+----
+(defalias
+  ;; bash: type date-time as YYYY-MM-DD HH:MM
+  pdb (cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'")
+
+  ;; powershell: type date-time as YYYY-MM-DD HH:MM
+  pdp (cmd-output-keys powershell.exe "echo '(' (((Get-Date -Format 'yyyy-MM-dd HH:mm').toCharArray() -join ' ').insert(20, ' spc ') -replace ':','S-;') ')'")
+)
+----
+
+[[push-msg]]
+=== push-msg
+
+NOTE: This action requires the TCP server to be enabled via the
+<<args-port,`-p` / `--port`>> command line argument.
+If used without the TCP server enabled, a warning will be logged
+and the action will have no effect.
+
+**Reference**
+
+The `push-msg` action sends an arbitrary message to all connected TCP clients.
+This enables communication between your keyboard configuration and external tools
+without the security risks or performance overhead of executing shell commands.
+
+.Syntax:
+[source]
+----
+(push-msg $message)
+----
+
+[cols="1,3"]
+|===
+| `$message`
+| A string or S-expression to send to TCP clients.
+  Strings are sent as-is; S-expressions are converted to JSON arrays.
+|===
+
+**Description**
+
+The `push-msg` action broadcasts a message to all TCP clients connected to Kanata's
+TCP server. This is useful for:
+
+- Triggering external tool actions from keyboard shortcuts
+- Layer change notifications to status bars or tray applications
+- Integration with automation tools like Raycast, Alfred, or Hammerspoon
+- Controlling other applications without spawning shell processes
+
+Messages are sent as newline-terminated JSON in the format:
+
+[source,json]
+----
+{"MessagePush":{"message":"your-message-here"}}
+----
+
+Compared to the <<cmd>> action, `push-msg` offers:
+
+- **Better security**: No shell execution, no privilege escalation risks
+- **Better performance**: Sub-millisecond latency vs ~100ms for command execution
+- **No special flags**: Does not require `danger-enable-cmd` in defcfg
+
+.Example - Basic messages:
+[source]
+----
+(defalias
+  ;; Send a simple string message
+  notify (push-msg "key-pressed")
+
+  ;; Send layer change notification
+  nav-on (push-msg "layer:nav:activated")
+  nav-off (push-msg "layer:nav:deactivated")
+)
+----
+
+.Example - Integration with external tools:
+[source]
+----
+(defalias
+  ;; Trigger a Raycast extension
+  raycast-clip (push-msg "raycast:clipboard-history")
+
+  ;; Control media playback via external script
+  play-pause (push-msg "media:toggle")
+  next-track (push-msg "media:next")
+
+  ;; Switch keyboard layouts via external tool
+  layout-next (push-msg "xkb:next-layout")
+)
+----
+
+.Example - Using with defvirtualkeys for external triggering:
+[source]
+----
+;; Define virtual keys that can be triggered via TCP's ActOnFakeKey command
+;; External tools can trigger these using: {"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}
+(defvirtualkeys
+  email-sig (macro S-b e s t spc r e g a r d s , ret ret S-j o h n)
+  nav-mode (layer-switch nav)
+)
+
+;; Combine push-msg with other actions
+(defalias
+  launch-term (multi
+    (push-msg "app:launch:terminal")
+    (layer-switch base)
+  )
+)
+----
+
+To receive these messages, connect a TCP client to Kanata's server port.
+See the https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example TCP client]
+for implementation guidance.
+
+[[clipboard-actions]]
+=== clipboard actions
+
+**Reference**
+
+Clipboard actions can manipulate the operating system clipboard
+alongside "save ids".
+To paste, you would use an action such as `C-v`;
+Kanata has no builtin paste action.
+
+.Syntax:
+[source]
+----
+(clipboard-set   $clipboard-string)
+(clipboard-save  $save-id)
+(clipboard-restore    $save-id)
+(clipboard-save-swap  $save-id $save-id)
+(clipboard-cmd-set  $binary $arg1 $arg2 ... $argN)
+(clipboard-save-cmd-set  $save-id $binary $arg1 $arg2 ... $argN)
+----
+
+[cols="1,3"]
+|===
+| `clipboard-set`
+| Sets the clipboard to the specified string.
+
+| `clipboard-save`
+| Saves the current clipboard content with the specified ID.
+
+| `clipboard-restore`
+| Sets the clipboard to content saved with the specified ID.
+If the save ID content is blank, this will do nothing.
+
+| `clipboard-save-swap`
+| Swaps the content of two save IDs.
+
+| `clipboard-cmd-set`
+| Sets the clipboard to the output of the command.
+The current content of the clipboard is passed to stdin of the command
+if the current content is text.
+If the content is an image, nothing is passed to stdin.
+
+| `clipboard-save-cmd-set`
+| Sets the save ID content to the output of the command.
+The current content of the save ID is passed to stdin of the command
+if the current content is text.
+If the content is an image, nothing is passed to stdin.
+
+| `$clipboard-string`
+| Fixed string to set the operating system clipboard to.
+
+| `$save-id`
+| A number `0-65535` representing an ID of saved clipboard content.
+
+| `$binary`
+| Executable binary to run.
+
+| `$arg`
+| Argument passed into the binary.
+|===
+
+**Description**
+
+You can use clipboard actions to save clipboard content,
+paste arbitrary content,
+and then restore the original clipboard content.
+This functionality is similar to what some text expanders do.
+You can additionally use shell commands to manipulate
+clipboard content in arbitrary ways.
+This can all be done in a single command via <<macro>>.
+
+Note that you will likely want to add delays in between components,
+because clipboard systems take some time to propagate updates.
+
+The example below is a macro that pastes the content of the clipboard
+twice with a space in between,
+while restoring the original clipboard content at the end.
+Notable is that the example uses `C-v` but this may not work for you.
+If you have OS-level remapping, the `v` may be different
+to effectively paste.
+Something that may also work is `S-ins`
+
+.Example:
+[source]
+----
+(macro
+ (clipboard-save 0)
+ 20
+ (clipboard-cmd-set powershell.exe -c r#"$v = ($Input | Select-Object -First 1); Write-Host -NoNewLine "$v $v""#)
+ 300
+ C-v
+ (clipboard-restore 0)
+)
+----
+
+As another example you can use templates
+with clipboard actions to have a convenient clipboard-based
+text output while preserving the old clipboard content.
+This can fit the use case of "text expansion".
+
+.Example:
+[source]
+----
+(deftemplate text-paste (text)
+ (macro
+  (clipboard-save 0)
+  20
+  (clipboard-set $text)
+  300
+  C-v
+  (clipboard-restore 0)
+ ))
+
+(defalias
+ myalias1 (t! text-paste "Hello world")
+ myalias2 (t! text-paste "Goodbye my old friend")
+)
+----
+
+[[arbitrary-code]]
+=== arbitrary-code
+
+The `arbitrary-code` action allows sending an arbitrary number to kanata's
+output mechanism. The press is sent when pressed, and the release sent when
+released. This action can be useful for testing keys that are not yet named or
+mapped in kanata. Please contribute findings with names and mappings, either in
+a GitHub issue or as a pull request!
+
+WARNING: This is not cross platform!
+
+WARNING: When using the Interception driver, this action is still sent over
+SendInput.
+
+[source]
+----
+(defalias ab1 (arbitrary-code 700))
+----
+
+[[global-overrides]]
+== Global overrides
+
+The `defoverrides` optional configuration item allows you to create global
+key overrides, irrespective of what actions are used to generate those keys.
+It accepts pairs of lists:
+
+1. the input key list that gets replaced
+2. the output key list to replace the input keys with
+
+Both input and output lists accept 0 or more modifier keys (e.g. lctl, rsft)
+and exactly 1 non-modifier key (e.g. 1, bspc).
+
+Only zero or one `defoverrides` is allowed in a configuration file.
+
+NOTE: Depending on your use case
+you may want to adjust <<override-release-on-activation>> in `defcfg`.
+
+.Example:
+[source]
+----
+;; Swap numbers and their symbols with respect to shift
+(defoverrides
+  (1) (lsft 1)
+  (2) (lsft 2)
+  ;; repeat for all remaining numbers
+
+  (lsft 1) (1)
+  (lsft 2) (2)
+  ;; repeat for all remaining numbers
+)
+----
+
+[[defoverridesv2]]
+=== defoverridesv2
+
+There is a more recent version of defoverrides that offers more customizability.
+Instead of 2 list items per override entry,
+`defoverridesv2` mandates 4, though the extra 2 can be empty.
+
+You cannot have both a v1 and v2 of `defoverrides` at the same time.
+
+The 3rd item is an "exclude modifiers list" which is composed of modifier key names
+(such as `lctl`, `lalt`) that, if held, will disable the override from activating.
+
+NOTE: if all excluded list modifiers are released while the
+override input is still active, the override will activate.
+You can avoid this by ensuring to always release the non-modifier key
+before releasing any modifiers.
+
+The 4th item is an "exclude layers" list which is composed of layer names
+that while active as the most recent `layer-switch` or `layer-while-held`,
+will disable the override from activating.
+
+NOTE: if the layer changes while the override input is still active,
+the override will activate.
+
+.Example:
+[source]
+----
+(defoverridesv2
+  ;; lctl+a will become lalt+9
+  ;; except when lsft is held or other-layer is active.
+  (lctl a) (lalt 9) (lsft) (other-layer))
+
+  ;; lctl+b will always become lalt+0
+  (lctl b) (lalt 0) () ()
+)
+----
+
+[[templates]]
+== Templates
+
+The top-level configuration item `deftemplate`
+declares a template that can be expanded multiple times
+via the list item `template-expand`.
+The short form of `template-expand` is `t!`.
+
+The parameters to `deftemplate` in order are:
+
+* Template name
+* List of template variables
+* Template content (any combination of lists / strings)
+
+Within the template content, variable names prefixed with `$`
+will be substituted with the expression passed into `template-expand`.
+
+The list item `template-expand` can be placed as a top-level list
+or within another list.
+Its parameters in order are:
+
+* template name
+* parameters to substitute into the template
+
+NOTE: Template expansion happens after file includes and before any other parsing.
+One consequence of this early parsing is that variables defined in `defvar`
+are **not** substituted when used inside of `template-expand`.
+This has consequences for condtional content, e.g. with `if-equal`.
+This is discussed further in Example 5.
+
+Example 1:
+
+In a simple example, let's say you wanted to set a large group of keys
+to do something different when you're holding alt. Yes, this could also
+be handled with remapping alt to a layer shift, but there are cases where
+you wouldn't want this. Rather than retyping the code with `fork` and
+`unmod` (to release alt) a bunch of times, you could template it like so:
+[source]
+----
+(deftemplate alt-fork (original-action new-action)
+  (fork $original-action (multi (unmod (ralt lalt) nop0) $new-action) (lalt ralt))
+)
+(defsrc 1 2 3)
+(defalias fn1 (template-expand alt-fork 1 f1))
+;; Templates are a simple text substitution, so the above is exactly equivalent to:
+;; (defalias fn1 (fork 1 (multi (unmod (ralt lalt) nop0) f1) (lalt ralt)))
+(defalias fn2 (template-expand alt-fork 2 f2))
+;; You can use t! as a short form of template-expand
+(defalias fn3 (t! alt-fork 3 f3))
+(deflayer default @fn1 @fn2 @fn3)
+----
+
+.Example 2:
+[source]
+----
+(defvar chord-timeout 200)
+(defcfg process-unmapped-keys yes)
+
+;; This template defines a chord group and aliases that use the chord group.
+;; The purpose is to easily define the same chord position behaviour
+;; for multiple layers that have different underlying keys.
+(deftemplate left-hand-chords (chordgroupname k1 k2 k3 k4 alias1 alias2 alias3 alias4)
+  (defalias
+    $alias1 (chord $chordgroupname $k1)
+    $alias2 (chord $chordgroupname $k2)
+    $alias3 (chord $chordgroupname $k3)
+    $alias4 (chord $chordgroupname $k4)
+  )
+  (defchords $chordgroupname $chord-timeout
+    ($k1) $k1
+    ($k2) $k2
+    ($k3) $k3
+    ($k4) $k4
+    ($k1 $k2) lctl
+    ($k3 $k4) lsft
+  )
+)
+
+(template-expand left-hand-chords qwerty a s d f qwa qws qwd qwf)
+;; t! is short for template-expand
+(t! left-hand-chords dvorak a o e u dva dvo dve dvu)
+
+(defsrc a s d f)
+(deflayer dvorak @dva @dvo @dve @dvu)
+(deflayer qwerty @qwa @qws @qwd @qwf)
+----
+
+.Example 3:
+[source]
+----
+;; This template defines a home row that customizes a single key's behaviour
+(deftemplate home-row (j-behaviour)
+  a s d f g h $j-behaviour k l ; '
+)
+
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+       ;; usable even inside defsrc
+  caps (t! home-row j)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+
+(deflayer base
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+                                 ;; lists can be passed in too!
+  caps (t! home-row (tap-hold 200 200 j lctl))    ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+----
+
+=== if-equal
+
+Within a template you can use the list item `if-equal`
+to have conditionally-used items within a template.
+
+It accepts a minimum of 2 parameters.
+The first two parameters must be strings and are compared
+against each other.
+If they match, the following parameters are inserted into
+the template in place of the `if-equal` list.
+Otherwise if the strings do not match
+then the whole `if-equal` list is removed from the template.
+
+.Example 4:
+----
+(deftemplate home-row (version)
+  a s d f g h
+  (if-equal $version v1 j)
+  (if-equal $version v2 (tap-hold 200 200 j lctl))
+   k l ; '
+)
+
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row v1)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+
+(deflayer base
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row v2)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+----
+
+Similar to `if-equal` are three more conditional operators for templates:
+
+* `if-not-equal`
+** the content is used if the first two string parameters are not equal
+* `if-in-list`
+** the content is used if the first string parameter exists in
+the second list-of-strings parameter
+* `if-not-in-list`
+** the content is used if the first string parameter does not exist in
+the second list-of-strings parameter
+
+.Example 5:
+----
+;; defvar is parsed AFTER template expansion occurs.
+(defvar a hello)
+
+(deftemplate template1 (var1)
+  a (if-equal hello $var1 b) c
+)
+
+;; Below will expand to: `a c` because the string
+;; $a itself is compared against the string hello
+;; and they are not equal.
+(template-expand template1 $a)
+
+(deftemplate template2 (var1)
+  a (if-equal $a $var1 b) c
+)
+
+;; Below will expand to: `a b c` because the string
+;; $a is compared against the string $a and they are equal.
+;; But note that the variable $a is still not substituted
+;; with its defvar value of: hello.
+(template-expand template2 $a)
+----
+
+[[concat-in-deftemplate]]
+=== concat in deftemplate
+
+Like <<concat-in-defvar,concat in defvar>>,
+a list beginning with `concat` within the content of `deftemplate`
+will be replaced with a single string that consists of
+all the subsequent items in the list concatenated to each other.
+
+== Include other files[[include]]
+
+The `include` optional configuration item
+allows you to include other files into the configuration.
+This configuration accepts a single string which is a file path.
+The file path can be an absolute path or a relative path.
+The path will be relative to the defined configuration file.
+
+At the time of writing, includes can only be placed at the top level.
+The included files also cannot contain includes themselves.
+
+Non-existing files will be ignored.
+
+.Example:
+----
+;; This is in the file initially read by kanata, e.g. kanata.kbd
+(include other-file.kbd)
+
+;; This is in the other file
+(defalias
+  included-alias XX
+  ;; ...
+)
+
+;; This is in the other file
+(deflayer included-layer
+  ;; ...
+)
+----
+
+[[platform]]
+== Platform-specific configuration
+
+If you put any top-level configuration item
+within a list beginning with `platform`,
+it will become a platform-specific configuration
+that is only active for the specified platforms.
+
+.Syntax:
+[source]
+----
+(platform (applicable-platforms) ...)
+----
+
+The valid values for applicable platforms are:
+
+- `win`
+- `winiov2`
+- `wintercept`
+- `linux`
+- `macos`
+
+.Example:
+[source]
+----
+(platform (macos)
+  ;; Only on macos, use command arrows to jump/delete words
+  ;; because command is used for so many other things
+  ;; and it's weird that these cases use alt.
+  (defoverrides
+    (lmet bspc) (lalt bspc)
+    (lmet left) (lalt left)
+    (lmet right) (lalt right)
+  )
+)
+
+(platform (win winiov2 wintercept)
+  (defalias run-my-script (cmd #| something involving powershell |#))
+)
+
+(platform (macos linux)
+  (defalias run-my-script (cmd #| something involving bash |#))
+)
+----
+
+[[environment]]
+== Environment-conditional configuration
+
+.Syntax:
+[source]
+----
+(environment (env-var-name env-var-value) ...)
+----
+
+The items `env-var-name` and `env-var-value` can be arbitrary strings.
+The name is the environment variable that is read
+for determining if the configuration is used or not.
+If the value of the environment variable (set only on kanata startup)
+matches `env-var-value`, the configuration is used; otherwise it is ignored.
+An empty string for `env-var-value` — `""` — will use the configuration
+if the environment variable is an empty string
+and also if the environment variable is not defined.
+
+.Example:
+[source]
+----
+(environment (LAPTOP lp1)
+  (defalias met @lp1met)
+)
+
+(environment (LAPTOP lp2)
+  (defalias met @lp2met)
+)
+----
+
+.Set environment variables in the current terminal process:
+[source]
+----
+# powershell
+$env:VAR_NAME = "var_value"
+
+# bash
+VAR_NAME=var_value
+----
+
+
+[[input-chords-v2]]
+== Input chords / combos (v2)
+
+You may define a single `+defchordsv2+` configuration item.
+This enables you to define global input chord behaviour.
+One might also find this functionality called another name of "combos"
+in other projects.
+
+Input chords enables you to press two or more keys in quick succession
+to activate a different action
+than would normally be associated with those keys.
+When activating a chord, the order of presses is not important;
+when all keys belonging to a chord are pressed,
+the action activates regardless of press order.
+
+The `+defchordsv2+` feature is configured as shown below:
+
+.Syntax example
+[source]
+----
+(defchordsv2
+  (participating-keys1) action1 timeout1 release-behaviour1 (disabled-layers1)
+    ...
+  (participating-keysN) actionN timeoutN release-behaviourN (disabled-layersN)
+)
+----
+
+The configuration is made up of 5-tuples of:
+
+[cols="1,3"]
+|===
+| `$participating-keys`
+| These are key names you would use in `defsrc`.
+A minimum of two keys must be defined per chord.
+The list must be unique per chord.
+
+| `$action`
+| These are actions as you would configure in `deflayer` or `defalias`.
+The action activates if all participating keys are activated
+within the timeout.
+
+| `$timeout`
+| The time (unit: milliseconds) within which,
+if all participating keys are pressed,
+the chord action will activate;
+otherwise the key presses are handled by the active layer.
+The time begins when the first participant is pressed.
+
+| `$release-behaviour`
+| This must be either `first-release` or `all-released`;
+`first-release` means the chord action will be released
+when the first participant is released,
+while `all-released` means the chord action will be released
+only when all of the participants have been released.
+
+| `$disabled-layers`
+| A list of layer names on which this chord is disabled.
+|===
+
+Input chords have a related `defcfg` item: <<chords-v2-min-idle>>.
+When any non-chord activation happens,
+a timeout begins with duration configured by
+`chords-v2-min-idle` (unit: milliseconds).
+Until this timeout expires, all inputs will immediately skip
+chords processing and be processed by the active layer.
+
+IMPORTANT: When opting into input chords v2,
+you must enable `concurrent-tap-hold`.
+This is enforced for a more responsive `tap-hold` experience when
+activated by a chord.
+
+.Example:
+[source]
+----
+(defcfg concurrent-tap-hold yes)
+(defchordsv2
+  (a s)    c                200 all-released  (non-chord-layer)
+  (a s d) (macro h e l l o) 250 first-release (non-chord-layer)
+  (s d f) (macro b y e)     400 first-release (non-chord-layer)
+)
+----
+
+NOTE: Also see <<input-chords,v1 chords>>,
+which are configured differently and can be defined per-layer.
+
+[[chordsv2-processing-order]]
+=== Action processing order
+
+The chordsv2 system handles keys before any layer action handling.
+This has a consequence of not entering the delay and interruption flow
+of actions such as `tap-hold-release`.
+
+If you want a chordsv2 action activation to be processed
+by the aforementioned category of actions
+you can move the action into a virtual key
+(see <<virtual-keys>>) and have the chordsv2 action
+press and release the virtual key.
+
+See a sample below that showcases a reusable template.
+
+.Example:
+[source]
+----
+(defcfg concurrent-tap-hold yes)
+(defsrc)
+(deflayermap (base)
+  caps (tap-hold-release 0 200 esc lctl))
+
+;; defines a vkey named v-$key, example v-bspc
+;; and an alias @v-bspc that press and and releases the v-key
+;; within on-press and on-release respectively.
+(deftemplate v- (key)
+  (defvirtualkeys (concat v- $key) $key)
+  (defalias (concat v- $key)
+    (multi (on-press press-vkey (concat v- $key)) (on-release release-vkey (concat v- $key))))
+)
+
+(t! v- bspc)
+(t! v- del)
+(defchordsv2
+  (j k) @v-bspc 75 first-release ()
+  (s d) @v-del 75 first-release ()
+)
+----
+
+[[definputdevices]]
+== definputdevices
+
+**Reference**
+
+The optional `definputdevices` block maps user-chosen numeric device IDs
+to physical input devices, enabling per-device key mappings via the
+<<switch,`switch`>> action's `(device-history $id $recency)` condition.
+
+.Syntax:
+[source]
+----
+(definputdevices
+  $id1 ($matcher1a $matcher1b ...)
+  $id2 ($matcher2a ...)
+  ...
+)
+----
+
+[cols="1,4"]
+|===
+| `$id`
+| An integer from 1-255 used to reference this device in `(device-history $id $recency)` conditions. The value is arbitrary; use `defvar` to give IDs meaningful names.
+
+| `($matcher ...)`
+| A list of matcher expressions. All matchers within an entry must match for a device to be assigned that ID (AND semantics).
+|===
+
+.Available matchers:
+[cols="1,4"]
+|===
+| `(name "...")`
+| Matches devices whose product name contains the given string.
+
+| `(hash "...")`
+| Matches devices whose hex hash equals the given string.
+Use `kanata --list` to see device hashes.
+
+| `(vendor_id N)`
+| Matches devices with the given USB vendor ID. Valid values: decimal 0-65535, or hex `0x0-0xFFFF`.
+
+| `(product_id N)`
+| Matches devices with the given USB product ID. Valid values: decimal 0-65535, or hex `0x0-0xFFFF`.
+|===
+
+**Description**
+
+`definputdevices` is useful when you have multiple keyboards with different
+physical layouts and want to unify their behavior — for example, to remap
+swapped modifier key positions between Ctrl, Meta, and Alt across devices.
+
+The kanata-defined IDs are arbitrary numbers whose only purpose is referencing
+within the `switch` action's `(device-history $id $recency)` condition.
+Using `defvar` to name them is recommended for readability.
+
+Device history only records press events (not release or repeat).
+If a key is pressed on a device not listed in `definputdevices`, the history
+slot will be recorded as "unknown" and will not match any device ID.
+
+.Example:
+[source]
+----
+(defvar
+  id-AppleInternal 1
+  id-Go60          2
+)
+
+(definputdevices
+  $id-AppleInternal ((name "Apple Internal Keyboard"))
+  $id-Go60 ((name "Go60") (vendor_id 0x1D50) (product_id 0x615E))
+)
+
+(defsrc a)
+(deflayer base
+  (switch
+    ((device-history $id-AppleInternal  1)) x break
+    ((device-history $id-Go60           1)) y break
+    () a break))
+----
+
+In this example, pressing `a` on the internal keyboard outputs `x`,
+pressing `a` on the Go60 outputs `y`, and pressing `a` on any other
+device outputs `a`.
+
+NOTE: Device IDs are matched at startup. Devices plugged in after kanata
+starts will not be recognized. Live reload does not re-read device mappings.
+
+NOTE: Currently supported on macOS only. Linux support is planned.
+
+[[optional-defcfg-options]]
+== defcfg options
+
+[[danger-enable-cmd]]
+=== danger-enable-cmd
+
+This option can be used to enable the `cmd` action in your configuration. The
+`+cmd+` action allows kanata to execute programs with arguments passed to them.
+
+This requires using a kanata program that is compiled with the `cmd` action
+enabled. The reason for this is so that if you choose to, there is no way for
+kanata to execute arbitrary programs even if you download some random
+configuration from the internet.
+
+This configuration is disabled by default and can be enabled by giving it the
+value `yes`.
+
+.Example:
+[source]
+----
+(defcfg
+  danger-enable-cmd yes
+)
+----
+
+[[sequence-timeout]]
+=== sequence-timeout
+
+This option customizes the key sequence timeout (unit: ms). Its default value
+is 1000. The purpose of this item is explained in <<sequences>>.
+
+.Example:
+[source]
+----
+(defcfg
+  sequence-timeout 2000
+)
+----
+
+[[sequence-input-mode]]
+=== sequence-input-mode
+
+This option customizes the key sequence input mode. Its default value when not
+configured is `hidden-suppressed`.
+
+The options are:
+
+- `visible-backspaced`: types sequence characters as they are inputted. The
+  typed characters will be erased with backspaces for a valid sequence termination.
+- `hidden-suppressed`: hides sequence characters as they are typed. Does not
+  output the hidden characters for an invalid sequence termination.
+- `hidden-delay-type`: hides sequence characters as they are typed. Outputs the
+  hidden characters for an invalid sequence termination either after a
+  timeout or after a non-sequence key is typed.
+
+For `visible-backspaced` and `hidden-delay-type`, a sequence leader input will
+be ignored if a sequence is already active. For historical reasons, and in case
+it is desired behaviour, a sequence leader input using `hidden-suppressed` will
+reset the key sequence.
+
+See <<sequences>> for more about sequences.
+
+.Example:
+[source]
+----
+(defcfg
+  sequence-input-mode visible-backspaced
+)
+----
+
+
+[[sequence-backtrack-modcancel]]
+=== sequence-backtrack-modcancel
+
+This option customizes the behaviour of key sequences
+when modifiers are used.
+The default is `yes` and can be overridden to `no` if desired.
+
+Setting it to `yes` allows both `fk1` and `fk2` to be activated
+in the following configuration, but with `no`,
+`fk1` will be impossible to activate
+
+----
+(defseq
+  fk1 (lsft a b)
+  fk2 (S-(c d))
+)
+----
+
+See <<sequences>> for more about sequences and
+https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[this document]
+for more context about this specific configuration.
+
+.Example:
+[source]
+----
+(defcfg
+  sequence-backtrack-modcancel no
+)
+----
+
+[[log-layer-changes]]
+=== log-layer-changes
+
+By default, kanata will log layer changes. However, logging has some processing
+overhead. If you do not care for the logging, you can choose to disable it.
+
+.Example:
+[source]
+----
+(defcfg
+  log-layer-changes no
+)
+----
+
+If `+--log-layer-changes+` is passed as a command line argument,
+a `no` in the configuration file will be overridden
+and layer changes will again be logged.
+This flag can be helpful when testing new configuration changes
+while keeping the default behaviour as "no logging" to save on processing,
+so that the `defcfg` item does not need to be adjusted back and forth
+when experimenting vs. stable usage.
+
+[[delegate-to-first-layer]]
+=== delegate-to-first-layer
+
+
+By default, transparent keys on layers
+will delegate to the corresponding defsrc key
+when found on a layer activated by `layer-switch`.
+
+This config entry changes the behaviour
+to delegate to the action in the same position on the first layer defined
+in the configuration, which is the active layer on startup.
+
+For more context, see https://github.com/jtroo/kanata/issues/435.
+
+.Example:
+[source]
+----
+(defcfg
+  delegate-to-first-layer yes
+)
+----
+
+
+[[movemouse-inherit-accel-state]]
+=== movemouse-inherit-accel-state
+
+By default `movemouse-accel` actions will track the acceleration
+state for vertical and horizontal axes separately.
+
+When this setting is enabled, `movemouse-accel` will behave exactly like mouse movements in https://qmk.fm[QMK],
+i.e. the acceleration state of new mouse
+movement actions will be inherited if others are already being pressed.
+
+.Example:
+[source]
+----
+(defcfg
+  movemouse-inherit-accel-state yes
+)
+----
+
+[[movemouse-smooth-diagonals]]
+=== movemouse-smooth-diagonals
+
+By default, mouse movements move one direction at a time
+and vertical/horizontal movements are on independent timers.
+
+This can result in non-smooth diagonals when drawing a line in some app.
+This option adds a small imperceptible amount of latency to
+synchronize the mouse movements.
+
+.Example:
+[source]
+----
+(defcfg
+  movemouse-smooth-diagonals yes
+)
+----
+
+=== dynamic-macro-max-presses [[dynamic-macro-max-presses]]
+
+This configuration allows you to customize the length limit on dynamic macros.
+The default length limit is 128 keys.
+
+.Example:
+[source]
+----
+(defcfg
+  dynamic-macro-max-presses 1000
+)
+----
+
+=== concurrent-tap-hold [[concurrent-tap-hold]]
+This configuration makes multiple tap-hold actions
+that are activated near in time expire their timeout quicker.
+By default this is disabled.
+When disabled, the timeout for a following tap-hold
+will start from 0ms **after** the previous tap-hold expires.
+When enabled, the timeout will start
+as soon as the tap-hold action is pressed
+even if a previous tap-hold action is still held and has not expired.
+
+.Example:
+[source]
+----
+(defcfg
+  concurrent-tap-hold yes
+)
+----
+
+[[block-unmapped-keys]]
+=== block-unmapped-keys
+
+If you desire to use only a subset of your keyboard
+you can use `block-unmapped-keys` to make every key
+other than those that exist in `defsrc` a no-op.
+
+NOTE: this only functions correctly if you also set
+<<process-unmapped-keys>> to yes.
+
+.Example:
+[source]
+----
+(defcfg
+  block-unmapped-keys yes
+)
+----
+
+[[rapid-event-delay]]
+=== rapid-event-delay
+
+This configuration applies to the following events:
+
+* the release of one-shot-press activation
+* the release of the tapped key in a tap-hold activation
+* a non-eager tap-dance activation from interruption by another key
+* input chord activations, both v1 and v2
+
+Key event processing is paused the defined number of milliseconds (approximate).
+The default value is 5.
+
+There will be a minor input latency impact in the mentioned scenarios.
+Since 5ms is 1 frame at 200 Hz refresh rate,
+in most scenarios this will not be perceptible.
+
+The reason for this configuration existing is that some environments
+do not process the scenarios correctly due to the rapidity of key events.
+Kanata does send the events in the correct order,
+so the fault is more in the environment,
+but kanata provides a workaround anyway.
+
+If you are negatively impacted by the latency increase of these events
+and your environment is not impacted by increased rapidity,
+you can reduce the value to a number between 0 and 4.
+
+.Example:
+[source]
+----
+(defcfg
+  ;; If your environment is particularly buggy, might need to delay even more
+  rapid-event-delay 20
+)
+----
+
+[[chords-v2-min-idle]]
+=== chords-v2-min-idle
+
+This configuration affects the timer during which chords processing is disabled.
+NOTE: For more info, see <<input-chords-v2>>.
+
+The default (and minimum) value is `5` and the unit is milliseconds.
+
+.Example:
+[source]
+----
+(defcfg
+  chords-v2-min-idle 200
+)
+----
+
+[[tap-hold-require-prior-idle]]
+=== tap-hold-require-prior-idle
+
+This configuration applies to all `tap-hold` variants.
+When a different physical key was pressed within the configured number of
+milliseconds before a `tap-hold` key is pressed, the `tap-hold` key will
+immediately resolve as its tap action without entering the waiting state.
+This prevents accidental modifier activations during fast typing.
+The concept is equivalent to ZMK's `require-prior-idle-ms`.
+
+NOTE: For more info, see <<tap-hold>>.
+
+The default value is `0` (disabled) and the unit is milliseconds.
+
+.Example:
+[source]
+----
+(defcfg
+  tap-hold-require-prior-idle 150
+)
+----
+
+- If you type a normal key and then press a `tap-hold` key within the threshold,
+  the `tap-hold` key immediately outputs its tap action.
+- If the keyboard is idle for longer than the threshold before pressing a `tap-hold` key,
+  normal `tap-hold` behavior applies (waiting state, hold on timeout, etc.).
+- When `tap-hold-require-prior-idle` triggers, the tap action is chosen before any other
+  `tap-hold` configuration (e.g., `tap-hold-opposite-hand`, `concurrent-tap-hold`)
+  is consulted.
+
+==== Per-action override
+
+The global `tap-hold-require-prior-idle` value can be overridden on individual
+`tap-hold` actions using the `(require-prior-idle <ms>)` option.
+This is useful when most keys benefit from idle detection (e.g., home-row mods)
+but specific keys (e.g., a layer-tap key) need immediate activation even during
+fast typing.
+
+The option can be appended to any `tap-hold` variant as a trailing
+`(keyword value)` list:
+
+.Example: disable for a specific key
+[source]
+----
+(defcfg tap-hold-require-prior-idle 150)
+(defalias
+  ;; HRMs use the global 150ms threshold
+  a (tap-hold 200 200 a lmet)
+  s (tap-hold 200 200 s lalt)
+  ;; Layer key disables idle detection for immediate activation
+  nav (tap-hold 200 200 tab (layer-toggle nav) (require-prior-idle 0))
+)
+----
+
+.Example: enable for a specific key without a global setting
+[source]
+----
+(defalias
+  a (tap-hold 200 200 a lmet (require-prior-idle 150))
+)
+----
+
+- `(require-prior-idle 0)` disables the feature for that action,
+  even when a global threshold is set.
+- A non-zero value enables or changes the threshold for that action only.
+- When no per-action override is specified, the global `defcfg` value is used.
+- Works with all `tap-hold` variants: `tap-hold`, `tap-hold-press`,
+  `tap-hold-release`, `tap-hold-press-timeout`, `tap-hold-release-timeout`,
+  `tap-hold-release-keys`, `tap-hold-except-keys`, `tap-hold-tap-keys`,
+  and `tap-hold-opposite-hand`.
+
+[[override-release-on-activation]]
+=== override-release-on-activation
+
+This configuration item changes activation behaviour from `defoverrides`.
+
+Take this example override:
+
+[source]
+----
+(defoverrides (lsft a) (lsft 9))
+----
+
+The default behaviour is that if `lsft` is released **before** releasing `a`,
+kanata's behaviour would be to send `a`.
+
+A future improvement could be to make the `9` continue to be the key held,
+but that is not implemented today.
+
+The workaround in case the above behaviour negatively impacts your workflow
+is to enable this configuration.
+This configuration will press and then immediately release the `9` output
+as soon as the override activates, meaning you are unlikely as a human to ever
+release `lsft` first.
+
+The effect of this configuration is that the `9` key cannot remain held
+when activated by the override which is important to consider for your use cases.
+
+.Example:
+[source]
+----
+(defcfg
+  override-release-on-activation yes
+)
+----
+
+[[allow-hardware-repeat]]
+=== allow-hardware-repeat
+
+By default, any repeat-key events generated by the physical keyboard (or operating system)
+will be passed through to the application.  On Linux, under Wayland, this is wasted effort
+since the DE handles key-repeat on its own.  Such events can also be distracting when
+debugging your configuration with evtest, etc.
+
+Setting this option to "false" will cause such events to be dropped, and not passed through.
+This is primarily meant for Linux, but may find some use on Mac.  It is not implemented on
+Windows, and will be silently ignored.
+
+.Example:
+[source]
+----
+(defcfg
+   allow-hardware-repeat false
+)
+----
+
+[[alias-to-trigger-on-load]]
+=== alias-to-trigger-on-load
+
+Select an alias to execute when first starting, and after each
+live-reload of the config. You can use this to run external
+commands, or to stack layers (with layer-while-held).
+
+The name of an alias, without a leading "@", is expected as a
+parameter.  The example below will beep at startup (assuming
+your system has a beep command), and will already be blocking
+the swapped "i" and "o" keys.
+
+.Example:
+[source]
+----
+(defcfg
+  alias-to-trigger-on-load S
+  danger-enable-cmd yes
+)
+
+(deffakekeys B (layer-while-held block))
+
+(defalias
+  P (on-press toggle-vkey B)
+  S (macro @P (cmd beep))
+)
+
+(defsrc i o p )
+(deflayer base o i @P )
+(deflayer block • • _ )
+----
+
+[[mouse-movement-key]]
+=== Linux, macOS, or Windows-interception only: mouse-movement-key
+
+Accepts a single key name.
+When configured, whenever a mouse cursor movement is received,
+the configured key name will be "tapped" by Kanata,
+activating the key's action.
+
+This enables reporting of every relative mouse movement, which
+corresponds to standard mice, trackballs, trackpads and
+trackpoints. Absolute movements, which can be generated by
+touchscreens, drawing tablets and some mouse replacement or
+accessibility software, are ignored. Scrolling events and mouse
+buttons are also ignored.
+
+The intended use of these events is to provide a way to automatically
+enable a mouse keys layer while mousing, which can be disabled by a
+timeout or typing on other keys, rather than explicit toggling. see
+cfg_examples/automousekeys-*.kbd for more.
+
+The `mvmt` key name is specially intended for this purpose.  It has no
+output key mapping and cannot be supplied as an action; however, any
+key may be used.
+
+Supports live reload on Linux and macOS. With Windows-interception, this
+option must be present on startup to enable mouse movement event
+collection, so restart is required to enable it. Changing the key name
+is always supported, however.
+
+On macOS, this feature uses the same CGEventTap as the existing mouse
+button input support, and so requires the same Accessibility or Input
+Monitoring permission in System Settings > Privacy & Security.
+
+.Example:
+[source]
+----
+(defcfg
+  process-unmapped-keys yes
+  mouse-movement-key mvmt
+)
+
+(defsrc
+  k     l     ;
+  mvmt
+)
+
+(defvirtualkeys
+  mouse (layer-while-held mouse-layer)
+)
+
+(defalias
+  mhld (hold-for-duration 750 mouse)
+)
+
+(deflayer qwerty
+  k     l     ;
+  @mhld
+)
+
+(deflayer mouse-layer
+  mlft  mmid  mrgt
+  @mhld
+)
+----
+
+[[linux-only-linux-dev]]
+=== Linux only: linux-dev
+
+By default, kanata will try to detect which input devices are keyboards and try
+to intercept them all. However, you may specify exact keyboard devices from the
+`/dev/input` directories using the `linux-dev` configuration.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
+)
+----
+
+If you want to specify multiple keyboards, you can separate the paths with a
+colon `+:+`.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-dev /dev/input/dev1:/dev/input/dev2
+)
+----
+
+Due to using the colon to separate devices, if you have a device with colons in
+its file name, you must escape those colons with backslashes:
+
+[source]
+----
+(defcfg
+  linux-dev /dev/input/path-to\:device
+)
+----
+
+Alternatively, you can use list syntax, where both backslashes and colons
+are parsed literally. List items are separated by spaces or newlines.
+Using quotation marks for each item is optional, and only required if an
+item contains spaces.
+
+[source]
+----
+(defcfg
+  linux-dev (
+    /dev/input/path:to:device
+    "/dev/input/path to device"
+  )
+)
+----
+
+For devices that do not have an easily identifiable device path like Bluetooth
+keyboards using the `linux-dev-names-include` option below is recommended.
+
+[[linux-only-linux-dev-names-include]]
+=== Linux only: linux-dev-names-include
+
+In the case that `linux-dev` is omitted,
+this option defines a list of device names that should be included.
+Device names that do not exist in the list will be ignored.
+
+Device paths are not supported by this option; instead use the device names
+as output by Kanata during startup.  Launch Kanata with a
+<<minimal-configuration,minimal configuration>> (any use of a `linux-dev*`
+option may hide devices) and look for lines beginning with "registering":
+
+----
+registering /dev/input/eventX: "Device name 1"
+registering /dev/input/eventY: "Device name 2"
+----
+
+The entire name within quotes must be used, partial matches and regex's are not supported.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-dev-names-include (
+    "Device name 1"
+    "Device name 2"
+  )
+)
+----
+
+[[linux-only-linux-dev-names-exclude]]
+=== Linux only: linux-dev-names-exclude
+
+In the case that `linux-dev` is omitted,
+this option defines a list of device names that should be excluded.
+This option is parsed identically to `linux-dev-names-include`.
+
+The `linux-dev-names-include` and `linux-dev-names-exclude` options
+are not mutually exclusive
+but in practice it probably only makes sense to use one and not both.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-dev-names-exclude (
+    "Device Name 1"
+    "Device Name 2"
+  )
+)
+----
+
+[[linux-only-linux-continue-if-no-devs-found]]
+=== Linux only: linux-continue-if-no-devs-found
+
+By default, kanata will crash if no input devices are found. You can change
+this behaviour by setting `linux-continue-if-no-devs-found`.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-continue-if-no-devs-found yes
+)
+----
+
+[[linux-only-linux-device-detect-mode]]
+=== Linux only: linux-device-detect-mode
+
+Kanata on Linux automatically detects and grabs input devices
+when none of the explicit device configurations are in use.
+In case kanata is undesirably grabbing mouse-like devices,
+you can use a configuration item to change detection behaviour.
+
+The configuration is `linux-device-detect-mode` and it has the options:
+
+[cols="1,4"]
+|===
+| `keyboard-only`
+| Grab devices that seem to be a keyboard only.
+
+| `keyboard-mice`
+| Grab devices that seem to be a keyboard only
+and devices that declare **both** keyboard and mouse functionality.
+
+| `any`
+| Grab all keyboard-like and mouse-like devices.
+|===
+
+The default behaviour is:
+
+[cols="1,4"]
+|===
+| `keyboard-mice`
+| When no mouse events are in `defsrc`.
+
+| `any`
+| When any mouse buttons or mouse scroll events are in `defsrc`.
+|===
+
+[[linux-only-linux-unicode-u-code]]
+=== Linux only: linux-unicode-u-code
+
+Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value,
+then pressing Enter. However, if you do remapping in userspace, e.g. via
+xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u"
+after the userspace remapping. This will be likely if you use non-US,
+non-European keyboards on top of kanata. For unicode to work, kanata needs to
+use the keycode that outputs the keysym "u", which might not be the keycode
+"U".
+
+You can use `evtest` or `kanata --debug`, set your userspace key remapping,
+then press the key that outputs the keysym "u" to see which underlying keycode
+is sent. Then you can use this configuration to change kanata's behaviour.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-unicode-u-code v
+)
+----
+
+[[linux-only-linux-unicode-termination]]
+=== Linux only: linux-unicode-termination
+
+Unicode on Linux terminates with the Enter key by default. This may not work in
+some applications. The termination is configurable with the following options:
+
+- `enter`
+- `space`
+- `enter-space`
+- `space-enter`
+
+.Example:
+[source]
+----
+(defcfg
+  linux-unicode-termination space
+)
+----
+
+=== Linux only: linux-x11-repeat-delay-rate[[linux-only-x11-repeat-rate]]
+
+On Linux, you can tell kanata to run `xset r rate <delay> <rate>`
+on startup and on live reload
+via the configuration item `linux-only-x11-repeat-rate`.
+This takes two numbers separated by a comma.
+The first number is the delay in ms
+and the second number is the repeat rate in repeats/second.
+
+This configuration item does not affect Wayland or no-desktop environments.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-x11-repeat-delay-rate 400,50
+)
+----
+
+[[linux-only-linux-use-trackpoint-property]]
+=== Linux only: linux-use-trackpoint-property
+
+On linux, you can ask kanata to label itself as a trackpoint. This has several
+effects on libinput including enabling middle mouse button scrolling and using a
+different acceleration curve. Otherwise, a trackpoint intercepted by kanata may
+not behave as expected.
+
+If using this feature, it is recommended to filter out any non-trackpoint
+pointing devices using <<linux-only-linux-dev-names-include>>,
+<<linux-only-linux-dev-names-exclude>> or <<linux-only-linux-dev>> to avoid
+changing their behavior as well.
+
+.Example:
+[source]
+----
+(defcfg
+  linux-use-trackpoint-property yes
+)
+----
+
+[[linux-only-linux-output-device-name]]
+=== Linux only: linux-output-device-name
+
+This option defines the name of the evdev output device.
+The default value is kanata.
+
+.Example:
+[source]
+----
+(defcfg
+   linux-output-device-name "kanata output"
+)
+----
+
+[[linux-only-linux-output-device-bus-type]]
+=== Linux only: linux-output-device-bus-type
+
+Kanata on Linux needs to declare a "bus type" for its evdev output device.
+The options are `USB`, `I8042`, and `virtual`, with the default as `I8042`.
+Using USB can https://github.com/jtroo/kanata/pull/661[break disable-touchpad-while-typing on Wayland].
+But using I8042 appears to break https://github.com/jtroo/kanata/issues/1131[some other scenarios].
+Thus the output bus type is configurable.
+
+.Example:
+[source]
+----
+(defcfg
+   linux-output-device-bus-type USB
+)
+----
+
+[[macos-only-macos-dev-names-include]]
+=== macOS only: macos-dev-names-include
+
+This option defines a list of device names that should be included.
+By default, kanata will try to detect which input devices are keyboards and try
+to intercept them all. However, you may specify exact keyboard devices to intercept
+using the `macos-dev-names-include` configuration.
+Device names that do not exist in the list will be ignored.
+This option is parsed identically to `linux-dev`.
+
+Use `kanata -l` or `kanata --list` to list the available keyboards.
+
+.Example:
+[source]
+----
+(defcfg
+  macos-dev-names-include (
+    "Device name 1"
+    "Device name 2"
+  )
+)
+----
+
+[[macos-only-macos-dev-names-exclude]]
+=== macOS only: macos-dev-names-exclude
+
+This option defines a list of device names that should be excluded.
+By default, kanata will try to detect which input devices are keyboards and try
+to intercept them all. However, you may specify certain keyboard devices to be ignored
+using the `macos-dev-names-exclude` configuration.
+Device names that do not exist in the list will be included.
+This option is parsed identically to `linux-dev`.
+
+Use `kanata -l` or `kanata --list` to list the available keyboards.
+
+.Example:
+[source]
+----
+(defcfg
+  macos-dev-names-exclude (
+    "Device name 1"
+    "Device name 2"
+  )
+)
+----
+
+[[macos-only-macos-continue-if-no-devs-found]]
+=== macOS only: macos-continue-if-no-devs-found
+
+By default, kanata will exit with an error if no input devices matching
+the configured include list are found at startup. Setting
+`macos-continue-if-no-devs-found` changes this: kanata keeps running and
+waits for matching devices to connect, then grabs them automatically.
+
+This is useful for Bluetooth or USB keyboards that may not be connected
+at boot time. When the device later appears (e.g. Bluetooth pairs, USB
+plugged in), kanata captures it and begins remapping.
+
+Works with `macos-dev-names-include` and `definputdevices`.
+This has no effect with macOS laptops when no device filter is configured
+because the default enumeration always finds the built-in keyboard.
+
+.Example:
+[source]
+----
+(defcfg
+  macos-dev-names-include ("My BT Keyboard")
+  macos-continue-if-no-devs-found yes
+)
+----
+
+[[windows-only-windows-altgr]]
+=== Windows only: windows-altgr
+
+There is an option for Windows to mitigate the strange behaviour of AltGr
+(key names: `ralt | altgr`) if you're using `process-unmapped-keys yes`
+or have the AltGr key or the Left Control key
+in your `defsrc` or in any `deflayermap` `$input` position.
+This is applicable for many non-US layouts
+that use AltGr for adding modifier accents to characters.
+You can use one of the listed values to change what kanata does with the key:
+
+* `cancel-lctl-press`
+** This will remove the `lctl` press that is generated alonside `ralt`
+* `add-lctl-release`
+** This adds an `lctl` release when `ralt` is released
+
+Without these workarounds,
+within <<process-unmapped-keys,`defcfg`>> you should use
+`process-unmapped-keys (all-except lctl ralt))` or `process-unmapped-keys no`
+**and** also omit both `ralt` and `lctl` from `defsrc`
+and any <<deflayermap,`deflayermap`>> `$input` position.
+
+.Example:
+[source]
+----
+(defcfg
+  windows-altgr add-lctl-release
+)
+----
+
+For more context, see: https://github.com/jtroo/kanata/issues/55.
+
+NOTE: Even with these workarounds, putting `+lctl+` and `+ralt+` in your defsrc may not
+work properly with other applications that also use keyboard interception.
+Known application with issues: GWSL/VcXsrv.
+In this case it is recommended to ensure the keys are omitted from processing.
+
+NOTE: Even if a workaround is applied in Kanata,
+if you use other LLHOOK-using programs such as
+PowerToys Keyboard Manager or AutoHotKey (AHK),
+you can still experience issues.
+PowerToys has no workaround while with AHK
+you may be able to script your own workaround.
+
+=== Windows only: windows-interception-mouse-hwid[[windows-only-windows-interception-mouse-hwid]]
+
+This defcfg item allows you to intercept mouse buttons for a specific mouse device.
+This only works with the Interception driver
+(the -wintercept variants of the release binaries).
+
+The original use case for this is for laptops such as a Thinkpad,
+which have mouse buttons that may be desirable to activate kanata actions with.
+
+To know what numbers to put into the string, you can run the variant with this
+defcfg item defined with any numbers. Then when a button is first pressed on
+the mouse device, kanata will print its hwid in the log; you can then
+copy-paste that into this configuration entry. If this defcfg item is not
+defined, the log will not print.
+
+Hwids in Kanata are byte array representations of a concatenation of the
+ASCII hardware ids, which can be seen in Device Manager on Windows. As such,
+they are an arbitrary length and can be very long.
+
+https://github.com/jtroo/kanata/issues/108[Relevant issue].
+
+.Example:
+[source]
+----
+(defcfg
+  windows-interception-mouse-hwid "70, 0, 60, 0"
+)
+----
+
+=== Windows only: windows-interception-mouse-hwids[[windows-only-windows-interception-mouse-hwids]]
+
+This item has a similar purpose as the singular version documented above,
+but is instead a list of strings that allows multiple mice to be intercepted.
+
+If both the singular and list items are used,
+the singular version will behave as if added to the list.
+
+.Example:
+[source]
+----
+(defcfg
+  windows-interception-mouse-hwids (
+    "70, 0, 60, 0"
+    "71, 0, 62, 0"
+  )
+)
+----
+
+=== Windows only: windows-interception-keyboard-hwids[[windows-only-windows-interception-keyboard-hwids]]
+
+This defcfg item allows you to intercept only specific keyboards.
+Its value must be a list of strings
+with each string representing one hardware ID.
+
+To know what numbers to put into the string,
+you can run the variant with this defcfg item empty.
+Then when a button is first pressed on the keyboard,
+kanata will print its hwid in the log.
+You can then copy-paste that into this configuration entry.
+If this defcfg item is not defined, the log will not print.
+
+Hwids in Kanata are byte array representations of a concatenation of the
+ASCII hardware ids, which can be seen in Device Manager on Windows. As such,
+they are an arbitrary length and can be very long.
+
+.Example:
+[source]
+----
+(defcfg
+  windows-interception-keyboard-hwids (
+    "70, 0, 60, 0"
+    "71, 72, 73, 74"
+  )
+)
+----
+
+=== Windows only: windows-interception-keyboard-hwids-exclude[[windows-only-windows-interception-keyboard-hwids-exclude]]
+
+This defcfg item allows you to exclude certain keyboards from being intercepted.
+You cannot define this alongside the inclusive keyboard configuration.
+
+It is parsed identically to the inclusive configuration.
+
+.Example:
+[source]
+----
+(defcfg
+  windows-interception-keyboard-hwids-exclude (
+    "70, 0, 60, 0"
+    "71, 72, 73, 74"
+  )
+)
+----
+
+=== Windows only: windows-interception-mouse-hwids-exclude[[windows-only-windows-interception-mouse-hwids-exclude]]
+
+This defcfg item allows you to exclude certain mice from being intercepted.
+You cannot define this alongside the inclusive mouse configuration.
+
+It is parsed identically to the inclusive configuration.
+
+.Example:
+[source]
+----
+(defcfg
+  windows-interception-mouse-hwids-exclude (
+    "70, 0, 60, 0"
+    "71, 0, 62, 0"
+  )
+)
+----
+
+[[windows-only-tray-icon]]
+=== Windows only: tray-icon
+
+Show a custom tray icon file for a <<windows-only-win-tray>> gui-enabled build of kanata on Windows.
+Accepts either the full path (including the file name with an extension) to the icon file
+or just the file name, which is then searched in the following locations:
+
+* Default parent folders:
+** config file's, executable's
+** env vars: `XDG_CONFIG_HOME`, `APPDATA` (`C:\Users\<Name>\AppData\Roaming`), `USERPROFILE` `/.config` (`C:\Users\<Name>\.config`)
+* Default config subfolders: `kanata` `kanata-tray`
+* Default image subfolders (optional): `icon` `img` `icons`
+* Supported image file formats: `ico` `jpg` `jpeg` `png` `bmp` `dds` `tiff`
+
+If not specified, tries to load any icon file from the same locations with the name matching
+config name with extension replaced by one of the supported ones.
+See https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config] for more details.
+
+.Example:
+[source]
+----
+;; in a config file C:\Users\<U>\AppData\Roaming\kanata\kanata.kbd
+(defcfg
+  tray-icon base.png ;; will load C:\Users\<U>\AppData\Roaming\kanata\base.png
+)
+----
+
+[[windows-only-icon-match-layer-name]]
+=== Windows only: icon-match-layer-name
+
+When enabled, attempt to switch to a custom tray icon that matches the name of the active layer
+if the layer doesn't specify an explicit icon. If no icon file is found, the default icon will be used (see <<windows-only-tray-icon>>).
+File search rules are the same as in <<windows-only-tray-icon>>. Defaults to true.
+See https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config] for more details.
+
+[[windows-only-tooltip-layer-changes]]
+=== Windows only: tooltip-layer-changes
+
+Show a custom layer icon near the mouse pointer position. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-tooltip-show-blank]]
+=== Windows only: tooltip-show-blank
+
+Show a blank square when instead of an icon if a layer isn't configured to have one. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-tooltip-no-base]]
+=== Windows only: tooltip-no-base
+
+Don't show a tooltip layer icon for the base layer (1st deflayer). Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-tooltip-duration]]
+=== Windows only: tooltip-duration
+
+Set duration (in ms) for showing a custom layer icon near the mouse pointer position. 0 to never hide. Defaults to 500. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-tooltip-size]]
+=== Windows only: tooltip-size
+
+Set the size (comma-separated Width,Height without spaces) for a custom layer icon near the mouse pointer position. Defaults to 24,24. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-notify-cfg-reload]]
+=== Windows only: notify-cfg-reload
+
+Show system notification message on config reload. Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-notify-cfg-reload-silent]]
+=== Windows only: notify-cfg-reload-silent
+
+Disable sound for the system notification message on config reload. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[windows-only-notify-error]]
+=== Windows only: notify-error
+
+Show system notification message on kanata errors. Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.
+
+[[using-multiple-defcfg-options]]
+=== Using multiple defcfg options
+
+The `defcfg` entry is treated as a list with pairs of strings. For example:
+
+[source]
+----
+(defcfg a 1 b 2)
+----
+
+This will be treated as configuration `a` having value `1` and configuration
+`b` having value `2`.
+
+An example defcfg containing many of the options is shown below. It should be
+noted options that are Linux-only, Windows-only, or macOS-only will be ignored when used on
+a non-applicable operating system.
+
+[source]
+----
+;; Don't actually use this exact configuration,
+;; it's almost certainly not what you want.
+(defcfg
+  process-unmapped-keys yes
+  danger-enable-cmd yes
+  sequence-timeout 2000
+  sequence-input-mode visible-backspaced
+  sequence-backtrack-modcancel no
+  log-layer-changes no
+  delegate-to-first-layer yes
+  movemouse-inherit-accel-state yes
+  movemouse-smooth-diagonals yes
+  dynamic-macro-max-presses 1000
+  linux-dev (/dev/input/dev1 /dev/input/dev2)
+  linux-dev-names-include ("Name 1" "Name 2")
+  linux-dev-names-exclude ("Name 3" "Name 4")
+  linux-continue-if-no-devs-found yes
+  linux-unicode-u-code v
+  linux-unicode-termination space
+  linux-x11-repeat-delay-rate 400,50
+  windows-altgr add-lctl-release
+  windows-interception-mouse-hwid "70, 0, 60, 0"
+)
+----
+
+== Command line arguments[[cli-args]]
+
+When executing Kanata, you can pass a variety of arguments to the program
+to change Kanata's behaviour.
+This section describes the purpose and usage of these arguments.
+
+[[args-help]]
+=== Show help text: `-h`, `--help`
+
+Only show help text that describes these arguments,
+then exit the program.
+
+[[args-config-file]]
+=== Configuration file(s): `-c`, `--cfg`
+
+Configuration file(s) to use with Kanata.
+When not specified, default file locations are checked.
+The default files checked depend on your operating system
+and are described by `--help`.
+
+This argument can be used more than once;
+see <<live-reload>> to understand the behaviour of this.
+The startup configuration will be the first file listed.
+
+[[args-tcp]]
+=== TCP server address: `-p`, `--port`
+
+Enable the TCP server capability and listen on either:
+- a specified port, on all IP addresses
+- a specific `IP:PORT`
+
+This enables use cases such as
+https://github.com/jtroo/kanata?tab=readme-ov-file#community-projects-related-to-kanata[application aware switching].
+
+The protocol is plaintext newline-terminated JSON.
+The source of truth is the
+https://github.com/jtroo/kanata/blob/main/tcp_protocol/src/lib.rs[TCP protocol code].
+
+You may also be interested in the
+https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example client].
+
+==== TCP Protocol Overview
+
+The TCP server uses a simple request/response model with JSON messages.
+Each message is a single line of JSON terminated by a newline (`\n`).
+
+- **Client → Server**: Commands to control Kanata (reload config, switch layers, etc.)
+- **Server → Client**: Responses to commands and event notifications (layer changes, config reloads, etc.)
+
+==== Client Commands
+
+These JSON messages can be sent from a TCP client to control Kanata:
+
+===== Layer Control
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `{"ChangeLayer":{"new":"layer-name"}}`
+| Switch to the specified layer. Equivalent to the `layer-switch` keyboard action.
+
+| `{"RequestLayerNames":{}}`
+| Request a list of all defined layer names. Server responds with `LayerNames`.
+
+| `{"RequestCurrentLayerName":{}}`
+| Request the name of the currently active layer. Server responds with `CurrentLayerName`.
+
+| `{"RequestCurrentLayerInfo":{}}`
+| Request the current layer's name and full configuration text. Server responds with `CurrentLayerInfo`.
+|===
+
+.Example - Query and switch layers:
+[source,bash]
+----
+# Get all layer names
+echo '{"RequestLayerNames":{}}' | nc localhost 7070
+
+# Get current layer
+echo '{"RequestCurrentLayerName":{}}' | nc localhost 7070
+
+# Switch to nav layer
+echo '{"ChangeLayer":{"new":"nav"}}' | nc localhost 7070
+----
+
+===== Virtual Key Actions
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `{"RequestFakeKeyNames":{}}`
+| Request a list of all defined virtual key names. Server responds with `FakeKeyNames`.
+
+| `{"ActOnFakeKey":{"name":"key-name","action":"Tap"}}`
+| Trigger a virtual key defined in `defvirtualkeys`. Actions: `Press`, `Release`, `Tap`, `Toggle`.
+|===
+
+Virtual keys must be defined in your configuration using `defvirtualkeys`.
+See the <<virtual-keys>> section for details.
+
+.Example - Trigger a text expansion macro:
+[source]
+----
+;; In your config:
+(defvirtualkeys
+  email-sig (macro S-b e s t spc r e g a r d s)
+)
+
+;; From TCP client:
+echo '{"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}' | nc localhost 7070
+----
+
+===== Mouse Control
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `{"SetMouse":{"x":100,"y":200}}`
+| Set the mouse cursor position to absolute screen coordinates.
+|===
+
+This is the TCP equivalent of the <<set-mouse>> keyboard action.
+
+===== Configuration Reload
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `{"Reload":{}}`
+| Reload the current configuration file. Equivalent to `lrld` keyboard action.
+
+| `{"ReloadNext":{}}`
+| Load the next configuration file in the list. Equivalent to `lrnx` keyboard action.
+
+| `{"ReloadPrev":{}}`
+| Load the previous configuration file in the list. Equivalent to `lrpv` keyboard action.
+
+| `{"ReloadNum":{"index":0}}`
+| Load configuration file at the specified index (0-based).
+
+| `{"ReloadFile":{"path":"/path/to/config.kbd"}}`
+| Load a specific configuration file by path.
+|===
+
+All reload commands support optional `wait` and `timeout_ms` fields for synchronous confirmation:
+
+[source,json]
+----
+{"Reload":{"wait":true,"timeout_ms":5000}}
+----
+
+When `wait` is `true`, the server blocks until the reload completes or times out, then sends a `ReloadResult` message. The `timeout_ms` field specifies the maximum wait time in milliseconds (default: 5000).
+
+===== Server Information
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `{"Hello":{}}`
+| Request server version and capabilities. Server responds with `HelloOk`.
+|===
+
+==== Server Messages
+
+These JSON messages are sent from Kanata to connected TCP clients:
+
+===== Event Notifications
+
+These are sent automatically when events occur:
+
+[cols="1,2"]
+|===
+| Message | Description
+
+| `{"LayerChange":{"new":"layer-name"}}`
+| Sent when the active layer changes.
+
+| `{"ConfigFileReload":{"new":"/path/to/config.kbd"}}`
+| Sent when a configuration file is reloaded.
+
+| `{"MessagePush":{"message":"your-message"}}`
+| Sent when a `push-msg` action is triggered from the keyboard configuration.
+
+| `{"Error":{"msg":"error description"}}`
+| Sent when an error occurs processing a command.
+
+| `{"HoldActivated":{"key":"caps"}}`
+| Sent when a tap-hold key transitions to hold state. The `key` field is the physical key name.
+
+| `{"TapActivated":{"key":"a"}}`
+| Sent when a tap-hold key triggers its tap action. The `key` field is the physical key name.
+|===
+
+===== Query Responses
+
+These are sent in response to client queries:
+
+[cols="1,2"]
+|===
+| Message | Description
+
+| `{"LayerNames":{"names":["base","nav","num"]}}`
+| Response to `RequestLayerNames`. Contains all defined layer names.
+
+| `{"FakeKeyNames":{"names":["email-sig","nav-mode"]}}`
+| Response to `RequestFakeKeyNames`. Contains all defined virtual key names.
+
+| `{"CurrentLayerName":{"name":"base"}}`
+| Response to `RequestCurrentLayerName`. Contains the active layer name.
+
+| `{"CurrentLayerInfo":{"name":"base","cfg_text":"..."}}`
+| Response to `RequestCurrentLayerInfo`. Contains the layer name and its full configuration text.
+
+| `{"HelloOk":{"version":"1.11.0","protocol":1,"capabilities":[...]}}`
+| Response to `Hello`. Contains server version, protocol version, and supported capabilities. Includes `hold-activated` and `tap-activated`.
+
+| `{"ReloadResult":{"ok":true}}`
+| Response to reload commands when `wait` was `true`. Indicates whether the config reload succeeded. If timed out, includes `timeout_ms`.
+|===
+
+For a complete implementation example, see the
+https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example TCP client].
+
+[[args-quiet]]
+=== Disable logs other than errors: `-q`, `--quiet`
+
+Silence info and warning logs so that only errors are logged.
+This might be desirable when running in the background as a system service.
+
+[[args-debug]]
+=== Enable debug logs: `-d`, `--debug`
+
+Add extra debug logging.
+This is helpful when diagnosing an issue
+or discovering key names.
+
+[[args-trace]]
+=== Enable trace logs: `-t`, `--trace`
+
+Add extra trace logging.
+Also includes debug logging.
+This is sometimes helpful when diagnosing an issue,
+but is very verbose.
 
-[[cmd]]
-=== cmd
-<<table-of-contents,Back to ToC>>
+[[args-nodelay]]
+=== Remove startup delay: `-n`, `--nodelay`
 
-The `+cmd+` action executes a program with arguments. It accepts one or more
-strings. The first string is the program that will be run and the following
-strings are arguments to that program. The arguments are provided to the
-program in the order written in the config file.
+By default, Kanata adds a delay before reading keyboard inputs.
+This helps protect against stale states
+when started from a terminal.
 
-NOTE: The command is executed directly and not via a shell, so you cannot make
-use of environment variables, e.g. `+~+` or `+$HOME+` in Linux will not be
-substituted with your home directory.
+Without this delay, Kanata may interpret any keys you're still holding down when it starts
+as being stuck.
 
-.Example:
-[source]
-----
-(defalias
-  cm1 (cmd rm -fr /tmp/testing)
+However, this may be undesirable
+when running as a background service.
 
-  ;; You can use bash -c and then a quoted string to execute arbitrary text in
-  ;; bash. All text within double-quotes is treated as a single string.
-  cm2 (cmd bash -c "echo hello world")
-)
-----
+[[args-check]]
+=== Only check configuration: `--check`
 
-There is a variant of `cmd`: `cmd-output-keys`. This variant reads the output
-of the executed program and reads it as an S-expression, similarly to the
-<<macro, macro action>>. However — unlike macro — only keys, chords, and
-chorded lists are supported. Delays and other actions are not supported.
+Check the configuration file validity and then exit.
 
-[source]
-----
-(defalias
-  ;; bash: type date-time as YYYY-MM-DD HH:MM
-  pdb (cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'")
+[[args-log-layer-changes]]
+=== Force log changes: `--log-layer-changes`
 
-  ;; powershell: type date-time as YYYY-MM-DD HH:MM
-  pdp (cmd-output-keys powershell.exe "echo '(' (((Get-Date -Format 'yyyy-MM-dd HH:mm').toCharArray() -join ' ').insert(20, ' spc ') -replace ':','S-;') ')'")
-)
-----
+Your final desired `defcfg` could be to have logging of layer changes as false.
+However, for testing purposes you may want to temporarily log the layers.
+This configuration forces logging to happen for this use case.
 
-[[arbitrary-code]]
-=== arbitrary-code
-<<table-of-contents,Back to ToC>>
+[[args-no-wait]]
+=== Skip exit prompt: `--no-wait`
 
-The `arbitrary-code` action allows sending an arbitrary number to kanata's
-output mechanism. The press is sent when pressed, and the release sent when
-released. This action can be useful for testing keys that are not yet named or
-mapped in kanata. Please contribute findings with names and mappings, either in
-a GitHub issue or as a pull request!
+By default, kanata displays "Press enter to exit" and waits for user input
+before exiting. This flag skips that prompt and exits immediately.
 
-WARNING: This is not cross platform!
+This is useful when running kanata as a background service (e.g., systemd)
+where you want automatic restart on failure. Without this flag,
+the service would hang waiting for stdin input that never comes.
 
-WARNING: When using the Interception driver, this action is still sent over
-SendInput.
+[[args-linux-dev-symlink]]
+=== Linux only - Device symlink path: `-s`, `--symlink-path`
 
-[source]
-----
-(defalias
-  ab1 (arbitrary-code 700)
-)
-----
+If you want another program to consume the Kanata device output,
+you can use this flag to have a consistent device filesystem path.
 
-[[global-overrides]]
-== Global overrides
-<<table-of-contents,Back to ToC>>
+[[args-wait-device]]
+=== Linux only - Wait before device grab attempt: `-w`, `--wait-device-ms`
 
-The `defoverrides` optional configuration item allows you to create global
-key overrides, irrespective of what actions are used to generate those keys.
-It accepts pairs of lists:
+Some devices take a while to become ready and can fail to be grabbed.
+This configuration adds a delay before trying to grab devices
+in case this is an issue impacting you.
 
-1. the input key list that gets replaced
-2. the output key list to replace the input keys with
+[[args-macos-list-devices]]
+=== macOS only - Only list keyboards: `-l`, `--list`
 
-Both input and output lists accept 0 or more modifier keys (e.g. lctl, rsft)
-and exactly 1 non-modifier key (e.g. 1, bspc).
+List keyboard names that can be used
+within defcfg and then exit.
 
-Only zero or one `defoverrides` is allowed in a configuration file.
+[[args-macos-release-grab-on-lock]]
+=== macOS only - Release grab on lock / user switch: `--release-grab-on-lock`
+
+By default, kanata's keyboard grab on macOS stays active even when
+the screen is locked or another user takes the console via fast user
+switching. This means anyone else at the keyboard (including you on
+the lock-screen prompt) types through your remap.
+
+Pass `--release-grab-on-lock` to make kanata poll its CGSession state
+and release the grab whenever the screen is locked
+(`CGSSessionScreenIsLocked`) or kanata's session loses the console
+(`kCGSSessionOnConsoleKey == false`). The grab is re-acquired once
+kanata's session is back on the console with the screen unlocked.
+
+This is useful on shared Macs where another user's lock-screen
+password or session should not be remapped. Off by default to
+preserve the historical always-grab behavior for single-user setups.
+
+== Advanced features[[advanced-features]]
+[[virtual-keys]]
+=== Virtual keys
+
+You can define up to 767 virtual keys.
+These keys are not directly mapped to any physical key presses or releases.
+Virtual keys can be activated via special actions:
+
+* `(on-press    <action> <virtual key name>)` or `on↓`:
+Activate a virtual key action when pressing the associated input key.
+* `(on-release  <action> <virtual key name>)` or `on↑`:
+Activate a virtual key action when releasing the associated input key.
+* `(on-idle <idle time> <action> <virtual key name>)`:
+Activate a virtual key action when kanata has been idle
+for at least `idle time` milliseconds.
+* `(on-physical-idle <idle time> <action> <virtual key name>)`:
+Activate a virtual key action when the physical keyboard has
+had all keys released
+for at least `idle time` milliseconds.
+* `(hold-for-duration <hold time> <virtual key name>`):
+Press a virtual key for `hold time` milliseconds.
+If `hold-for-duration` retriggered on a virtual key before release,
+the time will be reset with no additional press/release events.
+
+The `<action>` parameter can be one of:
+
+* `tap-virtualkey     | tap-vkey`:
+Press and release the virtual key. If the key is already pressed, this only releases it.
+* `press-virtualkey   | press-vkey`:
+Press the virtual key. It will not be released until another action triggers a release or tap.
+If the key is already pressed, this does nothing.
+* `release-virtualkey | release-vkey`:
+Release the virtual key. If it is not already pressed, this does nothing.
+* `toggle-virtualkey  | toggle-vkey`:
+Press the virtual key if it is not already pressed, otherwise release it.
+
+A virtual key can be defined in a `defvirtualkeys` configuration entry.
+Configuring this entry is similar to `+defalias+`,
+but you cannot make use of aliases inside to shorten an action.
+You can refer to previously defined virtual keys.
+
+Expanding on the `on-idle` action some more,
+the wording that "kanata" has been idle is important.
+Even if the keyboard is idle, kanata may not yet be idle.
+For example, if a long-running macro is playing,
+or kanata is waiting for the timeout of actions such as `caps-word` or `tap-dance`,
+kanata is not yet idle, and the tick count for the `<idle time>` parameter
+will not yet be counting even if you no longer have any keyboard keys pressed.
+The variant `on-physical-idle` may be more desirable if you want the timer
+to only start based on having all keyboard keys be released.
 
 .Example:
 [source]
 ----
-;; Swap numbers and their symbols with respect to shift
-(defoverrides
-  (1) (lsft 1)
-  (2) (lsft 2)
-  ;; repeat for all remaining numbers
+(defvirtualkeys
+  ;; Define some virtual keys that perform modifier actions
+  ctl lctl
+  sft lsft
+  met lmet
+  alt lalt
 
-  (lsft 1) (1)
-  (lsft 2) (2)
-  ;; repeat for all remaining numbers
+  ;; A virtual key that toggles all modifier virtual keys above
+  tal (multi
+        (on-press toggle-virtualkey ctl)
+        (on-press toggle-virtualkey sft)
+        (on-press toggle-virtualkey met)
+        (on-press toggle-virtualkey alt)
+      )
+
+  ;; Virtual key that activates a macro
+  vkmacro (macro h e l l o spc w o r l d)
+)
+
+(defalias
+  psf (on-press press-virtualkey   sft)
+  rsf (on-press release-virtualkey sft)
+
+  tal (on-press tap-vkey tal)
+  mac (on-press tap-vkey vkmacro)
+
+  isf (on-idle 1000 tap-vkey sft)
+  hfd (hold-for-duration 1000 met)
+)
+
+(deflayer use-virtual-keys
+  @psf @rsf @tal @mac a s d f @isf @hfd
 )
 ----
 
-[[advanced-weird-features]]
-== Advanced/weird features
+.Older fake keys documentation
+[%collapsible]
+====
+The older configuration style of fake keys are still supported
+but the new style is preferred due to (hopefully) clearer naming.
 
-[[fake-keys]]
-=== Fake keys
-<<table-of-contents,Back to ToC>>
+Fake keys can be defined inside of `deffakekeys`.
 
-You can define up to 767 fake keys. These keys are not directly mapped to any
-physical key presses and can only be activated via these actions:
+The actions are:
 
-* `+(on-press-fakekey <fake key name> <key action>)+`: Activate a fake key
+* `+(on-press-fakekey <fake key name> <action>)+` or `on↓fakekey`: Activate a fake key
   action when pressing the key mapped to this action.
-* `+(on-release-fakekey <fake key name> <key action>)+`: Activate a fake key
+* `+(on-release-fakekey <fake key name> <action>)+` or `on↑fakekey`: Activate a fake key
   action when releasing the key mapped to this action.
+* `+(on-idle-fakekey <fake key name> <action> <idle time>)+`:
+  Activate a fake key action when kanata has been idle
+  for at least `idle time` milliseconds.
 
-A fake key can be defined in a `+deffakekeys+` configuration entry. Configuring
-this entry is similar to `+defalias+`, but you cannot make use of aliases
-inside of `+deffakekeys+` to shorten an action. You can however refer to
-previously defined fake keys.
-
-The aforementioned `+<key action>+` can be one of three values:
+The aforementioned `+<key action>+` can be one of four values:
 
 * `+press+`: Press the fake key. It will not be released until another action
   triggers a release or tap.
 * `+release+`: Release the fake key. If it's not already pressed, this does nothing.
 * `+tap+`: Press and release the fake key. If it's already pressed, this only releases it.
+* `+toggle+`: Press the fake key if not already pressed, otherwise release it.
 
 .Example:
 [source]
@@ -1704,7 +5805,7 @@ The aforementioned `+<key action>+` can be one of three values:
 
   ;; Press all modifiers
   pal (multi
-        (on-press-fakekey ctl press)
+        (on-press fakekey ctl press)
         (on-press-fakekey sft press)
         (on-press-fakekey met press)
         (on-press-fakekey alt press)
@@ -1725,52 +5826,27 @@ The aforementioned `+<key action>+` can be one of three values:
 
   pal (on-press-fakekey pal tap)
   ral (on-press-fakekey ral tap)
-)
 
-(deflayer use-fake-keys
-  @psf @rsf @pal @ral a s d f
+  isf (on-idle-fakekey sft tap 1000)
 )
-----
 
-If you find that an application isn't registering keypresses correctly with
-`+multi+` because the sequence activates too quickly, you can try using fake
-key actions alongside the delay actions below.
-
-* `+on-press-fakekey-delay+`
-* `+on-release-fakekey-delay+`
-
-Do note that processing a fakekey-delay and even a sequence of delays will
-delay any other inputs from being processed until the fakekey-delays are all
-complete, so use with care.
-
-NOTE: You will likely want to use `+macro+` instead of fake keys with delays now
-that `+macro+` supports more actions.
-
-[source]
-----
-(defalias
-  stm (multi ;; Shift -> middle mouse with a delay
-    (on-press-fakekey lsft press)
-    (on-press-fakekey-delay 200)
-    (on-press-fakekey mmid press)
-    (on-release-fakekey mmid release)
-    (on-release-fakekey-delay 200)
-    (on-release-fakekey lsft release)
-  )
+(deflayer use-virtual-keys
+  @psf @rsf @pal @ral a s d f @isf
 )
 ----
 
+====
+
 For more context, you can read the
-https://github.com/jtroo/kanata/issues/80[issue that sparked the creation of fake keys].
+https://github.com/jtroo/kanata/issues/80[issue that sparked the creation of virtual keys].
 
-Something notable about fake keys is that they don't always interrupt the state
-of an active `+tap-dance-eager+`. If a `macro` action is assigned to a fake
+Something notable about virtual keys is that they don't always interrupt the state
+of an active `+tap-dance-eager+`. If a `macro` action is assigned to a virtual
 key, this won't interrupt a tap dance. However, most other action types,
 notably a "normal" key action like `+rsft+` will still interrupt a tap dance.
 
 [[sequences]]
 === Sequences
-<<table-of-contents,Back to ToC>>
 
 The `+sldr+` action makes kanata go into "sequence" mode. The action name is
 short for "sequence leader". This comes from Vim which has the concept of a configurable
@@ -1781,31 +5857,229 @@ but are saved until one of the following happens:
 * A key is typed that does not match any sequence
 * `+sequence-timeout+` milliseconds elapses since the most recent key press
 
-Sequences are configured similarly to `+deffakekeys+`. The first parameter of a
-pair must be a defined fake key name. The second parameter is a list of keys
-that will activate a fake key tap when typed in the defined order. More
+Sequences are configured similarly to `+defvirtualkeys+`. The first parameter of a
+pair must be a defined virtual key name. The second parameter is a list of keys
+that will activate a virtual key tap when typed in the defined order. More
 precisely, the action triggered is:
 
-`+(on-press-fakekey <fake key name> tap)+`
+`+(on-press tap-vkey <virtual key name>)+`
 
 .Example:
 [source]
 ----
 (defseq git-status (g s t))
-(deffakekeys git-status (macro g i t spc s t a t u s))
+(defvirtualkeys git-status (macro g i t spc s t a t u s))
 (defalias rcl (tap-hold-release 200 200 sldr rctl))
+
+(defseq
+    dotcom (. S-3)
+    dotorg (. S-4)
+
+    ;;     The shifted letters in parentheses means a single press of lsft
+    ;;     must remain held while both h and then s are pressed.
+    ;;     This is not the same as S-h S-s, which means that the lsft key
+    ;;     must be released and repressed between the h and s presses.
+    https (S-(h s))
+)
+(defvirtualkeys
+    dotcom (macro . c o m)
+    dotorg (macro . o r g)
+    https (macro h t t p s S-; / /)
+)
 ----
 
-For more context, you can read the
+There are 10 special keys with names `nop0-nop9` which kanata treats specially.
+Kanata will never send OS events for these keys
+but they can still participate in sequences.
+See an example of using the nop keys below.
+
+Additionally useful to note in this example is the use of a template
+to define a sequence and its virtual key in one template expansion,
+with template parameters:
+
+- virtual key name
+- activating key sequence
+- action triggered by sequence activation
+
+This template may be useful to you within your own configuration.
+
+.Example:
+[source]
+----
+(defsrc f7   f8   f9   f10)
+(deflayer base
+        sldr nop0 nop1 nop2)
+(deftemplate seq (vk-name input-keys output-action)
+    (defvirtualkeys $vk-name $output-action)
+    (defseq $vk-name $input-keys)
+)
+;; template-expand has a shortened form: t!
+(t! seq dotcom (nop0 nop1) (macro . c o m))
+(t! seq dotorg (nop0 nop2) (macro . o r g))
+----
+
+If 10 special nop keys do not seem sufficient,
+you can get creative with your sequences and treat some as a prefix modifier.
+For example, you can get 24 "keys" by treating `nop0-nop5` as normal
+while treating `nop6-nop9` as prefixes that are always followed by a second nop key.
+
+.Example:
+[source]
+----
+(defalias
+  nop0 nop0
+  ;; ...
+  nop5 nop5
+  nop6 (macro nop6 nop0)
+  ;; ...
+  nop11 (macro nop6 nop5)
+  ;; ...
+  nop18 (macro nop9 nop0)
+  ;; ...
+  nop23 (macro nop9 nop5)
+)
+----
+
+==== Overlapping keys in any order
+
+Within the key list of `defseq` configuration items,
+the special `O-` list prefix can be used to denote a set of keys that must
+all be pressed before any are released in order to match the sequence.
+
+For an example, `O-(a b c)` is equivalent to `O-(c b a)`.
+
+.Example:
+[source]
+----
+(defvirtualkey hello (macro h (unshift e l) 5 (unshift l o)))
+(defseq hello (O-(h l o)))
+----
+
+WARNING: The way that sequences implements this functionality behind the scenes
+is by generating a sequence for every permutation of the overlapping keys.
+This can make kanata use up a lot of memory.
+Due to this, the maximum keys allowed in a given `O-(...)` list is 6,
+but you are still permitted to add more to the sequence,
+including more `O-(...)` lists.
+Doing the above can balloon kanata's memory consumption.
+
+.Sample of more advanced usage
+[%collapsible]
+====
+
+The configuration below showcases context-dependent chording
+with auto-space and auto-deleted spaces from typing punctuation.
+
+For example, chording `(d a y)` and then `(t u e)` will output
+`Tuesday`, while chording `(t u e)` by itself does nothing.
+
+.Example configuration:
+[source]
+----
+(defsrc f1)
+(deflayer base lrld)
+(defcfg process-unmapped-keys yes
+	sequence-input-mode visible-backspaced
+	concurrent-tap-hold true)
+(deftemplate seq (vk-name in out)
+	(defvirtualkeys $vk-name $out)
+	(defseq $vk-name $in))
+
+(defvirtualkeys rls-sft (multi (release-key lsft)(release-key rsft)))
+(defvar rls-sft (on-press tap-vkey rls-sft))
+(deftemplate rls-sft () $rls-sft 5)
+
+(defchordsv2
+	(d a y) (macro sldr d (t! rls-sft) a y spc nop0) 200 first-release ()
+	(h l o) (macro h (t! rls-sft) e l l o sldr spc nop0) 200 first-release ()
+)
+(t! seq Monday (d a y spc nop0 O-(m o n)) (macro S-m $rls-sft o n d a y nop9 sldr spc nop0))
+(t! seq Tuesday (d a y spc nop0 O-(t u e)) (macro S-t $rls-sft u e s d a y nop9 sldr spc nop0))
+(t! seq DelSpace_. (spc nop0 .) (macro .))
+(t! seq DelSpace_; (spc nop0 ;) (macro ;))
+----
+
+.Try using the above configuration to type the text:
+[source]
+----
+day;
+Day;
+Tuesday.
+day hello
+hello day
+Hello day.
+hello Tuesday
+Hello Monday;
+----
+
+====
+
+==== Override the global timeout and input mode
+
+An alternative to using `sldr` is the `sequence` action.
+The syntax is `(sequence <timeout>)`.
+This enters sequence mode with a sequence timeout
+different from the globally configured one.
+
+The `sequence` action can also be called with a second parameter.
+The second parameter is an override for `sequence-input-mode`:
+
+----
+(sequence <timeout> <input-mode>)
+----
+
+
+.Example:
+[source]
+----
+;; Enter sequence mode and input . with a timeout of 250
+(defalias dot-sequence (macro (sequence 250) 10 .))
+
+;; Enter sequence mode and input . with a timeout of 250 and using hidden-delay-type
+(defalias dot-sequence (macro (sequence 250 hidden-delay-type) 10 .))
+----
+
+==== sequence-noerase
+
+When you have a keyboard locale that uses dead keys,
+you may be pressing two keys that only actually output one symbol.
+By default, when the `visible-backspaced` input mode does the backtracking backspaces,
+it backspaces according to input count.
+With dead keys, this may result in too many backspaces.
+
+The `sequence-noerase` action is a no-output action
+that tells the sequences action to have one fewer backspace
+when backtracking with visible-backspaced.
+
+.Example:
+[source]
+----
+(deflayermap (base)
+  0 sldr
+  u (t! maybe-noerase u)
+)
+(deftemplate maybe-noerase (char)
+  (multi
+    (switch
+      ((key-history ' 1)) (sequence-noerase 1) fallthrough
+      () $char break
+   ))
+)
+(defvirtualkeys seq-output-1 (macro a b c d e f g))
+(defseq seq-output-1 (' u))
+
+----
+
+==== More about sequences
+
+For more context about sequences, you can read the
 https://github.com/jtroo/kanata/issues/97[design and motivation of sequences].
 You may also be interested in
-https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[
-the document describing chords is sequences]
+https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[the document describing chords in sequences]
 to read about how chords in sequences behave.
 
 [[input-chords]]
 === Input chords
-<<table-of-contents,Back to ToC>>
 
 Not to be confused with <<output-chords-combos,output chords>>, `+chord+`
 actions allow you to perform various actions based on which specific combination
@@ -1869,6 +6143,8 @@ the input chord have been released.
 In other words, if even one key is held for the input chord
 then the output action will be continued to be held,
 but only for the mentioned action categories.
+The behaviour also applies to the actions mentioned above
+when used inside of `multi` but not within any other action.
 
 An exception to the behaviour described above
 for the action categories that would normally apply
@@ -1897,7 +6173,9 @@ Using a macro will guarantee a rapid press+release for the output keys.
 
 [[defaliasenvcond]]
 === defaliasenvcond
-<<table-of-contents,Back to ToC>>
+
+NOTE: this configuration item is older and instead you may want to use
+the newer and more generalized <<environment>> configuration.
 
 There is a variant of `defalias`: `defaliasenvcond`.
 This variant is parsed similarly,
@@ -1948,7 +6226,6 @@ VAR_NAME=var_value
 
 [[custom-tap-hold-behaviour]]
 === Custom tap-hold behaviour
-<<table-of-contents,Back to ToC>>
 
 This is not currently configurable without modifying the source code, but if
 you're willing and/or capable, there is a tap-hold behaviour that is currently
@@ -1961,3 +6238,380 @@ doesn't make full use of the power of this functionality.
 
 For more context, you can read the
 https://github.com/jtroo/kanata/issues/128[motivation for custom tap-hold behaviour].
+
+
+[[fancy-key-symbols]]
+=== Fancy key symbols
+
+Instead of using the same `+a-z+` letters for special keys, e.g., `+lsft+` for `+LeftShift+`
+you can use much shorter, yet more visible, key symbols like `+‹⇧+`.
+
+For more details see
+https://github.com/jtroo/kanata/blob/main/docs/fancy_symbols.md[symbol list] and
+https://github.com/jtroo/kanata/blob/main/cfg_samples/fancy_symbols.kbd[example config], which not only uses these symbols in layer definitions, but also repurposes `+⎇›+` and `+⇧›+` `+⎇›+` keys into "symbol" keys that allow you to insert these fancy symbols by pressing the key, e.g.,
+
+* hold `+⎇›+` and tap `+Delete+` would insert `+␡+`
+
+[[windows-only-work-elevated]]
+=== Windows only: enable in elevated windows
+
+The default `kanata.exe` binary doesn't work in elevated windows (run with administrative privileges),
+e.g., `Control Panel`. However, you can use AutoHotkey's "EnableUIAccess" script to self-sign the binary,
+move it to "Program Files", then launching kanata from there will also work in these elevated windows.
+See https://github.com/jtroo/kanata/blob/main/EnableUIAccess[EnableUIAccess] folder with the script
+and its required libraries (needs https://www.autohotkey.com/download/[AutoHotkey v2] installed)
+
+If compiling yourself, you should add the feature flag `win_manifest`
+to enable the use of the `EnableUIAccess` script:
+
+```
+cargo build --win_manifest
+```
+
+[[windows-only-win-tray]]
+=== Windows only: win-tray
+
+Kanata can be compiled as a Windows GUI tray app with the feature flag `gui`.
+This can simplify launching the app on user login by placing a `.lnk`
+at `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`, show custom icon indicator per config
+
+
+image:https://github.com/jtroo/kanata/blob/main/docs/win-tray/win-tray-screen.png[icon indicator per config,477,129]
+
+as well as dynamic icon indicator per layer (might need to click on the gif below to play)
+
+image:https://github.com/jtroo/kanata/blob/main/docs/win-tray/win-tray-layer-change.gif[icon indicator per layer,33,35,opts=autoplay]
+
+(see <<windows-only-win-tray>>). It also supports (re)loading configs.
+
+Currently the only configuration supported is tray icon per profile, all other configuration should
+be done by passing cli flags in the `Target` field of `.lnk`, e.g., `"C:\Program Files\kanata\kanata.exe" -d -n`
+to launch kanata without a delay in a debug mode
+
+When launched from a command line, the app outputs log to the console, but otherwise the logs are currently
+only available via an app capable of viewing `OutputDebugString` debugs, e.g., https://github.com/smourier/TraceSpy[TraceSpy].
+
+[[test-your-config]]
+=== Test your config
+
+Kanata has a `+kanata_simulated_input+` tool
+to help test your configuration in a predictable manner.
+
+You can try it out on https://jtroo.github.io/[GitHub pages].
+
+Code for the CLI tool can be found under link:https://github.com/jtroo/kanata/blob/main/simulated_input/[simulated_input].
+
+Instead of physically typing to test something
+and wondering whether you didn't get the expected result because your config is wrong or
+because you mistyped something,
+you can write a sequence of key presses in a `+sim.txt+` file,
+run the tool with your config
+and get a "timeline" view of input/output events that can help understand how kanata translates
+your input into various key/mouse presses.
+
+WARNING: The format of this view may change. Emoji output may break vertical alignment.
+
+For more details download the files below and run `kanata_simulated_input -c sim.kbd -s sim.txt` +
+  - https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim.kbd[example config] with simple home row mod bindings +
+  - https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim.txt[example input sequence] +
+  - https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim_out.txt[example output sequence] +
+
+Input sequence file format: whitespace insensitive list of `prefix:key` pairs where prefix is one of: +
+  - `🕐`, `t`, or `tick` to add time between key events in `ms` +
+  - `↓`, `d`, `down`, or `press` +
+  - `↑`, `u`, `up`, or `release` +
+  - `⟳`, `r`, or `repeat` +
+  - `🎭`, `fakekey`, `vk`, or `virtualkey` to activate virtual keys +
+  - `🔀`, `ls`, or `layer-switch` to switch layers +
+
+Virtual key format is `vk:name[:action]`, `fakekey:name[:action]`, or `virtualkey:name[:action]`. +
+When using the emoji prefix, the format is `🎭name[:action]`. Action is one of: +
+  - `press` or `p` (default if omitted) +
+  - `release` +
+  - `tap` or `t` +
+  - `toggle` or `g` +
+Example: `vk:vk_bear:tap` or `🎭vk_bear:tap`. +
+
+Layer switch format is `ls:name` or `layer-switch:name`. +
+When using the emoji prefix, the format is `🔀name`. +
+This switches to the specified layer as the new default layer. +
+Example: `ls:nav` or `🔀nav`. +
+
+And key names are defined in the https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[str_to_oscode function],
+for example, `1` for the numeric key 1 or `kp1`/`🔢₁` for the keypad numeric key 1
+
+Using unicode symbols `🕐`,`↓`,`↑`,`⟳`,`🎭`,`🔀` allows skipping the `:` separator, e.g., `↓k` ≝ `↓:k` ≝ `d:k`
+
+[[zippychord]]
+=== Zippychord
+
+**Reference**
+
+You may define a single `+defzippy+` configuration item.
+This configuration enables chorded text expansion.
+
+.Configuration syntax within the kanata configuration
+[source]
+----
+(defzippy
+  $zippy-filename ;; required
+  on-first-press-chord-deadline $deadline-millis  ;; optional
+  idle-reactivate-time          $idle-time-millis ;; optional
+  smart-space                   $smart-space-cfg  ;; optional
+  smart-space-punctuation (                       ;; optional
+    $punc1 $punc2 ... $puncN)
+  output-character-mappings (    ;; optional
+    $character1 $output-mapping1
+    $character2 $output-mapping2
+    ;; ...
+    $characterN $output-mappingN
+  )
+)
+----
+
+[cols="1,4"]
+|===
+| `$zippy-filename`
+| Relative or absolute file path.
+If relative, its path is relative to
+the directory containing the kanata configuration file.
+This must be the first item following `defzippy`.
+
+| `$deadline-millis`
+| Number of milliseconds.
+After the first press while zippy is enabled,
+if no chord activates within this configured time,
+zippy is temporarily disabled.
+
+| `$idle-time-millis`
+| Number of milliseconds.
+After typing ends and this configured number of milliseconds elapses,
+zippy will be re-enabled from being temporarily disabled.
+
+| `$smart-space-cfg`
+| Determines the smart space behaviour.
+The options are `none`, `add-space-only`, and `full`.
+With `none`, outputs are typed as-is.
+With `add-space-only`, spaces are automatically added after outputs
+which end with neither a space or a backspace ⌫.
+With `full`, the `add-space-only` behaviour applies
+alongside additional behaviour:
+typing punctuation (default characters: `, . ;`)
+after a zippy activation will delete a prior automatically-added space.
+
+| `$punc`
+| A character defined in `output-character-mappings`
+or a known key name, which shall be considered as punctuation.
+The `smart-space-punctuation` configuration
+will overwrite the default punctuation list
+considered by smart-space;
+if you want to include the default characters,
+you must include them in this configuration.
+
+| `$character`
+| A single unicode codepoint for use
+in the output column of the zippy configuration file.
+
+| `$output-mapping`
+| Key or output chord to tell kanata how to type `$character`
+when seen in the zippy file output column.
+Must be a single key or output chord.
+The output chord may contain `AG-` to tell kanata to press with AltGr
+and may contain `S-` to tell kanata to press with Shift.
+
+The list items `no-erase` and `single-output` are also usable in this position.
+
+| `no-erase`
+| Accepts a single key or output chord as a parameter.
+The zippy system will not backspace this character
+in case of auto-erasure by a superset chord or followup chord.
+Use for dead keys or compose keys.
+
+| `single-output`
+| Accepts one or more keys or output chords as a parameter.
+The zippy system send only one backspace
+in case of auto-erasure by a superset chord or followup chord.
+Use for a dead key or compose key sequence with one output symbol.
+|===
+
+Regarding output mappings,
+you can configure the output of the special-lisp-syntax characters
+`+) ( "+` via these lines:
+
+[source]
+----
+    ")"    $right-paren-output
+    "("    $left-paren-output
+    r#"""# $double-quote-output
+----
+
+As an example, for the US layout these should be the correct lines:
+
+[source]
+----
+    ")"     S-0
+    "("     S-9
+    r#"""#  S-'
+----
+
+.Configuration syntax within the zippy configuration file
+[source]
+----
+// This is a comment.
+//          inputs            ↹  outputs
+$chord1 $follow-chord1.1...1.M	$output1
+$chord2 $follow-chord2.1...2.M	$output2
+// ...
+$chordN $follow-chordN.1...N.M	$outputN
+----
+
+The format is two columns separated by a single Tab character.
+The first column is input and the second is output.
+
+[cols="1,4"]
+|===
+|`$chord`
+| A set of characters.
+You can use space by including it as the first character in the chord;
+for an example see `Alphabet` in the sample below.
+With 0 optional follow chords,
+the corresponding output on the same line (`$output`)
+will activate when zippy is enabled
+and all the defined chord keys are pressed simultaneously.
+The order of presses is not important.
+
+| `$follow-chord`
+| 0 or more chords, used the same way as `$chord`.
+Having follow chords means the `$output` on the same line
+will activate upon first activating the earlier chord(s) in the same line,
+releasing all keys, and pressing the keys in `$follow-chordN.M`.
+Follow chords are separated from the previous chord by a space.
+If using a space in the follow chord, use two spaces;
+for an example see `Washington` in the sample below.
+
+| `$output`
+| The characters to type when the chord and optional follow chord(s)
+are all pressed by the user.
+This is separated from the input chord column
+by a single Tab character.
+The characters are typed in sequence
+and must all be singular-name key names
+as one would configure in `defsrc`.
+A capitalized single-character key name
+will be parsed successfully
+and these will be outputted alongside Shift to output the capitalized key.
+Additionally, `output-character-mappings` configuration can be used
+to inform kanata of additional mappings that may use Shift or AltGr.
+|===
+
+**Examples**
+
+.Sample kanata configuration
+[source]
+----
+(defzippy
+  zippy.txt
+  on-first-press-chord-deadline 500
+  idle-reactivate-time          500
+  smart-space-punctuation (? ! . , ; :)
+  output-character-mappings (
+    ;; This should work for US international.
+    ! S-1
+    ? S-/
+    % S-5
+    "(" S-9
+    ")" S-0
+    : S-;
+    < S-,
+    > S-.
+    r#"""# S-'
+    | S-\
+    _ S--
+    ® AG-r
+    ’ (no-erase `)
+    é (single-output ' e)
+  )
+)
+----
+
+.Sample zippy file content
+
+[source]
+----
+dy	day
+dy 1	Monday
+dy 2	Tuesday
+ abc	alphabet
+ w  a	Washington
+gi	git
+gi f p	git fetch -p
+----
+
+**Description**
+
+Zippychord is yet another chording mechanism in Kanata.
+The inspiration behind it is primarily the
+https://github.com/psoukie/zipchord[zipchord project].
+The name is similar; it is named "zippy" instead of "zip" because
+Kanata's implementation is not a port and does not aim for 100%
+behavioural compatibility.
+
+The intended use case is shorthands, or accelerating character output.
+Within zippychord, inputs are keycode chords or sequences,
+and the outputs are also purely keycodes.
+In other words, all other actions are unsupported;
+e.g. layers, switch, one-shot.
+
+Zippychord behaves on outputted keycodes, i.e. the key outputs
+after kanata has finished processing your
+inputs, layers, switch logic and other configurations.
+This is similar to how sequences operate
+and is unlike chords(v1) and chordsv2.
+Furthermore, outputs are all eager like `visible-backspaced` on sequences.
+If a zippychord activation occurs, typed keys are backspaced.
+
+To give an example, if one configures zippychord with a line like:
+
+[source]
+----
+gi	git
+----
+
+then either of the following typing event sequences
+will erase the input characters
+and then proceed to type the output "git"
+like if it was `(macro bspc bspc g i t)`.
+
+[source]
+----
+(press g) (press i)
+(press i) (press g)
+----
+
+Note that there aren't any release events listed.
+To contrast, the following event sequence would not result in an activation:
+
+[source]
+----
+(press g) (release g) (press i)
+----
+
+Zippychord supports fully overlapping chords and sequences.
+For example, this configuration is allowed:
+
+[source]
+----
+gi	git␣
+gi s	git␣status
+gi c	git checkout␣
+gi c b	git checkout -b␣
+gi c a	git commit --amend␣
+gi c n	git commit --amend --no-edit
+gi c a m	git commit --amend -m 'FIX_THIS_COMMIT_MESSAGE'
+----
+
+When you begin with the `(g i)` chord, you can follow up
+with various character sequences to output different git commands.
+This use case is quite similar to git aliases.
+One advantage of zippychord is that it eagerly shows you
+the true underlying command as you type.
diff --git a/docs/dropping-root.md b/docs/dropping-root.md
deleted file mode 100644
index 4517d629c..000000000
--- a/docs/dropping-root.md
+++ /dev/null
@@ -1,27 +0,0 @@
-Create a user for kanata and add it to the input groups
-
-```
-sudo useradd -r -s /bin/false kanata
-sudo groupadd uinput
-sudo usermod -aG input kanata
-sudo usermod -aG uinput kanata
-```
-
-Add a new udev rule
-
-```
-sudo touch /etc/udev/rules.d/99-uinput.rules
-```
-
-Add the following line to it
-
-```
-KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"
-```
-
-If you are using the default `/opt/kanata` directory -
-
-```
-sudo chown -R kanata:$USER /opt/kanata
-sudo chmod -R 0770 /opt/kanata
-```
diff --git a/docs/fancy_symbols.md b/docs/fancy_symbols.md
new file mode 100644
index 000000000..87fe4d49f
--- /dev/null
+++ b/docs/fancy_symbols.md
@@ -0,0 +1,46 @@
+### Supported key symbols
+
+  |Symbol(s)[^1] 	|Key `name`                                	|
+  |---------     	|--------                                  	|
+  |‹x x›         	| Left/Right modifiers (e.g., ‹⎈ LCtrl)    	|
+  |⇧             	| Shift                                    	|
+  |⎈ ⌃           	| Control                                  	|
+  |⌘ ◆ ❖         	| Windows/Command                          	|
+  |⎇ ⌥           	| Alt                                      	|
+  |⇪             	| capslock                                 	|
+  |⎋             	|`escape`                                  	|
+  |⭾ ↹           	|`tab`                                     	|
+  |␠ ␣           	| `spc` spacebar                             	|
+  |␈ ⌫           	|`bspc` backspace (delete backward)         |
+  |␡ ⌦           	|`del` delete forward                      	|
+  |⏎ ↩ ⌤ ␤       	|`ret` return or enter                     	|
+  |︔ ⸴ ．⁄        	|semicolon `;` / comma `,` / period `.` / slash `/`	|
+  |⧵ ＼           	| backslash `\`                            	|
+  |﹨ <           	|`non_us_backslash`                        	|
+  |【 「 〔 ⎡       	|`open_bracket`                            	|
+  |】 」 〕 ⎣       	|`close_bracket`                           	|
+  |ˋ ˜           	|`grave_accent_and_tilde`                  	|
+  |‐ ₌           	|`hyphen` `equal_sign`                     	|
+  |▲ ▼ ◀ ▶       	|`up`/`down`/`left`/`right` (arrows)        |
+  |⇞ ⇟           	|`pgup`/`pgdn` (page up, page down)	      |
+  |⎀             	|`insert`                               	|
+  |⇤ ⤒ ↖         	|`home`                                 	|
+  |⇥ ⤓ ↘         	|`end`                                  	|
+  |⇭             	|`numlock`                              	|
+  |🔢₁ 🔢₂ 🔢₃ 🔢₄ 🔢₅	|`keypad_` `1`–`5`                      	|
+  |🔢₆ 🔢₇ 🔢₈ 🔢₉ 🔢₀	|`keypad_` `6`–`0`                      	|
+  |🔢₋ 🔢₌ 🔢₊      	|`keypad_` `hyphen`/`equal_sign`/`plus` 	|
+  |🔢⁄ 🔢．🔢∗       	|`keypad_` `slash`/`period`/`asterisk`  	|
+  |◀◀ ▶⏸ ▶▶      	|`vk_consumer_` `previous`/`play`/`next`	|
+  |🔊 🔈+ or ➕₊⊕   	|`volume_up`                            	|
+  |🔉 🔈− or ➖₋⊖   	|`volume_down`                          	|
+  |🔇 🔈⓪ or ⓿ ₀   	|`mute`                                 	|
+  |🔆 🔅           	|`vk_consumer_brightness_` `up`/`down`  	|
+  |⌨💡+ or ➕₊⊕    	|`vk_consumer_illumination_up`          	|
+  |⌨💡− or ➖₋⊖    	|`vk_consumer_illumination_down`        	|
+  |🎛             	|`vk_dashboard`                         	|
+  |▤ ☰ 𝌆         	|`application`                          	|
+  |🖰1 🖰2 ... 🖰5  	|`button` `1`–`5`                       	|
+  |‹🖰 🖰›         	|`button` `1` `2`                       	|
+
+[^1]: space-separated list of keys; `or` means only last symbol in a pair changes
diff --git a/docs/kmonad_comparison.md b/docs/kmonad_comparison.md
index 39c414952..1017354a9 100644
--- a/docs/kmonad_comparison.md
+++ b/docs/kmonad_comparison.md
@@ -4,7 +4,7 @@ The kmonad project is the closest alternative for this project.
 
 ## Benefits of kmonad over kanata
 
-- MacOS support
+- ~MacOS support~ (this is implemented now)
 - Different features
 
 ## Why I built and use kanata
diff --git a/docs/locales.adoc b/docs/locales.adoc
index 86cd80906..0a94f6367 100644
--- a/docs/locales.adoc
+++ b/docs/locales.adoc
@@ -1,14 +1,47 @@
+////
+Commented out since it doesn't seem to add anything for now, but maybe in the future
+:sectlinks:
+:sectanchors:
+////
+
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
 = Keyboard locales
+
+////
+Commented out since doc is short enough without a ToC for the time being.
 :toc:
-:toc-placement!:
-:toc-title!:
+:toc-title: pass:[<b>TABLE OF CONTENTS</b>]
+:toclevels: 3
+////
 
-== Table of contents
-toc::[]
+== ISO 100% Keyboard (event.code)
+
+NOTE: Tested on Linux only
+
+[%collapsible]
+====
+----
+(defsrc
+  Escape                   F1      F2     F3     F4         F5     F6     F7     F8             F9         F10            F11  F12      PrintScreen  ScrollLock  Pause
+  Backquote        Digit1 Digit2 Digit3 Digit4 Digit5 Digit6 Digit7 Digit8 Digit9 Digit0       Minus       Equal         Backspace      Insert       Home        PageUp        NumLock NumpadDivide NumpadMultiply NumpadSubtract
+  Tab                   KeyQ   KeyW   KeyE   KeyR   KeyT   KeyY   KeyU   KeyI   KeyO    KeyP       BracketLeft BracketRight  Enter      Delete       End         PageDown      Numpad7 Numpad8      Numpad9        NumpadAdd
+  CapsLock              KeyA   KeyS   KeyD   KeyF   KeyG   KeyH   KeyJ   KeyK   KeyL   Semicolon     Quote      Backslash                                                      Numpad4 Numpad5      Numpad6
+  ShiftLeft IntlBackslash  KeyZ   KeyX   KeyC   KeyV   KeyB   KeyN   KeyM   Comma  Period       Slash                   ShiftRight                   ArrowUp                   Numpad3 Numpad2      Numpad1        NumpadEnter
+  ControlLeft       MetaLeft AltLeft                   Space                   AltRight       MetaRight   ContextMenu ControlRight      ArrowLeft    ArrowDown   ArrowRight    Numpad0              NumpadDecimal  
+)
+----
+====
 
-== ISO German QWERTZ - Windows (non-interception)
+== ISO German QWERTZ (Windows, non-interception)[[german]]
 
-=== Using `deflocalkeys-win`:
+=== Using `deflocalkeys-win`:[[german-defwin]]
 
 [%collapsible]
 ====
@@ -35,7 +68,7 @@ toc::[]
 ----
 ====
 
-=== Without using `deflocalkeys`:
+=== Without using `deflocalkeys`:[[german-nodeflocalkeys]]
 
 [%collapsible]
 ====
@@ -50,7 +83,7 @@ toc::[]
 ----
 ====
 
-=== Example aliases
+=== Example aliases[[german-aliases]]
 
 [%collapsible]
 ====
@@ -100,3 +133,220 @@ toc::[]
 )
 ----
 ====
+
+== ISO German QWERTZ (MacOS)[[german]]
+
+=== Using `deflocalkeys-macos`:[[german-defmac]]
+
+[%collapsible]
+====
+----
+(deflocalkeys-macos
+  ß    12
+  ´    13
+  z    21
+  ü    26
+  +    27
+  ö    39
+  ä    40
+  <    41
+  #    43
+  y    44
+  -    53
+  ^    86
+)
+
+(defsrc
+  ⎋         f1   f2   f3   f4   f5   f6   f7   f8   f9   f10  f11  f12
+  ^         1    2    3    4    5    6    7    8    9    0    ß    ´    ⌫
+  ↹         q    w    e    r    t    z    u    i    o    p    ü    +
+  ⇪         a    s    d    f    g    h    j    k    l    ö    ä    #    ↩
+ ‹⇧   <     y    x    c    v    b    n    m    ,    .    -         ▲    ⇧›
+  fn       ‹⌃   ‹⌥   ‹⌘              ␣              ⌘›   ⌥›   ◀    ▼    ▶
+)
+----
+====
+
+== ISO French Azerty (MacOS)[[french]]
+
+=== Using `deflocalkeys-macos`:[[french-defmac]]
+
+[%collapsible]
+====
+----
+(deflocalkeys-macos
+  @    50
+  par  12 ;; Close parentheses
+  -    13
+  ^    73
+  $    164
+  ù    85
+  `    192
+  <    41
+  /    191
+  =    53
+  a    16
+  q    30
+  z    17
+  w    44
+  m    39
+)
+
+(defsrc
+  ⎋         f1   f2   f3   f4   f5   f6   f7   f8   f9  f10   f11  f12
+  @         1    2    3    4    5    6    7    8    9    0    par   -    ⌫
+  ↹         a    z    e    r    t    y    u    i    o    p     ^    $
+  ⇪         q    s    d    f    g    h    j    k    l    m     ù    `    ↩
+ ‹⇧   <     w    x    c    v    b    n    ,    .    /    =          ▲    ⇧›
+  fn       ‹⌃   ‹⌥   ‹⌘              ␣              ⌘›   ⌥›    ◀    ▼    ▶
+)
+----
+====
+
+== ISO French AZERTY (Windows, non-interception)[[french]]
+
+NOTE: This is for the https://kbdlayout.info/kbdfr?arrangement=ISO105[French AZERTY layout] (ISO105 arrangement). Tested on Windows only.
+
+[%collapsible]
+====
+----
+(deflocalkeys-win
+	k252 223 ;; ref to the key [!] (VK_OEM_8)
+)
+
+(defsrc ;; french
+  '        1     2     3     4     5     6     7     8     9     0      [    eql        bspc
+  tab       a     z     e     r     t     y     u     i     o     p      ]     ;
+  caps       q     s     d     f     g     h     j     k     l     m      `     bksl     ret
+  lsft nubs   w     x     c     v     b     n     comm  .     /     k252                rsft
+  lctl    lmet   lalt           spc                             ralt                    rctl
+)
+----
+====
+
+== ISO Turkish QWERTY (Linux)[[turkish]]
+
+NOTE: This is for the https://kbdlayout.info/kbdtuq?arrangement=ISO105[Turkish QWERTY layout] (ISO105 arrangement). Tested on Linux only.
+
+[%collapsible]
+====
+----
+(deflocalkeys-linux
+	* 	12
+	- 	13
+	ı 	23
+	ğ 	26
+	ü 	27
+	ş 	39
+	İ 	40
+	, 	43
+	< 	86
+	ö 	51
+	ç 	52
+	. 	53
+)
+
+(defsrc ;; turkish-iso105
+	grv  	1	2	3	4	5	6	7	8	9	0	*	-	bspc
+	tab  	q	w	e	r	t	y	u	ı	o	p	ğ	ü
+	caps 	a	s	d	f	g	h	j	k	l	ş	İ	,	ret
+	lsft 	<	z	x	c	v	b	n	m	ö	ç	.		rsft
+	lctl	lmet	lalt				spc					ralt	rmet	rctl
+)
+
+;; We use İ instead of i because kanata doesn't allow using i in deflocalkeys, as it is a default key name.
+----
+====
+
+== ABNT2 Brazillian Portuguese QWERTY (Linux)[[portuguese]]
+
+NOTE: This is for the https://kbdlayout.info/kbdbr[ABNT2 QWERTY layout]. Tested on Linux only.
+
+[%collapsible]
+====
+----
+(deflocalkeys-linux
+  ´ 26
+  [ 27
+  ç 39
+  ~ 40
+  ' 41
+  ] 43
+  ; 53
+  \ 86
+  / 89
+)
+
+(defsrc ;; brazillian-abnt2
+  esc  f1    f2   f3   f4   f5   f6   f7   f8   f9   f10  f11  f12 
+  '    1     2    3    4    5    6    7    8    9    0    -    =   bspc
+  tab  q     w    e    r    t    y    u    i    o    p    ´    [   ret
+  caps a     s    d    f    g    h    j    k    l    ç    ~    ]  
+  lsft \     z    x    c    v    b    n    m    ,    .    ;    rsft
+  lctl lmet  lalt           spc            ralt      /
+)
+----
+====
+
+== ISO Swedish QWERTY (Linux)[[swedish]]
+
+[%collapsible]
+====
+----
+;; Swedish ISO105
+(deflocalkeys-linux
+  §   41
+  +   12
+  ´   13 ;; Acute accent. Opposite to the grave accent (grv).
+  å   26
+  ¨   27
+  ö   39
+  ä   40
+  '   43
+  <   86
+  ,   51
+  .   52
+  -   53
+)
+
+(defsrc ;; Swedish ISO105
+  §    1    2    3    4    5    6    7    8    9    0    +    ´    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    å    ¨
+  caps a    s    d    f    g    h    j    k    l    ö    ä    '    ret
+  lsft <    z    x    c    v    b    n    m    ,    .    -         rsft
+  lctl lmet lalt                spc                 ralt rmet menu rctl
+)
+
+;; Empty layer that matches the Swedish layout
+(deflayer default
+  _    _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _         _
+  _    _    _                   _                   _    _    _    _
+)
+----
+====
+
+
+== Swedish QWERTY Localkeys (Windows)[[swedish]]
+
+[%collapsible]
+====
+----
+(deflocalkeys-win
+  §   220
+  +   187
+  ´   219
+  å   221
+  ¨   186
+  ö   192
+  ä   222
+  '   191
+  <   226
+  ,   188
+  .   190
+  -   189
+)
+----
+====
diff --git a/docs/platform-known-issues.adoc b/docs/platform-known-issues.adoc
index a6f7724e2..71f482623 100644
--- a/docs/platform-known-issues.adoc
+++ b/docs/platform-known-issues.adoc
@@ -1,11 +1,26 @@
+= Hardware known issues
+
+At the electric circuit layer of many keyboards,
+cost-saving measures can lead to key presses not registering
+when pressing multiple keys simultaneously.
+Usually this happens with at least 3 key presses.
+Kanata cannot fix this issue.
+You can work around it by avoiding
+the problem key combination,
+or using a different keyboard.
+
 = Platform-dependent known issues
 
 == Preface
 
 This document contains a list of known issues
 which are unique to a given platform.
-The officially supported platforms today
-are Windows 10/11 and Linux.
+The platform supported by the core maintainer (jtroo)
+are Windows 11 and Linux.
+Windows 10 is expected to work fine,
+but as Windows 10 end-of-support is approaching in 2025,
+jtroo no longer has any devices with it installed.
+
 On Windows, there are two backing mechanisms that can be used
 for keyboard input/output and they have different issues.
 These will be differentiated by the words "LLHOOK" and "Interception",
@@ -14,39 +29,73 @@ which map to the binaries
 
 == Windows 11 LLHOOK
 
-* The emoji picker does not work properly
-** https://github.com/jtroo/kanata/issues/240
-
-== Windows 10+11 LLHOOK
-
-* Mouse inputs cannot be used for processing or remapping
-** https://github.com/jtroo/kanata/issues/108
-** https://github.com/jtroo/kanata/issues/170
 * Some input key combinations (e.g. Win+L) cannot be intercepted before
   running their default action
 ** https://github.com/jtroo/kanata/issues/192
 ** https://github.com/jtroo/kanata/discussions/428
 * OS-level key remapping behaves differently vs. Linux or Interception
+** Does not affect winiov2 variant
 ** https://github.com/jtroo/kanata/issues/152
 * Certain applications that also use the LLHOOK mechanism may not behave correctly
 ** https://github.com/jtroo/kanata/issues/55
 ** https://github.com/jtroo/kanata/issues/250
 ** https://github.com/jtroo/kanata/issues/430
 ** https://github.com/espanso/espanso/issues/1488
-* AltGr can misbehave
+* AltGr / ralt / Right Alt can misbehave
 ** https://github.com/jtroo/kanata/blob/main/docs/config.adoc#windows-only-windows-altgr
+* NumLock state can mess with arrow keys in unexpected ways
+** Does not affect winiov2 variant
+** https://github.com/jtroo/kanata/issues/78
+** https://github.com/jtroo/kanata/issues/667
+** Workaround: use the correct https://github.com/jtroo/kanata/discussions/354[numlock state]
+* Without `process-unmapped-keys yes`, using arrow keys
+without also having the shift keys in `defsrc` will break shift highlighting
+** Does not affect winiov2 variant
+** https://github.com/jtroo/kanata/issues/858
+** Workaround: add shift keys to `defsrc` or use `process-unmapped-keys yes` in `defcfg`
 
-== Windows Interception
+== Windows 11 Interception
 
 * Sleeping your system or unplugging/replugging devices enough times causes
   inputs to stop working
 ** https://github.com/oblitum/Interception/issues/25
 * Some less-frequently used keys are not supported or handled correctly
+** https://github.com/jtroo/kanata/issues/127
 ** https://github.com/jtroo/kanata/issues/164
 ** https://github.com/jtroo/kanata/issues/425
+** https://github.com/jtroo/kanata/issues/532
 
 == Linux
 
 * Key repeats can occur when they normally wouldn't in some cases
 ** https://github.com/jtroo/kanata/discussions/422
 ** https://github.com/jtroo/kanata/issues/450
+** https://github.com/jtroo/kanata/issues/1441
+* Unicode support has varying success due to many applications
+  not supporting the `ibus` input mechanism.
+  Using xkb to map keys to unicode
+  or using clipboard actions are more consistent solutions
+** https://github.com/jtroo/kanata/discussions/703
+* Key actions can behave incorrectly due to the rapidity of key events
+** https://github.com/jtroo/kanata/discussions/733
+** https://github.com/jtroo/kanata/issues/740
+** adjusting https://github.com/jtroo/kanata/blob/main/docs/config.adoc#rapid-event-delay[rapid-event-delay] can potentially be a workaround
+* Macro keys on certain gaming keyboards might stop being processed
+** Context: search for `POTENTIAL PROBLEM - G-keys` in
+link:../src/kanata/mod.rs[the code].
+** Workaround: leave `process-unmapped-keys` disabled
+and explicitly map keys in `defsrc` instead
+
+== MacOS
+
+* Keyboard and mouse input processing requires the Input Monitoring permission in
+  System Settings > Privacy & Security. On first startup kanata asks macOS to
+  register itself under that pane so there is something to toggle on; if the
+  permission has already been denied, kanata exits early with a message pointing
+  you to the same setting instead of failing deeper in the driver stack.
+* In order to send mouse events/movements, it may be necessary to also add the kanata binary in
+  `System Settings > Privacy & Security > Accessibility` (discussed in https://github.com/jtroo/kanata/issues/1574[issue #1574]).
+* Once the mouse event tap is installed (on startup or via live-reload), it
+  continues running for the lifetime of the process. Removing all mouse keys
+  from `defsrc` then live-reloading does not stop the tap thread, though it
+  becomes a no-op pass-through.
diff --git a/docs/release-template.md b/docs/release-template.md
index f9866390a..aff6ee314 100644
--- a/docs/release-template.md
+++ b/docs/release-template.md
@@ -1,10 +1,14 @@
+## Configuration guide
+
+<!-- NOTE: GitHub release doc seems to not support multiline paragraph joining as opposed to other places markdown is used in GitHub. Keep paragraphs on one line in this file, as ugly as it is to do so. -->
+
+Link to the appropriate configuration guide version: [guide link TODO: FIX LINK](https://github.com/jtroo/kanata/blob/FIXME/docs/config.adoc).
+
 ## Changelog (since <TODO: previous_version_here>)
 
 <details>
 <summary>Change log</summary>
-
-- TODO: fill this out
-
+* TODO: fill this out
 </details>
 
 ## Sample configuration file
@@ -16,11 +20,59 @@ The attached `kanata.kbd` file is tested to work with the current version. The o
 <details>
 <summary>Instructions</summary>
 
-Download `kanata.exe`. Optionally, download `kanata.kbd`. With the two files in the same directory, you can double-click the `exe` to start kanata. Kanata does not start a background process, so the window needs to stay open after startup. See [this discussion](https://github.com/jtroo/kanata/discussions/193) for tips to run kanata in the background.
+Download the appropriate `kanata-windows-variant.zip` file for your machine CPU. Extract and move the desired binary variant to its intended location. Optionally, download `kanata.kbd`. With the two files in the same directory, you can double-click the extracted `.exe` file to start kanata. Kanata does not start a background process, so the window needs to stay open after startup. See [this discussion](https://github.com/jtroo/kanata/discussions/193) for tips to run kanata in the background.
+
+You need to run via `cmd` or `powershell` to use a different configuration file:
+
+`kanata_windows_binaryvariant.exe --cfg <cfg_file>`
 
-You need to run `kanata.exe` via `cmd` or `powershell` to use a different configuration file:
+### Binary variants
 
-`kanata.exe --cfg <cfg_file>`
+Explanation of items in the binary variant:
+
+- x64 vs. arm64:
+  - Select x64 if your machine's CPU is Intel or AMD. If ARM, use arm64.
+- tty vs gui:
+  - tty runs in a terminal, gui runs as a system tray application
+- cmd\_allowed vs. not
+  - cmd\_allowed allows the `cmd` actions; otherwise, they are compiled out of the application
+- winIOv2 vs. wintercept
+  - winIOv2 uses the LLHOOK and SendInput Windows mechanisms to intercept and send events.
+  - wintercept uses the [Interception driver](https://github.com/oblitum/Interception). Beware of its known issue that disables keyboards and mice until system reboot: [Link to issue](https://github.com/oblitum/Interception/issues/25).
+    - you will need to install the driver using the release or from the [copy in this repo](https://github.com/jtroo/kanata/tree/main/assets).
+    - the benefit of using this driver is that it is a lower-level mechanism than Windows hooks, and `kanata` will work in more applications.
+
+### wintercept installation
+
+#### Steps to install the driver
+
+- extract the `.zip`
+- run a shell with administrator privilege
+- run the script `"command line installer/install-interception.exe"`
+- reboot
+
+#### Additional installation steps
+
+The above steps are those recommended by the interception driver author. However, I have found that those steps work inconsistently and sometimes the dll stops being able to be loaded. I suspect it has something to do with being installed in the privileged location of `system32\drivers`.
+
+To help with the dll issue, you can copy the following file in the zip archive to the directory that kanata starts from: `Interception\library\x64\interception.dll`.
+
+E.g. if you start kanata from your `Documents` folder, put the file there:
+
+**Example:**
+
+```
+C:\Users\my_user\Documents\
+    kanata_windows_wintercept_x64.exe
+    kanata.kbd
+    interception.dll
+```
+
+### kanata\_passthru_x64.dll
+
+The Windows `kanata_passthru_x64.dll` file allows using Kanata as a library within AutoHotkey to avoid conflicts between keyboard hooks installed by both. You can channel keyboard input events received by AutoHotkey into Kanata's keyboard engine and get the transformed keyboard output events (per your Kanata config) that AutoHotkey can then send to the OS.
+
+To make use of this, take `kanata_passthru_x64.dll`, then the [simulated\_passthru\_ahk](https://github.com/jtroo/kanata/blob/main/docs/simulated_passthru_ahk) folder with a brief example, place the dll there, open `kanata_passthru.ahk` to read what the example does and then double-click to launch it.
 
 </details>
 
@@ -29,64 +81,81 @@ You need to run `kanata.exe` via `cmd` or `powershell` to use a different config
 <details>
 <summary>Instructions</summary>
 
-Download `kanata`.
+Download the `kanata-linux-x64.zip` file.
+
+ Extract and move the desired binary variant to its intended location. Run the binary in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup. See [this discussion](https://github.com/jtroo/kanata/discussions/130) for how to set up kanata with systemd.
+
+**Example:**
 
-Run it in a terminal and point it to a valid configuration file.  Kanata does not start a background process, so the window needs to stay open after startup. See [this discussion](https://github.com/jtroo/kanata/discussions/130) for how to set up kanata with systemd.
 ```
 chmod +x kanata   # may be downloaded without executable permissions
-sudo ./kanata --cfg <cfg_file>`
+sudo ./kanata_linux_x64 --cfg <cfg_file>`
 ```
 
 To avoid requiring `sudo`, [follow the instructions here](https://github.com/jtroo/kanata/wiki/Avoid-using-sudo-on-Linux).
 
+### Binary variants
+
+Explanation of items in the binary variant:
+
+- cmd\_allowed vs. not
+  - cmd\_allowed allows the `cmd` actions; otherwise, they are compiled out of the application
+
 </details>
 
-## cmd_allowed variants
+## macOS
 
 <details>
-<summary>Explanation</summary>
+<summary>Instructions</summary>
 
-The binaries with the name `cmd_allowed` are conditionally compiled with the `cmd` action enabled.
+The supported Karabiner driver version in this release is `v6.2.0`.
 
-Using the regular binaries, there is no way to get the `cmd` action to work. This action is restricted behind conditional compilation because I consider the action to be a security risk that should be explicitly opted into and completely forbidden by default.
+**NOTE**: macOS mouse button input requires Accessibility or Input Monitoring permission in System Settings > Privacy & Security.
 
-</details>
+### Binary variants
 
-## wintercept variants
+Explanation of items in the binary variant:
 
-<details>
-<summary>Explanation and instructions</summary>
+- x64 vs. arm64:
+  - Select x64 if your machine's CPU is Intel. If ARM, use arm64.
+- cmd\_allowed vs. not
+  - cmd\_allowed allows the `cmd` actions; otherwise, they are compiled out of the application
 
-### Warning: known issue
+### Instructions for macOS 11 and newer
 
-This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/25. This will affect you if you put your PC to sleep instead of shutting it down, or if you frequently plug/unplug USB devices.
+You must use the Karabiner driver version `v6.2.0`.
 
-### Description
+Please read through this issue comment:
 
-These variants use the [Interception driver](http://www.oblita.com/interception) instead of Windows hooks. You will need to install the driver using the assets from the linked website or from the [copy in this repo](https://github.com/jtroo/kanata/tree/main/assets). The benefit of using this driver is that it is a lower-level mechanism than Windows hooks. This means `kanata` will work in more applications, including administrator-privileged apps.
+https://github.com/jtroo/kanata/issues/1264#issuecomment-2763085239
 
-### Steps to install the driver
+Also have a read through this discussion:
 
-- extract the `.zip`
-- run a shell with administrator privilege
-- run the script `"command line installer/install-interception.exe"`
-- reboot
+https://github.com/jtroo/kanata/discussions/1537
 
-### Additional installation steps
+At some point it may be beneficial to provide concise and accurate instructions within this documentation. The maintainer (jtroo) does not own macOS devices to validate; please contribute the instructions to the file `docs/release-template.md` if you are able.
 
-The above steps are those recommended by the interception driver author. However, I have found that those steps work inconsistently and sometimes the dll stops being able to be loaded. I think it has something to do with being installed in the privileged location of `system32\drivers`.
+### Install Karabiner driver for macOS 10 and older:
 
-To help with the dll issue, you can copy the following file in the zip archive to the directory that kanata starts from: `Interception\library\x64\interception.dll`.
+- Install the [Karabiner kernel extension](https://github.com/pqrs-org/Karabiner-VirtualHIDDevice).
 
-E.g. if you start kanata from your `Documents` folder, put the file there:
+### After installing the appropriate driver for your OS (both macOS <=10 and >=11)
+
+Download the appropriate `kanata-macos-variant.zip` for your machine CPU.
+
+Extract and move the desired binary variant to its intended location. Run the binary in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup.
+
+**Example:**
 
 ```
-C:\Users\my_user\Documents\
-    kanata_wintercept.exe
-    kanata.kbd
-    interception.dll
+chmod +x kanata_macos_arm64   # may be downloaded without executable permissions
+sudo ./kanata_macos_arm64 --cfg <cfg_file>`
 ```
 
+### Add permissions
+
+If Kanata is not behaving correctly, you may need to add permissions. Please see this issue: [link to macOS permissions issue](https://github.com/jtroo/kanata/issues/1211).
+
 </details>
 
 ## sha256 checksums
diff --git a/docs/sequence-adding-chords-ideas.md b/docs/sequence-adding-chords-ideas.md
index b7fe3a345..5bd5621c3 100644
--- a/docs/sequence-adding-chords-ideas.md
+++ b/docs/sequence-adding-chords-ideas.md
@@ -61,7 +61,7 @@ of this type of sequence, but that seems complicated.
 Or maybe have a `u16` with a special bit pattern that could be used
 to differentiate between `(S-(a b))` and `(lsft a b)`.
 For now, let's say that the bit pattern is `0xFFFF`.
-If a modifier is pressed and the the sequence `[..., <mod>, 0xFFFF]`
+If a modifier is pressed and the sequence `[..., <mod>, 0xFFFF]`
 exists in the trie: continue processing the sequence in mod-aware mode.
 
 OR for simplicity, just say "screw backwards compatibility" and force users
diff --git a/docs/setup-linux.md b/docs/setup-linux.md
new file mode 100644
index 000000000..38715c6d6
--- /dev/null
+++ b/docs/setup-linux.md
@@ -0,0 +1,159 @@
+# Instructions
+
+In Linux, kanata needs to be able to access the input and uinput subsystem to inject events. To do this, your user needs to have permissions. Follow the steps in this page to obtain user permissions.
+
+### 1. Create the uinput group (if it doesn’t exist)
+
+```bash
+sudo groupdel uinput 2>/dev/null
+sudo groupadd --system uinput
+```
+
+### 2. Add your user to the `input` and `uinput` group
+
+```sh
+sudo usermod -aG input $USER
+sudo usermod -aG uinput $USER
+```
+
+Verify:
+
+```sh
+groups
+```
+
+You may need to log out and back in for it to take effect.
+
+### 3. Load the uinput kernel module
+
+```sh
+sudo modprobe uinput
+```
+
+This ensures `/dev/uinput` exists.
+
+### 4. Make sure the uinput device file has the right permissions.
+
+Create the udev rule:
+
+```bash
+sudo tee /etc/udev/rules.d/99-input.rules > /dev/null <<EOF
+KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"
+EOF
+```
+
+Reload udev rules:
+
+```bash
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+Verify:
+
+```bash
+ls -l /dev/uinput
+```
+
+Expected output:
+
+```bash
+crw-rw---- 1 root uinput 10, <minor> <MMM DD HH:MM> /dev/uinput
+```
+
+## 5. (Optional) Run Kanata immediately if the group change isn’t active
+
+If `uinput` is not listed in `groups` even after adding your user:
+
+```bash
+newgrp uinput -c kanata
+```
+
+This temporarily gives the current shell the `uinput` group so kanata can access `/dev/uinput` until the next login.
+
+### 6a. (Optional) Create and enable a systemd user service
+
+First, create the directory for user services:
+
+```bash
+mkdir -p ~/.config/systemd/user
+```
+
+Then add this to: `~/.config/systemd/user/kanata.service`:
+
+```bash
+[Unit]
+Description=Kanata keyboard remapper
+Documentation=https://github.com/jtroo/kanata
+
+[Service]
+Environment=PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/bin
+#   Uncomment the 4 lines beneath this to increase process priority
+#   of Kanata in case you encounter lagginess when resource constrained.
+#   WARNING: doing so will require the service to run as an elevated user such as root.
+#   Implementing least privilege access is an exercise left to the reader.
+#
+# CPUSchedulingPolicy=rr
+# CPUSchedulingPriority=99
+# IOSchedulingClass=realtime
+# Nice=-20
+Type=simple
+ExecStart=/usr/bin/sh -c 'exec $$(which kanata) --cfg $${HOME}/.config/kanata/config.kbd --no-wait'
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=default.target
+```
+
+Note: The `--no-wait` flag is required for `Restart=on-failure` to work.
+Without it, kanata waits for user input on exit, which blocks automatic restart.
+
+Make sure to update the executable location for sh in the snippet above.
+This would be the line starting with `ExecStart=/usr/bin/sh -c`.
+You can check the executable path with:
+
+```bash
+which sh
+```
+
+Also, verify if the path to kanata is included in the line `Environment=PATH=[...]`.
+For example, if executing `which kanata` returns `/home/[user]/.cargo/bin/kanata`, the `PATH` line should be appended with `/home/[user]/.cargo/bin` or `:%h/.cargo/bin`.
+`%h` is one of the specifiers allowed in systemd, more can be found in https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#Specifiers
+
+Then run:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable kanata.service
+systemctl --user start kanata.service
+systemctl --user status kanata.service   # check whether the service is running
+```
+
+### 6b. To create and enable an OpenRC daemon service
+
+Edit new file `/etc/init.d/kanata` as root, replacing \<username\> as appropriate:
+
+```bash
+#!/sbin/openrc-run
+
+command="/home/<username>/.cargo/bin/kanata"
+#command_args="--cfg=/home/<username>/.config/kanata/kanata.kbd"
+
+command_background=true
+pidfile="/run/${RC_SVCNAME}.pid"
+
+command_user="<username>"
+```
+
+Then run:
+
+```
+sudo chmod +x /etc/init.d/kanata # script must be executable
+sudo rc-service kanata start
+rc-status # check that kanata isn't listed as [ crashed ]
+sudo rc-update add kanata default # start the service automatically at boot
+```
+
+# Credits
+
+The original text was taken and adapted from: https://github.com/kmonad/kmonad/blob/master/doc/faq.md#linux
diff --git a/docs/setup-macos.md b/docs/setup-macos.md
new file mode 100644
index 000000000..f96e1c6c6
--- /dev/null
+++ b/docs/setup-macos.md
@@ -0,0 +1,225 @@
+# Instructions
+
+On macOS, kanata grabs the keyboard via the
+[Karabiner-DriverKit-VirtualHIDDevice](https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice)
+driver. The kanata process must run as root because the Karabiner virtual HID
+daemon exposes its IPC under `/Library/Application Support/org.pqrs/tmp/rootonly/`,
+which only root can access. This page walks through installing the driver,
+granting permissions, and (optionally) registering kanata as a LaunchDaemon so
+it starts at boot.
+
+### 1. Prerequisites
+
+- macOS 11 (Big Sur) or newer.
+- Xcode Command Line Tools, only if you intend to build kanata from source:
+
+```sh
+xcode-select --install
+```
+
+### 2. Install Karabiner-DriverKit-VirtualHIDDevice
+
+The supported driver version is `v6.2.0`. Kanata's bundled
+`karabiner-driverkit` crate is built against that release's IPC, and pqrs
+ships protocol changes between minor versions, so newer driver releases
+are not guaranteed to work. Download the `.pkg` from the
+[v6.2.0 release page](https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/releases/tag/v6.2.0)
+and run the installer.
+
+Then activate the driver and approve its system extension:
+
+```sh
+sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager forceActivate
+```
+
+Open `System Settings > General > Login Items & Extensions > Driver Extensions`
+and toggle on the entry for `org.pqrs.Karabiner-DriverKit-VirtualHIDDevice`.
+A reboot may be required if you previously ran `deactivate`.
+
+Verify the system extension is activated:
+
+```sh
+sudo launchctl list | grep org.pqrs
+```
+
+If you have **Karabiner-Elements** installed, you should see
+`org.pqrs.service.daemon.Karabiner-VirtualHIDDevice-Daemon` listed — KE
+manages the daemon automatically and you can skip ahead to Step 3.
+
+If you installed **only** the standalone DriverKit package (no
+Karabiner-Elements), the daemon will not start on its own. You need to
+launch it manually or install a LaunchDaemon so it starts at boot.
+
+**Quick test (won't survive reboot):**
+
+```sh
+sudo "/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon" &
+```
+
+**Persistent (LaunchDaemon):** use the included plist to run the daemon at boot:
+
+```sh
+sudo cp cfg_samples/karabiner-vhid-daemon.plist \
+  /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+sudo chown root:wheel \
+  /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+sudo launchctl bootstrap system \
+  /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+```
+
+Verify it started:
+
+```sh
+sudo launchctl list | grep org.pqrs
+```
+
+You should now see the daemon listed.
+
+### 3. Install the kanata binary
+
+Either download a pre-built binary from the
+[releases page](https://github.com/jtroo/kanata/releases) and place it on
+your `PATH`:
+
+```sh
+chmod +x kanata-macos-arm64
+sudo mv kanata-macos-arm64 /usr/local/bin/kanata
+```
+
+Or build from source:
+
+```sh
+git clone https://github.com/jtroo/kanata && cd kanata
+cargo build --release
+sudo cp target/release/kanata /usr/local/bin/kanata
+```
+
+### 4. Grant macOS privacy permissions
+
+kanata needs Input Monitoring permission in
+`System Settings > Privacy & Security > Input Monitoring` to read keyboard
+devices. The first time you run kanata as root, macOS will prompt you to add
+the binary; you can also pre-add `/usr/local/bin/kanata` (or wherever you
+installed it) by clicking the `+` button and selecting the binary.
+
+kanata also needs Accessibility permission in
+`System Settings > Privacy & Security > Accessibility`. Installers can ask
+macOS to register/show the Accessibility prompt without starting the remap
+loop:
+
+```sh
+/usr/local/bin/kanata --macos-request-permissions || true
+open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+```
+
+When launched from Terminal, macOS can report the Terminal/responsible process
+as trusted. If kanata does not appear as its own item in Accessibility, add the
+installed kanata binary manually with the `+` button.
+
+### 5. Smoke test from terminal
+
+Pick a sample config (or your own) and run:
+
+```sh
+sudo kanata -c cfg_samples/simple.kbd
+```
+
+You should see log lines similar to:
+
+```
+[INFO] kanata v1.x.x starting
+[INFO] entering the processing loop
+[INFO] init: catching only releases and sending immediately
+[INFO] Sleeping for 2s. Please release any keys now.
+[INFO] Starting kanata proper
+```
+
+Press a remapped key to confirm the mapping fires. `ctrl+space+esc` (held
+together) cleanly exits kanata.
+
+If kanata aborts immediately with a `libc++abi` / `filesystem_error` message,
+the on-process diagnostic will print three likely causes: not running as root,
+the Karabiner driver not installed/approved, or another process is grabbing
+the keyboard exclusively. See the troubleshooting section below.
+
+### 6. (Optional) Install as a LaunchDaemon
+
+For login-time / boot-time startup, use the sample LaunchDaemon plist in
+[`cfg_samples/kanata.plist`](../cfg_samples/kanata.plist).
+
+Edit the two paths in `ProgramArguments` to point at your kanata binary and
+your config file (the defaults are `/usr/local/bin/kanata` and
+`/etc/kanata/kanata.kbd`), then install:
+
+```sh
+sudo cp cfg_samples/kanata.plist /Library/LaunchDaemons/dev.kanata.kanata.plist
+sudo chown root:wheel /Library/LaunchDaemons/dev.kanata.kanata.plist
+sudo launchctl bootstrap system /Library/LaunchDaemons/dev.kanata.kanata.plist
+```
+
+Verify it is running:
+
+```sh
+sudo launchctl print system/dev.kanata.kanata
+```
+
+Logs are written to `/var/log/kanata.log`.
+
+After editing your kanata config (or the plist itself), reload with:
+
+```sh
+sudo launchctl kickstart -k system/dev.kanata.kanata
+```
+
+### 7. Uninstall
+
+Remove the LaunchDaemon (if you installed it):
+
+```sh
+sudo launchctl bootout system/dev.kanata.kanata
+sudo rm /Library/LaunchDaemons/dev.kanata.kanata.plist
+```
+
+If you installed the VHID daemon plist (standalone DriverKit only):
+
+```sh
+sudo launchctl bootout system/org.pqrs.Karabiner-VirtualHIDDevice-Daemon
+sudo rm /Library/LaunchDaemons/org.pqrs.Karabiner-VirtualHIDDevice-Daemon.plist
+```
+
+Remove the kanata binary:
+
+```sh
+sudo rm /usr/local/bin/kanata
+```
+
+If you are also fully removing the Karabiner driver:
+
+```sh
+sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager deactivate
+```
+
+You may then delete the `Karabiner-VirtualHIDDevice-Manager.app` from
+`/Applications/`.
+
+### 8. Troubleshooting
+
+- **`libc++abi: terminating due to uncaught exception ... filesystem_error`**
+  on startup: the three likely causes, in order, are (1) kanata is not running
+  as root, (2) the Karabiner driver is not installed or its system extension
+  is not approved, (3) another process is already grabbing the keyboard
+  exclusively. The kanata process prints this same hint to stderr right before
+  it aborts.
+- **`connect_failed asio.system:2` in a loop**: the Karabiner VirtualHIDDevice
+  daemon is not running. This happens when using the standalone DriverKit
+  package without Karabiner-Elements. See Step 2 above for how to start the
+  daemon manually or install it as a LaunchDaemon.
+- **A remapped key fires but nothing types**: confirm the kanata binary has
+  Input Monitoring permission in `System Settings > Privacy & Security`. If
+  you reinstalled the binary in place, macOS sometimes invalidates the
+  permission, so toggle it off and back on.
+- **Stuck modifier or layer after the lock screen / fast user switch**:
+  kanata pauses its grab while the screen is locked or another user has the
+  console; the first keystroke after unlock can be dropped. This is by design.
+- See [`docs/platform-known-issues.adoc`](./platform-known-issues.adoc) for
+  the full list of known macOS issues.
diff --git a/docs/simulated_output/sim.kbd b/docs/simulated_output/sim.kbd
new file mode 100644
index 000000000..650acf4b4
--- /dev/null
+++ b/docs/simulated_output/sim.kbd
@@ -0,0 +1,30 @@
+(defcfg
+  process-unmapped-keys	yes	;;|no| enable processing of keys that are not in defsrc, useful if mapping a few keys in defsrc instead of most of the keys on your keyboard. Without this, the tap-hold-release and tap-hold-press actions will not activate for keys that are not in defsrc. Disabled because some keys may not work correctly if they are intercepted. E.g. rctl/altgr on Windows; see the windows-altgr configuration item above for context.
+  log-layer-changes    	yes	;;|no| overhead
+)
+(defvar ;; declare commonly-used values. prefix with $ to call them. They are refered with `$<var name>`
+  tap-repress-timeout 	1000 ;;|500|
+  hold-timeout	        1500 ;;|500|
+  🕐↕          	        $tap-repress-timeout
+  🕐🠿          	        $hold-timeout
+)
+(defalias
+  ;; home row mods ↕tap 🠿hold
+  ;; pinky ring middle index | index middle ring pinky
+  ;; 	          timeout ↕tap 🠿hold¦↕tap 🠿hold action
+  ⌂‹◆	(tap-hold-release $🕐↕ $🕐🠿 a ‹◆)	;;
+  ⌂‹⎇	(tap-hold-release $🕐↕ $🕐🠿 s ‹⎇)	;;
+  ⌂‹⎈	(tap-hold-release $🕐↕ $🕐🠿 d ‹⎈)	;;
+  ⌂‹⇧	(tap-hold-release $🕐↕ $🕐🠿 f ‹⇧)	;;
+  ⌂⇧›	(tap-hold-release $🕐↕ $🕐🠿 j ⇧›)	;; same actions for the right side
+  ⌂⎈›	(tap-hold-release $🕐↕ $🕐🠿 k ⎈›)	;;
+  ⌂⎇›	(tap-hold-release $🕐↕ $🕐🠿 l ⎇›)	;;
+  ⌂◆›	(tap-hold-release $🕐↕ $🕐🠿 ; ◆›)	;;
+)
+
+(defsrc
+` 1 2
+a	s	d	f			j	k	l	;)
+(deflayer ⌂ ;; modtap layer for home row mods and 1 printing a 🤲🏿 char (will appear as 🤲 until kanata's unicode feature is extended)
+  ‗ 🔣🤲🏿 ‗
+  @⌂‹◆ @⌂‹⎇ @⌂‹⎈ @⌂‹⇧        @⌂⇧› @⌂⎈› @⌂⎇› @⌂◆›)
diff --git a/docs/simulated_output/sim.txt b/docs/simulated_output/sim.txt
new file mode 100644
index 000000000..bce4547a2
--- /dev/null
+++ b/docs/simulated_output/sim.txt
@@ -0,0 +1 @@
+↓j 🕐1600 ↓l 🕐5000 ↓1 🕐50 ↑1 🕐50 ↓1 🕐50 ↑1 🕐50 ↑j 🕐50 ↑l 🕐50
diff --git a/docs/simulated_output/sim_out.txt b/docs/simulated_output/sim_out.txt
new file mode 100644
index 000000000..3bf6652a4
--- /dev/null
+++ b/docs/simulated_output/sim_out.txt
@@ -0,0 +1,17 @@
+🕐Δms│           1500    100        1500    3500            50      50            50      50              50
+In───┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ k↑  │                                                      1                     1       J               L
+ k↓  │  J                L                  1                       1
+ k⟳  │
+Σin  │ ↓J 🕐1600         ↓L   🕐5000         ↓1    🕐50       ↑1  🕐50 ↓1  🕐50       ↑1  🕐50 ↑J  🕐50         ↑L  🕐50
+Out──┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ k↑  │                                                                                            ⇧›              ⎇›
+ k↓  │           ⇧›                 ⎇›
+ 🖰↑  │
+ 🖰↓  │
+ 🖰   │
+ 🔣  │                                                🤲                     🤲
+ code│
+ raw↑│
+ raw↓│
+Σout │          ↓⇧›                ↓⎇›                🤲                     🤲                    ↑⇧›             ↑⎇›
diff --git a/docs/simulated_passthru_ahk/[COPY HERE] kanata_passthru.dll _ b/docs/simulated_passthru_ahk/[COPY HERE] kanata_passthru.dll _
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/simulated_passthru_ahk/kanata_dll.kbd b/docs/simulated_passthru_ahk/kanata_dll.kbd
new file mode 100644
index 000000000..04b44c62c
--- /dev/null
+++ b/docs/simulated_passthru_ahk/kanata_dll.kbd
@@ -0,0 +1,17 @@
+;;Test config for kanata.dll use by AutoHotkey, only maps two keys (f,j) to left/right modtap home row mod Shifts
+(defcfg
+  process-unmapped-keys	yes	;;|no| enable processing of keys that are not in defsrc
+  log-layer-changes    	no 	;;|no| overhead
+)
+
+(defvar
+  🕐↕	1000 ;;|500| tap-repress-timeout
+  🕐🠿	1500 ;;|500| hold-timeout
+  )
+(defalias	;;      timeout→ 	tap	  hold   ¦	 tap	 hold ←action
+  f⌂‹⇧   	(tap-hold-release	$🕐↕	$🕐🠿       	f   	‹⇧)
+  j⌂⇧›   	(tap-hold-release	$🕐↕	$🕐🠿       	j   	⇧›)
+  )
+
+(defsrc      f     j   )
+(deflayer ⌂ @f⌂‹⇧ @j⌂⇧›)
diff --git a/docs/simulated_passthru_ahk/kanata_passthru.ahk b/docs/simulated_passthru_ahk/kanata_passthru.ahk
new file mode 100644
index 000000000..37cba17b2
--- /dev/null
+++ b/docs/simulated_passthru_ahk/kanata_passthru.ahk
@@ -0,0 +1,225 @@
+#Requires AutoHotKey 2.1-alpha.4
+/*
+A short example of using Kanata as a library with AutoHotkey, first F8 press will load the library, second F8 press will activate Kanata for a few (ihDuration) seconds with 'f'/'j' turned into home row Shift mods.
+The more useful script would not use F8, but f/j directly as hotkeys, but this owl hasn't been drawn yet...
+Both Kanata and this script mainly output to Windows debug log, use github.com/smourier/TraceSpy to view it
+Dependencies and config:
+*/
+  libPath   	:= "./"              	; kanata_passthru.dll @ this folder
+  kanata_cfg	:= "./kanata_dll.kbd"	; kanata config @ this file location
+  ihDuration	:= 10                	; seconds of activity after pressing F8
+  dbg       	:= 1                 	; script's debug level (0 to silence some of its output)
+  dbg_dll   	:= 1                  ; kanata's debug level (Err=1 Warn=2 Inf=3 Dbg=4 Trace=5)
+/*
+Brief overview of the architecture:
+Setup:
+  - AHK: configures cbKanataOut callback to Send keys out and shares its address with Kanata
+  - Kanata: exports 4 functions
+    - fnKanata_main: set up paths to config and initialize
+    - fnKanata_in_ev: get input key events
+    - K_output_ev_check: check if output key events exist
+    - fnKanata_reset: reset Kanata's state without exiting
+! AHK enables inputhook, so intercepts all keyboard input
+← Redirects all intercepted input to Kanata, where we hit 2 limitations
+  ✗ Kanata can't send keys out itself as it'll be intercepted by AHK's inputhook
+  ✗ Kanata's thread that processes input can't call AHK function in the main thread since AHK is single-threaded
+✓ Kanata opens an async channel from the input processing thread (with Keyberon state machine) to its main
+  ← sends key out data back to the main thread
+  → our script after sending input keys calls Kanata to read this channel until it's empty, and then Sends these keys out
+*/
+
+get_thread_id() {
+  return DllCall("GetCurrentThreadId", "UInt")
+}
+
+F8::kanata_dll('vk77')
+kanata_dll(vkC) {
+  ; static K	:= keyConstant , vk := K._map, sc := K._mapsc  ; various key name constants, gets vk code to avoid issues with another layout
+   ; , s    	:= helperString ; K.▼ = vk['▼']
+  static is_init := false
+   ,lErr:=1, lWarn:=2, lInf:=3, lDbg:=4, lTrace:=5, log_lvl := dbg_dll ; Kanata's
+   ,last↓ := [0,0]
+   ,id_thread := get_thread_id()
+   ,Cvk_d := GetKeyVK(vkC), Csc_d := GetKeySC(vkC), token1 := 1, ih0 := 0 ; decimal value
+   ,C↑ := false, cleanup := false ; track whether the trigger key has been released to not release it twice on kanata cleanup
+  ; set up machinery for AHK and Kanata to communicate
+  ,libNm            	:= "kanata_passthru"
+  ,lib𝑓             	:= libNm '\' 'lib_kanata_passthru' ; receives AHK's address of AHK's cb KanataOut that accepts simulated output events
+  ,lib𝑓input_ev     	:= libNm '\' 'input_ev_listener' ; receives key input and uses event_loop's input event handler callback (which will in turn communicate via the internal kanata's channels to keyberon state machine etc.)
+  ,lib𝑓output_ev    	:= libNm '\' 'output_ev_check' ; checks if output event is ready (it's sent to our callback if it is)
+  ,lib𝑓reset        	:= libNm '\' 'reset_kanata_state' ; reset kanata's state
+  ,hModule          	:= DllCall("LoadLibrary", "Str",libPath libNm '.dll', "Ptr")  ; Avoids the need for DllCall in the loop to load the library
+  ,fnKanata_main    	:= DllCall.Bind(lib𝑓, 'Ptr',unset, 'Str',unset, 'Int',unset)
+  ,fnKanata_in_ev   	:= DllCall.Bind(lib𝑓input_ev, 'Int',unset , 'Int',unset,  'Int',unset)
+  ,K_output_ev_check	:= DllCall.Bind(lib𝑓output_ev)
+  ,fnKanata_reset   	:= DllCall.Bind(lib𝑓reset, 'Int',unset)
+  static ih := InputHook("T" ihDuration " I1")
+  , 🕐k_pre := A_TickCount
+  , 🕐k_now := A_TickCount
+  hooks := "hooks#: " gethookcount()
+
+  addr_cbKanataOut := CallbackCreate(cbKanataOut)
+  if not is_init {
+    is_init := true
+
+    ; setup inputhook callback functions
+    ih.KeyOpt(  	'{All}','NSI')  ; N: Notify. OnKeyDown/OnKeyUp callbacks to be called each time the key is pressed
+    ih.OnKeyDown	:= cbK↓.Bind(1)	;
+    ih.OnKeyUp  	:= cbK↑.Bind(0)	;
+
+    OutputDebug('¦' id_thread "¦registered inputhook with VisibleText=" ih.VisibleText " VisibleNonText=" ih.VisibleNonText "`nIlevel=" ih.MinSendLevel ' hooks#: ' gethookcount() ' →kanata addr#' addr_cbKanataOut)
+    fnKanata_main(addr_cbKanataOut,kanata_cfg,log_lvl) ; setup kanata, passign ahk callback to accept out key events
+    return
+  }
+
+  cbK↓(token,  ih,vk,sc) {
+    static _d := 1, isUp := false, dir := (isUp?'↑':'↓')
+    🕐k_pre := 🕐k_now
+    🕐k_now := A_TickCount
+    if (dbg>=_d) {
+      dbgtxt := ''
+      vk_hex := Format("vk{:x}",vk)
+      key_name := GetKeyName(Format("vk{:x}",vk)) ; bugs with layouts, not english even if english is active
+      dbgtxt .= "ih" dir (isSet(key_name)?key_name:'') "      🢥🄺: vk=" vk "¦" vk_hex " sc=" sc ' l' A_SendLevel " ¦" id_thread "¦"
+      OutputDebug(dbgtxt)
+    }
+    isH := fnKanata_in_ev(vk,sc,isUp)
+    dbgOut := ''
+    for i in [4,4,4,5,5,5] { ; poll a key out channel@kanata) a few times to see if there are key events
+      sleep(i)
+      isOut := K_output_ev_check(), dbgOut.=isOut
+      if (isOut < 0) { ; get as many keys as are available untill reception errors out
+        break
+      }
+    } ;🔚∎🏁
+    (dbg<_d+1)?'':(dbgtxt:='🏁ih' dir ' pos isH=' isH ' isOut=' dbgOut ' ' format(" 🕐Δ{:.3f}",A_TickCount - 🕐k_now) ' ' A_ThisFunc ' ¦' id_thread '¦', OutputDebug(dbgtxt))
+  }
+  cbK↑(token,  ih,vk,sc) {
+    static _d := 1, isUp := true, dir := (isUp?'↑':'↓')
+    🕐k_pre := 🕐k_now
+    🕐k_now := A_TickCount
+    if (dbg>=_d) {
+      dbgtxt := ''
+      vk_hex := Format("vk{:x}",vk)
+      key_name := GetKeyName(Format("vk{:x}",vk)) ; bugs with layouts, not english even if english is active
+      dbgtxt .= "ih" dir (isSet(key_name)?key_name:'') "      🢥🄺: vk=" vk "¦" vk_hex " sc=" sc ' l' A_SendLevel " ¦" id_thread "¦"
+      OutputDebug(dbgtxt)
+    }
+    isH := fnKanata_in_ev(vk,sc,isUp)
+    dbgOut := ''
+    for i in [4,4,4,5,5,5] { ; poll a key out channel@kanata) a few times to see if there are key events
+      sleep(i)
+      isOut := K_output_ev_check(), dbgOut.=isOut
+      if (isOut < 0) { ; get as many keys as are available until reception errors out
+        break
+      }
+    }
+    (dbg<_d+1)?'':(dbgtxt:='🏁ih' dir ' pos isH=' isH ' isOut=' dbgOut ' ' format(" 🕐Δ{:.3f}",A_TickCount - 🕐k_now) ' ' A_ThisFunc ' ¦' id_thread '¦', OutputDebug(dbgtxt))
+  }
+  ; set up machinery for AHK to receive data from kanata
+  cbKanataOut(kvk,ksc,up) {
+    ; static K	:= keyConstant, vk:=K._map, vkr:=K._mapr, vkl:=K._maplng, vkrl:=K._maprlng, vk→en:=vkrl['en'], sc:=K._mapsc  ; various key name constants, gets vk code to avoid issues with another layout
+    static _d := 1, lvl_to := 0
+    🕐1 := preciseTΔ()
+    vk_hex := Format("vk{:x}",kvk)
+    if not C↑ && up && (kvk=Cvk_d) {
+      C↑ := true , (dbg<_d)?'':(OutputDebug('trigger key released'))
+    }
+    if cleanup && C↑ && up && (kvk=Cvk_d) { ; todo: check for physical position before excluding?
+      (dbg<_d)?'':(OutputDebug("dupe release of trigger key on kanata's cleanup, ignore"))
+      C↑ := false
+      return
+    }
+    ; Critical ; todo: needed??? avoid being interrupted by itself (or any other thread)
+    if (dbg>=_d) {
+      dbgtxt := ''
+      dir := (up?'↑':'↓')
+      key_name := GetKeyName(vk_hex) ; bugs with layouts, not english even if english is active
+      ; key_name := vk→en.Get(vk_hex,key_name_cur)
+      hooks := "hooks#: " gethookcount()
+      dbgtxt .= dir
+    }
+    if isSet(vk_hex) {
+      (dbg<_d)?'':(dbgtxt .= key_name "       🄷🢦 : vk=" kvk '¦' vk_hex ' @l' A_SendLevel ' → ' lvl_to ' ' hooks ' ¦' id_thread '¦ ' A_ThisFunc, OutputDebug(dbgtxt))
+      if up {
+        ; SendEvent('{' vk_hex ' up}')
+        SendInput('{' vk_hex ' up}')
+      } else {
+        ; SendEvent('{' vk_hex ' down}')
+        SendInput('{' vk_hex ' down}')
+      }
+    } else {
+      (dbg<_d)?'':(dbgtxt .= '✗name' "       🄷🢦 : vk=" kvk '¦' vk_hex ' @l' A_SendLevel ' → ' lvl_to ' ' hooks ' ¦' id_thread '¦ ' A_ThisFunc, OutputDebug(dbgtxt))
+    }
+    🕐2 := preciseTΔ(), 🕐Δ := 🕐2-🕐1
+    if 🕐Δ > 0.5 {
+      (dbg<_d+1)?'':(OutputDebug('🐢🏁 ' format(" 🕐Δ{:.3f}",🕐Δ) ' ¦' id_thread '¦ ' A_ThisFunc))
+    } else {
+      (dbg<_d+1)?'':(OutputDebug('🐇🏁 ' format(" 🕐Δ{:.3f}",🕐Δ) ' ¦' id_thread '¦ ' A_ThisFunc))
+    }
+    return 1
+  }
+  ; CallbackFree(cbKanataOut)
+
+  if (Cvk_d) { ; modtap; send the activating hotkey to Kanata so it can take it into acount
+    cbK↓(token1,ih0,Cvk_d,Csc_d)
+  }
+  ih.Start()		;
+  ih.Wait() 		; Waits until the Input is terminated (InProgress is false)
+  if (ih.EndReason  = "Timeout") { ; cleanup kanata's state
+    ; key_name := GetKeyName(Format("vk{:x}",last↓[1]))
+    OutputDebug('—`n`n——————————————— Timeout')
+    🕐k_now := A_TickCount, 🕐Δ := 🕐k_now - 🕐k_pre
+    cleanup := true
+    res := fnKanata_reset(🕐Δ) ; reset kanata's state, progressing time to catch up, release held keys (even those physically held since reset is reset, so from kanata's perspective they should be released)
+    cleanup := false
+    dbgtxt := ''
+    dbgtxt .= 'ih¦' 🕐Δ '🕐Δ timeout A_TimeSinceThisHotkey ' A_TimeSinceThisHotkey
+    dbgOut := ''
+    loop 10 { ; get the remaining out keys from kanata
+      isOut := K_output_ev_check(), dbgOut.=isOut
+      if (isOut < 0) {
+        break
+      }
+    }
+    OutputDebug(dbgtxt '`n`n——————————————— isOut=' dbgOut ' ')
+  }
+
+  ; DllCall("FreeLibrary", "Ptr",hModule)  ; to conserve memory, the DLL may be unloaded after using it
+  hModule:=0
+}
+
+gethookcount() {
+  if        (A_KeybdHookInstalled = 0) {
+    return "_¦_"
+  } else if (A_KeybdHookInstalled = 3) {
+    return "✓¦✓"
+  } else if (A_KeybdHookInstalled = 2) {
+    return "_¦✓"
+  } else if (A_KeybdHookInstalled = 1) {
+    return "✓¦_"
+  } else {
+    return "?"
+  }
+}
+
+preciseTΔ(n:=3) {
+  static start := nativeFunc.GetSystemTimePreciseAsFileTime()
+  t := round(     nativeFunc.GetSystemTimePreciseAsFileTime() - start,n)
+  return t
+}
+class nativeFunc {
+  static GetSystemTimePreciseAsFileTime() {
+    /* learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime
+    retrieves the current system date and time with the highest possible level of precision (<1us)
+    FILETIME structure contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC)
+    100 ns  ->  0.1 µs  ->  0.001 ms  ->  0.00001 s
+    1     sec  ->  1000 ms  ->  1000000 µs
+    0.1   sec  ->   100 ms  ->   100000 µs
+    0.001 sec  ->    10 ms  ->    10000 µs
+    */
+    static interval2sec := (10 * 1000 * 1000) ; 100ns * 10 → µs * 1000 → ms * 1000 → sec
+    DllCall("GetSystemTimePreciseAsFileTime", "int64*",&ft:=0)
+    return ft / interval2sec
+  }
+}
diff --git a/docs/switch-design b/docs/switch-design
new file mode 100644
index 000000000..1d0d94e12
--- /dev/null
+++ b/docs/switch-design
@@ -0,0 +1,198 @@
+# Preface:
+
+This document is a scratch space for the design of the switch action.
+It may be out of date and is kept around for posterity.
+
+.syntax:
+----
+(switch
+  (or a b c) (cmd <cmd1>) break
+  (and a b (or c d)) (cmd <cmd2>) fallthrough
+  (and a b (or c d) (or e f)) fallthrough
+  ()
+)
+----
+
+
+.opcode format examples:
+----
+(or a b c)
+OR-4 a b c
+
+(and a b (or c d))
+AND-6 a b OR-6 c d
+
+(and a b (or c d) (or e f))
+AND-9 a b OR-6 c d OR-9 e f
+----
+
+.opcodes:
+----
+key: all values < 1024
+OR/AND: OP & 0xF000
+  OR : 0x1000
+  AND: 0x2000
+  length: OP & 0x0FFF
+----
+
+.Rough algorithm for opcodes:
+----
+value=true
+push first opcode
+WHILE stack is not empty
+  WHILE index <= ending_index
+    switch
+      opcode:
+        push, continue
+      key(OR):
+        value=true: skip to index, pop
+        value=false: continue
+      key(AND):
+        value=true: continue
+        value=false: skip to index, pop
+  pop
+  switch
+    current_value(OR):
+      value=true: skip to index, pop
+      value=false: continue
+    current_value(AND):
+      value=true: continue
+      value=false: skip to index, pop
+return value
+----
+
+.statestruct:
+----
+  value
+  current_index
+  current_end_index
+  current_op
+  stack (op, ending_index)
+----
+
+.rough sequence 1:
+----
+pressed:       y y      y y      y y
+opcodes: AND-9 a b OR-6 c d OR-9 e f
+
+index: 0
+  push: AND-9
+  stack: AND-9
+
+index: 1
+  val: true
+
+index: 2
+  val: true
+
+index: 3
+  push: OR-6
+  stack: AND-9 OR-6
+
+index: 4
+  val: true
+  skip to 6
+  pop
+  stack: AND-9
+
+index: 6
+  push: OR-9
+  stack: AND-9 OR-9
+
+index: 7
+  val: true
+  skip to 9
+  pop
+  stack: AND-9-true
+
+index 9:
+  pop
+  stack: empty
+  return val: true
+----
+
+.rough sequence 2:
+----
+pressed:       y y      n n      y y
+opcodes: AND-9 a b OR-6 c d OR-9 e f
+
+index: 0
+  push: AND-9
+  stack: AND-9
+
+index: 1
+  val: true
+
+index: 2
+  val: true
+
+index: 3
+  push: OR-6
+  stack: AND-9 OR-6
+  val: true
+
+index: 4
+  val: false
+
+index: 5
+  val: false
+
+index: 6
+  val: false
+  pop
+  stack: AND-9
+  skip to 9
+  pop
+  stack: empty
+  return val: false
+----
+
+.rough sequence 3:
+----
+pressed:       n y      n n      y y
+opcodes: AND-9 a b OR-6 c d OR-9 e f
+
+index: 0
+  push: AND-9
+  stack: AND-9
+
+index: 1
+  val: false
+  skip to 9
+  pop
+  stack: empty
+  return val: false
+----
+
+
+.pseudo code again:
+----
+let mut value = true
+let mut current_index = 1
+let mut current_end_index = first_opcode - end_index
+let mut current_op = OR
+while current_index < slice_length {
+  if index >= current_end_index:
+    if stack is empty:
+      break
+    else:
+      pop stack to current_op and current_end_index
+      switch
+        current_value(OR):
+          value=true: skip to current_end_index; continue
+        current_value(AND):
+          value=false: skip to current_end_index; continue
+  switch
+    opcode:
+      push (current_end_index,current_op)
+      update (current_end_index,current_op) with opcode
+    key(OR):
+      value=true: skip to current_end_index; continue
+      value=false
+    key(AND):
+      value=true
+      value=false: skip to current_end_index; continue
+  current_index++;
+}
+return value
+----
diff --git a/docs/win-tray/win-tray-layer-change.gif b/docs/win-tray/win-tray-layer-change.gif
new file mode 100644
index 000000000..62b1f4a5d
Binary files /dev/null and b/docs/win-tray/win-tray-layer-change.gif differ
diff --git a/docs/win-tray/win-tray-screen.png b/docs/win-tray/win-tray-screen.png
new file mode 100644
index 000000000..fe7c5aa67
Binary files /dev/null and b/docs/win-tray/win-tray-screen.png differ
diff --git a/example_tcp_client/Cargo.lock b/example_tcp_client/Cargo.lock
deleted file mode 100644
index e327c9cbf..000000000
--- a/example_tcp_client/Cargo.lock
+++ /dev/null
@@ -1,415 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-version = 3
-
-[[package]]
-name = "anyhow"
-version = "1.0.59"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c91f1f46651137be86f3a2b9a8359f9ab421d04d941c62b5982e1ca21113adf9"
-
-[[package]]
-name = "atty"
-version = "0.2.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8"
-dependencies = [
- "hermit-abi",
- "libc",
- "winapi",
-]
-
-[[package]]
-name = "autocfg"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa"
-
-[[package]]
-name = "bitflags"
-version = "1.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
-
-[[package]]
-name = "bumpalo"
-version = "3.12.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d261e256854913907f67ed06efbc3338dfe6179796deefc1ff763fc1aee5535"
-
-[[package]]
-name = "cfg-if"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
-
-[[package]]
-name = "clap"
-version = "3.2.16"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a3dbbb6653e7c55cc8595ad3e1f7be8f32aba4eb7ff7f0fd1163d4f3d137c0a9"
-dependencies = [
- "atty",
- "bitflags",
- "clap_derive",
- "clap_lex",
- "indexmap",
- "once_cell",
- "strsim",
- "termcolor",
- "textwrap",
-]
-
-[[package]]
-name = "clap_derive"
-version = "3.2.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ba52acd3b0a5c33aeada5cdaa3267cdc7c594a98731d4268cdc1532f4264cb4"
-dependencies = [
- "heck",
- "proc-macro-error",
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "clap_lex"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2850f2f5a82cbf437dd5af4d49848fbdfc27c157c3d010345776f952765261c5"
-dependencies = [
- "os_str_bytes",
-]
-
-[[package]]
-name = "hashbrown"
-version = "0.12.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
-
-[[package]]
-name = "heck"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2540771e65fc8cb83cd6e8a237f70c319bd5c29f78ed1084ba5d50eeac86f7f9"
-
-[[package]]
-name = "hermit-abi"
-version = "0.1.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33"
-dependencies = [
- "libc",
-]
-
-[[package]]
-name = "indexmap"
-version = "1.9.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "10a35a97730320ffe8e2d410b5d3b69279b98d2c14bdb8b70ea89ecf7888d41e"
-dependencies = [
- "autocfg",
- "hashbrown",
-]
-
-[[package]]
-name = "itoa"
-version = "1.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6c8af84674fe1f223a982c933a0ee1086ac4d4052aa0fb8060c12c6ad838e754"
-
-[[package]]
-name = "js-sys"
-version = "0.3.59"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "258451ab10b34f8af53416d1fdab72c22e805f0c92a1136d59470ec0b11138b2"
-dependencies = [
- "wasm-bindgen",
-]
-
-[[package]]
-name = "kanata_example_tcp_client"
-version = "1.0.0"
-dependencies = [
- "anyhow",
- "clap",
- "log",
- "serde",
- "serde_json",
- "simplelog",
-]
-
-[[package]]
-name = "libc"
-version = "0.2.127"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "505e71a4706fa491e9b1b55f51b95d4037d0821ee40131190475f692b35b009b"
-
-[[package]]
-name = "log"
-version = "0.4.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abb12e687cfb44aa40f41fc3978ef76448f9b6038cad6aef4259d3c095a2382e"
-dependencies = [
- "cfg-if",
-]
-
-[[package]]
-name = "num_threads"
-version = "0.1.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2819ce041d2ee131036f4fc9d6ae7ae125a3a40e97ba64d04fe799ad9dabbb44"
-dependencies = [
- "libc",
-]
-
-[[package]]
-name = "once_cell"
-version = "1.13.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "18a6dbe30758c9f83eb00cbea4ac95966305f5a7772f3f42ebfc7fc7eddbd8e1"
-
-[[package]]
-name = "os_str_bytes"
-version = "6.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "648001efe5d5c0102d8cea768e348da85d90af8ba91f0bea908f157951493cd4"
-
-[[package]]
-name = "proc-macro-error"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c"
-dependencies = [
- "proc-macro-error-attr",
- "proc-macro2",
- "quote",
- "syn",
- "version_check",
-]
-
-[[package]]
-name = "proc-macro-error-attr"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869"
-dependencies = [
- "proc-macro2",
- "quote",
- "version_check",
-]
-
-[[package]]
-name = "proc-macro2"
-version = "1.0.43"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0a2ca2c61bc9f3d74d2886294ab7b9853abd9c1ad903a3ac7815c58989bb7bab"
-dependencies = [
- "unicode-ident",
-]
-
-[[package]]
-name = "quote"
-version = "1.0.21"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bbe448f377a7d6961e30f5955f9b8d106c3f5e449d493ee1b125c1d43c2b5179"
-dependencies = [
- "proc-macro2",
-]
-
-[[package]]
-name = "ryu"
-version = "1.0.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4501abdff3ae82a1c1b477a17252eb69cee9e66eb915c1abaa4f44d873df9f09"
-
-[[package]]
-name = "serde"
-version = "1.0.142"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e590c437916fb6b221e1d00df6e3294f3fccd70ca7e92541c475d6ed6ef5fee2"
-dependencies = [
- "serde_derive",
-]
-
-[[package]]
-name = "serde_derive"
-version = "1.0.142"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34b5b8d809babe02f538c2cfec6f2c1ed10804c0e5a6a041a049a4f5588ccc2e"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "serde_json"
-version = "1.0.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "38dd04e3c8279e75b31ef29dbdceebfe5ad89f4d0937213c53f7d49d01b3d5a7"
-dependencies = [
- "itoa",
- "ryu",
- "serde",
-]
-
-[[package]]
-name = "simplelog"
-version = "0.12.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48dfff04aade74dd495b007c831cd6f4e0cee19c344dd9dc0884c0289b70a786"
-dependencies = [
- "log",
- "termcolor",
- "time",
-]
-
-[[package]]
-name = "strsim"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
-
-[[package]]
-name = "syn"
-version = "1.0.99"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "58dbef6ec655055e20b86b15a8cc6d439cca19b667537ac6a1369572d151ab13"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
-[[package]]
-name = "termcolor"
-version = "1.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bab24d30b911b2376f3a13cc2cd443142f0c81dda04c118693e35b3835757755"
-dependencies = [
- "winapi-util",
-]
-
-[[package]]
-name = "textwrap"
-version = "0.15.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1141d4d61095b28419e22cb0bbf02755f5e54e0526f97f1e3d1d160e60885fb"
-
-[[package]]
-name = "time"
-version = "0.3.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "74b7cc93fc23ba97fde84f7eea56c55d1ba183f495c6715defdfc7b9cb8c870f"
-dependencies = [
- "itoa",
- "js-sys",
- "libc",
- "num_threads",
- "time-macros",
-]
-
-[[package]]
-name = "time-macros"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42657b1a6f4d817cda8e7a0ace261fe0cc946cf3a80314390b22cc61ae080792"
-
-[[package]]
-name = "unicode-ident"
-version = "1.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4f5b37a154999a8f3f98cc23a628d850e154479cd94decf3414696e12e31aaf"
-
-[[package]]
-name = "version_check"
-version = "0.9.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49874b5167b65d7193b8aba1567f5c7d93d001cafc34600cee003eda787e483f"
-
-[[package]]
-name = "wasm-bindgen"
-version = "0.2.82"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc7652e3f6c4706c8d9cd54832c4a4ccb9b5336e2c3bd154d5cccfbf1c1f5f7d"
-dependencies = [
- "cfg-if",
- "wasm-bindgen-macro",
-]
-
-[[package]]
-name = "wasm-bindgen-backend"
-version = "0.2.82"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "662cd44805586bd52971b9586b1df85cdbbd9112e4ef4d8f41559c334dc6ac3f"
-dependencies = [
- "bumpalo",
- "log",
- "once_cell",
- "proc-macro2",
- "quote",
- "syn",
- "wasm-bindgen-shared",
-]
-
-[[package]]
-name = "wasm-bindgen-macro"
-version = "0.2.82"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b260f13d3012071dfb1512849c033b1925038373aea48ced3012c09df952c602"
-dependencies = [
- "quote",
- "wasm-bindgen-macro-support",
-]
-
-[[package]]
-name = "wasm-bindgen-macro-support"
-version = "0.2.82"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5be8e654bdd9b79216c2929ab90721aa82faf65c48cdf08bdc4e7f51357b80da"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
- "wasm-bindgen-backend",
- "wasm-bindgen-shared",
-]
-
-[[package]]
-name = "wasm-bindgen-shared"
-version = "0.2.82"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6598dd0bd3c7d51095ff6531a5b23e02acdc81804e30d8f07afb77b7215a140a"
-
-[[package]]
-name = "winapi"
-version = "0.3.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
-dependencies = [
- "winapi-i686-pc-windows-gnu",
- "winapi-x86_64-pc-windows-gnu",
-]
-
-[[package]]
-name = "winapi-i686-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
-
-[[package]]
-name = "winapi-util"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70ec6ce85bb158151cae5e5c87f95a8e97d2c0c4b001223f33a334e3ce5de178"
-dependencies = [
- "winapi",
-]
-
-[[package]]
-name = "winapi-x86_64-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
diff --git a/example_tcp_client/Cargo.toml b/example_tcp_client/Cargo.toml
index 47b75186d..e397a9b18 100644
--- a/example_tcp_client/Cargo.toml
+++ b/example_tcp_client/Cargo.toml
@@ -1,15 +1,15 @@
 [package]
 name = "kanata_example_tcp_client"
-Description = "Example kanata TCP client"
-version = "1.0.0"
+description = "Example kanata TCP client"
+version = "1.1.0"
 edition = "2021"
 license = "LGPL-3.0"
 authors = ["jtroo <j.andreitabs@gmail.com>"]
 
 [dependencies]
 anyhow = "1"
-clap = { version = "3", features = [ "derive" ] }
+clap = { version = "4", features = [ "derive" ] }
+kanata-tcp-protocol = { path = "../tcp_protocol" }
 log = "0.4.8"
 simplelog = "0.12"
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
+serde_json = "1"
\ No newline at end of file
diff --git a/example_tcp_client/src/main.rs b/example_tcp_client/src/main.rs
index 0090d24a8..26bbf7b01 100644
--- a/example_tcp_client/src/main.rs
+++ b/example_tcp_client/src/main.rs
@@ -1,10 +1,9 @@
 use clap::Parser;
-use serde::{Deserialize, Serialize};
+use kanata_tcp_protocol::*;
 use simplelog::*;
-
-use std::io::{stdin, Read, Write};
+use std::io::{BufRead, BufReader, Write, stdin};
 use std::net::{SocketAddr, TcpStream};
-use std::str::FromStr;
+use std::process::exit;
 use std::time::Duration;
 
 #[derive(Parser, Debug)]
@@ -12,7 +11,7 @@ use std::time::Duration;
 struct Args {
     /// Port that kanata's TCP server is listening on
     #[clap(short, long)]
-    port: u16,
+    port: Option<u16>,
 
     /// Enable debug logging
     #[clap(short, long)]
@@ -26,21 +25,94 @@ struct Args {
 fn main() {
     let args = Args::parse();
     init_logger(&args);
+    print_usage();
+
+    let port = match args.port {
+        Some(p) => p,
+        None => {
+            log::error!("no port provided via the -p|--port flag; exiting");
+            exit(1);
+        }
+    };
     log::info!("attempting to connect to kanata");
     let kanata_conn = TcpStream::connect_timeout(
-        &SocketAddr::from(([127, 0, 0, 1], args.port)),
+        &SocketAddr::from(([127, 0, 0, 1], port)),
         Duration::from_secs(5),
     )
     .expect("connect to kanata");
     log::info!("successfully connected");
-    let writer_stream = kanata_conn
-        .try_clone()
-        .expect("clone writer");
+    let writer_stream = kanata_conn.try_clone().expect("clone writer");
     let reader_stream = kanata_conn;
     std::thread::spawn(move || write_to_kanata(writer_stream));
     read_from_kanata(reader_stream);
 }
 
+fn print_usage() {
+    log::info!(
+        "\n\
+    You can also use any other software to connect to kanata over TCP.\n\
+    The protocol is plaintext JSON with newline terminated messages.
+\n\
+    Layer change notifications from kanata look like:\n\
+    {}
+\n\
+    Requests to change kanata's layer look like:\n\
+    {}
+\n\
+    Configuration reload commands:\n\
+    - reload: {}\n\
+    - reload next: {}\n\
+    - reload previous: {}\n\
+    - reload specific index: {}\n\
+    - reload specific file: {}
+\n\
+    Server responses for commands look like:\n\
+    - Success: {}\n\
+    - Error: {}
+    ",
+        serde_json::to_string(&ServerMessage::LayerChange {
+            new: "newly-changed-to-layer".into()
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::ChangeLayer {
+            new: "requested-layer".into()
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::Reload {
+            wait: None,
+            timeout_ms: None
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::ReloadNext {
+            wait: None,
+            timeout_ms: None
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::ReloadPrev {
+            wait: None,
+            timeout_ms: None
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::ReloadNum {
+            index: 1,
+            wait: None,
+            timeout_ms: None
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ClientMessage::ReloadFile {
+            path: "/path/to/config.kbd".to_string(),
+            wait: None,
+            timeout_ms: None,
+        })
+        .expect("deserializable"),
+        serde_json::to_string(&ServerResponse::Ok).expect("deserializable"),
+        serde_json::to_string(&ServerResponse::Error {
+            msg: "Invalid config index: 5. Only 2 configs are available (0-1).".to_string()
+        })
+        .expect("deserializable"),
+    )
+}
+
 fn init_logger(args: &Args) {
     let log_lvl = match (args.debug, args.trace) {
         (_, true) => LevelFilter::Trace,
@@ -49,7 +121,7 @@ fn init_logger(args: &Args) {
     };
     let mut log_cfg = ConfigBuilder::new();
     if let Err(e) = log_cfg.set_time_offset_to_local() {
-        eprintln!("WARNING: could not set log TZ to local: {:?}", e);
+        eprintln!("WARNING: could not set log TZ to local: {e:?}");
     };
     CombinedLogger::init(vec![TermLogger::new(
         log_lvl,
@@ -64,54 +136,124 @@ fn init_logger(args: &Args) {
     );
 }
 
-#[derive(Debug, Serialize, Deserialize)]
-pub enum ServerMessage {
-    LayerChange { new: String },
-}
-
-#[derive(Debug, Serialize, Deserialize)]
-pub enum ClientMessage {
-    ChangeLayer { new: String },
-}
-
-impl FromStr for ServerMessage {
-    type Err = serde_json::Error;
-
-    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
-        serde_json::from_str(s)
-    }
-}
-
 fn write_to_kanata(mut s: TcpStream) {
     log::info!("writer starting");
-    log::info!("writer: type layer name then press enter to send a change layer request to kanata");
-    let mut layer = String::new();
+    log::info!("writer: enter commands to send to kanata:");
+    log::info!("  - layer name: change to that layer");
+    log::info!("  - fk:KEYNAME: tap fake key");
+    log::info!("  - reload: reload current config");
+    log::info!("  - reload-next: reload next config");
+    log::info!("  - reload-prev: reload previous config");
+    log::info!("  - reload-num:N: reload config at index N");
+    log::info!("  - reload-file:PATH: reload config file at PATH");
+    let mut input = String::new();
     loop {
-        stdin().read_line(&mut layer).expect("stdin is readable");
-        let new = layer.trim_end().to_owned();
-        log::info!("writer: telling kanata to change layer to \"{new}\"");
-        let msg =
-            serde_json::to_string(&ClientMessage::ChangeLayer { new }).expect("deserializable");
-        let expected_wsz = msg.len();
-        let wsz = s.write(msg.as_bytes()).expect("stream writable");
-        if wsz != expected_wsz {
-            panic!("failed to write entire message {wsz} {expected_wsz}");
-        }
-        layer.clear();
+        stdin().read_line(&mut input).expect("stdin is readable");
+        let command = input.trim_end().to_owned();
+
+        let msg = if command.starts_with("fk:") {
+            let fkname = command.trim_start_matches("fk:").into();
+            log::info!("writer: telling kanata to tap fake key \"{fkname}\"");
+            serde_json::to_string(&ClientMessage::ActOnFakeKey {
+                name: fkname,
+                action: FakeKeyActionMessage::Tap,
+            })
+            .expect("deserializable")
+        } else if command == "reload" {
+            log::info!("writer: telling kanata to reload current config");
+            serde_json::to_string(&ClientMessage::Reload {
+                wait: None,
+                timeout_ms: None,
+            })
+            .expect("deserializable")
+        } else if command == "reload-next" {
+            log::info!("writer: telling kanata to reload next config");
+            serde_json::to_string(&ClientMessage::ReloadNext {
+                wait: None,
+                timeout_ms: None,
+            })
+            .expect("deserializable")
+        } else if command == "reload-prev" {
+            log::info!("writer: telling kanata to reload previous config");
+            serde_json::to_string(&ClientMessage::ReloadPrev {
+                wait: None,
+                timeout_ms: None,
+            })
+            .expect("deserializable")
+        } else if command.starts_with("reload-num:") {
+            let index_str = command.trim_start_matches("reload-num:");
+            match index_str.parse::<usize>() {
+                Ok(index) => {
+                    log::info!("writer: telling kanata to reload config at index {index}");
+                    serde_json::to_string(&ClientMessage::ReloadNum {
+                        index,
+                        wait: None,
+                        timeout_ms: None,
+                    })
+                    .expect("deserializable")
+                }
+                Err(_) => {
+                    log::error!("Invalid number format for reload-num: {index_str}");
+                    input.clear();
+                    continue;
+                }
+            }
+        } else if command.starts_with("reload-file:") {
+            let path = command.trim_start_matches("reload-file:").to_string();
+            log::info!("writer: telling kanata to reload config file \"{path}\"");
+            serde_json::to_string(&ClientMessage::ReloadFile {
+                path,
+                wait: None,
+                timeout_ms: None,
+            })
+            .expect("deserializable")
+        } else {
+            log::info!("writer: telling kanata to change layer to \"{command}\"");
+            serde_json::to_string(&ClientMessage::ChangeLayer { new: command })
+                .expect("deserializable")
+        };
+
+        s.write_all(msg.as_bytes()).expect("stream writable");
+        input.clear();
     }
 }
 
-fn read_from_kanata(mut s: TcpStream) {
+fn read_from_kanata(s: TcpStream) {
     log::info!("reader starting");
-    let mut buf = vec![0; 256];
+    let mut reader = BufReader::new(s);
+    let mut msg = String::new();
     loop {
-        let sz = s.read(&mut buf).expect("stream readable");
-        let msg = String::from_utf8_lossy(&buf[..sz]);
-        let parsed_msg = ServerMessage::from_str(&msg).expect("kanata sends valid message");
+        msg.clear();
+        reader.read_line(&mut msg).expect("stream readable");
+
+        // Try to parse as ServerResponse first (for command responses)
+        if let Ok(response) = serde_json::from_str::<ServerResponse>(&msg) {
+            match response {
+                ServerResponse::Ok => {
+                    log::info!("✓ Command executed successfully");
+                }
+                ServerResponse::Error { msg } => {
+                    log::error!("✗ Command failed: {}", msg);
+                }
+            }
+            continue;
+        }
+
+        // Fall back to parsing as ServerMessage (for notifications)
+        let parsed_msg: ServerMessage = match serde_json::from_str(&msg) {
+            Ok(msg) => msg,
+            Err(e) => {
+                log::warn!("could not parse server message {msg}: {e:?}");
+                std::process::exit(1);
+            }
+        };
         match parsed_msg {
             ServerMessage::LayerChange { new } => {
                 log::info!("reader: kanata changed layers to \"{new}\"");
             }
+            msg => {
+                log::info!("got msg: {msg:?}");
+            }
         }
     }
 }
diff --git a/interception/Cargo.toml b/interception/Cargo.toml
index 7f5f5acfe..fafd9508b 100644
--- a/interception/Cargo.toml
+++ b/interception/Cargo.toml
@@ -1,7 +1,10 @@
+[workspace]
+members = ["."]
+
 [package]
 name = "kanata-interception"
 description = "Safe wrapper for Interception. Forked for use with kanata."
-version = "0.2.0"
+version = "0.3.0"
 authors = ["Joe Kaushal <joe.kaushal@gmail.com>"]
 edition = "2018"
 repository = "https://github.com/jtroo/kanata"
diff --git a/interception/src/scancode.rs b/interception/src/scancode.rs
index bba61e3f3..5f39e37d7 100644
--- a/interception/src/scancode.rs
+++ b/interception/src/scancode.rs
@@ -34,13 +34,10 @@ pub enum ScanCode {
     I = 0x17,
     O = 0x18,
     P = 0x19,
-
     LeftBracket = 0x1A,
     RightBracket = 0x1B,
     Enter = 0x1C,
-
     LeftControl = 0x1D,
-
     A = 0x1E,
     S = 0x1F,
     D = 0x20,
@@ -50,13 +47,11 @@ pub enum ScanCode {
     J = 0x24,
     K = 0x25,
     L = 0x26,
-
     SemiColon = 0x27,
     Apostrophe = 0x28,
     Grave = 0x29,
     LeftShift = 0x2A,
     BackSlash = 0x2B,
-
     Z = 0x2C,
     X = 0x2D,
     C = 0x2E,
@@ -64,7 +59,6 @@ pub enum ScanCode {
     B = 0x30,
     N = 0x31,
     M = 0x32,
-
     Comma = 0x33,
     Period = 0x34,
     Slash = 0x35,
@@ -73,7 +67,6 @@ pub enum ScanCode {
     LeftAlt = 0x38,
     Space = 0x39,
     CapsLock = 0x3A,
-
     F1 = 0x3B,
     F2 = 0x3C,
     F3 = 0x3D,
@@ -84,46 +77,37 @@ pub enum ScanCode {
     F8 = 0x42,
     F9 = 0x43,
     F10 = 0x44,
-
     NumLock = 0x45,
     ScrollLock = 0x46,
-
     Numpad7 = 0x47,
     Numpad8 = 0x48,
     Numpad9 = 0x49,
-
     NumpadMinus = 0x4A,
-
     Numpad4 = 0x4B,
     Numpad5 = 0x4C,
     Numpad6 = 0x4D,
-
     NumpadPlus = 0x4E,
-
     Numpad1 = 0x4F,
     Numpad2 = 0x50,
     Numpad3 = 0x51,
     Numpad0 = 0x52,
-
     NumpadPeriod = 0x53,
-    AltPrintScreen = 0x54, /* Alt + print screen. */
-    Int1 = 0x56,           /* Key between the left shift and Z. */
-
+    AltPrintScreen = 0x54,
+    SC_55 = 0x55,
+    Int1 = 0x56,
     F11 = 0x57,
     F12 = 0x58,
-
-    Oem1 = 0x5A, /* VK_OEM_WSCTRL */
-    Oem2 = 0x5B, /* VK_OEM_FINISH */
-    Oem3 = 0x5C, /* VK_OEM_JUMP */
-
+    SC_59 = 0x59,
+    Oem1 = 0x5A,
+    Oem2 = 0x5B,
+    Oem3 = 0x5C,
     EraseEOF = 0x5D,
-
-    Oem4 = 0x5E, /* VK_OEM_BACKTAB */
-    Oem5 = 0x5F, /* VK_OEM_AUTO */
-
+    Oem4 = 0x5E,
+    Oem5 = 0x5F,
+    SC_60 = 0x60,
+    SC_61 = 0x61,
     Zoom = 0x62,
     Help = 0x63,
-
     F13 = 0x64,
     F14 = 0x65,
     F15 = 0x66,
@@ -135,13 +119,149 @@ pub enum ScanCode {
     F21 = 0x6C,
     F22 = 0x6D,
     F23 = 0x6E,
-
-    Oem6 = 0x6F, /* VK_OEM_PA3 */
+    Oem6 = 0x6F,
     Katakana = 0x70,
-    Oem7 = 0x71, /* VK_OEM_RESET */
+    Oem7 = 0x71,
+    SC_72 = 0x72,
+    SC_73 = 0x73,
+    SC_74 = 0x74,
+    SC_75 = 0x75,
     F24 = 0x76,
-
     SBCSChar = 0x77,
+    SC_78 = 0x78,
     Convert = 0x79,
-    NonConvert = 0x7B, /* VK_OEM_PA1 */
+    SC_7A = 0x7A,
+    NonConvert = 0x7B,
+    SC_7C = 0x7C,
+    SC_7D = 0x7D,
+    SC_7E = 0x7E,
+    SC_7F = 0x7F,
+    SC_80 = 0x80,
+    SC_81 = 0x81,
+    SC_82 = 0x82,
+    SC_83 = 0x83,
+    SC_84 = 0x84,
+    SC_85 = 0x85,
+    SC_86 = 0x86,
+    SC_87 = 0x87,
+    SC_88 = 0x88,
+    SC_89 = 0x89,
+    SC_8A = 0x8A,
+    SC_8B = 0x8B,
+    SC_8C = 0x8C,
+    SC_8D = 0x8D,
+    SC_8E = 0x8E,
+    SC_8F = 0x8F,
+    SC_90 = 0x90,
+    SC_91 = 0x91,
+    SC_92 = 0x92,
+    SC_93 = 0x93,
+    SC_94 = 0x94,
+    SC_95 = 0x95,
+    SC_96 = 0x96,
+    SC_97 = 0x97,
+    SC_98 = 0x98,
+    SC_99 = 0x99,
+    SC_9A = 0x9A,
+    SC_9B = 0x9B,
+    SC_9C = 0x9C,
+    SC_9D = 0x9D,
+    SC_9E = 0x9E,
+    SC_9F = 0x9F,
+    SC_A0 = 0xA0,
+    SC_A1 = 0xA1,
+    SC_A2 = 0xA2,
+    SC_A3 = 0xA3,
+    SC_A4 = 0xA4,
+    SC_A5 = 0xA5,
+    SC_A6 = 0xA6,
+    SC_A7 = 0xA7,
+    SC_A8 = 0xA8,
+    SC_A9 = 0xA9,
+    SC_AA = 0xAA,
+    SC_AB = 0xAB,
+    SC_AC = 0xAC,
+    SC_AD = 0xAD,
+    SC_AE = 0xAE,
+    SC_AF = 0xAF,
+    SC_B0 = 0xB0,
+    SC_B1 = 0xB1,
+    SC_B2 = 0xB2,
+    SC_B3 = 0xB3,
+    SC_B4 = 0xB4,
+    SC_B5 = 0xB5,
+    SC_B6 = 0xB6,
+    SC_B7 = 0xB7,
+    SC_B8 = 0xB8,
+    SC_B9 = 0xB9,
+    SC_BA = 0xBA,
+    SC_BB = 0xBB,
+    SC_BC = 0xBC,
+    SC_BD = 0xBD,
+    SC_BE = 0xBE,
+    SC_BF = 0xBF,
+    SC_C0 = 0xC0,
+    SC_C1 = 0xC1,
+    SC_C2 = 0xC2,
+    SC_C3 = 0xC3,
+    SC_C4 = 0xC4,
+    SC_C5 = 0xC5,
+    SC_C6 = 0xC6,
+    SC_C7 = 0xC7,
+    SC_C8 = 0xC8,
+    SC_C9 = 0xC9,
+    SC_CA = 0xCA,
+    SC_CB = 0xCB,
+    SC_CC = 0xCC,
+    SC_CD = 0xCD,
+    SC_CE = 0xCE,
+    SC_CF = 0xCF,
+    SC_D0 = 0xD0,
+    SC_D1 = 0xD1,
+    SC_D2 = 0xD2,
+    SC_D3 = 0xD3,
+    SC_D4 = 0xD4,
+    SC_D5 = 0xD5,
+    SC_D6 = 0xD6,
+    SC_D7 = 0xD7,
+    SC_D8 = 0xD8,
+    SC_D9 = 0xD9,
+    SC_DA = 0xDA,
+    SC_DB = 0xDB,
+    SC_DC = 0xDC,
+    SC_DD = 0xDD,
+    SC_DE = 0xDE,
+    SC_DF = 0xDF,
+    SC_E0 = 0xE0,
+    SC_E1 = 0xE1,
+    SC_E2 = 0xE2,
+    SC_E3 = 0xE3,
+    SC_E4 = 0xE4,
+    SC_E5 = 0xE5,
+    SC_E6 = 0xE6,
+    SC_E7 = 0xE7,
+    SC_E8 = 0xE8,
+    SC_E9 = 0xE9,
+    SC_EA = 0xEA,
+    SC_EB = 0xEB,
+    SC_EC = 0xEC,
+    SC_ED = 0xED,
+    SC_EE = 0xEE,
+    SC_EF = 0xEF,
+    SC_F0 = 0xF0,
+    SC_F1 = 0xF1,
+    SC_F2 = 0xF2,
+    SC_F3 = 0xF3,
+    SC_F4 = 0xF4,
+    SC_F5 = 0xF5,
+    SC_F6 = 0xF6,
+    SC_F7 = 0xF7,
+    SC_F8 = 0xF8,
+    SC_F9 = 0xF9,
+    SC_FA = 0xFA,
+    SC_FB = 0xFB,
+    SC_FC = 0xFC,
+    SC_FD = 0xFD,
+    SC_FE = 0xFE,
+    SC_NonExtendMax = 0xFF,
 }
diff --git a/justfile b/justfile
index 4f79eb5b0..39d71cefb 100644
--- a/justfile
+++ b/justfile
@@ -1,18 +1,99 @@
+set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
+
 # Build the release binaries for Linux and put the binaries+cfg in the output directory
 build_release_linux output_dir:
-  cargo build --release && cp target/release/kanata "{{output_dir}}/kanata"
-  cargo build --release --features cmd && cp target/release/kanata "{{output_dir}}/kanata_cmd_allowed"
+  cargo build --release
+  cp target/release/kanata "{{output_dir}}/kanata"
+  strip "{{output_dir}}/kanata"
+  cargo build --release --features cmd
+  cp target/release/kanata "{{output_dir}}/kanata_cmd_allowed"
+  strip "{{output_dir}}/kanata_cmd_allowed"
   cp cfg_samples/kanata.kbd "{{output_dir}}"
 
-# Build the release binaries for Windows and put the binaries+cfg in the output directory. Run as follows: `just --shell powershell.exe --shell-arg -c build_release_windows <output_dir>`.
+# Build the release binaries for Windows and put the binaries+cfg in the output directory.
 build_release_windows output_dir:
-  cargo build --release; cp target/release/kanata.exe "{{output_dir}}\kanata.exe"
-  cargo build --release --features interception_driver; cp target/release/kanata.exe "{{output_dir}}\kanata_wintercept.exe"
-  cargo build --release --features cmd; cp target/release/kanata.exe "{{output_dir}}\kanata_cmd_allowed.exe"
-  cargo build --release --features cmd,interception_driver; cp target/release/kanata.exe "{{output_dir}}\kanata_wintercept_cmd_allowed.exe"
+  cargo build --release --no-default-features --features tcp_server,win_manifest; cp target/release/kanata.exe "{{output_dir}}\kanata_legacy_output.exe"
+  cargo build --release --features win_manifest,interception_driver; cp target/release/kanata.exe "{{output_dir}}\kanata_wintercept.exe"
+  cargo build --release --features win_manifest,win_sendinput_send_scancodes; cp target/release/kanata.exe "{{output_dir}}\kanata.exe"
+  cargo build --release --features win_manifest,win_sendinput_send_scancodes,win_llhook_read_scancodes; cp target/release/kanata.exe "{{output_dir}}\kanata_winIOv2.exe"
+  cargo build --release --features win_manifest,cmd,win_sendinput_send_scancodes; cp target/release/kanata.exe "{{output_dir}}\kanata_cmd_allowed.exe"
+  cargo build --release --features win_manifest,cmd,interception_driver; cp target/release/kanata.exe "{{output_dir}}\kanata_wintercept_cmd_allowed.exe"
+  cargo build --release --features passthru_ahk --package=simulated_passthru; cp target/release/kanata_passthru.dll "{{output_dir}}\kanata_passthru.dll"
+  cargo build --release --features win_manifest,gui    ; cp target/release/kanata.exe "{{output_dir}}\kanata_gui.exe"
+  cargo build --release --features win_manifest,gui,cmd; cp target/release/kanata.exe "{{output_dir}}\kanata_gui_cmd_allowed.exe"
+  cargo build --release --features win_manifest,gui,interception_driver    ; cp target/release/kanata.exe "{{output_dir}}\kanata_gui_wintercept.exe"
+  cargo build --release --features win_manifest,gui,cmd,interception_driver; cp target/release/kanata.exe "{{output_dir}}\kanata_gui_wintercept_cmd_allowed.exe"
   cp cfg_samples/kanata.kbd "{{output_dir}}"
 
 # Generate the sha256sums for all files in the output directory
 sha256sums output_dir:
   rm -f {{output_dir}}/sha256sums
   cd {{output_dir}}; sha256sum * > sha256sums
+
+test:
+  cargo test -p kanata -p kanata-parser -p kanata-keyberon -p kanata-wasm -p kanata-tcp-protocol -- --nocapture
+  cargo test --features=simulated_output sim_tests
+  cargo test --features=simulated_output -- must_be_single_threaded --ignored --test-threads=1
+  cargo clippy --all
+
+fmt:
+  cargo fmt --all
+
+[doc('Run fmt, check, and clippy')]
+check:
+  cargo fmt --all
+  cargo check
+  cargo clippy --all
+
+guic:
+  cargo check              --features=gui
+guif:
+  cargo fmt    --all
+  cargo clippy --all --fix --features=gui -- -D warnings
+
+ahkc:
+  cargo check              --features=passthru_ahk
+ahkf:
+  cargo fmt    --all
+  cargo clippy --all --fix --features=passthru_ahk -- -D warnings
+
+change_subcrate_versions version:
+  sed -i 's/^version = ".*"$/version = "{{version}}"/' parser/Cargo.toml tcp_protocol/Cargo.toml keyberon/Cargo.toml
+  sed -i 's/^\(#\? \?kanata-\(keyberon\|parser\|tcp-protocol\).*version\) = "[0-9.]*"/\1 = "{{version}}"/' Cargo.toml parser/Cargo.toml
+
+cov:
+  cargo llvm-cov clean --workspace
+  cargo llvm-cov --no-report --workspace --no-default-features
+  cargo llvm-cov --no-report --workspace
+  cargo llvm-cov --no-report --workspace --features=cmd,win_llhook_read_scancodes,win_sendinput_send_scancodes
+  cargo llvm-cov --no-report --workspace --features=cmd,interception_driver,win_sendinput_send_scancodes
+  cargo llvm-cov --no-report --features=simulated_output -- sim_tests
+  cargo llvm-cov report --html
+
+publish:
+  cd keyberon; cargo publish
+  cd tcp_protocol; cargo publish
+  cd parser; cargo publish
+  cargo publish
+
+# Include the trailing `\` or `/` in the output_dir parameter. The parameter should be an absolute path.
+cfg_to_html output_dir:
+  cd docs ; asciidoctor config.adoc
+  cd docs ; cp config.html "{{output_dir}}config.html"; rm config.html
+
+[doc('Deprecated. The wasm-pack project is no longer maintained; prefer wasm-build instead.
+Include the trailing `\` or `/` in the output_dir parameter. The parameter should be an absolute path.
+')]
+wasm_pack output_dir:
+  cd wasm; wasm-pack build --target web; cd pkg; cp kanata_wasm_bg.wasm "{{output_dir}}"; cp kanata_wasm.js "{{output_dir}}"
+
+[doc('Include the trailing `\` or `/` in the output_dir parameter. The parameter should be an absolute path.')]
+wasm-build output_dir:
+  cd wasm; echo "*" > pkg/.gitignore
+  cd wasm; cargo build --lib --release --target wasm32-unknown-unknown
+  cd wasm; wasm-bindgen ../target/wasm32-unknown-unknown/release/kanata_wasm.wasm --out-dir pkg --typescript --target web
+  wasm-opt wasm/pkg/kanata_wasm_bg.wasm -o wasm/pkg/kanata_wasm.wasm-opt.wasm -Oz
+  rm wasm/pkg/kanata_wasm_bg.wasm
+  mv wasm/pkg/kanata_wasm.wasm-opt.wasm wasm/pkg/kanata_wasm_bg.wasm
+  cp wasm/pkg/kanata_wasm_bg.wasm "{{output_dir}}"
+  cp wasm/pkg/kanata_wasm.js "{{output_dir}}"
diff --git a/key-sort-add/Cargo.toml b/key-sort-add/Cargo.toml
index 3d00b02cb..bb5f000ec 100644
--- a/key-sort-add/Cargo.toml
+++ b/key-sort-add/Cargo.toml
@@ -1,3 +1,6 @@
+[workspace]
+members = ["."]
+
 [package]
 name = "key-sort-add"
 version = "0.1.0"
diff --git a/key-sort-add/mapping.txt b/key-sort-add/mapping.txt
new file mode 100644
index 000000000..b563cf294
--- /dev/null
+++ b/key-sort-add/mapping.txt
@@ -0,0 +1,2173 @@
+=== kc to osc
+KeyCode::Escape => OsCode::KEY_ESC,
+KeyCode::Kb1 => OsCode::KEY_1,
+KeyCode::Kb2 => OsCode::KEY_2,
+KeyCode::Kb3 => OsCode::KEY_3,
+KeyCode::Kb4 => OsCode::KEY_4,
+KeyCode::Kb5 => OsCode::KEY_5,
+KeyCode::Kb6 => OsCode::KEY_6,
+KeyCode::Kb7 => OsCode::KEY_7,
+KeyCode::Kb8 => OsCode::KEY_8,
+KeyCode::Kb9 => OsCode::KEY_9,
+KeyCode::Kb0 => OsCode::KEY_0,
+KeyCode::Minus => OsCode::KEY_MINUS,
+KeyCode::Equal => OsCode::KEY_EQUAL,
+KeyCode::BSpace => OsCode::KEY_BACKSPACE,
+KeyCode::Tab => OsCode::KEY_TAB,
+KeyCode::Q => OsCode::KEY_Q,
+KeyCode::W => OsCode::KEY_W,
+KeyCode::E => OsCode::KEY_E,
+KeyCode::R => OsCode::KEY_R,
+KeyCode::T => OsCode::KEY_T,
+KeyCode::Y => OsCode::KEY_Y,
+KeyCode::U => OsCode::KEY_U,
+KeyCode::I => OsCode::KEY_I,
+KeyCode::O => OsCode::KEY_O,
+KeyCode::P => OsCode::KEY_P,
+KeyCode::LBracket => OsCode::KEY_LEFTBRACE,
+KeyCode::RBracket => OsCode::KEY_RIGHTBRACE,
+KeyCode::Enter => OsCode::KEY_ENTER,
+KeyCode::LCtrl => OsCode::KEY_LEFTCTRL,
+KeyCode::A => OsCode::KEY_A,
+KeyCode::S => OsCode::KEY_S,
+KeyCode::D => OsCode::KEY_D,
+KeyCode::F => OsCode::KEY_F,
+KeyCode::G => OsCode::KEY_G,
+KeyCode::H => OsCode::KEY_H,
+KeyCode::J => OsCode::KEY_J,
+KeyCode::K => OsCode::KEY_K,
+KeyCode::L => OsCode::KEY_L,
+KeyCode::SColon => OsCode::KEY_SEMICOLON,
+KeyCode::Quote => OsCode::KEY_APOSTROPHE,
+KeyCode::Grave => OsCode::KEY_GRAVE,
+KeyCode::LShift => OsCode::KEY_LEFTSHIFT,
+KeyCode::Bslash => OsCode::KEY_BACKSLASH,
+KeyCode::Z => OsCode::KEY_Z,
+KeyCode::X => OsCode::KEY_X,
+KeyCode::C => OsCode::KEY_C,
+KeyCode::V => OsCode::KEY_V,
+KeyCode::B => OsCode::KEY_B,
+KeyCode::N => OsCode::KEY_N,
+KeyCode::M => OsCode::KEY_M,
+KeyCode::Comma => OsCode::KEY_COMMA,
+KeyCode::Dot => OsCode::KEY_DOT,
+KeyCode::Slash => OsCode::KEY_SLASH,
+KeyCode::RShift => OsCode::KEY_RIGHTSHIFT,
+KeyCode::KpAsterisk => OsCode::KEY_KPASTERISK,
+KeyCode::LAlt => OsCode::KEY_LEFTALT,
+KeyCode::Space => OsCode::KEY_SPACE,
+KeyCode::CapsLock => OsCode::KEY_CAPSLOCK,
+KeyCode::F1 => OsCode::KEY_F1,
+KeyCode::F2 => OsCode::KEY_F2,
+KeyCode::F3 => OsCode::KEY_F3,
+KeyCode::F4 => OsCode::KEY_F4,
+KeyCode::F5 => OsCode::KEY_F5,
+KeyCode::F6 => OsCode::KEY_F6,
+KeyCode::F7 => OsCode::KEY_F7,
+KeyCode::F8 => OsCode::KEY_F8,
+KeyCode::F9 => OsCode::KEY_F9,
+KeyCode::F10 => OsCode::KEY_F10,
+KeyCode::NumLock => OsCode::KEY_NUMLOCK,
+KeyCode::Clear => OsCode::KEY_CLEAR,
+KeyCode::ScrollLock => OsCode::KEY_SCROLLLOCK,
+KeyCode::Kp7 => OsCode::KEY_KP7,
+KeyCode::Kp8 => OsCode::KEY_KP8,
+KeyCode::Kp9 => OsCode::KEY_KP9,
+KeyCode::KpMinus => OsCode::KEY_KPMINUS,
+KeyCode::Kp4 => OsCode::KEY_KP4,
+KeyCode::Kp5 => OsCode::KEY_KP5,
+KeyCode::Kp6 => OsCode::KEY_KP6,
+KeyCode::KpPlus => OsCode::KEY_KPPLUS,
+KeyCode::Kp1 => OsCode::KEY_KP1,
+KeyCode::Kp2 => OsCode::KEY_KP2,
+KeyCode::Kp3 => OsCode::KEY_KP3,
+KeyCode::Kp0 => OsCode::KEY_KP0,
+KeyCode::KpDot => OsCode::KEY_KPDOT,
+KeyCode::F11 => OsCode::KEY_F11,
+KeyCode::F12 => OsCode::KEY_F12,
+KeyCode::KpEnter => OsCode::KEY_KPENTER,
+KeyCode::RCtrl => OsCode::KEY_RIGHTCTRL,
+KeyCode::KpSlash => OsCode::KEY_KPSLASH,
+KeyCode::SysReq => OsCode::KEY_SYSRQ,
+KeyCode::RAlt => OsCode::KEY_RIGHTALT,
+KeyCode::Home => OsCode::KEY_HOME,
+KeyCode::Up => OsCode::KEY_UP,
+KeyCode::PgUp => OsCode::KEY_PAGEUP,
+KeyCode::Left => OsCode::KEY_LEFT,
+KeyCode::Right => OsCode::KEY_RIGHT,
+KeyCode::End => OsCode::KEY_END,
+KeyCode::Down => OsCode::KEY_DOWN,
+KeyCode::PgDown => OsCode::KEY_PAGEDOWN,
+KeyCode::Insert => OsCode::KEY_INSERT,
+KeyCode::Delete => OsCode::KEY_DELETE,
+KeyCode::Mute => OsCode::KEY_MUTE,
+KeyCode::VolDown => OsCode::KEY_VOLUMEDOWN,
+KeyCode::VolUp => OsCode::KEY_VOLUMEUP,
+KeyCode::Power => OsCode::KEY_POWER,
+KeyCode::KpEqual => OsCode::KEY_KPEQUAL,
+KeyCode::Pause => OsCode::KEY_PAUSE,
+KeyCode::KpComma => OsCode::KEY_KPCOMMA,
+KeyCode::LGui => OsCode::KEY_LEFTMETA,
+KeyCode::RGui => OsCode::KEY_RIGHTMETA,
+KeyCode::Stop => OsCode::KEY_STOP,
+KeyCode::Again => OsCode::KEY_AGAIN,
+KeyCode::Undo => OsCode::KEY_UNDO,
+KeyCode::Copy => OsCode::KEY_COPY,
+KeyCode::Paste => OsCode::KEY_PASTE,
+KeyCode::Find => OsCode::KEY_FIND,
+KeyCode::Cut => OsCode::KEY_CUT,
+KeyCode::Help => OsCode::KEY_HELP,
+KeyCode::Menu => OsCode::KEY_MENU,
+KeyCode::MediaCalc => OsCode::KEY_CALC,
+KeyCode::MediaSleep => OsCode::KEY_SLEEP,
+KeyCode::MediaWWW => OsCode::KEY_WWW,
+KeyCode::MediaCoffee => OsCode::KEY_COFFEE,
+KeyCode::MediaBack => OsCode::KEY_BACK,
+KeyCode::MediaForward => OsCode::KEY_FORWARD,
+KeyCode::MediaEjectCD => OsCode::KEY_EJECTCD,
+KeyCode::MediaNextSong => OsCode::KEY_NEXTSONG,
+KeyCode::MediaPlayPause => OsCode::KEY_PLAYPAUSE,
+KeyCode::MediaPreviousSong => OsCode::KEY_PREVIOUSSONG,
+KeyCode::MediaStopCD => OsCode::KEY_STOPCD,
+KeyCode::MediaRefresh => OsCode::KEY_REFRESH,
+KeyCode::MediaEdit => OsCode::KEY_EDIT,
+KeyCode::MediaScrollUp => OsCode::KEY_SCROLLUP,
+KeyCode::MediaScrollDown => OsCode::KEY_SCROLLDOWN,
+KeyCode::F13 => OsCode::KEY_F13,
+KeyCode::F14 => OsCode::KEY_F14,
+KeyCode::F15 => OsCode::KEY_F15,
+KeyCode::F16 => OsCode::KEY_F16,
+KeyCode::F17 => OsCode::KEY_F17,
+KeyCode::F18 => OsCode::KEY_F18,
+KeyCode::F19 => OsCode::KEY_F19,
+KeyCode::F20 => OsCode::KEY_F20,
+KeyCode::F21 => OsCode::KEY_F21,
+KeyCode::F22 => OsCode::KEY_F22,
+KeyCode::F23 => OsCode::KEY_F23,
+KeyCode::F24 => OsCode::KEY_F24,
+KeyCode::Wakeup => OsCode::KEY_WAKEUP,
+KeyCode::BrightnessUp => OsCode::KEY_BRIGHTNESSUP,
+KeyCode::BrightnessDown => OsCode::KEY_BRIGHTNESSDOWN,
+KeyCode::KbdIllumUp => OsCode::KEY_KBDILLUMUP,
+KeyCode::KbdIllumDown => OsCode::KEY_KBDILLUMDOWN,
+KeyCode::Lang1 => OsCode::KEY_HANGEUL,
+KeyCode::Lang2 => OsCode::KEY_HANJA,
+KeyCode::NonUsBslash => OsCode::KEY_102ND,
+KeyCode::PScreen => OsCode::KEY_PRINT,
+KeyCode::Application => OsCode::KEY_COMPOSE,
+KeyCode::AltErase => OsCode::KEY_ALTERASE,
+KeyCode::Cancel => OsCode::KEY_CANCEL,
+KeyCode::MediaMute => OsCode::KEY_MICMUTE,
+KeyCode::Intl1 => OsCode::KEY_RO,
+KeyCode::Intl3 => OsCode::KEY_YEN,
+KeyCode::K0xAA => OsCode::KEY_MEDIA,
+KeyCode::K0xAB => OsCode::KEY_EMAIL,
+KeyCode::K0xAC => OsCode::KEY_PLAYER,
+KeyCode::K0xAD => OsCode::KEY_HOMEPAGE,
+KeyCode::K0xAE => OsCode::KEY_MAIL,
+KeyCode::K0xAF => OsCode::KEY_MUHENKAN,
+KeyCode::K0xB0 => OsCode::KEY_HENKAN,
+KeyCode::K0xB1 => OsCode::KEY_KATAKANA,
+KeyCode::K0xB2 => OsCode::KEY_KATAKANAHIRAGANA,
+KeyCode::K0xB3 => OsCode::KEY_HIRAGANA,
+KeyCode::K252 => OsCode::KEY_252,
+KeyCode::K253 => OsCode::KEY_253,
+KeyCode::K254 => OsCode::KEY_254,
+KeyCode::K255 => OsCode::KEY_255,
+KeyCode::K256 => OsCode::BTN_0,
+KeyCode::K257 => OsCode::BTN_1,
+KeyCode::K258 => OsCode::BTN_2,
+KeyCode::K259 => OsCode::BTN_3,
+KeyCode::K260 => OsCode::BTN_4,
+KeyCode::K261 => OsCode::BTN_5,
+KeyCode::K262 => OsCode::BTN_6,
+KeyCode::K263 => OsCode::BTN_7,
+KeyCode::K264 => OsCode::BTN_8,
+KeyCode::K265 => OsCode::BTN_9,
+KeyCode::K266 => OsCode::KEY_266,
+KeyCode::K267 => OsCode::KEY_267,
+KeyCode::K268 => OsCode::KEY_268,
+KeyCode::K269 => OsCode::KEY_269,
+KeyCode::K270 => OsCode::KEY_270,
+KeyCode::K271 => OsCode::KEY_271,
+KeyCode::K272 => OsCode::BTN_LEFT,
+KeyCode::K273 => OsCode::BTN_RIGHT,
+KeyCode::K274 => OsCode::BTN_MIDDLE,
+KeyCode::K275 => OsCode::BTN_SIDE,
+KeyCode::K276 => OsCode::BTN_EXTRA,
+KeyCode::K277 => OsCode::BTN_FORWARD,
+KeyCode::K278 => OsCode::BTN_BACK,
+KeyCode::K279 => OsCode::BTN_TASK,
+KeyCode::K280 => OsCode::KEY_280,
+KeyCode::K281 => OsCode::KEY_281,
+KeyCode::K282 => OsCode::KEY_282,
+KeyCode::K283 => OsCode::KEY_283,
+KeyCode::K284 => OsCode::KEY_284,
+KeyCode::K285 => OsCode::KEY_285,
+KeyCode::K286 => OsCode::KEY_286,
+KeyCode::K287 => OsCode::KEY_287,
+KeyCode::K288 => OsCode::BTN_TRIGGER,
+KeyCode::K289 => OsCode::BTN_THUMB,
+KeyCode::K290 => OsCode::BTN_THUMB2,
+KeyCode::K291 => OsCode::BTN_TOP,
+KeyCode::K292 => OsCode::BTN_TOP2,
+KeyCode::K293 => OsCode::BTN_PINKIE,
+KeyCode::K294 => OsCode::BTN_BASE,
+KeyCode::K295 => OsCode::BTN_BASE2,
+KeyCode::K296 => OsCode::BTN_BASE3,
+KeyCode::K297 => OsCode::BTN_BASE4,
+KeyCode::K298 => OsCode::BTN_BASE5,
+KeyCode::K299 => OsCode::BTN_BASE6,
+KeyCode::K300 => OsCode::KEY_300,
+KeyCode::K301 => OsCode::KEY_301,
+KeyCode::K302 => OsCode::KEY_302,
+KeyCode::K303 => OsCode::BTN_DEAD,
+KeyCode::K304 => OsCode::BTN_SOUTH,
+KeyCode::K305 => OsCode::BTN_EAST,
+KeyCode::K306 => OsCode::BTN_C,
+KeyCode::K307 => OsCode::BTN_NORTH,
+KeyCode::K308 => OsCode::BTN_WEST,
+KeyCode::K309 => OsCode::BTN_Z,
+KeyCode::K310 => OsCode::BTN_TL,
+KeyCode::K311 => OsCode::BTN_TR,
+KeyCode::K312 => OsCode::BTN_TL2,
+KeyCode::K313 => OsCode::BTN_TR2,
+KeyCode::K314 => OsCode::BTN_SELECT,
+KeyCode::K315 => OsCode::BTN_START,
+KeyCode::K316 => OsCode::BTN_MODE,
+KeyCode::K317 => OsCode::BTN_THUMBL,
+KeyCode::K318 => OsCode::BTN_THUMBR,
+KeyCode::K319 => OsCode::KEY_319,
+KeyCode::K320 => OsCode::BTN_TOOL_PEN,
+KeyCode::K321 => OsCode::BTN_TOOL_RUBBER,
+KeyCode::K322 => OsCode::BTN_TOOL_BRUSH,
+KeyCode::K323 => OsCode::BTN_TOOL_PENCIL,
+KeyCode::K324 => OsCode::BTN_TOOL_AIRBRUSH,
+KeyCode::K325 => OsCode::BTN_TOOL_FINGER,
+KeyCode::K326 => OsCode::BTN_TOOL_MOUSE,
+KeyCode::K327 => OsCode::BTN_TOOL_LENS,
+KeyCode::K328 => OsCode::BTN_TOOL_QUINTTAP,
+KeyCode::K329 => OsCode::BTN_STYLUS3,
+KeyCode::K330 => OsCode::BTN_TOUCH,
+KeyCode::K331 => OsCode::BTN_STYLUS,
+KeyCode::K332 => OsCode::BTN_STYLUS2,
+KeyCode::K333 => OsCode::BTN_TOOL_DOUBLETAP,
+KeyCode::K334 => OsCode::BTN_TOOL_TRIPLETAP,
+KeyCode::K335 => OsCode::BTN_TOOL_QUADTAP,
+KeyCode::K336 => OsCode::BTN_GEAR_DOWN,
+KeyCode::K337 => OsCode::BTN_GEAR_UP,
+KeyCode::K338 => OsCode::KEY_338,
+KeyCode::K339 => OsCode::KEY_339,
+KeyCode::K340 => OsCode::KEY_340,
+KeyCode::K341 => OsCode::KEY_341,
+KeyCode::K342 => OsCode::KEY_342,
+KeyCode::K343 => OsCode::KEY_343,
+KeyCode::K344 => OsCode::KEY_344,
+KeyCode::K345 => OsCode::KEY_345,
+KeyCode::K346 => OsCode::KEY_346,
+KeyCode::K347 => OsCode::KEY_347,
+KeyCode::K348 => OsCode::KEY_348,
+KeyCode::K349 => OsCode::KEY_349,
+KeyCode::K350 => OsCode::KEY_350,
+KeyCode::K351 => OsCode::KEY_351,
+KeyCode::K352 => OsCode::KEY_OK,
+KeyCode::K353 => OsCode::KEY_SELECT,
+KeyCode::K354 => OsCode::KEY_GOTO,
+KeyCode::K355 => OsCode::KEY_CLEAR,
+KeyCode::K356 => OsCode::KEY_POWER2,
+KeyCode::K357 => OsCode::KEY_OPTION,
+KeyCode::K358 => OsCode::KEY_INFO,
+KeyCode::K359 => OsCode::KEY_TIME,
+KeyCode::K360 => OsCode::KEY_VENDOR,
+KeyCode::K361 => OsCode::KEY_ARCHIVE,
+KeyCode::K362 => OsCode::KEY_PROGRAM,
+KeyCode::K363 => OsCode::KEY_CHANNEL,
+KeyCode::K364 => OsCode::KEY_FAVORITES,
+KeyCode::K365 => OsCode::KEY_EPG,
+KeyCode::K366 => OsCode::KEY_PVR,
+KeyCode::K367 => OsCode::KEY_MHP,
+KeyCode::K368 => OsCode::KEY_LANGUAGE,
+KeyCode::K369 => OsCode::KEY_TITLE,
+KeyCode::K370 => OsCode::KEY_SUBTITLE,
+KeyCode::K371 => OsCode::KEY_ANGLE,
+KeyCode::K372 => OsCode::KEY_FULL_SCREEN,
+KeyCode::K373 => OsCode::KEY_MODE,
+KeyCode::K374 => OsCode::KEY_KEYBOARD,
+KeyCode::K375 => OsCode::KEY_ASPECT_RATIO,
+KeyCode::K376 => OsCode::KEY_PC,
+KeyCode::K377 => OsCode::KEY_TV,
+KeyCode::K378 => OsCode::KEY_TV2,
+KeyCode::K379 => OsCode::KEY_VCR,
+KeyCode::K380 => OsCode::KEY_VCR2,
+KeyCode::K381 => OsCode::KEY_SAT,
+KeyCode::K382 => OsCode::KEY_SAT2,
+KeyCode::K383 => OsCode::KEY_CD,
+KeyCode::K384 => OsCode::KEY_TAPE,
+KeyCode::K385 => OsCode::KEY_RADIO,
+KeyCode::K386 => OsCode::KEY_TUNER,
+KeyCode::K387 => OsCode::KEY_PLAYER,
+KeyCode::K388 => OsCode::KEY_TEXT,
+KeyCode::K389 => OsCode::KEY_DVD,
+KeyCode::K390 => OsCode::KEY_AUX,
+KeyCode::K391 => OsCode::KEY_MP3,
+KeyCode::K392 => OsCode::KEY_AUDIO,
+KeyCode::K393 => OsCode::KEY_VIDEO,
+KeyCode::K394 => OsCode::KEY_DIRECTORY,
+KeyCode::K395 => OsCode::KEY_LIST,
+KeyCode::K396 => OsCode::KEY_MEMO,
+KeyCode::K397 => OsCode::KEY_CALENDAR,
+KeyCode::K398 => OsCode::KEY_RED,
+KeyCode::K399 => OsCode::KEY_GREEN,
+KeyCode::K400 => OsCode::KEY_YELLOW,
+KeyCode::K401 => OsCode::KEY_BLUE,
+KeyCode::K402 => OsCode::KEY_CHANNELUP,
+KeyCode::K403 => OsCode::KEY_CHANNELDOWN,
+KeyCode::K404 => OsCode::KEY_FIRST,
+KeyCode::K405 => OsCode::KEY_LAST,
+KeyCode::K406 => OsCode::KEY_AB,
+KeyCode::K407 => OsCode::KEY_NEXT,
+KeyCode::K408 => OsCode::KEY_RESTART,
+KeyCode::K409 => OsCode::KEY_SLOW,
+KeyCode::K410 => OsCode::KEY_SHUFFLE,
+KeyCode::K411 => OsCode::KEY_BREAK,
+KeyCode::K412 => OsCode::KEY_PREVIOUS,
+KeyCode::K413 => OsCode::KEY_DIGITS,
+KeyCode::K414 => OsCode::KEY_TEEN,
+KeyCode::K415 => OsCode::KEY_TWEN,
+KeyCode::K416 => OsCode::KEY_VIDEOPHONE,
+KeyCode::K417 => OsCode::KEY_GAMES,
+KeyCode::K418 => OsCode::KEY_ZOOMIN,
+KeyCode::K419 => OsCode::KEY_ZOOMOUT,
+KeyCode::K420 => OsCode::KEY_ZOOMRESET,
+KeyCode::K421 => OsCode::KEY_WORDPROCESSOR,
+KeyCode::K422 => OsCode::KEY_EDITOR,
+KeyCode::K423 => OsCode::KEY_SPREADSHEET,
+KeyCode::K424 => OsCode::KEY_GRAPHICSEDITOR,
+KeyCode::K425 => OsCode::KEY_PRESENTATION,
+KeyCode::K426 => OsCode::KEY_DATABASE,
+KeyCode::K427 => OsCode::KEY_NEWS,
+KeyCode::K428 => OsCode::KEY_VOICEMAIL,
+KeyCode::K429 => OsCode::KEY_ADDRESSBOOK,
+KeyCode::K430 => OsCode::KEY_MESSENGER,
+KeyCode::K431 => OsCode::KEY_DISPLAYTOGGLE,
+KeyCode::K432 => OsCode::KEY_SPELLCHECK,
+KeyCode::K433 => OsCode::KEY_LOGOFF,
+KeyCode::K434 => OsCode::KEY_DOLLAR,
+KeyCode::K435 => OsCode::KEY_EURO,
+KeyCode::K436 => OsCode::KEY_FRAMEBACK,
+KeyCode::K437 => OsCode::KEY_FRAMEFORWARD,
+KeyCode::K438 => OsCode::KEY_CONTEXT_MENU,
+KeyCode::K439 => OsCode::KEY_MEDIA_REPEAT,
+KeyCode::K440 => OsCode::KEY_10CHANNELSUP,
+KeyCode::K441 => OsCode::KEY_10CHANNELSDOWN,
+KeyCode::K442 => OsCode::KEY_IMAGES,
+KeyCode::K443 => OsCode::KEY_443,
+KeyCode::K444 => OsCode::KEY_444,
+KeyCode::K445 => OsCode::KEY_445,
+KeyCode::K446 => OsCode::KEY_446,
+KeyCode::K447 => OsCode::KEY_447,
+KeyCode::K448 => OsCode::KEY_DEL_EOL,
+KeyCode::K449 => OsCode::KEY_DEL_EOS,
+KeyCode::K450 => OsCode::KEY_INS_LINE,
+KeyCode::K451 => OsCode::KEY_DEL_LINE,
+KeyCode::K452 => OsCode::KEY_452,
+KeyCode::K453 => OsCode::KEY_453,
+KeyCode::K454 => OsCode::KEY_454,
+KeyCode::K455 => OsCode::KEY_455,
+KeyCode::K456 => OsCode::KEY_456,
+KeyCode::K457 => OsCode::KEY_457,
+KeyCode::K458 => OsCode::KEY_458,
+KeyCode::K459 => OsCode::KEY_459,
+KeyCode::K460 => OsCode::KEY_460,
+KeyCode::K461 => OsCode::KEY_461,
+KeyCode::K462 => OsCode::KEY_462,
+KeyCode::K463 => OsCode::KEY_463,
+KeyCode::K464 => OsCode::KEY_FN,
+KeyCode::K465 => OsCode::KEY_FN_ESC,
+KeyCode::K466 => OsCode::KEY_FN_F1,
+KeyCode::K467 => OsCode::KEY_FN_F2,
+KeyCode::K468 => OsCode::KEY_FN_F3,
+KeyCode::K469 => OsCode::KEY_FN_F4,
+KeyCode::K470 => OsCode::KEY_FN_F5,
+KeyCode::K471 => OsCode::KEY_FN_F6,
+KeyCode::K472 => OsCode::KEY_FN_F7,
+KeyCode::K473 => OsCode::KEY_FN_F8,
+KeyCode::K474 => OsCode::KEY_FN_F9,
+KeyCode::K475 => OsCode::KEY_FN_F10,
+KeyCode::K476 => OsCode::KEY_FN_F11,
+KeyCode::K477 => OsCode::KEY_FN_F12,
+KeyCode::K478 => OsCode::KEY_FN_1,
+KeyCode::K479 => OsCode::KEY_FN_2,
+KeyCode::K480 => OsCode::KEY_FN_D,
+KeyCode::K481 => OsCode::KEY_FN_E,
+KeyCode::K482 => OsCode::KEY_FN_F,
+KeyCode::K483 => OsCode::KEY_FN_S,
+KeyCode::K484 => OsCode::KEY_FN_B,
+KeyCode::K485 => OsCode::KEY_485,
+KeyCode::K486 => OsCode::KEY_486,
+KeyCode::K487 => OsCode::KEY_487,
+KeyCode::K488 => OsCode::KEY_488,
+KeyCode::K489 => OsCode::KEY_489,
+KeyCode::K490 => OsCode::KEY_490,
+KeyCode::K491 => OsCode::KEY_491,
+KeyCode::K492 => OsCode::KEY_492,
+KeyCode::K493 => OsCode::KEY_493,
+KeyCode::K494 => OsCode::KEY_494,
+KeyCode::K495 => OsCode::KEY_495,
+KeyCode::K496 => OsCode::KEY_496,
+KeyCode::K497 => OsCode::KEY_BRL_DOT1,
+KeyCode::K498 => OsCode::KEY_BRL_DOT2,
+KeyCode::K499 => OsCode::KEY_BRL_DOT3,
+KeyCode::K500 => OsCode::KEY_BRL_DOT4,
+KeyCode::K501 => OsCode::KEY_BRL_DOT5,
+KeyCode::K502 => OsCode::KEY_BRL_DOT6,
+KeyCode::K503 => OsCode::KEY_BRL_DOT7,
+KeyCode::K504 => OsCode::KEY_BRL_DOT8,
+KeyCode::K505 => OsCode::KEY_BRL_DOT9,
+KeyCode::K506 => OsCode::KEY_BRL_DOT10,
+KeyCode::K507 => OsCode::KEY_507,
+KeyCode::K508 => OsCode::KEY_508,
+KeyCode::K509 => OsCode::KEY_509,
+KeyCode::K510 => OsCode::KEY_510,
+KeyCode::K511 => OsCode::KEY_511,
+KeyCode::K512 => OsCode::KEY_NUMERIC_0,
+KeyCode::K513 => OsCode::KEY_NUMERIC_1,
+KeyCode::K514 => OsCode::KEY_NUMERIC_2,
+KeyCode::K515 => OsCode::KEY_NUMERIC_3,
+KeyCode::K516 => OsCode::KEY_NUMERIC_4,
+KeyCode::K517 => OsCode::KEY_NUMERIC_5,
+KeyCode::K518 => OsCode::KEY_NUMERIC_6,
+KeyCode::K519 => OsCode::KEY_NUMERIC_7,
+KeyCode::K520 => OsCode::KEY_NUMERIC_8,
+KeyCode::K521 => OsCode::KEY_NUMERIC_9,
+KeyCode::K522 => OsCode::KEY_NUMERIC_STAR,
+KeyCode::K523 => OsCode::KEY_NUMERIC_POUND,
+KeyCode::K524 => OsCode::KEY_NUMERIC_A,
+KeyCode::K525 => OsCode::KEY_NUMERIC_B,
+KeyCode::K526 => OsCode::KEY_NUMERIC_C,
+KeyCode::K527 => OsCode::KEY_NUMERIC_D,
+KeyCode::K528 => OsCode::KEY_CAMERA_FOCUS,
+KeyCode::K529 => OsCode::KEY_WPS_BUTTON,
+KeyCode::K530 => OsCode::KEY_TOUCHPAD_TOGGLE,
+KeyCode::K531 => OsCode::KEY_TOUCHPAD_ON,
+KeyCode::K532 => OsCode::KEY_TOUCHPAD_OFF,
+KeyCode::K533 => OsCode::KEY_CAMERA_ZOOMIN,
+KeyCode::K534 => OsCode::KEY_CAMERA_ZOOMOUT,
+KeyCode::K535 => OsCode::KEY_CAMERA_UP,
+KeyCode::K536 => OsCode::KEY_CAMERA_DOWN,
+KeyCode::K537 => OsCode::KEY_CAMERA_LEFT,
+KeyCode::K538 => OsCode::KEY_CAMERA_RIGHT,
+KeyCode::K539 => OsCode::KEY_ATTENDANT_ON,
+KeyCode::K540 => OsCode::KEY_ATTENDANT_OFF,
+KeyCode::K541 => OsCode::KEY_ATTENDANT_TOGGLE,
+KeyCode::K542 => OsCode::KEY_LIGHTS_TOGGLE,
+KeyCode::K543 => OsCode::KEY_543,
+KeyCode::K544 => OsCode::BTN_DPAD_UP,
+KeyCode::K545 => OsCode::BTN_DPAD_DOWN,
+KeyCode::K546 => OsCode::BTN_DPAD_LEFT,
+KeyCode::K547 => OsCode::BTN_DPAD_RIGHT,
+KeyCode::K548 => OsCode::KEY_548,
+KeyCode::K549 => OsCode::KEY_549,
+KeyCode::K550 => OsCode::KEY_550,
+KeyCode::K551 => OsCode::KEY_551,
+KeyCode::K552 => OsCode::KEY_552,
+KeyCode::K553 => OsCode::KEY_553,
+KeyCode::K554 => OsCode::KEY_554,
+KeyCode::K555 => OsCode::KEY_555,
+KeyCode::K556 => OsCode::KEY_556,
+KeyCode::K557 => OsCode::KEY_557,
+KeyCode::K558 => OsCode::KEY_558,
+KeyCode::K559 => OsCode::KEY_559,
+KeyCode::K560 => OsCode::KEY_ALS_TOGGLE,
+KeyCode::K561 => OsCode::KEY_ROTATE_LOCK_TOGGLE,
+KeyCode::K562 => OsCode::KEY_562,
+KeyCode::K563 => OsCode::KEY_563,
+KeyCode::K564 => OsCode::KEY_564,
+KeyCode::K565 => OsCode::KEY_565,
+KeyCode::K566 => OsCode::KEY_566,
+KeyCode::K567 => OsCode::KEY_567,
+KeyCode::K568 => OsCode::KEY_568,
+KeyCode::K569 => OsCode::KEY_569,
+KeyCode::K570 => OsCode::KEY_570,
+KeyCode::K571 => OsCode::KEY_571,
+KeyCode::K572 => OsCode::KEY_572,
+KeyCode::K573 => OsCode::KEY_573,
+KeyCode::K574 => OsCode::KEY_574,
+KeyCode::K575 => OsCode::KEY_575,
+KeyCode::K576 => OsCode::KEY_BUTTONCONFIG,
+KeyCode::K577 => OsCode::KEY_TASKMANAGER,
+KeyCode::K578 => OsCode::KEY_JOURNAL,
+KeyCode::K579 => OsCode::KEY_CONTROLPANEL,
+KeyCode::K580 => OsCode::KEY_APPSELECT,
+KeyCode::K581 => OsCode::KEY_SCREENSAVER,
+KeyCode::K582 => OsCode::KEY_VOICECOMMAND,
+KeyCode::K583 => OsCode::KEY_ASSISTANT,
+KeyCode::K584 => OsCode::KEY_KBD_LAYOUT_NEXT,
+KeyCode::K585 => OsCode::KEY_585,
+KeyCode::K586 => OsCode::KEY_586,
+KeyCode::K587 => OsCode::KEY_587,
+KeyCode::K588 => OsCode::KEY_588,
+KeyCode::K589 => OsCode::KEY_589,
+KeyCode::K590 => OsCode::KEY_590,
+KeyCode::K591 => OsCode::KEY_591,
+KeyCode::K592 => OsCode::KEY_BRIGHTNESS_MIN,
+KeyCode::K593 => OsCode::KEY_BRIGHTNESS_MAX,
+KeyCode::K594 => OsCode::KEY_594,
+KeyCode::K595 => OsCode::KEY_595,
+KeyCode::K596 => OsCode::KEY_596,
+KeyCode::K597 => OsCode::KEY_597,
+KeyCode::K598 => OsCode::KEY_598,
+KeyCode::K599 => OsCode::KEY_599,
+KeyCode::K600 => OsCode::KEY_600,
+KeyCode::K601 => OsCode::KEY_601,
+KeyCode::K602 => OsCode::KEY_602,
+KeyCode::K603 => OsCode::KEY_603,
+KeyCode::K604 => OsCode::KEY_604,
+KeyCode::K605 => OsCode::KEY_605,
+KeyCode::K606 => OsCode::KEY_606,
+KeyCode::K607 => OsCode::KEY_607,
+KeyCode::K608 => OsCode::KEY_KBDINPUTASSIST_PREV,
+KeyCode::K609 => OsCode::KEY_KBDINPUTASSIST_NEXT,
+KeyCode::K610 => OsCode::KEY_KBDINPUTASSIST_PREVGROUP,
+KeyCode::K611 => OsCode::KEY_KBDINPUTASSIST_NEXTGROUP,
+KeyCode::K612 => OsCode::KEY_KBDINPUTASSIST_ACCEPT,
+KeyCode::K613 => OsCode::KEY_KBDINPUTASSIST_CANCEL,
+KeyCode::K614 => OsCode::KEY_RIGHT_UP,
+KeyCode::K615 => OsCode::KEY_RIGHT_DOWN,
+KeyCode::K616 => OsCode::KEY_LEFT_UP,
+KeyCode::K617 => OsCode::KEY_LEFT_DOWN,
+KeyCode::K618 => OsCode::KEY_ROOT_MENU,
+KeyCode::K619 => OsCode::KEY_MEDIA_TOP_MENU,
+KeyCode::K620 => OsCode::KEY_NUMERIC_11,
+KeyCode::K621 => OsCode::KEY_NUMERIC_12,
+KeyCode::K622 => OsCode::KEY_AUDIO_DESC,
+KeyCode::K623 => OsCode::KEY_3D_MODE,
+KeyCode::K624 => OsCode::KEY_NEXT_FAVORITE,
+KeyCode::K625 => OsCode::KEY_STOP_RECORD,
+KeyCode::K626 => OsCode::KEY_PAUSE_RECORD,
+KeyCode::K627 => OsCode::KEY_VOD,
+KeyCode::K628 => OsCode::KEY_UNMUTE,
+KeyCode::K629 => OsCode::KEY_FASTREVERSE,
+KeyCode::K630 => OsCode::KEY_SLOWREVERSE,
+KeyCode::K631 => OsCode::KEY_DATA,
+KeyCode::K632 => OsCode::KEY_ONSCREEN_KEYBOARD,
+KeyCode::K633 => OsCode::KEY_633,
+KeyCode::K634 => OsCode::KEY_634,
+KeyCode::K635 => OsCode::KEY_635,
+KeyCode::K636 => OsCode::KEY_636,
+KeyCode::K637 => OsCode::KEY_637,
+KeyCode::K638 => OsCode::KEY_638,
+KeyCode::K639 => OsCode::KEY_639,
+KeyCode::K640 => OsCode::KEY_640,
+KeyCode::K641 => OsCode::KEY_641,
+KeyCode::K642 => OsCode::KEY_642,
+KeyCode::K643 => OsCode::KEY_643,
+KeyCode::K644 => OsCode::KEY_644,
+KeyCode::K645 => OsCode::KEY_645,
+KeyCode::K646 => OsCode::KEY_646,
+KeyCode::K647 => OsCode::KEY_647,
+KeyCode::K648 => OsCode::KEY_648,
+KeyCode::K649 => OsCode::KEY_649,
+KeyCode::K650 => OsCode::KEY_650,
+KeyCode::K651 => OsCode::KEY_651,
+KeyCode::K652 => OsCode::KEY_652,
+KeyCode::K653 => OsCode::KEY_653,
+KeyCode::K654 => OsCode::KEY_654,
+KeyCode::K655 => OsCode::KEY_655,
+KeyCode::K656 => OsCode::KEY_656,
+KeyCode::K657 => OsCode::KEY_657,
+KeyCode::K658 => OsCode::KEY_658,
+KeyCode::K659 => OsCode::KEY_659,
+KeyCode::K660 => OsCode::KEY_660,
+KeyCode::K661 => OsCode::KEY_661,
+KeyCode::K662 => OsCode::KEY_662,
+KeyCode::K663 => OsCode::KEY_663,
+KeyCode::K664 => OsCode::KEY_664,
+KeyCode::K665 => OsCode::KEY_665,
+KeyCode::K666 => OsCode::KEY_666,
+KeyCode::K667 => OsCode::KEY_667,
+KeyCode::K668 => OsCode::KEY_668,
+KeyCode::K669 => OsCode::KEY_669,
+KeyCode::K670 => OsCode::KEY_670,
+KeyCode::K671 => OsCode::KEY_671,
+KeyCode::K672 => OsCode::KEY_672,
+KeyCode::K673 => OsCode::KEY_673,
+KeyCode::K674 => OsCode::KEY_674,
+KeyCode::K675 => OsCode::KEY_675,
+KeyCode::K676 => OsCode::KEY_676,
+KeyCode::K677 => OsCode::KEY_677,
+KeyCode::K678 => OsCode::KEY_678,
+KeyCode::K679 => OsCode::KEY_679,
+KeyCode::K680 => OsCode::KEY_680,
+KeyCode::K681 => OsCode::KEY_681,
+KeyCode::K682 => OsCode::KEY_682,
+KeyCode::K683 => OsCode::KEY_683,
+KeyCode::K684 => OsCode::KEY_684,
+KeyCode::K685 => OsCode::KEY_685,
+KeyCode::K686 => OsCode::KEY_686,
+KeyCode::K687 => OsCode::KEY_687,
+KeyCode::K688 => OsCode::KEY_688,
+KeyCode::K689 => OsCode::KEY_689,
+KeyCode::K690 => OsCode::KEY_690,
+KeyCode::K691 => OsCode::KEY_691,
+KeyCode::K692 => OsCode::KEY_692,
+KeyCode::K693 => OsCode::KEY_693,
+KeyCode::K694 => OsCode::KEY_694,
+KeyCode::K695 => OsCode::KEY_695,
+KeyCode::K696 => OsCode::KEY_696,
+KeyCode::K697 => OsCode::KEY_697,
+KeyCode::K698 => OsCode::KEY_698,
+KeyCode::K699 => OsCode::KEY_699,
+KeyCode::K700 => OsCode::KEY_700,
+KeyCode::K701 => OsCode::KEY_701,
+KeyCode::K702 => OsCode::KEY_702,
+KeyCode::K703 => OsCode::KEY_703,
+KeyCode::K704 => OsCode::BTN_TRIGGER_HAPPY1,
+KeyCode::K705 => OsCode::BTN_TRIGGER_HAPPY2,
+KeyCode::K706 => OsCode::BTN_TRIGGER_HAPPY3,
+KeyCode::K707 => OsCode::BTN_TRIGGER_HAPPY4,
+KeyCode::K708 => OsCode::BTN_TRIGGER_HAPPY5,
+KeyCode::K709 => OsCode::BTN_TRIGGER_HAPPY6,
+KeyCode::K710 => OsCode::BTN_TRIGGER_HAPPY7,
+KeyCode::K711 => OsCode::BTN_TRIGGER_HAPPY8,
+KeyCode::K712 => OsCode::BTN_TRIGGER_HAPPY9,
+KeyCode::K713 => OsCode::BTN_TRIGGER_HAPPY10,
+KeyCode::K714 => OsCode::BTN_TRIGGER_HAPPY11,
+KeyCode::K715 => OsCode::BTN_TRIGGER_HAPPY12,
+KeyCode::K716 => OsCode::BTN_TRIGGER_HAPPY13,
+KeyCode::K717 => OsCode::BTN_TRIGGER_HAPPY14,
+KeyCode::K718 => OsCode::BTN_TRIGGER_HAPPY15,
+KeyCode::K719 => OsCode::BTN_TRIGGER_HAPPY16,
+KeyCode::K720 => OsCode::BTN_TRIGGER_HAPPY17,
+KeyCode::K721 => OsCode::BTN_TRIGGER_HAPPY18,
+KeyCode::K722 => OsCode::BTN_TRIGGER_HAPPY19,
+KeyCode::K723 => OsCode::BTN_TRIGGER_HAPPY20,
+KeyCode::K724 => OsCode::BTN_TRIGGER_HAPPY21,
+KeyCode::K725 => OsCode::BTN_TRIGGER_HAPPY22,
+KeyCode::K726 => OsCode::BTN_TRIGGER_HAPPY23,
+KeyCode::K727 => OsCode::BTN_TRIGGER_HAPPY24,
+KeyCode::K728 => OsCode::BTN_TRIGGER_HAPPY25,
+KeyCode::K729 => OsCode::BTN_TRIGGER_HAPPY26,
+KeyCode::K730 => OsCode::BTN_TRIGGER_HAPPY27,
+KeyCode::K731 => OsCode::BTN_TRIGGER_HAPPY28,
+KeyCode::K732 => OsCode::BTN_TRIGGER_HAPPY29,
+KeyCode::K733 => OsCode::BTN_TRIGGER_HAPPY30,
+KeyCode::K734 => OsCode::BTN_TRIGGER_HAPPY31,
+KeyCode::K735 => OsCode::BTN_TRIGGER_HAPPY32,
+KeyCode::K736 => OsCode::BTN_TRIGGER_HAPPY33,
+KeyCode::K737 => OsCode::BTN_TRIGGER_HAPPY34,
+KeyCode::K738 => OsCode::BTN_TRIGGER_HAPPY35,
+KeyCode::K739 => OsCode::BTN_TRIGGER_HAPPY36,
+KeyCode::K740 => OsCode::BTN_TRIGGER_HAPPY37,
+KeyCode::K741 => OsCode::BTN_TRIGGER_HAPPY38,
+KeyCode::K742 => OsCode::BTN_TRIGGER_HAPPY39,
+KeyCode::K743 => OsCode::BTN_TRIGGER_HAPPY40,
+KeyCode::K744 => OsCode::BTN_MAX,
+KeyCode::MWU => OsCode::MouseWheelUp,
+KeyCode::MWD => OsCode::MouseWheelDown,
+KeyCode::MWL => OsCode::MouseWheelLeft,
+KeyCode::MWR => OsCode::MouseWheelRight,
+
+=== osc to u16
+KEY_RESERVED = 0,
+KEY_ESC = 1,
+KEY_1 = 2,
+KEY_2 = 3,
+KEY_3 = 4,
+KEY_4 = 5,
+KEY_5 = 6,
+KEY_6 = 7,
+KEY_7 = 8,
+KEY_8 = 9,
+KEY_9 = 10,
+KEY_0 = 11,
+KEY_MINUS = 12,
+KEY_EQUAL = 13,
+KEY_BACKSPACE = 14,
+KEY_TAB = 15,
+KEY_Q = 16,
+KEY_W = 17,
+KEY_E = 18,
+KEY_R = 19,
+KEY_T = 20,
+KEY_Y = 21,
+KEY_U = 22,
+KEY_I = 23,
+KEY_O = 24,
+KEY_P = 25,
+KEY_LEFTBRACE = 26,
+KEY_RIGHTBRACE = 27,
+KEY_ENTER = 28,
+KEY_LEFTCTRL = 29,
+KEY_A = 30,
+KEY_S = 31,
+KEY_D = 32,
+KEY_F = 33,
+KEY_G = 34,
+KEY_H = 35,
+KEY_J = 36,
+KEY_K = 37,
+KEY_L = 38,
+KEY_SEMICOLON = 39,
+KEY_APOSTROPHE = 40,
+KEY_GRAVE = 41,
+KEY_LEFTSHIFT = 42,
+KEY_BACKSLASH = 43,
+KEY_Z = 44,
+KEY_X = 45,
+KEY_C = 46,
+KEY_V = 47,
+KEY_B = 48,
+KEY_N = 49,
+KEY_M = 50,
+KEY_COMMA = 51,
+KEY_DOT = 52,
+KEY_SLASH = 53,
+KEY_RIGHTSHIFT = 54,
+KEY_KPASTERISK = 55,
+KEY_LEFTALT = 56,
+KEY_SPACE = 57,
+KEY_CAPSLOCK = 58,
+KEY_F1 = 59,
+KEY_F2 = 60,
+KEY_F3 = 61,
+KEY_F4 = 62,
+KEY_F5 = 63,
+KEY_F6 = 64,
+KEY_F7 = 65,
+KEY_F8 = 66,
+KEY_F9 = 67,
+KEY_F10 = 68,
+KEY_NUMLOCK = 69,
+KEY_SCROLLLOCK = 70,
+KEY_KP7 = 71,
+KEY_KP8 = 72,
+KEY_KP9 = 73,
+KEY_KPMINUS = 74,
+KEY_KP4 = 75,
+KEY_KP5 = 76,
+KEY_KP6 = 77,
+KEY_KPPLUS = 78,
+KEY_KP1 = 79,
+KEY_KP2 = 80,
+KEY_KP3 = 81,
+KEY_KP0 = 82,
+KEY_KPDOT = 83,
+KEY_84 = 84,
+KEY_ZENKAKUHANKAKU = 85,
+KEY_102ND = 86,
+KEY_F11 = 87,
+KEY_F12 = 88,
+KEY_RO = 89,
+KEY_KATAKANA = 90,
+KEY_HIRAGANA = 91,
+KEY_HENKAN = 92,
+KEY_KATAKANAHIRAGANA = 93,
+KEY_MUHENKAN = 94,
+KEY_KPJPCOMMA = 95,
+KEY_KPENTER = 96,
+KEY_RIGHTCTRL = 97,
+KEY_KPSLASH = 98,
+KEY_SYSRQ = 99,
+KEY_RIGHTALT = 100,
+KEY_LINEFEED = 101,
+KEY_HOME = 102,
+KEY_UP = 103,
+KEY_PAGEUP = 104,
+KEY_LEFT = 105,
+KEY_RIGHT = 106,
+KEY_END = 107,
+KEY_DOWN = 108,
+KEY_PAGEDOWN = 109,
+KEY_INSERT = 110,
+KEY_DELETE = 111,
+KEY_MACRO = 112,
+KEY_MUTE = 113,
+KEY_VOLUMEDOWN = 114,
+KEY_VOLUMEUP = 115,
+KEY_POWER = 116,
+KEY_KPEQUAL = 117,
+KEY_KPPLUSMINUS = 118,
+KEY_PAUSE = 119,
+KEY_SCALE = 120,
+KEY_KPCOMMA = 121,
+KEY_HANGEUL = 122,
+KEY_HANJA = 123,
+KEY_YEN = 124,
+KEY_LEFTMETA = 125,
+KEY_RIGHTMETA = 126,
+KEY_COMPOSE = 127,
+KEY_STOP = 128,
+KEY_AGAIN = 129,
+KEY_PROPS = 130,
+KEY_UNDO = 131,
+KEY_FRONT = 132,
+KEY_COPY = 133,
+KEY_OPEN = 134,
+KEY_PASTE = 135,
+KEY_FIND = 136,
+KEY_CUT = 137,
+KEY_HELP = 138,
+KEY_MENU = 139,
+KEY_CALC = 140,
+KEY_SETUP = 141,
+KEY_SLEEP = 142,
+KEY_WAKEUP = 143,
+KEY_FILE = 144,
+KEY_SENDFILE = 145,
+KEY_DELETEFILE = 146,
+KEY_XFER = 147,
+KEY_PROG1 = 148,
+KEY_PROG2 = 149,
+KEY_WWW = 150,
+KEY_MSDOS = 151,
+KEY_COFFEE = 152,
+KEY_ROTATE_DISPLAY = 153,
+KEY_CYCLEWINDOWS = 154,
+KEY_MAIL = 155,
+KEY_BOOKMARKS = 156,
+KEY_COMPUTER = 157,
+KEY_BACK = 158,
+KEY_FORWARD = 159,
+KEY_CLOSECD = 160,
+KEY_EJECTCD = 161,
+KEY_EJECTCLOSECD = 162,
+KEY_NEXTSONG = 163,
+KEY_PLAYPAUSE = 164,
+KEY_PREVIOUSSONG = 165,
+KEY_STOPCD = 166,
+KEY_RECORD = 167,
+KEY_REWIND = 168,
+KEY_PHONE = 169,
+KEY_ISO = 170,
+KEY_CONFIG = 171,
+KEY_HOMEPAGE = 172,
+KEY_REFRESH = 173,
+KEY_EXIT = 174,
+KEY_MOVE = 175,
+KEY_EDIT = 176,
+KEY_SCROLLUP = 177,
+KEY_SCROLLDOWN = 178,
+KEY_KPLEFTPAREN = 179,
+KEY_KPRIGHTPAREN = 180,
+KEY_NEW = 181,
+KEY_REDO = 182,
+KEY_F13 = 183,
+KEY_F14 = 184,
+KEY_F15 = 185,
+KEY_F16 = 186,
+KEY_F17 = 187,
+KEY_F18 = 188,
+KEY_F19 = 189,
+KEY_F20 = 190,
+KEY_F21 = 191,
+KEY_F22 = 192,
+KEY_F23 = 193,
+KEY_F24 = 194,
+KEY_195 = 195,
+KEY_196 = 196,
+KEY_197 = 197,
+KEY_198 = 198,
+KEY_199 = 199,
+KEY_PLAYCD = 200,
+KEY_PAUSECD = 201,
+KEY_PROG3 = 202,
+KEY_PROG4 = 203,
+KEY_DASHBOARD = 204,
+KEY_SUSPEND = 205,
+KEY_CLOSE = 206,
+KEY_PLAY = 207,
+KEY_FASTFORWARD = 208,
+KEY_BASSBOOST = 209,
+KEY_PRINT = 210,
+KEY_HP = 211,
+KEY_CAMERA = 212,
+KEY_SOUND = 213,
+KEY_QUESTION = 214,
+KEY_EMAIL = 215,
+KEY_CHAT = 216,
+KEY_SEARCH = 217,
+KEY_CONNECT = 218,
+KEY_FINANCE = 219,
+KEY_SPORT = 220,
+KEY_SHOP = 221,
+KEY_ALTERASE = 222,
+KEY_CANCEL = 223,
+KEY_BRIGHTNESSDOWN = 224,
+KEY_BRIGHTNESSUP = 225,
+KEY_MEDIA = 226,
+KEY_SWITCHVIDEOMODE = 227,
+KEY_KBDILLUMTOGGLE = 228,
+KEY_KBDILLUMDOWN = 229,
+KEY_KBDILLUMUP = 230,
+KEY_SEND = 231,
+KEY_REPLY = 232,
+KEY_FORWARDMAIL = 233,
+KEY_SAVE = 234,
+KEY_DOCUMENTS = 235,
+KEY_BATTERY = 236,
+KEY_BLUETOOTH = 237,
+KEY_WLAN = 238,
+KEY_UWB = 239,
+KEY_UNKNOWN = 240,
+KEY_VIDEO_NEXT = 241,
+KEY_VIDEO_PREV = 242,
+KEY_BRIGHTNESS_CYCLE = 243,
+KEY_BRIGHTNESS_AUTO = 244,
+KEY_DISPLAY_OFF = 245,
+KEY_WWAN = 246,
+KEY_RFKILL = 247,
+KEY_MICMUTE = 248,
+KEY_249 = 249,
+KEY_250 = 250,
+KEY_251 = 251,
+KEY_252 = 252,
+KEY_253 = 253,
+KEY_254 = 254,
+KEY_255 = 255,
+BTN_0 = 256,
+BTN_1 = 257,
+BTN_2 = 258,
+BTN_3 = 259,
+BTN_4 = 260,
+BTN_5 = 261,
+BTN_6 = 262,
+BTN_7 = 263,
+BTN_8 = 264,
+BTN_9 = 265,
+KEY_266 = 266,
+KEY_267 = 267,
+KEY_268 = 268,
+KEY_269 = 269,
+KEY_270 = 270,
+KEY_271 = 271,
+BTN_LEFT = 272,
+BTN_RIGHT = 273,
+BTN_MIDDLE = 274,
+BTN_SIDE = 275,
+BTN_EXTRA = 276,
+BTN_FORWARD = 277,
+BTN_BACK = 278,
+BTN_TASK = 279,
+KEY_280 = 280,
+KEY_281 = 281,
+KEY_282 = 282,
+KEY_283 = 283,
+KEY_284 = 284,
+KEY_285 = 285,
+KEY_286 = 286,
+KEY_287 = 287,
+BTN_TRIGGER = 288,
+BTN_THUMB = 289,
+BTN_THUMB2 = 290,
+BTN_TOP = 291,
+BTN_TOP2 = 292,
+BTN_PINKIE = 293,
+BTN_BASE = 294,
+BTN_BASE2 = 295,
+BTN_BASE3 = 296,
+BTN_BASE4 = 297,
+BTN_BASE5 = 298,
+BTN_BASE6 = 299,
+KEY_300 = 300,
+KEY_301 = 301,
+KEY_302 = 302,
+BTN_DEAD = 303,
+BTN_SOUTH = 304,
+BTN_EAST = 305,
+BTN_C = 306,
+BTN_NORTH = 307,
+BTN_WEST = 308,
+BTN_Z = 309,
+BTN_TL = 310,
+BTN_TR = 311,
+BTN_TL2 = 312,
+BTN_TR2 = 313,
+BTN_SELECT = 314,
+BTN_START = 315,
+BTN_MODE = 316,
+BTN_THUMBL = 317,
+BTN_THUMBR = 318,
+KEY_319 = 319,
+BTN_TOOL_PEN = 320,
+BTN_TOOL_RUBBER = 321,
+BTN_TOOL_BRUSH = 322,
+BTN_TOOL_PENCIL = 323,
+BTN_TOOL_AIRBRUSH = 324,
+BTN_TOOL_FINGER = 325,
+BTN_TOOL_MOUSE = 326,
+BTN_TOOL_LENS = 327,
+BTN_TOOL_QUINTTAP = 328,
+BTN_STYLUS3 = 329,
+BTN_TOUCH = 330,
+BTN_STYLUS = 331,
+BTN_STYLUS2 = 332,
+BTN_TOOL_DOUBLETAP = 333,
+BTN_TOOL_TRIPLETAP = 334,
+BTN_TOOL_QUADTAP = 335,
+BTN_GEAR_DOWN = 336,
+BTN_GEAR_UP = 337,
+KEY_338 = 338,
+KEY_339 = 339,
+KEY_340 = 340,
+KEY_341 = 341,
+KEY_342 = 342,
+KEY_343 = 343,
+KEY_344 = 344,
+KEY_345 = 345,
+KEY_346 = 346,
+KEY_347 = 347,
+KEY_348 = 348,
+KEY_349 = 349,
+KEY_350 = 350,
+KEY_351 = 351,
+KEY_OK = 352,
+KEY_SELECT = 353,
+KEY_GOTO = 354,
+KEY_CLEAR = 355,
+KEY_POWER2 = 356,
+KEY_OPTION = 357,
+KEY_INFO = 358,
+KEY_TIME = 359,
+KEY_VENDOR = 360,
+KEY_ARCHIVE = 361,
+KEY_PROGRAM = 362,
+KEY_CHANNEL = 363,
+KEY_FAVORITES = 364,
+KEY_EPG = 365,
+KEY_PVR = 366,
+KEY_MHP = 367,
+KEY_LANGUAGE = 368,
+KEY_TITLE = 369,
+KEY_SUBTITLE = 370,
+KEY_ANGLE = 371,
+KEY_FULL_SCREEN = 372,
+KEY_MODE = 373,
+KEY_KEYBOARD = 374,
+KEY_ASPECT_RATIO = 375,
+KEY_PC = 376,
+KEY_TV = 377,
+KEY_TV2 = 378,
+KEY_VCR = 379,
+KEY_VCR2 = 380,
+KEY_SAT = 381,
+KEY_SAT2 = 382,
+KEY_CD = 383,
+KEY_TAPE = 384,
+KEY_RADIO = 385,
+KEY_TUNER = 386,
+KEY_PLAYER = 387,
+KEY_TEXT = 388,
+KEY_DVD = 389,
+KEY_AUX = 390,
+KEY_MP3 = 391,
+KEY_AUDIO = 392,
+KEY_VIDEO = 393,
+KEY_DIRECTORY = 394,
+KEY_LIST = 395,
+KEY_MEMO = 396,
+KEY_CALENDAR = 397,
+KEY_RED = 398,
+KEY_GREEN = 399,
+KEY_YELLOW = 400,
+KEY_BLUE = 401,
+KEY_CHANNELUP = 402,
+KEY_CHANNELDOWN = 403,
+KEY_FIRST = 404,
+KEY_LAST = 405,
+KEY_AB = 406,
+KEY_NEXT = 407,
+KEY_RESTART = 408,
+KEY_SLOW = 409,
+KEY_SHUFFLE = 410,
+KEY_BREAK = 411,
+KEY_PREVIOUS = 412,
+KEY_DIGITS = 413,
+KEY_TEEN = 414,
+KEY_TWEN = 415,
+KEY_VIDEOPHONE = 416,
+KEY_GAMES = 417,
+KEY_ZOOMIN = 418,
+KEY_ZOOMOUT = 419,
+KEY_ZOOMRESET = 420,
+KEY_WORDPROCESSOR = 421,
+KEY_EDITOR = 422,
+KEY_SPREADSHEET = 423,
+KEY_GRAPHICSEDITOR = 424,
+KEY_PRESENTATION = 425,
+KEY_DATABASE = 426,
+KEY_NEWS = 427,
+KEY_VOICEMAIL = 428,
+KEY_ADDRESSBOOK = 429,
+KEY_MESSENGER = 430,
+KEY_DISPLAYTOGGLE = 431,
+KEY_SPELLCHECK = 432,
+KEY_LOGOFF = 433,
+KEY_DOLLAR = 434,
+KEY_EURO = 435,
+KEY_FRAMEBACK = 436,
+KEY_FRAMEFORWARD = 437,
+KEY_CONTEXT_MENU = 438,
+KEY_MEDIA_REPEAT = 439,
+KEY_10CHANNELSUP = 440,
+KEY_10CHANNELSDOWN = 441,
+KEY_IMAGES = 442,
+KEY_443 = 443,
+KEY_444 = 444,
+KEY_445 = 445,
+KEY_446 = 446,
+KEY_447 = 447,
+KEY_DEL_EOL = 448,
+KEY_DEL_EOS = 449,
+KEY_INS_LINE = 450,
+KEY_DEL_LINE = 451,
+KEY_452 = 452,
+KEY_453 = 453,
+KEY_454 = 454,
+KEY_455 = 455,
+KEY_456 = 456,
+KEY_457 = 457,
+KEY_458 = 458,
+KEY_459 = 459,
+KEY_460 = 460,
+KEY_461 = 461,
+KEY_462 = 462,
+KEY_463 = 463,
+KEY_FN = 464,
+KEY_FN_ESC = 465,
+KEY_FN_F1 = 466,
+KEY_FN_F2 = 467,
+KEY_FN_F3 = 468,
+KEY_FN_F4 = 469,
+KEY_FN_F5 = 470,
+KEY_FN_F6 = 471,
+KEY_FN_F7 = 472,
+KEY_FN_F8 = 473,
+KEY_FN_F9 = 474,
+KEY_FN_F10 = 475,
+KEY_FN_F11 = 476,
+KEY_FN_F12 = 477,
+KEY_FN_1 = 478,
+KEY_FN_2 = 479,
+KEY_FN_D = 480,
+KEY_FN_E = 481,
+KEY_FN_F = 482,
+KEY_FN_S = 483,
+KEY_FN_B = 484,
+KEY_485 = 485,
+KEY_486 = 486,
+KEY_487 = 487,
+KEY_488 = 488,
+KEY_489 = 489,
+KEY_490 = 490,
+KEY_491 = 491,
+KEY_492 = 492,
+KEY_493 = 493,
+KEY_494 = 494,
+KEY_495 = 495,
+KEY_496 = 496,
+KEY_BRL_DOT1 = 497,
+KEY_BRL_DOT2 = 498,
+KEY_BRL_DOT3 = 499,
+KEY_BRL_DOT4 = 500,
+KEY_BRL_DOT5 = 501,
+KEY_BRL_DOT6 = 502,
+KEY_BRL_DOT7 = 503,
+KEY_BRL_DOT8 = 504,
+KEY_BRL_DOT9 = 505,
+KEY_BRL_DOT10 = 506,
+KEY_507 = 507,
+KEY_508 = 508,
+KEY_509 = 509,
+KEY_510 = 510,
+KEY_511 = 511,
+KEY_NUMERIC_0 = 512,
+KEY_NUMERIC_1 = 513,
+KEY_NUMERIC_2 = 514,
+KEY_NUMERIC_3 = 515,
+KEY_NUMERIC_4 = 516,
+KEY_NUMERIC_5 = 517,
+KEY_NUMERIC_6 = 518,
+KEY_NUMERIC_7 = 519,
+KEY_NUMERIC_8 = 520,
+KEY_NUMERIC_9 = 521,
+KEY_NUMERIC_STAR = 522,
+KEY_NUMERIC_POUND = 523,
+KEY_NUMERIC_A = 524,
+KEY_NUMERIC_B = 525,
+KEY_NUMERIC_C = 526,
+KEY_NUMERIC_D = 527,
+KEY_CAMERA_FOCUS = 528,
+KEY_WPS_BUTTON = 529,
+KEY_TOUCHPAD_TOGGLE = 530,
+KEY_TOUCHPAD_ON = 531,
+KEY_TOUCHPAD_OFF = 532,
+KEY_CAMERA_ZOOMIN = 533,
+KEY_CAMERA_ZOOMOUT = 534,
+KEY_CAMERA_UP = 535,
+KEY_CAMERA_DOWN = 536,
+KEY_CAMERA_LEFT = 537,
+KEY_CAMERA_RIGHT = 538,
+KEY_ATTENDANT_ON = 539,
+KEY_ATTENDANT_OFF = 540,
+KEY_ATTENDANT_TOGGLE = 541,
+KEY_LIGHTS_TOGGLE = 542,
+KEY_543 = 543,
+BTN_DPAD_UP = 544,
+BTN_DPAD_DOWN = 545,
+BTN_DPAD_LEFT = 546,
+BTN_DPAD_RIGHT = 547,
+KEY_548 = 548,
+KEY_549 = 549,
+KEY_550 = 550,
+KEY_551 = 551,
+KEY_552 = 552,
+KEY_553 = 553,
+KEY_554 = 554,
+KEY_555 = 555,
+KEY_556 = 556,
+KEY_557 = 557,
+KEY_558 = 558,
+KEY_559 = 559,
+KEY_ALS_TOGGLE = 560,
+KEY_ROTATE_LOCK_TOGGLE = 561,
+KEY_562 = 562,
+KEY_563 = 563,
+KEY_564 = 564,
+KEY_565 = 565,
+KEY_566 = 566,
+KEY_567 = 567,
+KEY_568 = 568,
+KEY_569 = 569,
+KEY_570 = 570,
+KEY_571 = 571,
+KEY_572 = 572,
+KEY_573 = 573,
+KEY_574 = 574,
+KEY_575 = 575,
+KEY_BUTTONCONFIG = 576,
+KEY_TASKMANAGER = 577,
+KEY_JOURNAL = 578,
+KEY_CONTROLPANEL = 579,
+KEY_APPSELECT = 580,
+KEY_SCREENSAVER = 581,
+KEY_VOICECOMMAND = 582,
+KEY_ASSISTANT = 583,
+KEY_KBD_LAYOUT_NEXT = 584,
+KEY_585 = 585,
+KEY_586 = 586,
+KEY_587 = 587,
+KEY_588 = 588,
+KEY_589 = 589,
+KEY_590 = 590,
+KEY_591 = 591,
+KEY_BRIGHTNESS_MIN = 592,
+KEY_BRIGHTNESS_MAX = 593,
+KEY_594 = 594,
+KEY_595 = 595,
+KEY_596 = 596,
+KEY_597 = 597,
+KEY_598 = 598,
+KEY_599 = 599,
+KEY_600 = 600,
+KEY_601 = 601,
+KEY_602 = 602,
+KEY_603 = 603,
+KEY_604 = 604,
+KEY_605 = 605,
+KEY_606 = 606,
+KEY_607 = 607,
+KEY_KBDINPUTASSIST_PREV = 608,
+KEY_KBDINPUTASSIST_NEXT = 609,
+KEY_KBDINPUTASSIST_PREVGROUP = 610,
+KEY_KBDINPUTASSIST_NEXTGROUP = 611,
+KEY_KBDINPUTASSIST_ACCEPT = 612,
+KEY_KBDINPUTASSIST_CANCEL = 613,
+KEY_RIGHT_UP = 614,
+KEY_RIGHT_DOWN = 615,
+KEY_LEFT_UP = 616,
+KEY_LEFT_DOWN = 617,
+KEY_ROOT_MENU = 618,
+KEY_MEDIA_TOP_MENU = 619,
+KEY_NUMERIC_11 = 620,
+KEY_NUMERIC_12 = 621,
+KEY_AUDIO_DESC = 622,
+KEY_3D_MODE = 623,
+KEY_NEXT_FAVORITE = 624,
+KEY_STOP_RECORD = 625,
+KEY_PAUSE_RECORD = 626,
+KEY_VOD = 627,
+KEY_UNMUTE = 628,
+KEY_FASTREVERSE = 629,
+KEY_SLOWREVERSE = 630,
+KEY_DATA = 631,
+KEY_ONSCREEN_KEYBOARD = 632,
+KEY_633 = 633,
+KEY_634 = 634,
+KEY_635 = 635,
+KEY_636 = 636,
+KEY_637 = 637,
+KEY_638 = 638,
+KEY_639 = 639,
+KEY_640 = 640,
+KEY_641 = 641,
+KEY_642 = 642,
+KEY_643 = 643,
+KEY_644 = 644,
+KEY_645 = 645,
+KEY_646 = 646,
+KEY_647 = 647,
+KEY_648 = 648,
+KEY_649 = 649,
+KEY_650 = 650,
+KEY_651 = 651,
+KEY_652 = 652,
+KEY_653 = 653,
+KEY_654 = 654,
+KEY_655 = 655,
+KEY_656 = 656,
+KEY_657 = 657,
+KEY_658 = 658,
+KEY_659 = 659,
+KEY_660 = 660,
+KEY_661 = 661,
+KEY_662 = 662,
+KEY_663 = 663,
+KEY_664 = 664,
+KEY_665 = 665,
+KEY_666 = 666,
+KEY_667 = 667,
+KEY_668 = 668,
+KEY_669 = 669,
+KEY_670 = 670,
+KEY_671 = 671,
+KEY_672 = 672,
+KEY_673 = 673,
+KEY_674 = 674,
+KEY_675 = 675,
+KEY_676 = 676,
+KEY_677 = 677,
+KEY_678 = 678,
+KEY_679 = 679,
+KEY_680 = 680,
+KEY_681 = 681,
+KEY_682 = 682,
+KEY_683 = 683,
+KEY_684 = 684,
+KEY_685 = 685,
+KEY_686 = 686,
+KEY_687 = 687,
+KEY_688 = 688,
+KEY_689 = 689,
+KEY_690 = 690,
+KEY_691 = 691,
+KEY_692 = 692,
+KEY_693 = 693,
+KEY_694 = 694,
+KEY_695 = 695,
+KEY_696 = 696,
+KEY_697 = 697,
+KEY_698 = 698,
+KEY_699 = 699,
+KEY_700 = 700,
+KEY_701 = 701,
+KEY_702 = 702,
+KEY_703 = 703,
+BTN_TRIGGER_HAPPY1 = 704,
+BTN_TRIGGER_HAPPY2 = 705,
+BTN_TRIGGER_HAPPY3 = 706,
+BTN_TRIGGER_HAPPY4 = 707,
+BTN_TRIGGER_HAPPY5 = 708,
+BTN_TRIGGER_HAPPY6 = 709,
+BTN_TRIGGER_HAPPY7 = 710,
+BTN_TRIGGER_HAPPY8 = 711,
+BTN_TRIGGER_HAPPY9 = 712,
+BTN_TRIGGER_HAPPY10 = 713,
+BTN_TRIGGER_HAPPY11 = 714,
+BTN_TRIGGER_HAPPY12 = 715,
+BTN_TRIGGER_HAPPY13 = 716,
+BTN_TRIGGER_HAPPY14 = 717,
+BTN_TRIGGER_HAPPY15 = 718,
+BTN_TRIGGER_HAPPY16 = 719,
+BTN_TRIGGER_HAPPY17 = 720,
+BTN_TRIGGER_HAPPY18 = 721,
+BTN_TRIGGER_HAPPY19 = 722,
+BTN_TRIGGER_HAPPY20 = 723,
+BTN_TRIGGER_HAPPY21 = 724,
+BTN_TRIGGER_HAPPY22 = 725,
+BTN_TRIGGER_HAPPY23 = 726,
+BTN_TRIGGER_HAPPY24 = 727,
+BTN_TRIGGER_HAPPY25 = 728,
+BTN_TRIGGER_HAPPY26 = 729,
+BTN_TRIGGER_HAPPY27 = 730,
+BTN_TRIGGER_HAPPY28 = 731,
+BTN_TRIGGER_HAPPY29 = 732,
+BTN_TRIGGER_HAPPY30 = 733,
+BTN_TRIGGER_HAPPY31 = 734,
+BTN_TRIGGER_HAPPY32 = 735,
+BTN_TRIGGER_HAPPY33 = 736,
+BTN_TRIGGER_HAPPY34 = 737,
+BTN_TRIGGER_HAPPY35 = 738,
+BTN_TRIGGER_HAPPY36 = 739,
+BTN_TRIGGER_HAPPY37 = 740,
+BTN_TRIGGER_HAPPY38 = 741,
+BTN_TRIGGER_HAPPY39 = 742,
+BTN_TRIGGER_HAPPY40 = 743,
+BTN_MAX = 744,
+MouseWheelUp = 745,
+MouseWheelDown = 746,
+MouseWheelLeft = 747,
+MouseWheelRight = 748,
+KEY_MAX = 767,
+
+=== all kcs
+No,
+ErrorRollOver,
+PostFail,
+ErrorUndefined,
+A,
+B,
+C,
+D,
+E,
+F,
+G,
+H,
+I,
+J,
+K,
+L,
+M,
+N,
+O,
+P,
+Q,
+R,
+S,
+T,
+U,
+V,
+W,
+X,
+Y,
+Z,
+Kb1,
+Kb2,
+Kb3,
+Kb4,
+Kb5,
+Kb6,
+Kb7,
+Kb8,
+Kb9,
+Kb0,
+Enter,
+Escape,
+BSpace,
+Tab,
+Space,
+Minus,
+Equal,
+LBracket,
+RBracket,
+Bslash,
+NonUsHash,
+SColon,
+Quote,
+Grave,
+Comma,
+Dot,
+Slash,
+CapsLock,
+F1,
+F2,
+F3,
+F4,
+F5,
+F6,
+F7,
+F8,
+F9,
+F10,
+F11,
+F12,
+PScreen,
+ScrollLock,
+Pause,
+Insert,
+Home,
+PgUp,
+Delete,
+End,
+PgDown,
+Right,
+Left,
+Down,
+Up,
+NumLock,
+KpSlash,
+KpAsterisk,
+KpMinus,
+KpPlus,
+KpEnter,
+Kp1,
+Kp2,
+Kp3,
+Kp4,
+Kp5,
+Kp6,
+Kp7,
+Kp8,
+Kp9,
+Kp0,
+KpDot,
+NonUsBslash,
+Application,
+Power,
+KpEqual,
+F13,
+F14,
+F15,
+F16,
+F17,
+F18,
+F19,
+F20,
+F21,
+F22,
+F23,
+F24,
+Execute,
+Help,
+Menu,
+Select,
+Stop,
+Again,
+Undo,
+Cut,
+Copy,
+Paste,
+Find,
+Mute,
+VolUp,
+VolDown,
+LockingCapsLock,
+LockingNumLock,
+LockingScrollLock,
+KpComma,
+KpEqualSign,
+Intl1,
+Intl2,
+Intl3,
+Intl4,
+Intl5,
+Intl6,
+Intl7,
+Intl8,
+Intl9,
+Lang1,
+Lang2,
+Lang3,
+Lang4,
+Lang5,
+Lang6,
+Lang7,
+Lang8,
+Lang9,
+AltErase,
+SysReq,
+Cancel,
+Clear,
+Prior,
+Return,
+Separator,
+Out,
+Oper,
+ClearAgain,
+CrSel,
+ExSel,
+Wakeup,
+BrightnessUp,
+BrightnessDown,
+KbdIllumUp,
+KbdIllumDown,
+K0xAA,
+K0xAB,
+K0xAC,
+K0xAD,
+K0xAE,
+K0xAF,
+K0xB0,
+K0xB1,
+K0xB2,
+K0xB3,
+K0xB4,
+K0xB5,
+K0xB6,
+K0xB7,
+K0xB8,
+K0xB9,
+K0xBA,
+K0xBB,
+K0xBC,
+K0xBD,
+K0xBE,
+K0xBF,
+K0xC0,
+K0xC1,
+K0xC2,
+K0xC3,
+K0xC4,
+K0xC5,
+K0xC6,
+K0xC7,
+K0xC8,
+K0xC9,
+K0xCA,
+K0xCB,
+K0xCC,
+K0xCD,
+K0xCE,
+K0xCF,
+K0xD0,
+K0xD1,
+K0xD2,
+K0xD3,
+K0xD4,
+K0xD5,
+K0xD6,
+K0xD7,
+K0xD8,
+K0xD9,
+K0xDA,
+K0xDB,
+K0xDC,
+K0xDD,
+K0xDE,
+K0xDF,
+LCtrl,
+LShift,
+LAlt,
+LGui,
+RCtrl,
+RShift,
+RAlt,
+RGui,
+MediaPlayPause,
+MediaStopCD,
+MediaPreviousSong,
+MediaNextSong,
+MediaEjectCD,
+MediaVolUp,
+MediaVolDown,
+MediaMute,
+MediaWWW,
+MediaBack,
+MediaForward,
+MediaStop,
+MediaFind,
+MediaScrollUp,
+MediaScrollDown,
+MediaEdit,
+MediaSleep,
+MediaCoffee,
+MediaRefresh,
+MediaCalc,
+K252,
+K253,
+K254,
+K255,
+K256,
+K257,
+K258,
+K259,
+K260,
+K261,
+K262,
+K263,
+K264,
+K265,
+K266,
+K267,
+K268,
+K269,
+K270,
+K271,
+K272,
+K273,
+K274,
+K275,
+K276,
+K277,
+K278,
+K279,
+K280,
+K281,
+K282,
+K283,
+K284,
+K285,
+K286,
+K287,
+K288,
+K289,
+K290,
+K291,
+K292,
+K293,
+K294,
+K295,
+K296,
+K297,
+K298,
+K299,
+K300,
+K301,
+K302,
+K303,
+K304,
+K305,
+K306,
+K307,
+K308,
+K309,
+K310,
+K311,
+K312,
+K313,
+K314,
+K315,
+K316,
+K317,
+K318,
+K319,
+K320,
+K321,
+K322,
+K323,
+K324,
+K325,
+K326,
+K327,
+K328,
+K329,
+K330,
+K331,
+K332,
+K333,
+K334,
+K335,
+K336,
+K337,
+K338,
+K339,
+K340,
+K341,
+K342,
+K343,
+K344,
+K345,
+K346,
+K347,
+K348,
+K349,
+K350,
+K351,
+K352,
+K353,
+K354,
+K355,
+K356,
+K357,
+K358,
+K359,
+K360,
+K361,
+K362,
+K363,
+K364,
+K365,
+K366,
+K367,
+K368,
+K369,
+K370,
+K371,
+K372,
+K373,
+K374,
+K375,
+K376,
+K377,
+K378,
+K379,
+K380,
+K381,
+K382,
+K383,
+K384,
+K385,
+K386,
+K387,
+K388,
+K389,
+K390,
+K391,
+K392,
+K393,
+K394,
+K395,
+K396,
+K397,
+K398,
+K399,
+K400,
+K401,
+K402,
+K403,
+K404,
+K405,
+K406,
+K407,
+K408,
+K409,
+K410,
+K411,
+K412,
+K413,
+K414,
+K415,
+K416,
+K417,
+K418,
+K419,
+K420,
+K421,
+K422,
+K423,
+K424,
+K425,
+K426,
+K427,
+K428,
+K429,
+K430,
+K431,
+K432,
+K433,
+K434,
+K435,
+K436,
+K437,
+K438,
+K439,
+K440,
+K441,
+K442,
+K443,
+K444,
+K445,
+K446,
+K447,
+K448,
+K449,
+K450,
+K451,
+K452,
+K453,
+K454,
+K455,
+K456,
+K457,
+K458,
+K459,
+K460,
+K461,
+K462,
+K463,
+K464,
+K465,
+K466,
+K467,
+K468,
+K469,
+K470,
+K471,
+K472,
+K473,
+K474,
+K475,
+K476,
+K477,
+K478,
+K479,
+K480,
+K481,
+K482,
+K483,
+K484,
+K485,
+K486,
+K487,
+K488,
+K489,
+K490,
+K491,
+K492,
+K493,
+K494,
+K495,
+K496,
+K497,
+K498,
+K499,
+K500,
+K501,
+K502,
+K503,
+K504,
+K505,
+K506,
+K507,
+K508,
+K509,
+K510,
+K511,
+K512,
+K513,
+K514,
+K515,
+K516,
+K517,
+K518,
+K519,
+K520,
+K521,
+K522,
+K523,
+K524,
+K525,
+K526,
+K527,
+K528,
+K529,
+K530,
+K531,
+K532,
+K533,
+K534,
+K535,
+K536,
+K537,
+K538,
+K539,
+K540,
+K541,
+K542,
+K543,
+K544,
+K545,
+K546,
+K547,
+K548,
+K549,
+K550,
+K551,
+K552,
+K553,
+K554,
+K555,
+K556,
+K557,
+K558,
+K559,
+K560,
+K561,
+K562,
+K563,
+K564,
+K565,
+K566,
+K567,
+K568,
+K569,
+K570,
+K571,
+K572,
+K573,
+K574,
+K575,
+K576,
+K577,
+K578,
+K579,
+K580,
+K581,
+K582,
+K583,
+K584,
+K585,
+K586,
+K587,
+K588,
+K589,
+K590,
+K591,
+K592,
+K593,
+K594,
+K595,
+K596,
+K597,
+K598,
+K599,
+K600,
+K601,
+K602,
+K603,
+K604,
+K605,
+K606,
+K607,
+K608,
+K609,
+K610,
+K611,
+K612,
+K613,
+K614,
+K615,
+K616,
+K617,
+K618,
+K619,
+K620,
+K621,
+K622,
+K623,
+K624,
+K625,
+K626,
+K627,
+K628,
+K629,
+K630,
+K631,
+K632,
+K633,
+K634,
+K635,
+K636,
+K637,
+K638,
+K639,
+K640,
+K641,
+K642,
+K643,
+K644,
+K645,
+K646,
+K647,
+K648,
+K649,
+K650,
+K651,
+K652,
+K653,
+K654,
+K655,
+K656,
+K657,
+K658,
+K659,
+K660,
+K661,
+K662,
+K663,
+K664,
+K665,
+K666,
+K667,
+K668,
+K669,
+K670,
+K671,
+K672,
+K673,
+K674,
+K675,
+K676,
+K677,
+K678,
+K679,
+K680,
+K681,
+K682,
+K683,
+K684,
+K685,
+K686,
+K687,
+K688,
+K689,
+K690,
+K691,
+K692,
+K693,
+K694,
+K695,
+K696,
+K697,
+K698,
+K699,
+K700,
+K701,
+K702,
+K703,
+K704,
+K705,
+K706,
+K707,
+K708,
+K709,
+K710,
+K711,
+K712,
+K713,
+K714,
+K715,
+K716,
+K717,
+K718,
+K719,
+K720,
+K721,
+K722,
+K723,
+K724,
+K725,
+K726,
+K727,
+K728,
+K729,
+K730,
+K731,
+K732,
+K733,
+K734,
+K735,
+K736,
+K737,
+K738,
+K739,
+K740,
+K741,
+K742,
+K743,
+K744,
+MWU,
+MWD,
+MWL,
+MWR,
+KeyMax,
diff --git a/key-sort-add/src/main.rs b/key-sort-add/src/main.rs
index bea45dbd3..648d4696c 100644
--- a/key-sort-add/src/main.rs
+++ b/key-sort-add/src/main.rs
@@ -1,3 +1,5 @@
+//! one:
+//!
 //! Takes a file formatted as:
 //!
 //!     KEY_RESERVED = 0,
@@ -11,11 +13,21 @@
 //! Outputs to stdout a sorted version of the file with numeric gaps filled in with:
 //!
 //!     KEY_X = X,
+//!
+//! two: mapping.txt to ensure KeyCode and OsCode can simply be transmuted into each other.
 
 use std::io::Read;
 
 fn main() {
-    let mut f = std::fs::File::open(std::env::args().nth(1).expect("filename parameter"))
+    match std::env::args().nth(1).expect("function parameter").as_str() {
+        "one" => one(),
+        "two" => two(),
+        _ => panic!("unknown capabality"),
+    }
+}
+
+fn one() {
+    let mut f = std::fs::File::open(std::env::args().nth(2).expect("filename parameter"))
         .expect("file open");
     let mut s = String::new();
     f.read_to_string(&mut s).expect("read file");
@@ -24,7 +36,14 @@ fn main() {
         .map(|l| {
             let mut segments = l.trim_end_matches(',').trim().split(" = ");
             let key = segments.next().expect("a string");
-            let num: u16 = str::parse(segments.next().expect("string after =")).expect("u16");
+            let num: u16 = u16::from_str_radix(
+                segments
+                    .next()
+                    .map(|s| s.trim_start_matches("0x"))
+                    .expect("string after ="),
+                10,
+            )
+            .expect("u16");
             (key.to_owned(), num)
         })
         .collect::<Vec<_>>();
@@ -36,7 +55,7 @@ fn main() {
     for cur in cur_key {
         let prev = prev_key.next().expect("lagging iterator is valid");
         for missing in prev.1 + 1..cur.1 {
-            keys_to_add.push((format!("KEY_{missing}"), missing));
+            keys_to_add.push((format!("K{missing}"), missing));
         }
     }
     keys.append(&mut keys_to_add);
@@ -45,3 +64,67 @@ fn main() {
         println!("{} = {},", key.0, key.1);
     }
 }
+
+fn two() {
+    use std::collections::HashMap;
+
+    let mut f = std::fs::File::open(std::env::args().nth(2).expect("filename parameter"))
+        .expect("file open");
+    let mut s = String::new();
+    f.read_to_string(&mut s).expect("read file");
+    let mut lines = s.lines();
+
+    // filter out useless lines
+    while let Some(line) = lines.next() {
+        if line == "=== kc to osc" {
+            break;
+        }
+    }
+
+    // parse kc to osc
+    let mut kc_to_osc: HashMap<&str, &str> = HashMap::new();
+    while let Some(line) = lines.next() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        if line == "=== osc to u16" {
+            break;
+        }
+        let (kc, osc) = line.split_once(" => ").expect("arrow separator");
+        let kc = kc.trim_start_matches("KeyCode::");
+        let osc = osc.trim_end_matches(',')
+                .trim_start_matches("OsCode::");
+        kc_to_osc.insert(kc, osc);
+    }
+
+    // parse osc to u16
+    let mut osc_vals: HashMap<&str, u16> = HashMap::new();
+    while let Some(line) = lines.next() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        if line == "=== all kcs" {
+            break;
+        }
+        let (kc, num) = line.split_once(" = ").expect("equal separator");
+        let num = num.trim_end_matches(',').parse::<u16>().expect("u16");
+        osc_vals.insert(kc, num);
+    }
+
+    // parse kcs
+    let mut kc_vals: Vec<(&str, Option<u16>)> = vec![];
+    while let Some(line) = lines.next() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let kc = line.trim_end_matches(',');
+        let val: Option<u16> = kc_to_osc.get(&kc)
+            .and_then(|osc| osc_vals.get(osc))
+            .copied();
+        kc_vals.push((kc, val));
+    }
+
+    for (kc, val) in kc_vals.iter() {
+        println!("{kc} = {},", val.unwrap_or(65535));
+    }
+}
diff --git a/keyberon/Cargo.toml b/keyberon/Cargo.toml
index 9ea485711..df47423d9 100644
--- a/keyberon/Cargo.toml
+++ b/keyberon/Cargo.toml
@@ -1,8 +1,8 @@
 [package]
 name = "kanata-keyberon"
-version = "0.18.0"
+version = "0.1120.1"
 authors = ["Guillaume Pinot <texitoi@texitoi.eu>", "Robin Krahl <robin.krahl@ireas.org>", "jtroo <j.andreitabs@gmail.com>"]
-edition = "2018"
+edition = "2021"
 description = "Pure Rust keyboard firmware. Fork intended for use with kanata."
 documentation = "https://docs.rs/keyberon"
 repository = "https://github.com/TeXitoi/keyberon"
@@ -11,7 +11,11 @@ categories = ["no-std"]
 license = "MIT"
 readme = "README.md"
 
+[features]
+tap_hold_tracker = []
+
 [dependencies]
 kanata-keyberon-macros = { version = "0.2.0" }
 heapless = "0.7.16"
-arraydeque = { version = "0.4.5", default-features = false }
+rustc-hash = "1.1.0"
+arraydeque = { version = "0.5.1", default-features = false }
diff --git a/keyberon/README.md b/keyberon/README.md
index fc9c66ca7..72cd51939 100644
--- a/keyberon/README.md
+++ b/keyberon/README.md
@@ -4,3 +4,5 @@
 
 This is a fork intended for use by the [kanata keyboard remapper software](https://github.com/jtroo/kanata).
 Please make contributions to the [original project](https://github.com/TeXitoi/keyberon) where applicable.
+
+This crate does not follow semver. It tracks the version of kanata.
diff --git a/keyberon/src/action.rs b/keyberon/src/action.rs
index 004c88184..6f52f27ac 100644
--- a/keyberon/src/action.rs
+++ b/keyberon/src/action.rs
@@ -1,9 +1,12 @@
 //! The different actions that can be executed via any given key.
 
 use crate::key_code::KeyCode;
-use crate::layout::{QueuedIter, WaitingAction};
+use crate::layout::{KCoord, QueuedIter, WaitingAction};
 use core::fmt::Debug;
 
+pub mod switch;
+pub use switch::*;
+
 /// The different types of actions we support for key sequences/macros
 #[non_exhaustive]
 #[derive(Clone, Copy, Eq, PartialEq)]
@@ -28,7 +31,7 @@ pub enum SequenceEvent<'a, T: 'a> {
     Complete,
 }
 
-impl<'a, T> Debug for SequenceEvent<'a, T> {
+impl<T> Debug for SequenceEvent<'_, T> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             Self::NoOp => write!(f, "NoOp"),
@@ -58,6 +61,13 @@ pub enum HoldTapConfig<'a> {
     /// not used in the flow of typing, like escape for example. If
     /// you are annoyed by accidental tap, you can try this behavior.
     HoldOnOtherKeyPress,
+    /// Resolves based on release order after both keys are down.
+    /// If the other key releases first (modifier still held) → Hold.
+    /// If the modifier releases first (other key still held) → Tap.
+    /// The buffer field specifies a grace period in ticks (ms) after the
+    /// initial press during which release-order logic is ignored and fast
+    /// typing will resolve as Tap.
+    Order { buffer: u16 },
     /// If there is a press and release of another key, the hold
     /// action is activated.
     ///
@@ -69,11 +79,15 @@ pub enum HoldTapConfig<'a> {
     /// A custom configuration. Allows the behavior to be controlled by a caller
     /// supplied handler function.
     ///
-    /// The input to the custom handler will be an iterator that returns
+    /// The first argument to the custom handler will be an iterator that returns
     /// [Stacked] [Events](Event). The order of the events matches the order the
     /// corresponding key was pressed/released, i.e. the first event is the
     /// event first received after the HoldTap action key is pressed.
     ///
+    /// The second argument is the coordinate `(row, col)` of the key that
+    /// initiated the HoldTap action, allowing the handler to identify which
+    /// physical key is waiting for resolution.
+    ///
     /// The return value should be the intended action that should be used. A
     /// [Some] value will cause one of: [WaitingAction::Tap] for the configured
     /// tap action, [WaitingAction::Hold] for the hold action, and
@@ -81,27 +95,33 @@ pub enum HoldTapConfig<'a> {
     /// value will cause a fallback to the timeout-based approach. If the
     /// timeout is not triggered, the next tick will call the custom handler
     /// again.
-    Custom(&'a (dyn Fn(QueuedIter) -> Option<WaitingAction> + Send + Sync)),
+    /// The bool value defines if the timeout check should be skipped at the
+    /// next tick. This should generally be false. This is used by `tap-hold-
+    /// except-keys` to handle presses even when the timeout has been reached.
+    #[allow(clippy::type_complexity)]
+    Custom(&'a (dyn Fn(QueuedIter, KCoord) -> (Option<WaitingAction>, bool) + Send + Sync)),
 }
 
-impl<'a> Debug for HoldTapConfig<'a> {
+impl Debug for HoldTapConfig<'_> {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             HoldTapConfig::Default => f.write_str("Default"),
             HoldTapConfig::HoldOnOtherKeyPress => f.write_str("HoldOnOtherKeyPress"),
+            HoldTapConfig::Order { .. } => f.write_str("Order"),
             HoldTapConfig::PermissiveHold => f.write_str("PermissiveHold"),
             HoldTapConfig::Custom(_) => f.write_str("Custom"),
         }
     }
 }
 
-impl<'a> PartialEq for HoldTapConfig<'a> {
+impl PartialEq for HoldTapConfig<'_> {
     fn eq(&self, other: &Self) -> bool {
         #[allow(clippy::match_like_matches_macro)]
         match (self, other) {
             (HoldTapConfig::Default, HoldTapConfig::Default)
             | (HoldTapConfig::HoldOnOtherKeyPress, HoldTapConfig::HoldOnOtherKeyPress)
             | (HoldTapConfig::PermissiveHold, HoldTapConfig::PermissiveHold) => true,
+            (HoldTapConfig::Order { .. }, HoldTapConfig::Order { .. }) => true,
             _ => false,
         }
     }
@@ -161,6 +181,15 @@ where
     ///
     /// To deactivate the functionality, set this to 0.
     pub tap_hold_interval: u16,
+    /// Specifically the `tap-hold-release-timeout` action variant
+    /// can benefit from resetting the timeout after a new press,
+    /// because a human might have a slow release but they did
+    /// indeed want a hold to activate.
+    pub on_press_reset_timeout_to: Option<std::num::NonZeroU16>,
+    /// Per-action override for the global `tap_hold_require_prior_idle` setting.
+    /// If `Some(n)`, uses `n` instead of the global value (0 = disabled for this action).
+    /// If `None`, falls back to the global `defcfg` value.
+    pub require_prior_idle: Option<u16>,
 }
 
 /// Define one shot key behaviour.
@@ -276,7 +305,7 @@ impl<'a, T> ChordsGroup<'a, T> {
 /// A set of virtual keys (represented as a bit mask) pressed together.
 /// The keys do not directly correspond to physical keys. They are unique to a given [ChordGroup] and their mapping from physical keys is definied in [ChordGroup.coords].
 /// As such, each chord group can effectively have at most 32 different keys (though multiple physical keys may be mapped to the same virtual key).
-pub type ChordKeys = u32;
+pub type ChordKeys = u128;
 
 /// Defines the maximum number of (virtual) keys that can be used in a single chords group.
 pub const MAX_CHORD_KEYS: usize = ChordKeys::BITS as usize;
@@ -352,6 +381,8 @@ where
     /// key will hold space until either another key is pressed or the timeout occurs, which will
     /// probably send many undesired space characters to your active application.
     OneShot(&'a OneShot<'a, T>),
+    /// An action to ignore processing of events for OneShot.
+    OneShotIgnoreEventsTicks(u16),
     /// Tap-dance key. When tapping the key N times in quck succession, activates the N'th action
     /// in `actions`. The action will activate in the following conditions:
     ///
@@ -373,9 +404,18 @@ where
     /// Fork action that can activate one of two potential actions depending on what keys are
     /// currently active.
     Fork(&'a ForkConfig<'a, T>),
+    /// Action that can activate 0 to N actions based on what keys are currently
+    /// active and the boolean logic of each case.
+    ///
+    /// The maximum number of actions that can activate the same time is governed by
+    /// `ACTION_QUEUE_LEN`.
+    Switch(&'a Switch<'a, T>),
+    /// Disregard the entire layer stack, i.e. the current base layer and any while-held layers,
+    /// and select the action from `Layout.src_keys`.
+    Src,
 }
 
-impl<'a, T> Action<'a, T> {
+impl<T> Action<'_, T> {
     /// Gets the layer number if the action is the `Layer` action.
     pub fn layer(self) -> Option<usize> {
         match self {
diff --git a/keyberon/src/action/switch.rs b/keyberon/src/action/switch.rs
new file mode 100644
index 000000000..54eb13429
--- /dev/null
+++ b/keyberon/src/action/switch.rs
@@ -0,0 +1,1539 @@
+//! Handle processing of the switch action for Keyberon.
+//!
+//! Limitations:
+//! - Maximum opcode length: 4095
+//! - Maximum boolean expression depth: 8
+//! - Maximum key recency: 7, where 0 is the most recent key press
+//!
+//! The intended use is to build up a `Switch` struct and use that in the `Layout`.
+//!
+//! The `Layout` will use `Switch::actions` to iterate over the actions that should be activated
+//! when the corresponding key is pressed.
+
+use super::*;
+use crate::layout::{HistoricalEvent, KCoord};
+
+use crate::key_code::*;
+use std::num::NonZeroU8;
+
+use BooleanOperator::*;
+use BreakOrFallthrough::*;
+
+pub const MAX_OPCODE_LEN: u16 = 0x0FFF;
+pub const OP_MASK: u16 = 0xF000;
+pub const MAX_BOOL_EXPR_DEPTH: usize = 8;
+pub const MAX_KEY_RECENCY: u8 = 7;
+
+pub type Case<'a, T> = (&'a [OpCode], &'a Action<'a, T>, BreakOrFallthrough);
+
+#[derive(Clone, Copy)]
+/// Behaviour of a switch action. Each case is a 3-tuple of:
+///
+/// - the boolean expression (array of opcodes)
+/// - the action to evaluate if the expression evaluates to true
+/// - whether to break or fallthrough to the next case if the expression evaluates to true
+pub struct Switch<'a, T: 'a> {
+    // A callback to optionally initialize some state for this switch.
+    pub init_fn: Option<&'a (dyn Fn() + Send + Sync)>,
+    pub cases: &'a [Case<'a, T>],
+    // Extra callbacks that can be indexed into to evaluate functions,
+    // e.g. based on state updated by init_fn.
+    pub callbacks: &'a [&'a (dyn Fn() -> bool + Send + Sync)],
+}
+
+impl<'a, T: 'a + PartialEq> PartialEq for Switch<'a, T> {
+    fn eq(&self, other: &Self) -> bool {
+        self.cases == other.cases
+    }
+}
+
+impl<'a, T: 'a + Debug> Debug for Switch<'a, T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
+        f.debug_struct("Switch")
+            .field("cases", &self.cases)
+            .field("init_is_some", &self.init_fn.is_some())
+            .field("callbacks_len", &self.callbacks.len())
+            .finish()
+    }
+}
+
+// NOTE: have exhausted our opcodes for u16!
+//
+// Future rewrite: do traditional u8 opcodes, with variable length for the total opcode depending
+// on the first one encountered? Or could be lazy and use u32 and have 4 bytes for every opcode.
+// This probably isn't that performance-sensitive anyway... it's triggering on every input.
+
+const OR_VAL: u16 = 0x1000;
+const AND_VAL: u16 = 0x2000;
+const NOT_VAL: u16 = 0x3000;
+
+const INPUT_VAL: u16 = 851;
+const HISTORICAL_INPUT_VAL: u16 = 852;
+const LAYER_VAL: u16 = 853;
+const BASE_LAYER_VAL: u16 = 854;
+const HISTORICAL_DEVICE_VAL: u16 = 855;
+const CALLBACK_INDEX_VAL: u16 = 856;
+
+// Binary values:
+// 0b0100 ...
+// 0b0110 ...
+//
+// How-far-back are in bits 12-10 (3 bits)
+// Time is compressed in bits 9-0 (10 bits)
+const TICKS_SINCE_VAL_GT: u16 = 0x4000;
+const TICKS_SINCE_VAL_LT: u16 = 0x6000;
+
+// Highest bit in u16. Lower 3 bits in the highest nibble are "how far back". This means that
+// switch can look back up to 8 keys.
+const HISTORICAL_KEYCODE_VAL: u16 = 0x8000;
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// Boolean operator. Notably missing today is Not.
+pub enum BooleanOperator {
+    Or,
+    And,
+    Not,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
+/// OpCode for a switch case boolean expression.
+pub struct OpCode(u16);
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The more useful interpretion of an OpCode.
+enum OpCodeType {
+    BooleanOp(OperatorAndEndIndex),
+    KeyCode(u16),
+    HistoricalKeyCode(HistoricalKeyCode),
+    Input(KCoord),
+    HistoricalInput(HistoricalInput),
+    TicksSinceLessThan(TicksSinceNthKey),
+    TicksSinceGreaterThan(TicksSinceNthKey),
+    Layer(u16),
+    BaseLayer(u16),
+    HistoricalDevice(HistoricalDevice),
+    CallbackIndex(u16),
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The operation type and the opcode index at which evaluating this type ends.
+struct OperatorAndEndIndex {
+    pub op: BooleanOperator,
+    pub idx: usize,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// An op that checks specifically for a key that is a certain number of key presses back in
+/// history.
+struct HistoricalKeyCode {
+    key_code: u16,
+    how_far_back: u8,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// An op that checks specifically for a key that is a certain number of key presses back in
+/// history.
+struct HistoricalInput {
+    input: KCoord,
+    how_far_back: u8,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+struct HistoricalDevice {
+    device_id: NonZeroU8,
+    how_far_back: u8,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+struct TicksSinceNthKey {
+    nth_key: u8,
+    ticks_since: u16,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq)]
+/// Whether or not a case should break out of the switch if it evaluates to true or fallthrough to
+/// the next case.
+pub enum BreakOrFallthrough {
+    Break,
+    Fallthrough,
+}
+
+impl<'a, T> Switch<'a, T> {
+    /// Iterates over the actions (if any) that are activated in the `Switch` based on its cases,
+    /// the currently active keys, and historically pressed keys.
+    ///
+    /// The `historical_keys` parameter should iterate in the order of most-recent-first.
+    #[allow(clippy::too_many_arguments)]
+    pub fn actions<A1, A2, H1, H2, L, D>(
+        &self,
+        active_keys: A1,
+        active_positions: A2,
+        historical_keys: H1,
+        historical_positions: H2,
+        layers: L,
+        default_layer: u16,
+        device_history: D,
+    ) -> SwitchActions<'a, T, A1, A2, H1, H2, L, D>
+    where
+        A1: Iterator<Item = KeyCode> + Clone,
+        A2: Iterator<Item = KCoord> + Clone,
+        H1: Iterator<Item = HistoricalEvent<KeyCode>> + Clone,
+        H2: Iterator<Item = HistoricalEvent<KCoord>> + Clone,
+        L: Iterator<Item = u16> + Clone,
+        D: Iterator<Item = Option<NonZeroU8>> + Clone,
+    {
+        SwitchActions {
+            cases: self.cases,
+            active_keys,
+            active_positions,
+            historical_keys,
+            historical_positions,
+            layers,
+            default_layer,
+            device_history,
+            case_index: 0,
+            callbacks: self.callbacks,
+        }
+    }
+}
+
+#[derive(Clone)]
+/// Iterator returned by `Switch::actions`.
+pub struct SwitchActions<'a, T, A1, A2, H1, H2, L, D>
+where
+    A1: Iterator<Item = KeyCode> + Clone,
+    A2: Iterator<Item = KCoord> + Clone,
+    H1: Iterator<Item = HistoricalEvent<KeyCode>> + Clone,
+    H2: Iterator<Item = HistoricalEvent<KCoord>> + Clone,
+    L: Iterator<Item = u16> + Clone,
+    D: Iterator<Item = Option<NonZeroU8>> + Clone,
+{
+    cases: &'a [(&'a [OpCode], &'a Action<'a, T>, BreakOrFallthrough)],
+    active_keys: A1,
+    active_positions: A2,
+    historical_keys: H1,
+    historical_positions: H2,
+    layers: L,
+    default_layer: u16,
+    device_history: D,
+    case_index: usize,
+    callbacks: &'a [&'a (dyn Fn() -> bool + Send + Sync)],
+}
+
+impl<'a, T, A1, A2, H1, H2, L, D> Iterator for SwitchActions<'a, T, A1, A2, H1, H2, L, D>
+where
+    A1: Iterator<Item = KeyCode> + Clone,
+    A2: Iterator<Item = KCoord> + Clone,
+    H1: Iterator<Item = HistoricalEvent<KeyCode>> + Clone,
+    H2: Iterator<Item = HistoricalEvent<KCoord>> + Clone,
+    L: Iterator<Item = u16> + Clone,
+    D: Iterator<Item = Option<NonZeroU8>> + Clone,
+{
+    type Item = &'a Action<'a, T>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        while self.case_index < self.cases.len() {
+            let case = &self.cases[self.case_index];
+            if evaluate_boolean(
+                case.0,
+                self.active_keys.clone(),
+                self.active_positions.clone(),
+                self.historical_keys.clone(),
+                self.historical_positions.clone(),
+                self.layers.clone(),
+                self.default_layer,
+                self.device_history.clone(),
+                self.callbacks,
+            ) {
+                let ret_ac = case.1;
+                match case.2 {
+                    Break => self.case_index = self.cases.len(),
+                    Fallthrough => self.case_index += 1,
+                }
+                return Some(ret_ac);
+            }
+            self.case_index += 1;
+        }
+        None
+    }
+}
+
+impl BooleanOperator {
+    fn to_u16(self) -> u16 {
+        match self {
+            Or => OR_VAL,
+            And => AND_VAL,
+            Not => NOT_VAL,
+        }
+    }
+}
+fn lossy_compress_ticks(t: u16) -> u16 {
+    match t {
+        0..=255 => t,
+        256..=2303 => (t - 255) / 8 + 255,
+        _ => (t - 2303) / 128 + 511,
+    }
+}
+
+fn lossy_decompress_ticks(t: u16) -> u16 {
+    match t {
+        0..=255 => t,
+        256..=511 => (t - 255) * 8 + 255,
+        _ => (t - 511) * 128 + 2303,
+    }
+}
+
+impl OpCode {
+    /// Return a new OpCode that checks if the key active or not.
+    pub fn new_key(kc: KeyCode) -> Self {
+        assert!((kc as u16) <= KEY_MAX);
+        Self(kc as u16 & MAX_OPCODE_LEN)
+    }
+
+    /// Return a new OpCode that checks if the n'th most recent key, defined by `key_recency`,
+    /// matches the input keycode.
+    pub fn new_key_history(kc: KeyCode, key_recency: u8) -> Self {
+        assert!((kc as u16) <= MAX_OPCODE_LEN);
+        assert!(key_recency <= MAX_KEY_RECENCY);
+        Self((kc as u16 & MAX_OPCODE_LEN) | HISTORICAL_KEYCODE_VAL | ((key_recency as u16) << 12))
+    }
+
+    /// Returns a new opcode that returns true if the n'th most recent key was pressed greater
+    /// than `ticks_since` ticks ago.
+    ///
+    /// At 256 ticks or above, this has a resolution of 8ms (rounded down). At 2304 ticks or
+    /// above, this has a resolution of 128 ms (rounded down).
+    pub fn new_ticks_since_gt(nth_key: u8, ticks_since: u16) -> Self {
+        assert!(nth_key <= MAX_KEY_RECENCY);
+        Self(TICKS_SINCE_VAL_GT | lossy_compress_ticks(ticks_since) | (u16::from(nth_key) << 10))
+    }
+
+    /// Returns a new opcode that returns true if the n'th most recent key was pressed greater
+    /// than `ticks_since` ticks ago.
+    ///
+    /// At 256 ticks or above, this has a resolution of 8ms (rounded down). At 2304 ticks or
+    /// above, this has a resolution of 128 ms (rounded down).
+    pub fn new_ticks_since_lt(nth_key: u8, ticks_since: u16) -> Self {
+        assert!(nth_key <= MAX_KEY_RECENCY);
+        Self(TICKS_SINCE_VAL_LT | lossy_compress_ticks(ticks_since) | (u16::from(nth_key) << 10))
+    }
+
+    /// Return a new OpCode for a boolean operation that ends (non-inclusive) at the specified
+    /// index.
+    pub fn new_bool(op: BooleanOperator, end_idx: u16) -> Self {
+        assert!(end_idx <= MAX_OPCODE_LEN);
+        Self((end_idx & MAX_OPCODE_LEN) + op.to_u16())
+    }
+
+    /// Return OpCodes specifying an active input check.
+    pub fn new_active_input(input: KCoord) -> (Self, Self) {
+        assert!(input.0 < 4);
+        assert!(input.1 < 0x0400);
+        (
+            Self(INPUT_VAL),
+            Self((u16::from(input.0 & 3) << 14) + input.1),
+        )
+    }
+
+    /// Return OpCodes specifying an active input check.
+    pub fn new_historical_input(input: KCoord, key_recency: u8) -> (Self, Self) {
+        assert!(input.0 < 4);
+        assert!(input.1 < 0x0400);
+        assert!(key_recency < 0x8);
+        (
+            Self(HISTORICAL_INPUT_VAL),
+            Self((u16::from(input.0 & 3) << 14) + (u16::from(key_recency) << 11) + input.1),
+        )
+    }
+
+    /// Return OpCodes specifying an active layer check.
+    pub fn new_layer(layer: u16) -> (Self, Self) {
+        assert!(usize::from(layer) < crate::layout::MAX_LAYERS);
+        (Self(LAYER_VAL), Self(layer))
+    }
+
+    /// Return OpCodes specifying an base layer check.
+    pub fn new_base_layer(base_layer: u16) -> (Self, Self) {
+        assert!(usize::from(base_layer) < crate::layout::MAX_LAYERS);
+        (Self(BASE_LAYER_VAL), Self(base_layer))
+    }
+
+    /// Return OpCodes specifying a device history check.
+    pub fn new_device_history(id: NonZeroU8, how_far_back: u8) -> (Self, Self) {
+        assert!(how_far_back <= MAX_KEY_RECENCY);
+        (
+            Self(HISTORICAL_DEVICE_VAL),
+            Self(id.get() as u16 | ((how_far_back as u16) << 8)),
+        )
+    }
+
+    /// Returns OpCodes specifying a callback, referenced by index.
+    pub fn new_callback_index(index: u16) -> (Self, Self) {
+        (Self(CALLBACK_INDEX_VAL), Self(index))
+    }
+
+    /// Return the interpretation of this `OpCode`.
+    fn opcode_type(self, next: Option<OpCode>) -> OpCodeType {
+        if self.0 < KEY_MAX {
+            OpCodeType::KeyCode(self.0)
+        } else if self.0 <= MAX_OPCODE_LEN {
+            let op2 = next.expect("next should be some for opcode {self:?}");
+            match self.0 {
+                INPUT_VAL => OpCodeType::Input((((op2.0 >> 14) & 0x3) as u8, op2.0 & 0x3FF)),
+                HISTORICAL_INPUT_VAL => OpCodeType::HistoricalInput(HistoricalInput {
+                    input: (((op2.0 >> 14) & 0x3) as u8, op2.0 & 0x3FF),
+                    how_far_back: (op2.0 >> 11) as u8 & 0x7,
+                }),
+                LAYER_VAL => OpCodeType::Layer(op2.0),
+                BASE_LAYER_VAL => OpCodeType::BaseLayer(op2.0),
+                HISTORICAL_DEVICE_VAL => OpCodeType::HistoricalDevice(HistoricalDevice {
+                    device_id: NonZeroU8::new((op2.0 & 0xFF) as u8)
+                        .expect("device ID must be nonzero"),
+                    how_far_back: ((op2.0 >> 8) & 0x7) as u8,
+                }),
+                CALLBACK_INDEX_VAL => OpCodeType::CallbackIndex(op2.0),
+                _ => unreachable!("unexpected opcode {self:?}"),
+            }
+        } else {
+            match self.0 & 0xE000 {
+                TICKS_SINCE_VAL_LT => OpCodeType::TicksSinceLessThan(TicksSinceNthKey {
+                    nth_key: ((self.0 & 0x1C00) >> 10) as u8,
+                    ticks_since: lossy_decompress_ticks(self.0 & 0x03FF),
+                }),
+                TICKS_SINCE_VAL_GT => OpCodeType::TicksSinceGreaterThan(TicksSinceNthKey {
+                    nth_key: ((self.0 & 0x1C00) >> 10) as u8,
+                    ticks_since: lossy_decompress_ticks(self.0 & 0x03FF),
+                }),
+                0x8000..=0xF000 => OpCodeType::HistoricalKeyCode(HistoricalKeyCode {
+                    key_code: self.0 & 0x0FFF,
+                    how_far_back: ((self.0 & 0x7000) >> 12) as u8,
+                }),
+                _ => OpCodeType::BooleanOp(OperatorAndEndIndex::from(self.0)),
+            }
+        }
+    }
+}
+
+impl From<u16> for OperatorAndEndIndex {
+    fn from(value: u16) -> Self {
+        Self {
+            op: match value & OP_MASK {
+                OR_VAL => Or,
+                AND_VAL => And,
+                NOT_VAL => Not,
+                _ => unreachable!("public interface should protect from this"),
+            },
+            idx: usize::from(value & MAX_OPCODE_LEN),
+        }
+    }
+}
+
+/// Evaluate the return value of an expression evaluated on the given key codes.
+#[allow(clippy::too_many_arguments)]
+fn evaluate_boolean(
+    bool_expr: &[OpCode],
+    key_codes: impl Iterator<Item = KeyCode> + Clone,
+    inputs: impl Iterator<Item = KCoord> + Clone,
+    historical_keys: impl Iterator<Item = HistoricalEvent<KeyCode>> + Clone,
+    historical_inputs: impl Iterator<Item = HistoricalEvent<KCoord>> + Clone,
+    layers: impl Iterator<Item = u16> + Clone,
+    default_layer: u16,
+    device_history: impl Iterator<Item = Option<NonZeroU8>> + Clone,
+    callbacks: &[&(dyn Fn() -> bool + Send + Sync)],
+) -> bool {
+    let mut ret = true;
+    let mut current_index = 0;
+    let mut current_end_index = bool_expr.len();
+    let mut current_op = Or;
+    let mut stack: arraydeque::ArrayDeque<
+        OperatorAndEndIndex,
+        MAX_BOOL_EXPR_DEPTH,
+        arraydeque::behavior::Saturating,
+    > = Default::default();
+    while current_index < bool_expr.len() {
+        if current_index >= current_end_index {
+            match stack.pop_back() {
+                Some(operator) => {
+                    (current_op, current_end_index) = (operator.op, operator.idx);
+                }
+                None => break,
+            }
+            // Short-circuiting logic
+            if matches!((ret, current_op), (true, Or | Not) | (false, And))
+                || current_index >= current_end_index
+            {
+                if current_op == Not {
+                    ret = !ret;
+                }
+                current_index = current_end_index;
+                continue;
+            }
+        }
+        match bool_expr[current_index].opcode_type(bool_expr.get(current_index + 1).copied()) {
+            OpCodeType::BooleanOp(operator) => {
+                let res = stack.push_back(OperatorAndEndIndex {
+                    op: current_op,
+                    idx: current_end_index,
+                });
+                assert!(
+                    res.is_ok(),
+                    "exceeded boolean op depth {MAX_BOOL_EXPR_DEPTH}"
+                );
+                (current_op, current_end_index) = (operator.op, operator.idx);
+                current_index += 1;
+                continue;
+            }
+            OpCodeType::KeyCode(kc) => {
+                ret = key_codes.clone().any(|kc_input| kc_input as u16 == kc);
+            }
+            OpCodeType::HistoricalKeyCode(hkc) => {
+                ret = historical_keys
+                    .clone()
+                    .nth(hkc.how_far_back as usize)
+                    .map(|he| he.event as u16 == hkc.key_code)
+                    .unwrap_or(false);
+            }
+            OpCodeType::TicksSinceLessThan(tsnk) => {
+                ret = historical_keys
+                    .clone()
+                    .nth(tsnk.nth_key.into())
+                    .map(|he| he.ticks_since_occurrence <= tsnk.ticks_since)
+                    .unwrap_or(false);
+            }
+            OpCodeType::TicksSinceGreaterThan(tsnk) => {
+                ret = historical_keys
+                    .clone()
+                    .nth(tsnk.nth_key.into())
+                    .map(|he| he.ticks_since_occurrence > tsnk.ticks_since)
+                    .unwrap_or(false);
+            }
+            OpCodeType::Input(coord) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = inputs.clone().any(|c| c == coord)
+            }
+            OpCodeType::HistoricalInput(hki) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = historical_inputs
+                    .clone()
+                    .nth(hki.how_far_back as usize)
+                    .map(|he| he.event == hki.input)
+                    .unwrap_or(false)
+            }
+            OpCodeType::Layer(layer) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = layers.clone().next().map(|l| l == layer).unwrap_or(false)
+            }
+            OpCodeType::BaseLayer(base_layer) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = default_layer == base_layer;
+            }
+            OpCodeType::HistoricalDevice(hd) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = device_history
+                    .clone()
+                    .nth(hd.how_far_back as usize)
+                    .and_then(|d| d.map(|d| d == hd.device_id))
+                    .unwrap_or(false);
+            }
+            OpCodeType::CallbackIndex(callback_index) => {
+                // opcode has size 2
+                current_index += 1;
+                ret = callbacks[usize::from(callback_index)]();
+            }
+        };
+        if current_op == Not {
+            ret = !ret;
+        }
+        if matches!((ret, current_op), (true, Or) | (false, And | Not)) {
+            current_index = current_end_index;
+            continue;
+        }
+        current_index += 1;
+    }
+    while let Some(OperatorAndEndIndex { op, .. }) = stack.pop_back() {
+        if op == Not {
+            ret = !ret;
+        }
+    }
+    ret
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    fn svec<T>(s: &[T]) -> Vec<T>
+    where
+        T: Clone,
+    {
+        s.iter().cloned().collect()
+    }
+
+    // Do not use anymore.
+    // Superceded by test_evaluate with SwitchTestCfg.
+    fn evaluate_bool_test(opcodes: &[OpCode], key_codes: &[KeyCode]) -> bool {
+        let opcodes = svec(opcodes);
+        let key_codes = svec(key_codes);
+
+        let testcfg = SwitchTestCfg {
+            opcodes,
+            key_codes,
+            ..Default::default()
+        };
+        testcfg.evaluate()
+    }
+
+    struct SwitchTestCfg {
+        opcodes: Vec<OpCode>,
+        key_codes: Vec<KeyCode>,
+        inputs: Vec<KCoord>,
+        historical_keys: Vec<HistoricalEvent<KeyCode>>,
+        historical_inputs: Vec<HistoricalEvent<KCoord>>,
+        layers: Vec<u16>,
+        default_layer: u16,
+        device_history: Vec<Option<NonZeroU8>>,
+        callbacks: Vec<&'static (dyn Fn() -> bool + Send + Sync)>,
+    }
+
+    impl Default for SwitchTestCfg {
+        fn default() -> Self {
+            Self {
+                opcodes: vec![],
+                key_codes: vec![],
+                inputs: vec![],
+                historical_keys: vec![],
+                historical_inputs: vec![],
+                layers: vec![],
+                default_layer: 0,
+                device_history: vec![],
+                callbacks: vec![],
+            }
+        }
+    }
+
+    impl SwitchTestCfg {
+        fn new() -> Self {
+            Self::default()
+        }
+
+        fn evaluate(&self) -> bool {
+            evaluate_boolean(
+                self.opcodes.as_slice(),
+                self.key_codes.iter().copied(),
+                self.inputs.iter().copied(),
+                self.historical_keys.iter().copied(),
+                self.historical_inputs.iter().copied(),
+                self.layers.iter().copied(),
+                self.default_layer,
+                self.device_history.iter().copied(),
+                self.callbacks.as_slice(),
+            )
+        }
+
+        fn opcodes(mut self, opcodes: &[OpCode]) -> Self {
+            self.opcodes = svec(opcodes);
+            self
+        }
+
+        fn inputs(mut self, inputs: &[KCoord]) -> Self {
+            self.inputs = svec(inputs);
+            self
+        }
+
+        fn historical_keys(mut self, historical_keys: &[HistoricalEvent<KeyCode>]) -> Self {
+            self.historical_keys = svec(historical_keys);
+            self
+        }
+
+        fn historical_inputs(mut self, historical_inputs: &[HistoricalEvent<KCoord>]) -> Self {
+            self.historical_inputs = svec(historical_inputs);
+            self
+        }
+
+        fn device_history(mut self, device_history: &[Option<NonZeroU8>]) -> Self {
+            self.device_history = svec(device_history);
+            self
+        }
+    }
+
+    #[test]
+    fn bool_evaluation_test_0() {
+        let opcodes = &[
+            OpCode::new_bool(And, 9),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::B),
+            OpCode::new_bool(Or, 6),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_key(KeyCode::D),
+            OpCode::new_bool(Or, 9),
+            OpCode::new_key(KeyCode::E),
+            OpCode::new_key(KeyCode::F),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_1() {
+        let opcodes = &[
+            OpCode::new_bool(And, 9),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::B),
+            OpCode::new_bool(Or, 6),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_key(KeyCode::D),
+            OpCode::new_bool(Or, 9),
+            OpCode::new_key(KeyCode::E),
+            OpCode::new_key(KeyCode::F),
+        ];
+        let keycodes = &[
+            KeyCode::A,
+            KeyCode::B,
+            KeyCode::C,
+            KeyCode::D,
+            KeyCode::E,
+            KeyCode::F,
+        ];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_2() {
+        let opcodes = &[
+            OpCode(0x2009),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+            OpCode(0x1006),
+            OpCode(KeyCode::C as u16),
+            OpCode(KeyCode::D as u16),
+            OpCode(0x1009),
+            OpCode(KeyCode::E as u16),
+            OpCode(KeyCode::F as u16),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::E, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_3() {
+        let opcodes = &[
+            OpCode(0x2009),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+            OpCode(0x1006),
+            OpCode(KeyCode::C as u16),
+            OpCode(KeyCode::D as u16),
+            OpCode(0x1009),
+            OpCode(KeyCode::E as u16),
+            OpCode(KeyCode::F as u16),
+        ];
+        let keycodes = &[KeyCode::B, KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_4() {
+        let opcodes = &[];
+        let keycodes = &[];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_5() {
+        let opcodes = &[];
+        let keycodes = &[
+            KeyCode::A,
+            KeyCode::B,
+            KeyCode::C,
+            KeyCode::D,
+            KeyCode::E,
+            KeyCode::F,
+        ];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_6() {
+        let opcodes = &[OpCode(KeyCode::A as u16), OpCode(KeyCode::B as u16)];
+        let keycodes = &[
+            KeyCode::A,
+            KeyCode::B,
+            KeyCode::C,
+            KeyCode::D,
+            KeyCode::E,
+            KeyCode::F,
+        ];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_7() {
+        let opcodes = &[OpCode(KeyCode::A as u16), OpCode(KeyCode::B as u16)];
+        let keycodes = &[KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_9() {
+        let opcodes = &[
+            OpCode(0x2003),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+            OpCode(KeyCode::C as u16),
+        ];
+        let keycodes = &[KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_10() {
+        let opcodes = &[
+            OpCode(0x2004),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+            OpCode(KeyCode::C as u16),
+        ];
+        let keycodes = &[KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_11() {
+        let opcodes = &[
+            OpCode(0x1003),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+        ];
+        let keycodes = &[KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_12() {
+        let opcodes = &[
+            OpCode(0x1005),
+            OpCode(0x2004),
+            OpCode(KeyCode::A as u16),
+            OpCode(KeyCode::B as u16),
+            OpCode(KeyCode::C as u16),
+        ];
+        let keycodes = &[KeyCode::C, KeyCode::D, KeyCode::E, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_max_depth_does_not_panic() {
+        let opcodes = &[
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+            OpCode(0x1008),
+        ];
+        let keycodes = &[];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    #[should_panic]
+    fn bool_evaluation_test_more_than_max_depth_panics() {
+        let opcodes = &[
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+            OpCode(0x1009),
+        ];
+        let keycodes = &[];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn switch_fallthrough() {
+        let sw = Switch {
+            cases: &[
+                (&[], &Action::<()>::KeyCode(KeyCode::A), Fallthrough),
+                (&[], &Action::<()>::KeyCode(KeyCode::B), Fallthrough),
+            ],
+            init_fn: None,
+            callbacks: &[],
+        };
+        let mut actions = sw.actions(
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            0,
+            core::iter::empty(),
+        );
+        assert_eq!(actions.next(), Some(&Action::<()>::KeyCode(KeyCode::A)));
+        assert_eq!(actions.next(), Some(&Action::<()>::KeyCode(KeyCode::B)));
+        assert_eq!(actions.next(), None);
+    }
+
+    #[test]
+    fn switch_break() {
+        let sw = Switch {
+            cases: &[
+                (&[], &Action::<()>::KeyCode(KeyCode::A), Break),
+                (&[], &Action::<()>::KeyCode(KeyCode::B), Break),
+            ],
+            init_fn: None,
+            callbacks: &[],
+        };
+        let mut actions = sw.actions(
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            0,
+            core::iter::empty(),
+        );
+        assert_eq!(actions.next(), Some(&Action::<()>::KeyCode(KeyCode::A)));
+        assert_eq!(actions.next(), None);
+    }
+
+    #[test]
+    fn switch_no_actions() {
+        let sw = Switch {
+            cases: &[
+                (
+                    &[OpCode::new_key(KeyCode::A)],
+                    &Action::<()>::KeyCode(KeyCode::A),
+                    Break,
+                ),
+                (
+                    &[OpCode::new_key(KeyCode::A)],
+                    &Action::<()>::KeyCode(KeyCode::B),
+                    Break,
+                ),
+            ],
+            init_fn: None,
+            callbacks: &[],
+        };
+        let mut actions = sw.actions(
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            [].iter().copied(),
+            0,
+            core::iter::empty(),
+        );
+        assert_eq!(actions.next(), None);
+    }
+
+    #[test]
+    fn switch_device_history_match() {
+        let id1 = NonZeroU8::new(1).unwrap();
+        let id2 = NonZeroU8::new(2).unwrap();
+        let (op1, op2) = OpCode::new_device_history(id1, 0);
+        let opcodes = &[op1, op2];
+
+        // Matching device ID (most recent)
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(opcodes)
+            .device_history(&[Some(id1)]);
+        assert_eq!(true, testcfg.evaluate());
+
+        // Non-matching device ID
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(opcodes)
+            .device_history(&[Some(id2)]);
+        assert_eq!(false, testcfg.evaluate());
+
+        // Empty device history
+        let testcfg = SwitchTestCfg::new().opcodes(opcodes);
+        assert_eq!(false, testcfg.evaluate());
+    }
+
+    #[test]
+    fn switch_device_history_recency() {
+        let id1 = NonZeroU8::new(1).unwrap();
+        let id2 = NonZeroU8::new(2).unwrap();
+        let id3 = NonZeroU8::new(3).unwrap();
+        let history = [Some(id3), Some(id2), Some(id1)]; // most recent first: 3, 2, 1
+        //
+        // Check most recent (recency 1 → how_far_back 0) is id3
+        let (op1, op2) = OpCode::new_device_history(id3, 0);
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&[op1, op2])
+            .device_history(&history);
+        assert_eq!(true, testcfg.evaluate());
+
+        // Check second most recent (recency 2 → how_far_back 1) is id2
+        let (op1, op2) = OpCode::new_device_history(id2, 1);
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&[op1, op2])
+            .device_history(&history);
+        assert_eq!(true, testcfg.evaluate());
+
+        // Wrong device at recency 1
+        let (op1, op2) = OpCode::new_device_history(id1, 0);
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&[op1, op2])
+            .device_history(&history);
+        assert_eq!(false, testcfg.evaluate());
+    }
+
+    #[test]
+    fn switch_device_history_opcode_roundtrip() {
+        let id = NonZeroU8::new(42).unwrap();
+        let (op1, op2) = OpCode::new_device_history(id, 3);
+        match op1.opcode_type(Some(op2)) {
+            OpCodeType::HistoricalDevice(hd) => {
+                assert_eq!(hd.device_id, id);
+                assert_eq!(hd.how_far_back, 3);
+            }
+            other => panic!("expected HistoricalDevice, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn switch_device_history_unknown_device() {
+        let id1 = NonZeroU8::new(1).unwrap();
+        let history = [Some(id1), None, Some(id1)]; // unknown device at position 1
+        //
+        // Looking for id1 at position 0 should match
+        let (op1, op2) = OpCode::new_device_history(id1, 0);
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&[op1, op2])
+            .device_history(&history);
+        assert_eq!(true, testcfg.evaluate());
+
+        // Looking for id1 at position 1 (where None is) should NOT match
+        let (op1, op2) = OpCode::new_device_history(id1, 1);
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&[op1, op2])
+            .device_history(&history);
+        assert_eq!(false, testcfg.evaluate());
+    }
+
+    #[test]
+    fn switch_historical_1() {
+        let opcode_true = [OpCode(0x8000 | KeyCode::A as u16)];
+        let opcode_true2 = [OpCode(0xF000 | KeyCode::H as u16)];
+        let opcode_false = [OpCode(0x9000 | KeyCode::A as u16)];
+        let opcode_false2 = [OpCode(0xE000 | KeyCode::H as u16)];
+        assert_eq!(
+            OpCode::new_key_history(KeyCode::A, 0),
+            OpCode(0x8000 | KeyCode::A as u16)
+        );
+        assert_eq!(
+            OpCode::new_key_history(KeyCode::H, 7),
+            OpCode(0xF000 | KeyCode::H as u16)
+        );
+        let hist_keycodes = [
+            HistoricalEvent {
+                event: KeyCode::A,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::B,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::C,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::D,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::E,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::F,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::G,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::H,
+                ticks_since_occurrence: 0,
+            },
+        ];
+
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&opcode_true)
+            .historical_keys(&hist_keycodes);
+        assert_eq!(true, testcfg.evaluate());
+
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&opcode_true2)
+            .historical_keys(&hist_keycodes);
+        assert_eq!(true, testcfg.evaluate());
+
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&opcode_false)
+            .historical_keys(&hist_keycodes);
+        assert_eq!(false, testcfg.evaluate());
+
+        let testcfg = SwitchTestCfg::new()
+            .opcodes(&opcode_false2)
+            .historical_keys(&hist_keycodes);
+        assert_eq!(false, testcfg.evaluate());
+    }
+
+    #[test]
+    fn switch_historical_bools() {
+        let opcodes_true_and = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_key_history(KeyCode::A, 0),
+            OpCode::new_key_history(KeyCode::B, 1),
+        ];
+        let opcodes_false_and1 = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_key_history(KeyCode::A, 0),
+            OpCode::new_key_history(KeyCode::B, 2),
+        ];
+        let opcodes_false_and2 = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_key_history(KeyCode::B, 2),
+            OpCode::new_key_history(KeyCode::A, 0),
+        ];
+        let opcodes_true_or1 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_key_history(KeyCode::A, 0),
+            OpCode::new_key_history(KeyCode::B, 1),
+        ];
+        let opcodes_true_or2 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_key_history(KeyCode::A, 0),
+            OpCode::new_key_history(KeyCode::B, 2),
+        ];
+        let opcodes_true_or3 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_key_history(KeyCode::B, 2),
+            OpCode::new_key_history(KeyCode::A, 0),
+        ];
+        let opcodes_false_or = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_key_history(KeyCode::A, 1),
+            OpCode::new_key_history(KeyCode::B, 2),
+        ];
+        let hist_keycodes = [
+            HistoricalEvent {
+                event: KeyCode::A,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::B,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::C,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::D,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::E,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::F,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::G,
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: KeyCode::H,
+                ticks_since_occurrence: 0,
+            },
+        ];
+
+        let test = |opcodes: &[OpCode], expectation: bool| {
+            let testcfg = SwitchTestCfg::new()
+                .opcodes(opcodes)
+                .historical_keys(&hist_keycodes);
+            assert_eq!(expectation, testcfg.evaluate())
+        };
+        test(&opcodes_true_and, true);
+        test(&opcodes_true_or1, true);
+        test(&opcodes_true_or2, true);
+        test(&opcodes_true_or3, true);
+        test(&opcodes_false_and1, false);
+        test(&opcodes_false_and2, false);
+        test(&opcodes_false_or, false);
+    }
+
+    #[test]
+    fn switch_historical_ticks_since() {
+        let opcodes_true_and = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_ticks_since_gt(0, 99),
+            OpCode::new_ticks_since_lt(0, 101),
+        ];
+        let opcodes_false_and1 = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_ticks_since_gt(1, 200),
+            OpCode::new_ticks_since_lt(1, 240),
+        ];
+        let opcodes_false_and2 = [
+            OpCode::new_bool(And, 3),
+            OpCode::new_ticks_since_gt(2, 300),
+            OpCode::new_ticks_since_lt(2, 300),
+        ];
+        let opcodes_true_or1 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(3, 500),
+            OpCode::new_ticks_since_lt(3, 510),
+        ];
+        let opcodes_true_or2 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(4, 500),
+            OpCode::new_ticks_since_lt(4, 511),
+        ];
+        let opcodes_true_or3 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(5, 980),
+            OpCode::new_ticks_since_lt(5, 999),
+        ];
+        let opcodes_false_or1 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(6, 40200),
+            OpCode::new_ticks_since_lt(6, 39999),
+        ];
+        let opcodes_false_or2 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(5, 1030),
+            OpCode::new_ticks_since_lt(5, 999),
+        ];
+        let opcodes_false_or3 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(4, 520),
+            OpCode::new_ticks_since_lt(4, 511),
+        ];
+        let opcodes_false_or4 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(3, 520),
+            OpCode::new_ticks_since_lt(3, 510),
+        ];
+        let opcodes_false_or5 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(2, 265),
+            OpCode::new_ticks_since_lt(2, 255),
+        ];
+        let opcodes_false_or6 = [
+            OpCode::new_bool(Or, 3),
+            OpCode::new_ticks_since_gt(1, 256),
+            OpCode::new_ticks_since_lt(1, 254),
+        ];
+        let hist_keycodes = [
+            HistoricalEvent {
+                event: KeyCode::A,
+                ticks_since_occurrence: 100,
+            },
+            HistoricalEvent {
+                event: KeyCode::B,
+                ticks_since_occurrence: 255,
+            },
+            HistoricalEvent {
+                event: KeyCode::C,
+                ticks_since_occurrence: 256,
+            },
+            HistoricalEvent {
+                event: KeyCode::D,
+                ticks_since_occurrence: 511,
+            },
+            HistoricalEvent {
+                event: KeyCode::E,
+                ticks_since_occurrence: 512,
+            },
+            HistoricalEvent {
+                event: KeyCode::F,
+                ticks_since_occurrence: 1000,
+            },
+            HistoricalEvent {
+                event: KeyCode::G,
+                ticks_since_occurrence: 40000,
+            },
+        ];
+
+        let test = |opcodes: &[OpCode], expectation: bool| {
+            let testcfg = SwitchTestCfg::new()
+                .opcodes(opcodes)
+                .historical_keys(&hist_keycodes);
+            assert_eq!(expectation, testcfg.evaluate())
+        };
+        test(&opcodes_true_and, true);
+        test(&opcodes_true_or1, true);
+        test(&opcodes_true_or2, true);
+        test(&opcodes_true_or3, true);
+        test(&opcodes_false_and1, false);
+        test(&opcodes_false_and2, false);
+        test(&opcodes_false_or1, false);
+        test(&opcodes_false_or2, false);
+        test(&opcodes_false_or3, false);
+        test(&opcodes_false_or4, false);
+        test(&opcodes_false_or5, false);
+        test(&opcodes_false_or6, false);
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_0() {
+        // Full inverse of a previous test
+        let opcodes = &[
+            OpCode::new_bool(Not, 10),
+            OpCode::new_bool(And, 10),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::B),
+            OpCode::new_bool(Or, 7),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_key(KeyCode::D),
+            OpCode::new_bool(Or, 10),
+            OpCode::new_key(KeyCode::E),
+            OpCode::new_key(KeyCode::F),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_1() {
+        // Both A and B exist, should be false
+        let opcodes = &[
+            OpCode::new_bool(Not, 3),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::B),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_2() {
+        // Neither X nor Y exist, should be false
+        let opcodes = &[
+            OpCode::new_bool(Not, 3),
+            OpCode::new_key(KeyCode::X),
+            OpCode::new_key(KeyCode::Y),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_3() {
+        let opcodes = &[
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_bool(Not, 3),
+            OpCode::new_key(KeyCode::D),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_4() {
+        let opcodes = &[
+            OpCode::new_bool(And, 10),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::B),
+            OpCode::new_bool(Or, 7),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_bool(Not, 7),
+            OpCode::new_key(KeyCode::D),
+            OpCode::new_bool(Or, 10),
+            OpCode::new_key(KeyCode::E),
+            OpCode::new_key(KeyCode::F),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_5() {
+        let opcodes = &[
+            OpCode::new_bool(Not, 4),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_bool(Not, 4),
+            OpCode::new_key(KeyCode::D),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_6() {
+        // C does not exist, D does. Ensure C nonexistence does not short-circuit
+        // and existence of D is checked.
+        let opcodes = &[
+            OpCode::new_bool(Not, 3),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_key(KeyCode::D),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_or_equivalency_not_6() {
+        let opcodes = &[
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Or, 4),
+            OpCode::new_key(KeyCode::C),
+            OpCode::new_key(KeyCode::D),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_7() {
+        // A exists, make sure this short-circuits, and E nonexistence does not override the return.
+        let opcodes = &[
+            OpCode::new_bool(Not, 3),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::E),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_or_equivalency_not_7() {
+        let opcodes = &[
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Or, 4),
+            OpCode::new_key(KeyCode::A),
+            OpCode::new_key(KeyCode::E),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_8() {
+        let opcodes = &[
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Not, 4),
+            OpCode::new_key(KeyCode::A),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(!evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn bool_evaluation_test_not_9() {
+        let opcodes = &[
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Not, 4),
+            OpCode::new_bool(Not, 4),
+            OpCode::new_key(KeyCode::C),
+        ];
+        let keycodes = &[KeyCode::A, KeyCode::B, KeyCode::D, KeyCode::F];
+        assert!(evaluate_bool_test(opcodes, keycodes,));
+    }
+
+    #[test]
+    fn switch_inputs() {
+        let (op1, op2) = OpCode::new_active_input((0, 1));
+        let (op3, op4) = OpCode::new_active_input((1, 2));
+        let (op5, op6) = OpCode::new_active_input((1, 3));
+        let (op7, op8) = OpCode::new_active_input((3, 3));
+        let opcodes_true_and = [OpCode::new_bool(And, 5), op1, op2, op3, op4];
+        let opcodes_false_and1 = [OpCode::new_bool(And, 5), op1, op2, op5, op6];
+        let opcodes_false_and2 = [OpCode::new_bool(And, 5), op5, op6, op1, op2];
+        let opcodes_false_or = [OpCode::new_bool(Or, 5), op7, op8, op5, op6];
+        let opcodes_true_or1 = [OpCode::new_bool(Or, 5), op1, op2, op5, op6];
+        let opcodes_true_or2 = [OpCode::new_bool(Or, 5), op7, op8, op3, op4];
+        let active_inputs = [(0, 1), (1, 2), (2, 3), (3, 4)];
+        let test = |opcodes: &[OpCode], expectation: bool| {
+            let testcfg = SwitchTestCfg::new().opcodes(opcodes).inputs(&active_inputs);
+            assert_eq!(expectation, testcfg.evaluate())
+        };
+        test(&opcodes_true_and, true);
+        test(&opcodes_false_and1, false);
+        test(&opcodes_false_and2, false);
+        test(&opcodes_false_or, false);
+        test(&opcodes_true_or1, true);
+        test(&opcodes_true_or2, true);
+    }
+
+    #[test]
+    fn switch_historical_inputs() {
+        let (op1, op2) = OpCode::new_historical_input((0, 0), 0);
+        let (op3, op4) = OpCode::new_historical_input((3, 750), 7);
+        let (op5, op6) = OpCode::new_historical_input((1, 3), 0);
+        let (op7, op8) = OpCode::new_historical_input((3, 3), 7);
+        let opcodes_true_and = [OpCode::new_bool(And, 5), op1, op2, op3, op4];
+        let opcodes_false_and1 = [OpCode::new_bool(And, 5), op1, op2, op5, op6];
+        let opcodes_false_and2 = [OpCode::new_bool(And, 5), op5, op6, op1, op2];
+        let opcodes_false_or = [OpCode::new_bool(Or, 5), op7, op8, op5, op6];
+        let opcodes_true_or1 = [OpCode::new_bool(Or, 5), op1, op2, op5, op6];
+        let opcodes_true_or2 = [OpCode::new_bool(Or, 5), op7, op8, op3, op4];
+        let historical_inputs = [
+            HistoricalEvent {
+                event: (0, 0),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (1, 750),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (2, 1),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (3, 749),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (0, 1),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (1, 2),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (2, 3),
+                ticks_since_occurrence: 0,
+            },
+            HistoricalEvent {
+                event: (3, 750),
+                ticks_since_occurrence: 0,
+            },
+        ];
+
+        let test = |opcodes: &[OpCode], expectation: bool| {
+            let testcfg = SwitchTestCfg::new()
+                .opcodes(opcodes)
+                .historical_inputs(&historical_inputs);
+            assert_eq!(expectation, testcfg.evaluate())
+        };
+
+        test(&opcodes_true_and, true);
+        test(&opcodes_false_and1, false);
+        test(&opcodes_false_and2, false);
+        test(&opcodes_false_or, false);
+        test(&opcodes_true_or1, true);
+        test(&opcodes_true_or2, true);
+    }
+}
diff --git a/keyberon/src/chord.rs b/keyberon/src/chord.rs
new file mode 100644
index 000000000..d079bdd96
--- /dev/null
+++ b/keyberon/src/chord.rs
@@ -0,0 +1,617 @@
+//! Module for chords v2 implementation.
+
+use std::cell::Cell;
+
+use arraydeque::ArrayDeque;
+use heapless::Vec as HVec;
+use rustc_hash::FxHashMap;
+
+use crate::{
+    action::Action,
+    key_code::KEY_MAX,
+    layout::{Event, Queue, Queued, QueuedAction},
+};
+
+// Macro to help with this boilerplate.
+// $v should probably be `self` at points of use.
+// Ownership rules make this difficult to do as a regular fn,
+// because impl function calls don't understand split borrowing.
+macro_rules! no_chord_activations {
+    ($v:expr) => {{
+        $v.ticks_to_ignore_chord = $v.configured_ticks_to_ignore_chord;
+    }};
+}
+
+pub(crate) const TRIGGER_TAPHOLD_COORD: (u8, u16) = (0, 0);
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum ReleaseBehaviour {
+    OnFirstRelease,
+    OnLastRelease,
+}
+
+#[derive(Clone)]
+pub struct ChordV2<'a, T> {
+    /// The action associated with this chord.
+    pub action: &'a Action<'a, T>,
+    /// The full set of keys that need to be pressed to activate this chord.
+    pub participating_keys: &'a [u16],
+    /// The number of ticks during which, after the first press of a participant,
+    /// this chord can be activated if all participants get pressed.
+    /// In other words, after the number of ticks defined by `pending_duration`
+    /// elapses, this chord can no longer be completed.
+    pub pending_duration: u16,
+    /// The layers on which this chord is disabled.
+    pub disabled_layers: &'a [u16],
+    /// When should the action for this chord be released.
+    pub release_behaviour: ReleaseBehaviour,
+}
+
+impl<'a, T> std::fmt::Debug for ChordV2<'a, T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
+        f.debug_struct("Point")
+            .field("participating_keys", &self.participating_keys)
+            .field("pending_duration", &self.pending_duration)
+            .field("disabled_layers", &self.disabled_layers)
+            .field("release_behaviour", &self.release_behaviour)
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ChordsForKey<'a, T> {
+    /// Chords that this key participates in.
+    pub chords: Vec<&'a ChordV2<'a, T>>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ChordsForKeys<'a, T> {
+    pub mapping: FxHashMap<u16, ChordsForKey<'a, T>>,
+}
+
+const SMOL_Q_LEN: usize = 16;
+
+struct ActiveChord<'a, T> {
+    /// Chords uses a virtual coordinate in the keyberon state for an activated chord.
+    /// This field tracks which coordinate to release when the chord itself is released.
+    coordinate: u16,
+    /// Keys left to release.
+    /// For OnFirstRelease, this should have length 0.
+    remaining_keys_to_release: HVec<u16, SMOL_Q_LEN>,
+    /// Necessary to include here make sure that, for OnFirstRelease,
+    /// random other releases that are not part of this chord,
+    /// do not release this chord.
+    participating_keys: &'a [u16],
+    /// Action associated with the active chord.
+    /// This needs to be stored here
+    action: &'a Action<'a, T>,
+    /// In the case of Unread, this chord has not yet been consumed by the layout code.
+    /// This might happen for a while because of tap-hold-related delays.
+    /// In the Releasable status, the active chord has been consumed and can be released.
+    status: ActiveChordStatus,
+    /// Tracks how old an action is.
+    delay: u16,
+}
+
+fn tick_ach<T>(acc: &mut ActiveChord<T>) {
+    acc.delay = acc.delay.saturating_add(1);
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ActiveChordStatus {
+    /// -> UnreadPendingRelease if chord released before being consumed
+    /// -> Releasable if consumed
+    Unread,
+    /// -> Released once consumed
+    UnreadReleased,
+    /// Can remove at any time.
+    /// -> Released once released
+    Releasable,
+    /// Remove on next tick_chv2
+    Released,
+}
+use ActiveChordStatus::*;
+
+/// Like the layout Queue but smaller.
+pub(crate) type SmolQueue = ArrayDeque<Queued, SMOL_Q_LEN, arraydeque::behavior::Wrapping>;
+
+/// Global input chords configuration.
+pub struct ChordsV2<'a, T> {
+    // Note: Interior fields do not need to be pub or mutable via impl pub fn.
+    // Like a layout, this should be destroyed and recreated on a live reload.
+    //
+    /// Queued inputs that can potentially activate a chord but have not yet.
+    /// Inputs will leave if they are determined that they will not activate a chord,
+    /// or if a chord activates.
+    queue: Queue,
+    /// Information about what chords are possible and what keys they are associated with.
+    chords: ChordsForKeys<'a, T>,
+    /// Chords that are active, i.e. ones that have not yet been released.
+    active_chords: HVec<ActiveChord<'a, T>, 10>,
+    /// When a key leaves the combo queue without activating a chord,
+    /// this activates a timer during which keys cannot activate chords
+    /// and are always forwarded directly to the standard input queue.
+    ///
+    /// This keeps track of the timer.
+    ticks_to_ignore_chord: u16,
+    /// Initial value for the above when the appropriate event happens.
+    /// This must have a minimum value even if not configured by the user,
+    /// or if configured by the user to be zero. (maybe forbid that config)
+    configured_ticks_to_ignore_chord: u16,
+    /// Optimization: if there are no new inputs, the code can skip some processing work.
+    /// This tracks the next time that a change will happen, so that the processing work
+    /// is **not** skipped when something needs to be checked.
+    ticks_until_next_state_change: u16,
+    /// Optimization: the below is part of skipping processing work - if this is has changed,
+    /// then processing work cannot be skipped.
+    prev_active_layer: u16,
+    /// Optimization: the below is part of skipping processing work - if this is has changed,
+    /// then processing work cannot be skipped.
+    prev_queue_len: u8,
+    /// Virtual coordinate for use in the layout state.
+    next_coord: Cell<u16>,
+}
+
+impl<T> std::fmt::Debug for ChordsV2<'_, T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "ChordsV2")
+    }
+}
+
+impl<'a, T> ChordsV2<'a, T> {
+    pub fn new(chords: ChordsForKeys<'a, T>, ticks_ignore_chord: u16) -> Self {
+        assert!(ticks_ignore_chord >= 5);
+        Self {
+            queue: Queue::new(),
+            chords,
+            active_chords: HVec::new(),
+            ticks_to_ignore_chord: 0,
+            configured_ticks_to_ignore_chord: ticks_ignore_chord,
+            ticks_until_next_state_change: 0,
+            prev_active_layer: u16::MAX,
+            prev_queue_len: u8::MAX,
+            next_coord: Cell::new(KEY_MAX + 1),
+        }
+    }
+
+    pub fn is_idle_chv2(&self) -> bool {
+        self.queue.is_empty() && self.active_chords.is_empty()
+    }
+
+    pub fn accepts_chords_chv2(&self) -> bool {
+        self.ticks_to_ignore_chord == 0
+    }
+
+    pub fn push_back_chv2(&mut self, item: Queued) -> Option<Queued> {
+        self.queue.push_back(item)
+    }
+
+    pub fn chords(&self) -> &ChordsForKeys<'a, T> {
+        &self.chords
+    }
+
+    pub(crate) fn get_action_chv2(&mut self) -> QueuedAction<'a, T> {
+        self.active_chords
+            .iter_mut()
+            .find_map(|ach| match ach.status {
+                Unread => {
+                    ach.status = Releasable;
+                    // Note on LayerStack being default (empty):
+                    // A chordv2 is not allowed to use transparency,
+                    // so it does not need to handle this case.
+                    Some(Some((
+                        (0, ach.coordinate),
+                        ach.delay,
+                        ach.action,
+                        Default::default(),
+                    )))
+                }
+                UnreadReleased => {
+                    ach.status = Released;
+                    Some(Some((
+                        (0, ach.coordinate),
+                        ach.delay,
+                        ach.action,
+                        Default::default(),
+                    )))
+                }
+                Releasable | Released => None,
+            })
+            .unwrap_or_default()
+    }
+
+    /// Update the times in the queue without activating any chords yet.
+    /// Returns queued events that are no longer usable in chords.
+    pub(crate) fn tick_chv2(&mut self, active_layer: u16) -> SmolQueue {
+        let mut q = SmolQueue::new();
+        self.queue.iter_mut().for_each(Queued::tick_qd);
+        let prev_active_chord_len = self.active_chords.len();
+        self.active_chords.iter_mut().for_each(tick_ach);
+        self.drain_inputs(&mut q, active_layer);
+        if self.active_chords.len() != prev_active_chord_len {
+            // A chord was activated. Forward a no-op press event to potentially trigger
+            // HoldOnOtherKeyPress or PermissiveHold.
+            // FLAW: this does not associate with the actual input keys and thus cannot correctly
+            // trigger the early tap for *-keys variants of kanata tap-hold.
+            q.push_back(Queued::new_press(
+                TRIGGER_TAPHOLD_COORD.0,
+                TRIGGER_TAPHOLD_COORD.1,
+            ));
+        }
+        if self
+            .active_chords
+            .iter()
+            .any(|ach| matches!(ach.status, UnreadReleased | Released))
+        {
+            // A chord was released. Forward a no-op release event to potentially trigger
+            // PermissiveHold.
+            // FLAW: see above
+            q.push_back(Queued::new_release(
+                TRIGGER_TAPHOLD_COORD.0,
+                TRIGGER_TAPHOLD_COORD.1,
+            ));
+        }
+        self.clear_released_chords(&mut q);
+        self.ticks_to_ignore_chord = self.ticks_to_ignore_chord.saturating_sub(1);
+        q
+    }
+
+    fn next_coord(&self) -> u16 {
+        let ret = self.next_coord.get();
+        let mut new = ret + 1;
+        if new > KEY_MAX + 50 {
+            new = KEY_MAX + 1;
+        }
+        self.next_coord.set(new);
+        ret
+    }
+
+    fn drain_inputs(&mut self, drainq: &mut SmolQueue, active_layer: u16) {
+        if self.ticks_to_ignore_chord > 0 {
+            self.drain_without_new_activations(drainq);
+            return;
+        }
+        if self.ticks_until_next_state_change > 0
+            && self.prev_active_layer == active_layer
+            && usize::from(self.prev_queue_len) == self.queue.len()
+        {
+            self.ticks_until_next_state_change =
+                self.ticks_until_next_state_change.saturating_sub(1);
+            return;
+        }
+        self.ticks_until_next_state_change = 0;
+        self.prev_active_layer = active_layer;
+        debug_assert!(self.queue.capacity() < 255);
+        self.prev_queue_len = self.queue.len() as u8;
+
+        self.drain_virtual_keys(drainq);
+        self.drain_releases(drainq);
+        self.process_presses(active_layer);
+    }
+
+    /// Used to process keys while chordsv2 is in the disabled state from rapid typing.
+    /// Releases must still be processed to release already-activated chords.
+    fn drain_without_new_activations(&mut self, drainq: &mut SmolQueue) {
+        let achs = &mut self.active_chords;
+        for qd in self.queue.iter() {
+            if let Event::Release(_, j) = qd.event {
+                // Release the key from active chords.
+                achs.iter_mut().for_each(|ach| {
+                    if !ach.participating_keys.contains(&j) {
+                        return;
+                    }
+                    ach.remaining_keys_to_release.retain(|pk| *pk != j);
+                    if ach.remaining_keys_to_release.is_empty() {
+                        ach.status = match ach.status {
+                            Unread | UnreadReleased => UnreadReleased,
+                            Releasable | Released => Released,
+                        }
+                    }
+                });
+            }
+            drainq.push_back(*qd);
+        }
+        self.queue.clear();
+    }
+
+    fn drain_virtual_keys(&mut self, drainq: &mut SmolQueue) {
+        self.queue.retain(|qd| {
+            match qd.event {
+                // Only row 0 is real inputs.
+                // Drain other rows (at the time of writing should only be index 1).
+                Event::Press(0, _) | Event::Release(0, _) => true,
+                _ => {
+                    let overflow = drainq.push_back(*qd);
+                    assert!(overflow.is_none(), "oops overflowed drain queue");
+                    false
+                }
+            }
+        });
+    }
+
+    fn drain_releases(&mut self, drainq: &mut SmolQueue) {
+        let achs = &mut self.active_chords;
+        let mut presses = HVec::<_, SMOL_Q_LEN>::new();
+        self.queue.retain(|qd| match qd.event {
+            Event::Press(_, j) => {
+                let overflow = presses.push(j);
+                debug_assert!(overflow.is_ok());
+                true
+            }
+            Event::Release(_, j) => {
+                if presses.is_empty() {
+                    // Release the key from active chords.
+                    achs.iter_mut().for_each(|ach| {
+                        if !ach.participating_keys.contains(&j) {
+                            return;
+                        }
+                        ach.remaining_keys_to_release.retain(|pk| *pk != j);
+                        if ach.remaining_keys_to_release.is_empty() {
+                            ach.status = match ach.status {
+                                Unread | UnreadReleased => UnreadReleased,
+                                Releasable | Released => Released,
+                            }
+                        }
+                    });
+
+                    drainq.push_back(*qd);
+                    false
+                } else {
+                    true
+                }
+            }
+        })
+    }
+
+    fn process_presses(&mut self, active_layer: u16) {
+        #[derive(Copy, Clone, Debug)]
+        struct PressWithTime {
+            key: u16,
+            since: u16,
+        }
+
+        let mut presses = HVec::<u16, SMOL_Q_LEN>::new();
+        let mut presses_with_time = HVec::<PressWithTime, SMOL_Q_LEN>::new();
+        let mut relevant_release_found = false;
+        for qd in self.queue.iter() {
+            match qd.event {
+                Event::Press(_, j) => {
+                    let overflowed = presses.push(j);
+                    debug_assert!(overflowed.is_ok(), "too many presses in queue");
+                    let _ = presses_with_time.push(PressWithTime {
+                        key: j,
+                        since: qd.since,
+                    });
+                }
+                Event::Release(_, j) => {
+                    if presses.contains(&j) {
+                        relevant_release_found = true;
+                        break;
+                    }
+                }
+            }
+        }
+        let prev_active_chords_len = self.active_chords.len();
+        let Some(starting_press) = presses.first() else {
+            return;
+        };
+        let Some(possible_chords) = self.chords.mapping.get(starting_press) else {
+            no_chord_activations!(self);
+            return;
+        };
+
+        // For subsequent keypresses,
+        // all must fit into a single chord for chord state to remain pending
+        // instead of activating a chord,
+        // and there must also be a longer chord that can still potentially be activated.
+        //
+        // Prioritization of chord activation:
+        // 1. Timed out chord
+        // 2. Longer chord
+        let mut accumulated_presses = HVec::<PressWithTime, SMOL_Q_LEN>::new();
+        let mut chord_candidates = HVec::<&ChordV2<'a, T>, SMOL_Q_LEN>::new();
+        let mut prev_count = usize::MAX;
+        let mut min_timeout;
+
+        assert!(!presses_with_time.is_empty());
+        let since = self.queue.iter().next().unwrap().since;
+
+        for press in presses_with_time.iter().copied() {
+            min_timeout = u16::MAX;
+            let _ = accumulated_presses.push(press);
+
+            let count_possible = if prev_count == chord_candidates.len() {
+                // optimization: no longer need to check the whole list.
+                // chord_candidates will keep getting shrunk.
+                chord_candidates.retain(|chc| {
+                    chc.participating_keys.contains(&press.key)
+                        && accumulated_presses[0].since - press.since <= chc.pending_duration
+                });
+                for chc in chord_candidates.iter() {
+                    if chc.pending_duration > since {
+                        min_timeout = std::cmp::min(min_timeout, chc.pending_duration);
+                    }
+                }
+                chord_candidates.len()
+            } else {
+                chord_candidates.clear();
+                possible_chords
+                    .chords
+                    .iter()
+                    .filter(|pch| !pch.disabled_layers.contains(&active_layer))
+                    .filter(|pch| {
+                        if accumulated_presses
+                            .iter()
+                            .all(|acp| pch.participating_keys.contains(&acp.key))
+                            && accumulated_presses[0].since - press.since <= pch.pending_duration
+                        {
+                            // If full, can't run the optimization above, but not fatal.
+                            // Can ignore the overflow.
+                            let _overflow = chord_candidates.push(pch);
+                            if pch.pending_duration > since {
+                                min_timeout = std::cmp::min(min_timeout, pch.pending_duration);
+                            }
+                            true
+                        } else {
+                            false
+                        }
+                    })
+                    .count()
+            };
+
+            match count_possible {
+                1 => {
+                    // Found a chord that is not fully overlapped by another.
+                    // Activate the chord if it is completed
+                    let coord = self.next_coord();
+                    let cch = chord_candidates[0];
+                    if cch
+                        .participating_keys
+                        .iter()
+                        .all(|pk| accumulated_presses.iter().any(|ap| ap.key == *pk))
+                    {
+                        let ach = get_active_chord(cch, since, coord, relevant_release_found);
+                        let overflow = self.active_chords.push(ach);
+                        assert!(overflow.is_ok(), "active chords has room");
+                        break;
+                    }
+                }
+                0 => {
+                    // If reached this, it means we went from 2+ -> 0,
+                    // or we got to zero at the first iteration.
+                    // Backtrack one accumulated press then:
+                    // - activate a chord if one completed
+                    // - clear the input queue otherwise
+                    let _ = accumulated_presses.pop();
+                    chord_candidates.clear();
+                    let completed_chord = possible_chords
+                        .chords
+                        .iter()
+                        .filter(|pch| !pch.disabled_layers.contains(&active_layer))
+                        .find(
+                            // Ensure the two lists have the same set of keys
+                            |pch| {
+                                accumulated_presses
+                                    .iter()
+                                    .all(|acp| pch.participating_keys.contains(&acp.key))
+                                    && pch.participating_keys.iter().all(|pk| {
+                                        accumulated_presses.iter().any(|ap| ap.key == *pk)
+                                    })
+                            },
+                        );
+                    match completed_chord {
+                        Some(cch) => {
+                            let coord = self.next_coord();
+                            let ach = get_active_chord(cch, since, coord, relevant_release_found);
+                            let overflow = self.active_chords.push(ach);
+                            assert!(overflow.is_ok(), "active chords has room");
+                        }
+                        None => no_chord_activations!(self),
+                    }
+                    break;
+                }
+                _ => {}
+            }
+            self.ticks_until_next_state_change = match min_timeout {
+                u16::MAX => 0,
+                t => t.saturating_sub(since),
+            };
+            prev_count = count_possible;
+        }
+        if self.ticks_until_next_state_change == 0 || relevant_release_found {
+            // Find a chord that matches exactly and activate that,
+            // otherwise clear the input queue.
+            let completed_chord =
+                if chord_candidates.is_full() {
+                    possible_chords
+                        .chords
+                        .iter()
+                        .filter(|pch| !pch.disabled_layers.contains(&active_layer))
+                        .find(
+                            // Ensure the two lists have the same set of keys
+                            |pch| {
+                                accumulated_presses
+                                    .iter()
+                                    .all(|acp| pch.participating_keys.contains(&acp.key))
+                                    && pch.participating_keys.iter().all(|pk| {
+                                        accumulated_presses.iter().any(|ap| ap.key == *pk)
+                                    })
+                            },
+                        )
+                } else {
+                    chord_candidates
+                        .iter()
+                        .filter(|pch| !pch.disabled_layers.contains(&active_layer))
+                        .find(
+                            // Ensure the two lists have the same set of keys
+                            |pch| {
+                                accumulated_presses
+                                    .iter()
+                                    .all(|acp| pch.participating_keys.contains(&acp.key))
+                                    && pch.participating_keys.iter().all(|pk| {
+                                        accumulated_presses.iter().any(|ap| ap.key == *pk)
+                                    })
+                            },
+                        )
+                };
+            match completed_chord {
+                Some(cch) => {
+                    let ach =
+                        get_active_chord(cch, since, self.next_coord(), relevant_release_found);
+                    let overflow = self.active_chords.push(ach);
+                    assert!(overflow.is_ok(), "active chords has room");
+                }
+                None => {
+                    no_chord_activations!(self)
+                }
+            }
+        }
+
+        // Clear presses from the queue if they were consumed by a chord.
+        if self.active_chords.len() > prev_active_chords_len {
+            self.queue.retain(|qd| match qd.event {
+                Event::Press(_, j) => !accumulated_presses.iter().any(|ap| ap.key == j),
+                _ => true,
+            });
+        }
+    }
+
+    fn clear_released_chords(&mut self, drainq: &mut SmolQueue) {
+        self.active_chords.retain(|ach| {
+            if ach.status == Released {
+                let overflow = drainq.push_back(Queued {
+                    event: Event::Release(0, ach.coordinate),
+                    since: 0,
+                });
+                assert!(overflow.is_none(), "oops overflowed drain queue");
+                false
+            } else {
+                true
+            }
+        });
+    }
+}
+
+fn get_active_chord<'a, T>(
+    cch: &ChordV2<'a, T>,
+    since: u16,
+    coord: u16,
+    release_found: bool,
+) -> ActiveChord<'a, T> {
+    let mut remaining_keys_to_release = HVec::new();
+    if cch.release_behaviour == ReleaseBehaviour::OnLastRelease {
+        remaining_keys_to_release.extend(cch.participating_keys.iter().copied());
+    };
+    ActiveChord {
+        coordinate: coord,
+        remaining_keys_to_release,
+        participating_keys: cch.participating_keys,
+        action: cch.action,
+        status: if release_found && cch.release_behaviour == ReleaseBehaviour::OnFirstRelease {
+            ActiveChordStatus::UnreadReleased
+        } else {
+            ActiveChordStatus::Unread
+        },
+        delay: since,
+    }
+}
diff --git a/keyberon/src/key_code.rs b/keyberon/src/key_code.rs
index 50784fd17..60aed7eed 100644
--- a/keyberon/src/key_code.rs
+++ b/keyberon/src/key_code.rs
@@ -1,877 +1,873 @@
 //! Key code definitions.
 
+/// Used for switch opcode purposes. Keys should not exceed this amount.
+pub const KEY_MAX: u16 = 850;
+
+#[test]
+fn keycode_max_test() {
+    assert!((KeyCode::KeyMax as u16) < KEY_MAX);
+}
+
 #[allow(missing_docs)]
 /// Define a key code according to the HID specification.  Their names
 /// correspond to the american QWERTY layout.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(u16)]
 pub enum KeyCode {
-    /// The "no" key, a placeholder to express nothing.
-    No = 0x00,
-    /// Error if too much keys are pressed at the same time.
-    ErrorRollOver,
-    /// The POST fail error.
-    PostFail,
-    /// An undefined error occured.
-    ErrorUndefined,
-    /// `a` and `A`.
-    A,
-    B,
-    C,
-    D,
-    E,
-    F,
-    G,
-    H,
-    I,
-    J,
-    K,
-    L,
-    M, // 0x10
-    N,
-    O,
-    P,
-    Q,
-    R,
-    S,
-    T,
-    U,
-    V,
-    W,
-    X,
-    Y,
-    Z,
-    /// `1` and `!`.
-    Kb1,
-    /// `2` and `@`.
-    Kb2,
-    /// `3` and `#`.
-    Kb3, // 0x20
-    /// `4` and `$`.
-    Kb4,
-    /// `5` and `%`.
-    Kb5,
-    /// `6` and `^`.
-    Kb6,
-    /// `7` and `&`.
-    Kb7,
-    /// `8` and `*`.
-    Kb8,
-    /// `9` and `(`.
-    Kb9,
-    /// `0` and `)`.
-    Kb0,
-    Enter,
-    Escape,
-    BSpace,
-    Tab,
-    Space,
-    /// `-` and `_`.
-    Minus,
-    /// `=` and `+`.
-    Equal,
-    /// `[` and `{`.
-    LBracket,
-    /// `]` and `}`.
-    RBracket, // 0x30
-    /// `\` and `|`.
-    Bslash,
-    /// Non-US `#` and `~` (Typically near the Enter key).
-    NonUsHash,
-    /// `;` and `:`.
-    SColon,
-    /// `'` and `"`.
-    Quote,
-    // How to have ` as code?
-    /// \` and `~`.
-    Grave,
-    /// `,` and `<`.
-    Comma,
-    /// `.` and `>`.
-    Dot,
-    /// `/` and `?`.
-    Slash,
-    CapsLock,
-    F1,
-    F2,
-    F3,
-    F4,
-    F5,
-    F6,
-    F7, // 0x40
-    F8,
-    F9,
-    F10,
-    F11,
-    F12,
-    PScreen,
-    ScrollLock,
-    Pause,
-    Insert,
-    Home,
-    PgUp,
-    Delete,
-    End,
-    PgDown,
-    Right,
-    Left, // 0x50
-    Down,
-    Up,
-    NumLock,
-    /// Keypad `/`
-    KpSlash,
-    /// Keypad `*`
-    KpAsterisk,
-    /// Keypad `-`.
-    KpMinus,
-    /// Keypad `+`.
-    KpPlus,
-    /// Keypad enter.
-    KpEnter,
-    /// Keypad 1.
-    Kp1,
-    Kp2,
-    Kp3,
-    Kp4,
-    Kp5,
-    Kp6,
-    Kp7,
-    Kp8, // 0x60
-    Kp9,
-    Kp0,
-    KpDot,
-    /// Non-US `\` and `|` (Typically near the Left-Shift key)
-    NonUsBslash,
-    Application, // 0x65
-    /// not a key, used for errors
-    Power,
-    /// Keypad `=`.
-    KpEqual,
-    F13,
-    F14,
-    F15,
-    F16,
-    F17,
-    F18,
-    F19,
-    F20,
-    F21, // 0x70
-    F22,
-    F23,
-    F24,
-    Execute,
-    Help,
-    Menu,
-    Select,
-    Stop,
-    Again,
-    Undo,
-    Cut,
-    Copy,
-    Paste,
-    Find,
-    Mute,
-    VolUp, // 0x80
-    VolDown,
-    /// Deprecated.
-    LockingCapsLock,
-    /// Deprecated.
-    LockingNumLock,
-    /// Deprecated.
-    LockingScrollLock,
-    /// Keypad `,`, also used for the brazilian keypad period (.) key.
-    KpComma,
-    /// Used on AS/400 keyboard
-    KpEqualSign,
-    Intl1,
-    Intl2,
-    Intl3,
-    Intl4,
-    Intl5,
-    Intl6,
-    Intl7,
-    Intl8,
-    Intl9,
-    Lang1, // 0x90
-    Lang2,
-    Lang3,
-    Lang4,
-    Lang5,
-    Lang6,
-    Lang7,
-    Lang8,
-    Lang9,
-    AltErase,
-    SysReq,
-    Cancel,
-    Clear,
-    Prior,
-    Return,
-    Separator,
-    Out, // 0xA0
-    Oper,
-    ClearAgain,
-    CrSel,
-    ExSel,
-
-    // According to QMK, 0xA5-0xDF are not usable on modern keyboards. The keys below are
-    // not real keys for USB codes; they are used only for kanata.
-    Wakeup, // 0xA5
-    BrightnessUp,
-    BrightnessDown,
-    KbdIllumUp,
-    KbdIllumDown,
-    K0xAA,
-    K0xAB,
-    K0xAC,
-    K0xAD,
-    K0xAE,
-    K0xAF,
-    K0xB0,
-    K0xB1,
-    K0xB2,
-    K0xB3,
-    K0xB4,
-    K0xB5,
-    K0xB6,
-    K0xB7,
-    K0xB8,
-    K0xB9,
-    K0xBA,
-    K0xBB,
-    K0xBC,
-    K0xBD,
-    K0xBE,
-    K0xBF,
-    K0xC0,
-    K0xC1,
-    K0xC2,
-    K0xC3,
-    K0xC4,
-    K0xC5,
-    K0xC6,
-    K0xC7,
-    K0xC8,
-    K0xC9,
-    K0xCA,
-    K0xCB,
-    K0xCC,
-    K0xCD,
-    K0xCE,
-    K0xCF,
-    K0xD0,
-    K0xD1,
-    K0xD2,
-    K0xD3,
-    K0xD4,
-    K0xD5,
-    K0xD6,
-    K0xD7,
-    K0xD8,
-    K0xD9,
-    K0xDA,
-    K0xDB,
-    K0xDC,
-    K0xDD,
-    K0xDE,
-    K0xDF,
-
-    // Modifiers
-    /// Left Control.
-    LCtrl = 0xE0,
-    /// Left Shift.
-    LShift,
-    /// Left Alt.
-    LAlt,
-    /// Left GUI (the Windows key).
-    LGui,
-    /// Right Control.
-    RCtrl,
-    /// Right Shift.
-    RShift,
-    /// Right Alt (or Alt Gr).
-    RAlt,
-    /// Right GUI (the Windows key).
-    RGui, // 0xE7
-
-    // Unofficial
-    MediaPlayPause = 0xE8,
-    MediaStopCD,
-    MediaPreviousSong,
-    MediaNextSong,
-    MediaEjectCD,
-    MediaVolUp,
-    MediaVolDown,
-    MediaMute,
-    MediaWWW, // 0xF0
-    MediaBack,
-    MediaForward,
-    MediaStop,
-    MediaFind,
-    MediaScrollUp,
-    MediaScrollDown,
-    MediaEdit,
-    MediaSleep,
-    MediaCoffee,
-    MediaRefresh,
-    MediaCalc, // 0xFB
-
-    K252,
-    K253,
-    K254,
-    K255,
-    K256,
-    K257,
-    K258,
-    K259,
-    K260,
-    K261,
-    K262,
-    K263,
-    K264,
-    K265,
-    K266,
-    K267,
-    K268,
-    K269,
-    K270,
-    K271,
-    K272,
-    K273,
-    K274,
-    K275,
-    K276,
-    K277,
-    K278,
-    K279,
-    K280,
-    K281,
-    K282,
-    K283,
-    K284,
-    K285,
-    K286,
-    K287,
-    K288,
-    K289,
-    K290,
-    K291,
-    K292,
-    K293,
-    K294,
-    K295,
-    K296,
-    K297,
-    K298,
-    K299,
-    K300,
-    K301,
-    K302,
-    K303,
-    K304,
-    K305,
-    K306,
-    K307,
-    K308,
-    K309,
-    K310,
-    K311,
-    K312,
-    K313,
-    K314,
-    K315,
-    K316,
-    K317,
-    K318,
-    K319,
-    K320,
-    K321,
-    K322,
-    K323,
-    K324,
-    K325,
-    K326,
-    K327,
-    K328,
-    K329,
-    K330,
-    K331,
-    K332,
-    K333,
-    K334,
-    K335,
-    K336,
-    K337,
-    K338,
-    K339,
-    K340,
-    K341,
-    K342,
-    K343,
-    K344,
-    K345,
-    K346,
-    K347,
-    K348,
-    K349,
-    K350,
-    K351,
-    K352,
-    K353,
-    K354,
-    K355,
-    K356,
-    K357,
-    K358,
-    K359,
-    K360,
-    K361,
-    K362,
-    K363,
-    K364,
-    K365,
-    K366,
-    K367,
-    K368,
-    K369,
-    K370,
-    K371,
-    K372,
-    K373,
-    K374,
-    K375,
-    K376,
-    K377,
-    K378,
-    K379,
-    K380,
-    K381,
-    K382,
-    K383,
-    K384,
-    K385,
-    K386,
-    K387,
-    K388,
-    K389,
-    K390,
-    K391,
-    K392,
-    K393,
-    K394,
-    K395,
-    K396,
-    K397,
-    K398,
-    K399,
-    K400,
-    K401,
-    K402,
-    K403,
-    K404,
-    K405,
-    K406,
-    K407,
-    K408,
-    K409,
-    K410,
-    K411,
-    K412,
-    K413,
-    K414,
-    K415,
-    K416,
-    K417,
-    K418,
-    K419,
-    K420,
-    K421,
-    K422,
-    K423,
-    K424,
-    K425,
-    K426,
-    K427,
-    K428,
-    K429,
-    K430,
-    K431,
-    K432,
-    K433,
-    K434,
-    K435,
-    K436,
-    K437,
-    K438,
-    K439,
-    K440,
-    K441,
-    K442,
-    K443,
-    K444,
-    K445,
-    K446,
-    K447,
-    K448,
-    K449,
-    K450,
-    K451,
-    K452,
-    K453,
-    K454,
-    K455,
-    K456,
-    K457,
-    K458,
-    K459,
-    K460,
-    K461,
-    K462,
-    K463,
-    K464,
-    K465,
-    K466,
-    K467,
-    K468,
-    K469,
-    K470,
-    K471,
-    K472,
-    K473,
-    K474,
-    K475,
-    K476,
-    K477,
-    K478,
-    K479,
-    K480,
-    K481,
-    K482,
-    K483,
-    K484,
-    K485,
-    K486,
-    K487,
-    K488,
-    K489,
-    K490,
-    K491,
-    K492,
-    K493,
-    K494,
-    K495,
-    K496,
-    K497,
-    K498,
-    K499,
-    K500,
-    K501,
-    K502,
-    K503,
-    K504,
-    K505,
-    K506,
-    K507,
-    K508,
-    K509,
-    K510,
-    K511,
-    K512,
-    K513,
-    K514,
-    K515,
-    K516,
-    K517,
-    K518,
-    K519,
-    K520,
-    K521,
-    K522,
-    K523,
-    K524,
-    K525,
-    K526,
-    K527,
-    K528,
-    K529,
-    K530,
-    K531,
-    K532,
-    K533,
-    K534,
-    K535,
-    K536,
-    K537,
-    K538,
-    K539,
-    K540,
-    K541,
-    K542,
-    K543,
-    K544,
-    K545,
-    K546,
-    K547,
-    K548,
-    K549,
-    K550,
-    K551,
-    K552,
-    K553,
-    K554,
-    K555,
-    K556,
-    K557,
-    K558,
-    K559,
-    K560,
-    K561,
-    K562,
-    K563,
-    K564,
-    K565,
-    K566,
-    K567,
-    K568,
-    K569,
-    K570,
-    K571,
-    K572,
-    K573,
-    K574,
-    K575,
-    K576,
-    K577,
-    K578,
-    K579,
-    K580,
-    K581,
-    K582,
-    K583,
-    K584,
-    K585,
-    K586,
-    K587,
-    K588,
-    K589,
-    K590,
-    K591,
-    K592,
-    K593,
-    K594,
-    K595,
-    K596,
-    K597,
-    K598,
-    K599,
-    K600,
-    K601,
-    K602,
-    K603,
-    K604,
-    K605,
-    K606,
-    K607,
-    K608,
-    K609,
-    K610,
-    K611,
-    K612,
-    K613,
-    K614,
-    K615,
-    K616,
-    K617,
-    K618,
-    K619,
-    K620,
-    K621,
-    K622,
-    K623,
-    K624,
-    K625,
-    K626,
-    K627,
-    K628,
-    K629,
-    K630,
-    K631,
-    K632,
-    K633,
-    K634,
-    K635,
-    K636,
-    K637,
-    K638,
-    K639,
-    K640,
-    K641,
-    K642,
-    K643,
-    K644,
-    K645,
-    K646,
-    K647,
-    K648,
-    K649,
-    K650,
-    K651,
-    K652,
-    K653,
-    K654,
-    K655,
-    K656,
-    K657,
-    K658,
-    K659,
-    K660,
-    K661,
-    K662,
-    K663,
-    K664,
-    K665,
-    K666,
-    K667,
-    K668,
-    K669,
-    K670,
-    K671,
-    K672,
-    K673,
-    K674,
-    K675,
-    K676,
-    K677,
-    K678,
-    K679,
-    K680,
-    K681,
-    K682,
-    K683,
-    K684,
-    K685,
-    K686,
-    K687,
-    K688,
-    K689,
-    K690,
-    K691,
-    K692,
-    K693,
-    K694,
-    K695,
-    K696,
-    K697,
-    K698,
-    K699,
-    K700,
-    K701,
-    K702,
-    K703,
-    K704,
-    K705,
-    K706,
-    K707,
-    K708,
-    K709,
-    K710,
-    K711,
-    K712,
-    K713,
-    K714,
-    K715,
-    K716,
-    K717,
-    K718,
-    K719,
-    K720,
-    K721,
-    K722,
-    K723,
-    K724,
-    K725,
-    K726,
-    K727,
-    K728,
-    K729,
-    K730,
-    K731,
-    K732,
-    K733,
-    K734,
-    K735,
-    K736,
-    K737,
-    K738,
-    K739,
-    K740,
-    K741,
-    K742,
-    K743,
-    K744,
+    ErrorUndefined = 0,
+    Escape = 1,
+    Kb1 = 2,
+    Kb2 = 3,
+    Kb3 = 4,
+    Kb4 = 5,
+    Kb5 = 6,
+    Kb6 = 7,
+    Kb7 = 8,
+    Kb8 = 9,
+    Kb9 = 10,
+    Kb0 = 11,
+    Minus = 12,
+    Equal = 13,
+    BSpace = 14,
+    Tab = 15,
+    Q = 16,
+    W = 17,
+    E = 18,
+    R = 19,
+    T = 20,
+    Y = 21,
+    U = 22,
+    I = 23,
+    O = 24,
+    P = 25,
+    LBracket = 26,
+    RBracket = 27,
+    Enter = 28,
+    LCtrl = 29,
+    A = 30,
+    S = 31,
+    D = 32,
+    F = 33,
+    G = 34,
+    H = 35,
+    J = 36,
+    K = 37,
+    L = 38,
+    SColon = 39,
+    Quote = 40,
+    Grave = 41,
+    LShift = 42,
+    Bslash = 43,
+    Z = 44,
+    X = 45,
+    C = 46,
+    V = 47,
+    B = 48,
+    N = 49,
+    M = 50,
+    Comma = 51,
+    Dot = 52,
+    Slash = 53,
+    RShift = 54,
+    KpAsterisk = 55,
+    LAlt = 56,
+    Space = 57,
+    CapsLock = 58,
+    F1 = 59,
+    F2 = 60,
+    F3 = 61,
+    F4 = 62,
+    F5 = 63,
+    F6 = 64,
+    F7 = 65,
+    F8 = 66,
+    F9 = 67,
+    F10 = 68,
+    NumLock = 69,
+    ScrollLock = 70,
+    Kp7 = 71,
+    Kp8 = 72,
+    Kp9 = 73,
+    KpMinus = 74,
+    Kp4 = 75,
+    Kp5 = 76,
+    Kp6 = 77,
+    KpPlus = 78,
+    Kp1 = 79,
+    Kp2 = 80,
+    Kp3 = 81,
+    Kp0 = 82,
+    KpDot = 83,
+    K0xBF = 84,
+    K0xC0 = 85,
+    NonUsBslash = 86,
+    F11 = 87,
+    F12 = 88,
+    Intl1 = 89,
+    K0xB1 = 90,
+    K0xB3 = 91,
+    K0xB0 = 92,
+    K0xB2 = 93,
+    K0xAF = 94,
+    NonUsHash = 95,
+    KpEnter = 96,
+    RCtrl = 97,
+    KpSlash = 98,
+    SysReq = 99,
+    RAlt = 100,
+    K0xC1 = 101,
+    Home = 102,
+    Up = 103,
+    PgUp = 104,
+    Left = 105,
+    Right = 106,
+    End = 107,
+    Down = 108,
+    PgDown = 109,
+    Insert = 110,
+    Delete = 111,
+    K0xC2 = 112,
+    Mute = 113,
+    VolDown = 114,
+    VolUp = 115,
+    Power = 116,
+    KpEqual = 117,
+    K0xC3 = 118,
+    Pause = 119,
+    K0xC4 = 120,
+    KpComma = 121,
+    Lang1 = 122,
+    Lang2 = 123,
+    Intl3 = 124,
+    LGui = 125,
+    RGui = 126,
+    Application = 127,
+    Stop = 128,
+    Again = 129,
+    K0xC5 = 130,
+    Undo = 131,
+    K0xC6 = 132,
+    Copy = 133,
+    K0xC7 = 134,
+    Paste = 135,
+    Find = 136,
+    Cut = 137,
+    Help = 138,
+    Menu = 139,
+    MediaCalc = 140,
+    K0xC8 = 141,
+    MediaSleep = 142,
+    Wakeup = 143,
+    K0xC9 = 144,
+    K0xCA = 145,
+    K0xCB = 146,
+    K0xCC = 147,
+    K0xCD = 148,
+    K0xCE = 149,
+    MediaWWW = 150,
+    K0xCF = 151,
+    MediaCoffee = 152,
+    K0xD0 = 153,
+    K0xD1 = 154,
+    K0xAE = 155,
+    K0xD2 = 156,
+    K0xD3 = 157,
+    MediaBack = 158,
+    MediaForward = 159,
+    MediaStop = 160,
+    MediaEjectCD = 161,
+    MediaFind = 162,
+    MediaNextSong = 163,
+    MediaPlayPause = 164,
+    MediaPreviousSong = 165,
+    MediaStopCD = 166,
+    K0xD4 = 167,
+    K0xD5 = 168,
+    K0xD6 = 169,
+    K0xD7 = 170,
+    K0xD8 = 171,
+    K0xAD = 172,
+    MediaRefresh = 173,
+    K0xD9 = 174,
+    K0xDA = 175,
+    MediaEdit = 176,
+    MediaScrollUp = 177,
+    MediaScrollDown = 178,
+    K0xDB = 179,
+    K0xDC = 180,
+    K0xDD = 181,
+    K0xDE = 182,
+    F13 = 183,
+    F14 = 184,
+    F15 = 185,
+    F16 = 186,
+    F17 = 187,
+    F18 = 188,
+    F19 = 189,
+    F20 = 190,
+    F21 = 191,
+    F22 = 192,
+    F23 = 193,
+    F24 = 194,
+    Execute = 195,
+    LockingCapsLock = 196,
+    LockingNumLock = 197,
+    LockingScrollLock = 198,
+    KpEqualSign = 199,
+    Intl2 = 200,
+    Intl4 = 201,
+    Intl5 = 202,
+    Intl6 = 203,
+    Intl7 = 204,
+    Intl8 = 205,
+    Intl9 = 206,
+    Select = 207,
+    Lang3 = 208,
+    Lang4 = 209,
+    PScreen = 210,
+    Lang5 = 211,
+    Lang6 = 212,
+    Lang7 = 213,
+    Lang8 = 214,
+    K0xAB = 215,
+    Lang9 = 216,
+    K0xDF = 217,
+    K0xBE = 218,
+    Clear = 219,
+    K220 = 220,
+    K0xAC = 221,
+    AltErase = 222,
+    Cancel = 223,
+    BrightnessDown = 224,
+    BrightnessUp = 225,
+    K0xAA = 226,
+    Prior = 227,
+    Return = 228,
+    KbdIllumDown = 229,
+    KbdIllumUp = 230,
+    Separator = 231,
+    Out = 232,
+    Oper = 233,
+    ClearAgain = 234,
+    CrSel = 235,
+    ExSel = 236,
+    K0xB4 = 237,
+    K0xB5 = 238,
+    K0xB6 = 239,
+    No = 240,
+    K0xB7 = 241,
+    K0xB8 = 242,
+    K0xB9 = 243,
+    K0xBA = 244,
+    K0xBB = 245,
+    K0xBC = 246,
+    K0xBD = 247,
+    MediaMute = 248,
+    K249 = 249,
+    PostFail = 250,
+    ErrorRollOver = 251,
+    K252 = 252,
+    K253 = 253,
+    K254 = 254,
+    K255 = 255,
+    K256 = 256,
+    K257 = 257,
+    K258 = 258,
+    K259 = 259,
+    K260 = 260,
+    K261 = 261,
+    K262 = 262,
+    K263 = 263,
+    K264 = 264,
+    K265 = 265,
+    K266 = 266,
+    K267 = 267,
+    K268 = 268,
+    K269 = 269,
+    K270 = 270,
+    K271 = 271,
+    K272 = 272,
+    K273 = 273,
+    K274 = 274,
+    K275 = 275,
+    K276 = 276,
+    K277 = 277,
+    K278 = 278,
+    K279 = 279,
+    K280 = 280,
+    K281 = 281,
+    K282 = 282,
+    K283 = 283,
+    K284 = 284,
+    K285 = 285,
+    K286 = 286,
+    K287 = 287,
+    K288 = 288,
+    K289 = 289,
+    K290 = 290,
+    K291 = 291,
+    K292 = 292,
+    K293 = 293,
+    K294 = 294,
+    K295 = 295,
+    K296 = 296,
+    K297 = 297,
+    K298 = 298,
+    K299 = 299,
+    K300 = 300,
+    K301 = 301,
+    K302 = 302,
+    K303 = 303,
+    K304 = 304,
+    K305 = 305,
+    K306 = 306,
+    K307 = 307,
+    K308 = 308,
+    K309 = 309,
+    K310 = 310,
+    K311 = 311,
+    K312 = 312,
+    K313 = 313,
+    K314 = 314,
+    K315 = 315,
+    K316 = 316,
+    K317 = 317,
+    K318 = 318,
+    K319 = 319,
+    K320 = 320,
+    K321 = 321,
+    K322 = 322,
+    K323 = 323,
+    K324 = 324,
+    K325 = 325,
+    K326 = 326,
+    K327 = 327,
+    K328 = 328,
+    K329 = 329,
+    K330 = 330,
+    K331 = 331,
+    K332 = 332,
+    K333 = 333,
+    K334 = 334,
+    K335 = 335,
+    K336 = 336,
+    K337 = 337,
+    K338 = 338,
+    K339 = 339,
+    K340 = 340,
+    K341 = 341,
+    K342 = 342,
+    K343 = 343,
+    K344 = 344,
+    K345 = 345,
+    K346 = 346,
+    K347 = 347,
+    K348 = 348,
+    K349 = 349,
+    K350 = 350,
+    K351 = 351,
+    K352 = 352,
+    K353 = 353,
+    K354 = 354,
+    K355 = 355,
+    K356 = 356,
+    K357 = 357,
+    K358 = 358,
+    K359 = 359,
+    K360 = 360,
+    K361 = 361,
+    K362 = 362,
+    K363 = 363,
+    K364 = 364,
+    K365 = 365,
+    K366 = 366,
+    K367 = 367,
+    K368 = 368,
+    K369 = 369,
+    K370 = 370,
+    K371 = 371,
+    K372 = 372,
+    K373 = 373,
+    K374 = 374,
+    K375 = 375,
+    K376 = 376,
+    K377 = 377,
+    K378 = 378,
+    K379 = 379,
+    K380 = 380,
+    K381 = 381,
+    K382 = 382,
+    K383 = 383,
+    K384 = 384,
+    K385 = 385,
+    K386 = 386,
+    K387 = 387,
+    K388 = 388,
+    K389 = 389,
+    K390 = 390,
+    K391 = 391,
+    K392 = 392,
+    K393 = 393,
+    K394 = 394,
+    K395 = 395,
+    K396 = 396,
+    K397 = 397,
+    K398 = 398,
+    K399 = 399,
+    K400 = 400,
+    K401 = 401,
+    K402 = 402,
+    K403 = 403,
+    K404 = 404,
+    K405 = 405,
+    K406 = 406,
+    K407 = 407,
+    K408 = 408,
+    K409 = 409,
+    K410 = 410,
+    K411 = 411,
+    K412 = 412,
+    K413 = 413,
+    K414 = 414,
+    K415 = 415,
+    K416 = 416,
+    K417 = 417,
+    K418 = 418,
+    K419 = 419,
+    K420 = 420,
+    K421 = 421,
+    K422 = 422,
+    K423 = 423,
+    K424 = 424,
+    K425 = 425,
+    K426 = 426,
+    K427 = 427,
+    K428 = 428,
+    K429 = 429,
+    K430 = 430,
+    K431 = 431,
+    K432 = 432,
+    K433 = 433,
+    K434 = 434,
+    K435 = 435,
+    K436 = 436,
+    K437 = 437,
+    K438 = 438,
+    K439 = 439,
+    K440 = 440,
+    K441 = 441,
+    K442 = 442,
+    K443 = 443,
+    K444 = 444,
+    K445 = 445,
+    K446 = 446,
+    K447 = 447,
+    K448 = 448,
+    K449 = 449,
+    K450 = 450,
+    K451 = 451,
+    K452 = 452,
+    K453 = 453,
+    K454 = 454,
+    K455 = 455,
+    K456 = 456,
+    K457 = 457,
+    K458 = 458,
+    K459 = 459,
+    K460 = 460,
+    K461 = 461,
+    K462 = 462,
+    K463 = 463,
+    K464 = 464,
+    K465 = 465,
+    K466 = 466,
+    K467 = 467,
+    K468 = 468,
+    K469 = 469,
+    K470 = 470,
+    K471 = 471,
+    K472 = 472,
+    K473 = 473,
+    K474 = 474,
+    K475 = 475,
+    K476 = 476,
+    K477 = 477,
+    K478 = 478,
+    K479 = 479,
+    K480 = 480,
+    K481 = 481,
+    K482 = 482,
+    K483 = 483,
+    K484 = 484,
+    K485 = 485,
+    K486 = 486,
+    K487 = 487,
+    K488 = 488,
+    K489 = 489,
+    K490 = 490,
+    K491 = 491,
+    K492 = 492,
+    K493 = 493,
+    K494 = 494,
+    K495 = 495,
+    K496 = 496,
+    K497 = 497,
+    K498 = 498,
+    K499 = 499,
+    K500 = 500,
+    K501 = 501,
+    K502 = 502,
+    K503 = 503,
+    K504 = 504,
+    K505 = 505,
+    K506 = 506,
+    K507 = 507,
+    K508 = 508,
+    K509 = 509,
+    K510 = 510,
+    K511 = 511,
+    K512 = 512,
+    K513 = 513,
+    K514 = 514,
+    K515 = 515,
+    K516 = 516,
+    K517 = 517,
+    K518 = 518,
+    K519 = 519,
+    K520 = 520,
+    K521 = 521,
+    K522 = 522,
+    K523 = 523,
+    K524 = 524,
+    K525 = 525,
+    K526 = 526,
+    K527 = 527,
+    K528 = 528,
+    K529 = 529,
+    K530 = 530,
+    K531 = 531,
+    K532 = 532,
+    K533 = 533,
+    K534 = 534,
+    K535 = 535,
+    K536 = 536,
+    K537 = 537,
+    K538 = 538,
+    K539 = 539,
+    K540 = 540,
+    K541 = 541,
+    K542 = 542,
+    K543 = 543,
+    K544 = 544,
+    K545 = 545,
+    K546 = 546,
+    K547 = 547,
+    K548 = 548,
+    K549 = 549,
+    K550 = 550,
+    K551 = 551,
+    K552 = 552,
+    K553 = 553,
+    K554 = 554,
+    K555 = 555,
+    K556 = 556,
+    K557 = 557,
+    K558 = 558,
+    K559 = 559,
+    K560 = 560,
+    K561 = 561,
+    K562 = 562,
+    K563 = 563,
+    K564 = 564,
+    K565 = 565,
+    K566 = 566,
+    K567 = 567,
+    K568 = 568,
+    K569 = 569,
+    K570 = 570,
+    K571 = 571,
+    K572 = 572,
+    K573 = 573,
+    K574 = 574,
+    K575 = 575,
+    K576 = 576,
+    K577 = 577,
+    K578 = 578,
+    K579 = 579,
+    K580 = 580,
+    K581 = 581,
+    K582 = 582,
+    K583 = 583,
+    K584 = 584,
+    K585 = 585,
+    K586 = 586,
+    K587 = 587,
+    K588 = 588,
+    K589 = 589,
+    K590 = 590,
+    K591 = 591,
+    K592 = 592,
+    K593 = 593,
+    K594 = 594,
+    K595 = 595,
+    K596 = 596,
+    K597 = 597,
+    K598 = 598,
+    K599 = 599,
+    K600 = 600,
+    K601 = 601,
+    K602 = 602,
+    K603 = 603,
+    K604 = 604,
+    K605 = 605,
+    K606 = 606,
+    K607 = 607,
+    K608 = 608,
+    K609 = 609,
+    K610 = 610,
+    K611 = 611,
+    K612 = 612,
+    K613 = 613,
+    K614 = 614,
+    K615 = 615,
+    K616 = 616,
+    K617 = 617,
+    K618 = 618,
+    K619 = 619,
+    K620 = 620,
+    K621 = 621,
+    K622 = 622,
+    K623 = 623,
+    K624 = 624,
+    K625 = 625,
+    K626 = 626,
+    K627 = 627,
+    K628 = 628,
+    K629 = 629,
+    K630 = 630,
+    K631 = 631,
+    K632 = 632,
+    K633 = 633,
+    K634 = 634,
+    K635 = 635,
+    K636 = 636,
+    K637 = 637,
+    K638 = 638,
+    K639 = 639,
+    K640 = 640,
+    K641 = 641,
+    K642 = 642,
+    K643 = 643,
+    K644 = 644,
+    K645 = 645,
+    K646 = 646,
+    K647 = 647,
+    K648 = 648,
+    K649 = 649,
+    K650 = 650,
+    K651 = 651,
+    K652 = 652,
+    K653 = 653,
+    K654 = 654,
+    K655 = 655,
+    K656 = 656,
+    K657 = 657,
+    K658 = 658,
+    K659 = 659,
+    K660 = 660,
+    K661 = 661,
+    K662 = 662,
+    K663 = 663,
+    K664 = 664,
+    K665 = 665,
+    K666 = 666,
+    K667 = 667,
+    K668 = 668,
+    K669 = 669,
+    K670 = 670,
+    K671 = 671,
+    K672 = 672,
+    K673 = 673,
+    K674 = 674,
+    K675 = 675,
+    K676 = 676,
+    K677 = 677,
+    K678 = 678,
+    K679 = 679,
+    K680 = 680,
+    K681 = 681,
+    K682 = 682,
+    K683 = 683,
+    K684 = 684,
+    K685 = 685,
+    K686 = 686,
+    K687 = 687,
+    K688 = 688,
+    K689 = 689,
+    K690 = 690,
+    K691 = 691,
+    K692 = 692,
+    K693 = 693,
+    K694 = 694,
+    K695 = 695,
+    K696 = 696,
+    K697 = 697,
+    K698 = 698,
+    K699 = 699,
+    K700 = 700,
+    K701 = 701,
+    K702 = 702,
+    K703 = 703,
+    K704 = 704,
+    K705 = 705,
+    K706 = 706,
+    K707 = 707,
+    K708 = 708,
+    K709 = 709,
+    K710 = 710,
+    K711 = 711,
+    K712 = 712,
+    K713 = 713,
+    K714 = 714,
+    K715 = 715,
+    K716 = 716,
+    K717 = 717,
+    K718 = 718,
+    K719 = 719,
+    K720 = 720,
+    K721 = 721,
+    K722 = 722,
+    K723 = 723,
+    K724 = 724,
+    K725 = 725,
+    K726 = 726,
+    K727 = 727,
+    K728 = 728,
+    K729 = 729,
+    K730 = 730,
+    K731 = 731,
+    K732 = 732,
+    K733 = 733,
+    K734 = 734,
+    K735 = 735,
+    K736 = 736,
+    K737 = 737,
+    K738 = 738,
+    K739 = 739,
+    K740 = 740,
+    K741 = 741,
+    K742 = 742,
+    K743 = 743,
+    K744 = 744,
+    MWU = 745,
+    MWD = 746,
+    MWL = 747,
+    MWR = 748,
+    K749 = 749,
+    K750 = 750,
+    K751 = 751,
+    K752 = 752,
+    K753 = 753,
+    K754 = 754,
+    K755 = 755,
+    K756 = 756,
+    K757 = 757,
+    K758 = 758,
+    K759 = 759,
+    K760 = 760,
+    K761 = 761,
+    K762 = 762,
+    K763 = 763,
+    K764 = 764,
+    K765 = 765,
+    K766 = 766,
+    KeyMax = 767,
 }
 
 impl KeyCode {
-    /// Returns `true` if the key code corresponds to a modifier (sent
-    /// separately on the USB HID report).
-    pub fn is_modifier(self) -> bool {
-        KeyCode::LCtrl <= self && self <= KeyCode::RGui
-    }
-
-    /// Returns the byte with the bit corresponding to the USB HID
-    /// modifier bitfield set.
-    pub fn as_modifier_bit(self) -> u8 {
-        if self.is_modifier() {
-            1 << (self as u8 - KeyCode::LCtrl as u8)
-        } else {
-            0
-        }
-    }
-}
-
-/// A standard keyboard USB HID report.
-///
-/// It can handle any modifier and 6 keys.
-#[derive(Default, Debug, Clone, Eq, PartialEq)]
-pub struct KbHidReport([u8; 8]);
-
-impl core::iter::FromIterator<KeyCode> for KbHidReport {
-    fn from_iter<T>(iter: T) -> Self
-    where
-        T: IntoIterator<Item = KeyCode>,
-    {
-        let mut res = Self::default();
-        for kc in iter {
-            res.pressed(kc);
-        }
-        res
+    pub fn is_mod(self) -> bool {
+        use KeyCode::*;
+        matches!(
+            self,
+            LShift | RShift | LCtrl | RCtrl | LAlt | RAlt | LGui | RGui
+        )
     }
 }
 
-impl KbHidReport {
-    /// Returns the byte slice corresponding to the report.
-    pub fn as_bytes(&self) -> &[u8] {
-        &self.0
-    }
-
-    /// Add the given key code to the report. If the report is full,
-    /// it will be set to `ErrorRollOver`.
-    pub fn pressed(&mut self, kc: KeyCode) {
-        use KeyCode::*;
-        match kc {
-            No => (),
-            ErrorRollOver | PostFail | ErrorUndefined => self.set_all(kc),
-            kc if kc.is_modifier() => self.0[0] |= kc.as_modifier_bit(),
-            _ => self.0[2..]
-                .iter_mut()
-                .find(|c| **c == 0)
-                .map(|c| *c = kc as u8)
-                .unwrap_or_else(|| self.set_all(ErrorRollOver)),
-        }
-    }
-    fn set_all(&mut self, kc: KeyCode) {
-        for c in &mut self.0[2..] {
-            *c = kc as u8;
+use core::fmt;
+impl fmt::Display for KeyCode {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            KeyCode::Kb1 => write!(f, "1"),
+            KeyCode::Kb2 => write!(f, "2"),
+            KeyCode::Kb3 => write!(f, "3"),
+            KeyCode::Kb4 => write!(f, "4"),
+            KeyCode::Kb5 => write!(f, "5"),
+            KeyCode::Kb6 => write!(f, "6"),
+            KeyCode::Kb7 => write!(f, "7"),
+            KeyCode::Kb8 => write!(f, "8"),
+            KeyCode::Kb9 => write!(f, "9"),
+            KeyCode::Kb0 => write!(f, "0"),
+            KeyCode::LCtrl => write!(f, "‹⎈"),
+            KeyCode::RCtrl => write!(f, "⎈›"),
+            KeyCode::LShift => write!(f, "‹⇧"),
+            KeyCode::RShift => write!(f, "⇧›"),
+            KeyCode::LAlt => write!(f, "‹⎇"),
+            KeyCode::RAlt => write!(f, "⎇›"),
+            KeyCode::LGui => write!(f, "‹◆"),
+            KeyCode::RGui => write!(f, "◆›"),
+            KeyCode::Enter => write!(f, "⏎"),
+            KeyCode::Escape => write!(f, "⎋"),
+            KeyCode::BSpace => write!(f, "␈"),
+            KeyCode::Tab => write!(f, "⭾"),
+            KeyCode::Space => write!(f, "␠"),
+            KeyCode::Minus => write!(f, "−"),
+            KeyCode::Equal => write!(f, "="),
+            KeyCode::LBracket => write!(f, "["),
+            KeyCode::RBracket => write!(f, "]"),
+            KeyCode::Bslash => write!(f, "\\"),
+            KeyCode::NonUsHash => write!(f, "#"),
+            KeyCode::SColon => write!(f, ";"),
+            KeyCode::Quote => write!(f, "'"),
+            KeyCode::Grave => write!(f, "`"),
+            KeyCode::Comma => write!(f, ","),
+            KeyCode::Dot => write!(f, "."),
+            KeyCode::Slash => write!(f, "/"),
+            KeyCode::CapsLock => write!(f, "⇪"),
+            KeyCode::Insert => write!(f, "⎀"),
+            KeyCode::Delete => write!(f, "␡"),
+            KeyCode::Home => write!(f, "⇤"),
+            KeyCode::End => write!(f, "⇥"),
+            KeyCode::PgDown => write!(f, "⇟"),
+            KeyCode::PgUp => write!(f, "⇞"),
+            KeyCode::Down => write!(f, "▼"),
+            KeyCode::Up => write!(f, "▲"),
+            KeyCode::Right => write!(f, "▶"),
+            KeyCode::Left => write!(f, "◀"),
+            KeyCode::NumLock => write!(f, "⇭"),
+            KeyCode::KpSlash => write!(f, "🔢/"),
+            KeyCode::KpAsterisk => write!(f, "🔢*"),
+            KeyCode::KpMinus => write!(f, "🔢−"),
+            KeyCode::KpPlus => write!(f, "🔢+"),
+            KeyCode::KpEnter => write!(f, "🔢⏎"),
+            KeyCode::Kp0 => write!(f, "🔢0"),
+            KeyCode::Kp1 => write!(f, "🔢1"),
+            KeyCode::Kp2 => write!(f, "🔢2"),
+            KeyCode::Kp3 => write!(f, "🔢3"),
+            KeyCode::Kp4 => write!(f, "🔢4"),
+            KeyCode::Kp5 => write!(f, "🔢5"),
+            KeyCode::Kp6 => write!(f, "🔢6"),
+            KeyCode::Kp7 => write!(f, "🔢7"),
+            KeyCode::Kp8 => write!(f, "🔢8"),
+            KeyCode::Kp9 => write!(f, "🔢9"),
+            KeyCode::KpDot => write!(f, "🔢."),
+            KeyCode::KpEqual => write!(f, "🔢="),
+            KeyCode::NonUsBslash => write!(f, "|"),
+            KeyCode::Application => write!(f, "☰"),
+            KeyCode::Mute => write!(f, "🔇"),
+            KeyCode::VolUp => write!(f, "🔊"),
+            KeyCode::VolDown => write!(f, "🔉"),
+            _ => write!(f, "{self:?}"),
         }
     }
 }
diff --git a/keyberon/src/layout.rs b/keyberon/src/layout.rs
index 9ba8391ee..93bf0d6a0 100644
--- a/keyberon/src/layout.rs
+++ b/keyberon/src/layout.rs
@@ -22,14 +22,22 @@
 /// to do when not using a macro.
 pub use kanata_keyberon_macros::*;
 
-use crate::action::*;
+mod contextual_execution;
+use contextual_execution::*;
+
+use std::num::NonZeroU16;
+
+use crate::chord::*;
 use crate::key_code::KeyCode;
+use crate::{action::*, multikey_buffer::MultiKeyBuffer};
 use arraydeque::ArrayDeque;
 use heapless::Vec;
 
 use State::*;
 
 /// The coordinate type.
+/// First item is either 0 or 1 denoting real key or virtual key, respectively.
+/// Second item is the position in layout.
 pub type KCoord = (u8, u16);
 
 /// The Layers type.
@@ -39,45 +47,154 @@ pub type KCoord = (u8, u16);
 /// corresponds to the key on the first layer, row 2, column 3.
 /// The generic parameters are in order: the number of columns, rows and layers,
 /// and the type contained in custom actions.
-pub type Layers<'a, const C: usize, const R: usize, const L: usize, T = core::convert::Infallible> =
-    [[[Action<'a, T>; C]; R]; L];
+pub type Layers<'a, const C: usize, const R: usize, T = core::convert::Infallible> =
+    &'a [[[Action<'a, T>; C]; R]];
 
 const QUEUE_SIZE: usize = 32;
+pub type QueueLen = u8;
+
+#[test]
+fn check_queue_size() {
+    use std::convert::TryFrom;
+    let _v = QueueLen::try_from(QUEUE_SIZE).unwrap();
+}
 
 /// The current event queue.
 ///
 /// Events can be retrieved by iterating over this struct and calling [Queued::event].
-type Queue = ArrayDeque<[Queued; QUEUE_SIZE], arraydeque::behavior::Wrapping>;
+pub(crate) type Queue = ArrayDeque<Queued, QUEUE_SIZE, arraydeque::behavior::Wrapping>;
 
 /// A list of queued press events. Used for special handling of potentially multiple press events
 /// that occur during a Waiting event.
-type PressedQueue = ArrayDeque<[KCoord; QUEUE_SIZE]>;
+type PressedQueue = ArrayDeque<KCoord, QUEUE_SIZE>;
+
+/// The maximum number of actions that can be activated concurrently via chord decomposition or
+/// activation of multiple switch cases using fallthrough.
+pub const ACTION_QUEUE_LEN: usize = 8;
+
+pub const CUSTOM_EVENT_RELEASE_QUEUE_LEN: usize = 16;
 
 /// The queue is currently only used for chord decomposition when a longer chord does not result in
 /// an action, but splitting it into smaller chords would. The buffer size of 8 should be more than
 /// enough for real world usage, but if one wanted to be extra safe, this should be ChordKeys::BITS
 /// since that should guarantee that all potentially queueable actions can fit.
-type ActionQueue<'a, T> = ArrayDeque<[QueuedAction<'a, T>; 8], arraydeque::behavior::Wrapping>;
-type QueuedAction<'a, T> = Option<(KCoord, &'a Action<'a, T>)>;
+type ActionQueue<'a, T> =
+    ArrayDeque<QueuedAction<'a, T>, ACTION_QUEUE_LEN, arraydeque::behavior::Wrapping>;
+type CustomEventReleaseQueue<'a, T> =
+    ArrayDeque<&'a T, CUSTOM_EVENT_RELEASE_QUEUE_LEN, arraydeque::behavior::Wrapping>;
+type Delay = u16;
+pub(crate) type QueuedAction<'a, T> = Option<(KCoord, Delay, &'a Action<'a, T>, LayerStack)>;
+
+pub const REAL_KEY_ROW: u8 = 0;
+
+const HISTORICAL_EVENT_LEN: usize = 8;
+const EXTRA_WAITING_LEN: usize = 8;
+#[test]
+fn extra_waiting_size_constraint() {
+    assert!(EXTRA_WAITING_LEN < i8::MAX as usize);
+}
 
 /// The layout manager. It takes `Event`s and `tick`s as input, and
 /// generate keyboard reports.
-pub struct Layout<'a, const C: usize, const R: usize, const L: usize, T = core::convert::Infallible>
+pub struct Layout<'a, const C: usize, const R: usize, T = core::convert::Infallible>
 where
     T: 'a + std::fmt::Debug,
 {
-    pub layers: &'a [[[Action<'a, T>; C]; R]; L],
+    /// Fallback for transparent keys inside actions that are on `default_layer`.
+    pub src_keys: &'a [Action<'a, T>; C],
+    pub layers: &'a [[[Action<'a, T>; C]; R]],
     pub default_layer: usize,
     /// Key states.
     pub states: Vec<State<'a, T>, 64>,
     pub waiting: Option<WaitingState<'a, T>>,
+    pub extra_waiting:
+        ArrayDeque<WaitingState<'a, T>, EXTRA_WAITING_LEN, arraydeque::behavior::Wrapping>,
     pub tap_dance_eager: Option<TapDanceEagerState<'a, T>>,
     pub queue: Queue,
     pub oneshot: OneShotState,
+    pub keys_to_suppress_for_one_cycle: Vec<KeyCode, 8>,
     pub last_press_tracker: LastPressTracker,
-    pub active_sequences: ArrayDeque<[SequenceState<'a, T>; 4], arraydeque::behavior::Wrapping>,
+    pub active_sequences: ArrayDeque<SequenceState<'a, T>, 4, arraydeque::behavior::Wrapping>,
     pub action_queue: ActionQueue<'a, T>,
-    pub prev_action: Option<&'a Action<'a, T>>,
+    pub custom_event_release_queue: CustomEventReleaseQueue<'a, T>,
+    pub rpt_action: Option<&'a Action<'a, T>>,
+    pub historical_keys: History<KeyCode>,
+    pub historical_inputs: History<KCoord>,
+    /// Historical inputs where tap-holds that resolve to a hold or timeout are deleted.
+    /// Used for prior-idle calculations.
+    /// Ideally whether timeout behaviour is excluded would be configurable such that
+    /// timeout activations are only excluded when the timeout would resolve
+    /// to the same action as hold.
+    /// For now avoid that complexity, such behaviour can be added later via a flag on the
+    /// TapHoldConfiguration without much concern if it is desired.
+    pub historical_inputs_sans_holds_or_timeouts: History<KCoord>,
+    pub quick_tap_hold_timeout: bool,
+    /// If a different key was pressed within this many ticks before a HoldTap key,
+    /// immediately resolve as tap (typing streak detection). 0 = disabled.
+    pub tap_hold_require_prior_idle: u16,
+    pub chords_v2: Option<ChordsV2<'a, T>>,
+    /// History of device IDs that sent events, most-recent-first.
+    /// Used by `(device-history N recency)` switch conditions.
+    pub device_history: ArrayDeque<Option<std::num::NonZeroU8>, 8, arraydeque::behavior::Wrapping>,
+    rpt_multikey_key_buffer: MultiKeyBuffer<'a, T>,
+    trans_resolution_behavior_v2: bool,
+    delegate_to_first_layer: bool,
+    contextual_execution: ContextualExecution,
+    /// Tracks tap-hold activation events (hold/tap resolved).
+    /// Only stores data when the `tap_hold_tracker` feature is enabled;
+    /// otherwise this is a zero-sized no-op.
+    pub tap_hold_tracker: crate::tap_hold_tracker::TapHoldTracker,
+}
+
+pub use crate::tap_hold_tracker::{HoldActivatedInfo, TapActivatedInfo};
+
+#[derive(Debug)]
+pub struct History<T> {
+    events: ArrayDeque<T, HISTORICAL_EVENT_LEN, arraydeque::behavior::Wrapping>,
+    ticks_since_occurrences: ArrayDeque<u16, HISTORICAL_EVENT_LEN, arraydeque::behavior::Wrapping>,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct HistoricalEvent<T> {
+    pub event: T,
+    pub ticks_since_occurrence: u16,
+}
+
+impl<T> History<T>
+where
+    T: Copy,
+{
+    fn new() -> Self {
+        Self {
+            ticks_since_occurrences: ArrayDeque::new(),
+            events: ArrayDeque::new(),
+        }
+    }
+
+    fn tick_hist(&mut self) {
+        let ticks = self.ticks_since_occurrences.as_uninit_slice_mut();
+        for tick_count in ticks {
+            unsafe {
+                *tick_count.assume_init_mut() = tick_count.assume_init().saturating_add(1);
+            }
+        }
+    }
+
+    fn push_front(&mut self, event: T) {
+        self.ticks_since_occurrences.push_front(0);
+        self.events.push_front(event);
+    }
+
+    pub fn iter_hevents(&self) -> impl Iterator<Item = HistoricalEvent<T>> + '_ + Clone {
+        self.events
+            .iter()
+            .copied()
+            .zip(self.ticks_since_occurrences.iter().copied())
+            .map(|(event, ticks_since_occurrence)| HistoricalEvent {
+                event,
+                ticks_since_occurrence,
+            })
+    }
 }
 
 /// An event on the key matrix.
@@ -149,7 +266,7 @@ pub enum CustomEvent<'a, T: 'a> {
     /// The given custom action key is released.
     Release(&'a T),
 }
-impl<'a, T> CustomEvent<'a, T> {
+impl<T> CustomEvent<'_, T> {
     /// Update an event according to a new event.
     ///
     ///The event can only be modified in the order `NoEvent < Press <
@@ -164,11 +281,28 @@ impl<'a, T> CustomEvent<'a, T> {
     }
 }
 
+/// Metadata about normal key flags.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub struct NormalKeyFlags(pub u8);
+
+pub const NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION: u8 = 0x01;
+pub const NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE: u8 = 0x02;
+
+impl NormalKeyFlags {
+    pub fn nkf_clear_on_next_action(self) -> bool {
+        (self.0 & NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION) == NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION
+    }
+    pub fn nkf_clear_on_next_release(self) -> bool {
+        (self.0 & NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE) == NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE
+    }
+}
+
 #[derive(Debug, Eq, PartialEq)]
 pub enum State<'a, T: 'a> {
     NormalKey {
         keycode: KeyCode,
         coord: KCoord,
+        flags: NormalKeyFlags,
     },
     LayerModifier {
         value: usize,
@@ -188,36 +322,71 @@ pub enum State<'a, T: 'a> {
     SeqCustomPending(&'a T),
     SeqCustomActive(&'a T),
     Tombstone,
+    NoOpInput {
+        coord: KCoord,
+    },
 }
-impl<'a, T> Copy for State<'a, T> {}
-impl<'a, T> Clone for State<'a, T> {
+impl<T> Copy for State<'_, T> {}
+impl<T> Clone for State<'_, T> {
     fn clone(&self) -> Self {
         *self
     }
 }
 impl<'a, T: 'a> State<'a, T> {
-    fn keycode(&self) -> Option<KeyCode> {
+    pub fn keycode(&self) -> Option<KeyCode> {
         match self {
             NormalKey { keycode, .. } => Some(*keycode),
             FakeKey { keycode } => Some(*keycode),
             _ => None,
         }
     }
-    fn tick(&self) -> Option<Self> {
-        Some(*self)
+    pub fn coord(&self) -> Option<KCoord> {
+        match self {
+            NormalKey { coord, .. }
+            | LayerModifier { coord, .. }
+            | Custom { coord, .. }
+            | NoOpInput { coord }
+            | RepeatingSequence { coord, .. } => Some(*coord),
+            _ => None,
+        }
+    }
+    fn keycode_in_coords(&self, coords: &OneShotCoords) -> Option<KeyCode> {
+        match self {
+            NormalKey { keycode, coord, .. } => {
+                if coords.contains(coord) {
+                    Some(*keycode)
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        }
     }
     /// Returns None if the key has been released and Some otherwise.
-    pub fn release(&self, c: KCoord, custom: &mut CustomEvent<'a, T>) -> Option<Self> {
+    pub fn release(
+        &self,
+        c: KCoord,
+        custom: &mut CustomEvent<'a, T>,
+        custom_release_queue: &mut CustomEventReleaseQueue<'a, T>,
+    ) -> Option<Self> {
         match *self {
             NormalKey { coord, .. }
             | LayerModifier { coord, .. }
             | RepeatingSequence { coord, .. }
+            | NoOpInput { coord }
                 if coord == c =>
             {
                 None
             }
             Custom { value, coord } if coord == c => {
-                custom.update(CustomEvent::Release(value));
+                match custom {
+                    CustomEvent::NoEvent => custom.update(CustomEvent::Release(value)),
+                    _ => {
+                        if custom_release_queue.push_back(value).is_some() {
+                            panic!("overflowed custom action release queue");
+                        }
+                    }
+                }
                 None
             }
             _ => Some(*self),
@@ -225,7 +394,10 @@ impl<'a, T: 'a> State<'a, T> {
     }
     pub fn release_state(&self, s: ReleasableState) -> Option<Self> {
         match (*self, s) {
-            (NormalKey { keycode: k1, .. }, ReleasableState::KeyCode(k2)) => {
+            (
+                NormalKey { keycode: k1, .. } | FakeKey { keycode: k1 },
+                ReleasableState::KeyCode(k2),
+            ) => {
                 if k1 == k2 {
                     None
                 } else {
@@ -254,10 +426,19 @@ impl<'a, T: 'a> State<'a, T> {
             _ => None,
         }
     }
+    pub fn clear_on_next_release(&self) -> bool {
+        match self {
+            NormalKey { flags, .. } => {
+                (flags.0 & NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE)
+                    == NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE
+            }
+            _ => false,
+        }
+    }
 }
 
 #[derive(Copy, Clone, Debug)]
-struct TapDanceState<'a, T: 'a> {
+pub(crate) struct TapDanceState<'a, T: 'a> {
     actions: &'a [&'a Action<'a, T>],
     timeout: u16,
     num_taps: u16,
@@ -272,8 +453,8 @@ pub struct TapDanceEagerState<'a, T: 'a> {
     num_taps: u16,
 }
 
-impl<'a, T> TapDanceEagerState<'a, T> {
-    fn tick(&mut self) {
+impl<T> TapDanceEagerState<'_, T> {
+    fn tick_tde(&mut self) {
         self.timeout = self.timeout.saturating_sub(1);
     }
 
@@ -292,7 +473,7 @@ impl<'a, T> TapDanceEagerState<'a, T> {
 }
 
 #[derive(Debug)]
-enum WaitingConfig<'a, T: 'a + std::fmt::Debug> {
+pub(crate) enum WaitingConfig<'a, T: 'a + std::fmt::Debug> {
     HoldTap(HoldTapConfig<'a>),
     TapDance(TapDanceState<'a, T>),
     Chord(&'a ChordsGroup<'a, T>),
@@ -302,12 +483,15 @@ enum WaitingConfig<'a, T: 'a + std::fmt::Debug> {
 pub struct WaitingState<'a, T: 'a + std::fmt::Debug> {
     coord: KCoord,
     timeout: u16,
+    on_press_reset_timeout_to: Option<NonZeroU16>,
     delay: u16,
     ticks: u16,
     hold: &'a Action<'a, T>,
     tap: &'a Action<'a, T>,
     timeout_action: &'a Action<'a, T>,
     config: WaitingConfig<'a, T>,
+    layer_stack: LayerStack,
+    prev_queue_len: QueueLen,
 }
 
 /// Actions that can be triggered for a key configured for HoldTap.
@@ -324,7 +508,7 @@ pub enum WaitingAction {
 }
 
 impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
-    fn tick(
+    fn tick_wt(
         &mut self,
         queued: &mut Queue,
         action_queue: &mut ActionQueue<'a, T>,
@@ -337,6 +521,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
             WaitingConfig::TapDance(ref tds) => {
                 let (ret, num_taps) =
                     self.handle_tap_dance(tds.num_taps, tds.actions.len(), queued);
+                self.prev_queue_len = queued.len() as u8;
                 // Due to ownership issues, handle_tap_dance can't contain all of the necessary
                 // logic.
                 if ret.is_some() {
@@ -368,6 +553,19 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
     }
 
     fn handle_hold_tap(&mut self, cfg: HoldTapConfig, queued: &Queue) -> Option<WaitingAction> {
+        if queued.len() as u8 == self.prev_queue_len && self.timeout > 0 {
+            // Fast path: nothing has changed since last tick and we haven't timed out yet.
+            return None;
+        }
+        if let Some(timeout_reset_val) = self.on_press_reset_timeout_to {
+            if let Some(last) = queued.iter().next_back() {
+                if last.event.is_press() {
+                    self.timeout = timeout_reset_val.into();
+                }
+            }
+        }
+        self.prev_queue_len = queued.len() as u8;
+        let mut skip_timeout = false;
         match cfg {
             HoldTapConfig::Default => (),
             HoldTapConfig::HoldOnOtherKeyPress => {
@@ -375,6 +573,30 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                     return Some(WaitingAction::Hold);
                 }
             }
+            HoldTapConfig::Order { buffer, .. } => {
+                // Like PermissiveHold: if another key was pressed AND released
+                // (while modifier is still held), resolve as Hold.
+                // If modifier is released first, the fallthrough below handles Tap.
+                //
+                // Buffer: key presses that occurred within `buffer` ticks of the
+                // hold-tap key press are ignored by release-order logic, allowing
+                // fast typing to resolve as Tap regardless of release order.
+                let mut queued = queued.iter();
+                while let Some(q) = queued.next() {
+                    if q.event.is_press() {
+                        // Elapsed ticks since this key entered the queue, compared against buffer window.
+                        let press_tick = self.ticks.saturating_sub(q.since);
+                        if press_tick < buffer {
+                            continue;
+                        }
+                        let (i, j) = q.event.coord();
+                        let target = Event::Release(i, j);
+                        if queued.clone().any(|q| q.event == target) {
+                            return Some(WaitingAction::Hold);
+                        }
+                    }
+                }
+            }
             HoldTapConfig::PermissiveHold => {
                 let mut queued = queued.iter();
                 while let Some(q) = queued.next() {
@@ -388,21 +610,26 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 }
             }
             HoldTapConfig::Custom(func) => {
-                if let waiting_action @ Some(_) = (func)(QueuedIter(queued.iter())) {
+                let (waiting_action, local_skip) = (func)(QueuedIter(queued.iter()), self.coord);
+                if waiting_action.is_some() {
                     return waiting_action;
                 }
+                skip_timeout = local_skip;
             }
         }
-        if let Some(&Queued { since, .. }) = queued
+        if let Some(&Queued {
+            since: since_release,
+            ..
+        }) = queued
             .iter()
             .find(|s| self.is_corresponding_release(&s.event))
         {
-            if self.timeout >= self.delay.saturating_sub(since) {
+            if self.timeout >= self.delay.saturating_sub(since_release) {
                 Some(WaitingAction::Tap)
             } else {
                 Some(WaitingAction::Timeout)
             }
-        } else if self.timeout == 0 {
+        } else if self.timeout == 0 && (!skip_timeout) {
             Some(WaitingAction::Timeout)
         } else {
             None
@@ -415,6 +642,10 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
         max_taps: usize,
         queued: &mut Queue,
     ) -> (Option<WaitingAction>, u16) {
+        if queued.len() as u8 == self.prev_queue_len && self.timeout > 0 {
+            // Fast path: nothing has changed since last tick and we haven't timed out yet.
+            return (None, num_taps);
+        }
         // Evict events with the same coordinates except for the final release. E.g. if 3 taps have
         // occurred, this will remove all `Press` events and 2 `Release` events. This is done so
         // that the state machine processes the entire tap dance sequence as a single press and
@@ -434,7 +665,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 do_retain
             });
         };
-        if self.timeout == 0 || usize::from(num_taps) >= max_taps {
+        if self.timeout == 0 {
             evict_same_coord_events(num_taps, queued);
             return (Some(WaitingAction::Tap), num_taps);
         }
@@ -449,6 +680,10 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 Ok(same_tap_count)
             }
         }) {
+            Ok(num_taps) if usize::from(num_taps) >= max_taps => {
+                evict_same_coord_events(num_taps, queued);
+                (Some(WaitingAction::Tap), num_taps)
+            }
             Ok(num_taps) => (None, num_taps),
             Err((num_taps, _)) => {
                 evict_same_coord_events(num_taps, queued);
@@ -463,8 +698,16 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
         queued: &mut Queue,
         action_queue: &mut ActionQueue<'a, T>,
     ) -> Option<(WaitingAction, &'a Action<'a, T>, PressedQueue)> {
+        if queued.len() as u8 == self.prev_queue_len && self.timeout.saturating_sub(self.delay) > 0
+        {
+            // Fast path: nothing has changed since last tick and we haven't timed out yet.
+            return None;
+        }
+        self.prev_queue_len = queued.len() as u8;
+
         // need to keep track of how many Press events we handled so we can filter them out later
         let mut handled_press_events = 0;
+        let start_chord_coord = self.coord;
         let mut released_coord = None;
 
         // Compute the set of chord keys that are currently pressed
@@ -529,6 +772,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
         };
 
         let mut pq = PressedQueue::new();
+        let _ = pq.push_back(start_chord_coord);
 
         // Return all press events that were logically handled by this chording event
         queued.retain(|s| {
@@ -551,15 +795,15 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
     fn decompose_chord_into_action_queue(
         &mut self,
         config: &'a ChordsGroup<'a, T>,
-        queued: &mut Queue,
+        queued: &Queue,
         action_queue: &mut ActionQueue<'a, T>,
     ) {
-        let mut chord_key_order = [0u32; ChordKeys::BITS as usize];
+        let mut chord_key_order = [0u128; ChordKeys::BITS as usize];
 
         // Default to the initial coordinate. But if a key is released early (before the timeout
         // occurs), use that key for action releases. That way the chord is released as early as
         // possible.
-        let mut action_queue_coord = self.coord;
+        let mut default_associated_coord = self.coord;
 
         let starting_mask = config.get_keys(self.coord).unwrap_or(0);
         let mut mask_bits_set = 1;
@@ -569,7 +813,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 Ok(active)
             } else if let Some(chord_keys) = config.get_keys(s.event.coord()) {
                 match s.event {
-                    Event::Press(_, _) => {
+                    Event::Press(..) => {
                         if active | chord_keys != active {
                             chord_key_order[mask_bits_set] = chord_keys;
                             mask_bits_set += 1;
@@ -577,7 +821,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                         Ok(active | chord_keys)
                     }
                     Event::Release(i, j) => {
-                        action_queue_coord = (i, j);
+                        default_associated_coord = (i, j);
                         Err(active) // released a chord key, abort
                     }
                 }
@@ -590,6 +834,32 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
         let len = mask_bits_set;
         let chord_keys = &chord_key_order[0..len];
 
+        let get_coord_for_chord = |mask: ChordKeys| -> (u8, u16) {
+            if config.get_keys(default_associated_coord).unwrap_or(0) & mask > 0 {
+                // This might be a release.
+                // If it belongs to the associated action, prefer to use it.
+                return default_associated_coord;
+            }
+            if self.coord != default_associated_coord
+                && config.get_keys(self.coord).unwrap_or(0) & mask > 0
+            {
+                // The first coordinate not in queued
+                // so must be explicitly checked if it is not the default coord.
+                return self.coord;
+            }
+            queued
+                .iter()
+                .find_map(|q| {
+                    let coord = q.event.coord();
+                    let qmask = config.get_keys(coord).unwrap_or(0);
+                    match qmask & mask {
+                        0 => None,
+                        _ => Some(coord),
+                    }
+                })
+                .unwrap_or(default_associated_coord)
+        };
+
         // Compute actions using the following description:
         //
         // Let's say we have a chord group with keys (h j k l). The full set (h j k l) is not
@@ -620,6 +890,7 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
 
         let mut start = 0;
         let mut end = len;
+        let delay = self.delay + self.ticks;
         while start < len {
             let sub_chord = &chord_keys[start..end];
             let chord_mask = sub_chord
@@ -628,7 +899,13 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                 .reduce(|acc, e| acc | e)
                 .unwrap_or(0);
             if let Some(action) = config.get_chord(chord_mask) {
-                let _ = action_queue.push_back(Some((action_queue_coord, action)));
+                let coord = get_coord_for_chord(chord_mask);
+                // Note on LayerStack being default (empty):
+                // A chordv1 allows transparency, so this is broken right now,
+                // and could result in an infinite loop, because
+                // the queue activating code falls back to top-level resolution order
+                // if the stored layer stack is empty.
+                let _ = action_queue.push_back(Some((coord, delay, action, Default::default())));
             } else {
                 end -= 1;
                 // shrink from end until something is found, or have checked up to and including
@@ -641,7 +918,13 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                         .reduce(|acc, e| acc | e)
                         .unwrap_or(0);
                     if let Some(action) = config.get_chord(chord_mask) {
-                        let _ = action_queue.push_back(Some((action_queue_coord, action)));
+                        let coord = get_coord_for_chord(chord_mask);
+                        let _ = action_queue.push_back(Some((
+                            coord,
+                            delay,
+                            action,
+                            Default::default(),
+                        )));
                         break;
                     }
                     end -= 1;
@@ -661,6 +944,8 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
     }
 }
 
+type OneShotCoords = ArrayDeque<KCoord, ONE_SHOT_MAX_ACTIVE, arraydeque::behavior::Wrapping>;
+
 #[derive(Debug, Copy, Clone)]
 pub struct SequenceState<'a, T: 'a> {
     cur_event: Option<SequenceEvent<'a, T>>,
@@ -669,23 +954,80 @@ pub struct SequenceState<'a, T: 'a> {
     remaining_events: &'a [SequenceEvent<'a, T>],
 }
 
-type OneShotKeys = [KCoord; ONE_SHOT_MAX_ACTIVE];
 type ReleasedOneShotKeys = Vec<KCoord, ONE_SHOT_MAX_ACTIVE>;
 
+// Using a u16 for indices instead of usize.
+// Need to check against this value in code that creates layers.
+pub const MAX_LAYERS: usize = 60000;
+
+// Use heapless Vec for perf - avoid pointer indirections.
+// Use u16 for more efficient cache. 12*u16 = 3*u64 = 24 bytes.
+// Then there is a usize for the length, totaling 32 bytes.
+// Cache line is typically 64 bytes, so this takes half a cache line.
+// Above all assumes x86-64.
+pub const MAX_ACTIVE_LAYERS: usize = 12;
+
+/// Because we only need a read-only stack and efficient iteration over contained
+/// items, LayerStack items are in reverse order over usual back-to-front order
+/// of items in array-based stack implementations.
+type LayerStack = Vec<u16, MAX_ACTIVE_LAYERS>;
+
 /// Contains the state of one shot keys that are currently active.
 pub struct OneShotState {
     /// KCoordinates of one shot keys that are active
-    pub keys: ArrayDeque<OneShotKeys, arraydeque::behavior::Wrapping>,
+    pub keys: ArrayDeque<KCoord, ONE_SHOT_MAX_ACTIVE, arraydeque::behavior::Wrapping>,
     /// KCoordinates of one shot keys that have been released
-    pub released_keys: ArrayDeque<OneShotKeys, arraydeque::behavior::Wrapping>,
+    pub released_keys: ArrayDeque<KCoord, ONE_SHOT_MAX_ACTIVE, arraydeque::behavior::Wrapping>,
+    /// Fix #1874:
+    /// Represents the one-shot state that must not be released on physical key release.
+    /// Consider the case `(multi a (one-shot 100 b))`,
+    /// when only tracking coordinates (which this used to in the past),
+    /// the `a` would not release a even upon releasing the action key
+    /// because its state falls on the same coordinate as the oneshot b.
+    /// The fix is to explicitly know which key/layer states
+    /// — which are the only actions allowed within one-shot —
+    /// should be kept, and normally release others.
+    pub state_to_retain_on_release:
+        ArrayDeque<OneShotRetainableState, ONE_SHOT_MAX_ACTIVE, arraydeque::behavior::Wrapping>,
     /// Used to keep track of already-pressed keys for the release variants.
-    pub other_pressed_keys: ArrayDeque<OneShotKeys, arraydeque::behavior::Wrapping>,
+    pub other_pressed_keys: ArrayDeque<KCoord, ONE_SHOT_MAX_ACTIVE, arraydeque::behavior::Wrapping>,
     /// Timeout (ms) after which all one shot keys expire
     pub timeout: u16,
     /// Contains the end config of the most recently pressed one shot key
     pub end_config: OneShotEndConfig,
     /// Marks if release of the one shot keys should be done on the next tick
     pub release_on_next_tick: bool,
+    /// The number of ticks to delay the release of the one-shot activation
+    /// for EndOnFirstPress(OrRepress).
+    /// This used to not exist and effectively be 1 (1ms),
+    /// but that is too short for some environments.
+    /// When too short, applications or desktop environments process
+    /// the key release before the next press,
+    /// even if temporally the release was sent after.
+    pub pause_input_processing_delay: u16,
+    /// If pause_input_processing_delay is used, this will be >0,
+    /// meaning input processing should be paused to prevent extra presses
+    /// from coming in while OneShot has not yet been released.
+    ///
+    /// May also be reused for other purposes...
+    pub pause_input_processing_ticks: u16,
+
+    /// Number of ticks to ignore press events for.
+    pub ticks_to_ignore_events: u16,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub enum OneShotRetainableState {
+    KeyCode { coord: KCoord, kc: KeyCode },
+    Layer { coord: KCoord, layer: u16 },
+}
+
+impl OneShotRetainableState {
+    pub fn coord(&self) -> KCoord {
+        match self {
+            Self::KeyCode { coord, .. } | Self::Layer { coord, .. } => *coord,
+        }
+    }
 }
 
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
@@ -695,25 +1037,35 @@ enum OneShotHandlePressKey {
 }
 
 impl OneShotState {
-    fn tick(&mut self) -> Option<ReleasedOneShotKeys> {
+    fn tick_osh(&mut self) -> Option<ReleasedOneShotKeys> {
         if self.keys.is_empty() {
             return None;
         }
+        self.ticks_to_ignore_events = self.ticks_to_ignore_events.saturating_sub(1);
         self.timeout = self.timeout.saturating_sub(1);
         if self.release_on_next_tick || self.timeout == 0 {
             self.release_on_next_tick = false;
             self.timeout = 0;
+            self.pause_input_processing_ticks = 0;
+            self.ticks_to_ignore_events = 0;
             self.keys.clear();
             self.other_pressed_keys.clear();
+            self.state_to_retain_on_release.clear();
             Some(self.released_keys.drain(..).collect())
         } else {
             None
         }
     }
 
-    fn handle_press(&mut self, key: OneShotHandlePressKey) {
-        if self.keys.is_empty() {
-            return;
+    /// Returns the coordinates associated with an active oneshot.
+    /// The intended use of this is for `rpt-any` to be able to repeat
+    /// the output chord of a one-shot+normal key,
+    /// which are two separate actions that users
+    /// would likely want to combine under a repeat condition.
+    fn handle_press(&mut self, key: OneShotHandlePressKey) -> OneShotCoords {
+        let mut oneshot_coords = ArrayDeque::new();
+        if self.keys.is_empty() || self.ticks_to_ignore_events > 0 {
+            return oneshot_coords;
         }
         match key {
             OneShotHandlePressKey::OneShotKey(pressed_coord) => {
@@ -724,7 +1076,9 @@ impl OneShotState {
                 ) && self.keys.contains(&pressed_coord)
                 {
                     self.release_on_next_tick = true;
+                    oneshot_coords.extend(self.keys.iter().copied());
                 }
+
                 self.released_keys.retain(|coord| *coord != pressed_coord);
             }
             OneShotHandlePressKey::Other(pressed_coord) => {
@@ -732,12 +1086,15 @@ impl OneShotState {
                     self.end_config,
                     OneShotEndConfig::EndOnFirstPress | OneShotEndConfig::EndOnFirstPressOrRepress
                 ) {
-                    self.release_on_next_tick = true;
+                    self.timeout = core::cmp::min(self.pause_input_processing_delay, self.timeout);
+                    self.pause_input_processing_ticks = self.pause_input_processing_delay;
                 } else {
                     let _ = self.other_pressed_keys.push_back(pressed_coord);
                 }
+                oneshot_coords.extend(self.keys.iter().copied());
             }
-        }
+        };
+        oneshot_coords
     }
 
     /// Returns true if the caller should handle the release normally and false otherwise.
@@ -761,6 +1118,12 @@ impl OneShotState {
             (false, self.released_keys.push_back((i, j)))
         }
     }
+
+    fn add_state_to_retain(&mut self, state: OneShotRetainableState) {
+        if !self.state_to_retain_on_release.contains(&state) {
+            self.state_to_retain_on_release.push_back(state);
+        }
+    }
 }
 
 /// An iterator over the currently queued events.
@@ -782,8 +1145,8 @@ impl<'a> Iterator for QueuedIter<'a> {
 /// An event, waiting in a queue to be processed.
 #[derive(Debug, Copy, Clone)]
 pub struct Queued {
-    event: Event,
-    since: u16,
+    pub(crate) event: Event,
+    pub(crate) since: u16,
 }
 impl From<Event> for Queued {
     fn from(event: Event) -> Self {
@@ -791,7 +1154,21 @@ impl From<Event> for Queued {
     }
 }
 impl Queued {
-    fn tick(&mut self) {
+    pub(crate) fn new_press(i: u8, j: u16) -> Self {
+        Self {
+            since: 0,
+            event: Event::Press(i, j),
+        }
+    }
+
+    pub(crate) fn new_release(i: u8, j: u16) -> Self {
+        Self {
+            since: 0,
+            event: Event::Release(i, j),
+        }
+    }
+
+    pub(crate) fn tick_qd(&mut self) {
         self.since = self.since.saturating_add(1);
     }
 
@@ -808,21 +1185,28 @@ pub struct LastPressTracker {
 }
 
 impl LastPressTracker {
-    fn tick(&mut self) {
+    fn tick_lpt(&mut self) {
         self.tap_hold_timeout = self.tap_hold_timeout.saturating_sub(1);
     }
+    fn update_coord(&mut self, coord: KCoord) {
+        if coord.0 == REAL_KEY_ROW {
+            // Only update if it's a real key press.
+            self.coord = coord;
+        }
+    }
 }
 
-impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt::Debug>
-    Layout<'a, C, R, L, T>
-{
+impl<'a, const C: usize, const R: usize, T: 'a + Copy + std::fmt::Debug> Layout<'a, C, R, T> {
     /// Creates a new `Layout` object.
-    pub fn new(layers: &'a [[[Action<T>; C]; R]; L]) -> Self {
+    fn new(layers: &'a [[[Action<T>; C]; R]]) -> Self {
+        assert!(layers.len() < MAX_LAYERS);
         Self {
+            src_keys: &[Action::NoOp; C],
             layers,
             default_layer: 0,
             states: Vec::new(),
             waiting: None,
+            extra_waiting: ArrayDeque::new(),
             tap_dance_eager: None,
             queue: ArrayDeque::new(),
             oneshot: OneShotState {
@@ -830,82 +1214,243 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                 end_config: OneShotEndConfig::EndOnFirstPress,
                 keys: ArrayDeque::new(),
                 released_keys: ArrayDeque::new(),
+                state_to_retain_on_release: ArrayDeque::new(),
                 other_pressed_keys: ArrayDeque::new(),
                 release_on_next_tick: false,
+                pause_input_processing_delay: 0,
+                pause_input_processing_ticks: 0,
+                ticks_to_ignore_events: 0,
             },
+            keys_to_suppress_for_one_cycle: Vec::new(),
             last_press_tracker: Default::default(),
             active_sequences: ArrayDeque::new(),
             action_queue: ArrayDeque::new(),
-            prev_action: None,
+            custom_event_release_queue: ArrayDeque::new(),
+            rpt_action: None,
+            historical_keys: History::new(),
+            historical_inputs: History::new(),
+            historical_inputs_sans_holds_or_timeouts: History::new(),
+            rpt_multikey_key_buffer: unsafe { MultiKeyBuffer::new() },
+            quick_tap_hold_timeout: false,
+            tap_hold_require_prior_idle: 0,
+            trans_resolution_behavior_v2: true,
+            delegate_to_first_layer: false,
+            chords_v2: None,
+            device_history: ArrayDeque::new(),
+            contextual_execution: ContextualExecution::new(),
+            tap_hold_tracker: Default::default(),
         }
     }
+    pub fn new_with_trans_action_settings(
+        src_keys: &'a [Action<T>; C],
+        layers: &'a [[[Action<T>; C]; R]],
+        trans_resolution_behavior_v2: bool,
+        delegate_to_first_layer: bool,
+    ) -> Self {
+        let mut new = Self::new(layers);
+        new.src_keys = src_keys;
+        new.trans_resolution_behavior_v2 = trans_resolution_behavior_v2;
+        new.delegate_to_first_layer = delegate_to_first_layer;
+        new
+    }
+
     /// Iterates on the key codes of the current state.
-    pub fn keycodes(&self) -> impl Iterator<Item = KeyCode> + '_ {
-        self.states.iter().filter_map(State::keycode)
+    pub fn keycodes(&self) -> impl Iterator<Item = KeyCode> + Clone + '_ {
+        let keys_to_suppress_for_one_cycle = self.keys_to_suppress_for_one_cycle.clone();
+        self.states
+            .iter()
+            .filter_map(State::keycode)
+            .filter(move |kc| !keys_to_suppress_for_one_cycle.contains(kc))
+    }
+
+    fn exclude_hold_or_timeout_from_history(coord: KCoord, history: &mut History<KCoord>) {
+        if let Some((i, _)) = history
+            .events
+            .iter()
+            .copied()
+            .enumerate()
+            .find(|(_i, ev)| *ev == coord)
+        {
+            history.ticks_since_occurrences.remove(i);
+            history.events.remove(i);
+        }
     }
-    fn waiting_into_hold(&mut self) -> CustomEvent<'a, T> {
-        if let Some(w) = &self.waiting {
+
+    fn waiting_into_hold(&mut self, idx: i8) -> CustomEvent<'a, T> {
+        let waiting = if idx < 0 {
+            self.waiting.as_ref()
+        } else {
+            self.extra_waiting.get(idx as usize)
+        };
+        if let Some(w) = waiting {
             let hold = w.hold;
             let coord = w.coord;
+
+            Self::exclude_hold_or_timeout_from_history(
+                coord,
+                &mut self.historical_inputs_sans_holds_or_timeouts,
+            );
+
             let delay = match w.config {
                 WaitingConfig::HoldTap(..) | WaitingConfig::Chord(_) => w.delay + w.ticks,
                 WaitingConfig::TapDance(_) => 0,
             };
-            self.waiting = None;
+            let layer_stack = w.layer_stack.clone();
+            self.tap_hold_tracker.set_hold_activated(coord, &w.config);
+            if idx < 0 {
+                self.waiting = None;
+            } else {
+                self.extra_waiting.remove(idx as usize);
+            }
             if coord == self.last_press_tracker.coord {
                 self.last_press_tracker.tap_hold_timeout = 0;
             }
-            self.do_action(hold, coord, delay, false)
+            // Similar issue happens for the quick tap-hold tap as with on-press release;
+            // the rapidity of the release can cause issues. See pause_input_processing_delay
+            // comments for more detail.
+            self.oneshot.pause_input_processing_ticks = self.oneshot.pause_input_processing_delay;
+            let mut custom_activation_count = 0;
+            self.do_action(
+                hold,
+                coord,
+                delay,
+                false,
+                &mut layer_stack.into_iter(),
+                &mut custom_activation_count,
+            )
         } else {
             CustomEvent::NoEvent
         }
     }
-    fn waiting_into_tap(&mut self, pq: Option<PressedQueue>) -> CustomEvent<'a, T> {
-        if let Some(w) = &self.waiting {
+    fn waiting_into_tap(&mut self, pq: Option<PressedQueue>, idx: i8) -> CustomEvent<'a, T> {
+        let waiting = if idx < 0 {
+            self.waiting.as_ref()
+        } else {
+            self.extra_waiting.get(idx as usize)
+        };
+        if let Some(w) = waiting {
             let tap = w.tap;
             let coord = w.coord;
             let delay = match w.config {
                 WaitingConfig::HoldTap(..) | WaitingConfig::Chord(_) => w.delay + w.ticks,
                 WaitingConfig::TapDance(_) => 0,
             };
-            self.waiting = None;
-            let ret = self.do_action(tap, coord, delay, false);
+            let layer_stack = w.layer_stack.clone();
+            self.tap_hold_tracker.set_tap_activated(coord, &w.config);
+            if idx < 0 {
+                self.waiting = None;
+            } else {
+                self.extra_waiting.remove(idx as usize);
+            }
+            let mut custom_activation_count = 0;
+            let ret = self.do_action(
+                tap,
+                coord,
+                delay,
+                false,
+                &mut layer_stack.clone().into_iter(),
+                &mut custom_activation_count,
+            );
+
             if let Some(pq) = pq {
-                if matches!(
-                    tap,
+                let mut custom_activation_count = 0;
+                self.contextual_execution.pause_historical_keys_updates = true;
+                match tap {
                     Action::KeyCode(_)
-                        | Action::MultipleKeyCodes(_)
-                        | Action::OneShot(_)
-                        | Action::Layer(_)
-                ) {
-                    // The current intent of this block is to ensure that simple actions like
-                    // key presses or layer-while-held remain pressed as long as a single key from
-                    // the input chord remains held. The behaviour of these actions is correct in
-                    // the case of repeating do_action, so there is currently no harm in doing
-                    // this. Other action types are more problematic though.
-                    for other_coord in pq.iter().copied() {
-                        self.do_action(tap, other_coord, delay, false);
+                    | Action::MultipleKeyCodes(_)
+                    | Action::OneShot(_)
+                    | Action::Layer(_) => {
+                        // The current intent of this block is to ensure that simple actions like
+                        // key presses or layer-while-held remain pressed as long as a single key from
+                        // the input chord remains held. The behaviour of these actions is correct in
+                        // the case of repeating do_action, so there is currently no harm in doing
+                        // this. Other action types are more problematic though.
+                        for other_coord in pq.iter().copied() {
+                            self.do_action(
+                                tap,
+                                other_coord,
+                                delay,
+                                false,
+                                &mut layer_stack.clone().into_iter(),
+                                &mut custom_activation_count,
+                            );
+                        }
+                    }
+                    Action::MultipleActions(acs) => {
+                        // Like above block, but for the same simple actions within MultipleActions
+                        for ac in acs.iter() {
+                            if matches!(
+                                ac,
+                                Action::KeyCode(_)
+                                    | Action::MultipleKeyCodes(_)
+                                    | Action::OneShot(_)
+                                    | Action::Layer(_)
+                            ) {
+                                for other_coord in pq.iter().copied() {
+                                    self.do_action(
+                                        ac,
+                                        other_coord,
+                                        delay,
+                                        false,
+                                        &mut layer_stack.clone().into_iter(),
+                                        &mut custom_activation_count,
+                                    );
+                                }
+                            }
+                        }
                     }
+                    _ => {}
                 }
+                self.contextual_execution.pause_historical_keys_updates = false;
             }
+
+            // Similar issue happens for the quick tap-hold tap as with on-press release;
+            // the rapidity of the release can cause issues. See pause_input_processing_delay
+            // comments for more detail.
+            self.oneshot.pause_input_processing_ticks = self.oneshot.pause_input_processing_delay;
             ret
         } else {
             CustomEvent::NoEvent
         }
     }
-    fn waiting_into_timeout(&mut self) -> CustomEvent<'a, T> {
-        if let Some(w) = &self.waiting {
+    fn waiting_into_timeout(&mut self, idx: i8) -> CustomEvent<'a, T> {
+        let waiting = if idx < 0 {
+            self.waiting.as_ref()
+        } else {
+            self.extra_waiting.get(idx as usize)
+        };
+        if let Some(w) = waiting {
             let timeout_action = w.timeout_action;
             let coord = w.coord;
+
+            Self::exclude_hold_or_timeout_from_history(
+                coord,
+                &mut self.historical_inputs_sans_holds_or_timeouts,
+            );
+
             let delay = match w.config {
                 WaitingConfig::HoldTap(..) | WaitingConfig::Chord(_) => w.delay + w.ticks,
                 WaitingConfig::TapDance(_) => 0,
             };
-            self.waiting = None;
+            let layer_stack = w.layer_stack.clone();
+            self.tap_hold_tracker.set_hold_activated(coord, &w.config);
+            if idx < 0 {
+                self.waiting = None;
+            } else {
+                self.extra_waiting.remove(idx as usize);
+            }
             if coord == self.last_press_tracker.coord {
                 self.last_press_tracker.tap_hold_timeout = 0;
             }
-            self.do_action(timeout_action, coord, delay, false)
+            let mut custom_activation_count = 0;
+            self.do_action(
+                timeout_action,
+                coord,
+                delay,
+                false,
+                &mut layer_stack.into_iter(),
+                &mut custom_activation_count,
+            )
         } else {
             CustomEvent::NoEvent
         }
@@ -921,24 +1466,55 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
     /// Returns the corresponding `CustomEvent`, allowing to manage
     /// custom actions thanks to the `Action::Custom` variant.
     pub fn tick(&mut self) -> CustomEvent<'a, T> {
-        if let Some(Some((coord, action))) = self.action_queue.pop_front() {
+        self.tick_layout()
+    }
+
+    fn tick_layout(&mut self) -> CustomEvent<'a, T> {
+        // Eagerly process released queued custom actions
+        // then return; other items will be processed later!
+        if let Some(released_custom_event) = self.custom_event_release_queue.pop_front() {
+            return CustomEvent::Release(released_custom_event);
+        }
+
+        let active_layer = self.current_layer() as u16;
+        if let Some(chv2) = self.chords_v2.as_mut() {
+            self.queue.extend(chv2.tick_chv2(active_layer).drain(0..));
+            if let chord_action @ Some(_) = chv2.get_action_chv2() {
+                self.action_queue.push_back(chord_action);
+                self.oneshot.pause_input_processing_ticks =
+                    self.oneshot.pause_input_processing_delay;
+            }
+        }
+        self.keys_to_suppress_for_one_cycle.clear();
+        if let Some(Some((coord, delay, action, layer_stack))) = self.action_queue.pop_front() {
             // If there's anything in the action queue, don't process anything else yet - execute
             // everything. Otherwise an action may never be released.
-            return self.do_action(action, coord, 0, false);
+            let mut custom_activation_count = 0;
+            return self.do_action(
+                action,
+                coord,
+                delay,
+                false,
+                &mut layer_stack.into_iter(),
+                &mut custom_activation_count,
+            );
         }
-        self.states = self.states.iter().filter_map(State::tick).collect();
-        self.queue.iter_mut().for_each(Queued::tick);
-        self.last_press_tracker.tick();
+        self.queue.iter_mut().for_each(Queued::tick_qd);
+        self.last_press_tracker.tick_lpt();
         if let Some(ref mut tde) = self.tap_dance_eager {
-            tde.tick();
+            tde.tick_tde();
             if tde.is_expired() {
                 self.tap_dance_eager = None;
             }
         }
         self.process_sequences();
 
+        self.historical_keys.tick_hist();
+        self.historical_inputs.tick_hist();
+        self.historical_inputs_sans_holds_or_timeouts.tick_hist();
+
         let mut custom = CustomEvent::NoEvent;
-        if let Some(released_keys) = self.oneshot.tick() {
+        if let Some(released_keys) = self.oneshot.tick_osh() {
             for key in released_keys.iter() {
                 custom.update(self.dequeue(Queued {
                     event: Event::Release(key.0, key.1),
@@ -948,18 +1524,37 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
         }
 
         custom.update(match &mut self.waiting {
-            Some(w) => match w.tick(&mut self.queue, &mut self.action_queue) {
-                Some((WaitingAction::Hold, _)) => self.waiting_into_hold(),
-                Some((WaitingAction::Tap, pq)) => self.waiting_into_tap(pq),
-                Some((WaitingAction::Timeout, _)) => self.waiting_into_timeout(),
+            Some(w) => match w.tick_wt(&mut self.queue, &mut self.action_queue) {
+                Some((WaitingAction::Hold, _)) => self.waiting_into_hold(-1),
+                Some((WaitingAction::Tap, pq)) => self.waiting_into_tap(pq, -1),
+                Some((WaitingAction::Timeout, _)) => self.waiting_into_timeout(-1),
                 Some((WaitingAction::NoOp, _)) => self.drop_waiting(),
                 None => CustomEvent::NoEvent,
             },
-            None => match self.queue.pop_front() {
-                Some(s) => self.dequeue(s),
-                None => CustomEvent::NoEvent,
-            },
+            None => {
+                if self.extra_waiting.is_empty() {
+                    // Due to the possible delay in the key release for EndOnFirstPress
+                    // because some apps/DEs do not handle it properly if done too quickly,
+                    // undesirable behaviour of extra presses making it in before
+                    // the release happens might occur.
+                    //
+                    // A mitigation against that is to pause input processing.
+                    if self.oneshot.pause_input_processing_ticks > 0 {
+                        self.oneshot.pause_input_processing_ticks =
+                            self.oneshot.pause_input_processing_ticks.saturating_sub(1);
+                        CustomEvent::NoEvent
+                    } else {
+                        match self.queue.pop_front() {
+                            Some(s) => self.dequeue(s),
+                            None => CustomEvent::NoEvent,
+                        }
+                    }
+                } else {
+                    CustomEvent::NoEvent
+                }
+            }
         });
+        let custom = self.process_extra_waitings(custom);
         self.process_sequence_custom(custom)
     }
     /// Takes care of draining and populating the `active_sequences` ArrayDeque,
@@ -978,26 +1573,20 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     seq.tapped = None;
                 } else {
                     // Pull the next SequenceEvent
-                    match seq.remaining_events {
-                        [e, tail @ ..] => {
-                            seq.cur_event = Some(*e);
-                            seq.remaining_events = tail;
-                        }
-                        [] => (),
+                    if let [e, tail @ ..] = seq.remaining_events {
+                        seq.cur_event = Some(*e);
+                        seq.remaining_events = tail;
                     }
                     // Process it (SequenceEvent)
                     match seq.cur_event {
                         Some(SequenceEvent::Complete) => {
-                            for fake_key in self.states.clone().iter() {
-                                if let FakeKey { keycode } = *fake_key {
-                                    self.states.retain(|s| s.seq_release(keycode).is_some());
-                                }
-                            }
                             seq.remaining_events = &[];
                         }
                         Some(SequenceEvent::Press(keycode)) => {
                             // Start tracking this fake key Press() event
                             let _ = self.states.push(FakeKey { keycode });
+                            self.contextual_execution
+                                .push_historical_key(&mut self.historical_keys, keycode);
                             // Fine to fake (0, 0). This is sequences anyway. In Kanata, nothing
                             // valid should be at (0, 0) that this would interfere with.
                             self.oneshot
@@ -1006,6 +1595,8 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                         Some(SequenceEvent::Tap(keycode)) => {
                             // Same as Press() except we track it for one tick via seq.tapped:
                             let _ = self.states.push(FakeKey { keycode });
+                            self.contextual_execution
+                                .push_historical_key(&mut self.historical_keys, keycode);
                             self.oneshot
                                 .handle_press(OneShotHandlePressKey::Other((0, 0)));
                             seq.tapped = Some(keycode);
@@ -1015,12 +1606,10 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                             self.oneshot.handle_release((0, 0));
                             self.states.retain(|s| s.seq_release(keycode).is_some());
                         }
-                        Some(SequenceEvent::Delay { duration }) => {
+                        Some(SequenceEvent::Delay { duration }) if duration > 0 => {
                             // Setup a delay that will be decremented once per tick until 0
-                            if duration > 0 {
-                                // -1 to start since this tick counts
-                                seq.delay = duration - 1;
-                            }
+                            // -1 to start since this tick counts
+                            seq.delay = duration - 1;
                         }
                         Some(SequenceEvent::Custom(custom)) => {
                             let _ = self.states.push(State::SeqCustomPending(custom));
@@ -1051,6 +1640,38 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
             }
         }
     }
+
+    fn process_extra_waitings(&mut self, current_custom: CustomEvent<'a, T>) -> CustomEvent<'a, T> {
+        if !matches!(current_custom, CustomEvent::NoEvent) {
+            return current_custom;
+        }
+        let mut waiting_action = (0, None);
+        for (i, w) in self.extra_waiting.iter_mut().enumerate() {
+            match w.tick_wt(&mut self.queue, &mut self.action_queue) {
+                None => {}
+                wa => {
+                    waiting_action = (i as isize, wa);
+                    // break - only complete one at a time even if potentially multiple have
+                    // completed, so that only one custom event is returned.
+                    //
+                    // Theoretically if we could call the waiting_into_* functions, we could do that
+                    // here and break only if custom is None, but that runs into mutability
+                    // problems. I don't expect any perceptible degradation between from not doing
+                    // the above.
+                    break;
+                }
+            }
+        }
+        let i = waiting_action.0;
+        match waiting_action.1 {
+            Some((WaitingAction::Hold, _)) => self.waiting_into_hold(i as i8),
+            Some((WaitingAction::Tap, pq)) => self.waiting_into_tap(pq, i as i8),
+            Some((WaitingAction::Timeout, _)) => self.waiting_into_timeout(i as i8),
+            Some((WaitingAction::NoOp, _)) => self.drop_waiting(),
+            None => current_custom,
+        }
+    }
+
     fn process_sequence_custom(
         &mut self,
         mut current_custom: CustomEvent<'a, T>,
@@ -1058,6 +1679,11 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
         if self.states.is_empty() || !matches!(current_custom, CustomEvent::NoEvent) {
             return current_custom;
         }
+        // It is important to note that this code cannot simply be replaced by `retain_mut`.
+        // The `retain_mut` function is not chosen
+        // because it is important to break on the first `SeqCustom` that is discovered.
+        // Such functionality could be replaced by a marker to ignore processing,
+        // but for now that is not necessary.
         self.states.retain(|s| !matches!(s, State::Tombstone));
         for state in self.states.iter_mut() {
             match state {
@@ -1083,72 +1709,164 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                 let mut custom = CustomEvent::NoEvent;
                 let (do_release, overflow_key) = self.oneshot.handle_release((i, j));
                 if do_release {
-                    self.states
-                        .retain(|s| s.release((i, j), &mut custom).is_some());
+                    self.states.retain(|s| {
+                        !s.clear_on_next_release()
+                            && s.release((i, j), &mut custom, &mut self.custom_event_release_queue)
+                                .is_some()
+                    });
+                } else {
+                    // Fix #1874:
+                    // Might still need to apply release,
+                    // but need to check against states on same coordinate
+                    // that aren't part of a OneShot.
+                    self.states.retain(|s| {
+                        match s {
+                            NormalKey { coord, keycode, .. } => {
+                                // NormalKey is a valid oneshot state,
+                                // may need to keep.
+                                *coord != (i, j)
+                                    || self.oneshot.state_to_retain_on_release.contains(
+                                        &OneShotRetainableState::KeyCode {
+                                            coord: *coord,
+                                            kc: *keycode,
+                                        },
+                                    )
+                            }
+                            LayerModifier { coord, value } => {
+                                // LayerModifier is a valid oneshot state,
+                                // may need to keep.
+                                *coord != (i, j)
+                                    || self.oneshot.state_to_retain_on_release.contains(
+                                        &OneShotRetainableState::Layer {
+                                            coord: *coord,
+                                            layer: *value as u16,
+                                        },
+                                    )
+                            }
+                            // Everything else is not a valid oneshot state,
+                            // if it falls on the same coordinate
+                            // as a oneshot key, it should still be released here.
+                            _ => {
+                                !s.clear_on_next_release()
+                                    && s.release(
+                                        (i, j),
+                                        &mut custom,
+                                        &mut self.custom_event_release_queue,
+                                    )
+                                    .is_some()
+                            }
+                        }
+                    });
                 }
                 if let Some((i2, j2)) = overflow_key {
-                    self.states
-                        .retain(|s| s.release((i2, j2), &mut custom).is_some());
+                    self.states.retain(|s| {
+                        s.release((i2, j2), &mut custom, &mut self.custom_event_release_queue)
+                            .is_some()
+                    });
                 }
                 custom
             }
 
             Press(i, j) => {
-                if let Some(tde) = self.tap_dance_eager {
+                let mut layer_stack = self.trans_resolution_layer_order().into_iter();
+                let mut custom_activation_count = 0;
+                if let Some(tde) = &mut self.tap_dance_eager {
                     if (i, j) == self.last_press_tracker.coord && !tde.is_expired() {
+                        let tde_action = tde.actions[usize::from(tde.num_taps)];
+                        tde.incr_taps();
                         let custom = self.do_action(
-                            tde.actions[usize::from(tde.num_taps)],
+                            tde_action,
                             (i, j),
                             queue.since,
                             false,
+                            &mut layer_stack.skip(1),
+                            &mut custom_activation_count,
                         );
-                        // unwrap is here because tde cannot be ref mut
-                        self.tap_dance_eager.as_mut().expect("some").incr_taps();
                         custom
-
-                    // i == 0 means real key, i == 1 means fake key. Let fake keys do whatever, but
-                    // interrupt tap-dance-eager if real key.
-                    } else if i == 0 {
-                        // unwrap is here because tde cannot be ref mut
-                        self.tap_dance_eager.as_mut().expect("some").set_expired();
-                        let action = self.press_as_action((i, j), self.current_layer());
-                        self.do_action(action, (i, j), queue.since, false)
                     } else {
-                        let action = self.press_as_action((i, j), self.current_layer());
-                        self.do_action(action, (i, j), queue.since, false)
+                        // i == 0 means real key, i == 1 means fake key. Let fake keys do whatever, but
+                        // interrupt tap-dance-eager if real key.
+                        if i == REAL_KEY_ROW {
+                            tde.set_expired();
+                        }
+                        self.do_action(
+                            &Action::Trans,
+                            (i, j),
+                            queue.since,
+                            false,
+                            &mut layer_stack,
+                            &mut custom_activation_count,
+                        )
                     }
                 } else {
-                    let action = self.press_as_action((i, j), self.current_layer());
-                    self.do_action(action, (i, j), queue.since, false)
+                    self.do_action(
+                        &Action::Trans,
+                        (i, j),
+                        queue.since,
+                        false,
+                        &mut layer_stack,
+                        &mut custom_activation_count,
+                    )
                 }
             }
         }
     }
     /// Register a key event.
     pub fn event(&mut self, event: Event) {
-        if let Some(queued) = self.queue.push_back(event.into()) {
-            self.waiting_into_hold();
-            self.dequeue(queued);
+        if let Event::Press(x, y) = event {
+            self.historical_inputs.push_front((x, y));
+            self.historical_inputs_sans_holds_or_timeouts
+                .push_front((x, y));
+        }
+        if let Some(overflow) = if let Some(ch) = self.chords_v2.as_mut() {
+            ch.push_back_chv2(event.into())
+        } else {
+            self.queue.push_back(event.into())
+        } {
+            for i in -1..(EXTRA_WAITING_LEN as i8) {
+                self.waiting_into_hold(i);
+            }
+            self.dequeue(overflow);
+        }
+    }
+
+    /// Put a key event at the front instead of back.
+    /// These events will not participate in chordsv2.
+    pub fn event_to_front(&mut self, event: Event) {
+        if let Event::Press(x, y) = event {
+            self.historical_inputs.push_front((x, y));
+            self.historical_inputs_sans_holds_or_timeouts
+                .push_front((x, y));
+        }
+        if let Some(overflow) = self.queue.push_front(event.into()) {
+            for i in -1..(EXTRA_WAITING_LEN as i8) {
+                self.waiting_into_hold(i);
+            }
+            self.dequeue(overflow);
         }
     }
-    fn press_as_action(&self, coord: KCoord, layer: usize) -> &'a Action<'a, T> {
+
+    /// Resolve coordinate to first non-Trans actions.
+    /// Trans on base layer, resolves to key from defsrc.
+    fn resolve_coord(
+        &self,
+        coord: KCoord,
+        layer_stack: &mut (impl Iterator<Item = u16> + Clone),
+    ) -> &'a Action<'a, T> {
         use crate::action::Action::*;
-        let action = self
-            .layers
-            .get(layer)
-            .and_then(|l| l.get(coord.0 as usize))
-            .and_then(|l| l.get(coord.1 as usize));
-        match action {
-            None => &NoOp,
-            Some(Trans) => {
-                if layer != self.default_layer {
-                    self.press_as_action(coord, self.default_layer)
-                } else {
-                    &NoOp
-                }
+        let x = coord.0 as usize;
+        let y = coord.1 as usize;
+        assert!(x <= self.layers[0].len());
+        assert!(y <= self.layers[0][0].len());
+        for layer in layer_stack {
+            assert!(usize::from(layer) <= self.layers.len());
+            let action = &self.layers[usize::from(layer)][x][y];
+            match action {
+                Trans => continue,
+                action => return action,
             }
-            Some(action) => action,
         }
+        if x == 0 { &self.src_keys[y] } else { &NoOp }
     }
     fn do_action(
         &mut self,
@@ -1156,25 +1874,107 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
         coord: KCoord,
         delay: u16,
         is_oneshot: bool,
+        layer_stack: &mut (impl Iterator<Item = u16> + Clone), // used to resolve Trans action
+        custom_activation_count: &mut u8,
     ) -> CustomEvent<'a, T> {
-        assert!(self.waiting.is_none() || matches!(action, Action::Custom(..)));
-        if self.last_press_tracker.coord != coord {
+        let mut action = action;
+        if let Trans = action {
+            action = self.resolve_coord(coord, layer_stack);
+        }
+        let action = action;
+
+        if self.last_press_tracker.coord != coord && coord.0 == REAL_KEY_ROW {
             self.last_press_tracker.tap_hold_timeout = 0;
         }
         use Action::*;
-        if !matches!(action, Repeat | Layer(..) | DefaultLayer(..)) {
-            self.prev_action = Some(action);
-        }
+        self.states.retain(|s| match s {
+            // Need to solve a problem here - if the output chord `S-=` is active, and then a
+            // different keypress `=` happens, the `lsft =` states are cleared; but the `=`
+            // is immediately re-added again. This means the release is never observed..
+            //
+            // Bug introduced:
+            //
+            // If doing something like typing parentheses using output chords,
+            // e.g. S-9 followed by S-0,
+            // the trivial fix will suppress the shift key for a bit
+            // but the `0` still gets output,
+            // resulting in an unshifted `0` which is incorrect.
+            //
+            // Fix added:
+            //
+            // Do not apply the suppression to modifiers.
+            // Modifiers typically don't have a usage pattern similar to
+            // the real use case of `S-=` followed by `=` example,
+            // such as `S-=` followed by only `lsft`,
+            // with a desire for the lone `lsft` to actually activate something.
+            NormalKey { flags, keycode, .. } => match flags.nkf_clear_on_next_action() {
+                true => {
+                    self.oneshot.pause_input_processing_ticks += 2;
+                    if !keycode.is_mod() {
+                        let _ = self.keys_to_suppress_for_one_cycle.push(*keycode);
+                    }
+                    false
+                }
+                false => true,
+            },
+            _ => true,
+        });
         match action {
-            NoOp | Trans => {
-                if !is_oneshot {
+            NoOp => {
+                // There is an interaction between oneshot and chordsv2 here.
+                // chordsv2 sends fake queued press/release events at the coordinate level in order
+                // to trigger other "waiting" style actions, namely tap-hold. However, these can
+                // potentially interfere with oneshot by triggering early oneshot activation. This
+                // is resolved by ignoring actions at the coordinate at which the fake events are
+                // sent.
+                if !is_oneshot && coord != TRIGGER_TAPHOLD_COORD {
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                self.rpt_action = Some(action);
+                let _ = self.states.push(NoOpInput { coord });
+            }
+            Src => {
+                let action = &self.src_keys[usize::from(coord.1)];
+                // Risk: infinite recursive resulting in stack overflow.
+                // In practice this is not expected to happen.
+                // The `src_keys` actions are all expected to be `KeyCode` or `NoOp` actions.
+                self.do_action(
+                    action,
+                    coord,
+                    delay,
+                    is_oneshot,
+                    &mut std::iter::empty(),
+                    custom_activation_count,
+                );
+            }
+            Trans => {
+                // Transparent action should be resolved to non-transparent one near the top
+                // of `do_action`.
+                unreachable!("Trans action should have been resolved earlier")
             }
             Repeat => {
-                if let Some(ac) = self.prev_action {
-                    self.do_action(ac, coord, delay, is_oneshot);
+                // Notes around repeat:
+                //
+                // Though this action seems conceptually simple, in reality there are a lot of
+                // decisions to be made around how exactly actions repeat. For example: in a
+                // tap-dance action, would one expect the tap-dance to be repeated or the inner
+                // action that was most activated within the tap-dance?
+                //
+                // Currently the answer to these questions is: what is easy/possible to do?
+                // It is not consistent whether it is the outer or inner action.
+                // The actions tap-dance and tap-hold will repeat the inner action and
+                // not the outer (tap-dance|hold),
+                // but multi will repeat the entire outer multi action.
+                if let Some(ac) = self.rpt_action {
+                    self.do_action(
+                        ac,
+                        coord,
+                        delay,
+                        is_oneshot,
+                        &mut std::iter::empty(),
+                        custom_activation_count,
+                    );
                 }
             }
             HoldTap(HoldTapAction {
@@ -1184,35 +1984,102 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                 timeout_action,
                 config,
                 tap_hold_interval,
+                on_press_reset_timeout_to,
+                require_prior_idle,
             }) => {
+                // Typing streak detection: if a different physical key was pressed
+                // recently, resolve as tap immediately without entering WaitingState.
+                // Per-action override takes precedence over the global defcfg value.
+                let idle_threshold = require_prior_idle.unwrap_or(self.tap_hold_require_prior_idle);
+                if idle_threshold > 0 {
+                    let prior_idle_tap = self
+                        .historical_inputs_sans_holds_or_timeouts
+                        .iter_hevents()
+                        .find(|prior| {
+                            prior.event.0 == REAL_KEY_ROW
+                              // Disregard this same press event
+                              && prior.event != coord
+                              // Disregard any presses that are actually still in the queue and
+                              // unresolved.
+                              && !self.queue.iter().any(|q| {
+                                  q.since == prior.ticks_since_occurrence
+                                  && match q.event {
+                                      Event::Press(0, j) => j == prior.event.1,
+                                      _ => false
+                                  }
+                              })
+                        })
+                        .is_some_and(|prior| prior.ticks_since_occurrence <= idle_threshold);
+                    if prior_idle_tap {
+                        let custom = self.do_action(
+                            tap,
+                            coord,
+                            delay,
+                            is_oneshot,
+                            layer_stack,
+                            custom_activation_count,
+                        );
+                        self.last_press_tracker.update_coord(coord);
+                        return custom;
+                    }
+                }
                 let mut custom = CustomEvent::NoEvent;
                 if *tap_hold_interval == 0
                     || coord != self.last_press_tracker.coord
                     || self.last_press_tracker.tap_hold_timeout == 0
                 {
+                    let ticks = match self.quick_tap_hold_timeout {
+                        // Leave 1 tick to timeout as it will be consumed in the next processing cycle
+                        true => delay.min(timeout.saturating_sub(1)),
+                        false => 0,
+                    };
                     let waiting: WaitingState<T> = WaitingState {
                         coord,
-                        timeout: *timeout,
-                        delay,
-                        ticks: 0,
+                        timeout: timeout.saturating_sub(ticks),
+                        delay: delay.saturating_sub(ticks),
+                        ticks,
+                        on_press_reset_timeout_to: *on_press_reset_timeout_to,
                         hold,
                         tap,
                         timeout_action,
                         config: WaitingConfig::HoldTap(*config),
+                        layer_stack: layer_stack.collect(),
+                        prev_queue_len: QueueLen::MAX,
                     };
-                    self.waiting = Some(waiting);
+                    if self.waiting.is_some() {
+                        self.extra_waiting.push_back(waiting);
+                    } else {
+                        self.waiting = Some(waiting);
+                    }
                     self.last_press_tracker.tap_hold_timeout = *tap_hold_interval;
                 } else {
                     self.last_press_tracker.tap_hold_timeout = 0;
-                    custom.update(self.do_action(tap, coord, delay, is_oneshot));
+                    custom.update(self.do_action(
+                        tap,
+                        coord,
+                        delay,
+                        is_oneshot,
+                        layer_stack,
+                        custom_activation_count,
+                    ));
                 }
                 // Need to set tap_hold_tracker coord AFTER the checks.
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 return custom;
             }
             &OneShot(oneshot) => {
-                self.last_press_tracker.coord = coord;
-                let custom = self.do_action(oneshot.action, coord, delay, true);
+                self.last_press_tracker.update_coord(coord);
+                let custom = self.do_action(
+                    oneshot.action,
+                    coord,
+                    delay,
+                    true,
+                    &mut std::iter::empty(),
+                    custom_activation_count,
+                );
+                // Note - set rpt_action after doing the inner oneshot action. This means that the
+                // whole oneshot will be repeated by rpt-any rather than only the inner action.
+                self.rpt_action = Some(action);
                 self.oneshot
                     .handle_press(OneShotHandlePressKey::OneShotKey(coord));
                 self.oneshot.timeout = oneshot.timeout;
@@ -1222,8 +2089,13 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                 }
                 return custom;
             }
+            &OneShotIgnoreEventsTicks(ticks) => {
+                self.last_press_tracker.update_coord(coord);
+                self.rpt_action = Some(action);
+                self.oneshot.ticks_to_ignore_events = ticks;
+            }
             &TapDance(td) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 match td.config {
                     TapDanceConfig::Lazy => {
                         self.waiting = Some(WaitingState {
@@ -1234,11 +2106,14 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                             hold: &Action::NoOp,
                             tap: &Action::NoOp,
                             timeout_action: &Action::NoOp,
+                            on_press_reset_timeout_to: None,
                             config: WaitingConfig::TapDance(TapDanceState {
                                 actions: td.actions,
                                 timeout: td.timeout,
                                 num_taps: 1,
                             }),
+                            layer_stack: layer_stack.collect(),
+                            prev_queue_len: QueueLen::MAX,
                         });
                     }
                     TapDanceConfig::Eager => {
@@ -1264,12 +2139,19 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                                 }
                             }
                         };
-                        self.do_action(td.actions[0], coord, delay, false);
+                        return self.do_action(
+                            td.actions[0],
+                            coord,
+                            delay,
+                            false,
+                            layer_stack,
+                            custom_activation_count,
+                        );
                     }
                 }
             }
             &Chords(chords) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 self.waiting = Some(WaitingState {
                     coord,
                     timeout: chords.timeout,
@@ -1278,42 +2160,137 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     hold: &Action::NoOp,
                     tap: &Action::NoOp,
                     timeout_action: &Action::NoOp,
+                    on_press_reset_timeout_to: None,
                     config: WaitingConfig::Chord(chords),
+                    layer_stack: layer_stack.collect(),
+                    prev_queue_len: QueueLen::MAX,
                 });
             }
             &KeyCode(keycode) => {
-                self.last_press_tracker.coord = coord;
-                let _ = self.states.push(NormalKey { coord, keycode });
+                self.last_press_tracker.update_coord(coord);
+                // Most-recent-first!
+                self.contextual_execution
+                    .push_historical_key(&mut self.historical_keys, keycode);
+                let _ = self.states.push(NormalKey {
+                    coord,
+                    keycode,
+                    flags: NormalKeyFlags(0),
+                });
+                let mut oneshot_coords = ArrayDeque::new();
                 if !is_oneshot {
-                    self.oneshot
+                    oneshot_coords = self
+                        .oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
+                } else {
+                    self.oneshot
+                        .add_state_to_retain(OneShotRetainableState::KeyCode {
+                            coord,
+                            kc: keycode,
+                        });
+                }
+                if oneshot_coords.is_empty() {
+                    self.rpt_action = Some(action);
+                } else {
+                    self.rpt_action = None;
+                    unsafe {
+                        self.rpt_multikey_key_buffer.clear();
+                        for kc in self
+                            .states
+                            .iter()
+                            .filter_map(|kc| State::keycode_in_coords(kc, &oneshot_coords))
+                        {
+                            self.rpt_multikey_key_buffer.push(kc);
+                        }
+                        self.rpt_multikey_key_buffer.push(keycode);
+                        self.rpt_action = Some(self.rpt_multikey_key_buffer.get_ref());
+                    }
                 }
             }
             &MultipleKeyCodes(v) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 for &keycode in *v {
-                    let _ = self.states.push(NormalKey { coord, keycode });
+                    // BUG:
+                    // In the original implementation, activating an action sequence such as b ->
+                    // S-b will not type a separate instance of "B" because b is already held and
+                    // wont be re-sent by the outer processing loop.
+                    //
+                    // FIX:
+                    // If `keycode` is not a mod, suppress it for a cycle if it exists in the
+                    // status. This is not expected to have any negative perceptible effects.
+                    if !keycode.is_mod() && self.keycodes().any(|kc| kc == keycode) {
+                        let _ = self.keys_to_suppress_for_one_cycle.push(keycode);
+                    }
+                    self.contextual_execution
+                        .push_historical_key(&mut self.historical_keys, keycode);
+                    let _ = self.states.push(NormalKey {
+                        coord,
+                        keycode,
+                        // In Kanata, this action is only ever used with output chords. Output
+                        // chords within a one-shot are ignored because someone might do something
+                        // like (one-shot C-S-lalt to get 3 modifiers. These are probably intended
+                        // to remain held. However, other output chords are usually used to type
+                        // symbols or accented characters, e.g. S-1 or RA-a. Clearing chord keys on
+                        // the next action allows a subsequent typed key to not have modifiers
+                        // alongside it. But if the symbol or accented character is held down, key
+                        // repeat works just fine.
+                        flags: NormalKeyFlags(if is_oneshot {
+                            0
+                        } else {
+                            NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION
+                        }),
+                    });
                 }
+
+                let mut oneshot_coords = ArrayDeque::new();
                 if !is_oneshot {
-                    self.oneshot
+                    oneshot_coords = self
+                        .oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
+                } else {
+                    for &keycode in *v {
+                        self.oneshot
+                            .add_state_to_retain(OneShotRetainableState::KeyCode {
+                                coord,
+                                kc: keycode,
+                            });
+                    }
+                }
+                if oneshot_coords.is_empty() {
+                    self.rpt_action = Some(action);
+                } else {
+                    self.rpt_action = None;
+                    unsafe {
+                        self.rpt_multikey_key_buffer.clear();
+                        for kc in self
+                            .states
+                            .iter()
+                            .filter_map(|s| s.keycode_in_coords(&oneshot_coords))
+                        {
+                            self.rpt_multikey_key_buffer.push(kc);
+                        }
+                        for &keycode in *v {
+                            self.rpt_multikey_key_buffer.push(keycode);
+                        }
+                        self.rpt_action = Some(self.rpt_multikey_key_buffer.get_ref());
+                    }
                 }
             }
             &MultipleActions(v) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 let mut custom = CustomEvent::NoEvent;
                 for action in *v {
-                    custom.update(self.do_action(action, coord, delay, is_oneshot));
-                }
-                // Multi is probably the one action where it is desirable to repeat the top-level
-                // action instead of the final action. The final action meaning a hold action in
-                // `tap-hold` or the 3rd tap of a `tap-dance`.
-                //
-                // Set the prev_action again since it was probably overwritten by the
-                // `do_action` recursion.
-                if !matches!(action, Action::Repeat) {
-                    self.prev_action = Some(action);
+                    custom.update(self.do_action(
+                        action,
+                        coord,
+                        delay,
+                        is_oneshot,
+                        &mut layer_stack.clone(),
+                        custom_activation_count,
+                    ));
                 }
+                // Save the whole multi action instead of the final action in multi so that Repeat
+                // repeats all of the actions in this multi.
+                self.rpt_action = Some(action);
                 return custom;
             }
             Sequence { events } => {
@@ -1327,6 +2304,7 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                self.rpt_action = Some(action);
             }
             RepeatableSequence { events } => {
                 self.active_sequences.push_back(SequenceState {
@@ -1343,6 +2321,7 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                self.rpt_action = Some(action);
             }
             CancelSequences => {
                 // Clear any and all running sequences then clean up any leftover FakeKey events
@@ -1356,17 +2335,27 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                self.rpt_action = Some(action);
             }
             &Layer(value) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 let _ = self.states.push(LayerModifier { value, coord });
                 if !is_oneshot {
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
+                } else {
+                    self.oneshot
+                        .add_state_to_retain(OneShotRetainableState::Layer {
+                            coord,
+                            layer: value as u16,
+                        });
                 }
+                // Notably missing in Layer and below in DefaultLayer is setting rpt_action. This
+                // is so that if the Repeat key is on a different layer than the base, it can still
+                // be used to repeat the previous non-layer-changing action.
             }
             DefaultLayer(value) => {
-                self.last_press_tracker.coord = coord;
+                self.last_press_tracker.update_coord(coord);
                 self.set_default_layer(*value);
                 if !is_oneshot {
                     self.oneshot
@@ -1374,14 +2363,28 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                 }
             }
             Custom(value) => {
-                self.last_press_tracker.coord = coord;
-                if self.states.push(State::Custom { value, coord }).is_ok() {
-                    return CustomEvent::Press(value);
-                }
+                self.last_press_tracker.update_coord(coord);
                 if !is_oneshot {
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                *custom_activation_count = custom_activation_count.saturating_add(1);
+                self.rpt_action = Some(action);
+                return match custom_activation_count {
+                    0 | 1 => {
+                        let _ = self.states.push(State::Custom { value, coord });
+                        CustomEvent::Press(value)
+                    }
+                    _ => {
+                        self.action_queue.push_back(Some((
+                            coord,
+                            delay,
+                            action,
+                            layer_stack.clone().collect(),
+                        )));
+                        CustomEvent::NoEvent
+                    }
+                };
             }
             ReleaseState(rs) => {
                 self.states.retain(|s| s.release_state(*rs).is_some());
@@ -1389,17 +2392,75 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
                     self.oneshot
                         .handle_press(OneShotHandlePressKey::Other(coord));
                 }
+                self.rpt_action = Some(action);
             }
             Fork(fcfg) => {
-                return match self.states.iter().any(|s| match s {
+                let ret = match self.states.iter().any(|s| match s {
                     NormalKey { keycode, .. } | FakeKey { keycode } => {
                         fcfg.right_triggers.contains(keycode)
                     }
                     _ => false,
                 }) {
-                    false => self.do_action(&fcfg.left, coord, delay, false),
-                    true => self.do_action(&fcfg.right, coord, delay, false),
+                    false => self.do_action(
+                        &fcfg.left,
+                        coord,
+                        delay,
+                        false,
+                        &mut layer_stack.clone(),
+                        custom_activation_count,
+                    ),
+                    true => self.do_action(
+                        &fcfg.right,
+                        coord,
+                        delay,
+                        false,
+                        &mut layer_stack.clone(),
+                        custom_activation_count,
+                    ),
                 };
+                // Repeat the fork rather than the terminal action.
+                self.rpt_action = Some(action);
+                return ret;
+            }
+            Switch(sw) => {
+                let active_keys = self.states.iter().filter_map(State::keycode);
+                let active_coords = self.states.iter().filter_map(State::coord);
+                let historical_keys = self.historical_keys.iter_hevents();
+                let historical_coords = self.historical_inputs.iter_hevents();
+                let layers = self.trans_resolution_layer_order().into_iter();
+                let mut action_queue: ActionQueue<T> = Default::default();
+                if let Some(f) = sw.init_fn {
+                    f();
+                }
+                for ac in sw.actions(
+                    active_keys,
+                    active_coords,
+                    historical_keys,
+                    historical_coords,
+                    layers,
+                    // Note on truncating cast: I expect default layer to be in range by other
+                    // assertions.
+                    self.default_layer as u16,
+                    self.device_history.iter().copied(),
+                ) {
+                    action_queue.push_back(Some((coord, delay, ac, layer_stack.clone().collect())));
+                }
+
+                let mut custom = CustomEvent::NoEvent;
+                while let Some(Some((coord, delay, action, layer_stack))) = action_queue.pop_front()
+                {
+                    custom.update(self.do_action(
+                        action,
+                        coord,
+                        delay,
+                        is_oneshot,
+                        &mut layer_stack.into_iter(),
+                        custom_activation_count,
+                    ));
+                }
+
+                self.rpt_action = Some(action);
+                return custom;
             }
         }
         CustomEvent::NoEvent
@@ -1414,6 +2475,33 @@ impl<'a, const C: usize, const R: usize, const L: usize, T: 'a + Copy + std::fmt
             .unwrap_or(self.default_layer)
     }
 
+    pub fn active_held_layers(&self) -> impl Iterator<Item = u16> + Clone + '_ {
+        self.states
+            .iter()
+            .filter_map(|s| State::get_layer(s).map(|l| l as u16))
+            .rev()
+    }
+
+    /// Returns a list indices of layers that should be used for [`Action::Trans`] resolution.
+    pub fn trans_resolution_layer_order(&self) -> LayerStack {
+        let current_layer = self.current_layer();
+        if self.trans_resolution_behavior_v2 {
+            let mut v = self.active_held_layers().collect::<LayerStack>();
+            let _ = v.push(self.default_layer as u16);
+            if self.delegate_to_first_layer && current_layer != 0 && self.default_layer != 0 {
+                let _ = v.push(0);
+            }
+            v
+        } else {
+            let mut v = Vec::new();
+            let _ = v.push(current_layer as u16);
+            if self.delegate_to_first_layer && current_layer != 0 {
+                let _ = v.push(0);
+            }
+            v
+        }
+    }
+
     /// Sets the default layer for the layout
     pub fn set_default_layer(&mut self, value: usize) {
         if value < self.layers.len() {
@@ -1442,9 +2530,11 @@ mod test {
 
     #[test]
     fn basic_hold_tap() {
-        static LAYERS: Layers<2, 1, 2> = [
+        static LAYERS: Layers<2, 1> = &[
             [[
                 HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
                     timeout: 200,
                     hold: l(1),
                     tap: k(Space),
@@ -1453,6 +2543,8 @@ mod test {
                     tap_hold_interval: 0,
                 }),
                 HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
                     timeout: 200,
                     hold: k(LCtrl),
                     timeout_action: k(LShift),
@@ -1463,7 +2555,7 @@ mod test {
             ]],
             [[Trans, MultipleKeyCodes(&[LCtrl, Enter].as_slice())]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
         layout.event(Press(0, 1));
@@ -1493,10 +2585,12 @@ mod test {
     }
 
     #[test]
-    fn basic_hold_tap_timeout() {
-        static LAYERS: Layers<2, 1, 2> = [
+    fn basic_hold_tap_repress_timeout() {
+        static LAYERS: Layers<2, 1> = &[
             [[
                 HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
                     timeout: 200,
                     hold: l(1),
                     tap: k(Space),
@@ -1505,6 +2599,8 @@ mod test {
                     tap_hold_interval: 0,
                 }),
                 HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
                     timeout: 200,
                     hold: k(LCtrl),
                     timeout_action: k(LCtrl),
@@ -1515,7 +2611,7 @@ mod test {
             ]],
             [[Trans, MultipleKeyCodes(&[LCtrl, Enter].as_slice())]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
         layout.event(Press(0, 1));
@@ -1546,8 +2642,10 @@ mod test {
 
     #[test]
     fn hold_tap_interleaved_timeout() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1556,6 +2654,8 @@ mod test {
                 tap_hold_interval: 0,
             }),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 20,
                 hold: k(LCtrl),
                 timeout_action: k(LCtrl),
@@ -1564,7 +2664,7 @@ mod test {
                 tap_hold_interval: 0,
             }),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
         layout.event(Press(0, 0));
@@ -1595,8 +2695,10 @@ mod test {
 
     #[test]
     fn hold_on_press() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1606,7 +2708,7 @@ mod test {
             }),
             k(Enter),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Press another key before timeout
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -1651,10 +2753,213 @@ mod test {
         assert_keys(&[], layout.keycodes());
     }
 
+    #[test]
+    fn order_clean_tap() {
+        // Press and release modifier with no other keys → Tap.
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 0 },
+                tap_hold_interval: 0,
+                require_prior_idle: None,
+            }),
+            k(Enter),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        for _ in 0..50 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn order_hold() {
+        // Modifier down → other down → other up first → Hold.
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 0 },
+                tap_hold_interval: 0,
+                require_prior_idle: None,
+            }),
+            k(Enter),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // Other key releases first → Hold
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Enter], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        // Release modifier
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn order_tap() {
+        // Modifier down → other down → modifier up first → Tap.
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 0 },
+                tap_hold_interval: 0,
+                require_prior_idle: None,
+            }),
+            k(Enter),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // Modifier releases first → Tap
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space, Enter], layout.keycodes());
+    }
+
+    #[test]
+    fn order_multi_key_hold() {
+        // TH down → A down → B down → A up (while B still held) → TH up.
+        // A's press+release cycle completes while TH is held → Hold.
+        static LAYERS: Layers<3, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 0 },
+                tap_hold_interval: 0,
+                require_prior_idle: None,
+            }),
+            k(Enter),
+            k(Tab),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        // TH down
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // A down
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // B down
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // A up — A's press+release cycle is complete → Hold resolves
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        // Queued keys replay: Enter press, Tab press, Enter release
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Enter], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Enter, Tab], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, Tab], layout.keycodes());
+        // Release B
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        // Release TH
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn order_buffer_ignores_press_within_window() {
+        // TH down (buffer=50) → other key pressed+released within 50 ticks.
+        // Without buffer this would be Hold (other key's press+release cycle
+        // completes while TH held). With buffer=50, the press is ignored by
+        // release-order logic, so TH remains unresolved. Releasing TH → Tap.
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+                timeout: u16::MAX,
+                hold: k(LAlt),
+                timeout_action: k(Space),
+                tap: k(Space),
+                config: HoldTapConfig::Order { buffer: 50 },
+                tap_hold_interval: 0,
+            }),
+            k(Enter),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+
+        // TH down
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // Other key pressed at tick ~1 (well within 50-tick buffer)
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // Other key released — would normally trigger Hold, but press is buffered
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // TH released → Tap (buffered press was ignored).
+        // Space activates, then queued Enter press+release replays.
+        layout.event(Release(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space, Enter], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
     #[test]
     fn permissive_hold() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1664,7 +2969,7 @@ mod test {
             }),
             k(Enter),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Press and release another key before timeout
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -1691,13 +2996,79 @@ mod test {
         assert_keys(&[], layout.keycodes());
     }
 
+    #[test]
+    fn simultaneous_hold() {
+        static LAYERS: Layers<3, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+                timeout: 200,
+                hold: k(LAlt),
+                timeout_action: k(LAlt),
+                tap: k(Space),
+                config: HoldTapConfig::Default,
+                tap_hold_interval: 0,
+            }),
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+                timeout: 200,
+                hold: k(RAlt),
+                timeout_action: k(RAlt),
+                tap: k(A),
+                config: HoldTapConfig::Default,
+                tap_hold_interval: 0,
+            }),
+            HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+                timeout: 200,
+                hold: k(LCtrl),
+                timeout_action: k(LCtrl),
+                tap: k(A),
+                config: HoldTapConfig::Default,
+                tap_hold_interval: 0,
+            }),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+        layout.quick_tap_hold_timeout = true;
+
+        // Press and release another key before timeout
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+
+        for _ in 0..196 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, RAlt], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, RAlt], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LAlt, RAlt, LCtrl], layout.keycodes());
+    }
+
     #[test]
     fn multiple_actions() {
-        static LAYERS: Layers<2, 1, 2> = [
+        static LAYERS: Layers<2, 1> = &[
             [[MultipleActions(&[l(1), k(LShift)].as_slice()), k(F)]],
             [[Trans, k(E)]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
         layout.event(Press(0, 0));
@@ -1716,8 +3087,8 @@ mod test {
 
     #[test]
     fn custom() {
-        static LAYERS: Layers<1, 1, 1, u8> = [[[Action::Custom(42)]]];
-        let mut layout = Layout::new(&LAYERS);
+        static LAYERS: Layers<1, 1, i32> = &[[[Action::Custom(42)]]];
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
 
@@ -1738,13 +3109,13 @@ mod test {
 
     #[test]
     fn multiple_layers() {
-        static LAYERS: Layers<2, 1, 4> = [
+        static LAYERS: Layers<2, 1> = &[
             [[l(1), l(2)]],
             [[k(A), l(3)]],
             [[l(0), k(B)]],
             [[k(C), k(D)]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_eq!(0, layout.current_layer());
         assert_keys(&[], layout.keycodes());
@@ -1801,20 +3172,22 @@ mod test {
 
     #[test]
     fn custom_handler() {
-        fn always_tap(_: QueuedIter) -> Option<WaitingAction> {
-            Some(WaitingAction::Tap)
+        fn always_tap(_: QueuedIter, _: KCoord) -> (Option<WaitingAction>, bool) {
+            (Some(WaitingAction::Tap), false)
         }
-        fn always_hold(_: QueuedIter) -> Option<WaitingAction> {
-            Some(WaitingAction::Hold)
+        fn always_hold(_: QueuedIter, _: KCoord) -> (Option<WaitingAction>, bool) {
+            (Some(WaitingAction::Hold), false)
         }
-        fn always_nop(_: QueuedIter) -> Option<WaitingAction> {
-            Some(WaitingAction::NoOp)
+        fn always_nop(_: QueuedIter, _: KCoord) -> (Option<WaitingAction>, bool) {
+            (Some(WaitingAction::NoOp), false)
         }
-        fn always_none(_: QueuedIter) -> Option<WaitingAction> {
-            None
+        fn always_none(_: QueuedIter, _: KCoord) -> (Option<WaitingAction>, bool) {
+            (None, false)
         }
-        static LAYERS: Layers<4, 1, 1> = [[[
+        static LAYERS: Layers<4, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(Kb1),
                 timeout_action: k(Kb1),
@@ -1823,6 +3196,8 @@ mod test {
                 tap_hold_interval: 0,
             }),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(Kb3),
                 timeout_action: k(Kb3),
@@ -1831,6 +3206,8 @@ mod test {
                 tap_hold_interval: 0,
             }),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(Kb5),
                 timeout_action: k(Kb5),
@@ -1839,6 +3216,8 @@ mod test {
                 tap_hold_interval: 0,
             }),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(Kb7),
                 timeout_action: k(Kb7),
@@ -1847,7 +3226,7 @@ mod test {
                 tap_hold_interval: 0,
             }),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
 
@@ -1910,8 +3289,10 @@ mod test {
 
     #[test]
     fn tap_hold_interval() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1921,7 +3302,7 @@ mod test {
             }),
             k(Enter),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // press and release the HT key, expect tap action
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -1965,8 +3346,10 @@ mod test {
 
     #[test]
     fn tap_hold_interval_interleave() {
-        static LAYERS: Layers<3, 1, 1> = [[[
+        static LAYERS: Layers<3, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1976,6 +3359,8 @@ mod test {
             }),
             k(Enter),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -1984,7 +3369,7 @@ mod test {
                 tap_hold_interval: 200,
             }),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // press and release the HT key, expect tap action
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -2088,7 +3473,9 @@ mod test {
 
     #[test]
     fn tap_hold_interval_short_hold() {
-        static LAYERS: Layers<1, 1, 1> = [[[HoldTap(&HoldTapAction {
+        static LAYERS: Layers<1, 1> = &[[[HoldTap(&HoldTapAction {
+            on_press_reset_timeout_to: None,
+            require_prior_idle: None,
             timeout: 50,
             hold: k(LAlt),
             timeout_action: k(LAlt),
@@ -2096,7 +3483,7 @@ mod test {
             config: HoldTapConfig::Default,
             tap_hold_interval: 200,
         })]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // press and hold the HT key, expect hold action
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -2130,8 +3517,10 @@ mod test {
 
     #[test]
     fn tap_hold_interval_different_hold() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 50,
                 hold: k(LAlt),
                 timeout_action: k(LAlt),
@@ -2140,6 +3529,8 @@ mod test {
                 tap_hold_interval: 200,
             }),
             HoldTap(&HoldTapAction {
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
                 timeout: 200,
                 hold: k(RAlt),
                 timeout_action: k(RAlt),
@@ -2148,7 +3539,7 @@ mod test {
                 tap_hold_interval: 200,
             }),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // press HT1, press HT2, release HT1 after hold timeout, release HT2, press HT2
         layout.event(Press(0, 0));
@@ -2180,7 +3571,7 @@ mod test {
 
     #[test]
     fn one_shot() {
-        static LAYERS: Layers<3, 1, 1> = [[[
+        static LAYERS: Layers<3, 1> = &[[[
             OneShot(&crate::action::OneShot {
                 timeout: 100,
                 action: &k(LShift),
@@ -2189,7 +3580,8 @@ mod test {
             k(A),
             k(B),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
+        layout.oneshot.pause_input_processing_delay = 1;
 
         // Test:
         // 1. press one-shot
@@ -2291,7 +3683,7 @@ mod test {
 
     #[test]
     fn one_shot_end_press_or_repress() {
-        static LAYERS: Layers<3, 1, 1> = [[[
+        static LAYERS: Layers<3, 1> = &[[[
             OneShot(&crate::action::OneShot {
                 timeout: 100,
                 action: &k(LShift),
@@ -2300,7 +3692,8 @@ mod test {
             k(A),
             k(B),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
+        layout.oneshot.pause_input_processing_delay = 1;
 
         // Test:
         // 1. press one-shot
@@ -2444,7 +3837,7 @@ mod test {
 
     #[test]
     fn one_shot_end_on_release() {
-        static LAYERS: Layers<3, 1, 1> = [[[
+        static LAYERS: Layers<3, 1> = &[[[
             OneShot(&crate::action::OneShot {
                 timeout: 100,
                 action: &k(LShift),
@@ -2453,7 +3846,7 @@ mod test {
             k(A),
             k(B),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Test:
         // 1. press one-shot
@@ -2589,7 +3982,7 @@ mod test {
 
     #[test]
     fn one_shot_multi() {
-        static LAYERS: Layers<4, 1, 2> = [
+        static LAYERS: Layers<4, 1> = &[
             [[
                 OneShot(&crate::action::OneShot {
                     timeout: 100,
@@ -2610,7 +4003,8 @@ mod test {
             ]],
             [[k(A), k(B), k(C), k(D)]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
+        layout.oneshot.pause_input_processing_delay = 1;
 
         layout.event(Press(0, 0));
         layout.event(Release(0, 0));
@@ -2646,7 +4040,7 @@ mod test {
 
     #[test]
     fn one_shot_tap_hold() {
-        static LAYERS: Layers<3, 1, 2> = [
+        static LAYERS: Layers<3, 1> = &[
             [[
                 OneShot(&crate::action::OneShot {
                     timeout: 200,
@@ -2654,6 +4048,8 @@ mod test {
                     end_config: OneShotEndConfig::EndOnFirstPress,
                 }),
                 HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
                     timeout: 100,
                     hold: k(LAlt),
                     timeout_action: k(LAlt),
@@ -2665,7 +4061,8 @@ mod test {
             ]],
             [[k(A), k(B), k(C)]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
+        layout.oneshot.pause_input_processing_delay = 1;
 
         layout.event(Press(0, 0));
         layout.event(Release(0, 0));
@@ -2705,8 +4102,8 @@ mod test {
     }
 
     #[test]
-    fn tap_dance() {
-        static LAYERS: Layers<2, 2, 1> = [[
+    fn tap_dance_uneager() {
+        static LAYERS: Layers<2, 2> = &[[
             [
                 TapDance(&crate::action::TapDance {
                     timeout: 100,
@@ -2718,6 +4115,8 @@ mod test {
                             end_config: OneShotEndConfig::EndOnFirstPress,
                         }),
                         &HoldTap(&HoldTapAction {
+                            on_press_reset_timeout_to: None,
+                            require_prior_idle: None,
                             timeout: 100,
                             hold: k(LAlt),
                             timeout_action: k(LAlt),
@@ -2732,7 +4131,7 @@ mod test {
             ],
             [k(B), k(C)],
         ]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Test: tap-dance first key, timeout
         layout.event(Press(0, 0));
@@ -2809,8 +4208,6 @@ mod test {
         assert_keys(&[], layout.keycodes());
         layout.event(Release(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[], layout.keycodes());
-        assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[Space], layout.keycodes());
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
@@ -2833,7 +4230,7 @@ mod test {
             assert_keys(&[], layout.keycodes());
         }
         layout.event(Press(0, 0));
-        for _ in 0..101 {
+        for _ in 0..100 {
             assert_eq!(CustomEvent::NoEvent, layout.tick());
             assert_keys(&[], layout.keycodes());
         }
@@ -2848,7 +4245,7 @@ mod test {
 
     #[test]
     fn tap_dance_eager() {
-        static LAYERS: Layers<2, 2, 1> = [[
+        static LAYERS: Layers<2, 2> = &[[
             [
                 TapDance(&crate::action::TapDance {
                     timeout: 100,
@@ -2859,7 +4256,7 @@ mod test {
             ],
             [k(B), k(C)],
         ]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Test: tap-dance-eager first key
         layout.event(Press(0, 0));
@@ -2935,7 +4332,7 @@ mod test {
 
     #[test]
     fn release_state() {
-        static LAYERS: Layers<2, 1, 2> = [
+        static LAYERS: Layers<2, 1> = &[
             [[
                 MultipleActions(&(&[KeyCode(LCtrl), Layer(1)] as _)),
                 MultipleActions(&(&[KeyCode(LAlt), Layer(1)] as _)),
@@ -2948,7 +4345,7 @@ mod test {
             ]],
         ];
 
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         layout.event(Press(0, 1));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -2994,7 +4391,7 @@ mod test {
             ],
             timeout: 100,
         };
-        static LAYERS: Layers<6, 1, 1> = [[[
+        static LAYERS: Layers<6, 1> = &[[[
             NoOp,
             NoOp,
             Chords(&GROUP),
@@ -3003,7 +4400,7 @@ mod test {
             Chords(&GROUP),
         ]]];
 
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         layout.event(Press(0, 2));
         // timeout on non-terminal chord
         for _ in 0..50 {
@@ -3047,10 +4444,14 @@ mod test {
         assert_keys(&[Kb5, Kb3], layout.keycodes());
         layout.event(Release(0, 2));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[], layout.keycodes());
+        assert_keys(&[Kb3], layout.keycodes());
         layout.event(Release(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Kb3], layout.keycodes());
         layout.event(Release(0, 4));
-
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+
         // release terminal chord with no action associated
         // combo like (h j k) -> (h j) (k)
         layout.event(Press(0, 2));
@@ -3074,9 +4475,11 @@ mod test {
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[Kb5, Kb3], layout.keycodes());
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[], layout.keycodes());
-        layout.event(Release(0, 3));
+        assert_keys(&[Kb5], layout.keycodes());
         layout.event(Release(0, 2));
+        layout.event(Release(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
 
@@ -3100,7 +4503,7 @@ mod test {
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[Kb3, Kb6], layout.keycodes());
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[], layout.keycodes());
+        assert_keys(&[Kb3], layout.keycodes());
     }
 
     #[test]
@@ -3117,7 +4520,7 @@ mod test {
             ],
             timeout: 100,
         };
-        static LAYERS: Layers<6, 1, 1> = [[[
+        static LAYERS: Layers<6, 1> = &[[[
             NoOp,
             k(A),
             Chords(&GROUP),
@@ -3126,7 +4529,7 @@ mod test {
             Chords(&GROUP),
         ]]];
 
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
         layout.event(Press(0, 2));
         // timeout on non-terminal chord
         for _ in 0..50 {
@@ -3146,9 +4549,69 @@ mod test {
         assert_keys(&[], layout.keycodes());
     }
 
+    #[test]
+    fn test_chord_multi_waiting_decomposition() {
+        const GROUP: ChordsGroup<core::convert::Infallible> = ChordsGroup {
+            coords: &[((0, 0), 1), ((0, 1), 2)],
+            chords: &[
+                (
+                    1,
+                    &HoldTap(&HoldTapAction {
+                        on_press_reset_timeout_to: None,
+                        require_prior_idle: None,
+                        timeout: 100,
+                        hold: k(A),
+                        timeout_action: k(A),
+                        tap: k(Kb1),
+                        config: HoldTapConfig::Default,
+                        tap_hold_interval: 0,
+                    }),
+                ),
+                (
+                    2,
+                    &HoldTap(&HoldTapAction {
+                        on_press_reset_timeout_to: None,
+                        require_prior_idle: None,
+                        timeout: 100,
+                        hold: k(B),
+                        timeout_action: k(B),
+                        tap: k(Kb2),
+                        config: HoldTapConfig::Default,
+                        tap_hold_interval: 0,
+                    }),
+                ),
+            ],
+            timeout: 100,
+        };
+        static LAYERS: Layers<2, 1> = &[[[Chords(&GROUP), Chords(&GROUP)]]];
+
+        let mut layout = Layout::new(LAYERS);
+        layout.quick_tap_hold_timeout = true;
+        layout.event(Press(0, 0));
+        layout.event(Press(0, 1));
+        // Why does this take 103 ticks?
+        // 0: chord begin
+        // 1: chord decompose
+        // 2: action queue dequeue
+        // 3: action queue dequeue
+        // 4-103: timeout ticks
+        for _ in 0..102 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[A, B], layout.keycodes());
+        layout.event(Release(0, 0));
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
     #[test]
     fn test_fork() {
-        static LAYERS: Layers<2, 1, 1> = [[[
+        static LAYERS: Layers<2, 1> = &[[[
             Fork(&ForkConfig {
                 left: k(Kb1),
                 right: k(Kb2),
@@ -3156,7 +4619,7 @@ mod test {
             }),
             k(Space),
         ]]];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         layout.event(Press(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
@@ -3181,7 +4644,7 @@ mod test {
 
     #[test]
     fn test_repeat() {
-        static LAYERS: Layers<5, 1, 2> = [
+        static LAYERS: Layers<5, 1> = &[
             [[
                 k(A),
                 MultipleKeyCodes(&[LShift, B].as_slice()),
@@ -3197,7 +4660,7 @@ mod test {
                 Layer(1),
             ]],
         ];
-        let mut layout = Layout::new(&LAYERS);
+        let mut layout = Layout::new(LAYERS);
 
         // Press a key
         layout.event(Press(0, 0));
@@ -3283,4 +4746,684 @@ mod test {
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
     }
+
+    #[test]
+    fn test_clear_multiple_keycodes() {
+        static LAYERS: Layers<2, 1> = &[[[k(A), MultipleKeyCodes(&[LCtrl, Enter].as_slice())]]];
+        let mut layout = Layout::new(LAYERS);
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[LCtrl, Enter], layout.keycodes());
+        // Cancel chord keys on next keypress.
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[A], layout.keycodes());
+    }
+
+    // Tests the new Trans behavior.
+    // https://github.com/jtroo/kanata/issues/738
+    #[test]
+    fn test_trans_in_stacked_held_layers() {
+        static LAYERS: Layers<4, 1> = &[
+            [[Layer(1), NoOp, NoOp, k(A)]],
+            [[NoOp, Layer(2), NoOp, k(B)]],
+            [[NoOp, NoOp, Layer(3), Trans]],
+            [[NoOp, NoOp, NoOp, Trans]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        // change to layer 2
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // change to layer 3
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // change to layer 4
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // pressing Trans should press a key in layer 2, compared to previous behavior,
+        // where a key in layer 1 would be pressed
+        layout.event(Press(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes());
+        layout.event(Release(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_action_on_first_layer() {
+        static DEFSRC_LAYER: [Action; 2] = [NoOp, k(X)];
+        static LAYERS: Layers<2, 1> = &[
+            [[Layer(1), Trans]],
+            [[NoOp, MultipleActions(&[Trans].as_slice())]],
+        ];
+        let mut layout = Layout::new_with_trans_action_settings(&DEFSRC_LAYER, LAYERS, true, true);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[X], layout.keycodes());
+        layout.event(Release(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_taphold_tap() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
+                    timeout: 50,
+                    hold: k(Space),
+                    timeout_action: k(Space),
+                    tap: Trans,
+                    config: HoldTapConfig::Default,
+                    tap_hold_interval: 200,
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2)); // press th
+        for _ in 0..10 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        layout.event(Release(0, 2)); // release th
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes()); // B is resolved from Trans
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        // test tap action repeat
+        layout.event(Press(0, 2));
+        for _ in 0..30 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[B], layout.keycodes());
+        }
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_taphold_hold() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
+                    timeout: 50,
+                    hold: Trans,
+                    timeout_action: Trans,
+                    tap: k(Space),
+                    config: HoldTapConfig::Default,
+                    tap_hold_interval: 200,
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2)); // press th
+        for _ in 0..50 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        for _ in 0..70 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[B], layout.keycodes()); // B is resolved from Trans
+        }
+        layout.event(Release(0, 2)); // release th
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_tapdance_lazy() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                TapDance(&crate::action::TapDance {
+                    timeout: 100,
+                    actions: &[&Trans, &k(X)],
+                    config: TapDanceConfig::Lazy,
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        for _ in 0..10 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        layout.event(Release(0, 2));
+        for _ in 0..90 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_tapdance_eager() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                TapDance(&crate::action::TapDance {
+                    timeout: 100,
+                    actions: &[&Trans, &k(X)],
+                    config: TapDanceConfig::Eager,
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        for _ in 0..10 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[B], layout.keycodes());
+        }
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_multi() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[NoOp, NoOp, MultipleActions(&[Trans, k(X)].as_slice())]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        for _ in 0..10 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[B, X], layout.keycodes());
+        }
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_chords() {
+        const GROUP: ChordsGroup<core::convert::Infallible> = ChordsGroup {
+            coords: &[((0, 2), 1), ((0, 3), 2)],
+            chords: &[(1, &Trans), (2, &Trans), (3, &KeyCode(X))],
+            timeout: 100,
+        };
+        static LAYERS: Layers<4, 1> = &[
+            [[Layer(1), NoOp, k(A), k(B)]],
+            [[NoOp, Layer(2), k(C), k(D)]],
+            [[NoOp, NoOp, Chords(&GROUP), Chords(&GROUP)]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        for _ in 0..10 {
+            assert_eq!(CustomEvent::NoEvent, layout.tick());
+            assert_keys(&[], layout.keycodes());
+        }
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[C], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_fork() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                Fork(&ForkConfig {
+                    left: Trans,
+                    right: Trans,
+                    right_triggers: &[Space],
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes());
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_trans_in_switch() {
+        static LAYERS: Layers<3, 1> = &[
+            [[Layer(1), NoOp, k(A)]],
+            [[NoOp, Layer(2), k(B)]],
+            [[
+                NoOp,
+                NoOp,
+                Switch(&switch::Switch {
+                    cases: &[(&[], &Trans, BreakOrFallthrough::Break)],
+                    init_fn: None,
+                    callbacks: &[],
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+        layout.trans_resolution_behavior_v2 = true;
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[B], layout.keycodes());
+
+        layout.event(Release(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+    }
+
+    #[test]
+    fn test_multiple_taphold_trans() {
+        static LAYERS: Layers<4, 1> = &[
+            [[Layer(1), NoOp, NoOp, k(A)]],
+            [[
+                NoOp,
+                Layer(2),
+                NoOp,
+                HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
+                    timeout: 50,
+                    hold: k(B),
+                    timeout_action: k(B),
+                    tap: Trans,
+                    config: HoldTapConfig::Default,
+                    tap_hold_interval: 200,
+                }),
+            ]],
+            [[
+                NoOp,
+                NoOp,
+                Layer(3),
+                HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
+                    timeout: 50,
+                    hold: k(C),
+                    timeout_action: k(C),
+                    tap: Trans,
+                    config: HoldTapConfig::Default,
+                    tap_hold_interval: 200,
+                }),
+            ]],
+            [[
+                NoOp,
+                NoOp,
+                NoOp,
+                HoldTap(&HoldTapAction {
+                    on_press_reset_timeout_to: None,
+                    require_prior_idle: None,
+                    timeout: 50,
+                    hold: k(D),
+                    timeout_action: k(D),
+                    tap: Trans,
+                    config: HoldTapConfig::Default,
+                    tap_hold_interval: 200,
+                }),
+            ]],
+        ];
+        let mut layout = Layout::new(LAYERS);
+
+        layout.event(Press(0, 0));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 1));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 2));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Press(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Release(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[], layout.keycodes());
+        layout.event(Release(0, 3));
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[A], layout.keycodes());
+    }
+
+    #[test]
+    fn trans_in_multi_works_with_all_trans_settings() {
+        let permutations: &[(bool, bool)] =
+            &[(false, false), (false, true), (true, false), (true, true)];
+
+        for &(trans_v2, delegate_to_1st) in permutations {
+            static DEFSRC_LAYER: [Action; 3] = [NoOp, NoOp, k(X)];
+            static LAYERS: Layers<3, 1> = &[
+                [[
+                    Layer(1),
+                    DefaultLayer(1),
+                    MultipleActions(&[Trans, k(Y)].as_slice()),
+                ]],
+                [[NoOp, Layer(2), k(B)]],
+                [[NoOp, NoOp, Trans]],
+            ];
+            for &do_layer_switch in &[false, true] {
+                let mut layout = Layout::new_with_trans_action_settings(
+                    &DEFSRC_LAYER,
+                    LAYERS,
+                    trans_v2,
+                    delegate_to_1st,
+                );
+
+                layout.event(Press(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[X, Y], layout.keycodes());
+                layout.event(Release(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[], layout.keycodes());
+
+                if do_layer_switch {
+                    layout.event(Press(0, 1));
+                    assert_eq!(CustomEvent::NoEvent, layout.tick());
+                    assert_keys(&[], layout.keycodes());
+                    layout.event(Release(0, 1));
+                    assert_eq!(CustomEvent::NoEvent, layout.tick());
+                    assert_keys(&[], layout.keycodes());
+                    assert_eq!(layout.default_layer, 1);
+                } else {
+                    layout.event(Press(0, 0));
+                    assert_eq!(CustomEvent::NoEvent, layout.tick());
+                    assert_keys(&[], layout.keycodes());
+                }
+
+                layout.event(Press(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[B], layout.keycodes());
+                layout.event(Release(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[], layout.keycodes());
+
+                layout.event(Press(0, 1));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[], layout.keycodes());
+                layout.event(Press(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(
+                    match (trans_v2, delegate_to_1st) {
+                        (false, false) => &[X],
+                        (false, true) => &[X, Y],
+                        (true, _) => &[B],
+                    },
+                    layout.keycodes(),
+                );
+                layout.event(Release(0, 2));
+                assert_eq!(CustomEvent::NoEvent, layout.tick());
+                assert_keys(&[], layout.keycodes());
+            }
+        }
+    }
+
+    #[cfg(feature = "tap_hold_tracker")]
+    #[test]
+    fn hold_activated_is_set_on_hold_timeout() {
+        static LAYERS: Layers<1, 1> = &[[[HoldTap(&HoldTapAction {
+            timeout: 5,
+            hold: k(LAlt),
+            timeout_action: k(LAlt),
+            tap: k(Space),
+            config: HoldTapConfig::Default,
+            tap_hold_interval: 0,
+            on_press_reset_timeout_to: None,
+            require_prior_idle: None,
+        })]]];
+        let mut layout = Layout::new(LAYERS);
+        // Nothing set initially.
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+
+        layout.event(Press(0, 0));
+        for _ in 0..6 {
+            let _ = layout.tick();
+        }
+        // Hold action should be active.
+        assert_keys(&[LAlt], layout.keycodes());
+
+        // Flag should be set exactly once.
+        let info = layout
+            .tap_hold_tracker
+            .take_hold_activated()
+            .expect("hold_activated should be set");
+        assert_eq!(info.coord, (0, 0));
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+    }
+
+    #[cfg(feature = "tap_hold_tracker")]
+    #[test]
+    fn tap_activated_is_set_on_tap_release() {
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                timeout: 200,
+                hold: k(LAlt),
+                timeout_action: k(LAlt),
+                tap: k(Space),
+                config: HoldTapConfig::Default,
+                tap_hold_interval: 0,
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+            }),
+            k(A),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+
+        // Quick press and release triggers tap.
+        layout.event(Press(0, 0));
+        let _ = layout.tick();
+        layout.event(Release(0, 0));
+        let _ = layout.tick();
+
+        assert_keys(&[Space], layout.keycodes());
+        let info = layout
+            .tap_hold_tracker
+            .take_tap_activated()
+            .expect("tap_activated should be set");
+        assert_eq!(info.coord, (0, 0));
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+    }
+
+    #[cfg(feature = "tap_hold_tracker")]
+    #[test]
+    fn hold_activated_is_set_on_permissive_hold() {
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                timeout: 200,
+                hold: k(LAlt),
+                timeout_action: k(LAlt),
+                tap: k(Space),
+                config: HoldTapConfig::PermissiveHold,
+                tap_hold_interval: 0,
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+            }),
+            k(A),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+
+        // PermissiveHold: press hold-tap key, press another key, release it => hold.
+        layout.event(Press(0, 0));
+        let _ = layout.tick();
+        layout.event(Press(0, 1));
+        let _ = layout.tick();
+        layout.event(Release(0, 1));
+        let _ = layout.tick();
+
+        assert_keys(&[LAlt], layout.keycodes());
+        let info = layout
+            .tap_hold_tracker
+            .take_hold_activated()
+            .expect("hold_activated should be set via waiting_into_hold");
+        assert_eq!(info.coord, (0, 0));
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+    }
+
+    #[cfg(feature = "tap_hold_tracker")]
+    #[test]
+    fn hold_activated_is_set_on_hold_on_other_key_press() {
+        static LAYERS: Layers<2, 1> = &[[[
+            HoldTap(&HoldTapAction {
+                timeout: 200,
+                hold: k(LAlt),
+                timeout_action: k(LAlt),
+                tap: k(Space),
+                config: HoldTapConfig::HoldOnOtherKeyPress,
+                tap_hold_interval: 0,
+                on_press_reset_timeout_to: None,
+                require_prior_idle: None,
+            }),
+            k(A),
+        ]]];
+        let mut layout = Layout::new(LAYERS);
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+
+        // HoldOnOtherKeyPress: press hold-tap key, then press another key => hold.
+        layout.event(Press(0, 0));
+        let _ = layout.tick();
+        layout.event(Press(0, 1));
+        let _ = layout.tick();
+
+        assert_keys(&[LAlt], layout.keycodes());
+        let info = layout
+            .tap_hold_tracker
+            .take_hold_activated()
+            .expect("hold_activated should be set via waiting_into_hold");
+        assert_eq!(info.coord, (0, 0));
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+    }
+
+    #[test]
+    fn chord_does_not_set_tap_hold_activated() {
+        const GROUP: ChordsGroup<core::convert::Infallible> = ChordsGroup {
+            coords: &[((0, 0), 1), ((0, 1), 2)],
+            chords: &[(3, &KeyCode(Kb5))],
+            timeout: 100,
+        };
+        static LAYERS: Layers<2, 1> = &[[[Chords(&GROUP), Chords(&GROUP)]]];
+
+        let mut layout = Layout::new(LAYERS);
+        layout.event(Press(0, 0));
+        for _ in 0..50 {
+            let _ = layout.tick();
+        }
+        layout.event(Press(0, 1));
+        for _ in 0..50 {
+            let _ = layout.tick();
+        }
+        assert_keys(&[Kb5], layout.keycodes());
+        // Chord resolution must not set tap or hold activated flags.
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+    }
+
+    #[test]
+    fn tap_dance_does_not_set_tap_hold_activated() {
+        static LAYERS: Layers<2, 1> = &[[[
+            TapDance(&crate::action::TapDance {
+                timeout: 100,
+                actions: &[&k(LShift), &k(LCtrl)],
+                config: TapDanceConfig::Lazy,
+            }),
+            k(A),
+        ]]];
+
+        let mut layout = Layout::new(LAYERS);
+        // Single tap, wait for timeout.
+        layout.event(Press(0, 0));
+        for _ in 0..101 {
+            let _ = layout.tick();
+        }
+        assert_keys(&[LShift], layout.keycodes());
+        // Tap-dance resolution must not set tap or hold activated flags.
+        assert!(layout.tap_hold_tracker.take_hold_activated().is_none());
+        assert!(layout.tap_hold_tracker.take_tap_activated().is_none());
+    }
 }
diff --git a/keyberon/src/layout/contextual_execution.rs b/keyberon/src/layout/contextual_execution.rs
new file mode 100644
index 000000000..8049868a8
--- /dev/null
+++ b/keyberon/src/layout/contextual_execution.rs
@@ -0,0 +1,26 @@
+//! Information about what state the keyberon layout is in
+//! and handling conditional execution based on state.
+
+use super::*;
+
+#[derive(Clone, Copy, Debug)]
+pub(super) struct ContextualExecution {
+    /// Known pause case:
+    /// - When replicating output keys during chordv1 activation.
+    pub(super) pause_historical_keys_updates: bool,
+}
+
+impl ContextualExecution {
+    pub(super) fn new() -> Self {
+        Self {
+            pause_historical_keys_updates: false,
+        }
+    }
+
+    /// Push into historical keys while checking the pause state.
+    pub(super) fn push_historical_key<T: Copy>(&self, h: &mut History<T>, e: T) {
+        if !self.pause_historical_keys_updates {
+            h.push_front(e);
+        }
+    }
+}
diff --git a/keyberon/src/lib.rs b/keyberon/src/lib.rs
index 78258ea05..bacf39abf 100644
--- a/keyberon/src/lib.rs
+++ b/keyberon/src/lib.rs
@@ -2,5 +2,8 @@
 //! Please make contributions to the original project.
 
 pub mod action;
+pub mod chord;
 pub mod key_code;
 pub mod layout;
+mod multikey_buffer;
+pub mod tap_hold_tracker;
diff --git a/keyberon/src/multikey_buffer.rs b/keyberon/src/multikey_buffer.rs
new file mode 100644
index 000000000..85dec84b1
--- /dev/null
+++ b/keyberon/src/multikey_buffer.rs
@@ -0,0 +1,87 @@
+//! Module for `MultiKeyBuffer`.
+
+use std::{array, slice};
+
+use crate::action::{Action, ONE_SHOT_MAX_ACTIVE};
+use crate::key_code::KeyCode;
+
+// Presumably this should be plenty.
+// ONE_SHOT_MAX_ACTIVE is already likely unreasonably large enough.
+// This buffer capacity adds more onto that,
+// just in case somebody finds a way to use all of the one-shot capacity.
+const BUFCAP: usize = ONE_SHOT_MAX_ACTIVE + 4;
+
+/// This is an unsafe container that enables a mutable Action::MultipleKeyCodes.
+pub(crate) struct MultiKeyBuffer<'a, T> {
+    buf: [KeyCode; BUFCAP],
+    size: usize,
+    ptr: *mut &'static [KeyCode],
+    ac: *mut Action<'a, T>,
+}
+
+unsafe impl<T> Send for MultiKeyBuffer<'_, T> {}
+
+impl<'a, T> MultiKeyBuffer<'a, T> {
+    /// Create a new instance of `MultiKeyBuffer`.
+    ///
+    /// # Safety
+    ///
+    /// The program should not have any references to the inner buffer when the struct is dropped.
+    pub(crate) unsafe fn new() -> Self {
+        Self {
+            buf: array::from_fn(|_| KeyCode::Escape),
+            size: 0,
+            ptr: Box::leak(Box::new(slice::from_raw_parts(
+                core::ptr::NonNull::dangling().as_ptr(),
+                0,
+            ))),
+            ac: Box::leak(Box::new(Action::NoOp)),
+        }
+    }
+
+    /// Set the current size of the buffer to zero.
+    ///
+    /// # Safety
+    ///
+    /// The program should not have any references to the inner buffer.
+    pub(crate) unsafe fn clear(&mut self) {
+        self.size = 0;
+    }
+
+    /// Push to the end of the buffer. If the buffer is full, this silently fails.
+    ///
+    /// # Safety
+    ///
+    /// The program should not have any references to the inner buffer.
+    pub(crate) unsafe fn push(&mut self, kc: KeyCode) {
+        if self.size < BUFCAP {
+            self.buf[self.size] = kc;
+            self.size += 1;
+        }
+    }
+
+    /// Get a reference to the inner buffer in the form of an `Action`.
+    /// The `Action` will be the variant `MultipleKeyCodes`,
+    /// containing all keys that have been pushed.
+    ///
+    /// # Safety
+    ///
+    /// The program should not have any references to the inner buffer before calling.
+    /// The program should not mutate the buffer after calling this function until after the
+    /// returned reference is dropped.
+    pub(crate) unsafe fn get_ref(&self) -> &'a Action<'a, T> {
+        *self.ac = Action::NoOp;
+        *self.ptr = slice::from_raw_parts(self.buf.as_ptr(), self.size);
+        *self.ac = Action::MultipleKeyCodes(&*self.ptr);
+        &*self.ac
+    }
+}
+
+impl<T> Drop for MultiKeyBuffer<'_, T> {
+    fn drop(&mut self) {
+        unsafe {
+            drop(Box::from_raw(self.ac));
+            drop(Box::from_raw(self.ptr));
+        }
+    }
+}
diff --git a/keyberon/src/tap_hold_tracker.rs b/keyberon/src/tap_hold_tracker.rs
new file mode 100644
index 000000000..e3797f063
--- /dev/null
+++ b/keyberon/src/tap_hold_tracker.rs
@@ -0,0 +1,119 @@
+//! Tracks tap-hold activation events for external consumers (e.g. TCP broadcast).
+//!
+//! When the `tap_hold_tracker` feature is enabled, this module stores the
+//! coordinate of the most recent hold/tap activation so that higher-level code
+//! can relay it over the network.  When the feature is disabled the tracker is
+//! a zero-sized no-op — all setters are empty and all getters return `None`.
+//!
+//! The `config` parameter on the setters accepts a `&WaitingConfig` reference;
+//! the `matches!` guard lives inside the method body so that the no-op stub's
+//! empty body causes the compiler to eliminate the call entirely.
+
+#[cfg(feature = "tap_hold_tracker")]
+mod inner {
+    use crate::layout::{KCoord, WaitingConfig};
+
+    /// Information about a tap-hold key that just transitioned to hold state.
+    #[derive(Debug, Clone, Copy)]
+    pub struct HoldActivatedInfo {
+        /// The key coordinate (row, column).
+        pub coord: KCoord,
+    }
+
+    /// Information about a tap-hold key that just triggered its tap action.
+    #[derive(Debug, Clone, Copy)]
+    pub struct TapActivatedInfo {
+        /// The key coordinate (row, column).
+        pub coord: KCoord,
+    }
+
+    /// Records the most recent tap-hold activation event.
+    #[derive(Debug, Default)]
+    pub struct TapHoldTracker {
+        hold_activated: Option<HoldActivatedInfo>,
+        tap_activated: Option<TapActivatedInfo>,
+    }
+
+    impl TapHoldTracker {
+        pub(crate) fn set_hold_activated<'a, T: std::fmt::Debug>(
+            &mut self,
+            coord: KCoord,
+            config: &WaitingConfig<'a, T>,
+        ) {
+            if matches!(config, WaitingConfig::HoldTap(..)) {
+                self.hold_activated = Some(HoldActivatedInfo { coord });
+            }
+        }
+
+        pub(crate) fn set_tap_activated<'a, T: std::fmt::Debug>(
+            &mut self,
+            coord: KCoord,
+            config: &WaitingConfig<'a, T>,
+        ) {
+            if matches!(config, WaitingConfig::HoldTap(..)) {
+                self.tap_activated = Some(TapActivatedInfo { coord });
+            }
+        }
+
+        pub fn take_hold_activated(&mut self) -> Option<HoldActivatedInfo> {
+            self.hold_activated.take()
+        }
+
+        pub fn take_tap_activated(&mut self) -> Option<TapActivatedInfo> {
+            self.tap_activated.take()
+        }
+    }
+}
+
+#[cfg(not(feature = "tap_hold_tracker"))]
+mod inner {
+    use crate::layout::{KCoord, WaitingConfig};
+
+    /// Stub: no coordinate data stored when the feature is disabled.
+    #[derive(Debug, Clone, Copy)]
+    pub struct HoldActivatedInfo {
+        /// The key coordinate (row, column).
+        pub coord: KCoord,
+    }
+
+    /// Stub: no coordinate data stored when the feature is disabled.
+    #[derive(Debug, Clone, Copy)]
+    pub struct TapActivatedInfo {
+        /// The key coordinate (row, column).
+        pub coord: KCoord,
+    }
+
+    /// Zero-sized no-op tracker when the feature is disabled.
+    #[derive(Debug, Default)]
+    pub struct TapHoldTracker;
+
+    impl TapHoldTracker {
+        #[inline(always)]
+        pub(crate) fn set_hold_activated<'a, T: std::fmt::Debug>(
+            &mut self,
+            _coord: KCoord,
+            _config: &WaitingConfig<'a, T>,
+        ) {
+        }
+
+        #[inline(always)]
+        pub(crate) fn set_tap_activated<'a, T: std::fmt::Debug>(
+            &mut self,
+            _coord: KCoord,
+            _config: &WaitingConfig<'a, T>,
+        ) {
+        }
+
+        #[inline(always)]
+        pub fn take_hold_activated(&mut self) -> Option<HoldActivatedInfo> {
+            None
+        }
+
+        #[inline(always)]
+        pub fn take_tap_activated(&mut self) -> Option<TapActivatedInfo> {
+            None
+        }
+    }
+}
+
+pub use inner::*;
diff --git a/myfile b/myfile
new file mode 100644
index 000000000..e9944e6b6
Binary files /dev/null and b/myfile differ
diff --git a/parser/.gitignore b/parser/.gitignore
index 62e2af0b8..cb4f2dd90 100644
--- a/parser/.gitignore
+++ b/parser/.gitignore
@@ -1,2 +1,3 @@
 # Ignore Cargo.lock since this is a library crate
 Cargo.lock
+target
\ No newline at end of file
diff --git a/parser/Cargo.toml b/parser/Cargo.toml
index 91c3c20c7..699ed5ba5 100644
--- a/parser/Cargo.toml
+++ b/parser/Cargo.toml
@@ -1,32 +1,38 @@
 [package]
 name = "kanata-parser"
-version = "0.1.0"
+version = "0.1120.1"
 authors = ["jtroo <j.andreitabs@gmail.com>"]
 description = "A parser for configuration language of kanata, a keyboard remapper."
 keywords = ["kanata", "parser"]
 homepage = "https://github.com/jtroo/kanata"
 repository = "https://github.com/jtroo/kanata"
 readme = "README.md"
-license = "LGPL-3.0"
+license = "LGPL-3.0-only"
 edition = "2021"
 
 [dependencies]
-log = { version = "0.4.8", default_features = false }
 anyhow = "1"
-parking_lot = "0.12"
+bitflags = "2.5.0"
+bytemuck = "1.15.0"
+log = { version = "0.4.8", default-features = false }
+miette = { version = "5.7.0", features = ["fancy"] }
 once_cell = "1"
-radix_trie = "0.2"
+ordered-float = "5.1.0"
+parking_lot = "0.12"
+patricia_tree = "0.9"
 rustc-hash = "1.1.0"
-miette = { version = "5.7.0", features = ["fancy"] }
 thiserror = "1.0.38"
 
-kanata-keyberon = { path = "../keyberon" }
+kanata-keyberon = { path = "../keyberon", version = "0.1120.1" }
+
+[dev-dependencies]
+simplelog = "0.12.0"
 
 [features]
 cmd = []
 interception_driver = []
-
-[target.'cfg(target_os = "linux")'.dependencies]
-evdev = "=0.12.0"
-
-[target.'cfg(target_os = "windows")'.dependencies]
+gui = []
+lsp = []
+win_llhook_read_scancodes = []
+win_sendinput_send_scancodes = []
+zippychord = []
diff --git a/parser/README.md b/parser/README.md
index 9e0b759a4..3297d6fbf 100644
--- a/parser/README.md
+++ b/parser/README.md
@@ -1,3 +1,5 @@
 # kanata-parser
 
 A parser for configuration language of [kanata](https://github.com/jtroo/kanata).
+
+This crate does not follow semver. It tracks the version of kanata.
diff --git a/parser/src/cfg/alloc.rs b/parser/src/cfg/alloc.rs
index f0d520a6f..333ae35d7 100644
--- a/parser/src/cfg/alloc.rs
+++ b/parser/src/cfg/alloc.rs
@@ -11,8 +11,19 @@ use std::sync::Arc;
 ///
 /// In practice, this is not difficult to do in the `cfg` module which only exposes a single public
 /// method.
+///
+/// To avoid leaks, types transformed to &'static by this struct
+/// should not contain nested allocations,
+/// or if they do, the nested allocations should also
+/// be managed by this struct.
 pub(crate) struct Allocations {
-    allocations: Mutex<Vec<usize>>,
+    allocations: Mutex<Vec<Allocation>>,
+}
+
+#[derive(Debug, Copy, Clone)]
+pub(crate) struct Allocation {
+    ptr: usize,
+    len: usize,
 }
 
 impl std::fmt::Debug for Allocations {
@@ -27,8 +38,14 @@ impl Drop for Allocations {
             "freeing allocations of length {}",
             self.allocations.lock().len()
         );
-        for p in self.allocations.lock().iter().rev().copied() {
-            unsafe { drop(Box::from_raw(p as *mut usize)) };
+        for a in self.allocations.lock().iter().rev().copied() {
+            log::debug!("freeing ptr 0x{:x} len{}", a.ptr, a.len);
+            unsafe {
+                drop(Box::<[u8]>::from_raw(std::ptr::slice_from_raw_parts_mut(
+                    a.ptr as *mut u8,
+                    a.len,
+                )))
+            };
         }
     }
 }
@@ -40,48 +57,63 @@ impl Allocations {
     ///
     /// Ensure that all associated allocations are no longer referenced before dropping all
     /// clones of the `Arc`.
-    pub(super) unsafe fn new() -> Arc<Self> {
+    pub(crate) unsafe fn new() -> Arc<Self> {
         Arc::new(Self {
             allocations: Mutex::new(vec![]),
         })
     }
 
-    /// Returns a `&'static T` by leaking the existing box.
-    pub(super) fn bref<T>(&self, v: Box<T>) -> &'static T {
-        let p = Box::into_raw(v);
-        if (p as usize) < 16 {
-            panic!("bref bad ptr");
-        }
-        self.allocations.lock().push(p as usize);
-        Box::leak(unsafe { Box::from_raw(p) })
-    }
-
     /// Returns a `&'static T` by leaking a newly created Box of `v`.
-    pub(super) fn sref<T>(&self, v: T) -> &'static T {
+    pub(crate) fn sref<T>(&self, v: T) -> &'static T {
         let p = Box::into_raw(Box::new(v));
-        if (p as usize) < 16 {
-            panic!("sref bad ptr");
-        }
-        self.allocations.lock().push(p as usize);
+        log::debug!(
+            "sref type: {}, ptr:{p:?} sz:{}",
+            std::any::type_name::<T>(),
+            std::mem::size_of::<T>()
+        );
+        self.allocations.lock().push(Allocation {
+            ptr: p as usize,
+            len: std::mem::size_of::<T>(),
+        });
         Box::leak(unsafe { Box::from_raw(p) })
     }
 
-    fn bref_slice<T>(&self, v: Box<[T]>) -> &'static [T] {
+    pub(crate) fn bref_slice<T>(&self, v: Box<[T]>) -> &'static [T] {
         // An empty slice has no backing allocation. `Box<[T]>` is a fat pointer so the leaked return
         // will contain a length of 0 and an invalid pointer.
         if !v.is_empty() {
-            self.allocations.lock().push(v.as_ptr() as usize);
+            let p = v.as_ptr();
+            log::debug!(
+                "bref_slice type: {}, ptr:{p:?} sz:{}",
+                std::any::type_name::<T>(),
+                std::mem::size_of::<T>()
+            );
+            self.allocations.lock().push(Allocation {
+                ptr: p as usize,
+                len: std::mem::size_of::<T>() * v.len(),
+            });
         }
         Box::leak(v)
     }
 
     /// Returns a &'static [&'static T] from a `Vec<T>` by converting to a boxed slice and leaking it.
-    pub(super) fn sref_vec<T>(&self, v: Vec<T>) -> &'static [T] {
+    pub(crate) fn sref_vec<T>(&self, v: Vec<T>) -> &'static [T] {
+        log::debug!("sref_vec {}", std::any::type_name::<T>());
         self.bref_slice(v.into_boxed_slice())
     }
 
-    /// Returns a `&'static [&'static T]` by leaking a newly created box and boxed slice of `v`.
-    pub(super) fn sref_slice<T>(&self, v: T) -> &'static [&'static T] {
-        self.bref_slice(vec![self.sref(v)].into_boxed_slice())
+    /// Returns a `&'static str` by leaking a String.
+    pub(crate) fn sref_str(&self, v: String) -> &'static str {
+        if !v.capacity() == 0 {
+            ""
+        } else {
+            let len = v.len();
+            let s = v.leak();
+            self.allocations.lock().push(Allocation {
+                ptr: s.as_ptr() as usize,
+                len,
+            });
+            s
+        }
     }
 }
diff --git a/parser/src/cfg/arbitrary_code.rs b/parser/src/cfg/arbitrary_code.rs
new file mode 100644
index 000000000..118f4029f
--- /dev/null
+++ b/parser/src/cfg/arbitrary_code.rs
@@ -0,0 +1,20 @@
+use super::*;
+
+use crate::bail;
+use anyhow::anyhow;
+
+pub(crate) fn parse_arbitrary_code(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "arbitrary code expects one parameter: <code: 0-767>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_MSG}");
+    }
+    let code = ac_params[0]
+        .atom(s.vars())
+        .map(str::parse::<u16>)
+        .and_then(|c| c.ok())
+        .ok_or_else(|| anyhow!("{ERR_MSG}: got {:?}", ac_params[0]))?;
+    custom(CustomAction::SendArbitraryCode(code), &s.a)
+}
diff --git a/parser/src/cfg/caps_word.rs b/parser/src/cfg/caps_word.rs
new file mode 100644
index 000000000..5c88a04aa
--- /dev/null
+++ b/parser/src/cfg/caps_word.rs
@@ -0,0 +1,110 @@
+use super::*;
+
+use crate::bail;
+
+pub(crate) fn parse_caps_word(
+    ac_params: &[SExpr],
+    repress_behaviour: CapsWordRepressBehaviour,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_STR: &str = "caps-word expects 1 param: <timeout>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_STR}\nFound {} params instead of 1", ac_params.len());
+    }
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    custom(
+        CustomAction::CapsWord(CapsWordCfg {
+            repress_behaviour,
+            keys_to_capitalize: &[
+                KeyCode::A,
+                KeyCode::B,
+                KeyCode::C,
+                KeyCode::D,
+                KeyCode::E,
+                KeyCode::F,
+                KeyCode::G,
+                KeyCode::H,
+                KeyCode::I,
+                KeyCode::J,
+                KeyCode::K,
+                KeyCode::L,
+                KeyCode::M,
+                KeyCode::N,
+                KeyCode::O,
+                KeyCode::P,
+                KeyCode::Q,
+                KeyCode::R,
+                KeyCode::S,
+                KeyCode::T,
+                KeyCode::U,
+                KeyCode::V,
+                KeyCode::W,
+                KeyCode::X,
+                KeyCode::Y,
+                KeyCode::Z,
+                KeyCode::Minus,
+            ],
+            keys_nonterminal: &[
+                KeyCode::Kb0,
+                KeyCode::Kb1,
+                KeyCode::Kb2,
+                KeyCode::Kb3,
+                KeyCode::Kb4,
+                KeyCode::Kb5,
+                KeyCode::Kb6,
+                KeyCode::Kb7,
+                KeyCode::Kb8,
+                KeyCode::Kb9,
+                KeyCode::Kp0,
+                KeyCode::Kp1,
+                KeyCode::Kp2,
+                KeyCode::Kp3,
+                KeyCode::Kp4,
+                KeyCode::Kp5,
+                KeyCode::Kp6,
+                KeyCode::Kp7,
+                KeyCode::Kp8,
+                KeyCode::Kp9,
+                KeyCode::BSpace,
+                KeyCode::Delete,
+                KeyCode::Up,
+                KeyCode::Down,
+                KeyCode::Left,
+                KeyCode::Right,
+            ],
+            timeout,
+        }),
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_caps_word_custom(
+    ac_params: &[SExpr],
+    repress_behaviour: CapsWordRepressBehaviour,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_STR: &str = "caps-word-custom expects 3 param: <timeout> <keys-to-capitalize> <extra-non-terminal-keys>";
+    if ac_params.len() != 3 {
+        bail!("{ERR_STR}\nFound {} params instead of 3", ac_params.len());
+    }
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    custom(
+        CustomAction::CapsWord(CapsWordCfg {
+            repress_behaviour,
+            keys_to_capitalize: s.a.sref_vec(
+                parse_key_list(&ac_params[1], s, "keys-to-capitalize")?
+                    .into_iter()
+                    .map(KeyCode::from)
+                    .collect(),
+            ),
+            keys_nonterminal: s.a.sref_vec(
+                parse_key_list(&ac_params[2], s, "extra-non-terminal-keys")?
+                    .into_iter()
+                    .map(KeyCode::from)
+                    .collect(),
+            ),
+            timeout,
+        }),
+        &s.a,
+    )
+}
diff --git a/parser/src/cfg/chord.rs b/parser/src/cfg/chord.rs
new file mode 100644
index 000000000..9c88bb760
--- /dev/null
+++ b/parser/src/cfg/chord.rs
@@ -0,0 +1,342 @@
+use kanata_keyberon::chord::{ChordV2, ChordsForKey, ChordsForKeys, ReleaseBehaviour};
+use rustc_hash::{FxHashMap, FxHashSet};
+
+use std::fs;
+
+use crate::{anyhow_expr, bail_expr};
+
+use super::*;
+
+pub(crate) fn parse_defchordv2(
+    exprs: &[SExpr],
+    s: &ParserState,
+) -> Result<ChordsForKeys<'static, KanataCustom>> {
+    if exprs[0].atom(None).expect("should be atom") == "defchordsv2-experimental" {
+        log::warn!(
+            "You should replace defchordsv2-experimental with defchordsv2.\n\
+             Using -experimental will be invalid in the future."
+        );
+    }
+
+    let mut chunks = exprs[1..].chunks_exact(5);
+    let mut chords_container = ChordsForKeys::<'static, KanataCustom> {
+        mapping: FxHashMap::default(),
+    };
+
+    let mut all_participating_key_sets = FxHashSet::default();
+
+    let all_chords = chunks
+        .by_ref()
+        .flat_map(|chunk| match chunk[0] {
+            // Match a line like
+            // (include filename.txt) () 100 all-released (layer1 layer2)
+            SExpr::List(Spanned {
+                t: ref exprs,
+                span: _,
+            }) if matches!(exprs.first(), Some(SExpr::Atom(a)) if a.t == "include") => {
+                let file_name = exprs[1].atom(s.vars()).unwrap();
+                let chord_translation = ChordTranslation::create(
+                    file_name,
+                    &chunk[2],
+                    &chunk[3],
+                    &chunk[4],
+                    &s.layers[0][0],
+                );
+                let chord_definitions = parse_chord_file(file_name).unwrap();
+                let processed = chord_definitions.iter().map(|chord_def| {
+                    let chunk = chord_translation.translate_chord(chord_def);
+                    parse_single_chord(&chunk, s, &mut all_participating_key_sets)
+                });
+                Ok::<_, ParseError>(processed.collect::<Vec<_>>())
+            }
+            _ => Ok(vec![parse_single_chord(
+                chunk,
+                s,
+                &mut all_participating_key_sets,
+            )]),
+        })
+        .flat_map(|vec_result| vec_result.into_iter())
+        .collect::<Vec<Result<_>>>();
+    let unsuccessful = all_chords
+        .iter()
+        .filter_map(|r| r.as_ref().err())
+        .collect::<Vec<_>>();
+    if let Some(e) = unsuccessful.first() {
+        return Err((*e).clone());
+    }
+
+    let successful = all_chords
+        .into_iter()
+        .filter_map(Result::ok)
+        .collect::<Vec<_>>();
+    for chord in successful {
+        for pkey in chord.participating_keys.iter().copied() {
+            //log::trace!("chord for key:{pkey:?} > {chord:?}");
+            chords_container
+                .mapping
+                .entry(pkey)
+                .or_insert(ChordsForKey { chords: vec![] })
+                .chords
+                .push(s.a.sref(chord.clone()));
+        }
+    }
+    let rem = chunks.remainder();
+    if !rem.is_empty() {
+        bail_expr!(
+            rem.last().unwrap(),
+            "Incomplete chord entry. Each chord entry must have 5 items:\n\
+        participating-keys, action, timeout, release-type, disabled-layers"
+        );
+    }
+    Ok(chords_container)
+}
+
+fn parse_single_chord(
+    chunk: &[SExpr],
+    s: &ParserState,
+    all_participating_key_sets: &mut FxHashSet<Vec<u16>>,
+) -> Result<ChordV2<'static, KanataCustom>> {
+    let participants = parse_participating_keys(&chunk[0], s)?;
+    if !all_participating_key_sets.insert(participants.clone()) {
+        bail_expr!(
+            &chunk[0],
+            "Duplicate participating-keys, key sets may be used only once."
+        );
+    }
+    let action = parse_action(&chunk[1], s)?;
+    let timeout = parse_timeout(&chunk[2], s)?;
+    let release_behaviour = parse_release_behaviour(&chunk[3], s)?;
+    let disabled_layers = parse_disabled_layers(&chunk[4], s)?;
+    let chord: ChordV2<'static, KanataCustom> = ChordV2 {
+        action,
+        participating_keys: s.a.sref_vec(participants.clone()),
+        pending_duration: timeout,
+        disabled_layers: s.a.sref_vec(disabled_layers),
+        release_behaviour,
+    };
+    Ok(s.a.sref(chord).clone())
+}
+
+fn parse_participating_keys(keys: &SExpr, s: &ParserState) -> Result<Vec<u16>> {
+    let mut participants = keys
+        .list(s.vars())
+        .map(|l| {
+            l.iter()
+                .try_fold(vec![], |mut keys, key| -> Result<Vec<u16>> {
+                    let k = key.atom(s.vars()).and_then(str_to_oscode).ok_or_else(|| {
+                        anyhow_expr!(
+                            key,
+                            "The first chord item must be a list of keys.\nInvalid key name."
+                        )
+                    })?;
+                    keys.push(k.into());
+                    Ok(keys)
+                })
+        })
+        .ok_or_else(|| anyhow_expr!(keys, "The first chord item must be a list of keys."))??;
+    if participants.len() < 2 {
+        bail_expr!(keys, "The minimum number of participating chord keys is 2");
+    }
+    participants.sort();
+    Ok(participants)
+}
+
+fn parse_timeout(chunk: &SExpr, s: &ParserState) -> Result<u16> {
+    let timeout = parse_non_zero_u16(chunk, s, "chord timeout")?;
+    Ok(timeout)
+}
+
+fn parse_release_behaviour(
+    release_behaviour_string: &SExpr,
+    s: &ParserState,
+) -> Result<ReleaseBehaviour> {
+    let release_behaviour = release_behaviour_string
+        .atom(s.vars())
+        .and_then(|r| {
+            Some(match r {
+                "first-release" => ReleaseBehaviour::OnFirstRelease,
+                "all-released" => ReleaseBehaviour::OnLastRelease,
+                _ => return None,
+            })
+        })
+        .ok_or_else(|| {
+            anyhow_expr!(
+                release_behaviour_string,
+                "Chord release behaviour must be one of:\n\
+                first-release | all-released"
+            )
+        })?;
+    Ok(release_behaviour)
+}
+
+fn parse_disabled_layers(disabled_layers: &SExpr, s: &ParserState) -> Result<Vec<u16>> {
+    let disabled_layers = disabled_layers
+        .list(s.vars())
+        .map(|dl| {
+            dl.iter()
+                .try_fold(vec![], |mut layers, layer| -> Result<Vec<u16>> {
+                    let l_idx = layer
+                        .atom(s.vars())
+                        .and_then(|l| s.layer_idxs.get(l))
+                        .ok_or_else(|| anyhow_expr!(layer, "Not a known layer name."))?;
+                    layers.push((*l_idx) as u16);
+                    Ok(layers)
+                })
+        })
+        .ok_or_else(|| {
+            anyhow_expr!(
+                disabled_layers,
+                "Disabled layers must be a list of layer names"
+            )
+        })??;
+    Ok(disabled_layers)
+}
+
+fn parse_chord_file(file_name: &str) -> Result<Vec<ChordDefinition>> {
+    let input_data =
+        fs::read_to_string(file_name).unwrap_or_else(|_| panic!("Unable to read file {file_name}"));
+    let parsed_chords = parse_input(&input_data).unwrap();
+    Ok(parsed_chords)
+}
+
+fn parse_input(input: &str) -> Result<Vec<ChordDefinition>> {
+    input
+        .lines()
+        .filter(|line| !line.trim().is_empty() && !line.trim().starts_with("//"))
+        .map(|line| {
+            let mut caps = line.split('\t');
+            let error_message = format!(
+                "Each line needs to have an action separated by a tab character, got '{line}'"
+            );
+            let keys = caps.next().expect(&error_message);
+            let action = caps.next().expect(&error_message);
+            Ok(ChordDefinition {
+                keys: keys.to_string(),
+                action: action.to_string(),
+            })
+        })
+        .collect()
+}
+
+#[derive(Debug)]
+struct ChordDefinition {
+    keys: String,
+    action: String,
+}
+
+struct ChordTranslation<'a> {
+    file_name: &'a str,
+    target_map: FxHashMap<String, String>,
+    postprocess_map: FxHashMap<String, String>,
+    timeout: &'a SExpr,
+    release_behaviour: &'a SExpr,
+    disabled_layers: &'a SExpr,
+}
+
+impl<'a> ChordTranslation<'a> {
+    fn create(
+        file_name: &'a str,
+        timeout: &'a SExpr,
+        release_behaviour: &'a SExpr,
+        disabled_layers: &'a SExpr,
+        first_layer: &[Action<'static, KanataCustom>],
+    ) -> Self {
+        let postprocess_map: FxHashMap<String, String> = [
+            ("semicolon", ";"),
+            ("colon", "S-."),
+            ("slash", "/"),
+            ("apostrophe", "'"),
+            ("dot", "."),
+            (" ", "spc"),
+        ]
+        .iter()
+        .cloned()
+        .map(|(k, v)| (k.to_string(), v.to_string()))
+        .collect();
+        let target_map = first_layer
+            .iter()
+            .enumerate()
+            .filter_map(|(idx, layout)| {
+                layout
+                    .key_codes()
+                    .next()
+                    .map(|kc| kc.to_string().to_lowercase())
+                    .zip(
+                        idx.try_into()
+                            .ok()
+                            .and_then(OsCode::from_u16)
+                            .map(|osc| osc.to_string().to_lowercase()),
+                    )
+            })
+            .collect::<Vec<_>>()
+            .into_iter()
+            .chain(vec![(" ".to_string(), "spc".to_string())])
+            .collect::<FxHashMap<_, _>>();
+        ChordTranslation {
+            file_name,
+            target_map,
+            postprocess_map,
+            timeout,
+            release_behaviour,
+            disabled_layers,
+        }
+    }
+
+    fn post_process(&self, converted: &str) -> String {
+        self.postprocess_map
+            .get(converted)
+            .map(|c| c.to_string())
+            .unwrap_or_else(|| {
+                if converted.chars().all(|c| c.is_uppercase()) {
+                    format!("S-{}", converted.to_lowercase())
+                } else {
+                    converted.to_string()
+                }
+            })
+    }
+
+    fn participant_keys(&self, keys: &str) -> Vec<String> {
+        keys.chars()
+            .map(|key| {
+                self.target_map
+                    .get(key.to_string().to_lowercase().as_str())
+                    .map(|c| self.postprocess_map.get(c).unwrap_or(c).to_string())
+                    .unwrap_or_else(|| key.to_string())
+            })
+            .collect::<Vec<String>>()
+    }
+
+    fn action(&self, action: &str) -> Vec<String> {
+        let mut action_strings = action
+            .chars()
+            .map(|c| self.post_process(&c.to_string()))
+            .collect::<Vec<_>>();
+        // Wait 50ms for one-shot Shift to release
+        // TODO: This would be better handled by a (multi (release-key lsft)(release-key rsft))
+        // but I haven't gotten that to work yet.
+        action_strings.insert(1, "50".to_string());
+        action_strings.extend_from_slice(&[
+            "sldr".to_string(),
+            "spc".to_string(),
+            "nop0".to_string(),
+        ]);
+        action_strings
+    }
+
+    fn translate_chord(&self, chord_def: &ChordDefinition) -> Vec<SExpr> {
+        let sexpr_string = format!(
+            "(({}) (macro {}))",
+            self.participant_keys(&chord_def.keys).join(" "),
+            self.action(&chord_def.action).join(" ")
+        );
+        let mut participant_action = sexpr::parse(&sexpr_string, self.file_name).unwrap()[0]
+            .t
+            .clone();
+        participant_action.extend_from_slice(&[
+            self.timeout.clone(),
+            self.release_behaviour.clone(),
+            self.disabled_layers.clone(),
+        ]);
+        participant_action
+    }
+}
diff --git a/parser/src/cfg/chord_v1.rs b/parser/src/cfg/chord_v1.rs
new file mode 100644
index 000000000..534dca843
--- /dev/null
+++ b/parser/src/cfg/chord_v1.rs
@@ -0,0 +1,352 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::anyhow_span;
+use crate::bail;
+use crate::bail_expr;
+use crate::bail_span;
+use crate::err_expr;
+
+#[derive(Debug, Clone)]
+pub(crate) struct ChordGroup {
+    id: u16,
+    name: String,
+    keys: Vec<String>,
+    coords: Vec<((u8, u16), ChordKeys)>,
+    chords: HashMap<u128, SExpr>,
+    timeout: u16,
+}
+
+pub(crate) fn parse_chord(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "Action chord expects a chords group name followed by an identifier";
+    if ac_params.len() != 2 {
+        bail!(ERR_MSG);
+    }
+
+    let name = ac_params[0]
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_MSG}"))?;
+    let group = match s.chord_groups.get(name) {
+        Some(t) => t,
+        None => bail_expr!(&ac_params[0], "Referenced unknown chord group: {}.", name),
+    };
+    let chord_key_index = ac_params[1]
+        .atom(s.vars())
+        .map(|s| match group.keys.iter().position(|e| e == s) {
+            Some(i) => Ok(i),
+            None => err_expr!(
+                &ac_params[1],
+                r#"Identifier "{}" is not used in chord group "{}"."#,
+                &s,
+                name,
+            ),
+        })
+        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_MSG}"))??;
+    let chord_keys: u128 = 1 << chord_key_index;
+
+    // We don't yet know at this point what the entire chords group will look like nor at which
+    // coords this action will end up. So instead we store a dummy action which will be properly
+    // resolved in `resolve_chord_groups`.
+    Ok(s.a.sref(Action::Chords(s.a.sref(ChordsGroup {
+        timeout: group.timeout,
+        coords: s.a.sref_vec(vec![((0, group.id), chord_keys)]),
+        chords: s.a.sref_vec(vec![]),
+    }))))
+}
+
+pub(crate) fn parse_chord_groups(
+    exprs: &[&Spanned<Vec<SExpr>>],
+    s: &mut ParserState,
+) -> Result<()> {
+    const MSG: &str = "Incorrect number of elements found in defchords.\nThere should be the group name, followed by timeout, followed by keys-action pairs";
+    for expr in exprs {
+        let mut subexprs = check_first_expr(expr.t.iter(), "defchords")?;
+        let name = subexprs
+            .next()
+            .and_then(|e| e.atom(s.vars()))
+            .ok_or_else(|| anyhow_span!(expr, "{MSG}"))?
+            .to_owned();
+        let timeout = match subexprs.next() {
+            Some(e) => parse_non_zero_u16(e, s, "timeout")?,
+            None => bail_span!(expr, "{MSG}"),
+        };
+        let id = match s.chord_groups.len().try_into() {
+            Ok(id) => id,
+            Err(_) => bail_span!(expr, "Maximum number of chord groups exceeded."),
+        };
+        let mut group = ChordGroup {
+            id,
+            name: name.clone(),
+            keys: Vec::new(),
+            coords: Vec::new(),
+            chords: HashMap::default(),
+            timeout,
+        };
+        // Read k-v pairs from the configuration
+        while let Some(keys_expr) = subexprs.next() {
+            let action = match subexprs.next() {
+                Some(v) => v,
+                None => bail_expr!(
+                    keys_expr,
+                    "Key list found without action - add an action for this chord"
+                ),
+            };
+            let mut keys = keys_expr
+                .list(s.vars())
+                .map(|keys| {
+                    keys.iter().map(|key| {
+                        key.atom(s.vars()).ok_or_else(|| {
+                            anyhow_expr!(
+                                key,
+                                "Chord keys cannot be lists. Invalid key name: {:?}",
+                                key
+                            )
+                        })
+                    })
+                })
+                .ok_or_else(|| anyhow_expr!(keys_expr, "Chord must be a list/set of keys"))?;
+            let mask: u128 = keys.try_fold(0, |mask, key| {
+                let key = key?;
+                let index = match group.keys.iter().position(|k| k == key) {
+                    Some(i) => i,
+                    None => {
+                        let i = group.keys.len();
+                        if i + 1 > MAX_CHORD_KEYS {
+                            bail_expr!(keys_expr, "Maximum number of keys in a chords group ({MAX_CHORD_KEYS}) exceeded - found {}", i + 1);
+                        }
+                        group.keys.push(key.to_owned());
+                        i
+                    }
+                };
+                Ok(mask | (1 << index))
+            })?;
+            if group.chords.insert(mask, action.clone()).is_some() {
+                bail_expr!(keys_expr, "Duplicate chord in group {name}");
+            }
+        }
+        if s.chord_groups.insert(name.to_owned(), group).is_some() {
+            bail_span!(expr, "Duplicate chords group: {}", name);
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn resolve_chord_groups(layers: &mut IntermediateLayers, s: &ParserState) -> Result<()> {
+    let mut chord_groups = s.chord_groups.values().cloned().collect::<Vec<_>>();
+    chord_groups.sort_by_key(|group| group.id);
+
+    for layer in layers.iter() {
+        for (i, row) in layer.iter().enumerate() {
+            for (j, cell) in row.iter().enumerate() {
+                find_chords_coords(&mut chord_groups, (i as u8, j as u16), cell);
+            }
+        }
+    }
+
+    let chord_groups = chord_groups.into_iter().map(|group| {
+        // Check that all keys in the chord group have been assigned to some coordinate
+        for (key_index, key) in group.keys.iter().enumerate() {
+            let key_mask = 1 << key_index;
+            if !group.coords.iter().any(|(_, keys)| keys & key_mask != 0) {
+                bail!("coord group `{0}` defines unused key `{1}`, did you forget to bind `(chord {0} {1})`?", group.name, key)
+            }
+        }
+
+        let chords = group.chords.iter().map(|(mask, action)| {
+            Ok((*mask, parse_action(action, s)?))
+        }).collect::<Result<Vec<_>>>()?;
+
+        Ok(s.a.sref(ChordsGroup {
+            coords: s.a.sref_vec(group.coords),
+            chords: s.a.sref_vec(chords),
+            timeout: group.timeout,
+        }))
+    }).collect::<Result<Vec<_>>>()?;
+
+    for layer in layers.iter_mut() {
+        for row in layer.iter_mut() {
+            for cell in row.iter_mut() {
+                if let Some(action) = fill_chords(&chord_groups, cell, s) {
+                    *cell = action;
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+pub(crate) fn find_chords_coords(
+    chord_groups: &mut [ChordGroup],
+    coord: (u8, u16),
+    action: &KanataAction,
+) {
+    match action {
+        Action::Chords(ChordsGroup { coords, .. }) => {
+            for ((_, group_id), chord_keys) in coords.iter() {
+                let group = &mut chord_groups[*group_id as usize];
+                group.coords.push((coord, *chord_keys));
+            }
+        }
+        Action::NoOp
+        | Action::Trans
+        | Action::Src
+        | Action::Repeat
+        | Action::KeyCode(_)
+        | Action::MultipleKeyCodes(_)
+        | Action::Layer(_)
+        | Action::DefaultLayer(_)
+        | Action::Sequence { .. }
+        | Action::RepeatableSequence { .. }
+        | Action::CancelSequences
+        | Action::ReleaseState(_)
+        | Action::OneShotIgnoreEventsTicks(_)
+        | Action::Custom(_) => {}
+        Action::HoldTap(HoldTapAction { tap, hold, .. }) => {
+            find_chords_coords(chord_groups, coord, tap);
+            find_chords_coords(chord_groups, coord, hold);
+        }
+        Action::OneShot(OneShot { action: ac, .. }) => {
+            find_chords_coords(chord_groups, coord, ac);
+        }
+        Action::MultipleActions(actions) => {
+            for ac in actions.iter() {
+                find_chords_coords(chord_groups, coord, ac);
+            }
+        }
+        Action::TapDance(TapDance { actions, .. }) => {
+            for ac in actions.iter() {
+                find_chords_coords(chord_groups, coord, ac);
+            }
+        }
+        Action::Fork(ForkConfig { left, right, .. }) => {
+            find_chords_coords(chord_groups, coord, left);
+            find_chords_coords(chord_groups, coord, right);
+        }
+        Action::Switch(Switch { cases, .. }) => {
+            for case in cases.iter() {
+                find_chords_coords(chord_groups, coord, case.1);
+            }
+        }
+    }
+}
+
+pub(crate) fn fill_chords(
+    chord_groups: &[&'static ChordsGroup<KanataCustom>],
+    action: &KanataAction,
+    s: &ParserState,
+) -> Option<KanataAction> {
+    match action {
+        Action::Chords(ChordsGroup { coords, .. }) => {
+            let ((_, group_id), _) = coords
+                .iter()
+                .next()
+                .expect("unresolved chords should have exactly one entry");
+            Some(Action::Chords(chord_groups[*group_id as usize]))
+        }
+        Action::NoOp
+        | Action::Trans
+        | Action::Repeat
+        | Action::Src
+        | Action::KeyCode(_)
+        | Action::MultipleKeyCodes(_)
+        | Action::Layer(_)
+        | Action::DefaultLayer(_)
+        | Action::Sequence { .. }
+        | Action::RepeatableSequence { .. }
+        | Action::CancelSequences
+        | Action::ReleaseState(_)
+        | Action::OneShotIgnoreEventsTicks(_)
+        | Action::Custom(_) => None,
+        Action::HoldTap(&hta @ HoldTapAction { tap, hold, .. }) => {
+            let new_tap = fill_chords(chord_groups, &tap, s);
+            let new_hold = fill_chords(chord_groups, &hold, s);
+            if new_tap.is_some() || new_hold.is_some() {
+                Some(Action::HoldTap(s.a.sref(HoldTapAction {
+                    hold: new_hold.unwrap_or(hold),
+                    tap: new_tap.unwrap_or(tap),
+                    ..hta
+                })))
+            } else {
+                None
+            }
+        }
+        Action::OneShot(&os @ OneShot { action: ac, .. }) => {
+            fill_chords(chord_groups, ac, s).map(|ac| {
+                Action::OneShot(s.a.sref(OneShot {
+                    action: s.a.sref(ac),
+                    ..os
+                }))
+            })
+        }
+        Action::MultipleActions(actions) => {
+            let new_actions = actions
+                .iter()
+                .map(|ac| fill_chords(chord_groups, ac, s))
+                .collect::<Vec<_>>();
+            if new_actions.iter().any(|it| it.is_some()) {
+                let new_actions = new_actions
+                    .iter()
+                    .zip(**actions)
+                    .map(|(new_ac, ac)| new_ac.unwrap_or(*ac))
+                    .collect::<Vec<_>>();
+                Some(Action::MultipleActions(s.a.sref(s.a.sref_vec(new_actions))))
+            } else {
+                None
+            }
+        }
+        Action::TapDance(&td @ TapDance { actions, .. }) => {
+            let new_actions = actions
+                .iter()
+                .map(|ac| fill_chords(chord_groups, ac, s))
+                .collect::<Vec<_>>();
+            if new_actions.iter().any(|it| it.is_some()) {
+                let new_actions = new_actions
+                    .iter()
+                    .zip(actions)
+                    .map(|(new_ac, ac)| new_ac.map(|v| s.a.sref(v)).unwrap_or(*ac))
+                    .collect::<Vec<_>>();
+                Some(Action::TapDance(s.a.sref(TapDance {
+                    actions: s.a.sref_vec(new_actions),
+                    ..td
+                })))
+            } else {
+                None
+            }
+        }
+        Action::Fork(&fcfg @ ForkConfig { left, right, .. }) => {
+            let new_left = fill_chords(chord_groups, &left, s);
+            let new_right = fill_chords(chord_groups, &right, s);
+            if new_left.is_some() || new_right.is_some() {
+                Some(Action::Fork(s.a.sref(ForkConfig {
+                    left: new_left.unwrap_or(left),
+                    right: new_right.unwrap_or(right),
+                    ..fcfg
+                })))
+            } else {
+                None
+            }
+        }
+        Action::Switch(Switch {
+            cases,
+            init_fn,
+            callbacks,
+        }) => {
+            let mut new_cases = vec![];
+            for case in cases.iter() {
+                new_cases.push((
+                    case.0,
+                    fill_chords(chord_groups, case.1, s)
+                        .map(|ac| s.a.sref(ac))
+                        .unwrap_or(case.1),
+                    case.2,
+                ));
+            }
+            Some(Action::Switch(s.a.sref(Switch {
+                cases: s.a.sref_vec(new_cases),
+                init_fn: *init_fn,
+                callbacks,
+            })))
+        }
+    }
+}
diff --git a/parser/src/cfg/clipboard.rs b/parser/src/cfg/clipboard.rs
new file mode 100644
index 000000000..1e06b6d66
--- /dev/null
+++ b/parser/src/cfg/clipboard.rs
@@ -0,0 +1,83 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+pub(crate) fn parse_clipboard_set(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 1 parameter: <clipboard string>";
+    if ac_params.len() != 1 {
+        bail!("{CLIPBOARD_SET} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let expr = &ac_params[0];
+    let clip_string = match expr {
+        SExpr::Atom(filepath) => filepath,
+        SExpr::List(_) => {
+            bail_expr!(&expr, "Clipboard string cannot be a list")
+        }
+    };
+    let clip_string = clip_string.t.trim_atom_quotes();
+    custom(
+        CustomAction::ClipboardSet(s.a.sref_str(clip_string.to_string())),
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_clipboard_save(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 1 parameter: <clipboard save id (0-65535)>";
+    if ac_params.len() != 1 {
+        bail!("{CLIPBOARD_SAVE} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let id = parse_u16(&ac_params[0], s, "clipboard save ID")?;
+    custom(CustomAction::ClipboardSave(id), &s.a)
+}
+
+pub(crate) fn parse_clipboard_restore(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 1 parameter: <clipboard save id (0-65535)>";
+    if ac_params.len() != 1 {
+        bail!("{CLIPBOARD_RESTORE} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let id = parse_u16(&ac_params[0], s, "clipboard save ID")?;
+    custom(CustomAction::ClipboardRestore(id), &s.a)
+}
+
+pub(crate) fn parse_clipboard_save_swap(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str =
+        "expects 2 parameters: <clipboard save id (0-65535)> <clipboard save id #2>";
+    if ac_params.len() != 2 {
+        bail!("{CLIPBOARD_SAVE_SWAP} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let id1 = parse_u16(&ac_params[0], s, "clipboard save ID")?;
+    let id2 = parse_u16(&ac_params[1], s, "clipboard save ID")?;
+    custom(CustomAction::ClipboardSaveSwap(id1, id2), &s.a)
+}
+
+pub(crate) fn parse_clipboard_save_set(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 2 parameters: <clipboard save id (0-65535)> <save content>";
+    if ac_params.len() != 2 {
+        bail!("{CLIPBOARD_SAVE_SET} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let id = parse_u16(&ac_params[0], s, "clipboard save ID")?;
+    let save_content = ac_params[1]
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(&ac_params[1], "save content must be a string"))?;
+    custom(
+        CustomAction::ClipboardSaveSet(id, s.a.sref_str(save_content.into())),
+        &s.a,
+    )
+}
diff --git a/parser/src/cfg/cmd.rs b/parser/src/cfg/cmd.rs
new file mode 100644
index 000000000..b9d40574b
--- /dev/null
+++ b/parser/src/cfg/cmd.rs
@@ -0,0 +1,140 @@
+use super::*;
+
+use crate::bail;
+use crate::bail_expr;
+
+pub(crate) enum CmdType {
+    /// Execute command in own thread.
+    Standard,
+    /// Execute command synchronously and output stdout as macro-like SExpr.
+    OutputKeys,
+    /// Execute command and set clipboard to output. Clipboard content is passed as stdin to the
+    /// command.
+    ClipboardSet,
+    /// Execute command and set clipboard save id to output.
+    /// Clipboard save id content is passed as stdin to the command.
+    ClipboardSaveSet,
+}
+
+// Parse cmd, but there are 2 arguments before specifying normal log and error log
+pub(crate) fn parse_cmd_log(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_STR: &str =
+        "cmd-log expects at least 3 strings, <log-level> <error-log-level> <cmd...>";
+    if !s.is_cmd_enabled {
+        bail!(
+            "cmd is not enabled for this kanata executable (did you use 'cmd_allowed' variants?), but is set in the configuration"
+        );
+    }
+    if ac_params.len() < 3 {
+        bail!(ERR_STR);
+    }
+    let mut cmd = vec![];
+    let log_level =
+        if let Some(Ok(input_mode)) = ac_params[0].atom(s.vars()).map(LogLevel::try_from_str) {
+            input_mode
+        } else {
+            bail_expr!(&ac_params[0], "{ERR_STR}\n{}", LogLevel::err_msg());
+        };
+    let error_log_level =
+        if let Some(Ok(input_mode)) = ac_params[1].atom(s.vars()).map(LogLevel::try_from_str) {
+            input_mode
+        } else {
+            bail_expr!(&ac_params[1], "{ERR_STR}\n{}", LogLevel::err_msg());
+        };
+    collect_strings(&ac_params[2..], &mut cmd, s);
+    if cmd.is_empty() {
+        bail!(ERR_STR);
+    }
+    let cmds = cmd.into_iter().map(|v| s.a.sref_str(v)).collect();
+    custom(
+        CustomAction::CmdLog(log_level, error_log_level, s.a.sref_vec(cmds)),
+        &s.a,
+    )
+}
+
+#[allow(unused_variables)]
+pub(crate) fn parse_cmd(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    cmd_type: CmdType,
+) -> Result<&'static KanataAction> {
+    #[cfg(not(feature = "cmd"))]
+    {
+        bail!(
+            "cmd is not enabled for this kanata executable. Use a cmd_allowed prebuilt executable or compile with the feature: cmd."
+        );
+    }
+    #[cfg(feature = "cmd")]
+    {
+        if matches!(cmd_type, CmdType::ClipboardSaveSet) {
+            const ERR_STR: &str = "expects a save ID and at least one string";
+            if !s.is_cmd_enabled {
+                bail!("To use cmd you must put in defcfg: danger-enable-cmd yes.");
+            }
+            if ac_params.len() < 2 {
+                bail!("{CLIPBOARD_SAVE_CMD_SET} {ERR_STR}");
+            }
+            let mut cmd = vec![];
+            let save_id = parse_u16(&ac_params[0], s, "clipboard save ID")?;
+            collect_strings(&ac_params[1..], &mut cmd, s);
+            if cmd.is_empty() {
+                bail_expr!(&ac_params[1], "{CLIPBOARD_SAVE_CMD_SET} {ERR_STR}");
+            }
+            let cmds = cmd.into_iter().map(|v| s.a.sref_str(v)).collect();
+            return custom(
+                CustomAction::ClipboardSaveCmdSet(save_id, s.a.sref_vec(cmds)),
+                &s.a,
+            );
+        }
+
+        const ERR_STR: &str = "cmd expects at least one string";
+        if !s.is_cmd_enabled {
+            bail!("To use cmd you must put in defcfg: danger-enable-cmd yes.");
+        }
+        let mut cmd = vec![];
+        collect_strings(ac_params, &mut cmd, s);
+        if cmd.is_empty() {
+            bail!(ERR_STR);
+        }
+        let cmds = cmd.into_iter().map(|v| s.a.sref_str(v)).collect();
+        let cmds = s.a.sref_vec(cmds);
+        custom(
+            match cmd_type {
+                CmdType::Standard => CustomAction::Cmd(cmds),
+                CmdType::OutputKeys => CustomAction::CmdOutputKeys(cmds),
+                CmdType::ClipboardSet => CustomAction::ClipboardCmdSet(cmds),
+                CmdType::ClipboardSaveSet => unreachable!(),
+            },
+            &s.a,
+        )
+    }
+}
+
+/// Recurse through all levels of list nesting and collect into a flat list of strings.
+/// Recursion is DFS, which matches left-to-right reading of the strings as they appear,
+/// if everything was on a single line.
+pub(crate) fn collect_strings(params: &[SExpr], strings: &mut Vec<String>, s: &ParserState) {
+    for param in params {
+        if let Some(a) = param.atom(s.vars()) {
+            strings.push(a.trim_atom_quotes().to_owned());
+        } else {
+            // unwrap: this must be a list, since it's not an atom.
+            let l = param.list(s.vars()).unwrap();
+            collect_strings(l, strings, s);
+        }
+    }
+}
+
+#[test]
+pub(crate) fn test_collect_strings() {
+    let params = r#"(gah (squish "squash" (splish splosh) "bah mah") dah)"#;
+    let params = sexpr::parse(params, "noexist").unwrap();
+    let mut strings = vec![];
+    collect_strings(&params[0].t, &mut strings, &ParserState::default());
+    assert_eq!(
+        &strings,
+        &[
+            "gah", "squish", "squash", "splish", "splosh", "bah mah", "dah"
+        ]
+    );
+}
diff --git a/parser/src/cfg/custom_tap_hold.rs b/parser/src/cfg/custom_tap_hold.rs
index c46603523..b7fd6de31 100644
--- a/parser/src/cfg/custom_tap_hold.rs
+++ b/parser/src/cfg/custom_tap_hold.rs
@@ -1,32 +1,380 @@
-use kanata_keyberon::layout::{Event, QueuedIter, WaitingAction};
+use kanata_keyberon::layout::{Event, KCoord, QueuedIter, REAL_KEY_ROW, WaitingAction};
 
 use crate::keys::OsCode;
 
 use super::alloc::Allocations;
 
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub(crate) enum Hand {
+    Left,
+    Right,
+    Neutral,
+}
+
+/// Compact mapping from key codes to hand assignments.
+/// Stores only keys that have an explicit left/right assignment;
+/// any key not present is treated as `Hand::Neutral`.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct HandMap {
+    pub(crate) keys: &'static [u16],
+    pub(crate) hands: &'static [Hand],
+}
+
+impl HandMap {
+    pub(crate) fn get(&self, key_code: u16) -> Hand {
+        self.keys
+            .iter()
+            .position(|&k| k == key_code)
+            .map(|i| self.hands[i])
+            .unwrap_or(Hand::Neutral)
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+pub(crate) enum DecisionBehavior {
+    Tap,
+    Hold,
+    Ignore,
+}
+
+/// The function-trait object stored inside `HoldTapConfig::Custom`.
+pub(crate) type CustomTapHoldFn =
+    dyn Fn(QueuedIter, KCoord) -> (Option<WaitingAction>, bool) + Send + Sync;
+
 /// Returns a closure that can be used in `HoldTapConfig::Custom`, which will return early with a
 /// Tap action in the case that any of `keys` are pressed. Otherwise it behaves as
 /// `HoldTapConfig::PermissiveHold` would.
 pub(crate) fn custom_tap_hold_release(
     keys: &[OsCode],
     a: &Allocations,
-) -> &'static (dyn Fn(QueuedIter) -> Option<WaitingAction> + Send + Sync) {
+) -> &'static CustomTapHoldFn {
     let keys = a.sref_vec(Vec::from_iter(keys.iter().copied()));
-    a.sref(move |mut queued: QueuedIter| -> Option<WaitingAction> {
-        while let Some(q) = queued.next() {
-            if q.event().is_press() {
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            while let Some(q) = queued.next() {
+                if q.event().is_press() {
+                    let (i, j) = q.event().coord();
+                    // If any key matches the input, do a tap right away.
+                    if i == REAL_KEY_ROW && keys.iter().copied().map(u16::from).any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // Otherwise do the PermissiveHold algorithm.
+                    let target = Event::Release(i, j);
+                    if queued.clone().copied().any(|q| q.event() == target) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                }
+            }
+            (None, false)
+        },
+    )
+}
+
+/// Returns a closure that can be used in `HoldTapConfig::Custom`, which will return early with a
+/// Tap action in the case that any of `keys_press_then_release_trigger_tap` are pressed and
+/// released, or if any in `keys_press_trigger_tap` are pressed (no release needed). Otherwise it
+/// behaves as `HoldTapConfig::PermissiveHold` would.
+pub(crate) fn custom_tap_hold_release_trigger_tap_release(
+    keys_press_trigger_tap: &[OsCode],
+    keys_press_then_release_trigger_tap: &[OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    let keys_press_then_release_trigger_tap = a.sref_vec(Vec::from_iter(
+        keys_press_then_release_trigger_tap
+            .iter()
+            .copied()
+            .map(u16::from),
+    ));
+    let keys_press_trigger_tap = a.sref_vec(Vec::from_iter(
+        keys_press_trigger_tap.iter().copied().map(u16::from),
+    ));
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            while let Some(q) = queued.next() {
+                if q.event().is_press() {
+                    let (i, j) = q.event().coord();
+                    if i != REAL_KEY_ROW {
+                        continue;
+                    }
+                    // If any pressed key matches the press list and has been released, do
+                    // a tap right away.
+                    if keys_press_trigger_tap.iter().copied().any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // If any pressed key matches the press-release list and has been released, do
+                    // a tap right away.
+                    if keys_press_then_release_trigger_tap
+                        .iter()
+                        .copied()
+                        .any(|j2| j2 == j)
+                    {
+                        let target = Event::Release(i, j);
+                        if queued.clone().copied().any(|q| q.event() == target) {
+                            return (Some(WaitingAction::Tap), false);
+                        }
+                    }
+                    // Otherwise do the PermissiveHold algorithm.
+                    let target = Event::Release(i, j);
+                    if queued.clone().copied().any(|q| q.event() == target) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                }
+            }
+            (None, false)
+        },
+    )
+}
+
+/// Returns a closure for `tap-hold-keys` with three optional key lists:
+/// - `keys_tap_on_press`: trigger tap immediately on press
+/// - `keys_tap_on_press_release`: trigger tap when pressed then released
+/// - `keys_hold_on_press`: trigger hold immediately on press
+///
+/// For any other key, falls back to PermissiveHold behavior.
+///
+/// Priority when a key appears in multiple lists (checked in order):
+/// tap-on-press > hold-on-press > tap-on-press-release > PermissiveHold
+pub(crate) fn custom_tap_hold_keys(
+    keys_tap_on_press: &[OsCode],
+    keys_tap_on_press_release: &[OsCode],
+    keys_hold_on_press: &[OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    let keys_tap_on_press = a.sref_vec(keys_tap_on_press.iter().copied().map(u16::from).collect());
+    let keys_tap_on_press_release = a.sref_vec(
+        keys_tap_on_press_release
+            .iter()
+            .copied()
+            .map(u16::from)
+            .collect(),
+    );
+    let keys_hold_on_press =
+        a.sref_vec(keys_hold_on_press.iter().copied().map(u16::from).collect());
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            while let Some(q) = queued.next() {
+                if q.event().is_press() {
+                    let (i, j) = q.event().coord();
+                    if i != REAL_KEY_ROW {
+                        continue;
+                    }
+                    // If key is in tap-on-press list, trigger tap immediately.
+                    if keys_tap_on_press.iter().copied().any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // If key is in hold-on-press list, trigger hold immediately.
+                    if keys_hold_on_press.iter().copied().any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                    // If key is in tap-on-press-release list and has been released,
+                    // trigger tap.
+                    if keys_tap_on_press_release.iter().copied().any(|j2| j2 == j) {
+                        let target = Event::Release(i, j);
+                        if queued.clone().copied().any(|q| q.event() == target) {
+                            return (Some(WaitingAction::Tap), false);
+                        }
+                    }
+                    // Otherwise do the PermissiveHold algorithm:
+                    // if another key was pressed and released, trigger hold.
+                    let target = Event::Release(i, j);
+                    if queued.clone().copied().any(|q| q.event() == target) {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                }
+            }
+            (None, false)
+        },
+    )
+}
+
+pub(crate) fn custom_tap_hold_except(keys: &[OsCode], a: &Allocations) -> &'static CustomTapHoldFn {
+    let keys = a.sref_vec(Vec::from_iter(keys.iter().copied()));
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            for q in queued.by_ref() {
+                if q.event().is_press() {
+                    let (_i, j) = q.event().coord();
+                    // If any key matches the input, do a tap.
+                    if keys.iter().copied().map(u16::from).any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // Otherwise continue with default behavior
+                    return (None, false);
+                }
+            }
+            // Otherwise skip timeout
+            (None, true)
+        },
+    )
+}
+
+/// Returns a closure that can be used in `HoldTapConfig::Custom`, which will return early with a
+/// Tap action in the case that any of `keys` are pressed. Unlike `custom_tap_hold_except`, if no
+/// matching key is pressed, this waits for timeout instead of skipping it.
+pub(crate) fn custom_tap_hold_tap_keys(
+    keys: &[OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    let keys = a.sref_vec(Vec::from_iter(keys.iter().copied()));
+    a.sref(
+        move |mut queued: QueuedIter, _coord: KCoord| -> (Option<WaitingAction>, bool) {
+            for q in queued.by_ref() {
+                if q.event().is_press() {
+                    let (_i, j) = q.event().coord();
+                    // If any key matches the input, do a tap.
+                    if keys.iter().copied().map(u16::from).any(|j2| j2 == j) {
+                        return (Some(WaitingAction::Tap), false);
+                    }
+                    // Otherwise continue with default behavior (no early hold activation)
+                }
+            }
+            // Wait for timeout (key difference from custom_tap_hold_except which returns true)
+            (None, false)
+        },
+    )
+}
+
+pub(crate) fn custom_tap_hold_opposite_hand(
+    hand_map: &'static HandMap,
+    same_hand: DecisionBehavior,
+    neutral_behavior: DecisionBehavior,
+    unknown_hand: DecisionBehavior,
+    neutral_keys: &'static [OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    a.sref(
+        move |queued: QueuedIter, coord: KCoord| -> (Option<WaitingAction>, bool) {
+            let (_row, col) = coord;
+            let waiting_hand = hand_map.get(col);
+
+            for q in queued {
+                if !q.event().is_press() {
+                    continue;
+                }
+                let (i, j) = q.event().coord();
+                if i != REAL_KEY_ROW {
+                    continue;
+                }
+
+                // Check neutral-keys first (takes precedence over defhands)
+                if let Some(osc) = OsCode::from_u16(j) {
+                    if neutral_keys.contains(&osc) {
+                        match neutral_behavior {
+                            DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                            DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                            DecisionBehavior::Ignore => continue,
+                        }
+                    }
+                }
+
+                let pressed_hand = hand_map.get(j);
+
+                match (waiting_hand, pressed_hand) {
+                    (Hand::Left, Hand::Right) | (Hand::Right, Hand::Left) => {
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                    (Hand::Left, Hand::Left) | (Hand::Right, Hand::Right) => match same_hand {
+                        DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                        DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                        DecisionBehavior::Ignore => continue,
+                    },
+                    _ => {
+                        // At least one key is Neutral (not in defhands)
+                        match unknown_hand {
+                            DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                            DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                            DecisionBehavior::Ignore => continue,
+                        }
+                    }
+                }
+            }
+            (None, false)
+        },
+    )
+}
+
+/// Like `custom_tap_hold_opposite_hand` but waits for the interrupting key's
+/// press+release before committing to Hold. This avoids misfires on fast
+/// cross-hand overlaps where keystrokes briefly overlap.
+///
+/// The `-release` requirement only applies to opposite-hand and unknown-hand
+/// keys. Same-hand keys resolve immediately on press (no release needed),
+/// because requiring release would cause same-hand keys to be skipped when
+/// still held, allowing a later opposite-hand key+release to incorrectly
+/// trigger Hold.
+pub(crate) fn custom_tap_hold_opposite_hand_release(
+    hand_map: &'static HandMap,
+    same_hand: DecisionBehavior,
+    neutral_behavior: DecisionBehavior,
+    unknown_hand: DecisionBehavior,
+    neutral_keys: &'static [OsCode],
+    a: &Allocations,
+) -> &'static CustomTapHoldFn {
+    a.sref(
+        move |mut queued: QueuedIter, coord: KCoord| -> (Option<WaitingAction>, bool) {
+            let (_row, col) = coord;
+            let waiting_hand = hand_map.get(col);
+
+            while let Some(q) = queued.next() {
+                if !q.event().is_press() {
+                    continue;
+                }
                 let (i, j) = q.event().coord();
-                // If any key matches the input, do a tap right away.
-                if keys.iter().copied().map(u16::from).any(|j2| j2 == j) {
-                    return Some(WaitingAction::Tap);
+                if i != REAL_KEY_ROW {
+                    continue;
                 }
-                // Otherwise do the PermissiveHold algorithm.
-                let target = Event::Release(i, j);
-                if queued.clone().copied().any(|q| q.event() == target) {
-                    return Some(WaitingAction::Hold);
+
+                // Check neutral-keys first (takes precedence over defhands)
+                if let Some(osc) = OsCode::from_u16(j) {
+                    if neutral_keys.contains(&osc) {
+                        // Neutral keys require release before deciding
+                        let release = Event::Release(i, j);
+                        if !queued.clone().copied().any(|q| q.event() == release) {
+                            continue;
+                        }
+                        match neutral_behavior {
+                            DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                            DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                            DecisionBehavior::Ignore => continue,
+                        }
+                    }
+                }
+
+                let pressed_hand = hand_map.get(j);
+
+                match (waiting_hand, pressed_hand) {
+                    // Same hand: resolve immediately on press (no release needed).
+                    // This prevents same-hand keys from being skipped while held,
+                    // which would let a later opposite-hand release trigger Hold.
+                    (Hand::Left, Hand::Left) | (Hand::Right, Hand::Right) => match same_hand {
+                        DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                        DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                        DecisionBehavior::Ignore => continue,
+                    },
+                    // Opposite hand: require release before committing to Hold
+                    (Hand::Left, Hand::Right) | (Hand::Right, Hand::Left) => {
+                        let release = Event::Release(i, j);
+                        if !queued.clone().copied().any(|q| q.event() == release) {
+                            continue;
+                        }
+                        return (Some(WaitingAction::Hold), false);
+                    }
+                    _ => {
+                        // At least one key is Neutral (not in defhands):
+                        // require release before deciding
+                        let release = Event::Release(i, j);
+                        if !queued.clone().copied().any(|q| q.event() == release) {
+                            continue;
+                        }
+                        match unknown_hand {
+                            DecisionBehavior::Tap => return (Some(WaitingAction::Tap), false),
+                            DecisionBehavior::Hold => return (Some(WaitingAction::Hold), false),
+                            DecisionBehavior::Ignore => continue,
+                        }
+                    }
                 }
             }
-        }
-        None
-    })
+            (None, false)
+        },
+    )
 }
diff --git a/parser/src/cfg/defcfg.rs b/parser/src/cfg/defcfg.rs
new file mode 100644
index 000000000..2b5e70035
--- /dev/null
+++ b/parser/src/cfg/defcfg.rs
@@ -0,0 +1,1158 @@
+use super::HashSet;
+use super::sexpr::SExpr;
+use super::{TrimAtomQuotes, error::*};
+use crate::cfg::check_first_expr;
+use crate::custom_action::*;
+use crate::keys::*;
+#[allow(unused)]
+use crate::{anyhow_expr, anyhow_span, bail, bail_expr, bail_span};
+
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum DeviceDetectMode {
+    KeyboardOnly,
+    KeyboardMice,
+    Any,
+}
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+impl std::fmt::Display for DeviceDetectMode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+#[derive(Debug, Clone)]
+pub struct CfgLinuxOptions {
+    pub linux_dev: Vec<String>,
+    pub linux_dev_names_include: Option<Vec<String>>,
+    pub linux_dev_names_exclude: Option<Vec<String>>,
+    pub linux_continue_if_no_devs_found: bool,
+    pub linux_unicode_u_code: crate::keys::OsCode,
+    pub linux_unicode_termination: UnicodeTermination,
+    pub linux_x11_repeat_delay_rate: Option<KeyRepeatSettings>,
+    pub linux_use_trackpoint_property: bool,
+    pub linux_output_name: String,
+    pub linux_output_bus_type: LinuxCfgOutputBusType,
+    pub linux_device_detect_mode: Option<DeviceDetectMode>,
+}
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+impl Default for CfgLinuxOptions {
+    fn default() -> Self {
+        Self {
+            linux_dev: vec![],
+            linux_dev_names_include: None,
+            linux_dev_names_exclude: None,
+            linux_continue_if_no_devs_found: false,
+            // historically was the only option, so make KEY_U the default
+            linux_unicode_u_code: crate::keys::OsCode::KEY_U,
+            // historically was the only option, so make Enter the default
+            linux_unicode_termination: UnicodeTermination::Enter,
+            linux_x11_repeat_delay_rate: None,
+            linux_use_trackpoint_property: false,
+            linux_output_name: "kanata".to_owned(),
+            linux_output_bus_type: LinuxCfgOutputBusType::BusI8042,
+            linux_device_detect_mode: None,
+        }
+    }
+}
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+#[derive(Debug, Clone, Copy)]
+pub enum LinuxCfgOutputBusType {
+    BusUsb,
+    BusI8042,
+    BusVirtual,
+}
+
+#[cfg(any(target_os = "macos", target_os = "unknown"))]
+#[derive(Debug, Default, Clone)]
+pub struct CfgMacosOptions {
+    pub macos_dev_names_include: Option<Vec<String>>,
+    pub macos_dev_names_exclude: Option<Vec<String>>,
+    pub macos_continue_if_no_devs_found: bool,
+}
+
+#[cfg(any(
+    all(feature = "interception_driver", target_os = "windows"),
+    target_os = "unknown"
+))]
+#[derive(Debug, Clone, Default)]
+pub struct CfgWinterceptOptions {
+    pub windows_interception_mouse_hwids: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    pub windows_interception_mouse_hwids_exclude: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    pub windows_interception_keyboard_hwids: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    pub windows_interception_keyboard_hwids_exclude: Option<Vec<[u8; HWID_ARR_SZ]>>,
+}
+
+#[cfg(any(target_os = "windows", target_os = "unknown"))]
+#[derive(Debug, Clone, Default)]
+pub struct CfgWindowsOptions {
+    pub windows_altgr: AltGrBehaviour,
+    pub sync_keystates: bool,
+}
+
+#[cfg(all(any(target_os = "windows", target_os = "unknown"), feature = "gui"))]
+#[derive(Debug, Clone)]
+pub struct CfgOptionsGui {
+    /// File name / path to the tray icon file.
+    pub tray_icon: Option<String>,
+    /// Whether to match layer names to icon files without an explicit 'icon' field
+    pub icon_match_layer_name: bool,
+    /// Show tooltip on layer changes showing layer icons
+    pub tooltip_layer_changes: bool,
+    /// Show tooltip on layer changes for the default/base layer
+    pub tooltip_no_base: bool,
+    /// Show tooltip on layer changes even for layers without an icon
+    pub tooltip_show_blank: bool,
+    /// Show tooltip on layer changes for this duration (ms)
+    pub tooltip_duration: u16,
+    /// Show system notification message on config reload
+    pub notify_cfg_reload: bool,
+    /// Disable sound for the system notification message on config reload
+    pub notify_cfg_reload_silent: bool,
+    /// Show system notification message on errors
+    pub notify_error: bool,
+    /// Set tooltip size (width, height)
+    pub tooltip_size: (u16, u16),
+}
+#[cfg(all(any(target_os = "windows", target_os = "unknown"), feature = "gui"))]
+impl Default for CfgOptionsGui {
+    fn default() -> Self {
+        Self {
+            tray_icon: None,
+            icon_match_layer_name: true,
+            tooltip_layer_changes: false,
+            tooltip_show_blank: false,
+            tooltip_no_base: true,
+            tooltip_duration: 500,
+            notify_cfg_reload: true,
+            notify_cfg_reload_silent: false,
+            notify_error: true,
+            tooltip_size: (24, 24),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct CfgOptions {
+    pub process_unmapped_keys: bool,
+    pub process_unmapped_keys_exceptions: Option<Vec<(OsCode, SExpr)>>,
+    pub block_unmapped_keys: bool,
+    pub allow_hardware_repeat: bool,
+    pub start_alias: Option<String>,
+    pub enable_cmd: bool,
+    pub sequence_timeout: u16,
+    pub sequence_input_mode: SequenceInputMode,
+    pub sequence_backtrack_modcancel: bool,
+    pub sequence_always_on: bool,
+    pub log_layer_changes: bool,
+    pub delegate_to_first_layer: bool,
+    pub movemouse_inherit_accel_state: bool,
+    pub movemouse_smooth_diagonals: bool,
+    pub override_release_on_activation: bool,
+    pub dynamic_macro_max_presses: u16,
+    pub dynamic_macro_replay_delay_behaviour: ReplayDelayBehaviour,
+    pub concurrent_tap_hold: bool,
+    pub rapid_event_delay: u16,
+    pub trans_resolution_behavior_v2: bool,
+    pub chords_v2_min_idle: u16,
+    pub tap_hold_require_prior_idle: u16,
+    #[cfg(any(
+        all(target_os = "windows", feature = "interception_driver"),
+        target_os = "linux",
+        target_os = "android",
+        target_os = "macos",
+        target_os = "unknown"
+    ))]
+    pub mouse_movement_key: Option<OsCode>,
+    #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+    pub linux_opts: CfgLinuxOptions,
+    #[cfg(any(target_os = "macos", target_os = "unknown"))]
+    pub macos_opts: CfgMacosOptions,
+    #[cfg(any(target_os = "windows", target_os = "unknown"))]
+    pub windows_opts: CfgWindowsOptions,
+    #[cfg(any(
+        all(feature = "interception_driver", target_os = "windows"),
+        target_os = "unknown"
+    ))]
+    pub wintercept_opts: CfgWinterceptOptions,
+    #[cfg(all(any(target_os = "windows", target_os = "unknown"), feature = "gui"))]
+    pub gui_opts: CfgOptionsGui,
+}
+
+impl Default for CfgOptions {
+    fn default() -> Self {
+        Self {
+            process_unmapped_keys: false,
+            process_unmapped_keys_exceptions: None,
+            block_unmapped_keys: false,
+            allow_hardware_repeat: true,
+            start_alias: None,
+            enable_cmd: false,
+            sequence_timeout: 1000,
+            sequence_input_mode: SequenceInputMode::HiddenSuppressed,
+            sequence_backtrack_modcancel: true,
+            sequence_always_on: false,
+            log_layer_changes: true,
+            delegate_to_first_layer: false,
+            movemouse_inherit_accel_state: false,
+            movemouse_smooth_diagonals: false,
+            override_release_on_activation: false,
+            dynamic_macro_max_presses: 128,
+            dynamic_macro_replay_delay_behaviour: ReplayDelayBehaviour::Recorded,
+            concurrent_tap_hold: false,
+            rapid_event_delay: 5,
+            trans_resolution_behavior_v2: true,
+            chords_v2_min_idle: 5,
+            tap_hold_require_prior_idle: 0,
+            #[cfg(any(
+                all(target_os = "windows", feature = "interception_driver"),
+                target_os = "linux",
+                target_os = "android",
+                target_os = "macos",
+                target_os = "unknown"
+            ))]
+            mouse_movement_key: None,
+            #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+            linux_opts: Default::default(),
+            #[cfg(any(target_os = "windows", target_os = "unknown"))]
+            windows_opts: Default::default(),
+            #[cfg(any(
+                all(feature = "interception_driver", target_os = "windows"),
+                target_os = "unknown"
+            ))]
+            wintercept_opts: Default::default(),
+            #[cfg(any(target_os = "macos", target_os = "unknown"))]
+            macos_opts: Default::default(),
+            #[cfg(all(any(target_os = "windows", target_os = "unknown"), feature = "gui"))]
+            gui_opts: Default::default(),
+        }
+    }
+}
+
+/// Parse configuration entries from an expression starting with defcfg.
+pub fn parse_defcfg(expr: &[SExpr]) -> Result<CfgOptions> {
+    let mut seen_keys = HashSet::default();
+    let mut cfg = CfgOptions::default();
+    let mut exprs = check_first_expr(expr.iter(), "defcfg")?;
+    let mut is_process_unmapped_keys_defined = false;
+    // Read k-v pairs from the configuration
+    loop {
+        let key = match exprs.next() {
+            Some(k) => k,
+            None => {
+                if !is_process_unmapped_keys_defined {
+                    log::warn!(
+                        "The item process-unmapped-keys is not defined in defcfg. Consider whether process-unmapped-keys should be yes vs. no."
+                    );
+                }
+                return Ok(cfg);
+            }
+        };
+        let val = match exprs.next() {
+            Some(v) => v,
+            None => bail_expr!(key, "Found a defcfg option missing a value"),
+        };
+        match key {
+            SExpr::Atom(k) => {
+                let label = k.t.as_str();
+                if !seen_keys.insert(label) {
+                    bail_expr!(key, "Duplicate defcfg option {}", label);
+                }
+                match label {
+                    "sequence-timeout" => {
+                        cfg.sequence_timeout = parse_cfg_val_u16(val, label, true)?;
+                    }
+                    "sequence-input-mode" => {
+                        let v = sexpr_to_str_or_err(val, label)?;
+                        cfg.sequence_input_mode = SequenceInputMode::try_from_str(v)
+                            .map_err(|e| anyhow_expr!(val, "{}", e.to_string()))?;
+                    }
+                    "sequence-always-on" => {
+                        cfg.sequence_always_on = parse_defcfg_val_bool(val, label)?
+                    }
+                    "dynamic-macro-max-presses" => {
+                        cfg.dynamic_macro_max_presses = parse_cfg_val_u16(val, label, false)?;
+                    }
+                    "dynamic-macro-replay-delay-behaviour" => {
+                        cfg.dynamic_macro_replay_delay_behaviour = val
+                            .atom(None)
+                            .map(|v| match v {
+                                "constant" => Ok(ReplayDelayBehaviour::Constant),
+                                "recorded" => Ok(ReplayDelayBehaviour::Recorded),
+                                _ => bail_expr!(
+                                    val,
+                                    "this option must be one of: constant | recorded"
+                                ),
+                            })
+                            .ok_or_else(|| {
+                                anyhow_expr!(val, "this option must be one of: constant | recorded")
+                            })??;
+                    }
+                    "linux-dev" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            cfg.linux_opts.linux_dev = parse_dev(val)?;
+                            if cfg.linux_opts.linux_dev.is_empty() {
+                                bail_expr!(
+                                    val,
+                                    "device list is empty, no devices will be intercepted"
+                                );
+                            }
+                        }
+                    }
+                    "linux-dev-names-include" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let dev_names = parse_dev(val)?;
+                            if dev_names.is_empty() {
+                                log::warn!("linux-dev-names-include is empty");
+                            }
+                            cfg.linux_opts.linux_dev_names_include = Some(dev_names);
+                        }
+                    }
+                    "linux-dev-names-exclude" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            cfg.linux_opts.linux_dev_names_exclude = Some(parse_dev(val)?);
+                        }
+                    }
+                    "linux-unicode-u-code" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            cfg.linux_opts.linux_unicode_u_code = crate::keys::str_to_oscode(v)
+                                .ok_or_else(|| {
+                                    anyhow_expr!(val, "unknown code for {label}: {}", v)
+                                })?;
+                        }
+                    }
+                    "linux-unicode-termination" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            cfg.linux_opts.linux_unicode_termination = match v {
+                                "enter" => UnicodeTermination::Enter,
+                                "space" => UnicodeTermination::Space,
+                                "enter-space" => UnicodeTermination::EnterSpace,
+                                "space-enter" => UnicodeTermination::SpaceEnter,
+                                _ => bail_expr!(
+                                    val,
+                                    "{label} got {}. It accepts: enter|space|enter-space|space-enter",
+                                    v
+                                ),
+                            }
+                        }
+                    }
+                    "linux-x11-repeat-delay-rate" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            let delay_rate = v.split(',').collect::<Vec<_>>();
+                            const ERRMSG: &str = "Invalid value for linux-x11-repeat-delay-rate.\nExpected two numbers 0-65535 separated by a comma, e.g. 200,25";
+                            if delay_rate.len() != 2 {
+                                bail_expr!(val, "{}", ERRMSG)
+                            }
+                            cfg.linux_opts.linux_x11_repeat_delay_rate = Some(KeyRepeatSettings {
+                                delay: match str::parse::<u16>(delay_rate[0]) {
+                                    Ok(delay) => delay,
+                                    Err(_) => bail_expr!(val, "{}", ERRMSG),
+                                },
+                                rate: match str::parse::<u16>(delay_rate[1]) {
+                                    Ok(rate) => rate,
+                                    Err(_) => bail_expr!(val, "{}", ERRMSG),
+                                },
+                            });
+                        }
+                    }
+                    "linux-use-trackpoint-property" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            cfg.linux_opts.linux_use_trackpoint_property =
+                                parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "linux-output-device-name" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let device_name = sexpr_to_str_or_err(val, label)?;
+                            if device_name.is_empty() {
+                                log::warn!(
+                                    "linux-output-device-name is empty, using kanata as default value"
+                                );
+                            } else {
+                                cfg.linux_opts.linux_output_name = device_name.to_owned();
+                            }
+                        }
+                    }
+                    "linux-output-device-bus-type" => {
+                        let bus_type = sexpr_to_str_or_err(val, label)?;
+                        match bus_type {
+                            "USB" | "I8042" | "virtual" => {}
+                            _ => bail_expr!(
+                                val,
+                                "Invalid value for linux-output-device-bus-type.\nExpected one of: USB | I8042 | virtual"
+                            ),
+                        };
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let bus_type = match bus_type {
+                                "USB" => LinuxCfgOutputBusType::BusUsb,
+                                "I8042" => LinuxCfgOutputBusType::BusI8042,
+                                "virtual" => LinuxCfgOutputBusType::BusVirtual,
+                                _ => unreachable!("validated earlier"),
+                            };
+                            cfg.linux_opts.linux_output_bus_type = bus_type;
+                        }
+                    }
+                    "linux-device-detect-mode" => {
+                        let detect_mode = sexpr_to_str_or_err(val, label)?;
+                        match detect_mode {
+                            "any" | "keyboard-only" | "keyboard-mice" => {}
+                            _ => bail_expr!(
+                                val,
+                                "Invalid value for linux-device-detect-mode.\nExpected one of: any | keyboard-only | keyboard-mice"
+                            ),
+                        };
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            let detect_mode = Some(match detect_mode {
+                                "any" => DeviceDetectMode::Any,
+                                "keyboard-only" => DeviceDetectMode::KeyboardOnly,
+                                "keyboard-mice" => DeviceDetectMode::KeyboardMice,
+                                _ => unreachable!("validated earlier"),
+                            });
+                            cfg.linux_opts.linux_device_detect_mode = detect_mode;
+                        }
+                    }
+                    "windows-altgr" => {
+                        #[cfg(any(target_os = "windows", target_os = "unknown"))]
+                        {
+                            const CANCEL: &str = "cancel-lctl-press";
+                            const ADD: &str = "add-lctl-release";
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            cfg.windows_opts.windows_altgr = match v {
+                                CANCEL => AltGrBehaviour::CancelLctlPress,
+                                ADD => AltGrBehaviour::AddLctlRelease,
+                                _ => bail_expr!(
+                                    val,
+                                    "Invalid value for {label}: {}. Valid values are {},{}",
+                                    v,
+                                    CANCEL,
+                                    ADD
+                                ),
+                            }
+                        }
+                    }
+                    "windows-sync-keystates" => {
+                        #[cfg(any(target_os = "windows", target_os = "unknown"))]
+                        {
+                            cfg.windows_opts.sync_keystates = parse_defcfg_val_bool(val, label)?;
+                        }
+                    }
+                    "windows-interception-mouse-hwid" => {
+                        #[cfg(any(
+                            all(feature = "interception_driver", target_os = "windows"),
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if cfg
+                                .wintercept_opts
+                                .windows_interception_mouse_hwids_exclude
+                                .is_some()
+                            {
+                                bail_expr!(
+                                    val,
+                                    "{label} and windows-interception-mouse-hwid-exclude cannot both be included"
+                                );
+                            }
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            let hwid = v;
+                            log::trace!("win hwid: {hwid}");
+                            let hwid_vec = hwid
+                                .split(',')
+                                .try_fold(vec![], |mut hwid_bytes, hwid_byte| {
+                                    hwid_byte.trim_matches(' ').parse::<u8>().map(|b| {
+                                        hwid_bytes.push(b);
+                                        hwid_bytes
+                                    })
+                                }).map_err(|_| anyhow_expr!(val, "{label} format is invalid. It should consist of numbers [0,255] separated by commas"))?;
+                            let hwid_slice = hwid_vec.iter().copied().enumerate()
+                                .try_fold([0u8; HWID_ARR_SZ], |mut hwid, idx_byte| {
+                                    let (i, b) = idx_byte;
+                                    if i > HWID_ARR_SZ {
+                                        bail_expr!(val, "{label} is too long; it should be up to {HWID_ARR_SZ} numbers [0,255]")
+                                    }
+                                    hwid[i] = b;
+                                    Ok(hwid)
+                            })?;
+                            match cfg
+                                .wintercept_opts
+                                .windows_interception_mouse_hwids
+                                .as_mut()
+                            {
+                                Some(v) => {
+                                    v.push(hwid_slice);
+                                }
+                                None => {
+                                    cfg.wintercept_opts.windows_interception_mouse_hwids =
+                                        Some(vec![hwid_slice]);
+                                }
+                            }
+                            cfg.wintercept_opts
+                                .windows_interception_mouse_hwids
+                                .as_mut()
+                                .unwrap()
+                                .shrink_to_fit();
+                        }
+                    }
+                    "windows-interception-mouse-hwids" => {
+                        #[cfg(any(
+                            all(feature = "interception_driver", target_os = "windows"),
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if cfg
+                                .wintercept_opts
+                                .windows_interception_mouse_hwids_exclude
+                                .is_some()
+                            {
+                                bail_expr!(
+                                    val,
+                                    "{label} and windows-interception-mouse-hwid-exclude cannot both be included"
+                                );
+                            }
+                            let parsed_hwids = sexpr_to_hwids_vec(
+                                val,
+                                label,
+                                "entry in windows-interception-mouse-hwids",
+                            )?;
+                            match cfg
+                                .wintercept_opts
+                                .windows_interception_mouse_hwids
+                                .as_mut()
+                            {
+                                Some(v) => {
+                                    v.extend(parsed_hwids);
+                                }
+                                None => {
+                                    cfg.wintercept_opts.windows_interception_mouse_hwids =
+                                        Some(parsed_hwids);
+                                }
+                            }
+                            cfg.wintercept_opts
+                                .windows_interception_mouse_hwids
+                                .as_mut()
+                                .unwrap()
+                                .shrink_to_fit();
+                        }
+                    }
+                    "windows-interception-mouse-hwids-exclude" => {
+                        #[cfg(any(
+                            all(feature = "interception_driver", target_os = "windows"),
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if cfg
+                                .wintercept_opts
+                                .windows_interception_mouse_hwids
+                                .is_some()
+                            {
+                                bail_expr!(
+                                    val,
+                                    "{label} and windows-interception-mouse-hwid(s) cannot both be used"
+                                );
+                            }
+                            let parsed_hwids = sexpr_to_hwids_vec(
+                                val,
+                                label,
+                                "entry in windows-interception-mouse-hwids-exclude",
+                            )?;
+                            cfg.wintercept_opts.windows_interception_mouse_hwids_exclude =
+                                Some(parsed_hwids);
+                        }
+                    }
+                    "windows-interception-keyboard-hwids" => {
+                        #[cfg(any(
+                            all(feature = "interception_driver", target_os = "windows"),
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if cfg
+                                .wintercept_opts
+                                .windows_interception_keyboard_hwids_exclude
+                                .is_some()
+                            {
+                                bail_expr!(
+                                    val,
+                                    "{label} and windows-interception-keyboard-hwid-exclude cannot both be used"
+                                );
+                            }
+                            let parsed_hwids = sexpr_to_hwids_vec(
+                                val,
+                                label,
+                                "entry in windows-interception-keyboard-hwids",
+                            )?;
+                            cfg.wintercept_opts.windows_interception_keyboard_hwids =
+                                Some(parsed_hwids);
+                        }
+                    }
+                    "windows-interception-keyboard-hwids-exclude" => {
+                        #[cfg(any(
+                            all(feature = "interception_driver", target_os = "windows"),
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if cfg
+                                .wintercept_opts
+                                .windows_interception_keyboard_hwids
+                                .is_some()
+                            {
+                                bail_expr!(
+                                    val,
+                                    "{label} and windows-interception-keyboard-hwid cannot both be used"
+                                );
+                            }
+                            let parsed_hwids = sexpr_to_hwids_vec(
+                                val,
+                                label,
+                                "entry in windows-interception-keyboard-hwids-exclude",
+                            )?;
+                            cfg.wintercept_opts
+                                .windows_interception_keyboard_hwids_exclude = Some(parsed_hwids);
+                        }
+                    }
+                    "macos-dev-names-include" => {
+                        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+                        {
+                            let dev_names = parse_dev(val)?;
+                            if dev_names.is_empty() {
+                                log::warn!("macos-dev-names-include is empty");
+                            }
+                            cfg.macos_opts.macos_dev_names_include = Some(dev_names);
+                        }
+                    }
+                    "macos-dev-names-exclude" => {
+                        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+                        {
+                            let dev_names = parse_dev(val)?;
+                            if dev_names.is_empty() {
+                                log::warn!("macos-dev-names-exclude is empty");
+                            }
+                            cfg.macos_opts.macos_dev_names_exclude = Some(dev_names);
+                        }
+                    }
+                    "macos-continue-if-no-devs-found" => {
+                        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+                        {
+                            cfg.macos_opts.macos_continue_if_no_devs_found =
+                                parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tray-icon" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            let icon_path = sexpr_to_str_or_err(val, label)?;
+                            if icon_path.is_empty() {
+                                log::warn!("tray-icon is empty");
+                            }
+                            cfg.gui_opts.tray_icon = Some(icon_path.to_string());
+                        }
+                    }
+                    "icon-match-layer-name" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.icon_match_layer_name = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tooltip-layer-changes" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.tooltip_layer_changes = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tooltip-show-blank" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.tooltip_show_blank = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tooltip-no-base" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.tooltip_no_base = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tooltip-duration" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.tooltip_duration = parse_cfg_val_u16(val, label, false)?
+                        }
+                    }
+                    "notify-cfg-reload" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.notify_cfg_reload = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "notify-cfg-reload-silent" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.notify_cfg_reload_silent =
+                                parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "notify-error" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            cfg.gui_opts.notify_error = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "tooltip-size" => {
+                        #[cfg(all(
+                            any(target_os = "windows", target_os = "unknown"),
+                            feature = "gui"
+                        ))]
+                        {
+                            let v = sexpr_to_str_or_err(val, label)?;
+                            let tooltip_size = v.split(',').collect::<Vec<_>>();
+                            const ERRMSG: &str = "Invalid value for tooltip-size.\nExpected two numbers 0-65535 separated by a comma, e.g. 24,24";
+                            if tooltip_size.len() != 2 {
+                                bail_expr!(val, "{}", ERRMSG)
+                            }
+                            cfg.gui_opts.tooltip_size = (
+                                match str::parse::<u16>(tooltip_size[0]) {
+                                    Ok(w) => w,
+                                    Err(_) => bail_expr!(val, "{}", ERRMSG),
+                                },
+                                match str::parse::<u16>(tooltip_size[1]) {
+                                    Ok(h) => h,
+                                    Err(_) => bail_expr!(val, "{}", ERRMSG),
+                                },
+                            );
+                        }
+                    }
+
+                    "process-unmapped-keys" => {
+                        is_process_unmapped_keys_defined = true;
+                        if let Some(list) = val.list(None) {
+                            let err = "Expected (all-except key1 ... keyN).";
+                            if list.len() < 2 {
+                                bail_expr!(val, "{err}");
+                            }
+                            match list[0].atom(None) {
+                                Some("all-except") => {}
+                                _ => {
+                                    bail_expr!(val, "{err}");
+                                }
+                            };
+                            // Note: deflocalkeys should already be parsed when parsing defcfg,
+                            // so can use safely use str_to_oscode here; it will include user
+                            // configurations already.
+                            let mut key_exceptions: Vec<(OsCode, SExpr)> = vec![];
+                            for key_expr in list[1..].iter() {
+                                let key = key_expr.atom(None).and_then(str_to_oscode).ok_or_else(
+                                    || anyhow_expr!(key_expr, "Expected a known key name."),
+                                )?;
+                                if key_exceptions.iter().any(|k_exc| k_exc.0 == key) {
+                                    bail_expr!(key_expr, "Duplicate key name is not allowed.");
+                                }
+                                key_exceptions.push((key, key_expr.clone()));
+                            }
+                            cfg.process_unmapped_keys = true;
+                            cfg.process_unmapped_keys_exceptions = Some(key_exceptions);
+                        } else {
+                            cfg.process_unmapped_keys = parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+
+                    "block-unmapped-keys" => {
+                        cfg.block_unmapped_keys = parse_defcfg_val_bool(val, label)?
+                    }
+                    "allow-hardware-repeat" => {
+                        cfg.allow_hardware_repeat = parse_defcfg_val_bool(val, label)?
+                    }
+                    "alias-to-trigger-on-load" => {
+                        cfg.start_alias = parse_defcfg_val_string(val, label)?
+                    }
+                    "danger-enable-cmd" => cfg.enable_cmd = parse_defcfg_val_bool(val, label)?,
+                    "sequence-backtrack-modcancel" => {
+                        cfg.sequence_backtrack_modcancel = parse_defcfg_val_bool(val, label)?
+                    }
+                    "log-layer-changes" => {
+                        cfg.log_layer_changes = parse_defcfg_val_bool(val, label)?
+                    }
+                    "delegate-to-first-layer" => {
+                        cfg.delegate_to_first_layer = parse_defcfg_val_bool(val, label)?;
+                        if cfg.delegate_to_first_layer {
+                            log::info!(
+                                "delegating transparent keys on other layers to first defined layer"
+                            );
+                        }
+                    }
+                    "linux-continue-if-no-devs-found" => {
+                        #[cfg(any(
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            cfg.linux_opts.linux_continue_if_no_devs_found =
+                                parse_defcfg_val_bool(val, label)?
+                        }
+                    }
+                    "movemouse-smooth-diagonals" => {
+                        cfg.movemouse_smooth_diagonals = parse_defcfg_val_bool(val, label)?
+                    }
+                    "movemouse-inherit-accel-state" => {
+                        cfg.movemouse_inherit_accel_state = parse_defcfg_val_bool(val, label)?
+                    }
+                    "override-release-on-activation" => {
+                        cfg.override_release_on_activation = parse_defcfg_val_bool(val, label)?
+                    }
+                    "concurrent-tap-hold" => {
+                        cfg.concurrent_tap_hold = parse_defcfg_val_bool(val, label)?
+                    }
+                    "rapid-event-delay" => {
+                        cfg.rapid_event_delay = parse_cfg_val_u16(val, label, false)?
+                    }
+                    "transparent-key-resolution" => {
+                        let v = sexpr_to_str_or_err(val, label)?;
+                        cfg.trans_resolution_behavior_v2 = match v {
+                            "to-base-layer" => false,
+                            "layer-stack" => true,
+                            _ => bail_expr!(
+                                val,
+                                "{label} got {}. It accepts: 'to-base-layer' or 'layer-stack'",
+                                v
+                            ),
+                        };
+                    }
+                    "chords-v2-min-idle" | "chords-v2-min-idle-experimental" => {
+                        if label == "chords-v2-min-idle-experimental" {
+                            log::warn!(
+                                "You should replace chords-v2-min-idle-experimental with chords-v2-min-idle\n\
+                                        Using -experimental will be invalid in the future."
+                            )
+                        }
+                        let min_idle = parse_cfg_val_u16(val, label, true)?;
+                        if min_idle < 5 {
+                            bail_expr!(val, "{label} must be 5-65535");
+                        }
+                        cfg.chords_v2_min_idle = min_idle;
+                    }
+                    "tap-hold-require-prior-idle" => {
+                        cfg.tap_hold_require_prior_idle = parse_cfg_val_u16(val, label, false)?;
+                    }
+                    "mouse-movement-key" => {
+                        #[cfg(any(
+                            all(target_os = "windows", feature = "interception_driver"),
+                            target_os = "linux",
+                            target_os = "android",
+                            target_os = "macos",
+                            target_os = "unknown"
+                        ))]
+                        {
+                            if let Some(keystr) = parse_defcfg_val_string(val, label)? {
+                                if let Some(key) = str_to_oscode(&keystr) {
+                                    cfg.mouse_movement_key = Some(key);
+                                } else {
+                                    bail_expr!(val, "{label} not a recognised key code");
+                                }
+                            } else {
+                                bail_expr!(val, "{label} not a string for a key code");
+                            }
+                        }
+                    }
+                    _ => bail_expr!(key, "Unknown defcfg option {}", label),
+                };
+            }
+            SExpr::List(_) => {
+                bail_expr!(key, "Lists are not allowed in as keys in defcfg");
+            }
+        }
+    }
+}
+
+fn parse_defcfg_val_string(expr: &SExpr, _label: &str) -> Result<Option<String>> {
+    match expr {
+        SExpr::Atom(v) => Ok(Some(v.t.clone())),
+        _ => Ok(None),
+    }
+}
+
+pub const FALSE_VALUES: [&str; 3] = ["no", "false", "0"];
+pub const TRUE_VALUES: [&str; 3] = ["yes", "true", "1"];
+pub const BOOLEAN_VALUES: [&str; 6] = ["yes", "true", "1", "no", "false", "0"];
+
+fn parse_defcfg_val_bool(expr: &SExpr, label: &str) -> Result<bool> {
+    match &expr {
+        SExpr::Atom(v) => {
+            let val = v.t.trim_atom_quotes().to_ascii_lowercase();
+            if TRUE_VALUES.contains(&val.as_str()) {
+                Ok(true)
+            } else if FALSE_VALUES.contains(&val.as_str()) {
+                Ok(false)
+            } else {
+                bail_expr!(
+                    expr,
+                    "The value for {label} must be one of: {}",
+                    BOOLEAN_VALUES.join(", ")
+                );
+            }
+        }
+        SExpr::List(_) => {
+            bail_expr!(
+                expr,
+                "The value for {label} cannot be a list, it must be one of: {}",
+                BOOLEAN_VALUES.join(", "),
+            )
+        }
+    }
+}
+
+fn parse_cfg_val_u16(expr: &SExpr, label: &str, exclude_zero: bool) -> Result<u16> {
+    let start = if exclude_zero { 1 } else { 0 };
+    match &expr {
+        SExpr::Atom(v) => Ok(str::parse::<u16>(v.t.trim_atom_quotes())
+            .ok()
+            .and_then(|u| {
+                if exclude_zero && u == 0 {
+                    None
+                } else {
+                    Some(u)
+                }
+            })
+            .ok_or_else(|| anyhow_expr!(expr, "{label} must be {start}-65535"))?),
+        SExpr::List(_) => {
+            bail_expr!(
+                expr,
+                "The value for {label} cannot be a list, it must be a number {start}-65535",
+            )
+        }
+    }
+}
+
+pub fn parse_colon_separated_text(paths: &str) -> Vec<String> {
+    let mut all_paths = vec![];
+    let mut full_dev_path = String::new();
+    let mut dev_path_iter = paths.split(':').peekable();
+    while let Some(dev_path) = dev_path_iter.next() {
+        if dev_path.ends_with('\\') && dev_path_iter.peek().is_some() {
+            full_dev_path.push_str(dev_path.trim_end_matches('\\'));
+            full_dev_path.push(':');
+            continue;
+        } else {
+            full_dev_path.push_str(dev_path);
+        }
+        all_paths.push(full_dev_path.clone());
+        full_dev_path.clear();
+    }
+    all_paths.shrink_to_fit();
+    all_paths
+}
+
+#[cfg(any(
+    target_os = "linux",
+    target_os = "android",
+    target_os = "macos",
+    target_os = "unknown"
+))]
+pub fn parse_dev(val: &SExpr) -> Result<Vec<String>> {
+    Ok(match val {
+        SExpr::Atom(a) => {
+            let devs = parse_colon_separated_text(a.t.trim_atom_quotes());
+            if devs.len() == 1 && devs[0].is_empty() {
+                bail_expr!(val, "an empty string is not a valid device name or path")
+            }
+            devs
+        }
+        SExpr::List(l) => {
+            let r: Result<Vec<String>> =
+                l.t.iter()
+                    .try_fold(Vec::with_capacity(l.t.len()), |mut acc, expr| match expr {
+                        SExpr::Atom(path) => {
+                            let trimmed_path = path.t.trim_atom_quotes().to_string();
+                            if trimmed_path.is_empty() {
+                                bail_span!(
+                                    path,
+                                    "an empty string is not a valid device name or path"
+                                )
+                            }
+                            acc.push(trimmed_path);
+                            Ok(acc)
+                        }
+                        SExpr::List(inner_list) => {
+                            bail_span!(inner_list, "expected strings, found a list")
+                        }
+                    });
+
+            r?
+        }
+    })
+}
+
+fn sexpr_to_str_or_err<'a>(expr: &'a SExpr, label: &str) -> Result<&'a str> {
+    match expr {
+        SExpr::Atom(a) => Ok(a.t.trim_atom_quotes()),
+        SExpr::List(_) => bail_expr!(expr, "The value for {label} can't be a list"),
+    }
+}
+
+#[cfg(any(
+    all(feature = "interception_driver", target_os = "windows"),
+    target_os = "unknown"
+))]
+fn sexpr_to_list_or_err<'a>(expr: &'a SExpr, label: &str) -> Result<&'a [SExpr]> {
+    match expr {
+        SExpr::Atom(_) => bail_expr!(expr, "The value for {label} must be a list"),
+        SExpr::List(l) => Ok(&l.t),
+    }
+}
+
+#[cfg(any(
+    all(feature = "interception_driver", target_os = "windows"),
+    target_os = "unknown"
+))]
+fn sexpr_to_hwids_vec(
+    val: &SExpr,
+    label: &str,
+    entry_label: &str,
+) -> Result<Vec<[u8; HWID_ARR_SZ]>> {
+    let hwids = sexpr_to_list_or_err(val, label)?;
+    let mut parsed_hwids = vec![];
+    for hwid_expr in hwids.iter() {
+        let hwid = sexpr_to_str_or_err(hwid_expr, entry_label)?;
+        log::trace!("win hwid: {hwid}");
+        let hwid_vec = hwid
+            .split(',')
+            .try_fold(vec![], |mut hwid_bytes, hwid_byte| {
+                hwid_byte.trim_matches(' ').parse::<u8>().map(|b| {
+                    hwid_bytes.push(b);
+                    hwid_bytes
+                })
+            }).map_err(|_| anyhow_expr!(hwid_expr, "Entry in {label} is invalid. Entries should be numbers [0,255] separated by commas"))?;
+        let hwid_slice = hwid_vec.iter().copied().enumerate()
+            .try_fold([0u8; HWID_ARR_SZ], |mut hwid, idx_byte| {
+                let (i, b) = idx_byte;
+                if i > HWID_ARR_SZ {
+                    bail_expr!(hwid_expr, "entry in {label} is too long; it should be up to {HWID_ARR_SZ} 8-bit unsigned integers")
+                }
+                hwid[i] = b;
+                Ok(hwid)
+        });
+        parsed_hwids.push(hwid_slice?);
+    }
+    parsed_hwids.shrink_to_fit();
+    Ok(parsed_hwids)
+}
+
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct KeyRepeatSettings {
+    pub delay: u16,
+    pub rate: u16,
+}
+
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum UnicodeTermination {
+    Enter,
+    Space,
+    SpaceEnter,
+    EnterSpace,
+}
+
+#[cfg(any(target_os = "windows", target_os = "unknown"))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum AltGrBehaviour {
+    #[default]
+    DoNothing,
+    CancelLctlPress,
+    AddLctlRelease,
+}
+
+#[cfg(any(target_os = "windows", target_os = "unknown"))]
+#[cfg(any(
+    all(feature = "interception_driver", target_os = "windows"),
+    target_os = "unknown"
+))]
+pub const HWID_ARR_SZ: usize = 1024;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ReplayDelayBehaviour {
+    /// Always use a fixed number of ticks between presses and releases.
+    /// This is the original kanata behaviour.
+    /// This means that held action activations like in tap-hold do not behave as intended.
+    Constant,
+    /// Use the recorded number of ticks between presses and releases.
+    /// This is newer behaviour.
+    Recorded,
+}
diff --git a/parser/src/cfg/defhands.rs b/parser/src/cfg/defhands.rs
new file mode 100644
index 000000000..3229cfd07
--- /dev/null
+++ b/parser/src/cfg/defhands.rs
@@ -0,0 +1,426 @@
+use super::sexpr::*;
+use super::*;
+use crate::{anyhow_expr, bail, bail_expr};
+
+pub(super) fn parse_defhands(expr: &[SExpr], s: &ParserState) -> Result<custom_tap_hold::HandMap> {
+    use custom_tap_hold::Hand;
+
+    let exprs_iter = check_first_expr(expr.iter(), "defhands")?;
+    let mut keys: Vec<u16> = Vec::new();
+    let mut hands: Vec<Hand> = Vec::new();
+    let mut seen_left = false;
+    let mut seen_right = false;
+
+    for group_expr in exprs_iter {
+        let group = group_expr
+            .list(s.vars())
+            .ok_or_else(|| anyhow_expr!(group_expr, "expected (left ...) or (right ...)"))?;
+        if group.is_empty() {
+            bail_expr!(group_expr, "expected (left ...) or (right ...)");
+        }
+        let hand_name = group[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&group[0], "expected 'left' or 'right'"))?;
+        let hand = match hand_name {
+            "left" => {
+                if seen_left {
+                    bail_expr!(&group[0], "duplicate 'left' group in defhands");
+                }
+                seen_left = true;
+                Hand::Left
+            }
+            "right" => {
+                if seen_right {
+                    bail_expr!(&group[0], "duplicate 'right' group in defhands");
+                }
+                seen_right = true;
+                Hand::Right
+            }
+            _ => bail_expr!(&group[0], "expected 'left' or 'right', got '{}'", hand_name),
+        };
+        for key_expr in &group[1..] {
+            let key_name = key_expr
+                .atom(s.vars())
+                .ok_or_else(|| anyhow_expr!(key_expr, "expected a key name, found list"))?;
+            let osc = str_to_oscode(key_name)
+                .ok_or_else(|| anyhow_expr!(key_expr, "unknown key '{}'", key_name))?;
+            let code = u16::from(osc);
+            if let Some(pos) = keys.iter().position(|&k| k == code) {
+                let existing_name = if hands[pos] == Hand::Left {
+                    "left"
+                } else {
+                    "right"
+                };
+                bail_expr!(
+                    key_expr,
+                    "Key already assigned to '{}' hand, cannot also be in '{}'",
+                    existing_name,
+                    hand_name
+                );
+            }
+            keys.push(code);
+            hands.push(hand);
+        }
+    }
+
+    let keys_static = s.a.sref_vec(keys);
+    let hands_static = s.a.sref_vec(hands);
+    Ok(custom_tap_hold::HandMap {
+        keys: keys_static,
+        hands: hands_static,
+    })
+}
+
+pub(super) fn parse_tap_hold_opposite_hand(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    use custom_tap_hold::{DecisionBehavior, custom_tap_hold_opposite_hand};
+
+    const ARITY_MSG: &str = "tap-hold-opposite-hand expects at least 3 items: \
+            <timeout> <tap> <hold> [options...]";
+    if ac_params.is_empty() {
+        bail!(ARITY_MSG);
+    }
+    if ac_params.len() < 3 {
+        bail_expr!(&ac_params[0], "{}", ARITY_MSG);
+    }
+    let hand_map = s.hand_map.ok_or_else(|| {
+        anyhow_expr!(
+            &ac_params[0],
+            "tap-hold-opposite-hand requires defhands to be defined"
+        )
+    })?;
+
+    let hold_timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    let tap_action = parse_action(&ac_params[1], s)?;
+    let hold_action = parse_action(&ac_params[2], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail_expr!(
+            &ac_params[1],
+            "tap-hold does not work in the tap-action of tap-hold"
+        );
+    }
+
+    let mut timeout_behavior = DecisionBehavior::Tap;
+    let mut same_hand = DecisionBehavior::Tap;
+    let mut neutral_behavior = DecisionBehavior::Ignore;
+    let mut unknown_hand = DecisionBehavior::Ignore;
+    let mut neutral_keys: Vec<OsCode> = Vec::new();
+    let mut require_prior_idle: Option<u16> = None;
+    let mut tap_repress_timeout: u16 = 0;
+    let mut seen_options: HashSet<&str> = HashSet::default();
+
+    for option_expr in &ac_params[3..] {
+        let Some(option) = option_expr.list(s.vars()) else {
+            bail_expr!(
+                option_expr,
+                "expected option list, e.g. `(timeout hold)` or `(neutral-keys spc tab)`"
+            );
+        };
+        if option.is_empty() {
+            bail_expr!(option_expr, "option list cannot be empty");
+        }
+        let kw = option[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&option[0], "option name must be a string"))?;
+        if !seen_options.insert(kw) {
+            bail_expr!(
+                &option[0],
+                "duplicate option '{}' in tap-hold-opposite-hand",
+                kw
+            );
+        }
+        match kw {
+            "timeout" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                timeout_behavior = parse_decision_behavior_tap_hold(&option[1], s)?;
+            }
+            "same-hand" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                same_hand = parse_decision_behavior(&option[1], s)?;
+            }
+            "neutral" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                neutral_behavior = parse_decision_behavior(&option[1], s)?;
+            }
+            "unknown-hand" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                unknown_hand = parse_decision_behavior(&option[1], s)?;
+            }
+            "neutral-keys" => {
+                if option.len() < 2 {
+                    bail_expr!(
+                        option_expr,
+                        "neutral-keys expects one or more key atoms, e.g. `(neutral-keys spc tab)`"
+                    );
+                }
+                neutral_keys = parse_key_atoms(&option[1..], s, "neutral-keys")?;
+            }
+            "require-prior-idle" => {
+                require_prior_idle = Some(tap_hold::parse_require_prior_idle_option(
+                    option,
+                    option_expr,
+                    s,
+                )?);
+            }
+            "tap-repress-timeout" => {
+                tap_repress_timeout =
+                    tap_hold::parse_tap_repress_timeout_option(option, option_expr, s)?;
+            }
+            _ => bail_expr!(
+                &option[0],
+                "unknown option '{}' for tap-hold-opposite-hand. \
+                Valid options: timeout, same-hand, neutral, unknown-hand, neutral-keys, \
+                require-prior-idle, tap-repress-timeout",
+                kw
+            ),
+        }
+    }
+
+    let timeout_action = match timeout_behavior {
+        DecisionBehavior::Tap => tap_action,
+        DecisionBehavior::Hold => hold_action,
+        DecisionBehavior::Ignore => unreachable!(),
+    };
+
+    let neutral_keys_static = s.a.sref_vec(neutral_keys);
+
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_tap_hold_opposite_hand(
+            hand_map,
+            same_hand,
+            neutral_behavior,
+            unknown_hand,
+            neutral_keys_static,
+            &s.a,
+        )),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *timeout_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle,
+    }))))
+}
+
+pub(super) fn parse_tap_hold_opposite_hand_release(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    use custom_tap_hold::{DecisionBehavior, custom_tap_hold_opposite_hand_release};
+
+    const ARITY_MSG: &str = "tap-hold-opposite-hand-release expects at least 3 items: \
+            <timeout> <tap> <hold> [options...]";
+    if ac_params.is_empty() {
+        bail!(ARITY_MSG);
+    }
+    if ac_params.len() < 3 {
+        bail_expr!(&ac_params[0], "{}", ARITY_MSG);
+    }
+    let hand_map = s.hand_map.ok_or_else(|| {
+        anyhow_expr!(
+            &ac_params[0],
+            "tap-hold-opposite-hand-release requires defhands to be defined"
+        )
+    })?;
+
+    let hold_timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    let tap_action = parse_action(&ac_params[1], s)?;
+    let hold_action = parse_action(&ac_params[2], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail_expr!(
+            &ac_params[1],
+            "tap-hold does not work in the tap-action of tap-hold"
+        );
+    }
+
+    let mut timeout_behavior = DecisionBehavior::Tap;
+    let mut same_hand = DecisionBehavior::Tap;
+    let mut neutral_behavior = DecisionBehavior::Ignore;
+    let mut unknown_hand = DecisionBehavior::Ignore;
+    let mut neutral_keys: Vec<OsCode> = Vec::new();
+    let mut require_prior_idle: Option<u16> = None;
+    let mut tap_repress_timeout: u16 = 0;
+    let mut seen_options: HashSet<&str> = HashSet::default();
+
+    for option_expr in &ac_params[3..] {
+        let Some(option) = option_expr.list(s.vars()) else {
+            bail_expr!(
+                option_expr,
+                "expected option list, e.g. `(timeout hold)` or `(neutral-keys spc tab)`"
+            );
+        };
+        if option.is_empty() {
+            bail_expr!(option_expr, "option list cannot be empty");
+        }
+        let kw = option[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&option[0], "option name must be a string"))?;
+        if !seen_options.insert(kw) {
+            bail_expr!(
+                &option[0],
+                "duplicate option '{}' in tap-hold-opposite-hand-release",
+                kw
+            );
+        }
+        match kw {
+            "timeout" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                timeout_behavior = parse_decision_behavior_tap_hold(&option[1], s)?;
+            }
+            "same-hand" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                same_hand = parse_decision_behavior(&option[1], s)?;
+            }
+            "neutral" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                neutral_behavior = parse_decision_behavior(&option[1], s)?;
+            }
+            "unknown-hand" => {
+                if option.len() != 2 {
+                    bail_expr!(
+                        option_expr,
+                        "option must contain exactly 2 items: `(name value)`"
+                    );
+                }
+                unknown_hand = parse_decision_behavior(&option[1], s)?;
+            }
+            "neutral-keys" => {
+                if option.len() < 2 {
+                    bail_expr!(
+                        option_expr,
+                        "neutral-keys expects one or more key atoms, e.g. `(neutral-keys spc tab)`"
+                    );
+                }
+                neutral_keys = parse_key_atoms(&option[1..], s, "neutral-keys")?;
+            }
+            "require-prior-idle" => {
+                require_prior_idle = Some(tap_hold::parse_require_prior_idle_option(
+                    option,
+                    option_expr,
+                    s,
+                )?);
+            }
+            "tap-repress-timeout" => {
+                tap_repress_timeout =
+                    tap_hold::parse_tap_repress_timeout_option(option, option_expr, s)?;
+            }
+            _ => bail_expr!(
+                &option[0],
+                "unknown option '{}' for tap-hold-opposite-hand-release. \
+                Valid options: timeout, same-hand, neutral, unknown-hand, neutral-keys, \
+                require-prior-idle, tap-repress-timeout",
+                kw
+            ),
+        }
+    }
+
+    let timeout_action = match timeout_behavior {
+        DecisionBehavior::Tap => tap_action,
+        DecisionBehavior::Hold => hold_action,
+        DecisionBehavior::Ignore => unreachable!(),
+    };
+
+    let neutral_keys_static = s.a.sref_vec(neutral_keys);
+
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_tap_hold_opposite_hand_release(
+            hand_map,
+            same_hand,
+            neutral_behavior,
+            unknown_hand,
+            neutral_keys_static,
+            &s.a,
+        )),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *timeout_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle,
+    }))))
+}
+
+fn parse_key_atoms(exprs: &[SExpr], s: &ParserState, label: &str) -> Result<Vec<OsCode>> {
+    exprs
+        .iter()
+        .map(|key_expr| {
+            let key_name = key_expr
+                .atom(s.vars())
+                .ok_or_else(|| anyhow_expr!(key_expr, "{label} expects key atoms, found list"))?;
+            str_to_oscode(key_name)
+                .ok_or_else(|| anyhow_expr!(key_expr, "unknown key '{key_name}'"))
+        })
+        .collect()
+}
+
+fn parse_decision_behavior(
+    expr: &SExpr,
+    s: &ParserState,
+) -> Result<custom_tap_hold::DecisionBehavior> {
+    use custom_tap_hold::DecisionBehavior;
+
+    match expr
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(expr, "expected tap, hold, or ignore"))?
+    {
+        "tap" => Ok(DecisionBehavior::Tap),
+        "hold" => Ok(DecisionBehavior::Hold),
+        "ignore" => Ok(DecisionBehavior::Ignore),
+        v => bail_expr!(expr, "expected tap, hold, or ignore; got '{}'", v),
+    }
+}
+
+fn parse_decision_behavior_tap_hold(
+    expr: &SExpr,
+    s: &ParserState,
+) -> Result<custom_tap_hold::DecisionBehavior> {
+    use custom_tap_hold::DecisionBehavior;
+
+    match expr
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(expr, "expected tap or hold"))?
+    {
+        "tap" => Ok(DecisionBehavior::Tap),
+        "hold" => Ok(DecisionBehavior::Hold),
+        v => bail_expr!(expr, "expected tap or hold for timeout; got '{}'", v),
+    }
+}
diff --git a/parser/src/cfg/definputdevices.rs b/parser/src/cfg/definputdevices.rs
new file mode 100644
index 000000000..8aaf57150
--- /dev/null
+++ b/parser/src/cfg/definputdevices.rs
@@ -0,0 +1,132 @@
+use super::*;
+use crate::{anyhow_expr, bail_expr};
+use std::num::NonZeroU8;
+
+#[derive(Debug, Clone, Default)]
+pub struct InputDeviceMatcher {
+    pub name: Option<String>,
+    pub hash: Option<String>,
+    pub vendor_id: Option<u16>,
+    pub product_id: Option<u16>,
+}
+
+pub fn parse_definputdevices(expr: &[SExpr]) -> Result<Vec<(NonZeroU8, InputDeviceMatcher)>> {
+    let mut exprs = check_first_expr(expr.iter(), "definputdevices")?;
+    let mut seen_ids = HashSet::default();
+    let mut devices = vec![];
+    while let Some(id_expr) = exprs.next() {
+        let Some(matchers_expr) = exprs.next() else {
+            bail_expr!(
+                id_expr,
+                "definputdevices expects pairs: <id> <matcher-list>.\n\
+                 Missing matcher list for this device ID."
+            );
+        };
+        let id_str = id_expr
+            .atom(None)
+            .ok_or_else(|| anyhow_expr!(id_expr, "device ID must be a number (1-255)"))?;
+        let id_num: u8 = id_str
+            .parse()
+            .map_err(|_| anyhow_expr!(id_expr, "device ID must be a number (1-255)"))?;
+        let id = NonZeroU8::new(id_num)
+            .ok_or_else(|| anyhow_expr!(id_expr, "device ID must be nonzero (1-255)"))?;
+        if !seen_ids.insert(id) {
+            bail_expr!(id_expr, "duplicate device ID: {id_num}");
+        }
+        let matcher_list = matchers_expr
+            .list(None)
+            .ok_or_else(|| anyhow_expr!(matchers_expr, "device matchers must be a list"))?;
+        if matcher_list.is_empty() {
+            bail_expr!(
+                matchers_expr,
+                "device matcher list must not be empty; \
+                 specify at least one of: name, hash, vendor_id, product_id"
+            );
+        }
+        let mut matcher = InputDeviceMatcher::default();
+        for m in matcher_list.iter() {
+            let props = m.list(None).ok_or_else(|| {
+                anyhow_expr!(m, "each matcher must be a list, e.g. (name \"...\")")
+            })?;
+            if props.len() != 2 {
+                bail_expr!(
+                    m,
+                    "each matcher must have exactly 2 items: (property value)"
+                );
+            }
+            let prop_name = props[0]
+                .atom(None)
+                .ok_or_else(|| anyhow_expr!(&props[0], "matcher property must be an atom"))?;
+            let prop_val = props[1]
+                .atom(None)
+                .ok_or_else(|| anyhow_expr!(&props[1], "matcher value must be an atom"))?;
+            match prop_name {
+                "name" => {
+                    if matcher.name.is_some() {
+                        bail_expr!(m, "duplicate property: name");
+                    }
+                    matcher.name = Some(prop_val.to_string());
+                }
+                "hash" => {
+                    if matcher.hash.is_some() {
+                        bail_expr!(m, "duplicate property: hash");
+                    }
+                    let stripped = prop_val
+                        .strip_prefix("0x")
+                        .or_else(|| prop_val.strip_prefix("0X"))
+                        .unwrap_or(prop_val);
+                    if stripped.is_empty() || !stripped.chars().all(|c| c.is_ascii_hexdigit()) {
+                        bail_expr!(
+                            &props[1],
+                            "hash must be a valid hex string (e.g. \"a1b2c3def4\")"
+                        );
+                    }
+                    // Store lowercase, without 0x prefix, for case-insensitive matching.
+                    matcher.hash = Some(stripped.to_ascii_lowercase());
+                }
+                "vendor_id" => {
+                    if matcher.vendor_id.is_some() {
+                        bail_expr!(m, "duplicate property: vendor_id");
+                    }
+                    let v = parse_hex_or_decimal_u16(prop_val).map_err(|_| {
+                        anyhow_expr!(
+                            &props[1],
+                            "vendor_id must be a number 0-65535 or hex (e.g. 0x1D50)"
+                        )
+                    })?;
+                    matcher.vendor_id = Some(v);
+                }
+                "product_id" => {
+                    if matcher.product_id.is_some() {
+                        bail_expr!(m, "duplicate property: product_id");
+                    }
+                    let v = parse_hex_or_decimal_u16(prop_val).map_err(|_| {
+                        anyhow_expr!(
+                            &props[1],
+                            "product_id must be a number 0-65535 or hex (e.g. 0x615E)"
+                        )
+                    })?;
+                    matcher.product_id = Some(v);
+                }
+                _ => {
+                    bail_expr!(
+                        &props[0],
+                        "unknown matcher property: {prop_name}\n\
+                         valid properties: name, hash, vendor_id, product_id"
+                    );
+                }
+            }
+        }
+        devices.push((id, matcher));
+    }
+    Ok(devices)
+}
+
+fn parse_hex_or_decimal_u16(s: &str) -> std::result::Result<u16, Box<dyn std::error::Error>> {
+    let val: u64 = if let Some(hex) = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")) {
+        u64::from_str_radix(hex, 16)?
+    } else {
+        s.parse()?
+    };
+    u16::try_from(val).map_err(|e| e.into())
+}
diff --git a/parser/src/cfg/deflayer.rs b/parser/src/cfg/deflayer.rs
new file mode 100644
index 000000000..5aad47e59
--- /dev/null
+++ b/parser/src/cfg/deflayer.rs
@@ -0,0 +1,278 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::anyhow_span;
+use crate::bail;
+use crate::bail_expr;
+use crate::bail_span;
+
+pub(crate) type LayerIndexes = HashMap<String, usize>;
+
+pub(crate) const DEFLAYER: &str = "deflayer";
+pub(crate) const DEFLAYER_MAPPED: &str = "deflayermap";
+
+/// Returns layer names and their indexes into the keyberon layout. This also checks that:
+/// - All layers have the same number of items as the defsrc,
+/// - There are no duplicate layer names
+/// - Parentheses weren't used directly or kmonad-style escapes for parentheses weren't used.
+pub(crate) fn parse_layer_indexes(
+    exprs: &[SpannedLayerExprs],
+    expected_len: usize,
+    vars: &HashMap<String, SExpr>,
+    _lsp_hints: &mut LspHints,
+) -> Result<(LayerIndexes, LayerIcons)> {
+    let mut layer_indexes = HashMap::default();
+    let mut layer_icons = HashMap::default();
+    for (i, expr_type) in exprs.iter().enumerate() {
+        let (mut subexprs, expr, do_element_count_check, deflayer_keyword) = match expr_type {
+            SpannedLayerExprs::DefsrcMapping(e) => {
+                (check_first_expr(e.t.iter(), DEFLAYER)?, e, true, DEFLAYER)
+            }
+            SpannedLayerExprs::CustomMapping(e) => (
+                check_first_expr(e.t.iter(), DEFLAYER_MAPPED)?,
+                e,
+                false,
+                DEFLAYER_MAPPED,
+            ),
+        };
+        let layer_expr = subexprs.next().ok_or_else(|| {
+            anyhow_span!(
+                expr,
+                "{deflayer_keyword} requires a layer name after `{deflayer_keyword}` token"
+            )
+        })?;
+        let (layer_name, _layer_name_span, icon) = {
+            let name = layer_expr.atom(Some(vars));
+            match name {
+                Some(name) => (name.to_owned(), layer_expr.span(), None),
+                None => {
+                    // unwrap: this **must** be a list due to atom() call above.
+                    let list = layer_expr.list(Some(vars)).unwrap();
+                    let first = list.first().ok_or_else(|| anyhow_expr!(
+                            layer_expr,
+                            "{deflayer_keyword} requires a string name within this pair of parentheses (or a string name without any)"
+                        ))?;
+                    let name = first.atom(Some(vars)).ok_or_else(|| anyhow_expr!(
+                            layer_expr,
+                            "layer name after {deflayer_keyword} must be a string when enclosed within one pair of parentheses"
+                        ))?;
+                    let layer_opts = parse_layer_opts(&list[1..])?;
+                    let icon = layer_opts
+                        .get(DEFLAYER_ICON[0])
+                        .map(|icon_s| icon_s.trim_atom_quotes().to_owned());
+                    (name.to_owned(), first.span(), icon)
+                }
+            }
+        };
+        if layer_indexes.contains_key(&layer_name) {
+            bail_expr!(layer_expr, "duplicate layer name: {}", layer_name);
+        }
+        // Check if user tried to use parentheses directly - `(` and `)`
+        // or escaped them like in kmonad - `\(` and `\)`.
+        for subexpr in subexprs {
+            if let Some(list) = subexpr.list(None) {
+                if list.is_empty() {
+                    bail_expr!(
+                        subexpr,
+                        "You can't put parentheses in deflayer directly, because they are special characters for delimiting lists.\n\
+                         To get `(` and `)` in US layout, you should use `S-9` and `S-0` respectively.\n\
+                         For more context, see: https://github.com/jtroo/kanata/issues/459"
+                    )
+                }
+                if list.len() == 1
+                    && list
+                        .first()
+                        .is_some_and(|s| s.atom(None).is_some_and(|atom| atom == "\\"))
+                {
+                    bail_expr!(
+                        subexpr,
+                        "Escaping shifted characters with `\\` is currently not supported in kanata.\n\
+                         To get `(` and `)` in US layout, you should use `S-9` and `S-0` respectively.\n\
+                         For more context, see: https://github.com/jtroo/kanata/issues/163"
+                    )
+                }
+            }
+        }
+        if do_element_count_check {
+            let num_actions = expr.t.len() - 2;
+            if num_actions != expected_len {
+                bail_span!(
+                    expr,
+                    "Layer {} has {} item(s), but requires {} to match defsrc",
+                    layer_name,
+                    num_actions,
+                    expected_len
+                )
+            }
+        }
+
+        #[cfg(feature = "lsp")]
+        _lsp_hints
+            .definition_locations
+            .layer
+            .insert(layer_name.clone(), _layer_name_span.clone());
+
+        layer_indexes.insert(layer_name.clone(), i);
+        layer_icons.insert(layer_name, icon);
+    }
+
+    Ok((layer_indexes, layer_icons))
+}
+
+pub(crate) fn parse_layers(
+    s: &ParserState,
+    mapped_keys: &mut MappedKeys,
+    defcfg: &CfgOptions,
+) -> Result<IntermediateLayers> {
+    let mut layers_cfg = new_layers(s.layer_exprs.len());
+    if s.layer_exprs.len() > MAX_LAYERS {
+        bail!("Maximum number of layers ({}) exceeded.", MAX_LAYERS);
+    }
+    let mut defsrc_layer = s.defsrc_layer;
+    for (layer_level, layer) in s.layer_exprs.iter().enumerate() {
+        match layer {
+            // The skip is done to skip the `deflayer` and layer name tokens.
+            LayerExprs::DefsrcMapping(layer) => {
+                // Parse actions in the layer and place them appropriately according
+                // to defsrc mapping order.
+                for (i, ac) in layer.iter().skip(2).enumerate() {
+                    let ac = parse_action(ac, s)?;
+                    layers_cfg[layer_level][0][s.mapping_order[i]] = *ac;
+                }
+            }
+            LayerExprs::CustomMapping(layer) => {
+                // Parse actions as input output pairs
+                let mut pairs = layer[2..].chunks_exact(2);
+                let mut layer_mapped_keys = HashSet::default();
+                let mut defsrc_anykey_used = false;
+                let mut unmapped_anykey_used = false;
+                let mut both_anykey_used = false;
+                for pair in pairs.by_ref() {
+                    let input = &pair[0];
+                    let action = &pair[1];
+
+                    let action = parse_action(action, s)?;
+                    if input.atom(s.vars()).is_some_and(|x| x == "_") {
+                        if defsrc_anykey_used {
+                            bail_expr!(input, "must have only one use of _ within a layer")
+                        }
+                        if both_anykey_used {
+                            bail_expr!(input, "must either use _ or ___ within a layer, not both")
+                        }
+                        for i in 0..s.mapping_order.len() {
+                            if layers_cfg[layer_level][0][s.mapping_order[i]] == DEFAULT_ACTION {
+                                layers_cfg[layer_level][0][s.mapping_order[i]] = *action;
+                            }
+                        }
+                        defsrc_anykey_used = true;
+                    } else if input.atom(s.vars()).is_some_and(|x| x == "__") {
+                        if unmapped_anykey_used {
+                            bail_expr!(input, "must have only one use of __ within a layer")
+                        }
+                        if !defcfg.process_unmapped_keys {
+                            bail_expr!(
+                                input,
+                                "must set process-unmapped-keys to yes to use __ to map unmapped keys"
+                            );
+                        }
+                        if both_anykey_used {
+                            bail_expr!(input, "must either use __ or ___ within a layer, not both")
+                        }
+                        for i in 0..layers_cfg[0][0].len() {
+                            if layers_cfg[layer_level][0][i] == DEFAULT_ACTION
+                                && !s.mapping_order.contains(&i)
+                            {
+                                layers_cfg[layer_level][0][i] = *action;
+                            }
+                        }
+                        unmapped_anykey_used = true;
+                    } else if input.atom(s.vars()).is_some_and(|x| x == "___") {
+                        if both_anykey_used {
+                            bail_expr!(input, "must have only one use of ___ within a layer")
+                        }
+                        if defsrc_anykey_used {
+                            bail_expr!(input, "must either use _ or ___ within a layer, not both")
+                        }
+                        if unmapped_anykey_used {
+                            bail_expr!(input, "must either use __ or ___ within a layer, not both")
+                        }
+                        if !defcfg.process_unmapped_keys {
+                            bail_expr!(
+                                input,
+                                "must set process-unmapped-keys to yes to use ___ to also map unmapped keys"
+                            );
+                        }
+                        for i in 0..layers_cfg[0][0].len() {
+                            if layers_cfg[layer_level][0][i] == DEFAULT_ACTION {
+                                layers_cfg[layer_level][0][i] = *action;
+                            }
+                        }
+                        both_anykey_used = true;
+                    } else {
+                        let input_key = input
+                            .atom(s.vars())
+                            .and_then(str_to_oscode)
+                            .ok_or_else(|| anyhow_expr!(input, "input must be a key name"))?;
+                        mapped_keys.insert(input_key);
+                        if !layer_mapped_keys.insert(input_key) {
+                            bail_expr!(input, "input key must not be repeated within a layer")
+                        }
+                        layers_cfg[layer_level][0][usize::from(input_key)] = *action;
+                    }
+                }
+                let rem = pairs.remainder();
+                if !rem.is_empty() {
+                    bail_expr!(&rem[0], "input must by followed by an action");
+                }
+            }
+        }
+        for (osc, layer_action) in layers_cfg[layer_level][0].iter_mut().enumerate() {
+            if *layer_action == DEFAULT_ACTION {
+                *layer_action = match s.block_unmapped_keys && !is_a_button(osc as u16) {
+                    true => Action::NoOp,
+                    false => Action::Trans,
+                };
+            }
+        }
+
+        // Set fake keys on every layer.
+        for (y, action) in s.virtual_keys.values() {
+            let (x, y) = get_fake_key_coords(*y);
+            layers_cfg[layer_level][x as usize][y as usize] = **action;
+        }
+
+        // If the user has configured delegation to the first (default) layer for transparent keys,
+        // (as opposed to delegation to defsrc), replace the defsrc actions with the actions from
+        // the first layer.
+        if layer_level == 0 && s.delegate_to_first_layer {
+            for (defsrc_ac, default_layer_ac) in defsrc_layer.iter_mut().zip(layers_cfg[0][0]) {
+                if default_layer_ac != Action::Trans {
+                    *defsrc_ac = default_layer_ac;
+                }
+            }
+        }
+
+        // Very last thing - ensure index 0 is always no-op. This shouldn't have any way to be
+        // physically activated. This enable other code to rely on there always being a no-op key.
+        layers_cfg[layer_level][0][0] = Action::NoOp;
+    }
+    Ok(layers_cfg)
+}
+
+pub(crate) fn parse_layer_base(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let idx = layer_idx(ac_params, &s.layer_idxs, s)?;
+    set_layer_change_lsp_hint(&ac_params[0], &mut s.lsp_hints.borrow_mut());
+    Ok(s.a.sref(Action::DefaultLayer(idx)))
+}
+
+pub(crate) fn parse_layer_toggle(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let idx = layer_idx(ac_params, &s.layer_idxs, s)?;
+    set_layer_change_lsp_hint(&ac_params[0], &mut s.lsp_hints.borrow_mut());
+    Ok(s.a.sref(Action::Layer(idx)))
+}
diff --git a/parser/src/cfg/deflocalkeys.rs b/parser/src/cfg/deflocalkeys.rs
new file mode 100644
index 000000000..3bc7cc136
--- /dev/null
+++ b/parser/src/cfg/deflocalkeys.rs
@@ -0,0 +1,93 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail_expr;
+
+#[cfg(all(
+    not(feature = "interception_driver"),
+    any(
+        not(feature = "win_llhook_read_scancodes"),
+        not(feature = "win_sendinput_send_scancodes")
+    ),
+    target_os = "windows"
+))]
+pub(crate) const DEF_LOCAL_KEYS: &str = "deflocalkeys-win";
+#[cfg(all(
+    feature = "win_llhook_read_scancodes",
+    feature = "win_sendinput_send_scancodes",
+    not(feature = "interception_driver"),
+    target_os = "windows"
+))]
+pub(crate) const DEF_LOCAL_KEYS: &str = "deflocalkeys-winiov2";
+#[cfg(all(feature = "interception_driver", target_os = "windows"))]
+pub(crate) const DEF_LOCAL_KEYS: &str = "deflocalkeys-wintercept";
+#[cfg(target_os = "macos")]
+pub(crate) const DEF_LOCAL_KEYS: &str = "deflocalkeys-macos";
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+pub(crate) const DEF_LOCAL_KEYS: &str = "deflocalkeys-linux";
+
+pub(crate) fn deflocalkeys_variant_applies_to_current_os(variant: &str) -> bool {
+    variant == DEF_LOCAL_KEYS
+}
+
+pub(crate) const DEFLOCALKEYS_VARIANTS: &[&str] = &[
+    "deflocalkeys-win",
+    "deflocalkeys-winiov2",
+    "deflocalkeys-wintercept",
+    "deflocalkeys-linux",
+    "deflocalkeys-macos",
+];
+
+/// Parse custom keys from an expression starting with deflocalkeys.
+pub(crate) fn parse_deflocalkeys(
+    def_local_keys_variant: &str,
+    expr: &[SExpr],
+) -> Result<HashMap<String, OsCode>> {
+    let mut localkeys = HashMap::default();
+    let mut exprs = check_first_expr(expr.iter(), def_local_keys_variant)?;
+    // Read k-v pairs from the configuration
+    while let Some(key_expr) = exprs.next() {
+        let key = key_expr.atom(None).ok_or_else(|| {
+            anyhow_expr!(key_expr, "No lists are allowed in {def_local_keys_variant}")
+        })?;
+        if localkeys.contains_key(key) {
+            bail_expr!(
+                key_expr,
+                "Duplicate {key} found in {def_local_keys_variant}"
+            );
+        }
+
+        // Bug:
+        // Trying to convert a number to OsCode is OS-dependent and is fallible.
+        // A valid number for Linux could throw an error on Windows.
+        //
+        // Fix:
+        // When the deflocalkeys variant does not apply to the current OS,
+        // use a dummy OsCode to keep the "same name" validation
+        // while avoiding the u16->OsCode conversion attempt.
+        if !deflocalkeys_variant_applies_to_current_os(def_local_keys_variant) {
+            localkeys.insert(key.to_owned(), OsCode::KEY_RESERVED);
+            continue;
+        }
+
+        let osc = match exprs.next() {
+            Some(v) => v
+                .atom(None)
+                .ok_or_else(|| anyhow_expr!(v, "No lists are allowed in {def_local_keys_variant}"))
+                .and_then(|osc| {
+                    osc.parse::<u16>().map_err(|_| {
+                        anyhow_expr!(v, "Unknown number in {def_local_keys_variant}: {osc}")
+                    })
+                })
+                .and_then(|osc| {
+                    OsCode::from_u16(osc).ok_or_else(|| {
+                        anyhow_expr!(v, "Unknown number in {def_local_keys_variant}: {osc}")
+                    })
+                })?,
+            None => bail_expr!(key_expr, "Key without a number in {def_local_keys_variant}"),
+        };
+        log::debug!("custom mapping: {key} {}", osc.as_u16());
+        localkeys.insert(key.to_owned(), osc);
+    }
+    Ok(localkeys)
+}
diff --git a/parser/src/cfg/defsrc.rs b/parser/src/cfg/defsrc.rs
new file mode 100644
index 000000000..5f39127e1
--- /dev/null
+++ b/parser/src/cfg/defsrc.rs
@@ -0,0 +1,106 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail_expr;
+
+/// Parse mapped keys from an expression starting with defsrc. Returns the key mapping as well as
+/// a vec of the indexes in order. The length of the returned vec should be matched by the length
+/// of all layer declarations.
+pub(crate) fn parse_defsrc(
+    expr: &[SExpr],
+    defcfg: &CfgOptions,
+) -> Result<(MappedKeys, Vec<usize>, MouseInDefsrc)> {
+    let exprs = check_first_expr(expr.iter(), "defsrc")?;
+    let mut mkeys = MappedKeys::default();
+    let mut ordered_codes = Vec::new();
+    let mut is_mouse_used = MouseInDefsrc::NoMouse;
+    for expr in exprs {
+        let s = match expr {
+            SExpr::Atom(a) => &a.t,
+            _ => bail_expr!(expr, "No lists allowed in defsrc"),
+        };
+        let oscode = str_to_oscode(s)
+            .ok_or_else(|| anyhow_expr!(expr, "Unknown key in defsrc: \"{}\"", s))?;
+        is_mouse_used = match (is_mouse_used, oscode) {
+            (
+                MouseInDefsrc::NoMouse,
+                OsCode::BTN_LEFT
+                | OsCode::BTN_RIGHT
+                | OsCode::BTN_MIDDLE
+                | OsCode::BTN_SIDE
+                | OsCode::BTN_EXTRA
+                | OsCode::MouseWheelUp
+                | OsCode::MouseWheelDown
+                | OsCode::MouseWheelLeft
+                | OsCode::MouseWheelRight,
+            ) => MouseInDefsrc::MouseUsed,
+            _ => is_mouse_used,
+        };
+
+        if mkeys.contains(&oscode) {
+            bail_expr!(expr, "Repeat declaration of key in defsrc: \"{}\"", s)
+        }
+        mkeys.insert(oscode);
+        ordered_codes.push(oscode.into());
+    }
+
+    let mapped_exceptions = match &defcfg.process_unmapped_keys_exceptions {
+        Some(excluded_keys) => {
+            for excluded_key in excluded_keys.iter() {
+                log::debug!("process unmapped keys exception: {:?}", excluded_key);
+                if mkeys.contains(&excluded_key.0) {
+                    bail_expr!(
+                        &excluded_key.1,
+                        "Keys cannot be included in defsrc and also excepted in process-unmapped-keys."
+                    );
+                }
+            }
+
+            excluded_keys
+                .iter()
+                .map(|excluded_key| excluded_key.0)
+                .collect()
+        }
+        None => vec![],
+    };
+
+    log::info!("process unmapped keys: {}", defcfg.process_unmapped_keys);
+    if defcfg.process_unmapped_keys {
+        for osc in 0..KEYS_IN_ROW as u16 {
+            if let Some(osc) = OsCode::from_u16(osc) {
+                if osc.is_mouse_code() {
+                    // Bugfix #1879:
+                    // Auto-including mouse activity in mapped keys
+                    // seems strictly incorrect to do, so never do it.
+                    // Users can still choose to opt in if they want.
+                    // Auto-including mouse activity breaks many scenarios.
+                    continue;
+                }
+                match KeyCode::from(osc) {
+                    KeyCode::No => {}
+                    _ => {
+                        if !mapped_exceptions.contains(&osc) {
+                            mkeys.insert(osc);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    mkeys.shrink_to_fit();
+    Ok((mkeys, ordered_codes, is_mouse_used))
+}
+
+pub(crate) fn create_defsrc_layer() -> [KanataAction; KEYS_IN_ROW] {
+    let mut layer = [KanataAction::NoOp; KEYS_IN_ROW];
+
+    for (i, ac) in layer.iter_mut().enumerate() {
+        *ac = OsCode::from_u16(i as u16)
+            .map(|osc| Action::KeyCode(osc.into()))
+            .unwrap_or(Action::NoOp);
+    }
+    // Ensure 0-index is no-op.
+    layer[0] = KanataAction::NoOp;
+    layer
+}
diff --git a/parser/src/cfg/deftemplate.rs b/parser/src/cfg/deftemplate.rs
new file mode 100644
index 000000000..01afb501d
--- /dev/null
+++ b/parser/src/cfg/deftemplate.rs
@@ -0,0 +1,563 @@
+//! This file is responsible for template expansion.
+//! For simplicity of implementation, there is performance left off the table.
+//! This code runs at parse time and not in runtime
+//! so it is not performance critical.
+//!
+//! The known performance left off the table is:
+//!
+//! - Creating the expanded template recurses through all SExprs every time.
+//!   Instead the code could pre-compute the paths to access every variable
+//!   that needs substition. (perf_1)
+//!
+//! - Replacing the `template-expand|if-equal` items with the appropriate values
+//!   recreates the Vec for every replacement that happens at that recursion depth.
+//!   Instead the code could do recreate the vec only once
+//!   and insert SExprs at the proper places. (perf_2)
+
+use crate::anyhow_expr;
+use crate::anyhow_span;
+use crate::bail_expr;
+use crate::bail_span;
+use crate::err_expr;
+use crate::err_span;
+
+use super::error::*;
+use super::sexpr::*;
+use super::*;
+
+#[derive(Debug)]
+struct Template {
+    name: String,
+    vars: Vec<String>,
+    // Same as vars above but all names are prefixed with '$'.
+    vars_substitute_names: Vec<String>,
+    content: Vec<SExpr>,
+}
+
+/// Parse `deftemplate`s and expand `template-expand`s.
+///
+/// Syntax of `deftemplate` is:
+///
+/// `(deftemplate <template name> (<list of template vars>) <rest of template>)`
+///
+/// Syntax of `template-expand` is:
+///
+/// `(template-expand <template name> <template var substitutions>)`
+pub fn expand_templates(
+    mut toplevel_exprs: Vec<TopLevel>,
+    lsp_hints: &mut LspHints,
+) -> Result<Vec<TopLevel>> {
+    let mut templates: Vec<Template> = vec![];
+
+    // Find defined templates
+    for list in toplevel_exprs.iter_mut() {
+        if !matches!(
+            list.t.first().and_then(|expr| expr.atom(None)),
+            Some("deftemplate")
+        ) {
+            continue;
+        }
+
+        // Parse template name
+        let (name, _name_span) = list
+            .t
+            .get(1)
+            .ok_or_else(|| {
+                anyhow_span!(
+                    list,
+                    "deftemplate must have the template name as the first parameter"
+                )
+            })
+            .and_then(|name_expr| {
+                let name = name_expr
+                    .atom(None)
+                    .ok_or_else(|| anyhow_expr!(name_expr, "template name must be a string"))?;
+                // check for duplicates
+                if templates.iter().any(|t| t.name == name) {
+                    bail_expr!(name_expr, "template name was already defined earlier");
+                }
+                Ok((name, name_expr.span()))
+            })?;
+
+        #[cfg(feature = "lsp")]
+        lsp_hints
+            .definition_locations
+            .template
+            .insert(name.to_owned(), _name_span);
+
+        // Parse template variable names
+        let vars = list
+            .t
+            .get(2)
+            .ok_or_else(|| {
+                anyhow_span!(
+                    list,
+                    "deftemplate must have a list of template variables as the second parameter"
+                )
+            })
+            .and_then(|v| {
+                v.list(None).ok_or_else(|| {
+                    anyhow_expr!(
+                        v,
+                        "deftemplate must have a list of template variables the second parameter"
+                    )
+                })
+            })
+            .and_then(|v| {
+                v.iter().try_fold(vec![], |mut vars, var| {
+                    let s = var.atom(None).map(|a| a.to_owned()).ok_or_else(|| {
+                        anyhow_expr!(var, "deftemplate variables must be strings")
+                    })?;
+                    vars.push(s);
+                    Ok(vars)
+                })
+            })?;
+        let vars_substitute_names: Vec<_> = vars.iter().map(|v| format!("${v}")).collect();
+
+        // Validate content of template
+        let content: Vec<SExpr> = list.t.iter().skip(3).cloned().collect();
+        let mut var_usage_counts: HashMap<String, u32> = vars_substitute_names
+            .iter()
+            .map(|v| (v.clone(), 0))
+            .collect();
+        visit_validate_all_atoms_peek_next(&content, &mut |s, s_next| match s.t.as_str() {
+            "deftemplate" => err_span!(s, "deftemplate is not allowed within deftemplate"),
+            "template-expand" | "t!" => {
+                match s_next {
+                    Some(next) => {
+                        match next.atom(None) {
+                            Some(name_in_expand) => {
+                                match templates.iter().any(|existing_template| {
+                                    existing_template.name == name_in_expand
+                                }) {
+                                    true => Ok(()),
+                                    false => err_expr!(
+                                        next,
+                                        "Unknown template name in template-expand. Note that order of declaration matters."
+                                    ),
+                                }
+                            }
+                            None => {
+                                // Next expr is list.
+                                // This is invalid syntax, but this will be caught later.
+                                // For simplicity in this function, leave it be.
+                                Ok(())
+                            }
+                        }
+                    }
+                    None => {
+                        // No next expr after expand.
+                        // This is invalid syntax, but this will be caught later.
+                        // For simplicity in this function, leave it be.
+                        Ok(())
+                    }
+                }
+            }
+            s => {
+                if let Some(count) = var_usage_counts.get_mut(s) {
+                    *count += 1;
+                }
+                Ok(())
+            }
+        })?;
+        for (var, count) in var_usage_counts.iter() {
+            if *count == 0 {
+                log::warn!("deftemplate variable {var} did not appear in its template {name}");
+            }
+        }
+
+        templates.push(Template {
+            name: name.to_string(),
+            vars,
+            vars_substitute_names,
+            content,
+        });
+    }
+
+    // Find and do expansions
+    let mut toplevels: Vec<SExpr> = toplevel_exprs
+        .into_iter()
+        .map(|tl| {
+            SExpr::List(Spanned {
+                span: tl.span,
+                t: tl.t,
+            })
+        })
+        .collect();
+    expand(&mut toplevels, &templates, lsp_hints)?;
+
+    toplevels.into_iter().try_fold(vec![], |mut tls, tl| {
+        tls.push(match &tl {
+            SExpr::Atom(_) => bail_expr!(
+                &tl,
+                "expansion created a string outside any list which is not allowed"
+            ),
+            SExpr::List(l) => Spanned {
+                t: l.t.clone(),
+                span: l.span.clone(),
+            },
+        });
+        Ok(tls)
+    })
+}
+
+struct Replacement {
+    exprs: Vec<SExpr>,
+    insert_index: usize,
+}
+
+fn expand(exprs: &mut Vec<SExpr>, templates: &[Template], _lsp_hints: &mut LspHints) -> Result<()> {
+    let mut replacements: Vec<Replacement> = vec![];
+    loop {
+        for (expr_index, expr) in exprs.iter_mut().enumerate() {
+            match expr {
+                SExpr::Atom(_) => continue,
+                SExpr::List(l) => {
+                    if !matches!(
+                        l.t.first().and_then(|expr| expr.atom(None)),
+                        Some("template-expand") | Some("t!")
+                    ) {
+                        expand(&mut l.t, templates, _lsp_hints)?;
+                        continue;
+                    }
+
+                    // found expand, now parse
+                    let template = l
+                        .t
+                        .get(1)
+                        .ok_or_else(|| {
+                            anyhow_span!(
+                                l,
+                                "template-expand must have a template name as the first parameter"
+                            )
+                        })
+                        .and_then(|name_expr| {
+                            let name = name_expr.atom(None).ok_or_else(|| {
+                                anyhow_expr!(name_expr, "template name must be a string")
+                            })?;
+                            #[cfg(feature = "lsp")]
+                            _lsp_hints
+                                .reference_locations
+                                .template
+                                .push(name, name_expr.span());
+                            templates.iter().find(|t| t.name == name).ok_or_else(|| {
+                                anyhow_expr!(
+                                    name_expr,
+                                    "template name was not defined in any deftemplate"
+                                )
+                            })
+                        })?;
+                    if l.t.len() - 2 != template.vars.len() {
+                        bail_span!(
+                            l,
+                            "template-expand of {} needs {} parameters but instead found {}.\nParameters: {}",
+                            &template.name,
+                            template.vars.len(),
+                            l.t.len() - 2,
+                            template.vars.join(" ")
+                        );
+                    }
+
+                    let var_substitutions = l.t.iter().skip(2);
+                    let mut expanded_template = template.content.clone();
+                    // Substitute variables.
+                    // perf_1 : could store substitution knowledge instead of iterating and searching
+                    // every time
+                    visit_mut_all_atoms(&mut expanded_template, &mut |expr: &mut SExpr| {
+                        *expr = match expr {
+                            // Below should not be reached because only atoms should be visited
+                            SExpr::List(_) => unreachable!(),
+                            SExpr::Atom(a) => {
+                                match template
+                                    .vars_substitute_names
+                                    .iter()
+                                    .enumerate()
+                                    .find(|(_, var)| *var == &a.t)
+                                {
+                                    None => expr.clone(),
+                                    Some((var_index, _)) => var_substitutions
+                                        .clone()
+                                        .nth(var_index)
+                                        .expect("validated matching var lens")
+                                        .clone(),
+                                }
+                            }
+                        }
+                    });
+
+                    visit_mut_all_lists(&mut expanded_template, &mut |expr: &mut SExpr| {
+                        *expr = match expr {
+                            // Below should not be reached because only lists should be visited
+                            SExpr::Atom(_) => unreachable!(),
+                            SExpr::List(l) => parse_list_var(l, &HashMap::default()),
+                        };
+                        match expr {
+                            SExpr::Atom(_) => true,
+                            SExpr::List(_) => false,
+                        }
+                    });
+
+                    while evaluate_conditionals(&mut expanded_template)? {}
+
+                    replacements.push(Replacement {
+                        insert_index: expr_index,
+                        exprs: expanded_template,
+                    });
+                }
+            }
+        }
+
+        // Ensure replacements are sorted. They probably are, but may as well make sure.
+        replacements.sort_by_key(|r| r.insert_index);
+        // Must replace last-first to keep unreplaced insertion points stable.
+        // perf_2 : could construct vec in one pass.
+        for replacement in replacements.iter().rev() {
+            let (before, after) = exprs.split_at(replacement.insert_index);
+            let after = after.iter().skip(1); // first element is `(template-expand ...)`
+            let new_vec = before
+                .iter()
+                .cloned()
+                .chain(replacement.exprs.iter().cloned())
+                .chain(after.cloned())
+                .collect();
+            *exprs = new_vec;
+        }
+
+        if replacements.is_empty() {
+            break;
+        }
+        replacements.clear();
+    }
+
+    Ok(())
+}
+
+fn visit_validate_all_atoms(
+    exprs: &[SExpr],
+    visit: &mut dyn FnMut(&Spanned<String>) -> Result<()>,
+) -> Result<()> {
+    for expr in exprs {
+        match expr {
+            SExpr::Atom(a) => visit(a)?,
+            SExpr::List(l) => visit_validate_all_atoms(&l.t, visit)?,
+        }
+    }
+    Ok(())
+}
+
+#[allow(clippy::type_complexity)]
+fn visit_validate_all_atoms_peek_next(
+    exprs: &[SExpr],
+    visit: &mut dyn FnMut(&Spanned<String>, Option<&SExpr>) -> Result<()>,
+) -> Result<()> {
+    for (i, expr) in exprs.iter().enumerate() {
+        match expr {
+            SExpr::Atom(a) => visit(a, exprs.get(i + 1))?,
+            SExpr::List(l) => visit_validate_all_atoms_peek_next(&l.t, visit)?,
+        }
+    }
+    Ok(())
+}
+
+fn visit_mut_all_atoms(exprs: &mut [SExpr], visit: &mut dyn FnMut(&mut SExpr)) {
+    for expr in exprs {
+        match expr {
+            SExpr::Atom(_) => visit(expr),
+            SExpr::List(l) => visit_mut_all_atoms(&mut l.t, visit),
+        }
+    }
+}
+
+fn visit_mut_all_lists(exprs: &mut [SExpr], visit: &mut dyn FnMut(&mut SExpr) -> ChangeOccurred) {
+    for expr in exprs {
+        loop {
+            if let SExpr::Atom(_) = expr {
+                break;
+            }
+            // revisit until change did not happen to the list
+            if !visit(expr) {
+                if let SExpr::List(l) = expr {
+                    visit_mut_all_lists(&mut l.t, visit);
+                }
+                break;
+            }
+        }
+    }
+}
+
+type ChangeOccurred = bool;
+
+fn evaluate_conditionals(exprs: &mut Vec<SExpr>) -> Result<ChangeOccurred> {
+    let mut replacements: Vec<Replacement> = vec![];
+    let mut expand_happened = false;
+    for (index, expr) in exprs.iter_mut().enumerate() {
+        if matches!(expr, SExpr::Atom(_)) {
+            continue;
+        }
+        // expr must be a list, visit it
+        if let Some(exprs) = if_equal_replacement(expr)? {
+            replacements.push(Replacement {
+                exprs,
+                insert_index: index,
+            })
+        } else if let Some(exprs) = if_not_equal_replacement(expr)? {
+            replacements.push(Replacement {
+                exprs,
+                insert_index: index,
+            })
+        } else if let Some(exprs) = if_in_list_replacement(expr)? {
+            replacements.push(Replacement {
+                exprs,
+                insert_index: index,
+            })
+        } else if let Some(exprs) = if_not_in_list_replacement(expr)? {
+            replacements.push(Replacement {
+                exprs,
+                insert_index: index,
+            })
+        } else {
+            expand_happened |= match expr {
+                SExpr::Atom(_) => unreachable!(),
+                SExpr::List(l) => evaluate_conditionals(&mut l.t)?,
+            };
+        }
+    }
+    // Ensure replacements are sorted. They probably are, but may as well make sure.
+    replacements.sort_by_key(|r| r.insert_index);
+    // Must replace last-first to keep unreplaced insertion points stable.
+    // perf_2 : could construct vec in one pass.
+    for replacement in replacements.iter().rev() {
+        let (before, after) = exprs.split_at(replacement.insert_index);
+        let after = after.iter().skip(1); // first element is `(if-equal ...)`
+        let new_vec = before
+            .iter()
+            .cloned()
+            .chain(replacement.exprs.iter().cloned())
+            .chain(after.cloned())
+            .collect();
+        *exprs = new_vec;
+    }
+    expand_happened |= !replacements.is_empty();
+    Ok(expand_happened)
+}
+
+fn if_equal_replacement(expr: &SExpr) -> Result<Option<Vec<SExpr>>> {
+    strings_compare_replacement(expr, "if-equal")
+}
+
+fn if_not_equal_replacement(expr: &SExpr) -> Result<Option<Vec<SExpr>>> {
+    strings_compare_replacement(expr, "if-not-equal")
+}
+
+fn if_in_list_replacement(expr: &SExpr) -> Result<Option<Vec<SExpr>>> {
+    string_list_compare_replacement(expr, "if-in-list")
+}
+
+fn if_not_in_list_replacement(expr: &SExpr) -> Result<Option<Vec<SExpr>>> {
+    string_list_compare_replacement(expr, "if-not-in-list")
+}
+
+fn strings_compare_replacement(expr: &SExpr, operation: &str) -> Result<Option<Vec<SExpr>>> {
+    match expr {
+        // Below should not be reached because only lists should be visited
+        SExpr::Atom(_) => unreachable!(),
+        SExpr::List(l) => Ok(match l.t.first() {
+            Some(SExpr::Atom(Spanned { t, .. })) if t.as_str() == operation => {
+                let first =
+                    l.t.get(1)
+                        .ok_or_else(|| {
+                            anyhow_expr!(
+                                &expr,
+                                "{operation} expects a string comparand as the first parameter"
+                            )
+                        })
+                        .and_then(|expr| {
+                            expr.atom(None).ok_or_else(|| {
+                                anyhow_expr!(&expr, "comparands within {operation} must be strings")
+                            })
+                        })?;
+                let second =
+                    l.t.get(2)
+                        .ok_or_else(|| {
+                            anyhow_expr!(
+                                &expr,
+                                "{operation} expects a string comparand as the second parameter"
+                            )
+                        })
+                        .and_then(|expr| {
+                            expr.atom(None).ok_or_else(|| {
+                                anyhow_expr!(&expr, "comparands within {operation} must be strings")
+                            })
+                        })?;
+                if match operation {
+                    "if-equal" => first == second,
+                    "if-not-equal" => first != second,
+                    _ => unreachable!(),
+                } {
+                    Some(l.t.iter().skip(3).cloned().collect())
+                } else {
+                    Some(vec![])
+                }
+            }
+            _ => None,
+        }),
+    }
+}
+
+fn string_list_compare_replacement(expr: &SExpr, operation: &str) -> Result<Option<Vec<SExpr>>> {
+    match expr {
+        // Below should not be reached because only lists should be visited
+        SExpr::Atom(_) => unreachable!(),
+        SExpr::List(l) => Ok(match l.t.first() {
+            Some(SExpr::Atom(Spanned { t, .. })) if t.as_str() == operation => {
+                let first =
+                    l.t.get(1)
+                        .ok_or_else(|| {
+                            anyhow_expr!(
+                                &expr,
+                                "{operation} expects a string comparand as the first parameter"
+                            )
+                        })
+                        .and_then(|expr| {
+                            expr.atom(None).ok_or_else(|| {
+                                anyhow_expr!(
+                                    &expr,
+                                    "the first parameter of {operation} must be a string"
+                                )
+                            })
+                        })?;
+                let second =
+                    l.t.get(2)
+                        .ok_or_else(|| {
+                            anyhow_expr!(
+                                &expr,
+                                "{operation} expects a list comparand as the second parameter"
+                            )
+                        })
+                        .and_then(|expr| {
+                            expr.list(None).ok_or_else(|| {
+                                anyhow_expr!(
+                                    &expr,
+                                    "the second parameter of {operation} must be a list"
+                                )
+                            })
+                        })?;
+                let mut in_list = false;
+                visit_validate_all_atoms(second, &mut |s| {
+                    in_list |= s.t == first;
+                    Ok(())
+                })?;
+                if match operation {
+                    "if-in-list" => in_list,
+                    "if-not-in-list" => !in_list,
+                    _ => unreachable!(),
+                } {
+                    Some(l.t.iter().skip(3).cloned().collect())
+                } else {
+                    Some(vec![])
+                }
+            }
+            _ => None,
+        }),
+    }
+}
diff --git a/parser/src/cfg/error.rs b/parser/src/cfg/error.rs
index f1bbe2eb9..810ba76da 100644
--- a/parser/src/cfg/error.rs
+++ b/parser/src/cfg/error.rs
@@ -1,85 +1,93 @@
+// # Regarding #[allow(unused_assignments)]
+//
+// Seems the miette macros no longer trigger the compiler to find usage.
+
+#![allow(unused_assignments)]
+
 use miette::{Diagnostic, NamedSource, SourceSpan};
 use thiserror::Error;
 
-use super::*;
+use super::{sexpr::Span, *};
 
 pub type MResult<T> = miette::Result<T>;
-pub type Result<T> = std::result::Result<T, CfgError>;
+pub type Result<T> = std::result::Result<T, ParseError>;
 
-#[derive(Error, Debug, Diagnostic, Clone)]
-#[error("Error in configuration file")]
-#[diagnostic()]
-pub struct CfgError {
-    // Snippets and highlights can be included in the diagnostic!
-    #[label("Error here")]
-    pub err_span: Option<SourceSpan>,
-    #[help]
-    pub help_msg: String,
-    pub file_name: Option<String>,
-    pub file_content: Option<String>,
+#[derive(Debug, Clone)]
+pub struct ParseError {
+    pub msg: String,
+    pub span: Option<Span>,
 }
 
-pub(super) fn help(err_msg: impl AsRef<str>) -> String {
-    format!(
-        r"{}
+impl ParseError {
+    pub fn new(span: Span, err_msg: impl AsRef<str>) -> Self {
+        Self {
+            msg: err_msg.as_ref().to_string(),
+            span: Some(span),
+        }
+    }
 
-For more info, see the configuration guide or ask in GitHub discussions.
-    guide : https://github.com/jtroo/kanata/blob/main/docs/config.adoc
-    ask   : https://github.com/jtroo/kanata/discussions",
-        err_msg.as_ref(),
-    )
-}
+    pub fn new_without_span(err_msg: impl AsRef<str>) -> Self {
+        Self {
+            msg: err_msg.as_ref().to_string(),
+            span: None,
+        }
+    }
 
-pub(super) fn error_expr(expr: &sexpr::SExpr, err_msg: impl AsRef<str>) -> CfgError {
-    CfgError {
-        err_span: Some(expr_err_span(expr)),
-        help_msg: help(err_msg),
-        file_name: Some(expr.span().file_name()),
-        file_content: Some(expr.span().file_content()),
+    pub fn from_expr(expr: &sexpr::SExpr, err_msg: impl AsRef<str>) -> Self {
+        Self::new(expr.span(), err_msg)
     }
-}
 
-pub(super) fn error_spanned<T>(expr: &Spanned<T>, err_msg: impl AsRef<str>) -> CfgError {
-    CfgError {
-        err_span: Some(spanned_err_span(expr)),
-        help_msg: help(err_msg),
-        file_name: Some(expr.span.file_name()),
-        file_content: Some(expr.span.file_content()),
+    pub fn from_spanned<T>(spanned: &Spanned<T>, err_msg: impl AsRef<str>) -> Self {
+        Self::new(spanned.span.clone(), err_msg)
     }
 }
 
-pub(super) fn span_start_len(start: usize, len: usize) -> SourceSpan {
-    SourceSpan::new(start.into(), len.into())
+impl From<anyhow::Error> for ParseError {
+    fn from(value: anyhow::Error) -> Self {
+        Self::new_without_span(value.to_string())
+    }
 }
 
-pub(super) fn expr_err_span(expr: &sexpr::SExpr) -> SourceSpan {
-    let span = expr.span();
-    SourceSpan::new(span.start.into(), (span.end - span.start).into())
-}
+impl From<ParseError> for miette::Error {
+    fn from(val: ParseError) -> Self {
+        let diagnostic = CfgError {
+            err_span: val
+                .span
+                .as_ref()
+                .map(|s| SourceSpan::new(s.start().into(), (s.end() - s.start()).into())),
+            help_msg: help(val.msg),
+            file_name: val.span.as_ref().map(|s| s.file_name()),
+            file_content: val.span.as_ref().map(|s| s.file_content()),
+        };
 
-pub(super) fn spanned_err_span<T>(spanned: &Spanned<T>) -> SourceSpan {
-    let span = spanned.span.clone();
-    SourceSpan::new(span.start.into(), (span.end - span.start).into())
-}
+        let report: miette::Error = diagnostic.into();
 
-pub(super) fn error_with_source(e: CfgError) -> miette::Error {
-    let filename = e.file_name.clone();
-    let source = e.file_content.clone();
-    let e2: miette::Error = e.into();
-    if let (Some(f), Some(s)) = (filename, source) {
-        e2.with_source_code(NamedSource::new(f, s))
-    } else {
-        e2
+        if let Some(span) = val.span {
+            report.with_source_code(NamedSource::new(span.file_name(), span.file_content()))
+        } else {
+            report
+        }
     }
 }
 
-impl From<anyhow::Error> for CfgError {
-    fn from(value: anyhow::Error) -> Self {
-        Self {
-            err_span: None,
-            help_msg: help(value.to_string()),
-            file_name: None,
-            file_content: None,
-        }
-    }
+#[derive(Error, Debug, Diagnostic, Clone)]
+#[error("Error in configuration")]
+#[diagnostic()]
+struct CfgError {
+    #[label("Error here")]
+    err_span: Option<SourceSpan>,
+    #[help]
+    help_msg: String,
+    file_name: Option<String>,
+    file_content: Option<String>,
+}
+
+pub(super) fn help(err_msg: impl AsRef<str>) -> String {
+    format!(
+        r"{}
+
+For more info, see the configuration guide:
+https://github.com/jtroo/kanata/blob/main/docs/config.adoc",
+        err_msg.as_ref(),
+    )
 }
diff --git a/parser/src/cfg/fake_key.rs b/parser/src/cfg/fake_key.rs
new file mode 100644
index 000000000..aacaa30ff
--- /dev/null
+++ b/parser/src/cfg/fake_key.rs
@@ -0,0 +1,388 @@
+use super::*;
+
+use crate::{anyhow_expr, bail, bail_expr};
+
+#[allow(unused_variables)]
+fn set_virtual_key_reference_lsp_hint(vk_name_expr: &SExpr, s: &ParserState) {
+    #[cfg(feature = "lsp")]
+    {
+        let atom = match vk_name_expr {
+            SExpr::Atom(x) => x,
+            SExpr::List(_) => unreachable!("should be validated to be atom earlier"),
+        };
+        s.lsp_hints
+            .borrow_mut()
+            .reference_locations
+            .virtual_key
+            .push_from_atom(atom);
+    }
+}
+
+pub(crate) fn parse_fake_keys(exprs: &[&Vec<SExpr>], s: &mut ParserState) -> Result<()> {
+    for expr in exprs {
+        let mut subexprs = check_first_expr(expr.iter(), "deffakekeys")?;
+        // Read k-v pairs from the configuration
+        while let Some(key_name_expr) = subexprs.next() {
+            let key_name = key_name_expr
+                .atom(s.vars())
+                .ok_or_else(|| anyhow_expr!(key_name_expr, "Fake key name must not be a list."))?
+                .to_owned();
+            let action = match subexprs.next() {
+                Some(v) => v,
+                None => bail_expr!(
+                    key_name_expr,
+                    "Fake key name has no action - you should add an action."
+                ),
+            };
+            let action = parse_action(action, s)?;
+            let idx = s.virtual_keys.len();
+            log::trace!("inserting {key_name}->{idx}:{action:?}");
+            if s.virtual_keys
+                .insert(key_name.clone(), (idx, action))
+                .is_some()
+            {
+                bail_expr!(key_name_expr, "Duplicate fake key: {}", key_name);
+            }
+            #[cfg(feature = "lsp")]
+            s.lsp_hints
+                .borrow_mut()
+                .definition_locations
+                .virtual_key
+                .insert(key_name, key_name_expr.span());
+        }
+    }
+    if s.virtual_keys.len() > KEYS_IN_ROW {
+        bail!(
+            "Maximum number of fake keys is {KEYS_IN_ROW}, found {}",
+            s.virtual_keys.len()
+        );
+    }
+    Ok(())
+}
+
+pub(crate) fn parse_virtual_keys(exprs: &[&Vec<SExpr>], s: &mut ParserState) -> Result<()> {
+    s.pctx.is_within_defvirtualkeys = true;
+    for expr in exprs {
+        let mut subexprs = check_first_expr(expr.iter(), "defvirtualkeys")?;
+        // Read k-v pairs from the configuration
+        while let Some(key_name_expr) = subexprs.next() {
+            let key_name = key_name_expr
+                .atom(s.vars())
+                .ok_or_else(|| anyhow_expr!(key_name_expr, "Virtual key name must not be a list."))?
+                .to_owned();
+            let action = match subexprs.next() {
+                Some(v) => v,
+                None => bail_expr!(
+                    key_name_expr,
+                    "Virtual key name has no action - you must add an action."
+                ),
+            };
+            let action = parse_action(action, s)?;
+            let idx = s.virtual_keys.len();
+            log::trace!("inserting {key_name}->{idx}:{action:?}");
+            if s.virtual_keys
+                .insert(key_name.clone(), (idx, action))
+                .is_some()
+            {
+                bail_expr!(key_name_expr, "Duplicate virtual key: {}", key_name);
+            };
+            #[cfg(feature = "lsp")]
+            s.lsp_hints
+                .borrow_mut()
+                .definition_locations
+                .virtual_key
+                .insert(key_name, key_name_expr.span());
+        }
+    }
+    s.pctx.is_within_defvirtualkeys = false;
+    if s.virtual_keys.len() > KEYS_IN_ROW {
+        bail!(
+            "Maximum number of virtual keys is {KEYS_IN_ROW}, found {}",
+            s.virtual_keys.len()
+        );
+    }
+    Ok(())
+}
+
+pub(crate) fn parse_on_press_fake_key_op(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let (coord, action) = parse_fake_key_op_coord_action(ac_params, s, ON_PRESS_FAKEKEY)?;
+    set_virtual_key_reference_lsp_hint(&ac_params[0], s);
+    custom(CustomAction::FakeKey { coord, action }, &s.a)
+}
+
+pub(crate) fn parse_on_release_fake_key_op(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let (coord, action) = parse_fake_key_op_coord_action(ac_params, s, ON_RELEASE_FAKEKEY)?;
+    set_virtual_key_reference_lsp_hint(&ac_params[0], s);
+    custom(CustomAction::FakeKeyOnRelease { coord, action }, &s.a)
+}
+
+pub(crate) fn parse_on_idle_fakekey(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "on-idle-fakekey expects three parameters:\n<fake key name> <(tap|press|release)> <idle time>\n";
+    if ac_params.len() != 3 {
+        bail!("{ERR_MSG}");
+    }
+    let y = match s
+        .virtual_keys
+        .get(ac_params[0].atom(s.vars()).ok_or_else(|| {
+            anyhow_expr!(
+                &ac_params[0],
+                "{ERR_MSG}\nInvalid first parameter: a fake key name cannot be a list",
+            )
+        })?) {
+        Some((y, _)) => *y as u16, // cast should be safe; checked in `parse_fake_keys`
+        None => bail_expr!(
+            &ac_params[0],
+            "{ERR_MSG}\nInvalid first parameter: unknown fake key name {:?}",
+            &ac_params[0]
+        ),
+    };
+    let action = ac_params[1]
+        .atom(s.vars())
+        .and_then(|a| match a {
+            "tap" => Some(FakeKeyAction::Tap),
+            "press" => Some(FakeKeyAction::Press),
+            "release" => Some(FakeKeyAction::Release),
+            _ => None,
+        })
+        .ok_or_else(|| {
+            anyhow_expr!(
+                &ac_params[1],
+                "{ERR_MSG}\nInvalid second parameter, it must be one of: tap, press, release",
+            )
+        })?;
+    let idle_duration = parse_u16(&ac_params[2], s, "idle time").map_err(|mut e| {
+        e.msg = format!("{ERR_MSG}\nInvalid third parameter: {}", e.msg);
+        e
+    })?;
+    let (x, y) = get_fake_key_coords(y);
+    let coord = Coord { x, y };
+    set_virtual_key_reference_lsp_hint(&ac_params[0], s);
+    custom(
+        CustomAction::FakeKeyOnIdle(FakeKeyOnIdle {
+            coord,
+            action,
+            idle_duration,
+        }),
+        &s.a,
+    )
+}
+
+fn parse_fake_key_op_coord_action(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    ac_name: &str,
+) -> Result<(Coord, FakeKeyAction)> {
+    const ERR_MSG: &str = "expects two parameters: <fake key name> <(tap|press|release|toggle)>";
+    if ac_params.len() != 2 {
+        bail!("{ac_name} {ERR_MSG}");
+    }
+    let y = match s
+        .virtual_keys
+        .get(ac_params[0].atom(s.vars()).ok_or_else(|| {
+            anyhow_expr!(
+                &ac_params[0],
+                "{ac_name} {ERR_MSG}\nInvalid first parameter: a fake key name cannot be a list",
+            )
+        })?) {
+        Some((y, _)) => *y as u16, // cast should be safe; checked in `parse_fake_keys`
+        None => bail_expr!(
+            &ac_params[0],
+            "{ac_name} {ERR_MSG}\nInvalid first parameter: unknown fake key name {:?}",
+            &ac_params[0]
+        ),
+    };
+    let action = ac_params[1]
+        .atom(s.vars())
+        .and_then(|a| match a {
+            "tap" => Some(FakeKeyAction::Tap),
+            "press" => Some(FakeKeyAction::Press),
+            "release" => Some(FakeKeyAction::Release),
+            "toggle" => Some(FakeKeyAction::Toggle),
+            _ => None,
+        })
+        .ok_or_else(|| {
+            anyhow_expr!(
+                &ac_params[1],
+                "{ERR_MSG}\nInvalid second parameter, it must be one of: tap, press, release",
+            )
+        })?;
+    let (x, y) = get_fake_key_coords(y);
+    set_virtual_key_reference_lsp_hint(&ac_params[0], s);
+    Ok((Coord { x, y }, action))
+}
+
+pub const NORMAL_KEY_ROW: u8 = 0;
+pub const FAKE_KEY_ROW: u8 = 1;
+
+pub(crate) fn get_fake_key_coords<T: Into<usize>>(y: T) -> (u8, u16) {
+    let y: usize = y.into();
+    (FAKE_KEY_ROW, y as u16)
+}
+
+pub(crate) fn parse_fake_key_delay(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    parse_delay(ac_params, false, s)
+}
+
+pub(crate) fn parse_on_release_fake_key_delay(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    parse_delay(ac_params, true, s)
+}
+
+fn parse_delay(
+    ac_params: &[SExpr],
+    is_release: bool,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "delay expects a single number (ms, 0-65535)";
+    let delay = ac_params[0]
+        .atom(s.vars())
+        .map(str::parse::<u16>)
+        .ok_or_else(|| anyhow!("{ERR_MSG}"))?
+        .map_err(|e| anyhow!("{ERR_MSG}: {e}"))?;
+    custom(
+        match is_release {
+            false => CustomAction::Delay(delay),
+            true => CustomAction::DelayOnRelease(delay),
+        },
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_vkey_coord(param: &SExpr, s: &ParserState) -> Result<Coord> {
+    let name = param
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(param, "key-name must not be a list",))?;
+    let y = match s.virtual_keys.get(name) {
+        Some((y, _)) => *y as u16, // cast should be safe; checked in `parse_fake_keys`
+        None => bail_expr!(param, "unknown virtual key name: {name}",),
+    };
+    let coord = Coord { x: FAKE_KEY_ROW, y };
+    set_virtual_key_reference_lsp_hint(param, s);
+    Ok(coord)
+}
+
+fn parse_vkey_action(param: &SExpr, s: &ParserState) -> Result<FakeKeyAction> {
+    let action = param
+        .atom(s.vars())
+        .and_then(|ac| {
+            Some(match ac {
+                "press-vkey" | "press-virtualkey" => FakeKeyAction::Press,
+                "release-vkey" | "release-virtualkey" => FakeKeyAction::Release,
+                "tap-vkey" | "tap-virtualkey" => FakeKeyAction::Tap,
+                "toggle-vkey" | "toggle-virtualkey" => FakeKeyAction::Toggle,
+                _ => return None,
+            })
+        })
+        .ok_or_else(|| {
+            anyhow_expr!(
+                param,
+                "action must be one of: (press|release|tap|toggle)-virtualkey\n\
+                 example: toggle-virtualkey"
+            )
+        })?;
+    Ok(action)
+}
+
+pub(crate) fn parse_on_press(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "on-press expects two parameters: <action> <key-name>";
+    if ac_params.len() != 2 {
+        bail!("{ERR_MSG}");
+    }
+    let action = parse_vkey_action(&ac_params[0], s)?;
+    let coord = parse_vkey_coord(&ac_params[1], s)?;
+
+    custom(CustomAction::FakeKey { coord, action }, &s.a)
+}
+
+pub(crate) fn parse_on_release(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "on-release expects two parameters: <action> <key-name>";
+    if ac_params.len() != 2 {
+        bail!("{ERR_MSG}");
+    }
+    let action = parse_vkey_action(&ac_params[0], s)?;
+    let coord = parse_vkey_coord(&ac_params[1], s)?;
+
+    custom(CustomAction::FakeKeyOnRelease { coord, action }, &s.a)
+}
+
+pub(crate) fn parse_on_idle(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "on-idle expects three parameters: <timeout> <action> <key-name>";
+    if ac_params.len() != 3 {
+        bail!("{ERR_MSG}");
+    }
+    let idle_duration = parse_non_zero_u16(&ac_params[0], s, "on-idle-timeout")?;
+    let action = parse_vkey_action(&ac_params[1], s)?;
+    let coord = parse_vkey_coord(&ac_params[2], s)?;
+
+    custom(
+        CustomAction::FakeKeyOnIdle(FakeKeyOnIdle {
+            coord,
+            action,
+            idle_duration,
+        }),
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_on_physical_idle(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str =
+        "on-physical-idle expects three parameters: <timeout> <action> <key-name>";
+    if ac_params.len() != 3 {
+        bail!("{ERR_MSG}");
+    }
+    let idle_duration = parse_non_zero_u16(&ac_params[0], s, "on-idle-timeout")?;
+    let action = parse_vkey_action(&ac_params[1], s)?;
+    let coord = parse_vkey_coord(&ac_params[2], s)?;
+
+    custom(
+        CustomAction::FakeKeyOnPhysicalIdle(FakeKeyOnIdle {
+            coord,
+            action,
+            idle_duration,
+        }),
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_hold_for_duration(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "hold-for-duration expects two parameters: <hold-duration> <key-name>";
+    if ac_params.len() != 2 {
+        bail!("{ERR_MSG}");
+    }
+    let hold_duration = parse_non_zero_u16(&ac_params[0], s, "hold-duration")?;
+    let coord = parse_vkey_coord(&ac_params[1], s)?;
+
+    custom(
+        CustomAction::FakeKeyHoldForDuration(FakeKeyHoldForDuration {
+            coord,
+            hold_duration,
+        }),
+        &s.a,
+    )
+}
diff --git a/parser/src/cfg/fork.rs b/parser/src/cfg/fork.rs
new file mode 100644
index 000000000..a8c5a74f9
--- /dev/null
+++ b/parser/src/cfg/fork.rs
@@ -0,0 +1,24 @@
+use super::*;
+
+use crate::bail;
+
+pub(crate) fn parse_fork(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_STR: &str =
+        "fork expects 3 params: <left-action> <right-action> <right-trigger-keys>";
+    if ac_params.len() != 3 {
+        bail!("{ERR_STR}\nFound {} params instead of 3", ac_params.len());
+    }
+    let left = *parse_action(&ac_params[0], s)?;
+    let right = *parse_action(&ac_params[1], s)?;
+    let right_triggers = s.a.sref_vec(
+        parse_key_list(&ac_params[2], s, "right-trigger-keys")?
+            .into_iter()
+            .map(KeyCode::from)
+            .collect::<Vec<_>>(),
+    );
+    Ok(s.a.sref(Action::Fork(s.a.sref(ForkConfig {
+        left,
+        right,
+        right_triggers,
+    }))))
+}
diff --git a/parser/src/cfg/is_a_button.rs b/parser/src/cfg/is_a_button.rs
new file mode 100644
index 000000000..373d90b0a
--- /dev/null
+++ b/parser/src/cfg/is_a_button.rs
@@ -0,0 +1,178 @@
+pub(crate) fn is_a_button(osc: u16) -> bool {
+    if cfg!(target_os = "windows") {
+        matches!(osc, 1..=6 | 256..)
+    } else {
+        osc >= 256
+    }
+}
+
+#[test]
+fn mouse_inputs_most_care_about_are_considered_buttons() {
+    use crate::keys::{OsCode, OsCode::*};
+    const MOUSE_INPUTS: &[OsCode] = &[
+        MouseWheelUp,
+        MouseWheelDown,
+        MouseWheelLeft,
+        MouseWheelRight,
+        BTN_LEFT,
+        BTN_RIGHT,
+        BTN_MIDDLE,
+        BTN_SIDE,
+        BTN_EXTRA,
+        BTN_FORWARD,
+        BTN_BACK,
+    ];
+    for input in MOUSE_INPUTS.iter().copied() {
+        println!("{input}");
+        assert!(is_a_button(input.into()));
+    }
+}
+
+#[test]
+fn standard_keys_are_not_considered_buttons() {
+    use crate::keys::{OsCode, OsCode::*};
+    const KEY_INPUTS: &[OsCode] = &[
+        KEY_0,
+        KEY_1,
+        KEY_2,
+        KEY_3,
+        KEY_4,
+        KEY_5,
+        KEY_6,
+        KEY_7,
+        KEY_8,
+        KEY_9,
+        KEY_A,
+        KEY_B,
+        KEY_C,
+        KEY_D,
+        KEY_E,
+        KEY_F,
+        KEY_G,
+        KEY_H,
+        KEY_I,
+        KEY_J,
+        KEY_K,
+        KEY_L,
+        KEY_M,
+        KEY_N,
+        KEY_O,
+        KEY_P,
+        KEY_Q,
+        KEY_R,
+        KEY_S,
+        KEY_T,
+        KEY_U,
+        KEY_V,
+        KEY_W,
+        KEY_X,
+        KEY_Y,
+        KEY_Z,
+        KEY_SEMICOLON,
+        KEY_SLASH,
+        KEY_GRAVE,
+        KEY_LEFTBRACE,
+        KEY_BACKSLASH,
+        KEY_RIGHTBRACE,
+        KEY_APOSTROPHE,
+        KEY_MINUS,
+        KEY_DOT,
+        KEY_EQUAL,
+        KEY_BACKSPACE,
+        KEY_ESC,
+        KEY_TAB,
+        KEY_ENTER,
+        KEY_LEFTCTRL,
+        KEY_LEFTSHIFT,
+        KEY_COMMA,
+        KEY_RIGHTSHIFT,
+        KEY_KPASTERISK,
+        KEY_LEFTALT,
+        KEY_SPACE,
+        KEY_CAPSLOCK,
+        KEY_F1,
+        KEY_F2,
+        KEY_F3,
+        KEY_F4,
+        KEY_F5,
+        KEY_F6,
+        KEY_F7,
+        KEY_F8,
+        KEY_F9,
+        KEY_F10,
+        KEY_F11,
+        KEY_F12,
+        KEY_NUMLOCK,
+        KEY_SCROLLLOCK,
+        KEY_KP0,
+        KEY_KP1,
+        KEY_KP2,
+        KEY_KP3,
+        KEY_KP4,
+        KEY_KP5,
+        KEY_KP6,
+        KEY_KP7,
+        KEY_KP8,
+        KEY_KP9,
+        KEY_KPMINUS,
+        KEY_KPPLUS,
+        KEY_KPDOT,
+        KEY_KPENTER,
+        KEY_RIGHTCTRL,
+        KEY_KPSLASH,
+        KEY_RIGHTALT,
+        KEY_HOME,
+        KEY_UP,
+        KEY_PAGEUP,
+        KEY_LEFT,
+        KEY_RIGHT,
+        KEY_END,
+        KEY_DOWN,
+        KEY_PAGEDOWN,
+        KEY_INSERT,
+        KEY_DELETE,
+        KEY_MUTE,
+        KEY_VOLUMEDOWN,
+        KEY_VOLUMEUP,
+        KEY_EJECTCD,
+        KEY_PAUSE,
+        KEY_LEFTMETA,
+        KEY_RIGHTMETA,
+        KEY_COMPOSE,
+        KEY_BACK,
+        KEY_FORWARD,
+        KEY_NEXTSONG,
+        KEY_PLAYPAUSE,
+        KEY_PREVIOUSSONG,
+        KEY_STOP,
+        KEY_HOMEPAGE,
+        KEY_MAIL,
+        KEY_MEDIA,
+        KEY_REFRESH,
+        KEY_F13,
+        KEY_F14,
+        KEY_F15,
+        KEY_F16,
+        KEY_F17,
+        KEY_F18,
+        KEY_F19,
+        KEY_F20,
+        KEY_F21,
+        KEY_F22,
+        KEY_F23,
+        KEY_F24,
+        KEY_HANGEUL,
+        KEY_HANJA,
+        KEY_252,
+        KEY_102ND,
+        KEY_PLAY,
+        KEY_PRINT,
+        KEY_SEARCH,
+        KEY_RO,
+        KEY_HENKAN,
+        KEY_MUHENKAN,
+    ];
+    for input in KEY_INPUTS.iter().copied() {
+        assert!(!is_a_button(input.into()));
+    }
+}
diff --git a/parser/src/cfg/key_outputs.rs b/parser/src/cfg/key_outputs.rs
new file mode 100644
index 000000000..8acd0e9b7
--- /dev/null
+++ b/parser/src/cfg/key_outputs.rs
@@ -0,0 +1,162 @@
+use super::*;
+
+// Note: this uses a Vec inside the HashMap instead of a HashSet because ordering matters, e.g. for
+// chords like `S-b`, we want to ensure that `b` is checked first because key repeat for `b` is
+// useful while it is not useful for shift. The outputs should be iterated over in reverse order.
+pub type KeyOutputs = Vec<HashMap<OsCode, Vec<OsCode>>>;
+
+/// Creates a `KeyOutputs` from `layers::LAYERS`.
+pub(crate) fn create_key_outputs(
+    layers: &KLayers,
+    overrides: &Overrides,
+    chords_v2: &Option<ChordsV2<'static, KanataCustom>>,
+) -> KeyOutputs {
+    let mut outs = KeyOutputs::new();
+    for (layer_idx, layer) in layers.iter().enumerate() {
+        let mut layer_outputs = HashMap::default();
+        for (i, action) in layer[0].iter().enumerate() {
+            let osc_slot = match i.try_into() {
+                Ok(i) => i,
+                Err(_) => continue,
+            };
+            add_key_output_from_action_to_key_pos(osc_slot, action, &mut layer_outputs, overrides);
+            add_chordsv2_output_for_key_pos(
+                osc_slot,
+                layer_idx,
+                chords_v2,
+                &mut layer_outputs,
+                overrides,
+            );
+        }
+        outs.push(layer_outputs);
+    }
+    for layer_outs in outs.iter_mut() {
+        for keys_out in layer_outs.values_mut() {
+            keys_out.shrink_to_fit();
+        }
+        layer_outs.shrink_to_fit();
+    }
+    outs.shrink_to_fit();
+    outs
+}
+
+pub(crate) fn add_chordsv2_output_for_key_pos(
+    osc_slot: OsCode,
+    layer_idx: usize,
+    chords_v2: &Option<ChordsV2<'static, KanataCustom>>,
+    outputs: &mut HashMap<OsCode, Vec<OsCode>>,
+    overrides: &Overrides,
+) {
+    assert!(layer_idx <= usize::from(u16::MAX));
+    let Some(chords_v2) = chords_v2.as_ref() else {
+        return;
+    };
+    let Some(chords_for_key) = chords_v2.chords().mapping.get(&u16::from(osc_slot)) else {
+        return;
+    };
+    for chord in chords_for_key.chords.iter() {
+        if !chord.disabled_layers.contains(&(layer_idx as u16)) {
+            add_key_output_from_action_to_key_pos(osc_slot, chord.action, outputs, overrides);
+        }
+    }
+}
+
+pub(crate) fn add_key_output_from_action_to_key_pos(
+    osc_slot: OsCode,
+    action: &KanataAction,
+    outputs: &mut HashMap<OsCode, Vec<OsCode>>,
+    overrides: &Overrides,
+) {
+    match action {
+        Action::KeyCode(kc) => {
+            add_kc_output(osc_slot, kc.into(), outputs, overrides);
+        }
+        Action::HoldTap(HoldTapAction {
+            tap,
+            hold,
+            timeout_action,
+            ..
+        }) => {
+            add_key_output_from_action_to_key_pos(osc_slot, tap, outputs, overrides);
+            add_key_output_from_action_to_key_pos(osc_slot, hold, outputs, overrides);
+            add_key_output_from_action_to_key_pos(osc_slot, timeout_action, outputs, overrides);
+        }
+        Action::OneShot(OneShot { action: ac, .. }) => {
+            add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
+        }
+        Action::MultipleKeyCodes(kcs) => {
+            for kc in kcs.iter() {
+                add_kc_output(osc_slot, kc.into(), outputs, overrides);
+            }
+        }
+        Action::MultipleActions(actions) => {
+            for ac in actions.iter() {
+                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
+            }
+        }
+        Action::TapDance(TapDance { actions, .. }) => {
+            for ac in actions.iter() {
+                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
+            }
+        }
+        Action::Fork(ForkConfig { left, right, .. }) => {
+            add_key_output_from_action_to_key_pos(osc_slot, left, outputs, overrides);
+            add_key_output_from_action_to_key_pos(osc_slot, right, outputs, overrides);
+        }
+        Action::Chords(ChordsGroup { chords, .. }) => {
+            for (_, ac) in chords.iter() {
+                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
+            }
+        }
+        Action::Switch(Switch { cases, .. }) => {
+            for case in cases.iter() {
+                add_key_output_from_action_to_key_pos(osc_slot, case.1, outputs, overrides);
+            }
+        }
+        Action::Custom(ac) => match ac {
+            CustomAction::Unmodded { keys, .. } | CustomAction::Unshifted { keys } => {
+                for k in keys.iter() {
+                    add_kc_output(osc_slot, k.into(), outputs, overrides);
+                }
+            }
+            _ => {}
+        },
+        Action::Src => {
+            add_kc_output(osc_slot, osc_slot, outputs, overrides);
+        }
+        Action::NoOp
+        | Action::Trans
+        | Action::Repeat
+        | Action::Layer(_)
+        | Action::DefaultLayer(_)
+        | Action::Sequence { .. }
+        | Action::RepeatableSequence { .. }
+        | Action::CancelSequences
+        | Action::OneShotIgnoreEventsTicks(_)
+        | Action::ReleaseState(_) => {}
+    };
+}
+
+pub(crate) fn add_kc_output(
+    osc_slot: OsCode,
+    osc: OsCode,
+    outs: &mut HashMap<OsCode, Vec<OsCode>>,
+    overrides: &Overrides,
+) {
+    let outputs = match outs.entry(osc_slot) {
+        Entry::Occupied(o) => o.into_mut(),
+        Entry::Vacant(v) => v.insert(vec![]),
+    };
+    if !outputs.contains(&osc) {
+        outputs.push(osc);
+    }
+    for ov_osc in overrides
+        .output_non_mods_for_input_non_mod(osc)
+        .iter()
+        .copied()
+    {
+        if !outputs.contains(&ov_osc) {
+            outputs.push(ov_osc);
+        }
+    }
+}
diff --git a/parser/src/cfg/key_override.rs b/parser/src/cfg/key_override.rs
index b485b390f..bd31354c2 100644
--- a/parser/src/cfg/key_override.rs
+++ b/parser/src/cfg/key_override.rs
@@ -1,11 +1,15 @@
 //! Contains code to handle global override keys.
 
-use anyhow::{anyhow, bail, Result};
+use anyhow::{Result, anyhow, bail};
 use rustc_hash::FxHashMap as HashMap;
 
-use super::KeyCode;
 use crate::keys::*;
 
+use kanata_keyberon::key_code::KeyCode;
+use kanata_keyberon::layout::NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION;
+use kanata_keyberon::layout::NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE;
+use kanata_keyberon::layout::State;
+
 /// Scratch space containing allocations used to process override information. Exists as an
 /// optimization to reuse allocations between iterations.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
@@ -15,6 +19,12 @@ pub struct OverrideStates {
     oscs_to_add: Vec<OsCode>,
 }
 
+impl Default for OverrideStates {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl OverrideStates {
     pub fn new() -> Self {
         Self {
@@ -30,7 +40,7 @@ impl OverrideStates {
         self.mods_pressed = 0;
     }
 
-    fn update(&mut self, osc: OsCode, overrides: &Overrides) {
+    fn update(&mut self, osc: OsCode, overrides: &Overrides, active_layer: u16) {
         if let Some(mod_mask) = mask_for_key(osc) {
             self.mods_pressed |= mod_mask;
         } else {
@@ -39,6 +49,7 @@ impl OverrideStates {
                 self.mods_pressed,
                 &mut self.oscs_to_add,
                 &mut self.oscs_to_remove,
+                active_layer,
             );
         }
     }
@@ -50,6 +61,10 @@ impl OverrideStates {
     fn add_overrides(&self, oscs: &mut Vec<KeyCode>) {
         oscs.extend(self.oscs_to_add.iter().copied().map(KeyCode::from));
     }
+
+    pub fn removed_oscs(&self) -> impl Iterator<Item = OsCode> + '_ {
+        self.oscs_to_remove.iter().copied()
+    }
 }
 
 /// A collection of global key overrides.
@@ -74,16 +89,21 @@ impl Overrides {
         Self { overrides_by_osc }
     }
 
-    pub fn override_keys(&self, kcs: &mut Vec<KeyCode>, states: &mut OverrideStates) {
+    pub fn override_keys(
+        &self,
+        kcs: &mut Vec<KeyCode>,
+        states: &mut OverrideStates,
+        active_layer: u16,
+    ) {
         if self.is_empty() {
             return;
         }
+        states.cleanup();
         for kc in kcs.iter().copied() {
-            states.update(kc.into(), self);
+            states.update(kc.into(), self, active_layer);
         }
         kcs.retain(|kc| !states.is_key_overridden((*kc).into()));
         states.add_overrides(kcs);
-        states.cleanup();
     }
 
     pub fn output_non_mods_for_input_non_mod(&self, in_osc: OsCode) -> Vec<OsCode> {
@@ -106,30 +126,24 @@ impl Overrides {
         active_mod_mask: u8,
         oscs_to_add: &mut Vec<OsCode>,
         oscs_to_remove: &mut Vec<OsCode>,
+        active_layer: u16,
     ) {
         let Some(ovds) = self.overrides_by_osc.get(&active_osc) else {
             return;
         };
-        let mut cur_chord_size = 0;
-        if let Some(ovd) = ovds
-            .iter()
-            .filter(|ovd| {
-                let mask = ovd.get_mod_mask();
-                if mask & active_mod_mask == mask {
-                    // keep only the longest matching prefix.
-                    let chord_size = ovd.in_mod_oscs.len() + 1;
-                    if chord_size <= cur_chord_size {
-                        false
-                    } else {
-                        cur_chord_size = chord_size;
-                        true
-                    }
-                } else {
-                    false
-                }
-            })
-            .last()
-        {
+        if let Some(ovd) = ovds.iter().rfind(|ovd| {
+            if ovd
+                .excluded_layers
+                .as_ref()
+                .map(|excluded_layers| excluded_layers.iter().copied().any(|l| l == active_layer))
+                .unwrap_or(false)
+            {
+                return false;
+            }
+            let mask = ovd.get_mod_mask();
+            let exclude_mask = ovd.get_excluded_mod_mask();
+            mask & active_mod_mask == mask && exclude_mask & active_mod_mask == 0
+        }) {
             log::debug!("using override {ovd:?}");
             ovd.add_override_keys(oscs_to_add);
             ovd.add_removed_keys(oscs_to_remove);
@@ -142,8 +156,10 @@ impl Overrides {
 pub struct Override {
     in_non_mod_osc: OsCode,
     out_non_mod_osc: OsCode,
-    in_mod_oscs: Vec<OsCode>,
-    out_mod_oscs: Vec<OsCode>,
+    in_mod_oscs: Box<[OsCode]>,
+    out_mod_oscs: Box<[OsCode]>,
+    excluded_mod_oscs: Option<Box<[OsCode]>>,
+    excluded_layers: Option<Box<[u16]>>,
 }
 
 impl Override {
@@ -168,26 +184,38 @@ impl Override {
         if out_nmoscs.next().is_some() {
             bail!("override must contain exactly one output non-modifier key; found multiple");
         }
-        let mut in_mod_oscs = in_oscs
+        let in_mod_oscs = in_oscs
             .iter()
             .copied()
-            .filter(|osc| mask_for_key(*osc).is_some())
+            .filter(|osc| osc.is_modifier())
             .collect::<Vec<_>>();
-        let mut out_mod_oscs = out_oscs
+        let out_mod_oscs = out_oscs
             .iter()
             .copied()
-            .filter(|osc| mask_for_key(*osc).is_some())
+            .filter(|osc| osc.is_modifier())
             .collect::<Vec<_>>();
-        in_mod_oscs.shrink_to_fit();
-        out_mod_oscs.shrink_to_fit();
         Ok(Self {
             in_non_mod_osc,
             out_non_mod_osc,
-            in_mod_oscs,
-            out_mod_oscs,
+            in_mod_oscs: in_mod_oscs.into_boxed_slice(),
+            out_mod_oscs: out_mod_oscs.into_boxed_slice(),
+            excluded_mod_oscs: None,
+            excluded_layers: None,
         })
     }
 
+    pub fn try_new_v2(
+        in_oscs: &[OsCode],
+        out_oscs: &[OsCode],
+        excluded_mod_oscs: Box<[OsCode]>,
+        excluded_layers: Box<[u16]>,
+    ) -> Result<Self> {
+        let mut override_cfg = Self::try_new(in_oscs, out_oscs)?;
+        override_cfg.excluded_mod_oscs = Some(excluded_mod_oscs);
+        override_cfg.excluded_layers = Some(excluded_layers);
+        Ok(override_cfg)
+    }
+
     fn get_mod_mask(&self) -> u8 {
         let mut mask = 0;
         for osc in self.in_mod_oscs.iter().copied() {
@@ -196,6 +224,16 @@ impl Override {
         mask
     }
 
+    fn get_excluded_mod_mask(&self) -> u8 {
+        let mut mask = 0;
+        if let Some(mods) = self.excluded_mod_oscs.as_ref() {
+            for osc in mods.iter().copied() {
+                mask |= mask_for_key(osc).expect("mod only");
+            }
+        }
+        mask
+    }
+
     fn add_override_keys(&self, oscs_to_add: &mut Vec<OsCode>) {
         for osc in self.out_mod_oscs.iter().copied() {
             if !oscs_to_add.contains(&osc) {
@@ -232,3 +270,37 @@ fn mask_for_key(osc: OsCode) -> Option<u8> {
         _ => None,
     }
 }
+
+/// For every `OsCode` marked for removal by overrides that is not a modifier,
+/// mark its state in the keyberon layout
+/// with `NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION` and `NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE`
+/// so that it gets eagerly cleared, avoiding weird character outputs.
+pub fn mark_overridden_nonmodkeys_for_eager_erasure<T>(
+    override_states: &OverrideStates,
+    kb_states: &mut [State<T>],
+) {
+    for osc_to_mark in override_states
+        .removed_oscs()
+        .filter(|osc| !osc.is_modifier())
+    {
+        let kc: KeyCode = osc_to_mark.into();
+        for kbstate in kb_states.iter_mut() {
+            if let State::NormalKey {
+                mut flags,
+                keycode,
+                coord,
+            } = kbstate
+            {
+                if kc == *keycode {
+                    flags.0 |= NORMAL_KEY_FLAG_CLEAR_ON_NEXT_ACTION
+                        | NORMAL_KEY_FLAG_CLEAR_ON_NEXT_RELEASE;
+                    *kbstate = State::NormalKey {
+                        flags,
+                        keycode: *keycode,
+                        coord: *coord,
+                    };
+                }
+            }
+        }
+    }
+}
diff --git a/parser/src/cfg/layer_opts.rs b/parser/src/cfg/layer_opts.rs
new file mode 100644
index 000000000..55847944a
--- /dev/null
+++ b/parser/src/cfg/layer_opts.rs
@@ -0,0 +1,49 @@
+use crate::cfg::*;
+use crate::*;
+
+pub(crate) const DEFLAYER_ICON: [&str; 3] = ["icon", "🖻", "🖼"];
+pub(crate) type LayerIcons = HashMap<String, Option<String>>;
+
+pub fn parse_layer_opts(list: &[SExpr]) -> Result<HashMap<String, String>> {
+    let mut layer_opts: HashMap<String, String> = HashMap::default();
+    let mut opts = list.chunks_exact(2);
+    for kv in opts.by_ref() {
+        let key_expr = &kv[0];
+        let val_expr = &kv[1];
+        // Read k-v pairs from the configuration
+        // todo: add hashmap for future options, currently only parse icons
+        let opt_key = key_expr.atom(None)
+            .ok_or_else(|| anyhow_expr!(key_expr, "No lists are allowed in {DEFLAYER} options"))
+            .and_then(|opt_key| {
+                if DEFLAYER_ICON.contains(&opt_key) {
+                    if layer_opts.contains_key(DEFLAYER_ICON[0]) {
+                        // separate dupe check since multi-keys are stored
+                        // with one "canonical" repr, so '🖻' → 'icon'
+                        // and this info will be lost after the loop
+                        bail_expr!(
+                            key_expr,
+                            "Duplicate option found in {DEFLAYER}: {opt_key}, one of {DEFLAYER_ICON:?} already exists"
+                        );
+                    }
+                    Ok(DEFLAYER_ICON[0])
+                } else {
+                    bail_expr!(key_expr, "Invalid option in {DEFLAYER}: {opt_key}, expected one of {DEFLAYER_ICON:?}")
+                }
+            })?;
+        if layer_opts.contains_key(opt_key) {
+            bail_expr!(key_expr, "Duplicate option found in {DEFLAYER}: {opt_key}");
+        }
+        let opt_val = val_expr.atom(None).ok_or_else(|| {
+            anyhow_expr!(
+                val_expr,
+                "No lists are allowed in {DEFLAYER}'s option values"
+            )
+        })?;
+        layer_opts.insert(opt_key.to_owned(), opt_val.to_owned());
+    }
+    let rem = opts.remainder();
+    if !rem.is_empty() {
+        bail_expr!(&rem[0], "This option is missing a value.");
+    }
+    Ok(layer_opts)
+}
diff --git a/parser/src/cfg/list_actions.rs b/parser/src/cfg/list_actions.rs
new file mode 100644
index 000000000..5f376d106
--- /dev/null
+++ b/parser/src/cfg/list_actions.rs
@@ -0,0 +1,284 @@
+//! Contains all list action names and a function to check that an action name is that of a list
+//! action.
+
+// Note: changing any of these constants is a breaking change.
+pub const LAYER_SWITCH: &str = "layer-switch";
+pub const LAYER_TOGGLE: &str = "layer-toggle";
+pub const LAYER_WHILE_HELD: &str = "layer-while-held";
+pub const TAP_HOLD: &str = "tap-hold";
+pub const TAP_HOLD_PRESS: &str = "tap-hold-press";
+pub const TAP_HOLD_PRESS_A: &str = "tap⬓↓";
+pub const TAP_HOLD_RELEASE: &str = "tap-hold-release";
+pub const TAP_HOLD_RELEASE_A: &str = "tap⬓↑";
+pub const TAP_HOLD_PRESS_TIMEOUT: &str = "tap-hold-press-timeout";
+pub const TAP_HOLD_PRESS_TIMEOUT_A: &str = "tap⬓↓timeout";
+pub const TAP_HOLD_RELEASE_TIMEOUT: &str = "tap-hold-release-timeout";
+pub const TAP_HOLD_RELEASE_TIMEOUT_A: &str = "tap⬓↑timeout";
+pub const TAP_HOLD_RELEASE_KEYS: &str = "tap-hold-release-keys";
+pub const TAP_HOLD_RELEASE_KEYS_TAP_RELEASE: &str = "tap-hold-release-tap-keys-release";
+pub const TAP_HOLD_RELEASE_KEYS_A: &str = "tap⬓↑keys";
+pub const TAP_HOLD_EXCEPT_KEYS: &str = "tap-hold-except-keys";
+pub const TAP_HOLD_EXCEPT_KEYS_A: &str = "tap⬓⤫keys";
+pub const TAP_HOLD_TAP_KEYS: &str = "tap-hold-tap-keys";
+pub const TAP_HOLD_TAP_KEYS_A: &str = "tap⬓tapkeys";
+pub const TAP_HOLD_KEYS: &str = "tap-hold-keys";
+pub const MULTI: &str = "multi";
+pub const MACRO: &str = "macro";
+pub const MACRO_REPEAT: &str = "macro-repeat";
+pub const MACRO_REPEAT_A: &str = "macro⟳";
+pub const MACRO_RELEASE_CANCEL: &str = "macro-release-cancel";
+pub const MACRO_RELEASE_CANCEL_A: &str = "macro↑⤫";
+pub const MACRO_REPEAT_RELEASE_CANCEL: &str = "macro-repeat-release-cancel";
+pub const MACRO_REPEAT_RELEASE_CANCEL_A: &str = "macro⟳↑⤫";
+pub const MACRO_CANCEL_ON_NEXT_PRESS: &str = "macro-cancel-on-press";
+pub const MACRO_REPEAT_CANCEL_ON_NEXT_PRESS: &str = "macro-repeat-cancel-on-press";
+pub const MACRO_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE: &str =
+    "macro-release-cancel-and-cancel-on-press";
+pub const MACRO_REPEAT_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE: &str =
+    "macro-repeat-release-cancel-and-cancel-on-press";
+pub const UNICODE: &str = "unicode";
+pub const SYM: &str = "🔣";
+pub const ONE_SHOT: &str = "one-shot";
+pub const ONE_SHOT_PRESS: &str = "one-shot-press";
+pub const ONE_SHOT_PRESS_A: &str = "one-shot↓";
+pub const ONE_SHOT_RELEASE: &str = "one-shot-release";
+pub const ONE_SHOT_RELEASE_A: &str = "one-shot↑";
+pub const ONE_SHOT_PRESS_PCANCEL: &str = "one-shot-press-pcancel";
+pub const ONE_SHOT_PRESS_PCANCEL_A: &str = "one-shot↓⤫";
+pub const ONE_SHOT_RELEASE_PCANCEL: &str = "one-shot-release-pcancel";
+pub const ONE_SHOT_RELEASE_PCANCEL_A: &str = "one-shot↑⤫";
+pub const ONE_SHOT_PAUSE_PROCESSING: &str = "one-shot-pause-processing";
+pub const TAP_DANCE: &str = "tap-dance";
+pub const TAP_DANCE_EAGER: &str = "tap-dance-eager";
+pub const CHORD: &str = "chord";
+pub const RELEASE_KEY: &str = "release-key";
+pub const RELEASE_KEY_A: &str = "key↑";
+pub const RELEASE_LAYER: &str = "release-layer";
+pub const RELEASE_LAYER_A: &str = "layer↑";
+pub const ON_PRESS_FAKEKEY: &str = "on-press-fakekey";
+pub const ON_PRESS_FAKEKEY_A: &str = "on↓fakekey";
+pub const ON_RELEASE_FAKEKEY: &str = "on-release-fakekey";
+pub const ON_RELEASE_FAKEKEY_A: &str = "on↑fakekey";
+pub const ON_PRESS_DELAY: &str = "on-press-delay";
+pub const ON_RELEASE_DELAY: &str = "on-release-delay";
+pub const ON_PRESS_FAKEKEY_DELAY: &str = "on-press-fakekey-delay";
+pub const ON_PRESS_FAKEKEY_DELAY_A: &str = "on↓fakekey-delay";
+pub const ON_RELEASE_FAKEKEY_DELAY: &str = "on-release-fakekey-delay";
+pub const ON_RELEASE_FAKEKEY_DELAY_A: &str = "on↑fakekey-delay";
+pub const ON_IDLE_FAKEKEY: &str = "on-idle-fakekey";
+pub const MWHEEL_UP: &str = "mwheel-up";
+pub const MWHEEL_DOWN: &str = "mwheel-down";
+pub const MWHEEL_LEFT: &str = "mwheel-left";
+pub const MWHEEL_RIGHT: &str = "mwheel-right";
+pub const MWHEEL_UP_A: &str = "🖱☸↑";
+pub const MWHEEL_DOWN_A: &str = "🖱☸↓";
+pub const MWHEEL_LEFT_A: &str = "🖱☸←";
+pub const MWHEEL_RIGHT_A: &str = "🖱☸→";
+pub const MWHEEL_ACCEL_UP: &str = "mwheel-accel-up";
+pub const MWHEEL_ACCEL_DOWN: &str = "mwheel-accel-down";
+pub const MWHEEL_ACCEL_LEFT: &str = "mwheel-accel-left";
+pub const MWHEEL_ACCEL_RIGHT: &str = "mwheel-accel-right";
+pub const MOVEMOUSE_UP: &str = "movemouse-up";
+pub const MOVEMOUSE_DOWN: &str = "movemouse-down";
+pub const MOVEMOUSE_LEFT: &str = "movemouse-left";
+pub const MOVEMOUSE_RIGHT: &str = "movemouse-right";
+pub const MOVEMOUSE_ACCEL_UP: &str = "movemouse-accel-up";
+pub const MOVEMOUSE_ACCEL_DOWN: &str = "movemouse-accel-down";
+pub const MOVEMOUSE_ACCEL_LEFT: &str = "movemouse-accel-left";
+pub const MOVEMOUSE_ACCEL_RIGHT: &str = "movemouse-accel-right";
+pub const MOVEMOUSE_SPEED: &str = "movemouse-speed";
+pub const MOVEMOUSE_UP_A: &str = "🖱↑";
+pub const MOVEMOUSE_DOWN_A: &str = "🖱↓";
+pub const MOVEMOUSE_LEFT_A: &str = "🖱←";
+pub const MOVEMOUSE_RIGHT_A: &str = "🖱→";
+pub const MOVEMOUSE_ACCEL_UP_A: &str = "🖱accel↑";
+pub const MOVEMOUSE_ACCEL_DOWN_A: &str = "🖱accel↓";
+pub const MOVEMOUSE_ACCEL_LEFT_A: &str = "🖱accel←";
+pub const MOVEMOUSE_ACCEL_RIGHT_A: &str = "🖱accel→";
+pub const MOVEMOUSE_SPEED_A: &str = "🖱speed";
+pub const SETMOUSE: &str = "setmouse";
+pub const SETMOUSE_A: &str = "set🖱";
+pub const DYNAMIC_MACRO_RECORD: &str = "dynamic-macro-record";
+pub const DYNAMIC_MACRO_PLAY: &str = "dynamic-macro-play";
+pub const ARBITRARY_CODE: &str = "arbitrary-code";
+pub const CMD: &str = "cmd";
+pub const CMD_LOG: &str = "cmd-log";
+pub const PUSH_MESSAGE: &str = "push-msg";
+pub const CMD_OUTPUT_KEYS: &str = "cmd-output-keys";
+pub const FORK: &str = "fork";
+pub const CAPS_WORD: &str = "caps-word";
+pub const CAPS_WORD_A: &str = "word⇪";
+pub const CAPS_WORD_CUSTOM: &str = "caps-word-custom";
+pub const CAPS_WORD_CUSTOM_A: &str = "word⇪custom";
+pub const CAPS_WORD_TOGGLE: &str = "caps-word-toggle";
+pub const CAPS_WORD_TOGGLE_A: &str = "word⇪toggle";
+pub const CAPS_WORD_CUSTOM_TOGGLE: &str = "caps-word-custom-toggle";
+pub const CAPS_WORD_CUSTOM_TOGGLE_A: &str = "word⇪custom-toggle";
+pub const DYNAMIC_MACRO_RECORD_STOP_TRUNCATE: &str = "dynamic-macro-record-stop-truncate";
+pub const SWITCH: &str = "switch";
+pub const SEQUENCE: &str = "sequence";
+pub const SEQUENCE_NOERASE: &str = "sequence-noerase";
+pub const UNMOD: &str = "unmod";
+pub const UNSHIFT: &str = "unshift";
+pub const UNSHIFT_A: &str = "un⇧";
+pub const LIVE_RELOAD_NUM: &str = "lrld-num";
+pub const LIVE_RELOAD_FILE: &str = "lrld-file";
+pub const ON_PRESS: &str = "on-press";
+pub const ON_PRESS_A: &str = "on↓";
+pub const ON_RELEASE: &str = "on-release";
+pub const ON_RELEASE_A: &str = "on↑";
+pub const ON_IDLE: &str = "on-idle";
+pub const ON_PHYSICAL_IDLE: &str = "on-physical-idle";
+pub const HOLD_FOR_DURATION: &str = "hold-for-duration";
+pub const CLIPBOARD_SET: &str = "clipboard-set";
+pub const CLIPBOARD_CMD_SET: &str = "clipboard-cmd-set";
+pub const CLIPBOARD_SAVE: &str = "clipboard-save";
+pub const CLIPBOARD_RESTORE: &str = "clipboard-restore";
+pub const CLIPBOARD_SAVE_SET: &str = "clipboard-save-set";
+pub const CLIPBOARD_SAVE_CMD_SET: &str = "clipboard-save-cmd-set";
+pub const CLIPBOARD_SAVE_SWAP: &str = "clipboard-save-swap";
+pub const TAP_HOLD_ORDER: &str = "tap-hold-order";
+pub const TAP_HOLD_OPPOSITE_HAND: &str = "tap-hold-opposite-hand";
+pub const TAP_HOLD_OPPOSITE_HAND_RELEASE: &str = "tap-hold-opposite-hand-release";
+
+pub fn is_list_action(ac: &str) -> bool {
+    const LIST_ACTIONS: &[&str] = &[
+        LAYER_SWITCH,
+        LAYER_TOGGLE,
+        LAYER_WHILE_HELD,
+        TAP_HOLD,
+        TAP_HOLD_PRESS,
+        TAP_HOLD_PRESS_A,
+        TAP_HOLD_RELEASE,
+        TAP_HOLD_RELEASE_A,
+        TAP_HOLD_PRESS_TIMEOUT,
+        TAP_HOLD_PRESS_TIMEOUT_A,
+        TAP_HOLD_RELEASE_TIMEOUT,
+        TAP_HOLD_RELEASE_TIMEOUT_A,
+        TAP_HOLD_RELEASE_KEYS,
+        TAP_HOLD_RELEASE_KEYS_TAP_RELEASE,
+        TAP_HOLD_RELEASE_KEYS_A,
+        TAP_HOLD_EXCEPT_KEYS,
+        TAP_HOLD_EXCEPT_KEYS_A,
+        TAP_HOLD_TAP_KEYS,
+        TAP_HOLD_TAP_KEYS_A,
+        TAP_HOLD_KEYS,
+        MULTI,
+        MACRO,
+        MACRO_REPEAT,
+        MACRO_REPEAT_A,
+        MACRO_RELEASE_CANCEL,
+        MACRO_RELEASE_CANCEL_A,
+        MACRO_REPEAT_RELEASE_CANCEL,
+        MACRO_REPEAT_RELEASE_CANCEL_A,
+        UNICODE,
+        SYM,
+        ONE_SHOT,
+        ONE_SHOT_PRESS,
+        ONE_SHOT_PRESS_A,
+        ONE_SHOT_RELEASE,
+        ONE_SHOT_RELEASE_A,
+        ONE_SHOT_PRESS_PCANCEL,
+        ONE_SHOT_PRESS_PCANCEL_A,
+        ONE_SHOT_RELEASE_PCANCEL,
+        ONE_SHOT_RELEASE_PCANCEL_A,
+        TAP_DANCE,
+        TAP_DANCE_EAGER,
+        CHORD,
+        RELEASE_KEY,
+        RELEASE_KEY_A,
+        RELEASE_LAYER,
+        RELEASE_LAYER_A,
+        ON_PRESS_FAKEKEY,
+        ON_PRESS_FAKEKEY_A,
+        ON_RELEASE_FAKEKEY,
+        ON_RELEASE_FAKEKEY_A,
+        ON_PRESS_DELAY,
+        ON_RELEASE_DELAY,
+        ON_PRESS_FAKEKEY_DELAY,
+        ON_PRESS_FAKEKEY_DELAY_A,
+        ON_RELEASE_FAKEKEY_DELAY,
+        ON_RELEASE_FAKEKEY_DELAY_A,
+        ON_IDLE_FAKEKEY,
+        MWHEEL_UP,
+        MWHEEL_UP_A,
+        MWHEEL_DOWN,
+        MWHEEL_DOWN_A,
+        MWHEEL_LEFT,
+        MWHEEL_LEFT_A,
+        MWHEEL_RIGHT,
+        MWHEEL_RIGHT_A,
+        MWHEEL_ACCEL_UP,
+        MWHEEL_ACCEL_DOWN,
+        MWHEEL_ACCEL_LEFT,
+        MWHEEL_ACCEL_RIGHT,
+        MOVEMOUSE_UP,
+        MOVEMOUSE_UP_A,
+        MOVEMOUSE_DOWN,
+        MOVEMOUSE_DOWN_A,
+        MOVEMOUSE_LEFT,
+        MOVEMOUSE_LEFT_A,
+        MOVEMOUSE_RIGHT,
+        MOVEMOUSE_RIGHT_A,
+        MOVEMOUSE_ACCEL_UP,
+        MOVEMOUSE_ACCEL_UP_A,
+        MOVEMOUSE_ACCEL_DOWN,
+        MOVEMOUSE_ACCEL_DOWN_A,
+        MOVEMOUSE_ACCEL_LEFT,
+        MOVEMOUSE_ACCEL_LEFT_A,
+        MOVEMOUSE_ACCEL_RIGHT,
+        MOVEMOUSE_ACCEL_RIGHT_A,
+        MOVEMOUSE_SPEED,
+        MOVEMOUSE_SPEED_A,
+        SETMOUSE,
+        SETMOUSE_A,
+        DYNAMIC_MACRO_RECORD,
+        DYNAMIC_MACRO_PLAY,
+        ARBITRARY_CODE,
+        CMD,
+        CMD_OUTPUT_KEYS,
+        CMD_LOG,
+        PUSH_MESSAGE,
+        FORK,
+        CAPS_WORD,
+        CAPS_WORD_A,
+        CAPS_WORD_TOGGLE,
+        CAPS_WORD_TOGGLE_A,
+        CAPS_WORD_CUSTOM,
+        CAPS_WORD_CUSTOM_A,
+        CAPS_WORD_CUSTOM_TOGGLE,
+        CAPS_WORD_CUSTOM_TOGGLE_A,
+        DYNAMIC_MACRO_RECORD_STOP_TRUNCATE,
+        SWITCH,
+        SEQUENCE,
+        SEQUENCE_NOERASE,
+        UNMOD,
+        UNSHIFT,
+        UNSHIFT_A,
+        LIVE_RELOAD_NUM,
+        LIVE_RELOAD_FILE,
+        ON_PRESS,
+        ON_PRESS_A,
+        ON_RELEASE,
+        ON_RELEASE_A,
+        ON_IDLE,
+        ON_PHYSICAL_IDLE,
+        HOLD_FOR_DURATION,
+        MACRO_CANCEL_ON_NEXT_PRESS,
+        MACRO_REPEAT_CANCEL_ON_NEXT_PRESS,
+        MACRO_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE,
+        MACRO_REPEAT_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE,
+        ONE_SHOT_PAUSE_PROCESSING,
+        CLIPBOARD_SET,
+        CLIPBOARD_CMD_SET,
+        CLIPBOARD_SAVE,
+        CLIPBOARD_RESTORE,
+        CLIPBOARD_SAVE_SET,
+        CLIPBOARD_SAVE_CMD_SET,
+        CLIPBOARD_SAVE_SWAP,
+        TAP_HOLD_ORDER,
+        TAP_HOLD_OPPOSITE_HAND,
+        TAP_HOLD_OPPOSITE_HAND_RELEASE,
+    ];
+    LIST_ACTIONS.contains(&ac)
+}
diff --git a/parser/src/cfg/live_reload.rs b/parser/src/cfg/live_reload.rs
new file mode 100644
index 000000000..fba2e3191
--- /dev/null
+++ b/parser/src/cfg/live_reload.rs
@@ -0,0 +1,40 @@
+use super::*;
+
+use crate::bail;
+use crate::bail_expr;
+
+pub(crate) fn parse_live_reload_num(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 1 parameter: <config argument position (1-65535)>";
+    if ac_params.len() != 1 {
+        bail!("{LIVE_RELOAD_NUM} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let num = parse_non_zero_u16(&ac_params[0], s, "config argument position")?;
+    // Note: for user-friendliness (hopefully), begin at 1 for parsing.
+    // But for use as an index when stored as data, subtract 1 for 0-based indexing.
+    custom(CustomAction::LiveReloadNum(num - 1), &s.a)
+}
+
+pub(crate) fn parse_live_reload_file(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects 1 parameter: <config argument (exact path)>";
+    if ac_params.len() != 1 {
+        bail!("{LIVE_RELOAD_FILE} {ERR_MSG}, found {}", ac_params.len());
+    }
+    let expr = &ac_params[0];
+    let spanned_filepath = match expr {
+        SExpr::Atom(filepath) => filepath,
+        SExpr::List(_) => {
+            bail_expr!(&expr, "Filepath cannot be a list")
+        }
+    };
+    let lrld_file_path = spanned_filepath.t.trim_atom_quotes();
+    custom(
+        CustomAction::LiveReloadFile(s.a.sref_str(lrld_file_path.to_string())),
+        &s.a,
+    )
+}
diff --git a/parser/src/cfg/macro.rs b/parser/src/cfg/macro.rs
new file mode 100644
index 000000000..e84097e90
--- /dev/null
+++ b/parser/src/cfg/macro.rs
@@ -0,0 +1,284 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+const MACRO_ERR: &str = "Action macro only accepts delays, keys, chords, chorded sub-macros, and a subset of special actions.\nThe macro section of the documentation describes this in more detail:\nhttps://github.com/jtroo/kanata/blob/main/docs/config.adoc#macro";
+
+pub(crate) enum RepeatMacro {
+    Yes,
+    No,
+}
+
+pub(crate) fn parse_macro(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    repeat: RepeatMacro,
+) -> Result<&'static KanataAction> {
+    if ac_params.is_empty() {
+        bail!("macro expects at least one item after it")
+    }
+    let mut all_events = Vec::with_capacity(256);
+    let mut params_remainder = ac_params;
+    while !params_remainder.is_empty() {
+        let mut events;
+        (events, params_remainder) = parse_macro_item(params_remainder, s)?;
+        all_events.append(&mut events);
+    }
+    if all_events.iter().any(|e| match e {
+        SequenceEvent::Tap(kc) | SequenceEvent::Press(kc) | SequenceEvent::Release(kc) => {
+            *kc == KEY_OVERLAP
+        }
+        _ => false,
+    }) {
+        bail!("macro contains O- which is only valid within defseq")
+    }
+    all_events.push(SequenceEvent::Complete);
+    all_events.shrink_to_fit();
+    match repeat {
+        RepeatMacro::No => Ok(s.a.sref(Action::Sequence {
+            events: s.a.sref(s.a.sref(s.a.sref_vec(all_events))),
+        })),
+        RepeatMacro::Yes => Ok(s.a.sref(Action::RepeatableSequence {
+            events: s.a.sref(s.a.sref(s.a.sref_vec(all_events))),
+        })),
+    }
+}
+
+pub(crate) fn parse_macro_release_cancel(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    repeat: RepeatMacro,
+) -> Result<&'static KanataAction> {
+    let macro_action = parse_macro(ac_params, s, repeat)?;
+    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(vec![
+        *macro_action,
+        Action::Custom(s.a.sref(CustomAction::CancelMacroOnRelease)),
+    ])))))
+}
+
+pub(crate) fn parse_macro_cancel_on_next_press(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    repeat: RepeatMacro,
+) -> Result<&'static KanataAction> {
+    let macro_action = parse_macro(ac_params, s, repeat)?;
+    let macro_duration = match macro_action {
+        Action::RepeatableSequence { events } | Action::Sequence { events } => {
+            macro_sequence_event_total_duration(events)
+        }
+        _ => unreachable!("parse_macro should return sequence action"),
+    };
+    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(vec![
+        *macro_action,
+        Action::Custom(s.a.sref(CustomAction::CancelMacroOnNextPress(macro_duration))),
+    ])))))
+}
+
+pub(crate) fn parse_macro_cancel_on_next_press_cancel_on_release(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    repeat: RepeatMacro,
+) -> Result<&'static KanataAction> {
+    let macro_action = parse_macro(ac_params, s, repeat)?;
+    let macro_duration = match macro_action {
+        Action::RepeatableSequence { events } | Action::Sequence { events } => {
+            macro_sequence_event_total_duration(events)
+        }
+        _ => unreachable!("parse_macro should return sequence action"),
+    };
+    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(vec![
+        *macro_action,
+        Action::Custom(s.a.sref(CustomAction::CancelMacroOnRelease)),
+        Action::Custom(s.a.sref(CustomAction::CancelMacroOnNextPress(macro_duration))),
+    ])))))
+}
+
+pub(crate) fn macro_sequence_event_total_duration<T>(events: &[SequenceEvent<T>]) -> u32 {
+    events.iter().fold(0, |duration, event| {
+        duration.saturating_add(match event {
+            SequenceEvent::Delay { duration: d } => *d,
+            _ => 1,
+        })
+    })
+}
+
+pub(crate) fn parse_macro_record_stop_truncate(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_STR: &str =
+        "dynamic-macro-record-stop-truncate expects 1 param: <num-keys-to-truncate>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_STR}\nFound {} params instead of 1", ac_params.len());
+    }
+    let num_to_truncate = parse_u16(&ac_params[0], s, "num-keys-to-truncate")?;
+    custom(CustomAction::DynamicMacroRecordStop(num_to_truncate), &s.a)
+}
+
+#[derive(PartialEq)]
+pub(crate) enum MacroNumberParseMode {
+    Delay,
+    Action,
+}
+
+#[allow(clippy::type_complexity)] // return type is not pub
+pub(crate) fn parse_macro_item<'a>(
+    acs: &'a [SExpr],
+    s: &ParserState,
+) -> Result<(Vec<SequenceEvent<'static, KanataCustom>>, &'a [SExpr])> {
+    parse_macro_item_impl(acs, s, MacroNumberParseMode::Delay)
+}
+
+#[allow(clippy::type_complexity)] // return type is not pub
+pub(crate) fn parse_macro_item_impl<'a>(
+    acs: &'a [SExpr],
+    s: &ParserState,
+    num_parse_mode: MacroNumberParseMode,
+) -> Result<(Vec<SequenceEvent<'static, KanataCustom>>, &'a [SExpr])> {
+    if num_parse_mode == MacroNumberParseMode::Delay {
+        if let Some(a) = acs[0].atom(s.vars()) {
+            match parse_non_zero_u16(&acs[0], s, "delay") {
+                Ok(duration) => {
+                    let duration = u32::from(duration);
+                    return Ok((vec![SequenceEvent::Delay { duration }], &acs[1..]));
+                }
+                Err(e) => {
+                    if a.chars().all(|c| c.is_ascii_digit()) {
+                        return Err(e);
+                    }
+                }
+            }
+        }
+    }
+    match parse_action(&acs[0], s) {
+        Ok(Action::KeyCode(kc)) => {
+            // Should note that I tried `SequenceEvent::Tap` initially but it seems to be buggy
+            // so I changed the code to use individual press and release. The SequenceEvent
+            // code is from a PR that (at the time of this writing) hasn't yet been merged into
+            // keyberon master and doesn't have tests written for it yet. This seems to work as
+            // expected right now though.
+            Ok((
+                vec![SequenceEvent::Press(*kc), SequenceEvent::Release(*kc)],
+                &acs[1..],
+            ))
+        }
+        Ok(Action::MultipleKeyCodes(kcs)) => {
+            // chord - press in order then release in the reverse order
+            let mut events = vec![];
+            for kc in kcs.iter() {
+                events.push(SequenceEvent::Press(*kc));
+            }
+            for kc in kcs.iter().rev() {
+                events.push(SequenceEvent::Release(*kc));
+            }
+            Ok((events, &acs[1..]))
+        }
+        Ok(Action::Custom(custom)) => Ok((vec![SequenceEvent::Custom(custom)], &acs[1..])),
+        Ok(_) => bail_expr!(&acs[0], "{MACRO_ERR}"),
+        Err(e) => {
+            if let Some(submacro) = acs[0].list(s.vars()) {
+                // If it's just a list that's not parsable as a usable action, try parsing the
+                // content.
+                let mut submacro_remainder = submacro;
+                let mut all_events = vec![];
+                while !submacro_remainder.is_empty() {
+                    let mut events;
+                    (events, submacro_remainder) =
+                        parse_macro_item(submacro_remainder, s).map_err(|_e| e.clone())?;
+                    all_events.append(&mut events);
+                }
+                return Ok((all_events, &acs[1..]));
+            }
+
+            let (held_mods, unparsed_str) =
+                parse_mods_held_for_submacro(&acs[0], s).map_err(|mut err| {
+                    if err.msg == MACRO_ERR {
+                        err.msg = format!("{}\n{MACRO_ERR}", &e.msg);
+                    }
+                    err
+                })?;
+            let mut all_events = vec![];
+
+            // First, press all of the modifiers
+            for kc in held_mods.iter().copied() {
+                all_events.push(SequenceEvent::Press(kc));
+            }
+
+            let mut rem_start = 1;
+            let maybe_list_var = SExpr::Atom(Spanned::new(unparsed_str.into(), acs[0].span()));
+            let submacro = match maybe_list_var.list(s.vars()) {
+                Some(l) => l,
+                None => {
+                    // Ensure that the unparsed text is empty since otherwise it means there is
+                    // invalid text there
+                    if !unparsed_str.is_empty() {
+                        bail_expr!(&acs[0], "{}\n{MACRO_ERR}", &e.msg)
+                    }
+                    // Check for a follow-up list
+                    rem_start = 2;
+                    if acs.len() < 2 {
+                        bail_expr!(&acs[0], "{}\n{MACRO_ERR}", &e.msg)
+                    }
+                    acs[1]
+                        .list(s.vars())
+                        .ok_or_else(|| anyhow_expr!(&acs[1], "{MACRO_ERR}"))?
+                }
+            };
+            let mut submacro_remainder = submacro;
+            let mut events;
+            while !submacro_remainder.is_empty() {
+                (events, submacro_remainder) = parse_macro_item(submacro_remainder, s)?;
+                all_events.append(&mut events);
+            }
+
+            // Lastly, release modifiers
+            for kc in held_mods.iter().copied() {
+                all_events.push(SequenceEvent::Release(kc));
+            }
+
+            Ok((all_events, &acs[rem_start..]))
+        }
+    }
+}
+
+/// Parses mod keys like `C-S-`. Returns the `KeyCode`s for the modifiers parsed and the unparsed
+/// text after any parsed modifier prefixes.
+pub(crate) fn parse_mods_held_for_submacro<'a>(
+    held_mods: &'a SExpr,
+    s: &'a ParserState,
+) -> Result<(Vec<KeyCode>, &'a str)> {
+    let mods = held_mods
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(held_mods, "{MACRO_ERR}"))?;
+    let (mod_keys, unparsed_str) = parse_mod_prefix(mods)?;
+    if mod_keys.is_empty() {
+        bail_expr!(held_mods, "{MACRO_ERR}");
+    }
+    Ok((mod_keys, unparsed_str))
+}
+
+pub(crate) fn parse_dynamic_macro_record(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "dynamic-macro-record expects 1 parameter: <macro ID (0-65535)>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_MSG}, found {}", ac_params.len());
+    }
+    let key = parse_u16(&ac_params[0], s, "macro ID")?;
+    custom(CustomAction::DynamicMacroRecord(key), &s.a)
+}
+
+pub(crate) fn parse_dynamic_macro_play(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "dynamic-macro-play expects 1 parameter: <macro ID (number 0-65535)>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_MSG}, found {}", ac_params.len());
+    }
+    let key = parse_u16(&ac_params[0], s, "macro ID")?;
+    custom(CustomAction::DynamicMacroPlay(key), &s.a)
+}
diff --git a/parser/src/cfg/mod.rs b/parser/src/cfg/mod.rs
index 0e540811c..569f1807e 100644
--- a/parser/src/cfg/mod.rs
+++ b/parser/src/cfg/mod.rs
@@ -5,28 +5,28 @@
 //!
 //! If the mapped keys are defined as:
 //!
-//!     (defsrc
-//!         esc  1    2    3    4
-//!     )
+//! (defsrc
+//!     esc  1    2    3    4
+//! )
 //!
 //! and the layers are:
 //!
-//!     (deflayer one
-//!         _   a    s    d    _
-//!     )
+//! (deflayer one
+//!     _   a    s    d    _
+//! )
 //!
-//!     (deflayer two
-//!         _   a    o    e    _
-//!     )
+//! (deflayer two
+//!     _   a    o    e    _
+//! )
 //!
 //! Then the keyberon layers will be as follows:
 //!
-//!     xx means unimportant and _ means transparent.
+//! (xx means unimportant and _ means transparent)
 //!
-//!     layers[0] = { xx, esc, a, s, d, 4, xx... }
-//!     layers[1] = { xx, _  , a, s, d, _, xx... }
-//!     layers[2] = { xx, esc, a, o, e, 4, xx... }
-//!     layers[3] = { xx, _  , a, o, e, _, xx... }
+//! layers[0] = { xx, esc, a, s, d, 4, xx... }
+//! layers[1] = { xx, _  , a, s, d, _, xx... }
+//! layers[2] = { xx, esc, a, o, e, 4, xx... }
+//! layers[3] = { xx, _  , a, o, e, _, xx... }
 //!
 //! Note that this example isn't practical, but `(defsrc esc 1 2 3 4)` is used because these keys
 //! are at the beginning of the array. The column index for layers is the numerical value of
@@ -37,98 +37,225 @@
 //! the behaviour in kmonad.
 //!
 //! The specific values in example above applies to Linux, but the same logic applies to Windows.
-pub mod sexpr;
 
-mod alloc;
+pub(crate) mod alloc;
 use alloc::*;
-
-mod key_override;
-pub use key_override::*;
-
+mod arbitrary_code;
+use arbitrary_code::*;
+mod caps_word;
+use caps_word::*;
+mod chord;
+use chord::*;
+mod chord_v1;
+use chord_v1::*;
+mod clipboard;
+use clipboard::*;
+mod cmd;
+use cmd::*;
 mod custom_tap_hold;
 use custom_tap_hold::*;
+mod defcfg;
+pub use defcfg::*;
+mod definputdevices;
+pub use definputdevices::*;
+mod defhands;
+use defhands::{
+    parse_defhands, parse_tap_hold_opposite_hand, parse_tap_hold_opposite_hand_release,
+};
+mod deflocalkeys;
+use deflocalkeys::*;
+mod defsrc;
+use defsrc::*;
+mod deflayer;
+use deflayer::*;
+mod deftemplate;
+pub use deftemplate::*;
+mod error;
+pub use error::*;
+mod fake_key;
+use fake_key::*;
+mod fork;
+pub use fake_key::{FAKE_KEY_ROW, NORMAL_KEY_ROW};
+use fork::*;
+mod is_a_button;
+use is_a_button::*;
+mod live_reload;
+use live_reload::*;
+mod key_outputs;
+pub use key_outputs::*;
+mod key_override;
+pub use key_override::*;
+pub mod layer_opts;
+use layer_opts::*;
+pub mod list_actions;
+use list_actions::*;
+mod r#macro;
+use r#macro::*;
+mod mouse;
+use mouse::*;
+mod multi;
+use multi::*;
+mod oneshot;
+use oneshot::*;
+mod r#override;
+use r#override::*;
+mod permutations;
+use permutations::*;
+mod platform;
+use platform::*;
+mod push_msg;
+pub use push_msg::SimpleSExpr;
+use push_msg::*;
+mod releases;
+use releases::*;
+mod sequence;
+use sequence::*;
+pub mod sexpr;
+use sexpr::*;
+mod str_ext;
+pub use str_ext::*;
+mod switch;
+pub use switch::*;
+mod tap_dance;
+use tap_dance::*;
+mod tap_hold;
+use tap_hold::*;
+mod unicode;
+use unicode::*;
+mod unmod;
+use unmod::*;
+mod vars;
+use vars::*;
+mod zippychord;
+pub use zippychord::*;
 
 use crate::custom_action::*;
 use crate::keys::*;
 use crate::layers::*;
-
-mod error;
-use error::*;
-
+use crate::lsp_hints::{self, *};
+use crate::sequences::*;
 use crate::trie::Trie;
+
 use anyhow::anyhow;
+use ordered_float::OrderedFloat;
+
+use std::cell::Cell;
+use std::cell::RefCell;
 use std::collections::hash_map::Entry;
 use std::path::Path;
+use std::path::PathBuf;
 use std::sync::Arc;
 
-type HashSet<T> = rustc_hash::FxHashSet<T>;
-type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
-
 use kanata_keyberon::action::*;
+use kanata_keyberon::chord::ChordsV2;
 use kanata_keyberon::key_code::*;
 use kanata_keyberon::layout::*;
-use sexpr::SExpr;
 
-use self::sexpr::Spanned;
-use self::sexpr::TopLevel;
+type HashSet<T> = rustc_hash::FxHashSet<T>;
+type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
 
 #[cfg(test)]
 mod tests;
 #[cfg(test)]
 pub use sexpr::parse;
 
+#[macro_export]
 macro_rules! bail {
     ($err:expr $(,)?) => {
-        return Err(CfgError::from(anyhow!($err)))
+        return Err(ParseError::from(anyhow::anyhow!($err)))
     };
     ($fmt:expr, $($arg:tt)*) => {
-        return Err(CfgError::from(anyhow!($fmt, $($arg)*)))
+        return Err(ParseError::from(anyhow::anyhow!($fmt, $($arg)*)))
     };
 }
 
+#[macro_export]
 macro_rules! bail_expr {
     ($expr:expr, $fmt:expr $(,)?) => {
-        return Err(error_expr($expr, format!($fmt)))
+        return Err(ParseError::from_expr($expr, format!($fmt)))
+    };
+    ($expr:expr, $fmt:expr, $($arg:tt)*) => {
+        return Err(ParseError::from_expr($expr, format!($fmt, $($arg)*)))
+    };
+}
+
+#[macro_export]
+macro_rules! err_expr {
+    ($expr:expr, $fmt:expr $(,)?) => {
+        Err(ParseError::from_expr($expr, format!($fmt)))
     };
     ($expr:expr, $fmt:expr, $($arg:tt)*) => {
-        return Err(error_expr($expr, format!($fmt, $($arg)*)))
+        Err(ParseError::from_expr($expr, format!($fmt, $($arg)*)))
     };
 }
 
+#[macro_export]
 macro_rules! bail_span {
     ($expr:expr, $fmt:expr $(,)?) => {
-        return Err(error_spanned($expr, format!($fmt)))
+        return Err(ParseError::from_spanned($expr, format!($fmt)))
+    };
+    ($expr:expr, $fmt:expr, $($arg:tt)*) => {
+        return Err(ParseError::from_spanned($expr, format!($fmt, $($arg)*)))
+    };
+}
+
+#[macro_export]
+macro_rules! err_span {
+    ($expr:expr, $fmt:expr $(,)?) => {
+        Err(ParseError::from_spanned($expr, format!($fmt)))
     };
     ($expr:expr, $fmt:expr, $($arg:tt)*) => {
-        return Err(error_spanned($expr, format!($fmt, $($arg)*)))
+        Err(ParseError::from_spanned($expr, format!($fmt, $($arg)*)))
     };
 }
 
+#[macro_export]
 macro_rules! anyhow_expr {
     ($expr:expr, $fmt:expr $(,)?) => {
-        error_expr($expr, format!($fmt))
+        ParseError::from_expr($expr, format!($fmt))
     };
     ($expr:expr, $fmt:expr, $($arg:tt)*) => {
-        error_expr($expr, format!($fmt, $($arg)*))
+        ParseError::from_expr($expr, format!($fmt, $($arg)*))
     };
 }
 
+#[macro_export]
 macro_rules! anyhow_span {
     ($expr:expr, $fmt:expr $(,)?) => {
-        error_spanned($expr, format!($fmt))
+        ParseError::from_spanned($expr, format!($fmt))
     };
     ($expr:expr, $fmt:expr, $($arg:tt)*) => {
-        error_spanned($expr, format!($fmt, $($arg)*))
+        ParseError::from_spanned($expr, format!($fmt, $($arg)*))
     };
 }
 
-pub type KanataAction = Action<'static, &'static &'static [&'static CustomAction]>;
-type KLayout =
-    Layout<'static, KEYS_IN_ROW, 2, ACTUAL_NUM_LAYERS, &'static &'static [&'static CustomAction]>;
+pub struct FileContentProvider<'a> {
+    /// A function to load content of a file from a filepath.
+    /// Optionally, it could implement caching and a mechanism preventing "file" and "./file"
+    /// from loading twice.
+    get_file_content_fn: &'a mut dyn FnMut(&Path) -> std::result::Result<String, String>,
+}
+
+impl<'a> FileContentProvider<'a> {
+    pub fn new(
+        get_file_content_fn: &'a mut impl FnMut(&Path) -> std::result::Result<String, String>,
+    ) -> Self {
+        Self {
+            get_file_content_fn,
+        }
+    }
+    pub fn get_file_content(&mut self, filename: &Path) -> std::result::Result<String, String> {
+        (self.get_file_content_fn)(filename)
+    }
+}
+
+pub type KanataAction = Action<'static, KanataCustom>;
+type KLayout = Layout<'static, KEYS_IN_ROW, 2, KanataCustom>;
+
+type TapHoldCustomFunc = fn(&[OsCode], &Allocations) -> &'static custom_tap_hold::CustomTapHoldFn;
 
-pub type BorrowedKLayout<'a> =
-    Layout<'a, KEYS_IN_ROW, 2, ACTUAL_NUM_LAYERS, &'a &'a [&'a CustomAction]>;
-pub type KeySeqsToFKeys = Trie;
+pub type BorrowedKLayout<'a> = Layout<'a, KEYS_IN_ROW, 2, &'a CustomAction>;
+pub type KeySeqsToFKeys = Trie<(u8, u16)>;
 
 pub struct KanataLayout {
     layout: KLayout,
@@ -144,13 +271,13 @@ impl KanataLayout {
     }
 
     /// bm stands for borrow mut.
-    pub fn bm(&mut self) -> &mut BorrowedKLayout {
+    pub fn bm(&mut self) -> &mut BorrowedKLayout<'_> {
         // shrink the lifetime
         unsafe { std::mem::transmute(&mut self.layout) }
     }
 
     /// b stands for borrow.
-    pub fn b(&self) -> &BorrowedKLayout {
+    pub fn b(&self) -> &BorrowedKLayout<'_> {
         // shrink the lifetime
         unsafe { std::mem::transmute(&self.layout) }
     }
@@ -167,95 +294,193 @@ pub struct Cfg {
     /// Layer info used for printing to the logs.
     pub layer_info: Vec<LayerInfo>,
     /// Configuration items in `defcfg`.
-    pub items: HashMap<String, String>,
+    pub options: CfgOptions,
     /// The keyberon layout state machine struct.
     pub layout: KanataLayout,
     /// Sequences defined in `defseq`.
     pub sequences: KeySeqsToFKeys,
     /// Overrides defined in `defoverrides`.
     pub overrides: Overrides,
+    /// Mapping of fake key name to its column in the fake key row.
+    pub fake_keys: HashMap<String, usize>,
+    /// The maximum value of switch's key-timing item in the configuration.
+    pub max_key_timing_check: u16,
+    /// Zipchord-like configuration.
+    pub zippy: Option<(ZchPossibleChords, ZchConfig)>,
+    /// Input device ID mappings from `definputdevices`.
+    pub input_devices: Option<Vec<(std::num::NonZeroU8, InputDeviceMatcher)>>,
 }
 
 /// Parse a new configuration from a file.
-pub fn new_from_file(p: &std::path::Path) -> MResult<Cfg> {
-    let (items, mapped_keys, layer_info, key_outputs, layout, sequences, overrides) = parse_cfg(p)?;
-    log::info!("config parsed");
-    Ok(Cfg {
-        items,
-        mapped_keys,
-        layer_info,
-        key_outputs,
-        layout,
-        sequences,
-        overrides,
-    })
+pub fn new_from_file(p: &Path) -> MResult<Cfg> {
+    parse_cfg(p)
+}
+
+pub fn new_from_str(cfg_text: &str, file_content: HashMap<String, String>) -> MResult<Cfg> {
+    let mut s = ParserState::default();
+    let icfg = parse_cfg_raw_string(
+        cfg_text,
+        &mut s,
+        &PathBuf::from("configuration"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut move |fname| match file_content
+                .get(fname.to_string_lossy().as_ref())
+            {
+                Some(s) => Ok(s.clone()),
+                None => Err("File is not known".into()),
+            },
+        },
+        DEF_LOCAL_KEYS,
+        Err("environment variables are not supported".into()),
+    )?;
+    log::info!("config file is valid");
+    Ok(populate_cfg_with_icfg(icfg, s))
 }
 
 pub type MappedKeys = HashSet<OsCode>;
-// Note: this uses a Vec inside the HashMap instead of a HashSet because ordering matters, e.g. for
-// chords like `S-b`, we want to ensure that `b` is checked first because key repeat for `b` is
-// useful while it is not useful for shift. The outputs should be iterated over in reverse order.
-pub type KeyOutputs = Vec<HashMap<OsCode, Vec<OsCode>>>;
 
 #[derive(Debug)]
 pub struct LayerInfo {
     pub name: String,
     pub cfg_text: String,
+    pub icon: Option<String>,
 }
 
 #[allow(clippy::type_complexity)] // return type is not pub
-fn parse_cfg(
-    p: &std::path::Path,
-) -> MResult<(
-    HashMap<String, String>,
-    MappedKeys,
-    Vec<LayerInfo>,
-    KeyOutputs,
-    KanataLayout,
-    KeySeqsToFKeys,
-    Overrides,
-)> {
-    let mut s = ParsedState::default();
-    let (cfg, src, layer_info, klayers, seqs, overrides) = parse_cfg_raw(p, &mut s)?;
-    Ok((
-        cfg,
-        src,
-        layer_info,
-        create_key_outputs(&klayers, &overrides),
-        create_layout(klayers, s.a),
-        seqs,
-        overrides,
-    ))
+fn parse_cfg(p: &Path) -> MResult<Cfg> {
+    let mut s = ParserState::default();
+    let icfg = parse_cfg_raw(p, &mut s)?;
+    log::info!("config file is valid");
+    Ok(populate_cfg_with_icfg(icfg, s))
+}
+
+fn populate_cfg_with_icfg(icfg: IntermediateCfg, s: ParserState) -> Cfg {
+    let (layers, allocations) = icfg.klayers.get();
+    let key_outputs = create_key_outputs(&layers, &icfg.overrides, &icfg.chords_v2);
+    let max_key_timing_check = std::cmp::max(
+        s.max_key_timing_check.get(),
+        icfg.options.tap_hold_require_prior_idle,
+    );
+    let mut layout = KanataLayout::new(
+        Layout::new_with_trans_action_settings(
+            s.a.sref(s.defsrc_layer),
+            layers,
+            icfg.options.trans_resolution_behavior_v2,
+            icfg.options.delegate_to_first_layer,
+        ),
+        allocations,
+    );
+    layout.bm().chords_v2 = icfg.chords_v2;
+    layout.bm().quick_tap_hold_timeout = icfg.options.concurrent_tap_hold;
+    layout.bm().tap_hold_require_prior_idle = icfg.options.tap_hold_require_prior_idle;
+    layout.bm().oneshot.pause_input_processing_delay = icfg.options.rapid_event_delay;
+    if let Some(s) = icfg.start_action {
+        layout
+            .bm()
+            .action_queue
+            .push_front(Some(((1, 0), 0, s, Default::default())));
+    }
+    let mut fake_keys: HashMap<String, usize> = s
+        .virtual_keys
+        .iter()
+        .map(|(k, v)| (k.clone(), v.0))
+        .collect();
+    fake_keys.shrink_to_fit();
+    Cfg {
+        options: icfg.options,
+        mapped_keys: icfg.mapped_keys,
+        layer_info: icfg.layer_info,
+        key_outputs,
+        layout,
+        sequences: icfg.sequences,
+        overrides: icfg.overrides,
+        fake_keys,
+        max_key_timing_check,
+        zippy: icfg.zippy,
+        input_devices: s.input_devices,
+    }
 }
 
-pub const FALSE_VALUES: [&str; 3] = ["no", "false", "0"];
-pub const TRUE_VALUES: [&str; 3] = ["yes", "true", "1"];
+#[derive(Debug)]
+pub struct IntermediateCfg {
+    pub options: CfgOptions,
+    pub mapped_keys: MappedKeys,
+    pub layer_info: Vec<LayerInfo>,
+    pub klayers: KanataLayers,
+    pub sequences: KeySeqsToFKeys,
+    pub overrides: Overrides,
+    pub chords_v2: Option<ChordsV2<'static, KanataCustom>>,
+    pub start_action: Option<&'static KanataAction>,
+    pub zippy: Option<(ZchPossibleChords, ZchConfig)>,
+}
 
-#[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
-const DEF_LOCAL_KEYS: &str = "deflocalkeys-win";
-#[cfg(all(feature = "interception_driver", target_os = "windows"))]
-const DEF_LOCAL_KEYS: &str = "deflocalkeys-wintercept";
-#[cfg(target_os = "linux")]
-const DEF_LOCAL_KEYS: &str = "deflocalkeys-linux";
+// A snapshot of enviroment variables, or an error message with an explanation
+// why env vars are not supported.
+pub type EnvVars = std::result::Result<Vec<(String, String)>, String>;
 
 #[allow(clippy::type_complexity)] // return type is not pub
-fn parse_cfg_raw(
-    p: &std::path::Path,
-    s: &mut ParsedState,
-) -> MResult<(
-    HashMap<String, String>,
-    MappedKeys,
-    Vec<LayerInfo>,
-    Box<KanataLayers>,
-    KeySeqsToFKeys,
-    Overrides,
-)> {
-    let text = std::fs::read_to_string(p).map_err(|e| miette::miette!("{e}"))?;
-    let cfg_filename = p.to_string_lossy().to_string();
-    parse_cfg_raw_string(&text, s, &cfg_filename).map_err(error_with_source)
-}
+fn parse_cfg_raw(p: &Path, s: &mut ParserState) -> MResult<IntermediateCfg> {
+    const INVALID_PATH_ERROR: &str = "The provided config file path is not valid";
+
+    let mut loaded_files: HashSet<PathBuf> = HashSet::default();
+
+    let mut get_file_content_fn_impl = |filepath: &Path| {
+        // Make the include paths relative to main config file instead of kanata executable.
+        let filepath_relative_to_loaded_kanata_cfg = if filepath.is_absolute() {
+            filepath.to_owned()
+        } else {
+            let relative_main_cfg_file_dir = p.parent().ok_or(INVALID_PATH_ERROR)?;
+            relative_main_cfg_file_dir.join(filepath)
+        };
+
+        let Ok(abs_filepath) = filepath_relative_to_loaded_kanata_cfg.canonicalize() else {
+            log::info!(
+                "Failed to resolve relative path: {}. Ignoring this file.",
+                filepath_relative_to_loaded_kanata_cfg.to_string_lossy()
+            );
+            return Ok("".to_owned());
+        };
+
+        // Forbid loading the same file multiple times.
+        // This prevents a potential recursive infinite loop of includes
+        // (if includes within includes were to be allowed).
+        if !loaded_files.insert(abs_filepath.clone()) {
+            return Err("The provided config file was already included before".to_string());
+        };
 
-fn expand_includes(xs: Vec<TopLevel>, main_config_filepath: &str) -> Result<Vec<TopLevel>> {
+        std::fs::read_to_string(abs_filepath.to_str().ok_or(INVALID_PATH_ERROR)?)
+            .map_err(|e| format!("Failed to include file: {e}"))
+    };
+    let mut file_content_provider = FileContentProvider::new(&mut get_file_content_fn_impl);
+
+    // `get_file_content_fn_impl` already uses CWD of the main config path,
+    // so we need to provide only the name, not the whole path.
+    let cfg_file_name: PathBuf = p
+        .file_name()
+        .ok_or_else(|| miette::miette!(INVALID_PATH_ERROR))?
+        .into();
+    let text = file_content_provider
+        .get_file_content(&cfg_file_name)
+        .map_err(|e| miette::miette!(e))?;
+
+    let env_vars: EnvVars = Ok(std::env::vars().collect());
+
+    parse_cfg_raw_string(
+        &text,
+        s,
+        p,
+        &mut file_content_provider,
+        DEF_LOCAL_KEYS,
+        env_vars,
+    )
+    .map_err(|e| e.into())
+}
+
+fn expand_includes(
+    xs: Vec<TopLevel>,
+    file_content_provider: &mut FileContentProvider,
+    _lsp_hints: &mut LspHints,
+) -> Result<Vec<TopLevel>> {
     let include_is_first_atom = gen_first_atom_filter("include");
     xs.iter().try_fold(Vec::new(), |mut acc, spanned_exprs| {
         if include_is_first_atom(&&spanned_exprs.t) {
@@ -280,24 +505,15 @@ fn expand_includes(xs: Vec<TopLevel>, main_config_filepath: &str) -> Result<Vec<
                     "Multiple filepaths are not allowed in include blocks. If you want to include multiple files, create a new include block for each of them."
                 )
             };
-
-            let original_include_filepath = Path::new(spanned_filepath.t.trim_matches('"'));
-
-            // Make the include_filepath relative to main config file instead of kanata executable.
-            let final_include_filepath = if original_include_filepath.is_absolute() {
-                original_include_filepath.to_str().ok_or_else(|| anyhow_span!(spanned_filepath, "The provided path is not valid"))?.to_owned()
-            } else {
-                let parent = Path::new(main_config_filepath).parent().expect("should be validated before");
-                let a = parent.join(original_include_filepath);
-                a.to_string_lossy().into_owned()
-            };
-
-            let file_content = std::fs::read_to_string(&final_include_filepath).map_err(|e|
-                anyhow_span!(spanned_filepath, "Failed to include file: {e}")
-            )?;
-            let tree = sexpr::parse(&file_content, &final_include_filepath)?;
+            let include_file_path = spanned_filepath.t.trim_atom_quotes();
+            let file_content = file_content_provider.get_file_content(Path::new(include_file_path))
+                .map_err(|e| anyhow_span!(spanned_filepath, "{e}"))?;
+            let tree = sexpr::parse(&file_content, include_file_path)?;
             acc.extend(tree);
 
+            #[cfg(feature = "lsp")]
+            _lsp_hints.reference_locations.include.push_from_atom(spanned_filepath);
+
             Ok(acc)
         } else {
             acc.push(spanned_exprs.clone());
@@ -306,24 +522,31 @@ fn expand_includes(xs: Vec<TopLevel>, main_config_filepath: &str) -> Result<Vec<
     })
 }
 
+#[cfg(feature = "lsp")]
+thread_local! {
+    pub(crate) static LSP_VARIABLE_REFERENCES: RefCell<crate::lsp_hints::ReferencesMap> =
+        RefCell::new(crate::lsp_hints::ReferencesMap::default());
+}
+
 #[allow(clippy::type_complexity)] // return type is not pub
-fn parse_cfg_raw_string(
+pub fn parse_cfg_raw_string(
     text: &str,
-    s: &mut ParsedState,
-    cfg_filename: &str,
-) -> Result<(
-    HashMap<String, String>,
-    MappedKeys,
-    Vec<LayerInfo>,
-    Box<KanataLayers>,
-    KeySeqsToFKeys,
-    Overrides,
-)> {
-    let spanned_root_exprs =
-        sexpr::parse(text, cfg_filename).and_then(|xs| expand_includes(xs, cfg_filename))?;
-
-    // NOTE: If nested included were to be allowed in the future,
-    // a mechanism preventing circular includes should be incorporated.
+    s: &mut ParserState,
+    cfg_path: &Path,
+    file_content_provider: &mut FileContentProvider,
+    def_local_keys_variant_to_apply: &str,
+    env_vars: EnvVars,
+) -> Result<IntermediateCfg> {
+    let mut lsp_hints: LspHints = Default::default();
+
+    let spanned_root_exprs = sexpr::parse(text, &cfg_path.to_string_lossy())
+        .and_then(|xs| expand_includes(xs, file_content_provider, &mut lsp_hints))
+        .and_then(|xs| {
+            filter_platform_specific_cfg(xs, def_local_keys_variant_to_apply, &mut lsp_hints)
+        })
+        .and_then(|xs| filter_env_specific_cfg(xs, &env_vars, &mut lsp_hints))
+        .and_then(|xs| expand_templates(xs, &mut lsp_hints))?;
+
     if let Some(spanned) = spanned_root_exprs
         .iter()
         .find(gen_first_atom_filter_spanned("include"))
@@ -335,12 +558,62 @@ fn parse_cfg_raw_string(
 
     error_on_unknown_top_level_atoms(&spanned_root_exprs)?;
 
-    let cfg = root_exprs
+    let mut local_keys: Option<HashMap<String, OsCode>> = None;
+    clear_custom_str_oscode_mapping();
+    for def_local_keys_variant in DEFLOCALKEYS_VARIANTS {
+        let Some((result, _span)) = spanned_root_exprs
+            .iter()
+            .find(gen_first_atom_filter_spanned(def_local_keys_variant))
+            .map(|x| {
+                (
+                    parse_deflocalkeys(def_local_keys_variant, &x.t),
+                    x.span.clone(),
+                )
+            })
+        else {
+            continue;
+        };
+
+        let mapping = result?;
+        if def_local_keys_variant == &def_local_keys_variant_to_apply {
+            assert!(
+                local_keys.is_none(),
+                ">1 mutually exclusive deflocalkeys variants were parsed"
+            );
+            local_keys = Some(mapping);
+        } else {
+            #[cfg(feature = "lsp")]
+            lsp_hints.inactive_code.push(lsp_hints::InactiveCode {
+                span: _span,
+                reason: format!(
+                    "Another localkeys variant is currently active: {def_local_keys_variant_to_apply}"
+                    ),
+            })
+        }
+
+        if let Some(spanned) = spanned_root_exprs
+            .iter()
+            .filter(gen_first_atom_filter_spanned(def_local_keys_variant))
+            .nth(1)
+        {
+            bail_span!(
+                spanned,
+                "Only one {def_local_keys_variant} is allowed, found more. Delete the extras."
+            )
+        }
+    }
+    replace_custom_str_oscode_mapping(&local_keys.unwrap_or_default());
+
+    #[allow(unused_mut)]
+    let mut cfg = root_exprs
         .iter()
         .find(gen_first_atom_filter("defcfg"))
         .map(|cfg| parse_defcfg(cfg))
         .transpose()?
-        .unwrap_or_default();
+        .unwrap_or_else(|| {
+            log::warn!("No defcfg is defined. Consider whether the process-unmapped-keys defcfg option should be yes vs. no. Adding defcfg with process-unmapped-keys defined will remove this warning.");
+            Default::default()
+        });
     if let Some(spanned) = spanned_root_exprs
         .iter()
         .filter(gen_first_atom_filter_spanned("defcfg"))
@@ -351,64 +624,79 @@ fn parse_cfg_raw_string(
             "Only one defcfg is allowed, found more. Delete the extras."
         )
     }
-
-    if let Some(result) = root_exprs
+    let src_expr = root_exprs
         .iter()
-        .find(gen_first_atom_filter(DEF_LOCAL_KEYS))
-        .map(|custom_keys| parse_deflocalkeys(custom_keys))
-    {
-        result?;
-    }
+        .find(gen_first_atom_filter("defsrc"))
+        .ok_or_else(|| anyhow!("Exactly one defsrc must exist; found none"))?;
     if let Some(spanned) = spanned_root_exprs
         .iter()
-        .filter(gen_first_atom_filter_spanned(DEF_LOCAL_KEYS))
+        .filter(gen_first_atom_filter_spanned("defsrc"))
         .nth(1)
     {
         bail_span!(
             spanned,
-            "Only one {DEF_LOCAL_KEYS} is allowed, found more. Delete the extras."
+            "Exactly one defsrc is allowed, found more. Delete the extras."
         )
     }
+    let (mut mapped_keys, mapping_order, _mouse_in_defsrc) = parse_defsrc(src_expr, &cfg)?;
+    #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+    if cfg.linux_opts.linux_device_detect_mode.is_none() {
+        cfg.linux_opts.linux_device_detect_mode = Some(match _mouse_in_defsrc {
+            MouseInDefsrc::MouseUsed => DeviceDetectMode::Any,
+            MouseInDefsrc::NoMouse => DeviceDetectMode::KeyboardMice,
+        });
+    }
 
-    let src_expr = root_exprs
+    let input_devices = root_exprs
         .iter()
-        .find(gen_first_atom_filter("defsrc"))
-        .ok_or_else(|| anyhow!("Exactly one defsrc must exist; found none"))?;
+        .find(gen_first_atom_filter("definputdevices"))
+        .map(|expr| parse_definputdevices(expr))
+        .transpose()?;
     if let Some(spanned) = spanned_root_exprs
         .iter()
-        .filter(gen_first_atom_filter_spanned("defsrc"))
+        .filter(gen_first_atom_filter_spanned("definputdevices"))
         .nth(1)
     {
         bail_span!(
             spanned,
-            "Exactly one defsrc is allowed, found more. Delete the extras."
+            "Only one definputdevices is allowed, found more. Delete the extras."
         )
     }
-    let (src, mapping_order) = parse_defsrc(src_expr, &cfg)?;
 
-    let deflayer_filter = gen_first_atom_filter("deflayer");
+    let var_exprs = root_exprs
+        .iter()
+        .filter(gen_first_atom_filter("defvar"))
+        .collect::<Vec<_>>();
+    let vars = parse_vars(&var_exprs, &mut lsp_hints)?;
+
+    let deflayer_labels = [DEFLAYER, DEFLAYER_MAPPED];
+    let deflayer_filter = |exprs: &&Vec<SExpr>| -> bool {
+        if exprs.is_empty() {
+            return false;
+        }
+        if let SExpr::Atom(atom) = &exprs[0] {
+            deflayer_labels.contains(&atom.t.as_str())
+        } else {
+            false
+        }
+    };
+    let deflayer_spanned_filter =
+        |exprs: &&Spanned<Vec<SExpr>>| -> bool { deflayer_filter(&&exprs.t) };
     let layer_exprs = spanned_root_exprs
         .iter()
-        .filter(gen_first_atom_filter_spanned("deflayer"))
-        .cloned()
+        .filter(deflayer_spanned_filter)
+        .map(|e| match e.t[0].atom(None).unwrap() {
+            DEFLAYER => SpannedLayerExprs::DefsrcMapping(e.clone()),
+            DEFLAYER_MAPPED => SpannedLayerExprs::CustomMapping(e.clone()),
+            _ => unreachable!(),
+        })
         .collect::<Vec<_>>();
     if layer_exprs.is_empty() {
         bail!("No deflayer expressions exist. At least one layer must be defined.")
     }
-    if layer_exprs.len() > MAX_LAYERS {
-        let spanned = spanned_root_exprs
-            .iter()
-            .filter(gen_first_atom_filter_spanned("deflayer"))
-            .nth(MAX_LAYERS)
-            .expect(">25 layers");
-        bail_span!(
-            spanned,
-            "Exceeded the maximum number of layers ({MAX_LAYERS}), the layer shown is #{}",
-            MAX_LAYERS + 1
-        )
-    }
 
-    let layer_idxs = parse_layer_indexes(&layer_exprs, mapping_order.len())?;
+    let (layer_idxs, layer_icons) =
+        parse_layer_indexes(&layer_exprs, mapping_order.len(), &vars, &mut lsp_hints)?;
     let mut sorted_idxs: Vec<(&String, &usize)> =
         layer_idxs.iter().map(|tuple| (tuple.0, tuple.1)).collect();
 
@@ -420,39 +708,47 @@ fn parse_cfg_raw_string(
     let layer_names = sorted_idxs
         .into_iter()
         .map(|(name, _)| (*name).clone())
-        .flat_map(|s| {
-            // Duplicate the same layer for `layer_strings` because the keyberon layout itself has
-            // two versions of each layer.
-            std::iter::repeat(s).take(2)
-        })
         .collect::<Vec<_>>();
 
     let layer_strings = spanned_root_exprs
         .iter()
         .filter(|expr| deflayer_filter(&&expr.t))
         .map(|expr| expr.span.file_content()[expr.span.clone()].to_string())
-        .flat_map(|s| {
-            // Duplicate the same layer for `layer_strings` because the keyberon layout itself has
-            // two versions of each layer.
-            std::iter::repeat(s).take(2)
-        })
         .collect::<Vec<_>>();
 
     let layer_info: Vec<LayerInfo> = layer_names
         .into_iter()
         .zip(layer_strings)
-        .map(|(name, cfg_text)| LayerInfo { name, cfg_text })
+        .map(|(name, cfg_text)| LayerInfo {
+            name: name.clone(),
+            cfg_text,
+            icon: layer_icons.get(&name).unwrap_or(&None).clone(),
+        })
         .collect();
 
-    let defsrc_layer = parse_defsrc_layer(src_expr, &mapping_order, s);
+    let defsrc_layer = create_defsrc_layer();
 
+    let deflayer_filter = |exprs: &&Vec<SExpr>| -> bool {
+        if exprs.is_empty() {
+            return false;
+        }
+        if let SExpr::Atom(atom) = &exprs[0] {
+            deflayer_labels.contains(&atom.t.as_str())
+        } else {
+            false
+        }
+    };
     let layer_exprs = root_exprs
         .iter()
-        .filter(&deflayer_filter)
-        .cloned()
+        .filter(deflayer_filter)
+        .map(|e| match e[0].atom(None).unwrap() {
+            DEFLAYER => LayerExprs::DefsrcMapping(e.clone()),
+            DEFLAYER_MAPPED => LayerExprs::CustomMapping(e.clone()),
+            _ => unreachable!(),
+        })
         .collect::<Vec<_>>();
 
-    *s = ParsedState {
+    *s = ParserState {
         a: s.a.clone(),
         layer_exprs,
         layer_idxs,
@@ -461,14 +757,12 @@ fn parse_cfg_raw_string(
         is_cmd_enabled: {
             #[cfg(feature = "cmd")]
             {
-                cfg.get("danger-enable-cmd").map_or(false, |s| {
-                    if TRUE_VALUES.contains(&s.to_lowercase().as_str()) {
-                        log::warn!("DANGER! cmd action is enabled.");
-                        true
-                    } else {
-                        false
-                    }
-                })
+                if cfg.enable_cmd {
+                    log::warn!("DANGER! cmd action is enabled.");
+                    true
+                } else {
+                    false
+                }
             }
             #[cfg(not(feature = "cmd"))]
             {
@@ -476,22 +770,39 @@ fn parse_cfg_raw_string(
                 false
             }
         },
-        delegate_to_first_layer: cfg.get("delegate-to-first-layer").map_or(false, |s| {
-            if TRUE_VALUES.contains(&s.to_lowercase().as_str()) {
-                log::info!("delegating transparent keys on other layers to first defined layer");
-                true
-            } else {
-                false
-            }
-        }),
+        delegate_to_first_layer: cfg.delegate_to_first_layer,
+        default_sequence_timeout: cfg.sequence_timeout,
+        default_sequence_input_mode: cfg.sequence_input_mode,
+        block_unmapped_keys: cfg.block_unmapped_keys,
+        lsp_hints: RefCell::new(lsp_hints),
+        vars,
+        max_key_timing_check: Cell::new(cfg.rapid_event_delay),
+        input_devices,
         ..Default::default()
     };
 
-    let var_exprs = root_exprs
+    let defhands_exprs = root_exprs
         .iter()
-        .filter(gen_first_atom_filter("defvar"))
+        .filter(gen_first_atom_filter("defhands"))
         .collect::<Vec<_>>();
-    parse_vars(&var_exprs, s)?;
+    match defhands_exprs.len() {
+        0 => {}
+        1 => {
+            let hand_map = parse_defhands(defhands_exprs[0], s)?;
+            s.hand_map = Some(s.a.sref(hand_map));
+        }
+        _ => {
+            let spanned = spanned_root_exprs
+                .iter()
+                .filter(gen_first_atom_filter_spanned("defhands"))
+                .nth(1)
+                .expect(">= 2 defhands");
+            bail_span!(
+                spanned,
+                "Only one defhands block is allowed, found more. Delete the extras."
+            );
+        }
+    }
 
     let chords_exprs = spanned_root_exprs
         .iter()
@@ -505,35 +816,51 @@ fn parse_cfg_raw_string(
         .collect::<Vec<_>>();
     parse_fake_keys(&fake_keys_exprs, s)?;
 
+    let vkeys_exprs = root_exprs
+        .iter()
+        .filter(gen_first_atom_filter("defvirtualkeys"))
+        .collect::<Vec<_>>();
+    parse_virtual_keys(&vkeys_exprs, s)?;
+
     let sequence_exprs = root_exprs
         .iter()
         .filter(gen_first_atom_filter("defseq"))
         .collect::<Vec<_>>();
     let sequences = parse_sequences(&sequence_exprs, s)?;
 
-    let alias_exprs = root_exprs
+    let alias_exprs = spanned_root_exprs
         .iter()
-        .filter(gen_first_atom_start_filter("defalias"))
+        .filter(gen_first_atom_start_filter_spanned("defalias"))
         .collect::<Vec<_>>();
-    parse_aliases(&alias_exprs, s)?;
+    parse_aliases(&alias_exprs, s, &env_vars)?;
 
-    let mut klayers = parse_layers(s)?;
+    let start_action = cfg
+        .start_alias
+        .as_ref()
+        .and_then(|start| s.aliases.get(start).copied());
+    if let (Some(_), None) = (cfg.start_alias.as_ref(), start_action) {
+        bail!("alias-to-trigger-on-load was given, but alias could not be found")
+    }
+
+    let mut klayers = parse_layers(s, &mut mapped_keys, &cfg)?;
 
     resolve_chord_groups(&mut klayers, s)?;
+    let layers = s.a.bref_slice(klayers);
+    s.layers = layers;
 
     let override_exprs = root_exprs
         .iter()
         .filter(gen_first_atom_filter("defoverrides"))
         .collect::<Vec<_>>();
-    let overrides = match override_exprs.len() {
-        0 => Overrides::new(&[]),
-        1 => parse_overrides(override_exprs[0], s)?,
+    let (overrides, overrides_v1_exists) = match override_exprs.len() {
+        0 => (Overrides::new(&[]), false),
+        1 => (parse_overrides(override_exprs[0], s)?, true),
         _ => {
             let spanned = spanned_root_exprs
                 .iter()
                 .filter(gen_first_atom_filter_spanned("defoverrides"))
                 .nth(1)
-                .expect("> 2 overrides");
+                .expect(">= 2 overrides");
             bail_span!(
                 spanned,
                 "Only one defoverrides allowed, found more. Delete the extras."
@@ -541,7 +868,141 @@ fn parse_cfg_raw_string(
         }
     };
 
-    Ok((cfg, src, layer_info, klayers, sequences, overrides))
+    let overridesv2_exprs = root_exprs
+        .iter()
+        .filter(gen_first_atom_filter("defoverridesv2"))
+        .collect::<Vec<_>>();
+    let overrides = match overridesv2_exprs.len() {
+        0 => overrides,
+        1 => match overrides_v1_exists {
+            false => parse_overridesv2(overridesv2_exprs[0], s)?,
+            true => {
+                let spanned = spanned_root_exprs
+                    .iter()
+                    .find(gen_first_atom_filter_spanned("defoverridesv2"))
+                    .expect("1 overridesv2");
+                bail_span!(
+                    spanned,
+                    "Only one of defoverrides or defoverridesv2 allowed, found both. Delete one of them."
+                )
+            }
+        },
+        _ => {
+            let spanned = spanned_root_exprs
+                .iter()
+                .filter(gen_first_atom_filter_spanned("defoverridesv2"))
+                .nth(1)
+                .expect(">= 2 overridesv2");
+            bail_span!(
+                spanned,
+                "Only one defoverridesv2 allowed, found more. Delete the extras."
+            )
+        }
+    };
+
+    let defchordsv2_filter = |exprs: &&Vec<SExpr>| -> bool {
+        if exprs.is_empty() {
+            return false;
+        }
+        if let SExpr::Atom(atom) = &exprs[0] {
+            matches!(atom.t.as_str(), "defchordsv2" | "defchordsv2-experimental")
+        } else {
+            false
+        }
+    };
+    let defchordsv2_spanned_filter =
+        |exprs: &&Spanned<Vec<SExpr>>| -> bool { defchordsv2_filter(&&exprs.t) };
+
+    s.pctx.trans_forbidden_reason = Some("Transparent action is forbidden within chordsv2");
+    let chords_v2_exprs = root_exprs
+        .iter()
+        .filter(defchordsv2_filter)
+        .collect::<Vec<_>>();
+    let chords_v2 = match chords_v2_exprs.len() {
+        0 => None,
+        1 => {
+            let cfks = parse_defchordv2(chords_v2_exprs[0], s)?;
+            Some(ChordsV2::new(cfks, cfg.chords_v2_min_idle))
+        }
+        _ => {
+            let spanned = spanned_root_exprs
+                .iter()
+                .filter(defchordsv2_spanned_filter)
+                .nth(1)
+                .expect("> 2 overrides");
+            bail_span!(
+                spanned,
+                "Only one defchordsv2 allowed, found more.\nDelete the extras."
+            )
+        }
+    };
+    s.pctx.trans_forbidden_reason = None;
+    if chords_v2.is_some() && !cfg.concurrent_tap_hold {
+        return Err(anyhow!(
+            "With defchordsv2 defined, concurrent-tap-hold in defcfg must be true.\n\
+            It is currently false or unspecified."
+        )
+        .into());
+    }
+
+    let defzippy_filter = |exprs: &&Vec<SExpr>| -> bool {
+        if exprs.is_empty() {
+            return false;
+        }
+        if let SExpr::Atom(atom) = &exprs[0] {
+            matches!(atom.t.as_str(), "defzippy" | "defzippy-experimental")
+        } else {
+            false
+        }
+    };
+    let defzippy_spanned_filter =
+        |exprs: &&Spanned<Vec<SExpr>>| -> bool { defzippy_filter(&&exprs.t) };
+
+    let zippy_exprs = root_exprs
+        .iter()
+        .filter(defzippy_filter)
+        .collect::<Vec<_>>();
+    let zippy = match zippy_exprs.len() {
+        0 => None,
+        1 => {
+            let zippy = parse_zippy(zippy_exprs[0], s, file_content_provider)?;
+            Some(zippy)
+        }
+        _ => {
+            let spanned = spanned_root_exprs
+                .iter()
+                .filter(defzippy_spanned_filter)
+                .nth(1)
+                .expect("> 2 overrides");
+            bail_span!(
+                spanned,
+                "Only one defzippy allowed, found more.\nDelete the extras."
+            )
+        }
+    };
+
+    #[cfg(feature = "lsp")]
+    LSP_VARIABLE_REFERENCES.with_borrow_mut(|refs| {
+        s.lsp_hints
+            .borrow_mut()
+            .reference_locations
+            .variable
+            .0
+            .extend(refs.0.drain());
+    });
+
+    let klayers = unsafe { KanataLayers::new(layers, s.a.clone()) };
+    Ok(IntermediateCfg {
+        options: cfg,
+        mapped_keys,
+        layer_info,
+        klayers,
+        sequences,
+        overrides,
+        chords_v2,
+        start_action,
+        zippy,
+    })
 }
 
 fn error_on_unknown_top_level_atoms(exprs: &[Spanned<Vec<SExpr>>]) -> Result<()> {
@@ -560,16 +1021,28 @@ fn error_on_unknown_top_level_atoms(exprs: &[Spanned<Vec<SExpr>>]) -> Result<()>
                 | "defalias"
                 | "defaliasenvcond"
                 | "defsrc"
-                | "deflayer"
+                | DEFLAYER
+                | DEFLAYER_MAPPED
                 | "defoverrides"
+                | "defoverridesv2"
+                | "deflocalkeys-macos"
                 | "deflocalkeys-linux"
                 | "deflocalkeys-win"
+                | "deflocalkeys-winiov2"
                 | "deflocalkeys-wintercept"
                 | "deffakekeys"
+                | "defvirtualkeys"
                 | "defchords"
                 | "defvar"
-                | "defseq" => Ok(()),
-                _ => bail_span!(expr, "Found unknown configuration item"),
+                | "deftemplate"
+                | "defchordsv2"
+                | "defchordsv2-experimental"
+                | "defzippy"
+                | "defzippy-experimental"
+                | "defseq"
+                | "defhands"
+                | "definputdevices" => Ok(()),
+                _ => err_span!(expr, "Found unknown configuration item"),
             })
             .ok_or_else(|| {
                 anyhow_expr!(
@@ -601,13 +1074,13 @@ fn gen_first_atom_filter(a: &str) -> impl Fn(&&Vec<SExpr>) -> bool {
 /// Return a closure that filters a root expression by the content of the first element. The
 /// closure returns true if the first element is an atom that starts with the input `a` and false
 /// otherwise.
-fn gen_first_atom_start_filter(a: &str) -> impl Fn(&&Vec<SExpr>) -> bool {
+fn gen_first_atom_start_filter_spanned(a: &str) -> impl Fn(&&Spanned<Vec<SExpr>>) -> bool {
     let a = a.to_owned();
     move |expr| {
-        if expr.is_empty() {
+        if expr.t.is_empty() {
             return false;
         }
-        if let SExpr::Atom(atom) = &expr[0] {
+        if let SExpr::Atom(atom) = &expr.t[0] {
             atom.t.starts_with(&a)
         } else {
             false
@@ -649,268 +1122,107 @@ fn check_first_expr<'a>(
     Ok(exprs)
 }
 
-/// Parse configuration entries from an expression starting with defcfg.
-fn parse_defcfg(expr: &[SExpr]) -> Result<HashMap<String, String>> {
-    let valid_cfg_keys = &[
-        "process-unmapped-keys",
-        "danger-enable-cmd",
-        "sequence-timeout",
-        "sequence-input-mode",
-        "sequence-backtrack-modcancel",
-        "log-layer-changes",
-        "delegate-to-first-layer",
-        "linux-dev",
-        "linux-dev-names-include",
-        "linux-dev-names-exclude",
-        "linux-continue-if-no-devs-found",
-        "linux-unicode-u-code",
-        "linux-unicode-termination",
-        "linux-x11-repeat-delay-rate",
-        "windows-altgr",
-        "windows-interception-mouse-hwid",
-    ];
-    let mut cfg = HashMap::default();
-    let mut exprs = check_first_expr(expr.iter(), "defcfg")?;
-    // Read k-v pairs from the configuration
-    loop {
-        let key = match exprs.next() {
-            Some(k) => k,
-            None => return Ok(cfg),
-        };
-        let val = match exprs.next() {
-            Some(v) => v,
-            None => bail_expr!(key, "Found a defcfg option missing a value"),
-        };
-        match (&key, &val) {
-            (SExpr::Atom(k), SExpr::Atom(v)) => {
-                if !valid_cfg_keys.iter().any(|valid_key| &k.t == valid_key) {
-                    bail_expr!(key, "Unknown defcfg option {}", k.t);
-                }
-                if cfg
-                    .insert(
-                        k.t.trim_matches('"').to_owned(),
-                        v.t.trim_matches('"').to_owned(),
-                    )
-                    .is_some()
-                {
-                    bail_expr!(key, "Duplicate defcfg option {}", k.t);
-                }
-            }
-            (SExpr::List(_), _) => {
-                bail_expr!(key, "Lists are not allowed in defcfg");
-            }
-            (_, SExpr::List(_)) => {
-                bail_expr!(val, "Lists are not allowed in defcfg");
-            }
-        }
-    }
+#[derive(Debug, Copy, Clone)]
+enum MouseInDefsrc {
+    MouseUsed,
+    NoMouse,
 }
 
-/// Parse custom keys from an expression starting with deflocalkeys. Statefully updates the `keys`
-/// module using the custom keys parsed.
-fn parse_deflocalkeys(expr: &[SExpr]) -> Result<()> {
-    let mut cfg = HashMap::default();
-    let mut exprs = check_first_expr(expr.iter(), DEF_LOCAL_KEYS)?;
-    clear_custom_str_oscode_mapping();
-    // Read k-v pairs from the configuration
-    while let Some(key_expr) = exprs.next() {
-        let key = key_expr
-            .atom(None)
-            .ok_or_else(|| anyhow_expr!(key_expr, "No lists are allowed in {DEF_LOCAL_KEYS}"))?;
-        if str_to_oscode(key).is_some() {
-            bail_expr!(
-                key_expr,
-                "Cannot use {key} in {DEF_LOCAL_KEYS} because it is a default key name"
-            );
-        } else if cfg.contains_key(key) {
-            bail_expr!(key_expr, "Duplicate {key} found in {DEF_LOCAL_KEYS}");
-        }
-        let osc = match exprs.next() {
-            Some(v) => v
-                .atom(None)
-                .ok_or_else(|| anyhow_expr!(v, "No lists are allowed in {DEF_LOCAL_KEYS}"))
-                .and_then(|osc| {
-                    osc.parse::<u16>()
-                        .map_err(|_| anyhow_expr!(v, "Unknown number in {DEF_LOCAL_KEYS}: {osc}"))
-                })
-                .and_then(|osc| {
-                    OsCode::from_u16(osc)
-                        .ok_or_else(|| anyhow_expr!(v, "Unknown number in {DEF_LOCAL_KEYS}: {osc}"))
-                })?,
-            None => bail_expr!(key_expr, "Key without a number in {DEF_LOCAL_KEYS}"),
-        };
-        log::debug!("custom mapping: {key} {}", osc.as_u16());
-        cfg.insert(key.to_owned(), osc);
-    }
-    replace_custom_str_oscode_mapping(&cfg);
-    Ok(())
-}
-
-/// Parse mapped keys from an expression starting with defsrc. Returns the key mapping as well as
-/// a vec of the indexes in order. The length of the returned vec should be matched by the length
-/// of all layer declarations.
-fn parse_defsrc(
-    expr: &[SExpr],
-    defcfg: &HashMap<String, String>,
-) -> Result<(MappedKeys, Vec<usize>)> {
-    let exprs = check_first_expr(expr.iter(), "defsrc")?;
-    let mut mkeys = MappedKeys::default();
-    let mut ordered_codes = Vec::new();
-    for expr in exprs {
-        let s = match expr {
-            SExpr::Atom(a) => &a.t,
-            _ => bail_expr!(expr, "No lists allowed in defsrc"),
-        };
-        let oscode = str_to_oscode(s)
-            .ok_or_else(|| anyhow_expr!(expr, "Unknown key in defsrc: \"{}\"", s))?;
-        if mkeys.contains(&oscode) {
-            bail_expr!(expr, "Repeat declaration of key in defsrc: \"{}\"", s)
-        }
-        mkeys.insert(oscode);
-        ordered_codes.push(oscode.into());
-    }
-
-    let process_unmapped_keys = defcfg
-        .get("process-unmapped-keys")
-        .map(|s| TRUE_VALUES.contains(&s.to_lowercase().as_str()))
-        .unwrap_or(false);
-    log::info!("process unmapped keys: {process_unmapped_keys}");
-    if process_unmapped_keys {
-        for osc in 0..KEYS_IN_ROW as u16 {
-            if let Some(osc) = OsCode::from_u16(osc) {
-                match KeyCode::from(osc) {
-                    KeyCode::No => {}
-                    _ => {
-                        mkeys.insert(osc);
-                    }
-                }
-            }
-        }
-    }
+type Aliases = HashMap<String, &'static KanataAction>;
 
-    mkeys.shrink_to_fit();
-    Ok((mkeys, ordered_codes))
+#[derive(Debug, Clone)]
+enum LayerExprs {
+    DefsrcMapping(Vec<SExpr>),
+    CustomMapping(Vec<SExpr>),
 }
 
-type LayerIndexes = HashMap<String, usize>;
-type Aliases = HashMap<String, &'static KanataAction>;
-
-/// Returns layer names and their indexes into the keyberon layout. This also checks that all
-/// layers have the same number of items as the defsrc. Also ensures that there are no duplicate layer names.
-fn parse_layer_indexes(exprs: &[Spanned<Vec<SExpr>>], expected_len: usize) -> Result<LayerIndexes> {
-    let mut layer_indexes = HashMap::default();
-    for (i, expr) in exprs.iter().enumerate() {
-        let mut subexprs = check_first_expr(expr.t.iter(), "deflayer")?;
-        let layer_expr = subexprs.next().ok_or_else(|| {
-            anyhow_span!(expr, "deflayer requires a name and {expected_len} item(s)")
-        })?;
-        let layer_name = layer_expr
-            .atom(None)
-            .ok_or_else(|| anyhow_expr!(layer_expr, "layer name after deflayer must be a string"))?
-            .to_owned();
-        if layer_indexes.get(&layer_name).is_some() {
-            bail_expr!(layer_expr, "duplicate layer name: {}", layer_name);
-        }
-        let num_actions = subexprs.count();
-        if num_actions != expected_len {
-            bail_span!(
-                expr,
-                "Layer {} has {} item(s), but requires {} to match defsrc",
-                layer_name,
-                num_actions,
-                expected_len
-            )
-        }
-        layer_indexes.insert(layer_name, i);
-    }
+#[derive(Debug, Clone)]
+enum SpannedLayerExprs {
+    DefsrcMapping(Spanned<Vec<SExpr>>),
+    CustomMapping(Spanned<Vec<SExpr>>),
+}
 
-    Ok(layer_indexes)
+#[derive(Debug, Clone, Default)]
+pub struct ParserContext {
+    is_within_defvirtualkeys: bool,
+    trans_forbidden_reason: Option<&'static str>,
 }
 
 #[derive(Debug)]
-struct ParsedState {
-    layer_exprs: Vec<Vec<SExpr>>,
+pub struct ParserState {
+    layers: KLayers,
+    layer_exprs: Vec<LayerExprs>,
     aliases: Aliases,
     layer_idxs: LayerIndexes,
     mapping_order: Vec<usize>,
-    fake_keys: HashMap<String, (usize, &'static KanataAction)>,
+    virtual_keys: HashMap<String, (usize, &'static KanataAction)>,
     chord_groups: HashMap<String, ChordGroup>,
     defsrc_layer: [KanataAction; KEYS_IN_ROW],
+    vars: HashMap<String, SExpr>,
     is_cmd_enabled: bool,
     delegate_to_first_layer: bool,
-    vars: HashMap<String, SExpr>,
+    default_sequence_timeout: u16,
+    default_sequence_input_mode: SequenceInputMode,
+    block_unmapped_keys: bool,
+    max_key_timing_check: Cell<u16>,
+    multi_action_nest_count: Cell<u16>,
+    input_devices: Option<Vec<(std::num::NonZeroU8, InputDeviceMatcher)>>,
+    pctx: ParserContext,
+    pub lsp_hints: RefCell<LspHints>,
+    hand_map: Option<&'static custom_tap_hold::HandMap>,
     a: Arc<Allocations>,
 }
 
-impl ParsedState {
+impl ParserState {
     fn vars(&self) -> Option<&HashMap<String, SExpr>> {
         Some(&self.vars)
     }
 }
 
-impl Default for ParsedState {
+impl Default for ParserState {
     fn default() -> Self {
+        let default_cfg = CfgOptions::default();
         Self {
+            layers: Default::default(),
             layer_exprs: Default::default(),
             aliases: Default::default(),
             layer_idxs: Default::default(),
             mapping_order: Default::default(),
-            defsrc_layer: [KanataAction::Trans; KEYS_IN_ROW],
-            fake_keys: Default::default(),
+            defsrc_layer: [KanataAction::NoOp; KEYS_IN_ROW],
+            virtual_keys: Default::default(),
             chord_groups: Default::default(),
-            is_cmd_enabled: false,
-            delegate_to_first_layer: false,
             vars: Default::default(),
+            is_cmd_enabled: default_cfg.enable_cmd,
+            delegate_to_first_layer: default_cfg.delegate_to_first_layer,
+            default_sequence_timeout: default_cfg.sequence_timeout,
+            default_sequence_input_mode: default_cfg.sequence_input_mode,
+            block_unmapped_keys: default_cfg.block_unmapped_keys,
+            max_key_timing_check: Cell::new(0),
+            multi_action_nest_count: Cell::new(0),
+            input_devices: None,
+            lsp_hints: Default::default(),
+            hand_map: None,
             a: unsafe { Allocations::new() },
+            pctx: ParserContext::default(),
         }
     }
 }
 
-#[derive(Debug, Clone)]
-struct ChordGroup {
-    id: u16,
-    name: String,
-    keys: Vec<String>,
-    coords: Vec<((u8, u16), ChordKeys)>,
-    chords: HashMap<u32, SExpr>,
-    timeout: u16,
-}
-
-fn parse_vars(exprs: &[&Vec<SExpr>], s: &mut ParsedState) -> Result<()> {
-    for expr in exprs {
-        let mut subexprs = check_first_expr(expr.iter(), "defvar")?;
-        // Read k-v pairs from the configuration
-        while let Some(var_name_expr) = subexprs.next() {
-            let var_name = match var_name_expr {
-                SExpr::Atom(a) => &a.t,
-                _ => bail_expr!(var_name_expr, "variable name must not be a list"),
-            };
-            let var_expr = match subexprs.next() {
-                Some(v) => v,
-                None => bail_expr!(
-                    var_name_expr,
-                    "variable key name has no action - you should add an action."
-                ),
-            };
-            if s.vars.insert(var_name.into(), var_expr.clone()).is_some() {
-                bail_expr!(var_name_expr, "duplicate variable name: {}", var_name);
-            }
-        }
-    }
-    Ok(())
-}
-
 /// Parse alias->action mappings from multiple exprs starting with defalias.
 /// Mutates the input `s` by storing aliases inside.
-fn parse_aliases(exprs: &[&Vec<SExpr>], s: &mut ParsedState) -> Result<()> {
+fn parse_aliases(
+    exprs: &[&Spanned<Vec<SExpr>>],
+    s: &mut ParserState,
+    env_vars: &EnvVars,
+) -> Result<()> {
     for expr in exprs {
-        handle_standard_defalias(expr, s)?;
-        handle_envcond_defalias(expr, s)?;
+        handle_standard_defalias(&expr.t, s)?;
+        handle_envcond_defalias(expr, s, env_vars)?;
     }
     Ok(())
 }
 
-fn handle_standard_defalias(expr: &[SExpr], s: &mut ParsedState) -> Result<()> {
+fn handle_standard_defalias(expr: &[SExpr], s: &mut ParserState) -> Result<()> {
     let subexprs = match check_first_expr(expr.iter(), "defalias") {
         Ok(s) => s,
         Err(_) => return Ok(()),
@@ -918,8 +1230,12 @@ fn handle_standard_defalias(expr: &[SExpr], s: &mut ParsedState) -> Result<()> {
     read_alias_name_action_pairs(subexprs, s)
 }
 
-fn handle_envcond_defalias(expr: &[SExpr], s: &mut ParsedState) -> Result<()> {
-    let mut subexprs = match check_first_expr(expr.iter(), "defaliasenvcond") {
+fn handle_envcond_defalias(
+    exprs: &Spanned<Vec<SExpr>>,
+    s: &mut ParserState,
+    env_vars: &EnvVars,
+) -> Result<()> {
+    let mut subexprs = match check_first_expr(exprs.t.iter(), "defaliasenvcond") {
         Ok(exprs) => exprs,
         Err(_) => return Ok(()),
     };
@@ -949,21 +1265,53 @@ fn handle_envcond_defalias(expr: &[SExpr], s: &mut ParsedState) -> Result<()> {
                     "Environment variable value must be a string, not a list.\n{conderr}"
                 )
             })?;
-            if !std::env::vars().any(|(name, value)| name == env_var_name && value == env_var_value)
-            {
-                log::info!("Did not find env var ({env_var_name} {env_var_value}), skipping associated aliases");
-                return Ok(());
+            match env_vars {
+                Ok(vars) => {
+                    let values_of_matching_vars: Vec<_> = vars
+                        .iter()
+                        .filter_map(|(k, v)| if k == env_var_name { Some(v) } else { None })
+                        .collect();
+                    if values_of_matching_vars.is_empty() {
+                        let msg = format!("Env var '{env_var_name}' is not set");
+                        #[cfg(feature = "lsp")]
+                        s.lsp_hints
+                            .borrow_mut()
+                            .inactive_code
+                            .push(lsp_hints::InactiveCode {
+                                span: exprs.span.clone(),
+                                reason: msg.clone(),
+                            });
+                        log::info!("{msg}, skipping associated aliases");
+                        return Ok(());
+                    } else if !values_of_matching_vars.iter().any(|&v| v == env_var_value) {
+                        let msg =
+                            format!("Env var '{env_var_name}' is set, but value doesn't match");
+                        #[cfg(feature = "lsp")]
+                        s.lsp_hints
+                            .borrow_mut()
+                            .inactive_code
+                            .push(lsp_hints::InactiveCode {
+                                span: exprs.span.clone(),
+                                reason: msg.clone(),
+                            });
+                        log::info!("{msg}, skipping associated aliases");
+                        return Ok(());
+                    }
+                }
+                Err(err) => {
+                    bail_expr!(expr, "{err}");
+                }
             }
             log::info!("Found env var ({env_var_name} {env_var_value}), using associated aliases");
         }
-        None => bail_expr!(&expr[0], "Missing a list item.\n{conderr}"),
+        None => bail_expr!(&exprs.t[0], "Missing a list item.\n{conderr}"),
     };
     read_alias_name_action_pairs(subexprs, s)
 }
 
 fn read_alias_name_action_pairs<'a>(
     mut exprs: impl Iterator<Item = &'a SExpr>,
-    s: &mut ParsedState,
+    s: &mut ParserState,
 ) -> Result<()> {
     // Read k-v pairs from the configuration
     while let Some(alias_expr) = exprs.next() {
@@ -983,12 +1331,18 @@ fn read_alias_name_action_pairs<'a>(
         if s.aliases.insert(alias.into(), action).is_some() {
             bail_expr!(alias_expr, "Duplicate alias: {}", alias);
         }
+        #[cfg(feature = "lsp")]
+        s.lsp_hints
+            .borrow_mut()
+            .definition_locations
+            .alias
+            .insert(alias.into(), alias_expr.span());
     }
     Ok(())
 }
 
 /// Parse a `kanata_keyberon::action::Action` from a `SExpr`.
-fn parse_action(expr: &SExpr, s: &ParsedState) -> Result<&'static KanataAction> {
+fn parse_action(expr: &SExpr, s: &ParserState) -> Result<&'static KanataAction> {
     expr.atom(s.vars())
         .map(|a| parse_action_atom(&Spanned::new(a.into(), expr.span()), s))
         .unwrap_or_else(|| {
@@ -997,329 +1351,427 @@ fn parse_action(expr: &SExpr, s: &ParsedState) -> Result<&'static KanataAction>
                 .expect("must be atom or list")
         })
         .map_err(|mut e| {
-            if e.err_span.is_none() {
-                e.err_span = Some(expr_err_span(expr));
-                e.file_name = Some(expr.span().file_name());
-                e.file_content = Some(expr.span().file_content());
-            }
+            if e.span.is_none() {
+                e.span = Some(expr.span())
+            };
             e
         })
 }
 
+/// Returns a single custom action in the proper wrapped type.
+fn custom(ca: CustomAction, a: &Allocations) -> Result<&'static KanataAction> {
+    Ok(a.sref(Action::Custom(a.sref(ca))))
+}
+
 /// Parse a `kanata_keyberon::action::Action` from a string.
-fn parse_action_atom(ac: &Spanned<String>, s: &ParsedState) -> Result<&'static KanataAction> {
-    let ac = &*ac.t;
+fn parse_action_atom(ac_span: &Spanned<String>, s: &ParserState) -> Result<&'static KanataAction> {
+    let ac = &*ac_span.t;
+    if is_list_action(ac) {
+        bail_span!(
+            ac_span,
+            "This is a list action and must be in parentheses: ({ac} ...)"
+        );
+    }
     match ac {
-        "_" => return Ok(s.a.sref(Action::Trans)),
-        "XX" => return Ok(s.a.sref(Action::NoOp)),
-        "lrld" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::LiveReload)),
-            )))
-        }
-        "lrld-next" | "lrnx" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::LiveReloadNext)),
-            )))
-        }
-        "lrld-prev" | "lrpv" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::LiveReloadPrev)),
-            )))
+        "_" | "‗" | "≝" => {
+            if let Some(trans_forbidden_reason) = s.pctx.trans_forbidden_reason {
+                bail_span!(ac_span, "{trans_forbidden_reason}");
+            } else {
+                return Ok(s.a.sref(Action::Trans));
+            }
         }
+        "XX" | "✗" | "∅" | "•" => {
+            return Ok(s.a.sref(Action::NoOp));
+        }
+        "lrld" => return custom(CustomAction::LiveReload, &s.a),
+        "lrld-next" | "lrnx" => return custom(CustomAction::LiveReloadNext, &s.a),
+        "lrld-prev" | "lrpv" => return custom(CustomAction::LiveReloadPrev, &s.a),
         "sldr" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::SequenceLeader)),
-            )))
-        }
-        "mlft" | "mouseleft" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Mouse(Btn::Left))),
-            )))
-        }
-        "mrgt" | "mouseright" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Mouse(Btn::Right))),
-            )))
-        }
-        "mmid" | "mousemid" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Mouse(Btn::Mid))),
-            )))
-        }
-        "mfwd" | "mouseforward" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Mouse(Btn::Forward))),
-            )))
-        }
-        "mbck" | "mousebackward" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Mouse(Btn::Backward))),
-            )))
-        }
-        "mltp" | "mousetapleft" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::MouseTap(Btn::Left))),
-            )))
-        }
-        "mrtp" | "mousetapright" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::MouseTap(Btn::Right))),
-            )))
-        }
-        "mmtp" | "mousetapmid" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::MouseTap(Btn::Mid))),
-            )))
-        }
-        "mftp" | "mousetapforward" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::MouseTap(Btn::Forward))),
-            )))
-        }
-        "mbtp" | "mousetapbackward" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::MouseTap(Btn::Backward))),
-            )))
-        }
-        "rpt" | "repeat" | "rpt-key" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::Repeat)),
-            )))
+            return custom(
+                CustomAction::SequenceLeader(
+                    s.default_sequence_timeout,
+                    s.default_sequence_input_mode,
+                ),
+                &s.a,
+            );
         }
+        "scnl" => return custom(CustomAction::SequenceCancel, &s.a),
+        "mlft" | "mouseleft" => return custom(CustomAction::Mouse(Btn::Left), &s.a),
+        "mrgt" | "mouseright" => return custom(CustomAction::Mouse(Btn::Right), &s.a),
+        "mmid" | "mousemid" => return custom(CustomAction::Mouse(Btn::Mid), &s.a),
+        "mfwd" | "mouseforward" => return custom(CustomAction::Mouse(Btn::Forward), &s.a),
+        "mbck" | "mousebackward" => return custom(CustomAction::Mouse(Btn::Backward), &s.a),
+        "mltp" | "mousetapleft" => return custom(CustomAction::MouseTap(Btn::Left), &s.a),
+        "mrtp" | "mousetapright" => return custom(CustomAction::MouseTap(Btn::Right), &s.a),
+        "mmtp" | "mousetapmid" => return custom(CustomAction::MouseTap(Btn::Mid), &s.a),
+        "mftp" | "mousetapforward" => return custom(CustomAction::MouseTap(Btn::Forward), &s.a),
+        "mbtp" | "mousetapbackward" => return custom(CustomAction::MouseTap(Btn::Backward), &s.a),
+        "mwu" | "mousewheelup" => {
+            return custom(
+                CustomAction::MWheelNotch {
+                    direction: MWheelDirection::Up,
+                },
+                &s.a,
+            );
+        }
+        "mwd" | "mousewheeldown" => {
+            return custom(
+                CustomAction::MWheelNotch {
+                    direction: MWheelDirection::Down,
+                },
+                &s.a,
+            );
+        }
+        "mwl" | "mousewheelleft" => {
+            return custom(
+                CustomAction::MWheelNotch {
+                    direction: MWheelDirection::Left,
+                },
+                &s.a,
+            );
+        }
+        "mwr" | "mousewheelright" => {
+            return custom(
+                CustomAction::MWheelNotch {
+                    direction: MWheelDirection::Right,
+                },
+                &s.a,
+            );
+        }
+        "rpt" | "repeat" | "rpt-key" => return custom(CustomAction::Repeat, &s.a),
         "rpt-any" => return Ok(s.a.sref(Action::Repeat)),
         "dynamic-macro-record-stop" => {
-            return Ok(s.a.sref(Action::Custom(
-                s.a.sref(s.a.sref_slice(CustomAction::DynamicMacroRecordStop(0))),
-            )))
+            return custom(CustomAction::DynamicMacroRecordStop(0), &s.a);
+        }
+        "reverse-release-order" => match s.multi_action_nest_count.get() {
+            0 => bail_span!(
+                ac_span,
+                "reverse-release-order is only allowed inside of a (multi ...) action list"
+            ),
+            _ => return custom(CustomAction::ReverseReleaseOrder, &s.a),
+        },
+        "use-defsrc" => {
+            return Ok(s.a.sref(Action::Src));
+        }
+        "mvmt" | "mousemovement" | "🖰mv" => {
+            bail_span!(ac_span, "{ac} can only be used as an input")
         }
         _ => {}
     };
     if let Some(oscode) = str_to_oscode(ac) {
+        if matches!(ac, "comp" | "cmp") {
+            log::warn!(
+                "comp/cmp/cmps is not actually a compose key even though its correpsonding code is KEY_COMPOSE. Its actual functionality is context menu which somewhat behaves like right-click.\nTo remove this warning, replace this usage with an equivalent key name such as: menu"
+            );
+        }
         return Ok(s.a.sref(k(oscode.into())));
     }
     if let Some(alias) = ac.strip_prefix('@') {
         return match s.aliases.get(alias) {
-            Some(ac) => Ok(*ac),
-            None => bail!(
-                "Referenced unknown alias {}. Note that order of declarations matter.",
-                alias
-            ),
+            Some(ac) => {
+                #[cfg(feature = "lsp")]
+                s.lsp_hints
+                    .borrow_mut()
+                    .reference_locations
+                    .alias
+                    .push(alias, ac_span.span.clone());
+                Ok(*ac)
+            }
+            None => match s.pctx.is_within_defvirtualkeys {
+                true => bail_span!(
+                    ac_span,
+                    "Aliases are not usable within defvirtualkeys. You may use vars or templates.",
+                ),
+                false => bail_span!(
+                    ac_span,
+                    "Referenced unknown alias {}. Note that order of declarations matter.",
+                    alias
+                ),
+            },
         };
     }
-
+    if let Some(unisym) = ac.strip_prefix('🔣') {
+        // TODO: when unicode accepts multiple chars, change this to feed the whole string, not just the first char
+        return custom(
+            CustomAction::Unicode(unisym.chars().next().expect("1 char")),
+            &s.a,
+        );
+    }
     // Parse a sequence like `C-S-v` or `C-A-del`
     let (mut keys, unparsed_str) = parse_mod_prefix(ac)?;
     keys.push(
         str_to_oscode(unparsed_str)
-            .ok_or_else(|| anyhow!("Unknown key/action/variable: {ac:?}"))?
+            .ok_or_else(|| {
+                // check aliases
+                if s.aliases.contains_key(ac) {
+                    anyhow!("Unknown key/action: {ac}. If you meant to use an alias, prefix it with '@' symbol: @{ac}")
+                } else if s.vars.contains_key(ac) {
+                    anyhow!("Unknown key/action: {ac}. If you meant to use a variable, prefix it with '$' symbol: ${ac}")
+                } else {
+                    anyhow!("Unknown key/action: {ac}")
+                }
+            })?
             .into(),
     );
+    if keys.contains(&KEY_OVERLAP) {
+        bail!("O- is only valid in sequences for lists of keys");
+    }
     Ok(s.a.sref(Action::MultipleKeyCodes(s.a.sref(s.a.sref_vec(keys)))))
 }
 
 /// Parse a `kanata_keyberon::action::Action` from a `SExpr::List`.
-fn parse_action_list(ac: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
+fn parse_action_list(ac: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
     if ac.is_empty() {
         return Ok(s.a.sref(Action::NoOp));
     }
     let ac_type = match &ac[0] {
         SExpr::Atom(a) => &a.t,
-        _ => bail!("Action list must start with an atom"),
+        _ => bail!("All list actions must start with string and not a list"),
     };
+    if !is_list_action(ac_type) {
+        bail_expr!(&ac[0], "Unknown action type: {ac_type}");
+    }
     match ac_type.as_str() {
-        "layer-switch" => parse_layer_base(&ac[1..], s),
-        "layer-toggle" | "layer-while-held" => parse_layer_toggle(&ac[1..], s),
-        "tap-hold" => parse_tap_hold(&ac[1..], s, HoldTapConfig::Default),
-        "tap-hold-press" => parse_tap_hold(&ac[1..], s, HoldTapConfig::HoldOnOtherKeyPress),
-        "tap-hold-release" => parse_tap_hold(&ac[1..], s, HoldTapConfig::PermissiveHold),
-        "tap-hold-press-timeout" => {
+        LAYER_SWITCH => parse_layer_base(&ac[1..], s),
+        LAYER_TOGGLE | LAYER_WHILE_HELD => parse_layer_toggle(&ac[1..], s),
+        TAP_HOLD => parse_tap_hold(&ac[1..], s, HoldTapConfig::Default),
+        TAP_HOLD_PRESS | TAP_HOLD_PRESS_A => {
+            parse_tap_hold(&ac[1..], s, HoldTapConfig::HoldOnOtherKeyPress)
+        }
+        TAP_HOLD_ORDER => parse_tap_hold_order(&ac[1..], s),
+        TAP_HOLD_RELEASE | TAP_HOLD_RELEASE_A => {
+            parse_tap_hold(&ac[1..], s, HoldTapConfig::PermissiveHold)
+        }
+        TAP_HOLD_PRESS_TIMEOUT | TAP_HOLD_PRESS_TIMEOUT_A => {
             parse_tap_hold_timeout(&ac[1..], s, HoldTapConfig::HoldOnOtherKeyPress)
         }
-        "tap-hold-release-timeout" => {
+        TAP_HOLD_RELEASE_TIMEOUT | TAP_HOLD_RELEASE_TIMEOUT_A => {
             parse_tap_hold_timeout(&ac[1..], s, HoldTapConfig::PermissiveHold)
         }
-        "tap-hold-release-keys" => parse_tap_hold_release_keys(&ac[1..], s),
-        "multi" => parse_multi(&ac[1..], s),
-        "macro" => parse_macro(&ac[1..], s, RepeatMacro::No),
-        "macro-repeat" => parse_macro(&ac[1..], s, RepeatMacro::Yes),
-        "macro-release-cancel" => parse_macro_release_cancel(&ac[1..], s, RepeatMacro::No),
-        "macro-repeat-release-cancel" => parse_macro_release_cancel(&ac[1..], s, RepeatMacro::Yes),
-        "unicode" => parse_unicode(&ac[1..], s),
-        "one-shot" | "one-shot-press" => {
+        TAP_HOLD_RELEASE_KEYS_TAP_RELEASE => parse_tap_hold_keys_trigger_tap_release(&ac[1..], s),
+        TAP_HOLD_KEYS => parse_tap_hold_keys_named_lists(&ac[1..], s),
+        TAP_HOLD_RELEASE_KEYS | TAP_HOLD_RELEASE_KEYS_A => {
+            parse_tap_hold_keys(&ac[1..], s, TAP_HOLD_RELEASE_KEYS, custom_tap_hold_release)
+        }
+        TAP_HOLD_EXCEPT_KEYS | TAP_HOLD_EXCEPT_KEYS_A => {
+            parse_tap_hold_keys(&ac[1..], s, TAP_HOLD_EXCEPT_KEYS, custom_tap_hold_except)
+        }
+        TAP_HOLD_TAP_KEYS | TAP_HOLD_TAP_KEYS_A => {
+            parse_tap_hold_keys(&ac[1..], s, TAP_HOLD_TAP_KEYS, custom_tap_hold_tap_keys)
+        }
+        TAP_HOLD_OPPOSITE_HAND => parse_tap_hold_opposite_hand(&ac[1..], s),
+        TAP_HOLD_OPPOSITE_HAND_RELEASE => parse_tap_hold_opposite_hand_release(&ac[1..], s),
+        MULTI => parse_multi(&ac[1..], s),
+        MACRO => parse_macro(&ac[1..], s, RepeatMacro::No),
+        MACRO_REPEAT | MACRO_REPEAT_A => parse_macro(&ac[1..], s, RepeatMacro::Yes),
+        MACRO_RELEASE_CANCEL | MACRO_RELEASE_CANCEL_A => {
+            parse_macro_release_cancel(&ac[1..], s, RepeatMacro::No)
+        }
+        MACRO_REPEAT_RELEASE_CANCEL | MACRO_REPEAT_RELEASE_CANCEL_A => {
+            parse_macro_release_cancel(&ac[1..], s, RepeatMacro::Yes)
+        }
+        MACRO_CANCEL_ON_NEXT_PRESS => {
+            parse_macro_cancel_on_next_press(&ac[1..], s, RepeatMacro::No)
+        }
+        MACRO_REPEAT_CANCEL_ON_NEXT_PRESS => {
+            parse_macro_cancel_on_next_press(&ac[1..], s, RepeatMacro::Yes)
+        }
+        MACRO_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE => {
+            parse_macro_cancel_on_next_press_cancel_on_release(&ac[1..], s, RepeatMacro::No)
+        }
+        MACRO_REPEAT_CANCEL_ON_NEXT_PRESS_CANCEL_ON_RELEASE => {
+            parse_macro_cancel_on_next_press_cancel_on_release(&ac[1..], s, RepeatMacro::Yes)
+        }
+        UNICODE | SYM => parse_unicode(&ac[1..], s),
+        ONE_SHOT | ONE_SHOT_PRESS | ONE_SHOT_PRESS_A => {
             parse_one_shot(&ac[1..], s, OneShotEndConfig::EndOnFirstPress)
         }
-        "one-shot-release" => parse_one_shot(&ac[1..], s, OneShotEndConfig::EndOnFirstRelease),
-        "one-shot-press-pcancel" => {
+        ONE_SHOT_RELEASE | ONE_SHOT_RELEASE_A => {
+            parse_one_shot(&ac[1..], s, OneShotEndConfig::EndOnFirstRelease)
+        }
+        ONE_SHOT_PRESS_PCANCEL | ONE_SHOT_PRESS_PCANCEL_A => {
             parse_one_shot(&ac[1..], s, OneShotEndConfig::EndOnFirstPressOrRepress)
         }
-        "one-shot-release-pcancel" => {
+        ONE_SHOT_RELEASE_PCANCEL | ONE_SHOT_RELEASE_PCANCEL_A => {
             parse_one_shot(&ac[1..], s, OneShotEndConfig::EndOnFirstReleaseOrRepress)
         }
-        "tap-dance" => parse_tap_dance(&ac[1..], s, TapDanceConfig::Lazy),
-        "tap-dance-eager" => parse_tap_dance(&ac[1..], s, TapDanceConfig::Eager),
-        "chord" => parse_chord(&ac[1..], s),
-        "release-key" => parse_release_key(&ac[1..], s),
-        "release-layer" => parse_release_layer(&ac[1..], s),
-        "on-press-fakekey" => parse_fake_key_op(&ac[1..], s),
-        "on-release-fakekey" => parse_on_release_fake_key_op(&ac[1..], s),
-        "on-press-fakekey-delay" => parse_fake_key_delay(&ac[1..], s),
-        "on-release-fakekey-delay" => parse_on_release_fake_key_delay(&ac[1..], s),
-        "mwheel-up" => parse_mwheel(&ac[1..], MWheelDirection::Up, s),
-        "mwheel-down" => parse_mwheel(&ac[1..], MWheelDirection::Down, s),
-        "mwheel-left" => parse_mwheel(&ac[1..], MWheelDirection::Left, s),
-        "mwheel-right" => parse_mwheel(&ac[1..], MWheelDirection::Right, s),
-        "movemouse-up" => parse_move_mouse(&ac[1..], MoveDirection::Up, s),
-        "movemouse-down" => parse_move_mouse(&ac[1..], MoveDirection::Down, s),
-        "movemouse-left" => parse_move_mouse(&ac[1..], MoveDirection::Left, s),
-        "movemouse-right" => parse_move_mouse(&ac[1..], MoveDirection::Right, s),
-        "movemouse-accel-up" => parse_move_mouse_accel(&ac[1..], MoveDirection::Up, s),
-        "movemouse-accel-down" => parse_move_mouse_accel(&ac[1..], MoveDirection::Down, s),
-        "movemouse-accel-left" => parse_move_mouse_accel(&ac[1..], MoveDirection::Left, s),
-        "movemouse-accel-right" => parse_move_mouse_accel(&ac[1..], MoveDirection::Right, s),
-        "setmouse" => parse_set_mouse(&ac[1..], s),
-        "dynamic-macro-record" => parse_dynamic_macro_record(&ac[1..], s),
-        "dynamic-macro-play" => parse_dynamic_macro_play(&ac[1..], s),
-        "arbitrary-code" => parse_arbitrary_code(&ac[1..], s),
-        "cmd" => parse_cmd(&ac[1..], s, CmdType::Standard),
-        "cmd-output-keys" => parse_cmd(&ac[1..], s, CmdType::OutputKeys),
-        "fork" => parse_fork(&ac[1..], s),
-        "caps-word" => parse_caps_word(&ac[1..], s),
-        "caps-word-custom" => parse_caps_word_custom(&ac[1..], s),
-        "dynamic-macro-record-stop-truncate" => parse_macro_record_stop_truncate(&ac[1..], s),
-        _ => bail_expr!(&ac[0], "Unknown action type: {ac_type}"),
-    }
-}
-
-fn parse_layer_base(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    Ok(s.a.sref(Action::DefaultLayer(
-        layer_idx(ac_params, &s.layer_idxs)? * 2,
-    )))
-}
-
-fn parse_layer_toggle(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    Ok(s.a.sref(Action::Layer(layer_idx(ac_params, &s.layer_idxs)? * 2 + 1)))
-}
-
-fn layer_idx(ac_params: &[SExpr], layers: &LayerIndexes) -> Result<usize> {
+        ONE_SHOT_PAUSE_PROCESSING => parse_one_shot_pause_processing(&ac[1..], s),
+        TAP_DANCE => parse_tap_dance(&ac[1..], s, TapDanceConfig::Lazy),
+        TAP_DANCE_EAGER => parse_tap_dance(&ac[1..], s, TapDanceConfig::Eager),
+        CHORD => parse_chord(&ac[1..], s),
+        RELEASE_KEY | RELEASE_KEY_A => parse_release_key(&ac[1..], s),
+        RELEASE_LAYER | RELEASE_LAYER_A => parse_release_layer(&ac[1..], s),
+        ON_PRESS_FAKEKEY | ON_PRESS_FAKEKEY_A => parse_on_press_fake_key_op(&ac[1..], s),
+        ON_RELEASE_FAKEKEY | ON_RELEASE_FAKEKEY_A => parse_on_release_fake_key_op(&ac[1..], s),
+        ON_PRESS_DELAY | ON_PRESS_FAKEKEY_DELAY | ON_PRESS_FAKEKEY_DELAY_A => {
+            parse_fake_key_delay(&ac[1..], s)
+        }
+        ON_RELEASE_DELAY | ON_RELEASE_FAKEKEY_DELAY | ON_RELEASE_FAKEKEY_DELAY_A => {
+            parse_on_release_fake_key_delay(&ac[1..], s)
+        }
+        ON_IDLE_FAKEKEY => parse_on_idle_fakekey(&ac[1..], s),
+        ON_PRESS | ON_PRESS_A => parse_on_press(&ac[1..], s),
+        ON_RELEASE | ON_RELEASE_A => parse_on_release(&ac[1..], s),
+        ON_IDLE => parse_on_idle(&ac[1..], s),
+        ON_PHYSICAL_IDLE => parse_on_physical_idle(&ac[1..], s),
+        HOLD_FOR_DURATION => parse_hold_for_duration(&ac[1..], s),
+        MWHEEL_UP | MWHEEL_UP_A => parse_mwheel(&ac[1..], MWheelDirection::Up, s),
+        MWHEEL_DOWN | MWHEEL_DOWN_A => parse_mwheel(&ac[1..], MWheelDirection::Down, s),
+        MWHEEL_LEFT | MWHEEL_LEFT_A => parse_mwheel(&ac[1..], MWheelDirection::Left, s),
+        MWHEEL_RIGHT | MWHEEL_RIGHT_A => parse_mwheel(&ac[1..], MWheelDirection::Right, s),
+        MWHEEL_ACCEL_UP => parse_mwheel_accel(&ac[1..], MWheelDirection::Up, s),
+        MWHEEL_ACCEL_DOWN => parse_mwheel_accel(&ac[1..], MWheelDirection::Down, s),
+        MWHEEL_ACCEL_LEFT => parse_mwheel_accel(&ac[1..], MWheelDirection::Left, s),
+        MWHEEL_ACCEL_RIGHT => parse_mwheel_accel(&ac[1..], MWheelDirection::Right, s),
+        MOVEMOUSE_UP | MOVEMOUSE_UP_A => parse_move_mouse(&ac[1..], MoveDirection::Up, s),
+        MOVEMOUSE_DOWN | MOVEMOUSE_DOWN_A => parse_move_mouse(&ac[1..], MoveDirection::Down, s),
+        MOVEMOUSE_LEFT | MOVEMOUSE_LEFT_A => parse_move_mouse(&ac[1..], MoveDirection::Left, s),
+        MOVEMOUSE_RIGHT | MOVEMOUSE_RIGHT_A => parse_move_mouse(&ac[1..], MoveDirection::Right, s),
+        MOVEMOUSE_ACCEL_UP | MOVEMOUSE_ACCEL_UP_A => {
+            parse_move_mouse_accel(&ac[1..], MoveDirection::Up, s)
+        }
+        MOVEMOUSE_ACCEL_DOWN | MOVEMOUSE_ACCEL_DOWN_A => {
+            parse_move_mouse_accel(&ac[1..], MoveDirection::Down, s)
+        }
+        MOVEMOUSE_ACCEL_LEFT | MOVEMOUSE_ACCEL_LEFT_A => {
+            parse_move_mouse_accel(&ac[1..], MoveDirection::Left, s)
+        }
+        MOVEMOUSE_ACCEL_RIGHT | MOVEMOUSE_ACCEL_RIGHT_A => {
+            parse_move_mouse_accel(&ac[1..], MoveDirection::Right, s)
+        }
+        MOVEMOUSE_SPEED | MOVEMOUSE_SPEED_A => parse_move_mouse_speed(&ac[1..], s),
+        SETMOUSE | SETMOUSE_A => parse_set_mouse(&ac[1..], s),
+        DYNAMIC_MACRO_RECORD => parse_dynamic_macro_record(&ac[1..], s),
+        DYNAMIC_MACRO_PLAY => parse_dynamic_macro_play(&ac[1..], s),
+        ARBITRARY_CODE => parse_arbitrary_code(&ac[1..], s),
+        CMD => parse_cmd(&ac[1..], s, CmdType::Standard),
+        CMD_OUTPUT_KEYS => parse_cmd(&ac[1..], s, CmdType::OutputKeys),
+        CMD_LOG => parse_cmd_log(&ac[1..], s),
+        PUSH_MESSAGE => parse_push_message(&ac[1..], s),
+        FORK => parse_fork(&ac[1..], s),
+        CAPS_WORD | CAPS_WORD_A => {
+            parse_caps_word(&ac[1..], CapsWordRepressBehaviour::Overwrite, s)
+        }
+        CAPS_WORD_CUSTOM | CAPS_WORD_CUSTOM_A => {
+            parse_caps_word_custom(&ac[1..], CapsWordRepressBehaviour::Overwrite, s)
+        }
+        CAPS_WORD_TOGGLE | CAPS_WORD_TOGGLE_A => {
+            parse_caps_word(&ac[1..], CapsWordRepressBehaviour::Toggle, s)
+        }
+        CAPS_WORD_CUSTOM_TOGGLE | CAPS_WORD_CUSTOM_TOGGLE_A => {
+            parse_caps_word_custom(&ac[1..], CapsWordRepressBehaviour::Toggle, s)
+        }
+        DYNAMIC_MACRO_RECORD_STOP_TRUNCATE => parse_macro_record_stop_truncate(&ac[1..], s),
+        SWITCH => parse_switch(&ac[1..], s),
+        SEQUENCE => parse_sequence_start(&ac[1..], s),
+        SEQUENCE_NOERASE => parse_sequence_noerase(&ac[1..], s),
+        UNMOD => parse_unmod(UNMOD, &ac[1..], s),
+        UNSHIFT | UNSHIFT_A => parse_unmod(UNSHIFT, &ac[1..], s),
+        LIVE_RELOAD_NUM => parse_live_reload_num(&ac[1..], s),
+        LIVE_RELOAD_FILE => parse_live_reload_file(&ac[1..], s),
+        CLIPBOARD_SET => parse_clipboard_set(&ac[1..], s),
+        CLIPBOARD_CMD_SET => parse_cmd(&ac[1..], s, CmdType::ClipboardSet),
+        CLIPBOARD_SAVE => parse_clipboard_save(&ac[1..], s),
+        CLIPBOARD_RESTORE => parse_clipboard_restore(&ac[1..], s),
+        CLIPBOARD_SAVE_SET => parse_clipboard_save_set(&ac[1..], s),
+        CLIPBOARD_SAVE_CMD_SET => parse_cmd(&ac[1..], s, CmdType::ClipboardSaveSet),
+        CLIPBOARD_SAVE_SWAP => parse_clipboard_save_swap(&ac[1..], s),
+        _ => unreachable!(),
+    }
+}
+
+fn layer_idx(ac_params: &[SExpr], layers: &LayerIndexes, s: &ParserState) -> Result<usize> {
     if ac_params.len() != 1 {
         bail!(
             "Layer actions expect one item: the layer name, found {} items",
             ac_params.len()
         )
     }
-    let layer_name = match &ac_params[0] {
-        SExpr::Atom(ln) => &ln.t,
-        _ => bail_expr!(&ac_params[0], "layer name should be a string not a list",),
-    };
+    let layer_name = ac_params[0]
+        .atom(s.vars())
+        .ok_or_else(|| anyhow_expr!(&ac_params[0], "layer name should be a string not a list",))?;
     match layers.get(layer_name) {
         Some(i) => Ok(*i),
-        None => bail_expr!(
+        None => err_expr!(
             &ac_params[0],
             "layer name is not declared in any deflayer: {layer_name}"
         ),
     }
 }
 
-fn parse_tap_hold(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    config: HoldTapConfig<'static>,
-) -> Result<&'static KanataAction> {
-    if ac_params.len() != 4 {
-        bail!(
-            r"tap-hold expects 4 items after it, got {}.
-Params in order:
-<tap-timeout> <hold-timeout> <tap-action> <hold-action>",
-            ac_params.len(),
-        )
-    }
-    let tap_timeout = parse_u16(&ac_params[0], s, "tap timeout")?;
-    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
-    let tap_action = parse_action(&ac_params[2], s)?;
-    let hold_action = parse_action(&ac_params[3], s)?;
-    if matches!(tap_action, Action::HoldTap { .. }) {
-        bail!("tap-hold does not work in the tap-action of tap-hold")
-    }
-    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
-        config,
-        tap_hold_interval: tap_timeout,
-        timeout: hold_timeout,
-        tap: *tap_action,
-        hold: *hold_action,
-        timeout_action: *hold_action,
-    }))))
-}
-
-fn parse_tap_hold_timeout(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    config: HoldTapConfig<'static>,
-) -> Result<&'static KanataAction> {
-    if ac_params.len() != 5 {
-        bail!(
-            r"tap-hold-(press|release)-timeout expects 5 items after it, got {}.
-Params in order:
-<tap-timeout> <hold-timeout> <tap-action> <hold-action> <timeout-action>",
-            ac_params.len(),
+/// Parse a list expression with length 2 having format:
+///     (name value)
+/// The items name and value must both be strings.
+/// The name string is validated to ensure it matches the input.
+/// The value is parsed into a u8.
+#[allow(unused)]
+fn parse_named_u8_param(name: &str, name_and_param: &SExpr, s: &ParserState) -> Result<u8> {
+    let err = || {
+        format!(
+            "Expected a list with two items: {name} followed by a number. Example:\n\
+             ({name} 2)"
         )
+    };
+    let Some(list) = name_and_param.list(s.vars()) else {
+        bail_expr!(name_and_param, "{}", err());
+    };
+    if list.len() != 2 {
+        bail_expr!(name_and_param, "{}", err());
     }
-    let tap_timeout = parse_u16(&ac_params[0], s, "tap timeout")?;
-    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
-    let tap_action = parse_action(&ac_params[2], s)?;
-    let hold_action = parse_action(&ac_params[3], s)?;
-    let timeout_action = parse_action(&ac_params[4], s)?;
-    if matches!(tap_action, Action::HoldTap { .. }) {
-        bail!("tap-hold does not work in the tap-action of tap-hold")
+    let Some(expr_name) = list[0].atom(s.vars()) else {
+        bail_expr!(&list[0], "Expected {name}");
+    };
+    if expr_name != name {
+        bail_expr!(&list[0], "Expected {name}");
     }
-    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
-        config,
-        tap_hold_interval: tap_timeout,
-        timeout: hold_timeout,
-        tap: *tap_action,
-        hold: *hold_action,
-        timeout_action: *timeout_action,
-    }))))
+    parse_u8_with_range(&list[1], s, name, 0, 255)
 }
 
-fn parse_tap_hold_release_keys(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    if ac_params.len() != 5 {
-        bail!(
-            r"tap-hold-release-keys expects 5 items after it, got {}.
-Params in order:
-<tap-timeout> <hold-timeout> <tap-action> <hold-action> <tap-trigger-keys>",
-            ac_params.len(),
-        )
-    }
-    let tap_timeout = parse_u16(&ac_params[0], s, "tap timeout")?;
-    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
-    let tap_action = parse_action(&ac_params[2], s)?;
-    let hold_action = parse_action(&ac_params[3], s)?;
-    let tap_trigger_keys = parse_key_list(&ac_params[4], s, "tap-trigger-keys")?;
-    if matches!(tap_action, Action::HoldTap { .. }) {
-        bail!("tap-hold does not work in the tap-action of tap-hold")
-    }
-    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
-        config: HoldTapConfig::Custom(custom_tap_hold_release(&tap_trigger_keys, &s.a)),
-        tap_hold_interval: tap_timeout,
-        timeout: hold_timeout,
-        tap: *tap_action,
-        hold: *hold_action,
-        timeout_action: *hold_action,
-    }))))
+fn parse_u8_with_range(expr: &SExpr, s: &ParserState, label: &str, min: u8, max: u8) -> Result<u8> {
+    expr.atom(s.vars())
+        .map(str::parse::<u8>)
+        .and_then(|u| u.ok())
+        .and_then(|u| {
+            assert!(min <= max);
+            if u >= min && u <= max { Some(u) } else { None }
+        })
+        .ok_or_else(|| anyhow_expr!(expr, "{label} must be {min}-{max}"))
 }
 
-fn parse_u16(expr: &SExpr, s: &ParsedState, label: &str) -> Result<u16> {
+fn parse_u16(expr: &SExpr, s: &ParserState, label: &str) -> Result<u16> {
     expr.atom(s.vars())
         .map(str::parse::<u16>)
         .and_then(|u| u.ok())
         .ok_or_else(|| anyhow_expr!(expr, "{label} must be 0-65535"))
 }
 
-fn parse_non_zero_u16(expr: &SExpr, s: &ParsedState, label: &str) -> Result<u16> {
+fn parse_f32(
+    expr: &SExpr,
+    s: &ParserState,
+    label: &str,
+    min: f32,
+    max: f32,
+) -> Result<OrderedFloat<f32>> {
+    expr.atom(s.vars())
+        .map(str::parse::<f32>)
+        .and_then(|u| {
+            u.ok().and_then(|v| {
+                if v >= min && v <= max {
+                    Some(v.into())
+                } else {
+                    None
+                }
+            })
+        })
+        .ok_or_else(|| anyhow_expr!(expr, "{label} must be {min:.2}-{max:.2}"))
+}
+
+// Note on allows:
+// - macOS CI is behind on Rust version.
+// - Clippy bug in new lint of Rust v1.86.
+#[allow(unknown_lints)]
+#[allow(clippy::manual_ok_err)]
+fn parse_non_zero_u16(expr: &SExpr, s: &ParserState, label: &str) -> Result<u16> {
     expr.atom(s.vars())
         .map(str::parse::<u16>)
         .and_then(|u| match u {
@@ -1329,7 +1781,7 @@ fn parse_non_zero_u16(expr: &SExpr, s: &ParsedState, label: &str) -> Result<u16>
         .ok_or_else(|| anyhow_expr!(expr, "{label} must be 1-65535"))
 }
 
-fn parse_key_list(expr: &SExpr, s: &ParsedState, label: &str) -> Result<Vec<OsCode>> {
+fn parse_key_list(expr: &SExpr, s: &ParserState, label: &str) -> Result<Vec<OsCode>> {
     expr.list(s.vars())
         .map(|keys| {
             keys.iter().try_fold(vec![], |mut keys, key| {
@@ -1349,227 +1801,41 @@ fn parse_key_list(expr: &SExpr, s: &ParsedState, label: &str) -> Result<Vec<OsCo
         .ok_or_else(|| anyhow_expr!(expr, "{label} must be a list of keys"))?
 }
 
-fn parse_multi(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    if ac_params.is_empty() {
-        bail!("multi expects at least one item after it")
-    }
-    let mut actions = Vec::new();
-    let mut custom_actions: Vec<&'static CustomAction> = Vec::new();
-    for expr in ac_params {
-        let ac = parse_action(expr, s)?;
-        match ac {
-            Action::Custom(acs) => {
-                for ac in acs.iter() {
-                    custom_actions.push(ac);
-                }
-            }
-            // Flatten multi actions
-            Action::MultipleActions(acs) => {
-                for ac in acs.iter() {
-                    match ac {
-                        Action::Custom(acs) => {
-                            for ac in acs.iter() {
-                                custom_actions.push(ac);
-                            }
-                        }
-                        _ => actions.push(*ac),
-                    }
-                }
-            }
-            _ => actions.push(*ac),
-        }
-    }
-
-    if !custom_actions.is_empty() {
-        actions.push(Action::Custom(s.a.sref(s.a.sref_vec(custom_actions))));
-    }
-
-    if actions
-        .iter()
-        .filter(|ac| {
-            matches!(
-                ac,
-                Action::TapDance(TapDance {
-                    config: TapDanceConfig::Lazy,
-                    ..
-                }) | Action::HoldTap { .. }
-                    | Action::Chords { .. }
-            )
-        })
-        .count()
-        > 1
-    {
-        bail!("Cannot combine multiple tap-hold/tap-dance/chord");
-    }
-
-    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(actions)))))
-}
-
-const MACRO_ERR: &str = "Action macro only accepts delays, keys, chords, and chorded sub-macros";
-enum RepeatMacro {
-    Yes,
-    No,
-}
-
-fn parse_macro(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    repeat: RepeatMacro,
-) -> Result<&'static KanataAction> {
-    if ac_params.is_empty() {
-        bail!("macro expects at least one item after it")
-    }
-    let mut all_events = Vec::with_capacity(256);
-    let mut params_remainder = ac_params;
-    while !params_remainder.is_empty() {
-        let mut events;
-        (events, params_remainder) = parse_macro_item(params_remainder, s)?;
-        all_events.append(&mut events);
-    }
-    all_events.push(SequenceEvent::Complete);
-    all_events.shrink_to_fit();
-    match repeat {
-        RepeatMacro::No => Ok(s.a.sref(Action::Sequence {
-            events: s.a.sref(s.a.sref(s.a.sref_vec(all_events))),
-        })),
-        RepeatMacro::Yes => Ok(s.a.sref(Action::RepeatableSequence {
-            events: s.a.sref(s.a.sref(s.a.sref_vec(all_events))),
-        })),
-    }
-}
-
-fn parse_macro_release_cancel(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    repeat: RepeatMacro,
-) -> Result<&'static KanataAction> {
-    let macro_action = parse_macro(ac_params, s, repeat)?;
-    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(vec![
-        *macro_action,
-        Action::Custom(s.a.sref(s.a.sref_slice(CustomAction::CancelMacroOnRelease))),
-    ])))))
-}
-
-#[derive(PartialEq)]
-enum MacroNumberParseMode {
-    Delay,
-    Action,
-}
-
-#[allow(clippy::type_complexity)] // return type is not pub
-fn parse_macro_item<'a>(
-    acs: &'a [SExpr],
-    s: &ParsedState,
-) -> Result<(
-    Vec<SequenceEvent<'static, &'static &'static [&'static CustomAction]>>,
-    &'a [SExpr],
-)> {
-    parse_macro_item_impl(acs, s, MacroNumberParseMode::Delay)
-}
-
-#[allow(clippy::type_complexity)] // return type is not pub
-fn parse_macro_item_impl<'a>(
-    acs: &'a [SExpr],
-    s: &ParsedState,
-    num_parse_mode: MacroNumberParseMode,
-) -> Result<(
-    Vec<SequenceEvent<'static, &'static &'static [&'static CustomAction]>>,
-    &'a [SExpr],
-)> {
-    if num_parse_mode == MacroNumberParseMode::Delay {
-        if let Some(a) = acs[0].atom(s.vars()) {
-            match parse_non_zero_u16(&acs[0], s, "delay") {
-                Ok(duration) => {
-                    let duration = u32::from(duration);
-                    return Ok((vec![SequenceEvent::Delay { duration }], &acs[1..]));
-                }
-                Err(e) => {
-                    if a.chars().all(|c| c.is_ascii_digit()) {
-                        return Err(e);
-                    }
-                }
-            }
-        }
-    }
-    match parse_action(&acs[0], s) {
-        Ok(Action::KeyCode(kc)) => {
-            // Should note that I tried `SequenceEvent::Tap` initially but it seems to be buggy
-            // so I changed the code to use individual press and release. The SequenceEvent
-            // code is from a PR that (at the time of this writing) hasn't yet been merged into
-            // keyberon master and doesn't have tests written for it yet. This seems to work as
-            // expected right now though.
-            Ok((
-                vec![SequenceEvent::Press(*kc), SequenceEvent::Release(*kc)],
-                &acs[1..],
-            ))
-        }
-        Ok(Action::MultipleKeyCodes(kcs)) => {
-            // chord - press in order then release in the reverse order
-            let mut events = vec![];
-            for kc in kcs.iter() {
-                events.push(SequenceEvent::Press(*kc));
-            }
-            for kc in kcs.iter().rev() {
-                events.push(SequenceEvent::Release(*kc));
-            }
-            Ok((events, &acs[1..]))
-        }
-        Ok(Action::Custom(custom)) => Ok((vec![SequenceEvent::Custom(custom)], &acs[1..])),
-        _ => {
-            let (held_mods, unparsed_str) = parse_mods_held_for_submacro(&acs[0], s)?;
-            let mut all_events = vec![];
-
-            // First, press all of the modifiers
-            for kc in held_mods.iter().copied() {
-                all_events.push(SequenceEvent::Press(kc));
-            }
-
-            let mut rem_start = 1;
-            let maybe_list_var = SExpr::Atom(Spanned::new(unparsed_str.into(), acs[0].span()));
-            let submacro = match maybe_list_var.list(s.vars()) {
-                Some(l) => l,
-                None => {
-                    rem_start = 2;
-                    if acs.len() < 2 {
-                        bail_expr!(&acs[1], "{MACRO_ERR}")
-                    }
-                    acs[1]
-                        .list(s.vars())
-                        .ok_or_else(|| anyhow_expr!(&acs[1], "{MACRO_ERR}"))?
-                }
-            };
-            let mut submacro_remainder = submacro;
-            let mut events;
-            while !submacro_remainder.is_empty() {
-                (events, submacro_remainder) = parse_macro_item(submacro_remainder, s)?;
-                all_events.append(&mut events);
-            }
-
-            // Lastly, release modifiers
-            for kc in held_mods.iter().copied() {
-                all_events.push(SequenceEvent::Release(kc));
-            }
-
-            Ok((all_events, &acs[rem_start..]))
-        }
-    }
-}
-
-/// Parses mod keys like `C-S-`. Returns the `KeyCode`s for the modifiers parsed and the unparsed
-/// text after any parsed modifier prefixes.
-fn parse_mods_held_for_submacro<'a>(
-    held_mods: &'a SExpr,
-    s: &'a ParsedState,
-) -> Result<(Vec<KeyCode>, &'a str)> {
-    let mods = held_mods
-        .atom(s.vars())
-        .ok_or_else(|| anyhow_expr!(held_mods, "{MACRO_ERR}"))?;
-    let (mod_keys, unparsed_str) = parse_mod_prefix(mods)?;
-    if mod_keys.is_empty() {
-        bail_expr!(held_mods, "{MACRO_ERR}");
-    }
-    Ok((mod_keys, unparsed_str))
-}
+static KEYMODI: &[(&str, KeyCode)] = &[
+    ("S-", KeyCode::LShift),
+    ("‹⇧", KeyCode::LShift),
+    ("⇧›", KeyCode::RShift),
+    ("RS-", KeyCode::RShift),
+    ("C-", KeyCode::LCtrl),
+    ("‹⎈", KeyCode::LCtrl),
+    ("‹⌃", KeyCode::LCtrl),
+    ("⎈›", KeyCode::RCtrl),
+    ("⌃›", KeyCode::RCtrl),
+    ("RC-", KeyCode::RCtrl),
+    ("M-", KeyCode::LGui),
+    ("‹◆", KeyCode::LGui),
+    ("‹⌘", KeyCode::LGui),
+    ("‹❖", KeyCode::LGui),
+    ("◆›", KeyCode::RGui),
+    ("⌘›", KeyCode::RGui),
+    ("❖›", KeyCode::RGui),
+    ("RM-", KeyCode::RGui),
+    ("‹⎇", KeyCode::LAlt),
+    ("A-", KeyCode::LAlt),
+    ("‹⌥", KeyCode::LAlt),
+    ("AG-", KeyCode::RAlt),
+    ("RA-", KeyCode::RAlt),
+    ("⎇›", KeyCode::RAlt),
+    ("⌥›", KeyCode::RAlt),
+    ("⎈", KeyCode::LCtrl), // Shorter indicators should be at the end to only get matched after
+    // indicators with sides have had a chance
+    ("⌥", KeyCode::LAlt),
+    ("⎇", KeyCode::LAlt),
+    ("◆", KeyCode::LGui),
+    ("⌘", KeyCode::LGui),
+    ("❖", KeyCode::LGui),
+    ("O-", KEY_OVERLAP),
+];
 
 /// Parses mod keys like `C-S-`. Returns the `KeyCode`s for the modifiers parsed and the unparsed
 /// text after any parsed modifier prefixes.
@@ -1577,1220 +1843,34 @@ pub fn parse_mod_prefix(mods: &str) -> Result<(Vec<KeyCode>, &str)> {
     let mut key_stack = Vec::new();
     let mut rem = mods;
     loop {
-        if let Some(rest) = rem.strip_prefix("C-") {
-            if key_stack.contains(&KeyCode::LCtrl) {
-                bail!("Redundant \"C-\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::LCtrl);
-            rem = rest;
-        } else if let Some(rest) = rem.strip_prefix("S-") {
-            if key_stack.contains(&KeyCode::LShift) {
-                bail!("Redundant \"S-\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::LShift);
-            rem = rest;
-        } else if let Some(rest) = rem.strip_prefix("AG-") {
-            if key_stack.contains(&KeyCode::RAlt) {
-                bail!("Redundant \"AltGr\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::RAlt);
-            rem = rest;
-        } else if let Some(rest) = rem.strip_prefix("RA-") {
-            if key_stack.contains(&KeyCode::RAlt) {
-                bail!("Redundant \"AltGr\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::RAlt);
-            rem = rest;
-        } else if let Some(rest) = rem.strip_prefix("A-") {
-            if key_stack.contains(&KeyCode::LAlt) {
-                bail!("Redundant \"A-\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::LAlt);
-            rem = rest;
-        } else if let Some(rest) = rem.strip_prefix("M-") {
-            if key_stack.contains(&KeyCode::LGui) {
-                bail!("Redundant \"M-\" in {mods:?}");
-            }
-            key_stack.push(KeyCode::LGui);
-            rem = rest;
-        } else {
-            break;
-        }
-    }
-    Ok((key_stack, rem))
-}
-
-fn parse_unicode(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_STR: &str = "unicode expects exactly one unicode character as an argument";
-    if ac_params.len() != 1 {
-        bail!(ERR_STR)
-    }
-    ac_params[0]
-        .atom(s.vars())
-        .map(|a| {
-            if a.chars().count() != 1 {
-                bail_expr!(&ac_params[0], "{ERR_STR}")
-            }
-            Ok(s.a.sref(Action::Custom(s.a.sref(s.a.sref_slice(
-                CustomAction::Unicode(a.chars().next().expect("1 char")),
-            )))))
-        })
-        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_STR}"))?
-}
-
-enum CmdType {
-    Standard,
-    OutputKeys,
-}
-
-fn parse_cmd(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    cmd_type: CmdType,
-) -> Result<&'static KanataAction> {
-    const ERR_STR: &str = "cmd expects one or more strings";
-    if !s.is_cmd_enabled {
-        bail!("cmd is not enabled but cmd action is specified somewhere");
-    }
-    if ac_params.is_empty() {
-        bail!(ERR_STR);
-    }
-    let cmd = ac_params
-        .iter()
-        .try_fold(vec![], |mut v, p| -> Result<Vec<_>> {
-            p.atom(s.vars())
-                .map(|a| v.push(a.trim_matches('"').to_owned()))
-                .ok_or_else(|| anyhow_expr!(p, "{}, lists are not allowed", ERR_STR))?;
-            Ok(v)
-        })?;
-    Ok(s.a
-        .sref(Action::Custom(s.a.sref(s.a.sref_slice(match cmd_type {
-            CmdType::Standard => CustomAction::Cmd(cmd),
-            CmdType::OutputKeys => CustomAction::CmdOutputKeys(cmd),
-        })))))
-}
-
-fn parse_one_shot(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    end_config: OneShotEndConfig,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "one-shot expects a timeout followed by a key or action";
-    if ac_params.len() != 2 {
-        bail!(ERR_MSG);
-    }
-
-    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
-    let action = parse_action(&ac_params[1], s)?;
-    if !matches!(
-        action,
-        Action::Layer(..) | Action::KeyCode(..) | Action::MultipleKeyCodes(..)
-    ) {
-        bail!("one-shot is only allowed to contain layer-while-held, a keycode, or a chord");
-    }
-
-    Ok(s.a.sref(Action::OneShot(s.a.sref(OneShot {
-        timeout,
-        action,
-        end_config,
-    }))))
-}
-
-fn parse_tap_dance(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-    config: TapDanceConfig,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "tap-dance expects a timeout (number) followed by a list of actions";
-    if ac_params.len() != 2 {
-        bail!(ERR_MSG);
-    }
-
-    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
-    let actions = ac_params[1]
-        .list(s.vars())
-        .map(|tap_dance_actions| -> Result<Vec<&'static KanataAction>> {
-            let mut actions = Vec::new();
-            for expr in tap_dance_actions {
-                let ac = parse_action(expr, s)?;
-                actions.push(ac);
-            }
-            Ok(actions)
-        })
-        .ok_or_else(|| anyhow_expr!(&ac_params[1], "{ERR_MSG}: expected a list"))??;
-
-    Ok(s.a.sref(Action::TapDance(s.a.sref(TapDance {
-        timeout,
-        actions: s.a.sref_vec(actions),
-        config,
-    }))))
-}
-
-fn parse_chord(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "Action chord expects a chords group name followed by an identifier";
-    if ac_params.len() != 2 {
-        bail!(ERR_MSG);
-    }
-
-    let name = ac_params[0]
-        .atom(s.vars())
-        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_MSG}"))?;
-    let group = match s.chord_groups.get(name) {
-        Some(t) => t,
-        None => bail_expr!(&ac_params[0], "Referenced unknown chord group: {}.", name),
-    };
-    let chord_key_index = ac_params[1]
-        .atom(s.vars())
-        .map(|s| match group.keys.iter().position(|e| e == s) {
-            Some(i) => Ok(i),
-            None => bail_expr!(
-                &ac_params[1],
-                r#"Identifier "{}" is not used in chord group "{}"."#,
-                &s,
-                name,
-            ),
-        })
-        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_MSG}"))??;
-    let chord_keys = 1 << chord_key_index;
-
-    // We don't yet know at this point what the entire chords group will look like nor at which
-    // coords this action will end up. So instead we store a dummy action which will be properly
-    // resolved in `resolve_chord_groups`.
-    Ok(s.a.sref(Action::Chords(s.a.sref(ChordsGroup {
-        timeout: group.timeout,
-        coords: s.a.sref_vec(vec![((0, group.id), chord_keys)]),
-        chords: s.a.sref_vec(vec![]),
-    }))))
-}
-
-fn parse_release_key(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "release-key expects exactly one keycode (e.g. lalt)";
-    if ac_params.len() != 1 {
-        bail!("{ERR_MSG}: found {} items", ac_params.len());
-    }
-    let ac = parse_action(&ac_params[0], s)?;
-    match ac {
-        Action::KeyCode(kc) => {
-            Ok(s.a.sref(Action::ReleaseState(ReleasableState::KeyCode(*kc))))
-        }
-        _ => bail_expr!(&ac_params[0], "{}", ERR_MSG),
-    }
-}
-
-fn parse_release_layer(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    Ok(s.a.sref(Action::ReleaseState(ReleasableState::Layer(
-        layer_idx(ac_params, &s.layer_idxs)? * 2 + 1,
-    ))))
-}
-
-fn parse_defsrc_layer(
-    defsrc: &[SExpr],
-    mapping_order: &[usize],
-    s: &ParsedState,
-) -> [KanataAction; KEYS_IN_ROW] {
-    let mut layer = [KanataAction::Trans; KEYS_IN_ROW];
-
-    // These can be default (empty) since the defsrc layer definitely won't use it.
-    for (i, ac) in defsrc.iter().skip(1).enumerate() {
-        let ac = parse_action(ac, s).expect("prechecked valid key names");
-        layer[mapping_order[i]] = *ac;
-    }
-    layer
-}
-
-fn parse_chord_groups(exprs: &[&Spanned<Vec<SExpr>>], s: &mut ParsedState) -> Result<()> {
-    const MSG: &str = "Incorrect number of elements found in defchords.\nThere should be the group name, followed by timeout, followed by keys-action pairs";
-    for expr in exprs {
-        let mut subexprs = check_first_expr(expr.t.iter(), "defchords")?;
-        let name = subexprs
-            .next()
-            .and_then(|e| e.atom(s.vars()))
-            .ok_or_else(|| anyhow_span!(expr, "{MSG}"))?
-            .to_owned();
-        let timeout = match subexprs.next() {
-            Some(e) => parse_non_zero_u16(e, s, "timeout")?,
-            None => bail_span!(expr, "{MSG}"),
-        };
-        let id = match s.chord_groups.len().try_into() {
-            Ok(id) => id,
-            Err(_) => bail_span!(expr, "Maximum number of chord groups exceeded."),
-        };
-        let mut group = ChordGroup {
-            id,
-            name: name.clone(),
-            keys: Vec::new(),
-            coords: Vec::new(),
-            chords: HashMap::default(),
-            timeout,
-        };
-        // Read k-v pairs from the configuration
-        while let Some(keys_expr) = subexprs.next() {
-            let action = match subexprs.next() {
-                Some(v) => v,
-                None => bail_expr!(
-                    keys_expr,
-                    "Key list found without action - add an action for this chord"
-                ),
-            };
-            let mut keys = keys_expr
-                .list(s.vars())
-                .map(|keys| {
-                    keys.iter().map(|key| {
-                        key.atom(s.vars()).ok_or_else(|| {
-                            anyhow_expr!(
-                                key,
-                                "Chord keys cannot be lists. Invalid key name: {:?}",
-                                key
-                            )
-                        })
-                    })
-                })
-                .ok_or_else(|| anyhow_expr!(keys_expr, "Chord must be a list/set of keys"))?;
-            let mask = keys.try_fold(0, |mask, key| {
-                let key = key?;
-                let index = match group.keys.iter().position(|k| k == key) {
-                    Some(i) => i,
-                    None => {
-                        let i = group.keys.len();
-                        if i + 1 > MAX_CHORD_KEYS {
-                            bail_expr!(keys_expr, "Maximum number of keys in a chords group ({MAX_CHORD_KEYS}) exceeded - found {}", i + 1);
-                        }
-                        group.keys.push(key.to_owned());
-                        i
-                    }
-                };
-                Ok(mask | (1 << index))
-            })?;
-            if group.chords.insert(mask, action.clone()).is_some() {
-                bail_expr!(keys_expr, "Duplicate chord in group {name}");
-            }
-        }
-        if s.chord_groups.insert(name.to_owned(), group).is_some() {
-            bail_span!(expr, "Duplicate chords group: {}", name);
-        }
-    }
-    Ok(())
-}
-
-fn resolve_chord_groups(layers: &mut KanataLayers, s: &ParsedState) -> Result<()> {
-    let mut chord_groups = s.chord_groups.values().cloned().collect::<Vec<_>>();
-    chord_groups.sort_by_key(|group| group.id);
-
-    for layer in layers.iter() {
-        for (i, row) in layer.iter().enumerate() {
-            for (j, cell) in row.iter().enumerate() {
-                find_chords_coords(&mut chord_groups, (i as u8, j as u16), cell);
-            }
-        }
-    }
-
-    let chord_groups = chord_groups.into_iter().map(|group| {
-        // Check that all keys in the chord group have been assigned to some coordinate
-        for (key_index, key) in group.keys.iter().enumerate() {
-            let key_mask = 1 << key_index;
-            if !group.coords.iter().any(|(_, keys)| keys & key_mask != 0) {
-                bail!("coord group `{0}` defines unused key `{1}`, did you forget to bind `(chord {0} {1})`?", group.name, key)
-            }
-        }
-
-        let chords = group.chords.iter().map(|(mask, action)| {
-            Ok((*mask, parse_action(action, s)?))
-        }).collect::<Result<Vec<_>>>()?;
-
-        Ok(s.a.sref(ChordsGroup {
-            coords: s.a.sref_vec(group.coords),
-            chords: s.a.sref_vec(chords),
-            timeout: group.timeout,
-        }))
-    }).collect::<Result<Vec<_>>>()?;
-
-    for layer in layers.iter_mut() {
-        for row in layer.iter_mut() {
-            for cell in row.iter_mut() {
-                if let Some(action) = fill_chords(&chord_groups, cell, s) {
-                    *cell = action;
+        let mut found_none = true;
+        for (key_s, key_code) in KEYMODI {
+            if let Some(rest) = rem.strip_prefix(key_s) {
+                if key_stack.contains(key_code) {
+                    bail!("Redundant \"{key_code:?}\" in {mods:?}");
                 }
+                key_stack.push(*key_code);
+                rem = rest;
+                found_none = false;
             }
         }
-    }
-
-    Ok(())
-}
-
-fn find_chords_coords(chord_groups: &mut [ChordGroup], coord: (u8, u16), action: &KanataAction) {
-    match action {
-        Action::Chords(ChordsGroup { coords, .. }) => {
-            for ((_, group_id), chord_keys) in coords.iter() {
-                let group = &mut chord_groups[*group_id as usize];
-                group.coords.push((coord, *chord_keys));
-            }
-        }
-        Action::NoOp
-        | Action::Trans
-        | Action::Repeat
-        | Action::KeyCode(_)
-        | Action::MultipleKeyCodes(_)
-        | Action::Layer(_)
-        | Action::DefaultLayer(_)
-        | Action::Sequence { .. }
-        | Action::RepeatableSequence { .. }
-        | Action::CancelSequences
-        | Action::ReleaseState(_)
-        | Action::Custom(_) => {}
-        Action::HoldTap(HoldTapAction { tap, hold, .. }) => {
-            find_chords_coords(chord_groups, coord, tap);
-            find_chords_coords(chord_groups, coord, hold);
-        }
-        Action::OneShot(OneShot { action: ac, .. }) => {
-            find_chords_coords(chord_groups, coord, ac);
-        }
-        Action::MultipleActions(actions) => {
-            for ac in actions.iter() {
-                find_chords_coords(chord_groups, coord, ac);
-            }
-        }
-        Action::TapDance(TapDance { actions, .. }) => {
-            for ac in actions.iter() {
-                find_chords_coords(chord_groups, coord, ac);
-            }
-        }
-        Action::Fork(ForkConfig { left, right, .. }) => {
-            find_chords_coords(chord_groups, coord, left);
-            find_chords_coords(chord_groups, coord, right);
-        }
-    }
-}
-
-fn fill_chords(
-    chord_groups: &[&'static ChordsGroup<&&[&CustomAction]>],
-    action: &KanataAction,
-    s: &ParsedState,
-) -> Option<KanataAction> {
-    match action {
-        Action::Chords(ChordsGroup { coords, .. }) => {
-            let ((_, group_id), _) = coords
-                .iter()
-                .next()
-                .expect("unresolved chords should have exactly one entry");
-            Some(Action::Chords(chord_groups[*group_id as usize]))
-        }
-        Action::NoOp
-        | Action::Trans
-        | Action::Repeat
-        | Action::KeyCode(_)
-        | Action::MultipleKeyCodes(_)
-        | Action::Layer(_)
-        | Action::DefaultLayer(_)
-        | Action::Sequence { .. }
-        | Action::RepeatableSequence { .. }
-        | Action::CancelSequences
-        | Action::ReleaseState(_)
-        | Action::Custom(_) => None,
-        Action::HoldTap(&hta @ HoldTapAction { tap, hold, .. }) => {
-            let new_tap = fill_chords(chord_groups, &tap, s);
-            let new_hold = fill_chords(chord_groups, &hold, s);
-            if new_tap.is_some() || new_hold.is_some() {
-                Some(Action::HoldTap(s.a.sref(HoldTapAction {
-                    hold: new_hold.unwrap_or(hold),
-                    tap: new_tap.unwrap_or(tap),
-                    ..hta
-                })))
-            } else {
-                None
-            }
-        }
-        Action::OneShot(&os @ OneShot { action: ac, .. }) => {
-            fill_chords(chord_groups, ac, s).map(|ac| {
-                Action::OneShot(s.a.sref(OneShot {
-                    action: s.a.sref(ac),
-                    ..os
-                }))
-            })
-        }
-        Action::MultipleActions(actions) => {
-            let new_actions = actions
-                .iter()
-                .map(|ac| fill_chords(chord_groups, ac, s))
-                .collect::<Vec<_>>();
-            if new_actions.iter().any(|it| it.is_some()) {
-                let new_actions = new_actions
-                    .iter()
-                    .zip(**actions)
-                    .map(|(new_ac, ac)| new_ac.unwrap_or(*ac))
-                    .collect::<Vec<_>>();
-                Some(Action::MultipleActions(s.a.sref(s.a.sref_vec(new_actions))))
-            } else {
-                None
-            }
-        }
-        Action::TapDance(&td @ TapDance { actions, .. }) => {
-            let new_actions = actions
-                .iter()
-                .map(|ac| fill_chords(chord_groups, ac, s))
-                .collect::<Vec<_>>();
-            if new_actions.iter().any(|it| it.is_some()) {
-                let new_actions = new_actions
-                    .iter()
-                    .zip(actions)
-                    .map(|(new_ac, ac)| new_ac.map(|v| s.a.sref(v)).unwrap_or(*ac))
-                    .collect::<Vec<_>>();
-                Some(Action::TapDance(s.a.sref(TapDance {
-                    actions: s.a.sref_vec(new_actions),
-                    ..td
-                })))
-            } else {
-                None
-            }
-        }
-        Action::Fork(&fcfg @ ForkConfig { left, right, .. }) => {
-            let new_left = fill_chords(chord_groups, &left, s);
-            let new_right = fill_chords(chord_groups, &right, s);
-            if new_left.is_some() || new_right.is_some() {
-                Some(Action::Fork(s.a.sref(ForkConfig {
-                    left: new_left.unwrap_or(left),
-                    right: new_right.unwrap_or(right),
-                    ..fcfg
-                })))
-            } else {
-                None
-            }
-        }
-    }
-}
-
-fn parse_fake_keys(exprs: &[&Vec<SExpr>], s: &mut ParsedState) -> Result<()> {
-    for expr in exprs {
-        let mut subexprs = check_first_expr(expr.iter(), "deffakekeys")?;
-        // Read k-v pairs from the configuration
-        while let Some(key_name_expr) = subexprs.next() {
-            let key_name = key_name_expr
-                .atom(s.vars())
-                .ok_or_else(|| anyhow_expr!(key_name_expr, "Fake key name must not be a list."))?
-                .to_owned();
-            let action = match subexprs.next() {
-                Some(v) => v,
-                None => bail_expr!(
-                    key_name_expr,
-                    "Fake key name has no action - you should add an action."
-                ),
-            };
-            let action = parse_action(action, s)?;
-            let idx = s.fake_keys.len();
-            log::trace!("inserting {key_name}->{idx}:{action:?}");
-            if s.fake_keys
-                .insert(key_name.clone(), (idx, action))
-                .is_some()
-            {
-                bail_expr!(key_name_expr, "Duplicate fake key: {}", key_name);
-            }
-        }
-    }
-    if s.fake_keys.len() > KEYS_IN_ROW {
-        bail!(
-            "Maximum number of fake keys is {KEYS_IN_ROW}, found {}",
-            s.fake_keys.len()
-        );
-    }
-    Ok(())
-}
-
-fn parse_fake_key_op(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    let (coord, action) = parse_fake_key_op_coord_action(ac_params, s)?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(s.a.sref_slice(CustomAction::FakeKey { coord, action })),
-    )))
-}
-
-fn parse_on_release_fake_key_op(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    let (coord, action) = parse_fake_key_op_coord_action(ac_params, s)?;
-    Ok(s.a.sref(Action::Custom(s.a.sref(
-        s.a.sref_slice(CustomAction::FakeKeyOnRelease { coord, action }),
-    ))))
-}
-
-fn parse_fake_key_op_coord_action(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<(Coord, FakeKeyAction)> {
-    const ERR_MSG: &str =
-        "on-(press|release)-fakekey expects two parameters: <fake key name> <(tap|press|release)>";
-    if ac_params.len() != 2 {
-        bail!("{ERR_MSG}");
-    }
-    let y = match s.fake_keys.get(ac_params[0].atom(s.vars()).ok_or_else(|| {
-        anyhow_expr!(
-            &ac_params[0],
-            "{ERR_MSG}\nA list is not allowed for a fake key name",
-        )
-    })?) {
-        Some((y, _)) => *y as u8, // cast should be safe; checked in `parse_fake_keys`
-        None => bail_expr!(&ac_params[0], "unknown fake key name {:?}", &ac_params[0]),
-    };
-    let action = ac_params[1]
-        .atom(s.vars())
-        .map(|a| match a {
-            "tap" => Ok(FakeKeyAction::Tap),
-            "press" => Ok(FakeKeyAction::Press),
-            "release" => Ok(FakeKeyAction::Release),
-            _ => bail_expr!(
-                &ac_params[1],
-                "{ERR_MSG}\nInvalid second parameter, it must be one of: tap, press, release",
-            ),
-        })
-        .ok_or_else(|| {
-            anyhow_expr!(
-                &ac_params[1],
-                "{ERR_MSG}\nInvalid second parameter, it must be one of: tap, press, release",
-            )
-        })??;
-    let (x, y) = get_fake_key_coords(y);
-    Ok((Coord { x, y }, action))
-}
-
-fn get_fake_key_coords<T: Into<usize>>(y: T) -> (u8, u16) {
-    let y: usize = y.into();
-    (1, y as u16)
-}
-
-fn parse_fake_key_delay(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    parse_delay(ac_params, false, s)
-}
-
-fn parse_on_release_fake_key_delay(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    parse_delay(ac_params, true, s)
-}
-
-fn parse_delay(
-    ac_params: &[SExpr],
-    is_release: bool,
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "fakekey-delay expects a single number (ms, 0-65535)";
-    let delay = ac_params[0]
-        .atom(s.vars())
-        .map(str::parse::<u16>)
-        .ok_or_else(|| anyhow!("{ERR_MSG}"))?
-        .map_err(|e| anyhow!("{ERR_MSG}: {e}"))?;
-    Ok(s.a
-        .sref(Action::Custom(s.a.sref(s.a.sref_slice(match is_release {
-            false => CustomAction::Delay(delay),
-            true => CustomAction::DelayOnRelease(delay),
-        })))))
-}
-
-fn parse_distance(expr: &SExpr, s: &ParsedState, label: &str) -> Result<u16> {
-    expr.atom(s.vars())
-        .map(str::parse::<u16>)
-        .and_then(|d| match d {
-            Ok(dist @ 1..=30000) => Some(dist),
-            _ => None,
-        })
-        .ok_or_else(|| anyhow_expr!(expr, "{label} must be 1-30000"))
-}
-
-fn parse_mwheel(
-    ac_params: &[SExpr],
-    direction: MWheelDirection,
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "mwheel expects 2 parameters: <interval (ms)> <distance>";
-    if ac_params.len() != 2 {
-        bail!("{ERR_MSG}, found {}", ac_params.len());
-    }
-    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
-    let distance = parse_distance(&ac_params[1], s, "distance")?;
-    Ok(s.a.sref(Action::Custom(s.a.sref(s.a.sref_slice(
-        CustomAction::MWheel {
-            direction,
-            interval,
-            distance,
-        },
-    )))))
-}
-
-fn parse_move_mouse(
-    ac_params: &[SExpr],
-    direction: MoveDirection,
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "movemouse expects 2 parameters: <interval (ms)> <distance (px)>";
-    if ac_params.len() != 2 {
-        bail!("{ERR_MSG}, found {}", ac_params.len());
-    }
-    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
-    let distance = parse_distance(&ac_params[1], s, "distance")?;
-    Ok(s.a.sref(Action::Custom(s.a.sref(s.a.sref_slice(
-        CustomAction::MoveMouse {
-            direction,
-            interval,
-            distance,
-        },
-    )))))
-}
-
-fn parse_move_mouse_accel(
-    ac_params: &[SExpr],
-    direction: MoveDirection,
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    if ac_params.len() != 4 {
-        bail!("movemouse-accel expects four parameters, found {}\n<interval (ms)> <acceleration time (ms)> <min_distance> <max_distance>", ac_params.len());
-    }
-    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
-    let accel_time = parse_non_zero_u16(&ac_params[1], s, "acceleration time")?;
-    let min_distance = parse_distance(&ac_params[2], s, "min distance")?;
-    let max_distance = parse_distance(&ac_params[3], s, "max distance")?;
-    if min_distance > max_distance {
-        bail!("min distance should be less than max distance")
-    }
-    Ok(s.a.sref(Action::Custom(s.a.sref(s.a.sref_slice(
-        CustomAction::MoveMouseAccel {
-            direction,
-            interval,
-            accel_time,
-            min_distance,
-            max_distance,
-        },
-    )))))
-}
-
-fn parse_set_mouse(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    if ac_params.len() != 2 {
-        bail!(
-            "movemouse-accel expects two parameters, found {}: <x> <y>",
-            ac_params.len()
-        );
-    }
-    let x = parse_u16(&ac_params[0], s, "x")?;
-    let y = parse_u16(&ac_params[1], s, "y")?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(s.a.sref_slice(CustomAction::SetMouse { x, y })),
-    )))
-}
-
-fn parse_dynamic_macro_record(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "dynamic-macro-record expects 1 parameter: <macro ID (0-65535)>";
-    if ac_params.len() != 1 {
-        bail!("{ERR_MSG}, found {}", ac_params.len());
-    }
-    let key = parse_u16(&ac_params[0], s, "macro ID")?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(s.a.sref_slice(CustomAction::DynamicMacroRecord(key))),
-    )))
-}
-
-fn parse_dynamic_macro_play(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "dynamic-macro-play expects 1 parameter: <macro ID (number 0-65535)>";
-    if ac_params.len() != 1 {
-        bail!("{ERR_MSG}, found {}", ac_params.len());
-    }
-    let key = parse_u16(&ac_params[0], s, "macro ID")?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(s.a.sref_slice(CustomAction::DynamicMacroPlay(key))),
-    )))
-}
-
-fn parse_layers(s: &mut ParsedState) -> Result<Box<KanataLayers>> {
-    // There are two copies/versions of each layer. One is used as the target of "layer-switch" and
-    // the other is the target of "layer-while-held".
-    let mut layers_cfg = new_layers();
-    for (layer_level, layer) in s.layer_exprs.iter().enumerate() {
-        // The skip is done to skip the the `deflayer` and layer name tokens.
-        for (i, ac) in layer.iter().skip(2).enumerate() {
-            // Parse actions in the layer and place them appropriately.
-            let ac = parse_action(ac, s)?;
-            layers_cfg[layer_level * 2][0][s.mapping_order[i]] = *ac;
-            layers_cfg[layer_level * 2 + 1][0][s.mapping_order[i]] = *ac;
-        }
-        for (i, (layer_action, defsrc_action)) in layers_cfg[layer_level * 2][0]
-            .iter_mut()
-            .zip(s.defsrc_layer)
-            .enumerate()
-        {
-            // Set transparent actions in the "layer-switch" version of the layer according to
-            // defsrc action.
-            if *layer_action == Action::Trans {
-                *layer_action = defsrc_action;
-            }
-            // If there is no corresponding action in defsrc, default to the OsCode at the
-            // position. This is done so that `process-unmapped-keys` works correctly.
-            if *layer_action == Action::Trans {
-                *layer_action = OsCode::from_u16(i as u16)
-                    .and_then(|osc| match KeyCode::from(osc) {
-                        KeyCode::No => None,
-                        kc => Some(Action::KeyCode(kc)),
-                    })
-                    .unwrap_or(Action::Trans);
-            }
-        }
-        // Set fake keys on the `layer-switch` version of each layer.
-        for (y, action) in s.fake_keys.values() {
-            let (x, y) = get_fake_key_coords(*y);
-            layers_cfg[layer_level * 2][x as usize][y as usize] = **action;
-        }
-
-        // If the user has configured delegation to the first (default) layer for transparent keys,
-        // (as opposed to delegation to defsrc), replace the defsrc actions with the actions from
-        // the first layer.
-        if layer_level == 0 && s.delegate_to_first_layer {
-            for (defsrc_ac, default_layer_ac) in s.defsrc_layer.iter_mut().zip(layers_cfg[0][0]) {
-                *defsrc_ac = default_layer_ac;
-            }
-        }
-    }
-    Ok(layers_cfg)
-}
-
-const SEQ_ERR: &str = "defseq expects pairs of parameters: <fake_key_name> <key_list>";
-
-fn parse_sequences(exprs: &[&Vec<SExpr>], s: &ParsedState) -> Result<KeySeqsToFKeys> {
-    let mut sequences = Trie::new();
-    for expr in exprs {
-        let mut subexprs = check_first_expr(expr.iter(), "defseq")?.peekable();
-
-        while let Some(fake_key_expr) = subexprs.next() {
-            let fake_key = fake_key_expr.atom(s.vars()).ok_or_else(|| {
-                anyhow_expr!(fake_key_expr, "{SEQ_ERR}\nGot a list for fake_key_name")
-            })?;
-            if !s.fake_keys.contains_key(fake_key) {
-                bail_expr!(
-                    fake_key_expr,
-                    "{SEQ_ERR}\nThe referenced key does not exist: {fake_key}"
-                );
-            }
-            let key_seq_expr = subexprs.next().ok_or_else(|| {
-                anyhow_expr!(fake_key_expr, "{SEQ_ERR}\nMissing key_list for {fake_key}")
-            })?;
-            let key_seq = key_seq_expr.list(s.vars()).ok_or_else(|| {
-                anyhow_expr!(key_seq_expr, "{SEQ_ERR}\nGot a non-list for key_list")
-            })?;
-            if key_seq.is_empty() {
-                bail_expr!(key_seq_expr, "{SEQ_ERR}\nkey_list cannot be empty");
-            }
-            let keycode_seq = parse_sequence_keys(key_seq, s)?;
-            if sequences.ancestor_exists(&keycode_seq) {
-                bail_expr!(
-                    key_seq_expr,
-                    "Sequence has a conflict: its sequence contains an earlier defined sequence"
-                );
-            }
-            if sequences.descendant_exists(&keycode_seq) {
-                bail_expr!(key_seq_expr, "Sequence has a conflict: its sequence is contained within an earlier defined seqence");
-            }
-            sequences.insert(
-                keycode_seq,
-                s.fake_keys
-                    .get(fake_key)
-                    .map(|(y, _)| get_fake_key_coords(*y))
-                    .expect("fk exists, checked earlier"),
-            );
-        }
-    }
-    Ok(sequences)
-}
-
-fn parse_sequence_keys(exprs: &[SExpr], s: &ParsedState) -> Result<Vec<u16>> {
-    use crate::sequences::*;
-    use SequenceEvent::*;
-
-    // Reuse macro parsing but do some other processing since sequences don't support everything
-    // that can go in a macro, and also change error messages of course.
-    let mut exprs_remaining = exprs;
-    let mut all_keys = Vec::new();
-    while !exprs_remaining.is_empty() {
-        let (mut keys, exprs_remaining_tmp) =
-            match parse_macro_item_impl(exprs_remaining, s, MacroNumberParseMode::Action) {
-                Ok(res) => {
-                    if res.0.iter().any(|k| !matches!(k, Press(..) | Release(..))) {
-                        // Determine the bad expression depending on how many expressions were consumed
-                        // by parse_macro_item_impl.
-                        let bad_expr = if exprs_remaining.len() - res.1.len() == 1 {
-                            &exprs_remaining[0]
-                        } else {
-                            // This error message will have an imprecise span since it will take the
-                            // whole chorded list instead of the single element inside that's not a
-                            // standard key. Oh well, should still be helpful. I'm too lazy to write
-                            // the code to find the exact expr to use right now.
-                            &exprs_remaining[1]
-                        };
-                        bail_expr!(bad_expr, "{SEQ_ERR}\nFound invalid key/chord in key_list");
-                    }
-
-                    // The keys are currenty in the form of SequenceEvent::{Press, Release}. This is
-                    // not what we want.
-                    //
-                    // The trivial and incorrect way to parse this would be to just take all of the
-                    // presses. However, we need to transform chorded keys/lists like S-a or S-(a b) to
-                    // have the upper bits set, to be able to differentiate (S-a b) from (S-(a b)).
-                    //
-                    // The order of presses and releases reveals whether or not a key is chorded with
-                    // some modifier. When a chord starts, there are multiple presses in a row, whereas
-                    // non-chords will always be a press followed by a release. Likewise, a chord
-                    // ending is marked by multiple releases in a row.
-                    let mut mods_currently_held = vec![];
-                    let mut key_actions = res.0.iter().peekable();
-                    let mut seq = vec![];
-                    let mut do_release_mod = false;
-                    while let Some(action) = key_actions.next() {
-                        match action {
-                            Press(pressed) => {
-                                if matches!(key_actions.peek(), Some(Press(..))) {
-                                    // press->press: current press is mod
-                                    mods_currently_held.push(*pressed);
-                                }
-                                let mut seq_num = u16::from(OsCode::from(pressed));
-                                for modk in mods_currently_held.iter().copied() {
-                                    seq_num |= mod_mask_for_keycode(modk);
-                                }
-                                seq.push(seq_num);
-                            }
-                            Release(released) => {
-                                if do_release_mod {
-                                    mods_currently_held.remove(
-                                        mods_currently_held
-                                            .iter()
-                                            .position(|modk| modk == released)
-                                            .expect("had to be pressed to be released"),
-                                    );
-                                }
-                                // release->release: next release is mod
-                                do_release_mod = matches!(key_actions.peek(), Some(Release(..)));
-                            }
-                            _ => unreachable!("should be filtered out"),
-                        }
-                    }
-
-                    (seq, res.1)
-                }
-                Err(mut e) => {
-                    e.help_msg = format!("{SEQ_ERR}\nFound invalid key/chord in key_list");
-                    return Err(e);
-                }
-            };
-        all_keys.append(&mut keys);
-        exprs_remaining = exprs_remaining_tmp;
-    }
-    Ok(all_keys)
-}
-
-fn parse_arbitrary_code(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_MSG: &str = "arbitrary code expects one parameter: <code: 0-767>";
-    if ac_params.len() != 1 {
-        bail!("{ERR_MSG}");
-    }
-    let code = ac_params[0]
-        .atom(s.vars())
-        .map(str::parse::<u16>)
-        .and_then(|c| match c {
-            Ok(code @ 0..=767) => Some(code),
-            _ => None,
-        })
-        .ok_or_else(|| anyhow!("{ERR_MSG}: got {:?}", ac_params[0]))?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(s.a.sref_slice(CustomAction::SendArbitraryCode(code))),
-    )))
-}
-
-fn parse_overrides(exprs: &[SExpr], s: &ParsedState) -> Result<Overrides> {
-    const ERR_MSG: &str =
-        "defoverrides expects pairs of parameters: <input key list> <output key list>";
-    let mut subexprs = check_first_expr(exprs.iter(), "defoverrides")?;
-
-    let mut overrides = Vec::<Override>::new();
-    while let Some(in_keys_expr) = subexprs.next() {
-        let in_keys = in_keys_expr
-            .list(s.vars())
-            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Input keys must be a list"))?;
-        let out_keys_expr = subexprs
-            .next()
-            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Missing output keys for input keys"))?;
-        let out_keys = out_keys_expr
-            .list(s.vars())
-            .ok_or_else(|| anyhow_expr!(out_keys_expr, "Output keys must be a list"))?;
-        let in_keys =
-            in_keys
-                .iter()
-                .try_fold(vec![], |mut keys, key_expr| -> Result<Vec<OsCode>> {
-                    let key = key_expr
-                        .atom(s.vars())
-                        .and_then(str_to_oscode)
-                        .ok_or_else(|| {
-                            anyhow_expr!(key_expr, "Unknown input key name, must use known keys")
-                        })?;
-                    keys.push(key);
-                    Ok(keys)
-                })?;
-        let out_keys =
-            out_keys
-                .iter()
-                .try_fold(vec![], |mut keys, key_expr| -> Result<Vec<OsCode>> {
-                    let key = key_expr
-                        .atom(s.vars())
-                        .and_then(str_to_oscode)
-                        .ok_or_else(|| {
-                            anyhow_expr!(key_expr, "Unknown output key name, must use known keys")
-                        })?;
-                    keys.push(key);
-                    Ok(keys)
-                })?;
-        overrides
-            .push(Override::try_new(&in_keys, &out_keys).map_err(|e| anyhow!("{ERR_MSG}: {e}"))?);
-    }
-    log::debug!("All overrides:\n{overrides:#?}");
-    Ok(Overrides::new(&overrides))
-}
-
-fn parse_fork(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_STR: &str =
-        "fork expects 3 params: <left-action> <right-action> <right-trigger-keys>";
-    if ac_params.len() != 3 {
-        bail!("{ERR_STR}\nFound {} params instead of 3", ac_params.len());
-    }
-    let left = *parse_action(&ac_params[0], s)?;
-    let right = *parse_action(&ac_params[1], s)?;
-    let right_triggers = s.a.sref_vec(
-        parse_key_list(&ac_params[2], s, "right-trigger-keys")?
-            .into_iter()
-            .map(KeyCode::from)
-            .collect::<Vec<_>>(),
-    );
-    Ok(s.a.sref(Action::Fork(s.a.sref(ForkConfig {
-        left,
-        right,
-        right_triggers,
-    }))))
-}
-
-fn parse_caps_word(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_STR: &str = "caps-word expects 1 param: <timeout>";
-    if ac_params.len() != 1 {
-        bail!("{ERR_STR}\nFound {} params instead of 1", ac_params.len());
-    }
-    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
-    Ok(s.a.sref(Action::Custom(s.a.sref(s.a.sref_slice(
-        CustomAction::CapsWord(CapsWordCfg {
-            keys_to_capitalize: &[
-                KeyCode::A,
-                KeyCode::B,
-                KeyCode::C,
-                KeyCode::D,
-                KeyCode::E,
-                KeyCode::F,
-                KeyCode::G,
-                KeyCode::H,
-                KeyCode::I,
-                KeyCode::J,
-                KeyCode::K,
-                KeyCode::L,
-                KeyCode::M,
-                KeyCode::N,
-                KeyCode::O,
-                KeyCode::P,
-                KeyCode::Q,
-                KeyCode::R,
-                KeyCode::S,
-                KeyCode::T,
-                KeyCode::U,
-                KeyCode::V,
-                KeyCode::W,
-                KeyCode::X,
-                KeyCode::Y,
-                KeyCode::Z,
-                KeyCode::Minus,
-            ],
-            keys_nonterminal: &[
-                KeyCode::Kb0,
-                KeyCode::Kb1,
-                KeyCode::Kb2,
-                KeyCode::Kb3,
-                KeyCode::Kb4,
-                KeyCode::Kb5,
-                KeyCode::Kb6,
-                KeyCode::Kb7,
-                KeyCode::Kb8,
-                KeyCode::Kb9,
-                KeyCode::Kp0,
-                KeyCode::Kp1,
-                KeyCode::Kp2,
-                KeyCode::Kp3,
-                KeyCode::Kp4,
-                KeyCode::Kp5,
-                KeyCode::Kp6,
-                KeyCode::Kp7,
-                KeyCode::Kp8,
-                KeyCode::Kp9,
-                KeyCode::BSpace,
-                KeyCode::Delete,
-                KeyCode::Up,
-                KeyCode::Down,
-                KeyCode::Left,
-                KeyCode::Right,
-            ],
-            timeout,
-        }),
-    )))))
-}
-
-fn parse_caps_word_custom(ac_params: &[SExpr], s: &ParsedState) -> Result<&'static KanataAction> {
-    const ERR_STR: &str = "caps-word-custom expects 3 param: <timeout> <keys-to-capitalize> <extra-non-terminal-keys>";
-    if ac_params.len() != 3 {
-        bail!("{ERR_STR}\nFound {} params instead of 3", ac_params.len());
-    }
-    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
-    Ok(s.a.sref(Action::Custom(
-        s.a.sref(
-            s.a.sref_slice(CustomAction::CapsWord(CapsWordCfg {
-                keys_to_capitalize: s.a.sref_vec(
-                    parse_key_list(&ac_params[1], s, "keys-to-capitalize")?
-                        .into_iter()
-                        .map(KeyCode::from)
-                        .collect(),
-                ),
-                keys_nonterminal: s.a.sref_vec(
-                    parse_key_list(&ac_params[2], s, "extra-non-terminal-keys")?
-                        .into_iter()
-                        .map(KeyCode::from)
-                        .collect(),
-                ),
-                timeout,
-            })),
-        ),
-    )))
-}
-
-fn parse_macro_record_stop_truncate(
-    ac_params: &[SExpr],
-    s: &ParsedState,
-) -> Result<&'static KanataAction> {
-    const ERR_STR: &str =
-        "dynamic-macro-record-stop-truncate expects 1 param: <num-keys-to-truncate>";
-    if ac_params.len() != 1 {
-        bail!("{ERR_STR}\nFound {} params instead of 1", ac_params.len());
-    }
-    let num_to_truncate = parse_u16(&ac_params[0], s, "num-keys-to-truncate")?;
-    Ok(s.a.sref(Action::Custom(s.a.sref(
-        s.a.sref_slice(CustomAction::DynamicMacroRecordStop(num_to_truncate)),
-    ))))
-}
-
-/// Creates a `KeyOutputs` from `layers::LAYERS`.
-fn create_key_outputs(layers: &KanataLayers, overrides: &Overrides) -> KeyOutputs {
-    let mut outs = KeyOutputs::new();
-    for layer in layers.iter() {
-        let mut layer_outputs = HashMap::default();
-        for (i, action) in layer[0].iter().enumerate() {
-            let osc_slot = match i.try_into() {
-                Ok(i) => i,
-                Err(_) => continue,
-            };
-            add_key_output_from_action_to_key_pos(osc_slot, action, &mut layer_outputs, overrides);
-        }
-        outs.push(layer_outputs);
-    }
-    for layer_outs in outs.iter_mut() {
-        for keys_out in layer_outs.values_mut() {
-            keys_out.shrink_to_fit();
-        }
-        layer_outs.shrink_to_fit();
-    }
-    outs.shrink_to_fit();
-    outs
-}
-
-fn add_key_output_from_action_to_key_pos(
-    osc_slot: OsCode,
-    action: &KanataAction,
-    outputs: &mut HashMap<OsCode, Vec<OsCode>>,
-    overrides: &Overrides,
-) {
-    match action {
-        Action::KeyCode(kc) => {
-            add_kc_output(osc_slot, kc.into(), outputs, overrides);
-        }
-        Action::HoldTap(HoldTapAction {
-            tap,
-            hold,
-            timeout_action,
-            ..
-        }) => {
-            add_key_output_from_action_to_key_pos(osc_slot, tap, outputs, overrides);
-            add_key_output_from_action_to_key_pos(osc_slot, hold, outputs, overrides);
-            add_key_output_from_action_to_key_pos(osc_slot, timeout_action, outputs, overrides);
-        }
-        Action::OneShot(OneShot { action: ac, .. }) => {
-            add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
-        }
-        Action::MultipleKeyCodes(kcs) => {
-            for kc in kcs.iter() {
-                add_kc_output(osc_slot, kc.into(), outputs, overrides);
-            }
-        }
-        Action::MultipleActions(actions) => {
-            for ac in actions.iter() {
-                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
-            }
-        }
-        Action::TapDance(TapDance { actions, .. }) => {
-            for ac in actions.iter() {
-                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
-            }
-        }
-        Action::Fork(ForkConfig { left, right, .. }) => {
-            add_key_output_from_action_to_key_pos(osc_slot, left, outputs, overrides);
-            add_key_output_from_action_to_key_pos(osc_slot, right, outputs, overrides);
-        }
-        Action::Chords(ChordsGroup { chords, .. }) => {
-            for (_, ac) in chords.iter() {
-                add_key_output_from_action_to_key_pos(osc_slot, ac, outputs, overrides);
-            }
-        }
-        Action::NoOp
-        | Action::Trans
-        | Action::Repeat
-        | Action::Layer(_)
-        | Action::DefaultLayer(_)
-        | Action::Sequence { .. }
-        | Action::RepeatableSequence { .. }
-        | Action::CancelSequences
-        | Action::ReleaseState(_)
-        | Action::Custom(_) => {}
-    };
-}
-
-fn add_kc_output(
-    osc_slot: OsCode,
-    osc: OsCode,
-    outs: &mut HashMap<OsCode, Vec<OsCode>>,
-    overrides: &Overrides,
-) {
-    let outputs = match outs.entry(osc_slot) {
-        Entry::Occupied(o) => o.into_mut(),
-        Entry::Vacant(v) => v.insert(vec![]),
-    };
-    if !outputs.contains(&osc) {
-        outputs.push(osc);
-    }
-    for ov_osc in overrides
-        .output_non_mods_for_input_non_mod(osc)
-        .iter()
-        .copied()
-    {
-        if !outputs.contains(&ov_osc) {
-            outputs.push(ov_osc);
+        if found_none {
+            break;
         }
     }
+    Ok((key_stack, rem))
 }
 
-/// Create a layout from `layers::LAYERS`.
-fn create_layout(layers: Box<KanataLayers>, a: Arc<Allocations>) -> KanataLayout {
-    KanataLayout::new(Layout::new(a.bref(layers)), a)
+/// Parses an expression, expected to be a list and
+/// the first item in that list is expected to be an atom.
+/// Returns the first atom and the remaining parameters
+/// if parsing succeeds, otherwise returns None.
+pub(crate) fn parse_list_with_first_atom<'a>(
+    expr: &'a SExpr,
+    s: &'a ParserState,
+) -> Option<(&'a str, &'a [SExpr])> {
+    expr.list(s.vars()).and_then(|list| {
+        list.first()
+            .and_then(|first| first.atom(s.vars()).map(|a| (a, &list[1..])))
+    })
 }
diff --git a/parser/src/cfg/mouse.rs b/parser/src/cfg/mouse.rs
new file mode 100644
index 000000000..1d8305094
--- /dev/null
+++ b/parser/src/cfg/mouse.rs
@@ -0,0 +1,146 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+
+pub(crate) fn parse_distance(expr: &SExpr, s: &ParserState, label: &str) -> Result<u16> {
+    expr.atom(s.vars())
+        .map(str::parse::<u16>)
+        .and_then(|d| d.ok())
+        .ok_or_else(|| anyhow_expr!(expr, "{label} must be 1-30000"))
+}
+
+pub(crate) fn parse_mwheel(
+    ac_params: &[SExpr],
+    direction: MWheelDirection,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "mwheel expects 2 parameters: <interval (ms)> <distance>";
+    if ac_params.len() != 2 {
+        bail!("{ERR_MSG}, found {}", ac_params.len());
+    }
+    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
+    let distance = parse_distance(&ac_params[1], s, "distance")?;
+    custom(
+        CustomAction::MWheel {
+            direction,
+            interval,
+            distance,
+            inertial_scroll_params: None,
+        },
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_mwheel_accel(
+    ac_params: &[SExpr],
+    direction: MWheelDirection,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "mwheel-accel expects 4 float32 parameters:\n\
+                           - initial velocity\n- maximum velocity\n\
+                           - acceleration multiplier\n- deceleration multiplier";
+    if ac_params.len() != 4 {
+        bail!("{ERR_MSG}, found {}", ac_params.len());
+    }
+    let initial_velocity = parse_f32(&ac_params[0], s, "initial velocity", 1.0, 12000.0)?;
+    let maximum_velocity = parse_f32(&ac_params[1], s, "maximum velocity", 1.0, 12000.0)?;
+    let acceleration_multiplier =
+        parse_f32(&ac_params[2], s, "acceleration multiplier", 1.0, 1000.0)?;
+    let deceleration_multiplier =
+        parse_f32(&ac_params[3], s, "deceleration multiplier", 0.0, 0.99)?;
+    custom(
+        CustomAction::MWheel {
+            direction,
+            interval: 16,
+            distance: 1,
+            inertial_scroll_params: Some(s.a.sref(MWheelInertial {
+                initial_velocity,
+                maximum_velocity,
+                acceleration_multiplier,
+                deceleration_multiplier,
+            })),
+        },
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_move_mouse(
+    ac_params: &[SExpr],
+    direction: MoveDirection,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "movemouse expects 2 parameters: <interval (ms)> <distance (px)>";
+    if ac_params.len() != 2 {
+        bail!("{ERR_MSG}, found {}", ac_params.len());
+    }
+    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
+    let distance = parse_distance(&ac_params[1], s, "distance")?;
+    custom(
+        CustomAction::MoveMouse {
+            direction,
+            interval,
+            distance,
+        },
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_move_mouse_accel(
+    ac_params: &[SExpr],
+    direction: MoveDirection,
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    if ac_params.len() != 4 {
+        bail!(
+            "movemouse-accel expects four parameters, found {}\n<interval (ms)> <acceleration time (ms)> <min_distance> <max_distance>",
+            ac_params.len()
+        );
+    }
+    let interval = parse_non_zero_u16(&ac_params[0], s, "interval")?;
+    let accel_time = parse_non_zero_u16(&ac_params[1], s, "acceleration time")?;
+    let min_distance = parse_distance(&ac_params[2], s, "min distance")?;
+    let max_distance = parse_distance(&ac_params[3], s, "max distance")?;
+    if min_distance > max_distance {
+        bail!("min distance should be less than max distance")
+    }
+    custom(
+        CustomAction::MoveMouseAccel {
+            direction,
+            interval,
+            accel_time,
+            min_distance,
+            max_distance,
+        },
+        &s.a,
+    )
+}
+
+pub(crate) fn parse_move_mouse_speed(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    if ac_params.len() != 1 {
+        bail!(
+            "movemouse-speed expects one parameter, found {}\n<speed scaling % (1-65535)>",
+            ac_params.len()
+        );
+    }
+    let speed = parse_non_zero_u16(&ac_params[0], s, "speed scaling %")?;
+    custom(CustomAction::MoveMouseSpeed { speed }, &s.a)
+}
+
+pub(crate) fn parse_set_mouse(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    if ac_params.len() != 2 {
+        bail!(
+            "movemouse-accel expects two parameters, found {}: <x> <y>",
+            ac_params.len()
+        );
+    }
+    let x = parse_u16(&ac_params[0], s, "x")?;
+    let y = parse_u16(&ac_params[1], s, "y")?;
+    custom(CustomAction::SetMouse { x, y }, &s.a)
+}
diff --git a/parser/src/cfg/multi.rs b/parser/src/cfg/multi.rs
new file mode 100644
index 000000000..445e4ebec
--- /dev/null
+++ b/parser/src/cfg/multi.rs
@@ -0,0 +1,67 @@
+use super::*;
+
+use crate::bail;
+
+pub(crate) fn parse_multi(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    if ac_params.is_empty() {
+        bail!("multi expects at least one item after it")
+    }
+    s.multi_action_nest_count
+        .replace(s.multi_action_nest_count.get().saturating_add(1));
+    let mut actions = Vec::new();
+    for expr in ac_params {
+        let ac = parse_action(expr, s)?;
+        match ac {
+            // Flatten multi actions
+            Action::MultipleActions(acs) => {
+                for ac in acs.iter() {
+                    actions.push(*ac);
+                }
+            }
+            _ => actions.push(*ac),
+        }
+    }
+
+    // Transform all but the last Mouse actions into MouseTap.
+    // Need to transform mouse actions to preserve old v<=1.11.0 mouse behaviour where an action like:
+    //     (multi mlft mlft)
+    // should result in an event sequence like:
+    //     click-release-click ... held until key release ... release
+    //
+    // See test `multi_mouse_button_does_multi_click_release_single_hold`.
+    for ca in actions
+        .iter_mut()
+        .rev()
+        .filter(|ac| matches!(ac, Action::Custom(CustomAction::Mouse(..))))
+        .skip(1)
+    {
+        *ca = match ca {
+            Action::Custom(CustomAction::Mouse(btn)) => {
+                Action::Custom(s.a.sref(CustomAction::MouseTap(*btn)))
+            }
+            _ => *ca,
+        };
+    }
+
+    if actions
+        .iter()
+        .filter(|ac| {
+            matches!(
+                ac,
+                Action::TapDance(TapDance {
+                    config: TapDanceConfig::Lazy,
+                    ..
+                }) | Action::HoldTap { .. }
+                    | Action::Chords { .. }
+            )
+        })
+        .count()
+        > 1
+    {
+        bail!("Cannot combine multiple tap-hold/tap-dance/chord");
+    }
+
+    s.multi_action_nest_count
+        .replace(s.multi_action_nest_count.get().saturating_sub(1));
+    Ok(s.a.sref(Action::MultipleActions(s.a.sref(s.a.sref_vec(actions)))))
+}
diff --git a/parser/src/cfg/oneshot.rs b/parser/src/cfg/oneshot.rs
new file mode 100644
index 000000000..cd3b1376c
--- /dev/null
+++ b/parser/src/cfg/oneshot.rs
@@ -0,0 +1,41 @@
+use super::*;
+
+use crate::bail;
+
+pub(crate) fn parse_one_shot(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    end_config: OneShotEndConfig,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "one-shot expects a timeout followed by a key or action";
+    if ac_params.len() != 2 {
+        bail!(ERR_MSG);
+    }
+
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    let action = parse_action(&ac_params[1], s)?;
+    if !matches!(
+        action,
+        Action::Layer(..) | Action::KeyCode(..) | Action::MultipleKeyCodes(..)
+    ) {
+        bail!("one-shot is only allowed to contain layer-while-held, a keycode, or a chord");
+    }
+
+    Ok(s.a.sref(Action::OneShot(s.a.sref(OneShot {
+        timeout,
+        action,
+        end_config,
+    }))))
+}
+
+pub(crate) fn parse_one_shot_pause_processing(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "one-shot-pause-processing expects a time";
+    if ac_params.len() != 1 {
+        bail!(ERR_MSG);
+    }
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "time (milliseconds)")?;
+    Ok(s.a.sref(Action::OneShotIgnoreEventsTicks(timeout)))
+}
diff --git a/parser/src/cfg/override.rs b/parser/src/cfg/override.rs
new file mode 100644
index 000000000..bfd64f8d8
--- /dev/null
+++ b/parser/src/cfg/override.rs
@@ -0,0 +1,136 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail_expr;
+
+pub(crate) fn parse_overrides(exprs: &[SExpr], s: &ParserState) -> Result<Overrides> {
+    const ERR_MSG: &str =
+        "defoverrides expects pairs of parameters: <input key list> <output key list>";
+    let mut subexprs = check_first_expr(exprs.iter(), "defoverrides")?;
+
+    let mut overrides = Vec::<Override>::new();
+    while let Some(in_keys_expr) = subexprs.next() {
+        let out_keys_expr = subexprs
+            .next()
+            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Missing output keys for input keys"))?;
+        let (in_keys, out_keys) = parse_override_inout_keys(in_keys_expr, out_keys_expr, s)?;
+        overrides
+            .push(Override::try_new(&in_keys, &out_keys).map_err(|e| anyhow!("{ERR_MSG}: {e}"))?);
+    }
+    log::debug!("All overrides:\n{overrides:#?}");
+    Ok(Overrides::new(&overrides))
+}
+
+pub(crate) fn parse_override_inout_keys(
+    in_keys_expr: &SExpr,
+    out_keys_expr: &SExpr,
+    s: &ParserState,
+) -> Result<(Vec<OsCode>, Vec<OsCode>)> {
+    let out_keys = out_keys_expr
+        .list(s.vars())
+        .ok_or_else(|| anyhow_expr!(out_keys_expr, "Output keys must be a list"))?;
+    let in_keys = in_keys_expr
+        .list(s.vars())
+        .ok_or_else(|| anyhow_expr!(in_keys_expr, "Input keys must be a list"))?;
+    let in_keys = in_keys
+        .iter()
+        .try_fold(vec![], |mut keys, key_expr| -> Result<Vec<OsCode>> {
+            let key = key_expr
+                .atom(s.vars())
+                .and_then(str_to_oscode)
+                .ok_or_else(|| {
+                    anyhow_expr!(key_expr, "Unknown input key name, must use known keys")
+                })?;
+            keys.push(key);
+            Ok(keys)
+        })?;
+    let out_keys =
+        out_keys
+            .iter()
+            .try_fold(vec![], |mut keys, key_expr| -> Result<Vec<OsCode>> {
+                let key = key_expr
+                    .atom(s.vars())
+                    .and_then(str_to_oscode)
+                    .ok_or_else(|| {
+                        anyhow_expr!(key_expr, "Unknown output key name, must use known keys")
+                    })?;
+                keys.push(key);
+                Ok(keys)
+            })?;
+    Ok((in_keys, out_keys))
+}
+
+pub(crate) fn parse_overridesv2(exprs: &[SExpr], s: &ParserState) -> Result<Overrides> {
+    const ERR_MSG: &str = "defoverridesv2 expects 4-tuples of parameters: <input key list> <output key list> <without mods> <excluded layers>";
+    let mut subexprs = check_first_expr(exprs.iter(), "defoverridesv2")?;
+
+    let mut overrides = Vec::<Override>::new();
+    while let Some(in_keys_expr) = subexprs.next() {
+        let out_keys_expr = subexprs
+            .next()
+            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Missing output keys for input keys"))?;
+        let (in_keys, out_keys) = parse_override_inout_keys(in_keys_expr, out_keys_expr, s)?;
+
+        let without_mods_expr = subexprs
+            .next()
+            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Missing without mods list"))?;
+        let without_mods = without_mods_expr.list(s.vars()).ok_or_else(|| {
+            anyhow_expr!(
+                without_mods_expr,
+                "Without mods configuration must be a list"
+            )
+        })?;
+
+        let excluded_layers_expr = subexprs
+            .next()
+            .ok_or_else(|| anyhow_expr!(in_keys_expr, "Missing excluded layers"))?;
+        let excluded_layers = excluded_layers_expr
+            .list(s.vars())
+            .ok_or_else(|| anyhow_expr!(excluded_layers_expr, "Excluded layers must be a list"))?;
+
+        let without_mods =
+            without_mods
+                .iter()
+                .try_fold(vec![], |mut keys, key_expr| -> Result<Vec<OsCode>> {
+                    let key = key_expr
+                        .atom(s.vars())
+                        .and_then(str_to_oscode)
+                        .ok_or_else(|| {
+                            anyhow_expr!(key_expr, "Unknown key name, must use known keys")
+                        })
+                        .and_then(|osc| match osc.is_modifier() {
+                            true => Ok(osc),
+                            false => bail_expr!(
+                                key_expr,
+                                "Keys in without mods must be modifiers, e.g. lctl, ralt"
+                            ),
+                        })?;
+                    keys.push(key);
+                    Ok(keys)
+                })?;
+
+        let excluded_layers = excluded_layers.iter().try_fold(
+            vec![],
+            |mut layers, layer_expr| -> Result<Vec<u16>> {
+                let layer = layer_expr
+                    .atom(s.vars())
+                    .and_then(|l| s.layer_idxs.get(l))
+                    .ok_or_else(|| anyhow_expr!(layer_expr, "Unknown layer name"))?;
+                layers.push(*layer as u16);
+                Ok(layers)
+            },
+        )?;
+
+        overrides.push(
+            Override::try_new_v2(
+                &in_keys,
+                &out_keys,
+                without_mods.into(),
+                excluded_layers.into(),
+            )
+            .map_err(|e| anyhow!("{ERR_MSG}: {e}"))?,
+        );
+    }
+    log::debug!("All overrides:\n{overrides:#?}");
+    Ok(Overrides::new(&overrides))
+}
diff --git a/parser/src/cfg/permutations.rs b/parser/src/cfg/permutations.rs
new file mode 100644
index 000000000..990bf2269
--- /dev/null
+++ b/parser/src/cfg/permutations.rs
@@ -0,0 +1,50 @@
+//! Implements Heap's algorithm.
+
+/*
+From Wikipedia:
+
+procedure generate(k: integer, A : array of any):
+    if k = 1 then
+        output(A)
+    else
+        // Generate permutations with k-th unaltered
+        // Initially k = length(A)
+        generate(k - 1, A)
+
+        // Generate permutations for k-th swapped with each k-1 initial
+        for i := 0; i < k-1; i += 1 do
+            // Swap choice dependent on parity of k (even or odd)
+            if k is even then
+                swap(A[i], A[k-1]) // zero-indexed, the k-th is at k-1
+            else
+                swap(A[0], A[k-1])
+            end if
+            generate(k - 1, A)
+        end for
+    end if
+*/
+
+/// Heap's algorithm
+pub fn gen_permutations<T: Clone + Default>(a: &[T]) -> Vec<Vec<T>> {
+    let mut a2 = vec![Default::default(); a.len()];
+    a2.clone_from_slice(a);
+    let mut outs = vec![];
+    heaps_alg(a.len(), &mut a2, &mut outs);
+    outs
+}
+
+fn heaps_alg<T: Clone>(k: usize, a: &mut [T], outs: &mut Vec<Vec<T>>) {
+    if k == 1 {
+        outs.push(a.to_vec());
+    } else {
+        heaps_alg(k - 1, a, outs);
+        for i in 0..k - 1 {
+            if k.is_multiple_of(2) {
+                a.swap(i, k - 1);
+            } else {
+                a.swap(0, k - 1);
+            }
+            heaps_alg(k - 1, a, outs);
+        }
+    }
+}
diff --git a/parser/src/cfg/platform.rs b/parser/src/cfg/platform.rs
new file mode 100644
index 000000000..6e8ea3979
--- /dev/null
+++ b/parser/src/cfg/platform.rs
@@ -0,0 +1,182 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail_expr;
+use crate::bail_span;
+use crate::err_expr;
+
+pub(crate) fn filter_platform_specific_cfg(
+    top_levels: Vec<TopLevel>,
+    deflocalkeys_variant_to_apply: &str,
+    _lsp_hints: &mut lsp_hints::LspHints,
+) -> Result<Vec<TopLevel>> {
+    let valid_platform_names = DEFLOCALKEYS_VARIANTS
+        .iter()
+        .map(|dfl| dfl.trim_start_matches("deflocalkeys-"))
+        .collect::<Vec<_>>();
+    let current_platform = deflocalkeys_variant_to_apply.trim_start_matches("deflocalkeys-");
+    top_levels
+        .into_iter()
+        .try_fold(vec![], |mut tles, tle| -> Result<Vec<TopLevel>> {
+            if !matches!(tle.t.first().and_then(|m| m.atom(None)), Some("platform")) {
+                tles.push(tle);
+                return Ok(tles);
+            }
+
+            if tle.t.len() != 3 {
+                bail_span!(
+                    &tle,
+                    "platform requires exactly two parameters:\n\
+                      applicable-platforms, configuration-item"
+                );
+            }
+
+            let configuration = tle.t[2]
+                .span_list(None)
+                .ok_or_else(|| anyhow_expr!(&tle.t[2], "configuration-item must be a list"))?;
+
+            let applicable_platforms = tle.t[1]
+                .list(None)
+                .ok_or_else(|| anyhow_expr!(&tle.t[1], "applicable-platforms must be a list"))
+                .and_then(|pf_list| {
+                    pf_list.iter().try_fold(vec![], |mut pfs, pf_expr| {
+                        let good_pf = pf_expr
+                            .atom(None)
+                            .ok_or_else(|| anyhow_expr!(pf_expr, "platform must be a string"))
+                            .and_then(|pf| {
+                                if valid_platform_names.contains(&pf) {
+                                    Ok(pf)
+                                } else {
+                                    err_expr!(
+                                        pf_expr,
+                                        "Unknown platform. Valid platforms:\n{}",
+                                        valid_platform_names.join(" ")
+                                    )
+                                }
+                            })?;
+                        pfs.push(good_pf);
+                        Ok(pfs)
+                    })
+                })?;
+
+            if applicable_platforms.contains(&current_platform) {
+                tles.push(configuration.clone());
+            } else {
+                #[cfg(feature = "lsp")]
+                _lsp_hints.inactive_code.push(lsp_hints::InactiveCode {
+                    span: tle.span.clone(),
+                    reason: format!(
+                        "Current platform \"{current_platform}\" doesn't match any of: {}",
+                        applicable_platforms.join(" ")
+                    ),
+                })
+            }
+
+            Ok(tles)
+        })
+}
+
+pub(crate) fn filter_env_specific_cfg(
+    top_levels: Vec<TopLevel>,
+    env: &EnvVars,
+    _lsp_hints: &mut lsp_hints::LspHints,
+) -> Result<Vec<TopLevel>> {
+    top_levels
+        .into_iter()
+        .try_fold(vec![], |mut tles, tle| -> Result<Vec<TopLevel>> {
+            if !matches!(
+                tle.t.first().and_then(|m| m.atom(None)),
+                Some("environment")
+            ) {
+                tles.push(tle);
+                return Ok(tles);
+            }
+            let env = match env.as_ref() {
+                Ok(v) => v,
+                Err(e) => Err(anyhow!("{e}"))?,
+            };
+            if tle.t.len() != 3 {
+                bail_span!(
+                    &tle,
+                    "environment requires exactly two parameters:\n\
+                     varname-varvalue, configuration-item"
+                );
+            }
+
+            let configuration = tle.t[2]
+                .span_list(None)
+                .ok_or_else(|| anyhow_expr!(&tle.t[2], "configuration-item must be a list"))?;
+
+            let (env_var_name, env_var_val) = tle.t[1]
+                .list(None)
+                .ok_or_else(|| anyhow_expr!(&tle.t[1], "varname-varvalue must be a list"))
+                .and_then(|varnameval| {
+                    if varnameval.len() != 2 {
+                        bail_expr!(
+                            &tle.t[1],
+                            "varname-varvalue must be a list of two elements:\n\
+                                               varname, varvalue"
+                        );
+                    }
+                    Ok((
+                        varnameval[0].atom(None).ok_or_else(|| {
+                            anyhow_expr!(&varnameval[0], "varname must be a string")
+                        })?,
+                        varnameval[1].atom(None).ok_or_else(|| {
+                            anyhow_expr!(&varnameval[1], "varvalue must be a string")
+                        })?,
+                    ))
+                })?;
+            let env_var_val = env_var_val.trim_atom_quotes();
+            match (
+                env.iter().find_map(|(name, val)| {
+                    if name == env_var_name {
+                        Some(val)
+                    } else {
+                        None
+                    }
+                }),
+                env_var_val.is_empty(),
+            ) {
+                (None, false) => {
+                    #[cfg(feature = "lsp")]
+                    _lsp_hints.inactive_code.push(lsp_hints::InactiveCode {
+                        span: tle.span.clone(),
+                        reason: format!(
+                            "Active if env var {env_var_name} is {env_var_val}. It is unset."
+                        ),
+                    });
+                }
+                (None, true) => {
+                    tles.push(configuration.clone());
+                }
+                (Some(val), true) if val.is_empty() => {
+                    tles.push(configuration.clone());
+                }
+                (Some(_val), true) => {
+                    #[cfg(feature = "lsp")]
+                    _lsp_hints.inactive_code.push(lsp_hints::InactiveCode {
+                        span: tle.span.clone(),
+                        reason: format!(
+                            "Active if {env_var_name} is empty or unset. It has value {_val}"
+                        ),
+                    });
+                }
+                (Some(val), false) => {
+                    if val == env_var_val {
+                        tles.push(configuration.clone());
+                    } else {
+                        #[cfg(feature = "lsp")]
+                        _lsp_hints.inactive_code.push(lsp_hints::InactiveCode {
+                            span: tle.span.clone(),
+                            reason: format!(
+                                "Active if {env_var_name} is {env_var_val}. It has value {val}"
+                            ),
+                        })
+                    }
+                }
+            }
+
+            Ok(tles)
+        })
+}
diff --git a/parser/src/cfg/push_msg.rs b/parser/src/cfg/push_msg.rs
new file mode 100644
index 000000000..00136d383
--- /dev/null
+++ b/parser/src/cfg/push_msg.rs
@@ -0,0 +1,38 @@
+use super::*;
+
+use crate::bail;
+
+pub(crate) fn parse_push_message(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    if ac_params.is_empty() {
+        bail!(
+            "{PUSH_MESSAGE} expects at least one item, an item can be a list or an atom, found 0, none"
+        );
+    }
+    let message = to_simple_expr(ac_params, s);
+    custom(CustomAction::PushMessage(s.a.sref_vec(message)), &s.a)
+}
+
+pub(crate) fn to_simple_expr(params: &[SExpr], s: &ParserState) -> Vec<SimpleSExpr> {
+    let mut result: Vec<SimpleSExpr> = Vec::new();
+    for param in params {
+        if let Some(a) = param.atom(s.vars()) {
+            result.push(SimpleSExpr::Atom(a.trim_atom_quotes().to_owned()));
+        } else {
+            // unwrap: this must be a list, since it's not an atom.
+            let sexps = param.list(s.vars()).unwrap();
+            let value = to_simple_expr(sexps, s);
+            let list = SimpleSExpr::List(value);
+            result.push(list);
+        }
+    }
+    result
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum SimpleSExpr {
+    Atom(String),
+    List(Vec<SimpleSExpr>),
+}
diff --git a/parser/src/cfg/releases.rs b/parser/src/cfg/releases.rs
new file mode 100644
index 000000000..d85e72a91
--- /dev/null
+++ b/parser/src/cfg/releases.rs
@@ -0,0 +1,33 @@
+use super::*;
+
+use crate::bail;
+use crate::err_expr;
+
+pub(crate) fn parse_release_key(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "release-key expects exactly one keycode (e.g. lalt)";
+    if ac_params.len() != 1 {
+        bail!("{ERR_MSG}: found {} items", ac_params.len());
+    }
+    let ac = parse_action(&ac_params[0], s)?;
+    match ac {
+        Action::KeyCode(kc) => {
+            Ok(s.a.sref(Action::ReleaseState(ReleasableState::KeyCode(*kc))))
+        }
+        _ => err_expr!(&ac_params[0], "{}", ERR_MSG),
+    }
+}
+
+pub(crate) fn parse_release_layer(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    Ok(s.a
+        .sref(Action::ReleaseState(ReleasableState::Layer(layer_idx(
+            ac_params,
+            &s.layer_idxs,
+            s,
+        )?))))
+}
diff --git a/parser/src/cfg/sequence.rs b/parser/src/cfg/sequence.rs
new file mode 100644
index 000000000..0283e20b3
--- /dev/null
+++ b/parser/src/cfg/sequence.rs
@@ -0,0 +1,252 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+const SEQ_ERR: &str = "defseq expects pairs of parameters: <virtual_key_name> <key_list>";
+
+pub(crate) fn parse_sequence_start(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str =
+        "sequence expects one or two params: <timeout-override> <?input-mode-override>";
+    if !matches!(ac_params.len(), 1 | 2) {
+        bail!("{ERR_MSG}\nfound {} items", ac_params.len());
+    }
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout-override")?;
+    let input_mode = if ac_params.len() > 1 {
+        if let Some(Ok(input_mode)) = ac_params[1]
+            .atom(s.vars())
+            .map(SequenceInputMode::try_from_str)
+        {
+            input_mode
+        } else {
+            bail_expr!(&ac_params[1], "{ERR_MSG}\n{}", SequenceInputMode::err_msg());
+        }
+    } else {
+        s.default_sequence_input_mode
+    };
+    custom(CustomAction::SequenceLeader(timeout, input_mode), &s.a)
+}
+
+pub(crate) fn parse_sequence_noerase(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "sequence-noerase expects one: <noerase-count>";
+    if ac_params.len() != 1 {
+        bail!("{ERR_MSG}\nfound {} items", ac_params.len());
+    }
+    let count = parse_non_zero_u16(&ac_params[0], s, "noerase-count")?;
+    custom(CustomAction::SequenceNoerase(count), &s.a)
+}
+
+pub(crate) fn parse_sequences(exprs: &[&Vec<SExpr>], s: &ParserState) -> Result<KeySeqsToFKeys> {
+    let mut sequences = Trie::new();
+    for expr in exprs {
+        let mut subexprs = check_first_expr(expr.iter(), "defseq")?.peekable();
+
+        while let Some(vkey_expr) = subexprs.next() {
+            let vkey = vkey_expr.atom(s.vars()).ok_or_else(|| {
+                anyhow_expr!(vkey_expr, "{SEQ_ERR}\nvirtual_key_name must not be a list")
+            })?;
+            #[cfg(feature = "lsp")]
+            s.lsp_hints
+                .borrow_mut()
+                .reference_locations
+                .virtual_key
+                .push(vkey, vkey_expr.span());
+            if !s.virtual_keys.contains_key(vkey) {
+                bail_expr!(
+                    vkey_expr,
+                    "{SEQ_ERR}\nThe referenced key does not exist: {vkey}"
+                );
+            }
+            let key_seq_expr = subexprs
+                .next()
+                .ok_or_else(|| anyhow_expr!(vkey_expr, "{SEQ_ERR}\nMissing key_list for {vkey}"))?;
+            let key_seq = key_seq_expr.list(s.vars()).ok_or_else(|| {
+                anyhow_expr!(key_seq_expr, "{SEQ_ERR}\nGot a non-list for key_list")
+            })?;
+            if key_seq.is_empty() {
+                bail_expr!(key_seq_expr, "{SEQ_ERR}\nkey_list cannot be empty");
+            }
+
+            let keycode_seq = parse_sequence_keys(key_seq, s)?;
+
+            // Generate permutations of sequences for overlapping keys.
+            let mut permutations = vec![vec![]];
+            let mut vals = keycode_seq.iter().copied();
+            while let Some(val) = vals.next() {
+                if val & KEY_OVERLAP_MARKER == 0 {
+                    for p in permutations.iter_mut() {
+                        p.push(val);
+                    }
+                    continue;
+                }
+
+                if val == 0x0400 {
+                    bail_expr!(
+                        key_seq_expr,
+                        "O-(...) lists must have a minimum of 2 elements"
+                    );
+                }
+                let mut values_to_permute = vec![val];
+                for val in vals.by_ref() {
+                    if val == 0x0400 {
+                        break;
+                    }
+                    values_to_permute.push(val);
+                }
+
+                let ps = match values_to_permute.len() {
+                    0 | 1 => bail_expr!(
+                        key_seq_expr,
+                        "O-(...) lists must have a minimum of 2 elements"
+                    ),
+                    2..=6 => gen_permutations(&values_to_permute[..]),
+                    _ => bail_expr!(
+                        key_seq_expr,
+                        "O-(...) lists must have a maximum of 6 elements"
+                    ),
+                };
+
+                let mut new_permutations: Vec<Vec<u16>> = vec![];
+                for p in permutations.iter() {
+                    for p2 in ps.iter() {
+                        new_permutations.push(
+                            p.iter()
+                                .copied()
+                                .chain(p2.iter().copied().chain([KEY_OVERLAP_MARKER]))
+                                .collect(),
+                        );
+                    }
+                }
+                permutations = new_permutations;
+            }
+
+            for p in permutations.into_iter() {
+                if sequences.ancestor_exists(&p) {
+                    bail_expr!(
+                        key_seq_expr,
+                        "Sequence has a conflict: its sequence contains an earlier defined sequence"
+                    );
+                }
+                if sequences.descendant_exists(&p) {
+                    bail_expr!(
+                        key_seq_expr,
+                        "Sequence has a conflict: its sequence is contained within an earlier defined seqence"
+                    );
+                }
+                sequences.insert(
+                    p,
+                    s.virtual_keys
+                        .get(vkey)
+                        .map(|(y, _)| get_fake_key_coords(*y))
+                        .expect("vk exists, checked earlier"),
+                );
+            }
+        }
+    }
+    Ok(sequences)
+}
+
+pub(crate) fn parse_sequence_keys(exprs: &[SExpr], s: &ParserState) -> Result<Vec<u16>> {
+    use SequenceEvent::*;
+
+    // Reuse macro parsing but do some other processing since sequences don't support everything
+    // that can go in a macro, and also change error messages of course.
+    let mut exprs_remaining = exprs;
+    let mut all_keys = Vec::new();
+    while !exprs_remaining.is_empty() {
+        let (mut keys, exprs_remaining_tmp) =
+            match parse_macro_item_impl(exprs_remaining, s, MacroNumberParseMode::Action) {
+                Ok(res) => {
+                    if res.0.iter().any(|k| !matches!(k, Press(..) | Release(..))) {
+                        // Determine the bad expression depending on how many expressions were consumed
+                        // by parse_macro_item_impl.
+                        let bad_expr = if exprs_remaining.len() - res.1.len() == 1 {
+                            &exprs_remaining[0]
+                        } else {
+                            // This error message will have an imprecise span since it will take the
+                            // whole chorded list instead of the single element inside that's not a
+                            // standard key. Oh well, should still be helpful. I'm too lazy to write
+                            // the code to find the exact expr to use right now.
+                            &exprs_remaining[1]
+                        };
+                        bail_expr!(bad_expr, "{SEQ_ERR}\nFound invalid key/chord in key_list");
+                    }
+
+                    // The keys are currenty in the form of SequenceEvent::{Press, Release}. This is
+                    // not what we want.
+                    //
+                    // The trivial and incorrect way to parse this would be to just take all of the
+                    // presses. However, we need to transform chorded keys/lists like S-a or S-(a b) to
+                    // have the upper bits set, to be able to differentiate (S-a b) from (S-(a b)).
+                    //
+                    // The order of presses and releases reveals whether or not a key is chorded with
+                    // some modifier. When a chord starts, there are multiple presses in a row, whereas
+                    // non-chords will always be a press followed by a release. Likewise, a chord
+                    // ending is marked by multiple releases in a row.
+                    let mut mods_currently_held = vec![];
+                    let mut key_actions = res.0.iter().peekable();
+                    let mut seq = vec![];
+                    let mut do_release_mod = false;
+                    while let Some(action) = key_actions.next() {
+                        match action {
+                            Press(pressed) => {
+                                if matches!(key_actions.peek(), Some(Press(..))) {
+                                    // press->press: current press is mod
+                                    mods_currently_held.push(*pressed);
+                                }
+                                let mut seq_num = u16::from(OsCode::from(pressed));
+                                for modk in mods_currently_held.iter().copied() {
+                                    seq_num |= mod_mask_for_keycode(modk);
+                                }
+                                if seq_num & KEY_OVERLAP_MARKER == KEY_OVERLAP_MARKER
+                                    && seq_num & MASK_MODDED != KEY_OVERLAP_MARKER
+                                {
+                                    bail_expr!(
+                                        &exprs_remaining[0],
+                                        "O-(...) lists cannot be combined with other modifiers."
+                                    );
+                                }
+                                if *pressed != KEY_OVERLAP {
+                                    // Note: key overlap item is special and goes at the end,
+                                    // not the beginning
+                                    seq.push(seq_num);
+                                }
+                            }
+                            Release(released) => {
+                                if *released == KEY_OVERLAP {
+                                    seq.push(KEY_OVERLAP_MARKER);
+                                }
+                                if do_release_mod {
+                                    mods_currently_held.remove(
+                                        mods_currently_held
+                                            .iter()
+                                            .position(|modk| modk == released)
+                                            .expect("had to be pressed to be released"),
+                                    );
+                                }
+                                // release->release: next release is mod
+                                do_release_mod = matches!(key_actions.peek(), Some(Release(..)));
+                            }
+                            _ => unreachable!("should be filtered out"),
+                        }
+                    }
+
+                    (seq, res.1)
+                }
+                Err(mut e) => {
+                    e.msg = format!("{SEQ_ERR}\nFound invalid key/chord in key_list");
+                    return Err(e);
+                }
+            };
+        all_keys.append(&mut keys);
+        exprs_remaining = exprs_remaining_tmp;
+    }
+    Ok(all_keys)
+}
diff --git a/parser/src/cfg/sexpr.rs b/parser/src/cfg/sexpr.rs
index 0431f93d7..5dc1749eb 100644
--- a/parser/src/cfg/sexpr.rs
+++ b/parser/src/cfg/sexpr.rs
@@ -1,28 +1,58 @@
 use std::ops::Index;
 use std::rc::Rc;
 use std::str::Bytes;
-use std::{cmp, iter};
+use std::{fmt::Debug, iter};
 
-type ParseError = Spanned<String>;
 type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
 
-type ParseResult<T> = Result<T, ParseError>;
+use super::{ParseError, Result};
 
-use super::error::{span_start_len, CfgError};
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub struct Position {
+    /// The position (since the beginning of the file), in bytes.
+    pub absolute: usize,
+    /// The number of newline characters since the beginning of the file.
+    pub line: usize,
+    /// The position of beginning of line, in bytes.
+    pub line_beginning: usize,
+}
+
+impl Position {
+    pub fn new(absolute: usize, line: usize, line_beginning: usize) -> Self {
+        assert!(line <= absolute);
+        assert!(line_beginning <= absolute);
+        Self {
+            absolute,
+            line,
+            line_beginning,
+        }
+    }
+}
 
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Clone, PartialEq, Eq, Hash)]
 pub struct Span {
-    pub start: usize,
-    pub end: usize,
+    pub start: Position,
+    pub end: Position,
     pub file_name: Rc<str>,
     pub file_content: Rc<str>,
 }
 
+impl Debug for Span {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Span")
+            .field("start", &self.start)
+            .field("end", &self.end)
+            .field("file_name", &self.file_name)
+            .field("file_content [len]", &self.file_content.len())
+            .finish()
+    }
+}
+
 impl Default for Span {
     fn default() -> Self {
         Self {
-            start: 0,
-            end: 0,
+            start: Position::default(),
+            end: Position::default(),
             file_name: Rc::from(""),
             file_content: Rc::from(""),
         }
@@ -30,8 +60,9 @@ impl Default for Span {
 }
 
 impl Span {
-    fn new(start: usize, end: usize, file_name: Rc<str>, file_content: Rc<str>) -> Span {
-        assert!(start <= end);
+    pub fn new(start: Position, end: Position, file_name: Rc<str>, file_content: Rc<str>) -> Span {
+        assert!(start.absolute <= end.absolute);
+        assert!(start.line <= end.line);
         Span {
             start,
             end,
@@ -40,24 +71,35 @@ impl Span {
         }
     }
 
-    pub fn start(&self) -> usize {
-        self.start
+    pub fn cover(&self, other: &Span) -> Span {
+        assert!(self.file_name == other.file_name);
+
+        let start: Position = if self.start() <= other.start() {
+            self.start
+        } else {
+            other.start
+        };
+
+        let end: Position = if self.end() >= other.end() {
+            self.end
+        } else {
+            other.end
+        };
+
+        Span::new(
+            start,
+            end,
+            self.file_name.clone(),
+            self.file_content.clone(),
+        )
     }
 
-    pub fn end(&self) -> usize {
-        self.end
+    pub fn start(&self) -> usize {
+        self.start.absolute
     }
 
-    /// # Panics
-    ///
-    /// Panics if `other` has a different `file_name`
-    pub fn cover(self, other: Span) -> Span {
-        let start = cmp::min(self.start(), other.start());
-        let end = cmp::max(self.end(), other.end());
-        if self.file_name != other.file_name {
-            panic!("Can't create span across different files.");
-        }
-        Span::new(start, end, self.file_name, self.file_content)
+    pub fn end(&self) -> usize {
+        self.end.absolute
     }
 
     pub fn file_name(&self) -> String {
@@ -83,7 +125,7 @@ impl Index<Span> for String {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Spanned<T> {
     pub t: T,
     pub span: Span,
@@ -95,7 +137,7 @@ impl<T> Spanned<T> {
     }
 }
 
-#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Clone, PartialEq, Eq, Hash)]
 /// I know this isn't the classic definition of an S-Expression which uses cons cell and atom, but
 /// this is more convenient to work with (I find).
 pub enum SExpr {
@@ -110,7 +152,13 @@ impl SExpr {
                 let s = a.t.as_str();
                 match (s.strip_prefix('$'), vars) {
                     (Some(varname), Some(vars)) => match vars.get(varname) {
-                        Some(var) => var.atom(Some(vars)),
+                        Some(var) => {
+                            #[cfg(feature = "lsp")]
+                            super::LSP_VARIABLE_REFERENCES.with_borrow_mut(|refs| {
+                                refs.push(varname, a.span.clone());
+                            });
+                            var.atom(Some(vars))
+                        }
                         None => Some(s),
                     },
                     _ => Some(s),
@@ -125,7 +173,35 @@ impl SExpr {
             SExpr::List(l) => Some(&l.t),
             SExpr::Atom(a) => match (a.t.strip_prefix('$'), vars) {
                 (Some(varname), Some(vars)) => match vars.get(varname) {
-                    Some(var) => var.list(Some(vars)),
+                    Some(var) => {
+                        #[cfg(feature = "lsp")]
+                        super::LSP_VARIABLE_REFERENCES.with_borrow_mut(|refs| {
+                            refs.push(varname, a.span.clone());
+                        });
+                        var.list(Some(vars))
+                    }
+                    None => None,
+                },
+                _ => None,
+            },
+        }
+    }
+
+    pub fn span_list<'a>(
+        &'a self,
+        vars: Option<&'a HashMap<String, SExpr>>,
+    ) -> Option<&'a Spanned<Vec<SExpr>>> {
+        match self {
+            SExpr::List(l) => Some(l),
+            SExpr::Atom(a) => match (a.t.strip_prefix('$'), vars) {
+                (Some(varname), Some(vars)) => match vars.get(varname) {
+                    Some(var) => {
+                        #[cfg(feature = "lsp")]
+                        super::LSP_VARIABLE_REFERENCES.with_borrow_mut(|refs| {
+                            refs.push(varname, a.span.clone());
+                        });
+                        var.span_list(Some(vars))
+                    }
                     None => None,
                 },
                 _ => None,
@@ -146,53 +222,118 @@ impl std::fmt::Debug for SExpr {
         match self {
             SExpr::Atom(a) => write!(f, "{}", &a.t),
             SExpr::List(l) => {
-                write!(f, "(")?;
-                for i in 0..l.t.len() - 1 {
-                    write!(f, "{:?} ", &l.t[i])?;
-                }
-                if let Some(last) = &l.t.last() {
-                    write!(f, "{last:?}")?;
-                }
-                write!(f, ")")?;
+                let inner =
+                    l.t.iter()
+                        .map(|x| format!("{x:?}"))
+                        .collect::<Vec<_>>()
+                        .join(" ");
+                write!(f, "({inner})")?;
                 Ok(())
             }
         }
     }
 }
 
+#[derive(Clone, PartialEq, Eq, Debug)]
+/// Complementary to SExpr metadata items.
+pub enum SExprMetaData {
+    LineComment(Spanned<String>),
+    BlockComment(Spanned<String>),
+    Whitespace(Spanned<String>),
+}
+
+impl SExprMetaData {
+    pub fn span(&self) -> Span {
+        match self {
+            Self::LineComment(x) => x.span.clone(),
+            Self::BlockComment(x) => x.span.clone(),
+            Self::Whitespace(x) => x.span.clone(),
+        }
+    }
+}
+
 #[derive(Debug)]
 enum Token {
     Open,
     Close,
     StringTok,
+    BlockComment,
+    LineComment,
+    Whitespace,
 }
-pub struct Lexer<'a> {
-    s: &'a str,
+
+#[derive(Clone)]
+/// A wrapper around [`Bytes`] that keeps track of current [`Position`].
+struct PositionCountingBytesIterator<'a> {
     bytes: Bytes<'a>,
+    source_length: usize,
+    line: usize,
+    line_beginning: usize,
+}
+
+impl<'a> PositionCountingBytesIterator<'a> {
+    fn new(s: &'a str) -> Self {
+        Self {
+            bytes: s.bytes(),
+            source_length: s.len(),
+            line: 0,
+            line_beginning: 0,
+        }
+    }
+
+    fn pos(&self) -> Position {
+        let absolute = self.source_length - self.bytes.len();
+        Position::new(absolute, self.line, self.line_beginning)
+    }
+}
+
+impl Iterator for PositionCountingBytesIterator<'_> {
+    type Item = u8;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.bytes.next().inspect(|&b| {
+            if b == b'\n' {
+                self.line += 1;
+                self.line_beginning = self.source_length - self.bytes.len()
+            }
+        })
+    }
+}
+
+pub struct Lexer<'a> {
+    bytes: PositionCountingBytesIterator<'a>,
+    ignore_whitespace_and_comments: bool,
 }
 
 fn is_start(b: u8) -> bool {
     matches!(b, b'(' | b')' | b'"') || b.is_ascii_whitespace()
 }
 
-type TokenRes = Result<Token, String>;
+type TokenRes = std::result::Result<Token, String>;
 
 impl<'a> Lexer<'a> {
     #[allow(clippy::new_ret_no_self)]
     /// `file_name` is used only for indicating a file, where
     /// a fragment of `source` that caused parsing error came from.
-    fn new(source: &'a str, file_name: &'a str) -> impl Iterator<Item = Spanned<TokenRes>> + 'a {
+    fn new(
+        source: &'a str,
+        file_name: &'a str,
+        ignore_whitespace_and_comments: bool,
+    ) -> impl Iterator<Item = Spanned<TokenRes>> + 'a {
+        let _bytes = source.bytes().next();
+
         let mut lexer = Lexer {
-            s: source,
-            bytes: source.bytes(),
+            bytes: PositionCountingBytesIterator::new(source),
+            ignore_whitespace_and_comments,
         };
         let file_name: Rc<str> = Rc::from(file_name);
         let file_content: Rc<str> = Rc::from(source);
         iter::from_fn(move || {
             lexer.next_token().map(|(start, t)| {
+                let end = lexer.bytes.pos();
                 Spanned::new(
                     t,
-                    Span::new(start, lexer.pos(), file_name.clone(), file_content.clone()),
+                    Span::new(start, end, file_name.clone(), file_content.clone()),
                 )
             })
         })
@@ -209,36 +350,38 @@ impl<'a> Lexer<'a> {
         }
     }
 
-    /// Looks for "|#", consuming bytes until found. If not found, returns Some(Err(...));
-    /// otherwise returns None.
-    fn read_until_multiline_comment_end(&mut self) -> Option<TokenRes> {
-        let mut found_comment_end = false;
+    /// Looks for "#, consuming bytes until found. If not found, returns Err(...);
+    fn read_until_multiline_string_end(&mut self) -> TokenRes {
         for b2 in self.bytes.clone().skip(1) {
             // Iterating over a clone of this iterator that's 1 item ahead - this is guaranteed to
             // be Some.
             let b1 = self.bytes.next().expect("iter lag");
-            if b1 == b'|' && b2 == b'#' {
-                found_comment_end = true;
-                break;
+            if b1 == b'"' && b2 == b'#' {
+                self.bytes.next();
+                return Ok(Token::StringTok);
             }
         }
-        if !found_comment_end {
-            return Some(Err(
-                "Unterminated multiline comment. Add |# after the end of your comment.".to_string(),
-            ));
-        }
-        self.bytes.next();
-        None
+        Err("Unterminated multiline string. Add \"# after the end of your string.".to_string())
     }
 
-    fn pos(&self) -> usize {
-        self.s.len() - self.bytes.len()
+    /// Looks for "|#", consuming bytes until found. If not found, returns Err(...);
+    fn read_until_multiline_comment_end(&mut self) -> TokenRes {
+        for b2 in self.bytes.clone().skip(1) {
+            // Iterating over a clone of this iterator that's 1 item ahead - this is guaranteed to
+            // be Some.
+            let b1 = self.bytes.next().expect("iter lag");
+            if b1 == b'|' && b2 == b'#' {
+                self.bytes.next();
+                return Ok(Token::BlockComment);
+            }
+        }
+        Err("Unterminated multiline comment. Add |# after the end of your comment.".to_string())
     }
 
-    fn next_token(&mut self) -> Option<(usize, TokenRes)> {
+    fn next_token(&mut self) -> Option<(Position, TokenRes)> {
         use Token::*;
         loop {
-            let start = self.pos();
+            let start = self.bytes.pos();
             break match self.bytes.next() {
                 Some(b) => Some((
                     start,
@@ -256,25 +399,50 @@ impl<'a> Lexer<'a> {
                             Some(b';') => {
                                 self.next_while(|b| b != b'\n');
                                 // possibly consume the newline (or EOF handled in next iteration)
-                                let _ = self.bytes.next();
-                                continue;
+                                self.bytes.next();
+                                if self.ignore_whitespace_and_comments {
+                                    continue;
+                                }
+                                Token::LineComment
                             }
                             _ => self.next_string(),
                         },
+                        b'r' => {
+                            match (self.bytes.clone().next(), self.bytes.clone().nth(1)) {
+                                (Some(b'#'), Some(b'"')) => {
+                                    // consume the # and "
+                                    self.bytes.next();
+                                    self.bytes.next();
+                                    let tok: Token = match self.read_until_multiline_string_end() {
+                                        Ok(t) => t,
+                                        e @ Err(_) => return Some((start, e)),
+                                    };
+                                    tok
+                                }
+                                _ => self.next_string(),
+                            }
+                        }
                         b'#' => match self.bytes.clone().next() {
                             Some(b'|') => {
                                 // consume the '|'
                                 self.bytes.next();
-                                if let Some(e) = self.read_until_multiline_comment_end() {
-                                    return Some((start, e));
+                                let tok: Token = match self.read_until_multiline_comment_end() {
+                                    Ok(t) => t,
+                                    e @ Err(_) => return Some((start, e)),
+                                };
+                                if self.ignore_whitespace_and_comments {
+                                    continue;
                                 }
-                                continue;
+                                tok
                             }
                             _ => self.next_string(),
                         },
                         b if b.is_ascii_whitespace() => {
-                            self.next_while(|b| b.is_ascii_whitespace());
-                            continue;
+                            let tok = self.next_whitespace();
+                            if self.ignore_whitespace_and_comments {
+                                continue;
+                            }
+                            tok
                         }
                         _ => self.next_string(),
                     }),
@@ -289,30 +457,64 @@ impl<'a> Lexer<'a> {
         self.next_while(|b| !is_start(b));
         Token::StringTok
     }
+
+    fn next_whitespace(&mut self) -> Token {
+        self.next_while(|b| b.is_ascii_whitespace());
+        Token::Whitespace
+    }
 }
 
 pub type TopLevel = Spanned<Vec<SExpr>>;
 
-pub fn parse(cfg: &str, file_name: &str) -> Result<Vec<TopLevel>, CfgError> {
-    parse_(cfg, file_name).map_err(transform_error)
+pub fn parse(cfg: &str, file_name: &str) -> std::result::Result<Vec<TopLevel>, ParseError> {
+    let ignore_whitespace_and_comments = true;
+    parse_(cfg, file_name, ignore_whitespace_and_comments).map(|(x, _)| x)
+}
+
+pub fn parse_(
+    cfg: &str,
+    file_name: &str,
+    ignore_whitespace_and_comments: bool,
+) -> Result<(Vec<TopLevel>, Vec<SExprMetaData>)> {
+    let cfg = strip_utf8_bom(cfg);
+    parse_with(
+        cfg,
+        Lexer::new(cfg, file_name, ignore_whitespace_and_comments),
+    )
+    .map_err(|e| {
+        if e.msg.contains("Unterminated multiline comment") {
+            if let Some(mut span) = e.span {
+                span.end = span.start;
+                span.end.absolute += 2;
+                ParseError::new(span, e.msg)
+            } else {
+                e
+            }
+        } else {
+            e
+        }
+    })
 }
 
-pub fn parse_(cfg: &str, file_name: &str) -> ParseResult<Vec<TopLevel>> {
-    parse_with(cfg, Lexer::new(cfg, file_name))
+fn strip_utf8_bom(s: &str) -> &str {
+    match s.as_bytes().strip_prefix(&[0xef, 0xbb, 0xbf]) {
+        Some(stripped) => std::str::from_utf8(stripped).expect("valid input"),
+        None => s,
+    }
 }
 
 fn parse_with(
     s: &str,
     mut tokens: impl Iterator<Item = Spanned<TokenRes>>,
-) -> ParseResult<Vec<TopLevel>> {
-    use SExpr::*;
+) -> Result<(Vec<TopLevel>, Vec<SExprMetaData>)> {
     use Token::*;
     let mut stack = vec![Spanned::new(vec![], Span::default())];
+    let mut metadata: Vec<SExprMetaData> = vec![];
     loop {
         match tokens.next() {
             None => break,
-            Some(Spanned { t, span }) => match t.map_err(|s| Spanned::new(s, span.clone()))? {
-                Open => stack.push(Spanned::new(vec![], span.clone())),
+            Some(Spanned { t, span }) => match t.map_err(|s| ParseError::new(span.clone(), s))? {
+                Open => stack.push(Spanned::new(vec![], span)),
                 Close => {
                     let Spanned {
                         t: exprs,
@@ -321,22 +523,28 @@ fn parse_with(
                         // if the stack is ever empty, return an error.
                     } = stack.pop().expect("placeholder unpopped");
                     if stack.is_empty() {
-                        return Err(Spanned::new(
-                            "Unexpected closing parenthesis".to_string(),
-                            span,
-                        ));
+                        return Err(ParseError::new(span, "Unexpected closing parenthesis"));
                     }
-                    let expr = List(Spanned::new(exprs, stack_span.cover(span.clone())));
+                    let expr = SExpr::List(Spanned::new(exprs, stack_span.cover(&span)));
                     stack.last_mut().expect("not empty").t.push(expr);
                 }
                 StringTok => stack
                     .last_mut()
                     .expect("not empty")
                     .t
-                    .push(Atom(Spanned::new(
-                        s[span.clone()].to_string(),
-                        span.clone(),
-                    ))),
+                    .push(SExpr::Atom(Spanned::new(s[span.clone()].to_string(), span))),
+                BlockComment => metadata.push(SExprMetaData::BlockComment(Spanned::new(
+                    s[span.clone()].to_string(),
+                    span,
+                ))),
+                LineComment => metadata.push(SExprMetaData::LineComment(Spanned::new(
+                    s[span.clone()].to_string(),
+                    span,
+                ))),
+                Whitespace => metadata.push(SExprMetaData::Whitespace(Spanned::new(
+                    s[span.clone()].to_string(),
+                    span,
+                ))),
             },
         }
     }
@@ -344,47 +552,14 @@ fn parse_with(
     // empty, return an error.
     let Spanned { t: exprs, span: sp } = stack.pop().expect("placeholder unpopped");
     if !stack.is_empty() {
-        return Err(Spanned::new("Unclosed opening parenthesis".to_string(), sp));
+        return Err(ParseError::new(sp, "Unclosed opening parenthesis"));
     }
     let exprs = exprs
         .into_iter()
         .map(|expr| match expr {
             SExpr::List(es) => Ok(es),
-            SExpr::Atom(s) => Err(Spanned::new(
-                "Everything must be in a list".to_string(),
-                s.span,
-            )),
+            SExpr::Atom(s) => Err(ParseError::new(s.span, "Everything must be in a list")),
         })
-        .collect::<ParseResult<_>>()?;
-    Ok(exprs)
-}
-
-use miette::{Diagnostic, SourceSpan};
-use thiserror::Error;
-
-#[derive(Error, Debug, Diagnostic)]
-#[error("Error in configuration file syntax")]
-#[diagnostic()]
-pub struct LexError {
-    // Snippets and highlights can be included in the diagnostic!
-    #[label("Here")]
-    pub err_span: SourceSpan,
-    #[help]
-    pub help_msg: String,
-}
-
-pub fn transform_error(e: ParseError) -> CfgError {
-    let start = e.span.start();
-    let end = e.span.end();
-    let mut len = end - start;
-    if e.t.contains("Unterminated multiline comment") {
-        len = 2;
-    };
-
-    CfgError {
-        err_span: Some(span_start_len(start, len)),
-        help_msg: e.t,
-        file_name: Some(e.span.file_name()),
-        file_content: Some(e.span.file_content()),
-    }
+        .collect::<Result<_>>()?;
+    Ok((exprs, metadata))
 }
diff --git a/parser/src/cfg/str_ext.rs b/parser/src/cfg/str_ext.rs
new file mode 100644
index 000000000..df4d43800
--- /dev/null
+++ b/parser/src/cfg/str_ext.rs
@@ -0,0 +1,29 @@
+pub trait TrimAtomQuotes {
+    fn trim_atom_quotes(&self) -> &str;
+}
+
+impl TrimAtomQuotes for str {
+    fn trim_atom_quotes(&self) -> &str {
+        match self.strip_prefix("r#\"") {
+            Some(a) => a.strip_suffix("\"#").unwrap_or(a),
+            None => self
+                .strip_prefix('"')
+                .unwrap_or(self)
+                .strip_suffix('"')
+                .unwrap_or(self),
+        }
+    }
+}
+
+impl TrimAtomQuotes for String {
+    fn trim_atom_quotes(&self) -> &str {
+        match self.as_str().strip_prefix("r#\"") {
+            Some(a) => a.strip_suffix("\"#").unwrap_or(a),
+            None => self
+                .strip_prefix('"')
+                .unwrap_or(self)
+                .strip_suffix('"')
+                .unwrap_or(self),
+        }
+    }
+}
diff --git a/parser/src/cfg/switch.rs b/parser/src/cfg/switch.rs
new file mode 100644
index 000000000..bfba00af2
--- /dev/null
+++ b/parser/src/cfg/switch.rs
@@ -0,0 +1,529 @@
+use super::*;
+use crate::{anyhow_expr, bail, bail_expr};
+
+#[allow(unused)]
+/// The function stored inside `Switch.init_callback`.
+pub(crate) type InitFn = dyn Fn() + Send + Sync;
+#[allow(unused)]
+/// The function type stored inside `Switch.callbacks`.
+pub(crate) type CallbackFn = dyn Fn() -> bool + Send + Sync;
+
+#[derive(Default)]
+struct OptionalSwitchArgs {
+    #[cfg(feature = "cmd")]
+    init_cmd: Option<&'static InitFn>,
+}
+
+#[cfg(feature = "cmd")]
+pub(crate) mod cmd {
+    //! Global cmd results for switch processing.
+    //! This should not impact runtime which is single threaded in the kanata/keyberon execution
+    //! but this impacts possible future testability for parallel unit tests.
+    //! In practice at the time of writing the cmd actions are not simulation-tested today.
+
+    use super::*;
+    use std::sync::LazyLock;
+    use std::sync::Mutex;
+    use std::sync::atomic::AtomicI32;
+
+    static LATEST_EXIT_CODE: AtomicI32 = AtomicI32::new(0);
+
+    static LATEST_STDOUT: LazyLock<Mutex<String>> = LazyLock::new(|| Mutex::new(String::new()));
+
+    static LATEST_STDERR: LazyLock<Mutex<String>> = LazyLock::new(|| Mutex::new(String::new()));
+
+    struct CmdState {
+        // First item is the binary; the remaining (i.e. `&[1..]`) are arguments.
+        binary_then_args: &'static [&'static str],
+    }
+
+    impl CmdState {
+        fn binary(&self) -> &str {
+            self.binary_then_args[0]
+        }
+        fn args(&self) -> &[&str] {
+            &self.binary_then_args[1..]
+        }
+    }
+
+    /// Invariant: binary_then_args must not be empty.
+    /// Turn the cmd configuration into a callback used by keyberon.
+    pub(crate) fn create_init_fn(
+        binary_then_args: Vec<String>,
+        s: &ParserState,
+    ) -> &'static InitFn {
+        assert!(!binary_then_args.is_empty());
+        let binary_then_args = binary_then_args
+            .into_iter()
+            .map(|v| s.a.sref_str(v))
+            .collect();
+        let binary_then_args = s.a.sref_vec(binary_then_args);
+
+        s.a.sref(|| {
+            let cmd_cfg = cmd::CmdState { binary_then_args };
+            let mut cmd = std::process::Command::new(cmd_cfg.binary());
+            for arg in cmd_cfg.args() {
+                cmd.arg(arg);
+            }
+            match cmd.output() {
+                Ok(output) => {
+                    let exit_code = output.status.code().unwrap_or(1);
+                    let stdout = String::from_utf8_lossy(&output.stdout);
+                    let stderr = String::from_utf8_lossy(&output.stderr);
+                    cmd::LATEST_EXIT_CODE.store(exit_code, std::sync::atomic::Ordering::Release);
+                    *cmd::LATEST_STDOUT.lock().expect("unpoisoned") = stdout.into();
+                    *cmd::LATEST_STDERR.lock().expect("unpoisoned") = stderr.into();
+                }
+                Err(e) => {
+                    log::error!("Failed to execute program {:?}: {}", cmd.get_program(), e);
+                    cmd::LATEST_EXIT_CODE.store(1, std::sync::atomic::Ordering::Release);
+                    cmd::LATEST_STDOUT.lock().expect("unpoisoned").clear();
+                    cmd::LATEST_STDERR.lock().expect("unpoisoned").clear();
+                }
+            };
+        })
+    }
+
+    pub(crate) fn create_exitcode_callback(exitcode: i32, s: &ParserState) -> &'static CallbackFn {
+        s.a.sref(move || {
+            cmd::LATEST_EXIT_CODE.load(std::sync::atomic::Ordering::Acquire) == exitcode
+        })
+    }
+}
+
+fn parse_optional_arguments<'a>(
+    params: &'a [SExpr],
+    s: &ParserState,
+) -> Result<(OptionalSwitchArgs, &'a [SExpr])> {
+    if params.is_empty() {
+        return Ok((OptionalSwitchArgs::default(), params));
+    }
+    let Some((first_atom, params_after_first)) = parse_list_with_first_atom(&params[0], s) else {
+        return Ok((OptionalSwitchArgs::default(), params));
+    };
+    match first_atom {
+        "init-cmd" => {
+            #[cfg(not(feature = "cmd"))]
+            {
+                let _ = params_after_first; // suppress unused
+                bail_expr!(
+                    &params[0],
+                    "cmd is not enabled for this kanata executable. \
+                     Use a cmd_allowed prebuilt executable or compile with the feature: cmd."
+                );
+            }
+            #[cfg(feature = "cmd")]
+            {
+                if !s.is_cmd_enabled {
+                    bail_expr!(
+                        &params[0],
+                        "To use cmd you must put in defcfg: danger-enable-cmd yes."
+                    );
+                }
+                let mut binary_then_args = vec![];
+                collect_strings(params_after_first, &mut binary_then_args, s);
+                if binary_then_args.is_empty() {
+                    bail_expr!(
+                        &params[0],
+                        "cmd must have at least one atom for the binary to execute: <binary> [...args]"
+                    );
+                }
+                Ok((
+                    OptionalSwitchArgs {
+                        init_cmd: Some(cmd::create_init_fn(binary_then_args, s)),
+                    },
+                    &params[1..],
+                ))
+            }
+        }
+        _ => Ok((OptionalSwitchArgs::default(), params)),
+    }
+}
+
+pub fn parse_switch(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_STR: &str =
+        "switch expects triples of params: <key match> <action> <break|fallthrough>";
+
+    let (opts, remaining_params) = parse_optional_arguments(ac_params, s)?;
+
+    let mut cases = vec![];
+    let mut callbacks = vec![];
+    let mut params = remaining_params.iter();
+
+    while let Some(key_match) = params.next() {
+        let Some(action) = params.next() else {
+            bail!("{ERR_STR}\nMissing <action> and <break|fallthrough> for the final triple");
+        };
+        let Some(break_or_fallthrough_expr) = params.next() else {
+            bail!("{ERR_STR}\nMissing <break|fallthrough> for the final triple");
+        };
+
+        let Some(key_match) = key_match.list(s.vars()) else {
+            bail_expr!(key_match, "{ERR_STR}\n<key match> must be a list")
+        };
+        let mut ops = vec![];
+        for op in key_match.iter() {
+            parse_switch_case_bool(1, op, &mut ops, &mut callbacks, s)?;
+        }
+
+        let action = parse_action(action, s)?;
+
+        let Some(break_or_fallthrough) = break_or_fallthrough_expr.atom(s.vars()) else {
+            bail_expr!(
+                break_or_fallthrough_expr,
+                "{ERR_STR}\nthis must be one of: break, fallthrough"
+            );
+        };
+        let break_or_fallthrough = match break_or_fallthrough {
+            "break" => BreakOrFallthrough::Break,
+            "fallthrough" => BreakOrFallthrough::Fallthrough,
+            _ => bail_expr!(
+                break_or_fallthrough_expr,
+                "{ERR_STR}\nthis must be one of: break, fallthrough"
+            ),
+        };
+        cases.push((s.a.sref_vec(ops), action, break_or_fallthrough));
+    }
+
+    let init_fn = {
+        #[cfg(not(feature = "cmd"))]
+        {
+            let _ = opts; // suppress unused
+            None
+        }
+        #[cfg(feature = "cmd")]
+        {
+            opts.init_cmd
+        }
+    };
+
+    Ok(s.a.sref(Action::Switch(s.a.sref(Switch {
+        cases: s.a.sref_vec(cases),
+        init_fn,
+        callbacks: s.a.sref_vec(callbacks),
+    }))))
+}
+
+pub fn parse_switch_case_bool(
+    depth: u8,
+    op_expr: &SExpr,
+    ops: &mut Vec<OpCode>,
+    callbacks: &mut Vec<&'static CallbackFn>,
+    s: &ParserState,
+) -> Result<()> {
+    if ops.len() > MAX_OPCODE_LEN as usize {
+        bail_expr!(
+            op_expr,
+            "maximum key match size of {MAX_OPCODE_LEN} items is exceeded"
+        );
+    }
+    if usize::from(depth) > MAX_BOOL_EXPR_DEPTH {
+        bail_expr!(
+            op_expr,
+            "maximum key match expression depth {MAX_BOOL_EXPR_DEPTH} is exceeded"
+        );
+    }
+    if let Some(a) = op_expr.atom(s.vars()) {
+        let osc = str_to_oscode(a).ok_or_else(|| anyhow_expr!(op_expr, "invalid key name"))?;
+        ops.push(OpCode::new_key(osc.into()));
+        Ok(())
+    } else {
+        let l = op_expr
+            .list(s.vars())
+            .expect("must be a list, checked atom");
+        if l.is_empty() {
+            bail_expr!(op_expr, "switch logic cannot contain empty lists inside");
+        }
+        #[derive(PartialEq)]
+        enum AllowedListOps {
+            Or,
+            And,
+            Not,
+            KeyHistory,
+            KeyTiming,
+            Input,
+            InputHistory,
+            Layer,
+            BaseLayer,
+            DeviceHistory,
+            CmdExit,
+        }
+        #[derive(Copy, Clone)]
+        enum InputType {
+            Real,
+            Virtual,
+        }
+        impl InputType {
+            fn to_row(self) -> u8 {
+                match self {
+                    InputType::Real => 0,
+                    InputType::Virtual => 1,
+                }
+            }
+        }
+        let op = l[0]
+            .atom(s.vars())
+            .and_then(|s| match s {
+                "or" => Some(AllowedListOps::Or),
+                "and" => Some(AllowedListOps::And),
+                "not" => Some(AllowedListOps::Not),
+                "key-history" => Some(AllowedListOps::KeyHistory),
+                "key-timing" => Some(AllowedListOps::KeyTiming),
+                "input" => Some(AllowedListOps::Input),
+                "input-history" => Some(AllowedListOps::InputHistory),
+                "layer" => Some(AllowedListOps::Layer),
+                "base-layer" => Some(AllowedListOps::BaseLayer),
+                "device-history" => Some(AllowedListOps::DeviceHistory),
+                "cmd-exit" => Some(AllowedListOps::CmdExit),
+                _ => None,
+            })
+            .ok_or_else(|| {
+                anyhow_expr!(
+                    op_expr,
+                    "lists inside switch logic must begin with one of:\n\
+                    or | and | not | key-history | key-timing\n\
+                    | input | input-history | layer | base-layer | device-history",
+                )
+            })?;
+
+        match op {
+            AllowedListOps::KeyHistory => {
+                if l.len() != 3 {
+                    bail_expr!(
+                        op_expr,
+                        "key-history must have 2 parameters: key, key-recency"
+                    );
+                }
+                let osc = l[1]
+                    .atom(s.vars())
+                    .and_then(str_to_oscode)
+                    .ok_or_else(|| anyhow_expr!(&l[1], "invalid key name"))?;
+                let key_recency = parse_u8_with_range(&l[2], s, "key-recency", 1, 8)? - 1;
+                ops.push(OpCode::new_key_history(osc.into(), key_recency));
+                Ok(())
+            }
+            AllowedListOps::Input => {
+                if l.len() != 3 {
+                    bail_expr!(
+                        op_expr,
+                        "input must have 2 parameters: key-type(virtual|real), key"
+                    );
+                }
+
+                let input_type = match l[1]
+                    .atom(s.vars())
+                    .ok_or_else(|| anyhow_expr!(&l[1], "key-type must be virtual|real"))?
+                {
+                    "real" => InputType::Real,
+                    "fake" | "virtual" => InputType::Virtual,
+                    _ => bail_expr!(op_expr, "key-type must be virtual|real"),
+                };
+                let input = match input_type {
+                    InputType::Real => {
+                        let key = l[2].atom(s.vars()).ok_or_else(|| {
+                            anyhow_expr!(&l[2], "input key name must not be a list")
+                        })?;
+                        u16::from(
+                            str_to_oscode(key)
+                                .ok_or_else(|| anyhow_expr!(&l[2], "invalid input key name"))?,
+                        )
+                    }
+                    InputType::Virtual => parse_vkey_coord(&l[2], s)?.y,
+                };
+                let (op1, op2) = OpCode::new_active_input((input_type.to_row(), input));
+                ops.extend(&[op1, op2]);
+                Ok(())
+            }
+            AllowedListOps::InputHistory => {
+                if l.len() != 4 {
+                    bail_expr!(
+                        op_expr,
+                        "input-history must have 3 parameters: key-type(virtual|real), key, key-recency"
+                    );
+                }
+
+                let input_type = match l[1]
+                    .atom(s.vars())
+                    .ok_or_else(|| anyhow_expr!(&l[1], "key-type must be virtual|real"))?
+                {
+                    "real" => InputType::Real,
+                    "fake" | "virtual" => InputType::Virtual,
+                    _ => bail_expr!(&l[1], "key-type must be virtual|real"),
+                };
+                let input = match input_type {
+                    InputType::Real => {
+                        let key = l[2].atom(s.vars()).ok_or_else(|| {
+                            anyhow_expr!(&l[2], "input key name must not be a list")
+                        })?;
+                        u16::from(
+                            str_to_oscode(key)
+                                .ok_or_else(|| anyhow_expr!(&l[2], "invalid input key name"))?,
+                        )
+                    }
+                    InputType::Virtual => parse_vkey_coord(&l[2], s)?.y,
+                };
+                let key_recency = parse_u8_with_range(&l[3], s, "key-recency", 1, 8)? - 1;
+                let (op1, op2) =
+                    OpCode::new_historical_input((input_type.to_row(), input), key_recency);
+                ops.extend(&[op1, op2]);
+                Ok(())
+            }
+            AllowedListOps::KeyTiming => {
+                if l.len() != 4 {
+                    bail_expr!(
+                        op_expr,
+                        "key-timing must have 3 parameters: key-recency, lt|gt|less-than|greater-than, milliseconds (0-65535)"
+                    );
+                }
+                let nth_key = parse_u8_with_range(&l[1], s, "key-recency", 1, 8)? - 1;
+                let ticks_since = parse_u16(&l[3], s, "milliseconds")?;
+                match l[2].atom(s.vars()).ok_or_else(|| {
+                    anyhow_expr!(
+                        &l[2],
+                        "key-timing 2nd parameter must be one of: lt|gt|less-than|greater-than"
+                    )
+                })? {
+                    "less-than" | "lt" => {
+                        ops.push(OpCode::new_ticks_since_lt(nth_key, ticks_since));
+                    }
+                    "greater-than" | "gt" => {
+                        ops.push(OpCode::new_ticks_since_gt(nth_key, ticks_since));
+                    }
+                    _ => {
+                        bail_expr!(
+                            &l[2],
+                            "key-timing 2nd parameter must be one of: lt|gt|less-than|greater-than"
+                        );
+                    }
+                };
+                s.max_key_timing_check
+                    .set(std::cmp::max(s.max_key_timing_check.get(), ticks_since));
+                Ok(())
+            }
+            AllowedListOps::Layer | AllowedListOps::BaseLayer => {
+                if l.len() != 2 {
+                    bail_expr!(
+                        op_expr,
+                        "{} must have 1 parameter: layer-name",
+                        match op {
+                            AllowedListOps::Layer => "layer",
+                            AllowedListOps::BaseLayer => "base-layer",
+                            _ => unreachable!(),
+                        }
+                    );
+                }
+                let layer = l[1]
+                    .atom(s.vars())
+                    .and_then(|atom| s.layer_idxs.get(atom))
+                    .map(|idx| {
+                        assert!(*idx < MAX_LAYERS);
+                        *idx as u16
+                    })
+                    .ok_or_else(|| anyhow_expr!(&l[1], "not a known layer name"))?;
+                let (op1, op2) = match op {
+                    AllowedListOps::Layer => OpCode::new_layer(layer),
+                    AllowedListOps::BaseLayer => OpCode::new_base_layer(layer),
+                    _ => unreachable!(),
+                };
+                ops.extend(&[op1, op2]);
+                Ok(())
+            }
+            AllowedListOps::DeviceHistory => {
+                if l.len() != 3 {
+                    bail_expr!(
+                        op_expr,
+                        "device-history must have 2 parameters: device-id, device-recency"
+                    );
+                }
+                let id_str = l[1]
+                    .atom(s.vars())
+                    .ok_or_else(|| anyhow_expr!(&l[1], "device ID must be a number (1-255)"))?;
+                let id_num: u8 = id_str
+                    .parse()
+                    .map_err(|_| anyhow_expr!(&l[1], "device ID must be a number (1-255)"))?;
+                let id = std::num::NonZeroU8::new(id_num)
+                    .ok_or_else(|| anyhow_expr!(&l[1], "device ID must be nonzero (1-255)"))?;
+                if let Some(ref devs) = s.input_devices {
+                    if !devs.iter().any(|(did, _)| *did == id) {
+                        bail_expr!(
+                            &l[1],
+                            "device ID {id_num} is not defined in definputdevices"
+                        );
+                    }
+                } else {
+                    bail_expr!(
+                        &l[1],
+                        "cannot use (device-history {id_num} ...) without a definputdevices block"
+                    );
+                }
+                let device_recency = parse_u8_with_range(&l[2], s, "device-recency", 1, 8)? - 1;
+                let (op1, op2) = OpCode::new_device_history(id, device_recency);
+                ops.extend(&[op1, op2]);
+                Ok(())
+            }
+            AllowedListOps::CmdExit => {
+                #[cfg(not(feature = "cmd"))]
+                {
+                    let _ = callbacks; // suppress unused
+                    bail_expr!(
+                        op_expr,
+                        "cmd is not enabled for this kanata executable. \
+                     Use a cmd_allowed prebuilt executable or compile with the feature: cmd."
+                    );
+                }
+                #[cfg(feature = "cmd")]
+                {
+                    if !s.is_cmd_enabled {
+                        bail_expr!(
+                            &op_expr,
+                            "To use cmd you must put in defcfg: danger-enable-cmd yes."
+                        );
+                    }
+                    if l.len() != 2 {
+                        bail_expr!(op_expr, "cmd-exit must have 1 parameter: exit-code");
+                    }
+                    let exit_code = l[1]
+                        .atom(s.vars())
+                        .ok_or_else(|| anyhow_expr!(&l[1], "exit code must be a 32 bit integer"))?;
+                    let exit_code: i32 = exit_code
+                        .parse()
+                        .map_err(|_| anyhow_expr!(&l[1], "exit code must be a 32 bit integer"))?;
+
+                    let index = callbacks.len();
+                    if index > 60000 {
+                        bail_expr!(
+                            op_expr,
+                            "Exceeded limit of 60000 callback-based switch items"
+                        );
+                    }
+                    let index = u16::try_from(index).expect("checked <=60000 earlier");
+                    let callback = cmd::create_exitcode_callback(exit_code, s);
+                    callbacks.push(callback);
+
+                    let (op1, op2) = OpCode::new_callback_index(index);
+                    ops.extend(&[op1, op2]);
+                    Ok(())
+                }
+            }
+            AllowedListOps::Or | AllowedListOps::And | AllowedListOps::Not => {
+                let op = match op {
+                    AllowedListOps::Or => BooleanOperator::Or,
+                    AllowedListOps::And => BooleanOperator::And,
+                    AllowedListOps::Not => BooleanOperator::Not,
+                    _ => unreachable!(),
+                };
+                // insert a placeholder for now, don't know the end index yet.
+                let placeholder_index = ops.len() as u16;
+                ops.push(OpCode::new_bool(op, placeholder_index));
+                for op in l.iter().skip(1) {
+                    parse_switch_case_bool(depth + 1, op, ops, callbacks, s)?;
+                }
+                if ops.len() > usize::from(MAX_OPCODE_LEN) {
+                    bail_expr!(op_expr, "switch logic length has been exceeded");
+                }
+                ops[placeholder_index as usize] = OpCode::new_bool(op, ops.len() as u16);
+                Ok(())
+            }
+        }
+    }
+}
diff --git a/parser/src/cfg/tap_dance.rs b/parser/src/cfg/tap_dance.rs
new file mode 100644
index 000000000..00ee56b2b
--- /dev/null
+++ b/parser/src/cfg/tap_dance.rs
@@ -0,0 +1,34 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+
+pub(crate) fn parse_tap_dance(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    config: TapDanceConfig,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "tap-dance expects a timeout (number) followed by a list of actions";
+    if ac_params.len() != 2 {
+        bail!(ERR_MSG);
+    }
+
+    let timeout = parse_non_zero_u16(&ac_params[0], s, "timeout")?;
+    let actions = ac_params[1]
+        .list(s.vars())
+        .map(|tap_dance_actions| -> Result<Vec<&'static KanataAction>> {
+            let mut actions = Vec::new();
+            for expr in tap_dance_actions {
+                let ac = parse_action(expr, s)?;
+                actions.push(ac);
+            }
+            Ok(actions)
+        })
+        .ok_or_else(|| anyhow_expr!(&ac_params[1], "{ERR_MSG}: expected a list"))??;
+
+    Ok(s.a.sref(Action::TapDance(s.a.sref(TapDance {
+        timeout,
+        actions: s.a.sref_vec(actions),
+        config,
+    }))))
+}
diff --git a/parser/src/cfg/tap_hold.rs b/parser/src/cfg/tap_hold.rs
new file mode 100644
index 000000000..b910e34e0
--- /dev/null
+++ b/parser/src/cfg/tap_hold.rs
@@ -0,0 +1,471 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+/// Options that can be specified as trailing `(keyword value)` lists on any tap-hold action.
+#[derive(Default)]
+pub(crate) struct TapHoldOptions {
+    pub(crate) require_prior_idle: Option<u16>,
+}
+
+/// Parse the value of a `(tap-repress-timeout <ms>)` option list.
+pub(crate) fn parse_tap_repress_timeout_option(
+    option: &[SExpr],
+    option_expr: &SExpr,
+    s: &ParserState,
+) -> Result<u16> {
+    if option.len() != 2 {
+        bail_expr!(
+            option_expr,
+            "tap-repress-timeout option expects exactly 2 items: \
+            `(tap-repress-timeout <ms>)`"
+        );
+    }
+    parse_u16(&option[1], s, "tap-repress-timeout")
+}
+
+/// Parse the value of a `(require-prior-idle <ms>)` option list.
+/// Validates that the list has exactly 2 items and the value is a u16.
+pub(crate) fn parse_require_prior_idle_option(
+    option: &[SExpr],
+    option_expr: &SExpr,
+    s: &ParserState,
+) -> Result<u16> {
+    if option.len() != 2 {
+        bail_expr!(
+            option_expr,
+            "require-prior-idle option expects exactly 2 items: \
+            `(require-prior-idle <ms>)`"
+        );
+    }
+    let prior_idle = parse_u16(&option[1], s, "require-prior-idle")?;
+    s.max_key_timing_check
+        .set(std::cmp::max(prior_idle, s.max_key_timing_check.get()));
+    Ok(prior_idle)
+}
+
+/// Parse trailing `(keyword value)` option lists from tap-hold action parameters.
+/// Returns the parsed options. Errors on unknown or duplicate options.
+pub(crate) fn parse_tap_hold_options(
+    option_exprs: &[SExpr],
+    s: &ParserState,
+) -> Result<TapHoldOptions> {
+    let mut opts = TapHoldOptions::default();
+    let mut seen_options: HashSet<&str> = HashSet::default();
+
+    for option_expr in option_exprs {
+        let Some(option) = option_expr.list(s.vars()) else {
+            bail_expr!(
+                option_expr,
+                "expected option list, e.g. `(require-prior-idle 150)`"
+            );
+        };
+        if option.is_empty() {
+            bail_expr!(option_expr, "option list cannot be empty");
+        }
+        let kw = option[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&option[0], "option name must be a string"))?;
+        if !seen_options.insert(kw) {
+            bail_expr!(&option[0], "duplicate option '{}'", kw);
+        }
+        match kw {
+            "require-prior-idle" => {
+                opts.require_prior_idle =
+                    Some(parse_require_prior_idle_option(option, option_expr, s)?);
+            }
+            _ => bail_expr!(
+                &option[0],
+                "unknown tap-hold option '{}'. \
+                Valid options: require-prior-idle",
+                kw
+            ),
+        }
+    }
+    Ok(opts)
+}
+
+const TAP_HOLD_OPTION_KEYWORDS: &[&str] = &["require-prior-idle"];
+const TAP_HOLD_KEYS_OPTION_KEYWORDS: &[&str] = &[
+    "require-prior-idle",
+    "tap-on-press",
+    "tap-on-press-release",
+    "hold-on-press",
+];
+
+/// Count how many trailing expressions are tap-hold option lists.
+/// An option list is a list whose first element is a known option keyword.
+/// Stops at the first non-option expression (scanning from the end).
+fn count_trailing_options(ac_params: &[SExpr], s: &ParserState) -> usize {
+    let mut count = 0;
+    for expr in ac_params.iter().rev() {
+        if let Some(list) = expr.list(s.vars()) {
+            if let Some(kw) = list.first().and_then(|e| e.atom(s.vars())) {
+                if TAP_HOLD_OPTION_KEYWORDS.contains(&kw) {
+                    count += 1;
+                    continue;
+                }
+            }
+        }
+        break;
+    }
+    count
+}
+
+pub(crate) fn parse_tap_hold(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    config: HoldTapConfig<'static>,
+) -> Result<&'static KanataAction> {
+    let n_opts = count_trailing_options(ac_params, s);
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 4 {
+        bail!(
+            r"tap-hold expects 4 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <hold-timeout> <tap-action> <hold-action>",
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+    let opts = parse_tap_hold_options(&ac_params[n_positional..], s)?;
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config,
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *hold_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle: opts.require_prior_idle,
+    }))))
+}
+
+pub(crate) fn parse_tap_hold_timeout(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    config: HoldTapConfig<'static>,
+) -> Result<&'static KanataAction> {
+    const PARAMS_FOR_RELEASE: &str = "Params in order:\n\
+       <tap-repress-timeout> <hold-timeout> <tap-action> <hold-action> <timeout-action> [?reset-timeout-on-press]";
+    let n_opts = count_trailing_options(ac_params, s);
+    let n_positional = ac_params.len() - n_opts;
+    match config {
+        HoldTapConfig::PermissiveHold => {
+            if n_positional != 5 && n_positional != 6 {
+                bail!(
+                    "tap-hold-release-timeout expects at least 5 items after it, got {}.\n\
+                    {PARAMS_FOR_RELEASE}",
+                    n_positional,
+                )
+            }
+        }
+        HoldTapConfig::HoldOnOtherKeyPress => {
+            if n_positional != 5 {
+                bail!(
+                    "tap-hold-press-timeout expects 5 items after it, got {}.\n\
+                    Params in order:\n\
+                    <tap-repress-timeout> <hold-timeout> <tap-action> <hold-action> <timeout-action>",
+                    n_positional,
+                )
+            }
+        }
+        _ => unreachable!("other configs not expected"),
+    };
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    let timeout_action = parse_action(&ac_params[4], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+    let on_press_reset_timeout_to = match config {
+        HoldTapConfig::PermissiveHold => match n_positional {
+            6 => match ac_params[5].atom(s.vars()) {
+                Some("reset-timeout-on-press") => std::num::NonZeroU16::new(hold_timeout),
+                _ => bail_expr!(&ac_params[5], "Unexpected parameter.\n{PARAMS_FOR_RELEASE}"),
+            },
+            5 => None,
+            _ => unreachable!("other lengths not expected"),
+        },
+        HoldTapConfig::HoldOnOtherKeyPress => None,
+        _ => unreachable!("other configs not expected"),
+    };
+    let opts = parse_tap_hold_options(&ac_params[n_positional..], s)?;
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config,
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *timeout_action,
+        on_press_reset_timeout_to,
+        require_prior_idle: opts.require_prior_idle,
+    }))))
+}
+
+pub(crate) fn parse_tap_hold_order(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let n_opts = count_trailing_options(ac_params, s);
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 4 {
+        bail!(
+            r"tap-hold-order expects 4 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <buffer-ms> <tap-action> <hold-action>",
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let buffer = parse_u16(&ac_params[1], s, "buffer")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+    let opts = parse_tap_hold_options(&ac_params[n_positional..], s)?;
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Order { buffer },
+        tap_hold_interval: tap_repress_timeout,
+        timeout: u16::MAX, // Resolution is purely event-driven, not timeout-based.
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *tap_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle: opts.require_prior_idle,
+    }))))
+}
+
+pub(crate) fn parse_tap_hold_keys(
+    ac_params: &[SExpr],
+    s: &ParserState,
+    custom_name: &str,
+    custom_func: TapHoldCustomFunc,
+) -> Result<&'static KanataAction> {
+    let n_opts = count_trailing_options(ac_params, s);
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 5 {
+        bail!(
+            r"{} expects 5 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <hold-timeout> <tap-action> <hold-action> <tap-trigger-keys>",
+            custom_name,
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    let tap_trigger_keys = parse_key_list(&ac_params[4], s, "tap-trigger-keys")?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+    let opts = parse_tap_hold_options(&ac_params[n_positional..], s)?;
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_func(&tap_trigger_keys, &s.a)),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *hold_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle: opts.require_prior_idle,
+    }))))
+}
+
+pub(crate) fn parse_tap_hold_keys_trigger_tap_release(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    let n_opts = count_trailing_options(ac_params, s);
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 6 {
+        bail!(
+            r"{} expects 6 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <hold-timeout> <tap-action> <hold-action> <tap-trigger-keys-on-press> <tap-trigger-keys-on-press-then-release>",
+            TAP_HOLD_RELEASE_KEYS_TAP_RELEASE,
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    let tap_trigger_keys_on_press =
+        parse_key_list(&ac_params[4], s, "tap-trigger-keys-on-multi-press")?;
+    let tap_trigger_keys_on_press_then_release =
+        parse_key_list(&ac_params[5], s, "tap-trigger-keys-on-release")?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+    let opts = parse_tap_hold_options(&ac_params[n_positional..], s)?;
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_tap_hold_release_trigger_tap_release(
+            &tap_trigger_keys_on_press,
+            &tap_trigger_keys_on_press_then_release,
+            &s.a,
+        )),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *hold_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle: opts.require_prior_idle,
+    }))))
+}
+
+pub(crate) fn parse_tap_hold_keys_named_lists(
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    // Count trailing options using the extended keyword set.
+    let n_opts = {
+        let mut count = 0;
+        for expr in ac_params.iter().rev() {
+            if let Some(list) = expr.list(s.vars()) {
+                if let Some(kw) = list.first().and_then(|e| e.atom(s.vars())) {
+                    if TAP_HOLD_KEYS_OPTION_KEYWORDS.contains(&kw) {
+                        count += 1;
+                        continue;
+                    }
+                }
+            }
+            break;
+        }
+        count
+    };
+    let n_positional = ac_params.len() - n_opts;
+    if n_positional != 4 {
+        bail!(
+            r"{} expects 4 items after it, got {}.
+Params in order:
+<tap-repress-timeout> <hold-timeout> <tap-action> <hold-action>
+Followed by optional lists:
+(tap-on-press <keys...>) (tap-on-press-release <keys...>) (hold-on-press <keys...>)
+(require-prior-idle <ms>)",
+            TAP_HOLD_KEYS,
+            n_positional,
+        )
+    }
+    let tap_repress_timeout = parse_u16(&ac_params[0], s, "tap repress timeout")?;
+    let hold_timeout = parse_non_zero_u16(&ac_params[1], s, "hold timeout")?;
+    let tap_action = parse_action(&ac_params[2], s)?;
+    let hold_action = parse_action(&ac_params[3], s)?;
+    if matches!(tap_action, Action::HoldTap { .. }) {
+        bail!("tap-hold does not work in the tap-action of tap-hold")
+    }
+
+    let mut require_prior_idle = None;
+    let mut tap_on_press: Vec<OsCode> = vec![];
+    let mut tap_on_press_release: Vec<OsCode> = vec![];
+    let mut hold_on_press: Vec<OsCode> = vec![];
+    let mut seen_options: HashSet<&str> = HashSet::default();
+    let mut seen_keys: HashSet<OsCode> = HashSet::default();
+
+    for option_expr in &ac_params[n_positional..] {
+        let Some(option) = option_expr.list(s.vars()) else {
+            bail_expr!(
+                option_expr,
+                "expected option list, e.g. `(tap-on-press a b c)`"
+            );
+        };
+        if option.is_empty() {
+            bail_expr!(option_expr, "option list cannot be empty");
+        }
+        let kw = option[0]
+            .atom(s.vars())
+            .ok_or_else(|| anyhow_expr!(&option[0], "option name must be a string"))?;
+        if !seen_options.insert(kw) {
+            bail_expr!(&option[0], "duplicate option '{}'", kw);
+        }
+        match kw {
+            "require-prior-idle" => {
+                require_prior_idle = Some(parse_require_prior_idle_option(option, option_expr, s)?);
+            }
+            "tap-on-press" => {
+                tap_on_press =
+                    parse_key_list_from_option(option, option_expr, s, kw, &mut seen_keys)?;
+            }
+            "tap-on-press-release" => {
+                tap_on_press_release =
+                    parse_key_list_from_option(option, option_expr, s, kw, &mut seen_keys)?;
+            }
+            "hold-on-press" => {
+                hold_on_press =
+                    parse_key_list_from_option(option, option_expr, s, kw, &mut seen_keys)?;
+            }
+            _ => bail_expr!(
+                &option[0],
+                "unknown tap-hold-keys option '{}'. \
+                Valid options: tap-on-press, tap-on-press-release, hold-on-press, require-prior-idle",
+                kw
+            ),
+        }
+    }
+
+    Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
+        config: HoldTapConfig::Custom(custom_tap_hold_keys(
+            &tap_on_press,
+            &tap_on_press_release,
+            &hold_on_press,
+            &s.a,
+        )),
+        tap_hold_interval: tap_repress_timeout,
+        timeout: hold_timeout,
+        tap: *tap_action,
+        hold: *hold_action,
+        timeout_action: *hold_action,
+        on_press_reset_timeout_to: None,
+        require_prior_idle,
+    }))))
+}
+
+/// Parse keys from a named option list like `(tap-on-press a b c)`.
+/// The first element is the keyword, remaining elements are key names.
+fn parse_key_list_from_option(
+    option: &[SExpr],
+    option_expr: &SExpr,
+    s: &ParserState,
+    kw: &str,
+    seen_keys: &mut HashSet<OsCode>,
+) -> Result<Vec<OsCode>> {
+    if option.len() < 2 {
+        bail_expr!(
+            option_expr,
+            "{} expects at least one key, e.g. `({} a b c)`",
+            kw,
+            kw
+        );
+    }
+    let mut keys = Vec::new();
+    for key in &option[1..] {
+        let a = key.atom(s.vars()).ok_or_else(|| {
+            anyhow_expr!(key, "string of a known key is expected, found list instead")
+        })?;
+        let osc = str_to_oscode(a)
+            .ok_or_else(|| anyhow_expr!(key, "string of a known key is expected"))?;
+        if !seen_keys.insert(osc) {
+            bail_expr!(
+                key,
+                "key '{}' is already used in another tap-hold-keys option list",
+                a
+            );
+        }
+        keys.push(osc);
+    }
+    Ok(keys)
+}
diff --git a/parser/src/cfg/tests.rs b/parser/src/cfg/tests.rs
index 6b5cbf544..c8a599942 100644
--- a/parser/src/cfg/tests.rs
+++ b/parser/src/cfg/tests.rs
@@ -1,10 +1,74 @@
 use super::*;
-use crate::cfg::sexpr::parse;
+#[allow(unused_imports)]
+use crate::cfg::sexpr::{Span, parse};
+use kanata_keyberon::action::BooleanOperator::*;
 
-use std::sync::Mutex;
+use std::sync::{Mutex, MutexGuard};
+
+mod ambiguous;
+mod defcfg;
+mod defhands;
+mod device_detect;
+mod environment;
+mod macros;
 
 static CFG_PARSE_LOCK: Mutex<()> = Mutex::new(());
 
+fn init_log() {
+    use simplelog::*;
+    use std::sync::OnceLock;
+    static LOG_INIT: OnceLock<()> = OnceLock::new();
+    LOG_INIT.get_or_init(|| {
+        let mut log_cfg = ConfigBuilder::new();
+        if let Err(e) = log_cfg.set_time_offset_to_local() {
+            eprintln!("WARNING: could not set log TZ to local: {e:?}");
+        };
+        log_cfg.set_time_format_rfc3339();
+        CombinedLogger::init(vec![TermLogger::new(
+            // Note: set to a different level to see logs in tests.
+            // Also, not all tests call init_log so you might have to add the call there too.
+            LevelFilter::Error,
+            log_cfg.build(),
+            TerminalMode::Stderr,
+            ColorChoice::AlwaysAnsi,
+        )])
+        .expect("logger can init");
+    });
+}
+
+fn lock<T>(lk: &Mutex<T>) -> MutexGuard<'_, T> {
+    match lk.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => poisoned.into_inner(),
+    }
+}
+
+fn parse_cfg(cfg: &str) -> Result<IntermediateCfg> {
+    init_log();
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let icfg = parse_cfg_raw_string(
+        cfg,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    );
+    if let Ok(ref icfg) = icfg {
+        assert!(icfg.klayers.layers.iter().all(|layer| {
+            layer[usize::from(NORMAL_KEY_ROW)]
+                .iter()
+                .all(|action| *action != DEFAULT_ACTION)
+        }));
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+        assert!(icfg.options.linux_opts.linux_device_detect_mode.is_some());
+    }
+    icfg
+}
+
 #[test]
 fn sizeof_action_is_two_usizes() {
     assert_eq!(
@@ -14,70 +78,122 @@ fn sizeof_action_is_two_usizes() {
 }
 
 #[test]
-fn span_works() {
+fn test_span_absolute_ranges() {
     let s = "(hello world my oyster)\n(row two)";
     let tlevel = parse(s, "test").unwrap();
     assert_eq!(
-        &s[tlevel[0].span.start..tlevel[0].span.end],
+        &s[tlevel[0].span.start()..tlevel[0].span.end()],
         "(hello world my oyster)"
     );
-    assert_eq!(&s[tlevel[1].span.start..tlevel[1].span.end], "(row two)");
+    assert_eq!(
+        &s[tlevel[1].span.start()..tlevel[1].span.end()],
+        "(row two)"
+    );
 }
 
 #[test]
-fn parse_simple() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    new_from_file(&std::path::PathBuf::from("../cfg_samples/simple.kbd")).unwrap();
-}
+fn span_works_with_unicode_characters() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"(defsrc a) ;; 😊
+(deflayer base @😊)
+"#;
+    let span = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect_err("should be an error because @😊 is not defined")
+    .span
+    .expect("span should be Some");
 
-#[test]
-fn parse_minimal() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    new_from_file(&std::path::PathBuf::from("../cfg_samples/minimal.kbd")).unwrap();
-}
+    assert_eq!(&source[span.start()..span.end()], "@😊");
 
-#[test]
-fn parse_default() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    new_from_file(&std::path::PathBuf::from("../cfg_samples/kanata.kbd")).unwrap();
+    assert_eq!(span.start.line, 1);
+    assert_eq!(span.end.line, 1);
+
+    assert_eq!("😊".len(), 4);
+    assert_eq!("(defsrc a) ;; 😊\n".len(), 19);
+    assert_eq!(span.start.line_beginning, 19);
+    assert_eq!(span.end.line_beginning, 19);
 }
 
 #[test]
-fn parse_jtroo() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let cfg = new_from_file(&std::path::PathBuf::from("../cfg_samples/jtroo.kbd")).unwrap();
-    assert_eq!(cfg.layer_info.len(), 16);
+fn test_multiline_error_span() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"(defsrc a)
+(
+  🍍
+  🍕
+)
+(defalias a b)
+"#;
+    let span = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect_err("should error on unknown top level block")
+    .span
+    .expect("span should be Some");
+
+    assert_eq!(&source[span.start()..span.end()], "(\n  🍍\n  🍕\n)");
+
+    assert_eq!(span.start.line, 1);
+    assert_eq!(span.end.line, 4);
+
+    assert_eq!(span.start.line_beginning, "(defsrc a)\n".len());
+    assert_eq!(span.end.line_beginning, "(defsrc a)\n(\n  🍍\n  🍕\n".len());
 }
 
 #[test]
-fn parse_f13_f24() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    new_from_file(&std::path::PathBuf::from("../cfg_samples/f13_f24.kbd")).unwrap();
+fn test_span_of_an_unterminated_block_comment_error() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"(defsrc a) |# I'm an unterminated block comment..."#;
+    let span = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect_err("should be an unterminated comment error")
+    .span
+    .expect("span should be Some");
+
+    assert_eq!(&source[span.start()..span.end()], "|#");
+
+    assert_eq!(span.start.line, 0);
+    assert_eq!(span.end.line, 0);
+
+    assert_eq!(span.start.line_beginning, 0);
+    assert_eq!(span.end.line_beginning, 0);
 }
 
 #[test]
 fn parse_action_vars() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let mut s = ParsedState::default();
     let source = r#"
+(defvirtualkeys
+  ctl lctl
+  sft lsft
+  met lmet
+  alt lalt
+)
 (defvar
   one 1
   two 2
@@ -105,24 +221,64 @@ fn parse_action_vars() {
   rlk (release-key $one)
   mul (multi $two $one)
   mwu (mwheel-up $one $two)
+  mwua (🖱☸↑ $one $two)
+  mwda (🖱☸↓ $one $two)
+  mwla (🖱☸← $one $two)
+  mwra (🖱☸→ $one $two)
+  mmua (🖱↑ $one $two)
+  mmda (🖱↓ $one $two)
+  mmla (🖱← $one $two)
+  mmra (🖱→ $one $two)
   mmu (movemouse-up $one $two)
   mau (movemouse-accel-up $one $two $one $two)
+  maua (🖱accel↑ $one $two $one $two)
+  mada (🖱accel↓ $one $two $one $two)
+  mala (🖱accel← $one $two $one $two)
+  mara (🖱accel→ $one $two $one $two)
   ons (one-shot $one $two)
   thd (tap-hold $one $two $chr $two)
   tht (tap-hold-release-timeout $one $two $chr $two $one)
   thk (tap-hold-release-keys $one $two $chr $two $three)
+  the (tap-hold-except-keys $one $two $chr $two $three)
+  thtt (tap-hold-tap-keys $one $two $chr $two $three)
+  thta (tap⬓↑timeout $one $two $chr $two $one)
+  thka (tap⬓↑keys $one $two $chr $two $three)
+  thea (tap⬓⤫keys $one $two $chr $two $three)
+  thtta (tap⬓tapkeys $one $two $chr $two $three)
   mac (macro $one $two $one $two $chr C-S-$three $one)
   rmc (macro-repeat $one $two $one $two $chr C-S-$three $one)
+  mrca (macro↑⤫ $one 500 bspc S-1 500 bspc S-2)
+  mrra (macro⟳↑⤫ mltp)
+  oat (tap⬓↓timeout   200 200 o $one bspc)
+  fsta (🖱speed 200)
+  psfa (on↓ press-virtualkey   sft)
+  rsfa (on↑ release-virtualkey sft)
+  os2a (one-shot↓ 2000 lsft)
+  os3a (one-shot↑ 2000 lctl)
+  os4a (one-shot↓⤫ 2000 lalt)
+  os5a (one-shot↑⤫ 2000 lmet)
+  oara (tap⬓↓ 200 200 o $two)
+  echa (tap⬓↑ 200 200 e $two)
+  rmca (macro⟳ $one $two $one $two $chr C-S-$three $one)
   dr1 (dynamic-macro-record $one)
   dp1 (dynamic-macro-play $one)
   abc (arbitrary-code $one)
   opf (on-press-fakekey $one $rel)
   orf (on-release-fakekey $one $rel)
+  opfa (on↓fakekey $one $rel)
+  orfa (on↑fakekey $one $rel)
+  opfda (on↓fakekey-delay 200)
+  orfda (on↑fakekey-delay 200)
+  relka (key↑ $one)
+  rella (layer↑ base)
   fla $full-action
   frk (fork $one $two $five)
   cpw (caps-word-custom $one $three $four)
+  cwa (word⇪ 2000)
+  cpwa (word⇪custom $one $three $four)
   rst (dynamic-macro-record-stop-truncate $one)
   stm (setmouse $one $two)
+  stma (set🖱 $one $two)
 )
 (defsrc a b c d)
 (deflayer base $chord1 $chord2 $chr @tdl)
@@ -139,166 +295,49 @@ fn parse_action_vars() {
 (defchords $e $one $1 $two)
 (defchords $e2 $one ($one) $two)
 "#;
-    parse_cfg_raw_string(source, &mut s, "test")
-        .map_err(|e| {
-            eprintln!("{:?}", error_with_source(e));
-            ""
-        })
-        .unwrap();
-}
-
-#[test]
-fn parse_delegate_to_default_layer_yes() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let mut s = ParsedState::default();
-    let source = r#"
-(defcfg delegate-to-first-layer yes)
-(defsrc a)
-(deflayer base b)
-(deflayer other _)
-"#;
-    let res = parse_cfg_raw_string(source, &mut s, "test")
-        .map_err(|e| {
-            eprintln!("{:?}", error_with_source(e));
-            ""
-        })
-        .unwrap();
-    assert_eq!(
-        res.3[2][0][OsCode::KEY_A.as_u16() as usize],
-        Action::KeyCode(KeyCode::B),
-    );
-}
-
-#[test]
-fn parse_delegate_to_default_layer_yes_but_base_transparent() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let mut s = ParsedState::default();
-    let source = r#"
-(defcfg delegate-to-first-layer yes)
-(defsrc a)
-(deflayer base _)
-(deflayer other _)
-"#;
-    let res = parse_cfg_raw_string(source, &mut s, "test")
-        .map_err(|e| {
-            eprintln!("{:?}", error_with_source(e));
-            ""
-        })
-        .unwrap();
-    assert_eq!(
-        res.3[2][0][OsCode::KEY_A.as_u16() as usize],
-        Action::KeyCode(KeyCode::A),
-    );
-}
-
-#[test]
-fn parse_delegate_to_default_layer_no() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let mut s = ParsedState::default();
-    let source = r#"
-(defcfg delegate-to-first-layer no)
-(defsrc a)
-(deflayer base b)
-(deflayer other _)
-"#;
-    let res = parse_cfg_raw_string(source, &mut s, "test")
-        .map_err(|e| {
-            eprintln!("{:?}", error_with_source(e));
-            ""
-        })
-        .unwrap();
-    assert_eq!(
-        res.3[2][0][OsCode::KEY_A.as_u16() as usize],
-        Action::KeyCode(KeyCode::A),
-    );
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
 }
 
 #[test]
-fn parse_transparent_default() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    let mut s = ParsedState::default();
-    let (_, _, layer_strings, layers, _, _) = parse_cfg_raw(
-        &std::path::PathBuf::from("../cfg_samples/transparent_default.kbd"),
-        &mut s,
-    )
+fn parse_multiline_comment() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from(
+        "./test_cfgs/multiline_comment.kbd",
+    ))
     .unwrap();
-
-    assert_eq!(layer_strings.len(), 4);
-
-    assert_eq!(
-        layers[0][0][usize::from(OsCode::KEY_F13)],
-        Action::KeyCode(KeyCode::F13)
-    );
-    assert_eq!(
-        layers[0][0][usize::from(OsCode::KEY_F14)],
-        Action::DefaultLayer(2)
-    );
-    assert_eq!(layers[0][0][usize::from(OsCode::KEY_F15)], Action::Layer(3));
-    assert_eq!(layers[1][0][usize::from(OsCode::KEY_F13)], Action::Trans);
-    assert_eq!(
-        layers[1][0][usize::from(OsCode::KEY_F14)],
-        Action::DefaultLayer(2)
-    );
-    assert_eq!(layers[1][0][usize::from(OsCode::KEY_F15)], Action::Layer(3));
-    assert_eq!(
-        layers[2][0][usize::from(OsCode::KEY_F13)],
-        Action::DefaultLayer(0)
-    );
-    assert_eq!(layers[2][0][usize::from(OsCode::KEY_F14)], Action::Layer(1));
-    assert_eq!(
-        layers[2][0][usize::from(OsCode::KEY_F15)],
-        Action::KeyCode(KeyCode::F15)
-    );
-    assert_eq!(
-        layers[3][0][usize::from(OsCode::KEY_F13)],
-        Action::DefaultLayer(0)
-    );
-    assert_eq!(layers[3][0][usize::from(OsCode::KEY_F14)], Action::Layer(1));
-    assert_eq!(layers[3][0][usize::from(OsCode::KEY_F15)], Action::Trans);
 }
 
 #[test]
 fn parse_all_keys() {
+    init_log();
     let _lk = match CFG_PARSE_LOCK.lock() {
         Ok(guard) => guard,
         Err(poisoned) => poisoned.into_inner(),
     };
     new_from_file(&std::path::PathBuf::from(
-        "../cfg_samples/all_keys_in_defsrc.kbd",
+        "./test_cfgs/all_keys_in_defsrc.kbd",
     ))
     .unwrap();
 }
 
 #[test]
-fn parse_multiline_comment() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
-    new_from_file(&std::path::PathBuf::from(
-        "./test_cfgs/multiline_comment.kbd",
-    ))
-    .unwrap();
+fn parse_file_with_utf8_bom() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from("./test_cfgs/utf8bom.kbd")).unwrap();
+}
+
+#[test]
+#[cfg(feature = "zippychord")]
+fn parse_zippychord_file() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from("./test_cfgs/testzch.kbd")).unwrap();
 }
 
 #[test]
 fn disallow_nested_tap_hold() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     match new_from_file(&std::path::PathBuf::from("./test_cfgs/nested_tap_hold.kbd"))
         .map_err(|e| format!("{}", e.help().unwrap()))
     {
@@ -309,10 +348,7 @@ fn disallow_nested_tap_hold() {
 
 #[test]
 fn disallow_ancestor_seq() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     match new_from_file(&std::path::PathBuf::from("./test_cfgs/ancestor_seq.kbd"))
         .map_err(|e| format!("{e:?}"))
     {
@@ -323,10 +359,7 @@ fn disallow_ancestor_seq() {
 
 #[test]
 fn disallow_descendent_seq() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     match new_from_file(&std::path::PathBuf::from("./test_cfgs/descendant_seq.kbd"))
         .map_err(|e| format!("{e:?}"))
     {
@@ -337,10 +370,7 @@ fn disallow_descendent_seq() {
 
 #[test]
 fn disallow_multiple_waiting_actions() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     match new_from_file(&std::path::PathBuf::from("./test_cfgs/bad_multi.kbd"))
         .map_err(|e| format!("{}", e.help().unwrap()))
     {
@@ -351,10 +381,7 @@ fn disallow_multiple_waiting_actions() {
 
 #[test]
 fn chord_in_macro_dont_panic() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     new_from_file(&std::path::PathBuf::from(
         "./test_cfgs/macro-chord-dont-panic.kbd",
     ))
@@ -364,10 +391,7 @@ fn chord_in_macro_dont_panic() {
 
 #[test]
 fn unknown_defcfg_item_fails() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     new_from_file(&std::path::PathBuf::from(
         "./test_cfgs/unknown_defcfg_opt.kbd",
     ))
@@ -398,21 +422,23 @@ fn recursive_multi_is_flattened() {
             list!([atom!("multi"), atom!("c"), atom!("mrtp"),])
         ]),
     ];
-    let s = ParsedState::default();
+    let s = ParserState::default();
     if let KanataAction::MultipleActions(parsed_multi) = parse_multi(&params, &s).unwrap() {
-        assert_eq!(parsed_multi.len(), 4);
+        assert_eq!(parsed_multi.len(), 6);
         assert_eq!(parsed_multi[0], Action::KeyCode(KeyCode::A));
-        assert_eq!(parsed_multi[1], Action::KeyCode(KeyCode::B));
-        assert_eq!(parsed_multi[2], Action::KeyCode(KeyCode::C));
+        assert_eq!(parsed_multi[2], Action::KeyCode(KeyCode::B));
+        assert_eq!(parsed_multi[4], Action::KeyCode(KeyCode::C));
+        assert_eq!(
+            parsed_multi[1],
+            Action::Custom(&CustomAction::MouseTap(Btn::Mid))
+        );
         assert_eq!(
             parsed_multi[3],
-            Action::Custom(
-                &&[
-                    &CustomAction::MouseTap(Btn::Mid),
-                    &CustomAction::MouseTap(Btn::Left),
-                    &CustomAction::MouseTap(Btn::Right),
-                ][..]
-            )
+            Action::Custom(&CustomAction::MouseTap(Btn::Left))
+        );
+        assert_eq!(
+            parsed_multi[5],
+            Action::Custom(&CustomAction::MouseTap(Btn::Right))
         );
     } else {
         panic!("multi did not parse into multi");
@@ -423,7 +449,7 @@ fn recursive_multi_is_flattened() {
 fn test_parse_sequence_a_b() {
     let seq = parse_sequence_keys(
         &parse("(a b)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 2);
@@ -435,7 +461,7 @@ fn test_parse_sequence_a_b() {
 fn test_parse_sequence_sa_b() {
     let seq = parse_sequence_keys(
         &parse("(S-a b)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 3);
@@ -448,7 +474,7 @@ fn test_parse_sequence_sa_b() {
 fn test_parse_sequence_sab() {
     let seq = parse_sequence_keys(
         &parse("(S-(a b))", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 3);
@@ -461,7 +487,7 @@ fn test_parse_sequence_sab() {
 fn test_parse_sequence_bigchord() {
     let seq = parse_sequence_keys(
         &parse("(AG-A-M-C-S-(a b) c)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 8);
@@ -479,7 +505,7 @@ fn test_parse_sequence_bigchord() {
 fn test_parse_sequence_inner_chord() {
     let seq = parse_sequence_keys(
         &parse("(S-(a b C-c) d)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 6);
@@ -495,7 +521,7 @@ fn test_parse_sequence_inner_chord() {
 fn test_parse_sequence_earlier_inner_chord() {
     let seq = parse_sequence_keys(
         &parse("(S-(a C-b c) d)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 6);
@@ -511,7 +537,7 @@ fn test_parse_sequence_earlier_inner_chord() {
 fn test_parse_sequence_numbers() {
     let seq = parse_sequence_keys(
         &parse("(0 1 2 3 4 5 6 7 8 9)", "test").expect("parses")[0].t,
-        &ParsedState::default(),
+        &ParserState::default(),
     )
     .expect("parses");
     assert_eq!(seq.len(), 10);
@@ -537,7 +563,7 @@ fn test_parse_macro_numbers() {
     let mut i = 1;
     while !expr_rem.is_empty() {
         let (macro_events, expr_rem_tmp) =
-            parse_macro_item(expr_rem, &ParsedState::default()).expect("parses");
+            parse_macro_item(expr_rem, &ParserState::default()).expect("parses");
         expr_rem = expr_rem_tmp;
         assert_eq!(macro_events.len(), 1);
         match &macro_events[0] {
@@ -548,24 +574,18 @@ fn test_parse_macro_numbers() {
     }
 
     let exprs = parse("(0)", "test").expect("parses")[0].t.clone();
-    parse_macro_item(exprs.as_slice(), &ParsedState::default()).expect_err("errors");
+    parse_macro_item(exprs.as_slice(), &ParserState::default()).expect_err("errors");
 }
 
 #[test]
 fn test_include_good() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     new_from_file(&std::path::PathBuf::from("./test_cfgs/include-good.kbd")).unwrap();
 }
 
 #[test]
 fn test_include_bad_has_filename_included() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     let err = format!(
         "{:?}",
         new_from_file(
@@ -576,10 +596,7 @@ fn test_include_bad_has_filename_included() {
         .map(|_| ())
         .unwrap_err()
     );
-    assert!(err.contains(&format!(
-        "test_cfgs{}included-bad.kbd",
-        std::path::MAIN_SEPARATOR
-    )));
+    assert!(err.contains("included-bad.kbd"));
     assert!(!err.contains(&format!(
         "test_cfgs{}include-bad.kbd",
         std::path::MAIN_SEPARATOR
@@ -588,10 +605,7 @@ fn test_include_bad_has_filename_included() {
 
 #[test]
 fn test_include_bad2_has_original_filename() {
-    let _lk = match CFG_PARSE_LOCK.lock() {
-        Ok(guard) => guard,
-        Err(poisoned) => poisoned.into_inner(),
-    };
+    let _lk = lock(&CFG_PARSE_LOCK);
     let err = format!(
         "{:?}",
         new_from_file(
@@ -611,3 +625,1506 @@ fn test_include_bad2_has_original_filename() {
         std::path::MAIN_SEPARATOR
     )));
 }
+
+#[test]
+fn test_include_ignore_optional_filename() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from(
+        "./test_cfgs/include-good-optional-absent.kbd",
+    ))
+    .unwrap();
+}
+
+#[test]
+fn parse_bad_submacro() {
+    // Test exists since it used to crash. It should not crash.
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a)
+(deflayer base
+  (macro M-s-())
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+}
+
+#[test]
+fn parse_bad_submacro_2() {
+    // Test exists since it used to crash. It should not crash.
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a)
+(deflayer base
+  (macro M-s-g)
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+}
+
+#[test]
+fn parse_nested_macro() {
+    let source = r#"
+(defvar m1 (a b c))
+(defsrc a b)
+(deflayer base
+  (macro $m1)
+  (macro bspc bspc $m1)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_switch() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defvar var1 a)
+(defsrc a)
+(deffakekeys vk1 XX)
+(defvirtualkeys vk2 XX)
+(deflayer base
+  (switch
+    ((and a b (or c d) (or e f))) XX break
+    ((not (and a b (not (or c (not d))) (or e f)))) XX break
+    () _ fallthrough
+    (a b c) $var1 fallthrough
+    ((or (or (or (or (or (or (or (or))))))))) $var1 fallthrough
+    ((key-history a 1) (key-history b 5) (key-history c 8)) $var1 fallthrough
+    ((not
+      (key-timing 1 less-than 200)
+      (key-timing 4 greater-than 500)
+      (key-timing 7 lt 1000)
+      (key-timing 8 gt 20000)
+    )) $var1 fallthrough
+    ((input virtual vk1)) $var1 break
+    ((input real lctl)) $var1 break
+    ((input-history virtual vk2 1)) $var1 break
+    ((input-history real lsft 8)) $var1 break
+  )
+)
+"#;
+    let res = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .unwrap();
+    let (op1, op2) = OpCode::new_active_input((FAKE_KEY_ROW, 0));
+    let (op3, op4) = OpCode::new_active_input((NORMAL_KEY_ROW, u16::from(OsCode::KEY_LEFTCTRL)));
+    let (op5, op6) = OpCode::new_historical_input((FAKE_KEY_ROW, 1), 0);
+    let (op7, op8) =
+        OpCode::new_historical_input((NORMAL_KEY_ROW, u16::from(OsCode::KEY_LEFTSHIFT)), 7);
+    let (klayers, _) = res.klayers.get();
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_A.as_u16() as usize],
+        Action::Switch(&Switch {
+            cases: &[
+                (
+                    &[
+                        OpCode::new_bool(And, 9),
+                        OpCode::new_key(KeyCode::A),
+                        OpCode::new_key(KeyCode::B),
+                        OpCode::new_bool(Or, 6),
+                        OpCode::new_key(KeyCode::C),
+                        OpCode::new_key(KeyCode::D),
+                        OpCode::new_bool(Or, 9),
+                        OpCode::new_key(KeyCode::E),
+                        OpCode::new_key(KeyCode::F),
+                    ],
+                    &Action::NoOp,
+                    BreakOrFallthrough::Break
+                ),
+                (
+                    &[
+                        OpCode::new_bool(Not, 12),
+                        OpCode::new_bool(And, 12),
+                        OpCode::new_key(KeyCode::A),
+                        OpCode::new_key(KeyCode::B),
+                        OpCode::new_bool(Not, 9),
+                        OpCode::new_bool(Or, 9),
+                        OpCode::new_key(KeyCode::C),
+                        OpCode::new_bool(Not, 9),
+                        OpCode::new_key(KeyCode::D),
+                        OpCode::new_bool(Or, 12),
+                        OpCode::new_key(KeyCode::E),
+                        OpCode::new_key(KeyCode::F),
+                    ],
+                    &Action::NoOp,
+                    BreakOrFallthrough::Break
+                ),
+                (&[], &Action::Trans, BreakOrFallthrough::Fallthrough),
+                (
+                    &[
+                        OpCode::new_key(KeyCode::A),
+                        OpCode::new_key(KeyCode::B),
+                        OpCode::new_key(KeyCode::C),
+                    ],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Fallthrough
+                ),
+                (
+                    &[
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                        OpCode::new_bool(Or, 8),
+                    ],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Fallthrough
+                ),
+                (
+                    &[
+                        OpCode::new_key_history(KeyCode::A, 0),
+                        OpCode::new_key_history(KeyCode::B, 4),
+                        OpCode::new_key_history(KeyCode::C, 7),
+                    ],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Fallthrough
+                ),
+                (
+                    &[
+                        OpCode::new_bool(Not, 5),
+                        OpCode::new_ticks_since_lt(0, 200),
+                        OpCode::new_ticks_since_gt(3, 500),
+                        OpCode::new_ticks_since_lt(6, 1000),
+                        OpCode::new_ticks_since_gt(7, 20000),
+                    ],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Fallthrough
+                ),
+                (
+                    &[op1, op2],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Break
+                ),
+                (
+                    &[op3, op4],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Break
+                ),
+                (
+                    &[op5, op6],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Break
+                ),
+                (
+                    &[op7, op8],
+                    &Action::KeyCode(KeyCode::A),
+                    BreakOrFallthrough::Break
+                ),
+            ],
+            init_fn: None,
+            callbacks: &[],
+        })
+    );
+}
+
+#[test]
+fn parse_switch_exceed_depth() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a)
+(deflayer base
+  (switch
+    ((or (or (or (or (or (or (or (or (or)))))))))) XX break
+  )
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+}
+
+#[test]
+fn parse_virtualkeys() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defvar var1 a)
+(defsrc a b c d e f g h i j k l m n o p)
+(deffakekeys hello a)
+(defvirtualkeys bye a)
+(deflayer base
+  (on-press   press-virtualkey hello)
+  (on-press release-virtualkey hello)
+  (on-press  toggle-virtualkey hello)
+  (on-press     tap-virtualkey hello)
+  (on-press   press-vkey bye)
+  (on-press release-vkey bye)
+  (on-press  toggle-vkey bye)
+  (on-press     tap-vkey bye)
+  (on-release   press-virtualkey hello)
+  (on-release release-virtualkey hello)
+  (on-release  toggle-virtualkey hello)
+  (on-release     tap-virtualkey hello)
+  (on-release   press-vkey bye)
+  (on-release release-vkey bye)
+  (on-release  toggle-vkey bye)
+  (on-release     tap-vkey bye)
+)
+"#;
+    let res = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|e| {
+        eprintln!("{:?}", miette::Error::from(e));
+        ""
+    })
+    .unwrap();
+    let (klayers, _) = res.klayers.get();
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_A.as_u16() as usize],
+        Action::Custom(&CustomAction::FakeKey {
+            coord: Coord { x: 1, y: 0 },
+            action: FakeKeyAction::Press,
+        }),
+    );
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_F.as_u16() as usize],
+        Action::Custom(&CustomAction::FakeKey {
+            coord: Coord { x: 1, y: 1 },
+            action: FakeKeyAction::Release,
+        }),
+    );
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_K.as_u16() as usize],
+        Action::Custom(&CustomAction::FakeKeyOnRelease {
+            coord: Coord { x: 1, y: 0 },
+            action: FakeKeyAction::Toggle,
+        }),
+    );
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_P.as_u16() as usize],
+        Action::Custom(&CustomAction::FakeKeyOnRelease {
+            coord: Coord { x: 1, y: 1 },
+            action: FakeKeyAction::Tap,
+        }),
+    );
+}
+
+#[test]
+fn parse_on_idle_fakekey() {
+    let source = r#"
+(defvar var1 a)
+(defsrc a b c d e f g h i)
+(deffakekeys hello a)
+(defvirtualkeys bye a)
+(deflayer base
+  (on-idle-fakekey hello tap 200)
+  (on-idle 100   press-virtualkey hello)
+  (on-idle 100 release-virtualkey hello)
+  (on-idle 100  toggle-virtualkey hello)
+  (on-idle 100     tap-virtualkey hello)
+  (on-idle 100   press-vkey bye)
+  (on-idle 100 release-vkey bye)
+  (on-idle 100  toggle-vkey bye)
+  (on-idle 200     tap-vkey bye)
+)
+"#;
+    let res = parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+    let (klayers, _) = res.klayers.get();
+    assert_eq!(
+        klayers[0][0][OsCode::KEY_A.as_u16() as usize],
+        Action::Custom(&CustomAction::FakeKeyOnIdle(FakeKeyOnIdle {
+            coord: Coord { x: 1, y: 0 },
+            action: FakeKeyAction::Tap,
+            idle_duration: 200
+        })),
+    );
+}
+
+#[test]
+fn parse_on_idle_fakekey_errors() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defvar var1 a)
+(defsrc a)
+(deffakekeys hello a)
+(deflayer base
+  (on-idle-fakekey hello bap 200)
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // comment out to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+
+    let source = r#"
+(defvar var1 a)
+(defsrc a)
+(deffakekeys hello a)
+(deflayer base
+  (on-idle-fakekey jello tap 200)
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+
+    let source = r#"
+(defvar var1 a)
+(defsrc a)
+(deffakekeys hello a)
+(deflayer base
+  (on-idle-fakekey (hello) tap 200)
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+
+    let source = r#"
+(defvar var1 a)
+(defsrc a)
+(deffakekeys hello a)
+(deflayer base
+  (on-idle-fakekey hello tap -1)
+)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|_e| {
+        // uncomment to see what this looks like when running test
+        // eprintln!("{:?}", _e);
+        ""
+    })
+    .unwrap_err();
+}
+
+#[test]
+fn parse_fake_keys_errors_on_too_many() {
+    let mut s = ParserState::default();
+    let mut checked_for_err = false;
+    for n in 0..1000 {
+        let exprs = [&vec![
+            SExpr::Atom(Spanned {
+                t: "deffakekeys".to_string(),
+                span: Default::default(),
+            }),
+            SExpr::Atom(Spanned {
+                t: "a".repeat(n),
+                span: Default::default(),
+            }),
+            SExpr::Atom(Spanned {
+                t: "a".to_string(),
+                span: Default::default(),
+            }),
+        ]];
+        if n < 500 {
+            // fill up fake keys, expect first bunch to succeed
+            parse_fake_keys(&exprs, &mut s).unwrap();
+        } else if n < 999 {
+            // at some point they start failing, ignore result
+            let _ = parse_fake_keys(&exprs, &mut s);
+        } else {
+            // last iteration, check for error. probably happened before this, but just check here
+            let _ = parse_fake_keys(&exprs, &mut s).unwrap_err();
+            checked_for_err = true;
+        }
+    }
+    assert!(checked_for_err);
+}
+
+#[test]
+fn parse_deflocalkeys_overridden() {
+    let source = r#"
+(deflocalkeys-win
++   300
+[   301
+]   302
+{   303
+}   304
+/   305
+;   306
+`   307
+=   308
+-   309
+'   310
+,   311
+.   312
+\   313
+yen 314
+¥   315
+new 316
+)
+(deflocalkeys-winiov2
++   300
+[   301
+]   302
+{   303
+}   304
+/   305
+;   306
+`   307
+=   308
+-   309
+'   310
+,   311
+.   312
+\   313
+yen 314
+¥   315
+new 316
+)
+(deflocalkeys-wintercept
++   300
+[   301
+]   302
+{   303
+}   304
+/   305
+;   306
+`   307
+=   308
+-   309
+'   310
+,   311
+.   312
+\   313
+yen 314
+¥   315
+new 316
+)
+(deflocalkeys-linux
++   300
+[   301
+]   302
+{   303
+}   304
+/   305
+;   306
+`   307
+=   308
+-   309
+'   310
+,   311
+.   312
+\   313
+yen 314
+¥   315
+new 316
+)
+(deflocalkeys-macos
++   300
+[   301
+]   302
+{   303
+}   304
+/   305
+;   306
+`   307
+=   308
+-   309
+'   310
+,   311
+.   312
+\   313
+yen 314
+¥   315
+new 316
+)
+(defsrc + [  ]  {  }  /  ;  `  =  -  '  ,  .  \  yen ¥ new)
+(deflayer base + [  ]  {  }  /  ;  `  =  -  '  ,  .  \  yen ¥ new)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn use_default_overridable_mappings() {
+    let source = r#"
+(defsrc + [  ]  a  b  /  ;  `  =  -  '  ,  .  9  yen ¥  )
+(deflayer base + [  ]  {  }  /  ;  `  =  -  '  ,  .  \  yen ¥  )
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn list_action_not_in_list_error_message_is_good() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a)
+(defalias hello
+  one-shot 1 2
+)
+(deflayer base hello)
+"#;
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|e| {
+        assert_eq!(
+            e.msg,
+            "This is a list action and must be in parentheses: (one-shot ...)"
+        );
+    })
+    .unwrap_err();
+}
+
+#[test]
+fn parse_device_paths() {
+    assert_eq!(parse_colon_separated_text(""), [""]);
+    assert_eq!(parse_colon_separated_text("device1"), ["device1"]);
+    assert_eq!(parse_colon_separated_text("h:w"), ["h", "w"]);
+    assert_eq!(parse_colon_separated_text("h\\:w"), ["h:w"]);
+    assert_eq!(parse_colon_separated_text("h\\:w\\"), ["h:w\\"]);
+}
+
+#[test]
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+fn test_parse_dev() {
+    // The old colon separated devices format
+    assert_eq!(
+        parse_dev(&SExpr::Atom(Spanned {
+            t: "\"Keyboard2:Input Device 1:pci-0000\\:00\\:14.0-usb-0\\:1\\:1.0-event\""
+                .to_string(),
+            span: Span::default(),
+        }))
+        .expect("succeeds"),
+        [
+            "Keyboard2",
+            "Input Device 1",
+            "pci-0000:00:14.0-usb-0:1:1.0-event"
+        ]
+    );
+    parse_dev(&SExpr::Atom(Spanned {
+        t: "\"\"".to_string(),
+        span: Span::default(),
+    }))
+    .expect_err("'' is not a valid device name/path, this should fail");
+
+    // The new device list format
+    assert_eq!(
+        parse_dev(&SExpr::List(Spanned {
+            t: vec![
+                SExpr::Atom(Spanned {
+                    t: "Keyboard2".to_string(),
+                    span: Span::default(),
+                }),
+                SExpr::Atom(Spanned {
+                    t: "\"Input Device 1\"".to_string(),
+                    span: Span::default(),
+                }),
+                SExpr::Atom(Spanned {
+                    t: "pci-0000:00:14.0-usb-0:1:1.0-event".to_string(),
+                    span: Span::default(),
+                }),
+                SExpr::Atom(Spanned {
+                    t: r"backslashes\do\not\escape\:\anything".to_string(),
+                    span: Span::default(),
+                }),
+            ],
+            span: Span::default(),
+        }))
+        .expect("succeeds"),
+        [
+            "Keyboard2",
+            "Input Device 1",
+            "pci-0000:00:14.0-usb-0:1:1.0-event",
+            r"backslashes\do\not\escape\:\anything"
+        ]
+    );
+    parse_dev(&SExpr::List(Spanned {
+        t: vec![
+            SExpr::Atom(Spanned {
+                t: "Device1".to_string(),
+                span: Span::default(),
+            }),
+            SExpr::List(Spanned {
+                t: vec![],
+                span: Span::default(),
+            }),
+        ],
+        span: Span::default(),
+    }))
+    .expect_err("nested lists in path list shouldn't be allowed");
+}
+
+#[test]
+fn parse_all_defcfg() {
+    let source = r#"
+(defcfg
+  process-unmapped-keys yes
+  danger-enable-cmd yes
+  sequence-timeout 2000
+  sequence-input-mode visible-backspaced
+  sequence-backtrack-modcancel no
+  log-layer-changes no
+  delegate-to-first-layer yes
+  movemouse-inherit-accel-state yes
+  movemouse-smooth-diagonals yes
+  override-release-on-activation yes
+  dynamic-macro-max-presses 1000
+  concurrent-tap-hold yes
+  rapid-event-delay 5
+  linux-dev /dev/input/dev1:/dev/input/dev2
+  linux-dev-names-include "Name 1:Name 2"
+  linux-dev-names-exclude "Name 3:Name 4"
+  linux-continue-if-no-devs-found yes
+  linux-unicode-u-code v
+  linux-unicode-termination space
+  linux-x11-repeat-delay-rate 400,50
+  linux-use-trackpoint-property yes
+  linux-output-device-name "Kanata Test"
+  linux-output-device-bus-type USB
+  tray-icon symbols.ico
+  icon-match-layer-name no
+  tooltip-layer-changes yes
+  tooltip-show-blank yes
+  tooltip-no-base yes
+  tooltip-duration 300
+  tooltip-size 24,24
+  notify-cfg-reload yes
+  notify-cfg-reload-silent no
+  notify-error yes
+  windows-altgr add-lctl-release
+  windows-interception-mouse-hwid "70, 0, 60, 0"
+  windows-interception-mouse-hwids ("0, 0, 0" "1, 1, 1")
+  windows-interception-keyboard-hwids ("0, 0, 0" "1, 1, 1")
+)
+(defsrc a)
+(deflayer base a)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_defcfg_linux_output_bus() {
+    let source = r#"
+(defcfg linux-output-device-bus-type USB)
+(defsrc a)
+(deflayer base a)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+    let source = r#"
+(defcfg linux-output-device-bus-type I8042)
+(defsrc a)
+(deflayer base a)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+    let source = r#"
+(defcfg linux-output-device-bus-type INVALID)
+(defsrc a)
+(deflayer base a)
+"#;
+    let err = parse_cfg(source).expect_err("should err");
+    assert!(
+        err.msg
+            .contains("Invalid value for linux-output-device-bus-type")
+    );
+}
+
+#[test]
+fn parse_unmod() {
+    let source = r#"
+(defsrc a b c d e)
+(deflayer base
+  (unmod a)
+  (unmod a b)
+  (unshift a)
+  (un⇧ a)
+  (unshift a b)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn using_parentheses_in_deflayer_directly_fails_with_custom_message() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a b)
+(deflayer base ( ))
+"#;
+    let err = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect_err("should err");
+    assert!(
+        err.msg
+            .contains("You can't put parentheses in deflayer directly")
+    );
+}
+
+#[test]
+fn using_escaped_parentheses_in_deflayer_fails_with_custom_message() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    let source = r#"
+(defsrc a b)
+(deflayer base \( \))
+"#;
+    let err = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect_err("should err");
+    assert!(
+        err.msg
+            .contains("Escaping shifted characters with `\\` is currently not supported")
+    );
+}
+
+#[test]
+#[cfg(feature = "cmd")]
+fn parse_cmd() {
+    let source = r#"
+(defcfg danger-enable-cmd yes)
+(defsrc a)
+(deflayer base a)
+(defvar
+    x blah
+    y (nyoom)
+    z (squish squash (splish splosh))
+)
+(defalias
+    1 (cmd hello world)
+    2 (cmd (hello world))
+    3 (cmd $x $y ($z))
+    4 (clipboard-cmd-set powershell.exe -c "echo 'hello world'")
+    5 (clipboard-save-cmd-set 0 bash -c "echo 'goodbye'")
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+#[cfg(feature = "cmd")]
+fn parse_cmd_log() {
+    let source = r#"
+(defcfg danger-enable-cmd yes)
+(defsrc a)
+(deflayer base a)
+(defvar
+    x blah
+    y (nyoom)
+    z (squish squash (splish splosh))
+)
+(defalias
+    1 (cmd-log debug debug hello world)
+    2 (cmd-log error warn (hello world))
+    3 (cmd-log info debug $x $y ($z))
+    4 (cmd-log none none hello world)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_defvar_concat() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let source = r#"
+(defsrc a)
+(deflayer base a)
+(defvar
+    x (concat a b c)
+    y (concat d (e f))
+    z (squish squash (splish splosh))
+    xx (concat $x $y)
+    xy (concat $x ($y))
+    xz (notconcat a b " " c " d")
+    yx (concat a b " " c " d" ("efg" " hij ") "kl")
+    yz (concat "abc"def"ghi""jkl")
+
+    rootpath "/home/myuser/mysubdir"
+    ;; $otherpath will be the string: /home/myuser/mysubdir/helloworld
+    otherpath (concat $rootpath "/helloworld")
+)
+"#;
+    let mut s = ParserState::default();
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .expect("succeeds");
+    match s.vars().unwrap().get("x").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "abc"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("y").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "def"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("z").unwrap() {
+        SExpr::Atom(a) => panic!("expected list not string: {a:?}"),
+        SExpr::List(_) => {}
+    }
+    match s.vars().unwrap().get("xx").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "abcdef"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("xy").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "abcdef"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("xz").unwrap() {
+        SExpr::Atom(a) => panic!("expected list not string {a:?}"),
+        SExpr::List(_) => {}
+    }
+    match s.vars().unwrap().get("yx").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "ab c defg hij kl"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("yz").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "abcdefghijkl"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+    match s.vars().unwrap().get("otherpath").unwrap() {
+        SExpr::Atom(a) => assert_eq!(&a.t, "/home/myuser/mysubdir/helloworld"),
+        SExpr::List(l) => panic!("expected string not list: {l:?}"),
+    }
+}
+
+#[test]
+fn parse_template_1() {
+    let source = r#"
+(deftemplate home-row (j-behaviour)
+  a s d f g h $j-behaviour k l ; '
+)
+
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row j)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+
+(deflayer base
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row (tap-hold 200 200 j lctl))    ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_2() {
+    let source = r#"
+(defvar chord-timeout 200)
+(defcfg process-unmapped-keys yes)
+
+;; This template defines a chord group and aliases that use the chord group.
+;; The purpose is to easily define the same chord position behaviour
+;; for multiple layers that have different underlying keys.
+(deftemplate left-hand-chords (chordgroupname k1 k2 k3 k4 alias1 alias2 alias3 alias4)
+  (defalias
+    $alias1 (chord $chordgroupname $k1)
+    $alias2 (chord $chordgroupname $k2)
+    $alias3 (chord $chordgroupname $k3)
+    $alias4 (chord $chordgroupname $k4)
+  )
+  (defchords $chordgroupname $chord-timeout
+    ($k1) $k1
+    ($k2) $k2
+    ($k3) $k3
+    ($k4) $k4
+    ($k1 $k2) lctl
+    ($k3 $k4) lsft
+  )
+)
+
+(template-expand left-hand-chords qwerty a s d f qwa qws qwd qwf)
+(template-expand left-hand-chords dvorak a o e u dva dvo dve dvu)
+
+(defsrc a s d f)
+(deflayer dvorak @dva @dvo @dve @dvu)
+(deflayer qwerty @qwa @qws @qwd @qwf)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_3() {
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-equal $version v1 j)
+  (if-equal $version v2 (tap-hold 200 200 j (if-equal $version v2 k)))
+   k l ; '
+)
+
+(defsrc
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row v1)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+
+(deflayer base
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps (template-expand home-row v2)                            ret
+  lsft z    x    c    v    b    n    m    ,    .    /    rsft
+  lctl lmet lalt           spc            ralt rmet rctl
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_4() {
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-not-equal $version v2 j)
+  (if-not-equal $version v1 (tap-hold 200 200 j (if-not-equal $version v1 k)))
+   k l ; '
+)
+
+(defsrc
+  (template-expand home-row v1)
+)
+
+(deflayer base
+  (template-expand home-row v2)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_5() {
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-in-list $version (v0 v3 v1 v4) j)
+  (if-in-list $version (v0 v2 v3 v4) (tap-hold 200 200 j (if-in-list $version (v0 v3 v4 v2) k)))
+   k l ; '
+)
+
+(defsrc
+  (template-expand home-row v1)
+)
+
+(deflayer base
+  (template-expand home-row v2)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_6() {
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-not-in-list $version (v2 v3 v4) j)
+  (if-not-in-list $version (v1 v3 v4) (tap-hold 200 200 j (if-not-in-list $version (v1 v3 v4) k)))
+   k l ; '
+)
+
+(defsrc
+  (template-expand home-row v1)
+)
+
+(deflayer base
+  (template-expand home-row v2)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_7() {
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-in-list $version (v0 v3 (concat v (((1)))) v4) (concat j))
+  (if-in-list $version ((concat v 0) (concat v (2)) v3 v4) (tap-hold 200 200 (concat j) (if-in-list $version (v0 v3 v4 v2) (concat "k"))))
+   k l ; '
+)
+
+(defsrc
+  (template-expand home-row v1)
+)
+
+(deflayer base
+  (template-expand home-row v2)
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_template_8() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+
+    let source = r#"
+(deftemplate home-row (version)
+  a s d f g h
+  (if-in-list $version (v0 v3 (concat v (((1)))) v4) (concat j))
+  (if-in-list $version ((concat v 0) (concat v (2)) v3 v4) (tap-hold 200 200 (concat j) (if-in-list $version (v0 v3 v4 v2) (concat "k"))))
+   k l ; '
+)
+(deftemplate var () (defvar num 200))
+(defsrc
+  (t! home-row v1)
+)
+(deflayer base
+  (t! home-row v2)
+)
+(t! var)
+(defalias a (tap-dance $num (a)))
+"#;
+    let mut s = ParserState::default();
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err("env vars not implemented".into()),
+    )
+    .map_err(|e| {
+        eprintln!("{:?}", miette::Error::from(e));
+    })
+    .expect("parses");
+}
+
+#[test]
+fn test_deflayermap() {
+    let source = r#"
+(defsrc a b l)
+(deflayermap (blah)
+  d   (macro a b c)
+  e   e
+  f   0
+  j   1
+  k   2
+  l   3
+  m   4
+  =   a
+  a   =
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn test_defaliasenvcond() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let source = r#"
+(defsrc spc)
+(deflayer base _)
+(defaliasenvcond (ENV_TEST 1) a b)
+"#;
+
+    let env_var_err = "env vars not implemented";
+    let mut s = ParserState::default();
+    let parse_err = parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Err(env_var_err.into()),
+    )
+    .expect_err("should err");
+    assert_eq!(parse_err.msg, env_var_err);
+
+    // now test with env vars implemented
+
+    let mut s = ParserState::default();
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Ok(vec![("ENV_TEST".into(), "1".into())]),
+    )
+    .map_err(|e| {
+        eprintln!("{:?}", miette::Error::from(e));
+        ""
+    })
+    .expect("parses");
+    assert!(s.aliases["a"].key_codes().eq(vec![KeyCode::B]));
+
+    // test env var set but to a different value
+
+    let mut s = ParserState::default();
+    parse_cfg_raw_string(
+        source,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Ok(vec![("ENV_TEST".into(), "asdf".into())]),
+    )
+    .map_err(|e| {
+        eprintln!("{:?}", miette::Error::from(e));
+        ""
+    })
+    .expect("parses");
+    assert!(!s.aliases.contains_key("a"));
+}
+
+#[test]
+fn parse_platform_specific() {
+    let source = r#"
+(platform () (invalid config but is not used anywhere))
+(defsrc)
+(deflayermap (base)
+  a (layer-switch 2)
+)
+;; layer 2 must exist on all platforms, all in one list
+(platform (win winiov2 wintercept linux macos)
+  (deflayermap (2)
+    a (layer-switch 3)
+  )
+)
+;; layer 3 must exist on all platforms, in individual lists
+;; Tests for no duplication.
+(platform (win)
+  (deflayermap (3)
+    a (layer-switch 3)
+  )
+)
+(platform (winiov2)
+  (deflayermap (3)
+    a (layer-switch 3)
+  )
+)
+(platform (wintercept)
+  (deflayermap (3)
+    a (layer-switch 3)
+  )
+)
+(platform (linux)
+  (deflayermap (3)
+    a (layer-switch 3)
+  )
+)
+(platform (macos)
+  (deflayermap (3)
+    a (layer-switch 3)
+  )
+)
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_defseq_overlap_limits() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+(defvirtualkeys v v)
+(defseq v (O-(a b c d e f)))
+(defseq v (O-(a b)))
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_defseq_overlap_too_many() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+(defvirtualkeys v v)
+(defseq v (O-(a b c d e f g)))
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect_err("fails");
+}
+
+#[test]
+fn parse_layer_opts_icon() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from("./test_cfgs/icon_good.kbd")).unwrap();
+}
+
+#[test]
+fn disallow_dupe_layer_opts_icon_layernonmap() {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    new_from_file(&std::path::PathBuf::from("./test_cfgs/icon_bad_dupe.kbd"))
+        .map(|_| ())
+        .expect_err("fails");
+}
+
+#[test]
+fn disallow_dupe_layer_opts_icon_layermap() {
+    let source = "
+(defcfg)
+(defsrc)
+(deflayermap (base icon base.png 🖻 n.ico) 0 0)
+";
+    parse_cfg(source).map(|_| ()).expect_err("fails");
+}
+
+#[test]
+fn layer_name_allows_var() {
+    let source = "
+(defvar l1name base)
+(defvar l2name l2)
+(defvar l3name (concat $l1name $l2name))
+(defvar l4name (concat $l3name actually-4))
+(defsrc a)
+(deflayer $l1name (layer-while-held $l2name))
+(deflayermap ($l2name)
+  a (layer-while-held $l3name))
+(deflayer ($l3name) (layer-while-held $l4name))
+(deflayer ($l4name icon icon.ico) (layer-while-held $l1name))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parse succeeds");
+}
+
+#[test]
+fn disallow_whitespace_in_tooltip_size() {
+    let source = "
+(defcfg
+  tooltip-size 24 24	;; should be 24,24
+)
+(defsrc 1)
+(deflayer test 1)
+";
+    parse_cfg(source).map(|_| ()).expect_err("fails");
+}
+
+#[test]
+fn reverse_release_order_must_be_within_multi() {
+    let source = "
+(defsrc a)
+(deflayer base reverse-release-order)
+";
+    let e = parse_cfg(source).map(|_| ()).expect_err("fails");
+    assert_eq!(
+        e.msg,
+        "reverse-release-order is only allowed inside of a (multi ...) action list"
+    );
+}
+
+#[test]
+fn parse_clipboard_actions() {
+    let source = "
+(defsrc)
+(deflayermap (base)
+ a (clipboard-set       clip)
+ b (clipboard-save      0)
+ c (clipboard-restore   0)
+ d (clipboard-save-swap 0 65535)
+)
+";
+    parse_cfg(source).map(|_| ()).expect("success");
+}
+
+/// `mouse-movement-key` parses on every platform that supports the feature
+/// (Linux, Android, macOS, Windows-interception, unknown). Regression guard
+/// for the macOS cfg gate previously omitting `target_os = "macos"`, which
+/// caused the option to fail with "Unknown defcfg option" on macOS.
+#[cfg(any(
+    all(target_os = "windows", feature = "interception_driver"),
+    target_os = "linux",
+    target_os = "android",
+    target_os = "macos",
+    target_os = "unknown"
+))]
+#[test]
+fn parse_mouse_movement_key() {
+    let source = "
+(defcfg
+  process-unmapped-keys yes
+  mouse-movement-key mvmt
+)
+(defsrc a mvmt)
+(deflayer base a _)
+";
+    let icfg = parse_cfg(source).expect("parses");
+    assert_eq!(
+        icfg.options.mouse_movement_key,
+        Some(crate::keys::OsCode::KEY_766),
+    );
+}
diff --git a/parser/src/cfg/tests/ambiguous.rs b/parser/src/cfg/tests/ambiguous.rs
new file mode 100644
index 000000000..330ab84f5
--- /dev/null
+++ b/parser/src/cfg/tests/ambiguous.rs
@@ -0,0 +1,32 @@
+use super::*;
+
+#[test]
+fn parse_double_dollar_var() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+(defvar $$num 100
+         $num 99
+          num not-a-number-or-key)
+(defalias test
+         (movemouse-accel-up $$num $$$num $$num $$$num))
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
+
+#[test]
+fn parse_double_at_alias() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+          ;; alias cannot be used in macro, @alias can
+(defalias @alias 0
+           alias (tap-hold 9 9 a b)
+           test (macro @@alias))
+"#;
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("parses");
+}
diff --git a/parser/src/cfg/tests/defcfg.rs b/parser/src/cfg/tests/defcfg.rs
new file mode 100644
index 000000000..8384ca62f
--- /dev/null
+++ b/parser/src/cfg/tests/defcfg.rs
@@ -0,0 +1,313 @@
+use super::*;
+
+#[test]
+fn disallow_same_key_in_defsrc_unmapped_except() {
+    let source = "
+(defcfg process-unmapped-keys (all-except bspc))
+(defsrc bspc)
+(deflayermap (name) 0 0)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        //.map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect_err("fails");
+}
+
+#[test]
+fn unmapped_except_keys_cannot_have_dupes() {
+    let source = "
+(defcfg process-unmapped-keys (all-except bspc bspc))
+(defsrc)
+(deflayermap (name) 0 0)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        //.map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect_err("fails");
+}
+
+#[test]
+fn unmapped_except_keys_must_be_known() {
+    let source = "
+(defcfg process-unmapped-keys (all-except notakey))
+(defsrc)
+(deflayermap (name) 0 0)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        //.map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect_err("fails");
+}
+
+#[test]
+fn unmapped_except_keys_respects_deflocalkeys() {
+    let source = "
+(deflocalkeys-win         lkey90 555)
+(deflocalkeys-winiov2     lkey90 555)
+(deflocalkeys-wintercept  lkey90 555)
+(deflocalkeys-linux       lkey90 555)
+(deflocalkeys-macos       lkey90 555)
+(defcfg process-unmapped-keys (all-except lkey90))
+(defsrc)
+(deflayermap (name) 0 0)
+";
+    let cfg = parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+    assert!(!cfg.mapped_keys.contains(&OsCode::from(555u16)));
+    assert!(cfg.mapped_keys.contains(&OsCode::KEY_ENTER));
+    for osc in 0..KEYS_IN_ROW as u16 {
+        if let Some(osc) = OsCode::from_u16(osc) {
+            match KeyCode::from(osc) {
+                KeyCode::No | KeyCode::K555 => {
+                    assert!(!cfg.mapped_keys.contains(&osc));
+                }
+                _ if osc.is_mouse_code() => {
+                    assert!(!cfg.mapped_keys.contains(&osc));
+                }
+                _ => {
+                    assert!(cfg.mapped_keys.contains(&osc));
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn unmapped_except_keys_is_removed_from_mapping() {
+    let source = "
+(defcfg process-unmapped-keys (all-except 1 2 3))
+(defsrc mlft mmid)
+(deflayermap (name) 0 0)
+";
+    let cfg = parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+    assert!(cfg.mapped_keys.contains(&OsCode::KEY_A));
+    assert!(cfg.mapped_keys.contains(&OsCode::KEY_0));
+    assert!(!cfg.mapped_keys.contains(&OsCode::KEY_1));
+    assert!(!cfg.mapped_keys.contains(&OsCode::KEY_2));
+    assert!(!cfg.mapped_keys.contains(&OsCode::KEY_3));
+    assert!(cfg.mapped_keys.contains(&OsCode::KEY_4));
+    for osc in 0..KEYS_IN_ROW as u16 {
+        if let Some(osc) = OsCode::from_u16(osc) {
+            match KeyCode::from(osc) {
+                KeyCode::No | KeyCode::Kb1 | KeyCode::Kb2 | KeyCode::Kb3 => {
+                    assert!(!cfg.mapped_keys.contains(&osc));
+                }
+                // mlft, mmid
+                KeyCode::K272 | KeyCode::K274 => {
+                    assert!(cfg.mapped_keys.contains(&osc));
+                }
+                _ if osc.is_mouse_code() => {
+                    assert!(!cfg.mapped_keys.contains(&osc));
+                }
+                _ => {
+                    assert!(cfg.mapped_keys.contains(&osc));
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn non_applicable_os_deflocalkeys_always_succeeds_parsing() {
+    let source = "
+(deflocalkeys-linux å 26 ' 43)
+(defsrc)
+(deflayer base)
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn tap_hold_require_prior_idle_parses_valid_value() {
+    let source = "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a)
+(deflayer base a)
+";
+    let cfg = parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+    assert_eq!(cfg.options.tap_hold_require_prior_idle, 150);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_allows_zero() {
+    let source = "
+(defcfg tap-hold-require-prior-idle 0)
+(defsrc a)
+(deflayer base a)
+";
+    let cfg = parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+    assert_eq!(cfg.options.tap_hold_require_prior_idle, 0);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_rejects_non_numeric() {
+    let source = "
+(defcfg tap-hold-require-prior-idle nope)
+(defsrc a)
+(deflayer base a)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        //.map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect_err("fails");
+}
+
+#[test]
+fn per_action_require_prior_idle_parses() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold 200 200 a lctl (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_zero_parses() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold 200 200 a lctl (require-prior-idle 0)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_rejects_non_numeric() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold 200 200 a lctl (require-prior-idle nope)))
+";
+    parse_cfg(source).map(|_| ()).expect_err("fails");
+}
+
+#[test]
+fn per_action_require_prior_idle_rejects_unknown_option() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold 200 200 a lctl (unknown-option 100)))
+";
+    parse_cfg(source).map(|_| ()).expect_err("fails");
+}
+
+#[test]
+fn per_action_require_prior_idle_rejects_duplicate() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold 200 200 a lctl (require-prior-idle 100) (require-prior-idle 50)))
+";
+    parse_cfg(source).map(|_| ()).expect_err("fails");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_press() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold-press 200 200 a lctl (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_release() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold-release 200 200 a lctl (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_release_timeout() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold-release-timeout 200 200 a lctl lalt (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_press_timeout() {
+    let source = "
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold-press-timeout 200 200 a lctl lalt (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_release_keys() {
+    let source = "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-release-keys 200 200 a lctl (b) (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_except_keys() {
+    let source = "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-except-keys 200 200 a lctl (b) (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_opposite_hand() {
+    let source = "
+(defhands (left a s d f g) (right h j k l ;))
+(defsrc a)
+(deflayer base @a)
+(defalias a (tap-hold-opposite-hand 200 a lctl (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
+
+#[test]
+fn per_action_require_prior_idle_on_tap_hold_release_tap_keys_release() {
+    let source = "
+(defsrc a b c)
+(deflayer base @a b c)
+(defalias a (tap-hold-release-tap-keys-release 200 200 a lctl (b) (c) (require-prior-idle 100)))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("passes");
+}
diff --git a/parser/src/cfg/tests/defhands.rs b/parser/src/cfg/tests/defhands.rs
new file mode 100644
index 000000000..c4ded88b8
--- /dev/null
+++ b/parser/src/cfg/tests/defhands.rs
@@ -0,0 +1,157 @@
+use super::*;
+
+#[test]
+fn opposite_hand_no_args() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("tap-hold-opposite-hand with zero args should fail");
+}
+
+#[test]
+fn opposite_hand_one_arg() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("tap-hold-opposite-hand with one arg should fail");
+}
+
+#[test]
+fn opposite_hand_two_args() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("tap-hold-opposite-hand with two args should fail");
+}
+
+#[test]
+fn defhands_missing_for_opposite_hand() {
+    let source = "
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("tap-hold-opposite-hand without defhands should fail");
+}
+
+#[test]
+fn defhands_duplicate_blocks() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defhands (left q w e r))
+(defsrc a)
+(deflayer base a)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("duplicate defhands blocks should fail");
+}
+
+#[test]
+fn defhands_key_in_both_groups() {
+    let source = "
+(defhands (left a s d f) (right a j k l))
+(defsrc a)
+(deflayer base a)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("same key in both left and right should fail");
+}
+
+#[test]
+fn defhands_duplicate_group_name() {
+    let source = "
+(defhands (left a s d f) (left q w e r))
+(defsrc a)
+(deflayer base a)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("duplicate left group in defhands should fail");
+}
+
+#[test]
+fn defhands_invalid_group_name() {
+    let source = "
+(defhands (center a s d f))
+(defsrc a)
+(deflayer base a)
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("invalid group name 'center' should fail");
+}
+
+#[test]
+fn opposite_hand_unknown_option() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl (foo bar)))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("unknown option foo should fail");
+}
+
+#[test]
+fn opposite_hand_trailing_keyword() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl (timeout)))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("option list without value should fail");
+}
+
+#[test]
+fn opposite_hand_invalid_behavior() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl (same-hand maybe)))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("invalid behavior 'maybe' should fail");
+}
+
+#[test]
+fn opposite_hand_duplicate_option() {
+    let source = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl (timeout tap) (timeout hold)))
+";
+    parse_cfg(source)
+        .map(|_| ())
+        .expect_err("duplicate option timeout should fail");
+}
+
+#[test]
+fn defhands_valid_partial() {
+    let source = "
+(defhands (left a s d f))
+(defsrc a)
+(deflayer base (tap-hold-opposite-hand 180 a lctl))
+";
+    parse_cfg(source)
+        .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+        .expect("partial defhands with only left should succeed");
+}
diff --git a/parser/src/cfg/tests/device_detect.rs b/parser/src/cfg/tests/device_detect.rs
new file mode 100644
index 000000000..49ebbb0e2
--- /dev/null
+++ b/parser/src/cfg/tests/device_detect.rs
@@ -0,0 +1,66 @@
+#[cfg(any(target_os = "linux", target_os = "android"))]
+mod linux {
+    use super::super::*;
+
+    #[test]
+    fn linux_device_parses_properly() {
+        let source = r#"
+(defcfg linux-device-detect-mode any)
+(defsrc) (deflayer base)"#;
+        let icfg = parse_cfg(source)
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect("no error");
+        assert_eq!(
+            icfg.options.linux_opts.linux_device_detect_mode,
+            Some(DeviceDetectMode::Any)
+        );
+
+        let source = r#"
+(defcfg linux-device-detect-mode keyboard-only)
+(defsrc) (deflayer base)"#;
+        let icfg = parse_cfg(source)
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect("no error");
+        assert_eq!(
+            icfg.options.linux_opts.linux_device_detect_mode,
+            Some(DeviceDetectMode::KeyboardOnly)
+        );
+
+        let source = r#"
+(defcfg linux-device-detect-mode keyboard-mice)
+(defsrc) (deflayer base)"#;
+        let icfg = parse_cfg(source)
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect("no error");
+        assert_eq!(
+            icfg.options.linux_opts.linux_device_detect_mode,
+            Some(DeviceDetectMode::KeyboardMice)
+        );
+
+        let source = r#"(defsrc mmid) (deflayer base 1)"#;
+        let icfg = parse_cfg(source)
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect("no error");
+        assert_eq!(
+            icfg.options.linux_opts.linux_device_detect_mode,
+            Some(DeviceDetectMode::Any)
+        );
+
+        let source = r#"(defsrc a) (deflayer base b)"#;
+        let icfg = parse_cfg(source)
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect("no error");
+        assert_eq!(
+            icfg.options.linux_opts.linux_device_detect_mode,
+            Some(DeviceDetectMode::KeyboardMice)
+        );
+
+        let source = r#"
+(defcfg linux-device-detect-mode not an opt)
+(defsrc) (deflayer base)"#;
+        parse_cfg(source)
+            .map(|_| ())
+            .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+            .expect_err("error should happen");
+    }
+}
diff --git a/parser/src/cfg/tests/environment.rs b/parser/src/cfg/tests/environment.rs
new file mode 100644
index 000000000..7a3f28f00
--- /dev/null
+++ b/parser/src/cfg/tests/environment.rs
@@ -0,0 +1,37 @@
+use super::*;
+
+fn parse_cfg_env(cfg: &str, env_vars: Vec<(String, String)>) -> Result<IntermediateCfg> {
+    let _lk = lock(&CFG_PARSE_LOCK);
+    let mut s = ParserState::default();
+    parse_cfg_raw_string(
+        cfg,
+        &mut s,
+        &PathBuf::from("test"),
+        &mut FileContentProvider {
+            get_file_content_fn: &mut |_| unimplemented!(),
+        },
+        DEF_LOCAL_KEYS,
+        Ok(env_vars),
+    )
+}
+
+#[test]
+fn parse_env() {
+    parse_cfg_env(
+        r#"
+        (environment (hello "") (defsrc a))
+        (environment (goodbye "") (deflayer 1 (layer-switch 2)))
+        (environment (farewell val) (deflayer 2 (layer-switch 1)))
+        ;; below would conflict if environment did not cancel
+        (environment (hello yea) (defsrc))
+        (environment (goodbye yea) (deflayer 1))
+        (environment (farewell notval) (deflayer 2))
+        "#,
+        vec![
+            ("goodbye".into(), "".into()),
+            ("farewell".into(), "val".into()),
+        ],
+    )
+    .map_err(|e| eprintln!("{:?}", miette::Error::from(e)))
+    .unwrap();
+}
diff --git a/parser/src/cfg/tests/macros.rs b/parser/src/cfg/tests/macros.rs
new file mode 100644
index 000000000..ceec02939
--- /dev/null
+++ b/parser/src/cfg/tests/macros.rs
@@ -0,0 +1,30 @@
+use super::*;
+
+#[test]
+fn unsupported_action_in_macro_triggers_error() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+(defalias a (macro (multi a b c))) "#;
+    parse_cfg(source)
+        .map(|_| ())
+        .map_err(|e| log::info!("{:?}", miette::Error::from(e)))
+        .expect_err("errors");
+}
+
+#[test]
+fn incorrectly_configured_supported_action_in_macro_triggers_useful_error() {
+    let source = r#"
+(defsrc)
+(deflayer base)
+(defalias a (macro (on-press press-vkey does-not-exist))) "#;
+    parse_cfg(source)
+        .map(|_| ())
+        .map_err(|e| {
+            let e = miette::Error::from(e);
+            let msg = format!("{e:?}");
+            log::info!("{msg}");
+            assert!(msg.contains("unknown virtual key name: does-not-exist"));
+        })
+        .expect_err("errors");
+}
diff --git a/parser/src/cfg/unicode.rs b/parser/src/cfg/unicode.rs
new file mode 100644
index 000000000..ec77f0c71
--- /dev/null
+++ b/parser/src/cfg/unicode.rs
@@ -0,0 +1,36 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+pub(crate) fn parse_unicode(ac_params: &[SExpr], s: &ParserState) -> Result<&'static KanataAction> {
+    const ERR_STR: &str = "unicode expects exactly one (not combos looking like one) unicode character as an argument\nor a unicode hex number, prefixed by U+. Example: U+1F686.";
+    if ac_params.len() != 1 {
+        bail!(ERR_STR)
+    }
+    ac_params[0]
+        .atom(s.vars())
+        .map(|a| {
+            let a = a.trim_atom_quotes();
+            let unicode_char = match a.chars().count() {
+                0 => bail_expr!(&ac_params[0], "{ERR_STR}"),
+                1 => a.chars().next().expect("1 char"),
+                _ => {
+                    let normalized = a.to_uppercase();
+                    let Some(hexnum) = normalized.strip_prefix("U+") else {
+                        bail_expr!(&ac_params[0], "{ERR_STR}.\nMust begin with U+")
+                    };
+                    let Ok(u_val) = u32::from_str_radix(hexnum, 16) else {
+                        bail_expr!(&ac_params[0], "{ERR_STR}.\nInvalid number after U+")
+                    };
+                    match char::from_u32(u_val) {
+                        Some(v) => v,
+                        None => bail_expr!(&ac_params[0], "{ERR_STR}.\nInvalid char."),
+                    }
+                }
+            };
+            custom(CustomAction::Unicode(unicode_char), &s.a)
+        })
+        .ok_or_else(|| anyhow_expr!(&ac_params[0], "{ERR_STR}"))?
+}
diff --git a/parser/src/cfg/unmod.rs b/parser/src/cfg/unmod.rs
new file mode 100644
index 000000000..9218fe18d
--- /dev/null
+++ b/parser/src/cfg/unmod.rs
@@ -0,0 +1,88 @@
+use super::*;
+
+use crate::anyhow_expr;
+use crate::bail;
+use crate::bail_expr;
+
+pub(crate) fn parse_unmod(
+    unmod_type: &str,
+    ac_params: &[SExpr],
+    s: &ParserState,
+) -> Result<&'static KanataAction> {
+    const ERR_MSG: &str = "expects expects at least one key name";
+    if ac_params.is_empty() {
+        bail!("{unmod_type} {ERR_MSG}\nfound {} items", ac_params.len());
+    }
+
+    let mut mods = UnmodMods::all();
+    let mut params = ac_params;
+    // Parse the optional first-list that specifies the mod keys to use.
+    if let Some(mod_list) = ac_params[0].list(s.vars()) {
+        if unmod_type != UNMOD {
+            bail_expr!(
+                &ac_params[0],
+                "{unmod_type} only expects key names but found a list"
+            );
+        }
+        mods = mod_list
+            .iter()
+            .try_fold(UnmodMods::empty(), |mod_flags, mod_key| {
+                let flag = mod_key
+                    .atom(s.vars())
+                    .and_then(str_to_oscode)
+                    .and_then(|osc| match osc {
+                        OsCode::KEY_LEFTSHIFT => Some(UnmodMods::LSft),
+                        OsCode::KEY_RIGHTSHIFT => Some(UnmodMods::RSft),
+                        OsCode::KEY_LEFTCTRL => Some(UnmodMods::LCtl),
+                        OsCode::KEY_RIGHTCTRL => Some(UnmodMods::RCtl),
+                        OsCode::KEY_LEFTMETA => Some(UnmodMods::LMet),
+                        OsCode::KEY_RIGHTMETA => Some(UnmodMods::RMet),
+                        OsCode::KEY_LEFTALT => Some(UnmodMods::LAlt),
+                        OsCode::KEY_RIGHTALT => Some(UnmodMods::RAlt),
+                        _ => None,
+                    })
+                    .ok_or_else(|| {
+                        anyhow_expr!(
+                            mod_key,
+                            "{UNMOD} expects modifier key names within the modifier list."
+                        )
+                    })?;
+                if !(mod_flags & flag).is_empty() {
+                    bail_expr!(
+                        mod_key,
+                        "Duplicate key name in modifier key list is not allowed."
+                    );
+                }
+                Ok::<_, ParseError>(mod_flags | flag)
+            })?;
+        if mods.is_empty() {
+            bail_expr!(&ac_params[0], "an empty modifier key list is invalid");
+        }
+        if ac_params[1..].is_empty() {
+            bail!("at least one key is required after the modifier key list");
+        }
+        params = &ac_params[1..];
+    }
+
+    let keys: Vec<KeyCode> = params.iter().try_fold(Vec::new(), |mut keys, param| {
+        keys.push(
+            param
+                .atom(s.vars())
+                .and_then(str_to_oscode)
+                .ok_or_else(|| {
+                    anyhow_expr!(
+                        &ac_params[0],
+                        "{unmod_type} {ERR_MSG}\nfound invalid key name"
+                    )
+                })?
+                .into(),
+        );
+        Ok::<_, ParseError>(keys)
+    })?;
+    let keys = s.a.sref_vec(keys);
+    match unmod_type {
+        UNMOD => custom(CustomAction::Unmodded { keys, mods }, &s.a),
+        UNSHIFT => custom(CustomAction::Unshifted { keys }, &s.a),
+        _ => panic!("Unknown unmod type {unmod_type}"),
+    }
+}
diff --git a/parser/src/cfg/vars.rs b/parser/src/cfg/vars.rs
new file mode 100644
index 000000000..1194db099
--- /dev/null
+++ b/parser/src/cfg/vars.rs
@@ -0,0 +1,65 @@
+use super::*;
+
+use crate::bail_expr;
+
+pub(crate) fn parse_vars(
+    exprs: &[&Vec<SExpr>],
+    _lsp_hints: &mut LspHints,
+) -> Result<HashMap<String, SExpr>> {
+    let mut vars: HashMap<String, SExpr> = Default::default();
+    for expr in exprs {
+        let mut subexprs = check_first_expr(expr.iter(), "defvar")?;
+        // Read k-v pairs from the configuration
+        while let Some(var_name_expr) = subexprs.next() {
+            let var_name = match var_name_expr {
+                SExpr::Atom(a) => &a.t,
+                _ => bail_expr!(var_name_expr, "variable name must not be a list"),
+            };
+            let var_expr = match subexprs.next() {
+                Some(v) => match v {
+                    SExpr::Atom(_) => v.clone(),
+                    SExpr::List(l) => parse_list_var(l, &vars),
+                },
+                None => bail_expr!(var_name_expr, "variable name must have a subsequent value"),
+            };
+            #[cfg(feature = "lsp")]
+            _lsp_hints
+                .definition_locations
+                .variable
+                .insert(var_name.to_owned(), var_name_expr.span());
+            if vars.insert(var_name.into(), var_expr).is_some() {
+                bail_expr!(var_name_expr, "duplicate variable name: {}", var_name);
+            }
+        }
+    }
+    Ok(vars)
+}
+
+pub(crate) fn parse_list_var(expr: &Spanned<Vec<SExpr>>, vars: &HashMap<String, SExpr>) -> SExpr {
+    let ret = match expr.t.first() {
+        Some(SExpr::Atom(a)) => match a.t.as_str() {
+            "concat" => {
+                let mut concat_str = String::new();
+                let visitees = &expr.t[1..];
+                push_all_atoms(visitees, vars, &mut concat_str);
+                SExpr::Atom(Spanned {
+                    span: expr.span.clone(),
+                    t: concat_str,
+                })
+            }
+            _ => SExpr::List(expr.clone()),
+        },
+        _ => SExpr::List(expr.clone()),
+    };
+    ret
+}
+
+pub(crate) fn push_all_atoms(exprs: &[SExpr], vars: &HashMap<String, SExpr>, pusheen: &mut String) {
+    for expr in exprs {
+        if let Some(a) = expr.atom(Some(vars)) {
+            pusheen.push_str(a.trim_atom_quotes());
+        } else if let Some(l) = expr.list(Some(vars)) {
+            push_all_atoms(l, vars, pusheen);
+        }
+    }
+}
diff --git a/parser/src/cfg/zippychord.rs b/parser/src/cfg/zippychord.rs
new file mode 100644
index 000000000..a1e081dab
--- /dev/null
+++ b/parser/src/cfg/zippychord.rs
@@ -0,0 +1,782 @@
+//! Zipchord-like parsing. Probably not 100% compatible.
+//!
+//! Example lines in input file.
+//! The " => " string represents a tab character.
+//!
+//! "dy => day"
+//!   -> chord: (d y)
+//!   -> output: "day"
+//!
+//! "dy => day"
+//! "dy 1 => Monday"
+//!   -> chord: (d y)
+//!   -> output: "day"
+//!   -> chord: (d y)
+//!   -> output: "Monday"; "day" gets erased
+//!
+//! " abc => Alphabet"
+//!   -> chord: (space a b c)
+//!   -> output: "Alphabet"
+//!
+//! "r df => recipient"
+//!   -> chord: (r)
+//!   -> output: nothing yet, just type r
+//!   -> chord: (d f)
+//!   -> output: "recipient"
+//!
+//! " w  a => Washington"
+//!   -> chord: (space w)
+//!   -> output: nothing yet, type spacebar+w in whatever true order they were pressed
+//!   -> chord: (space a)
+//!   -> output: "Washington"
+//!   -> note: do observe the two spaces between 'w' and 'a'
+use super::*;
+use crate::bail_expr;
+
+#[cfg(not(feature = "zippychord"))]
+#[derive(Debug, Clone, Default)]
+pub struct ZchPossibleChords();
+#[cfg(not(feature = "zippychord"))]
+#[derive(Debug, Clone, Default)]
+pub struct ZchConfig();
+#[cfg(not(feature = "zippychord"))]
+fn parse_zippy_inner(
+    exprs: &[SExpr],
+    _s: &ParserState,
+    _f: &mut FileContentProvider,
+) -> Result<(ZchPossibleChords, ZchConfig)> {
+    bail_expr!(
+        &exprs[0],
+        "Kanata was not compiled with the \"zippychord\" feature. This configuration is unsupported"
+    )
+}
+
+pub(crate) fn parse_zippy(
+    exprs: &[SExpr],
+    s: &ParserState,
+    f: &mut FileContentProvider,
+) -> Result<(ZchPossibleChords, ZchConfig)> {
+    parse_zippy_inner(exprs, s, f)
+}
+
+#[cfg(feature = "zippychord")]
+pub use inner::*;
+#[cfg(feature = "zippychord")]
+mod inner {
+    use super::*;
+
+    use crate::anyhow_expr;
+    use crate::subset::*;
+
+    use parking_lot::Mutex;
+
+    /// All possible chords.
+    #[derive(Debug, Clone, Default)]
+    pub struct ZchPossibleChords(pub SubsetMap<u16, Arc<ZchChordOutput>>);
+    impl ZchPossibleChords {
+        pub fn is_empty(&self) -> bool {
+            self.0.is_empty()
+        }
+    }
+
+    /// Tracks current input to check against possible chords.
+    /// This does not store by the input order;
+    /// instead it is by some consistent ordering for
+    /// hashing into the possible chord map.
+    #[derive(Debug, Clone, Default, PartialEq, Eq)]
+    pub struct ZchInputKeys {
+        zch_inputs: ZchSortedChord,
+    }
+    impl ZchInputKeys {
+        pub fn zchik_new() -> Self {
+            Self {
+                zch_inputs: ZchSortedChord {
+                    zch_keys: Vec::new(),
+                },
+            }
+        }
+        pub fn zchik_contains(&self, osc: OsCode) -> bool {
+            self.zch_inputs.zch_keys.contains(&osc.into())
+        }
+        pub fn zchik_insert(&mut self, osc: OsCode) {
+            self.zch_inputs.zch_insert(osc.into());
+        }
+        pub fn zchik_remove(&mut self, osc: OsCode) {
+            self.zch_inputs.zch_keys.retain(|k| *k != osc.into());
+        }
+        pub fn zchik_len(&self) -> usize {
+            self.zch_inputs.zch_keys.len()
+        }
+        pub fn zchik_clear(&mut self) {
+            self.zch_inputs.zch_keys.clear()
+        }
+        pub fn zchik_keys(&self) -> &[u16] {
+            &self.zch_inputs.zch_keys
+        }
+        pub fn zchik_is_empty(&self) -> bool {
+            self.zch_inputs.zch_keys.is_empty()
+        }
+    }
+
+    #[derive(Debug, Default, Clone, Hash, PartialEq, Eq)]
+    /// Sorted consistently by some arbitrary key order;
+    /// as opposed to, for example, simply the user press order.
+    pub struct ZchSortedChord {
+        zch_keys: Vec<u16>,
+    }
+    impl ZchSortedChord {
+        pub fn zch_insert(&mut self, key: u16) {
+            match self.zch_keys.binary_search(&key) {
+                // Q: what is the meaning of Ok vs. Err?
+                // A: Ok means the element already in vector @ `pos`. Normally this wouldn't be
+                // expected to happen but it turns out that key repeat might get in the way of this
+                // assumption. Err means element does not exist and returns the correct insert position.
+                Ok(_pos) => {}
+                Err(pos) => self.zch_keys.insert(pos, key),
+            }
+        }
+    }
+
+    /// A chord.
+    ///
+    /// If any followups exist it will be Some.
+    /// E.g. with:
+    /// - dy   -> day
+    /// - dy 1 -> Monday
+    /// - dy 2 -> Tuesday
+    ///
+    /// the output will be "day" and the Monday+Tuesday chords will be in `followups`.
+    #[derive(Debug, Clone)]
+    pub struct ZchChordOutput {
+        pub zch_output: Box<[ZchOutput]>,
+        pub zch_followups: Option<Arc<Mutex<ZchPossibleChords>>>,
+    }
+
+    /// Zch output can be uppercase, lowercase, altgr, and shift-altgr characters.
+    /// The parser should ensure all `OsCode`s in variants containing them
+    /// are visible characters that are backspacable.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+    pub enum ZchOutput {
+        Lowercase(OsCode),
+        Uppercase(OsCode),
+        AltGr(OsCode),
+        ShiftAltGr(OsCode),
+        NoEraseLowercase(OsCode),
+        NoEraseUppercase(OsCode),
+        NoEraseAltGr(OsCode),
+        NoEraseShiftAltGr(OsCode),
+    }
+
+    impl ZchOutput {
+        pub fn osc(self) -> OsCode {
+            use ZchOutput::*;
+            match self {
+                Lowercase(osc)
+                | Uppercase(osc)
+                | AltGr(osc)
+                | ShiftAltGr(osc)
+                | NoEraseLowercase(osc)
+                | NoEraseUppercase(osc)
+                | NoEraseAltGr(osc)
+                | NoEraseShiftAltGr(osc) => osc,
+            }
+        }
+        pub fn osc_and_is_noerase(self) -> (OsCode, bool) {
+            use ZchOutput::*;
+            match self {
+                Lowercase(osc) | Uppercase(osc) | AltGr(osc) | ShiftAltGr(osc) => (osc, false),
+                NoEraseLowercase(osc)
+                | NoEraseUppercase(osc)
+                | NoEraseAltGr(osc)
+                | NoEraseShiftAltGr(osc) => (osc, true),
+            }
+        }
+        pub fn display_len(outs: impl AsRef<[Self]>) -> i16 {
+            outs.as_ref().iter().copied().fold(0i16, |mut len, out| {
+                len += out.output_char_count();
+                len
+            })
+        }
+        pub fn output_char_count(self) -> i16 {
+            match self.osc_and_is_noerase() {
+                (OsCode::KEY_BACKSPACE, _) => -1,
+                (_, false) => 1,
+                (_, true) => 0,
+            }
+        }
+    }
+
+    /// User configuration for smart space.
+    ///
+    /// - `Full`         = add spaces after words, remove these spaces after typing punctuation.
+    /// - `AddSpaceOnly` = add spaces after words
+    /// - `Disabled`     = do nothing
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    pub enum ZchSmartSpaceCfg {
+        Full,
+        AddSpaceOnly,
+        Disabled,
+    }
+
+    #[derive(Debug)]
+    pub struct ZchConfig {
+        /// When, during typing, chord fails to activate, zippychord functionality becomes temporarily
+        /// disabled. This is to avoid accidental chord activations when typing normally, as opposed to
+        /// intentionally trying to activate a chord. The duration of temporary disabling is determined
+        /// by this configuration item. Re-enabling also happens when word-splitting characters are
+        /// typed, for example typing  a space or a comma, but a pause of all typing activity lasting a
+        /// number of milliseconds equal to this configuration will also re-enable chording even if
+        /// typing within a single word.
+        pub zch_cfg_ticks_wait_enable: u16,
+
+        /// Assuming zippychording is enabled, when the first press happens this deadline will begin
+        /// and if no chords are completed within the deadline, zippychording will be disabled
+        /// temporarily (see `zch_cfg_ticks_wait_enable`). You may want a long or short deadline
+        /// depending on your use case. If you are primarily typing normally, with chords being used
+        /// occasionally being used, you may want a short deadline so that regular typing will be
+        /// unlikely to activate any chord. However, if you primarily type with chords, you may want a
+        /// longer deadline to give you more time to complete the intended chord (e.g. in case of
+        /// overlaps). With a long deadline you should be very intentional about pressing and releasing
+        /// an individual key to begin a sequence of regular typing to trigger the disabling of
+        /// zippychord. If, after the first press, a chord activates, this deadline will reset to
+        /// enable further chord activations.
+        pub zch_cfg_ticks_chord_deadline: u16,
+
+        /// User configuration for smart space. See `pub enum ZchSmartSpaceCfg`.
+        pub zch_cfg_smart_space: ZchSmartSpaceCfg,
+
+        /// Define keys for punctuation, which is relevant to smart space auto-erasure of added spaces.
+        pub zch_cfg_smart_space_punctuation: HashSet<ZchOutput>,
+    }
+
+    impl Default for ZchConfig {
+        fn default() -> Self {
+            Self {
+                zch_cfg_ticks_wait_enable: 500,
+                zch_cfg_ticks_chord_deadline: 500,
+                zch_cfg_smart_space: ZchSmartSpaceCfg::Disabled,
+                zch_cfg_smart_space_punctuation: {
+                    let mut puncs = HashSet::default();
+                    puncs.insert(ZchOutput::Lowercase(OsCode::KEY_DOT));
+                    puncs.insert(ZchOutput::Lowercase(OsCode::KEY_COMMA));
+                    puncs.insert(ZchOutput::Lowercase(OsCode::KEY_SEMICOLON));
+                    puncs.shrink_to_fit();
+                    puncs
+                },
+            }
+        }
+    }
+
+    const NO_ERASE: &str = "no-erase";
+    const SINGLE_OUTPUT_MULTI_KEY: &str = "single-output";
+
+    enum ZchIoMappingType {
+        NoErase,
+        SingleOutput,
+    }
+    impl ZchIoMappingType {
+        fn try_parse(expr: &SExpr, vars: Option<&HashMap<String, SExpr>>) -> Result<Self> {
+            use ZchIoMappingType::*;
+            expr.atom(vars)
+                .and_then(|name| match name {
+                    NO_ERASE => Some(NoErase),
+                    SINGLE_OUTPUT_MULTI_KEY => Some(SingleOutput),
+                    _ => None,
+                })
+                .ok_or_else(|| {
+                    anyhow_expr!(
+                        &expr,
+                        "Unknown output type. Must be one of:\nno-erase | single-output"
+                    )
+                })
+        }
+    }
+
+    #[cfg(feature = "zippychord")]
+    pub(super) fn parse_zippy_inner(
+        exprs: &[SExpr],
+        s: &ParserState,
+        f: &mut FileContentProvider,
+    ) -> Result<(ZchPossibleChords, ZchConfig)> {
+        use crate::subset::GetOrIsSubsetOfKnownKey::*;
+
+        if exprs[0].atom(None).expect("should be atom") == "defzippy-experimental" {
+            log::warn!(
+                "You should replace defzippy-experimental with defzippy.\n\
+             Using -experimental will be invalid in the future."
+            );
+        }
+
+        if exprs.len() < 2 {
+            bail_expr!(
+                &exprs[0],
+                "There must be a filename following the zippy definition.\nFound {}",
+                exprs.len() - 1
+            );
+        }
+
+        let Some(file_name) = exprs[1].atom(s.vars()) else {
+            bail_expr!(&exprs[1], "Filename must be a string, not a list.");
+        };
+
+        let mut config = ZchConfig::default();
+
+        const KEY_NAME_MAPPINGS: &str = "output-character-mappings";
+        const IDLE_REACTIVATE_TIME: &str = "idle-reactivate-time";
+        const CHORD_DEADLINE: &str = "on-first-press-chord-deadline";
+        const SMART_SPACE: &str = "smart-space";
+        const SMART_SPACE_PUNCTUATION: &str = "smart-space-punctuation";
+
+        let mut idle_reactivate_time_seen = false;
+        let mut key_name_mappings_seen = false;
+        let mut chord_deadline_seen = false;
+        let mut smart_space_seen = false;
+        let mut smart_space_punctuation_seen = false;
+        let mut smart_space_punctuation_val_expr = None;
+
+        let mut user_cfg_char_to_output: HashMap<char, Vec<ZchOutput>> = HashMap::default();
+        let mut pairs = exprs[2..].chunks_exact(2);
+        for pair in pairs.by_ref() {
+            let config_name = &pair[0];
+            let config_value = &pair[1];
+
+            match config_name.atom(s.vars()).ok_or_else(|| {
+                anyhow_expr!(
+                    config_name,
+                    "A configuration name must be a string, not a list"
+                )
+            })? {
+                IDLE_REACTIVATE_TIME => {
+                    if idle_reactivate_time_seen {
+                        bail_expr!(
+                            config_name,
+                            "This is the 2nd instance; it can only be defined once"
+                        );
+                    }
+                    idle_reactivate_time_seen = true;
+                    config.zch_cfg_ticks_wait_enable =
+                        parse_u16(config_value, s, IDLE_REACTIVATE_TIME)?;
+                }
+
+                CHORD_DEADLINE => {
+                    if chord_deadline_seen {
+                        bail_expr!(
+                            config_name,
+                            "This is the 2nd instance; it can only be defined once"
+                        );
+                    }
+                    chord_deadline_seen = true;
+                    config.zch_cfg_ticks_chord_deadline =
+                        parse_u16(config_value, s, CHORD_DEADLINE)?;
+                }
+
+                SMART_SPACE => {
+                    if smart_space_seen {
+                        bail_expr!(
+                            config_name,
+                            "This is the 2nd instance; it can only be defined once"
+                        );
+                    }
+                    smart_space_seen = true;
+                    config.zch_cfg_smart_space = config_value
+                        .atom(s.vars())
+                        .and_then(|val| match val {
+                            "none" => Some(ZchSmartSpaceCfg::Disabled),
+                            "full" => Some(ZchSmartSpaceCfg::Full),
+                            "add-space-only" => Some(ZchSmartSpaceCfg::AddSpaceOnly),
+                            _ => None,
+                        })
+                        .ok_or_else(|| {
+                            anyhow_expr!(&config_value, "Must be: none | full | add-space-only")
+                        })?;
+                }
+
+                SMART_SPACE_PUNCTUATION => {
+                    if smart_space_punctuation_seen {
+                        bail_expr!(
+                            config_name,
+                            "This is the 2nd instance; it can only be defined once"
+                        );
+                    }
+                    smart_space_punctuation_seen = true;
+                    // Need to save and parse this later since it makes use of KEY_NAME_MAPPINGS.
+                    smart_space_punctuation_val_expr = Some(config_value);
+                }
+
+                KEY_NAME_MAPPINGS => {
+                    if key_name_mappings_seen {
+                        bail_expr!(
+                            config_name,
+                            "This is the 2nd instance; it can only be defined once"
+                        );
+                    }
+                    key_name_mappings_seen = true;
+                    let mut mappings = config_value
+                        .list(s.vars())
+                        .ok_or_else(|| {
+                            anyhow_expr!(
+                                config_value,
+                                "{KEY_NAME_MAPPINGS} must be followed by a list"
+                            )
+                        })?
+                        .chunks_exact(2);
+
+                    for mapping_pair in mappings.by_ref() {
+                        let input = mapping_pair[0]
+                            .atom(None)
+                            .ok_or_else(|| {
+                                anyhow_expr!(
+                                    &mapping_pair[0],
+                                    "key mapping input does not use lists"
+                                )
+                            })?
+                            .trim_atom_quotes();
+                        if input.chars().count() != 1 {
+                            bail_expr!(&mapping_pair[0], "Inputs should be exactly one character");
+                        }
+                        let input_char = input.chars().next().expect("count is 1");
+
+                        let output = match mapping_pair[1].atom(s.vars()) {
+                            Some(o) => vec![parse_single_zippy_output_mapping(
+                                o,
+                                &mapping_pair[1],
+                                false,
+                            )?],
+                            None => {
+                                // note for unwrap below: must be list if not atom
+                                let output_list = mapping_pair[1].list(s.vars()).unwrap();
+                                if output_list.is_empty() {
+                                    bail_expr!(
+                                        &mapping_pair[1],
+                                        "Empty list is invalid for zippy output mapping."
+                                    );
+                                }
+                                let output_type =
+                                    ZchIoMappingType::try_parse(&output_list[0], s.vars())?;
+                                match output_type {
+                                    ZchIoMappingType::NoErase => {
+                                        const ERR: &str = "expects a single key or output chord.";
+                                        if output_list.len() != 2 {
+                                            anyhow_expr!(&output_list[1], "{NO_ERASE} {ERR}");
+                                        }
+                                        let output =
+                                            output_list[1].atom(s.vars()).ok_or_else(|| {
+                                                anyhow_expr!(&output_list[1], "{NO_ERASE} {ERR}")
+                                            })?;
+                                        vec![parse_single_zippy_output_mapping(
+                                            output,
+                                            &output_list[1],
+                                            true,
+                                        )?]
+                                    }
+                                    ZchIoMappingType::SingleOutput => {
+                                        if output_list.len() < 2 {
+                                            anyhow_expr!(
+                                                &output_list[1],
+                                                "{SINGLE_OUTPUT_MULTI_KEY} expects one or more keys or output chords."
+                                            );
+                                        }
+                                        let all_params_except_last =
+                                            &output_list[1..output_list.len() - 1];
+                                        let mut outs = vec![];
+                                        for expr in all_params_except_last {
+                                            let output = expr
+                                            .atom(s.vars())
+                                            .ok_or_else(|| {
+                                                anyhow_expr!(&output_list[1], "{SINGLE_OUTPUT_MULTI_KEY} does not allow list parameters.")
+                                            })?;
+                                            let out = parse_single_zippy_output_mapping(
+                                                output,
+                                                &output_list[1],
+                                                true,
+                                            )?;
+                                            outs.push(out);
+                                        }
+                                        let last_expr = &output_list.last().unwrap(); // non-empty, checked length already
+                                        let last_out = last_expr
+                                        .atom(s.vars())
+                                        .ok_or_else(|| {
+                                            anyhow_expr!(last_expr, "{SINGLE_OUTPUT_MULTI_KEY} does not allow list parameters.")
+                                        })?;
+                                        outs.push(parse_single_zippy_output_mapping(
+                                            last_out, last_expr, false,
+                                        )?);
+                                        outs
+                                    }
+                                }
+                            }
+                        };
+
+                        if user_cfg_char_to_output.insert(input_char, output).is_some() {
+                            bail_expr!(&mapping_pair[0], "Duplicate character, not allowed");
+                        }
+                    }
+
+                    let rem = mappings.remainder();
+                    if !rem.is_empty() {
+                        bail_expr!(&rem[0], "zippy input is missing its output mapping");
+                    }
+                }
+                _ => bail_expr!(config_name, "Unknown zippy configuration name"),
+            }
+        }
+
+        let rem = pairs.remainder();
+        if !rem.is_empty() {
+            bail_expr!(&rem[0], "zippy config name is missing its value");
+        }
+
+        if let Some(val) = smart_space_punctuation_val_expr {
+            config.zch_cfg_smart_space_punctuation = val
+                .list(s.vars())
+                .ok_or_else(|| {
+                    anyhow_expr!(val, "{SMART_SPACE_PUNCTUATION} must be followed by a list")
+                })?
+                .iter()
+                .try_fold(vec![], |mut puncs, punc_expr| -> Result<Vec<ZchOutput>> {
+                    let punc = punc_expr
+                        .atom(s.vars())
+                        .ok_or_else(|| anyhow_expr!(&punc_expr, "Lists are not allowed"))?;
+
+                    if punc.chars().count() == 1 {
+                        let c = punc.chars().next().unwrap(); // checked count above
+                        if let Some(out) = user_cfg_char_to_output.get(&c) {
+                            if out.len() > 1 {
+                                bail_expr!(
+                                    punc_expr,
+                                    "This character is a single-output with multiple keys\n
+                                       and is not yet supported as use for punctuation."
+                                );
+                            }
+                            puncs.push(out[0]);
+                            return Ok(puncs);
+                        }
+                    }
+
+                    let osc = str_to_oscode(punc)
+                        .ok_or_else(|| anyhow_expr!(&punc_expr, "Unknown key name"))?;
+                    puncs.push(ZchOutput::Lowercase(osc));
+
+                    Ok(puncs)
+                })?
+                .into_iter()
+                .collect();
+            config.zch_cfg_smart_space_punctuation.shrink_to_fit();
+        }
+
+        // process zippy file
+        let input_data = f
+            .get_file_content(file_name.as_ref())
+            .map_err(|e| anyhow_expr!(&exprs[1], "Failed to read file:\n{e}"))?;
+        let res = input_data
+            .lines()
+            .enumerate()
+            .filter(|(_, line)| !line.trim().is_empty() && !line.trim().starts_with("//"))
+            .try_fold(
+                Arc::new(Mutex::new(ZchPossibleChords(SubsetMap::ssm_new()))),
+                |zch, (line_number, line)| {
+                    let Some((input, output)) = line.split_once('\t') else {
+                        bail_expr!(
+                        &exprs[1],
+                        "Input and output are separated by a tab, but found no tab:\n{}: {line}",
+                        line_number + 1
+                    );
+                    };
+                    if input.is_empty() {
+                        bail_expr!(
+                            &exprs[1],
+                            "No input defined; line must not begin with a tab:\n{}: {line}",
+                            line_number + 1
+                        );
+                    }
+
+                    let mut char_buf: [u8; 4] = [0; 4];
+                    let output = {
+                        output
+                            .chars()
+                            .try_fold(vec![], |mut zch_output, out_char| -> Result<_> {
+                                if let Some(out) = user_cfg_char_to_output.get(&out_char) {
+                                    zch_output.extend(out.iter());
+                                    return Ok(zch_output);
+                                }
+
+                                let out_key = out_char.to_lowercase().next().unwrap();
+                                let key_name = out_key.encode_utf8(&mut char_buf);
+                                let osc = match key_name as &str {
+                                    " " => OsCode::KEY_SPACE,
+                                    _ => str_to_oscode(key_name).ok_or_else(|| {
+                                        anyhow_expr!(
+                                            &exprs[1],
+                                            "Unknown output key name '{}':\n{}: {line}",
+                                            out_char,
+                                            line_number + 1,
+                                        )
+                                    })?,
+                                };
+                                let out = match out_char.is_uppercase() {
+                                    true => ZchOutput::Uppercase(osc),
+                                    false => ZchOutput::Lowercase(osc),
+                                };
+                                zch_output.push(out);
+                                Ok(zch_output)
+                            })?
+                            .into_boxed_slice()
+                    };
+                    let mut input_left_to_parse = input;
+                    let mut chord_chars;
+                    let mut input_chord = ZchInputKeys::zchik_new();
+                    let mut is_space_included;
+                    let mut possible_chords_map = zch.clone();
+                    let mut next_map: Option<Arc<Mutex<_>>>;
+
+                    while !input_left_to_parse.is_empty() {
+                        input_chord.zchik_clear();
+
+                        // Check for a starting space.
+                        (is_space_included, input_left_to_parse) =
+                            match input_left_to_parse.strip_prefix(' ') {
+                                None => (false, input_left_to_parse),
+                                Some(i) => (true, i),
+                            };
+                        if is_space_included {
+                            input_chord.zchik_insert(OsCode::KEY_SPACE);
+                        }
+
+                        // Parse chord until next space.
+                        (chord_chars, input_left_to_parse) =
+                            match input_left_to_parse.split_once(' ') {
+                                Some(split) => split,
+                                None => (input_left_to_parse, ""),
+                            };
+
+                        chord_chars
+                            .chars()
+                            .try_fold((), |_, chord_char| -> Result<()> {
+                                let key_name = chord_char.encode_utf8(&mut char_buf);
+                                let osc = str_to_oscode(key_name).ok_or_else(|| {
+                                    anyhow_expr!(
+                                        &exprs[1],
+                                        "Unknown input key name: '{key_name}':\n{}: {line}",
+                                        line_number + 1
+                                    )
+                                })?;
+                                input_chord.zchik_insert(osc);
+                                Ok(())
+                            })?;
+
+                        let output_for_input_chord = possible_chords_map
+                            .lock()
+                            .0
+                            .ssm_get_or_is_subset_ksorted(input_chord.zchik_keys());
+                        match (input_left_to_parse.is_empty(), output_for_input_chord) {
+                            (true, HasValue(_)) => {
+                                bail_expr!(
+                            &exprs[1],
+                            "Found duplicate input chord, which is disallowed {input}:\n{}: {line}",
+                            line_number + 1
+                        );
+                            }
+                            (true, _) => {
+                                possible_chords_map.lock().0.ssm_insert_ksorted(
+                                    input_chord.zchik_keys(),
+                                    Arc::new(ZchChordOutput {
+                                        zch_output: output,
+                                        zch_followups: None,
+                                    }),
+                                );
+                                break;
+                            }
+                            (false, HasValue(next_nested_map)) => {
+                                match &next_nested_map.zch_followups {
+                                    None => {
+                                        let map = Arc::new(Mutex::new(ZchPossibleChords(
+                                            SubsetMap::ssm_new(),
+                                        )));
+                                        next_map = Some(map.clone());
+                                        possible_chords_map.lock().0.ssm_insert_ksorted(
+                                            input_chord.zchik_keys(),
+                                            ZchChordOutput {
+                                                zch_output: next_nested_map.zch_output.clone(),
+                                                zch_followups: Some(map),
+                                            }
+                                            .into(),
+                                        );
+                                    }
+                                    Some(followup) => {
+                                        next_map = Some(followup.clone());
+                                    }
+                                }
+                            }
+                            (false, _) => {
+                                let map =
+                                    Arc::new(Mutex::new(ZchPossibleChords(SubsetMap::ssm_new())));
+                                next_map = Some(map.clone());
+                                possible_chords_map.lock().0.ssm_insert_ksorted(
+                                    input_chord.zchik_keys(),
+                                    Arc::new(ZchChordOutput {
+                                        zch_output: Box::new([]),
+                                        zch_followups: Some(map),
+                                    }),
+                                );
+                            }
+                        };
+                        if let Some(map) = next_map.take() {
+                            possible_chords_map = map;
+                        }
+                    }
+                    Ok(zch)
+                },
+            )?;
+        Ok((
+            Arc::into_inner(res).expect("no other refs").into_inner(),
+            config,
+        ))
+    }
+
+    fn parse_single_zippy_output_mapping(
+        output: &str,
+        output_expr: &SExpr,
+        is_noerase: bool,
+    ) -> Result<ZchOutput> {
+        let (output_mods, output_key) = parse_mod_prefix(output)?;
+        if output_mods.contains(&KeyCode::LShift) && output_mods.contains(&KeyCode::RShift) {
+            bail_expr!(
+                output_expr,
+                "Both shifts are used which is redundant, use only one."
+            );
+        }
+        if output_mods
+            .iter()
+            .any(|m| !matches!(m, KeyCode::LShift | KeyCode::RShift | KeyCode::RAlt))
+        {
+            bail_expr!(output_expr, "Only S- and AG- are supported.");
+        }
+        let output_osc = str_to_oscode(output_key)
+            .ok_or_else(|| anyhow_expr!(output_expr, "unknown key name"))?;
+        let output = match output_mods.len() {
+            0 => match is_noerase {
+                false => ZchOutput::Lowercase(output_osc),
+                true => ZchOutput::NoEraseLowercase(output_osc),
+            },
+            1 => match output_mods[0] {
+                KeyCode::LShift | KeyCode::RShift => match is_noerase {
+                    false => ZchOutput::Uppercase(output_osc),
+                    true => ZchOutput::NoEraseUppercase(output_osc),
+                },
+                KeyCode::RAlt => match is_noerase {
+                    false => ZchOutput::AltGr(output_osc),
+                    true => ZchOutput::NoEraseAltGr(output_osc),
+                },
+                _ => unreachable!("forbidden by earlier parsing"),
+            },
+            2 => match is_noerase {
+                false => ZchOutput::ShiftAltGr(output_osc),
+                true => ZchOutput::NoEraseShiftAltGr(output_osc),
+            },
+            _ => {
+                unreachable!("contains at most: altgr and one of the shifts")
+            }
+        };
+        Ok(output)
+    }
+}
diff --git a/parser/src/custom_action.rs b/parser/src/custom_action.rs
index d5ace1ce3..38b946600 100644
--- a/parser/src/custom_action.rs
+++ b/parser/src/custom_action.rs
@@ -3,12 +3,18 @@
 //! When adding a new custom action, the macro section of the config.adoc documentation may need to
 //! be updated, to include the new action to the documented list of supported actions in macro.
 
+use anyhow::{Result, anyhow};
+use core::fmt;
 use kanata_keyberon::key_code::KeyCode;
 
+use crate::{cfg::SimpleSExpr, keys::OsCode};
+
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum CustomAction {
-    Cmd(Vec<String>),
-    CmdOutputKeys(Vec<String>),
+    Cmd(&'static [&'static str]),
+    CmdLog(LogLevel, LogLevel, &'static [&'static str]),
+    CmdOutputKeys(&'static [&'static str]),
+    PushMessage(&'static [SimpleSExpr]),
     Unicode(char),
     Mouse(Btn),
     MouseTap(Btn),
@@ -20,12 +26,19 @@ pub enum CustomAction {
         coord: Coord,
         action: FakeKeyAction,
     },
+    FakeKeyOnIdle(FakeKeyOnIdle),
+    FakeKeyOnPhysicalIdle(FakeKeyOnIdle),
+    FakeKeyHoldForDuration(FakeKeyHoldForDuration),
     Delay(u16),
     DelayOnRelease(u16),
     MWheel {
         direction: MWheelDirection,
         interval: u16,
         distance: u16,
+        inertial_scroll_params: Option<&'static MWheelInertial>,
+    },
+    MWheelNotch {
+        direction: MWheelDirection,
     },
     MoveMouse {
         direction: MoveDirection,
@@ -39,12 +52,28 @@ pub enum CustomAction {
         min_distance: u16,
         max_distance: u16,
     },
-    SequenceLeader,
+    MoveMouseSpeed {
+        speed: u16,
+    },
+    SequenceCancel,
+    SequenceLeader(u16, SequenceInputMode),
+    /// Purpose:
+    /// In case the user has dead keys in their OS layout, they may wish to send fewer backspaces upon
+    /// a successful completion of visible-backspaced sequences, because the number of key events
+    /// is larger than the number of backspace-able symbols typed within the application.
+    /// This custom action is a marker to accomplish the use case.
+    SequenceNoerase(u16),
     LiveReload,
     LiveReloadNext,
     LiveReloadPrev,
+    /// Live-reload the n'th configuration file provided on the CLI. This should begin with 0 as
+    /// the first configuration file provided. The rest of the parser code is free to choose 0 or 1
+    /// as the user-facing value though.
+    LiveReloadNum(u16),
+    LiveReloadFile(&'static str),
     Repeat,
     CancelMacroOnRelease,
+    CancelMacroOnNextPress(u32),
     DynamicMacroRecord(u16),
     DynamicMacroRecordStop(u16),
     DynamicMacroPlay(u16),
@@ -54,6 +83,21 @@ pub enum CustomAction {
         x: u16,
         y: u16,
     },
+    Unmodded {
+        keys: &'static [KeyCode],
+        mods: UnmodMods,
+    },
+    Unshifted {
+        keys: &'static [KeyCode],
+    },
+    ReverseReleaseOrder,
+    ClipboardSet(&'static str),
+    ClipboardCmdSet(&'static [&'static str]),
+    ClipboardSave(u16),
+    ClipboardRestore(u16),
+    ClipboardSaveSet(u16, &'static str),
+    ClipboardSaveCmdSet(u16, &'static [&'static str]),
+    ClipboardSaveSwap(u16, u16),
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -65,6 +109,18 @@ pub enum Btn {
     Backward,
 }
 
+impl fmt::Display for Btn {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            Btn::Left => write!(f, "‹🖰"),
+            Btn::Right => write!(f, "🖰›"),
+            Btn::Mid => write!(f, "🖱"),
+            Btn::Backward => write!(f, "⎌🖰"),
+            Btn::Forward => write!(f, "🖰↷"),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct Coord {
     pub x: u8,
@@ -76,6 +132,23 @@ pub enum FakeKeyAction {
     Press,
     Release,
     Tap,
+    Toggle,
+}
+
+/// An active waiting-for-idle state.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct FakeKeyOnIdle {
+    pub coord: Coord,
+    pub action: FakeKeyAction,
+    pub idle_duration: u16,
+}
+
+/// Information for an action that presses a fake key / vkey that becomes released on a
+/// renewable-when-reactivated deadline.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct FakeKeyHoldForDuration {
+    pub coord: Coord,
+    pub hold_duration: u16,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -85,6 +158,38 @@ pub enum MWheelDirection {
     Left,
     Right,
 }
+impl fmt::Display for MWheelDirection {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            MWheelDirection::Up => write!(f, "🖱↑"),
+            MWheelDirection::Down => write!(f, "🖱↓"),
+            MWheelDirection::Left => write!(f, "🖱←"),
+            MWheelDirection::Right => write!(f, "🖱→"),
+        }
+    }
+}
+
+impl TryFrom<OsCode> for MWheelDirection {
+    type Error = ();
+    fn try_from(value: OsCode) -> Result<Self, Self::Error> {
+        use OsCode::*;
+        Ok(match value {
+            MouseWheelUp => MWheelDirection::Up,
+            MouseWheelDown => MWheelDirection::Down,
+            MouseWheelLeft => MWheelDirection::Left,
+            MouseWheelRight => MWheelDirection::Right,
+            _ => return Err(()),
+        })
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Hash, Eq)]
+pub struct MWheelInertial {
+    pub initial_velocity: ordered_float::OrderedFloat<f32>,
+    pub maximum_velocity: ordered_float::OrderedFloat<f32>,
+    pub acceleration_multiplier: ordered_float::OrderedFloat<f32>,
+    pub deceleration_multiplier: ordered_float::OrderedFloat<f32>,
+}
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum MoveDirection {
@@ -93,10 +198,126 @@ pub enum MoveDirection {
     Left,
     Right,
 }
+impl fmt::Display for MoveDirection {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            MoveDirection::Up => write!(f, "↑"),
+            MoveDirection::Down => write!(f, "↓"),
+            MoveDirection::Left => write!(f, "←"),
+            MoveDirection::Right => write!(f, "→"),
+        }
+    }
+}
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct CapsWordCfg {
     pub keys_to_capitalize: &'static [KeyCode],
     pub keys_nonterminal: &'static [KeyCode],
     pub timeout: u16,
+    pub repress_behaviour: CapsWordRepressBehaviour,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum CapsWordRepressBehaviour {
+    Overwrite,
+    Toggle,
+}
+
+/// This controls the behaviour of kanata when sequence mode is initiated by the sequence leader
+/// action.
+///
+/// - `HiddenSuppressed` hides the keys typed as part of the sequence and does not output the keys
+///   typed when an invalid sequence is the result of an invalid sequence character or a timeout.
+/// - `HiddenDelayType` hides the keys typed as part of the sequence and outputs the keys when an
+///   typed when an invalid sequence is the result of an invalid sequence character or a timeout.
+/// - `VisibleBackspaced` will type the keys that are typed as part of the sequence but will
+///   backspace the typed sequence keys before performing the fake key tap when a valid sequence is
+///   the result.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SequenceInputMode {
+    HiddenSuppressed,
+    HiddenDelayType,
+    VisibleBackspaced,
+}
+
+const SEQ_VISIBLE_BACKSPACED: &str = "visible-backspaced";
+const SEQ_HIDDEN_SUPPRESSED: &str = "hidden-suppressed";
+const SEQ_HIDDEN_DELAY_TYPE: &str = "hidden-delay-type";
+
+impl SequenceInputMode {
+    pub fn try_from_str(s: &str) -> Result<Self> {
+        match s {
+            SEQ_VISIBLE_BACKSPACED => Ok(SequenceInputMode::VisibleBackspaced),
+            SEQ_HIDDEN_SUPPRESSED => Ok(SequenceInputMode::HiddenSuppressed),
+            SEQ_HIDDEN_DELAY_TYPE => Ok(SequenceInputMode::HiddenDelayType),
+            _ => Err(anyhow!(SequenceInputMode::err_msg())),
+        }
+    }
+
+    pub fn err_msg() -> String {
+        format!(
+            "sequence input mode must be one of: {SEQ_VISIBLE_BACKSPACED}, {SEQ_HIDDEN_SUPPRESSED}, {SEQ_HIDDEN_DELAY_TYPE}"
+        )
+    }
+}
+
+const LOG_LEVEL_DEBUG: &str = "debug";
+const LOG_LEVEL_INFO: &str = "info";
+const LOG_LEVEL_WARN: &str = "warn";
+const LOG_LEVEL_ERROR: &str = "error";
+const LOG_LEVEL_NONE: &str = "none";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum LogLevel {
+    // No trace here because that wouldn't make sense
+    Debug,
+    Info,
+    Warn,
+    Error,
+    None,
+}
+
+impl LogLevel {
+    pub fn try_from_str(s: &str) -> Result<Self> {
+        match s {
+            LOG_LEVEL_DEBUG => Ok(LogLevel::Debug),
+            LOG_LEVEL_INFO => Ok(LogLevel::Info),
+            LOG_LEVEL_WARN => Ok(LogLevel::Warn),
+            LOG_LEVEL_ERROR => Ok(LogLevel::Error),
+            LOG_LEVEL_NONE => Ok(LogLevel::None),
+            _ => Err(anyhow!(LogLevel::err_msg())),
+        }
+    }
+
+    pub fn get_level(&self) -> Option<log::Level> {
+        match self {
+            LogLevel::Debug => Some(log::Level::Debug),
+            LogLevel::Info => Some(log::Level::Info),
+            LogLevel::Warn => Some(log::Level::Warn),
+            LogLevel::Error => Some(log::Level::Error),
+            LogLevel::None => None,
+        }
+    }
+
+    pub fn err_msg() -> String {
+        format!(
+            "log level must be one of: {LOG_LEVEL_DEBUG}, {LOG_LEVEL_INFO}, {LOG_LEVEL_WARN}, {LOG_LEVEL_ERROR}, {LOG_LEVEL_NONE}"
+        )
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct UnmodMods(u8);
+
+bitflags::bitflags! {
+    impl UnmodMods: u8 {
+        const LSft = 0b00000001;
+        const RSft = 0b00000010;
+        const LAlt = 0b00000100;
+        const RAlt = 0b00001000;
+        const LCtl = 0b00010000;
+        const RCtl = 0b00100000;
+        const LMet = 0b01000000;
+        const RMet = 0b10000000;
+    }
 }
diff --git a/parser/src/keys/linux.rs b/parser/src/keys/linux.rs
index 2cd90a64b..dbec816f0 100644
--- a/parser/src/keys/linux.rs
+++ b/parser/src/keys/linux.rs
@@ -1,16 +1,12 @@
 // This file is taken from the original ktrl project's keys.rs file with modifications.
 
-use evdev::{EventType, InputEvent};
-use std::convert::TryFrom;
-
-use super::{KeyEvent, KeyValue, OsCode};
+use super::OsCode;
 
 impl OsCode {
-    pub const fn as_u16(self) -> u16 {
+    pub(super) const fn as_u16_linux(self) -> u16 {
         self as u16
     }
-
-    pub const fn from_u16(code: u16) -> Option<Self> {
+    pub(super) const fn from_u16_linux(code: u16) -> Option<Self> {
         match code {
             0 => Some(OsCode::KEY_RESERVED),
             1 => Some(OsCode::KEY_ESC),
@@ -757,31 +753,16 @@ impl OsCode {
             742 => Some(OsCode::BTN_TRIGGER_HAPPY39),
             743 => Some(OsCode::BTN_TRIGGER_HAPPY40),
             744 => Some(OsCode::BTN_MAX),
+            745 => Some(OsCode::MouseWheelUp),
+            746 => Some(OsCode::MouseWheelDown),
+            747 => Some(OsCode::MouseWheelLeft),
+            748 => Some(OsCode::MouseWheelRight),
             767 => Some(OsCode::KEY_MAX),
             _ => None,
         }
     }
 }
 
-impl TryFrom<InputEvent> for KeyEvent {
-    type Error = ();
-    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
-        match item.kind() {
-            evdev::InputEventKind::Key(k) => Ok(Self {
-                code: OsCode::from_u16(k.0).ok_or(())?,
-                value: KeyValue::from(item.value()),
-            }),
-            _ => Err(()),
-        }
-    }
-}
-
-impl From<KeyEvent> for InputEvent {
-    fn from(item: KeyEvent) -> Self {
-        InputEvent::new(EventType::KEY, item.code as u16, item.value as i32)
-    }
-}
-
 use crate::custom_action::Btn;
 impl From<Btn> for OsCode {
     fn from(btn: Btn) -> Self {
diff --git a/parser/src/keys/macos.rs b/parser/src/keys/macos.rs
new file mode 100644
index 000000000..fd0538ec4
--- /dev/null
+++ b/parser/src/keys/macos.rs
@@ -0,0 +1,2178 @@
+use super::OsCode;
+
+// because the parser can't handle oscode u16 values > 767
+// and macos has fucked up key coding (page and code)
+pub struct PageCode {
+    pub page: u32,
+    pub code: u32,
+}
+
+impl TryFrom<OsCode> for PageCode {
+    type Error = &'static str;
+    fn try_from(item: OsCode) -> Result<Self, Self::Error> {
+        match item {
+            OsCode::KEY_RESERVED => Ok(PageCode {
+                page: 0xFF,
+                code: 0xFF,
+            }),
+            OsCode::KEY_A => Ok(PageCode {
+                page: 0x07,
+                code: 0x04,
+            }),
+            OsCode::KEY_B => Ok(PageCode {
+                page: 0x07,
+                code: 0x05,
+            }),
+            OsCode::KEY_C => Ok(PageCode {
+                page: 0x07,
+                code: 0x06,
+            }),
+            OsCode::KEY_D => Ok(PageCode {
+                page: 0x07,
+                code: 0x07,
+            }),
+            OsCode::KEY_E => Ok(PageCode {
+                page: 0x07,
+                code: 0x08,
+            }),
+            OsCode::KEY_F => Ok(PageCode {
+                page: 0x07,
+                code: 0x09,
+            }),
+            OsCode::KEY_G => Ok(PageCode {
+                page: 0x07,
+                code: 0x0A,
+            }),
+            OsCode::KEY_H => Ok(PageCode {
+                page: 0x07,
+                code: 0x0B,
+            }),
+            OsCode::KEY_I => Ok(PageCode {
+                page: 0x07,
+                code: 0x0C,
+            }),
+            OsCode::KEY_J => Ok(PageCode {
+                page: 0x07,
+                code: 0x0D,
+            }),
+            OsCode::KEY_K => Ok(PageCode {
+                page: 0x07,
+                code: 0x0E,
+            }),
+            OsCode::KEY_L => Ok(PageCode {
+                page: 0x07,
+                code: 0x0F,
+            }),
+            OsCode::KEY_M => Ok(PageCode {
+                page: 0x07,
+                code: 0x10,
+            }),
+            OsCode::KEY_N => Ok(PageCode {
+                page: 0x07,
+                code: 0x11,
+            }),
+            OsCode::KEY_O => Ok(PageCode {
+                page: 0x07,
+                code: 0x12,
+            }),
+            OsCode::KEY_P => Ok(PageCode {
+                page: 0x07,
+                code: 0x13,
+            }),
+            OsCode::KEY_Q => Ok(PageCode {
+                page: 0x07,
+                code: 0x14,
+            }),
+            OsCode::KEY_R => Ok(PageCode {
+                page: 0x07,
+                code: 0x15,
+            }),
+            OsCode::KEY_S => Ok(PageCode {
+                page: 0x07,
+                code: 0x16,
+            }),
+            OsCode::KEY_T => Ok(PageCode {
+                page: 0x07,
+                code: 0x17,
+            }),
+            OsCode::KEY_U => Ok(PageCode {
+                page: 0x07,
+                code: 0x18,
+            }),
+            OsCode::KEY_V => Ok(PageCode {
+                page: 0x07,
+                code: 0x19,
+            }),
+            OsCode::KEY_W => Ok(PageCode {
+                page: 0x07,
+                code: 0x1A,
+            }),
+            OsCode::KEY_X => Ok(PageCode {
+                page: 0x07,
+                code: 0x1B,
+            }),
+            OsCode::KEY_Y => Ok(PageCode {
+                page: 0x07,
+                code: 0x1C,
+            }),
+            OsCode::KEY_Z => Ok(PageCode {
+                page: 0x07,
+                code: 0x1D,
+            }),
+            OsCode::KEY_1 => Ok(PageCode {
+                page: 0x07,
+                code: 0x1E,
+            }),
+            OsCode::KEY_2 => Ok(PageCode {
+                page: 0x07,
+                code: 0x1F,
+            }),
+            OsCode::KEY_3 => Ok(PageCode {
+                page: 0x07,
+                code: 0x20,
+            }),
+            OsCode::KEY_4 => Ok(PageCode {
+                page: 0x07,
+                code: 0x21,
+            }),
+            OsCode::KEY_5 => Ok(PageCode {
+                page: 0x07,
+                code: 0x22,
+            }),
+            OsCode::KEY_6 => Ok(PageCode {
+                page: 0x07,
+                code: 0x23,
+            }),
+            OsCode::KEY_7 => Ok(PageCode {
+                page: 0x07,
+                code: 0x24,
+            }),
+            OsCode::KEY_8 => Ok(PageCode {
+                page: 0x07,
+                code: 0x25,
+            }),
+            OsCode::KEY_9 => Ok(PageCode {
+                page: 0x07,
+                code: 0x26,
+            }),
+            OsCode::KEY_0 => Ok(PageCode {
+                page: 0x07,
+                code: 0x27,
+            }),
+            OsCode::KEY_ENTER => Ok(PageCode {
+                page: 0x07,
+                code: 0x28,
+            }),
+            OsCode::KEY_ESC => Ok(PageCode {
+                page: 0x07,
+                code: 0x29,
+            }),
+            OsCode::KEY_BACKSPACE => Ok(PageCode {
+                page: 0x07,
+                code: 0x2A,
+            }),
+            OsCode::KEY_TAB => Ok(PageCode {
+                page: 0x07,
+                code: 0x2B,
+            }),
+            OsCode::KEY_SPACE => Ok(PageCode {
+                page: 0x07,
+                code: 0x2C,
+            }),
+            OsCode::KEY_MINUS => Ok(PageCode {
+                page: 0x07,
+                code: 0x2D,
+            }),
+            OsCode::KEY_EQUAL => Ok(PageCode {
+                page: 0x07,
+                code: 0x2E,
+            }),
+            OsCode::KEY_LEFTBRACE => Ok(PageCode {
+                page: 0x07,
+                code: 0x2F,
+            }),
+            OsCode::KEY_RIGHTBRACE => Ok(PageCode {
+                page: 0x07,
+                code: 0x30,
+            }),
+            OsCode::KEY_BACKSLASH => Ok(PageCode {
+                page: 0x07,
+                code: 0x31,
+            }),
+            // Keyboard Non-US # and ~ (ISO layouts, key left of Enter labelled "#").
+            // Linux evdev folds this onto KEY_BACKSLASH (43); macOS exposes it as a
+            // distinct HID usage, so we reuse the otherwise-unused KEY_NUMERIC_POUND
+            // OsCode. Users who want a symmetric name across platforms can pair this
+            // with `deflocalkeys-linux` mapping 43 to the same name. See #1915.
+            OsCode::KEY_NUMERIC_POUND => Ok(PageCode {
+                page: 0x07,
+                code: 0x32,
+            }),
+            OsCode::KEY_SEMICOLON => Ok(PageCode {
+                page: 0x07,
+                code: 0x33,
+            }),
+            OsCode::KEY_APOSTROPHE => Ok(PageCode {
+                page: 0x07,
+                code: 0x34,
+            }),
+            OsCode::KEY_GRAVE => Ok(PageCode {
+                page: 0x07,
+                code: 0x35,
+            }),
+            OsCode::KEY_COMMA => Ok(PageCode {
+                page: 0x07,
+                code: 0x36,
+            }),
+            OsCode::KEY_DOT => Ok(PageCode {
+                page: 0x07,
+                code: 0x37,
+            }),
+            OsCode::KEY_SLASH => Ok(PageCode {
+                page: 0x07,
+                code: 0x38,
+            }),
+            OsCode::KEY_CAPSLOCK => Ok(PageCode {
+                page: 0x07,
+                code: 0x39,
+            }),
+            OsCode::KEY_F1 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3A,
+            }),
+            OsCode::KEY_F2 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3B,
+            }),
+            OsCode::KEY_F3 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3C,
+            }),
+            OsCode::KEY_F4 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3D,
+            }),
+            OsCode::KEY_F5 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3E,
+            }),
+            OsCode::KEY_F6 => Ok(PageCode {
+                page: 0x07,
+                code: 0x3F,
+            }),
+            OsCode::KEY_F7 => Ok(PageCode {
+                page: 0x07,
+                code: 0x40,
+            }),
+            OsCode::KEY_F8 => Ok(PageCode {
+                page: 0x07,
+                code: 0x41,
+            }),
+            OsCode::KEY_F9 => Ok(PageCode {
+                page: 0x07,
+                code: 0x42,
+            }),
+            OsCode::KEY_F10 => Ok(PageCode {
+                page: 0x07,
+                code: 0x43,
+            }),
+            OsCode::KEY_F11 => Ok(PageCode {
+                page: 0x07,
+                code: 0x44,
+            }),
+            OsCode::KEY_F12 => Ok(PageCode {
+                page: 0x07,
+                code: 0x45,
+            }),
+            OsCode::KEY_PRINT => Ok(PageCode {
+                page: 0x07,
+                code: 0x46,
+            }),
+            OsCode::KEY_SCROLLLOCK => Ok(PageCode {
+                page: 0x07,
+                code: 0x47,
+            }),
+            OsCode::KEY_PAUSE => Ok(PageCode {
+                page: 0x07,
+                code: 0x48,
+            }),
+            OsCode::KEY_INSERT => Ok(PageCode {
+                page: 0x07,
+                code: 0x49,
+            }),
+            OsCode::KEY_HOME => Ok(PageCode {
+                page: 0x07,
+                code: 0x4A,
+            }),
+            OsCode::KEY_PAGEUP => Ok(PageCode {
+                page: 0x07,
+                code: 0x4B,
+            }),
+            OsCode::KEY_DELETE => Ok(PageCode {
+                page: 0x07,
+                code: 0x4C,
+            }),
+            OsCode::KEY_END => Ok(PageCode {
+                page: 0x07,
+                code: 0x4D,
+            }),
+            OsCode::KEY_PAGEDOWN => Ok(PageCode {
+                page: 0x07,
+                code: 0x4E,
+            }),
+            OsCode::KEY_RIGHT => Ok(PageCode {
+                page: 0x07,
+                code: 0x4F,
+            }),
+            OsCode::KEY_LEFT => Ok(PageCode {
+                page: 0x07,
+                code: 0x50,
+            }),
+            OsCode::KEY_DOWN => Ok(PageCode {
+                page: 0x07,
+                code: 0x51,
+            }),
+            OsCode::KEY_UP => Ok(PageCode {
+                page: 0x07,
+                code: 0x52,
+            }),
+            OsCode::KEY_NUMLOCK => Ok(PageCode {
+                page: 0x07,
+                code: 0x53,
+            }),
+            OsCode::KEY_KPSLASH => Ok(PageCode {
+                page: 0x07,
+                code: 0x54,
+            }),
+            OsCode::KEY_KPASTERISK => Ok(PageCode {
+                page: 0x07,
+                code: 0x55,
+            }),
+            OsCode::KEY_KPMINUS => Ok(PageCode {
+                page: 0x07,
+                code: 0x56,
+            }),
+            OsCode::KEY_KPPLUS => Ok(PageCode {
+                page: 0x07,
+                code: 0x57,
+            }),
+            OsCode::KEY_KPENTER => Ok(PageCode {
+                page: 0x07,
+                code: 0x58,
+            }),
+            OsCode::KEY_KP1 => Ok(PageCode {
+                page: 0x07,
+                code: 0x59,
+            }),
+            OsCode::KEY_KP2 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5A,
+            }),
+            OsCode::KEY_KP3 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5B,
+            }),
+            OsCode::KEY_KP4 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5C,
+            }),
+            OsCode::KEY_KP5 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5D,
+            }),
+            OsCode::KEY_KP6 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5E,
+            }),
+            OsCode::KEY_KP7 => Ok(PageCode {
+                page: 0x07,
+                code: 0x5F,
+            }),
+            OsCode::KEY_KP8 => Ok(PageCode {
+                page: 0x07,
+                code: 0x60,
+            }),
+            OsCode::KEY_KP9 => Ok(PageCode {
+                page: 0x07,
+                code: 0x61,
+            }),
+            OsCode::KEY_KP0 => Ok(PageCode {
+                page: 0x07,
+                code: 0x62,
+            }),
+            OsCode::KEY_KPDOT => Ok(PageCode {
+                page: 0x07,
+                code: 0x63,
+            }),
+            OsCode::KEY_102ND => Ok(PageCode {
+                page: 0x07,
+                code: 0x64,
+            }), //KeyboardNonUSBackslash
+            OsCode::KEY_COMPOSE => Ok(PageCode {
+                page: 0x07,
+                code: 0x65,
+            }),
+            OsCode::KEY_POWER => Ok(PageCode {
+                page: 0x07,
+                code: 0x66,
+            }),
+            OsCode::KEY_KPEQUAL => Ok(PageCode {
+                page: 0x07,
+                code: 0x67,
+            }),
+            OsCode::KEY_F13 => Ok(PageCode {
+                page: 0x07,
+                code: 0x68,
+            }),
+            OsCode::KEY_F14 => Ok(PageCode {
+                page: 0x07,
+                code: 0x69,
+            }),
+            OsCode::KEY_F15 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6A,
+            }),
+            OsCode::KEY_F16 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6B,
+            }),
+            OsCode::KEY_F17 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6C,
+            }),
+            OsCode::KEY_F18 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6D,
+            }),
+            OsCode::KEY_F19 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6E,
+            }),
+            OsCode::KEY_F20 => Ok(PageCode {
+                page: 0x07,
+                code: 0x6F,
+            }),
+            OsCode::KEY_F21 => Ok(PageCode {
+                page: 0x07,
+                code: 0x70,
+            }),
+            OsCode::KEY_F22 => Ok(PageCode {
+                page: 0x07,
+                code: 0x71,
+            }),
+            OsCode::KEY_F23 => Ok(PageCode {
+                page: 0x07,
+                code: 0x72,
+            }),
+            OsCode::KEY_F24 => Ok(PageCode {
+                page: 0x07,
+                code: 0x73,
+            }),
+            // KeyboardExecute                   => 0x0774,  todo
+            OsCode::KEY_HELP => Ok(PageCode {
+                page: 0x07,
+                code: 0x75,
+            }),
+            OsCode::KEY_MENU => Ok(PageCode {
+                page: 0x07,
+                code: 0x76,
+            }),
+            OsCode::KEY_SELECT => Ok(PageCode {
+                page: 0x07,
+                code: 0x77,
+            }),
+            OsCode::KEY_STOP => Ok(PageCode {
+                page: 0x07,
+                code: 0x78,
+            }),
+            OsCode::KEY_AGAIN => Ok(PageCode {
+                page: 0x07,
+                code: 0x79,
+            }),
+            OsCode::KEY_UNDO => Ok(PageCode {
+                page: 0x07,
+                code: 0x7A,
+            }),
+            OsCode::KEY_CUT => Ok(PageCode {
+                page: 0x07,
+                code: 0x7B,
+            }),
+            OsCode::KEY_COPY => Ok(PageCode {
+                page: 0x07,
+                code: 0x7C,
+            }),
+            OsCode::KEY_PASTE => Ok(PageCode {
+                page: 0x07,
+                code: 0x7D,
+            }),
+            OsCode::KEY_FIND => Ok(PageCode {
+                page: 0x07,
+                code: 0x7E,
+            }),
+            OsCode::KEY_MUTE => Ok(PageCode {
+                page: 0x0C,
+                code: 0xE2,
+            }), // 0x077f
+            OsCode::KEY_VOLUMEUP => Ok(PageCode {
+                page: 0x0C,
+                code: 0xE9,
+            }), // 0x0780
+            OsCode::KEY_VOLUMEDOWN => Ok(PageCode {
+                page: 0x0C,
+                code: 0xEA,
+            }), // 0x0781
+            OsCode::KEY_EJECTCD => Ok(PageCode {
+                page: 0x0C,
+                code: 0xB8,
+            }), // 0x0781
+            //KeyboardLockingCapsLock   => 82, todo
+            //KeyboardLockingNumLock    => 83, todo
+            //KeyboardLockingScrollLock => 84, todo
+            OsCode::KEY_KPCOMMA => Ok(PageCode {
+                page: 0x07,
+                code: 0x85,
+            }),
+            OsCode::KEY_RO => Ok(PageCode {
+                page: 0x07,
+                code: 0x87,
+            }),
+            OsCode::KEY_KATAKANAHIRAGANA => Ok(PageCode {
+                page: 0x07,
+                code: 0x88,
+            }),
+            OsCode::KEY_YEN => Ok(PageCode {
+                page: 0x07,
+                code: 0x89,
+            }),
+            OsCode::KEY_HENKAN => Ok(PageCode {
+                page: 0x07,
+                code: 0x8A,
+            }),
+            OsCode::KEY_MUHENKAN => Ok(PageCode {
+                page: 0x07,
+                code: 0x8B,
+            }),
+            OsCode::KEY_KPJPCOMMA => Ok(PageCode {
+                page: 0x07,
+                code: 0x8C,
+            }),
+            OsCode::KEY_HANGEUL => Ok(PageCode {
+                page: 0x07,
+                code: 0x90,
+            }),
+            OsCode::KEY_HANJA => Ok(PageCode {
+                page: 0x07,
+                code: 0x91,
+            }),
+            OsCode::KEY_KATAKANA => Ok(PageCode {
+                page: 0x07,
+                code: 0x92,
+            }),
+            OsCode::KEY_HIRAGANA => Ok(PageCode {
+                page: 0x07,
+                code: 0x93,
+            }),
+            OsCode::KEY_ZENKAKUHANKAKU => Ok(PageCode {
+                page: 0x07,
+                code: 0x94,
+            }),
+            OsCode::KEY_ALTERASE => Ok(PageCode {
+                page: 0x07,
+                code: 0x99,
+            }),
+            OsCode::KEY_CANCEL => Ok(PageCode {
+                page: 0x07,
+                code: 0x9B,
+            }),
+            OsCode::KEY_CLEAR => Ok(PageCode {
+                page: 0x07,
+                code: 0x9C,
+            }),
+            OsCode::KEY_LEFTCTRL => Ok(PageCode {
+                page: 0x07,
+                code: 0xE0,
+            }),
+            OsCode::KEY_LEFTSHIFT => Ok(PageCode {
+                page: 0x07,
+                code: 0xE1,
+            }),
+            OsCode::KEY_LEFTALT => Ok(PageCode {
+                page: 0x07,
+                code: 0xE2,
+            }),
+            OsCode::KEY_LEFTMETA => Ok(PageCode {
+                page: 0x07,
+                code: 0xE3,
+            }),
+            OsCode::KEY_RIGHTCTRL => Ok(PageCode {
+                page: 0x07,
+                code: 0xE4,
+            }),
+            OsCode::KEY_RIGHTSHIFT => Ok(PageCode {
+                page: 0x07,
+                code: 0xE5,
+            }),
+            OsCode::KEY_RIGHTALT => Ok(PageCode {
+                page: 0x07,
+                code: 0xE6,
+            }),
+            OsCode::KEY_RIGHTMETA => Ok(PageCode {
+                page: 0x07,
+                code: 0xE7,
+            }),
+            // ??
+            //OsCode::KEY_POWER           => Ok( PageCode { page: 0x0C, code: 0x30 } ),
+            OsCode::KEY_SLEEP => Ok(PageCode {
+                page: 0x0C,
+                code: 0x32,
+            }),
+            OsCode::KEY_FORWARD => Ok(PageCode {
+                page: 0x0C,
+                code: 0xB3,
+            }),
+            OsCode::KEY_REWIND => Ok(PageCode {
+                page: 0x0C,
+                code: 0xB4,
+            }),
+            OsCode::KEY_NEXTSONG => Ok(PageCode {
+                page: 0x0C,
+                code: 0xB5,
+            }),
+            OsCode::KEY_PREVIOUSSONG => Ok(PageCode {
+                page: 0x0C,
+                code: 0xB6,
+            }),
+            OsCode::KEY_PLAYPAUSE => Ok(PageCode {
+                page: 0x0C,
+                code: 0xCD,
+            }),
+            OsCode::KEY_FN => Ok(PageCode {
+                page: 0xFF,
+                code: 0x03,
+            }),
+            OsCode::KEY_BRIGHTNESSUP => Ok(PageCode {
+                page: 0x0C,
+                code: 0x6F,
+            }),
+            OsCode::KEY_BRIGHTNESSDOWN => Ok(PageCode {
+                page: 0x0C,
+                code: 0x70,
+            }),
+            // OsCode::KEY_BRIGHTNESSUP    => Ok( PageCode { page: 0x0C, code: 0x04 } ),
+            // OsCode::KEY_BRIGHTNESSDOWN  => Ok( PageCode { page: 0x0C, code: 0x05 } ),
+            // OsCode::KEY_KBDILLUMTOGGLE  => Ok( PageCode { page: 0x0C, code: 0x07 } ),
+            // OsCode::KEY_KBDILLUMUP      => Ok( PageCode { page: 0x0C, code: 0x08 } ),
+            // OsCode::KEY_KBDILLUMDOWN    => Ok( PageCode { page: 0x0C, code: 0x09 } ),
+            OsCode::KEY_KBDILLUMTOGGLE => Ok(PageCode {
+                page: 0xFF,
+                code: 0x07,
+            }),
+            OsCode::KEY_KBDILLUMUP => Ok(PageCode {
+                page: 0xFF,
+                code: 0x08,
+            }),
+            OsCode::KEY_KBDILLUMDOWN => Ok(PageCode {
+                page: 0xFF,
+                code: 0x09,
+            }),
+            // ??
+            OsCode::KEY_DASHBOARD => Ok(PageCode {
+                page: 0xFF,
+                code: 0x02,
+            }),
+            OsCode::KEY_SEARCH => Ok(PageCode {
+                page: 0xFF,
+                code: 0x01,
+            }),
+            OsCode::KEY_249 => Ok(PageCode {
+                page: 0x0C,
+                code: 0x221,
+            }),
+            OsCode::KEY_250 => Ok(PageCode {
+                page: 0x0C,
+                code: 0xCF,
+            }),
+            OsCode::KEY_251 => Ok(PageCode {
+                page: 0x01,
+                code: 0x9B,
+            }),
+            OsCode::KEY_252 => Ok(PageCode {
+                page: 0x0C,
+                code: 0x29F,
+            }),
+            OsCode::KEY_253 => Ok(PageCode {
+                page: 0x0C,
+                code: 0x2A0,
+            }),
+            // OsCode::KEY_FN_ESC          => 0x07,
+            // OsCode::KEY_FN_F1           => 0x07,
+            // OsCode::KEY_FN_F2           => 0x07,
+            // OsCode::KEY_FN_F3           => 0x07,
+            // OsCode::KEY_FN_F4           => 0x07,
+            // OsCode::KEY_FN_F5           => 0x07,
+            // OsCode::KEY_FN_F6           => 0x07,
+            // OsCode::KEY_FN_F7           => 0x07,
+            // OsCode::KEY_FN_F8           => 0x07,
+            // OsCode::KEY_FN_F9           => 0x07,
+            // OsCode::KEY_FN_F10          => 0x07,
+            // OsCode::KEY_FN_F11          => 0x07,
+            // OsCode::KEY_FN_F12          => 0x07,
+            // OsCode::KEY_FN_1            => 0x07,
+            // OsCode::KEY_FN_2            => 0x07,
+            // OsCode::KEY_FN_D            => 0x07,
+            // OsCode::KEY_FN_E            => 0x07,
+            // OsCode::KEY_FN_F            => 0x07,
+            // OsCode::KEY_FN_S            => 0x07,
+            // OsCode::KEY_FN_B            => 0x07,
+            // osc => Err(&format!("OsCode {} not mapped!", osc.as_u16())),
+            _ => Err("OsCode unrecognized!"),
+        }
+    }
+}
+
+impl TryFrom<PageCode> for OsCode {
+    type Error = &'static str;
+    fn try_from(item: PageCode) -> Result<Self, Self::Error> {
+        match item {
+            PageCode {
+                page: 0xFF,
+                code: 0xFF,
+            } => Ok(OsCode::KEY_RESERVED),
+            PageCode {
+                page: 0x07,
+                code: 0x04,
+            } => Ok(OsCode::KEY_A),
+            PageCode {
+                page: 0x07,
+                code: 0x05,
+            } => Ok(OsCode::KEY_B),
+            PageCode {
+                page: 0x07,
+                code: 0x06,
+            } => Ok(OsCode::KEY_C),
+            PageCode {
+                page: 0x07,
+                code: 0x07,
+            } => Ok(OsCode::KEY_D),
+            PageCode {
+                page: 0x07,
+                code: 0x08,
+            } => Ok(OsCode::KEY_E),
+            PageCode {
+                page: 0x07,
+                code: 0x09,
+            } => Ok(OsCode::KEY_F),
+            PageCode {
+                page: 0x07,
+                code: 0x0A,
+            } => Ok(OsCode::KEY_G),
+            PageCode {
+                page: 0x07,
+                code: 0x0B,
+            } => Ok(OsCode::KEY_H),
+            PageCode {
+                page: 0x07,
+                code: 0x0C,
+            } => Ok(OsCode::KEY_I),
+            PageCode {
+                page: 0x07,
+                code: 0x0D,
+            } => Ok(OsCode::KEY_J),
+            PageCode {
+                page: 0x07,
+                code: 0x0E,
+            } => Ok(OsCode::KEY_K),
+            PageCode {
+                page: 0x07,
+                code: 0x0F,
+            } => Ok(OsCode::KEY_L),
+            PageCode {
+                page: 0x07,
+                code: 0x10,
+            } => Ok(OsCode::KEY_M),
+            PageCode {
+                page: 0x07,
+                code: 0x11,
+            } => Ok(OsCode::KEY_N),
+            PageCode {
+                page: 0x07,
+                code: 0x12,
+            } => Ok(OsCode::KEY_O),
+            PageCode {
+                page: 0x07,
+                code: 0x13,
+            } => Ok(OsCode::KEY_P),
+            PageCode {
+                page: 0x07,
+                code: 0x14,
+            } => Ok(OsCode::KEY_Q),
+            PageCode {
+                page: 0x07,
+                code: 0x15,
+            } => Ok(OsCode::KEY_R),
+            PageCode {
+                page: 0x07,
+                code: 0x16,
+            } => Ok(OsCode::KEY_S),
+            PageCode {
+                page: 0x07,
+                code: 0x17,
+            } => Ok(OsCode::KEY_T),
+            PageCode {
+                page: 0x07,
+                code: 0x18,
+            } => Ok(OsCode::KEY_U),
+            PageCode {
+                page: 0x07,
+                code: 0x19,
+            } => Ok(OsCode::KEY_V),
+            PageCode {
+                page: 0x07,
+                code: 0x1A,
+            } => Ok(OsCode::KEY_W),
+            PageCode {
+                page: 0x07,
+                code: 0x1B,
+            } => Ok(OsCode::KEY_X),
+            PageCode {
+                page: 0x07,
+                code: 0x1C,
+            } => Ok(OsCode::KEY_Y),
+            PageCode {
+                page: 0x07,
+                code: 0x1D,
+            } => Ok(OsCode::KEY_Z),
+            PageCode {
+                page: 0x07,
+                code: 0x1E,
+            } => Ok(OsCode::KEY_1),
+            PageCode {
+                page: 0x07,
+                code: 0x1F,
+            } => Ok(OsCode::KEY_2),
+            PageCode {
+                page: 0x07,
+                code: 0x20,
+            } => Ok(OsCode::KEY_3),
+            PageCode {
+                page: 0x07,
+                code: 0x21,
+            } => Ok(OsCode::KEY_4),
+            PageCode {
+                page: 0x07,
+                code: 0x22,
+            } => Ok(OsCode::KEY_5),
+            PageCode {
+                page: 0x07,
+                code: 0x23,
+            } => Ok(OsCode::KEY_6),
+            PageCode {
+                page: 0x07,
+                code: 0x24,
+            } => Ok(OsCode::KEY_7),
+            PageCode {
+                page: 0x07,
+                code: 0x25,
+            } => Ok(OsCode::KEY_8),
+            PageCode {
+                page: 0x07,
+                code: 0x26,
+            } => Ok(OsCode::KEY_9),
+            PageCode {
+                page: 0x07,
+                code: 0x27,
+            } => Ok(OsCode::KEY_0),
+            PageCode {
+                page: 0x07,
+                code: 0x28,
+            } => Ok(OsCode::KEY_ENTER),
+            PageCode {
+                page: 0x07,
+                code: 0x29,
+            } => Ok(OsCode::KEY_ESC),
+            PageCode {
+                page: 0x07,
+                code: 0x2A,
+            } => Ok(OsCode::KEY_BACKSPACE),
+            PageCode {
+                page: 0x07,
+                code: 0x2B,
+            } => Ok(OsCode::KEY_TAB),
+            PageCode {
+                page: 0x07,
+                code: 0x2C,
+            } => Ok(OsCode::KEY_SPACE),
+            PageCode {
+                page: 0x07,
+                code: 0x2D,
+            } => Ok(OsCode::KEY_MINUS),
+            PageCode {
+                page: 0x07,
+                code: 0x2E,
+            } => Ok(OsCode::KEY_EQUAL),
+            PageCode {
+                page: 0x07,
+                code: 0x2F,
+            } => Ok(OsCode::KEY_LEFTBRACE),
+            PageCode {
+                page: 0x07,
+                code: 0x30,
+            } => Ok(OsCode::KEY_RIGHTBRACE),
+            PageCode {
+                page: 0x07,
+                code: 0x31,
+            } => Ok(OsCode::KEY_BACKSLASH),
+            // Keyboard Non-US # and ~. See the forward mapping above for rationale.
+            PageCode {
+                page: 0x07,
+                code: 0x32,
+            } => Ok(OsCode::KEY_NUMERIC_POUND),
+            PageCode {
+                page: 0x07,
+                code: 0x33,
+            } => Ok(OsCode::KEY_SEMICOLON),
+            PageCode {
+                page: 0x07,
+                code: 0x34,
+            } => Ok(OsCode::KEY_APOSTROPHE),
+            PageCode {
+                page: 0x07,
+                code: 0x35,
+            } => Ok(OsCode::KEY_GRAVE),
+            PageCode {
+                page: 0x07,
+                code: 0x36,
+            } => Ok(OsCode::KEY_COMMA),
+            PageCode {
+                page: 0x07,
+                code: 0x37,
+            } => Ok(OsCode::KEY_DOT),
+            PageCode {
+                page: 0x07,
+                code: 0x38,
+            } => Ok(OsCode::KEY_SLASH),
+            PageCode {
+                page: 0x07,
+                code: 0x39,
+            } => Ok(OsCode::KEY_CAPSLOCK),
+            PageCode {
+                page: 0x07,
+                code: 0x3A,
+            } => Ok(OsCode::KEY_F1),
+            PageCode {
+                page: 0x07,
+                code: 0x3B,
+            } => Ok(OsCode::KEY_F2),
+            PageCode {
+                page: 0x07,
+                code: 0x3C,
+            } => Ok(OsCode::KEY_F3),
+            PageCode {
+                page: 0x07,
+                code: 0x3D,
+            } => Ok(OsCode::KEY_F4),
+            PageCode {
+                page: 0x07,
+                code: 0x3E,
+            } => Ok(OsCode::KEY_F5),
+            PageCode {
+                page: 0x07,
+                code: 0x3F,
+            } => Ok(OsCode::KEY_F6),
+            PageCode {
+                page: 0x07,
+                code: 0x40,
+            } => Ok(OsCode::KEY_F7),
+            PageCode {
+                page: 0x07,
+                code: 0x41,
+            } => Ok(OsCode::KEY_F8),
+            PageCode {
+                page: 0x07,
+                code: 0x42,
+            } => Ok(OsCode::KEY_F9),
+            PageCode {
+                page: 0x07,
+                code: 0x43,
+            } => Ok(OsCode::KEY_F10),
+            PageCode {
+                page: 0x07,
+                code: 0x44,
+            } => Ok(OsCode::KEY_F11),
+            PageCode {
+                page: 0x07,
+                code: 0x45,
+            } => Ok(OsCode::KEY_F12),
+            PageCode {
+                page: 0x07,
+                code: 0x46,
+            } => Ok(OsCode::KEY_PRINT),
+            PageCode {
+                page: 0x07,
+                code: 0x47,
+            } => Ok(OsCode::KEY_SCROLLLOCK),
+            PageCode {
+                page: 0x07,
+                code: 0x48,
+            } => Ok(OsCode::KEY_PAUSE),
+            PageCode {
+                page: 0x07,
+                code: 0x49,
+            } => Ok(OsCode::KEY_INSERT),
+            PageCode {
+                page: 0x07,
+                code: 0x4A,
+            } => Ok(OsCode::KEY_HOME),
+            PageCode {
+                page: 0x07,
+                code: 0x4B,
+            } => Ok(OsCode::KEY_PAGEUP),
+            PageCode {
+                page: 0x07,
+                code: 0x4C,
+            } => Ok(OsCode::KEY_DELETE),
+            PageCode {
+                page: 0x07,
+                code: 0x4D,
+            } => Ok(OsCode::KEY_END),
+            PageCode {
+                page: 0x07,
+                code: 0x4E,
+            } => Ok(OsCode::KEY_PAGEDOWN),
+            PageCode {
+                page: 0x07,
+                code: 0x4F,
+            } => Ok(OsCode::KEY_RIGHT),
+            PageCode {
+                page: 0x07,
+                code: 0x50,
+            } => Ok(OsCode::KEY_LEFT),
+            PageCode {
+                page: 0x07,
+                code: 0x51,
+            } => Ok(OsCode::KEY_DOWN),
+            PageCode {
+                page: 0x07,
+                code: 0x52,
+            } => Ok(OsCode::KEY_UP),
+            PageCode {
+                page: 0x07,
+                code: 0x53,
+            } => Ok(OsCode::KEY_NUMLOCK),
+            PageCode {
+                page: 0x07,
+                code: 0x54,
+            } => Ok(OsCode::KEY_KPSLASH),
+            PageCode {
+                page: 0x07,
+                code: 0x55,
+            } => Ok(OsCode::KEY_KPASTERISK),
+            PageCode {
+                page: 0x07,
+                code: 0x56,
+            } => Ok(OsCode::KEY_KPMINUS),
+            PageCode {
+                page: 0x07,
+                code: 0x57,
+            } => Ok(OsCode::KEY_KPPLUS),
+            PageCode {
+                page: 0x07,
+                code: 0x58,
+            } => Ok(OsCode::KEY_KPENTER),
+            PageCode {
+                page: 0x07,
+                code: 0x59,
+            } => Ok(OsCode::KEY_KP1),
+            PageCode {
+                page: 0x07,
+                code: 0x5A,
+            } => Ok(OsCode::KEY_KP2),
+            PageCode {
+                page: 0x07,
+                code: 0x5B,
+            } => Ok(OsCode::KEY_KP3),
+            PageCode {
+                page: 0x07,
+                code: 0x5C,
+            } => Ok(OsCode::KEY_KP4),
+            PageCode {
+                page: 0x07,
+                code: 0x5D,
+            } => Ok(OsCode::KEY_KP5),
+            PageCode {
+                page: 0x07,
+                code: 0x5E,
+            } => Ok(OsCode::KEY_KP6),
+            PageCode {
+                page: 0x07,
+                code: 0x5F,
+            } => Ok(OsCode::KEY_KP7),
+            PageCode {
+                page: 0x07,
+                code: 0x60,
+            } => Ok(OsCode::KEY_KP8),
+            PageCode {
+                page: 0x07,
+                code: 0x61,
+            } => Ok(OsCode::KEY_KP9),
+            PageCode {
+                page: 0x07,
+                code: 0x62,
+            } => Ok(OsCode::KEY_KP0),
+            PageCode {
+                page: 0x07,
+                code: 0x63,
+            } => Ok(OsCode::KEY_KPDOT),
+            PageCode {
+                page: 0x07,
+                code: 0x64,
+            } => Ok(OsCode::KEY_102ND),
+            PageCode {
+                page: 0x07,
+                code: 0x65,
+            } => Ok(OsCode::KEY_COMPOSE),
+            PageCode {
+                page: 0x07,
+                code: 0x66,
+            } => Ok(OsCode::KEY_POWER),
+            PageCode {
+                page: 0x07,
+                code: 0x67,
+            } => Ok(OsCode::KEY_KPEQUAL),
+            PageCode {
+                page: 0x07,
+                code: 0x68,
+            } => Ok(OsCode::KEY_F13),
+            PageCode {
+                page: 0x07,
+                code: 0x69,
+            } => Ok(OsCode::KEY_F14),
+            PageCode {
+                page: 0x07,
+                code: 0x6A,
+            } => Ok(OsCode::KEY_F15),
+            PageCode {
+                page: 0x07,
+                code: 0x6B,
+            } => Ok(OsCode::KEY_F16),
+            PageCode {
+                page: 0x07,
+                code: 0x6C,
+            } => Ok(OsCode::KEY_F17),
+            PageCode {
+                page: 0x07,
+                code: 0x6D,
+            } => Ok(OsCode::KEY_F18),
+            PageCode {
+                page: 0x07,
+                code: 0x6E,
+            } => Ok(OsCode::KEY_F19),
+            PageCode {
+                page: 0x07,
+                code: 0x6F,
+            } => Ok(OsCode::KEY_F20),
+            PageCode {
+                page: 0x07,
+                code: 0x70,
+            } => Ok(OsCode::KEY_F21),
+            PageCode {
+                page: 0x07,
+                code: 0x71,
+            } => Ok(OsCode::KEY_F22),
+            PageCode {
+                page: 0x07,
+                code: 0x72,
+            } => Ok(OsCode::KEY_F23),
+            PageCode {
+                page: 0x07,
+                code: 0x73,
+            } => Ok(OsCode::KEY_F24),
+            PageCode {
+                page: 0x07,
+                code: 0x75,
+            } => Ok(OsCode::KEY_HELP),
+            PageCode {
+                page: 0x07,
+                code: 0x76,
+            } => Ok(OsCode::KEY_MENU),
+            PageCode {
+                page: 0x07,
+                code: 0x77,
+            } => Ok(OsCode::KEY_SELECT),
+            PageCode {
+                page: 0x07,
+                code: 0x78,
+            } => Ok(OsCode::KEY_STOP),
+            PageCode {
+                page: 0x07,
+                code: 0x79,
+            } => Ok(OsCode::KEY_AGAIN),
+            PageCode {
+                page: 0x07,
+                code: 0x7A,
+            } => Ok(OsCode::KEY_UNDO),
+            PageCode {
+                page: 0x07,
+                code: 0x7B,
+            } => Ok(OsCode::KEY_CUT),
+            PageCode {
+                page: 0x07,
+                code: 0x7C,
+            } => Ok(OsCode::KEY_COPY),
+            PageCode {
+                page: 0x07,
+                code: 0x7D,
+            } => Ok(OsCode::KEY_PASTE),
+            PageCode {
+                page: 0x07,
+                code: 0x7E,
+            } => Ok(OsCode::KEY_FIND),
+            PageCode {
+                page: 0x0C,
+                code: 0xE2,
+            } => Ok(OsCode::KEY_MUTE),
+            PageCode {
+                page: 0x0C,
+                code: 0xE9,
+            } => Ok(OsCode::KEY_VOLUMEUP),
+            PageCode {
+                page: 0x0C,
+                code: 0xEA,
+            } => Ok(OsCode::KEY_VOLUMEDOWN),
+            PageCode {
+                page: 0x0C,
+                code: 0xB8,
+            } => Ok(OsCode::KEY_EJECTCD),
+            PageCode {
+                page: 0x07,
+                code: 0x85,
+            } => Ok(OsCode::KEY_KPCOMMA),
+            PageCode {
+                page: 0x07,
+                code: 0x87,
+            } => Ok(OsCode::KEY_RO),
+            PageCode {
+                page: 0x07,
+                code: 0x88,
+            } => Ok(OsCode::KEY_KATAKANAHIRAGANA),
+            PageCode {
+                page: 0x07,
+                code: 0x89,
+            } => Ok(OsCode::KEY_YEN),
+            PageCode {
+                page: 0x07,
+                code: 0x8A,
+            } => Ok(OsCode::KEY_HENKAN),
+            PageCode {
+                page: 0x07,
+                code: 0x8B,
+            } => Ok(OsCode::KEY_MUHENKAN),
+            PageCode {
+                page: 0x07,
+                code: 0x8C,
+            } => Ok(OsCode::KEY_KPJPCOMMA),
+            PageCode {
+                page: 0x07,
+                code: 0x90,
+            } => Ok(OsCode::KEY_HANGEUL),
+            PageCode {
+                page: 0x07,
+                code: 0x91,
+            } => Ok(OsCode::KEY_HANJA),
+            PageCode {
+                page: 0x07,
+                code: 0x92,
+            } => Ok(OsCode::KEY_KATAKANA),
+            PageCode {
+                page: 0x07,
+                code: 0x93,
+            } => Ok(OsCode::KEY_HIRAGANA),
+            PageCode {
+                page: 0x07,
+                code: 0x94,
+            } => Ok(OsCode::KEY_ZENKAKUHANKAKU),
+            PageCode {
+                page: 0x07,
+                code: 0x99,
+            } => Ok(OsCode::KEY_ALTERASE),
+            PageCode {
+                page: 0x07,
+                code: 0x9B,
+            } => Ok(OsCode::KEY_CANCEL),
+            PageCode {
+                page: 0x07,
+                code: 0x9C,
+            } => Ok(OsCode::KEY_CLEAR),
+            PageCode {
+                page: 0x07,
+                code: 0xE0,
+            } => Ok(OsCode::KEY_LEFTCTRL),
+            PageCode {
+                page: 0x07,
+                code: 0xE1,
+            } => Ok(OsCode::KEY_LEFTSHIFT),
+            PageCode {
+                page: 0x07,
+                code: 0xE2,
+            } => Ok(OsCode::KEY_LEFTALT),
+            PageCode {
+                page: 0x07,
+                code: 0xE3,
+            } => Ok(OsCode::KEY_LEFTMETA),
+            PageCode {
+                page: 0x07,
+                code: 0xE4,
+            } => Ok(OsCode::KEY_RIGHTCTRL),
+            PageCode {
+                page: 0x07,
+                code: 0xE5,
+            } => Ok(OsCode::KEY_RIGHTSHIFT),
+            PageCode {
+                page: 0x07,
+                code: 0xE6,
+            } => Ok(OsCode::KEY_RIGHTALT),
+            PageCode {
+                page: 0x07,
+                code: 0xE7,
+            } => Ok(OsCode::KEY_RIGHTMETA),
+            PageCode {
+                page: 0x0C,
+                code: 0x32,
+            } => Ok(OsCode::KEY_SLEEP),
+            PageCode {
+                page: 0x0C,
+                code: 0xB3,
+            } => Ok(OsCode::KEY_FORWARD),
+            PageCode {
+                page: 0x0C,
+                code: 0xB4,
+            } => Ok(OsCode::KEY_REWIND),
+            PageCode {
+                page: 0x0C,
+                code: 0xB5,
+            } => Ok(OsCode::KEY_NEXTSONG),
+            PageCode {
+                page: 0x0C,
+                code: 0xB6,
+            } => Ok(OsCode::KEY_PREVIOUSSONG),
+            PageCode {
+                page: 0x0C,
+                code: 0xCD,
+            } => Ok(OsCode::KEY_PLAYPAUSE),
+            PageCode {
+                page: 0xFF,
+                code: 0x03,
+            } => Ok(OsCode::KEY_FN),
+            PageCode {
+                page: 0x0C,
+                code: 0x6F,
+            } => Ok(OsCode::KEY_BRIGHTNESSUP),
+            PageCode {
+                page: 0x0C,
+                code: 0x70,
+            } => Ok(OsCode::KEY_BRIGHTNESSDOWN),
+            PageCode {
+                page: 0xFF,
+                code: 0x07,
+            } => Ok(OsCode::KEY_KBDILLUMTOGGLE),
+            PageCode {
+                page: 0xFF,
+                code: 0x08,
+            } => Ok(OsCode::KEY_KBDILLUMUP),
+            PageCode {
+                page: 0xFF,
+                code: 0x09,
+            } => Ok(OsCode::KEY_KBDILLUMDOWN),
+            PageCode {
+                page: 0xFF,
+                code: 0x02,
+            } => Ok(OsCode::KEY_DASHBOARD),
+            PageCode {
+                page: 0xFF,
+                code: 0x01,
+            } => Ok(OsCode::KEY_SEARCH),
+            PageCode {
+                page: 0x0C,
+                code: 0x221,
+            } => Ok(OsCode::KEY_249),
+            PageCode {
+                page: 0x0C,
+                code: 0xCF,
+            } => Ok(OsCode::KEY_250),
+            PageCode {
+                page: 0x01,
+                code: 0x9B,
+            } => Ok(OsCode::KEY_251),
+            PageCode {
+                page: 0x0C,
+                code: 0x29F,
+            } => Ok(OsCode::KEY_252),
+            PageCode {
+                page: 0x0C,
+                code: 0x2A0,
+            } => Ok(OsCode::KEY_253),
+            _ => Err("PageCode unrecognized!"),
+        }
+    }
+}
+
+impl OsCode {
+    pub(super) const fn as_u16_macos(self) -> u16 {
+        self as u16
+    }
+    pub(super) const fn from_u16_macos(code: u16) -> Option<Self> {
+        match code {
+            0 => Some(OsCode::KEY_RESERVED),
+            1 => Some(OsCode::KEY_ESC),
+            2 => Some(OsCode::KEY_1),
+            3 => Some(OsCode::KEY_2),
+            4 => Some(OsCode::KEY_3),
+            5 => Some(OsCode::KEY_4),
+            6 => Some(OsCode::KEY_5),
+            7 => Some(OsCode::KEY_6),
+            8 => Some(OsCode::KEY_7),
+            9 => Some(OsCode::KEY_8),
+            10 => Some(OsCode::KEY_9),
+            11 => Some(OsCode::KEY_0),
+            12 => Some(OsCode::KEY_MINUS),
+            13 => Some(OsCode::KEY_EQUAL),
+            14 => Some(OsCode::KEY_BACKSPACE),
+            15 => Some(OsCode::KEY_TAB),
+            16 => Some(OsCode::KEY_Q),
+            17 => Some(OsCode::KEY_W),
+            18 => Some(OsCode::KEY_E),
+            19 => Some(OsCode::KEY_R),
+            20 => Some(OsCode::KEY_T),
+            21 => Some(OsCode::KEY_Y),
+            22 => Some(OsCode::KEY_U),
+            23 => Some(OsCode::KEY_I),
+            24 => Some(OsCode::KEY_O),
+            25 => Some(OsCode::KEY_P),
+            26 => Some(OsCode::KEY_LEFTBRACE),
+            27 => Some(OsCode::KEY_RIGHTBRACE),
+            28 => Some(OsCode::KEY_ENTER),
+            29 => Some(OsCode::KEY_LEFTCTRL),
+            30 => Some(OsCode::KEY_A),
+            31 => Some(OsCode::KEY_S),
+            32 => Some(OsCode::KEY_D),
+            33 => Some(OsCode::KEY_F),
+            34 => Some(OsCode::KEY_G),
+            35 => Some(OsCode::KEY_H),
+            36 => Some(OsCode::KEY_J),
+            37 => Some(OsCode::KEY_K),
+            38 => Some(OsCode::KEY_L),
+            39 => Some(OsCode::KEY_SEMICOLON),
+            40 => Some(OsCode::KEY_APOSTROPHE),
+            41 => Some(OsCode::KEY_GRAVE),
+            42 => Some(OsCode::KEY_LEFTSHIFT),
+            43 => Some(OsCode::KEY_BACKSLASH),
+            44 => Some(OsCode::KEY_Z),
+            45 => Some(OsCode::KEY_X),
+            46 => Some(OsCode::KEY_C),
+            47 => Some(OsCode::KEY_V),
+            48 => Some(OsCode::KEY_B),
+            49 => Some(OsCode::KEY_N),
+            50 => Some(OsCode::KEY_M),
+            51 => Some(OsCode::KEY_COMMA),
+            52 => Some(OsCode::KEY_DOT),
+            53 => Some(OsCode::KEY_SLASH),
+            54 => Some(OsCode::KEY_RIGHTSHIFT),
+            55 => Some(OsCode::KEY_KPASTERISK),
+            56 => Some(OsCode::KEY_LEFTALT),
+            57 => Some(OsCode::KEY_SPACE),
+            58 => Some(OsCode::KEY_CAPSLOCK),
+            59 => Some(OsCode::KEY_F1),
+            60 => Some(OsCode::KEY_F2),
+            61 => Some(OsCode::KEY_F3),
+            62 => Some(OsCode::KEY_F4),
+            63 => Some(OsCode::KEY_F5),
+            64 => Some(OsCode::KEY_F6),
+            65 => Some(OsCode::KEY_F7),
+            66 => Some(OsCode::KEY_F8),
+            67 => Some(OsCode::KEY_F9),
+            68 => Some(OsCode::KEY_F10),
+            69 => Some(OsCode::KEY_NUMLOCK),
+            70 => Some(OsCode::KEY_SCROLLLOCK),
+            71 => Some(OsCode::KEY_KP7),
+            72 => Some(OsCode::KEY_KP8),
+            73 => Some(OsCode::KEY_KP9),
+            74 => Some(OsCode::KEY_KPMINUS),
+            75 => Some(OsCode::KEY_KP4),
+            76 => Some(OsCode::KEY_KP5),
+            77 => Some(OsCode::KEY_KP6),
+            78 => Some(OsCode::KEY_KPPLUS),
+            79 => Some(OsCode::KEY_KP1),
+            80 => Some(OsCode::KEY_KP2),
+            81 => Some(OsCode::KEY_KP3),
+            82 => Some(OsCode::KEY_KP0),
+            83 => Some(OsCode::KEY_KPDOT),
+            84 => Some(OsCode::KEY_84),
+            85 => Some(OsCode::KEY_ZENKAKUHANKAKU),
+            86 => Some(OsCode::KEY_102ND),
+            87 => Some(OsCode::KEY_F11),
+            88 => Some(OsCode::KEY_F12),
+            89 => Some(OsCode::KEY_RO),
+            90 => Some(OsCode::KEY_KATAKANA),
+            91 => Some(OsCode::KEY_HIRAGANA),
+            92 => Some(OsCode::KEY_HENKAN),
+            93 => Some(OsCode::KEY_KATAKANAHIRAGANA),
+            94 => Some(OsCode::KEY_MUHENKAN),
+            95 => Some(OsCode::KEY_KPJPCOMMA),
+            96 => Some(OsCode::KEY_KPENTER),
+            97 => Some(OsCode::KEY_RIGHTCTRL),
+            98 => Some(OsCode::KEY_KPSLASH),
+            99 => Some(OsCode::KEY_SYSRQ),
+            100 => Some(OsCode::KEY_RIGHTALT),
+            101 => Some(OsCode::KEY_LINEFEED),
+            102 => Some(OsCode::KEY_HOME),
+            103 => Some(OsCode::KEY_UP),
+            104 => Some(OsCode::KEY_PAGEUP),
+            105 => Some(OsCode::KEY_LEFT),
+            106 => Some(OsCode::KEY_RIGHT),
+            107 => Some(OsCode::KEY_END),
+            108 => Some(OsCode::KEY_DOWN),
+            109 => Some(OsCode::KEY_PAGEDOWN),
+            110 => Some(OsCode::KEY_INSERT),
+            111 => Some(OsCode::KEY_DELETE),
+            112 => Some(OsCode::KEY_MACRO),
+            113 => Some(OsCode::KEY_MUTE),
+            114 => Some(OsCode::KEY_VOLUMEDOWN),
+            115 => Some(OsCode::KEY_VOLUMEUP),
+            116 => Some(OsCode::KEY_POWER),
+            117 => Some(OsCode::KEY_KPEQUAL),
+            118 => Some(OsCode::KEY_KPPLUSMINUS),
+            119 => Some(OsCode::KEY_PAUSE),
+            120 => Some(OsCode::KEY_SCALE),
+            121 => Some(OsCode::KEY_KPCOMMA),
+            122 => Some(OsCode::KEY_HANGEUL),
+            123 => Some(OsCode::KEY_HANJA),
+            124 => Some(OsCode::KEY_YEN),
+            125 => Some(OsCode::KEY_LEFTMETA),
+            126 => Some(OsCode::KEY_RIGHTMETA),
+            127 => Some(OsCode::KEY_COMPOSE),
+            128 => Some(OsCode::KEY_STOP),
+            129 => Some(OsCode::KEY_AGAIN),
+            130 => Some(OsCode::KEY_PROPS),
+            131 => Some(OsCode::KEY_UNDO),
+            132 => Some(OsCode::KEY_FRONT),
+            133 => Some(OsCode::KEY_COPY),
+            134 => Some(OsCode::KEY_OPEN),
+            135 => Some(OsCode::KEY_PASTE),
+            136 => Some(OsCode::KEY_FIND),
+            137 => Some(OsCode::KEY_CUT),
+            138 => Some(OsCode::KEY_HELP),
+            139 => Some(OsCode::KEY_MENU),
+            140 => Some(OsCode::KEY_CALC),
+            141 => Some(OsCode::KEY_SETUP),
+            142 => Some(OsCode::KEY_SLEEP),
+            143 => Some(OsCode::KEY_WAKEUP),
+            144 => Some(OsCode::KEY_FILE),
+            145 => Some(OsCode::KEY_SENDFILE),
+            146 => Some(OsCode::KEY_DELETEFILE),
+            147 => Some(OsCode::KEY_XFER),
+            148 => Some(OsCode::KEY_PROG1),
+            149 => Some(OsCode::KEY_PROG2),
+            150 => Some(OsCode::KEY_WWW),
+            151 => Some(OsCode::KEY_MSDOS),
+            152 => Some(OsCode::KEY_COFFEE),
+            153 => Some(OsCode::KEY_ROTATE_DISPLAY),
+            154 => Some(OsCode::KEY_CYCLEWINDOWS),
+            155 => Some(OsCode::KEY_MAIL),
+            156 => Some(OsCode::KEY_BOOKMARKS),
+            157 => Some(OsCode::KEY_COMPUTER),
+            158 => Some(OsCode::KEY_BACK),
+            159 => Some(OsCode::KEY_FORWARD),
+            160 => Some(OsCode::KEY_CLOSECD),
+            161 => Some(OsCode::KEY_EJECTCD),
+            162 => Some(OsCode::KEY_EJECTCLOSECD),
+            163 => Some(OsCode::KEY_NEXTSONG),
+            164 => Some(OsCode::KEY_PLAYPAUSE),
+            165 => Some(OsCode::KEY_PREVIOUSSONG),
+            166 => Some(OsCode::KEY_STOPCD),
+            167 => Some(OsCode::KEY_RECORD),
+            168 => Some(OsCode::KEY_REWIND),
+            169 => Some(OsCode::KEY_PHONE),
+            170 => Some(OsCode::KEY_ISO),
+            171 => Some(OsCode::KEY_CONFIG),
+            172 => Some(OsCode::KEY_HOMEPAGE),
+            173 => Some(OsCode::KEY_REFRESH),
+            174 => Some(OsCode::KEY_EXIT),
+            175 => Some(OsCode::KEY_MOVE),
+            176 => Some(OsCode::KEY_EDIT),
+            177 => Some(OsCode::KEY_SCROLLUP),
+            178 => Some(OsCode::KEY_SCROLLDOWN),
+            179 => Some(OsCode::KEY_KPLEFTPAREN),
+            180 => Some(OsCode::KEY_KPRIGHTPAREN),
+            181 => Some(OsCode::KEY_NEW),
+            182 => Some(OsCode::KEY_REDO),
+            183 => Some(OsCode::KEY_F13),
+            184 => Some(OsCode::KEY_F14),
+            185 => Some(OsCode::KEY_F15),
+            186 => Some(OsCode::KEY_F16),
+            187 => Some(OsCode::KEY_F17),
+            188 => Some(OsCode::KEY_F18),
+            189 => Some(OsCode::KEY_F19),
+            190 => Some(OsCode::KEY_F20),
+            191 => Some(OsCode::KEY_F21),
+            192 => Some(OsCode::KEY_F22),
+            193 => Some(OsCode::KEY_F23),
+            194 => Some(OsCode::KEY_F24),
+            195 => Some(OsCode::KEY_195),
+            196 => Some(OsCode::KEY_196),
+            197 => Some(OsCode::KEY_197),
+            198 => Some(OsCode::KEY_198),
+            199 => Some(OsCode::KEY_199),
+            200 => Some(OsCode::KEY_PLAYCD),
+            201 => Some(OsCode::KEY_PAUSECD),
+            202 => Some(OsCode::KEY_PROG3),
+            203 => Some(OsCode::KEY_PROG4),
+            204 => Some(OsCode::KEY_DASHBOARD),
+            205 => Some(OsCode::KEY_SUSPEND),
+            206 => Some(OsCode::KEY_CLOSE),
+            207 => Some(OsCode::KEY_PLAY),
+            208 => Some(OsCode::KEY_FASTFORWARD),
+            209 => Some(OsCode::KEY_BASSBOOST),
+            210 => Some(OsCode::KEY_PRINT),
+            211 => Some(OsCode::KEY_HP),
+            212 => Some(OsCode::KEY_CAMERA),
+            213 => Some(OsCode::KEY_SOUND),
+            214 => Some(OsCode::KEY_QUESTION),
+            215 => Some(OsCode::KEY_EMAIL),
+            216 => Some(OsCode::KEY_CHAT),
+            217 => Some(OsCode::KEY_SEARCH),
+            218 => Some(OsCode::KEY_CONNECT),
+            219 => Some(OsCode::KEY_FINANCE),
+            220 => Some(OsCode::KEY_SPORT),
+            221 => Some(OsCode::KEY_SHOP),
+            222 => Some(OsCode::KEY_ALTERASE),
+            223 => Some(OsCode::KEY_CANCEL),
+            224 => Some(OsCode::KEY_BRIGHTNESSDOWN),
+            225 => Some(OsCode::KEY_BRIGHTNESSUP),
+            226 => Some(OsCode::KEY_MEDIA),
+            227 => Some(OsCode::KEY_SWITCHVIDEOMODE),
+            228 => Some(OsCode::KEY_KBDILLUMTOGGLE),
+            229 => Some(OsCode::KEY_KBDILLUMDOWN),
+            230 => Some(OsCode::KEY_KBDILLUMUP),
+            231 => Some(OsCode::KEY_SEND),
+            232 => Some(OsCode::KEY_REPLY),
+            233 => Some(OsCode::KEY_FORWARDMAIL),
+            234 => Some(OsCode::KEY_SAVE),
+            235 => Some(OsCode::KEY_DOCUMENTS),
+            236 => Some(OsCode::KEY_BATTERY),
+            237 => Some(OsCode::KEY_BLUETOOTH),
+            238 => Some(OsCode::KEY_WLAN),
+            239 => Some(OsCode::KEY_UWB),
+            240 => Some(OsCode::KEY_UNKNOWN),
+            241 => Some(OsCode::KEY_VIDEO_NEXT),
+            242 => Some(OsCode::KEY_VIDEO_PREV),
+            243 => Some(OsCode::KEY_BRIGHTNESS_CYCLE),
+            244 => Some(OsCode::KEY_BRIGHTNESS_AUTO),
+            245 => Some(OsCode::KEY_DISPLAY_OFF),
+            246 => Some(OsCode::KEY_WWAN),
+            247 => Some(OsCode::KEY_RFKILL),
+            248 => Some(OsCode::KEY_MICMUTE),
+            249 => Some(OsCode::KEY_249),
+            250 => Some(OsCode::KEY_250),
+            251 => Some(OsCode::KEY_251),
+            252 => Some(OsCode::KEY_252),
+            253 => Some(OsCode::KEY_253),
+            254 => Some(OsCode::KEY_254),
+            255 => Some(OsCode::KEY_255),
+            256 => Some(OsCode::BTN_0),
+            257 => Some(OsCode::BTN_1),
+            258 => Some(OsCode::BTN_2),
+            259 => Some(OsCode::BTN_3),
+            260 => Some(OsCode::BTN_4),
+            261 => Some(OsCode::BTN_5),
+            262 => Some(OsCode::BTN_6),
+            263 => Some(OsCode::BTN_7),
+            264 => Some(OsCode::BTN_8),
+            265 => Some(OsCode::BTN_9),
+            266 => Some(OsCode::KEY_266),
+            267 => Some(OsCode::KEY_267),
+            268 => Some(OsCode::KEY_268),
+            269 => Some(OsCode::KEY_269),
+            270 => Some(OsCode::KEY_270),
+            271 => Some(OsCode::KEY_271),
+            272 => Some(OsCode::BTN_LEFT),
+            273 => Some(OsCode::BTN_RIGHT),
+            274 => Some(OsCode::BTN_MIDDLE),
+            275 => Some(OsCode::BTN_SIDE),
+            276 => Some(OsCode::BTN_EXTRA),
+            277 => Some(OsCode::BTN_FORWARD),
+            278 => Some(OsCode::BTN_BACK),
+            279 => Some(OsCode::BTN_TASK),
+            280 => Some(OsCode::KEY_280),
+            281 => Some(OsCode::KEY_281),
+            282 => Some(OsCode::KEY_282),
+            283 => Some(OsCode::KEY_283),
+            284 => Some(OsCode::KEY_284),
+            285 => Some(OsCode::KEY_285),
+            286 => Some(OsCode::KEY_286),
+            287 => Some(OsCode::KEY_287),
+            288 => Some(OsCode::BTN_TRIGGER),
+            289 => Some(OsCode::BTN_THUMB),
+            290 => Some(OsCode::BTN_THUMB2),
+            291 => Some(OsCode::BTN_TOP),
+            292 => Some(OsCode::BTN_TOP2),
+            293 => Some(OsCode::BTN_PINKIE),
+            294 => Some(OsCode::BTN_BASE),
+            295 => Some(OsCode::BTN_BASE2),
+            296 => Some(OsCode::BTN_BASE3),
+            297 => Some(OsCode::BTN_BASE4),
+            298 => Some(OsCode::BTN_BASE5),
+            299 => Some(OsCode::BTN_BASE6),
+            300 => Some(OsCode::KEY_300),
+            301 => Some(OsCode::KEY_301),
+            302 => Some(OsCode::KEY_302),
+            303 => Some(OsCode::BTN_DEAD),
+            304 => Some(OsCode::BTN_SOUTH),
+            305 => Some(OsCode::BTN_EAST),
+            306 => Some(OsCode::BTN_C),
+            307 => Some(OsCode::BTN_NORTH),
+            308 => Some(OsCode::BTN_WEST),
+            309 => Some(OsCode::BTN_Z),
+            310 => Some(OsCode::BTN_TL),
+            311 => Some(OsCode::BTN_TR),
+            312 => Some(OsCode::BTN_TL2),
+            313 => Some(OsCode::BTN_TR2),
+            314 => Some(OsCode::BTN_SELECT),
+            315 => Some(OsCode::BTN_START),
+            316 => Some(OsCode::BTN_MODE),
+            317 => Some(OsCode::BTN_THUMBL),
+            318 => Some(OsCode::BTN_THUMBR),
+            319 => Some(OsCode::KEY_319),
+            320 => Some(OsCode::BTN_TOOL_PEN),
+            321 => Some(OsCode::BTN_TOOL_RUBBER),
+            322 => Some(OsCode::BTN_TOOL_BRUSH),
+            323 => Some(OsCode::BTN_TOOL_PENCIL),
+            324 => Some(OsCode::BTN_TOOL_AIRBRUSH),
+            325 => Some(OsCode::BTN_TOOL_FINGER),
+            326 => Some(OsCode::BTN_TOOL_MOUSE),
+            327 => Some(OsCode::BTN_TOOL_LENS),
+            328 => Some(OsCode::BTN_TOOL_QUINTTAP),
+            329 => Some(OsCode::BTN_STYLUS3),
+            330 => Some(OsCode::BTN_TOUCH),
+            331 => Some(OsCode::BTN_STYLUS),
+            332 => Some(OsCode::BTN_STYLUS2),
+            333 => Some(OsCode::BTN_TOOL_DOUBLETAP),
+            334 => Some(OsCode::BTN_TOOL_TRIPLETAP),
+            335 => Some(OsCode::BTN_TOOL_QUADTAP),
+            336 => Some(OsCode::BTN_GEAR_DOWN),
+            337 => Some(OsCode::BTN_GEAR_UP),
+            338 => Some(OsCode::KEY_338),
+            339 => Some(OsCode::KEY_339),
+            340 => Some(OsCode::KEY_340),
+            341 => Some(OsCode::KEY_341),
+            342 => Some(OsCode::KEY_342),
+            343 => Some(OsCode::KEY_343),
+            344 => Some(OsCode::KEY_344),
+            345 => Some(OsCode::KEY_345),
+            346 => Some(OsCode::KEY_346),
+            347 => Some(OsCode::KEY_347),
+            348 => Some(OsCode::KEY_348),
+            349 => Some(OsCode::KEY_349),
+            350 => Some(OsCode::KEY_350),
+            351 => Some(OsCode::KEY_351),
+            352 => Some(OsCode::KEY_OK),
+            353 => Some(OsCode::KEY_SELECT),
+            354 => Some(OsCode::KEY_GOTO),
+            355 => Some(OsCode::KEY_CLEAR),
+            356 => Some(OsCode::KEY_POWER2),
+            357 => Some(OsCode::KEY_OPTION),
+            358 => Some(OsCode::KEY_INFO),
+            359 => Some(OsCode::KEY_TIME),
+            360 => Some(OsCode::KEY_VENDOR),
+            361 => Some(OsCode::KEY_ARCHIVE),
+            362 => Some(OsCode::KEY_PROGRAM),
+            363 => Some(OsCode::KEY_CHANNEL),
+            364 => Some(OsCode::KEY_FAVORITES),
+            365 => Some(OsCode::KEY_EPG),
+            366 => Some(OsCode::KEY_PVR),
+            367 => Some(OsCode::KEY_MHP),
+            368 => Some(OsCode::KEY_LANGUAGE),
+            369 => Some(OsCode::KEY_TITLE),
+            370 => Some(OsCode::KEY_SUBTITLE),
+            371 => Some(OsCode::KEY_ANGLE),
+            372 => Some(OsCode::KEY_FULL_SCREEN),
+            373 => Some(OsCode::KEY_MODE),
+            374 => Some(OsCode::KEY_KEYBOARD),
+            375 => Some(OsCode::KEY_ASPECT_RATIO),
+            376 => Some(OsCode::KEY_PC),
+            377 => Some(OsCode::KEY_TV),
+            378 => Some(OsCode::KEY_TV2),
+            379 => Some(OsCode::KEY_VCR),
+            380 => Some(OsCode::KEY_VCR2),
+            381 => Some(OsCode::KEY_SAT),
+            382 => Some(OsCode::KEY_SAT2),
+            383 => Some(OsCode::KEY_CD),
+            384 => Some(OsCode::KEY_TAPE),
+            385 => Some(OsCode::KEY_RADIO),
+            386 => Some(OsCode::KEY_TUNER),
+            387 => Some(OsCode::KEY_PLAYER),
+            388 => Some(OsCode::KEY_TEXT),
+            389 => Some(OsCode::KEY_DVD),
+            390 => Some(OsCode::KEY_AUX),
+            391 => Some(OsCode::KEY_MP3),
+            392 => Some(OsCode::KEY_AUDIO),
+            393 => Some(OsCode::KEY_VIDEO),
+            394 => Some(OsCode::KEY_DIRECTORY),
+            395 => Some(OsCode::KEY_LIST),
+            396 => Some(OsCode::KEY_MEMO),
+            397 => Some(OsCode::KEY_CALENDAR),
+            398 => Some(OsCode::KEY_RED),
+            399 => Some(OsCode::KEY_GREEN),
+            400 => Some(OsCode::KEY_YELLOW),
+            401 => Some(OsCode::KEY_BLUE),
+            402 => Some(OsCode::KEY_CHANNELUP),
+            403 => Some(OsCode::KEY_CHANNELDOWN),
+            404 => Some(OsCode::KEY_FIRST),
+            405 => Some(OsCode::KEY_LAST),
+            406 => Some(OsCode::KEY_AB),
+            407 => Some(OsCode::KEY_NEXT),
+            408 => Some(OsCode::KEY_RESTART),
+            409 => Some(OsCode::KEY_SLOW),
+            410 => Some(OsCode::KEY_SHUFFLE),
+            411 => Some(OsCode::KEY_BREAK),
+            412 => Some(OsCode::KEY_PREVIOUS),
+            413 => Some(OsCode::KEY_DIGITS),
+            414 => Some(OsCode::KEY_TEEN),
+            415 => Some(OsCode::KEY_TWEN),
+            416 => Some(OsCode::KEY_VIDEOPHONE),
+            417 => Some(OsCode::KEY_GAMES),
+            418 => Some(OsCode::KEY_ZOOMIN),
+            419 => Some(OsCode::KEY_ZOOMOUT),
+            420 => Some(OsCode::KEY_ZOOMRESET),
+            421 => Some(OsCode::KEY_WORDPROCESSOR),
+            422 => Some(OsCode::KEY_EDITOR),
+            423 => Some(OsCode::KEY_SPREADSHEET),
+            424 => Some(OsCode::KEY_GRAPHICSEDITOR),
+            425 => Some(OsCode::KEY_PRESENTATION),
+            426 => Some(OsCode::KEY_DATABASE),
+            427 => Some(OsCode::KEY_NEWS),
+            428 => Some(OsCode::KEY_VOICEMAIL),
+            429 => Some(OsCode::KEY_ADDRESSBOOK),
+            430 => Some(OsCode::KEY_MESSENGER),
+            431 => Some(OsCode::KEY_DISPLAYTOGGLE),
+            432 => Some(OsCode::KEY_SPELLCHECK),
+            433 => Some(OsCode::KEY_LOGOFF),
+            434 => Some(OsCode::KEY_DOLLAR),
+            435 => Some(OsCode::KEY_EURO),
+            436 => Some(OsCode::KEY_FRAMEBACK),
+            437 => Some(OsCode::KEY_FRAMEFORWARD),
+            438 => Some(OsCode::KEY_CONTEXT_MENU),
+            439 => Some(OsCode::KEY_MEDIA_REPEAT),
+            440 => Some(OsCode::KEY_10CHANNELSUP),
+            441 => Some(OsCode::KEY_10CHANNELSDOWN),
+            442 => Some(OsCode::KEY_IMAGES),
+            443 => Some(OsCode::KEY_443),
+            444 => Some(OsCode::KEY_444),
+            445 => Some(OsCode::KEY_445),
+            446 => Some(OsCode::KEY_446),
+            447 => Some(OsCode::KEY_447),
+            448 => Some(OsCode::KEY_DEL_EOL),
+            449 => Some(OsCode::KEY_DEL_EOS),
+            450 => Some(OsCode::KEY_INS_LINE),
+            451 => Some(OsCode::KEY_DEL_LINE),
+            452 => Some(OsCode::KEY_452),
+            453 => Some(OsCode::KEY_453),
+            454 => Some(OsCode::KEY_454),
+            455 => Some(OsCode::KEY_455),
+            456 => Some(OsCode::KEY_456),
+            457 => Some(OsCode::KEY_457),
+            458 => Some(OsCode::KEY_458),
+            459 => Some(OsCode::KEY_459),
+            460 => Some(OsCode::KEY_460),
+            461 => Some(OsCode::KEY_461),
+            462 => Some(OsCode::KEY_462),
+            463 => Some(OsCode::KEY_463),
+            464 => Some(OsCode::KEY_FN),
+            465 => Some(OsCode::KEY_FN_ESC),
+            466 => Some(OsCode::KEY_FN_F1),
+            467 => Some(OsCode::KEY_FN_F2),
+            468 => Some(OsCode::KEY_FN_F3),
+            469 => Some(OsCode::KEY_FN_F4),
+            470 => Some(OsCode::KEY_FN_F5),
+            471 => Some(OsCode::KEY_FN_F6),
+            472 => Some(OsCode::KEY_FN_F7),
+            473 => Some(OsCode::KEY_FN_F8),
+            474 => Some(OsCode::KEY_FN_F9),
+            475 => Some(OsCode::KEY_FN_F10),
+            476 => Some(OsCode::KEY_FN_F11),
+            477 => Some(OsCode::KEY_FN_F12),
+            478 => Some(OsCode::KEY_FN_1),
+            479 => Some(OsCode::KEY_FN_2),
+            480 => Some(OsCode::KEY_FN_D),
+            481 => Some(OsCode::KEY_FN_E),
+            482 => Some(OsCode::KEY_FN_F),
+            483 => Some(OsCode::KEY_FN_S),
+            484 => Some(OsCode::KEY_FN_B),
+            485 => Some(OsCode::KEY_485),
+            486 => Some(OsCode::KEY_486),
+            487 => Some(OsCode::KEY_487),
+            488 => Some(OsCode::KEY_488),
+            489 => Some(OsCode::KEY_489),
+            490 => Some(OsCode::KEY_490),
+            491 => Some(OsCode::KEY_491),
+            492 => Some(OsCode::KEY_492),
+            493 => Some(OsCode::KEY_493),
+            494 => Some(OsCode::KEY_494),
+            495 => Some(OsCode::KEY_495),
+            496 => Some(OsCode::KEY_496),
+            497 => Some(OsCode::KEY_BRL_DOT1),
+            498 => Some(OsCode::KEY_BRL_DOT2),
+            499 => Some(OsCode::KEY_BRL_DOT3),
+            500 => Some(OsCode::KEY_BRL_DOT4),
+            501 => Some(OsCode::KEY_BRL_DOT5),
+            502 => Some(OsCode::KEY_BRL_DOT6),
+            503 => Some(OsCode::KEY_BRL_DOT7),
+            504 => Some(OsCode::KEY_BRL_DOT8),
+            505 => Some(OsCode::KEY_BRL_DOT9),
+            506 => Some(OsCode::KEY_BRL_DOT10),
+            507 => Some(OsCode::KEY_507),
+            508 => Some(OsCode::KEY_508),
+            509 => Some(OsCode::KEY_509),
+            510 => Some(OsCode::KEY_510),
+            511 => Some(OsCode::KEY_511),
+            512 => Some(OsCode::KEY_NUMERIC_0),
+            513 => Some(OsCode::KEY_NUMERIC_1),
+            514 => Some(OsCode::KEY_NUMERIC_2),
+            515 => Some(OsCode::KEY_NUMERIC_3),
+            516 => Some(OsCode::KEY_NUMERIC_4),
+            517 => Some(OsCode::KEY_NUMERIC_5),
+            518 => Some(OsCode::KEY_NUMERIC_6),
+            519 => Some(OsCode::KEY_NUMERIC_7),
+            520 => Some(OsCode::KEY_NUMERIC_8),
+            521 => Some(OsCode::KEY_NUMERIC_9),
+            522 => Some(OsCode::KEY_NUMERIC_STAR),
+            523 => Some(OsCode::KEY_NUMERIC_POUND),
+            524 => Some(OsCode::KEY_NUMERIC_A),
+            525 => Some(OsCode::KEY_NUMERIC_B),
+            526 => Some(OsCode::KEY_NUMERIC_C),
+            527 => Some(OsCode::KEY_NUMERIC_D),
+            528 => Some(OsCode::KEY_CAMERA_FOCUS),
+            529 => Some(OsCode::KEY_WPS_BUTTON),
+            530 => Some(OsCode::KEY_TOUCHPAD_TOGGLE),
+            531 => Some(OsCode::KEY_TOUCHPAD_ON),
+            532 => Some(OsCode::KEY_TOUCHPAD_OFF),
+            533 => Some(OsCode::KEY_CAMERA_ZOOMIN),
+            534 => Some(OsCode::KEY_CAMERA_ZOOMOUT),
+            535 => Some(OsCode::KEY_CAMERA_UP),
+            536 => Some(OsCode::KEY_CAMERA_DOWN),
+            537 => Some(OsCode::KEY_CAMERA_LEFT),
+            538 => Some(OsCode::KEY_CAMERA_RIGHT),
+            539 => Some(OsCode::KEY_ATTENDANT_ON),
+            540 => Some(OsCode::KEY_ATTENDANT_OFF),
+            541 => Some(OsCode::KEY_ATTENDANT_TOGGLE),
+            542 => Some(OsCode::KEY_LIGHTS_TOGGLE),
+            543 => Some(OsCode::KEY_543),
+            544 => Some(OsCode::BTN_DPAD_UP),
+            545 => Some(OsCode::BTN_DPAD_DOWN),
+            546 => Some(OsCode::BTN_DPAD_LEFT),
+            547 => Some(OsCode::BTN_DPAD_RIGHT),
+            548 => Some(OsCode::KEY_548),
+            549 => Some(OsCode::KEY_549),
+            550 => Some(OsCode::KEY_550),
+            551 => Some(OsCode::KEY_551),
+            552 => Some(OsCode::KEY_552),
+            553 => Some(OsCode::KEY_553),
+            554 => Some(OsCode::KEY_554),
+            555 => Some(OsCode::KEY_555),
+            556 => Some(OsCode::KEY_556),
+            557 => Some(OsCode::KEY_557),
+            558 => Some(OsCode::KEY_558),
+            559 => Some(OsCode::KEY_559),
+            560 => Some(OsCode::KEY_ALS_TOGGLE),
+            561 => Some(OsCode::KEY_ROTATE_LOCK_TOGGLE),
+            562 => Some(OsCode::KEY_562),
+            563 => Some(OsCode::KEY_563),
+            564 => Some(OsCode::KEY_564),
+            565 => Some(OsCode::KEY_565),
+            566 => Some(OsCode::KEY_566),
+            567 => Some(OsCode::KEY_567),
+            568 => Some(OsCode::KEY_568),
+            569 => Some(OsCode::KEY_569),
+            570 => Some(OsCode::KEY_570),
+            571 => Some(OsCode::KEY_571),
+            572 => Some(OsCode::KEY_572),
+            573 => Some(OsCode::KEY_573),
+            574 => Some(OsCode::KEY_574),
+            575 => Some(OsCode::KEY_575),
+            576 => Some(OsCode::KEY_BUTTONCONFIG),
+            577 => Some(OsCode::KEY_TASKMANAGER),
+            578 => Some(OsCode::KEY_JOURNAL),
+            579 => Some(OsCode::KEY_CONTROLPANEL),
+            580 => Some(OsCode::KEY_APPSELECT),
+            581 => Some(OsCode::KEY_SCREENSAVER),
+            582 => Some(OsCode::KEY_VOICECOMMAND),
+            583 => Some(OsCode::KEY_ASSISTANT),
+            584 => Some(OsCode::KEY_KBD_LAYOUT_NEXT),
+            585 => Some(OsCode::KEY_585),
+            586 => Some(OsCode::KEY_586),
+            587 => Some(OsCode::KEY_587),
+            588 => Some(OsCode::KEY_588),
+            589 => Some(OsCode::KEY_589),
+            590 => Some(OsCode::KEY_590),
+            591 => Some(OsCode::KEY_591),
+            592 => Some(OsCode::KEY_BRIGHTNESS_MIN),
+            593 => Some(OsCode::KEY_BRIGHTNESS_MAX),
+            594 => Some(OsCode::KEY_594),
+            595 => Some(OsCode::KEY_595),
+            596 => Some(OsCode::KEY_596),
+            597 => Some(OsCode::KEY_597),
+            598 => Some(OsCode::KEY_598),
+            599 => Some(OsCode::KEY_599),
+            600 => Some(OsCode::KEY_600),
+            601 => Some(OsCode::KEY_601),
+            602 => Some(OsCode::KEY_602),
+            603 => Some(OsCode::KEY_603),
+            604 => Some(OsCode::KEY_604),
+            605 => Some(OsCode::KEY_605),
+            606 => Some(OsCode::KEY_606),
+            607 => Some(OsCode::KEY_607),
+            608 => Some(OsCode::KEY_KBDINPUTASSIST_PREV),
+            609 => Some(OsCode::KEY_KBDINPUTASSIST_NEXT),
+            610 => Some(OsCode::KEY_KBDINPUTASSIST_PREVGROUP),
+            611 => Some(OsCode::KEY_KBDINPUTASSIST_NEXTGROUP),
+            612 => Some(OsCode::KEY_KBDINPUTASSIST_ACCEPT),
+            613 => Some(OsCode::KEY_KBDINPUTASSIST_CANCEL),
+            614 => Some(OsCode::KEY_RIGHT_UP),
+            615 => Some(OsCode::KEY_RIGHT_DOWN),
+            616 => Some(OsCode::KEY_LEFT_UP),
+            617 => Some(OsCode::KEY_LEFT_DOWN),
+            618 => Some(OsCode::KEY_ROOT_MENU),
+            619 => Some(OsCode::KEY_MEDIA_TOP_MENU),
+            620 => Some(OsCode::KEY_NUMERIC_11),
+            621 => Some(OsCode::KEY_NUMERIC_12),
+            622 => Some(OsCode::KEY_AUDIO_DESC),
+            623 => Some(OsCode::KEY_3D_MODE),
+            624 => Some(OsCode::KEY_NEXT_FAVORITE),
+            625 => Some(OsCode::KEY_STOP_RECORD),
+            626 => Some(OsCode::KEY_PAUSE_RECORD),
+            627 => Some(OsCode::KEY_VOD),
+            628 => Some(OsCode::KEY_UNMUTE),
+            629 => Some(OsCode::KEY_FASTREVERSE),
+            630 => Some(OsCode::KEY_SLOWREVERSE),
+            631 => Some(OsCode::KEY_DATA),
+            632 => Some(OsCode::KEY_ONSCREEN_KEYBOARD),
+            633 => Some(OsCode::KEY_633),
+            634 => Some(OsCode::KEY_634),
+            635 => Some(OsCode::KEY_635),
+            636 => Some(OsCode::KEY_636),
+            637 => Some(OsCode::KEY_637),
+            638 => Some(OsCode::KEY_638),
+            639 => Some(OsCode::KEY_639),
+            640 => Some(OsCode::KEY_640),
+            641 => Some(OsCode::KEY_641),
+            642 => Some(OsCode::KEY_642),
+            643 => Some(OsCode::KEY_643),
+            644 => Some(OsCode::KEY_644),
+            645 => Some(OsCode::KEY_645),
+            646 => Some(OsCode::KEY_646),
+            647 => Some(OsCode::KEY_647),
+            648 => Some(OsCode::KEY_648),
+            649 => Some(OsCode::KEY_649),
+            650 => Some(OsCode::KEY_650),
+            651 => Some(OsCode::KEY_651),
+            652 => Some(OsCode::KEY_652),
+            653 => Some(OsCode::KEY_653),
+            654 => Some(OsCode::KEY_654),
+            655 => Some(OsCode::KEY_655),
+            656 => Some(OsCode::KEY_656),
+            657 => Some(OsCode::KEY_657),
+            658 => Some(OsCode::KEY_658),
+            659 => Some(OsCode::KEY_659),
+            660 => Some(OsCode::KEY_660),
+            661 => Some(OsCode::KEY_661),
+            662 => Some(OsCode::KEY_662),
+            663 => Some(OsCode::KEY_663),
+            664 => Some(OsCode::KEY_664),
+            665 => Some(OsCode::KEY_665),
+            666 => Some(OsCode::KEY_666),
+            667 => Some(OsCode::KEY_667),
+            668 => Some(OsCode::KEY_668),
+            669 => Some(OsCode::KEY_669),
+            670 => Some(OsCode::KEY_670),
+            671 => Some(OsCode::KEY_671),
+            672 => Some(OsCode::KEY_672),
+            673 => Some(OsCode::KEY_673),
+            674 => Some(OsCode::KEY_674),
+            675 => Some(OsCode::KEY_675),
+            676 => Some(OsCode::KEY_676),
+            677 => Some(OsCode::KEY_677),
+            678 => Some(OsCode::KEY_678),
+            679 => Some(OsCode::KEY_679),
+            680 => Some(OsCode::KEY_680),
+            681 => Some(OsCode::KEY_681),
+            682 => Some(OsCode::KEY_682),
+            683 => Some(OsCode::KEY_683),
+            684 => Some(OsCode::KEY_684),
+            685 => Some(OsCode::KEY_685),
+            686 => Some(OsCode::KEY_686),
+            687 => Some(OsCode::KEY_687),
+            688 => Some(OsCode::KEY_688),
+            689 => Some(OsCode::KEY_689),
+            690 => Some(OsCode::KEY_690),
+            691 => Some(OsCode::KEY_691),
+            692 => Some(OsCode::KEY_692),
+            693 => Some(OsCode::KEY_693),
+            694 => Some(OsCode::KEY_694),
+            695 => Some(OsCode::KEY_695),
+            696 => Some(OsCode::KEY_696),
+            697 => Some(OsCode::KEY_697),
+            698 => Some(OsCode::KEY_698),
+            699 => Some(OsCode::KEY_699),
+            700 => Some(OsCode::KEY_700),
+            701 => Some(OsCode::KEY_701),
+            702 => Some(OsCode::KEY_702),
+            703 => Some(OsCode::KEY_703),
+            704 => Some(OsCode::BTN_TRIGGER_HAPPY1),
+            705 => Some(OsCode::BTN_TRIGGER_HAPPY2),
+            706 => Some(OsCode::BTN_TRIGGER_HAPPY3),
+            707 => Some(OsCode::BTN_TRIGGER_HAPPY4),
+            708 => Some(OsCode::BTN_TRIGGER_HAPPY5),
+            709 => Some(OsCode::BTN_TRIGGER_HAPPY6),
+            710 => Some(OsCode::BTN_TRIGGER_HAPPY7),
+            711 => Some(OsCode::BTN_TRIGGER_HAPPY8),
+            712 => Some(OsCode::BTN_TRIGGER_HAPPY9),
+            713 => Some(OsCode::BTN_TRIGGER_HAPPY10),
+            714 => Some(OsCode::BTN_TRIGGER_HAPPY11),
+            715 => Some(OsCode::BTN_TRIGGER_HAPPY12),
+            716 => Some(OsCode::BTN_TRIGGER_HAPPY13),
+            717 => Some(OsCode::BTN_TRIGGER_HAPPY14),
+            718 => Some(OsCode::BTN_TRIGGER_HAPPY15),
+            719 => Some(OsCode::BTN_TRIGGER_HAPPY16),
+            720 => Some(OsCode::BTN_TRIGGER_HAPPY17),
+            721 => Some(OsCode::BTN_TRIGGER_HAPPY18),
+            722 => Some(OsCode::BTN_TRIGGER_HAPPY19),
+            723 => Some(OsCode::BTN_TRIGGER_HAPPY20),
+            724 => Some(OsCode::BTN_TRIGGER_HAPPY21),
+            725 => Some(OsCode::BTN_TRIGGER_HAPPY22),
+            726 => Some(OsCode::BTN_TRIGGER_HAPPY23),
+            727 => Some(OsCode::BTN_TRIGGER_HAPPY24),
+            728 => Some(OsCode::BTN_TRIGGER_HAPPY25),
+            729 => Some(OsCode::BTN_TRIGGER_HAPPY26),
+            730 => Some(OsCode::BTN_TRIGGER_HAPPY27),
+            731 => Some(OsCode::BTN_TRIGGER_HAPPY28),
+            732 => Some(OsCode::BTN_TRIGGER_HAPPY29),
+            733 => Some(OsCode::BTN_TRIGGER_HAPPY30),
+            734 => Some(OsCode::BTN_TRIGGER_HAPPY31),
+            735 => Some(OsCode::BTN_TRIGGER_HAPPY32),
+            736 => Some(OsCode::BTN_TRIGGER_HAPPY33),
+            737 => Some(OsCode::BTN_TRIGGER_HAPPY34),
+            738 => Some(OsCode::BTN_TRIGGER_HAPPY35),
+            739 => Some(OsCode::BTN_TRIGGER_HAPPY36),
+            740 => Some(OsCode::BTN_TRIGGER_HAPPY37),
+            741 => Some(OsCode::BTN_TRIGGER_HAPPY38),
+            742 => Some(OsCode::BTN_TRIGGER_HAPPY39),
+            743 => Some(OsCode::BTN_TRIGGER_HAPPY40),
+            744 => Some(OsCode::BTN_MAX),
+            745 => Some(OsCode::MouseWheelUp),
+            746 => Some(OsCode::MouseWheelDown),
+            747 => Some(OsCode::MouseWheelLeft),
+            748 => Some(OsCode::MouseWheelRight),
+            767 => Some(OsCode::KEY_MAX),
+            _ => None,
+        }
+    }
+}
diff --git a/parser/src/keys/mappings.rs b/parser/src/keys/mappings.rs
index b45e3f81c..43c41beb4 100644
--- a/parser/src/keys/mappings.rs
+++ b/parser/src/keys/mappings.rs
@@ -3,1354 +3,792 @@ use super::OsCode;
 
 impl From<KeyCode> for OsCode {
     fn from(item: KeyCode) -> Self {
-        match item {
-            KeyCode::Escape => OsCode::KEY_ESC,
-            KeyCode::Kb1 => OsCode::KEY_1,
-            KeyCode::Kb2 => OsCode::KEY_2,
-            KeyCode::Kb3 => OsCode::KEY_3,
-            KeyCode::Kb4 => OsCode::KEY_4,
-            KeyCode::Kb5 => OsCode::KEY_5,
-            KeyCode::Kb6 => OsCode::KEY_6,
-            KeyCode::Kb7 => OsCode::KEY_7,
-            KeyCode::Kb8 => OsCode::KEY_8,
-            KeyCode::Kb9 => OsCode::KEY_9,
-            KeyCode::Kb0 => OsCode::KEY_0,
-            KeyCode::Minus => OsCode::KEY_MINUS,
-            KeyCode::Equal => OsCode::KEY_EQUAL,
-            KeyCode::BSpace => OsCode::KEY_BACKSPACE,
-            KeyCode::Tab => OsCode::KEY_TAB,
-            KeyCode::Q => OsCode::KEY_Q,
-            KeyCode::W => OsCode::KEY_W,
-            KeyCode::E => OsCode::KEY_E,
-            KeyCode::R => OsCode::KEY_R,
-            KeyCode::T => OsCode::KEY_T,
-            KeyCode::Y => OsCode::KEY_Y,
-            KeyCode::U => OsCode::KEY_U,
-            KeyCode::I => OsCode::KEY_I,
-            KeyCode::O => OsCode::KEY_O,
-            KeyCode::P => OsCode::KEY_P,
-            KeyCode::LBracket => OsCode::KEY_LEFTBRACE,
-            KeyCode::RBracket => OsCode::KEY_RIGHTBRACE,
-            KeyCode::Enter => OsCode::KEY_ENTER,
-            KeyCode::LCtrl => OsCode::KEY_LEFTCTRL,
-            KeyCode::A => OsCode::KEY_A,
-            KeyCode::S => OsCode::KEY_S,
-            KeyCode::D => OsCode::KEY_D,
-            KeyCode::F => OsCode::KEY_F,
-            KeyCode::G => OsCode::KEY_G,
-            KeyCode::H => OsCode::KEY_H,
-            KeyCode::J => OsCode::KEY_J,
-            KeyCode::K => OsCode::KEY_K,
-            KeyCode::L => OsCode::KEY_L,
-            KeyCode::SColon => OsCode::KEY_SEMICOLON,
-            KeyCode::Quote => OsCode::KEY_APOSTROPHE,
-            KeyCode::Grave => OsCode::KEY_GRAVE,
-            KeyCode::LShift => OsCode::KEY_LEFTSHIFT,
-            KeyCode::Bslash => OsCode::KEY_BACKSLASH,
-            KeyCode::Z => OsCode::KEY_Z,
-            KeyCode::X => OsCode::KEY_X,
-            KeyCode::C => OsCode::KEY_C,
-            KeyCode::V => OsCode::KEY_V,
-            KeyCode::B => OsCode::KEY_B,
-            KeyCode::N => OsCode::KEY_N,
-            KeyCode::M => OsCode::KEY_M,
-            KeyCode::Comma => OsCode::KEY_COMMA,
-            KeyCode::Dot => OsCode::KEY_DOT,
-            KeyCode::Slash => OsCode::KEY_SLASH,
-            KeyCode::RShift => OsCode::KEY_RIGHTSHIFT,
-            KeyCode::KpAsterisk => OsCode::KEY_KPASTERISK,
-            KeyCode::LAlt => OsCode::KEY_LEFTALT,
-            KeyCode::Space => OsCode::KEY_SPACE,
-            KeyCode::CapsLock => OsCode::KEY_CAPSLOCK,
-            KeyCode::F1 => OsCode::KEY_F1,
-            KeyCode::F2 => OsCode::KEY_F2,
-            KeyCode::F3 => OsCode::KEY_F3,
-            KeyCode::F4 => OsCode::KEY_F4,
-            KeyCode::F5 => OsCode::KEY_F5,
-            KeyCode::F6 => OsCode::KEY_F6,
-            KeyCode::F7 => OsCode::KEY_F7,
-            KeyCode::F8 => OsCode::KEY_F8,
-            KeyCode::F9 => OsCode::KEY_F9,
-            KeyCode::F10 => OsCode::KEY_F10,
-            KeyCode::NumLock => OsCode::KEY_NUMLOCK,
-            KeyCode::Clear => OsCode::KEY_CLEAR,
-            KeyCode::ScrollLock => OsCode::KEY_SCROLLLOCK,
-            KeyCode::Kp7 => OsCode::KEY_KP7,
-            KeyCode::Kp8 => OsCode::KEY_KP8,
-            KeyCode::Kp9 => OsCode::KEY_KP9,
-            KeyCode::KpMinus => OsCode::KEY_KPMINUS,
-            KeyCode::Kp4 => OsCode::KEY_KP4,
-            KeyCode::Kp5 => OsCode::KEY_KP5,
-            KeyCode::Kp6 => OsCode::KEY_KP6,
-            KeyCode::KpPlus => OsCode::KEY_KPPLUS,
-            KeyCode::Kp1 => OsCode::KEY_KP1,
-            KeyCode::Kp2 => OsCode::KEY_KP2,
-            KeyCode::Kp3 => OsCode::KEY_KP3,
-            KeyCode::Kp0 => OsCode::KEY_KP0,
-            KeyCode::KpDot => OsCode::KEY_KPDOT,
-            KeyCode::F11 => OsCode::KEY_F11,
-            KeyCode::F12 => OsCode::KEY_F12,
-            KeyCode::KpEnter => OsCode::KEY_KPENTER,
-            KeyCode::RCtrl => OsCode::KEY_RIGHTCTRL,
-            KeyCode::KpSlash => OsCode::KEY_KPSLASH,
-            KeyCode::SysReq => OsCode::KEY_SYSRQ,
-            KeyCode::RAlt => OsCode::KEY_RIGHTALT,
-            KeyCode::Home => OsCode::KEY_HOME,
-            KeyCode::Up => OsCode::KEY_UP,
-            KeyCode::PgUp => OsCode::KEY_PAGEUP,
-            KeyCode::Left => OsCode::KEY_LEFT,
-            KeyCode::Right => OsCode::KEY_RIGHT,
-            KeyCode::End => OsCode::KEY_END,
-            KeyCode::Down => OsCode::KEY_DOWN,
-            KeyCode::PgDown => OsCode::KEY_PAGEDOWN,
-            KeyCode::Insert => OsCode::KEY_INSERT,
-            KeyCode::Delete => OsCode::KEY_DELETE,
-            KeyCode::Mute => OsCode::KEY_MUTE,
-            KeyCode::VolDown => OsCode::KEY_VOLUMEDOWN,
-            KeyCode::VolUp => OsCode::KEY_VOLUMEUP,
-            KeyCode::Power => OsCode::KEY_POWER,
-            KeyCode::KpEqual => OsCode::KEY_KPEQUAL,
-            KeyCode::Pause => OsCode::KEY_PAUSE,
-            KeyCode::KpComma => OsCode::KEY_KPCOMMA,
-            KeyCode::LGui => OsCode::KEY_LEFTMETA,
-            KeyCode::RGui => OsCode::KEY_RIGHTMETA,
-            KeyCode::Stop => OsCode::KEY_STOP,
-            KeyCode::Again => OsCode::KEY_AGAIN,
-            KeyCode::Undo => OsCode::KEY_UNDO,
-            KeyCode::Copy => OsCode::KEY_COPY,
-            KeyCode::Paste => OsCode::KEY_PASTE,
-            KeyCode::Find => OsCode::KEY_FIND,
-            KeyCode::Cut => OsCode::KEY_CUT,
-            KeyCode::Help => OsCode::KEY_HELP,
-            KeyCode::Menu => OsCode::KEY_MENU,
-            KeyCode::MediaCalc => OsCode::KEY_CALC,
-            KeyCode::MediaSleep => OsCode::KEY_SLEEP,
-            KeyCode::MediaWWW => OsCode::KEY_WWW,
-            KeyCode::MediaCoffee => OsCode::KEY_COFFEE,
-            KeyCode::MediaBack => OsCode::KEY_BACK,
-            KeyCode::MediaForward => OsCode::KEY_FORWARD,
-            KeyCode::MediaEjectCD => OsCode::KEY_EJECTCD,
-            KeyCode::MediaNextSong => OsCode::KEY_NEXTSONG,
-            KeyCode::MediaPlayPause => OsCode::KEY_PLAYPAUSE,
-            KeyCode::MediaPreviousSong => OsCode::KEY_PREVIOUSSONG,
-            KeyCode::MediaStopCD => OsCode::KEY_STOPCD,
-            KeyCode::MediaRefresh => OsCode::KEY_REFRESH,
-            KeyCode::MediaEdit => OsCode::KEY_EDIT,
-            KeyCode::MediaScrollUp => OsCode::KEY_SCROLLUP,
-            KeyCode::MediaScrollDown => OsCode::KEY_SCROLLDOWN,
-            KeyCode::F13 => OsCode::KEY_F13,
-            KeyCode::F14 => OsCode::KEY_F14,
-            KeyCode::F15 => OsCode::KEY_F15,
-            KeyCode::F16 => OsCode::KEY_F16,
-            KeyCode::F17 => OsCode::KEY_F17,
-            KeyCode::F18 => OsCode::KEY_F18,
-            KeyCode::F19 => OsCode::KEY_F19,
-            KeyCode::F20 => OsCode::KEY_F20,
-            KeyCode::F21 => OsCode::KEY_F21,
-            KeyCode::F22 => OsCode::KEY_F22,
-            KeyCode::F23 => OsCode::KEY_F23,
-            KeyCode::F24 => OsCode::KEY_F24,
-            KeyCode::Wakeup => OsCode::KEY_WAKEUP,
-            KeyCode::BrightnessUp => OsCode::KEY_BRIGHTNESSUP,
-            KeyCode::BrightnessDown => OsCode::KEY_BRIGHTNESSDOWN,
-            KeyCode::KbdIllumUp => OsCode::KEY_KBDILLUMUP,
-            KeyCode::KbdIllumDown => OsCode::KEY_KBDILLUMDOWN,
-            KeyCode::Lang1 => OsCode::KEY_HANGEUL,
-            KeyCode::Lang2 => OsCode::KEY_HANJA,
-            KeyCode::NonUsBslash => OsCode::KEY_102ND,
-            KeyCode::PScreen => OsCode::KEY_PRINT,
-            KeyCode::Application => OsCode::KEY_COMPOSE,
-            KeyCode::AltErase => OsCode::KEY_ALTERASE,
-            KeyCode::Cancel => OsCode::KEY_CANCEL,
-            KeyCode::MediaMute => OsCode::KEY_MICMUTE,
-            KeyCode::Intl1 => OsCode::KEY_RO,
-            KeyCode::K0xAA => OsCode::KEY_MEDIA,
-            KeyCode::K0xAB => OsCode::KEY_EMAIL,
-            KeyCode::K0xAC => OsCode::KEY_PLAYER,
-            KeyCode::K0xAD => OsCode::KEY_HOMEPAGE,
-            KeyCode::K0xAE => OsCode::KEY_MAIL,
-            KeyCode::K0xAF => OsCode::KEY_MUHENKAN,
-            KeyCode::K0xB0 => OsCode::KEY_HENKAN,
-            KeyCode::K0xB1 => OsCode::KEY_KATAKANA,
-            KeyCode::K0xB2 => OsCode::KEY_KATAKANAHIRAGANA,
-            KeyCode::K0xB3 => OsCode::KEY_HIRAGANA,
-            _ => haphazard_kc_to_osc_mappings(item),
-        }
+        unsafe { std::mem::transmute(item) }
     }
 }
 
 impl From<OsCode> for KeyCode {
     fn from(item: OsCode) -> KeyCode {
-        match item {
-            OsCode::KEY_ESC => KeyCode::Escape,
-            OsCode::KEY_1 => KeyCode::Kb1,
-            OsCode::KEY_2 => KeyCode::Kb2,
-            OsCode::KEY_3 => KeyCode::Kb3,
-            OsCode::KEY_4 => KeyCode::Kb4,
-            OsCode::KEY_5 => KeyCode::Kb5,
-            OsCode::KEY_6 => KeyCode::Kb6,
-            OsCode::KEY_7 => KeyCode::Kb7,
-            OsCode::KEY_8 => KeyCode::Kb8,
-            OsCode::KEY_9 => KeyCode::Kb9,
-            OsCode::KEY_0 => KeyCode::Kb0,
-            OsCode::KEY_MINUS => KeyCode::Minus,
-            OsCode::KEY_EQUAL => KeyCode::Equal,
-            OsCode::KEY_BACKSPACE => KeyCode::BSpace,
-            OsCode::KEY_TAB => KeyCode::Tab,
-            OsCode::KEY_Q => KeyCode::Q,
-            OsCode::KEY_W => KeyCode::W,
-            OsCode::KEY_E => KeyCode::E,
-            OsCode::KEY_R => KeyCode::R,
-            OsCode::KEY_T => KeyCode::T,
-            OsCode::KEY_Y => KeyCode::Y,
-            OsCode::KEY_U => KeyCode::U,
-            OsCode::KEY_I => KeyCode::I,
-            OsCode::KEY_O => KeyCode::O,
-            OsCode::KEY_P => KeyCode::P,
-            OsCode::KEY_LEFTBRACE => KeyCode::LBracket,
-            OsCode::KEY_RIGHTBRACE => KeyCode::RBracket,
-            OsCode::KEY_ENTER => KeyCode::Enter,
-            OsCode::KEY_LEFTCTRL => KeyCode::LCtrl,
-            OsCode::KEY_A => KeyCode::A,
-            OsCode::KEY_S => KeyCode::S,
-            OsCode::KEY_D => KeyCode::D,
-            OsCode::KEY_F => KeyCode::F,
-            OsCode::KEY_G => KeyCode::G,
-            OsCode::KEY_H => KeyCode::H,
-            OsCode::KEY_J => KeyCode::J,
-            OsCode::KEY_K => KeyCode::K,
-            OsCode::KEY_L => KeyCode::L,
-            OsCode::KEY_SEMICOLON => KeyCode::SColon,
-            OsCode::KEY_APOSTROPHE => KeyCode::Quote,
-            OsCode::KEY_GRAVE => KeyCode::Grave,
-            OsCode::KEY_LEFTSHIFT => KeyCode::LShift,
-            OsCode::KEY_BACKSLASH => KeyCode::Bslash,
-            OsCode::KEY_Z => KeyCode::Z,
-            OsCode::KEY_X => KeyCode::X,
-            OsCode::KEY_C => KeyCode::C,
-            OsCode::KEY_V => KeyCode::V,
-            OsCode::KEY_B => KeyCode::B,
-            OsCode::KEY_N => KeyCode::N,
-            OsCode::KEY_M => KeyCode::M,
-            OsCode::KEY_COMMA => KeyCode::Comma,
-            OsCode::KEY_DOT => KeyCode::Dot,
-            OsCode::KEY_SLASH => KeyCode::Slash,
-            OsCode::KEY_RIGHTSHIFT => KeyCode::RShift,
-            OsCode::KEY_KPASTERISK => KeyCode::KpAsterisk,
-            OsCode::KEY_LEFTALT => KeyCode::LAlt,
-            OsCode::KEY_SPACE => KeyCode::Space,
-            OsCode::KEY_CAPSLOCK => KeyCode::CapsLock,
-            OsCode::KEY_F1 => KeyCode::F1,
-            OsCode::KEY_F2 => KeyCode::F2,
-            OsCode::KEY_F3 => KeyCode::F3,
-            OsCode::KEY_F4 => KeyCode::F4,
-            OsCode::KEY_F5 => KeyCode::F5,
-            OsCode::KEY_F6 => KeyCode::F6,
-            OsCode::KEY_F7 => KeyCode::F7,
-            OsCode::KEY_F8 => KeyCode::F8,
-            OsCode::KEY_F9 => KeyCode::F9,
-            OsCode::KEY_F10 => KeyCode::F10,
-            OsCode::KEY_NUMLOCK => KeyCode::NumLock,
-            OsCode::KEY_CLEAR => KeyCode::Clear,
-            OsCode::KEY_SCROLLLOCK => KeyCode::ScrollLock,
-            OsCode::KEY_KP7 => KeyCode::Kp7,
-            OsCode::KEY_KP8 => KeyCode::Kp8,
-            OsCode::KEY_KP9 => KeyCode::Kp9,
-            OsCode::KEY_KPMINUS => KeyCode::KpMinus,
-            OsCode::KEY_KP4 => KeyCode::Kp4,
-            OsCode::KEY_KP5 => KeyCode::Kp5,
-            OsCode::KEY_KP6 => KeyCode::Kp6,
-            OsCode::KEY_KPPLUS => KeyCode::KpPlus,
-            OsCode::KEY_KP1 => KeyCode::Kp1,
-            OsCode::KEY_KP2 => KeyCode::Kp2,
-            OsCode::KEY_KP3 => KeyCode::Kp3,
-            OsCode::KEY_KP0 => KeyCode::Kp0,
-            OsCode::KEY_KPDOT => KeyCode::KpDot,
-            OsCode::KEY_F11 => KeyCode::F11,
-            OsCode::KEY_F12 => KeyCode::F12,
-            OsCode::KEY_KPENTER => KeyCode::KpEnter,
-            OsCode::KEY_RIGHTCTRL => KeyCode::RCtrl,
-            OsCode::KEY_KPSLASH => KeyCode::KpSlash,
-            OsCode::KEY_SYSRQ => KeyCode::SysReq,
-            OsCode::KEY_RIGHTALT => KeyCode::RAlt,
-            OsCode::KEY_HOME => KeyCode::Home,
-            OsCode::KEY_UP => KeyCode::Up,
-            OsCode::KEY_PAGEUP => KeyCode::PgUp,
-            OsCode::KEY_LEFT => KeyCode::Left,
-            OsCode::KEY_RIGHT => KeyCode::Right,
-            OsCode::KEY_END => KeyCode::End,
-            OsCode::KEY_DOWN => KeyCode::Down,
-            OsCode::KEY_PAGEDOWN => KeyCode::PgDown,
-            OsCode::KEY_INSERT => KeyCode::Insert,
-            OsCode::KEY_DELETE => KeyCode::Delete,
-            OsCode::KEY_MUTE => KeyCode::Mute,
-            OsCode::KEY_VOLUMEDOWN => KeyCode::VolDown,
-            OsCode::KEY_VOLUMEUP => KeyCode::VolUp,
-            OsCode::KEY_POWER => KeyCode::Power,
-            OsCode::KEY_KPEQUAL => KeyCode::KpEqual,
-            OsCode::KEY_PAUSE => KeyCode::Pause,
-            OsCode::KEY_KPCOMMA => KeyCode::KpComma,
-            OsCode::KEY_LEFTMETA => KeyCode::LGui,
-            OsCode::KEY_RIGHTMETA => KeyCode::RGui,
-            OsCode::KEY_STOP => KeyCode::Stop,
-            OsCode::KEY_AGAIN => KeyCode::Again,
-            OsCode::KEY_UNDO => KeyCode::Undo,
-            OsCode::KEY_COPY => KeyCode::Copy,
-            OsCode::KEY_PASTE => KeyCode::Paste,
-            OsCode::KEY_FIND => KeyCode::Find,
-            OsCode::KEY_CUT => KeyCode::Cut,
-            OsCode::KEY_HELP => KeyCode::Help,
-            OsCode::KEY_MENU => KeyCode::Menu,
-            OsCode::KEY_CALC => KeyCode::MediaCalc,
-            OsCode::KEY_SLEEP => KeyCode::MediaSleep,
-            OsCode::KEY_WWW => KeyCode::MediaWWW,
-            OsCode::KEY_COFFEE => KeyCode::MediaCoffee,
-            OsCode::KEY_BACK => KeyCode::MediaBack,
-            OsCode::KEY_FORWARD => KeyCode::MediaForward,
-            OsCode::KEY_EJECTCD => KeyCode::MediaEjectCD,
-            OsCode::KEY_NEXTSONG => KeyCode::MediaNextSong,
-            OsCode::KEY_PLAYPAUSE => KeyCode::MediaPlayPause,
-            OsCode::KEY_PREVIOUSSONG => KeyCode::MediaPreviousSong,
-            OsCode::KEY_STOPCD => KeyCode::MediaStopCD,
-            OsCode::KEY_REFRESH => KeyCode::MediaRefresh,
-            OsCode::KEY_EDIT => KeyCode::MediaEdit,
-            OsCode::KEY_SCROLLUP => KeyCode::MediaScrollUp,
-            OsCode::KEY_SCROLLDOWN => KeyCode::MediaScrollDown,
-            OsCode::KEY_F13 => KeyCode::F13,
-            OsCode::KEY_F14 => KeyCode::F14,
-            OsCode::KEY_F15 => KeyCode::F15,
-            OsCode::KEY_F16 => KeyCode::F16,
-            OsCode::KEY_F17 => KeyCode::F17,
-            OsCode::KEY_F18 => KeyCode::F18,
-            OsCode::KEY_F19 => KeyCode::F19,
-            OsCode::KEY_F20 => KeyCode::F20,
-            OsCode::KEY_F21 => KeyCode::F21,
-            OsCode::KEY_F22 => KeyCode::F22,
-            OsCode::KEY_F23 => KeyCode::F23,
-            OsCode::KEY_F24 => KeyCode::F24,
-            OsCode::KEY_WAKEUP => KeyCode::Wakeup,
-            OsCode::KEY_BRIGHTNESSUP => KeyCode::BrightnessUp,
-            OsCode::KEY_BRIGHTNESSDOWN => KeyCode::BrightnessDown,
-            OsCode::KEY_KBDILLUMUP => KeyCode::KbdIllumUp,
-            OsCode::KEY_KBDILLUMDOWN => KeyCode::KbdIllumDown,
-            OsCode::KEY_HANGEUL => KeyCode::Lang1,
-            OsCode::KEY_HANJA => KeyCode::Lang2,
-            OsCode::KEY_102ND => KeyCode::NonUsBslash,
-            OsCode::KEY_PRINT => KeyCode::PScreen,
-            OsCode::KEY_COMPOSE => KeyCode::Application,
-            OsCode::KEY_ALTERASE => KeyCode::AltErase,
-            OsCode::KEY_CANCEL => KeyCode::Cancel,
-            OsCode::KEY_MICMUTE => KeyCode::MediaMute,
-            OsCode::KEY_RO => KeyCode::Intl1,
-            OsCode::KEY_MEDIA => KeyCode::K0xAA,
-            OsCode::KEY_EMAIL => KeyCode::K0xAB,
-            OsCode::KEY_PLAYER => KeyCode::K0xAC,
-            OsCode::KEY_HOMEPAGE => KeyCode::K0xAD,
-            OsCode::KEY_MAIL => KeyCode::K0xAE,
-            OsCode::KEY_MUHENKAN => KeyCode::K0xAF,
-            OsCode::KEY_HENKAN => KeyCode::K0xB0,
-            OsCode::KEY_KATAKANA => KeyCode::K0xB1,
-            OsCode::KEY_KATAKANAHIRAGANA => KeyCode::K0xB2,
-            OsCode::KEY_HIRAGANA => KeyCode::K0xB3,
-            _ => haphazard_osc_to_kc_mappings(item),
-        }
+        unsafe { std::mem::transmute(item) }
     }
 }
 
-fn haphazard_osc_to_kc_mappings(osc: OsCode) -> KeyCode {
-    match osc {
-        OsCode::KEY_252 => KeyCode::K252,
-        OsCode::KEY_253 => KeyCode::K253,
-        OsCode::KEY_254 => KeyCode::K254,
-        OsCode::KEY_255 => KeyCode::K255,
-        OsCode::BTN_0 => KeyCode::K256,
-        OsCode::BTN_1 => KeyCode::K257,
-        OsCode::BTN_2 => KeyCode::K258,
-        OsCode::BTN_3 => KeyCode::K259,
-        OsCode::BTN_4 => KeyCode::K260,
-        OsCode::BTN_5 => KeyCode::K261,
-        OsCode::BTN_6 => KeyCode::K262,
-        OsCode::BTN_7 => KeyCode::K263,
-        OsCode::BTN_8 => KeyCode::K264,
-        OsCode::BTN_9 => KeyCode::K265,
-        OsCode::KEY_266 => KeyCode::K266,
-        OsCode::KEY_267 => KeyCode::K267,
-        OsCode::KEY_268 => KeyCode::K268,
-        OsCode::KEY_269 => KeyCode::K269,
-        OsCode::KEY_270 => KeyCode::K270,
-        OsCode::KEY_271 => KeyCode::K271,
-        OsCode::BTN_LEFT => KeyCode::K272,
-        OsCode::BTN_RIGHT => KeyCode::K273,
-        OsCode::BTN_MIDDLE => KeyCode::K274,
-        OsCode::BTN_SIDE => KeyCode::K275,
-        OsCode::BTN_EXTRA => KeyCode::K276,
-        OsCode::BTN_FORWARD => KeyCode::K277,
-        OsCode::BTN_BACK => KeyCode::K278,
-        OsCode::BTN_TASK => KeyCode::K279,
-        OsCode::KEY_280 => KeyCode::K280,
-        OsCode::KEY_281 => KeyCode::K281,
-        OsCode::KEY_282 => KeyCode::K282,
-        OsCode::KEY_283 => KeyCode::K283,
-        OsCode::KEY_284 => KeyCode::K284,
-        OsCode::KEY_285 => KeyCode::K285,
-        OsCode::KEY_286 => KeyCode::K286,
-        OsCode::KEY_287 => KeyCode::K287,
-        OsCode::BTN_TRIGGER => KeyCode::K288,
-        OsCode::BTN_THUMB => KeyCode::K289,
-        OsCode::BTN_THUMB2 => KeyCode::K290,
-        OsCode::BTN_TOP => KeyCode::K291,
-        OsCode::BTN_TOP2 => KeyCode::K292,
-        OsCode::BTN_PINKIE => KeyCode::K293,
-        OsCode::BTN_BASE => KeyCode::K294,
-        OsCode::BTN_BASE2 => KeyCode::K295,
-        OsCode::BTN_BASE3 => KeyCode::K296,
-        OsCode::BTN_BASE4 => KeyCode::K297,
-        OsCode::BTN_BASE5 => KeyCode::K298,
-        OsCode::BTN_BASE6 => KeyCode::K299,
-        OsCode::KEY_300 => KeyCode::K300,
-        OsCode::KEY_301 => KeyCode::K301,
-        OsCode::KEY_302 => KeyCode::K302,
-        OsCode::BTN_DEAD => KeyCode::K303,
-        OsCode::BTN_SOUTH => KeyCode::K304,
-        OsCode::BTN_EAST => KeyCode::K305,
-        OsCode::BTN_C => KeyCode::K306,
-        OsCode::BTN_NORTH => KeyCode::K307,
-        OsCode::BTN_WEST => KeyCode::K308,
-        OsCode::BTN_Z => KeyCode::K309,
-        OsCode::BTN_TL => KeyCode::K310,
-        OsCode::BTN_TR => KeyCode::K311,
-        OsCode::BTN_TL2 => KeyCode::K312,
-        OsCode::BTN_TR2 => KeyCode::K313,
-        OsCode::BTN_SELECT => KeyCode::K314,
-        OsCode::BTN_START => KeyCode::K315,
-        OsCode::BTN_MODE => KeyCode::K316,
-        OsCode::BTN_THUMBL => KeyCode::K317,
-        OsCode::BTN_THUMBR => KeyCode::K318,
-        OsCode::KEY_319 => KeyCode::K319,
-        OsCode::BTN_TOOL_PEN => KeyCode::K320,
-        OsCode::BTN_TOOL_RUBBER => KeyCode::K321,
-        OsCode::BTN_TOOL_BRUSH => KeyCode::K322,
-        OsCode::BTN_TOOL_PENCIL => KeyCode::K323,
-        OsCode::BTN_TOOL_AIRBRUSH => KeyCode::K324,
-        OsCode::BTN_TOOL_FINGER => KeyCode::K325,
-        OsCode::BTN_TOOL_MOUSE => KeyCode::K326,
-        OsCode::BTN_TOOL_LENS => KeyCode::K327,
-        OsCode::BTN_TOOL_QUINTTAP => KeyCode::K328,
-        OsCode::BTN_STYLUS3 => KeyCode::K329,
-        OsCode::BTN_TOUCH => KeyCode::K330,
-        OsCode::BTN_STYLUS => KeyCode::K331,
-        OsCode::BTN_STYLUS2 => KeyCode::K332,
-        OsCode::BTN_TOOL_DOUBLETAP => KeyCode::K333,
-        OsCode::BTN_TOOL_TRIPLETAP => KeyCode::K334,
-        OsCode::BTN_TOOL_QUADTAP => KeyCode::K335,
-        OsCode::BTN_GEAR_DOWN => KeyCode::K336,
-        OsCode::BTN_GEAR_UP => KeyCode::K337,
-        OsCode::KEY_338 => KeyCode::K338,
-        OsCode::KEY_339 => KeyCode::K339,
-        OsCode::KEY_340 => KeyCode::K340,
-        OsCode::KEY_341 => KeyCode::K341,
-        OsCode::KEY_342 => KeyCode::K342,
-        OsCode::KEY_343 => KeyCode::K343,
-        OsCode::KEY_344 => KeyCode::K344,
-        OsCode::KEY_345 => KeyCode::K345,
-        OsCode::KEY_346 => KeyCode::K346,
-        OsCode::KEY_347 => KeyCode::K347,
-        OsCode::KEY_348 => KeyCode::K348,
-        OsCode::KEY_349 => KeyCode::K349,
-        OsCode::KEY_350 => KeyCode::K350,
-        OsCode::KEY_351 => KeyCode::K351,
-        OsCode::KEY_OK => KeyCode::K352,
-        OsCode::KEY_SELECT => KeyCode::K353,
-        OsCode::KEY_GOTO => KeyCode::K354,
-        OsCode::KEY_CLEAR => KeyCode::K355,
-        OsCode::KEY_POWER2 => KeyCode::K356,
-        OsCode::KEY_OPTION => KeyCode::K357,
-        OsCode::KEY_INFO => KeyCode::K358,
-        OsCode::KEY_TIME => KeyCode::K359,
-        OsCode::KEY_VENDOR => KeyCode::K360,
-        OsCode::KEY_ARCHIVE => KeyCode::K361,
-        OsCode::KEY_PROGRAM => KeyCode::K362,
-        OsCode::KEY_CHANNEL => KeyCode::K363,
-        OsCode::KEY_FAVORITES => KeyCode::K364,
-        OsCode::KEY_EPG => KeyCode::K365,
-        OsCode::KEY_PVR => KeyCode::K366,
-        OsCode::KEY_MHP => KeyCode::K367,
-        OsCode::KEY_LANGUAGE => KeyCode::K368,
-        OsCode::KEY_TITLE => KeyCode::K369,
-        OsCode::KEY_SUBTITLE => KeyCode::K370,
-        OsCode::KEY_ANGLE => KeyCode::K371,
-        OsCode::KEY_FULL_SCREEN => KeyCode::K372,
-        OsCode::KEY_MODE => KeyCode::K373,
-        OsCode::KEY_KEYBOARD => KeyCode::K374,
-        OsCode::KEY_ASPECT_RATIO => KeyCode::K375,
-        OsCode::KEY_PC => KeyCode::K376,
-        OsCode::KEY_TV => KeyCode::K377,
-        OsCode::KEY_TV2 => KeyCode::K378,
-        OsCode::KEY_VCR => KeyCode::K379,
-        OsCode::KEY_VCR2 => KeyCode::K380,
-        OsCode::KEY_SAT => KeyCode::K381,
-        OsCode::KEY_SAT2 => KeyCode::K382,
-        OsCode::KEY_CD => KeyCode::K383,
-        OsCode::KEY_TAPE => KeyCode::K384,
-        OsCode::KEY_RADIO => KeyCode::K385,
-        OsCode::KEY_TUNER => KeyCode::K386,
-        OsCode::KEY_PLAYER => KeyCode::K387,
-        OsCode::KEY_TEXT => KeyCode::K388,
-        OsCode::KEY_DVD => KeyCode::K389,
-        OsCode::KEY_AUX => KeyCode::K390,
-        OsCode::KEY_MP3 => KeyCode::K391,
-        OsCode::KEY_AUDIO => KeyCode::K392,
-        OsCode::KEY_VIDEO => KeyCode::K393,
-        OsCode::KEY_DIRECTORY => KeyCode::K394,
-        OsCode::KEY_LIST => KeyCode::K395,
-        OsCode::KEY_MEMO => KeyCode::K396,
-        OsCode::KEY_CALENDAR => KeyCode::K397,
-        OsCode::KEY_RED => KeyCode::K398,
-        OsCode::KEY_GREEN => KeyCode::K399,
-        OsCode::KEY_YELLOW => KeyCode::K400,
-        OsCode::KEY_BLUE => KeyCode::K401,
-        OsCode::KEY_CHANNELUP => KeyCode::K402,
-        OsCode::KEY_CHANNELDOWN => KeyCode::K403,
-        OsCode::KEY_FIRST => KeyCode::K404,
-        OsCode::KEY_LAST => KeyCode::K405,
-        OsCode::KEY_AB => KeyCode::K406,
-        OsCode::KEY_NEXT => KeyCode::K407,
-        OsCode::KEY_RESTART => KeyCode::K408,
-        OsCode::KEY_SLOW => KeyCode::K409,
-        OsCode::KEY_SHUFFLE => KeyCode::K410,
-        OsCode::KEY_BREAK => KeyCode::K411,
-        OsCode::KEY_PREVIOUS => KeyCode::K412,
-        OsCode::KEY_DIGITS => KeyCode::K413,
-        OsCode::KEY_TEEN => KeyCode::K414,
-        OsCode::KEY_TWEN => KeyCode::K415,
-        OsCode::KEY_VIDEOPHONE => KeyCode::K416,
-        OsCode::KEY_GAMES => KeyCode::K417,
-        OsCode::KEY_ZOOMIN => KeyCode::K418,
-        OsCode::KEY_ZOOMOUT => KeyCode::K419,
-        OsCode::KEY_ZOOMRESET => KeyCode::K420,
-        OsCode::KEY_WORDPROCESSOR => KeyCode::K421,
-        OsCode::KEY_EDITOR => KeyCode::K422,
-        OsCode::KEY_SPREADSHEET => KeyCode::K423,
-        OsCode::KEY_GRAPHICSEDITOR => KeyCode::K424,
-        OsCode::KEY_PRESENTATION => KeyCode::K425,
-        OsCode::KEY_DATABASE => KeyCode::K426,
-        OsCode::KEY_NEWS => KeyCode::K427,
-        OsCode::KEY_VOICEMAIL => KeyCode::K428,
-        OsCode::KEY_ADDRESSBOOK => KeyCode::K429,
-        OsCode::KEY_MESSENGER => KeyCode::K430,
-        OsCode::KEY_DISPLAYTOGGLE => KeyCode::K431,
-        OsCode::KEY_SPELLCHECK => KeyCode::K432,
-        OsCode::KEY_LOGOFF => KeyCode::K433,
-        OsCode::KEY_DOLLAR => KeyCode::K434,
-        OsCode::KEY_EURO => KeyCode::K435,
-        OsCode::KEY_FRAMEBACK => KeyCode::K436,
-        OsCode::KEY_FRAMEFORWARD => KeyCode::K437,
-        OsCode::KEY_CONTEXT_MENU => KeyCode::K438,
-        OsCode::KEY_MEDIA_REPEAT => KeyCode::K439,
-        OsCode::KEY_10CHANNELSUP => KeyCode::K440,
-        OsCode::KEY_10CHANNELSDOWN => KeyCode::K441,
-        OsCode::KEY_IMAGES => KeyCode::K442,
-        OsCode::KEY_443 => KeyCode::K443,
-        OsCode::KEY_444 => KeyCode::K444,
-        OsCode::KEY_445 => KeyCode::K445,
-        OsCode::KEY_446 => KeyCode::K446,
-        OsCode::KEY_447 => KeyCode::K447,
-        OsCode::KEY_DEL_EOL => KeyCode::K448,
-        OsCode::KEY_DEL_EOS => KeyCode::K449,
-        OsCode::KEY_INS_LINE => KeyCode::K450,
-        OsCode::KEY_DEL_LINE => KeyCode::K451,
-        OsCode::KEY_452 => KeyCode::K452,
-        OsCode::KEY_453 => KeyCode::K453,
-        OsCode::KEY_454 => KeyCode::K454,
-        OsCode::KEY_455 => KeyCode::K455,
-        OsCode::KEY_456 => KeyCode::K456,
-        OsCode::KEY_457 => KeyCode::K457,
-        OsCode::KEY_458 => KeyCode::K458,
-        OsCode::KEY_459 => KeyCode::K459,
-        OsCode::KEY_460 => KeyCode::K460,
-        OsCode::KEY_461 => KeyCode::K461,
-        OsCode::KEY_462 => KeyCode::K462,
-        OsCode::KEY_463 => KeyCode::K463,
-        OsCode::KEY_FN => KeyCode::K464,
-        OsCode::KEY_FN_ESC => KeyCode::K465,
-        OsCode::KEY_FN_F1 => KeyCode::K466,
-        OsCode::KEY_FN_F2 => KeyCode::K467,
-        OsCode::KEY_FN_F3 => KeyCode::K468,
-        OsCode::KEY_FN_F4 => KeyCode::K469,
-        OsCode::KEY_FN_F5 => KeyCode::K470,
-        OsCode::KEY_FN_F6 => KeyCode::K471,
-        OsCode::KEY_FN_F7 => KeyCode::K472,
-        OsCode::KEY_FN_F8 => KeyCode::K473,
-        OsCode::KEY_FN_F9 => KeyCode::K474,
-        OsCode::KEY_FN_F10 => KeyCode::K475,
-        OsCode::KEY_FN_F11 => KeyCode::K476,
-        OsCode::KEY_FN_F12 => KeyCode::K477,
-        OsCode::KEY_FN_1 => KeyCode::K478,
-        OsCode::KEY_FN_2 => KeyCode::K479,
-        OsCode::KEY_FN_D => KeyCode::K480,
-        OsCode::KEY_FN_E => KeyCode::K481,
-        OsCode::KEY_FN_F => KeyCode::K482,
-        OsCode::KEY_FN_S => KeyCode::K483,
-        OsCode::KEY_FN_B => KeyCode::K484,
-        OsCode::KEY_485 => KeyCode::K485,
-        OsCode::KEY_486 => KeyCode::K486,
-        OsCode::KEY_487 => KeyCode::K487,
-        OsCode::KEY_488 => KeyCode::K488,
-        OsCode::KEY_489 => KeyCode::K489,
-        OsCode::KEY_490 => KeyCode::K490,
-        OsCode::KEY_491 => KeyCode::K491,
-        OsCode::KEY_492 => KeyCode::K492,
-        OsCode::KEY_493 => KeyCode::K493,
-        OsCode::KEY_494 => KeyCode::K494,
-        OsCode::KEY_495 => KeyCode::K495,
-        OsCode::KEY_496 => KeyCode::K496,
-        OsCode::KEY_BRL_DOT1 => KeyCode::K497,
-        OsCode::KEY_BRL_DOT2 => KeyCode::K498,
-        OsCode::KEY_BRL_DOT3 => KeyCode::K499,
-        OsCode::KEY_BRL_DOT4 => KeyCode::K500,
-        OsCode::KEY_BRL_DOT5 => KeyCode::K501,
-        OsCode::KEY_BRL_DOT6 => KeyCode::K502,
-        OsCode::KEY_BRL_DOT7 => KeyCode::K503,
-        OsCode::KEY_BRL_DOT8 => KeyCode::K504,
-        OsCode::KEY_BRL_DOT9 => KeyCode::K505,
-        OsCode::KEY_BRL_DOT10 => KeyCode::K506,
-        OsCode::KEY_507 => KeyCode::K507,
-        OsCode::KEY_508 => KeyCode::K508,
-        OsCode::KEY_509 => KeyCode::K509,
-        OsCode::KEY_510 => KeyCode::K510,
-        OsCode::KEY_511 => KeyCode::K511,
-        OsCode::KEY_NUMERIC_0 => KeyCode::K512,
-        OsCode::KEY_NUMERIC_1 => KeyCode::K513,
-        OsCode::KEY_NUMERIC_2 => KeyCode::K514,
-        OsCode::KEY_NUMERIC_3 => KeyCode::K515,
-        OsCode::KEY_NUMERIC_4 => KeyCode::K516,
-        OsCode::KEY_NUMERIC_5 => KeyCode::K517,
-        OsCode::KEY_NUMERIC_6 => KeyCode::K518,
-        OsCode::KEY_NUMERIC_7 => KeyCode::K519,
-        OsCode::KEY_NUMERIC_8 => KeyCode::K520,
-        OsCode::KEY_NUMERIC_9 => KeyCode::K521,
-        OsCode::KEY_NUMERIC_STAR => KeyCode::K522,
-        OsCode::KEY_NUMERIC_POUND => KeyCode::K523,
-        OsCode::KEY_NUMERIC_A => KeyCode::K524,
-        OsCode::KEY_NUMERIC_B => KeyCode::K525,
-        OsCode::KEY_NUMERIC_C => KeyCode::K526,
-        OsCode::KEY_NUMERIC_D => KeyCode::K527,
-        OsCode::KEY_CAMERA_FOCUS => KeyCode::K528,
-        OsCode::KEY_WPS_BUTTON => KeyCode::K529,
-        OsCode::KEY_TOUCHPAD_TOGGLE => KeyCode::K530,
-        OsCode::KEY_TOUCHPAD_ON => KeyCode::K531,
-        OsCode::KEY_TOUCHPAD_OFF => KeyCode::K532,
-        OsCode::KEY_CAMERA_ZOOMIN => KeyCode::K533,
-        OsCode::KEY_CAMERA_ZOOMOUT => KeyCode::K534,
-        OsCode::KEY_CAMERA_UP => KeyCode::K535,
-        OsCode::KEY_CAMERA_DOWN => KeyCode::K536,
-        OsCode::KEY_CAMERA_LEFT => KeyCode::K537,
-        OsCode::KEY_CAMERA_RIGHT => KeyCode::K538,
-        OsCode::KEY_ATTENDANT_ON => KeyCode::K539,
-        OsCode::KEY_ATTENDANT_OFF => KeyCode::K540,
-        OsCode::KEY_ATTENDANT_TOGGLE => KeyCode::K541,
-        OsCode::KEY_LIGHTS_TOGGLE => KeyCode::K542,
-        OsCode::KEY_543 => KeyCode::K543,
-        OsCode::BTN_DPAD_UP => KeyCode::K544,
-        OsCode::BTN_DPAD_DOWN => KeyCode::K545,
-        OsCode::BTN_DPAD_LEFT => KeyCode::K546,
-        OsCode::BTN_DPAD_RIGHT => KeyCode::K547,
-        OsCode::KEY_548 => KeyCode::K548,
-        OsCode::KEY_549 => KeyCode::K549,
-        OsCode::KEY_550 => KeyCode::K550,
-        OsCode::KEY_551 => KeyCode::K551,
-        OsCode::KEY_552 => KeyCode::K552,
-        OsCode::KEY_553 => KeyCode::K553,
-        OsCode::KEY_554 => KeyCode::K554,
-        OsCode::KEY_555 => KeyCode::K555,
-        OsCode::KEY_556 => KeyCode::K556,
-        OsCode::KEY_557 => KeyCode::K557,
-        OsCode::KEY_558 => KeyCode::K558,
-        OsCode::KEY_559 => KeyCode::K559,
-        OsCode::KEY_ALS_TOGGLE => KeyCode::K560,
-        OsCode::KEY_ROTATE_LOCK_TOGGLE => KeyCode::K561,
-        OsCode::KEY_562 => KeyCode::K562,
-        OsCode::KEY_563 => KeyCode::K563,
-        OsCode::KEY_564 => KeyCode::K564,
-        OsCode::KEY_565 => KeyCode::K565,
-        OsCode::KEY_566 => KeyCode::K566,
-        OsCode::KEY_567 => KeyCode::K567,
-        OsCode::KEY_568 => KeyCode::K568,
-        OsCode::KEY_569 => KeyCode::K569,
-        OsCode::KEY_570 => KeyCode::K570,
-        OsCode::KEY_571 => KeyCode::K571,
-        OsCode::KEY_572 => KeyCode::K572,
-        OsCode::KEY_573 => KeyCode::K573,
-        OsCode::KEY_574 => KeyCode::K574,
-        OsCode::KEY_575 => KeyCode::K575,
-        OsCode::KEY_BUTTONCONFIG => KeyCode::K576,
-        OsCode::KEY_TASKMANAGER => KeyCode::K577,
-        OsCode::KEY_JOURNAL => KeyCode::K578,
-        OsCode::KEY_CONTROLPANEL => KeyCode::K579,
-        OsCode::KEY_APPSELECT => KeyCode::K580,
-        OsCode::KEY_SCREENSAVER => KeyCode::K581,
-        OsCode::KEY_VOICECOMMAND => KeyCode::K582,
-        OsCode::KEY_ASSISTANT => KeyCode::K583,
-        OsCode::KEY_KBD_LAYOUT_NEXT => KeyCode::K584,
-        OsCode::KEY_585 => KeyCode::K585,
-        OsCode::KEY_586 => KeyCode::K586,
-        OsCode::KEY_587 => KeyCode::K587,
-        OsCode::KEY_588 => KeyCode::K588,
-        OsCode::KEY_589 => KeyCode::K589,
-        OsCode::KEY_590 => KeyCode::K590,
-        OsCode::KEY_591 => KeyCode::K591,
-        OsCode::KEY_BRIGHTNESS_MIN => KeyCode::K592,
-        OsCode::KEY_BRIGHTNESS_MAX => KeyCode::K593,
-        OsCode::KEY_594 => KeyCode::K594,
-        OsCode::KEY_595 => KeyCode::K595,
-        OsCode::KEY_596 => KeyCode::K596,
-        OsCode::KEY_597 => KeyCode::K597,
-        OsCode::KEY_598 => KeyCode::K598,
-        OsCode::KEY_599 => KeyCode::K599,
-        OsCode::KEY_600 => KeyCode::K600,
-        OsCode::KEY_601 => KeyCode::K601,
-        OsCode::KEY_602 => KeyCode::K602,
-        OsCode::KEY_603 => KeyCode::K603,
-        OsCode::KEY_604 => KeyCode::K604,
-        OsCode::KEY_605 => KeyCode::K605,
-        OsCode::KEY_606 => KeyCode::K606,
-        OsCode::KEY_607 => KeyCode::K607,
-        OsCode::KEY_KBDINPUTASSIST_PREV => KeyCode::K608,
-        OsCode::KEY_KBDINPUTASSIST_NEXT => KeyCode::K609,
-        OsCode::KEY_KBDINPUTASSIST_PREVGROUP => KeyCode::K610,
-        OsCode::KEY_KBDINPUTASSIST_NEXTGROUP => KeyCode::K611,
-        OsCode::KEY_KBDINPUTASSIST_ACCEPT => KeyCode::K612,
-        OsCode::KEY_KBDINPUTASSIST_CANCEL => KeyCode::K613,
-        OsCode::KEY_RIGHT_UP => KeyCode::K614,
-        OsCode::KEY_RIGHT_DOWN => KeyCode::K615,
-        OsCode::KEY_LEFT_UP => KeyCode::K616,
-        OsCode::KEY_LEFT_DOWN => KeyCode::K617,
-        OsCode::KEY_ROOT_MENU => KeyCode::K618,
-        OsCode::KEY_MEDIA_TOP_MENU => KeyCode::K619,
-        OsCode::KEY_NUMERIC_11 => KeyCode::K620,
-        OsCode::KEY_NUMERIC_12 => KeyCode::K621,
-        OsCode::KEY_AUDIO_DESC => KeyCode::K622,
-        OsCode::KEY_3D_MODE => KeyCode::K623,
-        OsCode::KEY_NEXT_FAVORITE => KeyCode::K624,
-        OsCode::KEY_STOP_RECORD => KeyCode::K625,
-        OsCode::KEY_PAUSE_RECORD => KeyCode::K626,
-        OsCode::KEY_VOD => KeyCode::K627,
-        OsCode::KEY_UNMUTE => KeyCode::K628,
-        OsCode::KEY_FASTREVERSE => KeyCode::K629,
-        OsCode::KEY_SLOWREVERSE => KeyCode::K630,
-        OsCode::KEY_DATA => KeyCode::K631,
-        OsCode::KEY_ONSCREEN_KEYBOARD => KeyCode::K632,
-        OsCode::KEY_633 => KeyCode::K633,
-        OsCode::KEY_634 => KeyCode::K634,
-        OsCode::KEY_635 => KeyCode::K635,
-        OsCode::KEY_636 => KeyCode::K636,
-        OsCode::KEY_637 => KeyCode::K637,
-        OsCode::KEY_638 => KeyCode::K638,
-        OsCode::KEY_639 => KeyCode::K639,
-        OsCode::KEY_640 => KeyCode::K640,
-        OsCode::KEY_641 => KeyCode::K641,
-        OsCode::KEY_642 => KeyCode::K642,
-        OsCode::KEY_643 => KeyCode::K643,
-        OsCode::KEY_644 => KeyCode::K644,
-        OsCode::KEY_645 => KeyCode::K645,
-        OsCode::KEY_646 => KeyCode::K646,
-        OsCode::KEY_647 => KeyCode::K647,
-        OsCode::KEY_648 => KeyCode::K648,
-        OsCode::KEY_649 => KeyCode::K649,
-        OsCode::KEY_650 => KeyCode::K650,
-        OsCode::KEY_651 => KeyCode::K651,
-        OsCode::KEY_652 => KeyCode::K652,
-        OsCode::KEY_653 => KeyCode::K653,
-        OsCode::KEY_654 => KeyCode::K654,
-        OsCode::KEY_655 => KeyCode::K655,
-        OsCode::KEY_656 => KeyCode::K656,
-        OsCode::KEY_657 => KeyCode::K657,
-        OsCode::KEY_658 => KeyCode::K658,
-        OsCode::KEY_659 => KeyCode::K659,
-        OsCode::KEY_660 => KeyCode::K660,
-        OsCode::KEY_661 => KeyCode::K661,
-        OsCode::KEY_662 => KeyCode::K662,
-        OsCode::KEY_663 => KeyCode::K663,
-        OsCode::KEY_664 => KeyCode::K664,
-        OsCode::KEY_665 => KeyCode::K665,
-        OsCode::KEY_666 => KeyCode::K666,
-        OsCode::KEY_667 => KeyCode::K667,
-        OsCode::KEY_668 => KeyCode::K668,
-        OsCode::KEY_669 => KeyCode::K669,
-        OsCode::KEY_670 => KeyCode::K670,
-        OsCode::KEY_671 => KeyCode::K671,
-        OsCode::KEY_672 => KeyCode::K672,
-        OsCode::KEY_673 => KeyCode::K673,
-        OsCode::KEY_674 => KeyCode::K674,
-        OsCode::KEY_675 => KeyCode::K675,
-        OsCode::KEY_676 => KeyCode::K676,
-        OsCode::KEY_677 => KeyCode::K677,
-        OsCode::KEY_678 => KeyCode::K678,
-        OsCode::KEY_679 => KeyCode::K679,
-        OsCode::KEY_680 => KeyCode::K680,
-        OsCode::KEY_681 => KeyCode::K681,
-        OsCode::KEY_682 => KeyCode::K682,
-        OsCode::KEY_683 => KeyCode::K683,
-        OsCode::KEY_684 => KeyCode::K684,
-        OsCode::KEY_685 => KeyCode::K685,
-        OsCode::KEY_686 => KeyCode::K686,
-        OsCode::KEY_687 => KeyCode::K687,
-        OsCode::KEY_688 => KeyCode::K688,
-        OsCode::KEY_689 => KeyCode::K689,
-        OsCode::KEY_690 => KeyCode::K690,
-        OsCode::KEY_691 => KeyCode::K691,
-        OsCode::KEY_692 => KeyCode::K692,
-        OsCode::KEY_693 => KeyCode::K693,
-        OsCode::KEY_694 => KeyCode::K694,
-        OsCode::KEY_695 => KeyCode::K695,
-        OsCode::KEY_696 => KeyCode::K696,
-        OsCode::KEY_697 => KeyCode::K697,
-        OsCode::KEY_698 => KeyCode::K698,
-        OsCode::KEY_699 => KeyCode::K699,
-        OsCode::KEY_700 => KeyCode::K700,
-        OsCode::KEY_701 => KeyCode::K701,
-        OsCode::KEY_702 => KeyCode::K702,
-        OsCode::KEY_703 => KeyCode::K703,
-        OsCode::BTN_TRIGGER_HAPPY1 => KeyCode::K704,
-        OsCode::BTN_TRIGGER_HAPPY2 => KeyCode::K705,
-        OsCode::BTN_TRIGGER_HAPPY3 => KeyCode::K706,
-        OsCode::BTN_TRIGGER_HAPPY4 => KeyCode::K707,
-        OsCode::BTN_TRIGGER_HAPPY5 => KeyCode::K708,
-        OsCode::BTN_TRIGGER_HAPPY6 => KeyCode::K709,
-        OsCode::BTN_TRIGGER_HAPPY7 => KeyCode::K710,
-        OsCode::BTN_TRIGGER_HAPPY8 => KeyCode::K711,
-        OsCode::BTN_TRIGGER_HAPPY9 => KeyCode::K712,
-        OsCode::BTN_TRIGGER_HAPPY10 => KeyCode::K713,
-        OsCode::BTN_TRIGGER_HAPPY11 => KeyCode::K714,
-        OsCode::BTN_TRIGGER_HAPPY12 => KeyCode::K715,
-        OsCode::BTN_TRIGGER_HAPPY13 => KeyCode::K716,
-        OsCode::BTN_TRIGGER_HAPPY14 => KeyCode::K717,
-        OsCode::BTN_TRIGGER_HAPPY15 => KeyCode::K718,
-        OsCode::BTN_TRIGGER_HAPPY16 => KeyCode::K719,
-        OsCode::BTN_TRIGGER_HAPPY17 => KeyCode::K720,
-        OsCode::BTN_TRIGGER_HAPPY18 => KeyCode::K721,
-        OsCode::BTN_TRIGGER_HAPPY19 => KeyCode::K722,
-        OsCode::BTN_TRIGGER_HAPPY20 => KeyCode::K723,
-        OsCode::BTN_TRIGGER_HAPPY21 => KeyCode::K724,
-        OsCode::BTN_TRIGGER_HAPPY22 => KeyCode::K725,
-        OsCode::BTN_TRIGGER_HAPPY23 => KeyCode::K726,
-        OsCode::BTN_TRIGGER_HAPPY24 => KeyCode::K727,
-        OsCode::BTN_TRIGGER_HAPPY25 => KeyCode::K728,
-        OsCode::BTN_TRIGGER_HAPPY26 => KeyCode::K729,
-        OsCode::BTN_TRIGGER_HAPPY27 => KeyCode::K730,
-        OsCode::BTN_TRIGGER_HAPPY28 => KeyCode::K731,
-        OsCode::BTN_TRIGGER_HAPPY29 => KeyCode::K732,
-        OsCode::BTN_TRIGGER_HAPPY30 => KeyCode::K733,
-        OsCode::BTN_TRIGGER_HAPPY31 => KeyCode::K734,
-        OsCode::BTN_TRIGGER_HAPPY32 => KeyCode::K735,
-        OsCode::BTN_TRIGGER_HAPPY33 => KeyCode::K736,
-        OsCode::BTN_TRIGGER_HAPPY34 => KeyCode::K737,
-        OsCode::BTN_TRIGGER_HAPPY35 => KeyCode::K738,
-        OsCode::BTN_TRIGGER_HAPPY36 => KeyCode::K739,
-        OsCode::BTN_TRIGGER_HAPPY37 => KeyCode::K740,
-        OsCode::BTN_TRIGGER_HAPPY38 => KeyCode::K741,
-        OsCode::BTN_TRIGGER_HAPPY39 => KeyCode::K742,
-        OsCode::BTN_TRIGGER_HAPPY40 => KeyCode::K743,
-        OsCode::BTN_MAX => KeyCode::K744,
-        _ => KeyCode::No,
-    }
-}
+#[test]
+fn roundtrip_oscode_keycode() {
+    use super::OsCode::*;
+    let oscs = &[
+        KEY_RESERVED,
+        KEY_ESC,
+        KEY_1,
+        KEY_2,
+        KEY_3,
+        KEY_4,
+        KEY_5,
+        KEY_6,
+        KEY_7,
+        KEY_8,
+        KEY_9,
+        KEY_0,
+        KEY_MINUS,
+        KEY_EQUAL,
+        KEY_BACKSPACE,
+        KEY_TAB,
+        KEY_Q,
+        KEY_W,
+        KEY_E,
+        KEY_R,
+        KEY_T,
+        KEY_Y,
+        KEY_U,
+        KEY_I,
+        KEY_O,
+        KEY_P,
+        KEY_LEFTBRACE,
+        KEY_RIGHTBRACE,
+        KEY_ENTER,
+        KEY_LEFTCTRL,
+        KEY_A,
+        KEY_S,
+        KEY_D,
+        KEY_F,
+        KEY_G,
+        KEY_H,
+        KEY_J,
+        KEY_K,
+        KEY_L,
+        KEY_SEMICOLON,
+        KEY_APOSTROPHE,
+        KEY_GRAVE,
+        KEY_LEFTSHIFT,
+        KEY_BACKSLASH,
+        KEY_Z,
+        KEY_X,
+        KEY_C,
+        KEY_V,
+        KEY_B,
+        KEY_N,
+        KEY_M,
+        KEY_COMMA,
+        KEY_DOT,
+        KEY_SLASH,
+        KEY_RIGHTSHIFT,
+        KEY_KPASTERISK,
+        KEY_LEFTALT,
+        KEY_SPACE,
+        KEY_CAPSLOCK,
+        KEY_F1,
+        KEY_F2,
+        KEY_F3,
+        KEY_F4,
+        KEY_F5,
+        KEY_F6,
+        KEY_F7,
+        KEY_F8,
+        KEY_F9,
+        KEY_F10,
+        KEY_NUMLOCK,
+        KEY_SCROLLLOCK,
+        KEY_KP7,
+        KEY_KP8,
+        KEY_KP9,
+        KEY_KPMINUS,
+        KEY_KP4,
+        KEY_KP5,
+        KEY_KP6,
+        KEY_KPPLUS,
+        KEY_KP1,
+        KEY_KP2,
+        KEY_KP3,
+        KEY_KP0,
+        KEY_KPDOT,
+        KEY_84,
+        KEY_ZENKAKUHANKAKU,
+        KEY_102ND,
+        KEY_F11,
+        KEY_F12,
+        KEY_RO,
+        KEY_KATAKANA,
+        KEY_HIRAGANA,
+        KEY_HENKAN,
+        KEY_KATAKANAHIRAGANA,
+        KEY_MUHENKAN,
+        KEY_KPJPCOMMA,
+        KEY_KPENTER,
+        KEY_RIGHTCTRL,
+        KEY_KPSLASH,
+        KEY_SYSRQ,
+        KEY_RIGHTALT,
+        KEY_LINEFEED,
+        KEY_HOME,
+        KEY_UP,
+        KEY_PAGEUP,
+        KEY_LEFT,
+        KEY_RIGHT,
+        KEY_END,
+        KEY_DOWN,
+        KEY_PAGEDOWN,
+        KEY_INSERT,
+        KEY_DELETE,
+        KEY_MACRO,
+        KEY_MUTE,
+        KEY_VOLUMEDOWN,
+        KEY_VOLUMEUP,
+        KEY_POWER,
+        KEY_KPEQUAL,
+        KEY_KPPLUSMINUS,
+        KEY_PAUSE,
+        KEY_SCALE,
+        KEY_KPCOMMA,
+        KEY_HANGEUL,
+        KEY_HANJA,
+        KEY_YEN,
+        KEY_LEFTMETA,
+        KEY_RIGHTMETA,
+        KEY_COMPOSE,
+        KEY_STOP,
+        KEY_AGAIN,
+        KEY_PROPS,
+        KEY_UNDO,
+        KEY_FRONT,
+        KEY_COPY,
+        KEY_OPEN,
+        KEY_PASTE,
+        KEY_FIND,
+        KEY_CUT,
+        KEY_HELP,
+        KEY_MENU,
+        KEY_CALC,
+        KEY_SETUP,
+        KEY_SLEEP,
+        KEY_WAKEUP,
+        KEY_FILE,
+        KEY_SENDFILE,
+        KEY_DELETEFILE,
+        KEY_XFER,
+        KEY_PROG1,
+        KEY_PROG2,
+        KEY_WWW,
+        KEY_MSDOS,
+        KEY_COFFEE,
+        KEY_ROTATE_DISPLAY,
+        KEY_CYCLEWINDOWS,
+        KEY_MAIL,
+        KEY_BOOKMARKS,
+        KEY_COMPUTER,
+        KEY_BACK,
+        KEY_FORWARD,
+        KEY_CLOSECD,
+        KEY_EJECTCD,
+        KEY_EJECTCLOSECD,
+        KEY_NEXTSONG,
+        KEY_PLAYPAUSE,
+        KEY_PREVIOUSSONG,
+        KEY_STOPCD,
+        KEY_RECORD,
+        KEY_REWIND,
+        KEY_PHONE,
+        KEY_ISO,
+        KEY_CONFIG,
+        KEY_HOMEPAGE,
+        KEY_REFRESH,
+        KEY_EXIT,
+        KEY_MOVE,
+        KEY_EDIT,
+        KEY_SCROLLUP,
+        KEY_SCROLLDOWN,
+        KEY_KPLEFTPAREN,
+        KEY_KPRIGHTPAREN,
+        KEY_NEW,
+        KEY_REDO,
+        KEY_F13,
+        KEY_F14,
+        KEY_F15,
+        KEY_F16,
+        KEY_F17,
+        KEY_F18,
+        KEY_F19,
+        KEY_F20,
+        KEY_F21,
+        KEY_F22,
+        KEY_F23,
+        KEY_F24,
+        KEY_195,
+        KEY_196,
+        KEY_197,
+        KEY_198,
+        KEY_199,
+        KEY_PLAYCD,
+        KEY_PAUSECD,
+        KEY_PROG3,
+        KEY_PROG4,
+        KEY_DASHBOARD,
+        KEY_SUSPEND,
+        KEY_CLOSE,
+        KEY_PLAY,
+        KEY_FASTFORWARD,
+        KEY_BASSBOOST,
+        KEY_PRINT,
+        KEY_HP,
+        KEY_CAMERA,
+        KEY_SOUND,
+        KEY_QUESTION,
+        KEY_EMAIL,
+        KEY_CHAT,
+        KEY_SEARCH,
+        KEY_CONNECT,
+        KEY_FINANCE,
+        KEY_SPORT,
+        KEY_SHOP,
+        KEY_ALTERASE,
+        KEY_CANCEL,
+        KEY_BRIGHTNESSDOWN,
+        KEY_BRIGHTNESSUP,
+        KEY_MEDIA,
+        KEY_SWITCHVIDEOMODE,
+        KEY_KBDILLUMTOGGLE,
+        KEY_KBDILLUMDOWN,
+        KEY_KBDILLUMUP,
+        KEY_SEND,
+        KEY_REPLY,
+        KEY_FORWARDMAIL,
+        KEY_SAVE,
+        KEY_DOCUMENTS,
+        KEY_BATTERY,
+        KEY_BLUETOOTH,
+        KEY_WLAN,
+        KEY_UWB,
+        KEY_UNKNOWN,
+        KEY_VIDEO_NEXT,
+        KEY_VIDEO_PREV,
+        KEY_BRIGHTNESS_CYCLE,
+        KEY_BRIGHTNESS_AUTO,
+        KEY_DISPLAY_OFF,
+        KEY_WWAN,
+        KEY_RFKILL,
+        KEY_MICMUTE,
+        KEY_249,
+        KEY_250,
+        KEY_251,
+        KEY_252,
+        KEY_253,
+        KEY_254,
+        KEY_255,
+        BTN_0,
+        BTN_1,
+        BTN_2,
+        BTN_3,
+        BTN_4,
+        BTN_5,
+        BTN_6,
+        BTN_7,
+        BTN_8,
+        BTN_9,
+        KEY_266,
+        KEY_267,
+        KEY_268,
+        KEY_269,
+        KEY_270,
+        KEY_271,
+        BTN_LEFT,
+        BTN_RIGHT,
+        BTN_MIDDLE,
+        BTN_SIDE,
+        BTN_EXTRA,
+        BTN_FORWARD,
+        BTN_BACK,
+        BTN_TASK,
+        KEY_280,
+        KEY_281,
+        KEY_282,
+        KEY_283,
+        KEY_284,
+        KEY_285,
+        KEY_286,
+        KEY_287,
+        BTN_TRIGGER,
+        BTN_THUMB,
+        BTN_THUMB2,
+        BTN_TOP,
+        BTN_TOP2,
+        BTN_PINKIE,
+        BTN_BASE,
+        BTN_BASE2,
+        BTN_BASE3,
+        BTN_BASE4,
+        BTN_BASE5,
+        BTN_BASE6,
+        KEY_300,
+        KEY_301,
+        KEY_302,
+        BTN_DEAD,
+        BTN_SOUTH,
+        BTN_EAST,
+        BTN_C,
+        BTN_NORTH,
+        BTN_WEST,
+        BTN_Z,
+        BTN_TL,
+        BTN_TR,
+        BTN_TL2,
+        BTN_TR2,
+        BTN_SELECT,
+        BTN_START,
+        BTN_MODE,
+        BTN_THUMBL,
+        BTN_THUMBR,
+        KEY_319,
+        BTN_TOOL_PEN,
+        BTN_TOOL_RUBBER,
+        BTN_TOOL_BRUSH,
+        BTN_TOOL_PENCIL,
+        BTN_TOOL_AIRBRUSH,
+        BTN_TOOL_FINGER,
+        BTN_TOOL_MOUSE,
+        BTN_TOOL_LENS,
+        BTN_TOOL_QUINTTAP,
+        BTN_STYLUS3,
+        BTN_TOUCH,
+        BTN_STYLUS,
+        BTN_STYLUS2,
+        BTN_TOOL_DOUBLETAP,
+        BTN_TOOL_TRIPLETAP,
+        BTN_TOOL_QUADTAP,
+        BTN_GEAR_DOWN,
+        BTN_GEAR_UP,
+        KEY_338,
+        KEY_339,
+        KEY_340,
+        KEY_341,
+        KEY_342,
+        KEY_343,
+        KEY_344,
+        KEY_345,
+        KEY_346,
+        KEY_347,
+        KEY_348,
+        KEY_349,
+        KEY_350,
+        KEY_351,
+        KEY_OK,
+        KEY_SELECT,
+        KEY_GOTO,
+        KEY_CLEAR,
+        KEY_POWER2,
+        KEY_OPTION,
+        KEY_INFO,
+        KEY_TIME,
+        KEY_VENDOR,
+        KEY_ARCHIVE,
+        KEY_PROGRAM,
+        KEY_CHANNEL,
+        KEY_FAVORITES,
+        KEY_EPG,
+        KEY_PVR,
+        KEY_MHP,
+        KEY_LANGUAGE,
+        KEY_TITLE,
+        KEY_SUBTITLE,
+        KEY_ANGLE,
+        KEY_FULL_SCREEN,
+        KEY_MODE,
+        KEY_KEYBOARD,
+        KEY_ASPECT_RATIO,
+        KEY_PC,
+        KEY_TV,
+        KEY_TV2,
+        KEY_VCR,
+        KEY_VCR2,
+        KEY_SAT,
+        KEY_SAT2,
+        KEY_CD,
+        KEY_TAPE,
+        KEY_RADIO,
+        KEY_TUNER,
+        KEY_PLAYER,
+        KEY_TEXT,
+        KEY_DVD,
+        KEY_AUX,
+        KEY_MP3,
+        KEY_AUDIO,
+        KEY_VIDEO,
+        KEY_DIRECTORY,
+        KEY_LIST,
+        KEY_MEMO,
+        KEY_CALENDAR,
+        KEY_RED,
+        KEY_GREEN,
+        KEY_YELLOW,
+        KEY_BLUE,
+        KEY_CHANNELUP,
+        KEY_CHANNELDOWN,
+        KEY_FIRST,
+        KEY_LAST,
+        KEY_AB,
+        KEY_NEXT,
+        KEY_RESTART,
+        KEY_SLOW,
+        KEY_SHUFFLE,
+        KEY_BREAK,
+        KEY_PREVIOUS,
+        KEY_DIGITS,
+        KEY_TEEN,
+        KEY_TWEN,
+        KEY_VIDEOPHONE,
+        KEY_GAMES,
+        KEY_ZOOMIN,
+        KEY_ZOOMOUT,
+        KEY_ZOOMRESET,
+        KEY_WORDPROCESSOR,
+        KEY_EDITOR,
+        KEY_SPREADSHEET,
+        KEY_GRAPHICSEDITOR,
+        KEY_PRESENTATION,
+        KEY_DATABASE,
+        KEY_NEWS,
+        KEY_VOICEMAIL,
+        KEY_ADDRESSBOOK,
+        KEY_MESSENGER,
+        KEY_DISPLAYTOGGLE,
+        KEY_SPELLCHECK,
+        KEY_LOGOFF,
+        KEY_DOLLAR,
+        KEY_EURO,
+        KEY_FRAMEBACK,
+        KEY_FRAMEFORWARD,
+        KEY_CONTEXT_MENU,
+        KEY_MEDIA_REPEAT,
+        KEY_10CHANNELSUP,
+        KEY_10CHANNELSDOWN,
+        KEY_IMAGES,
+        KEY_443,
+        KEY_444,
+        KEY_445,
+        KEY_446,
+        KEY_447,
+        KEY_DEL_EOL,
+        KEY_DEL_EOS,
+        KEY_INS_LINE,
+        KEY_DEL_LINE,
+        KEY_452,
+        KEY_453,
+        KEY_454,
+        KEY_455,
+        KEY_456,
+        KEY_457,
+        KEY_458,
+        KEY_459,
+        KEY_460,
+        KEY_461,
+        KEY_462,
+        KEY_463,
+        KEY_FN,
+        KEY_FN_ESC,
+        KEY_FN_F1,
+        KEY_FN_F2,
+        KEY_FN_F3,
+        KEY_FN_F4,
+        KEY_FN_F5,
+        KEY_FN_F6,
+        KEY_FN_F7,
+        KEY_FN_F8,
+        KEY_FN_F9,
+        KEY_FN_F10,
+        KEY_FN_F11,
+        KEY_FN_F12,
+        KEY_FN_1,
+        KEY_FN_2,
+        KEY_FN_D,
+        KEY_FN_E,
+        KEY_FN_F,
+        KEY_FN_S,
+        KEY_FN_B,
+        KEY_485,
+        KEY_486,
+        KEY_487,
+        KEY_488,
+        KEY_489,
+        KEY_490,
+        KEY_491,
+        KEY_492,
+        KEY_493,
+        KEY_494,
+        KEY_495,
+        KEY_496,
+        KEY_BRL_DOT1,
+        KEY_BRL_DOT2,
+        KEY_BRL_DOT3,
+        KEY_BRL_DOT4,
+        KEY_BRL_DOT5,
+        KEY_BRL_DOT6,
+        KEY_BRL_DOT7,
+        KEY_BRL_DOT8,
+        KEY_BRL_DOT9,
+        KEY_BRL_DOT10,
+        KEY_507,
+        KEY_508,
+        KEY_509,
+        KEY_510,
+        KEY_511,
+        KEY_NUMERIC_0,
+        KEY_NUMERIC_1,
+        KEY_NUMERIC_2,
+        KEY_NUMERIC_3,
+        KEY_NUMERIC_4,
+        KEY_NUMERIC_5,
+        KEY_NUMERIC_6,
+        KEY_NUMERIC_7,
+        KEY_NUMERIC_8,
+        KEY_NUMERIC_9,
+        KEY_NUMERIC_STAR,
+        KEY_NUMERIC_POUND,
+        KEY_NUMERIC_A,
+        KEY_NUMERIC_B,
+        KEY_NUMERIC_C,
+        KEY_NUMERIC_D,
+        KEY_CAMERA_FOCUS,
+        KEY_WPS_BUTTON,
+        KEY_TOUCHPAD_TOGGLE,
+        KEY_TOUCHPAD_ON,
+        KEY_TOUCHPAD_OFF,
+        KEY_CAMERA_ZOOMIN,
+        KEY_CAMERA_ZOOMOUT,
+        KEY_CAMERA_UP,
+        KEY_CAMERA_DOWN,
+        KEY_CAMERA_LEFT,
+        KEY_CAMERA_RIGHT,
+        KEY_ATTENDANT_ON,
+        KEY_ATTENDANT_OFF,
+        KEY_ATTENDANT_TOGGLE,
+        KEY_LIGHTS_TOGGLE,
+        KEY_543,
+        BTN_DPAD_UP,
+        BTN_DPAD_DOWN,
+        BTN_DPAD_LEFT,
+        BTN_DPAD_RIGHT,
+        KEY_548,
+        KEY_549,
+        KEY_550,
+        KEY_551,
+        KEY_552,
+        KEY_553,
+        KEY_554,
+        KEY_555,
+        KEY_556,
+        KEY_557,
+        KEY_558,
+        KEY_559,
+        KEY_ALS_TOGGLE,
+        KEY_ROTATE_LOCK_TOGGLE,
+        KEY_562,
+        KEY_563,
+        KEY_564,
+        KEY_565,
+        KEY_566,
+        KEY_567,
+        KEY_568,
+        KEY_569,
+        KEY_570,
+        KEY_571,
+        KEY_572,
+        KEY_573,
+        KEY_574,
+        KEY_575,
+        KEY_BUTTONCONFIG,
+        KEY_TASKMANAGER,
+        KEY_JOURNAL,
+        KEY_CONTROLPANEL,
+        KEY_APPSELECT,
+        KEY_SCREENSAVER,
+        KEY_VOICECOMMAND,
+        KEY_ASSISTANT,
+        KEY_KBD_LAYOUT_NEXT,
+        KEY_585,
+        KEY_586,
+        KEY_587,
+        KEY_588,
+        KEY_589,
+        KEY_590,
+        KEY_591,
+        KEY_BRIGHTNESS_MIN,
+        KEY_BRIGHTNESS_MAX,
+        KEY_594,
+        KEY_595,
+        KEY_596,
+        KEY_597,
+        KEY_598,
+        KEY_599,
+        KEY_600,
+        KEY_601,
+        KEY_602,
+        KEY_603,
+        KEY_604,
+        KEY_605,
+        KEY_606,
+        KEY_607,
+        KEY_KBDINPUTASSIST_PREV,
+        KEY_KBDINPUTASSIST_NEXT,
+        KEY_KBDINPUTASSIST_PREVGROUP,
+        KEY_KBDINPUTASSIST_NEXTGROUP,
+        KEY_KBDINPUTASSIST_ACCEPT,
+        KEY_KBDINPUTASSIST_CANCEL,
+        KEY_RIGHT_UP,
+        KEY_RIGHT_DOWN,
+        KEY_LEFT_UP,
+        KEY_LEFT_DOWN,
+        KEY_ROOT_MENU,
+        KEY_MEDIA_TOP_MENU,
+        KEY_NUMERIC_11,
+        KEY_NUMERIC_12,
+        KEY_AUDIO_DESC,
+        KEY_3D_MODE,
+        KEY_NEXT_FAVORITE,
+        KEY_STOP_RECORD,
+        KEY_PAUSE_RECORD,
+        KEY_VOD,
+        KEY_UNMUTE,
+        KEY_FASTREVERSE,
+        KEY_SLOWREVERSE,
+        KEY_DATA,
+        KEY_ONSCREEN_KEYBOARD,
+        KEY_633,
+        KEY_634,
+        KEY_635,
+        KEY_636,
+        KEY_637,
+        KEY_638,
+        KEY_639,
+        KEY_640,
+        KEY_641,
+        KEY_642,
+        KEY_643,
+        KEY_644,
+        KEY_645,
+        KEY_646,
+        KEY_647,
+        KEY_648,
+        KEY_649,
+        KEY_650,
+        KEY_651,
+        KEY_652,
+        KEY_653,
+        KEY_654,
+        KEY_655,
+        KEY_656,
+        KEY_657,
+        KEY_658,
+        KEY_659,
+        KEY_660,
+        KEY_661,
+        KEY_662,
+        KEY_663,
+        KEY_664,
+        KEY_665,
+        KEY_666,
+        KEY_667,
+        KEY_668,
+        KEY_669,
+        KEY_670,
+        KEY_671,
+        KEY_672,
+        KEY_673,
+        KEY_674,
+        KEY_675,
+        KEY_676,
+        KEY_677,
+        KEY_678,
+        KEY_679,
+        KEY_680,
+        KEY_681,
+        KEY_682,
+        KEY_683,
+        KEY_684,
+        KEY_685,
+        KEY_686,
+        KEY_687,
+        KEY_688,
+        KEY_689,
+        KEY_690,
+        KEY_691,
+        KEY_692,
+        KEY_693,
+        KEY_694,
+        KEY_695,
+        KEY_696,
+        KEY_697,
+        KEY_698,
+        KEY_699,
+        KEY_700,
+        KEY_701,
+        KEY_702,
+        KEY_703,
+        BTN_TRIGGER_HAPPY1,
+        BTN_TRIGGER_HAPPY2,
+        BTN_TRIGGER_HAPPY3,
+        BTN_TRIGGER_HAPPY4,
+        BTN_TRIGGER_HAPPY5,
+        BTN_TRIGGER_HAPPY6,
+        BTN_TRIGGER_HAPPY7,
+        BTN_TRIGGER_HAPPY8,
+        BTN_TRIGGER_HAPPY9,
+        BTN_TRIGGER_HAPPY10,
+        BTN_TRIGGER_HAPPY11,
+        BTN_TRIGGER_HAPPY12,
+        BTN_TRIGGER_HAPPY13,
+        BTN_TRIGGER_HAPPY14,
+        BTN_TRIGGER_HAPPY15,
+        BTN_TRIGGER_HAPPY16,
+        BTN_TRIGGER_HAPPY17,
+        BTN_TRIGGER_HAPPY18,
+        BTN_TRIGGER_HAPPY19,
+        BTN_TRIGGER_HAPPY20,
+        BTN_TRIGGER_HAPPY21,
+        BTN_TRIGGER_HAPPY22,
+        BTN_TRIGGER_HAPPY23,
+        BTN_TRIGGER_HAPPY24,
+        BTN_TRIGGER_HAPPY25,
+        BTN_TRIGGER_HAPPY26,
+        BTN_TRIGGER_HAPPY27,
+        BTN_TRIGGER_HAPPY28,
+        BTN_TRIGGER_HAPPY29,
+        BTN_TRIGGER_HAPPY30,
+        BTN_TRIGGER_HAPPY31,
+        BTN_TRIGGER_HAPPY32,
+        BTN_TRIGGER_HAPPY33,
+        BTN_TRIGGER_HAPPY34,
+        BTN_TRIGGER_HAPPY35,
+        BTN_TRIGGER_HAPPY36,
+        BTN_TRIGGER_HAPPY37,
+        BTN_TRIGGER_HAPPY38,
+        BTN_TRIGGER_HAPPY39,
+        BTN_TRIGGER_HAPPY40,
+        BTN_MAX,
+        MouseWheelUp,
+        MouseWheelDown,
+        MouseWheelLeft,
+        MouseWheelRight,
+        KEY_749,
+        KEY_750,
+        KEY_751,
+        KEY_752,
+        KEY_753,
+        KEY_754,
+        KEY_755,
+        KEY_756,
+        KEY_757,
+        KEY_758,
+        KEY_759,
+        KEY_760,
+        KEY_761,
+        KEY_762,
+        KEY_763,
+        KEY_764,
+        KEY_765,
+        KEY_766,
+        KEY_MAX,
+    ];
 
-fn haphazard_kc_to_osc_mappings(kc: KeyCode) -> OsCode {
-    match kc {
-        KeyCode::K252 => OsCode::KEY_252,
-        KeyCode::K253 => OsCode::KEY_253,
-        KeyCode::K254 => OsCode::KEY_254,
-        KeyCode::K255 => OsCode::KEY_255,
-        KeyCode::K256 => OsCode::BTN_0,
-        KeyCode::K257 => OsCode::BTN_1,
-        KeyCode::K258 => OsCode::BTN_2,
-        KeyCode::K259 => OsCode::BTN_3,
-        KeyCode::K260 => OsCode::BTN_4,
-        KeyCode::K261 => OsCode::BTN_5,
-        KeyCode::K262 => OsCode::BTN_6,
-        KeyCode::K263 => OsCode::BTN_7,
-        KeyCode::K264 => OsCode::BTN_8,
-        KeyCode::K265 => OsCode::BTN_9,
-        KeyCode::K266 => OsCode::KEY_266,
-        KeyCode::K267 => OsCode::KEY_267,
-        KeyCode::K268 => OsCode::KEY_268,
-        KeyCode::K269 => OsCode::KEY_269,
-        KeyCode::K270 => OsCode::KEY_270,
-        KeyCode::K271 => OsCode::KEY_271,
-        KeyCode::K272 => OsCode::BTN_LEFT,
-        KeyCode::K273 => OsCode::BTN_RIGHT,
-        KeyCode::K274 => OsCode::BTN_MIDDLE,
-        KeyCode::K275 => OsCode::BTN_SIDE,
-        KeyCode::K276 => OsCode::BTN_EXTRA,
-        KeyCode::K277 => OsCode::BTN_FORWARD,
-        KeyCode::K278 => OsCode::BTN_BACK,
-        KeyCode::K279 => OsCode::BTN_TASK,
-        KeyCode::K280 => OsCode::KEY_280,
-        KeyCode::K281 => OsCode::KEY_281,
-        KeyCode::K282 => OsCode::KEY_282,
-        KeyCode::K283 => OsCode::KEY_283,
-        KeyCode::K284 => OsCode::KEY_284,
-        KeyCode::K285 => OsCode::KEY_285,
-        KeyCode::K286 => OsCode::KEY_286,
-        KeyCode::K287 => OsCode::KEY_287,
-        KeyCode::K288 => OsCode::BTN_TRIGGER,
-        KeyCode::K289 => OsCode::BTN_THUMB,
-        KeyCode::K290 => OsCode::BTN_THUMB2,
-        KeyCode::K291 => OsCode::BTN_TOP,
-        KeyCode::K292 => OsCode::BTN_TOP2,
-        KeyCode::K293 => OsCode::BTN_PINKIE,
-        KeyCode::K294 => OsCode::BTN_BASE,
-        KeyCode::K295 => OsCode::BTN_BASE2,
-        KeyCode::K296 => OsCode::BTN_BASE3,
-        KeyCode::K297 => OsCode::BTN_BASE4,
-        KeyCode::K298 => OsCode::BTN_BASE5,
-        KeyCode::K299 => OsCode::BTN_BASE6,
-        KeyCode::K300 => OsCode::KEY_300,
-        KeyCode::K301 => OsCode::KEY_301,
-        KeyCode::K302 => OsCode::KEY_302,
-        KeyCode::K303 => OsCode::BTN_DEAD,
-        KeyCode::K304 => OsCode::BTN_SOUTH,
-        KeyCode::K305 => OsCode::BTN_EAST,
-        KeyCode::K306 => OsCode::BTN_C,
-        KeyCode::K307 => OsCode::BTN_NORTH,
-        KeyCode::K308 => OsCode::BTN_WEST,
-        KeyCode::K309 => OsCode::BTN_Z,
-        KeyCode::K310 => OsCode::BTN_TL,
-        KeyCode::K311 => OsCode::BTN_TR,
-        KeyCode::K312 => OsCode::BTN_TL2,
-        KeyCode::K313 => OsCode::BTN_TR2,
-        KeyCode::K314 => OsCode::BTN_SELECT,
-        KeyCode::K315 => OsCode::BTN_START,
-        KeyCode::K316 => OsCode::BTN_MODE,
-        KeyCode::K317 => OsCode::BTN_THUMBL,
-        KeyCode::K318 => OsCode::BTN_THUMBR,
-        KeyCode::K319 => OsCode::KEY_319,
-        KeyCode::K320 => OsCode::BTN_TOOL_PEN,
-        KeyCode::K321 => OsCode::BTN_TOOL_RUBBER,
-        KeyCode::K322 => OsCode::BTN_TOOL_BRUSH,
-        KeyCode::K323 => OsCode::BTN_TOOL_PENCIL,
-        KeyCode::K324 => OsCode::BTN_TOOL_AIRBRUSH,
-        KeyCode::K325 => OsCode::BTN_TOOL_FINGER,
-        KeyCode::K326 => OsCode::BTN_TOOL_MOUSE,
-        KeyCode::K327 => OsCode::BTN_TOOL_LENS,
-        KeyCode::K328 => OsCode::BTN_TOOL_QUINTTAP,
-        KeyCode::K329 => OsCode::BTN_STYLUS3,
-        KeyCode::K330 => OsCode::BTN_TOUCH,
-        KeyCode::K331 => OsCode::BTN_STYLUS,
-        KeyCode::K332 => OsCode::BTN_STYLUS2,
-        KeyCode::K333 => OsCode::BTN_TOOL_DOUBLETAP,
-        KeyCode::K334 => OsCode::BTN_TOOL_TRIPLETAP,
-        KeyCode::K335 => OsCode::BTN_TOOL_QUADTAP,
-        KeyCode::K336 => OsCode::BTN_GEAR_DOWN,
-        KeyCode::K337 => OsCode::BTN_GEAR_UP,
-        KeyCode::K338 => OsCode::KEY_338,
-        KeyCode::K339 => OsCode::KEY_339,
-        KeyCode::K340 => OsCode::KEY_340,
-        KeyCode::K341 => OsCode::KEY_341,
-        KeyCode::K342 => OsCode::KEY_342,
-        KeyCode::K343 => OsCode::KEY_343,
-        KeyCode::K344 => OsCode::KEY_344,
-        KeyCode::K345 => OsCode::KEY_345,
-        KeyCode::K346 => OsCode::KEY_346,
-        KeyCode::K347 => OsCode::KEY_347,
-        KeyCode::K348 => OsCode::KEY_348,
-        KeyCode::K349 => OsCode::KEY_349,
-        KeyCode::K350 => OsCode::KEY_350,
-        KeyCode::K351 => OsCode::KEY_351,
-        KeyCode::K352 => OsCode::KEY_OK,
-        KeyCode::K353 => OsCode::KEY_SELECT,
-        KeyCode::K354 => OsCode::KEY_GOTO,
-        KeyCode::K355 => OsCode::KEY_CLEAR,
-        KeyCode::K356 => OsCode::KEY_POWER2,
-        KeyCode::K357 => OsCode::KEY_OPTION,
-        KeyCode::K358 => OsCode::KEY_INFO,
-        KeyCode::K359 => OsCode::KEY_TIME,
-        KeyCode::K360 => OsCode::KEY_VENDOR,
-        KeyCode::K361 => OsCode::KEY_ARCHIVE,
-        KeyCode::K362 => OsCode::KEY_PROGRAM,
-        KeyCode::K363 => OsCode::KEY_CHANNEL,
-        KeyCode::K364 => OsCode::KEY_FAVORITES,
-        KeyCode::K365 => OsCode::KEY_EPG,
-        KeyCode::K366 => OsCode::KEY_PVR,
-        KeyCode::K367 => OsCode::KEY_MHP,
-        KeyCode::K368 => OsCode::KEY_LANGUAGE,
-        KeyCode::K369 => OsCode::KEY_TITLE,
-        KeyCode::K370 => OsCode::KEY_SUBTITLE,
-        KeyCode::K371 => OsCode::KEY_ANGLE,
-        KeyCode::K372 => OsCode::KEY_FULL_SCREEN,
-        KeyCode::K373 => OsCode::KEY_MODE,
-        KeyCode::K374 => OsCode::KEY_KEYBOARD,
-        KeyCode::K375 => OsCode::KEY_ASPECT_RATIO,
-        KeyCode::K376 => OsCode::KEY_PC,
-        KeyCode::K377 => OsCode::KEY_TV,
-        KeyCode::K378 => OsCode::KEY_TV2,
-        KeyCode::K379 => OsCode::KEY_VCR,
-        KeyCode::K380 => OsCode::KEY_VCR2,
-        KeyCode::K381 => OsCode::KEY_SAT,
-        KeyCode::K382 => OsCode::KEY_SAT2,
-        KeyCode::K383 => OsCode::KEY_CD,
-        KeyCode::K384 => OsCode::KEY_TAPE,
-        KeyCode::K385 => OsCode::KEY_RADIO,
-        KeyCode::K386 => OsCode::KEY_TUNER,
-        KeyCode::K387 => OsCode::KEY_PLAYER,
-        KeyCode::K388 => OsCode::KEY_TEXT,
-        KeyCode::K389 => OsCode::KEY_DVD,
-        KeyCode::K390 => OsCode::KEY_AUX,
-        KeyCode::K391 => OsCode::KEY_MP3,
-        KeyCode::K392 => OsCode::KEY_AUDIO,
-        KeyCode::K393 => OsCode::KEY_VIDEO,
-        KeyCode::K394 => OsCode::KEY_DIRECTORY,
-        KeyCode::K395 => OsCode::KEY_LIST,
-        KeyCode::K396 => OsCode::KEY_MEMO,
-        KeyCode::K397 => OsCode::KEY_CALENDAR,
-        KeyCode::K398 => OsCode::KEY_RED,
-        KeyCode::K399 => OsCode::KEY_GREEN,
-        KeyCode::K400 => OsCode::KEY_YELLOW,
-        KeyCode::K401 => OsCode::KEY_BLUE,
-        KeyCode::K402 => OsCode::KEY_CHANNELUP,
-        KeyCode::K403 => OsCode::KEY_CHANNELDOWN,
-        KeyCode::K404 => OsCode::KEY_FIRST,
-        KeyCode::K405 => OsCode::KEY_LAST,
-        KeyCode::K406 => OsCode::KEY_AB,
-        KeyCode::K407 => OsCode::KEY_NEXT,
-        KeyCode::K408 => OsCode::KEY_RESTART,
-        KeyCode::K409 => OsCode::KEY_SLOW,
-        KeyCode::K410 => OsCode::KEY_SHUFFLE,
-        KeyCode::K411 => OsCode::KEY_BREAK,
-        KeyCode::K412 => OsCode::KEY_PREVIOUS,
-        KeyCode::K413 => OsCode::KEY_DIGITS,
-        KeyCode::K414 => OsCode::KEY_TEEN,
-        KeyCode::K415 => OsCode::KEY_TWEN,
-        KeyCode::K416 => OsCode::KEY_VIDEOPHONE,
-        KeyCode::K417 => OsCode::KEY_GAMES,
-        KeyCode::K418 => OsCode::KEY_ZOOMIN,
-        KeyCode::K419 => OsCode::KEY_ZOOMOUT,
-        KeyCode::K420 => OsCode::KEY_ZOOMRESET,
-        KeyCode::K421 => OsCode::KEY_WORDPROCESSOR,
-        KeyCode::K422 => OsCode::KEY_EDITOR,
-        KeyCode::K423 => OsCode::KEY_SPREADSHEET,
-        KeyCode::K424 => OsCode::KEY_GRAPHICSEDITOR,
-        KeyCode::K425 => OsCode::KEY_PRESENTATION,
-        KeyCode::K426 => OsCode::KEY_DATABASE,
-        KeyCode::K427 => OsCode::KEY_NEWS,
-        KeyCode::K428 => OsCode::KEY_VOICEMAIL,
-        KeyCode::K429 => OsCode::KEY_ADDRESSBOOK,
-        KeyCode::K430 => OsCode::KEY_MESSENGER,
-        KeyCode::K431 => OsCode::KEY_DISPLAYTOGGLE,
-        KeyCode::K432 => OsCode::KEY_SPELLCHECK,
-        KeyCode::K433 => OsCode::KEY_LOGOFF,
-        KeyCode::K434 => OsCode::KEY_DOLLAR,
-        KeyCode::K435 => OsCode::KEY_EURO,
-        KeyCode::K436 => OsCode::KEY_FRAMEBACK,
-        KeyCode::K437 => OsCode::KEY_FRAMEFORWARD,
-        KeyCode::K438 => OsCode::KEY_CONTEXT_MENU,
-        KeyCode::K439 => OsCode::KEY_MEDIA_REPEAT,
-        KeyCode::K440 => OsCode::KEY_10CHANNELSUP,
-        KeyCode::K441 => OsCode::KEY_10CHANNELSDOWN,
-        KeyCode::K442 => OsCode::KEY_IMAGES,
-        KeyCode::K443 => OsCode::KEY_443,
-        KeyCode::K444 => OsCode::KEY_444,
-        KeyCode::K445 => OsCode::KEY_445,
-        KeyCode::K446 => OsCode::KEY_446,
-        KeyCode::K447 => OsCode::KEY_447,
-        KeyCode::K448 => OsCode::KEY_DEL_EOL,
-        KeyCode::K449 => OsCode::KEY_DEL_EOS,
-        KeyCode::K450 => OsCode::KEY_INS_LINE,
-        KeyCode::K451 => OsCode::KEY_DEL_LINE,
-        KeyCode::K452 => OsCode::KEY_452,
-        KeyCode::K453 => OsCode::KEY_453,
-        KeyCode::K454 => OsCode::KEY_454,
-        KeyCode::K455 => OsCode::KEY_455,
-        KeyCode::K456 => OsCode::KEY_456,
-        KeyCode::K457 => OsCode::KEY_457,
-        KeyCode::K458 => OsCode::KEY_458,
-        KeyCode::K459 => OsCode::KEY_459,
-        KeyCode::K460 => OsCode::KEY_460,
-        KeyCode::K461 => OsCode::KEY_461,
-        KeyCode::K462 => OsCode::KEY_462,
-        KeyCode::K463 => OsCode::KEY_463,
-        KeyCode::K464 => OsCode::KEY_FN,
-        KeyCode::K465 => OsCode::KEY_FN_ESC,
-        KeyCode::K466 => OsCode::KEY_FN_F1,
-        KeyCode::K467 => OsCode::KEY_FN_F2,
-        KeyCode::K468 => OsCode::KEY_FN_F3,
-        KeyCode::K469 => OsCode::KEY_FN_F4,
-        KeyCode::K470 => OsCode::KEY_FN_F5,
-        KeyCode::K471 => OsCode::KEY_FN_F6,
-        KeyCode::K472 => OsCode::KEY_FN_F7,
-        KeyCode::K473 => OsCode::KEY_FN_F8,
-        KeyCode::K474 => OsCode::KEY_FN_F9,
-        KeyCode::K475 => OsCode::KEY_FN_F10,
-        KeyCode::K476 => OsCode::KEY_FN_F11,
-        KeyCode::K477 => OsCode::KEY_FN_F12,
-        KeyCode::K478 => OsCode::KEY_FN_1,
-        KeyCode::K479 => OsCode::KEY_FN_2,
-        KeyCode::K480 => OsCode::KEY_FN_D,
-        KeyCode::K481 => OsCode::KEY_FN_E,
-        KeyCode::K482 => OsCode::KEY_FN_F,
-        KeyCode::K483 => OsCode::KEY_FN_S,
-        KeyCode::K484 => OsCode::KEY_FN_B,
-        KeyCode::K485 => OsCode::KEY_485,
-        KeyCode::K486 => OsCode::KEY_486,
-        KeyCode::K487 => OsCode::KEY_487,
-        KeyCode::K488 => OsCode::KEY_488,
-        KeyCode::K489 => OsCode::KEY_489,
-        KeyCode::K490 => OsCode::KEY_490,
-        KeyCode::K491 => OsCode::KEY_491,
-        KeyCode::K492 => OsCode::KEY_492,
-        KeyCode::K493 => OsCode::KEY_493,
-        KeyCode::K494 => OsCode::KEY_494,
-        KeyCode::K495 => OsCode::KEY_495,
-        KeyCode::K496 => OsCode::KEY_496,
-        KeyCode::K497 => OsCode::KEY_BRL_DOT1,
-        KeyCode::K498 => OsCode::KEY_BRL_DOT2,
-        KeyCode::K499 => OsCode::KEY_BRL_DOT3,
-        KeyCode::K500 => OsCode::KEY_BRL_DOT4,
-        KeyCode::K501 => OsCode::KEY_BRL_DOT5,
-        KeyCode::K502 => OsCode::KEY_BRL_DOT6,
-        KeyCode::K503 => OsCode::KEY_BRL_DOT7,
-        KeyCode::K504 => OsCode::KEY_BRL_DOT8,
-        KeyCode::K505 => OsCode::KEY_BRL_DOT9,
-        KeyCode::K506 => OsCode::KEY_BRL_DOT10,
-        KeyCode::K507 => OsCode::KEY_507,
-        KeyCode::K508 => OsCode::KEY_508,
-        KeyCode::K509 => OsCode::KEY_509,
-        KeyCode::K510 => OsCode::KEY_510,
-        KeyCode::K511 => OsCode::KEY_511,
-        KeyCode::K512 => OsCode::KEY_NUMERIC_0,
-        KeyCode::K513 => OsCode::KEY_NUMERIC_1,
-        KeyCode::K514 => OsCode::KEY_NUMERIC_2,
-        KeyCode::K515 => OsCode::KEY_NUMERIC_3,
-        KeyCode::K516 => OsCode::KEY_NUMERIC_4,
-        KeyCode::K517 => OsCode::KEY_NUMERIC_5,
-        KeyCode::K518 => OsCode::KEY_NUMERIC_6,
-        KeyCode::K519 => OsCode::KEY_NUMERIC_7,
-        KeyCode::K520 => OsCode::KEY_NUMERIC_8,
-        KeyCode::K521 => OsCode::KEY_NUMERIC_9,
-        KeyCode::K522 => OsCode::KEY_NUMERIC_STAR,
-        KeyCode::K523 => OsCode::KEY_NUMERIC_POUND,
-        KeyCode::K524 => OsCode::KEY_NUMERIC_A,
-        KeyCode::K525 => OsCode::KEY_NUMERIC_B,
-        KeyCode::K526 => OsCode::KEY_NUMERIC_C,
-        KeyCode::K527 => OsCode::KEY_NUMERIC_D,
-        KeyCode::K528 => OsCode::KEY_CAMERA_FOCUS,
-        KeyCode::K529 => OsCode::KEY_WPS_BUTTON,
-        KeyCode::K530 => OsCode::KEY_TOUCHPAD_TOGGLE,
-        KeyCode::K531 => OsCode::KEY_TOUCHPAD_ON,
-        KeyCode::K532 => OsCode::KEY_TOUCHPAD_OFF,
-        KeyCode::K533 => OsCode::KEY_CAMERA_ZOOMIN,
-        KeyCode::K534 => OsCode::KEY_CAMERA_ZOOMOUT,
-        KeyCode::K535 => OsCode::KEY_CAMERA_UP,
-        KeyCode::K536 => OsCode::KEY_CAMERA_DOWN,
-        KeyCode::K537 => OsCode::KEY_CAMERA_LEFT,
-        KeyCode::K538 => OsCode::KEY_CAMERA_RIGHT,
-        KeyCode::K539 => OsCode::KEY_ATTENDANT_ON,
-        KeyCode::K540 => OsCode::KEY_ATTENDANT_OFF,
-        KeyCode::K541 => OsCode::KEY_ATTENDANT_TOGGLE,
-        KeyCode::K542 => OsCode::KEY_LIGHTS_TOGGLE,
-        KeyCode::K543 => OsCode::KEY_543,
-        KeyCode::K544 => OsCode::BTN_DPAD_UP,
-        KeyCode::K545 => OsCode::BTN_DPAD_DOWN,
-        KeyCode::K546 => OsCode::BTN_DPAD_LEFT,
-        KeyCode::K547 => OsCode::BTN_DPAD_RIGHT,
-        KeyCode::K548 => OsCode::KEY_548,
-        KeyCode::K549 => OsCode::KEY_549,
-        KeyCode::K550 => OsCode::KEY_550,
-        KeyCode::K551 => OsCode::KEY_551,
-        KeyCode::K552 => OsCode::KEY_552,
-        KeyCode::K553 => OsCode::KEY_553,
-        KeyCode::K554 => OsCode::KEY_554,
-        KeyCode::K555 => OsCode::KEY_555,
-        KeyCode::K556 => OsCode::KEY_556,
-        KeyCode::K557 => OsCode::KEY_557,
-        KeyCode::K558 => OsCode::KEY_558,
-        KeyCode::K559 => OsCode::KEY_559,
-        KeyCode::K560 => OsCode::KEY_ALS_TOGGLE,
-        KeyCode::K561 => OsCode::KEY_ROTATE_LOCK_TOGGLE,
-        KeyCode::K562 => OsCode::KEY_562,
-        KeyCode::K563 => OsCode::KEY_563,
-        KeyCode::K564 => OsCode::KEY_564,
-        KeyCode::K565 => OsCode::KEY_565,
-        KeyCode::K566 => OsCode::KEY_566,
-        KeyCode::K567 => OsCode::KEY_567,
-        KeyCode::K568 => OsCode::KEY_568,
-        KeyCode::K569 => OsCode::KEY_569,
-        KeyCode::K570 => OsCode::KEY_570,
-        KeyCode::K571 => OsCode::KEY_571,
-        KeyCode::K572 => OsCode::KEY_572,
-        KeyCode::K573 => OsCode::KEY_573,
-        KeyCode::K574 => OsCode::KEY_574,
-        KeyCode::K575 => OsCode::KEY_575,
-        KeyCode::K576 => OsCode::KEY_BUTTONCONFIG,
-        KeyCode::K577 => OsCode::KEY_TASKMANAGER,
-        KeyCode::K578 => OsCode::KEY_JOURNAL,
-        KeyCode::K579 => OsCode::KEY_CONTROLPANEL,
-        KeyCode::K580 => OsCode::KEY_APPSELECT,
-        KeyCode::K581 => OsCode::KEY_SCREENSAVER,
-        KeyCode::K582 => OsCode::KEY_VOICECOMMAND,
-        KeyCode::K583 => OsCode::KEY_ASSISTANT,
-        KeyCode::K584 => OsCode::KEY_KBD_LAYOUT_NEXT,
-        KeyCode::K585 => OsCode::KEY_585,
-        KeyCode::K586 => OsCode::KEY_586,
-        KeyCode::K587 => OsCode::KEY_587,
-        KeyCode::K588 => OsCode::KEY_588,
-        KeyCode::K589 => OsCode::KEY_589,
-        KeyCode::K590 => OsCode::KEY_590,
-        KeyCode::K591 => OsCode::KEY_591,
-        KeyCode::K592 => OsCode::KEY_BRIGHTNESS_MIN,
-        KeyCode::K593 => OsCode::KEY_BRIGHTNESS_MAX,
-        KeyCode::K594 => OsCode::KEY_594,
-        KeyCode::K595 => OsCode::KEY_595,
-        KeyCode::K596 => OsCode::KEY_596,
-        KeyCode::K597 => OsCode::KEY_597,
-        KeyCode::K598 => OsCode::KEY_598,
-        KeyCode::K599 => OsCode::KEY_599,
-        KeyCode::K600 => OsCode::KEY_600,
-        KeyCode::K601 => OsCode::KEY_601,
-        KeyCode::K602 => OsCode::KEY_602,
-        KeyCode::K603 => OsCode::KEY_603,
-        KeyCode::K604 => OsCode::KEY_604,
-        KeyCode::K605 => OsCode::KEY_605,
-        KeyCode::K606 => OsCode::KEY_606,
-        KeyCode::K607 => OsCode::KEY_607,
-        KeyCode::K608 => OsCode::KEY_KBDINPUTASSIST_PREV,
-        KeyCode::K609 => OsCode::KEY_KBDINPUTASSIST_NEXT,
-        KeyCode::K610 => OsCode::KEY_KBDINPUTASSIST_PREVGROUP,
-        KeyCode::K611 => OsCode::KEY_KBDINPUTASSIST_NEXTGROUP,
-        KeyCode::K612 => OsCode::KEY_KBDINPUTASSIST_ACCEPT,
-        KeyCode::K613 => OsCode::KEY_KBDINPUTASSIST_CANCEL,
-        KeyCode::K614 => OsCode::KEY_RIGHT_UP,
-        KeyCode::K615 => OsCode::KEY_RIGHT_DOWN,
-        KeyCode::K616 => OsCode::KEY_LEFT_UP,
-        KeyCode::K617 => OsCode::KEY_LEFT_DOWN,
-        KeyCode::K618 => OsCode::KEY_ROOT_MENU,
-        KeyCode::K619 => OsCode::KEY_MEDIA_TOP_MENU,
-        KeyCode::K620 => OsCode::KEY_NUMERIC_11,
-        KeyCode::K621 => OsCode::KEY_NUMERIC_12,
-        KeyCode::K622 => OsCode::KEY_AUDIO_DESC,
-        KeyCode::K623 => OsCode::KEY_3D_MODE,
-        KeyCode::K624 => OsCode::KEY_NEXT_FAVORITE,
-        KeyCode::K625 => OsCode::KEY_STOP_RECORD,
-        KeyCode::K626 => OsCode::KEY_PAUSE_RECORD,
-        KeyCode::K627 => OsCode::KEY_VOD,
-        KeyCode::K628 => OsCode::KEY_UNMUTE,
-        KeyCode::K629 => OsCode::KEY_FASTREVERSE,
-        KeyCode::K630 => OsCode::KEY_SLOWREVERSE,
-        KeyCode::K631 => OsCode::KEY_DATA,
-        KeyCode::K632 => OsCode::KEY_ONSCREEN_KEYBOARD,
-        KeyCode::K633 => OsCode::KEY_633,
-        KeyCode::K634 => OsCode::KEY_634,
-        KeyCode::K635 => OsCode::KEY_635,
-        KeyCode::K636 => OsCode::KEY_636,
-        KeyCode::K637 => OsCode::KEY_637,
-        KeyCode::K638 => OsCode::KEY_638,
-        KeyCode::K639 => OsCode::KEY_639,
-        KeyCode::K640 => OsCode::KEY_640,
-        KeyCode::K641 => OsCode::KEY_641,
-        KeyCode::K642 => OsCode::KEY_642,
-        KeyCode::K643 => OsCode::KEY_643,
-        KeyCode::K644 => OsCode::KEY_644,
-        KeyCode::K645 => OsCode::KEY_645,
-        KeyCode::K646 => OsCode::KEY_646,
-        KeyCode::K647 => OsCode::KEY_647,
-        KeyCode::K648 => OsCode::KEY_648,
-        KeyCode::K649 => OsCode::KEY_649,
-        KeyCode::K650 => OsCode::KEY_650,
-        KeyCode::K651 => OsCode::KEY_651,
-        KeyCode::K652 => OsCode::KEY_652,
-        KeyCode::K653 => OsCode::KEY_653,
-        KeyCode::K654 => OsCode::KEY_654,
-        KeyCode::K655 => OsCode::KEY_655,
-        KeyCode::K656 => OsCode::KEY_656,
-        KeyCode::K657 => OsCode::KEY_657,
-        KeyCode::K658 => OsCode::KEY_658,
-        KeyCode::K659 => OsCode::KEY_659,
-        KeyCode::K660 => OsCode::KEY_660,
-        KeyCode::K661 => OsCode::KEY_661,
-        KeyCode::K662 => OsCode::KEY_662,
-        KeyCode::K663 => OsCode::KEY_663,
-        KeyCode::K664 => OsCode::KEY_664,
-        KeyCode::K665 => OsCode::KEY_665,
-        KeyCode::K666 => OsCode::KEY_666,
-        KeyCode::K667 => OsCode::KEY_667,
-        KeyCode::K668 => OsCode::KEY_668,
-        KeyCode::K669 => OsCode::KEY_669,
-        KeyCode::K670 => OsCode::KEY_670,
-        KeyCode::K671 => OsCode::KEY_671,
-        KeyCode::K672 => OsCode::KEY_672,
-        KeyCode::K673 => OsCode::KEY_673,
-        KeyCode::K674 => OsCode::KEY_674,
-        KeyCode::K675 => OsCode::KEY_675,
-        KeyCode::K676 => OsCode::KEY_676,
-        KeyCode::K677 => OsCode::KEY_677,
-        KeyCode::K678 => OsCode::KEY_678,
-        KeyCode::K679 => OsCode::KEY_679,
-        KeyCode::K680 => OsCode::KEY_680,
-        KeyCode::K681 => OsCode::KEY_681,
-        KeyCode::K682 => OsCode::KEY_682,
-        KeyCode::K683 => OsCode::KEY_683,
-        KeyCode::K684 => OsCode::KEY_684,
-        KeyCode::K685 => OsCode::KEY_685,
-        KeyCode::K686 => OsCode::KEY_686,
-        KeyCode::K687 => OsCode::KEY_687,
-        KeyCode::K688 => OsCode::KEY_688,
-        KeyCode::K689 => OsCode::KEY_689,
-        KeyCode::K690 => OsCode::KEY_690,
-        KeyCode::K691 => OsCode::KEY_691,
-        KeyCode::K692 => OsCode::KEY_692,
-        KeyCode::K693 => OsCode::KEY_693,
-        KeyCode::K694 => OsCode::KEY_694,
-        KeyCode::K695 => OsCode::KEY_695,
-        KeyCode::K696 => OsCode::KEY_696,
-        KeyCode::K697 => OsCode::KEY_697,
-        KeyCode::K698 => OsCode::KEY_698,
-        KeyCode::K699 => OsCode::KEY_699,
-        KeyCode::K700 => OsCode::KEY_700,
-        KeyCode::K701 => OsCode::KEY_701,
-        KeyCode::K702 => OsCode::KEY_702,
-        KeyCode::K703 => OsCode::KEY_703,
-        KeyCode::K704 => OsCode::BTN_TRIGGER_HAPPY1,
-        KeyCode::K705 => OsCode::BTN_TRIGGER_HAPPY2,
-        KeyCode::K706 => OsCode::BTN_TRIGGER_HAPPY3,
-        KeyCode::K707 => OsCode::BTN_TRIGGER_HAPPY4,
-        KeyCode::K708 => OsCode::BTN_TRIGGER_HAPPY5,
-        KeyCode::K709 => OsCode::BTN_TRIGGER_HAPPY6,
-        KeyCode::K710 => OsCode::BTN_TRIGGER_HAPPY7,
-        KeyCode::K711 => OsCode::BTN_TRIGGER_HAPPY8,
-        KeyCode::K712 => OsCode::BTN_TRIGGER_HAPPY9,
-        KeyCode::K713 => OsCode::BTN_TRIGGER_HAPPY10,
-        KeyCode::K714 => OsCode::BTN_TRIGGER_HAPPY11,
-        KeyCode::K715 => OsCode::BTN_TRIGGER_HAPPY12,
-        KeyCode::K716 => OsCode::BTN_TRIGGER_HAPPY13,
-        KeyCode::K717 => OsCode::BTN_TRIGGER_HAPPY14,
-        KeyCode::K718 => OsCode::BTN_TRIGGER_HAPPY15,
-        KeyCode::K719 => OsCode::BTN_TRIGGER_HAPPY16,
-        KeyCode::K720 => OsCode::BTN_TRIGGER_HAPPY17,
-        KeyCode::K721 => OsCode::BTN_TRIGGER_HAPPY18,
-        KeyCode::K722 => OsCode::BTN_TRIGGER_HAPPY19,
-        KeyCode::K723 => OsCode::BTN_TRIGGER_HAPPY20,
-        KeyCode::K724 => OsCode::BTN_TRIGGER_HAPPY21,
-        KeyCode::K725 => OsCode::BTN_TRIGGER_HAPPY22,
-        KeyCode::K726 => OsCode::BTN_TRIGGER_HAPPY23,
-        KeyCode::K727 => OsCode::BTN_TRIGGER_HAPPY24,
-        KeyCode::K728 => OsCode::BTN_TRIGGER_HAPPY25,
-        KeyCode::K729 => OsCode::BTN_TRIGGER_HAPPY26,
-        KeyCode::K730 => OsCode::BTN_TRIGGER_HAPPY27,
-        KeyCode::K731 => OsCode::BTN_TRIGGER_HAPPY28,
-        KeyCode::K732 => OsCode::BTN_TRIGGER_HAPPY29,
-        KeyCode::K733 => OsCode::BTN_TRIGGER_HAPPY30,
-        KeyCode::K734 => OsCode::BTN_TRIGGER_HAPPY31,
-        KeyCode::K735 => OsCode::BTN_TRIGGER_HAPPY32,
-        KeyCode::K736 => OsCode::BTN_TRIGGER_HAPPY33,
-        KeyCode::K737 => OsCode::BTN_TRIGGER_HAPPY34,
-        KeyCode::K738 => OsCode::BTN_TRIGGER_HAPPY35,
-        KeyCode::K739 => OsCode::BTN_TRIGGER_HAPPY36,
-        KeyCode::K740 => OsCode::BTN_TRIGGER_HAPPY37,
-        KeyCode::K741 => OsCode::BTN_TRIGGER_HAPPY38,
-        KeyCode::K742 => OsCode::BTN_TRIGGER_HAPPY39,
-        KeyCode::K743 => OsCode::BTN_TRIGGER_HAPPY40,
-        KeyCode::K744 => OsCode::BTN_MAX,
-        _ => OsCode::KEY_UNKNOWN,
+    for osc in oscs.iter().copied() {
+        let roundtrip = OsCode::from(KeyCode::from(osc));
+        assert_eq!(osc, roundtrip);
     }
 }
diff --git a/parser/src/keys/mod.rs b/parser/src/keys/mod.rs
index 14cbb9b4a..049a37a52 100644
--- a/parser/src/keys/mod.rs
+++ b/parser/src/keys/mod.rs
@@ -1,22 +1,104 @@
 //! Platform specific code for OS key code mappings.
 
-use kanata_keyberon::key_code::KeyCode;
+use kanata_keyberon::key_code::*;
 use once_cell::sync::Lazy;
 use parking_lot::Mutex;
 use rustc_hash::FxHashMap as HashMap;
 
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
 mod linux;
-#[cfg(target_os = "linux")]
-pub use linux::*;
-
-#[cfg(target_os = "windows")]
+#[cfg(any(target_os = "macos", target_os = "unknown"))]
+mod macos;
+#[cfg(any(target_os = "windows", target_os = "unknown"))]
 mod windows;
+#[cfg(any(target_os = "macos", target_os = "unknown"))]
+pub use macos::PageCode;
+
 #[cfg(target_os = "windows")]
-pub use windows::*;
+pub use windows::VK_KPENTER_FAKE;
 
 mod mappings;
-pub use mappings::*;
+
+#[cfg(target_os = "unknown")]
+#[derive(Clone, Copy)]
+pub enum Platform {
+    Win,
+    Linux,
+    Macos,
+}
+
+#[cfg(target_os = "unknown")]
+pub static OSCODE_MAPPING_VARIANT: Mutex<Platform> = Mutex::new(Platform::Linux);
+
+impl OsCode {
+    pub fn as_u16(self) -> u16 {
+        #[cfg(target_os = "unknown")]
+        return match *OSCODE_MAPPING_VARIANT.lock() {
+            Platform::Win => self.as_u16_windows(),
+            Platform::Linux => self.as_u16_linux(),
+            Platform::Macos => self.as_u16_macos(),
+        };
+
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        return self.as_u16_linux();
+
+        #[cfg(target_os = "windows")]
+        return self.as_u16_windows();
+
+        #[cfg(target_os = "macos")]
+        return self.as_u16_macos();
+    }
+
+    pub fn from_u16(code: u16) -> Option<Self> {
+        #[cfg(target_os = "unknown")]
+        return match *OSCODE_MAPPING_VARIANT.lock() {
+            Platform::Win => OsCode::from_u16_windows(code),
+            Platform::Linux => OsCode::from_u16_linux(code),
+            Platform::Macos => OsCode::from_u16_macos(code),
+        };
+
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        return OsCode::from_u16_linux(code);
+
+        #[cfg(target_os = "windows")]
+        return OsCode::from_u16_windows(code);
+
+        #[cfg(target_os = "macos")]
+        return OsCode::from_u16_macos(code);
+    }
+
+    pub fn is_modifier(self) -> bool {
+        matches!(
+            self,
+            OsCode::KEY_LEFTSHIFT
+                | OsCode::KEY_RIGHTSHIFT
+                | OsCode::KEY_LEFTMETA
+                | OsCode::KEY_RIGHTMETA
+                | OsCode::KEY_LEFTCTRL
+                | OsCode::KEY_RIGHTCTRL
+                | OsCode::KEY_LEFTALT
+                | OsCode::KEY_RIGHTALT
+        )
+    }
+
+    #[cfg(feature = "zippychord")]
+    pub fn is_zippy_ignored(self) -> bool {
+        matches!(
+            self,
+            OsCode::KEY_LEFTSHIFT
+                | OsCode::KEY_RIGHTSHIFT
+                | OsCode::KEY_LEFTMETA
+                | OsCode::KEY_RIGHTMETA
+                | OsCode::KEY_LEFTCTRL
+                | OsCode::KEY_RIGHTCTRL
+                | OsCode::KEY_LEFTALT
+                | OsCode::KEY_RIGHTALT
+                | OsCode::KEY_ESC
+                | OsCode::KEY_BACKSPACE
+                | OsCode::KEY_DELETE
+        )
+    }
+}
 
 static CUSTOM_STRS_TO_OSCODES: Lazy<Mutex<HashMap<String, OsCode>>> = Lazy::new(|| {
     let mut mappings = HashMap::default();
@@ -41,17 +123,21 @@ pub fn replace_custom_str_oscode_mapping(mapping: &HashMap<String, OsCode>) {
     local_mapping.shrink_to_fit();
 }
 
-/// Clears the stateful custom `String` to `OsCode` mapping in this module.
+/// Clears the stateful custom `String` to `OsCode` mapping in this module, restoring only the
+/// default mappings. Defaults are restored under the same lock as the clear so that concurrent
+/// `str_to_oscode` callers never observe a window in which the default mappings are absent.
 pub fn clear_custom_str_oscode_mapping() {
     let mut local_mapping = CUSTOM_STRS_TO_OSCODES.lock();
     local_mapping.clear();
+    add_default_str_osc_mappings(&mut local_mapping);
+    local_mapping.shrink_to_fit();
 }
 
 /// Used for backwards compatibility. If there is hardcoded key name in `str_to_oscode` that would
 /// be useful to remap via `defcustomkeys`, then it should be moved into here. This is so that the
 /// key name can be remapped while also working for older configurations that already use it.
 fn add_default_str_osc_mappings(mapping: &mut HashMap<String, OsCode>) {
-    let default_mappings = [
+    const DEFAULT_MAPPINGS: &[(&str, OsCode)] = &[
         ("+", OsCode::KEY_KPPLUS),
         ("[", OsCode::KEY_LEFTBRACE),
         ("]", OsCode::KEY_RIGHTBRACE),
@@ -66,8 +152,14 @@ fn add_default_str_osc_mappings(mapping: &mut HashMap<String, OsCode>) {
         (",", OsCode::KEY_COMMA),
         (".", OsCode::KEY_DOT),
         ("\\", OsCode::KEY_BACKSLASH),
+        // Mapped as backslash because in some locales/fonts, yen=backslash
+        ("yen", OsCode::KEY_BACKSLASH),
+        // Unicode yen is probably the yen key, so map this to a separate oscode by default.
+        ("¥", OsCode::KEY_YEN),
+        ("right", OsCode::KEY_RIGHT),
+        ("grave", OsCode::KEY_GRAVE),
     ];
-    for dm in default_mappings {
+    for dm in DEFAULT_MAPPINGS {
         mapping.entry(dm.0.into()).or_insert(dm.1);
     }
 }
@@ -81,183 +173,227 @@ fn add_default_str_osc_mappings(mapping: &mut HashMap<String, OsCode>) {
 /// can stay clean.
 #[rustfmt::skip]
 pub fn str_to_oscode(s: &str) -> Option<OsCode> {
+    if let Some(osc) = CUSTOM_STRS_TO_OSCODES.lock().get(s) {
+        return Some(*osc);
+    }
     Some(match s {
-        "grv" => OsCode::KEY_GRAVE,
-        "1" => OsCode::KEY_1,
-        "2" => OsCode::KEY_2,
-        "3" => OsCode::KEY_3,
-        "4" => OsCode::KEY_4,
-        "5" => OsCode::KEY_5,
-        "6" => OsCode::KEY_6,
-        "7" => OsCode::KEY_7,
-        "8" => OsCode::KEY_8,
-        "9" => OsCode::KEY_9,
-        "0" => OsCode::KEY_0,
-        "min" => OsCode::KEY_MINUS,
-        "eql" => OsCode::KEY_EQUAL,
-        "bspc" | "bks" => OsCode::KEY_BACKSPACE,
-        "tab" => OsCode::KEY_TAB,
-        "q" => OsCode::KEY_Q,
-        "w" => OsCode::KEY_W,
-        "e" => OsCode::KEY_E,
-        "r" => OsCode::KEY_R,
-        "t" => OsCode::KEY_T,
-        "y" => OsCode::KEY_Y,
-        "u" => OsCode::KEY_U,
-        "i" => OsCode::KEY_I,
-        "o" => OsCode::KEY_O,
-        "p" => OsCode::KEY_P,
-        "lbrc" => OsCode::KEY_LEFTBRACE,
-        "rbrc" => OsCode::KEY_RIGHTBRACE,
-        "bksl" | "yen" | "¥" => OsCode::KEY_BACKSLASH,
-        "caps" => OsCode::KEY_CAPSLOCK,
-        "a" => OsCode::KEY_A,
-        "s" => OsCode::KEY_S,
-        "d" => OsCode::KEY_D,
-        "f" => OsCode::KEY_F,
-        "g" => OsCode::KEY_G,
-        "h" => OsCode::KEY_H,
-        "j" => OsCode::KEY_J,
-        "k" => OsCode::KEY_K,
-        "l" => OsCode::KEY_L,
-        "scln" => OsCode::KEY_SEMICOLON,
-        "apo" | "apos" => OsCode::KEY_APOSTROPHE,
-        "ret" | "return" | "ent" | "enter" => OsCode::KEY_ENTER,
-        "lshift" | "lshft" | "lsft" | "shft" | "sft" => OsCode::KEY_LEFTSHIFT,
-        "z" => OsCode::KEY_Z,
-        "x" => OsCode::KEY_X,
-        "c" => OsCode::KEY_C,
-        "v" => OsCode::KEY_V,
-        "b" => OsCode::KEY_B,
-        "n" => OsCode::KEY_N,
-        "m" => OsCode::KEY_M,
-        "comm" => OsCode::KEY_COMMA,
+        "Backquote" | "grv" | "ˋ" | "˜" => OsCode::KEY_GRAVE,
+        "Digit1" | "1" => OsCode::KEY_1,
+        "Digit2" | "2" => OsCode::KEY_2,
+        "Digit3" | "3" => OsCode::KEY_3,
+        "Digit4" | "4" => OsCode::KEY_4,
+        "Digit5" | "5" => OsCode::KEY_5,
+        "Digit6" | "6" => OsCode::KEY_6,
+        "Digit7" | "7" => OsCode::KEY_7,
+        "Digit8" | "8" => OsCode::KEY_8,
+        "Digit9" | "9" => OsCode::KEY_9,
+        "Digit0" | "0" => OsCode::KEY_0,
+        "Minus" | "min" | "‐" => OsCode::KEY_MINUS,
+        "Equal" | "eql" | "₌" => OsCode::KEY_EQUAL,
+        "Backspace" | "bspc" | "bks" | "␈" | "⌫"  => OsCode::KEY_BACKSPACE,
+        "Tab" | "tab" | "⭾" | "↹" => OsCode::KEY_TAB,
+        "KeyQ" | "q" => OsCode::KEY_Q,
+        "KeyW" | "w" => OsCode::KEY_W,
+        "KeyE" | "e" => OsCode::KEY_E,
+        "KeyR" | "r" => OsCode::KEY_R,
+        "KeyT" | "t" => OsCode::KEY_T,
+        "KeyY" | "y" => OsCode::KEY_Y,
+        "KeyU" | "u" => OsCode::KEY_U,
+        "KeyI" | "i" => OsCode::KEY_I,
+        "KeyO" | "o" => OsCode::KEY_O,
+        "KeyP" | "p" => OsCode::KEY_P,
+        "BracketLeft" | "lbrc" | "【" | "「" | "〔" | "⎡" => OsCode::KEY_LEFTBRACE,
+        "BracketRight" | "rbrc" | "】" | "」" | "〕" | "⎣" => OsCode::KEY_RIGHTBRACE,
+        "CapsLock" | "caps" | "⇪" => OsCode::KEY_CAPSLOCK,
+        "KeyA" | "a" => OsCode::KEY_A,
+        "KeyS" | "s" => OsCode::KEY_S,
+        "KeyD" | "d" => OsCode::KEY_D,
+        "KeyF" | "f" => OsCode::KEY_F,
+        "KeyG" | "g" => OsCode::KEY_G,
+        "KeyH" | "h" => OsCode::KEY_H,
+        "KeyJ" | "j" => OsCode::KEY_J,
+        "KeyK" | "k" => OsCode::KEY_K,
+        "KeyL" | "l" => OsCode::KEY_L,
+        "Semicolon" | "scln" | "︔" => OsCode::KEY_SEMICOLON,
+        "Quote" | "apo" | "apos" => OsCode::KEY_APOSTROPHE,
+        "Enter" | "ret" | "return" | "ent" | "enter" | "⏎" | "↩" | "↵" | "↲" | "⤶" | "⎆" | "⌤" | "␤" => OsCode::KEY_ENTER,
+        "ShiftLeft" | "lshift" | "lshft" | "lsft" | "shft" | "sft" | "‹⇧" => OsCode::KEY_LEFTSHIFT,
+        "KeyZ" | "z" => OsCode::KEY_Z,
+        "KeyX" | "x" => OsCode::KEY_X,
+        "KeyC" | "c" => OsCode::KEY_C,
+        "KeyV" | "v" => OsCode::KEY_V,
+        "KeyB" | "b" => OsCode::KEY_B,
+        "KeyN" | "n" => OsCode::KEY_N,
+        "KeyM" | "m" => OsCode::KEY_M,
+        "Comma" | "comm" | "⸴" => OsCode::KEY_COMMA,
+        "Period" | "．" => OsCode::KEY_DOT,
+        "Slash" | "⁄" => OsCode::KEY_SLASH,
+        "Backslash" | "bksl" | "⧵" | "＼" =>  OsCode::KEY_BACKSLASH,
         "kp=" | "clr" => OsCode::KEY_CLEAR,
         // The kp<etc> keys are also known as the numpad keys. E.g. below is numpad enter.
-        "kp0" => OsCode::KEY_KP0,
-        "kp1" => OsCode::KEY_KP1,
-        "kp2" => OsCode::KEY_KP2,
-        "kp3" => OsCode::KEY_KP3,
-        "kp4" => OsCode::KEY_KP4,
-        "kp5" => OsCode::KEY_KP5,
-        "kp6" => OsCode::KEY_KP6,
-        "kp7" => OsCode::KEY_KP7,
-        "kp8" => OsCode::KEY_KP8,
-        "kp9" => OsCode::KEY_KP9,
-        "kprt" => OsCode::KEY_KPENTER,
-        "kp/" => OsCode::KEY_KPSLASH,
-        "kp+" => OsCode::KEY_KPPLUS,
-        "kp*" => OsCode::KEY_KPASTERISK,
-        "kp-" => OsCode::KEY_KPMINUS,
-        "kp." => OsCode::KEY_KPDOT,
+        "Numpad0" | "kp0" | "🔢₀" => OsCode::KEY_KP0,
+        "Numpad1" | "kp1" | "🔢₁" => OsCode::KEY_KP1,
+        "Numpad2" | "kp2" | "🔢₂" => OsCode::KEY_KP2,
+        "Numpad3" | "kp3" | "🔢₃" => OsCode::KEY_KP3,
+        "Numpad4" | "kp4" | "🔢₄" => OsCode::KEY_KP4,
+        "Numpad5" | "kp5" | "🔢₅" => OsCode::KEY_KP5,
+        "Numpad6" | "kp6" | "🔢₆" => OsCode::KEY_KP6,
+        "Numpad7" | "kp7" | "🔢₇" => OsCode::KEY_KP7,
+        "Numpad8" | "kp8" | "🔢₈" => OsCode::KEY_KP8,
+        "Numpad9" | "kp9" | "🔢₉" => OsCode::KEY_KP9,
+        "NumpadEnter" | "kprt" | "🔢⏎" | "🔢↩" | "🔢↵" | "🔢↲" | "🔢⤶" | "🔢⎆" | "🔢⌤" | "🔢␤" => OsCode::KEY_KPENTER,
+        "NumpadDivide" | "kp/" | "🔢⁄" => OsCode::KEY_KPSLASH,
+        "NumpadAdd" | "kp+" | "🔢₊" => OsCode::KEY_KPPLUS,
+        "NumpadMultiply" | "kp*" | "🔢∗" => OsCode::KEY_KPASTERISK,
+        "NumpadEqual" | "🔢₌" => OsCode::KEY_KPEQUAL,
+        "NumpadSubtract" | "kp-" | "🔢₋" => OsCode::KEY_KPMINUS,
+        "NumpadDecimal" | "kp." | "🔢．" => OsCode::KEY_KPDOT,
+        "NumpadComma" | "kp," | "🔢⸴" =>OsCode::KEY_KPCOMMA,
+        "NumpadLeftParen" | "leftparen" | "lpar" | "kp(" | "🔢₍" => OsCode::KEY_KPLEFTPAREN,
+        "NumpadRightParen" | "rightparen" | "rpar" | "kp)" | "🔢₎" => OsCode::KEY_KPRIGHTPAREN,
         "ssrq" | "sys" => OsCode::KEY_SYSRQ,
         // Typically the Non-US backslash, near the left shift key
-        "102d" | "lsgt" | "nubs" | "nonusbslash" => OsCode::KEY_102ND,
-        "scrlck" | "slck" => OsCode::KEY_SCROLLLOCK,
-        "pause" | "break" | "brk" => OsCode::KEY_PAUSE,
-        "wkup" => OsCode::KEY_WAKEUP,
-        "esc" => OsCode::KEY_ESC,
-        "rshift" | "rshft" | "rsft" => OsCode::KEY_RIGHTSHIFT,
-        "lctrl" | "lctl" | "ctl" => OsCode::KEY_LEFTCTRL,
-        "lalt" | "alt" => OsCode::KEY_LEFTALT,
-        "spc" => OsCode::KEY_SPACE,
-        "ralt" => OsCode::KEY_RIGHTALT,
-        "comp" | "cmps" | "cmp" | "menu" | "apps" => OsCode::KEY_COMPOSE,
-        // Also known as Windows, GUI, Comand, Super
-        "lmeta" | "lmet" | "met" => OsCode::KEY_LEFTMETA,
-        "rmeta" | "rmet" => OsCode::KEY_RIGHTMETA,
-        "rctrl" | "rctl" => OsCode::KEY_RIGHTCTRL,
-        "del" => OsCode::KEY_DELETE,
-        "ins" => OsCode::KEY_INSERT,
-        "bck" => OsCode::KEY_BACK,
-        "fwd" => OsCode::KEY_FORWARD,
-        "pgup" => OsCode::KEY_PAGEUP,
-        "pgdn" => OsCode::KEY_PAGEDOWN,
-        "up" => OsCode::KEY_UP,
-        "down" => OsCode::KEY_DOWN,
-        "lft" | "left" => OsCode::KEY_LEFT,
-        "rght" => OsCode::KEY_RIGHT,
-        "home" => OsCode::KEY_HOME,
-        "end" => OsCode::KEY_END,
-        "nlck" | "nlk" => OsCode::KEY_NUMLOCK,
-        "mute" => OsCode::KEY_MUTE,
-        "volu" => OsCode::KEY_VOLUMEUP,
-        "voldwn" | "vold" => OsCode::KEY_VOLUMEDOWN,
-        "brup" | "bru" => OsCode::KEY_BRIGHTNESSUP,
-        "brdown" | "brdwn" | "brdn" => OsCode::KEY_BRIGHTNESSDOWN,
-        "blup" => OsCode::KEY_KBDILLUMUP,
-        "bldn" => OsCode::KEY_KBDILLUMDOWN,
-        "next" => OsCode::KEY_NEXTSONG,
-        "pp" => OsCode::KEY_PLAYPAUSE,
-        "prev" => OsCode::KEY_PREVIOUSSONG,
-        "f1" => OsCode::KEY_F1,
-        "f2" => OsCode::KEY_F2,
-        "f3" => OsCode::KEY_F3,
-        "f4" => OsCode::KEY_F4,
-        "f5" => OsCode::KEY_F5,
-        "f6" => OsCode::KEY_F6,
-        "f7" => OsCode::KEY_F7,
-        "f8" => OsCode::KEY_F8,
-        "f9" => OsCode::KEY_F9,
-        "f10" => OsCode::KEY_F10,
-        "f11" => OsCode::KEY_F11,
-        "f12" => OsCode::KEY_F12,
-        "f13" => OsCode::KEY_F13,
-        "f14" => OsCode::KEY_F14,
-        "f15" => OsCode::KEY_F15,
-        "f16" => OsCode::KEY_F16,
-        "f17" => OsCode::KEY_F17,
-        "f18" => OsCode::KEY_F18,
-        "f19" => OsCode::KEY_F19,
-        "f20" => OsCode::KEY_F20,
-        "f21" => OsCode::KEY_F21,
-        "f22" => OsCode::KEY_F22,
-        "f23" => OsCode::KEY_F23,
-        "f24" => OsCode::KEY_F24,
+        "IntlBackslash" | "102d" | "lsgt" | "nubs" | "nonusbslash" | "﹨" | "<" => OsCode::KEY_102ND,
+        // ISO "#" key to the left of Enter (USB HID page 7 usage 0x32, "Non-US # and ~").
+        // Distinct HID usage on macOS; folded onto Backslash by Linux evdev, so the name
+        // is gated to platforms where the physical key can actually produce it. See #1915.
+        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+        "NonUSPound" | "non_us_pound" | "nuhs" => OsCode::KEY_NUMERIC_POUND,
+        "ScrollLock" | "scrlck" | "slck" | "⇳🔒" => OsCode::KEY_SCROLLLOCK,
+        "Pause" | "pause" | "break" | "brk" => OsCode::KEY_PAUSE,
+        "WakeUp" | "wkup" => OsCode::KEY_WAKEUP,
+        "Escape" | "esc" | "⎋" => OsCode::KEY_ESC,
+        "ShiftRight" | "RightShift" | "rshift" | "rshft" | "rsft" | "⇧›" => OsCode::KEY_RIGHTSHIFT,
+        "ControlLeft" | "lctrl" | "lctl" | "ctl" | "‹⎈" | "‹⌃" => OsCode::KEY_LEFTCTRL,
+        "AltLeft" | "lalt" | "alt" | "‹⎇" | "‹⌥" => OsCode::KEY_LEFTALT,
+        "Space" | "spc" | "␠" | "␣" => OsCode::KEY_SPACE,
+        "AltRight" | "ralt" | "altgr" | "⎇›" | "⌥›" | "⇮" => OsCode::KEY_RIGHTALT,
+        "ContextMenu" | "comp" | "cmps" | "cmp" | "menu" | "apps" | "▤" | "☰" | "𝌆" => OsCode::KEY_COMPOSE,
+        "🎛" => OsCode::KEY_DASHBOARD,
+        // Also known as Windows, GUI, Command, Super
+        "MetaLeft" | "lmeta" | "lmet" | "met" | "‹◆" | "‹⌘" | "‹❖" | "‹⊞" => OsCode::KEY_LEFTMETA,
+        "MetaRight" | "rmeta" | "rmet" | "◆›" | "⌘›" | "❖›" | "⊞›" => OsCode::KEY_RIGHTMETA,
+        "ControlRight" | "rctrl" | "rctl" | "⎈›" | "⌃›" => OsCode::KEY_RIGHTCTRL,
+        "Delete" | "del" | "␡" | "⌦" => OsCode::KEY_DELETE,
+        "Insert" | "ins" | "⎀" => OsCode::KEY_INSERT,
+        "BrowserBack" | "bck" => OsCode::KEY_BACK,
+        "BrowserForward" | "fwd" => OsCode::KEY_FORWARD,
+        "PageUp" | "pgup" | "⇞" | "⎗" => OsCode::KEY_PAGEUP,
+        "PageDown" | "pgdn" | "⇟" | "⎘" => OsCode::KEY_PAGEDOWN,
+        "ArrowUp" | "up" | "▲" | "↑" => OsCode::KEY_UP,
+        "ArrowDown" | "down" | "▼" | "↓" => OsCode::KEY_DOWN,
+        "ArrowLeft" | "lft" | "left" | "◀" | "←" => OsCode::KEY_LEFT,
+        "ArrowRight" | "rght" | "▶" | "→" => OsCode::KEY_RIGHT,
+        "Home" | "home" | "⇤" | "⤒" | "↖" | "⇱" => OsCode::KEY_HOME,
+        "End" | "end" | "⇥" | "⤓" | "↘" | "⇲" => OsCode::KEY_END,
+        "NumLock" | "nlck" | "nlk" | "⇭"=> OsCode::KEY_NUMLOCK,
+        "VolumeMute" | "mute"  | "🔇" | "🔈⓪" | "🔈⓿" | "🔈₀" => OsCode::KEY_MUTE,
+        "VolumeUp" | "volu" | "🔊" | "🔈+" | "🔈➕" | "🔈₊" | "🔈⊕" => OsCode::KEY_VOLUMEUP,
+        "VolumeDown" | "voldwn" | "vold" | "🔉" | "🔈−" | "🔈➖" | "🔈₋" | "🔈⊖" => OsCode::KEY_VOLUMEDOWN,
+        "EjectCD" | "eject" => OsCode::KEY_EJECTCD,
+        "brup" | "bru" | "🔆" => OsCode::KEY_BRIGHTNESSUP,
+        "brdown" | "brdwn" | "brdn" | "🔅" => OsCode::KEY_BRIGHTNESSDOWN,
+        "blup" | "⌨💡+" | "⌨💡➕" | "⌨💡₊" | "⌨💡⊕" => OsCode::KEY_KBDILLUMUP,
+        "bldn" | "⌨💡−" | "⌨💡➖" | "⌨💡₋" | "⌨💡⊖" => OsCode::KEY_KBDILLUMDOWN,
+        "MediaTrackNext" | "next" | "▶▶" => OsCode::KEY_NEXTSONG,
+        "MediaPlayPause" | "pp" | "▶⏸" => OsCode::KEY_PLAYPAUSE,
+        "MediaTrackPrevious" | "prev" | "◀◀" => OsCode::KEY_PREVIOUSSONG,
+        "F1" | "f1" => OsCode::KEY_F1,
+        "F2" | "f2" => OsCode::KEY_F2,
+        "F3" | "f3" => OsCode::KEY_F3,
+        "F4" | "f4" => OsCode::KEY_F4,
+        "F5" | "f5" => OsCode::KEY_F5,
+        "F6" | "f6" => OsCode::KEY_F6,
+        "F7" | "f7" => OsCode::KEY_F7,
+        "F8" | "f8" => OsCode::KEY_F8,
+        "F9" | "f9" => OsCode::KEY_F9,
+        "F10" | "f10" => OsCode::KEY_F10,
+        "F11" | "f11" => OsCode::KEY_F11,
+        "F12" | "f12" => OsCode::KEY_F12,
+        "F13" | "f13" => OsCode::KEY_F13,
+        "F14" | "f14" => OsCode::KEY_F14,
+        "F15" | "f15" => OsCode::KEY_F15,
+        "F16" | "f16" => OsCode::KEY_F16,
+        "F17" | "f17" => OsCode::KEY_F17,
+        "F18" | "f18" => OsCode::KEY_F18,
+        "F19" | "f19" => OsCode::KEY_F19,
+        "F20" | "f20" => OsCode::KEY_F20,
+        "F21" | "f21" => OsCode::KEY_F21,
+        "F22" | "f22" => OsCode::KEY_F22,
+        "F23" | "f23" => OsCode::KEY_F23,
+        "F24" | "f24" => OsCode::KEY_F24,
+        #[cfg(any(target_os = "macos", target_os = "unknown", target_os = "linux"))]
+        "fn" | "🌐" | "ƒ" | "ⓕ" | "Ⓕ" | "🄵" | "🅕" | "🅵" => OsCode::KEY_FN,
         #[cfg(target_os = "windows")]
         "kana" | "katakana" | "katakanahiragana" => OsCode::KEY_HANGEUL,
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "kana" | "katakanahiragana" => OsCode::KEY_KATAKANAHIRAGANA,
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "hiragana" => OsCode::KEY_HIRAGANA,
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "katakana" => OsCode::KEY_KATAKANA,
         "cnv" | "conv" | "henk" | "hnk" | "henkan" => OsCode::KEY_HENKAN,
         "ncnv" | "mhnk" | "muhenkan" => OsCode::KEY_MUHENKAN,
-        "ro" => OsCode::KEY_RO,
+        #[cfg(target_os = "macos")]
+        "Lang1" | "kana" => OsCode::KEY_HANGEUL,
+        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+        "Lang2" | "eisu" => OsCode::KEY_HANJA,
+
+        "IntlRo" | "ro" => OsCode::KEY_RO,
 
-        #[cfg(target_os = "linux")]
-        "prtsc" | "prnt" => OsCode::KEY_SYSRQ,
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
+        "PrintScreen" | "prtsc" | "prnt" | "⎙" => OsCode::KEY_SYSRQ,
         #[cfg(target_os = "windows")]
-        "prtsc" | "prnt" => OsCode::KEY_PRINT,
+        "PrintScreen" | "prtsc" | "prnt" | "⎙" => OsCode::KEY_PRINT,
 
-        "mlft" | "mouseleft" => OsCode::BTN_LEFT,
-        "mrgt" | "mouseright" => OsCode::BTN_RIGHT,
-        "mmid" | "mousemid" => OsCode::BTN_MIDDLE,
-        "mfwd" | "mouseforward" => OsCode::BTN_EXTRA,
-        "mbck" | "mousebackward" => OsCode::BTN_SIDE,
+        "mlft" | "mouseleft" | "🖰1" | "‹🖰" => OsCode::BTN_LEFT,
+        "mrgt" | "mouseright" | "🖰2" | "🖰›" => OsCode::BTN_RIGHT,
+        "mmid" | "mousemid" | "🖰3" => OsCode::BTN_MIDDLE,
+        "mbck" | "mousebackward" | "🖰4" => OsCode::BTN_SIDE,
+        "mfwd" | "mouseforward" | "🖰5" => OsCode::BTN_EXTRA,
+        "mwu" | "mousewheelup" => OsCode::MouseWheelUp,
+        "mwd" | "mousewheeldown" => OsCode::MouseWheelDown,
+        "mwl" | "mousewheelleft" => OsCode::MouseWheelLeft,
+        "mwr" | "mousewheelright" => OsCode::MouseWheelRight,
 
         "hmpg" | "homepage" => OsCode::KEY_HOMEPAGE,
         "mdia" | "media" => OsCode::KEY_MEDIA,
-        "mail" => OsCode::KEY_MAIL,
+        "LaunchMail" | "mail" => OsCode::KEY_MAIL,
         "email" => OsCode::KEY_EMAIL,
         "calc" => OsCode::KEY_CALC,
 
         // NOTE: these are linux-only right now due to missing the mappings in windows.rs
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "plyr" | "player" => OsCode::KEY_PLAYER,
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "powr" | "power" => OsCode::KEY_POWER,
-        #[cfg(target_os = "linux")]
+        #[cfg(any(target_os = "linux", target_os = "android", target_os = "unknown"))]
         "zzz" | "sleep" => OsCode::KEY_SLEEP,
 
-        _ => {
-            let custom_mappings = CUSTOM_STRS_TO_OSCODES.lock();
-            match custom_mappings.get(s) {
-                Some(osc) => *osc,
-                None => return None,
-            }
-        }
+        "sls" | "SpotLightSearch" => OsCode::KEY_249,
+        "dtn" | "Dictation" => OsCode::KEY_250,
+        "dnd" | "DoNotDisturb" => OsCode::KEY_251,
+        "mctl" | "MissionControl" => OsCode::KEY_252,
+        "lpad" | "LaunchPad" => OsCode::KEY_253,
+
+        // Keys that behave as no-ops but can be used in sequences.
+        // Also see: POTENTIAL PROBLEM - G-keys
+        "nop0" => OsCode::KEY_676,
+        "nop1" => OsCode::KEY_677,
+        "nop2" => OsCode::KEY_678,
+        "nop3" => OsCode::KEY_679,
+        "nop4" => OsCode::KEY_680,
+        "nop5" => OsCode::KEY_681,
+        "nop6" => OsCode::KEY_682,
+        "nop7" => OsCode::KEY_683,
+        "nop8" => OsCode::KEY_684,
+        "nop9" => OsCode::KEY_685,
+
+        // has no output mapping. only intended to be used in the input
+        // position, in conjunction with `mouse-movement-key mvmt`
+        "mvmt" | "mousemovement" | "🖰mv" => OsCode::KEY_766,
+
+        _ => return None,
     })
 }
 
@@ -924,9 +1060,9 @@ pub enum OsCode {
     KEY_653 = 653,
     KEY_654 = 654,
     KEY_655 = 655,
-    KEY_656 = 656,
-    KEY_657 = 657,
-    KEY_658 = 658,
+    KEY_656 = 656, // 0x290 : KEY_MACRO1:
+    KEY_657 = 657, // https://github.com/torvalds/linux/commit/b5625db9d23e58a573eb10a7f6d0c2ae060bc0e8
+    KEY_658 = 658, // ...
     KEY_659 = 659,
     KEY_660 = 660,
     KEY_661 = 661,
@@ -944,7 +1080,7 @@ pub enum OsCode {
     KEY_673 = 673,
     KEY_674 = 674,
     KEY_675 = 675,
-    KEY_676 = 676,
+    KEY_676 = 676, // 0x2a4: KEY_MACRO21
     KEY_677 = 677,
     KEY_678 = 678,
     KEY_679 = 679,
@@ -952,8 +1088,8 @@ pub enum OsCode {
     KEY_681 = 681,
     KEY_682 = 682,
     KEY_683 = 683,
-    KEY_684 = 684,
-    KEY_685 = 685,
+    KEY_684 = 684, // ...
+    KEY_685 = 685, // 0x2ad: KEY_MACRO30
     KEY_686 = 686,
     KEY_687 = 687,
     KEY_688 = 688,
@@ -1013,9 +1149,73 @@ pub enum OsCode {
     BTN_TRIGGER_HAPPY39 = 742,
     BTN_TRIGGER_HAPPY40 = 743,
     BTN_MAX = 744,
+
+    // Mouse wheel events are not a part of EV_KEY, so they technically
+    // shouldn't be there, but they're still there, because this way
+    // it's easier to implement allowing to add them to defsrc without
+    // making tons of changes all over the codebase.
+    MouseWheelUp = 745,
+    MouseWheelDown = 746,
+    MouseWheelLeft = 747,
+    MouseWheelRight = 748,
+
+    KEY_749 = 749,
+    KEY_750 = 750,
+    KEY_751 = 751,
+    KEY_752 = 752,
+    KEY_753 = 753,
+    KEY_754 = 754,
+    KEY_755 = 755,
+    KEY_756 = 756,
+    KEY_757 = 757,
+    KEY_758 = 758,
+    KEY_759 = 759,
+    KEY_760 = 760,
+    KEY_761 = 761,
+    KEY_762 = 762,
+    KEY_763 = 763,
+    KEY_764 = 764,
+    KEY_765 = 765,
+    KEY_766 = 766, // aliased to mvmt as a dummy input for use with mouse-movement-key
+
     KEY_MAX = 767,
 }
 
+impl OsCode {
+    pub fn is_mouse_code(&self) -> bool {
+        use OsCode::*;
+        matches!(
+            self,
+            BTN_LEFT
+                | BTN_RIGHT
+                | BTN_MIDDLE
+                | BTN_SIDE
+                | BTN_EXTRA
+                | MouseWheelUp
+                | MouseWheelDown
+                | MouseWheelLeft
+                | MouseWheelRight
+        )
+    }
+}
+
+use core::fmt;
+impl fmt::Display for OsCode {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let self_dbg = format!("{self:?}");
+        if let Some(key) = self_dbg.strip_prefix("KEY_") {
+            write!(f, "{key}")
+        } else {
+            write!(f, "{self:?}")
+        }
+    }
+}
+
+#[test]
+fn parser_key_max_lt_keyberon_key_max() {
+    assert!(u16::from(OsCode::KEY_MAX) < KEY_MAX);
+}
+
 impl TryFrom<usize> for OsCode {
     type Error = ();
     fn try_from(item: usize) -> Result<Self, Self::Error> {
@@ -1050,6 +1250,12 @@ impl From<OsCode> for u32 {
     }
 }
 
+impl From<OsCode> for i32 {
+    fn from(item: OsCode) -> Self {
+        item.as_u16() as i32
+    }
+}
+
 impl From<OsCode> for u16 {
     fn from(item: OsCode) -> Self {
         item.as_u16()
@@ -1066,50 +1272,3 @@ impl From<&KeyCode> for OsCode {
         (*item).into()
     }
 }
-
-// ------------------ KeyValue --------------------
-
-#[derive(Copy, Clone, Debug, PartialEq, Eq)]
-pub enum KeyValue {
-    Release = 0,
-    Press = 1,
-    Repeat = 2,
-}
-
-impl From<i32> for KeyValue {
-    fn from(item: i32) -> Self {
-        match item {
-            0 => Self::Release,
-            1 => Self::Press,
-            2 => Self::Repeat,
-            _ => unreachable!(),
-        }
-    }
-}
-
-impl From<bool> for KeyValue {
-    fn from(up: bool) -> Self {
-        match up {
-            true => Self::Release,
-            false => Self::Press,
-        }
-    }
-}
-
-impl From<KeyValue> for bool {
-    fn from(val: KeyValue) -> Self {
-        matches!(val, KeyValue::Release)
-    }
-}
-#[derive(Debug, Clone, Copy)]
-pub struct KeyEvent {
-    pub code: OsCode,
-    pub value: KeyValue,
-}
-
-#[cfg(not(all(feature = "interception_driver", target_os = "windows")))]
-impl KeyEvent {
-    pub fn new(code: OsCode, value: KeyValue) -> Self {
-        Self { code, value }
-    }
-}
diff --git a/parser/src/keys/windows.rs b/parser/src/keys/windows.rs
index 5c6a1a7a6..8fb9a2b40 100644
--- a/parser/src/keys/windows.rs
+++ b/parser/src/keys/windows.rs
@@ -5,205 +5,267 @@ use super::OsCode;
 #[allow(unused)]
 mod keys {
     // Taken from:
-    // https://github.com/retep998/winapi-rs/blob/0.3/src/um/winuser.rs#L253
-    pub const VK_LBUTTON: u16 = 0x01;
-    pub const VK_RBUTTON: u16 = 0x02;
-    pub const VK_CANCEL: u16 = 0x03;
-    pub const VK_MBUTTON: u16 = 0x04;
-    pub const VK_XBUTTON1: u16 = 0x05;
-    pub const VK_XBUTTON2: u16 = 0x06;
-    pub const VK_BACK: u16 = 0x08;
-    pub const VK_TAB: u16 = 0x09;
-    pub const VK_CLEAR: u16 = 0x0C;
-    pub const VK_RETURN: u16 = 0x0D;
-    pub const VK_SHIFT: u16 = 0x10;
-    pub const VK_CONTROL: u16 = 0x11;
-    pub const VK_MENU: u16 = 0x12;
-    pub const VK_PAUSE: u16 = 0x13;
-    pub const VK_CAPITAL: u16 = 0x14;
-    pub const VK_KANA: u16 = 0x15;
-    pub const VK_HANGEUL: u16 = 0x15;
-    pub const VK_HANGUL: u16 = 0x15;
-    pub const VK_JUNJA: u16 = 0x17;
-    pub const VK_FINAL: u16 = 0x18;
-    pub const VK_HANJA: u16 = 0x19;
-    pub const VK_KANJI: u16 = 0x19;
-    pub const VK_ESCAPE: u16 = 0x1B;
-    pub const VK_CONVERT: u16 = 0x1C;
-    pub const VK_NONCONVERT: u16 = 0x1D;
-    pub const VK_ACCEPT: u16 = 0x1E;
-    pub const VK_MODECHANGE: u16 = 0x1F;
-    pub const VK_SPACE: u16 = 0x20;
-    pub const VK_PRIOR: u16 = 0x21;
-    pub const VK_NEXT: u16 = 0x22;
-    pub const VK_END: u16 = 0x23;
-    pub const VK_HOME: u16 = 0x24;
-    pub const VK_LEFT: u16 = 0x25;
-    pub const VK_UP: u16 = 0x26;
-    pub const VK_RIGHT: u16 = 0x27;
-    pub const VK_DOWN: u16 = 0x28;
-    pub const VK_SELECT: u16 = 0x29;
-    pub const VK_PRINT: u16 = 0x2A;
-    pub const VK_EXECUTE: u16 = 0x2B;
-    pub const VK_SNAPSHOT: u16 = 0x2C;
-    pub const VK_INSERT: u16 = 0x2D;
-    pub const VK_DELETE: u16 = 0x2E;
-    pub const VK_HELP: u16 = 0x2F;
-    pub const VK_LWIN: u16 = 0x5B;
-    pub const VK_RWIN: u16 = 0x5C;
-    pub const VK_APPS: u16 = 0x5D;
-    pub const VK_SLEEP: u16 = 0x5F;
-    pub const VK_NUMPAD0: u16 = 0x60;
-    pub const VK_NUMPAD1: u16 = 0x61;
-    pub const VK_NUMPAD2: u16 = 0x62;
-    pub const VK_NUMPAD3: u16 = 0x63;
-    pub const VK_NUMPAD4: u16 = 0x64;
-    pub const VK_NUMPAD5: u16 = 0x65;
-    pub const VK_NUMPAD6: u16 = 0x66;
-    pub const VK_NUMPAD7: u16 = 0x67;
-    pub const VK_NUMPAD8: u16 = 0x68;
-    pub const VK_NUMPAD9: u16 = 0x69;
-    pub const VK_MULTIPLY: u16 = 0x6A;
-    pub const VK_ADD: u16 = 0x6B;
-    pub const VK_SEPARATOR: u16 = 0x6C;
-    pub const VK_SUBTRACT: u16 = 0x6D;
-    pub const VK_DECIMAL: u16 = 0x6E;
-    pub const VK_DIVIDE: u16 = 0x6F;
-    pub const VK_F1: u16 = 0x70;
-    pub const VK_F2: u16 = 0x71;
-    pub const VK_F3: u16 = 0x72;
-    pub const VK_F4: u16 = 0x73;
-    pub const VK_F5: u16 = 0x74;
-    pub const VK_F6: u16 = 0x75;
-    pub const VK_F7: u16 = 0x76;
-    pub const VK_F8: u16 = 0x77;
-    pub const VK_F9: u16 = 0x78;
-    pub const VK_F10: u16 = 0x79;
-    pub const VK_F11: u16 = 0x7A;
-    pub const VK_F12: u16 = 0x7B;
-    pub const VK_F13: u16 = 0x7C;
-    pub const VK_F14: u16 = 0x7D;
-    pub const VK_F15: u16 = 0x7E;
-    pub const VK_F16: u16 = 0x7F;
-    pub const VK_F17: u16 = 0x80;
-    pub const VK_F18: u16 = 0x81;
-    pub const VK_F19: u16 = 0x82;
-    pub const VK_F20: u16 = 0x83;
-    pub const VK_F21: u16 = 0x84;
-    pub const VK_F22: u16 = 0x85;
-    pub const VK_F23: u16 = 0x86;
-    pub const VK_F24: u16 = 0x87;
-    pub const VK_NAVIGATION_VIEW: u16 = 0x88;
-    pub const VK_NAVIGATION_MENU: u16 = 0x89;
-    pub const VK_NAVIGATION_UP: u16 = 0x8A;
-    pub const VK_NAVIGATION_DOWN: u16 = 0x8B;
-    pub const VK_NAVIGATION_LEFT: u16 = 0x8C;
-    pub const VK_NAVIGATION_RIGHT: u16 = 0x8D;
-    pub const VK_NAVIGATION_ACCEPT: u16 = 0x8E;
-    pub const VK_NAVIGATION_CANCEL: u16 = 0x8F;
-    pub const VK_NUMLOCK: u16 = 0x90;
-    pub const VK_SCROLL: u16 = 0x91;
-    pub const VK_OEM_NEC_EQUAL: u16 = 0x92;
-    pub const VK_OEM_FJ_JISHO: u16 = 0x92;
-    pub const VK_OEM_FJ_MASSHOU: u16 = 0x93;
-    pub const VK_OEM_FJ_TOUROKU: u16 = 0x94;
-    pub const VK_OEM_FJ_LOYA: u16 = 0x95;
-    pub const VK_OEM_FJ_ROYA: u16 = 0x96;
-    pub const VK_LSHIFT: u16 = 0xA0;
-    pub const VK_RSHIFT: u16 = 0xA1;
-    pub const VK_LCONTROL: u16 = 0xA2;
-    pub const VK_RCONTROL: u16 = 0xA3;
-    pub const VK_LMENU: u16 = 0xA4;
-    pub const VK_RMENU: u16 = 0xA5;
-    pub const VK_BROWSER_BACK: u16 = 0xA6;
-    pub const VK_BROWSER_FORWARD: u16 = 0xA7;
-    pub const VK_BROWSER_REFRESH: u16 = 0xA8;
-    pub const VK_BROWSER_STOP: u16 = 0xA9;
-    pub const VK_BROWSER_SEARCH: u16 = 0xAA;
-    pub const VK_BROWSER_FAVORITES: u16 = 0xAB;
-    pub const VK_BROWSER_HOME: u16 = 0xAC;
-    pub const VK_VOLUME_MUTE: u16 = 0xAD;
-    pub const VK_VOLUME_DOWN: u16 = 0xAE;
-    pub const VK_VOLUME_UP: u16 = 0xAF;
-    pub const VK_MEDIA_NEXT_TRACK: u16 = 0xB0;
-    pub const VK_MEDIA_PREV_TRACK: u16 = 0xB1;
-    pub const VK_MEDIA_STOP: u16 = 0xB2;
-    pub const VK_MEDIA_PLAY_PAUSE: u16 = 0xB3;
-    pub const VK_LAUNCH_MAIL: u16 = 0xB4;
-    pub const VK_LAUNCH_MEDIA_SELECT: u16 = 0xB5;
-    pub const VK_LAUNCH_APP1: u16 = 0xB6;
-    pub const VK_LAUNCH_APP2: u16 = 0xB7;
-    pub const VK_OEM_1: u16 = 0xBA;
-    pub const VK_OEM_PLUS: u16 = 0xBB;
-    pub const VK_OEM_COMMA: u16 = 0xBC;
-    pub const VK_OEM_MINUS: u16 = 0xBD;
-    pub const VK_OEM_PERIOD: u16 = 0xBE;
-    pub const VK_OEM_2: u16 = 0xBF;
-    pub const VK_OEM_3: u16 = 0xC0;
-    pub const VK_GAMEPAD_A: u16 = 0xC3;
-    pub const VK_GAMEPAD_B: u16 = 0xC4;
-    pub const VK_GAMEPAD_X: u16 = 0xC5;
-    pub const VK_GAMEPAD_Y: u16 = 0xC6;
-    pub const VK_GAMEPAD_RIGHT_SHOULDER: u16 = 0xC7;
-    pub const VK_GAMEPAD_LEFT_SHOULDER: u16 = 0xC8;
-    pub const VK_GAMEPAD_LEFT_TRIGGER: u16 = 0xC9;
-    pub const VK_GAMEPAD_RIGHT_TRIGGER: u16 = 0xCA;
-    pub const VK_GAMEPAD_DPAD_UP: u16 = 0xCB;
-    pub const VK_GAMEPAD_DPAD_DOWN: u16 = 0xCC;
-    pub const VK_GAMEPAD_DPAD_LEFT: u16 = 0xCD;
-    pub const VK_GAMEPAD_DPAD_RIGHT: u16 = 0xCE;
-    pub const VK_GAMEPAD_MENU: u16 = 0xCF;
-    pub const VK_GAMEPAD_VIEW: u16 = 0xD0;
-    pub const VK_GAMEPAD_LEFT_THUMBSTICK_BUTTON: u16 = 0xD1;
-    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_BUTTON: u16 = 0xD2;
-    pub const VK_GAMEPAD_LEFT_THUMBSTICK_UP: u16 = 0xD3;
-    pub const VK_GAMEPAD_LEFT_THUMBSTICK_DOWN: u16 = 0xD4;
-    pub const VK_GAMEPAD_LEFT_THUMBSTICK_RIGHT: u16 = 0xD5;
-    pub const VK_GAMEPAD_LEFT_THUMBSTICK_LEFT: u16 = 0xD6;
-    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_UP: u16 = 0xD7;
-    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_DOWN: u16 = 0xD8;
-    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_RIGHT: u16 = 0xD9;
-    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_LEFT: u16 = 0xDA;
-    pub const VK_OEM_4: u16 = 0xDB;
-    pub const VK_OEM_5: u16 = 0xDC;
-    pub const VK_OEM_6: u16 = 0xDD;
-    pub const VK_OEM_7: u16 = 0xDE;
-    pub const VK_OEM_8: u16 = 0xDF;
-    pub const VK_OEM_AX: u16 = 0xE1;
-    pub const VK_OEM_102: u16 = 0xE2;
-    pub const VK_ICO_HELP: u16 = 0xE3;
-    pub const VK_ICO_00: u16 = 0xE4;
-    pub const VK_PROCESSKEY: u16 = 0xE5;
-    pub const VK_ICO_CLEAR: u16 = 0xE6;
-    pub const VK_PACKET: u16 = 0xE7;
-    pub const VK_OEM_RESET: u16 = 0xE9;
-    pub const VK_OEM_JUMP: u16 = 0xEA;
-    pub const VK_OEM_PA1: u16 = 0xEB;
-    pub const VK_OEM_PA2: u16 = 0xEC;
-    pub const VK_OEM_PA3: u16 = 0xED;
-    pub const VK_OEM_WSCTRL: u16 = 0xEE;
-    pub const VK_OEM_CUSEL: u16 = 0xEF;
-    pub const VK_OEM_ATTN: u16 = 0xF0;
-    pub const VK_OEM_FINISH: u16 = 0xF1;
-    pub const VK_OEM_COPY: u16 = 0xF2;
-    pub const VK_OEM_AUTO: u16 = 0xF3;
-    pub const VK_OEM_ENLW: u16 = 0xF4;
-    pub const VK_OEM_BACKTAB: u16 = 0xF5;
-    pub const VK_ATTN: u16 = 0xF6;
-    pub const VK_CRSEL: u16 = 0xF7;
-    pub const VK_EXSEL: u16 = 0xF8;
-    pub const VK_EREOF: u16 = 0xF9;
-    pub const VK_PLAY: u16 = 0xFA;
-    pub const VK_ZOOM: u16 = 0xFB;
-    pub const VK_NONAME: u16 = 0xFC;
-    pub const VK_PA1: u16 = 0xFD;
-    pub const VK_OEM_CLEAR: u16 = 0xFE;
-    pub const VK_KPENTER_FAKE: u16 = 0xFF;
+    // https://github.com/microsoft/windows-rs/blob/0.55.0/crates/libs/windows/src/Windows/Win32/UI/Input/KeyboardAndMouse/mod.rs
+    // Category             Count  List
+    // Reserved             #  6   7 10 11                            94                                     184 185
+    // Unassigned/undefined # 19           14 15 58 59 60 61 62 63 64    151 152 153 154 155 156 157 158 159         232
+    // Assigned             #230
+    // Total                #255
+    // 232 unassigned used as a `VK_KPENTER_FAKE`
+    pub type VirtualKey = u16;
+    pub const VK_KPENTER_FAKE: VirtualKey = 232u16; // unassigned VK used to enable Interception use
+    pub const VK_0: VirtualKey = 48u16;
+    pub const VK_1: VirtualKey = 49u16;
+    pub const VK_2: VirtualKey = 50u16;
+    pub const VK_3: VirtualKey = 51u16;
+    pub const VK_4: VirtualKey = 52u16;
+    pub const VK_5: VirtualKey = 53u16;
+    pub const VK_6: VirtualKey = 54u16;
+    pub const VK_7: VirtualKey = 55u16;
+    pub const VK_8: VirtualKey = 56u16;
+    pub const VK_9: VirtualKey = 57u16;
+    pub const VK_A: VirtualKey = 65u16;
+    pub const VK_ABNT_C1: VirtualKey = 193u16;
+    pub const VK_ABNT_C2: VirtualKey = 194u16;
+    pub const VK_ACCEPT: VirtualKey = 30u16;
+    pub const VK_ADD: VirtualKey = 107u16;
+    pub const VK_APPS: VirtualKey = 93u16;
+    pub const VK_ATTN: VirtualKey = 246u16;
+    pub const VK_B: VirtualKey = 66u16;
+    pub const VK_BACK: VirtualKey = 8u16;
+    pub const VK_BROWSER_BACK: VirtualKey = 166u16;
+    pub const VK_BROWSER_FAVORITES: VirtualKey = 171u16;
+    pub const VK_BROWSER_FORWARD: VirtualKey = 167u16;
+    pub const VK_BROWSER_HOME: VirtualKey = 172u16;
+    pub const VK_BROWSER_REFRESH: VirtualKey = 168u16;
+    pub const VK_BROWSER_SEARCH: VirtualKey = 170u16;
+    pub const VK_BROWSER_STOP: VirtualKey = 169u16;
+    pub const VK_C: VirtualKey = 67u16;
+    pub const VK_CANCEL: VirtualKey = 3u16;
+    pub const VK_CAPITAL: VirtualKey = 20u16;
+    pub const VK_CLEAR: VirtualKey = 12u16;
+    pub const VK_CONTROL: VirtualKey = 17u16;
+    pub const VK_CONVERT: VirtualKey = 28u16;
+    pub const VK_CRSEL: VirtualKey = 247u16;
+    pub const VK_D: VirtualKey = 68u16;
+    pub const VK_DBE_ALPHANUMERIC: VirtualKey = 240u16;
+    pub const VK_DBE_CODEINPUT: VirtualKey = 250u16;
+    pub const VK_DBE_DBCSCHAR: VirtualKey = 244u16;
+    pub const VK_DBE_DETERMINESTRING: VirtualKey = 252u16;
+    pub const VK_DBE_ENTERDLGCONVERSIONMODE: VirtualKey = 253u16;
+    pub const VK_DBE_ENTERIMECONFIGMODE: VirtualKey = 248u16;
+    pub const VK_DBE_ENTERWORDREGISTERMODE: VirtualKey = 247u16;
+    pub const VK_DBE_FLUSHSTRING: VirtualKey = 249u16;
+    pub const VK_DBE_HIRAGANA: VirtualKey = 242u16;
+    pub const VK_DBE_KATAKANA: VirtualKey = 241u16;
+    pub const VK_DBE_NOCODEINPUT: VirtualKey = 251u16;
+    pub const VK_DBE_NOROMAN: VirtualKey = 246u16;
+    pub const VK_DBE_ROMAN: VirtualKey = 245u16;
+    pub const VK_DBE_SBCSCHAR: VirtualKey = 243u16;
+    pub const VK_DECIMAL: VirtualKey = 110u16;
+    pub const VK_DELETE: VirtualKey = 46u16;
+    pub const VK_DIVIDE: VirtualKey = 111u16;
+    pub const VK_DOWN: VirtualKey = 40u16;
+    pub const VK_E: VirtualKey = 69u16;
+    pub const VK_END: VirtualKey = 35u16;
+    pub const VK_EREOF: VirtualKey = 249u16;
+    pub const VK_ESCAPE: VirtualKey = 27u16;
+    pub const VK_EXECUTE: VirtualKey = 43u16;
+    pub const VK_EXSEL: VirtualKey = 248u16;
+    pub const VK_F: VirtualKey = 70u16;
+    pub const VK_F1: VirtualKey = 112u16;
+    pub const VK_F10: VirtualKey = 121u16;
+    pub const VK_F11: VirtualKey = 122u16;
+    pub const VK_F12: VirtualKey = 123u16;
+    pub const VK_F13: VirtualKey = 124u16;
+    pub const VK_F14: VirtualKey = 125u16;
+    pub const VK_F15: VirtualKey = 126u16;
+    pub const VK_F16: VirtualKey = 127u16;
+    pub const VK_F17: VirtualKey = 128u16;
+    pub const VK_F18: VirtualKey = 129u16;
+    pub const VK_F19: VirtualKey = 130u16;
+    pub const VK_F2: VirtualKey = 113u16;
+    pub const VK_F20: VirtualKey = 131u16;
+    pub const VK_F21: VirtualKey = 132u16;
+    pub const VK_F22: VirtualKey = 133u16;
+    pub const VK_F23: VirtualKey = 134u16;
+    pub const VK_F24: VirtualKey = 135u16;
+    pub const VK_F3: VirtualKey = 114u16;
+    pub const VK_F4: VirtualKey = 115u16;
+    pub const VK_F5: VirtualKey = 116u16;
+    pub const VK_F6: VirtualKey = 117u16;
+    pub const VK_F7: VirtualKey = 118u16;
+    pub const VK_F8: VirtualKey = 119u16;
+    pub const VK_F9: VirtualKey = 120u16;
+    pub const VK_FINAL: VirtualKey = 24u16;
+    pub const VK_G: VirtualKey = 71u16;
+    pub const VK_GAMEPAD_A: VirtualKey = 195u16;
+    pub const VK_GAMEPAD_B: VirtualKey = 196u16;
+    pub const VK_GAMEPAD_DPAD_DOWN: VirtualKey = 204u16;
+    pub const VK_GAMEPAD_DPAD_LEFT: VirtualKey = 205u16;
+    pub const VK_GAMEPAD_DPAD_RIGHT: VirtualKey = 206u16;
+    pub const VK_GAMEPAD_DPAD_UP: VirtualKey = 203u16;
+    pub const VK_GAMEPAD_LEFT_SHOULDER: VirtualKey = 200u16;
+    pub const VK_GAMEPAD_LEFT_THUMBSTICK_BUTTON: VirtualKey = 209u16;
+    pub const VK_GAMEPAD_LEFT_THUMBSTICK_DOWN: VirtualKey = 212u16;
+    pub const VK_GAMEPAD_LEFT_THUMBSTICK_LEFT: VirtualKey = 214u16;
+    pub const VK_GAMEPAD_LEFT_THUMBSTICK_RIGHT: VirtualKey = 213u16;
+    pub const VK_GAMEPAD_LEFT_THUMBSTICK_UP: VirtualKey = 211u16;
+    pub const VK_GAMEPAD_LEFT_TRIGGER: VirtualKey = 201u16;
+    pub const VK_GAMEPAD_MENU: VirtualKey = 207u16;
+    pub const VK_GAMEPAD_RIGHT_SHOULDER: VirtualKey = 199u16;
+    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_BUTTON: VirtualKey = 210u16;
+    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_DOWN: VirtualKey = 216u16;
+    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_LEFT: VirtualKey = 218u16;
+    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_RIGHT: VirtualKey = 217u16;
+    pub const VK_GAMEPAD_RIGHT_THUMBSTICK_UP: VirtualKey = 215u16;
+    pub const VK_GAMEPAD_RIGHT_TRIGGER: VirtualKey = 202u16;
+    pub const VK_GAMEPAD_VIEW: VirtualKey = 208u16;
+    pub const VK_GAMEPAD_X: VirtualKey = 197u16;
+    pub const VK_GAMEPAD_Y: VirtualKey = 198u16;
+    pub const VK_H: VirtualKey = 72u16;
+    pub const VK_HANGEUL: VirtualKey = 21u16;
+    pub const VK_HANGUL: VirtualKey = 21u16;
+    pub const VK_HANJA: VirtualKey = 25u16;
+    pub const VK_HELP: VirtualKey = 47u16;
+    pub const VK_HOME: VirtualKey = 36u16;
+    pub const VK_I: VirtualKey = 73u16;
+    pub const VK_ICO_00: VirtualKey = 228u16;
+    pub const VK_ICO_CLEAR: VirtualKey = 230u16;
+    pub const VK_ICO_HELP: VirtualKey = 227u16;
+    pub const VK_IME_OFF: VirtualKey = 26u16;
+    pub const VK_IME_ON: VirtualKey = 22u16;
+    pub const VK_INSERT: VirtualKey = 45u16;
+    pub const VK_J: VirtualKey = 74u16;
+    pub const VK_JUNJA: VirtualKey = 23u16;
+    pub const VK_K: VirtualKey = 75u16;
+    pub const VK_KANA: VirtualKey = 21u16;
+    pub const VK_KANJI: VirtualKey = 25u16;
+    pub const VK_L: VirtualKey = 76u16;
+    pub const VK_LAUNCH_APP1: VirtualKey = 182u16;
+    pub const VK_LAUNCH_APP2: VirtualKey = 183u16;
+    pub const VK_LAUNCH_MAIL: VirtualKey = 180u16;
+    pub const VK_LAUNCH_MEDIA_SELECT: VirtualKey = 181u16;
+    pub const VK_LBUTTON: VirtualKey = 1u16;
+    pub const VK_LCONTROL: VirtualKey = 162u16;
+    pub const VK_LEFT: VirtualKey = 37u16;
+    pub const VK_LMENU: VirtualKey = 164u16;
+    pub const VK_LSHIFT: VirtualKey = 160u16;
+    pub const VK_LWIN: VirtualKey = 91u16;
+    pub const VK_M: VirtualKey = 77u16;
+    pub const VK_MBUTTON: VirtualKey = 4u16;
+    pub const VK_MEDIA_NEXT_TRACK: VirtualKey = 176u16;
+    pub const VK_MEDIA_PLAY_PAUSE: VirtualKey = 179u16;
+    pub const VK_MEDIA_PREV_TRACK: VirtualKey = 177u16;
+    pub const VK_MEDIA_STOP: VirtualKey = 178u16;
+    pub const VK_MENU: VirtualKey = 18u16;
+    pub const VK_MODECHANGE: VirtualKey = 31u16;
+    pub const VK_MULTIPLY: VirtualKey = 106u16;
+    pub const VK_N: VirtualKey = 78u16;
+    pub const VK_NAVIGATION_ACCEPT: VirtualKey = 142u16;
+    pub const VK_NAVIGATION_CANCEL: VirtualKey = 143u16;
+    pub const VK_NAVIGATION_DOWN: VirtualKey = 139u16;
+    pub const VK_NAVIGATION_LEFT: VirtualKey = 140u16;
+    pub const VK_NAVIGATION_MENU: VirtualKey = 137u16;
+    pub const VK_NAVIGATION_RIGHT: VirtualKey = 141u16;
+    pub const VK_NAVIGATION_UP: VirtualKey = 138u16;
+    pub const VK_NAVIGATION_VIEW: VirtualKey = 136u16;
+    pub const VK_NEXT: VirtualKey = 34u16;
+    pub const VK_NONAME: VirtualKey = 252u16;
+    pub const VK_NONCONVERT: VirtualKey = 29u16;
+    pub const VK_NUMLOCK: VirtualKey = 144u16;
+    pub const VK_NUMPAD0: VirtualKey = 96u16;
+    pub const VK_NUMPAD1: VirtualKey = 97u16;
+    pub const VK_NUMPAD2: VirtualKey = 98u16;
+    pub const VK_NUMPAD3: VirtualKey = 99u16;
+    pub const VK_NUMPAD4: VirtualKey = 100u16;
+    pub const VK_NUMPAD5: VirtualKey = 101u16;
+    pub const VK_NUMPAD6: VirtualKey = 102u16;
+    pub const VK_NUMPAD7: VirtualKey = 103u16;
+    pub const VK_NUMPAD8: VirtualKey = 104u16;
+    pub const VK_NUMPAD9: VirtualKey = 105u16;
+    pub const VK_O: VirtualKey = 79u16;
+    pub const VK_OEM_1: VirtualKey = 186u16;
+    pub const VK_OEM_102: VirtualKey = 226u16;
+    pub const VK_OEM_2: VirtualKey = 191u16;
+    pub const VK_OEM_3: VirtualKey = 192u16;
+    pub const VK_OEM_4: VirtualKey = 219u16;
+    pub const VK_OEM_5: VirtualKey = 220u16;
+    pub const VK_OEM_6: VirtualKey = 221u16;
+    pub const VK_OEM_7: VirtualKey = 222u16;
+    pub const VK_OEM_8: VirtualKey = 223u16;
+    pub const VK_OEM_ATTN: VirtualKey = 240u16;
+    pub const VK_OEM_AUTO: VirtualKey = 243u16;
+    pub const VK_OEM_AX: VirtualKey = 225u16;
+    pub const VK_OEM_BACKTAB: VirtualKey = 245u16;
+    pub const VK_OEM_CLEAR: VirtualKey = 254u16;
+    pub const VK_OEM_COMMA: VirtualKey = 188u16;
+    pub const VK_OEM_COPY: VirtualKey = 242u16;
+    pub const VK_OEM_CUSEL: VirtualKey = 239u16;
+    pub const VK_OEM_ENLW: VirtualKey = 244u16;
+    pub const VK_OEM_FINISH: VirtualKey = 241u16;
+    pub const VK_OEM_FJ_JISHO: VirtualKey = 146u16;
+    pub const VK_OEM_FJ_LOYA: VirtualKey = 149u16;
+    pub const VK_OEM_FJ_MASSHOU: VirtualKey = 147u16;
+    pub const VK_OEM_FJ_ROYA: VirtualKey = 150u16;
+    pub const VK_OEM_FJ_TOUROKU: VirtualKey = 148u16;
+    pub const VK_OEM_JUMP: VirtualKey = 234u16;
+    pub const VK_OEM_MINUS: VirtualKey = 189u16;
+    pub const VK_OEM_NEC_EQUAL: VirtualKey = 146u16;
+    pub const VK_OEM_PA1: VirtualKey = 235u16;
+    pub const VK_OEM_PA2: VirtualKey = 236u16;
+    pub const VK_OEM_PA3: VirtualKey = 237u16;
+    pub const VK_OEM_PERIOD: VirtualKey = 190u16;
+    pub const VK_OEM_PLUS: VirtualKey = 187u16;
+    pub const VK_OEM_RESET: VirtualKey = 233u16;
+    pub const VK_OEM_WSCTRL: VirtualKey = 238u16;
+    pub const VK_P: VirtualKey = 80u16;
+    pub const VK_PA1: VirtualKey = 253u16;
+    pub const VK_PACKET: VirtualKey = 231u16;
+    pub const VK_PAUSE: VirtualKey = 19u16;
+    pub const VK_PLAY: VirtualKey = 250u16;
+    pub const VK_PRINT: VirtualKey = 42u16;
+    pub const VK_PRIOR: VirtualKey = 33u16;
+    pub const VK_PROCESSKEY: VirtualKey = 229u16;
+    pub const VK_Q: VirtualKey = 81u16;
+    pub const VK_R: VirtualKey = 82u16;
+    pub const VK_RBUTTON: VirtualKey = 2u16;
+    pub const VK_RCONTROL: VirtualKey = 163u16;
+    pub const VK_RETURN: VirtualKey = 13u16;
+    pub const VK_RIGHT: VirtualKey = 39u16;
+    pub const VK_RMENU: VirtualKey = 165u16;
+    pub const VK_RSHIFT: VirtualKey = 161u16;
+    pub const VK_RWIN: VirtualKey = 92u16;
+    pub const VK_S: VirtualKey = 83u16;
+    pub const VK_SCROLL: VirtualKey = 145u16;
+    pub const VK_SELECT: VirtualKey = 41u16;
+    pub const VK_SEPARATOR: VirtualKey = 108u16;
+    pub const VK_SHIFT: VirtualKey = 16u16;
+    pub const VK_SLEEP: VirtualKey = 95u16;
+    pub const VK_SNAPSHOT: VirtualKey = 44u16;
+    pub const VK_SPACE: VirtualKey = 32u16;
+    pub const VK_SUBTRACT: VirtualKey = 109u16;
+    pub const VK_T: VirtualKey = 84u16;
+    pub const VK_TAB: VirtualKey = 9u16;
+    pub const VK_U: VirtualKey = 85u16;
+    pub const VK_UP: VirtualKey = 38u16;
+    pub const VK_V: VirtualKey = 86u16;
+    pub const VK_VOLUME_DOWN: VirtualKey = 174u16;
+    pub const VK_VOLUME_MUTE: VirtualKey = 173u16;
+    pub const VK_VOLUME_UP: VirtualKey = 175u16;
+    pub const VK_W: VirtualKey = 87u16;
+    pub const VK_X: VirtualKey = 88u16;
+    pub const VK_XBUTTON1: VirtualKey = 5u16;
+    pub const VK_XBUTTON2: VirtualKey = 6u16;
+    pub const VK_Y: VirtualKey = 89u16;
+    pub const VK_Z: VirtualKey = 90u16;
+    pub const VK_ZOOM: VirtualKey = 251u16;
+    pub const VK_NONE: VirtualKey = 255u16;
 }
 pub use keys::*;
 
 impl OsCode {
-    pub const fn from_u16(code: u16) -> Option<Self> {
+    pub(super) const fn from_u16_windows(code: u16) -> Option<Self> {
         match code {
             0x30 => Some(OsCode::KEY_0),
             0x31 => Some(OsCode::KEY_1),
@@ -347,6 +409,8 @@ impl OsCode {
             0xC1 => Some(OsCode::KEY_RO),
             VK_CONVERT => Some(OsCode::KEY_HENKAN),
             VK_NONCONVERT => Some(OsCode::KEY_MUHENKAN),
+            VK_DBE_KATAKANA => Some(OsCode::KEY_KATAKANA),
+            255 => Some(OsCode::KEY_YEN),
             256 => Some(OsCode::BTN_0),
             257 => Some(OsCode::BTN_1),
             258 => Some(OsCode::BTN_2),
@@ -363,11 +427,11 @@ impl OsCode {
             269 => Some(OsCode::KEY_269),
             270 => Some(OsCode::KEY_270),
             271 => Some(OsCode::KEY_271),
-            272 => Some(OsCode::BTN_LEFT),
-            273 => Some(OsCode::BTN_RIGHT),
-            274 => Some(OsCode::BTN_MIDDLE),
-            275 => Some(OsCode::BTN_SIDE),
-            276 => Some(OsCode::BTN_EXTRA),
+            1 => Some(OsCode::BTN_LEFT),
+            2 => Some(OsCode::BTN_RIGHT),
+            4 => Some(OsCode::BTN_MIDDLE),
+            5 => Some(OsCode::BTN_SIDE),
+            6 => Some(OsCode::BTN_EXTRA),
             277 => Some(OsCode::BTN_FORWARD),
             278 => Some(OsCode::BTN_BACK),
             279 => Some(OsCode::BTN_TASK),
@@ -836,12 +900,16 @@ impl OsCode {
             742 => Some(OsCode::BTN_TRIGGER_HAPPY39),
             743 => Some(OsCode::BTN_TRIGGER_HAPPY40),
             744 => Some(OsCode::BTN_MAX),
+            745 => Some(OsCode::MouseWheelUp),
+            746 => Some(OsCode::MouseWheelDown),
+            747 => Some(OsCode::MouseWheelLeft),
+            748 => Some(OsCode::MouseWheelRight),
             767 => Some(OsCode::KEY_MAX),
             _ => None,
         }
     }
 
-    pub const fn as_u16(self) -> u16 {
+    pub(super) const fn as_u16_windows(self) -> u16 {
         match self {
             OsCode::KEY_0 => 0x30,
             OsCode::KEY_1 => 0x31,
@@ -988,6 +1056,8 @@ impl OsCode {
             OsCode::BTN_MIDDLE => VK_MBUTTON,
             OsCode::BTN_SIDE => VK_XBUTTON1,
             OsCode::BTN_EXTRA => VK_XBUTTON2,
+            OsCode::KEY_YEN => 255,
+            OsCode::KEY_KATAKANA => VK_DBE_KATAKANA,
             osc => osc as u16,
         }
     }
diff --git a/parser/src/layers.rs b/parser/src/layers.rs
index 1e3bca738..b798ae327 100644
--- a/parser/src/layers.rs
+++ b/parser/src/layers.rs
@@ -1,38 +1,60 @@
+use kanata_keyberon::key_code::KeyCode;
 use kanata_keyberon::layout::*;
 
 use crate::cfg::KanataAction;
+use crate::cfg::alloc::*;
 use crate::custom_action::*;
 use crate::keys::OsCode;
 
+use std::sync::Arc;
+
 // OsCode::KEY_MAX is the biggest OsCode
 pub const KEYS_IN_ROW: usize = OsCode::KEY_MAX as usize;
-pub const LAYER_COLUMNS: usize = 2;
-pub const MAX_LAYERS: usize = 25;
-pub const ACTUAL_NUM_LAYERS: usize = MAX_LAYERS * 2;
-
-pub type KanataLayers = Layers<
-    'static,
-    KEYS_IN_ROW,
-    LAYER_COLUMNS,
-    ACTUAL_NUM_LAYERS,
-    &'static &'static [&'static CustomAction],
->;
-
-type Row = [kanata_keyberon::action::Action<'static, &'static &'static [&'static CustomAction]>;
-    KEYS_IN_ROW];
-
-pub fn new_layers() -> Box<KanataLayers> {
-    let boxed_slice: Box<[[Row; LAYER_COLUMNS]]> = {
-        let mut layers = Vec::with_capacity(ACTUAL_NUM_LAYERS);
-        for _ in 0..ACTUAL_NUM_LAYERS {
-            layers.push([
-                [KanataAction::Trans; KEYS_IN_ROW],
-                [KanataAction::Trans; KEYS_IN_ROW],
-            ]);
+pub const LAYER_ROWS: usize = 2;
+pub const DEFAULT_ACTION: KanataAction = KanataAction::KeyCode(KeyCode::ErrorUndefined);
+
+pub type IntermediateLayers = Box<[[Row; LAYER_ROWS]]>;
+pub type KanataCustom = &'static CustomAction;
+
+pub type KLayers = Layers<'static, KEYS_IN_ROW, LAYER_ROWS, KanataCustom>;
+
+pub struct KanataLayers {
+    pub(crate) layers: Layers<'static, KEYS_IN_ROW, LAYER_ROWS, KanataCustom>,
+    _allocations: Arc<Allocations>,
+}
+
+impl std::fmt::Debug for KanataLayers {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("KanataLayers").finish()
+    }
+}
+
+pub type Row = [kanata_keyberon::action::Action<'static, KanataCustom>; KEYS_IN_ROW];
+
+pub fn new_layers(layers: usize) -> IntermediateLayers {
+    let actual_num_layers = layers;
+    // Note: why construct it like this?
+    // Because don't want to construct KanataLayers on the stack.
+    // The stack will overflow because of lack of placement new.
+    let mut layers = Vec::with_capacity(actual_num_layers);
+    for _ in 0..actual_num_layers {
+        layers.push([[DEFAULT_ACTION; KEYS_IN_ROW], [DEFAULT_ACTION; KEYS_IN_ROW]]);
+    }
+    layers.into_boxed_slice()
+}
+
+impl KanataLayers {
+    /// # Safety
+    ///
+    /// The allocations must hold all of the &'static pointers found in layers.
+    pub(crate) unsafe fn new(layers: KLayers, allocations: Arc<Allocations>) -> Self {
+        Self {
+            layers,
+            _allocations: allocations,
         }
-        layers
     }
-    .into_boxed_slice();
-    let ptr = Box::into_raw(boxed_slice) as *mut KanataLayers;
-    unsafe { Box::from_raw(ptr) }
+
+    pub(crate) fn get(&self) -> (KLayers, Arc<Allocations>) {
+        (self.layers, self._allocations.clone())
+    }
 }
diff --git a/parser/src/lib.rs b/parser/src/lib.rs
index 0bd887531..1d359da13 100644
--- a/parser/src/lib.rs
+++ b/parser/src/lib.rs
@@ -4,5 +4,7 @@ pub mod cfg;
 pub mod custom_action;
 pub mod keys;
 pub mod layers;
+pub mod lsp_hints;
 pub mod sequences;
+pub mod subset;
 pub mod trie;
diff --git a/parser/src/lsp_hints.rs b/parser/src/lsp_hints.rs
new file mode 100644
index 000000000..aac82f6cd
--- /dev/null
+++ b/parser/src/lsp_hints.rs
@@ -0,0 +1,86 @@
+use crate::cfg::sexpr::SExpr;
+
+pub use inner::*;
+
+#[cfg(not(feature = "lsp"))]
+mod inner {
+    #[derive(Debug, Default)]
+    pub struct LspHints {}
+}
+
+#[cfg(feature = "lsp")]
+mod inner {
+    use crate::cfg::sexpr::{Span, Spanned};
+    type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
+
+    #[derive(Debug, Default)]
+    pub struct LspHints {
+        pub inactive_code: Vec<InactiveCode>,
+        pub definition_locations: DefinitionLocations,
+        pub reference_locations: ReferenceLocations,
+    }
+
+    #[derive(Debug, Clone)]
+    pub struct InactiveCode {
+        pub span: Span,
+        pub reason: String,
+    }
+
+    #[derive(Debug, Default, Clone)]
+    pub struct DefinitionLocations {
+        pub alias: HashMap<String, Span>,
+        pub variable: HashMap<String, Span>,
+        pub virtual_key: HashMap<String, Span>,
+        pub layer: HashMap<String, Span>,
+        pub template: HashMap<String, Span>,
+    }
+
+    #[derive(Debug, Default, Clone)]
+    pub struct ReferenceLocations {
+        pub alias: ReferencesMap,
+        pub variable: ReferencesMap,
+        pub virtual_key: ReferencesMap,
+        pub layer: ReferencesMap,
+        pub template: ReferencesMap,
+        pub include: ReferencesMap,
+    }
+
+    #[derive(Debug, Default, Clone)]
+    pub struct ReferencesMap(pub HashMap<String, Vec<Span>>);
+
+    #[allow(unused)]
+    impl ReferencesMap {
+        pub(crate) fn push_from_atom(&mut self, atom: &Spanned<String>) {
+            match self.0.get_mut(&atom.t) {
+                Some(refs) => refs.push(atom.span.clone()),
+                None => {
+                    self.0.insert(atom.t.clone(), vec![atom.span.clone()]);
+                }
+            };
+        }
+
+        pub(crate) fn push(&mut self, name: &str, span: Span) {
+            match self.0.get_mut(name) {
+                Some(refs) => refs.push(span),
+                None => {
+                    self.0.insert(name.to_owned(), vec![span]);
+                }
+            };
+        }
+    }
+}
+
+#[allow(unused)]
+pub(crate) fn set_layer_change_lsp_hint(layer_name_expr: &SExpr, lsp_hints: &mut LspHints) {
+    #[cfg(feature = "lsp")]
+    {
+        let layer_name_atom = match layer_name_expr {
+            SExpr::Atom(x) => x,
+            SExpr::List(_) => unreachable!("checked in layer_idx"),
+        };
+        lsp_hints
+            .reference_locations
+            .layer
+            .push_from_atom(layer_name_atom);
+    }
+}
diff --git a/parser/src/sequences.rs b/parser/src/sequences.rs
index 0936a6197..de3acb646 100644
--- a/parser/src/sequences.rs
+++ b/parser/src/sequences.rs
@@ -2,6 +2,8 @@ use kanata_keyberon::key_code::KeyCode;
 
 pub const MASK_KEYCODES: u16 = 0x03FF;
 pub const MASK_MODDED: u16 = 0xFC00;
+pub const KEY_OVERLAP: KeyCode = KeyCode::ErrorRollOver;
+pub const KEY_OVERLAP_MARKER: u16 = 0x0400;
 
 pub fn mod_mask_for_keycode(kc: KeyCode) -> u16 {
     use KeyCode::*;
@@ -11,6 +13,17 @@ pub fn mod_mask_for_keycode(kc: KeyCode) -> u16 {
         LAlt => 0x2000,
         RAlt => 0x1000,
         LGui | RGui => 0x0800,
+        // This is not real... this is a marker to help signify that key presses should be
+        // overlapping. The way this will look in the chord sequence is as such:
+        //
+        //   [ (0x0400 | X), (0x0400 | Y), (0x0400) ]
+        ErrorRollOver => KEY_OVERLAP_MARKER,
         _ => 0,
     }
 }
+
+#[test]
+fn keys_fit_within_mask() {
+    use crate::keys::OsCode;
+    assert!(MASK_KEYCODES >= u16::from(OsCode::KEY_MAX));
+}
diff --git a/parser/src/subset.rs b/parser/src/subset.rs
new file mode 100644
index 000000000..f1f1664c5
--- /dev/null
+++ b/parser/src/subset.rs
@@ -0,0 +1,183 @@
+//! Collection where keys are slices of a type, and supports a get operation to check if the key
+//! exists, is a subset of any existing key, or is neither of the aforementioned cases.
+//!
+//! In the underlying structure the value is cloned for each participating member of slice key, so
+//! you should ensure values are cheaply clonable. If the value is not, consider putting it inside
+//! `Rc` or `Arc`.
+
+use rustc_hash::FxHashMap;
+use std::hash::Hash;
+
+// # Design considerations:
+//
+// It was considered whether `key` should be in an `Arc` instead of a `Box` or whether
+// `SsmKeyValue` should be wrapped in `Arc`.
+//
+// ## No usage of `Arc`
+//
+// With no reference counting, the key slice `&[K]` will be allocated in a separate box for every
+// instance of `SsmKeyValue`. The number of instances of the key is equal to the length of the key.
+// This is obviously the best choice if key lengths are mostly expected to be 1. For key lengths
+// larger than 1, the point at which an `Arc` would be better would need to be measured.
+//
+// ## `key: Arc<[K]>`
+//
+// The benefit of using an `Arc` for the key instead of `Box` is that clones don't create a new
+// allocation. The downside is that the allocations use more space, namely there is an extra
+// `2 * usize` in the allocation for the strong and weak pointers, so 16 extra bytes.
+//
+// Kanata uses `K=u16` only today (August 2025). This means perfectly sized allocations, it would
+// take a 3 length key for `Box` to begin to reach `Arc`'s size:
+//   - Arc: 16 + (3*2) = 22 bytes
+//   - Box:  3 x (3*2) = 18 bytes
+//
+// A 4-length key is much worse:
+//   - Arc: 16 + (4*2) = 22 bytes
+//   - Box:  4 x (4*2) = 32 bytes
+//
+// In practice, allocators have allocation space overhead and/or minimum allocation sizes. With the
+// effects of these overheads and CPU caching, the estimate of when `Arc` outperforms `Box` for
+// read-only usage is likely a key length of 3 or even 2. Read-only is notable because Kanata
+// doesn't care about write performance; write only happens at parse time and only reads are done
+// for standard runtime.
+//
+// ## Vec<Arc<SsmKeyValue<...>>
+//
+// This has the downside of needing to follow two pointers to dereference `key`. For `Box`-only,
+// or `key: Arc<[K]>`, this is not the case. Having two indirections is not desirable.
+
+#[derive(Debug, Clone)]
+pub struct SubsetMap<K, V> {
+    map: FxHashMap<K, Vec<SsmKeyValue<K, V>>>,
+}
+
+#[derive(Debug, Clone)]
+struct SsmKeyValue<K, V> {
+    key: Box<[K]>,
+    value: V,
+}
+
+impl<K, V> SsmKeyValue<K, V>
+where
+    K: Clone,
+{
+    fn ssmkv_new(key: impl AsRef<[K]>, value: V) -> Self {
+        Self {
+            key: key.as_ref().to_vec().into_boxed_slice(),
+            value,
+        }
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum GetOrIsSubsetOfKnownKey<T> {
+    HasValue(T),
+    IsSubset,
+    Neither,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum SsmKeyExistedBeforeInsert {
+    Existed,
+    NotThere,
+}
+
+use GetOrIsSubsetOfKnownKey::*;
+
+impl<K, V> Default for SubsetMap<K, V>
+where
+    K: Clone + PartialEq + Ord + Hash,
+    V: Clone,
+{
+    fn default() -> Self {
+        Self::ssm_new()
+    }
+}
+
+impl<K, V> SubsetMap<K, V>
+where
+    K: Clone + PartialEq + Ord + Hash,
+    V: Clone,
+{
+    pub fn ssm_new() -> Self {
+        Self {
+            map: FxHashMap::default(),
+        }
+    }
+
+    /// Inserts a potentially unsorted key. Sorts the key and then calls ssm_insert_ksorted.
+    pub fn ssm_insert(&mut self, mut key: impl AsMut<[K]>, val: V) -> SsmKeyExistedBeforeInsert {
+        key.as_mut().sort();
+        self.ssm_insert_ksorted(key.as_mut(), val)
+    }
+
+    /// Inserts a sorted key. Failure to enforce that the key is sorted results in defined but
+    /// unspecified behaviour.
+    pub fn ssm_insert_ksorted(
+        &mut self,
+        key: impl AsRef<[K]>,
+        val: V,
+    ) -> SsmKeyExistedBeforeInsert {
+        let mut key_existed = SsmKeyExistedBeforeInsert::NotThere;
+        for k in key.as_ref().iter().cloned() {
+            let keyvals_for_key_item = self.map.entry(k).or_default();
+            match keyvals_for_key_item
+                .binary_search_by(|probe| probe.key.as_ref().cmp(key.as_ref()))
+            {
+                Ok(pos) => {
+                    key_existed = SsmKeyExistedBeforeInsert::Existed;
+                    keyvals_for_key_item[pos] = SsmKeyValue::ssmkv_new(key.as_ref(), val.clone());
+                }
+                Err(pos) => {
+                    keyvals_for_key_item
+                        .insert(pos, SsmKeyValue::ssmkv_new(key.as_ref(), val.clone()));
+                }
+            }
+        }
+        key_existed
+    }
+
+    /// Gets using a potentially unsorted key. Sorts the key then calls
+    /// ssm_get_or_is_subset_ksorted.
+    pub fn ssm_get_or_is_subset(&self, mut key: impl AsMut<[K]>) -> GetOrIsSubsetOfKnownKey<V> {
+        key.as_mut().sort();
+        self.ssm_get_or_is_subset_ksorted(key.as_mut())
+    }
+
+    /// Gets using a sorted key. Failure to enforce a sorted key results in defined but unspecified
+    /// behaviour.
+    pub fn ssm_get_or_is_subset_ksorted(
+        &self,
+        get_key: impl AsRef<[K]>,
+    ) -> GetOrIsSubsetOfKnownKey<V> {
+        let get_key = get_key.as_ref();
+        if get_key.is_empty() {
+            return match self.is_empty() {
+                true => Neither,
+                false => IsSubset,
+            };
+        }
+        match self.map.get(&get_key[0]) {
+            None => Neither,
+            Some(keyvals_for_key_item) => {
+                match keyvals_for_key_item
+                    .binary_search_by(|probe| probe.key.as_ref().cmp(get_key.as_ref()))
+                {
+                    Ok(pos) => HasValue(keyvals_for_key_item[pos].value.clone()),
+                    Err(_) => {
+                        for kv in keyvals_for_key_item.iter() {
+                            if get_key.iter().all(|kitem| kv.key.contains(kitem)) {
+                                return IsSubset;
+                            }
+                        }
+                        Neither
+                    }
+                }
+            }
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.map.is_empty()
+    }
+}
diff --git a/parser/src/trie.rs b/parser/src/trie.rs
index 31f26968c..d74aedb6b 100644
--- a/parser/src/trie.rs
+++ b/parser/src/trie.rs
@@ -1,64 +1,77 @@
 //! Wrapper around a trie type for (hopefully) easier swapping of libraries if desired.
 
-use radix_trie::TrieCommon;
+use bytemuck::cast_slice;
+use patricia_tree::map::PatriciaMap;
 
-pub type TrieKey = Vec<u16>;
-pub type TrieVal = (u8, u16);
+pub type TrieKeyElement = u16;
 
-pub struct Trie {
-    inner: radix_trie::Trie<TrieKey, TrieVal>,
+#[derive(Debug, Clone)]
+pub struct Trie<T> {
+    inner: patricia_tree::map::PatriciaMap<T>,
 }
 
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub enum GetOrDescendentExistsResult {
+pub enum GetOrDescendentExistsResult<T> {
     NotInTrie,
     InTrie,
-    HasValue(TrieVal),
+    HasValue(T),
 }
 
 use GetOrDescendentExistsResult::*;
 
-impl Trie {
+impl<T> Default for Trie<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn key_len(k: impl AsRef<[u16]>) -> usize {
+    debug_assert!(std::mem::size_of::<TrieKeyElement>() == 2 * std::mem::size_of::<u8>());
+    k.as_ref().len() * 2
+}
+
+impl<T> Trie<T> {
     pub fn new() -> Self {
         Self {
-            inner: radix_trie::Trie::new(),
+            inner: PatriciaMap::new(),
         }
     }
 
-    pub fn ancestor_exists(&self, key: &TrieKey) -> bool {
-        self.inner.get_ancestor(key).is_some()
+    pub fn ancestor_exists(&self, key: impl AsRef<[u16]>) -> bool {
+        self.inner
+            .get_longest_common_prefix(cast_slice(key.as_ref()))
+            .is_some()
     }
 
-    pub fn descendant_exists(&self, key: &TrieKey) -> bool {
-        self.inner.get_raw_descendant(key).is_some()
+    pub fn descendant_exists(&self, key: impl AsRef<[u16]>) -> bool {
+        // Length of the [u8] interpretation of the [u16] key is doubled.
+        self.inner
+            .longest_common_prefix_len(cast_slice(key.as_ref()))
+            == key_len(key)
     }
 
-    pub fn insert(&mut self, key: TrieKey, val: TrieVal) {
-        self.inner.insert(key, val);
+    pub fn insert(&mut self, key: impl AsRef<[u16]>, val: T) {
+        self.inner.insert(cast_slice(key.as_ref()), val);
     }
 
-    pub fn get_or_descendant_exists(&self, key: &TrieKey) -> GetOrDescendentExistsResult {
-        let descendant = self.inner.get_raw_descendant(key);
-        match descendant {
+    pub fn get_or_descendant_exists(&self, key: impl AsRef<[u16]>) -> GetOrDescendentExistsResult<T>
+    where
+        T: Clone,
+    {
+        let mut descendants = self.inner.iter_prefix(cast_slice(key.as_ref()));
+        match descendants.next() {
             None => NotInTrie,
-            Some(subtrie) => {
-                // If the key exists in this subtrie, returns the value. Otherwise returns
-                // KeyInTrie.
-                match subtrie.key() {
-                    Some(stkey) => {
-                        if key == stkey {
-                            HasValue(*subtrie.value().expect("node has value"))
-                        } else {
-                            InTrie
-                        }
-                    }
-                    None => {
-                        // Note: None happens if there are multiple children. The sequence is still
-                        // in the trie.
-                        InTrie
-                    }
+            Some(descendant) => {
+                if descendant.0.len() == key_len(key.as_ref()) {
+                    HasValue(descendant.1.clone())
+                } else {
+                    InTrie
                 }
             }
         }
     }
+
+    pub fn is_empty(&self) -> bool {
+        self.inner.is_empty()
+    }
 }
diff --git a/cfg_samples/all_keys_in_defsrc.kbd b/parser/test_cfgs/all_keys_in_defsrc.kbd
similarity index 100%
rename from cfg_samples/all_keys_in_defsrc.kbd
rename to parser/test_cfgs/all_keys_in_defsrc.kbd
diff --git a/parser/test_cfgs/icon_bad_dupe.kbd b/parser/test_cfgs/icon_bad_dupe.kbd
new file mode 100644
index 000000000..0fa0c83cc
--- /dev/null
+++ b/parser/test_cfgs/icon_bad_dupe.kbd
@@ -0,0 +1,4 @@
+;; This config file is invalid and should be rejected
+(defcfg)
+(defsrc 1)
+(deflayer	(base	icon base.png 🖻 n.ico	) 1)
diff --git a/parser/test_cfgs/icon_good.kbd b/parser/test_cfgs/icon_good.kbd
new file mode 100644
index 000000000..668e0e686
--- /dev/null
+++ b/parser/test_cfgs/icon_good.kbd
@@ -0,0 +1,7 @@
+(defcfg)
+(defsrc 1)
+(deflayer	(base       	icon base.png   	) 1)
+(deflayer	(1emoji     	🖻 1symbols.png  	) 1)
+(deflayer	(2icon-quote	🖻 "2Nav Num.png"	) 1)
+(deflayer	(3emoji_alt 	🖼 3trans.parent 	) 1)
+(deflayermap	(4layermap 	🖼 3trans.parent 	) 0 0)
diff --git a/parser/test_cfgs/include-good-optional-absent.kbd b/parser/test_cfgs/include-good-optional-absent.kbd
new file mode 100644
index 000000000..e98ac689f
--- /dev/null
+++ b/parser/test_cfgs/include-good-optional-absent.kbd
@@ -0,0 +1,3 @@
+(defsrc a)
+(include included-non-existing-file.kbd)
+(include included-good.kbd)
diff --git a/parser/test_cfgs/test.zch b/parser/test_cfgs/test.zch
new file mode 100644
index 000000000..b0c348fb0
--- /dev/null
+++ b/parser/test_cfgs/test.zch
@@ -0,0 +1,5 @@
+dy	day
+dy 1	Monday
+ abc	Alphabet
+r df	recipient
+ w  a	Washington
diff --git a/parser/test_cfgs/testzch.kbd b/parser/test_cfgs/testzch.kbd
new file mode 100644
index 000000000..529ced3ea
--- /dev/null
+++ b/parser/test_cfgs/testzch.kbd
@@ -0,0 +1,3 @@
+(defsrc)
+(deflayer base)
+(defzippy test.zch)
diff --git a/parser/test_cfgs/utf8bom-included.kbd b/parser/test_cfgs/utf8bom-included.kbd
new file mode 100644
index 000000000..f37644501
--- /dev/null
+++ b/parser/test_cfgs/utf8bom-included.kbd
@@ -0,0 +1,12 @@
+#|
+
+BOM should have been added via:
+
+  $f = Get-Content .\utf8bom-included.kbd
+  $f | Out-File -Encoding UTF8 .\utf8bom-included.kbd
+
+|#
+
+(deflayermap (layer-included)
+  y (unicode 🚀)
+)
diff --git a/parser/test_cfgs/utf8bom.kbd b/parser/test_cfgs/utf8bom.kbd
new file mode 100644
index 000000000..4e5669ee4
--- /dev/null
+++ b/parser/test_cfgs/utf8bom.kbd
@@ -0,0 +1,15 @@
+#|
+
+BOM should have been added via:
+
+  $f = Get-Content .\utf8bom.kbd
+  $f | Out-File -Encoding UTF8 .\utf8bom.kbd
+
+|#
+
+(defsrc)
+(deflayermap (layer-name)
+  x (unicode 🙂)
+)
+
+(include utf8bom-included.kbd)
diff --git a/rustfmt.toml b/rustfmt.toml
new file mode 100644
index 000000000..f3e454b61
--- /dev/null
+++ b/rustfmt.toml
@@ -0,0 +1,2 @@
+edition = "2024"
+style_edition = "2024"
diff --git a/scripts/test_linux_list_devices.sh b/scripts/test_linux_list_devices.sh
new file mode 100755
index 000000000..61bb7c6bd
--- /dev/null
+++ b/scripts/test_linux_list_devices.sh
@@ -0,0 +1,175 @@
+#!/bin/bash
+
+# Linux Testing Script for kanata --list functionality
+# Run this on your Ubuntu machine after cloning the repo
+
+set -e  # Exit on any error
+
+echo "🐧 Linux Testing Script for kanata --list"
+echo "========================================"
+echo
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+print_step() {
+    echo -e "${BLUE}📋 $1${NC}"
+}
+
+print_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+print_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Test 1: Basic Build Test
+print_step "Test 1: Building kanata on Linux"
+echo "Building with default features..."
+cargo build --release
+if [ $? -eq 0 ]; then
+    print_success "Build successful"
+else
+    print_error "Build failed"
+    exit 1
+fi
+echo
+
+# Test 2: Help Output Test
+print_step "Test 2: Checking --list availability in help"
+echo "Running: cargo run --release -- --help"
+HELP_OUTPUT=$(cargo run --release -- --help 2>&1)
+if echo "$HELP_OUTPUT" | grep -q "\-l, \-\-list"; then
+    print_success "--list option found in help output"
+else
+    print_error "--list option NOT found in help output"
+    echo "Help output:"
+    echo "$HELP_OUTPUT"
+    exit 1
+fi
+echo
+
+# Test 3: List Devices Functionality
+print_step "Test 3: Testing --list functionality"
+echo "Running: cargo run --release -- --list"
+echo "Note: This may require permissions or show permission errors"
+echo
+
+LIST_OUTPUT=$(cargo run --release -- --list 2>&1)
+EXIT_CODE=$?
+
+echo "Exit code: $EXIT_CODE"
+echo "Output:"
+echo "$LIST_OUTPUT"
+echo
+
+if [ $EXIT_CODE -eq 0 ]; then
+    print_success "--list executed successfully"
+    
+    # Check for expected output format
+    if echo "$LIST_OUTPUT" | grep -q "Available keyboard devices:"; then
+        print_success "Found expected header"
+    else
+        print_warning "Expected header not found"
+    fi
+    
+    if echo "$LIST_OUTPUT" | grep -q "Configuration example:"; then
+        print_success "Found configuration example"
+    else
+        print_warning "Configuration example not found"
+    fi
+    
+else
+    print_warning "--list execution returned non-zero exit code"
+    
+    # Check if it's a permission issue
+    if echo "$LIST_OUTPUT" | grep -q -i "permission"; then
+        print_warning "Permission issue detected - this is expected on some systems"
+        echo
+        echo "💡 Try running with sudo or adding user to input group:"
+        echo "   sudo usermod -a -G input \$USER"
+        echo "   (then log out and back in)"
+    else
+        print_error "Unexpected error"
+    fi
+fi
+echo
+
+# Test 4: System Information
+print_step "Test 4: System Information"
+echo "OS Information:"
+lsb_release -a 2>/dev/null || cat /etc/os-release
+echo
+echo "Available input devices in /dev/input/:"
+ls -la /dev/input/ | head -10
+echo
+echo "Current user groups:"
+groups
+echo
+echo "Input group membership:"
+if groups | grep -q input; then
+    print_success "User is in input group"
+else
+    print_warning "User is NOT in input group"
+    echo "💡 Add user to input group: sudo usermod -a -G input \$USER"
+fi
+echo
+
+# Test 5: Device Files Test
+print_step "Test 5: Input Device Files"
+echo "Checking for keyboard-like devices..."
+DEVICE_COUNT=$(ls /dev/input/event* 2>/dev/null | wc -l)
+echo "Found $DEVICE_COUNT event devices"
+
+if [ $DEVICE_COUNT -gt 0 ]; then
+    print_success "Input devices found"
+    echo "Device files:"
+    ls -la /dev/input/event* 2>/dev/null | head -5
+else
+    print_warning "No input devices found"
+fi
+echo
+
+# Test 6: Dependencies Check
+print_step "Test 6: Dependencies Check"
+echo "Rust version:"
+rustc --version
+echo "Cargo version:"
+cargo --version
+echo
+
+print_step "Test 7: Feature Build Test"  
+echo "Testing build without explicit features..."
+cargo clean
+cargo build --release --no-default-features
+if [ $? -eq 0 ]; then
+    print_success "No-default-features build successful"
+else
+    print_warning "No-default-features build failed"
+fi
+echo
+
+# Summary
+echo "🏁 Linux Testing Summary"
+echo "======================="
+echo "✅ Build test"
+echo "✅ Help output test"
+echo "✅ --list functionality test"
+echo "✅ System information gathering"
+echo "✅ Dependencies check"
+echo
+echo "📋 Next Steps:"
+echo "1. If permission errors: Add user to input group and re-test"
+echo "2. If successful: Test with actual USB keyboard plugged in"
+echo "3. Test edge cases (no keyboards, multiple keyboards, etc.)"
+echo
+echo "🎯 Linux testing complete!"
diff --git a/simulated_input/.gitignore b/simulated_input/.gitignore
new file mode 100644
index 000000000..e5e1f9514
--- /dev/null
+++ b/simulated_input/.gitignore
@@ -0,0 +1 @@
+Cargo.lock
diff --git a/simulated_input/Cargo.toml b/simulated_input/Cargo.toml
new file mode 100644
index 000000000..d139d40cb
--- /dev/null
+++ b/simulated_input/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "kanata-sim"
+version = "0.1.0"
+authors = ["jtroo <j.andreitabs@gmail.com>"]
+description = "Simulated input using kanata"
+keywords = ["kanata", "input", "simulated"]
+homepage = "https://github.com/jtroo/kanata"
+repository = "https://github.com/jtroo/kanata"
+readme = "README.md"
+license = "LGPL-3.0"
+edition = "2021"
+
+[[bin]]
+name = "kanata_simulated_input"
+path = "src/sim.rs"
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4", features = [ "std", "derive", "help", "suggestions" ], default-features = false }
+dirs = "5.0.1"
+log = { version = "0.4.8", default-features = false }
+simplelog = "0.12.0"
+time = "0.3.36"
+
+kanata = { path = ".." , default-features = false }
+
+[features]
+default = ["simulated_output", "tcp_server"]
+simulated_output = ["kanata/simulated_output"]
+simulated_input = ["kanata/simulated_input"]
+passthru_ahk = ["simulated_input","simulated_output"]
+tcp_server = ["kanata/tcp_server"]
diff --git a/simulated_input/README.md b/simulated_input/README.md
new file mode 100644
index 000000000..83a1415a9
--- /dev/null
+++ b/simulated_input/README.md
@@ -0,0 +1,11 @@
+# Kanata simulated input
+
+A CLI tool that lets you run simulated kanata input.
+
+Use the `-c` flag to specify a kanata configuration file
+and the `-s` flag to specify an input simulation file.
+You can pass the `--help` flag for more details.
+
+The input file format is described in the
+[guide](https://github.com/jtroo/kanata/blob/main/docs/config.adoc#test-your-config).
+
diff --git a/simulated_input/src/sim.rs b/simulated_input/src/sim.rs
new file mode 100644
index 000000000..384d77077
--- /dev/null
+++ b/simulated_input/src/sim.rs
@@ -0,0 +1,384 @@
+use anyhow::Result;
+use anyhow::{anyhow, bail};
+use clap::Parser;
+use kanata_state_machine::kanata::handle_fakekey_action;
+use kanata_state_machine::{FAKE_KEY_ROW, FakeKeyAction, oskbd::*, *};
+use simplelog::{format_description, *};
+use std::path::PathBuf;
+
+pub fn default_sim() -> Vec<PathBuf> {
+    let mut cfgs = Vec::new();
+
+    let default = PathBuf::from("test/sim.txt");
+    if default.is_file() {
+        cfgs.push(default);
+    }
+
+    if let Some(config_dir) = dirs::config_dir() {
+        let fallback = config_dir.join("kanata").join("test").join("sim.txt");
+        if fallback.is_file() {
+            cfgs.push(fallback);
+        }
+    }
+
+    cfgs
+}
+
+#[derive(Parser, Debug)]
+#[command(author, version, verbatim_doc_comment)]
+/// kanata_simulated_input: a cli tool that helps debug kanata's user configuration by:
+/// - reading a text file with a sequence of key events, including key delays
+/// - interpreting them with kanata
+/// - printing out which actions or key/mouse events kanata would execute if the keys were
+///   pressed by a user
+/// - (optionally) saving the result to a file for reference
+struct Args {
+    // Display different platform specific paths based on the target OS
+    #[cfg_attr(
+        target_os = "windows",
+        doc = r"Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'C:\Users\user\AppData\Roaming\kanata\kanata.kbd'"
+    )]
+    #[cfg_attr(
+        target_os = "macos",
+        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'$HOME/Library/Application Support/kanata/kanata.kbd.'"
+    )]
+    #[cfg_attr(
+        not(any(target_os = "macos", target_os = "windows")),
+        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'$XDG_CONFIG_HOME/kanata/kanata.kbd'"
+    )]
+    #[arg(short, long, verbatim_doc_comment)]
+    cfg: Option<Vec<PathBuf>>,
+
+    // Display different platform specific paths based on the target OS
+    #[cfg_attr(
+        target_os = "windows",
+        doc = r"Simulation file(s) to use with kanata_simulated_input. If not specified, defaults to
+test\sim.txt in the current working directory and
+'C:\Users\user\AppData\Roaming\kanata\test\sim.txt'"
+    )]
+    #[cfg_attr(
+        target_os = "macos",
+        doc = "Simulation file(s) to use with kanata_simulated_input. If not specified, defaults to
+test/sim.txt in the current working directory and
+'$HOME/Library/Application Support/kanata/test/sim.txt.'"
+    )]
+    #[cfg_attr(
+        not(any(target_os = "macos", target_os = "windows")),
+        doc = "Simulation file(s) to use with kanata_simulated_input. If not specified, defaults to
+test/sim.txt in the current working directory and
+'$XDG_CONFIG_HOME/kanata/test/sim.txt'"
+    )]
+    #[arg(short = 's', long, verbatim_doc_comment)]
+    sim: Option<Vec<PathBuf>>,
+    /// Save output to the simulation file's path with its name appended by the value of this argument.
+    /// This flag generates an error if the binary is compiled without simulated output.
+    #[arg(short = 'o', long, verbatim_doc_comment)]
+    out: Option<String>,
+}
+
+fn log_init() {
+    let mut log_cfg = ConfigBuilder::new();
+    if let Err(e) = log_cfg.set_time_offset_to_local() {
+        eprintln!("WARNING: could not set log TZ to local: {e:?}");
+    };
+    log_cfg.set_time_format_custom(format_description!(
+        version = 2,
+        "[hour]:[minute]:[second].[subsecond digits:4]"
+    ));
+    CombinedLogger::init(vec![TermLogger::new(
+        LevelFilter::Info,
+        log_cfg.build(),
+        TerminalMode::Stderr,
+        ColorChoice::AlwaysAnsi,
+    )])
+    .expect("logger can init");
+}
+
+/// Parse CLI arguments
+fn cli_init_fsim() -> Result<(ValidatedArgs, Vec<PathBuf>, Option<String>)> {
+    let args = Args::parse();
+    let cfg_paths = args.cfg.unwrap_or_else(default_cfg);
+    let sim_paths = args.sim.unwrap_or_else(default_sim);
+    let sim_appendix = args.out;
+
+    log::info!(
+        "kanata_simulated_input v{} starting",
+        env!("CARGO_PKG_VERSION")
+    );
+
+    if let Some(config_file) = cfg_paths.first() {
+        if !config_file.exists() {
+            bail!(
+                "Could not find the config file ({})\nFor more info, pass the `-h` or `--help` flags.",
+                cfg_paths[0].to_str().unwrap_or("?")
+            )
+        }
+    } else {
+        bail!("No config files provided\nFor more info, pass the `-h` or `--help` flags.");
+    }
+    if let Some(config_sim_file) = sim_paths.first() {
+        if !config_sim_file.exists() {
+            bail!(
+                "Could not find the simulation file ({})\nFor more info, pass the `-h` or `--help` flags.",
+                sim_paths[0].to_str().unwrap_or("?")
+            )
+        }
+    } else {
+        bail!("No simulation files provided\nFor more info, pass the `-h` or `--help` flags.");
+    }
+
+    Ok((
+        ValidatedArgs {
+            paths: cfg_paths,
+            #[cfg(feature = "tcp_server")]
+            tcp_server_address: None::<SocketAddrWrapper>,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            symlink_path: None,
+            nodelay: true,
+        },
+        sim_paths,
+        sim_appendix,
+    ))
+}
+
+fn split_at_1(s: &str) -> (&str, &str) {
+    match s.chars().next() {
+        Some(c) => s.split_at(c.len_utf8()),
+        None => s.split_at(0),
+    }
+}
+
+fn parse_fakekey_spec(spec: &str) -> Result<(&str, FakeKeyAction)> {
+    let (name, action) = match spec.split_once(':') {
+        Some((name, action_str)) => {
+            let action = match action_str {
+                "press" | "p" => FakeKeyAction::Press,
+                "release" => FakeKeyAction::Release,
+                "tap" | "t" => FakeKeyAction::Tap,
+                "toggle" | "g" => FakeKeyAction::Toggle,
+                _ => bail!(
+                    "unknown fakekey action: {action_str}. Expected: press, release, tap, or toggle"
+                ),
+            };
+            (name, action)
+        }
+        None => (spec, FakeKeyAction::Press),
+    };
+
+    if name.is_empty() {
+        bail!("fakekey name cannot be empty");
+    }
+
+    Ok((name, action))
+}
+
+fn apply_fakekey_action(k: &mut Kanata, name: &str, action: FakeKeyAction) -> Result<()> {
+    let index = k
+        .virtual_keys
+        .get(name)
+        .ok_or_else(|| anyhow!("unknown virtual key: {name}"))?;
+    log::info!("fakekey action: {name} {action:?}");
+    handle_fakekey_action(action, k.layout.bm(), FAKE_KEY_ROW, *index as u16);
+    Ok(())
+}
+
+fn apply_layer_switch(k: &mut Kanata, layer_name: &str) -> Result<()> {
+    let layer_idx = k
+        .layer_info
+        .iter()
+        .position(|l| l.name == layer_name)
+        .ok_or_else(|| anyhow!("unknown layer: {layer_name}"))?;
+    log::info!("layer-switch: {layer_name} (index {layer_idx})");
+    k.layout.bm().set_default_layer(layer_idx);
+    Ok(())
+}
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub enum LogFmtT {
+    // partial dupe of @simulated since otherwise no-features clippy fails when features are disabled since even though the function body is conditional and doesn't use the enum, the ↓ function signature still uses it, so will warn
+    InKeyUp,
+    InKeyDown,
+    InKeyRep,
+    InTick,
+}
+fn kbd_out_log(
+    _kbd_out: &mut KbdOut,
+    _log_type: LogFmtT,
+    _key_code: Option<OsCode>,
+    _tick: Option<u128>,
+) {
+    let a = LogFmtT::InTick;
+    if a == LogFmtT::InTick {
+        println!("{}", 42)
+    };
+    #[cfg(all(
+        not(feature = "simulated_input"),
+        not(feature = "passthru_ahk"),
+        feature = "simulated_output"
+    ))]
+    {
+        match _log_type {
+            LogFmtT::InTick => {
+                if let Some(tick) = _tick {
+                    _kbd_out.log.in_tick(tick);
+                }
+            }
+            LogFmtT::InKeyUp => {
+                if let Some(key_code) = _key_code {
+                    _kbd_out.log.in_release_key(key_code);
+                }
+            }
+            LogFmtT::InKeyDown => {
+                if let Some(key_code) = _key_code {
+                    _kbd_out.log.in_press_key(key_code);
+                }
+            }
+            LogFmtT::InKeyRep => {
+                if let Some(key_code) = _key_code {
+                    _kbd_out.log.in_repeat_key(key_code);
+                }
+            }
+        }
+    }
+}
+fn main_impl() -> Result<()> {
+    log_init();
+    let (args, sim_paths, _sim_appendix) = cli_init_fsim()?;
+    #[cfg(not(feature = "simulated_output"))]
+    {
+        if _sim_appendix.is_some() {
+            bail!(
+                "The program was compiled without simulated output. The -o|--out flag is unsupported"
+            );
+        }
+    }
+
+    for config_sim_file in &sim_paths {
+        let mut k = Kanata::new(&args)?;
+        log::info!("Evaluating simulation file = {:?}", config_sim_file);
+        let s = std::fs::read_to_string(config_sim_file)?;
+        for l in s.lines() {
+            for pair in l.split_whitespace() {
+                match pair.split_once(':') {
+                    Some((kind, val)) => match kind {
+                        "tick" | "🕐" | "t" => {
+                            let tick = str::parse::<u128>(val)?;
+                            kbd_out_log(&mut k.kbd_out, LogFmtT::InTick, None, Some(tick));
+                            k.tick_ms(tick, &None)?;
+                        }
+                        "press" | "↓" | "d" | "down" => {
+                            let key_code =
+                                str_to_oscode(val).ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                            kbd_out_log(&mut k.kbd_out, LogFmtT::InKeyDown, Some(key_code), None);
+                            k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Press))?;
+                        }
+                        "release" | "↑" | "u" | "up" => {
+                            let key_code =
+                                str_to_oscode(val).ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                            kbd_out_log(&mut k.kbd_out, LogFmtT::InKeyUp, Some(key_code), None);
+                            k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Release))?;
+                        }
+                        "repeat" | "⟳" | "r" => {
+                            let key_code =
+                                str_to_oscode(val).ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                            kbd_out_log(&mut k.kbd_out, LogFmtT::InKeyRep, Some(key_code), None);
+                            k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Repeat))?;
+                        }
+                        // Virtual/fake key activation: fakekey:name[:action] or vk:name[:action]
+                        // Supported actions: press, release, tap, toggle
+                        // Examples: fakekey:vk_bear:press, vk:vk_bear, virtualkey:vk_bear:tap
+                        "fakekey" | "vk" | "virtualkey" | "🎭" => {
+                            let (vk_name, action) = parse_fakekey_spec(val)?;
+                            apply_fakekey_action(&mut k, vk_name, action)?;
+                        }
+                        // Layer switch: ls:layer_name
+                        // Switches to the specified layer as the new default layer.
+                        // Example: ls:nav, ls:symbols
+                        "ls" | "layer-switch" | "🔀" => {
+                            apply_layer_switch(&mut k, val)?;
+                        }
+                        _ => bail!("invalid pair prefix: {kind}"),
+                    },
+                    None => {
+                        let (kind, val) = split_at_1(pair);
+                        match kind {
+                            //allow skipping : separator for unique non-key symbols
+                            "🕐" => {
+                                let tick = str::parse::<u128>(val)?;
+                                kbd_out_log(&mut k.kbd_out, LogFmtT::InTick, None, Some(tick));
+                                k.tick_ms(tick, &None)?;
+                            }
+                            "↓" => {
+                                let key_code = str_to_oscode(val)
+                                    .ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                                kbd_out_log(
+                                    &mut k.kbd_out,
+                                    LogFmtT::InKeyDown,
+                                    Some(key_code),
+                                    None,
+                                );
+                                k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Press))?;
+                            }
+                            "↑" => {
+                                let key_code = str_to_oscode(val)
+                                    .ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                                kbd_out_log(&mut k.kbd_out, LogFmtT::InKeyUp, Some(key_code), None);
+                                k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Release))?;
+                            }
+                            "⟳" => {
+                                let key_code = str_to_oscode(val)
+                                    .ok_or_else(|| anyhow!("unknown key: {val}"))?;
+                                kbd_out_log(
+                                    &mut k.kbd_out,
+                                    LogFmtT::InKeyRep,
+                                    Some(key_code),
+                                    None,
+                                );
+                                k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Repeat))?;
+                            }
+                            "🎭" => {
+                                // Virtual key activation with emoji prefix (defaults to press)
+                                // Format: 🎭vk_name or 🎭vk_name:action
+                                let (vk_name, action) = parse_fakekey_spec(val)?;
+                                apply_fakekey_action(&mut k, vk_name, action)?;
+                            }
+                            "🔀" => {
+                                // Layer switch with emoji prefix
+                                // Format: 🔀layer_name
+                                apply_layer_switch(&mut k, val)?;
+                            }
+                            _ => bail!("invalid pair: {l}"),
+                        }
+                    }
+                }
+            }
+        }
+        #[cfg(all(
+            not(feature = "simulated_input"),
+            not(feature = "passthru_ahk"),
+            feature = "simulated_output"
+        ))]
+        println!("{}", k.kbd_out.outputs.events.join("\n"));
+        #[cfg(all(
+            not(feature = "simulated_input"),
+            not(feature = "passthru_ahk"),
+            feature = "simulated_output"
+        ))]
+        k.kbd_out.log.end(config_sim_file, _sim_appendix.clone());
+    }
+
+    Ok(())
+}
+
+fn main() -> Result<()> {
+    let ret = main_impl();
+    if let Err(ref e) = ret {
+        log::error!("{e}\n");
+    }
+    ret
+}
diff --git a/simulated_passthru/.gitignore b/simulated_passthru/.gitignore
new file mode 100644
index 000000000..e5e1f9514
--- /dev/null
+++ b/simulated_passthru/.gitignore
@@ -0,0 +1 @@
+Cargo.lock
diff --git a/simulated_passthru/Cargo.toml b/simulated_passthru/Cargo.toml
new file mode 100644
index 000000000..3e9660a9a
--- /dev/null
+++ b/simulated_passthru/Cargo.toml
@@ -0,0 +1,39 @@
+[package]
+name   	= "simulated_passthru"
+version	= "0.0.1"
+edition	= "2021"
+
+[lib]
+name      	= "kanata_passthru"
+path      	= "src/lib_passthru.rs"
+crate-type	= ['lib','cdylib']
+
+[dependencies]
+anyhow = "1"
+log = { version = "0.4.8", default-features = false }
+parking_lot = "0.12"
+regex = "1.10.3"
+
+kanata = {path=".." , default-features=false}
+
+lazy_static = "1.4.0"
+
+[target.'cfg(target_os = "windows")'.dependencies]
+encode_unicode = "0.3.6"
+winapi = { version = "0.3.9", features = [
+    "wincon",
+    "timeapi",
+    "mmsystem",
+] }
+native-windows-gui = { version = "1.0.12", default-features = false }
+kanata-interception = { version = "0.3.0", optional = true }
+win_dbg_logger = "0.1.0"
+widestring = "1.1.0"
+
+[features]
+default         	= ["simulated_output","tcp_server"]
+tcp_server      	= ["kanata/tcp_server"]
+simulated_output	= ["kanata/simulated_output"]
+simulated_input 	= ["kanata/simulated_input"]
+passthru_ahk    	= ["simulated_input","simulated_output","kanata/passthru_ahk"]
+perf_logging    	= []
diff --git a/simulated_passthru/ReadMe.md b/simulated_passthru/ReadMe.md
new file mode 100644
index 000000000..769fc08f8
--- /dev/null
+++ b/simulated_passthru/ReadMe.md
@@ -0,0 +1,5 @@
+# Kanata passthru (simulated input and output)
+
+A Windows dynamic library (DLL) that lets you run simulated kanata input and get simulated kanata output.
+
+See a simplified [example](./../docs/simulated_passthru_ahk/) of using AutoHotkey to redirect custom inputhook's key events to kanata and get them remapped using kanata config, e.g., to get better modtap functionality
diff --git a/simulated_passthru/src/key_in.rs b/simulated_passthru/src/key_in.rs
new file mode 100644
index 000000000..a27057488
--- /dev/null
+++ b/simulated_passthru/src/key_in.rs
@@ -0,0 +1,43 @@
+use kanata_state_machine::oskbd::*;
+use log::*;
+
+use winapi::ctypes::*;
+use winapi::shared::minwindef::*;
+
+use crate::oskbd::HOOK_CB;
+
+/// Exported function: receives key input and uses event_loop's input event handler
+/// callback (which will in turn communicate via the internal kanata's channels to
+/// keyberon state machine etc.)
+#[no_mangle]
+pub extern "win64" fn input_ev_listener(vk: c_uint, sc: c_uint, up: c_int) -> LRESULT {
+    #[cfg(feature = "perf_logging")]
+    let start = std::time::Instant::now();
+    let key_event = InputEvent::from_vk_sc(vk, sc, up); //{code:KEY_0,value:Press}
+    let mut h_cbl = HOOK_CB.lock(); // to access the closure we move its box out of the mutex
+    // and put it back after it returned
+    if let Some(mut fnhook) = h_cbl.take() {
+        // move our opt+boxed closure, replacing it with None, can't just .unwrap since Copy
+        // trait not implemented for dyn fnMut
+        let handled = fnhook(key_event); // box(closure)() = closure()
+        *h_cbl = Some(fnhook); // put our closure back
+        if handled {
+            // now try to get the out key events that another thread should've sent via
+            #[cfg(feature = "perf_logging")]
+            debug!(
+                " 🕐{}μs   →→→✓ {key_event} from {vk} sc={sc} up={up}",
+                (start.elapsed()).as_micros()
+            );
+            #[cfg(not(feature = "perf_logging"))]
+            debug!("   →→→✓ {key_event} from {vk} sc={sc} up={up}");
+            1
+        } else {
+            0
+        }
+    } else {
+        error!(
+            "fnHook processing key events isn't available yet {key_event} from {vk} sc={sc} up={up}"
+        );
+        0
+    }
+}
diff --git a/simulated_passthru/src/key_out.rs b/simulated_passthru/src/key_out.rs
new file mode 100644
index 000000000..c3129f3a8
--- /dev/null
+++ b/simulated_passthru/src/key_out.rs
@@ -0,0 +1,116 @@
+use anyhow::Result;
+
+use kanata_state_machine::oskbd::*;
+use log::*;
+
+use winapi::ctypes::*;
+use winapi::shared::minwindef::*;
+
+use std::cell::Cell;
+
+type CbOutEvFn = dyn Fn(i64, i64, i64) -> i64 + 'static;
+thread_local! {static CBOUTEV_WRAP:Cell<Option<Box<CbOutEvFn>>> = Cell::default();}
+// Stores the hook callback for the current thread
+
+/// - Get the address of AutoHotkey's callback function that accepts simulated output
+/// events (and sends them to the OS)
+///   - `cbKanataOut(vk,sc,up) {return 1}` All args are i64 (AHK doesn't support u64)
+/// - Store it in a static thread-local Cell (AHK is single-threaded, so we can only
+///  use this callback from the main thread). KbdOut will use a channel to send a
+///  message key event that will use call the fn from this Cell
+/// address: pointer-sized integer, equivalent to Int64 on ahk64 (c_longlong=i64).
+/// Will be `as`-cast to a raw pointer before `transmute`ing to a function pointer to avoid
+///  an integer-to-pointer `transmute`, which can be problematic. Transmuting between raw pointers
+///  and function pointers (i.e., two pointer types) is fine.
+/// AHK uses x64 calling convention: TODO: is this the same as win64? extern "C" also seems to work?
+#[cfg(feature = "passthru_ahk")]
+pub fn set_cb_out_ev(cb_addr: c_longlong) -> Result<()> {
+    trace!("got func address {}", cb_addr);
+    let ptr_fn = cb_addr as *const ();
+    let cb_out_ev =
+        unsafe { std::mem::transmute::<*const (), fn(vk: i64, sc: i64, up: i64) -> i64>(ptr_fn) };
+    CBOUTEV_WRAP.with(|state| {
+        assert!(
+            state.take().is_none(),
+            "Only 1 callback can be registered per thread"
+        );
+        state.set(Some(Box::new(cb_out_ev)));
+    });
+    Ok(())
+}
+#[cfg(not(feature = "passthru_ahk"))]
+fn set_cb_out_ev(cb_addr: c_longlong) -> Result<()> {
+    debug!("✗✗✗✗ unimplemented!");
+    unimplemented!();
+    Ok(())
+}
+
+pub fn send_out_ev(in_ev: InputEvent) -> Result<()> {
+    // ext callback accepts vk:i64,sc:i64,up:i64
+    #[cfg(feature = "perf_logging")]
+    let start = std::time::Instant::now();
+    let key_event = KeyEvent::try_from(in_ev);
+    debug!("@send_out_ev key_event={key_event:?}");
+    let vk: i64 = in_ev.code.into();
+    let sc: i64 = 0;
+    let up: i64 = in_ev.up.into();
+
+    let mut handled = 0i64;
+    CBOUTEV_WRAP.with(|state| {
+        if let Some(hook) = state.take() {
+            handled = hook(vk, sc, up);
+            state.set(Some(hook));
+        }
+    });
+    #[cfg(feature = "perf_logging")]
+    debug!(
+        "🕐{}μs ←←←{} fnHookCC {key_event:?} {vk} {sc} {up}",
+        (start.elapsed()).as_micros(),
+        if handled == 1 { "✓" } else { "✗" }
+    );
+    #[cfg(not(feature = "perf_logging"))]
+    debug!(
+        "←←←{} fnHookCC {key_event:?} {vk} {sc} {up}",
+        if handled == 1 { "✓" } else { "✗" }
+    );
+    Ok(())
+}
+
+use crate::RX_KEY_EV_OUT;
+use std::sync::mpsc::TryRecvError; // thread_local Cell<Option<Receiver<InputEvent>>>
+// Stores receiver for key data to be sent out for
+// the current thread
+/// Exported function: checks if processing thread has sent key output and sends it
+/// back to an external callback
+#[no_mangle]
+pub extern "win64" fn output_ev_check() -> LRESULT {
+    let mut res: isize = 0;
+    RX_KEY_EV_OUT.with(|state| {
+        if let Some(rx) = state.take() {
+            match rx.try_recv() {
+                Ok(in_ev) => {
+                    debug!("✓ rx_kout@key_out(dll) ‘{in_ev}’");
+                    if send_out_ev(in_ev).is_ok() {
+                        res = 0;
+                    } else {
+                        res = -1;
+                    };
+                }
+                Err(TryRecvError::Empty) => {
+                    debug!("✗ rx_kout@key_out(dll) no data yet");
+                    res = -2
+                }
+                Err(TryRecvError::Disconnected) => {
+                    debug!("✗ rx_kout@key_out(dll) Disconnected");
+                    res = -3
+                }
+            }
+            state.set(Some(rx));
+        } else {
+            debug!("✗ RX_KEY_EV_OUT@key_out(dll) empty");
+            state.set(None);
+            res = -4
+        }
+    });
+    res
+}
diff --git a/simulated_passthru/src/lib_passthru.rs b/simulated_passthru/src/lib_passthru.rs
new file mode 100644
index 000000000..01460dd15
--- /dev/null
+++ b/simulated_passthru/src/lib_passthru.rs
@@ -0,0 +1,145 @@
+#![cfg(all(feature = "passthru_ahk", target_os = "windows"))]
+use anyhow::Result;
+use anyhow::bail;
+
+use kanata_state_machine::{oskbd::*, *};
+use log::*;
+
+fn log_init(max_lvl: &c_longlong) {
+    log_win::init();
+    let _a = log_win::set_thread_state(true);
+    let log_lvl = match max_lvl {
+        1 => log::LevelFilter::Error,
+        2 => log::LevelFilter::Warn,
+        3 => log::LevelFilter::Info,
+        4 => log::LevelFilter::Debug,
+        5 => log::LevelFilter::Trace,
+        _ => log::LevelFilter::Info,
+    };
+    log::set_max_level(log_lvl);
+}
+
+use parking_lot::Mutex;
+use std::cell::Cell;
+use std::sync::{Arc, OnceLock};
+static CFG: OnceLock<Arc<Mutex<Kanata>>> = OnceLock::new();
+
+use winapi::ctypes::*;
+use winapi::shared::minwindef::*;
+#[no_mangle]
+pub extern "win64" fn reset_kanata_state(tick: c_longlong) -> LRESULT {
+    debug!("                               ext →→→ reset_kanata_state");
+    if let Some(cfg) = CFG.get() {
+        if kanata::clean_state(cfg, tick.try_into().unwrap()).is_err() {
+            debug!("✗ @ reset_kanata_state");
+            return 1;
+        };
+    } else {
+        debug!("✗ @ reset_kanata_state, no CFG");
+        return 2;
+    };
+    0
+}
+
+use std::path::PathBuf;
+/// Parse CLI arguments
+fn cli_init(cfg_path: &str) -> Result<ValidatedArgs> {
+    let cfg_file = PathBuf::from(&cfg_path);
+    if !cfg_file.exists() {
+        bail!("Could not find the config file ({:?})", cfg_file)
+    }
+    Ok(ValidatedArgs {
+        paths: vec![cfg_file],
+        #[cfg(feature = "tcp_server")]
+        tcp_server_address: None, //todo: any need in a dll?
+        nodelay: true,
+    })
+}
+
+use std::sync::mpsc::Receiver;
+thread_local! {pub static RX_KEY_EV_OUT:Cell<Option<Receiver<InputEvent>>> = Cell::default();}
+// Stores receiver for key data to be sent out for the current thread
+
+fn lib_impl(cfg_path: &str) -> Result<()> {
+    let args = cli_init(cfg_path)?;
+    let (tx_kout, rx_kout) = std::sync::mpsc::channel(); //async channel
+    let cfg_arc = Kanata::new_with_output_channel(&args, Some(tx_kout))?;
+    // new configuration from a file
+    debug!("loaded {:?}", args.paths[0]);
+    if CFG.set(cfg_arc.clone()).is_err() {
+        warn!("Someone else set our ‘CFG’");
+    }; // store a clone of cfg so that we can ask it to reset itself
+
+    RX_KEY_EV_OUT.with(|state| {
+        assert!(
+            state.take().is_none(),
+            "Only one channel to send keys out can be registered per thread."
+        );
+        state.set(Some(rx_kout));
+    });
+
+    // Start a processing loop in another thread and run the event loop in this thread
+    // The reason for two different event loops is that the "event loop" only listens for keyboard
+    // events, which it sends to the "processing loop". The processing loop handles keyboard events
+    // while also maintaining `tick()` calls to keyberon.
+    let (tx, rx) = std::sync::mpsc::sync_channel(100);
+    let ntx = None;
+    Kanata::start_processing_loop(cfg_arc.clone(), rx, ntx, args.nodelay); // 2 handles keyboard
+    // events while also
+    // maintaining `tick()`
+    // calls to keyberon
+
+    Kanata::event_loop(cfg_arc, tx)?; // 1 only listens for keyboard events
+    // (not a real loop, just registers callback closures
+    // for external function to call at will)
+
+    Ok(())
+}
+
+mod key_in;
+mod key_out;
+
+use crate::key_out::*;
+use widestring::{
+    U16CStr, //   0 U16/U32-CString wide version of the standard CString type
+    U16Str,
+    Utf16Str, // no0 UTF-16 encoded, growable owned string
+    WideChar,
+};
+
+pub mod log_win;
+#[no_mangle]
+pub extern "win64" fn lib_kanata_passthru(
+    cb_addr: c_longlong,
+    cfg_path: &WideChar,
+    max_lvl: c_longlong,
+) -> LRESULT {
+    log_init(&max_lvl);
+    let ret = set_cb_out_ev(cb_addr);
+    if let Err(ref _e) = ret {
+        error!("couldn't register external key out event callback");
+        return 1;
+    };
+    let cfg_path_wc = unsafe { U16CStr::from_ptr_str(cfg_path) }; // Constructs a wide C string
+    // slice from a nul-terminated
+    // string pointer
+    let cfg_path_wx: &U16Str = cfg_path_wc.as_ustr(); // 16b wide string slice with undefined
+    // encoding reject invalid UTF16 (skip check
+    // with from_ustr_unchecked if certain input
+    // is valid UTF16)
+    let cfg_path_w: &Utf16Str = match Utf16Str::from_ustr(cfg_path_wx) {
+        Ok(s) => s,
+        Err(_e) => {
+            error!("{_e}\n");
+            return -1;
+        }
+    };
+    let cfg_path_s: String = cfg_path_w.to_string(); // valid UTF16→conv is lossless&non-fallible
+
+    let ret = lib_impl(&cfg_path_s);
+    if let Err(ref e) = ret {
+        error!("{e}\n");
+        return -2;
+    }
+    0
+}
diff --git a/simulated_passthru/src/log_win.rs b/simulated_passthru/src/log_win.rs
new file mode 100644
index 000000000..49e4594c1
--- /dev/null
+++ b/simulated_passthru/src/log_win.rs
@@ -0,0 +1,118 @@
+//! A logger that prints to OutputDebugString (Windows only)
+use log::{Level, Metadata, Record};
+
+/// Implements `log::Log`, so can be used as a logging provider to
+/// forward log messages to the Windows `OutputDebugString` API
+pub struct WinDebugLogger;
+
+/// Static instance of `WinDebugLogger`, can be directly registered using `log::set_logger`<br>
+/// ```
+/// use kanata_passthru::log_win;
+/// let _ = log_win::init(); // Init
+/// log::set_max_level(log::LevelFilter::Debug);
+/// use log::debug; // Use
+/// debug!("Debug log");
+/// ```
+pub static WINDBG_LOGGER: WinDebugLogger = WinDebugLogger;
+
+/// Convert logging levels to shorter and more visible icons
+pub fn iconify(lvl: log::Level) -> char {
+    match lvl {
+        Level::Error => '❗',
+        Level::Warn => '⚠',
+        Level::Info => 'ⓘ',
+        Level::Debug => 'ⓓ',
+        Level::Trace => 'ⓣ',
+    }
+}
+
+use std::sync::OnceLock;
+pub fn is_thread_state() -> &'static bool {
+    set_thread_state(false)
+}
+pub fn set_thread_state(is: bool) -> &'static bool {
+    // accessor function to avoid get_or_init on every call (lazycell
+    // allows doing that without an extra function)
+    static CELL: OnceLock<bool> = OnceLock::new();
+    CELL.get_or_init(|| is)
+}
+
+use lazy_static::lazy_static;
+use regex::Regex;
+lazy_static! { // shorten source file name, no src/ no .rs ext
+  static ref RE_EXT:Regex = Regex::new(r"\..*$"   ).unwrap();
+  static ref RE_SRC:Regex = Regex::new(r"src[\\/]").unwrap();
+}
+fn clean_name(path: Option<&str>) -> String {
+    if let Some(p) = path {
+        RE_SRC.replace(&RE_EXT.replace(p, ""), "").to_string()
+    } else {
+        "?".to_string()
+    }
+}
+
+#[cfg(target_os = "windows")]
+use winapi::um::processthreadsapi::GetCurrentThreadId;
+impl log::Log for WinDebugLogger {
+    #[cfg(windows)]
+    fn enabled(&self, _metadata: &Metadata) -> bool {
+        true
+    }
+    #[cfg(not(windows))]
+    fn enabled(&self, metadata: &Metadata) -> bool {
+        false
+    }
+    fn log(&self, record: &Record) {
+        #[cfg(not(target_os = "windows"))]
+        let thread_id = "";
+        #[cfg(target_os = "windows")]
+        let thread_id = if *is_thread_state() {
+            format!("¦{}¦", unsafe { GetCurrentThreadId() })
+        } else {
+            "".to_string()
+        };
+        if self.enabled(record.metadata()) {
+            let s = format!(
+                "{}{}{}:{} {}",
+                thread_id,
+                iconify(record.level()),
+                clean_name(record.file()),
+                record.line().unwrap_or(0),
+                record.args()
+            );
+            dbg_win(&s);
+        }
+    }
+    fn flush(&self) {}
+}
+
+pub fn dbg_win(s: &str) {
+    //! Calls the `OutputDebugString` API to log a string (on Windows only)<br>
+    //! See [`OutputDebugStringW`](https://docs.microsoft.com/en-us/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw).
+    #[cfg(windows)]
+    {
+        let len = s.encode_utf16().count() + 1;
+        let mut s_utf16: Vec<u16> = Vec::with_capacity(len + 1);
+        s_utf16.extend(s.encode_utf16());
+        s_utf16.push(0);
+        unsafe {
+            OutputDebugStringW(&s_utf16[0]);
+        }
+    }
+}
+
+#[cfg(windows)]
+extern "system" {
+    fn OutputDebugStringW(chars: *const u16);
+}
+
+pub fn init() {
+    //! Set `WinDebugLogger` as the active logger<br>
+    //! Doesn't panic on failure as it creates other problems for FFI etc.
+    match log::set_logger(&WINDBG_LOGGER) {
+        Ok(()) => {}
+        Err(_) => {
+            dbg_win("Warning: ✗ Failed to register WinDebugLogger\n");
+        }
+    }
+}
diff --git a/src/gui/mod.rs b/src/gui/mod.rs
new file mode 100644
index 000000000..2817a3aa5
--- /dev/null
+++ b/src/gui/mod.rs
@@ -0,0 +1,18 @@
+pub mod win;
+pub use win::*;
+pub mod win_dbg_logger;
+pub mod win_nwg_ext;
+pub use win_dbg_logger as log_win;
+pub use win_dbg_logger::WINDBG_LOGGER;
+pub use win_nwg_ext::*;
+
+use crate::*;
+use parking_lot::Mutex;
+use std::sync::mpsc::Sender as ASender;
+use std::sync::{Arc, OnceLock};
+pub static CFG: OnceLock<Arc<Mutex<Kanata>>> = OnceLock::new();
+pub static GUI_TX: OnceLock<native_windows_gui::NoticeSender> = OnceLock::new();
+pub static GUI_CFG_TX: OnceLock<native_windows_gui::NoticeSender> = OnceLock::new();
+pub static GUI_ERR_TX: OnceLock<native_windows_gui::NoticeSender> = OnceLock::new();
+pub static GUI_ERR_MSG_TX: OnceLock<ASender<(String, String)>> = OnceLock::new();
+pub static GUI_EXIT_TX: OnceLock<native_windows_gui::NoticeSender> = OnceLock::new();
diff --git a/src/gui/win.rs b/src/gui/win.rs
new file mode 100644
index 000000000..31e404d93
--- /dev/null
+++ b/src/gui/win.rs
@@ -0,0 +1,1699 @@
+use crate::Kanata;
+use anyhow::{Result, bail};
+use core::cell::RefCell;
+use kanata_parser::cfg::CfgOptionsGui;
+use log::Level::*;
+use std::cell::Cell;
+use winapi::shared::windef::HWND;
+
+use core::ffi::c_void;
+use native_windows_gui as nwg;
+use parking_lot::Mutex;
+use parking_lot::MutexGuard;
+
+use std::collections::HashMap;
+use std::env::{current_exe, var_os};
+use std::ffi::OsStr;
+use std::iter::once;
+use std::os::windows::ffi::OsStrExt;
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
+use std::sync::mpsc::{Receiver, Sender as ASender, TryRecvError};
+use std::time::Duration;
+use winapi::shared::minwindef::{BYTE, DWORD};
+use winapi::shared::windef::COLORREF;
+use windows_sys::Wdk::System::SystemServices::RtlGetVersion;
+use windows_sys::Win32::Foundation::{ERROR_FILE_NOT_FOUND, ERROR_SUCCESS, POINT, RECT, SIZE};
+use windows_sys::Win32::System::Registry::{HKEY_CURRENT_USER, RRF_RT_REG_DWORD, RegGetValueW};
+use windows_sys::Win32::System::SystemInformation::OSVERSIONINFOW;
+use windows_sys::Win32::UI::HiDpi::GetSystemMetricsForDpi;
+use windows_sys::Win32::UI::WindowsAndMessaging::{
+    CalculatePopupWindowPosition, SM_CXCURSOR, SM_CYCURSOR, TPM_WORKAREA,
+};
+
+use crate::gui::win_nwg_ext::{BitmapEx, MenuEx, MenuItemEx};
+use kanata_parser::cfg;
+use nwg::{ControlHandle, NativeUi};
+use std::sync::Arc;
+
+trait PathExt {
+    fn add_ext(&mut self, ext_o: impl AsRef<std::path::Path>);
+}
+impl PathExt for PathBuf {
+    fn add_ext(&mut self, ext_o: impl AsRef<std::path::Path>) {
+        match self.extension() {
+            Some(ext) => {
+                let mut ext = ext.to_os_string();
+                ext.push(".");
+                ext.push(ext_o.as_ref());
+                self.set_extension(ext)
+            }
+            None => self.set_extension(ext_o.as_ref()),
+        };
+    }
+}
+
+#[derive(Default, Debug, Clone)]
+pub struct SystemTrayData {
+    pub tooltip: String,
+    pub cfg_p: Vec<PathBuf>,
+    pub cfg_icon: Option<String>,
+    pub layer0_name: String,
+    pub layer0_icon: Option<String>,
+    pub gui_opts: CfgOptionsGui,
+    pub tt_duration_pre: u16,
+    pub tt_size_pre: (u16, u16),
+}
+#[derive(Default)]
+pub struct Icn {
+    pub tray: nwg::Bitmap, // uses an image of different size to fit the menu items
+    pub tooltip: nwg::Bitmap, // uses an image of different size to fit the tooltip
+    pub icon: nwg::Icon,
+}
+#[derive(Default)]
+pub struct SystemTray {
+    pub app_data: RefCell<SystemTrayData>,
+    /// Store dynamically created tray menu items
+    pub tray_item_dyn: RefCell<Vec<nwg::MenuItem>>,
+    /// Store dynamically created tray menu items' handlers
+    pub handlers_dyn: RefCell<Vec<nwg::EventHandler>>,
+    /// Store dynamically created icons to not load them from a file every time
+    /// (icon format for tray icon, bitmap for tray MenuItem icons and tooltips)
+    pub img_dyn: RefCell<HashMap<PathBuf, Option<Icn>>>,
+    /// Store 'img_dyn' hashmap key for the currently active icon ('cfg_path:🗍layer_name' format)
+    pub icon_act_key: RefCell<Option<PathBuf>>,
+    /// Store 'img_dyn' hashmap key for the first deflayer to allow skipping it in tooltips
+    pub icon_0_key: RefCell<Option<PathBuf>>,
+    /// Store embedded-in-the-binary resources like icons not to load them from a file
+    pub embed: nwg::EmbedResource,
+    pub icon: nwg::Icon,
+    decoder: nwg::ImageDecoder,
+    pub window: nwg::MessageWindow,
+    /// A tooltip-like (no title/resize/focus/taskbar/clickthru) window to show notifications
+    /// (e.g., layer change messages)
+    pub win_tt: nwg::Window,
+    win_tt_ifr: nwg::ImageFrame,
+    win_tt_timer: nwg::AnimationTimer,
+    pub layer_notice: nwg::Notice,
+    pub cfg_notice: nwg::Notice,
+    pub err_notice: nwg::Notice,
+    pub exit_notice: nwg::Notice,
+    pub tt_notice: nwg::Notice,
+    /// Receiver of error message content sent from other threads
+    /// (e.g., from key event thread via WinDbgLogger that will also notify our GUI
+    /// (but not pass data) after sending data to this receiver)
+    pub err_recv: Option<Receiver<(String, String)>>,
+    pub tt2m_channel: Option<(ASender<bool>, Receiver<bool>)>,
+    // receiver will be created before a thread is spawned and moved there
+    pub m2tt_sender: RefCell<Option<ASender<bool>>>,
+    pub m_ptr_wh: RefCell<(u32, u32)>,
+    pub tray: nwg::TrayNotification,
+    pub tray_menu: nwg::Menu,
+    pub tray_1cfg_m: nwg::Menu,
+    pub tray_2reload: nwg::MenuItem,
+    pub tray_3exit: nwg::MenuItem,
+    pub img_reload: nwg::Bitmap,
+    pub img_exit: nwg::Bitmap,
+}
+pub fn get_appdata() -> Option<PathBuf> {
+    var_os("APPDATA").map(PathBuf::from)
+}
+pub fn get_user_home() -> Option<PathBuf> {
+    var_os("USERPROFILE").map(PathBuf::from)
+}
+pub fn get_xdg_home() -> Option<PathBuf> {
+    var_os("XDG_CONFIG_HOME").map(PathBuf::from)
+}
+
+const CFG_FD: [&str; 3] = ["", "kanata", "kanata-tray"]; // blank "" allow checking directly for
+// user passed values
+const ASSET_FD: [&str; 4] = ["", "icon", "img", "icons"];
+const IMG_EXT: [&str; 7] = ["ico", "jpg", "jpeg", "png", "bmp", "dds", "tiff"];
+const PRE_LAYER: &str = "\n🗍: "; // : invalid path marker, so should be safe to use as a separator
+const TTTIMER_L: u16 = 9; // lifetime delta to duration for a tooltip timer
+use crate::gui::{CFG, GUI_CFG_TX, GUI_ERR_MSG_TX, GUI_ERR_TX, GUI_EXIT_TX, GUI_TX};
+
+pub fn send_gui_notice() {
+    if let Some(gui_tx) = GUI_TX.get() {
+        gui_tx.notice();
+    } else {
+        error!("no GUI_TX to notify GUI thread of layer changes");
+    }
+}
+pub fn send_gui_cfg_notice() {
+    if let Some(gui_tx) = GUI_CFG_TX.get() {
+        gui_tx.notice();
+    } else {
+        error!("no GUI_CFG_TX to notify GUI thread of layer changes");
+    }
+}
+pub fn send_gui_err_notice() {
+    if let Some(gui_tx) = GUI_ERR_TX.get() {
+        gui_tx.notice();
+    } else {
+        error!("no GUI_ERR_TX to notify GUI thread of errors");
+    }
+}
+pub fn send_gui_exit_notice() {
+    if let Some(gui_tx) = GUI_EXIT_TX.get() {
+        gui_tx.notice();
+    } else {
+        error!("no GUI_EXIT_TX to ask GUI thread to exit");
+    }
+}
+pub fn show_err_msg_nofail(title: String, msg: String) {
+    // log gets insalized before gui, so some errors might have no target to log to, ignore them
+    if let Some(gui_msg_tx) = GUI_ERR_MSG_TX.get() {
+        if gui_msg_tx.send((title, msg)).is_err() {
+            warn!("send_gui_err_msg_notice failed to use OS notifications")
+        } else {
+            // can't Error to avoid an ∞ error loop ↑
+            if let Some(gui_tx) = GUI_ERR_TX.get() {
+                gui_tx.notice();
+            }
+        }
+    }
+}
+
+/// Find an icon file that matches a given config icon name for a layer `lyr_icn` or a layer name
+/// `lyr_nm` (if `match_name` is `true`) or a given config icon name for the whole config `cfg_p`
+/// or a config file name at various locations (where config file is, where executable is,
+/// in user config folders)
+fn get_icon_p<S1, S2, S3, P>(
+    lyr_icn: S1,
+    lyr_nm: S2,
+    cfg_icn: S3,
+    cfg_p: P,
+    match_name: &bool,
+) -> Option<String>
+where
+    S1: AsRef<str>,
+    S2: AsRef<str>,
+    S3: AsRef<str>,
+    P: AsRef<Path>,
+{
+    get_icon_p_impl(
+        lyr_icn.as_ref(),
+        lyr_nm.as_ref(),
+        cfg_icn.as_ref(),
+        cfg_p.as_ref(),
+        match_name,
+    )
+}
+
+fn get_icon_p_impl(
+    lyr_icn: &str,
+    lyr_nm: &str,
+    cfg_icn: &str,
+    p: &Path,
+    match_name: &bool,
+) -> Option<String> {
+    trace!(
+        "lyr_icn={lyr_icn} lyr_nm={lyr_nm} cfg_icn={cfg_icn} cfg_p={p:?} match_name={match_name}"
+    );
+    let mut icon_file = PathBuf::new();
+    let blank_p = Path::new("");
+    let lyr_icn_p = Path::new(&lyr_icn);
+    let lyr_nm_p = Path::new(&lyr_nm);
+    let cfg_icn_p = Path::new(&cfg_icn);
+    let cfg_stem = &p.file_stem().unwrap_or_else(|| OsStr::new(""));
+    let cfg_name = &p.file_name().unwrap_or_else(|| OsStr::new(""));
+    let f_name = [
+        lyr_icn_p.as_os_str(),
+        if *match_name {
+            lyr_nm_p.as_os_str()
+        } else {
+            OsStr::new("")
+        },
+        cfg_icn_p.as_os_str(),
+        cfg_stem,
+        cfg_name,
+    ]
+    .into_iter();
+    let f_ext = [
+        lyr_icn_p.extension(),
+        if *match_name {
+            lyr_nm_p.extension()
+        } else {
+            None
+        },
+        cfg_icn_p.extension(),
+        None,
+        None,
+    ];
+    let pre_p = p.parent().unwrap_or_else(|| Path::new(""));
+    let cur_exe = current_exe().unwrap_or_else(|_| PathBuf::new());
+    let xdg_cfg = get_xdg_home().unwrap_or_default();
+    let app_data = get_appdata().unwrap_or_default();
+    let mut user_cfg = get_user_home().unwrap_or_default();
+    user_cfg.push(".config");
+    let parents = [
+        Path::new(""),
+        pre_p,
+        &cur_exe,
+        &xdg_cfg,
+        &app_data,
+        &user_cfg,
+    ]; // empty path to allow no prefixes when icon path is explictily set in case it's a full
+    // path already
+
+    for (i, nm) in f_name.enumerate() {
+        trace!("{}nm={:?}", "", nm);
+        if nm.is_empty() {
+            trace!("no file name to test, skip");
+            continue;
+        }
+        let mut is_full_p = false;
+        if nm == lyr_icn_p {
+            is_full_p = true
+        }; // user configs can have full paths, so test them even if all parent folders are emtpy
+        if nm == cfg_icn_p {
+            is_full_p = true
+        };
+        let icn_ext = &f_ext[i]
+            .unwrap_or_else(|| OsStr::new(""))
+            .to_string_lossy()
+            .to_string();
+        let is_icn_ext_valid = if f_ext[i].is_some() {
+            if IMG_EXT.iter().any(|&i| i == icn_ext) {
+                trace!("icn_ext={:?}", icn_ext);
+                true
+            } else {
+                warn!(
+                    "user icon extension \"{}\" might be invalid (or just not an extension)!",
+                    icn_ext
+                );
+                false
+            }
+        } else {
+            false
+        };
+        'p: for p_par in parents {
+            trace!("{}p_par={:?}", "  ", p_par);
+            if p_par == blank_p && !is_full_p {
+                trace!("blank parent for non-user, skip");
+                continue;
+            }
+            for p_kan in CFG_FD {
+                trace!("{}p_kan={:?}", "    ", p_kan);
+                for p_icn in ASSET_FD {
+                    trace!("{}p_icn={:?}", "      ", p_icn);
+                    for ext in IMG_EXT {
+                        trace!("{}  ext={:?}", "        ", ext);
+                        if p_par != blank_p {
+                            icon_file.push(p_par);
+                        } // folders
+                        if !p_kan.is_empty() {
+                            icon_file.push(p_kan);
+                        }
+                        if !p_icn.is_empty() {
+                            icon_file.push(p_icn);
+                        }
+                        if !nm.is_empty() {
+                            icon_file.push(nm);
+                        }
+                        if !is_full_p {
+                            icon_file.set_extension(ext); // no icon name passed, iterate extensions
+                        } else if !is_icn_ext_valid {
+                            icon_file.add_ext(ext);
+                        } else {
+                            trace!("skip ext");
+                        } // replace invalid icon extension
+                        trace!("testing icon file {:?}", icon_file);
+                        if !icon_file.is_file() {
+                            icon_file.clear();
+                            if p_par == blank_p && p_kan.is_empty() && p_icn.is_empty() && is_full_p
+                            {
+                                trace!(
+                                    "skipping further sub-iters on an empty parent with user config {:?}",
+                                    nm
+                                );
+                                continue 'p;
+                            }
+                        } else {
+                            debug!("✓ found icon file: {}", icon_file.display().to_string());
+                            return Some(icon_file.display().to_string());
+                        }
+                    }
+                }
+            }
+        }
+    }
+    debug!("✗ no icon file found");
+    None
+}
+
+pub const ICN_SZ_MENU: [u32; 2] = [24, 24]; // size for menu icons
+pub const ICN_SZ_TT: [u32; 2] = [36, 36]; // size for tooltip icons
+pub const ICN_SZ_MENU_I: [i32; 2] = [24, 24]; // for the builder, which needs i32
+pub const ICN_SZ_TT_I: [i32; 2] = [36, 36]; // for the builder, which needs i32
+
+macro_rules! win_ver {
+    () => {{
+        static WIN_VER: OnceLock<(u32, u32, u32)> = OnceLock::new();
+        *WIN_VER.get_or_init(|| {
+            let os_ver_i: *mut OSVERSIONINFOW = &mut OSVERSIONINFOW {
+                dwOSVersionInfoSize: 0, //u32
+                dwMajorVersion: 0,      //u32
+                dwMinorVersion: 0,      //u32
+                dwBuildNumber: 0,       //u32
+                dwPlatformId: 0,        //u32
+                szCSDVersion: [0; 128], //[u16; 128]
+            };
+            unsafe {
+                if 0 == RtlGetVersion(os_ver_i) {
+                    return (
+                        (*os_ver_i).dwMajorVersion,
+                        (*os_ver_i).dwMinorVersion,
+                        (*os_ver_i).dwBuildNumber,
+                    );
+                }
+            }
+            (0, 0, 0)
+        })
+    }};
+}
+/// Convert string to wide array and append null
+pub fn to_wide_str(s: &str) -> Vec<u16> {
+    OsStr::new(s).encode_wide().chain(once(0)).collect()
+}
+macro_rules! mouse_scale_factor {
+    // screen size = dpi⋅size⋅scaleF
+    () => {{
+        //TODO: track changes by subscribing via RegNotifyChangeKeyValue and reset value
+        static MOUSE_PTR_SCALE_F: OnceLock<u32> = OnceLock::new();
+        *MOUSE_PTR_SCALE_F.get_or_init(|| {
+            // 3. pointer scale factor @ Settings/Ease of Access/Mouse pointer
+            let key_root = HKEY_CURRENT_USER;
+            let key_path_s = r"SOFTWARE\Microsoft\Accessibility";
+            let key_name_s = "CursorSize";
+            let key_path = to_wide_str(key_path_s);
+            let key_name = to_wide_str(key_name_s);
+            let mut mouse_scale: DWORD = 0;
+            let mouse_scale_p: *mut c_void = &mut mouse_scale as *mut u32 as *mut std::ffi::c_void;
+            let mut mouse_scale_sz: DWORD = std::mem::size_of::<DWORD>() as DWORD;
+            let res = unsafe {
+                RegGetValueW(
+                    key_root,
+                    key_path.as_ptr(),
+                    key_name.as_ptr(),
+                    RRF_RT_REG_DWORD,     //restrict type to REG_DWORD
+                    std::ptr::null_mut(), //pdwType
+                    mouse_scale_p,
+                    &mut mouse_scale_sz,
+                )
+            };
+            match res as DWORD {
+                ERROR_SUCCESS => {}
+                ERROR_FILE_NOT_FOUND => {
+                    log::error!(r"Registry '{}\{}' not found", key_path_s, key_name_s);
+                    mouse_scale = 1;
+                }
+                _ => {
+                    log::error!(
+                        r"Registry '{}\{}' couldn't be read as DWORD {}",
+                        key_path_s,
+                        key_name_s,
+                        res
+                    );
+                    mouse_scale = 1;
+                }
+            }
+            mouse_scale
+        })
+    }};
+}
+pub fn get_mouse_ptr_size(dpi_scale: bool) -> (u32, u32) {
+    // 1. get monitor DPI
+    let dpi = if dpi_scale { unsafe { nwg::dpi() } } else { 96 };
+    // 2. icon size @ dpi
+    let cur_w = SM_CXCURSOR;
+    let cur_h = SM_CYCURSOR;
+    let width = unsafe { GetSystemMetricsForDpi(cur_w, dpi as u32) } as u32;
+    let height = unsafe { GetSystemMetricsForDpi(cur_h, dpi as u32) } as u32;
+    let mouse_scale = mouse_scale_factor!();
+    (mouse_scale * width, mouse_scale * height)
+}
+
+// stores old mouse pointer position to avoid refreshing tooltips if mouse doesn't move
+thread_local! {static MXY:Cell<(i32,i32)> = Cell::default();}
+impl SystemTray {
+    /// Read an image from a file, convert it to various formats: tray, tooltip, icon
+    fn get_icon_from_file<P>(&self, ico_p: P) -> Result<Icn>
+    where
+        P: AsRef<str>,
+    {
+        self.get_icon_from_file_impl(ico_p.as_ref())
+    }
+    fn get_icon_from_file_impl(&self, ico_p: &str) -> Result<Icn> {
+        let app_data = self.app_data.borrow();
+        let icn_sz_tt = [
+            app_data.gui_opts.tooltip_size.0 as u32,
+            app_data.gui_opts.tooltip_size.1 as u32,
+        ];
+        if let Ok(img_data) = self
+            .decoder
+            .from_filename(ico_p)
+            .and_then(|img_src| img_src.frame(0))
+        {
+            if let Ok(cfg_img_menu) = self.decoder.resize_image(&img_data, ICN_SZ_MENU) {
+                let cfg_icon_bmp_tray = cfg_img_menu.as_bitmap()?;
+                let cfg_icon_bmp_icon = cfg_icon_bmp_tray.copy_as_icon();
+                if let Ok(cfg_img_menu) = self.decoder.resize_image(&img_data, icn_sz_tt) {
+                    let cfg_icon_bmp_tt = cfg_img_menu.as_bitmap()?;
+                    return Ok(Icn {
+                        tray: cfg_icon_bmp_tray,
+                        tooltip: cfg_icon_bmp_tt,
+                        icon: cfg_icon_bmp_icon,
+                    });
+                } else {
+                    debug!("✓ main ✗ icon resize Tray for {:?}", ico_p);
+                }
+            } else {
+                debug!("✓ main ✗ icon resize TTip for {:?}", ico_p);
+            }
+        } else {
+            debug!("✗ main 0 icon ✓ icon path for {:?}", ico_p);
+        }
+        bail!("✗ couldn't get a valid icon at {:?}", ico_p)
+    }
+    /// Read an image from a file, convert it to a menu-sized icon,
+    /// assign to a menu and return the image in various formats (tray, tooltip, icon)
+    fn set_menu_item_cfg_icon(
+        &self,
+        menu_item: &mut nwg::MenuItem,
+        cfg_icon_s: &str,
+        cfg_p: &PathBuf,
+    ) -> Result<Icn> {
+        if let Some(ico_p) = get_icon_p("", "", cfg_icon_s, cfg_p, &false)
+            && let Ok(icn) = self.get_icon_from_file(ico_p)
+        {
+            menu_item.set_bitmap(Some(&icn.tray));
+            return Ok(icn);
+        } else if get_icon_p("", "", cfg_icon_s, cfg_p, &false).is_some() {
+            debug!(
+                "✗ main 0 icon ✓ icon path, will be using DEFAULT icon for {:?}",
+                cfg_p
+            );
+        }
+        menu_item.set_bitmap(None);
+        bail!("✗couldn't get a valid icon for {:?}", cfg_p)
+    }
+    /// Move tooltip to the current mouse pointer position
+    fn update_tooltip_pos(&self) {
+        let app_data = self.app_data.borrow();
+        let mut x = 0;
+        let mut y = 0;
+        let mut is_same = false;
+        MXY.with(|mxy| {
+            (x, y) = nwg::GlobalCursor::position();
+            let (mx, my) = mxy.get();
+            if mx == x && my == y {
+                is_same = true;
+                return;
+            }
+            mxy.set((x, y));
+        });
+        if is_same {
+            return;
+        };
+        let win_ver = win_ver!();
+        // image width/height to take it into account when calculating overlaps
+        let w = app_data.gui_opts.tooltip_size.0 as i32;
+        let h = app_data.gui_opts.tooltip_size.1 as i32;
+        let flags = if (win_ver.0 >= 6 && win_ver.1 >= 1) || win_ver.0 > 6 {
+            TPM_WORKAREA
+        } else {
+            0
+        };
+        // 🖰 pointer size to make sure tooltip doesn't overlap,
+        // don't adjust for dpi in internal calculations
+        // tooltip offset vs. 🖰 pointer by 25% its size
+        let (mouse_ptr_w, mouse_ptr_h) = *self.m_ptr_wh.borrow();
+        let tt_off_x = (mouse_ptr_w as f64 * 0.25).round() as i32;
+        let tt_off_y = (mouse_ptr_h as f64 * 0.25).round() as i32; //
+        let (mouse_ptr_w, mouse_ptr_h) = (mouse_ptr_w as i32, mouse_ptr_h as i32);
+        let anchorpoint = &POINT {
+            x: x + tt_off_x,
+            y: y + tt_off_y,
+        };
+        let tt_win_sz = &SIZE { cx: w, cy: h };
+        let excluderect = &RECT {
+            left: x.saturating_sub(mouse_ptr_w),
+            right: x.saturating_add(mouse_ptr_w), // assuming ~top-left hotspot
+            top: y.saturating_sub(mouse_ptr_h),
+            bottom: y.saturating_add(mouse_ptr_h),
+        }; //Avoid ~ mouse pointer area
+        let out_rect = &mut RECT {
+            left: 0,
+            right: 0,
+            top: 0,
+            bottom: 0,
+        };
+        let ret = unsafe {
+            CalculatePopupWindowPosition(anchorpoint, tt_win_sz, flags, excluderect, out_rect)
+        };
+        if ret != 0 {
+            x = out_rect.left;
+            y = out_rect.top;
+        }
+        let dpi = unsafe { nwg::dpi() };
+        let xx = (x as f64 / (dpi as f64 / 96_f64)).round() as i32; // adjust dpi for layout
+        let yy = (y as f64 / (dpi as f64 / 96_f64)).round() as i32;
+        self.win_tt.set_position(xx, yy);
+        // TODO: somehow still shown a bit too far off from the pointer
+        if log_enabled!(Trace) {
+            let (mx, my) = MXY.get();
+            trace!(
+                "🖰 @{mx}⋅{my} ↔{mouse_ptr_w}↕{mouse_ptr_h} (upd={}) {x}⋅{y} @ dpi={dpi} → {xx}⋅{yy} {win_ver:?} flags={flags} ex←{}→{}↑{}↓{}",
+                ret != 0,
+                excluderect.left,
+                excluderect.right,
+                excluderect.top,
+                excluderect.bottom
+            );
+        }
+    }
+    /// Spawn a thread with a new 🖰 pointer watcher
+    /// (that sends a signal back to GUI which in turn moves the tooltip to the new position)
+    fn update_mouse_watcher(&self, tt2m_sndr: ASender<bool>, ticks: u16, poll_time: Duration) {
+        debug!("   ✓   update_mouse_watcher");
+        let gui_tx = self.tt_notice.sender(); // allows notifying GUI on tooltip move updates
+        let (m2tt_sndr0, m2tt_rcvr) = std::sync::mpsc::channel::<bool>();
+        {
+            let mut m2tt_sender = self.m2tt_sender.borrow_mut();
+            *m2tt_sender = Some(m2tt_sndr0.clone());
+        }
+        let _handler = std::thread::spawn(move || -> Result<()> {
+            debug!("  ✓ Starting polling for a 🖰 pointer position");
+            let mut i = 0;
+            while i <= ticks {
+                i += 1;
+                std::thread::sleep(poll_time);
+                match m2tt_rcvr.try_recv() {
+                    Ok(_) => {
+                        debug!("extending tooltip watcher instead of launching +1");
+                        i = 0;
+                    }
+                    Err(TryRecvError::Empty) => {
+                        trace!("send signal to reposition");
+                        gui_tx.notice();
+                    }
+                    Err(TryRecvError::Disconnected) => {
+                        debug!("internal: m2tt_sender disconnected, no more 🖰 pointer tracking");
+                        break;
+                    }
+                }
+            }
+            debug!("  ✗ Stopped polling for a 🖰 pointer position");
+            tt2m_sndr.send(true)?;
+            Ok(())
+        });
+    }
+    /// Show our tooltip-like notification window
+    fn show_tooltip(&self, img: Option<&nwg::Bitmap>) {
+        let app_data = self.app_data.borrow();
+        if !app_data.gui_opts.tooltip_layer_changes {
+            return;
+        };
+        if img.is_none() && !app_data.gui_opts.tooltip_show_blank {
+            self.win_tt.set_visible(false);
+            return;
+        };
+        static IS_INIT: OnceLock<bool> = OnceLock::new();
+        if IS_INIT.get().is_none() {
+            // layered win needs a special call after being initialized to appear
+            let _ = IS_INIT.set(true);
+            debug!("win_tt hasn't been shown as a layered window");
+            let win_id = self
+                .win_tt
+                .handle
+                .hwnd()
+                .expect("win_tt should be a valid/existing window!");
+            show_layered_win(win_id);
+        } else {
+            debug!("win_tt has been shown as a layered window");
+        }
+        self.win_tt_ifr.set_bitmap(img);
+        {
+            let mut m_ptr_wh = self.m_ptr_wh.borrow_mut();
+            *m_ptr_wh = get_mouse_ptr_size(false);
+        } // 🖰 pointer size so tooltip doesn't overlap
+        // don't adjust for dpi in internal calculations
+        self.update_tooltip_pos();
+        self.win_tt.set_visible(true);
+        if app_data.gui_opts.tooltip_duration != 0 {
+            self.win_tt_timer.start()
+        };
+
+        if let Some((tt2m_sndr, tt2m_rcvr)) = &self.tt2m_channel {
+            let mut start = false;
+            match tt2m_rcvr.try_recv() {
+                Ok(_) => {
+                    debug!("launch a new thread");
+                    start = true;
+                }
+                Err(TryRecvError::Empty) => {
+                    if let Some(m2tt_sender) = self.m2tt_sender.borrow().as_ref() {
+                        trace!("send signal to extend");
+                        m2tt_sender.send(true).unwrap_or_else(|_| {
+                            error!("internal: couldn't send a signal to the 🖰 pointer watcher!")
+                        });
+                    } else {
+                        debug!(
+                            "no message and no m2tt_sender_o, so no thread should be running, launch a new thread!"
+                        );
+                        start = true;
+                    }
+                }
+                Err(TryRecvError::Disconnected) => {
+                    error!("internal: tt2m_channel disconnected, no more 🖰 pointer tracking")
+                }
+            }
+            let duration = 16;
+            let poll_time = Duration::from_millis(duration);
+            let ticks =
+                (app_data.gui_opts.tooltip_duration as f64 / duration as f64).round() as u16;
+            debug!(
+                "will tick for {ticks} every {duration} ms to match user {}",
+                app_data.gui_opts.tooltip_duration
+            );
+            if start {
+                self.update_mouse_watcher(tt2m_sndr.clone(), ticks, poll_time);
+            }
+        } else {
+            error!("internal: m2tt_sender doesn't exist can't track 🖰 pointer without it!");
+        }
+    }
+    /// Hide our tooltip-like notification window
+    fn hide_tooltip(&self) {
+        self.win_tt.set_visible(false)
+    }
+    fn show_menu(&self) {
+        self.update_tray_icon_cfg_group(false);
+        let (x, y) = nwg::GlobalCursor::position();
+        self.tray_menu.popup(x, y);
+    }
+    /// Add a ✓ (or highlight the icon) to the currently active config.
+    /// Runs on opening of the list of configs menu
+    fn update_tray_icon_cfg(
+        &self,
+        menu_item_cfg: &mut nwg::MenuItem,
+        cfg_p: &PathBuf,
+        is_active: bool,
+    ) -> Result<()> {
+        let mut img_dyn = self.img_dyn.borrow_mut();
+        if img_dyn.contains_key(cfg_p) {
+            // check if menu group icon needs to be updated to match active
+            if is_active
+                && let Some(icn) = img_dyn.get(cfg_p).and_then(|maybe_icn| maybe_icn.as_ref())
+            {
+                self.tray_1cfg_m.set_bitmap(Some(&icn.tray))
+            }
+        } else {
+            trace!("config menu item icon missing, read config and add it (or nothing) {cfg_p:?}");
+            if let Ok(cfg) = cfg::new_from_file(cfg_p)
+                && let Some(cfg_icon_s) = cfg.options.gui_opts.tray_icon
+            {
+                debug!("loaded config without a tray icon {cfg_p:?}");
+                if let Ok(icn) = self.set_menu_item_cfg_icon(menu_item_cfg, &cfg_icon_s, cfg_p) {
+                    if is_active {
+                        self.tray_1cfg_m.set_bitmap(Some(&icn.tray));
+                    }
+                    // update currently active config's icon in the combo menu
+                    debug!("✓set icon {cfg_p:?}");
+                    let _ = img_dyn.insert(cfg_p.clone(), Some(icn));
+                } else {
+                    bail!("✗couldn't get a valid icon")
+                }
+            } else {
+                bail!("✗icon not configured")
+            }
+        }
+        Ok(())
+    }
+    fn update_tray_icon_cfg_group(&self, force: bool) {
+        if let Some(cfg) = CFG.get() {
+            if let Some(k) = cfg.try_lock() {
+                let idx_cfg = k.cur_cfg_idx;
+                let mut tray_item_dyn = self.tray_item_dyn.borrow_mut();
+                let h_cfg_i = &mut tray_item_dyn[idx_cfg];
+                let is_check = h_cfg_i.checked();
+                if !is_check || force {
+                    let cfg_p = &k.cfg_paths[idx_cfg];
+                    debug!(
+                        "✗ mismatch idx_cfg={idx_cfg:?} {} {:?} cfg_p={cfg_p:?}",
+                        if is_check { "✓" } else { "✗" },
+                        h_cfg_i.handle
+                    );
+                    h_cfg_i.set_checked(true);
+                    if let Err(e) = self.update_tray_icon_cfg(h_cfg_i, cfg_p, true) {
+                        debug!("{e:?} {cfg_p:?}");
+                        let mut img_dyn = self.img_dyn.borrow_mut();
+                        img_dyn.insert(cfg_p.clone(), None);
+                        self.tray_1cfg_m.set_bitmap(None); // can't update menu, so remove combo
+                        // menu icon
+                    };
+                } else {
+                    debug!("gui cfg selection matches active config");
+                };
+            } else {
+                debug!(
+                    "✗ kanata config is locked, can't get current config (likely the gui changed the layer and is still holding the lock, it will update the icon)"
+                );
+            }
+        };
+    }
+    fn check_active(&self) {
+        if let Some(cfg) = CFG.get() {
+            let k = cfg.lock();
+            let idx_cfg = k.cur_cfg_idx;
+            let mut tray_item_dyn = self.tray_item_dyn.borrow_mut();
+            for (i, h_cfg_i) in tray_item_dyn.iter_mut().enumerate() {
+                // 1 if missing an icon, read config to get one
+                let cfg_p = &k.cfg_paths[i];
+                trace!("     →→→→ i={i:?} {:?} cfg_p={cfg_p:?}", h_cfg_i.handle);
+                let is_active = i == idx_cfg;
+                if let Err(e) = self.update_tray_icon_cfg(h_cfg_i, cfg_p, is_active) {
+                    debug!("{e:?} {cfg_p:?}");
+                    let mut img_dyn = self.img_dyn.borrow_mut();
+                    img_dyn.insert(cfg_p.clone(), None);
+                    if is_active {
+                        self.tray_1cfg_m.set_bitmap(None);
+                    } // update currently active config's icon in the combo menu
+                };
+                // 2 if wrong GUI checkmark, correct it
+                if h_cfg_i.checked() && !is_active {
+                    debug!("uncheck i{} act{}", i, idx_cfg);
+                    h_cfg_i.set_checked(false);
+                }
+                if !h_cfg_i.checked() && is_active {
+                    debug!("  check i{} act{}", i, idx_cfg);
+                    h_cfg_i.set_checked(true);
+                }
+            }
+        } else {
+            error!("no CFG var that contains active kanata config");
+        };
+    }
+    /// Check if tooltip data is changed, and update tooltip window size / timer duration
+    fn update_tooltip_data(&self, k: &Kanata) -> bool {
+        let mut app_data = self.app_data.borrow_mut();
+        let mut clear = false;
+        if app_data.tt_duration_pre != k.gui_opts.tooltip_duration {
+            app_data.gui_opts.tooltip_duration = k.gui_opts.tooltip_duration;
+            clear = true;
+            app_data.tt_duration_pre = k.gui_opts.tooltip_duration;
+            trace!("timer duration changed, updating");
+            self.win_tt_timer.set_interval(Duration::from_millis(
+                (k.gui_opts.tooltip_duration.saturating_add(1)).into(),
+            ));
+            self.win_tt_timer.set_lifetime(Some(Duration::from_millis(
+                (k.gui_opts.tooltip_duration.saturating_add(TTTIMER_L)).into(),
+            )));
+        }
+        if !(app_data.tt_size_pre.0 == k.gui_opts.tooltip_size.0
+            && app_data.tt_size_pre.1 == k.gui_opts.tooltip_size.1)
+        {
+            app_data.tt_size_pre = k.gui_opts.tooltip_size;
+            clear = true;
+            app_data.gui_opts.tooltip_size = k.gui_opts.tooltip_size;
+            trace!("tooltip_size duration changed, updating");
+            let dpi = unsafe { nwg::dpi() };
+            let icn_sz_tt_i = (k.gui_opts.tooltip_size.0, k.gui_opts.tooltip_size.1);
+            let w = (icn_sz_tt_i.0 as f64 / (dpi as f64 / 96_f64)).round() as u32;
+            let h = (icn_sz_tt_i.1 as f64 / (dpi as f64 / 96_f64)).round() as u32;
+            self.win_tt.set_size(w, h);
+
+            let icn_sz_tt_i = (
+                k.gui_opts.tooltip_size.0 as u32,
+                k.gui_opts.tooltip_size.1 as u32,
+            );
+            // todo: replace with a no-margin NWG config when it's available
+            let padx = (k.gui_opts.tooltip_size.0 as f64 / 6_f64).round() as i32;
+            let pady = (k.gui_opts.tooltip_size.1 as f64 / 6_f64).round() as i32;
+            trace!(
+                "kanata tooltip size = {icn_sz_tt_i:?}, ttsize = {w}⋅{h} offset = {padx}⋅{pady}"
+            );
+            self.win_tt_ifr.set_size(icn_sz_tt_i.0, icn_sz_tt_i.1);
+            self.win_tt_ifr.set_position(-padx, -pady);
+        }
+        clear
+    }
+    /// Reload config file, currently active (`i=None`) or matching a given `i` index
+    fn reload_cfg(&self, i: Option<usize>) -> Result<()> {
+        use nwg::TrayNotificationFlags as f_tray;
+        let mut msg_title = "".to_string();
+        let mut msg_content = "".to_string();
+        let mut flags = f_tray::empty();
+        if let Some(cfg) = CFG.get() {
+            let mut k = cfg.lock();
+            let paths = &k.cfg_paths;
+            let idx_cfg = match i {
+                Some(idx) => {
+                    if idx < paths.len() {
+                        idx
+                    } else {
+                        error!(
+                            "Invalid config index {} while kanata has only {} configs loaded",
+                            idx + 1,
+                            paths.len()
+                        );
+                        k.cur_cfg_idx
+                    }
+                }
+                None => k.cur_cfg_idx,
+            };
+            let path_cur = &paths[idx_cfg];
+            let path_cur_s = path_cur.display().to_string();
+            let path_cur_cc = path_cur.clone();
+            msg_content += &path_cur_s;
+            let cfg_name = &path_cur
+                .file_name()
+                .unwrap_or_else(|| OsStr::new(""))
+                .to_string_lossy()
+                .to_string();
+            if log_enabled!(Debug) {
+                let cfg_icon = &k.gui_opts.tray_icon;
+                let cfg_icon_s = cfg_icon.clone().unwrap_or("✗".to_string());
+                let layer_id = k.layout.b().current_layer();
+                let layer_name = &k.layer_info[layer_id].name;
+                let layer_icon = &k.layer_info[layer_id].icon;
+                let layer_icon_s = layer_icon.clone().unwrap_or("✗".to_string());
+                debug!(
+                    "pre reload tray_icon={} layer_name={} layer_icon={}",
+                    cfg_icon_s, layer_name, layer_icon_s
+                );
+            }
+            match i {
+                Some(idx) => {
+                    if let Ok(()) = k.live_reload_n(idx) {
+                        msg_title += &("🔄 \"".to_owned() + cfg_name + "\" loaded");
+                        flags |= f_tray::USER_ICON;
+                    } else {
+                        msg_title += &("🔄 \"".to_owned() + cfg_name + "\" NOT loaded");
+                        flags |= f_tray::ERROR_ICON | f_tray::LARGE_ICON;
+                        {
+                            let app_data = self.app_data.borrow();
+                            if app_data.gui_opts.notify_cfg_reload_silent {
+                                flags |= f_tray::SILENT;
+                            }
+                        }
+                        self.tray.show(
+                            &msg_content,
+                            Some(&msg_title),
+                            Some(flags),
+                            Some(&self.icon),
+                        );
+                        bail!("{msg_content}");
+                    }
+                }
+                None => {
+                    if let Ok(()) = k.live_reload() {
+                        msg_title += &("🔄 \"".to_owned() + cfg_name + "\" reloaded");
+                        flags |= f_tray::USER_ICON;
+                    } else {
+                        msg_title += &("🔄 \"".to_owned() + cfg_name + "\" NOT reloaded");
+                        flags |= f_tray::ERROR_ICON | f_tray::LARGE_ICON;
+                        {
+                            let app_data = self.app_data.borrow();
+                            if app_data.gui_opts.notify_cfg_reload_silent {
+                                flags |= f_tray::SILENT;
+                            }
+                        }
+                        self.tray.show(
+                            &msg_content,
+                            Some(&msg_title),
+                            Some(flags),
+                            Some(&self.icon),
+                        );
+                        bail!("{msg_content}");
+                    }
+                }
+            };
+            let cfg_icon = &k.gui_opts.tray_icon;
+            let layer_id = k.layout.b().current_layer();
+            let layer_name = &k.layer_info[layer_id].name;
+            let layer_icon = &k.layer_info[layer_id].icon;
+            let mut cfg_layer_pkey = PathBuf::new(); // path key
+            cfg_layer_pkey.push(path_cur_cc.clone());
+            cfg_layer_pkey.push(PRE_LAYER.to_owned() + layer_name); //:invalid path marker,
+            // so should be safe to use as
+            // a separator
+            let cfg_layer_pkey_s = cfg_layer_pkey.display().to_string();
+            if log_enabled!(Debug) {
+                let layer_icon_s = layer_icon.clone().unwrap_or("✗".to_string());
+                debug!(
+                    "pos reload tray_icon={:?} layer_name={:?} layer_icon={:?}",
+                    cfg_icon, layer_name, layer_icon_s
+                );
+            }
+
+            let _ = self.update_tooltip_data(&k); // check for changes before they're overwritten ↓
+            {
+                *self.app_data.borrow_mut() = update_app_data(&k)?;
+            }
+            self.tray.set_tip(&cfg_layer_pkey_s); // update tooltip to point to the newer config
+            let clear = i.is_none();
+            self.update_tray_icon(
+                cfg_layer_pkey,
+                &cfg_layer_pkey_s,
+                layer_name,
+                layer_icon,
+                path_cur_cc,
+                clear,
+            )
+        } else {
+            msg_title += "✗ Config NOT reloaded, no CFG";
+            warn!("{}", msg_title);
+            flags |= f_tray::ERROR_ICON;
+        };
+        flags |= f_tray::LARGE_ICON; // todo: fails without this, must have SM_CXICON x SM_CYICON?
+        {
+            let app_data = self.app_data.borrow();
+            if app_data.gui_opts.notify_cfg_reload_silent {
+                flags |= f_tray::SILENT;
+            }
+        }
+        self.tray.show(
+            &msg_content,
+            Some(&msg_title),
+            Some(flags),
+            Some(&self.icon),
+        );
+        Ok(())
+    }
+    fn reload_layer_icon(&self) {
+        let _ = self.reload_cfg_or_layer_icon(false);
+    }
+    /// Show OS notification message with an error coming from WinDbgLogger
+    fn notify_error(&self) {
+        let app_data = self.app_data.borrow();
+        if !app_data.gui_opts.notify_error {
+            return;
+        };
+        use nwg::TrayNotificationFlags as f_tray;
+        let mut msg_title = "".to_string();
+        let mut msg_content = "".to_string();
+        let mut flags = f_tray::empty();
+        if let Some(gui_msg_rx) = &self.err_recv {
+            match gui_msg_rx.try_recv() {
+                Ok((title, msg)) => {
+                    msg_title += &title;
+                    msg_content += &msg;
+                }
+                Err(TryRecvError::Empty) => {
+                    msg_title += "internal";
+                    msg_content += "channel to receive errors is Empty";
+                }
+                Err(TryRecvError::Disconnected) => {
+                    msg_title += "internal";
+                    msg_content += "channel to receive errors is Disconnected";
+                }
+            }
+        } else {
+            msg_title += "internal";
+            msg_content += "SystemTray is supposed to have a valid 'err_recv' field value"
+        }
+        flags |= f_tray::ERROR_ICON;
+        if app_data.gui_opts.notify_cfg_reload_silent {
+            flags |= f_tray::SILENT;
+        }
+        let msg_title = strip_ansi_escapes::strip_str(&msg_title);
+        let msg_content = strip_ansi_escapes::strip_str(&msg_content);
+        self.tray.show(
+            &msg_content,
+            Some(&msg_title),
+            Some(flags),
+            Some(&self.icon),
+        );
+    }
+    /// Update tray icon data on config reload
+    fn reload_cfg_icon(&self) {
+        let _ = self.reload_cfg_or_layer_icon(true);
+    }
+    /// Update tray icon data on layer change (and config reload)
+    fn reload_cfg_or_layer_icon(&self, is_cfg: bool) -> Result<()> {
+        if let Some(cfg) = CFG.get() {
+            if let Some(k) = cfg.try_lock() {
+                let paths = &k.cfg_paths;
+                let idx_cfg = k.cur_cfg_idx;
+                let path_cur = &paths[idx_cfg];
+                let path_cur_cc = path_cur.clone();
+                let cfg_icon = &k.gui_opts.tray_icon;
+                let layer_id = k.layout.b().current_layer();
+                let layer_name = &k.layer_info[layer_id].name;
+                let layer_icon = &k.layer_info[layer_id].icon;
+
+                let mut cfg_layer_pkey = PathBuf::new(); // path key
+                cfg_layer_pkey.push(path_cur_cc.clone());
+                cfg_layer_pkey.push(PRE_LAYER.to_owned() + layer_name); //:invalid path marker,
+                // so should be safe
+                // to use as a separator
+                let cfg_layer_pkey_s = cfg_layer_pkey.display().to_string();
+                if log_enabled!(Debug) {
+                    let cfg_name = &path_cur
+                        .file_name()
+                        .unwrap_or_else(|| OsStr::new(""))
+                        .to_string_lossy()
+                        .to_string();
+                    let cfg_icon_s = layer_icon.clone().unwrap_or("✗".to_string());
+                    let layer_icon_s = cfg_icon.clone().unwrap_or("✗".to_string());
+                    debug!(
+                        "✓ layer changed to ‘{}’ with icon ‘{}’ @ ‘{}’ tray_icon ‘{}’",
+                        layer_name, layer_icon_s, cfg_name, cfg_icon_s
+                    );
+                }
+
+                let clear = self.update_tooltip_data(&k);
+                if is_cfg {
+                    *self.app_data.borrow_mut() = update_app_data(&k)?;
+                }
+                if is_cfg {
+                    let app_data = self.app_data.borrow();
+                    if app_data.gui_opts.notify_cfg_reload {
+                        use nwg::TrayNotificationFlags as f_tray;
+                        let cfg_name = &path_cur
+                            .file_name()
+                            .unwrap_or_else(|| OsStr::new(""))
+                            .to_string_lossy()
+                            .to_string();
+                        let msg_title = "🔄 \"".to_owned() + cfg_name + "\" re-loaded";
+                        let msg_content = &path_cur.display().to_string();
+                        let mut flags = f_tray::empty() | f_tray::USER_ICON | f_tray::LARGE_ICON;
+                        if app_data.gui_opts.notify_cfg_reload_silent {
+                            flags |= f_tray::SILENT;
+                        }
+                        self.tray.show(
+                            msg_content,
+                            Some(&msg_title),
+                            Some(flags),
+                            Some(&self.icon),
+                        );
+                    }
+                }
+                self.tray.set_tip(&cfg_layer_pkey_s);
+                self.update_tray_icon(
+                    cfg_layer_pkey,
+                    &cfg_layer_pkey_s,
+                    layer_name,
+                    layer_icon,
+                    path_cur_cc,
+                    clear,
+                )
+            } else {
+                debug!(
+                    "✗ kanata config is locked, can't get current layer (likely the gui changed the layer and is still holding the lock, it will update the icon)"
+                );
+            }
+        } else {
+            warn!("✗ Layer indicator NOT changed, no CFG");
+        };
+        Ok(())
+    }
+    /// Update tray icon data given various config/layer info
+    /// * `cfg_layer_pkey` - "path␤🗍: layer_name" unique icon id
+    /// * `path_cur_cc` - "path" without the layer name
+    /// * `clear` - reset stored icon cached paths/files
+    fn update_tray_icon(
+        &self,
+        cfg_layer_pkey: PathBuf,
+        cfg_layer_pkey_s: &str,
+        layer_name: &str,
+        layer_icon: &Option<String>,
+        path_cur_cc: PathBuf,
+        clear: bool,
+    ) {
+        let mut img_dyn = self.img_dyn.borrow_mut(); // update the tray icons
+        let mut icon_act_key = self.icon_act_key.borrow_mut(); // update the tray icon active path
+        let mut icon_0_key = self.icon_0_key.borrow_mut(); // update the tray tooltip layer0 path
+        if clear {
+            *img_dyn = Default::default();
+            *icon_act_key = Default::default();
+            *icon_0_key = Some(cfg_layer_pkey.clone());
+            debug!("reloading active config, clearing img_dyn/_active cache");
+        }
+        let app_data = self.app_data.borrow();
+        let skip_tt = app_data.gui_opts.tooltip_no_base
+            && icon_0_key
+                .as_ref()
+                .filter(|p| **p == cfg_layer_pkey)
+                .is_some();
+        if icon_0_key.is_none() {
+            warn!("internal bug?: icon_0_key should never be empty?")
+        }
+        if let Some(icn_opt) = img_dyn.get(&cfg_layer_pkey) {
+            // 1a config+layer path has already been checked
+            if let Some(icn) = icn_opt {
+                self.tray.set_icon(&icn.icon);
+                *icon_act_key = Some(cfg_layer_pkey);
+                if !skip_tt {
+                    self.show_tooltip(Some(&icn.tooltip));
+                }
+            } else {
+                info!(
+                    "no icon found, using default for config+layer = {}",
+                    cfg_layer_pkey_s
+                );
+                self.tray.set_icon(&self.icon);
+                *icon_act_key = Some(cfg_layer_pkey);
+                self.show_tooltip(None);
+            }
+        } else if layer_icon.is_some() || app_data.gui_opts.icon_match_layer_name {
+            let layer_icon = match layer_icon {
+                Some(layer_icon_inner) => {
+                    trace!("configured layer icon = {}", layer_icon_inner);
+                    layer_icon_inner
+                }
+                None => {
+                    trace!(
+                        "no configured layer icon, checking its name = {}",
+                        layer_name
+                    );
+                    layer_name
+                }
+            };
+            // 1b cfg+layer path hasn't been checked, but layer has an icon configured...
+            // or configured to check its name, so check it
+            if let Some(ico_p) = get_icon_p(
+                layer_icon,
+                layer_name,
+                "",
+                &path_cur_cc,
+                &app_data.gui_opts.icon_match_layer_name,
+            ) {
+                if let Ok(icn) = self.get_icon_from_file(ico_p) {
+                    info!(
+                        "✓ Using an icon from this config+layer: {}",
+                        cfg_layer_pkey_s
+                    );
+                    self.tray.set_icon(&icn.icon);
+                    if !skip_tt {
+                        self.show_tooltip(Some(&icn.tooltip));
+                    }
+                    let _ = img_dyn.insert(cfg_layer_pkey.clone(), Some(icn));
+                    *icon_act_key = Some(cfg_layer_pkey);
+                } else {
+                    warn!(
+                        "✗ Invalid icon file \"{layer_icon}\" from this config+layer: {}",
+                        cfg_layer_pkey_s
+                    );
+                    let _ = img_dyn.insert(cfg_layer_pkey.clone(), None);
+                    self.tray.set_icon(&self.icon);
+                    *icon_act_key = Some(cfg_layer_pkey);
+                    self.show_tooltip(None);
+                }
+            } else {
+                warn!(
+                    "✗ Invalid icon path \"{layer_icon}\" from this config+layer: {}",
+                    cfg_layer_pkey_s
+                );
+                let _ = img_dyn.insert(cfg_layer_pkey.clone(), None);
+                self.tray.set_icon(&self.icon);
+                *icon_act_key = Some(cfg_layer_pkey);
+                self.show_tooltip(None);
+            }
+        } else if img_dyn.contains_key(&path_cur_cc) {
+            // 2a no layer icon configured, but config icon exists, use it
+            if let Some(icn) = img_dyn.get(&path_cur_cc).unwrap() {
+                self.tray.set_icon(&icn.icon);
+                *icon_act_key = Some(path_cur_cc);
+                self.show_tooltip(None);
+            } else {
+                info!(
+                    "no icon found, using default for config: {}",
+                    path_cur_cc.display().to_string()
+                );
+                self.tray.set_icon(&self.icon);
+                *icon_act_key = Some(path_cur_cc);
+                self.show_tooltip(None);
+            }
+        } else {
+            // 2b no layer icon configured, no config icon, use config path
+            let cfg_icon_p = if let Some(cfg_icon) = &app_data.cfg_icon {
+                cfg_icon
+            } else {
+                ""
+            };
+            if let Some(ico_p) = get_icon_p(
+                "",
+                layer_name,
+                cfg_icon_p,
+                &path_cur_cc,
+                &app_data.gui_opts.icon_match_layer_name,
+            ) {
+                if let Ok(icn) = self.get_icon_from_file(ico_p) {
+                    info!(
+                        "✓ Using an icon from this config: {}",
+                        path_cur_cc.display().to_string()
+                    );
+                    self.tray.set_icon(&icn.icon);
+                    if !skip_tt {
+                        self.show_tooltip(Some(&icn.tooltip));
+                    }
+                    let _ = img_dyn.insert(cfg_layer_pkey.clone(), Some(icn));
+                    *icon_act_key = Some(cfg_layer_pkey);
+                } else {
+                    warn!(
+                        "✗ Invalid icon file \"{cfg_icon_p}\" from this config: {}",
+                        cfg_layer_pkey.display().to_string()
+                    );
+                    let _ = img_dyn.insert(cfg_layer_pkey.clone(), None);
+                    *icon_act_key = Some(cfg_layer_pkey);
+                    self.tray.set_icon(&self.icon);
+                    self.show_tooltip(None);
+                }
+            } else {
+                warn!(
+                    "✗ Invalid icon path \"{cfg_icon_p}\" from this config: {}",
+                    cfg_layer_pkey.display().to_string()
+                );
+                let _ = img_dyn.insert(cfg_layer_pkey.clone(), None);
+                *icon_act_key = Some(cfg_layer_pkey);
+                self.tray.set_icon(&self.icon);
+                self.show_tooltip(None);
+            }
+        }
+    }
+    fn exit(&self) {
+        let handlers = self.handlers_dyn.borrow();
+        for handler in handlers.iter() {
+            nwg::unbind_event_handler(handler);
+        }
+        nwg::stop_thread_dispatch();
+    }
+
+    fn build_win_tt(&self) -> Result<nwg::Window, nwg::NwgError> {
+        let f_style = wf::POPUP;
+        let f_ex = WS_CLICK_THRU
+       | WS_EX_NOACTIVATE   //0x8000000L top-level win doesn't become foreground win on user click
+       | WS_EX_TOOLWINDOW   // remove from the taskbar (floating toolbar)
+       ;
+
+        let mut window: nwg::Window = Default::default();
+        let dpi = unsafe { nwg::dpi() };
+        let app_data = self.app_data.borrow();
+        let icn_sz_tt_i = (
+            app_data.gui_opts.tooltip_size.0,
+            app_data.gui_opts.tooltip_size.1,
+        );
+        let w = (icn_sz_tt_i.0 as f64 / (dpi as f64 / 96_f64)).round() as i32;
+        let h = (icn_sz_tt_i.1 as f64 / (dpi as f64 / 96_f64)).round() as i32;
+        trace!("Active Kanata Layer win size = {w}⋅{h}");
+        nwg::Window::builder()
+            .title("Active Kanata Layer")
+            .size((w, h))
+            .position((0, 0))
+            .center(false)
+            .topmost(true)
+            .maximized(false)
+            .minimized(false)
+            .flags(f_style)
+            .ex_flags(f_ex)
+            .icon(None)
+            .accept_files(false)
+            .build(&mut window)?;
+        Ok(window)
+    }
+}
+
+pub mod system_tray_ui {
+    use super::*;
+    use native_windows_gui::{self as nwg, MousePressEvent};
+    use std::cell::RefCell;
+    use std::ops::Deref;
+    use std::rc::Rc;
+    use windows_sys::Win32::UI::Shell::SIID_DELETE;
+
+    pub struct SystemTrayUi {
+        inner: Rc<SystemTray>,
+        handler_def: RefCell<Vec<nwg::EventHandler>>,
+    }
+
+    impl nwg::NativeUi<SystemTrayUi> for SystemTray {
+        fn build_ui(mut d: SystemTray) -> Result<SystemTrayUi, nwg::NwgError> {
+            use nwg::Event as E;
+
+            let app_data = d.app_data.borrow().clone();
+            d.tray_item_dyn = RefCell::new(Default::default());
+            d.handlers_dyn = RefCell::new(Default::default());
+            d.decoder = Default::default();
+            nwg::ImageDecoder::builder().build(&mut d.decoder)?;
+            // Resources
+            d.embed = Default::default();
+            d.embed = nwg::EmbedResource::load(None)?;
+            nwg::Icon::builder()
+                .source_embed(Some(&d.embed))
+                .source_embed_str(Some("iconMain"))
+                .strict(true) /*use sys, not panic, if missing*/
+                .build(&mut d.icon)?;
+
+            let (sndr, rcvr) = std::sync::mpsc::channel();
+            d.tt2m_channel = Some((sndr, rcvr));
+            let (sndr, rcvr) = std::sync::mpsc::channel();
+            d.err_recv = Some(rcvr);
+            if GUI_ERR_MSG_TX.set(sndr).is_err() {
+                warn!("Someone else set our ‘GUI_ERR_MSG_TX’");
+            };
+
+            // Controls
+            nwg::MessageWindow::builder().build(&mut d.window)?;
+            nwg::Notice::builder()
+                .parent(&d.window)
+                .build(&mut d.layer_notice)?;
+            nwg::Notice::builder()
+                .parent(&d.window)
+                .build(&mut d.cfg_notice)?;
+            nwg::Menu::builder()
+                .parent(&d.window)
+                .popup(true) /*context menu*/	//
+                .build(&mut d.tray_menu)?;
+            nwg::Notice::builder()
+                .parent(&d.window)
+                .build(&mut d.tt_notice)?;
+            nwg::Notice::builder()
+                .parent(&d.window)
+                .build(&mut d.err_notice)?;
+            nwg::Notice::builder()
+                .parent(&d.window)
+                .build(&mut d.exit_notice)?;
+            nwg::Menu::builder()
+                .parent(&d.tray_menu)
+                .text("&F Load config") //
+                .build(&mut d.tray_1cfg_m)?;
+            nwg::MenuItem::builder()
+                .parent(&d.tray_menu)
+                .text("&R Reload config") //
+                .build(&mut d.tray_2reload)?;
+            nwg::MenuItem::builder()
+                .parent(&d.tray_menu)
+                .text("&X Exit\t‹⎈␠⎋") //
+                .build(&mut d.tray_3exit)?;
+
+            if app_data.gui_opts.tooltip_layer_changes {
+                d.win_tt = d.build_win_tt().expect("Tooltip window");
+                nwg::AnimationTimer::builder()
+                    .parent(&d.window)
+                    .interval(Duration::from_millis(
+                        (app_data.gui_opts.tooltip_duration.saturating_add(1)).into(),
+                    ))
+                    .lifetime(Some(Duration::from_millis(
+                        (app_data.gui_opts.tooltip_duration + TTTIMER_L).into(),
+                    )))
+                    .max_tick(None)
+                    .active(false)
+                    .build(&mut d.win_tt_timer)?;
+
+                let icn_sz_tt_i = (
+                    app_data.gui_opts.tooltip_size.0 as i32,
+                    app_data.gui_opts.tooltip_size.1 as i32,
+                );
+                // todo: replace with a no-margin NWG config when it's available
+                let padx = (app_data.gui_opts.tooltip_size.0 as f64 / 6_f64).round() as i32;
+                let pady = (app_data.gui_opts.tooltip_size.1 as f64 / 6_f64).round() as i32;
+                let pad = (-padx, -pady);
+                trace!("kanata tooltip size = {icn_sz_tt_i:?}, offset = {padx}⋅{pady}");
+                let mut cfg_icon_bmp_tray = Default::default();
+                nwg::Bitmap::builder()
+                    .source_embed(Some(&d.embed))
+                    .source_embed_str(Some("imgMain"))
+                    .strict(true)
+                    .size(Some(ICN_SZ_MENU.into()))
+                    .build(&mut cfg_icon_bmp_tray)?;
+                nwg::ImageFrame::builder()
+                    .parent(&d.win_tt)
+                    .size(icn_sz_tt_i)
+                    .position(pad)
+                    .build(&mut d.win_tt_ifr)?;
+            }
+
+            let mut tmp_bitmap = Default::default();
+            nwg::Bitmap::builder()
+                .source_embed(Some(&d.embed))
+                .source_embed_str(Some("imgReload"))
+                .strict(true)
+                .size(Some(ICN_SZ_MENU.into()))
+                .build(&mut tmp_bitmap)?;
+            let img_exit = nwg::Bitmap::from_system_icon(SIID_DELETE);
+            d.tray_2reload.set_bitmap(Some(&tmp_bitmap));
+            d.tray_3exit.set_bitmap(Some(&img_exit));
+            d.img_reload = tmp_bitmap;
+            d.img_exit = img_exit;
+
+            let mut main_tray_icon_l = Default::default();
+            let mut main_tray_icon_is = false;
+            {
+                let mut tray_item_dyn = d.tray_item_dyn.borrow_mut();
+                let mut img_dyn = d.img_dyn.borrow_mut();
+                let mut icon_act_key = d.icon_act_key.borrow_mut();
+                let mut icon_0_key = d.icon_0_key.borrow_mut();
+                const MENU_ACC: &str = "1234567890ASDFGQWERTZXCVBYUIOPHJKLNM";
+                const M_E: usize = MENU_ACC.len() - 1;
+                let layer0_icon_s = &app_data.layer0_icon.clone().unwrap_or("".to_string());
+                let cfg_icon_s = &app_data.cfg_icon.clone().unwrap_or("".to_string());
+                if !(app_data.cfg_p).is_empty() {
+                    for (i, cfg_p) in app_data.cfg_p.iter().enumerate() {
+                        let i_acc = match i {
+                            // accelerators from 1–0, A–Z starting from home row for easier presses
+                            0..=M_E => format!("&{} ", &MENU_ACC[i..i + 1]),
+                            _ => "  ".to_string(),
+                        };
+                        let cfg_name = &cfg_p
+                            .file_name()
+                            .unwrap_or_else(|| OsStr::new(""))
+                            .to_string_lossy()
+                            .to_string(); //kanata.kbd
+                        let menu_text = format!("{cfg_name}\t{i_acc}"); // kanata.kbd &1
+                        let mut menu_item = Default::default();
+                        if i == 0 {
+                            nwg::MenuItem::builder()
+                                .parent(&d.tray_1cfg_m)
+                                .text(&menu_text)
+                                .check(true)
+                                .build(&mut menu_item)?;
+                        } else {
+                            nwg::MenuItem::builder()
+                                .parent(&d.tray_1cfg_m)
+                                .text(&menu_text)
+                                .build(&mut menu_item)?;
+                        }
+                        if i == 0 {
+                            // add icons if exists, hashed by config path
+                            // (for active config, others will create on load)
+                            if let Some(ico_p) = get_icon_p(
+                                layer0_icon_s,
+                                &app_data.layer0_name,
+                                cfg_icon_s,
+                                cfg_p,
+                                &app_data.gui_opts.icon_match_layer_name,
+                            ) {
+                                let mut cfg_layer_pkey = PathBuf::new(); // path key
+                                cfg_layer_pkey.push(cfg_p.clone());
+                                cfg_layer_pkey.push(PRE_LAYER.to_owned() + &app_data.layer0_name);
+                                let cfg_layer_pkey_s = cfg_layer_pkey.display().to_string();
+                                *icon_0_key = Some(cfg_layer_pkey.clone());
+                                if let Ok(icn) = d.get_icon_from_file(&ico_p) {
+                                    debug!("✓ main 0 config: using icon for {}", cfg_layer_pkey_s);
+                                    main_tray_icon_l = icn.tray.copy_as_icon();
+                                    main_tray_icon_is = true;
+                                    let _ = img_dyn.insert(cfg_layer_pkey, Some(icn));
+                                } else {
+                                    info!(
+                                        "✗ main 0 icon ✓ icon path, will be using DEFAULT icon for {:?}",
+                                        cfg_p
+                                    );
+                                    let _ = img_dyn.insert(cfg_layer_pkey, None);
+                                }
+                            } else {
+                                debug!("✗ main 0 config: using DEFAULT icon for {:?}", cfg_p);
+                                let mut cfg_icon_bmp_tray = Default::default();
+                                let mut cfg_icon_bmp_tt = Default::default();
+                                let mut cfg_icon_bmp_icon = Default::default();
+                                nwg::Bitmap::builder()
+                                    .source_embed(Some(&d.embed))
+                                    .source_embed_str(Some("imgMain"))
+                                    .strict(true)
+                                    .size(Some(ICN_SZ_MENU.into()))
+                                    .build(&mut cfg_icon_bmp_tray)?;
+                                nwg::Bitmap::builder()
+                                    .source_embed(Some(&d.embed))
+                                    .source_embed_str(Some("imgMain"))
+                                    .strict(true)
+                                    .size(Some(ICN_SZ_TT.into()))
+                                    .build(&mut cfg_icon_bmp_tt)?;
+                                nwg::Icon::builder()
+                                    .source_embed(Some(&d.embed))
+                                    .source_embed_str(Some("iconMain"))
+                                    .strict(true)
+                                    .build(&mut cfg_icon_bmp_icon)?;
+                                let _ = img_dyn.insert(
+                                    cfg_p.clone(),
+                                    Some(Icn {
+                                        tray: cfg_icon_bmp_tray,
+                                        tooltip: cfg_icon_bmp_tt,
+                                        icon: cfg_icon_bmp_icon,
+                                    }),
+                                );
+                                *icon_act_key = Some(cfg_p.clone());
+                            }
+                            // Set tray menu config item icons, ignores layers since these
+                            // are per config
+                            if let Ok(icn) =
+                                d.set_menu_item_cfg_icon(&mut menu_item, cfg_icon_s, cfg_p)
+                            {
+                                // show currently active config's icon in the combo menu
+                                d.tray_1cfg_m.set_bitmap(Some(&icn.tray));
+                                let _ = img_dyn.insert(cfg_p.clone(), Some(icn));
+                            } else {
+                                let _ = img_dyn.insert(cfg_p.clone(), None);
+                            }
+                        }
+                        tray_item_dyn.push(menu_item);
+                    }
+                } else {
+                    warn!("Didn't get any config paths from Kanata!")
+                }
+            }
+            let main_tray_icon = match main_tray_icon_is {
+                true => Some(&main_tray_icon_l),
+                false => Some(&d.icon),
+            };
+            nwg::TrayNotification::builder()
+                .parent(&d.window)
+                .icon(main_tray_icon)
+                .tip(Some(&app_data.tooltip))
+                .build(&mut d.tray)?;
+
+            let ui = SystemTrayUi {
+                // Wrap-up
+                inner: Rc::new(d),
+                handler_def: Default::default(),
+            };
+
+            let evt_ui = Rc::downgrade(&ui.inner); // Events
+            let handle_events = move |evt, _evt_data, handle| {
+                if let Some(evt_ui) = evt_ui.upgrade() {
+                    match evt {
+                        E::OnNotice =>
+                            if handle == evt_ui.layer_notice {
+                                SystemTray::reload_layer_icon(&evt_ui);
+                            } else if handle == evt_ui.cfg_notice {
+                                SystemTray::reload_cfg_icon(&evt_ui);
+                            } else if handle == evt_ui.err_notice {
+                                SystemTray::notify_error(&evt_ui);
+                            } else if handle == evt_ui.exit_notice {
+                                SystemTray::exit(&evt_ui);
+                            } else if handle == evt_ui.tt_notice {
+                                SystemTray::update_tooltip_pos(&evt_ui);}
+                        E::OnWindowClose if handle == evt_ui.window => {SystemTray::exit  (&evt_ui);}
+                        E::OnMousePress(MousePressEvent::MousePressLeftUp) if handle == evt_ui.tray => {SystemTray::show_menu(&evt_ui);}
+                        E::OnContextMenu/*🖰›*/ if handle == evt_ui.tray => {SystemTray::show_menu(&evt_ui);}
+                        E::OnTimerStop/*🕐*/ => {SystemTray::hide_tooltip(&evt_ui);}
+                        E::OnMenuHover if handle == evt_ui.tray_1cfg_m => {
+                                SystemTray::check_active(&evt_ui);
+                        }
+                        E::OnMenuItemSelected =>
+                            if        handle == evt_ui.tray_2reload   {
+                            let _ = SystemTray::reload_cfg(&evt_ui,None);
+                            SystemTray::update_tray_icon_cfg_group(&evt_ui,true);
+                        } else if handle == evt_ui.tray_3exit     {SystemTray::exit  (&evt_ui);
+                        } else if let
+                            ControlHandle::MenuItem(_parent, _id) = handle {
+                              {let tray_item_dyn    = &evt_ui.tray_item_dyn.borrow(); //
+                              for (i, h_cfg) in tray_item_dyn.iter().enumerate() {
+                                if &handle == h_cfg {
+                                    for h_cfg_j in tray_item_dyn.iter() {
+                                      if h_cfg_j.checked() {h_cfg_j.set_checked(false);} }
+                                      // uncheck others
+                                    h_cfg.set_checked(true); // check self
+                                  let _ = SystemTray::reload_cfg(&evt_ui,Some(i)); // depends
+                                }
+                              }
+                            }
+                          }
+                      _ => {}
+                    }
+                }
+            };
+            ui.handler_def
+                .borrow_mut()
+                .push(nwg::full_bind_event_handler(
+                    &ui.window.handle,
+                    handle_events,
+                ));
+            Ok(ui)
+        }
+    }
+
+    impl Drop for SystemTrayUi {
+        /// To make sure that everything is freed without issues, the default handler
+        /// must be unbound.
+        fn drop(&mut self) {
+            let mut handlers = self.handler_def.borrow_mut();
+            for handler in handlers.drain(0..) {
+                nwg::unbind_event_handler(&handler);
+            }
+        }
+    }
+    impl Deref for SystemTrayUi {
+        type Target = SystemTray;
+        fn deref(&self) -> &Self::Target {
+            &self.inner
+        }
+    }
+}
+use winapi::um::winuser::{
+    SetLayeredWindowAttributes, WS_EX_LAYERED, WS_EX_NOACTIVATE, WS_EX_TOOLWINDOW,
+    WS_EX_TRANSPARENT,
+};
+pub const WS_CLICK_THRU: u32 = WS_EX_LAYERED | WS_EX_TRANSPARENT;
+
+use nwg::WindowFlags as wf;
+/// Build a tooltip-like window to notify of user events
+fn show_layered_win(win_id: HWND) {
+    use winapi::um::wingdi::RGB;
+    use winapi::um::winuser::LWA_ALPHA;
+    let cr_key: COLORREF = RGB(0, 0, 0);
+    let b_alpha: BYTE = 255;
+    let dw_flags: DWORD = LWA_ALPHA;
+    unsafe {
+        SetLayeredWindowAttributes(win_id, cr_key, b_alpha, dw_flags);
+    } // layered window doesn't appear w/o this call
+}
+
+pub fn update_app_data(k: &MutexGuard<Kanata>) -> Result<SystemTrayData> {
+    let paths = &k.cfg_paths;
+    let path_cur = &paths[0];
+    let layer0_id = k.layout.b().current_layer();
+    let layer0_name = &k.layer_info[layer0_id].name;
+    let layer0_icon = &k.layer_info[layer0_id].icon;
+    Ok(SystemTrayData {
+        tooltip: path_cur.display().to_string(),
+        cfg_p: paths.clone(),
+        cfg_icon: k.gui_opts.tray_icon.clone(),
+        layer0_name: layer0_name.clone(),
+        layer0_icon: layer0_icon.clone(),
+        gui_opts: k.gui_opts.clone(),
+        tt_duration_pre: k.gui_opts.tooltip_duration,
+        tt_size_pre: k.gui_opts.tooltip_size,
+    })
+}
+pub fn build_tray(cfg: &Arc<Mutex<Kanata>>) -> Result<system_tray_ui::SystemTrayUi> {
+    let k = cfg.lock();
+    let app_data = update_app_data(&k)?;
+    let app = SystemTray {
+        app_data: RefCell::new(app_data),
+        ..Default::default()
+    };
+    Ok(SystemTray::build_ui(app)?)
+}
+
+pub use log::*;
+pub use std::io::{IsTerminal, stdout};
+pub use winapi::shared::minwindef::BOOL;
+pub use winapi::um::wincon::{ATTACH_PARENT_PROCESS, AttachConsole, FreeConsole};
+
+use once_cell::sync::Lazy;
+pub static IS_TERM: Lazy<bool> = Lazy::new(|| stdout().is_terminal());
+pub static IS_CONSOLE: Lazy<bool> =
+    Lazy::new(|| unsafe { AttachConsole(ATTACH_PARENT_PROCESS) != 0i32 });
diff --git a/src/gui/win_dbg_logger/mod.rs b/src/gui/win_dbg_logger/mod.rs
new file mode 100644
index 000000000..0117ccf9f
--- /dev/null
+++ b/src/gui/win_dbg_logger/mod.rs
@@ -0,0 +1,314 @@
+#![allow(non_upper_case_globals)]
+//! A logger for use with Windows debuggers.
+//!
+//! This crate integrates with the ubiquitous [`log`] crate and can be used with the [`simplelog`] crate.
+//!
+//! Windows allows applications to output a string directly to debuggers. This is very useful in
+//! situations where other forms of logging are not available.
+//! For example, stderr is not available for GUI apps.
+//!
+//! Windows provides the `OutputDebugString` entry point, which allows apps to print a debug string.
+//! Internally, `OutputDebugString` is implemented by raising an SEH exception, which the debugger
+//! catches and handles.
+//!
+//! Raising an exception has a significant cost, when run under a debugger, because the debugger
+//! halts all threads in the target process. So you should avoid using this logger for high rates
+//! of output, because doing so will slow down your app.
+//!
+//! Like many Windows entry points, `OutputDebugString` is actually two entry points:
+//! `OutputDebugStringA` (multi-byte encodings) and
+//! `OutputDebugStringW` (UTF-16). In most cases, the `*A` version is implemented using a "thunk"
+//! which converts its arguments to UTF-16 and then calls the `*W` version. However,
+//! `OutputDebugStringA` is one of the few entry points where the opposite is true.
+//!
+//! This crate can be compiled and used on non-Windows platforms, but it does nothing.
+//! This is intended to minimize the impact on code that takes a dependency on this crate.
+//!
+//! # Example
+//!
+//! ```rust
+//! use log::{debug, info};
+//!
+//! fn do_cool_stuff() {
+//!    info!("Hello, world!");
+//!    debug!("Hello, world, in detail!");
+//! }
+//!
+//! fn main() {
+//!     log::set_logger(&kanata_state_machine::gui::WINDBG_LOGGER).unwrap();
+//!     log::set_max_level(log::LevelFilter::Debug);
+//!
+//!     do_cool_stuff();
+//! }
+//! ```
+
+use log::{Level, LevelFilter, Metadata, Record};
+
+/// This implements `log::Log`, and so can be used as a logging provider.
+/// It forwards log messages to the Windows `OutputDebugString` API.
+#[derive(Copy, Clone)]
+pub struct WinDbgLogger {
+    level: LevelFilter,
+    /// Allow for `WinDbgLogger` to possibly have more fields in the future
+    _priv: (),
+}
+
+/// This is a static instance of `WinDbgLogger`. Since `WinDbgLogger` contains no state,
+/// this can be directly registered using `log::set_logger`, e.g.:
+///
+/// ```
+/// log::set_logger(&kanata_state_machine::gui::WINDBG_LOGGER).unwrap(); // Initialize
+/// log::set_max_level(log::LevelFilter::Debug);
+///
+/// use log::{info, debug}; // Import
+///
+/// info!("Hello, world!"); debug!("Hello, world, in detail!"); // Use to log
+/// ```
+pub static WINDBG_LOGGER: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Trace,
+    _priv: (),
+};
+pub static WINDBG_L1: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Error,
+    _priv: (),
+};
+pub static WINDBG_L2: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Warn,
+    _priv: (),
+};
+pub static WINDBG_L3: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Info,
+    _priv: (),
+};
+pub static WINDBG_L4: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Debug,
+    _priv: (),
+};
+pub static WINDBG_L5: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Trace,
+    _priv: (),
+};
+pub static WINDBG_L0: WinDbgLogger = WinDbgLogger {
+    level: LevelFilter::Off,
+    _priv: (),
+};
+
+#[cfg(all(target_os = "windows", feature = "gui"))]
+pub fn windbg_simple_combo(
+    log_lvl: LevelFilter,
+    noti_lvl: LevelFilter,
+) -> Box<dyn simplelog::SharedLogger> {
+    set_noti_lvl(noti_lvl);
+    match log_lvl {
+        LevelFilter::Error => Box::new(WINDBG_L1),
+        LevelFilter::Warn => Box::new(WINDBG_L2),
+        LevelFilter::Info => Box::new(WINDBG_L3),
+        LevelFilter::Debug => Box::new(WINDBG_L4),
+        LevelFilter::Trace => Box::new(WINDBG_L5),
+        LevelFilter::Off => Box::new(WINDBG_L0),
+    }
+}
+#[cfg(all(target_os = "windows", feature = "gui"))]
+impl simplelog::SharedLogger for WinDbgLogger {
+    // allows using with simplelog's CombinedLogger
+    fn level(&self) -> LevelFilter {
+        self.level
+    }
+    fn config(&self) -> Option<&simplelog::Config> {
+        None
+    }
+    fn as_log(self: Box<Self>) -> Box<dyn log::Log> {
+        Box::new(*self)
+    }
+}
+
+/// Convert logging levels to shorter and more visible icons
+pub fn iconify(lvl: log::Level) -> char {
+    match lvl {
+        Level::Error => '❗',
+        Level::Warn => '⚠',
+        Level::Info => 'ⓘ',
+        Level::Debug => 'ⓓ',
+        Level::Trace => 'ⓣ',
+    }
+}
+
+use std::sync::OnceLock;
+pub fn is_thread_state() -> &'static bool {
+    set_thread_state(false)
+}
+pub fn set_thread_state(is: bool) -> &'static bool {
+    // accessor function to avoid get_or_init on every call
+    // (lazycell allows doing that without an extra function)
+    static CELL: OnceLock<bool> = OnceLock::new();
+    CELL.get_or_init(|| is)
+}
+pub fn get_noti_lvl() -> &'static LevelFilter {
+    set_noti_lvl(LevelFilter::Off)
+}
+pub fn set_noti_lvl(lvl: LevelFilter) -> &'static LevelFilter {
+    static CELL: OnceLock<LevelFilter> = OnceLock::new();
+    CELL.get_or_init(|| lvl)
+}
+
+use regex::Regex;
+macro_rules! regex {
+    ($re:literal $(,)?) => {{
+        static RE: OnceLock<regex::Regex> = OnceLock::new();
+        RE.get_or_init(|| regex::Regex::new($re).unwrap())
+    }};
+}
+fn clean_name(path: Option<&str>) -> String {
+    let re_ext: &Regex = regex!(r"\..*$"); // shorten source file name, no src/ no .rs ext
+    let re_src: &Regex = regex!(r"src[\\/]");
+    // remove extension and src paths
+    if let Some(p) = path {
+        re_src.replace(&re_ext.replace(p, ""), "").to_string()
+    } else {
+        "?".to_string()
+    }
+}
+
+#[cfg(target_os = "windows")]
+use winapi::um::processthreadsapi::GetCurrentThreadId;
+impl log::Log for WinDbgLogger {
+    fn enabled(&self, metadata: &Metadata) -> bool {
+        metadata.level() <= self.level
+    }
+
+    fn log(&self, record: &Record) {
+        #[cfg(not(target_os = "windows"))]
+        let thread_id = "";
+        #[cfg(target_os = "windows")]
+        let thread_id = if *is_thread_state() {
+            format!("{}¦", unsafe { GetCurrentThreadId() })
+        } else {
+            "".to_string()
+        };
+        if self.enabled(record.metadata()) {
+            let s = format!(
+                "{}{}{}:{} {}",
+                thread_id,
+                iconify(record.level()),
+                clean_name(record.file()),
+                record.line().unwrap_or(0),
+                record.args()
+            );
+            #[cfg(all(target_os = "windows", feature = "gui"))]
+            {
+                use crate::gui::win::*;
+                let title = format!(
+                    "{}{}:{}",
+                    thread_id,
+                    clean_name(record.file()),
+                    record.line().unwrap_or(0)
+                );
+                let msg = format!("{}", record.args());
+                if record.level() <= *get_noti_lvl() {
+                    show_err_msg_nofail(title, msg);
+                }
+            }
+            output_debug_string(&s);
+        }
+    }
+
+    fn flush(&self) {}
+}
+
+/// Calls the `OutputDebugString` API to log a string.
+///
+/// On non-Windows platforms, this function does nothing.
+///
+/// See [`OutputDebugStringW`](https://docs.microsoft.com/en-us/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw).
+pub fn output_debug_string(s: &str) {
+    #[cfg(windows)]
+    {
+        let len = s.encode_utf16().count() + 1;
+        let mut s_utf16: Vec<u16> = Vec::with_capacity(len);
+        s_utf16.extend(s.encode_utf16());
+        s_utf16.push(0);
+        unsafe {
+            OutputDebugStringW(&s_utf16[0]);
+        }
+    }
+    #[cfg(not(windows))]
+    {
+        let _ = s;
+    }
+}
+
+#[cfg(windows)]
+unsafe extern "system" {
+    fn OutputDebugStringW(chars: *const u16);
+    fn IsDebuggerPresent() -> i32;
+}
+
+/// Checks whether a debugger is attached to the current process.
+///
+/// On non-Windows platforms, this function always returns `false`.
+///
+/// See [`IsDebuggerPresent`](https://docs.microsoft.com/en-us/windows/win32/api/debugapi/nf-debugapi-isdebuggerpresent).
+pub fn is_debugger_present() -> bool {
+    #[cfg(windows)]
+    {
+        unsafe { IsDebuggerPresent() != 0 }
+    }
+    #[cfg(not(windows))]
+    {
+        false
+    }
+}
+
+/// Sets the `WinDbgLogger` as the currently-active logger.
+///
+/// If an error occurs when registering `WinDbgLogger` as the current logger, this function will
+/// output a warning and will return normally. It will not panic.
+/// This behavior was chosen because `WinDbgLogger` is intended for use in debugging.
+/// Panicking would disrupt debugging and introduce new failure modes. It would also create
+/// problems for mixed-mode debugging, where Rust code is linked with C/C++ code.
+pub fn init() {
+    match log::set_logger(&WINDBG_LOGGER) {
+        Ok(()) => {} //↓ there's really nothing we can do about it.
+        Err(_) => {
+            output_debug_string(
+                "Warning: Failed to register WinDbgLogger as the current Rust logger.\r\n",
+            );
+        }
+    }
+}
+
+macro_rules! define_init_at_level {
+    ($func:ident, $level:ident) => {
+        /// This can be called from C/C++ code to register the debug logger.
+        ///
+        /// For Windows DLLs that have statically linked an instance of `win_dbg_logger` into
+        /// them, `DllMain` should call `win_dbg_logger_init_<level>()` from the `DLL_PROCESS_ATTACH`
+        /// handler, e.g.:
+        ///
+        /// ```ignore
+        /// extern "C" void __cdecl rust_win_dbg_logger_init_debug(); // Calls into Rust code
+        /// BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD reason, LPVOID reserved) {
+        ///   switch (reason) {
+        ///     case DLL_PROCESS_ATTACH:
+        ///       rust_win_dbg_logger_init_debug();
+        ///       // ...
+        ///   }
+        ///   // ...
+        /// }
+        /// ```
+        ///
+        /// For Windows executables that have statically linked an instance of `win_dbg_logger`
+        /// into them, call `win_dbg_logger_init_<level>()` during app startup.
+        #[unsafe(no_mangle)]
+        pub extern "C" fn $func() {
+            init();
+            log::set_max_level(LevelFilter::$level);
+        }
+    };
+}
+
+define_init_at_level!(rust_win_dbg_logger_init_trace, Trace);
+define_init_at_level!(rust_win_dbg_logger_init_info, Info);
+define_init_at_level!(rust_win_dbg_logger_init_debug, Debug);
+define_init_at_level!(rust_win_dbg_logger_init_warn, Warn);
+define_init_at_level!(rust_win_dbg_logger_init_error, Error);
diff --git a/src/gui/win_dbg_logger/win_dbg_logger.toml b/src/gui/win_dbg_logger/win_dbg_logger.toml
new file mode 100644
index 000000000..8e9533653
--- /dev/null
+++ b/src/gui/win_dbg_logger/win_dbg_logger.toml
@@ -0,0 +1,19 @@
+[package]
+name = "win_dbg_logger"
+version = "0.1.0"
+authors = ["Arlie Davis <ardavis@microsoft.com>"]
+edition = "2018"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/sivadeilra/win_dbg_logger"
+description = "A logger for use with Windows debuggers."
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log      	= "0.4.*"
+winapi   	= {version="0.3.9", features=["processthreadsapi",]}
+regex    	= {version="1.10.4"}
+simplelog	= {version="0.12.0", optional=true}
+
+[features]
+simple_shared	= ["simplelog"]
diff --git a/src/gui/win_nwg_ext/license-MIT b/src/gui/win_nwg_ext/license-MIT
new file mode 100644
index 000000000..a9d02d7ff
--- /dev/null
+++ b/src/gui/win_nwg_ext/license-MIT
@@ -0,0 +1,26 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2024` `Niccolò Betto`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
diff --git a/src/gui/win_nwg_ext/license-nwg-MIT b/src/gui/win_nwg_ext/license-nwg-MIT
new file mode 100644
index 000000000..c8c1643d5
--- /dev/null
+++ b/src/gui/win_nwg_ext/license-nwg-MIT
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Gabriel Dube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/src/gui/win_nwg_ext/mod.rs b/src/gui/win_nwg_ext/mod.rs
new file mode 100644
index 000000000..601e84327
--- /dev/null
+++ b/src/gui/win_nwg_ext/mod.rs
@@ -0,0 +1,246 @@
+// based on https://github.com/lynxnb/wsl-usb-manager/blob/master/src/gui/nwg_ext.rs
+use native_windows_gui as nwg;
+use native_windows_gui::ControlHandle;
+use std::{mem::size_of, ptr};
+use winapi::ctypes::c_int;
+use winapi::shared::windef::HWND;
+
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Graphics::Gdi::DeleteObject;
+use windows_sys::Win32::UI::Shell::{
+    SHGSI_ICON, SHGSI_SMALLICON, SHGetStockIconInfo, SHSTOCKICONID, SHSTOCKICONINFO,
+};
+use windows_sys::Win32::UI::WindowsAndMessaging::{
+    CopyImage, DestroyIcon, GetIconInfoExW, HMENU, ICONINFOEXW, IMAGE_BITMAP, LR_CREATEDIBSECTION,
+    MENUITEMINFOW, MF_BYCOMMAND, MIIM_BITMAP, SetMenuItemInfoW,
+};
+
+/// Extends [`nwg::Bitmap`] with additional functionality.
+pub trait BitmapEx {
+    fn from_system_icon(icon: SHSTOCKICONID) -> nwg::Bitmap;
+}
+
+impl BitmapEx for nwg::Bitmap {
+    /// Creates a bitmap from a [`SHSTOCKICONID`] system icon ID.
+    fn from_system_icon(icon: SHSTOCKICONID) -> nwg::Bitmap {
+        // Retrieve the icon
+        let mut stock_icon_info = SHSTOCKICONINFO {
+            cbSize: std::mem::size_of::<SHSTOCKICONINFO>() as u32,
+            hIcon: 0,
+            iSysImageIndex: 0,
+            iIcon: 0,
+            szPath: [0; 260],
+        };
+        unsafe {
+            SHGetStockIconInfo(
+                icon,
+                SHGSI_ICON | SHGSI_SMALLICON,
+                &mut stock_icon_info as *mut _,
+            );
+        }
+
+        // Retrieve the bitmap for the icon
+        let mut icon_info = ICONINFOEXW {
+            cbSize: std::mem::size_of::<ICONINFOEXW>() as u32,
+            fIcon: 0,
+            xHotspot: 0,
+            yHotspot: 0,
+            hbmMask: 0,
+            hbmColor: 0,
+            wResID: 0,
+            szModName: [0; 260],
+            szResName: [0; 260],
+        };
+        unsafe {
+            GetIconInfoExW(stock_icon_info.hIcon, &mut icon_info as *mut _);
+        }
+
+        // Create a copy of the bitmap with transparent background from the icon bitmap
+        let hbitmap = unsafe {
+            CopyImage(
+                icon_info.hbmColor as HANDLE,
+                IMAGE_BITMAP,
+                0,
+                0,
+                LR_CREATEDIBSECTION,
+            )
+        };
+
+        // Delete the unused icon and bitmaps
+        unsafe {
+            DeleteObject(icon_info.hbmMask);
+            DeleteObject(icon_info.hbmColor);
+            DestroyIcon(stock_icon_info.hIcon);
+        };
+
+        if hbitmap == 0 {
+            panic!("Failed to create bitmap from system icon");
+        } else {
+            #[allow(unused)]
+            struct Bitmap {
+                handle: HANDLE,
+                owned: bool,
+            }
+
+            let bitmap = Bitmap {
+                handle: hbitmap as HANDLE,
+                owned: true,
+            };
+
+            // Ugly hack to set the private `owned` field inside nwg::Bitmap to true
+            #[allow(clippy::missing_transmute_annotations)]
+            unsafe {
+                std::mem::transmute(bitmap)
+            }
+        }
+    }
+}
+
+/// Extends [`nwg::Menu`] with additional functionality.
+pub trait MenuEx {
+    fn set_bitmap(&self, bitmap: Option<&nwg::Bitmap>);
+}
+impl MenuEx for nwg::Menu {
+    /// Sets a bitmap to be displayed on a menu. Pass `None` to remove the bitmap
+    fn set_bitmap(&self, bitmap: Option<&nwg::Bitmap>) {
+        let (hmenu_par, hmenu) = self.handle.hmenu().unwrap();
+        let hbitmap = match bitmap {
+            Some(b) => b.handle as HANDLE,
+            None => 0,
+        };
+
+        let menu_item_info = MENUITEMINFOW {
+            cbSize: size_of::<MENUITEMINFOW>() as u32,
+            fMask: MIIM_BITMAP,
+            hbmpItem: hbitmap,
+            fType: 0,
+            fState: 0,
+            hSubMenu: 0,
+            hbmpChecked: 0,
+            hbmpUnchecked: 0,
+            dwTypeData: ptr::null_mut(),
+            wID: 0,
+            dwItemData: 0,
+            cch: 0,
+        };
+        unsafe {
+            SetMenuItemInfoW(
+                hmenu_par as HMENU,
+                hmenu as u32,
+                MF_BYCOMMAND as i32,
+                &menu_item_info as *const _,
+            );
+        }
+    }
+}
+
+/// Extends [`nwg::MenuItem`] with additional functionality.
+pub trait MenuItemEx {
+    fn set_bitmap(&self, bitmap: Option<&nwg::Bitmap>);
+}
+
+impl MenuItemEx for nwg::MenuItem {
+    /// Sets a bitmap to be displayed on a menu item. Pass `None` to remove the bitmap.
+    fn set_bitmap(&self, bitmap: Option<&nwg::Bitmap>) {
+        let (hmenu, item_id) = self.handle.hmenu_item().unwrap();
+        let hbitmap = match bitmap {
+            Some(b) => b.handle as HANDLE,
+            None => 0,
+        };
+
+        let menu_item_info = MENUITEMINFOW {
+            cbSize: std::mem::size_of::<MENUITEMINFOW>() as u32,
+            fMask: MIIM_BITMAP,
+            fType: 0,
+            fState: 0,
+            wID: 0,
+            hSubMenu: 0,
+            hbmpChecked: 0,
+            hbmpUnchecked: 0,
+            dwItemData: 0,
+            dwTypeData: std::ptr::null_mut(),
+            cch: 0,
+            hbmpItem: hbitmap,
+        };
+
+        unsafe {
+            SetMenuItemInfoW(
+                hmenu as HMENU,
+                item_id,
+                MF_BYCOMMAND as i32,
+                &menu_item_info as *const _,
+            );
+        }
+    }
+}
+
+pub trait WindowEx {
+    fn set_position_ex(&self, x: i32, y: i32);
+}
+pub fn dpi() -> i32 {
+    // prevents GDI DC resource leak
+    use winapi::um::wingdi::GetDeviceCaps;
+    use winapi::um::wingdi::LOGPIXELSX;
+    use winapi::um::winuser::{GetDC, ReleaseDC};
+    let screen = unsafe { GetDC(std::ptr::null_mut()) };
+    let dpi = unsafe { GetDeviceCaps(screen, LOGPIXELSX) };
+    let _ = unsafe { ReleaseDC(std::ptr::null_mut(), screen) };
+    dpi
+}
+pub fn logical_to_physical(x: i32, y: i32) -> (i32, i32) {
+    use muldiv::MulDiv;
+    use winapi::um::winuser::USER_DEFAULT_SCREEN_DPI;
+    let dpi = dpi();
+    let x = x.mul_div_round(dpi, USER_DEFAULT_SCREEN_DPI).unwrap_or(x);
+    let y = y.mul_div_round(dpi, USER_DEFAULT_SCREEN_DPI).unwrap_or(y);
+    (x, y)
+}
+/// # Safety
+/// The `handle` param must be a valid pointer to a window handle returned by some winapi call.
+/// Failure to do so probably won't be UB because the handle is passed to a WinAPI call
+/// which is expected to handle these cases safely, but seems worth noting anyway.
+pub unsafe fn set_window_position(handle: HWND, x: i32, y: i32) {
+    use winapi::um::winuser::SetWindowPos;
+    use winapi::um::winuser::{SWP_NOACTIVATE, SWP_NOOWNERZORDER, SWP_NOSIZE, SWP_NOZORDER};
+    let (x, y) = logical_to_physical(x, y);
+    unsafe {
+        SetWindowPos(
+            handle,
+            ptr::null_mut(),
+            x as c_int,
+            y as c_int,
+            0,
+            0,
+            SWP_NOZORDER | SWP_NOSIZE | SWP_NOACTIVATE | SWP_NOOWNERZORDER,
+        );
+    }
+}
+const NOT_BOUND: &str = "Window is not yet bound to a winapi object";
+const BAD_HANDLE: &str = "INTERNAL ERROR: Window handle is not HWND!";
+pub fn check_hwnd(handle: &ControlHandle, not_bound: &str, bad_handle: &str) -> HWND {
+    use winapi::um::winuser::IsWindow;
+    if handle.blank() {
+        panic!("{}", not_bound);
+    }
+    match handle.hwnd() {
+        Some(hwnd) => match unsafe { IsWindow(hwnd) } {
+            0 => {
+                panic!(
+                    "The window handle is no longer valid. This usually means the control was freed by the OS"
+                );
+            }
+            _ => hwnd,
+        },
+        None => {
+            panic!("{}", bad_handle);
+        }
+    }
+}
+
+impl WindowEx for nwg::Window {
+    /// Set the position of the button in the parent window
+    fn set_position_ex(&self, x: i32, y: i32) {
+        let handle = check_hwnd(&self.handle, NOT_BOUND, BAD_HANDLE);
+        unsafe { set_window_position(handle, x, y) }
+    }
+}
diff --git a/src/kanata.exe.manifest.rc b/src/kanata.exe.manifest.rc
new file mode 100644
index 000000000..73c6e7898
--- /dev/null
+++ b/src/kanata.exe.manifest.rc
@@ -0,0 +1,5 @@
+#define RT_MANIFEST 24
+1 RT_MANIFEST "./target/kanata.exe.manifest"
+iconMain ICON "../assets/kanata.ico"
+imgMain IMAGE "../assets/kanata.ico"
+imgReload IMAGE "../assets/reload_32px.png"
diff --git a/src/kanata/caps_word.rs b/src/kanata/caps_word.rs
index 329364535..c20a2f3b9 100644
--- a/src/kanata/caps_word.rs
+++ b/src/kanata/caps_word.rs
@@ -14,7 +14,7 @@ pub struct CapsWordState {
     /// The configured timeout for caps_word.
     pub timeout: u16,
     /// The number of ticks remaining for caps_word, after which its state should be cleared. The
-    /// number of ticks gets reset back to `timeout` when `maybe_add_lsft` is called. The reason
+    /// number of ticks gets reset back to `timeout` when `tick_maybe_add_lsft` is called. The reason
     /// for having this timeout at all is in case somebody was in the middle of typing a word, had
     /// to go do something, and forgot that caps_word was active. Having this timeout means that
     /// shift won't be active for their next keypress.
@@ -39,8 +39,12 @@ impl CapsWordState {
         }
     }
 
-    pub(crate) fn maybe_add_lsft(&mut self, active_keys: &mut Vec<KeyCode>) -> CapsWordNextState {
+    pub(crate) fn tick_maybe_add_lsft(
+        &mut self,
+        active_keys: &mut Vec<KeyCode>,
+    ) -> CapsWordNextState {
         if self.timeout_ticks == 0 {
+            log::trace!("caps-word ended");
             return End;
         }
         for kc in active_keys.iter() {
diff --git a/src/kanata/cfg_forced.rs b/src/kanata/cfg_forced.rs
new file mode 100644
index 000000000..b7b9422d5
--- /dev/null
+++ b/src/kanata/cfg_forced.rs
@@ -0,0 +1,19 @@
+//! Options in the configuration file that are overidden/forced to some value other than what's in
+//! the configuration file, with the primary example being CLI arguments.
+
+use std::sync::OnceLock;
+
+static LOG_LAYER_CHANGES: OnceLock<bool> = OnceLock::new();
+
+/// Force the log_layer_changes configuration to some value.
+/// This can only be called up to once. Panics if called a second time.
+pub fn force_log_layer_changes(v: bool) {
+    LOG_LAYER_CHANGES
+        .set(v)
+        .expect("force cfg fns can only be called once");
+}
+
+/// Get the forced log_layer_changes configuration if it was set.
+pub fn get_forced_log_layer_changes() -> Option<bool> {
+    LOG_LAYER_CHANGES.get().copied()
+}
diff --git a/src/kanata/clipboard.rs b/src/kanata/clipboard.rs
new file mode 100644
index 000000000..5b08274e3
--- /dev/null
+++ b/src/kanata/clipboard.rs
@@ -0,0 +1,322 @@
+use super::*;
+
+#[cfg(not(any(target_arch = "wasm32", target_os = "android")))]
+pub use real::*;
+#[cfg(not(any(target_arch = "wasm32", target_os = "android")))]
+mod real {
+    use super::*;
+    use std::sync::LazyLock;
+
+    use parking_lot::Mutex;
+
+    pub type SavedClipboardData = HashMap<u16, ClipboardData>;
+    #[derive(Debug, Clone)]
+    pub enum ClipboardData {
+        Text(String),
+        Image(arboard::ImageData<'static>),
+    }
+    use ClipboardData::*;
+
+    static CLIPBOARD: LazyLock<Mutex<arboard::Clipboard>> = LazyLock::new(|| {
+        for _ in 0..10 {
+            let c = arboard::Clipboard::new();
+            if let Ok(goodclip) = c {
+                log::trace!("clipboard init");
+                return Mutex::new(goodclip);
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+        panic!("could not initialize clipboard");
+    });
+
+    pub(crate) fn clpb_set(clipboard_string: &str) {
+        for _ in 0..10 {
+            match CLIPBOARD.lock().set_text(clipboard_string) {
+                Ok(()) => {
+                    log::trace!("clipboard set to {clipboard_string}");
+                    return;
+                }
+                Err(e) => {
+                    log::error!("error setting clipboard: {e:?}");
+                }
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+    }
+
+    pub(crate) fn clpb_cmd_set(cmd_and_args: &[&str]) {
+        let mut newclip = None;
+        for _ in 0..10 {
+            match CLIPBOARD.lock().get_text() {
+                Ok(cliptext) => {
+                    newclip = Some(run_cmd_get_stdout(cmd_and_args, cliptext.as_str()));
+                    break;
+                }
+                Err(e) => {
+                    if matches!(e, arboard::Error::ContentNotAvailable) {
+                        log::warn!("clipboard is unset or is image data; no-op for cmd-set");
+                        return;
+                    }
+                    log::error!("error setting clipboard: {e:?}");
+                }
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+        if let Some(nc) = newclip {
+            clpb_set(&nc);
+        }
+    }
+
+    fn run_cmd_get_stdout(cmd_and_args: &[&str], stdin: &str) -> String {
+        use std::io::Write;
+        use std::process::{Command, Stdio};
+        let mut args = cmd_and_args.iter();
+        let executable = args
+            .next()
+            .expect("parsing should have forbidden empty cmd");
+        log::trace!("executing {executable}");
+        let mut cmd = Command::new(executable);
+        cmd.stdin(Stdio::piped()).stdout(Stdio::piped());
+        for arg in args {
+            log::trace!("arg is {arg}");
+            cmd.arg(arg);
+        }
+        let mut child = match cmd.spawn() {
+            Ok(c) => c,
+            Err(e) => {
+                log::warn!("failed to spawn cmd, returning empty string for cmd-set: {e:?}");
+                return String::new();
+            }
+        };
+
+        let child_stdin = child.stdin.as_mut().unwrap();
+        if let Err(e) = child_stdin.write_all(stdin.as_bytes()) {
+            log::warn!("failed to write to stdin: {e:?}");
+        }
+        child
+            .wait_with_output()
+            .map(|out| String::from_utf8_lossy(&out.stdout).to_string())
+            .unwrap_or_else(|e| {
+                log::error!("failed to execute cmd: {e:?}");
+                String::new()
+            })
+    }
+
+    pub(crate) fn clpb_save(id: u16, save_data: &mut SavedClipboardData) {
+        for _ in 0..10 {
+            match CLIPBOARD.lock().get_text() {
+                Ok(cliptext) => {
+                    log::trace!("saving to id {id}: {cliptext}");
+                    save_data.insert(id, Text(cliptext));
+                    return;
+                }
+                Err(e) => {
+                    if matches!(e, arboard::Error::ContentNotAvailable) {
+                        // ContentNotAvailable could be an image or missing data
+                        break;
+                    }
+                    log::error!("error setting clipboard: {e:?}");
+                }
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+        for _ in 0..10 {
+            match CLIPBOARD.lock().get_image() {
+                Ok(clipimg) => {
+                    log::trace!("saving to id {id}: <imgdata>");
+                    save_data.insert(id, Image(clipimg));
+                }
+                Err(e) => {
+                    if matches!(e, arboard::Error::ContentNotAvailable) {
+                        break;
+                    }
+                    log::error!("error setting clipboard: {e:?}");
+                }
+            }
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+    }
+
+    pub(crate) fn clpb_restore(id: u16, save_data: &SavedClipboardData) {
+        let Some(restore_data) = save_data.get(&id) else {
+            log::warn!("tried to set clipboard with missing data in id {id}, doing nothing");
+            return;
+        };
+        for _ in 0..10 {
+            let e = match restore_data {
+                Text(s) => match CLIPBOARD.lock().set_text(s) {
+                    Ok(()) => {
+                        log::trace!("restored clipboard with id {id}: {s}");
+                        return;
+                    }
+                    Err(e) => e,
+                },
+                Image(img) => match CLIPBOARD.lock().set_image(img.clone()) {
+                    Ok(()) => {
+                        log::trace!("restored clipboard with id {id}: <imgdata>");
+                        return;
+                    }
+                    Err(e) => e,
+                },
+            };
+            log::error!("error setting clipboard: {e:?}");
+            std::thread::sleep(std::time::Duration::from_millis(25));
+        }
+    }
+
+    pub(crate) fn clpb_save_set(id: u16, content: &str, save_data: &mut SavedClipboardData) {
+        log::trace!("setting save id {id} with {content}");
+        save_data.insert(id, Text(content.into()));
+    }
+
+    #[test]
+    fn test_set() {
+        let mut sd = SavedClipboardData::default();
+        clpb_save_set(1, "hi", &mut sd);
+        if let Text(s) = sd.get(&1).unwrap() {
+            assert_eq!(s.as_str(), "hi");
+        } else {
+            panic!("did not expect image data");
+        }
+        assert!(!sd.contains_key(&2));
+    }
+
+    pub(crate) fn clpb_save_cmd_set(
+        id: u16,
+        cmd_and_args: &[&str],
+        save_data: &mut SavedClipboardData,
+    ) {
+        let stdin_content = match save_data.get(&id) {
+            Some(slot_data) => match slot_data {
+                Text(s) => s.as_str(),
+                Image(_) => "",
+            },
+            None => "",
+        };
+        let content = run_cmd_get_stdout(cmd_and_args, stdin_content);
+        log::trace!("setting save id {id} with {content}");
+        save_data.insert(id, Text(content));
+    }
+
+    #[test]
+    #[cfg(target_os = "windows")]
+    fn test_save_cmd_set() {
+        let mut sd = SavedClipboardData::default();
+        sd.insert(1, Text("one".into()));
+        clpb_save_cmd_set(
+            1,
+            &[
+                "powershell.exe".into(),
+                "-c".into(),
+                "$v = ($Input | Select-Object -First 1); Write-Host -NoNewLine \"$v $v\"".into(),
+            ],
+            &mut sd,
+        );
+
+        if let Text(s) = sd.get(&1).unwrap() {
+            assert_eq!("one one", s.as_str());
+        } else {
+            panic!("did not expect image data");
+        }
+        assert!(!sd.contains_key(&2));
+
+        clpb_save_cmd_set(
+            3,
+            &[
+                "powershell.exe".into(),
+                "-c".into(),
+                "Write-Host -NoNewLine 'wat'".into(),
+            ],
+            &mut sd,
+        );
+        if let Text(s) = sd.get(&3).unwrap() {
+            assert_eq!("wat", s.as_str());
+        } else {
+            panic!("did not expect image data");
+        }
+    }
+
+    pub(crate) fn clpb_save_swap(id1: u16, id2: u16, save_data: &mut SavedClipboardData) {
+        let data1 = save_data.remove(&id1);
+        let data2 = save_data.remove(&id2);
+        if let Some(d) = data1 {
+            save_data.insert(id2, d);
+        }
+        if let Some(d) = data2 {
+            save_data.insert(id1, d);
+        }
+    }
+
+    #[test]
+    fn test_swap() {
+        let mut sd = SavedClipboardData::default();
+        sd.insert(1, Text("one".into()));
+        sd.insert(2, Text("two".into()));
+        clpb_save_swap(1, 2, &mut sd);
+        if let Text(s) = sd.get(&1).unwrap() {
+            assert_eq!(s.as_str(), "two");
+        } else {
+            panic!("did not expect image data");
+        }
+        if let Text(s) = sd.get(&2).unwrap() {
+            assert_eq!(s.as_str(), "one");
+        } else {
+            panic!("did not expect image data");
+        }
+
+        sd.insert(3, Text("three".into()));
+        clpb_save_swap(3, 4, &mut sd);
+        assert!(!sd.contains_key(&3));
+        if let Text(s) = sd.get(&4).unwrap() {
+            assert_eq!(s.as_str(), "three");
+        } else {
+            panic!("did not expect image data");
+        }
+
+        sd.insert(6, Text("six".into()));
+        clpb_save_swap(5, 6, &mut sd);
+        if let Text(s) = sd.get(&5).unwrap() {
+            assert_eq!(s.as_str(), "six");
+        } else {
+            panic!("did not expect image data");
+        }
+        assert!(!sd.contains_key(&6));
+
+        clpb_save_swap(7, 8, &mut sd);
+        assert!(!sd.contains_key(&7));
+        assert!(!sd.contains_key(&8));
+    }
+}
+
+#[cfg(any(target_arch = "wasm32", target_os = "android"))]
+pub use fake::*;
+#[cfg(any(target_arch = "wasm32", target_os = "android"))]
+mod fake {
+    #![allow(unused)]
+    use super::*;
+    pub type SavedClipboardData = HashMap<u16, ClipboardData>;
+    #[derive(Debug, Clone)]
+    pub enum ClipboardData {
+        Text(String),
+        Text2(String),
+    }
+
+    pub(crate) fn clpb_set(clipboard_string: &str) {}
+
+    pub(crate) fn clpb_cmd_set(cmd_and_args: &[&str]) {}
+
+    pub(crate) fn clpb_save(id: u16, save_data: &mut SavedClipboardData) {}
+
+    pub(crate) fn clpb_restore(id: u16, save_data: &SavedClipboardData) {}
+
+    pub(crate) fn clpb_save_set(id: u16, content: &str, save_data: &mut SavedClipboardData) {}
+
+    pub(crate) fn clpb_save_cmd_set(
+        id: u16,
+        cmd_and_args: &[&str],
+        save_data: &mut SavedClipboardData,
+    ) {
+    }
+
+    pub(crate) fn clpb_save_swap(id1: u16, id2: u16, save_data: &mut SavedClipboardData) {}
+}
diff --git a/src/kanata/cmd.rs b/src/kanata/cmd.rs
index 580186606..e76d1063f 100644
--- a/src/kanata/cmd.rs
+++ b/src/kanata/cmd.rs
@@ -1,3 +1,7 @@
+#![cfg_attr(feature = "simulated_output", allow(dead_code, unused_imports))]
+
+use std::fmt::Write;
+
 use kanata_parser::cfg::parse_mod_prefix;
 use kanata_parser::cfg::sexpr::*;
 use kanata_parser::keys::*;
@@ -5,48 +9,69 @@ use kanata_parser::keys::*;
 // local log prefix
 const LP: &str = "cmd-out:";
 
-pub(super) fn run_cmd_in_thread(cmd_and_args: Vec<String>) -> std::thread::JoinHandle<()> {
+#[cfg(not(feature = "simulated_output"))]
+pub(super) fn run_cmd_in_thread(
+    cmd_and_args: Vec<String>,
+    log_level: Option<log::Level>,
+    error_log_level: Option<log::Level>,
+) -> std::thread::JoinHandle<()> {
     std::thread::spawn(move || {
         let mut args = cmd_and_args.iter();
-        let mut cmd = std::process::Command::new(
-            args.next()
-                .expect("parsing should have forbidden empty cmd"),
-        );
+        let mut printable_cmd = String::new();
+        let executable = args
+            .next()
+            .expect("parsing should have forbidden empty cmd");
+        write!(
+            printable_cmd,
+            "Program: {}, Arguments:",
+            executable.as_str()
+        )
+        .expect("write to string should succeed");
+        let mut cmd = std::process::Command::new(executable);
         for arg in args {
             cmd.arg(arg);
+            printable_cmd.push(' ');
+            printable_cmd.push_str(arg.as_str());
+        }
+        if let Some(level) = log_level {
+            log::log!(level, "Running cmd: {}", printable_cmd);
         }
         match cmd.output() {
             Ok(output) => {
-                log::info!(
-                    "Successfully ran cmd {}\nstdout:\n{}\nstderr:\n{}",
-                    {
-                        let mut printable_cmd = Vec::new();
-                        printable_cmd.push(format!("{:?}", cmd.get_program()));
-
-                        let printable_cmd = cmd.get_args().fold(printable_cmd, |mut cmd, arg| {
-                            cmd.push(format!("{arg:?}"));
-                            cmd
-                        });
-                        printable_cmd.join(" ")
-                    },
-                    String::from_utf8_lossy(&output.stdout),
-                    String::from_utf8_lossy(&output.stderr)
-                );
+                if let Some(level) = log_level {
+                    log::log!(
+                        level,
+                        "Successfully ran cmd: {}\nstdout:\n{}\nstderr:\n{}",
+                        printable_cmd,
+                        String::from_utf8_lossy(&output.stdout),
+                        String::from_utf8_lossy(&output.stderr)
+                    );
+                };
+            }
+            Err(e) => {
+                if let Some(level) = error_log_level {
+                    log::log!(
+                        level,
+                        "Failed to execute program {:?}: {}",
+                        cmd.get_program(),
+                        e
+                    )
+                }
             }
-            Err(e) => log::error!("Failed to execute cmd: {}", e),
         };
     })
 }
 
-pub(super) type Item = (KeyAction, OsCode);
+pub(super) type Item = KeyAction;
 
-#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub(super) enum KeyAction {
-    Press,
-    Release,
+    Press(OsCode),
+    Release(OsCode),
+    Delay(u16),
 }
-use kanata_keyberon::key_code::KeyCode;
 use KeyAction::*;
+use kanata_keyberon::key_code::KeyCode;
 
 fn empty() -> std::vec::IntoIter<Item> {
     vec![].into_iter()
@@ -65,11 +90,20 @@ fn parse_items<'a>(exprs: &'a [SExpr], items: &mut Vec<Item>) -> &'a [SExpr] {
     match &exprs[0] {
         SExpr::Atom(osc) => match str_to_oscode(&osc.t) {
             Some(osc) => {
-                items.push((Press, osc));
-                items.push((Release, osc));
+                items.push(Press(osc));
+                items.push(Release(osc));
                 &exprs[1..]
             }
-            None => try_parse_chord(&osc.t, exprs, items),
+            None => {
+                use std::str::FromStr;
+                match u16::from_str(&osc.t) {
+                    Ok(delay) => {
+                        items.push(Delay(delay));
+                        &exprs[1..]
+                    }
+                    Err(_) => try_parse_chord(&osc.t, exprs, items),
+                }
+            }
         },
         SExpr::List(sexprs) => {
             let mut remainder = sexprs.t.as_slice();
@@ -91,7 +125,7 @@ fn try_parse_chord<'a>(chord: &str, exprs: &'a [SExpr], items: &mut Vec<Item>) -
             }
         },
         Err(e) => {
-            log::warn!("{LP} found invalid chord {chord}: {e}");
+            log::warn!("{LP} found invalid chord {chord}: {}", e.msg);
             &exprs[1..]
         }
     }
@@ -105,13 +139,13 @@ fn try_parse_chorded_key(mods: &[KeyCode], osc: &str, chord: &str, items: &mut V
     match str_to_oscode(osc) {
         Some(osc) => {
             for mod_kc in mods.iter().copied() {
-                items.push((Press, mod_kc.into()));
+                items.push(Press(mod_kc.into()));
             }
-            items.push((Press, osc));
+            items.push(Press(osc));
             for mod_kc in mods.iter().copied() {
-                items.push((Release, mod_kc.into()));
+                items.push(Release(mod_kc.into()));
             }
-            items.push((Release, osc));
+            items.push(Release(osc));
         }
         None => {
             log::warn!("{LP} found chord {chord} with invalid key: {osc}");
@@ -138,21 +172,22 @@ fn try_parse_chorded_list<'a>(
         }
         SExpr::List(subexprs) => {
             for mod_kc in mods.iter().copied() {
-                items.push((Press, mod_kc.into()));
+                items.push(Press(mod_kc.into()));
             }
             let mut remainder = subexprs.t.as_slice();
             while !remainder.is_empty() {
                 remainder = parse_items(remainder, items);
             }
             for mod_kc in mods.iter().copied() {
-                items.push((Release, mod_kc.into()));
+                items.push(Release(mod_kc.into()));
             }
             &exprs[1..]
         }
     }
 }
 
-pub(super) fn keys_for_cmd_output(cmd_and_args: &[String]) -> impl Iterator<Item = Item> {
+#[cfg(not(feature = "simulated_output"))]
+pub(super) fn keys_for_cmd_output(cmd_and_args: &[&str]) -> impl Iterator<Item = Item> {
     let mut args = cmd_and_args.iter();
     let mut cmd = std::process::Command::new(
         args.next()
@@ -187,9 +222,26 @@ pub(super) fn keys_for_cmd_output(cmd_and_args: &[String]) -> impl Iterator<Item
         Err(e) => {
             log::warn!(
                 "{LP} could not parse an S-expression from cmd:\n{stdout}\n{}",
-                e.help_msg
+                e.msg
             );
             empty()
         }
     }
 }
+
+#[cfg(feature = "simulated_output")]
+pub(super) fn keys_for_cmd_output(cmd_and_args: &[&str]) -> impl Iterator<Item = Item> {
+    println!("cmd-keys:{cmd_and_args:?}");
+    [].iter().copied()
+}
+
+#[cfg(feature = "simulated_output")]
+pub(super) fn run_cmd_in_thread(
+    cmd_and_args: Vec<String>,
+    _log_level: Option<log::Level>,
+    _error_log_level: Option<log::Level>,
+) -> std::thread::JoinHandle<()> {
+    std::thread::spawn(move || {
+        println!("cmd:{cmd_and_args:?}");
+    })
+}
diff --git a/src/kanata/dynamic_macro.rs b/src/kanata/dynamic_macro.rs
new file mode 100644
index 000000000..cfd237c73
--- /dev/null
+++ b/src/kanata/dynamic_macro.rs
@@ -0,0 +1,315 @@
+use std::collections::VecDeque;
+
+use kanata_keyberon::layout::Event;
+use kanata_parser::cfg::ReplayDelayBehaviour;
+use kanata_parser::keys::OsCode;
+use rustc_hash::FxHashMap as HashMap;
+use rustc_hash::FxHashSet as HashSet;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DynamicMacroItem {
+    Press((OsCode, u16)),
+    Release((OsCode, u16)),
+    EndMacro(u16),
+}
+
+pub struct DynamicMacroReplayState {
+    active_macros: HashSet<u16>,
+    delay_remaining: u16,
+    macro_items: VecDeque<DynamicMacroItem>,
+}
+
+pub struct DynamicMacroRecordState {
+    starting_macro_id: u16,
+    waiting_event: Option<(OsCode, WaitingEventType)>,
+    macro_items: Vec<DynamicMacroItem>,
+    current_delay: u16,
+}
+
+enum WaitingEventType {
+    Press,
+    Release,
+}
+
+impl DynamicMacroRecordState {
+    fn new(macro_id: u16) -> Self {
+        Self {
+            starting_macro_id: macro_id,
+            waiting_event: None,
+            macro_items: vec![],
+            current_delay: 0,
+        }
+    }
+
+    fn add_release_for_all_unreleased_presses(&mut self) {
+        let mut pressed_oscs = HashSet::default();
+        for item in self.macro_items.iter() {
+            match item {
+                DynamicMacroItem::Press((osc, _)) => {
+                    pressed_oscs.insert(*osc);
+                }
+                DynamicMacroItem::Release((osc, _)) => {
+                    pressed_oscs.remove(osc);
+                }
+                DynamicMacroItem::EndMacro(_) => {}
+            };
+        }
+        // Hopefully release order doesn't matter here. A HashSet is being used, meaning release order is arbitrary.
+        for osc in pressed_oscs.into_iter() {
+            self.macro_items.push(DynamicMacroItem::Release((osc, 0)));
+        }
+    }
+
+    fn add_event(&mut self, osc: OsCode, evtype: WaitingEventType) {
+        if let Some(pending_event) = self.waiting_event.take() {
+            match pending_event.1 {
+                WaitingEventType::Press => self.macro_items.push(DynamicMacroItem::Press((
+                    pending_event.0,
+                    self.current_delay,
+                ))),
+                WaitingEventType::Release => self.macro_items.push(DynamicMacroItem::Release((
+                    pending_event.0,
+                    self.current_delay,
+                ))),
+            };
+        }
+        self.current_delay = 0;
+        self.waiting_event = Some((osc, evtype));
+    }
+}
+
+/// A replay event for a dynamically recorded macro.
+/// Note that the key event and the subsequent delay must be processed together.
+/// Otherwise there will be real-world time gap between event and the delay,
+/// which results in an inaccurate simulation of the keyberon state machine.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct ReplayEvent(Event, u16);
+
+impl ReplayEvent {
+    pub fn key_event(self) -> Event {
+        self.0
+    }
+    pub fn delay(self) -> u16 {
+        self.1
+    }
+}
+
+pub fn tick_record_state(record_state: &mut Option<DynamicMacroRecordState>) {
+    if let Some(state) = record_state {
+        state.current_delay = state.current_delay.saturating_add(1);
+    }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct ReplayBehaviour {
+    pub delay: ReplayDelayBehaviour,
+}
+
+pub fn tick_replay_state(
+    replay_state: &mut Option<DynamicMacroReplayState>,
+    replay_behaviour: ReplayBehaviour,
+) -> Option<ReplayEvent> {
+    if let Some(state) = replay_state {
+        state.delay_remaining = state.delay_remaining.saturating_sub(1);
+        if state.delay_remaining == 0 {
+            state.delay_remaining = 5;
+            match state.macro_items.pop_front() {
+                None => {
+                    *replay_state = None;
+                    log::debug!("finished macro replay");
+                    None
+                }
+                Some(i) => match i {
+                    DynamicMacroItem::Press((key, delay)) => {
+                        let event = Event::Press(0, key.into());
+                        let delay = match replay_behaviour.delay {
+                            ReplayDelayBehaviour::Constant => 0,
+                            ReplayDelayBehaviour::Recorded => {
+                                state.delay_remaining = delay;
+                                delay
+                            }
+                        };
+                        Some(ReplayEvent(event, delay))
+                    }
+                    DynamicMacroItem::Release((key, delay)) => {
+                        let event = Event::Release(0, key.into());
+                        let delay = match replay_behaviour.delay {
+                            ReplayDelayBehaviour::Constant => 0,
+                            ReplayDelayBehaviour::Recorded => {
+                                state.delay_remaining = delay;
+                                delay
+                            }
+                        };
+                        Some(ReplayEvent(event, delay))
+                    }
+                    DynamicMacroItem::EndMacro(macro_id) => {
+                        state.active_macros.remove(&macro_id);
+                        None
+                    }
+                },
+            }
+        } else {
+            None
+        }
+    } else {
+        None
+    }
+}
+
+pub fn begin_record_macro(
+    macro_id: u16,
+    record_state: &mut Option<DynamicMacroRecordState>,
+) -> Option<(u16, Vec<DynamicMacroItem>)> {
+    match record_state.take() {
+        None => {
+            log::info!("starting dynamic macro {macro_id} recording");
+            *record_state = Some(DynamicMacroRecordState::new(macro_id));
+            None
+        }
+        Some(mut state) => {
+            if let Some(pending_event) = state.waiting_event.take() {
+                match pending_event.1 {
+                    WaitingEventType::Press => state.macro_items.push(DynamicMacroItem::Press((
+                        pending_event.0,
+                        state.current_delay,
+                    ))),
+                    WaitingEventType::Release => state.macro_items.push(DynamicMacroItem::Release(
+                        (pending_event.0, state.current_delay),
+                    )),
+                };
+            }
+            // remove the last item, since it's almost certainly a "macro
+            // record" key press action which we don't want to keep.
+            state.macro_items.remove(state.macro_items.len() - 1);
+            state.add_release_for_all_unreleased_presses();
+
+            if state.starting_macro_id == macro_id {
+                log::info!(
+                    "same macro id pressed. saving and stopping dynamic macro {} recording",
+                    state.starting_macro_id
+                );
+                *record_state = None;
+            } else {
+                log::info!(
+                    "saving dynamic macro {} recording then starting new macro recording {macro_id}",
+                    state.starting_macro_id,
+                );
+                *record_state = Some(DynamicMacroRecordState::new(macro_id));
+            }
+            Some((state.starting_macro_id, state.macro_items))
+        }
+    }
+}
+
+pub fn record_press(
+    record_state: &mut Option<DynamicMacroRecordState>,
+    osc: OsCode,
+    max_presses: u16,
+) -> Option<(u16, Vec<DynamicMacroItem>)> {
+    if let Some(state) = record_state {
+        // This is not 100% accurate since there may be multiple presses before any of
+        // their relesease are received. But it's probably good enough in practice.
+        //
+        // The presses are defined so that a user cares about the number of keys rather
+        // than events. So rather than the user multiplying by 2 in their config after
+        // considering the number of keys they want, kanata does the multiplication
+        // instead.
+        if state.macro_items.len() > usize::from(max_presses) * 2 {
+            log::warn!(
+                "saving and stopping dynamic macro {} recording due to exceeding limit",
+                state.starting_macro_id,
+            );
+            state.add_release_for_all_unreleased_presses();
+            let state = record_state.take().unwrap();
+            Some((state.starting_macro_id, state.macro_items))
+        } else {
+            log::debug!("delay to press: {}", state.current_delay);
+            state.add_event(osc, WaitingEventType::Press);
+            None
+        }
+    } else {
+        None
+    }
+}
+
+pub fn record_release(record_state: &mut Option<DynamicMacroRecordState>, osc: OsCode) {
+    if let Some(state) = record_state {
+        log::debug!("delay to release: {}", state.current_delay);
+        state.add_event(osc, WaitingEventType::Release);
+    }
+}
+
+pub fn stop_macro(
+    record_state: &mut Option<DynamicMacroRecordState>,
+    num_actions_to_remove: u16,
+) -> Option<(u16, Vec<DynamicMacroItem>)> {
+    if let Some(mut state) = record_state.take() {
+        if let Some(pending_event) = state.waiting_event.take() {
+            match pending_event.1 {
+                WaitingEventType::Press => state.macro_items.push(DynamicMacroItem::Press((
+                    pending_event.0,
+                    state.current_delay,
+                ))),
+                WaitingEventType::Release => state.macro_items.push(DynamicMacroItem::Release((
+                    pending_event.0,
+                    state.current_delay,
+                ))),
+            };
+        }
+        // remove the last item independently of `num_actions_to_remove`
+        // since it's almost certainly a "macro record stop" key press
+        // action which we don't want to keep.
+        state.macro_items.remove(state.macro_items.len() - 1);
+        log::info!(
+            "saving and stopping dynamic macro {} recording with {num_actions_to_remove} actions at the end removed",
+            state.starting_macro_id,
+        );
+        state.macro_items.truncate(
+            state
+                .macro_items
+                .len()
+                .saturating_sub(usize::from(num_actions_to_remove)),
+        );
+        state.add_release_for_all_unreleased_presses();
+        Some((state.starting_macro_id, state.macro_items))
+    } else {
+        None
+    }
+}
+
+pub fn play_macro(
+    macro_id: u16,
+    replay_state: &mut Option<DynamicMacroReplayState>,
+    recorded_macros: &HashMap<u16, Vec<DynamicMacroItem>>,
+) {
+    match replay_state {
+        None => {
+            log::info!("replaying macro {macro_id}");
+            *replay_state = recorded_macros.get(&macro_id).map(|macro_items| {
+                let mut active_macros = HashSet::default();
+                active_macros.insert(macro_id);
+                log::debug!("playing macro {macro_items:?}");
+                DynamicMacroReplayState {
+                    active_macros,
+                    delay_remaining: 0,
+                    macro_items: macro_items.clone().into(),
+                }
+            });
+        }
+        Some(state) => {
+            if state.active_macros.contains(&macro_id) {
+                log::warn!("refusing to recurse into macro {macro_id}");
+            } else if let Some(items) = recorded_macros.get(&macro_id) {
+                log::debug!("prepending macro {macro_id} items to current replay");
+                log::debug!("playing macro {items:?}");
+                state.active_macros.insert(macro_id);
+                state
+                    .macro_items
+                    .push_front(DynamicMacroItem::EndMacro(macro_id));
+                for item in items.iter().copied().rev() {
+                    state.macro_items.push_front(item);
+                }
+            }
+        }
+    }
+}
diff --git a/src/kanata/key_repeat.rs b/src/kanata/key_repeat.rs
new file mode 100644
index 000000000..a27c1f161
--- /dev/null
+++ b/src/kanata/key_repeat.rs
@@ -0,0 +1,105 @@
+use super::*;
+
+impl Kanata {
+    /// This compares the active keys in the keyberon layout against the potential key outputs for
+    /// corresponding physical key in the configuration. If any of keyberon active keys match any
+    /// potential physical key output, write the repeat event to the OS.
+    pub(super) fn handle_repeat(&mut self, event: &KeyEvent) -> Result<()> {
+        let ret = self.handle_repeat_actual(event);
+        // The cur_keys Vec is re-used for processing, for efficiency reasons to avoid allocation.
+        // Unlike prev_keys which has useful info for the next call to handle_time_ticks, cur_keys
+        // can be reused and cleared — it just needs to be empty for the next handle_time_ticks
+        // call.
+        self.cur_keys.clear();
+        ret
+    }
+
+    pub(super) fn handle_repeat_actual(&mut self, event: &KeyEvent) -> Result<()> {
+        if let Some(state) = self.sequence_state.get_active() {
+            // While in non-visible sequence mode, don't send key repeats. I can't imagine it's a
+            // helpful use case for someone trying to type in a sequence that they want to rely on
+            // key repeats to finish a sequence. I suppose one might want to do repeat in order to
+            // try and cancel an input sequence... I'll wait for a user created issue to deal with
+            // this.
+            //
+            // It should be noted that even with visible-backspaced, key repeat does not interact
+            // with the sequence; the key is output with repeat as normal. Which might be
+            // surprising/unexpected. It's technically fixable but I don't want to add the code to
+            // do that if nobody needs it.
+            if state.sequence_input_mode != SequenceInputMode::VisibleBackspaced {
+                return Ok(());
+            }
+        }
+        self.cur_keys.extend(self.layout.b().keycodes());
+        self.overrides.override_keys(
+            &mut self.cur_keys,
+            &mut self.override_states,
+            self.layout.b().current_layer() as u16,
+        );
+
+        // Prioritize checking the active layer in case a layer-while-held is active.
+        let active_held_layers = self.layout.bm().trans_resolution_layer_order();
+        let mut held_layer_active = false;
+        for layer in active_held_layers {
+            held_layer_active = true;
+            if let Some(outputs_for_key) = self.key_outputs[usize::from(layer)].get(&event.code) {
+                log::debug!("key outs for active layer-while-held: {outputs_for_key:?};");
+                for osc in outputs_for_key.iter().rev().copied() {
+                    let kc = osc.into();
+                    if self.cur_keys.contains(&kc)
+                        || self.unshifted_keys.contains(&kc)
+                        || self.unmodded_keys.contains(&kc)
+                    {
+                        log::debug!("repeat    {:?}", KeyCode::from(osc));
+                        if let Err(e) = write_key(&mut self.kbd_out, osc, KeyValue::Repeat) {
+                            bail!("could not write key {e:?}")
+                        }
+                        return Ok(());
+                    }
+                }
+            }
+        }
+        if held_layer_active {
+            log::debug!("empty layer-while-held outputs, probably transparent");
+        }
+
+        if let Some(outputs_for_key) =
+            self.key_outputs[self.layout.bm().default_layer].get(&event.code)
+        {
+            // Try matching a key on the default layer.
+            //
+            // This code executes in two cases:
+            // 1. current layer is the default layer
+            // 2. current layer is layer-while-held but did not find a match in the code above, e.g. a
+            //    transparent key was pressed.
+            log::debug!("key outs for default layer: {outputs_for_key:?};");
+            for osc in outputs_for_key.iter().rev().copied() {
+                let kc = osc.into();
+                if self.cur_keys.contains(&kc)
+                    || self.unshifted_keys.contains(&kc)
+                    || self.unmodded_keys.contains(&kc)
+                {
+                    log::debug!("repeat    {:?}", KeyCode::from(osc));
+                    if let Err(e) = write_key(&mut self.kbd_out, osc, KeyValue::Repeat) {
+                        bail!("could not write key {e:?}")
+                    }
+                    return Ok(());
+                }
+            }
+        }
+
+        // Reached here and have not exited yet.
+        // Check the standard key output itself because default layer might also be transparent
+        // and have delegated to defsrc handling.
+        log::debug!("checking defsrc output");
+        let kc = event.code.into();
+        if (self.cur_keys.contains(&kc)
+            || self.unshifted_keys.contains(&kc)
+            || self.unmodded_keys.contains(&kc))
+            && let Err(e) = write_key(&mut self.kbd_out, event.code, KeyValue::Repeat)
+        {
+            bail!("could not write key {e:?}");
+        }
+        Ok(())
+    }
+}
diff --git a/src/kanata/linux.rs b/src/kanata/linux.rs
index aa2c2563c..124165611 100644
--- a/src/kanata/linux.rs
+++ b/src/kanata/linux.rs
@@ -1,9 +1,15 @@
-use anyhow::{anyhow, bail, Result};
+#![cfg_attr(
+    feature = "simulated_output",
+    allow(dead_code, unused_imports, unused_variables, unused_mut)
+)]
+
+use anyhow::{Result, anyhow, bail};
+use evdev::{EventSummary, InputEvent, RelativeAxisCode};
 use log::info;
 use parking_lot::Mutex;
 use std::convert::TryFrom;
-use std::sync::mpsc::Sender;
 use std::sync::Arc;
+use std::sync::mpsc::SyncSender as Sender;
 
 use super::*;
 
@@ -14,29 +20,46 @@ impl Kanata {
         info!("entering the event loop");
 
         let k = kanata.lock();
+        let allow_hardware_repeat = k.allow_hardware_repeat;
+        let mouse_movement_key = k.mouse_movement_key.clone();
         let mut kbd_in = match KbdIn::new(
             &k.kbd_in_paths,
             k.continue_if_no_devices,
             k.include_names.clone(),
             k.exclude_names.clone(),
+            k.device_detect_mode,
         ) {
             Ok(kbd_in) => kbd_in,
             Err(e) => {
                 bail!("failed to open keyboard device(s): {}", e)
             }
         };
+
+        // In some environments, this needs to be done after the input device grab otherwise it
+        // does not work on kanata startup.
+        Kanata::set_repeat_rate(k.x11_repeat_rate)?;
         drop(k);
 
         loop {
             let events = kbd_in.read().map_err(|e| anyhow!("failed read: {}", e))?;
-            log::trace!("{events:?}");
+            log::trace!("event count: {}\nevents:\n{events:?}", events.len());
+
+            for in_event in events.iter().copied() {
+                if let Some(ms_mvmt_key) = *mouse_movement_key.lock()
+                    && let EventSummary::RelativeAxis(_, _, _) = in_event.destructure()
+                {
+                    let fake_event = KeyEvent::new(ms_mvmt_key, KeyValue::Tap);
+                    if let Err(e) = tx.try_send(fake_event) {
+                        bail!("failed to send on channel: {}", e)
+                    }
+                }
 
-            for in_event in events.into_iter() {
                 let key_event = match KeyEvent::try_from(in_event) {
                     Ok(ev) => ev,
                     _ => {
-                        // Pass-through non-key events
+                        // Pass-through non-key and non-scroll events
                         let mut kanata = kanata.lock();
+                        #[cfg(not(feature = "simulated_output"))]
                         kanata
                             .kbd_out
                             .write_raw(in_event)
@@ -47,19 +70,42 @@ impl Kanata {
 
                 check_for_exit(&key_event);
 
-                // Check if this keycode is mapped in the configuration. If it hasn't been mapped, send
-                // it immediately.
+                if key_event.value == KeyValue::Repeat && !allow_hardware_repeat {
+                    continue;
+                }
+
+                if key_event.value == KeyValue::Tap {
+                    // Scroll event for sure. Only scroll events produce Tap.
+                    if !handle_scroll(&kanata, in_event, key_event.code, &events)? {
+                        continue;
+                    }
+                }
+
+                match key_event.value {
+                    KeyValue::Release => {
+                        PRESSED_KEYS.lock().remove(&key_event.code);
+                    }
+                    KeyValue::Press => {
+                        PRESSED_KEYS.lock().insert(key_event.code);
+                    }
+                    _ => {}
+                }
+
+                // Handle normal keypresses.
+                // Check if this keycode is mapped in the configuration.
+                // If it hasn't been mapped, send it immediately.
                 if !MAPPED_KEYS.lock().contains(&key_event.code) {
                     let mut kanata = kanata.lock();
+                    #[cfg(not(feature = "simulated_output"))]
                     kanata
                         .kbd_out
-                        .write_key(key_event.code, key_event.value)
-                        .map_err(|e| anyhow!("failed write key: {}", e))?;
+                        .write_raw(in_event)
+                        .map_err(|e| anyhow!("failed write: {}", e))?;
                     continue;
-                }
+                };
 
                 // Send key events to the processing loop
-                if let Err(e) = tx.send(key_event) {
+                if let Err(e) = tx.try_send(key_event) {
                     bail!("failed to send on channel: {}", e)
                 }
             }
@@ -70,28 +116,20 @@ impl Kanata {
         Ok(())
     }
 
-    pub fn set_repeat_rate(cfg_items: &HashMap<String, String>) -> Result<()> {
-        if let Some(x11_rpt_str) = cfg_items.get("linux-x11-repeat-delay-rate") {
-            let delay_rate = x11_rpt_str.split(',').collect::<Vec<_>>();
-            let errmsg = format!("Invalid value for linux-x11-repeat-delay-rate: \"{x11_rpt_str}\".\nExpected two numbers 0-65535 separated by a comma, e.g. 200,25");
-            if delay_rate.len() != 2 {
-                log::error!("{errmsg}");
-            }
-            str::parse::<u16>(delay_rate[0]).map_err(|e| {
-                log::error!("{errmsg}");
-                e
-            })?;
-            str::parse::<u16>(delay_rate[1]).map_err(|e| {
-                log::error!("{errmsg}");
-                e
-            })?;
+    pub fn set_repeat_rate(s: Option<KeyRepeatSettings>) -> Result<()> {
+        if let Some(s) = s {
             log::info!(
                 "Using xset to set X11 repeat delay to {} and repeat rate to {}",
-                delay_rate[0],
-                delay_rate[1]
+                s.delay,
+                s.rate,
             );
             let cmd_output = std::process::Command::new("xset")
-                .args(["r", "rate", delay_rate[0], delay_rate[1]])
+                .args([
+                    "r",
+                    "rate",
+                    s.delay.to_string().as_str(),
+                    s.rate.to_string().as_str(),
+                ])
                 .output()
                 .map_err(|e| {
                     log::error!("failed to run xset: {e:?}");
@@ -109,3 +147,70 @@ impl Kanata {
         Ok(())
     }
 }
+
+/// Returns true if the scroll event should be sent to the processing loop, otherwise returns
+/// false.
+fn handle_scroll(
+    kanata: &Mutex<Kanata>,
+    in_event: InputEvent,
+    code: OsCode,
+    all_events: &[InputEvent],
+) -> Result<bool> {
+    let direction: MWheelDirection = code.try_into().unwrap();
+    let scroll_distance = in_event.value().unsigned_abs() as u16;
+    match in_event.destructure() {
+        EventSummary::RelativeAxis(_, axis_type, _) => {
+            match axis_type {
+                RelativeAxisCode::REL_WHEEL | RelativeAxisCode::REL_HWHEEL => {
+                    if MAPPED_KEYS.lock().contains(&code) {
+                        return Ok(true);
+                    }
+                    // If we just used `write_raw` here, some of the scrolls issued by kanata would be
+                    // REL_WHEEL_HI_RES + REL_WHEEL and some just REL_WHEEL and an issue like this one
+                    // would happen: https://github.com/jtroo/kanata/issues/395
+                    //
+                    // So to fix this case, we need to use `scroll` which will also send hi-res scrolls
+                    // along normal scrolls.
+                    //
+                    // However, if this is a normal scroll event, it may be sent alongside a hi-res
+                    // scroll event. In this scenario, the hi-res event should be used to call
+                    // scroll, and not the normal event. Otherwise, too much scrolling will happen.
+                    let mut kanata = kanata.lock();
+                    if !all_events.iter().any(|ev| {
+                        matches!(
+                            ev.destructure(),
+                            EventSummary::RelativeAxis(
+                                _,
+                                RelativeAxisCode::REL_WHEEL_HI_RES
+                                    | RelativeAxisCode::REL_HWHEEL_HI_RES,
+                                _
+                            )
+                        )
+                    }) {
+                        kanata
+                            .kbd_out
+                            .scroll(direction, scroll_distance * HI_RES_SCROLL_UNITS_IN_LO_RES)
+                            .map_err(|e| anyhow!("failed write: {}", e))?;
+                    }
+                    Ok(false)
+                }
+                RelativeAxisCode::REL_WHEEL_HI_RES | RelativeAxisCode::REL_HWHEEL_HI_RES => {
+                    if !MAPPED_KEYS.lock().contains(&code) {
+                        // Passthrough if the scroll wheel event is not mapped
+                        // in the configuration.
+                        let mut kanata = kanata.lock();
+                        kanata
+                            .kbd_out
+                            .scroll(direction, scroll_distance)
+                            .map_err(|e| anyhow!("failed write: {}", e))?;
+                    }
+                    // Kanata will not handle high resolution scroll events for now.
+                    // Full notch scrolling only.
+                    Ok(false)
+                }
+                _ => unreachable!("expect to be handling a wheel event"),
+            }
+        }
+        _ => unreachable!("expect to be handling a wheel event"),
+    }
+}
diff --git a/src/kanata/macos.rs b/src/kanata/macos.rs
new file mode 100644
index 000000000..72f7b46fa
--- /dev/null
+++ b/src/kanata/macos.rs
@@ -0,0 +1,287 @@
+use super::*;
+use anyhow::{Result, anyhow, bail};
+use log::info;
+use parking_lot::Mutex;
+use std::convert::TryFrom;
+use std::sync::Arc;
+use std::sync::mpsc::SyncSender as Sender;
+use std::time::Duration;
+
+impl Kanata {
+    /// Enter an infinite loop that listens for OS key events and sends them to the processing thread.
+    ///
+    /// Contains a recovery mechanism: if the DriverKit output connection drops
+    /// (daemon crash, not installed, etc.), input devices are released so the
+    /// keyboard returns to normal operation. When the connection recovers,
+    /// devices are re-seized and remapping resumes.
+    ///
+    /// Recovery uses `regrab_input()` rather than recreating `KbdIn` to avoid
+    /// re-initializing the pqrs client (via `init_sink()`). A second client
+    /// causes duplicate connection callbacks that race with the IOHIDManager,
+    /// leading to "exclusive access" errors on the input device.
+    pub fn event_loop(kanata: Arc<Mutex<Self>>, tx: Sender<KeyEvent>) -> Result<()> {
+        info!("entering the event loop");
+
+        {
+            let rc = unsafe {
+                libc::pthread_set_qos_class_self_np(
+                    libc::qos_class_t::QOS_CLASS_USER_INTERACTIVE,
+                    0,
+                )
+            };
+            if rc == 0 {
+                info!("macOS: event loop thread QoS set to USER_INTERACTIVE");
+            } else {
+                log::warn!("macOS: failed to set event loop thread QoS (rc={rc})");
+            }
+        }
+
+        let k = kanata.lock();
+        let allow_hardware_repeat = k.allow_hardware_repeat;
+        let include_names = k.include_names.clone();
+        let exclude_names = k.exclude_names.clone();
+        let input_devices = k.input_devices.clone();
+        let continue_if_no_devices = k.continue_if_no_devices;
+        drop(k);
+
+        let mut kb = match KbdIn::new(
+            include_names,
+            exclude_names,
+            input_devices.as_deref(),
+            continue_if_no_devices,
+        ) {
+            Ok(kbd_in) => kbd_in,
+            Err(e) => bail!("failed to open keyboard device(s): {}", e),
+        };
+
+        {
+            let kanata = kanata.lock();
+            if !kanata
+                .kbd_out
+                .wait_until_ready(Some(Duration::from_secs(10)))
+            {
+                log::warn!(
+                    "output backend not ready after 10s. Key output may fail until the backend recovers."
+                );
+            }
+        }
+
+        // Clear any stale key state left on the virtual HID by a previous
+        // kanata process. The Karabiner driver retains the keyboard report
+        // across client reconnections, so keys that were pressed when the old
+        // process died remain "held" until explicitly released. Posting a
+        // release for a no-op key forces an async_post_report with the new
+        // process's empty keyboard.keys set, clearing all stale keys.
+        {
+            let mut kanata = kanata.lock();
+            if kanata.kbd_out.output_ready() {
+                use kanata_parser::keys::OsCode;
+                if let Err(e) = kanata.kbd_out.release_key(OsCode::KEY_F24) {
+                    log::warn!("failed to clear stale virtual HID state: {e}");
+                } else {
+                    info!("cleared stale virtual HID keyboard state");
+                }
+            }
+        }
+
+        // Startup is done. Stop decorating future `SIGABRT`s with the
+        // Karabiner setup hint — any abort from here on is almost
+        // certainly a dispatcher/CoreFoundation teardown race (e.g. the
+        // `mutex lock failed` one on kill-chord exit), for which the
+        // Karabiner hint would be actively misleading.
+        crate::oskbd::mark_karabiner_startup_complete();
+
+        if kb.is_grabbed() {
+            info!("keyboard grabbed, entering event processing loop");
+        } else {
+            info!("no devices grabbed yet, waiting for device connection...");
+        }
+
+        // Start the mouse event tap on a background thread if any mouse buttons
+        // are mapped in the config. Similar to the Windows mouse hook.
+        // The braces scope-drop the MAPPED_KEYS lock before entering the event loop;
+        // the JoinHandle is dropped because the run loop runs for the process lifetime.
+        // Subsequent live reloads that introduce mouse keys to a previously
+        // mouse-key-free defsrc install the tap lazily via
+        // `ensure_mouse_listener_installed_after_reload` (called from
+        // `do_live_reload`). The tap callback re-reads `MAPPED_KEYS` per event,
+        // so reloads that change *which* mouse keys are mapped also take
+        // effect without restart.
+        //
+        // Clone the mouse_movement_key Arc *before* locking MAPPED_KEYS to keep
+        // the project-wide lock order `kanata -> MAPPED_KEYS`. Reversing it here
+        // would create a new ordering edge with the rest of this file.
+        {
+            let mmk = kanata.lock().mouse_movement_key.clone();
+            let mapped = MAPPED_KEYS.lock();
+            let _ = crate::oskbd::start_mouse_listener(tx.clone(), &mapped, mmk);
+        }
+
+        // Toggles `is_screen_grab_paused()` on lock / fast-user-switch.
+        // See `oskbd::start_screen_lock_poller` for the design notes.
+        crate::oskbd::start_screen_lock_poller();
+
+        loop {
+            // --- Event processing loop ---
+            let needs_recovery = loop {
+                // Check output health before blocking on input
+                if !kanata.lock().kbd_out.output_ready() {
+                    log::warn!("output backend unavailable — releasing input devices");
+                    break true;
+                }
+
+                if crate::oskbd::is_screen_grab_paused() {
+                    log::info!(
+                        "console session paused (lock/user-switch) — releasing input devices"
+                    );
+                    break true;
+                }
+
+                let event = match kb.read() {
+                    Ok(ev) => ev,
+                    Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
+                        // Pipe closed by release_input_only() — expected during recovery
+                        log::info!("input pipe EOF — devices were released");
+                        break true;
+                    }
+                    Err(e) => return Err(anyhow!("failed read: {}", e)),
+                };
+
+                // Re-check after the blocking read: the lock may have
+                // landed while we were inside `wait_key`, in which case
+                // this event is the first keystroke from the new user
+                // and must be dropped, not remapped. See the caveat in
+                // `oskbd::macos`.
+                if crate::oskbd::is_screen_grab_paused() {
+                    log::info!(
+                        "console session paused (lock/user-switch) — dropping read event and releasing input devices"
+                    );
+                    break true;
+                }
+
+                let mut key_event = match KeyEvent::try_from(event) {
+                    Ok(mut ev) => {
+                        ev.set_device_id(kb.device_id_for_hash(event.device_hash));
+                        ev
+                    }
+                    _ => {
+                        log::debug!("{event:?} is unrecognized!");
+                        let mut kanata = kanata.lock();
+                        match kanata.kbd_out.write(event) {
+                            Ok(()) => continue,
+                            Err(e) if e.kind() == std::io::ErrorKind::NotConnected => {
+                                log::warn!(
+                                    "output backend unavailable during write — releasing input devices"
+                                );
+                                break true;
+                            }
+                            Err(e) => return Err(anyhow!("failed write: {}", e)),
+                        }
+                    }
+                };
+
+                check_for_exit(&key_event);
+
+                if key_event.value == KeyValue::Repeat && !allow_hardware_repeat {
+                    continue;
+                }
+
+                if !MAPPED_KEYS.lock().contains(&key_event.code) {
+                    log::debug!("{key_event:?} is not mapped");
+                    let mut kanata = kanata.lock();
+                    match kanata.kbd_out.write(event) {
+                        Ok(()) => continue,
+                        Err(e) if e.kind() == std::io::ErrorKind::NotConnected => {
+                            log::warn!(
+                                "output backend unavailable during write — releasing input devices"
+                            );
+                            break true;
+                        }
+                        Err(e) => return Err(anyhow!("failed write: {}", e)),
+                    }
+                }
+
+                log::debug!("sending {key_event:?} to processing loop");
+
+                match key_event.value {
+                    KeyValue::Release => {
+                        PRESSED_KEYS.lock().remove(&key_event.code);
+                    }
+                    KeyValue::Press => {
+                        let mut pressed_keys = PRESSED_KEYS.lock();
+                        if pressed_keys.contains(&key_event.code) {
+                            key_event.value = KeyValue::Repeat;
+                        } else {
+                            pressed_keys.insert(key_event.code);
+                        }
+                    }
+                    _ => {}
+                }
+                if let Err(std::sync::mpsc::TrySendError::Full(ke)) = tx.try_send(key_event) {
+                    log::warn!("channel full, blocking until processing thread drains");
+                    if let Err(e) = tx.send(ke) {
+                        bail!("failed to send key event: channel disconnected: {e}");
+                    }
+                }
+            };
+
+            if !needs_recovery {
+                break Ok(());
+            }
+
+            // --- Release input so the keyboard works normally (unseized) ---
+            kb.release_input();
+
+            info!(
+                "Input devices released. Keyboard is usable (without remapping). \
+                 Waiting for the output backend and console session to recover..."
+            );
+
+            // Re-grab once both the sink is healthy and the session is
+            // unpaused. Sleep explicitly when only the sink is ready,
+            // since `wait_until_ready` returns instantly in that case.
+            loop {
+                let sink_ready = kanata
+                    .lock()
+                    .kbd_out
+                    .wait_until_ready(Some(Duration::from_millis(500)));
+                let session_ready = !crate::oskbd::is_screen_grab_paused();
+                if sink_ready && session_ready {
+                    // Let the direct DriverKit backend finish its callback sequence
+                    // before we re-seize input devices. Seizing too early can race
+                    // with IOKit enumeration triggered by those callbacks.
+                    std::thread::sleep(Duration::from_secs(1));
+                    info!("output backend and console session ready — re-grabbing input devices");
+                    break;
+                }
+                if sink_ready && !session_ready {
+                    std::thread::sleep(Duration::from_millis(500));
+                }
+            }
+
+            {
+                let mut kanata = kanata.lock();
+                kanata
+                    .kbd_out
+                    .release_tracked_output_keys("output-backend-recovery");
+            }
+            PRESSED_KEYS.lock().clear();
+
+            // Re-seize input devices using regrab_input() which creates a fresh
+            // pipe and listener thread without re-initializing the sink client.
+            if kb.regrab_input() {
+                info!("keyboard grabbed, entering event processing loop");
+            } else if continue_if_no_devices {
+                info!("no devices grabbed after recovery, waiting for device connection...");
+            } else {
+                bail!("failed to re-grab keyboard devices after DriverKit recovery");
+            }
+
+            // Back to the event processing loop.
+        }
+    }
+
+    pub fn check_release_non_physical_shift(&mut self) -> Result<()> {
+        Ok(())
+    }
+}
diff --git a/src/kanata/millisecond_counting.rs b/src/kanata/millisecond_counting.rs
new file mode 100644
index 000000000..0e4a8fa26
--- /dev/null
+++ b/src/kanata/millisecond_counting.rs
@@ -0,0 +1,68 @@
+use web_time::Instant;
+
+pub struct MillisecondCountResult {
+    pub last_tick: Instant,
+    pub ms_elapsed: u128,
+    pub ms_remainder_in_ns: u128,
+}
+
+pub fn count_ms_elapsed(
+    last_tick: Instant,
+    now: Instant,
+    prev_ms_remainder_in_ns: u128,
+) -> MillisecondCountResult {
+    const NS_IN_MS: u128 = 1_000_000;
+    let ns_elapsed = now.duration_since(last_tick).as_nanos();
+    let ns_elapsed_with_rem = ns_elapsed + prev_ms_remainder_in_ns;
+    let ms_elapsed = ns_elapsed_with_rem / NS_IN_MS;
+    let ms_remainder_in_ns = ns_elapsed_with_rem % NS_IN_MS;
+
+    let last_tick = match ms_elapsed {
+        0 => last_tick,
+        _ => now,
+    };
+    MillisecondCountResult {
+        last_tick,
+        ms_elapsed,
+        ms_remainder_in_ns,
+    }
+}
+
+#[test]
+fn ms_counts_0_elapsed_correctly() {
+    use std::time::Duration;
+    let last_tick = Instant::now();
+    let now = last_tick + Duration::from_nanos(999999);
+    let result = count_ms_elapsed(last_tick, now, 0);
+    assert_eq!(0, result.ms_elapsed);
+    assert_eq!(last_tick, result.last_tick);
+    assert_eq!(999999, result.ms_remainder_in_ns);
+}
+
+#[test]
+fn ms_counts_1_elapsed_correctly() {
+    use std::time::Duration;
+    let last_tick = Instant::now();
+    let now = last_tick + Duration::from_nanos(1234567);
+    let result = count_ms_elapsed(last_tick, now, 0);
+    assert_eq!(1, result.ms_elapsed);
+    assert_eq!(now, result.last_tick);
+    assert_eq!(234567, result.ms_remainder_in_ns);
+}
+
+#[test]
+fn ms_counts_1_then_2_elapsed_correctly() {
+    use std::time::Duration;
+    let last_tick = Instant::now();
+    let now = last_tick + Duration::from_micros(1750);
+    let result = count_ms_elapsed(last_tick, now, 0);
+    assert_eq!(1, result.ms_elapsed);
+    assert_eq!(now, result.last_tick);
+    assert_eq!(750000, result.ms_remainder_in_ns);
+    let last_tick = result.last_tick;
+    let now = last_tick + Duration::from_micros(1750);
+    let result = count_ms_elapsed(last_tick, now, result.ms_remainder_in_ns);
+    assert_eq!(2, result.ms_elapsed);
+    assert_eq!(now, result.last_tick);
+    assert_eq!(500000, result.ms_remainder_in_ns);
+}
diff --git a/src/kanata/mod.rs b/src/kanata/mod.rs
index 5fe719911..d9e5d00da 100644
--- a/src/kanata/mod.rs
+++ b/src/kanata/mod.rs
@@ -1,28 +1,107 @@
 //! Implements the glue between OS input/output and keyberon state management.
 
-use anyhow::{anyhow, bail, Result};
+#[cfg(all(target_os = "windows", feature = "gui"))]
+use crate::gui::win::*;
+use anyhow::{Result, bail};
+use kanata_parser::sequences::*;
 use log::{error, info};
 use parking_lot::Mutex;
-use std::sync::mpsc::{Receiver, Sender, TryRecvError};
+use std::sync::mpsc::{Receiver, SyncSender as Sender, TryRecvError};
+
+/// Reorders events so modifiers are processed first on press, last on release.
+fn collect_and_sort_events(
+    first_event: KeyEvent,
+    rx: &Receiver<KeyEvent>,
+    events: &mut Vec<KeyEvent>,
+) {
+    events.clear();
+    events.push(first_event);
+    while let Ok(ev) = rx.try_recv() {
+        events.push(ev);
+    }
+    if events.len() > 1 {
+        log::debug!("collected {} events, reordering", events.len());
+        events.sort_by(|a, b| {
+            let a_is_mod = a.code.is_modifier();
+            let b_is_mod = b.code.is_modifier();
+            // Same modifier status: preserve original order
+            if a_is_mod == b_is_mod {
+                return std::cmp::Ordering::Equal;
+            }
+            let a_is_press = matches!(a.value, KeyValue::Press | KeyValue::Repeat);
+            let b_is_press = matches!(b.value, KeyValue::Press | KeyValue::Repeat);
+            // Different event types (press vs release): preserve original order
+            // to maintain valid total ordering
+            if a_is_press != b_is_press {
+                return std::cmp::Ordering::Equal;
+            }
+            // Same event type, different modifier status: reorder
+            if a_is_press {
+                // Press/Repeat: modifiers first
+                if a_is_mod {
+                    std::cmp::Ordering::Less
+                } else {
+                    std::cmp::Ordering::Greater
+                }
+            } else {
+                // Release: modifiers last
+                if a_is_mod {
+                    std::cmp::Ordering::Greater
+                } else {
+                    std::cmp::Ordering::Less
+                }
+            }
+        });
+        log::debug!("reordered: {:?}", events);
+    }
+}
 
+#[cfg(any(
+    feature = "passthru_ahk",
+    all(feature = "simulated_input", feature = "simulated_output")
+))]
+use std::sync::mpsc::Sender as ASender;
+
+use kanata_keyberon::action::ReleasableState;
 use kanata_keyberon::key_code::*;
-use kanata_keyberon::layout::*;
+use kanata_keyberon::layout::{CustomEvent, Event, Layout, State};
 
-use std::collections::VecDeque;
-use std::io::Write;
-use std::net::TcpStream;
 use std::path::PathBuf;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering::SeqCst};
 use std::sync::Arc;
 use std::time;
 
-use crate::oskbd::*;
-use crate::tcp_server::ServerMessage;
+#[cfg(feature = "tcp_server")]
+use crate::SocketAddrWrapper;
 use crate::ValidatedArgs;
+use crate::oskbd::{KeyEvent, *};
+#[cfg(feature = "tcp_server")]
+use crate::tcp_server::simple_sexpr_to_json_array;
 use kanata_parser::cfg;
+use kanata_parser::cfg::list_actions::*;
 use kanata_parser::cfg::*;
 use kanata_parser::custom_action::*;
-use kanata_parser::keys::*;
+pub use kanata_parser::keys::*;
+use kanata_tcp_protocol::ServerMessage;
+
+mod clipboard;
+use clipboard::*;
+
+mod dynamic_macro;
+use dynamic_macro::*;
+
+mod key_repeat;
+
+mod millisecond_counting;
+pub use millisecond_counting::*;
+
+mod scroll;
+use scroll::*;
+
+mod sequences;
+use sequences::*;
+
+pub mod cfg_forced;
+use cfg_forced::*;
 
 #[cfg(feature = "cmd")]
 mod cmd;
@@ -34,10 +113,17 @@ mod windows;
 #[cfg(target_os = "windows")]
 pub use windows::*;
 
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "android"))]
 mod linux;
-#[cfg(target_os = "linux")]
-pub use linux::*;
+
+#[cfg(target_os = "macos")]
+mod macos;
+
+mod output_logic;
+use output_logic::*;
+
+#[cfg(target_os = "unknown")]
+mod unknown;
 
 mod caps_word;
 pub use caps_word::*;
@@ -45,12 +131,19 @@ pub use caps_word::*;
 type HashSet<T> = rustc_hash::FxHashSet<T>;
 type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub enum DynamicMacroItem {
-    Press(OsCode),
-    Release(OsCode),
-    EndMacro(u16),
-}
+/// State of pressed keys on the physical keyboard.
+///
+/// Notably this is not what keys kanata is outputting as pressed.
+#[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+pub(crate) static PRESSED_KEYS: Lazy<Mutex<HashSet<OsCode>>> =
+    Lazy::new(|| Mutex::new(HashSet::default()));
+#[cfg(all(target_os = "windows", not(feature = "interception_driver")))]
+pub(crate) static PRESSED_KEYS: Lazy<Mutex<HashMap<OsCode, web_time::Instant>>> =
+    Lazy::new(|| Mutex::new(HashMap::default()));
+
+/// Exit code to use when emergency exit (LCtrl+Space+Escape) is triggered.
+/// Configurable via --emergency-exit-code CLI argument. Default is 0.
+pub static EMERGENCY_EXIT_CODE: std::sync::atomic::AtomicI32 = std::sync::atomic::AtomicI32::new(0);
 
 pub struct Kanata {
     /// Handle to some OS keyboard output mechanism.
@@ -60,14 +153,17 @@ pub struct Kanata {
     /// Index into `cfg_paths`, used to know which file to live reload. Changes when cycling
     /// through the configuration files.
     pub cur_cfg_idx: usize,
+    /// Files included via (include "path") in the configuration.
     /// The potential key outputs of every key input. Used for managing key repeat.
     pub key_outputs: cfg::KeyOutputs,
     /// Handle to the keyberon library layout.
     pub layout: cfg::KanataLayout,
     /// Reusable vec (to save on allocations) that stores the currently active output keys.
+    /// This can be cleared and reused in various procedures as buffer space.
     pub cur_keys: Vec<KeyCode>,
     /// Reusable vec (to save on allocations) that stores the active output keys from the previous
-    /// tick.
+    /// tick. This must only be updated once per tick and must not be modified outside of the one
+    /// procedure that updates it.
     pub prev_keys: Vec<KeyCode>,
     /// Used for printing layer info to the info log when changing layers.
     pub layer_info: Vec<LayerInfo>,
@@ -85,23 +181,27 @@ pub struct Kanata {
     /// Horizontal mouse movement state. Is Some(...) when horizontal mouse movement is active and
     /// None otherwise.
     pub move_mouse_state_horizontal: Option<MoveMouseState>,
-    /// The number of ticks defined in the user configuration for sequence timeout.
-    pub sequence_timeout: u16,
+    /// A list of mouse speed modifiers in percentages by which mouse travel distance is scaled.
+    pub move_mouse_speed_modifiers: Vec<u16>,
     /// The user configuration for backtracking to find valid sequences. See
     /// <../../docs/sequence-adding-chords-ideas.md> for more info.
     pub sequence_backtrack_modcancel: bool,
+    /// The user configuration for sequences be permanently on.
+    pub sequence_always_on: bool,
+    /// Default sequence input mode for use with always-on.
+    pub sequence_input_mode: SequenceInputMode,
+    /// Default sequence timeout for use with always-on.
+    pub sequence_timeout: u16,
     /// Tracks sequence progress. Is Some(...) when in sequence mode and None otherwise.
-    pub sequence_state: Option<SequenceState>,
+    pub sequence_state: SequenceState,
     /// Valid sequences defined in the user configuration.
     pub sequences: cfg::KeySeqsToFKeys,
-    /// Stores the user configuration for the sequence input mode.
-    pub sequence_input_mode: SequenceInputMode,
     /// Stores the user recored dynamic macros.
     pub dynamic_macros: HashMap<u16, Vec<DynamicMacroItem>>,
     /// Tracks the progress of an active dynamic macro. Is Some(...) when a dynamic macro is being
     /// replayed and None otherwise.
     pub dynamic_macro_replay_state: Option<DynamicMacroReplayState>,
-    /// Tracks the the inputs for a dynamic macro recording. Is Some(...) when a dynamic macro is
+    /// Tracks the inputs for a dynamic macro recording. Is Some(...) when a dynamic macro is
     /// being recorded and None otherwise.
     pub dynamic_macro_record_state: Option<DynamicMacroRecordState>,
     /// Global overrides defined in the user configuration.
@@ -111,40 +211,156 @@ pub struct Kanata {
     pub override_states: OverrideStates,
     /// Time of the last tick to know how many tick iterations to run, to achieve a 1ms tick
     /// interval more closely.
-    last_tick: time::Instant,
+    last_tick: web_time::Instant,
     /// Tracks the non-whole-millisecond gaps between ticks to know when to do another tick
     /// iteration without sleeping, to achive a 1ms tick interval more closely.
     time_remainder: u128,
     /// Is true if a live reload was requested by the user and false otherwise.
     live_reload_requested: bool,
-    #[cfg(target_os = "linux")]
+    #[cfg(any(target_os = "linux", target_os = "android"))]
     /// Linux input paths in the user configuration.
     pub kbd_in_paths: Vec<String>,
-    #[cfg(target_os = "linux")]
-    /// Tracks the Linux user configuration to continue or abort if no devices are found.
+    #[cfg(any(target_os = "linux", target_os = "android", target_os = "macos"))]
+    /// Tracks the user configuration to continue or abort if no devices are found.
     continue_if_no_devices: bool,
-    #[cfg(target_os = "linux")]
-    /// Tracks the Linux user configuration for device names (instead of paths) that should be
+    #[cfg(any(target_os = "linux", target_os = "android", target_os = "macos"))]
+    /// Tracks the Linux/Macos user configuration for device names (instead of paths) that should be
     /// included for interception and processing by kanata.
     pub include_names: Option<Vec<String>>,
-    #[cfg(target_os = "linux")]
-    /// Tracks the Linux user configuration for device names (instead of paths) that should be
+    #[cfg(any(target_os = "linux", target_os = "android", target_os = "macos"))]
+    /// Tracks the Linux/Macos user configuration for device names (instead of paths) that should be
     /// excluded for interception and processing by kanata.
     pub exclude_names: Option<Vec<String>>,
+    /// Device ID mappings from `definputdevices` configuration block.
+    pub input_devices: Option<Vec<(std::num::NonZeroU8, kanata_parser::cfg::InputDeviceMatcher)>>,
+    #[cfg(target_os = "windows")]
+    /// Tracks whether Kanata should try to synchronize keystates with the Windows OS.
+    /// Has no effect on Interception. Fixes some use cases related to admin window permissions and
+    /// potentially locking via Win+L.
+    pub windows_sync_keystates: bool,
     #[cfg(all(feature = "interception_driver", target_os = "windows"))]
     /// Used to know which input device to treat as a mouse for intercepting and processing inputs
     /// by kanata.
-    intercept_mouse_hwid: Option<Vec<u8>>,
+    intercept_mouse_hwids: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+    /// Used to know which mouse input devices to exclude from processing inputs by kanata. This is
+    /// mutually exclusive from `intercept_mouse_hwids` and kanata will panic if both are included.
+    intercept_mouse_hwids_exclude: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+    /// Used to know which input device to treat as a keyboard for intercepting and processing inputs
+    /// by kanata.
+    intercept_kb_hwids: Option<Vec<[u8; HWID_ARR_SZ]>>,
+    #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+    /// Used to know which keyboard input devices to exclude from processing inputs by kanata. This
+    /// is mutually exclusive from `intercept_kb_hwids` and kanata will panic if both are included.
+    intercept_kb_hwids_exclude: Option<Vec<[u8; HWID_ARR_SZ]>>,
     /// User configuration to do logging of layer changes or not.
     log_layer_changes: bool,
     /// Tracks the caps-word state. Is Some(...) if caps-word is active and None otherwise.
     pub caps_word: Option<CapsWordState>,
+    /// Config items from `defcfg`.
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub x11_repeat_rate: Option<KeyRepeatSettings>,
+    /// Determines what types of devices to grab based on autodetection mode.
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub device_detect_mode: DeviceDetectMode,
+    /// Fake key actions that are waiting for a certain duration of kanata idling.
+    pub waiting_for_idle: HashSet<FakeKeyOnIdle>,
+    /// Fake key actions that are waiting for a certain duration of physical keyboard idling,
+    /// as opposed to `waiting_for_idle`, for which non-idling is extended by ongoing kanata state
+    /// processing, such as `caps_word` or `one_shot` terminations.
+    pub waiting_for_physical_idle: HashSet<FakeKeyOnIdle>,
+    /// Fake key actions that are being held and are pending release.
+    /// The key is the coordinate and the value is the number of ticks until release should be
+    /// done.
+    pub vkeys_pending_release: HashMap<Coord, u16>,
+    /// Number of ticks since kanata was idle.
+    pub ticks_since_idle: u16,
+    /// Number of ticks since physical keyboards were all idle.
+    pub ticks_since_physical_idle: u16,
+    /// If a mousemove action is active and another mousemove action is activated,
+    /// reuse the acceleration state.
+    movemouse_inherit_accel_state: bool,
+    /// Removes jaggedneess of vertical and horizontal mouse movements when used
+    /// simultaneously at the cost of increased mousemove actions latency.
+    movemouse_smooth_diagonals: bool,
+    /// If movemouse_smooth_diagonals is enabled, the previous mouse actions
+    /// gets stored in this buffer and if the next movemouse action is opposite axis
+    /// than the one stored in the buffer, both events are outputted at the same time.
+    movemouse_buffer: Option<(Axis, CalculatedMouseMove)>,
+    override_release_on_activation: bool,
+    /// Configured maximum for dynamic macro recording, to protect users from themselves if they
+    /// have accidentally left it on.
+    dynamic_macro_max_presses: u16,
+    /// Determines behaviour of replayed dynamic macros.
+    dynamic_macro_replay_behaviour: ReplayBehaviour,
+    /// Keys that should be unmodded. If non-empty, any modifier should be cleared.
+    unmodded_keys: Vec<KeyCode>,
+    /// Modifiers to be cleared in case the above is non-empty.
+    unmodded_mods: UnmodMods,
+    /// Keys that should be unshifted. If non-empty, left+right shift keys should be cleared.
+    unshifted_keys: Vec<KeyCode>,
+    /// Keep track of last pressed key for [`CustomAction::Repeat`].
+    last_pressed_key: KeyCode,
+    /// Names of fake keys mapped to their index in the fake keys row
+    pub virtual_keys: HashMap<String, usize>,
+    /// The maximum value of the any time-dependent check in the configuration.
+    pub max_key_timing_check: u16,
+    #[cfg(feature = "tcp_server")]
+    tcp_server_address: Option<SocketAddrWrapper>,
+    #[cfg(all(target_os = "windows", feature = "gui"))]
+    /// Various GUI-related options.
+    pub gui_opts: CfgOptionsGui,
+    pub allow_hardware_repeat: bool,
+    /// When > 0, it means macros should be cancelled on the next press.
+    /// Upon cancelling this should be set to 0.
+    pub macro_on_press_cancel_duration: u32,
+    /// Stores user's saved clipboard contents.
+    pub saved_clipboard_content: SavedClipboardData,
+    // if set, key taps of this code are sent whenever mouse movement events are passed through
+    #[cfg(any(
+        all(target_os = "windows", feature = "interception_driver"),
+        target_os = "linux",
+        target_os = "android",
+        target_os = "macos",
+        target_os = "unknown"
+    ))]
+    pub(crate) mouse_movement_key: Arc<Mutex<Option<OsCode>>>,
+    /// Time when kanata started (for uptime tracking)
+    #[cfg(feature = "tcp_server")]
+    start_time: web_time::Instant,
+    /// Whether last reload was successful
+    #[cfg(feature = "tcp_server")]
+    last_reload_ok: bool,
 }
 
-pub struct ScrollState {
-    pub direction: MWheelDirection,
-    pub interval: u16,
-    pub ticks_until_scroll: u16,
+#[derive(PartialEq, Clone, Copy)]
+pub enum Axis {
+    Vertical,
+    Horizontal,
+}
+
+impl From<MoveDirection> for Axis {
+    fn from(val: MoveDirection) -> Axis {
+        match val {
+            MoveDirection::Up | MoveDirection::Down => Axis::Vertical,
+            MoveDirection::Left | MoveDirection::Right => Axis::Horizontal,
+        }
+    }
+}
+
+/// Represents reload actions that need to be processed after releasing borrows
+enum ReloadAction {
+    Reload,
+    ReloadNext,
+    ReloadPrev,
+    ReloadNum(usize),
+    ReloadFile(String),
+}
+
+#[derive(Clone, Copy)]
+pub struct CalculatedMouseMove {
+    pub direction: MoveDirection,
     pub distance: u16,
 }
 
@@ -156,6 +372,7 @@ pub struct MoveMouseState {
     pub move_mouse_accel_state: Option<MoveMouseAccelState>,
 }
 
+#[derive(Clone, Copy)]
 pub struct MoveMouseAccelState {
     pub accel_ticks_from_min: u16,
     pub accel_ticks_until_max: u16,
@@ -164,84 +381,14 @@ pub struct MoveMouseAccelState {
     pub max_distance: u16,
 }
 
-pub struct SequenceState {
-    pub sequence: Vec<u16>,
-    pub ticks_until_timeout: u16,
-}
-
-/// This controls the behaviour of kanata when sequence mode is initiated by the sequence leader
-/// action.
-///
-/// - `HiddenSuppressed` hides the keys typed as part of the sequence and does not output the keys
-///   typed when an invalid sequence is the result of an invalid sequence character or a timeout.
-/// - `HiddenDelayType` hides the keys typed as part of the sequence and outputs the keys when an
-///   typed when an invalid sequence is the result of an invalid sequence character or a timeout.
-/// - `VisibleBackspaced` will type the keys that are typed as part of the sequence but will
-///   backspace the typed sequence keys before performing the fake key tap when a valid sequence is
-///   the result.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub enum SequenceInputMode {
-    HiddenSuppressed,
-    HiddenDelayType,
-    VisibleBackspaced,
-}
-
-const SEQ_INPUT_MODE_CFG_NAME: &str = "sequence-input-mode";
-const SEQ_VISIBLE_BACKSPACED: &str = "visible-backspaced";
-const SEQ_HIDDEN_SUPPRESSED: &str = "hidden-suppressed";
-const SEQ_HIDDEN_DELAY_TYPE: &str = "hidden-delay-type";
-
-impl SequenceInputMode {
-    fn try_from_str(s: &str) -> Result<Self> {
-        match s {
-            SEQ_VISIBLE_BACKSPACED => Ok(SequenceInputMode::VisibleBackspaced),
-            SEQ_HIDDEN_SUPPRESSED => Ok(SequenceInputMode::HiddenSuppressed),
-            SEQ_HIDDEN_DELAY_TYPE => Ok(SequenceInputMode::HiddenDelayType),
-            _ => Err(anyhow!("{SEQ_INPUT_MODE_CFG_NAME} mode must be one of: {SEQ_VISIBLE_BACKSPACED}, {SEQ_HIDDEN_SUPPRESSED}, {SEQ_HIDDEN_DELAY_TYPE}"))
-        }
-    }
-}
-
-pub struct DynamicMacroReplayState {
-    pub active_macros: HashSet<u16>,
-    pub delay_remaining: u16,
-    pub macro_items: VecDeque<DynamicMacroItem>,
-}
-
-pub struct DynamicMacroRecordState {
-    pub starting_macro_id: u16,
-    pub macro_items: Vec<DynamicMacroItem>,
-}
-
-impl DynamicMacroRecordState {
-    fn add_release_for_all_unreleased_presses(&mut self) {
-        let mut pressed_oscs = HashSet::default();
-        for item in self.macro_items.iter() {
-            match item {
-                DynamicMacroItem::Press(osc) => pressed_oscs.insert(*osc),
-                DynamicMacroItem::Release(osc) => pressed_oscs.remove(osc),
-                DynamicMacroItem::EndMacro(_) => false,
-            };
-        }
-        // Hopefully release order doesn't matter here since a HashSet is being used
-        for osc in pressed_oscs.into_iter() {
-            self.macro_items.push(DynamicMacroItem::Release(osc));
-        }
-    }
-}
-
-static LAST_PRESSED_KEY: AtomicU32 = AtomicU32::new(0);
-
-const SEQUENCE_TIMEOUT_ERR: &str = "sequence-timeout should be a number (1-65535)";
-const SEQUENCE_TIMEOUT_DEFAULT: u16 = 1000;
-
 use once_cell::sync::Lazy;
 
-static MAPPED_KEYS: Lazy<Mutex<cfg::MappedKeys>> =
+pub(crate) static MAPPED_KEYS: Lazy<Mutex<cfg::MappedKeys>> =
     Lazy::new(|| Mutex::new(cfg::MappedKeys::default()));
 
+const LINUX_PERMISSIONS_ERROR: &str = "Failed to open the output uinput device. Make sure you added the user executing kanata to the 'uinput' group and that the 'uinput' group is configured correctly.\nSee for more detail: https://github.com/jtroo/kanata/blob/main/docs/setup-linux.md";
+
 impl Kanata {
-    /// Create a new configuration from a file.
     pub fn new(args: &ValidatedArgs) -> Result<Self> {
         let cfg = match cfg::new_from_file(&args.paths[0]) {
             Ok(c) => c,
@@ -251,55 +398,27 @@ impl Kanata {
             }
         };
 
-        #[cfg(all(feature = "interception_driver", target_os = "windows"))]
-        let intercept_mouse_hwid = cfg
-            .items
-            .get("windows-interception-mouse-hwid")
-            .map(|hwid: &String| {
-                log::trace!("win hwid: {hwid}");
-                hwid.split_whitespace()
-                    .try_fold(vec![], |mut hwid_bytes, hwid_byte| {
-                        hwid_byte.trim_matches(',').parse::<u8>().map(|b| {
-                            hwid_bytes.push(b);
-                            hwid_bytes
-                        })
-                    })
-                    .ok()
-            })
-            .unwrap_or_default();
-
         let kbd_out = match KbdOut::new(
-            #[cfg(target_os = "linux")]
+            #[cfg(any(target_os = "linux", target_os = "android"))]
             &args.symlink_path,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            cfg.options.linux_opts.linux_use_trackpoint_property,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            &cfg.options.linux_opts.linux_output_name,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            match cfg.options.linux_opts.linux_output_bus_type {
+                LinuxCfgOutputBusType::BusUsb => evdev::BusType::BUS_USB,
+                LinuxCfgOutputBusType::BusI8042 => evdev::BusType::BUS_I8042,
+                LinuxCfgOutputBusType::BusVirtual => evdev::BusType::BUS_VIRTUAL,
+            },
         ) {
             Ok(kbd_out) => kbd_out,
             Err(err) => {
-                error!("Failed to open the output uinput device. Make sure you've added kanata to the `uinput` group");
+                error!("{LINUX_PERMISSIONS_ERROR}");
                 bail!(err)
             }
         };
 
-        #[cfg(target_os = "linux")]
-        let kbd_in_paths = cfg
-            .items
-            .get("linux-dev")
-            .cloned()
-            .map(|paths| parse_colon_separated_text(&paths))
-            .unwrap_or_default();
-        #[cfg(target_os = "linux")]
-        let include_names = cfg
-            .items
-            .get("linux-dev-names-include")
-            .cloned()
-            .map(|paths| parse_colon_separated_text(&paths));
-        #[cfg(target_os = "linux")]
-        let exclude_names = cfg
-            .items
-            .get("linux-dev-names-exclude")
-            .cloned()
-            .map(|paths| parse_colon_separated_text(&paths));
-        Kanata::set_repeat_rate(&cfg.items)?;
-
         #[cfg(target_os = "windows")]
         unsafe {
             log::info!("Asking Windows to improve timer precision");
@@ -313,38 +432,20 @@ impl Kanata {
             log::info!("Asking Windows to increase process priority");
             winapi::um::processthreadsapi::SetPriorityClass(
                 winapi::um::processthreadsapi::GetCurrentProcess(),
-                winapi::um::winbase::HIGH_PRIORITY_CLASS,
+                winapi::um::winbase::REALTIME_PRIORITY_CLASS,
             );
         }
 
-        update_kbd_out(&cfg.items, &kbd_out)?;
-        set_altgr_behaviour(&cfg)?;
+        update_kbd_out(&cfg.options, &kbd_out)?;
 
-        let sequence_timeout = cfg
-            .items
-            .get("sequence-timeout")
-            .map(|s| match str::parse::<u16>(s) {
-                Ok(0) | Err(_) => Err(anyhow!("{SEQUENCE_TIMEOUT_ERR}")),
-                Ok(t) => Ok(t),
-            })
-            .unwrap_or(Ok(SEQUENCE_TIMEOUT_DEFAULT))?;
-        let sequence_backtrack_modcancel = cfg
-            .items
-            .get("sequence-backtrack-modcancel")
-            .map(|s| !FALSE_VALUES.contains(&s.to_lowercase().as_str()))
-            .unwrap_or(true);
-        let sequence_input_mode = cfg
-            .items
-            .get(SEQ_INPUT_MODE_CFG_NAME)
-            .map(|s| SequenceInputMode::try_from_str(s.as_str()))
-            .unwrap_or(Ok(SequenceInputMode::HiddenSuppressed))?;
-        let log_layer_changes = cfg
-            .items
-            .get("log-layer-changes")
-            .map(|s| !FALSE_VALUES.contains(&s.to_lowercase().as_str()))
-            .unwrap_or(true);
+        #[cfg(target_os = "windows")]
+        set_win_altgr_behaviour(cfg.options.windows_opts.windows_altgr);
 
         *MAPPED_KEYS.lock() = cfg.mapped_keys;
+        #[cfg(feature = "zippychord")]
+        {
+            zch().zch_configure(cfg.zippy.unwrap_or_default());
+        }
 
         Ok(Self {
             kbd_out,
@@ -360,35 +461,103 @@ impl Kanata {
             hscroll_state: None,
             move_mouse_state_vertical: None,
             move_mouse_state_horizontal: None,
-            sequence_timeout,
-            sequence_backtrack_modcancel,
-            sequence_state: None,
+            move_mouse_speed_modifiers: Vec::new(),
+            sequence_backtrack_modcancel: cfg.options.sequence_backtrack_modcancel,
+            sequence_always_on: cfg.options.sequence_always_on,
+            sequence_input_mode: cfg.options.sequence_input_mode,
+            sequence_timeout: cfg.options.sequence_timeout,
+            sequence_state: SequenceState::new(),
             sequences: cfg.sequences,
-            sequence_input_mode,
-            last_tick: time::Instant::now(),
+            last_tick: web_time::Instant::now(),
             time_remainder: 0,
             live_reload_requested: false,
             overrides: cfg.overrides,
             override_states: OverrideStates::new(),
-            #[cfg(target_os = "linux")]
-            kbd_in_paths,
-            #[cfg(target_os = "linux")]
-            continue_if_no_devices: cfg
-                .items
-                .get("linux-continue-if-no-devs-found")
-                .map(|s| TRUE_VALUES.contains(&s.to_lowercase().as_str()))
-                .unwrap_or_default(),
-            #[cfg(target_os = "linux")]
-            include_names,
-            #[cfg(target_os = "linux")]
-            exclude_names,
+            #[cfg(target_os = "macos")]
+            include_names: cfg.options.macos_opts.macos_dev_names_include,
+            #[cfg(target_os = "macos")]
+            exclude_names: cfg.options.macos_opts.macos_dev_names_exclude,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            kbd_in_paths: cfg.options.linux_opts.linux_dev,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            continue_if_no_devices: cfg.options.linux_opts.linux_continue_if_no_devs_found,
+            #[cfg(target_os = "macos")]
+            continue_if_no_devices: cfg.options.macos_opts.macos_continue_if_no_devs_found,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            include_names: cfg.options.linux_opts.linux_dev_names_include,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            exclude_names: cfg.options.linux_opts.linux_dev_names_exclude,
+            #[cfg(target_os = "windows")]
+            windows_sync_keystates: cfg.options.windows_opts.sync_keystates,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_mouse_hwids: cfg.options.wintercept_opts.windows_interception_mouse_hwids,
             #[cfg(all(feature = "interception_driver", target_os = "windows"))]
-            intercept_mouse_hwid,
+            intercept_mouse_hwids_exclude: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_mouse_hwids_exclude,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_kb_hwids: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_keyboard_hwids,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_kb_hwids_exclude: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_keyboard_hwids_exclude,
             dynamic_macro_replay_state: None,
             dynamic_macro_record_state: None,
             dynamic_macros: Default::default(),
-            log_layer_changes,
+            log_layer_changes: get_forced_log_layer_changes()
+                .unwrap_or(cfg.options.log_layer_changes),
             caps_word: None,
+            movemouse_smooth_diagonals: cfg.options.movemouse_smooth_diagonals,
+            override_release_on_activation: cfg.options.override_release_on_activation,
+            movemouse_inherit_accel_state: cfg.options.movemouse_inherit_accel_state,
+            dynamic_macro_max_presses: cfg.options.dynamic_macro_max_presses,
+            dynamic_macro_replay_behaviour: ReplayBehaviour {
+                delay: cfg.options.dynamic_macro_replay_delay_behaviour,
+            },
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            x11_repeat_rate: cfg.options.linux_opts.linux_x11_repeat_delay_rate,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            device_detect_mode: cfg
+                .options
+                .linux_opts
+                .linux_device_detect_mode
+                .expect("parser should default to some"),
+            waiting_for_idle: HashSet::default(),
+            waiting_for_physical_idle: HashSet::default(),
+            vkeys_pending_release: HashMap::default(),
+            ticks_since_idle: 0,
+            ticks_since_physical_idle: 0,
+            movemouse_buffer: None,
+            unmodded_keys: vec![],
+            unmodded_mods: UnmodMods::empty(),
+            unshifted_keys: vec![],
+            last_pressed_key: KeyCode::No,
+            virtual_keys: cfg.fake_keys,
+            max_key_timing_check: cfg.max_key_timing_check,
+            input_devices: cfg.input_devices,
+            #[cfg(feature = "tcp_server")]
+            tcp_server_address: args.tcp_server_address.clone(),
+            #[cfg(all(target_os = "windows", feature = "gui"))]
+            gui_opts: cfg.options.gui_opts,
+            allow_hardware_repeat: cfg.options.allow_hardware_repeat,
+            macro_on_press_cancel_duration: 0,
+            saved_clipboard_content: Default::default(),
+            #[cfg(any(
+                all(target_os = "windows", feature = "interception_driver"),
+                any(target_os = "linux", target_os = "android"),
+                target_os = "macos",
+                target_os = "unknown"
+            ))]
+            mouse_movement_key: Arc::new(Mutex::new(cfg.options.mouse_movement_key)),
+            #[cfg(feature = "tcp_server")]
+            start_time: web_time::Instant::now(),
+            #[cfg(feature = "tcp_server")]
+            last_reload_ok: true,
         })
     }
 
@@ -397,184 +566,600 @@ impl Kanata {
         Ok(Arc::new(Mutex::new(Self::new(args)?)))
     }
 
-    fn do_live_reload(&mut self) -> Result<()> {
+    pub fn new_from_str(cfg: &str, file_content: HashMap<String, String>) -> Result<Self> {
+        let cfg = match cfg::new_from_str(cfg, file_content) {
+            Ok(c) => c,
+            Err(e) => {
+                bail!("{e:?}");
+            }
+        };
+
+        let kbd_out = match KbdOut::new(
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            &None,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            cfg.options.linux_opts.linux_use_trackpoint_property,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            &cfg.options.linux_opts.linux_output_name,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            match cfg.options.linux_opts.linux_output_bus_type {
+                LinuxCfgOutputBusType::BusUsb => evdev::BusType::BUS_USB,
+                LinuxCfgOutputBusType::BusI8042 => evdev::BusType::BUS_I8042,
+                LinuxCfgOutputBusType::BusVirtual => evdev::BusType::BUS_VIRTUAL,
+            },
+        ) {
+            Ok(kbd_out) => kbd_out,
+            Err(err) => {
+                error!("{LINUX_PERMISSIONS_ERROR}");
+                bail!(err)
+            }
+        };
+
+        *MAPPED_KEYS.lock() = cfg.mapped_keys;
+        #[cfg(feature = "zippychord")]
+        {
+            zch().zch_configure(cfg.zippy.unwrap_or_default());
+        }
+
+        Ok(Self {
+            kbd_out,
+            cfg_paths: vec!["config string".into()],
+            cur_cfg_idx: 0,
+            key_outputs: cfg.key_outputs,
+            layout: cfg.layout,
+            layer_info: cfg.layer_info,
+            cur_keys: Vec::new(),
+            prev_keys: Vec::new(),
+            prev_layer: 0,
+            scroll_state: None,
+            hscroll_state: None,
+            move_mouse_state_vertical: None,
+            move_mouse_state_horizontal: None,
+            move_mouse_speed_modifiers: Vec::new(),
+            sequence_backtrack_modcancel: cfg.options.sequence_backtrack_modcancel,
+            sequence_always_on: cfg.options.sequence_always_on,
+            sequence_input_mode: cfg.options.sequence_input_mode,
+            sequence_timeout: cfg.options.sequence_timeout,
+            sequence_state: SequenceState::new(),
+            sequences: cfg.sequences,
+            last_tick: web_time::Instant::now(),
+            time_remainder: 0,
+            live_reload_requested: false,
+            overrides: cfg.overrides,
+            override_states: OverrideStates::new(),
+            #[cfg(target_os = "macos")]
+            include_names: cfg.options.macos_opts.macos_dev_names_include,
+            #[cfg(target_os = "macos")]
+            exclude_names: cfg.options.macos_opts.macos_dev_names_exclude,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            kbd_in_paths: cfg.options.linux_opts.linux_dev,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            continue_if_no_devices: cfg.options.linux_opts.linux_continue_if_no_devs_found,
+            #[cfg(target_os = "macos")]
+            continue_if_no_devices: cfg.options.macos_opts.macos_continue_if_no_devs_found,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            include_names: cfg.options.linux_opts.linux_dev_names_include,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            exclude_names: cfg.options.linux_opts.linux_dev_names_exclude,
+            #[cfg(target_os = "windows")]
+            windows_sync_keystates: cfg.options.windows_opts.sync_keystates,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_mouse_hwids: cfg.options.wintercept_opts.windows_interception_mouse_hwids,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_mouse_hwids_exclude: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_mouse_hwids_exclude,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_kb_hwids: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_keyboard_hwids,
+            #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+            intercept_kb_hwids_exclude: cfg
+                .options
+                .wintercept_opts
+                .windows_interception_keyboard_hwids_exclude,
+            dynamic_macro_replay_state: None,
+            dynamic_macro_record_state: None,
+            dynamic_macros: Default::default(),
+            log_layer_changes: get_forced_log_layer_changes()
+                .unwrap_or(cfg.options.log_layer_changes),
+            caps_word: None,
+            movemouse_smooth_diagonals: cfg.options.movemouse_smooth_diagonals,
+            override_release_on_activation: cfg.options.override_release_on_activation,
+            movemouse_inherit_accel_state: cfg.options.movemouse_inherit_accel_state,
+            dynamic_macro_max_presses: cfg.options.dynamic_macro_max_presses,
+            dynamic_macro_replay_behaviour: ReplayBehaviour {
+                delay: cfg.options.dynamic_macro_replay_delay_behaviour,
+            },
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            x11_repeat_rate: cfg.options.linux_opts.linux_x11_repeat_delay_rate,
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            device_detect_mode: cfg
+                .options
+                .linux_opts
+                .linux_device_detect_mode
+                .expect("parser should default to some"),
+            waiting_for_idle: HashSet::default(),
+            waiting_for_physical_idle: HashSet::default(),
+            vkeys_pending_release: HashMap::default(),
+            ticks_since_idle: 0,
+            ticks_since_physical_idle: 0,
+            movemouse_buffer: None,
+            unmodded_keys: vec![],
+            unmodded_mods: UnmodMods::empty(),
+            unshifted_keys: vec![],
+            last_pressed_key: KeyCode::No,
+            virtual_keys: cfg.fake_keys,
+            max_key_timing_check: cfg.max_key_timing_check,
+            input_devices: cfg.input_devices,
+            #[cfg(feature = "tcp_server")]
+            tcp_server_address: None,
+            #[cfg(all(target_os = "windows", feature = "gui"))]
+            gui_opts: cfg.options.gui_opts,
+            allow_hardware_repeat: cfg.options.allow_hardware_repeat,
+            macro_on_press_cancel_duration: 0,
+            saved_clipboard_content: Default::default(),
+            #[cfg(any(
+                all(target_os = "windows", feature = "interception_driver"),
+                target_os = "linux",
+                target_os = "android",
+                target_os = "macos",
+                target_os = "unknown"
+            ))]
+            mouse_movement_key: Arc::new(Mutex::new(cfg.options.mouse_movement_key)),
+            #[cfg(feature = "tcp_server")]
+            start_time: web_time::Instant::now(),
+            #[cfg(feature = "tcp_server")]
+            last_reload_ok: true,
+        })
+    }
+
+    #[cfg(any(
+        feature = "passthru_ahk",
+        all(feature = "simulated_input", feature = "simulated_output")
+    ))]
+    pub fn new_with_output_channel(
+        args: &ValidatedArgs,
+        tx: Option<ASender<InputEvent>>,
+    ) -> Result<Arc<Mutex<Self>>> {
+        let mut k = Self::new(args)?;
+        k.kbd_out.tx_kout = tx;
+        Ok(Arc::new(Mutex::new(k)))
+    }
+
+    fn do_live_reload(&mut self, _tx: &Option<Sender<ServerMessage>>) -> Result<()> {
         let cfg = match cfg::new_from_file(&self.cfg_paths[self.cur_cfg_idx]) {
             Ok(c) => c,
             Err(e) => {
                 log::error!("{e:?}");
+                #[cfg(feature = "tcp_server")]
+                {
+                    self.last_reload_ok = false;
+                }
                 bail!("failed to parse config file");
             }
         };
-        update_kbd_out(&cfg.items, &self.kbd_out)?;
-        set_altgr_behaviour(&cfg).map_err(|e| anyhow!("failed to set altgr behaviour {e})"))?;
-        self.sequence_timeout = cfg
-            .items
-            .get("sequence-timeout")
-            .map(|s| match str::parse::<u16>(s) {
-                Ok(0) | Err(_) => Err(anyhow!("{SEQUENCE_TIMEOUT_ERR}")),
-                Ok(t) => Ok(t),
-            })
-            .unwrap_or(Ok(SEQUENCE_TIMEOUT_DEFAULT))?;
-        self.sequence_input_mode = cfg
-            .items
-            .get(SEQ_INPUT_MODE_CFG_NAME)
-            .map(|s| SequenceInputMode::try_from_str(s.as_str()))
-            .unwrap_or(Ok(SequenceInputMode::HiddenSuppressed))?;
-        let log_layer_changes = cfg
-            .items
-            .get("log-layer-changes")
-            .map(|s| !FALSE_VALUES.contains(&s.to_lowercase().as_str()))
-            .unwrap_or(true);
-        self.sequence_backtrack_modcancel = cfg
-            .items
-            .get("sequence-backtrack-modcancel")
-            .map(|s| !FALSE_VALUES.contains(&s.to_lowercase().as_str()))
-            .unwrap_or(true);
+        update_kbd_out(&cfg.options, &self.kbd_out)?;
+        #[cfg(target_os = "windows")]
+        set_win_altgr_behaviour(cfg.options.windows_opts.windows_altgr);
+        self.sequence_backtrack_modcancel = cfg.options.sequence_backtrack_modcancel;
+        self.sequence_always_on = cfg.options.sequence_always_on;
+        self.sequence_input_mode = cfg.options.sequence_input_mode;
+        self.sequence_timeout = cfg.options.sequence_timeout;
         self.layout = cfg.layout;
         self.key_outputs = cfg.key_outputs;
         self.layer_info = cfg.layer_info;
         self.sequences = cfg.sequences;
         self.overrides = cfg.overrides;
-        self.log_layer_changes = log_layer_changes;
+        self.log_layer_changes =
+            get_forced_log_layer_changes().unwrap_or(cfg.options.log_layer_changes);
+        self.movemouse_smooth_diagonals = cfg.options.movemouse_smooth_diagonals;
+        self.override_release_on_activation = cfg.options.override_release_on_activation;
+        self.movemouse_inherit_accel_state = cfg.options.movemouse_inherit_accel_state;
+        self.dynamic_macro_max_presses = cfg.options.dynamic_macro_max_presses;
+        self.dynamic_macro_replay_behaviour = ReplayBehaviour {
+            delay: cfg.options.dynamic_macro_replay_delay_behaviour,
+        };
+        self.max_key_timing_check = cfg.max_key_timing_check;
+        // Note: input_devices is intentionally not updated on live reload.
+        // The KbdIn device_hash_to_id map is built at startup and not rebuilt.
+        // This matches behavior of other device configs (macos-dev-names-include, etc.).
+        // See: https://github.com/malpern/kanata/issues/13
+        self.virtual_keys = cfg.fake_keys;
+        #[cfg(target_os = "windows")]
+        {
+            self.windows_sync_keystates = cfg.options.windows_opts.sync_keystates;
+        }
+        #[cfg(all(target_os = "windows", feature = "gui"))]
+        {
+            self.gui_opts.tray_icon = cfg.options.gui_opts.tray_icon;
+            self.gui_opts.icon_match_layer_name = cfg.options.gui_opts.icon_match_layer_name;
+            self.gui_opts.tooltip_layer_changes = cfg.options.gui_opts.tooltip_layer_changes;
+            self.gui_opts.tooltip_no_base = cfg.options.gui_opts.tooltip_no_base;
+            self.gui_opts.tooltip_show_blank = cfg.options.gui_opts.tooltip_show_blank;
+            self.gui_opts.tooltip_duration = cfg.options.gui_opts.tooltip_duration;
+            self.gui_opts.notify_cfg_reload = cfg.options.gui_opts.notify_cfg_reload;
+            self.gui_opts.notify_cfg_reload_silent = cfg.options.gui_opts.notify_cfg_reload_silent;
+            self.gui_opts.notify_error = cfg.options.gui_opts.notify_error;
+            self.gui_opts.tooltip_size = cfg.options.gui_opts.tooltip_size;
+        }
+        #[cfg(feature = "zippychord")]
+        {
+            zch().zch_configure(cfg.zippy.unwrap_or_default());
+        }
+
         *MAPPED_KEYS.lock() = cfg.mapped_keys;
-        Kanata::set_repeat_rate(&cfg.items)?;
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        Kanata::set_repeat_rate(cfg.options.linux_opts.linux_x11_repeat_delay_rate)?;
+        // The macOS mouse-tap reload hook is invoked further down, *after* the
+        // `mouse_movement_key` mutate, so its install gate sees fresh state
+        // for both `MAPPED_KEYS` and `mouse_movement_key`.
         log::info!("Live reload successful");
+        #[cfg(feature = "tcp_server")]
+        if let Some(tx) = _tx {
+            match tx.try_send(ServerMessage::ConfigFileReload {
+                new: self.cfg_paths[self.cur_cfg_idx]
+                    .to_str()
+                    .unwrap()
+                    .to_string(),
+            }) {
+                Ok(_) => {}
+                Err(error) => {
+                    log::error!(
+                        "could not send ConfigFileReload event notification: {}",
+                        error
+                    );
+                }
+            }
+        }
+
+        let cur_layer = self.layout.bm().current_layer();
+        self.prev_layer = cur_layer;
+        self.print_layer(cur_layer);
+        self.macro_on_press_cancel_duration = 0;
+
+        #[cfg(any(
+            all(target_os = "windows", feature = "interception_driver"),
+            target_os = "linux",
+            target_os = "android",
+            target_os = "macos",
+            target_os = "unknown"
+        ))]
+        {
+            #[cfg(all(target_os = "windows", feature = "interception_driver"))]
+            {
+                if self.mouse_movement_key.lock().is_none()
+                    && cfg.options.mouse_movement_key.is_some()
+                {
+                    log::warn!(
+                        "defcfg option mouse-movement-key will not take effect until kanata is restarted!"
+                    );
+                }
+            }
+
+            *self.mouse_movement_key.lock() = cfg.options.mouse_movement_key;
+
+            #[cfg(target_os = "macos")]
+            crate::oskbd::ensure_mouse_listener_installed_after_reload();
+        }
+
+        PRESSED_KEYS.lock().clear();
+
+        #[cfg(feature = "tcp_server")]
+        if let Some(tx) = _tx {
+            let new = self.layer_info[cur_layer].name.clone();
+            match tx.try_send(ServerMessage::LayerChange { new }) {
+                Ok(_) => {}
+                Err(error) => {
+                    log::error!("could not send LayerChange event notification: {}", error);
+                }
+            }
+        }
+        #[cfg(all(target_os = "windows", feature = "gui"))]
+        send_gui_cfg_notice();
+
+        #[cfg(feature = "tcp_server")]
+        {
+            self.last_reload_ok = true;
+        }
+
         Ok(())
     }
 
     /// Update keyberon layout state for press/release, handle repeat separately
-    fn handle_key_event(&mut self, event: &KeyEvent) -> Result<()> {
+    pub fn handle_input_event(&mut self, event: &KeyEvent) -> Result<()> {
         log::debug!("process recv ev {event:?}");
+        if event.value == KeyValue::Press {
+            self.layout
+                .bm()
+                .device_history
+                .push_front(event.device_id());
+        }
         let evc: u16 = event.code.into();
+        self.ticks_since_idle = 0;
         let kbrn_ev = match event.value {
             KeyValue::Press => {
-                if let Some(state) = &mut self.dynamic_macro_record_state {
-                    state.macro_items.push(DynamicMacroItem::Press(event.code));
+                if let Some((macro_id, recorded_macro)) = record_press(
+                    &mut self.dynamic_macro_record_state,
+                    event.code,
+                    self.dynamic_macro_max_presses,
+                ) {
+                    self.dynamic_macros.insert(macro_id, recorded_macro);
+                }
+                if self.macro_on_press_cancel_duration > 0 {
+                    log::debug!("cancelling all macros: other press");
+                    self.macro_on_press_cancel_duration = 0;
+                    let layout = self.layout.bm();
+                    layout.active_sequences.clear();
+                    layout.states.retain(|s| {
+                        !matches!(s, State::FakeKey { .. } | State::RepeatingSequence { .. })
+                    });
                 }
                 Event::Press(0, evc)
             }
             KeyValue::Release => {
-                if let Some(state) = &mut self.dynamic_macro_record_state {
-                    state
-                        .macro_items
-                        .push(DynamicMacroItem::Release(event.code));
-                }
+                record_release(&mut self.dynamic_macro_record_state, event.code);
                 Event::Release(0, evc)
             }
             KeyValue::Repeat => {
                 let ret = self.handle_repeat(event);
                 return ret;
             }
+            KeyValue::Tap => {
+                self.layout.bm().event(Event::Press(0, evc));
+                self.layout.bm().event(Event::Release(0, evc));
+                return Ok(());
+            }
+            KeyValue::WakeUp => {
+                return Ok(());
+            }
         };
         self.layout.bm().event(kbrn_ev);
         Ok(())
     }
 
+    /// Returns the number of ms elapsed for the procesing loop according to current monotonic time
+    /// and stored internal state. Mutates the internal time-tracking state.
+    pub fn get_ms_elapsed(&mut self) -> u128 {
+        let now = web_time::Instant::now();
+        let ms_count_result = count_ms_elapsed(self.last_tick, now, self.time_remainder);
+        let ms_elapsed = ms_count_result.ms_elapsed;
+        self.time_remainder = ms_count_result.ms_remainder_in_ns;
+        self.last_tick = match ms_elapsed {
+            0..=10 => ms_count_result.last_tick,
+            // If too many ms elapsed, probably doing a tight loop of something that's quite
+            // expensive, e.g. click spamming. To avoid a growing ms_elapsed due to trying and
+            // failing to catch up, reset last_tick to the "actual now" instead the "past now"
+            // even though that means ticks will be missed - meaning there will be fewer than
+            // 1000 ticks in 1ms on average. In practice, there will already be fewer than 1000
+            // ticks in 1ms when running expensive operations, this just avoids having tens to
+            // thousands of ticks all happening as soon as the expensive operations end.
+            _ => web_time::Instant::now(),
+        };
+
+        ms_elapsed
+    }
+
     /// Advance keyberon layout state and send events based on changes to its state.
-    fn handle_time_ticks(&mut self, tx: &Option<Sender<ServerMessage>>) -> Result<()> {
-        const NS_IN_MS: u128 = 1_000_000;
-        let now = time::Instant::now();
-        let ns_elapsed = now.duration_since(self.last_tick).as_nanos();
-        let ns_elapsed_with_rem = ns_elapsed + self.time_remainder;
-        let ms_elapsed = ns_elapsed_with_rem / NS_IN_MS;
-        self.time_remainder = ns_elapsed_with_rem % NS_IN_MS;
+    /// Returns the number of ticks that elapsed.
+    fn handle_time_ticks(&mut self, tx: &Option<Sender<ServerMessage>>) -> Result<u16> {
+        let ms_elapsed = self.get_ms_elapsed();
+        self.tick_ms(ms_elapsed, tx)?;
+
+        if self.live_reload_requested
+            && ((self.prev_keys.is_empty() && self.cur_keys.is_empty())
+                || self.ticks_since_idle > 1000)
+        {
+            // Note regarding the ticks_since_idle check above:
+            // After 1 second if live reload is still not done, there might be a key in a stuck
+            // state. One known instance where this happens is Win+L to lock the screen in
+            // Windows with the LLHOOK mechanism. The release of Win and L keys will not be
+            // caught by the kanata process when on the lock screen. However, the OS knows that
+            // these keys have released - only the kanata state is wrong. And since kanata has
+            // a key in a stuck state, without this 1s fallback, live reload would never
+            // activate. Having this fallback allows live reload to happen which resets the
+            // kanata states.
+            self.live_reload_requested = false;
+            if let Err(e) = self.do_live_reload(tx) {
+                log::error!("live reload failed {e}");
+            }
+        }
+
+        #[cfg(feature = "perf_logging")]
+        log::info!("ms elapsed: {ms_elapsed}");
+        // Note regarding `as` casting. It doesn't really matter if the result would truncate and
+        // end up being wrong. Prefer to do the cheaper operation, as compared to doing the min of
+        // u16::MAX and ms_elapsed.
+        Ok(ms_elapsed as u16)
+    }
 
+    pub fn tick_ms(&mut self, ms_elapsed: u128, _tx: &Option<Sender<ServerMessage>>) -> Result<()> {
+        let mut extra_ticks: u16 = 0;
         for _ in 0..ms_elapsed {
-            self.live_reload_requested |= self.handle_keystate_changes()?;
-            self.handle_scrolling()?;
-            self.handle_move_mouse()?;
-            self.tick_sequence_state()?;
-            self.tick_dynamic_macro_state()?;
-
-            if self.live_reload_requested && self.prev_keys.is_empty() && self.cur_keys.is_empty() {
-                self.live_reload_requested = false;
-                if let Err(e) = self.do_live_reload() {
-                    log::error!("live reload failed {e}");
-                }
+            self.tick_states(_tx)?;
+            if let Some(event) = tick_replay_state(
+                &mut self.dynamic_macro_replay_state,
+                self.dynamic_macro_replay_behaviour,
+            ) {
+                self.layout.bm().event(event.key_event());
+                extra_ticks = extra_ticks.saturating_add(event.delay());
+                log::debug!("dyn macro extra ticks: {extra_ticks}, ms_elapsed: {ms_elapsed}");
             }
-
-            self.prev_keys.clear();
-            self.prev_keys.append(&mut self.cur_keys);
         }
+        for i in 0..(extra_ticks.saturating_sub(ms_elapsed as u16)) {
+            self.tick_states(_tx)?;
+            if tick_replay_state(
+                &mut self.dynamic_macro_replay_state,
+                self.dynamic_macro_replay_behaviour,
+            )
+            .is_some()
+            {
+                log::error!("overshot to next event at iteration #{i}, the code is broken!");
+                break;
+            }
+        }
+        Ok(())
+    }
 
-        if ms_elapsed > 0 {
-            self.last_tick = match ms_elapsed {
-                0..=10 => now,
-                // If too many ms elapsed, probably doing a tight loop of something that's quite
-                // expensive, e.g. click spamming. To avoid a growing ms_elapsed due to trying and
-                // failing to catch up, reset last_tick to the "actual now" instead the "past now"
-                // even though that means ticks will be missed - meaning there will be fewer than
-                // 1000 ticks in 1ms on average. In practice, there will already be fewer than 1000
-                // ticks in 1ms when running expensive operations, this just avoids having tens to
-                // thousands of ticks all happening as soon as the expensive operations end.
-                _ => time::Instant::now(),
-            };
-
-            // Handle layer change outside the loop. I don't see any practical scenario where it
-            // would make a difference, so may as well reduce the amount of processing.
-            self.check_handle_layer_change(tx);
+    fn tick_held_vkeys(&mut self) {
+        if self.vkeys_pending_release.is_empty() {
+            return;
         }
+        let layout = self.layout.bm();
+        self.vkeys_pending_release.retain(|coord, deadline| {
+            *deadline = deadline.saturating_sub(1);
+            match deadline {
+                0 => {
+                    layout.event(Event::Release(coord.x, coord.y));
+                    false
+                }
+                _ => true,
+            }
+        });
+    }
 
+    fn tick_states(&mut self, _tx: &Option<Sender<ServerMessage>>) -> Result<()> {
+        self.live_reload_requested |= self.handle_keystate_changes(_tx)?;
+        self.handle_scrolling()?;
+        self.handle_move_mouse()?;
+        self.tick_sequence_state()?;
+        self.tick_idle_timeout();
+        self.tick_physical_idle_timeout();
+        self.macro_on_press_cancel_duration = self.macro_on_press_cancel_duration.saturating_sub(1);
+        tick_record_state(&mut self.dynamic_macro_record_state);
+        zippy_tick(self.caps_word.is_some());
+        self.prev_keys.clear();
+        self.prev_keys.append(&mut self.cur_keys);
+        self.tick_held_vkeys();
+        #[cfg(feature = "simulated_output")]
+        {
+            self.kbd_out.tick();
+        }
         Ok(())
     }
 
     fn handle_scrolling(&mut self) -> Result<()> {
-        if let Some(scroll_state) = &mut self.scroll_state {
-            if scroll_state.ticks_until_scroll == 0 {
-                scroll_state.ticks_until_scroll = scroll_state.interval - 1;
-                self.kbd_out
-                    .scroll(scroll_state.direction, scroll_state.distance)?;
-            } else {
-                scroll_state.ticks_until_scroll -= 1;
+        if let Some((direction, distance)) = update_scrollstate_get_result(&mut self.scroll_state) {
+            match distance {
+                0 => {
+                    self.scroll_state = None;
+                }
+                _ => {
+                    self.kbd_out.scroll(direction, distance)?;
+                }
             }
         }
-        if let Some(hscroll_state) = &mut self.hscroll_state {
-            if hscroll_state.ticks_until_scroll == 0 {
-                hscroll_state.ticks_until_scroll = hscroll_state.interval - 1;
-                self.kbd_out
-                    .scroll(hscroll_state.direction, hscroll_state.distance)?;
-            } else {
-                hscroll_state.ticks_until_scroll -= 1;
+        if let Some((direction, distance)) = update_scrollstate_get_result(&mut self.hscroll_state)
+        {
+            match distance {
+                0 => {
+                    self.hscroll_state = None;
+                }
+                _ => {
+                    self.kbd_out.scroll(direction, distance)?;
+                }
             }
         }
         Ok(())
     }
 
     fn handle_move_mouse(&mut self) -> Result<()> {
-        if let Some(mmsv) = &mut self.move_mouse_state_vertical {
-            if let Some(mmas) = &mut mmsv.move_mouse_accel_state {
-                if mmas.accel_ticks_until_max != 0 {
-                    let increment =
-                        (mmas.accel_increment * f64::from(mmas.accel_ticks_from_min)) as u16;
-                    mmsv.distance = mmas.min_distance + increment;
-                    mmas.accel_ticks_from_min += 1;
-                    mmas.accel_ticks_until_max -= 1;
-                } else {
-                    mmsv.distance = mmas.max_distance;
-                }
+        if let Some(mmsv) = &mut self.move_mouse_state_vertical
+            && let Some(mmas) = &mut mmsv.move_mouse_accel_state
+        {
+            if mmas.accel_ticks_until_max != 0 {
+                let increment =
+                    (mmas.accel_increment * f64::from(mmas.accel_ticks_from_min)) as u16;
+                mmsv.distance = mmas.min_distance + increment;
+                mmas.accel_ticks_from_min += 1;
+                mmas.accel_ticks_until_max -= 1;
+            } else {
+                mmsv.distance = mmas.max_distance;
             }
+        }
+        if let Some(mmsv) = &mut self.move_mouse_state_vertical {
             if mmsv.ticks_until_move == 0 {
                 mmsv.ticks_until_move = mmsv.interval - 1;
-                self.kbd_out.move_mouse(mmsv.direction, mmsv.distance)?;
+                let scaled_distance =
+                    apply_mouse_distance_modifiers(mmsv.distance, &self.move_mouse_speed_modifiers);
+                log::debug!("handle_move_mouse: scaled vdistance: {}", scaled_distance);
+
+                let current_move = CalculatedMouseMove {
+                    direction: mmsv.direction,
+                    distance: scaled_distance,
+                };
+
+                if self.movemouse_smooth_diagonals {
+                    let axis: Axis = current_move.direction.into();
+                    match &self.movemouse_buffer {
+                        Some((previous_axis, previous_move)) => {
+                            if axis == *previous_axis {
+                                self.kbd_out.move_mouse(*previous_move)?;
+                                self.movemouse_buffer = Some((axis, current_move));
+                            } else {
+                                self.kbd_out
+                                    .move_mouse_many(&[*previous_move, current_move])?;
+                                self.movemouse_buffer = None;
+                            }
+                        }
+                        None => {
+                            self.movemouse_buffer = Some((axis, current_move));
+                        }
+                    }
+                } else {
+                    self.kbd_out.move_mouse(current_move)?;
+                }
             } else {
                 mmsv.ticks_until_move -= 1;
             }
         }
-        if let Some(mmsh) = &mut self.move_mouse_state_horizontal {
-            if let Some(mmas) = &mut mmsh.move_mouse_accel_state {
-                if mmas.accel_ticks_until_max != 0 {
-                    let increment =
-                        (mmas.accel_increment * f64::from(mmas.accel_ticks_from_min)) as u16;
-                    mmsh.distance = mmas.min_distance + increment;
-                    mmas.accel_ticks_from_min += 1;
-                    mmas.accel_ticks_until_max -= 1;
-                } else {
-                    mmsh.distance = mmas.max_distance;
-                }
+        if let Some(mmsh) = &mut self.move_mouse_state_horizontal
+            && let Some(mmas) = &mut mmsh.move_mouse_accel_state
+        {
+            if mmas.accel_ticks_until_max != 0 {
+                let increment =
+                    (mmas.accel_increment * f64::from(mmas.accel_ticks_from_min)) as u16;
+                mmsh.distance = mmas.min_distance + increment;
+                mmas.accel_ticks_from_min += 1;
+                mmas.accel_ticks_until_max -= 1;
+            } else {
+                mmsh.distance = mmas.max_distance;
             }
+        }
+        if let Some(mmsh) = &mut self.move_mouse_state_horizontal {
             if mmsh.ticks_until_move == 0 {
                 mmsh.ticks_until_move = mmsh.interval - 1;
-                self.kbd_out.move_mouse(mmsh.direction, mmsh.distance)?;
+                let scaled_distance =
+                    apply_mouse_distance_modifiers(mmsh.distance, &self.move_mouse_speed_modifiers);
+                log::debug!("handle_move_mouse: scaled hdistance: {}", scaled_distance);
+
+                let current_move = CalculatedMouseMove {
+                    direction: mmsh.direction,
+                    distance: scaled_distance,
+                };
+
+                if self.movemouse_smooth_diagonals {
+                    let axis: Axis = current_move.direction.into();
+                    match &self.movemouse_buffer {
+                        Some((previous_axis, previous_move)) => {
+                            if axis == *previous_axis {
+                                self.kbd_out.move_mouse(*previous_move)?;
+                                self.movemouse_buffer = Some((axis, current_move));
+                            } else {
+                                self.kbd_out
+                                    .move_mouse_many(&[*previous_move, current_move])?;
+                                self.movemouse_buffer = None;
+                            }
+                        }
+                        None => {
+                            self.movemouse_buffer = Some((axis, current_move));
+                        }
+                    }
+                } else {
+                    self.kbd_out.move_mouse(current_move)?;
+                }
             } else {
                 mmsh.ticks_until_move -= 1;
             }
@@ -583,54 +1168,48 @@ impl Kanata {
     }
 
     fn tick_sequence_state(&mut self) -> Result<()> {
-        if let Some(state) = &mut self.sequence_state {
+        if let Some(state) = self.sequence_state.get_active() {
             state.ticks_until_timeout -= 1;
             if state.ticks_until_timeout == 0 {
                 log::debug!("sequence timeout; exiting sequence state");
-                match self.sequence_input_mode {
-                    SequenceInputMode::HiddenDelayType => {
-                        for code in state.sequence.iter().copied() {
-                            if let Some(osc) = OsCode::from_u16(code) {
-                                self.kbd_out.press_key(osc)?;
-                                self.kbd_out.release_key(osc)?;
-                            }
-                        }
-                    }
-                    SequenceInputMode::HiddenSuppressed | SequenceInputMode::VisibleBackspaced => {}
-                }
-                self.sequence_state = None;
+                cancel_sequence(state, &mut self.kbd_out)?;
             }
         }
         Ok(())
     }
 
-    fn tick_dynamic_macro_state(&mut self) -> Result<()> {
-        let mut clear_replaying_macro = false;
-        if let Some(state) = &mut self.dynamic_macro_replay_state {
-            state.delay_remaining = state.delay_remaining.saturating_sub(1);
-            if state.delay_remaining == 0 {
-                match state.macro_items.pop_front() {
-                    None => clear_replaying_macro = true,
-                    Some(i) => match i {
-                        DynamicMacroItem::Press(k) => {
-                            self.layout.bm().event(Event::Press(0, k.into()))
-                        }
-                        DynamicMacroItem::Release(k) => {
-                            self.layout.bm().event(Event::Release(0, k.into()))
-                        }
-                        DynamicMacroItem::EndMacro(macro_id) => {
-                            state.active_macros.remove(&macro_id);
-                        }
-                    },
-                }
-                state.delay_remaining = 5;
-            }
+    fn tick_idle_timeout(&mut self) {
+        if self.waiting_for_idle.is_empty() {
+            return;
         }
-        if clear_replaying_macro {
-            log::debug!("finished macro replay");
-            self.dynamic_macro_replay_state = None;
+        self.waiting_for_idle.retain(|wfd| {
+            if self.ticks_since_idle >= wfd.idle_duration {
+                // Process this and return false so that it is not retained.
+                let layout = self.layout.bm();
+                let Coord { x, y } = wfd.coord;
+                handle_fakekey_action(wfd.action, layout, x, y);
+                false
+            } else {
+                true
+            }
+        })
+    }
+
+    fn tick_physical_idle_timeout(&mut self) {
+        if self.waiting_for_physical_idle.is_empty() {
+            return;
         }
-        Ok(())
+        self.waiting_for_physical_idle.retain(|wfd| {
+            if self.ticks_since_physical_idle >= wfd.idle_duration {
+                // Process this and return false so that it is not retained.
+                let layout = self.layout.bm();
+                let Coord { x, y } = wfd.coord;
+                handle_fakekey_action(wfd.action, layout, x, y);
+                false
+            } else {
+                true
+            }
+        })
     }
 
     /// Sends OS key events according to the change in key state between the current and the
@@ -639,34 +1218,212 @@ impl Kanata {
     /// Updates self.cur_keys.
     ///
     /// Returns whether live reload was requested.
-    fn handle_keystate_changes(&mut self) -> Result<bool> {
+    fn handle_keystate_changes(&mut self, _tx: &Option<Sender<ServerMessage>>) -> Result<bool> {
         let layout = self.layout.bm();
         let custom_event = layout.tick();
-        let mut live_reload_requested = false;
-        let cur_keys = &mut self.cur_keys;
-        cur_keys.extend(layout.keycodes());
-        self.overrides
-            .override_keys(cur_keys, &mut self.override_states);
-        if let Some(caps_word) = &mut self.caps_word {
-            if caps_word.maybe_add_lsft(cur_keys) == CapsWordNextState::End {
-                self.caps_word = None;
+
+        #[cfg(feature = "tcp_server")]
+        if let Some(hold_info) = layout.tap_hold_tracker.take_hold_activated()
+            && hold_info.coord.0 == NORMAL_KEY_ROW
+            && let Some(tx) = _tx
+        {
+            let osc = OsCode::from(hold_info.coord.1);
+            let key = osc.to_string().to_lowercase();
+            log::debug!("HoldActivated: key={key} coord={:?}", hold_info.coord);
+            match tx.try_send(ServerMessage::HoldActivated { key }) {
+                Ok(_) => {}
+                Err(error) => {
+                    log::error!("could not send HoldActivated event: {}", error);
+                }
             }
         }
-
+        #[cfg(feature = "tcp_server")]
+        if let Some(tap_info) = layout.tap_hold_tracker.take_tap_activated()
+            && tap_info.coord.0 == NORMAL_KEY_ROW
+            && let Some(tx) = _tx
+        {
+            let osc = OsCode::from(tap_info.coord.1);
+            let key = osc.to_string().to_lowercase();
+            log::debug!("TapActivated: key={key} coord={:?}", tap_info.coord);
+            match tx.try_send(ServerMessage::TapActivated { key }) {
+                Ok(_) => {}
+                Err(error) => {
+                    log::error!("could not send TapActivated event: {}", error);
+                }
+            }
+        }
+
+        let mut live_reload_requested = false;
+        let cur_keys = &mut self.cur_keys;
+        cur_keys.extend(layout.keycodes());
+        let mut reverse_release_order = false;
+
+        // Deal with unmodded and other early custom actions.
+        // Unlike other custom actions, these should come before key presses and releases.
+        // I don't quite remember why custom actions come after the key processing,
+        // but I remember that it is intentional.
+        // However, since unmodded needs to modify the key lists,
+        // and SequenceNoerase may need to be evaluated within multi before a key
+        // that completes the sequence, it should come before.
+        match custom_event {
+            CustomEvent::Press(custact) => match custact {
+                CustomAction::Unmodded { keys, mods } => {
+                    self.unmodded_keys.extend(keys.iter());
+                    self.unmodded_mods = *mods;
+                }
+                CustomAction::Unshifted { keys } => {
+                    self.unshifted_keys.extend(keys.iter());
+                }
+                CustomAction::SequenceNoerase(noerase_count) => {
+                    if let Some(state) = self.sequence_state.get_active() {
+                        log::debug!("adding noerase: {noerase_count}");
+                        add_noerase(state, *noerase_count);
+                    }
+                }
+                _ => {}
+            },
+            CustomEvent::Release(custact) => match custact {
+                CustomAction::Unmodded { keys, mods: _ } => {
+                    self.unmodded_keys.retain(|k| !keys.contains(k));
+                }
+                CustomAction::Unshifted { keys } => {
+                    self.unshifted_keys.retain(|k| !keys.contains(k));
+                }
+                CustomAction::ReverseReleaseOrder => {
+                    reverse_release_order = true;
+                }
+                _ => {}
+            },
+            _ => {}
+        }
+        if !self.unmodded_keys.is_empty() {
+            for mod_key in self.unmodded_mods.iter() {
+                let kc = match mod_key {
+                    UnmodMods::LSft => KeyCode::LShift,
+                    UnmodMods::RSft => KeyCode::RShift,
+                    UnmodMods::LAlt => KeyCode::LAlt,
+                    UnmodMods::RAlt => KeyCode::RAlt,
+                    UnmodMods::LCtl => KeyCode::LCtrl,
+                    UnmodMods::RCtl => KeyCode::RCtrl,
+                    UnmodMods::LMet => KeyCode::LGui,
+                    UnmodMods::RMet => KeyCode::RGui,
+                    _ => unreachable!("all bits of u8 should be covered"), // test_unmodmods_bits
+                };
+                cur_keys.retain(|k| *k != kc);
+            }
+            cur_keys.extend(self.unmodded_keys.iter());
+        }
+        if !self.unshifted_keys.is_empty() {
+            cur_keys.retain(|k| !matches!(k, KeyCode::LShift | KeyCode::RShift));
+            cur_keys.extend(self.unshifted_keys.iter());
+        }
+
+        self.overrides.override_keys(
+            cur_keys,
+            &mut self.override_states,
+            layout.current_layer() as u16,
+        );
+        mark_overridden_nonmodkeys_for_eager_erasure(&self.override_states, &mut layout.states);
+        if self.override_release_on_activation {
+            for removed in self.override_states.removed_oscs() {
+                if !removed.is_modifier() {
+                    layout.states.retain(|s| {
+                        s.release_state(ReleasableState::KeyCode(removed.into()))
+                            .is_some()
+                    });
+                }
+            }
+        }
+
+        if let Some(caps_word) = &mut self.caps_word
+            && caps_word.tick_maybe_add_lsft(cur_keys) == CapsWordNextState::End
+        {
+            self.caps_word = None;
+        }
+
         // Release keys that do not exist in the current state but exist in the previous state.
         // This used to use a HashSet but it was changed to a Vec because the order of operations
         // matters.
+        //
+        // BUG(sequences):
+        //
+        // With hidden-delay-type or hidden-suppressed,
+        // sequences will unexpectedly send releases
+        // for the presses that would otherwise have happened.
+        // This is because the press is skipped but the keys make it
+        // into `self.prev_keys` and the OS release event is sent in the code below.
+        //
+        // There haven't been any reports of negative consequences of this behaviour,
+        // but it is unusual and ideally wouldn't happen, so I tried to fix it anyway.
+        // But I was unsuccessful. Approach tried:
+        //
+        // - clear `self.cur_keys` and `layout.states` of outputted keys
+        //   when a sequence is active, for the impacted sequence modes.
+        //
+        // This approach fails because it keeping `layout.states` intact
+        // is necessary to complete chorded sequences, e.g. `S-(a b c)`.
+        // Clearing the `lsft` means the above sequence is impossible to complete.
+        //
+        // Another approach that might work, which has not been attempted,
+        // is to keep track of oskbd events that have actually been sent.
+        // Then, a release can only be sent if an un-released corresponding press
+        // has been pressed in the past.
+        // However, this doesn't seem worth the:
+        //
+        // - runtime cost
+        // - work involved to add the code
+        // - ongoing burden of maintaining that code
+        //
+        // Given that there appears to be no practical negative consequences for this bug
+        // remaining.
         log::trace!("{:?}", &self.prev_keys);
-        for k in &self.prev_keys {
+        let mut fwd_release = self.prev_keys.iter();
+        let mut rev_release = self.prev_keys.iter().rev();
+        let keys: &mut dyn Iterator<Item = &KeyCode> = match reverse_release_order {
+            false => &mut fwd_release,
+            true => &mut rev_release,
+        };
+        for k in keys {
             if cur_keys.contains(k) {
                 continue;
             }
             log::debug!("key release   {:?}", k);
-            if let Err(e) = self.kbd_out.release_key(k.into()) {
+            if let Err(e) = release_key(&mut self.kbd_out, k.into()) {
                 bail!("failed to release key: {:?}", e);
             }
         }
 
+        if cur_keys.is_empty()
+            && !self.prev_keys.is_empty()
+            && let Some(state) = self.sequence_state.get_active()
+        {
+            use kanata_parser::trie::GetOrDescendentExistsResult::*;
+            state.overlapped_sequence.push(KEY_OVERLAP_MARKER);
+            match self
+                .sequences
+                .get_or_descendant_exists(&state.overlapped_sequence)
+            {
+                HasValue((i, j)) => {
+                    do_successful_sequence_termination(
+                        &mut self.kbd_out,
+                        state,
+                        layout,
+                        i,
+                        j,
+                        EndSequenceType::Overlap,
+                    )?;
+                }
+                NotInTrie => {
+                    // Overwrite overlapped with non-overlapped tracking
+                    state.overlapped_sequence.clear();
+                    state
+                        .overlapped_sequence
+                        .extend(state.sequence.iter().copied());
+                }
+                InTrie => {}
+            }
+        }
+
         // Press keys that exist in the current state but are missing from the previous state.
         // Comment above regarding Vec/HashSet also applies here.
         log::trace!("{cur_keys:?}");
@@ -683,147 +1440,27 @@ impl Kanata {
             // logic there and is easier to add here since we already have
             // allocations and logic.
             self.prev_keys.push(*k);
-            LAST_PRESSED_KEY.store(OsCode::from(k).into(), SeqCst);
-            match &mut self.sequence_state {
-                None => {
-                    log::debug!("key press     {:?}", k);
-                    if let Err(e) = self.kbd_out.press_key(k.into()) {
-                        bail!("failed to press key: {:?}", e);
-                    }
-                }
-                Some(state) => {
-                    state.ticks_until_timeout = self.sequence_timeout;
-
-                    // Transform to OsCode and convert modifiers other than altgr/ralt (same key
-                    // different names) to the left version, since that's how chords get
-                    // transformed when building up sequences.
-                    let osc = match OsCode::from(*k) {
-                        OsCode::KEY_RIGHTSHIFT => OsCode::KEY_LEFTSHIFT,
-                        OsCode::KEY_RIGHTMETA => OsCode::KEY_LEFTMETA,
-                        OsCode::KEY_RIGHTCTRL => OsCode::KEY_LEFTCTRL,
-                        osc => osc,
-                    };
-
-                    // Modify the upper unused bits of the u16 to signify that the key is activated
-                    // alongside a modifier.
-                    let pushed_into_seq = {
-                        let mut base = u16::from(osc);
-                        for k in cur_keys.iter().copied() {
-                            base |= mod_mask_for_keycode(k);
-                        }
-                        base
-                    };
-
-                    state.sequence.push(pushed_into_seq);
-                    match self.sequence_input_mode {
-                        SequenceInputMode::VisibleBackspaced => {
-                            self.kbd_out.press_key(osc)?;
-                        }
-                        SequenceInputMode::HiddenSuppressed
-                        | SequenceInputMode::HiddenDelayType => {}
-                    }
-                    log::debug!("sequence got {k:?}");
+            self.last_pressed_key = *k;
 
-                    use kanata_parser::sequences::*;
-                    use kanata_parser::trie::GetOrDescendentExistsResult::*;
-
-                    // Check for invalid sequence termination.
-                    let mut res = self.sequences.get_or_descendant_exists(&state.sequence);
-                    if res == NotInTrie {
-                        let is_invalid_termination = if self.sequence_backtrack_modcancel
-                            && (pushed_into_seq & MASK_MODDED > 0)
-                        {
-                            let mut no_valid_seqs = true;
-                            // If applicable, check again with modifier bits unset.
-                            for i in (0..state.sequence.len()).rev() {
-                                // Safety: proper bounds are immediately above.
-                                // Note - can't use iter_mut due to borrowing issues.
-                                *unsafe { state.sequence.get_unchecked_mut(i) } &= MASK_KEYCODES;
-                                res = self.sequences.get_or_descendant_exists(&state.sequence);
-                                if res != NotInTrie {
-                                    no_valid_seqs = false;
-                                    break;
-                                }
-                            }
-                            no_valid_seqs
-                        } else {
-                            true
-                        };
-                        if is_invalid_termination {
-                            log::debug!("got invalid sequence; exiting sequence mode");
-                            match self.sequence_input_mode {
-                                SequenceInputMode::HiddenDelayType => {
-                                    for code in state.sequence.iter().copied() {
-                                        if let Some(osc) = OsCode::from_u16(code) {
-                                            self.kbd_out.press_key(osc)?;
-                                            self.kbd_out.release_key(osc)?;
-                                        }
-                                    }
-                                }
-                                SequenceInputMode::HiddenSuppressed
-                                | SequenceInputMode::VisibleBackspaced => {}
-                            }
-                            self.sequence_state = None;
-                            continue;
-                        }
-                    }
-
-                    // Check for and handle valid termination.
-                    if let HasValue((i, j)) = res {
-                        log::debug!("sequence complete; tapping fake key");
-                        match self.sequence_input_mode {
-                            SequenceInputMode::HiddenSuppressed
-                            | SequenceInputMode::HiddenDelayType => {}
-                            SequenceInputMode::VisibleBackspaced => {
-                                for k in state.sequence.iter() {
-                                    // Check for pressed modifiers and don't input backspaces for
-                                    // those since they don't output characters that can be
-                                    // backspaced.
-                                    let kc = OsCode::from(*k & MASK_KEYCODES);
-                                    if matches!(
-                                        kc,
-                                        // Known bug: most non-characters-outputting keys are not
-                                        // listed. I'm too lazy to list them all. Just use
-                                        // character-outputting keys (and modifiers) in sequences
-                                        // please! Or switch to a different input mode? It doesn't
-                                        // really make sense to use non-typing characters other
-                                        // than modifiers does it? Since those would probably be
-                                        // further away from the home row, so why use them? If one
-                                        // desired to fix this, a shorter list of keys would
-                                        // probably be the list of keys that **do** output
-                                        // characters than those that don't.
-                                        OsCode::KEY_LEFTSHIFT
-                                            | OsCode::KEY_RIGHTSHIFT
-                                            | OsCode::KEY_LEFTMETA
-                                            | OsCode::KEY_RIGHTMETA
-                                            | OsCode::KEY_LEFTCTRL
-                                            | OsCode::KEY_RIGHTCTRL
-                                            | OsCode::KEY_LEFTALT
-                                            | OsCode::KEY_RIGHTALT
-                                    ) {
-                                        continue;
-                                    }
-
-                                    self.kbd_out.press_key(OsCode::KEY_BACKSPACE)?;
-                                    self.kbd_out.release_key(OsCode::KEY_BACKSPACE)?;
-                                }
-                            }
-                        }
+            if self.sequence_always_on && self.sequence_state.is_inactive() {
+                self.sequence_state
+                    .activate(self.sequence_input_mode, self.sequence_timeout);
+            }
 
-                        // Make sure to unpress any keys that were pressed as part of the sequence
-                        // so that the keyberon internal sequence mechanism can do press+unpress of
-                        // them.
-                        for k in state.sequence.iter() {
-                            let kc = KeyCode::from(OsCode::from(*k & MASK_KEYCODES));
-                            layout.states.retain(|s| match s {
-                                State::NormalKey { keycode, .. } => kc != *keycode,
-                                _ => true,
-                            });
-                        }
-                        layout.event(Event::Press(i, j));
-                        layout.event(Event::Release(i, j));
-                        self.sequence_state = None;
-                    }
+            if let Some(state) = self.sequence_state.get_active() {
+                do_sequence_press_logic(
+                    state,
+                    k,
+                    get_mod_mask_for_cur_keys(cur_keys),
+                    &mut self.kbd_out,
+                    &self.sequences,
+                    self.sequence_backtrack_modcancel,
+                    layout,
+                )?;
+            } else {
+                log::debug!("key press     {:?}", k);
+                if let Err(e) = press_key(&mut self.kbd_out, k.into()) {
+                    bail!("failed to press key: {:?}", e);
                 }
             }
         }
@@ -831,532 +1468,647 @@ impl Kanata {
         // Handle custom events. This used to be in a separate function but lifetime issues cause
         // it to now be here.
         match custom_event {
-            CustomEvent::Press(custacts) => {
+            CustomEvent::Press(custact) => {
                 #[cfg(feature = "cmd")]
                 let mut cmds = vec![];
-                let mut prev_mouse_btn = None;
-                for custact in custacts.iter() {
-                    match custact {
-                        // For unicode, only send on the press. No repeat action is supported for this for
-                        // now.
-                        CustomAction::Unicode(c) => self.kbd_out.send_unicode(*c)?,
-                        CustomAction::LiveReload => {
-                            live_reload_requested = true;
-                            log::info!(
-                                "Requested live reload of file: {}",
-                                self.cfg_paths[self.cur_cfg_idx].display()
-                            );
-                        }
-                        CustomAction::LiveReloadNext => {
-                            live_reload_requested = true;
-                            self.cur_cfg_idx = if self.cur_cfg_idx == self.cfg_paths.len() - 1 {
-                                0
-                            } else {
-                                self.cur_cfg_idx + 1
-                            };
-                            log::info!(
-                                "Requested live reload of next file: {}",
-                                self.cfg_paths[self.cur_cfg_idx].display()
-                            );
+
+                let mut reload_action: Option<ReloadAction> = None;
+                match custact {
+                    // For unicode, only send on the press. No repeat action is supported for this for
+                    // now.
+                    CustomAction::Unicode(c) => self.kbd_out.send_unicode(*c)?,
+                    CustomAction::LiveReload => {
+                        reload_action = Some(ReloadAction::Reload);
+                    }
+                    CustomAction::LiveReloadNext => {
+                        reload_action = Some(ReloadAction::ReloadNext);
+                    }
+                    CustomAction::LiveReloadPrev => {
+                        reload_action = Some(ReloadAction::ReloadPrev);
+                    }
+                    CustomAction::LiveReloadNum(n) => {
+                        reload_action = Some(ReloadAction::ReloadNum(usize::from(*n)));
+                    }
+                    CustomAction::LiveReloadFile(path) => {
+                        reload_action = Some(ReloadAction::ReloadFile(path.to_string()));
+                    }
+                    CustomAction::Mouse(btn) => {
+                        self.kbd_out.click_btn(*btn)?;
+                    }
+                    CustomAction::MouseTap(btn) => {
+                        log::debug!("click     {:?}", btn);
+                        self.kbd_out.click_btn(*btn)?;
+                        log::debug!("unclick   {:?}", btn);
+                        self.kbd_out.release_btn(*btn)?;
+                    }
+                    CustomAction::MWheel {
+                        direction,
+                        interval,
+                        distance,
+                        inertial_scroll_params,
+                    } => match direction {
+                        MWheelDirection::Up | MWheelDirection::Down => {
+                            self.scroll_state = Some(ScrollState {
+                                direction: *direction,
+                                distance: *distance,
+                                ticks_until_scroll: 0,
+                                interval: *interval,
+                                scroll_accel_state: inertial_scroll_params.as_ref().map(|isp|
+                                    ScrollAccelState {
+                                    deceleration_multiplier: isp.deceleration_multiplier.0,
+                                    acceleration_multiplier: isp.acceleration_multiplier.0,
+                                    max_velocity: isp.maximum_velocity.0,
+                                    current_velocity: isp.initial_velocity.0,
+                                    scroll_released: false,
+                                    }
+                                ),
+                            })
                         }
-                        CustomAction::LiveReloadPrev => {
-                            live_reload_requested = true;
-                            self.cur_cfg_idx = match self.cur_cfg_idx {
-                                0 => self.cfg_paths.len() - 1,
-                                i => i - 1,
-                            };
-                            log::info!(
-                                "Requested live reload of prev file: {}",
-                                self.cfg_paths[self.cur_cfg_idx].display()
-                            );
+                        MWheelDirection::Left | MWheelDirection::Right => {
+                            self.hscroll_state = Some(ScrollState {
+                                direction: *direction,
+                                distance: *distance,
+                                ticks_until_scroll: 0,
+                                interval: *interval,
+                                scroll_accel_state: None,
+                            })
                         }
-                        CustomAction::Mouse(btn) => {
-                            log::debug!("click     {:?}", btn);
-                            if let Some(pbtn) = prev_mouse_btn {
-                                log::debug!("unclick   {:?}", pbtn);
-                                self.kbd_out.release_btn(pbtn)?;
-                            }
-                            self.kbd_out.click_btn(*btn)?;
-                            prev_mouse_btn = Some(*btn);
+                    },
+                    CustomAction::MWheelNotch { direction } => {
+                        self.kbd_out
+                            .scroll(*direction, HI_RES_SCROLL_UNITS_IN_LO_RES)?;
+                    }
+                    CustomAction::MoveMouse {
+                        direction,
+                        interval,
+                        distance,
+                    } => match direction {
+                        MoveDirection::Up | MoveDirection::Down => {
+                            self.move_mouse_state_vertical = Some(MoveMouseState {
+                                direction: *direction,
+                                distance: *distance,
+                                ticks_until_move: 0,
+                                interval: *interval,
+                                move_mouse_accel_state: None,
+                            })
                         }
-                        CustomAction::MouseTap(btn) => {
-                            log::debug!("click     {:?}", btn);
-                            self.kbd_out.click_btn(*btn)?;
-                            log::debug!("unclick   {:?}", btn);
-                            self.kbd_out.release_btn(*btn)?;
+                        MoveDirection::Left | MoveDirection::Right => {
+                            self.move_mouse_state_horizontal = Some(MoveMouseState {
+                                direction: *direction,
+                                distance: *distance,
+                                ticks_until_move: 0,
+                                interval: *interval,
+                                move_mouse_accel_state: None,
+                            })
                         }
-                        CustomAction::MWheel {
-                            direction,
-                            interval,
-                            distance,
-                        } => match direction {
-                            MWheelDirection::Up | MWheelDirection::Down => {
-                                self.scroll_state = Some(ScrollState {
-                                    direction: *direction,
-                                    distance: *distance,
-                                    ticks_until_scroll: 0,
-                                    interval: *interval,
-                                })
-                            }
-                            MWheelDirection::Left | MWheelDirection::Right => {
-                                self.hscroll_state = Some(ScrollState {
-                                    direction: *direction,
-                                    distance: *distance,
-                                    ticks_until_scroll: 0,
-                                    interval: *interval,
-                                })
+                    },
+                    CustomAction::MoveMouseAccel {
+                        direction,
+                        interval,
+                        accel_time,
+                        min_distance,
+                        max_distance,
+                    } => {
+                        let move_mouse_accel_state = match (
+                            self.movemouse_inherit_accel_state,
+                            &self.move_mouse_state_horizontal,
+                            &self.move_mouse_state_vertical,
+                        ) {
+                            (
+                                true,
+                                Some(MoveMouseState {
+                                    move_mouse_accel_state: Some(s),
+                                    ..
+                                }),
+                                _,
+                            )
+                            | (
+                                true,
+                                _,
+                                Some(MoveMouseState {
+                                    move_mouse_accel_state: Some(s),
+                                    ..
+                                }),
+                            ) => *s,
+                            _ => {
+                                let f_max_distance: f64 = *max_distance as f64;
+                                let f_min_distance: f64 = *min_distance as f64;
+                                let f_accel_time: f64 = *accel_time as f64;
+                                let increment =
+                                    (f_max_distance - f_min_distance) / f_accel_time;
+
+                                MoveMouseAccelState {
+                                    accel_ticks_from_min: 0,
+                                    accel_ticks_until_max: *accel_time,
+                                    accel_increment: increment,
+                                    min_distance: *min_distance,
+                                    max_distance: *max_distance,
+                                }
                             }
-                        },
-                        CustomAction::MoveMouse {
-                            direction,
-                            interval,
-                            distance,
-                        } => match direction {
+                        };
+
+                        match direction {
                             MoveDirection::Up | MoveDirection::Down => {
                                 self.move_mouse_state_vertical = Some(MoveMouseState {
                                     direction: *direction,
-                                    distance: *distance,
+                                    distance: *min_distance,
                                     ticks_until_move: 0,
                                     interval: *interval,
-                                    move_mouse_accel_state: None,
+                                    move_mouse_accel_state: Some(move_mouse_accel_state),
                                 })
                             }
                             MoveDirection::Left | MoveDirection::Right => {
                                 self.move_mouse_state_horizontal = Some(MoveMouseState {
                                     direction: *direction,
-                                    distance: *distance,
+                                    distance: *min_distance,
                                     ticks_until_move: 0,
                                     interval: *interval,
-                                    move_mouse_accel_state: None,
+                                    move_mouse_accel_state: Some(move_mouse_accel_state),
                                 })
                             }
-                        },
-                        CustomAction::MoveMouseAccel {
-                            direction,
-                            interval,
-                            accel_time,
-                            min_distance,
-                            max_distance,
-                        } => {
-                            let f_max_distance: f64 = *max_distance as f64;
-                            let f_min_distance: f64 = *min_distance as f64;
-                            let f_accel_time: f64 = *accel_time as f64;
-                            let increment = (f_max_distance - f_min_distance) / f_accel_time;
-                            match direction {
-                                MoveDirection::Up | MoveDirection::Down => {
-                                    self.move_mouse_state_vertical = Some(MoveMouseState {
-                                        direction: *direction,
-                                        distance: *min_distance,
-                                        ticks_until_move: 0,
-                                        interval: *interval,
-                                        move_mouse_accel_state: Some(MoveMouseAccelState {
-                                            accel_ticks_from_min: 0,
-                                            accel_ticks_until_max: *accel_time,
-                                            accel_increment: increment,
-                                            min_distance: *min_distance,
-                                            max_distance: *max_distance,
-                                        }),
-                                    })
-                                }
-                                MoveDirection::Left | MoveDirection::Right => {
-                                    self.move_mouse_state_horizontal = Some(MoveMouseState {
-                                        direction: *direction,
-                                        distance: *min_distance,
-                                        ticks_until_move: 0,
-                                        interval: *interval,
-                                        move_mouse_accel_state: Some(MoveMouseAccelState {
-                                            accel_ticks_from_min: 0,
-                                            accel_ticks_until_max: *accel_time,
-                                            accel_increment: increment,
-                                            min_distance: *min_distance,
-                                            max_distance: *max_distance,
-                                        }),
-                                    })
-                                }
-                            }
                         }
-                        CustomAction::Cmd(_cmd) => {
-                            #[cfg(feature = "cmd")]
-                            cmds.push(_cmd.clone());
-                        }
-                        CustomAction::CmdOutputKeys(_cmd) => {
-                            #[cfg(feature = "cmd")]
-                            {
-                                for (key_action, osc) in keys_for_cmd_output(_cmd) {
-                                    match key_action {
-                                        KeyAction::Press => self.kbd_out.press_key(osc)?,
-                                        KeyAction::Release => self.kbd_out.release_key(osc)?,
+                    }
+                    CustomAction::MoveMouseSpeed { speed } => {
+                        self.move_mouse_speed_modifiers.push(*speed);
+                        log::debug!(
+                            "movemousespeed modifiers: {:?}",
+                            self.move_mouse_speed_modifiers
+                        );
+                    }
+                    CustomAction::Cmd(_cmd) => {
+                        #[cfg(feature = "cmd")]
+                        cmds.push((
+                            Some(log::Level::Info),
+                            Some(log::Level::Error),
+                            Vec::from_iter(_cmd.iter().map(|s| s.to_string())),
+                        ));
+                    }
+                    CustomAction::CmdLog(_log_level, _error_log_level, _cmd) => {
+                        #[cfg(feature = "cmd")]
+                        cmds.push((
+                            _log_level.get_level(),
+                            _error_log_level.get_level(),
+                            Vec::from_iter(_cmd.iter().map(|s| s.to_string())),
+                        ));
+                    }
+                    CustomAction::CmdOutputKeys(_cmd) => {
+                        #[cfg(feature = "cmd")]
+                        {
+                            // Maybe improvement in the future:
+                            // A delay here, as in KeyAction::Delay, will pause the entire
+                            // state machine loop. That is _probably_ OK, but ideally this
+                            // would be done in a separate thread or somehow
+                            for key_action in keys_for_cmd_output(_cmd) {
+                                match key_action {
+                                    KeyAction::Press(osc) => press_key(&mut self.kbd_out, osc)?,
+                                    KeyAction::Release(osc) => {
+                                        release_key(&mut self.kbd_out, osc)?
                                     }
+                                    KeyAction::Delay(delay) => std::thread::sleep(
+                                        std::time::Duration::from_millis(u64::from(delay)),
+                                    ),
                                 }
                             }
                         }
-                        CustomAction::FakeKey { coord, action } => {
-                            let (x, y) = (coord.x, coord.y);
-                            log::debug!(
-                                "fake key on press   {action:?} {:?},{x:?},{y:?} {:?}",
-                                layout.default_layer,
-                                layout.layers[layout.default_layer][x as usize][y as usize]
-                            );
-                            match action {
-                                FakeKeyAction::Press => layout.event(Event::Press(x, y)),
-                                FakeKeyAction::Release => layout.event(Event::Release(x, y)),
-                                FakeKeyAction::Tap => {
-                                    layout.event(Event::Press(x, y));
-                                    layout.event(Event::Release(x, y));
+                    }
+                    CustomAction::PushMessage(_message) => {
+                        log::debug!("Action push-msg");
+                        #[cfg(feature = "tcp_server")]
+                        if let Some(tx) = _tx {
+                            let message = simple_sexpr_to_json_array(_message);
+                            log::debug!("Action push-msg message: {}", message);
+                            match tx.try_send(ServerMessage::MessagePush { message }) {
+                                Ok(_) => {}
+                                Err(error) => {
+                                    log::error!(
+                                        "could not send {} event notification: {}",
+                                        PUSH_MESSAGE,
+                                        error
+                                    );
                                 }
                             }
                         }
-                        CustomAction::Delay(delay) => {
-                            log::debug!("on-press: sleeping for {delay} ms");
-                            std::thread::sleep(std::time::Duration::from_millis((*delay).into()));
+                        #[cfg(feature = "tcp_server")]
+                        if self.tcp_server_address.is_none() {
+                            log::warn!("{} was used, but TCP server is not running. did you specify a port?", PUSH_MESSAGE);
                         }
-                        CustomAction::SequenceLeader => {
-                            if self.sequence_state.is_none()
-                                || self.sequence_input_mode == SequenceInputMode::HiddenSuppressed
-                            {
-                                log::debug!("entering sequence mode");
-                                self.sequence_state = Some(SequenceState {
-                                    sequence: vec![],
-                                    ticks_until_timeout: self.sequence_timeout,
-                                });
-                            }
+                        #[cfg(not(feature = "tcp_server"))]
+                        log::warn!(
+                            "{} was used, but Kanata was compiled with TCP server disabled.",
+                            PUSH_MESSAGE
+                        );
+                    }
+                    CustomAction::FakeKey { coord, action } => {
+                        let (x, y) = (coord.x, coord.y);
+                        log::debug!(
+                            "fake key on press   {action:?} {:?},{x:?},{y:?} {:?}",
+                            layout.default_layer,
+                            layout.layers[layout.default_layer][x as usize][y as usize]
+                        );
+                        handle_fakekey_action(*action, layout, x, y);
+                    }
+                    CustomAction::Delay(delay) => {
+                        log::debug!("on-press: sleeping for {delay} ms");
+                        std::thread::sleep(time::Duration::from_millis((*delay).into()));
+                    }
+                    CustomAction::SequenceCancel => {
+                        if let Some(state) = self.sequence_state.get_active() {
+                            log::debug!("pressed cancel sequence key");
+                            cancel_sequence(state, &mut self.kbd_out)?;
                         }
-                        CustomAction::Repeat => {
-                            let key = OsCode::from(LAST_PRESSED_KEY.load(SeqCst));
-                            log::debug!("repeating a keypress {key:?}");
-                            let mut do_caps_word = false;
-                            if !cur_keys.contains(&KeyCode::LShift) {
-                                if let Some(ref mut cw) = self.caps_word {
-                                    cur_keys.push(key.into());
-                                    let prev_len = cur_keys.len();
-                                    cw.maybe_add_lsft(cur_keys);
-                                    if cur_keys.len() > prev_len {
-                                        do_caps_word = true;
-                                        self.kbd_out.press_key(OsCode::KEY_LEFTSHIFT)?;
-                                    }
-                                }
-                            }
-                            // Release key in case the most recently pressed key is still pressed.
-                            self.kbd_out.release_key(key)?;
-                            self.kbd_out.press_key(key)?;
-                            self.kbd_out.release_key(key)?;
-                            if do_caps_word {
-                                self.kbd_out.release_key(OsCode::KEY_LEFTSHIFT)?;
-                            }
+                    }
+                    CustomAction::SequenceLeader(timeout, input_mode) => {
+                        if self.sequence_state.is_inactive() {
+                            log::debug!("entering sequence mode");
+                            self.sequence_state.activate(*input_mode, *timeout);
+                        } else if *input_mode == SequenceInputMode::HiddenSuppressed {
+                            log::debug!("retriggering sequence mode");
+                            self.sequence_state.activate(*input_mode, *timeout);
                         }
-                        CustomAction::DynamicMacroRecord(macro_id) => {
-                            let mut stop_record = false;
-                            let mut new_recording = None;
-                            match &mut self.dynamic_macro_record_state {
-                                None => {
-                                    log::info!("starting dynamic macro {macro_id} recording");
-                                    self.dynamic_macro_record_state =
-                                        Some(DynamicMacroRecordState {
-                                            starting_macro_id: *macro_id,
-                                            macro_items: vec![],
-                                        })
-                                }
-                                Some(ref mut state) => {
-                                    // remove the last item, since it's almost certainly a "macro
-                                    // record" key press action which we don't want to keep.
-                                    state.macro_items.remove(state.macro_items.len() - 1);
-                                    state.add_release_for_all_unreleased_presses();
-                                    self.dynamic_macros
-                                        .insert(state.starting_macro_id, state.macro_items.clone());
-                                    if state.starting_macro_id == *macro_id {
-                                        log::info!(
-                                            "same macro id pressed. saving and stopping dynamic macro {} recording",
-                                            state.starting_macro_id
-                                        );
-                                        stop_record = true;
-                                    } else {
-                                        log::info!(
-                                            "saving dynamic macro {} recording then starting new macro recording {macro_id}",
-                                            state.starting_macro_id,
-                                        );
-                                        new_recording = Some(macro_id);
-                                    }
+                    }
+                    CustomAction::SequenceNoerase(..) => {}
+                    CustomAction::Repeat => {
+                        let keycode = self.last_pressed_key;
+                        let osc: OsCode = keycode.into();
+                        log::debug!("repeating a keypress {osc:?}");
+                        let mut do_caps_word = false;
+                        if !cur_keys.contains(&KeyCode::LShift)
+                            && let Some(ref mut cw) = self.caps_word {
+                                cur_keys.push(keycode);
+                                let prev_len = cur_keys.len();
+                                cw.tick_maybe_add_lsft(cur_keys);
+                                if cur_keys.len() > prev_len {
+                                    do_caps_word = true;
+                                    press_key(&mut self.kbd_out, OsCode::KEY_LEFTSHIFT)?;
                                 }
                             }
-                            if stop_record {
-                                self.dynamic_macro_record_state = None;
-                            } else if let Some(macro_id) = new_recording {
-                                log::info!("starting new dynamic macro {macro_id} recording");
-                                self.dynamic_macro_record_state = Some(DynamicMacroRecordState {
-                                    starting_macro_id: *macro_id,
-                                    macro_items: vec![],
-                                });
-                            }
+                        // Release key in case the most recently pressed key is still pressed.
+                        release_key(&mut self.kbd_out, osc)?;
+                        press_key(&mut self.kbd_out, osc)?;
+                        release_key(&mut self.kbd_out, osc)?;
+                        if do_caps_word {
+                            self.kbd_out.release_key(OsCode::KEY_LEFTSHIFT)?;
                         }
-                        CustomAction::DynamicMacroRecordStop(num_actions_to_remove) => {
-                            if let Some(state) = &mut self.dynamic_macro_record_state {
-                                // remove the last item independently of `num_actions_to_remove`
-                                // since it's almost certainly a "macro record stop" key press
-                                // action which we don't want to keep.
-                                state.macro_items.remove(state.macro_items.len() - 1);
-                                log::info!(
-                                    "saving and stopping dynamic macro {} recording with {num_actions_to_remove} actions at the end removed",
-                                    state.starting_macro_id,
-                                );
-                                state.macro_items.truncate(
-                                    state
-                                        .macro_items
-                                        .len()
-                                        .saturating_sub(*num_actions_to_remove as usize),
-                                );
-                                state.add_release_for_all_unreleased_presses();
-                                self.dynamic_macros
-                                    .insert(state.starting_macro_id, state.macro_items.clone());
-                            }
-                            self.dynamic_macro_record_state = None;
+                    }
+                    CustomAction::DynamicMacroRecord(macro_id) => {
+                        if let Some((macro_id, prev_recorded_macro)) =
+                            begin_record_macro(*macro_id, &mut self.dynamic_macro_record_state)
+                        {
+                            log::debug!("saving macro {prev_recorded_macro:?}");
+                            self.dynamic_macros.insert(macro_id, prev_recorded_macro);
                         }
-                        CustomAction::DynamicMacroPlay(macro_id) => {
-                            match &mut self.dynamic_macro_replay_state {
-                                None => {
-                                    log::info!("replaying macro {macro_id}");
-                                    self.dynamic_macro_replay_state =
-                                        self.dynamic_macros.get(macro_id).map(|macro_items| {
-                                            let mut active_macros = HashSet::default();
-                                            active_macros.insert(*macro_id);
-                                            DynamicMacroReplayState {
-                                                active_macros,
-                                                delay_remaining: 0,
-                                                macro_items: macro_items.clone().into(),
-                                            }
-                                        });
-                                }
-                                Some(state) => {
-                                    if state.active_macros.contains(macro_id) {
-                                        log::warn!("refusing to recurse into macro {macro_id}");
-                                    } else if let Some(items) = self.dynamic_macros.get(macro_id) {
-                                        log::debug!(
-                                            "prepending macro {macro_id} items to current replay"
-                                        );
-                                        state.active_macros.insert(*macro_id);
-                                        state
-                                            .macro_items
-                                            .push_front(DynamicMacroItem::EndMacro(*macro_id));
-                                        for item in items.iter().copied().rev() {
-                                            state.macro_items.push_front(item);
-                                        }
-                                    }
-                                }
-                            }
+                    }
+                    CustomAction::DynamicMacroRecordStop(num_actions_to_remove) => {
+                        if let Some((macro_id, prev_recorded_macro)) = stop_macro(
+                            &mut self.dynamic_macro_record_state,
+                            *num_actions_to_remove,
+                        ) {
+                            log::debug!("saving macro {prev_recorded_macro:?}");
+                            self.dynamic_macros.insert(macro_id, prev_recorded_macro);
                         }
-                        CustomAction::SendArbitraryCode(code) => {
+                    }
+                    CustomAction::DynamicMacroPlay(macro_id) => {
+                        play_macro(
+                            *macro_id,
+                            &mut self.dynamic_macro_replay_state,
+                            &self.dynamic_macros,
+                        );
+                    }
+                    CustomAction::CancelMacroOnNextPress(duration) => {
+                        self.macro_on_press_cancel_duration = *duration;
+                    }
+                    CustomAction::SendArbitraryCode(code) => {
+                        #[cfg(all(not(feature = "simulated_output"), target_os = "windows"))]
+                        {
+                            self.kbd_out.write_code_raw(*code, KeyValue::Press)?;
+                        }
+                        #[cfg(any(feature = "simulated_output", not(target_os = "windows")))]
+                        {
                             self.kbd_out.write_code(*code as u32, KeyValue::Press)?;
                         }
-                        CustomAction::CapsWord(cfg) => {
+                    }
+                    CustomAction::CapsWord(cfg) => match cfg.repress_behaviour {
+                        CapsWordRepressBehaviour::Overwrite => {
+                            log::trace!("caps-word overwrite");
                             self.caps_word = Some(CapsWordState::new(cfg));
                         }
-                        CustomAction::SetMouse { x, y } => {
-                            self.kbd_out.set_mouse(*x, *y)?;
+                        CapsWordRepressBehaviour::Toggle => {
+                            log::trace!("caps-word toggle");
+                            self.caps_word = match self.caps_word {
+                                Some(_) => None,
+                                None => Some(CapsWordState::new(cfg)),
+                            };
                         }
-                        CustomAction::FakeKeyOnRelease { .. }
-                        | CustomAction::DelayOnRelease(_)
-                        | CustomAction::CancelMacroOnRelease => {}
+                    },
+                    CustomAction::SetMouse { x, y } => {
+                        self.kbd_out.set_mouse(*x, *y)?;
+                    }
+                    CustomAction::FakeKeyOnIdle(fkd) => {
+                        self.ticks_since_idle = 0;
+                        self.waiting_for_idle.insert(*fkd);
+                    }
+                    CustomAction::FakeKeyOnPhysicalIdle(fkd) => {
+                        self.ticks_since_physical_idle = 0;
+                        self.waiting_for_physical_idle.insert(*fkd);
+                    }
+                    CustomAction::FakeKeyHoldForDuration(fk_hfd) => {
+                        let duration = fk_hfd.hold_duration;
+                        self.vkeys_pending_release.entry(fk_hfd.coord)
+                            .and_modify(|d| *d = duration)
+                            .or_insert_with(|| {
+                                let Coord { x, y } = fk_hfd.coord;
+                                layout.event(Event::Press(x, y));
+                                duration
+                            });
                     }
+                    CustomAction::ClipboardSet(clipboard_string) => {
+                        clpb_set(clipboard_string);
+                    }
+                    CustomAction::ClipboardCmdSet(cmd_params) => {
+                        clpb_cmd_set(cmd_params);
+                    }
+                    CustomAction::ClipboardSave(id) => {
+                        clpb_save(*id, &mut self.saved_clipboard_content);
+                    }
+                    CustomAction::ClipboardRestore(id) => {
+                        clpb_restore(*id, &self.saved_clipboard_content);
+                    }
+                    CustomAction::ClipboardSaveSet(id, clipboard_string) => {
+                        clpb_save_set(*id, clipboard_string, &mut self.saved_clipboard_content);
+                    }
+                    CustomAction::ClipboardSaveCmdSet(id, cmd_params) => {
+                        clpb_save_cmd_set(*id, cmd_params, &mut self.saved_clipboard_content);
+                    }
+                    CustomAction::ClipboardSaveSwap(id1, id2) => {
+                        clpb_save_swap(*id1, *id2, &mut self.saved_clipboard_content);
+                    }
+                    CustomAction::FakeKeyOnRelease { .. }
+                    | CustomAction::DelayOnRelease(_)
+                    | CustomAction::Unmodded { .. }
+                    | CustomAction::Unshifted { .. }
+                    // Note: ReverseReleaseOrder is already handled earlier on.
+                    | CustomAction::ReverseReleaseOrder
+                    | CustomAction::CancelMacroOnRelease => {}
                 }
                 #[cfg(feature = "cmd")]
                 run_multi_cmd(cmds);
-            }
 
-            CustomEvent::Release(custacts) => {
-                // Unclick only the last mouse button
-                if let Some(Err(e)) = custacts
-                    .iter()
-                    .fold(None, |pbtn, ac| match ac {
-                        CustomAction::Mouse(btn) => Some(btn),
-                        CustomAction::MWheel { direction, .. } => {
-                            match direction {
-                                MWheelDirection::Up | MWheelDirection::Down => {
-                                    if let Some(ss) = &self.scroll_state {
-                                        if ss.direction == *direction {
-                                            self.scroll_state = None;
-                                        }
-                                    }
-                                }
-                                MWheelDirection::Left | MWheelDirection::Right => {
-                                    if let Some(ss) = &self.hscroll_state {
-                                        if ss.direction == *direction {
-                                            self.hscroll_state = None;
-                                        }
-                                    }
-                                }
-                            }
-                            pbtn
+                // Process reload actions after releasing the layout borrow
+                if let Some(action) = reload_action {
+                    let reload_succeeded = match action {
+                        ReloadAction::Reload => {
+                            self.request_live_reload();
+                            true
                         }
-                        CustomAction::MoveMouse { direction, .. } => {
-                            match direction {
-                                MoveDirection::Up | MoveDirection::Down => {
-                                    if let Some(move_mouse_state_vertical) =
-                                        &self.move_mouse_state_vertical
-                                    {
-                                        if move_mouse_state_vertical.direction == *direction {
-                                            self.move_mouse_state_vertical = None;
-                                        }
-                                    }
-                                }
-                                MoveDirection::Left | MoveDirection::Right => {
-                                    if let Some(move_mouse_state_horizontal) =
-                                        &self.move_mouse_state_horizontal
-                                    {
-                                        if move_mouse_state_horizontal.direction == *direction {
-                                            self.move_mouse_state_horizontal = None;
-                                        }
-                                    }
-                                }
+                        ReloadAction::ReloadNext => {
+                            self.request_live_reload_next();
+                            true
+                        }
+                        ReloadAction::ReloadPrev => {
+                            self.request_live_reload_prev();
+                            true
+                        }
+                        ReloadAction::ReloadNum(n) => {
+                            if let Err(e) = self.request_live_reload_num(n) {
+                                log::error!("{}", e);
+                                false
+                            } else {
+                                true
                             }
-                            pbtn
                         }
-                        CustomAction::MoveMouseAccel { direction, .. } => {
-                            match direction {
-                                MoveDirection::Up | MoveDirection::Down => {
-                                    if let Some(move_mouse_state_vertical) =
-                                        &self.move_mouse_state_vertical
-                                    {
-                                        if move_mouse_state_vertical.direction == *direction {
-                                            self.move_mouse_state_vertical = None;
-                                        }
-                                    }
-                                }
-                                MoveDirection::Left | MoveDirection::Right => {
-                                    if let Some(move_mouse_state_horizontal) =
-                                        &self.move_mouse_state_horizontal
-                                    {
-                                        if move_mouse_state_horizontal.direction == *direction {
-                                            self.move_mouse_state_horizontal = None;
-                                        }
-                                    }
-                                }
+                        ReloadAction::ReloadFile(path) => {
+                            if let Err(e) = self.request_live_reload_file(path) {
+                                log::error!("{}", e);
+                                false
+                            } else {
+                                true
                             }
-                            pbtn
                         }
-                        CustomAction::Delay(delay) => {
-                            log::debug!("on-press: sleeping for {delay} ms");
-                            std::thread::sleep(std::time::Duration::from_millis((*delay).into()));
-                            pbtn
+                    };
+
+                    if reload_succeeded {
+                        live_reload_requested = true;
+                    }
+                }
+            }
+
+            CustomEvent::Release(custact) => match custact {
+                CustomAction::Mouse(btn) => {
+                    self.kbd_out.release_btn(*btn)?;
+                }
+                CustomAction::MWheel { direction, .. } => match direction {
+                    MWheelDirection::Up | MWheelDirection::Down => {
+                        if let Some(ss) = &mut self.scroll_state
+                            && ss.direction == *direction
+                        {
+                            ss.distance = 0;
+                            if let Some(acs) = &mut ss.scroll_accel_state {
+                                acs.scroll_released = true
+                            }
                         }
-                        CustomAction::FakeKeyOnRelease { coord, action } => {
-                            let (x, y) = (coord.x, coord.y);
-                            log::debug!("fake key on release {action:?} {x:?},{y:?}");
-                            match action {
-                                FakeKeyAction::Press => layout.event(Event::Press(x, y)),
-                                FakeKeyAction::Release => layout.event(Event::Release(x, y)),
-                                FakeKeyAction::Tap => {
-                                    layout.event(Event::Press(x, y));
-                                    layout.event(Event::Release(x, y));
-                                }
+                    }
+                    MWheelDirection::Left | MWheelDirection::Right => {
+                        if let Some(ss) = &mut self.hscroll_state
+                            && ss.direction == *direction
+                        {
+                            ss.distance = 0;
+                            if let Some(acs) = &mut ss.scroll_accel_state {
+                                acs.scroll_released = true
                             }
-                            pbtn
                         }
-                        CustomAction::CancelMacroOnRelease => {
-                            log::debug!("cancelling all macros");
-                            layout.active_sequences.clear();
-                            layout
-                                .states
-                                .retain(|s| !matches!(s, State::FakeKey { .. }));
-                            pbtn
+                    }
+                },
+                CustomAction::MoveMouse { direction, .. }
+                | CustomAction::MoveMouseAccel { direction, .. } => {
+                    match direction {
+                        MoveDirection::Up | MoveDirection::Down => {
+                            if let Some(move_mouse_state_vertical) = &self.move_mouse_state_vertical
+                                && move_mouse_state_vertical.direction == *direction
+                            {
+                                self.move_mouse_state_vertical = None;
+                            }
                         }
-                        CustomAction::SendArbitraryCode(code) => {
-                            if let Err(e) = self.kbd_out.write_code(*code as u32, KeyValue::Release)
+                        MoveDirection::Left | MoveDirection::Right => {
+                            if let Some(move_mouse_state_horizontal) =
+                                &self.move_mouse_state_horizontal
+                                && move_mouse_state_horizontal.direction == *direction
                             {
-                                log::error!("failed to send arbitrary code {e:?}");
+                                self.move_mouse_state_horizontal = None;
                             }
-                            pbtn
                         }
-                        _ => pbtn,
-                    })
-                    .map(|btn| {
-                        log::debug!("unclick   {:?}", btn);
-                        self.kbd_out.release_btn(*btn)
-                    })
-                {
-                    bail!(e);
+                    }
+                    if self.movemouse_smooth_diagonals {
+                        self.movemouse_buffer = None
+                    }
                 }
-            }
-            _ => {}
+                CustomAction::MoveMouseSpeed { speed, .. } => {
+                    if let Some(idx) = self
+                        .move_mouse_speed_modifiers
+                        .iter()
+                        .position(|s| *s == *speed)
+                    {
+                        self.move_mouse_speed_modifiers.remove(idx);
+                    }
+                    log::debug!(
+                        "movemousespeed modifiers: {:?}",
+                        self.move_mouse_speed_modifiers
+                    );
+                }
+                CustomAction::DelayOnRelease(delay) => {
+                    log::debug!("on-release: sleeping for {delay} ms");
+                    std::thread::sleep(time::Duration::from_millis((*delay).into()));
+                }
+                CustomAction::FakeKeyOnRelease { coord, action } => {
+                    let (x, y) = (coord.x, coord.y);
+                    log::debug!("fake key on release {action:?} {x:?},{y:?}");
+                    handle_fakekey_action(*action, layout, x, y);
+                }
+                CustomAction::CancelMacroOnRelease => {
+                    log::debug!("cancelling all macros: releasable macro");
+                    layout.active_sequences.clear();
+                    self.macro_on_press_cancel_duration = 0;
+                    layout.states.retain(|s| {
+                        !matches!(s, State::FakeKey { .. } | State::RepeatingSequence { .. })
+                    });
+                }
+                CustomAction::SendArbitraryCode(code) => {
+                    if let Err(e) = {
+                        #[cfg(all(not(feature = "simulated_output"), target_os = "windows"))]
+                        {
+                            self.kbd_out.write_code_raw(*code, KeyValue::Release)
+                        }
+                        #[cfg(any(feature = "simulated_output", not(target_os = "windows")))]
+                        {
+                            self.kbd_out.write_code(*code as u32, KeyValue::Release)
+                        }
+                    } {
+                        log::error!("failed to release arbitrary code {e:?}");
+                    }
+                }
+                _ => {}
+            },
+            CustomEvent::NoEvent => {}
         };
 
+        self.check_handle_layer_change(_tx);
         self.check_release_non_physical_shift()?;
         Ok(live_reload_requested)
     }
 
-    /// This compares the active keys in the keyberon layout against the potential key outputs for
-    /// corresponding physical key in the configuration. If any of keyberon active keys match any
-    /// potential physical key output, write the repeat event to the OS.
-    fn handle_repeat(&mut self, event: &KeyEvent) -> Result<()> {
-        let ret = self.handle_repeat_actual(event);
-        // The cur_keys Vec is re-used for processing, for efficiency reasons to avoid allocation.
-        // Unlike prev_keys which has useful info for the next call to handle_time_ticks, cur_keys
-        // can be reused and cleared — it just needs to be empty for the next handle_time_ticks
-        // call.
-        self.cur_keys.clear();
-        ret
+    #[cfg(feature = "tcp_server")]
+    pub fn change_layer(&mut self, layer_name: String) {
+        for (i, l) in self.layer_info.iter().enumerate() {
+            if l.name == layer_name {
+                self.layout.bm().set_default_layer(i);
+                return;
+            }
+        }
     }
 
-    fn handle_repeat_actual(&mut self, event: &KeyEvent) -> Result<()> {
-        if self.sequence_state.is_some() {
-            // While in sequence mode, don't send key repeats. I can't imagine it's a helpful use
-            // case for someone trying to type in a sequence that they want to rely on key repeats
-            // to finish a sequence. I suppose one might want to do repeat in order to try and
-            // cancel an input sequence... I'll wait for a user created issue to deal with this.
-            return Ok(());
-        }
-        self.cur_keys.extend(self.layout.bm().keycodes());
-        self.overrides
-            .override_keys(&mut self.cur_keys, &mut self.override_states);
-        let current_layer = self.layout.bm().current_layer();
-        if current_layer % 2 == 1 {
-            // Prioritize checking the active layer in case a layer-while-held is active.
-            if let Some(outputs_for_key) = self.key_outputs[current_layer].get(&event.code) {
-                log::debug!("key outs for active layer-while-held: {outputs_for_key:?};");
-                for kc in outputs_for_key.iter().rev() {
-                    if self.cur_keys.contains(&kc.into()) {
-                        log::debug!("repeat    {:?}", KeyCode::from(*kc));
-                        if let Err(e) = self.kbd_out.write_key(*kc, KeyValue::Repeat) {
-                            bail!("could not write key {:?}", e)
-                        }
-                        return Ok(());
-                    }
-                }
-            } else {
-                log::debug!("empty layer-while-held outputs, probably transparent");
+    /// Request a live reload of the current configuration file.
+    pub fn request_live_reload(&mut self) {
+        self.live_reload_requested = true;
+        log::info!(
+            "Requested live reload of file: {}",
+            self.cfg_paths[self.cur_cfg_idx].display()
+        );
+    }
+
+    /// Handle a client command from TCP server and return a result.
+    /// This centralizes validation logic and provides proper error messages.
+    #[cfg(feature = "tcp_server")]
+    pub fn handle_client_command(
+        &mut self,
+        command: kanata_tcp_protocol::ClientMessage,
+    ) -> Result<()> {
+        use kanata_tcp_protocol::ClientMessage;
+
+        match command {
+            ClientMessage::Reload { .. } => {
+                self.request_live_reload();
+                Ok(())
             }
-        }
-        // Try matching a key on the default layer.
-        //
-        // This code executes in two cases:
-        // 1. current layer is the default layer
-        // 2. current layer is layer-while-held but did not find a match in the code above, e.g. a
-        //    transparent key was pressed.
-        let outputs_for_key =
-            match self.key_outputs[self.layout.bm().default_layer].get(&event.code) {
-                None => return Ok(()),
-                Some(v) => v,
-            };
-        log::debug!("key outs for default layer: {outputs_for_key:?};");
-        for kc in outputs_for_key.iter().rev() {
-            if self.cur_keys.contains(&kc.into()) {
-                log::debug!("repeat    {:?}", KeyCode::from(*kc));
-                if let Err(e) = self.kbd_out.write_key(*kc, KeyValue::Repeat) {
-                    bail!("could not write key {:?}", e)
-                }
-                return Ok(());
+            ClientMessage::ReloadNext { .. } => {
+                self.request_live_reload_next();
+                Ok(())
             }
+            ClientMessage::ReloadPrev { .. } => {
+                self.request_live_reload_prev();
+                Ok(())
+            }
+            ClientMessage::ReloadNum { index, .. } => self.request_live_reload_num(index),
+            ClientMessage::ReloadFile { path, .. } => self.request_live_reload_file(path),
+            _ => {
+                // For non-reload commands, we don't validate here - they're handled directly in tcp_server
+                Ok(())
+            }
+        }
+    }
+
+    /// Request a live reload of the next configuration file.
+    pub fn request_live_reload_next(&mut self) {
+        self.live_reload_requested = true;
+        self.cur_cfg_idx = if self.cur_cfg_idx == self.cfg_paths.len() - 1 {
+            0
+        } else {
+            self.cur_cfg_idx + 1
+        };
+        log::info!(
+            "Requested live reload of next file: {}",
+            self.cfg_paths[self.cur_cfg_idx].display()
+        );
+    }
+
+    /// Request a live reload of the previous configuration file.
+    pub fn request_live_reload_prev(&mut self) {
+        self.live_reload_requested = true;
+        if self.cur_cfg_idx == 0 {
+            self.cur_cfg_idx = self.cfg_paths.len() - 1;
+        } else {
+            self.cur_cfg_idx -= 1;
+        }
+        log::info!(
+            "Requested live reload of previous file: {}",
+            self.cfg_paths[self.cur_cfg_idx].display()
+        );
+    }
+
+    /// Request a live reload of the configuration file at the specified index.
+    pub fn request_live_reload_num(&mut self, index: usize) -> Result<()> {
+        if index >= self.cfg_paths.len() {
+            bail!(
+                "config index {} out of bounds: only {} configs available",
+                index,
+                self.cfg_paths.len()
+            );
         }
+        self.live_reload_requested = true;
+        self.cur_cfg_idx = index;
+        log::info!(
+            "Requested live reload of config file {}: {}",
+            index,
+            self.cfg_paths[self.cur_cfg_idx].display()
+        );
         Ok(())
     }
 
-    pub fn change_layer(&mut self, layer_name: String) {
-        for (i, l) in self.layer_info.iter().enumerate() {
-            if l.name == layer_name {
-                self.layout.bm().set_default_layer(i);
-                return;
-            }
+    /// Request a live reload of the specified configuration file.
+    pub fn request_live_reload_file(&mut self, path: String) -> Result<()> {
+        let new_path = std::path::PathBuf::from(&path);
+        if !new_path.exists() {
+            bail!("config file does not exist: {}", path);
         }
+        self.live_reload_requested = true;
+        self.cfg_paths.push(new_path);
+        self.cur_cfg_idx = self.cfg_paths.len() - 1;
+        log::info!(
+            "Requested live reload of file: {}",
+            self.cfg_paths[self.cur_cfg_idx].display()
+        );
+        Ok(())
     }
 
+    #[allow(unused_variables)]
     /// Prints the layer. If the TCP server is enabled, then this will also send a notification to
     /// all connected clients.
     fn check_handle_layer_change(&mut self, tx: &Option<Sender<ServerMessage>>) {
@@ -1366,14 +2118,17 @@ impl Kanata {
             self.prev_layer = cur_layer;
             self.print_layer(cur_layer);
 
+            #[cfg(feature = "tcp_server")]
             if let Some(tx) = tx {
-                match tx.send(ServerMessage::LayerChange { new }) {
+                match tx.try_send(ServerMessage::LayerChange { new }) {
                     Ok(_) => {}
                     Err(error) => {
                         log::error!("could not send event notification: {}", error);
                     }
                 }
             }
+            #[cfg(all(target_os = "windows", feature = "gui"))]
+            send_gui_notice();
         }
     }
 
@@ -1383,10 +2138,30 @@ impl Kanata {
         }
     }
 
+    #[cfg(feature = "tcp_server")]
+    /// Get engine uptime in seconds
+    pub fn get_uptime_s(&self) -> u64 {
+        self.start_time.elapsed().as_secs()
+    }
+
+    #[cfg(feature = "tcp_server")]
+    /// Check if a reload has completed (regardless of success or failure)
+    pub fn is_reload_complete(&self) -> bool {
+        !self.live_reload_requested
+    }
+
+    #[cfg(feature = "tcp_server")]
+    /// Whether the most recent reload succeeded.
+    pub fn last_reload_succeeded(&self) -> bool {
+        self.last_reload_ok
+    }
+
+    #[cfg(feature = "tcp_server")]
     pub fn start_notification_loop(
         rx: Receiver<ServerMessage>,
-        clients: Arc<Mutex<HashMap<String, TcpStream>>>,
+        clients: crate::tcp_server::Connections,
     ) {
+        use std::io::Write;
         info!("listening for event notifications to relay to connected clients");
         std::thread::spawn(move || {
             loop {
@@ -1399,11 +2174,14 @@ impl Kanata {
                         let mut clients = clients.lock();
                         let mut stale_clients = vec![];
                         for (id, client) in &mut *clients {
-                            match client.write(&notification) {
+                            match client.write_all(&notification) {
                                 Ok(_) => {
                                     log::debug!("layer change notification sent");
                                 }
-                                Err(_) => {
+                                Err(e) => {
+                                    log::warn!(
+                                        "removing tcp client where write failed: {id}, {e:?}"
+                                    );
                                     // the client is no longer connected, let's remove them
                                     stale_clients.push(id.clone());
                                 }
@@ -1420,6 +2198,13 @@ impl Kanata {
         });
     }
 
+    #[cfg(not(feature = "tcp_server"))]
+    pub fn start_notification_loop(
+        _rx: Receiver<ServerMessage>,
+        _clients: crate::tcp_server::Connections,
+    ) {
+    }
+
     /// Starts a new thread that processes OS key events and advances the keyberon layout's state.
     pub fn start_processing_loop(
         kanata: Arc<Mutex<Self>>,
@@ -1429,37 +2214,128 @@ impl Kanata {
     ) {
         info!("entering the processing loop");
         std::thread::spawn(move || {
+            // Elevate the processing thread to the highest QoS class so that
+            // CPU-intensive background work (compilation, indexing, etc.) does
+            // not starve the 1 ms tick loop. Without this, delayed key-release
+            // processing causes the OS to autorepeat keys that the user has
+            // already released physically. Windows does the equivalent with
+            // REALTIME_PRIORITY_CLASS (see new() above).
+            #[cfg(target_os = "macos")]
+            {
+                let rc = unsafe {
+                    libc::pthread_set_qos_class_self_np(
+                        libc::qos_class_t::QOS_CLASS_USER_INTERACTIVE,
+                        0,
+                    )
+                };
+                if rc == 0 {
+                    info!("macOS: processing thread QoS set to USER_INTERACTIVE");
+                } else {
+                    log::warn!("macOS: failed to set processing thread QoS (rc={rc})");
+                }
+            }
             if !nodelay {
                 info!("Init: catching only releases and sending immediately");
                 for _ in 0..500 {
-                    if let Ok(kev) = rx.try_recv() {
-                        if kev.value == KeyValue::Release {
-                            let mut k = kanata.lock();
-                            info!("Init: releasing {:?}", kev.code);
-                            k.kbd_out.release_key(kev.code).expect("key released");
-                        }
+                    if let Ok(kev) = rx.try_recv()
+                        && kev.value == KeyValue::Release
+                    {
+                        let mut k = kanata.lock();
+                        info!("Init: releasing {:?}", kev.code);
+                        k.kbd_out.release_key(kev.code).expect("key released");
                     }
                     std::thread::sleep(time::Duration::from_millis(1));
                 }
             }
+            let mut ms_elapsed = 0;
 
             info!("Starting kanata proper");
+
+            #[cfg(not(feature = "passthru_ahk"))]
+            info!(
+                "You may forcefully exit kanata by pressing lctl+spc+esc at any time. \
+                        These keys refer to defsrc input, meaning BEFORE kanata remaps keys."
+            );
+
+            #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+            let mut idle_clear_happened = false;
+            #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+            let mut last_input_time = web_time::Instant::now();
+
+            let mut events = Vec::new();
             let err = loop {
-                if kanata.lock().can_block() {
+                let can_block = {
+                    let mut k = kanata.lock();
+                    k.can_block_update_idle_waiting(ms_elapsed)
+                };
+                if can_block {
+                    #[cfg(all(
+                        target_os = "windows",
+                        not(feature = "interception_driver"),
+                        not(feature = "simulated_input"),
+                    ))]
+                    kanata.lock().win_synchronize_keystates();
+
                     log::trace!("blocking on channel");
                     match rx.recv() {
                         Ok(kev) => {
+                            collect_and_sort_events(kev, &rx, &mut events);
+
                             let mut k = kanata.lock();
-                            k.last_tick = time::Instant::now()
+                            let now = web_time::Instant::now()
                                 .checked_sub(time::Duration::from_millis(1))
                                 .expect("subtract 1ms from current time");
 
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            clear_states_from_inactivity(
+                                &mut k,
+                                now,
+                                last_input_time,
+                                &mut idle_clear_happened,
+                            );
+                            k.last_tick = now;
+
+                            // Check for live reload BEFORE processing the key event
+                            if k.live_reload_requested
+                                && ((k.prev_keys.is_empty() && k.cur_keys.is_empty())
+                                    || k.ticks_since_idle > 1000)
+                            {
+                                k.live_reload_requested = false;
+                                if let Err(e) = k.do_live_reload(&tx) {
+                                    log::error!("live reload failed {e}");
+                                }
+                            }
+
                             #[cfg(feature = "perf_logging")]
-                            let start = std::time::Instant::now();
+                            let start = web_time::Instant::now();
 
-                            if let Err(e) = k.handle_key_event(&kev) {
+                            let mut event_error = None;
+                            for ev in &events {
+                                if let Err(e) = k.handle_input_event(ev) {
+                                    event_error = Some(e);
+                                    break;
+                                }
+                            }
+                            if let Some(e) = event_error {
                                 break e;
                             }
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            {
+                                last_input_time = now;
+                            }
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            {
+                                idle_clear_happened = false;
+                            }
 
                             #[cfg(feature = "perf_logging")]
                             log::info!(
@@ -1467,11 +2343,12 @@ impl Kanata {
                                 (start.elapsed()).as_nanos()
                             );
                             #[cfg(feature = "perf_logging")]
-                            let start = std::time::Instant::now();
+                            let start = web_time::Instant::now();
 
-                            if let Err(e) = k.handle_time_ticks(&tx) {
-                                break e;
-                            }
+                            match k.handle_time_ticks(&tx) {
+                                Ok(ms) => ms_elapsed = ms,
+                                Err(e) => break e,
+                            };
 
                             #[cfg(feature = "perf_logging")]
                             log::info!(
@@ -1485,15 +2362,49 @@ impl Kanata {
                         }
                     }
                 } else {
-                    let mut k = kanata.lock();
                     match rx.try_recv() {
                         Ok(kev) => {
+                            collect_and_sort_events(kev, &rx, &mut events);
+
+                            let mut k = kanata.lock();
+                            // Check for live reload BEFORE processing the key event
+                            if k.live_reload_requested
+                                && ((k.prev_keys.is_empty() && k.cur_keys.is_empty())
+                                    || k.ticks_since_idle > 1000)
+                            {
+                                k.live_reload_requested = false;
+                                if let Err(e) = k.do_live_reload(&tx) {
+                                    log::error!("live reload failed {e}");
+                                }
+                            }
+
                             #[cfg(feature = "perf_logging")]
-                            let start = std::time::Instant::now();
+                            let start = web_time::Instant::now();
 
-                            if let Err(e) = k.handle_key_event(&kev) {
+                            let mut event_error = None;
+                            for ev in &events {
+                                if let Err(e) = k.handle_input_event(ev) {
+                                    event_error = Some(e);
+                                    break;
+                                }
+                            }
+                            if let Some(e) = event_error {
                                 break e;
                             }
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            {
+                                last_input_time = web_time::Instant::now();
+                            }
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            {
+                                idle_clear_happened = false;
+                            }
 
                             #[cfg(feature = "perf_logging")]
                             log::info!(
@@ -1501,11 +2412,12 @@ impl Kanata {
                                 (start.elapsed()).as_nanos()
                             );
                             #[cfg(feature = "perf_logging")]
-                            let start = std::time::Instant::now();
+                            let start = web_time::Instant::now();
 
-                            if let Err(e) = k.handle_time_ticks(&tx) {
-                                break e;
-                            }
+                            match k.handle_time_ticks(&tx) {
+                                Ok(ms) => ms_elapsed = ms,
+                                Err(e) => break e,
+                            };
 
                             #[cfg(feature = "perf_logging")]
                             log::info!(
@@ -1514,12 +2426,15 @@ impl Kanata {
                             );
                         }
                         Err(TryRecvError::Empty) => {
+                            let mut k = kanata.lock();
+
                             #[cfg(feature = "perf_logging")]
-                            let start = std::time::Instant::now();
+                            let start = web_time::Instant::now();
 
-                            if let Err(e) = k.handle_time_ticks(&tx) {
-                                break e;
-                            }
+                            match k.handle_time_ticks(&tx) {
+                                Ok(ms) => ms_elapsed = ms,
+                                Err(e) => break e,
+                            };
 
                             #[cfg(feature = "perf_logging")]
                             log::info!(
@@ -1527,6 +2442,17 @@ impl Kanata {
                                 (start.elapsed()).as_nanos()
                             );
 
+                            #[cfg(all(
+                                not(feature = "interception_driver"),
+                                target_os = "windows"
+                            ))]
+                            clear_states_from_inactivity(
+                                &mut k,
+                                web_time::Instant::now(),
+                                last_input_time,
+                                &mut idle_clear_happened,
+                            );
+
                             drop(k);
                             std::thread::sleep(time::Duration::from_millis(1));
                         }
@@ -1541,99 +2467,639 @@ impl Kanata {
         });
     }
 
-    pub fn can_block(&self) -> bool {
-        self.layout.b().queue.is_empty()
-            && self.layout.b().waiting.is_none()
-            && self.layout.b().last_press_tracker.tap_hold_timeout == 0
-            && (self.layout.b().oneshot.timeout == 0 || self.layout.b().oneshot.keys.is_empty())
-            && self.layout.b().active_sequences.is_empty()
-            && self.layout.b().tap_dance_eager.is_none()
-            && self.sequence_state.is_none()
+    /// Returns `true` if kanata's processing thread loop can block on the channel instead of doing
+    /// a non-blocking channel read and then sleeping for ~1ms.
+    ///
+    /// In addition to doing the logic for the above, this mutates the `waiting_for_idle` state
+    /// used by the `on-idle` action for virtual keys.
+    pub fn can_block_update_idle_waiting(&mut self, ms_elapsed: u16) -> bool {
+        let k = self;
+        let is_idle = k.is_idle();
+        // Note: checking waiting_for_idle can not be part of the computation for
+        // is_idle() since incrementing ticks_since_idle is dependent on the return
+        // value of is_idle().
+        let counting_idle_ticks = !k.waiting_for_idle.is_empty() || k.live_reload_requested;
+        if !is_idle {
+            k.ticks_since_idle = 0;
+        } else if is_idle && counting_idle_ticks {
+            k.ticks_since_idle = k.ticks_since_idle.saturating_add(ms_elapsed);
+            #[cfg(feature = "perf_logging")]
+            log::info!("ticks since idle: {}", k.ticks_since_idle);
+        }
+
+        let counting_physical_idle_ticks = if k.waiting_for_physical_idle.is_empty() {
+            false
+        } else {
+            let is_physical_idle = PRESSED_KEYS.lock().is_empty();
+            if is_physical_idle {
+                k.ticks_since_physical_idle =
+                    k.ticks_since_physical_idle.saturating_add(ms_elapsed);
+            } else {
+                k.ticks_since_physical_idle = 0;
+            }
+            true
+        };
+
+        // NOTE: this check must not be part of `is_idle` because its falsiness
+        // does not mean that kanata is in a non-idle state, just that we
+        // haven't done enough ticks yet to properly compute key-timing.
+        let passed_max_timing_check = k
+            .layout
+            .b()
+            .historical_keys
+            .iter_hevents()
+            .next()
+            .map(|he| he.ticks_since_occurrence >= k.max_key_timing_check)
+            .unwrap_or(true);
+        let chordsv2_accepts_chords = k
+            .layout
+            .b()
+            .chords_v2
+            .as_ref()
+            .map(|cv2| cv2.accepts_chords_chv2())
+            .unwrap_or(true);
+        is_idle
+            && !counting_idle_ticks
+            && !counting_physical_idle_ticks
+            && passed_max_timing_check
+            && chordsv2_accepts_chords
+    }
+
+    pub fn is_idle(&self) -> bool {
+        let pressed_keys_means_not_idle =
+            !self.waiting_for_idle.is_empty() || self.live_reload_requested;
+        let layout = self.layout.b();
+        layout.queue.is_empty()
+            && zippy_is_idle()
+            && layout.waiting.is_none()
+            && layout.last_press_tracker.tap_hold_timeout == 0
+            && (layout.oneshot.timeout == 0 || layout.oneshot.keys.is_empty())
+            && layout.active_sequences.is_empty()
+            && layout.tap_dance_eager.is_none()
+            && layout.action_queue.is_empty()
+            && layout.custom_event_release_queue.is_empty()
+            && self.sequence_state.is_inactive()
             && self.scroll_state.is_none()
             && self.hscroll_state.is_none()
             && self.move_mouse_state_vertical.is_none()
+            && self.macro_on_press_cancel_duration == 0
             && self.move_mouse_state_horizontal.is_none()
             && self.dynamic_macro_replay_state.is_none()
             && self.caps_word.is_none()
-            && !self
-                .layout
-                .b()
-                .states
-                .iter()
-                .any(|s| matches!(s, State::SeqCustomPending(_) | State::SeqCustomActive(_)))
+            && self.vkeys_pending_release.is_empty()
+            && !layout.states.iter().any(|s| {
+                matches!(s, State::SeqCustomPending(_) | State::SeqCustomActive(_))
+                    || (pressed_keys_means_not_idle && matches!(s, State::NormalKey { .. }))
+            })
+            && layout
+                .chords_v2
+                .as_ref()
+                .map(|cv2| cv2.is_idle_chv2())
+                .unwrap_or(true)
     }
 }
 
-fn set_altgr_behaviour(_cfg: &cfg::Cfg) -> Result<()> {
-    #[cfg(target_os = "windows")]
-    set_win_altgr_behaviour(_cfg)?;
-    Ok(())
+#[test]
+fn test_unmodmods_bits() {
+    assert_eq!(UnmodMods::empty().bits(), 0u8);
+    assert_eq!(UnmodMods::all().bits(), 255u8);
 }
 
 #[cfg(feature = "cmd")]
-fn run_multi_cmd(cmds: Vec<Vec<String>>) {
+fn run_multi_cmd(cmds: Vec<(Option<log::Level>, Option<log::Level>, Vec<String>)>) {
     std::thread::spawn(move || {
-        for cmd in cmds {
-            if let Err(e) = run_cmd_in_thread(cmd).join() {
+        for (cmd_log_level, cmd_error_log_level, cmd) in cmds {
+            if let Err(e) = run_cmd_in_thread(cmd, cmd_log_level, cmd_error_log_level).join() {
                 log::error!("problem joining thread {:?}", e);
             }
         }
     });
 }
 
+fn apply_mouse_distance_modifiers(initial_distance: u16, mods: &Vec<u16>) -> u16 {
+    let mut scaled_distance = initial_distance;
+    for &modifier in mods {
+        scaled_distance = u16::max(
+            1,
+            f32::min(
+                scaled_distance as f32 * (modifier as f32 / 100f32),
+                u16::MAX as f32,
+            )
+            .round() as u16,
+        );
+    }
+    scaled_distance
+}
+
+#[test]
+fn apply_speed_modifiers() {
+    assert_eq!(apply_mouse_distance_modifiers(15, &vec![]), 15);
+
+    assert_eq!(apply_mouse_distance_modifiers(10, &vec![200u16]), 20);
+    assert_eq!(apply_mouse_distance_modifiers(20, &vec![50u16]), 10);
+
+    assert_eq!(apply_mouse_distance_modifiers(5, &vec![33u16]), 2); // 1.65
+    assert_eq!(apply_mouse_distance_modifiers(100, &vec![99u16]), 99);
+
+    // Clamping
+    assert_eq!(
+        apply_mouse_distance_modifiers(65535, &vec![65535u16]),
+        65535
+    );
+    assert_eq!(apply_mouse_distance_modifiers(1, &vec![1u16]), 1);
+
+    // Nice, round calculations equal themselves
+    assert_eq!(
+        apply_mouse_distance_modifiers(10, &vec![50u16, 200u16]),
+        apply_mouse_distance_modifiers(10, &vec![200u16, 50u16])
+    );
+
+    // 33% of 20
+    assert_eq!(apply_mouse_distance_modifiers(10, &vec![200u16, 33u16]), 7);
+    // 200% of 3
+    assert_eq!(apply_mouse_distance_modifiers(10, &vec![33u16, 200u16]), 6);
+}
+
+#[cfg(feature = "passthru_ahk")]
+/// Clean kanata's state without exiting
+pub fn clean_state(kanata: &Arc<Mutex<Kanata>>, tick: u128) -> Result<()> {
+    let mut k = kanata.lock();
+    #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+    let layout = k.layout.bm();
+    #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+    release_normalkey_states(layout);
+    k.tick_ms(tick, &None)?;
+    #[cfg(not(any(target_os = "linux", target_os = "android")))]
+    {
+        let mut k_pressed = PRESSED_KEYS.lock();
+        for key_os in k_pressed.clone() {
+            #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+            k.kbd_out.release_key(key_os)?;
+            #[cfg(all(target_os = "windows", not(feature = "interception_driver")))]
+            k.kbd_out.release_key(key_os.0)?;
+        }
+        k_pressed.clear();
+    }
+    Ok(())
+}
+
 /// Checks if kanata should exit based on the fixed key combination of:
 /// Lctl+Spc+Esc
-fn check_for_exit(event: &KeyEvent) {
-    static IS_LCL_PRESSED: AtomicBool = AtomicBool::new(false);
-    static IS_SPC_PRESSED: AtomicBool = AtomicBool::new(false);
-    static IS_ESC_PRESSED: AtomicBool = AtomicBool::new(false);
-    let is_pressed = match event.value {
-        KeyValue::Press => true,
-        KeyValue::Release => false,
-        _ => return,
-    };
-    match event.code {
-        OsCode::KEY_ESC => IS_ESC_PRESSED.store(is_pressed, SeqCst),
-        OsCode::KEY_SPACE => IS_SPC_PRESSED.store(is_pressed, SeqCst),
-        OsCode::KEY_LEFTCTRL => IS_LCL_PRESSED.store(is_pressed, SeqCst),
-        _ => return,
-    }
-    const EXIT_MSG: &str = "pressed LControl+Space+Escape, exiting";
-    if IS_ESC_PRESSED.load(SeqCst) && IS_SPC_PRESSED.load(SeqCst) && IS_LCL_PRESSED.load(SeqCst) {
-        #[cfg(not(target_os = "linux"))]
-        {
-            log::info!("{EXIT_MSG}");
-            panic!("{EXIT_MSG}");
+fn check_for_exit(_event: &KeyEvent) {
+    #[cfg(not(feature = "passthru_ahk"))]
+    {
+        use std::sync::atomic::{AtomicBool, Ordering::SeqCst};
+        static IS_LCL_PRESSED: AtomicBool = AtomicBool::new(false);
+        static IS_SPC_PRESSED: AtomicBool = AtomicBool::new(false);
+        static IS_ESC_PRESSED: AtomicBool = AtomicBool::new(false);
+        let is_pressed = match _event.value {
+            KeyValue::Press => true,
+            KeyValue::Release => false,
+            _ => return,
+        };
+        match _event.code {
+            OsCode::KEY_ESC => IS_ESC_PRESSED.store(is_pressed, SeqCst),
+            OsCode::KEY_SPACE => IS_SPC_PRESSED.store(is_pressed, SeqCst),
+            OsCode::KEY_LEFTCTRL => IS_LCL_PRESSED.store(is_pressed, SeqCst),
+            _ => return,
         }
-        #[cfg(target_os = "linux")]
+        const EXIT_MSG: &str = "pressed LControl+Space+Escape, exiting";
+        if IS_ESC_PRESSED.load(SeqCst) && IS_SPC_PRESSED.load(SeqCst) && IS_LCL_PRESSED.load(SeqCst)
         {
             log::info!("{EXIT_MSG}");
-            signal_hook::low_level::raise(signal_hook::consts::SIGTERM).expect("raise signal");
+            #[cfg(all(target_os = "windows", feature = "gui"))]
+            {
+                #[cfg(not(feature = "interception_driver"))]
+                native_windows_gui::stop_thread_dispatch();
+                #[cfg(feature = "interception_driver")]
+                send_gui_exit_notice(); // interception driver is running in another thread to allow
+                // GUI take the main one, so it's calling check_for_exit
+                // from a thread that has no access to the main one, so
+                // can't stop main thread's dispatch
+            }
+            // macOS: use `libc::_exit` instead of `std::process::exit` to
+            // skip C++ static destructors. The underlying pqrs shared
+            // dispatcher (used by the karabiner-driverkit crate) has a
+            // teardown race where its destructor kills its own worker
+            // threads while they still hold a `std::mutex`, which then
+            // throws `std::system_error: mutex lock failed` on
+            // `pthread_mutex_destroy`. That exception is uncaught and
+            // aborts the process with a cryptic libc++abi message right
+            // after the user's kill chord. `_exit` bypasses the whole
+            // mess by jumping straight to the kernel exit syscall.
+            //
+            // Flush stdio first so any buffered log output (including the
+            // "exiting" line we just emitted) actually reaches the user.
+            #[cfg(target_os = "macos")]
+            {
+                use std::io::Write;
+                let _ = std::io::stderr().flush();
+                let _ = std::io::stdout().flush();
+                let code = EMERGENCY_EXIT_CODE.load(std::sync::atomic::Ordering::SeqCst);
+                // SAFETY: `_exit` has no preconditions; it terminates the
+                // process immediately without running user destructors.
+                unsafe {
+                    libc::_exit(code);
+                }
+            }
+            // Linux/Android: Use SIGTERM to trigger signal handler for cleanup
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            {
+                signal_hook::low_level::raise(signal_hook::consts::SIGTERM).expect("raise signal");
+            }
+            // Windows non-GUI: Direct exit (no cleanup needed)
+            #[cfg(all(target_os = "windows", not(feature = "gui")))]
+            {
+                let code = EMERGENCY_EXIT_CODE.load(std::sync::atomic::Ordering::SeqCst);
+                std::process::exit(code);
+            }
+            // Unsupported platforms: panic to indicate emergency exit isn't implemented
+            #[cfg(not(any(
+                target_os = "macos",
+                target_os = "linux",
+                target_os = "android",
+                target_os = "windows"
+            )))]
+            {
+                panic!("{EXIT_MSG}");
+            }
         }
     }
 }
 
-fn update_kbd_out(_cfg: &HashMap<String, String>, _kbd_out: &KbdOut) -> Result<()> {
-    #[cfg(target_os = "linux")]
+fn update_kbd_out(_cfg: &CfgOptions, _kbd_out: &KbdOut) -> Result<()> {
+    #[cfg(all(
+        not(feature = "simulated_output"),
+        any(target_os = "linux", target_os = "android")
+    ))]
     {
-        _kbd_out.update_unicode_termination(
-                _cfg.get("linux-unicode-termination").map(|s| {
-                match s.as_str() {
-                    "enter" => Ok(UnicodeTermination::Enter),
-                    "space" => Ok(UnicodeTermination::Space),
-                    "enter-space" => Ok(UnicodeTermination::EnterSpace),
-                    "space-enter" => Ok(UnicodeTermination::SpaceEnter),
-                    _ => Err(anyhow!("linux-unicode-termination got {s}. It accepts: enter|space|enter-space|space-enter")),
-                }
-            }).unwrap_or(Ok(_kbd_out.unicode_termination.get()))?);
-        _kbd_out.update_unicode_u_code(
-            _cfg.get("linux-unicode-u-code")
-                .map(|s| {
-                    str_to_oscode(s)
-                        .ok_or_else(|| anyhow!("unknown code for linux-unicode-u-code {s}"))
-                })
-                .unwrap_or(Ok(_kbd_out.unicode_u_code.get()))?,
-        );
+        _kbd_out.update_unicode_termination(_cfg.linux_opts.linux_unicode_termination);
+        _kbd_out.update_unicode_u_code(_cfg.linux_opts.linux_unicode_u_code);
     }
     Ok(())
 }
+
+pub fn handle_fakekey_action<'a, const C: usize, const R: usize, T>(
+    action: FakeKeyAction,
+    layout: &mut Layout<'a, C, R, T>,
+    x: u8,
+    y: u16,
+) where
+    T: 'a + std::fmt::Debug + Copy,
+{
+    match action {
+        FakeKeyAction::Press => layout.event(Event::Press(x, y)),
+        FakeKeyAction::Release => layout.event(Event::Release(x, y)),
+        FakeKeyAction::Tap => {
+            layout.event(Event::Press(x, y));
+            layout.event(Event::Release(x, y));
+        }
+        FakeKeyAction::Toggle => {
+            match states_has_coord(&layout.states, x, y) {
+                true => layout.event(Event::Release(x, y)),
+                false => layout.event(Event::Press(x, y)),
+            };
+        }
+    };
+}
+
+fn states_has_coord<T>(states: &[State<T>], x: u8, y: u16) -> bool {
+    states.iter().any(|s| match s {
+        State::NormalKey { coord, .. }
+        | State::LayerModifier { coord, .. }
+        | State::Custom { coord, .. }
+        | State::NoOpInput { coord }
+        | State::RepeatingSequence { coord, .. } => *coord == (x, y),
+        State::FakeKey { .. }
+        | State::SeqCustomPending(_)
+        | State::SeqCustomActive(_)
+        | State::Tombstone => false,
+    })
+}
+
+#[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+fn release_normalkey_states<'a, const C: usize, const R: usize, T>(layout: &mut Layout<'a, C, R, T>)
+where
+    T: 'a + std::fmt::Debug + Copy,
+{
+    let mut coords_to_release = vec![];
+    for state in layout.states.iter().copied() {
+        match state {
+            State::NormalKey {
+                coord: (NORMAL_KEY_ROW, y),
+                ..
+            }
+            | State::LayerModifier {
+                coord: (NORMAL_KEY_ROW, y),
+                ..
+            }
+            | State::Custom {
+                coord: (NORMAL_KEY_ROW, y),
+                ..
+            }
+            | State::RepeatingSequence {
+                coord: (NORMAL_KEY_ROW, y),
+                ..
+            } => {
+                coords_to_release.push((NORMAL_KEY_ROW, y));
+            }
+            _ => {}
+        }
+    }
+    for coord in coords_to_release.into_iter() {
+        layout.event(Event::Release(coord.0, coord.1));
+    }
+}
+
+#[cfg(test)]
+mod collect_and_sort_events_tests {
+    use super::*;
+    use kanata_parser::keys::OsCode;
+    use std::sync::mpsc::sync_channel;
+
+    fn make_event(code: OsCode, value: KeyValue) -> KeyEvent {
+        KeyEvent::new(code, value)
+    }
+
+    #[test]
+    fn single_event_unchanged() {
+        let (_tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Press);
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].code, OsCode::KEY_A);
+    }
+
+    #[test]
+    fn modifiers_first_on_press() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Press);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Press))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Press)).unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[1].code, OsCode::KEY_A);
+        assert_eq!(result[2].code, OsCode::KEY_B);
+    }
+
+    #[test]
+    fn modifiers_last_on_release() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Release);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Release))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Release))
+            .unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].code, OsCode::KEY_A);
+        assert_eq!(result[1].code, OsCode::KEY_B);
+        assert_eq!(result[2].code, OsCode::KEY_LEFTCTRL);
+    }
+
+    #[test]
+    fn multiple_modifiers_on_press() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Press);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Press))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_LEFTSHIFT, KeyValue::Press))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Press)).unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 4);
+        assert_eq!(result[0].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[1].code, OsCode::KEY_LEFTSHIFT);
+        assert_eq!(result[2].code, OsCode::KEY_A);
+        assert_eq!(result[3].code, OsCode::KEY_B);
+    }
+
+    #[test]
+    fn multiple_modifiers_on_release() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Release);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Release))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_LEFTSHIFT, KeyValue::Release))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Release))
+            .unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 4);
+        assert_eq!(result[0].code, OsCode::KEY_A);
+        assert_eq!(result[1].code, OsCode::KEY_B);
+        assert_eq!(result[2].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[3].code, OsCode::KEY_LEFTSHIFT);
+    }
+
+    #[test]
+    fn repeat_treated_like_press() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Repeat);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Repeat))
+            .unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 2);
+        assert_eq!(result[0].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[1].code, OsCode::KEY_A);
+    }
+
+    #[test]
+    fn all_modifiers_no_reorder_needed() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_LEFTCTRL, KeyValue::Press);
+        tx.send(make_event(OsCode::KEY_LEFTSHIFT, KeyValue::Press))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_LEFTALT, KeyValue::Press))
+            .unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[1].code, OsCode::KEY_LEFTSHIFT);
+        assert_eq!(result[2].code, OsCode::KEY_LEFTALT);
+    }
+
+    #[test]
+    fn all_non_modifiers_no_reorder_needed() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Press);
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Press)).unwrap();
+        tx.send(make_event(OsCode::KEY_C, KeyValue::Press)).unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].code, OsCode::KEY_A);
+        assert_eq!(result[1].code, OsCode::KEY_B);
+        assert_eq!(result[2].code, OsCode::KEY_C);
+    }
+
+    #[test]
+    fn mixed_press_release_preserves_interleaving() {
+        let (tx, rx) = sync_channel::<KeyEvent>(10);
+        let first = make_event(OsCode::KEY_A, KeyValue::Press);
+        tx.send(make_event(OsCode::KEY_LEFTCTRL, KeyValue::Release))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_B, KeyValue::Release))
+            .unwrap();
+        tx.send(make_event(OsCode::KEY_LEFTSHIFT, KeyValue::Press))
+            .unwrap();
+
+        let mut result = Vec::new();
+        collect_and_sort_events(first, &rx, &mut result);
+
+        assert_eq!(result.len(), 4);
+        assert_eq!(result[0].code, OsCode::KEY_A);
+        assert_eq!(result[1].code, OsCode::KEY_B);
+        assert_eq!(result[2].code, OsCode::KEY_LEFTCTRL);
+        assert_eq!(result[3].code, OsCode::KEY_LEFTSHIFT);
+    }
+}
+
+#[cfg(all(test, feature = "tcp_server"))]
+mod tcp_layer_change_tests {
+    use super::*;
+    use std::sync::mpsc::{TryRecvError, sync_channel};
+    use std::time::Duration;
+
+    fn collect_layer_changes(rx: &Receiver<ServerMessage>) -> Vec<String> {
+        let mut changes = Vec::new();
+        loop {
+            match rx.try_recv() {
+                Ok(ServerMessage::LayerChange { new }) => changes.push(new),
+                Ok(_) => {}
+                Err(TryRecvError::Empty) => break,
+                Err(TryRecvError::Disconnected) => break,
+            }
+        }
+        changes
+    }
+
+    #[test]
+    fn direct_held_layer_press_and_release_emit_layer_changes() {
+        let _lk = match crate::tests::CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        let mut k = Kanata::new_from_str(
+            r"
+(defsrc a)
+(deflayer base
+  (layer-while-held nav))
+(deflayer nav
+  b)
+            ",
+            Default::default(),
+        )
+        .expect("failed to parse cfg");
+        let (tx, rx) = sync_channel::<ServerMessage>(10);
+        let tx = Some(tx);
+
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Press))
+            .expect("press should succeed");
+        k.last_tick = web_time::Instant::now() - Duration::from_millis(1);
+        k.handle_time_ticks(&tx).expect("press tick should succeed");
+
+        assert_eq!(collect_layer_changes(&rx), vec!["nav"]);
+
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Release))
+            .expect("release should succeed");
+        k.last_tick = web_time::Instant::now() - Duration::from_millis(1);
+        k.handle_time_ticks(&tx)
+            .expect("release tick should succeed");
+
+        assert_eq!(collect_layer_changes(&rx), vec!["base"]);
+    }
+
+    #[test]
+    fn oneshot_held_layer_timeout_emits_both_transitions_within_one_tick_batch() {
+        let _lk = match crate::tests::CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        let mut k = Kanata::new_from_str(
+            r"
+(defsrc a)
+(deflayer base
+  (one-shot 2 (layer-while-held nav)))
+(deflayer nav
+  b)
+            ",
+            Default::default(),
+        )
+        .expect("failed to parse cfg");
+        let (tx, rx) = sync_channel::<ServerMessage>(10);
+        let tx = Some(tx);
+
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Press))
+            .expect("press should succeed");
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Release))
+            .expect("release should succeed");
+        k.last_tick = web_time::Instant::now() - Duration::from_millis(5);
+        k.handle_time_ticks(&tx)
+            .expect("batched timeout ticks should succeed");
+
+        assert_eq!(collect_layer_changes(&rx), vec!["nav", "base"]);
+    }
+
+    #[test]
+    fn oneshot_held_layer_consumed_by_keypress_emits_both_transitions_within_one_tick_batch() {
+        let _lk = match crate::tests::CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        let mut k = Kanata::new_from_str(
+            r"
+(defsrc a b)
+(deflayer base
+  (one-shot 20 (layer-while-held nav))
+  XX)
+(deflayer nav
+  _
+  (layer-while-held base))
+            ",
+            Default::default(),
+        )
+        .expect("failed to parse cfg");
+        let (tx, rx) = sync_channel::<ServerMessage>(10);
+        let tx = Some(tx);
+
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Press))
+            .expect("oneshot press should succeed");
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_A, KeyValue::Release))
+            .expect("oneshot release should succeed");
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_B, KeyValue::Press))
+            .expect("consumer press should succeed");
+        k.handle_input_event(&KeyEvent::new(OsCode::KEY_B, KeyValue::Release))
+            .expect("consumer release should succeed");
+        k.last_tick = web_time::Instant::now() - Duration::from_millis(5);
+        k.handle_time_ticks(&tx)
+            .expect("batched consume ticks should succeed");
+
+        assert_eq!(collect_layer_changes(&rx), vec!["nav", "base"]);
+    }
+}
diff --git a/src/kanata/output_logic.rs b/src/kanata/output_logic.rs
new file mode 100644
index 000000000..0ea2d094b
--- /dev/null
+++ b/src/kanata/output_logic.rs
@@ -0,0 +1,138 @@
+use super::*;
+
+#[cfg(feature = "zippychord")]
+mod zippychord;
+#[cfg(feature = "zippychord")]
+pub(crate) use zippychord::*;
+
+// Functions to send keys except those that fall in the ignorable range.
+// And also have been repurposed to have additional logic to send mouse events, out of convenience.
+//
+// POTENTIAL PROBLEM - G-keys:
+// Some keys are ignored because they are *probably* unused,
+// or otherwise are probably in an unergonomic, far away key position,
+// so if you're using kanata, you can now stop using those keys and
+// do something better!
+//
+// I should probably let people turn this off if they really want to,
+// but I don't like how that would require extra code.
+// I'll defer to YAGNI and add docs, and let people report problems if
+// they want a fix 🐝.
+//
+// The keys ignored are intentionally the upper numbers of KEY_MACROX.
+// The Linux input-event-codes.h file mentions G1-G18 and S1-S30
+// as keys that might use these codes.
+//
+// Logitech still makes devices with G-keys
+// but the S-keys are apparently from the
+// "Microsoft SideWinder X6 Keyboard"
+// which appears to no longer be in production.
+//
+// Thus based on my reading, 18 is the highest macro key
+// that can be assumed to be used by devices still in production.
+pub(super) const KEY_IGNORE_MIN: u16 = 0x2a4; // KEY_MACRO21
+pub(super) const KEY_IGNORE_MAX: u16 = 0x2ad; // KEY_MACRO30
+pub(super) fn write_key(kb: &mut KbdOut, osc: OsCode, val: KeyValue) -> Result<(), std::io::Error> {
+    match u16::from(osc) {
+        KEY_IGNORE_MIN..=KEY_IGNORE_MAX => Ok(()),
+        _ => kb.write_key(osc, val),
+    }
+}
+pub(super) fn press_key(kb: &mut KbdOut, osc: OsCode) -> Result<(), std::io::Error> {
+    use OsCode::*;
+    match u16::from(osc) {
+        KEY_IGNORE_MIN..=KEY_IGNORE_MAX => Ok(()),
+        _ => match osc {
+            BTN_LEFT | BTN_RIGHT | BTN_MIDDLE | BTN_SIDE | BTN_EXTRA => {
+                let btn = osc_to_btn(osc);
+                kb.click_btn(btn)
+            }
+            MouseWheelUp | MouseWheelDown | MouseWheelLeft | MouseWheelRight => {
+                let direction = osc_to_wheel_direction(osc);
+                kb.scroll(direction, HI_RES_SCROLL_UNITS_IN_LO_RES)
+            }
+            _ => post_filter_press(kb, osc),
+        },
+    }
+}
+pub(super) fn release_key(kb: &mut KbdOut, osc: OsCode) -> Result<(), std::io::Error> {
+    use OsCode::*;
+    match u16::from(osc) {
+        KEY_IGNORE_MIN..=KEY_IGNORE_MAX => Ok(()),
+        _ => match osc {
+            BTN_LEFT | BTN_RIGHT | BTN_MIDDLE | BTN_SIDE | BTN_EXTRA => {
+                let btn = osc_to_btn(osc);
+                kb.release_btn(btn)
+            }
+            MouseWheelUp | MouseWheelDown | MouseWheelLeft | MouseWheelRight => {
+                // no-op: these are handled as scroll events in the press but scroll has no notion
+                // of release.
+                Ok(())
+            }
+            _ => post_filter_release(kb, osc),
+        },
+    }
+}
+fn osc_to_btn(osc: OsCode) -> Btn {
+    use Btn::*;
+    use OsCode::*;
+    match osc {
+        BTN_LEFT => Left,
+        BTN_RIGHT => Right,
+        BTN_MIDDLE => Mid,
+        BTN_EXTRA => Forward,
+        BTN_SIDE => Backward,
+        _ => unreachable!("called osc_to_btn with bad value {osc}"),
+    }
+}
+fn osc_to_wheel_direction(osc: OsCode) -> MWheelDirection {
+    use MWheelDirection::*;
+    use OsCode::*;
+    match osc {
+        MouseWheelUp => Up,
+        MouseWheelDown => Down,
+        MouseWheelLeft => Left,
+        MouseWheelRight => Right,
+        _ => unreachable!("called osc_to_wheel_direction with bad value {osc}"),
+    }
+}
+
+fn post_filter_press(kb: &mut KbdOut, osc: OsCode) -> Result<(), std::io::Error> {
+    #[cfg(not(feature = "zippychord"))]
+    {
+        kb.press_key(osc)
+    }
+    #[cfg(feature = "zippychord")]
+    {
+        zch().zch_press_key(kb, osc)
+    }
+}
+
+fn post_filter_release(kb: &mut KbdOut, osc: OsCode) -> Result<(), std::io::Error> {
+    #[cfg(not(feature = "zippychord"))]
+    {
+        kb.release_key(osc)
+    }
+    #[cfg(feature = "zippychord")]
+    {
+        zch().zch_release_key(kb, osc)
+    }
+}
+
+pub(super) fn zippy_is_idle() -> bool {
+    #[cfg(not(feature = "zippychord"))]
+    {
+        true
+    }
+    #[cfg(feature = "zippychord")]
+    {
+        zch().zch_is_idle()
+    }
+}
+
+pub(super) fn zippy_tick(_caps_word_is_active: bool) {
+    #[cfg(feature = "zippychord")]
+    {
+        zch().zch_tick(_caps_word_is_active)
+    }
+}
diff --git a/src/kanata/output_logic/zippychord.rs b/src/kanata/output_logic/zippychord.rs
new file mode 100644
index 000000000..eaaf86ca9
--- /dev/null
+++ b/src/kanata/output_logic/zippychord.rs
@@ -0,0 +1,628 @@
+use super::*;
+
+use kanata_parser::subset::GetOrIsSubsetOfKnownKey::*;
+
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::MutexGuard;
+
+// Maybe-todos:
+// ---
+// Feature-parity: suffixes - only active while disabled, to complete a word.
+// Feature-parity: prefix vs. non-prefix. Assuming smart spacing is implemented and enabled,
+//                 standard activations would output space one outputs space, but not prefixes.
+//                 I guess can be done in parser.
+
+static ZCH: Lazy<Mutex<ZchState>> = Lazy::new(|| Mutex::new(Default::default()));
+
+pub(crate) fn zch() -> MutexGuard<'static, ZchState> {
+    match ZCH.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut inner = poisoned.into_inner();
+            inner.zchd.zchd_reset();
+            inner
+        }
+    }
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
+enum ZchEnabledState {
+    #[default]
+    Enabled,
+    WaitEnable,
+    Disabled,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum ZchLastPressClassification {
+    #[default]
+    IsChord,
+    NotChord,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum ZchSmartSpaceState {
+    #[default]
+    Inactive,
+    Sent,
+}
+
+#[derive(Debug, Default)]
+struct ZchDynamicState {
+    /// Input to compare against configured available chords to output.
+    zchd_input_keys: ZchInputKeys,
+    /// Whether chording should be enabled or disabled.
+    /// Chording will be disabled if:
+    /// - further presses cannot possibly activate a chord
+    /// - a release happens with no chord having been activated
+    ///
+    /// Once disabled, chording will be enabled when:
+    /// - all keys have been released
+    /// - zchd_ticks_until_enabled shrinks to 0
+    zchd_enabled_state: ZchEnabledState,
+    /// Is Some when a chord has been activated which has possible follow-up chords.
+    /// E.g. dy -> day
+    ///      dy 1 -> Monday
+    ///      dy 2 -> Tuesday
+    /// Using the example above, when dy has been activated, the `1` and `2` activations will be
+    /// contained within `zchd_prioritized_chords`. This is cleared if the input is such that an
+    /// activation is no longer possible.
+    zchd_prioritized_chords: Option<Arc<parking_lot::Mutex<ZchPossibleChords>>>,
+    /// Tracks the prior output character count
+    /// because it may need to be erased (see `zchd_prioritized_chords).
+    zchd_prior_activation_output_count: i16,
+    /// Tracks the number of characters typed to complete an activation, which will be erased if an
+    /// activation completes succesfully.
+    zchd_characters_to_delete_on_next_activation: i16,
+    /// Tracks past activation for additional computation.
+    zchd_prior_activation: Option<Arc<ZchChordOutput>>,
+    /// Tracker for time until prior state change to know if potential stale data should be
+    /// cleared. This is a contingency in case of bugs or weirdness with OS interactions, e.g.
+    /// Windows lock screen weirdness.
+    ///
+    /// This counts upwards to a "reset state" number.
+    zchd_ticks_since_state_change: u16,
+    /// Zch has a time delay between being disabled->pending-enabled->truly-enabled to mitigate
+    /// against unintended activations. This counts downwards from a configured number until 0, and
+    /// at 0 the state transitions from pending-enabled to truly-enabled if applicable.
+    zchd_ticks_until_enabled: u16,
+    /// There is a deadline between the first press happening and a chord activation being
+    /// possible; after which if a chord has not been activated, zippychording is disabled. This
+    /// state is the counter for this deadline.
+    zchd_ticks_until_disable: u16,
+    /// Track number of activations within the same hold.
+    zchd_same_hold_activation_count: u16,
+    /// Current state of caps-word, which is a factor in handling capitalization.
+    zchd_is_caps_word_active: bool,
+    /// Current state of lsft which is a factor in handling capitalization.
+    zchd_is_lsft_active: bool,
+    /// Current state of rsft which is a factor in handling capitalization.
+    zchd_is_rsft_active: bool,
+    /// Current state of altgr which is a factor in smart space erasure.
+    zchd_is_altgr_active: bool,
+    /// Tracks whether last press was part of a chord or not.
+    /// Upon releasing keys, this state determines if zippychording should remain enabled or
+    /// disabled.
+    zchd_last_press: ZchLastPressClassification,
+    /// Tracks smart spacing state so punctuation characters
+    /// can know whether a space needs to be erased or not.
+    zchd_smart_space_state: ZchSmartSpaceState,
+}
+
+impl ZchDynamicState {
+    fn zchd_tick(&mut self, is_caps_word_active: bool) {
+        const TICKS_UNTIL_FORCE_STATE_RESET: u16 = 10000;
+        self.zchd_ticks_since_state_change += 1;
+        self.zchd_is_caps_word_active = is_caps_word_active;
+        match self.zchd_enabled_state {
+            ZchEnabledState::WaitEnable => {
+                self.zchd_ticks_until_enabled = self.zchd_ticks_until_enabled.saturating_sub(1);
+                if self.zchd_ticks_until_enabled == 0 {
+                    log::debug!("zippy wait enable->enable");
+                    self.zchd_enabled_state = ZchEnabledState::Enabled;
+                    self.zchd_ticks_until_disable = 0;
+                }
+            }
+            ZchEnabledState::Enabled => {
+                // Only run disable-check logic if ticks is already greater than zero, because zero
+                // means deadline has never been triggered by any press.
+                if self.zchd_ticks_until_disable > 0 {
+                    self.zchd_ticks_until_disable = self.zchd_ticks_until_disable.saturating_sub(1);
+                    if self.zchd_ticks_until_disable == 0 {
+                        log::debug!("zippy enable->disable");
+                        self.zchd_soft_reset();
+                    }
+                }
+            }
+            ZchEnabledState::Disabled => {}
+        }
+        if self.zchd_ticks_since_state_change > TICKS_UNTIL_FORCE_STATE_RESET {
+            self.zchd_reset();
+        }
+    }
+
+    fn zchd_state_change(&mut self, cfg: &ZchConfig) {
+        self.zchd_ticks_since_state_change = 0;
+        self.zchd_ticks_until_enabled = cfg.zch_cfg_ticks_wait_enable;
+    }
+
+    fn zchd_activate_chord_deadline(&mut self, deadline_ticks: u16) {
+        if self.zchd_ticks_until_disable == 0 {
+            self.zchd_ticks_until_disable = deadline_ticks;
+        }
+    }
+
+    fn zchd_restart_deadline(&mut self, deadline_ticks: u16) {
+        self.zchd_ticks_until_disable = deadline_ticks;
+    }
+
+    /// Clean up the state, potentially causing inaccuracies with regards to what the user is
+    /// currently still pressing.
+    fn zchd_reset(&mut self) {
+        log::debug!("zchd reset state");
+        self.zchd_soft_reset();
+        self.zchd_is_caps_word_active = false;
+        self.zchd_is_lsft_active = false;
+        self.zchd_is_rsft_active = false;
+        self.zchd_is_altgr_active = false;
+        self.zchd_last_press = ZchLastPressClassification::IsChord;
+        self.zchd_enabled_state = ZchEnabledState::Enabled;
+    }
+
+    fn zchd_soft_reset(&mut self) {
+        log::debug!("zchd soft reset state");
+        self.zchd_last_press = ZchLastPressClassification::NotChord;
+        self.zchd_enabled_state = ZchEnabledState::Disabled;
+        self.zchd_input_keys.zchik_clear();
+        self.zchd_ticks_since_state_change = 0;
+        self.zchd_ticks_until_disable = 0;
+        self.zchd_ticks_until_enabled = 0;
+        self.zchd_smart_space_state = ZchSmartSpaceState::Inactive;
+        self.zchd_clear_history();
+    }
+
+    fn zchd_clear_history(&mut self) {
+        log::debug!("zchd clear historical data");
+        self.zchd_characters_to_delete_on_next_activation = 0;
+        self.zchd_prioritized_chords = None;
+        self.zchd_prior_activation = None;
+        self.zchd_prior_activation_output_count = 0;
+    }
+
+    /// Returns true if dynamic zch state is such that idling optimization can activate.
+    fn zchd_is_idle(&self) -> bool {
+        let is_idle = self.zchd_enabled_state == ZchEnabledState::Enabled
+            && self.zchd_input_keys.zchik_is_empty();
+        log::trace!("zch is idle: {is_idle}");
+        is_idle
+    }
+
+    fn zchd_press_key(&mut self, osc: OsCode) {
+        self.zchd_input_keys.zchik_insert(osc);
+    }
+
+    fn zchd_release_key(&mut self, osc: OsCode) {
+        self.zchd_input_keys.zchik_remove(osc);
+        match (self.zchd_last_press, self.zchd_input_keys.zchik_is_empty()) {
+            (ZchLastPressClassification::NotChord, true) => {
+                log::debug!("all released->zippy wait enable");
+                self.zchd_enabled_state = ZchEnabledState::WaitEnable;
+                self.zchd_clear_history();
+            }
+            (ZchLastPressClassification::NotChord, false) => {
+                log::debug!("release but not all->zippy disable");
+                self.zchd_soft_reset();
+            }
+            (ZchLastPressClassification::IsChord, true) => {
+                log::debug!("all released->zippy enabled");
+                if self.zchd_prioritized_chords.is_none() {
+                    log::debug!("no continuation->zippy clear key erase state");
+                    self.zchd_clear_history();
+                }
+                self.zchd_characters_to_delete_on_next_activation = 0;
+                self.zchd_ticks_until_disable = 0;
+                self.zchd_enabled_state = ZchEnabledState::Enabled;
+                self.zchd_same_hold_activation_count = 0;
+            }
+            (ZchLastPressClassification::IsChord, false) => {
+                log::debug!("some released->zippy enabled");
+                self.zchd_ticks_until_disable = 0;
+            }
+        }
+    }
+}
+
+#[derive(Debug, Default)]
+pub(crate) struct ZchState {
+    /// Dynamic state. Maybe doesn't make sense to separate this from zch_chords and to instead
+    /// just flatten the structures.
+    zchd: ZchDynamicState,
+    /// Chords configured by the user. This is fixed at runtime other than live-reloads replacing
+    /// the state.
+    zch_chords: ZchPossibleChords,
+    /// Options to configure behaviour.
+    zch_cfg: ZchConfig,
+}
+
+impl ZchState {
+    /// Configure zippychord behaviour.
+    pub(crate) fn zch_configure(&mut self, cfg: (ZchPossibleChords, ZchConfig)) {
+        self.zch_chords = cfg.0;
+        self.zch_cfg = cfg.1;
+        self.zchd.zchd_reset();
+    }
+
+    /// Zch handling for key presses.
+    pub(crate) fn zch_press_key(
+        &mut self,
+        kb: &mut KbdOut,
+        osc: OsCode,
+    ) -> Result<(), std::io::Error> {
+        if self.zch_chords.is_empty() {
+            return kb.press_key(osc);
+        }
+        match osc {
+            OsCode::KEY_LEFTSHIFT => {
+                self.zchd.zchd_is_lsft_active = true;
+                return kb.press_key(osc);
+            }
+            OsCode::KEY_RIGHTSHIFT => {
+                self.zchd.zchd_is_rsft_active = true;
+                return kb.press_key(osc);
+            }
+            OsCode::KEY_RIGHTALT => {
+                self.zchd.zchd_is_altgr_active = true;
+                return kb.press_key(osc);
+            }
+            osc if osc.is_zippy_ignored() => {
+                return kb.press_key(osc);
+            }
+            _ => {}
+        }
+        if self.zchd.zchd_smart_space_state == ZchSmartSpaceState::Sent
+            && self
+                .zch_cfg
+                .zch_cfg_smart_space_punctuation
+                .contains(&match (
+                    self.zchd.zchd_is_lsft_active | self.zchd.zchd_is_rsft_active,
+                    self.zchd.zchd_is_altgr_active,
+                ) {
+                    (false, false) => ZchOutput::Lowercase(osc),
+                    (true, false) => ZchOutput::Uppercase(osc),
+                    (false, true) => ZchOutput::AltGr(osc),
+                    (true, true) => ZchOutput::ShiftAltGr(osc),
+                })
+        {
+            self.zchd.zchd_characters_to_delete_on_next_activation -= 1;
+            kb.press_key(OsCode::KEY_BACKSPACE)?;
+            kb.release_key(OsCode::KEY_BACKSPACE)?;
+        }
+        self.zchd.zchd_smart_space_state = ZchSmartSpaceState::Inactive;
+        if self.zchd.zchd_enabled_state != ZchEnabledState::Enabled {
+            return kb.press_key(osc);
+        }
+
+        // Zippychording is enabled. Ensure the deadline to disable it if no chord activates is
+        // active.
+        self.zchd
+            .zchd_activate_chord_deadline(self.zch_cfg.zch_cfg_ticks_chord_deadline);
+        self.zchd.zchd_state_change(&self.zch_cfg);
+        self.zchd.zchd_press_key(osc);
+
+        // There might be an activation.
+        // - delete typed keys
+        // - output activation
+        //
+        // Key deletion needs to remove typed keys as well as past activations that need to be
+        // cleaned up, e.g. either the antecedent in a "combo chord" or an eagerly-activated
+        // chord using fewer keys, but user has still held that chord and pressed further keys,
+        // activating a chord with the same+extra keys.
+        let mut activation = Neither;
+        if let Some(pchords) = &self.zchd.zchd_prioritized_chords {
+            activation = pchords
+                .lock()
+                .0
+                .ssm_get_or_is_subset_ksorted(self.zchd.zchd_input_keys.zchik_keys());
+        }
+        let mut is_prioritized_activation = false;
+        if !matches!(activation, HasValue(..)) {
+            activation = self
+                .zch_chords
+                .0
+                .ssm_get_or_is_subset_ksorted(self.zchd.zchd_input_keys.zchik_keys());
+        } else {
+            is_prioritized_activation = true;
+        }
+
+        match activation {
+            HasValue(a) => {
+                // Find the longest common prefix length between the prior activation and the new
+                // activation. This value affects both:
+                // - the number of backspaces that need to be done
+                // - the number of characters that actually need to be typed by the activation
+                let common_prefix_len_from_past_activation = if !is_prioritized_activation
+                    && self.zchd.zchd_same_hold_activation_count == 0
+                {
+                    0
+                } else {
+                    self.zchd
+                        .zchd_prior_activation
+                        .as_ref()
+                        .map(|prior_activation| {
+                            let current_activation_output = &a.zch_output;
+                            let mut len: i16 = 0;
+                            for (past, current) in prior_activation
+                                .zch_output
+                                .iter()
+                                .copied()
+                                .zip(current_activation_output.iter().copied())
+                            {
+                                if past.osc() == OsCode::KEY_BACKSPACE
+                                    || current.osc() == OsCode::KEY_BACKSPACE
+                                    || past != current
+                                {
+                                    break;
+                                }
+                                len += 1;
+                            }
+                            len
+                        })
+                        .unwrap_or(0)
+                };
+                self.zchd.zchd_prior_activation = Some(a.clone());
+                self.zchd.zchd_same_hold_activation_count += 1;
+
+                self.zchd
+                    .zchd_restart_deadline(self.zch_cfg.zch_cfg_ticks_chord_deadline);
+                if !a.zch_output.is_empty() {
+                    // Zippychording eagerly types characters that form a chord and also eagerly
+                    // outputs chords that are of a maybe-to-be-activated-later chord with more
+                    // participating keys. This procedure erases both classes of typed characters
+                    // in order to have the correct typed output for this chord activation.
+                    for _ in 0..(self.zchd.zchd_characters_to_delete_on_next_activation
+                        + if is_prioritized_activation {
+                            self.zchd.zchd_prior_activation_output_count
+                        } else {
+                            0
+                        }
+                        - common_prefix_len_from_past_activation)
+                    {
+                        kb.press_key(OsCode::KEY_BACKSPACE)?;
+                        kb.release_key(OsCode::KEY_BACKSPACE)?;
+                    }
+                    self.zchd.zchd_characters_to_delete_on_next_activation = 0;
+                    self.zchd.zchd_prior_activation_output_count =
+                        ZchOutput::display_len(&a.zch_output);
+                } else {
+                    // Followup chords may consist of an empty output; eventually in the followup
+                    // chain has an activation output that is not empty. For empty outputs, do not
+                    // do any backspacing.
+                    self.zchd.zchd_characters_to_delete_on_next_activation += 1;
+                    self.zchd.zchd_prior_activation_output_count +=
+                        self.zchd.zchd_input_keys.zchik_keys().len() as i16;
+                    kb.press_key(osc)?;
+                }
+
+                self.zchd
+                    .zchd_prioritized_chords
+                    .clone_from(&a.zch_followups);
+                let mut released_sft = false;
+                #[cfg(feature = "interception_driver")]
+                let mut send_count = 0;
+                if self.zchd.zchd_is_altgr_active && !a.zch_output.is_empty() {
+                    kb.release_key(OsCode::KEY_RIGHTALT)?;
+                }
+                for key_to_send in a
+                    .zch_output
+                    .iter()
+                    .copied()
+                    .skip(common_prefix_len_from_past_activation as usize)
+                {
+                    #[cfg(feature = "interception_driver")]
+                    {
+                        // Note: every 5 keys on Windows Interception, do a sleep because
+                        // sending too quickly apparently causes weird behaviour...
+                        // I guess there's some buffer in the Interception code that is filling up.
+                        send_count += 1;
+                        if send_count % 5 == 0 {
+                            std::thread::sleep(std::time::Duration::from_millis(1));
+                        }
+                    }
+
+                    match key_to_send {
+                        ZchOutput::Lowercase(osc) | ZchOutput::NoEraseLowercase(osc) => {
+                            type_osc(osc, kb, &self.zchd)?;
+                        }
+                        ZchOutput::Uppercase(osc) | ZchOutput::NoEraseUppercase(osc) => {
+                            maybe_press_sft_during_activation(released_sft, kb, &self.zchd)?;
+                            type_osc(osc, kb, &self.zchd)?;
+                            maybe_release_sft_during_activation(released_sft, kb, &self.zchd)?;
+                        }
+                        ZchOutput::AltGr(osc) | ZchOutput::NoEraseAltGr(osc) => {
+                            // A note regarding maybe_press|release_sft
+                            // in contrast to always pressing|releasing altgr:
+                            //
+                            // The maybe-logic is valuable with Shift to capitalize the first
+                            // typed output during activation.
+                            // However, altgr - if already held -
+                            // does not seem useful to keep held on the first typed output so it is
+                            // always released at the beginning and pressed at the end if it was
+                            // previously being held.
+                            kb.press_key(OsCode::KEY_RIGHTALT)?;
+                            type_osc(osc, kb, &self.zchd)?;
+                            kb.release_key(OsCode::KEY_RIGHTALT)?;
+                        }
+                        ZchOutput::ShiftAltGr(osc) | ZchOutput::NoEraseShiftAltGr(osc) => {
+                            kb.press_key(OsCode::KEY_RIGHTALT)?;
+                            maybe_press_sft_during_activation(released_sft, kb, &self.zchd)?;
+                            type_osc(osc, kb, &self.zchd)?;
+                            maybe_release_sft_during_activation(released_sft, kb, &self.zchd)?;
+                            kb.release_key(OsCode::KEY_RIGHTALT)?;
+                        }
+                    };
+
+                    self.zchd.zchd_characters_to_delete_on_next_activation +=
+                        key_to_send.output_char_count();
+
+                    if !released_sft && !self.zchd.zchd_is_caps_word_active {
+                        released_sft = true;
+                        if self.zchd.zchd_is_lsft_active {
+                            kb.release_key(OsCode::KEY_LEFTSHIFT)?;
+                        }
+                        if self.zchd.zchd_is_rsft_active {
+                            kb.release_key(OsCode::KEY_RIGHTSHIFT)?;
+                        }
+                    }
+                }
+
+                if self.zch_cfg.zch_cfg_smart_space != ZchSmartSpaceCfg::Disabled
+                    && a.zch_output
+                        .last()
+                        .map(|out| !matches!(out.osc(), OsCode::KEY_SPACE | OsCode::KEY_BACKSPACE))
+                        .unwrap_or(false /* if output is empty, don't do smart spacing */)
+                {
+                    if self.zch_cfg.zch_cfg_smart_space == ZchSmartSpaceCfg::Full {
+                        self.zchd.zchd_smart_space_state = ZchSmartSpaceState::Sent;
+                    }
+
+                    // It might look unusual to add to both.
+                    // This is correct to do.
+                    // zchd_prior_activation_output_count only applies to followup activations,
+                    // which should only occur after a full release+repress of a new chord.
+                    // The full release will set zchd_characters_to_delete_on_next_activation to 0.
+                    // Overlapping chords do not use zchd_prior_activation_output_count but
+                    // instead keep track of characters to delete via
+                    // zchd_characters_to_delete_on_next_activation,
+                    // which is incremented both by typing characters
+                    // to achieve a chord in the first place,
+                    // as well as by chord activations that are overlapped
+                    // by the intended final chord.
+                    self.zchd.zchd_prior_activation_output_count += 1;
+                    self.zchd.zchd_characters_to_delete_on_next_activation += 1;
+
+                    kb.press_key(OsCode::KEY_SPACE)?;
+                    kb.release_key(OsCode::KEY_SPACE)?;
+                }
+
+                if !self.zchd.zchd_is_caps_word_active {
+                    // When expanding, lsft/rsft will be released after the first press.
+                    if self.zchd.zchd_is_lsft_active {
+                        kb.press_key(OsCode::KEY_LEFTSHIFT)?;
+                    }
+                    if self.zchd.zchd_is_rsft_active {
+                        kb.press_key(OsCode::KEY_RIGHTSHIFT)?;
+                    }
+                }
+                if self.zchd.zchd_is_altgr_active && !a.zch_output.is_empty() {
+                    kb.press_key(OsCode::KEY_RIGHTALT)?;
+                }
+
+                // Note: it is incorrect to clear input keys.
+                // Zippychord will eagerly output chords even if there is an overlapping chord that
+                // may be activated later by an additional keypress before any releases happen.
+                // E.g.
+                // ab => Abba
+                // abc => Alphabet
+                //
+                // If (b a) are typed, "Abba" is outputted.
+                // If (b a) are continued to be held and (c) is subsequently pressed,
+                // "Abba" gets erased and "Alphabet" is outputted.
+                //
+                // WRONG:
+                // self.zchd.zchd_input_keys.zchik_clear()
+
+                self.zchd.zchd_last_press = ZchLastPressClassification::IsChord;
+                Ok(())
+            }
+
+            IsSubset => {
+                self.zchd.zchd_last_press = ZchLastPressClassification::NotChord;
+                self.zchd.zchd_characters_to_delete_on_next_activation += 1;
+                kb.press_key(osc)
+            }
+
+            Neither => {
+                self.zchd.zchd_soft_reset();
+                kb.press_key(osc)
+            }
+        }
+    }
+
+    // Zch handling for key releases.
+    pub(crate) fn zch_release_key(
+        &mut self,
+        kb: &mut KbdOut,
+        osc: OsCode,
+    ) -> Result<(), std::io::Error> {
+        if self.zch_chords.is_empty() {
+            return kb.release_key(osc);
+        }
+        match osc {
+            OsCode::KEY_LEFTSHIFT => {
+                self.zchd.zchd_is_lsft_active = false;
+            }
+            OsCode::KEY_RIGHTSHIFT => {
+                self.zchd.zchd_is_rsft_active = false;
+            }
+            OsCode::KEY_RIGHTALT => {
+                self.zchd.zchd_is_altgr_active = false;
+            }
+            _ => {}
+        }
+        if osc.is_zippy_ignored() {
+            return kb.release_key(osc);
+        }
+        self.zchd.zchd_state_change(&self.zch_cfg);
+        self.zchd.zchd_release_key(osc);
+        kb.release_key(osc)
+    }
+
+    /// Tick the zch output state.
+    pub(crate) fn zch_tick(&mut self, is_caps_word_active: bool) {
+        self.zchd.zchd_tick(is_caps_word_active);
+    }
+
+    /// Returns true if zch state has no further processing so the idling optimization can
+    /// activate.
+    pub(crate) fn zch_is_idle(&self) -> bool {
+        self.zchd.zchd_is_idle()
+    }
+}
+
+fn type_osc(osc: OsCode, kb: &mut KbdOut, zchd: &ZchDynamicState) -> Result<(), std::io::Error> {
+    if zchd.zchd_input_keys.zchik_contains(osc) {
+        kb.release_key(osc)?;
+        kb.press_key(osc)?;
+    } else {
+        kb.press_key(osc)?;
+        kb.release_key(osc)?;
+    }
+    Ok(())
+}
+
+fn maybe_press_sft_during_activation(
+    sft_already_released: bool,
+    kb: &mut KbdOut,
+    zchd: &ZchDynamicState,
+) -> Result<(), std::io::Error> {
+    if !zchd.zchd_is_caps_word_active
+        && (sft_already_released || !zchd.zchd_is_lsft_active && !zchd.zchd_is_rsft_active)
+    {
+        kb.press_key(OsCode::KEY_LEFTSHIFT)?;
+    }
+    Ok(())
+}
+
+fn maybe_release_sft_during_activation(
+    sft_already_released: bool,
+    kb: &mut KbdOut,
+    zchd: &ZchDynamicState,
+) -> Result<(), std::io::Error> {
+    if !zchd.zchd_is_caps_word_active
+        && (sft_already_released || !zchd.zchd_is_lsft_active && !zchd.zchd_is_rsft_active)
+    {
+        kb.release_key(OsCode::KEY_LEFTSHIFT)?;
+    }
+    Ok(())
+}
diff --git a/src/kanata/scroll.rs b/src/kanata/scroll.rs
new file mode 100644
index 000000000..1dfea35fe
--- /dev/null
+++ b/src/kanata/scroll.rs
@@ -0,0 +1,55 @@
+use super::*;
+
+pub struct ScrollState {
+    pub direction: MWheelDirection,
+    pub interval: u16,
+    pub ticks_until_scroll: u16,
+    pub distance: u16,
+    pub scroll_accel_state: Option<ScrollAccelState>,
+}
+
+pub struct ScrollAccelState {
+    pub deceleration_multiplier: f32,
+    pub acceleration_multiplier: f32,
+    pub max_velocity: f32,
+    pub current_velocity: f32,
+    pub scroll_released: bool,
+}
+
+pub(crate) fn update_scrollstate_get_result(
+    state: &mut Option<ScrollState>,
+) -> Option<(MWheelDirection, u16)> {
+    let Some(state) = state else {
+        return None;
+    };
+    if state.ticks_until_scroll == 0 {
+        state.ticks_until_scroll = state.interval - 1;
+        let direction = state.direction;
+        let distance = state.distance;
+
+        Some(match &mut state.scroll_accel_state {
+            Some(acs) => match acs.scroll_released {
+                false => {
+                    let new_velocity = f32::min(
+                        acs.max_velocity,
+                        acs.current_velocity * acs.acceleration_multiplier,
+                    );
+                    acs.current_velocity = new_velocity;
+                    (direction, new_velocity as u16)
+                }
+                true => {
+                    let mut new_velocity = acs.current_velocity * acs.deceleration_multiplier;
+                    if new_velocity < 5.0 {
+                        new_velocity = 0.0;
+                    }
+                    acs.current_velocity = new_velocity;
+                    (direction, new_velocity as u16)
+                }
+            },
+            None => (direction, distance),
+        })
+    } else {
+        state.ticks_until_scroll -= 1;
+        None
+    }
+}
diff --git a/src/kanata/sequences.rs b/src/kanata/sequences.rs
new file mode 100644
index 000000000..f184e40f7
--- /dev/null
+++ b/src/kanata/sequences.rs
@@ -0,0 +1,371 @@
+use super::*;
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum SequenceActivity {
+    Inactive,
+    Active,
+}
+
+use SequenceActivity::*;
+
+pub struct SequenceState {
+    /// Unmangled sequence of keys pressed for hidden-delay-type.
+    pub raw_oscs: Vec<OsCode>,
+    /// Keeps track of standard sequence state.
+    /// This includes regular keys, e.g. `a b c`
+    /// and chorded keys, e.g. `S-(d e f)`.
+    pub sequence: Vec<u16>,
+    /// Keeps track of overlapping sequence state.
+    /// E.g. able to detect `O-(g h i)`
+    pub overlapped_sequence: Vec<u16>,
+    /// Determines the handling of keys while sequence state is in progress.
+    pub sequence_input_mode: SequenceInputMode,
+    /// Starts from `sequence_timeout` and ticks down
+    /// approximately every millisecond.
+    /// At 0 the sequence state terminates.
+    pub ticks_until_timeout: u16,
+    /// User-configured sequence timeout setting.
+    pub sequence_timeout: u16,
+    /// Whether the sequence is active or not.
+    pub activity: SequenceActivity,
+    /// Counter to reduce number of backspaces typed.
+    noerase_count: u16,
+}
+
+impl SequenceState {
+    pub fn new() -> Self {
+        Self {
+            raw_oscs: vec![],
+            sequence: vec![],
+            overlapped_sequence: vec![],
+            sequence_input_mode: SequenceInputMode::HiddenSuppressed,
+            ticks_until_timeout: 0,
+            sequence_timeout: 0,
+            activity: Inactive,
+            noerase_count: 0,
+        }
+    }
+
+    /// Updates the sequence state parameters, clears buffers, and sets the state to active.
+    pub fn activate(&mut self, input_mode: SequenceInputMode, timeout: u16) {
+        self.sequence_input_mode = input_mode;
+        self.sequence_timeout = timeout;
+        self.ticks_until_timeout = timeout;
+        self.raw_oscs.clear();
+        self.sequence.clear();
+        self.overlapped_sequence.clear();
+        self.activity = Active;
+        self.noerase_count = 0;
+    }
+
+    pub fn is_active(&self) -> bool {
+        self.activity == Active
+    }
+
+    pub fn get_active(&mut self) -> Option<&mut Self> {
+        match self.activity {
+            Active => Some(self),
+            Inactive => None,
+        }
+    }
+
+    pub fn is_inactive(&self) -> bool {
+        self.activity == Inactive
+    }
+}
+
+impl Default for SequenceState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub(super) fn get_mod_mask_for_cur_keys(cur_keys: &[KeyCode]) -> u16 {
+    cur_keys
+        .iter()
+        .copied()
+        .fold(0, |a, v| a | mod_mask_for_keycode(v))
+}
+
+pub(super) enum EndSequenceType {
+    Standard,
+    Overlap,
+}
+
+pub(super) fn do_sequence_press_logic(
+    state: &mut SequenceState,
+    k: &KeyCode,
+    mod_mask: u16,
+    kbd_out: &mut KbdOut,
+    sequences: &kanata_parser::trie::Trie<(u8, u16)>,
+    sequence_backtrack_modcancel: bool,
+    layout: &mut BorrowedKLayout,
+) -> Result<(), anyhow::Error> {
+    state.ticks_until_timeout = state.sequence_timeout;
+    let osc = OsCode::from(*k);
+    state.raw_oscs.push(osc);
+    use kanata_parser::trie::GetOrDescendentExistsResult::*;
+    let pushed_into_seq = {
+        // Transform to OsCode and convert modifiers other than altgr/ralt
+        // (same key different names) to the left version, since that's
+        // how chords get transformed when building up sequences.
+        let base = u16::from(match osc {
+            OsCode::KEY_RIGHTSHIFT => OsCode::KEY_LEFTSHIFT,
+            OsCode::KEY_RIGHTMETA => OsCode::KEY_LEFTMETA,
+            OsCode::KEY_RIGHTCTRL => OsCode::KEY_LEFTCTRL,
+            osc => osc,
+        });
+        base | mod_mask
+    };
+    match state.sequence_input_mode {
+        SequenceInputMode::VisibleBackspaced => {
+            press_key(kbd_out, osc)?;
+        }
+        SequenceInputMode::HiddenSuppressed | SequenceInputMode::HiddenDelayType => {}
+    }
+    log::debug!("sequence got {k:?}");
+    state.sequence.push(pushed_into_seq);
+    let pushed_into_overlap_seq = (pushed_into_seq & MASK_KEYCODES) | KEY_OVERLAP_MARKER;
+    state.overlapped_sequence.push(pushed_into_overlap_seq);
+    let mut res = sequences.get_or_descendant_exists(&state.sequence);
+
+    // Check for invalid termination of standard variant of sequence state.
+    // Can potentially backtrack and overwrite modded keystates as well as overlap keystates, which
+    // might exist in the sequence because of an earlier invalid termination where the standard
+    // sequence got filled in with overlap sequence data.
+    let mut is_invalid_termination_standard = false;
+    if res == NotInTrie {
+        is_invalid_termination_standard = {
+            let mut no_valid_seqs = true;
+            // If applicable, check again with modifier bits unset.
+            for i in (0..state.sequence.len()).rev() {
+                // Note: proper bounds are immediately above.
+                // Can't use iter_mut due to borrowing issues.
+                if state.sequence[i] == KEY_OVERLAP_MARKER {
+                    state.sequence.remove(i);
+                } else if sequence_backtrack_modcancel {
+                    state.sequence[i] &= MASK_KEYCODES;
+                } else {
+                    state.sequence[i] &= !KEY_OVERLAP_MARKER;
+                }
+                res = sequences.get_or_descendant_exists(&state.sequence);
+                if res != NotInTrie {
+                    no_valid_seqs = false;
+                    break;
+                }
+            }
+            no_valid_seqs
+        };
+    }
+
+    // Check for invalid termination of overlap variant of sequence state.
+    // This variant does not backtrack today because I haven't figured out how to do that easily.
+    // It does do some attempts to stay valid by modifying the tail of the sequence though.
+    let mut res_overlapped = sequences.get_or_descendant_exists(&state.overlapped_sequence);
+    let is_invalid_termination_overlapped = if res_overlapped == NotInTrie {
+        // Try ending the overlapping and push overlapping seq again.
+        let index_of_last = state.overlapped_sequence.len() - 1;
+        state.overlapped_sequence[index_of_last] = KEY_OVERLAP_MARKER;
+        state.overlapped_sequence.push(pushed_into_overlap_seq);
+        res_overlapped = sequences.get_or_descendant_exists(&state.overlapped_sequence);
+        let index_of_last = index_of_last + 1;
+        if res_overlapped == NotInTrie {
+            // Try checking the trie after setting the latest key to not have the overlapping
+            // marker.
+            state.overlapped_sequence[index_of_last] = pushed_into_seq;
+            res_overlapped = sequences.get_or_descendant_exists(&state.overlapped_sequence);
+            if res_overlapped == NotInTrie {
+                if pushed_into_seq & MASK_KEYCODES == pushed_into_seq {
+                    // Avoid calling get_or_descendant_exists if there is no difference, to save on
+                    // doing work checking in the trie.
+                    true
+                } else {
+                    // Try unmodded `pushed_into_seq`.
+                    state.overlapped_sequence[index_of_last] = pushed_into_seq & MASK_KEYCODES;
+                    res_overlapped = sequences.get_or_descendant_exists(&state.overlapped_sequence);
+                    res_overlapped == NotInTrie
+                }
+            } else {
+                false
+            }
+        } else {
+            false
+        }
+    } else {
+        false
+    };
+
+    match (
+        is_invalid_termination_standard,
+        is_invalid_termination_overlapped,
+    ) {
+        (false, false) => {}
+        (false, true) => {
+            log::debug!("overlap seq is invalid; filling with standard seq");
+            // Overwrite overlapped with non-overlapped tracking
+            state.overlapped_sequence.clear();
+            state
+                .overlapped_sequence
+                .extend(state.sequence.iter().copied());
+            res_overlapped = sequences.get_or_descendant_exists(&state.overlapped_sequence);
+        }
+        (true, false) => {
+            log::debug!("standard seq is invalid; filling with overlap seq");
+            state.sequence.clear();
+            state
+                .sequence
+                .extend(state.overlapped_sequence.iter().copied());
+            if state.sequence.last().copied().unwrap_or(0) != KEY_OVERLAP_MARKER
+                && state.overlapped_sequence.last().copied().unwrap_or(0) >= KEY_OVERLAP_MARKER
+            {
+                // Always treat non-overlapping sequence as if overlap state has
+                // ended; if overlapped_sequence itself has an overlap state.
+                state.sequence.push(KEY_OVERLAP_MARKER);
+            }
+            res = sequences.get_or_descendant_exists(&state.sequence);
+        }
+        (true, true) => {
+            // One more try for backtracking: check for validity by removing from the front.
+            while res == NotInTrie && !state.sequence.is_empty() {
+                state.sequence.remove(0);
+                res = sequences.get_or_descendant_exists(&state.sequence);
+            }
+            if res == NotInTrie || state.sequence.is_empty() {
+                log::debug!("invalid keys for seq");
+                cancel_sequence(state, kbd_out)?;
+            }
+        }
+    }
+
+    // Check for successful sequence termination.
+    if let HasValue((i, j)) = res_overlapped {
+        // First, check for a valid simultaneous completion.
+        // Simultaneous completion should take priority.
+        do_successful_sequence_termination(kbd_out, state, layout, i, j, EndSequenceType::Overlap)?;
+    } else if let HasValue((i, j)) = res {
+        // Try terminating the overlapping and check if simultaneous termination worked.
+        // Simultaneous completion should take priority.
+        state.overlapped_sequence.push(KEY_OVERLAP_MARKER);
+        if let HasValue((oi, oj)) = sequences.get_or_descendant_exists(&state.overlapped_sequence) {
+            do_successful_sequence_termination(
+                kbd_out,
+                state,
+                layout,
+                oi,
+                oj,
+                EndSequenceType::Overlap,
+            )?;
+        } else {
+            do_successful_sequence_termination(
+                kbd_out,
+                state,
+                layout,
+                i,
+                j,
+                EndSequenceType::Standard,
+            )?;
+        }
+    }
+    Ok(())
+}
+
+use kanata_keyberon::key_code::KeyCode::*;
+
+pub(super) fn do_successful_sequence_termination(
+    kbd_out: &mut KbdOut,
+    state: &mut SequenceState,
+    layout: &mut Layout<'_, 767, 2, &CustomAction>,
+    i: u8,
+    j: u16,
+    seq_type: EndSequenceType,
+) -> Result<(), anyhow::Error> {
+    log::debug!("sequence complete; tapping fake key");
+    state.activity = Inactive;
+    let sequence = match seq_type {
+        EndSequenceType::Standard => &state.sequence,
+        EndSequenceType::Overlap => &state.overlapped_sequence,
+    };
+    match state.sequence_input_mode {
+        SequenceInputMode::HiddenSuppressed | SequenceInputMode::HiddenDelayType => {}
+        SequenceInputMode::VisibleBackspaced => {
+            // Release mod keys and backspace because they can cause backspaces to mess up.
+            layout.states.retain(|s| match s {
+                State::NormalKey { keycode, .. } => {
+                    if matches!(keycode, LCtrl | RCtrl | LAlt | RAlt | LGui | RGui) {
+                        // Ignore the error, ugly to return it from retain, and
+                        // this is very unlikely to happen anyway.
+                        let _ = release_key(kbd_out, keycode.into());
+                        false
+                    } else {
+                        true
+                    }
+                }
+                _ => true,
+            });
+            for k in sequence.iter().copied() {
+                // Check for pressed modifiers and don't input backspaces for
+                // those since they don't output characters that can be
+                // backspaced.
+                if k == KEY_OVERLAP_MARKER {
+                    continue;
+                };
+                let osc = OsCode::from(k & MASK_KEYCODES);
+                match osc {
+                    // Known bug: most non-characters-outputting keys are not
+                    // listed. I'm too lazy to list them all. Just use
+                    // character-outputting keys (and modifiers) in sequences
+                    // please! Or switch to a different input mode? It doesn't
+                    // really make sense to use non-typing characters other
+                    // than modifiers does it? Since those would probably be
+                    // further away from the home row, so why use them? If one
+                    // desired to fix this, a shorter list of keys would
+                    // probably be the list of keys that **do** output
+                    // characters than those that don't.
+                    osc if osc.is_modifier() => continue,
+                    osc if matches!(u16::from(osc), KEY_IGNORE_MIN..=KEY_IGNORE_MAX) => continue,
+                    _ => {
+                        if state.noerase_count > 0 {
+                            state.noerase_count -= 1;
+                        } else {
+                            kbd_out.press_key(OsCode::KEY_BACKSPACE)?;
+                            kbd_out.release_key(OsCode::KEY_BACKSPACE)?;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for k in sequence.iter().copied() {
+        if k == KEY_OVERLAP_MARKER {
+            continue;
+        };
+        let kc = KeyCode::from(OsCode::from(k & MASK_KEYCODES));
+        layout.states.retain(|s| match s {
+            State::NormalKey { keycode, .. } => kc != *keycode,
+            _ => true,
+        });
+    }
+    layout.event_to_front(Event::Release(i, j));
+    layout.event_to_front(Event::Press(i, j));
+    Ok(())
+}
+
+pub(super) fn cancel_sequence(state: &mut SequenceState, kbd_out: &mut KbdOut) -> Result<()> {
+    state.activity = Inactive;
+    log::debug!("sequence cancelled");
+    match state.sequence_input_mode {
+        SequenceInputMode::HiddenDelayType => {
+            for osc in state.raw_oscs.iter().copied() {
+                // BUG: chorded_hidden_delay_type
+                press_key(kbd_out, osc)?;
+                release_key(kbd_out, osc)?;
+            }
+        }
+        SequenceInputMode::HiddenSuppressed | SequenceInputMode::VisibleBackspaced => {}
+    }
+    Ok(())
+}
+
+pub(super) fn add_noerase(state: &mut SequenceState, noerase_count: u16) {
+    state.noerase_count += noerase_count;
+}
diff --git a/src/kanata/unknown.rs b/src/kanata/unknown.rs
new file mode 100644
index 000000000..a204f4bdf
--- /dev/null
+++ b/src/kanata/unknown.rs
@@ -0,0 +1,9 @@
+use super::*;
+
+impl Kanata {
+    pub fn check_release_non_physical_shift(&mut self) -> Result<()> {
+        // Silence warning
+        check_for_exit(&KeyEvent::new(OsCode::KEY_UNKNOWN, KeyValue::Release));
+        Ok(())
+    }
+}
diff --git a/src/kanata/windows/exthook.rs b/src/kanata/windows/exthook.rs
new file mode 100644
index 000000000..195ce9b9a
--- /dev/null
+++ b/src/kanata/windows/exthook.rs
@@ -0,0 +1,181 @@
+use parking_lot::Mutex;
+use std::convert::TryFrom;
+use std::sync::Arc;
+use std::sync::mpsc::{Receiver, SyncSender as Sender, TryRecvError, sync_channel};
+use std::time;
+
+use super::PRESSED_KEYS;
+use crate::kanata::*;
+
+impl Kanata {
+    /// Initialize the callback that is passed to the Windows low level hook to receive key events and run the native_windows_gui event loop.
+    pub fn event_loop(_cfg: Arc<Mutex<Self>>, tx: Sender<KeyEvent>) -> Result<()> {
+        let (preprocess_tx, preprocess_rx) = sync_channel(100);
+        start_event_preprocessor(preprocess_rx, tx);
+
+        let _ = KeyboardHook::set_input_cb(move |input_event| {
+            // →true if input event was handled, false otherwise, informs input_ev_listener whether to look for the output key event
+            let mut key_event = match KeyEvent::try_from(input_event) {
+                // InputEvent{code:u32      , up   :bool}
+                Ok(ev) => ev, // KeyEvent  {code:OsCode   , value:KeyValue}
+                _ => return false,
+            }; // Some(OsCode::KEY_0)←0x30        Release0 Press1 Repeat2 Tap WakeUp
+            check_for_exit(&key_event); //noop
+
+            let oscode = OsCode::from(input_event.code);
+            if !MAPPED_KEYS.lock().contains(&oscode) {
+                return false;
+            }
+            log::debug!("event loop: {}", key_event);
+            match key_event.value {
+                // Unlike Linux, Windows does not use a separate value for repeat. However, our code needs to differentiate between initial press and repeat press.
+                KeyValue::Release => {
+                    PRESSED_KEYS.lock().remove(&key_event.code);
+                }
+                KeyValue::Press => {
+                    let mut pressed_keys = PRESSED_KEYS.lock();
+                    if pressed_keys.contains_key(&key_event.code) {
+                        key_event.value = KeyValue::Repeat;
+                    } else {
+                        pressed_keys.insert(key_event.code, web_time::Instant::now());
+                    }
+                }
+                _ => {}
+            }
+            try_send_panic(&preprocess_tx, key_event); // Send input_events to the preprocessing loop. Panic if channel somehow gets full or if channel disconnects. Typing input should never trigger a panic based on the channel getting full, assuming regular operation of the program and some other bug isn't the problem. I've tried to crash the program by pressing as many keys on my keyboard at the same time as I could, but was unable to.
+            #[cfg(feature = "perf_logging")]
+            debug!(
+                " 🕐{}μs sent msg to tx→rx@start_processing_loop from event loop@KeyboardHook::set_input_cb",
+                (start.elapsed()).as_micros()
+            );
+            true
+        });
+        Ok(())
+    }
+}
+
+fn try_send_panic(tx: &Sender<KeyEvent>, kev: KeyEvent) {
+    if let Err(e) = tx.try_send(kev) {
+        panic!("failed to send on channel: {e:?}")
+    }
+}
+
+fn start_event_preprocessor(preprocess_rx: Receiver<KeyEvent>, process_tx: Sender<KeyEvent>) {
+    #[derive(Debug, Clone, Copy, PartialEq)]
+    enum LctlState {
+        Pressed,
+        Released,
+        Pending,
+        PendingReleased,
+        None,
+    }
+
+    std::thread::spawn(move || {
+        let mut lctl_state = LctlState::None;
+        loop {
+            match preprocess_rx.try_recv() {
+                Ok(kev) => match (*ALTGR_BEHAVIOUR.lock(), kev) {
+                    (AltGrBehaviour::DoNothing, _) => try_send_panic(&process_tx, kev),
+                    (
+                        AltGrBehaviour::AddLctlRelease,
+                        KeyEvent {
+                            value: KeyValue::Release,
+                            code: OsCode::KEY_RIGHTALT,
+                            ..
+                        },
+                    ) => {
+                        log::debug!("altgr add: adding lctl release");
+                        try_send_panic(&process_tx, kev);
+                        try_send_panic(
+                            &process_tx,
+                            KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Release),
+                        );
+                        PRESSED_KEYS.lock().remove(&OsCode::KEY_LEFTCTRL);
+                    }
+                    (
+                        AltGrBehaviour::CancelLctlPress,
+                        KeyEvent {
+                            value: KeyValue::Press,
+                            code: OsCode::KEY_LEFTCTRL,
+                            ..
+                        },
+                    ) => {
+                        log::debug!("altgr cancel: lctl state->pressed");
+                        lctl_state = LctlState::Pressed;
+                    }
+                    (
+                        AltGrBehaviour::CancelLctlPress,
+                        KeyEvent {
+                            value: KeyValue::Release,
+                            code: OsCode::KEY_LEFTCTRL,
+                            ..
+                        },
+                    ) => match lctl_state {
+                        LctlState::Pressed => {
+                            log::debug!("altgr cancel: lctl state->released");
+                            lctl_state = LctlState::Released;
+                        }
+                        LctlState::Pending => {
+                            log::debug!("altgr cancel: lctl state->pending-released");
+                            lctl_state = LctlState::PendingReleased;
+                        }
+                        LctlState::None => try_send_panic(&process_tx, kev),
+                        _ => {}
+                    },
+                    (
+                        AltGrBehaviour::CancelLctlPress,
+                        KeyEvent {
+                            value: KeyValue::Press,
+                            code: OsCode::KEY_RIGHTALT,
+                            ..
+                        },
+                    ) => {
+                        log::debug!("altgr cancel: lctl state->none");
+                        lctl_state = LctlState::None;
+                        try_send_panic(&process_tx, kev);
+                    }
+                    (_, _) => try_send_panic(&process_tx, kev),
+                },
+                Err(TryRecvError::Empty) => {
+                    if *ALTGR_BEHAVIOUR.lock() == AltGrBehaviour::CancelLctlPress {
+                        match lctl_state {
+                            LctlState::Pressed => {
+                                log::debug!("altgr cancel: lctl state->pending");
+                                lctl_state = LctlState::Pending;
+                            }
+                            LctlState::Released => {
+                                log::debug!("altgr cancel: lctl state->pending-released");
+                                lctl_state = LctlState::PendingReleased;
+                            }
+                            LctlState::Pending => {
+                                log::debug!("altgr cancel: lctl state->send");
+                                try_send_panic(
+                                    &process_tx,
+                                    KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Press),
+                                );
+                                lctl_state = LctlState::None;
+                            }
+                            LctlState::PendingReleased => {
+                                log::debug!("altgr cancel: lctl state->send+release");
+                                try_send_panic(
+                                    &process_tx,
+                                    KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Press),
+                                );
+                                try_send_panic(
+                                    &process_tx,
+                                    KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Release),
+                                );
+                                lctl_state = LctlState::None;
+                            }
+                            _ => {}
+                        }
+                    }
+                    std::thread::sleep(time::Duration::from_millis(1));
+                }
+                Err(TryRecvError::Disconnected) => {
+                    panic!("channel disconnected (exthook event_preproces)")
+                }
+            }
+        }
+    });
+}
diff --git a/src/kanata/windows/interception.rs b/src/kanata/windows/interception.rs
index a7fe3bd8a..365d2904e 100644
--- a/src/kanata/windows/interception.rs
+++ b/src/kanata/windows/interception.rs
@@ -1,17 +1,16 @@
-use anyhow::Result;
+use anyhow::{Result, anyhow};
 use kanata_interception as ic;
 use parking_lot::Mutex;
-use std::sync::mpsc::Sender;
 use std::sync::Arc;
+use std::sync::mpsc::SyncSender as Sender;
 
 use super::PRESSED_KEYS;
 use crate::kanata::*;
-use kanata_parser::keys::{KeyValue, OsCode};
-
-const HWID_ARR_SZ: usize = 128;
+use crate::oskbd::KeyValue;
+use kanata_parser::keys::OsCode;
 
 impl Kanata {
-    pub fn event_loop(kanata: Arc<Mutex<Self>>, tx: Sender<KeyEvent>) -> Result<()> {
+    pub fn event_loop_inner(kanata: Arc<Mutex<Self>>, tx: Sender<KeyEvent>) -> Result<()> {
         let intrcptn = ic::Interception::new().ok_or_else(|| anyhow!("interception driver should init: have you completed the interception driver installation?"))?;
         intrcptn.set_filter(ic::is_keyboard, ic::Filter::KeyFilter(ic::KeyFilter::all()));
         let mut strokes = [ic::Stroke::Keyboard {
@@ -20,33 +19,24 @@ impl Kanata {
             information: 0,
         }; 32];
 
-        let mouse_to_intercept_hwid: Option<[u8; HWID_ARR_SZ]> = kanata
-            .lock()
-            .intercept_mouse_hwid.as_ref()
-            .map(|hwid| {
-                hwid.iter().copied().enumerate()
-                    .fold([0u8; HWID_ARR_SZ], |mut hwid, idx_byte| {
-                        let (i, b) = idx_byte;
-                        if i > HWID_ARR_SZ {
-                            panic!("windows-interception-mouse-hwid is too long; it should be up to {HWID_ARR_SZ} 8-bit unsigned integers");
-                        }
-                        hwid[i] = b;
-                        hwid
-                    })
-            });
-        if mouse_to_intercept_hwid.is_some() {
-            intrcptn.set_filter(
-                ic::is_mouse,
-                ic::Filter::MouseFilter(
-                    ic::MouseState::all()
-                        & (!ic::MouseState::WHEEL)
-                        & (!ic::MouseState::HWHEEL)
-                        & (!ic::MouseState::MOVE),
-                ),
-            );
+        let keyboards_to_intercept_hwids = kanata.lock().intercept_kb_hwids.clone();
+        let keyboards_to_intercept_hwids_exclude = kanata.lock().intercept_kb_hwids_exclude.clone();
+        let mouse_to_intercept_hwids: Option<Vec<[u8; HWID_ARR_SZ]>> =
+            kanata.lock().intercept_mouse_hwids.clone();
+        let mouse_to_intercept_excluded_hwids: Option<Vec<[u8; HWID_ARR_SZ]>> =
+            kanata.lock().intercept_mouse_hwids_exclude.clone();
+        let mouse_movement_key = kanata.lock().mouse_movement_key.clone();
+        if mouse_to_intercept_hwids.is_some() || mouse_to_intercept_excluded_hwids.is_some() {
+            if mouse_movement_key.lock().is_some() {
+                intrcptn.set_filter(ic::is_mouse, ic::Filter::MouseFilter(ic::MouseState::all()));
+            } else {
+                intrcptn.set_filter(
+                    ic::is_mouse,
+                    ic::Filter::MouseFilter(ic::MouseState::all() & (!ic::MouseState::MOVE)),
+                );
+            }
         }
         let mut is_dev_interceptable: HashMap<ic::Device, bool> = HashMap::default();
-
         loop {
             let dev = intrcptn.wait();
             if dev > 0 {
@@ -54,6 +44,17 @@ impl Kanata {
                 for i in 0..num_strokes {
                     let mut key_event = match strokes[i] {
                         ic::Stroke::Keyboard { state, .. } => {
+                            if !is_device_interceptable(
+                                dev,
+                                &intrcptn,
+                                &keyboards_to_intercept_hwids,
+                                &keyboards_to_intercept_hwids_exclude,
+                                &mut is_dev_interceptable,
+                            ) {
+                                log::debug!("stroke {:?} is from undesired device", strokes[i]);
+                                intrcptn.send(dev, &strokes[i..i + 1]);
+                                continue;
+                            }
                             log::debug!("got stroke {:?}", strokes[i]);
                             let code = match OsCodeWrapper::try_from(strokes[i]) {
                                 Ok(c) => c.0,
@@ -67,23 +68,36 @@ impl Kanata {
                                 false => KeyValue::Press,
                                 true => KeyValue::Release,
                             };
-                            KeyEvent { code, value }
+                            KeyEvent::new(code, value)
                         }
-                        ic::Stroke::Mouse { state, .. } => {
-                            if let Some(hwid) = mouse_to_intercept_hwid {
+                        ic::Stroke::Mouse {
+                            state,
+                            rolling,
+                            flags,
+                            ..
+                        } => {
+                            let allow_this_dev = is_device_interceptable(
+                                dev,
+                                &intrcptn,
+                                &mouse_to_intercept_hwids,
+                                &mouse_to_intercept_excluded_hwids,
+                                &mut is_dev_interceptable,
+                            );
+
+                            if allow_this_dev {
                                 log::trace!("checking mouse stroke {:?}", strokes[i]);
-                                if let Some(event) = mouse_state_to_event(
-                                    dev,
-                                    &hwid,
-                                    state,
-                                    &intrcptn,
-                                    &mut is_dev_interceptable,
-                                ) {
-                                    event
-                                } else {
-                                    intrcptn.send(dev, &strokes[i..i + 1]);
-                                    continue;
+
+                                if let Some(ms_mvmt_key) = *mouse_movement_key.lock()
+                                    && flags.contains(ic::MouseFlags::MOVE_RELATIVE)
+                                {
+                                    tx.try_send(KeyEvent::new(ms_mvmt_key, KeyValue::Tap))?;
                                 }
+                            }
+
+                            if let (true, Some(event)) =
+                                (allow_this_dev, mouse_state_to_event(state, rolling))
+                            {
+                                event
                             } else {
                                 intrcptn.send(dev, &strokes[i..i + 1]);
                                 continue;
@@ -111,85 +125,113 @@ impl Kanata {
                         }
                         _ => {}
                     }
-                    tx.send(key_event)?;
+                    tx.try_send(key_event)?;
                 }
             }
         }
     }
+    pub fn event_loop(
+        kanata: Arc<Mutex<Self>>,
+        tx: Sender<KeyEvent>,
+        #[cfg(feature = "gui")] ui: crate::gui::system_tray_ui::SystemTrayUi,
+    ) -> Result<()> {
+        #[cfg(not(feature = "gui"))]
+        {
+            Self::event_loop_inner(kanata, tx)
+        }
+        #[cfg(feature = "gui")]
+        {
+            std::thread::spawn(move || -> Result<()> { Self::event_loop_inner(kanata, tx) });
+            let _ui = ui; // prevents thread from panicking on exiting via a GUI
+            native_windows_gui::dispatch_thread_events();
+            Ok(())
+        }
+    }
 }
 
-fn mouse_state_to_event(
+fn is_device_interceptable(
     input_dev: ic::Device,
-    allowed_hwid: &[u8; HWID_ARR_SZ],
-    state: ic::MouseState,
     intrcptn: &ic::Interception,
-    is_dev_interceptable: &mut HashMap<ic::Device, bool>,
-) -> Option<KeyEvent> {
-    if !match is_dev_interceptable.get(&input_dev) {
-        Some(v) => *v,
-        None => {
-            let mut hwid = [0u8; HWID_ARR_SZ];
-            log::trace!("getting hardware id for input dev: {input_dev}");
-            let res = intrcptn.get_hardware_id(input_dev, &mut hwid);
-            let dev_is_interceptable = hwid == *allowed_hwid;
-            log::info!("res {res}; device #{input_dev} hwid {hwid:?} matches allowed mouse input: {dev_is_interceptable}");
-            is_dev_interceptable.insert(input_dev, dev_is_interceptable);
-            dev_is_interceptable
-        }
-    } {
-        return None;
+    allowed_hwids: &Option<Vec<[u8; HWID_ARR_SZ]>>,
+    excluded_hwids: &Option<Vec<[u8; HWID_ARR_SZ]>>,
+    cache: &mut HashMap<ic::Device, bool>,
+) -> bool {
+    match (allowed_hwids, excluded_hwids) {
+        (None, None) => true,
+        (Some(allowed), None) => match cache.get(&input_dev) {
+            Some(v) => *v,
+            None => {
+                let mut hwid = [0u8; HWID_ARR_SZ];
+                log::trace!("getting hardware id for input dev: {input_dev}");
+                let res = intrcptn.get_hardware_id(input_dev, &mut hwid);
+                let dev_is_interceptable = allowed.contains(&hwid);
+                log::info!(
+                    "include check - res {res}; device #{input_dev} is intercepted: {dev_is_interceptable}; hwid {hwid:?} "
+                );
+                cache.insert(input_dev, dev_is_interceptable);
+                dev_is_interceptable
+            }
+        },
+        (None, Some(excluded)) => match cache.get(&input_dev) {
+            Some(v) => *v,
+            None => {
+                let mut hwid = [0u8; HWID_ARR_SZ];
+                log::trace!("getting hardware id for input dev: {input_dev}");
+                let res = intrcptn.get_hardware_id(input_dev, &mut hwid);
+                let dev_is_interceptable = !excluded.contains(&hwid);
+                log::info!(
+                    "exclude check - res {res}; device #{input_dev} is intercepted: {dev_is_interceptable}; hwid {hwid:?} "
+                );
+                cache.insert(input_dev, dev_is_interceptable);
+                dev_is_interceptable
+            }
+        },
+        _ => unreachable!("excluded and allowed should be mutually exclusive"),
     }
-
+}
+fn mouse_state_to_event(state: ic::MouseState, rolling: i16) -> Option<KeyEvent> {
     if state.contains(ic::MouseState::RIGHT_BUTTON_DOWN) {
-        Some(KeyEvent {
-            code: OsCode::BTN_RIGHT,
-            value: KeyValue::Press,
-        })
+        Some(KeyEvent::new(OsCode::BTN_RIGHT, KeyValue::Press))
     } else if state.contains(ic::MouseState::RIGHT_BUTTON_UP) {
-        Some(KeyEvent {
-            code: OsCode::BTN_RIGHT,
-            value: KeyValue::Release,
-        })
+        Some(KeyEvent::new(OsCode::BTN_RIGHT, KeyValue::Release))
     } else if state.contains(ic::MouseState::LEFT_BUTTON_DOWN) {
-        Some(KeyEvent {
-            code: OsCode::BTN_LEFT,
-            value: KeyValue::Press,
-        })
+        Some(KeyEvent::new(OsCode::BTN_LEFT, KeyValue::Press))
     } else if state.contains(ic::MouseState::LEFT_BUTTON_UP) {
-        Some(KeyEvent {
-            code: OsCode::BTN_LEFT,
-            value: KeyValue::Release,
-        })
+        Some(KeyEvent::new(OsCode::BTN_LEFT, KeyValue::Release))
     } else if state.contains(ic::MouseState::MIDDLE_BUTTON_DOWN) {
-        Some(KeyEvent {
-            code: OsCode::BTN_MIDDLE,
-            value: KeyValue::Press,
-        })
+        Some(KeyEvent::new(OsCode::BTN_MIDDLE, KeyValue::Press))
     } else if state.contains(ic::MouseState::MIDDLE_BUTTON_UP) {
-        Some(KeyEvent {
-            code: OsCode::BTN_MIDDLE,
-            value: KeyValue::Release,
-        })
+        Some(KeyEvent::new(OsCode::BTN_MIDDLE, KeyValue::Release))
     } else if state.contains(ic::MouseState::BUTTON_4_DOWN) {
-        Some(KeyEvent {
-            code: OsCode::BTN_SIDE,
-            value: KeyValue::Press,
-        })
+        Some(KeyEvent::new(OsCode::BTN_SIDE, KeyValue::Press))
     } else if state.contains(ic::MouseState::BUTTON_4_UP) {
-        Some(KeyEvent {
-            code: OsCode::BTN_SIDE,
-            value: KeyValue::Release,
-        })
+        Some(KeyEvent::new(OsCode::BTN_SIDE, KeyValue::Release))
     } else if state.contains(ic::MouseState::BUTTON_5_DOWN) {
-        Some(KeyEvent {
-            code: OsCode::BTN_EXTRA,
-            value: KeyValue::Press,
-        })
+        Some(KeyEvent::new(OsCode::BTN_EXTRA, KeyValue::Press))
     } else if state.contains(ic::MouseState::BUTTON_5_UP) {
-        Some(KeyEvent {
-            code: OsCode::BTN_EXTRA,
-            value: KeyValue::Release,
-        })
+        Some(KeyEvent::new(OsCode::BTN_EXTRA, KeyValue::Release))
+    } else if state.contains(ic::MouseState::WHEEL) {
+        let osc = if rolling >= 0 {
+            OsCode::MouseWheelUp
+        } else {
+            OsCode::MouseWheelDown
+        };
+        if MAPPED_KEYS.lock().contains(&osc) {
+            Some(KeyEvent::new(osc, KeyValue::Tap))
+        } else {
+            None
+        }
+    } else if state.contains(ic::MouseState::HWHEEL) {
+        let osc = if rolling >= 0 {
+            OsCode::MouseWheelRight
+        } else {
+            OsCode::MouseWheelLeft
+        };
+        if MAPPED_KEYS.lock().contains(&osc) {
+            Some(KeyEvent::new(osc, KeyValue::Tap))
+        } else {
+            None
+        }
     } else {
         None
     }
diff --git a/src/kanata/windows/llhook.rs b/src/kanata/windows/llhook.rs
index 59e7a1153..7a2d9c505 100644
--- a/src/kanata/windows/llhook.rs
+++ b/src/kanata/windows/llhook.rs
@@ -1,7 +1,7 @@
 use parking_lot::Mutex;
 use std::convert::TryFrom;
-use std::sync::mpsc::{channel, Receiver, Sender, TryRecvError};
 use std::sync::Arc;
+use std::sync::mpsc::{Receiver, RecvError, SyncSender as Sender, TryRecvError, sync_channel};
 use std::time;
 
 use super::PRESSED_KEYS;
@@ -10,18 +10,24 @@ use crate::kanata::*;
 impl Kanata {
     /// Initialize the callback that is passed to the Windows low level hook to receive key events
     /// and run the native_windows_gui event loop.
-    pub fn event_loop(_kanata: Arc<Mutex<Self>>, tx: Sender<KeyEvent>) -> Result<()> {
+    pub fn event_loop(
+        _cfg: Arc<Mutex<Self>>,
+        tx: Sender<KeyEvent>,
+        #[cfg(all(target_os = "windows", feature = "gui"))]
+        ui: crate::gui::system_tray_ui::SystemTrayUi,
+    ) -> Result<()> {
         // Display debug and panic output when launched from a terminal.
+        #[cfg(not(feature = "gui"))]
         unsafe {
             use winapi::um::wincon::*;
             if AttachConsole(ATTACH_PARENT_PROCESS) != 0 {
                 panic!("Could not attach to console");
             }
         };
-        native_windows_gui::init()?;
 
-        let (preprocess_tx, preprocess_rx) = channel();
+        let (preprocess_tx, preprocess_rx) = sync_channel(100);
         start_event_preprocessor(preprocess_rx, tx);
+        let kb_preprocess_tx = preprocess_tx.clone();
 
         // This callback should return `false` if the input event is **not** handled by the
         // callback and `true` if the input event **is** handled by the callback. Returning false
@@ -34,7 +40,7 @@ impl Kanata {
             };
 
             check_for_exit(&key_event);
-            let oscode = OsCode::from(input_event.code);
+            let oscode = key_event.code;
             if !MAPPED_KEYS.lock().contains(&oscode) {
                 return false;
             }
@@ -43,15 +49,22 @@ impl Kanata {
             // needs to differentiate between initial press and repeat press.
             log::debug!("event loop: {:?}", key_event);
             match key_event.value {
-                KeyValue::Release => {
-                    PRESSED_KEYS.lock().remove(&key_event.code);
+                KeyValue::Release if PRESSED_KEYS.lock().remove(&key_event.code).is_none() => {
+                    log::debug!("forwarding release of never-seen press {:?}", key_event);
+                    // If we never saw the initial press for this release,
+                    // we should not pass it along to the processing loop.
+                    // There is likely a pressed key in Windows that Kanata never knew about.
+                    // Consuming the release here will mean Windows gets a stuck press.
+                    return false;
                 }
                 KeyValue::Press => {
                     let mut pressed_keys = PRESSED_KEYS.lock();
-                    if pressed_keys.contains(&key_event.code) {
-                        key_event.value = KeyValue::Repeat;
+                    if let std::collections::hash_map::Entry::Vacant(e) =
+                        pressed_keys.entry(key_event.code)
+                    {
+                        e.insert(web_time::Instant::now());
                     } else {
-                        pressed_keys.insert(key_event.code);
+                        key_event.value = KeyValue::Repeat;
                     }
                 }
                 _ => {}
@@ -62,108 +75,355 @@ impl Kanata {
             // getting full, assuming regular operation of the program and some other bug isn't the
             // problem. I've tried to crash the program by pressing as many keys on my keyboard at
             // the same time as I could, but was unable to.
-            try_send_panic(&preprocess_tx, key_event);
+            try_send_panic(&kb_preprocess_tx, key_event);
             true
         });
 
+        use OsCode::*;
+        let oscodes_for_mhook_active = &[
+            BTN_LEFT,
+            BTN_RIGHT,
+            BTN_MIDDLE,
+            BTN_SIDE,
+            BTN_EXTRA,
+            MouseWheelUp,
+            MouseWheelDown,
+            MouseWheelLeft,
+            MouseWheelRight,
+        ];
+        let _handle = if oscodes_for_mhook_active
+            .iter()
+            .any(|osc| MAPPED_KEYS.lock().contains(osc))
+        {
+            log::info!("Installing mouse hook callback.");
+            let mousehook = MouseHook::set_input_cb(move |mouse_event| {
+                log::debug!("llhook mouse event: {mouse_event:?}");
+                let key_event = match KeyEvent::try_from(mouse_event) {
+                    Ok(ev) => ev,
+                    _ => return false,
+                };
+                let oscode = key_event.code;
+                if !MAPPED_KEYS.lock().contains(&oscode) {
+                    return false;
+                }
+                log::debug!("event loop - mouse: {:?}", key_event);
+                try_send_panic(&preprocess_tx, key_event);
+                true
+            });
+            log::info!("Installed mouse hook callback successfully.");
+            Some(mousehook)
+        } else {
+            log::info!("No mouse inputs were in defsrc on startup. Not activating mouse hook.");
+            None
+        };
+
+        #[cfg(all(target_os = "windows", feature = "gui"))]
+        let _ui = ui; // prevents thread from panicking on exiting via a GUI
         // The event loop is also required for the low-level keyboard hook to work.
         native_windows_gui::dispatch_thread_events();
         Ok(())
     }
+
+    /// # Note
+    ///
+    /// This is disabled by default due to known issues.
+    /// Under some use cases this works just fine and can be enabled.
+    ///
+    /// ## Known issues
+    ///
+    /// - Ralt/lctl may have some issues with AltGr layouts
+    /// - Some software may have a later-stage remapping that changes which VK is active for a
+    ///   given VK that Kanata outputs. E.g. changing to roya/loya modifiers.
+    ///
+    /// # Description
+    ///
+    /// On Windows with LLHOOK/SendInput APIs,
+    /// Kanata does not have as much control
+    /// over the full system's keystates as one would want;
+    /// unlike in Linux or with the Interception driver.
+    /// Sometimes Kanata can miss events; e.g. a release is
+    /// missed and a keystate remains pressed within Kanata (1),
+    /// or a press is missed in Kanata but the release is caught,
+    /// and thus the keystate remains pressed within the Windows system
+    /// because Kanata consumed the release and didn't know what to do about it (2).
+    ///
+    /// For (1), `release_normalkey_states` theoretically fixes the issue
+    /// after 60s of Kanata being idle,
+    /// but that is a long time and doesn't seem to work consistently.
+    /// Unfortunately this does not seem to be easily fixable in all cases.
+    /// For example, a press consumed by Kanata could result in
+    /// **only** a `(layer-while-held ...)` action as the output;
+    /// if the corresponding release were missed,
+    /// Kanata has no information available from the larger Windows system
+    /// to confirm that the physical key is actually released
+    /// but that the process didn't see the event.
+    /// E.g. there is the `GetAsyncKeyState` API
+    /// and this will be useful when the missed release has a key output,
+    /// but not with the layer example.
+    /// There does not appear to be any "raw input" mechanism
+    /// to see the snapshot of the current state of physical keyboard keys.
+    ///
+    /// For (2), consider that this might be fixed purely within Kanata's
+    /// event handling and processing, by checking Kanata's active action states,
+    /// and if there are no active states corresponding to a released event,
+    /// to send a release of the original input.
+    /// This would result in extra release events though;
+    /// for example if the `A` key action is `(macro a)`,
+    /// the above logic will result in a second SendInput release event of `A`.
+    /// Instead, this function checks against the outside Windows state.
+    ///
+    /// The solution makes use of the following states:
+    /// - `MAPPED_KEYS` (MK)
+    /// - `GetAsyncKeyState` WinAPI (GKS)
+    /// - `PRESSED_KEYS` (PK)
+    /// - `self.prev_keys` (SPV)
+    ///
+    /// If a discrepancy is detected,
+    /// this procedure releases Windows keys via SendInput
+    /// and/or clears internal Kanata states.
+    ///
+    /// The checks are:
+    /// 1. For all of SPV, check that it is pressed in GKS.
+    ///    If a key is not pressed, find the coordinate of this state.
+    ///    Clear in PK and clear all states with the same coordinate as key output.
+    /// 2. For all keys in MK and active in GKS, check it is in SPV.
+    ///    If not in SPV, call SendInput to release in Windows.
+    #[cfg(not(feature = "simulated_input"))]
+    pub(crate) fn win_synchronize_keystates(&mut self) {
+        use kanata_keyberon::layout::*;
+        use winapi::um::winuser::*;
+
+        // Note: this procedure (1) used to be also gated behind the config flag.
+        // Revisiting it later, it should be reasonably safe to always run this,
+        // because releasing a Kanata state should not interfere with other programs
+        // in contrast to releasing Windows VK codes which could.
+        log::debug!("synchronizing kanata keystates with windows");
+        for pvk in self.prev_keys.iter() {
+            // Check 1 : each pvk is expected to be pressed.
+            let osc: OsCode = pvk.into();
+            let vk = i32::from(osc);
+            if vk > 254 {
+                // 254 should be highest valid VK number in Windows OS.
+                continue;
+            }
+            let vk_state = unsafe { GetAsyncKeyState(vk) } as u32;
+            let is_pressed_in_windows = vk_state >= 0b1000000;
+            if is_pressed_in_windows {
+                continue;
+            }
+
+            log::error!(
+                "Unexpected keycode is pressed in kanata but not in Windows. Clearing kanata states: {pvk:?}"
+            );
+            // Need to clear internal state about this key.
+            // find coordinate(s) in keyberon associated with pvk
+            let mut coords_to_clear = Vec::<KCoord>::new();
+            let layout = self.layout.bm();
+            layout.states.retain(|s| {
+                let retain = match s.keycode() {
+                    Some(k) => k != *pvk,
+                    _ => true,
+                };
+                if !retain && let Some(coord) = s.coord() {
+                    coords_to_clear.push(coord);
+                }
+                retain
+            });
+
+            // Clear other states other than keycode associated with a keycode that needs to be
+            // cleaned up.
+            layout.states.retain(|s| match s.coord() {
+                Some(c) => !coords_to_clear.contains(&c),
+                None => true,
+            });
+
+            // Clear PRESSED_KEYS for coordinates associated with real and not virtual keys
+            let mut pressed_keys = PRESSED_KEYS.lock();
+            for osc in coords_to_clear.iter().copied().filter_map(|c| match c {
+                (FAKE_KEY_ROW, _) => None,
+                (_, kc) => Some(OsCode::from(kc)),
+            }) {
+                pressed_keys.remove(&osc);
+            }
+            drop(pressed_keys);
+        }
+
+        if !self.windows_sync_keystates {
+            return;
+        }
+
+        log::debug!("releasing windows keystates with kanata");
+        let mapped_keys = MAPPED_KEYS.lock();
+        for mapped_osc in mapped_keys.iter().copied() {
+            // Check 2: each active win vk mapped in Kanata should have a value in pvk
+            if matches!(
+                mapped_osc,
+                OsCode::BTN_LEFT
+                    | OsCode::BTN_RIGHT
+                    | OsCode::BTN_MIDDLE
+                    | OsCode::BTN_SIDE
+                    | OsCode::BTN_EXTRA
+            ) {
+                // Skip mouse. Probably not under primary control of Kanata.
+                continue;
+            }
+            let vk = i32::from(mapped_osc);
+            if vk >= 256 {
+                continue;
+            }
+            let vk_state = unsafe { GetAsyncKeyState(vk) } as u32;
+            let is_pressed_in_windows = vk_state >= 0b1000000;
+            if !is_pressed_in_windows {
+                continue;
+            }
+            let vk = vk as u16;
+            let Some(osc) = OsCode::from_u16(vk) else {
+                continue;
+            };
+            if self.prev_keys.contains(&osc.into()) {
+                continue;
+            }
+            log::error!(
+                "Unexpected keycode is pressed in Windows but not Kanata. Releasing in Windows: {osc}"
+            );
+            let _ = release_key(&mut self.kbd_out, osc);
+        }
+        drop(mapped_keys);
+    }
 }
 
 fn try_send_panic(tx: &Sender<KeyEvent>, kev: KeyEvent) {
-    if let Err(e) = tx.send(kev) {
+    if let Err(e) = tx.try_send(kev) {
         panic!("failed to send on channel: {e:?}")
     }
 }
 
-fn start_event_preprocessor(preprocess_rx: Receiver<KeyEvent>, process_tx: Sender<KeyEvent>) {
-    #[derive(Debug, Clone, Copy, PartialEq)]
-    enum LctlState {
-        Pressed,
-        Released,
-        Pending,
-        PendingReleased,
-        None,
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum LctlState {
+    Pressed,
+    Released,
+    Pending,
+    PendingReleased,
+    None,
+}
+
+#[derive(Debug, Clone, Copy)]
+enum RecvValue {
+    Ok(KeyEvent),
+    Empty,
+    Disconnected,
+}
+
+enum CanBlock {
+    YesCanBlock,
+    NoMustPeriodicPoll,
+}
+
+fn preprocessor_recv(preprocess_rx: &Receiver<KeyEvent>, can_block: CanBlock) -> RecvValue {
+    match can_block {
+        CanBlock::YesCanBlock => match preprocess_rx.recv() {
+            Ok(kev) => RecvValue::Ok(kev),
+            Err(RecvError) => RecvValue::Disconnected,
+        },
+        CanBlock::NoMustPeriodicPoll => match preprocess_rx.try_recv() {
+            Ok(kev) => RecvValue::Ok(kev),
+            Err(TryRecvError::Empty) => RecvValue::Empty,
+            Err(TryRecvError::Disconnected) => RecvValue::Disconnected,
+        },
     }
+}
 
+fn start_event_preprocessor(preprocess_rx: Receiver<KeyEvent>, process_tx: Sender<KeyEvent>) {
+    use CanBlock::*;
+    use RecvValue::*;
     std::thread::spawn(move || {
         let mut lctl_state = LctlState::None;
+        let mut can_block = NoMustPeriodicPoll;
         loop {
-            match preprocess_rx.try_recv() {
-                Ok(kev) => match (*ALTGR_BEHAVIOUR.lock(), kev) {
-                    (AltGrBehaviour::DoNothing, _) => try_send_panic(&process_tx, kev),
-                    (
-                        AltGrBehaviour::AddLctlRelease,
-                        KeyEvent {
-                            value: KeyValue::Release,
-                            code: OsCode::KEY_RIGHTALT,
-                            ..
-                        },
-                    ) => {
-                        log::debug!("altgr add: adding lctl release");
-                        try_send_panic(&process_tx, kev);
-                        try_send_panic(
-                            &process_tx,
-                            KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Release),
-                        );
-                        PRESSED_KEYS.lock().remove(&OsCode::KEY_LEFTCTRL);
-                    }
-                    (
-                        AltGrBehaviour::CancelLctlPress,
-                        KeyEvent {
-                            value: KeyValue::Press,
-                            code: OsCode::KEY_LEFTCTRL,
-                            ..
-                        },
-                    ) => {
-                        log::debug!("altgr cancel: lctl state->pressed");
-                        lctl_state = LctlState::Pressed;
-                    }
-                    (
-                        AltGrBehaviour::CancelLctlPress,
-                        KeyEvent {
-                            value: KeyValue::Release,
-                            code: OsCode::KEY_LEFTCTRL,
-                            ..
-                        },
-                    ) => match lctl_state {
-                        LctlState::Pressed => {
-                            log::debug!("altgr cancel: lctl state->released");
-                            lctl_state = LctlState::Released;
+            can_block = match preprocessor_recv(&preprocess_rx, can_block) {
+                Ok(kev) => {
+                    match (*ALTGR_BEHAVIOUR.lock(), kev) {
+                        (AltGrBehaviour::DoNothing, _) => {
+                            try_send_panic(&process_tx, kev);
+                        }
+                        (
+                            AltGrBehaviour::AddLctlRelease,
+                            KeyEvent {
+                                value: KeyValue::Release,
+                                code: OsCode::KEY_RIGHTALT,
+                                ..
+                            },
+                        ) => {
+                            log::debug!("altgr add: adding lctl release");
+                            try_send_panic(&process_tx, kev);
+                            try_send_panic(
+                                &process_tx,
+                                KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Release),
+                            );
+                            PRESSED_KEYS.lock().remove(&OsCode::KEY_LEFTCTRL);
                         }
-                        LctlState::Pending => {
-                            log::debug!("altgr cancel: lctl state->pending-released");
-                            lctl_state = LctlState::PendingReleased;
+                        (
+                            AltGrBehaviour::CancelLctlPress,
+                            KeyEvent {
+                                value: KeyValue::Press,
+                                code: OsCode::KEY_LEFTCTRL,
+                                ..
+                            },
+                        ) => {
+                            log::debug!("altgr cancel: lctl state->pressed");
+                            lctl_state = LctlState::Pressed;
                         }
-                        LctlState::None => try_send_panic(&process_tx, kev),
-                        _ => {}
-                    },
-                    (
-                        AltGrBehaviour::CancelLctlPress,
-                        KeyEvent {
-                            value: KeyValue::Press,
-                            code: OsCode::KEY_RIGHTALT,
-                            ..
+                        (
+                            AltGrBehaviour::CancelLctlPress,
+                            KeyEvent {
+                                value: KeyValue::Release,
+                                code: OsCode::KEY_LEFTCTRL,
+                                ..
+                            },
+                        ) => match lctl_state {
+                            LctlState::Pressed => {
+                                log::debug!("altgr cancel: lctl state->released");
+                                lctl_state = LctlState::Released;
+                            }
+                            LctlState::Pending => {
+                                log::debug!("altgr cancel: lctl state->pending-released");
+                                lctl_state = LctlState::PendingReleased;
+                            }
+                            LctlState::None => {
+                                try_send_panic(&process_tx, kev);
+                            }
+                            _ => {}
                         },
-                    ) => {
-                        log::debug!("altgr cancel: lctl state->none");
-                        lctl_state = LctlState::None;
-                        try_send_panic(&process_tx, kev);
+                        (
+                            AltGrBehaviour::CancelLctlPress,
+                            KeyEvent {
+                                value: KeyValue::Press,
+                                code: OsCode::KEY_RIGHTALT,
+                                ..
+                            },
+                        ) => {
+                            log::debug!("altgr cancel: lctl state->none");
+                            lctl_state = LctlState::None;
+                            try_send_panic(&process_tx, kev);
+                        }
+                        (_, _) => {
+                            try_send_panic(&process_tx, kev);
+                        }
                     }
-                    (_, _) => try_send_panic(&process_tx, kev),
-                },
-                Err(TryRecvError::Empty) => {
-                    if *ALTGR_BEHAVIOUR.lock() == AltGrBehaviour::CancelLctlPress {
+                    NoMustPeriodicPoll
+                }
+                Empty => {
+                    can_block = if *ALTGR_BEHAVIOUR.lock() == AltGrBehaviour::CancelLctlPress {
                         match lctl_state {
                             LctlState::Pressed => {
                                 log::debug!("altgr cancel: lctl state->pending");
                                 lctl_state = LctlState::Pending;
+                                NoMustPeriodicPoll
                             }
                             LctlState::Released => {
                                 log::debug!("altgr cancel: lctl state->pending-released");
                                 lctl_state = LctlState::PendingReleased;
+                                NoMustPeriodicPoll
                             }
                             LctlState::Pending => {
                                 log::debug!("altgr cancel: lctl state->send");
@@ -172,6 +432,7 @@ fn start_event_preprocessor(preprocess_rx: Receiver<KeyEvent>, process_tx: Sende
                                     KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Press),
                                 );
                                 lctl_state = LctlState::None;
+                                NoMustPeriodicPoll
                             }
                             LctlState::PendingReleased => {
                                 log::debug!("altgr cancel: lctl state->send+release");
@@ -184,13 +445,17 @@ fn start_event_preprocessor(preprocess_rx: Receiver<KeyEvent>, process_tx: Sende
                                     KeyEvent::new(OsCode::KEY_LEFTCTRL, KeyValue::Release),
                                 );
                                 lctl_state = LctlState::None;
+                                NoMustPeriodicPoll
                             }
-                            _ => {}
+                            _ => YesCanBlock,
                         }
-                    }
+                    } else {
+                        YesCanBlock
+                    };
                     std::thread::sleep(time::Duration::from_millis(1));
+                    can_block
                 }
-                Err(TryRecvError::Disconnected) => {
+                Disconnected => {
                     panic!("channel disconnected")
                 }
             }
diff --git a/src/kanata/windows/mod.rs b/src/kanata/windows/mod.rs
index 658d831e3..9575fb556 100644
--- a/src/kanata/windows/mod.rs
+++ b/src/kanata/windows/mod.rs
@@ -1,61 +1,40 @@
-use anyhow::{bail, Result};
+use anyhow::Result;
 
 use parking_lot::Mutex;
 
 use crate::kanata::*;
-use kanata_parser::cfg;
 
-#[cfg(not(feature = "interception_driver"))]
-mod llhook;
-#[cfg(not(feature = "interception_driver"))]
-pub use llhook::*;
-
-#[cfg(feature = "interception_driver")]
+#[cfg(all(feature = "simulated_input", not(feature = "interception_driver")))]
+mod exthook;
+#[cfg(all(not(feature = "simulated_input"), feature = "interception_driver"))]
 mod interception;
-#[cfg(feature = "interception_driver")]
-pub use self::interception::*;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum AltGrBehaviour {
-    DoNothing,
-    CancelLctlPress,
-    AddLctlRelease,
-}
-
-static PRESSED_KEYS: Lazy<Mutex<HashSet<OsCode>>> = Lazy::new(|| Mutex::new(HashSet::default()));
+#[cfg(all(not(feature = "simulated_input"), not(feature = "interception_driver")))]
+mod llhook;
 
 pub static ALTGR_BEHAVIOUR: Lazy<Mutex<AltGrBehaviour>> =
-    Lazy::new(|| Mutex::new(AltGrBehaviour::DoNothing));
+    Lazy::new(|| Mutex::new(AltGrBehaviour::default()));
 
-pub fn set_win_altgr_behaviour(cfg: &cfg::Cfg) -> Result<()> {
-    *ALTGR_BEHAVIOUR.lock() = {
-        const CANCEL: &str = "cancel-lctl-press";
-        const ADD: &str = "add-lctl-release";
-        match cfg.items.get("windows-altgr") {
-            None => AltGrBehaviour::DoNothing,
-            Some(cfg_val) => match cfg_val.as_str() {
-                CANCEL => AltGrBehaviour::CancelLctlPress,
-                ADD => AltGrBehaviour::AddLctlRelease,
-                _ => bail!(
-                    "Invalid value for windows-altgr: {}. Valid values are {},{}",
-                    cfg_val,
-                    CANCEL,
-                    ADD
-                ),
-            },
-        }
-    };
-    Ok(())
+pub fn set_win_altgr_behaviour(b: AltGrBehaviour) {
+    *ALTGR_BEHAVIOUR.lock() = b;
 }
 
 impl Kanata {
-    #[cfg(not(feature = "interception_driver"))]
+    #[cfg(all(
+        not(feature = "interception_driver"),
+        not(feature = "simulated_output"),
+        not(feature = "win_sendinput_send_scancodes"),
+    ))]
     pub fn check_release_non_physical_shift(&mut self) -> Result<()> {
         fn state_filter(v: &State<'_, &&[&CustomAction]>) -> Option<State<'static, ()>> {
             match v {
-                State::NormalKey { keycode, coord } => Some(State::NormalKey::<()> {
+                State::NormalKey {
+                    keycode,
+                    coord,
+                    flags,
+                } => Some(State::NormalKey::<()> {
                     keycode: *keycode,
                     coord: *coord,
+                    flags: *flags,
                 }),
                 State::FakeKey { keycode } => Some(State::FakeKey::<()> { keycode: *keycode }),
                 _ => None,
@@ -81,38 +60,64 @@ impl Kanata {
         // this should not be a problem. State does not implement Hash so can't use a HashSet. A
         // HashSet might perform worse anyway.
         for prev_state in prev_states.iter() {
-            if let State::NormalKey { keycode, coord } = prev_state {
-                if !matches!(keycode, KeyCode::LShift | KeyCode::RShift)
-                    || (matches!(keycode, KeyCode::LShift)
-                        && coord.1 == u16::from(OsCode::KEY_LEFTSHIFT))
-                    || (matches!(keycode, KeyCode::RShift)
-                        && coord.1 == u16::from(OsCode::KEY_RIGHTSHIFT))
-                    || self
-                        .layout
-                        .bm()
-                        .states
-                        .iter()
-                        .filter_map(state_filter)
-                        .any(|s| s == *prev_state)
-                {
-                    continue;
+            let keycode = match prev_state {
+                State::NormalKey { keycode, coord, .. } => {
+                    // Goal of this conditional:
+                    //
+                    // Do not process state if:
+                    // - keycode is neither shift
+                    // - keycode is at the position of either shift
+                    // - state has not yet been released
+                    if !matches!(keycode, KeyCode::LShift | KeyCode::RShift)
+                        || *coord == (NORMAL_KEY_ROW, u16::from(OsCode::KEY_LEFTSHIFT))
+                        || *coord == (NORMAL_KEY_ROW, u16::from(OsCode::KEY_RIGHTSHIFT))
+                        || self
+                            .layout
+                            .bm()
+                            .states
+                            .iter()
+                            .filter_map(state_filter)
+                            .any(|s| s == *prev_state)
+                    {
+                        continue;
+                    } else {
+                        keycode
+                    }
                 }
-                log::debug!(
-                    "lsft-arrowkey workaround: releasing {keycode:?} at its typical coordinate"
-                );
-                self.layout.bm().states.retain(|s| match s {
-                    State::NormalKey {
-                        keycode: cur_kc,
-                        coord: cur_coord,
-                    } => cur_kc != keycode && *cur_coord != (0, u16::from(OsCode::from(keycode))),
-                    _ => true,
-                });
-                log::debug!("releasing {keycode:?} from pressed keys");
-                PRESSED_KEYS.lock().remove(&keycode.into());
-                if let Err(e) = self.kbd_out.release_key(keycode.into()) {
-                    bail!("failed to release key: {:?}", e);
+                State::FakeKey { keycode } => {
+                    // Goal of this conditional:
+                    //
+                    // Do not process state if:
+                    // - keycode is neither shift
+                    // - state has not yet been released
+                    if !matches!(keycode, KeyCode::LShift | KeyCode::RShift)
+                        || self
+                            .layout
+                            .bm()
+                            .states
+                            .iter()
+                            .filter_map(state_filter)
+                            .any(|s| s == *prev_state)
+                    {
+                        continue;
+                    } else {
+                        keycode
+                    }
                 }
-            }
+                _ => continue,
+            };
+            log::debug!("lsft-arrowkey workaround: removing {keycode:?} at its typical coordinate");
+            self.layout.bm().states.retain(|s| match s {
+                State::LayerModifier { coord, .. }
+                | State::Custom { coord, .. }
+                | State::RepeatingSequence { coord, .. }
+                | State::NormalKey { coord, .. } => {
+                    *coord != (NORMAL_KEY_ROW, u16::from(OsCode::from(keycode)))
+                }
+                _ => true,
+            });
+            log::debug!("removing {keycode:?} from pressed keys");
+            PRESSED_KEYS.lock().remove(&keycode.into());
         }
 
         prev_states.clear();
@@ -120,13 +125,79 @@ impl Kanata {
         Ok(())
     }
 
-    #[cfg(feature = "interception_driver")]
+    #[cfg(any(
+        feature = "interception_driver",
+        feature = "simulated_output",
+        feature = "win_sendinput_send_scancodes"
+    ))]
     pub fn check_release_non_physical_shift(&mut self) -> Result<()> {
         Ok(())
     }
 
-    pub fn set_repeat_rate(_cfg_items: &HashMap<String, String>) -> Result<()> {
-        // TODO: no-op right now
+    #[cfg(feature = "gui")]
+    pub fn live_reload(&mut self) -> Result<()> {
+        self.live_reload_requested = true;
+        self.do_live_reload(&None)?;
         Ok(())
     }
+    #[cfg(feature = "gui")]
+    pub fn live_reload_n(&mut self, n: usize) -> Result<()> {
+        // can't use in CustomAction::LiveReloadNum(n) due to 2nd mut borrow
+        self.live_reload_requested = true;
+        // let backup_cfg_idx = self.cur_cfg_idx;
+        match self.cfg_paths.get(n) {
+            Some(path) => {
+                self.cur_cfg_idx = n;
+                log::info!("Requested live reload of file: {}", path.display(),);
+            }
+            None => {
+                log::error!(
+                    "Requested live reload of config file number {}, but only {} config files were passed",
+                    n + 1,
+                    self.cfg_paths.len()
+                );
+            }
+        }
+        // if let Err(e) = self.do_live_reload(&None) {
+        // self.cur_cfg_idx = backup_cfg_idx; // restore index on fail when. TODO: add when a similar reversion is added to other custom actions
+        // return Err(e)
+        // }
+        self.do_live_reload(&None)?;
+        Ok(())
+    }
+}
+
+/// If kanata has been inactive for long enough, clear all states.
+/// This won't trigger if there are macros running, or if a key is
+/// held down for a long time and is sending OS repeats. The reason
+/// for this code is in case like Win+L which locks the Windows
+/// desktop. When this happens, the Win key and L key will be stuck
+/// as pressed in the kanata state because LLHOOK kanata cannot read
+/// keys in the lock screen or administrator applications. So this
+/// is heuristic to detect such an issue and clear states assuming
+/// that's what happened.
+///
+/// Only states in the normal key row are cleared, since those are
+/// the states that might be stuck. A real use case might be to have
+/// a fake key pressed for a long period of time, so make sure those
+/// are not cleared.
+#[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+pub fn clear_states_from_inactivity(
+    k: &mut parking_lot::MutexGuard<Kanata>,
+    now: web_time::Instant,
+    last_input_time: web_time::Instant,
+    idle_clear_happened: &mut bool,
+) {
+    if (now - (last_input_time)) > time::Duration::from_secs(LLHOOK_IDLE_TIME_SECS_CLEAR_INPUTS)
+        && !*idle_clear_happened
+    {
+        *idle_clear_happened = true;
+        log::debug!("clearing keyberon normal key states due to inactivity");
+        let layout = k.layout.bm();
+        release_normalkey_states(layout);
+        let now = web_time::Instant::now();
+        PRESSED_KEYS
+            .lock()
+            .retain(|_, v| now - *v < std::time::Duration::from_secs(5));
+    }
 }
diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 000000000..a54c15ecc
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,73 @@
+use anyhow::{Error, Result, anyhow};
+use std::net::SocketAddr;
+use std::path::PathBuf;
+use std::str::FromStr;
+
+#[cfg(all(target_os = "windows", feature = "gui"))]
+pub mod gui;
+pub mod kanata;
+pub mod oskbd;
+pub mod tcp_server;
+#[cfg(test)]
+pub mod tests;
+
+pub use kanata::*;
+pub use kanata_parser::cfg::FAKE_KEY_ROW;
+pub use kanata_parser::custom_action::FakeKeyAction;
+pub use tcp_server::TcpServer;
+
+type CfgPath = PathBuf;
+
+pub struct ValidatedArgs {
+    pub paths: Vec<CfgPath>,
+    #[cfg(feature = "tcp_server")]
+    pub tcp_server_address: Option<SocketAddrWrapper>,
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub symlink_path: Option<String>,
+    pub nodelay: bool,
+}
+
+pub fn default_cfg() -> Vec<PathBuf> {
+    let mut cfgs = Vec::new();
+
+    let default = PathBuf::from("kanata.kbd");
+    if default.is_file() {
+        cfgs.push(default);
+    }
+
+    if let Some(config_dir) = dirs::config_dir() {
+        let fallback = config_dir.join("kanata").join("kanata.kbd");
+        if fallback.is_file() {
+            cfgs.push(fallback);
+        }
+    }
+
+    cfgs
+}
+
+#[derive(Debug, Clone)]
+pub struct SocketAddrWrapper(SocketAddr);
+
+impl FromStr for SocketAddrWrapper {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mut address = s.to_string();
+        if let Ok(port) = s.parse::<u16>() {
+            address = format!("127.0.0.1:{port}");
+        }
+        address
+            .parse::<SocketAddr>()
+            .map(SocketAddrWrapper)
+            .map_err(|e| anyhow!("Please specify either a port number, e.g. 8081 or an address, e.g. 127.0.0.1:8081.\n{e}"))
+    }
+}
+
+impl SocketAddrWrapper {
+    pub fn into_inner(self) -> SocketAddr {
+        self.0
+    }
+    pub fn get_ref(&self) -> &SocketAddr {
+        &self.0
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index 3bbb2c2de..40f2c6052 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,201 +1,265 @@
-use anyhow::{bail, Result};
-use log::info;
-use simplelog::*;
-use std::path::PathBuf;
-
-mod kanata;
-mod oskbd;
-mod tcp_server;
+#![cfg_attr(feature = "gui", windows_subsystem = "windows")]
+// disable default console for a Windows GUI app
+mod main_lib;
 
+#[cfg(not(feature = "gui"))]
+use anyhow::{Result, bail};
+#[cfg(not(feature = "gui"))]
 use clap::Parser;
-use kanata::Kanata;
-use tcp_server::TcpServer;
+#[cfg(not(feature = "gui"))]
+use kanata_parser::cfg;
+#[cfg(not(feature = "gui"))]
+use kanata_state_machine::*;
+#[cfg(not(feature = "gui"))]
+use main_lib::args::Args;
+#[cfg(not(feature = "gui"))]
+use simplelog::{format_description, *};
 
-type CfgPath = PathBuf;
+#[cfg(not(feature = "gui"))]
+mod cli {
+    use super::*;
 
-pub struct ValidatedArgs {
-    paths: Vec<CfgPath>,
-    port: Option<i32>,
-    #[cfg(target_os = "linux")]
-    symlink_path: Option<String>,
-    nodelay: bool,
-}
+    /// Parse CLI arguments and initialize logging.
+    fn cli_init() -> Result<(ValidatedArgs, Option<String>)> {
+        let args = Args::parse();
 
-fn default_cfg() -> Vec<PathBuf> {
-    let mut cfgs = Vec::new();
+        #[cfg(all(target_os = "macos", not(feature = "gui")))]
+        if args.list {
+            main_lib::list_devices_macos();
+            std::process::exit(0);
+        }
 
-    let default = PathBuf::from("kanata.kbd");
-    if default.is_file() {
-        cfgs.push(default);
-    }
+        #[cfg(all(any(target_os = "linux", target_os = "android"), not(feature = "gui")))]
+        if args.list {
+            main_lib::list_devices_linux();
+            std::process::exit(0);
+        }
 
-    if let Some(config_dir) = dirs::config_dir() {
-        let fallback = config_dir.join("kanata").join("kanata.kbd");
-        if fallback.is_file() {
-            cfgs.push(fallback);
+        #[cfg(all(target_os = "windows", feature = "interception_driver"))]
+        if args.list {
+            main_lib::list_devices_windows();
+            std::process::exit(0);
         }
-    }
 
-    cfgs
-}
+        let log_lvl = match (args.debug, args.trace, args.quiet) {
+            (_, true, false) => LevelFilter::Trace,
+            (true, false, false) => LevelFilter::Debug,
+            (false, false, false) => LevelFilter::Info,
+            (_, _, true) => LevelFilter::Error,
+        };
 
-#[derive(Parser, Debug)]
-#[command(author, version, verbatim_doc_comment)]
-/// kanata: an advanced software key remapper
-///
-/// kanata remaps key presses to other keys or complex actions depending on the
-/// configuration for that key. You can find the guide for creating a config
-/// file here:
-///
-///     https://github.com/jtroo/kanata/blob/main/docs/config.adoc
-///
-/// If you need help, please feel welcome to create an issue or discussion in
-/// the kanata repository:
-///
-///     https://github.com/jtroo/kanata
-struct Args {
-    // Display different platform specific paths based on the target OS
-    #[cfg_attr(
-        target_os = "windows",
-        doc = r"Configuration file(s) to use with kanata. If not specified, defaults to
-kanata.kbd in the current working directory and
-'C:\Users\user\AppData\Roaming\kanata\kanata.kbd'"
-    )]
-    #[cfg_attr(
-        target_os = "macos",
-        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
-kanata.kbd in the current working directory and
-'$HOME/Library/Application Support/kanata/kanata.kbd.'"
-    )]
-    #[cfg_attr(
-        not(any(target_os = "macos", target_os = "windows")),
-        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
-kanata.kbd in the current working directory and
-'$XDG_CONFIG_HOME/kanata/kanata.kbd'"
-    )]
-    #[arg(short, long, verbatim_doc_comment)]
-    cfg: Option<Vec<PathBuf>>,
-
-    /// Port to run the optional TCP server on. If blank, no TCP port will be
-    /// listened on.
-    #[arg(short, long, verbatim_doc_comment)]
-    port: Option<i32>,
-
-    /// Path for the symlink pointing to the newly-created device. If blank, no
-    /// symlink will be created.
-    #[cfg(target_os = "linux")]
-    #[arg(short, long, verbatim_doc_comment)]
-    symlink_path: Option<String>,
-
-    /// Enable debug logging.
-    #[arg(short, long)]
-    debug: bool,
-
-    /// Enable trace logging; implies --debug as well.
-    #[arg(short, long)]
-    trace: bool,
-
-    /// Remove the startup delay on kanata. In some cases, removing the delay may cause keyboard
-    /// issues on startup.
-    #[arg(short, long)]
-    nodelay: bool,
-}
+        let mut log_cfg = ConfigBuilder::new();
+        if let Err(e) = log_cfg.set_time_offset_to_local() {
+            eprintln!("WARNING: could not set log TZ to local: {e:?}");
+        };
+        log_cfg.set_time_format_custom(format_description!(
+            version = 2,
+            "[hour]:[minute]:[second].[subsecond digits:4]"
+        ));
+        CombinedLogger::init(vec![TermLogger::new(
+            log_lvl,
+            log_cfg.build(),
+            TerminalMode::Mixed,
+            ColorChoice::AlwaysAnsi,
+        )])
+        .expect("logger can init");
 
-/// Parse CLI arguments and initialize logging.
-fn cli_init() -> Result<ValidatedArgs> {
-    let args = Args::parse();
+        log::info!("kanata v{} starting", env!("CARGO_PKG_VERSION"));
+        #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+        log::info!("using LLHOOK+SendInput for keyboard IO");
+        #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+        log::info!("using the Interception driver for keyboard IO");
 
-    let cfg_paths = args.cfg.unwrap_or_else(default_cfg);
-
-    let log_lvl = match (args.debug, args.trace) {
-        (_, true) => LevelFilter::Trace,
-        (true, false) => LevelFilter::Debug,
-        (false, false) => LevelFilter::Info,
-    };
-
-    let mut log_cfg = ConfigBuilder::new();
-    if let Err(e) = log_cfg.set_time_offset_to_local() {
-        eprintln!("WARNING: could not set log TZ to local: {e:?}");
-    };
-    log_cfg.set_time_format_rfc3339();
-    CombinedLogger::init(vec![TermLogger::new(
-        log_lvl,
-        log_cfg.build(),
-        TerminalMode::Mixed,
-        ColorChoice::AlwaysAnsi,
-    )])
-    .expect("logger can init");
-    log::info!("kanata v{} starting", env!("CARGO_PKG_VERSION"));
-    #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
-    log::info!("using LLHOOK+SendInput for keyboard IO");
-    #[cfg(all(feature = "interception_driver", target_os = "windows"))]
-    log::info!("using the Interception driver for keyboard IO");
-
-    if let Some(config_file) = cfg_paths.first() {
-        if !config_file.exists() {
-            bail!(
-                "Could not find the config file ({})\nFor more info, pass the `-h` or `--help` flags.",
-                cfg_paths[0].to_str().unwrap_or("?")
-            )
+        #[cfg(target_os = "macos")]
+        if args.macos_request_permissions {
+            match oskbd::request_accessibility_permission() {
+                Ok(oskbd::AccessibilityPermissionStatus::Trusted) => {
+                    println!(
+                        "macOS reported this process as trusted, but kanata may still not appear as a separate item when launched from Terminal. Add {} manually if it is not listed.",
+                        macos_current_executable_hint()
+                    );
+                    std::process::exit(0);
+                }
+                Ok(oskbd::AccessibilityPermissionStatus::Requested) => {
+                    println!(
+                        "kanata has requested macOS Accessibility permission. Enable kanata in System Settings -> Privacy & Security -> Accessibility, then restart kanata."
+                    );
+                }
+                Err(e) => eprintln!("failed to request macOS Accessibility permission: {e}"),
+            }
+            std::process::exit(1);
         }
-    } else {
-        bail!("No config files provided\nFor more info, pass the `-h` or `--help` flags.");
-    }
 
-    Ok(ValidatedArgs {
-        paths: cfg_paths,
-        port: args.port,
-        #[cfg(target_os = "linux")]
-        symlink_path: args.symlink_path,
-        nodelay: args.nodelay,
-    })
-}
+        let config_string = if args.cfg_stdin {
+            use std::io::Read;
+            let mut buf = String::new();
+            std::io::stdin().read_to_string(&mut buf)?;
+            Some(buf)
+        } else {
+            None
+        };
 
-fn main_impl() -> Result<()> {
-    let args = cli_init()?;
-    let kanata_arc = Kanata::new_arc(&args)?;
+        let cfg_paths = if config_string.is_none() {
+            args.cfg.unwrap_or_else(default_cfg)
+        } else {
+            vec![]
+        };
 
-    if !args.nodelay {
-        info!("Sleeping for 2s. Please release all keys and don't press additional ones.");
-        std::thread::sleep(std::time::Duration::from_secs(2));
-    }
+        if config_string.is_none() {
+            if let Some(config_file) = cfg_paths.first() {
+                if !config_file.exists() {
+                    bail!(
+                        "Could not find the config file ({})\nFor more info, pass the `-h` or `--help` flags.",
+                        cfg_paths[0].to_str().unwrap_or("?")
+                    )
+                }
+            } else {
+                bail!("No config files provided\nFor more info, pass the `-h` or `--help` flags.");
+            }
+        }
+
+        if args.check {
+            log::info!("validating config only and exiting");
+            let status = if let Some(ref cfg_str) = config_string {
+                use rustc_hash::FxHashMap;
+                match cfg::new_from_str(cfg_str, FxHashMap::default()) {
+                    Ok(_) => 0,
+                    Err(e) => {
+                        log::error!("{e:?}");
+                        1
+                    }
+                }
+            } else {
+                match cfg::new_from_file(&cfg_paths[0]) {
+                    Ok(_) => 0,
+                    Err(e) => {
+                        log::error!("{e:?}");
+                        1
+                    }
+                }
+            };
+            std::process::exit(status);
+        }
+
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        if let Some(wait) = args.wait_device_ms {
+            use std::sync::atomic::Ordering;
+            log::info!("Setting device registration wait time to {wait} ms.");
+            oskbd::WAIT_DEVICE_MS.store(wait, Ordering::SeqCst);
+        }
+
+        if args.log_layer_changes {
+            cfg_forced::force_log_layer_changes(true);
+        }
+
+        // Set emergency exit code from CLI args
+        kanata::EMERGENCY_EXIT_CODE.store(
+            args.emergency_exit_code,
+            std::sync::atomic::Ordering::SeqCst,
+        );
 
-    // Start a processing loop in another thread and run the event loop in this thread.
-    //
-    // The reason for two different event loops is that the "event loop" only listens for keyboard
-    // events, which it sends to the "processing loop". The processing loop handles keyboard events
-    // while also maintaining `tick()` calls to keyberon.
-
-    let (server, ntx, nrx) = if let Some(port) = args.port {
-        let mut server = TcpServer::new(port);
-        server.start(kanata_arc.clone());
-        let (ntx, nrx) = std::sync::mpsc::channel();
-        (Some(server), Some(ntx), Some(nrx))
-    } else {
-        (None, None, None)
-    };
-
-    let (tx, rx) = std::sync::mpsc::channel();
-    Kanata::start_processing_loop(kanata_arc.clone(), rx, ntx, args.nodelay);
-
-    if let (Some(server), Some(nrx)) = (server, nrx) {
-        Kanata::start_notification_loop(nrx, server.connections);
+        #[cfg(target_os = "macos")]
+        oskbd::set_release_grab_on_lock(args.release_grab_on_lock);
+
+        Ok((
+            ValidatedArgs {
+                paths: cfg_paths,
+                #[cfg(feature = "tcp_server")]
+                tcp_server_address: args.tcp_server_address,
+                #[cfg(any(target_os = "linux", target_os = "android"))]
+                symlink_path: args.symlink_path,
+                nodelay: args.nodelay,
+            },
+            config_string,
+        ))
     }
 
-    #[cfg(target_os = "linux")]
-    sd_notify::notify(true, &[sd_notify::NotifyState::Ready])?;
+    pub(crate) fn main_impl() -> Result<()> {
+        let (args, config_string) = cli_init()?;
+
+        let kanata_arc = if let Some(cfg_str) = config_string {
+            use rustc_hash::FxHashMap;
+            let kanata = Kanata::new_from_str(&cfg_str, FxHashMap::default())?;
+            std::sync::Arc::new(parking_lot::Mutex::new(kanata))
+        } else {
+            Kanata::new_arc(&args)?
+        };
+
+        if !args.nodelay {
+            log::info!(
+                "Sleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep."
+            );
+            std::thread::sleep(std::time::Duration::from_secs(2));
+        }
+
+        // Start a processing loop in another thread and run the event loop in this thread.
+        //
+        // The reason for two different event loops is that the "event loop" only listens for
+        // keyboard events, which it sends to the "processing loop". The processing loop handles
+        // keyboard events while also maintaining `tick()` calls to keyberon.
+
+        let (tx, rx) = std::sync::mpsc::sync_channel(100);
+
+        let (server, ntx, nrx) = if let Some(address) = {
+            #[cfg(feature = "tcp_server")]
+            {
+                args.tcp_server_address
+            }
+            #[cfg(not(feature = "tcp_server"))]
+            {
+                None::<SocketAddrWrapper>
+            }
+        } {
+            let mut server = TcpServer::new(address.into_inner(), tx.clone());
+            server.start(kanata_arc.clone());
+            let (ntx, nrx) = std::sync::mpsc::sync_channel(100);
+            (Some(server), Some(ntx), Some(nrx))
+        } else {
+            (None, None, None)
+        };
+
+        Kanata::start_processing_loop(kanata_arc.clone(), rx, ntx, args.nodelay);
+
+        if let (Some(server), Some(nrx)) = (server, nrx) {
+            #[allow(clippy::unit_arg)]
+            Kanata::start_notification_loop(nrx, server.connections);
+        }
 
-    Kanata::event_loop(kanata_arc, tx)?;
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        sd_notify::notify(true, &[sd_notify::NotifyState::Ready])?;
 
-    Ok(())
+        Kanata::event_loop(kanata_arc, tx)
+    }
+
+    #[cfg(target_os = "macos")]
+    fn macos_current_executable_hint() -> String {
+        std::env::current_exe()
+            .map(|path| path.display().to_string())
+            .unwrap_or_else(|_| "kanata".to_string())
+    }
 }
 
-fn main() -> Result<()> {
-    let ret = main_impl();
+#[cfg(not(feature = "gui"))]
+pub fn main() -> Result<()> {
+    let args = Args::parse();
+    let no_wait = args.no_wait;
+    let ret = cli::main_impl();
     if let Err(ref e) = ret {
         log::error!("{e}\n");
     }
-    eprintln!("\nPress enter to exit");
-    let _ = std::io::stdin().read_line(&mut String::new());
+    if !no_wait {
+        eprintln!("\nPress enter to exit");
+        let _ = std::io::stdin().read_line(&mut String::new());
+    }
     ret
 }
+
+#[cfg(all(feature = "gui", target_os = "windows"))]
+fn main() {
+    main_lib::win_gui::lib_main_gui();
+}
+
+#[cfg(all(feature = "gui", not(target_os = "windows")))]
+fn main() {
+    panic!("GUI feature is only supported on Windows");
+}
diff --git a/src/main_lib/args.rs b/src/main_lib/args.rs
new file mode 100644
index 000000000..b0b9fb231
--- /dev/null
+++ b/src/main_lib/args.rs
@@ -0,0 +1,213 @@
+use clap::Parser;
+#[cfg(feature = "tcp_server")]
+use kanata_state_machine::SocketAddrWrapper;
+use std::path::PathBuf;
+
+#[derive(Parser, Debug)]
+#[command(author, version, verbatim_doc_comment)]
+/// kanata: an advanced software key remapper
+///
+/// kanata remaps key presses to other keys or complex actions depending on the
+/// configuration for that key. You can find the guide for creating a config
+/// file here: https://github.com/jtroo/kanata/blob/main/docs/config.adoc
+///
+/// If you need help, please feel welcome to create an issue or discussion in
+/// the kanata repository: https://github.com/jtroo/kanata
+pub struct Args {
+    // Display different platform specific paths based on the target OS
+    #[cfg_attr(
+        target_os = "windows",
+        doc = r"Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'C:\Users\user\AppData\Roaming\kanata\kanata.kbd'."
+    )]
+    #[cfg_attr(
+        target_os = "macos",
+        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'$HOME/Library/Application Support/kanata/kanata.kbd'."
+    )]
+    #[cfg_attr(
+        not(any(target_os = "macos", target_os = "windows")),
+        doc = "Configuration file(s) to use with kanata. If not specified, defaults to
+kanata.kbd in the current working directory and
+'$XDG_CONFIG_HOME/kanata/kanata.kbd'."
+    )]
+    #[arg(short, long, verbatim_doc_comment)]
+    pub cfg: Option<Vec<PathBuf>>,
+
+    /// Read configuration from stdin instead of a file.
+    #[arg(long, verbatim_doc_comment)]
+    pub cfg_stdin: bool,
+
+    /// Port or full address (IP:PORT) to run the optional TCP server on. If blank,
+    /// no TCP port will be listened on.
+    #[cfg(feature = "tcp_server")]
+    #[arg(
+        short = 'p',
+        long = "port",
+        value_name = "PORT or IP:PORT",
+        verbatim_doc_comment
+    )]
+    pub tcp_server_address: Option<SocketAddrWrapper>,
+
+    /// Path for the symlink pointing to the newly-created device. If blank, no
+    /// symlink will be created.
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    #[arg(short, long, verbatim_doc_comment)]
+    pub symlink_path: Option<String>,
+
+    /// List the keyboards available for grabbing and exit.
+    #[cfg(any(
+        target_os = "macos",
+        any(target_os = "linux", target_os = "android"),
+        all(target_os = "windows", feature = "interception_driver")
+    ))]
+    #[arg(short, long)]
+    pub list: bool,
+
+    /// Disable logging, except for errors. Takes precedent over debug and trace.
+    #[arg(short, long)]
+    pub quiet: bool,
+
+    /// Enable debug logging.
+    #[arg(short, long)]
+    pub debug: bool,
+
+    /// Enable trace logging; implies --debug as well.
+    #[arg(short, long)]
+    pub trace: bool,
+
+    /// Remove the startup delay.
+    /// In some cases, removing the delay may cause keyboard issues on startup.
+    #[arg(short, long, verbatim_doc_comment)]
+    pub nodelay: bool,
+
+    /// Milliseconds to wait before attempting to register a newly connected
+    /// device. The default is 200.
+    ///
+    /// You may wish to increase this if you have a device that is failing
+    /// to register - the device may be taking too long to become ready.
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    #[arg(short, long, verbatim_doc_comment)]
+    pub wait_device_ms: Option<u64>,
+
+    /// Validate configuration file and exit
+    #[arg(long, verbatim_doc_comment)]
+    pub check: bool,
+
+    /// Log layer changes even if the configuration file has set the defcfg
+    /// option to false. Useful if you are experimenting with a new
+    /// configuration but want to default to no logging.
+    #[arg(long, verbatim_doc_comment)]
+    pub log_layer_changes: bool,
+
+    /// Skip the "Press enter to exit" prompt and exit immediately.
+    /// Useful for running kanata as a background service (e.g., systemd)
+    /// where automatic restart on failure is desired.
+    #[arg(long, verbatim_doc_comment)]
+    pub no_wait: bool,
+
+    /// Exit code to use when emergency exit is triggered (LCtrl+Space+Escape).
+    /// Default is 0 (success). Set to non-zero if your service manager should
+    /// treat emergency exit as a failure and restart.
+    #[arg(long, default_value = "0", verbatim_doc_comment)]
+    pub emergency_exit_code: i32,
+
+    /// Release the keyboard grab while the screen is locked or another user
+    /// holds the console (fast user switching), and re-grab once kanata's
+    /// session is back. Useful on shared Macs so the lock screen and other
+    /// users get an unmodified keyboard. Off by default to preserve the
+    /// historical always-grab behavior.
+    #[cfg(target_os = "macos")]
+    #[arg(long, verbatim_doc_comment)]
+    pub release_grab_on_lock: bool,
+
+    /// Request/register macOS Accessibility permission and exit.
+    /// This does not read a config file, open keyboard devices, or start remapping.
+    #[cfg(target_os = "macos")]
+    #[arg(long, verbatim_doc_comment)]
+    pub macos_request_permissions: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn no_wait_flag_default_false() {
+        let args = Args::try_parse_from(["kanata"]).unwrap();
+        assert!(!args.no_wait);
+    }
+
+    #[test]
+    fn no_wait_flag_enabled() {
+        let args = Args::try_parse_from(["kanata", "--no-wait"]).unwrap();
+        assert!(args.no_wait);
+    }
+
+    #[test]
+    fn no_wait_with_other_flags() {
+        let args =
+            Args::try_parse_from(["kanata", "--no-wait", "--nodelay", "-c", "test.kbd"]).unwrap();
+        assert!(args.no_wait);
+        assert!(args.nodelay);
+    }
+
+    #[test]
+    fn emergency_exit_code_default() {
+        let args = Args::try_parse_from(["kanata"]).unwrap();
+        assert_eq!(args.emergency_exit_code, 0);
+    }
+
+    #[test]
+    fn emergency_exit_code_custom() {
+        let args = Args::try_parse_from(["kanata", "--emergency-exit-code", "42"]).unwrap();
+        assert_eq!(args.emergency_exit_code, 42);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn release_grab_on_lock_default_false() {
+        let args = Args::try_parse_from(["kanata"]).unwrap();
+        assert!(!args.release_grab_on_lock);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn release_grab_on_lock_enabled() {
+        let args = Args::try_parse_from(["kanata", "--release-grab-on-lock"]).unwrap();
+        assert!(args.release_grab_on_lock);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn macos_request_permissions_enabled() {
+        let args = Args::try_parse_from(["kanata", "--macos-request-permissions"]).unwrap();
+        assert!(args.macos_request_permissions);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn help_mentions_macos_request_permissions() {
+        use clap::CommandFactory;
+
+        let help = Args::command().render_long_help().to_string();
+        assert!(help.contains("--macos-request-permissions"));
+    }
+
+    #[test]
+    fn emergency_exit_code_with_other_flags() {
+        let args = Args::try_parse_from([
+            "kanata",
+            "--emergency-exit-code",
+            "1",
+            "--no-wait",
+            "-c",
+            "test.kbd",
+        ])
+        .unwrap();
+        assert_eq!(args.emergency_exit_code, 1);
+        assert!(args.no_wait);
+    }
+}
diff --git a/src/main_lib/mod.rs b/src/main_lib/mod.rs
new file mode 100644
index 000000000..36c860b2e
--- /dev/null
+++ b/src/main_lib/mod.rs
@@ -0,0 +1,307 @@
+pub(crate) mod args;
+
+#[cfg(all(target_os = "windows", feature = "gui"))]
+pub(crate) mod win_gui;
+
+#[cfg(all(target_os = "macos", not(feature = "gui")))]
+pub(crate) fn list_devices_macos() {
+    use karabiner_driverkit::fetch_devices;
+
+    println!("Available keyboard devices:");
+    println!("===========================\n");
+
+    let kb_list = fetch_devices();
+
+    let print_header = || {
+        println!(
+            "{:<20} {:<10} {:<10} product_key",
+            "hash", "vendor_id", "product_id"
+        );
+    };
+
+    let print_line = || {
+        println!(
+            "{}   {}   {}   {}",
+            "-".repeat(18),
+            "-".repeat(8),
+            "-".repeat(8),
+            "-".repeat(50)
+        );
+    };
+
+    print_header();
+    print_line();
+    for kb in kb_list.iter() {
+        println!("{}", kb);
+    }
+    print_line();
+
+    if kb_list.is_empty() {
+        println!("No devices found. Ensure Karabiner-VirtualHIDDevice driver is activated.");
+        return;
+    }
+
+    let has_empty_names = kb_list.iter().any(|k| k.product_key.trim().is_empty());
+    if has_empty_names {
+        println!(
+            "\nTo address devices with empty names (product key), hash values can be used in the configuration!"
+        );
+    }
+
+    if kb_list.iter().any(|k| k.product_key.contains("Karabiner")) {
+        println!(
+            "\nNote: Karabiner virtual devices detected. Device hashes may not be stable \
+             because Karabiner virtualizes HID devices. Prefer name-based matching."
+        );
+    }
+
+    println!("\nConfiguration example:");
+    println!("  (defcfg");
+    println!("    macos-dev-names-include (");
+    for kb in kb_list
+        .iter()
+        .map(|k| k.product_key.clone())
+        .filter(|k| !k.trim().is_empty())
+    {
+        println!("      \"{}\"", kb.trim());
+    }
+    println!("    )");
+    println!("    or instead:");
+    println!("    macos-dev-names-include (");
+    for kb in kb_list.iter().map(|k| k.hash) {
+        println!("      \"0x{:<16X}\"", kb);
+    }
+    println!("    )");
+    println!("  )");
+}
+
+#[cfg(all(any(target_os = "linux", target_os = "android"), not(feature = "gui")))]
+pub(crate) fn list_devices_linux() {
+    use crate::oskbd::discover_devices;
+    use kanata_parser::cfg::DeviceDetectMode;
+
+    println!("Available keyboard devices:");
+    println!("===========================");
+
+    let devices = discover_devices(None, None, DeviceDetectMode::KeyboardOnly);
+
+    if devices.is_empty() {
+        println!("No keyboard devices found.");
+        println!("\nTroubleshooting:");
+        println!("  1. Check permissions: sudo usermod -a -G input $USER");
+        println!("  2. Log out and back in for group changes to take effect");
+        println!("  3. Ensure devices are connected and working");
+        return;
+    }
+
+    println!("Found {} keyboard device(s):\n", devices.len());
+
+    for (i, (device, path)) in devices.iter().enumerate() {
+        let name = device.name().unwrap_or("Unknown");
+        let input_id = device.input_id();
+        println!("  {}. \"{}\"", i + 1, name);
+        println!("     Path: {path}");
+        println!(
+            "     Vendor ID: {} (0x{:04X}), Product ID: {} (0x{:04X})",
+            input_id.vendor(),
+            input_id.vendor(),
+            input_id.product(),
+            input_id.product()
+        );
+        println!();
+    }
+
+    println!("Configuration example:");
+    println!("  (defcfg");
+    println!("    linux-dev-names-include (");
+    for (device, _path) in devices.iter() {
+        println!("      \"{}\"", device.name().unwrap_or("Unknown"));
+    }
+    println!("    )");
+    println!("  )");
+}
+
+#[cfg(all(target_os = "windows", feature = "interception_driver"))]
+struct WindowsDeviceInfo {
+    display_name: String,        // For user display
+    raw_wide_bytes: Vec<u8>,     // For kanata configuration (original wide string bytes)
+    hardware_id: Option<String>, // Parsed hardware ID (e.g., "HID#VID_046D&PID_C52B")
+}
+
+#[cfg(all(target_os = "windows", feature = "interception_driver"))]
+fn get_device_info(device_handle: winapi::um::winnt::HANDLE) -> Option<WindowsDeviceInfo> {
+    use std::ffi::OsString;
+    use std::os::windows::ffi::OsStringExt;
+    use std::ptr::null_mut;
+    use winapi::shared::minwindef::{PUINT, UINT};
+    use winapi::um::winuser::{GetRawInputDeviceInfoW, RIDI_DEVICENAME};
+
+    unsafe {
+        let mut name_size: UINT = 0;
+
+        // First call to get the required buffer size (in characters, not bytes)
+        GetRawInputDeviceInfoW(
+            device_handle,
+            RIDI_DEVICENAME,
+            null_mut(),
+            &mut name_size as PUINT,
+        );
+
+        if name_size > 0 {
+            // Allocate buffer for wide characters
+            let mut name_buffer: Vec<u16> = vec![0; name_size as usize];
+            let result = GetRawInputDeviceInfoW(
+                device_handle,
+                RIDI_DEVICENAME,
+                name_buffer.as_mut_ptr() as *mut _,
+                &mut name_size as PUINT,
+            );
+
+            if result != u32::MAX {
+                // Truncate buffer to actual data length (result is in bytes, divide by 2 for chars)
+                let actual_char_count = (result / 2) as usize;
+                name_buffer.truncate(actual_char_count);
+
+                // Remove null terminator if present
+                if let Some(&0) = name_buffer.last() {
+                    name_buffer.pop();
+                }
+
+                // Convert to raw bytes (preserve original wide string format)
+                let raw_wide_bytes: Vec<u8> =
+                    name_buffer.iter().flat_map(|&c| c.to_le_bytes()).collect();
+
+                // Create display name using OsString (preserves invalid UTF-16)
+                let os_string = OsString::from_wide(&name_buffer);
+                let display_name = os_string.to_string_lossy().into_owned();
+
+                // Extract hardware ID from display name
+                let hardware_id = extract_hardware_id(&display_name);
+
+                return Some(WindowsDeviceInfo {
+                    display_name,
+                    raw_wide_bytes,
+                    hardware_id,
+                });
+            }
+        }
+    }
+    None
+}
+
+#[cfg(all(target_os = "windows", feature = "interception_driver"))]
+pub(crate) fn list_devices_windows() {
+    use std::ptr::null_mut;
+    use winapi::shared::minwindef::{PUINT, UINT};
+    use winapi::um::winuser::{GetRawInputDeviceList, RAWINPUTDEVICELIST, RIM_TYPEKEYBOARD};
+
+    println!("Available keyboard devices:");
+    println!("===========================");
+
+    unsafe {
+        // First, get the number of devices
+        let mut num_devices: UINT = 0;
+        let result = GetRawInputDeviceList(
+            null_mut(),
+            &mut num_devices as PUINT,
+            std::mem::size_of::<RAWINPUTDEVICELIST>() as UINT,
+        );
+
+        if result == u32::MAX {
+            println!("Error: Failed to get device count");
+            return;
+        }
+
+        if num_devices == 0 {
+            println!("No input devices found.");
+            return;
+        }
+
+        // Allocate buffer for device list
+        let mut devices: Vec<RAWINPUTDEVICELIST> = vec![std::mem::zeroed(); num_devices as usize];
+
+        let result = GetRawInputDeviceList(
+            devices.as_mut_ptr(),
+            &mut num_devices as PUINT,
+            std::mem::size_of::<RAWINPUTDEVICELIST>() as UINT,
+        );
+
+        if result == u32::MAX {
+            println!("Error: Failed to get device list");
+            return;
+        }
+
+        // Filter for keyboards and get device info
+        let keyboards: Vec<&RAWINPUTDEVICELIST> = devices
+            .iter()
+            .filter(|device| device.dwType == RIM_TYPEKEYBOARD)
+            .collect();
+
+        if keyboards.is_empty() {
+            println!("No keyboard devices found.");
+            println!("\nTroubleshooting:");
+            println!("  1. Ensure keyboards are connected and working");
+            println!("  2. Try running as administrator if needed");
+            return;
+        }
+
+        println!("Found {} keyboard device(s):\n", keyboards.len());
+
+        for (i, device) in keyboards.iter().enumerate() {
+            if let Some(device_info) = get_device_info(device.hDevice) {
+                println!("  {}. Device: {}", i + 1, device_info.display_name);
+
+                // Show hardware ID if available
+                if let Some(hwid) = &device_info.hardware_id {
+                    println!("     Hardware ID: {hwid}");
+                }
+
+                // Show raw wide string bytes for kanata configuration
+                println!(
+                    "     Raw wide string bytes: {:?}",
+                    device_info.raw_wide_bytes
+                );
+                println!();
+            }
+        }
+
+        if !keyboards.is_empty() {
+            println!("Configuration example:");
+            println!("  (defcfg");
+            println!("    windows-interception-keyboard-hwids (");
+
+            for device in keyboards.iter() {
+                if let Some(device_info) = get_device_info(device.hDevice) {
+                    // Use the preserved raw wide string bytes for configuration
+                    print!("      {:?}", device_info.raw_wide_bytes);
+
+                    // Add comment with hardware ID and display name for clarity
+                    if let Some(hwid) = &device_info.hardware_id {
+                        println!("  ; {} ({})", hwid, device_info.display_name);
+                    } else {
+                        println!("  ; {}", device_info.display_name);
+                    }
+                }
+            }
+
+            println!("    )");
+            println!("  )");
+        }
+    }
+}
+
+#[cfg(all(target_os = "windows", feature = "interception_driver"))]
+fn extract_hardware_id(device_name: &str) -> Option<String> {
+    // Windows device names typically look like:
+    // \\?\HID#VID_046D&PID_C52B&MI_01#7&1234abcd&0&0000#{884b96c3-56ef-11d1-bc8c-00a0c91405dd}
+    // We want to extract the HID#VID_046D&PID_C52B&MI_01 part
+
+    if let Some(start) = device_name.find("HID#")
+        && let Some(end) = device_name[start..].find('#')
+    {
+        let hwid_part = &device_name[start..start + end];
+        return Some(hwid_part.to_string());
+    }
+
+    None
+}
diff --git a/src/main_lib/win_gui.rs b/src/main_lib/win_gui.rs
new file mode 100644
index 000000000..6ee973fd7
--- /dev/null
+++ b/src/main_lib/win_gui.rs
@@ -0,0 +1,229 @@
+use super::args::Args;
+use anyhow::{Context, Result, anyhow, bail};
+use clap::{CommandFactory, Parser, error::ErrorKind};
+use kanata_parser::cfg;
+use kanata_state_machine::gui::*;
+use kanata_state_machine::*;
+use simplelog::{
+    ColorChoice, CombinedLogger, Config, ConfigBuilder, LevelFilter, TermLogger, TerminalMode,
+    WriteLogger, format_description,
+};
+use std::fs::File;
+
+/// Parse CLI arguments and initialize logging.
+fn cli_init() -> Result<ValidatedArgs> {
+    let noti_lvl = LevelFilter::Error; // min lvl above which to use Win system notifications
+    let log_file_p = "kanata_log.txt";
+    let args = match Args::try_parse() {
+        Ok(args) => args,
+        Err(e) => {
+            if *IS_TERM {
+                // init loggers without config so '-help' "error" or real ones can be printed
+                let mut log_cfg = ConfigBuilder::new();
+                CombinedLogger::init(vec![
+                    TermLogger::new(
+                        LevelFilter::Debug,
+                        log_cfg.build(),
+                        TerminalMode::Mixed,
+                        ColorChoice::AlwaysAnsi,
+                    ),
+                    log_win::windbg_simple_combo(LevelFilter::Debug, noti_lvl),
+                ])
+                .expect("logger can init");
+            } else {
+                CombinedLogger::init(vec![
+                    log_win::windbg_simple_combo(LevelFilter::Debug, noti_lvl),
+                    WriteLogger::new(
+                        LevelFilter::Debug,
+                        Config::default(),
+                        File::create(log_file_p).unwrap(),
+                    ),
+                ])
+                .expect("logger can init");
+            }
+            match e.kind() {
+                ErrorKind::DisplayHelp => {
+                    let mut cmd = Args::command();
+                    let help = cmd.render_help();
+                    info!("{help}");
+                    log::set_max_level(LevelFilter::Off);
+                    if !*IS_TERM {
+                        // detached to open log still opened for writing
+                        match open::that_detached(log_file_p) {
+                            Ok(()) => {} // on the off-chance the user looks at WinDbg logs
+                            Err(ef) => error!("failed to open {log_file_p} due to {ef:?}"),
+                        }
+                    }
+                    return Err(anyhow!(""));
+                }
+                _ => {
+                    if !*IS_TERM {
+                        match open::that_detached(log_file_p) {
+                            Ok(()) => {}
+                            Err(ef) => error!("failed to open {log_file_p} due to {ef:?}"),
+                        }
+                    }
+                    return Err(e.into());
+                }
+            }
+        }
+    };
+
+    #[cfg(feature = "interception_driver")]
+    {
+        if args.list {
+            super::list_devices_windows();
+            std::process::exit(0);
+        }
+    }
+
+    let cfg_paths = args.cfg.unwrap_or_else(default_cfg);
+
+    let log_lvl = match (args.debug, args.trace) {
+        (_, true) => LevelFilter::Trace,
+        (true, false) => LevelFilter::Debug,
+        (false, false) => LevelFilter::Info,
+    };
+
+    let mut log_cfg = ConfigBuilder::new();
+    if let Err(e) = log_cfg.set_time_offset_to_local() {
+        eprintln!("WARNING: could not set log TZ to local: {e:?}");
+    };
+    log_cfg.set_time_format_custom(format_description!(
+        version = 2,
+        "[hour]:[minute]:[second].[subsecond digits:4]"
+    ));
+    if *IS_TERM {
+        CombinedLogger::init(vec![
+            TermLogger::new(
+                log_lvl,
+                log_cfg.build(),
+                TerminalMode::Mixed,
+                ColorChoice::AlwaysAnsi,
+            ),
+            log_win::windbg_simple_combo(log_lvl, noti_lvl),
+        ])
+        .expect("logger can init");
+    } else {
+        CombinedLogger::init(vec![log_win::windbg_simple_combo(log_lvl, noti_lvl)])
+            .expect("logger can init");
+    }
+    log::info!("kanata v{} starting", env!("CARGO_PKG_VERSION"));
+    #[cfg(all(not(feature = "interception_driver"), target_os = "windows"))]
+    log::info!("using LLHOOK+SendInput for keyboard IO");
+    #[cfg(all(feature = "interception_driver", target_os = "windows"))]
+    log::info!("using the Interception driver for keyboard IO");
+
+    if let Some(config_file) = cfg_paths.first() {
+        if !config_file.exists() {
+            bail!(
+                "Could not find the config file ({})\nFor more info, pass the `-h` or `--help` flags.",
+                cfg_paths[0].to_str().unwrap_or("?")
+            )
+        }
+    } else {
+        bail!("No config files provided\nFor more info, pass the `-h` or `--help` flags.");
+    }
+
+    if args.check {
+        log::info!("validating config only and exiting");
+        let status = match cfg::new_from_file(&cfg_paths[0]) {
+            Ok(_) => 0,
+            Err(e) => {
+                log::error!("{e:?}");
+                1
+            }
+        };
+        std::process::exit(status);
+    }
+
+    Ok(ValidatedArgs {
+        paths: cfg_paths,
+        #[cfg(feature = "tcp_server")]
+        tcp_server_address: args.tcp_server_address,
+        nodelay: args.nodelay,
+    })
+}
+
+fn main_impl() -> Result<()> {
+    let args = cli_init()?;
+    let kanata_arc = Kanata::new_arc(&args)?;
+
+    if CFG.set(kanata_arc.clone()).is_err() {
+        warn!("Someone else set our ‘CFG’");
+    }; // store a clone of cfg so that we can ask it to reset itself
+
+    if !args.nodelay {
+        info!(
+            "Sleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep."
+        );
+        std::thread::sleep(std::time::Duration::from_secs(2));
+    }
+
+    // Start a processing loop in another thread and run the event loop in this thread.
+    //
+    // The reason for two different event loops is that the "event loop" only listens for keyboard
+    // events, which it sends to the "processing loop". The processing loop handles keyboard events
+    // while also maintaining `tick()` calls to keyberon.
+
+    let (tx, rx) = std::sync::mpsc::sync_channel(100);
+
+    let (server, ntx, nrx) = if let Some(address) = {
+        #[cfg(feature = "tcp_server")]
+        {
+            args.tcp_server_address
+        }
+        #[cfg(not(feature = "tcp_server"))]
+        {
+            None::<SocketAddrWrapper>
+        }
+    } {
+        let mut server = TcpServer::new(address.into_inner(), tx.clone());
+        server.start(kanata_arc.clone());
+        let (ntx, nrx) = std::sync::mpsc::sync_channel(100);
+        (Some(server), Some(ntx), Some(nrx))
+    } else {
+        (None, None, None)
+    };
+
+    native_windows_gui::init().context("Failed to init Native Windows GUI")?;
+    let ui = build_tray(&kanata_arc)?;
+    let gui_tx = ui.layer_notice.sender();
+    let gui_cfg_tx = ui.cfg_notice.sender(); // allows notifying GUI on config reloads
+    let gui_err_tx = ui.err_notice.sender(); // allows notifying GUI on erorrs (from logger)
+    let gui_exit_tx = ui.exit_notice.sender(); // allows notifying GUI on app quit
+    if GUI_TX.set(gui_tx).is_err() {
+        warn!("Someone else set our ‘GUI_TX’");
+    };
+    if GUI_CFG_TX.set(gui_cfg_tx).is_err() {
+        warn!("Someone else set our ‘GUI_CFG_TX’");
+    };
+    if GUI_ERR_TX.set(gui_err_tx).is_err() {
+        warn!("Someone else set our ‘GUI_ERR_TX’");
+    };
+    if GUI_EXIT_TX.set(gui_exit_tx).is_err() {
+        warn!("Someone else set our ‘GUI_EXIT_TX’");
+    };
+    Kanata::start_processing_loop(kanata_arc.clone(), rx, ntx, args.nodelay);
+
+    if let (Some(server), Some(nrx)) = (server, nrx) {
+        #[allow(clippy::unit_arg)]
+        Kanata::start_notification_loop(nrx, server.connections);
+    }
+
+    Kanata::event_loop(kanata_arc, tx, ui)?;
+
+    Ok(())
+}
+
+pub fn lib_main_gui() {
+    let _attach_console = *IS_CONSOLE;
+    let ret = main_impl();
+    if let Err(ref e) = ret {
+        log::error!("{e}\n");
+    }
+
+    unsafe {
+        FreeConsole();
+    }
+}
diff --git a/src/oskbd/linux.rs b/src/oskbd/linux.rs
index 371f79160..4f147a222 100644
--- a/src/oskbd/linux.rs
+++ b/src/oskbd/linux.rs
@@ -1,23 +1,31 @@
 //! Contains the input/output code for keyboards on Linux.
 
-use evdev::{uinput, Device, EventType, InputEvent, RelativeAxisType};
+#![cfg_attr(feature = "simulated_output", allow(dead_code, unused_imports))]
+
+pub use evdev::BusType;
+use evdev::{Device, EventType, InputEvent, KeyCode, PropType, RelativeAxisCode, uinput};
 use inotify::{Inotify, WatchMask};
-use mio::{unix::SourceFd, Events, Interest, Poll, Token};
+use mio::{Events, Interest, Poll, Token, unix::SourceFd};
 use nix::ioctl_read_buf;
 use rustc_hash::FxHashMap as HashMap;
 use signal_hook::{
-    consts::{SIGINT, SIGTERM},
+    consts::{SIGINT, SIGTERM, SIGTSTP},
     iterator::Signals,
 };
 
+use std::convert::TryFrom;
 use std::fs;
 use std::io;
 use std::os::unix::io::AsRawFd;
 use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::thread;
 
+use super::*;
+use crate::{kanata::CalculatedMouseMove, oskbd::KeyEvent};
+use kanata_parser::cfg::DeviceDetectMode;
+use kanata_parser::cfg::UnicodeTermination;
 use kanata_parser::custom_action::*;
-use kanata_parser::keys::KeyEvent;
 use kanata_parser::keys::*;
 
 pub struct KbdIn {
@@ -31,17 +39,21 @@ pub struct KbdIn {
     _inotify: Inotify,
     include_names: Option<Vec<String>>,
     exclude_names: Option<Vec<String>>,
+    device_detect_mode: DeviceDetectMode,
 }
 
 const INOTIFY_TOKEN_VALUE: usize = 0;
 const INOTIFY_TOKEN: Token = Token(INOTIFY_TOKEN_VALUE);
 
+pub static WAIT_DEVICE_MS: AtomicU64 = AtomicU64::new(200);
+
 impl KbdIn {
     pub fn new(
         dev_paths: &[String],
         continue_if_no_devices: bool,
         include_names: Option<Vec<String>>,
         exclude_names: Option<Vec<String>>,
+        device_detect_mode: DeviceDetectMode,
     ) -> Result<Self, io::Error> {
         let poll = Poll::new()?;
 
@@ -53,7 +65,11 @@ impl KbdIn {
                 missing_device_paths.as_mut().expect("initialized"),
             )
         } else {
-            discover_devices(include_names.as_deref(), exclude_names.as_deref())
+            discover_devices(
+                include_names.as_deref(),
+                exclude_names.as_deref(),
+                device_detect_mode,
+            )
         };
         if devices.is_empty() {
             if continue_if_no_devices {
@@ -61,7 +77,11 @@ impl KbdIn {
             } else {
                 return Err(io::Error::new(
                     io::ErrorKind::NotFound,
-                    "No keyboard devices were found",
+                    "No keyboard devices were found. Try:\n\
+                     1. Run 'kanata --list' to see available devices\n\
+                     2. Check permissions: sudo usermod -a -G input $USER\n\
+                     3. Log out and back in for group changes to take effect\n\
+                     4. Ensure devices are connected and working",
                 ));
             }
         }
@@ -84,6 +104,7 @@ impl KbdIn {
             token_counter: INOTIFY_TOKEN_VALUE + 1,
             include_names,
             exclude_names,
+            device_detect_mode,
         };
 
         for (device, dev_path) in devices.into_iter() {
@@ -127,15 +148,18 @@ impl KbdIn {
                 return Ok(vec![]);
             }
 
+            const EVENT_LIMIT: usize = 48;
+
             let mut do_rediscover = false;
             for event in &self.events {
                 if let Some((device, _)) = self.devices.get_mut(&event.token()) {
-                    if let Err(e) = device
-                        .fetch_events()
-                        .map(|evs| evs.into_iter().for_each(|ev| input_events.push(ev)))
-                    {
+                    if let Err(e) = device.fetch_events().map(|evs| {
+                        evs.into_iter()
+                            .take(EVENT_LIMIT)
+                            .for_each(|ev| input_events.push(ev))
+                    }) {
                         // Currently the kind() is uncategorized... not helpful, need to match
-                        // on os error (19)
+                        // on os error. code 19 is ENODEV, "no such device".
                         match e.raw_os_error() {
                             Some(19) => {
                                 self.poll
@@ -182,7 +206,7 @@ impl KbdIn {
             let discovered_devices = missing
                 .iter()
                 .filter_map(|dev_path| {
-                    for _ in 0..10 {
+                    for _ in 0..(WAIT_DEVICE_MS.load(Ordering::SeqCst) / 10) {
                         // try a few times with waits in between; device might not be ready
                         if let Ok(device) = Device::open(dev_path) {
                             return Some((device, dev_path.clone()));
@@ -204,110 +228,192 @@ impl KbdIn {
             missing.retain(|path| !paths_registered.contains(path));
         } else {
             log::info!("sleeping for a moment to let devices become ready");
-            std::thread::sleep(std::time::Duration::from_millis(200));
-            discover_devices(self.include_names.as_deref(), self.exclude_names.as_deref())
-                .into_iter()
-                .try_for_each(|(dev, path)| {
-                    if !self
-                        .devices
-                        .values()
-                        .any(|(_, registered_path)| &path == registered_path)
-                    {
-                        self.register_device(dev, path)
-                    } else {
-                        Ok(())
-                    }
-                })?;
+            std::thread::sleep(std::time::Duration::from_millis(
+                WAIT_DEVICE_MS.load(Ordering::SeqCst),
+            ));
+            discover_devices(
+                self.include_names.as_deref(),
+                self.exclude_names.as_deref(),
+                self.device_detect_mode,
+            )
+            .into_iter()
+            .try_for_each(|(dev, path)| {
+                if !self
+                    .devices
+                    .values()
+                    .any(|(_, registered_path)| &path == registered_path)
+                {
+                    self.register_device(dev, path)
+                } else {
+                    Ok(())
+                }
+            })?;
         }
         Ok(())
     }
 }
 
-pub fn is_input_device(device: &Device) -> bool {
-    use evdev::Key;
-    let is_keyboard = device
-        .supported_keys()
-        .map_or(false, |keys| keys.contains(Key::KEY_ENTER));
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+enum DeviceType {
+    Keyboard,
+    KeyboardMouse,
+    Mouse,
+    Other,
+}
+
+pub fn is_input_device(device: &Device, detect_mode: DeviceDetectMode) -> bool {
+    if device.name() == Some("kanata") {
+        return false;
+    }
+    let is_keyboard = device.supported_keys().is_some_and(has_keyboard_keys);
     let is_mouse = device
         .supported_relative_axes()
-        .map_or(false, |axes| axes.contains(RelativeAxisType::REL_X));
-    if is_keyboard || is_mouse {
-        if device.name() == Some("kanata") {
-            return false;
+        .is_some_and(|axes| axes.contains(RelativeAxisCode::REL_X));
+    let device_type = match (is_keyboard, is_mouse) {
+        (true, true) => DeviceType::KeyboardMouse,
+        (true, false) => DeviceType::Keyboard,
+        (false, true) => DeviceType::Mouse,
+        (false, false) => DeviceType::Other,
+    };
+    let device_name = device.name().unwrap_or("unknown device name");
+    match (detect_mode, device_type) {
+        (DeviceDetectMode::Any, _)
+        | (DeviceDetectMode::KeyboardMice, DeviceType::Keyboard | DeviceType::KeyboardMouse)
+        | (DeviceDetectMode::KeyboardOnly, DeviceType::Keyboard) => {
+            let use_input = true;
+            log::debug!(
+                "Use for input autodetect: {use_input}. detect type {:?}; device type {:?}, device name: {}",
+                detect_mode,
+                device_type,
+                device_name,
+            );
+            use_input
+        }
+        (_, DeviceType::Other) => {
+            log::debug!(
+                "Use for input autodetect: false. Non-input device: {}",
+                device_name,
+            );
+            false
+        }
+        _ => {
+            let use_input = false;
+            log::debug!(
+                "Use for input autodetect: {use_input}. detect type {:?}; device type {:?}, device name: {}",
+                detect_mode,
+                device_type,
+                device_name,
+            );
+            use_input
         }
-        log::debug!(
-            "Detected {}: name={} physical_path={:?}",
-            if is_keyboard && is_mouse {
-                "Keyboard/Mouse"
-            } else if is_keyboard {
-                "Keyboard"
-            } else {
-                "Mouse"
-            },
-            device.name().unwrap_or("unknown device name"),
-            device.physical_path()
-        );
-        true
-    } else {
-        log::trace!(
-            "Detected other device: {}",
-            device.name().unwrap_or("unknown device name")
-        );
-        false
     }
 }
 
-#[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub enum UnicodeTermination {
-    Enter,
-    Space,
-    SpaceEnter,
-    EnterSpace,
+fn has_keyboard_keys(keys: &evdev::AttributeSetRef<KeyCode>) -> bool {
+    const SENSIBLE_KEYBOARD_SCANCODE_LOWER_BOUND: u16 = 1;
+    // The next one is power button. Some keyboards have it,
+    // but so does the power button...
+    const SENSIBLE_KEYBOARD_SCANCODE_UPPER_BOUND: u16 = 115;
+    let mut sensible_keyboard_keys = (SENSIBLE_KEYBOARD_SCANCODE_LOWER_BOUND
+        ..=SENSIBLE_KEYBOARD_SCANCODE_UPPER_BOUND)
+        .map(KeyCode::new);
+    sensible_keyboard_keys.any(|k| keys.contains(k))
+}
+
+impl TryFrom<InputEvent> for KeyEvent {
+    type Error = ();
+    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
+        use OsCode::*;
+        match item.destructure() {
+            evdev::EventSummary::Key(_, k, _) => Ok(Self::new(
+                OsCode::from_u16(k.0).ok_or(())?,
+                KeyValue::from(item.value()),
+            )),
+            evdev::EventSummary::RelativeAxis(_, axis_type, _) => {
+                let dist = item.value();
+                let code: OsCode = match axis_type {
+                    RelativeAxisCode::REL_WHEEL | RelativeAxisCode::REL_WHEEL_HI_RES => {
+                        if dist > 0 {
+                            MouseWheelUp
+                        } else {
+                            MouseWheelDown
+                        }
+                    }
+                    RelativeAxisCode::REL_HWHEEL | RelativeAxisCode::REL_HWHEEL_HI_RES => {
+                        if dist > 0 {
+                            MouseWheelRight
+                        } else {
+                            MouseWheelLeft
+                        }
+                    }
+                    _ => return Err(()),
+                };
+                Ok(KeyEvent::new(code, KeyValue::Tap))
+            }
+            _ => Err(()),
+        }
+    }
+}
+
+impl From<KeyEvent> for InputEvent {
+    fn from(item: KeyEvent) -> Self {
+        InputEvent::new(EventType::KEY.0, item.code as u16, item.value as i32)
+    }
 }
 
 use std::cell::Cell;
 
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 pub struct KbdOut {
     device: uinput::VirtualDevice,
     accumulated_scroll: u16,
     accumulated_hscroll: u16,
-    #[allow(dead_code)] // stored here for persistence+cleanup on exit
-    symlink: Option<Symlink>,
     raw_buf: Vec<InputEvent>,
     pub unicode_termination: Cell<UnicodeTermination>,
     pub unicode_u_code: Cell<OsCode>,
 }
 
-pub const HI_RES_SCROLL_UNITS_IN_LO_RES: u16 = 120;
-
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 impl KbdOut {
-    pub fn new(symlink_path: &Option<String>) -> Result<Self, io::Error> {
+    pub fn new(
+        symlink_path: &Option<String>,
+        trackpoint: bool,
+        name: &str,
+        bus_type: BusType,
+    ) -> Result<Self, io::Error> {
         // Support pretty much every feature of a Keyboard or a Mouse in a VirtualDevice so that no event from the original input devices gets lost
         // TODO investigate the rare possibility that a device is e.g. a Joystick and a Keyboard or a Mouse at the same time, which could lead to lost events
 
         // For some reason 0..0x300 (max value for a key) doesn't work, the closest that I've got to work is 560
-        let keys = evdev::AttributeSet::from_iter((0..560).map(evdev::Key));
+        let keys = evdev::AttributeSet::from_iter((0..560).map(evdev::KeyCode));
         let relative_axes = evdev::AttributeSet::from_iter([
-            RelativeAxisType::REL_WHEEL,
-            RelativeAxisType::REL_HWHEEL,
-            RelativeAxisType::REL_X,
-            RelativeAxisType::REL_Y,
-            RelativeAxisType::REL_Z,
-            RelativeAxisType::REL_RX,
-            RelativeAxisType::REL_RY,
-            RelativeAxisType::REL_RZ,
-            RelativeAxisType::REL_DIAL,
-            RelativeAxisType::REL_MISC,
-            RelativeAxisType::REL_WHEEL_HI_RES,
-            RelativeAxisType::REL_HWHEEL_HI_RES,
+            RelativeAxisCode::REL_WHEEL,
+            RelativeAxisCode::REL_HWHEEL,
+            RelativeAxisCode::REL_X,
+            RelativeAxisCode::REL_Y,
+            RelativeAxisCode::REL_Z,
+            RelativeAxisCode::REL_RX,
+            RelativeAxisCode::REL_RY,
+            RelativeAxisCode::REL_RZ,
+            RelativeAxisCode::REL_DIAL,
+            RelativeAxisCode::REL_MISC,
+            RelativeAxisCode::REL_WHEEL_HI_RES,
+            RelativeAxisCode::REL_HWHEEL_HI_RES,
         ]);
 
-        let mut device = uinput::VirtualDeviceBuilder::new()?
-            .name("kanata")
-            .input_id(evdev::InputId::new(evdev::BusType::BUS_USB, 1, 1, 1))
+        let device = uinput::VirtualDevice::builder()?
+            .name(&name)
+            // libinput's "disable while typing" feature don't work when bus_type
+            // is set to BUS_USB, but appears to work when it's set to BUS_I8042.
+            .input_id(evdev::InputId::new(bus_type, 1, 1, 1))
             .with_keys(&keys)?
-            .with_relative_axes(&relative_axes)?
-            .build()?;
+            .with_relative_axes(&relative_axes)?;
+        let device = if trackpoint {
+            device.with_properties(&evdev::AttributeSet::from_iter([PropType::POINTING_STICK]))?
+        } else {
+            device
+        };
+        let mut device = device.build()?;
         let devnode = device
             .enumerate_dev_nodes_blocking()?
             .next() // Expect only one. Using fold or calling next again blocks indefinitely
@@ -316,17 +422,16 @@ impl KbdOut {
         let symlink = if let Some(symlink_path) = symlink_path {
             let dest = PathBuf::from(symlink_path);
             let symlink = Symlink::new(devnode, dest)?;
-            Symlink::clean_when_killed(symlink.clone());
             Some(symlink)
         } else {
             None
         };
+        handle_signals(symlink);
 
         Ok(KbdOut {
             device,
             accumulated_scroll: 0,
             accumulated_hscroll: 0,
-            symlink,
             raw_buf: vec![],
 
             // historically was the only option, so make Enter the default
@@ -392,7 +497,7 @@ impl KbdOut {
     }
 
     pub fn write_code(&mut self, code: u32, value: KeyValue) -> Result<(), io::Error> {
-        let event = InputEvent::new(EventType::KEY, code as u16, value as i32);
+        let event = InputEvent::new(EventType::KEY.0, code as u16, value as i32);
         self.device.emit(&[event])?;
         Ok(())
     }
@@ -480,11 +585,11 @@ impl KbdOut {
         }
 
         let hi_res_scroll_event = InputEvent::new(
-            EventType::RELATIVE,
+            EventType::RELATIVE.0,
             match direction {
-                MWheelDirection::Up | MWheelDirection::Down => RelativeAxisType::REL_WHEEL_HI_RES.0,
+                MWheelDirection::Up | MWheelDirection::Down => RelativeAxisCode::REL_WHEEL_HI_RES.0,
                 MWheelDirection::Left | MWheelDirection::Right => {
-                    RelativeAxisType::REL_HWHEEL_HI_RES.0
+                    RelativeAxisCode::REL_HWHEEL_HI_RES.0
                 }
             },
             match direction {
@@ -497,13 +602,13 @@ impl KbdOut {
             self.write_many(&[
                 hi_res_scroll_event,
                 InputEvent::new(
-                    EventType::RELATIVE,
+                    EventType::RELATIVE.0,
                     match direction {
                         MWheelDirection::Up | MWheelDirection::Down => {
-                            RelativeAxisType::REL_WHEEL.0
+                            RelativeAxisCode::REL_WHEEL.0
                         }
                         MWheelDirection::Left | MWheelDirection::Right => {
-                            RelativeAxisType::REL_HWHEEL.0
+                            RelativeAxisCode::REL_HWHEEL.0
                         }
                     },
                     match direction {
@@ -519,18 +624,34 @@ impl KbdOut {
         }
     }
 
-    pub fn move_mouse(&mut self, direction: MoveDirection, distance: u16) -> Result<(), io::Error> {
-        let (axis, distance) = match direction {
-            MoveDirection::Up => (RelativeAxisType::REL_Y, -i32::from(distance)),
-            MoveDirection::Down => (RelativeAxisType::REL_Y, i32::from(distance)),
-            MoveDirection::Left => (RelativeAxisType::REL_X, -i32::from(distance)),
-            MoveDirection::Right => (RelativeAxisType::REL_X, i32::from(distance)),
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        let (axis, distance) = match mv.direction {
+            MoveDirection::Up => (RelativeAxisCode::REL_Y, -i32::from(mv.distance)),
+            MoveDirection::Down => (RelativeAxisCode::REL_Y, i32::from(mv.distance)),
+            MoveDirection::Left => (RelativeAxisCode::REL_X, -i32::from(mv.distance)),
+            MoveDirection::Right => (RelativeAxisCode::REL_X, i32::from(mv.distance)),
         };
-        self.write(InputEvent::new(EventType::RELATIVE, axis.0, distance))
+        self.write(InputEvent::new(EventType::RELATIVE.0, axis.0, distance))
+    }
+
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        let mut events = vec![];
+        for mv in moves {
+            let (axis, distance) = match mv.direction {
+                MoveDirection::Up => (RelativeAxisCode::REL_Y, -i32::from(mv.distance)),
+                MoveDirection::Down => (RelativeAxisCode::REL_Y, i32::from(mv.distance)),
+                MoveDirection::Left => (RelativeAxisCode::REL_X, -i32::from(mv.distance)),
+                MoveDirection::Right => (RelativeAxisCode::REL_X, i32::from(mv.distance)),
+            };
+            events.push(InputEvent::new(EventType::RELATIVE.0, axis.0, distance));
+        }
+        self.write_many(&events)
     }
 
     pub fn set_mouse(&mut self, _x: u16, _y: u16) -> Result<(), io::Error> {
-        log::warn!("setmouse does not work in Linux yet. Maybe try out warpd:\n\thttps://github.com/rvaiya/warpd");
+        log::warn!(
+            "setmouse does not work in Linux yet. Maybe try out warpd:\n\thttps://github.com/rvaiya/warpd"
+        );
         Ok(())
     }
 }
@@ -553,9 +674,10 @@ fn devices_from_input_paths(
         .collect()
 }
 
-fn discover_devices(
+pub fn discover_devices(
     include_names: Option<&[String]>,
     exclude_names: Option<&[String]>,
+    device_detect_mode: DeviceDetectMode,
 ) -> Vec<(Device, String)> {
     log::info!("looking for devices in /dev/input");
     let devices: Vec<_> = evdev::enumerate()
@@ -568,40 +690,39 @@ fn discover_devices(
             )
         })
         .filter(|pd| {
-            is_input_device(&pd.0)
-                && match include_names {
-                    None => true,
-                    Some(include_names) => {
-                        let name = pd.0.name().unwrap_or("");
-                        if include_names.iter().any(|include| name == include) {
-                            log::info!("device [{}:{name}] is included", &pd.1);
-                            true
-                        } else {
-                            log::info!("device [{}:{name}] is ignored", &pd.1);
-                            false
-                        }
+            let is_input = is_input_device(&pd.0, device_detect_mode);
+            (match include_names {
+                None => is_input,
+                Some(include_names) => {
+                    let name = pd.0.name().unwrap_or("");
+                    if include_names.iter().any(|include| name == include) {
+                        log::info!("device [{}:{name}] is included", &pd.1);
+                        true
+                    } else {
+                        log::info!("device [{}:{name}] is ignored", &pd.1);
+                        false
                     }
                 }
-                && match exclude_names {
-                    None => true,
-                    Some(exclude_names) => {
-                        let name = pd.0.name().unwrap_or("");
-                        if exclude_names.iter().any(|exclude| name == exclude) {
-                            log::info!("device [{}:{name}] is excluded", &pd.1);
-                            false
-                        } else {
-                            true
-                        }
+            }) && (match exclude_names {
+                None => true,
+                Some(exclude_names) => {
+                    let name = pd.0.name().unwrap_or("");
+                    if exclude_names.iter().any(|exclude| name == exclude) {
+                        log::info!("device [{}:{name}] is excluded", &pd.1);
+                        false
+                    } else {
+                        true
                     }
                 }
+            })
         })
         .collect();
     devices
 }
 
 fn watch_devinput() -> Result<Inotify, io::Error> {
-    let mut inotify = Inotify::init().expect("Failed to initialize inotify");
-    inotify.add_watch("/dev/input", WatchMask::CREATE)?;
+    let inotify = Inotify::init().expect("Failed to initialize inotify");
+    inotify.watches().add("/dev/input", WatchMask::CREATE)?;
     Ok(inotify)
 }
 
@@ -629,42 +750,28 @@ impl Symlink {
         log::info!("Created symlink {:#?} -> {:#?}", dest, source);
         Ok(Self { dest })
     }
+}
 
-    fn clean_when_killed(symlink: Self) {
-        thread::spawn(|| {
-            let mut signals = Signals::new([SIGINT, SIGTERM]).expect("signals register");
-            for signal in &mut signals {
-                match signal {
-                    SIGINT | SIGTERM => {
-                        drop(symlink);
-                        signal_hook::low_level::emulate_default_handler(signal)
-                            .expect("run original sighandlers");
-                        unreachable!();
-                    }
-                    _ => unreachable!(),
+fn handle_signals(symlink: Option<Symlink>) {
+    thread::spawn(|| {
+        let mut signals = Signals::new([SIGINT, SIGTERM, SIGTSTP]).expect("signals register");
+        if let Some(signal) = (&mut signals).into_iter().next() {
+            match signal {
+                SIGINT | SIGTERM => {
+                    drop(symlink);
+                    signal_hook::low_level::emulate_default_handler(signal)
+                        .expect("run original sighandlers");
+                    unreachable!();
                 }
+                SIGTSTP => {
+                    drop(symlink);
+                    log::warn!("got SIGTSTP, exiting instead of pausing so keyboards don't hang");
+                    std::process::exit(SIGTSTP);
+                }
+                _ => unreachable!(),
             }
-        });
-    }
-}
-
-pub fn parse_colon_separated_text(paths: &str) -> Vec<String> {
-    let mut all_paths = vec![];
-    let mut full_dev_path = String::new();
-    let mut dev_path_iter = paths.split(':').peekable();
-    while let Some(dev_path) = dev_path_iter.next() {
-        if dev_path.ends_with('\\') && dev_path_iter.peek().is_some() {
-            full_dev_path.push_str(dev_path.trim_end_matches('\\'));
-            full_dev_path.push(':');
-            continue;
-        } else {
-            full_dev_path.push_str(dev_path);
         }
-        all_paths.push(full_dev_path.clone());
-        full_dev_path.clear();
-    }
-    all_paths.shrink_to_fit();
-    all_paths
+    });
 }
 
 // Note for allow: the ioctl_read_buf triggers this clippy lint.
@@ -675,12 +782,13 @@ fn wait_for_all_keys_unpressed(dev: &Device) -> Result<(), io::Error> {
     let mut pending_release = false;
     const KEY_MAX: usize = OsCode::KEY_MAX as usize;
     let mut keystate = [0u8; KEY_MAX / 8 + 1];
+    let mut loop_attempts: usize = 0;
     loop {
         let mut n_pressed_keys = 0;
         ioctl_read_buf!(read_keystates, 'E', 0x18, u8);
         unsafe { read_keystates(dev.as_raw_fd(), &mut keystate) }
             .map_err(|_| io::Error::last_os_error())?;
-        for i in 0..=KEY_MAX {
+        for i in 0..KEY_MAX {
             if (keystate[i / 8] >> (i % 8)) & 0x1 > 0 {
                 n_pressed_keys += 1;
             }
@@ -689,6 +797,30 @@ fn wait_for_all_keys_unpressed(dev: &Device) -> Result<(), io::Error> {
             0 => break,
             _ => pending_release = true,
         }
+        if loop_attempts > 1250 {
+            let dev_str = if let Some(dev_name) = dev.name() {
+                format!("\"{}\"", dev_name)
+            } else if let Some(dev_path) = dev.physical_path() {
+                format!("\"{}\"", dev_path)
+            } else {
+                let dev_input_id = dev.input_id();
+                let vendor = dev_input_id.vendor();
+                let product = dev_input_id.product();
+                let version = dev_input_id.version();
+                format!(
+                    "{{ Vendor:{:#04x}, Product:{:#04x}, Version:{:#04x} }}",
+                    vendor, product, version
+                )
+            };
+            log::warn!(
+                "timed out waiting for {} to release its keys ({} pressed)",
+                dev_str,
+                n_pressed_keys
+            );
+            break;
+        }
+        loop_attempts += 1;
+        std::thread::sleep(std::time::Duration::from_millis(4));
     }
     if pending_release {
         std::thread::sleep(std::time::Duration::from_micros(100));
@@ -696,13 +828,6 @@ fn wait_for_all_keys_unpressed(dev: &Device) -> Result<(), io::Error> {
     Ok(())
 }
 
-#[test]
-fn test_parse_dev_paths() {
-    assert_eq!(parse_colon_separated_text("h:w"), ["h", "w"]);
-    assert_eq!(parse_colon_separated_text("h\\:w"), ["h:w"]);
-    assert_eq!(parse_colon_separated_text("h\\:w\\"), ["h:w\\"]);
-}
-
 impl Drop for Symlink {
     fn drop(&mut self) {
         let _ = fs::remove_file(&self.dest);
diff --git a/src/oskbd/macos.rs b/src/oskbd/macos.rs
new file mode 100644
index 000000000..be9483224
--- /dev/null
+++ b/src/oskbd/macos.rs
@@ -0,0 +1,1768 @@
+//! Contains the input/output code for keyboards on Macos.
+
+// Caused by unmaintained objc crate triggering warnings.
+#![allow(unexpected_cfgs)]
+#![cfg_attr(
+    feature = "simulated_output",
+    allow(dead_code, unused_imports, unused_variables, unused_mut)
+)]
+
+use super::*;
+use crate::kanata::CalculatedMouseMove;
+use crate::oskbd::KeyEvent;
+use anyhow::anyhow;
+use core_foundation::base::{CFType, TCFType};
+use core_foundation::boolean::CFBoolean;
+use core_foundation::dictionary::{CFDictionary, CFDictionaryRef};
+use core_foundation::runloop::{CFRunLoop, kCFRunLoopCommonModes};
+use core_foundation::string::{CFString, CFStringRef};
+use core_graphics::base::CGFloat;
+use core_graphics::display::{CGDisplay, CGPoint};
+use core_graphics::event::{
+    CGEvent, CGEventTap, CGEventTapLocation, CGEventTapOptions, CGEventTapPlacement, CGEventType,
+    CGMouseButton, EventField,
+};
+use core_graphics::event_source::{CGEventSource, CGEventSourceStateID};
+use kanata_parser::cfg::MappedKeys;
+use kanata_parser::custom_action::*;
+use kanata_parser::keys::*;
+use karabiner_driverkit::*;
+use objc::runtime::Class;
+use objc::{msg_send, sel, sel_impl};
+use std::collections::HashMap;
+use std::convert::TryFrom;
+use std::fmt;
+use std::io;
+use std::io::Error;
+use std::sync::OnceLock;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::SyncSender as Sender;
+use std::time::{Duration, Instant};
+
+/// Mouse `OsCode`s that, when present in `MAPPED_KEYS`, justify installing the
+/// CGEventTap. Used both as the startup/reload install gate and as the set of
+/// codes the tap can produce.
+const MOUSE_OSCODES: [OsCode; 9] = [
+    OsCode::BTN_LEFT,
+    OsCode::BTN_RIGHT,
+    OsCode::BTN_MIDDLE,
+    OsCode::BTN_SIDE,
+    OsCode::BTN_EXTRA,
+    OsCode::MouseWheelUp,
+    OsCode::MouseWheelDown,
+    OsCode::MouseWheelLeft,
+    OsCode::MouseWheelRight,
+];
+
+/// Sender stashed by the first `start_mouse_listener` call so that
+/// `ensure_mouse_listener_installed_after_reload` can install the tap on a
+/// later live reload without needing the original `event_loop` context.
+static MOUSE_TAP_TX: OnceLock<Sender<KeyEvent>> = OnceLock::new();
+
+/// Tracks whether `start_mouse_listener` has *claimed* the install slot —
+/// i.e. promised to spawn a thread that will create and enable a CGEventTap.
+/// Claimed via `compare_exchange` *before* `thread::spawn` so a concurrent
+/// live reload cannot race in and install a second tap during the brief
+/// window before the spawned thread reaches `tap.enable()`. Reset to `false`
+/// if `CGEventTap::new` fails, so a future reload (e.g. after the user grants
+/// Accessibility permission) can retry.
+///
+/// Note that "claimed" is slightly stronger than "currently capturing
+/// events": there is a sub-millisecond gap between the claim and
+/// `tap.enable()` during which no events flow yet. Reload callers
+/// short-circuit in that gap, which is correct because the spawned thread
+/// will deliver the working tap regardless.
+static MOUSE_TAP_INSTALLED: AtomicBool = AtomicBool::new(false);
+
+/// Stashed by the first `start_mouse_listener` call so the CGEventTap callback
+/// can read the live `mouse-movement-key` setting on every cursor movement
+/// event. The Arc points to the same `parking_lot::Mutex` that the live-reload
+/// path updates, so changes take effect with no extra plumbing.
+static MOUSE_MOVEMENT_KEY: OnceLock<std::sync::Arc<parking_lot::Mutex<Option<OsCode>>>> =
+    OnceLock::new();
+
+// --- Karabiner startup-abort diagnostics ---
+//
+// On macOS, kanata grabs keyboards via the
+// Karabiner-DriverKit-VirtualHIDDevice C++ library (the
+// `karabiner-driverkit` crate). That library spawns its own dispatcher
+// threads which talk to the `Karabiner-VirtualHIDDevice-Daemon` over
+// root-owned IPC files under
+// `/Library/Application Support/org.pqrs/tmp/rootonly/`. That directory
+// is mode 700 owned by root, so *the kanata process itself must run as
+// root* (via `sudo` or a launchd daemon) to reach the sockets inside.
+//
+// When that invariant is violated — the #1 real-world cause being
+// "forgot to `sudo`", followed by "driver not installed / system
+// extension not approved" — the C++ dispatcher threads hit an uncaught
+// `std::filesystem_error` on a `posix_stat` of the rootonly directory.
+// The exception bubbles up on a background thread that has no
+// try/catch wrapper, libc++abi calls `std::terminate`, and the process
+// aborts via `SIGABRT` with the cryptic message:
+//
+//     libc++abi: terminating due to uncaught exception of type
+//     std::__1::__fs::filesystem::filesystem_error: ...
+//
+// To turn that into something actionable, we install a `SIGABRT`
+// handler that — *after* libc++abi has printed its own message —
+// writes a static hint to stderr enumerating the likely causes in
+// order (not running as root, driver not approved, exclusive grabber),
+// then restores the default handler and re-raises so the abort still
+// propagates with the usual exit code / coredump behavior.
+//
+// The hint is gated on `KARABINER_STARTUP_PHASE`: it is only emitted
+// from handler-install time until `mark_karabiner_startup_complete()`
+// fires (right after `wait_until_ready` returns on the happy path).
+// Any `SIGABRT` after that is almost certainly an unrelated
+// dispatcher/CoreFoundation teardown race — for which the Karabiner
+// hint would be actively misleading — so the handler silently
+// re-raises in that phase. The kill-chord exit path avoids tripping
+// the teardown race at all by using `libc::_exit` instead of
+// `std::process::exit` (see `check_for_exit` in `src/kanata/mod.rs`).
+//
+// The handler body uses only async-signal-safe calls
+// (`AtomicBool::load`, `write(2)`, `signal`, `raise`).
+
+/// True while kanata is still in the Karabiner startup path — i.e. from
+/// the first call to `install_karabiner_abort_handler` until
+/// `mark_karabiner_startup_complete()` is called. The `SIGABRT` handler
+/// reads this to decide whether to emit the Karabiner hint: during
+/// startup, an uncaught exception is almost always a Karabiner setup
+/// issue and the hint is actionable; after startup (running normally or
+/// tearing down), it's typically a dispatcher/CoreFoundation teardown
+/// race and the hint would be misleading.
+static KARABINER_STARTUP_PHASE: std::sync::atomic::AtomicBool =
+    std::sync::atomic::AtomicBool::new(false);
+
+/// Signal that kanata has finished talking to the Karabiner daemon during
+/// startup and is running normally. After this, the `SIGABRT` handler will
+/// stop emitting the Karabiner hint. Idempotent.
+pub fn mark_karabiner_startup_complete() {
+    KARABINER_STARTUP_PHASE.store(false, std::sync::atomic::Ordering::Release);
+}
+
+extern "C" fn karabiner_sigabrt_handler(_sig: libc::c_int) {
+    // Only emit the hint during startup — see `KARABINER_STARTUP_PHASE`.
+    // `AtomicBool::load` compiles to an async-signal-safe plain load.
+    if !KARABINER_STARTUP_PHASE.load(std::sync::atomic::Ordering::Acquire) {
+        // Not in startup — restore default handler and re-raise without
+        // printing anything extra. The underlying libc++abi message
+        // (if any) has already been written to stderr by the time we
+        // get here.
+        unsafe {
+            libc::signal(libc::SIGABRT, libc::SIG_DFL);
+            libc::raise(libc::SIGABRT);
+        }
+        return;
+    }
+    // Async-signal-safe: only `write(2)` and `signal/raise`. Keep the
+    // message as a single static byte string — no formatting, no
+    // allocations.
+    const HINT: &[u8] = b"\n\
+        kanata: aborted while talking to the Karabiner virtual HID daemon.\n\
+        The most likely causes, in order:\n\
+          1) kanata is not running as root. The Karabiner virtual HID daemon\n\
+             exposes its IPC under `/Library/Application Support/org.pqrs/\n\
+             tmp/rootonly/`, which only root can access. Re-run kanata with\n\
+             `sudo`, or install it as a launchd daemon that runs as root.\n\
+          2) Karabiner-DriverKit-VirtualHIDDevice is not installed or its\n\
+             system extension has not been approved. Run\n\
+             `sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager forceActivate`,\n\
+             approve the driver in System Settings -> General -> Login Items\n\
+             & Extensions -> Driver Extensions if prompted, then re-run\n\
+             kanata. A reboot may be required after a prior `deactivate`.\n\
+          3) Another process is already grabbing your keyboard exclusively.\n\
+        \n";
+    // SAFETY: write(2) is async-signal-safe and takes a raw fd + buffer.
+    unsafe {
+        libc::write(
+            libc::STDERR_FILENO,
+            HINT.as_ptr() as *const libc::c_void,
+            HINT.len(),
+        );
+        // Restore default handler and re-raise so the abort propagates as
+        // usual (preserves exit code / coredump behavior).
+        libc::signal(libc::SIGABRT, libc::SIG_DFL);
+        libc::raise(libc::SIGABRT);
+    }
+}
+
+// --- Input Monitoring (TCC) pre-flight ---
+//
+// On macOS, observing raw keyboard events requires the "Input
+// Monitoring" TCC permission (System Settings -> Privacy & Security
+// -> Input Monitoring). Without it, startup fails deep inside the
+// Karabiner DriverKit stack with an error that doesn't mention TCC at
+// all, leaving users guessing. Checking up front turns that into a
+// single actionable message, and on a first run asks macOS to
+// register kanata under Input Monitoring so the user has something to
+// toggle on. Flagged in issue #1743.
+
+// IOKit framework bindings for the Input Monitoring TCC gate.
+// `IOHIDCheckAccess` reports the current decision; `IOHIDRequestAccess`
+// registers the binary under System Settings and (if possible) prompts
+// the user. Both take an `IOHIDRequestType` and return an
+// `IOHIDAccessType` / `bool`.
+#[link(name = "IOKit", kind = "framework")]
+unsafe extern "C" {
+    fn IOHIDCheckAccess(request: u32) -> u32;
+    fn IOHIDRequestAccess(request: u32) -> bool;
+    fn IOHIDGetModifierLockState(handle: u32, selector: i32, state: *mut bool) -> i32;
+    fn IOHIDSetModifierLockState(handle: u32, selector: i32, state: bool) -> i32;
+    fn IOServiceMatching(name: *const libc::c_char) -> *mut libc::c_void;
+    fn IOServiceGetMatchingService(main_port: u32, matching: *mut libc::c_void) -> u32;
+    fn IOServiceOpen(service: u32, owning_task: u32, type_: u32, connect: *mut u32) -> i32;
+    fn IOObjectRelease(object: u32) -> i32;
+
+    static mach_task_self_: u32;
+}
+
+// ApplicationServices bindings for the Accessibility TCC gate.
+// `AXIsProcessTrusted` reports whether the current process is trusted
+// for Accessibility without showing any system prompt. If it is not
+// trusted, `AXIsProcessTrustedWithOptions` with
+// `kAXTrustedCheckOptionPrompt = true` asks macOS to register/prompt
+// kanata so the user can flip the Accessibility toggle. The symbols
+// live in the HIServices subframework of ApplicationServices and are
+// available on every macOS version kanata supports. core-graphics
+// (already a dependency) links CoreGraphics, which transitively loads
+// ApplicationServices, but declare the framework link explicitly so
+// this does not silently break if that transitive link ever changes.
+#[link(name = "ApplicationServices", kind = "framework")]
+unsafe extern "C" {
+    static kAXTrustedCheckOptionPrompt: CFStringRef;
+
+    fn AXIsProcessTrusted() -> bool;
+    fn AXIsProcessTrustedWithOptions(options: CFDictionaryRef) -> bool;
+}
+
+/// `IOHIDRequestType::kIOHIDRequestTypeListenEvent` from
+/// `<IOKit/hid/IOHIDLib.h>`: the request type that maps to the Input
+/// Monitoring TCC service.
+const K_IOHID_REQUEST_TYPE_LISTEN_EVENT: u32 = 1;
+/// `IOHIDAccessType` values from `<IOKit/hid/IOHIDLib.h>`.
+const K_IOHID_ACCESS_TYPE_GRANTED: u32 = 0;
+const K_IOHID_ACCESS_TYPE_DENIED: u32 = 1;
+const K_IOHID_ACCESS_TYPE_UNKNOWN: u32 = 2;
+const K_IOHID_PARAM_CONNECT_TYPE: u32 = 1;
+const K_IOHID_CAPS_LOCK_STATE: i32 = 1;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum AccessibilityPermissionStatus {
+    Trusted,
+    Requested,
+}
+
+/// Pre-flight check for Input Monitoring permission. Returns `Ok(())`
+/// if kanata is allowed to observe events; otherwise returns an
+/// `anyhow::Error` that surfaces as the startup failure reason,
+/// pointing the user at the exact setting to flip.
+///
+/// On the "unknown" (first-run) branch we call `IOHIDRequestAccess`,
+/// which adds kanata to System Settings -> Privacy & Security -> Input
+/// Monitoring. For a root/LaunchDaemon context that call cannot
+/// display a UI prompt and will return false; the returned error
+/// message then tells the user where to grant it manually.
+fn ensure_input_monitoring_permission() -> Result<(), anyhow::Error> {
+    const HINT: &str = "Enable kanata in System Settings -> Privacy & Security -> \
+         Input Monitoring, then re-run kanata.";
+    // SAFETY: plain FFI call with a scalar arg; the symbol is present
+    // on every macOS version kanata supports (10.15+).
+    let status = unsafe { IOHIDCheckAccess(K_IOHID_REQUEST_TYPE_LISTEN_EVENT) };
+    match status {
+        K_IOHID_ACCESS_TYPE_GRANTED => Ok(()),
+        K_IOHID_ACCESS_TYPE_UNKNOWN => {
+            log::info!(
+                "macOS Input Monitoring permission not yet decided; \
+                 asking IOKit to register kanata under System Settings"
+            );
+            // SAFETY: plain FFI call.
+            let granted = unsafe { IOHIDRequestAccess(K_IOHID_REQUEST_TYPE_LISTEN_EVENT) };
+            if granted {
+                Ok(())
+            } else {
+                Err(anyhow!(
+                    "kanata needs macOS Input Monitoring permission. {HINT}"
+                ))
+            }
+        }
+        K_IOHID_ACCESS_TYPE_DENIED => Err(anyhow!(
+            "macOS Input Monitoring permission is denied for kanata. {HINT}"
+        )),
+        other => {
+            log::warn!(
+                "IOHIDCheckAccess returned unexpected status {other}; \
+                 continuing and letting the driver layer report any failure"
+            );
+            Ok(())
+        }
+    }
+}
+
+/// Pre-flight check for Accessibility permission. Even after Input
+/// Monitoring is granted, grabbing keyboards through the Karabiner
+/// DriverKit stack can fail with `IOHIDDeviceOpen error: (iokit/common)
+/// not permitted` / `kIOReturnNotPermitted` when the Accessibility TCC
+/// service is not granted — issue #1211 and many duplicates. Checking
+/// up front turns that into a single actionable message pointing at
+/// the exact setting, instead of the generic "grab failed" users see
+/// otherwise.
+///
+/// If the permission has not been granted yet, ask ApplicationServices
+/// to register/prompt kanata by calling `AXIsProcessTrustedWithOptions`
+/// with `kAXTrustedCheckOptionPrompt = true`. In root/LaunchDaemon
+/// contexts macOS may be unable to show UI, but the call still gives
+/// TCC a chance to create the System Settings entry for the current
+/// binary path.
+pub fn request_accessibility_permission() -> Result<AccessibilityPermissionStatus, anyhow::Error> {
+    // Important CLI UX caveat: Apple's public AX trust APIs only answer
+    // whether "the current process" is trusted; they do not let us ask
+    // about, or register, an arbitrary executable path. For a command-line
+    // tool launched from Terminal, macOS may attribute trust to Terminal (the
+    // responsible process), so this status must not be presented as proof
+    // that the kanata binary itself appears as a separate Accessibility item.
+    if unsafe {
+        // SAFETY: plain FFI call with no args; the symbol is present on
+        // every macOS version kanata supports (10.15+).
+        AXIsProcessTrusted()
+    } {
+        return Ok(AccessibilityPermissionStatus::Trusted);
+    }
+
+    log::info!(
+        "macOS Accessibility permission not yet granted; \
+         asking ApplicationServices to register/prompt kanata under System Settings"
+    );
+
+    let prompt_key = unsafe {
+        if kAXTrustedCheckOptionPrompt.is_null() {
+            return Err(anyhow!(
+                "macOS Accessibility permission request failed: \
+                 kAXTrustedCheckOptionPrompt was not available"
+            ));
+        }
+
+        // SAFETY: kAXTrustedCheckOptionPrompt is a process-global CFString
+        // owned by ApplicationServices. wrap_under_get_rule retains it for
+        // the temporary dictionary below.
+        CFString::wrap_under_get_rule(kAXTrustedCheckOptionPrompt)
+    };
+    let prompt_value = CFBoolean::true_value();
+    let options = CFDictionary::from_CFType_pairs(&[(prompt_key, prompt_value)]);
+
+    if unsafe {
+        // SAFETY: options is a valid CFDictionary containing the documented
+        // kAXTrustedCheckOptionPrompt -> true pair.
+        AXIsProcessTrustedWithOptions(options.as_concrete_TypeRef())
+    } {
+        Ok(AccessibilityPermissionStatus::Trusted)
+    } else {
+        Ok(AccessibilityPermissionStatus::Requested)
+    }
+}
+
+fn ensure_accessibility_permission() -> Result<(), anyhow::Error> {
+    match request_accessibility_permission()? {
+        AccessibilityPermissionStatus::Trusted => Ok(()),
+        AccessibilityPermissionStatus::Requested => Err(anyhow!(
+            "kanata needs macOS Accessibility permission. Enable kanata in \
+             System Settings -> Privacy & Security -> Accessibility, then \
+             restart kanata. Note: if you moved, renamed, or upgraded the \
+             kanata binary, macOS pins the old path and you must remove the \
+             stale entry and re-add the current binary. This is the \
+             commonly-missed second permission behind the `IOHIDDeviceOpen \
+             error: (iokit/common) not permitted` failure (issue #1211)."
+        )),
+    }
+}
+
+/// Install a `SIGABRT` handler that adds an actionable hint about
+/// Karabiner setup issues *after* libc++abi prints its own
+/// uncaught-exception message, and enter the "Karabiner startup phase"
+/// during which that hint is active. Idempotent and process-global; safe
+/// to call multiple times. See the module-level comment for the full
+/// rationale.
+fn install_karabiner_abort_handler() {
+    use std::sync::atomic::{AtomicBool, Ordering};
+    static INSTALLED: AtomicBool = AtomicBool::new(false);
+    // Enter the startup phase unconditionally — even on a repeat call we
+    // want the hint active until `mark_karabiner_startup_complete` runs.
+    KARABINER_STARTUP_PHASE.store(true, Ordering::Release);
+    if INSTALLED
+        .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+        .is_err()
+    {
+        return;
+    }
+    // SAFETY: signal(2) takes an fn pointer with the C ABI; the handler
+    // body only calls async-signal-safe functions. The two-step cast goes
+    // through `*const ()` to satisfy the `function_casts_as_integer` lint.
+    let handler_ptr = karabiner_sigabrt_handler as *const () as libc::sighandler_t;
+    unsafe {
+        libc::signal(libc::SIGABRT, handler_ptr);
+    }
+}
+
+// --- Console session lock / user-switch detection ---
+//
+// kanata on macOS must run as root, so its keyboard grab is global —
+// it stays active at the lock screen and during fast user switching.
+// That's hostile to anyone else at the keyboard, who is stuck with
+// the kanata user's remap (any layout swap, home-row mods, etc.)
+// when trying to type their own password or use their own session.
+// Flagged in issue #1743.
+//
+// Fix: poll `CGSessionCopyCurrentDictionary` from a small background
+// thread (~200ms) and toggle `SCREEN_GRAB_PAUSED` when either:
+//   - the screen is locked (`CGSSessionScreenIsLocked` boolean —
+//     undocumented but stable for many years; empirically the key
+//     is *absent* from the dict while unlocked and present-and-true
+//     while locked, so missing is treated as unlocked), OR
+//   - kanata's session is no longer on the console
+//     (`kCGSSessionOnConsoleKey` boolean is false; this one *is*
+//     documented in `<CoreGraphics/CGSession.h>`), i.e. another
+//     user has taken the console via fast user switching.
+//
+// Per `<CoreGraphics/CGSession.h>`, `CGSessionCopyCurrentDictionary`
+// returns the *caller's* session (not the active console session) or
+// NULL if the caller has no Quartz GUI session at all (e.g. root
+// LaunchDaemon started at boot before any login). That last case
+// matters: NULL must NOT pause, otherwise launchd-daemon installs
+// would never grab the keyboard. NULL therefore falls back to "do
+// not pause", preserving the historical behavior on that path.
+//
+// Caveat: `wait_key()` is a blocking `read(2)` on the pqrs pipe, so
+// the poller can't wake kanata mid-read. The new user's first
+// keystroke after a lock is still seized by IOKit and arrives through
+// the pipe; the event loop drops it (see `src/kanata/macos.rs`)
+// instead of running it through the layer. Net effect: one lost
+// keystroke, never a remapped one.
+//
+// We do *not* call `release_input_only` from the poller thread to
+// wake the read sooner. The C++ side joins the listener thread and
+// closes raw FDs without poisoning them, so racing a poller-side
+// release against the event-loop's release/regrab could close FDs
+// that another kanata thread has reused.
+
+// Not exposed by `core-graphics`. Symbol lives in `CoreGraphics.framework`
+// (re-exported from SkyLight) which `core-graphics` already links.
+// Returns a +1-retained dictionary or NULL.
+unsafe extern "C" {
+    fn CGSessionCopyCurrentDictionary() -> CFDictionaryRef;
+}
+
+fn copy_session_dict() -> Option<CFDictionary<CFString, CFType>> {
+    // SAFETY: CGSessionCopyCurrentDictionary returns NULL or a +1 retained
+    // CFDictionaryRef; wrap_under_create_rule takes ownership of that retain.
+    unsafe {
+        let raw = CGSessionCopyCurrentDictionary();
+        if raw.is_null() {
+            None
+        } else {
+            Some(CFDictionary::wrap_under_create_rule(raw))
+        }
+    }
+}
+
+/// True while kanata's keyboard grab should be paused — currently set
+/// when kanata's CGSession reports either `CGSSessionScreenIsLocked`
+/// or `kCGSSessionOnConsoleKey == false`.
+static SCREEN_GRAB_PAUSED: AtomicBool = AtomicBool::new(false);
+
+/// Opt-in flag, set from `--release-grab-on-lock`. When false (the
+/// default), `start_screen_lock_poller` is a no-op and
+/// `is_screen_grab_paused` always returns false, preserving the
+/// historical always-grab behavior for users who run kanata on a
+/// single-user Mac and want the remap active even at the lock screen.
+static RELEASE_GRAB_ON_LOCK_ENABLED: AtomicBool = AtomicBool::new(false);
+
+pub fn set_release_grab_on_lock(enabled: bool) {
+    RELEASE_GRAB_ON_LOCK_ENABLED.store(enabled, Ordering::Release);
+}
+
+pub fn is_screen_grab_paused() -> bool {
+    SCREEN_GRAB_PAUSED.load(Ordering::Acquire)
+}
+
+/// Look up a `CFBoolean`-valued key on the given session dictionary.
+/// Returns `None` if the key is missing or the value is the wrong type.
+fn dict_bool(dict: &CFDictionary<CFString, CFType>, key: &'static str) -> Option<bool> {
+    let key = CFString::from_static_string(key);
+    let value = dict.find(&key)?;
+    value.downcast::<CFBoolean>().map(bool::from)
+}
+
+/// Decide whether the keyboard grab should currently be paused, based
+/// on the live CGSession state for kanata's own session.
+fn should_pause_for_session() -> bool {
+    // No GUI session (launchd root daemon at boot) — preserve the
+    // historical "always grab" behavior. See module-level notes.
+    let Some(dict) = copy_session_dict() else {
+        return false;
+    };
+    if dict_bool(&dict, "CGSSessionScreenIsLocked").unwrap_or(false) {
+        return true;
+    }
+    // Missing OnConsole key (early-boot / loginwindow) → treat as
+    // still-on-console to avoid false pauses.
+    !dict_bool(&dict, "kCGSSessionOnConsoleKey").unwrap_or(true)
+}
+
+/// Spawn the screen-lock / user-switch poller thread once. The thread
+/// runs for the process lifetime, polling every 200ms. Idempotent.
+/// No-op unless `--release-grab-on-lock` was passed on the CLI.
+pub fn start_screen_lock_poller() {
+    if !RELEASE_GRAB_ON_LOCK_ENABLED.load(Ordering::Acquire) {
+        return;
+    }
+    static STARTED: AtomicBool = AtomicBool::new(false);
+    if STARTED
+        .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+        .is_err()
+    {
+        return;
+    }
+
+    // Seed the flag synchronously before any read happens, so a
+    // kanata started while the screen is already locked won't get a
+    // free 200ms grab window before the first poll iteration.
+    let initial_paused = should_pause_for_session();
+    SCREEN_GRAB_PAUSED.store(initial_paused, Ordering::Release);
+    log::info!(
+        "screen-lock poller: starting (initial state: {})",
+        if initial_paused { "paused" } else { "active" },
+    );
+
+    if let Err(e) = std::thread::Builder::new()
+        .name("screen-lock-poller".into())
+        .spawn(move || {
+            let mut last_paused = initial_paused;
+            loop {
+                let now_paused = should_pause_for_session();
+                if now_paused != last_paused {
+                    SCREEN_GRAB_PAUSED.store(now_paused, Ordering::Release);
+                    if now_paused {
+                        log::info!(
+                            "screen lock or user-switch detected — keyboard grab will pause on next event"
+                        );
+                    } else {
+                        log::info!(
+                            "console session restored — keyboard grab will resume"
+                        );
+                    }
+                    last_paused = now_paused;
+                }
+                std::thread::sleep(std::time::Duration::from_millis(200));
+            }
+        })
+    {
+        log::warn!("failed to spawn screen-lock poller thread: {e}");
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct InputEvent {
+    pub value: u64,
+    pub page: u32,
+    pub code: u32,
+    pub device_hash: u64,
+}
+
+impl InputEvent {
+    pub fn new(event: DKEvent) -> Self {
+        InputEvent {
+            value: event.value,
+            page: event.page,
+            code: event.code,
+            device_hash: event.device_hash,
+        }
+    }
+}
+
+impl From<InputEvent> for DKEvent {
+    fn from(event: InputEvent) -> Self {
+        Self {
+            value: event.value,
+            page: event.page,
+            code: event.code,
+            // Output events don't originate from a physical device.
+            device_hash: 0,
+        }
+    }
+}
+
+pub struct KbdIn {
+    grabbed: bool,
+    device_hash_to_id: HashMap<u64, std::num::NonZeroU8>,
+}
+
+impl Drop for KbdIn {
+    fn drop(&mut self) {
+        release();
+    }
+}
+
+impl KbdIn {
+    pub fn new(
+        include_names: Option<Vec<String>>,
+        exclude_names: Option<Vec<String>>,
+        input_devices: Option<&[(std::num::NonZeroU8, kanata_parser::cfg::InputDeviceMatcher)]>,
+        continue_if_no_devices: bool,
+    ) -> Result<Self, anyhow::Error> {
+        // Pre-flight the Input Monitoring TCC gate before touching the
+        // Karabiner stack. A denied permission here produces a clean,
+        // actionable error pointing the user at the exact System
+        // Settings pane, instead of a confusing libc++abi abort from
+        // the driverkit dispatcher threads. See the "Input Monitoring
+        // (TCC) pre-flight" block above for the full rationale.
+        ensure_input_monitoring_permission()?;
+
+        // Pre-flight the Accessibility TCC gate too. Even with Input
+        // Monitoring granted, `IOHIDDeviceOpen` inside the Karabiner
+        // stack returns `kIOReturnNotPermitted` ("(iokit/common) not
+        // permitted") when Accessibility is missing — issue #1211 and
+        // its many duplicates. Catching that here gives the user one
+        // clean error pointing at the right pane instead of a cryptic
+        // `grab failed` after a noisy IOKit log line.
+        ensure_accessibility_permission()?;
+
+        // Install the SIGABRT hint handler before touching the
+        // karabiner-driverkit C++ code, so any uncaught
+        // `std::filesystem_error` from the C++ dispatcher threads gets
+        // decorated with an actionable Karabiner-setup message after
+        // libc++abi's output. See the module-level comment block for the
+        // full rationale (tl;dr: most commonly "kanata is not running as
+        // root").
+        install_karabiner_abort_handler();
+
+        if !driver_activated() {
+            return Err(anyhow!(
+                "Karabiner-VirtualHIDDevice driver is not activated."
+            ));
+        }
+
+        // Based on the definition of include and exclude names, they should never be used together.
+        // Kanata config parser should probably enforce this.
+        let has_device_filter = include_names.is_some() || exclude_names.is_some();
+        let device_names = if let Some(ref included_names) = include_names {
+            validate_and_register_devices(included_names)
+        } else if let Some(ref excluded_names) = exclude_names {
+            // Exclude list: enumerate devices, filter out excluded and
+            // known-problematic virtual devices (Sidecar, etc.), then
+            // register the remainder individually.
+            let kb_list = fetch_devices();
+            let devices_to_include = kb_list
+                .iter()
+                .filter(|k| !excluded_names.iter().any(|n| *k == n.as_str()))
+                .filter(|k| !is_skipped_virtual_device(&k.product_key))
+                .map(|k| {
+                    if k.product_key.trim().is_empty() {
+                        format!("{:x}", k.hash)
+                    } else {
+                        k.product_key.clone()
+                    }
+                })
+                .collect::<Vec<String>>();
+
+            validate_and_register_devices(&devices_to_include)
+        } else {
+            vec![]
+        };
+
+        if !device_names.is_empty() || (!has_device_filter && register_device("")) {
+            if grab() {
+                let device_hash_to_id = build_device_hash_to_id_map(input_devices);
+                Ok(Self {
+                    grabbed: true,
+                    device_hash_to_id,
+                })
+            } else {
+                // We have already pre-flighted Input Monitoring and
+                // Accessibility, so by this point the most common
+                // remaining cause of a `grab failed` is a stale TCC
+                // entry that still points at an older copy of the
+                // kanata binary — macOS pins the granted path, and
+                // after a move/rename/upgrade the new binary is not
+                // actually trusted even though the UI shows an entry.
+                // See issue #1211.
+                Err(anyhow!(
+                    "grab failed. kanata could not open the keyboard device \
+                     despite Input Monitoring and Accessibility being \
+                     reported as granted. If you recently moved, renamed, \
+                     or upgraded the kanata binary, remove kanata from \
+                     System Settings -> Privacy & Security -> Input \
+                     Monitoring *and* Accessibility, then re-add the \
+                     current binary (macOS pins TCC grants to the original \
+                     path). Also verify kanata is running as root (via \
+                     sudo or a LaunchDaemon) and that no other process is \
+                     exclusively grabbing the keyboard."
+                ))
+            }
+        } else if continue_if_no_devices {
+            let names = include_names.unwrap_or_default();
+            if grab() {
+                log::info!(
+                    "No devices currently connected but listener started. \
+                     Waiting for device connection via callback..."
+                );
+                let device_hash_to_id = build_device_hash_to_id_map(input_devices);
+                Ok(Self {
+                    grabbed: false,
+                    device_hash_to_id,
+                })
+            } else {
+                log::info!("No devices registered yet. Polling for device connection...");
+                Self::poll_for_devices(&names, input_devices)
+            }
+        } else {
+            Err(anyhow!(
+                "Couldn't register any device. Use 'kanata --list' to see available devices. \
+                 Note: devices with empty names and known virtual devices (e.g. Sidecar) are \
+                 automatically skipped to prevent crashes."
+            ))
+        }
+    }
+
+    pub fn read(&mut self) -> Result<InputEvent, io::Error> {
+        let mut event = DKEvent {
+            value: 0,
+            page: 0,
+            code: 0,
+            device_hash: 0,
+        };
+
+        let got_event = wait_key(&mut event);
+        if got_event == 0 {
+            // Pipe returned EOF — input was released via release_input_only()
+            return Err(io::Error::new(
+                io::ErrorKind::UnexpectedEof,
+                "input pipe closed (devices released)",
+            ));
+        }
+
+        Ok(InputEvent::new(event))
+    }
+
+    /// Look up the device ID for an event's device hash.
+    pub fn device_id_for_hash(&self, hash: u64) -> Option<std::num::NonZeroU8> {
+        self.device_hash_to_id.get(&hash).copied()
+    }
+
+    /// Release seized input devices without tearing down the output connection.
+    /// After this call, `read()` will return `UnexpectedEof`.
+    pub fn release_input(&mut self) {
+        release_input_only();
+        self.grabbed = false;
+    }
+
+    /// Re-seize input devices after a previous `release_input()`.
+    /// Returns true if at least one device was seized.
+    pub fn regrab_input(&mut self) -> bool {
+        if !self.grabbed {
+            let ok = karabiner_driverkit::regrab_input();
+            self.grabbed = ok;
+            ok
+        } else {
+            true
+        }
+    }
+
+    pub fn is_grabbed(&self) -> bool {
+        self.grabbed
+    }
+
+    fn poll_for_devices(
+        names: &[String],
+        input_devices: Option<&[(std::num::NonZeroU8, kanata_parser::cfg::InputDeviceMatcher)]>,
+    ) -> Result<Self, anyhow::Error> {
+        let mut poll_count: u32 = 0;
+        loop {
+            std::thread::sleep(std::time::Duration::from_secs(2));
+            poll_count += 1;
+            if poll_count.is_multiple_of(15) {
+                log::info!(
+                    "Still waiting for device(s): {:?} ({}s elapsed)",
+                    names,
+                    poll_count * 2
+                );
+            }
+            let mut any_registered = false;
+            for name in names {
+                if device_matches(name) && register_device(name) {
+                    log::info!("Device '{name}' appeared and was registered");
+                    any_registered = true;
+                }
+            }
+            if any_registered {
+                if grab() {
+                    let device_hash_to_id = build_device_hash_to_id_map(input_devices);
+                    return Ok(Self {
+                        grabbed: true,
+                        device_hash_to_id,
+                    });
+                }
+                log::warn!("Device appeared but grab failed, continuing to poll...");
+            }
+        }
+    }
+}
+
+/// Device product-name patterns to skip in the default (no explicit
+/// include list) enumeration path. These are virtual HID devices that
+/// appear in the keyboard iterator but cannot or must not be seized:
+/// seizing them either aborts the process (Sidecar, see issue #1342)
+/// or is simply noise the user cannot have intended.
+///
+/// Matched case-insensitively against the device's product name. Users
+/// who need to keep one of these can add it to `macos-dev-names-include`
+/// explicitly; that path bypasses this filter.
+const SKIPPED_VIRTUAL_DEVICE_SUBSTRINGS: &[&str] = &[
+    // Apple Sidecar: iPad-as-display exposes a virtual HID keyboard.
+    // Seizing it has aborted kanata during grab() on multiple reporters.
+    "sidecar",
+    // Karabiner's own virtual keyboard. The driverkit layer already
+    // refuses to seize it, but skipping it earlier avoids a misleading
+    // "couldn't register" warning in the common list.
+    "karabiner",
+];
+
+fn is_skipped_virtual_device(product_key: &str) -> bool {
+    let lower = product_key.to_lowercase();
+    SKIPPED_VIRTUAL_DEVICE_SUBSTRINGS
+        .iter()
+        .any(|needle| lower.contains(needle))
+}
+
+/// Build a mapping from device hashes to configured device IDs by matching
+/// the connected devices against the `definputdevices` matchers.
+fn build_device_hash_to_id_map(
+    input_devices: Option<&[(std::num::NonZeroU8, kanata_parser::cfg::InputDeviceMatcher)]>,
+) -> HashMap<u64, std::num::NonZeroU8> {
+    use std::num::NonZeroU8;
+    let mut map: HashMap<u64, NonZeroU8> = HashMap::new();
+    let Some(matchers) = input_devices else {
+        return map;
+    };
+    let kb_list = fetch_devices();
+    for (id, matcher) in matchers.iter() {
+        for kb in &kb_list {
+            let name_matches = matcher
+                .name
+                .as_ref()
+                .is_none_or(|n| kb.product_key.contains(n.as_str()));
+            let hash_matches = matcher.hash.as_ref().is_none_or(|h| {
+                let device_hash = format!("{:x}", kb.hash);
+                device_hash.eq_ignore_ascii_case(h)
+            });
+            let vendor_matches = matcher
+                .vendor_id
+                .is_none_or(|v| u16::try_from(kb.vendor_id) == Ok(v));
+            let product_matches = matcher
+                .product_id
+                .is_none_or(|p| u16::try_from(kb.product_id) == Ok(p));
+            if name_matches && hash_matches && vendor_matches && product_matches {
+                if let Some(existing_id) = map.get(&kb.hash) {
+                    log::warn!(
+                        "definputdevices: device \"{}\" (hash {:x}) also matches ID {id}, \
+                         keeping first match ID {existing_id}",
+                        kb.product_key,
+                        kb.hash
+                    );
+                    continue;
+                }
+                log::info!(
+                    "definputdevices: device ID {id} matched \"{}\" (hash {:x})",
+                    kb.product_key,
+                    kb.hash
+                );
+                map.insert(kb.hash, *id);
+            }
+        }
+    }
+    map
+}
+
+fn validate_and_register_devices(include_names: &[String]) -> Vec<String> {
+    include_names
+        .iter()
+        .filter_map(|dev| {
+            // Defensive check: skip empty device names that could cause crashes
+            if dev.trim().is_empty() {
+                log::warn!("Skipping empty device name (likely old keyboard without proper identification)");
+                return None;
+            }
+
+            // Also skip the Karabiner device
+            // driverkit already prevents registering it, but this avoids unnecessary warnings
+            if dev.to_lowercase().contains("karabiner") {
+                return None;
+            }
+
+            match device_matches(dev) {
+                true => Some(dev.to_string()),
+                false => {
+                    log::warn!("'{dev}' doesn't match any connected device");
+                    None
+                }
+            }
+        })
+        .filter_map(|dev| {
+            if register_device(&dev) {
+                Some(dev.to_string())
+            } else {
+                log::warn!("Couldn't register device '{}' - device may be in use by another application or disconnected", dev);
+                None
+            }
+        })
+        .collect()
+}
+
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use kanata_keyberon::key_code::KeyCode;
+        match KeyEvent::try_from(*self) {
+            Ok(ke) => {
+                let direction = match ke.value {
+                    KeyValue::Press => "↓",
+                    KeyValue::Release => "↑",
+                    KeyValue::Repeat => "⟳",
+                    KeyValue::Tap => "↕",
+                    KeyValue::WakeUp => "!",
+                };
+                let key_name = KeyCode::from(ke.code);
+                write!(f, "{direction}{key_name:?}")
+            }
+            Err(()) => {
+                write!(
+                    f,
+                    "?unknown(page=0x{:02X},code=0x{:02X})",
+                    self.page, self.code
+                )
+            }
+        }
+    }
+}
+
+impl TryFrom<InputEvent> for KeyEvent {
+    type Error = ();
+
+    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
+        if let Ok(oscode) = OsCode::try_from(PageCode {
+            page: item.page,
+            code: item.code,
+        }) {
+            Ok(KeyEvent::new(
+                oscode,
+                if item.value == 1 {
+                    KeyValue::Press
+                } else {
+                    KeyValue::Release
+                },
+            ))
+        } else {
+            Err(())
+        }
+    }
+}
+
+impl TryFrom<KeyEvent> for InputEvent {
+    type Error = ();
+
+    fn try_from(item: KeyEvent) -> Result<Self, Self::Error> {
+        if let Ok(pagecode) = PageCode::try_from(item.code) {
+            let val = match item.value {
+                KeyValue::Press | KeyValue::Repeat => 1,
+                _ => 0,
+            };
+            Ok(InputEvent {
+                value: val,
+                page: pagecode.page,
+                code: pagecode.code,
+                device_hash: 0,
+            })
+        } else {
+            Err(())
+        }
+    }
+}
+
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+fn hid_system_param_connect() -> Option<u32> {
+    static CONNECT: OnceLock<Option<u32>> = OnceLock::new();
+
+    *CONNECT.get_or_init(|| {
+        let service_name = c"IOHIDSystem";
+        let matching = unsafe {
+            // SAFETY: IOServiceMatching expects a null-terminated service name
+            // and returns a retained matching dictionary consumed by
+            // IOServiceGetMatchingService below.
+            IOServiceMatching(service_name.as_ptr())
+        };
+        if matching.is_null() {
+            log::warn!("failed to create IOHIDSystem matching dictionary");
+            return None;
+        }
+
+        let service = unsafe {
+            // SAFETY: kIOMainPortDefault is 0. IOServiceGetMatchingService
+            // consumes the retained matching dictionary returned above.
+            IOServiceGetMatchingService(0, matching)
+        };
+        if service == 0 {
+            log::warn!("failed to find IOHIDSystem service for Caps Lock LED sync");
+            return None;
+        }
+
+        let mut connect = 0u32;
+        let rc = unsafe {
+            // SAFETY: service is a live IOService handle. mach_task_self_ is
+            // the process task port exported by libSystem.
+            IOServiceOpen(
+                service,
+                mach_task_self_,
+                K_IOHID_PARAM_CONNECT_TYPE,
+                &mut connect,
+            )
+        };
+        unsafe {
+            // SAFETY: service was returned by IOServiceGetMatchingService and
+            // must be released after IOServiceOpen.
+            IOObjectRelease(service);
+        }
+
+        if rc == 0 && connect != 0 {
+            Some(connect)
+        } else {
+            log::warn!("failed to open IOHIDSystem parameter connection: rc={rc}");
+            None
+        }
+    })
+}
+
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+fn get_hid_caps_lock_state() -> Option<bool> {
+    let connect = hid_system_param_connect()?;
+    let mut state = false;
+    let rc = unsafe {
+        // SAFETY: connect is an IOHIDSystem parameter connection cached above;
+        // state points to valid writable memory for the duration of the call.
+        IOHIDGetModifierLockState(connect, K_IOHID_CAPS_LOCK_STATE, &mut state)
+    };
+    if rc == 0 {
+        Some(state)
+    } else {
+        log::warn!("failed to read IOHID Caps Lock state: rc={rc}");
+        None
+    }
+}
+
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+fn set_hid_caps_lock_state(state: bool) -> io::Result<()> {
+    let connect = hid_system_param_connect()
+        .ok_or_else(|| io::Error::other("IOHIDSystem parameter connection unavailable"))?;
+    let rc = unsafe {
+        // SAFETY: connect is an IOHIDSystem parameter connection cached above.
+        // kIOHIDCapsLockState is the documented selector for this API.
+        IOHIDSetModifierLockState(connect, K_IOHID_CAPS_LOCK_STATE, state)
+    };
+    if rc == 0 {
+        Ok(())
+    } else {
+        Err(io::Error::other(format!(
+            "failed to set IOHID Caps Lock state: rc={rc}"
+        )))
+    }
+}
+
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+pub struct KbdOut {
+    output_pressed_since: HashMap<OsCode, Instant>,
+    caps_lock_state: Option<bool>,
+}
+
+/// Treat a sink-disconnect from the processing thread as a non-fatal drop.
+///
+/// The macOS event loop (`src/kanata/macos.rs`) coordinates recovery when the
+/// DriverKit sink goes away (e.g. on wake-from-sleep) by polling
+/// `output_ready()` and re-grabbing input. The processing thread runs in
+/// parallel and can race ahead, attempting a write before the event loop
+/// notices. Without this, that write would propagate `NotConnected` up to
+/// `handle_keys` and panic the processing loop.
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+fn drop_if_sink_disconnected(
+    err: io::Error,
+    key: OsCode,
+    value: KeyValue,
+) -> Result<(), io::Error> {
+    if err.kind() == io::ErrorKind::NotConnected {
+        log::warn!("dropping {key:?} {value:?}: output backend unavailable (will recover)");
+        Ok(())
+    } else {
+        Err(err)
+    }
+}
+
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
+impl KbdOut {
+    pub fn new() -> Result<Self, io::Error> {
+        Ok(KbdOut {
+            output_pressed_since: HashMap::default(),
+            caps_lock_state: get_hid_caps_lock_state(),
+        })
+    }
+
+    fn write_caps_lock(&mut self, value: u64) -> Result<(), io::Error> {
+        if value != KeyValue::Press as u64 {
+            return Ok(());
+        }
+
+        let next_state = !self.caps_lock_state.unwrap_or(false);
+
+        // Use IOHIDSetModifierLockState instead of the VirtualHID path for caps
+        // lock. macOS sends LED output reports to the originating HID device;
+        // the DriverKit virtual keyboard has no physical LED, so the physical
+        // keyboard LED would never update. IOHIDSetModifierLockState sets both
+        // the system modifier state (so apps see correct case) and drives the
+        // LED on the physical keyboard.
+        set_hid_caps_lock_state(next_state)?;
+        self.caps_lock_state = Some(next_state);
+        Ok(())
+    }
+
+    pub fn write(&mut self, event: InputEvent) -> Result<(), io::Error> {
+        if event.page == 0x07 && event.code == 0x39 {
+            log::debug!("Caps Lock output: using IOHIDSetModifierLockState path for {event:?}");
+            return self.write_caps_lock(event.value);
+        }
+
+        let mut devent = event.into();
+        log::debug!("Attempting to write {event:?} {devent:?}");
+        let rc = send_key(&mut devent);
+        if rc == 2 {
+            return Err(io::Error::new(
+                io::ErrorKind::NotConnected,
+                "DriverKit virtual keyboard not ready (sink disconnected)",
+            ));
+        }
+        Ok(())
+    }
+
+    pub fn output_ready(&self) -> bool {
+        is_sink_ready()
+    }
+
+    pub fn wait_until_ready(&self, timeout: Option<Duration>) -> bool {
+        let start = Instant::now();
+        let mut attempt = 0u32;
+
+        loop {
+            if self.output_ready() {
+                return true;
+            }
+
+            if let Some(timeout) = timeout
+                && start.elapsed() >= timeout
+            {
+                return false;
+            }
+
+            attempt += 1;
+            if attempt % 10 == 0 {
+                if let Some(timeout) = timeout {
+                    log::info!(
+                        "Waiting for DriverKit virtual keyboard... ({:.1}s/{:.1}s)",
+                        start.elapsed().as_secs_f64(),
+                        timeout.as_secs_f64()
+                    );
+                } else {
+                    log::info!(
+                        "Waiting for DriverKit virtual keyboard... ({:.1}s)",
+                        start.elapsed().as_secs_f64()
+                    );
+                }
+            }
+
+            std::thread::sleep(Duration::from_millis(100));
+        }
+    }
+
+    pub fn write_key(&mut self, key: OsCode, value: KeyValue) -> Result<(), io::Error> {
+        if let Ok(event) = InputEvent::try_from(KeyEvent::new(key, value)) {
+            match self.write(event) {
+                Ok(()) => {
+                    self.record_output_transition_after_write(key, value);
+                    Ok(())
+                }
+                Err(e) => drop_if_sink_disconnected(e, key, value),
+            }
+        } else {
+            log::debug!("couldn't write unrecognized {key:?}");
+            Err(io::Error::other("OsCode not recognized!"))
+        }
+    }
+
+    pub fn write_code(&mut self, code: u32, value: KeyValue) -> Result<(), io::Error> {
+        let Some(key) = OsCode::from_u16(code as u16) else {
+            log::debug!("couldn't write unrecognized OsCode {code}");
+            return Err(io::Error::other("OsCode not recognized!"));
+        };
+        if let Ok(event) = InputEvent::try_from(KeyEvent::new(key, value)) {
+            match self.write(event) {
+                Ok(()) => Ok(()),
+                Err(e) => drop_if_sink_disconnected(e, key, value),
+            }
+        } else {
+            log::debug!("couldn't write unrecognized OsCode {code}");
+            Err(io::Error::other("OsCode not recognized!"))
+        }
+    }
+
+    pub fn press_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.write_key(key, KeyValue::Press)
+    }
+
+    pub fn release_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.write_key(key, KeyValue::Release)
+    }
+
+    pub fn release_tracked_output_keys(&mut self, reason: &str) {
+        let tracked_keys: Vec<OsCode> = self.output_pressed_since.keys().copied().collect();
+        if tracked_keys.is_empty() {
+            return;
+        }
+
+        for key in tracked_keys {
+            if let Err(error) = self.write_key(key, KeyValue::Release) {
+                log::warn!(
+                    "failed to release tracked output key during {} recovery: key={key:?} error={error}",
+                    reason
+                );
+            }
+        }
+
+        self.output_pressed_since.clear();
+    }
+
+    pub fn send_unicode(&mut self, c: char) -> Result<(), io::Error> {
+        let event = Self::make_event()?;
+        let mut arr = [0u16; 2];
+        // Capture the slice containing the encoded UTF-16 code units.
+        let encoded = c.encode_utf16(&mut arr);
+        // Pass only the part of the array that was populated.
+        event.set_string_from_utf16_unchecked(encoded);
+        event.set_type(CGEventType::KeyDown);
+        event.post(CGEventTapLocation::AnnotatedSession);
+        event.set_type(CGEventType::KeyUp);
+        event.post(CGEventTapLocation::AnnotatedSession);
+        Ok(())
+    }
+    pub fn scroll(&mut self, direction: MWheelDirection, distance: u16) -> Result<(), io::Error> {
+        let event = Self::make_event()?;
+        event.set_type(CGEventType::ScrollWheel);
+        match direction {
+            MWheelDirection::Down => event.set_integer_value_field(
+                EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_1,
+                distance as i64,
+            ),
+            MWheelDirection::Up => event.set_integer_value_field(
+                EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_1,
+                -(distance as i64),
+            ),
+            MWheelDirection::Left => event.set_integer_value_field(
+                EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_2,
+                distance as i64,
+            ),
+            MWheelDirection::Right => event.set_integer_value_field(
+                EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_2,
+                -(distance as i64),
+            ),
+        }
+        // Mouse control only seems to work with CGEventTapLocation::HID.
+        event.post(CGEventTapLocation::HID);
+        Ok(())
+    }
+    /// Synthesize a mouse button press or release via CGEvent.
+    ///
+    /// Side buttons (Backward/Forward) use OtherMouseDown/Up with
+    /// CGMouseButton::Center as a placeholder, then override the
+    /// MOUSE_EVENT_BUTTON_NUMBER field to the real index (3=Back, 4=Forward).
+    /// The Rust CGMouseButton enum only has 3 variants but the underlying
+    /// Apple API supports up to 32 buttons via this field.
+    ///
+    /// Ref: [init(mouseEventSource:mouseType:mouseCursorPosition:mouseButton:)][1], [setIntegerValueField][2]
+    ///
+    /// [1]: https://developer.apple.com/documentation/coregraphics/cgevent/init(mouseeventsource:mousetype:mousecursorposition:mousebutton:)
+    /// [2]: https://developer.apple.com/documentation/coregraphics/cgevent/setintegervaluefield(_:value:)
+    fn button_action(&mut self, btn: Btn, is_click: bool) -> Result<(), io::Error> {
+        // (event_type, placeholder_button, real_button_number_override)
+        let (event_type, button, button_number) = match btn {
+            Btn::Left => (
+                if is_click {
+                    CGEventType::LeftMouseDown
+                } else {
+                    CGEventType::LeftMouseUp
+                },
+                CGMouseButton::Left,
+                None,
+            ),
+            Btn::Right => (
+                if is_click {
+                    CGEventType::RightMouseDown
+                } else {
+                    CGEventType::RightMouseUp
+                },
+                CGMouseButton::Right,
+                None,
+            ),
+            Btn::Mid => (
+                if is_click {
+                    CGEventType::OtherMouseDown
+                } else {
+                    CGEventType::OtherMouseUp
+                },
+                CGMouseButton::Center,
+                None,
+            ),
+            // Side buttons use OtherMouseDown/Up (same event type as middle click)
+            // with the button number overridden after event creation.
+            Btn::Backward => (
+                if is_click {
+                    CGEventType::OtherMouseDown
+                } else {
+                    CGEventType::OtherMouseUp
+                },
+                CGMouseButton::Center,
+                Some(3), // USB HID button 4 -> CGEvent button 3 (0-indexed)
+            ),
+            Btn::Forward => (
+                if is_click {
+                    CGEventType::OtherMouseDown
+                } else {
+                    CGEventType::OtherMouseUp
+                },
+                CGMouseButton::Center,
+                Some(4), // USB HID button 5 -> CGEvent button 4 (0-indexed)
+            ),
+        };
+
+        let event_source = Self::make_event_source()?;
+        let event = Self::make_event()?;
+        let mouse_position = event.location();
+        let event = CGEvent::new_mouse_event(event_source, event_type, mouse_position, button)
+            .map_err(|_| std::io::Error::other("Failed to create mouse event"))?;
+
+        if let Some(num) = button_number {
+            event.set_integer_value_field(EventField::MOUSE_EVENT_BUTTON_NUMBER, num);
+        }
+
+        // Mouse control only seems to work with CGEventTapLocation::HID.
+        event.post(CGEventTapLocation::HID);
+        Ok(())
+    }
+
+    pub fn click_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        Self::button_action(self, btn, true)
+    }
+
+    pub fn release_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        Self::button_action(self, btn, false)
+    }
+
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        let pressed = Self::pressed_buttons();
+
+        let event_type = if pressed & 1 > 0 {
+            CGEventType::LeftMouseDragged
+        } else if pressed & 2 > 0 {
+            CGEventType::RightMouseDragged
+        } else {
+            CGEventType::MouseMoved
+        };
+
+        let event = Self::make_event()?;
+        let mut mouse_position = event.location();
+        Self::apply_calculated_move(&mv, &mut mouse_position);
+        if let Ok(event) = CGEvent::new_mouse_event(
+            Self::make_event_source()?,
+            event_type,
+            mouse_position,
+            CGMouseButton::Left,
+        ) {
+            event.post(CGEventTapLocation::HID);
+        }
+        Ok(())
+    }
+
+    fn pressed_buttons() -> usize {
+        if let Some(ns_event) = Class::get("NSEvent") {
+            unsafe { msg_send![ns_event, pressedMouseButtons] }
+        } else {
+            0
+        }
+    }
+
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        let event = Self::make_event()?;
+        let mut mouse_position = event.location();
+        let display = CGDisplay::main();
+        for current_move in moves.iter() {
+            Self::apply_calculated_move(current_move, &mut mouse_position);
+        }
+        display
+            .move_cursor_to_point(mouse_position)
+            .map_err(|_| io::Error::other("failed to move mouse"))?;
+        Ok(())
+    }
+
+    pub fn set_mouse(&mut self, x: u16, y: u16) -> Result<(), io::Error> {
+        let display = CGDisplay::main();
+        let point = CGPoint::new(x as CGFloat, y as CGFloat);
+        display
+            .move_cursor_to_point(point)
+            .map_err(|_| io::Error::other("failed to move cursor to point"))?;
+        Ok(())
+    }
+
+    fn make_event_source() -> Result<CGEventSource, Error> {
+        CGEventSource::new(CGEventSourceStateID::CombinedSessionState)
+            .map_err(|_| Error::other("failed to create core graphics event source"))
+    }
+    /// Creates a core graphics event.
+    /// `CombinedSessionState` merges state from all event sources in the
+    /// current login session, which is what a remapper needs.
+    /// Note that the CFRelease function mentioned in the docs is automatically called when the
+    /// event is dropped, therefore we don't need to care about this ourselves.
+    fn make_event() -> Result<CGEvent, Error> {
+        let event_source = Self::make_event_source()?;
+        let event = CGEvent::new(event_source)
+            .map_err(|_| Error::other("failed to create core graphics event"))?;
+        Ok(event)
+    }
+
+    fn record_output_transition_after_write(&mut self, key: OsCode, value: KeyValue) {
+        match value {
+            KeyValue::Press | KeyValue::Repeat => {
+                self.output_pressed_since
+                    .entry(key)
+                    .or_insert_with(Instant::now);
+            }
+            KeyValue::Release => {
+                self.output_pressed_since.remove(&key);
+            }
+            KeyValue::Tap | KeyValue::WakeUp => {}
+        }
+    }
+
+    /// Applies a calculated mouse move to a CGPoint.
+    ///
+    /// This does _not_ move the mouse, it just mutates the point.
+    fn apply_calculated_move(mv: &CalculatedMouseMove, mouse_position: &mut CGPoint) {
+        match mv.direction {
+            MoveDirection::Up => mouse_position.y -= mv.distance as CGFloat,
+            MoveDirection::Down => mouse_position.y += mv.distance as CGFloat,
+            MoveDirection::Left => mouse_position.x -= mv.distance as CGFloat,
+            MoveDirection::Right => mouse_position.x += mv.distance as CGFloat,
+        }
+    }
+}
+
+/// Convert a `(CGEventType, button_number)` pair from a CGEventTap into a
+/// kanata `KeyEvent`. The button number field is only meaningful for
+/// `OtherMouseDown`/`OtherMouseUp` (2=Middle, 3=Back, 4=Forward); Left/Right
+/// are determined entirely by the event type.
+impl TryFrom<(CGEventType, i64)> for KeyEvent {
+    type Error = ();
+    fn try_from((event_type, button_number): (CGEventType, i64)) -> Result<Self, ()> {
+        use OsCode::*;
+        let (code, value) = match event_type {
+            CGEventType::LeftMouseDown => (BTN_LEFT, KeyValue::Press),
+            CGEventType::LeftMouseUp => (BTN_LEFT, KeyValue::Release),
+            CGEventType::RightMouseDown => (BTN_RIGHT, KeyValue::Press),
+            CGEventType::RightMouseUp => (BTN_RIGHT, KeyValue::Release),
+            CGEventType::OtherMouseDown | CGEventType::OtherMouseUp => {
+                let code = match button_number {
+                    2 => BTN_MIDDLE,
+                    3 => BTN_SIDE,
+                    4 => BTN_EXTRA,
+                    _ => return Err(()),
+                };
+                let value = if matches!(event_type, CGEventType::OtherMouseDown) {
+                    KeyValue::Press
+                } else {
+                    KeyValue::Release
+                };
+                (code, value)
+            }
+            _ => return Err(()),
+        };
+        Ok(KeyEvent::new(code, value))
+    }
+}
+
+/// Decode a `ScrollWheel` `CGEvent` into a kanata `KeyEvent`. A scroll event
+/// may carry both axes simultaneously (diagonal scroll on a trackpad); we
+/// pick the dominant axis with vertical winning ties, matching how Linux
+/// processes one `REL_WHEEL`/`REL_HWHEEL` at a time. The axis/sign convention
+/// mirrors `OsKbdOut::scroll`.
+fn scroll_event_to_key_event(event: &CGEvent) -> Option<KeyEvent> {
+    use OsCode::*;
+    let dy = event.get_integer_value_field(EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_1);
+    let dx = event.get_integer_value_field(EventField::SCROLL_WHEEL_EVENT_DELTA_AXIS_2);
+    let code = if dy.abs() >= dx.abs() {
+        match dy.signum() {
+            1 => MouseWheelDown,
+            -1 => MouseWheelUp,
+            _ => return None,
+        }
+    } else {
+        match dx.signum() {
+            1 => MouseWheelLeft,
+            -1 => MouseWheelRight,
+            _ => return None,
+        }
+    };
+    Some(KeyEvent::new(code, KeyValue::Tap))
+}
+
+/// Start a CGEventTap on a background thread to intercept mouse button events
+/// and (optionally) cursor movement events. macOS equivalent of the Windows
+/// mouse hook in `windows/llhook.rs` plus the cursor-movement branch of the
+/// Linux event loop.
+///
+/// Mapped buttons are suppressed and forwarded to the processing channel;
+/// unmapped buttons pass through. If `mouse_movement_key` is `Some`, every
+/// cursor movement (including drags) sends a synthetic `Tap` of the configured
+/// `OsCode` on the channel without suppressing the underlying movement event.
+///
+/// Only installed if the config has mouse buttons in defsrc OR
+/// `mouse-movement-key` is configured.
+///
+/// Requires Accessibility or Input Monitoring permission.
+pub fn start_mouse_listener(
+    tx: Sender<KeyEvent>,
+    mapped_keys: &MappedKeys,
+    mouse_movement_key: std::sync::Arc<parking_lot::Mutex<Option<OsCode>>>,
+) -> Option<std::thread::JoinHandle<()>> {
+    // Stash both unconditionally so the reload helper always has them, even
+    // if this initial call bails on the install gate. `OnceLock::set` is a
+    // no-op on subsequent calls — we rely on the single-process,
+    // single-Kanata assumption: the inner `parking_lot::Mutex` is shared with
+    // `do_live_reload`, so reloads mutate the *value*, never replace the
+    // Arc. The `debug_assert!` surfaces accidental violations in test builds.
+    let tx_was_unset = MOUSE_TAP_TX.set(tx.clone()).is_ok();
+    let _ = MOUSE_MOVEMENT_KEY.set(mouse_movement_key.clone());
+    debug_assert!(
+        tx_was_unset
+            || std::sync::Arc::ptr_eq(
+                MOUSE_MOVEMENT_KEY
+                    .get()
+                    .expect("set above or already present"),
+                &mouse_movement_key,
+            ),
+        "start_mouse_listener called twice with a different mouse_movement_key Arc — \
+         the previously stashed Arc would be silently kept"
+    );
+
+    let has_mouse_keys = MOUSE_OSCODES.iter().any(|c| mapped_keys.contains(c));
+    let has_movement_key = mouse_movement_key.lock().is_some();
+    if !has_mouse_keys && !has_movement_key {
+        log::info!(
+            "No mouse buttons/wheel in defsrc and no mouse-movement-key configured. \
+             Not installing mouse event tap."
+        );
+        return None;
+    }
+
+    // Claim the install slot atomically *before* spawning. Closes the race
+    // where a live reload could observe `MOUSE_TAP_INSTALLED == false` between
+    // the spawn here and the spawned thread's `tap.enable()`, and try to
+    // install a second tap. If the claim fails, an installation is already in
+    // progress (or completed) — the running tap reads both globals live, so
+    // this caller has nothing to do.
+    if MOUSE_TAP_INSTALLED
+        .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+        .is_err()
+    {
+        return None;
+    }
+
+    let spawn_result = std::thread::Builder::new()
+        .name("mouse-event-tap".into())
+        .spawn(move || {
+            let events_of_interest = vec![
+                CGEventType::LeftMouseDown,
+                CGEventType::LeftMouseUp,
+                CGEventType::RightMouseDown,
+                CGEventType::RightMouseUp,
+                CGEventType::OtherMouseDown,
+                CGEventType::OtherMouseUp,
+                CGEventType::ScrollWheel,
+                CGEventType::MouseMoved,
+                CGEventType::LeftMouseDragged,
+                CGEventType::RightMouseDragged,
+                CGEventType::OtherMouseDragged,
+            ];
+
+            // Tap at the *session* location, not HID. HID taps sit upstream of
+            // the window server and coalesce with raw HID delivery; on some
+            // Bluetooth mice this either freezes the cursor entirely
+            // (issue #739) or pins it to the screen edges because relative
+            // movement deltas race with the tap thread (issue #1636, Logitech
+            // M720 and friends). Session taps sit downstream of the window
+            // server and see post-acceleration button/wheel/movement events,
+            // which is everything kanata actually needs and does not interfere
+            // with cursor delivery. Note: *posting* synthetic mouse events
+            // still uses the HID location; that's unrelated and intentional.
+            let tap = match CGEventTap::new(
+                CGEventTapLocation::Session,
+                CGEventTapPlacement::HeadInsertEventTap,
+                CGEventTapOptions::Default,
+                events_of_interest,
+                // Callback receives &CGEvent; return Some(clone) to pass through,
+                // None to suppress the event.
+                move |_proxy, event_type, event| {
+                    // Cursor movement (incl. drags while a button is held).
+                    // Always pass through — never suppress, or the cursor freezes.
+                    if matches!(
+                        event_type,
+                        CGEventType::MouseMoved
+                            | CGEventType::LeftMouseDragged
+                            | CGEventType::RightMouseDragged
+                            | CGEventType::OtherMouseDragged
+                    ) {
+                        // The Arc is stashed before this tap is created, so
+                        // `get()` is `Some` in practice. Fall back to a plain
+                        // pass-through if not, rather than panicking on the
+                        // hot path.
+                        let mmk_slot = match MOUSE_MOVEMENT_KEY.get() {
+                            Some(slot) => slot,
+                            None => return Some(event.clone()),
+                        };
+                        if let Some(code) = *mmk_slot.lock() {
+                            let fake = KeyEvent::new(code, KeyValue::Tap);
+                            if let Err(e) = tx.try_send(fake) {
+                                // Drops are expected under high movement rates;
+                                // the user only needs one tap to refresh their
+                                // hold timer, so this is not user-visible.
+                                log::trace!("mouse tap (movement): drop synthetic tap: {e}");
+                            }
+                        }
+                        return Some(event.clone());
+                    }
+
+                    if matches!(event_type, CGEventType::ScrollWheel) {
+                        let Some(key_event) = scroll_event_to_key_event(event) else {
+                            return Some(event.clone());
+                        };
+                        if !crate::kanata::MAPPED_KEYS.lock().contains(&key_event.code) {
+                            return Some(event.clone());
+                        }
+                        log::debug!("mouse tap (wheel): {key_event:?}");
+                        if let Err(e) = tx.try_send(key_event) {
+                            log::warn!("mouse tap: failed to send wheel event: {e}");
+                            return Some(event.clone());
+                        }
+                        return None;
+                    }
+
+                    let button_number =
+                        event.get_integer_value_field(EventField::MOUSE_EVENT_BUTTON_NUMBER);
+                    let mut key_event = match KeyEvent::try_from((event_type, button_number)) {
+                        Ok(ev) => ev,
+                        Err(()) => return Some(event.clone()),
+                    };
+
+                    if !crate::kanata::MAPPED_KEYS.lock().contains(&key_event.code) {
+                        return Some(event.clone());
+                    }
+
+                    // Track pressed state to convert duplicate presses into repeats,
+                    // matching the keyboard event loop behavior.
+                    match key_event.value {
+                        KeyValue::Release => {
+                            crate::kanata::PRESSED_KEYS.lock().remove(&key_event.code);
+                        }
+                        KeyValue::Press => {
+                            let mut pressed_keys = crate::kanata::PRESSED_KEYS.lock();
+                            if pressed_keys.contains(&key_event.code) {
+                                key_event.value = KeyValue::Repeat;
+                            } else {
+                                pressed_keys.insert(key_event.code);
+                            }
+                        }
+                        _ => {}
+                    }
+
+                    log::debug!("mouse tap: {key_event:?}");
+
+                    if let Err(e) = tx.try_send(key_event) {
+                        log::warn!("mouse tap: failed to send event: {e}");
+                        return Some(event.clone());
+                    }
+
+                    // Suppress the original event so it doesn't reach the system.
+                    None
+                },
+            ) {
+                Ok(tap) => tap,
+                Err(()) => {
+                    log::error!(
+                        "Failed to create mouse event tap. \
+                         Ensure kanata has Accessibility or Input Monitoring permission \
+                         in System Settings > Privacy & Security."
+                    );
+                    // Release the install claim so a future live reload can
+                    // retry once the user grants permission.
+                    MOUSE_TAP_INSTALLED.store(false, Ordering::Release);
+                    return;
+                }
+            };
+
+            let Ok(loop_source) = tap.mach_port.create_runloop_source(0) else {
+                log::error!("failed to create CFRunLoop source for mouse event tap");
+                MOUSE_TAP_INSTALLED.store(false, Ordering::Release);
+                return;
+            };
+            // Safety: kCFRunLoopCommonModes is an extern static from CoreFoundation.
+            // Accessing it requires unsafe but is always valid in a running process.
+            let mode = unsafe { kCFRunLoopCommonModes };
+            CFRunLoop::get_current().add_source(&loop_source, mode);
+            tap.enable();
+            // MOUSE_TAP_INSTALLED was already set by the caller via
+            // compare_exchange before this thread was spawned.
+            log::info!("Mouse event tap installed and active.");
+            CFRunLoop::run_current();
+        });
+
+    match spawn_result {
+        Ok(handle) => Some(handle),
+        Err(e) => {
+            log::error!("failed to spawn mouse event tap thread: {e}");
+            MOUSE_TAP_INSTALLED.store(false, Ordering::Release);
+            None
+        }
+    }
+}
+
+/// Re-attempt installing the mouse event tap after a live reload. The running
+/// tap callback already reads `MAPPED_KEYS` and `MOUSE_MOVEMENT_KEY` live, so
+/// if the tap is already up there is nothing to do — but if a reload introduces
+/// the first mouse key in defsrc or the first `mouse-movement-key` value, the
+/// startup-time install gate may have skipped installation, and we need to
+/// install now.
+pub fn ensure_mouse_listener_installed_after_reload() {
+    if MOUSE_TAP_INSTALLED.load(Ordering::Acquire) {
+        // Existing tap reads both MAPPED_KEYS and MOUSE_MOVEMENT_KEY live.
+        return;
+    }
+    let Some(tx) = MOUSE_TAP_TX.get().cloned() else {
+        log::debug!("mouse tap reload hook: no tx stashed yet, skipping");
+        return;
+    };
+    let Some(mmk) = MOUSE_MOVEMENT_KEY.get().cloned() else {
+        log::debug!("mouse tap reload hook: no mouse_movement_key stashed yet, skipping");
+        return;
+    };
+    let mapped = crate::kanata::MAPPED_KEYS.lock();
+    let _ = start_mouse_listener(tx, &mapped, mmk);
+}
diff --git a/src/oskbd/mod.rs b/src/oskbd/mod.rs
index 092717cb4..afab7d66e 100644
--- a/src/oskbd/mod.rs
+++ b/src/oskbd/mod.rs
@@ -1,11 +1,172 @@
 //! Platform specific code for low level keyboard read/write.
 
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "android"))]
 mod linux;
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "android"))]
 pub use linux::*;
 
 #[cfg(target_os = "windows")]
 mod windows;
 #[cfg(target_os = "windows")]
 pub use windows::*;
+
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(target_os = "macos")]
+pub use macos::*;
+
+#[cfg(any(
+    all(
+        not(feature = "simulated_input"),
+        feature = "simulated_output",
+        not(feature = "passthru_ahk")
+    ),
+    all(
+        feature = "simulated_input",
+        not(feature = "simulated_output"),
+        not(feature = "passthru_ahk")
+    )
+))]
+mod simulated; // has KbdOut
+#[cfg(any(
+    all(
+        not(feature = "simulated_input"),
+        feature = "simulated_output",
+        not(feature = "passthru_ahk")
+    ),
+    all(
+        feature = "simulated_input",
+        not(feature = "simulated_output"),
+        not(feature = "passthru_ahk")
+    )
+))]
+pub use simulated::*;
+#[cfg(any(
+    all(feature = "simulated_input", feature = "simulated_output"),
+    all(
+        feature = "simulated_input",
+        feature = "simulated_output",
+        feature = "passthru_ahk"
+    ),
+))]
+mod sim_passthru; // has KbdOut
+#[cfg(any(
+    all(feature = "simulated_input", feature = "simulated_output"),
+    all(
+        feature = "simulated_input",
+        feature = "simulated_output",
+        feature = "passthru_ahk"
+    ),
+))]
+pub use sim_passthru::*;
+
+pub const HI_RES_SCROLL_UNITS_IN_LO_RES: u16 = 120;
+
+// ------------------ KeyValue --------------------
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum KeyValue {
+    Release = 0,
+    Press = 1,
+    Repeat = 2,
+    Tap,
+    WakeUp,
+}
+
+impl From<i32> for KeyValue {
+    fn from(item: i32) -> Self {
+        match item {
+            0 => Self::Release,
+            1 => Self::Press,
+            2 => Self::Repeat,
+            _ => unreachable!(),
+        }
+    }
+}
+
+impl From<bool> for KeyValue {
+    fn from(up: bool) -> Self {
+        match up {
+            true => Self::Release,
+            false => Self::Press,
+        }
+    }
+}
+
+impl From<KeyValue> for bool {
+    fn from(val: KeyValue) -> Self {
+        matches!(val, KeyValue::Release)
+    }
+}
+
+use kanata_parser::keys::OsCode;
+
+#[derive(Clone, Copy)]
+pub struct KeyEvent {
+    pub code: OsCode,
+    pub value: KeyValue,
+    #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+    device_id: Option<std::num::NonZeroU8>,
+}
+
+#[allow(dead_code, unused)]
+impl KeyEvent {
+    pub fn new(code: OsCode, value: KeyValue) -> Self {
+        Self {
+            code,
+            value,
+            #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+            device_id: None,
+        }
+    }
+
+    /// Returns the device ID that produced this event, if known.
+    /// Always returns `None` on Windows LLHOOK (which cannot distinguish devices).
+    pub fn device_id(&self) -> Option<std::num::NonZeroU8> {
+        #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+        {
+            self.device_id
+        }
+        #[cfg(all(target_os = "windows", not(feature = "interception_driver")))]
+        {
+            None
+        }
+    }
+
+    /// Sets the device ID for this event.
+    /// No-op on Windows LLHOOK.
+    pub fn set_device_id(&mut self, id: Option<std::num::NonZeroU8>) {
+        #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+        {
+            self.device_id = id;
+        }
+    }
+}
+
+use core::fmt;
+impl fmt::Display for KeyEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use kanata_keyberon::key_code::KeyCode;
+        let direction = match self.value {
+            KeyValue::Press => "↓",
+            KeyValue::Release => "↑",
+            KeyValue::Repeat => "⟳",
+            KeyValue::Tap => "↕",
+            KeyValue::WakeUp => "!",
+        };
+        let key_name = KeyCode::from(self.code);
+        write!(f, "{direction}{key_name:?}")
+    }
+}
+
+impl fmt::Debug for KeyEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("KeyEvent")
+            .field(
+                "code",
+                &format_args!("{:?} ({})", self.code, self.code.as_u16()),
+            )
+            .field("value", &self.value)
+            .finish()
+    }
+}
diff --git a/src/oskbd/sim_passthru.rs b/src/oskbd/sim_passthru.rs
new file mode 100644
index 000000000..25f30eceb
--- /dev/null
+++ b/src/oskbd/sim_passthru.rs
@@ -0,0 +1,193 @@
+//! Redirects output to the function provided by the entity supplying simulated input (e.g., AHK)
+// todo: allow sharing numpad status to differentiate between vk enter and vk numpad enter
+// todo: only press/release_key is implemented
+use super::*;
+use anyhow::Result;
+use log::*;
+
+use crate::kanata::CalculatedMouseMove;
+use kanata_parser::custom_action::*;
+
+use std::io;
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+use std::fmt;
+
+use std::sync::Arc;
+use std::sync::OnceLock;
+type CbOutEvFn = dyn Fn(i64, i64, i64) -> i64 + Send + Sync + 'static; // Rust wrapper func around external callback (transmuted into this) Ahk accept only i64 arguments (vk,sc,up)
+pub struct FnOutEvWrapper {
+    pub cb: Arc<CbOutEvFn>,
+} // wrapper struct to store our callback in a thread-shareable manner
+pub static OUTEVWRAP: OnceLock<FnOutEvWrapper> = OnceLock::new(); // ensure that our wrapper struct is created once (thread-safe)
+
+use std::sync::mpsc::{SendError, Sender as ASender};
+/// Handle for writing keys to the simulated input provider.
+pub struct KbdOut {
+    pub tx_kout: Option<ASender<InputEvent>>,
+}
+
+use std::io::{Error as IoErr, ErrorKind::NotConnected};
+impl KbdOut {
+    #[cfg(not(any(target_os = "linux", target_os = "android")))]
+    pub fn new() -> Result<Self, io::Error> {
+        Ok(Self { tx_kout: None })
+    }
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub fn new(
+        _s: &Option<String>,
+        _tp: bool,
+        _name: &str,
+        _bustype: evdev::BusType,
+    ) -> Result<Self, io::Error> {
+        Ok(Self { tx_kout: None })
+    }
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub fn write_raw(&mut self, event: InputEvent) -> Result<(), io::Error> {
+        trace!("out-raw:{event:?}");
+        Ok(())
+    }
+    pub fn write(&mut self, event: InputEvent) -> Result<(), io::Error> {
+        trace!("out:{event}");
+        if let Some(tx_kout) = &self.tx_kout {
+            // Send key event msg → main thread so it can be polled to try receiving it after processing external input events
+            match tx_kout.send(event) {
+                // send won't block for an async channel
+                Ok(res) => {
+                    debug!(
+                        "✓ tx_kout → rx_kout@key_out(dll) ‘{event}’ from send_out_ev_msg@sim_passthru(oskbd)"
+                    );
+                    return Ok(res);
+                }
+                Err(SendError(event)) => {
+                    error!(
+                        "✗ tx_kout → rx_kout@key_out(dll) ‘{event}’ from send_out_ev_msg@sim_passthru(oskbd)"
+                    );
+                    return Err(IoErr::new(
+                        NotConnected,
+                        format!("Failed sending sending {event}"),
+                    ));
+                }
+            }
+        } else {
+            debug!("✗ tx_kout doesn't exist");
+        }
+        Ok(())
+    }
+    pub fn output_ready(&self) -> bool {
+        true
+    }
+    pub fn wait_until_ready(&self, _timeout: Option<std::time::Duration>) -> bool {
+        true
+    }
+    pub fn write_key(&mut self, key: OsCode, value: KeyValue) -> Result<(), io::Error> {
+        let key_ev = KeyEvent::new(key, value);
+        let event = {
+            #[cfg(target_os = "macos")]
+            {
+                key_ev.try_into().unwrap()
+            }
+            #[cfg(not(target_os = "macos"))]
+            {
+                key_ev.into()
+            }
+        };
+        self.write(event)
+    }
+    pub fn write_code(&mut self, code: u32, value: KeyValue) -> Result<(), io::Error> {
+        trace!("out-code:{code};{value:?}");
+        Ok(())
+    }
+    pub fn press_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.write_key(key, KeyValue::Press)
+    }
+    pub fn release_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.write_key(key, KeyValue::Release)
+    }
+    pub fn release_tracked_output_keys(&mut self, _reason: &str) {}
+    pub fn send_unicode(&mut self, c: char) -> Result<(), io::Error> {
+        trace!("outU:{c}");
+        Ok(())
+    }
+    pub fn click_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        trace!("out🖰:↓{btn:?}");
+        Ok(())
+    }
+    pub fn release_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        trace!("out🖰:↑{btn:?}");
+        Ok(())
+    }
+    pub fn scroll(&mut self, direction: MWheelDirection, distance: u16) -> Result<(), io::Error> {
+        trace!("scroll:{direction:?},{distance:?}");
+        Ok(())
+    }
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        let (direction, distance) = (mv.direction, mv.distance);
+        trace!("out🖰:move {direction:?},{distance:?}");
+        Ok(())
+    }
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        for mv in moves {
+            let (direction, distance) = (&mv.direction, &mv.distance);
+            trace!("out🖰:move {direction:?},{distance:?}");
+        }
+        Ok(())
+    }
+    pub fn set_mouse(&mut self, x: u16, y: u16) -> Result<(), io::Error> {
+        log::info!("out🖰:@{x},{y}");
+        Ok(())
+    }
+    pub fn tick(&mut self) {}
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+#[derive(Debug, Clone, Copy)]
+pub struct InputEvent {
+    pub code: u32,
+
+    /// Key was released
+    pub up: bool,
+}
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use kanata_keyberon::key_code::KeyCode;
+        let direction = if self.up { "↑" } else { "↓" };
+        let key_name = KeyCode::from(OsCode::from(self.code));
+        write!(f, "{}{:?}", direction, key_name)
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl InputEvent {
+    pub fn from_oscode(code: OsCode, val: KeyValue) -> Self {
+        Self {
+            code: code.into(),
+            up: val.into(),
+        }
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl TryFrom<InputEvent> for KeyEvent {
+    type Error = ();
+    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
+        Ok(Self::new(
+            OsCode::from_u16(item.code as u16).ok_or(())?,
+            match item.up {
+                true => KeyValue::Release,
+                false => KeyValue::Press,
+            },
+        ))
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl From<KeyEvent> for InputEvent {
+    fn from(item: KeyEvent) -> Self {
+        Self {
+            code: item.code.into(),
+            up: item.value.into(),
+        }
+    }
+}
diff --git a/src/oskbd/simulated.rs b/src/oskbd/simulated.rs
new file mode 100644
index 000000000..51b6bd082
--- /dev/null
+++ b/src/oskbd/simulated.rs
@@ -0,0 +1,512 @@
+//! Output that just prints text to stdout instead of actually doing anything OS-related.
+//! See <../../docs/simulated_output/sim_out.txt> for an example output.
+use indoc::formatdoc;
+use std::ffi::{OsStr, OsString};
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+pub fn concat_os_str2(a: &OsStr, b: &OsStr) -> OsString {
+    let mut ret = OsString::with_capacity(a.len() + b.len()); // allocate once
+    ret.push(a);
+    ret.push(b); // doesn't allocate
+    ret
+}
+fn append_file_name(path: impl AsRef<Path>, appendix: impl AsRef<OsStr>) -> PathBuf {
+    let path = path.as_ref();
+    let mut result = path.to_owned();
+    let stem_in = path.file_stem().unwrap_or(OsStr::new(""));
+    let stem_out = concat_os_str2(stem_in, OsStr::new(&appendix));
+    result.set_file_name(stem_out);
+    if let Some(ext) = path.extension() {
+        result.set_extension(ext);
+    }
+    result
+}
+
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub enum LogFmtT {
+    InKeyUp,
+    InKeyDown,
+    InKeyRep,
+    InTick,
+    KeyUp,
+    KeyDown,
+    Tick,
+    MouseUp,
+    MouseDown,
+    MouseMove,
+    Unicode,
+    Code,
+    RawUp,
+    RawDown,
+}
+
+pub struct LogFmt {
+    ticks: u64,
+    //In       	//
+    in_time: String,
+    in_key_up: String,
+    in_key_down: String,
+    in_key_rep: String,
+    in_combo: String,
+    //Out      	//
+    time: String,
+    key_up: String,
+    key_down: String,
+    raw_up: String,
+    raw_down: String,
+    combo: String,
+    mouse_up: String,
+    mouse_down: String,
+    mouse_move: String,
+    unicode: String,
+    code: String,
+}
+impl Default for LogFmt {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+impl LogFmt {
+    pub fn new() -> Self {
+        Self {
+            ticks: 0,
+            //In       	//
+            in_time: String::new(),
+            in_key_up: String::new(),
+            in_key_down: String::new(),
+            in_key_rep: String::new(),
+            in_combo: String::new(),
+            //Out      	//
+            time: String::new(),
+            key_up: String::new(),
+            key_down: String::new(),
+            raw_up: String::new(),
+            raw_down: String::new(),
+            mouse_up: String::new(),
+            mouse_down: String::new(),
+            mouse_move: String::new(),
+            unicode: String::new(),
+            code: String::new(),
+            combo: String::new(),
+        }
+    }
+    pub fn fmt(&mut self, key: LogFmtT, value: String) {
+        let mut pad = value.len();
+        let mut time = "".to_string();
+        if self.ticks > 0 {
+            pad = std::cmp::max(value.len(), self.ticks.to_string().len()); // add extra padding if
+            // event tick is wider
+            time = format!("  {: <pad$}", self.ticks);
+            self.ticks = 0;
+        }
+        let blank = format!("  {: <pad$}", ""); //+␠ to allow combo log indicator
+        let val = format!("  {value: <pad$}");
+        self.in_time += if key == LogFmtT::InTick {
+            self.combo += &blank;
+            self.in_combo += &format!(" 🕐{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.in_key_up += if key == LogFmtT::InKeyUp {
+            self.combo += &blank;
+            self.in_combo += &format!(" ↑{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.in_key_down += if key == LogFmtT::InKeyDown {
+            self.combo += &blank;
+            self.in_combo += &format!(" ↓{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.in_key_rep += if key == LogFmtT::InKeyRep {
+            self.combo += &blank;
+            self.in_combo += &format!(" ⟳{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.time += if !time.is_empty() { &time } else { &blank };
+        self.key_up += if key == LogFmtT::KeyUp {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↑{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.key_down += if key == LogFmtT::KeyDown {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↓{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.mouse_up += if key == LogFmtT::MouseUp {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↑{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.mouse_down += if key == LogFmtT::MouseDown {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↓{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.mouse_move += if key == LogFmtT::MouseMove {
+            self.in_combo += &blank;
+            self.combo += &val;
+            &val
+        } else {
+            &blank
+        };
+        self.raw_up += if key == LogFmtT::RawUp {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↑{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.raw_down += if key == LogFmtT::RawDown {
+            self.in_combo += &blank;
+            self.combo += &format!(" ↓{value: <pad$}");
+            &val
+        } else {
+            &blank
+        };
+        self.unicode += if key == LogFmtT::Unicode {
+            self.in_combo += &blank;
+            self.combo += &val;
+            &val
+        } else {
+            &blank
+        };
+        self.code += if key == LogFmtT::Code {
+            self.in_combo += &blank;
+            self.combo += &val;
+            &val
+        } else {
+            &blank
+        };
+    }
+
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub fn write_raw(&mut self, event: InputEvent) {
+        let key_name = KeyCode::from(OsCode::from(event.code));
+        if event.up {
+            self.fmt(LogFmtT::RawUp, key_name.to_string())
+        } else {
+            self.fmt(LogFmtT::RawDown, key_name.to_string())
+        }
+    }
+    pub fn in_tick(&mut self, t: u128) {
+        self.fmt(LogFmtT::InTick, t.to_string())
+    }
+    pub fn in_press_key(&mut self, key: OsCode) {
+        self.fmt(LogFmtT::InKeyDown, KeyCode::from(key).to_string())
+    }
+    pub fn in_release_key(&mut self, key: OsCode) {
+        self.fmt(LogFmtT::InKeyUp, KeyCode::from(key).to_string())
+    }
+    pub fn in_repeat_key(&mut self, key: OsCode) {
+        self.fmt(LogFmtT::InKeyRep, KeyCode::from(key).to_string())
+    }
+    pub fn press_key(&mut self, key: OsCode) {
+        self.fmt(LogFmtT::KeyDown, KeyCode::from(key).to_string())
+    }
+    pub fn release_key(&mut self, key: OsCode) {
+        self.fmt(LogFmtT::KeyUp, KeyCode::from(key).to_string())
+    }
+    pub fn send_unicode(&mut self, c: char) {
+        self.fmt(LogFmtT::Unicode, c.to_string())
+    }
+    pub fn click_btn(&mut self, btn: Btn) {
+        self.fmt(LogFmtT::MouseDown, btn.to_string())
+    }
+    pub fn release_btn(&mut self, btn: Btn) {
+        self.fmt(LogFmtT::MouseUp, btn.to_string())
+    }
+    pub fn set_mouse(&mut self, x: u16, y: u16) {
+        self.fmt(LogFmtT::MouseMove, format!("@{x},{y}"))
+    }
+    pub fn scroll(&mut self, dir: MWheelDirection, dist: u16) {
+        self.fmt(LogFmtT::MouseMove, format!("{dir}{dist}"))
+    }
+    pub fn move_mouse(&mut self, dir: MoveDirection, dist: u16) {
+        self.fmt(LogFmtT::MouseMove, format!("{dir}{dist}"))
+    }
+    pub fn write_code(&mut self, code: u32, value: KeyValue) {
+        self.fmt(LogFmtT::Code, format!("{code};{value:?}"))
+    }
+
+    pub fn end(&self, in_path: &PathBuf, appendix: Option<String>) {
+        let pad = self.combo.len().saturating_sub(3);
+        let table_out = formatdoc!(
+            "🕐Δms│{}
+          In───┼{:─<pad$}
+           k↑  │{}
+           k↓  │{}
+           k⟳  │{}
+          Σin  │{}
+          Out──┼{:─<pad$}
+           k↑  │{}
+           k↓  │{}
+           🖰↑  │{}
+           🖰↓  │{}
+           🖰   │{}
+           🔣  │{}
+           code│{}
+           raw↑│{}
+           raw↓│{}
+          Σout │{}
+          ",
+            self.time,
+            "",
+            self.in_key_up,
+            self.in_key_down,
+            self.in_key_rep,
+            self.in_combo,
+            "",
+            self.key_up,
+            self.key_down,
+            self.mouse_up,
+            self.mouse_down,
+            self.mouse_move,
+            self.unicode,
+            self.code,
+            self.raw_up,
+            self.raw_down,
+            self.combo
+        );
+        eprintln!("{table_out}");
+        if let Some(appendix_s) = appendix {
+            let out_path = append_file_name(in_path, appendix_s);
+            let out_path_s = out_path.display();
+            let mut out_file = match File::create(&out_path) {
+                Err(e) => panic!("✗ Couldn't create {out_path_s}: {e}"),
+                Ok(out_file) => out_file,
+            };
+            match out_file.write_all(table_out.as_bytes()) {
+                Err(e) => panic!("✗ Couldn't write to {out_path_s}: {e}"),
+                Ok(_) => eprintln!("Saved output → {out_path_s}"),
+            }
+        }
+    }
+}
+
+use super::*;
+
+use crate::kanata::CalculatedMouseMove;
+use kanata_parser::custom_action::*;
+
+use std::io;
+
+use kanata_keyberon::key_code::KeyCode;
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+use std::fmt;
+
+pub struct Outputs {
+    pub events: Vec<String>,
+    ticks: u64,
+}
+
+impl Outputs {
+    fn new() -> Self {
+        Self {
+            events: vec![],
+            ticks: 0,
+        }
+    }
+
+    fn push(&mut self, event: impl AsRef<str>) {
+        if self.ticks > 0 {
+            self.events.push(format!("t:{}ms", self.ticks));
+        }
+        self.events.push(event.as_ref().to_string());
+        self.ticks = 0;
+    }
+}
+
+/// Handle for writing keys to the OS.
+pub struct KbdOut {
+    pub log: LogFmt,
+    pub outputs: Outputs,
+}
+
+impl KbdOut {
+    fn new_actual() -> Result<Self, io::Error> {
+        Ok(Self {
+            log: LogFmt::new(),
+            outputs: Outputs::new(),
+        })
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "android")))]
+    pub fn new() -> Result<Self, io::Error> {
+        Self::new_actual()
+    }
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub fn new(
+        _s: &Option<String>,
+        _tp: bool,
+        _name: &str,
+        _bustype: evdev::BusType,
+    ) -> Result<Self, io::Error> {
+        Self::new_actual()
+    }
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    pub fn write_raw(&mut self, event: InputEvent) -> Result<(), io::Error> {
+        self.log.write_raw(event);
+        self.outputs.push(format!("out-raw:{event:?}"));
+        Ok(())
+    }
+    pub fn write(&mut self, event: InputEvent) -> Result<(), io::Error> {
+        self.outputs.push(format!("out:{event}"));
+        Ok(())
+    }
+    pub fn output_ready(&self) -> bool {
+        true
+    }
+    pub fn wait_until_ready(&self, _timeout: Option<std::time::Duration>) -> bool {
+        true
+    }
+    pub fn write_key(&mut self, key: OsCode, value: KeyValue) -> Result<(), io::Error> {
+        let key_ev = KeyEvent::new(key, value);
+        let event = {
+            #[cfg(target_os = "macos")]
+            {
+                key_ev.try_into().unwrap()
+            }
+            #[cfg(not(target_os = "macos"))]
+            {
+                key_ev.into()
+            }
+        };
+        self.write(event)
+    }
+    pub fn write_code(&mut self, code: u32, value: KeyValue) -> Result<(), io::Error> {
+        self.log.write_code(code, value);
+        self.outputs.push(format!("out-code:{code};{value:?}"));
+        Ok(())
+    }
+    pub fn press_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.log.press_key(key);
+        self.write_key(key, KeyValue::Press)
+    }
+    pub fn release_key(&mut self, key: OsCode) -> Result<(), io::Error> {
+        self.log.release_key(key);
+        self.write_key(key, KeyValue::Release)
+    }
+    pub fn release_tracked_output_keys(&mut self, _reason: &str) {}
+    pub fn send_unicode(&mut self, c: char) -> Result<(), io::Error> {
+        self.log.send_unicode(c);
+        self.outputs.push(format!("outU:{c}"));
+        Ok(())
+    }
+    pub fn click_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        self.log.click_btn(btn);
+        self.outputs.push(format!("out🖰:↓{btn:?}"));
+        Ok(())
+    }
+    pub fn release_btn(&mut self, btn: Btn) -> Result<(), io::Error> {
+        self.log.release_btn(btn);
+        self.outputs.push(format!("out🖰:↑{btn:?}"));
+        Ok(())
+    }
+    pub fn scroll(&mut self, direction: MWheelDirection, distance: u16) -> Result<(), io::Error> {
+        self.log.scroll(direction, distance);
+        self.outputs
+            .push(format!("scroll:{direction:?},{distance:?}"));
+        Ok(())
+    }
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        let (direction, distance) = (mv.direction, mv.distance);
+        self.log.move_mouse(direction, distance);
+        self.outputs
+            .push(format!("out🖰:move {direction:?},{distance:?}"));
+        Ok(())
+    }
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        for mv in moves {
+            let (direction, distance) = (&mv.direction, &mv.distance);
+            self.log.move_mouse(*direction, *distance);
+            self.outputs
+                .push(format!("out🖰:move {direction:?},{distance:?}"));
+        }
+        Ok(())
+    }
+    pub fn set_mouse(&mut self, x: u16, y: u16) -> Result<(), io::Error> {
+        self.log.set_mouse(x, y);
+        log::info!("out🖰:@{x},{y}");
+        Ok(())
+    }
+    pub fn tick(&mut self) {
+        self.outputs.ticks += 1;
+        self.log.ticks += 1;
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+#[derive(Debug, Clone, Copy)]
+pub struct InputEvent {
+    pub code: u32,
+    /// Key was released
+    pub up: bool,
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let direction = if self.up { "↑" } else { "↓" };
+        let key_name = KeyCode::from(OsCode::from(self.code));
+        write!(f, "{direction}{key_name:?}")
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl InputEvent {
+    pub fn from_oscode(code: OsCode, val: KeyValue) -> Self {
+        Self {
+            code: code.into(),
+            up: val.into(),
+        }
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl TryFrom<InputEvent> for KeyEvent {
+    type Error = ();
+    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
+        Ok(Self::new(
+            OsCode::from_u16(item.code as u16).ok_or(())?,
+            match item.up {
+                true => KeyValue::Release,
+                false => KeyValue::Press,
+            },
+        ))
+    }
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+impl From<KeyEvent> for InputEvent {
+    fn from(item: KeyEvent) -> Self {
+        Self {
+            code: item.code.into(),
+            up: item.value.into(),
+        }
+    }
+}
+
+#[cfg(all(target_os = "windows", feature = "interception_driver"))]
+impl From<KeyEvent> for InputEvent {
+    fn from(_item: KeyEvent) -> Self {
+        unimplemented!()
+    }
+}
diff --git a/src/oskbd/windows/exthook_os.rs b/src/oskbd/windows/exthook_os.rs
new file mode 100644
index 000000000..65c4a62ed
--- /dev/null
+++ b/src/oskbd/windows/exthook_os.rs
@@ -0,0 +1,99 @@
+//! A function listener for keyboard input events replacing Windows keyboard hook API
+
+use core::fmt;
+use once_cell::sync::Lazy;
+use parking_lot::Mutex;
+
+use winapi::ctypes::*;
+use winapi::um::winuser::*;
+
+use crate::oskbd::{KeyEvent, KeyValue};
+use kanata_keyberon::key_code::KeyCode;
+
+use kanata_parser::keys::*;
+
+pub const LLHOOK_IDLE_TIME_SECS_CLEAR_INPUTS: u64 = 60;
+
+type HookFn = dyn FnMut(InputEvent) -> bool + Send + Sync + 'static;
+
+pub static HOOK_CB: Lazy<Mutex<Option<Box<HookFn>>>> = Lazy::new(|| Mutex::new(None)); // store thread-safe hook callback with a mutex (can be called from an external process)
+
+pub struct KeyboardHook {} // reusing hook type for our listener
+impl KeyboardHook {
+    /// Sets input callback (panics if already registered)
+    pub fn set_input_cb(
+        callback: impl FnMut(InputEvent) -> bool + Send + Sync + 'static,
+    ) -> KeyboardHook {
+        let mut cb_opt = HOOK_CB.lock();
+        assert!(
+            cb_opt.take().is_none(),
+            "Only 1 external listener is allowed!"
+        );
+        *cb_opt = Some(Box::new(callback));
+        KeyboardHook {}
+    }
+}
+#[cfg(not(feature = "passthru_ahk"))] // unused KeyboardHook will be dropped, breaking our hook, disable it
+impl Drop for KeyboardHook {
+    fn drop(&mut self) {
+        let mut cb_opt = HOOK_CB.lock();
+        cb_opt.take();
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct InputEvent {
+    // Key event received by the low level keyboard hook.
+    pub code: u32,
+    pub up: bool, /*Key was released*/
+}
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let direction = if self.up { "↑" } else { "↓" };
+        let key_name = KeyCode::from(OsCode::from(self.code));
+        write!(f, "{direction}{key_name:?}")
+    }
+}
+impl InputEvent {
+    pub fn from_vk_sc(vk: c_uint, sc: c_uint, up: c_int) -> Self {
+        let code = if vk == (VK_RETURN as u32) {
+            // todo: do a proper check for numpad enter, maybe 0x11c isn't universal
+            match sc {
+                0x11C => u32::from(VK_KPENTER_FAKE),
+                _ => VK_RETURN as u32,
+            }
+        } else {
+            vk
+        };
+        Self {
+            code,
+            up: (up != 0),
+        }
+    }
+    pub fn from_oscode(code: OsCode, val: KeyValue) -> Self {
+        Self {
+            code: code.into(),
+            up: val.into(),
+        }
+    }
+}
+impl TryFrom<InputEvent> for KeyEvent {
+    type Error = ();
+    fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
+        Ok(Self::new(
+            OsCode::from_u16(item.code as u16).ok_or(())?,
+            match item.up {
+                true => KeyValue::Release,
+                false => KeyValue::Press,
+            },
+        ))
+    }
+}
+impl From<KeyEvent> for InputEvent {
+    fn from(item: KeyEvent) -> Self {
+        Self {
+            code: item.code.into(),
+            up: item.value.into(),
+        }
+    }
+}
diff --git a/src/oskbd/windows/interception.rs b/src/oskbd/windows/interception.rs
index 87c254ec8..4930c08db 100644
--- a/src/oskbd/windows/interception.rs
+++ b/src/oskbd/windows/interception.rs
@@ -2,27 +2,43 @@
 
 use std::io;
 
-use kanata_interception::{Interception, KeyState, MouseFlags, MouseState, Stroke};
+use kanata_interception::{Interception, KeyState, MouseFlags, MouseState, ScanCode, Stroke};
 
+use super::OsCodeWrapper;
+use crate::kanata::CalculatedMouseMove;
+use crate::oskbd::KeyValue;
 use kanata_parser::custom_action::*;
 use kanata_parser::keys::*;
 
-use super::OsCodeWrapper;
-
 /// Key event received by the low level keyboard hook.
 #[derive(Debug, Clone, Copy)]
 pub struct InputEvent(pub Stroke);
 
+use std::fmt;
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
 impl InputEvent {
     fn from_oscode(code: OsCode, val: KeyValue) -> Self {
-        let mut stroke =
-            Stroke::try_from(OsCodeWrapper(code)).expect("kanata only sends mapped `OsCode`s");
+        let mut stroke = Stroke::try_from(OsCodeWrapper(code)).unwrap_or_else(|_| {
+            log::error!("Trying to send unmapped oscode '{code:?}', sending esc instead");
+            Stroke::Keyboard {
+                code: ScanCode::Esc,
+                state: KeyState::empty(),
+                information: 0,
+            }
+        });
         match &mut stroke {
             Stroke::Keyboard { state, .. } => {
                 state.set(
                     match val {
                         KeyValue::Press | KeyValue::Repeat => KeyState::DOWN,
                         KeyValue::Release => KeyState::UP,
+                        KeyValue::Tap => panic!("invalid value attempted to be sent"),
+                        KeyValue::WakeUp => panic!("invalid value attempted to be sent"),
                     },
                     true,
                 );
@@ -41,10 +57,10 @@ impl InputEvent {
                 (Btn::Right, false) => MouseState::RIGHT_BUTTON_DOWN,
                 (Btn::Mid, true) => MouseState::MIDDLE_BUTTON_UP,
                 (Btn::Mid, false) => MouseState::MIDDLE_BUTTON_DOWN,
-                (Btn::Backward, true) => MouseState::BUTTON_4_DOWN,
-                (Btn::Backward, false) => MouseState::BUTTON_4_UP,
-                (Btn::Forward, true) => MouseState::BUTTON_5_DOWN,
-                (Btn::Forward, false) => MouseState::BUTTON_5_UP,
+                (Btn::Backward, true) => MouseState::BUTTON_4_UP,
+                (Btn::Backward, false) => MouseState::BUTTON_4_DOWN,
+                (Btn::Forward, true) => MouseState::BUTTON_5_UP,
+                (Btn::Forward, false) => MouseState::BUTTON_5_DOWN,
             },
             flags: MouseFlags::empty(),
             rolling: 0,
@@ -94,6 +110,29 @@ impl InputEvent {
         })
     }
 
+    fn from_mouse_move_many(moves: &[CalculatedMouseMove]) -> Self {
+        let mut x_acc = 0;
+        let mut y_acc = 0;
+        for mov in moves {
+            let acc_change = match mov.direction {
+                MoveDirection::Up => (0, -i32::from(mov.distance)),
+                MoveDirection::Down => (0, i32::from(mov.distance)),
+                MoveDirection::Left => (-i32::from(mov.distance), 0),
+                MoveDirection::Right => (i32::from(mov.distance), 0),
+            };
+            x_acc += acc_change.0;
+            y_acc += acc_change.1;
+        }
+        Self(Stroke::Mouse {
+            state: MouseState::MOVE,
+            flags: MouseFlags::empty(),
+            rolling: 0,
+            x: x_acc,
+            y: y_acc,
+            information: 0,
+        })
+    }
+
     fn from_mouse_set(x: u16, y: u16) -> Self {
         Self(Stroke::Mouse {
             state: MouseState::MOVE,
@@ -110,6 +149,7 @@ thread_local! {
     static INTRCPTN: Interception = Interception::new().expect("interception driver should init: have you completed the interception driver installation?");
 }
 
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 /// Handle for writing keys to the OS.
 pub struct KbdOut {}
 
@@ -131,6 +171,7 @@ fn write_interception(event: InputEvent) {
     })
 }
 
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 impl KbdOut {
     pub fn new() -> Result<Self, io::Error> {
         Ok(Self {})
@@ -141,6 +182,10 @@ impl KbdOut {
         Ok(())
     }
 
+    pub fn write_code_raw(&mut self, code: u16, value: KeyValue) -> Result<(), io::Error> {
+        super::write_code_raw(code, value)
+    }
+
     pub fn write_code(&mut self, code: u32, value: KeyValue) -> Result<(), io::Error> {
         super::write_code(code as u16, value)
     }
@@ -183,8 +228,13 @@ impl KbdOut {
         Ok(())
     }
 
-    pub fn move_mouse(&mut self, direction: MoveDirection, distance: u16) -> Result<(), io::Error> {
-        write_interception(InputEvent::from_mouse_move(direction, distance));
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        write_interception(InputEvent::from_mouse_move(mv.direction, mv.distance));
+        Ok(())
+    }
+
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        write_interception(InputEvent::from_mouse_move_many(moves));
         Ok(())
     }
 
diff --git a/src/oskbd/windows/interception_convert.rs b/src/oskbd/windows/interception_convert.rs
index 17c06eecc..791bb9b44 100644
--- a/src/oskbd/windows/interception_convert.rs
+++ b/src/oskbd/windows/interception_convert.rs
@@ -197,172 +197,8 @@ impl TryFrom<Stroke> for OsCodeWrapper {
         Ok(match item {
             Stroke::Keyboard { code, state, .. } => {
                 let code = match (state.contains(KeyState::E0), state.contains(KeyState::E1)) {
-                    (false, false) => {
-                        match code {
-                            ScanCode::Esc => OsCode::KEY_ESC,
-                            ScanCode::Num1 => OsCode::KEY_1,
-                            ScanCode::Num2 => OsCode::KEY_2,
-                            ScanCode::Num3 => OsCode::KEY_3,
-                            ScanCode::Num4 => OsCode::KEY_4,
-                            ScanCode::Num5 => OsCode::KEY_5,
-                            ScanCode::Num6 => OsCode::KEY_6,
-                            ScanCode::Num7 => OsCode::KEY_7,
-                            ScanCode::Num8 => OsCode::KEY_8,
-                            ScanCode::Num9 => OsCode::KEY_9,
-                            ScanCode::Num0 => OsCode::KEY_0,
-                            ScanCode::Minus => OsCode::KEY_MINUS,
-                            ScanCode::Equals => OsCode::KEY_EQUAL,
-                            ScanCode::Backspace => OsCode::KEY_BACKSPACE,
-                            ScanCode::Tab => OsCode::KEY_TAB,
-                            ScanCode::Q => OsCode::KEY_Q,
-                            ScanCode::W => OsCode::KEY_W,
-                            ScanCode::E => OsCode::KEY_E,
-                            ScanCode::R => OsCode::KEY_R,
-                            ScanCode::T => OsCode::KEY_T,
-                            ScanCode::Y => OsCode::KEY_Y,
-                            ScanCode::U => OsCode::KEY_U,
-                            ScanCode::I => OsCode::KEY_I,
-                            ScanCode::O => OsCode::KEY_O,
-                            ScanCode::P => OsCode::KEY_P,
-                            ScanCode::LeftBracket => OsCode::KEY_LEFTBRACE,
-                            ScanCode::RightBracket => OsCode::KEY_RIGHTBRACE,
-                            ScanCode::Enter => OsCode::KEY_ENTER,
-                            ScanCode::LeftControl => OsCode::KEY_LEFTCTRL,
-                            ScanCode::A => OsCode::KEY_A,
-                            ScanCode::S => OsCode::KEY_S,
-                            ScanCode::D => OsCode::KEY_D,
-                            ScanCode::F => OsCode::KEY_F,
-                            ScanCode::G => OsCode::KEY_G,
-                            ScanCode::H => OsCode::KEY_H,
-                            ScanCode::J => OsCode::KEY_J,
-                            ScanCode::K => OsCode::KEY_K,
-                            ScanCode::L => OsCode::KEY_L,
-                            ScanCode::SemiColon => OsCode::KEY_SEMICOLON,
-                            ScanCode::Apostrophe => OsCode::KEY_APOSTROPHE,
-                            ScanCode::Grave => OsCode::KEY_GRAVE,
-                            ScanCode::LeftShift => OsCode::KEY_LEFTSHIFT,
-                            ScanCode::BackSlash => OsCode::KEY_BACKSLASH,
-                            ScanCode::Z => OsCode::KEY_Z,
-                            ScanCode::X => OsCode::KEY_X,
-                            ScanCode::C => OsCode::KEY_C,
-                            ScanCode::V => OsCode::KEY_V,
-                            ScanCode::B => OsCode::KEY_B,
-                            ScanCode::N => OsCode::KEY_N,
-                            ScanCode::M => OsCode::KEY_M,
-                            ScanCode::Comma => OsCode::KEY_COMMA,
-                            ScanCode::Period => OsCode::KEY_DOT,
-                            ScanCode::Slash => OsCode::KEY_SLASH,
-                            ScanCode::RightShift => OsCode::KEY_RIGHTSHIFT,
-                            ScanCode::NumpadMultiply => OsCode::KEY_KPASTERISK,
-                            ScanCode::LeftAlt => OsCode::KEY_LEFTALT,
-                            ScanCode::Space => OsCode::KEY_SPACE,
-                            ScanCode::CapsLock => OsCode::KEY_CAPSLOCK,
-                            ScanCode::F1 => OsCode::KEY_F1,
-                            ScanCode::F2 => OsCode::KEY_F2,
-                            ScanCode::F3 => OsCode::KEY_F3,
-                            ScanCode::F4 => OsCode::KEY_F4,
-                            ScanCode::F5 => OsCode::KEY_F5,
-                            ScanCode::F6 => OsCode::KEY_F6,
-                            ScanCode::F7 => OsCode::KEY_F7,
-                            ScanCode::F8 => OsCode::KEY_F8,
-                            ScanCode::F9 => OsCode::KEY_F9,
-                            ScanCode::F10 => OsCode::KEY_F10,
-                            ScanCode::NumLock => OsCode::KEY_NUMLOCK,
-                            ScanCode::ScrollLock => OsCode::KEY_SCROLLLOCK,
-                            ScanCode::Numpad7 => OsCode::KEY_KP7,
-                            ScanCode::Numpad8 => OsCode::KEY_KP8,
-                            ScanCode::Numpad9 => OsCode::KEY_KP9,
-                            ScanCode::NumpadMinus => OsCode::KEY_KPMINUS,
-                            ScanCode::Numpad4 => OsCode::KEY_KP4,
-                            ScanCode::Numpad5 => OsCode::KEY_KP5,
-                            ScanCode::Numpad6 => OsCode::KEY_KP6,
-                            ScanCode::NumpadPlus => OsCode::KEY_KPPLUS,
-                            ScanCode::Numpad1 => OsCode::KEY_KP1,
-                            ScanCode::Numpad2 => OsCode::KEY_KP2,
-                            ScanCode::Numpad3 => OsCode::KEY_KP3,
-                            ScanCode::Numpad0 => OsCode::KEY_KP0,
-                            ScanCode::NumpadPeriod => OsCode::KEY_KPDOT,
-                            ScanCode::Int1 => OsCode::KEY_102ND, /* Key between the left shift and Z. */
-                            ScanCode::F11 => OsCode::KEY_F11,
-                            ScanCode::F12 => OsCode::KEY_F12,
-                            ScanCode::F13 => OsCode::KEY_F13,
-                            ScanCode::F14 => OsCode::KEY_F14,
-                            ScanCode::F15 => OsCode::KEY_F15,
-                            ScanCode::F16 => OsCode::KEY_F16,
-                            ScanCode::F17 => OsCode::KEY_F17,
-                            ScanCode::F18 => OsCode::KEY_F18,
-                            ScanCode::F19 => OsCode::KEY_F19,
-                            ScanCode::F20 => OsCode::KEY_F20,
-                            ScanCode::F21 => OsCode::KEY_F21,
-                            ScanCode::F22 => OsCode::KEY_F22,
-                            ScanCode::F23 => OsCode::KEY_F23,
-                            ScanCode::F24 => OsCode::KEY_F24,
-                            ScanCode::Katakana => OsCode::KEY_KATAKANA,
-                            // Note: the OEM keys below don't seem to correspond to the same VK OEM
-                            // mappings as the LLHOOK codes.
-                            // ScanCode::Oem1 = 0x5A, /* VK_OEM_WSCTRL */
-                            // ScanCode::Oem2 = 0x5B, /* VK_OEM_FINISH */
-                            // ScanCode::Oem3 = 0x5C, /* VK_OEM_JUMP */
-                            // ScanCode::Oem4 = 0x5E, /* VK_OEM_BACKTAB */
-                            // ScanCode::Oem5 = 0x5F, /* VK_OEM_AUTO */
-                            // ScanCode::Oem6 = 0x6F, /* VK_OEM_PA3 */
-                            // ScanCode::Oem7 = 0x71, /* VK_OEM_RESET */
-                            // ScanCode::EraseEOF = 0x5D,
-                            // ScanCode::Zoom => 0x62,
-                            // ScanCode::Help => 0x63,
-                            // ScanCode::AltPrintScreen = 0x55, /* Alt + print screen. */
-                            // ScanCode::SBCSChar = 0x77,
-                            // ScanCode::Convert = 0x79,
-                            // ScanCode::NonConvert = 0x7B,
-                            _ => return Err(()),
-                        }
-                    }
-
-                    (true, _) => {
-                        match code as u8 {
-                            0x10 => OsCode::KEY_PREVIOUSSONG,
-                            0x19 => OsCode::KEY_NEXTSONG,
-                            0x1C => OsCode::KEY_KPENTER,
-                            0x1D => OsCode::KEY_RIGHTCTRL,
-                            0x20 => OsCode::KEY_MUTE,
-                            0x22 => OsCode::KEY_PLAYPAUSE, // sc_media_play
-                            // 0x24 => OsCode::KEY_TODO, // sc_media_stop
-                            0x2E => OsCode::KEY_VOLUMEDOWN, // sc_volume_down
-                            0x30 => OsCode::KEY_VOLUMEUP,   // sc_volume_up
-                            // 0x32 => OsCode::KEY_TODO, // sc_browser_home
-                            0x35 => OsCode::KEY_KPSLASH, // sc_numpad_divide
-                            0x37 => OsCode::KEY_PRINT,   // sc_printScreen
-                            0x38 => OsCode::KEY_RIGHTALT, // sc_altRight
-                            // 0x46 => OsCode::KEY_TODO, // sc_cancel
-                            0x47 => OsCode::KEY_HOME,      // sc_home
-                            0x48 => OsCode::KEY_UP,        // sc_arrowUp
-                            0x49 => OsCode::KEY_PAGEUP,    // sc_pageUp
-                            0x4B => OsCode::KEY_LEFT,      // sc_arrowLeft
-                            0x4D => OsCode::KEY_RIGHT,     // sc_arrowRight
-                            0x4F => OsCode::KEY_END,       // sc_end
-                            0x50 => OsCode::KEY_DOWN,      // sc_arrowDown
-                            0x51 => OsCode::KEY_PAGEDOWN,  // sc_pageDown
-                            0x52 => OsCode::KEY_INSERT,    // sc_insert
-                            0x53 => OsCode::KEY_DELETE,    // sc_delete
-                            0x5B => OsCode::KEY_LEFTMETA,  // sc_metaLeft
-                            0x5C => OsCode::KEY_RIGHTMETA, // sc_metaRight
-                            0x5D => OsCode::KEY_COMPOSE,   // sc_application / compose
-                            // 0x5E => OsCode::KEY_TODO, // sc_power
-                            // 0x5F => OsCode::KEY_TODO, // sc_sleep
-                            // 0x63 => OsCode::KEY_TODO, // sc_wake
-                            // 0x65 => OsCode::KEY_TODO, // sc_browser_search
-                            // 0x66 => OsCode::KEY_TODO, // sc_browser_favorites
-                            // 0x67 => OsCode::KEY_TODO, // sc_browser_refresh
-                            // 0x68 => OsCode::KEY_TODO, // sc_browser_stop
-                            0x69 => OsCode::KEY_FORWARD, // sc_browser_forward
-                            0x6A => OsCode::KEY_BACK,    // sc_browser_back
-                            // 0x6B => OsCode::KEY_TODO, // sc_launch_app1
-                            // 0x6C => OsCode::KEY_TODO, // sc_launch_email
-                            // 0x6D => OsCode::KEY_TODO, // sc_launch_media
-                            _ => return Err(()),
-                        }
-                    }
-
+                    (false, false) => crate::oskbd::u16_to_osc(code as u16).ok_or(())?,
+                    (true, _) => crate::oskbd::u16_to_osc((code as u16) | 0xE000).ok_or(())?,
                     _ => return Err(()),
                 };
                 OsCodeWrapper(code)
@@ -475,7 +311,7 @@ impl TryFrom<OsCodeWrapper> for Stroke {
             OsCode::KEY_F22 => (ScanCode::F22, KeyState::empty()),
             OsCode::KEY_F23 => (ScanCode::F23, KeyState::empty()),
             OsCode::KEY_F24 => (ScanCode::F24, KeyState::empty()),
-            OsCode::KEY_KATAKANA => (ScanCode::Katakana, KeyState::empty()),
+            OsCode::KEY_HANGEUL => (ScanCode::Katakana, KeyState::empty()),
             // Note: the OEM keys below don't seem to correspond to the same VK OEM
             // mappings as the LLHOOK codes.
             // ScanCode::Oem1 = 0x5A, /* VK_OEM_WSCTRL */
@@ -490,8 +326,8 @@ impl TryFrom<OsCodeWrapper> for Stroke {
             // ScanCode::Help => 0x63,
             // ScanCode::AltPrintScreen = 0x55, /* Alt + print screen. */
             // ScanCode::SBCSChar = 0x77,
-            // ScanCode::Convert = 0x79,
-            // ScanCode::NonConvert = 0x7B,
+            OsCode::KEY_HENKAN => (ScanCode::Convert, KeyState::empty()),
+            OsCode::KEY_MUHENKAN => (ScanCode::NonConvert, KeyState::empty()),
             OsCode::KEY_PREVIOUSSONG => (ScanCode::Q, KeyState::E0),
             OsCode::KEY_NEXTSONG => (ScanCode::P, KeyState::E0), // 0x19
             OsCode::KEY_KPENTER => (ScanCode::Enter, KeyState::E0), // 0x1C
diff --git a/src/oskbd/windows/llhook.rs b/src/oskbd/windows/llhook.rs
index f751d916f..2229a1995 100644
--- a/src/oskbd/windows/llhook.rs
+++ b/src/oskbd/windows/llhook.rs
@@ -3,6 +3,15 @@
 // This file is taken from kbremap with minor modifications.
 // https://github.com/timokroeger/kbremap
 
+#![cfg_attr(
+    feature = "simulated_output",
+    allow(dead_code, unused_imports, unused_variables, unused_mut)
+)]
+
+mod mouse;
+pub use mouse::*;
+
+use core::fmt;
 use std::cell::Cell;
 use std::io;
 use std::{mem, ptr};
@@ -12,9 +21,14 @@ use winapi::shared::minwindef::*;
 use winapi::shared::windef::*;
 use winapi::um::winuser::*;
 
+use crate::kanata::CalculatedMouseMove;
+use crate::oskbd::{KeyEvent, KeyValue};
+use kanata_keyberon::key_code::KeyCode;
 use kanata_parser::custom_action::*;
 use kanata_parser::keys::*;
 
+pub const LLHOOK_IDLE_TIME_SECS_CLEAR_INPUTS: u64 = 60;
+
 type HookFn = dyn FnMut(InputEvent) -> bool;
 
 thread_local! {
@@ -69,15 +83,48 @@ pub struct InputEvent {
     pub up: bool,
 }
 
+impl fmt::Display for InputEvent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let direction = if self.up { "↑" } else { "↓" };
+        let key_name = KeyCode::from(OsCode::from(self.code));
+        write!(f, "{direction}{key_name:?}")
+    }
+}
+
 impl InputEvent {
+    #[rustfmt::skip]
     fn from_hook_lparam(lparam: &KBDLLHOOKSTRUCT) -> Self {
+        let code = if lparam.vkCode == (VK_RETURN as u32) {
+            match lparam.flags & 0x1 {
+                0 => VK_RETURN as u32,
+                _ => u32::from(VK_KPENTER_FAKE),
+            }
+        } else {
+            #[cfg(not(feature = "win_llhook_read_scancodes"))]
+            {
+                lparam.vkCode
+            }
+            #[cfg(feature = "win_llhook_read_scancodes")]
+            {
+                let extended = if lparam.flags & 0x1 == 0x1 {
+                    0xE000
+                } else {
+                    0
+                };
+                let sc_with_ext = (lparam.scanCode as u16) | extended;
+                log::debug!("converting {sc_with_ext}");
+                crate::oskbd::u16_to_osc(sc_with_ext)
+                    .map(Into::into)
+                    .unwrap_or(lparam.vkCode)
+            }
+        };
         Self {
-            code: lparam.vkCode,
+            code,
             up: lparam.flags & LLKHF_UP != 0,
         }
     }
 
-    fn from_oscode(code: OsCode, val: KeyValue) -> Self {
+    pub fn from_oscode(code: OsCode, val: KeyValue) -> Self {
         Self {
             code: code.into(),
             up: val.into(),
@@ -88,13 +135,13 @@ impl InputEvent {
 impl TryFrom<InputEvent> for KeyEvent {
     type Error = ();
     fn try_from(item: InputEvent) -> Result<Self, Self::Error> {
-        Ok(Self {
-            code: OsCode::from_u16(item.code as u16).ok_or(())?,
-            value: match item.up {
+        Ok(Self::new(
+            OsCode::from_u16(item.code as u16).ok_or(())?,
+            match item.up {
                 true => KeyValue::Release,
                 false => KeyValue::Press,
             },
-        })
+        ))
     }
 }
 
@@ -108,46 +155,87 @@ impl From<KeyEvent> for InputEvent {
 }
 
 /// The actual WinAPI compatible callback.
+/// code: determines how to process the message
+/// source: https://learn.microsoft.com/windows/win32/winmsg/lowlevelkeyboardproc
+///   <0 : must pass the message to CallNextHookEx without further processing
+///    and should return the value returned by CallNextHookEx
+///   HC_ACTION (=0) : wParam and lParam parameters contain information about the message
+///
+/// wparam: ID keyboard message
+/// source: https://learn.microsoft.com/windows/win32/winmsg/lowlevelkeyboardproc
+///   WM_KEY(DOWN|UP) Posted to kb-focused window when a nonsystem key is pressed
+///   WM_SYSKEYDOWN¦UP Posted to kb-focused window when a F10 (activate menu bar)
+///     or ⎇X⃣ or posted to active window if no win has kb focus (check context code in lParam)
+///
+/// lparam: pointer to a KBDLLHOOKSTRUCT struct
+/// source: https://learn.microsoft.com/windows/win32/api/winuser/ns-winuser-kbdllhookstruct
+///   vkCode     :DWORD key's virtual code (1–254)
+///   scanCode   :DWORD key's hardware scan code
+///   flags      :DWORD flags (extended-key, event-injected, transition-state), context code
+///     Bits (2-3 6 reserved)                        Description
+///     7 KF_UP       >> 8 LLKHF_UP                  transition state: 0=key↓  1=key↑
+///                                                           (being pressed)  (being released)
+///     5 KF_ALTDOWN  >> 8 LLKHF_ALTDOWN             context code    : 1=alt↓  0=alt↑
+///     4 0x10             LLKHF_INJECTED            event was injected: 1=yes, 0=no
+///     1 0x02             LLKHF_LOWER_IL_INJECTED   injected by proc with lower integrity level
+//                                                   1=yes 0=no (bit 4 will also set)
+///     0 KF_EXTENDED >> 8 LLKHF_EXTENDED            extended key (Fn, numpad): 1=yes, 0=no
+///   time       :DWORD time stamp = GetMessageTime
+///   dwExtraInfo:ULONG_PTR Additional info
 unsafe extern "system" fn hook_proc(code: c_int, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
-    let hook_lparam = &*(lparam as *const KBDLLHOOKSTRUCT);
-    let is_injected = hook_lparam.flags & LLKHF_INJECTED != 0;
-    log::trace!("{code}, {wparam:?}, {is_injected}");
-    if code != HC_ACTION {
-        return CallNextHookEx(ptr::null_mut(), code, wparam, lparam);
-    }
-
-    let key_event = InputEvent::from_hook_lparam(hook_lparam);
+    unsafe {
+        let hook_lparam = &*(lparam as *const KBDLLHOOKSTRUCT);
+        let is_injected = hook_lparam.flags & LLKHF_INJECTED != 0;
+        log::trace!("{code} {}{wparam} {is_injected}", {
+            match wparam as u32 {
+                WM_KEYDOWN => "↓",
+                WM_KEYUP => "↑",
+                WM_SYSKEYDOWN => "sys↓",
+                WM_SYSKEYUP => "sys↑",
+                _ => "?",
+            }
+        });
+
+        // Regarding code check:
+        // If code is non-zero (technically <0, but 0 is the only valid value anyway),
+        // then it must be forwarded.
+        // Source: https://learn.microsoft.com/windows/win32/winmsg/lowlevelkeyboardproc
+        //
+        // Regarding in_injected check:
+        // `SendInput()` internally calls the hook function.
+        // Filter out injected events to prevent infinite recursion.
+        if code != HC_ACTION || is_injected {
+            return CallNextHookEx(ptr::null_mut(), code, wparam, lparam);
+        }
 
-    // `SendInput()` internally calls the hook function. Filter out injected events
-    // to prevent recursion and potential stack overflows if our remapping logic
-    // sent the injected event.
-    if is_injected {
-        return CallNextHookEx(ptr::null_mut(), code, wparam, lparam);
-    }
+        let key_event = InputEvent::from_hook_lparam(hook_lparam);
 
-    let mut handled = false;
-    HOOK.with(|state| {
-        // The unwrap cannot fail, because we have initialized [`HOOK`] with a
-        // valid closure before registering the hook (this function).
-        // To access the closure we move it out of the cell and put it back
-        // after it returned. For this to work we need to prevent recursion by
-        // dropping injected events. Otherwise we would try to take the closure
-        // twice and the call would fail the second time.
-        let mut hook = state.take().expect("no recurse");
-        handled = hook(key_event);
-        state.set(Some(hook));
-    });
-
-    if handled {
-        1
-    } else {
-        CallNextHookEx(ptr::null_mut(), code, wparam, lparam)
+        let mut handled = false;
+        HOOK.with(|state| {
+            // The unwrap cannot fail, because we have initialized [`HOOK`] with a
+            // valid closure before registering the hook (this function).
+            // To access the closure we move it out of the cell and put it back
+            // after it returned. For this to work we need to prevent recursion by
+            // dropping injected events. Otherwise we would try to take the closure
+            // twice and the call would fail the second time.
+            let mut hook = state.take().expect("no recurse");
+            handled = hook(key_event);
+            state.set(Some(hook));
+        });
+
+        if handled {
+            1
+        } else {
+            CallNextHookEx(ptr::null_mut(), code, wparam, lparam)
+        }
     }
 }
 
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 /// Handle for writing keys to the OS.
 pub struct KbdOut {}
 
+#[cfg(all(not(feature = "simulated_output"), not(feature = "passthru_ahk")))]
 impl KbdOut {
     pub fn new() -> Result<Self, io::Error> {
         Ok(Self {})
@@ -167,6 +255,10 @@ impl KbdOut {
         super::write_code(code as u16, value)
     }
 
+    pub fn write_code_raw(&mut self, code: u16, value: KeyValue) -> Result<(), io::Error> {
+        super::write_code_raw(code, value)
+    }
+
     pub fn press_key(&mut self, key: OsCode) -> Result<(), io::Error> {
         self.write_key(key, KeyValue::Press)
     }
@@ -215,8 +307,13 @@ impl KbdOut {
         Ok(())
     }
 
-    pub fn move_mouse(&mut self, direction: MoveDirection, distance: u16) -> Result<(), io::Error> {
-        move_mouse(direction, distance);
+    pub fn move_mouse(&mut self, mv: CalculatedMouseMove) -> Result<(), io::Error> {
+        move_mouse(mv.direction, mv.distance);
+        Ok(())
+    }
+
+    pub fn move_mouse_many(&mut self, moves: &[CalculatedMouseMove]) -> Result<(), io::Error> {
+        move_mouse_many(moves);
         Ok(())
     }
 
@@ -302,6 +399,22 @@ fn move_mouse(direction: MoveDirection, distance: u16) {
     }
 }
 
+fn move_mouse_many(moves: &[CalculatedMouseMove]) {
+    let mut x_acc = 0;
+    let mut y_acc = 0;
+    for mov in moves {
+        let acc_change = match mov.direction {
+            MoveDirection::Up => (0, -i32::from(mov.distance)),
+            MoveDirection::Down => (0, i32::from(mov.distance)),
+            MoveDirection::Left => (-i32::from(mov.distance), 0),
+            MoveDirection::Right => (i32::from(mov.distance), 0),
+        };
+        x_acc += acc_change.0;
+        y_acc += acc_change.1;
+    }
+    move_mouse_xy(x_acc, y_acc);
+}
+
 fn move_mouse_xy(x: i32, y: i32) {
     mouse_event(MOUSEEVENTF_MOVE, 0, x, y);
 }
@@ -320,14 +433,16 @@ fn mouse_event(flags: u32, data: u32, dx: i32, dy: i32) {
     let mut input = INPUT {
         type_: INPUT_MOUSE,
         u: unsafe {
-            mem::transmute(MOUSEINPUT {
-                dx,
-                dy,
-                mouseData: data,
-                dwFlags: flags,
-                time: 0,
-                dwExtraInfo: 0,
-            })
+            mem::transmute::<winapi::um::winuser::MOUSEINPUT, winapi::um::winuser::INPUT_u>(
+                MOUSEINPUT {
+                    dx,
+                    dy,
+                    mouseData: data,
+                    dwFlags: flags,
+                    time: 0,
+                    dwExtraInfo: 0,
+                },
+            )
         },
     };
     unsafe { SendInput(1, &mut input as LPINPUT, mem::size_of::<INPUT>() as c_int) };
diff --git a/src/oskbd/windows/llhook/mouse.rs b/src/oskbd/windows/llhook/mouse.rs
new file mode 100644
index 000000000..137fc883f
--- /dev/null
+++ b/src/oskbd/windows/llhook/mouse.rs
@@ -0,0 +1,417 @@
+/// Mouse functionality for windows hooks.
+///
+/// Code taken and adapted from:
+/// https://github.com/myood/willhook-rs/tree/f4ccbc897504834d0c01fa449a2660b9989290e5
+/// License: MIT
+use super::*;
+
+use winapi::shared::windef::HHOOK;
+use winapi::um::winuser::UnhookWindowsHookEx;
+
+type MHookFn = dyn FnMut(MouseEventType) -> bool;
+thread_local! {
+    /// Stores the hook callback for the current thread.
+    static MHOOK: Cell<Option<Box<MHookFn>>> = Cell::default();
+}
+
+/// Wrapper for the low-level keyboard hook API.
+/// Automatically unregisters the hook when dropped.
+pub struct MouseHook {
+    handle: HHOOK,
+}
+
+impl MouseHook {
+    pub fn set_input_cb(callback: impl FnMut(MouseEventType) -> bool + 'static) -> MouseHook {
+        MHOOK.with(|state| {
+            assert!(
+                state.take().is_none(),
+                "Only one mouse hook can be registered per thread."
+            );
+
+            state.set(Some(Box::new(callback)));
+
+            MouseHook {
+                handle: unsafe {
+                    SetWindowsHookExW(WH_MOUSE_LL, Some(mhook_proc), ptr::null_mut(), 0)
+                        .as_mut()
+                        .expect("install low-level keyboard hook successfully")
+                },
+            }
+        })
+    }
+}
+
+impl Drop for MouseHook {
+    fn drop(&mut self) {
+        unsafe { UnhookWindowsHookEx(self.handle) };
+        MHOOK.with(|state| state.take());
+    }
+}
+
+unsafe extern "system" fn mhook_proc(code: c_int, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
+    let mouse_lparam = unsafe { &*(lparam as *const MSLLHOOKSTRUCT) };
+    let is_injected = mouse_lparam.flags & (LLMHF_INJECTED | LLMHF_LOWER_IL_INJECTED) != 0;
+    log::trace!("{code} {wparam} {is_injected}");
+
+    // Regarding is_injected check:
+    // `SendInput()` internally calls the hook function.
+    // Filter out injected events to prevent infinite recursion.
+    if is_injected {
+        return unsafe { CallNextHookEx(ptr::null_mut(), code, wparam, lparam) };
+    }
+
+    let mut handled = false;
+    let mouse_event = unsafe { classify_mouse_event(wparam, mouse_lparam) };
+    MHOOK.with(|state| {
+        // The unwrap cannot fail, because we have initialized [`HOOK`] with a
+        // valid closure before registering the hook (this function).
+        // To access the closure we move it out of the cell and put it back
+        // after it returned. For this to work we need to prevent recursion by
+        // dropping injected events. Otherwise we would try to take the closure
+        // twice and the call would fail the second time.
+        let mut hook = state.take().expect("no recurse");
+        handled = hook(mouse_event);
+        state.set(Some(hook));
+    });
+
+    if handled {
+        1
+    } else {
+        unsafe { CallNextHookEx(ptr::null_mut(), code, wparam, lparam) }
+    }
+}
+
+/// The type of the mouse event with it's specific data
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseEventType {
+    /// Button on the mouse was pressed
+    Press(MousePressEvent),
+    /// Mouse was moved
+    Move(MouseMoveEvent),
+    /// Wheel on the mouse was, well, spinning.
+    Wheel(MouseWheelEvent),
+    /// Received unrecognized mouse event type, the code is stored for reference.
+    Other(usize),
+}
+
+use MouseEventType::*;
+
+/// Holds information which button was pressed or released
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub struct MousePressEvent {
+    pub pressed: MouseButtonPress,
+    pub button: MouseButton,
+}
+
+/// Holds information which mouse wheel triggered the event
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseWheel {
+    Horizontal,
+    Vertical,
+    Unknown(usize),
+}
+
+/// Indicates the direction of the mouse wheel spin
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseWheelDirection {
+    Forward,
+    Backward,
+    Unknown(u32),
+}
+
+/// The mouse wheel event with information which wheel triggered an event and the direction of the spin
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub struct MouseWheelEvent {
+    pub wheel: MouseWheel,
+    pub direction: Option<MouseWheelDirection>,
+}
+
+/// Point in per-monitor aware coordinates, see
+/// [MSDN](https://learn.microsoft.com/en-us/windows/desktop/api/shellscalingapi/ne-shellscalingapi-process_dpi_awareness)
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub struct Point {
+    pub x: i32,
+    pub y: i32,
+}
+
+/// Holds the new cursor position after mouse move
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub struct MouseMoveEvent {
+    pub point: Option<Point>,
+}
+
+/// Indicates if button was pressed or released
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseButtonPress {
+    Down,
+    Up,
+    Other(usize),
+}
+
+/// Indicates if mouse button press is single or double click
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseClick {
+    SingleClick,
+    DoubleClick,
+    Other(u32),
+}
+
+/// Identifies which mouse button triggered an event
+#[derive(Copy, Clone, Ord, PartialOrd, Hash, Eq, PartialEq, Debug)]
+pub enum MouseButton {
+    Left(MouseClick),
+    Right(MouseClick),
+    Middle(MouseClick),
+    /// XBUTTON1
+    X1(MouseClick),
+    /// XBUTTON2
+    X2(MouseClick),
+    /// Either XBUTTON1 or XBUTTON2
+    UnkownX(MouseClick),
+    /// Unexpected mouse button. Raw code stored for reference, see MSDN documentation about low-level hooks.
+    Other(usize),
+}
+
+/// # Safety
+/// Pointers must be valid from winapi.
+pub unsafe fn classify_mouse_event(
+    wm_mouse_param: WPARAM,
+    ms_ll_hook_struct: *const MSLLHOOKSTRUCT,
+) -> MouseEventType {
+    match wm_mouse_param as u32 {
+        // Mouse press
+        WM_LBUTTONDOWN | WM_LBUTTONUP | WM_LBUTTONDBLCLK => {
+            Press(unsafe { MousePressEvent::new(wm_mouse_param, ms_ll_hook_struct) })
+        }
+        WM_RBUTTONDOWN | WM_RBUTTONUP | WM_RBUTTONDBLCLK => {
+            Press(unsafe { MousePressEvent::new(wm_mouse_param, ms_ll_hook_struct) })
+        }
+        WM_MBUTTONDOWN | WM_MBUTTONUP | WM_MBUTTONDBLCLK => {
+            Press(unsafe { MousePressEvent::new(wm_mouse_param, ms_ll_hook_struct) })
+        }
+        WM_XBUTTONDOWN | WM_XBUTTONUP | WM_XBUTTONDBLCLK => {
+            Press(unsafe { MousePressEvent::new(wm_mouse_param, ms_ll_hook_struct) })
+        }
+
+        // Mouse move
+        WM_MOUSEMOVE => Move(unsafe { MouseMoveEvent::new(ms_ll_hook_struct) }),
+
+        // Wheel move
+        WM_MOUSEWHEEL | WM_MOUSEHWHEEL => {
+            Wheel(unsafe { MouseWheelEvent::new(wm_mouse_param, ms_ll_hook_struct) })
+        }
+
+        _ => Other(wm_mouse_param),
+    }
+}
+
+impl MousePressEvent {
+    /// # Safety
+    /// Pointers must be valid from winapi.
+    pub unsafe fn new(
+        wm_mouse_param: WPARAM,
+        ms_ll_hook_struct: *const MSLLHOOKSTRUCT,
+    ) -> MousePressEvent {
+        MousePressEvent {
+            pressed: MouseButtonPress::from(wm_mouse_param),
+            button: unsafe { MouseButton::from(wm_mouse_param, ms_ll_hook_struct) },
+        }
+    }
+}
+
+impl From<POINT> for Point {
+    fn from(value: POINT) -> Self {
+        Point {
+            x: value.x,
+            y: value.y,
+        }
+    }
+}
+
+impl MouseWheel {
+    pub fn new(wm_mouse_param: WPARAM) -> MouseWheel {
+        use MouseWheel::*;
+        match wm_mouse_param.try_into() {
+            Ok(param_u32) => match param_u32 {
+                WM_MOUSEWHEEL => Vertical,
+                WM_MOUSEHWHEEL => Horizontal,
+                _ => Unknown(wm_mouse_param),
+            },
+            _ => Unknown(wm_mouse_param),
+        }
+    }
+}
+
+impl MouseWheelEvent {
+    /// # Safety
+    /// Pointers must be valid from winapi.
+    pub unsafe fn new(
+        wm_mouse_param: WPARAM,
+        ms_ll_hook_struct: *const MSLLHOOKSTRUCT,
+    ) -> MouseWheelEvent {
+        MouseWheelEvent {
+            wheel: MouseWheel::new(wm_mouse_param),
+            direction: unsafe { MouseWheelDirection::optionally_from(ms_ll_hook_struct) },
+        }
+    }
+}
+
+impl MouseWheelDirection {
+    /// # Safety
+    /// Pointers must be valid from winapi.
+    pub unsafe fn optionally_from(
+        ms_ll_hook_struct: *const MSLLHOOKSTRUCT,
+    ) -> Option<MouseWheelDirection> {
+        if ms_ll_hook_struct.is_null() {
+            None
+        } else {
+            Some(unsafe { MouseWheelDirection::new(&*ms_ll_hook_struct) })
+        }
+    }
+
+    fn new(ms_ll_hook_struct: &MSLLHOOKSTRUCT) -> MouseWheelDirection {
+        use MouseWheelDirection::*;
+        let delta = GET_WHEEL_DELTA_WPARAM(ms_ll_hook_struct.mouseData as WPARAM);
+        match delta {
+            _ if delta > 0 => Forward,
+            _ if delta < 0 => Backward,
+            _ => Unknown(ms_ll_hook_struct.mouseData),
+        }
+    }
+}
+
+impl MouseMoveEvent {
+    /// # Safety
+    /// Pointers must be valid from winapi.
+    pub unsafe fn new(ms_ll_hook_struct: *const MSLLHOOKSTRUCT) -> MouseMoveEvent {
+        if ms_ll_hook_struct.is_null() {
+            MouseMoveEvent { point: None }
+        } else {
+            let msll = unsafe { &*ms_ll_hook_struct };
+            let pt = msll.pt;
+            MouseMoveEvent {
+                point: Some(pt.into()),
+            }
+        }
+    }
+}
+
+impl From<WPARAM> for MouseButtonPress {
+    fn from(value: WPARAM) -> Self {
+        use MouseButtonPress::*;
+        match value.try_into() {
+            Ok(uv) => match uv {
+                WM_LBUTTONDOWN | WM_RBUTTONDOWN | WM_MBUTTONDOWN | WM_XBUTTONDOWN => Down,
+                WM_RBUTTONUP | WM_LBUTTONUP | WM_MBUTTONUP | WM_XBUTTONUP => Up,
+                _ => Other(value),
+            },
+            Err(_) => Other(value),
+        }
+    }
+}
+
+impl From<WPARAM> for MouseClick {
+    fn from(value: WPARAM) -> Self {
+        use MouseClick::*;
+        match value.try_into() {
+            Ok(uv) => match uv {
+                WM_LBUTTONDOWN | WM_RBUTTONDOWN | WM_MBUTTONDOWN | WM_XBUTTONDOWN => SingleClick,
+                WM_LBUTTONUP | WM_RBUTTONUP | WM_MBUTTONUP | WM_XBUTTONUP => SingleClick,
+                WM_LBUTTONDBLCLK | WM_RBUTTONDBLCLK | WM_MBUTTONDBLCLK | WM_XBUTTONDBLCLK => {
+                    DoubleClick
+                }
+                _ => Other(value as u32),
+            },
+            Err(_) => Other(value as u32),
+        }
+    }
+}
+
+impl MouseButton {
+    /// # Safety
+    /// Pointers must be valid from winapi.
+    pub unsafe fn from(wm_mouse_param: WPARAM, ms_ll_hook_struct: *const MSLLHOOKSTRUCT) -> Self {
+        let click = MouseClick::from(wm_mouse_param);
+
+        use MouseButton::*;
+        match wm_mouse_param.try_into() {
+            Ok(param) => {
+                match param {
+                    WM_LBUTTONDOWN | WM_LBUTTONUP | WM_LBUTTONDBLCLK => Left(click),
+                    WM_RBUTTONDOWN | WM_RBUTTONUP | WM_RBUTTONDBLCLK => Right(click),
+                    WM_MBUTTONDOWN | WM_MBUTTONUP | WM_MBUTTONDBLCLK => Middle(click),
+                    WM_XBUTTONDOWN | WM_XBUTTONUP | WM_XBUTTONDBLCLK => {
+                        if ms_ll_hook_struct.is_null() {
+                            UnkownX(click)
+                        } else {
+                            Self::into_extra(click, unsafe { &*ms_ll_hook_struct })
+                        }
+                    }
+                    // Value out of expected set
+                    _ => Other(wm_mouse_param),
+                }
+            }
+            // Conversion error
+            Err(_) => Other(wm_mouse_param),
+        }
+    }
+
+    fn into_extra(click: MouseClick, ms_ll_hook_struct: &MSLLHOOKSTRUCT) -> Self {
+        use MouseButton::*;
+        match GET_XBUTTON_WPARAM(ms_ll_hook_struct.mouseData.try_into().expect("")) {
+            XBUTTON1 => X1(click),
+            XBUTTON2 => X2(click),
+            _ => UnkownX(click),
+        }
+    }
+}
+
+impl TryFrom<MouseEventType> for KeyEvent {
+    type Error = ();
+    fn try_from(mevt: MouseEventType) -> Result<Self, ()> {
+        use OsCode::*;
+        match mevt {
+            Move(..) | Other(..) => Err(()),
+            Press(MousePressEvent { pressed, button }) => {
+                let value = match pressed {
+                    MouseButtonPress::Up => KeyValue::Release,
+                    MouseButtonPress::Down => KeyValue::Press,
+                    MouseButtonPress::Other(..) => return Err(()),
+                };
+                let code = match button {
+                    // TODO:
+                    // The inner type is MouseClick.
+                    // - DoubleClick might need to actually send two events.. but Kanata doesn't
+                    //   have a good way to signal multiple events into the event queue for a
+                    //   single oskbd source event.
+                    // - Other might be better off as Err(())
+                    // This applies to all variants.
+                    MouseButton::Left(..) => BTN_LEFT,
+                    MouseButton::Right(..) => BTN_RIGHT,
+                    MouseButton::Middle(..) => BTN_MIDDLE,
+                    MouseButton::X1(..) => BTN_SIDE,
+                    MouseButton::X2(..) => BTN_EXTRA,
+                    MouseButton::UnkownX(..) | MouseButton::Other(..) => return Err(()),
+                };
+                Ok(KeyEvent::new(code, value))
+            }
+            Wheel(MouseWheelEvent { wheel, direction }) => {
+                use MouseWheel::*;
+                use MouseWheelDirection::*;
+                let Some(direction) = direction else {
+                    return Err(());
+                };
+                let code = match (wheel, direction) {
+                    (Vertical, Forward) => MouseWheelUp,
+                    (Vertical, Backward) => MouseWheelDown,
+                    (Horizontal, Forward) => MouseWheelRight,
+                    (Horizontal, Backward) => MouseWheelLeft,
+                    (MouseWheel::Unknown(..), _) | (_, MouseWheelDirection::Unknown(..)) => {
+                        return Err(());
+                    }
+                };
+                Ok(KeyEvent::new(code, KeyValue::Tap))
+            }
+        }
+    }
+}
diff --git a/src/oskbd/windows/mod.rs b/src/oskbd/windows/mod.rs
index d78bb013c..2ff66b1e0 100644
--- a/src/oskbd/windows/mod.rs
+++ b/src/oskbd/windows/mod.rs
@@ -1,16 +1,34 @@
+#![cfg_attr(
+    feature = "simulated_output",
+    allow(dead_code, unused_imports, unused_variables, unused_mut)
+)]
+
+#[cfg(not(feature = "simulated_input"))]
 use std::mem;
 
+#[cfg(not(feature = "simulated_input"))]
 use winapi::um::winuser::*;
 
+#[cfg(not(feature = "simulated_input"))]
 use encode_unicode::CharExt;
 
-use kanata_parser::keys::KeyValue;
+#[cfg(not(feature = "simulated_input"))]
+use crate::oskbd::KeyValue;
 
-#[cfg(not(feature = "interception_driver"))]
-mod llhook;
-#[cfg(not(feature = "interception_driver"))]
+#[cfg(all(not(feature = "interception_driver"), not(feature = "simulated_input")))]
+mod llhook; // contains KbdOut any(not(feature = "simulated_output"), not(feature = "passthru_ahk"))
+#[cfg(all(not(feature = "interception_driver"), not(feature = "simulated_input")))]
 pub use llhook::*;
 
+#[cfg(all(not(feature = "interception_driver"), feature = "simulated_input"))]
+mod exthook_os;
+#[cfg(all(not(feature = "interception_driver"), feature = "simulated_input"))]
+pub use exthook_os::*;
+
+mod scancode_to_usvk;
+#[allow(unused)]
+pub use scancode_to_usvk::*;
+
 #[cfg(feature = "interception_driver")]
 mod interception;
 #[cfg(feature = "interception_driver")]
@@ -20,6 +38,7 @@ pub use self::interception::*;
 #[cfg(feature = "interception_driver")]
 pub use interception_convert::*;
 
+#[cfg(not(feature = "simulated_input"))]
 fn send_uc(c: char, up: bool) {
     log::debug!("sending unicode {c}");
     let mut inputs: [INPUT; 2] = unsafe { mem::zeroed() };
@@ -48,24 +67,167 @@ fn send_uc(c: char, up: bool) {
     }
 }
 
+#[cfg(not(feature = "simulated_output"))]
+fn write_code_raw(code: u16, value: KeyValue) -> Result<(), std::io::Error> {
+    let is_key_up = match value {
+        KeyValue::Press | KeyValue::Repeat => false,
+        KeyValue::Release => true,
+        KeyValue::Tap => panic!("invalid value attempted to be sent"),
+        KeyValue::WakeUp => panic!("invalid value attempted to be sent"),
+    };
+    unsafe {
+        let mut kb_input: KEYBDINPUT = mem::zeroed();
+        if is_key_up {
+            kb_input.dwFlags |= KEYEVENTF_KEYUP;
+        }
+        kb_input.wVk = code;
+        let mut inputs: [INPUT; 1] = mem::zeroed();
+        inputs[0].type_ = INPUT_KEYBOARD;
+        *inputs[0].u.ki_mut() = kb_input;
+        SendInput(1, inputs.as_mut_ptr(), mem::size_of::<INPUT>() as _);
+    }
+    Ok(())
+}
+
+#[cfg(not(feature = "simulated_input"))]
 fn write_code(code: u16, value: KeyValue) -> Result<(), std::io::Error> {
     send_key_sendinput(
         code,
         match value {
             KeyValue::Press | KeyValue::Repeat => false,
             KeyValue::Release => true,
+            KeyValue::Tap => panic!("invalid value attempted to be sent"),
+            KeyValue::WakeUp => panic!("invalid value attempted to be sent"),
         },
     );
     Ok(())
 }
 
+#[cfg(not(feature = "simulated_input"))]
 fn send_key_sendinput(code: u16, is_key_up: bool) {
     unsafe {
         let mut kb_input: KEYBDINPUT = mem::zeroed();
         if is_key_up {
             kb_input.dwFlags |= KEYEVENTF_KEYUP;
         }
-        kb_input.wVk = code;
+
+        #[cfg(feature = "win_sendinput_send_scancodes")]
+        {
+            /*
+            Credit to @VictorLemosR from GitHub for the code here 🙂:
+
+            All the keys that are extended are on font 1, inside the table on column 'Scan 1 Make' and start with '0xE0'.
+            To obtain the scancode, one could just print 'kb_input.wScan' from the function below.
+            Font 1: https://learn.microsoft.com/en-us/windows/win32/inputdev/about-keyboard-input#scan-codes
+            To obtain a virtual key code, one could just print 'code' from the function below for a key or see font 2
+            Font 2: https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
+
+            For example, left arrow and 4 from numpad. For the scancode, they have the same low byte,
+            but not the same high byte, which is 0xE0. LeftArrow = 0xE04B, keypad 4 = 0x004B. For the virtual code,
+            left arrow is 0x25 and 4 from numpad is 0x64.
+            There is a windows function called 'MapVirtualKeyA' that can be used to convert a virtual key code to a scancode.
+
+            IMPORTANT: these numbers are the VK numbers, e.g. VK_Q, VK_LSHIFT
+            */
+            const EXTENDED_KEYS: [u8; 48] = if cfg!(not(feature = "win_llhook_read_scancodes")) {
+                // BUG NOTES:
+                // The difference between the two variants is the handling of VK_SNAPSHOT.
+                //
+                // It seems the winapi MapVirtualKeyA does an different mapping when passing in
+                // VK_SNAPSHOT than the rest of the code used to expect. It gets mapped to 88, or
+                // 0x54, and this should be non-extended, i.e. it remains 0x54 and not 0xE037. With
+                // winiov2/gui/interception variants, MapVirtualKeyA is not used by default and
+                // instead it's a custom mapping, which maps it to 0xE037, and this value seems to
+                // have the correct effect.
+                //
+                // According to readings, MapVirtualKeyA does not do extended flag properly, so
+                // since the VK_SNAPSHOT mapping was believed to be an extended key, the 0xE000 was
+                // added and 0x54 became 0xE054 which doesn't do anything. Avoiding adding of the
+                // 0xE000 fixes the issue.
+                [
+                    0xb1, 0xb0, 0xa3, 0xad, 0x8c, 0xb3, 0xb2, 0xae, 0xaf, 0xac, 0x6f, 0x13, 0xa5,
+                    0x24, 0x26, 0x21, 0x25, 0x27, 0x23, 0x28, 0x22, 0x2d, 0x2e, 0x5b, 0x5c, 0x5d,
+                    0x5f, 0xaa, 0xa8, 0xa9, 0xa7, 0xa6, 0xac, 0xb4, 0x13,
+                    /*
+                    The 0x13 here is repeated. Why? Maybe it will generate better comparison code 😅.
+                    Probably should test+measure when making changes like this (but I didn't).
+                    The theory is that comparing on a 16-byte boundary seems good.
+                    Below taken from Rust source:
+
+                    const fn memchr_aligned(x: u8, text: &[u8]) -> Option<usize> {
+                        // Scan for a single byte value by reading two `usize` words at a time.
+                        //
+                        // Split `text` in three parts
+                        // - unaligned initial part, before the first word aligned address in text
+                        // - body, scan by 2 words at a time
+                        // - the last remaining part, < 2 word size
+                    */
+                    0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13,
+                ]
+            } else {
+                [
+                    0xb1, 0xb0, 0xa3, 0xad, 0x8c, 0xb3, 0xb2, 0xae, 0xaf, 0xac, 0x6f, 0x2c, 0xa5,
+                    0x24, 0x26, 0x21, 0x25, 0x27, 0x23, 0x28, 0x22, 0x2d, 0x2e, 0x5b, 0x5c, 0x5d,
+                    0x5f, 0xaa, 0xa8, 0xa9, 0xa7, 0xa6, 0xac, 0xb4, 0x13, 0x13, 0x13, 0x13, 0x13,
+                    0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13, 0x13,
+                ]
+            };
+
+            let code_u32 = code as u32;
+            kb_input.dwFlags |= KEYEVENTF_SCANCODE;
+            #[cfg(not(feature = "win_llhook_read_scancodes"))]
+            {
+                // This MapVirtualKeyA is needed to translate back to the proper scancode
+                // associated with with the virtual key.
+                // E.g. take this example:
+                //
+                // - KEY_A is the code here
+                // - OS layout is AZERTY
+                // - No remapping, e.g. active layer is:
+                //   - (deflayermap (active-layer) a a)
+                //
+                // This means kanata received a key press at US-layout position Q. However,
+                // translating KEY_A via osc_to_u16 will result in the scancode assocated with
+                // US-layout position A, but we want to output the position Q scancode. It is
+                // MapVirtualKeyA that does the correct translation for this based on the user's OS
+                // layout.
+                kb_input.wScan = MapVirtualKeyA(code_u32, 0) as u16;
+                if kb_input.wScan == 0 {
+                    // The known scenario for this is VK_KPENTER_FAKE which isn't a real VK so
+                    // MapVirtualKeyA is expected to return 0. This fake VK is used to
+                    // distinguish the key within kanata since in Windows there is no output VK for
+                    // the enter key at the numpad.
+                    //
+                    // The osc_to_u16 function knows the scancode for keypad enter though, and it
+                    // isn't known to change based on language layout so this seems fine to do.
+                    kb_input.wScan = osc_to_u16(code.into()).unwrap_or(0);
+                }
+            }
+            #[cfg(feature = "win_llhook_read_scancodes")]
+            {
+                kb_input.wScan =
+                    osc_to_u16(code.into()).unwrap_or_else(|| MapVirtualKeyA(code_u32, 0) as u16);
+            }
+
+            if kb_input.wScan == 0 {
+                kb_input.dwFlags &= !KEYEVENTF_SCANCODE;
+                kb_input.wVk = code;
+            }
+
+            let is_extended_key: bool = code < 0xff && EXTENDED_KEYS.contains(&(code as u8));
+            if is_extended_key {
+                kb_input.wScan |= 0xE0 << 8;
+                kb_input.dwFlags |= KEYEVENTF_EXTENDEDKEY;
+            }
+        }
+        #[cfg(not(feature = "win_sendinput_send_scancodes"))]
+        {
+            use kanata_parser::keys::*;
+            kb_input.wVk = match code {
+                VK_KPENTER_FAKE => VK_RETURN as u16,
+                _ => code,
+            };
+        }
 
         let mut inputs: [INPUT; 1] = mem::zeroed();
         inputs[0].type_ = INPUT_KEYBOARD;
diff --git a/src/oskbd/windows/scancode_to_usvk.rs b/src/oskbd/windows/scancode_to_usvk.rs
new file mode 100644
index 000000000..9fc4e3682
--- /dev/null
+++ b/src/oskbd/windows/scancode_to_usvk.rs
@@ -0,0 +1,309 @@
+use kanata_parser::keys::OsCode;
+
+#[rustfmt::skip]
+#[allow(unused)]
+pub fn u16_to_osc(input: u16) -> Option<OsCode> {
+    Some(if input < 0xE000 {
+        match input {
+            0x01 => OsCode::KEY_ESC,
+            0x02 => OsCode::KEY_1,
+            0x03 => OsCode::KEY_2,
+            0x04 => OsCode::KEY_3,
+            0x05 => OsCode::KEY_4,
+            0x06 => OsCode::KEY_5,
+            0x07 => OsCode::KEY_6,
+            0x08 => OsCode::KEY_7,
+            0x09 => OsCode::KEY_8,
+            0x0A => OsCode::KEY_9,
+            0x0B => OsCode::KEY_0,
+            0x0C => OsCode::KEY_MINUS,
+            0x0D => OsCode::KEY_EQUAL,
+            0x0E => OsCode::KEY_BACKSPACE,
+            0x0F => OsCode::KEY_TAB,
+            0x10 => OsCode::KEY_Q,
+            0x11 => OsCode::KEY_W,
+            0x12 => OsCode::KEY_E,
+            0x13 => OsCode::KEY_R,
+            0x14 => OsCode::KEY_T,
+            0x15 => OsCode::KEY_Y,
+            0x16 => OsCode::KEY_U,
+            0x17 => OsCode::KEY_I,
+            0x18 => OsCode::KEY_O,
+            0x19 => OsCode::KEY_P,
+            0x1A => OsCode::KEY_LEFTBRACE,
+            0x1B => OsCode::KEY_RIGHTBRACE,
+            0x1C => OsCode::KEY_ENTER,
+            0x1D => OsCode::KEY_LEFTCTRL,
+            0x1E => OsCode::KEY_A,
+            0x1F => OsCode::KEY_S,
+            0x20 => OsCode::KEY_D,
+            0x21 => OsCode::KEY_F,
+            0x22 => OsCode::KEY_G,
+            0x23 => OsCode::KEY_H,
+            0x24 => OsCode::KEY_J,
+            0x25 => OsCode::KEY_K,
+            0x26 => OsCode::KEY_L,
+            0x27 => OsCode::KEY_SEMICOLON,
+            0x28 => OsCode::KEY_APOSTROPHE,
+            0x29 => OsCode::KEY_GRAVE,
+            0x2A => OsCode::KEY_LEFTSHIFT,
+            0x2B => OsCode::KEY_BACKSLASH,
+            0x2C => OsCode::KEY_Z,
+            0x2D => OsCode::KEY_X,
+            0x2E => OsCode::KEY_C,
+            0x2F => OsCode::KEY_V,
+            0x30 => OsCode::KEY_B,
+            0x31 => OsCode::KEY_N,
+            0x32 => OsCode::KEY_M,
+            0x33 => OsCode::KEY_COMMA,
+            0x34 => OsCode::KEY_DOT,
+            0x35 => OsCode::KEY_SLASH,
+            0x36 => OsCode::KEY_RIGHTSHIFT,
+            0x37 => OsCode::KEY_KPASTERISK,
+            0x38 => OsCode::KEY_LEFTALT,
+            0x39 => OsCode::KEY_SPACE,
+            0x3A => OsCode::KEY_CAPSLOCK,
+            0x3B => OsCode::KEY_F1,
+            0x3C => OsCode::KEY_F2,
+            0x3D => OsCode::KEY_F3,
+            0x3E => OsCode::KEY_F4,
+            0x3F => OsCode::KEY_F5,
+            0x40 => OsCode::KEY_F6,
+            0x41 => OsCode::KEY_F7,
+            0x42 => OsCode::KEY_F8,
+            0x43 => OsCode::KEY_F9,
+            0x44 => OsCode::KEY_F10,
+            0x45 => OsCode::KEY_NUMLOCK,
+            0x46 => OsCode::KEY_SCROLLLOCK,
+            0x47 => OsCode::KEY_KP7,
+            0x48 => OsCode::KEY_KP8,
+            0x49 => OsCode::KEY_KP9,
+            0x4A => OsCode::KEY_KPMINUS,
+            0x4B => OsCode::KEY_KP4,
+            0x4C => OsCode::KEY_KP5,
+            0x4D => OsCode::KEY_KP6,
+            0x4E => OsCode::KEY_KPPLUS,
+            0x4F => OsCode::KEY_KP1,
+            0x50 => OsCode::KEY_KP2,
+            0x51 => OsCode::KEY_KP3,
+            0x52 => OsCode::KEY_KP0,
+            0x53 => OsCode::KEY_KPDOT,
+            0x56 => OsCode::KEY_102ND, /* Key between the left shift and Z. */
+            0x57 => OsCode::KEY_F11,
+            0x58 => OsCode::KEY_F12,
+            0x64 => OsCode::KEY_F13,
+            0x65 => OsCode::KEY_F14,
+            0x66 => OsCode::KEY_F15,
+            0x67 => OsCode::KEY_F16,
+            0x68 => OsCode::KEY_F17,
+            0x69 => OsCode::KEY_F18,
+            0x6A => OsCode::KEY_F19,
+            0x6B => OsCode::KEY_F20,
+            0x6C => OsCode::KEY_F21,
+            0x6D => OsCode::KEY_F22,
+            0x6E => OsCode::KEY_F23,
+            0x73 => OsCode::KEY_RO,
+            0x76 => OsCode::KEY_F24,
+            0x70 => OsCode::KEY_KATAKANA,
+            0x79 => OsCode::KEY_HENKAN,   // Convert
+            0x7B => OsCode::KEY_MUHENKAN, // Noconvert
+            0x7D => OsCode::KEY_YEN,      // Yen / Pipe
+            // Note: the OEM keys below don't seem to correspond to the same VK OEM
+            // mappings as the LLHOOK codes.
+            // ScanCode::Oem1 = 0x5A, /* VK_OEM_WSCTRL */
+            // ScanCode::Oem2 = 0x5B, /* VK_OEM_FINISH */
+            // ScanCode::Oem3 = 0x5C, /* VK_OEM_JUMP */
+            // ScanCode::Oem4 = 0x5E, /* VK_OEM_BACKTAB */
+            // ScanCode::Oem5 = 0x5F, /* VK_OEM_AUTO */
+            // ScanCode::Oem6 = 0x6F, /* VK_OEM_PA3 */
+            // ScanCode::Oem7 = 0x71, /* VK_OEM_RESET */
+            // ScanCode::EraseEOF = 0x5D,
+            // ScanCode::Zoom => 0x62,
+            // ScanCode::Help => 0x63,
+            // ScanCode::AltPrintScreen = 0x55, /* Alt + print screen. */
+            // ScanCode::SBCSChar = 0x77,
+            _ => return None,
+        }
+    } else {
+        match input & 0xFF {
+            0x10 => OsCode::KEY_PREVIOUSSONG,
+            0x19 => OsCode::KEY_NEXTSONG,
+            0x1C => OsCode::KEY_KPENTER,
+            0x1D => OsCode::KEY_RIGHTCTRL,
+            0x20 => OsCode::KEY_MUTE,
+            0x22 => OsCode::KEY_PLAYPAUSE, // sc_media_play
+            // 0x24 => OsCode::KEY_TODO, // sc_media_stop
+            0x2E => OsCode::KEY_VOLUMEDOWN, // sc_volume_down
+            0x30 => OsCode::KEY_VOLUMEUP,   // sc_volume_up
+            // 0x32 => OsCode::KEY_TODO, // sc_browser_home
+            0x35 => OsCode::KEY_KPSLASH,  // sc_numpad_divide
+            0x37 => OsCode::KEY_PRINT,    // sc_printScreen
+            0x38 => OsCode::KEY_RIGHTALT, // sc_altRight
+            // 0x46 => OsCode::KEY_TODO, // sc_cancel
+            0x47 => OsCode::KEY_HOME,      // sc_home
+            0x48 => OsCode::KEY_UP,        // sc_arrowUp
+            0x49 => OsCode::KEY_PAGEUP,    // sc_pageUp
+            0x4B => OsCode::KEY_LEFT,      // sc_arrowLeft
+            0x4D => OsCode::KEY_RIGHT,     // sc_arrowRight
+            0x4F => OsCode::KEY_END,       // sc_end
+            0x50 => OsCode::KEY_DOWN,      // sc_arrowDown
+            0x51 => OsCode::KEY_PAGEDOWN,  // sc_pageDown
+            0x52 => OsCode::KEY_INSERT,    // sc_insert
+            0x53 => OsCode::KEY_DELETE,    // sc_delete
+            0x5B => OsCode::KEY_LEFTMETA,  // sc_metaLeft
+            0x5C => OsCode::KEY_RIGHTMETA, // sc_metaRight
+            0x5D => OsCode::KEY_COMPOSE,   // sc_application / compose
+            // 0x5E => OsCode::KEY_TODO, // sc_power
+            // 0x5F => OsCode::KEY_TODO, // sc_sleep
+            // 0x63 => OsCode::KEY_TODO, // sc_wake
+            // 0x65 => OsCode::KEY_TODO, // sc_browser_search
+            // 0x66 => OsCode::KEY_TODO, // sc_browser_favorites
+            // 0x67 => OsCode::KEY_TODO, // sc_browser_refresh
+            // 0x68 => OsCode::KEY_TODO, // sc_browser_stop
+            0x69 => OsCode::KEY_FORWARD, // sc_browser_forward
+            0x6A => OsCode::KEY_BACK,    // sc_browser_back
+            // 0x6B => OsCode::KEY_TODO, // sc_launch_app1
+            // 0x6C => OsCode::KEY_TODO, // sc_launch_email
+            // 0x6D => OsCode::KEY_TODO, // sc_launch_media
+            _ => return None,
+        }
+    })
+}
+
+#[allow(unused)]
+pub(crate) fn osc_to_u16(osc: OsCode) -> Option<u16> {
+    Some(match osc {
+        OsCode::KEY_ESC => 0x01,
+        OsCode::KEY_1 => 0x02,
+        OsCode::KEY_2 => 0x03,
+        OsCode::KEY_3 => 0x04,
+        OsCode::KEY_4 => 0x05,
+        OsCode::KEY_5 => 0x06,
+        OsCode::KEY_6 => 0x07,
+        OsCode::KEY_7 => 0x08,
+        OsCode::KEY_8 => 0x09,
+        OsCode::KEY_9 => 0x0A,
+        OsCode::KEY_0 => 0x0B,
+        OsCode::KEY_MINUS => 0x0C,
+        OsCode::KEY_EQUAL => 0x0D,
+        OsCode::KEY_BACKSPACE => 0x0E,
+        OsCode::KEY_TAB => 0x0F,
+        OsCode::KEY_Q => 0x10,
+        OsCode::KEY_W => 0x11,
+        OsCode::KEY_E => 0x12,
+        OsCode::KEY_R => 0x13,
+        OsCode::KEY_T => 0x14,
+        OsCode::KEY_Y => 0x15,
+        OsCode::KEY_U => 0x16,
+        OsCode::KEY_I => 0x17,
+        OsCode::KEY_O => 0x18,
+        OsCode::KEY_P => 0x19,
+        OsCode::KEY_LEFTBRACE => 0x1A,
+        OsCode::KEY_RIGHTBRACE => 0x1B,
+        OsCode::KEY_ENTER => 0x1C,
+        OsCode::KEY_LEFTCTRL => 0x1D,
+        OsCode::KEY_A => 0x1E,
+        OsCode::KEY_S => 0x1F,
+        OsCode::KEY_D => 0x20,
+        OsCode::KEY_F => 0x21,
+        OsCode::KEY_G => 0x22,
+        OsCode::KEY_H => 0x23,
+        OsCode::KEY_J => 0x24,
+        OsCode::KEY_K => 0x25,
+        OsCode::KEY_L => 0x26,
+        OsCode::KEY_SEMICOLON => 0x27,
+        OsCode::KEY_APOSTROPHE => 0x28,
+        OsCode::KEY_GRAVE => 0x29,
+        OsCode::KEY_LEFTSHIFT => 0x2A,
+        OsCode::KEY_BACKSLASH => 0x2B,
+        OsCode::KEY_Z => 0x2C,
+        OsCode::KEY_X => 0x2D,
+        OsCode::KEY_C => 0x2E,
+        OsCode::KEY_V => 0x2F,
+        OsCode::KEY_B => 0x30,
+        OsCode::KEY_N => 0x31,
+        OsCode::KEY_M => 0x32,
+        OsCode::KEY_COMMA => 0x33,
+        OsCode::KEY_DOT => 0x34,
+        OsCode::KEY_SLASH => 0x35,
+        OsCode::KEY_RIGHTSHIFT => 0x36,
+        OsCode::KEY_KPASTERISK => 0x37,
+        OsCode::KEY_LEFTALT => 0x38,
+        OsCode::KEY_SPACE => 0x39,
+        OsCode::KEY_CAPSLOCK => 0x3A,
+        OsCode::KEY_F1 => 0x3B,
+        OsCode::KEY_F2 => 0x3C,
+        OsCode::KEY_F3 => 0x3D,
+        OsCode::KEY_F4 => 0x3E,
+        OsCode::KEY_F5 => 0x3F,
+        OsCode::KEY_F6 => 0x40,
+        OsCode::KEY_F7 => 0x41,
+        OsCode::KEY_F8 => 0x42,
+        OsCode::KEY_F9 => 0x43,
+        OsCode::KEY_F10 => 0x44,
+        OsCode::KEY_NUMLOCK => 0x45,
+        OsCode::KEY_SCROLLLOCK => 0x46,
+        OsCode::KEY_KP7 => 0x47,
+        OsCode::KEY_KP8 => 0x48,
+        OsCode::KEY_KP9 => 0x49,
+        OsCode::KEY_KPMINUS => 0x4A,
+        OsCode::KEY_KP4 => 0x4B,
+        OsCode::KEY_KP5 => 0x4C,
+        OsCode::KEY_KP6 => 0x4D,
+        OsCode::KEY_KPPLUS => 0x4E,
+        OsCode::KEY_KP1 => 0x4F,
+        OsCode::KEY_KP2 => 0x50,
+        OsCode::KEY_KP3 => 0x51,
+        OsCode::KEY_KP0 => 0x52,
+        OsCode::KEY_KPDOT => 0x53,
+        OsCode::KEY_102ND => 0x56, /* Key between the left shift and Z. */
+        OsCode::KEY_F11 => 0x57,
+        OsCode::KEY_F12 => 0x58,
+        OsCode::KEY_F13 => 0x64,
+        OsCode::KEY_F14 => 0x65,
+        OsCode::KEY_F15 => 0x66,
+        OsCode::KEY_F16 => 0x67,
+        OsCode::KEY_F17 => 0x68,
+        OsCode::KEY_F18 => 0x69,
+        OsCode::KEY_F19 => 0x6A,
+        OsCode::KEY_F20 => 0x6B,
+        OsCode::KEY_F21 => 0x6C,
+        OsCode::KEY_F22 => 0x6D,
+        OsCode::KEY_F23 => 0x6E,
+        OsCode::KEY_RO => 0x73,
+        OsCode::KEY_F24 => 0x76,
+        OsCode::KEY_KATAKANA => 0x70, // https://kbdlayout.info/kbdjpn/virtualkeys?arrangement=ISO105
+        // Apparantly SC 0x70 does not exist.
+        // But seems to be hiragana/katakana?
+        OsCode::KEY_HENKAN => 0x79,   // Convert
+        OsCode::KEY_MUHENKAN => 0x7B, // Noconvert
+        OsCode::KEY_YEN => 0x7D,      // Yen / Pipe
+        OsCode::KEY_PREVIOUSSONG => 0xE010,
+        OsCode::KEY_NEXTSONG => 0xE019,
+        OsCode::KEY_KPENTER => 0xE01C,
+        OsCode::KEY_RIGHTCTRL => 0xE01D,
+        OsCode::KEY_MUTE => 0xE020,
+        OsCode::KEY_PLAYPAUSE => 0xE022,  // sc_media_play
+        OsCode::KEY_VOLUMEDOWN => 0xE02E, // sc_volume_down
+        OsCode::KEY_VOLUMEUP => 0xE030,   // sc_volume_up
+        OsCode::KEY_KPSLASH => 0xE035,    // sc_numpad_divide
+        OsCode::KEY_PRINT => 0xE037,      // sc_printScreen
+        OsCode::KEY_RIGHTALT => 0xE038,   // sc_altRight
+        OsCode::KEY_HOME => 0xE047,       // sc_home
+        OsCode::KEY_UP => 0xE048,         // sc_arrowUp
+        OsCode::KEY_PAGEUP => 0xE049,     // sc_pageUp
+        OsCode::KEY_LEFT => 0xE04B,       // sc_arrowLeft
+        OsCode::KEY_RIGHT => 0xE04D,      // sc_arrowRight
+        OsCode::KEY_END => 0xE04F,        // sc_end
+        OsCode::KEY_DOWN => 0xE050,       // sc_arrowDown
+        OsCode::KEY_PAGEDOWN => 0xE051,   // sc_pageDown
+        OsCode::KEY_INSERT => 0xE052,     // sc_insert
+        OsCode::KEY_DELETE => 0xE053,     // sc_delete
+        OsCode::KEY_LEFTMETA => 0xE05B,   // sc_metaLeft
+        OsCode::KEY_RIGHTMETA => 0xE05C,  // sc_metaRight
+        OsCode::KEY_COMPOSE => 0xE05D,    // sc_application / compose
+        OsCode::KEY_FORWARD => 0xE069,    // sc_browser_forward
+        OsCode::KEY_BACK => 0xE06A,       // sc_browser_back
+        _ => return None,
+    })
+}
diff --git a/src/tcp_server.rs b/src/tcp_server.rs
index 8d81c2446..43bcbd44b 100644
--- a/src/tcp_server.rs
+++ b/src/tcp_server.rs
@@ -1,66 +1,147 @@
 use crate::Kanata;
+use crate::oskbd::*;
+
+#[cfg(feature = "tcp_server")]
+use kanata_tcp_protocol::*;
 use parking_lot::Mutex;
-use serde::{Deserialize, Serialize};
-use std::io::{Read, Write};
-use std::net::{TcpListener, TcpStream};
-use std::str::FromStr;
+use std::net::SocketAddr;
 use std::sync::Arc;
+use std::sync::mpsc::SyncSender as Sender;
 
+#[cfg(feature = "tcp_server")]
 type HashMap<K, V> = rustc_hash::FxHashMap<K, V>;
+#[cfg(feature = "tcp_server")]
+use kanata_parser::cfg::SimpleSExpr;
+#[cfg(feature = "tcp_server")]
+use std::io::Write;
+#[cfg(feature = "tcp_server")]
+use std::net::{TcpListener, TcpStream};
 
-#[derive(Debug, Serialize, Deserialize)]
-pub enum ServerMessage {
-    LayerChange { new: String },
-}
+#[cfg(feature = "tcp_server")]
+pub type Connections = Arc<Mutex<HashMap<String, TcpStream>>>;
 
-#[test]
-fn layer_change_serializes() {
-    serde_json::to_string(&ServerMessage::LayerChange {
-        new: "hello".into(),
-    })
-    .expect("ServerMessage serializes");
-}
+#[cfg(not(feature = "tcp_server"))]
+pub type Connections = ();
+
+#[cfg(feature = "tcp_server")]
+use kanata_parser::custom_action::FakeKeyAction;
 
-#[derive(Debug, Serialize, Deserialize)]
-pub enum ClientMessage {
-    ChangeLayer { new: String },
+#[cfg(feature = "tcp_server")]
+fn send_response(
+    stream: &mut TcpStream,
+    response: ServerResponse,
+    connections: &Connections,
+    addr: &str,
+) -> bool {
+    if let Err(write_err) = stream.write_all(&response.as_bytes()) {
+        log::error!("stream write error: {write_err}");
+        connections.lock().remove(addr);
+        return false;
+    }
+    true
 }
 
-impl ServerMessage {
-    pub fn as_bytes(&self) -> Vec<u8> {
-        serde_json::to_string(self)
-            .expect("ServerMessage should serialize")
-            .as_bytes()
-            .to_vec()
+#[cfg(feature = "tcp_server")]
+fn to_action(val: FakeKeyActionMessage) -> FakeKeyAction {
+    match val {
+        FakeKeyActionMessage::Press => FakeKeyAction::Press,
+        FakeKeyActionMessage::Release => FakeKeyAction::Release,
+        FakeKeyActionMessage::Tap => FakeKeyAction::Tap,
+        FakeKeyActionMessage::Toggle => FakeKeyAction::Toggle,
     }
 }
 
-impl FromStr for ClientMessage {
-    type Err = serde_json::Error;
+/// Handles reload commands with optional wait/timeout for completion confirmation.
+/// Returns false if the connection should be closed, true otherwise.
+#[cfg(feature = "tcp_server")]
+fn handle_reload_with_wait(
+    reload_cmd: ClientMessage,
+    wait: Option<bool>,
+    timeout_ms: Option<u64>,
+    stream: &mut TcpStream,
+    kanata: &Arc<Mutex<Kanata>>,
+    connections: &Connections,
+    addr: &str,
+) -> bool {
+    let (response, reload_ok) = match kanata.lock().handle_client_command(reload_cmd) {
+        Ok(_) => (ServerResponse::Ok, true),
+        Err(e) => (
+            ServerResponse::Error {
+                msg: format!("{e}"),
+            },
+            false,
+        ),
+    };
+    if !send_response(stream, response, connections, addr) {
+        return false;
+    }
+
+    // If wait flag is set and reload succeeded, poll for completion
+    if reload_ok && wait.unwrap_or(false) {
+        let timeout_ms = timeout_ms.unwrap_or(5000);
+        let start = std::time::Instant::now();
+        let timeout_duration = std::time::Duration::from_millis(timeout_ms);
+
+        while start.elapsed() < timeout_duration {
+            if kanata.lock().is_reload_complete() {
+                break;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(50));
+        }
+        let timed_out = start.elapsed() >= timeout_duration;
 
-    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
-        serde_json::from_str(s)
+        let ok = kanata.lock().last_reload_succeeded();
+        let msg = ServerMessage::ReloadResult {
+            ok,
+            timeout_ms: if timed_out { Some(timeout_ms) } else { None },
+        };
+        if let Err(err) = stream.write_all(&msg.as_bytes()) {
+            log::error!("Error writing ReloadResult: {err}");
+            connections.lock().remove(addr);
+            return false;
+        }
+        let _ = stream.flush();
     }
+    true
+}
+
+#[cfg(feature = "tcp_server")]
+pub struct TcpServer {
+    pub address: SocketAddr,
+    pub connections: Connections,
+    pub wakeup_channel: Sender<KeyEvent>,
 }
 
+#[cfg(not(feature = "tcp_server"))]
 pub struct TcpServer {
-    pub port: i32,
-    pub connections: Arc<Mutex<HashMap<String, TcpStream>>>,
+    pub connections: Connections,
 }
 
 impl TcpServer {
-    pub fn new(port: i32) -> Self {
+    #[cfg(feature = "tcp_server")]
+    pub fn new(address: SocketAddr, wakeup_channel: Sender<KeyEvent>) -> Self {
         Self {
-            port,
+            address,
             connections: Arc::new(Mutex::new(HashMap::default())),
+            wakeup_channel,
         }
     }
 
+    #[cfg(not(feature = "tcp_server"))]
+    pub fn new(_address: SocketAddr, _wakeup_channel: Sender<KeyEvent>) -> Self {
+        Self { connections: () }
+    }
+
+    #[cfg(feature = "tcp_server")]
     pub fn start(&mut self, kanata: Arc<Mutex<Kanata>>) {
-        let listener =
-            TcpListener::bind(format!("0.0.0.0:{}", self.port)).expect("TCP server starts");
+        use kanata_parser::cfg::FAKE_KEY_ROW;
+
+        use crate::kanata::handle_fakekey_action;
+
+        let listener = TcpListener::bind(self.address).expect("TCP server starts");
 
         let connections = self.connections.clone();
+        let wakeup_channel = self.wakeup_channel.clone();
 
         std::thread::spawn(move || {
             for stream in listener.incoming() {
@@ -82,51 +163,297 @@ impl TcpServer {
                             }
                         }
 
-                        let addr = stream
-                            .peer_addr()
-                            .expect("incoming conn has known address")
-                            .to_string();
+                        let addr = match stream.peer_addr() {
+                            Ok(addr) => addr.to_string(),
+                            Err(e) => {
+                                log::warn!("failed to get peer address, using fallback: {e:?}");
+                                format!("unknown_{}", std::ptr::addr_of!(stream) as usize)
+                            }
+                        };
 
                         connections.lock().insert(
                             addr.clone(),
                             stream.try_clone().expect("stream is clonable"),
                         );
+                        let reader = serde_json::Deserializer::from_reader(
+                            stream.try_clone().expect("stream is clonable"),
+                        )
+                        .into_iter::<ClientMessage>();
 
-                        log::info!("listening for incoming messages {}", &addr);
+                        log::info!("listening for incoming messages {addr}");
 
                         let connections = connections.clone();
                         let kanata = kanata.clone();
-                        std::thread::spawn(move || loop {
-                            let mut buf = vec![0; 1024];
-                            match stream.read(&mut buf) {
-                                Ok(size) => {
-                                    if let Ok(event) = ClientMessage::from_str(
-                                        &String::from_utf8_lossy(&buf[..size]),
-                                    ) {
+                        let wakeup_channel = wakeup_channel.clone();
+                        std::thread::spawn(move || {
+                            for v in reader {
+                                match v {
+                                    Ok(event) => {
+                                        log::debug!("tcp server received command: {:?}", event);
                                         match event {
                                             ClientMessage::ChangeLayer { new } => {
                                                 kanata.lock().change_layer(new);
                                             }
+                                            ClientMessage::RequestLayerNames {} => {
+                                                let msg = ServerMessage::LayerNames {
+                                                    names: kanata
+                                                        .lock()
+                                                        .layer_info
+                                                        .iter()
+                                                        .map(|info| info.name.clone())
+                                                        .collect::<Vec<_>>(),
+                                                };
+                                                match stream.write_all(&msg.as_bytes()) {
+                                                    Ok(_) => {}
+                                                    Err(err) => log::error!(
+                                                        "server could not send response: {err}"
+                                                    ),
+                                                }
+                                            }
+                                            ClientMessage::RequestFakeKeyNames {} => {
+                                                let msg = ServerMessage::FakeKeyNames {
+                                                    names: kanata
+                                                        .lock()
+                                                        .virtual_keys
+                                                        .keys()
+                                                        .cloned()
+                                                        .collect::<Vec<_>>(),
+                                                };
+                                                match stream.write_all(&msg.as_bytes()) {
+                                                    Ok(_) => {}
+                                                    Err(err) => log::error!(
+                                                        "server could not send response: {err}"
+                                                    ),
+                                                }
+                                            }
+                                            ClientMessage::ActOnFakeKey { name, action } => {
+                                                let mut k = kanata.lock();
+                                                let index = match k.virtual_keys.get(&name) {
+                                                    Some(index) => Some(*index as u16),
+                                                    None => {
+                                                        if let Err(e) = stream.write_all(
+                                                            &ServerMessage::Error {
+                                                                msg: format!(
+                                                                    "unknown virtual/fake key: {name}"
+                                                                ),
+                                                            }
+                                                            .as_bytes(),
+                                                        ) {
+                                                            log::error!("stream write error: {e}");
+                                                            connections.lock().remove(&addr);
+                                                            break;
+                                                        }
+                                                        continue;
+                                                    }
+                                                };
+                                                if let Some(index) = index {
+                                                    log::info!(
+                                                        "tcp server fake-key action: {name},{action:?}"
+                                                    );
+                                                    handle_fakekey_action(
+                                                        to_action(action),
+                                                        k.layout.bm(),
+                                                        FAKE_KEY_ROW,
+                                                        index,
+                                                    );
+                                                }
+                                                drop(k);
+                                            }
+                                            ClientMessage::SetMouse { x, y } => {
+                                                log::info!(
+                                                    "tcp server SetMouse action: x {x} y {y}"
+                                                );
+                                                match kanata.lock().kbd_out.set_mouse(x, y) {
+                                                    Ok(_) => {
+                                                        log::info!(
+                                                            "sucessfully did set mouse position to: x {x} y {y}"
+                                                        );
+                                                    }
+                                                    Err(e) => {
+                                                        log::error!(
+                                                            "Failed to set mouse position: {}",
+                                                            e
+                                                        );
+                                                    }
+                                                }
+                                            }
+                                            ClientMessage::RequestCurrentLayerInfo {} => {
+                                                let mut k = kanata.lock();
+                                                let cur_layer = k.layout.bm().current_layer();
+                                                let msg = ServerMessage::CurrentLayerInfo {
+                                                    name: k.layer_info[cur_layer].name.clone(),
+                                                    cfg_text: k.layer_info[cur_layer]
+                                                        .cfg_text
+                                                        .clone(),
+                                                };
+                                                drop(k);
+                                                match stream.write_all(&msg.as_bytes()) {
+                                                    Ok(_) => {}
+                                                    Err(err) => log::error!(
+                                                        "Error writing response to RequestCurrentLayerInfo: {err}"
+                                                    ),
+                                                }
+                                            }
+                                            ClientMessage::RequestCurrentLayerName {} => {
+                                                let mut k = kanata.lock();
+                                                let cur_layer = k.layout.bm().current_layer();
+                                                let msg = ServerMessage::CurrentLayerName {
+                                                    name: k.layer_info[cur_layer].name.clone(),
+                                                };
+                                                drop(k);
+                                                match stream.write_all(&msg.as_bytes()) {
+                                                    Ok(_) => {}
+                                                    Err(err) => log::error!(
+                                                        "Error writing response to RequestCurrentLayerName: {err}"
+                                                    ),
+                                                }
+                                            }
+                                            // New command: Hello - capability detection
+                                            ClientMessage::Hello {} => {
+                                                let version = env!("CARGO_PKG_VERSION").to_string();
+                                                let capabilities = vec![
+                                                    "reload".to_string(),
+                                                    "layer-names".to_string(),
+                                                    "fake-key-names".to_string(),
+                                                    "layer-change".to_string(),
+                                                    "hold-activated".to_string(),
+                                                    "tap-activated".to_string(),
+                                                    "current-layer-name".to_string(),
+                                                    "current-layer-info".to_string(),
+                                                    "fake-key".to_string(),
+                                                    "set-mouse".to_string(),
+                                                ];
+                                                let msg = ServerMessage::HelloOk {
+                                                    version,
+                                                    protocol: 1,
+                                                    capabilities,
+                                                };
+                                                match stream.write_all(&msg.as_bytes()) {
+                                                    Ok(_) => {
+                                                        let _ = stream.flush();
+                                                    }
+                                                    Err(err) => {
+                                                        log::error!(
+                                                            "Error writing HelloOk response: {err}"
+                                                        );
+                                                        connections.lock().remove(&addr);
+                                                        break;
+                                                    }
+                                                }
+                                            }
+                                            // Reload commands with optional wait/timeout
+                                            ClientMessage::Reload { wait, timeout_ms } => {
+                                                log::info!("tcp server Reload action");
+                                                if !handle_reload_with_wait(
+                                                    ClientMessage::Reload { wait, timeout_ms },
+                                                    wait,
+                                                    timeout_ms,
+                                                    &mut stream,
+                                                    &kanata,
+                                                    &connections,
+                                                    &addr,
+                                                ) {
+                                                    break;
+                                                }
+                                            }
+                                            ClientMessage::ReloadNext { wait, timeout_ms } => {
+                                                log::info!("tcp server ReloadNext action");
+                                                if !handle_reload_with_wait(
+                                                    ClientMessage::ReloadNext { wait, timeout_ms },
+                                                    wait,
+                                                    timeout_ms,
+                                                    &mut stream,
+                                                    &kanata,
+                                                    &connections,
+                                                    &addr,
+                                                ) {
+                                                    break;
+                                                }
+                                            }
+                                            ClientMessage::ReloadPrev { wait, timeout_ms } => {
+                                                log::info!("tcp server ReloadPrev action");
+                                                if !handle_reload_with_wait(
+                                                    ClientMessage::ReloadPrev { wait, timeout_ms },
+                                                    wait,
+                                                    timeout_ms,
+                                                    &mut stream,
+                                                    &kanata,
+                                                    &connections,
+                                                    &addr,
+                                                ) {
+                                                    break;
+                                                }
+                                            }
+                                            ClientMessage::ReloadNum {
+                                                index,
+                                                wait,
+                                                timeout_ms,
+                                            } => {
+                                                log::info!(
+                                                    "tcp server ReloadNum action: index {index}"
+                                                );
+                                                if !handle_reload_with_wait(
+                                                    ClientMessage::ReloadNum {
+                                                        index,
+                                                        wait,
+                                                        timeout_ms,
+                                                    },
+                                                    wait,
+                                                    timeout_ms,
+                                                    &mut stream,
+                                                    &kanata,
+                                                    &connections,
+                                                    &addr,
+                                                ) {
+                                                    break;
+                                                }
+                                            }
+                                            ClientMessage::ReloadFile {
+                                                path,
+                                                wait,
+                                                timeout_ms,
+                                            } => {
+                                                log::info!(
+                                                    "tcp server ReloadFile action: path {path}"
+                                                );
+                                                if !handle_reload_with_wait(
+                                                    ClientMessage::ReloadFile {
+                                                        path,
+                                                        wait,
+                                                        timeout_ms,
+                                                    },
+                                                    wait,
+                                                    timeout_ms,
+                                                    &mut stream,
+                                                    &kanata,
+                                                    &connections,
+                                                    &addr,
+                                                ) {
+                                                    break;
+                                                }
+                                            }
                                         }
-                                    } else {
+                                        use kanata_parser::keys::*;
+                                        wakeup_channel
+                                            .send(KeyEvent::new(
+                                                OsCode::KEY_RESERVED,
+                                                KeyValue::WakeUp,
+                                            ))
+                                            .expect("write key event");
+                                    }
+                                    Err(e) => {
                                         log::warn!(
-                                            "client sent an invalid message of size {size}, disconnecting them"
-                                        );
-                                        // Ignore write result because we're about to disconnect
-                                        // the client anyway.
-                                        let _ = stream.write(
-                                            "you sent an invalid message; disconnecting you"
-                                                .as_bytes(),
+                                            "client sent an invalid message, disconnecting them. Err: {e:?}"
                                         );
+                                        // Send proper error response for malformed JSON
+                                        let response = ServerResponse::Error {
+                                            msg: format!("Failed to deserialize command: {e}"),
+                                        };
+                                        let _ = stream.write_all(&response.as_bytes());
                                         connections.lock().remove(&addr);
                                         break;
                                     }
                                 }
-                                Err(_) => {
-                                    log::warn!("removing disconnected tcp client: {addr}");
-                                    connections.lock().remove(&addr);
-                                    break;
-                                }
                             }
                         });
                     }
@@ -135,4 +462,21 @@ impl TcpServer {
             }
         });
     }
+
+    #[cfg(not(feature = "tcp_server"))]
+    pub fn start(&mut self, _kanata: Arc<Mutex<Kanata>>) {}
+}
+
+#[cfg(feature = "tcp_server")]
+pub fn simple_sexpr_to_json_array(exprs: &[SimpleSExpr]) -> serde_json::Value {
+    let mut result = Vec::new();
+
+    for expr in exprs.iter() {
+        match expr {
+            SimpleSExpr::Atom(s) => result.push(serde_json::Value::String(s.clone())),
+            SimpleSExpr::List(list) => result.push(simple_sexpr_to_json_array(list)),
+        }
+    }
+
+    serde_json::Value::Array(result)
 }
diff --git a/src/tests.rs b/src/tests.rs
new file mode 100644
index 000000000..af5ea833a
--- /dev/null
+++ b/src/tests.rs
@@ -0,0 +1,189 @@
+use kanata_parser::cfg::*;
+use std::sync::Mutex;
+
+#[cfg(all(
+    feature = "simulated_output",
+    not(feature = "simulated_input"),
+    not(feature = "interception_driver")
+))]
+mod sim_tests;
+
+#[cfg(all(
+    target_os = "macos",
+    feature = "simulated_input",
+    feature = "simulated_output"
+))]
+mod passthru_macos_tests;
+
+pub(crate) static CFG_PARSE_LOCK: Mutex<()> = Mutex::new(());
+
+fn init_log() {
+    use simplelog::*;
+    use std::sync::OnceLock;
+    static LOG_INIT: OnceLock<()> = OnceLock::new();
+    LOG_INIT.get_or_init(|| {
+        let mut log_cfg = ConfigBuilder::new();
+        if let Err(e) = log_cfg.set_time_offset_to_local() {
+            eprintln!("WARNING: could not set log TZ to local: {e:?}");
+        };
+        log_cfg.set_time_format_rfc3339();
+        CombinedLogger::init(vec![TermLogger::new(
+            // Note: set to a different level to see logs in tests.
+            // Also, not all tests call init_log so you might have to add the call there too.
+            LevelFilter::Off,
+            log_cfg.build(),
+            TerminalMode::Stderr,
+            ColorChoice::AlwaysAnsi,
+        )])
+        .expect("logger can init");
+    });
+}
+
+// Do not run during simulated input testing
+// because those will manipulate the deflocalkeys globals
+// which interferes with these tests.
+#[cfg(not(feature = "simulated_input"))]
+mod parse_samples {
+    use super::*;
+
+    #[test]
+    fn parse_simple() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/simple.kbd")).unwrap();
+    }
+
+    #[test]
+    fn parse_minimal() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/minimal.kbd")).unwrap();
+    }
+
+    #[test]
+    fn parse_deflayermap() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/deflayermap.kbd")).unwrap();
+    }
+
+    #[test]
+    fn parse_default() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/kanata.kbd")).unwrap();
+    }
+
+    #[test]
+    fn parse_jtroo() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        let cfg = new_from_file(&std::path::PathBuf::from("./cfg_samples/jtroo.kbd")).unwrap();
+        assert_eq!(cfg.layer_info.len(), 8);
+    }
+
+    #[test]
+    fn parse_f13_f24() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/f13_f24.kbd")).unwrap();
+    }
+
+    #[test]
+    fn parse_home_row_mods() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from(
+            "./cfg_samples/home-row-mod-basic.kbd",
+        ))
+        .unwrap();
+        new_from_file(&std::path::PathBuf::from(
+            "./cfg_samples/home-row-mod-advanced.kbd",
+        ))
+        .unwrap();
+    }
+
+    #[test]
+    fn parse_press_release_toggle_vkeys() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from(
+            "./cfg_samples/key-toggle_press-only_release-only.kbd",
+        ))
+        .unwrap();
+    }
+
+    #[test]
+    fn parse_automousekeys_only() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from(
+            "./cfg_samples/automousekeys-only.kbd",
+        ))
+        .unwrap();
+    }
+
+    #[test]
+    fn parse_automousekeys_full_map() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from(
+            "./cfg_samples/automousekeys-full-map.kbd",
+        ))
+        .unwrap();
+    }
+
+    #[test]
+    fn parse_push_msg() {
+        init_log();
+        let _lk = match CFG_PARSE_LOCK.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        new_from_file(&std::path::PathBuf::from("./cfg_samples/push-msg.kbd")).unwrap();
+    }
+
+    #[test]
+    #[cfg(target_pointer_width = "64")]
+    fn sizeof_state() {
+        init_log();
+        assert_eq!(
+            std::mem::size_of::<
+                kanata_keyberon::layout::State<
+                    &'static &'static [&'static kanata_parser::custom_action::CustomAction],
+                >,
+            >(),
+            2 * std::mem::size_of::<usize>()
+        );
+    }
+}
diff --git a/src/tests/passthru_macos_tests.rs b/src/tests/passthru_macos_tests.rs
new file mode 100644
index 000000000..82176ef45
--- /dev/null
+++ b/src/tests/passthru_macos_tests.rs
@@ -0,0 +1,36 @@
+use crate::oskbd::{KeyEvent, KeyValue};
+use crate::{Kanata, ValidatedArgs, str_to_oscode};
+use std::path::PathBuf;
+use std::sync::mpsc;
+
+fn passthru_args() -> ValidatedArgs {
+    ValidatedArgs {
+        paths: vec![PathBuf::from("./cfg_samples/minimal.kbd")],
+        #[cfg(feature = "tcp_server")]
+        tcp_server_address: None,
+        nodelay: true,
+    }
+}
+
+#[test]
+fn passthru_runtime_output_channel_is_ready_and_emits_events() {
+    let args = passthru_args();
+    let (tx, rx) = mpsc::channel();
+    let runtime = Kanata::new_with_output_channel(&args, Some(tx)).expect("passthru runtime");
+
+    {
+        let mut runtime = runtime.lock();
+        assert!(runtime.kbd_out.output_ready());
+
+        let key = str_to_oscode("a").expect("key code");
+        runtime
+            .kbd_out
+            .write_key(key, KeyValue::Press)
+            .expect("write key through passthru output");
+    }
+
+    let event = rx.try_recv().expect("passthru output event");
+    let key_event = KeyEvent::try_from(event).expect("output event should decode");
+    assert_eq!(key_event.code, str_to_oscode("a").expect("key code"));
+    assert_eq!(key_event.value, KeyValue::Press);
+}
diff --git a/src/tests/sim_tests/block_keys_tests.rs b/src/tests/sim_tests/block_keys_tests.rs
new file mode 100644
index 000000000..24f41bac4
--- /dev/null
+++ b/src/tests/sim_tests/block_keys_tests.rs
@@ -0,0 +1,35 @@
+use super::*;
+
+#[test]
+fn block_does_not_block_buttons() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys yes
+                   block-unmapped-keys yes)
+        (defsrc)
+        (deflayer base)",
+        "d:mlft d:mrgt d:mmid d:mbck d:mfwd t:10 d:f1
+         u:mlft u:mrgt u:mmid u:mbck u:mfwd t:10 u:f1",
+    );
+    assert_eq!(
+        "out🖰:↓Left\nt:1ms\nout🖰:↓Right\nt:1ms\nout🖰:↓Mid\nt:1ms\nout🖰:↓Backward\n\
+               t:1ms\nout🖰:↓Forward\nt:7ms\nout🖰:↑Left\nt:1ms\nout🖰:↑Right\nt:1ms\nout🖰:↑Mid\n\
+               t:1ms\nout🖰:↑Backward\nt:1ms\nout🖰:↑Forward",
+        result
+    );
+}
+
+#[test]
+fn block_does_not_block_wheel() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys yes
+                   block-unmapped-keys yes)
+        (defsrc)
+        (deflayer base)",
+        "d:mwu d:mwd d:mwl d:mwr t:10 d:f1
+         u:mwu u:mwd u:mwl u:mwr t:10 u:f1",
+    );
+    assert_eq!(
+        "scroll:Up,120\nt:1ms\nscroll:Down,120\nt:1ms\nscroll:Left,120\nt:1ms\nscroll:Right,120",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/capsword_sim_tests.rs b/src/tests/sim_tests/capsword_sim_tests.rs
new file mode 100644
index 000000000..141fe9716
--- /dev/null
+++ b/src/tests/sim_tests/capsword_sim_tests.rs
@@ -0,0 +1,104 @@
+use super::*;
+
+const CFG: &str = r##"
+ (defcfg)
+ (defsrc 7 8 9 0)
+ (deflayer base
+     (caps-word 1000)
+     (caps-word-custom 200 (a) (b))
+     (caps-word-toggle 1000)
+     (caps-word-custom-toggle 200 (a) (b))
+ )
+"##;
+
+#[test]
+fn caps_word_behaves_correctly() {
+    let result = simulate(
+        CFG,
+        "d:7 u:7 d:a u:a d:1 u:1 d:a u:a d:spc u:spc d:a u:a t:1000",
+    )
+    .no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓Kb1 out:↑Kb1 out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓Space out:↑Space out:↓A out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_custom_behaves_correctly() {
+    let result = simulate(
+        CFG,
+        "d:8 u:8 d:a u:a d:b u:b d:a u:a d:1 u:1 d:a u:a t:1000",
+    )
+    .no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓B out:↑B out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓Kb1 out:↑Kb1 out:↓A out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_times_out() {
+    let result = simulate(CFG, "d:7 u:7 d:a u:a t:500 d:a u:a t:1001 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓A out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_custom_times_out() {
+    let result = simulate(CFG, "d:8 u:8 d:a u:a t:100 d:a u:a t:201 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓A out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_does_not_toggle() {
+    let result = simulate(CFG, "d:7 u:7 d:a u:a t:100 d:7 u:7 t:100 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓LShift out:↓A out:↑LShift out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_custom_does_not_toggle() {
+    let result = simulate(CFG, "d:8 u:8 d:a u:a t:100 d:8 u:8 t:100 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓LShift out:↓A out:↑LShift out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_toggle_does_toggle() {
+    let result = simulate(CFG, "d:9 u:9 d:a u:a t:100 d:9 u:9 t:100 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓A out:↑A",
+        result
+    );
+}
+
+#[test]
+fn caps_word_custom_toggle_does_toggle() {
+    let result = simulate(CFG, "d:0 u:0 d:a u:a t:100 d:0 u:0 t:100 d:a u:a t:10").no_time();
+    assert_eq!(
+        "out:↓LShift out:↓A out:↑LShift out:↑A \
+         out:↓A out:↑A",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/chord_sim_tests.rs b/src/tests/sim_tests/chord_sim_tests.rs
new file mode 100644
index 000000000..e910d89cf
--- /dev/null
+++ b/src/tests/sim_tests/chord_sim_tests.rs
@@ -0,0 +1,534 @@
+use super::*;
+
+static SIMPLE_NONOVERLAPPING_CHORD_CFG: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes) \
+(defsrc) \
+(defalias c c)
+(defvar d d)
+(deflayer base) \
+(defchordsv2 \
+  (a b) @c 200 all-released () \
+  (b z) $d 200 first-release () \
+)";
+
+#[test]
+fn sim_chord_basic_repeated_last_release() {
+    let result = simulate(
+        SIMPLE_NONOVERLAPPING_CHORD_CFG,
+        "d:a t:50 d:b t:50 u:a t:50 u:b t:50 \
+         d:b t:50 d:a t:50 u:b t:50 u:a t:50 ",
+    );
+    assert_eq!(
+        "t:50ms\nout:↓C\nt:102ms\nout:↑C\nt:98ms\nout:↓C\nt:102ms\nout:↑C",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_min_idle_takes_effect() {
+    let result = simulate(
+        SIMPLE_NONOVERLAPPING_CHORD_CFG,
+        "d:z t:20 d:a t:20 d:b t:20 d:d t:20",
+    );
+    assert_eq!(
+        "t:21ms
+out:↓Z
+t:1ms
+out:↓A
+t:39ms
+out:↓B
+t:1ms
+out:↓D",
+        result
+    );
+}
+
+#[test]
+fn sim_timeout_hold_key() {
+    let result = simulate(SIMPLE_NONOVERLAPPING_CHORD_CFG, "d:z t:201 d:b t:200");
+    assert_eq!(
+        "t:201ms
+out:↓Z
+t:1ms
+out:↓B",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_basic_repeated_first_release() {
+    let result = simulate(
+        SIMPLE_NONOVERLAPPING_CHORD_CFG,
+        "d:z t:50 d:b t:50 u:z t:50 u:b t:50 \
+        d:z t:50 d:b t:50 u:z t:50 u:b t:50 ",
+    );
+    assert_eq!(
+        "t:50ms\nout:↓D\nt:52ms\nout:↑D\nt:148ms\nout:↓D\nt:52ms\nout:↑D",
+        result
+    );
+}
+
+static SIMPLE_OVERLAPPING_CHORD_CFG: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes
+ chords-v2-min-idle-experimental 5)
+(defsrc)
+(deflayer base)
+(defchordsv2-experimental
+  (a b) c 200 all-released ()
+  (a b z) d 250 first-release ()
+  (a b z y) e 400 first-release ()
+)";
+
+#[test]
+fn sim_chord_overlapping_timeout() {
+    let result = simulate(SIMPLE_OVERLAPPING_CHORD_CFG, "d:a d:b t:201 d:z t:500").to_ascii();
+    assert_eq!("t:400ms dn:D", result);
+}
+
+#[test]
+fn sim_chord_overlapping_timeout_v2() {
+    let result = simulate(
+        "
+(defcfg process-unmapped-keys yes
+ concurrent-tap-hold yes)
+(defsrc e f j)
+(deflayermap (layer1))
+(defchordsv2
+ (e f) lctl 5 all-released ()
+ (f j) ret  10 first-release ()
+)
+        ",
+        "d:f t:7 d:j t:100",
+    )
+    .to_ascii();
+    assert_eq!("t:7ms dn:Enter", result);
+}
+
+#[test]
+fn sim_chord_pending_can_still_evaluate_to_individual() {
+    let result = simulate(
+        "
+(defcfg process-unmapped-keys yes
+ concurrent-tap-hold yes)
+(defsrc e f j)
+(deflayermap (layer1))
+(defchordsv2
+ (e f) lctl 5 all-released ()
+ (e f j) lsft 10 all-released ()
+)
+        ",
+        "d:e t:7 d:f t:15",
+    )
+    .to_ascii();
+    assert_eq!("t:11ms dn:E t:1ms dn:F", result);
+}
+
+#[test]
+fn sim_chord_overlapping_release() {
+    let result = simulate(
+        SIMPLE_OVERLAPPING_CHORD_CFG,
+        "d:a d:b t:100 u:a d:z t:300 u:b t:300",
+    )
+    .to_ascii();
+    assert_eq!("t:100ms dn:C t:401ms dn:Z t:3ms up:C", result);
+}
+
+#[test]
+fn sim_presses_for_old_chord_repress_into_new_chord() {
+    let result = simulate(
+        SIMPLE_OVERLAPPING_CHORD_CFG,
+        "d:a d:b t:50 u:a t:50 d:z t:50 u:b t:50 d:a d:b t:50 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:50ms dn:C t:200ms dn:D t:11ms up:C t:1ms up:D", result);
+}
+
+#[test]
+fn sim_chord_activate_largest_overlapping() {
+    let result = simulate(
+        SIMPLE_OVERLAPPING_CHORD_CFG,
+        "d:a t:50 d:b t:50 d:z t:50 d:y t:50 u:b t:50",
+    );
+    assert_eq!("t:150ms\nout:↓E\nt:52ms\nout:↑E", result);
+}
+
+static SIMPLE_DISABLED_LAYER_CHORD_CFG: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes)
+(defsrc)
+(deflayermap (1) 2 (layer-switch 2)
+                 3 (layer-switch 3))
+(deflayermap (2) 3 (layer-while-held 3)
+                 1 (layer-while-held 1))
+(deflayermap (3) 2 (layer-while-held 2)
+                 1 (layer-while-held 1))
+(defchordsv2
+  (a b) x 200 all-released (1)
+  (c d) y 200 all-released (2)
+  (e f) z 200 all-released (3)
+)";
+
+#[test]
+fn sim_chord_layer_1_switch_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:1ms\nout:↓A\nt:50ms\nout:↓B\nt:99ms\nout:↓Y\nt:100ms\nout:↓Z",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_2_switch_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:2 t:50 d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:100ms\nout:↓X\nt:51ms\nout:↓C\nt:50ms\nout:↓D\nt:99ms\nout:↓Z",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_3_switch_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:3 t:50 d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:100ms\nout:↓X\nt:100ms\nout:↓Y\nt:51ms\nout:↓E\nt:50ms\nout:↓F",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_1_held_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:3 t:50 d:1 t:50 d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:101ms\nout:↓A\nt:50ms\nout:↓B\nt:99ms\nout:↓Y\nt:100ms\nout:↓Z",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_2_held_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:3 t:50 d:2 t:50 d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:150ms\nout:↓X\nt:51ms\nout:↓C\nt:50ms\nout:↓D\nt:99ms\nout:↓Z",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_3_held_disabled() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:2 t:50 d:3 t:50 d:a t:50 d:b t:50 d:c t:50 d:d t:50 d:e t:50 d:f t:50",
+    );
+    assert_eq!(
+        "t:150ms\nout:↓X\nt:100ms\nout:↓Y\nt:51ms\nout:↓E\nt:50ms\nout:↓F",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_layer_3_repeat() {
+    let result = simulate(
+        SIMPLE_DISABLED_LAYER_CHORD_CFG,
+        "d:3 t:50 d:a t:50 d:b t:50 r:b t:50 r:b t:50\n\
+         d:d t:50 d:c t:50 r:c t:50 r:d t:50",
+    );
+    assert_eq!(
+        "t:100ms\nout:↓X\nt:50ms\nout:↓X\nt:50ms\nout:↓X\n\
+         t:100ms\nout:↓Y\nt:50ms\nout:↓Y\nt:50ms\nout:↓Y",
+        result
+    );
+}
+
+static CHORD_INTO_TAP_HOLD_CFG: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes)
+(defsrc)
+(deflayer base)
+(defchordsv2
+  (a b) (tap-hold 200 200 x y) 200 all-released ()
+)";
+
+#[test]
+fn sim_chord_into_tap_hold() {
+    let result = simulate(
+        CHORD_INTO_TAP_HOLD_CFG,
+        "d:a t:50 d:b t:150 u:a u:b t:5 \
+         d:a t:50 d:b t:149 u:a u:b t:1000",
+    );
+    assert_eq!(
+        "t:199ms\nout:↓Y\nt:10ms\nout:↑Y\nt:195ms\nout:↓X\nt:10ms\nout:↑X",
+        result
+    );
+}
+
+static CHORD_WITH_PENDING_UNDERLYING_TAP_HOLD: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes)
+(defsrc)
+(deflayermap (base) a (tap-hold 200 200 a b))
+(defchordsv2
+  (b c) d 100 all-released ()
+)";
+
+#[test]
+fn sim_chord_pending_tap_hold() {
+    let result = simulate(
+        CHORD_WITH_PENDING_UNDERLYING_TAP_HOLD,
+        "d:a t:10 d:b t:10 d:c t:300",
+    );
+    // unlike other actions, chordv2 activations
+    // are intentionally not delayed by waiting actions like tap-hold.
+    assert_eq!("t:20ms\nout:↓D\nt:179ms\nout:↓B", result);
+}
+
+static CHORD_WITH_TRANSPARENCY: &str = "\
+(defcfg process-unmapped-keys yes concurrent-tap-hold yes)
+(defsrc)
+(deflayer base)
+(defchordsv2
+  (a b) _ 100 all-released ()
+)";
+
+#[test]
+#[should_panic]
+fn sim_denies_transparent() {
+    simulate(CHORD_WITH_TRANSPARENCY, "");
+}
+
+#[test]
+fn sim_chord_eager_tapholdpress_activation() {
+    let result = simulate(
+        "
+    (defcfg concurrent-tap-hold yes)
+    (defsrc caps j k bspc)
+    (deflayer one (tap-hold-press 0 200 esc lctl) j k bspc)
+    (defvirtualkeys bspc bspc)
+    (defchordsv2
+      (j k) (multi
+        (on-press press-vkey bspc)
+        (on-release release-vkey bspc)
+        (fork XX bspc (nop9))) 75 first-release ()
+    )
+        ",
+        "d:caps t:10 d:j d:k t:100 r:bspc t:10 r:bspc t:10 u:j u:k t:100 u:caps t:1000",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:12ms dn:LCtrl t:7ms dn:BSpace t:91ms dn:BSpace t:10ms dn:BSpace t:15ms up:BSpace t:95ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_eager_tapholdrelease_activation() {
+    let result = simulate(
+        "
+(defcfg concurrent-tap-hold yes)
+(defsrc)
+(deflayermap (base)
+  caps (tap-hold-release 0 200 esc lctl))
+
+;; defines a vkey named v-$key, example v-bspc
+;; and an alias @v-bspc that press and and releases the v-key
+;; within on-press and on-release respectively.
+(deftemplate v- (key)
+  (defvirtualkeys (concat v- $key) $key)
+  (defalias (concat v- $key)
+    (multi (on-press press-vkey (concat v- $key)) (on-release release-vkey (concat v- $key))))
+)
+
+(t! v- bspc)
+(t! v- del)
+(defchordsv2
+  (j k) @v-bspc 75 first-release ()
+  (s d) @v-del 75 first-release ()
+)
+        ",
+        "d:caps t:10 d:j d:k t:10 u:j u:k t:100 u:caps t:1000",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:20ms dn:LCtrl t:7ms dn:BSpace t:6ms up:BSpace t:87ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_release_nonchord_key_has_correct_order() {
+    let result = simulate(
+        "
+    (defcfg concurrent-tap-hold yes)
+    (defsrc ralt j k)
+    (deflayer base _ _ _)
+    (defchordsv2
+      (j k) l 75 first-release ()
+    )
+        ",
+        "d:ralt t:1000 d:j t:1 u:ralt t:100 u:j t:100",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:1ms dn:RAlt t:1075ms dn:J t:1ms up:RAlt t:24ms up:J",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_simultaneous_macro() {
+    let result = simulate(
+        "
+        (defsrc a b o)
+        (deflayer default
+          (chord base a)
+          (chord base b)
+          (chord base o)
+        )
+        (defchords base 500
+          (a) (macro a z)
+          (b) (macro b)
+          (o) o
+          (a o) o
+        )
+        ",
+        "d:a t:10 d:b t:500",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:502ms dn:A dn:B t:1ms up:A up:B t:1ms dn:Z t:1ms up:Z",
+        result
+    );
+}
+
+#[test]
+#[should_panic]
+fn sim_chord_error_on_duplicate_keyset() {
+    simulate(
+        "
+(defcfg concurrent-tap-hold yes)
+(defsrc)
+(deflayer base)
+(defchordsv2
+ (1 2) (one-shot 2000 lsft) 20 all-released ()
+ (2 1) (one-shot 2000 lctl) 20 all-released ()
+)
+        ",
+        "",
+    );
+}
+
+#[test]
+fn sim_chord_oneshot() {
+    let result = simulate(
+        "
+(defcfg concurrent-tap-hold yes)
+(defsrc)(deflayer base)
+(defchordsv2
+  (a b) (one-shot 2500 rsft) 35 first-release ()
+)
+        ",
+        "d:a t:10 d:b t:10 u:a t:10 u:b t:3000 \
+         d:a t:10 d:b t:10 u:a t:10 u:b t:500 d:c u:c t:3000",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:10ms dn:RShift t:2500ms up:RShift t:530ms \
+         dn:RShift t:521ms dn:C t:5ms up:RShift up:C",
+        result
+    );
+}
+
+#[test]
+fn sim_chord_timeout_events() {
+    let result = simulate(
+        "
+(defcfg
+ concurrent-tap-hold yes
+ process-unmapped-keys yes
+)
+(defvirtualkeys
+ v-macro-word-end (macro spc)
+)
+(defsrc a b c)
+(defchordsv2-experimental
+ (a b c) (macro x y z (on-press tap-vkey v-macro-word-end)) 200 all-released ()
+ (a b) (macro x y (on-press tap-vkey v-macro-word-end)) 200 all-released ()
+)
+(deflayer base a b c)
+        ",
+        "d:a t:10 d:b t:3000 u:a u:b t:100",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:201ms dn:X t:1ms up:X t:1ms dn:Y t:1ms up:Y t:4ms dn:Space t:1ms up:Space",
+        result
+    );
+}
+
+#[test]
+fn sim_chordsv2_quick_release() {
+    let result = simulate(
+        "
+(defsrc)
+(defcfg concurrent-tap-hold yes)
+(deflayermap layer1)
+(defchordsv2
+ (k l) rsft 75 all-released ()
+)
+        ",
+        "
+d:k d:l t:10
+d:t t:1
+u:k t:1 u:l t:10
+u:t t:10
+",
+    )
+    .to_ascii();
+    assert_eq!("dn:RShift t:11ms dn:T t:4ms up:RShift t:7ms up:T", result);
+}
+
+#[test]
+fn sim_chordsv1_key_history_updates_once() {
+    let result = simulate(
+        "
+(defsrc)
+(defchords iobspc 50
+  (i o) bspc
+)
+(deflayermap (base)
+  i (chord iobspc i)
+  o (chord iobspc o)
+  t (switch
+    ((key-history bspc 3)) a fallthrough
+    ((key-history bspc 2)) b fallthrough
+    ((key-history bspc 1)) c fallthrough
+  )
+)
+        ",
+        "
+d:i d:o t:10
+u:i u:o t:10
+d:t u:t t:10
+d:t u:t t:10
+",
+    )
+    .to_ascii();
+    // For first press of `t`, only position 1 should be filled.
+    // The key history should unpause, so on pressing `t` again,
+    // position 2 is now where bspc is because C was sent.
+    assert_eq!(
+        "t:1ms dn:BSpace t:10ms up:BSpace t:9ms dn:C t:1ms up:C t:9ms dn:B t:1ms up:B",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/delay_tests.rs b/src/tests/sim_tests/delay_tests.rs
new file mode 100644
index 000000000..c9bb39b65
--- /dev/null
+++ b/src/tests/sim_tests/delay_tests.rs
@@ -0,0 +1,42 @@
+use super::*;
+
+#[test]
+#[ignore] // timing-based: fails intermittently
+fn on_press_delay_must_be_single_threaded() {
+    let start = std::time::Instant::now();
+    let result = simulate(
+        "(defsrc) (deflayermap (base) a (on-press-delay 10))",
+        "d:a t:50 u:a t:50",
+    );
+    assert_eq!("", result);
+    let end = std::time::Instant::now();
+    let duration = end - start;
+    assert!(duration > std::time::Duration::from_millis(9));
+    assert!(duration < std::time::Duration::from_millis(19));
+}
+
+#[test]
+#[ignore] // timing-based: fails intermittently
+fn on_release_delay_must_be_single_threaded() {
+    let start = std::time::Instant::now();
+    let result = simulate(
+        "(defsrc) (deflayermap (base) a (on-release-delay 10))",
+        "d:a t:50 u:a t:50",
+    );
+    assert_eq!("", result);
+    let end = std::time::Instant::now();
+    let duration = end - start;
+    assert!(duration > std::time::Duration::from_millis(9));
+    assert!(duration < std::time::Duration::from_millis(19));
+}
+
+#[test]
+#[ignore] // timing-based: fails intermittently
+fn no_delay_must_be_single_threaded() {
+    let start = std::time::Instant::now();
+    let result = simulate("(defsrc) (deflayermap (base) a XX)", "d:a t:50 u:a t:50");
+    assert_eq!("", result);
+    let end = std::time::Instant::now();
+    let duration = end - start;
+    assert!(duration < std::time::Duration::from_millis(10));
+}
diff --git a/src/tests/sim_tests/layer_sim_tests.rs b/src/tests/sim_tests/layer_sim_tests.rs
new file mode 100644
index 000000000..10df06129
--- /dev/null
+++ b/src/tests/sim_tests/layer_sim_tests.rs
@@ -0,0 +1,187 @@
+use super::*;
+
+#[test]
+fn transparent_base() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys yes concurrent-tap-hold yes) \
+         (defsrc a) \
+         (deflayer base _)",
+        "d:a t:50 u:a t:50",
+    );
+    assert_eq!("out:↓A\nt:50ms\nout:↑A", result);
+}
+
+#[test]
+fn delegate_base() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys   yes \
+                 delegate-to-first-layer yes)
+         (defsrc a b) \
+         (deflayer base c (layer-switch 2)) \
+         (deflayer 2 _ _)",
+        "d:b t:50 u:b t:50 d:a t:50 u:a t:50",
+    );
+    assert_eq!("t:100ms\nout:↓C\nt:50ms\nout:↑C", result);
+}
+
+#[test]
+fn delegate_base_but_base_is_transparent() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys   yes \
+                 delegate-to-first-layer yes)
+         (defsrc a b) \
+         (deflayer base _ (layer-switch 2)) \
+         (deflayer 2 _ _)",
+        "d:b t:50 u:b t:50 d:a t:50 u:a t:50",
+    );
+    assert_eq!("t:100ms\nout:↓A\nt:50ms\nout:↑A", result);
+}
+
+#[test]
+fn layer_switching() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys   yes
+                 delegate-to-first-layer yes)
+         (defsrc a b c d)
+         (deflayer base x y z (layer-switch 2))
+         (deflayer 2 e f _ (layer-switch 3))
+         (deflayer 3 g _ _ (layer-switch 4))
+         (deflayer 4 _ _ _ XX)
+        ",
+        "d:c t:20 u:c t:20 d:d t:20 u:d t:20
+         d:b t:20 u:b t:20
+         d:c t:20 u:c t:20
+         d:d t:20 u:d t:20
+         d:a t:20 u:a t:20
+         d:b t:20 u:b t:20
+         d:d t:20 u:d t:20
+         d:a t:20 u:a t:20",
+    );
+    assert_eq!(
+        "out:↓Z\nt:20ms\nout:↑Z\nt:60ms\nout:↓F\nt:20ms\nout:↑F\nt:20ms\nout:↓Z\nt:20ms\nout:↑Z\nt:60ms\nout:↓G\nt:20ms\nout:↑G\nt:20ms\nout:↓Y\nt:20ms\nout:↑Y\nt:60ms\nout:↓X\nt:20ms\nout:↑X",
+        result
+    );
+}
+
+#[test]
+fn layer_holding() {
+    let result = simulate(
+        "(defcfg process-unmapped-keys   yes
+                 delegate-to-first-layer no)
+         (defsrc a b c d e f)
+         (deflayer base x y z (layer-while-held 2) XX XX)
+         (deflayer 2 e f _ XX (layer-while-held 3) XX)
+         (deflayer 3 g _ _ XX XX (layer-while-held 4))
+         (deflayer 4 _ _ _ XX XX XX)
+        ",
+        "d:c t:20 u:c t:20
+         d:d t:20
+         d:a t:20 u:a t:20
+         d:b t:20 u:b t:20
+         d:c t:20 u:c t:20
+         d:e t:20
+         d:a t:20 u:a t:20
+         d:b t:20 u:b t:20
+         d:c t:20 u:c t:20
+         d:f t:20
+         d:a t:20 u:a t:20
+         d:b t:20 u:b t:20
+         d:c t:20 u:c t:20",
+    );
+    assert_eq!(
+        "out:↓Z\nt:20ms\nout:↑Z\nt:40ms\nout:↓E\nt:20ms\nout:↑E\nt:20ms\nout:↓F\nt:20ms\nout:↑F\nt:20ms\nout:↓Z\nt:20ms\nout:↑Z\nt:40ms\nout:↓G\nt:20ms\nout:↑G\nt:20ms\nout:↓F\nt:20ms\nout:↑F\nt:20ms\nout:↓Z\nt:20ms\nout:↑Z\nt:40ms\nout:↓G\nt:20ms\nout:↑G\nt:20ms\nout:↓F\nt:20ms\nout:↑F\nt:20ms\nout:↓Z\nt:20ms\nout:↑Z",
+        result
+    );
+}
+
+// =============================================================================
+// Layer Switch Simulator Input Tests
+// =============================================================================
+// These tests verify the simulator's ability to directly switch layers
+// using the ls:name syntax in simulation input strings.
+
+/// Test ls:layer_name to switch to a named layer
+#[test]
+fn ls_sim_switch_to_layer() {
+    const CFG: &str = r"
+        (defsrc a b)
+        (deflayer base a b)
+        (deflayer other 1 2)
+    ";
+    // Switch to 'other' layer, then press 'a' which should output '1'
+    let result = simulate(CFG, "ls:other t:10 d:a t:10 u:a t:10").to_ascii();
+    assert_eq!("t:10ms dn:Kb1 t:10ms up:Kb1", result);
+}
+
+/// Test ls: can switch between multiple layers
+#[test]
+fn ls_sim_switch_multiple_layers() {
+    const CFG: &str = r"
+        (defsrc a b)
+        (deflayer base a b)
+        (deflayer num 1 2)
+        (deflayer nav left right)
+    ";
+    // Switch to num, press a (outputs 1), switch to nav, press a (outputs left)
+    let result = simulate(CFG, "ls:num d:a t:10 u:a t:10 ls:nav d:a t:10 u:a t:10").to_ascii();
+    assert_eq!("dn:Kb1 t:10ms up:Kb1 t:10ms dn:Left t:10ms up:Left", result);
+}
+
+/// Test ls: can switch back to base layer
+#[test]
+fn ls_sim_switch_back_to_base() {
+    const CFG: &str = r"
+        (defsrc a)
+        (deflayer base a)
+        (deflayer other 1)
+    ";
+    // Switch to other (a->1), switch back to base (a->a)
+    let result = simulate(CFG, "ls:other d:a t:10 u:a t:10 ls:base d:a t:10 u:a t:10").to_ascii();
+    assert_eq!("dn:Kb1 t:10ms up:Kb1 t:10ms dn:A t:10ms up:A", result);
+}
+
+/// Test layer-switch: as alternative syntax
+#[test]
+fn ls_sim_layer_switch_prefix() {
+    const CFG: &str = r"
+        (defsrc a)
+        (deflayer base a)
+        (deflayer other 1)
+    ";
+    let result = simulate(CFG, "layer-switch:other d:a t:10 u:a t:10").to_ascii();
+    assert_eq!("dn:Kb1 t:10ms up:Kb1", result);
+}
+
+/// Test ls: with delegate-to-first-layer - transparent keys should delegate to base
+#[test]
+fn ls_sim_with_delegate_to_first_layer() {
+    const CFG: &str = r"
+        (defcfg process-unmapped-keys yes
+                delegate-to-first-layer yes)
+        (defsrc a b)
+        (deflayer base x y)
+        (deflayer nav left _)
+    ";
+    // Switch to nav: 'a' -> left, 'b' -> transparent -> delegates to base -> y
+    let result = simulate(CFG, "ls:nav d:a t:10 u:a t:10 d:b t:10 u:b t:10").to_ascii();
+    assert_eq!("dn:Left t:10ms up:Left t:10ms dn:Y t:10ms up:Y", result);
+}
+
+/// Test ls: with transparent keys but NO delegate-to-first-layer
+#[test]
+fn ls_sim_transparent_no_delegate() {
+    const CFG: &str = r"
+        (defcfg process-unmapped-keys yes
+                delegate-to-first-layer no)
+        (defsrc a b)
+        (deflayer base x y)
+        (deflayer nav left _)
+    ";
+    // Switch to nav: 'a' -> left, 'b' -> transparent -> passthrough (outputs B)
+    let result = simulate(CFG, "ls:nav d:a t:10 u:a t:10 d:b t:10 u:b t:10").to_ascii();
+    assert_eq!("dn:Left t:10ms up:Left t:10ms dn:B t:10ms up:B", result);
+}
+
+// =============================================================================
+// End Layer Switch Simulator Input Tests
+// =============================================================================
diff --git a/src/tests/sim_tests/macro_sim_tests.rs b/src/tests/sim_tests/macro_sim_tests.rs
new file mode 100644
index 000000000..2293801d7
--- /dev/null
+++ b/src/tests/sim_tests/macro_sim_tests.rs
@@ -0,0 +1,145 @@
+use super::*;
+
+#[test]
+fn macro_cancel_on_press() {
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-cancel-on-press z 100 y) (macro x 100 w) c)";
+    test_on_press(cfg);
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-repeat-cancel-on-press z 100 y 100) (macro x 100 w) c)";
+    test_on_press(cfg);
+}
+
+fn test_on_press(cfg: &str) {
+    // Cancellation should happen.
+    let result = simulate(cfg, "d:a t:50 d:c t:100").to_ascii();
+    assert_eq!("t:1ms dn:Z t:1ms up:Z t:48ms dn:C", result);
+    // Macro should complete if allowed to.
+    let result = simulate(cfg, "d:a u:a t:150 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Z t:1ms up:Z t:101ms dn:Y t:1ms up:Y t:46ms dn:C",
+        result
+    );
+    // The window for macro cancellation should not persist to a new macro that is not cancellable.
+    let result = simulate(cfg, "d:a t:120 d:b t:20 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Z t:1ms up:Z t:101ms dn:Y t:1ms up:Y \
+                t:17ms dn:X t:1ms up:X t:18ms dn:C t:83ms dn:W t:1ms up:W",
+        result
+    );
+    let result = simulate(cfg, "d:a t:10 d:c u:c t:10 d:b t:20 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Z t:1ms up:Z t:8ms dn:C t:1ms up:C t:10ms \
+                dn:X t:1ms up:X t:18ms dn:C t:83ms dn:W t:1ms up:W",
+        result
+    );
+}
+
+#[test]
+fn macro_release_cancel_and_cancel_on_press() {
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-release-cancel-and-cancel-on-press z 100 y 100) (macro x 100 w) c)";
+    test_release_and_on_press(cfg);
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-repeat-release-cancel-and-cancel-on-press z 100 y 100) (macro x 100 w) c)";
+    test_release_and_on_press(cfg);
+}
+
+fn test_release_and_on_press(cfg: &str) {
+    // Cancellation should happen for press.
+    let result = simulate(cfg, "d:a t:50 d:c t:100").to_ascii();
+    assert_eq!("t:2ms dn:Z t:1ms up:Z t:47ms dn:C", result);
+    // Cancellation should happen for release
+    let result = simulate(cfg, "d:a u:a t:150 d:c t:100").to_ascii();
+    assert_eq!("t:2ms dn:Z t:1ms up:Z t:147ms dn:C", result);
+    // Macro should complete if allowed to.
+    let result = simulate(cfg, "d:a t:150 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:2ms dn:Z t:1ms up:Z t:101ms dn:Y t:1ms up:Y t:45ms dn:C",
+        result
+    );
+    // The window for macro cancellation should not persist to a new macro that is not cancellable.
+    let result = simulate(cfg, "d:a t:120 d:b t:20 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:2ms dn:Z t:1ms up:Z t:101ms dn:Y t:1ms up:Y \
+                t:16ms dn:X t:1ms up:X t:18ms dn:C t:83ms dn:W t:1ms up:W",
+        result
+    );
+    let result = simulate(cfg, "d:a t:10 d:c u:c t:10 d:b t:20 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:2ms dn:Z t:1ms up:Z t:7ms dn:C t:1ms up:C t:10ms \
+                dn:X t:1ms up:X t:18ms dn:C t:83ms dn:W t:1ms up:W",
+        result
+    );
+    let result = simulate(cfg, "d:a u:a t:10 t:10 d:b u:b t:20 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:2ms dn:Z t:1ms up:Z t:18ms \
+         dn:X t:1ms up:X t:18ms dn:C t:83ms dn:W t:1ms up:W",
+        result
+    );
+}
+
+#[test]
+fn macro_repeat() {
+    let cfg = "\
+(defsrc a b c d)
+(deflayer base
+ (macro-repeat Digit1 50)
+ (macro-repeat-release-cancel Digit1 50)
+ (macro-repeat-cancel-on-press Digit1 50)
+ (macro-repeat-release-cancel-and-cancel-on-press Digit1 50))";
+    let result = simulate(cfg, "d:a t:125 u:a").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1",
+        result
+    );
+    let result = simulate(cfg, "d:b t:125 u:b").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1",
+        result
+    );
+    let result = simulate(cfg, "d:c t:125 u:c").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1",
+        result
+    );
+    let result = simulate(cfg, "d:d t:125 u:d").to_ascii();
+    assert_eq!(
+        "t:2ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1 t:52ms dn:Kb1 t:1ms up:Kb1",
+        result
+    );
+}
+
+#[test]
+fn macro_release_cancel() {
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-release-cancel z 100 y 100) (macro x 100 w) c)";
+    test_release(cfg);
+    let cfg = "\
+(defsrc a b c)
+(deflayer base (macro-repeat-release-cancel z 100 y 100) (macro x 100 w) c)";
+    test_release(cfg);
+}
+
+fn test_release(cfg: &str) {
+    // Cancellation should not happen for press.
+    let result = simulate(cfg, "d:a t:50 d:c t:100").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Z t:1ms up:Z t:48ms dn:C t:53ms dn:Y t:1ms up:Y",
+        result
+    );
+    // Cancellation should happen for release
+    let result = simulate(cfg, "d:a u:a t:150 d:c t:100").to_ascii();
+    assert_eq!("t:1ms dn:Z t:1ms up:Z t:148ms dn:C", result);
+    // Macro should complete if allowed to.
+    let result = simulate(cfg, "d:a t:150 d:c t:20").to_ascii();
+    assert_eq!(
+        "t:1ms dn:Z t:1ms up:Z t:101ms dn:Y t:1ms up:Y t:46ms dn:C",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/mod.rs b/src/tests/sim_tests/mod.rs
new file mode 100644
index 000000000..f5e9182e6
--- /dev/null
+++ b/src/tests/sim_tests/mod.rs
@@ -0,0 +1,196 @@
+//! Contains tests that use simulated inputs.
+//!
+//! One way to write tests is to write the configuration, write the simulated input, and then let
+//! the test fail by comparing the output to an empty string. Run the test then inspect the failure
+//! and see if the real output looks sensible according to what is expected.
+
+use std::num::NonZeroU128;
+
+use crate::tests::*;
+use crate::{
+    FAKE_KEY_ROW, FakeKeyAction, Kanata,
+    kanata::handle_fakekey_action,
+    oskbd::{KeyEvent, KeyValue},
+    str_to_oscode,
+};
+
+use rustc_hash::FxHashMap;
+
+/// Parse a fakekey specification like "name" or "name:action"
+/// Returns (name, action) where action defaults to Press if not specified.
+fn parse_fakekey_spec(spec: &str) -> (&str, FakeKeyAction) {
+    match spec.split_once(':') {
+        Some((name, action_str)) => {
+            let action = match action_str {
+                "press" | "p" => FakeKeyAction::Press,
+                "release" => FakeKeyAction::Release,
+                "tap" | "t" => FakeKeyAction::Tap,
+                "toggle" | "g" => FakeKeyAction::Toggle,
+                _ => panic!(
+                    "unknown fakekey action: {action_str}. Expected: press, release, tap, or toggle"
+                ),
+            };
+            (name, action)
+        }
+        None => (spec, FakeKeyAction::Press),
+    }
+}
+
+/// Apply a fakekey action to the kanata instance
+fn apply_fakekey_action(k: &mut Kanata, name: &str, action: FakeKeyAction) {
+    let index = k
+        .virtual_keys
+        .get(name)
+        .unwrap_or_else(|| panic!("unknown virtual key: {name}"));
+    handle_fakekey_action(action, k.layout.bm(), FAKE_KEY_ROW, *index as u16);
+}
+
+/// Apply a layer switch to the kanata instance
+fn apply_layer_switch(k: &mut Kanata, layer_name: &str) {
+    let layer_idx = k
+        .layer_info
+        .iter()
+        .position(|l| l.name == layer_name)
+        .unwrap_or_else(|| panic!("unknown layer: {layer_name}"));
+    k.layout.bm().set_default_layer(layer_idx);
+}
+
+mod block_keys_tests;
+mod capsword_sim_tests;
+mod chord_sim_tests;
+mod delay_tests;
+mod layer_sim_tests;
+mod macro_sim_tests;
+mod mouse_sim_tests;
+mod oneshot_tests;
+mod output_chord_tests;
+mod override_tests;
+mod release_sim_tests;
+mod repeat_sim_tests;
+mod seq_sim_tests;
+mod switch_sim_tests;
+mod tap_dance_tests;
+mod tap_hold_tests;
+mod template_sim_tests;
+mod timing_tests;
+mod unicode_sim_tests;
+mod unmod_sim_tests;
+mod use_defsrc_sim_tests;
+mod vkey_sim_tests;
+#[cfg(feature = "zippychord")]
+mod zippychord_sim_tests;
+
+fn simulate<S: AsRef<str>>(cfg: S, sim: S) -> String {
+    simulate_with_file_content(cfg, sim, Default::default())
+}
+
+fn simulate_with_file_content<S: AsRef<str>>(
+    cfg: S,
+    sim: S,
+    file_content: FxHashMap<String, String>,
+) -> String {
+    init_log();
+    let _lk = match CFG_PARSE_LOCK.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => poisoned.into_inner(),
+    };
+    let mut k = Kanata::new_from_str(cfg.as_ref(), file_content).expect("failed to parse cfg");
+    for pair in sim.as_ref().split_whitespace() {
+        match pair.split_once(':') {
+            Some((kind, val)) => match kind {
+                "t" => {
+                    let ticks = str::parse::<u128>(val).expect("valid num for tick");
+                    let mut ticks_with_no_processing: Option<NonZeroU128> = None;
+                    for t in 0..ticks {
+                        let _ = k.tick_ms(1, &None);
+                        let can_block = k.can_block_update_idle_waiting(1);
+                        if can_block {
+                            ticks_with_no_processing = NonZeroU128::new(ticks - t);
+                            break;
+                        }
+                    }
+                    if let Some(twnp) = ticks_with_no_processing {
+                        for _ in 1..twnp.into() {
+                            k.kbd_out.tick();
+                        }
+                    }
+                }
+                "d" => {
+                    let key_code = str_to_oscode(val).expect("valid keycode");
+                    k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Press))
+                        .expect("input handles fine");
+                    #[cfg(not(all(target_os = "windows", not(feature = "interception_driver"))))]
+                    crate::PRESSED_KEYS.lock().insert(key_code);
+                    #[cfg(all(target_os = "windows", not(feature = "interception_driver")))]
+                    crate::PRESSED_KEYS
+                        .lock()
+                        .insert(key_code, web_time::Instant::now());
+                }
+                "u" => {
+                    let key_code = str_to_oscode(val).expect("valid keycode");
+                    k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Release))
+                        .expect("input handles fine");
+                    crate::PRESSED_KEYS.lock().remove(&key_code);
+                }
+                "r" => {
+                    let key_code = str_to_oscode(val).expect("valid keycode");
+                    k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Repeat))
+                        .expect("input handles fine");
+                }
+                // Virtual/fake key activation: vk:name[:action] or fakekey:name[:action]
+                // Supported actions: press (p), release, tap (t), toggle (g)
+                "vk" | "fakekey" | "virtualkey" | "🎭" => {
+                    let (vk_name, action) = parse_fakekey_spec(val);
+                    apply_fakekey_action(&mut k, vk_name, action);
+                }
+                // Layer switch: ls:layer_name
+                "ls" | "layer-switch" | "🔀" => {
+                    apply_layer_switch(&mut k, val);
+                }
+                _ => panic!("invalid item {pair}"),
+            },
+            None => panic!("invalid item {pair}"),
+        }
+    }
+    drop(_lk);
+    k.kbd_out.outputs.events.join("\n")
+}
+
+#[allow(unused)]
+trait SimTransform {
+    /// Changes newlines to spaces.
+    fn to_spaces(self) -> Self;
+    /// Removes out:↑_ items from the string. Also transforms newlines to spaces.
+    fn no_releases(self) -> Self;
+    /// Removes t:_ms items from the string. Also transforms newlines to spaces.
+    fn no_time(self) -> Self;
+    /// Replaces out:↓_ with dn:_ and out:↑_ with up:_. Also transforms newlines to spaces.
+    fn to_ascii(self) -> Self;
+}
+
+impl SimTransform for String {
+    fn to_spaces(self) -> Self {
+        self.replace('\n', " ")
+    }
+
+    fn no_time(self) -> Self {
+        self.split_ascii_whitespace()
+            .filter(|s| !s.starts_with("t:"))
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+
+    fn no_releases(self) -> Self {
+        self.split_ascii_whitespace()
+            .filter(|s| !s.starts_with("out:↑") && !s.starts_with("up:"))
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+
+    fn to_ascii(self) -> Self {
+        self.split_ascii_whitespace()
+            .map(|s| s.replace("out:↑", "up:").replace("out:↓", "dn:"))
+            .collect::<Vec<_>>()
+            .join(" ")
+    }
+}
diff --git a/src/tests/sim_tests/mouse_sim_tests.rs b/src/tests/sim_tests/mouse_sim_tests.rs
new file mode 100644
index 000000000..649abfaeb
--- /dev/null
+++ b/src/tests/sim_tests/mouse_sim_tests.rs
@@ -0,0 +1,14 @@
+use super::*;
+
+#[test]
+fn multi_mouse_button_does_multi_click_release_single_hold() {
+    let result = simulate(
+        "(defsrc) (deflayermap (base) a (multi mmid mmid mrgt mlft))",
+        "d:a t:50 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "out🖰:↓Mid out🖰:↑Mid t:1ms out🖰:↓Mid out🖰:↑Mid t:1ms out🖰:↓Right out🖰:↑Right t:1ms out🖰:↓Left t:50ms out🖰:↑Left",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/oneshot_tests.rs b/src/tests/sim_tests/oneshot_tests.rs
new file mode 100644
index 000000000..f7889ccb4
--- /dev/null
+++ b/src/tests/sim_tests/oneshot_tests.rs
@@ -0,0 +1,77 @@
+use super::*;
+
+#[test]
+fn oneshot_pause() {
+    let result = simulate(
+        "
+(defsrc a lmet rmet)
+(deflayer base
+  1 @lme @rme)
+(deflayer numbers
+  2 @lme @rme)
+(deflayer navigation
+  (one-shot 2000 lalt) @lme @rme)
+(deflayer symbols
+  4 @lme @rme)
+
+(defvirtualkeys
+  callum (switch
+    ((and nop1 nop2)) (layer-while-held numbers) break
+    (nop1) (layer-while-held navigation) break
+    (nop2) (layer-while-held symbols) break)
+  activate-callum (multi
+   (one-shot-pause-processing 5)
+   (switch
+    ((or nop1 nop2))
+     (multi (on-press release-vkey callum)
+            (on-press press-vkey callum))
+     break
+    () (on-press release-vkey callum) break)))
+
+(defalias
+  lme (multi nop1
+             (on-press tap-vkey activate-callum)
+             (on-release tap-vkey activate-callum))
+  rme (multi nop2
+             (on-press tap-vkey activate-callum)
+             (on-release tap-vkey activate-callum)))
+        ",
+        "d:lmet t:10 d:a u:a t:10 u:lmet t:10 d:a u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!("t:10ms dn:LAlt t:20ms dn:Kb1 t:5ms up:LAlt up:Kb1", result);
+}
+
+#[test]
+fn oneshot_multi_with_chord() {
+    let result = simulate(
+        "(defsrc a)
+         (deflayer test (multi a (one-shot 1000 C-z)))",
+        "d:KeyA t:10 u:KeyA t:200 d:KeyC t:1000",
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:A dn:LCtrl dn:Z t:10ms up:A t:200ms dn:C t:5ms up:LCtrl up:Z",
+        result
+    );
+}
+
+#[test]
+fn oneshot_multi_with_layer() {
+    let result = simulate(
+        "(defsrc a)
+         (deflayer l1 (multi a (one-shot 100 (layer-while-held l2))))
+         (deflayer l2 b)
+        ",
+        "d:KeyA t:10 u:KeyA t:10 d:KeyA t:10 u:KeyA t:1000",
+    )
+    .to_ascii();
+    // Known bug:
+    // The 5ms should be 10ms.
+    // The B is released (with instant action delay) even when it shouldn't
+    // because one-shot completion is releasing everything
+    // that is on the same coordinate as it.
+    //   issue: -------------------------------.
+    //                                         v
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:B t:5ms up:B", result);
+}
diff --git a/src/tests/sim_tests/output_chord_tests.rs b/src/tests/sim_tests/output_chord_tests.rs
new file mode 100644
index 000000000..844953ca3
--- /dev/null
+++ b/src/tests/sim_tests/output_chord_tests.rs
@@ -0,0 +1,34 @@
+use super::*;
+
+#[test]
+fn output_chord_samekey_has_release() {
+    let config = "
+        (defsrc a b)
+        (deflayer _ S-= =)
+        ";
+    let result = simulate(config, "d:a t:10 d:b t:10").to_ascii();
+    assert_eq!(
+        "dn:LShift dn:Equal t:10ms up:LShift up:Equal t:1ms dn:Equal",
+        result
+    );
+    let result = simulate(config, "d:b t:10 d:a t:10").to_ascii();
+    assert_eq!("dn:Equal t:10ms up:Equal dn:LShift t:1ms dn:Equal", result);
+}
+
+#[test]
+fn output_chord_follows_processing_delay_config() {
+    let result = simulate(
+        "
+        (defsrc)
+        (deflayermap (base)
+         a S-9
+         b S-0)
+        ",
+        "d:a t:10 d:b t:10 u:b t:10 u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift dn:Kb9 t:10ms up:Kb9 dn:Kb0 t:10ms up:LShift up:Kb0",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/override_tests.rs b/src/tests/sim_tests/override_tests.rs
new file mode 100644
index 000000000..8f252bea6
--- /dev/null
+++ b/src/tests/sim_tests/override_tests.rs
@@ -0,0 +1,166 @@
+use super::*;
+
+#[test]
+fn override_with_unmod() {
+    let result = simulate(
+        "
+(defoverrides
+ (a) (b)
+ (b) (a)
+)
+
+(defalias
+ b (unshift b)
+ a (unshift a)
+)
+(defsrc a b)
+(deflayer base @a @b)
+        ",
+        "d:lsft t:50 d:a t:50 u:a t:50 d:b t:50 u:b t:50",
+    )
+    .to_ascii()
+    .no_time();
+    assert_eq!(
+        "dn:LShift up:LShift dn:B up:B dn:LShift up:LShift dn:A up:A dn:LShift",
+        result
+    );
+}
+
+#[test]
+fn override_release_mod_change_key() {
+    let cfg = "
+(defsrc)
+(deflayer base)
+(defoverrides
+  (lsft a) (lsft 9)
+  (lsft 1) (lctl 2))
+        ";
+    let result = simulate(cfg, "d:lsft t:10 d:a t:10 u:lsft t:10 u:a t:10").to_ascii();
+    assert_eq!("dn:LShift t:10ms dn:Kb9 t:10ms up:LShift up:Kb9", result);
+    let result = simulate(cfg, "d:lsft t:10 d:a t:10 u:a t:10 u:lsft t:10").to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:Kb9 t:10ms up:Kb9 t:10ms up:LShift",
+        result
+    );
+    let result = simulate(cfg, "d:lsft t:10 d:a t:10 d:c t:10").to_ascii();
+    assert_eq!("dn:LShift t:10ms dn:Kb9 t:10ms up:Kb9 dn:C", result);
+    let result = simulate(cfg, "d:lsft t:10 d:1 t:10 d:c t:10").to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms up:LShift dn:LCtrl dn:Kb2 t:10ms up:LCtrl up:Kb2 dn:LShift dn:C",
+        result
+    );
+}
+
+#[test]
+fn override_eagerly_releases() {
+    let result = simulate(
+        "
+(defcfg override-release-on-activation yes)
+(defsrc)
+(deflayer base)
+(defoverrides (lsft a) (lsft 9))
+        ",
+        "d:lsft t:10 d:a t:10 u:lsft t:10 u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:Kb9 t:1ms up:Kb9 t:9ms up:LShift",
+        result
+    );
+}
+
+#[test]
+#[should_panic]
+fn config_with_both_overrides() {
+    simulate(
+        "
+(defcfg override-release-on-activation yes)
+(defsrc)
+(deflayer base)
+(defoverrides (lsft a) (lsft 9))
+(defoverridesv2 (lsft a) (lsft 9) () ())
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn config_with_two_overrides() {
+    simulate(
+        "
+(defcfg override-release-on-activation yes)
+(defsrc)
+(deflayer base)
+(defoverrides (lsft a) (lsft 9))
+(defoverrides (lsft a) (lsft 9))
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn config_with_both_overridesv2() {
+    simulate(
+        "
+(defcfg override-release-on-activation yes)
+(defsrc)
+(deflayer base)
+(defoverridesv2 (lsft a) (lsft 9) () ())
+(defoverridesv2 (lsft a) (lsft 9) () ())
+        ",
+        "",
+    );
+}
+
+#[test]
+fn config_with_overridev2() {
+    let cfg = "
+(defsrc)
+(deflayermap (l1) b (layer-switch l2))
+(deflayermap (l2) b (layer-switch l1))
+(defoverridesv2 (lsft a) (lsft 9) (lctl) (l2))
+        ";
+
+    // Override works.
+    let result = simulate(cfg, "d:lctl d:lsft d:a t:10 u:a u:lsft u:lctl t:10").to_ascii();
+    assert_eq!(
+        "dn:LCtrl t:1ms dn:LShift t:1ms dn:A t:8ms up:A t:1ms up:LShift t:1ms up:LCtrl",
+        result
+    );
+
+    // Override doesn't apply while lctl is held
+    let result = simulate(cfg, "d:lctl d:lsft d:a u:a t:10 u:lctl t:10 u:lsft t:10").to_ascii();
+    assert_eq!(
+        "dn:LCtrl t:1ms dn:LShift t:1ms dn:A t:1ms up:A t:7ms up:LCtrl t:10ms up:LShift",
+        result
+    );
+    let result = simulate(cfg, "d:lctl d:lsft d:a t:10 u:lctl t:10 u:lsft u:a t:10").to_ascii();
+    assert_eq!(
+        // Note that this may not be desirable...
+        // One could imagine that the desired behavior is that A is released, or that A remains
+        // held, so that irrespective of which key is released first, the 9 never activates.
+        //
+        // Doing the latter not-implemented behaviour is more complicated in code though, so for
+        // now stick to "worse is better" and keep it as-is.
+        // The user workaround is to always release the A before releasing modifiers.
+        "dn:LCtrl t:1ms dn:LShift t:1ms dn:A t:8ms up:LCtrl up:A dn:Kb9 t:10ms up:LShift up:Kb9",
+        result
+    );
+
+    // Override doesn't apply while on disabled layer is held
+    let result = simulate(
+        cfg,
+        "d:b u:b \
+         t:10 d:lsft d:a t:10 u:lsft t:10 u:a t:10 \
+         d:b u:b \
+         t:10 d:lsft d:a t:10 u:lsft t:10 u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:10ms dn:LShift t:1ms dn:A t:9ms up:LShift t:10ms up:A \
+         t:20ms dn:LShift t:1ms dn:Kb9 t:9ms up:LShift up:Kb9",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/release_sim_tests.rs b/src/tests/sim_tests/release_sim_tests.rs
new file mode 100644
index 000000000..05224dd3f
--- /dev/null
+++ b/src/tests/sim_tests/release_sim_tests.rs
@@ -0,0 +1,31 @@
+use super::*;
+
+#[test]
+fn release_standard() {
+    let result = simulate(
+        "
+         (defsrc a)
+         (deflayer base (multi lalt a))
+        ",
+        "
+         d:a t:10 u:a t:10
+        ",
+    )
+    .to_ascii();
+    assert_eq!("dn:LAlt dn:A t:10ms up:LAlt up:A", result);
+}
+
+#[test]
+fn release_reversed() {
+    let result = simulate(
+        "
+         (defsrc a)
+         (deflayer base (multi lalt a reverse-release-order))
+        ",
+        "
+         d:a t:10 u:a t:10
+        ",
+    )
+    .to_ascii();
+    assert_eq!("dn:LAlt dn:A t:10ms up:A up:LAlt", result);
+}
diff --git a/src/tests/sim_tests/repeat_sim_tests.rs b/src/tests/sim_tests/repeat_sim_tests.rs
new file mode 100644
index 000000000..e8c2526b3
--- /dev/null
+++ b/src/tests/sim_tests/repeat_sim_tests.rs
@@ -0,0 +1,136 @@
+use super::*;
+
+#[test]
+fn repeat_standard() {
+    let result = simulate(
+        "
+         (defsrc a)
+         (deflayer base b)
+        ",
+        "
+         d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "out:↓B\nt:10ms\nout:↓B\nt:10ms\nout:↓B\nt:10ms\nout:↑B",
+        result
+    );
+}
+
+#[test]
+fn repeat_layer_while_held() {
+    let result = simulate(
+        "
+         (defsrc a b)
+         (deflayer base a (layer-while-held held))
+         (deflayer held c b)
+        ",
+        "
+         d:b t:10 r:b t:10 d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "t:20ms\nout:↓C\nt:10ms\nout:↓C\nt:10ms\nout:↓C\nt:10ms\nout:↑C",
+        result
+    );
+}
+
+#[test]
+fn repeat_layer_switch() {
+    let result = simulate(
+        "
+         (defsrc a b)
+         (deflayer base a (layer-switch swtc))
+         (deflayer swtc d b)
+        ",
+        "
+         d:b t:10 r:b t:10 d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "t:20ms\nout:↓D\nt:10ms\nout:↓D\nt:10ms\nout:↓D\nt:10ms\nout:↑D",
+        result
+    );
+}
+
+#[test]
+fn repeat_layer_held_trans() {
+    let result = simulate(
+        "
+         (defsrc a b)
+         (deflayer base e (layer-while-held held))
+         (deflayer held _ b)
+        ",
+        "
+         d:b t:10 r:b t:10 d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "t:20ms\nout:↓E\nt:10ms\nout:↓E\nt:10ms\nout:↓E\nt:10ms\nout:↑E",
+        result
+    );
+}
+
+#[test]
+fn repeat_many_layer_held_trans() {
+    let result = simulate(
+        "
+         (defsrc a b c d e)
+         (deflayer base e (layer-while-held held1) _ _ _)
+         (deflayer held1 f b (layer-while-held held2) _ _)
+         (deflayer held2 _ _ _ (layer-while-held held3) _)
+         (deflayer held3 _ _ _ _ (layer-while-held held4))
+         (deflayer held4 _ _ _ _ _)
+        ",
+        "
+         d:b t:10 r:b t:10
+         d:c t:10 r:c t:10
+         d:d t:10 r:d t:10
+         d:e t:10 r:e t:10
+         d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "t:80ms\nout:↓F\nt:10ms\nout:↓F\nt:10ms\nout:↓F\nt:10ms\nout:↑F",
+        result
+    );
+}
+
+#[test]
+fn repeat_base_layer_trans() {
+    let result = simulate(
+        "
+         (defsrc a)
+         (deflayer base _)
+        ",
+        "
+         d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+        ",
+    );
+    assert_eq!(
+        "out:↓A\nt:10ms\nout:↓A\nt:10ms\nout:↓A\nt:10ms\nout:↑A",
+        result
+    );
+}
+
+#[test]
+fn repeat_delegate_to_base_layer_trans() {
+    let result = simulate(
+        "
+         (defcfg delegate-to-first-layer yes)
+         (defsrc a c b)
+         (deflayer base e _ (layer-switch swtc))
+         (deflayer swtc _ _ _)
+        ",
+        "
+         d:b t:10 r:b t:10
+         d:a t:10 r:a t:10 r:a t:10 u:a t:10 r:a
+         d:c t:10 r:c t:10 r:c t:10 u:c t:10 r:c
+        ",
+    );
+    assert_eq!(
+        "t:20ms\nout:↓E\nt:10ms\nout:↓E\nt:10ms\nout:↓E\nt:10ms\nout:↑E\n\
+         t:10ms\nout:↓C\nt:10ms\nout:↓C\nt:10ms\nout:↓C\nt:10ms\nout:↑C",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/seq_sim_tests.rs b/src/tests/sim_tests/seq_sim_tests.rs
new file mode 100644
index 000000000..39362d7e5
--- /dev/null
+++ b/src/tests/sim_tests/seq_sim_tests.rs
@@ -0,0 +1,261 @@
+use super::*;
+
+#[test]
+fn special_nop_keys() {
+    let result = simulate(
+        "(defcfg sequence-input-mode visible-backspaced)
+         (defsrc a b c d e)
+         (deflayer base sldr nop0 c nop9 0)
+         (defvirtualkeys s1 (macro h i))
+         (defseq s1 (nop0 c nop9))
+        ",
+        "d:b d:d t:50 u:b u:d t:50
+         d:a d:b d:c t:50 u:a u:b u:c t:50 d:d t:50",
+    );
+    assert_eq!(
+        "t:102ms\nout:↓C\nt:50ms\nout:↑C\nt:48ms\n\
+        out:↓BSpace\nout:↑BSpace\n\
+        t:2ms\nout:↓H\nt:1ms\nout:↑H\nt:1ms\nout:↓I\nt:1ms\nout:↑I",
+        result
+    );
+}
+
+#[test]
+fn chorded_keys_visible_backspaced() {
+    let result = simulate(
+        "(defcfg sequence-input-mode visible-backspaced)
+         (defsrc 0)
+         (deflayer base sldr)
+         (defvirtualkeys s1 z)
+         (defseq s1 (S-(a b)))
+        ",
+        "d:0 u:0 d:lsft t:50 d:a d:b t:50 u:lsft u:a u:b t:500
+         d:0 u:0 d:rsft t:50 d:a d:b t:50 u:rsft u:a u:b t:500
+         d:0 u:0 d:rsft t:50 d:a u:rsft t:50 d:b u:a u:b t:500",
+    )
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        // 2nd row is buggy/unexpected! RShift isn't released before outputting Z
+        // Workarounds:
+        // - remap your rsft key to lsft
+        // - use release-key in the macro via virtual keys
+        // - accept and use the quirky behaviour; maybe it's what you wanted?
+        "dn:LShift dn:A dn:B dn:BSpace up:BSpace dn:BSpace up:BSpace up:LShift up:A up:B dn:Z up:Z \
+         dn:RShift dn:A dn:B dn:BSpace up:BSpace dn:BSpace up:BSpace up:A up:B dn:Z up:Z up:RShift \
+         dn:RShift dn:A up:RShift dn:B up:A up:B",
+        result
+    );
+}
+
+const OVERLAP_CFG: &str = "
+    (defcfg sequence-input-mode visible-backspaced)
+    (defsrc 0)
+    (deflayer base sldr)
+    (defvirtualkeys s1 y)
+    (defvirtualkeys s2 z)
+    (defvirtualkeys s3 l)
+    (defvirtualkeys s4 m)
+    (defvirtualkeys s5 n)
+    (defvirtualkeys s6 o)
+    (defvirtualkeys s7 p)
+    (defvirtualkeys s8 q)
+    (defseq s1 (O-(a b)))
+    (defseq s2 (a b))
+    (defseq s3 (O-(c d) e))
+    (defseq s4 (c d e))
+    (defseq s5 (O-(c d) O-(f g)))
+    (defseq s6 (O-(c d) f g))
+    (defseq s7 (c d O-(f g)))
+    ;; (defseq s8 (c d f g)) KNOWN BUGGY CASE! breaks s6 detection
+    ";
+
+#[test]
+fn overlapping_activate_overlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:a d:b t:100 u:a u:b u:0");
+    assert_eq!(
+        "t:1ms\nout:↓A\nt:1ms\nout:↓B\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nt:1ms\nout:↑A\nout:↑B\n\
+         out:↓Y\nt:1ms\nout:↑Y",
+        result
+    );
+}
+
+#[test]
+fn overlapping_activate_nonoverlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:a t:10 u:a t:10 d:b t:10 u:b t:10 u:0");
+    assert_eq!(
+        "t:1ms\nout:↓A\nt:9ms\nout:↑A\nt:10ms\nout:↓B\n\
+        out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+        t:1ms\nout:↑B\nout:↓Z\nt:1ms\nout:↑Z",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_nonoverlap_activate_overlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c d:d d:e t:100 u:c u:d u:e u:0");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↓D\nt:1ms\nout:↓E\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑C\nout:↑D\nout:↑E\nout:↓L\nt:1ms\nout:↑L",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_nonoverlap_activate_non_overlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c u:c d:d d:e t:100 u:d u:e u:0");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↑C\nt:1ms\nout:↓D\nt:1ms\nout:↓E\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑D\nout:↑E\nout:↓M\nt:1ms\nout:↑M",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_overlap_activate_overlap1() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c d:d d:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↓D\nt:1ms\nout:↓F\nt:1ms\nout:↓G\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑C\nout:↑D\nout:↑F\nout:↑G\nout:↓N\nt:1ms\nout:↑N",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_overlap_activate_overlap2() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c d:d u:c u:d d:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↓D\nt:1ms\nout:↑C\nt:1ms\nout:↑D\nt:1ms\nout:↓F\nt:1ms\nout:↓G\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑F\nout:↑G\nout:↓N\nt:1ms\nout:↑N",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_overlap_activate_overlap3() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c d:d u:c u:d t:10 d:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↓D\nt:1ms\nout:↑C\nt:1ms\nout:↑D\nt:6ms\nout:↓F\nt:1ms\nout:↓G\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑F\nout:↑G\nout:↓N\nt:1ms\nout:↑N",
+        result
+    );
+}
+
+#[test]
+fn overlapping_then_overlap_activate_nonoverlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c d:d u:c u:d t:10 d:f u:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↓D\nt:1ms\nout:↑C\nt:1ms\nout:↑D\nt:6ms\nout:↓F\nt:1ms\nout:↑F\nt:1ms\nout:↓G\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑G\nout:↓O\nt:1ms\nout:↑O",
+        result
+    );
+}
+
+#[test]
+fn non_overlapping_then_overlap_activate_overlap() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c u:c d:d u:d d:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↑C\nt:1ms\nout:↓D\nt:1ms\nout:↑D\nt:1ms\nout:↓F\nt:1ms\nout:↓G\n\
+         out:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\nout:↓BSpace\nout:↑BSpace\n\
+         t:1ms\nout:↑F\nout:↑G\nout:↓P\nt:1ms\nout:↑P",
+        result
+    );
+}
+
+#[test]
+fn non_overlapping_then_overlap_activate_nothing() {
+    let result = simulate(OVERLAP_CFG, "d:0 d:c u:c d:d u:d d:f u:f d:g t:100");
+    assert_eq!(
+        "t:1ms\nout:↓C\nt:1ms\nout:↑C\nt:1ms\nout:↓D\nt:1ms\nout:↑D\nt:1ms\nout:↓F\nt:1ms\nout:↑F\nt:1ms\nout:↓G",
+        result
+    );
+}
+
+/* BUG: chorded_hidden_delay_type
+ *
+ * Enable this test when fixing.
+ *
+ * Backtracking currently destroys information about held modifiers before finally outputting the
+ * invalid sequence characters. There is also no logic to keep modifier keys held for the
+ * appropriate duration according to the modifier bits information, even if the information was
+ * preserved. Seems like a complicated low-value edge-case bug to fix so for now will just document
+ * it... Nobody has reported it yet anyway. And visible-backspaced seems preferable in most cases
+ * anyway.
+#[test]
+fn chorded_keys_hidden_delaytype() {
+    let result = simulate(
+        "(defcfg sequence-input-mode hidden-delay-type)
+         (defsrc 0)
+         (deflayer base sldr)
+         (defvirtualkeys s1 z)
+         (defseq s1 (S-(a b)))
+        ",
+        "d:0 u:0 d:lsft t:50 d:a d:b t:50 u:lsft u:a u:b t:500
+         d:0 u:0 d:rsft t:50 d:a d:b t:50 u:rsft u:a u:b t:500
+         d:0 u:0 d:rsft t:50 d:a u:rsft t:50 d:b u:a u:b t:500",
+    );
+    assert_eq!(
+        "",
+        result
+    );
+}
+*/
+
+#[test]
+fn noerase() {
+    let result = simulate(
+        "(defcfg sequence-input-mode visible-backspaced)
+         (defsrc)
+         (deflayermap (base)
+           0 sldr
+           u (t! maybe-noerase u)
+         )
+         (deftemplate maybe-noerase (char)
+            (multi
+             (switch
+              ((key-history ' 1)) (sequence-noerase 1) fallthrough
+              () $char break
+            ))
+         )
+         (defvirtualkeys s1 z)
+         (defseq s1 (' u))
+        ",
+        "d:0 u:0 d:' t:50 d:u t:500",
+    )
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:Quote dn:U dn:BSpace up:BSpace up:Quote up:U dn:Z up:Z",
+        result,
+    );
+}
+
+#[test]
+fn tap_hold_pending() {
+    let result = simulate(
+        "
+(defalias md     (tap-hold 200 200 s S-s))
+(defsrc s d j)
+(deflayer base @md d sldr)
+(deffakekeys _u  (unicode μ))
+(defseq _u     (s))
+        ",
+        "
+d:KeyJ t:10 u:KeyJ t:10
+d:KeyS t:10 u:KeyS t:10 d:KeyD t:10 u:KeyD t:10
+
+d:KeyJ t:10 u:KeyJ t:10
+d:KeyS t:10 d:KeyD t:10 u:KeyS t:10 u:KeyD t:10",
+    )
+    .no_time()
+    .no_releases()
+    .to_ascii();
+    assert_eq!("outU:μ dn:D outU:μ dn:D", result,);
+}
diff --git a/src/tests/sim_tests/switch_sim_tests.rs b/src/tests/sim_tests/switch_sim_tests.rs
new file mode 100644
index 000000000..ffc65da0d
--- /dev/null
+++ b/src/tests/sim_tests/switch_sim_tests.rs
@@ -0,0 +1,99 @@
+use super::*;
+
+#[test]
+fn sim_switch_layer() {
+    let result = simulate(
+        "
+         (defcfg)
+         (defsrc a b)
+         (defalias b (switch
+            ((layer base)) x break
+            ((layer other)) y break))
+         (deflayer base (layer-while-held other) @b)
+         (deflayer other XX @b)
+        ",
+        "d:b u:b t:10 d:a d:b u:b u:a t:10",
+    )
+    .no_time();
+    assert_eq!("out:↓X out:↑X out:↓Y out:↑Y", result);
+}
+
+#[test]
+fn sim_switch_base_layer() {
+    let result = simulate(
+        "
+         (defcfg)
+         (defsrc a b c)
+         (defalias b (switch
+            ((base-layer base)) x break
+            ((base-layer other)) y break))
+         (deflayer base (layer-switch other) @b c)
+         (deflayer other XX @b (layer-while-held base))
+        ",
+        "d:b u:b t:10 d:a d:b u:b u:a t:10 d:c t:10 d:b t:10 u:c u:b t:10",
+    )
+    .no_time();
+    assert_eq!("out:↓X out:↑X out:↓Y out:↑Y out:↓Y out:↑Y", result);
+}
+
+#[test]
+fn sim_switch_noop() {
+    let result = simulate(
+        "
+         (defsrc)
+         (deflayermap (-) a XX b (switch
+          ((input real a)) c break
+          () d break
+         ))
+        ",
+        "d:a d:b t:10 u:a u:b t:10 d:b u:b t:10",
+    )
+    .no_time();
+    assert_eq!("out:↓C out:↑C out:↓D out:↑D", result);
+}
+
+#[test]
+fn sim_switch_trans_not_top_layer() {
+    let result = simulate(
+        "
+        (defalias init (multi (layer-while-held l1) (layer-while-held l2) (layer-while-held l3) (layer-while-held l4)))
+        (defsrc a b)
+        (deflayer l0 c @init)
+        (deflayer l1 b @init)
+        (deflayer l2 (switch () _ break) @init)
+        (deflayer l3 _ @init)
+        (deflayer l4 _ @init)
+        ",
+        "d:b t:20 d:a t:10 u:a t:100 d:a t:10 u:a t:100",
+    )
+    .to_ascii();
+    assert_eq!("t:20ms dn:B t:10ms up:B t:100ms dn:B t:10ms up:B", result);
+}
+
+#[test]
+fn sim_switch_not_logic() {
+    let result = simulate(
+        "
+        (defsrc a)
+        (deflayer base
+          (switch
+            ((or (not (or b)) b)) x break
+            () y break))
+        ",
+        "d:a t:10 u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!("dn:X t:10ms up:X", result);
+    let result = simulate(
+        "
+        (defsrc a)
+        (deflayer base
+          (switch
+            ((or (not b) b)) x break
+            () y break))
+        ",
+        "d:a t:10 u:a t:10",
+    )
+    .to_ascii();
+    assert_eq!("dn:X t:10ms up:X", result);
+}
diff --git a/src/tests/sim_tests/tap_dance_tests.rs b/src/tests/sim_tests/tap_dance_tests.rs
new file mode 100644
index 000000000..86f2be133
--- /dev/null
+++ b/src/tests/sim_tests/tap_dance_tests.rs
@@ -0,0 +1,23 @@
+use super::*;
+
+#[test]
+fn tap_dance_eager_with_mlft() {
+    let result = simulate(
+        "
+        (defsrc)
+        (deflayermap (baselayer)
+            a (tap-dance-eager 200 (mlft mrgt mmid))
+        )
+        ",
+        "
+        d:a t:1 u:a t:1
+        d:a t:1 u:a t:1
+        d:a t:1 u:a t:1
+        ",
+    )
+    .to_ascii();
+    assert_eq!(
+        "out🖰:↓Left t:1ms out🖰:↑Left t:1ms out🖰:↓Right t:1ms out🖰:↑Right t:1ms out🖰:↓Mid t:1ms out🖰:↑Mid",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/tap_hold_tests.rs b/src/tests/sim_tests/tap_hold_tests.rs
new file mode 100644
index 000000000..3318111a0
--- /dev/null
+++ b/src/tests/sim_tests/tap_hold_tests.rs
@@ -0,0 +1,1281 @@
+use super::*;
+
+#[test]
+fn delayed_timedout_released_taphold_can_still_tap() {
+    let result = simulate(
+        "
+        (defcfg concurrent-tap-hold yes )
+        (defsrc a b j)
+        (deflayer base @a @b @j)
+        (defalias
+         a (tap-hold 200 1000 a lctl)
+         b (tap-hold-tap-keys 0 100 b c (j))
+         j (tap-hold 200 500 j lsft))
+        ",
+        "d:a t:50 d:b t:50 d:j t:10 u:j t:100 u:b t:100 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:310ms dn:A t:7ms dn:B t:7ms dn:J t:6ms up:J t:1ms up:B t:1ms up:A",
+        result
+    );
+}
+
+#[test]
+fn delayed_timedout_released_taphold_can_hold() {
+    let result = simulate(
+        "
+        (defcfg concurrent-tap-hold yes)
+        (defsrc a b)
+        (deflayer base @a @b)
+        (defalias
+          a (tap-hold 0 300 a b)
+          b (tap-hold 0 100 c d)
+        )
+        ",
+        "d:a t:50 d:b t:150 u:b t:50 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:250ms dn:A t:7ms dn:D t:1ms up:D t:1ms up:A", result);
+}
+
+#[test]
+fn tap_hold_release_timeout_no_reset() {
+    let result = simulate(
+        "
+        (defsrc a)
+        (deflayer l1 (tap-hold-release-timeout 100 100 x y z))
+        ",
+        "d:a t:50 d:b t:75 u:b u:a t:25",
+    )
+    .to_ascii();
+    assert_eq!("t:100ms dn:Z t:1ms dn:B t:24ms up:B t:1ms up:Z", result);
+}
+
+#[test]
+fn tap_hold_release_timeout_with_reset() {
+    let result = simulate(
+        "
+        (defsrc a)
+        (deflayer l1 (tap-hold-release-timeout 100 100 x y z reset-timeout-on-press))
+        ",
+        "d:a t:50 d:b t:75 u:b u:a t:25",
+    )
+    .to_ascii();
+    assert_eq!("t:125ms dn:Y t:6ms dn:B t:1ms up:B t:1ms up:Y", result);
+}
+
+#[test]
+fn on_physical_idle_with_tap_repress() {
+    let result = simulate(
+        "
+(defsrc a)
+(deflayer base @a)
+(deflayer nomods a)
+(defvirtualkeys to-base (layer-switch base))
+(defalias
+  tap (multi
+    (layer-switch nomods)
+    (on-physical-idle 20 tap-vkey to-base)
+  )
+  a (tap-hold 100 100 (multi a @tap) b)
+)
+        ",
+        "d:a t:30 u:a t:30 d:a t:1000",
+    )
+    .to_ascii();
+    // t:30ms dn:A t:6ms up:A t:124ms dn:B
+    assert_eq!("t:30ms dn:A t:6ms up:A t:24ms dn:A", result);
+}
+
+#[test]
+fn tap_hold_release_tap_keys_release() {
+    let cfg = "
+        (defsrc a b c)
+        (deflayer l1
+         (tap-hold-release-tap-keys-release 100 100 x y (v) (z))
+         (tap-hold-release-tap-keys-release 100 100 x y (w) (z v))
+         (tap-hold-release-tap-keys-release 100 100 x y () (z v))
+        )
+    ";
+    let result = simulate(cfg, "d:a t:20 u:a t:20 d:a t:200").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms up:X t:14ms dn:X", result);
+    let result = simulate(cfg, "d:a t:20 u:a t:200 d:a t:200").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms up:X t:294ms dn:Y", result);
+    let result = simulate(cfg, "d:a t:50 u:a t:50").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+    let result = simulate(cfg, "d:a t:150 u:a t:50").to_ascii();
+    assert_eq!("t:100ms dn:Y t:50ms up:Y", result);
+    let result = simulate(cfg, "d:a t:50 d:z t:75").to_ascii();
+    assert_eq!("t:100ms dn:Y t:1ms dn:Z", result);
+    let result = simulate(cfg, "d:a t:50 d:z u:z t:75").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms dn:Z t:1ms up:Z", result);
+    let result = simulate(cfg, "d:a t:33 d:z t:33 d:v t:100").to_ascii();
+    assert_eq!("t:66ms dn:X t:6ms dn:Z t:1ms dn:V", result);
+    let result = simulate(cfg, "d:b t:33 d:z t:33 d:v t:100").to_ascii();
+    assert_eq!("t:100ms dn:Y t:1ms dn:Z t:1ms dn:V", result);
+    let result = simulate(cfg, "d:b t:20 d:z t:20 d:v t:20 d:w t:100").to_ascii();
+    assert_eq!("t:60ms dn:X t:6ms dn:Z t:1ms dn:V t:1ms dn:W", result);
+    let result = simulate(cfg, "d:c t:33 d:z t:33 d:v t:100").to_ascii();
+    assert_eq!("t:100ms dn:Y t:1ms dn:Z t:1ms dn:V", result);
+}
+
+#[test]
+fn tap_hold_keys_hold_on_press() {
+    let cfg = "
+        (defsrc a b c)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y (hold-on-press b))
+         b c
+        )
+    ";
+    // hold-on-press key triggers hold immediately
+    let result = simulate(cfg, "d:a t:20 d:b t:100").to_ascii();
+    assert_eq!("t:20ms dn:Y t:6ms dn:B", result);
+    // non-listed key: PermissiveHold — needs press+release for hold
+    let result = simulate(cfg, "d:a t:20 d:c t:20 u:c t:100").to_ascii();
+    assert_eq!("t:40ms dn:Y t:6ms dn:C t:1ms up:C", result);
+    // release before timeout with no other key → tap
+    let result = simulate(cfg, "d:a t:50 u:a t:100").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+    // timeout → hold
+    let result = simulate(cfg, "d:a t:150 u:a t:100").to_ascii();
+    assert_eq!("t:100ms dn:Y t:50ms up:Y", result);
+}
+
+#[test]
+fn tap_hold_keys_tap_on_press() {
+    let cfg = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y (tap-on-press b))
+         b
+        )
+    ";
+    // tap-on-press key triggers tap immediately
+    let result = simulate(cfg, "d:a t:20 d:b t:100").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:B", result);
+}
+
+#[test]
+fn tap_hold_keys_tap_on_press_release() {
+    let cfg = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y (tap-on-press-release b))
+         b
+        )
+    ";
+    // tap-on-press-release key needs press+release to trigger tap
+    let result = simulate(cfg, "d:a t:20 d:b u:b t:100").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:B t:1ms up:B", result);
+    // tap-on-press-release key pressed but not released: no early tap or hold,
+    // waits for timeout.
+    let result = simulate(cfg, "d:a t:20 d:b t:200").to_ascii();
+    assert_eq!("t:100ms dn:Y t:1ms dn:B", result);
+}
+
+#[test]
+fn tap_hold_keys_all_lists() {
+    let cfg = "
+        (defsrc a b c d e)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y
+           (tap-on-press b)
+           (tap-on-press-release c)
+           (hold-on-press d))
+         b c d e
+        )
+    ";
+    // tap-on-press
+    let result = simulate(cfg, "d:a t:20 d:b t:100").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:B", result);
+    // tap-on-press-release
+    let result = simulate(cfg, "d:a t:20 d:c u:c t:100").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:C t:1ms up:C", result);
+    // hold-on-press
+    let result = simulate(cfg, "d:a t:20 d:d t:100").to_ascii();
+    assert_eq!("t:20ms dn:Y t:6ms dn:D", result);
+    // unlisted key: PermissiveHold
+    let result = simulate(cfg, "d:a t:20 d:e t:20 u:e t:100").to_ascii();
+    assert_eq!("t:40ms dn:Y t:6ms dn:E t:1ms up:E", result);
+}
+
+#[test]
+fn tap_hold_keys_with_require_prior_idle() {
+    let cfg = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y
+           (hold-on-press b)
+           (require-prior-idle 200))
+         b
+        )
+    ";
+    // Quick typing should resolve as tap due to require-prior-idle
+    let result = simulate(cfg, "d:b t:10 u:b t:10 d:a t:50 u:a t:100").to_ascii();
+    assert_eq!("dn:B t:10ms up:B t:10ms dn:X t:50ms up:X", result);
+}
+
+#[test]
+fn tap_hold_keys_with_multiple_mods_require_prior_idle() {
+    let cfg = "
+        (defsrc)
+        (deflayermap (base)
+         a (tap-hold-keys 100 100 a b
+           (require-prior-idle 200))
+         b (tap-hold-keys 100 100 m n
+           (require-prior-idle 200))
+         c (tap-hold-keys 100 100 x y
+           (require-prior-idle 200))
+        )
+    ";
+    // Quick typing should resolve as tap due to require-prior-idle
+    let result = simulate(cfg, "d:a t:10 d:b t:10 d:c t:310").to_ascii();
+    assert_eq!("t:100ms dn:B t:101ms dn:N t:101ms dn:Y", result);
+}
+
+#[test]
+fn tap_hold_keys_with_multiple_mods_require_prior_idle_concerrent() {
+    let cfg = "
+        (defcfg concurrent-tap-hold yes)
+        (defsrc)
+        (deflayermap (base)
+         a (tap-hold-keys 100 100 a b
+           (require-prior-idle 200))
+         b (tap-hold-keys 100 100 m n
+           (require-prior-idle 200))
+         c (tap-hold-keys 100 100 x y
+           (require-prior-idle 200))
+        )
+    ";
+    // Quick typing should resolve as tap due to require-prior-idle
+    let result = simulate(cfg, "d:a t:10 d:b t:10 d:c t:130").to_ascii();
+    assert_eq!("t:99ms dn:B t:10ms dn:N t:10ms dn:Y", result);
+}
+
+#[test]
+fn tap_hold_keys_no_options() {
+    // With no key list options, tap-hold-keys behaves like tap-hold-release (PermissiveHold).
+    let cfg = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y)
+         b
+        )
+    ";
+    // press+release of another key triggers hold
+    let result = simulate(cfg, "d:a t:20 d:b t:20 u:b t:100").to_ascii();
+    assert_eq!("t:40ms dn:Y t:6ms dn:B t:1ms up:B", result);
+    // release before timeout → tap
+    let result = simulate(cfg, "d:a t:50 u:a t:100").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+    // timeout → hold
+    let result = simulate(cfg, "d:a t:150 u:a t:100").to_ascii();
+    assert_eq!("t:100ms dn:Y t:50ms up:Y", result);
+}
+
+#[test]
+fn tap_hold_keys_duplicate_key_across_lists() {
+    // A key appearing in multiple lists should be rejected at parse time.
+    let cfg = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y
+           (tap-on-press b)
+           (hold-on-press b))
+         b
+        )
+    ";
+    let result = Kanata::new_from_str(cfg, Default::default());
+    assert!(
+        result.is_err(),
+        "expected error for duplicate key across tap-on-press and hold-on-press"
+    );
+
+    let cfg2 = "
+        (defsrc a b)
+        (deflayer l1
+         (tap-hold-keys 100 100 x y
+           (tap-on-press-release b)
+           (hold-on-press b))
+         b
+        )
+    ";
+    let result = Kanata::new_from_str(cfg2, Default::default());
+    assert!(
+        result.is_err(),
+        "expected error for duplicate key across tap-on-press-release and hold-on-press"
+    );
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_basic() {
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a j k)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand tap) (unknown-hand hold))
+         j k
+        )
+    ";
+    // Opposite-hand key pressed + released → hold
+    let result = simulate(cfg, "d:a t:20 d:j t:20 u:j t:100").to_ascii();
+    assert_eq!("t:40ms dn:Y t:6ms dn:J t:1ms up:J", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_same_hand_tap() {
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a s j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand tap) (unknown-hand hold))
+         s j
+        )
+    ";
+    // Same-hand key pressed + released → tap (resolves on press, not release)
+    let result = simulate(cfg, "d:a t:20 d:s t:20 u:s t:100").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:S t:14ms up:S", result);
+
+    // Same-hand key pressed but NOT released → tap immediately on press
+    // (same-hand doesn't require release, only opposite-hand does)
+    let result = simulate(cfg, "d:a t:20 d:s t:250").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms dn:S", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_no_interrupt() {
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand tap) (unknown-hand hold))
+         j
+        )
+    ";
+    // Released before timeout, no interrupt → tap
+    let result = simulate(cfg, "d:a t:50 u:a t:100").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+
+    // Timeout, no interrupt → timeout action (tap by default)
+    let result = simulate(cfg, "d:a t:250 u:a t:100").to_ascii();
+    assert_eq!("t:200ms dn:X t:50ms up:X", result);
+
+    // With (timeout hold), timeout → hold
+    let cfg_timeout_hold = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand tap) (unknown-hand hold) (timeout hold))
+         j
+        )
+    ";
+    let result = simulate(cfg_timeout_hold, "d:a t:250 u:a t:100").to_ascii();
+    assert_eq!("t:200ms dn:Y t:50ms up:Y", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_vs_press() {
+    // Compare: press-time (existing) vs release-time (new)
+    // With press-time, opposite-hand key triggers hold immediately on press.
+    // With release-time, it waits for the key's release.
+    let cfg_press = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a j)
+        (deflayer l1
+         (tap-hold-opposite-hand 200 x y (same-hand tap) (unknown-hand hold))
+         j
+        )
+    ";
+    let cfg_release = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand tap) (unknown-hand hold))
+         j
+        )
+    ";
+    // Press-time: hold decides on press (before j is released)
+    let result = simulate(cfg_press, "d:a t:20 d:j t:100").to_ascii();
+    assert_eq!("t:20ms dn:Y t:6ms dn:J", result);
+
+    // Release-time: does NOT decide on press alone — waits for release
+    let result = simulate(cfg_release, "d:a t:20 d:j t:20 u:j t:100").to_ascii();
+    assert_eq!("t:40ms dn:Y t:6ms dn:J t:1ms up:J", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_with_require_prior_idle() {
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a s j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y
+           (same-hand tap) (unknown-hand hold) (require-prior-idle 200))
+         s j
+        )
+    ";
+    // Quick typing should resolve as tap due to require-prior-idle
+    let result = simulate(cfg, "d:s t:10 u:s t:10 d:a t:50 u:a t:100").to_ascii();
+    assert_eq!("dn:S t:10ms up:S t:10ms dn:X t:50ms up:X", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_same_hand_hold() {
+    // (same-hand hold) should trigger hold immediately on press (no release needed)
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a s j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y (same-hand hold) (unknown-hand hold))
+         s j
+        )
+    ";
+    let result = simulate(cfg, "d:a t:20 d:s t:20 u:s t:100").to_ascii();
+    assert_eq!("t:20ms dn:Y t:6ms dn:S t:14ms up:S", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_same_hand_then_opposite() {
+    // Regression test: pressing two same-hand HRM keys together then an
+    // opposite-hand key should resolve the first as tap (via same-hand),
+    // not as hold (via opposite-hand release).
+    // Bug: the -release variant required ALL keys to have press+release before
+    // considering them, so same-hand keys were skipped if still held, and the
+    // opposite-hand key's release incorrectly triggered Hold.
+    let cfg = "
+        (defcfg concurrent-tap-hold yes process-unmapped-keys yes)
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc d f j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 500 d lsft (same-hand tap) (timeout tap))
+         (tap-hold-opposite-hand-release 500 f lctl (same-hand tap) (timeout tap))
+         j
+        )
+    ";
+    // f↓ d↓ j↓ j↑ → f sees d (same-hand) → tap immediately; d sees j (opposite+release) → hold
+    // Result: f (tap) at t=5, then lsft+j when j is released at t=45
+    let result = simulate(cfg, "d:f t:5 d:d t:20 d:j t:20 u:j t:100").to_ascii();
+    assert_eq!("t:5ms dn:F t:40ms dn:LShift t:6ms dn:J t:1ms up:J", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_same_hand_ignore() {
+    // (same-hand ignore) should skip same-hand keys and wait for timeout
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a s j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y
+           (same-hand ignore) (unknown-hand hold) (timeout hold))
+         s j
+        )
+    ";
+    // Same-hand key pressed+released is ignored, timeout fires
+    let result = simulate(cfg, "d:a t:20 d:s t:20 u:s t:250").to_ascii();
+    assert_eq!("t:200ms dn:Y t:1ms dn:S t:1ms up:S", result);
+}
+
+#[test]
+fn tap_hold_opposite_hand_release_neutral_keys() {
+    let cfg = "
+        (defhands
+          (left  a s d f)
+          (right j k l ;))
+        (defsrc a spc j)
+        (deflayer l1
+         (tap-hold-opposite-hand-release 200 x y
+           (same-hand tap) (unknown-hand hold) (neutral-keys spc) (neutral tap))
+         spc j
+        )
+    ";
+    // spc is in neutral-keys with (neutral tap) → tap on press+release
+    let result = simulate(cfg, "d:a t:20 d:spc t:20 u:spc t:100").to_ascii();
+    assert_eq!("t:40ms dn:X t:6ms dn:Space t:1ms up:Space", result);
+}
+
+#[test]
+fn tap_hold_release_keys() {
+    let cfg = "
+        (defsrc a)
+        (deflayer l1 (tap-hold-release-keys 100 100 x y (z)))
+    ";
+    let result = simulate(cfg, "d:a t:20 u:a t:20 d:a t:200").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms up:X t:14ms dn:X", result);
+    let result = simulate(cfg, "d:a t:20 u:a t:200 d:a t:200").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms up:X t:294ms dn:Y", result);
+    let result = simulate(cfg, "d:a t:50 u:a t:50").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+    let result = simulate(cfg, "d:a t:150 u:a t:50").to_ascii();
+    assert_eq!("t:100ms dn:Y t:50ms up:Y", result);
+    let result = simulate(cfg, "d:a t:50 d:z t:75").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms dn:Z", result);
+    let result = simulate(cfg, "d:a t:50 d:z u:z t:75").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms dn:Z t:1ms up:Z", result);
+}
+
+#[test]
+fn tap_hold_tap_keys() {
+    let cfg = "
+        (defsrc a b z)
+        (deflayer l1 (tap-hold-tap-keys 100 100 x y (z)) b z)
+    ";
+
+    // Basic tap: release before timeout → tap action
+    let result = simulate(cfg, "d:a t:50 u:a t:50").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms up:X", result);
+
+    // Basic hold: timeout elapsed → hold action
+    let result = simulate(cfg, "d:a t:150 u:a t:50").to_ascii();
+    assert_eq!("t:100ms dn:Y t:50ms up:Y", result);
+
+    // $tap-keys (z) pressed → immediate tap
+    let result = simulate(cfg, "d:a t:50 d:z t:75").to_ascii();
+    assert_eq!("t:50ms dn:X t:6ms dn:Z", result);
+
+    // KEY DIFFERENCE from tap-hold-release-keys:
+    // Other key (b) pressed+released → wait for timeout, NOT immediate hold
+    // This is the critical behavioral difference that tap-hold-tap-keys provides
+    let result = simulate(cfg, "d:a t:50 d:b u:b t:100").to_ascii();
+    // After 100ms timeout, hold activates, then b events are replayed
+    // d:b and u:b have no delay between them, so both replay with minimal gap
+    assert_eq!("t:100ms dn:Y t:1ms dn:B t:1ms up:B", result);
+
+    // Tap repress behavior
+    let result = simulate(cfg, "d:a t:20 u:a t:20 d:a t:200").to_ascii();
+    assert_eq!("t:20ms dn:X t:6ms up:X t:14ms dn:X", result);
+}
+
+// ========== tap-hold-opposite-hand tests ==========
+
+fn opposite_hand_cfg() -> &'static str {
+    "
+    (defhands
+      (left a s d f g)
+      (right h j k l ;))
+    (defsrc f j h)
+    (deflayer base @f j h)
+    (defalias
+      f (tap-hold-opposite-hand 200 f lctl))
+    "
+}
+
+#[test]
+fn opposite_hand_press_resolves_hold() {
+    // Press f (left hand), then j (right hand) -> should resolve as HOLD (lctl)
+    let result = simulate(opposite_hand_cfg(), "d:f t:50 d:j t:50 u:j t:50 u:f t:50").to_ascii();
+    assert_eq!(
+        "t:50ms dn:LCtrl t:6ms dn:J t:44ms up:J t:50ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn same_hand_press_resolves_tap() {
+    // Press f (left hand), then d (left hand) -> same hand default = tap
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc d f)
+        (deflayer base d @f)
+        (defalias f (tap-hold-opposite-hand 200 f lctl))
+        ",
+        "d:f t:50 d:d t:50 u:d t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:50ms dn:F t:6ms dn:D t:44ms up:D t:50ms up:F", result);
+}
+
+#[test]
+fn same_hand_ignore_defers_to_timeout() {
+    // With (same-hand ignore), a same-hand press is ignored, timeout fires
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc d f)
+        (deflayer base d @f)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (same-hand ignore)))
+        ",
+        "d:f t:50 d:d t:200 u:d t:50 u:f t:50",
+    )
+    .to_ascii();
+    // timeout (default=tap) fires at 200ms from f press
+    assert_eq!("t:200ms dn:F t:1ms dn:D t:49ms up:D t:50ms up:F", result);
+}
+
+#[test]
+fn neutral_key_ignore_defers() {
+    // With default (neutral ignore), neutral keys are skipped, timeout fires
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f h spc)
+        (deflayer base @f h spc)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (neutral-keys spc)))
+        ",
+        "d:f t:50 d:spc t:200 u:spc t:50 u:f t:50",
+    )
+    .to_ascii();
+    // spc is neutral, default (neutral ignore), so timeout fires
+    assert_eq!(
+        "t:200ms dn:F t:1ms dn:Space t:49ms up:Space t:50ms up:F",
+        result
+    );
+}
+
+#[test]
+fn neutral_key_tap_resolves_immediately() {
+    // With (neutral tap), neutral key press triggers TAP immediately
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f h spc)
+        (deflayer base @f h spc)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (neutral-keys spc) (neutral tap)))
+        ",
+        "d:f t:50 d:spc t:50 u:spc t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:50ms dn:F t:6ms dn:Space t:44ms up:Space t:50ms up:F",
+        result
+    );
+}
+
+#[test]
+fn unknown_hand_key_defers_by_default() {
+    // Key not in defhands at all -> unknown hand, default = ignore
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f b)
+        (deflayer base @f b)
+        (defalias f (tap-hold-opposite-hand 200 f lctl))
+        ",
+        "d:f t:50 d:b t:200 u:b t:50 u:f t:50",
+    )
+    .to_ascii();
+    // b is not in defhands, unknown-hand default = ignore, timeout fires
+    assert_eq!("t:200ms dn:F t:1ms dn:B t:49ms up:B t:50ms up:F", result);
+}
+
+#[test]
+fn timeout_default_is_tap() {
+    // Default timeout behavior is tap
+    let result = simulate(opposite_hand_cfg(), "d:f t:250 u:f t:50").to_ascii();
+    assert_eq!("t:200ms dn:F t:50ms up:F", result);
+}
+
+#[test]
+fn timeout_hold_option() {
+    // (timeout hold) makes timeout resolve to hold action
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f j)
+        (deflayer base @f j)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (timeout hold)))
+        ",
+        "d:f t:250 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:200ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn release_before_timeout_taps() {
+    // Release the hold-tap key before timeout -> immediate tap
+    let result = simulate(opposite_hand_cfg(), "d:f t:50 u:f t:50").to_ascii();
+    assert_eq!("t:50ms dn:F t:6ms up:F", result);
+}
+
+#[test]
+fn multiple_options_combined() {
+    // Combine (same-hand hold), (timeout hold), (neutral-keys ...) with (neutral tap)
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc d f j spc)
+        (deflayer base d @f j spc)
+        (defalias f (tap-hold-opposite-hand 200 f lctl
+          (same-hand hold) (timeout hold)
+          (neutral-keys spc) (neutral tap)))
+        ",
+        "d:f t:50 d:d t:50 u:d t:50 u:f t:50",
+    )
+    .to_ascii();
+    // d is same hand, (same-hand hold) -> resolves as hold
+    assert_eq!(
+        "t:50ms dn:LCtrl t:6ms dn:D t:44ms up:D t:50ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn unknown_hand_tap_resolves_immediately() {
+    // (unknown-hand tap) makes unassigned keys resolve as tap
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f b)
+        (deflayer base @f b)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (unknown-hand tap)))
+        ",
+        "d:f t:50 d:b t:50 u:b t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:50ms dn:F t:6ms dn:B t:44ms up:B t:50ms up:F", result);
+}
+
+#[test]
+fn unknown_hand_hold_resolves_immediately() {
+    // (unknown-hand hold) makes unassigned keys resolve as hold
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f b)
+        (deflayer base @f b)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (unknown-hand hold)))
+        ",
+        "d:f t:50 d:b t:50 u:b t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:50ms dn:LCtrl t:6ms dn:B t:44ms up:B t:50ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn neutral_key_hold_resolves_immediately() {
+    // (neutral hold) makes neutral keys resolve as hold
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f h spc)
+        (deflayer base @f h spc)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (neutral-keys spc) (neutral hold)))
+        ",
+        "d:f t:50 d:spc t:50 u:spc t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:50ms dn:LCtrl t:6ms dn:Space t:44ms up:Space t:50ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn waiting_key_unassigned_in_defhands() {
+    // The hold-tap key (b) is NOT in defhands, so its hand is unknown.
+    // Pressing j (right hand) still triggers unknown-hand logic (both sides unknown = unknown).
+    // Default (unknown-hand ignore), so it defers; timeout fires as tap.
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc b j)
+        (deflayer base @b j)
+        (defalias b (tap-hold-opposite-hand 200 b lctl))
+        ",
+        "d:b t:50 d:j t:200 u:j t:50 u:b t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:200ms dn:B t:1ms dn:J t:49ms up:J t:50ms up:B", result);
+}
+
+#[test]
+fn neutral_keys_override_defhands_assignment() {
+    // j is in defhands (right hand), but also in (neutral-keys ...).
+    // (neutral-keys ...) takes precedence, so j is treated as neutral.
+    // With (neutral tap), pressing j should resolve as tap (not hold).
+    let result = simulate(
+        "
+        (defhands (left a s d f g) (right h j k l ;))
+        (defsrc f j)
+        (deflayer base @f j)
+        (defalias f (tap-hold-opposite-hand 200 f lctl (neutral-keys j) (neutral tap)))
+        ",
+        "d:f t:50 d:j t:50 u:j t:50 u:f t:50",
+    )
+    .to_ascii();
+    // j would normally be opposite-hand (hold), but neutral-keys overrides -> tap
+    assert_eq!("t:50ms dn:F t:6ms dn:J t:44ms up:J t:50ms up:F", result);
+}
+
+// ========== tap-hold-require-prior-idle tests ==========
+
+#[test]
+fn tap_hold_require_prior_idle_typing_streak_resolves_tap() {
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a b d)
+(deflayer base a b @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        // Type a, release, then quickly press d within idle window.
+        // 'a' was pressed 20ms ago (10ms press + 10ms gap), well within 150ms threshold.
+        "d:a t:10 u:a t:10 d:d t:50 u:d t:50",
+    )
+    .to_ascii();
+    // d should resolve as tap immediately (no 200ms waiting state)
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:D t:50ms up:D", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_idle_long_enough_enters_hold() {
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a b d)
+(deflayer base a b @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        // Press a, release, wait 200ms (longer than 150ms threshold), then press d.
+        // d should enter normal WaitingState (hold on other key press).
+        "d:a t:10 u:a t:200 d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // After 200ms idle, d enters normal tap-hold. Timeout at 200ms → hold (lctl).
+    assert_eq!("dn:A t:10ms up:A t:400ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_no_prior_key_enters_hold() {
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a b d)
+(deflayer base a b @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        // No prior key at all. d should enter normal WaitingState.
+        "d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // Timeout → hold (lctl)
+    assert_eq!("t:200ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_boundary_just_within_threshold() {
+    // Prior key pressed 149ms ago (just within 150ms threshold).
+    // ticks_since_occurrence will be ~150 (149 + 1 tick offset), which is
+    // <= 150 threshold, so tap fires.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        "d:a t:10 u:a t:139 d:d t:50 u:d t:50",
+    )
+    .to_ascii();
+    assert_eq!("dn:A t:10ms up:A t:139ms dn:D t:50ms up:D", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_boundary_just_outside_threshold() {
+    // Prior key pressed 150ms ago (just outside 150ms threshold).
+    // ticks_since_occurrence will be ~151 (150 + 1 tick offset), which is
+    // > 150 threshold, so normal tap-hold behavior applies.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        // d enters WaitingState; released at 50ms → tap via release
+        "d:a t:10 u:a t:140 d:d t:50 u:d t:50",
+    )
+    .to_ascii();
+    assert_eq!("dn:A t:10ms up:A t:190ms dn:D t:6ms up:D", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_with_opposite_hand() {
+    // tap-hold-require-prior-idle should short-circuit before tap-hold-opposite-hand
+    // evaluates hand membership. During a typing streak, even an opposite-hand
+    // key should resolve as tap.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defhands (left a s d f g) (right h j k l ;))
+(defsrc a f j)
+(deflayer base a @f j)
+(defalias f (tap-hold-opposite-hand 200 f lctl))
+        ",
+        // a is left hand, f is left hand tap-hold. a pressed 20ms ago.
+        // Without tap-hold-require-prior-idle, pressing j (opposite hand) would hold.
+        // With tap-hold-require-prior-idle active, f resolves as tap before hand check.
+        "d:a t:10 u:a t:10 d:f t:50 u:f t:50",
+    )
+    .to_ascii();
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:F t:50ms up:F", result);
+}
+
+#[test]
+fn tap_repress_timeout_opposite_hand() {
+    let cfg = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc f j)
+(deflayer base @f j)
+(defalias f (tap-hold-opposite-hand 200 f lctl (tap-repress-timeout 100)))
+    ";
+    // Re-press within tap-repress-timeout → immediate tap (no hold decision)
+    let result = simulate(cfg, "d:f t:30 u:f t:30 d:f t:300 u:f t:50").to_ascii();
+    assert_eq!("t:30ms dn:F t:6ms up:F t:24ms dn:F t:300ms up:F", result);
+    // Re-press after tap-repress-timeout expires → enters hold decision, timeout → tap
+    let result = simulate(cfg, "d:f t:30 u:f t:200 d:f t:300 u:f t:50").to_ascii();
+    assert_eq!("t:30ms dn:F t:6ms up:F t:394ms dn:F t:100ms up:F", result);
+}
+
+#[test]
+fn tap_repress_timeout_opposite_hand_release() {
+    let cfg = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc f j)
+(deflayer base @f j)
+(defalias f (tap-hold-opposite-hand-release 200 f lctl (tap-repress-timeout 100)))
+    ";
+    // Re-press within tap-repress-timeout → immediate tap
+    let result = simulate(cfg, "d:f t:30 u:f t:30 d:f t:300 u:f t:50").to_ascii();
+    assert_eq!("t:30ms dn:F t:6ms up:F t:24ms dn:F t:300ms up:F", result);
+    // Re-press after tap-repress-timeout expires → enters hold decision, timeout → tap
+    let result = simulate(cfg, "d:f t:30 u:f t:200 d:f t:300 u:f t:50").to_ascii();
+    assert_eq!("t:30ms dn:F t:6ms up:F t:394ms dn:F t:100ms up:F", result);
+}
+
+#[test]
+fn tap_repress_timeout_opposite_hand_zero_disables() {
+    let cfg = "
+(defhands (left a s d f) (right j k l ;))
+(defsrc f j)
+(deflayer base @f j)
+(defalias f (tap-hold-opposite-hand 200 f lctl (tap-repress-timeout 0)))
+    ";
+    // tap-repress-timeout 0 → every press enters hold decision (same as no option)
+    let result = simulate(cfg, "d:f t:30 u:f t:30 d:f t:300 u:f t:50").to_ascii();
+    assert_eq!("t:30ms dn:F t:6ms up:F t:224ms dn:F t:100ms up:F", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_with_tap_hold_interval() {
+    // tap-hold-require-prior-idle check runs before tap-hold-interval (quick re-press).
+    // Both should work together: typing streak → tap immediately,
+    // idle re-press → tap via tap_hold_interval.
+    let cfg = "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl))
+    ";
+    // Case 1: typing streak (a then d quickly) → tap-hold-require-prior-idle fires
+    let result = simulate(cfg, "d:a t:10 u:a t:10 d:d t:50 u:d t:50").to_ascii();
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:D t:50ms up:D", result);
+    // Case 2: idle, then d pressed twice (tap-hold-interval re-press)
+    let result = simulate(cfg, "d:d t:50 u:d t:50 d:d t:50 u:d t:50").to_ascii();
+    assert_eq!("t:50ms dn:D t:6ms up:D t:44ms dn:D t:50ms up:D", result);
+}
+
+#[test]
+fn tap_hold_require_prior_idle_ignores_virtual_keys() {
+    // Virtual key events (row 1) should not count as prior physical input.
+    // Only real physical key presses (row 0) trigger the typing streak.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc d)
+(defvirtualkeys vk1 a)
+(deflayer base @d)
+(defalias d (tap-hold 200 200 d lctl))
+        ",
+        // Virtual key tap, then d pressed 10ms later.
+        // vk should NOT trigger typing streak — d should enter normal hold.
+        "vk:vk1:tap t:10 d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // Virtual key outputs A, then d times out to hold (lctl).
+    assert_eq!("dn:A t:1ms up:A t:209ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+// ========== per-action require-prior-idle override tests ==========
+
+#[test]
+fn per_action_require_prior_idle_overrides_global() {
+    // Global defcfg sets 150ms, but per-action override sets 50ms.
+    // A prior key 60ms ago is within 150ms (global) but outside 50ms (per-action).
+    // Per-action should win: normal hold behavior, not tap.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl (require-prior-idle 50)))
+        ",
+        "d:a t:10 u:a t:50 d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // 60ms gap > 50ms per-action threshold → normal hold
+    assert_eq!("dn:A t:10ms up:A t:250ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn per_action_require_prior_idle_disable_overrides_global() {
+    // Global defcfg sets 150ms, but per-action override sets 0 (disabled).
+    // Even during a typing streak, this action should use normal tap-hold.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl (require-prior-idle 0)))
+        ",
+        // a pressed 20ms ago, well within 150ms global threshold.
+        // But per-action disables it, so d enters normal WaitingState.
+        "d:a t:10 u:a t:10 d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // d enters hold (250ms > 200ms timeout)
+    assert_eq!("dn:A t:10ms up:A t:210ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn per_action_require_prior_idle_enables_without_global() {
+    // No global defcfg (default 0), but per-action sets 150ms.
+    // The per-action value should enable the feature for this action only.
+    let result = simulate(
+        "
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold 200 200 d lctl (require-prior-idle 150)))
+        ",
+        "d:a t:10 u:a t:10 d:d t:50 u:d t:50",
+    )
+    .to_ascii();
+    // a pressed 20ms ago, within 150ms per-action threshold → tap
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:D t:50ms up:D", result);
+}
+
+#[test]
+fn per_action_require_prior_idle_mixed_actions() {
+    // The issue #1967 use case: two tap-hold keys with different idle behavior.
+    // @a (HRM) uses the global 150ms threshold.
+    // @d (layer key) disables idle detection via per-action override.
+    // During a typing streak, @a should resolve as tap but @d should hold.
+    let cfg = "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d e)
+(deflayer base @a @d e)
+(defalias
+  a (tap-hold-press 200 200 a lmet)
+  d (tap-hold-press 200 200 d lctl (require-prior-idle 0))
+)
+    ";
+    // Case 1: type e, then quickly press @a → global idle fires, a resolves as tap
+    let result = simulate(cfg, "d:e t:10 u:e t:10 d:a t:50 u:a t:50").to_ascii();
+    assert_eq!("dn:E t:10ms up:E t:10ms dn:A t:50ms up:A", result);
+    // Case 2: type e, then quickly press @d → per-action 0 disables idle, d enters hold.
+    // tap-hold-press resolves on next key press: e pressed 10ms after d triggers hold.
+    let result = simulate(cfg, "d:e t:10 u:e t:10 d:d t:10 d:e t:50 u:e t:50 u:d t:50").to_ascii();
+    assert_eq!(
+        "dn:E t:10ms up:E t:20ms dn:LCtrl t:6ms dn:E t:44ms up:E t:50ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn per_action_require_prior_idle_with_tap_hold_release() {
+    // Per-action option works with tap-hold-release variant.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold-release 200 200 d lctl (require-prior-idle 0)))
+        ",
+        // Typing streak: a pressed 20ms ago. Global would force tap,
+        // but per-action 0 disables it.
+        "d:a t:10 u:a t:10 d:d t:250 u:d t:50",
+    )
+    .to_ascii();
+    // d enters normal hold (per-action override disables idle check)
+    assert_eq!("dn:A t:10ms up:A t:210ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+#[test]
+fn per_action_require_prior_idle_with_opposite_hand() {
+    // Per-action option works with tap-hold-opposite-hand variant.
+    // Use j (right hand) pressing before f (left hand tap-hold).
+    // Without require-prior-idle, j is opposite-hand → f would hold.
+    // With global require-prior-idle 150, the typing streak forces tap.
+    // With per-action override 0, the override disables it and f holds.
+    let result = simulate(
+        "
+(defcfg tap-hold-require-prior-idle 150)
+(defhands (left a s d f g) (right h j k l ;))
+(defsrc j f)
+(deflayer base j @f)
+(defalias f (tap-hold-opposite-hand 200 f lctl
+  (timeout hold)
+  (require-prior-idle 0)))
+        ",
+        // j (right) pressed 20ms ago, then f (left) pressed.
+        // Global 150ms would force tap, but per-action 0 disables it.
+        // j is opposite hand → f should hold. timeout → hold.
+        "d:j t:10 u:j t:10 d:f t:250 u:f t:50",
+    )
+    .to_ascii();
+    // f enters normal opposite-hand behavior: j is opposite → hold
+    assert_eq!("dn:J t:10ms up:J t:210ms dn:LCtrl t:50ms up:LCtrl", result);
+}
+
+// ========== tap-hold-order simulation tests ==========
+// Note: t:6ms gaps after resolution are sim framework processing overhead for
+// event-triggered resolution (as opposed to timeout-triggered). This is consistent
+// with other event-driven tap-hold variants (e.g., tap-hold-opposite-hand).
+
+#[test]
+fn tap_hold_order_clean_tap() {
+    // Press and release tap-hold-order key with no other keys → Tap.
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-order 200 50 a lctl))
+        ",
+        "d:a t:100 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:100ms dn:A t:6ms up:A", result);
+}
+
+#[test]
+fn tap_hold_order_hold_other_released_first() {
+    // TH down → other down → other up (released first) → Hold.
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-order 200 0 a lctl))
+        ",
+        "d:a t:10 d:b t:10 u:b t:10 u:a t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:20ms dn:LCtrl t:6ms dn:B t:1ms up:B t:3ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn tap_hold_order_tap_modifier_released_first() {
+    // TH down → other down → TH up first → Tap.
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-order 200 0 a lctl))
+        ",
+        "d:a t:10 d:b t:10 u:a t:10 u:b t:50",
+    )
+    .to_ascii();
+    assert_eq!("t:20ms dn:A t:6ms dn:B t:1ms up:A t:3ms up:B", result);
+}
+
+#[test]
+fn tap_hold_order_buffer_ignores_fast_typing() {
+    // Other key pressed+released within buffer window → ignored by
+    // release-order logic. TH released → Tap.
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-order 200 50 a lctl))
+        ",
+        "d:a t:10 d:b t:10 u:b t:10 u:a t:50",
+    )
+    .to_ascii();
+    // Without buffer, b's press+release would trigger Hold.
+    // With buffer=50, b's press at 10ms is within window → ignored → Tap.
+    assert_eq!("t:30ms dn:A t:6ms dn:B t:1ms up:B t:1ms up:A", result);
+}
+
+#[test]
+fn tap_hold_order_hold_after_buffer_expires() {
+    // Other key pressed after buffer window expires → release-order applies.
+    // Other released first → Hold.
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer base @a b)
+(defalias a (tap-hold-order 200 50 a lctl))
+        ",
+        "d:a t:60 d:b t:10 u:b t:10 u:a t:50",
+    )
+    .to_ascii();
+    // b pressed at 60ms (after 50ms buffer) → release-order active.
+    // b released first → Hold.
+    assert_eq!(
+        "t:70ms dn:LCtrl t:6ms dn:B t:1ms up:B t:3ms up:LCtrl",
+        result
+    );
+}
+
+#[test]
+fn tap_hold_order_with_require_prior_idle() {
+    // Per-action require-prior-idle short-circuits to tap during typing streak.
+    let result = simulate(
+        "
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold-order 200 50 d lctl (require-prior-idle 150)))
+        ",
+        // a pressed 20ms ago → within 150ms idle threshold → tap immediately.
+        "d:a t:10 u:a t:10 d:d t:50 u:d t:50",
+    )
+    .to_ascii();
+    assert_eq!("dn:A t:10ms up:A t:10ms dn:D t:50ms up:D", result);
+}
+
+#[test]
+fn tap_hold_order_no_prior_idle_enters_normal_resolution() {
+    // No recent keypress → require-prior-idle doesn't fire → normal release-order.
+    // Other key released first → Hold.
+    let result = simulate(
+        "
+(defsrc a d)
+(deflayer base a @d)
+(defalias d (tap-hold-order 200 0 d lctl (require-prior-idle 150)))
+        ",
+        "d:d t:10 d:a t:10 u:a t:10 u:d t:50",
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:20ms dn:LCtrl t:6ms dn:A t:1ms up:A t:3ms up:LCtrl",
+        result
+    );
+}
diff --git a/src/tests/sim_tests/template_sim_tests.rs b/src/tests/sim_tests/template_sim_tests.rs
new file mode 100644
index 000000000..30ebb8426
--- /dev/null
+++ b/src/tests/sim_tests/template_sim_tests.rs
@@ -0,0 +1,21 @@
+use super::*;
+
+#[test]
+fn nested_template() {
+    let result = simulate(
+        "
+        (deftemplate one (v1)
+         a b c $v1
+        )
+        (deftemplate two (v2)
+         (t! one $v2)
+         e f g
+        )
+        (defsrc        (t! two d))
+        (deflayer base (t! two x))
+        ",
+        "d:a t:10 u:a t:10 d:d t:10 u:d t:10 d:g t:10 u:g t:10",
+    )
+    .no_time();
+    assert_eq!("out:↓A out:↑A out:↓X out:↑X out:↓G out:↑G", result);
+}
diff --git a/src/tests/sim_tests/timing_tests.rs b/src/tests/sim_tests/timing_tests.rs
new file mode 100644
index 000000000..65b345ee6
--- /dev/null
+++ b/src/tests/sim_tests/timing_tests.rs
@@ -0,0 +1,28 @@
+use std::thread::sleep;
+use std::time::Duration;
+
+use crate::Kanata;
+
+use web_time::Instant;
+
+#[test]
+fn one_second_is_roughly_1000_counted_ticks() {
+    let mut k = Kanata::new_from_str("(defsrc)(deflayer base)", Default::default())
+        .expect("failed to parse cfg");
+
+    let mut accumulated_ticks = 0;
+
+    let start = Instant::now();
+    while start.elapsed() < Duration::from_secs(1) {
+        sleep(Duration::from_millis(1));
+        accumulated_ticks += k.get_ms_elapsed();
+    }
+
+    let actually_elapsed_ms = start.elapsed().as_millis();
+
+    // Allow fudge of 1%
+    // In practice this is within 1ms purely due to the remainder.
+    eprintln!("ticks:{accumulated_ticks}, actual elapsed:{actually_elapsed_ms}");
+    assert!(accumulated_ticks < (actually_elapsed_ms + 10));
+    assert!(accumulated_ticks > (actually_elapsed_ms - 10));
+}
diff --git a/src/tests/sim_tests/unicode_sim_tests.rs b/src/tests/sim_tests/unicode_sim_tests.rs
new file mode 100644
index 000000000..387394042
--- /dev/null
+++ b/src/tests/sim_tests/unicode_sim_tests.rs
@@ -0,0 +1,68 @@
+use super::*;
+
+#[test]
+fn unicode() {
+    let result = simulate(
+        r##"
+         (defcfg)
+         (defsrc 6 7 8 9 0 f1)
+         (deflayer base
+             (unicode r#"("#)
+             (unicode r#")"#)
+             (unicode r#"""#)
+             (unicode "(")
+             (unicode ")")
+             (tap-dance 200 (f1(unicode 😀)f2(unicode 🙂)))
+         )
+        "##,
+        "d:6 d:7 d:8 d:9 d:0 t:100",
+    )
+    .no_time();
+    assert_eq!(r#"outU:( outU:) outU:" outU:( outU:)"#, result);
+}
+
+#[test]
+#[cfg(target_os = "macos")]
+fn macos_unicode_handling() {
+    let result = simulate(
+        r##"
+         (defcfg)
+         (defsrc a)
+         (deflayer base
+             (unicode "🎉")  ;; Test with an emoji that uses multi-unit UTF-16
+         )
+        "##,
+        "d:a t:100",
+    )
+    .no_time();
+    assert_eq!("outU:🎉", result);
+}
+
+#[test]
+fn unicode_pulus() {
+    let result = simulate(
+        "
+(defsrc a b)
+(deflayer _
+ (unicode 🚆)
+ (unicode U+1F686)
+)
+        ",
+        "d:a t:10 d:b t:10",
+    )
+    .no_time();
+    assert_eq!("outU:🚆 outU:🚆", result);
+}
+
+#[test]
+fn unicode_multi() {
+    let result = simulate(
+        "
+        (defsrc a)
+        (deflayer l (multi (unicode a) (fork (unicode b) XX ())))
+        ",
+        "d:KeyA t:5 u:KeyA t:5",
+    )
+    .to_ascii();
+    assert_eq!("outU:a t:1ms outU:b", result);
+}
diff --git a/src/tests/sim_tests/unmod_sim_tests.rs b/src/tests/sim_tests/unmod_sim_tests.rs
new file mode 100644
index 000000000..b8749d967
--- /dev/null
+++ b/src/tests/sim_tests/unmod_sim_tests.rs
@@ -0,0 +1,108 @@
+use super::*;
+
+#[test]
+fn unmod_keys_functionality_works() {
+    let result = simulate(
+        "
+         (defcfg)
+         (defsrc f1 1 2 3 4 5 6 7 8 9 0)
+         (deflayer base
+             (multi lctl rctl lsft rsft lmet rmet lalt ralt)
+             (unmod a)
+             (unmod (lctl) b)
+             (unmod (rctl) c)
+             (unmod (lsft) d)
+             (unmod (rsft) e)
+             (unmod (lmet) f)
+             (unmod (rmet) g)
+             (unmod (lalt) h)
+             (unmod (ralt) i)
+             (unmod (lctl lsft lmet lalt) j)
+         )
+        ",
+        "d:f1 t:5 d:1 u:1 t:5 d:2 u:2 t:5 d:3 u:3 t:5 d:4 u:4 t:5 d:5 u:5 t:5 d:6 u:6 t:5
+                  d:7 u:7 t:5 d:8 u:8 t:5 d:9 u:9 t:5 d:0 u:0 t:5",
+    )
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:LCtrl dn:RCtrl dn:LShift dn:RShift dn:LGui dn:RGui dn:LAlt dn:RAlt \
+         up:LCtrl up:RCtrl up:LShift up:RShift up:LGui up:RGui up:LAlt up:RAlt dn:A up:A \
+         dn:LCtrl dn:RCtrl dn:LShift dn:RShift dn:LGui dn:RGui dn:LAlt dn:RAlt \
+         up:LCtrl dn:B up:B dn:LCtrl \
+         up:RCtrl dn:C up:C dn:RCtrl \
+         up:LShift dn:D up:D dn:LShift \
+         up:RShift dn:E up:E dn:RShift \
+         up:LGui dn:F up:F dn:LGui \
+         up:RGui dn:G up:G dn:RGui \
+         up:LAlt dn:H up:H dn:LAlt \
+         up:RAlt dn:I up:I dn:RAlt \
+         up:LCtrl up:LShift up:LGui up:LAlt dn:J up:J dn:LCtrl dn:LShift dn:LGui dn:LAlt",
+        result
+    );
+}
+
+#[test]
+#[should_panic]
+fn unmod_keys_mod_list_cannot_be_empty() {
+    simulate(
+        "
+         (defcfg)
+         (defsrc a)
+         (deflayer base (unmod () a))
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn unmod_keys_mod_list_cannot_have_nonmod_key() {
+    simulate(
+        "
+         (defcfg)
+         (defsrc a)
+         (deflayer base (unmod (lmet c) a))
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn unmod_keys_mod_list_cannot_have_empty_keys_after_mod_list() {
+    simulate(
+        "
+         (defcfg)
+         (defsrc a)
+         (deflayer base (unmod (lmet)))
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn unmod_keys_mod_list_cannot_have_empty_keys() {
+    simulate(
+        "
+         (defcfg)
+         (defsrc a)
+         (deflayer base (unmod))
+        ",
+        "",
+    );
+}
+
+#[test]
+#[should_panic]
+fn unmod_keys_mod_list_cannot_have_invalid_keys() {
+    simulate(
+        "
+         (defcfg)
+         (defsrc a)
+         (deflayer base (unmod invalid-key))
+        ",
+        "",
+    );
+}
diff --git a/src/tests/sim_tests/use_defsrc_sim_tests.rs b/src/tests/sim_tests/use_defsrc_sim_tests.rs
new file mode 100644
index 000000000..54c469f80
--- /dev/null
+++ b/src/tests/sim_tests/use_defsrc_sim_tests.rs
@@ -0,0 +1,57 @@
+use super::*;
+
+#[test]
+fn use_defsrc_deflayer() {
+    let result = simulate(
+        r##"
+         (defcfg)
+         (defsrc a b c d)
+         (deflayer base
+            1 2 3 (layer-while-held other)
+         )
+         (deflayer other
+            4 5 (layer-while-held src) XX
+         )
+         (deflayer src
+            use-defsrc use-defsrc XX XX
+         )
+        "##,
+        "d:d d:c d:b d:a t:100",
+    )
+    .to_ascii();
+    assert_eq!("t:2ms dn:B t:1ms dn:A", result);
+}
+
+#[test]
+fn use_defsrc_deflayermap() {
+    const CFG: &str = "
+         (defcfg process-unmapped-keys yes)
+         (defsrc a b c d)
+         (deflayer base
+            1
+            (layer-while-held othermap1)
+            (layer-while-held othermap2)
+            (layer-while-held othermap3)
+         )
+         (deflayermap (othermap1)
+            a 5
+            ___ use-defsrc
+         )
+         (deflayermap (othermap2)
+            a 6
+            __ use-defsrc
+            _ x
+         )
+         (deflayermap (othermap3)
+            a 7
+            _ use-defsrc
+            __ x
+         )
+        ";
+    let result = simulate(CFG, "d:b d:a d:c d:e t:10").to_ascii();
+    assert_eq!("t:1ms dn:Kb5 t:1ms dn:C t:1ms dn:E", result);
+    let result = simulate(CFG, "d:c d:a d:c d:e t:10").to_ascii();
+    assert_eq!("t:1ms dn:Kb6 t:1ms dn:X t:1ms dn:E", result);
+    let result = simulate(CFG, "d:d d:a d:c d:e t:10").to_ascii();
+    assert_eq!("t:1ms dn:Kb7 t:1ms dn:C t:1ms dn:X", result);
+}
diff --git a/src/tests/sim_tests/vkey_sim_tests.rs b/src/tests/sim_tests/vkey_sim_tests.rs
new file mode 100644
index 000000000..56c46b800
--- /dev/null
+++ b/src/tests/sim_tests/vkey_sim_tests.rs
@@ -0,0 +1,243 @@
+use super::*;
+
+#[test]
+fn hold_for_duration() {
+    const CFG: &str = r"
+     (defsrc a b c)
+     (defvirtualkeys lmet lmet)
+     (defalias hm (hold-for-duration 50 lmet))
+     (deflayer base
+        (multi @hm (macro-repeat 40 @hm))
+        (multi 1 @hm)
+        (release-key lmet)
+     )
+    ";
+    let result = simulate(CFG, "d:a t:200 u:a t:60").to_ascii();
+    assert_eq!("t:1ms dn:LGui t:258ms up:LGui", result);
+    let result = simulate(CFG, "d:a u:a t:25 d:c u:c t:25").to_ascii();
+    assert_eq!("t:2ms dn:LGui t:23ms up:LGui", result);
+    let result = simulate(CFG, "d:a u:a t:25 d:b u:b t:25 d:b u:b t:60").to_ascii();
+    assert_eq!(
+        "t:2ms dn:LGui t:23ms dn:Kb1 t:1ms up:Kb1 t:24ms dn:Kb1 t:1ms up:Kb1 t:49ms up:LGui",
+        result
+    );
+}
+
+// =============================================================================
+// Virtual Key Simulator Input Tests
+// =============================================================================
+// These tests verify the simulator's ability to directly activate virtual keys
+// using the vk:name[:action] syntax in simulation input strings.
+
+/// Test vk:name with default press action
+#[test]
+fn vk_sim_default_press() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test (multi lctl lalt))
+        (deflayer base a)
+    ";
+    // vk:name without action should default to press
+    // Virtual key actions happen immediately (no preceding tick)
+    let result = simulate(CFG, "vk:vk_test t:10").to_ascii();
+    assert_eq!("dn:LCtrl dn:LAlt", result);
+}
+
+/// Test vk:name:press explicit action
+#[test]
+fn vk_sim_explicit_press() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    // Virtual key actions happen immediately (no preceding tick)
+    let result = simulate(CFG, "vk:vk_test:press t:10").to_ascii();
+    assert_eq!("dn:LGui", result);
+}
+
+/// Test vk:name:p shorthand for press
+#[test]
+fn vk_sim_press_shorthand() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "vk:vk_test:p t:10").to_ascii();
+    assert_eq!("dn:LGui", result);
+}
+
+/// Test vk:name:release action
+#[test]
+fn vk_sim_release() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    // Press first, then release after tick
+    let result = simulate(CFG, "vk:vk_test:press t:10 vk:vk_test:release t:10").to_ascii();
+    assert_eq!("dn:LGui t:10ms up:LGui", result);
+}
+
+/// Test vk:name:tap action (press + release)
+#[test]
+fn vk_sim_tap() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    // For tap, press happens immediately, then 1ms tick, then release
+    let result = simulate(CFG, "vk:vk_test:tap t:10").to_ascii();
+    assert_eq!("dn:LGui t:1ms up:LGui", result);
+}
+
+/// Test vk:name:t shorthand for tap
+#[test]
+fn vk_sim_tap_shorthand() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "vk:vk_test:t t:10").to_ascii();
+    assert_eq!("dn:LGui t:1ms up:LGui", result);
+}
+
+/// Test vk:name:toggle action
+#[test]
+fn vk_sim_toggle() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    // First toggle: press (key not active -> activate)
+    // Second toggle: release (key active -> deactivate)
+    let result = simulate(CFG, "vk:vk_test:toggle t:10 vk:vk_test:toggle t:10").to_ascii();
+    assert_eq!("dn:LGui t:10ms up:LGui", result);
+}
+
+/// Test vk:name:g shorthand for toggle
+#[test]
+fn vk_sim_toggle_shorthand() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "vk:vk_test:g t:10 vk:vk_test:g t:10").to_ascii();
+    assert_eq!("dn:LGui t:10ms up:LGui", result);
+}
+
+/// Test fakekey: prefix (alias for vk:)
+#[test]
+fn vk_sim_fakekey_prefix() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "fakekey:vk_test:tap t:10").to_ascii();
+    assert_eq!("dn:LGui t:1ms up:LGui", result);
+}
+
+/// Test virtualkey: prefix (alias for vk:)
+#[test]
+fn vk_sim_virtualkey_prefix() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "virtualkey:vk_test:tap t:10").to_ascii();
+    assert_eq!("dn:LGui t:1ms up:LGui", result);
+}
+
+/// Test 🎭 emoji prefix
+#[test]
+fn vk_sim_emoji_prefix() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys vk_test lmet)
+        (deflayer base a)
+    ";
+    let result = simulate(CFG, "🎭:vk_test:tap t:10").to_ascii();
+    assert_eq!("dn:LGui t:1ms up:LGui", result);
+}
+
+/// Test virtual key with layer switching
+#[test]
+fn vk_sim_layer_switch() {
+    const CFG: &str = r"
+        (defsrc a b)
+        (defvirtualkeys vk_layer (layer-switch other))
+        (deflayer base a b)
+        (deflayer other 1 2)
+    ";
+    // Activate the layer switch virtual key, then press 'a' which should output '1'
+    let result = simulate(CFG, "vk:vk_layer t:10 d:a u:a t:10").to_ascii();
+    assert_eq!("t:10ms dn:Kb1 t:1ms up:Kb1", result);
+}
+
+/// Test multiple virtual keys in sequence
+#[test]
+fn vk_sim_multiple_vkeys() {
+    const CFG: &str = r"
+        (defsrc a)
+        (defvirtualkeys
+            vk_ctrl lctl
+            vk_alt lalt
+        )
+        (deflayer base a)
+    ";
+    // Each vk action triggers a layout tick, so there's 1ms between each action
+    let result = simulate(
+        CFG,
+        "vk:vk_ctrl:press vk:vk_alt:press t:10 vk:vk_alt:release vk:vk_ctrl:release t:10",
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LCtrl t:1ms dn:LAlt t:9ms up:LAlt t:1ms up:LCtrl",
+        result
+    );
+}
+
+// =============================================================================
+// End Virtual Key Simulator Input Tests
+// =============================================================================
+
+/// Ignored because PRESSED_KEYS is a global static,
+/// so shares state with other tests and will fail at random.
+/// Should be run on its own until PRESSED_KEYS can be refactored
+/// to avoid being a global.
+///
+/// The "must_be_single_threaded" function naming is referenced
+/// in test runners, e.g. justfile and workflows.
+#[ignore]
+#[test]
+fn on_idle_must_be_single_threaded() {
+    const CFG: &str = r"
+     (defvirtualkeys lmet lmet)
+     (defalias i1 (on-idle 20 tap-vkey lmet)
+               i2 (on-physical-idle 20 tap-vkey lmet))
+     (defsrc a b c)
+     (deflayer base
+        (caps-word 100) @i1 @i2
+     )
+    ";
+    let result = simulate(
+        CFG,
+        "d:c t:10 u:c t:5 d:a t:50 u:a t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10",
+    )
+    .to_ascii();
+    assert_eq!("t:86ms dn:LGui t:1ms up:LGui", result);
+    let result = simulate(
+        CFG,
+        "d:b t:10 u:b t:5 d:a t:50 u:a t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10 t:10",
+    )
+    .to_ascii();
+    assert_eq!("t:137ms dn:LGui t:1ms up:LGui", result);
+}
diff --git a/src/tests/sim_tests/zippychord_sim_tests.rs b/src/tests/sim_tests/zippychord_sim_tests.rs
new file mode 100644
index 000000000..277273b03
--- /dev/null
+++ b/src/tests/sim_tests/zippychord_sim_tests.rs
@@ -0,0 +1,729 @@
+use super::*;
+
+static ZIPPY_CFG: &str = "(defsrc lalt)(deflayer base (caps-word 2000))(defzippy file)";
+static ZIPPY_FILE_CONTENT: &str = "
+dy	day
+dy 1	Monday
+ abc	Alphabet
+pr	pre ⌫
+pra	partner
+pr q	pull request
+r df	recipient
+ w  a	Washington
+xy	WxYz
+rq	request
+rqa	request␣assistance
+.g	git
+.g f p	git fetch -p
+12	hi
+1234	bye
+";
+
+fn simulate_with_zippy_file_content(cfg: &str, input: &str, content: &str) -> String {
+    let mut fcontent = FxHashMap::default();
+    fcontent.insert("file".into(), content.into());
+    simulate_with_file_content(cfg, input, fcontent)
+}
+
+#[test]
+fn sim_zippychord_capitalize() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:a t:10 d:b t:10 d:spc t:10 d:c u:a u:b u:c u:spc t:300 \
+         d:a t:10 d:b t:10 d:spc t:10 d:c t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:A t:10ms dn:B t:10ms dn:Space t:10ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift up:A dn:A up:LShift \
+         dn:L up:L dn:P up:P dn:H up:H up:A dn:A up:B dn:B dn:E up:E dn:T up:T \
+         t:1ms up:A t:1ms up:B t:1ms up:C t:1ms up:Space t:296ms \
+         dn:A t:10ms dn:B t:10ms dn:Space t:10ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift up:A dn:A up:LShift \
+         dn:L up:L dn:P up:P dn:H up:H up:A dn:A up:B dn:B dn:E up:E dn:T up:T",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_followup_with_prev() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:d t:10 d:y t:10 u:d u:y t:10 d:1 t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:10ms dn:BSpace up:BSpace \
+         up:D dn:D dn:A up:A up:Y dn:Y \
+         t:10ms up:D t:1ms up:Y t:9ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift dn:M up:M up:LShift dn:O up:O dn:N up:N dn:D up:D dn:A up:A dn:Y up:Y",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_followup_no_prev() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:r t:10 u:r t:10 d:d d:f t:10 t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:R t:10ms up:R t:10ms dn:D t:1ms \
+        dn:BSpace up:BSpace dn:BSpace up:BSpace \
+        dn:R up:R dn:E up:E dn:C up:C dn:I up:I dn:P up:P dn:I up:I dn:E up:E dn:N up:N dn:T up:T",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_washington() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:w d:spc t:10
+         u:w u:spc t:10
+         d:a d:spc t:10
+         u:a u:spc t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:W t:1ms dn:Space t:9ms up:W t:1ms up:Space t:9ms \
+         dn:A t:1ms dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift dn:W up:W up:LShift \
+         up:A dn:A dn:S up:S dn:H up:H dn:I up:I dn:N up:N dn:G up:G dn:T up:T dn:O up:O dn:N up:N \
+         t:9ms up:A t:1ms up:Space",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_overlap() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:r t:10  d:q t:10 d:a t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:R t:10ms dn:BSpace up:BSpace \
+        up:R dn:R dn:E up:E up:Q dn:Q dn:U up:U dn:E up:E dn:S up:S dn:T up:T t:10ms \
+        dn:Space up:Space \
+        up:A dn:A dn:S up:S dn:S up:S dn:I up:I dn:S up:S dn:T up:T up:A dn:A dn:N up:N dn:C up:C dn:E up:E",
+        result
+    );
+    let result =
+        simulate_with_zippy_file_content(ZIPPY_CFG, "d:1 d:2 d:3 d:4 t:20", ZIPPY_FILE_CONTENT)
+            .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace dn:H up:H dn:I up:I t:1ms dn:Kb3 t:1ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:B up:B dn:Y up:Y dn:E up:E",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_lsft() {
+    // test lsft behaviour while pressed
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lsft t:10 d:d t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:D t:10ms dn:BSpace up:BSpace up:D dn:D up:LShift dn:A up:A up:Y dn:Y dn:LShift",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lsft t:10 d:x t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:X t:10ms dn:BSpace up:BSpace \
+         dn:W up:W up:LShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z dn:LShift",
+        result
+    );
+
+    // ensure lsft-held behaviour goes away when released
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lsft t:10 d:d u:lsft t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:D t:1ms up:LShift t:9ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lsft t:10 d:x u:lsft t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:LShift t:10ms dn:X t:1ms up:LShift t:9ms dn:BSpace up:BSpace \
+         dn:LShift dn:W up:W up:LShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_rsft() {
+    // test rsft behaviour while pressed
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:rsft t:10 d:d t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RShift t:10ms dn:D t:10ms dn:BSpace up:BSpace up:D dn:D up:RShift dn:A up:A up:Y dn:Y dn:RShift",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:rsft t:10 d:x t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RShift t:10ms dn:X t:10ms dn:BSpace up:BSpace \
+         dn:W up:W up:RShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z dn:RShift",
+        result
+    );
+
+    // ensure rsft-held behaviour goes away when released
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:rsft t:10 d:d u:rsft t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RShift t:10ms dn:D t:1ms up:RShift t:9ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:rsft t:10 d:x u:rsft t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RShift t:10ms dn:X t:1ms up:RShift t:9ms dn:BSpace up:BSpace \
+         dn:LShift dn:W up:W up:LShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_ralt() {
+    // test ralt behaviour while pressed
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:ralt t:10 d:d t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RAlt t:10ms dn:D t:10ms dn:BSpace up:BSpace up:RAlt up:D dn:D dn:A up:A up:Y dn:Y dn:RAlt",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:ralt t:10 d:x t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RAlt t:10ms dn:X t:10ms dn:BSpace up:BSpace \
+         up:RAlt dn:LShift dn:W up:W up:LShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z dn:RAlt",
+        result
+    );
+
+    // ensure rsft-held behaviour goes away when released
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:ralt t:10 d:d u:ralt t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RAlt t:10ms dn:D t:1ms up:RAlt t:9ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:ralt t:10 d:x u:ralt t:10 d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:RAlt t:10ms dn:X t:1ms up:RAlt t:9ms dn:BSpace up:BSpace \
+         dn:LShift dn:W up:W up:LShift up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_caps_word() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lalt u:lalt t:10 d:d t:10 d:y t:10 u:d u:y t:10 d:spc u:spc t:2000 d:d d:y t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:10ms dn:LShift dn:D t:10ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y \
+         t:10ms up:D t:1ms up:LShift up:Y t:9ms dn:Space t:1ms up:Space \
+         t:1999ms dn:D t:1ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:lalt t:10 d:y t:10 d:x t:10 u:x u:y t:10 d:spc u:spc t:1000 d:y d:x t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "t:10ms dn:LShift dn:Y t:10ms dn:BSpace up:BSpace \
+         dn:W up:W up:X dn:X up:Y dn:Y dn:Z up:Z \
+         t:10ms up:X t:1ms up:LShift up:Y t:9ms dn:Space t:1ms up:Space \
+         t:999ms dn:Y t:1ms dn:BSpace up:BSpace dn:LShift dn:W up:W up:LShift \
+         up:X dn:X dn:LShift up:Y dn:Y up:LShift dn:Z up:Z",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_triple_combo() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:. d:g t:10 u:. u:g d:f t:10 u:f d:p t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Dot t:1ms dn:BSpace up:BSpace up:G dn:G dn:I up:I dn:T up:T t:9ms up:Dot t:1ms up:G \
+         t:1ms dn:F t:8ms up:F t:1ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:G up:G dn:I up:I dn:T up:T dn:Space up:Space \
+         dn:F up:F dn:E up:E dn:T up:T dn:C up:C dn:H up:H dn:Space up:Space \
+         dn:Minus up:Minus up:P dn:P",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_disabled_by_typing() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:v u:v t:10 d:d d:y t:100",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!("dn:V t:1ms up:V t:9ms dn:D t:1ms dn:Y", result);
+}
+
+#[test]
+fn sim_zippychord_prefix() {
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:p d:r u:p u:r t:10 d:q u:q t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:P t:1ms dn:BSpace up:BSpace up:P dn:P up:R dn:R dn:E up:E dn:Space up:Space \
+         dn:BSpace up:BSpace t:1ms up:P t:1ms up:R t:7ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:U up:U dn:L up:L dn:L up:L dn:Space up:Space \
+         dn:R up:R dn:E up:E up:Q dn:Q dn:U up:U dn:E up:E dn:S up:S dn:T up:T t:1ms up:Q",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        ZIPPY_CFG,
+        "d:p d:r d:a t:10 u:d u:r u:a",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii()
+    .no_time()
+    .no_releases();
+    assert_eq!(
+        "dn:P dn:BSpace \
+         dn:P dn:R dn:E dn:Space dn:BSpace \
+         dn:BSpace dn:BSpace dn:A dn:R dn:T dn:N dn:E dn:R",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_smartspace_full() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space full)",
+        "d:d d:y t:10 u:d u:y t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:1ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y dn:Space up:Space \
+         t:9ms up:D t:1ms up:Y t:99ms dn:BSpace up:BSpace dn:Dot t:10ms up:Dot",
+        result
+    );
+
+    // Test that prefix works as intended.
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space add-space-only)",
+        "d:p d:r t:10 u:p u:r t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:P t:1ms dn:BSpace up:BSpace up:P dn:P up:R dn:R dn:E up:E \
+         dn:Space up:Space dn:BSpace up:BSpace \
+         t:9ms up:P t:1ms up:R t:99ms dn:Dot t:10ms up:Dot",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_smartspace_spaceonly() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space add-space-only)",
+        "d:d d:y t:10 u:d u:y t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:1ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y dn:Space up:Space \
+         t:9ms up:D t:1ms up:Y t:99ms dn:Dot t:10ms up:Dot",
+        result
+    );
+
+    // Test that prefix works as intended.
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space add-space-only)",
+        "d:p d:r t:10 u:p u:r t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:P t:1ms dn:BSpace up:BSpace up:P dn:P up:R dn:R dn:E up:E \
+         dn:Space up:Space dn:BSpace up:BSpace \
+         t:9ms up:P t:1ms up:R t:99ms dn:Dot t:10ms up:Dot",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_smartspace_none() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space none)",
+        "d:d d:y t:10 u:d u:y t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:1ms dn:BSpace up:BSpace up:D dn:D dn:A up:A up:Y dn:Y \
+         t:9ms up:D t:1ms up:Y t:99ms dn:Dot t:10ms up:Dot",
+        result
+    );
+
+    // Test that prefix works as intended.
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space add-space-only)",
+        "d:p d:r t:10 u:p u:r t:100 d:. t:10 u:. t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:P t:1ms dn:BSpace up:BSpace up:P dn:P up:R dn:R dn:E up:E \
+         dn:Space up:Space dn:BSpace up:BSpace \
+         t:9ms up:P t:1ms up:R t:99ms dn:Dot t:10ms up:Dot",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_smartspace_overlap() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space full)",
+        "d:r t:10 d:q t:10 d:a t:10",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:R t:10ms dn:BSpace up:BSpace \
+        up:R dn:R dn:E up:E up:Q dn:Q dn:U up:U dn:E up:E dn:S up:S dn:T up:T dn:Space up:Space t:10ms \
+        dn:BSpace up:BSpace dn:Space up:Space \
+        up:A dn:A dn:S up:S dn:S up:S dn:I up:I dn:S up:S dn:T up:T up:A dn:A dn:N up:N dn:C up:C dn:E up:E \
+        dn:Space up:Space",
+        result
+    );
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space full)",
+        "d:1 d:2 d:3 d:4 t:20",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace dn:H up:H dn:I up:I dn:Space up:Space \
+         t:1ms dn:Kb3 t:1ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:B up:B dn:Y up:Y dn:E up:E dn:Space up:Space",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_smartspace_followup() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space full)",
+        "d:d t:10 d:y t:10 u:d u:y t:10 d:1 t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:10ms dn:BSpace up:BSpace \
+         up:D dn:D dn:A up:A up:Y dn:Y dn:Space up:Space \
+         t:10ms up:D t:1ms up:Y t:9ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift dn:M up:M up:LShift dn:O up:O dn:N up:N dn:D up:D dn:A up:A dn:Y up:Y dn:Space up:Space",
+        result
+    );
+}
+
+const CUSTOM_PUNC_CFG: &str = "\
+(defsrc)
+(deflayer base)
+(defzippy file
+ smart-space full
+ smart-space-punctuation (z ! ® *)
+ output-character-mappings (
+   ® AG-r
+   * S-AG-v
+   ! S-1))";
+
+#[test]
+fn sim_zippychord_smartspace_custom_punc() {
+    // 1 without lsft: no smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:d t:10 d:y t:10 u:d u:y t:10 d:1 t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:D t:10ms dn:BSpace up:BSpace \
+         up:D dn:D dn:A up:A up:Y dn:Y dn:Space up:Space \
+         t:10ms up:D t:1ms up:Y t:9ms \
+         dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace dn:BSpace up:BSpace \
+         dn:LShift dn:M up:M up:LShift dn:O up:O dn:N up:N dn:D up:D dn:A up:A dn:Y up:Y dn:Space up:Space",
+        result
+    );
+
+    // S-1 = !: smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:1 d:2 t:10 u:1 u:2 t:10 d:lsft d:1 u:1 u:lsft t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace \
+         dn:H up:H dn:I up:I dn:Space up:Space t:9ms \
+         up:Kb1 t:1ms up:Kb2 t:9ms \
+         dn:LShift t:1ms dn:BSpace up:BSpace dn:Kb1 t:1ms up:Kb1 t:1ms up:LShift",
+        result
+    );
+
+    // z: smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:1 d:2 t:10 u:1 u:2 t:10 d:z u:z t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace \
+         dn:H up:H dn:I up:I dn:Space up:Space t:9ms \
+         up:Kb1 t:1ms up:Kb2 t:9ms \
+         dn:BSpace up:BSpace dn:Z t:1ms up:Z",
+        result
+    );
+
+    // r no altgr: no smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:1 d:2 t:10 u:1 u:2 t:10 d:r u:r t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace \
+         dn:H up:H dn:I up:I dn:Space up:Space t:9ms \
+         up:Kb1 t:1ms up:Kb2 t:9ms \
+         dn:R t:1ms up:R",
+        result
+    );
+
+    // r with altgr: smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:1 d:2 t:10 u:1 u:2 t:10 d:ralt d:r u:r u:ralt t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace \
+         dn:H up:H dn:I up:I dn:Space up:Space t:9ms \
+         up:Kb1 t:1ms up:Kb2 t:9ms \
+         dn:RAlt t:1ms dn:BSpace up:BSpace dn:R t:1ms up:R t:1ms up:RAlt",
+        result
+    );
+
+    // v with altgr+lsft: smart-space-erase
+    let result = simulate_with_zippy_file_content(
+        CUSTOM_PUNC_CFG,
+        "d:1 d:2 t:10 u:1 u:2 t:10 d:ralt d:lsft d:v u:v u:ralt u:lsft t:300",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:Kb1 t:1ms dn:BSpace up:BSpace \
+         dn:H up:H dn:I up:I dn:Space up:Space t:9ms \
+         up:Kb1 t:1ms up:Kb2 t:9ms \
+         dn:RAlt t:1ms dn:LShift t:1ms dn:BSpace up:BSpace dn:V t:1ms up:V t:1ms up:RAlt t:1ms up:LShift",
+        result
+    );
+}
+
+#[test]
+fn sim_zippychord_non_followup_subsequent_with_potential_followups_available() {
+    let result = simulate_with_zippy_file_content(
+        "(defsrc)(deflayer base)(defzippy file
+         smart-space full)",
+        "d:g d:. t:10 u:g u:. t:1000 d:g d:. t:10 u:g u:. t:1000",
+        ZIPPY_FILE_CONTENT,
+    )
+    .to_ascii();
+    assert_eq!(
+        "dn:G t:1ms dn:BSpace up:BSpace up:G dn:G dn:I up:I dn:T up:T dn:Space up:Space t:9ms \
+         up:G t:1ms up:Dot t:999ms \
+         dn:G t:1ms dn:BSpace up:BSpace up:G dn:G dn:I up:I dn:T up:T dn:Space up:Space t:9ms \
+         up:G t:1ms up:Dot",
+        result
+    );
+}
+
+const DEAD_KEYS_CFG: &str = "\
+(defsrc)
+(deflayer base)
+(defzippy file
+ smart-space full
+ output-character-mappings (
+   ’ (no-erase ')
+   ‘ (no-erase `)
+   é (single-output ' e)
+   è (single-output ` e)
+ ))";
+static DEAD_KEYS_FILE_CONTENT: &str = "
+by	h’elo
+bye	by‘e
+by d	ft‘a’ng
+by d a	aye
+cy	hélo
+cye	byè
+cy d	ftéèng
+cy d a	aye
+";
+
+#[test]
+fn sim_zippychord_noerase() {
+    let result = simulate_with_zippy_file_content(
+        DEAD_KEYS_CFG,
+        "d:b d:y t:100 d:e u:b u:y u:e t:1000",
+        DEAD_KEYS_FILE_CONTENT,
+    )
+    .no_releases()
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:B dn:BSpace dn:H dn:Quote dn:E dn:L dn:O dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:B dn:Y dn:Grave dn:E dn:Space",
+        result,
+    );
+
+    let result = simulate_with_zippy_file_content(
+        DEAD_KEYS_CFG,
+        "d:b d:y t:100 u:b u:y d:d t:10 u:d d:a t:10 u:a t:1000",
+        DEAD_KEYS_FILE_CONTENT,
+    )
+    .no_releases()
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:B dn:BSpace dn:H dn:Quote dn:E dn:L dn:O dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:F dn:T dn:Grave dn:A dn:Quote dn:N dn:G dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:A dn:Y dn:E dn:Space",
+        result,
+    );
+}
+
+#[test]
+fn sim_zippychord_single_output() {
+    let result = simulate_with_zippy_file_content(
+        DEAD_KEYS_CFG,
+        "d:c d:y t:100 d:e u:c u:y u:e t:1000",
+        DEAD_KEYS_FILE_CONTENT,
+    )
+    .no_releases()
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:C dn:BSpace dn:H dn:Quote dn:E dn:L dn:O dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:B dn:Y dn:Grave dn:E dn:Space",
+        result,
+    );
+
+    let result = simulate_with_zippy_file_content(
+        DEAD_KEYS_CFG,
+        "d:c d:y t:100 u:c u:y d:d t:10 u:d d:a t:10 u:a t:1000",
+        DEAD_KEYS_FILE_CONTENT,
+    )
+    .no_releases()
+    .no_time()
+    .to_ascii();
+    assert_eq!(
+        "dn:C dn:BSpace dn:H dn:Quote dn:E dn:L dn:O dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:F dn:T dn:Quote dn:E dn:Grave dn:E dn:N dn:G dn:Space \
+         dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace dn:BSpace \
+         dn:A dn:Y dn:E dn:Space",
+        result,
+    );
+}
diff --git a/tcp_protocol/Cargo.toml b/tcp_protocol/Cargo.toml
new file mode 100644
index 000000000..69cd3663f
--- /dev/null
+++ b/tcp_protocol/Cargo.toml
@@ -0,0 +1,11 @@
+[package]
+name = "kanata-tcp-protocol"
+version = "0.1120.1"
+edition = "2021"
+description = "TCP protocol for kanata. This does not follow semver."
+license = "LGPL-3.0-only"
+
+[dependencies]
+serde = { version = "1", features = ["alloc", "derive"], default-features = false }
+serde_derive = "1.0"
+serde_json = { version = "1", features = ["alloc"], default-features = false }
diff --git a/tcp_protocol/src/lib.rs b/tcp_protocol/src/lib.rs
new file mode 100644
index 000000000..0fbed0478
--- /dev/null
+++ b/tcp_protocol/src/lib.rs
@@ -0,0 +1,283 @@
+//! Kanata TCP Protocol
+//!
+//! This crate defines the JSON message format for communication between
+//! TCP clients and the Kanata keyboard remapping daemon.
+
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+
+/// Messages sent from the server to connected clients.
+#[derive(Debug, Serialize, Deserialize)]
+pub enum ServerMessage {
+    LayerChange {
+        new: String,
+    },
+    LayerNames {
+        names: Vec<String>,
+    },
+    FakeKeyNames {
+        names: Vec<String>,
+    },
+    CurrentLayerInfo {
+        name: String,
+        cfg_text: String,
+    },
+    ConfigFileReload {
+        new: String,
+    },
+    CurrentLayerName {
+        name: String,
+    },
+    MessagePush {
+        message: serde_json::Value,
+    },
+    Error {
+        msg: String,
+    },
+    /// Response to `Hello` command with server capabilities.
+    /// Introduced in protocol v1.11.
+    HelloOk {
+        version: String,
+        protocol: u8,
+        capabilities: Vec<String>,
+    },
+    /// Response to Reload commands when `wait: true` was specified.
+    /// Introduced in protocol v1.11.
+    ReloadResult {
+        ok: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+    /// Sent when a tap-hold key transitions to hold state.
+    /// The `key` field is the physical key name (e.g., `"caps"`, `"a"`).
+    HoldActivated {
+        key: String,
+    },
+    /// Sent when a tap-hold key triggers its tap action.
+    /// The `key` field is the physical key name (e.g., `"caps"`, `"a"`).
+    TapActivated {
+        key: String,
+    },
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "status")]
+pub enum ServerResponse {
+    Ok,
+    Error { msg: String },
+}
+
+impl ServerResponse {
+    pub fn as_bytes(&self) -> Vec<u8> {
+        let mut msg = serde_json::to_vec(self).expect("ServerResponse should serialize");
+        msg.push(b'\n');
+        msg
+    }
+}
+
+impl ServerMessage {
+    pub fn as_bytes(&self) -> Vec<u8> {
+        let mut msg = serde_json::to_vec(self).expect("ServerMessage should serialize");
+        msg.push(b'\n');
+        msg
+    }
+}
+
+/// Messages sent from clients to the server.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ClientMessage {
+    ChangeLayer {
+        new: String,
+    },
+    RequestLayerNames {},
+    RequestFakeKeyNames {},
+    RequestCurrentLayerInfo {},
+    RequestCurrentLayerName {},
+    ActOnFakeKey {
+        name: String,
+        action: FakeKeyActionMessage,
+    },
+    SetMouse {
+        x: u16,
+        y: u16,
+    },
+
+    /// Reload the current configuration file.
+    Reload {
+        /// If true, block until reload completes or times out.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        wait: Option<bool>,
+        /// Maximum time to wait for reload (milliseconds). Default: 5000.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+    ReloadNext {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        wait: Option<bool>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+    ReloadPrev {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        wait: Option<bool>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+    ReloadNum {
+        index: usize,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        wait: Option<bool>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+    ReloadFile {
+        path: String,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        wait: Option<bool>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+
+    /// Request server capabilities and version.
+    /// Introduced in protocol v1.11.
+    Hello {},
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
+pub enum FakeKeyActionMessage {
+    Press,
+    Release,
+    Tap,
+    Toggle,
+}
+
+impl FromStr for ClientMessage {
+    type Err = serde_json::Error;
+
+    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
+        serde_json::from_str(s)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_server_response_json_format() {
+        assert_eq!(
+            serde_json::to_string(&ServerResponse::Ok).unwrap(),
+            r#"{"status":"Ok"}"#
+        );
+    }
+
+    #[test]
+    fn test_as_bytes_includes_newline() {
+        let response = ServerResponse::Ok;
+        assert!(response.as_bytes().ends_with(b"\n"));
+    }
+
+    #[test]
+    fn test_hello_ok_json_format() {
+        let msg = ServerMessage::HelloOk {
+            version: "1.10.0".to_string(),
+            protocol: 1,
+            capabilities: vec!["reload".to_string()],
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert!(json.contains("HelloOk"));
+        assert!(json.contains("\"version\":\"1.10.0\""));
+    }
+
+    #[test]
+    fn test_reload_with_wait() {
+        let msg = ClientMessage::Reload {
+            wait: Some(true),
+            timeout_ms: Some(5000),
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert!(json.contains("wait\":true"));
+        assert!(json.contains("timeout_ms\":5000"));
+    }
+
+    #[test]
+    fn test_reload_minimal() {
+        // Backward compatible: no optional fields
+        let json = r#"{"Reload":{}}"#;
+        let msg: ClientMessage = serde_json::from_str(json).unwrap();
+        match msg {
+            ClientMessage::Reload { wait, timeout_ms } => {
+                assert!(wait.is_none());
+                assert!(timeout_ms.is_none());
+            }
+            _ => panic!("Expected Reload"),
+        }
+    }
+
+    #[test]
+    fn test_existing_commands_unchanged() {
+        // Verify existing commands still parse without any new fields
+        let json = r#"{"ChangeLayer":{"new":"nav"}}"#;
+        let msg: ClientMessage = serde_json::from_str(json).unwrap();
+        assert!(matches!(msg, ClientMessage::ChangeLayer { new } if new == "nav"));
+
+        let json = r#"{"RequestLayerNames":{}}"#;
+        let _msg: ClientMessage = serde_json::from_str(json).unwrap();
+
+        let json = r#"{"ActOnFakeKey":{"name":"test","action":"Tap"}}"#;
+        let _msg: ClientMessage = serde_json::from_str(json).unwrap();
+    }
+
+    #[test]
+    fn test_request_fake_key_names() {
+        let json = r#"{"RequestFakeKeyNames":{}}"#;
+        let msg: ClientMessage = serde_json::from_str(json).unwrap();
+        assert!(matches!(msg, ClientMessage::RequestFakeKeyNames {}));
+    }
+
+    #[test]
+    fn test_fake_key_names_response() {
+        let msg = ServerMessage::FakeKeyNames {
+            names: vec!["email-sig".to_string(), "nav-mode".to_string()],
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert_eq!(
+            json,
+            r#"{"FakeKeyNames":{"names":["email-sig","nav-mode"]}}"#
+        );
+
+        // Round-trip
+        let parsed: ServerMessage = serde_json::from_str(&json).unwrap();
+        match parsed {
+            ServerMessage::FakeKeyNames { names } => {
+                assert_eq!(names, vec!["email-sig", "nav-mode"]);
+            }
+            _ => panic!("Expected FakeKeyNames"),
+        }
+    }
+
+    #[test]
+    fn test_fake_key_names_empty() {
+        let msg = ServerMessage::FakeKeyNames { names: vec![] };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert_eq!(json, r#"{"FakeKeyNames":{"names":[]}}"#);
+    }
+
+    #[test]
+    fn test_hold_activated_json_format() {
+        let msg = ServerMessage::HoldActivated {
+            key: "caps".to_string(),
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert_eq!(json, r#"{"HoldActivated":{"key":"caps"}}"#);
+    }
+
+    #[test]
+    fn test_tap_activated_json_format() {
+        let msg = ServerMessage::TapActivated {
+            key: "a".to_string(),
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        assert_eq!(json, r#"{"TapActivated":{"key":"a"}}"#);
+    }
+}
diff --git a/wasm/.gitignore b/wasm/.gitignore
new file mode 100644
index 000000000..56fea6170
--- /dev/null
+++ b/wasm/.gitignore
@@ -0,0 +1,5 @@
+# wasm-pack output
+pkg/
+
+# do not commit lockfile; not important for wasm project
+Cargo.lock
diff --git a/wasm/Cargo.toml b/wasm/Cargo.toml
new file mode 100644
index 000000000..32bfde32d
--- /dev/null
+++ b/wasm/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "kanata-wasm"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = [ "cdylib", "rlib" ]
+
+[dependencies]
+wasm-bindgen = "0.2.100"
+kanata = { path = ".." , default-features = false, features = [ "simulated_output", "zippychord" ] }
+anyhow = "1.0.81"
+log = "0.4.21"
+console_error_panic_hook = "0.1.7"
+rustc-hash = "1.1.0"
diff --git a/wasm/README.md b/wasm/README.md
new file mode 100644
index 000000000..d1621cc01
--- /dev/null
+++ b/wasm/README.md
@@ -0,0 +1,31 @@
+# Kanata WASM
+
+Code to expose kanata functionality over WASM.
+
+Prerequisites:
+
+- Install the wasm32-unknown-unknown rustc target
+- Install wasm-bindgen: `cargo install wasm-bindgen-cli`
+- Install wasm-opt: `cargo install wasm-opt`
+
+You can run the command below to generate files for use in the browser:
+
+```
+wasm-pack build --target web
+```
+
+- Either install `just` and run `just wasm-build <output_directory>
+  or execute the commands for the recipe (see `justfile` in the repository).
+
+This will output files into `pkg/` which can be used for a website.
+This has yet not been tested with targets other than web (e.g. node).
+
+An example project using this code is the
+[online kanata simulator](https://github.com/jtroo/jtroo.github.io).
+
+The simulator files can be served by any webserver,
+such as the default Python webserver:
+
+```
+python -m http.server <tcp_port>
+```
diff --git a/wasm/src/lib.rs b/wasm/src/lib.rs
new file mode 100644
index 000000000..06d026c77
--- /dev/null
+++ b/wasm/src/lib.rs
@@ -0,0 +1,369 @@
+use anyhow::{Result, anyhow, bail};
+use kanata_state_machine::{kanata::handle_fakekey_action, oskbd::*, *};
+use rustc_hash::FxHashMap;
+use wasm_bindgen::prelude::*;
+
+use std::sync::Once;
+
+static INIT: Once = Once::new();
+
+#[wasm_bindgen]
+pub fn init() {
+    INIT.call_once(|| {
+        std::panic::set_hook(Box::new(console_error_panic_hook::hook));
+    });
+}
+
+#[wasm_bindgen]
+pub fn check_config(cfg: &str) -> JsValue {
+    let (cfg, files) = split_cfg_and_sim_files(cfg);
+    let res = Kanata::new_from_str(&cfg, files);
+    JsValue::from_str(&match res {
+        Ok(_) => "Config is good!".to_owned(),
+        Err(e) => format!("{e:?}"),
+    })
+}
+
+#[wasm_bindgen]
+pub fn simulate(cfg: &str, sim: &str) -> JsValue {
+    JsValue::from_str(&match simulate_impl(cfg, sim) {
+        Ok(s) => s,
+        Err(e) => format!("Config or simulation input has error.\n\n{e:?}"),
+    })
+}
+
+fn split_cfg_and_sim_files(original_cfg: &str) -> (String, FxHashMap<String, String>) {
+    let mut cfg = String::new();
+    let mut file_name = None;
+    let mut file = String::new();
+    let mut sim_files = Default::default();
+
+    let mut original_lines = original_cfg.lines();
+    const FILE_PREFIX: &str = "=== file:";
+
+    // Parse main configuration.
+    // Must not consume whole iterator here.
+    #[allow(clippy::while_let_on_iterator)]
+    while let Some(line) = original_lines.next() {
+        if line.starts_with(FILE_PREFIX) {
+            file_name = line.strip_prefix(FILE_PREFIX);
+            break;
+        }
+        cfg.push_str(line);
+        cfg.push('\n');
+    }
+    if file_name.is_none() {
+        return (cfg, sim_files);
+    }
+
+    // Parse simulated sim_files.
+    for line in original_lines {
+        if line.starts_with(FILE_PREFIX) {
+            sim_files.insert(file_name.unwrap().to_string(), file.clone());
+            file_name = line.strip_prefix(FILE_PREFIX);
+            file.clear();
+            continue;
+        }
+        file.push_str(line);
+        file.push('\n');
+    }
+    // Save the last file
+    sim_files.insert(file_name.unwrap().to_string(), file.clone());
+    (cfg, sim_files)
+}
+
+fn parse_fakekey_spec(spec: &str) -> Result<(&str, FakeKeyAction)> {
+    let (name, action) = match spec.split_once(':') {
+        Some((name, action_str)) => {
+            let action = match action_str {
+                "press" | "p" => FakeKeyAction::Press,
+                "release" => FakeKeyAction::Release,
+                "tap" | "t" => FakeKeyAction::Tap,
+                "toggle" | "g" => FakeKeyAction::Toggle,
+                _ => bail!(
+                    "unknown fakekey action: {action_str}. Expected: press, release, tap, or toggle"
+                ),
+            };
+            (name, action)
+        }
+        None => (spec, FakeKeyAction::Press),
+    };
+    if name.is_empty() {
+        bail!("fakekey name cannot be empty");
+    }
+    Ok((name, action))
+}
+
+fn apply_fakekey_action(k: &mut Kanata, name: &str, action: FakeKeyAction) -> Result<()> {
+    let index = k
+        .virtual_keys
+        .get(name)
+        .ok_or_else(|| anyhow!("unknown virtual key: {name}"))?;
+    handle_fakekey_action(action, k.layout.bm(), FAKE_KEY_ROW, *index as u16);
+    Ok(())
+}
+
+fn simulate_impl(cfg: &str, sim: &str) -> Result<String> {
+    let (cfg, files) = split_cfg_and_sim_files(cfg);
+    let mut k = Kanata::new_from_str(&cfg, files)?;
+    let mut accumulated_ticks = 0;
+    let mut count_of_headers = 0;
+    for l in sim.lines() {
+        // Parse header lines like:
+        //
+        // --- this section does a one-shot and expects X
+        // --- this section holds and expects Y
+        //
+        // then add the lines to the simulation output directly.
+        if l.starts_with("---") {
+            if count_of_headers >= 1 {
+                // Push an empty string as an empty line in final output,
+                // for visual separation/clarity of header sections.
+                k.kbd_out.outputs.events.push("".into());
+            }
+            count_of_headers += 1;
+            k.kbd_out.outputs.events.push(l.into());
+            continue;
+        }
+
+        for pair in l.split_whitespace() {
+            match pair.split_once(':') {
+                Some((kind, val)) => match kind {
+                    "tick" | "🕐" | "t" => {
+                        let ticks = str::parse::<u128>(val).map_err(|e| {
+                            anyhow!("line: {l}\ninvalid number in {kind}:{val}\n{e}")
+                        })?;
+                        if ticks > 60000 {
+                            bail!("line: {l}\nmax tick is 60000: {kind}:{val}")
+                        }
+                        for _ in 0..ticks {
+                            if !k.can_block_update_idle_waiting(1) {
+                                k.tick_ms(1, &None)?;
+                            } else {
+                                k.kbd_out.tick();
+                            }
+                        }
+                        accumulated_ticks += ticks;
+                        if accumulated_ticks > 3600000 {
+                            bail!(
+                                "You are trying to simulate over an hour's worth of time.\nAborting to avoid wasting your CPU cycles."
+                            )
+                        }
+                    }
+                    "press" | "↓" | "d" | "down" => {
+                        let key_code = str_to_oscode(val)
+                            .ok_or_else(|| anyhow!("line: {l}\nunknown key in {kind}:{val}"))?;
+                        k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Press))?;
+                    }
+                    "release" | "↑" | "u" | "up" => {
+                        let key_code = str_to_oscode(val)
+                            .ok_or_else(|| anyhow!("line: {l}\nunknown key in {kind}:{val}"))?;
+                        k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Release))?;
+                    }
+                    "repeat" | "⟳" | "r" => {
+                        let key_code = str_to_oscode(val)
+                            .ok_or_else(|| anyhow!("line: {l}\nunknown key in {kind}:{val}"))?;
+                        k.handle_input_event(&KeyEvent::new(key_code, KeyValue::Repeat))?;
+                    }
+                    // Virtual/fake key activation: vk:name[:action]
+                    "vk" | "fakekey" | "virtualkey" | "🎭" => {
+                        let (vk_name, action) = parse_fakekey_spec(val)?;
+                        apply_fakekey_action(&mut k, vk_name, action)?;
+                    }
+                    // Layer switch: ls:layer_name
+                    "ls" | "layer-switch" | "🔀" => {
+                        let layer_idx = k
+                            .layer_info
+                            .iter()
+                            .position(|l| l.name == val)
+                            .ok_or_else(|| anyhow!("line: {l}\nunknown layer: {val}"))?;
+                        k.layout.bm().set_default_layer(layer_idx);
+                    }
+                    _ => bail!(
+                        "line: {l}\ninvalid action: {kind}\nvalid actions:\nu | up\nd | down\nt | tick\nvk | fakekey\nls | layer-switch"
+                    ),
+                },
+                None => bail!("line: {l}\ninvalid item: {pair}\nexpected format: action:item"),
+            }
+        }
+    }
+    Ok(k.kbd_out
+        .outputs
+        .events
+        .join("\n")
+        .replace('↓', "↓(press)   ")
+        .replace('↑', "↑(release) "))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sim(cfg: &str, sim: &str) -> String {
+        simulate_impl(cfg, sim).expect("simulation should succeed")
+    }
+
+    fn sim_err(cfg: &str, sim: &str) -> String {
+        simulate_impl(cfg, sim)
+            .expect_err("simulation should fail")
+            .to_string()
+    }
+
+    #[test]
+    fn basic_key_press_release() {
+        let result = sim("(defsrc a)(deflayer base b)", "d:a t:10 u:a t:1");
+        assert!(result.contains("↓(press)   B"));
+        assert!(result.contains("↑(release) B"));
+    }
+
+    #[test]
+    fn tick_syntax_variants() {
+        let result = sim(
+            "(defsrc a)(deflayer base b)",
+            "d:a t:5 u:a tick:5 d:a 🕐:5 u:a t:1",
+        );
+        assert!(result.contains("t:5ms"));
+    }
+
+    #[test]
+    fn press_syntax_variants() {
+        let result = sim(
+            "(defsrc a b c d)(deflayer base 1 2 3 4)",
+            "press:a t:1 u:a t:1 down:b t:1 u:b t:1 ↓:c t:1 u:c t:1 d:d t:1 u:d t:1",
+        );
+        assert!(result.contains("↓(press)   Kb1"));
+        assert!(result.contains("↓(press)   Kb2"));
+        assert!(result.contains("↓(press)   Kb3"));
+        assert!(result.contains("↓(press)   Kb4"));
+    }
+
+    #[test]
+    fn release_syntax_variants() {
+        let result = sim(
+            "(defsrc a b c d)(deflayer base 1 2 3 4)",
+            "d:a t:1 release:a t:1 d:b t:1 up:b t:1 d:c t:1 ↑:c t:1 d:d t:1 u:d t:1",
+        );
+        assert!(result.contains("↑(release) Kb1"));
+        assert!(result.contains("↑(release) Kb2"));
+        assert!(result.contains("↑(release) Kb3"));
+        assert!(result.contains("↑(release) Kb4"));
+    }
+
+    #[test]
+    fn repeat_key() {
+        let result = sim("(defsrc a)(deflayer base b)", "d:a t:10 r:a t:10 u:a t:1");
+        assert!(result.contains("↓(press)   B"));
+        assert!(result.contains("↑(release) B"));
+    }
+
+    #[test]
+    fn layer_switch() {
+        let result = sim(
+            "(defsrc a)(deflayer base a)(deflayer other 1)",
+            "ls:other d:a t:10 u:a t:1",
+        );
+        assert!(result.contains("↓(press)   Kb1"));
+    }
+
+    #[test]
+    fn layer_switch_back_to_base() {
+        let result = sim(
+            "(defsrc a)(deflayer base a)(deflayer other 1)",
+            "ls:other d:a t:10 u:a t:1 ls:base d:a t:10 u:a t:1",
+        );
+        assert!(result.contains("↓(press)   Kb1"));
+        assert!(result.contains("↓(press)   A"));
+    }
+
+    #[test]
+    fn layer_switch_syntax_variants() {
+        let r1 = sim(
+            "(defsrc a)(deflayer base a)(deflayer x 1)",
+            "ls:x d:a t:1 u:a t:1",
+        );
+        let r2 = sim(
+            "(defsrc a)(deflayer base a)(deflayer x 1)",
+            "layer-switch:x d:a t:1 u:a t:1",
+        );
+        let r3 = sim(
+            "(defsrc a)(deflayer base a)(deflayer x 1)",
+            "🔀:x d:a t:1 u:a t:1",
+        );
+        assert!(r1.contains("Kb1"));
+        assert!(r2.contains("Kb1"));
+        assert!(r3.contains("Kb1"));
+    }
+
+    #[test]
+    fn virtual_key_press() {
+        let result = sim(
+            "(defsrc a)(defvirtualkeys vk1 lctl)(deflayer base a)",
+            "vk:vk1 t:10",
+        );
+        assert!(result.contains("↓(press)   LCtrl"));
+    }
+
+    #[test]
+    fn virtual_key_tap() {
+        let result = sim(
+            "(defsrc a)(defvirtualkeys vk1 lctl)(deflayer base a)",
+            "vk:vk1:tap t:10",
+        );
+        assert!(result.contains("↓(press)   LCtrl"));
+        assert!(result.contains("↑(release) LCtrl"));
+    }
+
+    #[test]
+    fn virtual_key_syntax_variants() {
+        let r1 = sim(
+            "(defsrc a)(defvirtualkeys v lctl)(deflayer base a)",
+            "vk:v t:1",
+        );
+        let r2 = sim(
+            "(defsrc a)(defvirtualkeys v lctl)(deflayer base a)",
+            "fakekey:v t:1",
+        );
+        let r3 = sim(
+            "(defsrc a)(defvirtualkeys v lctl)(deflayer base a)",
+            "virtualkey:v t:1",
+        );
+        let r4 = sim(
+            "(defsrc a)(defvirtualkeys v lctl)(deflayer base a)",
+            "🎭:v t:1",
+        );
+        assert!(r1.contains("LCtrl"));
+        assert!(r2.contains("LCtrl"));
+        assert!(r3.contains("LCtrl"));
+        assert!(r4.contains("LCtrl"));
+    }
+
+    #[test]
+    fn error_unknown_key() {
+        let err = sim_err("(defsrc a)(deflayer base a)", "d:notakey");
+        assert!(err.contains("unknown key"));
+    }
+
+    #[test]
+    fn error_unknown_layer() {
+        let err = sim_err("(defsrc a)(deflayer base a)", "ls:notalayer");
+        assert!(err.contains("unknown layer"));
+    }
+
+    #[test]
+    fn error_unknown_virtual_key() {
+        let err = sim_err("(defsrc a)(deflayer base a)", "vk:notavk");
+        assert!(err.contains("unknown virtual key"));
+    }
+
+    #[test]
+    fn error_invalid_action() {
+        let err = sim_err("(defsrc a)(deflayer base a)", "badaction:a");
+        assert!(err.contains("invalid action"));
+    }
+
+    #[test]
+    fn error_missing_colon() {
+        let err = sim_err("(defsrc a)(deflayer base a)", "nocolon");
+        assert!(err.contains("expected format"));
+    }
+}
diff --git a/windows_key_tester/.gitignore b/windows_key_tester/.gitignore
new file mode 100644
index 000000000..e5e1f9514
--- /dev/null
+++ b/windows_key_tester/.gitignore
@@ -0,0 +1 @@
+Cargo.lock
diff --git a/windows_key_tester/Cargo.lock b/windows_key_tester/Cargo.lock
deleted file mode 100644
index e3d10ae0b..000000000
--- a/windows_key_tester/Cargo.lock
+++ /dev/null
@@ -1,584 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-version = 3
-
-[[package]]
-name = "anyhow"
-version = "1.0.66"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "216261ddc8289130e551ddcd5ce8a064710c0d064a4d2895c67151c92b5443f6"
-
-[[package]]
-name = "atty"
-version = "0.2.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8"
-dependencies = [
- "hermit-abi",
- "libc",
- "winapi",
-]
-
-[[package]]
-name = "autocfg"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa"
-
-[[package]]
-name = "bitflags"
-version = "1.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
-
-[[package]]
-name = "bumpalo"
-version = "3.11.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "572f695136211188308f16ad2ca5c851a712c464060ae6974944458eb83880ba"
-
-[[package]]
-name = "cfg-if"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
-
-[[package]]
-name = "clap"
-version = "3.2.23"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71655c45cb9845d3270c9d6df84ebe72b4dad3c2ba3f7023ad47c144e4e473a5"
-dependencies = [
- "atty",
- "bitflags",
- "clap_derive",
- "clap_lex",
- "indexmap",
- "once_cell",
- "strsim",
- "termcolor",
- "textwrap",
-]
-
-[[package]]
-name = "clap_derive"
-version = "3.2.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea0c8bce528c4be4da13ea6fead8965e95b6073585a2f05204bd8f4119f82a65"
-dependencies = [
- "heck",
- "proc-macro-error",
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "clap_lex"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2850f2f5a82cbf437dd5af4d49848fbdfc27c157c3d010345776f952765261c5"
-dependencies = [
- "os_str_bytes",
-]
-
-[[package]]
-name = "hashbrown"
-version = "0.12.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
-
-[[package]]
-name = "heck"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2540771e65fc8cb83cd6e8a237f70c319bd5c29f78ed1084ba5d50eeac86f7f9"
-
-[[package]]
-name = "hermit-abi"
-version = "0.1.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33"
-dependencies = [
- "libc",
-]
-
-[[package]]
-name = "indexmap"
-version = "1.9.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "10a35a97730320ffe8e2d410b5d3b69279b98d2c14bdb8b70ea89ecf7888d41e"
-dependencies = [
- "autocfg",
- "hashbrown",
-]
-
-[[package]]
-name = "interception"
-version = "0.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76b4dc218c6fdcf3c6e9807b892a1100396d936e56b391e533a71e3ad02b17b3"
-dependencies = [
- "bitflags",
- "interception-sys",
- "num_enum",
- "serde",
-]
-
-[[package]]
-name = "interception-sys"
-version = "0.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abe875cf6439eb5d98f0fdbcc6128fdef4870c47e0f898735105ff77685dfcd1"
-
-[[package]]
-name = "itoa"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4217ad341ebadf8d8e724e264f13e593e0648f5b3e94b3896a5df283be015ecc"
-
-[[package]]
-name = "js-sys"
-version = "0.3.60"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49409df3e3bf0856b916e2ceaca09ee28e6871cf7d9ce97a692cacfdb2a25a47"
-dependencies = [
- "wasm-bindgen",
-]
-
-[[package]]
-name = "lazy_static"
-version = "1.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
-
-[[package]]
-name = "libc"
-version = "0.2.137"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc7fcc620a3bff7cdd7a365be3376c97191aeaccc2a603e600951e452615bf89"
-
-[[package]]
-name = "libm"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fc7aa29613bd6a620df431842069224d8bc9011086b1db4c0e0cd47fa03ec9a"
-
-[[package]]
-name = "log"
-version = "0.4.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abb12e687cfb44aa40f41fc3978ef76448f9b6038cad6aef4259d3c095a2382e"
-dependencies = [
- "cfg-if",
-]
-
-[[package]]
-name = "native-windows-gui"
-version = "1.0.13"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f7003a669f68deb6b7c57d74fff4f8e533c44a3f0b297492440ef4ff5a28454"
-dependencies = [
- "bitflags",
- "lazy_static",
- "newline-converter",
- "plotters",
- "plotters-backend",
- "stretch",
- "winapi",
- "winapi-build",
-]
-
-[[package]]
-name = "newline-converter"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f71d09d5c87634207f894c6b31b6a2b2c64ea3bdcf71bd5599fdbbe1600c00f"
-dependencies = [
- "unicode-segmentation",
-]
-
-[[package]]
-name = "num-traits"
-version = "0.2.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "578ede34cf02f8924ab9447f50c28075b4d3e5b269972345e7e0372b38c6cdcd"
-dependencies = [
- "autocfg",
-]
-
-[[package]]
-name = "num_enum"
-version = "0.5.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cf5395665662ef45796a4ff5486c5d41d29e0c09640af4c5f17fd94ee2c119c9"
-dependencies = [
- "num_enum_derive",
-]
-
-[[package]]
-name = "num_enum_derive"
-version = "0.5.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b0498641e53dd6ac1a4f22547548caa6864cc4933784319cd1775271c5a46ce"
-dependencies = [
- "proc-macro-crate",
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "num_threads"
-version = "0.1.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2819ce041d2ee131036f4fc9d6ae7ae125a3a40e97ba64d04fe799ad9dabbb44"
-dependencies = [
- "libc",
-]
-
-[[package]]
-name = "once_cell"
-version = "1.16.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86f0b0d4bf799edbc74508c1e8bf170ff5f41238e5f8225603ca7caaae2b7860"
-
-[[package]]
-name = "os_str_bytes"
-version = "6.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b5bf27447411e9ee3ff51186bf7a08e16c341efdde93f4d823e8844429bed7e"
-
-[[package]]
-name = "plotters"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2538b639e642295546c50fcd545198c9d64ee2a38620a628724a3b266d5fbf97"
-dependencies = [
- "num-traits",
- "plotters-backend",
- "wasm-bindgen",
- "web-sys",
-]
-
-[[package]]
-name = "plotters-backend"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "193228616381fecdc1224c62e96946dfbc73ff4384fba576e052ff8c1bea8142"
-
-[[package]]
-name = "proc-macro-crate"
-version = "1.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eda0fc3b0fb7c975631757e14d9049da17374063edb6ebbcbc54d880d4fe94e9"
-dependencies = [
- "once_cell",
- "thiserror",
- "toml",
-]
-
-[[package]]
-name = "proc-macro-error"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c"
-dependencies = [
- "proc-macro-error-attr",
- "proc-macro2",
- "quote",
- "syn",
- "version_check",
-]
-
-[[package]]
-name = "proc-macro-error-attr"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869"
-dependencies = [
- "proc-macro2",
- "quote",
- "version_check",
-]
-
-[[package]]
-name = "proc-macro2"
-version = "1.0.47"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ea3d908b0e36316caf9e9e2c4625cdde190a7e6f440d794667ed17a1855e725"
-dependencies = [
- "unicode-ident",
-]
-
-[[package]]
-name = "quote"
-version = "1.0.21"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bbe448f377a7d6961e30f5955f9b8d106c3f5e449d493ee1b125c1d43c2b5179"
-dependencies = [
- "proc-macro2",
-]
-
-[[package]]
-name = "serde"
-version = "1.0.147"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d193d69bae983fc11a79df82342761dfbf28a99fc8d203dca4c3c1b590948965"
-dependencies = [
- "serde_derive",
-]
-
-[[package]]
-name = "serde_derive"
-version = "1.0.147"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f1d362ca8fc9c3e3a7484440752472d68a6caa98f1ab81d99b5dfe517cec852"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "simplelog"
-version = "0.12.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48dfff04aade74dd495b007c831cd6f4e0cee19c344dd9dc0884c0289b70a786"
-dependencies = [
- "log",
- "termcolor",
- "time",
-]
-
-[[package]]
-name = "stretch"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b0dc6d20ce137f302edf90f9cd3d278866fd7fb139efca6f246161222ad6d87"
-dependencies = [
- "lazy_static",
- "libm",
-]
-
-[[package]]
-name = "strsim"
-version = "0.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
-
-[[package]]
-name = "syn"
-version = "1.0.103"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a864042229133ada95abf3b54fdc62ef5ccabe9515b64717bcb9a1919e59445d"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
-[[package]]
-name = "termcolor"
-version = "1.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bab24d30b911b2376f3a13cc2cd443142f0c81dda04c118693e35b3835757755"
-dependencies = [
- "winapi-util",
-]
-
-[[package]]
-name = "textwrap"
-version = "0.16.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "222a222a5bfe1bba4a77b45ec488a741b3cb8872e5e499451fd7d0129c9c7c3d"
-
-[[package]]
-name = "thiserror"
-version = "1.0.37"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "10deb33631e3c9018b9baf9dcbbc4f737320d2b576bac10f6aefa048fa407e3e"
-dependencies = [
- "thiserror-impl",
-]
-
-[[package]]
-name = "thiserror-impl"
-version = "1.0.37"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "982d17546b47146b28f7c22e3d08465f6b8903d0ea13c1660d9d84a6e7adcdbb"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "time"
-version = "0.3.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a561bf4617eebd33bca6434b988f39ed798e527f51a1e797d0ee4f61c0a38376"
-dependencies = [
- "itoa",
- "libc",
- "num_threads",
- "serde",
- "time-core",
- "time-macros",
-]
-
-[[package]]
-name = "time-core"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e153e1f1acaef8acc537e68b44906d2db6436e2b35ac2c6b42640fff91f00fd"
-
-[[package]]
-name = "time-macros"
-version = "0.2.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d967f99f534ca7e495c575c62638eebc2898a8c84c119b89e250477bc4ba16b2"
-dependencies = [
- "time-core",
-]
-
-[[package]]
-name = "toml"
-version = "0.5.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8d82e1a7758622a465f8cee077614c73484dac5b836c02ff6a40d5d1010324d7"
-dependencies = [
- "serde",
-]
-
-[[package]]
-name = "unicode-ident"
-version = "1.0.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ceab39d59e4c9499d4e5a8ee0e2735b891bb7308ac83dfb4e80cad195c9f6f3"
-
-[[package]]
-name = "unicode-segmentation"
-version = "1.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fdbf052a0783de01e944a6ce7a8cb939e295b1e7be835a1112c3b9a7f047a5a"
-
-[[package]]
-name = "version_check"
-version = "0.9.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49874b5167b65d7193b8aba1567f5c7d93d001cafc34600cee003eda787e483f"
-
-[[package]]
-name = "wasm-bindgen"
-version = "0.2.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eaf9f5aceeec8be17c128b2e93e031fb8a4d469bb9c4ae2d7dc1888b26887268"
-dependencies = [
- "cfg-if",
- "wasm-bindgen-macro",
-]
-
-[[package]]
-name = "wasm-bindgen-backend"
-version = "0.2.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4c8ffb332579b0557b52d268b91feab8df3615f265d5270fec2a8c95b17c1142"
-dependencies = [
- "bumpalo",
- "log",
- "once_cell",
- "proc-macro2",
- "quote",
- "syn",
- "wasm-bindgen-shared",
-]
-
-[[package]]
-name = "wasm-bindgen-macro"
-version = "0.2.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "052be0f94026e6cbc75cdefc9bae13fd6052cdcaf532fa6c45e7ae33a1e6c810"
-dependencies = [
- "quote",
- "wasm-bindgen-macro-support",
-]
-
-[[package]]
-name = "wasm-bindgen-macro-support"
-version = "0.2.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bc0c051dc5f23e307b13285f9d75df86bfdf816c5721e573dec1f9b8aa193c"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
- "wasm-bindgen-backend",
- "wasm-bindgen-shared",
-]
-
-[[package]]
-name = "wasm-bindgen-shared"
-version = "0.2.83"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1c38c045535d93ec4f0b4defec448e4291638ee608530863b1e2ba115d4fff7f"
-
-[[package]]
-name = "web-sys"
-version = "0.3.60"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bcda906d8be16e728fd5adc5b729afad4e444e106ab28cd1c7256e54fa61510f"
-dependencies = [
- "js-sys",
- "wasm-bindgen",
-]
-
-[[package]]
-name = "winapi"
-version = "0.3.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
-dependencies = [
- "winapi-i686-pc-windows-gnu",
- "winapi-x86_64-pc-windows-gnu",
-]
-
-[[package]]
-name = "winapi-build"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d315eee3b34aca4797b2da6b13ed88266e6d612562a0c46390af8299fc699bc"
-
-[[package]]
-name = "winapi-i686-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
-
-[[package]]
-name = "winapi-util"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70ec6ce85bb158151cae5e5c87f95a8e97d2c0c4b001223f33a334e3ce5de178"
-dependencies = [
- "winapi",
-]
-
-[[package]]
-name = "winapi-x86_64-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
-
-[[package]]
-name = "windows_key_tester"
-version = "0.2.0"
-dependencies = [
- "anyhow",
- "clap",
- "interception",
- "log",
- "native-windows-gui",
- "simplelog",
- "winapi",
-]
diff --git a/windows_key_tester/Cargo.toml b/windows_key_tester/Cargo.toml
index 6e8909486..87105184b 100644
--- a/windows_key_tester/Cargo.toml
+++ b/windows_key_tester/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "windows_key_tester"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["jtroo <j.andreitabs@gmail.com>"]
 description = "Windows keycode tester"
 keywords = []
@@ -11,8 +11,8 @@ readme = "README.md"
 license = "LGPL-3.0"
 edition = "2021"
 
-[dependencies]
-clap = { version = "3", features = [ "derive" ] }
+[target.'cfg(target_os = "windows")'.dependencies]
+clap = { version = "4", features = [ "std", "derive", "help", "suggestions" ], default-features = false }
 log = "0.4.8"
 simplelog = "0.12.0"
 anyhow = "1"
@@ -21,13 +21,10 @@ winapi = { version = "0.3.9", features = [
     "timeapi",
     "mmsystem",
 ] }
-native-windows-gui = "1.0.12"
-interception = { version = "0.1.2", optional = true }
+native-windows-gui = { version = "1.0.12", default-features = false }
+kanata-interception = { version = "0.3.0", optional = true }
+kanata = { path = "..", optional = true }
 
 [features]
-cmd = []
-interception_driver = [ "interception" ]
-
-[profile.release]
-opt-level = "z"
-lto = "fat"
+interception_driver = [ "kanata-interception" ]
+winiov2 = [ "kanata" ]
diff --git a/windows_key_tester/src/main.rs b/windows_key_tester/src/main.rs
index 0bb08bd85..24a5e0d85 100644
--- a/windows_key_tester/src/main.rs
+++ b/windows_key_tester/src/main.rs
@@ -2,72 +2,22 @@
 //! events, print out the event info, then forward it the keyboard event as-is to the rest of the
 //! operating system handling.
 
-use anyhow::Result;
-use log::info;
-use simplelog::*;
+#[cfg(target_os = "windows")]
+mod windows;
+#[cfg(target_os = "windows")]
+use windows::*;
 
-use clap::Parser;
-
-#[cfg(not(feature = "interception_driver"))]
-mod llhook;
-#[cfg(not(feature = "interception_driver"))]
-use llhook::*;
-
-#[cfg(feature = "interception_driver")]
-mod interception;
-#[cfg(feature = "interception_driver")]
-use crate::interception::*;
-
-#[derive(Parser, Debug)]
-#[clap(author, version, about, long_about = None)]
-struct Args {
-    /// Enable debug logging
-    #[clap(short, long)]
-    debug: bool,
-
-    /// Enable trace logging (implies --debug as well)
-    #[clap(short, long)]
-    trace: bool,
-}
-
-/// Parse CLI arguments and initialize logging.
-fn cli_init() {
-    let args = Args::parse();
-
-    let log_lvl = match (args.debug, args.trace) {
-        (_, true) => LevelFilter::Trace,
-        (true, false) => LevelFilter::Debug,
-        (false, false) => LevelFilter::Info,
-    };
-
-    let mut log_cfg = ConfigBuilder::new();
-    if let Err(e) = log_cfg.set_time_offset_to_local() {
-        eprintln!("WARNING: could not set log TZ to local: {:?}", e);
-    };
-    CombinedLogger::init(vec![TermLogger::new(
-        log_lvl,
-        log_cfg.build(),
-        TerminalMode::Mixed,
-        ColorChoice::AlwaysAnsi,
-    )])
-    .expect("logger can init");
-    log::info!("windows_key_tester v{} starting", env!("CARGO_PKG_VERSION"));
-}
-
-fn main_impl() -> Result<()> {
-    cli_init();
-    info!("Sleeping for 2s. Please release all keys and don't press additional ones.");
-    std::thread::sleep(std::time::Duration::from_secs(2));
-    start()?;
-    Ok(())
-}
-
-fn main() -> Result<()> {
+#[cfg(target_os = "windows")]
+fn main() {
     let ret = main_impl();
     if let Err(ref e) = ret {
         log::error!("main got error {}", e);
     }
     eprintln!("\nPress any key to exit");
     let _ = std::io::stdin().read_line(&mut String::new());
-    ret
+}
+
+#[cfg(not(target_os = "windows"))]
+fn main() {
+    print!("Hello world! Wrong OS. Doing nothing.");
 }
diff --git a/windows_key_tester/src/windows.rs b/windows_key_tester/src/windows.rs
new file mode 100644
index 000000000..7ba1c8f14
--- /dev/null
+++ b/windows_key_tester/src/windows.rs
@@ -0,0 +1,58 @@
+use anyhow::Result;
+use simplelog::*;
+
+use clap::Parser;
+#[cfg(not(feature = "interception_driver"))]
+mod llhook;
+#[cfg(not(feature = "interception_driver"))]
+use llhook::*;
+
+#[cfg(feature = "interception_driver")]
+mod interception;
+#[cfg(feature = "interception_driver")]
+use interception::*;
+
+#[derive(Parser, Debug)]
+#[clap(author, version, about, long_about = None)]
+struct Args {
+    /// Enable debug logging
+    #[clap(short, long)]
+    debug: bool,
+
+    /// Enable trace logging (implies --debug as well)
+    #[clap(short, long)]
+    trace: bool,
+}
+
+#[cfg(target_os = "windows")]
+/// Parse CLI arguments and initialize logging.
+fn cli_init() {
+    let args = Args::parse();
+
+    let log_lvl = match (args.debug, args.trace) {
+        (_, true) => LevelFilter::Trace,
+        (true, false) => LevelFilter::Debug,
+        (false, false) => LevelFilter::Info,
+    };
+
+    let mut log_cfg = ConfigBuilder::new();
+    if let Err(e) = log_cfg.set_time_offset_to_local() {
+        eprintln!("WARNING: could not set log TZ to local: {e:?}");
+    };
+    CombinedLogger::init(vec![TermLogger::new(
+        log_lvl,
+        log_cfg.build(),
+        TerminalMode::Mixed,
+        ColorChoice::AlwaysAnsi,
+    )])
+    .expect("logger can init");
+    log::info!("windows_key_tester v{} starting", env!("CARGO_PKG_VERSION"));
+}
+
+pub(crate) fn main_impl() -> Result<()> {
+    cli_init();
+    log::info!("Sleeping for 2s. Please release all keys and don't press additional ones.");
+    std::thread::sleep(std::time::Duration::from_secs(2));
+    start()?;
+    Ok(())
+}
diff --git a/windows_key_tester/src/interception.rs b/windows_key_tester/src/windows/interception.rs
similarity index 99%
rename from windows_key_tester/src/interception.rs
rename to windows_key_tester/src/windows/interception.rs
index 0ed012930..d5f6a052c 100644
--- a/windows_key_tester/src/interception.rs
+++ b/windows_key_tester/src/windows/interception.rs
@@ -1,6 +1,6 @@
 use anyhow::Result;
-use interception as ic;
-use interception::{KeyState, ScanCode, Stroke};
+use kanata_interception as ic;
+use kanata_interception::{KeyState, ScanCode, Stroke};
 
 pub fn start() -> Result<()> {
     let intrcptn = ic::Interception::new().expect(
@@ -219,7 +219,7 @@ impl TryFrom<Stroke> for OsCode {
 
 #[allow(unused)]
 #[allow(non_camel_case_types)]
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum OsCode {
     KEY_RESERVED = 0,
     KEY_ESC = 1,
diff --git a/windows_key_tester/src/llhook.rs b/windows_key_tester/src/windows/llhook.rs
similarity index 85%
rename from windows_key_tester/src/llhook.rs
rename to windows_key_tester/src/windows/llhook.rs
index 972e74669..a111420ce 100644
--- a/windows_key_tester/src/llhook.rs
+++ b/windows_key_tester/src/windows/llhook.rs
@@ -40,6 +40,7 @@ impl Drop for KeyboardHook {
 }
 
 /// Key event received by the low level keyboard hook.
+#[allow(dead_code)]
 #[derive(Debug, Clone, Copy)]
 pub struct InputEvent {
     pub code: u32,
@@ -48,12 +49,25 @@ pub struct InputEvent {
 }
 
 impl InputEvent {
+    #[cfg(not(feature = "winiov2"))]
     fn from_hook_lparam(lparam: &KBDLLHOOKSTRUCT) -> Self {
         Self {
             code: lparam.vkCode,
             up: lparam.flags & LLKHF_UP != 0,
         }
     }
+
+    #[cfg(feature = "winiov2")]
+    fn from_hook_lparam(lparam: &KBDLLHOOKSTRUCT) -> Self {
+        let extended = if lparam.flags & 0x1 == 0x1 { 0xE000 } else { 0 };
+        let code = kanata_state_machine::oskbd::u16_to_osc((lparam.scanCode as u16) | extended)
+            .map(Into::into)
+            .unwrap_or(lparam.vkCode);
+        Self {
+            code,
+            up: lparam.flags & LLKHF_UP != 0,
+        }
+    }
 }
 
 /// The actual WinAPI compatible callback.