//! Core types and layout pipeline for the text/inline formatting context.

//!

//! This module defines the central data structures (`UnifiedConstraints`,

//! `LayoutCache`, `FontManager`, `UnifiedLayout`, etc.) and implements the

//! 5-stage inline layout pipeline:

//!

//! 1. **Logical Analysis** — `InlineContent` → `LogicalItem`

//! 2. **`BiDi` Reordering** — `LogicalItem` → `VisualItem`

//! 3. **Shaping** — `VisualItem` → `ShapedItem`

//! 4. **Text Orientation** — vertical writing-mode transforms

//! 5. **Flow / Positioning** — line breaking + final `PositionedItem` placement

//!

//! The module also contains cursor movement helpers, caching infrastructure

//! (per-item and monolithic), and font management (`FontContext`, `FontManager`,

//! `LoadedFonts`).  Integration with the box layout solver lives in

//! `solver3/fc.rs`.

use std::{

    cmp::Ordering,

    collections::{

        hash_map::{DefaultHasher, HashMap},

        BTreeSet, HashSet,

    },

    hash::{Hash, Hasher},

    mem::discriminant,

    num::NonZeroUsize,

    sync::{Arc, Mutex},

};

pub use azul_core::selection::{ContentIndex, GraphemeClusterId};

use azul_core::{

    dom::NodeId,

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    resources::ImageRef,

    selection::{CursorAffinity, SelectionRange, TextCursor},

    ui_solver::GlyphInstance,

};

use azul_css::{

    corety::LayoutDebugMessage, props::basic::ColorU, props::style::StyleBackgroundContent,

};

#[cfg(feature = "text_layout_hyphenation")]

use hyphenation::{Hyphenator, Language as HyphenationLanguage, Load, Standard};

use rust_fontconfig::{FcFontCache, FcPattern, FcStretch, FcWeight, FontId, PatternMatch, UnicodeRange};

use smallvec::{smallvec, SmallVec};

use unicode_bidi::{BidiInfo, Level, TextSource};

use unicode_segmentation::UnicodeSegmentation;

// --- Named constants for layout heuristics ---

/// Fraction of line-height used as ascent when no font metrics are available.

/// Matches the typical 80/20 ascent/descent ratio found in Latin fonts.

const FALLBACK_ASCENT_RATIO: f32 = 0.8;

const FALLBACK_DESCENT_RATIO: f32 = 1.0 - FALLBACK_ASCENT_RATIO;

// Strut/metric fallbacks below assume the CSS-initial 16px font size when no

// explicit size is set.

/// Default strut ascent: `FALLBACK_ASCENT_RATIO` * (16px * `DEFAULT_LINE_HEIGHT_FACTOR`)

const DEFAULT_STRUT_ASCENT: f32 = 12.8;

/// Default strut descent: `FALLBACK_DESCENT_RATIO` * (16px * `DEFAULT_LINE_HEIGHT_FACTOR`)

const DEFAULT_STRUT_DESCENT: f32 = 3.2;

/// Default x-height approximation: 0.5 * 16px (CSS spec fallback).

const DEFAULT_X_HEIGHT: f32 = 8.0;

/// Cap height of the default strut (0.7 x the 16px default font size), the

/// same typical-Latin-ratio approximation the rest of the strut block uses.

const DEFAULT_CAP_HEIGHT: f32 = 11.2;

/// Default ch-width (advance of '0'): 0.5 * 16px.

const DEFAULT_CH_WIDTH: f32 = 8.0;

/// Approximate space character width as a fraction of `font_size`.

const SPACE_WIDTH_RATIO: f32 = 0.5;

/// CSS subscript baseline offset as fraction of line ascent (CSS Inline §3).

const SUBSCRIPT_OFFSET_RATIO: f32 = 0.3;

/// CSS superscript baseline offset as fraction of line ascent (CSS Inline §3).

const SUPERSCRIPT_OFFSET_RATIO: f32 = 0.4;

/// Ruby annotation font size relative to the base, per the CSS UA stylesheet

/// (`rt { font-size: 50% }`). Used to reserve placeholder width for the

/// annotation so a long annotation is not clipped by a short base.

const RUBY_ANNOTATION_FONT_SCALE: f32 = 0.5;

/// Computes the reserved box size for a ruby pair (CSS Ruby Layout §3): the inline-size is

/// the wider of the base and annotation runs (the narrower is centered over the wider), and

/// the block-size stacks the annotation line above the base line so the base reserves

/// vertical space for the annotation. Both inputs are REAL shaped advances / resolved line

/// heights — no magic per-character ratio.

/// Glyph storage for a single shaped cluster.

///

/// Inline one glyph (the

/// common case for Latin text), spill to heap for ligatures / combining

/// marks / multi-glyph clusters. The `union` feature of smallvec packs

/// the inline buffer and the heap pointer into the same bytes, so sizeof

/// stays `sizeof(ShapedGlyph) + 2*usize` regardless of inline/heap state.

pub type ShapedGlyphVec = SmallVec<[ShapedGlyph; 1]>;

/// CSS `line-height` value.

///

/// `Normal` defers resolution to the point where font metrics are available,

/// computing `(ascent + |descent| + lineGap) / upem * fontSize`.

/// `Px` is an already-resolved pixel value from an explicit CSS declaration

/// (e.g. `line-height: 1.5` → `Px(fontSize * 1.5)`).

#[derive(Debug, Clone, Copy)]

#[derive(Default)]

pub enum LineHeight {

    /// `line-height: normal` — resolve from font metrics at layout time

    #[default]

    Normal,

    /// Pre-resolved pixel value (from CSS `line-height: <number|length|percentage>`)

    Px(f32),

}

impl LineHeight {

    /// Resolve to a pixel value, using font metrics when `Normal`.

    ///

    /// `ascent`, `descent` (negative in OpenType convention), `line_gap` are in font units.

    /// `font_size_px` and `units_per_em` are used to scale.

            Self::Normal => {

            }

        }

    /// Resolve using a `LayoutFontMetrics` struct for convenience.

}

impl PartialEq for LineHeight {

        }

}

impl Eq for LineHeight {}

impl Hash for LineHeight {

}

// Stub type when hyphenation is disabled

#[cfg(not(feature = "text_layout_hyphenation"))]

pub struct Standard;

#[cfg(not(feature = "text_layout_hyphenation"))]

impl Standard {

    /// Stub hyphenate method that returns no breaks

    pub fn hyphenate<'a>(&'a self, _word: &'a str) -> StubHyphenationBreaks {

        StubHyphenationBreaks { breaks: Vec::new() }

    }

}

/// Result of hyphenation (stub when feature is disabled)

#[cfg(not(feature = "text_layout_hyphenation"))]

pub struct StubHyphenationBreaks {

    pub breaks: Vec<usize>,

}

// Always import Language from script module

use crate::text3::script::{script_to_language, Language, Script};

/// Available space for layout, similar to Taffy's `AvailableSpace`.

///

/// This type explicitly represents the three possible states for available space:

///

/// - `Definite(f32)`: A specific pixel width is available

/// - `MinContent`: Layout should use minimum content width (shrink-wrap)

/// - `MaxContent`: Layout should use maximum content width (no line breaks unless necessary)

///

/// This is critical for proper handling of intrinsic sizing in Flexbox/Grid

/// where the available space may be indefinite during the measure phase.

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

pub enum AvailableSpace {

    /// A specific amount of space is available (in pixels).

    /// Must be >= 0.  A value of 0.0 means "genuinely zero-width container"

    /// (e.g. `width: 0px`), NOT "unresolved".

    Definite(f32),

    /// The node should be laid out under a min-content constraint

    MinContent,

    /// The node should be laid out under a max-content constraint.

    /// This is the correct default: "lay out to natural width, no constraint".

    MaxContent,

}

impl Default for AvailableSpace {

    /// Default is `MaxContent` — the absence of a width constraint.

    /// Never `Definite(0.0)`, which would make every word overflow.

}

impl AvailableSpace {

    /// Returns true if this is a definite (finite, known) amount of space

    /// Returns true if this is an indefinite (min-content or max-content) constraint

    /// Returns the definite value if available, or a fallback for indefinite constraints

        }

    /// Returns the definite value, or a large value for both min-content and max-content.

    /// 

    /// For intrinsic sizing, we use a large value to let text lay out fully,

    /// then measure the result. The distinction between min/max-content is handled

    /// by the line breaking algorithm, not by constraining the available width.

    #[allow(clippy::match_same_arms)] // enum/value mapping/dispatch table: one arm per input variant (or cross-type bindings that can't merge)

        }

    /// Create from an f32 value, recognizing special sentinel values.

    ///

    /// This function provides backwards compatibility with code that uses f32 for constraints:

    /// - `f32::INFINITY` or `f32::MAX` → `MaxContent` (no line wrapping)

    /// - `0.0` → `MinContent` (maximum line wrapping, return longest word width)

    /// - Other values → `Definite(value)`

    ///

    /// Note: Using sentinel values like 0.0 for `MinContent` is fragile. Prefer using

    /// `AvailableSpace::MinContent` directly when possible.

            // Treat very large values (including f32::MAX) as MaxContent

            // Treat zero or negative as MinContent (shrink-wrap)

        } else {

        }

}

impl Hash for AvailableSpace {

            // Hash the full f32 bit pattern, NOT the integer-rounded value. The

            // derived `PartialEq` compares `Definite` widths exactly, so rounding

            // here both (a) broke sub-pixel precision — a 100.1px vs 100.4px

            // constraint can wrap lines differently yet collided in the same hash

            // bucket — and (b) was inconsistent with the exact equality used as the

            // cache key. `-0.0` is normalized to `+0.0` so the `+0.0 == -0.0`

            // PartialEq pair still hashes identically (Hash/Eq contract).

}

// Re-export traits for backwards compatibility

pub use crate::font_traits::{ParsedFontTrait, ShallowClone};

// --- Core Data Structures for the New Architecture ---

/// Key for caching font chains - based only on CSS properties, not text content

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

pub struct FontChainKey {

    pub font_families: Vec<String>,

    pub weight: FcWeight,

    pub italic: bool,

    pub oblique: bool,

}

/// Either a `FontChainKey` (resolved via fontconfig) or a direct `FontRef` hash.

/// 

/// This enum cleanly separates:

/// - `Chain`: Fonts resolved through fontconfig with fallback support

/// - `Ref`: Direct `FontRef` that bypasses fontconfig entirely (e.g., embedded icon fonts)

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

pub enum FontChainKeyOrRef {

    /// Regular font chain resolved via fontconfig

    Chain(FontChainKey),

    /// Direct `FontRef` identified by pointer address (covers entire Unicode range, no fallbacks)

    Ref(usize),

}

impl FontChainKeyOrRef {

    /// Create from a `FontStack` enum

        }

    /// Returns true if this is a direct `FontRef`

    /// Returns the `FontRef` pointer if this is a Ref variant

        }

    /// Returns the `FontChainKey` if this is a Chain variant

        }

}

impl FontChainKey {

    /// Create a `FontChainKey` from a slice of font selectors

        // (2026-06-10) FIRST-WINS DEDUP: cascaded font stacks can carry duplicate

        // families (e.g. [serif, sans-serif, serif, monospace] when the UA fallback

        // list is appended to a stack already naming serif). The pre-resolve

        // collector dedupes its stacks, so without deduping HERE the shaping-time

        // key never matched the stored key (the g121/g122 chain-lookup misses).

        // This is THE canonical FontChainKey constructor — every key-build site

        // must go through it so lookups match by construction.

        }

        } else {

        };

}

/// On-demand chain resolution for a shaping-time cache miss.

///

/// `font_chain_cache` is an OPTIMIZATION, not a gate: the pre-resolve

/// collector dedupes text nodes by compact-cache (family-hash, weight,

/// style) bits, and when those bits under-represent the real cascade

/// (e.g. every text node reads 0 and ONE representative decides the only

/// chain — its UA-bold h1 weight), whole runs asked for a key that was

/// never stored. The old behavior silently SKIPPED such runs: zero shaped

/// items, zero lines, zero height (miniword: multi-line paragraphs

/// measured 0.0 depending on which text node came first). Resolving at

/// miss time uses the same `fc_cache` query the pre-pass would have used,

/// so the result is identical — just later.

        } else {

        },

        } else {

        },

    )

/// A map of pre-loaded fonts, keyed by `FontId` (from rust-fontconfig)

///

/// This is passed to the shaper - no font loading happens during shaping

/// The fonts are loaded BEFORE layout based on the font chains and text content.

///

/// Provides both `FontId` and hash-based lookup for efficient glyph operations.

#[derive(Debug, Clone)]

pub struct LoadedFonts<T> {

    /// Primary storage: `FontId` -> Font

    pub fonts: HashMap<FontId, T>,

    /// Reverse index: `font_hash` -> `FontId` for fast hash-based lookups

    hash_to_id: HashMap<u64, FontId>,

}

impl<T: ParsedFontTrait> LoadedFonts<T> {

    /// Insert a font with its `FontId`

    /// Get a font by `FontId`

    /// Get a font by its hash

    /// Get the `FontId` for a hash

    /// Check if a `FontId` is present

    /// Check if a hash is present

    /// Iterate over all fonts

    /// Get the number of loaded fonts

    /// Check if empty

}

impl<T: ParsedFontTrait> Default for LoadedFonts<T> {

}

impl<T: ParsedFontTrait> FromIterator<(FontId, T)> for LoadedFonts<T> {

}

/// Enum that wraps either a fontconfig-resolved font (T) or a direct `FontRef`.

///

/// This allows the shaping code to handle both fontconfig-resolved fonts

/// and embedded fonts (`FontRef`) uniformly through the `ParsedFontTrait` interface.

#[derive(Debug, Clone)]

pub enum FontOrRef<T> {

    /// A font loaded via fontconfig

    Font(T),

    /// A direct `FontRef` (embedded font, bypasses fontconfig)

    Ref(azul_css::props::basic::FontRef),

}

impl<T: ParsedFontTrait> ShallowClone for FontOrRef<T> {

        }

}

impl<T: ParsedFontTrait> ParsedFontTrait for FontOrRef<T> {

        }

        }

        }

        }

        }

        }

        }

        }

        }

        }

}

/// Bundles all font-related state that can be shared across layout passes.

///

/// Separates font concerns from layout/rendering state (`LayoutWindow`).

/// Each test/render creates a fresh `LayoutWindow` from a shared `FontContext`,

/// avoiding stale layout cache reuse while keeping parsed fonts warm.

///

/// Usage:

/// ```ignore

/// let ctx = FontContext::from_fc_cache(fc_cache);

/// ctx.pre_resolve_chains(&styled_dom, &platform);

/// ctx.load_fonts_for_chains();

///

/// // Per-test: create fresh LayoutWindow from context

/// let mut window = LayoutWindow::from_font_context(&ctx)?;

/// window.layout_and_generate_display_list(styled_dom, ...)?;

/// ```

#[derive(Debug, Clone)]

pub struct FontContext {

    /// The shared font cache. As of rust-fontconfig 4.1 this type is

    /// itself backed by `Arc<RwLock<_>>`, so cloning is cheap and all

    /// clones see builder-thread writes immediately — no more `Arc<T>`

    /// wrapping is needed and no more stale-snapshot refresh dance.

    pub fc_cache: FcFontCache,

    pub parsed_fonts: Arc<Mutex<HashMap<FontId, azul_css::props::basic::FontRef>>>,

    pub font_chain_cache: HashMap<FontChainKey, rust_fontconfig::FontFallbackChain>,

    pub embedded_fonts: HashMap<u64, azul_css::props::basic::FontRef>,

    /// Reverse map: `font_family_hash` → actual `StyleFontFamilyVec`.

    /// Accumulated across DOMs for persistence. Copied to `FontManager` on `LayoutWindow` creation.

    pub font_hash_to_families: HashMap<u64, azul_css::props::basic::font::StyleFontFamilyVec>,

    /// Optional link back to the live `FcFontRegistry`. Present iff the

    /// caller wants the scout-on-demand path

    /// ([`rust_fontconfig::registry::FcFontRegistry::request_and_resolve_with_scripts`]),

    /// which priority-bumps the builder for not-yet-parsed families

    /// rather than falling back to the empty-snapshot response.

    pub registry: Option<Arc<rust_fontconfig::registry::FcFontRegistry>>,

}

impl FontContext {

    /// Create from an `FcFontCache`. Parsed fonts, font chains, and

    /// embedded fonts start empty.

    ///

    /// The resulting `FontContext` has `registry = None`, so font

    /// chain resolution only sees what's already in the cache. For

    /// the scout-on-demand path, use [`FontContext::from_registry`]

    /// instead, which keeps a handle to the registry so that chain

    /// resolution can lazy-parse families the DOM needs.

    /// Create from a live `FcFontRegistry`. The `fc_cache` field gets

    /// a *shared* handle to the registry's cache (cheap `Arc::clone`

    /// on the v4.1 shared-state cache) — writes by builder threads

    /// show up immediately in every reader. Chain resolution goes

    /// through

    /// [`rust_fontconfig::registry::FcFontRegistry::request_and_resolve_with_scripts`]

    /// which priority-bumps the builder for unparsed families and

    /// waits for them. This is the "scout-on-demand" path: a

    /// headless renderer can skip the eager common-stack parse and

    /// pay only the per-family cost on first use, dropping peak RSS

    /// by the common-stack metadata size (~15 MiB on macOS).

    /// Pre-resolve font chains for a `StyledDom`'s CSS font stacks.

    /// Call this before layout so text rendering doesn't skip glyphs.

    ///

    /// Unicode-fallback fonts are limited to the scripts actually

    /// present in the document's text content — for an ASCII-only

    /// page, this skips the ~300 MiB Arial-Unicode / CJK / Arabic

    /// pull-in entirely. See

    /// [`crate::solver3::getters::scripts_present_in_styled_dom`].

        use crate::solver3::getters::{

            collect_font_stacks_from_styled_dom, collect_used_codepoints,

            prune_chain_to_used_chars, resolve_font_chains, scripts_present_in_styled_dom,

        };

        // Coverage-based prune (matches `collect_and_resolve_font_chains_with_registration`).

        // WEB-LIFT last resort (after prune, so it survives — prune drops the registered

        // fallback because its cmap isn't parsed yet): if a chain ended up with no fonts,

        // append the first registered font so load_missing_for_chains finds it and text

        // shapes instead of measuring 0. (Done in azul-layout, NOT rust-fontconfig, so the

        // lift-fragile with_memory_fonts isn't re-codegen'd into a trapping shape.)

                // `list()` deep-copies the ENTIRE font database to read one entry;

                // see `first_font_in_cache` in solver3::getters for the

                // measurement (717k String clones, 2.3 MB retained).

                };

        }

    /// Load parsed font bytes from disk for all fonts referenced in `font_chain_cache`.

    ///

    /// Thin wrapper that materialises a `ResolvedFontChains` from the

    /// cached chain map and delegates the actual disk-load to the

    /// shared `FontManager::load_missing_for_chains` helper, so the

    /// "collect → diff → load → insert" sequence lives in exactly

    /// one place. Failures are silently dropped here (the caller is

    /// the warmup path which has no good place to log them); use

    /// `FontManager::load_missing_for_chains` directly for diagnostics.

        use crate::solver3::getters::ResolvedFontChains;

        use crate::text3::default::PathLoader;

        // Borrow our shared `parsed_fonts` Arc as a transient

        // FontManager so we can use the helper. `from_arc_shared`

        // returns a manager that mutates the same underlying pool.

        };

    /// Convert into a `FontManager` with all data populated.

    /// Carries the `registry` forward so the resulting manager also

    /// has the scout-on-demand path available.

        // Idempotent: reuses the FontIds already in the shared fc_cache.

}

/// How a registered in-memory face ranks against fonts on disk.

///

/// The distinction exists because "register a font by name" means two different

/// things. A font the caller explicitly supplied for a family *is* that family

/// and must beat anything installed, exactly as CSS says. A font offered as a

/// stand-in for a generic family - the 14 standard PDF fonts answering

/// `sans-serif`, say - must not, or a Win-1252 subset would displace the

/// system's full Unicode faces on every desktop.

///

/// Without the second tier the choice is all-or-nothing: claim `sans-serif` and

/// wreck desktop, or leave it alone and have nothing at all on a target with no

/// fonts on disk, such as wasm.

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

pub enum MemoryFontTier {

    /// Wins over anything on disk. The right tier for a font the caller named.

    Primary,

    /// Used only after disk resolution has had its turn. The right tier for a

    /// last-resort face standing in for a generic family.

    Fallback,

}

/// One in-memory face registered under a family name, with the style attributes

/// needed to choose the right face for a CSS `(weight, italic/oblique)` query.

///

/// [`FontManager::register_named_font`] registers several faces under the *same*

/// family name (e.g. `Helvetica` regular, bold, oblique). Keying

/// [`FontManager::memory_families`] by family alone therefore collapsed them —

/// the last registration won and `font-weight: bold` silently rendered in the

/// regular face. Each face now records its own weight/style so resolution can

/// pick the closest one (see `getters::split_memory_matches`).

#[derive(Debug, Clone)]

pub struct MemoryFace {

    /// Whether this face outranks the disk or only backstops it.

    pub tier: MemoryFontTier,

    /// The `FontMatch` the resolver emits when this face is chosen.

    pub font_match: rust_fontconfig::FontMatch,

    /// OS/2 weight of this face (static fonts). For a variable font this is the

    /// default-instance weight; `weight_axis` carries the selectable range.

    pub weight: FcWeight,

    /// `head`/OS-2 italic bit.

    pub italic: bool,

    /// OS/2 oblique bit.

    pub oblique: bool,

    /// OS/2 width class.

    pub stretch: FcStretch,

    /// For a variable font, the `wght` axis `(min, max)` in user units; `None`

    /// for a static face. Lets a single VF satisfy any requested weight.

    pub weight_axis: Option<(f32, f32)>,

}

/// Style attributes parsed from a font's bytes (OS/2 + `head`), used to index a

/// registered face in [`FontManager::memory_families`].

#[derive(Debug, Clone, Copy)]

struct FaceStyle {

    weight: FcWeight,

    italic: bool,

    oblique: bool,

    stretch: FcStretch,

    weight_axis: Option<(f32, f32)>,

}

impl Default for FaceStyle {

}

/// Parse a face's weight / italic / oblique / stretch from its bytes via

/// rust-fontconfig (which reads OS/2 `usWeightClass`/`usWidthClass` and the

/// `head` italic bit). Falls back to upright Normal when the font can't be

/// parsed, so registration never fails on a malformed face.

    };

    };

/// The font GC's grace pool: faces evicted from `parsed_fonts` wait here for

/// one resurrection window (see `FontManager::condemned_fonts`).

#[derive(Debug)]

pub struct CondemnedFonts<T> {

    /// Evicted faces, each stamped with the GC generation that evicted it.

    pub faces: HashMap<FontId, (T, u64)>,

    /// Monotonic GC pass counter.

    pub generation: u64,

}

impl<T> Default for CondemnedFonts<T> {

}

#[derive(Debug)]

pub struct FontManager<T> {

    /// The font-path cache. `FcFontCache` in rust-fontconfig 4.1 is

    /// already a shared handle internally (`Arc<RwLock<_>>`), so no

    /// further `Arc<...>` wrapping is needed — clones are cheap and

    /// all clones see builder writes instantly.

    pub fc_cache: FcFontCache,

    /// Holds the actual parsed font (usually with the font bytes attached).

    /// Wrapped in Arc so multiple `FontManager` instances can share the same

    /// pool of already-parsed fonts (avoids re-reading from disk).

    pub parsed_fonts: Arc<Mutex<HashMap<FontId, T>>>,

    /// Faces the font GC evicted, kept for a RESURRECTION window instead of

    /// dropped: any hash resolution against a condemned face moves it back

    /// into `parsed_fonts`, and only a face nobody resolved for two GC

    /// generations is truly dropped.

    ///

    /// This exists because the GC's original safety argument — "eviction is

    /// always safe, the next layout re-loads what it needs" — is FALSE when

    /// a shaping cache serves cached glyphs without re-loading: the display

    /// list then carries a `font_hash` whose face is gone and the renderer

    /// silently loses the text (the azwriter textless-window bug; the

    /// failing hash appeared verbatim in the GC's eviction trace).

    pub condemned_fonts: Arc<Mutex<CondemnedFonts<T>>>,

    // Cache for font chains - populated by resolve_all_font_chains() before layout

    // This is read-only during layout - no locking needed for reads

    pub font_chain_cache: HashMap<FontChainKey, rust_fontconfig::FontFallbackChain>,

    /// Cache for direct `FontRefs` (embedded fonts like Material Icons)

    /// These are fonts referenced via `FontStack::Ref` that bypass fontconfig

    pub embedded_fonts: Mutex<HashMap<u64, azul_css::props::basic::FontRef>>,

    /// Reverse map: `font_family_hash` → actual `StyleFontFamilyVec`.

    /// Accumulated across DOMs. Used by font collection and text shaping to

    /// resolve compact cache hashes without `get_property_slow`.

    pub font_hash_to_families: HashMap<u64, azul_css::props::basic::font::StyleFontFamilyVec>,

    /// Optional link back to the live `FcFontRegistry`. When present,

    /// chain resolution uses

    /// [`rust_fontconfig::registry::FcFontRegistry::request_and_resolve_with_scripts`]

    /// which lazy-parses system fonts as the DOM requests them

    /// (scout-on-demand). `None` falls back to querying whatever is

    /// already in the shared cache.

    pub registry: Option<Arc<rust_fontconfig::registry::FcFontRegistry>>,

    /// `FxHash` of the `prev_font_hashes` slice at the moment the last

    /// successful `collect_and_resolve_font_chains_with_registration`

    /// call populated `font_chain_cache`. Lets repeated layouts of the

    /// same DOM skip the ~1.5 ms (cold) / ~0.9 ms (warm) chain resolver

    /// when the set of font-family hashes has not changed. Cleared

    /// whenever `font_chain_cache` is explicitly emptied.

    pub last_resolved_font_stacks_sig: Option<u64>,

    /// Index of every font registered by FAMILY NAME into `fc_cache`'s

    /// in-memory font table (bundled fonts, embedder fonts, the built-in

    /// mock test fonts): normalized family name → the `FontMatch` the

    /// resolver should emit for it.

    ///

    /// WHY THIS EXISTS (architectural, see `resolve_font_chains_fast`):

    /// the fast chain resolver in rust-fontconfig 4.4

    /// (`FcFontRegistry::request_fonts_fast`) resolves families purely

    /// against `known_paths` — i.e. fonts that exist as FILES ON DISK.

    /// In-memory fonts are invisible to it, so a family registered with

    /// `FcFontCache::with_memory_fonts` could never be matched by name

    /// on the production path (which always has a live registry): it

    /// silently fell back to a system font. This index is consulted

    /// FIRST, before the disk probe, so a memory-registered family wins

    /// exactly as CSS says it should.

    pub memory_families: HashMap<String, Vec<MemoryFace>>,

    /// Baked static instances of variable fonts, keyed by a hash of the original

    /// VF bytes. A variable font is expanded into one static face per weight

    /// bucket (see `register_named_font`); this caches the minted faces so the

    /// several spelling registrations of the same VF don't re-bake it.

    vf_bake_cache: HashMap<u64, Vec<(FontId, FaceStyle)>>,

}

impl<T: ParsedFontTrait> FontManager<T> {

    /// A second manager sharing this one's font pool.

    ///

    /// `fc_cache`, `parsed_fonts` and `registry` are shared handles — a font

    /// parsed through either manager is visible to both — and the resolved

    /// chain/name caches are copied. Use this to lay out the same content

    /// OUTSIDE the window pipeline (e.g. DOM→PDF from a callback) with

    /// exactly the fonts the window resolved on screen: same fallback

    /// chains, same embedded fonts, no re-parse from disk.

        Self {

            ),

            // Deliberately reset: the sig gates a chain-resolver skip that is

            // only valid against THIS manager's font_chain_cache history.

        }

    /// # Errors

    ///

    /// Returns a `LayoutError` if the font cache cannot be initialized.

    /// Register a font by FAMILY NAME from raw bytes, as an in-memory font

    /// in the shared `FcFontCache`.

    ///

    /// This is the ONE hook an embedder (or a test) uses to make a font

    /// resolvable by `font-family: "<family>"`. It mints one `FontId` for

    /// the font, inserts it into the fontconfig cache's memory-font table

    /// (so `get_font_bytes` / `load_fonts_from_disk` find it with no

    /// special-casing) and indexes it in [`Self::memory_families`] so the

    /// fast chain resolver can match it by name.

    ///

    /// `coverage` are the codepoint ranges the font actually covers.

    /// Passing the true ranges matters: `FontFallbackChain::resolve_char`

    /// skips any font that reports no coverage, and a font claiming

    /// coverage it doesn't have would render .notdef instead of falling

    /// back.

    ///

    /// Returns the `FontId` the family now resolves to.

    /// Register an in-memory face under `family` at an explicit

    /// [`MemoryFontTier`].

    ///

    /// [`Self::register_named_font`] is this with [`MemoryFontTier::Primary`].

    /// Use [`MemoryFontTier::Fallback`] to offer a face for a family without

    /// displacing whatever is installed - a caller that ships stand-in fonts for

    /// `serif`/`sans-serif`/`monospace` wants the system's faces to win on a

    /// desktop and its own to be there on wasm, and that is the tier that does

    /// both.

        // Variable fonts: expand into one STATIC instance per weight bucket so the

        // ordinary static weight-selection path (see `split_memory_matches` /

        // `pick_memory_face`) picks the right one, with NO changes to shaping,

        // glyph decode, or PDF embedding — each baked instance is an ordinary

        // static font. Falls through to the static path below if the font is not a

        // bakeable variable font (baking failed / no glyf variations).

            {

        // The weight/style come from the font BYTES (OS/2), not the registration

        // name: registering `Helvetica-Bold.ttf` under either "Helvetica-Bold" or

        // its internal family "Helvetica" must both yield weight=Bold. A font can

        // (and Helvetica does) reuse the same family name across faces, so faces

        // are distinguished by (weight, italic, oblique), never by name alone.

        // IDEMPOTENT: several `FontManager`s (one per window, plus the PDF

        // writer) share one `FcFontCache`. Registering the same face twice would

        // mint a second `FontId` for the same bytes, orphan the first in the

        // cache's metadata table and make the id non-deterministic. Reuse an

        // existing memory font ONLY when family AND (weight, italic, oblique)

        // match — a bold face must not be deduplicated against the regular one.

        {

        } else {

            };

            );

        };

    /// Append (or refresh) a face in [`Self::memory_families`] under `norm`,

    /// de-duplicating by `FontId` so repeated registrations don't grow the list.

    /// Expand a variable font (with a `wght` axis over `[min, max]`, default

    /// `def`) into one baked STATIC instance per standard weight bucket and

    /// register each as an in-memory face under `norm`. Returns the face nearest

    /// the fvar default, or `None` if no instance could be baked (caller then

    /// falls back to registering the raw bytes as a single static face).

    ///

    /// Baking is done once per unique VF bytes and cached (`vf_bake_cache`) so the

    /// several spelling registrations of the same font don't re-bake it.

    // Weight axis values are clamped to [1, 1000] and rounded before the cast, so

    // the f32 -> u16 conversion is bounded and sign-safe.

    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]

            use core::hash::Hasher;

        };

        // Same VF already baked under another spelling: re-index, don't re-bake.

            else {

            };

            };

            );

        }

    /// Register the built-in mock test fonts (see

    /// [`crate::text3::mock_fonts`]). Called from every constructor: the

    /// mock families are only reachable if a stylesheet names them, and

    /// having them always present means tests exercise the *same* font

    /// path as production instead of a test-only bypass.

    /// Create a `FontManager` sharing the font-path cache handle.

    ///

    /// The `parsed_fonts` pool starts empty. Fonts loaded during the first

    /// layout pass are cached and will be available on subsequent calls

    /// if you clone the `parsed_fonts` Arc before creating the next instance.

    /// For full sharing, prefer `from_arc_shared()`.

    /// # Errors

    ///

    /// Returns a `LayoutError` if the font cache cannot be initialized.

    /// Create a `FontManager` sharing both the font-path cache and the

    /// already-parsed font data with another `FontManager`.

    ///

    /// This avoids re-reading and re-parsing font files from disk when

    /// rendering multiple documents that use the same fonts.

    /// # Errors

    ///