## System details

Omarchy 4.0.4-1 (quattro branch)

## What's wrong?

Every time the session locks (idle timeout or manual lock), there is a brief black flash — the `WlSessionLockSurface` appears with the solid `Color.background` color before the wallpaper image loads and the blur renders. The delay is a single frame or two, but noticeable.

This is **not** related to suspend/resume. It reproduces on every fresh lock.

**Steps to reproduce:**
1. Have the stock `omarchy.lock` plugin enabled (no third-party lock plugins)
2. Lock the session (`omarchy system lock` or idle timeout)
3. Observe: a brief black flash before the blurred wallpaper appears

**Root cause:**

In `shell/plugins/lock/Service.qml`, `beginLock()` defers `refreshBackground()` via `Qt.callLater` while `queueSessionLock()` starts its timers immediately:

```qml
function beginLock() {
  // ...
  lockRequested = true       // root.locked = true → loadBackground = true
  armBlankTimer()
  logEvent("lock-requested")
  queueSessionLock()         // 500ms stabilize timer starts NOW

  Qt.callLater(function() {  // deferred to next event loop iteration
    root.refreshBackground() // readlinkProc starts here
    root.refreshFingerprintStatus()
  })

  return true
}
```

The race:
1. `lockRequested = true` → `root.locked` becomes true → `LockView.qml`'s `loadBackground` binding flips to `true`
2. `queueSessionLock()` starts `sessionLockStabilizeTimer` (500ms) → `sessionLock.locked = true` shortly after
3. The `Image` element in `LockView.qml` starts loading with whatever `backgroundPath` is currently set
4. `Qt.callLater` defers `refreshBackground()` to the next event loop — `readlinkProc` hasn't resolved the symlink yet
5. If `backgroundPath` is empty or stale, the Image loads nothing → **black screen**
6. Once `readlinkProc` completes and the Image decodes → wallpaper appears

In `LockView.qml`:

```qml
Image {
  id: wallpaper
  source: root.loadBackground ? root.fileUrl(root.backgroundPath) : ""
  asynchronous: true
  cache: false
  // ...
}
```

`loadBackground` is bound to `root.locked`, which is true the instant `beginLock()` runs. The Image tries to load before `backgroundPath` is resolved.

**Note on lock-explorer plugin:**

This race exists on both `quattro` and `v4-0-4` (stable). The `io.github.sirjul1337.lock-explorer` plugin copies the same `Qt.callLater` pattern from the stock plugin. Users may notice the flash more after removing lock-explorer if the plugin's different rendering pipeline happened to mask the symptom.

**Related issues:**
- #7416 — related but different (wallpaper not reloading after suspend/resume, `backgroundVersion` cache-bust not firing on wake)

**Suggested fix:**

Move `refreshBackground()` before `queueSessionLock()` so `backgroundPath` is resolved before the session lock activates:

```qml
function beginLock() {
  if (!passwordPamConfigured) {
    logEvent("lock-denied: missing-pam")
    return false
  }

  resetAuthenticationState()
  lockRequested = true
  armBlankTimer()
  logEvent("lock-requested")

  refreshBackground()         // resolve path BEFORE arming the lock
  refreshFingerprintStatus()

  queueSessionLock()          // now the 500ms timer runs with a valid backgroundPath

  return true
}
```

Or keep the `Qt.callLater` for fingerprint (which is slow) but resolve the background synchronously.

---
*This issue was investigated and written by OpenCode (AI coding agent) on behalf of the user.*

---
Related Images (@AlyKazani04 here): 

Shows up for a split second.
<img width="4080" height="2296" alt="Image" src="https://github.com/user-attachments/assets/6bf288d5-9ede-4213-a278-2318a84d2719" />
After
<img width="4080" height="2296" alt="Image" src="https://github.com/user-attachments/assets/67b7edd3-7ade-4093-ab7c-956632b9d561" />