From 4b03f5b5ad8f0b81deafbe85e953cde1a98c3a75 Mon Sep 17 00:00:00 2001 From: Adam Malczewski Date: Mon, 29 Jun 2026 15:24:42 +0900 Subject: docs: record GLFW 3.4 Wayland drag-drop crash + patch scar tissue Cross-ref from study-player.md drag-drop section to environment.md so the next agent touching drag-drop finds the real root cause (GLFW/Wayland, not the Ruby CheckFileDrop code). --- .agents/knowledge/environment.md | 26 ++++++++++++++++++++++++++ .agents/knowledge/study-player.md | 7 +++++++ 2 files changed, 33 insertions(+) diff --git a/.agents/knowledge/environment.md b/.agents/knowledge/environment.md index f130a40..38ae92d 100644 --- a/.agents/knowledge/environment.md +++ b/.agents/knowledge/environment.md @@ -20,5 +20,31 @@ Expect harmless Mesa/EGL/zink warnings on stderr in this environment (`libEGL warning: ... zink ...`, `Wayland: The platform does not provide the window position`); they are not errors. +## Wayland drag-and-drop crashes on GLFW 3.4 (patched) +raylib 6.0 vendors **GLFW 3.4** (release). Its Wayland `wl_data_offer_listener` +(`vendor/raylib/src/external/glfw/src/wl_window.c`) only sets the `offer` +(opcode 0) handler; `source_actions` (opcode 1) and `action` (opcode 2) are +NULL (`wl_data_offer` is v3; those events were added in v3). Modern compositors +(labwc, GNOME, KDE) emit source_actions/action *during a drag*, and +libwayland-client then `wl_abort("listener function for opcode N of +wl_data_offer is NULL")` — **the app crashes the moment a file is dragged over +the window**, before any drop registers (glfw/glfw#2835, #2562). This is why +drag-and-drop was "unreliable" in the rewrite but reliable in the original +`../source` app, which uses the X11/Xdnd backend (`-D_GLFW_X11`) — a separate +code path with none of these bugs. + +Fix: `patches/glfw-wayland-dnd-crash.patch` backports the upstream GLFW-master +fix (no-op source_actions/action handlers + two NULL-deref guards in the +data-device path). `build.zig` applies it **idempotently** before `make` +(marker = `dataOfferHandleAction` in the file; when newly applied it deletes the +stale `libraylib.a` so `make` actually rebuilds). The vendored file is +gitignored, so the patch file + the build.zig step ARE the committed fix — a +fresh checkout reproduces it. **Drop the patch once raylib vendors a GLFW +release containing the upstream fix.** + +Do NOT "fix" this by re-enabling X11 (`GLFW_LINUX_ENABLE_X11=TRUE`): on a real +Wayland session GLFW 3.4 still picks Wayland (so it wouldn't help), and forcing +X11 reintroduces the WSLg GLX segfault above. + ## Toolchain versions (pinned) raylib 5.5, mruby 3.3.0, RmlUi 6.1, flecs v4.1.1, Zig 0.16.0, emcc 6.0.0 (emsdk). diff --git a/.agents/knowledge/study-player.md b/.agents/knowledge/study-player.md index a800a8c..e0d1831 100644 --- a/.agents/knowledge/study-player.md +++ b/.agents/knowledge/study-player.md @@ -94,6 +94,13 @@ hand-written method `path_at(index)` was added to drag-and-drop. This method is registered on `Rl::FilePathList` after the generated registrar runs. +The Ruby `CheckFileDrop` system (`game/study_player/study_player.rb`) is correct +and identical in pattern to the original C app. If drag-and-drop is unreliable, +the cause is NOT the Ruby — it is the GLFW/Wayland backend: see +`.agents/knowledge/environment.md` § "Wayland drag-and-drop crashes on GLFW 3.4" +(the `wl_data_offer` NULL-listener crash + the `patches/glfw-wayland-dnd-crash.patch` +fix). The X11 `../source` app never hits it. + ## Non-blocking seek (skip_auto_update) After `Rl.seek_music_stream`, raylib's miniaudio stream may briefly report the old position. The `skip_auto_update` counter (set to 3 frames = ~50ms at 60fps) -- cgit v1.2.3