react-native-apple-key-commands 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Georgian Alexa
+
+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.

package/README.md

@@ -0,0 +1,165 @@
+# react-native-apple-key-commands
+
+> ☕ **If this library has helped you, consider [buying me a coffee](https://buymeacoffee.com/boogdan)!** Your support keeps development going.
+
+Dynamic hardware-keyboard shortcuts (UIKeyCommand) for React Native and Expo. Register key commands from JavaScript, get an event back when one fires. Works on iPad with a connected keyboard and on iPad apps running on an Apple silicon Mac. iOS only, built with the Expo Modules API.
+
+```ts
+import { setKeyCommands, addKeyCommandListener } from 'react-native-apple-key-commands';
+
+setKeyCommands([{ id: 'launch', input: 'return', modifiers: ['command'], title: 'Launch' }]);
+const sub = addKeyCommandListener(id => { if (id === 'launch') runSearch(); });
+```
+
+## Why
+
+React Native and Expo expose no API for hardware-keyboard shortcuts. On iPad (and iPad apps running on Mac), UIKit has a first-class mechanism for this: `UIKeyCommand`. This module bridges it -- commands are defined dynamically from JavaScript (not hardcoded native), and a single JS event fires when any registered command is pressed.
+
+Note: **there is no menu bar integration.** The `title` field feeds only the iPad ⌘-hold discoverbility overlay; `UIMenuBuilder` and the macOS menu bar are not involved.
+
+## Installation
+
+```bash
+npm install react-native-apple-key-commands
+# or
+yarn add react-native-apple-key-commands
+# or
+bun add react-native-apple-key-commands
+```
+
+Then rebuild the native project so autolinking picks up the module:
+
+```bash
+npx expo prebuild
+npx expo run:ios
+```
+
+There is **no config plugin and no entitlements** to set up -- installing and rebuilding is all that is required.
+
+### Prerequisites
+
+- Expo `>= 51.0.0`
+- React Native `>= 0.74.0`
+- iOS only (Android and other platforms are safely inert -- see [Platform behavior](#platform-behavior))
+- A native build. Key commands register and fire on a device or simulator build; in Jest the native module is absent and all helpers no-op.
+
+## API Reference
+
+```ts
+import {
+  setKeyCommands,
+  clearKeyCommands,
+  addKeyCommandListener,
+  isKeyCommandsSupported,
+} from 'react-native-apple-key-commands';
+import type { KeyCommand, KeyModifier } from 'react-native-apple-key-commands';
+```
+
+### Types
+
+```ts
+type KeyModifier = 'command' | 'shift' | 'option' | 'control';
+
+interface KeyCommand {
+  /** Stable id echoed back to the listener when this command fires. */
+  id: string;
+  /**
+   * The key to bind. Use a single character, or one of the named keys:
+   * return | escape | space | tab | up | down | left | right
+   */
+  input: string;
+  modifiers?: KeyModifier[];
+  /** Shown in the iPad ⌘-hold overlay. No effect on the menu bar. */
+  title?: string;
+}
+```
+
+### `setKeyCommands(commands)`
+
+```ts
+function setKeyCommands(commands: KeyCommand[]): void;
+```
+
+Registers (or replaces) the full set of active key commands. The previous set is removed before the new one is applied. No-op when the native module is unavailable (Android, Jest).
+
+### `clearKeyCommands()`
+
+```ts
+function clearKeyCommands(): void;
+```
+
+Removes all currently registered key commands. No-op when unsupported.
+
+### `addKeyCommandListener(cb)`
+
+```ts
+function addKeyCommandListener(cb: (id: string) => void): { remove(): void };
+```
+
+Subscribes to key command presses. The callback receives the `id` of the command that fired. Returns an object with a `remove()` method to unsubscribe. When the native module is unavailable, the callback is never called and `remove()` is a no-op.
+
+### `isKeyCommandsSupported()`
+
+```ts
+function isKeyCommandsSupported(): boolean;
+```
+
+Returns `true` on iOS when the native module is loaded, `false` otherwise (Android, Jest). Use this to conditionally render keyboard-shortcut hints.
+
+## Example: a default key map
+
+A full key map defined entirely from JavaScript -- no native rebuild needed when commands change:
+
+```ts
+import { setKeyCommands, addKeyCommandListener } from 'react-native-apple-key-commands';
+import { useEffect } from 'react';
+
+const KEY_MAP = [
+  { id: 'launch',   input: 'return', modifiers: ['command'],        title: 'Launch search'    },
+  { id: 'palette',  input: 'k',      modifiers: ['command'],        title: 'Open palette'     },
+  { id: 'copy',     input: 'c',      modifiers: ['command'],        title: 'Copy query'       },
+  { id: 'dismiss',  input: 'escape', modifiers: [],                 title: 'Dismiss'          },
+  { id: 'engine1',  input: '1',      modifiers: ['option'],         title: 'Engine 1'         },
+  { id: 'engine2',  input: '2',      modifiers: ['option'],         title: 'Engine 2'         },
+  { id: 'engine3',  input: '3',      modifiers: ['option'],         title: 'Engine 3'         },
+  { id: 'engine4',  input: '4',      modifiers: ['option'],         title: 'Engine 4'         },
+  { id: 'engine5',  input: '5',      modifiers: ['option'],         title: 'Engine 5'         },
+  { id: 'engine6',  input: '6',      modifiers: ['option'],         title: 'Engine 6'         },
+  { id: 'engine7',  input: '7',      modifiers: ['option'],         title: 'Engine 7'         },
+  { id: 'engine8',  input: '8',      modifiers: ['option'],         title: 'Engine 8'         },
+];
+
+export function useKeyMap(handlers: Record<string, () => void>) {
+  useEffect(() => {
+    setKeyCommands(KEY_MAP);
+    const sub = addKeyCommandListener(id => handlers[id]?.());
+    return () => { sub.remove(); };
+  }, []);
+}
+```
+
+> **Note:** bare `escape` and `return` (no modifier) may be swallowed by a focused text field. Commands with a `command` modifier fire reliably even while text input is active.
+
+## Platform behavior
+
+| Environment                          | Commands fire | Listener fires |
+| ------------------------------------ | :-----------: | :------------: |
+| iPad with keyboard                   |      yes      |      yes       |
+| iPad app on Mac (Apple silicon)      |      yes      |      yes       |
+| iPhone / no keyboard                 |      no       |       no       |
+| Android                              |      no       |       no       |
+| Jest / no native runtime             |      no       |       no       |
+
+All exports are safe to call on any platform. On non-iOS and when the native module is absent (Jest), `setKeyCommands` and `clearKeyCommands` are no-ops, `addKeyCommandListener` returns a no-op `{ remove() {} }`, and `isKeyCommandsSupported()` returns `false`.
+
+## How it works
+
+When `setKeyCommands` is called, the native module dispatches to the main thread and attaches `UIKeyCommand` objects to the root view controller of the key window (`rootViewController.addKeyCommand`). Each command stores its `id` in `UIKeyCommand.propertyList`.
+
+The first call installs a single action method (`ak_handleKeyCommand:`) on the root view controller class at runtime using `class_addMethod`. Because the method is on the view controller (not a text field), it sits above focused responders in the responder chain -- ⌘-modified commands reach it even while a text field has first responder. When the action fires, the module reads the `id` from `propertyList` and emits an `onKeyCommand` event to JavaScript.
+
+There is no `UIMenuBuilder` involvement and no macOS menu bar integration. The `title` field controls only the discoverbility label shown in the iPad ⌘-hold overlay.
+
+## License
+
+MIT © [Bogdan Georgian Alexa](https://github.com/BogdanGeorgian91)

package/build/index.d.ts

@@ -0,0 +1,21 @@
+export type KeyModifier = 'command' | 'shift' | 'option' | 'control';
+export interface KeyCommand {
+    /** stable id echoed back on press */
+    id: string;
+    /** single char, or: return | escape | space | tab | up | down | left | right */
+    input: string;
+    modifiers?: KeyModifier[];
+    /** shown in the iPad ⌘-hold overlay (no menu bar) */
+    title?: string;
+}
+/** iOS only; false on Android / when the native module is absent (Jest). */
+export declare function isKeyCommandsSupported(): boolean;
+/** Register/replace the active set of key commands. No-op when unsupported. */
+export declare function setKeyCommands(commands: KeyCommand[]): void;
+/** Remove all registered key commands. No-op when unsupported. */
+export declare function clearKeyCommands(): void;
+/** Subscribe to command presses; the callback receives the command id. */
+export declare function addKeyCommandListener(cb: (id: string) => void): {
+    remove(): void;
+};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AACrE,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAC1B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD,4EAA4E;AAC5E,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAE3D;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CAIlF"}

package/build/index.js

@@ -0,0 +1,28 @@
+import { Platform } from 'react-native';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+// In expo-modules-core (Expo 56), a native module that declares `Events(...)` IS an
+// EventEmitter — call `addListener` on it directly. Constructing `new EventEmitter(module)`
+// is the legacy form and types the event name as `never`.
+const Native = Platform.OS === 'ios'
+    ? requireOptionalNativeModule('AppleKeyCommands')
+    : null;
+/** iOS only; false on Android / when the native module is absent (Jest). */
+export function isKeyCommandsSupported() {
+    return !!Native;
+}
+/** Register/replace the active set of key commands. No-op when unsupported. */
+export function setKeyCommands(commands) {
+    Native?.setKeyCommands(commands.map(c => ({ ...c, modifiers: c.modifiers ?? [] })));
+}
+/** Remove all registered key commands. No-op when unsupported. */
+export function clearKeyCommands() {
+    Native?.clearKeyCommands();
+}
+/** Subscribe to command presses; the callback receives the command id. */
+export function addKeyCommandListener(cb) {
+    if (!Native)
+        return { remove() { } };
+    const sub = Native.addListener('onKeyCommand', (e) => cb(e.id));
+    return { remove: () => sub.remove() };
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAahE,oFAAoF;AACpF,4FAA4F;AAC5F,0DAA0D;AAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,KAAK,KAAK;IAClC,CAAC,CAAC,2BAA2B,CAAM,kBAAkB,CAAC;IACtD,CAAC,CAAC,IAAI,CAAC;AAET,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB;IACpC,OAAO,CAAC,CAAC,MAAM,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,QAAsB;IACnD,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAE,gBAAgB,EAAE,CAAC;AAC7B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CAAC,EAAwB;IAC5D,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,KAAI,CAAC,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,cAAc,EAAE,CAAC,CAAiB,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import { Platform } from 'react-native';\nimport { requireOptionalNativeModule } from 'expo-modules-core';\n\nexport type KeyModifier = 'command' | 'shift' | 'option' | 'control';\nexport interface KeyCommand {\n  /** stable id echoed back on press */\n  id: string;\n  /** single char, or: return | escape | space | tab | up | down | left | right */\n  input: string;\n  modifiers?: KeyModifier[];\n  /** shown in the iPad ⌘-hold overlay (no menu bar) */\n  title?: string;\n}\n\n// In expo-modules-core (Expo 56), a native module that declares `Events(...)` IS an\n// EventEmitter — call `addListener` on it directly. Constructing `new EventEmitter(module)`\n// is the legacy form and types the event name as `never`.\nconst Native = Platform.OS === 'ios'\n  ? requireOptionalNativeModule<any>('AppleKeyCommands')\n  : null;\n\n/** iOS only; false on Android / when the native module is absent (Jest). */\nexport function isKeyCommandsSupported(): boolean {\n  return !!Native;\n}\n\n/** Register/replace the active set of key commands. No-op when unsupported. */\nexport function setKeyCommands(commands: KeyCommand[]): void {\n  Native?.setKeyCommands(commands.map(c => ({ ...c, modifiers: c.modifiers ?? [] })));\n}\n\n/** Remove all registered key commands. No-op when unsupported. */\nexport function clearKeyCommands(): void {\n  Native?.clearKeyCommands();\n}\n\n/** Subscribe to command presses; the callback receives the command id. */\nexport function addKeyCommandListener(cb: (id: string) => void): { remove(): void } {\n  if (!Native) return { remove() {} };\n  const sub = Native.addListener('onKeyCommand', (e: { id: string }) => cb(e.id));\n  return { remove: () => sub.remove() };\n}\n"]}

package/expo-module.config.json

@@ -0,0 +1 @@
+{ "platforms": ["apple"], "apple": { "modules": ["AppleKeyCommandsModule"] } }

package/ios/AppleKeyCommands.podspec

@@ -0,0 +1,21 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'AppleKeyCommands'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.4'
+  s.source         = { git: 'https://github.com/BogdanGeorgian91/react-native-apple-key-commands.git' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.source_files = "**/*.swift"
+end

package/ios/AppleKeyCommandsModule.swift

@@ -0,0 +1,80 @@
+import ExpoModulesCore
+import UIKit
+import ObjectiveC.runtime
+
+public class AppleKeyCommandsModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("AppleKeyCommands")
+    Events("onKeyCommand")
+
+    Function("isSupported") { () -> Bool in true } // the iOS module only loads on iOS
+
+    Function("setKeyCommands") { (commands: [[String: Any]]) in
+      DispatchQueue.main.async {
+        KeyCommandCenter.shared.emit = { [weak self] id in self?.sendEvent("onKeyCommand", ["id": id]) }
+        KeyCommandCenter.shared.setCommands(commands)
+      }
+    }
+    Function("clearKeyCommands") {
+      DispatchQueue.main.async { KeyCommandCenter.shared.setCommands([]) }
+    }
+  }
+}
+
+final class KeyCommandCenter: NSObject {
+  static let shared = KeyCommandCenter()
+  var emit: ((String) -> Void)?
+  private weak var hostVC: UIViewController?
+  private var actionInstalled = false
+
+  func setCommands(_ commands: [[String: Any]]) {
+    guard let rootVC = Self.keyWindow()?.rootViewController else { return }
+    installActionIfNeeded(on: rootVC)
+
+    (hostVC?.keyCommands ?? []).forEach { hostVC?.removeKeyCommand($0) }
+    hostVC = rootVC
+    let sel = NSSelectorFromString("ak_handleKeyCommand:")
+    for c in commands {
+      guard let id = c["id"] as? String, let raw = c["input"] as? String else { continue }
+      var mods: UIKeyModifierFlags = []
+      for m in (c["modifiers"] as? [String] ?? []) {
+        switch m {
+        case "command": mods.insert(.command); case "shift": mods.insert(.shift)
+        case "option": mods.insert(.alternate); case "control": mods.insert(.control); default: break
+        }
+      }
+      let cmd = UIKeyCommand(title: (c["title"] as? String) ?? "", image: nil, action: sel,
+                             input: Self.mapInput(raw), modifierFlags: mods, propertyList: id)
+      rootVC.addKeyCommand(cmd)
+    }
+  }
+
+  private func installActionIfNeeded(on vc: UIViewController) {
+    guard !actionInstalled else { return }
+    actionInstalled = true
+    let sel = NSSelectorFromString("ak_handleKeyCommand:")
+    let block: @convention(block) (AnyObject, UIKeyCommand) -> Void = { _, cmd in
+      if let id = cmd.propertyList as? String { KeyCommandCenter.shared.emit?(id) }
+    }
+    let imp = imp_implementationWithBlock(block)
+    class_addMethod(type(of: vc), sel, imp, "v@:@")
+  }
+
+  static func keyWindow() -> UIWindow? {
+    UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+      .flatMap { $0.windows }.first { $0.isKeyWindow } ?? UIApplication.shared.windows.first
+  }
+  static func mapInput(_ raw: String) -> String {
+    switch raw.lowercased() {
+    case "return","enter": return "\r"
+    case "escape","esc": return UIKeyCommand.inputEscape
+    case "space": return " "
+    case "tab": return "\t"
+    case "up": return UIKeyCommand.inputUpArrow
+    case "down": return UIKeyCommand.inputDownArrow
+    case "left": return UIKeyCommand.inputLeftArrow
+    case "right": return UIKeyCommand.inputRightArrow
+    default: return raw
+    }
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "react-native-apple-key-commands",
+  "version": "0.1.0",
+  "description": "Dynamic hardware-keyboard shortcuts (UIKeyCommand) for React Native and Expo. Register key commands from JS and get an event back when one fires. Works on iPad and on iPad apps running on Mac. iOS only. Built with the Expo Modules API.",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module"
+  },
+  "keywords": ["react-native","expo","ios","macos","ipad","keyboard","shortcuts","uikeycommand","key-command","hotkey"],
+  "repository": { "type": "git", "url": "https://github.com/BogdanGeorgian91/react-native-apple-key-commands.git" },
+  "bugs": { "url": "https://github.com/BogdanGeorgian91/react-native-apple-key-commands/issues" },
+  "author": "Bogdan Georgian Alexa <bogdan.georgian370@gmail.com> (https://github.com/BogdanGeorgian91)",
+  "license": "MIT",
+  "homepage": "https://github.com/BogdanGeorgian91/react-native-apple-key-commands#readme",
+  "files": ["build/","ios/","src/","expo-module.config.json"],
+  "dependencies": {},
+  "devDependencies": { "@types/react": "~19.1.1", "expo": "^55.0.3", "expo-module-scripts": "^55.0.2", "react-native": "0.82.1" },
+  "peerDependencies": { "expo": ">=51.0.0", "react-native": ">=0.74.0" }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,11 @@
+import { isKeyCommandsSupported, setKeyCommands, clearKeyCommands, addKeyCommandListener } from '../index';
+
+describe('react-native-apple-key-commands (native module absent)', () => {
+  it('is inert and never throws when unsupported', () => {
+    expect(isKeyCommandsSupported()).toBe(false);
+    expect(() => setKeyCommands([{ id: 'palette', input: 'k', modifiers: ['command'] }])).not.toThrow();
+    expect(() => clearKeyCommands()).not.toThrow();
+    const sub = addKeyCommandListener(() => {});
+    expect(() => sub.remove()).not.toThrow();
+  });
+});

package/src/index.ts

@@ -0,0 +1,42 @@
+import { Platform } from 'react-native';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+
+export type KeyModifier = 'command' | 'shift' | 'option' | 'control';
+export interface KeyCommand {
+  /** stable id echoed back on press */
+  id: string;
+  /** single char, or: return | escape | space | tab | up | down | left | right */
+  input: string;
+  modifiers?: KeyModifier[];
+  /** shown in the iPad ⌘-hold overlay (no menu bar) */
+  title?: string;
+}
+
+// In expo-modules-core (Expo 56), a native module that declares `Events(...)` IS an
+// EventEmitter — call `addListener` on it directly. Constructing `new EventEmitter(module)`
+// is the legacy form and types the event name as `never`.
+const Native = Platform.OS === 'ios'
+  ? requireOptionalNativeModule<any>('AppleKeyCommands')
+  : null;
+
+/** iOS only; false on Android / when the native module is absent (Jest). */
+export function isKeyCommandsSupported(): boolean {
+  return !!Native;
+}
+
+/** Register/replace the active set of key commands. No-op when unsupported. */
+export function setKeyCommands(commands: KeyCommand[]): void {
+  Native?.setKeyCommands(commands.map(c => ({ ...c, modifiers: c.modifiers ?? [] })));
+}
+
+/** Remove all registered key commands. No-op when unsupported. */
+export function clearKeyCommands(): void {
+  Native?.clearKeyCommands();
+}
+
+/** Subscribe to command presses; the callback receives the command id. */
+export function addKeyCommandListener(cb: (id: string) => void): { remove(): void } {
+  if (!Native) return { remove() {} };
+  const sub = Native.addListener('onKeyCommand', (e: { id: string }) => cb(e.id));
+  return { remove: () => sub.remove() };
+}