Armenian KeyBridge

Armenian KeyBridge is an open-source, iPad-only Armenian keyboard focused on attached hardware keyboards. It also provides a native-style touchscreen keyboard, using the Armenian Phonetic (KDWin) mapping throughout.

Important

The touchscreen keyboard uses Apple's supported keyboard-extension API. The hardware path is a public-API workaround, not a system hardware layout, and still requires testing on real iPad models and iPadOS versions.

Highlights

• Exact normal and Shift mappings for all 47 KDWin typing keys.
• Familiar mappings such as 8 → ր, R → ռ, 7 → և, 9 → չ, and 0 → ճ.
• Armenian quotation marks « and », plus ։, ՝, ՛, ՜, and ՞.
• Touch and attached-keyboard input from the same tested mapping source.
• Standard touchscreen globe key for switching keyboards.
• No toolbar, hardware toggle, status banner, network access, analytics, clipboard access, or Full Access permission.
• iPad-only build with a minimum deployment target of iPadOS 17.0.

The complete layout is documented in docs/KDWIN_LAYOUT.md.

How the hardware bridge works

iPadOS keyboard extensions cannot register a custom system hardware-keyboard layout. Armenian KeyBridge instead uses two public Apple APIs while its keyboard extension is active:

1. GCKeyboard reports the physical HID key that was pressed.
2. iPadOS inserts the corresponding U.S.-layout character into the host app.
3. Armenian KeyBridge waits for that exact character to appear at the end of documentContextBeforeInput.
4. Only after an exact, safe match, Armenian KeyBridge deletes that character and inserts the mapped Armenian output through UITextDocumentProxy.

The bridge never deletes text when the expected suffix is absent. It retries briefly for editors that publish context asynchronously, then fails closed and leaves the original character untouched. It performs no polling while idle.

See docs/HARDWARE_KEYBOARD_BRIDGE.md for the full architecture, safety invariants, performance characteristics, and known limitations.

Compatibility

• iPad only; iPhone and Mac Catalyst are intentionally disabled.
• Minimum iPadOS: 17.0.
• Compiles against the iOS/iPadOS 26.5 SDK with Xcode 26.6.
• The underlying GCKeyboard API exists on earlier systems, but this project is configured and tested only for iPadOS 17 or newer.

The hardware bridge requires:

• An attached hardware keyboard.
• The iPad hardware layout set to U.S..
• Հայերեն • KDWin selected and kept active while typing Armenian.
• A normal text field in an app that permits third-party keyboards and exposes surrounding text through UITextDocumentProxy.

Secure fields and apps that reject third-party keyboards fall back to Apple's keyboard. The Simulator is useful for the touch UI, but is not authoritative for attached-keyboard behavior.

Build and install

1. Install Xcode and its current iOS platform component.
2. Open ArmenianKeyBridge.xcodeproj.
3. Choose the same development team under Signing & Capabilities for the ArmenianKeyBridge and ArmenianKeyBridgeKeyboard targets.
4. Select an iPad destination and run the ArmenianKeyBridge scheme.
5. On the iPad, open Settings › General › Keyboard › Keyboards › Add New Keyboard and choose Հայերեն • KDWin.
6. Leave Allow Full Access disabled.

With a free Personal Team, development provisioning normally needs to be renewed periodically by running the project from Xcode again.

Physical keyboard setup

1. Set the attached keyboard's English hardware layout to U.S..
2. With the hardware keyboard connected, tap the keyboard or language control in iPadOS's Shortcuts bar, then tap Show Keyboard.
3. Touch and hold the onscreen Globe key, then select Հայերեն • KDWin.
4. Keep Armenian KeyBridge selected while typing Armenian. Its touch surface automatically collapses while a hardware keyboard is detected.

iPadOS does not register third-party keyboard extensions as hardware input sources. The hardware Globe key and Control–Space therefore cannot select Armenian KeyBridge. If you switch away from it, repeat steps 2 and 3 to return.

Verification

The shared Swift package contains tests for every normal and shifted KDWin key, the complete Armenian alphabet, touch-page coverage, and hardware modifier translation.

cd Core
swift test
swift run ArmenianKeyBridgeLayoutVerifier

The current suite executes four tests with 94 key-map comparisons. The iOS app and extension also pass a strict iOS 17+ type-check with compiler warnings treated as errors. Real-iPad testing remains required for the hardware bridge.

Project structure

• App/ — minimal setup and test app.
• KeyboardExtension/ — touch keyboard and physical-keyboard bridge.
• Core/ — shared KDWin mapping, verifier, and unit tests.
• docs/ — layout and hardware-workaround documentation.
• project.yml — XcodeGen source; the generated Xcode project is committed for contributors who do not use XcodeGen.

Privacy and security

Armenian KeyBridge requests no Full Access, has no network code, and does not persist or log typed text. The hardware bridge only examines the limited context made available by the active text field and only to confirm the character it is about to replace.

Contributing

See CONTRIBUTING.md. Changes to the hardware bridge must preserve the fail-closed deletion rule and changes to the layout must include updated mapping tests.

Acknowledgements

The KDWin compatibility mapping was independently checked against Vahe Evoyan's Armenian Phonetic keyboard layout. That external layout is a reference only and is not bundled with Armenian KeyBridge.

License

Armenian KeyBridge is available under the MIT License.