# Interface

The layout is inspired by [torrra](https://github.com/stabldev/torrra): a
left sidebar with filter categories, a main panel with the torrent list, and
an always-visible footer with keybindings. All panels and popups are drawn
with rounded corners (`╭─╮`/`╰─╯`) in a consistent style.

## Splash screen

```
              ╭─ TransTUI ──────────────────────────────────────────╮
              │                                                     │
              │   █████ ████   ███  █   █  ████ █████ █   █ █████   │
              │     █   █   █ █   █ ██  █ █       █   █   █   █     │
              │     █   ████  █████ █ █ █  ███    █   █   █   █     │
              │     █   █  █  █   █ █  ██     █   █   █   █   █     │
              │     █   █   █ █   █ █   █ ████    █    ███  █████   │
              │                                                     │
              │               Transmission TUI Client               │
              │      Press any key to continue…                     │
              ╰─────────────────────────────────────────────────────╯
```

A blocky, white "16-bit"-style splash screen shows for up to 3 seconds or
until you press a key. Can be turned off permanently in settings
(`g` → *Splash screen: On/Off*), see [Configuration](Configuration.md).

## List view

```
╭─ Filter ─────╮╭─ All (2) ────────────────────────────────────────────────╮
│ ❯ All        ││  Name            Size        %  Status       Down   Up   │
│   Downloading││  Debian netinst  667 MiB  100%  Seeding      0 B/s  12K/s│
│   Uploading  ││  Ubuntu ISO      3.7 GiB    75%  Downloading 5M/s   0 B/s│
│   Paused     ││                                                          │
│   Completed  ││                                                          │
╰──────────────╯╰──────────────────────────────────────────────────────────╯
  ↑↓  Navigate  Tab  Filter  Enter  Details  Space  Select  s/S/p  Start/Stop
  a  Add  d  Remove  l  Speed  o/O  Sort  /  Search  g  Settings
```

- **The sidebar** (left) filters the list live by category: All,
  Downloading, Uploading, Paused, Completed.
- **The main panel** (right) shows torrents matching the filter, with
  columns for size, progress, status, speeds, ETA, and ratio (the last two
  are automatically hidden on narrow terminals to give the name more room).
- **The footer** shows keybindings as chips, context-dependent on whether
  the sidebar or the list has focus.
- **The status line** (above the footer) shows total speeds, torrent count,
  and sort column - or a temporary status message after an action (e.g.
  "Started 1 torrent(s)").

`Tab` switches keyboard focus between the sidebar and the list. With focus
in the sidebar, `↑`/`↓` moves the cursor between categories and applies the
filter immediately (live preview); `Enter`/`→`/`Tab` moves focus back to
the list. Full key reference: [Keybindings](Keybindings.md).

## Detail view

Opened with `Enter` on a selected torrent. Four tabs (`Tab` or `1`-`4`):

- **General** - hash, size, progress, speed, ratio, peers, speed limits,
  folder, dates, any error message.
- **Files** - every file in the torrent with size, progress, priority, and
  wanted/skip status. `space` toggles wanted/skip, `+`/`-` changes priority
  (low/normal/high) - changes are sent to the daemon immediately.
- **Peers** - connected peers: address, client, progress, speeds, flags.
- **Trackers** - tracker URLs per tier, latest announce result,
  seeders/leechers.

## Settings (`g`)

Opens as its own full-screen view (same style as the help screen) - even if
no daemon is connected, since otherwise it would be impossible to fix a
wrong host/port. Contains:

- **Connection** (Host, Port, Username, Password) - saved to `config.ini`
  and applied immediately to the running session. Does *not* replace the
  command-line flags (`-H`/`-P`/`-u`/`-p`), which are still read at startup
  and override what's in `config.ini`.
- **Splash screen** (On/Off).
- **Download folder** (choose to browse or type a path, same picker as
  described below) and speed limits/ratio limit/alt-speed schedule -
  read/written directly against the daemon via `session-get`/`session-set`.
  Also cached locally so an unclean daemon restart can't silently lose the
  change - see [Configuration](Configuration.md#session-settings-cache-cache_-keys).

`↑`/`↓` navigates the fields, `Enter`/`space` changes a value or toggles
on/off, `Esc`/`q` closes. If the daemon isn't connected it's shown in the
title, and `r` offers help fixing it - see
[Daemon: setup & troubleshooting](Daemon-Setup-and-Troubleshooting.md).

## Dialogs

Confirmations (`[y]es`/`[n]o`), text prompts (e.g. when adding a torrent
manually or editing a field), and message boxes are drawn as smaller,
centered popup boxes in the same rounded style, and can stack (e.g. "also
delete data on disk?" on top of "remove torrent?").

## Add torrent (`a`)

Asks first whether to browse for a local `.torrent` file or type a
magnet link/URL/path by hand - magnet links and remote URLs obviously
can't be browsed to. Choosing to browse opens a directory picker starting
in `$HOME` (remembering the last folder you visited for next time),
showing only subfolders and `.torrent` files to keep it uncluttered:

| Key | Function |
|---|---|
| `↑`/`k`, `↓`/`j` | move selection |
| `Enter` | open the selected folder, or select the highlighted `.torrent` file |
| `Backspace` / `←` | go up one folder (also listed as `..`) |
| `Esc` / `q` | cancel |

After picking a file (or typing a source), you're asked whether to use the
daemon's default download folder, or choose one - and if choosing, whether
to browse or type a path. The folder picker works like the file picker
above, but only lists subfolders (no `.torrent` filter) and `space`
selects whichever folder is currently open, since there's no file to press
`Enter` on to finish:

| Key | Function |
|---|---|
| `↑`/`k`, `↓`/`j` | move selection |
| `Enter` | open the selected folder |
| `space` | select the folder currently shown at the top of the box |
| `Backspace` / `←` | go up one folder (also listed as `..`) |
| `Esc` / `q` | cancel |

The same folder picker is used for the **Download folder** field in
settings (`g`).