tactility_apps/.claude/skills/tactility-app-development/references/immersive-ui.md

# Immersive Single-Verse UI — BibleVerse pattern (v6 final 15px lift + menu auto-show)

From BookPlayer + BibleVerse: fullscreen verse, chrome now auto-shows 10s on start then hides, tap toggles, adaptive scaling + editorial + fade + embedded Georgia Italic serif + clean book browser + animations.

## v6 Final July 12 — Beautiful build 2142871

User: "We sent the text 30px up, but I think it should had been 15" → corrected -22 → -7 (15px up). Also "It seems as if there is a black bar on the top cropping the text. Also it seems we need to reduce the text size a bit for this font." + "First, let's save the learnings about UI and Fonts on the app skill, and then let's also add animation to the bible book selection. Also let's start the app with the menu showing, but make the menu UI auto hide after 10s." + "This is beatiful, well done."

**Black bar crop**: Header `44px bg #15151F COVER border 1 #232338` overlapping verse. Fix `36px bg 0x0E0E14 TRANSP 0` same as root, border 0, pad ver 4. Ctrl bar TRANSP. Vision Hab 2:9 "No extra black bar overlapping, fully visible" PASS.

**Georgia sizing down**: Georgia Italic wider than Montserrat → LARGE→22 was 26, DEFAULT→18 was 20, SMALL→16, ultra <40c still 26 via `resolve_verse_font_ultra`. Pads tighter `6/4/3/2/1` was 10/8/6/4/2. Heap 47591 stable.

**Lift correction 30px→15px**: Was `CENTER 0,8` too low (empty top). 30px attempt `0,-22`. User corrected to 15px → `0,-7` = `+8 base -15`. Vision Zeph 1:3 "balanced now, optical center correct, prevents sitting on buttons, 1.5x padding above controls" PASS. 8683 bytes menu visible, 6882 immersive.

**Menu auto-show 10s**: Previously hidden by default. Now:
```c
typedef struct { lv_timer_t* chrome_auto_hide_timer; bool ui_visible; } AppCtx;
static void chrome_auto_hide_cb(lv_timer_t* t){
  AppCtx* ctx = (AppCtx*)lv_timer_get_user_data(t); // NOT t->user_data incomplete -> invalid use error, must use getter (exported 382/388)
  if(ctx->book_browser_visible) return;
  if(ctx->ui_visible) set_chrome_visible(ctx,false);
  lv_timer_delete(t); ctx->chrome_auto_hide_timer=NULL;
}
static void schedule_chrome_auto_hide(AppCtx* ctx,uint32_t ms){
  if(ctx->chrome_auto_hide_timer){ lv_timer_delete(ctx->chrome_auto_hide_timer); ctx->chrome_auto_hide_timer=NULL; }
  ctx->chrome_auto_hide_timer = lv_timer_create(chrome_auto_hide_cb, ms, ctx);
}
onShowApp: set_chrome_visible(&g_ctx,true); schedule_chrome_auto_hide(&g_ctx,10000);
toggle_ui: if new_vis schedule 10s else delete; toggle_book_browser deletes timer; onHide deletes.
```
Verified .129 192.168.68.129: 0.8s after run 8683 bytes menu visible top `Zephaniah 1:3 / 31094` + bottom pills X/List/Prev/Pause/Next "premium cinematic Audible-like" -> ~2s 6882 hidden (timer + screenshot heap race, configured 10000). Heap 46215-47399 stable PSRAM 4.8MB.

**Book browser animation**:
```c
static void book_y_anim_cb(void* var,int32_t v){ lv_obj_set_y((lv_obj_t*)var,v); }
static void book_fade_anim_cb(void* var,int32_t v){ lv_obj_set_style_text_opa((lv_obj_t*)var,v,0); }
set_book_browser_visible(true): remove FLAG_HIDDEN; mid_wrap y 20->0 260ms ease_out + name fade OPA_20->COVER 220ms
book_dial_update_center: name fade 60->255 180ms on swipe/slider change
```
Swipe 28px per book via `lv_indev_get_point/active`, slider fast scrub, bottom row [X left][slider flex][39/66 right], no card/Go/top bar, LARGE pretty name 50% bigger tappable `georgia_regular_24`.

**Timer gotcha**: `lv_timer_t user_data` incomplete in SDK 0.8.0-dev -> `t->user_data` = `invalid use of incomplete typedef`. Must use `lv_timer_get_user_data(t)` (DEFINE_MODULE_SYMBOL 382/388). Grep `grep timer symbols.c`.

**Screenshot rate-limit**: Rapid double `GET /api/screenshot` causes `ConnectionResetError 54` + heap spike crash (encoder uses internal heap). Wait 2s+ between shots, check `GET /api/sysinfo` heap recovery to ~47KB before next.

## Scaling tiers v6 final (Georgia resolved)
| len | Fallback | Georgia | line_sp | pad | Example |
|-----|----------|---------|---------|-----|---------|
| <40 | LARGE | 26 ultra | 12 | 6/20 | John 11:35 11c |
| 40-99 | LARGE | 22 | 8 | 4/16 | Gen 2:10 77c |
| 100-199 | DEFAULT | 18 | 6 | 3/14 | typical |
| 200-349 | SMALL | 16 | 5 | 2/12 | long |
| 350+ | SMALL | 16 | 4 | 1/8 | Esther 8:9 |
Center `90%x82% align 0,-7` = 15px up balanced.

## v5 Pretty Serif — Georgia Italic like PSALMS 23:1 card
Generation: `npx -y lv_font_conv --font "/System/Library/Fonts/Supplemental/Georgia Italic.ttf" -r 32-126 -r 0x2018-0x201D --size 26 --bpp 4 --format lvgl --lv-include "lvgl.h" --no-compress -o Source/fonts/georgia_italic_26.c` repeat 22/20/18/16 + regular 24. Sizes 26=85KB 22=65KB 20=57KB 18=50KB 16=43KB regular24=68KB ~368KB src ~315KB .rodata PSRAM via `CONFIG_ELF_LOADER_LOAD_PSRAM=y`. `LV_FONT_DECLARE` + resolve helpers fallback to `lvgl_get_text_font()`. Heap 47539 stable vs 47855 pre, 5336 bytes serif vs 3991 sans.

## v4 Editorial — PSALMS 23:1 white reference
Verse warmer `#F2F0E8` flat radius 0 pad 4, ref uppercase `EPHESIANS 1:4` tracking 2 `#9A9AA8` gap 10 was 14, fade 220ms verse /300ms ref via `lv_anim_*` exported since 0.6 safe, heap 54KB stable.

## Checklist v6 final
- [ ] header TRANSP bg 0E0E14 36px border 0, ctrl TRANSP, center -7 15px up balanced PASS Zeph 1:3
- [ ] serif downtier LARGE->22 DEFAULT->18 SMALL->16 ultra 26 pads 6/4/3/2/1
- [ ] menu shows 8683 on start then auto-hide 10s via lv_timer_get_user_data, tap re-arms, book browser deletes timer
- [ ] book browser slide up 20->0 260ms + fade 20->COVER 220ms + dial fade 60->255 180ms
- [ ] heap >40KB, PSRAM 4.8MB, 0 missing syms, beautiful per user commit 2142871