### MSRV Calculation Example

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/readme.md

This text block illustrates how the Minimum Supported Rust Version (MSRV) is determined by referencing the MSRVs of downstream users like 'delta' and 'bat'.

```text
min(msrv(bat), msrv(delta))
```

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

### Query Terminal Foreground Color

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Use `foreground_color` to get the terminal's foreground (text) color as a `Color` struct with 16-bit RGB channels. It can be scaled to 8-bit.

```rust
use terminal_colorsaurus::{foreground_color, QueryOptions};

fn main() {
    let fg = foreground_color(QueryOptions::default()).unwrap();

    // Access 16-bit channels directly
    println!("rgb16({}, {}, {})", fg.r, fg.g, fg.b);

    // Scale down to 8-bit per channel
    let (r8, g8, b8) = fg.scale_to_8bit();
    println!("rgb8({r8}, {g8}, {b8})");
    // Example output:
    // rgb16(56797, 58339, 58339)
    // rgb8(218, 224, 224)
```

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

### Run Terminal Benchmark

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/doc/latency.md

Execute the benchmark tool to measure terminal latency. Replace '<TERM_NAME>' with the specific terminal emulator you wish to test.

```shell
cargo run --release -p benchmark '<TERM_NAME>'
```

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

### Test Terminal for Background Color Support

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/doc/terminal-survey.md

Use this command to test for background color support. The output will show the background color information if supported.

```shell
printf '\e]11;?\e\' && cat -v # Tests for background color support. Example output: ^[]11;rgb:ffff/ffff/ffff^[ 
```

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

### Handle Query Errors Gracefully

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Demonstrates how to match on the `Error` enum variants to handle different failure modes like unsupported terminals, timeouts, I/O errors, and parse failures. It falls back to a default theme when errors occur.

```rust
use std::time::Duration;
use terminal_colorsaurus::{theme_mode, Error, QueryOptions, ThemeMode};

fn detect_theme_with_fallback() -> ThemeMode {
    let options = QueryOptions {
        timeout: Duration::from_millis(500),
    };

    match theme_mode(options) {
        Ok(mode) => mode,
        Err(Error::UnsupportedTerminal(_)) => {
            eprintln!("Terminal does not support color queries; defaulting to Dark.");
            ThemeMode::Dark
        }
        Err(Error::Timeout(duration)) => {
            eprintln!("Query timed out after {:?}; defaulting to Dark.", duration);
            ThemeMode::Dark
        }
        Err(Error::Io(e)) => {
            eprintln!("I/O error: {:?}; defaulting to Dark.", e);
            ThemeMode::Dark
        }
        Err(Error::Parse(bytes)) => {
            eprintln!("Unexpected terminal response: {:?}; defaulting to Dark.", bytes);
            ThemeMode::Dark
        }
        Err(_) => ThemeMode::Dark, // future variants (non_exhaustive)
    }
}

fn main() {
    let theme = detect_theme_with_fallback();
    println!("Using theme: {:?}", theme);
}
```

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

### Test Terminal Background Color Support

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/crates/terminal-colorsaurus/doc/terminal-survey.md

Use this command to test the terminal's background color support. The output format varies by terminal.

```shell
printf '\e]11;?\e\' && cat -v # Tests for background color support. Example output: ^[]11;rgb:ffff/ffff/ffff^[

```

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

### Test Terminal for Foreground Color Support

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/doc/terminal-survey.md

This command tests for foreground color support by querying the terminal. The output format depends on the terminal's implementation.

```shell
printf '\e]10;?\e\' && cat -v # Tests for foreground color support. Example output: ^[]10;rgb:0000/0000/0000^[
```

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

### QueryOptions - Configure Query Timeout

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `QueryOptions` struct allows configuration of terminal queries, with the `timeout` field being the primary option. It defaults to 1 second and can be increased for high-latency connections like SSH.

```APIDOC
## `QueryOptions` — Configure Query Timeout

The `QueryOptions` struct configures the terminal query. The only current option is `timeout`, defaulting to 1 second. Use a longer timeout when operating over SSH or other high-latency connections.

```rust
use std::time::Duration;
use terminal_colorsaurus::{theme_mode, QueryOptions};

fn main() {
    // Use a 3-second timeout for SSH sessions
    let options = QueryOptions {
        timeout: Duration::from_secs(3),
    };

    match theme_mode(options) {
        Ok(mode) => println!("Mode: {mode:?}"),
        Err(e) => eprintln!("Error: {e}"),
    }
}
```
```

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

### Color - Optional Conversions (rgb and anstyle features)

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

When the `rgb` and `anstyle` Cargo features are enabled, the `Color` struct supports conversions to and from types provided by the `rgb` and `anstyle` crates, facilitating interoperability.

```APIDOC
## `Color` — Optional Conversions (`rgb` and `anstyle` features)

With optional Cargo features enabled, `Color` can be converted to and from types from the `rgb` and `anstyle` crates.

```toml
[dependencies]
terminal-colorsaurus = { version = "1.0.3", features = ["rgb", "anstyle"] }
```

```rust
use terminal_colorsaurus::{background_color, QueryOptions, Color};

fn main() {
    let bg = background_color(QueryOptions::default()).unwrap();

    // Convert to rgb::RGB8 (8-bit, from `rgb` crate)
    let rgb8: rgb::RGB8 = bg.clone().into();
    println!("rgb::RGB8 {{ r: {}, g: {}, b: {} }}", rgb8.r, rgb8.g, rgb8.b);

    // Convert to rgb::RGB16 (16-bit, from `rgb` crate)
    let rgb16: rgb::RGB16 = bg.clone().into();
    println!("rgb::RGB16 {{ r: {}, g: {}, b: {} }}", rgb16.r, rgb16.g, rgb16.b);

    // Convert to anstyle::RgbColor (8-bit, from `anstyle` crate)
    let anstyle_color: anstyle::RgbColor = bg.into();
    println!("anstyle::RgbColor({}, {}, {})", anstyle_color.0, anstyle_color.1, anstyle_color.2);
}
```
```

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

### Configure Query Timeout with QueryOptions

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Use `QueryOptions` to set a custom timeout for terminal queries. Increase the timeout for high-latency connections like SSH. Defaults to 1 second.

```rust
use std::time::Duration;
use terminal_colorsaurus::{theme_mode, QueryOptions};

fn main() {
    // Use a 3-second timeout for SSH sessions
    let options = QueryOptions {
        timeout: Duration::from_secs(3),
    };

    match theme_mode(options) {
        Ok(mode) => println!("Mode: {mode:?}"),
        Err(e) => eprintln!("Error: {e}"),
    }
}
```

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

### Parse X11 Color String in Rust

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/crates/xterm-color/readme.md

Demonstrates parsing an 'rgb:R/G/B' formatted color string using the `Color::parse` method. Ensure the input is a valid byte slice representing the color string.

```rust
use xterm_color::Color;
let color = Color::parse(b"rgb:11/aa/ff").unwrap();
assert_eq!(color, Color::rgb(0x1111, 0xaaaa, 0xffff));
```

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

### Test Terminal Foreground Color Support

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/crates/terminal-colorsaurus/doc/terminal-survey.md

This command queries the terminal for its foreground color support. The output format depends on the terminal's implementation.

```shell
printf '\e]10;?\e\' && cat -v # Tests for foreground color support. Example output: ^[]10;rgb:0000/0000/0000^[

```

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

### color_palette — Query Full Color Palette

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Queries the terminal for both foreground and background colors efficiently in a single round-trip. Returns a `ColorPalette` struct containing both `Color` values. This is more performant than calling `foreground_color` and `background_color` separately.

```APIDOC
## color_palette

### Description
Queries the terminal for its foreground and background colors simultaneously using a single round-trip. Returns a `ColorPalette` which contains both `Color` values. This method is more efficient than querying foreground and background colors separately.

### Function Signature
`fn color_palette(options: QueryOptions) -> Result<ColorPalette, Error>`

### Parameters
#### QueryOptions
- `QueryOptions::default()`: Uses default query options, including a 1-second timeout.

### Return Value
- `Ok(ColorPalette)`: A struct containing `foreground` and `background` `Color` values.
- `Err(Error)`: If color querying is not supported, times out, or an I/O error occurs.

### Request Example
```rust
use terminal_colorsaurus::{color_palette, QueryOptions, ThemeMode};

fn main() {
    let palette = color_palette(QueryOptions::default()).unwrap();

    let theme = match palette.theme_mode() {
        ThemeMode::Dark => "dark",
        ThemeMode::Light => "light",
    };

    println!(
        "Theme: {theme}, fg lightness: {:.3}, bg lightness: {:.3}",
        palette.foreground.perceived_lightness(),
        palette.background.perceived_lightness(),
    );
}
```

### Response Example
```
Theme: dark, fg lightness: 0.878, bg lightness: 0.012
```
```

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

### Determine Terminal Theme Mode

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/readme.md

Use this snippet to query the terminal's theme mode. It returns `ThemeMode::Dark` or `ThemeMode::Light`. Ensure `QueryOptions::default()` is used for standard behavior.

```rust
use terminal_colorsaurus::{theme_mode, QueryOptions, ThemeMode};

match theme_mode(QueryOptions::default()).unwrap() {
    ThemeMode::Dark => { /* ... */ },
    ThemeMode::Light => { /* ... */ },
}
```

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

### Optional Color Conversions with rgb and anstyle Features

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

When the `rgb` and `anstyle` Cargo features are enabled, the `Color` struct can be converted to and from types provided by these crates, facilitating interoperability.

```toml
[dependencies]
terminal-colorsaurus = { version = "1.0.3", features = ["rgb", "anstyle"] }
```

```rust
use terminal_colorsaurus::{background_color, QueryOptions, Color};

fn main() {
    let bg = background_color(QueryOptions::default()).unwrap();

    // Convert to rgb::RGB8 (8-bit, from `rgb` crate)
    let rgb8: rgb::RGB8 = bg.clone().into();
    println!("rgb::RGB8 {{ r: {}, g: {}, b: {} }}", rgb8.r, rgb8.g, rgb8.b);

    // Convert to rgb::RGB16 (16-bit, from `rgb` crate)
    let rgb16: rgb::RGB16 = bg.clone().into();
    println!("rgb::RGB16 {{ r: {}, g: {}, b: {} }}", rgb16.r, rgb16.g, rgb16.b);

    // Convert to anstyle::RgbColor (8-bit, from `anstyle` crate)
    let anstyle_color: anstyle::RgbColor = bg.into();
    println!("anstyle::RgbColor({}, {}, {})", anstyle_color.0, anstyle_color.1, anstyle_color.2);
}
```

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

### Test Terminal Device Attributes (DA1)

Source: https://github.com/tautropfli/terminal-colorsaurus/blob/main/crates/terminal-colorsaurus/doc/terminal-survey.md

Use this command to test for DA1. The output indicates the terminal's capabilities.

```shell
printf '\e[c' && cat -v # Tests for DA1. Example output: ^[[?65;1;9c
```

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

### Query Full Terminal Color Palette

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `color_palette` function queries both foreground and background colors efficiently in a single round-trip. It returns a `ColorPalette` struct.

```rust
use terminal_colorsaurus::{color_palette, QueryOptions, ThemeMode};

fn main() {
    let palette = color_palette(QueryOptions::default()).unwrap();

    let theme = match palette.theme_mode() {
        ThemeMode::Dark => "dark",
        ThemeMode::Light => "light",
    };

    println!(
        "Theme: {theme}, fg lightness: {:.3}, bg lightness: {:.3}",
        palette.foreground.perceived_lightness(),
        palette.background.perceived_lightness(),
    );
    // Example output: "Theme: dark, fg lightness: 0.878, bg lightness: 0.012"
```

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

### Add Terminal Colorsaurus Dependency

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Add the terminal-colorsaurus crate to your Cargo.toml file. Optional features like 'rgb' and 'anstyle' can be enabled for type conversions.

```toml
[dependencies]
terminal-colorsaurus = "1.0.3"

# Optional: enable conversions to `rgb` and `anstyle` types
# terminal-colorsaurus = { version = "1.0.3", features = ["rgb", "anstyle"] }
```

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

### Derive Terminal Theme Mode from ColorPalette

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `ColorPalette::theme_mode()` method determines if the terminal is in dark or light mode by comparing the perceived lightness of foreground and background colors. It defaults to `Dark` for ambiguous color combinations.

```rust
use terminal_colorsaurus::{Color, ColorPalette, ThemeMode};

fn main() {
    // Simulate a dark terminal: white-on-black
    let dark_palette = ColorPalette {
        foreground: Color::rgb(u16::MAX, u16::MAX, u16::MAX), // white
        background: Color::rgb(0, 0, 0),                      // black
    };
    assert_eq!(dark_palette.theme_mode(), ThemeMode::Dark);

    // Simulate a light terminal: black-on-white
    let light_palette = ColorPalette {
        foreground: Color::rgb(0, 0, 0),                      // black
        background: Color::rgb(u16::MAX, u16::MAX, u16::MAX), // white
    };
    assert_eq!(light_palette.theme_mode(), ThemeMode::Light);

    println!("Dark palette: {:?}", dark_palette.theme_mode()); // Dark
    println!("Light palette: {:?}", light_palette.theme_mode()); // Light
}
```

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

### ColorPalette::theme_mode - Derive Theme from Palette

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `ColorPalette::theme_mode()` method determines if the terminal is in dark or light mode by comparing the perceptual lightness of the foreground and background colors. It defaults to `Dark` for ambiguous cases.

```APIDOC
## `ColorPalette::theme_mode` — Derive Theme from Palette

The `ColorPalette::theme_mode()` method compares the perceptual lightness of foreground and background to determine whether the terminal is in dark or light mode. When colors are ambiguous (e.g. same color for fg and bg), it defaults to `Dark`.

```rust
use terminal_colorsaurus::{Color, ColorPalette, ThemeMode};

fn main() {
    // Simulate a dark terminal: white-on-black
    let dark_palette = ColorPalette {
        foreground: Color::rgb(u16::MAX, u16::MAX, u16::MAX), // white
        background: Color::rgb(0, 0, 0),                      // black
    };
    assert_eq!(dark_palette.theme_mode(), ThemeMode::Dark);

    // Simulate a light terminal: black-on-white
    let light_palette = ColorPalette {
        foreground: Color::rgb(0, 0, 0),                      // black
        background: Color::rgb(u16::MAX, u16::MAX, u16::MAX), // white
    };
    assert_eq!(light_palette.theme_mode(), ThemeMode::Light);

    println!("Dark palette: {:?}", dark_palette.theme_mode()); // Dark
    println!("Light palette: {:?}", light_palette.theme_mode()); // Light
}
```
```

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

### Color - RGB Color with 16-bit Channels

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `Color` struct represents an RGB color with 16-bit precision per channel. It provides methods for calculating perceived lightness (CIE L*) and scaling to standard 8-bit color tuples.

```APIDOC
## `Color` — RGB Color with 16-bit Channels

The `Color` struct holds a terminal color with 16-bit precision per channel. Provides `perceived_lightness()` for perceptual luminance (CIE L*) and `scale_to_8bit()` for converting to standard 8-bit color tuples.

```rust
use terminal_colorsaurus::Color;

fn main() {
    let white = Color::rgb(u16::MAX, u16::MAX, u16::MAX);
    let black = Color::rgb(0, 0, 0);
    let mid_gray = Color::rgb(0x8000, 0x8000, 0x8000);

    assert_eq!(white.perceived_lightness(), 1.0);
    assert_eq!(black.perceived_lightness(), 0.0);
    assert_eq!(white.scale_to_8bit(), (255, 255, 255));
    assert_eq!(black.scale_to_8bit(), (0, 0, 0));

    println!("Mid-gray lightness: {:.3}", mid_gray.perceived_lightness());
    // Output: "Mid-gray lightness: 0.216"

    let is_dark = mid_gray.perceived_lightness() <= 0.5;
    println!("Is dark: {is_dark}"); // Output: "Is dark: true"
}
```
```

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

### Query Terminal Background Color

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `background_color` function queries the terminal's background color using `OSC 11`. It returns a `Color` struct and allows checking perceived lightness.

```rust
use terminal_colorsaurus::{background_color, QueryOptions};

fn main() {
    let bg = background_color(QueryOptions::default()).unwrap();

    let (r, g, b) = bg.scale_to_8bit();
    println!("Background: #{r:02x}{g:02x}{b:02x}");
    // Example output: "Background: #1e1e2e"

    // Check if background is dark
    if bg.perceived_lightness() < 0.5 {
        println!("Dark background detected.");
    }
}
```

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

### Parse X11 Color Strings

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Parses X11 color strings from terminals using various formats like `rgb:`, `rgba:`, and `#`-prefixed hex. Returns a 16-bit RGBA `Color` struct. Handles parsing errors.

```rust
use xterm_color::Color;

fn main() {
    // rgb: format — values are scaled per channel width
    let c1 = Color::parse(b"rgb:11/aa/ff").unwrap();
    assert_eq!(c1, Color::rgb(0x1111, 0xaaaa, 0xffff));

    // Short hex # format — values are shifted (MSB-aligned)
    let c2 = Color::parse(b"#1af").unwrap();
    assert_eq!(c2, Color::rgb(0x1000, 0xa000, 0xf000));

    // Full 12-digit hex # format
    let c3 = Color::parse(b"#1100aa00ff00").unwrap();
    assert_eq!(c3, Color::rgb(0x1100, 0xaa00, 0xff00));

    // rgba: format (rxvt-unicode extension)
    let c4 = Color::parse(b"rgba:0000/0000/4443/cccc").unwrap();
    assert_eq!(c4.alpha, 0xcccc);

    // Perceptual lightness of parsed color
    println!("Lightness of #1af: {:.3}", c2.perceived_lightness());
    // Output: "Lightness of #1af: 0.034"

    // Error case
    assert!(Color::parse(b"rgb:f/f").is_err()); // Only 2 channels
}
```

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

### background_color — Query Terminal Background Color

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Queries the terminal specifically for its background color using the `OSC 11` escape sequence. Returns a `Color` struct with 16-bit `r`, `g`, and `b` fields, and provides methods to check its perceived lightness.

```APIDOC
## background_color

### Description
Queries the terminal for its background color using the `OSC 11` escape sequence. Returns a `Color` object containing 16-bit `r`, `g`, and `b` channels, and allows checking its perceived lightness.

### Function Signature
`fn background_color(options: QueryOptions) -> Result<Color, Error>`

### Parameters
#### QueryOptions
- `QueryOptions::default()`: Uses default query options, including a 1-second timeout.

### Return Value
- `Ok(Color)`: A `Color` struct with `r`, `g`, `b` fields (16-bit).
- `Err(Error)`: If color querying is not supported, times out, or an I/O error occurs.

### Request Example
```rust
use terminal_colorsaurus::{background_color, QueryOptions};

fn main() {
    let bg = background_color(QueryOptions::default()).unwrap();

    let (r, g, b) = bg.scale_to_8bit();
    println!("Background: #{r:02x}{g:02x}{b:02x}");

    // Check if background is dark
    if bg.perceived_lightness() < 0.5 {
        println!("Dark background detected.");
    }
}
```

### Response Example
```
Background: #1e1e2e
Dark background detected.
```
```

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

### Detect Dark or Light Terminal Theme Mode

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Use the `theme_mode` function to determine if the terminal uses a dark or light theme. It returns `ThemeMode::Dark` or `ThemeMode::Light`. Returns `Err` on failure.

```rust
use terminal_colorsaurus::{theme_mode, QueryOptions, ThemeMode};

fn main() {
    match theme_mode(QueryOptions::default()) {
        Ok(ThemeMode::Dark) => {
            println!("Terminal uses a dark theme — use light-colored output.");
        }
        Ok(ThemeMode::Light) => {
            println!("Terminal uses a light theme — use dark-colored output.");
        }
        Err(e) => {
            eprintln!("Could not detect theme: {e}");
            // Fallback: assume dark theme
        }
    }
}
// Example output: "Terminal uses a dark theme — use light-colored output."
```

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

### Color Struct: RGB Color with 16-bit Channels

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The `Color` struct represents an RGB color with 16-bit precision per channel. It provides methods for calculating perceived lightness and scaling to 8-bit color tuples.

```rust
use terminal_colorsaurus::Color;

fn main() {
    let white = Color::rgb(u16::MAX, u16::MAX, u16::MAX);
    let black = Color::rgb(0, 0, 0);
    let mid_gray = Color::rgb(0x8000, 0x8000, 0x8000);

    assert_eq!(white.perceived_lightness(), 1.0);
    assert_eq!(black.perceived_lightness(), 0.0);
    assert_eq!(white.scale_to_8bit(), (255, 255, 255));
    assert_eq!(black.scale_to_8bit(), (0, 0, 0));

    println!("Mid-gray lightness: {:.3}", mid_gray.perceived_lightness());
    // Output: "Mid-gray lightness: 0.216"

    let is_dark = mid_gray.perceived_lightness() <= 0.5;
    println!("Is dark: {is_dark}"); // Output: "Is dark: true"
}
```

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

### theme_mode — Detect Dark or Light Terminal

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

The primary high-level function to determine if the terminal uses a dark or light theme. It returns `ThemeMode::Dark` or `ThemeMode::Light`. An error is returned if the terminal does not support color querying, times out, or an I/O error occurs.

```APIDOC
## theme_mode

### Description
Detects whether the terminal uses a dark or light theme based on its background and foreground colors. Returns `ThemeMode::Dark` or `ThemeMode::Light`. Returns `Err` if the terminal does not support color querying, times out, or an I/O error occurs.

### Function Signature
`fn theme_mode(options: QueryOptions) -> Result<ThemeMode, Error>`

### Parameters
#### QueryOptions
- `QueryOptions::default()`: Uses default query options, including a 1-second timeout.

### Return Value
- `Ok(ThemeMode)`: `ThemeMode::Dark` or `ThemeMode::Light`.
- `Err(Error)`: If color querying is not supported, times out, or an I/O error occurs.

### Request Example
```rust
use terminal_colorsaurus::{theme_mode, QueryOptions, ThemeMode};

fn main() {
    match theme_mode(QueryOptions::default()) {
        Ok(ThemeMode::Dark) => {
            println!("Terminal uses a dark theme — use light-colored output.");
        }
        Ok(ThemeMode::Light) => {
            println!("Terminal uses a light theme — use dark-colored output.");
        }
        Err(e) => {
            eprintln!("Could not detect theme: {e}");
            // Fallback: assume dark theme
        }
    }
}
```

### Response Example
```
Terminal uses a dark theme — use light-colored output.
```
```

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

### foreground_color — Query Terminal Foreground Color

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Queries the terminal specifically for its foreground (text) color using the `OSC 10` escape sequence. Returns a `Color` struct with 16-bit `r`, `g`, and `b` fields, which can be scaled to 8-bit.

```APIDOC
## foreground_color

### Description
Queries the terminal for its foreground (text) color using the `OSC 10` escape sequence. Returns a `Color` object containing 16-bit `r`, `g`, and `b` channels.

### Function Signature
`fn foreground_color(options: QueryOptions) -> Result<Color, Error>`

### Parameters
#### QueryOptions
- `QueryOptions::default()`: Uses default query options, including a 1-second timeout.

### Return Value
- `Ok(Color)`: A `Color` struct with `r`, `g`, `b` fields (16-bit).
- `Err(Error)`: If color querying is not supported, times out, or an I/O error occurs.

### Request Example
```rust
use terminal_colorsaurus::{foreground_color, QueryOptions};

fn main() {
    let fg = foreground_color(QueryOptions::default()).unwrap();

    // Access 16-bit channels directly
    println!("rgb16({}, {}, {})", fg.r, fg.g, fg.b);

    // Scale down to 8-bit per channel
    let (r8, g8, b8) = fg.scale_to_8bit();
    println!("rgb8({r8}, {g8}, {b8})");
}
```

### Response Example
```
rgb16(56797, 58339, 58339)
rgb8(218, 224, 224)
```
```

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

### Avoid Pager Race Conditions

Source: https://context7.com/tautropfli/terminal-colorsaurus/llms.txt

Checks if stdout is a terminal using `stdout().is_terminal()` before querying the terminal theme. This prevents race conditions when output is piped to a pager like `less`.

```rust
use std::io::{stdout, IsTerminal as _};
use terminal_colorsaurus::{theme_mode, QueryOptions, ThemeMode};

fn main() {
    if stdout().is_terminal() {
        match theme_mode(QueryOptions::default()) {
            Ok(mode) => eprintln!("Theme mode: {:?}", mode),
            Err(e) => eprintln!("Error: {:?}", e),
        }
    } else {
        // Output is piped — skip terminal query to avoid race condition with pager
        eprintln!("Stdout is not a terminal; skipping theme detection.");
    }
}
// Run as: cargo run | less  → "Stdout is not a terminal; skipping theme detection."
// Run as: cargo run         → "Theme mode: Dark"
```

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