//! Font parsing, metrics extraction, and subsetting.

//!

//! This module provides the core font infrastructure for text layout and PDF generation:

//! - `loading`: System font cache construction and font reload errors

//! - `mock`: Mock font implementation for testing without real font files

//! - `parsed`: Full font parsing via allsorts (outlines, metrics, shaping tables, subsetting)

#![cfg(feature = "font_loading")]

use azul_css::{AzString, U8Vec};

use rust_fontconfig::{FcFontCache, OwnedFontSource};

pub mod loading {

    #![cfg(feature = "std")]

    #![cfg(feature = "font_loading")]

    #![cfg_attr(not(feature = "std"), no_std)]

    use std::io::Error as IoError;

    use azul_css::{AzString, StringVec, U8Vec};

    use rust_fontconfig::FcFontCache;

    #[cfg(not(miri))]

    #[cfg(miri)]

    pub fn build_font_cache() -> FcFontCache {

        FcFontCache::default()

    }

    #[derive(Debug)]

    pub enum FontReloadError {

        Io(IoError, AzString),

        FontNotFound(AzString),

        FontLoadingNotActive(AzString),

    }

    impl Clone for FontReloadError {

            use self::FontReloadError::*;

            }

    }

    azul_core::impl_display!(FontReloadError, {

        Io(err, path_buf) => format!("Could not load \"{}\" - IO error: {}", path_buf.as_str(), err),

        FontNotFound(id) => format!("Could not locate system font: \"{:?}\" found", id),

        FontLoadingNotActive(id) => format!("Could not load system font: \"{:?}\": crate was not compiled with --features=\"font_loading\"", id)

    });

}

pub mod mock {

    //! Mock font implementation for testing text layout.

    //!

    //! Provides a `MockFont` that simulates font behavior without requiring

    //! actual font files, useful for unit testing text layout functionality.

    use std::collections::BTreeMap;

    use crate::text3::cache::LayoutFontMetrics;

    /// A mock font implementation for testing text layout without real fonts.

    ///

    /// This allows testing text shaping, layout, and rendering code paths

    /// without needing to load actual TrueType/OpenType font files.

    #[derive(Debug, Clone)]

    pub struct MockFont {

        /// Font metrics (ascent, descent, etc.).

        pub font_metrics: LayoutFontMetrics,

        /// Width of the space character in font units.

        pub space_width: Option<usize>,

        /// Horizontal advance widths keyed by glyph ID.

        pub glyph_advances: BTreeMap<u16, u16>,

        /// Glyph bounding box sizes (width, height) keyed by glyph ID.

        pub glyph_sizes: BTreeMap<u16, (i32, i32)>,

        /// Unicode codepoint to glyph ID mapping.

        pub glyph_indices: BTreeMap<u32, u16>,

    }

    impl MockFont {

        /// Creates a new `MockFont` with the given font metrics.

        /// Sets the space character width.

        /// Adds a horizontal advance value for a glyph.

        /// Adds a bounding box size for a glyph.

        /// Adds a Unicode codepoint to glyph ID mapping.

    }

}

pub mod parsed {

    use core::fmt;

    use std::{collections::BTreeMap, sync::Arc};

    use allsorts::{

        binary::read::ReadScope,

        font_data::FontData,

        layout::{GDEFTable, LayoutCache, LayoutCacheData, GPOS, GSUB},

        outline::{OutlineBuilder, OutlineSink},

        pathfinder_geometry::{line_segment::LineSegment2F, vector::Vector2F},

        subset::{subset as allsorts_subset, whole_font, CmapTarget, SubsetProfile},

        tables::{

            cmap::owned::CmapSubtable as OwnedCmapSubtable,

            glyf::{

                Glyph, GlyfVisitorContext, LocaGlyf, Point,

                VariableGlyfContext, VariableGlyfContextStore,

            },

            kern::owned::KernTable,

            FontTableProvider, HheaTable, MaxpTable,

        },

        tag,

    };

    use azul_core::resources::{

        GlyphOutline, GlyphOutlineOperation, OutlineCubicTo, OutlineLineTo, OutlineMoveTo,

        OutlineQuadTo, OwnedGlyphBoundingBox,

    };

    use azul_css::props::basic::FontMetrics as CssFontMetrics;

    // Mock font module for testing

    pub use crate::font::mock::MockFont;

    use crate::text3::cache::LayoutFontMetrics;

    /// Cached GSUB table for glyph substitution operations.

    pub type GsubCache = Arc<LayoutCacheData<GSUB>>;

    /// Cached GPOS table for glyph positioning operations.

    pub type GposCache = Arc<LayoutCacheData<GPOS>>;

    /// Monotonic-clock nanos since process start. Used to timestamp

    /// `ParsedFont.last_used` for LRU eviction. Cheap (single

    /// `Instant::now`); resolution is plenty fine for "did this

    /// face get touched in the last N seconds" decisions. Exposed

    /// `pub(crate)` so `FontManager::evict_unused` reads from the

    /// same clock as `last_used` writes.

        // Safe: `Instant::elapsed` against the same launch instant is

        // monotonic and never overflows in any realistic process

        // lifetime (>500 years).

        use std::sync::OnceLock;

        use std::time::Instant;

        static LAUNCH: OnceLock<Instant> = OnceLock::new();

    /// Glyph-outline decoder state. See the

    /// [`ParsedFont::loca_glyf`] field docs for the full description.

    #[derive(Clone)]

    pub(crate) enum LocaGlyfState {

        /// Ready to decode immediately, or known to have no outline

        /// data. `None` covers both CFF fonts and fonts where the

        /// loca+glyf parse failed.

        ///

        /// This variant *cannot* be evicted by

        /// [`crate::text3::cache::FontManager::evict_unused`]: there

        /// are no source bytes retained to re-decode from. The eager

        /// `from_bytes` path (tests, `with_source_bytes` PDF callers)

        /// produces this variant.

        Loaded(Option<Arc<std::sync::Mutex<LocaGlyf>>>),

        /// Font bytes retained for lazy `LocaGlyf` construction.

        ///

        /// `loaded` is `Mutex<Option<…>>` (not `OnceLock`) so an

        /// idle eviction can clear it back to `None`; the next

        /// `get_or_decode_glyph` will re-parse from `bytes`. Two-step

        /// double-check pattern in `resolve_loca_glyf` keeps the

        /// expensive `LocaGlyf::load` outside the critical section.

        Deferred {

            bytes: Arc<rust_fontconfig::FontBytes>,

            font_index: usize,

            loaded: Arc<std::sync::Mutex<Option<Arc<std::sync::Mutex<LocaGlyf>>>>>,

        },

    }

    /// Adapter that collects allsorts outline commands into our `GlyphOutline` format.

    ///

    /// Implements `OutlineSink` so it can be passed to `GlyfVisitorContext::visit()`.

    /// This handles composite glyph resolution, transforms, and variable font

    /// deltas automatically via allsorts internals.

    struct GlyphOutlineCollector {

        contours: Vec<GlyphOutline>,

        current_contour: Vec<GlyphOutlineOperation>,

    }

    impl GlyphOutlineCollector {

    }

    impl OutlineSink for GlyphOutlineCollector {

    }

    /// Parsed font data with all required tables for text layout and PDF generation.

    ///

    /// This struct holds the parsed representation of a TrueType/OpenType font,

    /// including glyph outlines, metrics, and shaping tables. It's used for:

    /// - Text layout (via GSUB/GPOS tables)

    /// - Glyph rendering (via glyf/CFF outlines)

    /// - PDF font embedding (via font metrics and subsetting)

    pub struct ParsedFont {

        /// Hash of the font bytes for caching and equality checks.

        pub hash: u64,

        /// Layout-specific font metrics (ascent, descent, line gap).

        pub font_metrics: LayoutFontMetrics,

        /// PDF-specific detailed font metrics from HEAD, HHEA, OS/2 tables.

        pub pdf_font_metrics: PdfFontMetrics,

        /// Total number of glyphs in the font (from maxp table).

        pub num_glyphs: u16,

        /// Horizontal header table (hhea) containing global horizontal metrics.

        pub hhea_table: HheaTable,

        /// Offset+length into original_bytes for hmtx table (lazy: no copy).

        pub hmtx_range: (usize, usize),

        /// Offset+length into original_bytes for vmtx table (lazy: no copy).

        pub vmtx_range: (usize, usize),

        /// Vertical header table (vhea), same format as hhea. None if font has no vertical metrics.

        pub vhea_table: Option<HheaTable>,

        /// Maximum profile table (maxp) containing glyph count and memory hints.

        pub maxp_table: MaxpTable,

        /// Raw GSUB table bytes, kept as a `Vec<u8>` (tens to low-hundreds

        /// of KiB) so the parsed `GsubCache` can be built on first shape

        /// call instead of up-front. Access via [`ParsedFont::gsub`] —

        /// that getter populates `gsub_cache_lazy` via `OnceLock` and

        /// returns a borrow.

        pub(crate) gsub_bytes: Option<Vec<u8>>,

        /// Lazy GSUB cache: populated on first [`ParsedFont::gsub`] call.

        /// `None` means "font has no GSUB table" *after* init attempt;

        /// the `OnceLock` wrapper distinguishes "not yet initialised"

        /// from "initialised to None".

        pub(crate) gsub_cache_lazy: std::sync::OnceLock<Option<GsubCache>>,

        /// Raw GPOS table bytes. Same lazy-parse arrangement as

        /// `gsub_bytes` — see [`ParsedFont::gpos`].

        pub(crate) gpos_bytes: Option<Vec<u8>>,

        /// Lazy GPOS cache, populated on first [`ParsedFont::gpos`] call.

        pub(crate) gpos_cache_lazy: std::sync::OnceLock<Option<GposCache>>,

        /// Glyph definition table (GDEF) for glyph classification.

        pub opt_gdef_table: Option<Arc<GDEFTable>>,

        /// Legacy kerning table (kern) for fonts without GPOS.

        pub opt_kern_table: Option<Arc<KernTable>>,

        /// Monotonic-clock nanos at the most recent

        /// [`ParsedFont::get_or_decode_glyph`] / `gsub()` / `gpos()`

        /// call. `0` means "never touched". Used by

        /// [`crate::text3::cache::FontManager::evict_unused`] to

        /// decide which `LocaGlyfState::Deferred` faces to release.

        pub(crate) last_used: Arc<std::sync::atomic::AtomicU64>,

        /// `true` if this font is a variable font (carries a `gvar`

        /// table). Cached at parse time so [`decode_glyph_inner`]

        /// can short-circuit the variable-context construction for

        /// the common non-variable case. Variable-glyph delta

        /// application requires the source bytes to be retained,

        /// so it only fires on the `LocaGlyfState::Deferred` path.

        pub(crate) is_variable_font: bool,

        /// Lazy outline cache. Populated on first

        /// [`ParsedFont::get_or_decode_glyph`] call per `gid`; entries

        /// are wrapped in `Arc` so callers can hold them without

        /// keeping the lock. The space glyph (and `.notdef` when

        /// present) are pre-inserted by `from_bytes_internal` so the

        /// shaper's cmap-miss path has something to render without

        /// racing with a decode.

        ///

        /// Tests that previously walked the public `glyph_records_decoded`

        /// `BTreeMap` field now call

        /// [`ParsedFont::prime_glyph_cache`] (decodes every glyph into

        /// this cache) followed by

        /// [`ParsedFont::for_each_decoded_glyph`] /

        /// [`ParsedFont::glyph_cache_snapshot`] to walk the result.

        pub(crate) glyph_cache: Arc<std::sync::RwLock<BTreeMap<u16, Arc<OwnedGlyph>>>>,

        /// Glyph outline decoder state.

        ///

        /// - `Loaded(Some(arc))`: `LocaGlyf` is already loaded (owning

        ///   its own `Box<[u8]>` copy of the loca+glyf tables) and

        ///   ready to decode glyphs. Produced by the eager `from_bytes`

        ///   constructor path (tests).

        /// - `Loaded(None)`: the font has no usable loca+glyf (CFF, or

        ///   a parse failure). Glyph outlines won't decode; the hmtx

        ///   advance fallback fills in the blanks.

        /// - `Deferred`: we retain an `Arc<[u8]>` to the full font file

        ///   and the `font_index`; the first `get_or_decode_glyph` call

        ///   parses a fresh `FontData` / `TableProvider` from those

        ///   bytes and loads `LocaGlyf`, storing the result in the

        ///   `OnceLock`. Fonts that get resolved into a chain but are

        ///   never actually rasterized pay zero decode cost — this is

        ///   the big win for pages like `excel.html` where 20+ fallback

        ///   faces load but only a handful are touched.

        pub(crate) loca_glyf: LocaGlyfState,

        /// Cached width of the space character in font units.

        pub space_width: Option<usize>,

        /// Character-to-glyph mapping (cmap subtable).

        pub cmap_subtable: Option<OwnedCmapSubtable>,

        /// Mock font data for testing (replaces real font behavior).

        pub mock: Option<Box<MockFont>>,

        /// Reverse mapping: glyph_id -> cluster text (handles ligatures like "fi").

        pub reverse_glyph_cache: std::collections::BTreeMap<u16, String>,

        /// Original font bytes — only retained for callers that need to

        /// reconstruct or subset the font (PDF export). Layout / shaping /

        /// raster never read this, so `ParsedFont::from_bytes` leaves it

        /// as `None` by default and callers opt in via

        /// [`ParsedFont::with_source_bytes`]. Shared across faces of the

        /// same `.ttc` via the `Arc<FontBytes>` that

        /// [`rust_fontconfig::FcFontCache::get_font_bytes`] returns —

        /// for disk fonts the backing is an mmap so untouched pages

        /// don't count toward RSS.

        pub original_bytes: Option<std::sync::Arc<rust_fontconfig::FontBytes>>,

        /// Font index within collection (0 for single-font files).

        pub original_index: usize,

        /// GID to CID mapping for CFF fonts (required for PDF embedding).

        pub index_to_cid: BTreeMap<u16, u16>,

        /// Font type (TrueType outlines or OpenType CFF).

        pub font_type: FontType,

        /// PostScript font name from the NAME table.

        pub font_name: Option<String>,

        /// TrueType bytecode hinting instance (mutable interpreter state).

        /// Wrapped in Mutex because hinting mutates internal state.

        /// None for CFF fonts or fonts without hinting data.

        pub hint_instance: Option<std::sync::Mutex<allsorts::hinting::HintInstance>>,

    }

    impl Clone for ParsedFont {

    }

    /// Distinguishes TrueType fonts from OpenType CFF fonts.

    ///

    /// This affects how glyph outlines are extracted and how the font

    /// is embedded in PDF documents.

    #[derive(Debug, Clone, PartialEq)]

    pub enum FontType {

        /// TrueType font with quadratic Bézier outlines in glyf table.

        TrueType,

        /// OpenType font with cubic Bézier outlines in CFF table.

        /// Contains the serialized CFF data for PDF embedding.

        OpenTypeCFF(Vec<u8>),

    }

    /// PDF-specific font metrics from HEAD, HHEA, and OS/2 tables.

    ///

    /// These metrics are used for PDF font descriptors and accurate

    /// text positioning in generated PDF documents.

    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

    #[repr(C)]

    pub struct PdfFontMetrics {

        // -- HEAD table fields --

        /// Font units per em-square (typically 1000 or 2048).

        pub units_per_em: u16,

        /// Font flags (italic, bold, fixed-pitch, etc.).

        pub font_flags: u16,

        /// Minimum x-coordinate across all glyphs.

        pub x_min: i16,

        /// Minimum y-coordinate across all glyphs.

        pub y_min: i16,

        /// Maximum x-coordinate across all glyphs.

        pub x_max: i16,

        /// Maximum y-coordinate across all glyphs.

        pub y_max: i16,

        // -- HHEA table fields --

        /// Typographic ascender (distance above baseline).

        pub ascender: i16,

        /// Typographic descender (distance below baseline, usually negative).

        pub descender: i16,

        /// Recommended line gap between lines of text.

        pub line_gap: i16,

        /// Maximum horizontal advance width across all glyphs.

        pub advance_width_max: u16,

        /// Caret slope rise for italic angle calculation.

        pub caret_slope_rise: i16,

        /// Caret slope run for italic angle calculation.

        pub caret_slope_run: i16,

        // -- OS/2 table fields (0 if table not present) --

        /// Average width of lowercase letters.

        pub x_avg_char_width: i16,

        /// Visual weight class (100-900, 400=normal, 700=bold).

        pub us_weight_class: u16,

        /// Visual width class (1-9, 5=normal).

        pub us_width_class: u16,

        /// Thickness of strikeout stroke in font units.

        pub y_strikeout_size: i16,

        /// Vertical position of strikeout stroke.

        pub y_strikeout_position: i16,

    }

    impl Default for PdfFontMetrics {

    }

    impl PdfFontMetrics {

        /// Returns zeroed metrics with `units_per_em` set to 1000 (standard PostScript default)

        /// to avoid division-by-zero in scaling calculations.

    }

    /// Result of font subsetting operation.

    ///

    /// Contains the subsetted font bytes and a mapping from original

    /// glyph IDs to new glyph IDs in the subset.

    #[derive(Debug, Clone)]

    pub struct SubsetFont {

        /// The subsetted font file bytes (smaller than original).

        pub bytes: Vec<u8>,

        /// Mapping: original glyph ID -> (new subset glyph ID, source character).

        pub glyph_mapping: BTreeMap<u16, (u16, char)>,

    }

    impl SubsetFont {

        /// Return the changed text so that when rendering with the subset font (instead of the

        /// original) the renderer will end up at the same glyph IDs as if we used the original text

        /// on the original font

                        } else {

                        }

    }

    /// Hash-based equality: two fonts are considered equal if their content hash matches.

    /// This is a performance optimization — hash collisions are possible but vanishingly

    /// unlikely (~1/2^64).

    impl PartialEq for ParsedFont {

    }

    impl Eq for ParsedFont {}

    const FONT_B64_START: &str = "data:font/ttf;base64,";

    impl serde::Serialize for ParsedFont {

            use base64::Engine;

            );

    }

    impl<'de> serde::Deserialize<'de> for ParsedFont {

            use base64::Engine;

            } else {

            };

    }

    impl fmt::Debug for ParsedFont {

                    ),

                )

    }

    /// Warning or error message generated during font parsing.

    #[derive(Debug, Clone, PartialEq, Eq)]

    pub struct FontParseWarning {

        /// Severity level of this warning.

        pub severity: FontParseWarningSeverity,

        /// Human-readable description of the issue.

        pub message: String,

    }

    /// Severity level for font parsing warnings.

    #[derive(Debug, Clone, Copy, PartialEq, Eq)]

    pub enum FontParseWarningSeverity {

        /// Informational message (not an error).

        Info,

        /// Warning that may affect font rendering.

        Warning,

        /// Error that prevents proper font usage.

        Error,

    }

    impl FontParseWarning {

        /// Creates an info-level message.

        /// Creates a warning-level message.

        /// Creates an error-level message.

    }

    impl ParsedFont {

        /// Parse a font from bytes using allsorts

        ///

        /// # Arguments

        /// * `font_bytes` - The font file data

        /// * `font_index` - Index of the font in a font collection (0 for single fonts)

        /// * `warnings` - Optional vector to collect parsing warnings

        ///

        /// # Returns

        /// `Some(ParsedFont)` if parsing succeeds, `None` otherwise

        ///

        /// Note: Outlines are decoded lazily by `get_or_decode_glyph`;

        /// `LocaGlyf::load` runs eagerly here. Use `from_bytes_shared`

        /// for the lazy-LocaGlyf production path.

            // `from_bytes` keeps the eager-LocaGlyf behaviour for the

            // small number of callers (mainly tests) that don't have

            // an `Arc<[u8]>` to keep alive for the lazy path.

            // Retain an owned copy of the source bytes so the face can later be

            // subset/embedded (PDF export, save->parse roundtrips). Callers pass a

            // borrowed slice that may not outlive us, so we own it here. Mirrors

            // `from_bytes_shared`, which retains the caller's `Arc<FontBytes>`.

        /// Shared implementation of `from_bytes` / `from_bytes_shared`.

        ///

        /// `defer_loca_glyf = true` skips the `LocaGlyf::load` call

        /// here so the caller (`from_bytes_shared`) can install a

        /// `LocaGlyfState::Deferred` slot that re-parses on first

        /// glyph decode. Saves the load-then-drop cycle the previous

        /// arrangement paid (`from_bytes_shared` used to call

        /// `from_bytes` and immediately replace the loaded LocaGlyf

        /// with a Deferred slot, throwing away ~hundreds of KiB of

        /// loca+glyf bytes per face for fonts in the chain that get

        /// loaded but never rasterized).

            use std::{

                collections::hash_map::DefaultHasher,

                hash::{Hash, Hasher},

            };

            use allsorts::{

                binary::read::ReadScope,

                font_data::FontData,

                tables::{

                    cmap::{owned::CmapSubtable as OwnedCmapSubtable, CmapSubtable},

                    FontTableProvider, HeadTable, HheaTable, MaxpTable,

                },

                tag,

            };

                        e

                    )));

                }

            };

                        font_index, e

                    )));

                }

            };

            // Extract font name from NAME table early (before provider is moved)

            // Compute byte offset+length into font_bytes for hmtx/vmtx

            // instead of copying the table data. The provider returns a

            // borrowed slice for OpenType fonts, so we can derive the

            // offset via pointer arithmetic.

                            } else {

                            }

                        }

                    }

                    } else {

                    }

            // Parse vhea table (same format as hhea, used for vertical metrics)

            // hhea is required per the OpenType spec; return None if missing

            // Build layout-specific font metrics

                } else {

                },

            };

            // Build PDF-specific font metrics

            // Use allsorts LocaGlyf for on-demand outline extraction. We

            // *load* LocaGlyf eagerly (it owns ~tens of KiB of loca +

            // ~hundreds of KiB of glyf bytes) but we *don't* decode any

            // glyph outlines up front — that's the big RSS win. Glyphs

            // are decoded by `ParsedFont::get_or_decode_glyph` on first

            // access from the CPU/GPU rasterizer.

            //

            // When `defer_loca_glyf` is set (production lazy path via

            // `from_bytes_shared`), we skip `LocaGlyf::load` here too —

            // the caller will overwrite the slot with

            // `LocaGlyfState::Deferred` carrying the source bytes

            // `Arc<[u8]>`, and the load happens on the first

            // `get_or_decode_glyph` call. This avoids parsing

            // ~hundreds of KiB per face for fonts that get resolved

            // into a chain but never actually rasterized (typical

            // for fallback fonts in CSS chains).

            // Cache `has_gvar` before `provider` gets moved into

            // `allsorts::font::Font::new(provider)` further down —

            // it's the cheapest way to detect a variable font and

            // avoids the borrow-after-move that a later

            // `provider.has_table(tag::GVAR)` would incur.

            {

                        )));

                    }

                }

            } else {

            };

            // Lazy `glyph_cache` starts empty; the space-glyph stub

            // below pre-inserts gid 0 / space so the shaper's

            // cmap-miss fallback has something to render without

            // racing with a decode.

            // Create TrueType hinting instance from font tables

            // Stash raw GSUB/GPOS bytes for lazy parse. Typical fonts

            // have ~tens of KiB of GSUB + a few-to-tens of KiB of GPOS —

            // dwarfed by glyph outlines — so we keep the bytes around

            // and only spend `LayoutTable::read` + `new_layout_cache`

            // cycles when the shaper actually needs them (via

            // `ParsedFont::gsub` / `::gpos`). For an ASCII run where no

            // substitution / kerning is required, we skip both entirely.

            // Font identity hash — used by `PartialEq` for ParsedFont.

            //

            // Previously we did `font_bytes.hash(&mut hasher)` over

            // the full mmap. That touched every page of the file

            // (a 40 MiB `.ttc` walked byte-for-byte) so the "lazy

            // mmap" ended up *fully resident* the moment we built

            // a `ParsedFont`. Cold RSS jumped ~40 MiB from this

            // single line.

            //

            // The hash doesn't need to be cryptographic — it just

            // has to disambiguate two `ParsedFont`s. `(len, first

            // 4 KiB, last 4 KiB, font_index)` is plenty unique and

            // only faults in the two header / trailer pages, which

            // shaping is going to need anyway.

            // Calculate space width

            // Pre-decode the space glyph straight into the lazy

            // `glyph_cache`. Space typically has no outline, so the

            // decoder's outline visitor returns nothing useful and

            // we'd spin re-decoding it every shape — short-circuit

            // here with a hand-rolled record carrying the hmtx

            // advance.

            })();

        /// Attach the source font bytes to this `ParsedFont`, enabling

        /// [`ParsedFont::to_bytes`] and [`ParsedFont::subset`] (both of

        /// which the layout / shaping path never calls).

        ///

        /// Takes an `Arc<FontBytes>` so the same file's bytes can be

        /// shared across every face of a `.ttc` at zero extra cost —

        /// pair with [`rust_fontconfig::FcFontCache::get_font_bytes`].

        /// For ad-hoc PDF callers that have raw heap bytes, wrap them

        /// via `Arc::new(FontBytes::Owned(Arc::from(vec)))`.

        /// Lazy-friendly constructor — identical to

        /// [`ParsedFont::from_bytes`] except that `LocaGlyf` is

        /// **not** loaded during the call. Instead, the supplied

        /// `Arc<[u8]>` is retained and `LocaGlyf::load` runs the first

        /// time [`get_or_decode_glyph`] needs glyph outlines for this

        /// face.

        ///

        /// Fonts that get resolved into a CSS fallback chain but are

        /// never actually rasterized (common on desktop — e.g. every

        /// face of HelveticaNeue.ttc loads, but only one or two are

        /// shaped) then pay zero loca/glyf cost.

        ///

        /// Production callers (the reftest harness, `LayoutWindow`,

        /// `cpurender`) should prefer this constructor. Tests that

        /// inspect `glyph_records_decoded` directly and don't want

        /// a lazy path keep using `from_bytes`.

            // Skip the eager LocaGlyf::load via `defer_loca_glyf=true`

            // — saves the load-then-drop cycle the prior arrangement

            // paid (when this called `from_bytes`, allocated

            // ~hundreds of KiB of loca+glyf bytes, then immediately

            // replaced the slot with `Deferred` and dropped them).

            // `bytes.as_ref()` derefs FontBytes → &[u8] (mmap or owned

            // — same code path).

        /// Resolve the current face's `LocaGlyf`, loading it lazily

        /// on first call when `loca_glyf` is `Deferred`. Returns

        /// `None` when the font has no usable loca+glyf (CFF fonts

        /// or parse failures).

                    // Fast path: cached LocaGlyf is present.

                    // Slow path: parse provider + load LocaGlyf without

                    // holding the slot's lock (allsorts can take a

                    // millisecond or two on a fresh load). Re-check

                    // after acquiring the write lock so a parallel

                    // decoder doesn't double-load.

                    use allsorts::{

                        binary::read::ReadScope,

                        font_data::FontData,

                        tables::FontTableProvider,

                    };

                    // Gate on table presence to match the `from_bytes`

                    // has_glyf check; avoids a spurious warning on

                    // CFF fonts that sneak into the Deferred path.

                }

            }

        /// Source bytes for PDF subsetting / table extraction.

        ///

        /// Looks in two places:

        /// - `original_bytes` (set by [`ParsedFont::with_source_bytes`]

        ///   for legacy PDF-first construction).

        /// - `LocaGlyfState::Deferred.bytes` (set by

        ///   [`ParsedFont::from_bytes_shared`] — the production lazy

        ///   path, which already retains an `Arc<[u8]>` for the lazy

        ///   loca/glyf loader).

        ///

        /// Returns `None` only for `ParsedFont`s built via the eager

        /// `from_bytes` path without an explicit `with_source_bytes`

        /// call — i.e. unit tests that load a font and don't touch

        /// PDF.

        /// Read the monotonic-clock nanos timestamp of the most

        /// recent [`get_or_decode_glyph`] call on this face, or `0`

        /// if it's never been touched.

        /// Drop the cached `LocaGlyf` for this face if it's

        /// `Deferred`-with-bytes-retained — so the next

        /// [`get_or_decode_glyph`] re-parses from `bytes`. No-op for

        /// `Loaded` faces (no source bytes to fall back to).

        ///

        /// Used by [`crate::text3::cache::FontManager::evict_unused`]

        /// and exposed publicly so embedders can free memory under

        /// pressure on fonts they no longer need to render.

                }

            }

        /// Fetch the parsed GSUB cache if this font has one, parsing

        /// it from the retained `gsub_bytes` on first access.

        ///

        /// Moved out of the eager `from_bytes` path because most text

        /// runs never trigger GSUB — plain ASCII without ligatures is

        /// handled entirely by the cmap + hmtx fast path. Building

        /// `LayoutCacheData<GSUB>` up front reserved ~0.5–2 MiB per

        /// face just to throw it away on pages that don't shape

        /// complex scripts.

                    use allsorts::{

                        binary::read::ReadScope,

                        layout::{new_layout_cache, LayoutTable, GSUB},

                    };

        /// Fetch the parsed GPOS cache if this font has one, parsing

        /// it from the retained `gpos_bytes` on first access. See

        /// [`ParsedFont::gsub`] for the motivation.

                    use allsorts::{

                        binary::read::ReadScope,

                        layout::{new_layout_cache, LayoutTable, GPOS},

                    };

        /// Fetch an `OwnedGlyph` for `gid`, decoding it on first access.

        ///

        /// Cached in the `Arc<RwLock<…>>` `glyph_cache` so subsequent

        /// calls (including across clones of this `ParsedFont`) hit the

        /// cache. Returns `None` when `gid >= num_glyphs` or the font

        /// has no loca+glyf and no hmtx entry for the glyph. For CFF

        /// fonts the returned record has an empty outline and an advance

        /// pulled from hmtx — matching the pre-lazy behaviour.

        ///

        /// Called on the rasterizer hot path; performance budget is a

        /// few µs per unique glyph (first hit) and an Arc bump + BTreeMap

        /// lookup (cache hits). The write lock is held only across the

        /// decode, not across the caller's use of the returned Arc.

            use std::sync::Arc;

            // Bump the LRU timestamp so `FontManager::evict_unused`

            // can tell this face is still in use. Cheap atomic store

            // (Relaxed — eviction reads the same atomic and tolerates

            // a slightly stale value, which only causes "evict, then

            // re-load on next access" — never an incorrect render).

            // Fast path: cache hit.

            // Miss: decode. We drop the read lock before taking the

            // write lock to avoid deadlock, and we re-check on the way

            // in because another thread may have decoded the same glyph

            // in between.

                // If another thread beat us to the insert, return theirs

                // so all callers observe the same Arc.

        /// Eagerly decode every glyph into the lazy `glyph_cache`,

        /// restoring the pre-lazy "every glyph is materialised at

        /// construction time" behaviour. Used by tests that iterate

        /// or compare against reference tooling, and by embedders

        /// that want a walkable view without driving every shape

        /// through `get_or_decode_glyph`.

        ///