xbintsc 0.5.45 → 0.5.52

package/runtime/ext_gui/text.cpp

@@ -1,542 +1,70 @@
 /*
- * xbintsc GUI engine — text stack implementation.
+ * xbintsc GUI engine — text front-end.
  *
- * HarfBuzz does shaping (ligatures/kerning/complex scripts), FreeType owns the
- * glyph outlines and the vertical metrics. We create one HarfBuzz font per
- * (file, pixel size) and scale it so that advances come back in 26.6 pixels.
- *
- * A run is shaped with a *single* face, but that face rarely covers every
- * codepoint in it — a CJK face such as Microsoft YaHei / PingFang / Noto Sans
- * CJK has no geometric shapes (U+25AE ▮, U+25AF ▯, …), and a Latin face has no
- * CJK. Each codepoint therefore resolves to the first face in a small fallback
- * chain that has it, the run is shaped in segments (one per face), and each
- * shaped glyph carries the face it came from so the rasteriser draws it from
- * the right atlas entry. Without this a missing glyph came back as `.notdef`
- * (glyph 0) and the renderer silently dropped it.
+ * The engine always links the bundled stb_truetype backend (`text_stb.cpp`).
+ * The optional `shaping` link feature installs a HarfBuzz + FreeType backend
+ * (`text_hb.cpp`) through `TextApi`; all public text entry points dispatch
+ * through the active table, so the core never references either library
+ * directly and a Latin-only page keeps the small DOM-only binary.
  */
 
-#include "text.h"
+#include "text_api.h"
 
 #include "perf.h"
-
-#include <ft2build.h>
-#include FT_FREETYPE_H
-
-#include <hb.h>
-#include <hb-ot.h>
-
-#include <cmath>
-#include <cstddef>
-#include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
-#include <memory>
-#include <string>
-#include <unordered_map>
-#include <vector>
+#include "text_fonts.h"
 
 namespace xtgui {
 
-/* Opaque to callers (declared in text.h); defined here so the loading helpers
- * in the anonymous namespace can build it. */
-struct Font {
-  FT_Face ft_face = nullptr;
-  hb_font_t *hb_font = nullptr;
-  std::string path;
-  bool monospace = false;
-  float pixel_size = 16.0f;
-  float ascent = 0;
-  float descent = 0;
-  float line_height = 0;
-
-  ~Font() {
-    if (hb_font != nullptr) hb_font_destroy(hb_font);
-    if (ft_face != nullptr) FT_Done_Face(ft_face);
-  }
-};
-
 namespace {
 
-const char *const kSansCandidates[] = {
-    /* Explicit override wins (also checked per family class below). */
-    nullptr,
-    /* Fonts with CJK coverage come first: the default face is a single face, so
-     * it has to be able to render Chinese/Japanese/Korean text as well as
-     * Latin (see "Implemented text" in doc/gui.md). */
-    "C:\\Windows\\Fonts\\msyh.ttc",      /* Microsoft YaHei (Win 8.1+) */
-    "C:\\Windows\\Fonts\\msyh.ttf",      /* Microsoft YaHei (Win 7) */
-    "C:\\Windows\\Fonts\\Deng.ttf",      /* DengXian */
-    "C:\\Windows\\Fonts\\simsun.ttc",    /* SimSun */
-    "/System/Library/Fonts/PingFang.ttc",
-    "/System/Library/Fonts/STHeiti Light.ttc",
-    "/System/Library/Fonts/Helvetica.ttc",
-    "/System/Library/Fonts/Supplemental/Arial.ttf",
-    "/System/Library/Fonts/Supplemental/Verdana.ttf",
-    "/Library/Fonts/Arial.ttf",
-    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
-    "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
-    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
-    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
-    "/usr/share/fonts/TTF/DejaVuSans.ttf",
-    "/usr/share/fonts/dejavu/DejaVuSans.ttf",
-    "C:\\Windows\\Fonts\\segoeui.ttf",
-    "C:\\Windows\\Fonts\\arial.ttf",
-};
-
-const char *const kMonoCandidates[] = {
-    nullptr,
-    "C:\\Windows\\Fonts\\msyh.ttc",      /* CJK-capable fallback (see above) */
-    "/System/Library/Fonts/PingFang.ttc",
-    "/System/Library/Fonts/Menlo.ttc",
-    "/System/Library/Fonts/Supplemental/Courier New.ttf",
-    "/System/Library/Fonts/Courier.ttc",
-    "/Library/Fonts/Courier New.ttf",
-    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
-    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
-    "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf",
-    "/usr/share/fonts/TTF/DejaVuSansMono.ttf",
-    "C:\\Windows\\Fonts\\consola.ttf",
-    "C:\\Windows\\Fonts\\cour.ttf",
-};
-
-/* Faces tried after the primary one for codepoints it does not cover. Symbol
- * faces come first (they carry the geometric shapes, arrows, box drawing and
- * dingbats the CJK/Latin primary often lacks), then the other family class so
- * a monospace run still gets CJK and a sans run still gets monospace-only
- * codepoints. The primary and duplicates are dropped when the chain is built. */
-const char *const kSymbolCandidates[] = {
-    nullptr,
-    "C:\\Windows\\Fonts\\seguisym.ttf",  /* Segoe UI Symbol */
-    "C:\\Windows\\Fonts\\arialuni.ttf",  /* Arial Unicode MS */
-    "/System/Library/Fonts/Apple Symbols.ttf",
-    "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
-    "/usr/share/fonts/truetype/noto/NotoSansSymbols2-Regular.ttf",
-    "/usr/share/fonts/truetype/noto/NotoSansSymbols-Regular.ttf",
-    "/usr/share/fonts/truetype/ancient-scripts/Symbola_hint.ttf",
-    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
-};
-
-struct Engine {
-  bool initialized = false;
-  FT_Library ft = nullptr;
-  bool ft_ok = false;
-  std::string sans_path;
-  std::string mono_path;
-  std::vector<std::string> sans_fallbacks;
-  std::vector<std::string> mono_fallbacks;
-  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() {
-  static Engine instance;
-  return instance;
-}
-
-bool fileExists(const char *path) {
-  FILE *file = fopen(path, "rb");
-  if (file == nullptr) return false;
-  fclose(file);
-  return true;
-}
-
-/* Deliberately crude, deterministic per-byte advance (fraction of the font
- * size). Used only when no font file can be loaded. */
-float charAdvance(unsigned char c) {
-  if (c < 0x20 || c == 0x7f) return 0.0f;
-  if (c >= 0x80) return 0.55f;
-  char ch = (char)c;
-  if (ch == ' ') return 0.28f;
-  if (std::strchr("ilj|.,:;'!`", ch) != nullptr) return 0.26f;
-  if (std::strchr("mwMW@%", ch) != nullptr) return 0.85f;
-  if (ch >= '0' && ch <= '9') return 0.56f;
-  if (ch >= 'A' && ch <= 'Z') return 0.64f;
-  if (std::strchr("()[]{}<>/\\\"", ch) != nullptr) return 0.36f;
-  return 0.52f;
-}
-
-/* Decode one UTF-8 sequence starting at `index`; advances `index`. */
-uint32_t decodeUtf8(const std::string &text, size_t &index) {
-  unsigned char first = (unsigned char)text[index];
-  if (first < 0x80) {
-    index += 1;
-    return first;
-  }
-  uint32_t code_point = 0;
-  size_t extra = 0;
-  if ((first & 0xe0) == 0xc0) {
-    code_point = first & 0x1f;
-    extra = 1;
-  } else if ((first & 0xf0) == 0xe0) {
-    code_point = first & 0x0f;
-    extra = 2;
-  } else if ((first & 0xf8) == 0xf0) {
-    code_point = first & 0x07;
-    extra = 3;
-  } else {
-    index += 1;
-    return 0xfffd;
-  }
-  if (index + extra >= text.size()) {
-    index = text.size();
-    return 0xfffd;
-  }
-  for (size_t i = 1; i <= extra; i++) {
-    unsigned char next = (unsigned char)text[index + i];
-    if ((next & 0xc0) != 0x80) {
-      index += 1;
-      return 0xfffd;
-    }
-    code_point = (code_point << 6) | (next & 0x3f);
-  }
-  index += extra + 1;
-  return code_point;
-}
-
-float approximateWidth(const std::string &utf8, float pixel_size, const std::string &family) {
-  bool monospace = family.find("mono") != std::string::npos ||
-                   family.find("courier") != std::string::npos;
-  float factor = monospace ? 0.6f : 1.0f;
-  float width = 0;
-  for (char c : utf8) width += charAdvance((unsigned char)c) * factor;
-  return width * pixel_size;
-}
-
-bool isMonospaceFamily(const std::string &family) {
-  return family.find("mono") != std::string::npos || family.find("courier") != std::string::npos ||
-         family.find("consol") != std::string::npos || family.find("menlo") != std::string::npos ||
-         family.find("code") != std::string::npos;
-}
-
-const char *firstExisting(const char *const *candidates, size_t count) {
-  for (size_t i = 0; i < count; i++) {
-    if (candidates[i] != nullptr && fileExists(candidates[i])) return candidates[i];
-  }
-  return nullptr;
-}
-
-void addFallbackPath(std::vector<std::string> &paths, const char *path) {
-  if (path == nullptr || !fileExists(path)) return;
-  for (const std::string &entry : paths) {
-    if (entry == path) return;
-  }
-  paths.push_back(path);
-}
-
-/* The chain for a primary face: every existing symbol face, then the other
- * family class (CJK coverage for a monospace primary and vice versa). The
- * primary itself is skipped because it is tried first, per codepoint. */
-void buildFallbackChain(std::vector<std::string> &paths, const std::string &primary,
-                        const std::string &otherClass) {
-  for (const char *candidate : kSymbolCandidates) {
-    if (candidate != nullptr && primary != candidate) addFallbackPath(paths, candidate);
-  }
-  if (!otherClass.empty() && otherClass != primary) addFallbackPath(paths, otherClass.c_str());
-}
-
-void ensureInitialized() {
-  Engine &e = engine();
-  if (e.initialized) return;
-  e.initialized = true;
-  if (FT_Init_FreeType(&e.ft) != 0) {
-    e.ft = nullptr;
-    return;
-  }
-  e.ft_ok = true;
-
-  const size_t sansCount = sizeof(kSansCandidates) / sizeof(kSansCandidates[0]);
-  const size_t monoCount = sizeof(kMonoCandidates) / sizeof(kMonoCandidates[0]);
-
-  const char *env = std::getenv("XT_GUI_FONT");
-  if (env != nullptr && env[0] != '\0' && fileExists(env)) e.sans_path = env;
-  if (e.sans_path.empty()) {
-    const char *path = firstExisting(kSansCandidates, sansCount);
-    if (path != nullptr) e.sans_path = path;
-  }
-
-  const char *envMono = std::getenv("XT_GUI_FONT_MONO");
-  if (envMono != nullptr && envMono[0] != '\0' && fileExists(envMono)) {
-    e.mono_path = envMono;
-  } else if (env != nullptr && env[0] != '\0' && fileExists(env) && isMonospaceFamily(env)) {
-    e.mono_path = env;
-  }
-  if (e.mono_path.empty()) {
-    const char *path = firstExisting(kMonoCandidates, monoCount);
-    if (path != nullptr) e.mono_path = path;
-  }
-  /* No dedicated monospace face: reuse the sans face so metrics stay real. */
-  if (e.mono_path.empty()) e.mono_path = e.sans_path;
-
-  buildFallbackChain(e.sans_fallbacks, e.sans_path, e.mono_path);
-  buildFallbackChain(e.mono_fallbacks, e.mono_path, e.sans_path);
-}
-
-hb_face_t *hbFaceForPath(const std::string &path) {
-  Engine &e = engine();
-  auto it = e.hb_faces.find(path);
-  if (it != e.hb_faces.end()) return it->second;
-  hb_blob_t *blob = hb_blob_create_from_file(path.c_str());
-  hb_face_t *face = nullptr;
-  if (blob != nullptr && hb_blob_get_length(blob) > 0) {
-    face = hb_face_create(blob, 0);
-  }
-  if (blob != nullptr) hb_blob_destroy(blob);
-  e.hb_faces[path] = face;
-  return face;
-}
-
-std::unique_ptr<Font> createFont(const std::string &path, float pixel_size, bool monospace) {
-  Engine &e = engine();
-  if (!e.ft_ok || path.empty()) return nullptr;
-
-  FT_Face face = nullptr;
-  if (FT_New_Face(e.ft, path.c_str(), 0, &face) != 0) return nullptr;
-  FT_Set_Pixel_Sizes(face, 0, (FT_UInt)(pixel_size + 0.5f));
-
-  auto font = std::make_unique<Font>();
-  font->ft_face = face;
-  font->path = path;
-  font->monospace = monospace;
-  font->pixel_size = pixel_size;
-
-  FT_Size_Metrics metrics = face->size->metrics;
-  font->ascent = metrics.ascender / 64.0f;
-  font->descent = -metrics.descender / 64.0f;
-  font->line_height = metrics.height / 64.0f;
-
-  hb_face_t *hb_face = hbFaceForPath(path);
-  if (hb_face != nullptr) {
-    font->hb_font = hb_font_create(hb_face);
-    hb_ot_font_set_funcs(font->hb_font);
-    int scale = (int)(pixel_size * 64.0f + 0.5f);
-    hb_font_set_scale(font->hb_font, scale, scale);
-    unsigned ppem = (unsigned)(pixel_size + 0.5f);
-    hb_font_set_ppem(font->hb_font, ppem, ppem);
-  }
-  return font;
-}
-
-/* Resolve one face by path, keyed by path+class+size so the primary resolved
- * through a `FontSpec` and the same face resolved as a fallback share one
- * `Font` (and one glyph-atlas key). */
-Font *resolveFacePath(const std::string &path, float pixel_size, bool monospace) {
-  Engine &e = engine();
-  if (!e.ft_ok || path.empty()) return nullptr;
-  char key[512];
-  std::snprintf(key, sizeof(key), "p|%c|%.2f|%s", monospace ? 'm' : 's', (double)pixel_size,
-                path.c_str());
-  auto it = e.cache.find(key);
-  if (it != e.cache.end()) return it->second.get();
-  std::unique_ptr<Font> font = createFont(path, pixel_size, monospace);
-  Font *raw = font.get();
-  e.cache.emplace(key, std::move(font));
-  return raw;
-}
-
-/* The resolved fallback faces for a primary, in order, cached per class+size. */
-const std::vector<Font *> &fallbackFaces(Font *font) {
-  static const std::vector<Font *> kEmpty;
-  if (font == nullptr) return kEmpty;
-  Engine &e = engine();
-  char key[80];
-  std::snprintf(key, sizeof(key), "f|%c|%.2f", font->monospace ? 'm' : 's',
-                (double)font->pixel_size);
-  auto it = e.fallbacks.find(key);
-  if (it != e.fallbacks.end()) return it->second;
-
-  const std::vector<std::string> &paths =
-      font->monospace ? e.mono_fallbacks : e.sans_fallbacks;
-  std::vector<Font *> faces;
-  for (const std::string &path : paths) {
-    Font *face = resolveFacePath(path, font->pixel_size, font->monospace);
-    if (face != nullptr) faces.push_back(face);
-  }
-  return e.fallbacks.emplace(key, std::move(faces)).first->second;
-}
-
-/* The face that draws `code_point`: the primary when it has the glyph, else the
- * first fallback that does, else the primary (so `.notdef` is still skipped). */
-Font *faceForCodePoint(Font *primary, uint32_t code_point) {
-  if (primary != nullptr && FT_Get_Char_Index(primary->ft_face, code_point) != 0) return primary;
-  for (Font *fallback : fallbackFaces(primary)) {
-    if (FT_Get_Char_Index(fallback->ft_face, code_point) != 0) return fallback;
-  }
-  return primary;
-}
-
-/* Shape one face's segment of a run and append its glyphs. */
-float shapeSegment(const std::string &segment, Font *font, std::vector<ShapedGlyph> &out) {
-  if (font == nullptr || segment.empty()) return 0;
-  float total = 0;
-  if (font->hb_font == nullptr) {
-    /* HarfBuzz unavailable: fall back to FreeType's per-codepoint advances. */
-    size_t index = 0;
-    while (index < segment.size()) {
-      uint32_t code_point = decodeUtf8(segment, index);
-      FT_UInt glyph = FT_Get_Char_Index(font->ft_face, code_point);
-      float advance = 0;
-      if (FT_Load_Glyph(font->ft_face, glyph, FT_LOAD_DEFAULT) == 0) {
-        advance = font->ft_face->glyph->advance.x / 64.0f;
-      }
-      ShapedGlyph shaped;
-      shaped.glyph = glyph;
-      shaped.x_advance = advance;
-      shaped.font = font;
-      total += advance;
-      out.push_back(shaped);
-    }
-    return total;
-  }
-
-  hb_buffer_t *buffer = hb_buffer_create();
-  hb_buffer_add_utf8(buffer, segment.c_str(), (int)segment.size(), 0, -1);
-  hb_buffer_guess_segment_properties(buffer);
-  hb_shape(font->hb_font, buffer, nullptr, 0);
-  unsigned count = hb_buffer_get_length(buffer);
-  hb_glyph_info_t *infos = hb_buffer_get_glyph_infos(buffer, nullptr);
-  hb_glyph_position_t *positions = hb_buffer_get_glyph_positions(buffer, nullptr);
-  for (unsigned i = 0; i < count; i++) {
-    ShapedGlyph shaped;
-    shaped.glyph = infos[i].codepoint;
-    shaped.x_advance = positions[i].x_advance / 64.0f;
-    shaped.x_offset = positions[i].x_offset / 64.0f;
-    shaped.y_offset = positions[i].y_offset / 64.0f;
-    shaped.font = font;
-    total += shaped.x_advance;
-    out.push_back(shaped);
-  }
-  hb_buffer_destroy(buffer);
-  return total;
-}
+const TextApi *g_api = nullptr;
 
 }  // namespace
 
-Font *xt_text_resolve(const FontSpec &spec) {
-  ensureInitialized();
-  Engine &e = engine();
-  if (!e.ft_ok) return nullptr;
+const TextApi *xt_text_api() { return g_api != nullptr ? g_api : xt_text_stb_api(); }
 
-  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;
+void xt_text_api_install(const TextApi *api) { g_api = api; }
 
-  const std::string &path = mono ? e.mono_path : e.sans_path;
-  Font *font = path.empty() ? nullptr : resolveFacePath(path, spec.pixel_size, mono);
-  e.primary.emplace(key, font);
-  return font;
-}
+Font *xt_text_resolve(const FontSpec &spec) { return xt_text_api()->resolve(spec); }
 
 Font *xt_text_scale(Font *font, float pixel_size) {
-  if (font == nullptr) return nullptr;
-  return resolveFacePath(font->path, pixel_size, font->monospace);
+  return xt_text_api()->scale(font, 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);
   if (utf8.empty()) return 0.0f;
-  const ShapedRun *run = xt_text_shape_cached(utf8, font);
+  Font *font = xt_text_resolve(spec);
+  if (font == nullptr) {
+    /* No font file: keep layout deterministic (bytes rather than codepoints;
+     * this path is only hit on hosts with no usable system font). */
+    return (float)utf8.size() * (spec.pixel_size * 0.55f + spec.letter_spacing);
+  }
+  const ShapedRun *run = xt_text_shape_cached(utf8, font, spec.letter_spacing);
   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;
-  Font *segment_font = nullptr;
-  while (index < utf8.size()) {
-    size_t char_start = index;
-    uint32_t code_point = decodeUtf8(utf8, index);
-    Font *chosen = faceForCodePoint(font, code_point);
-    if (segment_font == nullptr) {
-      segment_font = chosen;
-      segment_start = char_start;
-    } else if (chosen != segment_font) {
-      total += shapeSegment(utf8.substr(segment_start, char_start - segment_start), segment_font, out);
-      segment_font = chosen;
-      segment_start = char_start;
-    }
-  }
-  if (segment_font != nullptr) {
-    total += shapeSegment(utf8.substr(segment_start), segment_font, out);
-  }
-  return total;
+  return xt_text_api()->shape_run(utf8, font, out);
 }
 
 bool xt_text_rasterize(Font *font, uint32_t glyph, GlyphImage &out) {
-  out.width = 0;
-  out.height = 0;
-  out.left = 0;
-  out.top = 0;
-  out.pixels.clear();
-  if (font == nullptr || font->ft_face == nullptr) return false;
-  if (FT_Load_Glyph(font->ft_face, glyph, FT_LOAD_DEFAULT) != 0) return false;
-  if (FT_Render_Glyph(font->ft_face->glyph, FT_RENDER_MODE_NORMAL) != 0) return false;
-  FT_GlyphSlot slot = font->ft_face->glyph;
-  const FT_Bitmap &bitmap = slot->bitmap;
-  out.left = slot->bitmap_left;
-  out.top = slot->bitmap_top;
-  if (bitmap.width == 0 || bitmap.rows == 0) return false;
-  out.width = (int)bitmap.width;
-  out.height = (int)bitmap.rows;
-  out.pixels.resize((size_t)bitmap.width * bitmap.rows);
-  for (unsigned row = 0; row < bitmap.rows; row++) {
-    const unsigned char *source = bitmap.buffer + (ptrdiff_t)row * bitmap.pitch;
-    std::memcpy(out.pixels.data() + (size_t)row * bitmap.width, source, bitmap.width);
-  }
-  return true;
+  return xt_text_api()->rasterize(font, glyph, out);
 }
 
 void xt_text_metrics(const FontSpec &spec, float *ascent, float *descent, float *line_height) {
-  Font *font = xt_text_resolve(spec);
-  if (font != nullptr) {
-    if (ascent != nullptr) *ascent = font->ascent;
-    if (descent != nullptr) *descent = font->descent;
-    if (line_height != nullptr) *line_height = font->line_height;
-    return;
-  }
-  if (ascent != nullptr) *ascent = spec.pixel_size * 0.8f;
-  if (descent != nullptr) *descent = spec.pixel_size * 0.2f;
-  if (line_height != nullptr) *line_height = spec.pixel_size * 1.2f;
+  xt_text_api()->metrics(spec, ascent, descent, line_height);
 }
 
-bool xt_text_ready() {
-  ensureInitialized();
-  return engine().ft_ok;
-}
+bool xt_text_ready() { return xt_text_api()->ready(); }
 
 void xt_text_shutdown() {
-  Engine &e = engine();
-  /* Cached shaped runs point at faces, so drop them before the faces go. */
+  /* Cached shaped runs and glyphs point at backend faces; drop them first. */
   xt_text_cache_clear();
   xt_text_glyph_cache_clear();
-  e.primary.clear();
-  e.fallbacks.clear();
-  e.cache.clear();
-  for (auto &entry : e.hb_faces) {
-    if (entry.second != nullptr) hb_face_destroy(entry.second);
-  }
-  e.hb_faces.clear();
-  if (e.ft != nullptr) {
-    FT_Done_FreeType(e.ft);
-    e.ft = nullptr;
-  }
-  e.ft_ok = false;
-  e.initialized = false;
-  e.sans_path.clear();
-  e.mono_path.clear();
-  e.sans_fallbacks.clear();
-  e.mono_fallbacks.clear();
+  xt_text_api()->shutdown();
+  xt_font_db_shutdown();
 }
 
 }  // namespace xtgui

package/runtime/ext_gui/text.h

@@ -1,13 +1,19 @@
 /*
  * xbintsc GUI engine — text stack (M4).
  *
- * Text is shaped with HarfBuzz and rasterised with FreeType. Both libraries
- * are statically linked into `gui.a`; this module hides them behind a small
- * interface so layout and paint do not see the third-party types.
+ * Text is shaped and rasterised with the bundled stb_truetype; this module
+ * hides it behind a small interface so layout and paint do not see the
+ * third-party types. The shaper is a per-codepoint mapping plus the font's
+ * `kern` table: no OpenType ligatures or complex-script shaping, and only
+ * TrueType outlines (not CFF/OTF or variable fonts).
  *
- * Fonts are resolved lazily from well-known system locations (or a path in
- * `XT_GUI_FONT` / `XT_GUI_FONT_MONO`) and cached per size. Only regular
- * upright faces are used today; weight/italic selection is a later refinement.
+ * Fonts are resolved from the installed system faces: the CSS family list is
+ * matched case-insensitively, generic `sans-serif`/`serif`/`monospace` map to
+ * platform defaults, and `font-weight` / `font-style: italic` select the real
+ * bold/italic face of the chosen family (falling back to the nearest weight and
+ * to the requested family's other styles). `XT_GUI_FONT` / `XT_GUI_FONT_MONO`
+ * override the generic defaults, and faces are cached per size and collection
+ * index.
  */
 #ifndef XT_GUI_TEXT_H
 #define XT_GUI_TEXT_H
@@ -24,6 +30,8 @@ struct FontSpec {
   float pixel_size = 16.0f;
   int weight = 400;
   bool italic = false;
+  /** CSS `letter-spacing` in pixels; adds to each glyph's advance. */
+  float letter_spacing = 0.0f;
 };
 
 /** Opaque loaded face (defined in text.cpp). */
@@ -46,7 +54,7 @@ struct ShapedRun {
   std::vector<ShapedGlyph> glyphs;
 };
 
-/** An 8-bit grayscale glyph bitmap, as produced by FreeType. */
+/** An 8-bit grayscale glyph bitmap, as produced by stb_truetype. */
 struct GlyphImage {
   int width = 0;
   int height = 0;
@@ -70,7 +78,8 @@ float xt_text_shape_run(const std::string &utf8, Font *font, std::vector<ShapedG
  * 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);
+const ShapedRun *xt_text_shape_cached(const std::string &utf8, Font *font,
+                                      float letter_spacing = 0.0f);
 
 /** Current cache occupancy (bytes of keys + glyphs, number of entries). */
 uint64_t xt_text_cache_bytes();
@@ -87,7 +96,7 @@ Font *xt_text_scale(Font *font, float pixel_size);
 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
+ * redraws the same text every frame otherwise rasterises with stb_truetype 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. */

package/runtime/ext_gui/text_api.h

@@ -0,0 +1,45 @@
+/*
+ * xbintsc GUI engine — text backend table.
+ *
+ * The default backend is the bundled stb_truetype implementation
+ * (`text_stb.cpp`). The optional `shaping` link feature installs a
+ * HarfBuzz + FreeType backend (`text_hb.cpp`) through this table, so the core
+ * never references either library directly. A page with only Latin text can
+ * therefore keep the ~3 MiB DOM-only binary, while a complex-script page can
+ * opt into full OpenType shaping.
+ */
+#ifndef XT_GUI_TEXT_API_H
+#define XT_GUI_TEXT_API_H
+
+#include <string>
+#include <vector>
+
+#include "text.h"
+
+namespace xtgui {
+
+struct TextApi {
+  Font *(*resolve)(const FontSpec &spec);
+  Font *(*scale)(Font *font, float pixel_size);
+  float (*shape_run)(const std::string &utf8, Font *font, std::vector<ShapedGlyph> &out);
+  bool (*rasterize)(Font *font, uint32_t glyph, GlyphImage &out);
+  void (*metrics)(const FontSpec &spec, float *ascent, float *descent, float *line_height);
+  bool (*ready)();
+  void (*shutdown)();
+};
+
+/** The built-in stb_truetype backend, always linked. */
+const TextApi *xt_text_stb_api();
+
+/** Install the optional backend (called by the `shaping` feature bridge). */
+void xt_text_api_install(const TextApi *api);
+
+/** The installed backend, or the stb_truetype default. */
+const TextApi *xt_text_api();
+
+}  // namespace xtgui
+
+/** Implemented by `text_hb.cpp`; called by the feature's C bridge. */
+extern "C" void xt_text_feature_register(void);
+
+#endif /* XT_GUI_TEXT_API_H */