### Install scdoc from source

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Clone the scdoc repository, build, and install it from source.

```bash
git clone https://git.sr.ht/~sircmpwn/scdoc
cd scdoc
make
sudo make install
```

--------------------------------

### Run Sugarloaf Example

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Command to run a specific example, 'text', using the Sugarloaf rendering engine.

```bash
cargo run --example text
```

--------------------------------

### Install scdoc on Arch Linux

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Use pacman to install the scdoc utility on Arch Linux.

```bash
sudo pacman -S scdoc
```

--------------------------------

### Install scdoc on Ubuntu/Debian

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Use apt to install the scdoc utility on Ubuntu or Debian-based systems.

```bash
sudo apt install scdoc
```

--------------------------------

### Install man pages to system directory

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Install the built man pages to the system's man directory. Requires sudo privileges.

```bash
sudo cp rio.1 /usr/local/share/man/man1/
sudo cp rio.5 /usr/local/share/man/man5/
sudo cp rio-bindings.5 /usr/local/share/man/man5/
```

--------------------------------

### Install wasm-bindgen-cli

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Installs the wasm-bindgen-cli tool globally, which provides a test runner harness for WebAssembly.

```bash
cargo install wasm-bindgen-cli
```

--------------------------------

### Install GLSL Tools on Fedora

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Installs the necessary GLSL to SPIR-V compiler for the Vulkan backend on Fedora.

```bash
dnf install glslang
```

--------------------------------

### Install GLSL Tools on Arch Linux

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Installs the necessary GLSL to SPIR-V compiler for the Vulkan backend on Arch Linux.

```bash
pacman -S shaderc
```

--------------------------------

### Install scdoc on macOS

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Use Homebrew to install the scdoc utility on macOS.

```bash
brew install scdoc
```

--------------------------------

### View man pages

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

View the installed man pages using the 'man' command, specifying the section number if necessary.

```bash
man rio
```

```bash
man 5 rio
```

```bash
man 5 rio-bindings
```

--------------------------------

### Install GLSL Tools on Debian/Ubuntu

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Installs the necessary GLSL to SPIR-V compiler for the Vulkan backend on Debian or Ubuntu-based systems.

```bash
apt install glslang-tools
```

--------------------------------

### Color Conversion Example

Source: https://github.com/raphamorim/rio/blob/main/rio-backend/src/config/colors/README.md

Illustrates the conversion of a hex color string to a WGPU Color struct using the ColorBuilder.

```rust
let color: wgpu::Color =
    ColorBuilder::from_hex(String::from("#151515"), Format::SRGB0_1)
        .unwrap()
        .to_wgpu();

assert_eq!(
    color,
    Color {
        r: 0.08235294117647059,
        g: 0.08235294117647059,
        b: 0.08235294117647059,
        a: 1.0
    }
);
```

--------------------------------

### Programmatic Access to Key Bindings

Source: https://context7.com/raphamorim/rio/llms.txt

Load the configuration and iterate through defined key bindings programmatically. Shows example output for different binding types.

```rust
// Programmatic access after loading config
use rio_backend::config::Config;

let config = Config::load();
for binding in &config.bindings.keys {
    println!(
        "key={} with={} action={} esc={} mode={}",
        binding.key,
        binding.with,
        binding.action,
        binding.esc,
        binding.mode
    );
}
// Example output:
// key=t with=super action=CreateTab esc= mode=
// key=Home with= action= esc=\x1bOH mode=appcursor

```

--------------------------------

### Internal Event System with `RioEvent`

Source: https://context7.com/raphamorim/rio/llms.txt

Illustrates how internal terminal and application events are routed through `RioEvent` and `EventPayload`. Shows an example of sending a `PrepareUpdateConfig` event using `EventLoopProxy` and lists common `RioEvent` variants.

```rust
use rio_backend::event::{EventPayload, RioEvent, RioEventType};
use rio_window::window::WindowId;

// Events are sent via EventProxy (wraps winit's EventLoopProxy)
// Example: triggering a config reload from another thread
let proxy: rio_window::event_loop::EventLoopProxy<EventPayload> = /* … */;

proxy.send_event(
    EventPayload::new(
        RioEventType::Rio(RioEvent::PrepareUpdateConfig),
        unsafe { WindowId::dummy() },
    )
).ok();

// Events handled inside ApplicationHandler::user_event:
// RioEvent::Render                 — repaint the focused window
// RioEvent::UpdateConfig           — hot-reload config from disk
// RioEvent::ClipboardStore(t, s)  — write `s` to clipboard type `t`
// RioEvent::ClipboardLoad(id,t,f) — read clipboard and send escape via `f`
// RioEvent::PtyWrite(id, text)    — write bytes to PTY of route `id`
// RioEvent::CreateWindow          — open a new window
// RioEvent::CloseTerminal(id)     — close a split pane / tab
// RioEvent::Bell                  — ring audio bell (if configured)
// RioEvent::DesktopNotification{title, body} — system notification
// RioEvent::ToggleFullScreen      — toggle borderless fullscreen
// RioEvent::Title(t)              — update window title bar to `t`
```

--------------------------------

### teletypewriter::terminfo_exists

Source: https://context7.com/raphamorim/rio/llms.txt

Checks if a given terminfo entry is installed on the system, used by Rio to determine the best `$TERM` value.

```APIDOC
## `teletypewriter::terminfo_exists`

Checks whether a given terminfo entry is installed on the system. Rio uses this at startup to pick the best `$TERM` value (`xterm-rio` > `rio` > `xterm-256color`).

### Arguments

*   `terminfo_entry`: A string slice representing the terminfo entry name to check.

### Returns

*   `true` if the terminfo entry exists, `false` otherwise.

### Usage Example

```rust
use teletypewriter::terminfo_exists;

// Check in $TERMINFO, $HOME/.terminfo, $TERMINFO_DIRS, and standard paths
if terminfo_exists("xterm-rio") {
    std::env::set_var("TERM", "xterm-rio");
} else if terminfo_exists("xterm-256color") {
    std::env::set_var("TERM", "xterm-256color");
} else {
    eprintln!("Warning: no suitable terminfo found");
}
```
```

--------------------------------

### Get Rio Configuration Paths

Source: https://context7.com/raphamorim/rio/llms.txt

Retrieves platform-specific paths for Rio's configuration directory and file. The `$RIO_CONFIG_HOME` environment variable can override these defaults. Useful for accessing configuration, themes, and log directories.

```rust
use rio_backend::config::{config_dir_path, config_file_path};

// macOS / Linux:  ~/.config/rio
// Windows:        %USERPROFILE%\AppData\Local\rio
// $RIO_CONFIG_HOME overrides all platforms
let dir  = config_dir_path();
let file = config_file_path();  // dir.join("config.toml")
let themes_dir = dir.join("themes");
let log_dir    = dir.join("log");

println!("Config dir:  {}", dir.display());
println!("Config file: {}", file.display());
// Config dir:  /home/user/.config/rio
// Config file: /home/user/.config/rio/config.toml
```

--------------------------------

### Update man database

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Update the system's man page database after installing new man pages. Requires sudo privileges.

```bash
sudo mandb
```

--------------------------------

### Launch Rio Terminal with CLI Flags

Source: https://context7.com/raphamorim/rio/llms.txt

Use these command-line flags to customize how Rio starts, including specifying the shell, working directory, title, and Wayland app ID. The -e flag must be the last argument, forwarding any subsequent arguments to the specified shell.

```bash
# Start rio with default shell in home directory
rio
```

```bash
# Start with a specific shell and arguments
rio -e /bin/bash --login
```

```bash
# Start in a specific working directory
rio --working-dir /home/user/projects/myapp
```

```bash
# Start with a custom title placeholder
rio --title-placeholder "dev session"
```

```bash
# Set the Wayland app_id (Linux/BSD)
rio --app-id my.custom.id
```

```bash
# Write the default config file to the standard path and exit
rio --write-config
```

```bash
# Write config to a custom path and exit
rio --write-config /tmp/rio-config.toml
```

```bash
# Enable file logging (written to <config-dir>/log/rio.log)
rio --enable-log-file
```

```bash
# Override shell via -e (must be last argument, all remaining args are forwarded)
rio -e nvim /tmp/file.txt
```

--------------------------------

### Setup Environment Variables for Child Processes

Source: https://context7.com/raphamorim/rio/llms.txt

Configures essential environment variables like `TERM`, `TERM_PROGRAM`, `COLORTERM`, and custom variables from the config file. On macOS, it also sets the locale and changes the working directory to `$HOME`. This ensures child processes inherit the correct terminal environment.

```rust
// From frontends/rioterm/src/main.rs
use rio_backend::config::Config;

let config = Config::load();

// Sets: TERM=xterm-rio (or xterm-256color fallback)
//       TERM_PROGRAM=rio
//       TERM_PROGRAM_VERSION=0.4.3
//       COLORTERM=truecolor
//       + any env-vars from config, e.g. EDITOR=nvim
setup_environment_variables(&config);

// After this call, child processes spawned by the PTY will inherit these vars.
// Check the result:
println!("TERM={}", std::env::var("TERM").unwrap_or_default());
println!("COLORTERM={}", std::env::var("COLORTERM").unwrap_or_default());
// TERM=xterm-rio
// COLORTERM=truecolor
```

--------------------------------

### Check Terminfo Existence

Source: https://context7.com/raphamorim/rio/llms.txt

Checks if a specific terminfo entry is installed on the system using `teletypewriter::terminfo_exists`. This is used to select the appropriate `$TERM` value for terminal emulation.

```rust
use teletypewriter::terminfo_exists;

// Check in $TERMINFO, $HOME/.terminfo, $TERMINFO_DIRS, and standard paths
if terminfo_exists("xterm-rio") {
    std::env::set_var("TERM", "xterm-rio");
} else if terminfo_exists("xterm-256color") {
    std::env::set_var("TERM", "xterm-256color");
} else {
    eprintln!("Warning: no suitable terminfo found");
}
```

--------------------------------

### Application Bootstrap with `Application::new`

Source: https://context7.com/raphamorim/rio/llms.txt

Initializes the main Rio application by loading configuration, building the event loop, and constructing the `Application` struct. This is the entry point for the application's main function.

```rust
use rio_backend::config::Config;
use rio_backend::event::EventPayload;
use rio_window::event_loop::EventLoop;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load config (fall back to defaults on error)
    let (mut config, config_error) = match Config::try_load() {
        Ok(c)  => (c, None),
        Err(e) => (Config::default(), Some(e)),
    };
    config.overwrite_based_on_platform();

    // 2. Build the event loop with a custom user-event type
    let event_loop =
        EventLoop::<EventPayload>::with_user_event().build()?;

    // 3. Construct the application (installs config watcher, initialises clipboard,
    //    sets up scheduler and notification permissions)
    let mut app = crate::application::Application::new(
        config,
        config_error,
        &event_loop,
        None,          // optional Wayland app_id / X11 WM_CLASS override
    );

    // 4. Run — blocks until all windows are closed
    app.run(event_loop)?;
    Ok(())
}
```

--------------------------------

### Application::new — Main Application Bootstrap

Source: https://context7.com/raphamorim/rio/llms.txt

Constructs the top-level `Application` struct, which ties together configuration, the event loop, window management, and scheduling.

```APIDOC
## `Application::new` — Main Application Bootstrap

`Application` is the top-level struct that ties together config, the windowing event loop, the router (window/tab manager), and the scheduler. It is constructed once in `main()` after config is loaded.

### Arguments

*   `config`: The loaded application configuration.
*   `config_error`: An optional error encountered during configuration loading.
*   `event_loop`: A reference to the application's event loop.
*   `wayland_app_id_or_wm_class_override`: An optional override for the Wayland app ID or X11 WM_CLASS.

### Returns

*   An instance of the `Application` struct.

### Usage Example

```rust
use rio_backend::config::Config;
use rio_backend::event::EventPayload;
use rio_window::event_loop::EventLoop;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load config (fall back to defaults on error)
    let (mut config, config_error) = match Config::try_load() {
        Ok(c)  => (c, None),
        Err(e) => (Config::default(), Some(e)),
    };
    config.overwrite_based_on_platform();

    // 2. Build the event loop with a custom user-event type
    let event_loop = 
        EventLoop::<EventPayload>::with_user_event().build()?;

    // 3. Construct the application (installs config watcher, initialises clipboard,
    //    sets up scheduler and notification permissions)
    let mut app = crate::application::Application::new(
        config,
        config_error,
        &event_loop,
        None,          // optional Wayland app_id / X11 WM_CLASS override
    );

    // 4. Run — blocks until all windows are closed
    app.run(event_loop)?;
    Ok(())
}
```
```

--------------------------------

### Configure Renderer Backend

Source: https://context7.com/raphamorim/rio/llms.txt

Select the GPU backend for rendering. Defaults vary by OS. Enable the 'wgpu' Cargo feature for librashader filters.

```toml
# config.toml — renderer section

# macOS: native Metal (default, no wgpu feature required)
[renderer]
backend = "Metal"

# Linux: native Vulkan (default, no wgpu feature required)
[renderer]
backend = "Vulkan"

# Windows / WASM: wgpu umbrella (wgpu feature is force-enabled on Windows)
[renderer]
backend = "Webgpu"

# Optional: CRT / scanline filter via librashader (requires wgpu feature)
[renderer]
backend = "Webgpu"
[[renderer.filters]]
name = "crt-royale"
path = "/usr/share/reshade/Shaders/crt-royale.slangp"

# Rendering strategy
# "Events" = vsync-paced, CPU-efficient (default)
# "Game"   = unlocked framerate (Poll mode), maximises FPS at cost of CPU
strategy = "Events"

disable-unfocused-render = true   # skip redraws when window loses focus
disable-occluded-render  = false  # skip redraws when window is fully hidden

```

--------------------------------

### Create PTY with Spawn and Fork Strategies

Source: https://context7.com/raphamorim/rio/llms.txt

Demonstrates creating pseudoterminals using both the preferred `create_pty_with_spawn` and legacy `create_pty_with_fork` methods. Includes writing to and reading from the PTY, and resizing the terminal. Requires `teletypewriter` crate.

```rust
use teletypewriter::{create_pty_with_spawn, create_pty_with_fork, WinsizeBuilder, ProcessReadWrite};
use std::io::{Read, Write};

// --- Spawn strategy (default on Linux/Windows, preferred on macOS) ---
let mut pty = create_pty_with_spawn(
    "/bin/bash",                       // shell program
    vec!["--login".to_string()],       // shell args
    &Some("/home/user/project".into()), // working directory
    220,                               // columns
    50,                                // rows
).expect("failed to create PTY");

// Write to the shell
pty.write_all(b"echo hello\n").unwrap();

// Read output
let mut buf = [0u8; 4096];
let n = pty.read(&mut buf).unwrap();
println!("{}", String::from_utf8_lossy(&buf[..n]));

// Resize the terminal
pty.set_winsize(WinsizeBuilder { rows: 60, cols: 240, width: 0, height: 0 }).unwrap();

// --- Fork strategy (used when use-fork = true in config) ---
let mut pty_fork = create_pty_with_fork("/bin/zsh", 200, 48)
    .expect("forkpty failed");

// Query child PID
println!("child pid: {}", *pty_fork.child.pid);
```

--------------------------------

### Build all man pages

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Build all man pages for the Rio terminal by navigating to the man directory and running make.

```bash
make -C extra/man
```

--------------------------------

### Initialize Sugarloaf Font Library

Source: https://context7.com/raphamorim/rio/llms.txt

Demonstrates the basic integration of the Sugarloaf GPU rendering engine by initializing its font library. Font settings like size are configured, and potential errors during font loading are handled.

```rust
// Minimal sugarloaf integration sketch (see sugarloaf/examples/ for full code)
use sugarloaf::font::fonts::SugarloafFonts;

// Font library is initialized from the fonts section of the config
let fonts = SugarloafFonts {
    size: 16.0,
    ..SugarloafFonts::default()
};

// FontLibrary::new returns (library, Option<FontLibraryError>)
let (font_library, font_errors) = sugarloaf::font::FontLibrary::new(fonts);
if let Some(err) = font_errors {
    eprintln!("Fonts not found: {:?}", err.fonts_not_found);
}
```

--------------------------------

### Create Default Rio Configuration File

Source: https://context7.com/raphamorim/rio/llms.txt

This function creates the default configuration file at the standard platform path or a specified custom path. If the configuration file already exists, this function does nothing. It's useful for initializing the configuration or when using the `--write-config` CLI flag.

```rust
use rio_backend::config::{create_config_file, config_file_path};
use std::path::PathBuf;

// Create at the default location (~/.config/rio/config.toml)
create_config_file(None);
println!("Config lives at: {}", config_file_path().display());

// Create at a custom path (useful for --write-config CLI flag)
create_config_file(Some(PathBuf::from("/tmp/my-rio-config.toml")));
```

--------------------------------

### Apply Platform-Specific Configuration Overrides

Source: https://context7.com/raphamorim/rio/llms.txt

This method merges platform-specific settings from the `[platform.<os>]` table into the main configuration. It's automatically called after loading the configuration. Note that the shell setting is fully replaced, while other fields like window, navigation, and renderer are merged individually. Environment variables are appended.

```rust
use rio_backend::config::Config;

let mut config = Config::load();
// Merges [platform.macos] / [platform.linux] / [platform.windows] into config
config.overwrite_based_on_platform();

// After merging, platform-specific env vars are appended:
// global: ["GLOBAL=1"]  +  macos: ["MACOS=1"]  =>  ["GLOBAL=1", "MACOS=1"]
assert!(config.env_vars.contains(&"GLOBAL=1".to_string()));
```

--------------------------------

### Build individual man pages

Source: https://github.com/raphamorim/rio/blob/main/extra/man/README.md

Build individual man pages using scdoc by redirecting the scdoc file output to the respective man file.

```bash
scdoc < extra/man/rio.1.scd > rio.1
```

```bash
scdoc < extra/man/rio.5.scd > rio.5
```

```bash
scdoc < extra/man/rio-bindings.5.scd > rio-bindings.5
```

--------------------------------

### Initialize Rio Terminal WASM

Source: https://github.com/raphamorim/rio/blob/main/frontends/wasm/index.html

Import and initialize the WebAssembly module for the Rio Terminal. This should be called once during application startup.

```javascript
import init from "./wasm/rioterm.js";

init()
  .then(() => {
    console.log("Rio terminal was loaded");
  })
  .catch(err => {
    console.log(err);
  });
```

--------------------------------

### Load Rio Configuration in Rust

Source: https://context7.com/raphamorim/rio/llms.txt

These Rust functions handle loading the Rio configuration. `create_config_file` writes defaults, `Config::load` falls back to defaults on error, and `Config::try_load` returns specific errors for handling.

```rust
use rio_backend::config::{Config, ConfigError, config_file_path, create_config_file};

// Write the default config to the standard path (creates parent directories)
create_config_file(None);

// Load config, falling back silently to defaults on error
let config: Config = Config::load();

// Load config and propagate errors (used by the application on hot-reload)
match Config::try_load() {
    Ok(config) => {
        println!("Shell: {} {:?}", config.shell.program, config.shell.args);
        println!("Theme: {}", config.theme);
        println!("Font size: {}", config.fonts.size);
        println!("Navigation mode: {}", config.navigation.mode);
    }
    Err(ConfigError::PathNotFound) => eprintln!("No config file found"),
    Err(ConfigError::ErrLoadingConfig(msg)) => eprintln!("Parse error: {msg}"),
    Err(ConfigError::ErrLoadingTheme(msg)) => eprintln!("Theme error: {msg}"),
}

// Apply per-OS platform overrides after loading
let mut config = Config::load();
config.overwrite_based_on_platform();
```

--------------------------------

### Define Custom Key Bindings

Source: https://context7.com/raphamorim/rio/llms.txt

Map keys to named actions or raw escape sequences. Supports modifier keys and mode guards like 'appcursor' or 'vi'.

```toml
[bindings]
keys = [
  # Named actions
  { key = "q",      with = "super",               action = "Quit" },
  { key = "t",      with = "super",               action = "CreateTab" },
  { key = "w",      with = "super",               action = "CloseTab" },
  { key = "d",      with = "super",               action = "SplitRight" },
  { key = "d",      with = "super | shift",        action = "SplitDown" },
  { key = "Return", with = "super | shift",        action = "ToggleFullScreen" },
  { key = "]",      with = "super | shift",        action = "SelectNextTab" },
  { key = "[",      with = "super | shift",        action = "SelectPrevTab" },

  # Raw escape sequences (e.g., fix Home/End in application-cursor mode)
  { key = "Home",   esc = "\x1bOH", mode = "appcursor" },
  { key = "End",    esc = "\x1bOF", mode = "appcursor" },
  { key = "Up",     esc = "\x1bOA", mode = "appcursor" },

  # Mode guard values: "appcursor" | "alt" | "vi" 
  { key = "k", with = "ctrl", esc = "\x1b[A", mode = "vi" },
]

```

--------------------------------

### Run WASM Tests with wasm-bindgen

Source: https://github.com/raphamorim/rio/blob/main/sugarloaf/README.md

Executes WebAssembly tests for the sugarloaf crate using the wasm-bindgen test runner harness. This command is run from the root sugarloaf directory.

```bash
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner cargo test --target wasm32-unknown-unknown -p sugarloaf --tests
```

--------------------------------

### Rio Configuration File TOML Structure

Source: https://context7.com/raphamorim/rio/llms.txt

This TOML file defines the configuration for the Rio terminal. All sections are optional, and defaults are applied when omitted. Refer to the official documentation for a full reference.

```toml
# ~/.config/rio/config.toml
# Full reference: https://rioterm.com/docs/config

# ── General ──────────────────────────────────────────────────────────────────
theme = "lucario"                   # name under <config-dir>/themes/*.toml
confirm-before-quit = true
copy-on-select = false
hide-mouse-cursor-when-typing = false
draw-bold-text-with-light-colors = false
option-as-alt = "none"             # "left" | "right" | "both" | "none"
line-height = 1.0
scrollback-history-limit = 10000   # 0 = disabled
env-vars = ["EDITOR=nvim", "TERM=xterm-256color"]
working-dir = "/home/user"

# ── Shell ─────────────────────────────────────────────────────────────────────
[shell]
program = "/bin/fish"
args = ["--login"]

# ── Window ────────────────────────────────────────────────────────────────────
[window]
width = 1200
height = 800
mode = "Windowed"       # "Windowed" | "Maximized" | "Fullscreen"
opacity = 0.95
blur = true             # compositor blur behind transparent windows
decorations = "Transparent"   # "Enabled" | "Disabled" | "Transparent" | "Buttonless"
colorspace = "srgb"    # "srgb" | "display-p3" | "rec2020"

[window.background-image]
path = "/home/user/wallpaper.png"
opacity = 0.15
x = 0.0
y = 0.0

```

--------------------------------

### Configure Navigation Modes

Source: https://context7.com/raphamorim/rio/llms.txt

Set the navigation mode for tabs and splits. 'Tab' is the default and draws its own UI. 'NativeTab' uses macOS native tabs. 'Plain' offers no navigation UI.

```toml
# Tab mode (default on all platforms): Rio draws its own tab bar using GPU
[navigation]
mode = "Tab"
use-split = true
clickable  = true
hide-if-single = true          # hide tab bar when only one tab is open
current-working-directory = true  # new tabs inherit the current pane's cwd
use-terminal-title = true
unfocused-split-opacity = 0.7  # dim inactive split panes (0.15–1.0)
unfocused-split-fill    = "#1e1e2e"  # optional solid fill for inactive panes
open-config-with-split  = false      # open config editor in a split instead of new window

# NativeTab (macOS only): use macOS's native tab bar
[navigation]
mode = "NativeTab"

# Plain: no tab bar, no navigation UI; single pane per window
[navigation]
mode = "Plain"

# Color automation: tint tab indicators based on running program or cwd
[[navigation.color-automation]]
program = "nvim"
color   = "#bd93f9"

[[navigation.color-automation]]
path  = "/home/user/projects"
color = "#50fa7b"

```

--------------------------------

### teletypewriter — PTY Creation

Source: https://context7.com/raphamorim/rio/llms.txt

Provides cross-platform pseudoterminal abstraction. Supports creating PTYs using a spawn strategy (preferred) or a legacy fork strategy.

```APIDOC
## `teletypewriter` — PTY Creation

This module provides cross-platform pseudoterminal (PTY) abstraction. It wraps `openpty`/`forkpty` on Unix and ConPTY on Windows.

### Functions

*   **`create_pty_with_spawn`**: Preferred method for creating a PTY. It uses `Command::spawn` for process creation.
    *   **Arguments**:
        *   `shell_program`: The path to the shell executable.
        *   `shell_args`: A vector of arguments for the shell.
        *   `working_directory`: An optional path for the working directory.
        *   `columns`: The initial number of columns for the PTY.
        *   `rows`: The initial number of rows for the PTY.
    *   **Returns**:
        A `Result` containing a PTY handler or an error.

*   **`create_pty_with_fork`**: Legacy method for creating a PTY using `forkpty`.
    *   **Arguments**:
        *   `shell_program`: The path to the shell executable.
        *   `columns`: The initial number of columns for the PTY.
        *   `rows`: The initial number of rows for the PTY.
    *   **Returns**:
        A `Result` containing a PTY handler or an error.

### Usage Example

```rust
use teletypewriter::{create_pty_with_spawn, create_pty_with_fork, WinsizeBuilder, ProcessReadWrite};
use std::io::{Read, Write};

// --- Spawn strategy ---
let mut pty = create_pty_with_spawn(
    "/bin/bash",                       // shell program
    vec!["--login".to_string()],       // shell args
    &Some("/home/user/project".into()), // working directory
    220,                               // columns
    50,                                // rows
).expect("failed to create PTY");

// Write to the shell
pty.write_all(b"echo hello\n").unwrap();

// Read output
let mut buf = [0u8; 4096];
let n = pty.read(&mut buf).unwrap();
println!("{}", String::from_utf8_lossy(&buf[..n]));

// Resize the terminal
pty.set_winsize(WinsizeBuilder { rows: 60, cols: 240, width: 0, height: 0 }).unwrap();

// --- Fork strategy ---
let mut pty_fork = create_pty_with_fork("/bin/zsh", 200, 48)
    .expect("forkpty failed");

// Query child PID
println!("child pid: {}", *pty_fork.child.pid);
```
```

--------------------------------

### Define Theme Colors

Source: https://context7.com/raphamorim/rio/llms.txt

Specify color overrides for the terminal's appearance in a theme file. Supports static and adaptive themes based on OS appearance.

```toml
# ~/.config/rio/themes/dracula.toml
[colors]
background       = "#282A36"
foreground       = "#F8F8F2"
cursor           = "#F8F8F2"
tabs-active      = "#BD93F9"
selection-background = "#44475A"
selection-foreground = "#F8F8F2"
black   = "#000000"
red     = "#FF5555"
green   = "#50FA7B"
yellow  = "#F1FA8C"
blue    = "#BD93F9"
magenta = "#FF79C6"
cyan    = "#8BE9FD"
white   = "#BFBFBF"

# Activate a static theme
# config.toml:
# theme = "dracula"

# Adaptive theme — switches with system dark/light appearance
# config.toml:
# [adaptive-theme]
# dark  = "dracula"
# light = "gruvbox-light"

```

--------------------------------

### Add Sugarloaf GPU Rendering Engine Dependency

Source: https://context7.com/raphamorim/rio/llms.txt

Specifies the `sugarloaf` crate as a dependency in `Cargo.toml` for GPU-accelerated rendering. The `render` feature is required, and the `wgpu` feature can be enabled for librashader filters and broader platform support (Windows/WASM).

```toml
# Cargo.toml
[dependencies]
sugarloaf = { version = "0.4.3", features = ["render"] }
# Add "wgpu" feature for librashader filters and Windows/WASM support
# sugarloaf = { version = "0.4.3", features = ["render", "wgpu"] }
```

--------------------------------

### Color Conversion Enums

Source: https://github.com/raphamorim/rio/blob/main/rio-backend/src/config/colors/README.md

Defines enums for different color formats used in conversions.

```rust
pub enum Format {
    SRGB0_255,
    SRGB0_1,
}
```

--------------------------------

### RioEvent — Internal Event System

Source: https://context7.com/raphamorim/rio/llms.txt

Defines the internal event system used by Rio, routing terminal and application events through `RioEvent` and `EventPayload`.

```APIDOC
## `RioEvent` — Internal Event System

All terminal and application events are routed through `RioEvent` (wrapped in `EventPayload`) and dispatched by `ApplicationHandler::user_event`. Key variants cover rendering, config reload, clipboard, PTY I/O, tab/window lifecycle, and cursor blinking.

### Event Variants

*   **`RioEvent::Render`**: Repaint the focused window.
*   **`RioEvent::UpdateConfig`**: Hot-reload configuration from disk.
*   **`RioEvent::ClipboardStore(t, s)`**: Write `s` to clipboard type `t`.
*   **`RioEvent::ClipboardLoad(id, t, f)`**: Read clipboard and send escape via `f`.
*   **`RioEvent::PtyWrite(id, text)`**: Write bytes to the PTY of route `id`.
*   **`RioEvent::CreateWindow`**: Open a new window.
*   **`RioEvent::CloseTerminal(id)`**: Close a split pane or tab.
*   **`RioEvent::Bell`**: Ring the audio bell (if configured).
*   **`RioEvent::DesktopNotification{title, body}`**: Display a system notification.
*   **`RioEvent::ToggleFullScreen`**: Toggle borderless fullscreen mode.
*   **`RioEvent::Title(t)`**: Update the window title bar to `t`.

### Usage Example (Sending an Event)

```rust
use rio_backend::event::{EventPayload, RioEvent, RioEventType};
use rio_window::window::WindowId;

// Events are sent via EventProxy (wraps winit's EventLoopProxy)
// Example: triggering a config reload from another thread
let proxy: rio_window::event_loop::EventLoopProxy<EventPayload> = /* … */;

proxy.send_event(
    EventPayload::new(
        RioEventType::Rio(RioEvent::PrepareUpdateConfig),
        unsafe { WindowId::dummy() },
    )
).ok();
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.