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
```bash
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)
```c
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