refactor: split the TUI and refresh project docs
Move login state, authentication, discovery, input, rendering, and tests into focused TUI modules. Add detailed CLI error reports with recovery commands, align the build and host-check documentation, and keep the legacy Go tree outside normal builds. Checks: make check; make integration-test; go test ./... (legacy/go).
This commit is contained in:
82
docs/ui.md
82
docs/ui.md
@@ -1,39 +1,75 @@
|
||||
# Latchd user interface
|
||||
# User interface
|
||||
|
||||
Latchd starts on a virtual terminal. The interface keeps the session list and the login fields visible at the same time.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
The screenshot comes from the Docker test image. It uses preview mode. Preview mode does not contact PAM or start a user session.
|
||||
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 show the key reference.
|
||||
Press `?` to open the key reference:
|
||||
|
||||
|
||||
|
||||
|
||||
Use the following keys:
|
||||
Press `Esc` or `?` again to close it. The help panel does not change the selected account or session.
|
||||
|
||||
- Press `Tab` or `Shift-Tab` to move focus.
|
||||
- Press the arrow keys to choose a session.
|
||||
- Press `/` to filter sessions or accounts.
|
||||
- Press `Ctrl-N` or `Ctrl-P` to change the account.
|
||||
- Press `Ctrl-R` to refresh account and session discovery.
|
||||
- Press `Ctrl-B` to toggle the background.
|
||||
- Press `Ctrl-M` to toggle reduced motion.
|
||||
- Press `Enter` to authenticate.
|
||||
- Press `Esc` to clear the password or close the help panel.
|
||||
- Press `Ctrl-C` to restore the terminal and quit.
|
||||
## Capture the screen
|
||||
|
||||
These messages show account state before login. PAM accepts or rejects the login.
|
||||
|
||||
## Capture method
|
||||
|
||||
The capture uses a Docker PTY and the release binary from `latchd-test:local`:
|
||||
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 image in this directory contains the plain terminal capture. It does not show a host VT, a host compositor, or a real PAM login.
|
||||
The capture shows the preview binary and terminal renderer, preview mode is simply for testing and doesn't perform any real login.
|
||||
Reference in New Issue
Block a user