Document successful HDMI hardware validation for 0.2.1

CHANGELOG.md

@@ -13,6 +13,13 @@ All notable changes to this project will be documented here.
 - Add regression coverage for Lua, older Hyprland without `status`, and refresh
   failures before and after the VT switch. Document the Lua startup hook.
 
+### Validated
+
+- 30 behavioral tests, Bash syntax checks and ShellCheck 0.11.0 passed.
+- Full manual recovery completed on the desktop; the operator then confirmed
+  physical HDMI input switching and recovery on Hyprland 0.56.2 with Lua and
+  an iiyama PL3288UH on `HDMI-A-2`. See [validation details](docs/hardware-validation.md).
+
 ## 0.2.0 - 2026-09-23
 
 ### Fixed

README.md

@@ -8,6 +8,10 @@ DPMS toggle or polling timer.
 **Version 0.2.1.** The initial implementation and the review fixes are separate
 commits. See [the code review](docs/code-review.md) and [changelog](CHANGELOG.md).
 
+Physical HDMI input switching and recovery were confirmed working on
+2026-09-23 with Hyprland 0.56.2 (Lua configuration) and an iiyama PL3288UH on
+`HDMI-A-2`. See [validation results and remaining checks](docs/hardware-validation.md).
+
 ## Requirements
 
 A systemd-based Linux desktop with Hyprland, a local `seat0` Wayland session,
@@ -24,8 +28,10 @@ recovery. Hyprland must still expose the configured monitor over its IPC socket.
 
 ## Install from the package
 
-Download `hyprland-hdmi-revive-0.2.1.tar.gz` and `SHA256SUMS` from the
+Use `hyprland-hdmi-revive-0.2.1.tar.gz` and `SHA256SUMS` from a published
-[Gitea release](https://gitea.jr-it-services.de/johannes/hyprland-hdmi-revive/releases).
+[Gitea release](https://gitea.jr-it-services.de/johannes/hyprland-hdmi-revive/releases)
+or [build the bundle from source](#build-and-validate). A Git push alone does not
+publish installer bundles.
 Run as your desktop user, **without sudo**:
 
 ```bash
@@ -181,7 +187,9 @@ It creates a `.tar.gz` installer bundle, source ZIP, Base64 ZIP and `SHA256SUMS`
 be decoded on Windows with `certutil -decode <file.zip.b64> <file.zip>`.
 
 Tests mock loginctl, Hyprland IPC, udev, sudo and systemd. They never switch the
-real display. A hardware input-switch test after installation remains necessary.
+real display. Version 0.2.1 passed 30 behavioral tests and a physical input-switch
+test on the [documented setup](docs/hardware-validation.md). Test input switching
+after installation on other hardware as well.
 CI runs the shell checks and behavioral tests on a configured Gitea Actions runner.
 
 See [architecture](docs/architecture.md), [troubleshooting](docs/troubleshooting.md)

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.