keymanapp · keyman-status · Mar 3, 2026 · Mar 3, 2026
diff --git a/developer/19.0/reference/messages/developer-utils.developerutilsmessages.md b/developer/19.0/reference/messages/developer-utils.developerutilsmessages.md
@@ -16,3 +16,4 @@ title: Compiler Messages Reference for @keymanapp/developer-utils
 [KM0100A](km0100a) | `ERROR_InvalidProjectFile` | Project file is not valid: &lt;param&gt;
 [KM0100B](km0100b) | `ERROR_UnsupportedProjectVersion` | Project version &lt;param&gt; is not supported by this version of Keyman Developer\.
 [KM0100C](km0100c) | `ERROR_ProjectFileCouldNotBeRead` | Project file could not be read
+[KM0100D](km0100d) | `ERROR_NotAPackageFile` | Package source file is not a valid \.kps file because it is missing the &lt;Package&gt; root element\.
diff --git a/developer/19.0/reference/messages/km0100d.md b/developer/19.0/reference/messages/km0100d.md
@@ -0,0 +1,11 @@
+---
+title: KM0100D: ERROR_NotAPackageFile
+---
+
+|            |           |
+|------------|---------- |
+| Message    | Package source file is not a valid \.kps file because it is missing the &lt;Package&gt; root element\. |
+| Module     | [developer-utils.DeveloperUtilsMessages](developer-utils.developerutilsmessages) |
+| Identifier | `ERROR_NotAPackageFile` |
+
+
diff --git a/developer/core/19.0/index.md b/developer/core/19.0/index.md
@@ -19,6 +19,7 @@ This is an internal API intended for use only within Keyman Engine.
 * [Options](options)
 * [Processor](processor)
 * [State and Actions](state)
+* [Key Handling](keyhandling)
 * [JSON introspection Schema](json-schema)
 * [Building Keyman Core](building)
 
@@ -122,4 +123,4 @@ Caps Lock.
 [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum"
 [km_core_process_event]: processor#km_core_process_event "km_core_process_event function"
 [km_core_event]: processor#km_core_event "km_core_event function"
-[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
+[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
diff --git a/developer/core/19.0/json-schema.md b/developer/core/19.0/json-schema.md
@@ -4,10 +4,10 @@ title: JSON Introspection Schema
 
 The [`km_core_state_to_json()`](state#km_core_state_to_json) call
 generates a JSON document describing the internal state of the keyboard
-processor, this is the schema describing that document.
+processor. This is the schema describing that document.
 
 **WARNING**: The structure and format of the JSON document is independently
-versioned is not considered part of C API. It is intended solely for use in
+versioned and is not considered part of the C API. It is intended solely for use in
 diagnostics or by development and debugging tools which may need to be aware of
 keyboard processor engine implementation details.
 
@@ -74,4 +74,4 @@ keyboard processor engine implementation details.
     "context": { "$ref": "#/definitions/context" }
   }
 }
-```
+```
diff --git a/developer/core/19.0/keyhandling.md b/developer/core/19.0/keyhandling.md
@@ -0,0 +1,42 @@
+# Key Handling
+
+For each key press the processor will called twice, for the key down event
+as well as for the key up event. Depending on the type of key pressed the
+processor might handle the key itself or pass it on to the application.
+The value of `emit_keystroke` in `km_core_actions` struct tells if the
+processor handled the key (`emit_keystroke=0`) or not (`emit_keystroke=1`).
+It is important that the same value gets set for both key down and key up
+events, otherwise the application might miss some events which then looks
+to the user like keys are stuck.
+
+Usually the processor won't handle any frame keys and let the application
+deal with it. This allows shortcut keys like <kbd>Ctrl</kbd>+<kbd>C</kbd>
+to work. The only exception is the <kbd>Backspace</kbd> key which is
+handled internally if enough context is available. Regular keys will be
+handled by the processor.
+
+Note that there is a difference between CLDR/LDML and KMN keyboards if
+there are no rules/transforms defined for a key: KMN keyboards will
+output the cap value of the key (e.g. pressing <kbd>a</kbd> will output
+`a` if no rule is defined), whereas CLDR/LDML keyboards will suppress
+any output for that key.
+
+The following table lists the state of `km_core_actions.emit_keystroke`
+on return of `km_core_process_event` when the following type of key is
+pressed:
+
+|Type                         |   KeyDown     |  KeyUp   |
+|-----------------------------|---------------|----------|
+|Key with rule                |    FALSE      |  FALSE   |
+|Key w/o rule                 |    FALSE      |  FALSE   |
+|Framekeys:                   |               |          |
+|<kbd>Enter</kbd>             |    TRUE       |  TRUE    |
+|<kbd>Backspace</kbd>¹        |    FALSE      |  FALSE   |
+|<kbd>Backspace</kbd>²        |    TRUE       |  TRUE    |
+|<kbd>Ctrl</kbd>+Key          |    TRUE       |  TRUE    |
+|Modifier key <kbd>Shift</kbd>|    TRUE       |  TRUE    |
+|Modifier key <kbd>Ctrl</kbd> |    TRUE       |  TRUE    |
+|Modifier key <kbd>LAlt</kbd> |    TRUE       |  TRUE    |
+
+1: context available<br/>
+2: without or with empty context
diff --git a/developer/core/19.0/options.md b/developer/core/19.0/options.md
@@ -3,7 +3,7 @@ title: Options - Keyman Core API
 ---
 
 A state’s default options are set from the keyboard at creation time and the
-environment. The Platform layer is then is expected to apply any persisted
+environment. The Platform layer is then expected to apply any persisted
 options it is maintaining.  Options are passed into and out of API functions as
 simple C arrays of [km_core_option_item] terminated with a `KM_CORE_OPTIONS_END`
 sentinel value. A state's options are exposed and manipulatable via the
@@ -281,4 +281,4 @@ km_core_state_options_to_json(km_core_state const *state,
 [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum"
 [km_core_process_event]: processor#km_core_process_event "km_core_process_event function"
 [km_core_event]: processor#km_core_event "km_core_event function"
-[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
+[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
diff --git a/developer/core/19.0/processor.md b/developer/core/19.0/processor.md
@@ -15,8 +15,8 @@ enum km_core_event_flags {
   KM_CORE_EVENT_FLAG_DEFAULT = 0,
   KM_CORE_EVENT_FLAG_TOUCH = 1,
 };
-
 ```
+
 ## Values
 
 `KM_CORE_EVENT_FLAG_DEFAULT`
@@ -195,4 +195,4 @@ enum km_core_event_code {
 [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum"
 [km_core_process_event]: processor#km_core_process_event "km_core_process_event function"
 [km_core_event]: processor#km_core_event "km_core_event function"
-[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
+[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
diff --git a/developer/core/19.0/state.md b/developer/core/19.0/state.md
@@ -15,7 +15,8 @@ owned by the state object.
 
 ## Description
 
-Describes the
+Describes a change to the hardware caps lock indicator state requested by
+Keyman Core to the Platform layer.
 
 ## Specification
 ```c
@@ -50,6 +51,7 @@ This API replaces the Action items APIs, which are now deprecated and will be
 removed in the future.
 
 ## Specification
+
 ```c
 typedef struct {
   unsigned int code_points_to_delete;
@@ -60,8 +62,8 @@ typedef struct {
   km_core_caps_state new_caps_lock_state;
   const km_core_usv* deleted_context;
 } km_core_actions;
-
 ```
+
 ## Members
 
 `code_points_to_delete`
@@ -78,15 +80,17 @@ typedef struct {
 
 `emit_keystroke`
 : Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes.
+  On most platforms this signals whether the processor handled the event
+  (0) or not (1). See also [key handling](keyhandling).
 
 `new_caps_lock_state`
 : -1=unchanged, 0=off, 1=on
 
 `deleted_context`
 : Reference copy of actual UTF32 codepoints deleted from end of context
-  (closest to caret) exactly code_points_to_delete in length (plus null
+  (closest to caret) exactly `code_points_to_delete` in length (plus null
   terminator). Used to determine encoding conversion differences when
-  deleting; only set when using [km_core_state_get_actions], otherwise nullptr.
+  deleting; only set when using [km_core_state_get_actions], otherwise `nullptr`.
 
 -------------------------------------------------------------------------------
 
@@ -282,4 +286,4 @@ An opaque pointer to a state object.
 [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum"
 [km_core_process_event]: processor#km_core_process_event "km_core_process_event function"
 [km_core_event]: processor#km_core_event "km_core_event function"
-[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"
+[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum"