Skip to content
485 changes: 485 additions & 0 deletions src/ui/canvas_cache.rs

Large diffs are not rendered by default.

248 changes: 248 additions & 0 deletions src/ui/canvas_layer.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
//! The cacheable base layer of a pane's `OutputCanvas`: background fill, VT cells with WCAG
//! contrast, URL and trigger highlights, CRT scanlines.
//!
//! [`paint_canvas_layer`] is a pure function of the [`VtParser`] grid and [`CanvasLayerInputs`].
//! It deliberately takes neither the pane nor the config, so it cannot read an input that the
//! cache key in [`crate::ui::canvas_cache`] does not cover. A new input goes into
//! `CanvasLayerInputs`; the key destructures that struct exhaustively and stops compiling until
//! the field is handled.

use ratatui::buffer::Buffer;
use ratatui::layout::Rect;
use ratatui::style::{Color, Modifier, Style};

use crate::config::BiltermConfig;
use crate::pane::CompositePane;
use crate::ui::theme::{ThemePalette, ThemePreset};
use crate::ui::typography::{self, LineSizeAttr};
use crate::ui::{contrast, gui_font};
use crate::vt::VtParser;

/// Every input of the canvas base layer other than the VT grid itself (which is identified by
/// `VtParser::generation`, the scrollback offset and the grid size).
#[derive(Clone, Copy, Debug)]
pub struct CanvasLayerInputs<'a> {
/// Absolute canvas rectangle in the frame buffer.
pub canvas: Rect,
/// Theme preset: selects the ANSI 0..15 table and the fallback foreground.
pub theme: ThemePreset,
/// Resolved palette (global, per-window theme or per-window colour overrides).
pub palette: &'a ThemePalette,
/// Per-pane font option: force bold.
pub font_bold: bool,
/// Per-pane font option: force italic.
pub font_italic: bool,
/// Per-pane font option: render every row double-width.
pub font_double_width: bool,
/// Output triggers highlighted on the canvas.
pub triggers: &'a [String],
/// CRT scanline dimming on odd rows.
pub crt_scanlines: bool,
}

impl<'a> CanvasLayerInputs<'a> {
/// Collects the layer inputs for `pane` drawn into `canvas` with `cfg` and `palette`.
pub fn gather(
pane: &CompositePane,
canvas: Rect,
cfg: &'a BiltermConfig,
palette: &'a ThemePalette,
) -> Self {
let font = pane.font_options();
Self {
canvas,
theme: cfg.theme,
palette,
font_bold: font.bold,
font_italic: font.italic,
font_double_width: font.double_width,
triggers: &cfg.triggers,
crt_scanlines: cfg.crt_scanlines,
}
}
}

fn is_safe_terminal_cluster(s: &str, expected_width: usize, grapheme_mode_2027: bool) -> bool {
if s.is_empty() {
return false;
}
let w = unicode_width::UnicodeWidthStr::width(s);
if w != expected_width {
let first_ok = expected_width == 1
&& s.chars().next().is_some_and(|ch| {
gui_font::geometric::is_private_use_area(ch)
|| gui_font::geometric::is_geometric_glyph(ch)
|| unicode_width::UnicodeWidthChar::width(ch) == Some(1)
});
if !first_ok {
return false;
}
}
for ch in s.chars() {
let code = ch as u32;
if matches!(code, 0xFE00..=0xFE0F) || (grapheme_mode_2027 && code == 0x200D) {
continue;
}
if ch.is_control()
|| matches!(
code,
0x200B..=0x200F | 0x2028..=0x202F | 0x2060..=0x206F | 0xFEFF | 0xFFF9..=0xFFFB
)
{
return false;
}
}
true
}

/// Paints the canvas base layer into `buf`. Every cell of `inputs.canvas` that lies inside `buf`
/// gets its symbol, foreground and background replaced and modifiers added (never removed), which
/// is what lets [`crate::ui::canvas_cache`] replay a stored layer over any prior buffer content.
pub fn paint_canvas_layer(vt: &VtParser, inputs: &CanvasLayerInputs<'_>, buf: &mut Buffer) {
let canvas = inputs.canvas;
let palette = inputs.palette;
let (vt_rows, vt_cols) = vt.size();
let render_rows = canvas.height.min(vt_rows);
let render_cols = canvas.width.min(vt_cols);
let grapheme_2027 = vt.is_grapheme_cluster_2027();
let fill_style = Style::default()
.fg(palette.text_fg.unwrap_or(palette.title_fg))
.bg(palette.window_frame_bg);
for y in canvas.y..canvas.y + canvas.height {
for x in canvas.x..canvas.x + canvas.width {
if let Some(c) = buf.cell_mut((x, y)) {
c.set_symbol(" ");
c.set_style(fill_style);
}
}
}

// Runs of cells with the same colours and attributes are the norm; reuse the last style
// instead of redoing the contrast maths (the style depends on nothing else in the cell).
let mut last_style: Option<(contrast::CellStyleKey, Style)> = None;
for r in 0..render_rows {
let mut line_attr = vt.line_size_attr(r);
if !line_attr.is_double_width() && inputs.font_double_width {
line_attr = LineSizeAttr::DoubleWidth;
}
if line_attr.is_double_width() {
typography::render_double_width_row(vt, r, canvas, render_cols, line_attr, buf);
continue;
}
let mut skip_next_wide_continuation = false;
for c in 0..render_cols {
let Some(vt_cell) = vt.cell_view(r, c) else {
skip_next_wide_continuation = false;
continue;
};
let dst_x = canvas.x + c;
let dst_y = canvas.y + r;
let style_key = contrast::CellStyleKey::of(&vt_cell);
let mut style = match last_style {
Some((key, style)) if key == style_key => style,
_ => {
let style = contrast::readable_canvas_cell_style(&vt_cell, inputs.theme, palette);
last_style = Some((style_key, style));
style
}
};
if inputs.font_bold {
style = style.add_modifier(Modifier::BOLD);
}
if inputs.font_italic {
style = style.add_modifier(Modifier::ITALIC);
}

if skip_next_wide_continuation {
skip_next_wide_continuation = false;
if let Some(dst_cell) = buf.cell_mut((dst_x, dst_y)) {
dst_cell.set_style(style);
}
continue;
}

if vt_cell.is_wide_continuation() {
if let Some(dst_cell) = buf.cell_mut((dst_x, dst_y)) {
dst_cell.set_symbol(" ");
dst_cell.set_style(style);
}
continue;
}

let contents = vt_cell.grapheme;
if vt_cell.is_wide() {
// Prevent a 2-column wide glyph at the rightmost column from overflowing/wrapping the host terminal
if c + 1 < render_cols && is_safe_terminal_cluster(contents, 2, grapheme_2027) {
if let Some(dst_cell) = buf.cell_mut((dst_x, dst_y)) {
dst_cell.set_symbol(contents);
dst_cell.set_style(style);
}
skip_next_wide_continuation = true;
} else if let Some(dst_cell) = buf.cell_mut((dst_x, dst_y)) {
dst_cell.set_symbol(" ");
dst_cell.set_style(style);
}
} else if let Some(dst_cell) = buf.cell_mut((dst_x, dst_y)) {
if contents.is_empty() {
dst_cell.set_symbol(" ");
} else if is_safe_terminal_cluster(contents, 1, grapheme_2027) {
if !grapheme_2027 && contents.contains(['\u{FE0E}', '\u{FE0F}'])
&& let Some(base) = contents.chars().next()
{
let mut sym = [0u8; 4];
dst_cell.set_symbol(base.encode_utf8(&mut sym));
} else {
dst_cell.set_symbol(contents);
}
} else {
dst_cell.set_symbol("·");
}
dst_cell.set_style(style);
}
}
}

// Highlight detected URLs with underline + bright cyan tint (VAL-03)
for url in vt.detect_visible_urls() {
if url.row < render_rows {
for c in url.start_col..=url.end_col.min(render_cols.saturating_sub(1)) {
if let Some(cell) = buf.cell_mut((canvas.x + c, canvas.y + url.row)) {
cell.set_style(
cell.style()
.fg(Color::Rgb(85, 255, 255))
.add_modifier(Modifier::UNDERLINED),
);
}
}
}
}

// Highlight custom output triggers (v0.7.0)
for trigger in inputs.triggers {
for m in vt.search_canvas(trigger) {
if m.row < render_rows {
for c in m.start_col..=m.end_col.min(render_cols.saturating_sub(1)) {
if let Some(cell) = buf.cell_mut((canvas.x + c, canvas.y + m.row)) {
cell.set_style(
Style::default()
.fg(Color::White)
.bg(Color::Rgb(200, 0, 80))
.add_modifier(Modifier::BOLD),
);
}
}
}
}
}

// Apply CRT phosphor scanline effect on odd rows when enabled (v0.6.0)
if inputs.crt_scanlines {
for r in (1..render_rows).step_by(2) {
for c in 0..render_cols {
if let Some(cell) = buf.cell_mut((canvas.x + c, canvas.y + r)) {
cell.set_style(cell.style().add_modifier(Modifier::DIM));
}
}
}
}
}
66 changes: 57 additions & 9 deletions src/ui/contrast.rs
Original file line number Diff line number Diff line change
Expand Up @@ -122,18 +122,33 @@ pub fn resolve_ratatui_color_rgb(c: Color, theme: ThemePreset, default_rgb: (u8,
}
}

/// sRGB channel linearisation exactly as WCAG 2.1 defines it (one `powf` per call).
#[inline]
fn linear_channel(v: u8) -> f32 {
let s = f32::from(v) / 255.0;
if s <= 0.03928 {
s / 12.92
} else {
((s + 0.055) / 1.055).powf(2.4)
}
}

/// [`linear_channel`] for every possible channel value, computed once at first use with the same
/// expression, so a lookup is bit-identical to the direct call. The canvas calls
/// [`rgb_luminance`] several times per cell; the table keeps `powf` out of that path.
static LINEAR_CHANNEL: std::sync::LazyLock<[f32; 256]> = std::sync::LazyLock::new(|| {
let mut table = [0.0f32; 256];
for (v, slot) in table.iter_mut().enumerate() {
*slot = linear_channel(v as u8);
}
table
});

/// WCAG 2.1 relative luminance (`0.0..=1.0`) for an `(r, g, b)` triplet.
#[inline]
pub fn rgb_luminance(rgb: (u8, u8, u8)) -> f32 {
fn chan(v: u8) -> f32 {
let s = f32::from(v) / 255.0;
if s <= 0.03928 {
s / 12.92
} else {
((s + 0.055) / 1.055).powf(2.4)
}
}
0.2126 * chan(rgb.0) + 0.7152 * chan(rgb.1) + 0.0722 * chan(rgb.2)
let t = &*LINEAR_CHANNEL;
0.2126 * t[usize::from(rgb.0)] + 0.7152 * t[usize::from(rgb.1)] + 0.0722 * t[usize::from(rgb.2)]
}

/// WCAG 2.1 contrast ratio (`1.0..=21.0`) between two `(r, g, b)` colors.
Expand Down Expand Up @@ -179,6 +194,28 @@ pub fn boost_fg_contrast(fg: (u8, u8, u8), bg: (u8, u8, u8), min_ratio: f32) ->
pole
}

/// The cell attributes [`readable_canvas_cell_style`] reads. Two cells with equal keys get the
/// same style for a given theme and palette, so a renderer may reuse the previous result.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct CellStyleKey {
fg: CellColor,
bg: CellColor,
bold: bool,
italic: bool,
underlined: bool,
inverse: bool,
}

impl CellStyleKey {
#[inline]
pub fn of(cell: &CellView<'_>) -> Self {
// Exhaustive on purpose: a new `CellView` field must be classified here as either part of
// the style key or irrelevant to the style (`grapheme`, `width`).
let CellView { grapheme: _, width: _, fg, bg, bold, italic, underline, inverse } = *cell;
Self { fg, bg, bold, italic, underlined: underline.is_underlined(), inverse }
}
}

/// Converts a [`CellView`] into a high-legibility `ratatui::style::Style` on the `OutputCanvas`:
/// - Resolves `inverse` (`SGR 7`) explicitly into concrete `(fg, bg)` RGB colors so reversed blocks
/// never rely on ambiguous `Color::Reset` host inversion.
Expand Down Expand Up @@ -305,6 +342,17 @@ mod tests {
}
}

#[test]
fn luminance_table_is_bit_identical_to_the_direct_formula() {
for v in 0..=255u8 {
assert_eq!(LINEAR_CHANNEL[usize::from(v)].to_bits(), linear_channel(v).to_bits(), "channel {v}");
}
for rgb in [(0, 0, 0), (255, 255, 255), (12, 16, 24), (248, 250, 252), (96, 165, 250), (1, 127, 254)] {
let direct = 0.2126 * linear_channel(rgb.0) + 0.7152 * linear_channel(rgb.1) + 0.0722 * linear_channel(rgb.2);
assert_eq!(rgb_luminance(rgb).to_bits(), direct.to_bits(), "{rgb:?}");
}
}

#[test]
fn light_highlight_background_with_default_or_light_fg_enforces_dark_text_contrast() {
let palette = ThemePreset::TurboBlue.palette();
Expand Down
Loading
Loading