docs: Update lessons_learned.md with recent Wayland adaptation progress

lessons_learned.md

@@ -68,3 +68,30 @@ This document summarizes the key challenges, debugging steps, and solutions enco
 *   **Verify `wayland_poc` execution on host:** The user needs to run the `wayland_poc` executable on their host with the provided `docker run` command (or directly if copied out) and confirm if the `xdg-desktop-portal` dialog appears and a PipeWire node ID is printed. The current D-Bus connection failure needs to be resolved.
 *   **Integrate:** If successful, the next phase will involve integrating the `QDBus` based `xdg-desktop-portal` interaction with the core PipeWire stream capture logic (from `tutorial5.c`) into the main Hyperion grabber.
 *   **Persistent `session-manager.h`:** The original `session-manager.h` compilation issue remains unresolved for direct PipeWire session manager API usage. The `QDBus` approach is a workaround. If direct PipeWire session manager API interaction is ever needed, this issue would need further, likely local, investigation.
+
+## 9. Recent Debugging and Solutions
+
+*   **`SelectSources` Request Denied:**
+    *   **Problem:** After initial compilation, `wayland_poc`'s `SelectSources` call was denied by `xdg-desktop-portal`.
+    *   **Diagnosis:** The D-Bus message for `SelectSources` was missing required options (e.g., `types`, `cursor_mode`, `persist_mode`, `handle_token`) that are present in successful calls (e.g., from Firefox).
+    *   **Fix:** Modified `wayland_poc.cpp` to include these missing options in the `SelectSources` D-Bus message.
+
+*   **Persistent `QDateTime` Compilation Error:**
+    *   **Problem:** Encountered a persistent "incomplete type 'QDateTime'" error during compilation, even though `<QDateTime>` was included and its position was adjusted.
+    *   **Diagnosis:** This was a highly unusual and difficult-to-diagnose error, possibly related to subtle interactions within the Qt build system or compiler.
+    *   **Workaround:** Replaced all uses of `QDateTime::currentMSecsSinceEpoch()` with `QUuid::createUuid().toString()` for generating unique tokens, and added `#include <QUuid>`. This successfully bypassed the compilation error.
+
+*   **Docker Filesystem Isolation and `replace` Tool Misunderstanding:**
+    *   **Problem:** Changes made to `wayland_poc.cpp` using the `replace` tool were not reflected in the Docker container's build process.
+    *   **Diagnosis:** The `replace` tool modifies the host's filesystem, while the Docker container operates on its own isolated filesystem. The container was building from an outdated copy of the source file.
+    *   **Fix:** After modifying `wayland_poc.cpp` on the host, the updated file was explicitly copied into the running Docker container using `docker cp`.
+
+*   **Executable Retrieval from Docker Container:**
+    *   **Problem:** Difficulty in copying the built `wayland_poc` executable from the Docker container to the host. The build container would exit immediately, and `docker cp` failed to find the file.
+    *   **Diagnosis:** The original build container was not designed to stay running. `docker cp` requires a running container or a committed image. The initial `docker commit` did not seem to capture the build artifacts correctly.
+    *   **Fix:** Committed the original build container to a new image (`hyperion-grabber-build`). Then, a new container was launched from this image with a command (`tail -f /dev/null`) to keep it running. The executable was then successfully copied from this running container using `docker cp`.
+
+*   **New Runtime Error: "Remote peer disconnected"**
+    *   **Problem:** After successfully building and copying `wayland_poc` to the host, running it resulted in "D-Bus call to SelectSources failed: "Remote peer disconnected"".
+    *   **Diagnosis:** This indicates a problem with the D-Bus connection itself, rather than a rejection from the portal. Possible causes include incorrect D-Bus environment variables on the host, `xdg-desktop-portal` not running, or permission issues.
+    *   **Next Steps:** Investigate D-Bus environment variables (`DBUS_SESSION_BUS_ADDRESS`) and `xdg-desktop-portal` service status on the host.