fret-core 0.1.0

Core contracts, IDs, geometry, events, and shared data types for the Fret framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

use crate::FrameId;
use crate::{FontId, Px, TextOverflow, TextWrap};

/// Per-frame renderer-owned text cache counters.
///
/// This is intended for diagnostics bundles and on-screen debug panels. The runner can update it
/// once per rendered frame to make renderer-level churn (text blobs, glyph atlas pressure) visible
/// in a single artifact.
#[derive(Debug, Default, Clone, Copy)]
pub struct RendererTextPerfSnapshot {
    pub frame_id: FrameId,

    pub font_stack_key: u64,
    pub font_db_revision: u64,
    /// Fingerprint of the effective font fallback policy (locale + family config + injection).
    ///
    /// This is intended for diagnostics only.
    pub fallback_policy_key: u64,

    /// Total count of missing/tofu glyphs observed across text prepared this frame.
    ///
    /// Implementation note: this is currently approximated as the number of shaped glyphs whose
    /// glyph id is `0` (the `.notdef` glyph) across prepared text runs.
    pub frame_missing_glyphs: u64,
    /// Count of prepared text blobs that contained at least one missing/tofu glyph.
    pub frame_texts_with_missing_glyphs: u64,

    pub blobs_live: u64,
    pub blob_cache_entries: u64,
    pub shape_cache_entries: u64,
    pub measure_cache_buckets: u64,

    /// Best-effort heap byte estimates for text caches (CPU-side).
    ///
    /// These values are intended for diagnostics only. They are approximate and may under-count
    /// allocator overhead and shared allocations.
    pub shape_cache_bytes_estimate_total: u64,
    pub blob_paint_palette_bytes_estimate_total: u64,
    pub blob_decorations_bytes_estimate_total: u64,

    pub unwrapped_layout_cache_entries: u64,
    pub frame_unwrapped_layout_cache_hits: u64,
    pub frame_unwrapped_layout_cache_misses: u64,
    pub frame_unwrapped_layouts_created: u64,

    pub frame_cache_resets: u64,
    pub frame_blob_cache_hits: u64,
    pub frame_blob_cache_misses: u64,
    pub frame_blobs_created: u64,
    pub frame_shape_cache_hits: u64,
    pub frame_shape_cache_misses: u64,
    pub frame_shapes_created: u64,

    pub mask_atlas: RendererGlyphAtlasPerfSnapshot,
    pub color_atlas: RendererGlyphAtlasPerfSnapshot,
    pub subpixel_atlas: RendererGlyphAtlasPerfSnapshot,

    /// Best-effort process-local font database/cache counters.
    ///
    /// These are intended to help attribute CPU-side footprint concerns (e.g. "too many injected
    /// font blobs") without requiring heap profilers.
    pub registered_font_blobs_count: u64,
    pub registered_font_blobs_total_bytes: u64,
    pub family_id_cache_entries: u64,
    pub baseline_metrics_cache_entries: u64,
}

#[derive(Debug, Default, Clone, Copy)]
pub struct RendererGlyphAtlasPerfSnapshot {
    pub width: u32,
    pub height: u32,
    pub pages: u32,
    pub entries: u64,

    pub used_px: u64,
    pub capacity_px: u64,

    pub frame_hits: u64,
    pub frame_misses: u64,
    pub frame_inserts: u64,
    pub frame_evict_glyphs: u64,
    pub frame_evict_pages: u64,
    pub frame_out_of_space: u64,
    pub frame_too_large: u64,

    pub frame_pending_uploads: u64,
    pub frame_pending_upload_bytes: u64,
    pub frame_upload_bytes: u64,
}

/// Per-frame renderer-owned font selection trace, intended for diagnostics bundles.
///
/// This is **not** a stable contract for apps; it exists to make font fallback issues auditable and
/// to help keep refactors fearless (especially around variable fonts and fallback chain semantics).
#[derive(Debug, Default, Clone)]
pub struct RendererTextFontTraceSnapshot {
    pub frame_id: FrameId,
    /// Bounded list of trace entries for the frame.
    ///
    /// Renderers are expected to keep this list small. Typical policies:
    ///
    /// - record entries only when missing/tofu glyphs are observed
    /// - record a small ring of the most recent prepared blobs when explicitly enabled
    pub entries: Vec<RendererTextFontTraceEntry>,
}

#[derive(Debug, Clone)]
pub struct RendererTextFontTraceEntry {
    /// Human-readable preview of the text (may be truncated).
    pub text_preview: String,
    pub text_len_bytes: u32,

    pub font: FontId,
    pub font_size: Px,
    pub scale_factor: f32,

    pub wrap: TextWrap,
    pub overflow: TextOverflow,
    pub max_width: Option<Px>,

    pub locale_bcp47: Option<String>,

    pub missing_glyphs: u32,

    /// Families used by shaping/rasterization for this blob (best-effort).
    pub families: Vec<RendererTextFontTraceFamilyUsage>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RendererTextFontTraceFamilyUsage {
    pub family: String,
    pub glyphs: u32,
    pub missing_glyphs: u32,
    pub class: RendererTextFontTraceFamilyClass,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RendererTextFontTraceFamilyClass {
    Requested,
    CommonFallback,
    SystemFallback,
    Unknown,
}

/// Snapshot of the effective renderer font fallback policy, intended for diagnostics bundles.
#[derive(Debug, Default, Clone)]
pub struct RendererTextFallbackPolicySnapshot {
    pub frame_id: FrameId,
    pub font_stack_key: u64,
    pub font_db_revision: u64,
    pub fallback_policy_key: u64,

    pub system_fonts_enabled: bool,
    pub locale_bcp47: Option<String>,

    pub common_fallback_injection: crate::TextCommonFallbackInjection,
    pub prefer_common_fallback: bool,
    pub prefer_common_fallback_for_generics: bool,

    pub configured_ui_sans_families: Vec<String>,
    pub configured_ui_serif_families: Vec<String>,
    pub configured_ui_mono_families: Vec<String>,
    pub configured_common_fallback_families: Vec<String>,

    pub default_ui_sans_candidates: Vec<String>,
    pub default_ui_serif_candidates: Vec<String>,
    pub default_ui_mono_candidates: Vec<String>,
    pub default_common_fallback_families: Vec<String>,

    /// The effective suffix appended to named-family stacks when common fallback is preferred.
    pub common_fallback_stack_suffix: String,
    /// The effective candidate list used to build `common_fallback_stack_suffix` (trimmed + deduped, preserving order).
    pub common_fallback_candidates: Vec<String>,

    pub bundled_profile_contract: RendererBundledFontProfileSnapshot,
}

/// Diagnostics-only view of the bundled font profile contract the renderer knows about.
#[derive(Debug, Default, Clone)]
pub struct RendererBundledFontProfileSnapshot {
    pub name: String,
    pub provided_roles: Vec<String>,
    pub expected_family_names: Vec<String>,
    pub guaranteed_generic_families: Vec<String>,
    pub ui_sans_families: Vec<String>,
    pub ui_serif_families: Vec<String>,
    pub ui_mono_families: Vec<String>,
    pub common_fallback_families: Vec<String>,
}