ltk/

system_fonts.rs

// SPDX-License-Identifier: LGPL-2.1-only
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>

//! Process-wide font resolution for both backends: the primary UI font
//! ([`default_handle`] / [`primary_handle`], loaded once from the
//! [`SYSTEM_FONT_CANDIDATES`] chain) and lazy per-glyph fallback.
//!
//! The default font ([`crate::theme::fallback::FALLBACK_FONT`], Sora)
//! covers Latin and a portion of extended Latin; everything outside
//! that band — Cyrillic, Devanagari, Arabic, Hebrew, Thai, the CJK
//! ideographic block — relies on a chain of system Noto fonts loaded
//! on demand: a fallback file is read off disk the first time some
//! glyph asks for it and the resulting `Arc<FontFace>` is cached
//! process-wide.
//!
//! Each `(path, face)` entry in [`FALLBACK_FONT_CANDIDATES`] gets its
//! own `OnceLock<Option<Arc<FontFace>>>` slot. `Some(font)` means the
//! file was read and parsed successfully; `None` means it's missing
//! or unparseable, locked in for the rest of the process so we don't
//! re-`stat` the same path on every glyph miss. The `OnceLock`
//! handles concurrent first-loads correctly: at most one thread runs
//! the closure for a given slot, the rest wait for the result.
//!
//! Renderers (`SoftwareCanvas` and `GlesCanvas`) consult this module
//! through [`lookup`] in their `font_for_char` paths.

use std::sync::{ Arc, OnceLock };

use crate::font_face::FontFace;

/// Bytes-aware font handle. The `font` is what glyphs rasterise
/// against; `bytes` is the raw OpenType / TrueType buffer that
/// rustybuzz (HarfBuzz) requires for shaping. Both name the same
/// buffer — the face holds its own `Arc` so it can pull outlines in
/// later — and are kept side by side so shaping needs no second read.
///
/// `face` is the TTC sub-face index (0 for single-face files, the
/// face index for collections like Noto Sans CJK).
#[ derive( Clone ) ]
pub struct FontHandle
{
	pub font:  Arc<FontFace>,
	pub bytes: Arc<Vec<u8>>,
	pub face:  u32,
}

impl FontHandle
{
	/// The handle of a face, with the bytes it was parsed from.
	pub fn of( font: Arc<FontFace> ) -> Self
	{
		let bytes = Arc::clone( font.data() );
		let face  = font.face_index();
		Self { font, bytes, face }
	}
}

/// Per-script fallback font path with the TrueType-collection face
/// index to load (most files are single-face → 0; CJK `.ttc` archives
/// carry many faces, see the SC face on the canonical Adobe-built
/// `NotoSansCJK-Regular.ttc`). A path that does not exist is looked up by
/// its file name in the resource directory's `fonts/`, which is where a
/// browser finds the fallbacks a page bundles.
struct FallbackFontSpec
{
	path: &'static str,
	face: u32,
}

/// Ordered fallback chain consulted on a glyph miss. Order matters:
/// the first slot whose font owns a non-zero glyph index for the
/// codepoint wins, so the broadest families come first (Noto Sans
/// covers Cyrillic, Greek, extended Latin) and the script-specific
/// and CJK packs trail. DejaVu goes ahead of the CJK collection: it owns
/// the geometric shapes, arrows and box drawing that would otherwise
/// pull a 19 MB collection in for a single bullet.
#[ cfg( not( any( target_os = "android", windows ) ) ) ]
const FALLBACK_FONT_CANDIDATES: &[ FallbackFontSpec ] =
&[
	// Noto Sans — Cyrillic, Greek, extended Latin.
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSans-Regular.ttf",       face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/noto/NotoSans-Regular.ttf",                face: 0 },

	// Devanagari (Hindi).
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansDevanagari-Regular.ttf", face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/noto/NotoSansDevanagari-Regular.ttf",          face: 0 },

	// Arabic, Hebrew, Thai — common scripts cheap to keep.
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansArabic-Regular.ttf",  face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansHebrew-Regular.ttf",  face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansThai-Regular.ttf",    face: 0 },

	// DejaVu — broad-but-shallow coverage of most scripts, plus the
	// symbol, arrow and box-drawing blocks. Ships almost everywhere.
	FallbackFontSpec { path: "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",            face: 0 },

	// Symbols DejaVu lacks: media controls, extra arrows and shapes.
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansSymbols2-Regular.ttf", face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoSansSymbols-Regular.ttf",  face: 0 },

	// Colour emoji, flags included; its glyphs are bitmaps (FontFace::color_glyph).
	FallbackFontSpec { path: "/usr/share/fonts/truetype/noto/NotoColorEmoji.ttf",          face: 0 },
	FallbackFontSpec { path: "/usr/share/fonts/noto/NotoColorEmoji.ttf",                   face: 0 },

	// CJK packs ship as `.ttc`. The collection layout on the canonical
	// Adobe-built `NotoSansCJK-Regular.ttc` is 0=JP, 1=KR, 2=SC, 3=TC,
	// 4=HK; we want CJK shared ideographs available in any locale, so
	// any of the faces is fine — pick SC (face 2) as the broadest
	// baseline. Last, because probing a slot reads its whole file, and
	// this one is 19 MB.
	FallbackFontSpec { path: "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",     face: 2 },
	FallbackFontSpec { path: "/usr/share/fonts/opentype/noto-cjk/NotoSansCJK-Regular.ttc", face: 2 },
	FallbackFontSpec { path: "/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",          face: 2 },
];

/// The same chain over Android's `/system/fonts`, whose file names have held across releases; Devanagari changed to a variable font in Android 12.
#[ cfg( target_os = "android" ) ]
const FALLBACK_FONT_CANDIDATES: &[ FallbackFontSpec ] =
&[
	FallbackFontSpec { path: "/system/fonts/Roboto-Regular.ttf",                       face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansDevanagari-VF.ttf",                face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansDevanagari-Regular.otf",           face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoNaskhArabic-Regular.ttf",              face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansHebrew-Regular.ttf",               face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansThai-Regular.ttf",                 face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansSymbols-Regular-Subsetted.ttf",    face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansSymbols-Regular-Subsetted2.ttf",   face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoColorEmoji.ttf",                       face: 0 },
	FallbackFontSpec { path: "/system/fonts/NotoSansCJK-Regular.ttc",                  face: 2 },
];

/// The same chain over the fonts every Windows 10 and 11 installs; Nirmala UI is a collection since Windows 11.
#[ cfg( windows ) ]
const FALLBACK_FONT_CANDIDATES: &[ FallbackFontSpec ] =
&[
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\segoeui.ttf",  face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\Nirmala.ttc",  face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\Nirmala.ttf",  face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\LeelawUI.ttf", face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\seguisym.ttf", face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\seguiemj.ttf", face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\malgun.ttf",   face: 0 },
	FallbackFontSpec { path: "C:\\Windows\\Fonts\\msyh.ttc",     face: 0 },
];

/// Per-slot lazy state, two stages so probing a slot for coverage never
/// builds a face: `bytes` is the file read once, `font` is the face
/// built only when a glyph in this slot is actually needed. `None` in a
/// resolved stage is a sticky negative result.
struct Slot
{
	bytes: OnceLock<Option<Arc<Vec<u8>>>>,
	font:  OnceLock<Option<FontHandle>>,
}

fn slots() -> &'static [ Slot ]
{
	static SLOTS: OnceLock<Vec<Slot>> = OnceLock::new();
	SLOTS.get_or_init( ||
	{
		( 0..FALLBACK_FONT_CANDIDATES.len() )
			.map( |_| Slot { bytes: OnceLock::new(), font: OnceLock::new() } )
			.collect()
	} )
}

fn slot_bytes( idx: usize ) -> Option<Arc<Vec<u8>>>
{
	slots()[ idx ].bytes.get_or_init( ||
	{
		crate::resources::read_font( std::path::Path::new( FALLBACK_FONT_CANDIDATES[ idx ].path ) ).ok().map( Arc::new )
	} )
		.clone()
}

/// Whether slot `idx` owns a glyph for `ch`, answered from the `cmap`
/// alone: ttf-parser only touches the tables it is asked for, so this
/// stays cheap even for a multi-megabyte CJK collection.
fn slot_covers( idx: usize, ch: char ) -> bool
{
	let Some( bytes ) = slot_bytes( idx ) else { return false };
	let face = FALLBACK_FONT_CANDIDATES[ idx ].face;
	rustybuzz::ttf_parser::Face::parse( &bytes, face )
		.ok()
		.and_then( |f| f.glyph_index( ch ) )
		.is_some()
}

/// Build (once) the face for slot `idx`. The raw bytes are preserved
/// inside the handle so the same `Arc<Vec<u8>>` can be handed to
/// rustybuzz for shaping without re-reading the file.
fn slot_handle( idx: usize ) -> Option<FontHandle>
{
	slots()[ idx ].font.get_or_init( ||
	{
		let bytes = slot_bytes( idx )?;
		let face  = FALLBACK_FONT_CANDIDATES[ idx ].face;
		let font  = FontFace::from_bytes( Arc::clone( &bytes ), face )?;
		Some( FontHandle { font: Arc::new( font ), bytes, face } )
	} )
		.clone()
}

/// Find the first fallback font that has a non-zero glyph index for
/// `ch`, loading it from disk on the first hit and caching the
/// `Arc<FontFace>` for the rest of the process. Returns `None` if no
/// installed fallback covers the codepoint — the caller then paints
/// the primary font's `.notdef` rather than dropping the glyph.
pub fn lookup( ch: char ) -> Option<Arc<FontFace>>
{
	lookup_handle( ch ).map( |h| h.font )
}

/// System-font search chain for the primary UI font, ordered by preference.
/// Shared by [`find_font_opt`] and [`load_default_font_bytes`].
#[ cfg( not( any( target_os = "android", windows ) ) ) ]
const SYSTEM_FONT_CANDIDATES: &[&str] =
&[
	// Debian `fonts-sora` — the canonical path `ltk-theme-default`
	// depends on. Listed first so Sora wins as the default font
	// whenever the package is installed.
	"/usr/share/fonts/opentype/sora/Sora-Regular.otf",
	"/usr/share/fonts/truetype/sora/Sora-Regular.ttf",
	"/usr/share/fonts/sora/Sora-Regular.ttf",
	"/usr/share/fonts/TTF/Sora-Regular.ttf",
	"/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
	"/usr/share/fonts/liberation/LiberationSans-Regular.ttf",
	"/usr/share/fonts/truetype/freefont/FreeSans.ttf",
	"/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
	"/usr/share/fonts/dejavu/DejaVuSans.ttf",
	"/usr/share/fonts/TTF/DejaVuSans.ttf",
];

/// None on Android and Windows: the embedded Sora is ltk's face there, not the system's Roboto or Segoe UI.
#[ cfg( any( target_os = "android", windows ) ) ]
const SYSTEM_FONT_CANDIDATES: &[&str] = &[];

/// Resolve the first system font available from [`SYSTEM_FONT_CANDIDATES`], or
/// `None` if none exist. Used by the font registry and by tests that skip
/// gracefully on images without the usual fonts installed.
pub ( crate ) fn find_font_opt() -> Option<String>
{
	SYSTEM_FONT_CANDIDATES.iter()
		.find( |p| crate::vfs::is_file( p ) )
		.copied()
		.map( str::to_string )
}

/// Load the bytes of a default system font. Tries the candidate chain via
/// [`find_font_opt`]; falls back to the embedded
/// [`crate::theme::fallback::FALLBACK_FONT`] (Sora Regular, ~50 KB, OFL 1.1)
/// when nothing matches or the file cannot be read. Always returns usable bytes
/// so canvas construction never panics on a system without the expected fonts.
pub ( crate ) fn load_default_font_bytes() -> Vec<u8>
{
	if let Some( path ) = find_font_opt()
	{
		if let Ok( bytes ) = crate::vfs::read( &path )
		{
			return bytes;
		}
	}
	crate::theme::fallback::FALLBACK_FONT.to_vec()
}

/// The process-wide primary UI font handle — the single default every canvas
/// loads. Cached so a layer shell bringing up several surfaces parses the small
/// Sora face once rather than per surface. The per-glyph fallback chain (Noto
/// Sans / CJK / Devanagari / …) is loaded lazily through [`lookup`], not here.
pub ( crate ) fn default_handle() -> FontHandle
{
	static PRIMARY: OnceLock<FontHandle> = OnceLock::new();
	PRIMARY.get_or_init( ||
	{
		let bytes = Arc::new( load_default_font_bytes() );
		let font  = FontFace::from_bytes( Arc::clone( &bytes ), 0 ).expect( "primary font parses" );
		FontHandle { font: Arc::new( font ), bytes, face: 0 }
	} ).clone()
}

/// The process-wide primary UI font — the same default a canvas loads — for
/// standalone text measurement (e.g. an embedded measure pass with no live
/// canvas). Falls back to the bundled font when no system font is found.
pub fn primary_handle() -> FontHandle
{
	default_handle()
}

/// Bytes-aware variant of [`lookup`]. Returns the full
/// [`FontHandle`] (face + raw bytes + face index) so callers that
/// need to invoke a HarfBuzz-style shaper can do so without
/// re-reading the font file.
pub fn lookup_handle( ch: char ) -> Option<FontHandle>
{
	( 0..FALLBACK_FONT_CANDIDATES.len() )
		.find( |&idx| slot_covers( idx, ch ) )
		.and_then( slot_handle )
}

/// The monospace face, as found among the app's resources, which a page and an APK carry, and then among the system's fonts.
const MONOSPACE_BUNDLED: &str = "DejaVuSansMono.ttf";

#[ cfg( not( any( target_os = "android", windows ) ) ) ]
const MONOSPACE_CANDIDATES: &[&str] =
&[
	"/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
	"/usr/share/fonts/TTF/DejaVuSansMono.ttf",
	"/usr/share/fonts/dejavu/DejaVuSansMono.ttf",
	"/usr/share/fonts/truetype/hack/Hack-Regular.ttf",
	"/usr/share/fonts/truetype/noto/NotoSansMono-Regular.ttf",
];

#[ cfg( target_os = "android" ) ]
const MONOSPACE_CANDIDATES: &[&str] =
&[
	"/system/fonts/DroidSansMono.ttf",
	"/system/fonts/CutiveMono.ttf",
];

#[ cfg( windows ) ]
const MONOSPACE_CANDIDATES: &[&str] =
&[
	"C:\\Windows\\Fonts\\consola.ttf",
	"C:\\Windows\\Fonts\\cour.ttf",
];

/// A monospace face for text that lines up in columns, such as line numbers or a terminal; `None` when none is installed.
pub fn monospace() -> Option<Arc<FontFace>>
{
	static FACE: OnceLock<Option<Arc<FontFace>>> = OnceLock::new();
	FACE.get_or_init( ||
	{
		let bundled = crate::resource_dir().map( |dir| dir.join( "fonts" ).join( MONOSPACE_BUNDLED ) );
		let path    = bundled.into_iter()
			.chain( MONOSPACE_CANDIDATES.iter().map( std::path::PathBuf::from ) )
			.find( |path| crate::vfs::is_file( path ) )?;
		let bytes   = crate::vfs::read( path ).ok()?;
		FontFace::from_bytes( Arc::new( bytes ), 0 ).map( Arc::new )
	} ).clone()
}