hid-keymap 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# hid-keymap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+macOS HID keyboard Event Viewer and key mapper. The npm package includes a universal binary for Apple Silicon and Intel Macs; it has no third-party runtime dependencies.
+
+## Install
+
+```sh
+npm install --global hid-keymap
+```
+
+With no arguments, the command prints help. Start the live Event Viewer with:
+
+```sh
+hid-keymap --monitor
+```
+
+Map a non-keyboard HID usage to a modifier, key, or chord:
+
+```sh
+hid-keymap --map 0x01/0x97=right_option
+hid-keymap --map 0x01/0x97=key:escape
+hid-keymap --map 0x01/0x97=left_command+key:space
+```
+
+Mapping mode stays running as a menu bar utility. Open its keyboard icon to see the configured source-to-target mappings, current status, and controls to stop, restart, or quit. The `--monitor` Event Viewer remains in the terminal and prints raw HID usage/value events.
+
+Use `hid-keymap --list-targets` to list accepted target names. By default, it listens to all keyboard collections; add `--device VID/PID` to scope a monitor or mapping to one keyboard.
+
+## Permissions and behavior
+
+Event monitoring needs **Input Monitoring** permission. Mapping also needs **Accessibility** permission to post synthetic key events. macOS may attribute these permissions to the terminal app that launched the command. Set them in **System Settings → Privacy & Security**.
+
+The tool observes HID events and does not suppress the keyboard's original events. It can map non-keyboard-page HID state usages, but cannot replace normal keyboard-page (`0x07`) key events. The keyboard's own Fn layer remains active.
+
+The Event Viewer prints device names and HID page/usage/value data to the terminal, but does not save or transmit it. Press Ctrl-C to stop and release held synthetic modifiers.
+
+## Build
+
+The included Swift source is in `src/hid-keymap.swift`. Building from source requires Xcode Command Line Tools on macOS.

package/bin/hid-keymap.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+if (process.platform !== 'darwin') {
+  console.error('hid-keymap currently supports macOS only.');
+  process.exit(1);
+}
+
+if (!['arm64', 'x64'].includes(process.arch)) {
+  console.error(`hid-keymap does not support macOS architecture: ${process.arch}`);
+  process.exit(1);
+}
+
+const executable = path.resolve(__dirname, '..', 'native', 'hid-keymap');
+const packageRoot = path.resolve(__dirname, '..');
+const relativeExecutable = path.relative(packageRoot, executable);
+if (relativeExecutable.startsWith('..') || path.isAbsolute(relativeExecutable)) {
+  console.error('Invalid bundled executable path.');
+  process.exit(1);
+}
+
+const result = spawnSync(executable, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`Could not start hid-keymap: ${result.error.message}`);
+  process.exit(1);
+}
+process.exitCode = result.status ?? 1;

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "hid-keymap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "macOS HID keyboard event viewer and key mapper",
+  "bin": {
+    "hid-keymap": "bin/hid-keymap.js"
+  },
+  "files": [
+    "README.md",
+    "bin/",
+    "native/",
+    "src/"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "macOS",
+    "HID",
+    "keyboard",
+    "keymap"
+  ]
+}

package/src/hid-keymap.swift

@@ -0,0 +1,608 @@
+import ApplicationServices
+import AppKit
+import CoreGraphics
+import Foundation
+import IOKit.hid
+import IOKit.hidsystem
+
+private let genericDesktopPage = 0x01
+private let keyboardUsage = 0x06
+
+private struct HIDCode: Hashable, CustomStringConvertible {
+    let page: UInt32
+    let usage: UInt32
+
+    var description: String { String(format: "0x%04x/0x%04x", page, usage) }
+
+    static func parse(_ text: String) throws -> HIDCode {
+        let parts = text.split(separator: "/", omittingEmptySubsequences: false)
+        guard parts.count == 2 else { throw CLIError("Expected HID code PAGE/USAGE, such as 0x01/0x97") }
+        let page = try parseNumber(String(parts[0]))
+        let usage = try parseNumber(String(parts[1]))
+        guard page <= UInt32(UInt16.max), usage <= UInt32(UInt16.max) else {
+            throw CLIError("HID page and usage must each fit in 16 bits")
+        }
+        return HIDCode(page: page, usage: usage)
+    }
+
+    private static func parseNumber(_ raw: String) throws -> UInt32 {
+        let value: UInt32?
+        if raw.hasPrefix("0x") || raw.hasPrefix("0X") {
+            value = UInt32(raw.dropFirst(2), radix: 16)
+        } else {
+            value = UInt32(raw, radix: 10)
+        }
+        guard let value else { throw CLIError("Invalid HID number: \(raw)") }
+        return value
+    }
+}
+
+private enum ModifierTarget: String, CaseIterable, Hashable {
+    case leftControl = "left_control"
+    case rightControl = "right_control"
+    case leftOption = "left_option"
+    case rightOption = "right_option"
+    case leftCommand = "left_command"
+    case rightCommand = "right_command"
+    case leftShift = "left_shift"
+    case rightShift = "right_shift"
+
+    var keyCode: CGKeyCode {
+        switch self {
+        case .leftControl: return 0x3b
+        case .rightControl: return 0x3e
+        case .leftOption: return 0x3a
+        case .rightOption: return 0x3d
+        case .leftCommand: return 0x37
+        case .rightCommand: return 0x36
+        case .leftShift: return 0x38
+        case .rightShift: return 0x3c
+        }
+    }
+
+    var flag: CGEventFlags {
+        switch self {
+        case .leftControl, .rightControl: return .maskControl
+        case .leftOption, .rightOption: return .maskAlternate
+        case .leftCommand, .rightCommand: return .maskCommand
+        case .leftShift, .rightShift: return .maskShift
+        }
+    }
+}
+
+private struct KeyTarget: Hashable, CustomStringConvertible {
+    let keyCode: CGKeyCode
+    let modifiers: Set<ModifierTarget>
+    let modifierOnly: ModifierTarget?
+    let name: String
+
+    var description: String { name }
+
+    static let keyCodes: [String: CGKeyCode] = [
+        "a": 0x00, "s": 0x01, "d": 0x02, "f": 0x03, "h": 0x04, "g": 0x05,
+        "z": 0x06, "x": 0x07, "c": 0x08, "v": 0x09, "b": 0x0b, "q": 0x0c,
+        "w": 0x0d, "e": 0x0e, "r": 0x0f, "y": 0x10, "t": 0x11,
+        "1": 0x12, "2": 0x13, "3": 0x14, "4": 0x15, "6": 0x16, "5": 0x17,
+        "=": 0x18, "9": 0x19, "7": 0x1a, "-": 0x1b, "8": 0x1c, "0": 0x1d,
+        "]": 0x1e, "o": 0x1f, "u": 0x20, "[": 0x21, "i": 0x22, "p": 0x23,
+        "return": 0x24, "l": 0x25, "j": 0x26, "'": 0x27, "k": 0x28, ";": 0x29,
+        "\\": 0x2a, ",": 0x2b, "/": 0x2c, "n": 0x2d, "m": 0x2e, ".": 0x2f,
+        "tab": 0x30, "space": 0x31, "grave": 0x32, "backspace": 0x33, "escape": 0x35,
+        "f1": 0x7a, "f2": 0x78, "f3": 0x63, "f4": 0x76, "f5": 0x60, "f6": 0x61,
+        "f7": 0x62, "f8": 0x64, "f9": 0x65, "f10": 0x6d, "f11": 0x67, "f12": 0x6f,
+        "home": 0x73, "page_up": 0x74, "forward_delete": 0x75, "end": 0x77,
+        "page_down": 0x79, "left": 0x7b, "right": 0x7c, "down": 0x7d, "up": 0x7e
+    ]
+
+    static func parse(_ raw: String) throws -> KeyTarget {
+        if let modifier = ModifierTarget(rawValue: raw) {
+            return KeyTarget(keyCode: modifier.keyCode, modifiers: [modifier], modifierOnly: modifier, name: raw)
+        }
+
+        let parts = raw.split(separator: "+", omittingEmptySubsequences: false).map(String.init)
+        guard !parts.isEmpty, !parts.contains(where: \.isEmpty) else {
+            throw CLIError("Invalid target '\(raw)'. Use a key name, modifier name, or modifier+key, such as left_command+key:space")
+        }
+        var modifiers = Set<ModifierTarget>()
+        var keyName: String?
+        for part in parts {
+            if let modifier = ModifierTarget(rawValue: part) {
+                modifiers.insert(modifier)
+            } else if part.hasPrefix("key:"), keyName == nil {
+                keyName = String(part.dropFirst(4))
+            } else {
+                throw CLIError("Unknown target component '\(part)'. Use --list-targets to see available keys")
+            }
+        }
+        guard let keyName, let keyCode = keyCodes[keyName] else {
+            throw CLIError("Target must include one supported key (key:NAME). Use --list-targets to see names")
+        }
+        let canonicalModifiers = ModifierTarget.allCases.filter { modifiers.contains($0) }.map(\.rawValue)
+        let name = (canonicalModifiers + ["key:\(keyName)"]).joined(separator: "+")
+        return KeyTarget(keyCode: keyCode, modifiers: modifiers, modifierOnly: nil, name: name)
+    }
+}
+
+private struct HIDMapping {
+    let source: HIDCode
+    let target: KeyTarget
+}
+
+private struct DeviceFilter {
+    let vendorID: UInt32
+    let productID: UInt32
+
+    static func parse(_ raw: String) throws -> DeviceFilter {
+        let components = raw.split(separator: "/", omittingEmptySubsequences: false)
+        guard components.count == 2,
+              let vendor = parseInteger(String(components[0])),
+              let product = parseInteger(String(components[1])) else {
+            throw CLIError("Expected device filter VID/PID, such as 0x045e/0x0832")
+        }
+        return DeviceFilter(vendorID: vendor, productID: product)
+    }
+}
+
+private struct CLIOptions {
+    let mappings: [HIDMapping]?
+    let deviceFilter: DeviceFilter?
+    let monitor: Bool
+}
+
+private struct DeviceInfo {
+    let id: String
+    let label: String
+    let vendorID: UInt32
+    let productID: UInt32
+
+    init(_ device: IOHIDDevice) {
+        let name = IOHIDDeviceGetProperty(device, kIOHIDProductKey as CFString) as? String ?? "Keyboard"
+        let vendor = (IOHIDDeviceGetProperty(device, kIOHIDVendorIDKey as CFString) as? NSNumber)?.uint32Value ?? 0
+        let product = (IOHIDDeviceGetProperty(device, kIOHIDProductIDKey as CFString) as? NSNumber)?.uint32Value ?? 0
+        vendorID = vendor
+        productID = product
+        let location = (IOHIDDeviceGetProperty(device, kIOHIDLocationIDKey as CFString) as? NSNumber)?.uint32Value
+        id = location.map { String(format: "%04x:%08x", vendor, $0) } ?? String(format: "%04x:%04x:%@", vendor, product, name)
+        label = String(format: "%@ [0x%04x:0x%04x]", name, vendor, product)
+    }
+
+    func matches(_ filter: DeviceFilter?) -> Bool {
+        guard let filter else { return true }
+        return vendorID == filter.vendorID && productID == filter.productID
+    }
+}
+
+private struct ActiveSource: Hashable {
+    let deviceID: String
+    let code: HIDCode
+}
+
+private func parseInteger(_ raw: String) -> UInt32? {
+    if raw.hasPrefix("0x") || raw.hasPrefix("0X") {
+        return UInt32(raw.dropFirst(2), radix: 16)
+    }
+    return UInt32(raw, radix: 10)
+}
+
+private struct CLIError: Error, CustomStringConvertible {
+    let message: String
+    init(_ message: String) { self.message = message }
+    var description: String { message }
+}
+
+private func parseArguments(_ arguments: [String]) throws -> CLIOptions {
+    if arguments.isEmpty {
+        printUsage()
+        exit(EXIT_SUCCESS)
+    }
+    if arguments == ["--help"] || arguments == ["-h"] {
+        printUsage()
+        exit(EXIT_SUCCESS)
+    }
+    if arguments == ["--list-targets"] {
+        printTargets()
+        exit(EXIT_SUCCESS)
+    }
+
+    var mappings: [HIDMapping] = []
+    var seenSources = Set<HIDCode>()
+    var deviceFilter: DeviceFilter?
+    var monitor = false
+    var index = 0
+    while index < arguments.count {
+        if arguments[index] == "--monitor" {
+            guard !monitor else { throw CLIError("Specify --monitor only once") }
+            monitor = true
+            index += 1
+            continue
+        }
+        if arguments[index] == "--device" {
+            index += 1
+            guard index < arguments.count else { throw CLIError("--device requires VID/PID") }
+            guard deviceFilter == nil else { throw CLIError("Specify --device only once") }
+            deviceFilter = try DeviceFilter.parse(arguments[index])
+            index += 1
+            continue
+        }
+        guard arguments[index] == "--map" else {
+            throw CLIError("Unknown argument: \(arguments[index])")
+        }
+        index += 1
+        guard index < arguments.count else { throw CLIError("--map requires PAGE/USAGE=TARGET") }
+        let pair = arguments[index].split(separator: "=", maxSplits: 1, omittingEmptySubsequences: false)
+        guard pair.count == 2 else { throw CLIError("Expected PAGE/USAGE=TARGET after --map") }
+        let source = try HIDCode.parse(String(pair[0]))
+        guard source.page != 0x07 else {
+            throw CLIError("Keyboard-page sources (0x07) are passed through and cannot be safely remapped by this listener")
+        }
+        let target = try KeyTarget.parse(String(pair[1]))
+        guard seenSources.insert(source).inserted else { throw CLIError("Duplicate source HID code: \(source)") }
+        mappings.append(HIDMapping(source: source, target: target))
+        index += 1
+    }
+    guard !(monitor && !mappings.isEmpty) else { throw CLIError("--monitor cannot be combined with --map") }
+    guard monitor || !mappings.isEmpty else { throw CLIError("Use --monitor to view events, or --map to create a mapping") }
+    return CLIOptions(mappings: mappings.isEmpty ? nil : mappings, deviceFilter: deviceFilter, monitor: monitor)
+}
+
+private func printUsage() {
+    print("""
+    hid-keymap — HID Event Viewer / keyboard mapper
+
+    Usage:
+      hid-keymap --monitor [--device VID/PID]
+          Listen and print HID usage/value changes (Event Viewer mode).
+      hid-keymap --map PAGE/USAGE=TARGET [--map PAGE/USAGE=TARGET ...] [--device VID/PID]
+          Map one or more non-keyboard HID state usages to held keys or modifiers.
+      hid-keymap --list-targets
+          List supported target key names.
+
+    Example:
+      hid-keymap --monitor
+      hid-keymap --map 0x01/0x97=right_option
+      hid-keymap --map 0x01/0x97=key:escape
+      hid-keymap --map 0x01/0x97=left_command+key:space
+
+    Targets:
+      Modifier alone: right_option
+      Key alone: key:escape
+      Chord: left_command+key:space (modifiers: left/right_control, option, command, shift)
+
+    Without --device, the listener includes every connected keyboard.
+    Keyboard-page sources (0x07) are rejected because this observer cannot
+    suppress their original key events.
+    """)
+}
+
+private func printTargets() {
+    print("Modifier targets (use alone to hold the modifier):")
+    print(ModifierTarget.allCases.map(\.rawValue).joined(separator: ", "))
+    print("\nKey targets (prefix names with key:):")
+    print(KeyTarget.keyCodes.keys.sorted().map { "key:\($0)" }.joined(separator: "\n"))
+    print("\nExamples: right_option, key:escape, left_command+key:space")
+}
+
+private func inputValueCallback(context: UnsafeMutableRawPointer?, result: IOReturn, sender: UnsafeMutableRawPointer?, value: IOHIDValue) {
+    guard result == kIOReturnSuccess, let context else { return }
+    Unmanaged<HIDMapper>.fromOpaque(context).takeUnretainedValue().handle(value)
+}
+
+private func deviceMatchedCallback(context: UnsafeMutableRawPointer?, result: IOReturn, sender: UnsafeMutableRawPointer?, device: IOHIDDevice) {
+    guard result == kIOReturnSuccess, let context else { return }
+    Unmanaged<HIDMapper>.fromOpaque(context).takeUnretainedValue().setConnected(device, connected: true)
+}
+
+private func deviceRemovedCallback(context: UnsafeMutableRawPointer?, result: IOReturn, sender: UnsafeMutableRawPointer?, device: IOHIDDevice) {
+    guard result == kIOReturnSuccess, let context else { return }
+    Unmanaged<HIDMapper>.fromOpaque(context).takeUnretainedValue().setConnected(device, connected: false)
+}
+
+private final class HIDMapper {
+    private let mappings: [HIDCode: KeyTarget]
+    private let deviceFilter: DeviceFilter?
+    private let eventViewer: Bool
+    private var manager: IOHIDManager?
+    private var activeSources = Set<ActiveSource>()
+    private var activeTargets = Set<KeyTarget>()
+    private var connectedDevices = Set<String>()
+    private let formatter = ISO8601DateFormatter()
+    var onStatusChange: ((String) -> Void)?
+    private(set) var status = "Not started"
+
+    init(options: CLIOptions) {
+        eventViewer = options.monitor
+        deviceFilter = options.deviceFilter
+        mappings = Dictionary(uniqueKeysWithValues: (options.mappings ?? []).map { ($0.source, $0.target) })
+    }
+
+    func start() throws {
+        if IOHIDCheckAccess(kIOHIDRequestTypeListenEvent) != kIOHIDAccessTypeGranted {
+            _ = IOHIDRequestAccess(kIOHIDRequestTypeListenEvent)
+        }
+        guard IOHIDCheckAccess(kIOHIDRequestTypeListenEvent) == kIOHIDAccessTypeGranted else {
+            throw CLIError("Input Monitoring permission is required. Allow the launching app (usually Terminal) in System Settings → Privacy & Security → Input Monitoring, then run again.")
+        }
+
+        if !eventViewer && !AXIsProcessTrusted() {
+            let promptKey = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
+            _ = AXIsProcessTrustedWithOptions([promptKey: true] as CFDictionary)
+        }
+        guard eventViewer || AXIsProcessTrusted() else {
+            throw CLIError("Accessibility permission is required to post modifier events. Allow the launching app (usually Terminal) in System Settings → Privacy & Security → Accessibility, then run again.")
+        }
+
+        let newManager = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))
+        var criteria: [String: Any] = [
+            kIOHIDPrimaryUsagePageKey as String: genericDesktopPage,
+            kIOHIDPrimaryUsageKey as String: keyboardUsage
+        ]
+        if let deviceFilter {
+            criteria[kIOHIDVendorIDKey as String] = deviceFilter.vendorID
+            criteria[kIOHIDProductIDKey as String] = deviceFilter.productID
+        }
+        IOHIDManagerSetDeviceMatching(newManager, criteria as CFDictionary)
+        let context = Unmanaged.passUnretained(self).toOpaque()
+        IOHIDManagerRegisterInputValueCallback(newManager, inputValueCallback, context)
+        IOHIDManagerRegisterDeviceMatchingCallback(newManager, deviceMatchedCallback, context)
+        IOHIDManagerRegisterDeviceRemovalCallback(newManager, deviceRemovedCallback, context)
+        IOHIDManagerScheduleWithRunLoop(newManager, CFRunLoopGetMain(), CFRunLoopMode.defaultMode.rawValue)
+
+        let result = IOHIDManagerOpen(newManager, IOOptionBits(kIOHIDOptionsTypeNone))
+        guard result == kIOReturnSuccess else {
+            IOHIDManagerUnscheduleFromRunLoop(newManager, CFRunLoopGetMain(), CFRunLoopMode.defaultMode.rawValue)
+            throw CLIError("Could not open keyboard HID devices (IOKit status \(result))")
+        }
+        manager = newManager
+
+        if eventViewer {
+            let scope = deviceFilter.map { String(format: "VID/PID 0x%04x/0x%04x", $0.vendorID, $0.productID) } ?? "all keyboards"
+            print("Listening for HID changes from \(scope). Press Ctrl-C to stop.")
+            print("Timestamp                      Device                                  Usage page   Usage        Value")
+        } else {
+            setStatus("Ready · \(mappings.count) mapping\(mappings.count == 1 ? "" : "s")")
+        }
+        fflush(stdout)
+    }
+
+    func handle(_ value: IOHIDValue) {
+        let element = IOHIDValueGetElement(value)
+        let device = DeviceInfo(IOHIDElementGetDevice(element))
+        guard device.matches(deviceFilter) else { return }
+        let code = HIDCode(page: IOHIDElementGetUsagePage(element), usage: IOHIDElementGetUsage(element))
+        let integerValue = IOHIDValueGetIntegerValue(value)
+
+        if eventViewer {
+            let timestamp = formatter.string(from: Date())
+            print(String(format: "%@  %-39@  0x%04x       0x%04x     %lld", timestamp, device.label as NSString, code.page, code.usage, integerValue))
+            fflush(stdout)
+            return
+        }
+
+        guard mappings[code] != nil else { return }
+        let source = ActiveSource(deviceID: device.id, code: code)
+        let isDown = integerValue != 0
+        let changed: Bool
+        if isDown { changed = activeSources.insert(source).inserted }
+        else { changed = activeSources.remove(source) != nil }
+        guard changed else { return }
+
+        updateTargets()
+        if !eventViewer, let target = mappings[code] {
+            setStatus(isDown ? "Pressed · \(target)" : "Ready · \(mappings.count) mapping\(mappings.count == 1 ? "" : "s")")
+        }
+    }
+
+    func setConnected(_ rawDevice: IOHIDDevice, connected: Bool) {
+        let device = DeviceInfo(rawDevice)
+        guard device.matches(deviceFilter) else { return }
+        if connected {
+            guard connectedDevices.insert(device.id).inserted else { return }
+            if eventViewer { print("[Connected] \(device.label)") }
+        } else {
+            guard connectedDevices.remove(device.id) != nil else { return }
+            if eventViewer { print("[Disconnected] \(device.label)") }
+            activeSources = activeSources.filter { $0.deviceID != device.id }
+            updateTargets()
+            if !eventViewer { setStatus("Keyboard disconnected · waiting for input") }
+        }
+    }
+
+    func run() {
+        let interrupt = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+        signal(SIGINT, SIG_IGN)
+        interrupt.setEventHandler { [weak self] in
+            self?.stop()
+            exit(EXIT_SUCCESS)
+        }
+        interrupt.resume()
+
+        let terminate = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main)
+        signal(SIGTERM, SIG_IGN)
+        terminate.setEventHandler { [weak self] in
+            self?.stop()
+            exit(EXIT_SUCCESS)
+        }
+        terminate.resume()
+        CFRunLoopRun()
+        stop()
+    }
+
+    func stop() {
+        releaseAllTargets()
+        if let manager {
+            IOHIDManagerClose(manager, IOOptionBits(kIOHIDOptionsTypeNone))
+            IOHIDManagerUnscheduleFromRunLoop(manager, CFRunLoopGetMain(), CFRunLoopMode.defaultMode.rawValue)
+        }
+        manager = nil
+        if !eventViewer { setStatus("Stopped") }
+    }
+
+    private func releaseAllTargets() {
+        activeSources.removeAll()
+        updateTargets()
+    }
+
+    private func updateTargets() {
+        let newTargets = Set(activeSources.compactMap { mappings[$0.code] })
+        let releases = activeTargets.subtracting(newTargets)
+        let presses = newTargets.subtracting(activeTargets)
+        activeTargets = newTargets
+        for target in releases { post(target, down: false, flags: flags(for: activeTargets)) }
+        for target in presses { post(target, down: true, flags: flags(for: activeTargets)) }
+    }
+
+    private func flags(for targets: Set<KeyTarget>) -> CGEventFlags {
+        targets.reduce(into: CGEventFlags()) { flags, target in
+            for modifier in target.modifiers { flags.formUnion(modifier.flag) }
+        }
+    }
+
+    private func post(_ target: KeyTarget, down: Bool, flags: CGEventFlags) {
+        guard let event = CGEvent(keyboardEventSource: nil, virtualKey: target.keyCode, keyDown: down) else {
+            fputs("Could not create event for \(target)\n", stderr)
+            return
+        }
+        event.flags = target.modifiers.reduce(flags) { $0.union($1.flag) }
+        event.post(tap: .cghidEventTap)
+    }
+
+    func reportError(_ error: Error) {
+        setStatus(String(describing: error))
+    }
+
+    private func setStatus(_ newStatus: String) {
+        status = newStatus
+        onStatusChange?(newStatus)
+    }
+}
+
+private final class MappingMenuApp: NSObject, NSApplicationDelegate {
+    private let mapper: HIDMapper
+    private let mappings: [HIDMapping]
+    private let deviceFilter: DeviceFilter?
+    private var statusItem: NSStatusItem?
+    private var statusMenuItem: NSMenuItem?
+    private var interruptSource: DispatchSourceSignal?
+    private var terminateSource: DispatchSourceSignal?
+
+    init(options: CLIOptions) {
+        mapper = HIDMapper(options: options)
+        mappings = options.mappings ?? []
+        deviceFilter = options.deviceFilter
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        buildMenu()
+        mapper.onStatusChange = { [weak self] status in
+            self?.statusMenuItem?.title = status
+            self?.statusItem?.button?.toolTip = "hid-keymap · \(status)"
+        }
+        installSignalHandlers()
+        startMapping()
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        mapper.stop()
+    }
+
+    @objc private func stopMapping() {
+        mapper.stop()
+    }
+
+    @objc private func restartMapping() {
+        mapper.stop()
+        startMapping()
+    }
+
+    @objc private func quit() {
+        mapper.stop()
+        NSApp.terminate(nil)
+    }
+
+    private func startMapping() {
+        do {
+            try mapper.start()
+        } catch {
+            mapper.reportError(error)
+        }
+    }
+
+    private func buildMenu() {
+        let item = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        item.button?.title = "⌨"
+        item.button?.toolTip = "hid-keymap"
+
+        let menu = NSMenu()
+        let status = NSMenuItem(title: mapper.status, action: nil, keyEquivalent: "")
+        status.isEnabled = false
+        menu.addItem(status)
+        statusMenuItem = status
+        menu.addItem(.separator())
+
+        for mapping in mappings.sorted(by: { $0.source.description < $1.source.description }) {
+            let line = NSMenuItem(title: "\(mapping.source) → \(mapping.target)", action: nil, keyEquivalent: "")
+            line.isEnabled = false
+            menu.addItem(line)
+        }
+        if let deviceFilter {
+            let scope = NSMenuItem(title: String(format: "Device · 0x%04x/0x%04x", deviceFilter.vendorID, deviceFilter.productID), action: nil, keyEquivalent: "")
+            scope.isEnabled = false
+            menu.addItem(scope)
+        } else {
+            let scope = NSMenuItem(title: "Device · all keyboards", action: nil, keyEquivalent: "")
+            scope.isEnabled = false
+            menu.addItem(scope)
+        }
+        menu.addItem(.separator())
+
+        let stopItem = NSMenuItem(title: "Stop Mapping", action: #selector(stopMapping), keyEquivalent: "")
+        stopItem.target = self
+        menu.addItem(stopItem)
+        let restartItem = NSMenuItem(title: "Restart Mapping", action: #selector(restartMapping), keyEquivalent: "")
+        restartItem.target = self
+        menu.addItem(restartItem)
+        menu.addItem(.separator())
+        let quitItem = NSMenuItem(title: "Quit hid-keymap", action: #selector(quit), keyEquivalent: "q")
+        quitItem.target = self
+        menu.addItem(quitItem)
+        item.menu = menu
+        statusItem = item
+    }
+
+    private func installSignalHandlers() {
+        signal(SIGINT, SIG_IGN)
+        let interrupt = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+        interrupt.setEventHandler { [weak self] in self?.quit() }
+        interrupt.resume()
+        interruptSource = interrupt
+
+        signal(SIGTERM, SIG_IGN)
+        let terminate = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main)
+        terminate.setEventHandler { [weak self] in self?.quit() }
+        terminate.resume()
+        terminateSource = terminate
+    }
+}
+
+@main
+enum FnHIDMapMain {
+    static func main() {
+        do {
+            let options = try parseArguments(Array(CommandLine.arguments.dropFirst()))
+            if options.monitor {
+                let mapper = HIDMapper(options: options)
+                try mapper.start()
+                mapper.run()
+            } else {
+                let app = NSApplication.shared
+                let delegate = MappingMenuApp(options: options)
+                app.delegate = delegate
+                app.run()
+            }
+        } catch {
+            fputs("hid-keymap: \(error)\nUse --help for usage.\n", stderr)
+            exit(EXIT_FAILURE)
+        }
+    }
+}