keymanapp / keymanapp/keyman

spec(web): Keyman Core integration for Web 🎼

Open
#11,293 2 comments 2 reactions 1 assignee Claimed by @ermshiperete View on GitHub
epic-web-core spec web/
Dominant language
Pascal
Stars
534
Forks
143
Avg merge
2d 10h
Merged PRs (30d)
113

Description

## Introduction

Currently _Keyman Core_ is only used on the desktop platforms (Windows, Mac, Linux). _Keyman Core_ supports KMN as well as LDML keyboards.

_Keyman Engine for Web_ has a separate implementation that only supports KMN based keyboards. This is also used by _Keyman for Android_ and _Keyman for iOS_.

_Keyman Engine for Web_ currently doesn't use the .kmx keyboard files but .js files that get generated by `kmc` as well.

_Keyman Core_ doesn't deal with touch and OSK aspects of a keyboard.

LDML keyboards use an enhanced version of KMX (KMX+).

We would like to integrate _Keyman Core_ in _Keyman Engine for Web_.

## Architecture

- _Keyman Core_ API will be accessed through WASM (#13423)
- OSK will continue to be handled by _Keyman Engine for Web_ (#13424)
- _Keyman Engine for Web_ will read a subset of KMX+ for touch layout/OSK (#13429)
- Keyboards in .js format will be deprecated (probably v20?). Instead we use .kmx everywhere (#13439).

## Implementation

### Refactorings/Cleanup in _Keyman Engine for Web_ (#11374)

- move `gesture-recognizer`, `input-processor`, `keyboard-processor` from `common` to `web/src` (do we still need `{input,keyboard}-processor` in the future or will this be replaced by Core?)
- ~~for clarity, rename `KeymanEngine.core` to `KeymanEngine.inputProcessor`~~
- rename `keyboardCache` to `keyboardStore` (and `StubAndKeyboardCache` to `StubAndKeyboardStore`?)

- [x] keymanapp/keyman#11374

#### Additional refactorings

- [x] rename `KeymanEngine` (in `main` module) to `KeymanEngineBase` (#13398/#13404)
- [x] rename `js-processor`'s `OutputTarget` → `OutputTargetBase` and `element-wrappers`' `OutputTarget` → `OutputTargetElementWrapper` (#13406)
- [x] keymanapp/keyman#13438

### Changes required to _Keyman Engine for Web_

- check backspace code - `nothingDeletable` - make sure LDML's return is understood by the K_BKSP fixup code
- probably want a new subclass of `KeyboardHarness` (or `KeyboardInterface`, or in-between) for LDML
- add interface `KeyboardHarness` -> `AbstractKeyboardInterface` -> `KeyboardInterface`
- add new class `CoreKeyboardInterface`
- `KeyboardProcessor` needs to know when to load `CoreKeyboardInterface`
1. set `KeyboardProcessor.activeKeyboard` called by another layer
2. caller will need to be able to load a `.kmx` instead of a `.js`

#### KMX Loader

_Keyman Engine for Web_ will load .kmx files instead of .js. The .kmx loader should detect at load time if first bytes are `KXTS` and treat it as kmx, otherwise ~~`eval()` as a script~~ reject it and it will be loaded by the existing .js loader.

- Onscreen keyboard - and layer ids will need some wrangling.
- setNumericLayer
- should be generic intent stuff

### Changes required to Core API

- core API will need to have a concept of `layerId`

## Keyman Core Web discussion list from 1 Mar 2025 [EB,MD]:

- [x] WASM bindings + .wasm file management
- [x] KMX loading + .kmx file management
- [x] .kmx file lifecycle
- [ ] keymanapp/keyman#13432
- [ ] keymanapp/keyman#13423
- [x] keymanapp/keyman#13392
- [x] keymanapp/keyman#13393
- [x] keymanapp/keyman#13400
- [x] #13926
- [ ] keymanapp/keyman#13424
a) .kvk
b) .keyman-touch-layout
c) LDML keyboard
d) bundling .kvk/.keyman-touch-layout into .kmx (developer)
e) API: providing OSK data from Core to KMW for dynamic generation of KMW format OSK
f) fat finger handling -- cloning current state and multiple calls to processevent
- [ ] keymanapp/keyman#13425
- [x] keymanapp/keyman#13426
- [ ] keymanapp/keyman#13427
- [ ] keymanapp/keyman#13428
- [ ] keymanapp/keyman#13429
- touch keys in .kmx
- touch key identifiers in Core APIs (VK >= 256) --> VKDictionary
- layer switching (start of sentence infrastructure)
- support &kmw_rtl - or query i18n apis for script or character direction
- &kmw_embedcss?, &kmw_embedjs??, &kmw_helpfile?, &kmw_helptext?
- [ ] keymanapp/keyman#13431

### Additional work

- [ ] keymanapp/keyman#13433
- [ ] keymanapp/keyman#13434
- [ ] keymanapp/keyman#13435
- [ ] keymanapp/keyman#13436
- [ ] keymanapp/keyman#13437
- [ ] keymanapp/keyman#13922
- [ ] keymanapp/keyman#13923
- [ ] keymanapp/api.keyman.com#281
- [ ] keymanapp/keyboards#3523

## Related issues and discussions

- [Design discussion](https://docs.google.com/document/d/17r4fDrt8jr1m7VDL2umIL2dcSpjSvLoUC9HXI27AE90/edit?usp=sharing)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.