# Lios

Lios is a polished Rust GTK4/VTE terminal emulator by Knott Dynamics and Trevor Knott. It keeps the terminal core reliable by using VTE, then focuses on what should feel better day to day: beautiful built-in themes, glass/background controls, fast same-directory windows, simple config, and an opt-in GPU renderer switch without making unstable GPU paths the default.

## Why Lios

- Uses VTE for real terminal behavior instead of a toy parser.
- Keeps Cairo as the reliable default renderer, with explicit opt-in GPU modes for GTK auto, OpenGL, or Vulkan.
- Treats theming as a core feature, not a plugin: built-in palettes, opacity, background images, accent tint, and live preferences are baked in.
- Opens new windows in the active terminal directory, which keeps shell workflows smooth.
- Stays small: SSH and other extra workflows belong in optional `lios-*` helpers, not the core terminal.
- Avoids telemetry, background downloads, and secret storage.

## Features

- GTK4 window with a VTE terminal widget.
- Spawns `$SHELL`, with common Unix shell fallbacks.
- Optional `-- COMMAND ...` and `--command "..."` launch modes.
- Dark readable defaults: white-on-black palette, opaque dark backing layer, `Monospace 12`, block cursor, 1,000 lines of scrollback.
- Built-in themes: `xfce`, `xterm`, `green-on-black`, `white-on-black`, `dark-pastels`, `cyberpunk`, `matrix`, `ocean`, `ember`, `solarized-dark`, `solarized-light`, `black-on-white`.
- Slider-based master/full-window opacity plus nested image, terminal shade, and accent opacity controls.
- Background image support with `~` path expansion, fixed color tint, or per-launch random accent tint.
- Packaged default background image for first launch on new machines.
- Explicit visible mouse pointer over the terminal instead of VTE's dark text cursor shape.
- GPU acceleration toggle: reliable `cairo` by default, with opt-in safe auto/OpenGL (`auto` or `gl`) or explicit Vulkan (`vulkan`) through `GSK_RENDERER` before GTK starts.
- Child shells get `TERM=xterm-256color`, `COLORTERM=truecolor`, and `TERM_PROGRAM=lios`; VTE Sixel rendering is enabled.
- Desktop launcher install with `lios --install` or `lios ---install`.
- App icon installed from `assets/logo.png`.
- Optional window decoration/topbar removal.
- Slim topbar with a collapsible in-window preferences drawer for common live theme/background changes.
- `Ctrl+Shift+N` and `New Window` open a borderless terminal in the active terminal directory.
- Right-click appearance submenus for background images, terminal glass, accent presets, random tint, and themes.
- Right-click diagnostics for active windows, RSS, scrollback, terminal identity, image protocol, theme, background, and config path.
- Terminal-driven config commands for theming from a shell or script.
- Clipboard/context actions for copy, copy as HTML, paste, select all.
- Ctrl-clickable `http`, `https`, and `file` links open through the system URI handler.
- Fixed cursor color profiles for `XFCE Red`, `Violet`, `Cyan`, `Emerald`, `Amber`, and `Rose`, plus persistent cursor-to-accent matching.
- Keyboard shortcuts for `Ctrl+Shift+C`, `Ctrl+Shift+V`, `Ctrl+Shift+A`, `Ctrl+Shift+N`, `Ctrl+Shift+Q`, `Ctrl+Shift+,`, `Esc` while preferences are open, `Ctrl++`, `Ctrl+-`, and `Ctrl+0`.

## Links

- [Source repository](https://github.com/Tknott95/KnottTerminal)
- [crates.io package](https://crates.io/crates/lios)
- [docs.rs package page](https://docs.rs/lios)
- [GTK4 project](https://www.gtk.org/)
- [VTE terminal widget](https://gitlab.gnome.org/GNOME/vte)

## System Dependencies

Install Rust plus GTK4/VTE libraries and headers.

Debian/Ubuntu names:

```sh
sudo apt install pkg-config libgtk-4-dev libvte-2.91-gtk4-dev
```

Arch names:

```sh
sudo pacman -S rust pkgconf gtk4 vte4
```

## Run

Install from crates.io:

```sh
cargo install lios
lios
```

Run from source:

```sh
cargo run
cargo run -- --working-directory "$HOME"
cargo run -- -- htop
cargo run -- --command "ls -la"
cargo run -- --theme solarized-dark
cargo run -- --gpu
cargo run -- --gpu-mode vulkan
cargo run -- --renderer gl
cargo run -- --opacity 0.88
cargo run -- --background-image ~/Pictures/wallpaper.jpg --background-opacity 0.50 --random-overlay
cargo run -- --hide-titlebar
cargo run -- config init
cargo run -- config set gpu on
cargo run -- config set gpu_mode gl
cargo run -- config set theme solarized-dark
cargo run -- config set renderer gl
cargo run -- config set background.image ~/Pictures/wallpaper.jpg
cargo run -- config set topbar false
```

## Optional Plugins

Core Lios stays small. Optional helpers use separate `lios-*` packages.

`lios-ssh` launches OpenSSH inside Lios without storing hosts, passwords, keys, or SSH config:

```sh
cargo install lios-ssh
lios-ssh user@example.com
lios-ssh -p 2222 user@example.com
lios-ssh --theme solarized-dark -- -J jump.example.com user@example.com
```

The helper wraps `lios -- ssh ...` using argv. OpenSSH still handles `~/.ssh/config`, SSH agent, known hosts, keys, jump hosts, and verification.

## Configuration

Lios reads `~/.config/lios/config.toml` by default when it exists. Use `--config path/to/config.toml` to load another file.

```toml
[window]
title = "Lios"
width = 960
height = 640
decorated = false # set true to show the topbar/window decorations
renderer = "cairo" # cairo disables GPU; auto/gl use OpenGL, vulkan explicitly tries Vulkan
opacity = 1.00 # master/full-window opacity

[terminal]
font = "Monospace 12"
scrollback_lines = 1000 # max 100000

[theme]
name = "xfce"
# Optional custom overrides:
# foreground = "#ffffff"
# background = "#000000"
# Optional XFCE Red cursor preset values:
# cursor_background = "#e6192e"
# cursor_foreground = "#a51d2d"
# cursor = "#e6192e" # legacy alias for cursor_background
# cursor_match_overlay = false # cursor follows the effective accent overlay when true
# palette = ["#000000", "#aa0000", "#00aa00", "#aa5500", "#0000aa", "#aa00aa", "#00aaaa", "#aaaaaa", "#555555", "#ff5555", "#55ff55", "#ffff55", "#5555ff", "#ff55ff", "#55ffff", "#ffffff"]

[[theme_profile]]
name = "Ocean Glass"
theme = "ocean"
font = "Monospace 12"
window_opacity = 0.95
terminal_opacity = 0.50
overlay_color = "#00b4d8"
overlay_opacity = 0.12
random_overlay = false

[background]
image = "/home/example/Pictures/wallpaper.jpg"
image_opacity = 1.00
terminal_opacity = 0.50
# Use lower values for more glass/desktop transparency.
# overlay_color = "#7c3aed"
overlay_opacity = 0.00
random_overlay = true
```

CLI flags override the config file for one run. Use `--gpu` for safe GTK GL rendering, `--gpu-mode gl` to force OpenGL, `--gpu-mode vulkan` to explicitly try Vulkan, and `--no-gpu` to force the reliable Cairo renderer. The text config stores this as `window.renderer` so older configs remain valid.

Theme cursor colors can be configured as a pair with `theme.cursor_background` and `theme.cursor_foreground`; leaving both unset keeps the normal inherited VTE cursor. Set `theme.cursor_match_overlay = true` to make the cursor follow the effective accent overlay color for the current terminal and newly opened windows. The red XFCE-style pair shown above is available as a fixed `XFCE Red` profile, alongside `Violet`, `Cyan`, `Emerald`, `Amber`, and `Rose` cursor profiles. Existing configs that use `theme.cursor` still work as a cursor-background alias. Preferences include cursor background/foreground fields with clickable color swatches, fixed profiles, `Match Accent`, and clear controls. Saved appearance profiles use `[[theme_profile]]` tables and appear in the compact bottom `Profiles` section after saving.

Cursor accent matching is cursor-only. It does not change `[background]` settings such as `overlay_color`, `overlay_opacity`, or `random_overlay`. If no overlay is currently drawn, Lios keeps the configured or inherited cursor color until an effective overlay exists. Selecting a fixed cursor profile or clearing cursor colors turns `theme.cursor_match_overlay` off.

Use `window.opacity` or `--opacity` as the main full-window opacity. This affects the whole terminal UI and is the primary control for app transparency.

Background images are rendered against the theme background and composited below a transparent VTE terminal. `image_opacity` controls how strongly the image blends into the theme-colored base. `terminal_opacity` is the nested terminal shade layer over that image; lower values show more image while preserving readable text. Without an image, use the master opacity for reliable transparent-terminal behavior, then use `terminal_opacity` only as the inner shade. If an older config has an image with `terminal_opacity = 1.00`, Lios uses the image shade at runtime so the image is not hidden by a fully opaque terminal background.

On a new machine with no existing Lios config, the packaged default background is written to the user data directory and used automatically. Existing config files are respected.

The topbar is hidden by default. `Ctrl+Shift+,` opens the collapsible in-window preferences drawer, and the right-click menu also includes `Open Preferences...`. `Ctrl+Shift+N` opens another borderless terminal window in the active terminal directory using the current live settings. `Ctrl+Shift+Q` closes the current window. The drawer can change GPU acceleration mode, theme, cursor colors, font, topbar visibility, background image path, master opacity, terminal shade opacity, image opacity, accent opacity, overlay color, and random overlay. The compact bottom `Profiles` section saves the current appearance under a name, persists it as a `[[theme_profile]]`, and shows small apply buttons for saved looks. Cursor color rows include text fields and color-picker swatches; clearing both fields restores the normal inherited cursor. `Match Accent` is a persistent cursor-only toggle: when enabled, the cursor follows the effective overlay color, including random overlay colors chosen for new terminals, without mutating overlay color, random overlay, or overlay opacity. Opacity controls are sliders. The background row includes `Browse` and `Clear` controls; chosen images apply immediately and lower terminal shade opacity if needed so the image is visible. Other edits enable `Apply and Save` plus `Revert`, and `Esc` closes the drawer. The footer includes a glowing `Live Edit` toggle that starts off whenever the drawer opens, applies and saves valid edits immediately while lit, and turns itself off when the drawer closes. Theme/background/font/cursor changes apply live after Apply or Live Edit; renderer changes are saved and apply on the next launch. Changes are written back to `~/.config/lios/config.toml` when a config path is available.

Right-click inside the terminal for quick actions. `New Window` opens a borderless terminal in the active terminal directory. `Close Window` manages terminal windows. `Diagnostics` prints resource state into the terminal. `Reset to Dark Default` returns the current window to the plain dark default look. The `Opacity` submenu starts with master/full-window opacity controls, then nests terminal shade controls under `Terminal Shade`. The `Background` submenu changes/clears images, adjusts image brightness, or resets the whole background. `Cursor` applies fixed cursor profiles (`XFCE Red`, `Violet`, `Cyan`, `Emerald`, `Amber`, `Rose`), enables persistent cursor-to-accent matching, or restores the inherited default. `Accent` switches fixed accent presets (`Violet`, `Cyan`, `Emerald`, `Amber`, `Rose`), toggles random accent tint, and adjusts accent strength. The `Theme` submenu switches built-in terminal themes. These actions apply live and persist to the active config path when one is available.

## Desktop Launcher

Install or build the binary first, then run `lios --install` to add Lios to the desktop app menu without launching it from another terminal. `lios ---install` is also accepted.

```sh
cargo install --path .
lios --install
```

The command writes `dev.lios.Terminal.desktop` under `$XDG_DATA_HOME/applications` or `~/.local/share/applications` with `Terminal=false` and `Exec` pointing at the exact binary that ran the command. It also installs the app icon from `assets/logo.png` as `dev.lios.Terminal` under the user icon theme and requests a desktop/icon cache refresh when the standard desktop tools are available. Normal GUI startup also makes the packaged icon available to GTK so direct `cargo run` launches can resolve the same icon name. Running `cargo run -- --install` creates a launcher for `target/debug/lios`; use the installed `lios --install` command for a stable app-menu entry. Use `lios --uninstall` or `lios ---uninstall` to remove that launcher and icon.

## Resource Policy

- Terminal scrollback is bounded. `scrollback_lines` must be between `0` and `100000`; the default is `1000`.
- Runtime diagnostics show active windows, process RSS, scrollback limit, renderer, terminal identity, image protocol, theme, background image, opacity, overlay state, and config path.
- GTK callbacks that can outlive their parent window use weak window references to avoid reference cycles during repeated open/close cycles.
- Segmented preference controls store weak button references internally, avoiding self-cycles between buttons and their click closures.
- No Tokio tasks or channels are used; child processes are owned by VTE and tied to the terminal widget/window lifecycle.
- VTE Sixel rendering is enabled. Lios exports its own VTE/Sixel identity and strips inherited Kitty, WezTerm, and iTerm marker variables so child apps do not detect unsupported image protocols. Image tools still need to run outside tmux or inside tmux configured to pass image protocols through.

Rust `1.88.0` can ICE while compiling generated GTK binding crates with heavy debug or optimization settings. `Cargo.toml` keeps the workaround scoped to the affected GTK crates. If `cargo install` still crashes while compiling GTK dependencies with a rustc stack trace, retry with a larger compiler stack:

```sh
RUST_MIN_STACK=16777216 cargo install --path .
```

Terminal config commands:

```sh
lios config path
lios config sample
lios config init
lios config init --force
lios config show
lios config set gpu on
lios config set gpu_mode vulkan
lios config set renderer gl
lios config set theme solarized-dark
lios config set opacity 0.88
lios config set background_opacity 0.80
lios config set overlay_color '#7c3aed'
lios config set overlay_opacity 0.18
lios config set random_overlay true
lios config set cursor_match_overlay true
lios config set topbar false
lios --install
lios ---install
lios --uninstall
```

Useful keys include `gpu`, `gpu_mode`, `renderer`, `theme`, `font`, `cursor_match_overlay`, `opacity`, `background.image`, `background_opacity`, `background_image_opacity`, `overlay_color`, `overlay_opacity`, `random_overlay`, and `topbar`.

## Package

The Cargo package is named `lios` and includes crate metadata for packaging. `Cargo.toml` uses an explicit package include list, so workspace notes such as `.notes.MD` are not part of the published crate.

```sh
cargo publish --dry-run
cargo publish
```
