# User interface

The screen is designed for a virtual terminal. It keeps the session list beside the account and password fields, and adapts down to 60 columns by 16 rows.

![Latchd login screen](images/latchd-preview.png)

Preview mode screenshot of the login layout.

## Fields and status

- session list — choose an X11, Wayland, administrator-script, or TTY entry
- username — type an account name or select one discovered through NSS
- password — enter the password; the screen clears it after an attempt
- status line — shows focus prompts, account state, faillock counts, notices, and authentication progress
- footer — shows the keys that apply to the current screen state

When the selected account needs a new password, the password field changes to the new-password prompt. The old password stays in the pending authentication request until the password-change call finishes, then both values are cleared.

## Keys

| Key | Action |
| --- | --- |
| `Tab` / `Shift-Tab` | Move between session, username, and password |
| `Up` / `Down` | Move focus, or move through the filtered list |
| `Left` / `Right` | Change the session when the session list has focus |
| `/` | Start a session or account filter |
| `Ctrl-R` | Refresh accounts and sessions in the background |
| `Ctrl-N` / `Ctrl-P` | Select the next or previous account |
| `Ctrl-B` | Toggle the wallpaper and ambient animation |
| `Ctrl-M` | Toggle reduced motion |
| `Enter` | Start login or submit a new password |
| `Esc` | Clear the password, close a popup, or cancel power confirmation |
| `?` | Open the key reference |
| `Ctrl-C` | Restore the terminal and exit |
| `F1`–`F12` | Confirm the matching configured power action |

Lowercase filters ignore case. A filter with an uppercase character uses case-sensitive matching. Press `Esc` while filtering to leave the filter field.

## Visual settings

The `[visual]` section controls the background:

```toml
[visual]
background_enabled = true
animations = true
notifications = true
reduced_motion = false
max_wallpaper_bytes = 8388608
# wallpaper_path = "/etc/latchd/wallpaper.png"
```

`wallpaper_path` accepts a root-owned PNG or JPEG file. The loader checks the file size and source dimensions, then scales the image before it draws it in the terminal. `animations = false` stops frame updates at startup, while `reduced_motion = true` does the same and can also be changed with `Ctrl-M`.

Set `LATCHD_ASCII=1` for terminals without reliable Unicode cells, `NO_COLOR=1` for plain output, and `LATCHD_HIGH_CONTRAST=1` for a stronger focus style.

## Help panel

Press `?` to open the key reference:

![Latchd help panel](images/latchd-help.png)

Press `Esc` or `?` again to close it. The help panel does not change the selected account or session.

## Capture the screen

Build the Docker test image, then start a PTY with a fixed size:

```sh
docker build -f Dockerfile.test -t latchd-test:local .
tmux new-session -d -x 120 -y 36 \
  'docker run --rm -it latchd-test:local /workspace/target/release/latchd --preview --no-log'
```

The capture shows the preview binary and terminal renderer, preview mode is simply for testing and doesn't perform any real login.