Skip to main content

iced_code_editor/canvas_editor/render/
highlighting.rs

1//! Syntax resolution and token highlighting for [`CodeEditor`].
2//!
3//! Everything here answers "what colour is this text?", which is a different
4//! question from "where on the canvas does it go?" -- the latter lives in
5//! [`super::text`]. The two process-wide syntect singletons, the per-editor
6//! memo in front of them ([`CodeEditor::resolve_syntax`]), the incremental
7//! per-line cache ([`CodeEditor::highlighted_line_cached`]) and the
8//! rainbow-bracket palettes are all colour decisions, so they sit together
9//! here, leaving `text.rs` with the `draw_*` family.
10
11use iced::Color;
12use std::rc::Rc;
13use std::sync::{Mutex, OnceLock};
14use syntect::easy::HighlightLines;
15use syntect::highlighting::{
16    HighlightState, Highlighter, RangedHighlightIterator, Style, ThemeSet,
17};
18use syntect::parsing::{
19    ParseState, ScopeStack, SyntaxDefinition, SyntaxReference, SyntaxSet,
20    SyntaxSetBuilder,
21};
22
23#[cfg(not(target_arch = "wasm32"))]
24use std::time::Instant;
25#[cfg(target_arch = "wasm32")]
26use web_time::Instant;
27
28use super::token_colors::TokenColorizer;
29use crate::canvas_editor::{
30    CodeEditor, HIGHLIGHT_CLOCK_CHECK_INTERVAL, HighlightCache, ResolvedSyntax,
31};
32
33/// Loading syntect's syntax definitions is expensive, so the set is built once
34/// per process and shared by every editor instance.
35static SYNTAX_SET: OnceLock<SyntaxSet> = OnceLock::new();
36
37/// Definitions added with [`register_syntaxes`], waiting for [`EXTRA_SET`] to
38/// be built.
39static EXTRA_SYNTAXES: Mutex<Vec<SyntaxDefinition>> = Mutex::new(Vec::new());
40
41/// The registered syntaxes, in a set of their own (see [`register_syntaxes`]).
42/// Kept apart from [`SYNTAX_SET`] because adding to the bundled set means
43/// re-linking every bundled grammar, which costs hundreds of milliseconds.
44static EXTRA_SET: OnceLock<SyntaxSet> = OnceLock::new();
45
46/// Error returned by [`register_syntaxes`].
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub enum SyntaxRegistrationError {
49    /// A definition is not a valid `.sublime-syntax` file. `index` is its
50    /// position in the input; nothing was registered.
51    Parse {
52        /// Position of the definition in the input.
53        index: usize,
54        /// The parser's message.
55        message: String,
56    },
57    /// An editor has already highlighted text, and the syntax set is built
58    /// once per process: register syntaxes before creating editors.
59    AlreadyBuilt,
60}
61
62impl std::fmt::Display for SyntaxRegistrationError {
63    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
64        match self {
65            Self::Parse { index, message } => {
66                write!(f, "syntax definition {index}: {message}")
67            }
68            Self::AlreadyBuilt => write!(
69                f,
70                "the syntax set is already built; register syntaxes before \
71                 the first editor highlights text"
72            ),
73        }
74    }
75}
76
77impl std::error::Error for SyntaxRegistrationError {}
78
79/// Adds syntax definitions, in Sublime Text's `.sublime-syntax` format, to the
80/// set every editor highlights with.
81///
82/// A definition is chosen like the bundled ones, by the file extensions it
83/// lists (`file_extensions`) matching the editor's syntax name. Registered
84/// syntaxes are looked up before the bundled ones, so one can replace a bundled
85/// syntax; among registered ones claiming the same extension, the one
86/// registered last wins.
87///
88/// Registered syntaxes form a set of their own, which keeps building it cheap
89/// (adding to the bundled set would re-link every bundled grammar). They can
90/// include each other by scope (`include: scope:source.zig`), but not the
91/// bundled ones: register the grammars a definition includes along with it.
92/// An include that resolves to nothing is ignored.
93///
94/// The set is built once per process, the first time an editor highlights
95/// text, so call this before that, typically at startup. All or nothing: if
96/// one definition does not parse, none is registered.
97///
98/// # Errors
99///
100/// [`SyntaxRegistrationError::Parse`] for an invalid definition, and
101/// [`SyntaxRegistrationError::AlreadyBuilt`] when the set already exists.
102///
103/// # Example
104///
105/// ```
106/// let ini = r#"
107/// name: Tiny INI
108/// file_extensions: [tini]
109/// scope: source.tini
110/// contexts:
111///   main:
112///     - match: '^\[.*\]$'
113///       scope: entity.name.section.tini
114/// "#;
115/// iced_code_editor::register_syntaxes([ini]).expect("valid syntax");
116/// ```
117pub fn register_syntaxes<'a>(
118    definitions: impl IntoIterator<Item = &'a str>,
119) -> Result<(), SyntaxRegistrationError> {
120    register_into(&EXTRA_SET, &EXTRA_SYNTAXES, definitions)
121}
122
123/// [`register_syntaxes`] against an explicit set and queue (tests use their
124/// own, so they don't depend on the process-wide one).
125fn register_into<'a>(
126    set: &OnceLock<SyntaxSet>,
127    queue: &Mutex<Vec<SyntaxDefinition>>,
128    definitions: impl IntoIterator<Item = &'a str>,
129) -> Result<(), SyntaxRegistrationError> {
130    let parsed = definitions
131        .into_iter()
132        .enumerate()
133        .map(|(index, text)| {
134            SyntaxDefinition::load_from_str(text, true, None).map_err(|e| {
135                SyntaxRegistrationError::Parse { index, message: e.to_string() }
136            })
137        })
138        .collect::<Result<Vec<_>, _>>()?;
139    // Hold the queue while checking, so the set can't be built in between.
140    let mut queue = queue.lock().unwrap_or_else(|e| e.into_inner());
141    if set.get().is_some() {
142        return Err(SyntaxRegistrationError::AlreadyBuilt);
143    }
144    queue.extend(parsed);
145    Ok(())
146}
147
148/// The bundled syntaxes.
149fn bundled_syntax_set() -> SyntaxSet {
150    #[cfg(feature = "two-face")]
151    {
152        two_face::syntax::extra_newlines()
153    }
154    #[cfg(not(feature = "two-face"))]
155    {
156        SyntaxSet::load_defaults_newlines()
157    }
158}
159
160/// The registered syntaxes (see [`register_syntaxes`]), empty when none were.
161fn build_extra_set(queue: &Mutex<Vec<SyntaxDefinition>>) -> SyntaxSet {
162    let mut builder = SyntaxSetBuilder::new();
163    let definitions =
164        std::mem::take(&mut *queue.lock().unwrap_or_else(|e| e.into_inner()));
165    for definition in definitions {
166        builder.add(definition);
167    }
168    builder.build()
169}
170
171/// The registered syntax for an editor's syntax name, if any: the last one
172/// registered that lists it among its file extensions.
173fn find_registered<'a>(
174    set: &'a SyntaxSet,
175    name: &str,
176) -> Option<&'a SyntaxReference> {
177    set.syntaxes().iter().rev().find(|syntax| {
178        syntax.file_extensions.iter().any(|e| e.eq_ignore_ascii_case(name))
179    })
180}
181
182/// Syntect's bundled themes, loaded once per process (see [`SYNTAX_SET`]).
183static THEME_SET: OnceLock<ThemeSet> = OnceLock::new();
184
185/// Converts a syntect highlight [`Style`] into an iced [`Color`].
186///
187/// Only the foreground color is used; alpha is left fully opaque.
188///
189/// # Arguments
190///
191/// * `style` - The syntect style whose foreground color is converted.
192fn color_from_style(style: Style) -> Color {
193    color_from_syntect(style.foreground)
194}
195
196/// Converts a syntect [`syntect::highlighting::Color`] into an opaque iced
197/// [`Color`].
198fn color_from_syntect(color: syntect::highlighting::Color) -> Color {
199    Color::from_rgb(
200        f32::from(color.r) / 255.0,
201        f32::from(color.g) / 255.0,
202        f32::from(color.b) / 255.0,
203    )
204}
205
206/// Perceptual luminance (ITU-R BT.601), used only to compare contrast.
207fn luminance(color: Color) -> f32 {
208    color.r * 0.299 + color.g * 0.587 + color.b * 0.114
209}
210
211/// Minimum luminance separation for a token to count as legible.
212const MIN_CONTRAST: f32 = 0.12;
213
214/// Whether `color` stands out enough from `background` to be read.
215fn contrasts_with(color: Color, background: Color) -> bool {
216    (luminance(color) - luminance(background)).abs() >= MIN_CONTRAST
217}
218
219/// Picks a foreground color for `style` that is legible on `background`.
220///
221/// Some syntect themes express a scope as a *background* highlight: the
222/// base16 themes paint `invalid.illegal` as "foreground = the theme
223/// background, background = red". Drawing only the foreground on the editor
224/// background therefore made half-typed code (an unmatched brace, a stray
225/// comma) disappear until it became valid again.
226///
227/// Resolution order: the style's foreground if it contrasts, then its
228/// background (the color the theme chose to stand out, so invalid tokens
229/// read as red), then `fallback`, the editor's plain text color.
230fn readable_color(style: Style, background: Color, fallback: Color) -> Color {
231    let foreground = color_from_style(style);
232    if contrasts_with(foreground, background) {
233        return foreground;
234    }
235    let highlight = color_from_syntect(style.background);
236    if contrasts_with(highlight, background) {
237        return highlight;
238    }
239    fallback
240}
241
242/// Tokenizes a full logical line into colored spans using syntect.
243///
244/// The returned spans cover the entire line in order, each pairing an iced
245/// [`Color`] with the owned token text. Each call highlights the line
246/// independently from the syntax's initial state, so it does not handle
247/// multi-line constructs; it is used for tests and benchmarks. Rendering uses
248/// the sequential `CodeEditor::highlighted_line_cached` instead.
249///
250/// # Arguments
251///
252/// * `line` - The full logical line content (without trailing newline).
253/// * `syntax` - The syntect syntax definition to tokenize with.
254/// * `theme` - The syntect highlighting theme providing token colors.
255/// * `syntax_set` - The syntax set the `syntax` belongs to.
256///
257/// # Returns
258///
259/// The ordered colored spans covering the entire line.
260pub fn highlight_line_spans(
261    line: &str,
262    syntax: &syntect::parsing::SyntaxReference,
263    theme: &syntect::highlighting::Theme,
264    syntax_set: &SyntaxSet,
265) -> Vec<(Color, String)> {
266    let mut highlighter = HighlightLines::new(syntax, theme);
267    let ranges = highlighter
268        .highlight_line(line, syntax_set)
269        .unwrap_or_else(|_| vec![(Style::default(), line)]);
270
271    // Check contrast against the theme's own colors, for the same reason as
272    // the rendering path (see `readable_color`).
273    let background =
274        theme.settings.background.map_or(Color::BLACK, color_from_syntect);
275    let fallback =
276        theme.settings.foreground.map_or(Color::WHITE, color_from_syntect);
277
278    ranges
279        .into_iter()
280        .map(|(style, text)| {
281            (readable_color(style, background, fallback), text.to_string())
282        })
283        .collect()
284}
285
286/// Color cycle for bracket-pair colorization on a **dark** editor background,
287/// indexed by nesting depth modulo its length so a matching pair always shares
288/// a color. Matches the well-known VS Code Dark+ rainbow-bracket palette (gold,
289/// orchid, light sky blue) for a look users are likely already familiar with.
290const BRACKET_PAIR_COLORS_DARK: [Color; 3] = [
291    Color { r: 1.0, g: 0.843, b: 0.0, a: 1.0 }, // gold
292    Color { r: 0.855, g: 0.439, b: 0.839, a: 1.0 }, // orchid
293    Color { r: 0.529, g: 0.808, b: 0.980, a: 1.0 }, // light sky blue
294];
295
296/// The same cycle for a **light** editor background, following VS Code Light+.
297///
298/// The dark palette is built from bright, low-contrast-on-white hues; reusing
299/// it on a light background leaves brackets barely visible, so the light theme
300/// gets its own saturated, dark-toned triple.
301const BRACKET_PAIR_COLORS_LIGHT: [Color; 3] = [
302    Color { r: 0.016, g: 0.192, b: 0.980, a: 1.0 }, // blue
303    Color { r: 0.192, g: 0.576, b: 0.192, a: 1.0 }, // green
304    Color { r: 0.482, g: 0.220, b: 0.078, a: 1.0 }, // brown
305];
306
307impl CodeEditor {
308    /// Returns the rainbow-bracket palette matching this editor's theme.
309    ///
310    /// Like the syntect token palette (see [`CodeEditor::resolve_syntax`]),
311    /// the cycle is picked from the lightness of the style's background, so
312    /// brackets stay legible under both light and dark themes.
313    ///
314    /// # Returns
315    ///
316    /// The three-color cycle to index by nesting depth.
317    pub(super) fn bracket_pair_colors(&self) -> &'static [Color; 3] {
318        if crate::theme::is_dark_background(self.style.background) {
319            &BRACKET_PAIR_COLORS_DARK
320        } else {
321            &BRACKET_PAIR_COLORS_LIGHT
322        }
323    }
324
325    /// Resolves the syntect syntax and theme used to color this editor's text.
326    ///
327    /// Both the syntax set and the theme set are process-wide singletons, and
328    /// the per-editor result is memoized in [`ResolvedSyntax`], so this is
329    /// cheap enough to call on every render -- the underlying
330    /// `find_syntax_by_extension` scan is not. Common language aliases and
331    /// extensions (`python`/`py`, `markdown`/`md`, …) are normalized here, and
332    /// an unknown syntax falls back to plain text rather than losing the text.
333    ///
334    /// The token palette is [`crate::Style::syntax_theme_name`] when set to a
335    /// bundled theme; otherwise it follows the editor's own theme: a light
336    /// editor background selects `base16-ocean.light`, a dark one
337    /// `base16-ocean.dark`.
338    ///
339    /// # Returns
340    ///
341    /// The shared syntax set, the syntax to tokenize with, and the theme
342    /// providing token colors. The syntax and theme are `None` only when
343    /// syntect ships no definition at all for them.
344    pub(crate) fn resolve_syntax(
345        &self,
346    ) -> (
347        &'static SyntaxSet,
348        Option<&'static SyntaxReference>,
349        Option<&'static syntect::highlighting::Theme>,
350    ) {
351        let bundled = SYNTAX_SET.get_or_init(bundled_syntax_set);
352        let registered =
353            EXTRA_SET.get_or_init(|| build_extra_set(&EXTRA_SYNTAXES));
354        // A syntax is parsed with the set it belongs to.
355        let owner = |syntax: Option<&'static SyntaxReference>| {
356            let is_registered = syntax.is_some_and(|s| {
357                registered.syntaxes().iter().any(|r| std::ptr::eq(r, s))
358            });
359            if is_registered { registered } else { bundled }
360        };
361
362        // Pair the token palette with the editor's own theme: a dark-tuned
363        // palette on a light background leaves comments and strings unreadable.
364        let dark_background =
365            crate::theme::is_dark_background(self.style.background);
366
367        let requested_theme = self.style.syntax_theme_name;
368
369        let mut memo = self.resolved_syntax.borrow_mut();
370        if let Some((syntax, theme)) = memo.as_ref().and_then(|resolved| {
371            resolved.get(&self.syntax, dark_background, requested_theme)
372        }) {
373            return (owner(syntax), syntax, theme);
374        }
375
376        let theme_set = THEME_SET.get_or_init(ThemeSet::load_defaults);
377        let automatic_theme = if dark_background {
378            "base16-ocean.dark"
379        } else {
380            "base16-ocean.light"
381        };
382        // A host-chosen theme wins; an unknown name falls back to the
383        // automatic one rather than losing the colors.
384        let theme = requested_theme
385            .and_then(|name| theme_set.themes.get(name))
386            .or_else(|| theme_set.themes.get(automatic_theme))
387            .or_else(|| theme_set.themes.values().next());
388
389        // Registered syntaxes first, then the bundled ones, normalizing common
390        // language aliases/extensions used by consumers.
391        let syntax_set = bundled;
392        let syntax = find_registered(registered, &self.syntax)
393            .or_else(|| match self.syntax.as_str() {
394                "python" => syntax_set.find_syntax_by_extension("py"),
395                "rust" => syntax_set.find_syntax_by_extension("rs"),
396                "javascript" => syntax_set.find_syntax_by_extension("js"),
397                "htm" => syntax_set.find_syntax_by_extension("html"),
398                "svg" => syntax_set.find_syntax_by_extension("xml"),
399                "markdown" => syntax_set.find_syntax_by_extension("md"),
400                "text" => Some(syntax_set.find_syntax_plain_text()),
401                _ => syntax_set.find_syntax_by_extension(self.syntax.as_str()),
402            })
403            .or(Some(syntax_set.find_syntax_plain_text()));
404
405        *memo = Some(ResolvedSyntax::new(
406            &self.syntax,
407            dark_background,
408            requested_theme,
409            syntax,
410            theme,
411        ));
412
413        (owner(syntax), syntax, theme)
414    }
415
416    /// Returns the memoized syntax-highlighted spans for a logical line.
417    ///
418    /// Highlighting is performed sequentially: lines `0..=logical_line` are
419    /// tokenized in order, each resuming from the syntect state left by the
420    /// previous line, so multi-line constructs (block comments, multi-line
421    /// strings) are colored correctly. The result is stored as a dense valid
422    /// prefix in [`HighlightCache`] and reused across wrapped visual segments
423    /// and across renders; an edit truncates the prefix from the changed line
424    /// (see [`CodeEditor::invalidate_highlight_from`]) instead of clearing it,
425    /// so deep lines are not re-parsed from the top on every keystroke. The
426    /// cache is reset only when the active syntax changes.
427    ///
428    /// # Arguments
429    ///
430    /// * `logical_line` - Index of the logical line in the buffer.
431    /// * `syntax` - The syntect syntax definition to tokenize with.
432    /// * `theme` - The syntect highlighting theme providing token colors.
433    /// * `syntax_set` - The syntax set the `syntax` belongs to.
434    ///
435    /// # Returns
436    ///
437    /// A shared handle to the line's colored token spans.
438    pub(crate) fn highlighted_line_cached(
439        &self,
440        logical_line: usize,
441        syntax: &syntect::parsing::SyntaxReference,
442        theme: &syntect::highlighting::Theme,
443        syntax_set: &SyntaxSet,
444    ) -> Rc<Vec<(Color, String)>> {
445        let mut guard = self.highlight_cache.borrow_mut();
446
447        // Reset the whole cache only when the active syntax changes.
448        let needs_reset =
449            guard.as_ref().is_none_or(|cache| cache.syntax() != self.syntax);
450        if needs_reset {
451            *guard = Some(HighlightCache::new(self.syntax.clone()));
452        }
453
454        let Some(cache) = guard.as_mut() else {
455            // Unreachable: populated just above. `unwrap`/`panic` are denied,
456            // so fall back to a single independent highlight without caching.
457            return Rc::new(highlight_line_spans(
458                self.buffer.line(logical_line),
459                syntax,
460                theme,
461                syntax_set,
462            ));
463        };
464
465        if let Some(spans) = cache.spans(logical_line) {
466            return spans;
467        }
468
469        // Extend the valid prefix sequentially up to `logical_line`, carrying
470        // the parser/highlight state forward across lines.
471        let highlighter = Highlighter::new(theme);
472        let (mut parse_state, mut highlight_state) =
473            cache.resume_state().unwrap_or_else(|| {
474                (
475                    ParseState::new(syntax),
476                    HighlightState::new(&highlighter, ScopeStack::new()),
477                )
478            });
479
480        let line_count = self.buffer.line_count();
481        let target = logical_line.min(line_count.saturating_sub(1));
482        let missing_lines =
483            target.saturating_add(1).saturating_sub(cache.valid_len());
484        let lines_to_parse =
485            missing_lines.min(self.highlight_lines_remaining.get());
486        let parse_end = cache
487            .valid_len()
488            .saturating_add(lines_to_parse)
489            .saturating_sub(1)
490            .min(target);
491        let mut result = None;
492        let background = self.style.background;
493        let fallback = self.style.text_color;
494        let deadline = self.highlight_deadline.get();
495        let mut parsed = 0usize;
496        if lines_to_parse > 0 {
497            for index in cache.valid_len()..=parse_end {
498                // Stop when this frame's time budget runs out, even if the
499                // line budget has not. The clock is only read every few lines.
500                if parsed > 0
501                    && parsed.is_multiple_of(HIGHLIGHT_CLOCK_CHECK_INTERVAL)
502                    && deadline
503                        .is_some_and(|deadline| Instant::now() >= deadline)
504                {
505                    break;
506                }
507                parsed += 1;
508                // syntect's `_newlines` syntaxes expect a trailing '\n' for correct
509                // end-of-line context handling; the stored buffer line has none.
510                let mut line = self.buffer.line(index).to_string();
511                line.push('\n');
512
513                let ops = parse_state
514                    .parse_line(&line, syntax_set)
515                    .unwrap_or_default();
516                // Captured before the highlighter advances the scope stack.
517                let mut token_colors = TokenColorizer::new(
518                    self.style.token_colors,
519                    highlight_state.path.clone(),
520                    &ops,
521                );
522                let spans: Vec<(Color, String)> = RangedHighlightIterator::new(
523                    &mut highlight_state,
524                    &ops,
525                    &line,
526                    &highlighter,
527                )
528                .filter_map(|(style, text, range)| {
529                    let text = text.strip_suffix('\n').unwrap_or(text);
530                    if text.is_empty() {
531                        return None;
532                    }
533                    let color = token_colors
534                        .as_mut()
535                        .and_then(|colors| colors.color_at(range.start))
536                        .unwrap_or_else(|| {
537                            readable_color(style, background, fallback)
538                        });
539                    Some((color, text.to_string()))
540                })
541                .collect();
542
543                let spans = Rc::new(spans);
544                cache.push_line(
545                    Rc::clone(&spans),
546                    parse_state.clone(),
547                    highlight_state.clone(),
548                );
549                if index == logical_line {
550                    result = Some(spans);
551                }
552            }
553        }
554        // Charge only the lines actually parsed: stopping on the time budget
555        // must not consume the rest of the line budget.
556        self.highlight_lines_remaining
557            .set(self.highlight_lines_remaining.get().saturating_sub(parsed));
558        // The target is still out of reach: ask for another frame. The line
559        // budget is only refilled when the content layer is redrawn, so
560        // without this the catch-up would stop until an unrelated redraw.
561        if cache.valid_len() <= target {
562            self.highlight_catch_up_pending.set(true);
563        }
564
565        result.or_else(|| cache.spans(logical_line)).unwrap_or_else(|| {
566            Rc::new(vec![(
567                self.style.text_color,
568                self.buffer.line(logical_line).to_string(),
569            )])
570        })
571    }
572}
573
574#[cfg(test)]
575mod tests {
576    use std::rc::Rc;
577
578    use syntect::parsing::SyntaxSet;
579
580    use super::*;
581
582    #[test]
583    fn test_bracket_pair_colors_follow_the_editor_theme() {
584        let mut editor = CodeEditor::new("(a)", "rs");
585
586        editor.set_theme(crate::theme::from_iced_theme(&iced::Theme::Dark));
587        let dark = editor.bracket_pair_colors();
588
589        editor.set_theme(crate::theme::from_iced_theme(&iced::Theme::Light));
590        let light = editor.bracket_pair_colors();
591
592        assert_ne!(
593            dark[0], light[0],
594            "a light theme must not reuse the dark rainbow palette"
595        );
596    }
597
598    #[test]
599    fn test_bracket_pair_colors_contrast_with_their_background() {
600        // Every dark-theme bracket color must read as light (drawn on a dark
601        // background) and every light-theme one as dark, or the brackets
602        // vanish into the page.
603        for color in BRACKET_PAIR_COLORS_DARK {
604            assert!(
605                !crate::theme::is_dark_background(color),
606                "{color:?} is too dark for a dark background"
607            );
608        }
609        for color in BRACKET_PAIR_COLORS_LIGHT {
610            assert!(
611                crate::theme::is_dark_background(color),
612                "{color:?} is too light for a light background"
613            );
614        }
615    }
616
617    #[test]
618    fn test_highlight_line_spans_covers_full_line() {
619        let syntax_set = SyntaxSet::load_defaults_newlines();
620        let syntax = syntax_set.find_syntax_plain_text();
621        let theme = syntect::highlighting::Theme::default();
622
623        let line = "fn main() {}";
624        let spans = highlight_line_spans(line, syntax, &theme, &syntax_set);
625
626        assert!(!spans.is_empty(), "expected at least one span");
627        let combined: String =
628            spans.iter().map(|(_, text)| text.as_str()).collect();
629        assert_eq!(combined, line, "spans must cover the entire line");
630    }
631
632    #[test]
633    fn test_highlighted_line_cached_reuses_until_invalidated() {
634        let editor = CodeEditor::new("fn main() {}\nlet x = 1;", "rs");
635        let syntax_set = SyntaxSet::load_defaults_newlines();
636        let syntax = syntax_set.find_syntax_plain_text();
637        let theme = syntect::highlighting::Theme::default();
638
639        let first =
640            editor.highlighted_line_cached(0, syntax, &theme, &syntax_set);
641        let second =
642            editor.highlighted_line_cached(0, syntax, &theme, &syntax_set);
643        assert!(
644            Rc::ptr_eq(&first, &second),
645            "a cached line should be reused as the same Rc"
646        );
647
648        editor.invalidate_highlight_from(0);
649        let third =
650            editor.highlighted_line_cached(0, syntax, &theme, &syntax_set);
651        assert!(
652            !Rc::ptr_eq(&first, &third),
653            "invalidation should force the line to be recomputed"
654        );
655    }
656
657    #[test]
658    fn test_highlight_budget_uses_plain_fallback_without_scanning_to_target() {
659        let editor = CodeEditor::new("zero\none\ntwo\nthree\nfour", "txt");
660        let syntax_set = SyntaxSet::load_defaults_newlines();
661        let syntax = syntax_set.find_syntax_plain_text();
662        let theme = syntect::highlighting::Theme::default();
663        editor.highlight_lines_remaining.set(2);
664
665        let spans =
666            editor.highlighted_line_cached(4, syntax, &theme, &syntax_set);
667        let combined: String =
668            spans.iter().map(|(_, text)| text.as_str()).collect();
669
670        assert_eq!(combined, "four");
671        assert_eq!(
672            editor
673                .highlight_cache
674                .borrow()
675                .as_ref()
676                .map(super::HighlightCache::valid_len),
677            Some(2)
678        );
679        assert_eq!(editor.highlight_lines_remaining.get(), 0);
680    }
681
682    #[test]
683    fn test_expired_time_budget_stops_parsing_early() {
684        let content = vec!["{\"k\": 1}"; 1_000].join("\n");
685        let editor = CodeEditor::new(&content, "json");
686        let (syntax_set, syntax, theme) = editor.resolve_syntax();
687        let (Some(syntax), Some(theme)) = (syntax, theme) else {
688            return;
689        };
690        // Plenty of line budget, but the frame's clock already ran out.
691        editor.highlight_lines_remaining.set(10_000);
692        editor.highlight_deadline.set(Some(Instant::now()));
693
694        let _ = editor.highlighted_line_cached(999, syntax, theme, syntax_set);
695
696        let parsed = editor
697            .highlight_cache
698            .borrow()
699            .as_ref()
700            .map(super::HighlightCache::valid_len);
701        assert_eq!(
702            parsed,
703            Some(HIGHLIGHT_CLOCK_CHECK_INTERVAL),
704            "parsing stops at the first clock check past the deadline"
705        );
706        assert_eq!(
707            editor.highlight_lines_remaining.get(),
708            10_000 - HIGHLIGHT_CLOCK_CHECK_INTERVAL,
709            "only the lines actually parsed are charged"
710        );
711        assert!(editor.highlight_catch_up_pending.get());
712    }
713
714    #[test]
715    fn test_no_deadline_parses_up_to_the_target() {
716        let content = vec!["{\"k\": 1}"; 1_000].join("\n");
717        let editor = CodeEditor::new(&content, "json");
718        let (syntax_set, syntax, theme) = editor.resolve_syntax();
719        let (Some(syntax), Some(theme)) = (syntax, theme) else {
720            return;
721        };
722
723        let _ = editor.highlighted_line_cached(999, syntax, theme, syntax_set);
724
725        assert!(!editor.highlight_catch_up_pending.get());
726        assert_eq!(
727            editor
728                .highlight_cache
729                .borrow()
730                .as_ref()
731                .map(super::HighlightCache::valid_len),
732            Some(1_000)
733        );
734    }
735
736    /// Perceptual luminance (ITU-R BT.601), recomputed locally so the test
737    /// does not depend on the code under test.
738    fn test_luminance(color: Color) -> f32 {
739        color.r * 0.299 + color.g * 0.587 + color.b * 0.114
740    }
741
742    /// Every rendered span of `code` must stay legible on the editor
743    /// background, for both the light and the dark palette.
744    fn assert_all_spans_legible(code: &str, syntax_name: &str) {
745        for iced_theme in [iced::Theme::Dark, iced::Theme::Light] {
746            let mut editor = CodeEditor::new(code, syntax_name);
747            editor.set_theme(crate::theme::from_iced_theme(&iced_theme));
748            let (syntax_set, syntax, theme) = editor.resolve_syntax();
749            let (Some(syntax), Some(theme)) = (syntax, theme) else {
750                continue;
751            };
752            let background = test_luminance(editor.style.background);
753
754            for line in 0..editor.buffer.line_count() {
755                let spans = editor
756                    .highlighted_line_cached(line, syntax, theme, syntax_set);
757                for (color, text) in spans.iter() {
758                    let contrast = (test_luminance(*color) - background).abs();
759                    assert!(
760                        contrast >= 0.12,
761                        "{iced_theme:?}: {text:?} on line {line} is drawn in \
762                         {color:?}, which vanishes into the background"
763                    );
764                }
765            }
766        }
767    }
768
769    #[test]
770    fn test_invalid_json_tokens_stay_legible() {
771        // A half-typed JSON body: the grammar flags the stray tokens as
772        // `invalid.illegal`, which base16 themes paint as background-coloured
773        // text on a red block.
774        assert_all_spans_legible("{\n  \"a\": 1,,\n  \"b\" 2\n}}\n]", "json");
775    }
776
777    #[test]
778    fn test_valid_code_keeps_distinct_theme_colors() {
779        // The legibility fallback must not flatten ordinary highlighting.
780        let editor = CodeEditor::new("{\"key\": \"value\", \"n\": 42}", "json");
781        let (syntax_set, syntax, theme) = editor.resolve_syntax();
782        let (Some(syntax), Some(theme)) = (syntax, theme) else {
783            return;
784        };
785        let spans =
786            editor.highlighted_line_cached(0, syntax, theme, syntax_set);
787        let mut colors: Vec<Color> = Vec::new();
788        for (color, _) in spans.iter() {
789            if !colors.contains(color) {
790                colors.push(*color);
791            }
792        }
793        assert!(colors.len() >= 3, "expected varied token colors: {colors:?}");
794        assert_all_spans_legible("{\"key\": \"value\", \"n\": 42}", "json");
795    }
796
797    #[test]
798    fn test_highlighted_line_cached_handles_multiline_comments() {
799        let syntax_set = SyntaxSet::load_defaults_newlines();
800        let syntax = syntax_set
801            .find_syntax_by_extension("rs")
802            .unwrap_or_else(|| syntax_set.find_syntax_plain_text());
803        let theme = ThemeSet::load_defaults()
804            .themes
805            .get("base16-ocean.dark")
806            .cloned()
807            .unwrap_or_default();
808
809        // Line index 2 ("still inside") sits within a `/* ... */` block.
810        let code = "let a = 1;\n/* open\nstill inside\n*/\nlet b = 2;";
811        let editor = CodeEditor::new(code, "rs");
812
813        // Sequential highlighting resumes inside the block comment.
814        let sequential =
815            editor.highlighted_line_cached(2, syntax, &theme, &syntax_set);
816        // Independent highlighting wrongly treats the line as ordinary code.
817        let independent = highlight_line_spans(
818            editor.buffer.line(2),
819            syntax,
820            &theme,
821            &syntax_set,
822        );
823
824        let sequential_color = sequential.first().map(|(color, _)| *color);
825        let independent_color = independent.first().map(|(color, _)| *color);
826        assert!(sequential_color.is_some());
827        assert!(independent_color.is_some());
828        assert_ne!(
829            sequential_color, independent_color,
830            "a line inside a block comment must be colored as a comment"
831        );
832    }
833
834    const TINY: &str = r#"
835name: Tiny
836file_extensions: [tiny]
837scope: source.tiny
838contexts:
839  main:
840    - match: '\bhello\b'
841      scope: keyword.tiny
842"#;
843
844    #[test]
845    #[allow(clippy::unwrap_used, clippy::expect_used)]
846    fn registered_syntaxes_are_found_by_extension() {
847        let set = OnceLock::new();
848        let queue = Mutex::new(Vec::new());
849        register_into(&set, &queue, [TINY]).expect("valid");
850        let built = set.get_or_init(|| build_extra_set(&queue));
851        assert!(queue.lock().unwrap().is_empty(), "the queue is consumed");
852
853        let tiny = find_registered(built, "TINY").expect("registered");
854        assert_eq!(tiny.name, "Tiny");
855        assert!(find_registered(built, "rs").is_none());
856
857        let spans = highlight_line_spans(
858            "say hello",
859            tiny,
860            &syntect::highlighting::Theme::default(),
861            built,
862        );
863        let texts: Vec<_> = spans.iter().map(|(_, t)| t.as_str()).collect();
864        assert_eq!(texts.concat(), "say hello");
865    }
866
867    #[test]
868    #[allow(clippy::unwrap_used, clippy::expect_used)]
869    fn registered_syntaxes_include_each_other_and_the_last_one_wins() {
870        let host = r#"
871name: Host
872file_extensions: [host]
873scope: source.host
874contexts:
875  main:
876    - include: scope:source.tiny
877"#;
878        let newer_tiny = TINY.replace("name: Tiny", "name: Newer Tiny");
879        let set = OnceLock::new();
880        let queue = Mutex::new(Vec::new());
881        register_into(&set, &queue, [TINY, host, newer_tiny.as_str()])
882            .expect("valid");
883        let built = set.get_or_init(|| build_extra_set(&queue));
884        assert_eq!(find_registered(built, "tiny").unwrap().name, "Newer Tiny");
885
886        let host = find_registered(built, "host").unwrap();
887        let mut state = ParseState::new(host);
888        let ops = state.parse_line("hello\n", built).expect("parses");
889        assert!(!ops.is_empty(), "the included grammar colors the word");
890    }
891
892    #[test]
893    #[allow(clippy::unwrap_used, clippy::expect_used)]
894    fn invalid_definitions_and_late_registration_are_rejected() {
895        let set = OnceLock::new();
896        let queue = Mutex::new(Vec::new());
897        let error = register_into(&set, &queue, [TINY, "name: [unclosed"])
898            .expect_err("invalid");
899        assert!(matches!(
900            error,
901            SyntaxRegistrationError::Parse { index: 1, .. }
902        ));
903        assert!(queue.lock().unwrap().is_empty(), "all or nothing");
904
905        set.get_or_init(|| build_extra_set(&queue));
906        assert_eq!(
907            register_into(&set, &queue, [TINY]),
908            Err(SyntaxRegistrationError::AlreadyBuilt)
909        );
910    }
911
912    #[test]
913    #[allow(clippy::unwrap_used, clippy::expect_used)]
914    fn an_include_of_a_missing_syntax_does_not_panic() {
915        let dangling = r#"
916name: Dangling
917file_extensions: [dangling]
918scope: source.dangling
919contexts:
920  main:
921    - include: scope:source.rust
922    - match: '\bok\b'
923      scope: keyword.dangling
924"#;
925        let set = OnceLock::new();
926        let queue = Mutex::new(Vec::new());
927        register_into(&set, &queue, [dangling]).expect("valid");
928        let built = set.get_or_init(|| build_extra_set(&queue));
929        let syntax = find_registered(built, "dangling").expect("registered");
930        let mut state = ParseState::new(syntax);
931        let _ = state.parse_line("ok then\n", built);
932    }
933
934    #[test]
935    fn with_nothing_registered_the_extra_set_is_empty() {
936        let queue = Mutex::new(Vec::new());
937        assert!(build_extra_set(&queue).syntaxes().is_empty());
938    }
939}