lock

The session lock: whether it is held, authentication progress and the last failure.

The lock screen itself is a lock surface; this capability locks the session and reports the password attempt.

button {
    on_click = function() mantle.lock:lock() end,
    children = { text { content = "Lock" } },
}

State

mantle.lock:get() returns LockState, nil before the first push. A field marked ? may be absent.

mantle.lock’s payload.

Field	Type	Description
`active`	`boolean`	The Renderer confirmed the session locked; a requested lock stays `false` until then.
`attempts`	`integer`	Rejected passwords since this lock was confirmed; reset by the next lock.
`authenticating`	`boolean`	A password is with PAM. A second submit is refused while true.
`error`	`string`	Last failure to draw: PAM’s verdict (`"authentication failed"`, `"too many attempts"`, or a PAM or worker error) or a refused lock’s reason. Cleared by a correct password, `lock`, a confirmed lock, and unlock.
`unlocking`	`boolean`	PAM said yes and the lock is still up: the window for an out-animation.

Call each as mantle.lock:<action>(arguments...); ? marks an argument you may omit.

mantle.lock actions. There is no unlock; only a correct password unlocks.

Action	Arguments	Description
`lock`		Locks the session; a no-op while `active`.
`set_unlock_animation`	`ms?: integer`	Keeps the lock up `ms` after a correct password for an out-animation. Clamped to 600; omitted is `0`.

Contract	Behavior
Ownership	The Supervisor decides lock and unlock; the Renderer holds and paints `ext_session_lock_v1`. Built at boot, unlike other capabilities
Triggers	The `lock` action, and logind’s `Lock` signal (`loginctl lock-session`). logind’s `Unlock` is logged and ignored. Each lock and unlock sets logind’s `LockedHint`
Unlock	Only a successful PAM conversation, run in a re-exec’d worker with the `mantle` PAM service from `/etc/pam.d` or `/usr/lib/pam.d`, else `login`. An exchange that takes over 30 s fails
Unlock animation	`set_unlock_animation` delays the release by up to 600 ms; the value persists across reloads
Crash	A dead Renderer never unlocks; the replacement retakes the lock. `$XDG_RUNTIME_DIR/mantle/session-locked` carries the lock across a Supervisor restart
Refused or lost	Sets `mantle.rescue` with the reason
Reload	An edit that would recreate a lock surface is refused while locked (lock surface)

Task	Answer
Show “wrong password”	`error` and `attempts`: lock surface example
Animate the lock screen out	`set_unlock_animation` with the animation’s length, then drive the fade from `unlocking`: Lock screen recipe

Trap	Fix
Removing `set_unlock_animation` from the config keeps the old delay	The value outlives reloads. Call `set_unlock_animation` with no argument to reset it to `0`
A 1 s out-animation is cut short	The delay clamps to 600 ms. Keep the animation within it

See also: Lock screen recipe; idle to lock after inactivity.