termzzz 0.0.2

Screen savers and visual effects for terminal
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
use crate::buffer::Cell;
use crate::canvas::Canvas;
use crate::common::{DEFAULT_SEED, EffectRng, TerminalEffect, seeded_rng};
use crate::render::glyph_ramp::{GlyphRamp, presets as glyph_presets};
use crossterm::style;
use rand::RngExt;
use serde::{Deserialize, Serialize};
use std::sync::LazyLock;

static PALETTE: LazyLock<Vec<u8>> = LazyLock::new(|| {
    let mut vec = Vec::with_capacity(768);
    vec.extend_from_slice(&[
        0, 0, 0, 0, 0, 6, 0, 0, 6, 0, 0, 7, 0, 0, 8, 0, 0, 8, 0, 0, 9, 0, 0, 10, 2,
        0, 10, 4, 0, 9, 6, 0, 9, 8, 0, 8, 10, 0, 7, 12, 0, 7, 14, 0, 6, 16, 0, 5,
        18, 0, 5, 20, 0, 4, 22, 0, 4, 24, 0, 3, 26, 0, 2, 28, 0, 2, 30, 0, 1, 32,
        0, 0, 32, 0, 0, 33, 0, 0, 34, 0, 0, 35, 0, 0, 36, 0, 0, 36, 0, 0, 37, 0, 0,
        38, 0, 0, 39, 0, 0, 40, 0, 0, 40, 0, 0, 41, 0, 0, 42, 0, 0, 43, 0, 0, 44,
        0, 0, 45, 0, 0, 46, 1, 0, 47, 1, 0, 48, 2, 0, 49, 2, 0, 50, 3, 0, 51, 3, 0,
        52, 4, 0, 53, 4, 0, 54, 5, 0, 55, 5, 0, 56, 6, 0, 57, 6, 0, 58, 7, 0, 59,
        7, 0, 60, 8, 0, 61, 8, 0, 63, 9, 0, 63, 9, 0, 63, 10, 0, 63, 10, 0, 63, 11,
        0, 63, 11, 0, 63, 12, 0, 63, 12, 0, 63, 13, 0, 63, 13, 0, 63, 14, 0, 63,
        14, 0, 63, 15, 0, 63, 15, 0, 63, 16, 0, 63, 16, 0, 63, 17, 0, 63, 17, 0,
        63, 18, 0, 63, 18, 0, 63, 19, 0, 63, 19, 0, 63, 20, 0, 63, 20, 0, 63, 21,
        0, 63, 21, 0, 63, 22, 0, 63, 22, 0, 63, 23, 0, 63, 24, 0, 63, 24, 0, 63,
        25, 0, 63, 25, 0, 63, 26, 0, 63, 26, 0, 63, 27, 0, 63, 27, 0, 63, 28, 0,
        63, 28, 0, 63, 29, 0, 63, 29, 0, 63, 30, 0, 63, 30, 0, 63, 31, 0, 63, 31,
        0, 63, 32, 0, 63, 32, 0, 63, 33, 0, 63, 33, 0, 63, 34, 0, 63, 34, 0, 63,
        35, 0, 63, 35, 0, 63, 36, 0, 63, 36, 0, 63, 37, 0, 63, 38, 0, 63, 38, 0,
        63, 39, 0, 63, 39, 0, 63, 40, 0, 63, 40, 0, 63, 41, 0, 63, 41, 0, 63, 42,
        0, 63, 42, 0, 63, 43, 0, 63, 43, 0, 63, 44, 0, 63, 44, 0, 63, 45, 0, 63,
        45, 0, 63, 46, 0, 63, 46, 0, 63, 47, 0, 63, 47, 0, 63, 48, 0, 63, 48, 0,
        63, 49, 0, 63, 49, 0, 63, 50, 0, 63, 50, 0, 63, 51, 0, 63, 52, 0, 63, 52,
        0, 63, 52, 0, 63, 52, 0, 63, 52, 0, 63, 53, 0, 63, 53, 0, 63, 53, 0, 63,
        53, 0, 63, 54, 0, 63, 54, 0, 63, 54, 0, 63, 54, 0, 63, 54, 0, 63, 55, 0,
        63, 55, 0, 63, 55, 0, 63, 55, 0, 63, 56, 0, 63, 56, 0, 63, 56, 0, 63, 56,
        0, 63, 57, 0, 63, 57, 0, 63, 57, 0, 63, 57, 0, 63, 57, 0, 63, 58, 0, 63,
        58, 0, 63, 58, 0, 63, 58, 0, 63, 59, 0, 63, 59, 0, 63, 59, 0, 63, 59, 0,
        63, 60, 0, 63, 60, 0, 63, 60, 0, 63, 60, 0, 63, 60, 0, 63, 61, 0, 63, 61,
        0, 63, 61, 0, 63, 61, 0, 63, 62, 0, 63, 62, 0, 63, 62, 0, 63, 62, 0, 63,
        63, 0, 63, 63, 1, 63, 63, 2, 63, 63, 3, 63, 63, 4, 63, 63, 5, 63, 63, 6,
        63, 63, 7, 63, 63, 8, 63, 63, 9, 63, 63, 10, 63, 63, 10, 63, 63, 11, 63,
        63, 12, 63, 63, 13, 63, 63, 14, 63, 63, 15, 63, 63, 16, 63, 63, 17, 63, 63,
        18, 63, 63, 19, 63, 63, 20, 63, 63, 21, 63, 63, 21, 63, 63, 22, 63, 63, 23,
        63, 63, 24, 63, 63, 25, 63, 63, 26, 63, 63, 27, 63, 63, 28, 63, 63, 29, 63,
        63, 30, 63, 63, 31, 63, 63, 31, 63, 63, 32, 63, 63, 33, 63, 63, 34, 63, 63,
        35, 63, 63, 36, 63, 63, 37, 63, 63, 38, 63, 63, 39, 63, 63, 40, 63, 63, 41,
        63, 63, 42, 63, 63, 42, 63, 63, 43, 63, 63, 44, 63, 63, 45, 63, 63, 46, 63,
        63, 47, 63, 63, 48, 63, 63, 49, 63, 63, 50, 63, 63, 51, 63, 63, 52, 63, 63,
        52, 63, 63, 53, 63, 63, 54, 63, 63, 55, 63, 63, 56, 63, 63, 57, 63, 63, 58,
        63, 63, 59, 63, 63, 60, 63, 63, 61, 63, 63, 62, 63, 63, 63,
    ]);
    vec
});
const MAXTABLE: usize = 256 * 5;

/// Scale that takes the table's 0..63 range to 0..255.
const PALETTE_GAIN: f32 = 4.047619;

/// Highest intensity the palette is used at.
///
/// The table's top entries walk out of yellow and into white, ending at
/// `(63, 63, 63)`, which `PALETTE_GAIN` turns into `(254, 254, 254)`. Every cell
/// above intensity 187 was therefore drawn as a near-white block -- and the core
/// of a large flame is almost entirely above 187, so the brightest part of the
/// effect was a slab of white rather than a hot colour.
///
/// 187 is the last table entry with no blue channel at all, i.e. pure yellow,
/// and yellow is what the hottest part of a flame actually looks like. Capping
/// the index there rather than editing the table keeps the table honest: the
/// white is still in it, the effect just never reaches it.
const HOTTEST: usize = 187;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct FireOptions {
    pub use_colors: bool,
    /// Seed for the combustion noise that seeds new fires along the bottom row.
    pub seed: u64,
}

impl Default for FireOptions {
    /// Hand-written so it is the single source of truth.
    ///
    /// The builder carried the real defaults while the derived `Default`
    /// produced zeros, and serde used the derived one, so a config file
    /// that omitted a section silently zeroed it.
    fn default() -> Self {
        Self {
            use_colors: true,
            seed: DEFAULT_SEED,
        }
    }
}

/// One combustion iteration is modelled as taking a fixed slice of wall clock.
/// Real elapsed time is accumulated and spent in whole quanta, so the fire
/// burns at the same rate on any refresh rate and honours the speed keys.
const STEP_QUANTUM: f32 = 1.0 / 60.0;
/// Upper bound on catch-up work per frame, so a long stall cannot lock up.
const MAX_STEPS_PER_FRAME: usize = 4;

pub struct Fire {
    pub screen_size: (u16, u16),
    options: FireOptions,
    canvas: Canvas,
    color_palette: Vec<style::Color>,
    fire_bitmap: Vec<u8>,     // fire bitmap
    intensity_table: Vec<u8>, // Fire intensity lookup table
    loop_counter: i32,        // Animation loop counter
    sloop_counter: i32,       // Secondary loop counter
    height_counter: u32,      // Height counter for fire growth
    step_accumulator: f32,    // Elapsed time not yet spent on a combustion step
    /// The intensity-to-glyph mapping, cached so the per-cell draw does not
    /// rebuild it. See [`presets::FLAME`].
    ///
    /// ## The leading space, which looks like the bug the glyph ramp documents
    ///
    /// [`presets::FLAME`] starts with a space, and the glyph ramp's own docs say a
    /// ramp for a filled region must not: the sparsest step lands on the row at
    /// the top of the region, and a space there makes the region invisible
    /// against whatever is behind it. That is a real rule and this ramp does not
    /// break it, because the field is not a filled region.
    ///
    /// A flame is a *sparse* field. Intensity 0 is not the faint end of a solid
    /// body of fire, it is the gap between two tongues of flame and the empty air
    /// above them, and it is the majority of the frame. Drawing it as `Cell::
    /// default` rather than as a coloured space is worth a note on its own: a
    /// space in a ramp colour still costs a colour on the wire, and the majority
    /// of a fire frame is that case.
    glyphs: GlyphRamp,
    rng: EffectRng,
}

impl TerminalEffect for Fire {
    fn get_diff(&mut self) -> Vec<(usize, usize, Cell)> {
        self.draw_fire();
        self.canvas.commit()
    }

    fn update(&mut self) {
        self.advance(STEP_QUANTUM as f64);
    }

    fn update_with_context(&mut self, context: &crate::runtime::FrameContext) {
        self.advance(context.delta.as_secs_f64());
    }

    fn update_size(&mut self, width: u16, height: u16) {
        self.screen_size = (width, height);
        self.reset();
    }

    fn reset(&mut self) {
        let width = self.screen_size.0 as usize;
        let height = self.screen_size.1 as usize;

        // A resize invalidates the frame on screen, so the canvas blanks its
        // baseline and the next commit repaints in full.
        self.canvas.resize(width as u16, height as u16);

        // Initialize fire bitmap (double the width and height for better resolution)
        let bitmap_width = width * 2;
        let bitmap_height = height * 2;
        self.fire_bitmap = vec![0; bitmap_width * bitmap_height];

        // Generate the intensity table
        self.generate_intensity_table();

        // Reseeded with the rest of the state this function already rebuilds,
        // so a resize restarts the combustion noise rather than continuing the
        // old sequence against a blank bitmap.
        self.rng = seeded_rng(self.options.seed, "fire");

        // Reset animation counters
        self.loop_counter = 0;
        self.sloop_counter = 0;
        self.height_counter = 0;
    }
}

impl Fire {
    pub fn new(options: FireOptions, screen_size: (u16, u16)) -> Self {
        let width = screen_size.0 as usize;
        let height = screen_size.1 as usize;
        let canvas = Canvas::new(screen_size.0, screen_size.1);

        // Create color palette from RGB values
        let mut color_palette = Vec::with_capacity(256);
        for i in 0..256 {
            let r = (PALETTE[i * 3] as f32 * PALETTE_GAIN) as u8;
            let g = (PALETTE[i * 3 + 1] as f32 * PALETTE_GAIN) as u8;
            let b = (PALETTE[i * 3 + 2] as f32 * PALETTE_GAIN) as u8;
            color_palette.push(style::Color::Rgb { r, g, b });
        }

        // Initialize fire bitmap (double the width and height)
        let bitmap_width = width * 2;
        let bitmap_height = height * 2;
        let fire_bitmap = vec![0; bitmap_width * bitmap_height];

        // Initialize intensity table
        let intensity_table = vec![0; MAXTABLE];

        let mut fire = Fire {
            screen_size,
            rng: seeded_rng(options.seed, "fire"),
            options,
            canvas,
            color_palette,
            fire_bitmap,
            intensity_table,
            loop_counter: 0,
            sloop_counter: 0,
            height_counter: 0,
            step_accumulator: 0.0,
            glyphs: GlyphRamp::from_text(glyph_presets::FLAME),
        };

        // Generate the intensity table
        fire.generate_intensity_table();

        fire
    }

    /// Spends elapsed time on whole combustion steps.
    fn advance(&mut self, delta: f64) {
        self.step_accumulator += delta as f32;
        let mut steps = 0;
        while self.step_accumulator >= STEP_QUANTUM && steps < MAX_STEPS_PER_FRAME {
            self.step_accumulator -= STEP_QUANTUM;
            self.combust();
            steps += 1;
        }
        if steps == MAX_STEPS_PER_FRAME {
            self.step_accumulator = 0.0;
        }
    }

    /// A single combustion iteration.
    fn combust(&mut self) {
        self.height_counter += 1;
        self.loop_counter -= 1;

        if self.loop_counter < 0 {
            self.loop_counter = self.rng.random_range(0..3);
            self.sloop_counter += 1;
        }

        self.generate_fire_base();
        self.propagate_fire();
    }

    fn generate_intensity_table(&mut self) {
        let height = self.screen_size.1 as usize * 2;
        let minus = if height > 0 { 800 / height } else { 1 };

        for i in 0..MAXTABLE {
            if i > minus {
                let p2 = (i - minus) / 5;
                self.intensity_table[i] = p2 as u8;
            } else {
                self.intensity_table[i] = 0;
            }
        }
    }

    fn propagate_fire(&mut self) {
        let width = self.screen_size.0 as usize * 2;
        let height = self.screen_size.1 as usize * 2;

        // Skip last row since bitmap has look-ahead
        for y in 0..height - 1 {
            for x in 1..width - 1 {
                let idx = y * width + x;

                if idx >= self.fire_bitmap.len()
                    || idx + width >= self.fire_bitmap.len()
                {
                    continue;
                }

                // Calculate the new value based on surrounding pixels
                let sum = self.fire_bitmap[idx + width - 1] as usize
                    + self.fire_bitmap[idx + width + 1] as usize
                    + self.fire_bitmap[idx + width] as usize;

                // Add pixels from two rows below
                let two_rows = idx + 2 * width;
                let additional = if two_rows < self.fire_bitmap.len() {
                    self.fire_bitmap[two_rows - 1] as usize
                        + self.fire_bitmap[two_rows + 1] as usize
                } else {
                    0
                };

                let total = sum + additional;
                if total < MAXTABLE {
                    self.fire_bitmap[idx] = self.intensity_table[total];
                }
            }
        }
    }

    fn generate_fire_base(&mut self) {
        // Reuse the effect's own generator rather than constructing a fresh
        // thread-local one on every combustion step.
        let rng = &mut self.rng;
        let width = self.screen_size.0 as usize * 2;
        let height = self.screen_size.1 as usize * 2;

        // Start with base row
        let base_row = height - 1;
        let mut x = 0;

        while x < width {
            let i1 = 1 + x * 4;
            let i2 = 4 * width + 1 - x * 4;
            // `height_counter` is 0 before the first step, and `min_val` is the
            // exclusive upper end of a range, so it cannot be 0. A terminal one
            // row tall also makes `base_row` 1, which is why the rows above are
            // taken with `saturating_sub` rather than a bare `- 2`.
            let min_val = i1.min(i2).min(self.height_counter as usize).max(1);
            let last1 = rng.random_range(0..min_val) as u8;

            let count = rng.random_range(0..6);

            for i in 0..count {
                if x + i >= width {
                    break;
                }

                // Set current pixel
                let idx = base_row * width + x + i;
                if idx < self.fire_bitmap.len() {
                    self.fire_bitmap[idx] = last1;
                }

                // Set pixel one row up with slightly varied intensity
                let one_up = base_row.saturating_sub(1) * width + x + i;
                if one_up < self.fire_bitmap.len() {
                    let intensity = last1 as i16 + rng.random_range(-2..4) as i16;
                    self.fire_bitmap[one_up] = intensity.clamp(0, 255) as u8;
                }

                // Set pixel two rows up with more varied intensity
                let two_up = base_row.saturating_sub(2) * width + x + i;
                if two_up < self.fire_bitmap.len() {
                    let intensity = last1 as i16 + rng.random_range(-2..4) as i16;
                    self.fire_bitmap[two_up] = intensity.clamp(0, 255) as u8;
                }
            }

            x += count;
        }
    }

    /// Maps the fire bitmap onto the canvas, one cell per 2x2 bitmap block.
    fn draw_fire(&mut self) {
        self.canvas.clear();

        // Map fire bitmap to terminal cells
        for y in 0..self.screen_size.1 as usize {
            for x in 0..self.screen_size.0 as usize {
                // Sample from the fire bitmap
                let fire_x = x * 2;
                let fire_y = y * 2;
                let width = self.screen_size.0 as usize * 2;

                if fire_y * width + fire_x < self.fire_bitmap.len() {
                    let intensity =
                        self.fire_bitmap[fire_y * width + fire_x] as usize;

                    // Indexed on **the same 0..HOTTEST scale as the colour**,
                    // which is the fix for a miscalibration the first version of
                    // this ramp had.
                    //
                    // Indexing the glyph on the bitmap's full 0..255 while the
                    // colour used 0..187 looks like a harmless detail and is not:
                    // the bitmap's distribution is heavily skewed to the cold end,
                    // so a 9-entry ramp spread over 0..255 puts its first step at
                    // 16 and its last at 240. Measured on a settled fire at 400x200,
                    // 75.7% of all cells are intensity 0-9 and 0.01% reach 190 --
                    // so a quarter of the *visible* flame drew as a single `▁`,
                    // and `▇` and `█` were never drawn at all on any terminal.
                    //
                    // One scale for both. Measured the same way, the hottest cell
                    // in a settled fire is 193, above `HOTTEST`, so the top of the
                    // ramp is now reachable and the top of the colour ramp is
                    // where the top of the glyph ramp is.
                    let scaled = intensity.min(HOTTEST) as f32 / HOTTEST as f32;
                    let character = self.glyphs.sample(scaled);

                    // A blank is a blank, in either colour mode. The
                    // `use_colors = false` branch used to hand back
                    // `Color::White` for these as well as for the glyphs, so the
                    // cold part of the frame was a field of white spaces: a slab
                    // of white on a light profile and nothing at all on a dark
                    // one, which is the opposite of the plain ASCII fire the
                    // option is meant to give.
                    let cell = if character == ' ' {
                        Cell::default()
                    } else {
                        // `Color::Reset` rather than white when colour is off:
                        // "no colours" means the terminal's own foreground, not
                        // the one that happens to be in the palette.
                        let fg_color = if self.options.use_colors
                            && intensity < self.color_palette.len()
                        {
                            self.color_palette[intensity.min(HOTTEST)]
                        } else {
                            style::Color::Reset
                        };

                        // `Attribute::Reset`, not `Attribute::Bold`. Every cell
                        // used to be bold, and bold on a truecolor foreground is
                        // a brightening hint that many terminals act on, which
                        // pushes the hot end of a ramp toward white.
                        Cell::new(character, fg_color, style::Attribute::Reset)
                    };

                    self.canvas.set(x, y, cell);
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_hottest_colour_the_effect_can_draw_is_yellow_not_white() {
        let fire = Fire::new(FireOptions::default(), (20, 10));

        // Scanned over the range the effect indexes, not the whole table: the
        // table's top entries are white by design and the cap is what stops the
        // effect reaching them. If the cap goes, this fails.
        let reachable = fire.color_palette.len().min(HOTTEST + 1);
        for (index, color) in fire.color_palette.iter().take(reachable).enumerate()
        {
            let style::Color::Rgb { r, g, b } = *color else {
                panic!("palette entry {index} is not truecolor: {color:?}");
            };
            assert!(
                r.min(g).min(b) < 200,
                "palette entry {index} is ({r}, {g}, {b}): close enough to white \
                 that the core of a flame reads as a white block"
            );
        }

        // And the cap is at the top of the table's yellow, not merely somewhere
        // short of the white.
        let style::Color::Rgb { r, g, b } = fire.color_palette[HOTTEST] else {
            unreachable!("the palette is built as truecolor");
        };
        assert!(
            r > 200 && g > 200 && b < 32,
            "the hottest entry is ({r}, {g}, {b}), which is not hot yellow"
        );
    }

    #[test]
    fn a_settled_fire_never_puts_a_near_white_or_a_bold_cell_on_screen() {
        let mut fire = Fire::new(FireOptions::default(), (40, 12));
        for _ in 0..180 {
            fire.update();
            fire.get_diff();
        }

        let mut hottest: Option<u8> = None;
        for cell in fire.canvas.on_screen().buffer.iter() {
            assert_eq!(
                cell.attr,
                style::Attribute::Reset,
                "cell {:?} is still bold, which brightens the hot end of the ramp",
                cell.symbol
            );
            let style::Color::Rgb { r, g, b } = cell.color else {
                continue;
            };
            let lo = r.min(g).min(b);
            if hottest.is_none_or(|best| lo > best) {
                hottest = Some(lo);
            }
        }

        // The brightest thing in the effect is a hot yellow, not a white block.
        // Before the cap the core was `(254, 254, 254)` and this is 254.
        let hottest = hottest.expect("nothing was drawn at all");
        assert!(
            hottest < 64,
            "the brightest cell on screen has every channel at {hottest} or above, \
             which is white"
        );
    }

    #[test]
    fn without_colours_a_dead_cell_is_a_blank_rather_than_a_white_space() {
        let mut fire = Fire::new(
            FireOptions {
                use_colors: false,
                seed: 7,
            },
            (40, 12),
        );
        for _ in 0..120 {
            fire.update();
            fire.get_diff();
        }

        let blanks: Vec<Cell> = fire
            .canvas
            .on_screen()
            .buffer
            .iter()
            .copied()
            .filter(|cell| cell.symbol == ' ')
            .collect();

        assert!(
            !blanks.is_empty(),
            "the fixture produced no dead cells, so there was nothing to check"
        );
        for cell in blanks {
            assert_ne!(
                cell.color,
                style::Color::White,
                "a dead cell was painted as a white space"
            );
            assert_eq!(
                cell,
                Cell::default(),
                "a dead cell is not the blank the rest of the crate clears to"
            );
        }
    }

    /// The glyph for an intensity, taking the effect's own calibration.
    fn glyph_for(fire: &Fire, intensity: usize) -> char {
        let scaled = intensity.min(HOTTEST) as f32 / HOTTEST as f32;
        fire.glyphs.sample(scaled)
    }

    /// The glyph ramp is indexed on the colour ramp's scale, and nothing else.
    ///
    /// Not a test of the picture -- a test of the *calibration*, which is where
    /// the defect was. The two used to be indexed on different ranges (the glyph
    /// on the bitmap's 0..255, the colour on 0..`HOTTEST`), and because the
    /// bitmap's distribution is heavily skewed to the cold end that put the
    /// ramp's first step at 16 and its last at 240, so a quarter of the visible
    /// flame drew as one glyph and the top two were never drawn at all.
    ///
    /// Asserted as the mapping rather than as a threshold, so it cannot be
    /// satisfied by nudging a number. The *reachability* half of the claim -- that
    /// a real fire actually gets to the top -- is
    /// `a_settled_fire_reaches_the_top_of_the_ramp_and_the_middle_of_it`, because
    /// it needs the simulation and not just the table.
    #[test]
    fn the_glyph_and_the_colour_share_one_scale() {
        let fire = Fire::new(FireOptions::default(), (20, 10));

        // The scale is clamped at HOTTEST, so the two ends are the interesting
        // cases: at the cap they must agree, and above it both must hold.
        assert_eq!(glyph_for(&fire, HOTTEST), fire.glyphs.sample(1.0));
        assert_eq!(
            glyph_for(&fire, HOTTEST + 40),
            glyph_for(&fire, HOTTEST),
            "intensity above the cap must not climb the glyph ramp past its top"
        );
        assert_eq!(glyph_for(&fire, 0), ' ');

        // The last step has to be the top of the scale rather than somewhere
        // short of it, or clamping above the cap throws away the hottest glyphs
        // rather than holding them.
        let top = fire.glyphs.sample(1.0);
        assert_eq!(
            top, '█',
            "the top of the glyph ramp is {top:?}, not the full block"
        );
    }

    /// Intensity has to buy *more mark*, and the order is the whole point.
    ///
    /// The nine-arm `match` this replaced stepped backwards at the top: it ended
    /// `'@' -> '%'`, and a per-cent sign is sparser than an at-sign, so the
    /// hottest part of a flame was drawn in a lighter mark than the part below it.
    ///
    /// Ink coverage cannot be measured in a test, which the glyph ramp's module
    /// docs say outright. What *can* be asserted is that the ramp's codepoints
    /// climb, which for this particular ramp is the same statement: U+2581 to
    /// U+2587 are one-eighth increments of the same bar and U+2588 is the whole
    /// box, so the codepoint order is the ink order. That is the property
    /// `SHADE` lacks and this ramp was added for.
    #[test]
    fn the_glyph_ramp_climbs_and_never_repeats_a_step() {
        let fire = Fire::new(FireOptions::default(), (20, 10));
        let levels = fire.glyphs.len();
        assert!(levels >= 8, "the ramp has only {levels} steps");

        let mut seen = Vec::new();
        for step in 0..levels {
            let glyph = fire.glyphs.sample(step as f32 / (levels - 1) as f32);
            assert!(
                !seen.contains(&glyph),
                "step {step} repeated the glyph {glyph:?}, so the ramp has fewer \
                 distinct steps than it has entries"
            );
            seen.push(glyph);
        }
        assert_eq!(seen[0], ' ', "a zero-intensity cell must be a blank");
        assert_eq!(
            seen[levels - 1],
            '█',
            "the top of the ramp must be the full block, not {}",
            seen[levels - 1]
        );

        for pair in seen.windows(2) {
            let (a, b) = (pair[0] as u32, pair[1] as u32);
            assert!(
                b > a,
                "{:?} at U+{a:04X} is followed by {:?} at U+{b:04X}, so the ramp \
                 draws less mark as intensity rises",
                pair[0],
                pair[1]
            );
        }
    }

    /// A real fire reaches the top of the ramp, and uses more than two steps.
    ///
    /// Both halves are the calibration from the other direction, and they are
    /// opposite failures: a ramp the field never reaches wastes its top, and a
    /// field that only ever hits two steps means the scale is too coarse and the
    /// flame is banded. Measured on a settled 400x200 fire the hottest cell is
    /// 193 -- above `HOTTEST` at 187, which is why the shared scale is the one
    /// that works -- and the distribution runs 0-9 for three quarters of the
    /// frame and out past 150 for a small hot core.
    #[test]
    fn a_settled_fire_reaches_the_top_of_the_ramp_and_the_middle_of_it() {
        let mut fire = Fire::new(FireOptions::default(), (200, 50));
        for _ in 0..200 {
            fire.update();
            fire.get_diff();
        }

        let (width, height) = fire.screen_size;
        let stride = width as usize * 2;
        let mut highest = 0usize;
        let mut glyphs_used = std::collections::BTreeSet::new();
        for y in 0..height as usize {
            for x in 0..width as usize {
                let value = fire.fire_bitmap[(y * 2) * stride + x * 2] as usize;
                highest = highest.max(value);
                if value > 0 {
                    glyphs_used.insert(glyph_for(&fire, value));
                }
            }
        }

        assert!(
            highest >= HOTTEST,
            "the hottest cell in a settled fire is {highest}, below the cap at \
             {HOTTEST}, so the top of the ramp is never drawn"
        );
        assert!(
            glyphs_used.len() >= 4,
            "the visible flame only ever used {} distinct glyphs ({:?}), so the \
             ramp is banded",
            glyphs_used.len(),
            glyphs_used
        );
    }
}