feat: parse palettes with ANSI OSC 4 codes

Screenshot parsing is still supported but is only attempted if the OSC
method fails.

Thanks to shiomiru on Hacker News for suggesting this:
https://news.ycombinator.com/item?id=44270561

Relates to: #99, #107

Author: tombh

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 name = "tattoy"
 description = "Eye-candy for your terminal"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 readme = "README.md"
 repository = "https://github.com/tombh/tattoy"

crates/tattoy/Cargo.toml

@@ -23,7 +23,8 @@ pub(crate) struct CliArgs {
     #[arg(long)]
     pub command: Option<String>,
 
-    /// Use image capture to detect the true colour values of the terminal's palette.
+    /// Capture the true color values of the terminal's palette. First tries using ANSI CSI queries
+    /// and if that fails resorts to parsing a screenshot of the palette (with user's consent).
     #[arg(long)]
     pub capture_palette: bool,
 

crates/tattoy/src/cli_args.rs

@@ -405,7 +405,7 @@ impl Config {
     pub async fn load_palette(
         state: std::sync::Arc<crate::shared_state::SharedState>,
     ) -> Result<crate::palette::converter::Palette> {
-        let path = crate::palette::parser::Parser::palette_config_path(&state).await;
+        let path = crate::palette::main::palette_config_path(&state).await;
         if !path.exists() {
             color_eyre::eyre::bail!(
                 "Terminal palette colours config file not found at: {}",
@@ -415,7 +415,7 @@ impl Config {
 
         tracing::info!("Loading the terminal palette's true colours from config");
         let data = tokio::fs::read_to_string(path).await?;
-        let map = toml::from_str::<crate::palette::converter::PaletteHashMap>(&data)?;
+        let map = toml::from_str::<crate::palette::main::PaletteHashMap>(&data)?;
         let palette = crate::palette::converter::Palette { map };
         Ok(palette)
     }

crates/tattoy/src/config/main.rs

@@ -17,6 +17,8 @@ pub mod raw_input;
 /// The palette code is for helping convert a terminal's palette to true colour.
 pub mod palette {
     pub mod converter;
+    pub mod main;
+    pub mod osc;
     pub mod parser;
     pub mod state_machine;
 }

crates/tattoy/src/main.rs

@@ -6,17 +6,11 @@ use color_eyre::{eyre::ContextCompat as _, Result};
 /// the palette when no other index or true colour is specified.
 const DEFAULT_TEXT_PALETTE_INDEX: u8 = 15;
 
-/// A single palette colour.
-type PaletteColour = (u8, u8, u8);
-
-/// A hash of palette indexes to true colour values.
-pub type PaletteHashMap = std::collections::HashMap<String, PaletteColour>;
-
 /// Convenience type for the palette hash.
 #[derive(Clone)]
 pub(crate) struct Palette {
     /// The palette hash.
-    pub map: PaletteHashMap,
+    pub map: super::main::PaletteHashMap,
 }
 
 impl Palette {

crates/tattoy/src/palette/converter.rs

@@ -0,0 +1,67 @@
+//! Get the true colour values for the terminal's colour palette.
+
+#![expect(clippy::print_stdout, reason = "We need to give user feedback")]
+
+use color_eyre::Result;
+/// A default palette for users that can't parse their own palette.
+const DEFAULT_PALETTE: &str = include_str!("../../default_palette.toml");
+
+/// A single palette colour.
+pub type PaletteColour = (u8, u8, u8);
+
+/// A hash of palette indexes to true colour values.
+pub type PaletteHashMap = std::collections::HashMap<String, PaletteColour>;
+
+/// Get the terminal's colour palette.
+pub(crate) async fn get_palette(
+    state: &std::sync::Arc<crate::shared_state::SharedState>,
+) -> Result<()> {
+    match super::osc::OSC::run(state).await {
+        Ok(()) => return Ok(()),
+        Err(error) => tracing::warn!("Failed getting palette with OSC query: {error:?}"),
+    }
+
+    super::parser::Parser::run(state, None).await?;
+
+    Ok(())
+}
+
+/// Canonical path to the palette config file.
+pub(crate) async fn palette_config_path(
+    state: &std::sync::Arc<crate::shared_state::SharedState>,
+) -> std::path::PathBuf {
+    crate::config::main::Config::directory(state)
+        .await
+        .join("palette.toml")
+}
+
+/// Does a palette config file exist?
+pub(crate) async fn palette_config_exists(
+    state: &std::sync::Arc<crate::shared_state::SharedState>,
+) -> bool {
+    palette_config_path(state).await.exists()
+}
+
+/// Save the default palette config to the user's Tattoy config path.
+pub(crate) async fn set_default_palette(
+    state: &std::sync::Arc<crate::shared_state::SharedState>,
+) -> Result<()> {
+    let path = palette_config_path(state).await;
+    std::fs::write(path.clone(), DEFAULT_PALETTE)?;
+
+    println!("Default palette saved to: {}", path.display());
+    Ok(())
+}
+
+/// Save the parsed palette true colours as TOML in the Tattoy config directory.
+pub(crate) async fn save(
+    state: &std::sync::Arc<crate::shared_state::SharedState>,
+    palette: &crate::palette::converter::Palette,
+) -> Result<()> {
+    let path = palette_config_path(state).await;
+    let data = toml::to_string(&palette.map)?;
+    std::fs::write(path.clone(), data)?;
+
+    println!("Palette saved to: {}", path.display());
+    Ok(())
+}

crates/tattoy/src/palette/main.rs

@@ -0,0 +1,176 @@
+//! Use OSC codes to query the terminal emulator about what RGB values it uses for each palette
+//! index.
+
+use color_eyre::eyre::{ContextCompat as _, Result};
+use termwiz::terminal::Terminal as _;
+use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+
+/// The amount of time in seconds to wait for a response from the host terminal emulator.
+const WAIT_FOR_RESPONSE_TIMEOUT: u64 = 1;
+
+/// `OSC`
+pub(crate) struct OSC;
+
+impl OSC {
+    /// Main entry point.
+    pub async fn run(state: &std::sync::Arc<crate::shared_state::SharedState>) -> Result<()> {
+        let mut termwiz_terminal = crate::renderer::Renderer::get_termwiz_terminal()?;
+
+        termwiz_terminal.set_raw_mode()?;
+        let result = Self::query_terminal().await;
+        termwiz_terminal.set_cooked_mode()?;
+
+        match result {
+            Ok(hashmap) => {
+                let palette = super::converter::Palette { map: hashmap };
+                super::main::save(state, &palette).await?;
+            }
+            Err(error) => color_eyre::eyre::bail!(error),
+        }
+
+        Ok(())
+    }
+
+    /// Send OSC codes to the user's terminal emulator to query the terminal's palette.
+    async fn query_terminal() -> Result<super::main::PaletteHashMap> {
+        let mut tty = tokio::fs::OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open("/dev/tty")
+            .await?;
+
+        let mut command = String::new();
+        for index in 0..255u8 {
+            command.extend(
+                format!("{}]4;{index};?{}", crate::utils::ESCAPE, crate::utils::BELL).chars(),
+            );
+        }
+        tty.write_all(command.as_bytes()).await?;
+        tty.flush().await?;
+
+        let palette = Self::read_response(tty).await?;
+        tracing::debug!("OSC response to palette RGB query: {palette:?}");
+        Ok(palette)
+    }
+
+    /// Read the response from the controlling terminal after sending an OSC code.
+    async fn read_response(tty: tokio::fs::File) -> Result<super::main::PaletteHashMap> {
+        let buffer_size = 1024;
+        let mut reader = tokio::io::BufReader::new(tty);
+        let mut all = Vec::new();
+        let mut attempts = 0u16;
+
+        loop {
+            let mut buffer = vec![0; buffer_size];
+            let result = tokio::time::timeout(
+                tokio::time::Duration::from_secs(WAIT_FOR_RESPONSE_TIMEOUT),
+                reader.read(&mut buffer),
+            )
+            .await;
+            attempts += 1;
+            if result.is_err() || attempts > 300 {
+                let message = "Timed out waiting for response from controlling terminal \
+                    when querying for palette colour values";
+                tracing::warn!(message);
+                color_eyre::eyre::bail!(message);
+            }
+
+            buffer.retain(|&x| x != 0);
+            all.extend(buffer.clone());
+
+            let response = &String::from_utf8_lossy(&all)
+                .replace(crate::utils::ESCAPE, "ESC")
+                .replace(crate::utils::STRING_TERMINATOR, "ST")
+                .replace(crate::utils::BELL, "BELL");
+
+            match Self::parse_colours(response) {
+                Ok(colours) => {
+                    if colours.len() == 255 {
+                        return Ok(colours);
+                    }
+                }
+                Err(error) => tracing::debug!("Potential error parsing OSC codes: {error:?}"),
+            }
+        }
+    }
+
+    /// Parse the OSC response for palette colours.
+    fn parse_colours(response: &str) -> Result<super::main::PaletteHashMap> {
+        let mut palette = super::main::PaletteHashMap::new();
+        for sequence in response.split("ESC]4;") {
+            if sequence.is_empty() {
+                continue;
+            }
+            tracing::trace!("Parsing OSC sequence: {sequence}");
+
+            let mut index_and_colour = sequence.split(';');
+            let index = index_and_colour
+                .next()
+                .context(format!("OSC sequence not delimited by colon: {sequence}"))?
+                .to_owned();
+            let colourish = index_and_colour
+                .next()
+                .context(format!("Colour not found in OSC sequence: {sequence}"))?;
+
+            let mut channels = colourish.split('/');
+            let red = Self::get_last_chars(
+                channels
+                    .next()
+                    .context(format!("Couldn't get red from OSC response: {colourish:?}"))?,
+                2,
+            );
+            let green = Self::get_last_chars(
+                channels.next().context(format!(
+                    "Couldn't get green from OSC response: {colourish:?}"
+                ))?,
+                2,
+            );
+            let blue = Self::get_first_chars(
+                channels.next().context(format!(
+                    "Couldn't get blue from OSC response: {colourish:?}"
+                ))?,
+                2,
+            );
+
+            let colour: super::main::PaletteColour = (
+                u8::from_str_radix(&red, 16)?,
+                u8::from_str_radix(&green, 16)?,
+                u8::from_str_radix(&blue, 16)?,
+            );
+            palette.insert(index, colour);
+        }
+
+        Ok(palette)
+    }
+
+    /// Get the first x characters from a string.
+    fn get_first_chars(string: &str, count: usize) -> String {
+        string.chars().take(count).collect::<String>()
+    }
+
+    /// Get the last x characters from a string.
+    fn get_last_chars(string: &str, count: usize) -> String {
+        string
+            .chars()
+            .rev()
+            .take(count)
+            .collect::<String>()
+            .chars()
+            .rev()
+            .collect::<String>()
+    }
+}
+
+#[cfg(test)]
+#[expect(clippy::indexing_slicing, reason = "It's just a test")]
+mod test {
+    use super::*;
+
+    #[test]
+    fn parsing_osc_colours() {
+        let response = "ESC]4;1;rgb:c0c0/2222/eaeaBELLESC]4;229;rgb:aaaa/ffff/afafBELL";
+        let palette = OSC::parse_colours(response).unwrap();
+        assert_eq!(palette["1"], (192, 34, 234));
+        assert_eq!(palette["229"], (170, 255, 175));
+    }
+}