spec(web): Keyman Core integration for Web

[ermshiperete]

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 (feat(web,core): interface between kmw and Keyman Core APIs - keyboard events + context management (incl. context reset) #13423)
• OSK will continue to be handled by Keyman Engine for Web (feat(web,core): On screen keyboard - mobile and desktop #13424)
• Keyman Engine for Web will read a subset of KMX+ for touch layout/OSK (feat(web,core): Support for touch keys in .kmx, .kmx target of web/touch platforms #13429)
• Keyboards in .js format will be deprecated (probably v20?). Instead we use .kmx everywhere (feat(developer): deprecate .js keyboards #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?)

• chore(web): restructure repo #11374

Additional refactorings

• rename KeymanEngine (in main module) to KeymanEngineBase (refactor(web): clean up confusion with three files named KeymanEngine.ts, class named KeymanEngine and aliased to KeymanEngineBase #13398/refactor(web): rename base KeymanEngine to KeymanEngineBase 🎼 #13404)
• rename js-processor's OutputTarget → OutputTargetBase and element-wrappers' OutputTarget → OutputTargetElementWrapper (refactor(web): cleanup OutputTarget class names 🎼 #13406)
• refactor(web): clean up confusion with three files named keyboardInterface.ts, class named KeyboardInterface and aliased to KeyboardInterfaceBase #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]:

• WASM bindings + .wasm file management
• KMX loading + .kmx file management
• .kmx file lifecycle
• feat(core): debug build of WASM should have symbols (e.g. when segfaulting) #13432
• feat(web,core): interface between kmw and Keyman Core APIs - keyboard events + context management (incl. context reset) #13423
  • feat(web): implement getting properties of KMXKeyboard 🎼 #13392
  • feat(core): expose state and event API to WASM 🎼 #13393
  • feat(core): expose context and actions APIs to WASM 🎼 #13400
• feat(web,core): On screen keyboard - mobile and desktop #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
• feat(web,core): Lexical model binding #13425
• feat(web,core): Keyboard options #13426
• feat(web,core): Add platform tests #13427
• feat(web,core): Chirality support (isChiral) #13428
• feat(web,core): Support for touch keys in .kmx, .kmx target of web/touch platforms #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?
• feat(developer): Compiler needs to error on compile targets for &VERSION >= 19.0 #13431

Additional work

• feat(web,core): improve performance + size of WASM binaries #13433
• docs(core): integrator documentation of new Core APIs #13434
• docs(web): integrator documentation of KeymanWeb .kmx file support #13435
• chore(web): theoretical build which excludes all legacy kmw keystroke processing #13436
• refactor(web): Split web worker into separate .js [do this against master] #13437

Related issues and discussions

• Design discussion

[mcdurdin]

The .kmx loader should detect at load time if first bytes are KXTS and treat it as kmx, otherwise eval() as a script.

I don't think we want to do sniffing and eval as script. The pathway for loading a .js keyboard right now is injecting as a <script> element. The new pathway will take a blob from a source tbd and should just reject it if it doesn't start with the KMX magic bytes KXTS.