Look at a redesign of the actions list that comes out of Keyman Core, to:

• normalize the chars + backspaces so that we don't interleave them
• convert into a structure rather than an arbitrary list of actions

Things to consider:

• implementation coordination - how to work with all different consumer engines
• backspace types - char vs marker vs unknown
• eradication of Engine-ownership of cached context (Windows, Linux?)

Proposal

1. Keep the existing interface km_core_state_action_items(), but add a new function km_core_state_get_actions() which returns a single structure, and in which Keyman Engine no longer needs to think about markers at all, because they are maintained within Keyman Core's cached context. When you have finished with the returned structure, free it with km_core_actions_dispose().

   typedef struct {
     // number of codepoints (not codeunits!) to delete from app context, 0+
     int delete_back;
   
     // null-term string of characters to insert into document
     km_core_usv* output;
   
     // list of options to persist, terminated with KM_CORE_OPTIONS_END
     km_core_option_item* persist_options;
   
     // issue a beep
     bool do_alert;
   
     // emit the input keystroke to the application, unmodified?
     bool emit_keystroke;
   
     // -1=unchanged, 0=off, 1=on
     int new_caps_lock_state;
   } km_core_actions;

2. Add a new function km_core_state_context_validate() which does a comparison of the passed-in context from a compliant app to the state's cached context, allowing Core to know if it needs to reset the context. This should replace all the existing context API functions. This should only be used with compliant apps, on every key event, before km_core_process_event() is called.

3. If a mouse click is received on a non-compliant app, then Engine can call km_core_state_context_invalidate() to wipe out any cached context.

Design discussion document

• https://docs.google.com/document/d/13kRnMm_5b2h4ijWzsOfqq963nwnM1RED2WAHmknzOhQ/edit

Benefits

• Simplification of APIs reduces complexity of Engine implementations and centralizes the key context management algorithms
• One source of truth for cached context
• Backspace types - char vs marker vs unknown becomes an internal distinction only in Core

Costs

• Implementation time and coordination of Core changes vs Engine changes. Mitigated by maintenance of existing functions until all consumers have rolled over to the new design.