Qt viewer: verify packaged artifacts in CI; descope Qt Comparator (#63)

Add a packaged-artifact smoke check to the Qt viewer CI and release
workflows: after deploying the bundle (windeployqt / macdeployqt) or
building the Linux AppImage, run that artifact headlessly via --selftest
over a PNG and a raw fixture so it must open a common image and a raw
frame and exit 0. This exercises the artifact's own bundled Qt
libs/plugins and libheif runtime, not the build-tree binary the existing
offscreen smoke test used, and is the automated stand-in for #63's manual
clean-desktop / packaged-app verification (Linux runs under xvfb; the
Windows/macOS step caches the process handle so the exit code is
readable). Add a tiny 16x16 PNG fixture for the image-plugin check.

Record the maintainer decision that the Qt Comparator (ComparatorQt) is
out of scope: the cross-platform effort targets Viewer parity only, the
MFC Comparator stays the comparison tool, and PORTING_ROADMAP Phase 5 is
descoped. With Comparator excluded and packaged verification automated,
the Qt Viewer parity tracked in #63 is complete.

Author: chammoru

.github/workflows/release-qt-viewer.yml

@@ -165,6 +165,46 @@ jobs:
 
           chmod +x "dist/${{ matrix.asset_name }}.AppImage"
 
+      # Verify the released artifact (its own bundled Qt libs/plugins and libheif
+      # runtime) before publishing: the deployed bundle / AppImage must open a
+      # common image and a raw frame headlessly and exit 0. Automated stand-in
+      # for the manual clean-desktop check (#63).
+      - name: Verify packaged AppImage (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          sudo apt-get install -y xvfb
+          appimage="dist/${{ matrix.asset_name }}.AppImage"
+          export APPIMAGE_EXTRACT_AND_RUN=1
+          xvfb-run -a "${appimage}" --selftest Tests/fixtures/sample_16x16.png
+          xvfb-run -a "${appimage}" --selftest --raw --width 16 --height 16 \
+            --format yuv420 Tests/fixtures/raw/gradient_16x16.yuv420
+
+      - name: Verify packaged app (Windows/macOS)
+        if: runner.os != 'Linux'
+        shell: pwsh
+        run: |
+          $pkg = "package/${{ matrix.asset_name }}"
+          if ($env:RUNNER_OS -eq "Windows") {
+            $bin = Join-Path $pkg "q1view_viewer_qt.exe"
+          } else {
+            $bin = Join-Path $pkg "q1view_viewer_qt.app/Contents/MacOS/q1view_viewer_qt"
+          }
+          if (-not (Test-Path $bin)) { throw "packaged binary not found: $bin" }
+          function Invoke-SelfTest($AppArgs) {
+            $p = Start-Process -FilePath $bin -ArgumentList $AppArgs -PassThru -NoNewWindow
+            $null = $p.Handle   # cache handle so ExitCode is readable after exit
+            if (-not $p.WaitForExit(60000)) {
+              $p.Kill(); throw "packaged --selftest timed out: $($AppArgs -join ' ')"
+            }
+            if ($p.ExitCode -ne 0) {
+              throw "packaged --selftest failed ($($p.ExitCode)): $($AppArgs -join ' ')"
+            }
+          }
+          Invoke-SelfTest @("--selftest", "Tests/fixtures/sample_16x16.png")
+          Invoke-SelfTest @("--selftest", "--raw", "--width", "16", "--height", "16", "--format", "yuv420", "Tests/fixtures/raw/gradient_16x16.yuv420")
+
       - name: Upload release asset artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/viewer-qt.yml

@@ -163,6 +163,48 @@ jobs:
 
           chmod +x "${package}/q1view-viewer-qt-linux-x86_64.AppImage"
 
+      # Verify the *packaged* artifact (its own bundled Qt libs/plugins and the
+      # libheif runtime), not the build-tree binary the smoke test above used.
+      # This is the automated stand-in for the manual clean-desktop check (#63):
+      # the deployed bundle must open a common image and a raw frame and exit 0.
+      - name: Verify packaged AppImage (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          sudo apt-get install -y xvfb
+          appimage="package/q1view-viewer-qt-${RUNNER_OS}/q1view-viewer-qt-linux-x86_64.AppImage"
+          # xvfb gives the bundled xcb plugin a display; extract-and-run avoids
+          # needing FUSE on the runner.
+          export APPIMAGE_EXTRACT_AND_RUN=1
+          xvfb-run -a "${appimage}" --selftest Tests/fixtures/sample_16x16.png
+          xvfb-run -a "${appimage}" --selftest --raw --width 16 --height 16 \
+            --format yuv420 Tests/fixtures/raw/gradient_16x16.yuv420
+
+      - name: Verify packaged app (Windows/macOS)
+        if: runner.os != 'Linux'
+        shell: pwsh
+        run: |
+          $pkg = "package/q1view-viewer-qt-${{ runner.os }}"
+          if ($env:RUNNER_OS -eq "Windows") {
+            $bin = Join-Path $pkg "q1view_viewer_qt.exe"
+          } else {
+            $bin = Join-Path $pkg "q1view_viewer_qt.app/Contents/MacOS/q1view_viewer_qt"
+          }
+          if (-not (Test-Path $bin)) { throw "packaged binary not found: $bin" }
+          function Invoke-SelfTest($AppArgs) {
+            $p = Start-Process -FilePath $bin -ArgumentList $AppArgs -PassThru -NoNewWindow
+            $null = $p.Handle   # cache handle so ExitCode is readable after exit
+            if (-not $p.WaitForExit(60000)) {
+              $p.Kill(); throw "packaged --selftest timed out: $($AppArgs -join ' ')"
+            }
+            if ($p.ExitCode -ne 0) {
+              throw "packaged --selftest failed ($($p.ExitCode)): $($AppArgs -join ' ')"
+            }
+          }
+          Invoke-SelfTest @("--selftest", "Tests/fixtures/sample_16x16.png")
+          Invoke-SelfTest @("--selftest", "--raw", "--width", "16", "--height", "16", "--format", "yuv420", "Tests/fixtures/raw/gradient_16x16.yuv420")
+
       - name: Upload package
         uses: actions/upload-artifact@v4
         with:

Tests/fixtures/sample_16x16.png

@@ -591,6 +591,12 @@ viewer entry once parity is reached.
 
 ## Phase 5 — ComparatorQt
 
+> **Descoped (maintainer decision, 2026-06-17).** ComparatorQt will **not** be
+> implemented. The cross-platform effort targets Viewer parity only; the Windows
+> MFC Comparator stays the comparison tool. The design below is retained for
+> reference in case this decision is ever revisited, but it is not planned work,
+> and #63 is considered complete without it.
+
 **Why last:** ComparatorQt is the largest single chunk of new UI work and
 it benefits from a battle-tested ViewerQt plus the abstractions laid down
 in Phases 0–2 (decoders, file scanner, watcher, video, audio). Doing it

docs/PORTING_ROADMAP.md

@@ -11,9 +11,10 @@ This file captures the current cross-platform porting state so future Codex sess
 - The short-lived `cross-platform-core` branch has been **merged and deleted** —
   it no longer exists. All further work lands directly on `master`.
 - Qt viewer feature-parity work is tracked in #63. Video playback, file-change
-  auto-refresh, and multi-window Sync Input have landed; remaining items are the
-  Comparator features, clean-desktop AppImage verification, automated Qt smoke
-  checks, and raw fixtures.
+  auto-refresh, and multi-window Sync Input have landed. The Qt **Comparator**
+  is out of scope (see "Out of scope" below), so the only remaining #63 item —
+  verifying the *packaged* artifacts on each OS — is now automated in CI: every
+  Qt build runs the deployed bundle / AppImage headlessly via `--selftest`.
 - The Qt viewer stays additive: it builds behind the `Q1VIEW_BUILD_QT_VIEWER`
   CMake option (default OFF) and only *links* the shared core, so the MFC
   Windows product (`Viewer.sln` / `Comparator.sln`) is unaffected.
@@ -131,9 +132,15 @@ Current capabilities:
     Playback sync covers raw-sequence play/stop and video play/pause; the video
     clock/position itself is not mirrored (each window plays on its own clock)
 
-It does not yet implement:
+Out of scope (maintainer decision, 2026-06-17):
 
-- Comparator features.
+- **Comparator / ComparatorQt features are not being ported to Qt.** The
+  cross-platform effort targets *Viewer* parity only; the Windows MFC
+  Comparator remains the comparison tool. Phase 5 of
+  [PORTING_ROADMAP.md](PORTING_ROADMAP.md) is therefore descoped, and #63's
+  remaining Viewer work (packaged-artifact verification) is now automated in
+  CI rather than done by hand. With Comparator excluded, the Qt Viewer is at
+  feature parity with the MFC Viewer.
 
 Successful Qt viewer CI runs:
 
@@ -206,8 +213,12 @@ Local build note: GitHub Actions remains the cross-platform source of truth (Lin
 
 ## Next Suggested Steps
 
-1. Track and land the remaining Qt viewer parity work via #63 (Comparator, Qt
-   smoke checks, and raw fixtures).
+1. Qt viewer parity (#63) is complete for the in-scope feature set; the Qt
+   Comparator is intentionally not ported (the MFC Comparator remains the
+   comparison tool). Raw fixtures and automated Qt smoke checks have landed, and
+   the packaged artifacts are now verified headlessly in CI (`--selftest` against
+   the deployed bundle / AppImage), replacing the earlier manual clean-desktop
+   check.
 2. Improve packaging for `q1view_viewer_qt`:
    - Windows packaging uses `windeployqt`.
    - macOS packaging uses `macdeployqt`.