docs: translate CLAUDE.md to English

Per the committed=English rule.

.gitea/workflows/update-pkgver.yaml

@@ -1,22 +1,22 @@
-# ABOUTME: Updates pkgver in moonarch-pkgbuilds after a push to main.
-# ABOUTME: Ensures paru detects new versions of this package.
+# ABOUTME: Updates pkgver in moonarch-pkgbuilds when a new moonlock tag is pushed.
+# ABOUTME: Reads the latest version tag and bumps the PKGBUILD + .SRCINFO.
 
 name: Update PKGBUILD version
 
 on:
   push:
-    branches:
-      - main
+    tags:
+      - 'v*'
 
 jobs:
   update-pkgver:
     runs-on: moonarch
     steps:
-      - name: Checkout source repo
+      - name: Determine pkgver from latest tag
         run: |
           git clone --bare http://gitea:3000/nevaforget/moonlock.git source.git
           cd source.git
-          PKGVER=$(git describe --long --tags | sed 's/^v//;s/-/.r/;s/-/./')
+          PKGVER=$(git describe --tags --abbrev=0 | sed 's/^v//')
           echo "New pkgver: $PKGVER"
           echo "$PKGVER" > /tmp/pkgver
 
@@ -26,18 +26,18 @@ jobs:
           git clone http://gitea:3000/nevaforget/moonarch-pkgbuilds.git pkgbuilds
           cd pkgbuilds
 
-          OLD_VER=$(grep '^pkgver=' moonlock-git/PKGBUILD | cut -d= -f2)
+          OLD_VER=$(grep '^pkgver=' moonlock/PKGBUILD | cut -d= -f2)
           if [ "$OLD_VER" = "$PKGVER" ]; then
             echo "pkgver already up to date ($PKGVER)"
             exit 0
           fi
 
-          sed -i "s/^pkgver=.*/pkgver=$PKGVER/" moonlock-git/PKGBUILD
-          sed -i "s/^\tpkgver = .*/\tpkgver = $PKGVER/" moonlock-git/.SRCINFO
+          sed -i "s/^pkgver=.*/pkgver=$PKGVER/" moonlock/PKGBUILD
+          sed -i "s/^\tpkgver = .*/\tpkgver = $PKGVER/" moonlock/.SRCINFO
           echo "Updated pkgver: $OLD_VER → $PKGVER"
 
           git config user.name "pkgver-bot"
           git config user.email "gitea@moonarch.de"
-          git add moonlock-git/PKGBUILD moonlock-git/.SRCINFO
-          git commit -m "chore(moonlock-git): bump pkgver to $PKGVER"
+          git add moonlock/PKGBUILD moonlock/.SRCINFO
+          git commit -m "chore(moonlock): bump pkgver to $PKGVER"
           git -c http.extraHeader="Authorization: token ${{ secrets.PKGBUILD_TOKEN }}" push

CLAUDE.md

@@ -1,63 +1,63 @@
 # Moonlock
 
-## Projekt
+## Project
 
-Moonlock ist ein sicherer Wayland-Lockscreen, gebaut mit Rust + gtk4-rs + ext-session-lock-v1.
-Teil des Moonarch-Ökosystems.
+Moonlock is a secure Wayland lockscreen, built with Rust + gtk4-rs + ext-session-lock-v1.
+Part of the Moonarch ecosystem.
 
-## Tech-Stack
+## Tech Stack
 
-- Rust (Edition 2024), gtk4-rs 0.11, glib 0.22
-- gtk4-session-lock 0.4 für ext-session-lock-v1 Protokoll
-- PAM-Authentifizierung via Raw FFI (libc, libpam.so)
-- fprintd D-Bus Integration (gio::DBusProxy) für Fingerabdruck-Unlock
-- zeroize für sicheres Passwort-Wiping
-- `cargo test` für Unit-Tests
+- Rust (edition 2024), gtk4-rs 0.11, glib 0.22
+- gtk4-session-lock 0.4 for the ext-session-lock-v1 protocol
+- PAM authentication via raw FFI (libc, libpam.so)
+- fprintd D-Bus integration (gio::DBusProxy) for fingerprint unlock
+- zeroize for secure password wiping
+- `cargo test` for unit tests
 
-## Projektstruktur
+## Project Structure
 
-- `src/` — Rust-Quellcode (main.rs, lockscreen.rs, auth.rs, fingerprint.rs, config.rs, i18n.rs, users.rs, power.rs)
-- `resources/` — GResource-Assets (style.css, default-avatar.svg)
-- `config/` — PAM-Konfiguration und Beispiel-Config
+- `src/` — Rust source code (main.rs, lockscreen.rs, auth.rs, fingerprint.rs, config.rs, i18n.rs, users.rs, power.rs)
+- `resources/` — GResource assets (style.css, default-avatar.svg)
+- `config/` — PAM configuration and example config
 
-## Kommandos
+## Commands
 
 ```bash
-# Tests ausführen
+# Run tests
 cargo test
 
-# Release-Build
+# Release build
 cargo build --release
 
-# Lockscreen starten (zum Testen)
+# Start the lockscreen (for testing)
 LD_PRELOAD=/usr/lib/libgtk4-layer-shell.so ./target/release/moonlock
 ```
 
-## Architektur
+## Architecture
 
-- `auth.rs` — PAM-Authentifizierung via Raw FFI (unsafe extern "C" conv callback, msg_style-aware, Zeroizing<CString>)
-- `fingerprint.rs` — fprintd D-Bus Listener, async init/claim/verify via gio futures, sender-validated signal handler, cleanup_dbus() für sauberen D-Bus-Lifecycle, running_flag für Race-Safety in async restarts, on_exhausted callback after MAX_FP_ATTEMPTS, resume_async() für Neustart nach transientem Fehler (mit failed_attempts-Reset und Signal-Handler-Cleanup)
-- `users.rs` — Aktuellen User via nix getuid, Avatar-Loading mit Symlink-Rejection
-- `power.rs` — Reboot/Shutdown via /usr/bin/systemctl
-- `i18n.rs` — Locale-Erkennung (OnceLock-cached) und String-Tabellen (DE/EN), faillock_warning mit konfigurierbarem max_attempts
-- `config.rs` — TOML-Config (background_path, background_blur clamped [0,200], fingerprint_enabled als Option<bool>) + Wallpaper-Fallback + Symlink-Rejection via symlink_metadata + Parse-Error-Logging
-- `lockscreen.rs` — GTK4 UI via LockscreenHandles, PAM-Auth via gio::spawn_blocking mit 30s Timeout und Generation Counter, FP-Success ruft unlock_callback direkt (PAM-Stack ohne account-Modul, Lockout via auth-Pfad und MAX_FP_ATTEMPTS), Zeroizing<String> für Passwort, Power-Confirm, GPU-Blur via GskBlurNode (Downscale auf max 1920px), Blur/Avatar-Cache für Multi-Monitor
-- `main.rs` — Entry Point, Panic-Hook (vor Logging), Root-Check, ext-session-lock-v1 (Pflicht in Release), Monitor-Hotplug via `connect_monitor`-Signal (v1_2) + Pruning toter Fenster bei Monitor-Removal (`display.monitors()` items_changed → `remove_window`) gegen Resume-Unlock-SIGSEGV, shared Blur/Avatar-Caches in Rc, systemd-Journal-Logging, Debug-Level per `MOONLOCK_DEBUG` Env-Var, async fprintd-Init nach window.present()
+- `auth.rs` — PAM authentication via raw FFI (unsafe extern "C" conv callback, msg_style-aware, Zeroizing<CString>)
+- `fingerprint.rs` — fprintd D-Bus listener, async init/claim/verify via gio futures, sender-validated signal handler, cleanup_dbus() for a clean D-Bus lifecycle, running_flag for race safety in async restarts, on_exhausted callback after MAX_FP_ATTEMPTS, resume_async() for restart after a transient error (with failed_attempts reset and signal handler cleanup)
+- `users.rs` — current user via nix getuid, avatar loading with symlink rejection
+- `power.rs` — reboot/shutdown via /usr/bin/systemctl
+- `i18n.rs` — locale detection (OnceLock-cached) and string tables (DE/EN), faillock_warning with configurable max_attempts
+- `config.rs` — TOML config (background_path, background_blur clamped [0,200], fingerprint_enabled as Option<bool>) + wallpaper fallback + symlink rejection via symlink_metadata + parse-error logging
+- `lockscreen.rs` — GTK4 UI via LockscreenHandles, PAM auth via gio::spawn_blocking with a 30s timeout and generation counter, FP success calls unlock_callback directly (PAM stack without account module, lockout via the auth path and MAX_FP_ATTEMPTS), Zeroizing<String> for the password, power confirm, GPU blur via GskBlurNode (downscale to max 1920px), blur/avatar cache for multi-monitor
+- `main.rs` — entry point, panic hook (before logging), root check, ext-session-lock-v1 (mandatory in release), monitor hotplug via the `connect_monitor` signal (v1_2), unlock via `unlock()` + `connect_unlocked`→`app.quit()` (the lib destroys the lock windows itself when the lock ends — no own destroy/quit, otherwise double-destroy SIGSEGV), shared blur/avatar caches in Rc, systemd journal logging, debug level via the `MOONLOCK_DEBUG` env var, async fprintd init after window.present()
 
-## Sicherheit
+## Security
 
-- ext-session-lock-v1 garantiert: Compositor sperrt alle Surfaces bei lock()
-- Release-Build: Ohne ext-session-lock-v1 wird `exit(1)` aufgerufen — kein Fenster-Fallback
-- Panic-Hook: Bei Crash wird geloggt, aber NIEMALS unlock() aufgerufen — Screen bleibt schwarz. Hook wird vor Logging installiert.
-- PAM-Callback: msg_style-aware (Passwort nur bei PAM_PROMPT_ECHO_OFF), strdup-OOM-sicher, num_msg-Guard gegen negative Werte
-- fprintd: D-Bus Signal-Sender wird gegen fprintd's unique bus name validiert (Anti-Spoofing)
-- Passwort: Zeroizing<String> ab GTK-Entry-Extraktion, Zeroizing<CString> im PAM-FFI-Layer (bekannte Einschränkung: GLib-GString und strdup-Kopie in PAM werden nicht gezeroized — inhärente GTK/libc-Limitierung)
-- Fingerprint-Unlock: ruft unlock_callback direkt nach verify-match (kein zusätzlicher PAM-acct-Check, weil PAM-Stack nur `auth include login` enthält — wie swaylock); FP-Lockout ist über MAX_FP_ATTEMPTS in fingerprint.rs umgesetzt
-- PAM-Stack: nur `auth include login` (Standard-Pattern wie swaylock/gtklock); kein `account`/`session`-Stack, weil Lockscreen keinen Session-Lifecycle managed und `pam_unix(account)` setuid root benötigt
-- Wallpaper wird vor lock() geladen — connect_monitor feuert während lock() und braucht die Textur; lokales JPEG-Laden ist schnell genug
-- PAM-Timeout: 30s Timeout verhindert permanentes Aussperren bei hängenden PAM-Modulen, Generation Counter verhindert Interferenz paralleler Auth-Versuche
-- Root-Check: Exit mit Fehler wenn als root gestartet
-- Faillock: UI-Warnung nach 3 Fehlversuchen, aber PAM entscheidet über Lockout (Entry bleibt aktiv)
-- Kein Schließen per Escape/Alt-F4 — nur durch erfolgreiche PAM-Auth oder Fingerprint
-- Peek-Icon am Passwortfeld aktiv (UX-Entscheidung, konsistent mit moongreet)
-- GResource-Bundle: CSS/Assets in der Binary kompiliert
+- ext-session-lock-v1 guarantees: the compositor locks all surfaces on lock()
+- Release build: without ext-session-lock-v1, `exit(1)` is called — no window fallback
+- Panic hook: on a crash it logs, but NEVER calls unlock() — the screen stays black. The hook is installed before logging.
+- PAM callback: msg_style-aware (password only on PAM_PROMPT_ECHO_OFF), strdup-OOM-safe, num_msg guard against negative values
+- fprintd: the D-Bus signal sender is validated against fprintd's unique bus name (anti-spoofing)
+- Password: Zeroizing<String> from GTK entry extraction, Zeroizing<CString> in the PAM FFI layer (known limitation: the GLib GString and the strdup copy in PAM are not zeroized — an inherent GTK/libc limitation)
+- Fingerprint unlock: calls unlock_callback directly after a verify match (no additional PAM acct check, because the PAM stack contains only `auth include login` — like swaylock); FP lockout is implemented via MAX_FP_ATTEMPTS in fingerprint.rs
+- PAM stack: only `auth include login` (standard pattern like swaylock/gtklock); no `account`/`session` stack, because the lockscreen does not manage a session lifecycle and `pam_unix(account)` requires setuid root
+- The wallpaper is loaded before lock() — connect_monitor fires during lock() and needs the texture; local JPEG loading is fast enough
+- PAM timeout: a 30s timeout prevents permanent lockout when PAM modules hang, the generation counter prevents interference from parallel auth attempts
+- Root check: exits with an error if started as root
+- Faillock: UI warning after 3 failed attempts, but PAM decides on lockout (the entry stays active)
+- No closing via Escape/Alt-F4 — only via successful PAM auth or fingerprint
+- Peek icon on the password field active (UX decision, consistent with moongreet)
+- GResource bundle: CSS/assets compiled into the binary

Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "moonlock"
-version = "0.6.15"
+version = "0.6.17"
 dependencies = [
  "gdk-pixbuf",
  "gdk4",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "moonlock"
-version = "0.6.15"
+version = "0.6.17"
 edition = "2024"
 description = "A secure Wayland lockscreen with GTK4, PAM and fingerprint support"
 license = "MIT"

DECISIONS.md

@@ -2,6 +2,13 @@
 
 Architectural and design decisions for Moonlock, in reverse chronological order.
 
+## 2026-06-02 – Real fix for the unlock SIGSEGV: quit in ::unlocked, never destroy windows ourselves (v0.6.17)
+
+- **Who**: ClaudeCode, Dom
+- **Why**: The v0.6.15 "stale per-monitor window" theory was a **misdiagnosis**. A clean manual `target/release/moonlock` lock→unlock (single monitor, no suspend, no monitor removal) still crashed, preceded by `Gdk-CRITICAL: gdk_surface_get_display: assertion 'GDK_IS_SURFACE (surface)' failed`. The v0.6.16 backtrace's top app frame is the `unlock_callback` closure, which ran `lock.unlock(); app.quit();`. Per the gtk4-session-lock header (`assign_window_to_monitor`: "the window will be unmapped and `gtk_window_destroy()` called on it when the current lock ends") the **library destroys the lock windows itself** on unlock. `app.quit()` then destroyed the same windows again — surface already gone → SIGSEGV. A double-destroy in the teardown sequence, entirely independent of monitors.
+- **Tradeoffs**: Reverted the v0.6.15/v0.6.16 monitor-pruning + `LockscreenHandles.monitor` field: it targeted the wrong cause, never fired in testing, and manually called `app.remove_window()` on library-managed lock windows — exactly what the upstream example warns against ("does NOT manually destroy or close the lock windows"). Monitor-removal-during-lock is left entirely to the library (which already auto-unmaps+dereferences such windows). Three attempts total: idle_add deferral (wrong: reentrancy theory), monitor-pruning (wrong: misdiagnosis), and this one — verified against both the C header and the upstream `examples/simple.rs`.
+- **How**: `unlock_callback` now calls only `lock.unlock()`. A new `lock.connect_unlocked(|_| app.quit())` quits the app only after the library finishes its teardown and fires `::unlocked`. Mirrors the canonical gtk4-session-lock usage exactly.
+
 ## 2026-06-02 – Prune per-monitor windows on monitor removal to fix resume-unlock SIGSEGV (v0.6.15)
 
 - **Who**: ClaudeCode, Dom

src/lockscreen.rs

@@ -27,9 +27,6 @@ pub struct LockscreenHandles {
     pub password_entry: gtk::PasswordEntry,
     pub unlock_callback: Rc<dyn Fn()>,
     pub username: String,
-    /// The monitor this window was assigned to (session-lock path only).
-    /// Used to prune the window when its monitor is removed on suspend/resume.
-    pub monitor: Option<gdk::Monitor>,
     state: Rc<RefCell<LockscreenState>>,
 }
 
@@ -73,7 +70,6 @@ pub fn create_lockscreen_window(
                 password_entry: gtk::PasswordEntry::new(),
                 unlock_callback,
                 username: String::new(),
-                monitor: None,
                 state: Rc::new(RefCell::new(LockscreenState {
                     failed_attempts: 0,
                     fp_listener_rc: None,
@@ -364,7 +360,6 @@ pub fn create_lockscreen_window(
         password_entry: password_entry.clone(),
         unlock_callback,
         username: user.username,
-        monitor: None,
         state: state.clone(),
     }
 }

src/main.rs

@@ -59,7 +59,7 @@ fn activate(app: &gtk::Application) {
 
 fn activate_with_session_lock(
     app: &gtk::Application,
-    display: &gdk::Display,
+    _display: &gdk::Display,
     config: &config::Config,
 ) {
     let lock = gtk4_session_lock::Instance::new();
@@ -72,41 +72,22 @@ fn activate_with_session_lock(
             .and_then(|path| lockscreen::load_background_texture(&path)),
     );
 
-    // Shared handles list — populated by connect_monitor, read by fingerprint init.
-    // Declared before unlock_callback so the callback can inspect window state on unlock.
-    let all_handles: Rc<RefCell<Vec<lockscreen::LockscreenHandles>>> =
-        Rc::new(RefCell::new(Vec::new()));
-
     // Shared unlock callback — unlocks session and quits.
     // Guard prevents double-unlock if PAM and fingerprint succeed simultaneously.
     let lock_clone = lock.clone();
-    let app_clone = app.clone();
     let already_unlocked = Rc::new(Cell::new(false));
     let au = already_unlocked.clone();
-    let all_handles_dbg = all_handles.clone();
+    // unlock() only. The library destroys the lock windows itself when the lock ends,
+    // and the ::unlocked handler quits the app afterwards. Calling app.quit() here too
+    // double-destroyed the windows (their surface was already gone) and segfaulted
+    // gtk_window_destroy. Matches the upstream gtk4-session-lock example.
     let unlock_callback: Rc<dyn Fn()> = Rc::new(move || {
         if au.get() {
             log::debug!("Unlock already triggered, ignoring duplicate");
             return;
         }
         au.set(true);
-        // DIAGNOSTIC: log lock-window state at unlock to confirm whether a stale
-        // window (unrealized / dead surface) remains in all_handles after a monitor
-        // power-off/resume. Remove once the resume-unlock crash is fixed.
-        {
-            let handles = all_handles_dbg.borrow();
-            log::info!("UNLOCK: {} window(s) in all_handles", handles.len());
-            for (i, h) in handles.iter().enumerate() {
-                log::info!(
-                    "UNLOCK:   window[{i}] realized={} mapped={} visible={}",
-                    h.window.is_realized(),
-                    h.window.is_mapped(),
-                    h.window.is_visible(),
-                );
-            }
-        }
         lock_clone.unlock();
-        app_clone.quit();
     });
 
     // Shared caches for multi-monitor — first monitor renders, rest reuse
@@ -116,6 +97,10 @@ fn activate_with_session_lock(
     // Shared config for use in the monitor signal handler
     let config = Rc::new(config.clone());
 
+    // Shared handles list — populated by connect_monitor, read by fingerprint init
+    let all_handles: Rc<RefCell<Vec<lockscreen::LockscreenHandles>>> =
+        Rc::new(RefCell::new(Vec::new()));
+
     // Shared fingerprint listener — None until async init completes.
     // The monitor handler checks this to wire up FP labels on hotplugged monitors.
     let shared_fp: Rc<RefCell<Option<Rc<RefCell<FingerprintListener>>>>> =
@@ -144,7 +129,7 @@ fn activate_with_session_lock(
         shared_fp,
         move |_instance, monitor| {
             log::debug!("Monitor signal: creating lockscreen window");
-            let mut handles = lockscreen::create_lockscreen_window(
+            let handles = lockscreen::create_lockscreen_window(
                 bg_texture.as_ref().as_ref(),
                 &config,
                 &app,
@@ -154,7 +139,6 @@ fn activate_with_session_lock(
             );
             lock_for_signal.assign_window_to_monitor(&handles.window, monitor);
             handles.window.present();
-            handles.monitor = Some(monitor.clone());
 
             // If fingerprint is already initialized, wire up the label
             if let Some(ref fp_rc) = *shared_fp.borrow() {
@@ -165,29 +149,14 @@ fn activate_with_session_lock(
         }
     ));
 
-    // connect_monitor only ADDS — it never tells us when a monitor powers off on
-    // suspend. gtk4-session-lock then unmaps and drops its own ref to that monitor's
-    // window, but the GtkApplication and all_handles still hold refs, so the orphaned
-    // window survives until unlock — where gtk_window_destroy dereferences its now-NULL
-    // monitor association and segfaults. Watch the display's monitor list and prune any
-    // window whose monitor is no longer valid, releasing our refs (the lib doc points to
-    // "GTK APIs" for exactly this). We release refs, not destroy — the lib already
-    // unmapped+dereffed the window.
-    display.monitors().connect_items_changed(glib::clone!(
+    // Quit only after the library finishes unlocking (::unlocked fires after the lock
+    // ends). gtk4-session-lock destroys the lock windows itself at lock-end; quitting
+    // earlier — or destroying windows ourselves — races that teardown and segfaults
+    // gtk_window_destroy on an already-gone surface. Mirrors the upstream example.
+    lock.connect_unlocked(glib::clone!(
         #[weak]
         app,
-        #[strong]
-        all_handles,
-        move |_, _, _, _| {
-            all_handles.borrow_mut().retain(|h| {
-                let alive = h.monitor.as_ref().is_none_or(gdk::Monitor::is_valid);
-                if !alive {
-                    log::info!("Monitor removed — pruning its lockscreen window");
-                    app.remove_window(&h.window);
-                }
-                alive
-            });
-        }
+        move |_| app.quit()
     ));
 
     lock.lock();