# Capswitch code review — 2026-10-25

## Scope

Review of the already-working Caps->F19 HID remapping, Quartz event tap,
TIS input source switching, menu bar lifecycle, installer and login setup.

## Findings and changes

1. High: no stable installation path. Launching a bundle in build/ makes
   privacy permissions and login registration fragile. Added a user-scoped
   installer to ~/Applications with staged copying, identity validation and
   safeguards against replacing a different or running application.
2. High: unsafe restart could strand a remapped Caps. Restart restores the
   physical key first, refuses to exit if restoration fails, launches a new
   copy of the same executable and waits for the previous PID to disappear
   before creating AppKit, the event tap or HID manager.
3. Medium: no native login management. SMAppService.mainApp now provides a
   user-toggleable Launch at Login status with approval guidance in Settings.
4. Medium: InputSourceManager and HID event-tap concerns were co-located.
   Extracted the input source adapter without changing the proven event path.
5. Medium: startup argument parsing embedded in main. Added an independent
   LaunchArguments core type and tests for doctor, install and wait-for-PID.
6. Medium: distribution required manual copying. Taskfile now provides an
   install task that packages and starts the installed copy without sudo.

## Protected behavior

The existing HID IOHIDServiceClientSetProperty and CoreGraphics CGEventTap
approach is hardware-verified on macOS 14.8.9. The normal Caps->F19 event
path and Option+Caps gesture state machine are deliberately unchanged.

## Remaining verification

- SMAppService status/registration for ad-hoc signed apps and user Applications
  on this particular macOS Sonoma machine.
- Restart of a copy launched via its signed bundle executable must be checked
  for macOS privacy identity continuity.
- Staged app replacement rolls back ordinary filesystem errors but a power
  interruption between filesystem moves can leave a backup copy.
- HID ownership persistence failure handling needs independent runtime tests.
- Enabled input source ordering uses HIToolbox preferences. Preserve the
  current working behavior unless a future acceptance test demonstrates a bug.

## On-Mac acceptance

1. Quit the old app and run task test, task install.
2. Confirm the launched bundle resides in ~/Applications.
3. Verify the rapid Caps typing test still passes.
4. Restart via menu; only one status item and running process remains.
5. Verify Caps+Option and Pause/Quit restore normal Caps.
6. Toggle Launch at Login on, approve when required, log out/in to verify.
7. Toggle Launch at Login off, log out/in to verify it stays off.
8. Reinstall an updated development build after closing the installed app.
9. Confirm other pre-existing HID mappings survive every path.