Update docs

Author: ThomasFarstrike

docs/frameworks/font-manager.md

@@ -1,14 +1,13 @@
 # FontManager
 
-FontManager is a singleton framework for loading, caching, and composing LVGL fonts — including built-in bitmap fonts, TrueType fonts, and emoji image fonts. It automatically selects the best-quality pre-rendered emoji asset for the requested size and uses LVGL's imgfont fallback mechanism to render emoji inline with text.
+FontManager is a singleton framework for loading, caching, and composing LVGL fonts — including built-in bitmap fonts, TrueType fonts, and emoji image fonts. It uses LVGL's imgfont fallback mechanism to render 20×20 emoji PNGs inline with text, with nearest-neighbour scaling to match any font size.
 
 ## Overview
 
 FontManager centralizes all font concerns in a single class:
 
 - **Unified API** - One call (`getFont`) to get any font, with or without emoji support
-- **Emoji Compositing** - Transparently layers an emoji imgfont on top of any base font via LVGL's `fallback` mechanism
-- **Size-tiered Assets** - Picks the closest pre-rendered emoji PNG directory so LVGL never has to scale further than necessary
+- **Emoji Compositing** - Transparently layers 20×20 emoji PNGs via LVGL's imgfont fallback, with nearest-neighbour scaling to match any font size
 - **Lazy Caching** - Fonts and scaled image descriptors are cached on first use; no redundant work on subsequent calls
 - **Android-Inspired** - Follows the same singleton/class-method pattern as other MicroPythonOS frameworks
 
@@ -17,20 +16,20 @@ FontManager centralizes all font concerns in a single class:
 ```python
 from mpos import FontManager
 
-# Get a built-in Montserrat font at 16px, with emoji support (default)
+# Get a built-in Montserrat font at 16px (emoji disabled by default)
 font = FontManager.getFont(size=16, family="Montserrat")
 
-# Get the same font without emoji (e.g. for glyph enumeration)
-base_font = FontManager.getFont(size=16, family="Montserrat", emoji=False)
+# Get the same font with emoji support
+emoji_font = FontManager.getFont(size=16, family="Montserrat", emoji=True)
 
 # Load a TrueType font from a file
 ttf_font = FontManager.getFont(size=42, ttf="M:apps/com.myapp/assets/MyFont.ttf")
 
-# List all available built-in fonts (each already has emoji composed in)
+# List all available built-in fonts (pass emojis=True for composed fonts)
 for info in FontManager.listFonts():
     print(info["name"], info["size"])
 
-# Get all available emoji codepoints (union across all size tiers)
+# Get all available emoji codepoints
 for cp in FontManager.getEmojiCodepoints():
     print(hex(cp))
 ```
@@ -41,10 +40,10 @@ FontManager is implemented as a singleton using class variables and class method
 
 ### Font composition
 
-When `emoji=True` (the default), `getFont()` wraps the requested base font in an LVGL imgfont that renders emoji as scaled PNG images. The imgfont's `fallback` is set to the base font, so LVGL automatically falls through to the base font for any codepoint that is not an emoji.
+When `emoji=True`, `getFont()` wraps the requested base font in an LVGL imgfont that renders emoji as scaled PNG images. The imgfont's `fallback` is set to the base font, so LVGL automatically falls through to the base font for any codepoint that is not an emoji.
 
 ```
-getFont(size=16)
+getFont(size=16, emoji=True)
   └── base_font = font_montserrat_16          (builtin bitmap)
   └── emoji_font = lv.imgfont_create(...)     (PNG-based imgfont)
         └── emoji_font.fallback = base_font
@@ -53,14 +52,13 @@ getFont(size=16)
 
 ### Emoji size tiers
 
-Emoji PNGs are stored in size-specific directories under `builtin/res/emojis/`:
+Emoji PNGs are stored in `builtin/res/emojis/`:
 
-| Directory | Max target height | Used for |
-|-----------|------------------|----------|
-| `20x20/`  | ≤ 20 px          | Montserrat 8–16 (line heights ≤ 20 px) |
-| `56x56/`  | any              | Larger fonts |
+| Directory | Used for |
+|-----------|----------|
+| `20x20/`  | All fonts — emoji are rendered at 20×20 px and nearest-neighbour scaled up or down by LVGL as needed |
 
-`_imgfont_path_cb` receives the rendering font's pixel height and picks the smallest tier whose `max_height` is ≥ the target. This minimises (or eliminates) the nearest-neighbour downscale performed by LVGL's software renderer.
+`_imgfont_path_cb` receives the rendering font's pixel height and returns the 20×20 emoji source. LVGL's software renderer performs nearest-neighbour scaling to fit the target font size.
 
 ### Caching layers
 
@@ -75,7 +73,7 @@ Emoji PNGs are stored in size-specific directories under `builtin/res/emojis/`:
 
 ## API Reference
 
-### `getFont(size=None, ttf=None, family=None, emoji=True)`
+### `getFont(size=None, ttf=None, family=None, emoji=False)`
 
 Return a font object suitable for use with `set_style_text_font()`.
 
@@ -84,7 +82,7 @@ Return a font object suitable for use with `set_style_text_font()`.
 - `size` (int, optional): Target pixel size. Snapped to the nearest available builtin size. Defaults to 12.
 - `ttf` (str, optional): Path to a `.ttf` file (e.g. `"M:apps/myapp/assets/MyFont.ttf"`). When provided, `family` is ignored.
 - `family` (str, optional): Font family name — `"Montserrat"` (default) or `"Unscii"`.
-- `emoji` (bool): If `True` (default), the returned font transparently renders emoji via a PNG imgfont fallback. Pass `False` to get the raw base font (useful for `get_glyph_dsc` enumeration).
+- `emoji` (bool, optional): If `True`, the returned font transparently renders emoji via a PNG imgfont fallback. Defaults to `False`. Pass `True` to enable inline emoji rendering (adds a small rendering cost per emoji glyph).
 
 **Returns:** `lv.font_t` — the requested font, possibly wrapped with emoji support.
 
@@ -94,17 +92,17 @@ Return a font object suitable for use with `set_style_text_font()`.
 from mpos import FontManager
 import lvgl as lv
 
-font = FontManager.getFont(size=24, family="Montserrat")
+font = FontManager.getFont(size=24, family="Montserrat", emoji=True)
 label = lv.label(screen)
 label.set_style_text_font(font, lv.PART.MAIN)
 label.set_text("Hello ❤️ 😀")
 ```
 
 ---
 
-### `listFonts()`
+### `listFonts(emojis=False)`
 
-Return a list of all available built-in fonts, each already composed with emoji support.
+Return a list of all available built-in fonts. By default returns raw base fonts; pass `emojis=True` to wrap each font with emoji composition.
 
 **Returns:** list of dicts, each with keys:
 
@@ -120,7 +118,7 @@ Return a list of all available built-in fonts, each already composed with emoji
 from mpos import FontManager
 import lvgl as lv
 
-for info in FontManager.listFonts():
+for info in FontManager.listFonts(emojis=True):
     label = lv.label(screen)
     label.set_style_text_font(info["font"], lv.PART.MAIN)
     label.set_text(info["name"] + ": ABC 😀 ❤️")
@@ -130,7 +128,7 @@ for info in FontManager.listFonts():
 
 ### `getEmojiCodepoints()`
 
-Return a sorted list of all emoji codepoints available across all size tiers.
+Return a sorted list of all available emoji codepoints.
 
 **Returns:** list of int
 
@@ -165,28 +163,24 @@ clean = FontManager.normalizeEmojiText("❤️")  # removes U+FE0F after ❤
 
 ## Emoji Assets
 
-Emoji PNGs are stored in `internal_filesystem/builtin/res/emojis/` and are included in the firmware image at `/builtin/res/emojis/` on the device filesystem. Each subdirectory is a size tier:
+Emoji PNGs are stored in `internal_filesystem/builtin/res/emojis/` and are included in the firmware image at `/builtin/res/emojis/` on the device filesystem:
 
 ```
 builtin/res/emojis/
-├── 20x20/       # Pre-rendered at 20×20 px (Lanczos-downscaled from 56×56)
-│   ├── 1F600.png
-│   ├── 263A.png
-│   └── ...
-└── 56x56/       # Cropped from original 72×72 OpenMoji PNGs
+└── 20x20/       # Pre-rendered at 20×20 px
     ├── 1F600.png
     ├── 263A.png
     └── ...
 ```
 
-Files are named by their Unicode codepoint in uppercase hex (e.g. `1F600.png` for 😀). FontManager scans each directory at runtime and builds a `{codepoint: path}` map.
+Files are named by their Unicode codepoint in uppercase hex (e.g. `1F600.png` for 😀). FontManager scans the directory at runtime and builds a `{codepoint: path}` map.
 
 ### Adding new emoji
 
-1. Add a PNG named `<CODEPOINT_HEX>.png` to both `56x56/` and `20x20/` (generate the 20×20 version with ImageMagick):
+1. Add a PNG named `<CODEPOINT_HEX>.png` to `20x20/`:
 
 ```bash
-convert original.png -gravity center -crop 56x56+0+0 +repage -filter Lanczos -resize 20x20 20x20/CODEPOINT.png
+cp original.png 20x20/CODEPOINT.png
 ```
 
 2. The new emoji will be picked up automatically on next boot — no code changes needed.
@@ -198,8 +192,7 @@ internal_filesystem/
 ├── lib/mpos/ui/
 │   └── font_manager.py      # FontManager class
 └── builtin/res/emojis/
-    ├── 20x20/               # 20×20 px emoji PNGs
-    └── 56x56/               # 56×56 px emoji PNGs
+    └── 20x20/               # 20×20 px emoji PNGs
 ```
 
 ## Related Frameworks