[inayayousfi]

inayayousfi directed the work and made every decision.
gpt-5.6-sol, running in OpenCode, and Claude Opus 5.5, running in Claude Code, carried inayayousfi's decisions out.

Summary

This branch started as a generic action and event queue. It now also merges main up to 0.18.1 and turns the runtime into an engine that knows nothing about keyboards. The bundled US ISO keyboard is a profile written against that engine, in the shape a Lua config will have.

• Route every event and action through one registered, plain-data queue that only drains on the Qt thread, so keyboard listener callbacks can no longer run handlers on the listener thread.
• Describe profiles as plain data plus functions. A binding fn(state) -> value re-runs only when the state it read changes, and a callback fn(ctx, event) returns actions. State lives in declared, typed variables (see State registry below), and true is not 1.
• Add curated node kinds (window, grid, box, stack, button, label, spacer), attachments by reference (dwell, pointer locator, hot corners, lock-screen panel), observed state (input.*, keyboard.*, windows.*), and explicit effects (keyboard.down/up/tap/type_text, showing, hiding, closing, and moving windows, process.spawn, logging).
• Move keyboard conventions into python_defaults/axidev_osk/std, and the bundled keyboard with its colors and font into python_defaults/default_profile.py, then delete key modes, hooks, state tags, the keyboard grid, and the prompt and permission dialogs from the engine.
• Rewrite AGENTS.md as a map of the engine, the standard library, and profiles, and write each module's behavior in its docstrings. The remaining Lua work is tracked in Define Lua config architecture #8.

Architecture

Everything under src/axidev_osk/ except python_defaults/ is the engine. It owns windows, the queue, central state, platform integration, keyboard output, and process lifecycle, and it holds no layout, legend, latch, or prompt logic. A Lua loader is expected to replace python_defaults/ by producing the same maps and functions, so the engine does not change when Lua arrives.

The default keyboard should behave as before. Quit confirmation, the Linux permission prompts, hot-corner show and hide, Ghost, Dwell, and second-launch activation now come from the profile instead of engine code. SIGTERM still quits without asking, a profile that handles no quit request quits directly, and other quit requests reach the profile with their reason (signal, stdin_closed, or window_closed).

Every window keeps Qt's close rule unless it sets default_close to false: closing it closes it, and closing the last visible window asks to quit. The default keyboard turns the rule off and asks through its own prompt.

Plasma lock-screen panels keep the same supervisor protocol. The profile's secure_input_panel attachment names the window they show, and the panel now answers ERROR when keyboard output cannot start.

State registry

State is now a registry of declared variables. A profile declares each one with axidev_osk.var(type, default). Variables in the root config's state are shared by every profile and survive a profile switch, while a profile's own state resets when that profile starts. Reading or writing a path nobody declared fails, values are checked against their type, and None resets a variable to its default or removes a map entry. Every value field of a node, window, attachment, or theme accepts a binding, so window.set_opacity, window.block_input, window.unblock_input, and dwell.set_enabled are gone.

Profiles also get three generic input primitives. timer.start (id, delay_ms, repeat) and timer.cancel (id) schedule timer.fired events; restarting an ID replaces its timer, and a profile switch drops every timer. Buttons report hover through on_enter and on_leave (button.entered, button.left). Any node can set reports_pointer, and the engine then posts node.pointer_pressed, node.pointer_moved (while pressed) and node.pointer_released with the node and the pointer's x and y, for gestures such as swipes. Buttons lose their active and latched options: how a key looks while down or latched is profile policy, so std.lit sets those style properties from bindings instead. The window chrome stays in the engine, because on Windows a window keeps the operating system's frame and a profile could not replace it there.

Every interaction now reaches the profile as an event, and the engine decides nothing about what it means. button.pressed and button.released carry {node, button}, where button is left, right, middle, back, forward or other; every other mouse button presses a button as the left one does, and node.pointer_pressed and node.pointer_released carry the button too. Dragging a window's title bar or resize grip posts window.dragged or window.resize_dragged with the window and the distance, and a finished dwell posts dwell.completed with the window and the point. The engine no longer moves, resizes or clicks on its own: std.with_handlers maps these events to window.move_by, the new window.resize_by, and the new window.click (left button unless the action names another), so the default profile behaves as before, and a profile can give a right click, a drag or a dwell another meaning, or none. AGENTS.md states this rule, along with which code may call services, what the engine promises on every platform, and that frequent observations are opt-in.

Built-ins are now optional, and AGENTS.md says when a feature belongs in a profile, the standard library, or the engine. Any mouse button drags the title bar and the resize grip and presses the close button, and window.dragged, window.resize_dragged, window.drag_started and window.close_requested name it; std moves and resizes only on the left button. Nodes can opt in to node.pointer_hovered and node.pointer_left (reports_hover), node.wheel (reports_wheel), and node.geometry_changed (report_geometry), which records nodes.<id>.position and nodes.<id>.size. Hot corners can be turned off (enabled) or only report (fires_on_rest), and post hot_corner.entered and hot_corner.left. The pointer locator glows each button in its locator_color, and std.locator computes the old palette from the keys' reported geometry, so all 89 keys keep their colors. Dwell's thresholds and indicator, the hot-corner indicator, and the locator's poll interval are options. Window placement is an anchor, one of 9 names or any x and y, and keep_on_screen can let a floating window leave its screen.

The parity tests changed on purpose with this. Ghost used to send block and opacity actions for the keyboard window. It now sets std.ghosted.keyboard, and the window's opacity and input block follow that flag. Dwell now toggles settings.dwell.enabled, a variable in the root config, instead of the removed dwell.keyboard-dwell.enabled. The layout, key outputs, latches, and the quit, permission, and second-launch flows are checked as before.

Platform changes

• Linux Wayland: each overlay window asks LayerShellQt for a layer surface through LayerShellQt::Window::get, called with ctypes, instead of the app setting QT_WAYLAND_SHELL_INTEGRATION=layer-shell for the whole process. Only overlay windows become layer surfaces, and the "already has a shell integration" warning is gone. The Linux launcher checks that this function exists; without it, the app falls back to the X11 overlay backend.
• All platforms: showing a minimized window restores it. Before, only Windows did that.
• Failed keyboard actions now report action.failed instead of being dropped silently.

Testing

• QT_QPA_PLATFORM=offscreen python -m unittest discover -s tests: 472 passed, 1 skipped on Linux.
• Parity tests compare the default profile with measurements taken from the original keyboard: grid position, span, and minimum size of all 89 keys, all 87 outputs, latching (including the shared left and right latches), Caps Lock, Ghost, Dwell, hot corners, and the quit, permission, and second-launch flows.
• pyright: 0 errors. flake8 --select=F,E9,W6 src: clean.
• Tried on a KDE Plasma Wayland desktop: the keyboard, hot corners, the quit prompt, and shutdown. Wayland protocol logs confirmed that every overlay window gets a layer surface.
• Not yet run on Hyprland, niri, X11, a Windows machine, the Nix package, or the Plasma lock screen.
• The state registry has not been tried on a desktop yet; the KDE Plasma run above predates it.