feat(usb-hid): queue and replay HID reports across USB not-ready windows

[akira-toriyama]

What

Add CONFIG_ZMK_USB_HID_REPLAY_ON_READY (default n). When enabled,
zmk_usb_hid_send_report enqueues HID reports issued during any USB
not-ready state (SUSPEND, ERROR, RESET, DISCONNECTED,
UNKNOWN, CONNECTED) into a small static ring buffer, and a
listener on zmk_usb_conn_state_changed schedules a delayable work
item to flush the queue shortly after USB transitions back to a ready
state.

Why

zmk_usb_hid_send_report currently drops every report issued while
the USB endpoint is not ready:

• USB_DC_SUSPEND → returns usb_wakeup_request() (the report itself
  is discarded).
• USB_DC_DISCONNECTED / RESET / UNKNOWN / ERROR → returns -ENODEV.
• USB_DC_CONNECTED → falls into the default branch, where
  hid_int_ep_write is attempted on a not-yet-configured bus and
  fails silently.

The host HID stack additionally drops the first input report from a
freshly bound interface — a binding-race quirk observed on macOS.
Together these surface as:

• "First key after dongle replug is ignored."
• "First key on host sleep resume is lost or needs an extra press" —
  intermittent, because the user's press lands on a transient USB
  state (SUSPEND/RESET/CONNECTED) on the resume path, and macOS
  re-enumerates with one or more extra bus resets on deep wake.

This is especially visible on USB-dongle keyboard setups where a BLE
central forwards HID over USB — the host-side resume latency is on
the order of hundreds of ms and traverses several short-lived USB
device-controller states, so the user's first keystrokes fall inside
that window.

Related: #2686 (the BLE deep-sleep variant of the same symptom class —
out of scope here; a peripheral powered off in deep sleep consumes its
wake keypress at the hardware level before firmware runs).

How

Every not-ready case in zmk_usb_hid_send_report enqueues the report
bytes before returning its existing error. A new ZMK listener on
zmk_usb_conn_state_changed schedules a delayable work item when USB
reaches a ready state; the flush worker drains the ring buffer via
hid_int_ep_write. The configurable flush delay defaults to 100 ms,
which experimentally is enough on macOS to let the host finish HID
interface binding before the resend.

The flush path is hardened against deep-wake re-enumeration hazards
found during on-hardware testing:

• Advisory semaphore take in the flush (mirroring the normal send
  path, which ignores its take result): a bus reset aborts an armed IN
  transfer without raising the write-complete callback
  (usb_dc_nrfx EP_ABORTED is log-only), stranding the semaphore at
  0; blocking on it would abandon the queue for the whole wake cycle.
• Retry on a short timer while the bus is active when a flush
  write fails (e.g. -EAGAIN mid-enumeration), instead of waiting for
  a status-change event that may never come.
• k_work_reschedule in the listener: k_work_schedule on an
  already-pending work keeps the old deadline, so a
  RESUME → RESET → CONFIGURED cluster would otherwise fire the flush
  ~0 ms after CONFIGURED — inside the host binding race the delay
  exists to avoid. Suspend entry (which still maps to a HID-ready conn
  state) no longer schedules a pointless flush.
• Ordering: HID reports are absolute state snapshots, so a live
  release racing past its queued press would leave that key logically
  held on the host. While the queue is non-empty, ready-path reports
  append and flush in order.
• Queue cleared on USB_DC_DISCONNECTED: replaying hours-old
  keystrokes on replug is phantom input, not recovery.

Queue sizing is configurable so embedded targets can trade RAM for
robustness:

• CONFIG_ZMK_USB_HID_REPLAY_QUEUE_DEPTH — default 8, range 1..64
• CONFIG_ZMK_USB_HID_REPLAY_REPORT_MAX_LEN — default 16 B, range 8..64
• CONFIG_ZMK_USB_HID_REPLAY_FLUSH_DELAY_MS — default 100 ms, range 0..1000

Overflow drops the oldest entry. Oversized reports are dropped at
enqueue with a LOG_WRN. Default-off so the static memory cost
(depth × max_len + one mutex + one delayable work item) is only
paid by firmwares that opt in.

Testing

Tested in production on a dongle-based BLE split setup (XIAO BLE
central + two assimilator-bt peripherals forwarding HID over USB)
on macOS. With the option enabled:

• Dongle physical unplug → replug → first key arrives immediately.
• PC sleep → resume → no extra keypress needed beyond the wake key
  that macOS itself consumes by design (its HID pipeline cancels
  key-downs within 500 ms of wake and while the display is off — that
  part is host behaviour common to all keyboards, not fixable in
  firmware).
• No stuck keys, phantom repeats, or latency regressions in normal
  typing, including immediately after resume.

Default-off path is byte-identical (#if-guarded), verified by
building the same target with and without the option enabled.

Downstream use: akira-toriyama/canon
runs this change as an out-of-tree patch (patches/zmk/usb-hid-prime-on-ready.patch)
pending this PR.

PR check-list

• Branch has a clean commit history
• Additional tests are included, if changing behaviors/core code that is testable. (no zmk-side test harness for USB HID lifecycle; happy to add one if pointed at an existing pattern)
• Proper Copyright + License headers added to applicable files
• Pre-commit used to check formatting
• Includes any necessary documentation changes. (can add a docs mention if maintainers prefer)