Document the Frame's broken Qt WebEngine and the bundling experiment

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/PROGRESS.md

@@ -80,6 +80,18 @@ Known limitation: the bundled-Qt package does not support WebEngine in this iter
   present (relevant for Q2/Q3).
 - libmosquitto ABI check: Debian's 2.0.21 needs at most `OPENSSL_3.0.0`/`GLIBC_2.34`; the
   Frame has OpenSSL 3.2.1 and glibc 2.39. No libcjson dependency. D14 holds.
+- Phase 4 (testing on the Frame), first findings:
+  - `deploy-to-frame.sh` exited silently without a bundled package in `dist/` (fixed).
+  - The system-Qt package doesn't start: the Frame's Qt WebEngine is 6.7.0 (rest of Qt 6.8.0)
+    and built against FFmpeg 6, which the Frame lacks (STEAM-FRAME.md). DSH-1's out-of-the-box
+    variant therefore fails on the Frame; and since the app links WebEngine, the whole app
+    fails.
+  - At the user's request, experiment B: the bundled package now ships Qt WebEngine (Debian
+    6.8.2, own FFmpeg inside) with its helper process and resources: 141 MB archive, 352 MB
+    unpacked. Needs `GLIBC_2.38` and `GLIBCXX_3.4.32` from the Frame. Test pending.
+  - Other options noted: load WebEngine only at runtime so the app survives without it; a
+    native dashboard (DSH-2, Q2b). Qt WebView is no alternative (on Linux its backend is
+    WebEngine; native views are separate windows, not rendered into the texture).
 - Phase 3 of implementation iteration 1:
   - Platform: `prepare()` hook and app-specific command-line options, tested in
     `tst_surfaces` (incl. `surfaces_prepare_fail`).

docs/REQUIREMENTS.md

@@ -273,11 +273,14 @@ use Qt's private API, which requires the exact Qt version.
 | Sounds, audio from URL | NOT-4, SRV-8 | Qt Multimedia + QtNetwork | ✓ `libQt6Multimedia`, FFmpeg plugin | no |
 | HTTPS (downloads, WebSocket) | SRV-8, Q3 | Qt TLS plugin | ✓ `libqopensslbackend.so` | no |
 | Translations | NFR-4 | `QTranslator`, `lupdate`/`lrelease` | ✓ (build-time tools) | no |
-| Dashboard, HA web UI | DSH-1, DSH-2, Q2 | Qt WebEngine (Quick) | ✓ `libQt6WebEngineCore`, `libQt6WebEngineQuick`, `libQt6WebView` | no; works with our off-screen renderer and Vulkan? Needs a spike |
+| Dashboard, HA web UI | DSH-1, DSH-2, Q2 | Qt WebEngine (Quick) | **✗ present but not loadable**: 6.7.0 next to Qt 6.8.0, built against FFmpeg 6, which the Frame lacks (STEAM-FRAME.md) | yes, only bundled with all of Qt (experiment, see PROGRESS.md) |
 | Dashboard, native UI | DSH-2, Q2/Q3 | HA WebSocket API via Qt WebSockets | ✓ `libQt6WebSockets` | no |
 | Haptics, fade, apps | SRV-1/2 | OpenVR | ✓ | no |
 | Tests | NFR-8 | QtTest | ✓ (host only) | no |
 
+**Lesson:** "present" was checked by file only. Check that a library loads (`ldd … | grep "not
+found"`) and that its package version matches the rest of Qt (`pacman -Q | grep qt6-`).
+
 Also present and possibly useful later: `libQt6TextToSpeech`, Qt's `networkinformation` plugin.
 
 Open points:

docs/STEAM-FRAME.md

@@ -77,6 +77,13 @@ Checked 2026-10-05; details per requirement in [REQUIREMENTS.md](REQUIREMENTS.md
   **SteamVR does not use Qt 6:** nothing under `/opt/steamvr` links or ships `libQt6*`. So the
   system Qt is not a SteamVR dependency, which is one more reason to keep the bundled-Qt
   fallback.
+- **Qt WebEngine on the Frame can't be loaded** (checked 2026-10-05): `qt6-webengine` and
+  `qt6-webchannel` are 6.7.0 while the rest of Qt is 6.8.0, and WebEngine was built against
+  FFmpeg 6 (`libavcodec.so.60`, `libavformat.so.60`, `libavutil.so.58`); the Frame has FFmpeg
+  7.0 (`.61`/`.59`) and an old FFmpeg 4 (`.58`/`.56`). Only `qt6-webview` and `signon-ui`
+  depend on it. A program linking WebEngine fails to start ("libavcodec.so.60: cannot open
+  shared object file"). Other Qt modules are 6.8.0 (`pacman -Q | grep qt6-`). Not yet
+  checked: whether Qt Multimedia's FFmpeg plugin has the same problem.
 - **Qt add-on modules must come from the system Qt.** Shipping one fails: they use Qt's private
   API, and QtCore aborts on any version mismatch ("Cannot mix incompatible Qt library").
 - **Not present:** any MQTT library (no `libmosquitto`, no Qt MQTT). FrameAssistant ships