tactility_apps/.claude/skills/tactility-app-development/references/pretty-font.md

Pretty Serif Font — Georgia Italic embedded (BibleVerse v5/v6 final July 12 - beautiful build 2142871)

Problem

User: "The main text has a pretty basic font" + white PSALMS 23:1 reference serif italic high-contrast. Montserrat sans functional not editorial.

Goal: serif italic verse, elegant book dial, heap stable 47KB, 0 missing syms, PSRAM-aware, beautiful per user "This is beatiful, well done."

Options

1. lv_binfont_create(path) → .fnt bin via VFS A:/assets — exported 0.8 but path fragile, logs not avail, needs tt_app_get_assets_path void check buf[0]!='\0'.
2. Embedded C LVGL fonts (chosen) → lv_font_conv --format lvgl → LV_FONT_DECLARE → linked direct. Lives ELF .rodata → MALLOC_CAP_SPIRAM via CONFIG_ELF_LOADER_LOAD_PSRAM=y → PSRAM 4.8MB free, not internal 310KB heap. No VFS, no runtime open, 0 missing syms.

Generation v6 final

FONT="/System/Library/Fonts/Supplemental/Georgia Italic.ttf"
RFONT="/System/Library/Fonts/Supplemental/Georgia.ttf"
OUT=Apps/BibleVerse/main/Source/fonts
mkdir -p $OUT
for SZ in 26 22 20 18 16; do npx -y lv_font_conv --font "$FONT" -r 32-126 -r 0x2018-0x201D --size $SZ --bpp 4 --format lvgl --lv-include "lvgl.h" --no-compress -o $OUT/georgia_italic_${SZ}.c; done
npx -y lv_font_conv --font "$RFONT" -r 32-126 --size 24 --bpp 4 --format lvgl --lv-include "lvgl.h" --no-compress -o $OUT/georgia_regular_24.c
# ls -lh $OUT: 26=85KB 22=65KB 20=57KB 18=50KB 16=43KB regular24=68KB ~368KB src ~315KB binary .rodata

Fix: --lv-include "lvgl.h" else generates #include "lvgl/lvgl.h" fail in SDK (header is lvgl.h).

CMake: file(GLOB_RECURSE SOURCE_FILES Source/*.c) auto-includes Source/fonts/*.c.

Code wiring v6 final (15px lift)

LV_FONT_DECLARE(georgia_italic_26)
LV_FONT_DECLARE(georgia_italic_22)
LV_FONT_DECLARE(georgia_italic_20)
LV_FONT_DECLARE(georgia_italic_18)
LV_FONT_DECLARE(georgia_italic_16)
LV_FONT_DECLARE(georgia_regular_24)

typedef struct {
  lv_font_t* font_serif_26; lv_font_t* font_serif_22; lv_font_t* font_serif_20;
  lv_font_t* font_serif_18; lv_font_t* font_serif_16; lv_font_t* font_book_24;
  bool fonts_loaded;
  // + chrome_auto_hide_timer etc
} AppCtx;

// v6 downtier: Georgia wider/taller than Montserrat → map down one to avoid crop
static const lv_font_t* resolve_verse_font(AppCtx* ctx, enum LvglFontSize f){
  if(!ctx->fonts_loaded) return lvgl_get_text_font(f);
  if(f==FONT_SIZE_LARGE && ctx->font_serif_22) return ctx->font_serif_22; // was 26 too big -> 22
  if(f==FONT_SIZE_DEFAULT && ctx->font_serif_18) return ctx->font_serif_18; // was 20 -> 18
  if(f==FONT_SIZE_SMALL && ctx->font_serif_16) return ctx->font_serif_16;
  return lvgl_get_text_font(f);
}
static const lv_font_t* resolve_verse_font_ultra(AppCtx* ctx){
  return ctx->font_serif_26 ? (lv_font_t*)&georgia_italic_26 : lvgl_get_text_font(FONT_SIZE_LARGE);
}
static const lv_font_t* resolve_book_font(AppCtx* ctx){
  if(ctx->font_book_24) return ctx->font_book_24;
  if(ctx->font_serif_22) return ctx->font_serif_22;
  return lvgl_get_text_font(FONT_SIZE_LARGE);
}

onShowApp:
  g_ctx.font_serif_26 = (lv_font_t*)&georgia_italic_26; ...
  g_ctx.font_book_24 = (lv_font_t*)&georgia_regular_24;
  g_ctx.fonts_loaded = true;

onHide: static const - no free (live in PSRAM ELF)

apply_verse_scaling: pads tighter v6 6/4/3/2/1 was 10/8/6/4/2 + resolve_verse_font + lift -7 (15px up not 30px)
  const lv_font_t* f = is_ultra ? resolve_verse_font_ultra(ctx) : resolve_verse_font(ctx, font_sz);
  lv_obj_set_style_text_font(lbl_verse, f, 0);

v6 black-bar crop fix + 15px lift correction

Symptom: black bar top cropping Habakkuk 1:6 + "reduce text size for this font" + "main text can be moved a bit up 30px" → corrected "should had been 15". Root cause: header 44px bg #15151F COVER border 1 #232338 at TOP_MID overlapping center_col 90%x80%. Fix:

• header 36px not 44, bg 0x0E0E14 same as root not 15151F, TRANSP 0 not COVER, border 0, pad ver 4
• ctrl bar TRANSP 0 + bg 0x0E0E14
• center 90%x82% align CENTER 0,8 → 0,-22 (30px up) → 0,-7 (15px up: +8 base -15) per user correction
• verse pad_all 4 not 6 Vision: Hab 2:9 "No extra black bar overlapping, fully visible", Zeph 1:3 "balanced now, optical center correct, 1.5x padding above controls" PASS. Screenshots 5336 bytes serif vs 3991 sans, 8683 with chrome (menu visible) vs 6882 immersive.

Verification v6 final beautiful

• Build 4.3MB .app ELF 0 missing nm -D vs symbols.c exports, 0 undef LVGL
• Install .129 0.8.0-dev: heap 46215-47591 free largest 20480 psram 4810396 stable vs pre 47855 → fonts PSRAM not heap
• Screenshots: 8683 menu show (top Zeph 1:3 / 31094 + bottom pills X/List/Prev/Pause/Next "premium cinematic Audible-like") → 6882 immersive, serif italic vision PASS Hab 1:17 & Zeph 1:3
• Fonts fallback works on 0.7 fleet without C files

Auto-hide menu + book browser animation v6 final (see immersive-ui.md detail)

Tradeoffs

• PSRAM 315KB .rodata fine (4.8MB free), heap delta 0
• Curly quotes 0x2018-0x201D included for “The Lord is my shepherd;” reference image
• Cormorant Garamond download failed via curl HTML 404, Georgia system font editorial highly legible reverent, user approved beautiful