add notes

Author: raphamorim

sugarloaf/src/font/cjk_metrics_tests.rs

@@ -114,6 +114,25 @@ mod tests {
                 },
             }
         }
+
+        fn noto_color_emoji() -> Self {
+            Self {
+                name: "Noto Color Emoji",
+                face: FaceMetrics {
+                    cell_width: 20.0, // Emoji are typically double-width
+                    ascent: 14.0,
+                    descent: 3.5,
+                    line_gap: 1.0,
+                    underline_position: Some(-2.0),
+                    underline_thickness: Some(1.2),
+                    strikethrough_position: Some(7.0),
+                    strikethrough_thickness: Some(1.2),
+                    cap_height: Some(10.5),
+                    ex_height: Some(7.0),
+                    ic_width: None,
+                },
+            }
+        }
     }
 
     #[test]
@@ -866,4 +885,130 @@ mod tests {
             "Mixed content must not affect total height calculations"
         );
     }
+
+    /// Test edge cases for font metrics calculations
+    #[test]
+    fn test_edge_cases() {
+        // Test extremely small font size
+        let tiny_font = FaceMetrics {
+            cell_width: 0.1,
+            ascent: 0.1,
+            descent: 0.05,
+            line_gap: 0.01,
+            underline_position: Some(-0.01),
+            underline_thickness: Some(0.01),
+            strikethrough_position: Some(0.05),
+            strikethrough_thickness: Some(0.01),
+            cap_height: Some(0.08),
+            ex_height: Some(0.05),
+            ic_width: None,
+        };
+
+        let tiny_metrics = Metrics::calc(tiny_font);
+        assert!(
+            tiny_metrics.cell_width >= 1,
+            "Cell width must be at least 1 pixel"
+        );
+        assert!(
+            tiny_metrics.cell_height >= 1,
+            "Cell height must be at least 1 pixel"
+        );
+        assert!(
+            tiny_metrics.underline_thickness >= 1,
+            "Line thickness must be at least 1 pixel"
+        );
+
+        // Test extremely large font size
+        let huge_font = FaceMetrics {
+            cell_width: 1000.0,
+            ascent: 1200.0,
+            descent: 300.0,
+            line_gap: 100.0,
+            underline_position: Some(-100.0),
+            underline_thickness: Some(100.0),
+            strikethrough_position: Some(600.0),
+            strikethrough_thickness: Some(100.0),
+            cap_height: Some(900.0),
+            ex_height: Some(600.0),
+            ic_width: None,
+        };
+
+        let huge_metrics = Metrics::calc(huge_font);
+        assert_eq!(
+            huge_metrics.cell_width, 1000,
+            "Large font metrics should be preserved"
+        );
+        assert_eq!(
+            huge_metrics.cell_height, 1700,
+            "Large font height calculation"
+        );
+
+        // Test font with missing optional metrics
+        let minimal_font = FaceMetrics {
+            cell_width: 10.0,
+            ascent: 12.0,
+            descent: 3.0,
+            line_gap: 1.0,
+            underline_position: None,
+            underline_thickness: None,
+            strikethrough_position: None,
+            strikethrough_thickness: None,
+            cap_height: None,
+            ex_height: None,
+            ic_width: None,
+        };
+
+        let minimal_metrics = Metrics::calc(minimal_font);
+        assert!(
+            minimal_metrics.underline_thickness >= 1,
+            "Default underline thickness"
+        );
+        assert!(
+            minimal_metrics.strikethrough_thickness >= 1,
+            "Default strikethrough thickness"
+        );
+        assert!(
+            minimal_metrics.underline_position > 0,
+            "Default underline position"
+        );
+        assert!(
+            minimal_metrics.strikethrough_position > 0,
+            "Default strikethrough position"
+        );
+    }
+
+    /// Test mixed script rendering (Latin + CJK + Emoji)
+    #[test]
+    fn test_mixed_script_rendering() {
+        let latin_font = TestFontData::cascadia_code();
+        let cjk_font = TestFontData::noto_sans_cjk();
+        let emoji_font = TestFontData::noto_color_emoji();
+
+        let latin_metrics = Metrics::calc(latin_font.face);
+        let cjk_metrics =
+            Metrics::calc_with_primary_cell_dimensions(cjk_font.face, &latin_metrics);
+        let emoji_metrics =
+            Metrics::calc_with_primary_cell_dimensions(emoji_font.face, &latin_metrics);
+
+        // All fonts should have the same cell height for consistent rendering
+        assert_eq!(latin_metrics.cell_height, cjk_metrics.cell_height);
+        assert_eq!(latin_metrics.cell_height, emoji_metrics.cell_height);
+
+        // All fonts should have the same baseline
+        assert_eq!(latin_metrics.cell_baseline, cjk_metrics.cell_baseline);
+        assert_eq!(latin_metrics.cell_baseline, emoji_metrics.cell_baseline);
+
+        // Verify that a line containing all three scripts renders consistently
+        let mixed_line_height = latin_metrics.cell_height;
+        let latin_only_height = latin_metrics.cell_height;
+        let cjk_only_height = cjk_metrics.cell_height;
+        let emoji_only_height = emoji_metrics.cell_height;
+
+        assert_eq!(
+            mixed_line_height, latin_only_height,
+            "Mixed script lines must have same height as single script lines"
+        );
+        assert_eq!(mixed_line_height, cjk_only_height);
+        assert_eq!(mixed_line_height, emoji_only_height);
+    }
 }

sugarloaf/src/font/metrics.rs

@@ -57,6 +57,13 @@ pub struct FaceMetrics {
     /// if present. This is used for font size adjustment, to normalize
     /// the width of CJK fonts mixed with latin fonts.
     ///
+    /// Why "水" (water)?
+    /// - It's a common CJK ideograph present in most CJK fonts
+    /// - Has typical width characteristics of CJK characters
+    /// - Simple structure makes it reliable for measurement
+    /// - Part of the CJK Unified Ideographs block (U+4E00-U+9FFF)
+    /// - Used as a standard reference in many font metrics systems
+    ///
     /// NOTE: IC = Ideograph Character
     pub ic_width: Option<f64>,
 }
@@ -100,6 +107,12 @@ impl FaceMetrics {
     ///
     /// This measurement is used for font size adjustment to normalize
     /// CJK fonts mixed with Latin fonts in the `calculate_cjk_font_size_adjustment` function.
+    ///
+    /// The water ideograph is chosen because:
+    /// - It has consistent width across different CJK fonts
+    /// - It's present in virtually all CJK fonts (basic kanji/hanzi)
+    /// - Its width is representative of typical CJK character width
+    /// - It avoids edge cases like punctuation or rare characters
     fn measure_cjk_character_width(
         font_ref: &crate::font_introspector::FontRef,
     ) -> Option<f64> {
@@ -142,6 +155,12 @@ impl Metrics {
 
         // Calculate baseline position from bottom of cell (adjusted for Rio's positive descent)
         // Rio uses positive descent format, baseline = half_line_gap + descent
+        //
+        // Baseline Adjustment Strategy:
+        // - The baseline is positioned consistently for all fonts (primary and secondary)
+        // - This ensures CJK characters align properly with Latin text
+        // - The half_line_gap provides breathing room above and below text
+        // - Using descent ensures proper positioning for characters with descenders
         let cell_baseline = (half_line_gap + face.descent).round();
 
         // Calculate top-to-baseline for other calculations

sugarloaf/src/font/mod.rs

@@ -241,7 +241,22 @@ impl FontLibraryData {
     }
 
     /// Get font metrics for rich text rendering (consistent metrics approach)
-    /// Primary font determines cell dimensions for all fonts
+    ///
+    /// Primary font determines cell dimensions for all fonts to ensure consistent
+    /// baseline alignment across different scripts (Latin, CJK, emoji, etc.).
+    ///
+    /// # Arguments
+    /// * `font_id` - The font to get metrics for
+    /// * `font_size` - The font size in pixels
+    ///
+    /// # Returns
+    /// A tuple of (width, height, line_height) for the font, or None if the font
+    /// cannot be found or metrics cannot be calculated.
+    ///
+    /// # Implementation Notes
+    /// - Primary font metrics are cached for performance
+    /// - Secondary fonts inherit cell dimensions from primary font
+    /// - This ensures CJK characters don't appear "higher" than Latin text
     pub fn get_font_metrics(
         &mut self,
         font_id: &usize,
@@ -254,20 +269,22 @@ impl FontLibraryData {
             if let Some(cached) = self.primary_metrics_cache.get(&size_key) {
                 *cached
             } else {
-                // Calculate primary font metrics and cache them
                 let primary_font = self.inner.get_mut(&FONT_ID_REGULAR)?;
                 let primary_metrics = primary_font.get_metrics(font_size, None)?;
                 self.primary_metrics_cache.insert(size_key, primary_metrics);
                 primary_metrics
             };
 
-        if font_id == &FONT_ID_REGULAR {
-            // Primary font uses its own metrics
-            Some(primary_metrics.for_rich_text())
-        } else {
-            // Secondary fonts use primary font's cell dimensions
-            let font = self.inner.get_mut(font_id)?;
-            font.get_rich_text_metrics(font_size, Some(&primary_metrics))
+        match font_id {
+            &FONT_ID_REGULAR => {
+                // Primary font uses its own metrics
+                Some(primary_metrics.for_rich_text())
+            }
+            _ => {
+                // Secondary fonts use primary font's cell dimensions
+                let font = self.inner.get_mut(font_id)?;
+                font.get_rich_text_metrics(font_size, Some(&primary_metrics))
+            }
         }
     }