xbintsc 0.5.37 → 0.5.41

package/runtime/ext_gui/style.cpp

@@ -9,6 +9,7 @@
 #include "style_internal.h"
 
 #include "css_internal.h"
+#include "perf.h"
 
 #include <algorithm>
 #include <cctype>
@@ -45,13 +46,17 @@ struct Candidate {
   int important = 0;
   int specificity = 0;
   int order = 0;
+  /** Push order, so two candidates with the same `order` (the inline
+   * declarations all use `INT_MAX`) keep their declaration order. */
+  int sequence = 0;
   const Declaration *declaration = nullptr;
 };
 
 bool candidateBefore(const Candidate &a, const Candidate &b) {
   if (a.important != b.important) return a.important < b.important;
   if (a.specificity != b.specificity) return a.specificity < b.specificity;
-  return a.order < b.order;
+  if (a.order != b.order) return a.order < b.order;
+  return a.sequence < b.sequence;
 }
 
 
@@ -156,7 +161,9 @@ void inheritFrom(XtStyle *style, const XtStyle *parent) {
   style->color = parent->color;
   style->visible = parent->visible;
   style->pointer_events = parent->pointer_events;
-  style->variables = parent->variables;
+  /* Most documents define no custom properties; copying the (empty) map for
+   * every element is pure overhead. */
+  if (!parent->variables.empty()) style->variables = parent->variables;
   style->font_size = parent->font_size;
   style->font_weight = parent->font_weight;
   style->font_family = parent->font_family;
@@ -167,14 +174,12 @@ void inheritFrom(XtStyle *style, const XtStyle *parent) {
   style->text_shadow = parent->text_shadow;
 }
 
-bool ruleApplies(const Rule &rule, const ApplyContext &context) {
-  return rule.media.empty() ||
-         xt_css_media_matches(rule.media, context.viewportWidth, context.viewportHeight);
-}
-
 void applyCandidates(XtStyle *style, std::vector<Candidate> *candidates,
                      const ApplyContext &nodeContext) {
-  std::stable_sort(candidates->begin(), candidates->end(), candidateBefore);
+  /* `candidateBefore` is a total order now (the sequence breaks ties), so an
+   * unstable `std::sort` is equivalent to the old `stable_sort` without its
+   * temporary buffer. */
+  std::sort(candidates->begin(), candidates->end(), candidateBefore);
   /* Custom properties participate in the cascade first; their final values are
    * then available to every normal declaration on this element. */
   for (const Candidate &candidate : *candidates) {
@@ -332,11 +337,35 @@ void resetPseudoPointers(const Node *node) {
   for (const std::unique_ptr<Node> &child : node->children) resetPseudoPointers(child.get());
 }
 
+/** Per-computation scratch buffers. The cascade runs depth-first, so one
+ * candidate list (and one inline-declaration list) can be reused for every
+ * node — the old code allocated both per element. */
+struct ComputeScratch {
+  std::vector<Candidate> candidates;
+  std::vector<Declaration> inline_declarations;
+  int sequence = 0;
+  /** Set when any computed style declares a `transition` (including an inline
+   * `style="transition: …"`), so the document knows whether it needs the
+   * transition snapshot path at all. */
+  bool has_transitions = false;
+};
+
+void pushCandidates(std::vector<Candidate> *candidates, ComputeScratch *scratch,
+                    const Declaration &declaration, int important, int specificity, int order) {
+  Candidate candidate;
+  candidate.important = important;
+  candidate.specificity = specificity;
+  candidate.order = order;
+  candidate.sequence = scratch->sequence++;
+  candidate.declaration = &declaration;
+  candidates->push_back(candidate);
+}
+
 /** Compute one `::before`/`::after` style and attach its generated content. */
 void computePseudo(const Node *origin, PseudoElement side, const XtStyle &originStyle,
-                   const StyleSheet &sheet, std::unordered_map<const Node *, XtStyle> &out,
-                   const ApplyContext &context, const MatchState &state,
-                   PseudoNodeSet *pseudos) {
+                   const StyleSheet &sheet, const std::vector<char> &applies,
+                   std::unordered_map<const Node *, XtStyle> &out, const ApplyContext &context,
+                   const MatchState &state, PseudoNodeSet *pseudos, ComputeScratch *scratch) {
   if (pseudos == nullptr || originStyle.display == Display::None) return;
   Node *pseudo = pseudos->create(const_cast<Node *>(origin), side);
   if (side == PseudoElement::Before) const_cast<Node *>(origin)->pseudo_before = pseudo;
@@ -350,9 +379,11 @@ void computePseudo(const Node *origin, PseudoElement side, const XtStyle &origin
   nodeContext.parentFontSize = originStyle.font_size;
 
   std::string pseudoName = side == PseudoElement::Before ? "before" : "after";
-  std::vector<Candidate> candidates;
-  for (const Rule &rule : sheet.rules) {
-    if (!ruleApplies(rule, nodeContext)) continue;
+  std::vector<Candidate> &candidates = scratch->candidates;
+  candidates.clear();
+  for (size_t ruleIndex = 0; ruleIndex < sheet.rules.size(); ruleIndex++) {
+    if (applies[ruleIndex] == 0) continue;
+    const Rule &rule = sheet.rules[ruleIndex];
     for (const ComplexSelector &selector : rule.selectors) {
       if (selector.compounds.empty() || selector.compounds.back().pseudo_element != pseudoName)
         continue;
@@ -360,15 +391,17 @@ void computePseudo(const Node *origin, PseudoElement side, const XtStyle &origin
        * pseudo-element suffix removed: `.card.info::before` is `.card.info`. */
       ComplexSelector copy = selector;
       copy.compounds.back().pseudo_element.clear();
+      g_perf_frame.rulesEvaluated += 1;
       if (!xt_css_match(origin, copy, state)) continue;
       for (const Declaration &declaration : rule.declarations) {
-        candidates.push_back({declaration.important ? 1 : 0, selector.specificity, rule.order,
-                              &declaration});
+        pushCandidates(&candidates, scratch, declaration, declaration.important ? 1 : 0,
+                       selector.specificity, rule.order);
       }
     }
   }
   applyCandidates(&style, &candidates, nodeContext);
   finalizeStyle(&style, nodeContext);
+  if (!style.transitions.empty()) scratch->has_transitions = true;
 
   bool generated = false;
   std::string text;
@@ -380,8 +413,9 @@ void computePseudo(const Node *origin, PseudoElement side, const XtStyle &origin
 }
 
 void computeNode(const Node *node, const XtStyle *parent, const StyleSheet &sheet,
-                 std::unordered_map<const Node *, XtStyle> &out, const ApplyContext &context,
-                 const MatchState &state, PseudoNodeSet *pseudos) {
+                 const std::vector<char> &applies, std::unordered_map<const Node *, XtStyle> &out,
+                 const ApplyContext &context, const MatchState &state, PseudoNodeSet *pseudos,
+                 ComputeScratch *scratch) {
   const XtStyle *childParent = parent;
   if (node->isElement() && !node->is_pseudo) {
     XtStyle style = xt_style_initial();
@@ -395,35 +429,48 @@ void computeNode(const Node *node, const XtStyle *parent, const StyleSheet &shee
     ApplyContext nodeContext = context;
     nodeContext.parentFontSize = (parent != nullptr) ? parent->font_size : context.rootFontSize;
 
-    std::vector<Candidate> candidates;
-    for (const Rule &rule : sheet.rules) {
-      if (!ruleApplies(rule, nodeContext)) continue;
+    std::vector<Candidate> &candidates = scratch->candidates;
+    candidates.clear();
+    for (size_t ruleIndex = 0; ruleIndex < sheet.rules.size(); ruleIndex++) {
+      if (applies[ruleIndex] == 0) continue;
+      const Rule &rule = sheet.rules[ruleIndex];
       for (const ComplexSelector &selector : rule.selectors) {
+        g_perf_frame.rulesEvaluated += 1;
         if (!xt_css_match(node, selector, state)) continue;
         for (const Declaration &declaration : rule.declarations) {
-          candidates.push_back({declaration.important ? 1 : 0, selector.specificity, rule.order, &declaration});
+          pushCandidates(&candidates, scratch, declaration, declaration.important ? 1 : 0,
+                         selector.specificity, rule.order);
         }
       }
     }
     const std::string *inlineStyle = node->attr("style");
-    std::vector<Declaration> inlineDeclarations;
     if (inlineStyle != nullptr) {
+      std::vector<Declaration> &inlineDeclarations = scratch->inline_declarations;
       inlineDeclarations = xt_css_parse_declarations(*inlineStyle);
       for (const Declaration &declaration : inlineDeclarations) {
-        candidates.push_back({declaration.important ? 1 : 0, 1 << 28, INT_MAX, &declaration});
+        pushCandidates(&candidates, scratch, declaration, declaration.important ? 1 : 0, 1 << 28,
+                       INT_MAX);
       }
     }
     applyCandidates(&style, &candidates, nodeContext);
     finalizeStyle(&style, nodeContext);
+    if (!style.transitions.empty()) scratch->has_transitions = true;
 
+    /* `emplace` keeps the address of an existing entry stable, which is what
+     * `box->style` pointers rely on. */
     out[node] = style;
     childParent = &out[node];
     const XtStyle &computed = out[node];
-    computePseudo(node, PseudoElement::Before, computed, sheet, out, context, state, pseudos);
-    computePseudo(node, PseudoElement::After, computed, sheet, out, context, state, pseudos);
+    if (pseudos != nullptr && sheet.has_pseudo_elements) {
+      computePseudo(node, PseudoElement::Before, computed, sheet, applies, out, context, state,
+                    pseudos, scratch);
+      computePseudo(node, PseudoElement::After, computed, sheet, applies, out, context, state,
+                    pseudos, scratch);
+    }
+    g_perf_frame.restyleNodes += 1;
   }
   for (const std::unique_ptr<Node> &child : node->children) {
-    computeNode(child.get(), childParent, sheet, out, context, state, pseudos);
+    computeNode(child.get(), childParent, sheet, applies, out, context, state, pseudos, scratch);
   }
 }
 
@@ -431,16 +478,40 @@ void computeNode(const Node *node, const XtStyle *parent, const StyleSheet &shee
 
 void xt_style_compute(const Node *root, const StyleSheet &sheet,
                       std::unordered_map<const Node *, XtStyle> &out, float viewportWidth,
-                      float viewportHeight, const MatchState &state, PseudoNodeSet *pseudos) {
+                      float viewportHeight, const MatchState &state, PseudoNodeSet *pseudos,
+                      bool *hasTransitions) {
   out.clear();
-  if (pseudos != nullptr && root != nullptr) {
+  bool wantsPseudo = pseudos != nullptr && sheet.has_pseudo_elements;
+  if (wantsPseudo && root != nullptr) {
     resetPseudoPointers(root);
     pseudos->clear();
   }
   ApplyContext context;
   context.viewportWidth = viewportWidth;
   context.viewportHeight = viewportHeight;
-  computeNode(root, nullptr, sheet, out, context, state, pseudos);
+  /* An `@media` prelude is evaluated once per rule (not once per rule *and*
+   * node): the query never depends on the element, so this was the engine's
+   * largest per-element cost on a large document. */
+  std::vector<char> applies(sheet.rules.size(), 0);
+  for (size_t i = 0; i < sheet.rules.size(); i++) {
+    const std::string &media = sheet.rules[i].media;
+    if (media.empty()) {
+      applies[i] = 1;
+      continue;
+    }
+    g_perf_frame.mediaEvaluated += 1;
+    applies[i] =
+        xt_css_media_matches(media, viewportWidth, viewportHeight) ? (char)1 : (char)0;
+  }
+  ComputeScratch scratch;
+  scratch.candidates.reserve(32);
+  if (root != nullptr) {
+    computeNode(root, nullptr, sheet, applies, out, context, state, wantsPseudo ? pseudos : nullptr,
+                &scratch);
+  }
+  if (hasTransitions != nullptr) {
+    *hasTransitions = *hasTransitions || scratch.has_transitions;
+  }
 }
 
 }  // namespace xtgui

package/runtime/ext_gui/style.h

@@ -60,7 +60,7 @@ struct BackgroundGradientStop {
   Color color;
 };
 
-enum class BackgroundKind { Linear, Radial };
+enum class BackgroundKind { Linear, Radial, Image };
 
 /** How a radial layer's radii are chosen when it has no explicit lengths. */
 enum class RadialSize { ClosestSide, FarthestSide, ClosestCorner, FarthestCorner, Explicit };
@@ -80,6 +80,8 @@ struct BackgroundLayer {
   Length center_y{50.0f, Unit::Percent};
   Length radius_x{0.0f, Unit::Auto};  // Explicit radii only
   Length radius_y{0.0f, Unit::Auto};
+  /** `BackgroundKind::Image`: the `url(...)` source (a path or data URL). */
+  std::string image_src;
   std::vector<BackgroundGradientStop> stops;
 };
 
@@ -262,11 +264,12 @@ class PseudoNodeSet {
  * `state` supplies `:hover`/`:focus` for dynamic selector matching. When
  * `pseudos` is non-null, `::before`/`::after` styles are computed too and each
  * element's transient `pseudo_before`/`pseudo_after` pointers are published for
- * layout. */
+ * layout. When `hasTransitions` is non-null it is OR-ed with whether any
+ * computed style declares a `transition` (inline `style="…"` included). */
 void xt_style_compute(const Node *root, const StyleSheet &sheet,
                       std::unordered_map<const Node *, XtStyle> &out, float viewportWidth,
                       float viewportHeight, const MatchState &state = MatchState(),
-                      PseudoNodeSet *pseudos = nullptr);
+                      PseudoNodeSet *pseudos = nullptr, bool *hasTransitions = nullptr);
 
 /** Format a computed property for diagnostics/tests (`computedStyle(sel, prop)`). */
 std::string xt_style_property_to_string(const XtStyle &style, const std::string &property);

package/runtime/ext_gui/style_print.cpp

@@ -247,7 +247,13 @@ std::string xt_style_property_to_string(const XtStyle &style, const std::string
     std::string out;
     for (const BackgroundLayer &layer : style.background_layers) {
       if (!out.empty()) out += ", ";
-      out += layer.kind == BackgroundKind::Linear ? "linear-gradient()" : "radial-gradient()";
+      if (layer.kind == BackgroundKind::Linear) {
+        out += "linear-gradient()";
+      } else if (layer.kind == BackgroundKind::Radial) {
+        out += "radial-gradient()";
+      } else {
+        out += "url(" + layer.image_src + ")";
+      }
     }
     return out;
   }

package/runtime/ext_gui/text.cpp

@@ -17,6 +17,8 @@
 
 #include "text.h"
 
+#include "perf.h"
+
 #include <ft2build.h>
 #include FT_FREETYPE_H
 
@@ -25,6 +27,7 @@
 
 #include <cmath>
 #include <cstddef>
+#include <cstdint>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
@@ -125,6 +128,10 @@ struct Engine {
   std::unordered_map<std::string, std::unique_ptr<Font>> cache;  // key -> face (may be null)
   std::unordered_map<std::string, std::vector<Font *>> fallbacks;  // class+size -> faces
   std::unordered_map<std::string, hb_face_t *> hb_faces;         // path -> face
+  /** Primary face by (family class, pixel size): `xt_text_resolve` and
+   * `xt_text_metrics` are called per text box per layout, and building the
+   * 512-byte path key each time showed up in the profile. */
+  std::unordered_map<std::string, Font *> primary;
 };
 
 Engine &engine() {
@@ -416,9 +423,15 @@ Font *xt_text_resolve(const FontSpec &spec) {
   if (!e.ft_ok) return nullptr;
 
   bool mono = isMonospaceFamily(spec.family);
+  char key[48];
+  std::snprintf(key, sizeof(key), "%c|%.4f", mono ? 'm' : 's', (double)spec.pixel_size);
+  auto cached = e.primary.find(key);
+  if (cached != e.primary.end()) return cached->second;
+
   const std::string &path = mono ? e.mono_path : e.sans_path;
-  if (path.empty()) return nullptr;
-  return resolveFacePath(path, spec.pixel_size, mono);
+  Font *font = path.empty() ? nullptr : resolveFacePath(path, spec.pixel_size, mono);
+  e.primary.emplace(key, font);
+  return font;
 }
 
 Font *xt_text_scale(Font *font, float pixel_size) {
@@ -429,12 +442,14 @@ Font *xt_text_scale(Font *font, float pixel_size) {
 float xt_text_measure_width(const std::string &utf8, const FontSpec &spec) {
   Font *font = xt_text_resolve(spec);
   if (font == nullptr) return approximateWidth(utf8, spec.pixel_size, spec.family);
-  std::vector<ShapedGlyph> glyphs;
-  return xt_text_shape_run(utf8, font, glyphs);
+  if (utf8.empty()) return 0.0f;
+  const ShapedRun *run = xt_text_shape_cached(utf8, font);
+  return run != nullptr ? run->width : 0.0f;
 }
 
 float xt_text_shape_run(const std::string &utf8, Font *font, std::vector<ShapedGlyph> &out) {
   if (font == nullptr) return 0;
+  g_perf_frame.textShapeCalls += 1;
   float total = 0;
   size_t index = 0;
   size_t segment_start = 0;
@@ -502,6 +517,10 @@ bool xt_text_ready() {
 
 void xt_text_shutdown() {
   Engine &e = engine();
+  /* Cached shaped runs point at faces, so drop them before the faces go. */
+  xt_text_cache_clear();
+  xt_text_glyph_cache_clear();
+  e.primary.clear();
   e.fallbacks.clear();
   e.cache.clear();
   for (auto &entry : e.hb_faces) {

package/runtime/ext_gui/text.h

@@ -40,6 +40,12 @@ struct ShapedGlyph {
   Font *font = nullptr;
 };
 
+/** One shaped run: its glyphs and total advance. */
+struct ShapedRun {
+  float width = 0;
+  std::vector<ShapedGlyph> glyphs;
+};
+
 /** An 8-bit grayscale glyph bitmap, as produced by FreeType. */
 struct GlyphImage {
   int width = 0;
@@ -59,6 +65,19 @@ Font *xt_text_resolve(const FontSpec &spec);
  * glyph's `font` says which face it belongs to. */
 float xt_text_shape_run(const std::string &utf8, Font *font, std::vector<ShapedGlyph> &out);
 
+/** Shape `utf8` through the process-wide bounded cache (`text_cache.cpp`).
+ * Returns a stable pointer for the lifetime of the cache entry (valid until the
+ * next cache generation is dropped); callers must not hold it across frames.
+ * Layout and paint both go through this, so a word is shaped once instead of
+ * once per layout pass and again per repaint. `nullptr` for a null face. */
+const ShapedRun *xt_text_shape_cached(const std::string &utf8, Font *font);
+
+/** Current cache occupancy (bytes of keys + glyphs, number of entries). */
+uint64_t xt_text_cache_bytes();
+uint64_t xt_text_cache_entries();
+/** Drop every entry (called by `xt_text_shutdown`, and by tests). */
+void xt_text_cache_clear();
+
 /** The same face as `font` at a different pixel size (used to rasterise glyphs
  * at the display's scale factor), or null when it cannot be loaded. */
 Font *xt_text_scale(Font *font, float pixel_size);
@@ -67,6 +86,16 @@ Font *xt_text_scale(Font *font, float pixel_size);
  * the glyph has no outline (e.g. a space) or cannot be rendered. */
 bool xt_text_rasterize(Font *font, uint32_t glyph, GlyphImage &out);
 
+/** `xt_text_rasterize` through a bounded, two-generation cache. A canvas that
+ * redraws the same text every frame otherwise runs FreeType for every glyph of
+ * every `fillText`. The pointer stays valid for the rest of the frame (until a
+ * later call fills a generation and drops the spare one); callers must not hold
+ * it across frames. Returns null for a glyph without a bitmap. */
+const GlyphImage *xt_text_glyph_cached(Font *font, uint32_t glyph);
+
+/** Drop every cached glyph bitmap (called by `xt_text_shutdown`). */
+void xt_text_glyph_cache_clear(void);
+
 /** Shaped horizontal advance of `utf8` in pixels. Falls back to a deterministic
  * approximation when no font file can be loaded. */
 float xt_text_measure_width(const std::string &utf8, const FontSpec &spec);

package/runtime/ext_gui/text_cache.cpp

@@ -0,0 +1,118 @@
+/*
+ * xbintsc GUI engine — bounded shaping cache.
+ *
+ * Layout measures every word of the document on every layout pass, and the
+ * renderer shapes every text run again to place its glyphs. Without a cache a
+ * document with a few thousand words runs thousands of HarfBuzz shapes per
+ * frame, which is what made a large page unusable. This module memoises
+ * `(face, text) -> glyphs + advance` behind a two-generation cache: when the
+ * budget is exceeded the *spare* generation is dropped and becomes the current
+ * one, so no entry-by-entry LRU bookkeeping is needed on the hot path (a
+ * document that cycles through many strings keeps at most two budgets).
+ *
+ * The key is the resolved face pointer plus the text: fallback faces, sizes and
+ * `XT_GUI_FONT` overrides each resolve to their own face, and
+ * `xt_text_shutdown()` clears the cache before the faces are freed.
+ */
+
+#include "text.h"
+
+#include "perf.h"
+
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace xtgui {
+namespace {
+
+/** Glyph + key budget per generation. A shaped glyph is 24 bytes, so 2 MiB is
+ * roughly 80k glyphs (more than any single document draws). */
+constexpr uint64_t kMaxBytes = 2ull * 1024 * 1024;
+constexpr uint64_t kMaxEntries = 8192;
+
+struct Key {
+  Font *font = nullptr;
+  std::string text;
+
+  bool operator==(const Key &other) const {
+    return font == other.font && text == other.text;
+  }
+};
+
+struct KeyHash {
+  size_t operator()(const Key &key) const {
+    size_t hash = std::hash<const void *>()(key.font);
+    // FNV-ish mix of the text, then combine — cheap and stable.
+    size_t textHash = std::hash<std::string>()(key.text);
+    hash ^= textHash + 0x9e3779b97f4a7c15ull + (hash << 6) + (hash >> 2);
+    return hash;
+  }
+};
+
+struct Generation {
+  std::unordered_map<Key, ShapedRun, KeyHash> runs;
+  uint64_t bytes = 0;
+};
+
+Generation g_generations[2];
+int g_current = 0;
+
+uint64_t estimateBytes(const Key &key, const ShapedRun &run) {
+  /* Key/Run objects plus the map node's own overhead (a rough, conservative
+   * constant: the budget is a guard, not an allocator). */
+  return (uint64_t)sizeof(Key) + (uint64_t)key.text.size() + (uint64_t)sizeof(ShapedRun) +
+         (uint64_t)run.glyphs.size() * sizeof(ShapedGlyph) + 64;
+}
+
+/** Rotate to the spare generation when the current one is full. */
+void respectBudget() {
+  Generation &current = g_generations[g_current];
+  if (current.runs.size() <= kMaxEntries && current.bytes <= kMaxBytes) return;
+  int spare = 1 - g_current;
+  g_generations[spare].runs.clear();
+  g_generations[spare].bytes = 0;
+  g_current = spare;
+}
+
+}  // namespace
+
+const ShapedRun *xt_text_shape_cached(const std::string &utf8, Font *font) {
+  if (font == nullptr) return nullptr;
+  if (utf8.empty()) return nullptr;
+  Key key;
+  key.font = font;
+  key.text = utf8;
+  Generation &generation = g_generations[g_current];
+  auto found = generation.runs.find(key);
+  if (found != generation.runs.end()) {
+    g_perf_frame.textShapeHits += 1;
+    return &found->second;
+  }
+
+  auto inserted = generation.runs.emplace(std::move(key), ShapedRun());
+  ShapedRun &run = inserted.first->second;
+  run.width = xt_text_shape_run(utf8, font, run.glyphs);
+  generation.bytes += estimateBytes(inserted.first->first, run);
+  respectBudget();
+  return &run;
+}
+
+uint64_t xt_text_cache_bytes() {
+  return g_generations[0].bytes + g_generations[1].bytes;
+}
+
+uint64_t xt_text_cache_entries() {
+  return (uint64_t)(g_generations[0].runs.size() + g_generations[1].runs.size());
+}
+
+void xt_text_cache_clear() {
+  g_generations[0].runs.clear();
+  g_generations[0].bytes = 0;
+  g_generations[1].runs.clear();
+  g_generations[1].bytes = 0;
+  g_current = 0;
+}
+
+}  // namespace xtgui

package/runtime/ext_gui/text_glyph_cache.cpp

@@ -0,0 +1,100 @@
+/*
+ * xbintsc GUI engine — cached glyph bitmaps.
+ *
+ * `xt_text_rasterize` runs FreeType for one glyph. Canvas `fillText` used to
+ * call it for every glyph of every draw, so a redrawn label paid the whole
+ * rasterisation cost again on every frame. This unit keeps the bitmaps in two
+ * bounded generations, the same policy as the shaped-run cache in
+ * `text_cache.cpp`: a hot generation survives, and a page that walks a huge
+ * alphabet cannot grow the cache without bound.
+ *
+ * The cache is process-wide (fonts are), keyed by the face pointer and the
+ * glyph id. It is deliberately leaked at shutdown like the other engine
+ * caches; `xt_text_glyph_cache_clear` drops its contents when the fonts go.
+ */
+
+#include "text.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <unordered_map>
+#include <utility>
+
+namespace xtgui {
+
+namespace {
+
+/** Per-generation bitmap budget and entry cap. */
+constexpr size_t kGlyphCacheBytes = 2u * 1024u * 1024u;
+constexpr size_t kGlyphCacheEntries = 8192;
+
+struct GlyphCache {
+  std::unordered_map<uint64_t, GlyphImage> current;
+  std::unordered_map<uint64_t, GlyphImage> spare;
+  size_t current_bytes = 0;
+  size_t spare_bytes = 0;
+};
+
+GlyphCache &glyph_cache() {
+  /* Deliberately leaked: `Font` objects are destroyed at shutdown after this
+   * cache would be, and the key holds their addresses (never dereferenced). */
+  static GlyphCache *cache = new GlyphCache();
+  return *cache;
+}
+
+uint64_t glyph_key(Font *font, uint32_t glyph) {
+  return (uint64_t)(uintptr_t)font << 32 | (uint64_t)glyph;
+}
+
+/** Drop the old generation and make the current one the spare. */
+void rotate(GlyphCache &cache) {
+  cache.current.swap(cache.spare);
+  std::swap(cache.current_bytes, cache.spare_bytes);
+  cache.spare.clear();
+  cache.spare_bytes = 0;
+}
+
+}  // namespace
+
+const GlyphImage *xt_text_glyph_cached(Font *font, uint32_t glyph) {
+  if (font == nullptr) return nullptr;
+  GlyphCache &cache = glyph_cache();
+  const uint64_t key = glyph_key(font, glyph);
+  auto found = cache.current.find(key);
+  if (found != cache.current.end()) {
+    return found->second.pixels.empty() ? nullptr : &found->second;
+  }
+  GlyphImage image;
+  auto spare = cache.spare.find(key);
+  if (spare != cache.spare.end()) {
+    image = std::move(spare->second);
+    cache.spare_bytes -= image.pixels.size();
+    cache.spare.erase(spare);
+  } else if (!xt_text_rasterize(font, glyph, image)) {
+    /* Cache the miss too: a space (or .notdef) would otherwise retry FreeType
+     * on every `fillText`. */
+    image.width = 0;
+    image.height = 0;
+    image.left = 0;
+    image.top = 0;
+  }
+  const size_t bytes = image.pixels.size();
+  if ((cache.current_bytes + bytes > kGlyphCacheBytes ||
+       cache.current.size() >= kGlyphCacheEntries) &&
+      !cache.current.empty()) {
+    rotate(cache);
+  }
+  cache.current_bytes += bytes;
+  auto inserted = cache.current.emplace(key, std::move(image));
+  return inserted.first->second.pixels.empty() ? nullptr : &inserted.first->second;
+}
+
+void xt_text_glyph_cache_clear(void) {
+  GlyphCache &cache = glyph_cache();
+  cache.current.clear();
+  cache.spare.clear();
+  cache.current_bytes = 0;
+  cache.spare_bytes = 0;
+}
+
+}  // namespace xtgui