Document successful HDMI hardware validation for 0.2.1

docs/code-review.md

@@ -41,4 +41,24 @@ kann einen echten schnellen Rückwechsel unterdrücken. Das bleibt eine bewusste
 Einschränkung dieses hardwareabhängigen Workarounds und ist in README beschrieben.
 
 Ein realer Test von HDMI-Eingangswechsel, Ab-/Anmeldung und Boot-Verhalten wurde
-in diesem Review nicht ausgeführt. Er bleibt nach Installation erforderlich.
+im ursprünglichen Review für 0.2.0 nicht ausgeführt. Der anschließende Praxistest
+für 0.2.1 ist im folgenden Nachtrag dokumentiert.
+
+## Nachtrag: Lua-Korrektur und Praxistest für 0.2.1
+
+Die Prüfung am Desktop zeigte, dass Hyprland 0.56.2 mit Lua-Konfiguration die
+alten `dispatch dpms on`-/`dispatch focusmonitor`-Befehle ablehnt. Version 0.2.0
+brach dadurch vor dem VT-Wechsel ab. Die bisherigen Mocks hatten beliebige
+Dispatch-Aufrufe akzeptiert und diesen Fehler nicht erkannt.
+
+Version 0.2.1 erkennt den aktiven Konfigurationsanbieter über `hyprctl -j status`
+und verwendet die passenden Lua- oder hyprlang-Befehle. Die Mocks prüfen nun die
+Befehlssyntax; fehlgeschlagene Refresh-Aufrufe protokollieren Operation,
+Exitstatus und Fehlerantwort. Alle 30 Verhaltenstests sowie Bash-Syntaxprüfung
+und ShellCheck 0.11.0 waren erfolgreich.
+
+Der vollständige manuelle Recovery-Lauf am Desktop kehrte auf die grafische VT1
+zurück und meldete `Recovery completed for HDMI-A-2`. Anschließend bestätigte
+der Betreiber am 23.09.2026 den erfolgreichen physischen HDMI-Eingangswechsel.
+Testumgebung und noch nicht separat bestätigte Prüfungen sind unter
+[Hardware validation](hardware-validation.md) festgehalten.

docs/hardware-validation.md

@@ -0,0 +1,51 @@
+# Hardware validation
+
+## Confirmed on 2026-09-23
+
+Version 0.2.1 was installed and the systemd user watcher restarted on the
+following setup:
+
+| Component | Tested configuration |
+| --- | --- |
+| Desktop | Arch Linux, Hyprland 0.56.2 |
+| Configuration provider | Lua (`hyprctl -j status`) |
+| Session | Local Wayland session on seat0, graphical VT1 |
+| Display | iiyama PL3288UH, 3840 × 2160 at 60 Hz |
+| Output | `HDMI-A-2` |
+| Timing | 5 s HDMI settle, 1 s temporary VT, 2 s return settle, 30 s cooldown |
+
+The original failure was reproduced: legacy DPMS/focus commands returned Lua
+syntax errors and stopped recovery before the VT switch. Both corrected Lua
+commands returned `ok` on the running compositor.
+
+After installation, a complete manual recovery returned to graphical VT1 and
+reported:
+
+```text
+revive-monitor-fix: Recovery started for HDMI-A-2 on VT 1
+revive-monitor-fix: Using lua dispatch syntax
+revive-monitor-fix: VT refresh: 2 -> 1
+revive-monitor-fix: Recovery completed for HDMI-A-2
+```
+
+The watcher remained active. The operator then tested physical HDMI input
+switching and confirmed that recovery worked successfully.
+
+## Automated validation
+
+- All 30 behavioral tests passed, including Lua and legacy dispatch syntax,
+  refresh failures, session guards, VT return handling and installer behavior.
+- Bash syntax checks and ShellCheck 0.11.0 passed.
+- Installer archive and ZIP contents matched; ZIP integrity, Base64 round-trip
+  and release checksums were verified.
+
+## Scope and remaining checks
+
+This confirms the normal HDMI input-switch path on the setup above. It does
+not establish compatibility with every monitor or GPU.
+
+The operator had reported that the earlier unwanted tty switching was gone.
+A dedicated cold-boot/pre-login check and logout/login cycle after the 0.2.1
+update have not been separately confirmed. Rapid away/back switching inside
+the cooldown also remains a separate test; such events can be suppressed by
+design. See [the hardware acceptance procedure](troubleshooting.md#hardware-acceptance).

docs/troubleshooting.md

@@ -100,6 +100,15 @@ hook manually as documented in README.
 
 ## Hardware acceptance
 
+The operator confirmed successful physical HDMI input switching and recovery
+with version 0.2.1 on 2026-09-23. The tested setup and the scope of that result
+are recorded in [hardware validation](hardware-validation.md).
+
 After installation, check a normal input change, a rapid away/back change and a
 logout/login cycle. Before Hyprland login there must be no chvt invocation from
 this service. Automated tests use mocks and do not replace this hardware check.
+
+For a first normal input-switch test with the default timing, stay on the other
+input for about 40 seconds before returning. This allows the initial attempt
+and its 30-second cooldown to finish. Then test rapid switching separately;
+returns inside the cooldown can still be suppressed.