Merge pull request #2326 from keymanapp/docs/windows/2061/non-compliant-apps

docs(windows): describe windows compliant app implementation with sequence diagram

Author: rc-swag

knowledge-base/assets/kb0118/windows-compliant-app-sequence.mmd

@@ -0,0 +1,26 @@
+sequenceDiagram
+    autonumber
+    participant User as User
+    participant OS as Windows OS
+    participant TSF as TSF Manager
+    participant Keyman as Keyman TIP
+    participant App as Application (Compliant)
+
+    User->>OS: Press key (e.g. 'D')
+    OS->>TSF: Deliver key event
+    TSF->>Keyman: Call OnKeyDown(ITfContext)
+
+    Note right of Keyman: Keyman create TIPEditSession & requests context
+    Keyman->>TSF: ITfContext.GetStatus()
+    Keyman->>TSF: ITfContext.GetSelection()
+    TSF->>App: Request current selection
+    App-->>TSF: Return selection
+    TSF-->>Keyman: Return GetSelection
+
+
+    Note right of Keyman: Keyman applies keyboard rules and inserts or modifies the text in the selection
+
+    Keyman->>TSF: ITfContext.SetSelection()
+    TSF->>App: Modified selection is applied to the application
+
+    App-->>User: Display “∆” in document

knowledge-base/assets/kb0118/windows-compliant-app-sequence.png

@@ -223,4 +223,30 @@ on the Keyman system service which emits a fake key event. That way it is possib
 
 ## Compliance on Windows
 
-TODO
+On Windows, Keyman integrates with applications primarily through the Text Services Framework (TSF). Keyman implements a Text Input Processor (TIP) that communicates with the TSF manager and the target application.
+
+When the user types, the TSF manager passes key events and text context to Keyman through the `ITfContext` interface, which provides access to the current edit context within the application. Keyman relies on this interface to retrieve context, as a selection object, and insert or replace text.
+For `ITfContext` details see [Learn Microsoft](https://learn.microsoft.com/en-us/windows/win32/api/msctf/nn-msctf-itfcontext).
+
+Relevant for Keyman are the following API functions:
+
+**`GetStatus()`** — Retrieves the current status of the text context. Keyman uses this to check for the `TF_SS_TRANSITORY` flag, which indicates temporary or non-standard contexts that may not behave consistently.
+
+**`GetSelection()`** — Used by Keyman for Windows to get the context next to the cursor.
+
+**`SetSelection()`** — Updates the current selection or caret position after Keyman inserts or replaces text in the selection retrieved with `GetSelection()`.
+
+
+Keyman determines whether an application is compliant by inspecting the status returned by `ITfContext::GetStatus()`. Compliant applications provide a stable, non-transitory context and correctly implement the TSF APIs needed to retrieve context and modify text.
+
+Applications can restrict how much surrounding text can be read; Keyman limits its requests to 64 characters of context.
+
+<img src="./assets/kb0118/windows-compliant-app-sequence.png" width="75%" alt="compliant sequence on Windows"/>
+
+The sequence diagram is for a rule that replaces "D" with "∆". 
+ 
+### Non-compliance on Windows
+
+If the `TF_SS_TRANSITORY` flag is present or context cannot be read as expected, Keyman treats the application as **non-compliant** and falls back to legacy behavior, maintaining its own internal context buffer and simulating text operations where possible.
+
+The limitations are as stated at the start of this knowledge base article [Working around non-compliant behavior](##-working-around-non-compliant-behavior). Further reading on sending a backspace to an application to perform a delete can be found on the Keyman wiki [here](https://github.com/keymanapp/keyman/wiki/Backspace-and-cluster-deletion).