# Lios
Customizable Rust GTK4/VTE terminal emulator scaffolded from the initial Xfce Terminal-style reference in `../KnottTerminalRef`.
## Current Scope
- GTK4 window with a VTE terminal widget.
- Spawns the user's `$SHELL`, with common Unix shell fallbacks.
- Optional `-- COMMAND ...` and `--command "..."` launch modes.
- Reference-aligned dark defaults: Xfce-style 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`, `solarized-dark`, `solarized-light`, `black-on-white`.
- Background image support with `~` path expansion, image opacity, terminal shade opacity, fixed color tint, or per-launch random accent tint.
- Renderer selection: `auto`, `gl`, `vulkan`, or `cairo` through `GSK_RENDERER` before GTK starts.
- User-level desktop launcher install with `lios --install` or the typo-compatible `lios ---install`.
- Optional window decoration/topbar removal.
- Slim topbar with a collapsible in-window preferences drawer for common live theme/background changes.
- Right-click appearance submenus for background images, terminal glass, accent presets, random tint, and themes.
- Right-click diagnostics for active windows, RSS, scrollback, 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.
- Keyboard shortcuts for `Ctrl+Shift+C`, `Ctrl+Shift+V`, `Ctrl+Shift+A`, `Ctrl+Shift+N`, `Ctrl+Shift+Q`, `Ctrl+Shift+,`, `Ctrl++`, `Ctrl+-`, and `Ctrl+0`.
## System Dependencies
Install Rust plus GTK4/VTE development packages.
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
```sh
cargo run
cargo run -- --working-directory "$HOME"
cargo run -- -- htop
cargo run -- --command "ls -la"
cargo run -- --theme solarized-dark
cargo run -- --renderer gl
cargo run -- --background-image ~/Pictures/wallpaper.jpg --background-opacity 0.62 --random-overlay
cargo run -- --hide-titlebar
cargo run -- config init
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
```
## 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 = true # set false to remove the topbar/window decorations
renderer = "auto" # auto, gl, vulkan, cairo
[terminal]
font = "Monospace 12"
scrollback_lines = 1000 # max 100000
[theme]
name = "xfce"
# Optional custom overrides:
# foreground = "#ffffff"
# background = "#000000"
# cursor = "#ffffff"
# palette = ["#000000", "#aa0000", "#00aa00", "#aa5500", "#0000aa", "#aa00aa", "#00aaaa", "#aaaaaa", "#555555", "#ff5555", "#55ff55", "#ffff55", "#5555ff", "#ff55ff", "#55ffff", "#ffffff"]
[background]
image = "/home/you/Pictures/wallpaper.jpg"
image_opacity = 1.00
terminal_opacity = 0.62
# overlay_color = "#7c3aed"
overlay_opacity = 0.00
random_overlay = false
```
CLI flags override the config file for one run.
Background images are rendered against the theme background and then composited below a transparent VTE terminal, matching the reference behavior. `image_opacity` controls how strongly the image blends into the theme-colored base. `terminal_opacity` controls Lios' own theme-colored shade layer over that image; lower values show more image while preserving readable text. If an older config has an image with `terminal_opacity = 1.00`, Lios uses the reference-style image shade at runtime so the image is not hidden by a fully opaque terminal background.
The default topbar includes a `Customize` button when `decorated = true`. It opens a collapsible in-window drawer rather than a separate dialog. `Ctrl+Shift+,` toggles the same drawer, which is useful when the topbar is hidden. `Ctrl+Shift+N` opens another terminal window using the current live settings. `Ctrl+Shift+Q` closes the current window. The drawer can change renderer, theme, font, background image path, image opacity, terminal opacity, overlay color, overlay opacity, random overlay, and topbar visibility. The background row includes a `Choose Image` button with an image-file picker; chosen images apply immediately and lower terminal opacity if needed so the image is visible. Theme/background/font changes apply live; 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` and `Close Window` manage terminal windows. `Diagnostics` prints resource state into the terminal. `Reset to Dark Default` returns the current window to the plain dark reference-style look. The `Background` submenu changes/clears images, adjusts image brightness, or resets the whole background. `Terminal Glass` adjusts terminal transparency. `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 accepted as a typo-compatible alias.
```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. If you run `cargo run -- --install`, the launcher will point at `target/debug/lios`; use the installed `lios --install` command when you want a stable app-menu entry. Use `lios --uninstall` or `lios ---uninstall` to remove that launcher.
## 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, 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.
Rust `1.88.0` can ICE while compiling `glib` with full dev debuginfo during package verification. `Cargo.toml` keeps dev debuginfo disabled for only `glib` as a scoped workaround. If `cargo install` still crashes while compiling GTK/glib 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 renderer gl
lios config set theme solarized-dark
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 topbar false
lios --install
lios ---install
lios --uninstall
```
Useful keys include `renderer`, `theme`, `font`, `background.image`, `background_opacity`, `background_image_opacity`, `overlay_color`, `overlay_opacity`, `random_overlay`, and `topbar`.
## Publish
The Cargo package is currently named `lios` and has crates.io metadata. The crates.io index currently reports `lios = "0.1.0"`, so publish under this exact name only if you control that crate; otherwise rename the package before a real publish. Also decide whether to keep the current `MIT OR Apache-2.0` license.
```sh
cargo publish --dry-run
cargo publish
```