SouveraineOS/docs/tasks/02-lockscreen-rust-system.md

TASK 02 — Lockscreen-as-Rust-system: glance + swipe

Status: in progress. Stopgap shipped 2026-07-17 (fallback invisible on normal boot). The real fix is this task.

Goal

sessiond's fallback surface should NOT be a second lockscreen. It should render the glance (clock, wallpaper, notification count) and defer PIN entry to the shell's lockscreen. The keypad appears only in true recovery — when the shell is genuinely dead, not just slow at boot.

This kills two problems at the root:

• The two-PIN-styles flash on every boot.
• The class of bug where a shell crash takes the lockscreen with it (sessiond's surface stays coherent; it just shows the glance until the shell retakes the lock).

Context — what exists

• ~/Projects/souveraine/src/sessiond/draw.rs — software renderer. Today renders a dark field + PIN dots + 3x4 keypad. Has Scene { quiet: bool } (added 2026-07-17): when quiet, renders only the dark field until first input, then reveals the keypad. That's the stopgap.
• ~/Projects/souveraine/src/sessiond/lock.rs — ext-session-lock-v1 client. LockState has quiet, reveal(), the touch/pointer/keyboard dispatch. Splash handoff via poke_splash() → /run/souveraine-splash.sock.
• ~/Projects/souveraine/src/sessiond/server.rs — LockedAck handler fires hyprctl dismissnotify to clear the "lockscreen crashed" banner that Hyprland shows for any dying lock client (added 2026-07-17).
• Shell side: ~/.config/quickshell/souveraine/modules/souveraine/lock/ has LockSurfaceHost, LockMediaCard, LockAgentCard — the rich glance widgets already exist in the shell. sessiond doesn't need to reimplement them, just get out of their way.

What to build

1. Replace the keypad-only render() scene with a glance scene: clock (system time, no Date::now() in workflow scripts — but this is a runtime binary, std::time::SystemTime is fine), wallpaper fill, and a small "tap to unlock" hint. Keep the dark-field aesthetic.
2. Move PIN entry to only arm after a real recovery trigger: shell heartbeat lost for >N seconds (server.rs already tracks shell_alive and retakes on EOF). The keypad is the recovery UI, not the boot UI.
3. First-input reveal stays as the fallback's own escape hatch.

Acceptance

• Cold boot: splash fades directly onto the shell's lockscreen glance. sessiond's surface is never visible as a distinct second lock.
• Shell killed manually mid-session: sessiond retakes, shows its glance (not a bare keypad), and offers PIN entry.

Do not

• Don't make sessiond render the shell's widget cards. That's the shell's job. sessiond's glance is spartan on purpose — it competes on availability, not feature parity (see draw.rs header comment).

Connects to

TASK-03 (boot timing — the glance is what the splash should fade onto), TASK-05 (crash reporter — a crashed shell should surface here).