Rearrange and standardize Kaleidoscope core headers

I ran `include-what-you-use` wherever possible, and made a number of manual
changes required to get things working with the new header organization.

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

src/Kaleidoscope-LEDControl.h

@@ -16,7 +16,7 @@
 
 #pragma once
 
-#include <kaleidoscope/plugin/LEDMode.h>
+#include "kaleidoscope/plugin/LEDMode.h"
-#include <kaleidoscope/plugin/LEDControl.h>
+#include "kaleidoscope/plugin/LEDControl.h"
-#include <kaleidoscope/plugin/LEDControl/LEDUtils.h>
+#include "kaleidoscope/plugin/LEDControl/LEDUtils.h"
-#include <kaleidoscope/plugin/LEDControl/LED-Off.h>
+#include "kaleidoscope/plugin/LEDControl/LED-Off.h"

src/Kaleidoscope.h

@@ -86,7 +86,7 @@ void setup();
 #include "kaleidoscope/layers.h"
 #include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
 #include "kaleidoscope/macro_map.h"
-#include "kaleidoscope_internal/event_dispatch.h"
+#include "kaleidoscope/hooks.h"
 #include "kaleidoscope_internal/LEDModeManager.h"
 #include "kaleidoscope/macro_helpers.h"
 #include "kaleidoscope/plugin.h"

src/kaleidoscope/KeyAddr.h

@@ -16,6 +16,6 @@
 
 #pragma once
 
-#include "kaleidoscope/device/device.h"
+#include "kaleidoscope/device/device.h"  // for Device
 
 typedef kaleidoscope::Device::KeyAddr KeyAddr;

src/kaleidoscope/KeyAddrBitfield.h

@@ -16,10 +16,11 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <Arduino.h>               // for bitClear, bitRead, bitSet, bitWrite
-
+#include <stdint.h>                // for uint8_t
-#include "kaleidoscope/KeyAddr.h"
+#include <string.h>                // for memset
 
+#include "kaleidoscope/KeyAddr.h"  // for KeyAddr
 
 namespace kaleidoscope {
 

src/kaleidoscope/KeyAddrEventQueue.h

@@ -17,13 +17,15 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <Arduino.h>                       // for bitRead, bitWrite
+#include <stdint.h>                        // for uint8_t, uint16_t
 //#include <assert.h>
 
-#include "kaleidoscope/Runtime.h"
+#include "kaleidoscope/KeyAddr.h"          // for KeyAddr
-#include "kaleidoscope/KeyEvent.h"
+#include "kaleidoscope/KeyEvent.h"         // for KeyEvent, KeyEventId
-#include "kaleidoscope/KeyAddr.h"
+#include "kaleidoscope/Runtime.h"          // for Runtime, Runtime_
-#include "kaleidoscope/keyswitch_state.h"
+#include "kaleidoscope/key_defs.h"         // for Key_Undefined
+#include "kaleidoscope/keyswitch_state.h"  // for IS_PRESSED, WAS_PRESSED
 
 namespace kaleidoscope {
 

src/kaleidoscope/KeyAddrMap.h

@@ -16,9 +16,9 @@
 
 #pragma once
 
-#include "kaleidoscope_internal/device.h"
+#include <stdint.h>                // for uint8_t
-#include "kaleidoscope/KeyAddr.h"
+
-#include "kaleidoscope/key_defs.h"
+#include "kaleidoscope/KeyAddr.h"  // for KeyAddr
 
 namespace kaleidoscope {
 

src/kaleidoscope/KeyEvent.h

@@ -18,8 +18,8 @@
 
 #include <stdint.h>                 // for uint8_t, int8_t
 
-#include "kaleidoscope/key_defs.h"  // for Key, Key_NoKey
 #include "kaleidoscope/KeyAddr.h"   // for KeyAddr
+#include "kaleidoscope/key_defs.h"  // for Key_Undefined, Key
 
 namespace kaleidoscope {
 

src/kaleidoscope/KeyEventTracker.h

@@ -16,8 +16,7 @@
 
 #pragma once
 
-#include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
+#include "kaleidoscope/KeyEvent.h"  // for KeyEvent, KeyEventId
-#include "kaleidoscope/KeyEvent.h"              // for KeyEvent, KeyEventId
 
 namespace kaleidoscope {
 

src/kaleidoscope/KeyMap.h

@@ -16,7 +16,9 @@
 
 #pragma once
 
-#include "kaleidoscope/KeyAddrMap.h"
+#include "kaleidoscope/KeyAddr.h"     // for KeyAddr
+#include "kaleidoscope/KeyAddrMap.h"  // for KeyAddrMap
+#include "kaleidoscope/key_defs.h"    // for Key
 
 namespace kaleidoscope {
 

src/kaleidoscope/LiveKeys.h

@@ -16,9 +16,10 @@
 
 #pragma once
 
-#include "kaleidoscope/key_defs.h"    // for Key, Key_NoKey, Key_Transparent
 #include "kaleidoscope/KeyAddr.h"     // for KeyAddr
+#include "kaleidoscope/KeyAddrMap.h"  // for KeyAddrMap<>::Iterator, KeyAddrMap
 #include "kaleidoscope/KeyMap.h"      // for KeyMap
+#include "kaleidoscope/key_defs.h"    // for Key, Key_Masked, Key_Inactive
 
 namespace kaleidoscope {
 

src/kaleidoscope/MatrixAddr.h

@@ -14,10 +14,11 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+// IWYU pragma: private, include "kaleidoscope/KeyAddr.h"
+
 #pragma once
 
-#include <limits.h>
+#include <stdint.h>  // for uint8_t, int8_t
-#include <stdint.h>
 
 namespace kaleidoscope {
 

src/kaleidoscope/Runtime.cpp

@@ -15,9 +15,17 @@
  */
 
 #include "kaleidoscope/Runtime.h"
-#include "kaleidoscope/LiveKeys.h"
+
-#include "kaleidoscope/layers.h"
+#include <Arduino.h>                                      // for millis
-#include "kaleidoscope/keyswitch_state.h"
+#include <HardwareSerial.h>                               // for HardwareSerial
+
+#include "kaleidoscope/KeyAddr.h"                         // for KeyAddr
+#include "kaleidoscope/KeyEvent.h"                        // for KeyEvent
+#include "kaleidoscope/LiveKeys.h"                        // for LiveKeys
+#include "kaleidoscope/device/device.h"                   // for Base<>::HID
+#include "kaleidoscope/driver/hid/keyboardio/Keyboard.h"  // for Keyboard
+#include "kaleidoscope/keyswitch_state.h"                 // for keyToggledOff
+#include "kaleidoscope/layers.h"                          // for Layer, Layer_
 
 namespace kaleidoscope {
 

src/kaleidoscope/Runtime.h

@@ -16,12 +16,17 @@
 
 #pragma once
 
-#include "kaleidoscope_internal/device.h"
+#include <stdint.h>                             // for uint32_t
-#include "kaleidoscope/event_handler_result.h"
+
-#include "kaleidoscope/hooks.h"
+#include "kaleidoscope/KeyAddr.h"               // for KeyAddr
-#include "kaleidoscope/KeyEvent.h"
+#include "kaleidoscope/KeyEvent.h"              // for KeyEvent
-#include "kaleidoscope/LiveKeys.h"
+#include "kaleidoscope/LiveKeys.h"              // for LiveKeys, live_keys
-#include "kaleidoscope/layers.h"
+#include "kaleidoscope/device/device.h"         // for Device
+#include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
+#include "kaleidoscope/hooks.h"                 // for Hooks
+#include "kaleidoscope/key_defs.h"              // for Key, Key_Transparent
+#include "kaleidoscope/layers.h"                // for Layer, Layer_
+#include "kaleidoscope_internal/device.h"       // for device
 
 namespace kaleidoscope {
 

src/kaleidoscope/bitfields.cpp

@@ -14,9 +14,10 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <Arduino.h>
+#include "kaleidoscope/bitfields.h"
 
-#include "bitfields.h"
+#include <Arduino.h>  // for pgm_read_byte
+#include <stdint.h>   // for uint8_t
 
 namespace kaleidoscope {
 namespace bitfields {

src/kaleidoscope/bitfields.h

@@ -16,8 +16,9 @@
 
 #pragma once
 
-#include <stdint.h>
+#include <Arduino.h>  // for PROGMEM
-#include <stddef.h>
+#include <stddef.h>   // for size_t
+#include <stdint.h>   // for uint8_t
 
 namespace kaleidoscope {
 namespace bitfields {

src/kaleidoscope/device/ATmega32U4Keyboard.h

@@ -19,14 +19,13 @@
 
 #if defined(__AVR__) || defined(KALEIDOSCOPE_VIRTUAL_BUILD)
 
-#include <Arduino.h>
+// IWYU pragma: begin_exports
-#include "kaleidoscope/device/Base.h"
+#include "kaleidoscope/device/Base.h"                           // for BaseP...
-
+#include "kaleidoscope/driver/hid/Keyboardio.h"                 // for Keybo...
-#include "kaleidoscope/driver/mcu/ATmega32U4.h"
+#include "kaleidoscope/driver/mcu/ATmega32U4.h"                 // for ATmeg...
-#include "kaleidoscope/driver/hid/Keyboardio.h"
+#include "kaleidoscope/driver/storage/ATmega32U4EEPROMProps.h"  // for ATmeg...
-#include "kaleidoscope/driver/keyscanner/ATmega.h"
+#include "kaleidoscope/driver/storage/AVREEPROM.h"              // for AVREE...
-#include "kaleidoscope/driver/storage/ATmega32U4EEPROMProps.h"
+// IWYU pragma: end_exports
-#include "kaleidoscope/driver/storage/AVREEPROM.h"
 
 namespace kaleidoscope {
 namespace device {

src/kaleidoscope/device/Base.h

@@ -15,22 +15,26 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+// IWYU pragma: private, include "kaleidoscope/device/device.h"
+
 /** @file kaleidoscope/device/Base.h
  * Base class for Kaleidoscope device libraries.
  */
 
 #pragma once
 
-#include "kaleidoscope/MatrixAddr.h"
+#include <stdint.h>                               // for uint8_t, int8_t
-#include "kaleidoscope_internal/deprecations.h"
+#include <string.h>                               // for size_t, strlen, memcpy
-#include "kaleidoscope/macro_helpers.h"
+
-
+#include "kaleidoscope/driver/bootloader/None.h"  // for None
-#include "kaleidoscope/driver/hid/Base.h"
+#include "kaleidoscope/driver/hid/Base.h"         // for Base, BaseProps
-#include "kaleidoscope/driver/keyscanner/None.h"
+#include "kaleidoscope/driver/keyscanner/Base.h"  // for BaseProps
-#include "kaleidoscope/driver/led/None.h"
+#include "kaleidoscope/driver/keyscanner/None.h"  // for None
-#include "kaleidoscope/driver/mcu/None.h"
+#include "kaleidoscope/driver/led/None.h"         // for cRGB, BaseProps, CRGB
-#include "kaleidoscope/driver/bootloader/None.h"
+#include "kaleidoscope/driver/mcu/Base.h"         // for BaseProps
-#include "kaleidoscope/driver/storage/None.h"
+#include "kaleidoscope/driver/mcu/None.h"         // for None
+#include "kaleidoscope/driver/storage/Base.h"     // for BaseProps
+#include "kaleidoscope/driver/storage/None.h"     // for None
 
 #ifndef CRGB
 #error cRGB and CRGB *must* be defined before including this header!

src/kaleidoscope/device/device.h

@@ -1,5 +1,6 @@
-/* Kaleidoscope - Firmware for computer input devices
+/* -*- mode: c++ -*-
- * Copyright (C) 2013-2019  Keyboard.io, Inc.
+ * Kaleidoscope - Firmware for computer input devices
+ * Copyright (C) 2013-2022  Keyboard.io, Inc.
  *
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
@@ -16,8 +17,42 @@
 
 #pragma once
 
+/** @file kaleidoscope/device/device.h
+ *
+ * Provider of the following types:
+ *  - `kaleidoscope::Device`
+ *  - `kaleidoscope::Device::KeyAddr`
+ *  - `kaleidoscope::DeviceProps`
+ *  - `kaleidoscope::device::HID`
+ *  - `kaleidoscope::device::Storage`
+ *  - `kaleidoscope::device::StorageProps`
+ */
+
+// This file includes whatever hardware plugin is specified during the build.
+// Depending on which device is targeted, you can find the sources in one of the
+// following files under the `plugins` directory:
+//
+// `Kaleidoscope-Hardware-<make>-<model>/src/kaleidoscope/device/<make>/<model>.h`
+//
+// Each hardware device header defines a types `kaleidoscope::Device` and
+// `kaleidoscope::DeviceProps` by using the `EXPORT_DEVICE()` preprocessor
+// macro, which then becomes available to client code by means of this header.
+// Client code should not include specific hardware device headers directly.
+//
+// `KALEIDOSCOPE_HARDWARE_H` gets defined during the build process like this:
+// The fully-qualified board name (fqbn) is read from the `sketch.json` file (in
+// the same directory as the sketch's *.ino file), and that tells Arduino which
+// core to use and which definition to read from `boards.txt`, which adds
+// compiler flags that set `KALEIDOSCOPE_HARDWARE_H` to the appropriate header
+// for the hardware plugin.
+//
+// For a description of the API for the `kaleidoscope::Device` class, see the
+// base device class definition in the following file:
+//
+// `kaleidoscope/device/Base.h`
+
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
-#include "kaleidoscope/device/virtual/Virtual.h"
+#include "kaleidoscope/device/virtual/Virtual.h"  // IWYU pragma: export
 #else
 #include KALEIDOSCOPE_HARDWARE_H
 #endif

src/kaleidoscope/device/key_indexes.h

@@ -17,7 +17,9 @@
 
 #pragma once
 
-#include "kaleidoscope/KeyAddr.h"
+#include <stdint.h>                // for uint8_t
+
+#include "kaleidoscope/KeyAddr.h"  // for KeyAddr
 
 /* To be used by the hardware implementations, `keyIndex` tells us the index of
  * a key, from which we can figure out the row and column as needed. The index

src/kaleidoscope/device/virtual/DefaultHIDReportConsumer.cpp

@@ -16,16 +16,24 @@
 
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
 
-#include "DefaultHIDReportConsumer.h"
+#include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"
-#include "MultiReport/Keyboard.h"
-#include "Logging.h"
 
-#include "virtual_io.h"
+// From KeyboardioHID:
+#include <HID-Settings.h>                         // for HID_REPORTID_NKRO_K...
+#include <MultiReport/Keyboard.h>                 // for HID_KeyboardReport_...
+// From system:
+#include <stdint.h>                               // for uint8_t
+// From Arduino core:
+#include <virtual_io.h>                           // for logUSBEvent_keyboard
+
+// From Kaleidoscope:
+#include "kaleidoscope/device/virtual/Logging.h"  // for log_info, logging
 
 #undef min
 #undef max
 
-#include <sstream>
+#include <sstream>                                // for operator<<, strings...
+#include <string>                                 // for char_traits, operator+
 
 namespace kaleidoscope {
 

src/kaleidoscope/device/virtual/DefaultHIDReportConsumer.h

@@ -18,7 +18,7 @@
 
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
 
-#include <stdint.h>
+#include <stdint.h>  // for uint8_t
 
 namespace kaleidoscope {
 

src/kaleidoscope/device/virtual/HID.cpp

@@ -22,11 +22,9 @@
 // library KeyboardioHID. It replaces all hardware related stuff
 // with stub implementations.
 
-// Include KeyboardioHID's HID.h header
+// From KeyboardioHID:
-//
 #include "HID.h"
-
+#include "HIDReportObserver.h"  // for HIDReportObserver
-#include "HIDReportObserver.h"
 
 #if defined(USBCON)
 

src/kaleidoscope/device/virtual/Logging.h

@@ -18,8 +18,9 @@
 
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
 
-#include "utility"
+#include <stdio.h>  // for fprintf, stderr, stdout
-#include "stdio.h"
+#include <utility>  // IWYU pragma: keep
+// IWYU pragma: no_include <__utility/forward.h>
 
 namespace kaleidoscope {
 namespace logging {

src/kaleidoscope/device/virtual/Virtual.cpp

@@ -18,20 +18,28 @@
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
 
 #include "kaleidoscope/device/virtual/Virtual.h"
-#include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"
-#include "kaleidoscope/device/virtual/Logging.h"
 
-#include "kaleidoscope/keyswitch_state.h"
+// From system:
-#include "kaleidoscope/MatrixAddr.h"
+#include <stdint.h>                               // for uint8_t, uint16_t
-#include "kaleidoscope/key_defs.h"
+#include <stdlib.h>                               // for exit, size_t
 
+// From Arduino:
+#include <EEPROM.h>                               // for EEPROMClass, EERef
+#include <virtual_io.h>                           // for getLineOfInput, isI...
 
-#include "HIDReportObserver.h"
+// From KeyboardioHID:
-#include "virtual_io.h"
+#include <HIDReportObserver.h>                    // for HIDReportObserver
-#include "EEPROM.h"
 
-#include <sstream>
+// From Kaleidoscope:
-#include <string>
+#include "kaleidoscope/KeyAddr.h"                 // for MatrixAddr, MatrixA...
+#include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"  // for DefaultHIDReportCon...
+#include "kaleidoscope/device/virtual/Logging.h"  // for log_error, logging
+#include "kaleidoscope/key_defs.h"                // for Key_NoKey
+#include "kaleidoscope/keyswitch_state.h"         // for IS_PRESSED, WAS_PRE...
+
+// These must come after other headers:
+#include <sstream>                                // for operator<<, string
+#include <string>                                 // for operator==, char_tr...
 
 // FIXME: This relates to virtual/cores/arduino/EEPROM.h.
 //        EEPROM static data must be defined here as only

src/kaleidoscope/device/virtual/Virtual.h

@@ -15,15 +15,25 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+// IWYU pragma: private, include "kaleidoscope/device/device.h"
+
 #pragma once
 
 #ifdef KALEIDOSCOPE_VIRTUAL_BUILD
 
+// Compile-time (emulated) hardware header:
 #include KALEIDOSCOPE_HARDWARE_H
 
-#include "kaleidoscope/driver/bootloader/None.h"
+// From system:
-#include "kaleidoscope/driver/hid/Keyboardio.h"
+#include <stdint.h>                                    // for uint8_t
-#include "kaleidoscope/driver/led/Base.h"
+// From Arduino libraries:
+#include <HardwareSerial.h>                            // for Serial
+// From Kaleidoscope:
+#include "kaleidoscope/device/Base.h"                  // for Base
+#include "kaleidoscope/driver/bootloader/None.h"       // for None
+#include "kaleidoscope/driver/hid/Keyboardio.h"        // for Keyboardio
+#include "kaleidoscope/driver/keyscanner/Base.h"       // for Base
+#include "kaleidoscope/driver/mcu/None.h"              // for None
 
 namespace kaleidoscope {
 namespace device {

src/kaleidoscope/driver/bootloader/None.h

@@ -17,7 +17,7 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/bootloader/Base.h"
+#include "kaleidoscope/driver/bootloader/Base.h"  // for Base
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/bootloader/avr/Caterina.h

@@ -20,8 +20,8 @@
 #ifndef KALEIDOSCOPE_VIRTUAL_BUILD
 #include <avr/wdt.h>
 #endif // ifndef KALEIDOSCOPE_VIRTUAL_BUILD
-#include "kaleidoscope/driver/bootloader/None.h"
+#include "kaleidoscope/driver/bootloader/Base.h"  // IWYU pragma: keep
-#include "kaleidoscope/driver/bootloader/Base.h"
+#include "kaleidoscope/driver/bootloader/None.h"  // for None
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/bootloader/avr/FLIP.h

@@ -25,8 +25,8 @@
 #endif
 #endif // ifndef KALEIDOSCOPE_VIRTUAL_BUILD
 
-#include "kaleidoscope/driver/bootloader/None.h"
+#include "kaleidoscope/driver/bootloader/Base.h"  // IWYU pragma: keep
-#include "kaleidoscope/driver/bootloader/Base.h"
+#include "kaleidoscope/driver/bootloader/None.h"  // for None
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/bootloader/avr/HalfKay.h

@@ -20,8 +20,8 @@
 #ifndef KALEIDOSCOPE_VIRTUAL_BUILD
 #include <avr/wdt.h>
 #endif // ifndef KALEIDOSCOPE_VIRTUAL_BUILD
-#include "kaleidoscope/driver/bootloader/None.h"
+#include "kaleidoscope/driver/bootloader/Base.h"  // IWYU pragma: keep
-#include "kaleidoscope/driver/bootloader/Base.h"
+#include "kaleidoscope/driver/bootloader/None.h"  // for None
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/bootloader/gd32/Base.h

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <Arduino.h>  // IWYU pragma: keep
+
 #include "kaleidoscope/driver/bootloader/Base.h"
 
 namespace kaleidoscope {

src/kaleidoscope/driver/bootloader/samd/Bossac.h

@@ -20,6 +20,8 @@
 
 #ifdef ARDUINO_ARCH_SAMD
 
+#include <Arduino.h>
+
 #include "kaleidoscope/driver/bootloader/Base.h"
 
 namespace kaleidoscope {

src/kaleidoscope/driver/color/GammaCorrection.h

@@ -17,7 +17,8 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <Arduino.h>  // for PROGMEM
+#include <stdint.h>   // for uint8_t
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/Base.h

@@ -16,12 +16,10 @@
  */
 
 #pragma once
-#include <Arduino.h>
-#include "kaleidoscope/key_defs.h"
 
-#include "base/Keyboard.h"
+#include "base/AbsoluteMouse.h"  // for AbsoluteMouse, AbsoluteMouseProps
-#include "base/Mouse.h"
+#include "base/Keyboard.h"       // for Keyboard, KeyboardProps
-#include "base/AbsoluteMouse.h"
+#include "base/Mouse.h"          // for Mouse, MouseProps
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/Keyboardio.h

@@ -16,15 +16,11 @@
  */
 
 #pragma once
-#include <Arduino.h>
-#include <KeyboardioHID.h>
-#include "kaleidoscope/key_defs.h"
 
-#include "kaleidoscope/driver/hid/Base.h"
+#include "kaleidoscope/driver/hid/Base.h"  // for Base, BaseProps
-
+#include "keyboardio/AbsoluteMouse.h"      // for AbsoluteMouse, AbsoluteMou...
-#include "keyboardio/Keyboard.h"
+#include "keyboardio/Keyboard.h"           // for Keyboard, KeyboardProps
-#include "keyboardio/Mouse.h"
+#include "keyboardio/Mouse.h"              // for Mouse, MouseProps
-#include "keyboardio/AbsoluteMouse.h"
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/base/AbsoluteMouse.h

@@ -17,7 +17,7 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <stdint.h>  // for uint8_t, int8_t, uint16_t
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/base/Keyboard.h

@@ -16,9 +16,10 @@
  */
 
 #pragma once
-#include <Arduino.h>
 
-#include "kaleidoscope/key_defs.h"
+#include <stdint.h>                 // for uint8_t
+
+#include "kaleidoscope/key_defs.h"  // for Key, Key_LeftAlt, Key_LeftControl
 
 #ifndef HID_BOOT_PROTOCOL
 #define HID_BOOT_PROTOCOL 0

src/kaleidoscope/driver/hid/base/Mouse.h

@@ -16,7 +16,8 @@
  */
 
 #pragma once
-#include <Arduino.h>
+
+#include <stdint.h>  // for int8_t, uint8_t
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/keyboardio/AbsoluteMouse.h

@@ -17,10 +17,14 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <stdint.h>                                      // for uint8_t, int8_t
-#include <KeyboardioHID.h>
 
-#include "kaleidoscope/driver/hid/base/AbsoluteMouse.h"
+#include <KeyboardioHID.h>
+// From KeyboardioHID:
+#include "DeviceAPIs/AbsoluteMouseAPI.hpp"               // for AbsoluteMous...
+#include "SingleReport/SingleAbsoluteMouse.h"            // for SingleAbsolu...
+// From Kaleidoscope:
+#include "kaleidoscope/driver/hid/base/AbsoluteMouse.h"  // for AbsoluteMouse
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/keyboardio/Keyboard.h

@@ -16,10 +16,17 @@
  */
 
 #pragma once
-#include <Arduino.h>
-#include <KeyboardioHID.h>
 
-#include "kaleidoscope/driver/hid/base/Keyboard.h"
+#include <stdint.h>                                 // for uint8_t, uint16_t
+
+#include <KeyboardioHID.h>
+// From KeyboardioHID:
+#include "BootKeyboard/BootKeyboard.h"              // for BootKeyboard, Boo...
+#include "MultiReport/ConsumerControl.h"            // for ConsumerControl
+#include "MultiReport/Keyboard.h"                   // for Keyboard, Keyboard_
+#include "MultiReport/SystemControl.h"              // for SystemControl
+// From Kaleidoscope:
+#include "kaleidoscope/driver/hid/base/Keyboard.h"  // for Keyboard, Keyboar...
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/keyboardio/Mouse.h

@@ -16,10 +16,14 @@
  */
 
 #pragma once
-#include <Arduino.h>
-#include <KeyboardioHID.h>
 
-#include "kaleidoscope/driver/hid/base/Mouse.h"
+#include <stdint.h>                              // for int8_t, uint8_t
+
+#include <KeyboardioHID.h>
+// From KeyboardioHID:
+#include "MultiReport/Mouse.h"                   // for HID_MouseReport_Data_t
+// From Kaleidoscope:
+#include "kaleidoscope/driver/hid/base/Mouse.h"  // for Mouse, MouseProps
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/keyscanner/ATmega.h

@@ -17,13 +17,11 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <stdint.h>                               // for uint16_t, uint8_t
 
-#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/device/avr/pins_and_ports.h"  // IWYU pragma: keep
-#include "kaleidoscope/driver/keyscanner/Base.h"
+#include "kaleidoscope/driver/keyscanner/Base.h"  // for BaseProps
-#include "kaleidoscope/driver/keyscanner/None.h"
+#include "kaleidoscope/driver/keyscanner/None.h"  // for None
-
-#include "kaleidoscope/device/avr/pins_and_ports.h"
 
 #ifndef KALEIDOSCOPE_VIRTUAL_BUILD
 #include <avr/wdt.h>

src/kaleidoscope/driver/keyscanner/Base.h

@@ -17,10 +17,10 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <stdint.h>                   // for uint8_t
 
-#include "kaleidoscope/key_defs.h"
+#include "kaleidoscope/MatrixAddr.h"  // for MatrixAddr
-#include "kaleidoscope/MatrixAddr.h"
+#include "kaleidoscope/key_defs.h"    // for Key
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/keyscanner/Base_Impl.h

@@ -17,11 +17,14 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/keyscanner/Base.h"
+#include <stdint.h>                               // for uint8_t
-#include "kaleidoscope/device/device.h"
+
-#include "kaleidoscope/keyswitch_state.h"
+#include "kaleidoscope/KeyEvent.h"                // for KeyEvent
-#include "kaleidoscope/KeyEvent.h"
+#include "kaleidoscope/Runtime.h"                 // for Runtime, Runtime_
-#include "kaleidoscope/Runtime.h"
+#include "kaleidoscope/device/virtual/Virtual.h"  // for Device
+#include "kaleidoscope/driver/keyscanner/Base.h"  // for Base
+#include "kaleidoscope/key_defs.h"                // for Key
+#include "kaleidoscope/keyswitch_state.h"         // for keyToggledOff, keyT...
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/keyscanner/None.h

@@ -17,9 +17,7 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include "kaleidoscope/driver/keyscanner/Base.h"  // for BaseProps, Base
-
-#include "kaleidoscope/driver/keyscanner/Base.h"
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/led/Base.h

@@ -21,6 +21,9 @@
 #error cRGB and CRGB *must* be defined before including this header!
 #endif
 
+#include <Arduino.h>  // for PROGMEM, pgm_read_byte
+#include <stdint.h>   // for uint8_t
+
 namespace kaleidoscope {
 namespace driver {
 namespace led {

src/kaleidoscope/driver/led/Color.h

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <stdint.h>  // for uint8_t
+
 namespace kaleidoscope {
 namespace driver {
 namespace led {

src/kaleidoscope/driver/led/None.h

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <stdint.h>                        // for uint8_t
+
 #ifndef CRGB
 
 struct cRGB {
@@ -27,7 +29,7 @@ struct cRGB {
 
 #endif
 
-#include "kaleidoscope/driver/led/Base.h"
+#include "kaleidoscope/driver/led/Base.h"  // for Base, BaseProps (ptr only)
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/led/WS2812.h

@@ -33,8 +33,8 @@
 
 #pragma once
 
-#include "kaleidoscope/hardware/avr/pins_and_ports.h"
 #include "kaleidoscope/driver/led/Color.h"
+#include "kaleidoscope/hardware/avr/pins_and_ports.h"
 #include "ws2812/config.h"
 
 namespace kaleidoscope {

src/kaleidoscope/driver/mcu/ATmega32U4.h

@@ -17,7 +17,7 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/mcu/Base.h"
+#include "kaleidoscope/driver/mcu/Base.h"  // for Base, BaseProps
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/mcu/None.h

@@ -17,7 +17,7 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/mcu/Base.h"
+#include "kaleidoscope/driver/mcu/Base.h"  // for Base, BaseProps (ptr only)
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/storage/ATmega32U4EEPROMProps.h

@@ -17,7 +17,9 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/storage/AVREEPROM.h"
+#include <stdint.h>                                 // for uint16_t
+
+#include "kaleidoscope/driver/storage/AVREEPROM.h"  // for AVREEPROMProps
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/storage/AVREEPROM.h

@@ -17,10 +17,12 @@
 
 #pragma once
 
+#include <stdint.h>                            // for uint16_t, uint8_t
 #if defined(__AVR__) || defined(KALEIDOSCOPE_VIRTUAL_BUILD)
 
-#include "kaleidoscope/driver/storage/Base.h"
+#include <EEPROM.h>                            // for EEPROM, EEPROMClass
-#include <EEPROM.h>
+
+#include "kaleidoscope/driver/storage/Base.h"  // for Base, BaseProps
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/storage/Base.h

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <stdint.h>  // for uint16_t, uint8_t
+
 namespace kaleidoscope {
 namespace driver {
 namespace storage {

src/kaleidoscope/driver/storage/Flash.h

@@ -27,9 +27,10 @@
 
 #ifdef __SAMD21G18A__
 
-#include "kaleidoscope/driver/storage/Base.h"
-#include <FlashStorage.h>
 #include <FlashAsEEPROM.h>
+#include <FlashStorage.h>
+
+#include "kaleidoscope/driver/storage/Base.h"
 
 // We need to undefine Flash, because `FlashStorage` defines it as a macro, yet,
 // we want to use it as a class name.

src/kaleidoscope/driver/storage/GD32Flash.h

@@ -19,9 +19,10 @@
 
 #if defined(ARDUINO_ARCH_GD32) || defined(KALEIDOSCOPE_VIRTUAL_BUILD)
 
+#include <FlashAsEEPROM.h>
+#include <FlashStorage.h>
+
 #include "kaleidoscope/driver/storage/Base.h"
-#include "FlashStorage.h"
-#include "FlashAsEEPROM.h"
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/storage/None.h

@@ -17,7 +17,7 @@
 
 #pragma once
 
-#include "kaleidoscope/driver/storage/Base.h"
+#include "kaleidoscope/driver/storage/Base.h"  // for Base, BaseProps (ptr o...
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/event_handler_result.h

@@ -16,7 +16,7 @@
 
 #pragma once
 
-#include <stdint.h>
+#include <stdint.h>  // for uint8_t
 
 namespace kaleidoscope {
 

src/kaleidoscope/hooks.cpp

@@ -14,10 +14,10 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "kaleidoscope/event_handler_result.h"
+#include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
-#include "kaleidoscope/event_handlers.h"
+#include "kaleidoscope/event_handlers.h"        // for _FOR_EACH_EVENT_HANDLER
-#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/hooks.h"                 // for Hooks
-#include "kaleidoscope/hooks.h"
+#include "kaleidoscope/macro_helpers.h"         // for __NL__, MAKE_TEMPLATE...
 
 namespace kaleidoscope {
 

src/kaleidoscope/hooks.h

@@ -16,30 +16,22 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include "kaleidoscope/KeyEvent.h"  // IWYU pragma: keep
+#include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
+#include "kaleidoscope/event_handlers.h"        // for _FOR_EACH_EVENT_HANDLER
+#include "kaleidoscope/macro_helpers.h"         // for __NL__, MAKE_TEMPLATE...
+#include "kaleidoscope_internal/event_dispatch.h"  // IWYU pragma: keep
 
 namespace kaleidoscope {
-class Key;
+// Forward declarations to enable friend declarations.
-}
+class Layer_;
-
+class Runtime_;
-#include "kaleidoscope/KeyAddr.h"
-#include "kaleidoscope/KeyEvent.h"
-#include "kaleidoscope/plugin.h"
-#include "kaleidoscope/event_handlers.h"
-
-// Forward declaration required to enable friend declarations
-// in class Hooks.
-class kaleidoscope_;
 
-namespace kaleidoscope {
 namespace plugin {
-// Forward declaration to enable friend declarations.
+// Forward declarations to enable friend declarations.
-class LEDControl;
 class FocusSerial;
-}
+class LEDControl;
-
+} // namespace plugin
-// Forward declaration to enable friend declarations.
-class Layer_;
 
 namespace sketch_exploration {
 void pluginsExploreSketch();
@@ -61,11 +53,11 @@ class Hooks {
 
   // Runtime_ calls Hooks::onSetup, Hooks::beforeReportingState
   // and Hooks::afterEachCycle.
+  friend class Layer_;
   friend class Runtime_;
-  friend class ::kaleidoscope::plugin::FocusSerial;
+  friend class plugin::FocusSerial;
-  friend class ::kaleidoscope::Layer_;
+  friend class plugin::LEDControl;
-  friend class ::kaleidoscope::plugin::LEDControl;
+  friend void sketch_exploration::pluginsExploreSketch();
-  friend void ::kaleidoscope::sketch_exploration::pluginsExploreSketch();
 
  private:
 

src/kaleidoscope/key_defs.h

@@ -16,16 +16,18 @@
 
 #pragma once
 
-#include <stdint.h>                         // for uint8_t, uint16_t
-
 #include <Arduino.h>                        // for pgm_read_byte, INPUT
+#include <stdint.h>                         // for uint8_t, uint16_t
 
 #include "kaleidoscope/HIDTables.h"         // for HID_KEYBOARD_LEFT_CONTROL
+
+// IWYU pragma: begin_exports
+#include "kaleidoscope/key_defs/aliases.h"
+#include "kaleidoscope/key_defs/consumerctl.h"
 #include "kaleidoscope/key_defs/keyboard.h"
+#include "kaleidoscope/key_defs/keymaps.h"  // for LAYER_MOVE_OFFSET, LAYER_...
 #include "kaleidoscope/key_defs/sysctl.h"
-#include "kaleidoscope/key_defs/consumerctl.h"
+// IWYU pragma: end_exports
-#include "kaleidoscope/key_defs/keymaps.h"  // for LAYER_SHIFT_OFFSET
-#include "kaleidoscope/key_defs/aliases.h"
 
 // -----------------------------------------------------------------------------
 // Constant keycode values

src/kaleidoscope/key_defs/keymaps.h

@@ -16,9 +16,7 @@
 
 #pragma once
 
-#include <stdint.h>
+#include <stdint.h>  // for uint8_t
-
-#include "kaleidoscope_internal/deprecations.h"
 
 static const uint8_t LAYER_OP_OFFSET = 42;
 static const uint8_t LAYER_SHIFT_OFFSET = LAYER_OP_OFFSET;

src/kaleidoscope/keymaps.h

@@ -16,9 +16,12 @@
 
 #pragma once
 
-#include "kaleidoscope/key_defs.h"
+#include <stdint.h>                        // for uint8_t
-#include "kaleidoscope/KeyAddr.h"
+
-#include "kaleidoscope_internal/device.h"
+#include "kaleidoscope/KeyAddr.h"          // for KeyAddr
+#include "kaleidoscope/device/device.h"    // for Device
+#include "kaleidoscope/key_defs.h"         // for Key
+#include "kaleidoscope_internal/device.h"  // for device
 
 extern const Key keymaps_linear[][kaleidoscope_internal::device.matrix_rows * kaleidoscope_internal::device.matrix_columns];
 

src/kaleidoscope/keyswitch_state.h

@@ -17,8 +17,6 @@
 #pragma once
 // switch debouncing and status
 
-#include <Arduino.h>
-
 #define INJECTED    0b10000000
 #define IS_PRESSED  0b00000010
 #define WAS_PRESSED 0b00000001

src/kaleidoscope/layers.cpp

@@ -14,12 +14,22 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "kaleidoscope_internal/device.h"
+#include <stdint.h>                               // for uint8_t, int8_t
-#include "kaleidoscope/hooks.h"
+#include <string.h>                               // for memmove, memset
-#include "kaleidoscope/layers.h"
+
-#include "kaleidoscope/keyswitch_state.h"
+#include "kaleidoscope/KeyAddr.h"                 // for KeyAddr
-#include "kaleidoscope/KeyEvent.h"
+#include "kaleidoscope/KeyAddrMap.h"              // for KeyAddrMap<>::Iterator
-#include "kaleidoscope/LiveKeys.h"
+#include "kaleidoscope/KeyEvent.h"                // for KeyEvent
+#include "kaleidoscope/KeyMap.h"                  // for KeyMap
+#include "kaleidoscope/LiveKeys.h"                // for LiveKeys, live_keys
+#include "kaleidoscope/MatrixAddr.h"              // for MatrixAddr, MatrixA...
+#include "kaleidoscope/device/virtual/Virtual.h"  // for Device
+#include "kaleidoscope/hooks.h"                   // for Hooks
+#include "kaleidoscope/key_defs.h"                // for Key, LAYER_MOVE_OFFSET
+#include "kaleidoscope/keymaps.h"                 // for keyFromKeymap
+#include "kaleidoscope/keyswitch_state.h"         // for keyToggledOn
+#include "kaleidoscope/layers.h"                  // for Layer_, Layer, Laye...
+#include "kaleidoscope_internal/device.h"         // for device
 
 // The maximum number of layers allowed.
 #define MAX_LAYERS 32;

src/kaleidoscope/layers.h

@@ -16,15 +16,18 @@
 
 #pragma once
 
-#include <Arduino.h>
+#include <Arduino.h>                                // for PROGMEM
-#include "kaleidoscope/key_defs.h"
+#include <stdint.h>                                 // for uint8_t, int8_t
-#include "kaleidoscope/keymaps.h"
+
-#include "kaleidoscope/KeyEvent.h"
+#include "kaleidoscope/KeyAddr.h"                   // for KeyAddr
-#include "kaleidoscope/device/device.h"
+#include "kaleidoscope/KeyEvent.h"                  // for KeyEvent
-#include "kaleidoscope_internal/device.h"
+#include "kaleidoscope/device/device.h"             // for Device
-#include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
+#include "kaleidoscope/key_defs.h"                  // for Key
-#include "kaleidoscope_internal/shortname.h"
+#include "kaleidoscope/keymaps.h"                   // IWYU pragma: keep
-#include "kaleidoscope_internal/deprecations.h"
+#include "kaleidoscope/macro_helpers.h"             // for __NL__
+#include "kaleidoscope_internal/device.h"           // for device
+#include "kaleidoscope_internal/shortname.h"        // for _INIT_HID_GETSHOR...
+#include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"  // for _INIT_SKETCH_EXPL...
 
 #define START_KEYMAPS                                                   __NL__ \
    constexpr Key keymaps_linear[][kaleidoscope_internal::device.matrix_rows * kaleidoscope_internal::device.matrix_columns] PROGMEM = {

src/kaleidoscope/plugin.h

@@ -16,10 +16,6 @@
 
 #pragma once
 
-#include "kaleidoscope/event_handler_result.h"
-#include "kaleidoscope_internal/event_dispatch.h"
-#include "kaleidoscope/event_handlers.h"
-
 #if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
 #error The V1 plugin API has been removed, please see UPGRADING.md.
 #endif

src/kaleidoscope/plugin/AccessTransientLEDMode.h

@@ -16,6 +16,8 @@
 
 #pragma once
 
+#include <stdint.h>  // for uint8_t
+
 namespace kaleidoscope {
 namespace plugin {
 

src/kaleidoscope/plugin/LEDControl.cpp

@@ -14,11 +14,18 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "Kaleidoscope-LEDControl.h"
+#include "kaleidoscope/plugin/LEDControl.h"
-#include "Kaleidoscope-FocusSerial.h"
+
-#include "kaleidoscope_internal/LEDModeManager.h"
+#include <Arduino.h>                               // for PSTR, strcmp_P
-#include "kaleidoscope/keyswitch_state.h"
+#include <Kaleidoscope-FocusSerial.h>              // for Focus, FocusSerial
-#include "kaleidoscope/LiveKeys.h"
+
+#include "kaleidoscope/KeyAddrMap.h"               // for KeyAddrMap<>::Iter...
+#include "kaleidoscope/KeyEvent.h"                 // for KeyEvent
+#include "kaleidoscope/KeyMap.h"                   // for KeyMap
+#include "kaleidoscope/LiveKeys.h"                 // for LiveKeys, live_keys
+#include "kaleidoscope/hooks.h"                    // for Hooks
+#include "kaleidoscope/keyswitch_state.h"          // for keyToggledOn
+#include "kaleidoscope_internal/LEDModeManager.h"  // for LEDModeManager
 
 using namespace kaleidoscope::internal; // NOLINT(build/namespaces)
 

src/kaleidoscope/plugin/LEDControl.h

@@ -16,8 +16,17 @@
 
 #pragma once
 
-#include "kaleidoscope/Runtime.h"
+#include <stdint.h>                                // for uint8_t, uint16_t
-#include "kaleidoscope/plugin/LEDMode.h"
+
+#include "kaleidoscope/KeyAddr.h"                  // for KeyAddr
+#include "kaleidoscope/KeyEvent.h"                 // for KeyEvent
+#include "kaleidoscope/Runtime.h"                  // for Runtime, Runtime_
+#include "kaleidoscope/device/device.h"            // for cRGB, Device, Base...
+#include "kaleidoscope/event_handler_result.h"     // for EventHandlerResult
+#include "kaleidoscope/key_defs.h"                 // for Key, IS_INTERNAL
+#include "kaleidoscope/plugin.h"                   // for Plugin
+#include "kaleidoscope/plugin/LEDMode.h"           // for LEDMode
+#include "kaleidoscope/plugin/LEDModeInterface.h"  // for LEDModeInterface
 
 constexpr uint8_t LED_TOGGLE = 0b00000001;  // Synthetic, internal
 
@@ -28,8 +37,6 @@ constexpr Key Key_LEDToggle = Key(2, KEY_FLAGS | SYNTHETIC | IS_INTERNAL | LED_T
 namespace kaleidoscope {
 namespace plugin {
 
-class LEDMode;
-
 class LEDControl : public kaleidoscope::Plugin {
  public:
   LEDControl(void);

src/kaleidoscope/plugin/LEDControl/LED-Off.cpp

@@ -16,6 +16,8 @@
 
 #include "kaleidoscope/plugin/LEDControl/LED-Off.h"
 
+#include "kaleidoscope/plugin/LEDControl.h"  // for LEDControl
+
 namespace kaleidoscope {
 namespace plugin {
 void LEDOff::onActivate(void) {

src/kaleidoscope/plugin/LEDControl/LED-Off.h

@@ -16,7 +16,8 @@
 
 #pragma once
 
-#include "Kaleidoscope-LEDControl.h"
+#include "kaleidoscope/KeyAddr.h"         // for KeyAddr
+#include "kaleidoscope/plugin/LEDMode.h"  // for LEDMode
 
 namespace kaleidoscope {
 namespace plugin {

src/kaleidoscope/plugin/LEDControl/LEDUtils.cpp

@@ -16,6 +16,8 @@
 
 #include "kaleidoscope/plugin/LEDControl/LEDUtils.h"
 
+#include "kaleidoscope/Runtime.h"  // for Runtime, Runtime_
+
 cRGB
 breath_compute(uint8_t hue, uint8_t saturation, uint8_t phase_offset) {
 

src/kaleidoscope/plugin/LEDControl/LEDUtils.h

@@ -16,7 +16,9 @@
 
 #pragma once
 
-#include "kaleidoscope/Runtime.h"
+#include <stdint.h>                      // for uint16_t, uint8_t
+
+#include "kaleidoscope/device/device.h"  // for cRGB
 
 cRGB breath_compute(uint8_t hue = 170, uint8_t saturation = 255, uint8_t phase_offset = 0);
 cRGB hsvToRgb(uint16_t h, uint16_t s, uint16_t v);

src/kaleidoscope/plugin/LEDMode.h

@@ -16,9 +16,11 @@
 
 #pragma once
 
-#include "kaleidoscope/plugin.h"
+#include "kaleidoscope/KeyAddr.h"                  // for KeyAddr
-#include "kaleidoscope/plugin/AccessTransientLEDMode.h"
+#include "kaleidoscope/event_handler_result.h"     // for EventHandlerResult
-#include "kaleidoscope/plugin/LEDModeInterface.h"
+#include "kaleidoscope/plugin.h"                   // for Plugin
+#include "kaleidoscope/plugin/AccessTransientLEDMode.h"  // IWYU pragma: keep
+#include "kaleidoscope/plugin/LEDModeInterface.h"  // for LEDModeInterface
 
 namespace kaleidoscope {
 

src/kaleidoscope/plugin/LEDModeInterface.cpp

@@ -15,8 +15,8 @@
  */
 
 
-#include <kaleidoscope/plugin/LEDModeInterface.h>
+#include <kaleidoscope/plugin/LEDControl.h>        // for LEDControl
-#include <kaleidoscope/plugin/LEDControl.h>
+#include <kaleidoscope/plugin/LEDModeInterface.h>  // for LEDModeInterface
 
 namespace kaleidoscope {
 namespace plugin {

src/kaleidoscope/progmem_helpers.h

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <Arduino.h>  // for memcpy_P
+
 // Load any intrinsic data type or trivial class stored in PROGMEM into an
 // object of that type in memory.
 template <typename _Type>

src/kaleidoscope/util/crc16.h

@@ -33,7 +33,7 @@
 
 #pragma once
 
-#include <stdint.h>
+#include <stdint.h>  // for uint16_t, uint8_t
 
 static inline uint16_t _crc16_update(uint16_t crc, uint8_t data) __attribute__((always_inline, unused));
 static inline uint16_t _crc16_update(uint16_t crc, uint8_t data) {

src/kaleidoscope/util/flasher/Base.h

@@ -18,6 +18,8 @@
 
 #pragma once
 
+#include <stdint.h>  // for uint8_t
+
 namespace kaleidoscope {
 namespace util {
 namespace flasher {

src/kaleidoscope/util/flasher/KeyboardioI2CBootloader.h

@@ -21,10 +21,11 @@
 // TODO(@algernon): We should support AVR here, too.
 #ifdef __SAMD21G18A__
 
+#include <stdint.h>
 #include <Wire.h>
 
-#include "kaleidoscope/util/flasher/Base.h"
 #include "kaleidoscope/util/crc16.h"
+#include "kaleidoscope/util/flasher/Base.h"
 
 namespace kaleidoscope {
 namespace util {

src/kaleidoscope_internal/LEDModeManager.cpp

@@ -15,7 +15,8 @@
  */
 
 #include "kaleidoscope_internal/LEDModeManager.h"
-#include "kaleidoscope/plugin/LEDMode.h"
+
+#include "kaleidoscope/plugin/LEDMode.h"  // for LEDMode
 
 namespace kaleidoscope {
 namespace internal {

src/kaleidoscope_internal/LEDModeManager.h

@@ -16,12 +16,17 @@
 
 #pragma once
 
-#include "kaleidoscope_internal/array_like_storage.h"
+#include <Arduino.h>                                       // for PROGMEM
-#include "kaleidoscope/plugin.h"
+#include <stddef.h>                                        // for size_t
-#include "kaleidoscope/plugin/LEDMode.h"
+#include <stdint.h>                                        // for uint8_t
-#include "kaleidoscope_internal/type_traits/has_method.h"
+// IWYU pragma: no_include <new>
-
+
-#include <stddef.h>
+#include "kaleidoscope/macro_helpers.h"                    // for __NL__
+#include "kaleidoscope/plugin.h"                           // for Plugin
+#include "kaleidoscope/plugin/LEDMode.h"                   // for LEDMode
+#include "kaleidoscope/plugin/LEDModeInterface.h"          // for LEDModeInt...
+#include "kaleidoscope_internal/array_like_storage.h"  // IWYU pragma: keep
+#include "kaleidoscope_internal/type_traits/has_method.h"  // for DEFINE_HAS...
 
 #if defined(KALEIDOSCOPE_VIRTUAL_BUILD) || defined(ARDUINO_ARCH_STM32)
 #include <new>

src/kaleidoscope_internal/array_like_storage.h

@@ -16,7 +16,7 @@
 
 #pragma once
 
-#include <stdint.h>
+#include <stdint.h>  // for uint8_t
 
 namespace kaleidoscope {
 namespace internal {

src/kaleidoscope_internal/event_dispatch.h

@@ -33,11 +33,10 @@
 
 #pragma once
 
+#include "kaleidoscope/event_handlers.h"
 #include "kaleidoscope/macro_helpers.h"
 #include "kaleidoscope/plugin.h"
-#include "kaleidoscope/hooks.h"
 #include "kaleidoscope_internal/eventhandler_signature_check.h"
-#include "kaleidoscope/event_handlers.h"
 #include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
 
 // Some words about the design of hook routing:

src/kaleidoscope_internal/eventhandler_signature_check.h

@@ -16,10 +16,10 @@
 
 #pragma once
 
-#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/event_handlers.h"                   // for _PROCESS_E...
-#include "kaleidoscope/plugin.h"
+#include "kaleidoscope/macro_helpers.h"                    // for __NL__
-#include "kaleidoscope_internal/type_traits/has_member.h"
+#include "kaleidoscope_internal/type_traits/has_member.h"  // for DEFINE_HAS...
-#include "kaleidoscope_internal/type_traits/has_method.h"
+#include "kaleidoscope_internal/type_traits/has_method.h"  // for DEFINE_HAS...
 
 // *************************************************************************
 // *************************************************************************

src/kaleidoscope_internal/sketch_exploration/keymap_exploration.h

@@ -16,7 +16,10 @@
 
 #pragma once
 
-#include "kaleidoscope/key_defs.h"
+#include <stdint.h>                 // for uint8_t
+
+#include "kaleidoscope/KeyAddr.h"   // for KeyAddr
+#include "kaleidoscope/key_defs.h"  // for Key, Key_NoKey
 
 namespace kaleidoscope { // NOLINT(build/namespaces)
 namespace sketch_exploration { // NOLINT(build/namespaces)
@@ -175,11 +178,6 @@ struct HasKey {
   Key k_;
 };
 
-// This class is actually defined and implemented in _INIT_KEYMAP_EXPLORATION
-// which is invoked by KALEIDOSCOPE_INIT_PLUGINS
-//
-class KeymapInterface;
-
 extern void pluginsExploreSketch();
 
 //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

src/kaleidoscope_internal/sketch_exploration/plugin_exploration.h

@@ -16,7 +16,8 @@
 
 #pragma once
 
-#include "kaleidoscope_internal/type_traits/type_traits"
+#include "kaleidoscope_internal/type_traits/type_traits"  // IWYU pragma: keep
+// IWYU pragma: no_include <type_traits>
 
 namespace kaleidoscope {
 namespace sketch_exploration {

src/kaleidoscope_internal/sketch_exploration/sketch_exploration.cpp

@@ -15,7 +15,6 @@
  */
 
 namespace kaleidoscope {
-\
 namespace sketch_exploration {
 
 // This empty weak symbol is necessary if the KEYMAP(...) macro

src/kaleidoscope_internal/sketch_exploration/sketch_exploration.h

@@ -17,7 +17,7 @@
 #pragma once
 
 #include "kaleidoscope_internal/sketch_exploration/keymap_exploration.h"
-#include "kaleidoscope_internal/sketch_exploration/plugin_exploration.h"
+#include "kaleidoscope_internal/sketch_exploration/plugin_exploration.h"  // IWYU pragma: keep
 
 //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 // Read carefully

src/kaleidoscope_internal/type_traits/has_member.h

@@ -16,7 +16,7 @@
 
 #pragma once
 
-#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/macro_helpers.h"  // for __NL__
 
 // The following code has been stolen from
 //

src/kaleidoscope_internal/type_traits/has_method.h

@@ -16,7 +16,7 @@
 
 #pragma once
 
-#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/macro_helpers.h"  // for __NL__, UNWRAP, ADD_TEMPLATE...
 
 #define DEFINE_HAS_METHOD_TRAITS(PREFIX,                                       \
                                  TMPL_PARAM_TYPE_LIST, TMPL_PARAM_LIST,        \