Type at the window with a real keyboard: the akgl_typing test

xdotool closes the gap that shipped the missing SDL_StartTextInput(). Every
other keyboard test synthesises SDL events, which covers the code downstream
of SDL and cannot cover the code upstream of it -- so the suite stayed green
while the real keyboard was dead.

akgl_typing starts the driver under a pty, waits for the window with xdotool
search --sync, gives it focus, and types a program containing a string literal
and a lower-case one, polling the mirrored stdout for what they print. Verified
by reverting both halves of the text-input fix and watching it fail with the
reported symptom: READY, and nothing after it.

Skips rather than fails without a display, xdotool, script(1) or a window
manager -- none of those means the answer is no. It steals keyboard focus for
about fifteen seconds; AKBASIC_SKIP_INTERACTIVE=1 skips it deliberately.

xdotool and script(1) are documented as optional test dependencies, alongside
what gcovr and python3 already bought.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -28,6 +28,30 @@ ctest --test-dir build-akgl --output-on-failure
 ./build-akgl/basic tests/reference/language/functions.bas
 ```
 
+### Optional tools, and what you lose without them
+
+Everything above works with cmake and a C compiler. Three tools are optional, and each one buys
+a specific test rather than general convenience:
+
+| Tool | Buys | Without it |
+|---|---|---|
+| `xdotool` + `script`(1) | `akgl_typing` — types at a real focused SDL window with a real keyboard | The test reports **Skipped**. Nothing fails |
+| `gcovr` | the `coverage` target and its 90%-of-lines gate | `-DAKBASIC_COVERAGE=ON` will not configure |
+| `python3` | `scripts/mutation_test.py` and the `mutation` target | The target is not created |
+
+**`akgl_typing` is worth installing `xdotool` for.** It is the only test that exercises the path
+a person actually uses — X11 delivers a key press to a focused window, SDL composes it, libakgl
+rings it, the editor echoes it, the interpreter runs it. Every other keyboard test synthesises
+SDL events, which tests the code *downstream* of SDL and cannot test the code upstream of it.
+That gap shipped a bug: the frontend never called `SDL_StartTextInput()`, so SDL emitted no
+text-input events at all, the line editor dropped every keystroke, and the whole suite stayed
+green because it was pushing those events itself.
+
+It needs a real X server and **it steals keyboard focus for about fifteen seconds**. Set
+`AKBASIC_SKIP_INTERACTIVE=1` to skip it while you are using the machine. It skips itself
+automatically when there is no display, no `xdotool`, or no window manager answering — CTest
+reports `Skipped` rather than a failure, because none of those means the answer is no.
+
 There are two workflows. **`.gitea/workflows/ci.yaml`** runs on every push: the suite,
 ASan+UBSan, coverage gated at 90% of lines, and mutation testing over two files. The coverage
 report is uploaded as a `code-coverage` artifact.