fix(windows): UTF-8 console + self-sufficient validation wrapper

Make the suite run cleanly on Windows.

Product code:
- __init__.py: force UTF-8 on stdout/stderr. The Windows console code
  page (cp1252) cannot encode the box-drawing/accented characters the
  runner prints, which crashed the parent capture_stdout thread. Only
  the stream encoders are reconfigured; the locale default used to read
  cp1252 config files is left untouched.
- report_export_junit/html: open the report file with encoding="utf-8"
  (XML/HTML are UTF-8) instead of the platform default, matching the
  txt/json exporters.

Validation:
- run.bat: source mode now sets up its own venv and runs testium from
  src\ directly instead of delegating to the project run.bat (which
  launches the GUI and drops its arguments). Installs the fake_exporter
  entry-point plugin (report_plugin) and the [lsp] extra, and runs the
  same lsp_check.py pre-flight as run.sh.
- jsonrpc/test.tum: launch the echo server via "$(python_bin)" instead
  of "python3" (the Microsoft Store stub on Windows).
- post_execution.py: write the JUnit XML with encoding="utf-8".
- restore items/run/sub_pass.tum and sub_fail.tum, deleted by mistake in
  d97d00c "removed test logs".

.gitignore

@@ -8,6 +8,8 @@ dist
 /.vscode
 .venv/
 .flatpak-builder/
+package/flatpak/repo/
+package/flatpak/*.flatpak
 crash.tx*
 report_test.tx*
 *.autosave
@@ -24,6 +26,7 @@ package/appimage/*.AppImage
 package/appimage/src
 package/appimage/*.py
 AppDir
+*.squashfs
 doc/manual/doxygen
 doc/manual/sphinx/build/*
 doc/manual/sphinx/source/_build/*

CLAUDE.md

@@ -1,250 +0,0 @@
-# Testium — Claude Context
-
-## What is testium
-
-Testium is a test sequencer/runner written in Python. It executes YAML-based test scripts ("`.tum`" files) and supports two execution modes:
-
-- **GUI mode** (default, no flag): PySide6 Qt application (`src/testium/main_win/`)
-- **Batch mode** (`-b` / `--batch-execution`): headless, non-interactive, runs tests and exits
-
-Run from repo root: `./run.sh` (Linux) or `run.bat` / `run.ps1` (Windows).  
-Direct invocation: `python3 -m src/testium [-b] <test_file.tum>`
-
-## Architecture
-
-### Entry point
-`src/testium/__init__.py` — parses CLI args, dispatches to the two modes.  
-`multiprocessing.set_start_method('spawn')` is called early (required for Linux dialog subprocesses).
-
-### Core execution
-- `src/testium/interpreter/process.py` — `TestProcess(multiprocessing.Process)`: runs the test in a child process. Stdout is redirected via a `StringQueue` → pipe → parent thread (`capture_stdout`) that writes to real stdout.
-- `src/testium/interpreter/batch.py` — `Batch`: parent-side orchestrator for `-b` mode. Creates the `msg_queue`, starts `TestProcess`, waits for the "finished" signal.
-- `src/testium/interpreter/test_set.py` — `TestSet`: builds and executes the tree of test items.
-- `src/testium/interpreter/test_items/test_item*.py` — one file per test item type (check, cycle, group, let, unittest, py_func, lua_func, console, git, dialogs, report, parallel, …).
-
-### Communication channels (parent ↔ child process)
-- `msg_queue` (`multiprocessing.Queue`): carries status messages from child to parent.
-  - Item status: `{"id": <non-None>, "name": ..., "status": "started"|"finished", ...}`
-  - Global dict updates: `{"type": "gd_update"|"gd_delete", "key": ..., "value": ...}` — **no "id" key**
-  - Process finished: `{"id": None, "name": "test_process", "status": "finished"}` — id key present but `None`
-- `tst_ctrl` (`TestSetController`): sends control commands (execute, stop, pause, close, …) from parent to child.
-- stdout pipe (`multiprocessing.Pipe`): streams test output from child back to parent's `capture_stdout` thread.
-
-### Stdout pipeline (batch mode)
-```
-test item print()
-  → sys.stdout (StringQueue, in child)
-  → send_stdout thread (child) → pipe → capture_stdout thread (parent)
-  → print() → sys.stdout (TermLog wrapping real stdout, in parent)
-  → terminal
-```
-
-### Global dictionary
-`src/testium/interpreter/utils/globdict.py` — shared state accessible from test scripts via `tm.gd()` / `tm.setgd()`. When `set_update_queue()` is active (during test execution), every `setgd`/`delgd` on a non-`_`-prefixed key pushes a message to `msg_queue`.
-
-### Coloring (`-o` disables it)
-`src/testium/interpreter/utils/termlog.py` — `TermLog` wraps stdout with colorama-based line coloring (PASS=green, FAIL=red, WARN=yellow, …). Applied in parent process for batch mode. Auto-detects light/dark terminal background via (in order): `COLORFGBG` env var, OSC 11 query, default dark.
-
-### Dialog items in batch mode
-All dialog items (`dialog_image`, `dialog_question`, `dialog_references`, `dialog_value`, `dialog_message`, `dialog_choices`, `dialog_note`) follow this rule in non-interactive text mode (`-b`):
-- `auto_result` defined in the `.tum` → result controlled by it (`ok`/`yes` → SUCCESS, `cancel`/`no` → FAIL)
-- `auto_result` absent → FAIL with `"Dialog not supported in batch mode"`
-- `sleep dialog: true` → exception: just sleeps normally, no GUI, no failure
-
-`auto_result` (and `auto_value` for value/note dialogs) is intended for the validation test suite (`test/validation/`) only.
-
-### `parallel` item
-`src/testium/interpreter/test_items/test_item_parallel.py` — runs multiple branches concurrently.
-
-```yaml
-- parallel:
-    name: My parallel block
-    sync: all        # all: wait for all; any: stop as soon as one finishes
-    no_fail: true    # (optional) don't propagate branch failures to parent
-    branches:
-      - name: Branch A
-        wait_for:              # (optional) poll condition before starting
-          condition: <| expr |>
-          timeout: 10
-        steps:
-          - ...
-      - name: Branch B
-        steps:
-          - ...
-```
-
-- `TestItemParallel(TestItemContainer)`: mutates `dict_item["steps"]` to inject synthetic `parallel_branch` items so `load_test_recursively` loads branches normally as children.
-- `TestItemParallelBranch(TestItemContainer)`: container for one branch. `wait_for` polls every 0.1s up to `timeout` seconds before running steps.
-- `sync: any` calls `_stop_branch_recursively()` on all other branches when one *actually runs* (SUCCESS/FAILURE). A `NORUN` branch (disabled, condition not met) never wins the race.
-- Each branch runs in a daemon thread; the parent waits with `.join()`.
-- Branches stopped late (e.g. user disabled them in the GUI, or another sync:any branch already won) go through the normal `branch.stop() + branch.execute()` path so they always produce a clean DB entry via `addTest()`.
-- Exceptions raised in a branch's `execute()` are caught by `run_branch`, logged to stdout, and converted to a `FAILURE` result so they never disappear silently.
-- `sync: all` ignores `NORUN` branches when computing success (matches Group/Cycle semantics): only an actual `FAILURE` fails the parallel.
-- `TestItemSleep` is interruptible (polls `self._is_stopped` in a loop) so `sync: any` can stop slow branches quickly. `py_func` and `console` items are not interruptible; their full duration is observed before the branch returns.
-
-### `TestItemContainer` base class
-`src/testium/interpreter/test_items/test_item_container.py` — shared base for Group, Cycle, Parallel, and ParallelBranch. Provides `_run_children_sequentially()` which handles stop-on-failure, `executedOnStop` items, and returns `(TestResult, stopped_bool)`.
-
-### Report threading
-`src/testium/interpreter/test_report/test_report.py` — SQLite report with thread-safe writes:
-- `sqlite3.connect(..., check_same_thread=False)`
-- `self._lock = threading.Lock()` guards the SQLite `INSERT` only.
-- Per-item log capture (`stdio_redir.read()`) is naturally race-free thanks to per-thread buffers (see `StdoutProxy`).
-
-### Thread-aware stdout (`StdoutProxy`)
-`src/testium/runtime/stdout_redirect.py` — when `log_stored: True`, `intercept()` installs a `StdoutProxy` as `sys.stdout`/`sys.stderr` instead of a single shared `StringQueue`. The proxy:
-- Holds one `StringQueue` per thread (registered via `register_thread(buffer=...)`). The main thread uses a default buffer; each parallel branch's thread registers its own at start and unregisters at end. `stdio_redir.read()` reads the calling thread's buffer → `addTest()` of an item running in branch X reads X's clean, non-interleaved output.
-- For the live stream (terminal in batch / GUI panel), prefixes every line emitted from a branch's thread with `[<branch_name>] ` so concurrent branches stay readable.
-- Exposes `write` / `writeln` / `flush` (Python 3.14's `unittest` calls `stream.writeln()` directly without `_WritelnDecorator`).
-
-### Subprocess API contract (py_func / lua_func)
-
-User test scripts running inside a `py_func` or `lua_func` subprocess **must** use the JSON-RPC bridge to interact with testium state:
-
-- Python: `import py_func.tm as tm` — auto-generates wrappers for every function in `runtime/api.py:SUPPORTED_API`. `tm.gd`/`tm.setgd`/`tm.delgd` go through JSON-RPC to the parent.
-- Lua: `local tm = require("tm")` — same idea on the Lua side.
-
-`api.testium` is the *main-process* implementation; it is **not** exposed to subprocesses by design (not bundled in PyInstaller, not on the subprocess `PYTHONPATH` in pip-installed mode either when isolation is preserved). An import attempt from a subprocess script is a code smell and is detected by `test/validation/items/isolation/`.
-
-To add a new API call usable from subprocesses:
-1. Add the function to `api/testium.py`
-2. Add its name to `SUPPORTED_API` in `runtime/api.py`
-3. It is auto-exposed via JSON-RPC by `interpreter/utils/api_srv.py` and auto-wrapped by `py_func/tm.py:_make_api`
-
-### External interpreter resolution (`bins.py`)
-`src/testium/interpreter/utils/bins.py` — single source of truth for the paths to the external Python and Lua interpreters used by subprocesses.
-
-- `python_bin()` / `lua_bin()` : resolve once, cache in memory. User can override via the `python_bin` / `lua_bin` global dict keys (typically populated from the YAML config). Falls back to discovery on PATH (candidates: `python3`/`python` and `lua`/`lua5.5`/`lua5.4`/`lua5.3`/`lua5.2`/`lua5.1`).
-- `ensure(*names)` : called by `TestSet._validate_runtime_deps()` at test load. Always requires `python` (the eval engine always runs); requires `lua` only if a `lua_func` item is in the tree. Fails fast with a clear error citing tried candidates and override key.
-
-Engines (`PyProcessBase`, `LuaProcessBase`, `EvalExecEngine`) call `bins.python_bin()`/`bins.lua_bin()` themselves — call sites never pass an explicit binary path.
-
-## Key files
-
-| Path | Role |
-|------|------|
-| `src/testium/__init__.py` | CLI entry, mode dispatch |
-| `src/testium/interpreter/batch.py` | `-b` mode orchestrator |
-| `src/testium/interpreter/process.py` | Child test process |
-| `src/testium/interpreter/test_set.py` | Test tree builder/executor |
-| `src/testium/interpreter/test_items/test_item_container.py` | Base class for container items |
-| `src/testium/interpreter/test_items/test_item_parallel.py` | `parallel` and `parallel_branch` items |
-| `src/testium/interpreter/utils/globdict.py` | Global variable dict |
-| `src/testium/interpreter/utils/termlog.py` | Terminal color output |
-| `src/testium/runtime/stdout_redirect.py` | `StdioRedirect` singleton (`stdio_redir`) |
-| `src/testium/runtime/string_queue.py` | Thread-safe string buffer used for stdout redirection |
-| `src/testium/api/testium.py` | Public API for test scripts (`tm.*`) |
-| `src/testium/py_func/` | Python subprocess for `py_func` items (sandboxed: imports only `runtime/` and `py_func/`) |
-| `src/testium/lua_func/` | Lua subprocess scripts for `lua_func` items |
-
-## Package layout
-
-The whole project is a single Python package under `src/testium/`:
-
-```
-src/testium/
-├── __init__.py / __main__.py
-├── runtime/      internal plumbing (jrpc, stdout_redirect, string_queue, tum_except, api)
-├── api/          public SDK exposed to test scripts (`import api.testium as tm`)
-├── interpreter/  test execution engine (NOT visible to py_func/lua_func)
-├── main_win/     GUI (NOT visible to py_func/lua_func)
-├── py_func/      subprocess code for python_func items
-└── lua_func/     subprocess scripts for lua_func items (data files)
-```
-
-`subproc_path()` and `testium_path()` both return the package directory. The py_func subprocess is launched with cwd=that directory and `python3 py_func`. The contract that `py_func/` and `lua_func/` only depend on `runtime/` (no `interpreter`, `main_win`, `api`, `testium`) is enforced by `test/validation/items/isolation/`.
-
-## GUI icons (main_win)
-
-Icons live in `src/testium/main_win/resources/` with three theme variants:
-
-| Folder | Theme index | Usage |
-|--------|-------------|-------|
-| `color/` | 0 (default) | Coloured icons |
-| `black/` | 1 | Black silhouette on transparent |
-| `white/` | 2 | White silhouette on transparent (LA mode) |
-
-Icons are **64×64 PNG**. Black variants: RGBA with RGB=`(0,0,0)`, alpha varies. White variants: LA with luminance=`255`, alpha varies.
-
-The mapping item-type → icon filename is in `_ITEM_CONFIG` (`src/testium/main_win/test_tree_items/test_tree_item.py`). At runtime, `icon_prefix()` returns `:/color`, `:/black`, or `:/white` (Qt resource prefix) based on the user preference.
-
-All icons must be declared in `src/testium/main_win/resources/testium_core_win.qrc` (one entry per theme section). After any QRC change, regenerate the compiled resource file:
-```
-cd src/testium/main_win/resources
-pyside6-rcc testium_core_win.qrc -o testium_core_win_rc.py
-```
-
-Icons are assigned once when the test file is loaded (not updated live on theme change — a file reload is required).
-
-### `run` item
-`src/testium/interpreter/test_items/test_item_run.py` — launches a `.tum` file in a new testium instance (`-b` in batch mode, `-r` in GUI mode). Result:
-- **PASS** if the sub-instance launched and ran to completion (exit code is ignored)
-- **FAIL** if the file is not found, `wait_for_exec` is set without `start_time`/`end_time`, the time window was not reached, or any other launch error
-
-The sub-test's own pass/fail result is intentionally not propagated.
-
-### Report exporters & plugins
-`src/testium/interpreter/test_report/test_report.py` — `_EXPORTER_REGISTRY` dict maps a format name (cmd key in the YAML `report.export`) to a lazy loader. Built-ins: `text`, `json`, `junit` (needs `junit_xml`), `html` (needs `lxml`). `sqlite` is the storage layer, no-op as an export.
-
-Third-party plugins are discovered at module import via `importlib.metadata.entry_points(group="testium.exporters")` — installing a wheel that declares such an entry point is enough, no testium config change needed:
-```toml
-[project.entry-points."testium.exporters"]
-my_format = "my_pkg:MyExporter"
-```
-Exporter contract: `__init__(self, name, con, path, pats, keys, no_header=False)` — the class does its work in `__init__` and writes to `path`.
-
-Behaviour on errors:
-- Unknown format → info line `[report] Export skipped: format "X" not found. Available: ...`, run continues.
-- Optional dependency missing → same info line with a pip-install hint, run continues.
-
-A real-world test plugin lives at `test/validation/fake_exporter/` (CSV exporter, auto-installed by `scripts/build_env.sh` and exercised by `test/validation/items/report_plugin/`).
-
-## Packaging
-
-Three distribution channels coexist, sharing the single `src/testium/` package:
-
-| Channel | Where | Notes |
-|---------|-------|-------|
-| Wheel (`pip install`) | `src/pyproject.toml` | Vanilla Python package; entry point `testium = "testium:main"` |
-| PyInstaller binary | `package/pyinstaller/` | Single ~130 MB binary. `py_func`, `runtime`, `lua_func` bundled at `_MEIPASS` root so the **host** Python can find them when launched as `python3 py_func`. `api`/`interpreter` are **not** exposed (subprocess isolation). |
-| Flatpak | `package/flatpak/` | (Existing recipe, not actively maintained in current refactor wave.) |
-
-The `.deb` work-in-progress lives in `package/deb/`:
-- `test_distro.sh debian:bookworm | debian:trixie | ubuntu:24.04` spins up a Docker/Podman container, reports system package availability, falls back to pip for what's missing (`pyside6` on bookworm/ubuntu, `telnetlib3`, `junit_xml`), runs the validation suite. Currently green on the three targets.
-
-## Recent fixes / notable changes
-- Restructure: single `src/testium/` Python package (was 4 sibling top-levels: `testium`, `lib`, `py_func`, `lua_func`). `lib/` → `runtime/`, `libs/` → `api/`. `pip install` now produces a clean `site-packages/testium/` with no top-level pollution; `.lua` files travel via `package_data`.
-- `bins.py`: centralised resolution + cache of external `python3` / `lua` binaries. Replaces the scattered `tm.gd("python_bin")`/`tm.gd("lua_bin")` dance and the duplicated discovery logic in `py_process.py`/`lua_process.py`. Validates at test load via `TestSet._validate_runtime_deps()` so missing interpreters fail fast.
-- Subprocess API contract: user scripts in `py_func`/`lua_func` use the JSON-RPC bridge (`py_func.tm` / Lua `tm`) — never `api.testium` / `interpreter.*` directly. `SUPPORTED_API` extended with `OS`, `get_main_dir`, `init_timestamp`, `timestamp`, `timestamp_as_sec` so subprocess scripts have the same surface as main-process code.
-- Report exporter plugin registry (`test_report.py`): `_EXPORTER_REGISTRY` + `entry_points("testium.exporters")` discovery. Missing format → info line, run continues.
-- About dialog rework: `QVBoxLayout` (resizable), version + dirty/branch info in a `QLabel` (auto-sized), copyright + clickable EUPL-1.2 link.
-- `test_ctrl.control()`: drain stale responses (left over from polled `loaded()` after `clear()` race) instead of failing on a wrong cmd key — fixes a "Unexpected return error in test set controller" seen in GUI mode after a fast reload.
-- `lua_process.py`: stderr no longer DEVNULL'd so actual Lua errors (missing `cjson`/`socket`) surface instead of "Connection refused".
-- `run_post_exec`: failure message uses `print_warn` (was `print_debug` — silent in non-debug runs).
-- Python 3.11 compat: replaced PEP 701 nested-quote f-strings (e.g. `f"... {d["k"]} ..."`) with single-quote inner strings or string concatenation.
-- `parallel` item: new item with `sync: all|any`, `wait_for`, daemon threads, `_stop_branch_recursively()`. Each branch thread registers a per-thread stdout buffer.
-- `parallel_branch` icon: distinct single-arrow icon (`parallel_branch.png`).
-- `parallel` F1 panel: `steps` stripped from each branch dict.
-- `test_item_container.py`: shared base class extracted from Group/Cycle.
-- `test_item_sleep.py`: interruptible loop so `sync: any` can stop slow branches quickly.
-- `stdout_redirect.py`: `StdoutProxy` (thread-aware buffers + branch-prefixed live output, `writeln()` for Python 3.14 unittest).
-- `test_report.py`: thread-safe SQLite INSERT for parallel branch concurrency.
-- `terminal.py`: deleted — `-m`/`--terminal` mode removed.
-- `batch.py`: premature finish bug on `gd_update` (no `"id"` key) — fix uses `"id" in m and m["id"] is None`.
-- `batch.py`: `control("loaded")` deadlock on TestProcess crash — fix uses daemon thread + `threading.Event` + `is_alive()` polling.
-- `termlog.py`: light/dark terminal auto-detection (`COLORFGBG`, OSC 11) + write residue bug.
-- Dialog items: `auto_result`/`auto_value` for non-interactive text mode; dialogs without `auto_result` FAIL immediately in batch.
-- `run` item: renamed `tum_fime` → `tum`; removed `stdout=PIPE` deadlock; PASS on any completed subprocess.
-- `unittest` item: renamed from `unittest_file`.
-- GUI test tree: check and fold state preserved across same-file reloads.
-- Licence: EUPL-1.2.
-
-## Validation tests
-Located in `test/validation/`. Run with `-b` flag:
-```
-./run.sh -b -- test/validation/main.tum
-```
-Parallel item tests: `test/validation/items/parallel/test.tum`
-
-## Dependencies
-See `src/requirements.txt`. Key ones: `pyside6`, `pyyaml`, `jinja2`, `colorama`, `gitpython`, `pexpect`, `matplotlib`.

DESIGN.md

@@ -0,0 +1,329 @@
+# Testium — Design Context
+
+## What is testium
+
+Testium is a test sequencer/runner written in Python. It executes YAML-based test scripts ("`.tum`" files) and supports two execution modes:
+
+- **GUI mode** (default, no flag): PySide6 Qt application (`src/testium/main_win/`)
+- **Batch mode** (`-b` / `--batch-execution`): headless, non-interactive, runs tests and exits
+
+Run from repo root: `./run.sh` (Linux) or `run.bat` / `run.ps1` (Windows).  
+Direct invocation: `python3 -m src/testium [-b] <test_file.tum>`
+
+## Architecture
+
+### Entry point
+`src/testium/__init__.py` — parses CLI args, dispatches to the two modes.  
+`multiprocessing.set_start_method('spawn')` is called early (required for Linux dialog subprocesses).
+
+### Core execution
+- `src/testium/interpreter/process.py` — `TestProcess(multiprocessing.Process)`: runs the test in a child process. Stdout is redirected via a `StringQueue` → pipe → parent thread (`capture_stdout`) that writes to real stdout.
+- `src/testium/interpreter/batch.py` — `Batch`: parent-side orchestrator for `-b` mode. Creates the `msg_queue`, starts `TestProcess`, waits for the "finished" signal.
+- `src/testium/interpreter/test_set.py` — `TestSet`: builds and executes the tree of test items.
+- `src/testium/interpreter/test_items/test_item*.py` — one file per test item type (check, cycle, group, let, unittest, py_func, lua_func, console, git, dialogs, report, parallel, …).
+
+### Communication channels (parent ↔ child process)
+- `msg_queue` (`multiprocessing.Queue`): carries status messages from child to parent.
+  - Item status: `{"id": <non-None>, "name": ..., "status": "started"|"finished", ...}`
+  - Global dict updates: `{"type": "gd_update"|"gd_delete", "key": ..., "value": ...}` — **no "id" key**
+  - Process finished: `{"id": None, "name": "test_process", "status": "finished"}` — id key present but `None`
+- `tst_ctrl` (`TestSetController`): sends control commands (execute, stop, pause, close, …) from parent to child.
+- stdout pipe (`multiprocessing.Pipe`): streams test output from child back to parent's `capture_stdout` thread.
+
+### Stdout pipeline (batch mode)
+```
+test item print()
+  → sys.stdout (StringQueue, in child)
+  → send_stdout thread (child) → pipe → capture_stdout thread (parent)
+  → print() → sys.stdout (TermLog wrapping real stdout, in parent)
+  → terminal
+```
+
+### Global dictionary
+`src/testium/interpreter/utils/globdict.py` — shared state accessible from test scripts via `tm.gd()` / `tm.setgd()`. When `set_update_queue()` is active (during test execution), every `setgd`/`delgd` on a non-`_`-prefixed key pushes a message to `msg_queue`.
+
+### Coloring (`-o` disables it)
+`src/testium/interpreter/utils/termlog.py` — `TermLog` wraps stdout with colorama-based line coloring (PASS=green, FAIL=red, WARN=yellow, …). Applied in parent process for batch mode. Auto-detects light/dark terminal background via (in order): `COLORFGBG` env var, OSC 11 query, default dark.
+
+### Dialog items in batch mode
+All dialog items (`dialog_image`, `dialog_question`, `dialog_references`, `dialog_value`, `dialog_message`, `dialog_choices`, `dialog_note`) follow this rule in non-interactive text mode (`-b`):
+- `auto_result` defined in the `.tum` → result controlled by it (`ok`/`yes` → SUCCESS, `cancel`/`no` → FAIL)
+- `auto_result` absent → FAIL with `"Dialog not supported in batch mode"`
+- `sleep dialog: true` → exception: just sleeps normally, no GUI, no failure
+
+`auto_result` (and `auto_value` for value/note dialogs) is intended for the validation test suite (`test/validation/`) only.
+
+### `parallel` item
+`src/testium/interpreter/test_items/test_item_parallel.py` — runs multiple branches concurrently.
+
+```yaml
+- parallel:
+    name: My parallel block
+    sync: all        # all: wait for all; any: stop as soon as one finishes
+    no_fail: true    # (optional) don't propagate branch failures to parent
+    branches:
+      - name: Branch A
+        wait_for:              # (optional) poll condition before starting
+          condition: <| expr |>
+          timeout: 10
+        steps:
+          - ...
+      - name: Branch B
+        steps:
+          - ...
+```
+
+- `TestItemParallel(TestItemContainer)`: mutates `dict_item["steps"]` to inject synthetic `parallel_branch` items so `load_test_recursively` loads branches normally as children.
+- `TestItemParallelBranch(TestItemContainer)`: container for one branch. `wait_for` polls every 0.1s up to `timeout` seconds before running steps.
+- `sync: any` calls `_stop_branch_recursively()` on all other branches when one *actually runs* (SUCCESS/FAILURE). A `NORUN` branch (disabled, condition not met) never wins the race.
+- Each branch runs in a daemon thread; the parent waits with `.join()`.
+- Branches stopped late (e.g. user disabled them in the GUI, or another sync:any branch already won) go through the normal `branch.stop() + branch.execute()` path so they always produce a clean DB entry via `addTest()`.
+- Exceptions raised in a branch's `execute()` are caught by `run_branch`, logged to stdout, and converted to a `FAILURE` result so they never disappear silently.
+- `sync: all` ignores `NORUN` branches when computing success (matches Group/Cycle semantics): only an actual `FAILURE` fails the parallel.
+- `TestItemSleep` is interruptible (polls `self._is_stopped` in a loop) so `sync: any` can stop slow branches quickly. `py_func` and `console` items are not interruptible; their full duration is observed before the branch returns.
+
+### `TestItemContainer` base class
+`src/testium/interpreter/test_items/test_item_container.py` — shared base for Group, Cycle, Parallel, and ParallelBranch. Provides `_run_children_sequentially()` which handles stop-on-failure, `executedOnStop` items, and returns `(TestResult, stopped_bool)`.
+
+### Report threading
+`src/testium/interpreter/test_report/test_report.py` — SQLite report with thread-safe writes:
+- `sqlite3.connect(..., check_same_thread=False)`
+- `self._lock = threading.Lock()` guards the SQLite `INSERT` only.
+- Per-item log capture (`stdio_redir.read()`) is naturally race-free thanks to per-thread buffers (see `StdoutProxy`).
+
+### Thread-aware stdout (`StdoutProxy`)
+`src/testium/runtime/stdout_redirect.py` — when `log_stored: True`, `intercept()` installs a `StdoutProxy` as `sys.stdout`/`sys.stderr` instead of a single shared `StringQueue`. The proxy:
+- Holds one `StringQueue` per thread (registered via `register_thread(buffer=...)`). The main thread uses a default buffer; each parallel branch's thread registers its own at start and unregisters at end. `stdio_redir.read()` reads the calling thread's buffer → `addTest()` of an item running in branch X reads X's clean, non-interleaved output.
+- For the live stream (terminal in batch / GUI panel), prefixes every line emitted from a branch's thread with `[<branch_name>] ` so concurrent branches stay readable.
+- Exposes `write` / `writeln` / `flush` (Python 3.14's `unittest` calls `stream.writeln()` directly without `_WritelnDecorator`).
+
+### Subprocess API contract (py_func / lua_func)
+
+User test scripts running inside a `py_func` or `lua_func` subprocess **must** use the JSON-RPC bridge to interact with testium state:
+
+- Python: `import py_func.tm as tm` — auto-generates wrappers for every function in `runtime/api.py:SUPPORTED_API`. `tm.gd`/`tm.setgd`/`tm.delgd` go through JSON-RPC to the parent.
+- Lua: `local tm = require("tm")` — same idea on the Lua side.
+
+`api.testium` is the *main-process* implementation; it is **not** exposed to subprocesses by design (not bundled in PyInstaller, not on the subprocess `PYTHONPATH` in pip-installed mode either when isolation is preserved). An import attempt from a subprocess script is a code smell and is detected by `test/validation/items/isolation/`.
+
+To add a new API call usable from subprocesses:
+1. Add the function to `api/testium.py`
+2. Add its name to `SUPPORTED_API` in `runtime/api.py`
+3. It is auto-exposed via JSON-RPC by `interpreter/utils/api_srv.py` and auto-wrapped by `py_func/tm.py:_make_api`
+
+### External interpreter resolution (`bins.py`)
+`src/testium/interpreter/utils/bins.py` — single source of truth for the paths to the external Python and Lua interpreters used by subprocesses.
+
+- `python_bin()` / `lua_bin()` : resolve and cache. The cache is keyed by `(name, override)` so that a later change to `gd[python_bin]` (typically when a `param.yaml` sets the key) triggers a re-resolution on the next lookup instead of returning the stale auto-discovered path. Falls back to discovery on PATH (candidates: `python3`/`python` and `lua`/`lua5.5`/`lua5.4`/`lua5.3`/`lua5.2`/`lua5.1`).
+- `ensure(*names)` : called by `TestSet._validate_runtime_deps()` at test load. Always requires `python` (the eval engine always runs); requires `lua` only if a `lua_func` item is in the tree. Fails fast with a clear error citing tried candidates and override key.
+
+Engines (`PyProcessBase`, `LuaProcessBase`, `EvalExecEngine`) call `bins.python_bin()`/`bins.lua_bin()` themselves — call sites never pass an explicit binary path.
+
+#### Override-timing contract (`apply_overrides`)
+`bins.python_bin()` is called for the **first** time inside `eval_process_init()` (the long-lived inline-`<| … |>` subprocess), which happens **before** the YAML param files are loaded. To make `-d python_bin=…` and the GUI `python_bin` preference take effect for `eval_proc` itself, `process.py:run()` applies them to gd **before** `eval_process_init()` via the `apply_overrides()` helper extracted from `update_global()`. The post-load `update_global()` call then re-applies the same overrides (after `prepare_global()` clears gd), keeping the gd value in sync with the cached resolution.
+
+| Override source | `eval_proc` | `py_func` / `cycle` / `post_exec` |
+|---|---|---|
+| `-d python_bin=…` (CLI) | ✅ | ✅ |
+| GUI `python_bin` preference | ✅ | ✅ |
+| `python_bin: …` in `param.yaml` | ❌ (eval_proc already started) | ✅ (cache re-resolves on key change) |
+
+## Key files
+
+| Path | Role |
+|------|------|
+| `src/testium/__init__.py` | CLI entry, mode dispatch |
+| `src/testium/interpreter/batch.py` | `-b` mode orchestrator |
+| `src/testium/interpreter/process.py` | Child test process |
+| `src/testium/interpreter/test_set.py` | Test tree builder/executor |
+| `src/testium/interpreter/test_items/test_item_container.py` | Base class for container items |
+| `src/testium/interpreter/test_items/test_item_parallel.py` | `parallel` and `parallel_branch` items |
+| `src/testium/interpreter/utils/globdict.py` | Global variable dict |
+| `src/testium/interpreter/utils/termlog.py` | Terminal color output |
+| `src/testium/runtime/stdout_redirect.py` | `StdioRedirect` singleton (`stdio_redir`) |
+| `src/testium/runtime/string_queue.py` | Thread-safe string buffer used for stdout redirection |
+| `src/testium/api/testium.py` | Public API for test scripts (`tm.*`) |
+| `src/testium/py_func/` | Python subprocess for `py_func` items (sandboxed: imports only `runtime/` and `py_func/`) |
+| `src/testium/lua_func/` | Lua subprocess scripts for `lua_func` items |
+
+## Package layout
+
+The whole project is a single Python package under `src/testium/`:
+
+```
+src/testium/
+├── __init__.py / __main__.py
+├── runtime/      internal plumbing (jrpc, stdout_redirect, string_queue, tum_except, api)
+├── api/          public SDK exposed to test scripts (`import api.testium as tm`)
+├── interpreter/  test execution engine (NOT visible to py_func/lua_func)
+├── main_win/     GUI (NOT visible to py_func/lua_func)
+├── py_func/      subprocess code for python_func items
+└── lua_func/     subprocess scripts for lua_func items (data files)
+```
+
+`subproc_path()` and `testium_path()` both return the package directory. The py_func subprocess is launched with cwd=that directory and `python3 py_func`. The contract that `py_func/` and `lua_func/` only depend on `runtime/` (no `interpreter`, `main_win`, `api`, `testium`) is enforced by `test/validation/items/isolation/`.
+
+## GUI icons (main_win)
+
+Icons live in `src/testium/main_win/resources/` with three theme variants:
+
+| Folder | Theme index | Usage |
+|--------|-------------|-------|
+| `color/` | 0 (default) | Coloured icons |
+| `black/` | 1 | Black silhouette on transparent |
+| `white/` | 2 | White silhouette on transparent (LA mode) |
+
+Icons are **64×64 PNG**. Black variants: RGBA with RGB=`(0,0,0)`, alpha varies. White variants: LA with luminance=`255`, alpha varies.
+
+The mapping item-type → icon filename is in `_ITEM_CONFIG` (`src/testium/main_win/test_tree_items/test_tree_item.py`). At runtime, `icon_prefix()` returns `:/color`, `:/black`, or `:/white` (Qt resource prefix) based on the user preference.
+
+All icons must be declared in `src/testium/main_win/resources/testium_core_win.qrc` (one entry per theme section). After any QRC change, regenerate the compiled resource file:
+```
+cd src/testium/main_win/resources
+pyside6-rcc testium_core_win.qrc -o testium_core_win_rc.py
+```
+
+Icons are assigned once when the test file is loaded (not updated live on theme change — a file reload is required).
+
+### `run` item
+`src/testium/interpreter/test_items/test_item_run.py` — launches a `.tum` file in a new testium instance (`-b` in batch mode, `-r` in GUI mode). Result:
+- **PASS** if the sub-instance launched and ran to completion (exit code is ignored)
+- **FAIL** if the file is not found, `wait_for_exec` is set without `start_time`/`end_time`, the time window was not reached, or any other launch error
+
+The sub-test's own pass/fail result is intentionally not propagated.
+
+The interpreter and entry point used to spawn the sub-instance are picked automatically by `_testium_launch_cmd()` based on how the parent was started (AppImage → `$APPIMAGE`; Flatpak → `flatpak run`; PyInstaller → the frozen binary; source/wheel → `[sys.executable, abspath(sys.argv[0])]`). The user cannot override either via the YAML — selecting a different testium binary or Python from a sub-test was removed because it was either ill-defined (bundle modes have no separable Python) or could mismatch the parent's environment in surprising ways.
+
+### Report exporters & plugins
+`src/testium/interpreter/test_report/test_report.py` — `_EXPORTER_REGISTRY` dict maps a format name (cmd key in the YAML `report.export`) to a lazy loader. Built-ins: `text`, `json`, `junit` (needs `junit_xml`), `html` (needs `lxml`). `sqlite` is the storage layer, no-op as an export.
+
+Third-party plugins are discovered at module import via `importlib.metadata.entry_points(group="testium.exporters")` — installing a wheel that declares such an entry point is enough, no testium config change needed:
+```toml
+[project.entry-points."testium.exporters"]
+my_format = "my_pkg:MyExporter"
+```
+Exporter contract: `__init__(self, name, con, path, pats, keys, no_header=False)` — the class does its work in `__init__` and writes to `path`.
+
+Behaviour on errors:
+- Unknown format → info line `[report] Export skipped: format "X" not found. Available: ...`, run continues.
+- Optional dependency missing → same info line with a pip-install hint, run continues.
+
+A real-world test plugin lives at `test/validation/fake_exporter/` (CSV exporter, auto-installed by `scripts/build_env.sh` and exercised by `test/validation/items/report_plugin/`).
+
+## Packaging
+
+Four distribution channels coexist, all sharing the single `src/testium/` package and the single `src/requirements.txt` dependency list:
+
+| Channel | Where | Build | Notes |
+|---------|-------|-------|-------|
+| Wheel (`pip install`) | `src/pyproject.toml` | `python -m build` | Vanilla Python package; entry point `testium = "testium:main"`. |
+| PyInstaller binary | `package/pyinstaller/` | `build.sh` | Single ~130 MB binary. `py_func`, `runtime`, `lua_func` bundled at `_MEIPASS` root so the **host** Python can find them when launched as `python3 py_func`. `api`/`interpreter` are **not** exposed (subprocess isolation). |
+| Flatpak | `package/flatpak/` | `build.sh` (uses `flatpak-builder`) | KDE 6.10 runtime. The bundled Python runs only the main process; `py_func` / `lua_func` MUST run under the **host** interpreter (no Python/Lua bundled). Produces a distributable `.flatpak` bundle. |
+| AppImage | `package/appimage/` | `build.sh` (Debian Bookworm container via Podman/Docker) | Bundles Python 3.11 for the main process; `py_func` / `lua_func` MUST run under the **host** interpreter. Build runs in a container so it works on Arch / any non-Debian host. |
+
+The `.deb` work-in-progress lives in `package/deb/`:
+- `test_distro.sh debian:bookworm | debian:trixie | ubuntu:24.04` spins up a Docker/Podman container, reports system package availability, falls back to pip for what's missing (`pyside6` on bookworm/ubuntu, `telnetlib3`, `junit_xml`), runs the validation suite. Currently green on the three targets.
+
+### Building all channels (`build_all.sh`)
+
+`build_all.sh` builds every artifact into `dist/` (manual PDF, wheel, PyInstaller binary, Flatpak bundle, AppImage). It reuses `scripts/build_env.sh` + `set_env.sh` so the venv at `test/tmp/.venv` stays the single source of Python deps; `build`/`pyinstaller`/`sphinx`/`linuxdoc` (and `pygls`, via the `[lsp]` extra) are installed there on demand. A step is skipped if its artifact already exists; `--clean` forces a rebuild.
+
+- **Parallelism (default).** A serial *prep* phase does everything that writes the shared venv (the `pip install`s) plus the Flatpak runtime install and the wheel (the AppImage installs it). Then manual + PyInstaller + Flatpak + AppImage build concurrently — they only *read* the venv, so there is no concurrent-pip race. Per-step output goes to `dist/.build-logs/<step>.log`; results print in completion order (`wait -n`), and a failing step's log is dumped at the end. `--serial` builds one at a time. Ctrl+C is trapped to kill each job's whole process tree (subshell + grandchildren: podman container, flatpak-builder, pyinstaller), so no orphans survive.
+- **`--ram` (slow/flash storage).** Redirects the build scratch to `/dev/shm` and skips UPX, a large win when building from a USB stick / SD card (I/O-bound on flash): `TMPDIR` + `PIP_CACHE_DIR`, the PyInstaller `--workpath` (`PYI_WORKPATH`), and a tmpfs bind-mount at the in-container AppImage AppDir (`APPIMAGE_APPDIR_TMPFS`); UPX is disabled via `TESTIUM_NO_UPX` (read by the `.spec`). **Flatpak is excluded** — `flatpak-builder` mounts its state dir with `rofiles-fuse` and FUSE cannot mount on `/dev/shm` (`fusermount: Permission denied`), so it builds on disk. Each `package/*/build.sh` honours these env vars with on-disk defaults, so behaviour is unchanged without `--ram`; the tmpfs scratch is freed on exit. On a RAM-limited machine combine with `--serial`.
+
+### Host-only py_func / lua_func in sandboxed bundles (Flatpak, AppImage)
+
+The bundled Python (Flatpak's runtime python, AppImage's `python3.11`) is reserved for the **main process only**. Subprocesses (`py_func`, `lua_func`, `git`, the `run` item's sub-instance) must use the host's interpreters and tools so user-installed modules (pyserial, junit_xml, …) are visible. This is enforced by `interpreter/utils/bins.py`:
+
+- `_in_flatpak()` (checks `/.flatpak-info`) and `_in_appimage()` (checks `APPIMAGE` env var) detect the sandbox.
+- **Flatpak**: the sandbox glibc/ABI is incompatible with arbitrary host shared libraries, so we **cannot** run host binaries inside the Flatpak runtime — `LD_LIBRARY_PATH` injection trips a `_dl_call_libc_early_init` assertion. The supported way out is `flatpak-spawn --host`, a stub on `$PATH` inside every Flatpak that proxies an `exec` over D-Bus to the host's `org.freedesktop.Flatpak` service. The manifest grants `--talk-name=org.freedesktop.Flatpak` so the call is allowed. Helpers:
+  - `flatpak_host_spawn(interp, args, host_cwd, extra_env=…)` builds the spawn command vector with a curated set of forwarded env vars (`HOME`, `USER`, `DISPLAY`, `DBUS_SESSION_BUS_ADDRESS`, …) plus any explicit overrides.
+  - `_get_host_testium_path()` returns a path to the testium package the host can read. In Flatpak the package lives under `/app/lib/testium` which the host cannot see, so the package is staged once per process under `/tmp/testium_host_*` (`/tmp` is shared) and reused. In source / wheel / PyInstaller installs under `$HOME` the original path is returned untouched.
+  - `_which_host_flatpak(name)` resolves a binary by spawning `command -v` on the host (or `test -x` for absolute paths) — sandbox-visible probing under `/run/host/...` is unreliable (only `host-os` is mounted; user paths like `/scratch` aren't there).
+  - `_python_version()` and `_lua_version()` go through `_run_probe()` which dispatches to `flatpak-spawn` in Flatpak so validation happens against the actual host interpreter.
+  - `py_process.py` / `lua_process.py` `start()` use `flatpak_host_spawn` with `host_cwd = _get_host_testium_path()[+/lua_func]` and forward `PYTHONPATH` / `LUA_PATH` / `LUA_CPATH` / `PATH` as `--env=` arguments.
+  - The `run` item's `_testium_launch_cmd()` prefixes `flatpak run org.testium.Testium` with `flatpak-spawn --host` so the sub-instance is launched by the host's `flatpak` CLI, not by an unworkable in-sandbox `flatpak` binary.
+- **AppImage**: we are directly on the host filesystem, so the regular discovery on `/usr/local/bin`, `/usr/bin`, `/bin` suffices. `apply_host_libs(env)` strips `$APPDIR`-prefixed entries from `LD_LIBRARY_PATH` / `PYTHONPATH` / `PATH` and drops `PYTHONHOME` so the host Python doesn't try to load the bundled stdlib/site-packages.
+- User overrides (`python_bin`/`lua_bin` in globdict): in Flatpak, both bare names and absolute paths go through `_which()` so they are validated on the host side (the sandbox can't see e.g. `/scratch/...`). Outside Flatpak, absolute paths are accepted as-is and bare names go through PATH discovery.
+- If the host has no python3/lua, `ensure()` raises `ETUMRuntimeError` at test load with the candidate list — no silent fallback to a bundled interpreter.
+- `py_process.py` additionally pops `PYTHONUSERBASE` (set to `/var/data/python` by the Flatpak runtime, which would hide `~/.local/lib/...`).
+
+### Declarative test item parameters
+
+Each `TestItem` subclass declares its accepted parameters as a class attribute `PARAMS = ParamSet(Param(...), ...)` (`interpreter/utils/param_decl.py`). The descriptor carries the parameter name, *kind* (`SCALAR` — the default and may be omitted; `LIST`; `BLOCK`; `Enum("a", "b", ...)`), `required` flag, `default`, and free-form `doc`. There is **no Python type** in the descriptor on purpose: most parameter values are expressions (`$(...)` / `<| ... |>`) whose effective type is only known after expansion, so a static type would be misleading. Post-expansion `validate=lambda v: ...` callbacks are available as an opt-in for the rare cases where a runtime check is warranted (e.g. a specific format).
+
+`TestItem.COMMON_PARAMS` (in `test_item.py`) declares the 14 parameters accepted by every item: `name`, `doc`, `skipped`, `key`, `stop_on_failure`, `execute_on_stop`, `process_result`, `store_result`, `expected_result`, `no_fail`, `report`, `condition`, `steps`, and the internal `seq_filename` injected by the loader. The base class concatenates `COMMON_PARAMS + subclass.PARAMS` in `_validate_declared_params()` and:
+
+- emits a `tm.print_warn(...)` listing the accepted names when an unknown key appears in the user YAML (catches typos like `param_filee`);
+- raises `ETUMSyntaxError` (with the `.tum` source as context) when a `required=True` param is missing.
+
+Validation is **opt-in per subclass**: while a subclass keeps `PARAMS = None` (the base-class default), the check is skipped entirely. This kept the migration incremental — items can be visited one by one without forcing a big-bang change. All structured items have been migrated; only the "unstructured-body" classes (`TestItemConsoleWrite`/`WriteLn` which carry the message as the raw value, `TestItemPlotActionAdd`/`Export` which take arbitrary plot-data keys, `TestItemUnittestElement` which is internally instantiated with `dict_item=None`) intentionally remain unvalidated.
+
+Diagnostics are currently **warnings** for unknown params so an out-of-tree `.tum` with a pre-existing typo doesn't suddenly fail. The flip to a hard error is a one-line change in `_validate_declared_params()` once the user is comfortable.
+
+Action items follow the same declarative principle. A `TestItemActions` parent (`console`, `plot`, `json_rpc`) declares its nested actions as a class attribute `ACTIONS = {yaml_key: action_class}` (e.g. `{"open": TestItemConsoleOpen, "write": …}`), mirroring `PARAMS`. The base `TestItemActions.__init__` seeds `self.action_classes` from `type(self).ACTIONS`; the imperative `register_actions(**…)` method is retained only as an escape hatch for actions that can't be known at class-definition time (none today). Because the action classes are always defined above their parent in the module, the class-level dict resolves without forward-reference gymnastics.
+
+The schema is the realized source of truth for the LSP server (`testium lsp`), the `testium schema` CLI dump, and future auto-generated manual sections: `ParamSet.to_schema()` returns the JSON-Schema-shaped representation, and `lsp/schema.py` reads both `PARAMS` and `ACTIONS` **purely from class attributes** — no `inspect.getsource`/AST parsing. This is what lets the full schema (including nested actions) survive a frozen PyInstaller build where the `.py` source isn't on disk.
+
+### Language server (`testium lsp`) across channels
+
+The `testium_assist` editor extension is a thin LSP client that spawns `testium lsp` and talks JSON-RPC over stdio, so the language server must work from *every* distribution channel. Two requirements:
+
+1. **`pygls` (+ `lsprotocol`, `cattrs`, `attrs`, `typing_extensions`) must be bundled.** It is the pyproject `[lsp]` extra (kept optional so a plain `pip install testium` stays lean), wired into each full-app channel: `build_env.sh` installs it into the shared `test/tmp/.venv` (covers **source run** and the **PyInstaller** build env); the **AppImage** installs the wheel as `…whl[lsp]`; the **Flatpak** adds a `python3-lsp` pip module (network-at-build, consistent with the manifest's global `--share=network`); the **PyInstaller** `.spec` force-collects the submodules via `collect_submodules` + explicit `hiddenimports` (including the lazily-imported `lsp`, `lsp.server`, `lsp.schema`).
+2. **The schema must build without source** — handled by the declarative `PARAMS`/`ACTIONS` above; PyInstaller is the only channel that strips `.py` source, and it no longer matters.
+
+`test/validation/lsp_check.py` enforces both per channel: `run.sh` calls it before launching the suite, asserting that `<channel> schema` returns JSON whose `console`/`plot`/`json_rpc` items still carry their actions, and that `<channel> lsp` answers an `initialize` request with capabilities (and never reports the pygls dependency missing). So `./test/validation/run.sh --mode flatpak|pyinstaller|appimage` now fails loudly if a channel ships a broken or pygls-less language server.
+
+### Version reporting (`interpreter/utils/version.py`)
+
+Both Flatpak and AppImage export `TESTIUM_VERSION` from a launcher (Flatpak: launcher script in `org.testium.Testium.yaml`; AppImage: `runtime.env` in `AppImageBuilder.yml`). `get_testium_version()` checks `/.flatpak-info` / `APPIMAGE` and reads `TESTIUM_VERSION` rather than relying on package metadata or repo introspection.
+
+## Recent fixes / notable changes
+- `build_all.sh`: builds the four heavy channels in parallel (serial prep for the shared venv + wheel), results in completion order, Ctrl+C kills the whole job tree; `--ram` puts the build scratch on tmpfs (`/dev/shm`) + skips UPX for fast builds on USB/SD storage (Flatpak excluded — rofiles-fuse can't mount tmpfs). See the "Building all channels" section.
+- LSP across packaging channels: `testium lsp` (and the `testium_assist` editor extension that spawns it) now works from source, wheel, PyInstaller, Flatpak and AppImage. Two enablers — (1) action items declare a class-level `ACTIONS = {key: class}` registry (like `PARAMS`), so `lsp/schema.py` builds the full schema from class attributes with no `inspect.getsource`/AST (which broke under frozen PyInstaller); (2) the `[lsp]` extra (pygls) is wired into every full-app channel. `test/validation/lsp_check.py`, run by `run.sh` before the suite, asserts per-channel that `schema` keeps its actions and `lsp` answers `initialize`. See the matching architecture sections.
+- Declarative test item parameters (v0.2): each `TestItem` subclass exposes a `PARAMS = ParamSet(...)` class attribute consumed by the base `__init__`. Catches unknown YAML keys (typo warnings listing the accepted names) and missing required params (load-time errors with `.tum` context). Lays the schema foundation for a future LSP server and auto-generated manual sections. See the matching architecture section.
+- Flatpak: `py_func` / `lua_func` / `run` sub-instance now execute on the host via `flatpak-spawn --host`. The previous attempt to inject host lib dirs into the sandbox's `LD_LIBRARY_PATH` was abandoned — host shared libs are ABI-incompatible with the Flatpak runtime's glibc and would trip `_dl_call_libc_early_init`. The manifest gained `--talk-name=org.freedesktop.Flatpak` so the spawn proxy call is allowed. The testium package is staged once per process under `/tmp` (shared with the host) so the host interpreter can locate `py_func` / `lua_func`.
+- Validation suite: single entry point with `--mode source|wheel|pyinstaller|flatpak|appimage` to validate every packaging channel against the same items. Per-mode report filenames prevent clobbering.
+- Restructure: single `src/testium/` Python package (was 4 sibling top-levels: `testium`, `lib`, `py_func`, `lua_func`). `lib/` → `runtime/`, `libs/` → `api/`. `pip install` now produces a clean `site-packages/testium/` with no top-level pollution; `.lua` files travel via `package_data`.
+- `bins.py`: centralised resolution + cache of external `python3` / `lua` binaries. Replaces the scattered `tm.gd("python_bin")`/`tm.gd("lua_bin")` dance and the duplicated discovery logic in `py_process.py`/`lua_process.py`. Validates at test load via `TestSet._validate_runtime_deps()` so missing interpreters fail fast.
+- Subprocess API contract: user scripts in `py_func`/`lua_func` use the JSON-RPC bridge (`py_func.tm` / Lua `tm`) — never `api.testium` / `interpreter.*` directly. `SUPPORTED_API` extended with `OS`, `get_main_dir`, `init_timestamp`, `timestamp`, `timestamp_as_sec` so subprocess scripts have the same surface as main-process code.
+- Report exporter plugin registry (`test_report.py`): `_EXPORTER_REGISTRY` + `entry_points("testium.exporters")` discovery. Missing format → info line, run continues.
+- About dialog rework: `QVBoxLayout` (resizable), version + dirty/branch info in a `QLabel` (auto-sized), copyright + clickable EUPL-1.2 link.
+- `test_ctrl.control()`: drain stale responses (left over from polled `loaded()` after `clear()` race) instead of failing on a wrong cmd key — fixes a "Unexpected return error in test set controller" seen in GUI mode after a fast reload.
+- `lua_process.py`: stderr no longer DEVNULL'd so actual Lua errors (missing `cjson`/`socket`) surface instead of "Connection refused".
+- `run_post_exec`: failure message uses `print_warn` (was `print_debug` — silent in non-debug runs).
+- Python 3.11 compat: replaced PEP 701 nested-quote f-strings (e.g. `f"... {d["k"]} ..."`) with single-quote inner strings or string concatenation.
+- `parallel` item: new item with `sync: all|any`, `wait_for`, daemon threads, `_stop_branch_recursively()`. Each branch thread registers a per-thread stdout buffer.
+- `parallel_branch` icon: distinct single-arrow icon (`parallel_branch.png`).
+- `parallel` F1 panel: `steps` stripped from each branch dict.
+- `test_item_container.py`: shared base class extracted from Group/Cycle.
+- `test_item_sleep.py`: interruptible loop so `sync: any` can stop slow branches quickly.
+- `stdout_redirect.py`: `StdoutProxy` (thread-aware buffers + branch-prefixed live output, `writeln()` for Python 3.14 unittest).
+- `test_report.py`: thread-safe SQLite INSERT for parallel branch concurrency.
+- `terminal.py`: deleted — `-m`/`--terminal` mode removed.
+- `batch.py`: premature finish bug on `gd_update` (no `"id"` key) — fix uses `"id" in m and m["id"] is None`.
+- `batch.py`: `control("loaded")` deadlock on TestProcess crash — fix uses daemon thread + `threading.Event` + `is_alive()` polling.
+- `termlog.py`: light/dark terminal auto-detection (`COLORFGBG`, OSC 11) + write residue bug.
+- Dialog items: `auto_result`/`auto_value` for non-interactive text mode; dialogs without `auto_result` FAIL immediately in batch.
+- `run` item: renamed `tum_fime` → `tum`; removed `stdout=PIPE` deadlock; PASS on any completed subprocess.
+- `unittest` item: renamed from `unittest_file`.
+- GUI test tree: check and fold state preserved across same-file reloads.
+- Licence: EUPL-1.2.
+- Interpreter override timing: `apply_overrides()` extracted from `update_global()` and called by `process.py:run()` before `eval_process_init()`, so `-d python_bin=…` / GUI prefs reach `bins.python_bin()` on its first lookup. `bins._resolve()` cache is now keyed by `(name, override)` so later `param.yaml` changes are picked up by subsequently constructed engines.
+
+## Validation tests
+Located in `test/validation/`. Two entry points:
+```
+./test/validation/run.sh [clean] [--mode MODE] [extra args]   # wrapper — uses a dedicated venv (see below)
+./run.sh -b -- test/validation/main.tum                       # direct — testium's own python is used for test execution
+```
+The same item set is reused across every packaging channel — `--mode source|wheel|pyinstaller|flatpak|appimage` selects which testium binary launches the suite (`source` is the default, invoking the project's `run.sh`). Each mode stamps its results into a distinct report file (`validation-<mode>.sqlite`, `validation-<mode>-<item>.xml`) so successive runs in different modes don't clobber each other. Prerequisites (PyInstaller binary built, Flatpak bundle installed, …) are checked before launch with a hint pointing at `build_all.sh`. On Windows only `source`, `wheel`, `pyinstaller` are supported.
+
+The `run.sh` / `run.bat` wrappers create a dedicated **host** Python venv at `${TMPDIR:-/tmp}/testium-validation-venv` (Linux) or `%TEMP%\testium-validation-venv` (Windows), with `--system-site-packages` + `pip install junit-xml`, and run the suite with `-d python_bin=…` so every test-execution subprocess (eval_proc, py_func, cycle, post_exec) runs inside that venv. testium itself keeps running in its own environment for the chosen mode. The venv is shared across modes because every test-execution subprocess ends up on the host either directly (source/wheel/pyinstaller/appimage) or via `flatpak-spawn --host` (flatpak). `clean` as the first argument recreates the venv. `wheel` mode also creates a separate `testium-wheel-venv-<v>` to hold the installed package.
+
+The `venv` item (`test/validation/items/venv/`) asserts that the override actually took effect: `python_bin` is set, `sys.executable` matches it, `sys.prefix == dirname(dirname(python_bin))`, and `sys.prefix != sys.base_prefix` (the last marker catches the case where `python_bin` happens to be a system interpreter, which path-equality alone would miss because the venv's `bin/python3` is a symlink to the host). Both `eval_proc` (inline `<| … |>`) and `py_func` paths are exercised.
+
+Parallel item tests: `test/validation/items/parallel/test.tum`
+
+## Dependencies
+See `src/requirements.txt`. Key ones: `pyside6`, `pyyaml`, `jinja2`, `colorama`, `gitpython`, `pexpect`, `matplotlib`.

README.md

@@ -27,7 +27,43 @@ Pre-built artifacts are published at
   runnable directly, no Python installation required on the host. Lua
   support still needs a system `lua` interpreter and the `lua-socket` /
   `lua-cjson` modules.
-* **Flatpak** — *coming soon.*
+* **AppImage** (`Testium-<version>-x86_64.AppImage`) — single-file
+  Linux binary, runnable directly:
+
+  ```sh
+  chmod +x Testium-*-x86_64.AppImage
+  ./Testium-*-x86_64.AppImage
+  ```
+
+  Requires `libfuse2` on the host (FUSE 2 — distinct from `fuse3`, which
+  most distros now ship by default):
+
+  | Distro | Package |
+  |--------|---------|
+  | Arch / CachyOS / Manjaro | `fuse2` |
+  | Debian trixie / Ubuntu 24.04+ | `libfuse2t64` |
+  | Debian bookworm / Ubuntu 22.04 | `libfuse2` |
+  | Fedora | `fuse-libs` |
+
+  If you can't install libfuse2 (e.g. minimal container), prefix the
+  invocation with `APPIMAGE_EXTRACT_AND_RUN=1` — the AppImage will
+  self-extract to `/tmp` on each run instead of FUSE-mounting.
+* **Flatpak bundle** (`testium.flatpak`) — install with:
+
+  ```sh
+  # Add Flathub (once, to fetch the KDE/PySide runtimes)
+  flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+
+  # Install the bundle
+  flatpak install --user testium.flatpak
+  ```
+
+  After installation testium appears in the desktop application menu and the
+  `testium` command is available in the terminal (requires `~/.local/bin` in
+  `PATH`, which most modern distributions provide by default).
+
+Every channel ships the language server, so `testium lsp` (see
+[Editor support](#editor-support)) works out of the box from any of them.
 
 ## Quick start
 
@@ -70,6 +106,45 @@ python3 src/testium               # GUI
 python3 src/testium -b mytest.tum # batch
 ```
 
+## Editor support
+
+testium ships a Language Server Protocol (LSP) server that gives `.tum` files
+completion of item types, hover documentation, and an outline view in any
+LSP-capable editor:
+
+```sh
+testium lsp        # speaks LSP over stdio; an editor's LSP client drives it
+testium schema     # dumps the item/parameter schema as JSON (what the LSP serves)
+```
+
+The server is bundled in every pre-built release (wheel, binary, Flatpak,
+AppImage). For a source / wheel install, pull the language-server extra:
+
+```sh
+pip install 'testium[lsp]'                 # from PyPI / a wheel
+pip install -e /path/to/testium/src[lsp]   # from a source checkout
+```
+
+A VSCode / VSCodium client extension (`testium_assist`) wraps `testium lsp`;
+the schema is built from testium itself, so new item types and parameters
+appear in the editor on the next testium upgrade with no client change.
+
+It is published on [Open VSX](https://open-vsx.org/extension/testium/testium-assist),
+so in **VSCodium, Cursor, Windsurf, Theia and code-server** it installs from the
+Extensions view (search `testium-assist`) or with
+`codium --install-extension testium.testium-assist`.
+
+**Microsoft VSCode** does not list Open VSX extensions, so install the `.vsix`
+by hand — download it from the Open VSX page above, then *Extensions → ⋯ →
+Install from VSIX…* or:
+
+```sh
+code --install-extension testium-assist-0.1.0.vsix
+```
+
+The extension runs `testium lsp`, so `testium` must be on the `PATH` (otherwise
+point the `testium.serverPath` setting at the binary/AppImage).
+
 ## Troubleshooting
 
 ### `wl_proxy_marshal_flags` symbol error

build_all.sh

@@ -0,0 +1,299 @@
+#!/bin/bash
+# Build every distribution channel of testium:
+#   1. Manual PDF         -> dist/testium-manual-<v>.pdf
+#   2. Wheel              -> dist/testium-<v>-py3-none-any.whl   (PEP 427 name)
+#   3. PyInstaller binary -> dist/testium-<v>
+#   4. Flatpak bundle     -> dist/testium-<v>.flatpak
+#   5. AppImage           -> dist/Testium-<v>-x86_64.AppImage    (original name)
+# release_note.txt is copied to dist/ up front (with a warning if it has no
+# entry for the current version).
+#
+# By default, a step is skipped if its artifact already exists in dist/.
+# Pass --clean to remove existing dist/ artifacts and rebuild everything.
+#
+# Parallelism: the wheel is built first (the AppImage installs it), then the
+# manual, PyInstaller, Flatpak and AppImage builds run concurrently. The shared
+# venv at test/tmp/.venv is only WRITTEN during the serial prep phase (the
+# `pip install` of build/sphinx/pyinstaller); the parallel builds only read it,
+# so there is no concurrent-pip race. Pass --serial to build one step at a time
+# (useful when debugging or on a resource-constrained machine). Per-step output
+# of the parallel phase is captured under dist/.build-logs/<step>.log and the
+# log of any failing step is printed at the end.
+#
+# Pass --ram to redirect the per-channel build scratch (PyInstaller workpath,
+# AppImage AppDir) and TMPDIR/PIP_CACHE_DIR to /dev/shm, and skip UPX. Big
+# speedup on slow/flash storage. Flatpak is excluded (its rofiles-fuse can't
+# mount on /dev/shm), so it still builds on disk. On a RAM-limited machine
+# combine with --serial (e.g. ./build_all.sh --ram --serial).
+#
+# All artifacts are collected (copied) under <repo>/dist/. Original outputs in
+# src/dist/, package/*/dist/, doc/manual/ are left in place. Wheel and AppImage
+# keep their original names (which already contain the version); manual,
+# pyinstaller and flatpak are renamed to testium(-manual)-<version>(.suff).
+#
+# Re-uses scripts/build_env.sh and scripts/set_env.sh — the same pair invoked
+# by run.sh — so the venv at test/tmp/.venv stays the single source of Python
+# dependencies. `build`, `pyinstaller`, `sphinx` and `linuxdoc` are installed
+# into that venv on demand if not already there. Flatpak and AppImage build in
+# their own container/sandbox; their build.sh scripts have their own toolchain
+# checks.
+
+set -e
+
+CLEAN=0
+SERIAL=0
+RAM=0
+for arg in "$@"; do
+    case "$arg" in
+        --clean|-c) CLEAN=1 ;;
+        --serial)   SERIAL=1 ;;
+        --ram)      RAM=1 ;;
+        *) echo "Unknown option: $arg" >&2; exit 1 ;;
+    esac
+done
+
+SCRIPT_DIR=$(realpath "$(dirname "$0")")
+VERSION=$(cat "$SCRIPT_DIR/src/VERSION")
+DIST_DIR="$SCRIPT_DIR/dist"
+mkdir -p "$DIST_DIR"
+
+if [ "$CLEAN" -eq 1 ]; then
+    echo "-- clean: removing existing dist artifacts for version $VERSION"
+    rm -f "$DIST_DIR/testium-manual-${VERSION}.pdf"
+    rm -f "$DIST_DIR"/testium-${VERSION}-*.whl
+    rm -f "$DIST_DIR/testium-${VERSION}"
+    rm -f "$DIST_DIR/testium-${VERSION}.flatpak"
+    rm -f "$DIST_DIR"/Testium-${VERSION}-*.AppImage
+fi
+
+# Release note: copy it to dist/ and warn (but don't fail) if it has no entry
+# for the current version.
+RELEASE_NOTE_SRC="$SCRIPT_DIR/release_note.txt"
+RELEASE_NOTE="$DIST_DIR/release_note.txt"
+cp -f "$RELEASE_NOTE_SRC" "$RELEASE_NOTE"
+if ! grep -qE "^version $VERSION([^.0-9]|$)" "$RELEASE_NOTE_SRC"; then
+    echo "WARNING: release_note.txt has no entry for version $VERSION." >&2
+fi
+
+export PY_VENV_NAME=".venv"
+export PY_VENV_DIR="$SCRIPT_DIR/test/tmp/$PY_VENV_NAME"
+export REQ_PATH="$SCRIPT_DIR/src/requirements.txt"
+
+bash "$SCRIPT_DIR/scripts/build_env.sh"
+source "$SCRIPT_DIR/scripts/set_env.sh"
+
+# ---------- RAM mode: put build scratch on tmpfs (--ram) ----------------------
+# On slow storage (USB stick, SD card) the per-channel build dirs and temp
+# churn dominate. --ram redirects the PyInstaller workpath, the AppImage AppDir
+# and TMPDIR/PIP_CACHE_DIR to /dev/shm, and skips UPX. Flatpak is intentionally
+# NOT moved: flatpak-builder mounts its state dir with rofiles-fuse, and FUSE
+# can't mount on /dev/shm (fusermount: Permission denied) — so it builds on
+# disk. The tmpfs scratch is freed on exit.
+if [ "$RAM" -eq 1 ]; then
+    RAMROOT="/dev/shm/testium-build-${VERSION}"
+    echo "-- RAM mode: build scratch under $RAMROOT (tmpfs), freed on exit"
+    echo "   (flatpak builds on disk — rofiles-fuse can't mount on /dev/shm)"
+    rm -rf "$RAMROOT"
+    mkdir -p "$RAMROOT"/{tmp,pip,pyi-work,appdir}
+    export TMPDIR="$RAMROOT/tmp"
+    export PIP_CACHE_DIR="$RAMROOT/pip"
+    export PYI_WORKPATH="$RAMROOT/pyi-work"            # pyinstaller --workpath
+    export APPIMAGE_APPDIR_TMPFS="$RAMROOT/appdir"     # AppDir bind-mount
+    export TESTIUM_NO_UPX=1                            # skip slow UPX in the spec
+    trap 'rm -rf "$RAMROOT"' EXIT
+    if [ "$SERIAL" -ne 1 ]; then
+        echo "   note: with --ram, prefer adding --serial so each step gets the"
+        echo "         full tmpfs and you don't risk OOM (flatpak+appimage are ~1 GB each)."
+    fi
+fi
+
+step() {
+    echo
+    echo "================================================================"
+    echo "  $1"
+    echo "================================================================"
+}
+
+# Kill a process and its whole descendant tree (children first) — used by the
+# interrupt handler so SIGINT also stops grandchildren the parallel jobs spawned
+# (podman container, flatpak-builder, pyinstaller …), not just the subshells.
+_kill_tree() {
+    local pid=$1 c
+    for c in $(pgrep -P "$pid" 2>/dev/null); do
+        _kill_tree "$c"
+    done
+    kill -TERM "$pid" 2>/dev/null || true
+}
+
+# Set as INT/TERM handler around the parallel wait. Stops every running build
+# tree, then exits — the EXIT trap (set under --ram) frees the tmpfs scratch.
+_interrupt() {
+    echo >&2
+    echo "-- interrupted: stopping running builds…" >&2
+    local pid
+    for pid in "${!PID2NAME[@]}"; do
+        _kill_tree "$pid"
+    done
+    exit 130
+}
+
+# ---------- artifact paths ----------------------------------------------------
+
+MANUAL="$DIST_DIR/testium-manual-${VERSION}.pdf"
+PYI_BIN="$DIST_DIR/testium-${VERSION}"
+FLATPAK_BUNDLE="$DIST_DIR/testium-${VERSION}.flatpak"
+wheel_in_dist() { ls -1t "$DIST_DIR"/testium-${VERSION}-*.whl 2>/dev/null | head -1; }
+appimage_in_dist() { ls -1t "$DIST_DIR"/Testium-${VERSION}-*.AppImage 2>/dev/null | head -1; }
+
+# ---------- per-step build functions (assume tools are installed) -------------
+
+build_wheel() {
+    if [ -n "$(wheel_in_dist)" ]; then echo "wheel: already built — skipping"; return 0; fi
+    echo "wheel: building"
+    (
+        cd "$SCRIPT_DIR/src"
+        rm -rf dist build *.egg-info
+        python -m build --wheel
+    )
+    local src; src=$(ls -1t "$SCRIPT_DIR/src/dist"/*.whl | head -1)
+    cp -f "$src" "$DIST_DIR/$(basename "$src")"
+    echo "wheel: done"
+}
+
+build_manual() {
+    if [ -f "$MANUAL" ]; then echo "manual: already built — skipping"; return 0; fi
+    echo "manual: building"
+    bash "$SCRIPT_DIR/doc/manual/sphinx/build_doc.sh"
+    cp -f "$SCRIPT_DIR/doc/manual/testium_manual.pdf" "$MANUAL"
+    echo "manual: done"
+}
+
+build_pyinstaller() {
+    if [ -f "$PYI_BIN" ]; then echo "pyinstaller: already built — skipping"; return 0; fi
+    echo "pyinstaller: building"
+    bash "$SCRIPT_DIR/package/pyinstaller/build.sh"
+    cp -f "$SCRIPT_DIR/package/pyinstaller/dist/testium" "$PYI_BIN"
+    echo "pyinstaller: done"
+}
+
+build_flatpak() {
+    if [ -f "$FLATPAK_BUNDLE" ]; then echo "flatpak: already built — skipping"; return 0; fi
+    echo "flatpak: building"
+    (
+        cd "$SCRIPT_DIR/package/flatpak"
+        bash build.sh
+    )
+    cp -f "$SCRIPT_DIR/package/flatpak/testium.flatpak" "$FLATPAK_BUNDLE"
+    echo "flatpak: done"
+}
+
+build_appimage() {
+    if [ -n "$(appimage_in_dist)" ]; then echo "appimage: already built — skipping"; return 0; fi
+    echo "appimage: building"
+    (
+        cd "$SCRIPT_DIR/package/appimage"
+        bash build.sh
+    )
+    local src; src=$(ls -1t "$SCRIPT_DIR/package/appimage"/*.AppImage 2>/dev/null | head -1)
+    cp -f "$src" "$DIST_DIR/$(basename "$src")"
+    chmod +x "$DIST_DIR/$(basename "$src")"
+    echo "appimage: done"
+}
+
+# ---------- serial prep: tool installs (shared venv) + flatpak runtimes -------
+
+step "Prep: build tools + runtimes (serial — shared venv)"
+
+[ -f "$MANUAL" ]   || python -m pip install --quiet --upgrade sphinx linuxdoc
+[ -n "$(wheel_in_dist)" ] || python -m pip install --quiet --upgrade build
+[ -f "$PYI_BIN" ]  || python -m pip install --quiet --upgrade pyinstaller
+
+if [ ! -f "$FLATPAK_BUNDLE" ]; then
+    FLATPAK_DEPS=(
+        "org.kde.Platform//6.10"
+        "org.kde.Sdk//6.10"
+        "io.qt.PySide.BaseApp//6.10"
+    )
+    if ! flatpak remotes --user | grep -q "^flathub"; then
+        echo "  Adding Flathub remote"
+        flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+    fi
+    for dep in "${FLATPAK_DEPS[@]}"; do
+        if ! flatpak info --user "$dep" &>/dev/null && ! flatpak info --system "$dep" &>/dev/null; then
+            echo "  Installing Flatpak dependency: $dep"
+            flatpak install --user --noninteractive flathub "$dep"
+        fi
+    done
+fi
+
+# ---------- serial: wheel (the AppImage installs it) --------------------------
+
+step "1/5  Wheel (version $VERSION)"
+build_wheel
+
+# ---------- build the rest --------------------------------------------------
+
+REST=(manual pyinstaller flatpak appimage)
+
+if [ "$SERIAL" -eq 1 ]; then
+    n=2
+    for name in "${REST[@]}"; do
+        step "$n/5  $name (version $VERSION)"
+        "build_$name"
+        n=$((n + 1))
+    done
+else
+    step "2-5/5  manual + pyinstaller + flatpak + appimage (parallel)"
+    LOGDIR="$DIST_DIR/.build-logs"
+    mkdir -p "$LOGDIR"
+    declare -A PID2NAME
+    for name in "${REST[@]}"; do
+        log="$LOGDIR/$name.log"
+        echo "  -> launching $name (log: $log)"
+        ( "build_$name" ) >"$log" 2>&1 &
+        PID2NAME[$!]="$name"
+    done
+
+    # From here until all jobs are reaped, Ctrl+C stops every build tree.
+    trap _interrupt INT TERM
+
+    # Reap in completion order (wait -n) so each result prints the moment that
+    # build finishes, not when its slot comes up in the array.
+    FAILED=()
+    remaining=${#PID2NAME[@]}
+    while [ "$remaining" -gt 0 ]; do
+        if wait -n -p donepid; then rc=0; else rc=$?; fi
+        name="${PID2NAME[$donepid]:-}"
+        [ -z "$name" ] && continue
+        if [ "$rc" -eq 0 ]; then
+            echo "  -> $name: OK"
+        else
+            echo "  -> $name: FAILED (rc=$rc)"
+            FAILED+=("$name")
+        fi
+        remaining=$((remaining - 1))
+    done
+
+    trap - INT TERM
+
+    if [ "${#FAILED[@]}" -gt 0 ]; then
+        for name in "${FAILED[@]}"; do
+            echo
+            echo "===================== $name log ====================="
+            cat "$LOGDIR/$name.log"
+        done
+        echo >&2
+        echo "BUILD FAILED: ${FAILED[*]} (logs under $LOGDIR)" >&2
+        exit 1
+    fi
+fi
+
+# ---------- summary -----------------------------------------------------------
+
+step "All packages built"
+printf "  manual       : %s\n" "$MANUAL"
+printf "  wheel        : %s\n" "$(wheel_in_dist)"
+printf "  pyinstaller  : %s\n" "$PYI_BIN"
+printf "  flatpak      : %s\n" "$FLATPAK_BUNDLE"
+printf "  appimage     : %s\n" "$(appimage_in_dist)"
+printf "  release_note : %s\n" "$RELEASE_NOTE"

doc/examples/example_simple.tum

@@ -20,6 +20,22 @@ main:
           param:
               - 123
 
+      - py_func:
+          name: python long wait
+          doc: The purpose of this step is to try the tasks "stop" interruption
+          file: utils.py
+          func_name: long_wait
+          param:
+              - 10
+
+      - lua_func:
+          name: lua long wait
+          doc: The purpose of this step is to try the tasks "stop" interruption
+          file: lua_func.lua
+          func_name: long_wait
+          param:
+              - 10
+
       - sleep:
           name: sleep item
           dialog: true

doc/examples/lua_func.lua

@@ -1,4 +1,5 @@
 tm = require("tm")
+socket = require("socket")
 
 local module = {}
 
@@ -7,4 +8,8 @@ function module.func_to_be_executed(param)
     return param
 end
 
+function module.long_wait(sec)
+    socket.sleep(sec)
+end
+
 return module

doc/examples/param.yaml

@@ -17,18 +17,3 @@ plot_log_path: /tmp/testium_plot/$(testrun_date)/$(testrun_time)/
 python_path_Windows: C:\Users\François\Applications\Python313\python.exe
 python_path_Linux: $(home)/tmp/tum_venv/bin/python3
 
-# lua_bin_Windows: C:\Lua\5.1
-# lua_bin_Linux: /usr/bin/lua
-
-LUA_PATH_Linux: /usr/share/lua/5.4/?.lua;/usr/local/share/lua/5.4/?.lua;/usr/local/share/lua/5.4/?/init.lua;/usr/share/lua/5.4/?/init.lua;/usr/local/lib/lua/5.4/?.lua;/usr/local/lib/lua/5.4/?/init.lua;/usr/lib/lua/5.4/?.lua;/usr/lib/lua/5.4/?/init.lua;./?.lua;./?/init.lua;/home/francois/.luarocks/share/lua/5.4/?.lua;/home/francois/.luarocks/share/lua/5.4/?/init.lua
-LUA_CPATH_Linux: /usr/local/lib/lua/5.4/?.so;/usr/lib/lua/5.4/?.so;/usr/local/lib/lua/5.4/loadall.so;/usr/lib/lua/5.4/loadall.so;./?.so;/home/francois/.luarocks/lib/lua/5.4/?.so
-PATH_Linux:
-
-LUA_PATH_Windows: ;.\?.lua;C:\Lua\5.1\lua\?.lua;C:\Lua\5.1\lua\?\init.lua;C:\Lua\5.1\?.lua;C:\Lua\5.1\?\init.lua;C:\Lua\5.1\lua\?.luac
-LUA_CPATH_Windows: .\?.dll;C:\Lua\5.1\?.dll;C:\Lua\5.1\loadall.dll;C:\Lua\5.1\clibs\?.dll;C:\Lua\5.1\clibs\loadall.dll;.\?51.dll;C:\Lua\5.1\?51.dll;C:\Lua\5.1\clibs\?51.dll
-PATH_Windows: ""
-
-lua_env:
-  PATH: $(PATH_$(os))
-  LUA_PATH: $(LUA_PATH_$(os))
-  LUA_CPATH: $(LUA_CPATH_$(os))

doc/examples/utils.py

@@ -1,3 +1,5 @@
+from time import sleep
+
 def dummy_exit(useless1, useless2):
     return True
 
@@ -10,4 +12,7 @@ def funcToBeExecuted (bla):
 
 def funcToBeExecuted2 (bla):
     print(bla)
-    return blo
+    return blo
+
+def long_wait (sec):
+    sleep(sec)

doc/manual/sphinx/source/modes.rst

@@ -23,3 +23,80 @@ graphical interface.
     :caption: call a test in batch mode
 
     testium -b test/my_test/main.tum
+
+.. _sec_language_server:
+
+Language server (editor support)
+--------------------------------
+
+*testium* ships a `Language Server Protocol
+<https://microsoft.github.io/language-server-protocol/>`_ server so that
+``.tum`` files get editor assistance — completion of test item types, hover
+documentation of their parameters, and an outline view — in any LSP-capable
+editor.
+
+The server speaks LSP over standard input/output and is started with:
+
+.. code-block:: text
+    :caption: start the language server
+
+    testium lsp
+
+It is not meant to be launched directly by the user: an editor's LSP client
+spawns it and drives the exchange. A VSCode / VSCodium client extension,
+*testium_assist*, is provided for that purpose; any other LSP client (Neovim,
+Emacs ``lsp-mode``, …) can be pointed at ``testium lsp`` as well.
+
+The information the server exposes is the test item schema, which can also be
+dumped as JSON for inspection or tooling:
+
+.. code-block:: text
+    :caption: dump the item / parameter schema
+
+    testium schema
+
+Because the schema is built from *testium* itself, every new item type or
+parameter becomes available in the editor on the next *testium* upgrade, with
+no change to the client.
+
+The language server is included in the pre-built binary, Flatpak and AppImage
+releases. For a source or wheel installation, pull the optional ``lsp``
+dependencies:
+
+.. code-block:: text
+    :caption: enable the language server for a wheel / source install
+
+    pip install 'testium[lsp]'
+
+Installing the VSCode / VSCodium extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *testium_assist* client extension is published on `Open VSX
+<https://open-vsx.org/extension/testium/testium-assist>`_, the registry used by
+VSCodium, Cursor, Windsurf, Eclipse Theia and code-server. In those editors,
+open the Extensions view and search ``testium-assist``, or install it from the
+command line:
+
+.. code-block:: text
+    :caption: install in VSCodium and other Open VSX editors
+
+    codium --install-extension testium.testium-assist
+
+Microsoft *VSCode* uses a different marketplace that does not list Open VSX
+extensions, so install the packaged ``.vsix`` by hand. Download it from the
+Open VSX page linked above, then either choose *Extensions* → *⋯* →
+*Install from VSIX…* in the UI, or run:
+
+.. code-block:: text
+    :caption: install the .vsix in Microsoft VSCode
+
+    code --install-extension testium-assist-0.1.0.vsix
+
+The extension launches ``testium lsp``, so the ``testium`` command must be on
+the ``PATH``. If *testium* is installed elsewhere — a specific binary or an
+AppImage — point the ``testium.serverPath`` setting at it instead.
+
+Once installed, open a ``.tum`` file: completion of item types, hover
+documentation and the outline view become available. If nothing happens, check
+that no ``files.associations`` entry forces ``*.tum`` to another language (it
+must stay the ``tum`` language the extension provides).

doc/manual/sphinx/source/tum_syntax.rst

@@ -232,6 +232,15 @@ list of the main test item (and eventually of the loop test item).
 TUM file ``main`` item is itself a variant of test items with a name and an
 step list attributes.
 
+.. note::
+
+   Each test item declares the parameters it accepts. When a ``.tum`` file
+   uses a key the item does not know, *testium* emits a warning listing the
+   accepted parameter names (catching typos such as ``param_filee`` for
+   ``param_file``); a missing **required** parameter aborts loading with an
+   error pointing at the source ``.tum`` file. Valid existing tests are
+   unaffected.
+
 
 
 .. toctree::

package/appimage/AppImageBuilder.yml

@@ -24,9 +24,8 @@ AppDir:
 
     runtime:
         env:
-            SEQUENCER_REV: '{{APP_VERSION}}'
+            TESTIUM_VERSION: '{{APP_VERSION}}'
             PYTHONPATH: $APPDIR/usr/lib/python3.11/site-packages:$APPDIR/usr/lib/python3.11
-            QT_QPA_PLATFORM: xcb
 
         path_mappings:
             - /usr/share/matplotlib/mpl-data/matplotlibrc:$APPDIR/etc/matplotlibrc
@@ -69,15 +68,19 @@ AppDir:
 
         # Set python 3.11 as default
         ln -fs python3.11 $TARGET_APPDIR/usr/bin/python3
-        # Install pip
-        if [ ! -f "get-pip.py" ]; then curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py; fi
+
+        # Bootstrap pip into the AppDir Python
+        if [ ! -f "get-pip.py" ]; then curl -sS https://bootstrap.pypa.io/get-pip.py -o get-pip.py; fi
         python3.11 get-pip.py --break-system-packages
 
         # Install application dependencies in AppDir
-        python3.11 -m pip install --break-system-packages --upgrade --isolated --no-input --ignore-installed --prefix=$TARGET_APPDIR/usr -r requirements.txt
+        python3.11 -m pip install --break-system-packages --upgrade --isolated --no-input --ignore-installed --prefix=$TARGET_APPDIR/usr -r ../../src/requirements.txt
 
         export PIP_CONFIG_FILE=$HOME/.pip/pip.conf
-        python3.11 -m pip install --break-system-packages --upgrade --isolated --no-input --ignore-installed --prefix=$TARGET_APPDIR/usr ../../src/dist/testium-{{APP_VERSION}}-py3-none-any.whl
+        # Install the wheel with the [lsp] extra so `testium lsp` (pygls) works
+        # from the AppImage. The extra pulls pygls/lsprotocol/cattrs/attrs from
+        # the index (network is available at build time, see get-pip above).
+        python3.11 -m pip install --break-system-packages --upgrade --isolated --no-input --ignore-installed --prefix=$TARGET_APPDIR/usr "../../src/dist/testium-{{APP_VERSION}}-py3-none-any.whl[lsp]"
 
 
 AppImage:

package/appimage/build.sh

@@ -1,12 +1,63 @@
-#!/usr/bin/bash
+#!/bin/bash
+# Build the testium AppImage inside a Debian container (Podman or Docker).
+# The resulting .AppImage file is written to this directory.
 
-export APP_VERSION=$(<../../src/VERSION)
+set -e
 
-appimage-builder --recipe AppImageBuilder.yml
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+APP_VERSION="$(<"$REPO_ROOT/src/VERSION")"
 
-RESULT=$?
-if [ -n "$1" ] && [ "$1" = "install" ]; then
-    if [ $RESULT -eq 0 ]; then
-        install -v "testium-${APP_VERSION}-x86_64.AppImage" "${HOME}/.local/bin/testium"
-    fi
+if command -v podman &>/dev/null; then
+    RUNTIME=podman
+elif command -v docker &>/dev/null; then
+    RUNTIME=docker
+else
+    echo "Error: neither podman nor docker found." >&2
+    exit 1
+fi
+echo "Using $RUNTIME — building testium $APP_VERSION AppImage..."
+
+# APPIMAGE_APPDIR_TMPFS (set by build_all --ram) bind-mounts a host tmpfs dir at
+# the AppDir build path, keeping the ~1 GB AppDir churn off slow storage.
+APPDIR_MOUNT=""
+if [ -n "$APPIMAGE_APPDIR_TMPFS" ]; then
+    mkdir -p "$APPIMAGE_APPDIR_TMPFS"
+    APPDIR_MOUNT="-v $APPIMAGE_APPDIR_TMPFS:/work/package/appimage/AppDir"
+fi
+
+# APPIMAGE_EXTRACT_AND_RUN=1 lets appimagetool run without FUSE in the container.
+$RUNTIME run --rm \
+    --privileged \
+    -e APPIMAGE_EXTRACT_AND_RUN=1 \
+    -v "$REPO_ROOT:/work" \
+    $APPDIR_MOUNT \
+    -w /work/package/appimage \
+    debian:bookworm bash -c "
+        set -e
+        export DEBIAN_FRONTEND=noninteractive
+
+        apt-get update -qq
+        apt-get install -y -qq \
+            python3 python3-pip python3-venv python3-build \
+            dpkg-dev fakeroot squashfs-tools wget curl file binutils \
+            libglib2.0-0 patchelf zsync > /dev/null
+
+        # Build the wheel
+        cd /work/src
+        python3 -m build --wheel --outdir dist/ > /dev/null
+        cd /work/package/appimage
+
+        # Install appimage-builder
+        pip3 install appimage-builder --quiet --break-system-packages
+
+        # Run the build
+        export APP_VERSION=$APP_VERSION
+        appimage-builder --recipe AppImageBuilder.yml --skip-test
+    "
+
+APPIMAGE_FILE=$(ls -1t Testium-*-x86_64.AppImage 2>/dev/null | head -1)
+echo "Done: ${APPIMAGE_FILE}"
+
+if [ "${1}" = "install" ] && [ -n "${APPIMAGE_FILE}" ]; then
+    install -v "${APPIMAGE_FILE}" "${HOME}/.local/bin/testium"
 fi

package/appimage/requirements.txt

@@ -1,3 +0,0 @@
-tables
-pandas
-scapy

package/flatpak/build.sh

@@ -5,4 +5,30 @@
 # flatpak install flathub org.kde.Sdk//6.10
 # flatpak install flathub io.qt.PySide.BaseApp//6.10
 
-flatpak-builder --user --verbose --force-clean --install build org.testium.Testium.yaml
+set -e
+
+# Build + install local. FLATPAK_BUILDDIR / FLATPAK_STATEDIR / FLATPAK_REPODIR
+# (set by build_all --ram) redirect the build dir, the state dir
+# (.flatpak-builder) and the ostree repo to tmpfs. flatpak-builder hardlinks
+# between the state dir and the build dir, so they MUST be on the same
+# filesystem — hence the state dir moves to tmpfs too (its download cache then
+# doesn't persist across --ram runs).
+BUILDDIR="${FLATPAK_BUILDDIR:-build}"
+STATEDIR="${FLATPAK_STATEDIR:-.flatpak-builder}"
+REPODIR="${FLATPAK_REPODIR:-repo}"
+flatpak-builder --user --verbose --force-clean --install --state-dir="$STATEDIR" --repo="$REPODIR" "$BUILDDIR" org.testium.Testium.yaml
+
+# Génère le bundle distribuable
+flatpak build-bundle "$REPODIR" testium.flatpak org.testium.Testium
+echo "Bundle généré : $(pwd)/testium.flatpak"
+
+# Crée ~/.local/bin/testium pour pouvoir taper "testium" en console
+WRAPPER="$HOME/.local/bin/testium"
+mkdir -p "$HOME/.local/bin"
+cat > "$WRAPPER" <<'EOF'
+#!/bin/sh
+exec flatpak run org.testium.Testium "$@"
+EOF
+chmod +x "$WRAPPER"
+echo "Wrapper installé : $WRAPPER"
+echo "Assurez-vous que ~/.local/bin est dans votre PATH."

package/flatpak/org.testium.Testium-mime.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
+  <mime-type type="application/x-testium">
+    <comment>Testium test script</comment>
+    <glob pattern="*.tum"/>
+  </mime-type>
+</mime-info>

package/flatpak/org.testium.Testium.desktop

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Name=Testium
+GenericName=Test Sequencer
+Comment=YAML-based test sequencer and runner
+Exec=testium %f
+Icon=org.testium.Testium
+Type=Application
+Categories=Development;
+MimeType=application/x-testium;
+StartupNotify=true

package/flatpak/org.testium.Testium.yaml

@@ -13,7 +13,14 @@ finish-args:
   - --socket=wayland
   - --device=dri
   - --share=network
-  - --filesystem=home # Optionnel : si votre testium doit lire des fichiers utilisateurs
+  - --filesystem=home
+  - --filesystem=/tmp
+  - --filesystem=host-os
+  # Allow flatpak-spawn --host to launch host binaries (Python, Lua, git…)
+  # outside the sandbox. Required because the sandbox glibc/ABI is
+  # incompatible with arbitrary host shared libraries — we route py_func and
+  # lua_func through the host instead.
+  - --talk-name=org.freedesktop.Flatpak
 
 build-options:
   build-args:
@@ -21,6 +28,23 @@ build-options:
 
 modules:
   - python3-requirements.json
+
+  # Language-server deps for `testium lsp` (pygls + lsprotocol + cattrs + attrs
+  # + typing_extensions). Installed from PyPI at build time — the build already
+  # runs with --share=network (see build-options). The core runtime deps stay
+  # offline-pinned in python3-requirements.json; these are pure-python wheels,
+  # hence --only-binary=:all: (no compilation, deterministic).
+  - name: python3-lsp
+    buildsystem: simple
+    build-options:
+      build-args:
+        - --share=network
+    build-commands:
+      # Whole command single-quoted: the ':all: ' colon-space would otherwise
+      # make YAML parse this list item as a mapping, silently dropping the
+      # command (flatpak-builder then runs an empty module — installs nothing).
+      - 'pip3 install --prefix=${FLATPAK_DEST} --only-binary=:all: "pygls>=1.3"'
+
   # 1. Dépendances Python tierces (HORS PySide6)
   # Utilisez flatpak-pip-generator pour vos autres libs (ex: pyserial, requests, etc.)
   # - name: python3-requirements
@@ -41,18 +65,41 @@ modules:
     sources:
       - type: dir
         path: ../../src
+      - type: file
+        path: org.testium.Testium.desktop
+      - type: file
+        path: org.testium.Testium-mime.xml
+      - type: file
+        path: ../../package/testium.png
     build-commands:
-      # On installe le code source dans /app/lib/testium
+      # Code source
       - mkdir -p /app/lib
-      - cp -r . /app/lib/
+      - cp -r testium /app/lib/
+      - cp VERSION /app/lib/testium/VERSION
 
-      # Création du launcher exécutable
+      # Launcher exécutable
       - mkdir -p /app/bin
       - |
         cat <<EOF > /app/bin/testium
         #!/bin/sh
-        # On ajoute le code source et l'extension PySide6 au PYTHONPATH
+        export TESTIUM_VERSION="\$(cat /app/lib/testium/VERSION 2>/dev/null || echo unknown)"
         export PYTHONPATH="/app/lib/testium:/usr/lib/sdk/pyside6/lib/python3.13/site-packages:\$PYTHONPATH"
-        exec python3 /app/lib/testium "\$@"
+        # Expose host binaries (git, python3, lua, …) for subprocess lookups.
+        # PATH is appended (not prepended) so the main process keeps the sandbox python3.
+        export PATH="\$PATH:/run/host/usr/local/bin:/run/host/usr/bin:/run/host/bin"
+        export GIT_PYTHON_GIT_EXECUTABLE="/run/host/usr/bin/git"
+        exec /usr/bin/python3 /app/lib/testium "\$@"
         EOF
       - chmod +x /app/bin/testium
+
+      # Icône
+      - mkdir -p /app/share/icons/hicolor/256x256/apps
+      - cp testium.png /app/share/icons/hicolor/256x256/apps/org.testium.Testium.png
+
+      # Entrée menu
+      - mkdir -p /app/share/applications
+      - cp org.testium.Testium.desktop /app/share/applications/
+
+      # Type MIME pour .tum
+      - mkdir -p /app/share/mime/packages
+      - cp org.testium.Testium-mime.xml /app/share/mime/packages/

package/pyinstaller/build.sh

@@ -2,11 +2,15 @@
 
 SCRIPT_DIR=$(realpath $( dirname "$0"))
 
-rm -r "${SCRIPT_DIR}/build" "${SCRIPT_DIR}/dist"
+rm -rf "${SCRIPT_DIR}/build" "${SCRIPT_DIR}/dist"
 
 pwd=$(pwd)
 cd ${SCRIPT_DIR}
-pyinstaller testium.spec
+# PYI_WORKPATH (set by build_all --ram) puts the big intermediate build tree on
+# tmpfs; dist/ stays local so build_all can collect the binary.
+WORKARG=""
+[ -n "$PYI_WORKPATH" ] && WORKARG="--workpath $PYI_WORKPATH"
+pyinstaller $WORKARG testium.spec
 RESULT=$?
 if [ -n "$1" ] && [ "$1" = "install" ]; then
     if [ $RESULT -eq 0 ]; then

package/pyinstaller/testium.spec

@@ -1,5 +1,21 @@
 # -*- mode: python ; coding: utf-8 -*-
 import os
+from PyInstaller.utils.hooks import collect_submodules
+
+# Language-server dependencies for `testium lsp`. pygls/lsprotocol register
+# converters and features dynamically, so we collect their submodules wholesale
+# and force-import their pure-python deps (cattrs/attrs/typing_extensions).
+# The testium lsp modules are imported lazily by the CLI dispatch
+# (`from lsp.server import serve`), which PyInstaller's static analysis misses —
+# hence the explicit names. No source files need bundling: the schema export is
+# now fully declarative (PARAMS + ACTIONS class attributes), so it no longer
+# reads .py source via inspect.getsource (which fails in a frozen build).
+_LSP_HIDDEN = (
+    collect_submodules("pygls")
+    + collect_submodules("lsprotocol")
+    + ["cattrs", "attr", "attrs", "typing_extensions",
+       "lsp", "lsp.server", "lsp.schema"]
+)
 
 # junit_xml is imported by post_exec scripts running under the *host* Python,
 # not the frozen interpreter — so bundling it via hiddenimports alone is not
@@ -54,7 +70,7 @@ a = Analysis(
                    "colorama",
                    "matplotlib",
                    "junit_xml",
-                   "lxml"],
+                   "lxml"] + _LSP_HIDDEN,
     hookspath=[],
     hooksconfig={},
     runtime_hooks=[],
@@ -73,7 +89,9 @@ exe = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    # UPX is CPU+IO heavy for a marginal size gain — build_all --ram sets
+    # TESTIUM_NO_UPX=1 to skip it (much faster on slow/flash storage).
+    upx=not os.environ.get("TESTIUM_NO_UPX"),
     upx_exclude=[],
     runtime_tmpdir=None,
     console=True,

release_note.txt

@@ -1,3 +1,85 @@
+version 0.2.2
+==============
+- Flatpak sandbox issue fixed for term console. Now a term console is
+  exactly like a host console.
+- Persistence fix of dialogs in case of flatpak.
+
+version 0.2.1
+==============
+- Faster test loading, especially for large tests built from jinja
+  templates and ``!include``: compiled jinja templates are cached and
+  reused (a file included many times is compiled once), rendering happens
+  in memory instead of through a temporary file, and YAML is parsed with
+  the libyaml C loader when available. Typical load time is 3-6x lower on
+  include / template-heavy tests; behaviour is unchanged.
+- Fix: a nested list holding more than one step under ``steps`` no longer
+  duplicates its entries while the step tree is built.
+- New load-time benchmark under ``test/benchmark/`` (synthetic-tree
+  generator + in-process timing harness) to measure the load pipeline.
+
+version 0.2
+==============
+- Test items: each item type now declares its accepted parameters
+  (``PARAMS = ParamSet(...)``). Typos in a ``.tum`` are surfaced as a
+  WARN listing the accepted names instead of being silently ignored;
+  missing required parameters error out at load time with the source
+  ``.tum`` file as context. No change to valid existing tests.
+- Editor support: testium now ships a language server. ``testium lsp``
+  gives ``.tum`` files item-type completion, hover documentation and an
+  outline view in any LSP-capable editor (a VSCode / VSCodium client is
+  provided separately). ``testium schema`` dumps the item/parameter
+  schema as JSON. The server works from every channel — bundled in the
+  binary / Flatpak / AppImage, and pulled by ``pip install testium[lsp]``
+  for wheel installs.
+- build_all.sh: the four heavy channels now build in parallel (results
+  reported as each finishes; Ctrl+C stops them cleanly). New ``--ram``
+  option builds on a tmpfs (``/dev/shm``) and skips UPX for much faster
+  packaging on USB-stick / SD-card storage.
+
+version 0.1.3
+==============
+- Stop interrupts engaged blocking steps (console, py_func, lua_func,
+  json_rpc, sleep) within ~200 ms instead of waiting for the step
+  to finish.
+- GUI Start / Stop / Pause flow simplified.
+- lua_func: a function returning nil is no longer reported as a failure.
+- ``-d python_bin=...`` and the GUI ``python_bin`` preference now reach
+  the eval subprocess (used to be silently ignored). ``param.yaml`` can
+  also override ``python_bin`` for py_func / cycle / post_exec.
+- Validation suite: ``test/validation/run.sh`` (and ``run.bat``)
+  runs the suite inside a dedicated venv in the system temp dir.
+- build_all.sh: ``release_note.txt`` and the user manual copied into
+  ``dist/``; warning if the file has no entry for the version being built.
+- Flatpak: every GUI file/directory dialog (open test, save report, log
+  path, default report/log dirs, python/lua interpreter pickers) now
+  bypasses the XDG document portal — the v0.1.2 fix was only on the
+  "open test" dialog.
+- Flatpak: py_func / lua_func / run sub-instance now execute on the host
+  via flatpak-spawn, lifting the previous glibc/ABI incompatibility that
+  prevented user-configured host Python or Lua interpreters from being
+  reached from the sandbox.
+- Validation suite: single entry point with ``--mode source|wheel|
+  pyinstaller|flatpak|appimage`` to validate any packaging channel
+  against the same item set; reports are stamped per mode.
+- GUI: the "Run tum" test item now uses the testium logo.
+
+version 0.1.2
+==============
+- Flatpak: opening a test from the GUI now correctly finds its companion
+  files (param.yaml, .py scripts, ...).
+
+version 0.1.1
+==============
+- New install channels: Flatpak bundle and AppImage. The AppImage runs
+  on any distribution (built inside a Debian container).
+- About dialog: version is now correct in Flatpak and AppImage builds
+  (used to display "unknown").
+- GUI dialogs no longer hang on pure-Wayland sessions.
+- Plot "last values" API: more tolerant timeout on loaded machines.
+- run item: `testium_path` and `python_bin` parameters removed —
+  sub-instances are launched in the same packaging mode as the parent.
+- License: EUPL-1.2.
+
 version 0.1
 ==============
 - Start of the project

scripts/build_env.sh

@@ -20,6 +20,12 @@ if [ "$?" -ne 0 ]; then
     echo "venv must be installed on the host distribution."
     exit -1
 fi
+# Check if venv is installed
+python3 -c "import ensurepip"
+if [ "$?" -ne 0 ]; then
+    echo "ensurepip must be installed on the host distribution."
+    exit -1
+fi
 
 # Install the virtual environment if needed
 if [ ! -d "$PY_VENV_DIR" ]; then
@@ -27,6 +33,11 @@ if [ ! -d "$PY_VENV_DIR" ]; then
     python3 -m venv "$PY_VENV_DIR"
     source "$PY_VENV_DIR/bin/activate"
     pip install --extra-index-url https://pypi.python.org/pypi -r $REQ_PATH
+    # Language-server deps (the pyproject [lsp] extra). Installed here so the
+    # source run AND the PyInstaller build — both of which use this venv — can
+    # start / collect the `testium lsp` server. pip-installed wheel users get
+    # them via `pip install testium[lsp]` instead.
+    pip install --extra-index-url https://pypi.python.org/pypi "pygls>=1.3"
     # Validation suite plugin used to verify the report-exporter
     # entry-points discovery end-to-end.
     FAKE_EXPORTER_DIR="$(dirname "$REQ_PATH")/../test/validation/fake_exporter"

src/LICENSE

@@ -0,0 +1,315 @@
+Copyright (c) 2025-2026 François Dausseur
+
+Licensed under the EUPL
+
+
+                       EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                       EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the 'EUPL') applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+        Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- 'The Licence': this Licence.
+
+- 'The Original Work': the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- 'Derivative Works': the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This Licence
+  does not define the extent of modification or dependence on the Original
+  Work required in order to classify a work as a Derivative Work; this extent
+  is determined by copyright law applicable in the country mentioned in
+  Article 15.
+
+- 'The Work': the Original Work or its Derivative Works.
+
+- 'The Source Code': the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- 'The Executable Code': any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+
+- 'The Licensor': the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- 'Contributor(s)': any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- 'The Licensee' or 'You': any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- 'Distribution' or 'Communication': any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright
+vested in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights
+to any patents held by the Licensor, to the extent necessary to make use of
+the rights granted on the Work under this Licence.
+
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices
+and a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will
+be done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence — for example by communicating 'EUPL v. 1.2 only'. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+'Compatible Licence' refers to the licences listed in the appendix attached
+to this Licence. Should the Licensee's obligations under the Compatible
+Licence conflict with his/her obligations under this Licence, the obligations
+of the Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the
+Work and reproducing the content of the copyright notice.
+
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work
+granted hereunder is owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that
+he/she has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under
+the terms of this Licence.
+
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+'bugs' inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an 'as is'
+basis and without warranties of any kind concerning the Work, including
+without limitation merchantability, fitness for a particular purpose, absence
+of defects or errors, accuracy, non-infringement of intellectual property
+rights other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a
+condition for the grant of any rights to the Work.
+
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to
+natural persons, the Licensor will in no event be liable for any direct or
+indirect, material or moral, damages of any kind, arising out of the Licence
+or of the use of the Work, including without limitation, damages for loss of
+goodwill, work stoppage, computer failure or malfunction, loss of data or any
+commercial damage, even if the Licensor has been advised of the possibility
+of such damage. However, the Licensor will be liable under statutory product
+liability laws as far such laws apply to the Work.
+
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted
+against such Contributor by the fact You have accepted any warranty or
+additional liability.
+
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon 'I
+agree' placed under the bottom of a window displaying the text of this
+Licence or by affirming consent in any other similar way, in accordance with
+the rules of applicable law. Clicking on that icon indicates your clear and
+irrevocable acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative
+Work or the Distribution or Communication by You of the Work or copies
+thereof.
+
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the
+Work from a remote location) the distribution channel or media (for example,
+a website) must at least provide to the public the information requested by
+the applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically
+upon any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make
+it valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the
+  Court of Justice of the European Union, as laid down in article 272 of the
+  Treaty on the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive
+  jurisdiction of the competent court where the Licensor resides or conducts
+  its primary business.
+
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member
+  State where the Licensor has his seat, resides or has his registered
+  office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+
+                                  Appendix
+
+
+'Compatible Licences' according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
+  Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the
+above licences without producing a new version of the EUPL, as long as they
+provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a
+new EUPL version.

src/VERSION

@@ -1 +1 @@
-0.2
+0.2.2

src/pyproject.toml

@@ -30,6 +30,12 @@ dependencies = [
 ]
 dynamic = ["version"]
 
+[project.optional-dependencies]
+# `pip install testium[lsp]` adds the language-server dependencies. The
+# stdio-only LSP server (`testium lsp`) reuses the schema export from the
+# core install; pygls is the only marginal cost.
+lsp = ["pygls>=1.3"]
+
 [project.scripts]
 testium = "testium:main"
 

src/testium/__init__.py

@@ -11,6 +11,40 @@ sys.path.append(os.path.abspath(ourpath.parent))
 import interpreter.utils.constants as cst
 
 def main():
+    # Force UTF-8 on stdout/stderr so the runner's output survives a legacy
+    # console code page (Windows cp1252 can't encode box-drawing/accented
+    # chars). Only the stream encoders change; the locale default used for
+    # config files is untouched.
+    for _stream in (sys.stdout, sys.stderr):
+        try:
+            _stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass  # no stdout (frozen GUI) or non-reconfigurable stream
+
+    # Subcommand dispatch (must run *before* argparse so neither 'schema' nor
+    # 'lsp' has to share the GUI/batch flag surface). The subcommands also
+    # skip the multiprocessing 'spawn' setup which is only meaningful for the
+    # main runtime — schema is a pure stdout dump and lsp speaks JSON-RPC
+    # over stdio without ever forking a test process.
+    if len(sys.argv) >= 2 and sys.argv[1] in ("schema", "lsp"):
+        sub = sys.argv[1]
+        if sub == "schema":
+            from lsp.schema import dump_all_schemas_json
+            print(dump_all_schemas_json())
+            return
+        # lsp
+        try:
+            from lsp.server import serve
+        except ImportError as e:
+            print(
+                f"testium lsp: language server dependencies missing ({e.name}). "
+                "Install with: pip install 'testium[lsp]'",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        serve()
+        return
+
     # This line sets the method for the "Process" function. It is required for Linux
     # support of the test dialogs.
     multiprocessing.set_start_method('spawn')

src/testium/api/console.py

@@ -11,6 +11,7 @@ import threading
 from telnetlib3 import Telnet, DO, WILL, WONT, TTYPE, IAC, SB, SE, theNULL
 
 TIMEOUT_NULL = 0.000001
+STOP_POLL_INTERVAL = 0.2
 
 
 class BytesStore(object):
@@ -123,12 +124,14 @@ A {classname}.close() is missing somewhere in your code !'.format(classname=type
         #    c = ''
         return c
 
-    def read_until(self, match, timeout=None, return_data=False, mute=False):
+    def read_until(self, match, timeout=None, return_data=False, mute=False, should_stop=None):
         """
         read until the string 'match is found
             If timeout is not set (None), this function runs indefinitely
             If timeout is set to zero, this function returns immediately
             If mute is set to True the characters read from the console will not be displayed
+            If should_stop is a callable, it is polled between reads (every STOP_POLL_INTERVAL
+            at most) and the loop exits early — like a timeout — when it returns True.
 
             If function fails (because of a timeout) it will return a 'status' integer set to -1
             otherwise it will return 0.
@@ -139,13 +142,6 @@ A {classname}.close() is missing somewhere in your code !'.format(classname=type
         status = -1
         if not match:
             raise ValueError('match parameter can not be empty')
-        # replace all '\r' by '\n' as any '\r' read will undergo the same replacement
-        # match = match.replace('\r\n', '\n')
-        # match = match.replace('\r', '')
-
-        # update the console timeout in conformity with what is required.
-
-        self.set_read_timeout(timeout)
 
         if timeout is None:
             timeout = 1000000
@@ -159,6 +155,7 @@ A {classname}.close() is missing somewhere in your code !'.format(classname=type
         # buffer is empty
         # Otherwise we are waiting for the timeout to rise
         if timeout < TIMEOUT_NULL:
+            self.set_read_timeout(0)
             data = self.readchar(0)
 
             while (status < 0) and ((data is not None) and (data != b'')):
@@ -191,39 +188,45 @@ A {classname}.close() is missing somewhere in your code !'.format(classname=type
 
         # Timeout different than zero
         else:
+            # Poll in short chunks so a stop request is honored within
+            # STOP_POLL_INTERVAL, regardless of the per-protocol blocking
+            # behavior of readchar().
+            self.set_read_timeout(STOP_POLL_INTERVAL)
 
             time_is_out = threading.Event()
             timer = threading.Timer(timeout, lambda: time_is_out.set())
             timer.start()
 
-            # We are waiting for the timeout to rise
+            try:
+                while (status < 0) and (not time_is_out.is_set()):
+                    if should_stop is not None and should_stop():
+                        break
 
-            while (status < 0) and (not time_is_out.isSet()):
-
-                data = self.readchar(timeout)
-                if data is not None:
-                    data = self._compute_char(data)
-                    if data != '':
-                        if not mute:
-                            self.string_buffer += data
-                        read_data += data
-
-                        search_deque.append(data)
-                        if search_deque == match_deque:
-                            timer.cancel()
-                            status = 0
-                            if (not mute) and (data != '\n'):
-                                self.string_buffer += '\n'
-
-                        if data == '\n' or (status >= 0):
-                            # the datas are written line by line for display optimisation in GUI mode
+                    data = self.readchar(STOP_POLL_INTERVAL)
+                    if data is not None:
+                        data = self._compute_char(data)
+                        if data != '':
                             if not mute:
-                                self.string_buffer = self.string_buffer.replace('\r\n', '\n')
-                                self.string_buffer = self.string_buffer.replace('\r', '')
-                                self.stream.write(self.string_buffer)
+                                self.string_buffer += data
+                            read_data += data
 
-                            date_str = str(datetime.now()).split('.')[0].split(' ')[1]
-                            self.string_buffer = '[{} {}]'.format(date_str, self.name)
+                            search_deque.append(data)
+                            if search_deque == match_deque:
+                                status = 0
+                                if (not mute) and (data != '\n'):
+                                    self.string_buffer += '\n'
+
+                            if data == '\n' or (status >= 0):
+                                # the datas are written line by line for display optimisation in GUI mode
+                                if not mute:
+                                    self.string_buffer = self.string_buffer.replace('\r\n', '\n')
+                                    self.string_buffer = self.string_buffer.replace('\r', '')
+                                    self.stream.write(self.string_buffer)
+
+                                date_str = str(datetime.now()).split('.')[0].split(' ')[1]
+                                self.string_buffer = '[{} {}]'.format(date_str, self.name)
+            finally:
+                timer.cancel()
 
         if return_data:
             return status, read_data

src/testium/api/runtime_plot.py

@@ -1,5 +1,6 @@
 import sys
 import os
+import queue
 import multiprocessing as mp
 from threading import Timer
 from time import sleep, monotonic
@@ -367,7 +368,7 @@ class RuntimePlot:
             self.msg_queue_in.get()
         self.msg_queue_out.put({"command": "last_values"})
         try:
-            res = self.msg_queue_in.get(timeout=1)
-        except:
+            res = self.msg_queue_in.get(timeout=5)
+        except queue.Empty:
             raise ETUMRuntimeError(f"Impossible to retrieve the last values of the \"{self.name}\" plot")
         return res

src/testium/api/termconsole.py

@@ -81,9 +81,13 @@ class TermConsole(Console):
                                    bufsize=0)
 
         else:
-            self.term = pexpect.spawn(  shell_cmd,
-                                        echo=False,
-                                        cwd=self.ppath)
+            # In Flatpak this returns a `flatpak-spawn --host` wrapper so the
+            # console behaves like a host shell (matching py_func / lua_func /
+            # run); elsewhere it's the chosen command unchanged.
+            from interpreter.utils import bins
+            argv = bins.host_console_command(shell_cmd, self.ppath)
+            self.term = pexpect.spawn(argv[0], args=argv[1:],
+                                      echo=False, cwd=self.ppath)
 
         self.q = BytesStore()
         self.t = threading.Thread(target=self.enqueue_output)

src/testium/interpreter/process.py

@@ -16,6 +16,7 @@ from interpreter.utils.test_init import (
     env_init,
     prepare_global,
     update_global,
+    apply_overrides,
     set_standard_gd_keys,
     test_run_init,
     test_run_header,
@@ -210,6 +211,19 @@ class TestProcess(Process):
 
                 env_init()
 
+                # Apply GUI defaults and CLI defines to the global dict
+                # *before* eval_proc starts: bins.python_bin() reads
+                # ``python_bin`` from gd on its very first call (during
+                # eval_process_init) and caches the result. Without this,
+                # ``-d python_bin=...`` and the GUI ``python_bin`` preference
+                # would only take effect for items spawned *after* the cache
+                # was already populated with the auto-discovered interpreter,
+                # i.e. they would silently be ignored for eval_proc itself.
+                # _load_initial_params re-applies the same overrides after
+                # ``prepare_global()`` clears gd, so the gd value stays in
+                # sync with the cached path.
+                apply_overrides(self.__defs, self.__gui_defaults)
+
                 # Creation of the python evaluation process for loading of the complete test
                 eval_proc = eval_process_init(api_request, 10, test_dir)
                 eval_proc.start()

src/testium/interpreter/test_items/dialog_choices_files/choices_dialog.py

@@ -221,6 +221,11 @@ def main(args, conn=None):
 
     if conn:
         settings.setValue(SettingsLastChoices, result)
+        # Flush before sending: the parent terminates this subprocess as soon
+        # as it reads the result, so the QSettings destructor never runs and
+        # the write would race the kill (lost under Flatpak — see the
+        # tested-references dialog for the full rationale).
+        settings.sync()
         conn.send([result, success])
         conn.close()
     else:

src/testium/interpreter/test_items/dialog_env.py

@@ -10,6 +10,8 @@ import os
 def setup():
     """Configure the Qt environment for dialog subprocess usage."""
     if sys.platform.startswith('linux'):
-        # On Linux/Wayland, force X11 (via XWayland) to avoid crashes
-        # when Qt is initialized inside a multiprocessing subprocess.
-        os.environ['QT_QPA_PLATFORM'] = 'xcb'
+        if os.environ.get('DISPLAY'):
+            # X11 available: force xcb to avoid crashes in multiprocessing subprocesses.
+            os.environ['QT_QPA_PLATFORM'] = 'xcb'
+        elif os.environ.get('WAYLAND_DISPLAY'):
+            os.environ['QT_QPA_PLATFORM'] = 'wayland'

src/testium/interpreter/test_items/item_actions/__init__.py

@@ -5,6 +5,13 @@ from interpreter.test_items.item_actions.action import TestItemAction
 
 
 class TestItemActions(TestItem):
+    # Declarative action registry: subclasses set ``ACTIONS = {yaml_key: class}``
+    # as a class attribute (mirroring ``PARAMS``). It is read here to populate
+    # the runtime registry, and read identically by the schema export — no
+    # instantiation or source inspection required. ``register_actions()`` stays
+    # available as an imperative escape hatch for dynamic/conditional cases.
+    ACTIONS = {}
+
     def __init__(
         self, item_type, dict_actions, parent=None, status_queue=None, filename=""
     ):
@@ -12,7 +19,7 @@ class TestItemActions(TestItem):
         super().__init__(dict_actions, parent, status_queue, filename=filename)
         self._type = item_type
         self.is_container = False
-        self.action_classes = {}
+        self.action_classes = dict(type(self).ACTIONS)
         self.actions_token = None
         self.actions = []
         try:
@@ -24,6 +31,9 @@ class TestItemActions(TestItem):
             )
 
     def register_actions(self, **args: TestItemAction):
+        # Imperative escape hatch. The declarative ``ACTIONS`` class attribute
+        # covers every current subclass; use this only to add actions that
+        # can't be known at class-definition time (e.g. platform-conditional).
         for action_name, action_class in args.items():
             self.action_classes.update({action_name: action_class})
 

src/testium/interpreter/test_items/test_item.py

@@ -5,6 +5,9 @@ from copy import deepcopy
 from interpreter.test_items.test_result import TestResult, TestValue
 import api.testium as tm
 from interpreter.utils.params import TestItemParams
+from interpreter.utils.param_decl import (
+    Param, ParamSet, LIST, BLOCK, unknown_keys, missing_required,
+)
 from interpreter.utils.constants import TestItemType as cst_type
 from interpreter.utils.eval import eval_to_boolean, evaluate, post_evaluate
 from runtime.tum_except import ETUMSyntaxError, item_load_context
@@ -13,6 +16,32 @@ LOG_TEST_STOP = '<----- step "{}" finished'
 LOG_TEST_START = '-----> step "{}" started'
 
 
+# Parameters accepted by every test item, regardless of its type. Subclasses
+# concatenate their own ``PARAMS`` to this set; the merged result drives
+# unknown-param warnings and (later) the LSP schema export.
+COMMON_PARAMS = ParamSet(
+    Param("name",            doc="Display name shown in the GUI tree and reports."),
+    Param("doc",             doc="Free-form documentation; surfaced in tooltips."),
+    Param("skipped",         doc="If truthy, the step is skipped (static expression, "
+                                 "evaluated at load time)."),
+    Param("key",             doc="Report key used to classify the result "
+                                 "(typically <test>_PASS or <test>_FAIL)."),
+    Param("stop_on_failure", doc="If true, abort the surrounding container on failure."),
+    Param("execute_on_stop", doc="If true, run this step even when its container "
+                                 "is being stopped (cleanup)."),
+    Param("process_result",  doc="Post-evaluation expression applied to the test result."),
+    Param("store_result",    doc="Global-dict key in which to store the test result."),
+    Param("expected_result", doc="Expected outcome; the step is failed if it doesn't match."),
+    Param("no_fail",         doc="If truthy, never report a FAILURE for this step."),
+    Param("report",          doc="Per-step reporting override."),
+    Param("condition",       doc="Optional gating expression evaluated before each "
+                                 "run; false ⇒ the step is skipped."),
+    Param("steps",  kind=LIST, doc="Children (for container items)."),
+    Param("seq_filename",    doc="(internal) source .tum file of this step; injected "
+                                 "by the loader."),
+)
+
+
 class TestItem:
     pass
 
@@ -20,52 +49,64 @@ class TestItem:
 def test_run(f):
     @wraps(f)
     def wrapper(self):
-        if not self.skipped:
-            if self.enabled:
-                self.run_test_init()
-                # Conditional execution
-                raw_condition = self._prms.getParam(
-                    "condition", default=None, processed=False
-                )
-                if raw_condition is None:
-                    condition = True
-                else:
-                    c = self._prms.expanse(raw_condition)
-                    if isinstance(c, bool):
-                        condition = c
-                    else:
-                        condition = False
-                        c = False
-
-                    if raw_condition == c:
-                        msg = f'"{c}"'
-                    else:
-                        msg = f'"{raw_condition}" --> "{c}"'
-
-                # Do we have to skip the test because of a true condition ?
-                if condition:
-                    if not raw_condition is None:
-                        msg = "condition met: " + msg
-                        self.result.reported = {"input_condition": msg}
-                        print(msg)
-                    # Test preparation
-                    self.run_before_test()
-                    # Test execution
-                    f(self)
-                else:
-                    msg = "condition not met: " + msg
-                    self.result.set(TestValue.NORUN, msg)
-                    self.result.reported = {"input_condition": msg}
-                self.run_test_end()
-            else:
-                self.result.set(TestValue.NORUN, "test disabled")
-                print("Test is disabled.")
-        else:
+        if self.skipped:
             self.result.set(TestValue.NORUN, "test skipped")
             print("Test is skipped.")
+            return self.result
+        
+        if not self.enabled:
+            self.result.set(TestValue.NORUN, "test disabled")
+            print("Test is disabled.")
+            return self.result
+
+        self.run_test_init()
+
+        while self._is_paused:
+            sleep(0.2)
+            if self.isStopped() :
+                self.result.set(TestValue.NORUN, "test stopped")
+                print("Test is Stopped.")
+                self._is_stopped = False    # Restore state for next run
+                return self.result
+
+        # Conditional execution
+        raw_condition = self._prms.getParam(
+            "condition", default=None, processed=False
+        )
+        if raw_condition is None:
+            condition = True
+        else:
+            c = self._prms.expanse(raw_condition)
+            if isinstance(c, bool):
+                condition = c
+            else:
+                condition = False
+                c = False
+
+            if raw_condition == c:
+                msg = f'"{c}"'
+            else:
+                msg = f'"{raw_condition}" --> "{c}"'
+
+        # Do we have to skip the test because of a true condition ?
+        if condition:
+            if not raw_condition is None:
+                msg = "condition met: " + msg
+                self.result.reported = {"input_condition": msg}
+                print(msg)
+            # Test preparation
+            self.run_before_test()
+            # Test execution
+            f(self)
+        else:
+            msg = "condition not met: " + msg
+            self.result.set(TestValue.NORUN, msg)
+            self.result.reported = {"input_condition": msg}
+        self.run_test_end()
 
         return self.result
 
+
     return wrapper
 
 
@@ -85,6 +126,11 @@ def test_data(item: TestItem, child: dict) -> dict:
 
 
 class TestItem:
+    # Subclasses override with their own ParamSet to opt into the declarative
+    # validation. While ``PARAMS`` is empty / unset, the base class skips the
+    # unknown-param check for this item type — keeps the migration incremental.
+    PARAMS = None
+
     def __init__(
         self, dict_item: dict = None, parent: TestItem = None, status_queue=None, filename = ""
     ):
@@ -122,6 +168,13 @@ class TestItem:
             # creation of the params object
             self._prms = TestItemParams(dict_item, parent)
 
+            # Declarative-params validation. Only kicks in when the concrete
+            # subclass declares ``PARAMS`` — items not yet migrated stay
+            # silent. Warnings (not errors) during the migration window so
+            # existing .tum files don't break suddenly; will be flipped to
+            # errors once every item has migrated.
+            self._validate_declared_params(dict_item)
+
             # getting parameters for the test item
             try:
                 self._name = self._prms.getParam("name", default="", processed=True)
@@ -178,6 +231,36 @@ class TestItem:
 
         self.result = TestResult(self, TestValue.FAILURE, "Failure by default")
 
+    def _validate_declared_params(self, dict_item):
+        """Warn on unknown / missing-required params, if PARAMS is declared.
+
+        The check is opt-in per subclass: it only runs when the concrete
+        class sets a non-empty ``PARAMS`` attribute. Items not yet migrated
+        produce no diagnostics — preserving the historical "silently accept
+        anything" behavior until they get their declaration.
+        """
+        if not self.PARAMS:
+            return
+        # ``self._type`` is the parent root type at this point (subclasses set
+        # it after super().__init__), so use the class name as a stable label
+        # in diagnostics. ``self._name`` was preset to the type name by every
+        # subclass before super() ran, which gives a useful prefix.
+        label = f"{type(self).__name__} '{self._name}'"
+        declared = COMMON_PARAMS + self.PARAMS
+        unknown = unknown_keys(declared, dict_item)
+        if unknown:
+            accepted = ", ".join(sorted(declared.names()))
+            for k in unknown:
+                tm.print_warn(
+                    f"{label}: unknown parameter '{k}'. Accepted: {accepted}."
+                )
+        missing = missing_required(declared, dict_item)
+        for k in missing:
+            raise ETUMSyntaxError(
+                f"{label}: required parameter '{k}' is missing.",
+                self._seq_filename,
+            )
+
     def _filter_dict_item(self, dict_item):
         # Stores the content of the step to be displayed
         # in the GUI
@@ -255,8 +338,6 @@ class TestItem:
         self._sendStatusStarted()
         if self._is_breakpoint:
             self._is_paused = True
-            while self._is_paused:
-                sleep(0.2)
 
         if self.is_container:
             self.report.incLevel()
@@ -274,9 +355,6 @@ class TestItem:
         if self.is_container:
             self.report.decLevel()
 
-        while self._is_paused:
-            sleep(0.2)
-
         # Post evaluation of the test result
         self.process_result()
         # expected_result treatment
@@ -310,6 +388,7 @@ class TestItem:
             self.process_report(self._reported)
         self.report.addTest(self, self.result, rk)
         self._sendStatusFinished()
+        
 
     def process_result(self):
         if self._post_eval is None:

src/testium/interpreter/test_items/test_item_check.py

@@ -5,11 +5,22 @@ from runtime.tum_except import ETUMSyntaxError, item_load_context
 import api.testium as tm
 from interpreter.utils.constants import TestItemType as cst
 from interpreter.utils.eval import evaluate
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 
 class TestItemCheckValue(TestItem):
     """check item usage.
     check usage:{check: {name: check my func output, steps: ['$(pfn_echo) < 5']}}
     """
+
+    PARAMS = ParamSet(
+        Param("values", kind=LIST, required=True,
+              doc="List of expressions to evaluate. Each is expanded then "
+                  "evaluated; non-truthy results fail the check."),
+        # 'steps' is intentionally not redeclared here — it's the deprecated
+        # alias of 'values' and is already accepted by COMMON_PARAMS for
+        # container items. A runtime warning is emitted when 'steps' is used.
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_CHECK.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_choices_dialog.py

@@ -2,11 +2,25 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, BLOCK
 from runtime.tum_except import item_load_context
 import api.testium as tm
 
 
 class TestItemChoicesDialog(TestItemDialogBase):
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Prompt shown above the list of choices."),
+        Param("choices", kind=BLOCK, required=True,
+              doc="Tree of choices: either a list of strings, or a nested "
+                  "mapping {label: subchoices, ...} to build a multi-level menu."),
+        Param("icon", default=None,
+              doc="Default icon name shown next to each choice."),
+        Param("auto_result", default=None,
+              doc="Batch-mode selection (path or label). None ⇒ FAILURE."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_CHOICES_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_console.py

@@ -10,6 +10,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.item_actions import TestItemActions
 from interpreter.test_items.item_actions.action import TestItemAction
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from interpreter.test_items.test_result import TestResult, TestValue
 
 
@@ -21,6 +22,38 @@ class TestItemConsoleAction(TestItemAction):
 
 
 class TestItemConsoleOpen(TestItemConsoleAction):
+
+    PARAMS = ParamSet(
+        Param("protocol", required=True,
+              doc="Transport: 'telnet', 'ssh', 'rawtcp', 'serial' or 'terminal'."),
+        Param("write_delay", default=0,
+              doc="Inter-character write delay in ms (slow devices)."),
+        Param("log", doc="Path to a log file capturing the console traffic."),
+        Param("overwrite_log", default=True,
+              doc="If true, truncate the log file at open; else append."),
+        # telnet
+        Param("telnet_host", doc="Hostname/IP for the telnet target."),
+        Param("telnet_port", default=69, doc="TCP port for telnet."),
+        # ssh
+        Param("ssh_host", doc="Hostname/IP for the SSH target."),
+        Param("ssh_user", doc="SSH login user."),
+        Param("ssh_pwd",  doc="SSH password (if key-based auth is not used)."),
+        # rawtcp
+        Param("tcp_host", doc="Hostname/IP for a raw-TCP connection."),
+        Param("tcp_port", doc="TCP port for a raw-TCP connection."),
+        # serial
+        Param("serial_port",     doc="Serial device path (e.g. /dev/ttyUSB0 or COM3)."),
+        Param("serial_baudrate", doc="Serial baudrate."),
+        Param("buffered", default=True,
+              doc="If true, the serial console buffers received bytes between reads."),
+        # terminal
+        Param("terminal_path",
+              doc="Working directory for the local terminal protocol."),
+        Param("shell",
+              doc="Shell command used for the local terminal protocol "
+                  "(default: 'cmd.exe' on Windows, '/usr/bin/env bash' elsewhere)."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -283,6 +316,17 @@ class TestItemConsoleWriteLn(TestItemConsoleAction):
 
 
 class TestItemConsoleReadUntil(TestItemConsoleAction):
+
+    PARAMS = ParamSet(
+        Param("expected", required=True,
+              doc="Regex matched against incoming console output until found "
+                  "or until timeout."),
+        Param("timeout", default=-1,
+              doc="Seconds before giving up. Negative means infinite."),
+        Param("mute", default=False,
+              doc="If true, don't echo received bytes to testium's stdout/log."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -307,11 +351,17 @@ class TestItemConsoleReadUntil(TestItemConsoleAction):
 
         try:
             status, data = cons.read_until(
-                ru, timeout=read_timeout, return_data=True, mute=mute
+                ru, timeout=read_timeout, return_data=True, mute=mute,
+                should_stop=self.isStopped,
             )
             if status == 0:
                 self.result.set(TestValue.SUCCESS)
                 self.result.value = data
+            elif self.isStopped():
+                self.result.set(
+                    result=TestValue.FAILURE,
+                    message="Console read aborted on stop request",
+                )
             else:
                 self.result.set(result=TestValue.FAILURE, message="No matching text")
             if mute:
@@ -330,18 +380,27 @@ class TestItemConsoleReadUntil(TestItemConsoleAction):
 
 
 class TestItemConsole(TestItemActions):
+
+    PARAMS = ParamSet(
+        Param("console_name", required=True,
+              doc="Identifier of the console — used by every nested action to "
+                  "reach back the same transport. Multiple consoles can coexist "
+                  "as long as their names differ."),
+    )
+
+    ACTIONS = {
+        "open": TestItemConsoleOpen,
+        "close": TestItemConsoleClose,
+        "write": TestItemConsoleWrite,
+        "writeln": TestItemConsoleWriteLn,
+        "read_until": TestItemConsoleReadUntil,
+    }
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         super().__init__(
             cst.TYPE_CONSOLE, dict_item, parent, status_queue, filename=filename
         )
 
-        self.register_actions(
-            open=TestItemConsoleOpen,
-            close=TestItemConsoleClose,
-            write=TestItemConsoleWrite,
-            writeln=TestItemConsoleWriteLn,
-            read_until=TestItemConsoleReadUntil,
-        )
         self.actions_token = {}
 
         global console

src/testium/interpreter/test_items/test_item_cycle.py

@@ -8,9 +8,36 @@ from interpreter.test_items.test_result import TestResult, TestValue
 import api.testium as tm
 from interpreter.utils.params import TestItemParams
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, BLOCK
+
+
+# Sub-block validation: 'cycle' accepts an 'exit_condition:' mapping whose
+# own params are reported here so unknown keys inside it can be flagged
+# during a future Block-aware diagnostic pass. For now the parent only
+# declares that 'exit_condition' is an accepted top-level key.
+EXIT_CONDITION_PARAMS = ParamSet(
+    Param("time",      doc="HH:MM time of day after which the loop exits."),
+    Param("value",     doc="Expression; when truthy the loop exits."),
+    Param("file",      doc="Python file containing the exit-condition function."),
+    Param("func_name", doc="Function name in 'file' returning the exit value."),
+    Param("param",     doc="Arguments passed to the exit function."),
+    Param("eval", default="",
+          doc="Post-evaluation expression applied to the function's return."),
+)
 
 
 class TestItemCycle(TestItem):
+
+    PARAMS = ParamSet(
+        Param("iterator",
+              doc="Iterable (or string expanding to one) driving the loop. "
+                  "The current value is exposed as $(loop_param)."),
+        Param("exit_condition", kind=BLOCK,
+              doc="Optional block stopping the loop early: combine 'time', "
+                  "'value', or a 'file'+'func_name' pair (with optional "
+                  "'param' and 'eval')."),
+    )
+
     def __init__(self, dict_cycle, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_CYCLE.item_name
         super().__init__(dict_cycle, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_git.py

@@ -1,6 +1,7 @@
 from interpreter.test_items.test_item import (TestItem, test_run)
 from interpreter.test_items.test_result import (TestValue)
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 from runtime.tum_except import ETUMParamError, ETUMSyntaxError
 import interpreter.utils.version as git
 
@@ -8,6 +9,13 @@ class TestItemGit(TestItem):
     """
     This item expect only one parameter which is a string or list of string being the path to the git folder
     """
+
+    PARAMS = ParamSet(
+        Param("repo", kind=LIST, required=True,
+              doc="Path to a git checkout, or list of such paths. Each is "
+                  "reported with its current version (tag + dirty state)."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_GIT.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_group.py

@@ -1,10 +1,17 @@
 from interpreter.test_items.test_item import (TestItem, test_run)
 from interpreter.test_items.test_result import (TestResult, TestValue)
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import ParamSet
 from runtime.tum_except import ETUMSyntaxError
 import api.testium as tm
 
 class TestItemGroup(TestItem):
+
+    # 'group' has no item-specific parameters; 'steps' is handled by COMMON_PARAMS.
+    # Declaring an empty ParamSet still opts in to unknown-param validation
+    # (e.g. typo 'stop_on_failures').
+    PARAMS = ParamSet()
+
     def __init__(self, dict_cycle, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_GROUP.item_name
         super().__init__(dict_cycle, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_image_dialog.py

@@ -4,6 +4,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import item_load_context
 import api.testium as tm
 
@@ -12,6 +13,17 @@ class TestItemImageDialog(TestItemDialogBase):
     """dialog_image item usage.
     dialog_image name: Nice image, question: could you press the red button, filename: img.jpg
     """
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Prompt shown above the image."),
+        Param("filename", required=True,
+              doc="Path to the image file (relative to the test directory or absolute)."),
+        Param("auto_result", default=None,
+              doc="Outcome used in batch/non-interactive mode. Truthy ⇒ SUCCESS, "
+                  "None ⇒ FAILURE."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_IMAGE_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_json_rpc/__init__.py

@@ -11,6 +11,7 @@ from interpreter.test_items.item_actions.action import TestItemAction
 
 from interpreter.utils.constants import TestItemType as cst
 from interpreter.utils.eval import evaluate
+from interpreter.utils.param_decl import Param, ParamSet, BLOCK
 
 from interpreter.test_items.test_item_json_rpc.jsonrpc_adapters import (
     JrpcAdapter,
@@ -76,6 +77,20 @@ class TestItemJSRPCActionClose(TestItemAction):
 
 class TestItemJSRPCActionQuery(TestItemAction):
 
+    PARAMS = ParamSet(
+        Param("method", required=True,
+              doc="JSON-RPC method name to call."),
+        Param("params",
+              doc="Parameters payload (list, dict or scalar) sent to the method."),
+        Param("id", default="rand",
+              doc="JSON-RPC request id. 'rand' (default) ⇒ a random integer is used."),
+        Param("no_wait", default=False,
+              doc="If true, send the request without waiting for a response."),
+        Param("timeout", default=None,
+              doc="Seconds to wait for a response. None ⇒ inherits the transport "
+                  "default."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -105,6 +120,7 @@ class TestItemJSRPCActionQuery(TestItemAction):
             jrpc_id = randint(1, (2**32) - 1)
         send_only = self._prms.expanse(self._send_only)
         timeout = self._prms.expanse(self._timeout)
+        self.token.set_should_stop(self.isStopped)
         try:
             success, result = self.token.query(
                 meth, obj, jrpc_id, send_only, timeout=timeout
@@ -128,6 +144,13 @@ class TestItemJSRPCActionQuery(TestItemAction):
 
 class TestItemJSRPCActionReceive(TestItemAction):
 
+    PARAMS = ParamSet(
+        Param("id", required=True,
+              doc="JSON-RPC request id whose response we expect."),
+        Param("timeout", default=None,
+              doc="Seconds to wait for the response. None ⇒ transport default."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -146,6 +169,7 @@ class TestItemJSRPCActionReceive(TestItemAction):
     def execute(self):
         timeout = self._prms.expanse(self._timeout)
         jrpc_id = self._prms.expanse(self._jrpc_id)
+        self.token.set_should_stop(self.isStopped)
 
         try:
             success, result = self.token.receive(jrpc_id, timeout)
@@ -170,6 +194,29 @@ class TestItemJSON_RPC(TestItemActions):
     This item TBD
     """
 
+    PARAMS = ParamSet(
+        Param("console", kind=BLOCK,
+              doc="Console-transport block: {console_name, …}. Either 'console' "
+                  "or 'udp' must be set."),
+        Param("udp", kind=BLOCK,
+              doc="UDP-transport block: {host, port, …}. Either 'console' or "
+                  "'udp' must be set."),
+        Param("version", default="1.0",
+              doc="JSON-RPC protocol version ('1.0' or '2.0')."),
+        Param("timeout", required=True,
+              doc="Default seconds to wait for a JSON-RPC response across all "
+                  "child query/receive actions."),
+        Param("mute", default=False,
+              doc="If true, don't echo wire traffic to the log."),
+    )
+
+    ACTIONS = {
+        "open": TestItemJSRPCActionOpen,
+        "close": TestItemJSRPCActionClose,
+        "query": TestItemJSRPCActionQuery,
+        "receive": TestItemJSRPCActionReceive,
+    }
+
     def __init__(
         self, dict_item: dict, parent: TestItem = None, status_queue=None, filename=""
     ):
@@ -177,13 +224,6 @@ class TestItemJSON_RPC(TestItemActions):
             cst.TYPE_JSON_RPC, dict_item, parent, status_queue, filename=filename
         )
 
-        self.register_actions(
-            open=TestItemJSRPCActionOpen,
-            close=TestItemJSRPCActionClose,
-            query=TestItemJSRPCActionQuery,
-            receive=TestItemJSRPCActionReceive,
-        )
-
         # Console specific params
         self._console = self._prms.getParam("console", required=False)
         # UDP specific params

src/testium/interpreter/test_items/test_item_json_rpc/jsonrpc_adapters.py

@@ -2,10 +2,11 @@ import json
 import socket
 import re
 import struct
+import time
 
 from runtime.tum_except import ETUMRuntimeError
 import api.testium as tm
-from api.console import Console
+from api.console import Console, STOP_POLL_INTERVAL
 
 
 def is_ip_address(address):
@@ -45,9 +46,16 @@ class JrpcAdapter:
         self._jrpc_version = version
         self._mute = mute
         self._timeout = timeout
+        # Optional callable polled by _receive() implementations to abort
+        # waits early when the test is being stopped. Set by the test item
+        # action before each query/receive call.
+        self._should_stop = None
         if not (version == "1.0" or version == "2.0"):
             raise ETUMRuntimeError("Invalid JSONRPC version passed.")
 
+    def set_should_stop(self, cb):
+        self._should_stop = cb
+
     @property
     def timeout(self):
         return self._timeout
@@ -249,32 +257,38 @@ class JrpcUdpAdapter(JrpcAdapter):
             print(f"  | sent to @{self._server}:{self._snd_port}")
 
     def _receive(self, timeout: float) -> str:
+        # Poll in short chunks so a stop request is honored within
+        # STOP_POLL_INTERVAL.
+        self.sock.settimeout(STOP_POLL_INTERVAL)
+        deadline = time.monotonic() + float(timeout)
+        data = None
+        addr = None
+        while True:
+            if self._should_stop is not None and self._should_stop():
+                raise ETUMRuntimeError("JSONRPC udp receive aborted on stop request.")
+            try:
+                data, addr = self.sock.recvfrom(self._bufsize)
+                break
+            except socket.timeout:
+                if time.monotonic() >= deadline:
+                    raise ETUMRuntimeError(
+                        "JSONRPC udp answer took too long. Try to increase the timeout."
+                    )
 
-        # configures the reception timeout
-        self.sock.settimeout(timeout)
-
-        # Receives the answer from the server
-        try:
-            data, addr = self.sock.recvfrom(self._bufsize)
-
-            # In case of buffer overload we chose to complain
-            if len(data) >= self._bufsize:
-                raise ETUMRuntimeError(
-                    "JSONRPC udp answer size overflow. Try to increase the bufsize"
-                )
-
-            # Converts binary to string
-            res = data.decode()
-
-            # Don't log if mute
-            if not self._mute:
-                print(f"  | UDP answer: '{res}'")
-                print(f"  | received from @{addr[0]}:{addr[1]}")
-
-        except socket.timeout:
+        # In case of buffer overload we chose to complain
+        if len(data) >= self._bufsize:
             raise ETUMRuntimeError(
-                "JSONRPC udp answer took too long. Try to increase the timeout."
+                "JSONRPC udp answer size overflow. Try to increase the bufsize"
             )
+
+        # Converts binary to string
+        res = data.decode()
+
+        # Don't log if mute
+        if not self._mute:
+            print(f"  | UDP answer: '{res}'")
+            print(f"  | received from @{addr[0]}:{addr[1]}")
+
         return res
 
     def _build_query(self, method: str, obj, jrpc_id: int):
@@ -339,11 +353,16 @@ class JrpcConsoleAdapter(JrpcAdapter):
 
     def _receive(self, timeout: float) -> str:
         status, data = self._cons.read_until(
-            self._endswith, timeout, return_data=True, mute=self._mute
+            self._endswith, timeout, return_data=True, mute=self._mute,
+            should_stop=self._should_stop,
         )
 
         # if we did not receive anything, we complain
         if not status == 0:
+            if self._should_stop is not None and self._should_stop():
+                raise ETUMRuntimeError(
+                    f"JSONRPC console receive aborted on stop request."
+                )
             raise ETUMRuntimeError(
                 f"The '{self._cons.name}' console did not answer in the requested time."
             )

src/testium/interpreter/test_items/test_item_let.py

@@ -8,12 +8,20 @@ from interpreter.test_items.test_result import (TestResult, TestValue)
 from runtime.tum_except import ETUMSyntaxError, item_load_context
 import api.testium as tm
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 
 class TestItemLet(TestItem):
     """let item usage.
     let values: {variable1: a, variable2: /dev/ttyUSB0, variable3: 115200}
     let eval: {conditional_exec: "random.randint(1, 4)"}
     """
+
+    PARAMS = ParamSet(
+        Param("values", kind=LIST, required=True,
+              doc="Mapping (or list of single-pair mappings) of global-dict "
+                  "key → value to set. Values are expanded at execution time."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_LET.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_lua_func.py

@@ -11,6 +11,7 @@ import api.testium as tm
 from interpreter.utils.lua_func_exec import LuaFuncExecEngine
 from interpreter.utils.api_srv import api_request
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 
 _LUA_FUNC_CONTEXTS_KEY = "_lua_func_contexts"
 
@@ -21,6 +22,21 @@ class TestItemLuaFunc(TestItem):
     Optional: context_id: <id>  — share a persistent process with other lua_func items using the same id.
     """
 
+    PARAMS = ParamSet(
+        Param("file", required=True,
+              doc="Path to the .lua file containing the function."),
+        Param("func_name", required=True,
+              doc="Name of the function to call in the file."),
+        Param("param", kind=LIST,
+              doc="Arguments passed to the function. Each entry is expanded "
+                  "before the call. Special tokens $(loop_param) / $(loop_index) "
+                  "resolve from the surrounding cycle."),
+        Param("context_id", default=None,
+              doc="If set, the lua_func subprocess is kept alive and reused by "
+                  "every other lua_func item with the same context_id — enables "
+                  "shared in-memory state between successive calls."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_LUA_FUNCTION.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)
@@ -45,6 +61,18 @@ class TestItemLuaFunc(TestItem):
             tm.setgd(_LUA_FUNC_CONTEXTS_KEY, contexts)
         return contexts[ctx_id], True
 
+    def stop(self):
+        super().stop()
+        # Tear down the worker so any in-flight func_call returns promptly.
+        # join() clears _rpc/_process so a subsequent item reusing the same
+        # context_id can restart the engine cleanly.
+        try:
+            engine, _ = self._get_engine()
+            engine.stop()
+            engine.join()
+        except Exception:
+            pass
+
     @test_run
     def execute(self):
         self.result.set(
@@ -96,9 +124,15 @@ Is the lua environnment well defined in the "LUA_PATH" and "LUA_CPATH" variables
 
             return
 
+        except ConnectionAbortedError:
+            self.result.set(TestValue.FAILURE, "lua_func aborted on stop request")
+            print("lua_func aborted on stop request.")
         except:
             traceback.print_exception(*sys.exc_info())
-            self.result.set(
-                TestValue.FAILURE,
-                'Unrecoverable "lua_func" item error from {}'.format(self.func_name),
-            )
+            if self.isStopped():
+                self.result.set(TestValue.FAILURE, "lua_func aborted on stop request")
+            else:
+                self.result.set(
+                    TestValue.FAILURE,
+                    'Unrecoverable "lua_func" item error from {}'.format(self.func_name),
+                )

src/testium/interpreter/test_items/test_item_msg_dialog.py

@@ -5,6 +5,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import item_load_context
 
 
@@ -12,6 +13,15 @@ class TestItemMsgDialog(TestItemDialogBase):
     """dialog_message item usage.
     dialog_message name: Nice message, question: Open the door and press OK
     """
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Message body shown to the user. Multi-line strings are supported."),
+        Param("auto_result", default=None,
+              doc="Outcome used in batch/non-interactive mode instead of waiting "
+                  "for the user. Truthy ⇒ SUCCESS, None ⇒ FAILURE."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_MESSAGE_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_note_dialog.py

@@ -2,11 +2,23 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import item_load_context
 import api.testium as tm
 
 
 class TestItemNoteDialog(TestItemDialogBase):
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Prompt shown above the note input field."),
+        Param("auto_result", default=None,
+              doc="Batch-mode outcome: None ⇒ FAILURE, 'cancel' ⇒ cancelled, "
+                  "any other truthy ⇒ SUCCESS with auto_value."),
+        Param("auto_value", default=None,
+              doc="Note text used in batch mode when auto_result is set."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_NOTE_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_parallel.py

@@ -6,6 +6,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestResult, TestValue
 from interpreter.utils.constants import TestItemType as cst
 from interpreter.utils.eval import eval_to_boolean
+from interpreter.utils.param_decl import Param, ParamSet, LIST, BLOCK, Enum
 from runtime.tum_except import ETUMSyntaxError
 from runtime.string_queue import StringQueue
 from runtime.stdout_redirect import stdio_redir
@@ -15,6 +16,12 @@ class TestItemParallelBranch(TestItemContainer):
     """One branch of a parallel item. Runs its children sequentially,
     optionally waiting for a condition before starting."""
 
+    PARAMS = ParamSet(
+        Param("wait_for", kind=BLOCK,
+              doc="Optional block {condition, timeout} that defers the branch "
+                  "start until the condition is truthy (or the timeout elapses)."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         super().__init__(cst.TYPE_PARALLEL_BRANCH, dict_item, parent, status_queue, filename=filename)
         self._wait_condition = None
@@ -87,6 +94,15 @@ class TestItemParallel(TestItemContainer):
                   - ...
     """
 
+    PARAMS = ParamSet(
+        Param("branches", kind=LIST, required=True,
+              doc="List of branch blocks (each branch holds its own 'steps' "
+                  "and optional 'wait_for')."),
+        Param("sync", kind=Enum("all", "any"), default="all",
+              doc="'all' (default) waits for every branch; 'any' returns as "
+                  "soon as the first branch completes."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         branches = dict_item.get("branches", [])
         if not branches:

src/testium/interpreter/test_items/test_item_py_func.py

@@ -11,6 +11,7 @@ import api.testium as tm
 from interpreter.utils.py_func_exec import PyFuncExecEngine
 from interpreter.utils.api_srv import api_request
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 
 _PY_FUNC_CONTEXTS_KEY = "_py_func_contexts"
 
@@ -21,6 +22,21 @@ class TestItemPyFunc(TestItem):
     Optional: context_id: <id>  — share a persistent process with other py_func items using the same id.
     """
 
+    PARAMS = ParamSet(
+        Param("file", required=True,
+              doc="Path to the .py file containing the function."),
+        Param("func_name", required=True,
+              doc="Name of the function to call in the file."),
+        Param("param", kind=LIST,
+              doc="Arguments passed to the function. Each entry is expanded "
+                  "before the call. Special tokens $(loop_param) / $(loop_index) "
+                  "resolve from the surrounding cycle."),
+        Param("context_id", default=None,
+              doc="If set, the py_func subprocess is kept alive and reused by "
+                  "every other py_func item with the same context_id — enables "
+                  "shared in-memory state between successive calls."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_PY_FUNCTION.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)
@@ -45,6 +61,18 @@ class TestItemPyFunc(TestItem):
             tm.setgd(_PY_FUNC_CONTEXTS_KEY, contexts)
         return contexts[ctx_id], True
 
+    def stop(self):
+        super().stop()
+        # Tear down the worker so any in-flight func_call returns promptly.
+        # join() clears _rpc/_process so a subsequent item reusing the same
+        # context_id can restart the engine cleanly.
+        try:
+            engine, _ = self._get_engine()
+            engine.stop()
+            engine.join()
+        except Exception:
+            pass
+
     @test_run
     def execute(self):
         self.result.set(
@@ -94,9 +122,15 @@ python_bin = {tm.gd("python_bin", "no python path defined")}"""
 
             return
 
+        except ConnectionAbortedError:
+            self.result.set(TestValue.FAILURE, "py_func aborted on stop request")
+            print("py_func aborted on stop request.")
         except:
             traceback.print_exception(*sys.exc_info())
-            self.result.set(
-                TestValue.FAILURE,
-                'Unrecoverable "py_func" item error from {}'.format(self.func_name),
-            )
+            if self.isStopped():
+                self.result.set(TestValue.FAILURE, "py_func aborted on stop request")
+            else:
+                self.result.set(
+                    TestValue.FAILURE,
+                    'Unrecoverable "py_func" item error from {}'.format(self.func_name),
+                )

src/testium/interpreter/test_items/test_item_question_dialog.py

@@ -2,6 +2,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import item_load_context
 
 
@@ -9,6 +10,14 @@ class TestItemQuestionDialog(TestItemDialogBase):
     """dialog_question item usage.
     dialog_question name: Nice question, question: "If OK, press OK, If not, press cancel"
     """
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Yes/No prompt presented to the user."),
+        Param("auto_result", default=None,
+              doc="Batch-mode answer ('yes'/'no' or truthy/falsy). None ⇒ FAILURE."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_QUESTION_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_report.py

@@ -3,9 +3,17 @@ from interpreter.test_items.test_item import (TestItem, test_run)
 from interpreter.test_items.test_result import (TestValue)
 from runtime.tum_except import ETUMSyntaxError
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 from interpreter.test_report.test_report import Export
 
 class TestItemReport(TestItem):
+
+    PARAMS = ParamSet(
+        Param("export", kind=LIST, required=True,
+              doc="List of exporters to run (junit, sqlite, …). Each entry is a "
+                  "mapping describing the exporter type and its parameters."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_REPORT.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_run.py

@@ -10,9 +10,42 @@ from interpreter.test_items.test_item import (TestItem, test_run)
 from interpreter.test_items.test_result import (TestValue)
 import api.testium as tm
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import ETUMSyntaxError, ETUMRuntimeError, item_load_context
 
 
+def _testium_launch_cmd():
+    """Command prefix to launch a fresh testium instance, runtime-aware.
+
+    AppImage / Flatpak / PyInstaller / wheel / source all need a different
+    entry point than just the path to __main__.py (which may be a .py inside
+    a read-only bundle, or unreachable from the sub-instance's cwd).
+    """
+    # AppImage: the env var holds the path to the .AppImage file itself.
+    appimage = os.environ.get("APPIMAGE")
+    if appimage:
+        return [appimage]
+    # Flatpak: re-launch via the Flatpak app id, but on the host side —
+    # the `flatpak` CLI cannot run inside our sandbox (no D-Bus access to the
+    # host Flatpak service, and the host binary would need host libs that are
+    # ABI-incompatible with the sandbox runtime). flatpak-spawn proxies the
+    # call to the host via org.freedesktop.Flatpak (allowed by --talk-name in
+    # the manifest).
+    if os.path.isfile("/.flatpak-info"):
+        return ["flatpak-spawn", "--host",
+                "flatpak", "run", "org.testium.Testium"]
+    # PyInstaller frozen exe: sys.executable is the binary itself.
+    if getattr(sys, "frozen", False):
+        return [sys.executable]
+    # Source / wheel: re-use the same Python with the same entry point that
+    # launched this instance, made absolute so cwd changes in the sub-instance
+    # don't break the lookup. argv[0] is either:
+    #  - the package directory (source: `python3 src/testium ...`)
+    #  - the console_scripts wrapper (wheel: `/usr/bin/testium`)
+    # Both are runnable as `python <argv0>`.
+    return [sys.executable, os.path.abspath(sys.argv[0])]
+
+
 def nowInBetween(start, end):
     """
     Check wether current time is within boundaries
@@ -25,6 +58,25 @@ def nowInBetween(start, end):
 
 
 class TestItemRun(TestItem):
+
+    PARAMS = ParamSet(
+        Param("tum", required=True,
+              doc="Path to the .tum file launched in a fresh testium instance."),
+        Param("param_file", default="",
+              doc="Optional path to a param.yaml passed to the sub-instance."),
+        Param("log_file", default="",
+              doc="Path where the sub-instance writes its log."),
+        Param("report_file", default="",
+              doc="Path where the sub-instance writes its report."),
+        Param("start_time",
+              doc="HH:MM time of day after which the sub-instance may run."),
+        Param("end_time",
+              doc="HH:MM time of day after which the sub-instance no longer runs."),
+        Param("wait_for_exec",
+              doc="If true, block until the time window opens. Requires both "
+                  "start_time and end_time."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_RUN.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)
@@ -33,8 +85,6 @@ class TestItemRun(TestItem):
         with item_load_context(self.cmd(), self.name(), self.seqFilename()):
             self.tum_file = self._prms.getParam('tum', required=True)
             self.param_file = self._prms.getParam('param_file', default='')
-            self.python_bin = self._prms.getParam('python_bin', default='')
-            self.testium_path = self._prms.getParam('testium_path', default='')
             self.log_path = self._prms.getParam('log_file', default='')
             self.report_path = self._prms.getParam('report_file', default='')
             self.start_time = self._prms.getParam('start_time')
@@ -52,18 +102,9 @@ class TestItemRun(TestItem):
                     '"{}" file could not be found'.format(file_path))
             self.tum_file = file_path
             pf = self._prms.expanse(self.param_file)
-            pp = self._prms.expanse(self.python_bin)
-            sp = self._prms.expanse(self.testium_path)
             lp = self._prms.expanse(self.log_path)
             rp = self._prms.expanse(self.report_path)
-            cmd = []
-            if sp == '':
-                sp = sys.argv[0]
-            if pp != '':
-                cmd.append(pp)
-            elif not os.path.isfile(sp) or not os.access(sp, os.X_OK):
-                cmd.append(sys.executable)
-            cmd.append(sp)
+            cmd = _testium_launch_cmd()
             if tm.text_mode():
                 cmd.append("-b")
             else:

src/testium/interpreter/test_items/test_item_runtime_plot.py

@@ -11,6 +11,7 @@ from interpreter.test_items.item_actions import TestItemActions
 from interpreter.test_items.item_actions.action import TestItemAction
 from interpreter.utils.constants import TestItemType as cst
 from interpreter.utils.eval import evaluate
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 
 
 class TestItemPlotAction(TestItemAction):
@@ -21,6 +22,12 @@ class TestItemPlotAction(TestItemAction):
 
 
 class TestItemPlotActionOpen(TestItemPlotAction):
+
+    PARAMS = ParamSet(
+        Param("log_path", default=None,
+              doc="Optional file to which the plot data are appended."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -57,6 +64,15 @@ class TestItemPlotActionOpen(TestItemPlotAction):
 
 
 class TestItemPlotActionClose(TestItemPlotAction):
+
+    PARAMS = ParamSet(
+        Param("wait_dialog_exit", default=False,
+              doc="If true, the close action blocks until the user closes the "
+                  "plot window (or timeout)."),
+        Param("timeout", default=-1,
+              doc="Seconds to wait when wait_dialog_exit is true. Negative ⇒ infinite."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -96,6 +112,20 @@ class TestItemPlotActionClose(TestItemPlotAction):
 
 
 class TestItemPlotActionPeriodic(TestItemPlotAction):
+
+    PARAMS = ParamSet(
+        Param("period", required=True,
+              doc="Seconds between two calls of the periodic function."),
+        Param("file", required=True,
+              doc="Path to the .py file holding the periodic function."),
+        Param("func_name", required=True,
+              doc="Name of the periodic function."),
+        Param("param", kind=LIST,
+              doc="Arguments passed to the periodic function on each call."),
+        Param("eval", default="",
+              doc="Post-evaluation applied to the function's return value."),
+    )
+
     def __init__(
         self, action_name, dict_item, parent=None, status_queue=None, filename=""
     ):
@@ -169,6 +199,13 @@ class TestItemPlotActionAdd(TestItemPlotAction):
 
 
 class TestItemPlotActionLastValues(TestItemPlotAction):
+
+    PARAMS = ParamSet(
+        Param("name", kind=LIST,
+              doc="List of plot variable names whose last sample is returned. "
+                  "Result is stored in $(plv_<plot_name>) as a dict."),
+    )
+
     def __init__(self, action_name, dict_item, parent=None, status_queue=None, filename=""):
         super().__init__(
             action_name, cst.TYPE_GRAPH_ACTION, dict_item, parent, status_queue, filename=filename
@@ -219,18 +256,25 @@ class TestItemPlotActionExport(TestItemPlotAction):
 
 
 class TestItemPlot(TestItemActions):
+
+    PARAMS = ParamSet(
+        Param("plot_name", required=True,
+              doc="Identifier of the plot window — referenced by every nested "
+                  "action and by $(plv_<plot_name>) for last-values output."),
+    )
+
+    ACTIONS = {
+        "open": TestItemPlotActionOpen,
+        "close": TestItemPlotActionClose,
+        "periodic": TestItemPlotActionPeriodic,
+        "add": TestItemPlotActionAdd,
+        "last_value": TestItemPlotActionLastValues,
+        "export": TestItemPlotActionExport,
+    }
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         super().__init__(
             cst.TYPE_GRAPH, dict_item, parent, status_queue, filename=filename
         )
 
-        self.register_actions(
-            open=TestItemPlotActionOpen,
-            close=TestItemPlotActionClose,
-            periodic=TestItemPlotActionPeriodic,
-            add=TestItemPlotActionAdd,
-            last_value=TestItemPlotActionLastValues,
-            export=TestItemPlotActionExport,
-        )
-
         self.actions_token = self._prms.getParam("plot_name", required=True)

src/testium/interpreter/test_items/test_item_sleep.py

@@ -7,6 +7,7 @@ import api.testium as tm
 from interpreter.test_items.test_item import (TestItem, test_run)
 from interpreter.test_items.test_result import (TestValue)
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import ETUMSyntaxError, ETUMRuntimeError, item_load_context
 
 class TestItemSleep(TestItem):
@@ -14,6 +15,15 @@ class TestItemSleep(TestItem):
     sleep timeout: 10
     """
 
+    PARAMS = ParamSet(
+        Param("timeout", required=True,
+              doc="Duration to sleep. Number of seconds, or a string "
+                  "like '1d 2h 30m 15s'."),
+        Param("dialog", default=False,
+              doc="If true, show a cancel dialog (GUI mode) or an interactive "
+                  "Ctrl+C-able countdown (text mode)."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_SLEEP.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)
@@ -80,4 +90,7 @@ class TestItemSleep(TestItem):
             end_time = _time.time() + float(timeout)
             while _time.time() < end_time and not self._is_stopped:
                 sleep(min(0.05, end_time - _time.time()))
-            self.result.set(TestValue.SUCCESS, 'Sleep %s sec' % (str(timeout)))
+            if self._is_stopped:
+                self.result.set(TestValue.FAILURE, 'Sleep aborted on stop request')
+            else:
+                self.result.set(TestValue.SUCCESS, 'Sleep %s sec' % (str(timeout)))

src/testium/interpreter/test_items/test_item_tested_references.py

@@ -2,11 +2,23 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 from runtime.tum_except import item_load_context
 import api.testium as tm
 
 
 class TestItemTestedRefsDialog(TestItemDialogBase):
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Prompt asking the operator to enter the tested references."),
+        Param("reference", kind=LIST,
+              doc="Pre-filled list of references shown in the dialog."),
+        Param("auto_result", default=None,
+              doc="Batch-mode outcome: None ⇒ FAILURE, truthy ⇒ SUCCESS with "
+                  "the pre-filled references."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_REFERENCE_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_unittest.py

@@ -11,6 +11,7 @@ from interpreter.test_items.test_item import (TestItem, test_run, LOG_TEST_STOP,
 from interpreter.test_items.test_result import (TestResult, TestValue)
 from interpreter.test_items.test_item import test_data
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet, LIST
 from runtime.stdout_redirect import stdio_redir
 
 class UnittestResult(TextTestResult):
@@ -95,6 +96,15 @@ class TestItemUnittestElement(TestItem):
 
 
 class TestItemUnittestFile(TestItem):
+
+    PARAMS = ParamSet(
+        Param("test_file", required=True,
+              doc="Path to the Python unittest file (TestCase subclass)."),
+        Param("test_method", kind=LIST,
+              doc="Optional list of method names to restrict the run to. "
+                  "When empty, every test_* method in the file is run."),
+    )
+
     def __init__(self, dict_item, parent = None, status_queue=None, filename=""):
         self._name = cst.TYPE_UNITTEST.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/test_item_value_dialog.py

@@ -2,6 +2,7 @@ from interpreter.test_items.test_item import test_run
 from interpreter.test_items.test_result import TestValue
 from interpreter.test_items.test_item_dialog_base import TestItemDialogBase, _is_text_mode, _is_interactive
 from interpreter.utils.constants import TestItemType as cst
+from interpreter.utils.param_decl import Param, ParamSet
 from runtime.tum_except import item_load_context
 import api.testium as tm
 
@@ -10,6 +11,19 @@ class TestItemValueDialog(TestItemDialogBase):
     """dialog_value item usage.
     dialog_value name: Enter value, question: "Which value did you measure?"
     """
+
+    PARAMS = ParamSet(
+        Param("question", required=True,
+              doc="Prompt shown above the value input field."),
+        Param("default", default="",
+              doc="Pre-filled value of the input field."),
+        Param("auto_result", default=None,
+              doc="Batch-mode outcome: None ⇒ FAILURE, 'cancel' ⇒ cancelled, "
+                  "any other truthy ⇒ SUCCESS with auto_value."),
+        Param("auto_value", default=None,
+              doc="Value used in batch mode when auto_result is set."),
+    )
+
     def __init__(self, dict_item, parent=None, status_queue=None, filename=""):
         self._name = cst.TYPE_VALUE_DLG.item_name
         super().__init__(dict_item, parent, status_queue, filename=filename)

src/testium/interpreter/test_items/tested_references_files/tested_refs_dialog.py

@@ -76,6 +76,12 @@ def main(args, conn=None):
 
     if conn:
         settings.setValue(SettingsLastReference, result)
+        # Flush to disk *before* handing the result back: as soon as the parent
+        # receives it on the pipe it terminates this subprocess (SIGTERM, no
+        # handler), so the QSettings destructor never runs. Without sync() the
+        # write races the kill and is lost — reliably so under Flatpak, where
+        # the .conf is atomically renamed on the slower ~/.var/app overlay.
+        settings.sync()
         conn.send([result, success])
         conn.close()
     else:

src/testium/interpreter/test_report/report_export_html.py

@@ -14,7 +14,7 @@ class ReportExportHTML(rpe.ReportExport):
         self.prepareFile()
         self.create_base()
         self.process_tests()
-        with open(self._file_name, 'w') as f:
+        with open(self._file_name, 'w', encoding="utf-8") as f:
             f.write(lxml.html.tostring(self.root, pretty_print=True).decode())
 
     def testsIterate(self, row):

src/testium/interpreter/test_report/report_export_junit.py

@@ -20,7 +20,7 @@ class ReportExportJUnit(rpe.ReportExport):
 
         ts = TestSuite(repname, test_cases=self.test_cases,
                        hostname=tm.gd('host_ip'))
-        with open(self._file_name, 'w') as f:
+        with open(self._file_name, 'w', encoding="utf-8") as f:
             TestSuite.to_file(f, [ts])
 
     def testsIterate(self, row):

src/testium/interpreter/test_set.py

@@ -29,6 +29,51 @@ def _build_item_path(item) -> str:
     return " > ".join(reversed(parts))
 
 
+def _flatten_actions(actions, out, parent_seq_name):
+    """Expand nested lists and included ``sequence`` entries into ``out`` as a
+    flat list of single test-item dicts, propagating each sequence's source
+    filename onto its items.
+
+    Replaces the previous approach, which spliced each entry into the step
+    list and rebuilt the whole list every time (O(n^2) over the step list, and
+    a rebuild that duplicated entries when a nested list held more than one
+    element). This single forward pass is linear.
+    """
+    for idx, action in enumerate(actions):
+        # a bare list raises its elements to the same level
+        if isinstance(action, (list, tuple)):
+            _flatten_actions(action, out, parent_seq_name)
+            continue
+        # a NoneType (e.g. pointing at an unused alias) contributes nothing
+        if action is None:
+            continue
+        # a 'sequence' (an included file) is spliced in, with its filename
+        # propagated onto each of its items
+        if isinstance(action, dict) and "sequence" in action:
+            sequence = action["sequence"]["data"]
+            f = action["sequence"]["filename"]
+            if isinstance(sequence, dict):
+                sequence = [{k: v} for k, v in sequence.items()]
+            # Case of an empty sequence
+            elif sequence is None:
+                tm.print_info(
+                    f"An empty sequence is loaded in '{parent_seq_name}'."
+                )
+                sequence = []
+            elif not isinstance(sequence, list):
+                raise ETUMSyntaxError(
+                    f"Syntax error in '{parent_seq_name}' step number {idx+1}. Sequence definition: '{str(action)}'",
+                    f
+                )
+            for s in sequence:
+                if isinstance(s, dict) and s:
+                    s[list(s.keys())[0]]["seq_filename"] = f
+            _flatten_actions(sequence, out, parent_seq_name)
+            continue
+
+        out.append(action)
+
+
 class TestSet:
     def __init__(
         self,
@@ -434,56 +479,16 @@ class TestSet:
                 f"No valid list of actions in sequence {parent_seq_name}",
                 file_name
             )
-        # first we merged to the same level 'sequence dict entries and list within the list
-        counter = 0
         test_dir = tm.gd("test_directory")
-        la = len(parent_seq_actions)
-        while counter < la:
-            action = parent_seq_actions[counter]
-            # if action is a list raise up to the the same level,
-            # ie insert action element into the parent_seq_actions
-            if isinstance(action, (list, tuple)):
-                parent_seq_actions[counter : counter + 1] = action
-                parent_seq_actions = (
-                    parent_seq_actions[:counter]
-                    + action
-                    + parent_seq_actions[counter + 1 :]
-                )
-                la = len(parent_seq_actions)
-                continue
-            # if action is a NoneType skip and continue
-            # (when pointing to an unused alias for instance)
-            if action is None:
-                counter += 1
-                continue
-            # if action is a sequence we insert its entry into the action list
-            if "sequence" in action:
-                sequence = action["sequence"]["data"]
-                f = action["sequence"]["filename"]
-                if isinstance(sequence, dict):
-                    sequence = [{k: v} for k, v in sequence.items()]
-                # Case of an empty sequence
-                elif sequence is None:
-                    tm.print_info(
-                        f"An empty sequence is loaded in '{parent_seq_name}'."
-                    )
-                    sequence = []
-                elif not isinstance(sequence, list):
-                    raise ETUMSyntaxError(
-                        f"Syntax error in '{parent_seq_name}' step number {counter+1}. Sequence definition: '{str(action)}'",
-                        f
-                    )
-                for s in sequence:
-                    s[list(s.keys())[0]]["seq_filename"] = f
-                parent_seq_actions = (
-                    parent_seq_actions[:counter]
-                    + sequence
-                    + parent_seq_actions[counter + 1 :]
-                )
-                la = len(parent_seq_actions)
-                continue
 
-            # Action is now for sure a list of dict of length 1
+        # Flatten nested lists and included 'sequence' entries to the same level
+        # in one linear pass (was an in-place splice + full list rebuild per
+        # entry: O(n^2) over the step list).
+        flat_actions = []
+        _flatten_actions(parent_seq_actions, flat_actions, parent_seq_name)
+
+        for action in flat_actions:
+            # Action is now for sure a dict of length 1
             k = list(action.keys())[0]
             if action[k].get("seq_filename", None) is None:
                 action[k]["seq_filename"] = file_name
@@ -546,8 +551,6 @@ class TestSet:
                     action[k]["seq_filename"]
                 )
 
-            counter += 1
-
         return ret
 
     def tree(self):

src/testium/interpreter/utils/bins.py

@@ -17,8 +17,12 @@ Public API
 ``reset()``             : clear the cache (mostly useful for tests)
 """
 
+import atexit
+import os
+import shlex
 import shutil
 import subprocess
+import tempfile
 
 import api.testium as tm
 from interpreter.utils.paths import sys_app_path_lin, sys_app_path_win
@@ -30,23 +34,256 @@ from runtime.tum_except import ETUMRuntimeError
 _PYTHON_CANDIDATES = ["python3", "python"]
 _LUA_CANDIDATES = ["lua", "lua5.5", "lua5.4", "lua5.3", "lua5.2", "lua5.1"]
 
+# Inside an AppImage, AppRun prepends $APPDIR/usr/bin to PATH and exports a
+# bundle-local PYTHONHOME / PYTHONPATH / LD_LIBRARY_PATH. We want py_func and
+# lua_func to run under the *host* interpreter (not the bundled one), so we
+# probe standard host bin dirs directly and scrub APPDIR-prefixed entries from
+# the env passed to host subprocesses.
+_APPIMAGE_HOST_DIRS = [
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+]
+
+
+def _in_flatpak():
+    return os.path.isfile("/.flatpak-info")
+
+
+def _in_appimage():
+    return "APPIMAGE" in os.environ
+
+
+def apply_host_libs(env):
+    """Strip bundle-local entries from *env* so a host binary can run cleanly.
+
+    Only meaningful for AppImage: removes $APPDIR-prefixed entries from
+    LD_LIBRARY_PATH / PYTHONPATH / PATH and drops PYTHONHOME, so the host
+    interpreter doesn't try to load the bundled (incompatible) Python
+    lib/site-packages. Flatpak is handled via flatpak-spawn --host instead
+    (see flatpak_host_spawn), so the sandbox env is irrelevant there.
+    """
+    if not _in_appimage():
+        return
+    appdir = os.environ.get("APPDIR", "")
+    if appdir:
+        for var, sep in (("LD_LIBRARY_PATH", ":"),
+                         ("PYTHONPATH", os.pathsep),
+                         ("PATH", os.pathsep)):
+            cur = env.get(var, "")
+            if not cur:
+                continue
+            cleaned = sep.join(
+                p for p in cur.split(sep)
+                if p and not p.startswith(appdir)
+            )
+            if cleaned:
+                env[var] = cleaned
+            else:
+                env.pop(var, None)
+    env.pop("PYTHONHOME", None)
+
+
+# ---------- Flatpak: spawn on host outside the sandbox -----------------------
+#
+# Inside a Flatpak the sandbox glibc is incompatible with host shared libraries,
+# so we can't run host Python/Lua under the sandbox runtime — `LD_LIBRARY_PATH`
+# tricks hit a `_dl_call_libc_early_init` assertion. The supported way out is
+# `flatpak-spawn --host`, which talks to the session-bus Flatpak D-Bus service
+# (org.freedesktop.Flatpak.Development) and asks it to spawn a process in the
+# host execution environment instead of inside our sandbox. The manifest must
+# grant `--talk-name=org.freedesktop.Flatpak` for the D-Bus call to be allowed.
+#
+# The host process can't see our /app/ contents (sandbox-only), so when we
+# spawn host Python/Lua to run `py_func` / `lua_func`, the cwd must be a
+# directory both sides can reach. /tmp is shared (--filesystem=/tmp), so we
+# stage the testium package there once per process and reuse it for every
+# spawn. In source mode (testium under $HOME) the host already sees the
+# original path, so we skip the copy.
+
+_staged_testium_path = None
+
+
+def _get_host_testium_path():
+    """Return a path to the testium package that the host can read.
+
+    - Source / wheel / PyInstaller install under $HOME → return testium_path()
+      as-is (host sees the same path via --filesystem=home).
+    - Flatpak bundle (testium under /app/) → stage a copy under /tmp on first
+      call and reuse it for the rest of the process.
+    """
+    global _staged_testium_path
+    if _staged_testium_path is not None:
+        return _staged_testium_path
+
+    # Imported lazily to avoid a circular import (paths.py -> api.testium).
+    from interpreter.utils.paths import testium_path
+    tp = testium_path()
+
+    if not tp.startswith("/app/"):
+        _staged_testium_path = tp
+        return tp
+
+    staged = tempfile.mkdtemp(prefix="testium_host_", dir="/tmp")
+    # copytree refuses to write into an existing dir unless dirs_exist_ok=True.
+    # mkdtemp creates the dir, so we copy *into* it.
+    for entry in os.listdir(tp):
+        src = os.path.join(tp, entry)
+        dst = os.path.join(staged, entry)
+        if os.path.isdir(src):
+            shutil.copytree(src, dst, symlinks=True)
+        else:
+            shutil.copy2(src, dst, follow_symlinks=False)
+    _staged_testium_path = staged
+    atexit.register(shutil.rmtree, staged, ignore_errors=True)
+    return staged
+
+
+_FORWARDED_ENV_KEYS = (
+    "HOME", "USER", "LOGNAME", "TMPDIR",
+    "XDG_RUNTIME_DIR", "XDG_DATA_HOME", "XDG_CONFIG_HOME", "XDG_CACHE_HOME",
+    "DBUS_SESSION_BUS_ADDRESS", "DISPLAY", "WAYLAND_DISPLAY",
+    "LANG", "LC_ALL",
+)
+
+
+def flatpak_host_spawn(interp_bin, cmd_args, host_cwd, extra_env=None):
+    """Build a flatpak-spawn --host command vector.
+
+    Args:
+        interp_bin: absolute path to the host interpreter (e.g. /usr/bin/python3).
+        cmd_args: list of arguments passed to the interpreter.
+        host_cwd: working directory on the host (must be reachable from host).
+        extra_env: optional {name: value} of env vars to set on the host side
+                   in addition to the default forwarded set. Values of ""
+                   unset the variable on the host.
+
+    Returns a list suitable for subprocess.Popen.
+    """
+    spawn = ["flatpak-spawn", "--host", f"--directory={host_cwd}"]
+    forwarded = {}
+    for key in _FORWARDED_ENV_KEYS:
+        val = os.environ.get(key)
+        if val:
+            forwarded[key] = val
+    if extra_env:
+        forwarded.update(extra_env)
+    for k, v in forwarded.items():
+        if v == "":
+            spawn.append(f"--unset-env={k}")
+        else:
+            spawn.append(f"--env={k}={v}")
+    spawn.append(interp_bin)
+    spawn.extend(cmd_args)
+    return spawn
+
+
+def host_console_command(shell_cmd, cwd):
+    """Build the argv to start *shell_cmd* as an ordinary interactive console.
+
+    *shell_cmd* is the command the caller chose (a string — shell-split — or
+    an argv list); the choice is preserved verbatim.
+
+    Outside Flatpak the command is returned unchanged. Inside Flatpak a bare
+    spawn would run in the sandbox under the runtime python3, so a host venv
+    (``/path/venv/bin/python3 -m mod``) can't see its pip deps. We simply run
+    it on the host with ``flatpak-spawn --host`` so it behaves like any other
+    terminal: flatpak-spawn passes the current environment through unchanged
+    and the shell (sourced venv, profile, …) sets things up as the user wants.
+    No env forwarding or scrubbing — the launcher's leaked PYTHONPATH points at
+    /app paths absent on the host, so it's inert there.
+    """
+    argv = shlex.split(shell_cmd) if isinstance(shell_cmd, str) else list(shell_cmd)
+    if not _in_flatpak():
+        return argv
+    return ["flatpak-spawn", "--host", f"--directory={cwd}", *argv]
+
+
+def _which_host_flatpak(name):
+    """Resolve a binary name (or absolute path) on the host via flatpak-spawn.
+
+    We can't probe /run/host/... because (a) only host-os is mounted there,
+    not arbitrary paths like /scratch, and (b) returning a /run/host path
+    would be useless — the host-side spawn sees a different filesystem and
+    needs the host-native path anyway.
+    """
+    if os.path.isabs(name):
+        cmd = flatpak_host_spawn("/bin/sh", ["-c", f'test -x "{name}"'],
+                                 host_cwd="/tmp")
+        try:
+            r = subprocess.run(cmd, capture_output=True, timeout=10)
+        except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
+            return ""
+        return name if r.returncode == 0 else ""
+    cmd = flatpak_host_spawn("/bin/sh", ["-c", f'command -v "{name}"'],
+                             host_cwd="/tmp")
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+    except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
+        return ""
+    if r.returncode != 0:
+        return ""
+    return r.stdout.strip()
+
 
 def _which(name):
-    func = sys_app_path_win if tm.OS() == "Windows" else sys_app_path_lin
-    return func(name)
+    if tm.OS() == "Windows":
+        return sys_app_path_win(name)
+    if _in_flatpak():
+        return _which_host_flatpak(name)
+    if _in_appimage():
+        for d in _APPIMAGE_HOST_DIRS:
+            p = os.path.join(d, name)
+            if os.path.isfile(p) and os.access(p, os.X_OK):
+                return p
+        return ""
+    return sys_app_path_lin(name)
 
 
-def _python_version(path):
-    cmd = [path, "-c", "import sys; print(sys.version_info[:3])"]
+def _probe_env():
+    """Subprocess env for probing host binaries.
+
+    In AppImage we still need to scrub APPDIR-prefixed entries; in Flatpak we
+    delegate execution to the host via flatpak-spawn so the sandbox env doesn't
+    matter, but apply_host_libs is a no-op cost.
+    """
+    env = os.environ.copy()
+    apply_host_libs(env)
+    return env
+
+
+def _run_probe(cmd):
+    """Run a probe command, dispatching through flatpak-spawn --host in Flatpak.
+
+    Returns (stdout, stderr) as str, or None on failure.
+    """
+    if _in_flatpak():
+        spawn = flatpak_host_spawn(cmd[0], cmd[1:], host_cwd="/tmp")
+        try:
+            r = subprocess.run(
+                spawn, capture_output=True, text=True, timeout=10,
+            )
+        except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
+            return None
+        if r.returncode != 0:
+            return None
+        return r.stdout, r.stderr
     try:
         r = subprocess.run(
             cmd, capture_output=True, text=True,
-            encoding=tm.sys_encoding(), timeout=10,
+            encoding=tm.sys_encoding(), timeout=10, env=_probe_env(),
         )
     except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
         return None
+    return r.stdout, r.stderr
+
+
+def _python_version(path):
+    out = _run_probe([path, "-c", "import sys; print(sys.version_info[:3])"])
+    if out is None:
+        return None
     try:
-        return eval(r.stdout)
+        return eval(out[0])
     except Exception:
         return None
 
@@ -57,14 +294,11 @@ def _is_python3(path):
 
 
 def _lua_version(path):
-    try:
-        r = subprocess.run(
-            [path, "-v"], capture_output=True, text=True, timeout=10,
-        )
-    except (FileNotFoundError, PermissionError, subprocess.TimeoutExpired):
+    out = _run_probe([path, "-v"])
+    if out is None:
         return None
     # On Windows the version banner goes to stderr.
-    line = r.stdout or r.stderr
+    line = out[0] or out[1]
     try:
         major, minor, _patch = line.split(" ")[1].split(".")
         return (int(major), int(minor))
@@ -85,20 +319,39 @@ _SPECS = {
     "lua":    ("Lua 5.1+",  "lua_bin",    _LUA_CANDIDATES,    _is_lua51),
 }
 
+# Cached per (name, override) so that runtime changes to gd[gd_key] —
+# e.g. ``python_bin`` set from a YAML config file loaded *after*
+# eval_proc has already resolved its own interpreter — are picked up by
+# the next lookup instead of returning the stale, auto-discovered path.
+# Long-lived subprocesses (eval_proc) keep whatever they captured at
+# construction time, but every new PyProcessBase / FuncExecEngine spawned
+# afterwards sees the current override.
 _resolved = {}
 
 
 def _resolve(name):
-    if name in _resolved:
-        return _resolved[name]
-
     display, gd_key, candidates, validator = _SPECS[name]
     override = tm.gd(gd_key, "") or ""
 
+    cached = _resolved.get(name)
+    if cached is not None and cached[0] == override:
+        return cached[1]
+
     path = ""
     if override:
-        if shutil.which(override) and validator(override):
-            path = override
+        # Absolute path: accept as-is (user knows exactly what they want).
+        # Bare name: resolve via _which() so the override stays host-only in
+        # Flatpak/AppImage instead of silently picking the bundled interpreter.
+        # In Flatpak we always defer to _which() so even absolute paths are
+        # checked from the host's perspective (the sandbox can't see e.g.
+        # /scratch/... paths that the user may have configured).
+        if os.path.isabs(override) and not _in_flatpak():
+            resolved = override if (os.path.isfile(override)
+                                    and os.access(override, os.X_OK)) else ""
+        else:
+            resolved = _which(override)
+        if resolved and validator(resolved):
+            path = resolved
         else:
             tm.print_warn(
                 f"Configured {display} interpreter '{override}' is not usable; "
@@ -114,7 +367,7 @@ def _resolve(name):
                 path = p
                 break
 
-    _resolved[name] = path
+    _resolved[name] = (override, path)
     return path
 
 

src/testium/interpreter/utils/include.py

@@ -6,10 +6,10 @@ from runtime.tum_except import ETUMFileError
 from interpreter.utils.template import template_to_test
 from copy import copy
 from interpreter.utils.globdict import global_dict
-from interpreter.utils.yaml_load import yaml_load
+from interpreter.utils.yaml_load import yaml_load, YAML_BASE_LOADER
 
 
-class TUMLoaderNoIncludes(yaml.Loader):
+class TUMLoaderNoIncludes(YAML_BASE_LOADER):
 
     def __init__(self, stream):
 

src/testium/interpreter/utils/lua_process.py

@@ -47,9 +47,16 @@ class LuaProcessBase:
         if self._process is not None:
             raise ETUMRuntimeError("The function subprocess has already been started.")
 
-        func_proc_path = os.path.realpath(
-            os.path.join(subproc_path(), "lua_func")
-        )
+        # In Flatpak the host can't see /app/lib/testium/lua_func, so use a
+        # staged copy under /tmp (shared between sandbox and host).
+        if bins._in_flatpak():
+            func_proc_path = os.path.join(
+                bins._get_host_testium_path(), "lua_func"
+            )
+        else:
+            func_proc_path = os.path.realpath(
+                os.path.join(subproc_path(), "lua_func")
+            )
 
         # POpen config
         CUST_ENV = {
@@ -60,6 +67,7 @@ class LuaProcessBase:
 
         lua_env = tm.gd("lua_env", {})
         env = os.environ.copy()
+        bins.apply_host_libs(env)
         if not isinstance(lua_env, dict):
             raise ETUMRuntimeError(f"The 'lua_env' global value should be a dictionary. But it is '{lua_env}'.")
 
@@ -77,8 +85,7 @@ class LuaProcessBase:
         sock.close()
 
         # POpen params
-        params = [
-            self._lbin,
+        cmd_args = [
             "main.lua",
             "--timeout",
             f"{self._timeout}",
@@ -89,14 +96,31 @@ class LuaProcessBase:
         ]
 
         if tm.debug_enabled() and tm.gd("debug_rpc", False):
-            params.append("--verbose")
+            cmd_args.append("--verbose")
+
+        if bins._in_flatpak():
+            # Run on the host outside the sandbox: avoids glibc ABI mismatches
+            # between the Flatpak runtime and host shared libraries.
+            host_env = {
+                k: env[k] for k in ("LUA_PATH", "LUA_CPATH", "PATH")
+                if k in env and env[k]
+            }
+            params = bins.flatpak_host_spawn(
+                self._lbin, cmd_args, host_cwd=func_proc_path,
+                extra_env=host_env,
+            )
+            popen_kwargs = {}
+        else:
+            params = [self._lbin, *cmd_args]
+            popen_kwargs = {"env": env, "cwd": func_proc_path}
 
         self._process = subprocess.Popen(
-            params, env=env, cwd=func_proc_path,
+            params,
             stdin=subprocess.DEVNULL,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             restore_signals=False,
+            **popen_kwargs,
         )
         # Route subprocess stdout/stderr (lua require failures, syntax
         # errors, anything written to fd 1/2 before the in-script
@@ -144,4 +168,12 @@ class LuaProcessBase:
         """
         if self._rpc is not None:
             self._rpc.stop()
+        # Force-kill the worker if it's still running. Needed when user code
+        # in the worker is stuck and won't notice the parent closing the RPC
+        # socket on its own.
+        if self._process is not None and self._process.poll() is None:
+            try:
+                self._process.terminate()
+            except Exception:
+                pass
 

src/testium/interpreter/utils/param_decl.py

@@ -0,0 +1,175 @@
+"""Declarative description of a test item's accepted parameters.
+
+Each ``TestItem`` subclass declares its parameter surface as a class
+attribute::
+
+    class TestItemFoo(TestItem):
+        PARAMS = ParamSet(
+            Param("bar",      required=True,  doc="The bar value."),
+            Param("baz",      default=0,      doc="Optional baz."),
+            Param("modes",    kind=LIST,      doc="Iterable of modes."),
+            Param("strategy", kind=ENUM("a", "b"), doc="..."),
+            Param("opts",     kind=BLOCK,     doc="Sub-block."),
+        )
+
+The base ``TestItem.__init__`` consumes both ``COMMON_PARAMS`` (defined
+in ``test_item.py``) and the subclass ``PARAMS`` to:
+
+* warn on any key in the user's YAML that isn't declared anywhere
+  (catches typos like ``param_filee``);
+* expose a machine-readable schema for documentation generation and,
+  eventually, an LSP server.
+
+The descriptor is **purely about shape and naming**. Type coercion and
+runtime checking of expanded values remain the responsibility of each
+item's ``execute()`` method — most parameters are expressions
+(``$(...)`` / ``<| ... |>``) whose effective type is only known after
+expansion, so a static type would be misleading.
+
+Validation of *values* (e.g. ``start_time`` must match HH:MM) can be
+attached per-param via ``validate=lambda v: ...`` and is applied at
+execution time on the expanded value, not at load time.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Union
+
+
+# ---------- Parameter "kinds" -------------------------------------------------
+#
+# These describe the YAML *shape* expected for a parameter, not its
+# semantic type. They drive the LSP completion (do we suggest a single
+# value, a list, a sub-block, an enum picker?) and the unknown-param
+# diagnostic; nothing more.
+
+SCALAR = "scalar"  # single value (string, number, bool, expression, ...)
+LIST = "list"      # YAML list — the historical ``getParamAll`` case
+BLOCK = "block"    # nested dict — e.g. ``cycle.exit:``
+
+
+@dataclass(frozen=True)
+class Enum:
+    """Closed enumeration of acceptable scalar values."""
+    values: tuple
+
+    def __init__(self, *values):
+        # frozen=True forbids assignment; bypass via object.__setattr__.
+        object.__setattr__(self, "values", tuple(values))
+
+    def __repr__(self):
+        return f"Enum({', '.join(repr(v) for v in self.values)})"
+
+
+Kind = Union[str, Enum]
+
+
+# ---------- The descriptor ----------------------------------------------------
+
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class Param:
+    """Declarative description of one accepted parameter.
+
+    Attributes
+    ----------
+    name : str
+        The YAML key.
+    kind : ``SCALAR`` (default) | ``LIST`` | ``BLOCK`` | ``Enum(...)``
+        The YAML shape expected.
+    required : bool
+        If True, missing the parameter is a load-time error.
+    default : Any
+        Default value when the parameter is absent. ``_MISSING`` when no
+        default was set (used to distinguish "absent" from "None").
+    doc : str
+        Free-form description used for hover / generated documentation.
+    validate : Optional[Callable[[Any], bool]]
+        Optional post-expansion validator, evaluated at ``execute()``
+        time on the effective (expanded) value. Returning ``False``
+        raises a clear error pointing at the param.
+    """
+    name: str
+    kind: Kind = SCALAR
+    required: bool = False
+    default: Any = _MISSING
+    doc: str = ""
+    validate: Optional[Callable[[Any], bool]] = None
+
+    def has_default(self):
+        return self.default is not _MISSING
+
+    def to_schema(self):
+        """Return a dict suitable for JSON Schema generation."""
+        s = {"name": self.name, "required": self.required, "doc": self.doc}
+        if isinstance(self.kind, Enum):
+            s["kind"] = "enum"
+            s["enum"] = list(self.kind.values)
+        else:
+            s["kind"] = self.kind
+        if self.has_default():
+            s["default"] = self.default
+        return s
+
+
+class ParamSet:
+    """Ordered, name-indexed collection of ``Param`` descriptors.
+
+    Supports concatenation (``COMMON_PARAMS + SUBCLASS_PARAMS``) to
+    merge the common surface with each item's own params. Later
+    declarations override earlier ones (so a subclass can tighten a
+    common param's docstring without redeclaring everything).
+    """
+
+    def __init__(self, *params):
+        self._params = {}
+        for p in params:
+            self.add(p)
+
+    def add(self, param):
+        if not isinstance(param, Param):
+            raise TypeError(f"ParamSet only accepts Param instances, got {type(param).__name__}")
+        self._params[param.name] = param
+
+    def __iter__(self):
+        return iter(self._params.values())
+
+    def __contains__(self, name):
+        return name in self._params
+
+    def __getitem__(self, name):
+        return self._params[name]
+
+    def names(self):
+        return tuple(self._params.keys())
+
+    def __add__(self, other):
+        if not isinstance(other, ParamSet):
+            return NotImplemented
+        merged = ParamSet()
+        merged._params = {**self._params, **other._params}
+        return merged
+
+    def to_schema(self):
+        return [p.to_schema() for p in self._params.values()]
+
+
+# ---------- Validation primitives --------------------------------------------
+
+def unknown_keys(declared, user_dict):
+    """Return the user-provided keys that are not declared in *declared*.
+
+    *declared* is a ``ParamSet``; *user_dict* is the raw YAML mapping
+    for the item. Unknown keys catch typos and obsolete parameters.
+    """
+    if not isinstance(user_dict, dict):
+        return ()
+    return tuple(k for k in user_dict.keys() if k not in declared)
+
+
+def missing_required(declared, user_dict):
+    """Return the names of declared required params absent from *user_dict*."""
+    if not isinstance(user_dict, dict):
+        return tuple(p.name for p in declared if p.required)
+    return tuple(p.name for p in declared if p.required and p.name not in user_dict)

src/testium/interpreter/utils/py_process.py

@@ -42,6 +42,10 @@ class PyProcessBase:
             raise ETUMRuntimeError(f"The 'py_env' global value should be a dictionary. But it is '{py_env}'.")
 
         env = os.environ.copy()
+        bins.apply_host_libs(env)
+        # PYTHONUSERBASE is set by the Flatpak runtime to isolate sandbox
+        # user packages; remove it so the host Python finds ~/.local packages.
+        env.pop("PYTHONUSERBASE", None)
         for k, v in self.CUST_ENV.items():
             e = py_env.get(k, "")
             if e != "":
@@ -57,14 +61,18 @@ class PyProcessBase:
         if sock is not None:
             sock.close()
 
-        # Add the path of the subprocess (root sources of testium)
-        tstium_path = os.path.realpath(testium_path())
-        func_proc_path = os.path.realpath(subproc_path())
+        # In Flatpak the host can't see /app/lib/testium, so use a staged copy
+        # under /tmp (shared between sandbox and host) for both cwd and as the
+        # root in PYTHONPATH. Outside Flatpak the original paths are used.
+        if bins._in_flatpak():
+            tstium_path = bins._get_host_testium_path()
+            func_proc_path = tstium_path
+        else:
+            tstium_path = os.path.realpath(testium_path())
+            func_proc_path = os.path.realpath(subproc_path())
         env["PYTHONPATH"] = tstium_path + os.pathsep + self._ppath + os.pathsep + env.get("PYTHONPATH", "")
 
-        params = [
-            self._pbin,
-            # "-m",
+        cmd_args = [
             "py_func",
             "-p",
             f"{self._port}",
@@ -73,14 +81,31 @@ class PyProcessBase:
         ]
 
         if tm.debug_enabled() and tm.gd("debug_rpc", False):
-            params.append("-v")
+            cmd_args.append("-v")
+
+        if bins._in_flatpak():
+            # Run on the host outside the sandbox: avoids glibc ABI mismatches
+            # between the Flatpak runtime and host shared libraries.
+            host_env = {
+                k: env[k] for k in ("PYTHONPATH", "PATH")
+                if k in env and env[k]
+            }
+            params = bins.flatpak_host_spawn(
+                self._pbin, cmd_args, host_cwd=func_proc_path,
+                extra_env=host_env,
+            )
+            popen_kwargs = {}
+        else:
+            params = [self._pbin, *cmd_args]
+            popen_kwargs = {"env": env, "cwd": func_proc_path}
 
         self._process = subprocess.Popen(
-            params, env=env, cwd=func_proc_path,
+            params,
             stdin=subprocess.DEVNULL,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             restore_signals=False,
+            **popen_kwargs,
         )
         # Route subprocess stdout/stderr (early-startup errors,
         # unhandled exceptions, anything written to fd 1/2 before the
@@ -119,3 +144,11 @@ class PyProcessBase:
     def stop(self):
         if self._rpc is not None:
             self._rpc.stop()
+        # Force-kill the worker if it's still running. Needed when user code
+        # in the worker is stuck (e.g. sleep, blocking I/O) and won't notice
+        # the parent closing the RPC socket on its own.
+        if self._process is not None and self._process.poll() is None:
+            try:
+                self._process.terminate()
+            except Exception:
+                pass

src/testium/interpreter/utils/template.py

@@ -1,33 +1,74 @@
+import io
 import os
 from sys import exc_info
-from jinja2 import Template
+from jinja2 import Environment
 from jinja2.exceptions import TemplateSyntaxError, TemplateError, UndefinedError
-from tempfile import TemporaryFile
 from interpreter.utils.yaml_load import print_yaml
 from runtime.tum_except import ETUMSyntaxError
 
 
+# One Environment reused for every render (default settings, i.e. identical
+# behaviour to jinja2.Template), plus a compiled-template cache so a file that
+# is included many times — or a test that is reloaded — is compiled only once.
+# Jinja compilation is the expensive step; render (variable substitution) stays
+# per-call. Cache is keyed on path + mtime + size so an edited file recompiles.
+_ENV = Environment()
+_template_cache = {}  # abspath -> (mtime_ns, size, compiled_template)
+
+
+class _RenderedStream(io.StringIO):
+    """A rendered template kept in memory.
+
+    Carries ``root`` (and ``name``) so the YAML loader resolves ``!include``
+    paths exactly as it did from the on-disk temp file this replaces — without
+    the write + seek + read round-trip (one temp file per included file). That
+    round-trip is pure overhead, and especially costly on slow storage.
+    """
+
+
+def _compiled_template(filename: str):
+    """Return the compiled jinja template for *filename*, reusing the cached
+    one when the file is unchanged (path + mtime + size)."""
+    key = os.path.abspath(filename)
+    try:
+        st = os.stat(filename)
+    except OSError:
+        st = None
+    if st is not None:
+        cached = _template_cache.get(key)
+        if (cached is not None
+                and cached[0] == st.st_mtime_ns
+                and cached[1] == st.st_size):
+            return cached[2]
+    with open(filename, "r") as f:
+        source = f.read()
+    template = _ENV.from_string(source)  # compile (may raise TemplateSyntaxError)
+    if st is not None:
+        _template_cache[key] = (st.st_mtime_ns, st.st_size, template)
+    return template
+
+
 def template_to_test(filename: str, params: list):
     """ Function which processes an eventual jinja2 template to a test file
     """
-    # Temporary file created to receive the processed include
-    # file
-    tmpf = TemporaryFile('w+t')
-    with open(filename, 'r') as f:
-        try:
-            j2_template = Template(f.read())
-        except TemplateError as e:
+    # Compile (cached) — a syntax error in the template surfaces here.
+    try:
+        j2_template = _compiled_template(filename)
+    except TemplateError as e:
+        with open(filename, "r") as f:
             print_yaml(f, filename)
-            type, value, tb = exc_info()
-            msg = "Template error"
-            if hasattr(value, 'lineno'):
-                msg = msg + f" on line {value.lineno}: "
-            else:
-                msg += ": "
-            raise ETUMSyntaxError(msg + str(e), filename)
+        type, value, tb = exc_info()
+        msg = "Template error"
+        if hasattr(value, 'lineno'):
+            msg = msg + f" on line {value.lineno}: "
+        else:
+            msg += ": "
+        raise ETUMSyntaxError(msg + str(e), filename)
+
+    # Render into memory (no temp file).
     try:
         params["include_directory"] = os.path.dirname(os.path.abspath(filename))
-        tmpf.write(j2_template.render(params))
+        rendered = j2_template.render(params)
     except TemplateSyntaxError as e:
         raise ETUMSyntaxError(f"""Template loading of file '{filename}' with following parameters '{str(params)}'
 Syntax error in template: {e.message}""")
@@ -42,8 +83,7 @@ Template rendering error: {e.message}""")
         raise ETUMSyntaxError(f"""Template loading of file '{filename}' with following parameters '{str(params)}'
 Unexpected error: {str(e)}""")
 
-    # return to begining of the temp file
-    tmpf.seek(0, os.SEEK_SET)
-    tmpf.root = os.path.dirname(filename)
-
-    return tmpf
+    stream = _RenderedStream(rendered)
+    stream.root = os.path.dirname(filename)
+    stream.name = filename
+    return stream

src/testium/interpreter/utils/test_init.py

@@ -11,7 +11,7 @@ import api.testium as tm
 import interpreter.utils.globdict as globdict
 import interpreter.utils.settings as prefs
 from interpreter.utils.paths import testium_path
-from interpreter.utils.yaml_load import yaml_load
+from interpreter.utils.yaml_load import yaml_load, YAML_BASE_LOADER
 from interpreter.utils import clear_recursively
 from runtime.tum_except import ETUMSyntaxError
 from interpreter.utils.params import expanse, eval_func_init
@@ -89,7 +89,7 @@ def locate_report_file(rep_file):
 def yamltodict(param_file, silent=True):
     # load of the file
     with open(param_file, "r") as fd:
-        dp = yaml_load(fd, param_file, yaml.Loader)
+        dp = yaml_load(fd, param_file, YAML_BASE_LOADER)
 
     if dp is None:
         tm.print_info(f"The YAML file '{param_file}' is empty.")
@@ -165,11 +165,14 @@ def env_init():
     _constants_init()
 
 
-def update_global(config_files, defines, gui_defaults, silent=False):
-    """Global dict updated with the content of the config file and a dict provided.
-    this function returns the resulting dict.
+def apply_overrides(defines, gui_defaults):
+    """Push GUI defaults then CLI defines into the global dict.
+
+    Extracted from update_global so it can be called *before* eval_proc
+    starts: interpreter overrides (python_bin, lua_bin) must be visible
+    to bins.python_bin() on its first lookup, which happens during
+    eval_process_init.
     """
-    # GUI preferences applied first
     for k, v in gui_defaults.items():
         try:
             val = ast.literal_eval(v)
@@ -177,7 +180,6 @@ def update_global(config_files, defines, gui_defaults, silent=False):
             val = v
         tm.setgd(k, val)
 
-    # Then command line defines
     for k, v in defines.items():
         try:
             val = ast.literal_eval(v)
@@ -185,6 +187,14 @@ def update_global(config_files, defines, gui_defaults, silent=False):
             val = v
         tm.setgd(k, val)
 
+
+def update_global(config_files, defines, gui_defaults, silent=False):
+    """Global dict updated with the content of the config file and a dict provided.
+    this function returns the resulting dict.
+    """
+    # GUI preferences applied first, then command line defines
+    apply_overrides(defines, gui_defaults)
+
     # Then the configuration files
     # load global dic before test item
     _feed_gd_with_params(config_files, silent)

src/testium/interpreter/utils/version.py

@@ -1,10 +1,54 @@
+import atexit
 import os
+import stat
 import sys
+import tempfile
 from importlib import import_module
 
 import interpreter.utils.settings as prefs
 import api.testium as tm
 
+
+# When running inside a Flatpak, the host /usr/bin/git is reachable at
+# /run/host/usr/bin/git but linked against host glibc/zlib, which the
+# sandbox can't load (``libz-ng.so.2`` not found). gitpython resolves git
+# eagerly on import and would crash the whole test run. We install a
+# tiny shell wrapper under /tmp that forwards to ``flatpak-spawn --host
+# git``, and point gitpython at it via ``GIT_PYTHON_GIT_EXECUTABLE``.
+_HOST_GIT_WRAPPER = None
+
+
+def _setup_flatpak_git():
+    global _HOST_GIT_WRAPPER
+    if not os.path.isfile("/.flatpak-info"):
+        return
+    if _HOST_GIT_WRAPPER is not None:
+        return
+    fd, path = tempfile.mkstemp(prefix="testium-git-host-", suffix=".sh", dir="/tmp")
+    with os.fdopen(fd, "w") as f:
+        f.write('#!/bin/sh\nexec flatpak-spawn --host git "$@"\n')
+    os.chmod(path, stat.S_IRWXU)
+    _HOST_GIT_WRAPPER = path
+    atexit.register(_cleanup_flatpak_git)
+    os.environ["GIT_PYTHON_GIT_EXECUTABLE"] = path
+    # Silence gitpython's warning if its refresh probe ever still fails;
+    # the wrapper itself should make the probe succeed.
+    os.environ.setdefault("GIT_PYTHON_REFRESH", "quiet")
+
+
+def _cleanup_flatpak_git():
+    global _HOST_GIT_WRAPPER
+    if _HOST_GIT_WRAPPER and os.path.isfile(_HOST_GIT_WRAPPER):
+        try:
+            os.unlink(_HOST_GIT_WRAPPER)
+        except OSError:
+            pass
+        _HOST_GIT_WRAPPER = None
+
+
+_setup_flatpak_git()
+
+
 _cached_versions = {}
 
 def repo_rev(path):
@@ -31,10 +75,15 @@ def get_version(path :str)-> str:
         return "Warning git not supported in your settings, version of {} unknown".format(path)
 
 def get_testium_version():
+    # Flatpak bundle
+    if os.path.isfile('/.flatpak-info'):
+        ver = os.environ.get('TESTIUM_VERSION', '').strip()
+        return (ver if ver else 'unknown') + " (flatpak release)"
+
     # AppImage
     if 'APPIMAGE' in os.environ:
-        ver = os.getenv('SEQUENCER_REV', 'unknown')
-        return ver + " (binary release)"
+        ver = os.environ.get('TESTIUM_VERSION', '').strip()
+        return (ver if ver else 'unknown') + " (binary release)"
 
     # PyInstaller frozen exe
     if getattr(sys, 'frozen', False):

src/testium/interpreter/utils/yaml_load.py

@@ -1,3 +1,4 @@
+import yaml
 from yaml.parser import ParserError
 from yaml import load, Loader
 from yaml.scanner import ScannerError
@@ -5,6 +6,12 @@ from api.testium import print_debug
 from runtime.tum_except import ETUMSyntaxError
 import io
 
+# Use the libyaml-backed loader (much faster parsing) when PyYAML was built
+# with it, falling back to the pure-Python loader otherwise. The C loader
+# raises the same ParserError/ScannerError and supports the same custom
+# constructors (!include) and construct_* helpers the TUM loaders rely on.
+YAML_BASE_LOADER = yaml.CLoader if getattr(yaml, "__with_libyaml__", False) else yaml.Loader
+
 
 def print_yaml(file: io.TextIOWrapper, file_name):
     """ Prints YAML file if debug mode is activated.
@@ -21,10 +28,10 @@ def yaml_load(file, real_file_name: str, loader: Loader):
         return load(file, loader)
 
     except ParserError as e:
-        if isinstance(file, io.TextIOWrapper):
+        if isinstance(file, (io.TextIOWrapper, io.StringIO)):
             print_yaml(file, real_file_name)
         raise ETUMSyntaxError(f"yaml file parsing error: " + str(e), real_file_name)
     except ScannerError as e:
-        if isinstance(file, io.TextIOWrapper):
+        if isinstance(file, (io.TextIOWrapper, io.StringIO)):
             print_yaml(file, real_file_name)
         raise ETUMSyntaxError("yaml file scanning error: " + str(e), real_file_name)

src/testium/lsp/__init__.py

@@ -0,0 +1,16 @@
+"""testium language tooling.
+
+Hosts the JSON-Schema-style schema export of every test item type, and a
+``pygls`` language server that consumes the same schema to provide
+completion / hover / diagnostics for ``.tum`` files in any LSP-capable
+editor (VSCode, neovim, Helix, Emacs, …).
+
+Entry points (both surfaced through the ``testium`` CLI):
+
+- ``testium schema`` — dump the schema of every item type as JSON on stdout.
+  Zero runtime dependencies; can be used by editors that already speak the
+  YAML JSON Schema extension to get static completion immediately.
+
+- ``testium lsp`` — start the language server over stdio. Requires the
+  ``pygls`` optional dependency (``pip install testium[lsp]``).
+"""

src/testium/lsp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m testium.lsp`` (alternative to ``testium lsp``)."""
+
+from lsp.server import serve
+
+if __name__ == "__main__":
+    serve()

src/testium/lsp/schema.py

@@ -0,0 +1,122 @@
+"""Schema export of the test item registry.
+
+Walks every ``TestItemType`` entry (``interpreter/utils/constants.py``),
+combines its declared ``PARAMS`` with the common ones, and returns a
+serialisable structure keyed by ``item_cmd`` — the YAML key the user
+writes (e.g. ``sleep``, ``py_func``, ``dialog_message``).
+
+Items intentionally without ``PARAMS`` (the unstructured-body classes
+like console ``write``/``writeln`` or plot ``add``/``export``) are
+emitted as ``"params_declared": false`` so consumers know to suggest
+nothing for them rather than reporting a closed empty set.
+
+Action items (children of ``parallel``, ``console``, ``json_rpc``,
+``plot``) are registered separately under each parent's ``actions``
+entry — they're not top-level YAML keys, they live nested inside a
+parent's ``steps:``.
+"""
+
+import json
+
+from interpreter.utils.constants import TestItemType
+from interpreter.utils.test_init import _constants_init
+
+
+# Action class -> parent cmd (the action's parent in the YAML). Action classes
+# aren't first-class TestItemType entries (TYPE_*_ACTION is one generic bucket),
+# so we resolve their YAML key from the parent's declarative ``ACTIONS`` map.
+def _collect_action_classes(parent_class):
+    """Return {action_yaml_key: action_class} for a TestItemActions parent.
+
+    Each parent declares its actions as a class-level ``ACTIONS = {key: class}``
+    attribute (see ``item_actions/TestItemActions``). We read it directly — no
+    instantiation, no source inspection — so this works identically whether the
+    package runs from source, a wheel, or a frozen (PyInstaller) build where the
+    ``.py`` source isn't on disk.
+    """
+    return dict(getattr(parent_class, "ACTIONS", None) or {})
+
+
+def _params_to_schema(item_class, common_params):
+    """Return the params-portion of an item's schema entry.
+
+    Common params are flagged so consumers can render them differently
+    (an editor might show "common" parameters in a separate group).
+    """
+    own = getattr(item_class, "PARAMS", None)
+    if own is None:
+        return {"params_declared": False}
+    common_names = set(common_params.names())
+    params = []
+    for p in common_params:
+        d = p.to_schema()
+        d["common"] = True
+        params.append(d)
+    for p in own:
+        if p.name in common_names:
+            # Subclass overrode a common param (e.g. tightened doc).
+            for d in params:
+                if d["name"] == p.name:
+                    d.update(p.to_schema())
+                    break
+            continue
+        d = p.to_schema()
+        d["common"] = False
+        params.append(d)
+    return {"params_declared": True, "params": params}
+
+
+def dump_all_schemas():
+    """Return the full schema as a Python dict ready for json.dumps.
+
+    Shape:
+        {
+          "items": {
+            "sleep": {
+              "display_name": "Sleep",
+              "params_declared": true,
+              "params": [{name, kind, required, default?, doc, common}, ...],
+            },
+            "console": {
+              ...,
+              "actions": {"open": {...}, "close": {...}, ...},
+            },
+            ...
+          }
+        }
+    """
+    _constants_init()
+    # Imported lazily — pulls test_item.py which references constants.
+    from interpreter.test_items.test_item import COMMON_PARAMS
+
+    out = {"items": {}}
+    for tp in TestItemType:
+        cls = getattr(tp, "item_class", None)
+        if cls is None:
+            continue
+        # Action types (CONSOLE_ACTION, GRAPH_ACTION, JSON_RPC_ACTION) have no
+        # standalone YAML representation — skip them here, they show up under
+        # their parent's "actions" key.
+        cmd = tp.item_cmd
+        if cmd.endswith("_action"):
+            continue
+        entry = {"display_name": tp.item_name}
+        entry.update(_params_to_schema(cls, COMMON_PARAMS))
+
+        actions = _collect_action_classes(cls)
+        if actions:
+            entry["actions"] = {
+                name: _params_to_schema(acls, COMMON_PARAMS)
+                for name, acls in actions.items()
+            }
+            for name in entry["actions"]:
+                entry["actions"][name]["display_name"] = name
+
+        out["items"][cmd] = entry
+    return out
+
+
+def dump_all_schemas_json(indent=2):
+    """Same as ``dump_all_schemas`` but serialised to a JSON string."""
+    return json.dumps(dump_all_schemas(), indent=indent, sort_keys=False,
+                      default=str)

src/testium/lsp/server.py

@@ -0,0 +1,313 @@
+"""LSP server for ``.tum`` files.
+
+Features available so far:
+
+- **Completion** — when the user starts a new YAML step (``- <cursor>``),
+  the server proposes the full list of known item types. The completion
+  item carries a short hover-style description listing required and
+  optional parameters.
+- **Hover** — over a known item-type word (``sleep``, ``py_func``, …)
+  the server renders the same description in a popup.
+- **Document symbols (outline)** — every ``- <type>:`` line becomes an
+  entry in the editor's outline view. Nesting follows YAML indentation,
+  so containers (``group``, ``loop``, ``parallel``, ``console`` …)
+  display their children as a subtree.
+
+The server speaks LSP over stdio. Start it with::
+
+    testium lsp
+
+Editors invoke it through their LSP client; the connection layer
+(``vscode-languageclient``, ``nvim-lspconfig``, ``lsp-mode``, …) takes
+care of the JSON-RPC framing.
+
+Architecture notes
+------------------
+
+The schema is built once at server start (``dump_all_schemas()``) and
+kept in memory; an editor restart picks up upstream changes. The schema
+is the **only** source of truth — when testium adds a new item type or
+parameter, the LSP automatically exposes it without any change here.
+
+The current handlers stay deliberately heuristic on the parser side:
+completion uses a line-prefix regex, outline a per-line ``- <known>:``
+sweep with indentation tracking. A proper YAML+Jinja parsing pass is
+still pending and is the prerequisite for *parameter*-level completion
+and diagnostics.
+"""
+
+import re
+
+try:
+    # pygls 2.x moved LanguageServer under pygls.lsp.server. We pin >=1.3 in
+    # the optional dependency to stay open to either family, but the import
+    # path differs — try the new one first, then the legacy one.
+    try:
+        from pygls.lsp.server import LanguageServer
+    except ImportError:
+        from pygls.server import LanguageServer  # pygls < 2
+    from lsprotocol.types import (
+        TEXT_DOCUMENT_COMPLETION,
+        TEXT_DOCUMENT_DOCUMENT_SYMBOL,
+        TEXT_DOCUMENT_HOVER,
+        CompletionItem,
+        CompletionItemKind,
+        CompletionList,
+        CompletionOptions,
+        CompletionParams,
+        DocumentSymbol,
+        DocumentSymbolParams,
+        Hover,
+        HoverParams,
+        InsertTextFormat,
+        MarkupContent,
+        MarkupKind,
+        Position,
+        Range,
+        SymbolKind,
+    )
+except ImportError as exc:
+    # Surfaced by the CLI dispatcher with a friendly install hint.
+    raise
+
+
+from lsp.schema import dump_all_schemas
+
+
+_LINE_START_STEP = re.compile(r"^\s*-\s*([A-Za-z_][A-Za-z0-9_]*)?\s*:?\s*$")
+
+# Matches "- <identifier>:" for outline / hover purposes. Captures the start
+# column of the identifier and the identifier itself. Trailing tokens after
+# the colon (inline-form params, comments) are tolerated.
+_STEP_LINE = re.compile(r"^(?P<lead>\s*-\s*)(?P<ident>[A-Za-z_][A-Za-z0-9_]*)\s*:")
+
+# Matches a ``name: <value>`` line under an item — used by the outline pass
+# to surface the user's display name next to the item type.
+_NAME_FIELD = re.compile(r"^\s*name\s*:\s*(?P<value>.+?)\s*$")
+
+# Word boundary used by hover to extract the identifier under the cursor.
+_IDENT_AT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+def _render_item_markdown(cmd, entry):
+    """Render an item-type's schema entry as a Markdown hover string.
+
+    Reused by both the completion-item documentation and the hover
+    handler so the editor presents identical information regardless of
+    how the user reached it.
+    """
+    detail = entry.get("display_name", cmd)
+    lines = [f"**{cmd}** — {detail}", ""]
+    if entry.get("params_declared"):
+        non_common = [p for p in entry["params"] if not p["common"]]
+        required = [p for p in non_common if p["required"]]
+        optional = [p for p in non_common if not p["required"]]
+        if required:
+            lines.append("Required parameters:")
+            for p in required:
+                lines.append(f"- `{p['name']}` — {p['doc']}")
+            lines.append("")
+        if optional:
+            lines.append("Optional parameters:")
+            for p in optional:
+                lines.append(f"- `{p['name']}` — {p['doc']}")
+    else:
+        lines.append("(Parameter list is not described — this item's body is the "
+                     "raw user value.)")
+    return "\n".join(lines)
+
+
+def _build_item_completions(schema):
+    """Return a list of CompletionItem covering every top-level item type.
+
+    Each completion inserts ``<name>:`` with the cursor positioned after
+    the colon so the user can immediately start typing parameters.
+    """
+    items = []
+    for cmd, entry in schema["items"].items():
+        if cmd == "default":
+            # Root sentinel; never appears as a YAML key.
+            continue
+        items.append(
+            CompletionItem(
+                label=cmd,
+                kind=CompletionItemKind.Class,
+                detail=entry.get("display_name", cmd),
+                documentation=MarkupContent(
+                    kind=MarkupKind.Markdown,
+                    value=_render_item_markdown(cmd, entry),
+                ),
+                insert_text=f"{cmd}:",
+                insert_text_format=InsertTextFormat.PlainText,
+            )
+        )
+    items.sort(key=lambda it: it.label)
+    return items
+
+
+def _word_at(line, character):
+    """Return ``(start, end, text)`` of the identifier under ``character``.
+
+    Returns ``None`` when the cursor isn't on a word. Used by hover.
+    """
+    for m in _IDENT_AT.finditer(line):
+        if m.start() <= character <= m.end():
+            return m.start(), m.end(), m.group(0)
+    return None
+
+
+def _build_document_symbols(lines, item_cmds):
+    """Walk ``lines`` and produce a nested ``DocumentSymbol`` tree.
+
+    Heuristics (no YAML parsing yet):
+    - Each ``- <known_cmd>:`` line becomes a symbol.
+    - Nesting follows the indentation of the leading ``-``: a deeper-
+      indented step is treated as a child of the most recent shallower
+      step.
+    - The symbol's ``detail`` is the ``name: <value>`` field if found
+      within a small window after the step header (no YAML parsing —
+      we just look at indented lines that aren't another ``- …`` step).
+
+    The result is suitable for the LSP outline panel even when the
+    surrounding YAML is mid-edit and structurally invalid.
+    """
+    root_children = []
+    # Each stack entry: (indent_col, children_list_to_append_to,
+    #                    pending_parent_symbol or None).
+    stack = [(-1, root_children, None)]
+
+    def _attach_name(parent_symbol, start_line):
+        """Look for the nearest ``name:`` field in the children of ``parent``."""
+        if parent_symbol is None or start_line + 1 >= len(lines):
+            return
+        base_indent = len(lines[start_line]) - len(lines[start_line].lstrip(" "))
+        for j in range(start_line + 1, min(start_line + 10, len(lines))):
+            l = lines[j]
+            stripped = l.lstrip(" ")
+            indent = len(l) - len(stripped)
+            if indent <= base_indent and stripped.strip() != "":
+                break
+            m = _NAME_FIELD.match(l)
+            if m:
+                value = m.group("value").strip("\"' ")
+                parent_symbol.detail = value
+                return
+
+    for i, raw_line in enumerate(lines):
+        m = _STEP_LINE.match(raw_line)
+        if not m:
+            continue
+        cmd = m.group("ident")
+        if cmd not in item_cmds:
+            continue
+        indent = len(m.group("lead")) - len(m.group("lead").lstrip(" "))
+        # Pop the stack until we find a parent with strictly smaller indent.
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        if not stack:
+            stack.append((-1, root_children, None))
+        parent_children = stack[-1][1]
+
+        ident_start = m.start("ident")
+        ident_end = m.end("ident")
+        symbol = DocumentSymbol(
+            name=cmd,
+            detail=None,
+            kind=SymbolKind.Function,
+            range=Range(
+                start=Position(line=i, character=0),
+                end=Position(line=i, character=len(raw_line.rstrip("\n"))),
+            ),
+            selection_range=Range(
+                start=Position(line=i, character=ident_start),
+                end=Position(line=i, character=ident_end),
+            ),
+            children=[],
+        )
+        parent_children.append(symbol)
+        stack.append((indent, symbol.children, symbol))
+        _attach_name(symbol, i)
+    return root_children
+
+
+def _make_server():
+    server = LanguageServer("testium-lsp", "0.1.0")
+    schema = dump_all_schemas()
+    item_completions = _build_item_completions(schema)
+    # Set of cmd names accepted by the outline / hover passes. We include
+    # action names (console open/close/…, plot open/close/…, …) too so they
+    # appear in the outline tree and respond to hover.
+    item_cmds = set()
+    for cmd, entry in schema["items"].items():
+        if cmd == "default":
+            continue
+        item_cmds.add(cmd)
+        item_cmds.update(entry.get("actions", {}).keys())
+
+    @server.feature(
+        TEXT_DOCUMENT_COMPLETION,
+        CompletionOptions(trigger_characters=["-", " "]),
+    )
+    def completion(params: CompletionParams):
+        doc = server.workspace.get_text_document(params.text_document.uri)
+        line_idx = params.position.line
+        if line_idx >= len(doc.lines):
+            return CompletionList(is_incomplete=False, items=[])
+        line = doc.lines[line_idx]
+        # Only look at what's left of the cursor.
+        prefix = line[: params.position.character]
+        if not _LINE_START_STEP.match(prefix):
+            return CompletionList(is_incomplete=False, items=[])
+        return CompletionList(is_incomplete=False, items=item_completions)
+
+    @server.feature(TEXT_DOCUMENT_HOVER)
+    def hover(params: HoverParams):
+        doc = server.workspace.get_text_document(params.text_document.uri)
+        line_idx = params.position.line
+        if line_idx >= len(doc.lines):
+            return None
+        line = doc.lines[line_idx]
+        # Only respond when the cursor is on the type part of a step line
+        # ("- sleep:") — never for arbitrary words in a string.
+        step_match = _STEP_LINE.match(line)
+        if not step_match:
+            return None
+        word = _word_at(line, params.position.character)
+        if word is None:
+            return None
+        start, end, text = word
+        if text != step_match.group("ident") or text not in item_cmds:
+            return None
+        # Resolve the entry: top-level item, or action of any parent.
+        entry = schema["items"].get(text)
+        if entry is None:
+            for parent_entry in schema["items"].values():
+                actions = parent_entry.get("actions") or {}
+                if text in actions:
+                    entry = actions[text]
+                    break
+        if entry is None:
+            return None
+        return Hover(
+            contents=MarkupContent(
+                kind=MarkupKind.Markdown,
+                value=_render_item_markdown(text, entry),
+            ),
+            range=Range(
+                start=Position(line=line_idx, character=start),
+                end=Position(line=line_idx, character=end),
+            ),
+        )
+
+    @server.feature(TEXT_DOCUMENT_DOCUMENT_SYMBOL)
+    def document_symbols(params: DocumentSymbolParams):
+        doc = server.workspace.get_text_document(params.text_document.uri)
+        return _build_document_symbols(doc.lines, item_cmds)
+
+    return server
+
+
+def serve():
+    """Start the LSP server on stdio. Blocks until the client disconnects."""
+    server = _make_server()
+    server.start_io()

src/testium/lua_func/json-rpc.lua

@@ -41,8 +41,7 @@ end
 --- INTERNAL: Handle requests from the client
 function JSONRPC:_handle_request(req)
     local method = self.methods[req.method]
-    local ok, ret
-    local res, err
+    local ok, ret, err
     if not method then
         if req.id then self:_send_error(req.id, string.format("Method '%s' not registered in lua server")) end
         return
@@ -52,15 +51,18 @@ function JSONRPC:_handle_request(req)
 
     -- Only send response if it's not a Notification (notifications have no ID)
     if req.id then
-        if ok then
-            res = ret
-            if res == nil then
-                self:_send_error(req.id, tostring(err))
-            else
-                self:_send({ jsonrpc = "2.0", result = { returned_value = res }, id = req.id })
-            end
-        else
+        if not ok then
+            -- pcall trapped a runtime error in the method itself.
+            self:_send_error(req.id, tostring(ret))
+        elseif err ~= nil then
+            -- Method ran but signaled a logical error via its 2nd return.
             self:_send_error(req.id, tostring(err))
+        else
+            -- Success. A user function returning nothing yields ret==nil;
+            -- encode it as JSON null so "returned_value" stays present.
+            local val = ret
+            if val == nil then val = json.null end
+            self:_send({ jsonrpc = "2.0", result = { returned_value = val }, id = req.id })
         end
     end
 end

src/testium/main_win/desktop_integration.py

@@ -0,0 +1,95 @@
+"""Install a desktop entry + icon under the user's data dir so desktop shells
+show the testium icon in the task bar / dock.
+
+On a native Wayland session GNOME takes a window's task-bar icon from the
+``.desktop`` file whose name (or ``StartupWMClass``) matches the window
+``app_id`` — ``QGuiApplication.setWindowIcon`` is ignored there. The portable
+channels (source checkout, PyInstaller binary, AppImage) install no system
+desktop file, so we drop an idempotent one in ``~/.local/share``. The window
+``app_id`` is set to ``testium`` (see ``QApplication.setDesktopFileName`` in
+``testium_win``), which is exactly this file's base name.
+
+Flatpak ships its own ``org.testium.Testium.desktop`` and keeps its own app id,
+so the caller skips this integration there.
+"""
+import os
+import sys
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QPixmap
+
+# Must match QApplication.setDesktopFileName(...) for the GUI, and is used as
+# both the desktop-file base name and the StartupWMClass.
+APP_ID = "testium"
+
+
+def _launch_command():
+    """Best-effort Exec= for the menu entry. Not needed for icon matching, but
+    makes the entry actually launchable when possible."""
+    appimage = os.environ.get("APPIMAGE")
+    if appimage:
+        return f'"{appimage}"'
+    if getattr(sys, "frozen", False):
+        return f'"{os.path.abspath(sys.executable)}"'
+    argv0 = os.path.abspath(sys.argv[0]) if sys.argv and sys.argv[0] else ""
+    if argv0 and os.path.exists(argv0):
+        return f'"{os.path.abspath(sys.executable)}" "{argv0}"'
+    return f'"{os.path.abspath(sys.executable)}" -m testium'
+
+
+def ensure_desktop_entry():
+    """Create (or refresh) ~/.local/share icon + desktop entry. Best-effort:
+    any failure is swallowed so it can never take the GUI down.
+
+    Freedesktop-only: a no-op off Linux (Windows / macOS use the window icon)."""
+    if not sys.platform.startswith("linux"):
+        return
+    try:
+        data_home = os.environ.get("XDG_DATA_HOME") or os.path.join(
+            os.path.expanduser("~"), ".local", "share"
+        )
+        icon_dir = os.path.join(data_home, "icons", "hicolor", "256x256", "apps")
+        app_dir = os.path.join(data_home, "applications")
+        icon_path = os.path.join(icon_dir, f"{APP_ID}.png")
+        desktop_path = os.path.join(app_dir, f"{APP_ID}.desktop")
+
+        os.makedirs(icon_dir, exist_ok=True)
+        os.makedirs(app_dir, exist_ok=True)
+
+        # Icon: render the bundled Qt resource to a PNG once. Requires a live
+        # QGuiApplication (the caller creates it before calling us).
+        if not os.path.isfile(icon_path):
+            pixmap = QPixmap(u":/black/testium_logo.png")
+            if not pixmap.isNull():
+                pixmap = pixmap.scaled(
+                    256, 256,
+                    Qt.AspectRatioMode.KeepAspectRatio,
+                    Qt.TransformationMode.SmoothTransformation,
+                )
+                pixmap.save(icon_path, "PNG")
+
+        # Absolute Icon= path so the shell resolves it without an icon-cache
+        # refresh; StartupWMClass lets X11 / XWayland match too.
+        desktop = (
+            "[Desktop Entry]\n"
+            "Type=Application\n"
+            "Name=Testium\n"
+            "Comment=Test sequencer\n"
+            f"Icon={icon_path}\n"
+            f"Exec={_launch_command()} %f\n"
+            "Terminal=false\n"
+            f"StartupWMClass={APP_ID}\n"
+            "Categories=Utility;Development;\n"
+        )
+
+        # Write only when missing or changed, to avoid needless menu churn.
+        current = None
+        if os.path.isfile(desktop_path):
+            with open(desktop_path, "r") as fh:
+                current = fh.read()
+        if current != desktop:
+            with open(desktop_path, "w") as fh:
+                fh.write(desktop)
+    except Exception:
+        # Desktop integration is a nicety, never a hard requirement.
+        pass

src/testium/main_win/file_dialog.py

@@ -0,0 +1,21 @@
+"""Helpers for Qt file/directory dialogs.
+
+In Flatpak the native QFileDialog goes through the XDG document portal,
+which returns ``/run/user/UID/doc/.../<file>`` and only exposes the
+selected file — sibling files (param.yaml, scripts, recent paths in
+preferences, ...) are unreachable. Forcing Qt's own non-native dialog
+makes it walk the real filesystem mounted via ``--filesystem=home``
+and return a regular path.
+"""
+
+import os
+
+from PySide6.QtWidgets import QFileDialog
+
+
+def options():
+    """Default ``QFileDialog`` options for the current runtime."""
+    opts = QFileDialog.Options()
+    if os.path.isfile("/.flatpak-info"):
+        opts |= QFileDialog.Option.DontUseNativeDialog
+    return opts

src/testium/main_win/preference_win/preference_win.py

@@ -3,6 +3,7 @@ from PySide6.QtWidgets import QDialog, QFileDialog
 from PySide6.QtGui import QFont
 
 from main_win.preference_win.preference_core_win import Ui_preferenceWindow
+from main_win import file_dialog
 
 import interpreter.utils.settings as prefs
 
@@ -193,6 +194,7 @@ class PrefWindow(QDialog):
             self,
             caption="Select the default report directory",
             dir=self.ui.editDefaultReportPath.text(),
+            options=file_dialog.options(),
         )
         if path:
             self.ui.editDefaultReportPath.setText(path)
@@ -203,6 +205,7 @@ class PrefWindow(QDialog):
             self,
             caption="Select the default log directory",
             dir=self.ui.editDefaultLogPath.text(),
+            options=file_dialog.options(),
         )
         if path:
             self.ui.editDefaultLogPath.setText(path)
@@ -213,6 +216,7 @@ class PrefWindow(QDialog):
             self,
             caption="Select the python interpreter",
             dir=self.ui.editPythonPath.text(),
+            options=file_dialog.options(),
         )
         if path:
             self.ui.editPythonPath.setText(path)
@@ -220,7 +224,10 @@ class PrefWindow(QDialog):
     @Slot()
     def on_butLuaPath_pressed(self):
         path, _ = QFileDialog.getOpenFileName(
-            self, caption="Select the lua interpreter", dir=self.ui.editLuaPath.text()
+            self,
+            caption="Select the lua interpreter",
+            dir=self.ui.editLuaPath.text(),
+            options=file_dialog.options(),
         )
         if path:
             self.ui.editLuaPath.setText(path)

src/testium/main_win/test_file_manager.py

@@ -9,6 +9,7 @@ from PySide6.QtWidgets import QApplication, QFileDialog, QProgressDialog
 from interpreter.process import TestProcess
 from interpreter.utils.test_ctrl import TestSetController
 from main_win.test_controller_service import TestControllerService
+from main_win import file_dialog
 import interpreter.utils.settings as prefs
 from runtime.tum_except import ETUMFileError, ETUMRuntimeError
 
@@ -213,7 +214,8 @@ class TestFileManager:
         if w.testFile is not None:
             d = os.path.dirname(w.testFile)
         file_name, _ = QFileDialog.getOpenFileName(
-            w, "Open the test file", d, "testium file (*.tum);;All Files (*)"
+            w, "Open the test file", d,
+            "testium file (*.tum);;All Files (*)", options=file_dialog.options()
         )
         if file_name:
             self.reload(file_name)

src/testium/main_win/test_runner.py

@@ -176,7 +176,7 @@ class TestRunner:
             w.actionOpenTest.setDisabled(True)
             w.actionExit.setDisabled(True)
             icon = QtGui.QIcon()
-            icon.addPixmap(QtGui.QPixmap(icon_prefix() + "/pause.png"), QtGui.QIcon.Normal, QtGui.QIcon.Off)
+            icon.addPixmap(QtGui.QPixmap(icon_prefix() + "/pause2.png"), QtGui.QIcon.Normal, QtGui.QIcon.On)
             w.actionStart_test.setIcon(icon)
             w.actionStart_test.setText("Pause test")
             w.actionPreferences.setDisabled(True)

src/testium/main_win/testium_win.py

@@ -37,6 +37,7 @@ from interpreter.utils.icons import icon_prefix
 
 from main_win.test_run.outlog import OutLog
 from main_win.test_run.test_run import ThreadTestStatus
+from main_win import file_dialog
 import interpreter.utils.settings as prefs
 from runtime.stdout_redirect import stdio_redir
 import api.testium as tm
@@ -484,7 +485,8 @@ class MainWindow(QMainWindow, Ui_MainWindow):
         else:
             initialPath = None
         fileName, _ = QFileDialog.getSaveFileName(
-            self, "Path to Log file", initialPath, "Log Files (*.log);;All Files (*)"
+            self, "Path to Log file", initialPath, "Log Files (*.log);;All Files (*)",
+            options=file_dialog.options(),
         )
         if fileName:
             shutil.copy(self.logFileName, fileName)
@@ -525,7 +527,8 @@ class MainWindow(QMainWindow, Ui_MainWindow):
         else:
             initialPath = None
         fileName, _ = QFileDialog.getSaveFileName(
-            self, "Path to log file", initialPath, "Log Files (*.log);;All Files (*)"
+            self, "Path to log file", initialPath, "Log Files (*.log);;All Files (*)",
+            options=file_dialog.options(),
         )
         if fileName:
             self.editLogFilePath.setText(fileName)
@@ -675,6 +678,24 @@ def MainWin(
     debug=False,
 ):
     app = QApplication(sys.argv)
+    # Application identity so desktop shells (GNOME, ...) show the testium
+    # icon in the task bar / dock instead of a generic one. On Wayland this
+    # sets the surface app_id; on X11/XWayland it sets WM_CLASS, so the window
+    # stops inheriting the launcher's class (e.g. "python3" under the AppImage,
+    # which is what GNOME was keying the wrong icon off) and the window icon
+    # below is used as the fallback. In Flatpak the id must be the Flatpak app
+    # id so it matches the installed desktop file.
+    app.setApplicationName("Testium")
+    app.setApplicationDisplayName("Testium")
+    app.setDesktopFileName(os.environ.get("FLATPAK_ID", "testium"))
+    app.setWindowIcon(QIcon(u":/black/testium_logo.png"))
+    # On native Wayland the task-bar icon comes from an installed desktop file
+    # matched to the app_id, not from setWindowIcon(). Flatpak ships its own;
+    # for the other Linux channels drop an idempotent one under ~/.local/share.
+    # Windows / macOS use the window icon set above, so this is Linux-only.
+    if sys.platform.startswith("linux") and not os.environ.get("FLATPAK_ID"):
+        from main_win.desktop_integration import ensure_desktop_entry
+        ensure_desktop_entry()
     ui = MainWindow(
         test_file,
         config_files,

src/testium/py_func/__main__.py

@@ -8,16 +8,20 @@ def exception_handler(typ_exc, value, trbk):
     print(f"Critical failure : '{value}'.")
     tb = traceback.format_exception(typ_exc, value, trbk)
     print("".join(tb))
+    print(f"  python    : {sys.executable}")
+    print(f"  sys.path  : {sys.path}")
 
 sys.excepthook = exception_handler
 
-p = Path(__file__)
-p = p.parent / ".."
-p = p.resolve()
-
-sys.path.append(p)
+# Make the parent directory of py_func/ (= the testium package dir, which also
+# contains runtime/, lua_func/, …) the first entry on sys.path so `from py_func
+# import main` and `from runtime…` resolve regardless of cwd or how this script
+# was invoked. str() because some importers don't play well with PathLike entries.
+_pkg_parent = str((Path(__file__).resolve().parent / "..").resolve())
+if _pkg_parent not in sys.path:
+    sys.path.insert(0, _pkg_parent)
 
 from py_func import main
 
 if __name__ == '__main__':
-    main()
+    main()

src/testium/runtime/jrpc.py

@@ -200,6 +200,7 @@ class JsonRpcConnection:
 
         Raises:
             TimeoutError: If no response is received within `timeout`.
+            ConnectionAbortedError: If stop() was called while waiting.
         """
 
         req_id = next(self.id_gen)
@@ -214,7 +215,12 @@ class JsonRpcConnection:
             self.pending.pop(req_id, None)
             raise TimeoutError("Timeout JSON-RPC")
 
-        return self.pending.pop(req_id)["response"]
+        entry = self.pending.pop(req_id)
+        if entry["response"] is None:
+            # Woken by stop() (or by a malformed dispatch) rather than by a
+            # real response — abort the call so callers don't block further.
+            raise ConnectionAbortedError("JSON-RPC client stopped")
+        return entry["response"]
 
     def print_info(self, msg):
         if self.dbg_out is not None:
@@ -223,6 +229,10 @@ class JsonRpcConnection:
     def stop(self):
         if self.running:
             self.running = False
+        # Wake any in-flight call() so it doesn't sit on its (default 1h)
+        # timeout. The response stays None and call() raises ConnectionAbortedError.
+        for entry in list(self.pending.values()):
+            entry["event"].set()
 
     def join(self):
         self.recv_thread.join()

test/benchmark/.gitignore

@@ -0,0 +1 @@
+cases/

test/benchmark/README.md

@@ -0,0 +1,116 @@
+# Load-time benchmark
+
+Measures how long *testium* takes to **load** a `.tum` test tree — template
+rendering (jinja) + YAML parsing + test-tree construction — *without* executing
+it. Purpose: get reproducible numbers before/after load-path optimisations, and
+attribute any gain to a specific part of the pipeline.
+
+It is meant for *very long* tests, the kind you can build with `jinja` loops and
+`!include`, where load time becomes noticeable.
+
+## Files
+
+| File | Role |
+|------|------|
+| `gen_bench_test.py` | Generates a synthetic `.tum` tree (the test input). |
+| `load_bench.py` | Drives the **real** loader in-process and times it. |
+| `run.sh` | Convenience: generate + time across profiles, using the project venv. |
+| `cases/` | Generated trees (git-ignored, recreated on demand). |
+
+The benchmark `.tum` files are **generated**, not committed — the generator is
+the artifact. They use only `let` leaves and `group` containers, so loading has
+no runtime side effect (no subprocess, no `<| |>` eval) and the timing reflects
+the parse/build pipeline alone.
+
+## Quick start
+
+```bash
+# default matrix (all profiles), 5 repeats each
+./test/benchmark/run.sh
+
+# one profile at one size
+./test/benchmark/run.sh repeat 2000
+
+# more repeats for a tighter min
+REPEAT=10 ./test/benchmark/run.sh includes 1000
+```
+
+`run.sh` uses the project venv at `test/tmp/.venv` (created by `./run.sh`). If it
+is missing, run `./run.sh` once first.
+
+To drive the harness directly on any `.tum` (not just generated ones):
+
+```bash
+test/tmp/.venv/bin/python3 test/benchmark/load_bench.py --repeat 5 --quiet path/to/main.tum
+```
+
+## Profiles
+
+Each profile isolates one cost. `--size` is the profile-specific count.
+
+| Profile | What it builds | Stresses |
+|---------|----------------|----------|
+| `flat` | one main file, N inline `let` steps | big YAML parse + linear object build |
+| `includes` | main `!include`s N **distinct** sub-files | per-include template+YAML+tempfile, `sequence` splice |
+| `repeat` | main `!include`s the **same** parametrised leaf N times | jinja **recompilation** of an identical template |
+| `jinja` | one main file, `{% for %}` emitting N steps | single large render + single large parse |
+| `deep` | nested includes, depth N | include recursion (see caveat) |
+| `mix` | groups + jinja loop + distinct + repeated includes | realistic blend |
+
+## Reading the output
+
+```
+phase              min      median
+initial         0.1131      0.1285   <- pass 1: discover config files (no includes)
+loadtest        1.0724      1.0900   <- config fixpoint loop + full recursive include load
+build           0.1850      0.1976   <- TestSet: load_test_recursively tree build
+total           1.3886      1.4227
+counters  (last run):
+  templates :    1003 calls   0.5247s  (exclusive: jinja compile+render+tempfile)
+  yaml      :    1004 parses   1.4696s  (inclusive of nested includes)
+```
+
+- **min** is the headline (least noisy); median is a sanity check.
+- **initial / loadtest / build** map to the three pipeline stages in
+  `interpreter/process.py` and `interpreter/test_set.py`. The main file is
+  rendered+parsed across `initial` *and* `loadtest` (the loader does ~3 passes).
+- **templates** = number of `template_to_test()` calls and their *exclusive*
+  wall time (one file render each — pure jinja compile+render+tempfile I/O).
+  A high count with the same source file = recompilation, the `repeat` case.
+- **yaml** = number of `yaml_load()` parses. Its time is *inclusive* of nested
+  includes, so use the **count** for attribution, not the seconds.
+
+## Mapping to the optimisation axes
+
+| Axis (see DESIGN / discussion) | Watch | Best profile to prove it |
+|--------------------------------|-------|--------------------------|
+| 1 — cache compiled jinja templates | `templates` time drops, count unchanged | `repeat` |
+| 2 — drop the tempfile round-trip | `templates` time drops | `includes`, `repeat`, `mix` |
+| 3 — C YAML loader (libyaml) | `yaml` time / `loadtest` drops | `flat`, `jinja` |
+| 6 — O(n²) sequence splice | `build` drops | `includes`, `mix` |
+
+## How to compare before/after a change
+
+1. Run the matrix on the current code, keep the output.
+2. Apply one axis.
+3. Re-run the **same** profiles/sizes; compare `min` per phase and the counters.
+
+Change one axis at a time so the attribution is clean. Run on an idle machine
+(and note the disk: on a USB stick the tempfile round-trip of axis 2 weighs
+more).
+
+## Caveat: deep includes
+
+The loader is recursive and spends ~10 stack frames per include level, so
+`deep` hits Python's `RecursionError` around ~90 nested levels. The harness
+reports this cleanly instead of crashing. Real tests are *wide* (many steps /
+many includes), not deep, so `includes`/`repeat`/`jinja`/`mix` are the
+representative "very long" cases.
+
+## Notes
+
+- No execution is triggered — timing stops where `Batch` would mark the test
+  *loaded*.
+- The profiles contain no `<| |>`, so the external eval process is not started.
+  Pass `--with-eval` to `load_bench.py` for trees that evaluate at load time.
+- Numbers are machine- and disk-specific; only compare runs from the same host.

test/benchmark/gen_bench_test.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Generate synthetic ``.tum`` test trees to benchmark *load* time.
+
+The generated trees are deliberately cheap to *build* (only ``let`` leaves and
+``group`` containers — no subprocess, no runtime side effect) so the load
+benchmark measures the parse / template / tree-build pipeline and nothing else.
+
+Profiles, each targeting a specific cost in the loader:
+
+  flat      one main file, N inline ``let`` steps, no include, no jinja.
+            Baseline: YAML parse of a big document + linear object build.
+
+  includes  main ``!include``s N *distinct* sub-files (a few steps each).
+            Stresses the per-include template+YAML+tempfile round-trip and the
+            ``sequence`` splice in test_set.load_test_recursively.
+
+  repeat    main ``!include``s the *same* parametrised leaf file N times.
+            Stresses jinja *recompilation*: the compiled template is identical
+            every time, only the render params (idx) differ -> the case a
+            template cache collapses.
+
+  jinja     one main file whose ``{% for %}`` loop emits N steps.
+            Stresses a single large jinja render + a single large YAML parse.
+
+  deep      nested includes, depth N (main -> d0 -> d1 -> ...).
+            Stresses include recursion and per-level template+YAML.
+
+  mix       a realistic blend: groups, a jinja loop, distinct includes and a
+            repeated parametrised include.
+
+Usage:
+    gen_bench_test.py --profile repeat --size 1000 --out cases/repeat_1000
+    -> writes <out>/main.tum (+ includes, + param.yaml) and prints the path.
+"""
+import argparse
+import os
+import shutil
+
+
+def _let(indent, i, name=None):
+    name = name if name is not None else f"s{i}"
+    pad = " " * indent
+    return (
+        f"{pad}- let:\n"
+        f"{pad}    name: {name}\n"
+        f"{pad}    values:\n"
+        f"{pad}        - k{i}: {i}\n"
+    )
+
+
+def gen_flat(out, n):
+    body = "".join(_let(8, i) for i in range(n))
+    main = f"main:\n    name: bench flat {n}\n    steps:\n{body}"
+    _write(out, "main.tum", main)
+
+
+def gen_includes(out, n):
+    steps = "".join(f"        - !include inc_{i}.tum\n" for i in range(n))
+    main = f"main:\n    name: bench includes {n}\n    steps:\n{steps}"
+    _write(out, "main.tum", main)
+    for i in range(n):
+        # each include is a YAML *sequence* (list of steps)
+        seq = "".join(_let(0, i * 3 + j, name=f"inc{i}_{j}") for j in range(3))
+        _write(out, f"inc_{i}.tum", seq)
+
+
+def gen_repeat(out, n):
+    steps = "".join(
+        f"        - !include {{file: leaf.tum, idx: {i}}}\n" for i in range(n)
+    )
+    main = f"main:\n    name: bench repeat {n}\n    steps:\n{steps}"
+    _write(out, "main.tum", main)
+    leaf = (
+        "- let:\n"
+        "    name: leaf_{{ idx }}\n"
+        "    values:\n"
+        "        - leaf_{{ idx }}: {{ idx }}\n"
+    )
+    _write(out, "leaf.tum", leaf)
+
+
+def gen_jinja(out, n):
+    main = (
+        f"main:\n    name: bench jinja {n}\n    steps:\n"
+        "{% for i in range(" + str(n) + ") %}\n"
+        "        - let:\n"
+        "            name: j{{ i }}\n"
+        "            values:\n"
+        "                - k{{ i }}: {{ i }}\n"
+        "{% endfor %}\n"
+    )
+    _write(out, "main.tum", main)
+
+
+def gen_deep(out, n):
+    main = (
+        f"main:\n    name: bench deep {n}\n    steps:\n"
+        "        - let:\n            name: top\n            values:\n                - a: 0\n"
+        "        - !include d_0.tum\n"
+    )
+    _write(out, "main.tum", main)
+    for i in range(n):
+        seq = _let(0, i, name=f"d{i}")
+        if i < n - 1:
+            seq += f"- !include d_{i + 1}.tum\n"
+        _write(out, f"d_{i}.tum", seq)
+
+
+def gen_mix(out, n):
+    # n groups, each: 2 inline lets, one distinct include, one repeated include,
+    # plus a small jinja loop. Roughly ~6*n steps.
+    per = max(1, n)
+    parts = [f"main:\n    name: bench mix {n}\n    steps:\n"]
+    for g in range(per):
+        parts.append(
+            f"        - group:\n"
+            f"            name: grp{g}\n"
+            f"            steps:\n"
+        )
+        parts.append(_let(16, g * 2, name=f"g{g}_a"))
+        parts.append(_let(16, g * 2 + 1, name=f"g{g}_b"))
+        parts.append(f"                - !include inc_{g}.tum\n")
+        parts.append(f"                - !include {{file: leaf.tum, idx: {g}}}\n")
+        parts.append(
+            "{% for i in range(3) %}\n"
+            f"                - let:\n"
+            f"                    name: g{g}_j{{{{ i }}}}\n"
+            f"                    values:\n"
+            f"                        - g{g}_k{{{{ i }}}}: {{{{ i }}}}\n"
+            "{% endfor %}\n"
+        )
+    _write(out, "main.tum", "".join(parts))
+    for g in range(per):
+        _write(out, f"inc_{g}.tum", _let(0, g, name=f"mixinc{g}"))
+    _write(
+        out,
+        "leaf.tum",
+        "- let:\n    name: mixleaf_{{ idx }}\n    values:\n        - mixleaf_{{ idx }}: {{ idx }}\n",
+    )
+
+
+PROFILES = {
+    "flat": gen_flat,
+    "includes": gen_includes,
+    "repeat": gen_repeat,
+    "jinja": gen_jinja,
+    "deep": gen_deep,
+    "mix": gen_mix,
+}
+
+
+def _write(out, name, content):
+    with open(os.path.join(out, name), "w") as f:
+        f.write(content)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--profile", required=True, choices=sorted(PROFILES))
+    ap.add_argument("--size", type=int, default=1000,
+                    help="profile-specific count (steps / includes / depth)")
+    ap.add_argument("--out", required=True, help="output directory (recreated)")
+    args = ap.parse_args()
+
+    out = os.path.abspath(args.out)
+    if os.path.isdir(out):
+        shutil.rmtree(out)
+    os.makedirs(out)
+
+    # minimal config file so the loader does not emit "no param file" noise
+    _write(out, "param.yaml", "bench_dummy: 1\n")
+
+    PROFILES[args.profile](out, args.size)
+    print(os.path.join(out, "main.tum"))
+
+
+if __name__ == "__main__":
+    main()

test/benchmark/load_bench.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Time the testium *load* pipeline on a given ``.tum`` tree.
+
+It drives the real loader code (``TestProcess._load_initial_params`` /
+``_load_test`` then ``TestSet(...)``) in-process, so the numbers track the
+production path and stay honest as the code evolves. Execution is never
+triggered — we stop exactly where ``Batch`` would report the test as *loaded*.
+
+Reported per run, over ``--repeat`` iterations (min is the headline, least
+noisy):
+
+    initial   first pass: discover config files (template+YAML, no includes)
+    loadtest  config-file fixpoint loop + full recursive include/template/YAML
+    build     TestSet construction: the load_test_recursively tree build
+    total     sum of the three
+
+Plus instrumentation counters (exact call counts, wall time) for the two
+hot leaves the optimisation axes target:
+
+    templates  jinja template_to_test() calls   (axis 1 compile cache, axis 2 tempfile)
+    yaml       yaml_load() parses               (axis 3 C loader)
+
+template time is exclusive (one file render); yaml time is wall-inclusive of
+nested includes, so lean on the *counts* for attribution.
+
+Must run inside the project venv (jinja2, pyyaml, telnetlib3, ...). The
+benchmark profiles contain no ``<| |>`` so the external eval process is not
+needed; pass --with-eval to start it for faithfulness on eval-heavy trees.
+
+Usage (see run.sh for the convenience wrapper):
+    test/tmp/.venv/bin/python3 test/benchmark/load_bench.py [--repeat 5] <main.tum>
+"""
+import argparse
+import os
+import statistics
+import sys
+from queue import Queue
+from time import perf_counter
+
+# --- bootstrap: src/testium for flat imports, src for `import testium` --------
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "src"))
+sys.path.insert(0, os.path.join(ROOT, "src", "testium"))
+
+import api.testium as tm  # noqa: E402
+from interpreter.utils.test_init import env_init, apply_overrides  # noqa: E402
+from interpreter.utils.test_ctrl import TestSetController  # noqa: E402
+from interpreter.process import TestProcess  # noqa: E402
+from interpreter.test_set import TestSet  # noqa: E402
+from interpreter.utils.py_eval import eval_process_init  # noqa: E402
+from interpreter.utils.api_srv import api_request  # noqa: E402
+
+# --- instrumentation: count + time the two hot leaves -------------------------
+import interpreter.process as _proc  # noqa: E402
+import interpreter.utils.include as _inc  # noqa: E402
+import interpreter.utils.test_init as _ti  # noqa: E402
+import interpreter.utils.template as _tpl  # noqa: E402
+import interpreter.utils.yaml_load as _yl  # noqa: E402
+
+_C = {"tpl_n": 0, "tpl_t": 0.0, "yaml_n": 0, "yaml_t": 0.0}
+_orig_tpl = _tpl.template_to_test
+_orig_yaml = _yl.yaml_load
+
+
+def _wrap_tpl(*a, **k):
+    t = perf_counter()
+    try:
+        return _orig_tpl(*a, **k)
+    finally:
+        _C["tpl_t"] += perf_counter() - t
+        _C["tpl_n"] += 1
+
+
+def _wrap_yaml(*a, **k):
+    t = perf_counter()
+    try:
+        return _orig_yaml(*a, **k)
+    finally:
+        _C["yaml_t"] += perf_counter() - t
+        _C["yaml_n"] += 1
+
+
+# rebind in every module that did `from ... import template_to_test / yaml_load`
+for _m in (_proc, _inc):
+    _m.template_to_test = _wrap_tpl
+for _m in (_proc, _inc, _ti):
+    _m.yaml_load = _wrap_yaml
+
+
+def _reset_counters():
+    _C.update(tpl_n=0, tpl_t=0.0, yaml_n=0, yaml_t=0.0)
+
+
+def load_once(tp, fname, test_dir):
+    """One full load (no execution). Returns (initial, loadtest, build) seconds."""
+    t0 = perf_counter()
+    init_pf, gv = tp._load_initial_params(test_dir)
+    t1 = perf_counter()
+    test_dict, _pf = tp._load_test(init_pf, gv)
+    t2 = perf_counter()
+    TestSet(fname, test_dict, Queue())
+    t3 = perf_counter()
+    return (t1 - t0, t2 - t1, t3 - t2)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("main_tum", help="path to the generated main.tum")
+    ap.add_argument("--repeat", type=int, default=5)
+    ap.add_argument("--with-eval", action="store_true",
+                    help="start the external eval process (needed only for <| |> at load)")
+    ap.add_argument("--quiet", action="store_true",
+                    help="silence the loader's INFO output during runs")
+    args = ap.parse_args()
+
+    fname = os.path.abspath(args.main_tum)
+    if not os.path.isfile(fname):
+        ap.error(f"not found: {fname}")
+    test_dir = os.path.dirname(fname)
+
+    env_init()
+    apply_overrides({}, {})
+
+    eval_proc = None
+    if args.with_eval:
+        eval_proc = eval_process_init(api_request, 10, test_dir)
+        eval_proc.start()
+        eval_proc.wait_ready(10)
+
+    if args.quiet:
+        # the loader prints a couple of INFO lines per config file; mute stdout
+        # around the measured section to avoid I/O skew.
+        devnull = open(os.devnull, "w")
+        real_stdout = sys.stdout
+
+    tp = TestProcess(fname, Queue(), TestSetController(),
+                     config_files=[], defines={}, gui_defaults={}, text_mode=True)
+
+    samples = []  # list of (initial, loadtest, build)
+    last_counters = None
+    try:
+        for r in range(args.repeat):
+            _reset_counters()
+            if args.quiet:
+                sys.stdout = devnull
+            try:
+                samples.append(load_once(tp, fname, test_dir))
+            except RecursionError:
+                if args.quiet:
+                    sys.stdout = real_stdout
+                print(f"file      : {fname}")
+                print("ERROR     : RecursionError during load — the include "
+                      "nesting is too deep for the recursive loader.\n"
+                      "            (each include level costs ~10 stack frames; "
+                      "raise sys.setrecursionlimit to probe further.)")
+                return 2
+            except Exception as e:  # noqa: BLE001 - report, don't crash the bench
+                if args.quiet:
+                    sys.stdout = real_stdout
+                print(f"file      : {fname}")
+                print(f"ERROR     : load failed: {type(e).__name__}: {e}")
+                return 2
+            finally:
+                if args.quiet:
+                    sys.stdout = real_stdout
+            last_counters = dict(_C)
+    finally:
+        if eval_proc is not None:
+            eval_proc.stop()
+            eval_proc.join()
+        if args.quiet:
+            devnull.close()
+
+    initial = [s[0] for s in samples]
+    loadtest = [s[1] for s in samples]
+    build = [s[2] for s in samples]
+    total = [sum(s) for s in samples]
+
+    def stat(xs):
+        return min(xs), statistics.median(xs)
+
+    print(f"file      : {fname}")
+    print(f"repeats   : {args.repeat}   (showing  min | median, seconds)")
+    print(f"{'phase':<10}{'min':>12}{'median':>12}")
+    for name, xs in (("initial", initial), ("loadtest", loadtest),
+                     ("build", build), ("total", total)):
+        mn, md = stat(xs)
+        print(f"{name:<10}{mn:>12.4f}{md:>12.4f}")
+    if last_counters:
+        print("counters  (last run):")
+        print(f"  templates : {last_counters['tpl_n']:>7d} calls   "
+              f"{last_counters['tpl_t']:>8.4f}s  (exclusive: jinja compile+render+tempfile)")
+        print(f"  yaml      : {last_counters['yaml_n']:>7d} parses  "
+              f"{last_counters['yaml_t']:>8.4f}s  (inclusive of nested includes)")
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

test/benchmark/run.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Load-time benchmark driver: generate synthetic .tum trees and time the
+# testium load pipeline on them, using the project venv.
+#
+# Usage:
+#   ./test/benchmark/run.sh                     # default matrix (all profiles)
+#   ./test/benchmark/run.sh <profile> <size>    # one profile at one size
+#   REPEAT=10 ./test/benchmark/run.sh repeat 2000
+#
+# Profiles: flat includes repeat jinja deep mix   (see gen_bench_test.py)
+#
+# Generated trees go under test/benchmark/cases/ (git-ignored). The numbers
+# are wall-clock; run on an otherwise idle machine and compare min values.
+set -e
+
+SCRIPT_DIR="$(realpath "$(dirname "$(readlink -f "$0")")")"
+PROJECT_DIR="$(realpath "$SCRIPT_DIR/../..")"
+VPY="$PROJECT_DIR/test/tmp/.venv/bin/python3"
+CASES="$SCRIPT_DIR/cases"
+REPEAT="${REPEAT:-5}"
+
+if [ ! -x "$VPY" ]; then
+    echo "ERROR: project venv not found at $VPY — run ./run.sh once to create it." >&2
+    exit 1
+fi
+
+bench() {
+    local profile="$1" size="$2"
+    local out="$CASES/${profile}_${size}"
+    local main
+    main="$("$VPY" "$SCRIPT_DIR/gen_bench_test.py" --profile "$profile" --size "$size" --out "$out")"
+    echo "===== profile=$profile size=$size ====="
+    "$VPY" "$SCRIPT_DIR/load_bench.py" --repeat "$REPEAT" --quiet "$main"
+    echo
+}
+
+if [ $# -eq 2 ]; then
+    bench "$1" "$2"
+    exit 0
+fi
+
+# Default matrix. 'deep' is kept small: the recursive loader hits Python's
+# recursion limit around ~90 nested include levels.
+bench flat     2000
+bench includes 1000
+bench repeat   1000
+bench jinja    2000
+bench deep     40
+bench mix      300

test/robustness/console serial/rsl_terminal_robustness.tum

@@ -1,69 +0,0 @@
-# Main
-################################################################################
-main:
-  name:                               Serial Terminal bug reproducer
-  version:                            0.1
-  steps:
-    - group:
-        name:                         Test preparation
-        steps:
-          - console:
-              name:             Open RSL Simulator Terminal
-              console_name:     RSL_simulator
-              steps:
-                  - open:
-                      protocol:   terminal
-                      terminal_path: $(rslsimulatorpath)
-                  - writeln: "pwd"
-                  - read_until: {expected: "$", timeout: 5}
-                  - writeln: "./RSverify $(rsTx)" # /dev/ttyMUE1
-                  - read_until: {expected: "RSL controller>", timeout: 5}
-                  - writeln: "setportconf 0 115200 none 8 1 1 255"
-                  - read_until: {expected: "RSL controller>", timeout: 5}
-                  - writeln: "send4ever 0 0"
-                  - read_until: {expected: "RSL controller>", timeout: 5}
-
-          - console:
-              name:                   Open the EUT console
-              console_name:           cons_target
-              doc:                    Initiates the console of the target in order
-                                      to be ready to capture its traces.
-              stop_on_failure:        True
-              steps:
-                - open:
-                    protocol:         serial
-                    serial_port:      $(rsRx) # /dev/ttyMUE2
-                    serial_baudrate:  115200
-
-    - loop:
-        name:                         Qualification loop
-        stop_on_failure:              False
-        steps:
-          - py_func:
-              name:                   Capture the RS serial output
-              file:                   $(test_directory)/terminal_bug_reproducer.py
-              func_name:              RetreiveData
-              param:
-                - cons_target
-
-          - sleep: {timeout: 1}
-
-# Cleanup sequence
-#-------------------------------------------------------------------------------
-    - group:
-        name:                         Cleanup
-        execute_on_stop:              True
-        steps:
-          - console:
-              name:                   Close the target console
-              console_name:           cons_target
-              execute_on_stop:        True
-              steps:
-                - close:
-
-          - console:
-              name:                   Close the RSL_simulator
-              console_name:           RSL_simulator
-              execute_on_stop:        True
-              steps:
-                - close:

test/robustness/console serial/terminal_bug_reproducer.py

@@ -1,26 +0,0 @@
-import api.testium as tm
-
-def RetreiveData(console_name):
-    print("--------------- retrieving data ---------------")
-    result = 0
-    cons   = tm.console(console_name)
-
-    if cons is None:
-        print("--------------- The console does not exist ---------------")
-    else:
-        try:
-            is_finished = False
-            while not is_finished:
-                status, d = cons.read_until('\n', timeout=0, return_data=True, mute=True)
-                if 0 == status:
-                    print("--------------- Data ---------------")
-                    print(d)
-                else:
-                    print("--------------- No data ---------------")
-                    print("Status: ", status)
-                    is_finished = True
-        except:
-            print("--------------- Error retrieving data ---------------")
-            result = -1
-
-    return result

test/robustness/console terminal/generate_char.sh

@@ -1,9 +0,0 @@
-chars='<=>| -,;:!/."()[]{}*\&#%+012345689abcdefghiklmnopqrstuvwxyzABCD'
-for j in {1..256} ;
-do
-    for i in {1..256} ; do
-        echo -n "${chars:RANDOM%${#chars}:1}"
-    done
-    echo
-    sleep 0.01
-done

test/robustness/console terminal/terminal_bug_reproducer.py

@@ -1,26 +0,0 @@
-import api.testium as tm
-
-def RetreiveData(console_name):
-    print("--------------- retrieving data ---------------")
-    result = 0
-    cons   = tm.console(console_name)
-
-    if cons is None:
-        print("--------------- The console does not exist ---------------")
-    else:
-        try:
-            is_finished = False
-            while not is_finished:
-                status, d = cons.read_until('\n', timeout=0, return_data=True, mute=True)
-                if 0 == status:
-                    print("--------------- Data ---------------")
-                    print(d)
-                else:
-                    print("--------------- No data ---------------")
-                    print("Status: ", status)
-                    is_finished = True
-        except:
-            print("--------------- Error retrieving data ---------------")
-            result = -1
-
-    return result

test/robustness/console terminal/terminal_robustness.tum

@@ -1,50 +0,0 @@
-# Main
-################################################################################
-main:
-  name:                               Terminal bug reproducer
-  version:                            0.1
-  steps:
-    - group:
-        name:                         Test preparation
-        steps:
-          - console:
-              name:                   Open the EUT console
-              console_name:           cons_target
-              doc:                    Initiates the console of the target in order
-                                      to be ready to capture its traces.
-              stop_on_failure:        True
-              steps:
-                - open:
-                    protocol: terminal
-
-    - loop:
-        name:                         Qualification loop
-        stop_on_failure:              False
-        steps:
-          - console:
-              name:                   write random data
-              console_name:           cons_target
-              steps:
-                  - writeln: bash $(test_directory)/generate_char.sh
-
-          - py_func:
-              name:                   Capture the terminal output
-              file:                   $(test_directory)/terminal_bug_reproducer.py
-              func_name:              RetreiveData
-              param:
-                - cons_target
-
-          - sleep: {timeout: 1}
-
-# Cleanup sequence
-#-------------------------------------------------------------------------------
-    - group:
-        name:                         Cleanup
-        execute_on_stop:              True
-        steps:
-          - console:
-              name:                   Close the target console
-              console_name:           cons_target
-              execute_on_stop:        True
-              steps:
-                - close:

test/validation/README.md

@@ -1,10 +1,76 @@
 # Validation
 
-This directory contains the necessary material to run the testium validation.
+This directory contains the testium validation suite. A single set of
+items (`items/`), fixtures and post-processing (`post_execution.py`) is
+re-used across every packaging channel.
 
-Here is the documentation on how to configure the validation, run it and check that the
-results are correct.
+## Running the suite
 
-# Tests
+```sh
+./test/validation/run.sh                       # default mode = source
+./test/validation/run.sh --mode wheel
+./test/validation/run.sh --mode pyinstaller
+./test/validation/run.sh --mode flatpak
+./test/validation/run.sh --mode appimage
+```
 
-TBD
+On Windows (only `source`, `wheel`, `pyinstaller` are supported):
+
+```bat
+test\validation\run.bat --mode pyinstaller
+```
+
+Pass `clean` as the **first** argument to recreate the validation venv
+from scratch (useful after a system Python upgrade):
+
+```sh
+./test/validation/run.sh clean --mode flatpak
+```
+
+Any extra arguments after the mode flag are forwarded to testium.
+
+## Modes
+
+| Mode          | What it launches                                            | Prerequisite                                                     |
+|---------------|-------------------------------------------------------------|------------------------------------------------------------------|
+| `source`      | `python3 src/testium` via the project's `run.sh`            | none — works straight out of the repo                            |
+| `wheel`       | `python -m testium` inside a dedicated wheel venv           | `./build_all.sh` produced `dist/testium-<v>-py3-none-any.whl`    |
+| `pyinstaller` | `dist/testium-<v>` (frozen binary)                          | `./build_all.sh` produced the PyInstaller binary                 |
+| `flatpak`     | `flatpak run --command=testium org.testium.Testium`         | the Flatpak bundle is installed (`flatpak install --user dist/testium-<v>.flatpak`) |
+| `appimage`    | `dist/Testium-<v>-x86_64.AppImage`                          | `./build_all.sh` produced the AppImage                           |
+
+Each mode writes its results to a distinct report file
+(`validation-<mode>.sqlite` / `validation-<mode>-<item>.xml`), so you
+can run several modes in a row without clobbering previous reports.
+
+## How `python_bin` is pinned
+
+Every test-execution subprocess (inline `<| ... |>` evaluation,
+`py_func`, `cycle`, `post_execution`, …) is routed through a dedicated
+venv at `${TMPDIR:-/tmp}/testium-validation-venv`. The venv is created
+with `--system-site-packages` so existing system packages stay visible,
+then `junit-xml` is pip-installed for `post_execution.py`.
+
+This is a **host** venv. In every mode (including Flatpak) the
+test-execution subprocesses end up running on the host — directly for
+source/wheel/pyinstaller/appimage, and via `flatpak-spawn --host` for
+Flatpak — so the same venv works across modes. The wheel mode
+additionally creates a separate `testium-wheel-venv-<v>` to hold the
+installed wheel; that one is only used to launch testium itself.
+
+## What is checked
+
+The `venv` item under `items/venv/` asserts that the validation venv is
+actually being used:
+
+* `python_bin` is set in the global dict.
+* The eval subprocess (used for `<| ... |>` expressions) has
+  `sys.executable == python_bin`, `sys.prefix == dirname(dirname(python_bin))`,
+  and `sys.prefix != sys.base_prefix` (i.e. is actually inside a venv).
+* A `py_func` subprocess passes the same three checks.
+
+These checks use `abspath`/`normpath` rather than `realpath` on
+purpose: the venv's `bin/python3` is a symlink to the host interpreter,
+so `realpath` would map both venv and non-venv interpreters to the same
+target. `sys.prefix != sys.base_prefix` is the venv-specific marker
+that distinguishes the two cases.

test/validation/items/console/test.tum

@@ -94,6 +94,17 @@
 {% endif %}
         - read_until: {expected: endOfCmd, timeout: 1, process_result: "'Hello' in r'''$(result)''' and 'PASS' in r'''$(result)''' "}
 
+{% if os == "Linux" %}
+- console:
+    name: Console runs on host (not the Flatpak sandbox)
+    doc: Regression guard for the 0.2.1 Flatpak bug (term console spawned inside the sandbox instead of on the host). /.flatpak-info exists only inside the sandbox, so the host-only marker is emitted (and matched by read_until) ONLY when the shell really runs on the host. On a broken Flatpak the marker never appears, read_until times out and the item FAILS. The marker is built at runtime ($M) so it is never present in the command line itself. Passes on every other channel.
+    console_name: term
+    key: $(test)_PASS
+    steps:
+        - writeln: 'test -e /.flatpak-info && M=SANDBOX || M=HOST; echo "console_host_check_$M"'
+        - read_until: {expected: console_host_check_HOST, timeout: 5}
+{% endif %}
+
 - console:
     name: Console closure
     execute_on_stop: true

test/validation/items/jsonrpc/test.tum

@@ -20,7 +20,7 @@
             console_name: jrpces
             key: $(test)_PASS
             steps:
-                - writeln: python3 {{include_directory}}/jrpc_echo_server.py -c {{include_directory}}/jrpces.ini
+                - writeln: '"$(python_bin)" {{include_directory}}/jrpc_echo_server.py -c {{include_directory}}/jrpces.ini'
                 - read_until: {expected: ready, timeout: 5}
 
         - console:

test/validation/items/lua_func/lua_func.lua

@@ -49,4 +49,12 @@ function module.test_delgd()
     return 0
 end
 
+function module.return_nothing()
+    -- Returns no value: ret is nil but no error.
+end
+
+function module.return_explicit_nil()
+    return nil
+end
+
 return module

test/validation/items/lua_func/test.tum

@@ -186,6 +186,18 @@
     file: $(test_path)$(psep)lua_func.lua
     func_name: test_delgd
 
+- lua_func:
+    name: function returning nothing should succeed
+    key: $(test)_PASS
+    file: $(test_path)$(psep)lua_func.lua
+    func_name: return_nothing
+
+- lua_func:
+    name: function returning explicit nil should succeed
+    key: $(test)_PASS
+    file: $(test_path)$(psep)lua_func.lua
+    func_name: return_explicit_nil
+
 - group:
     name: context_id tests
     steps:

test/validation/items/py_func/py_func.py

@@ -54,3 +54,10 @@ def test_delgd():
     tm.delgd("_py_delgd_test")
     assert tm.gd("_py_delgd_test", None) is None
     return 0
+
+def return_nothing():
+    # Falls off the end: implicit None return, no error.
+    pass
+
+def return_explicit_none():
+    return None