update serial settings guide

Made it really stupidly clear that this is vibecoded

.vscode/extensions.json

@@ -1,4 +1,6 @@
 {
+    // See http://go.microsoft.com/fwlink/?LinkId=827846
+    // for the documentation about the extensions.json format
     "recommendations": [
         "pioarduino.pioarduino-ide",
         "platformio.platformio-ide"

Audiobook Player Guide.md

@@ -0,0 +1,78 @@
+## Audiobook Player (Audio variant only)
+
+Press **P** from the home screen to open the audiobook player.
+Place `.mp3`, `.m4b`, `.m4a`, or `.wav` files in `/audiobooks/` on the SD card.
+Files can be organised into subfolders (e.g. by author) — use **Enter** to
+browse into folders and **.. (up)** to go back.
+
+| Key | Action |
+|-----|--------|
+| W / S | Scroll file list / Volume up-down |
+| Enter | Select book or folder / Play-Pause |
+| A | Seek back 30 seconds |
+| D | Seek forward 30 seconds |
+| [ | Previous chapter (M4B only) |
+| ] | Next chapter (M4B only) |
+| Q | Leave player (audio continues) / Close book (when paused) / Exit (from file list) |
+
+### Recommended Format
+
+**MP3 is the recommended format.** M4B/M4A files are supported but currently
+have playback issues with the ESP32-audioI2S library — some files may fail to
+decode or produce silence. MP3 files play reliably and are the safest choice.
+
+MP3 files should be encoded at a **44100 Hz sample rate**. Lower sample rates
+(e.g. 22050 Hz) can cause distortion or playback failure due to ESP32-S3 I2S
+hardware limitations.
+
+**Bookmarks** are saved automatically every 30 seconds during playback and when
+you stop or exit. Reopening a book resumes from your last position.
+
+**Cover art** from M4B files is displayed as dithered monochrome on the e-ink
+screen, along with title, author, and chapter information.
+
+**Metadata caching** — the first time you open the audiobook player, it reads
+title and author tags from each file (which can take a few seconds with many
+files). This metadata is cached to the SD card so subsequent visits load
+near-instantly. If you add or remove files the cache updates automatically.
+
+### Background Playback
+
+Audio continues playing when you leave the audiobook player screen. Press **Q**
+while audio is playing to return to the home screen — a **>>** indicator will
+appear in the status bar next to the battery icon to show that audio is active
+in the background. Press **P** at any time to return to the player screen and
+resume control.
+
+If you pause or stop playback first and then press **Q**, the book is closed
+and you're returned to the file list instead.
+
+### Audio Hardware
+
+The audiobook player uses the PCM5102A I2S DAC on the audio variant of the
+T-Deck Pro (I2S pins: BCLK=7, DOUT=8, LRC=9). Audio is output via the 3.5mm
+headphone jack.
+
+> **Note:** The audiobook player is not available on the 4G modem variant
+> due to I2S pin conflicts.
+
+### SD Card Folder Structure
+
+```
+SD Card
+├── audiobooks/
+│   ├── .bookmarks/          (auto-created, stores resume positions)
+│   │   ├── mybook.bmk
+│   │   └── another.bmk
+│   ├── .metacache            (auto-created, speeds up file list loading)
+│   ├── Ann Leckie/
+│   │   ├── Ancillary Justice.mp3
+│   │   └── Ancillary Sword.mp3
+│   ├── Iain M. Banks/
+│   │   └── The Algebraist.mp3
+│   ├── mybook.mp3
+│   └── podcast.mp3
+├── books/                   (existing — text reader)
+│   └── ...
+└── ...
+```

Filter_clock_sync.py

@@ -0,0 +1,64 @@
+# PlatformIO monitor filter: automatic clock sync for Meck devices
+#
+# When a Meck device boots with no valid RTC time, it prints "MECK_CLOCK_REQ"
+# over serial.  This filter watches for that line and responds immediately
+# with "clock sync <epoch>\r\n", setting the device's real-time clock to
+# the host computer's current time.
+#
+# The sync is completely transparent — the user just sees it happen in the
+# boot log.  If the RTC already has valid time, the device never sends the
+# request and this filter does nothing.
+#
+# Install: place this file in <project>/monitor/filter_clock_sync.py
+# Enable:  add "clock_sync" to monitor_filters in platformio.ini
+#
+# Works with: PlatformIO Core >= 6.0
+
+import time
+
+from platformio.device.monitor.filters.base import DeviceFilter
+
+
+class ClockSync(DeviceFilter):
+    NAME = "clock_sync"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._buf = bytearray()
+        self._synced = False
+
+    def rx(self, text):
+        """Called with each chunk of data received from the device."""
+        if self._synced:
+            return text
+
+        # Accumulate into a line buffer to detect MECK_CLOCK_REQ
+        if isinstance(text, str):
+            self._buf.extend(text.encode("utf-8", errors="replace"))
+        else:
+            self._buf.extend(text)
+
+        if b"MECK_CLOCK_REQ" in self._buf:
+            epoch = int(time.time())
+            response = "clock sync {}\r\n".format(epoch)
+            try:
+                # Write directly to the serial port
+                self.miniterm.serial.write(response.encode("utf-8"))
+            except Exception as e:
+                # Fallback: shouldn't happen, but don't crash the monitor
+                import sys
+                print(
+                    "\n[clock_sync] Failed to auto-sync: {}".format(e),
+                    file=sys.stderr,
+                )
+            self._synced = True
+            self._buf = bytearray()
+        elif len(self._buf) > 2048:
+            # Prevent unbounded growth — keep tail only
+            self._buf = self._buf[-256:]
+
+        return text
+
+    def tx(self, text):
+        """Called with each chunk of data sent from terminal to device."""
+        return text

README.md

@@ -1,36 +1,380 @@
-## Meshcore + Fork = Meck 
-This fork was created specifically to focus on enabling BLE companion firmware for the LilyGo T-Deck Pro. Created with the assistance of Claude AI using Meshcore v1.11 code. 
+## Meshcore + Fork = Meck
 
-⭐ ***Please note as of 1 Feb 2026, the T-Deck Pro repeater & usb firmware has not been finalised nor confirmed as functioning.*** ⭐
+A fork created specifically to focus on enabling BLE & WiFi companion firmware for the LilyGo T-Deck Pro & LilyGo T5 E-Paper S3 Pro. Created wholly with Claude AI using Meshcore v1.11 code. 100% vibecoded.
 
-## T-Deck Pro Keyboard Controls
+[Check out the Meck discussion channel on the MeshCore Discord](https://discord.com/channels/1343693475589263471/1460136499390447670)
 
-The T-Deck Pro BLE companion firmware includes full keyboard support for standalone messaging without a phone.
+<img src="https://github.com/user-attachments/assets/b30ce6bd-79af-44d3-93c4-f5e7e21e5621" alt="IMG_1453" width="300" height="650">
+
+### Contents
+- [Supported Devices](#supported-devices)
+- [SD Card Requirements](#sd-card-requirements)
+- [Flashing Firmware](#flashing-firmware)
+  - [First-Time Flash (Merged Firmware)](#first-time-flash-merged-firmware)
+  - [Upgrading Firmware](#upgrading-firmware)
+  - [Launcher](#launcher)
+  - [OTA Firmware Update](#ota-firmware-update-v13)
+- [Path Hash Mode (v0.9.9+)](#path-hash-mode-v099)
+- [T-Deck Pro](#t-deck-pro)
+  - [Build Variants](#t-deck-pro-build-variants)
+  - [Keyboard Controls](#t-deck-pro-keyboard-controls)
+  - [Navigation (Home Screen)](#navigation-home-screen)
+  - [Bluetooth (BLE)](#bluetooth-ble)
+  - [WiFi Companion](#wifi-companion)
+  - [Clock & Timezone](#clock--timezone)
+  - [Channel Message Screen](#channel-message-screen)
+  - [Contacts Screen](#contacts-screen)
+  - [Sending a Direct Message](#sending-a-direct-message)
+  - [Roomservers](#roomservers)
+  - [Repeater Admin Screen](#repeater-admin-screen)
+  - [Settings Screen](#settings-screen)
+  - [Compose Mode](#compose-mode)
+  - [Symbol Entry (Sym Key)](#symbol-entry-sym-key)
+  - [Emoji Picker](#emoji-picker)
+  - [SMS & Phone App (4G only)](#sms--phone-app-4g-only)
+  - [Web Browser & IRC](#web-browser--irc)
+  - [Alarm Clock (Audio only)](#alarm-clock-audio-only)
+  - [Lock Screen (T-Deck Pro)](#lock-screen-t-deck-pro)
+- [T5S3 E-Paper Pro](#t5s3-e-paper-pro)
+  - [Build Variants](#t5s3-build-variants)
+  - [Touch Navigation](#touch-navigation)
+  - [Home Screen](#t5s3-home-screen)
+  - [Boot Button Controls](#boot-button-controls)
+  - [Backlight](#backlight)
+  - [Lock Screen](#lock-screen)
+  - [Virtual Keyboard](#virtual-keyboard)
+  - [Display Settings](#display-settings)
+  - [Clock & RTC](#clock--rtc)
+  - [Touch Gestures by Screen](#touch-gestures-by-screen)
+- [Serial Settings (USB)](Serial_Settings_Guide.md)
+- [Text & EPUB Reader](TXT___EPUB_Reader_Guide.md)
+- [Web Browser & IRC Guide](Web_App_Guide.md)
+- [SMS & Phone App Guide](SMS___Phone_App_Guide.md)
+- [About MeshCore](#about-meshcore)
+- [What is MeshCore?](#what-is-meshcore)
+- [Key Features](#key-features)
+- [What Can You Use MeshCore For?](#what-can-you-use-meshcore-for)
+- [How to Get Started](#how-to-get-started)
+- [MeshCore Clients](#meshcore-clients)
+- [Hardware Compatibility](#-hardware-compatibility)
+- [Contributing](#contributing)
+- [Road-Map / To-Do](#road-map--to-do)
+- [Get Support](#-get-support)
+- [License](#-license)
+  - [Third-Party Libraries](#third-party-libraries)
+
+---
+
+## Supported Devices
+
+Meck currently targets two LilyGo devices:
+
+| Device | Display | Input | LoRa | Battery | GPS | RTC |
+|--------|---------|-------|------|---------|-----|-----|
+| **T-Deck Pro** | 240×320 e-ink (GxEPD2) | TCA8418 keyboard + optional touch | SX1262 | BQ27220 fuel gauge, 1400 mAh | Yes | No (uses GPS time) |
+| **T5S3 E-Paper Pro** (V2, H752-B) | 960×540 e-ink (FastEPD, parallel) | GT911 capacitive touch (no keyboard) | SX1262 | BQ27220 fuel gauge, 1500 mAh | No (non-GPS variant) | Yes (PCF8563 hardware RTC) |
+
+Both devices use the ESP32-S3 with 16 MB flash and 8 MB PSRAM.
+
+---
+
+## SD Card Requirements
+
+**An SD card is essential for Meck to function properly.** Many features — including the e-book reader, notes, bookmarks, web reader cache, audiobook playback, firmware updates, contact import/export, and WiFi credential storage — rely on files stored on the SD card. Without an SD card inserted, the device will boot and handle mesh messaging, but most extended features will be unavailable or will fail silently.
+
+**Recommended:** A **32 GB or larger** microSD card formatted as **FAT32**. MeshCore users have found that **SanDisk** microSD cards are the most reliable across both the T-Deck Pro and T5S3.
+
+---
+
+## Flashing Firmware
+
+Download the latest firmware from the [Releases](https://github.com/pelgraine/Meck/releases) page. Each release includes two types of `.bin` files per build variant:
+
+| File Type | When to Use |
+|-----------|-------------|
+| `*-merged.bin` | **First-time flash** — includes bootloader, partition table, and firmware in a single file. Flash at address `0x0`. |
+| `*.bin` (non-merged) | **Upgrading existing firmware** — firmware image only. Also used when loading firmware from an SD card via the Launcher. |
+
+### First-Time Flash (Merged Firmware)
+
+If the device has never had Meck firmware (or you want a clean start), use the **merged** `.bin` file. This contains the bootloader, partition table, and application firmware combined into a single image.
+
+**Using esptool.py:**
+
+```
+esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 \
+  write_flash 0x0 meck_t5s3_standalone-merged.bin
+```
+
+On macOS the port is typically `/dev/cu.usbmodem*`. On Windows it will be a COM port like `COM3`.
+
+**Using the MeshCore Flasher (web-based, T-Deck Pro only):**
+
+1. Go to https://flasher.meshcore.co.uk
+2. Select **Custom Firmware**
+3. Select the **merged** `.bin` file you downloaded
+4. Click **Flash**, select your device in the popup, and click **Connect**
+
+> **Note:** The MeshCore Flasher detects merged firmware by the `-merged.bin` suffix in the filename and automatically flashes at address `0x0`. If the filename doesn't end with `-merged.bin`, the flasher writes at `0x10000` instead, which will fail on a clean device.
+
+### Upgrading Firmware
+
+If the device is already running Meck (or any MeshCore-based firmware with a valid bootloader), use the **non-merged** `.bin` file. This is smaller and faster to flash since it only contains the application firmware.
+
+**Using esptool.py:**
+
+```
+esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 \
+  write_flash 0x10000 meck_t5s3_standalone.bin
+```
+
+> **Tip:** If you're unsure whether the device already has a bootloader, it's always safe to use the merged file and flash at `0x0` — it will overwrite everything cleanly.
+
+### Launcher
+
+If you're loading firmware from an SD card via the LilyGo Launcher firmware, use the **non-merged** `.bin` file. The Launcher provides its own bootloader and only needs the application image.
+
+### OTA Firmware Update (v1.3+)
+
+Once Meck is installed, you can update firmware directly from your phone — no computer or serial cable required. The device creates a temporary WiFi access point and you upload the new `.bin` via your phone's browser.
+
+1. Download the new **non-merged** `.bin` to your phone (from GitHub Releases, Discord, etc.)
+2. On the device: **Settings → OTA Tools → Firmware Update → Enter** (T-Deck Pro) or **tap** (T5S3)
+3. The device starts a WiFi network called `Meck-Update-XXXX` and displays connection details
+4. On your phone: connect to the `Meck-Update` WiFi network, open a browser, go to `192.168.4.1`
+5. Tap **Choose File**, select the `.bin`, tap **Upload**
+6. The device receives the file, saves to SD, verifies, flashes, and reboots
+
+The partition layout supports dual OTA slots — the old firmware remains on the inactive partition as an automatic rollback target. If the new firmware fails to boot, the ESP32 bootloader reverts to the previous working version automatically.
+
+> **Note:** Use the **non-merged** `.bin` for OTA updates. The merged binary is only needed for first-time USB flashing.
+
+**OTA Tools (v1.5+):** The firmware update has moved into **Settings → OTA Tools**, a submenu that also contains the new **SD File Manager**. The file manager creates the same WiFi access point and serves a browser-based interface where you can browse, upload, download, and delete files on the SD card from your phone — useful for managing audiobooks, alarm sounds, e-books, and notes without ejecting the SD card. Both OTA tools work on all variants including standalone builds.
+
+---
+
+## Path Hash Mode (v0.9.9+)
+
+Meck supports multibyte path hash, bringing it in line with MeshCore firmware v1.14. The path hash controls how many bytes each repeater uses to identify itself in forwarded flood packets. Larger hashes reduce the chance of identity collisions at the cost of fewer maximum hops per packet.
+
+You can configure the path hash size in the device settings (press **S** from the home screen on T-Deck Pro, or open Settings via the tile on T5S3) or set it via USB serial:
+
+```
+set path.hash.mode 1
+```
+
+| Mode | Bytes per hop | Max hops | Notes |
+|------|--------------|----------|-------|
+| 0 | 1 | 64 | Legacy — prone to hash collisions in larger networks |
+| 1 | 2 | 32 | Recommended — effectively eliminates collisions |
+| 2 | 3 | 21 | Maximum precision, rarely needed |
+
+Nodes with different path hash modes can coexist on the same network. The mode only affects packets your node originates — the hash size is encoded in each packet's header, so receiving nodes adapt automatically.
+
+For a detailed explanation of what multibyte path hash means and why it matters, see the [Path Diagnostics & Improvements write-up](https://buymeacoffee.com/ripplebiz/path-diagnostics-improvements).
+
+---
+
+## T-Deck Pro
+
+### T-Deck Pro Build Variants
+
+| Variant | Environment | BLE | WiFi | 4G Modem | Audio DAC | Web Reader | Max Contacts |
+|---------|------------|-----|------|----------|-----------|------------|-------------|
+| Audio + BLE | `meck_audio_ble` | Yes | Yes (via BLE stack) | — | PCM5102A | Yes | 500 |
+| Audio + WiFi | `meck_audio_wifi` | — | Yes (TCP:5000) | — | PCM5102A | Yes | 1,500 |
+| Audio + Standalone | `meck_audio_standalone` | — | — | — | PCM5102A | No | 1,500 |
+| 4G + BLE | `meck_4g_ble` | Yes | Yes | A7682E | — | Yes | 500 |
+| 4G + WiFi | `meck_4g_wifi` | — | Yes (TCP:5000) | A7682E | — | Yes | 1,500 |
+| 4G + Standalone | `meck_4g_standalone` | — | Yes | A7682E | — | Yes | 1,500 |
+
+The audio DAC and 4G modem occupy the same hardware slot and are mutually exclusive.
+
+### T-Deck Pro Keyboard Controls
+
+The T-Deck Pro firmware includes full keyboard support for standalone messaging without a phone.
 
 ### Navigation (Home Screen)
 
 | Key | Action |
 |-----|--------|
 | W / A | Previous page |
-| S / D | Next page |
+| D | Next page |
 | Enter | Select / Confirm |
 | M | Open channel messages |
+| C | Open contacts list |
+| E | Open e-book reader |
+| N | Open notes |
+| S | Open settings |
+| B | Open web browser (BLE and 4G variants only) |
+| T | Open SMS & Phone app (4G variant only) |
+| P | Open audiobook player (audio variant only) |
+| K | Open alarm clock (audio variant only) |
+| F | Open node discovery (search for nearby repeaters/nodes) |
+| H | Open last heard list (passive advert history) |
+| G | Open map screen (shows contacts with GPS positions) |
 | Q | Back to home screen |
+| Double-click Boot | Lock / unlock screen |
+
+### Bluetooth (BLE)
+
+BLE is **disabled by default** at boot to support standalone-first operation. The device is fully functional without a phone — you can send and receive messages, browse contacts, read e-books, and set your timezone directly from the keyboard.
+
+To connect to the MeshCore companion app, navigate to the **Bluetooth** home page (use D to page through) and press **Enter** to toggle BLE on. The BLE PIN will be displayed on screen. Toggle it off again the same way when you're done.
+
+### WiFi Companion
+
+The WiFi companion variants (`meck_audio_wifi`, `meck_4g_wifi`) connect to the MeshCore web app, meshcore.js, or Python CLI over your local network via TCP on port 5000. WiFi credentials are stored on the SD card at `/web/wifi.cfg`.
+
+**Connecting:**
+
+1. Navigate to the **WiFi** home page (use D to page through)
+2. Press **Enter** to toggle WiFi on
+3. The device scans for networks — select yours and enter the password
+4. Once connected, the IP address is displayed on the WiFi home page
+
+Connect the MeshCore web app or meshcore.js to `<device IP>:5000`.
+
+WiFi is also used by the web reader and IRC client on WiFi variants. The web reader shares the same connection — no extra setup needed.
+
+> **Tip:** WiFi variants support up to 1,500 contacts (vs 500 for BLE variants) because they are not constrained by the BLE protocol ceiling.
+
+### Clock & Timezone
+
+The T-Deck Pro does not include a dedicated RTC chip, so after each reboot the device clock starts unset. The clock will appear in the nav bar (between node name and battery) once the time has been synced by one of these methods:
+
+1. **GPS fix** (standalone) — Once the GPS acquires a satellite fix, the time is automatically synced from the NMEA data. No phone or BLE connection required. Typical time to first fix is 30–90 seconds outdoors with clear sky.
+2. **BLE/WiFi companion app** — If connected to the MeshCore companion app (via BLE or WiFi), the app will push the current time to the device.
+
+**Setting your timezone:**
+
+The UTC offset can be set from the **Settings** screen (press **S** from the home screen), or from the **GPS** home page by pressing **U** to open the UTC offset editor.
+
+| Key | Action |
+|-----|--------|
+| W | Increase offset (+1 hour) |
+| S | Decrease offset (-1 hour) |
+| Enter | Save and exit |
+| Q | Cancel and exit |
+
+The UTC offset is persisted to flash and survives reboots — you only need to set it once. The valid range is UTC-12 to UTC+14. For example, AEST is UTC+10 and AEDT is UTC+11.
+
+The GPS page also shows the current time, satellite count, position, altitude, and your configured UTC offset for reference.
 
 ### Channel Message Screen
 
 | Key | Action |
 |-----|--------|
 | W / S | Scroll messages up/down |
-| A / D | Switch between channels |
-| C | Compose new message |
+| A / D | Switch between channels (press D past the last channel to reach the DM inbox, A to return) |
+| Enter | Compose new message |
+| R | Reply to a message — enter reply select mode, scroll to a message with W/S, then press Enter to compose a reply with an @mention |
+| V | View relay path of the last received message (scrollable, up to 20 hops) |
 | Q | Back to home screen |
 
+### Contacts Screen
+
+Press **C** from the home screen to open the contacts list. All known mesh contacts are shown sorted by most recently seen, with their type (Chat, Repeater, Room, Sensor), hop count, and time since last advert.
+
+| Key | Action |
+|-----|--------|
+| W / S | Scroll up / down through contacts |
+| A / D | Cycle filter: All → Chat → Repeater → Room → Sensor → Favourites |
+| Enter | Open DM compose (Chat contact) or repeater admin (Repeater contact) |
+| X | Export contacts to SD card (wait 5–10 seconds for confirmation popup) |
+| R | Import contacts from SD card (wait 5–10 seconds for confirmation popup) |
+| Q | Back to home screen |
+
+**Contact limits:** Standalone and WiFi variants support up to 1,500 contacts (stored in PSRAM). BLE variants (Audio-BLE and 4G-BLE) are limited to 500 contacts due to BLE protocol constraints.
+
+### Sending a Direct Message
+
+Select a **Chat** contact in the contacts list and press **Enter** to start composing a direct message. The compose screen will show `DM: ContactName` in the header. Type your message and press **Enter** to send. The DM is sent encrypted directly to that contact (or flooded if no direct path is known). After sending or cancelling, you're returned to the contacts list.
+
+Contacts with unread direct messages show a `*` marker next to their name in the contacts list.
+
+**Reading received DMs:** On the Channel Messages screen, press **D** past the last group channel to reach the **DM inbox**. This shows all received direct messages with sender name and timestamp. Entering the DM inbox marks all DM messages as read and clears the unread indicator. Press **A** to return to group channels.
+
+### Roomservers
+
+Room servers are MeshCore nodes that host persistent chat rooms. Messages sent to a room server are stored and relayed to anyone who logs in. In Meck, room server messages arrive as contact messages and appear in the DM inbox alongside regular direct messages.
+
+To interact with a room server, navigate to the Contacts screen, filter to **Room** contacts, select the room, and press **Enter** to open the Repeater Admin screen. Log in with the room's admin password to access room administration. On successful login, all unread messages from that room are automatically marked as read.
+
+Room server messages are also synced to the companion app when connected via BLE or WiFi — the companion app will pull and display them alongside other messages.
+
+### Repeater Admin Screen
+
+Select a **Repeater** contact in the contacts list and press **Enter** to open the repeater admin screen. You'll be prompted for the repeater's admin password. Characters briefly appear as you type them before being masked, making it easier to enter symbols and numbers on the T-Deck Pro keyboard.
+
+After a successful login, you'll see a menu with the following remote administration commands:
+
+| Menu Item | Description |
+|-----------|-------------|
+| Clock Sync | Push your device's clock time to the repeater |
+| Send Advert | Trigger the repeater to broadcast an advertisement |
+| Neighbors | View other repeaters heard via zero-hop adverts |
+| Get Clock | Read the repeater's current clock value |
+| Version | Query the repeater's firmware version |
+| Get Status | Retrieve repeater status information |
+
+| Key | Action |
+|-----|--------|
+| W / S | Navigate menu items |
+| Enter | Execute selected command |
+| Q | Back to contacts (from menu) or cancel login |
+
+Command responses are displayed in a scrollable view. Use **W / S** to scroll long responses and **Q** to return to the menu.
+
+### Settings Screen
+
+Press **S** from the home screen to open settings. On first boot (when the device name is still the default hex ID), the settings screen launches automatically as an onboarding wizard to set your device name and radio preset.
+
+| Key | Action |
+|-----|--------|
+| W / S | Navigate up / down through settings |
+| Enter | Edit selected setting, or enter a sub-screen |
+| Q | Back one level (sub-screen → top level → home screen) |
+
+**Available settings:**
+
+| Setting | Edit Method |
+|---------|-------------|
+| Device Name | Text entry — type a name, Enter to confirm |
+| Radio Preset | A / D to cycle presets (MeshCore Default, Long Range, Fast/Short, EU Default), Enter to apply |
+| Frequency | Text entry — type exact value (e.g. 916.575), Enter to confirm |
+| Bandwidth | W / S to cycle standard values (31.25 / 62.5 / 125 / 250 / 500 kHz), Enter to confirm |
+| Spreading Factor | W / S to adjust (5–12), Enter to confirm |
+| Coding Rate | W / S to adjust (5–8), Enter to confirm |
+| TX Power | W / S to adjust (1–20 dBm), Enter to confirm |
+| UTC Offset | W / S to adjust (-12 to +14), Enter to confirm |
+| Msg Rcvd LED Pulse | Toggle keyboard backlight flash on new message (Enter to toggle) |
+| GPS Baud Rate | A / D to cycle (Default 38400 / 4800 / 9600 / 19200 / 38400 / 57600 / 115200), Enter to confirm. **Requires reboot to take effect.** |
+| Path Hash Mode | W / S to cycle (1-byte / 2-byte / 3-byte), Enter to confirm |
+| Dark Mode | Toggle inverted display — white text on black background (Enter to toggle) |
+| Larger Font | Toggle larger text size on channel messages, contacts, DM inbox, and repeater admin screens (Enter to toggle) |
+| Auto Lock | A / D to cycle timeout (None / 2 / 5 / 10 / 15 / 30 min), Enter to confirm |
+| Contacts >> | Opens the Contacts sub-screen (see below) |
+| Channels >> | Opens the Channels sub-screen (see below) |
+| Device Info | Public key and firmware version (read-only) |
+
+**Contacts sub-screen** — press Enter on the `Contacts >>` row to open. Contains the contact auto-add mode picker (Auto All / Custom / Manual) and, when set to Custom, per-type toggles for Chat, Repeater, Room Server, Sensor, and an Overwrite Oldest option. Press Q to return to the top-level settings list.
+
+**Channels sub-screen** — press Enter on the `Channels >>` row to open. Lists all current channels, with an option to add hashtag channels or delete non-primary channels (X). Press Q to return to the top-level settings list.
+
+The top-level settings screen also displays your node ID and firmware version. On the 4G variant, IMEI, carrier name, and APN details are shown here as well.
+
+When adding a hashtag channel, type the channel name and press Enter. The channel secret is automatically derived from the name via SHA-256, matching the standard MeshCore hashtag convention.
+
+If you've changed radio parameters, pressing Q will prompt you to apply changes before exiting.
+
+> **Tip:** All device settings (plus mesh tuning parameters not available on-screen) can also be configured via USB serial. See the [Serial Settings Guide](Serial_Settings_Guide.md) for complete documentation.
+
 ### Compose Mode
 
 | Key | Action |
 |-----|--------|
-| A / D | Switch destination channel (when message is empty) |
+| A / D | Switch destination channel (when message is empty, channel compose only) |
 | Enter | Send message |
 | Backspace | Delete last character |
 | Shift + Backspace | Cancel and exit compose mode |
@@ -49,7 +393,7 @@ Press the **Sym** key then the letter key to enter numbers and symbols:
 | Y | ) | | H | : | | N | , |
 | U | _ | | J | ; | | M | . |
 | I | - | | K | ' | | Mic | 0 |
-| O | + | | L | " | | $ | (dedicated) |
+| O | + | | L | " | | $ | Emoji picker (Sym+$ for literal $) |
 | P | @ | | | | | | |
 
 ### Other Keys
@@ -60,14 +404,327 @@ Press the **Sym** key then the letter key to enter numbers and symbols:
 | Alt | Same as Sym (for numbers/symbols) |
 | Space | Space character / Next in navigation |
 
+### Emoji Picker
+
+While in compose mode, press the **$** key to open the emoji picker. A scrollable grid of 47 emoji is displayed in a 5-column layout.
+
+| Key | Action |
+|-----|--------|
+| W / S | Navigate up / down |
+| A / D | Navigate left / right |
+| Enter | Insert selected emoji |
+| $ / Q / Backspace | Cancel and return to compose |
+
+### SMS & Phone App (4G only)
+
+Press **T** from the home screen to open the SMS & Phone app. The app opens to a menu screen where you can choose between the **Phone** dialer (for calling any number) or the **SMS Inbox** (for messaging and calling saved contacts).
+
+For full documentation including key mappings, dialpad usage, contacts management, and troubleshooting, see the [SMS & Phone App Guide](SMS___Phone_App_Guide.md).
+
+### Web Browser & IRC
+
+Press **B** from the home screen to open the web reader. This is available on the BLE, WiFi, and 4G variants (not the standalone audio variant, which excludes WiFi to preserve lowest-battery-usage design).
+
+The web reader home screen provides access to the **IRC client**, the **URL bar**, and your **bookmarks** and **history**. Select IRC Chat and press Enter to configure and connect to an IRC server. Select the URL bar to enter a web address, or scroll down to open a bookmark or history entry.
+
+The browser is a text-centric reader best suited to text-heavy websites. It also includes basic web search via DuckDuckGo Lite, and can download EPUB files — follow a link to an `.epub` and it will be saved to the books folder on your SD card for reading later in the e-book reader.
+
+For full documentation including key mappings, WiFi setup, bookmarks, IRC configuration, and SD card structure, see the [Web App Guide](Web_App_Guide.md).
+
+### Alarm Clock (Audio only)
+
+Press **K** from the home screen to open the alarm clock. This is available on the audio variant of the T-Deck Pro (PCM5102A DAC). Set up to five daily alarms that play custom MP3 files through the headphone jack.
+
+**Setup:**
+
+1. Place MP3 files (44100 Hz sample rate) in `/alarms/` on the SD card
+2. Press **K** to open the alarm clock
+3. Select an alarm slot (1–5) with **W / S** and press **Enter** to edit
+4. Set the hour and minute, then choose an MP3 file from the list
+5. Press **Enter** to save the alarm
+
+| Key | Action |
+|-----|--------|
+| W / S | Navigate alarm slots / adjust time |
+| A / D | Switch between hour and minute fields |
+| Enter | Edit slot / save alarm / select MP3 |
+| X | Delete selected alarm |
+| Q | Back to home screen |
+
+**When an alarm fires:**
+
+The selected MP3 plays through the headphone jack, even if you're on another screen or playing an audiobook.
+
+| Key | Action |
+|-----|--------|
+| Z | Snooze for 5 minutes |
+| Any other key | Dismiss alarm |
+
+Alarm configuration is stored in `/alarms/.alarmcfg` on the SD card. Alarms persist across reboots — if the RTC has valid time (via GPS or companion app sync), alarms fire at the correct time after a restart.
+
+> **Note:** MP3 files should be encoded at **44100 Hz** sample rate. Lower sample rates may cause distortion due to ESP32-S3 I2S hardware limitations (same requirement as the audiobook player).
+
+**SD Card Folder Structure:**
+
+```
+SD Card
+├── alarms/
+│   ├── .alarmcfg             (auto-created, stores alarm slot config)
+│   ├── morning-chime.mp3
+│   ├── rooster.mp3
+│   └── gentle-bells.mp3
+├── audiobooks/               (existing — audiobook player)
+│   └── ...
+├── books/                    (existing — text reader)
+│   └── ...
+└── ...
+```
+
+### Lock Screen (T-Deck Pro)
+
+Double-click the Boot button to lock the screen. The lock screen shows the current time, battery percentage, and unread message count. The CPU drops to 40 MHz while locked to reduce power consumption.
+
+Double-click the Boot button again to unlock and return to whatever screen you were on.
+
+An auto-lock timer can be configured in **Settings → Auto Lock** (None / 2 / 5 / 10 / 15 / 30 minutes of idle time).
+
+---
+
+## T5S3 E-Paper Pro
+
+The LilyGo T5S3 E-Paper Pro (V2, H752-B) is a 4.7-inch e-ink device with capacitive touch and no physical keyboard. All navigation is done via touch gestures and the Boot button (GPIO0). The larger 960×540 display provides significantly more screen real estate than the T-Deck Pro's 240×320 panel.
+
+### T5S3 Build Variants
+
+| Variant | Environment | BLE | WiFi | Web Reader | Max Contacts |
+|---------|------------|-----|------|------------|-------------|
+| Standalone | `meck_t5s3_standalone` | — | — | No | 1,500 |
+| BLE Companion | `meck_t5s3_ble` | Yes | — | No | 500 |
+| WiFi Companion | `meck_t5s3_wifi` | — | Yes (TCP:5000) | Yes | 1,500 |
+
+The WiFi variant connects to the MeshCore web app or meshcore.js over your local network. The web reader shares the same WiFi connection — no extra setup needed.
+
+### Touch Navigation
+
+The T5S3 uses a combination of touch gestures and the Boot button for all interaction. There is no physical keyboard — text entry uses an on-screen virtual keyboard that appears when needed.
+
+**Core gesture types:**
+
+| Gesture | Description |
+|---------|-------------|
+| **Tap** | Touch and release quickly. Context-dependent: opens tiles on home screen, selects items in lists, advances pages in readers. |
+| **Swipe** | Touch, drag at least 60 pixels, and release. Direction determines action (scroll, page turn, switch channel/filter). |
+| **Long press (touch)** | Touch and hold for 500ms+. Context-dependent: compose messages, open DMs, delete bookmarks. |
+
+### T5S3 Home Screen
+
+The home screen displays a 3×2 grid of tappable tiles:
+
+| | Column 1 | Column 2 | Column 3 |
+|---|----------|----------|----------|
+| **Row 1** | Messages | Contacts | Settings |
+| **Row 2** | Reader | Notes | Browser (WiFi) / Discover (other) |
+
+Tap a tile to open that screen. Tap outside the tile grid (or swipe left/right) to cycle between home pages. The additional home pages show BLE status, battery info, GPS status, and a hibernate option — same as the T-Deck Pro but navigated by swiping or tapping the left/right halves of the screen instead of pressing keys.
+
+### Boot Button Controls
+
+The Boot button (GPIO0, bottom of device) provides essential navigation and utility functions:
+
+| Action | Effect |
+|--------|--------|
+| **Single click** | On home screen: cycle to next page. On other screens: go back (same as pressing Q on T-Deck Pro). In text reader reading mode: close book and return to file list. |
+| **Double-click** | Toggle backlight at full brightness (comfortable for indoor reading). |
+| **Triple-click** | Toggle backlight at low brightness (dim nighttime reading). |
+| **Long press** | Lock or unlock the screen. While locked, touch is disabled and a lock screen shows the time, battery percentage, and unread message count. |
+| **Long press during first 8 seconds after boot** | Enter CLI rescue mode (serial settings interface). |
+
+### Backlight
+
+The T5S3 has a warm-tone front-light controlled by PWM on GPIO11. Brightness ranges from 0 (off) to 255 (maximum).
+
+- **Double-click Boot button** — toggle backlight on at 153/255 brightness (comfortable reading level)
+- **Triple-click Boot button** — toggle backlight on at low brightness (4/255, nighttime reading)
+- The backlight turns off automatically when the screen locks
+
+### Lock Screen
+
+Long press the Boot button to lock the device. The lock screen shows:
+- Current time in large text (HH:MM)
+- Battery percentage
+- Unread message count (if any)
+- "Hold button to unlock" hint
+
+Touch input is completely disabled while locked. Long press the Boot button again to unlock and return to whatever screen you were on.
+
+An auto-lock timer can be configured in **Settings → Auto Lock** (None / 2 / 5 / 10 / 15 / 30 minutes of idle time). The CPU drops to 40 MHz while locked to reduce power consumption.
+
+### Virtual Keyboard
+
+Since the T5S3 has no physical keyboard, a full-screen QWERTY virtual keyboard appears automatically when text input is needed (composing messages, entering WiFi passwords, editing settings, etc.).
+
+The virtual keyboard supports:
+- QWERTY letter layout with a symbol/number layer (tap the **123** key to switch)
+- Shift toggle for uppercase
+- Backspace and Enter keys
+- Phantom keystroke prevention (a brief cooldown after the keyboard opens prevents accidental taps)
+
+Tap keys to type. Tap **Enter** to submit, or press the **Boot button** to cancel and close the keyboard.
+
+### External Keyboard (CardKB)
+
+The T5S3 supports the M5Stack CardKB (or compatible I2C keyboard) connected via the QWIIC port. When detected at boot, the CardKB can be used for all text input — composing messages, entering URLs, editing notes, and navigating menus — without the on-screen virtual keyboard.
+
+The CardKB is auto-detected on the I2C bus at address `0x5F`. No configuration is needed — just plug it in.
+
+### Display Settings
+
+The T5S3 Settings screen includes one additional display option not available on the T-Deck Pro:
+
+| Setting | Description |
+|---------|-------------|
+| **Dark Mode** | Inverts the display — white text on black background. Tap to toggle on/off. Available on both T-Deck Pro and T5S3. |
+| **Larger Font** | Increases text size on channel messages, contacts, DM inbox, and repeater admin screens. Tap to toggle on/off. Available on both T-Deck Pro and T5S3. |
+| **Portrait Mode** | Rotates the display 90° from landscape (960×540) to portrait (540×960). Touch coordinates are automatically remapped. Text reader layout recalculates on orientation change. T5S3 only. |
+
+These settings are persisted and survive reboots.
+
+### Clock & RTC
+
+Unlike the T-Deck Pro (which relies on GPS for time), the T5S3 has a hardware RTC (PCF8563/BM8563) that maintains time across reboots as long as the battery has charge. On first use (or after a full battery drain), the clock needs to be set via USB serial:
+
+```
+clock sync 1773554535
+```
+
+Where the number is a Unix epoch timestamp. Quick one-liner from a macOS/Linux terminal:
+
+```
+echo "clock sync $(date +%s)" > /dev/ttyACM0
+```
+
+Once set, the RTC retains the time across reboots. See the [Serial Settings Guide](Serial_Settings_Guide.md) for full clock sync documentation including the PlatformIO auto-sync feature.
+
+The UTC offset is configured in the Settings screen (same as T-Deck Pro) and is persisted to flash.
+
+### Touch Gestures by Screen
+
+#### Home Screen
+
+| Gesture | Action |
+|---------|--------|
+| Tap tile | Open that screen (Messages, Contacts, Settings, Reader, Notes, Browser/Discover) |
+| Tap outside tiles (left half) | Previous home page |
+| Tap outside tiles (right half) | Next home page |
+| Swipe left / right | Next / previous home page |
+| Long press (touch) | Activate current page action (toggle BLE, hibernate, etc.) |
+
+#### Channel Messages
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll messages |
+| Swipe left / right | Switch between channels (swipe left past the last channel to reach the DM inbox) |
+| Tap footer area | View relay path of last received message |
+| Tap path overlay | Dismiss overlay |
+| Long press (touch) | Open virtual keyboard to compose message to current channel |
+
+#### Contacts
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll through contacts |
+| Swipe left / right | Cycle contact filter (All → Chat → Repeater → Room → Sensor → Favourites) |
+| Tap | Select contact |
+| Long press on Chat contact | View unread DMs (if any), then compose DM |
+| Long press on Repeater contact | Open repeater admin login |
+
+#### Text Reader (File List)
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll file list |
+| Tap | Open selected book |
+
+#### Text Reader (Reading)
+
+| Gesture | Action |
+|---------|--------|
+| Tap anywhere | Next page |
+| Tap footer bar | Go to page number (via virtual keyboard) |
+| Swipe left | Next page |
+| Swipe right | Previous page |
+| Swipe up / down | Next / previous page |
+| Long press (touch) | Close book, return to file list |
+| Tap status bar | Go to home screen |
+
+#### Web Reader (WiFi variant)
+
+| Gesture | Action |
+|---------|--------|
+| Tap URL bar | Open virtual keyboard for URL entry |
+| Tap Search | Open virtual keyboard for DuckDuckGo search |
+| Tap reading area | Next page |
+| Tap footer (if links exist) | Open virtual keyboard to enter link number |
+| Swipe left / right (reading) | Next / previous page |
+| Swipe up / down (home/lists) | Scroll list |
+| Long press (reading) | Navigate back |
+| Long press on bookmark | Delete bookmark |
+| Long press on home | Exit web reader |
+
+#### Settings
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll through settings |
+| Swipe left / right | Adjust value (same as A/D keys on T-Deck Pro) |
+| Tap | Toggle or edit selected setting |
+
+#### Notes
+
+| Gesture | Action |
+|---------|--------|
+| Tap (while editing) | Open virtual keyboard for text entry |
+| Long press (while editing) | Save note and exit editor |
+
+#### Discovery
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll node list |
+| Tap | Add selected node to contacts |
+| Long press | Rescan for nodes |
+
+#### Last Heard
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll advert list |
+| Tap | Add to or delete from contacts |
+
+#### Repeater Admin
+
+| Gesture | Action |
+|---------|--------|
+| Swipe up / down | Scroll menu / response |
+| Long press (password entry) | Open virtual keyboard for admin password |
+
+#### All Screens
+
+| Gesture | Action |
+|---------|--------|
+| Tap status bar (top of screen) | Return to home screen (except in text reader reading mode, where it advances the page) |
+
+---
+
 ## About MeshCore
 
 MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.
 
 ## What is MeshCore?
 
-MeshCore now supports a range of LoRa devices, allowing for easy flashing without the need to compile firmware manually. Users can flash a pre-built binary using tools like Adafruit ESPTool and interact with the network through a serial console.
-MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions., where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.
+MeshCore now supports a range of LoRa devices, allowing for easy flashing without the need to compile firmware manually. Users can flash a pre-built binary using tools like esptool.py and interact with the network through a serial console.
+MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions, where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.
 
 ## Key Features
 
@@ -92,31 +749,22 @@ MeshCore provides the ability to create wireless mesh networks, similar to Mesht
 
 - Watch the [MeshCore Intro Video](https://www.youtube.com/watch?v=t1qne8uJBAc) by Andy Kirby.
 - Read through our [Frequently Asked Questions](./docs/faq.md) section.
-- Flash the MeshCore firmware on a supported device.
+- Download firmware from the [Releases](https://github.com/pelgraine/Meck/releases) page and flash it using the instructions above.
 - Connect with a supported client.
 
-For developers;
+For developers:
 
 - Install [PlatformIO](https://docs.platformio.org) in [Visual Studio Code](https://code.visualstudio.com).
-- Clone and open the MeshCore repository in Visual Studio Code.
-- See the example applications you can modify and run:
-  - [Companion Radio](./examples/companion_radio) - For use with an external chat app, over BLE, USB or WiFi.
-
-## MeshCore Flasher
-
-Download a copy of the Meck firmware bin from https://github.com/pelgraine/Meck/releases, then:
-
-- Launch https://flasher.meshcore.co.uk
-- Select Custom Firmware
-- Select the .bin file you just downloaded, and click Open or press Enter.
-- Click Flash, then select your device in the popup window (eg. USB JTAG/serial debug unit cu.usbmodem101 as an example), then click Connect.
-- Once flashing is complete, you can connect with one of the MeshCore clients below.
+- Clone and open the Meck repository in Visual Studio Code.
+- Build for your target device using the environment names listed in the build variant tables above.
 
 ## MeshCore Clients
 
 **Companion Firmware**
 
-The companion firmware can be connected to via BLE. USB is planned for a future update.
+The companion firmware can be connected to via BLE (T-Deck Pro and T5S3 BLE variants) or WiFi (T-Deck Pro WiFi variants and T5S3 WiFi variant, TCP port 5000).
+
+> **Note:** On both the T-Deck Pro and T5S3, BLE and WiFi are disabled by default at boot. On the T-Deck Pro, navigate to the Bluetooth or WiFi home page and press Enter to enable. On the T5S3, navigate to the Bluetooth home page and long-press the screen to toggle BLE on.
 
 - Web: https://app.meshcore.nz
 - Android: https://play.google.com/store/apps/details?id=com.liamcottle.meshcore.android
@@ -126,11 +774,7 @@ The companion firmware can be connected to via BLE. USB is planned for a future
 
 ## 🛠 Hardware Compatibility
 
-MeshCore is designed for devices listed in the [MeshCore Flasher](https://flasher.meshcore.co.uk)
-
-## 📜 License
-
-MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.
+MeshCore is designed for devices listed in the [MeshCore Flasher](https://flasher.meshcore.co.uk). Meck specifically targets the LilyGo T-Deck Pro and LilyGo T5S3 E-Paper Pro.
 
 ## Contributing
 
@@ -145,15 +789,81 @@ Here are some general principals you should try to adhere to:
 ## Road-Map / To-Do
 
 There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In partly chronological order:
+
+**T-Deck Pro:**
 - [X] Companion radio: BLE
 - [X] Text entry for Public channel messages Companion BLE firmware
 - [X] View and compose all channel messages Companion BLE firmware
-- [ ] Standalone DM functionality for Companion BLE firmware
-- [ ] Companion radio: USB
-- [ ] Simple Repeater firmware for the T-Deck Pro
-- [ ] Get pin 45 with the screen backlight functioning for the T-Deck Pro v1.1
-- [ ] Canned messages function for Companion BLE firmware
+- [X] Standalone DM functionality for Companion BLE firmware
+- [X] Contacts list with filtering for Companion BLE firmware
+- [X] Standalone repeater admin access for Companion BLE firmware
+- [X] GPS time sync with on-device timezone setting
+- [X] Settings screen with radio presets, channel management, and first-boot onboarding
+- [X] Expand SMS app to enable phone calls
+- [X] Basic web reader app with IRC client
+- [X] Lock screen with auto-lock timer and low-power standby
+- [X] Last heard passive advert list
+- [X] Touch-to-select on contacts, discovery, settings, text reader, notes screens
+- [X] Map screen with GPS tile rendering
+- [X] WiFi companion environment
+- [X] OTA firmware update via phone
+- [X] DM inbox with per-contact unread indicators
+- [X] Roomserver message handling and mark-read on login
+- [X] Alarm clock with custom MP3 sounds (audio variant)
+- [X] Customised user option for larger-font mode
+- [ ] Fix M4B rendering to enable chaptered audiobook playback
+- [ ] Better JPEG and PNG decoding
+- [ ] Improve EPUB rendering and EPUB format handling
+- [ ] Figure out a way to silence the ringtone
+- [ ] Figure out a way to customise the ringtone
+
+**T5S3 E-Paper Pro:**
+- [X] Core port: display, touch input, LoRa, battery, RTC
+- [X] Touch-navigable home screen with tappable tile grid
+- [X] Full virtual keyboard for text entry
+- [X] Lock screen with clock, battery, unread count, and auto-lock timer
+- [X] Backlight control (double/triple-click Boot button)
+- [X] Dark mode and portrait mode display settings
+- [X] Channel messages with swipe navigation and touch compose
+- [X] Contacts with filter cycling and long-press DM/admin
+- [X] Text reader with swipe page turns
+- [X] Web reader with virtual keyboard URL/search entry (WiFi variant)
+- [X] Settings screen with touch editing
+- [X] Serial clock sync for hardware RTC
+- [X] CardKB external keyboard support (via QWIIC)
+- [X] Last heard passive advert list
+- [X] Tap-to-select on contacts, discovery, settings, text reader, notes screens
+- [X] OTA firmware update via phone (WiFi variant)
+- [X] DM inbox with per-contact unread indicators
+- [X] Roomserver message handling and mark-read on login
+- [X] Customised user option for larger-font mode
+- [ ] Improve EPUB rendering and EPUB format handling
 
 ## 📞 Get Support
 
-- Join [MeshCore Discord](https://discord.gg/BMwCtwHj5V) to chat with the developers and get help from the community.
+- Join [MeshCore Discord](https://discord.gg/BMwCtwHj5V) to chat with the developers and get help from the community.
+
+## 📜 License
+
+The upstream [MeshCore](https://github.com/meshcore-dev/MeshCore) library is released under the **MIT License** (Copyright © 2025 Scott Powell / rippleradios.com). Meck-specific code (UI screens, display helpers, device integration) is also provided under the MIT License.
+
+However, this firmware links against libraries with different license terms. Because two dependencies use the **GPL-3.0** copyleft license, the combined firmware binary is effectively subject to GPL-3.0 obligations when distributed. Please review the individual licenses below if you intend to redistribute or modify this firmware.
+
+### Third-Party Libraries
+
+| Library | License | Author / Source |
+|---------|---------|-----------------|
+| [MeshCore](https://github.com/meshcore-dev/MeshCore) | MIT | Scott Powell / rippleradios.com |
+| [GxEPD2](https://github.com/ZinggJM/GxEPD2) | GPL-3.0 | Jean-Marc Zingg |
+| [FastEPD](https://github.com/bitbank2/FastEPD) | Apache-2.0 | Larry Bank (bitbank2) |
+| [ESP32-audioI2S](https://github.com/schreibfaul1/ESP32-audioI2S) | GPL-3.0 | schreibfaul1 (Wolle) |
+| [Adafruit GFX Library](https://github.com/adafruit/Adafruit-GFX-Library) | BSD | Adafruit |
+| [RadioLib](https://github.com/jgromes/RadioLib) | MIT | Jan Gromeš |
+| [SensorLib](https://github.com/lewisxhe/SensorLib) | MIT | Lewis He |
+| [JPEGDEC](https://github.com/bitbank2/JPEGDEC) | Apache-2.0 | Larry Bank (bitbank2) |
+| [PNGdec](https://github.com/bitbank2/PNGdec) | Apache-2.0 | Larry Bank (bitbank2) |
+| [CRC32](https://github.com/bakercp/CRC32) | MIT | Christopher Baker |
+| [base64](https://github.com/Densaugeo/base64_arduino) | MIT | densaugeo |
+| [Arduino Crypto](https://github.com/rweather/arduinolibs) | MIT | Rhys Weatherley |
+
+Full license texts for each dependency are available in their respective repositories linked above.

SMS & Phone App Guide.md

@@ -0,0 +1,206 @@
+## SMS & Phone App (4G variant only) - Meck v0.9.5
+
+Press **T** from the home screen to open the SMS & Phone app.
+Requires a nano SIM card inserted in the T-Deck Pro V1.1 4G modem slot and an
+SD card formatted as FAT32. The modem registers on the cellular network
+automatically at boot — the red LED on the board indicates the modem is
+powered. The modem (and its red LED) can be switched off and on from the
+settings screen. After each modem startup, the system clock syncs from the
+cellular network, which takes roughly 15 seconds.
+
+### App Menu
+
+The SMS & Phone app opens to a landing screen with two options:
+
+| Option | Description |
+|--------|-------------|
+| **Phone** | Open the phone dialer to call any number |
+| **SMS Inbox** | Open the SMS inbox for messaging and calling saved contacts |
+
+Use **W / S** to select an option and **Enter** to confirm. Press **Q** to
+return to the home screen.
+
+### Key Mapping
+
+| Context | Key | Action |
+|---------|-----|--------|
+| Home screen | T | Open SMS & Phone app |
+| App menu | W / S | Select Phone or SMS Inbox |
+| App menu | Enter | Open selected option |
+| App menu | Q | Back to home screen |
+| Inbox | W / S | Scroll conversations |
+| Inbox | Enter | Open conversation |
+| Inbox | C | Compose new SMS (enter phone number) |
+| Inbox | D | Open contacts directory |
+| Inbox | Q | Back to app menu |
+| Conversation | W / S | Scroll messages |
+| Conversation | C | Reply to this conversation |
+| Conversation | F | Call this number |
+| Conversation | A | Add or edit contact name for this number |
+| Conversation | Q | Back to inbox |
+| Compose | Enter | Send SMS (from body) / Confirm phone number (from phone input) |
+| Compose | Shift+Del | Cancel and return |
+| Contacts | W / S | Scroll contact list |
+| Contacts | Enter | Compose SMS to selected contact |
+| Contacts | F | Call selected contact |
+| Contacts | Q | Back to inbox |
+| Edit Contact | Enter | Save contact name |
+| Edit Contact | Shift+Del | Cancel without saving |
+| Phone Dialer | 0–9, *, +, # | Enter phone number (see input methods below) |
+| Phone Dialer | Enter | Place call |
+| Phone Dialer | Backspace | Delete last digit |
+| Phone Dialer | Q | Back to app menu |
+| Dialing | Enter or Q | Cancel / hang up |
+| Incoming Call | Enter | Answer call |
+| Incoming Call | Q | Reject call |
+| In Call | Enter or Q | Hang up |
+| In Call | W / S | Volume up / down (0–5) |
+| In Call | 0–9, *, # | Send DTMF tone |
+
+### Sending an SMS
+
+There are three ways to start a new message:
+
+1. **From inbox** — press **C**, type the destination phone number, press
+   **Enter**, then type your message and press **Enter** to send.
+2. **From a conversation** — press **C** to reply. The recipient is
+   pre-filled so you go straight to typing the message body.
+3. **From the contacts directory** — press **D** from the inbox, scroll to a
+   contact, and press **Enter**. The compose screen opens with the number
+   pre-filled.
+
+Messages are limited to 160 characters (standard SMS). A character counter is
+shown in the footer while composing.
+
+### Making a Phone Call
+
+There are three ways to start a call:
+
+1. **From the phone dialer** — select **Phone** from the app menu to open the
+   dialer. Enter a phone number and press **Enter** to call. This is the
+   easiest way to call a number you haven't messaged before.
+2. **From a conversation** — open a conversation and press **F**. You can call
+   any number you have previously exchanged messages with, whether or not it is
+   saved as a named contact.
+3. **From the contacts directory** — press **D** from the inbox, scroll to a
+   contact, and press **F**.
+
+The display switches to a dialing screen showing the contact name (or phone
+number) and an animated progress indicator. Once the remote party answers, the
+screen transitions to the in-call view with a live call timer.
+
+During an active call, **W** and **S** adjust the speaker volume (0–5). The
+number keys **0–9**, **\***, and **#** send DTMF tones for navigating phone
+menus and voicemail systems. Press **Enter** or **Q** to hang up.
+
+Audio is routed through the A7682E modem's internal codec to the board speaker
+and microphone — no headphones or external audio hardware are required.
+
+### Phone Dialer Input Methods
+
+The phone dialer supports three ways to enter digits:
+
+1. **Direct key press** — press the keyboard letter that corresponds to each
+   number using the silk-screened labels on the T-Deck Pro keys:
+
+   | Key | Digit | | Key | Digit | | Key | Digit |
+   |-----|-------|-|-----|-------|-|-----|-------|
+   | W | 1 | | S | 4 | | Z | 7 |
+   | E | 2 | | D | 5 | | X | 8 |
+   | R | 3 | | F | 6 | | C | 9 |
+   | A | * | | O | + | | Mic | 0 |
+
+2. **Touchscreen tap** — tap the on-screen number buttons directly. Note: this
+   currently requires fairly precise taps on the numbers themselves.
+
+3. **Sym+key** — the standard symbol entry method (e.g. Sym+W for 1, Sym+S for
+   4, etc.)
+
+### Receiving a Phone Call
+
+When an incoming call arrives, the app automatically switches to the incoming
+call screen regardless of which view is active. A short alert and buzzer
+notification are triggered. The caller's name is shown if saved in contacts,
+otherwise the raw phone number is displayed.
+
+Press **Enter** to answer or **Q** to reject the call. If the call is not
+answered it is logged as a missed call and a "Missed: ..." alert is shown
+briefly.
+
+### Contacts
+
+The contacts directory lets you assign display names to phone numbers.
+Names appear in the inbox list, conversation headers, call screens, and
+compose screen instead of raw numbers.
+
+To add or edit a contact, open a conversation with that number and press **A**.
+Type the display name and press **Enter** to save. Names can be up to 23
+characters long.
+
+Contacts are stored as a plain text file at `/sms/contacts.txt` on the SD card
+in `phone=Display Name` format — one per line, human-editable. Up to 30
+contacts are supported.
+
+### Conversation History
+
+Messages are saved to the SD card automatically and persist across reboots.
+Each phone number gets its own file under `/sms/` on the SD card. The inbox
+shows the most recent 20 conversations sorted by last activity. Within a
+conversation, the most recent 30 messages are loaded with the newest at the
+bottom (chat-style). Sent messages are shown with `>>>` and received messages
+with `<<<`.
+
+Message timestamps use the cellular network clock (synced via NITZ roughly 15
+seconds after each modem startup) and display as relative times (e.g. 5m, 2h,
+1d). If the modem is toggled off and back on, the clock re-syncs automatically.
+
+### Modem Power Control
+
+The 4G modem can be toggled on or off from the settings screen. Scroll to
+**4G Modem: ON/OFF** and press **Enter** to toggle. Switching the modem off
+kills its red status LED and stops all cellular activity. The setting persists
+to SD card and is respected on subsequent boots — if disabled, the modem and
+LED stay off until re-enabled. The SMS & Phone app remains accessible when the
+modem is off but will not be able to send or receive messages or calls.
+
+### Signal Indicator
+
+A signal strength indicator is shown in the top-right corner of all SMS and
+call screens. Bars are derived from the modem's CSQ (signal quality) reading,
+updated every 30 seconds. The modem state (REG, READY, OFF, etc.) is shown
+when not yet connected. During a call, the signal indicator remains visible.
+
+### IMEI, Carrier & APN
+
+The 4G modem's IMEI, current carrier name, and APN are displayed at the bottom
+of the settings screen (press **S** from the home screen), alongside your node
+ID and firmware version.
+
+### SD Card Structure
+
+```
+SD Card
+├── sms/
+│   ├── contacts.txt           (plain text, phone=Name format)
+│   ├── modem.cfg              (0 or 1, modem enable state)
+│   ├── 0412345678.sms         (binary message log per phone number)
+│   └── 0498765432.sms
+├── books/                     (text reader)
+├── audiobooks/                (audio variant only)
+└── ...
+```
+
+### Troubleshooting
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| Modem icon stays at REG / never reaches READY | SIM not inserted, no signal, or SIM requires PIN unlock (not currently supported) |
+| Timestamps show `---` | Modem clock hasn't synced yet (wait ~15 seconds after modem startup), or messages were saved before clock sync was available |
+| Red LED stays on after disabling modem | Toggle the setting off, then reboot — the boot sequence ensures power is cut when disabled |
+| SMS sends but no delivery | Check signal strength; below 5 bars is marginal. Move to better coverage |
+| Call drops immediately after dialing | Check signal strength and ensure the SIM plan supports voice calls |
+| No audio during call | The A7682E routes audio through its own codec; ensure the board speaker is not obstructed. Try adjusting volume with W/S |
+
+> **Note:** The SMS & Phone app is only available on the 4G modem variant of
+> the T-Deck Pro. It is not present on the audio or standalone BLE builds due
+> to shared GPIO pin conflicts between the A7682E modem and PCM5102A DAC.

Serial Settings Guide.md

@@ -0,0 +1,490 @@
+# Meck Serial Settings Guide
+
+Configure your T-Deck Pro's Meck firmware over USB serial — no companion app needed. Plug in a USB-C cable, open a serial terminal, and you have full access to every setting on the device.
+
+## Getting Started
+
+### What You Need
+
+- T-Deck Pro running Meck firmware
+- USB-C cable
+- A serial terminal application:
+  - **Windows:** PuTTY, TeraTerm, or the Arduino IDE Serial Monitor
+  - **macOS:** `screen`, CoolTerm, or the Arduino IDE Serial Monitor
+  - **Linux:** `screen`, `minicom`, `picocom`, or the Arduino IDE Serial Monitor
+
+### Connection Settings
+
+| Parameter | Value |
+|-----------|-------|
+| Baud rate | 115200 |
+| Data bits | 8 |
+| Parity | None |
+| Stop bits | 1 |
+| Line ending | CR (carriage return) or CR+LF |
+
+### Quick Start (macOS / Linux)
+
+```
+screen /dev/ttyACM0 115200
+```
+
+On macOS the port is typically `/dev/cu.usbmodem*`. On Linux it is usually `/dev/ttyACM0` or `/dev/ttyUSB0`.
+
+### Quick Start (Arduino IDE)
+
+Open **Tools → Serial Monitor**, set baud to **115200** and line ending to **Carriage Return** or **Both NL & CR**.
+
+Once connected, type `help` and press Enter to confirm everything is working.
+
+---
+
+## Command Reference
+
+All commands follow a simple pattern: `get` to read, `set` to write.
+
+### Viewing Settings
+
+| Command | Description |
+|---------|-------------|
+| `get all` | Dump every setting at once |
+| `get name` | Device name |
+| `get freq` | Radio frequency (MHz) |
+| `get bw` | Bandwidth (kHz) |
+| `get sf` | Spreading factor |
+| `get cr` | Coding rate |
+| `get tx` | TX power (dBm) |
+| `get radio` | All radio params in one line |
+| `get utc` | UTC offset (hours) |
+| `get notify` | Keyboard flash notification (on/off) |
+| `get largefont` | Larger font mode (on/off) |
+| `get gps` | GPS status and interval |
+| `get pin` | BLE pairing PIN |
+| `get path.hash.mode` | Path hash size (0=1-byte, 1=2-byte, 2=3-byte) |
+| `get rxdelay` | Rx delay base (0=disabled) |
+| `get af` | Airtime factor |
+| `get multi.acks` | Redundant ACKs (0 or 1) |
+| `get int.thresh` | Interference threshold (0=disabled) |
+| `get tx.fail.reset` | TX fail reset threshold (0=disabled, default 3) |
+| `get rx.fail.reboot` | RX stuck reboot threshold (0=disabled, default 3) |
+| `get gps.baud` | GPS baud rate (0=compile-time default) |
+| `get channels` | List all channels with index numbers |
+| `get presets` | List all radio presets with parameters |
+| `get pubkey` | Device public key (hex) |
+| `get firmware` | Firmware version string |
+| `clock` | Current RTC time (UTC + epoch) |
+
+**4G variant only:**
+
+| Command | Description |
+|---------|-------------|
+| `get modem` | Modem enabled/disabled |
+| `get apn` | Current APN |
+| `get imei` | Device IMEI |
+
+### Changing Settings
+
+#### Device Name
+
+```
+set name MyNode
+```
+
+Names cannot contain these characters: `[ ] / \ : , ? *`
+
+#### Radio Parameters (Individual)
+
+Each of these applies immediately — no reboot required.
+
+```
+set freq 910.525
+set bw 62.5
+set sf 7
+set cr 5
+set tx 22
+```
+
+Valid ranges:
+
+| Parameter | Min | Max |
+|-----------|-----|-----|
+| freq | 400.0 | 928.0 |
+| bw | 7.8 | 500.0 |
+| sf | 5 | 12 |
+| cr | 5 | 8 |
+| tx | 1 | Board max (typically 22) |
+
+#### Radio Parameters (All at Once)
+
+Set frequency, bandwidth, spreading factor, and coding rate in a single command:
+
+```
+set radio 910.525 62.5 7 5
+```
+
+#### Radio Presets
+
+The easiest way to configure your radio. First, list the available presets:
+
+```
+get presets
+```
+
+This prints a numbered list like:
+
+```
+  Available radio presets:
+     0  Australia                       915.800 MHz  BW250.0  SF10  CR5  TX22
+     1  Australia (Narrow)              916.575 MHz  BW62.5   SF7   CR8  TX22
+    ...
+    14  USA/Canada (Recommended)        910.525 MHz  BW62.5   SF7   CR5  TX22
+    15  Vietnam                         920.250 MHz  BW250.0  SF11  CR5  TX22
+```
+
+Apply a preset by name or number:
+
+```
+set preset USA/Canada (Recommended)
+set preset 14
+```
+
+Preset names are case-insensitive, so `set preset australia` works too. The preset applies all five radio parameters (freq, bw, sf, cr, tx) and takes effect immediately.
+
+#### UTC Offset
+
+```
+set utc 10
+```
+
+Range: -12 to +14.
+
+#### Keyboard Notification Flash
+
+Toggle whether the keyboard backlight flashes when a new message arrives:
+
+```
+set notify on
+set notify off
+```
+
+#### Larger Font Mode
+
+Toggle larger text on channel messages, contacts, DM inbox, and repeater admin screens:
+
+```
+set largefont on
+set largefont off
+```
+
+#### BLE PIN
+
+```
+set pin 123456
+```
+
+#### Path Hash Mode
+
+Controls the byte size of each repeater's identity stamp in forwarded flood packets. Larger hashes reduce collisions at the cost of fewer maximum hops.
+
+```
+set path.hash.mode 1
+```
+
+| Mode | Bytes/hop | Max hops | Notes |
+|------|-----------|----------|-------|
+| 0 | 1 | 64 | Legacy — prone to hash collisions in larger networks |
+| 1 | 2 | 32 | Recommended — effectively eliminates collisions |
+| 2 | 3 | 21 | Maximum precision, rarely needed |
+
+Nodes with different modes can coexist — the mode only affects packets your node originates. The hash size is encoded in each packet's header, so receiving nodes adapt automatically.
+
+### Mesh Tuning
+
+These settings control how the device participates in the mesh network. They take effect immediately — no reboot required (except `gps.baud`).
+
+#### Rx Delay (rxdelay)
+
+Delays processing of flood packets based on signal quality. Stronger signals are processed first; weaker copies wait longer and are typically discarded as duplicates. Direct messages are always processed immediately.
+
+```
+set rxdelay 3
+```
+
+Range: 0–20 (0 = disabled, default). Higher values create larger timing differences between strong and weak signals. Values below 1.0 have no practical effect. See the [MeshSydney wiki](https://meshsydney.com/wiki) for detailed tuning profiles.
+
+#### Airtime Factor (af)
+
+Adjusts how long certain internal timing windows remain open. Does not change the LoRa radio parameters (SF, BW, CR) — those remain as configured.
+
+```
+set af 1.0
+```
+
+Range: 0–9 (default: 1.0). Keep this value consistent across nodes in your mesh for best coherence.
+
+#### Multiple Acknowledgments (multi.acks)
+
+Sends redundant ACK packets for direct messages. When enabled, two ACKs are sent (a multi-ack first, then the standard ACK), improving delivery confirmation reliability.
+
+```
+set multi.acks 1
+```
+
+Values: 0 (single ACK) or 1 (redundant ACKs, default).
+
+#### Interference Threshold (int.thresh)
+
+Enables channel activity scanning before transmitting. Not recommended unless your device is in a high RF interference environment — specifically where the noise floor is low but shows significant fluctuations indicating interference. Enabling this adds approximately 4 seconds of receive delay per packet.
+
+```
+set int.thresh 14
+set int.thresh 0
+```
+
+Values: 0 (disabled, default) or 14+ (14 is the typical setting). Values between 1–13 are not functional and will be rejected.
+
+#### TX Fail Reset Threshold (tx.fail.reset)
+
+Automatically resets the radio hardware after this many consecutive failed transmission attempts. This recovers from "zombie radio" states where the SX1262 stops responding to send commands.
+
+```
+set tx.fail.reset 3
+set tx.fail.reset 0
+```
+
+Values: 0 (disabled) or 1–10 (default: 3). After the threshold is reached, the radio is reset and the failed packet is re-queued.
+
+#### RX Stuck Reboot Threshold (rx.fail.reboot)
+
+Automatically reboots the device after this many consecutive RX-stuck recovery failures. An RX-stuck event occurs when the radio is not in receive mode for 8 seconds despite automatic recovery attempts.
+
+```
+set rx.fail.reboot 3
+set rx.fail.reboot 0
+```
+
+Values: 0 (disabled) or 1–10 (default: 3). A full device reboot is a last resort — this should only trigger in rare cases of persistent radio hardware malfunction.
+
+#### GPS Baud Rate (gps.baud)
+
+Override the GPS serial baud rate. The default (0) uses the compile-time value of 38400. **Requires a reboot to take effect** — the GPS serial port is only configured at startup.
+
+```
+set gps.baud 9600
+set gps.baud 0
+```
+
+Valid rates: 0 (default), 4800, 9600, 19200, 38400, 57600, 115200.
+
+### Channel Management
+
+#### List Channels
+
+```
+get channels
+```
+
+Output:
+
+```
+  [0] #public
+  [1] #meck-test
+  [2] #local-group
+```
+
+#### Add a Hashtag Channel
+
+```
+set channel.add meck-test
+```
+
+The `#` prefix is added automatically if you omit it. The channel's encryption key is derived from the name (SHA-256), matching the same method used by the on-device Settings screen and companion apps.
+
+#### Delete a Channel
+
+```
+set channel.del 2
+```
+
+Channels are referenced by their index number (shown in `get channels`). Channel 0 (public) cannot be deleted. Remaining channels are automatically compacted after deletion.
+
+### 4G Modem (4G Variant Only)
+
+#### Enable / Disable Modem
+
+```
+set modem on
+set modem off
+```
+
+#### Set APN
+
+```
+set apn telstra.internet
+```
+
+To clear a custom APN and revert to auto-detection on next boot:
+
+```
+set apn
+```
+
+### Clock Sync
+
+Set the device's real-time clock from a Unix timestamp. This is especially important for the T5S3 E-Paper Pro which has no GPS to auto-set the clock. These are standalone commands (not `get`/`set` prefixed) — matching the same `clock sync` command used on MeshCore repeaters.
+
+#### View Current Time
+
+```
+clock
+```
+
+Output:
+
+```
+  > 2026-03-13 04:22:15 UTC (epoch: 1773554535)
+```
+
+If the clock has never been set:
+
+```
+  > not set (epoch: 0)
+```
+
+#### Sync Clock from Serial
+
+```
+clock sync 1773554535
+```
+
+The value must be a Unix epoch timestamp in the 2024–2036 range.
+
+**Quick one-liner from your terminal (macOS / Linux / WSL):**
+
+```
+echo "clock sync $(date +%s)" > /dev/ttyACM0
+```
+
+Or paste directly into the Arduino IDE Serial Monitor:
+
+```
+clock sync 1773554535
+```
+
+**Tip:** On macOS/Linux, run `date +%s` to get the current epoch. On Windows PowerShell: `[int](Get-Date -UFormat %s)`.
+
+#### Boot-Time Auto-Sync (T5S3)
+
+When the T5S3 boots with no valid RTC time and detects a USB serial host is connected, it sends a `MECK_CLOCK_REQ` handshake over serial. If you're using PlatformIO's serial monitor (`pio device monitor`), the built-in `clock_sync` monitor filter responds automatically with the host computer's current time — no user action required. The sync appears transparently in the boot log:
+
+```
+MECK_CLOCK_REQ
+  (Waiting 3s for clock sync from host...)
+  > Clock synced to 1773554535
+```
+
+If no USB host is connected (e.g. running on battery), the sync window is skipped entirely with no boot delay.
+
+**Manual fallback:** If you're using a serial terminal that doesn't have the filter (e.g. `screen`, PuTTY), you can paste a `clock sync` command during the 3-second window, or any time after boot:
+
+```
+clock sync $(date +%s)
+```
+
+### System Commands
+
+| Command | Description |
+|---------|-------------|
+| `reboot` | Restart the device |
+| `rebuild` | Erase filesystem, re-save identity + prefs + contacts + channels |
+| `erase` | Format the filesystem (caution: loses everything) |
+| `ls UserData/` | List files on internal filesystem |
+| `ls ExtraFS/` | List files on secondary filesystem |
+| `cat UserData/<path>` | Dump file contents as hex |
+| `rm UserData/<path>` | Delete a file |
+| `help` | Show command summary |
+
+---
+
+## Common Workflows
+
+### First-Time Setup
+
+Plug in your new T-Deck Pro and run through these commands to get on the air:
+
+```
+set name YourCallsign
+set preset Australia
+set utc 10
+set channel.add local-group
+get all
+```
+
+### Switching to a New Region
+
+Moving from Australia to the US? One command:
+
+```
+set preset USA/Canada (Recommended)
+```
+
+Verify with:
+
+```
+get radio
+```
+
+### Custom Radio Configuration
+
+If none of the presets match your local group or you need specific parameters, set them directly. You can do it all in one command:
+
+```
+set radio 916.575 62.5 8 8
+set tx 20
+```
+
+Or one parameter at a time if you're only adjusting part of your config:
+
+```
+set freq 916.575
+set bw 62.5
+set sf 8
+set cr 8
+set tx 20
+```
+
+Both approaches apply immediately. Confirm with `get radio` to double-check everything took:
+
+```
+get radio
+  > freq=916.575 bw=62.5 sf=8 cr=8 tx=20
+```
+
+### Troubleshooting Radio Settings
+
+If you're not sure what went wrong, dump everything:
+
+```
+get all
+```
+
+Compare the radio section against what others in your area are using. If you need to match exact parameters from another node:
+
+```
+set radio 916.575 62.5 7 8
+set tx 22
+```
+
+### Backing Up Your Settings
+
+Use `get all` to capture a snapshot of your configuration. Copy the serial output and save it — you can manually re-enter the settings after a firmware update or device reset if your SD card backup isn't available.
+
+---
+
+## Tips
+
+- **All radio changes apply live.** There is no need to reboot after changing frequency, bandwidth, spreading factor, coding rate, or TX power. The radio reconfigures on the fly.
+- **Preset selection by number is faster.** Once you've seen `get presets`, use the index number instead of typing the full name.
+- **Settings are persisted immediately.** Every `set` command writes to flash. If power is lost, your settings are safe.
+- **SD card backup is automatic.** If your T-Deck Pro has an SD card inserted, settings are backed up after every change. On a fresh flash, settings restore automatically from the SD card.
+- **The `get all` command is your friend.** When in doubt, dump everything and check.

TXT & EPUB Reader Guide.md

@@ -0,0 +1,126 @@
+# Text & EPUB Reader Integration for Meck Firmware
+
+## Overview
+
+This adds a text reader accessible via the **E** key from the home screen.
+
+**Features:**
+- Browse `.txt` and `.epub` files from `/books/` folder on SD card
+- Automatic EPUB-to-text conversion on first open (cached for instant re-opens)
+- Word-wrapped text rendering using tiny font (maximum text density)  
+- Page navigation with W/S/A/D keys
+- Automatic reading position resume (persisted to SD card)
+- Index files cached to SD for instant re-opens
+- Bookmark indicator (`*`) on files with saved positions
+
+**Key Mapping (T-Deck Pro):**
+| Context | Key | Action |
+|---------|-----|--------|
+| Home screen | E | Open text reader |
+| File list | W/S | Navigate up/down |
+| File list | Tap / Enter | Open selected file |
+| File list | Q | Back to home screen |
+| Reading | W/A | Previous page |
+| Reading | S/D/Space | Next page |
+| Reading | Enter | Go to page number (type digits, Enter to confirm, Q to cancel) |
+| Reading | Q | Close book → file list |
+
+**Touch Gestures (T5S3):**
+| Context | Gesture | Action |
+|---------|---------|--------|
+| File list | Swipe up/down | Scroll file list |
+| File list | Tap | Open selected book |
+| Reading | Tap | Next page |
+| Reading | Swipe left/right | Next / previous page |
+| Reading | Tap footer | Go to page number (via virtual keyboard) |
+| Reading | Long press | Close book → file list |
+
+---
+
+## SD Card Setup
+
+Place `.txt` or `.epub` files in a `/books/` folder on the SD card root. The reader will:
+- Auto-create `/books/` if it doesn't exist
+- Auto-create `/.indexes/` for page index cache files
+- Auto-create `/books/.epub_cache/` for converted EPUB text
+- Skip macOS hidden files (`._*`, `.DS_Store`)
+- Support up to 50 files
+
+**Index format** is compatible with the standalone reader (version 4), so if you've used the standalone reader previously, bookmarks and indexes will carry over.
+
+---
+
+## EPUB Support
+
+### How It Works
+
+EPUB files are transparently converted to plain text on first open. The conversion pipeline is:
+
+1. **File list** — `scanFiles()` picks up both `.txt` and `.epub` files from `/books/`
+2. **First open** — `openBook()` detects the `.epub` extension and triggers conversion:
+   - Shows a "Converting EPUB..." splash screen
+   - Extracts the ZIP structure using ESP32-S3's built-in ROM `tinfl` decompressor (no external library needed)
+   - Parses `META-INF/container.xml` → finds the OPF file
+   - Parses the OPF manifest and spine to get chapters in reading order
+   - Extracts each XHTML chapter, strips tags, decodes HTML entities
+   - Writes concatenated plain text to `/books/.epub_cache/<filename>.txt`
+3. **Subsequent opens** — the cached `.txt` is found immediately and opened like any regular text file
+
+### Cache Structure
+
+```
+/books/
+  MyBook.epub              ← original EPUB (untouched)
+  SomeStory.txt            ← regular text file
+  .epub_cache/
+    MyBook.txt             ← auto-generated from MyBook.epub
+/.indexes/
+  MyBook.txt.idx           ← page index for the converted text
+```
+
+- The original `.epub` file is never modified
+- Deleting a cached `.txt` from `.epub_cache/` forces re-conversion on next open
+- Index files (`.idx`) work identically for both regular and EPUB-derived text files
+- Boot scan picks up previously cached EPUB text files so they appear in the file list even before the EPUB is re-opened
+
+### EPUB Processing Details
+
+The conversion is handled by three components:
+
+| Component | Role |
+|-----------|------|
+| `EpubZipReader.h` | ZIP central directory parsing + `tinfl` decompression (supports Store and Deflate) |
+| `EpubProcessor.h` | EPUB structure parsing (container.xml → OPF → spine) and XHTML tag stripping |
+| `TextReaderScreen.h` | Integration: detects `.epub`, triggers conversion, redirects to cached `.txt` |
+
+**XHTML stripping handles:**
+- Tag removal with block-element newlines (`<p>`, `<br>`, `<div>`, `<h1>`–`<h6>`, `<li>`, etc.)
+- `<head>`, `<style>`, `<script>` content skipped entirely
+- HTML entity decoding: named (`&amp;`, `&mdash;`, `&ldquo;`, etc.) and numeric (`&#8212;`, `&#x2014;`)
+- Smart quote / em-dash / ellipsis → ASCII equivalents (e-ink font is ASCII-only)
+- Whitespace collapsing and cleanup
+
+**Limits:**
+- Max 200 chapters in spine (`EPUB_MAX_CHAPTERS`)
+- Max 256 manifest items (`EPUB_MAX_MANIFEST`)
+- Manifest and chapter data are heap-allocated in PSRAM where available
+- Typical conversion time: 2–10 seconds depending on book size
+
+### Troubleshooting
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| "Convert failed!" splash | EPUB may be DRM-protected, corrupted, or use an unusual structure |
+| EPUB appears in list but opens as blank | Check serial output for `EpubProc:` messages; chapter count may be 0 |
+| Stale content after replacing an EPUB | Delete the matching `.txt` from `/books/.epub_cache/` to force re-conversion |
+
+---
+
+## Architecture Notes
+
+- The reader renders through the standard `UIScreen::render()` framework, so no special bypass is needed in the main loop (unlike compose mode)
+- SD card uses the same HSPI bus as e-ink display and LoRa radio — CS pin management handles contention
+- Page content is pre-read from SD into a memory buffer during `handleInput()`, then rendered from buffer during `render()` — this avoids SPI bus conflicts during display refresh
+- Layout metrics (chars per line, lines per page) are calculated dynamically from the display driver's font metrics on first entry
+- EPUB conversion runs synchronously in `openBook()` — the e-ink splash screen keeps the user informed while the ESP32 processes the archive
+- ZIP extraction uses the ESP32-S3's hardware-optimised ROM `tinfl` inflate, avoiding external compression library dependencies and the linker conflicts they cause

Web App Guide.md

@@ -0,0 +1,181 @@
+# Web Reader & IRC - Meck v0.9.5
+
+Press **B** from the home screen to open the web reader. The web reader is
+available on the BLE and 4G variants. It is excluded from the standalone audio
+variant to preserve zero-radio-power design.
+
+The web reader home screen provides access to the **IRC client**, the **URL
+bar**, your **bookmarks**, and browsing **history**. Use **W / S** to navigate
+the list and **Enter** to select an item.
+
+## Web Browser
+
+A text-centric web browser ("reader mode") that fetches pages over WiFi,
+strips HTML to readable text, extracts links as numbered references, and
+paginates content for the e-ink display. Still very much in development, but
+already useful for text-heavy websites.
+
+Includes basic web search via **DuckDuckGo Lite** — type a search query into
+the URL bar and it will be sent to DuckDuckGo.
+
+### EPUB Downloads
+
+If you follow a link to an `.epub` file, it will be saved directly to the
+`/books/` folder on your SD card. You can then read it in the e-book reader
+(press **E** from the home screen).
+
+### Bookmarks
+
+Press **K** while on a page to save a bookmark. Bookmarks appear on the web
+reader home screen below the URL bar. To delete a bookmark, open the browser
+home screen, scroll down to the bookmark, and press **Delete**.
+
+### Cookies & History
+
+Press **X** to clear cookies and browsing history.
+
+---
+
+## IRC Client
+
+The IRC client lets you connect to IRC networks directly from the device. It
+is accessed from the web reader home screen — select **IRC Chat** (the first
+item) and press **Enter**.
+
+If you are not currently connected, the IRC setup screen opens where you can
+configure the server, port, nickname, and channel. If you are already
+connected, you go straight to the chat view.
+
+### IRC Setup
+
+The setup screen has five fields. Use **W / S** to navigate between them and
+press **Enter** to edit a field (type the value, then **Enter** to confirm).
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| Host | IRC server hostname (e.g. `irc.libera.chat`) | — |
+| Port | Server port. Use `6697` for TLS or `6667` for plain | 6697 |
+| Nick | Your IRC nickname (max 16 characters) | — |
+| Channel | Channel to join, including the `#` (e.g. `#meshcore`) | — |
+| Connect | Select and press Enter to connect | — |
+
+TLS is used automatically when the port is 6697. Other ports connect without
+encryption.
+
+Configuration is saved to the SD card at `/web/irc.cfg` and restored on next
+launch, so you only need to enter server details once.
+
+If WiFi is not connected when you press Connect, you'll be taken to the WiFi
+setup screen first.
+
+### IRC Chat View
+
+Once connected and joined to the channel, you'll see messages in a scrollable
+chat view. The channel name and connection status are shown at the top.
+
+| Key | Action |
+|-----|--------|
+| Enter | Start composing a message (type, then Enter to send) |
+| Backspace | Delete last character while composing; exit compose if empty |
+| W / S | Scroll up (older) / down (newer) through messages |
+| X | Disconnect from IRC and return to web reader home |
+| Q | Return to web reader home (connection stays alive in background) |
+
+The IRC connection remains active when you press **Q** to go back to the web
+reader home screen. You'll see the connection status and channel name displayed
+on the IRC Chat line. Select it and press Enter to return to the chat. Press
+**X** from the chat view to disconnect.
+
+The client automatically reconnects if the connection drops (10-second delay
+between attempts) and detects dead connections after 5 minutes of inactivity
+via ping timeout.
+
+Messages are stored in a circular buffer of 64 messages. Older messages are
+discarded as new ones arrive.
+
+---
+
+## Key Bindings
+
+### From Home Screen
+| Key | Action |
+|-----|--------|
+| `b` | Open web reader |
+
+### Web Reader - Home View
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate up/down in IRC / URL bar / bookmarks / history |
+| `Enter` | Select IRC Chat, activate URL bar, or open bookmark/history item |
+| Type | Enter URL (when URL bar is active) |
+| `q` | Exit to firmware home |
+
+### Web Reader - Reading View
+| Key | Action |
+|-----|--------|
+| `w` / `a` | Previous page |
+| `s` / `d` / `Space` | Next page |
+| `l` or `Enter` | Enter link selection (type link number) |
+| `g` | Go to new URL (return to web reader home) |
+| `k` | Bookmark current page |
+| `x` | Clear cookies and history |
+| `q` | Back to web reader home |
+
+### Web Reader - WiFi Setup
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate SSID list |
+| `Enter` | Select SSID / submit password / retry |
+| Type | Enter WiFi password |
+| `q` | Back |
+
+### IRC - Setup View
+| Key | Action |
+|-----|--------|
+| `w` / `s` | Navigate fields (Host / Port / Nick / Channel / Connect) |
+| `Enter` | Edit selected field, or connect (when on Connect button) |
+| Type | Enter field value (when editing) |
+| `Backspace` | Delete last character (when editing) |
+| `q` | Back to web reader home |
+
+### IRC - Chat View
+| Key | Action |
+|-----|--------|
+| `Enter` | Start composing / send message |
+| `Backspace` | Delete character / exit compose if empty |
+| `w` / `s` | Scroll older / newer messages |
+| `x` | Disconnect and return to web reader home |
+| `q` | Back to web reader home (stays connected) |
+
+---
+
+## WiFi
+
+The web reader and IRC client both use WiFi for network access. On first use,
+you'll be taken to the WiFi setup screen to scan for networks and enter a
+password. Credentials are saved to `/web/wifi.cfg` on the SD card and used for
+auto-reconnect on subsequent launches.
+
+On the 4G variant, the web reader currently uses WiFi. A future update will add
+PPP support via the A7682E cellular modem, allowing the browser and IRC to work
+over cellular data without WiFi.
+
+---
+
+## SD Card Structure
+```
+/web/
+  wifi.cfg         - Saved WiFi credentials (auto-reconnect)
+  bookmarks.txt    - One URL per line
+  history.txt      - Recent URLs, newest first
+  irc.cfg          - IRC server/port/nick/channel config
+```
+
+---
+
+## Conditional Compilation
+All web reader code is wrapped in `#ifdef MECK_WEB_READER` guards. The flag is set:
+- **meck_audio_ble**: Yes (`-D MECK_WEB_READER=1`) — WiFi available via BLE radio stack
+- **meck_4g_ble**: Yes (`-D MECK_WEB_READER=1`) — WiFi now, PPP via A7682E in future
+- **meck_4g_standalone**: Yes (`-D MECK_WEB_READER=1`) — WiFi works better without BLE (no teardown needed, more free heap)
+- **meck_audio_standalone**: No — excluded to preserve zero-radio-power design

boards/t5s3-epaper-pro.json

@@ -0,0 +1,38 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32s3_out.ld",
+      "memory_type": "qio_opi",
+      "partitions": "default_16MB.csv"
+    },
+    "core": "esp32",
+    "extra_flags": [
+      "-DBOARD_HAS_PSRAM",
+      "-DARDUINO_RUNNING_CORE=1",
+      "-DARDUINO_EVENT_RUNNING_CORE=0",
+      "-DARDUINO_USB_CDC_ON_BOOT=1",
+      "-DARDUINO_USB_MODE=1"
+    ],
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "hwids": [["0x303A", "0x1001"]],
+    "mcu": "esp32s3",
+    "variant": "esp32s3"
+  },
+  "connectivity": ["wifi", "bluetooth", "lora"],
+  "debug": {
+    "openocd_target": "esp32s3.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "LilyGo T5S3 E-Paper Pro",
+  "upload": {
+    "flash_size": "16MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 16777216,
+    "require_upload_port": true,
+    "speed": 921600
+  },
+  "url": "https://lilygo.cc/products/t5-e-paper-s3-pro",
+  "vendor": "LILYGO"
+}

docs/Launcher_Flash_Guide.md

@@ -0,0 +1,101 @@
+# How to Flash Meck Firmware Using Launcher over WiFi
+
+## How to Install Launcher on Your T-Deck Pro
+
+First, ensure your SD card is inserted into your T-Deck Pro. Your SD card should already have been formatted as FAT32.
+
+1. Plug your T-Deck Pro into your computer via USB-C.
+2. Go to [https://bmorcelli.github.io/Launcher/webflasher.html](https://bmorcelli.github.io/Launcher/webflasher.html) in Chrome browser.
+3. Click on **LilyGo** under Choose a Vendor.
+4. Click on **T-Deck Pro**.
+5. Click on **Connect**.
+6. In the serial connect popup, click on your device in the list (likely starts with "USB JTAG/serial debug unit"), and click **Connect**. Wait a few seconds for it to connect.
+7. Click the **Install T-Deck Pro** popup.
+8. Click **Next**. (Don't worry about ticking the Erase Device checkbox.)
+9. Click **Install**.
+
+### If You Don't Already Have a Meck Firmware File
+
+Download one from [https://github.com/pelgraine/Meck/releases](https://github.com/pelgraine/Meck/releases).
+
+## How to Install a New Meck Firmware .bin File via Launcher
+
+After flashing using [https://bmorcelli.github.io/Launcher/webflasher.html](https://bmorcelli.github.io/Launcher/webflasher.html), your Pro will reboot itself automatically and display the main Launcher home screen, with the SD card option highlighted.
+
+<img src="images/01_launcher_home.jpg" alt="Launcher home screen" width="200">
+
+Either tap **NEXT** on the device screen twice or tap on the WUI button, and tap **SEL**.
+
+<img src="images/02_wui_selected.jpg" alt="WUI selected" width="200">
+
+Tap on **My Network** on the pop-up menu. Press **NEXT/SEL** as needed to highlight and select your WiFi SSID.
+
+Enter your WiFi SSID details.
+
+Once connected, your device will display the WebUI connection screen with the T-Deck Pro IP address.
+
+Open a browser on your computer — Chrome, Firefox, or Safari will do, but Firefox tends to be easiest — and type in the IP address displayed on your T-Deck Pro into your computer browser address bar, and press enter.
+
+<img src="images/03_webui_ip.jpg" alt="WebUI IP address screen" width="200">
+
+In this instance, for example, I would type `192.168.1.118`, and once I've pressed enter, the address bar now displays `http://192.168.1.118/` (as per the photo). If you're having trouble loading the IP address page, double check your browser hasn't automatically changed it to `https`. If it has, delete the `s` out of the URL and hit enter to load the page.
+
+Login to the browser page with the username **admin** and password **launcher**, and click **Login**. The browser will refresh and display your SD card file list.
+
+<img src="images/04_browser_login.jpg" alt="Browser login" width="450">
+
+<img src="images/05_send_files.png" alt="SD card file list with Send Files button" width="450">
+
+Scroll down to the bottom of the browser page, and click the **Send Files** button.
+
+Your computer/device will load the file browser. Navigate to wherever you've previously saved your new Meck firmware `.bin` file, select the bin file, and click **Open**.
+
+Wait for the blue loading bar on the bottom of the browser page to finish, and then check you can see the file name in the list in green. Also worth checking the file is at least 1.2MB — if it is under 1MB, the file hasn't uploaded properly and you will need to go through the **Send Files** button to try uploading it again.
+
+<img src="images/06_check_file_uploaded.png" alt="Check file uploaded" width="450">
+
+You can then either close the browser window or just leave it. Go back to your T-Deck Pro and press **SEL** to disconnect the WUI mode.
+
+<img src="images/07_disconnect_wui.png" alt="Disconnect WUI" width="200">
+
+Either press **PREV** twice to navigate to it and then press **SEL** again to open, or tap right on the **SD** button to open the SD card menu.
+
+<img src="images/08_sd_button.jpg" alt="SD button on Launcher home" width="200">
+
+The Launcher SD file browser will open. You will most likely have to tap **Page Down** at least twice to scroll to where the name of your new file is.
+
+<img src="images/09_sd_file_list.png" alt="SD file list page 1" width="200">
+
+<img src="images/10_page_down.png" alt="Page Down to find file" width="200">
+
+Either press **NEXT** to navigate until the new file is highlighted with the `>`, or just tap right on the file name, and press **SEL** to bring up the file menu.
+
+<img src="images/11_select_file.png" alt="Select the firmware file" width="200">
+
+The first option on the file menu list will be **>Install**. You can either tap right on **Install** or tap **SEL**.
+
+<img src="images/12_install_option.png" alt="Install option" width="200">
+
+**Wait for the firmware to finish installing.** It will reboot itself automatically.
+
+<img src="images/13_installing_fw.jpg" alt="Installing firmware" width="200">
+
+> **Note:** On first flash of a new firmware version, the "Loading…" screen will most likely display for about 70 seconds. This is a known bug. **Please be patient** if this is the first time loading your new Meck firmware.
+
+<img src="images/14_loading_screen.png" alt="Loading screen" width="200">
+
+On every boot, the firmware will scan your SD card and `/books` folder for any new `.txt` or `.epub` files that haven't yet been cached. It's usually very quick even if you have a lot of ebook files, and even faster after the first boot.
+
+<img src="images/15_indexing_pages.jpg" alt="Indexing pages" width="200">
+
+You'll then see the firmware version splash screen for a split second.
+
+<img src="images/16_version_splash.jpg" alt="Version splash screen" width="200">
+
+Then the Meck home screen will display, and you're good to go. Here's an example of what the Meck 4G WiFi companion firmware home screen looks like:
+
+<img src="images/17_meck_home.jpg" alt="Meck home screen" width="200">
+
+> **Tip:** Every time you reset the device, the Launcher splash screen will display. Wait about six seconds if you just want the Meck firmware to boot by default. Otherwise, tap the **LAUNCHER** text at the bottom to boot back into the Launcher home screen, to get access to the SD menu and WUI menu again.
+
+<img src="images/18_launcher_boot.jpg" alt="Launcher boot screen" width="200">

examples/companion_radio/AbstractUITask.h

@@ -40,7 +40,19 @@ public:
   void enableSerial() { _serial->enable(); }
   void disableSerial() { _serial->disable(); }
   virtual void msgRead(int msgcount) = 0;
-  virtual void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount) = 0;
+  virtual void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount,
+                      const uint8_t* path = nullptr, int8_t snr = 0) = 0;
   virtual void notify(UIEventType t = UIEventType::none) = 0;
   virtual void loop() = 0;
-};
+  virtual void showAlert(const char* text, int duration_millis) {}
+  virtual void forceRefresh() {}
+  virtual void addSentChannelMessage(uint8_t channel_idx, const char* sender, const char* text) {}
+
+  // Mark a channel as read when BLE companion app syncs a message
+  virtual void markChannelReadFromBLE(uint8_t channel_idx) {}
+
+  // Repeater admin callbacks (from MyMesh)
+  virtual void onAdminLoginResult(bool success, uint8_t permissions, uint32_t server_time) {}
+  virtual void onAdminCliResponse(const char* from_name, const char* text) {}
+  virtual void onAdminTelemetryResult(const uint8_t* data, uint8_t len) {}
+};

examples/companion_radio/DataStore.cpp

@@ -228,6 +228,73 @@ void DataStore::loadPrefsInt(const char *filename, NodePrefs& _prefs, double& no
     file.read((uint8_t *)&_prefs.gps_enabled, sizeof(_prefs.gps_enabled));                 // 85
     file.read((uint8_t *)&_prefs.gps_interval, sizeof(_prefs.gps_interval));               // 86
     file.read((uint8_t *)&_prefs.autoadd_config, sizeof(_prefs.autoadd_config));           // 87
+    file.read((uint8_t *)&_prefs.utc_offset_hours, sizeof(_prefs.utc_offset_hours));       // 88
+
+    // Fields added later — may not exist in older prefs files
+    if (file.read((uint8_t *)&_prefs.kb_flash_notify, sizeof(_prefs.kb_flash_notify)) != sizeof(_prefs.kb_flash_notify)) {
+      _prefs.kb_flash_notify = 0;  // default OFF for old files
+    }
+    if (file.read((uint8_t *)&_prefs.ringtone_enabled, sizeof(_prefs.ringtone_enabled)) != sizeof(_prefs.ringtone_enabled)) {
+      _prefs.ringtone_enabled = 0;  // default OFF for old files
+    }
+
+    // Clamp booleans to 0/1 in case of garbage
+    if (_prefs.kb_flash_notify > 1) _prefs.kb_flash_notify = 0;
+    if (_prefs.ringtone_enabled > 1) _prefs.ringtone_enabled = 0;
+
+    // v1.14+ fields — may not exist in older prefs files
+    if (file.read((uint8_t *)&_prefs.path_hash_mode, sizeof(_prefs.path_hash_mode)) != sizeof(_prefs.path_hash_mode)) {
+      _prefs.path_hash_mode = 0;  // default: legacy 1-byte
+    }
+    if (file.read((uint8_t *)&_prefs.autoadd_max_hops, sizeof(_prefs.autoadd_max_hops)) != sizeof(_prefs.autoadd_max_hops)) {
+      _prefs.autoadd_max_hops = 0;  // default: no limit
+    }
+    if (_prefs.path_hash_mode > 2) _prefs.path_hash_mode = 0;
+    if (_prefs.autoadd_max_hops > 64) _prefs.autoadd_max_hops = 0;
+
+    // v1.1+ Meck fields — may not exist in older prefs files
+    if (file.read((uint8_t *)&_prefs.gps_baudrate, sizeof(_prefs.gps_baudrate)) != sizeof(_prefs.gps_baudrate)) {
+      _prefs.gps_baudrate = 0;  // default: use compile-time GPS_BAUDRATE
+    }
+    if (file.read((uint8_t *)&_prefs.interference_threshold, sizeof(_prefs.interference_threshold)) != sizeof(_prefs.interference_threshold)) {
+      _prefs.interference_threshold = 0;  // default: disabled
+    }
+    if (file.read((uint8_t *)&_prefs.dark_mode, sizeof(_prefs.dark_mode)) != sizeof(_prefs.dark_mode)) {
+      _prefs.dark_mode = 0;  // default: light mode
+    }
+    if (file.read((uint8_t *)&_prefs.portrait_mode, sizeof(_prefs.portrait_mode)) != sizeof(_prefs.portrait_mode)) {
+      _prefs.portrait_mode = 0;  // default: landscape
+    }
+    if (file.read((uint8_t *)&_prefs.auto_lock_minutes, sizeof(_prefs.auto_lock_minutes)) != sizeof(_prefs.auto_lock_minutes)) {
+      _prefs.auto_lock_minutes = 0;  // default: disabled
+    }
+    if (file.read((uint8_t *)&_prefs.hint_shown, sizeof(_prefs.hint_shown)) != sizeof(_prefs.hint_shown)) {
+      _prefs.hint_shown = 0;  // default: show boot hint
+    }
+    if (file.read((uint8_t *)&_prefs.large_font, sizeof(_prefs.large_font)) != sizeof(_prefs.large_font)) {
+      _prefs.large_font = 0;  // default: tiny font
+    }
+    if (file.read((uint8_t *)&_prefs.tx_fail_reset_threshold, sizeof(_prefs.tx_fail_reset_threshold)) != sizeof(_prefs.tx_fail_reset_threshold)) {
+      _prefs.tx_fail_reset_threshold = 3;  // default: 3
+    }
+    if (file.read((uint8_t *)&_prefs.rx_fail_reboot_threshold, sizeof(_prefs.rx_fail_reboot_threshold)) != sizeof(_prefs.rx_fail_reboot_threshold)) {
+      _prefs.rx_fail_reboot_threshold = 3;  // default: 3
+    }
+
+    // Clamp to valid ranges
+    if (_prefs.dark_mode > 1) _prefs.dark_mode = 0;
+    if (_prefs.portrait_mode > 1) _prefs.portrait_mode = 0;
+    if (_prefs.hint_shown > 1) _prefs.hint_shown = 0;
+    if (_prefs.large_font > 1) _prefs.large_font = 0;
+    if (_prefs.tx_fail_reset_threshold > 10) _prefs.tx_fail_reset_threshold = 3;
+    if (_prefs.rx_fail_reboot_threshold > 10) _prefs.rx_fail_reboot_threshold = 3;
+    // auto_lock_minutes: only accept known options (0, 2, 5, 10, 15, 30)
+    {
+      uint8_t alm = _prefs.auto_lock_minutes;
+      if (alm != 0 && alm != 2 && alm != 5 && alm != 10 && alm != 15 && alm != 30) {
+        _prefs.auto_lock_minutes = 0;
+      }
+    }
 
     file.close();
   }
@@ -263,14 +330,76 @@ void DataStore::savePrefs(const NodePrefs& _prefs, double node_lat, double node_
     file.write((uint8_t *)&_prefs.gps_enabled, sizeof(_prefs.gps_enabled));                 // 85
     file.write((uint8_t *)&_prefs.gps_interval, sizeof(_prefs.gps_interval));               // 86
     file.write((uint8_t *)&_prefs.autoadd_config, sizeof(_prefs.autoadd_config));           // 87
+    file.write((uint8_t *)&_prefs.utc_offset_hours, sizeof(_prefs.utc_offset_hours));     // 88
+    file.write((uint8_t *)&_prefs.kb_flash_notify, sizeof(_prefs.kb_flash_notify));      // 89
+    file.write((uint8_t *)&_prefs.ringtone_enabled, sizeof(_prefs.ringtone_enabled));    // 90
+    file.write((uint8_t *)&_prefs.path_hash_mode, sizeof(_prefs.path_hash_mode));        // 91
+    file.write((uint8_t *)&_prefs.autoadd_max_hops, sizeof(_prefs.autoadd_max_hops));   // 92
+    file.write((uint8_t *)&_prefs.gps_baudrate, sizeof(_prefs.gps_baudrate));            // 93
+    file.write((uint8_t *)&_prefs.interference_threshold, sizeof(_prefs.interference_threshold)); // 97
+    file.write((uint8_t *)&_prefs.dark_mode, sizeof(_prefs.dark_mode));                  // 98
+    file.write((uint8_t *)&_prefs.portrait_mode, sizeof(_prefs.portrait_mode));          // 99
+    file.write((uint8_t *)&_prefs.auto_lock_minutes, sizeof(_prefs.auto_lock_minutes)); // 100
+    file.write((uint8_t *)&_prefs.hint_shown, sizeof(_prefs.hint_shown));               // 101
+    file.write((uint8_t *)&_prefs.large_font, sizeof(_prefs.large_font));               // 102
+    file.write((uint8_t *)&_prefs.tx_fail_reset_threshold, sizeof(_prefs.tx_fail_reset_threshold)); // 103
+    file.write((uint8_t *)&_prefs.rx_fail_reboot_threshold, sizeof(_prefs.rx_fail_reboot_threshold)); // 104
 
     file.close();
   }
 }
 
 void DataStore::loadContacts(DataStoreHost* host) {
-File file = openRead(_getContactsChannelsFS(), "/contacts3");
+  FILESYSTEM* fs = _getContactsChannelsFS();
+
+  // --- Crash recovery ---
+  // If /contacts3 is missing but /contacts3.tmp exists, a crash occurred
+  // after removing the original but before the rename completed.
+  // The .tmp file has the valid data — promote it.
+  if (!fs->exists("/contacts3") && fs->exists("/contacts3.tmp")) {
+    Serial.println("DataStore: recovering contacts from .tmp file");
+    fs->rename("/contacts3.tmp", "/contacts3");
+  }
+  // If both exist, a crash occurred before the old file was removed.
+  // The original /contacts3 is still valid — just clean up the orphan.
+  if (fs->exists("/contacts3.tmp")) {
+    fs->remove("/contacts3.tmp");
+  }
+
+  File file = openRead(fs, "/contacts3");
     if (file) {
+      // --- Truncation guard ---
+      // If the file is smaller than one full contact record (152 bytes),
+      // it was truncated by a crash/brown-out. Discard it and try the
+      // .tmp backup if available.
+      size_t fsize = file.size();
+      if (fsize > 0 && fsize < 152) {
+        Serial.printf("DataStore: contacts3 truncated (%d bytes < 152), discarding\n", (int)fsize);
+        file.close();
+        fs->remove("/contacts3");
+        if (fs->exists("/contacts3.tmp")) {
+          File tmp = openRead(fs, "/contacts3.tmp");
+          if (tmp && tmp.size() >= 152) {
+            Serial.println("DataStore: recovering from .tmp after truncation");
+            tmp.close();
+            fs->rename("/contacts3.tmp", "/contacts3");
+            file = openRead(fs, "/contacts3");
+            if (!file) return;  // give up
+          } else {
+            if (tmp) tmp.close();
+            Serial.println("DataStore: no valid contacts backup — starting fresh");
+            return;
+          }
+        } else {
+          Serial.println("DataStore: no .tmp backup — starting fresh");
+          return;
+        }
+      } else if (fsize == 0) {
+        // Empty file — nothing to load
+        file.close();
+        return;
+      }
+
       bool full = false;
       while (!full) {
         ContactInfo c;
@@ -300,36 +429,181 @@ File file = openRead(_getContactsChannelsFS(), "/contacts3");
 }
 
 void DataStore::saveContacts(DataStoreHost* host) {
-  File file = openWrite(_getContactsChannelsFS(), "/contacts3");
-  if (file) {
-    uint32_t idx = 0;
-    ContactInfo c;
-    uint8_t unused = 0;
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  const char* finalPath = "/contacts3";
+  const char* tmpPath   = "/contacts3.tmp";
 
-    while (host->getContactForSave(idx, c)) {
-      bool success = (file.write(c.id.pub_key, 32) == 32);
-      success = success && (file.write((uint8_t *)&c.name, 32) == 32);
-      success = success && (file.write(&c.type, 1) == 1);
-      success = success && (file.write(&c.flags, 1) == 1);
-      success = success && (file.write(&unused, 1) == 1);
-      success = success && (file.write((uint8_t *)&c.sync_since, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.out_path_len, 1) == 1);
-      success = success && (file.write((uint8_t *)&c.last_advert_timestamp, 4) == 4);
-      success = success && (file.write(c.out_path, 64) == 64);
-      success = success && (file.write((uint8_t *)&c.lastmod, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.gps_lat, 4) == 4);
-      success = success && (file.write((uint8_t *)&c.gps_lon, 4) == 4);
+  // --- Step 1: Write all contacts to a temporary file ---
+  File file = openWrite(fs, tmpPath);
+  if (!file) {
+    Serial.println("DataStore: saveContacts FAILED — cannot open tmp file");
+    return;
+  }
 
-      if (!success) break; // write failed
+  uint32_t idx = 0;
+  ContactInfo c;
+  uint8_t unused = 0;
+  uint32_t recordsWritten = 0;
+  bool writeOk = true;
 
-      idx++;  // advance to next contact
+  while (host->getContactForSave(idx, c)) {
+    bool success = (file.write(c.id.pub_key, 32) == 32);
+    success = success && (file.write((uint8_t *)&c.name, 32) == 32);
+    success = success && (file.write(&c.type, 1) == 1);
+    success = success && (file.write(&c.flags, 1) == 1);
+    success = success && (file.write(&unused, 1) == 1);
+    success = success && (file.write((uint8_t *)&c.sync_since, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.out_path_len, 1) == 1);
+    success = success && (file.write((uint8_t *)&c.last_advert_timestamp, 4) == 4);
+    success = success && (file.write(c.out_path, 64) == 64);
+    success = success && (file.write((uint8_t *)&c.lastmod, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.gps_lat, 4) == 4);
+    success = success && (file.write((uint8_t *)&c.gps_lon, 4) == 4);
+
+    if (!success) {
+      writeOk = false;
+      Serial.printf("DataStore: saveContacts write error at record %d\n", idx);
+      break;
     }
-    file.close();
+
+    recordsWritten++;
+    idx++;
+  }
+
+  file.close();
+
+  // --- Step 2: Verify the write completed ---
+  // Reopen read-only to get true on-disk size (SPIFFS file.size() is unreliable before close)
+  size_t expectedBytes = recordsWritten * 152;  // 152 bytes per contact record
+  File verify = openRead(fs, tmpPath);
+  size_t bytesWritten = verify ? verify.size() : 0;
+  if (verify) verify.close();
+
+  if (!writeOk || bytesWritten != expectedBytes) {
+    Serial.printf("DataStore: saveContacts ABORTED — wrote %d bytes, expected %d (%d records)\n",
+                  (int)bytesWritten, (int)expectedBytes, recordsWritten);
+    fs->remove(tmpPath);  // Clean up failed tmp file
+    return;  // Original /contacts3 is untouched
+  }
+
+  // --- Step 3: Replace original with verified temp file ---
+  fs->remove(finalPath);
+  if (fs->rename(tmpPath, finalPath)) {
+    Serial.printf("DataStore: saved %d contacts (%d bytes)\n", recordsWritten, (int)bytesWritten);
+  } else {
+    // Rename failed — tmp file still has the good data
+    Serial.println("DataStore: rename failed, tmp file preserved");
+  }
+}
+
+// =========================================================================
+// Chunked contact save — non-blocking across multiple loop iterations
+// =========================================================================
+
+bool DataStore::beginSaveContacts(DataStoreHost* host) {
+  if (_saveInProgress) return false;  // Already saving
+
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  _saveFile = openWrite(fs, "/contacts3.tmp");
+  if (!_saveFile) {
+    Serial.println("DataStore: chunked save FAILED — cannot open tmp file");
+    return false;
+  }
+
+  _saveHost = host;
+  _saveIdx = 0;
+  _saveRecordsWritten = 0;
+  _saveWriteOk = true;
+  _saveInProgress = true;
+  Serial.println("DataStore: chunked save started");
+  return true;
+}
+
+bool DataStore::saveContactsChunk(int batchSize) {
+  if (!_saveInProgress || !_saveWriteOk) return false;
+
+  ContactInfo c;
+  uint8_t unused = 0;
+  int written = 0;
+
+  while (written < batchSize && _saveHost->getContactForSave(_saveIdx, c)) {
+    bool success = (_saveFile.write(c.id.pub_key, 32) == 32);
+    success = success && (_saveFile.write((uint8_t *)&c.name, 32) == 32);
+    success = success && (_saveFile.write(&c.type, 1) == 1);
+    success = success && (_saveFile.write(&c.flags, 1) == 1);
+    success = success && (_saveFile.write(&unused, 1) == 1);
+    success = success && (_saveFile.write((uint8_t *)&c.sync_since, 4) == 4);
+    success = success && (_saveFile.write((uint8_t *)&c.out_path_len, 1) == 1);
+    success = success && (_saveFile.write((uint8_t *)&c.last_advert_timestamp, 4) == 4);
+    success = success && (_saveFile.write(c.out_path, 64) == 64);
+    success = success && (_saveFile.write((uint8_t *)&c.lastmod, 4) == 4);
+    success = success && (_saveFile.write((uint8_t *)&c.gps_lat, 4) == 4);
+    success = success && (_saveFile.write((uint8_t *)&c.gps_lon, 4) == 4);
+
+    if (!success) {
+      _saveWriteOk = false;
+      Serial.printf("DataStore: chunked save write error at record %d\n", _saveIdx);
+      return false;  // Error — finishSaveContacts will clean up
+    }
+
+    _saveRecordsWritten++;
+    _saveIdx++;
+    written++;
+  }
+
+  // Check if there are more contacts to write
+  ContactInfo peek;
+  if (_saveHost->getContactForSave(_saveIdx, peek)) {
+    return true;  // More to write
+  }
+  return false;  // Done
+}
+
+void DataStore::finishSaveContacts() {
+  if (!_saveInProgress) return;
+
+  _saveFile.close();
+  _saveInProgress = false;
+
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  const char* finalPath = "/contacts3";
+  const char* tmpPath   = "/contacts3.tmp";
+
+  // Verify
+  size_t expectedBytes = _saveRecordsWritten * 152;
+  File verify = openRead(fs, tmpPath);
+  size_t bytesWritten = verify ? verify.size() : 0;
+  if (verify) verify.close();
+
+  if (!_saveWriteOk || bytesWritten != expectedBytes) {
+    Serial.printf("DataStore: chunked save ABORTED — wrote %d bytes, expected %d (%d records)\n",
+                  (int)bytesWritten, (int)expectedBytes, _saveRecordsWritten);
+    fs->remove(tmpPath);
+    return;
+  }
+
+  fs->remove(finalPath);
+  if (fs->rename(tmpPath, finalPath)) {
+    Serial.printf("DataStore: saved %d contacts (%d bytes, chunked)\n",
+                  _saveRecordsWritten, (int)bytesWritten);
+  } else {
+    Serial.println("DataStore: rename failed, tmp file preserved");
   }
 }
 
 void DataStore::loadChannels(DataStoreHost* host) {
-    File file = openRead(_getContactsChannelsFS(), "/channels2");
+    FILESYSTEM* fs = _getContactsChannelsFS();
+
+    // Crash recovery (same pattern as contacts)
+    if (!fs->exists("/channels2") && fs->exists("/channels2.tmp")) {
+      Serial.println("DataStore: recovering channels from .tmp file");
+      fs->rename("/channels2.tmp", "/channels2");
+    }
+    if (fs->exists("/channels2.tmp")) {
+      fs->remove("/channels2.tmp");
+    }
+
+    File file = openRead(fs, "/channels2");
     if (file) {
       bool full = false;
       uint8_t channel_idx = 0;
@@ -354,22 +628,54 @@ void DataStore::loadChannels(DataStoreHost* host) {
 }
 
 void DataStore::saveChannels(DataStoreHost* host) {
-  File file = openWrite(_getContactsChannelsFS(), "/channels2");
-  if (file) {
-    uint8_t channel_idx = 0;
-    ChannelDetails ch;
-    uint8_t unused[4];
-    memset(unused, 0, 4);
+  FILESYSTEM* fs = _getContactsChannelsFS();
+  const char* finalPath = "/channels2";
+  const char* tmpPath   = "/channels2.tmp";
 
-    while (host->getChannelForSave(channel_idx, ch)) {
-      bool success = (file.write(unused, 4) == 4);
-      success = success && (file.write((uint8_t *)ch.name, 32) == 32);
-      success = success && (file.write((uint8_t *)ch.channel.secret, 32) == 32);
+  File file = openWrite(fs, tmpPath);
+  if (!file) {
+    Serial.println("DataStore: saveChannels FAILED — cannot open tmp file");
+    return;
+  }
 
-      if (!success) break; // write failed
-      channel_idx++;
+  uint8_t channel_idx = 0;
+  ChannelDetails ch;
+  uint8_t unused[4];
+  memset(unused, 0, 4);
+  bool writeOk = true;
+
+  while (host->getChannelForSave(channel_idx, ch)) {
+    bool success = (file.write(unused, 4) == 4);
+    success = success && (file.write((uint8_t *)ch.name, 32) == 32);
+    success = success && (file.write((uint8_t *)ch.channel.secret, 32) == 32);
+
+    if (!success) {
+      writeOk = false;
+      Serial.printf("DataStore: saveChannels write error at channel %d\n", channel_idx);
+      break;
     }
-    file.close();
+    channel_idx++;
+  }
+
+  file.close();
+
+  // Reopen read-only to get true on-disk size (SPIFFS file.size() is unreliable before close)
+  size_t expectedBytes = channel_idx * 68;  // 4 + 32 + 32 = 68 bytes per channel
+  File verify = openRead(fs, tmpPath);
+  size_t bytesWritten = verify ? verify.size() : 0;
+  if (verify) verify.close();
+  if (!writeOk || bytesWritten != expectedBytes) {
+    Serial.printf("DataStore: saveChannels ABORTED — wrote %d bytes, expected %d\n",
+                  (int)bytesWritten, (int)expectedBytes);
+    fs->remove(tmpPath);
+    return;
+  }
+
+  fs->remove(finalPath);
+  if (fs->rename(tmpPath, finalPath)) {
+    Serial.printf("DataStore: saved %d channels (%d bytes)\n", channel_idx, (int)bytesWritten);
+  } else {
+    Serial.println("DataStore: channels rename failed, tmp file preserved");
   }
 }
 
@@ -598,4 +904,4 @@ bool DataStore::putBlobByKey(const uint8_t key[], int key_len, const uint8_t src
   }
   return false; // error
 }
-#endif
+#endif

examples/companion_radio/DataStore.h

@@ -24,6 +24,14 @@ class DataStore {
   void checkAdvBlobFile();
 #endif
 
+  // Chunked save state
+  File _saveFile;
+  DataStoreHost* _saveHost = nullptr;
+  uint32_t _saveIdx = 0;
+  uint32_t _saveRecordsWritten = 0;
+  bool _saveInProgress = false;
+  bool _saveWriteOk = true;
+
 public:
   DataStore(FILESYSTEM& fs, mesh::RTCClock& clock);
   DataStore(FILESYSTEM& fs, FILESYSTEM& fsExtra, mesh::RTCClock& clock);
@@ -37,6 +45,14 @@ public:
   void savePrefs(const NodePrefs& prefs, double node_lat, double node_lon);
   void loadContacts(DataStoreHost* host);
   void saveContacts(DataStoreHost* host);
+  // Chunked save — splits contact write across multiple loop iterations
+  // to prevent blocking the main loop for 500ms+ on large contact lists.
+  // Call beginSaveContacts(), then saveContactsChunk() each loop until it
+  // returns false (done), then finishSaveContacts() to verify and commit.
+  bool beginSaveContacts(DataStoreHost* host);
+  bool saveContactsChunk(int batchSize = 20);  // returns true if more to write
+  void finishSaveContacts();
+  bool isSaveInProgress() const { return _saveInProgress; }
   void loadChannels(DataStoreHost* host);
   void saveChannels(DataStoreHost* host);
   void migrateToSecondaryFS();
@@ -51,4 +67,4 @@ public:
 
 private:
   FILESYSTEM* _getContactsChannelsFS() const { if (_fsExtra) return _fsExtra; return _fs;};
-};
+};

examples/companion_radio/MyMesh.h

@@ -5,14 +5,14 @@
 #include "AbstractUITask.h"
 
 /*------------ Frame Protocol --------------*/
-#define FIRMWARE_VER_CODE 8
+#define FIRMWARE_VER_CODE 10
 
 #ifndef FIRMWARE_BUILD_DATE
-#define FIRMWARE_BUILD_DATE "2 Feb 2026"
+#define FIRMWARE_BUILD_DATE "28 March 2026"
 #endif
 
 #ifndef FIRMWARE_VERSION
-#define FIRMWARE_VERSION "Meck v0.6.1"
+#define FIRMWARE_VERSION "Meck v1.5"
 #endif
 
 #if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM)
@@ -79,11 +79,22 @@
 struct AdvertPath {
   uint8_t pubkey_prefix[7];
   uint8_t path_len;
+  uint8_t type;             // ADV_TYPE_* (Chat/Repeater/Room/Sensor)
   char    name[32];
   uint32_t recv_timestamp;
   uint8_t path[MAX_PATH_SIZE];
 };
 
+// Discovery scan — transient buffer for on-device node discovery
+#define MAX_DISCOVERED_NODES 20
+
+struct DiscoveredNode {
+  ContactInfo contact;
+  uint8_t path_len;
+  int8_t snr;                 // SNR × 4 from active discovery response (0 if pre-seeded)
+  bool already_in_contacts;   // true if contact was auto-added or already known
+};
+
 class MyMesh : public BaseChatMesh, public DataStoreHost {
 public:
   MyMesh(mesh::Radio &radio, mesh::RNG &rng, mesh::RTCClock &rtc, SimpleMeshTables &tables, DataStore& store, AbstractUITask* ui=NULL);
@@ -101,17 +112,48 @@ public:
   void enterCLIRescue();
 
   int  getRecentlyHeard(AdvertPath dest[], int max_num);
+
+  // Discovery scan — on-device node discovery
+  void startDiscovery(uint32_t duration_ms = 30000);
+  void stopDiscovery();
+  bool isDiscoveryActive() const { return _discoveryActive; }
+  int  getDiscoveredCount() const { return _discoveredCount; }
+  const DiscoveredNode& getDiscovered(int idx) const { return _discovered[idx]; }
+  bool addDiscoveredToContacts(int idx);  // promote a discovered node into contacts
+
+  // Last Heard — public wrappers for contact add/remove from UI
+  void scheduleLazyContactSave();
+  int getContactBlob(const uint8_t key[], int key_len, uint8_t dest_buf[]) {
+    return getBlobByKey(key, key_len, dest_buf);
+  }
   
   // Queue a sent channel message for BLE app sync
   void queueSentChannelMessage(uint8_t channel_idx, uint32_t timestamp, const char* sender, const char* text);
 
+  // Send a direct message from the UI (no BLE dependency)
+  bool uiSendDirectMessage(uint32_t contact_idx, const char* text);
+
+  // Repeater admin - UI-initiated operations
+  bool uiLoginToRepeater(uint32_t contact_idx, const char* password, uint32_t& est_timeout_ms);
+  bool uiSendCliCommand(uint32_t contact_idx, const char* command);
+  bool uiSendTelemetryRequest(uint32_t contact_idx);
+  int  getAdminContactIdx() const { return _admin_contact_idx; }
+
+
 protected:
   float getAirtimeBudgetFactor() const override;
   int getInterferenceThreshold() const override;
+  uint8_t getTxFailResetThreshold() const override;
+  uint8_t getRxFailRebootThreshold() const override;
+  void onRxUnrecoverable() override;
   int calcRxDelay(float score, uint32_t air_time) const override;
+  uint32_t getRetransmitDelay(const mesh::Packet *packet) override;
+  uint32_t getDirectRetransmitDelay(const mesh::Packet *packet) override;
   uint8_t getExtraAckTransmitCount() const override;
+  uint8_t getAutoAddMaxHops() const override;
   bool filterRecvFloodPacket(mesh::Packet* packet) override;
 
+  uint8_t getPathHashSize() const override { return _prefs.path_hash_mode + 1; }
   void sendFloodScoped(const ContactInfo& recipient, mesh::Packet* pkt, uint32_t delay_millis=0) override;
   void sendFloodScoped(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t delay_millis=0) override;
 
@@ -161,6 +203,12 @@ protected:
 
 public:
   void savePrefs() { _store->savePrefs(_prefs, sensors.node_lat, sensors.node_lon); }
+  void saveChannels() {
+    _store->saveChannels(this);
+  }
+  void saveContacts() {
+    _store->saveContacts(this);
+  }
 
 private:
   void writeOKFrame();
@@ -180,10 +228,6 @@ private:
   void checkCLIRescueCmd();
   void checkSerialInterface();
 
-  // helpers, short-cuts
-  void saveChannels() { _store->saveChannels(this); }
-  void saveContacts() { _store->saveContacts(this); }
-
   DataStore* _store;
   NodePrefs _prefs;
   uint32_t pending_login;
@@ -229,8 +273,29 @@ private:
   AckTableEntry expected_ack_table[EXPECTED_ACK_TABLE_SIZE]; // circular table
   int next_ack_idx;
 
-  #define ADVERT_PATH_TABLE_SIZE   16
+  #define ADVERT_PATH_TABLE_SIZE   40
   AdvertPath advert_paths[ADVERT_PATH_TABLE_SIZE]; // circular table
+
+    // Sent message repeat tracking
+  #define SENT_TRACK_SIZE          4
+  #define SENT_FINGERPRINT_SIZE    12
+  #define SENT_TRACK_EXPIRY_MS     30000  // stop tracking after 30 seconds
+  struct SentMsgTrack {
+    uint8_t fingerprint[SENT_FINGERPRINT_SIZE];
+    uint8_t repeat_count;
+    unsigned long sent_millis;
+    bool active;
+  };
+  SentMsgTrack _sent_track[SENT_TRACK_SIZE];
+  int _sent_track_idx;  // next slot in circular buffer
+  int _admin_contact_idx;  // contact index for active admin session (-1 if none)
+
+  // Discovery scan state
+  DiscoveredNode _discovered[MAX_DISCOVERED_NODES];
+  int _discoveredCount;
+  bool _discoveryActive;
+  unsigned long _discoveryTimeout;
+  uint32_t _discoveryTag;      // random correlation tag for active discovery
 };
 
 extern MyMesh the_mesh;

examples/companion_radio/NodePrefs.h

@@ -28,4 +28,52 @@ struct NodePrefs {  // persisted to file
   uint8_t  gps_enabled;      // GPS enabled flag (0=disabled, 1=enabled)
   uint32_t gps_interval;     // GPS read interval in seconds
   uint8_t autoadd_config;    // bitmask for auto-add contacts config
+  int8_t  utc_offset_hours;  // UTC offset in hours (-12 to +14), default 0
+  uint8_t kb_flash_notify;   // Keyboard backlight flash on new message (0=off, 1=on)
+  uint8_t ringtone_enabled;  // Ringtone on incoming call (0=off, 1=on) — 4G only
+  uint8_t path_hash_mode;    // 0=1-byte (legacy), 1=2-byte, 2=3-byte path hashes
+  uint8_t autoadd_max_hops;  // 0=no limit, N=up to N-1 hops (max 64)
+  uint32_t gps_baudrate;     // GPS baud rate (0 = use compile-time GPS_BAUDRATE default)
+  uint8_t interference_threshold; // Interference threshold in dB (0=disabled, 14+=enabled)
+  uint8_t dark_mode;              // 0=off (white bg), 1=on (black bg)
+  uint8_t portrait_mode;          // 0=landscape, 1=portrait — T5S3 only
+  uint8_t auto_lock_minutes;      // 0=disabled, 2/5/10/15/30=auto-lock after idle
+  uint8_t hint_shown;             // 0=show nav hint on boot, 1=already shown (dismiss permanently)
+  uint8_t large_font;             // 0=tiny (built-in 6x8), 1=larger (FreeSans9pt) — T-Deck Pro only
+  uint8_t tx_fail_reset_threshold;  // 0=disabled, 1-10, default 3
+  uint8_t rx_fail_reboot_threshold; // 0=disabled, 1-10, default 3
+
+  // --- Font helpers (inline, no overhead) ---
+  // Returns the DisplayDriver text-size index for "small/body" text.
+  // T-Deck Pro: 0 = built-in 6×8, 1 = FreeSans9pt.
+  // T5S3: both 0 and 1 are 12pt fonts (regular vs bold) with identical line
+  //        height, so large_font has no layout effect there.
+  inline uint8_t smallTextSize() const {
+    return large_font ? 1 : 0;
+  }
+
+  // Returns the virtual-coordinate line height matching smallTextSize().
+  // T-Deck Pro size 0 → 9 (6×8 + 1px gap), size 1 → 11 (9pt ascent+descent).
+  // T5S3 size 0/1 → same 12pt height → always 9 in virtual coords.
+  inline int smallLineH() const {
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    return 9;
+#else
+    return large_font ? 11 : 9;
+#endif
+  }
+
+  // Returns the Y offset for selection highlight fillRect (T-Deck Pro only).
+  // Size 0 (built-in font): cursor positions at top-left, +5 offset in
+  //   setCursor places text below → fillRect at y+5 aligns with text.
+  // Size 1 (FreeSans9pt): cursor positions at baseline, ascenders render
+  //   upward → fillRect must start above baseline to cover ascenders.
+  // T5S3: always 0 (both sizes use baseline fonts with highlight at y).
+  inline int smallHighlightOff() const {
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    return 0;
+#else
+    return large_font ? -2 : 5;
+#endif
+  }
 };

examples/companion_radio/ui-new/ApnDatabase.h

@@ -0,0 +1,372 @@
+#pragma once
+
+// =============================================================================
+// ApnDatabase.h - Embedded APN Lookup Table
+//
+// Maps MCC/MNC (Mobile Country Code / Mobile Network Code) to default APN
+// settings for common carriers worldwide. Compiled directly into flash (~3KB)
+// so users never need to manually install a lookup file.
+//
+// The modem queries IMSI via AT+CIMI to extract MCC (3 digits) + MNC (2-3
+// digits), then looks up the APN here. If not found, falls back to the
+// modem's existing PDP context (AT+CGDCONT?) or user-configured APN.
+//
+// To add a carrier: append to APN_DATABASE[] with the MCC+MNC as a single
+// integer.  MNC can be 2 or 3 digits:
+//   MCC=310, MNC=260  → mccmnc = 310260
+//   MCC=505, MNC=01   → mccmnc = 50501
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef APN_DATABASE_H
+#define APN_DATABASE_H
+
+struct ApnEntry {
+  uint32_t mccmnc;        // MCC+MNC as integer (e.g. 310260 for T-Mobile US)
+  const char* apn;        // APN string
+  const char* carrier;    // Human-readable carrier name (for debug/display)
+};
+
+// ---------------------------------------------------------------------------
+// APN Database — sorted by MCC for binary search potential (not required)
+//
+// Sources: carrier documentation, GSMA databases, community wikis.
+// This covers ~120 major carriers across key regions. Users with less
+// common carriers can set APN manually in Settings.
+// ---------------------------------------------------------------------------
+
+static const ApnEntry APN_DATABASE[] = {
+  // =========================================================================
+  // Australia (MCC 505)
+  // =========================================================================
+  { 50501,  "telstra.internet",    "Telstra" },
+  { 50502,  "yesinternet",         "Optus" },
+  { 50503,  "vfinternet.au",       "Vodafone AU" },
+  { 50506,  "3netaccess",          "Three AU" },
+  { 50507,  "telstra.internet",    "Vodafone AU (MVNO)" },  // Many MVNOs on Telstra
+  { 50510,  "telstra.internet",    "Norfolk Tel" },
+  { 50512,  "3netaccess",          "Amaysim" },              // Optus MVNO
+  { 50514,  "yesinternet",         "Aussie Broadband" },     // Optus MVNO
+  { 50590,  "yesinternet",         "Optus MVNO" },
+
+  // =========================================================================
+  // New Zealand (MCC 530)
+  // =========================================================================
+  { 53001,  "internet",            "Vodafone NZ" },
+  { 53005,  "internet",            "Spark NZ" },
+  { 53024,  "internet",            "2degrees" },
+
+  // =========================================================================
+  // United States (MCC 310, 311, 312, 313, 316)
+  // =========================================================================
+  { 310012, "fast.t-mobile.com",   "Verizon (old)" },
+  { 310026, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310030, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310032, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310060, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310160, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310200, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310210, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310220, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310230, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310240, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310250, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310260, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310270, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310310, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310490, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310530, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310580, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310660, "fast.t-mobile.com",   "T-Mobile US" },
+  { 310800, "fast.t-mobile.com",   "T-Mobile US" },
+  { 311480, "vzwinternet",         "Verizon" },
+  { 311481, "vzwinternet",         "Verizon" },
+  { 311482, "vzwinternet",         "Verizon" },
+  { 311483, "vzwinternet",         "Verizon" },
+  { 311484, "vzwinternet",         "Verizon" },
+  { 311489, "vzwinternet",         "Verizon" },
+  { 310410, "fast.t-mobile.com",   "AT&T (migrated)" },
+  { 310120, "att.mvno",            "AT&T (Sprint)" },
+  { 312530, "iot.1nce.net",        "1NCE IoT" },
+  { 310120, "tfdata",              "Tracfone" },
+
+  // =========================================================================
+  // Canada (MCC 302)
+  // =========================================================================
+  { 30220,  "internet.com",        "Rogers" },
+  { 30221,  "internet.com",        "Rogers" },
+  { 30237,  "internet.com",        "Rogers" },
+  { 30272,  "internet.com",        "Rogers" },
+  { 30234,  "sp.telus.com",        "Telus" },
+  { 30286,  "sp.telus.com",        "Telus" },
+  { 30236,  "sp.telus.com",        "Telus" },
+  { 30261,  "sp.bell.ca",          "Bell" },
+  { 30263,  "sp.bell.ca",          "Bell" },
+  { 30267,  "sp.bell.ca",          "Bell" },
+  { 30268,  "fido-core-appl1.apn", "Fido" },
+  { 30278,  "internet.com",        "SaskTel" },
+  { 30266,  "sp.mb.com",           "MTS" },
+
+  // =========================================================================
+  // United Kingdom (MCC 234, 235)
+  // =========================================================================
+  { 23410,  "o2-internet",         "O2 UK" },
+  { 23415,  "three.co.uk",         "Vodafone UK" },
+  { 23420,  "three.co.uk",         "Three UK" },
+  { 23430,  "everywhere",          "EE" },
+  { 23431,  "everywhere",          "EE" },
+  { 23432,  "everywhere",          "EE" },
+  { 23433,  "everywhere",          "EE" },
+  { 23450,  "data.lycamobile.co.uk","Lycamobile UK" },
+  { 23486,  "three.co.uk",         "Three UK" },
+
+  // =========================================================================
+  // Germany (MCC 262)
+  // =========================================================================
+  { 26201,  "internet.t-mobile",   "Telekom DE" },
+  { 26202,  "web.vodafone.de",     "Vodafone DE" },
+  { 26203,  "internet",            "O2 DE" },
+  { 26207,  "internet",            "O2 DE" },
+
+  // =========================================================================
+  // France (MCC 208)
+  // =========================================================================
+  { 20801,  "orange",              "Orange FR" },
+  { 20810,  "sl2sfr",              "SFR" },
+  { 20815,  "free",                "Free Mobile" },
+  { 20820,  "ofnew.fr",            "Bouygues" },
+
+  // =========================================================================
+  // Italy (MCC 222)
+  // =========================================================================
+  { 22201,  "mobile.vodafone.it",  "TIM" },
+  { 22210,  "mobile.vodafone.it",  "Vodafone IT" },
+  { 22250,  "internet.it",         "Iliad IT" },
+  { 22288,  "internet.wind",       "WindTre" },
+  { 22299,  "internet.wind",       "WindTre" },
+
+  // =========================================================================
+  // Spain (MCC 214)
+  // =========================================================================
+  { 21401,  "internet",            "Vodafone ES" },
+  { 21403,  "internet",            "Orange ES" },
+  { 21404,  "internet",            "Yoigo" },
+  { 21407,  "internet",            "Movistar" },
+
+  // =========================================================================
+  // Netherlands (MCC 204)
+  // =========================================================================
+  { 20404,  "internet",            "Vodafone NL" },
+  { 20408,  "internet",            "KPN" },
+  { 20412,  "internet",            "Telfort" },
+  { 20416,  "internet",            "T-Mobile NL" },
+  { 20420,  "internet",            "T-Mobile NL" },
+
+  // =========================================================================
+  // Sweden (MCC 240)
+  // =========================================================================
+  { 24001,  "internet.telia.se",   "Telia SE" },
+  { 24002,  "tre.se",              "Three SE" },
+  { 24007,  "internet.telenor.se", "Telenor SE" },
+
+  // =========================================================================
+  // Norway (MCC 242)
+  // =========================================================================
+  { 24201,  "internet.telenor.no", "Telenor NO" },
+  { 24202,  "internet.netcom.no",  "Telia NO" },
+
+  // =========================================================================
+  // Denmark (MCC 238)
+  // =========================================================================
+  { 23801,  "internet",            "TDC" },
+  { 23802,  "internet",            "Telenor DK" },
+  { 23806,  "internet",            "Three DK" },
+  { 23820,  "internet",            "Telia DK" },
+
+  // =========================================================================
+  // Switzerland (MCC 228)
+  // =========================================================================
+  { 22801,  "gprs.swisscom.ch",    "Swisscom" },
+  { 22802,  "internet",            "Sunrise" },
+  { 22803,  "internet",            "Salt" },
+
+  // =========================================================================
+  // Austria (MCC 232)
+  // =========================================================================
+  { 23201,  "a1.net",              "A1" },
+  { 23203,  "web.one.at",          "Three AT" },
+  { 23205,  "web",                 "T-Mobile AT" },
+
+  // =========================================================================
+  // Japan (MCC 440, 441)
+  // =========================================================================
+  { 44010,  "spmode.ne.jp",        "NTT Docomo" },
+  { 44020,  "plus.4g",             "SoftBank" },
+  { 44051,  "au.au-net.ne.jp",     "KDDI au" },
+
+  // =========================================================================
+  // South Korea (MCC 450)
+  // =========================================================================
+  { 45005,  "lte.sktelecom.com",   "SK Telecom" },
+  { 45006,  "lte.ktfwing.com",     "KT" },
+  { 45008,  "lte.lguplus.co.kr",   "LG U+" },
+
+  // =========================================================================
+  // India (MCC 404, 405)
+  // =========================================================================
+  { 40445,  "airtelgprs.com",      "Airtel" },
+  { 40410,  "airtelgprs.com",      "Airtel" },
+  { 40411,  "www",                 "Vodafone IN (Vi)" },
+  { 40413,  "www",                 "Vodafone IN (Vi)" },
+  { 40486,  "www",                 "Vodafone IN (Vi)" },
+  { 40553,  "jionet",              "Jio" },
+  { 40554,  "jionet",              "Jio" },
+  { 40512,  "bsnlnet",             "BSNL" },
+
+  // =========================================================================
+  // Singapore (MCC 525)
+  // =========================================================================
+  { 52501,  "internet",            "Singtel" },
+  { 52503,  "internet",            "M1" },
+  { 52505,  "internet",            "StarHub" },
+
+  // =========================================================================
+  // Hong Kong (MCC 454)
+  // =========================================================================
+  { 45400,  "internet",            "CSL" },
+  { 45406,  "internet",            "SmarTone" },
+  { 45412,  "internet",            "CMHK" },
+
+  // =========================================================================
+  // Brazil (MCC 724)
+  // =========================================================================
+  { 72405,  "claro.com.br",        "Claro BR" },
+  { 72406,  "wap.oi.com.br",       "Vivo" },
+  { 72410,  "wap.oi.com.br",       "Vivo" },
+  { 72411,  "wap.oi.com.br",       "Vivo" },
+  { 72415,  "internet.tim.br",     "TIM BR" },
+  { 72431,  "gprs.oi.com.br",      "Oi" },
+
+  // =========================================================================
+  // Mexico (MCC 334)
+  // =========================================================================
+  { 33402,  "internet.itelcel.com","Telcel" },
+  { 33403,  "internet.movistar.mx","Movistar MX" },
+  { 33404,  "internet.att.net.mx", "AT&T MX" },
+
+  // =========================================================================
+  // South Africa (MCC 655)
+  // =========================================================================
+  { 65501,  "internet",            "Vodacom" },
+  { 65502,  "internet",            "Telkom ZA" },
+  { 65507,  "internet",            "Cell C" },
+  { 65510,  "internet",            "MTN ZA" },
+
+  // =========================================================================
+  // Philippines (MCC 515)
+  // =========================================================================
+  { 51502,  "internet.globe.com.ph","Globe" },
+  { 51503,  "internet",            "Smart" },
+  { 51505,  "internet",            "Sun Cellular" },
+
+  // =========================================================================
+  // Thailand (MCC 520)
+  // =========================================================================
+  { 52001,  "internet",            "AIS" },
+  { 52004,  "internet",            "TrueMove" },
+  { 52005,  "internet",            "dtac" },
+
+  // =========================================================================
+  // Indonesia (MCC 510)
+  // =========================================================================
+  { 51001,  "internet",            "Telkomsel" },
+  { 51010,  "internet",            "Telkomsel" },
+  { 51011,  "3gprs",               "XL Axiata" },
+  { 51028,  "3gprs",               "XL Axiata (Axis)" },
+
+  // =========================================================================
+  // Malaysia (MCC 502)
+  // =========================================================================
+  { 50212,  "celcom3g",            "Celcom" },
+  { 50213,  "celcom3g",            "Celcom" },
+  { 50216,  "internet",            "Digi" },
+  { 50219,  "celcom3g",            "Celcom" },
+
+  // =========================================================================
+  // Czech Republic (MCC 230)
+  // =========================================================================
+  { 23001,  "internet.t-mobile.cz","T-Mobile CZ" },
+  { 23002,  "internet",            "O2 CZ" },
+  { 23003,  "internet.vodafone.cz","Vodafone CZ" },
+
+  // =========================================================================
+  // Poland (MCC 260)
+  // =========================================================================
+  { 26001,  "internet",            "Plus PL" },
+  { 26002,  "internet",            "T-Mobile PL" },
+  { 26003,  "internet",            "Orange PL" },
+  { 26006,  "internet",            "Play" },
+
+  // =========================================================================
+  // Portugal (MCC 268)
+  // =========================================================================
+  { 26801,  "internet",            "Vodafone PT" },
+  { 26803,  "internet",            "NOS" },
+  { 26806,  "internet",            "MEO" },
+
+  // =========================================================================
+  // Ireland (MCC 272)
+  // =========================================================================
+  { 27201,  "internet",            "Vodafone IE" },
+  { 27202,  "open.internet",       "Three IE" },
+  { 27205,  "three.ie",            "Three IE" },
+
+  // =========================================================================
+  // IoT / Global SIMs
+  // =========================================================================
+  { 901028, "iot.1nce.net",        "1NCE (IoT)" },
+  { 90143,  "hologram",            "Hologram" },
+};
+
+#define APN_DATABASE_SIZE (sizeof(APN_DATABASE) / sizeof(APN_DATABASE[0]))
+
+// ---------------------------------------------------------------------------
+// Lookup function — returns nullptr if not found
+// ---------------------------------------------------------------------------
+
+inline const ApnEntry* apnLookup(uint32_t mccmnc) {
+  for (int i = 0; i < (int)APN_DATABASE_SIZE; i++) {
+    if (APN_DATABASE[i].mccmnc == mccmnc) {
+      return &APN_DATABASE[i];
+    }
+  }
+  return nullptr;
+}
+
+// Parse IMSI string into MCC+MNC.  Tries 3-digit MNC first (6-digit mccmnc),
+// falls back to 2-digit MNC (5-digit mccmnc) if not found.
+inline const ApnEntry* apnLookupFromIMSI(const char* imsi) {
+  if (!imsi || strlen(imsi) < 5) return nullptr;
+
+  // Extract MCC (always 3 digits)
+  uint32_t mcc = (imsi[0] - '0') * 100 + (imsi[1] - '0') * 10 + (imsi[2] - '0');
+
+  // Try 3-digit MNC first (more specific)
+  if (strlen(imsi) >= 6) {
+    uint32_t mnc3 = (imsi[3] - '0') * 100 + (imsi[4] - '0') * 10 + (imsi[5] - '0');
+    uint32_t mccmnc6 = mcc * 1000 + mnc3;
+    const ApnEntry* entry = apnLookup(mccmnc6);
+    if (entry) return entry;
+  }
+
+  // Fall back to 2-digit MNC
+  uint32_t mnc2 = (imsi[3] - '0') * 10 + (imsi[4] - '0');
+  uint32_t mccmnc5 = mcc * 100 + mnc2;
+  return apnLookup(mccmnc5);
+}
+
+#endif // APN_DATABASE_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/CardKBKeyboard.h

@@ -0,0 +1,122 @@
+#pragma once
+// =============================================================================
+// CardKBKeyboard — M5Stack CardKB (or compatible) I2C keyboard driver
+//
+// Polls 0x5F on the shared I2C bus via QWIIC connector.
+// Maps CardKB special key codes to Meck key constants.
+//
+// Usage:
+//   CardKBKeyboard cardkb;
+//   if (cardkb.begin()) { /* detected */ }
+//   char key = cardkb.readKey();  // returns 0 if no key
+// =============================================================================
+
+#if defined(LilyGo_T5S3_EPaper_Pro) && defined(MECK_CARDKB)
+#ifndef CARDKB_KEYBOARD_H
+#define CARDKB_KEYBOARD_H
+
+#include <Arduino.h>
+#include <Wire.h>
+#include "variant.h"  // For I2C_SDA, I2C_SCL (bus recovery)
+
+// I2C address (defined in variant.h, fallback here)
+#ifndef CARDKB_I2C_ADDR
+#define CARDKB_I2C_ADDR 0x5F
+#endif
+
+// CardKB special key codes (from M5Stack documentation)
+#define CARDKB_KEY_UP      0xB5
+#define CARDKB_KEY_DOWN    0xB6
+#define CARDKB_KEY_LEFT    0xB4
+#define CARDKB_KEY_RIGHT   0xB7
+#define CARDKB_KEY_TAB     0x09
+#define CARDKB_KEY_ESC     0x1B
+#define CARDKB_KEY_BS      0x08
+#define CARDKB_KEY_ENTER   0x0D
+#define CARDKB_KEY_DEL     0x7F
+#define CARDKB_KEY_FN      0x00   // Fn modifier (swallowed by CardKB internally)
+
+class CardKBKeyboard {
+public:
+  CardKBKeyboard() : _detected(false) {}
+
+  // Probe for CardKB on the I2C bus. Call after Wire.begin().
+  bool begin() {
+    Wire.beginTransmission(CARDKB_I2C_ADDR);
+    _detected = (Wire.endTransmission() == 0);
+    if (_detected) {
+      Serial.println("[CardKB] Detected at 0x5F");
+    }
+    return _detected;
+  }
+
+  // Re-probe (e.g. for hot-plug detection every few seconds)
+  bool probe() {
+    Wire.beginTransmission(CARDKB_I2C_ADDR);
+    _detected = (Wire.endTransmission() == 0);
+    return _detected;
+  }
+
+  bool isDetected() const { return _detected; }
+
+  // Poll for a keypress. Returns 0 if no key available.
+  // Returns raw ASCII for printable chars, or Meck KEY_* constants for nav keys.
+  // Throttled to avoid flooding I2C bus — polls at most every 50ms.
+  // On read failure, backs off 500ms and re-inits Wire to recover bus state.
+  char readKey() {
+    if (!_detected) return 0;
+
+    unsigned long now = millis();
+    if (now - _lastPoll < _pollInterval) return 0;
+    _lastPoll = now;
+
+    Wire.requestFrom((uint8_t)CARDKB_I2C_ADDR, (uint8_t)1);
+    if (!Wire.available()) {
+      _errorCount++;
+      if (_errorCount >= 3) {
+        // I2C bus may be stuck — re-init to recover
+        Wire.begin(I2C_SDA, I2C_SCL);
+        Wire.setClock(100000);
+        _pollInterval = 500;  // Back off for 500ms
+        _errorCount = 0;
+        Serial.println("[CardKB] I2C error recovery — bus re-init");
+      }
+      return 0;
+    }
+
+    _errorCount = 0;
+    _pollInterval = 50;  // Normal polling rate
+
+    uint8_t raw = Wire.read();
+    if (raw == 0) return 0;
+
+    // Map CardKB special keys to Meck constants
+    switch (raw) {
+      case CARDKB_KEY_UP:    return 0xF2;  // KEY_PREV
+      case CARDKB_KEY_DOWN:  return 0xF1;  // KEY_NEXT
+      case CARDKB_KEY_LEFT:  return 0xF3;  // KEY_LEFT
+      case CARDKB_KEY_RIGHT: return 0xF4;  // KEY_RIGHT
+      case CARDKB_KEY_ENTER: return '\r';
+      case CARDKB_KEY_BS:    return '\b';
+      case CARDKB_KEY_DEL:   return '\b';  // Treat delete same as backspace
+      case CARDKB_KEY_ESC:   return 0x1B;  // ESC — handled by caller
+      case CARDKB_KEY_TAB:   return 0x09;  // Tab — available for future use
+      default:
+        // Printable ASCII — pass through unchanged
+        if (raw >= 0x20 && raw <= 0x7E) {
+          return (char)raw;
+        }
+        // Unknown code — ignore
+        return 0;
+    }
+  }
+
+private:
+  bool _detected;
+  unsigned long _lastPoll = 0;
+  unsigned long _pollInterval = 50;  // ms between polls (increases on error)
+  uint8_t _errorCount = 0;
+};
+
+#endif // CARDKB_KEYBOARD_H
+#endif // LilyGo_T5S3_EPaper_Pro && MECK_CARDKB

examples/companion_radio/ui-new/Contactsscreen.h

@@ -0,0 +1,406 @@
+#pragma once
+
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <MeshCore.h>
+
+// Forward declarations
+class UITask;
+class MyMesh;
+extern MyMesh the_mesh;
+
+class ContactsScreen : public UIScreen {
+public:
+  // Filter modes for contact type
+  enum FilterMode {
+    FILTER_ALL = 0,
+    FILTER_CHAT,       // Companions / Chat nodes
+    FILTER_REPEATER,
+    FILTER_ROOM,       // Room servers
+    FILTER_SENSOR,
+    FILTER_FAVOURITE,  // Contacts marked as favourite (any type)
+    FILTER_COUNT       // keep last
+  };
+
+private:
+  UITask* _task;
+  mesh::RTCClock* _rtc;
+
+  int _scrollPos;        // Index into filtered list (top visible row)
+  FilterMode _filter;    // Current filter mode
+
+  // Cached filtered contact indices for efficient scrolling
+  // We rebuild this on filter change or when entering the screen
+  // Arrays allocated in PSRAM when available (supports 1000+ contacts)
+  uint16_t* _filteredIdx;    // indices into contact table
+  uint32_t* _filteredTs;     // cached last_advert_timestamp for sorting
+  int _filteredCount;                  // how many contacts match current filter
+  bool _cacheValid;
+
+  // How many rows fit on screen (computed during render)
+  int _rowsPerPage;
+
+  // Pointer to per-contact DM unread array (owned by UITask, set via setter)
+  const uint8_t* _dmUnread = nullptr;
+
+  // --- helpers ---
+
+  static const char* filterLabel(FilterMode f) {
+    switch (f) {
+      case FILTER_ALL:       return "All";
+      case FILTER_CHAT:      return "Chat";
+      case FILTER_REPEATER:  return "Rptr";
+      case FILTER_ROOM:      return "Room";
+      case FILTER_SENSOR:    return "Sens";
+      case FILTER_FAVOURITE: return "Fav";
+      default:               return "?";
+    }
+  }
+
+  static char typeChar(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return 'C';
+      case ADV_TYPE_REPEATER: return 'R';
+      case ADV_TYPE_ROOM:     return 'S';  // Server
+      default:                return '?';
+    }
+  }
+
+  bool matchesFilter(uint8_t adv_type, uint8_t flags = 0) const {
+    switch (_filter) {
+      case FILTER_ALL:       return true;
+      case FILTER_CHAT:      return adv_type == ADV_TYPE_CHAT;
+      case FILTER_REPEATER:  return adv_type == ADV_TYPE_REPEATER;
+      case FILTER_ROOM:      return adv_type == ADV_TYPE_ROOM;
+      case FILTER_SENSOR:    return (adv_type != ADV_TYPE_CHAT &&
+                                     adv_type != ADV_TYPE_REPEATER &&
+                                     adv_type != ADV_TYPE_ROOM);
+      case FILTER_FAVOURITE: return (flags & 0x01) != 0;
+      default:               return true;
+    }
+  }
+
+  void rebuildCache() {
+    _filteredCount = 0;
+    uint32_t numContacts = the_mesh.getNumContacts();
+    ContactInfo contact;
+    for (uint32_t i = 0; i < numContacts && _filteredCount < MAX_CONTACTS; i++) {
+      if (the_mesh.getContactByIdx(i, contact)) {
+        if (matchesFilter(contact.type, contact.flags)) {
+          _filteredIdx[_filteredCount] = (uint16_t)i;
+          _filteredTs[_filteredCount] = contact.last_advert_timestamp;
+          _filteredCount++;
+        }
+      }
+    }
+    // Sort by last_advert_timestamp descending (most recently seen first)
+    // Insertion sort — fine for up to ~1000 entries on ESP32
+    for (int i = 1; i < _filteredCount; i++) {
+      uint16_t tmpIdx = _filteredIdx[i];
+      uint32_t tmpTs  = _filteredTs[i];
+      int j = i - 1;
+      while (j >= 0 && _filteredTs[j] < tmpTs) {
+        _filteredIdx[j + 1] = _filteredIdx[j];
+        _filteredTs[j + 1]  = _filteredTs[j];
+        j--;
+      }
+      _filteredIdx[j + 1] = tmpIdx;
+      _filteredTs[j + 1]  = tmpTs;
+    }
+    _cacheValid = true;
+    // Clamp scroll position
+    if (_scrollPos >= _filteredCount) {
+      _scrollPos = (_filteredCount > 0) ? _filteredCount - 1 : 0;
+    }
+  }
+
+  // Format seconds-ago as compact string: "3s" "5m" "2h" "4d" "??"
+  static void formatAge(char* buf, size_t bufLen, uint32_t now, uint32_t timestamp) {
+    if (timestamp == 0) {
+      strncpy(buf, "--", bufLen);
+      return;
+    }
+    int secs = (int)(now - timestamp);
+    if (secs < 0) secs = 0;
+    if (secs < 60) {
+      snprintf(buf, bufLen, "%ds", secs);
+    } else if (secs < 3600) {
+      snprintf(buf, bufLen, "%dm", secs / 60);
+    } else if (secs < 86400) {
+      snprintf(buf, bufLen, "%dh", secs / 3600);
+    } else {
+      snprintf(buf, bufLen, "%dd", secs / 86400);
+    }
+  }
+
+public:
+  ContactsScreen(UITask* task, mesh::RTCClock* rtc)
+    : _task(task), _rtc(rtc), _scrollPos(0), _filter(FILTER_ALL),
+      _filteredCount(0), _cacheValid(false), _rowsPerPage(5) {
+  #if defined(ESP32) && defined(BOARD_HAS_PSRAM)
+    _filteredIdx = (uint16_t*)ps_calloc(MAX_CONTACTS, sizeof(uint16_t));
+    _filteredTs = (uint32_t*)ps_calloc(MAX_CONTACTS, sizeof(uint32_t));
+  #else
+    _filteredIdx = new uint16_t[MAX_CONTACTS]();
+    _filteredTs = new uint32_t[MAX_CONTACTS]();
+  #endif
+  }
+
+  void invalidateCache() { _cacheValid = false; }
+
+  // Set pointer to per-contact DM unread array (called by UITask after allocation)
+  void setDMUnreadPtr(const uint8_t* ptr) { _dmUnread = ptr; }
+
+  void resetScroll() {
+    _scrollPos = 0;
+    _cacheValid = false;
+  }
+
+  FilterMode getFilter() const { return _filter; }
+
+  // Tap-to-select: given virtual Y, select contact row.
+  // Returns: 0=miss, 1=moved, 2=tapped current row.
+  int selectRowAtVY(int vy) {
+    if (_filteredCount == 0) return 0;
+    const int headerH = 14, footerH = 14, lineH = the_mesh.getNodePrefs()->smallLineH();
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    const int bodyTop = headerH;
+#else
+    const int bodyTop = headerH + the_mesh.getNodePrefs()->smallHighlightOff();
+#endif
+    if (vy < bodyTop || vy >= 128 - footerH) return 0;
+
+    int maxVisible = (128 - headerH - footerH) / lineH;
+    if (maxVisible < 3) maxVisible = 3;
+    int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                              _filteredCount - maxVisible));
+
+    int tappedRow = startIdx + (vy - bodyTop) / lineH;
+    if (tappedRow < 0 || tappedRow >= _filteredCount) return 0;
+
+    if (tappedRow == _scrollPos) return 2;
+    _scrollPos = tappedRow;
+    return 1;
+  }
+
+  // Get the raw contact table index for the currently highlighted item
+  // Returns -1 if no valid selection
+  int getSelectedContactIdx() const {
+    if (_filteredCount == 0) return -1;
+    return _filteredIdx[_scrollPos];
+  }
+
+  // Get the adv_type of the currently highlighted contact
+  // Returns 0xFF if no valid selection
+  uint8_t getSelectedContactType() const {
+    if (_filteredCount == 0) return 0xFF;
+    ContactInfo contact;
+    if (!the_mesh.getContactByIdx(_filteredIdx[_scrollPos], contact)) return 0xFF;
+    return contact.type;
+  }
+
+  // Copy the name of the currently highlighted contact into buf
+  // Returns false if no valid selection
+  bool getSelectedContactName(char* buf, size_t bufLen) const {
+    if (_filteredCount == 0) return false;
+    ContactInfo contact;
+    if (!the_mesh.getContactByIdx(_filteredIdx[_scrollPos], contact)) return false;
+    strncpy(buf, contact.name, bufLen);
+    buf[bufLen - 1] = '\0';
+    return true;
+  }
+
+  int render(DisplayDriver& display) override {
+    if (!_cacheValid) rebuildCache();
+
+    char tmp[48];
+
+    // === Header ===
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::GREEN);
+    display.setCursor(0, 0);
+    snprintf(tmp, sizeof(tmp), "Contacts [%s]", filterLabel(_filter));
+    display.print(tmp);
+
+    // Count on right: All → total/max, filtered → matched/total
+    if (_filter == FILTER_ALL) {
+      snprintf(tmp, sizeof(tmp), "%d/%d", (int)the_mesh.getNumContacts(), MAX_CONTACTS);
+    } else {
+      snprintf(tmp, sizeof(tmp), "%d/%d", _filteredCount, (int)the_mesh.getNumContacts());
+    }
+    display.setCursor(display.width() - display.getTextWidth(tmp) - 2, 0);
+    display.print(tmp);
+
+    // Divider
+    display.drawRect(0, 11, display.width(), 1);
+
+    // === Body - contact rows ===
+    display.setTextSize(the_mesh.getNodePrefs()->smallTextSize());  // tiny font for compact rows
+    int lineHeight = the_mesh.getNodePrefs()->smallLineH();      // 8px font + 1px gap
+    int headerHeight = 14;
+    int footerHeight = 14;
+    int maxY = display.height() - footerHeight;
+    int y = headerHeight;
+
+    uint32_t now = _rtc->getCurrentTime();
+    int rowsDrawn = 0;
+
+    if (_filteredCount == 0) {
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(0, y);
+      display.print("No contacts");
+      display.setCursor(0, y + lineHeight);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+      display.print("Swipe to change filter");
+#else
+      display.print("A/D: Change filter");
+#endif
+    } else {
+      // Center visible window around selected item (TextReaderScreen pattern)
+      int maxVisible = (maxY - headerHeight) / lineHeight;
+      if (maxVisible < 3) maxVisible = 3;
+      int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                                _filteredCount - maxVisible));
+      int endIdx = min(_filteredCount, startIdx + maxVisible);
+
+      for (int i = startIdx; i < endIdx && y + lineHeight <= maxY; i++) {
+        ContactInfo contact;
+        if (!the_mesh.getContactByIdx(_filteredIdx[i], contact)) continue;
+
+        bool selected = (i == _scrollPos);
+
+        // Highlight: fill LIGHT rect first, then draw DARK text on top
+        if (selected) {
+          display.setColor(DisplayDriver::LIGHT);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+          display.fillRect(0, y, display.width(), lineHeight);
+#else
+          display.fillRect(0, y + the_mesh.getNodePrefs()->smallHighlightOff(), display.width(), lineHeight);
+#endif
+          display.setColor(DisplayDriver::DARK);
+        } else {
+          display.setColor(DisplayDriver::LIGHT);
+        }
+
+        // Set cursor AFTER fillRect so text draws on top of highlight
+        display.setCursor(0, y);
+
+        // Prefix: "> " for selected, type char + space for others
+        char prefix[4];
+        if (selected) {
+          snprintf(prefix, sizeof(prefix), ">%c", typeChar(contact.type));
+        } else {
+          snprintf(prefix, sizeof(prefix), " %c", typeChar(contact.type));
+        }
+        display.print(prefix);
+
+        // Contact name (truncated to fit)
+        char filteredName[32];
+        display.translateUTF8ToBlocks(filteredName, contact.name, sizeof(filteredName));
+
+        // Reserve space for hops + age on right side
+        char hopStr[6];
+        if (contact.out_path_len == 0xFF || contact.out_path_len == 0) {
+          strcpy(hopStr, "D");  // direct
+        } else {
+          snprintf(hopStr, sizeof(hopStr), "%d", contact.out_path_len);
+        }
+
+        char ageStr[6];
+        formatAge(ageStr, sizeof(ageStr), now, contact.last_advert_timestamp);
+
+        // Build right-side string: "*N hops age" if unread, else "hops age"
+        int dmCount = (_dmUnread && _filteredIdx[i] < MAX_CONTACTS) ? _dmUnread[_filteredIdx[i]] : 0;
+        char rightStr[20];
+        if (dmCount > 0) {
+          snprintf(rightStr, sizeof(rightStr), "*%d %sh %s", dmCount, hopStr, ageStr);
+        } else {
+          snprintf(rightStr, sizeof(rightStr), "%sh %s", hopStr, ageStr);
+        }
+        int rightWidth = display.getTextWidth(rightStr) + 2;
+
+        // Name region: after prefix + small gap, before right info
+        int nameX = display.getTextWidth(prefix) + 2;
+        int nameMaxW = display.width() - nameX - rightWidth - 2;
+        display.drawTextEllipsized(nameX, y, nameMaxW, filteredName);
+
+        // Right-aligned: hops + age
+        display.setCursor(display.width() - rightWidth, y);
+        display.print(rightStr);
+
+        y += lineHeight;
+        rowsDrawn++;
+      }
+      _rowsPerPage = (rowsDrawn > 0) ? rowsDrawn : 1;
+    }
+
+    display.setTextSize(1);  // restore for footer
+
+    // === Footer ===
+    int footerY = display.height() - 12;
+    display.drawRect(0, footerY - 2, display.width(), 1);
+    display.setColor(DisplayDriver::YELLOW);
+
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    display.setCursor(0, footerY);
+    display.print("Swipe:Filter");
+    const char* right = "Hold:DM/Admin";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#else
+    // Left: Q:Bk
+    display.setCursor(0, footerY);
+    display.print("Q:Bk A/D:Filter");
+
+    // Right: Tap/Ent:Select
+    const char* right = "Tap/Ent:Select";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#endif
+
+    return 5000;  // e-ink: next render after 5s
+  }
+
+  bool handleInput(char c) override {
+    // W - scroll up (previous contact)
+    if (c == 'w' || c == 'W' || c == 0xF2) {
+      if (_scrollPos > 0) {
+        _scrollPos--;
+        return true;
+      }
+    }
+
+    // S - scroll down (next contact)
+    if (c == 's' || c == 'S' || c == 0xF1) {
+      if (_scrollPos < _filteredCount - 1) {
+        _scrollPos++;
+        return true;
+      }
+    }
+
+    // A - previous filter
+    if (c == 'a' || c == 'A') {
+      _filter = (FilterMode)(((int)_filter + FILTER_COUNT - 1) % FILTER_COUNT);
+      _scrollPos = 0;
+      _cacheValid = false;
+      return true;
+    }
+
+    // D - next filter
+    if (c == 'd' || c == 'D') {
+      _filter = (FilterMode)(((int)_filter + 1) % FILTER_COUNT);
+      _scrollPos = 0;
+      _cacheValid = false;
+      return true;
+    }
+
+    // Enter - select contact (future: open RepeaterAdmin for repeaters)
+    if (c == 13 || c == KEY_ENTER) {
+      // TODO Phase 3: if selected contact is a repeater, open RepeaterAdminScreen
+      // For now, just acknowledge the selection
+      return true;
+    }
+
+    return false;
+  }
+};

examples/companion_radio/ui-new/Discoveryscreen.h

@@ -0,0 +1,247 @@
+#pragma once
+
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <helpers/AdvertDataHelpers.h>
+#include <MeshCore.h>
+
+// Forward declarations
+class UITask;
+class MyMesh;
+extern MyMesh the_mesh;
+
+class DiscoveryScreen : public UIScreen {
+  UITask* _task;
+  mesh::RTCClock* _rtc;
+  int _scrollPos;
+  int _rowsPerPage;
+
+  static char typeChar(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return 'C';
+      case ADV_TYPE_REPEATER: return 'R';
+      case ADV_TYPE_ROOM:     return 'S';
+      case ADV_TYPE_SENSOR:   return 'N';
+      default:                return '?';
+    }
+  }
+
+  static const char* typeLabel(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return "Chat";
+      case ADV_TYPE_REPEATER: return "Rptr";
+      case ADV_TYPE_ROOM:     return "Room";
+      case ADV_TYPE_SENSOR:   return "Sens";
+      default:                return "?";
+    }
+  }
+
+public:
+  DiscoveryScreen(UITask* task, mesh::RTCClock* rtc)
+    : _task(task), _rtc(rtc), _scrollPos(0), _rowsPerPage(5) {}
+
+  void resetScroll() { _scrollPos = 0; }
+
+  int getSelectedIdx() const { return _scrollPos; }
+
+  // Tap-to-select: given virtual Y, select discovered node row.
+  // Returns: 0=miss, 1=moved, 2=tapped current row.
+  int selectRowAtVY(int vy) {
+    int count = the_mesh.getDiscoveredCount();
+    if (count == 0) return 0;
+    const int headerH = 14, footerH = 14, lineH = the_mesh.getNodePrefs()->smallLineH();
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    const int bodyTop = headerH;
+#else
+    const int bodyTop = headerH + the_mesh.getNodePrefs()->smallHighlightOff();
+#endif
+    if (vy < bodyTop || vy >= 128 - footerH) return 0;
+
+    int maxVisible = (128 - headerH - footerH) / lineH;
+    if (maxVisible < 3) maxVisible = 3;
+    int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                              count - maxVisible));
+
+    int tappedRow = startIdx + (vy - bodyTop) / lineH;
+    if (tappedRow < 0 || tappedRow >= count) return 0;
+
+    if (tappedRow == _scrollPos) return 2;
+    _scrollPos = tappedRow;
+    return 1;
+  }
+
+  int render(DisplayDriver& display) override {
+    int count = the_mesh.getDiscoveredCount();
+    bool active = the_mesh.isDiscoveryActive();
+
+    // === Header ===
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::GREEN);
+    display.setCursor(0, 0);
+
+    char hdr[32];
+    if (active) {
+      snprintf(hdr, sizeof(hdr), "Scanning... %d found", count);
+    } else {
+      snprintf(hdr, sizeof(hdr), "Scan done: %d found", count);
+    }
+    display.print(hdr);
+
+    // Divider
+    display.drawRect(0, 11, display.width(), 1);
+
+    // === Body — discovered node rows ===
+    display.setTextSize(the_mesh.getNodePrefs()->smallTextSize());  // tiny font for compact rows
+    int lineHeight = the_mesh.getNodePrefs()->smallLineH();
+    int headerHeight = 14;
+    int footerHeight = 14;
+    int maxY = display.height() - footerHeight;
+    int y = headerHeight;
+    int rowsDrawn = 0;
+
+    if (count == 0) {
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(4, 28);
+      display.print(active ? "Listening for adverts..." : "No nodes found");
+      if (!active) {
+        display.setCursor(4, 38);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+        display.print("Long press: Rescan");
+#else
+        display.print("F: Scan again  Q: Back");
+#endif
+      }
+    } else {
+      // Center visible window around selected item
+      int maxVisible = (maxY - headerHeight) / lineHeight;
+      if (maxVisible < 3) maxVisible = 3;
+      int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                                count - maxVisible));
+      int endIdx = min(count, startIdx + maxVisible);
+
+      for (int i = startIdx; i < endIdx && y + lineHeight <= maxY; i++) {
+        const DiscoveredNode& node = the_mesh.getDiscovered(i);
+        bool selected = (i == _scrollPos);
+
+        // Highlight selected row
+        if (selected) {
+          display.setColor(DisplayDriver::LIGHT);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+          display.fillRect(0, y, display.width(), lineHeight);
+#else
+          display.fillRect(0, y + the_mesh.getNodePrefs()->smallHighlightOff(), display.width(), lineHeight);
+#endif
+          display.setColor(DisplayDriver::DARK);
+        } else {
+          display.setColor(DisplayDriver::LIGHT);
+        }
+
+        display.setCursor(0, y);
+
+        // Prefix: cursor + type
+        char prefix[4];
+        if (selected) {
+          snprintf(prefix, sizeof(prefix), ">%c", typeChar(node.contact.type));
+        } else {
+          snprintf(prefix, sizeof(prefix), " %c", typeChar(node.contact.type));
+        }
+        display.print(prefix);
+
+        // Build right-side info: SNR or hop count + status
+        char rightStr[16];
+        if (node.snr != 0) {
+          // Active discovery result — show SNR in dB (value is ×4 scaled)
+          int snr_db = node.snr / 4;
+          if (node.already_in_contacts) {
+            snprintf(rightStr, sizeof(rightStr), "%ddB [+]", snr_db);
+          } else {
+            snprintf(rightStr, sizeof(rightStr), "%ddB", snr_db);
+          }
+        } else {
+          // Pre-seeded from cache — show hop count
+          if (node.already_in_contacts) {
+            snprintf(rightStr, sizeof(rightStr), "%dh [+]", node.path_len & 63);
+          } else {
+            snprintf(rightStr, sizeof(rightStr), "%dh", node.path_len & 63);
+          }
+        }
+        int rightWidth = display.getTextWidth(rightStr) + 2;
+
+        // Name (truncated with ellipsis)
+        char filteredName[32];
+        display.translateUTF8ToBlocks(filteredName, node.contact.name, sizeof(filteredName));
+        int nameX = display.getTextWidth(prefix) + 2;
+        int nameMaxW = display.width() - nameX - rightWidth - 2;
+        display.drawTextEllipsized(nameX, y, nameMaxW, filteredName);
+
+        // Right-aligned info
+        display.setCursor(display.width() - rightWidth, y);
+        display.print(rightStr);
+
+        y += lineHeight;
+        rowsDrawn++;
+      }
+      _rowsPerPage = (rowsDrawn > 0) ? rowsDrawn : 1;
+    }
+
+    display.setTextSize(1);  // restore for footer
+
+    // === Footer ===
+    int footerY = display.height() - 12;
+    display.drawRect(0, footerY - 2, display.width(), 1);
+    display.setColor(DisplayDriver::YELLOW);
+
+    display.setCursor(0, footerY);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    display.print("Swipe:Scroll");
+
+    const char* mid = "Tap:Add";
+    display.setCursor((display.width() - display.getTextWidth(mid)) / 2, footerY);
+    display.print(mid);
+
+    const char* right = "Hold:Rescan";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#else
+    display.print("Q:Bk F:Rescan");
+
+    const char* right = "Tap/Ent:Add";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#endif
+
+    // Faster refresh while actively scanning
+    return active ? 1000 : 5000;
+  }
+
+  bool handleInput(char c) override {
+    int count = the_mesh.getDiscoveredCount();
+
+    // W - scroll up
+    if (c == 'w' || c == 'W' || c == 0xF2) {
+      if (_scrollPos > 0) {
+        _scrollPos--;
+        return true;
+      }
+    }
+
+    // S - scroll down
+    if (c == 's' || c == 'S' || c == 0xF1) {
+      if (_scrollPos < count - 1) {
+        _scrollPos++;
+        return true;
+      }
+    }
+
+    // F - rescan (handled here as well as in main.cpp for consistency)
+    if (c == 'f') {
+      the_mesh.startDiscovery();
+      _scrollPos = 0;
+      return true;
+    }
+
+    // Enter - handled by main.cpp for alert feedback
+
+    return false;  // Q/back and Enter handled by main.cpp
+  }
+};

examples/companion_radio/ui-new/Emojisprites.h

@@ -0,0 +1,748 @@
+#pragma once
+
+// Emoji sprites for e-ink display - dual size
+// Large (12x12) for compose/picker, Small (10x10) for channel view
+// MSB-first, 2 bytes per row
+// 65 total emoji: joy/thumbsup/frown first, then 43 original, then 19 new
+
+#include <stdint.h>
+#ifdef ESP32
+#include <pgmspace.h>
+#endif
+
+#define EMOJI_LG_W 12
+#define EMOJI_LG_H 12
+#define EMOJI_SM_W 10
+#define EMOJI_SM_H 10
+
+#define EMOJI_COUNT 65
+
+// Escape codes in 0x80+ range - safe from keyboard ASCII (32-126)
+#define EMOJI_ESCAPE_START 0x80
+#define EMOJI_ESCAPE_END   0xC0   // 0x80 + 64
+#define EMOJI_PAD_BYTE     0x7F   // DEL, not typeable (key < 127 guard)
+
+// ======== LARGE 12x12 SPRITES ========
+
+// [0] joy  (most common mesh emoji)
+static const uint8_t emoji_lg_joy[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x59,0xA0, 0x59,0xA0, 0x80,0x10, 0xA0,0x50, 0x9F,0x90, 0x40,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [1] thumbsup
+static const uint8_t emoji_lg_thumbsup[] PROGMEM = {
+  0x00,0x00, 0x70,0x00, 0x70,0x00, 0x70,0x00, 0x7F,0x80, 0xFF,0x80, 0xFF,0x80, 0x7F,0x80, 0x3F,0x80, 0x1F,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [2] frown
+static const uint8_t emoji_lg_frown[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x59,0xA0, 0x59,0xA0, 0x80,0x10, 0x9F,0x90, 0xA0,0x50, 0x40,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [3] wireless
+static const uint8_t emoji_lg_wireless[] PROGMEM = {
+  0x00,0x00, 0x3F,0xC0, 0x60,0x60, 0xC0,0x30, 0x0F,0x00, 0x19,0x80, 0x30,0xC0, 0x00,0x00, 0x06,0x00, 0x0F,0x00, 0x06,0x00, 0x00,0x00,
+};
+// [4] infinity
+static const uint8_t emoji_lg_infinity[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x61,0x80, 0x92,0x40, 0x8C,0x40, 0x8C,0x40, 0x92,0x40, 0x61,0x80, 0x00,0x00, 0x00,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [5] trex
+static const uint8_t emoji_lg_trex[] PROGMEM = {
+  0x03,0xE0, 0x06,0xA0, 0x07,0xE0, 0x0C,0x00, 0x5C,0x00, 0x7C,0x00, 0x3C,0x00, 0x38,0x00, 0x3C,0x00, 0x36,0x00, 0x22,0x00, 0x33,0x00,
+};
+// [6] skull
+static const uint8_t emoji_lg_skull[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x59,0xA0, 0x59,0xA0, 0x40,0x20, 0x49,0x20, 0x2F,0x40, 0x1F,0x80, 0x96,0x90, 0x66,0x60, 0x36,0xC0, 0x96,0x90,
+};
+// [7] cross
+static const uint8_t emoji_lg_cross[] PROGMEM = {
+  0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x3F,0xC0, 0x3F,0xC0, 0x3F,0xC0, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00,
+};
+// [8] lightning
+static const uint8_t emoji_lg_lightning[] PROGMEM = {
+  0x03,0x00, 0x07,0x00, 0x0E,0x00, 0x1C,0x00, 0x3F,0x80, 0x01,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x00,0x00,
+};
+// [9] tophat
+static const uint8_t emoji_lg_tophat[] PROGMEM = {
+  0x00,0x00, 0x1F,0x80, 0x3F,0xC0, 0x3F,0xC0, 0x3F,0xC0, 0x3F,0xC0, 0x3F,0xC0, 0x20,0x40, 0x7F,0xE0, 0xFF,0xF0, 0xFF,0xF0, 0x00,0x00,
+};
+// [10] motorcycle
+static const uint8_t emoji_lg_motorcycle[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x0F,0x00, 0x1F,0x80, 0x7F,0xE0, 0xDF,0xB0, 0xDF,0xB0, 0xDF,0xB0, 0xDF,0xB0, 0x60,0x60, 0x00,0x00, 0x00,0x00,
+};
+// [11] seedling
+static const uint8_t emoji_lg_seedling[] PROGMEM = {
+  0x00,0x00, 0x30,0x00, 0x79,0x80, 0x7B,0xC0, 0x33,0xC0, 0x1F,0x80, 0x06,0x00, 0x06,0x00, 0x06,0x00, 0x06,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [12] flag_au
+static const uint8_t emoji_lg_flag_au[] PROGMEM = {
+  0x00,0x00, 0x32,0x40, 0x4A,0x40, 0x4A,0x40, 0x7A,0x40, 0x4A,0x40, 0x49,0x80, 0x00,0x00, 0xFF,0xF0, 0x00,0x00, 0xFF,0xF0, 0x00,0x00,
+};
+// [13] umbrella
+static const uint8_t emoji_lg_umbrella[] PROGMEM = {
+  0x06,0x00, 0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0xFF,0xF0, 0xDB,0x70, 0x06,0x00, 0x06,0x00, 0x06,0x00, 0x06,0x00, 0x46,0x00, 0x3C,0x00,
+};
+// [14] nazar
+static const uint8_t emoji_lg_nazar[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x4F,0x20, 0x99,0x90, 0xB6,0xD0, 0xB6,0xD0, 0xB6,0xD0, 0x99,0x90, 0x4F,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [15] globe
+static const uint8_t emoji_lg_globe[] PROGMEM = {
+  0x1F,0x80, 0x34,0xC0, 0x66,0x60, 0x4F,0x20, 0x8E,0x10, 0x86,0x10, 0x80,0x30, 0x46,0x60, 0x43,0xE0, 0x30,0xC0, 0x1F,0x80, 0x00,0x00,
+};
+// [16] radioactive
+static const uint8_t emoji_lg_radioactive[] PROGMEM = {
+  0x00,0x00, 0x22,0x40, 0x32,0xC0, 0x32,0xC0, 0x1B,0x40, 0x00,0x00, 0x0F,0x00, 0x0F,0x00, 0x00,0x00, 0x60,0x20, 0x39,0xC0, 0x0F,0x00,
+};
+// [17] cow
+static const uint8_t emoji_lg_cow[] PROGMEM = {
+  0x00,0x00, 0xC0,0x60, 0x6E,0xC0, 0x3F,0x80, 0x2A,0x80, 0x3F,0x80, 0x3F,0x80, 0x7F,0xC0, 0x5F,0x40, 0x5F,0x40, 0x11,0x00, 0x31,0x80,
+};
+// [18] alien
+static const uint8_t emoji_lg_alien[] PROGMEM = {
+  0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0x76,0xE0, 0xF6,0xF0, 0x96,0x90, 0x7F,0xE0, 0x36,0xC0, 0x3F,0xC0, 0x16,0x80, 0x0F,0x00, 0x06,0x00,
+};
+// [19] invader
+static const uint8_t emoji_lg_invader[] PROGMEM = {
+  0x10,0x80, 0x09,0x00, 0x1F,0x80, 0x36,0xC0, 0x7F,0xE0, 0x5F,0xA0, 0x50,0xA0, 0x50,0xA0, 0x19,0x80, 0x19,0x80, 0x30,0xC0, 0x00,0x00,
+};
+// [20] dagger
+static const uint8_t emoji_lg_dagger[] PROGMEM = {
+  0x01,0x80, 0x01,0x40, 0x01,0xA0, 0x01,0xC0, 0x01,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x60,0x00, 0x40,0x00,
+};
+// [21] grimace
+static const uint8_t emoji_lg_grimace[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x59,0xA0, 0x59,0xA0, 0x40,0x20, 0x40,0x20, 0x5F,0xA0, 0x55,0x40, 0x5F,0xA0, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [22] mountain
+static const uint8_t emoji_lg_mountain[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x06,0x00, 0x0F,0x00, 0x19,0x80, 0x30,0xC0, 0x66,0x60, 0xCF,0x30, 0x9F,0x90, 0xFF,0xF0, 0xFF,0xF0, 0x00,0x00,
+};
+// [23] end_arrow
+static const uint8_t emoji_lg_end_arrow[] PROGMEM = {
+  0x00,0x00, 0x7B,0x60, 0x43,0x60, 0x42,0xA0, 0x72,0xA0, 0x43,0x60, 0x43,0x60, 0x7B,0x60, 0x00,0x00, 0x06,0x00, 0x0F,0x00, 0x06,0x00,
+};
+// [24] hollow_circle
+static const uint8_t emoji_lg_hollow_circle[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x40,0x20, 0x80,0x10, 0x80,0x10, 0x80,0x10, 0x80,0x10, 0x80,0x10, 0x40,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [25] dragon
+static const uint8_t emoji_lg_dragon[] PROGMEM = {
+  0x60,0x00, 0xF0,0x00, 0x76,0x00, 0x3F,0x00, 0x1F,0x00, 0x0F,0x00, 0x1F,0x80, 0x3F,0xC0, 0x79,0xE0, 0x30,0xC0, 0x20,0x40, 0x30,0xC0,
+};
+// [26] globe_meridians
+static const uint8_t emoji_lg_globe_meridians[] PROGMEM = {
+  0x1F,0x80, 0x26,0x40, 0x46,0x20, 0x86,0x10, 0xFF,0xF0, 0x86,0x10, 0x86,0x10, 0x46,0x20, 0x26,0x40, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [27] eggplant
+static const uint8_t emoji_lg_eggplant[] PROGMEM = {
+  0x01,0x80, 0x03,0x00, 0x07,0x00, 0x0F,0x00, 0x1F,0x00, 0x3F,0x00, 0x3F,0x00, 0x7E,0x00, 0x7C,0x00, 0x78,0x00, 0x30,0x00, 0x00,0x00,
+};
+// [28] shield
+static const uint8_t emoji_lg_shield[] PROGMEM = {
+  0x00,0x00, 0x7F,0xE0, 0x7F,0xE0, 0x6F,0x60, 0x6F,0x60, 0x6F,0x60, 0x36,0xC0, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x06,0x00, 0x00,0x00,
+};
+// [29] goggles
+static const uint8_t emoji_lg_goggles[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x00,0x00, 0x79,0xE0, 0xCF,0x30, 0x86,0x10, 0x86,0x10, 0xCF,0x30, 0x79,0xE0, 0x00,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [30] lizard
+static const uint8_t emoji_lg_lizard[] PROGMEM = {
+  0x00,0x00, 0x03,0x80, 0x07,0xC0, 0x8F,0x00, 0x7F,0x00, 0x3E,0x00, 0x3F,0x80, 0x23,0xC0, 0x41,0xC0, 0x00,0xC0, 0x00,0x60, 0x00,0x20,
+};
+// [31] zany_face
+static const uint8_t emoji_lg_zany_face[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x59,0x20, 0x58,0xA0, 0x40,0x20, 0x40,0x20, 0x4F,0x20, 0x50,0xA0, 0x20,0x40, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [32] kangaroo
+static const uint8_t emoji_lg_kangaroo[] PROGMEM = {
+  0x0E,0x00, 0x1F,0x00, 0x1F,0x00, 0x0E,0x00, 0x0F,0x00, 0x07,0x80, 0x47,0x80, 0x65,0x80, 0x3C,0x80, 0x18,0x80, 0x10,0xC0, 0x18,0xF0,
+};
+// [33] feather
+static const uint8_t emoji_lg_feather[] PROGMEM = {
+  0x00,0x20, 0x00,0x60, 0x00,0xC0, 0x01,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x60,0x00, 0x70,0x00, 0x00,0x00,
+};
+// [34] bright
+static const uint8_t emoji_lg_bright[] PROGMEM = {
+  0x06,0x00, 0x26,0x40, 0x16,0x80, 0x0F,0x00, 0x6F,0x60, 0x6F,0x60, 0x0F,0x00, 0x16,0x80, 0x26,0x40, 0x06,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [35] part_alt
+static const uint8_t emoji_lg_part_alt[] PROGMEM = {
+  0xC0,0xC0, 0xE1,0xC0, 0xF3,0xC0, 0xDE,0xC0, 0xCC,0xC0, 0xCC,0xC0, 0xC0,0xC0, 0xC0,0xC0, 0xC0,0xC0, 0xC0,0xC0, 0x00,0x00, 0x00,0x00,
+};
+// [36] motorboat
+static const uint8_t emoji_lg_motorboat[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x02,0x00, 0x07,0x00, 0x0F,0x80, 0x1F,0xC0, 0xFF,0xF0, 0x7F,0xE0, 0x3F,0xC0, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [37] domino
+static const uint8_t emoji_lg_domino[] PROGMEM = {
+  0xFF,0xF0, 0x99,0x90, 0x80,0x10, 0x99,0x90, 0x80,0x10, 0x99,0x90, 0xFF,0xF0, 0x80,0x10, 0x80,0x10, 0x86,0x10, 0x80,0x10, 0xFF,0xF0,
+};
+// [38] satellite
+static const uint8_t emoji_lg_satellite[] PROGMEM = {
+  0x78,0x00, 0xCC,0x00, 0x84,0x00, 0xCD,0x00, 0x7B,0x00, 0x03,0x80, 0x01,0xC0, 0x00,0xE0, 0x00,0x60, 0x00,0x20, 0x00,0x00, 0x00,0x00,
+};
+// [39] customs
+static const uint8_t emoji_lg_customs[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x40,0x20, 0x4F,0x20, 0x50,0xA0, 0x50,0xA0, 0x4F,0x20, 0x42,0x20, 0x22,0x40, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [40] cowboy
+static const uint8_t emoji_lg_cowboy[] PROGMEM = {
+  0x0F,0x00, 0x0F,0x00, 0x7F,0xE0, 0xFF,0xF0, 0x00,0x00, 0x3F,0xC0, 0x59,0xA0, 0x40,0x20, 0x4F,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [41] wheel
+static const uint8_t emoji_lg_wheel[] PROGMEM = {
+  0x1F,0x80, 0x26,0x40, 0x46,0x20, 0x9F,0x90, 0xB6,0xD0, 0xFF,0xF0, 0xB6,0xD0, 0x9F,0x90, 0x46,0x20, 0x26,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [42] koala
+static const uint8_t emoji_lg_koala[] PROGMEM = {
+  0x60,0x60, 0xF0,0xF0, 0xF0,0xF0, 0x76,0xE0, 0x26,0x40, 0x2F,0x40, 0x26,0x40, 0x30,0xC0, 0x1F,0x80, 0x00,0x00, 0x00,0x00, 0x00,0x00,
+};
+// [43] control_knobs
+static const uint8_t emoji_lg_control_knobs[] PROGMEM = {
+  0x00,0x00, 0x33,0x30, 0x33,0x30, 0x33,0x30, 0x33,0x30, 0x33,0x30, 0x33,0x30, 0x7B,0x30, 0x37,0xB0, 0x33,0x70, 0x33,0x30, 0x00,0x00,
+};
+// [44] peach
+static const uint8_t emoji_lg_peach[] PROGMEM = {
+  0x06,0x00, 0x0C,0x00, 0x1E,0x00, 0x3F,0x00, 0x7F,0x80, 0x7B,0xC0, 0x7B,0xC0, 0x7B,0xC0, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x00,0x00,
+};
+// [45] racing_car
+static const uint8_t emoji_lg_racing_car[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x00,0x00, 0x07,0x80, 0x0F,0xC0, 0x7F,0xE0, 0xFF,0xF0, 0xFF,0xF0, 0x6F,0x60, 0x49,0x20, 0x00,0x00, 0x00,0x00,
+};
+// [46] mouse 🐭
+static const uint8_t emoji_lg_mouse[] PROGMEM = {
+  0x30,0xC0, 0x79,0xE0, 0x79,0xE0, 0x3F,0xC0, 0x49,0x20, 0x80,0x10, 0x86,0x10, 0x89,0x10, 0x40,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [47] mushroom 🍄
+static const uint8_t emoji_lg_mushroom[] PROGMEM = {
+  0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0xE6,0x70, 0xE6,0x70, 0x7F,0xE0, 0x3F,0xC0, 0x0F,0x00, 0x0F,0x00, 0x0F,0x00, 0x1F,0x80, 0x00,0x00,
+};
+// [48] biohazard ☣️
+static const uint8_t emoji_lg_biohazard[] PROGMEM = {
+  0x0F,0x00, 0x1F,0x80, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x66,0x60, 0x76,0xE0, 0x70,0xE0, 0x79,0xE0, 0x39,0xC0, 0x19,0x80, 0x00,0x00,
+};
+// [49] panda 🐼
+static const uint8_t emoji_lg_panda[] PROGMEM = {
+  0x00,0x00, 0x60,0x60, 0xF0,0xF0, 0xF0,0xF0, 0x7F,0xE0, 0x59,0xA0, 0x59,0xA0, 0x40,0x20, 0x46,0x20, 0x20,0x40, 0x1F,0x80, 0x00,0x00,
+};
+// [50] anger 💢
+static const uint8_t emoji_lg_anger[] PROGMEM = {
+  0x00,0x00, 0x3C,0xC0, 0x3C,0xC0, 0x30,0xC0, 0x30,0x00, 0x00,0x00, 0x00,0x00, 0x00,0xC0, 0x30,0xC0, 0x33,0xC0, 0x33,0xC0, 0x00,0x00,
+};
+// [51] dragon_face 🐲
+static const uint8_t emoji_lg_dragon_face[] PROGMEM = {
+  0xC0,0x30, 0xE0,0x70, 0x76,0xE0, 0x3F,0xC0, 0x69,0x60, 0x40,0x20, 0x4F,0x20, 0x29,0x40, 0x30,0xC0, 0x1F,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [52] pager 📟
+static const uint8_t emoji_lg_pager[] PROGMEM = {
+  0x00,0x00, 0x7F,0xE0, 0x40,0x20, 0x5F,0xA0, 0x5F,0xA0, 0x40,0x20, 0x5B,0x20, 0x5B,0x20, 0x40,0x20, 0x7F,0xE0, 0x00,0x00, 0x00,0x00,
+};
+// [53] bee 🐝
+static const uint8_t emoji_lg_bee[] PROGMEM = {
+  0x00,0x00, 0x19,0x80, 0x19,0x80, 0x3F,0x80, 0x7F,0xC0, 0x7F,0xE0, 0x7F,0xE0, 0x7F,0xC0, 0x3F,0x80, 0x1F,0x40, 0x0A,0x00, 0x00,0x00,
+};
+// [54] bulb 💡
+static const uint8_t emoji_lg_bulb[] PROGMEM = {
+  0x1F,0x80, 0x20,0x40, 0x40,0x20, 0x40,0x20, 0x40,0x20, 0x20,0x40, 0x30,0xC0, 0x1F,0x80, 0x16,0x80, 0x1F,0x80, 0x0F,0x00, 0x00,0x00,
+};
+// [55] cat 🐱
+static const uint8_t emoji_lg_cat[] PROGMEM = {
+  0x40,0x20, 0x60,0x60, 0x70,0xE0, 0x3F,0xC0, 0x59,0xA0, 0x40,0x20, 0x40,0x20, 0x46,0x20, 0x29,0x40, 0x30,0xC0, 0x1F,0x80, 0x00,0x00,
+};
+// [56] fleur ⚜️
+static const uint8_t emoji_lg_fleur[] PROGMEM = {
+  0x06,0x00, 0x06,0x00, 0x0F,0x00, 0x6F,0x60, 0xF6,0xF0, 0xF6,0xF0, 0x76,0xE0, 0x3F,0xC0, 0x1F,0x80, 0x0F,0x00, 0x19,0x80, 0x00,0x00,
+};
+// [57] moon 🌔
+static const uint8_t emoji_lg_moon[] PROGMEM = {
+  0x1F,0x80, 0x3F,0xC0, 0x7F,0xE0, 0x7F,0x80, 0xFF,0x80, 0xFF,0x00, 0xFF,0x00, 0xFF,0x80, 0x7F,0x80, 0x7F,0xE0, 0x3F,0xC0, 0x1F,0x80,
+};
+// [58] coffee ☕
+static const uint8_t emoji_lg_coffee[] PROGMEM = {
+  0x24,0x80, 0x12,0x40, 0x00,0x00, 0x7F,0xC0, 0x40,0x70, 0x40,0x50, 0x40,0x50, 0x40,0x70, 0x7F,0xC0, 0x00,0x00, 0xFF,0xC0, 0x00,0x00,
+};
+// [59] tooth 🦷
+static const uint8_t emoji_lg_tooth[] PROGMEM = {
+  0x3F,0xC0, 0x7F,0xE0, 0xFF,0xF0, 0xFF,0xF0, 0xFF,0xF0, 0x7F,0xE0, 0x3F,0xC0, 0x3F,0xC0, 0x39,0xC0, 0x39,0xC0, 0x30,0xC0, 0x20,0x40,
+};
+// [60] pretzel 🥨
+static const uint8_t emoji_lg_pretzel[] PROGMEM = {
+  0x39,0xC0, 0x46,0x20, 0x80,0x20, 0x86,0x10, 0x49,0x20, 0x30,0xC0, 0x30,0xC0, 0x49,0x20, 0x86,0x10, 0x80,0x10, 0x46,0x20, 0x39,0xC0,
+};
+// [61] abacus 🧮
+static const uint8_t emoji_lg_abacus[] PROGMEM = {
+  0xFF,0xF0, 0x80,0x10, 0xB6,0x50, 0x80,0x10, 0xA6,0x90, 0x80,0x10, 0x94,0xD0, 0x80,0x10, 0xB2,0x50, 0x80,0x10, 0xFF,0xF0, 0x00,0x00,
+};
+// [62] moai 🗿
+static const uint8_t emoji_lg_moai[] PROGMEM = {
+  0x3F,0xC0, 0x7F,0xC0, 0x7F,0xC0, 0x39,0xC0, 0x39,0xC0, 0x3F,0xC0, 0x27,0x40, 0x3F,0x80, 0x2F,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00,
+};
+// [63] tipping 💁
+static const uint8_t emoji_lg_tipping[] PROGMEM = {
+  0x1E,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x0C,0x00, 0x1E,0x00, 0x3F,0x00, 0x7F,0x80, 0x0C,0xE0, 0x0D,0xE0, 0x12,0xE0, 0x33,0x00,
+};
+// [64] hedgehog 🦔
+static const uint8_t emoji_lg_hedgehog[] PROGMEM = {
+  0x00,0x00, 0x0A,0x80, 0x15,0x40, 0x2A,0xA0, 0x55,0x60, 0x7E,0xF0, 0xDB,0x90, 0xFF,0xD0, 0x7F,0xE0, 0x3F,0xC0, 0x24,0x80, 0x00,0x00,
+};
+
+static const uint8_t* const EMOJI_SPRITES_LG[] PROGMEM = {
+  emoji_lg_joy, emoji_lg_thumbsup, emoji_lg_frown,
+  emoji_lg_wireless, emoji_lg_infinity, emoji_lg_trex, emoji_lg_skull, emoji_lg_cross,
+  emoji_lg_lightning, emoji_lg_tophat, emoji_lg_motorcycle, emoji_lg_seedling, emoji_lg_flag_au,
+  emoji_lg_umbrella, emoji_lg_nazar, emoji_lg_globe, emoji_lg_radioactive, emoji_lg_cow,
+  emoji_lg_alien, emoji_lg_invader, emoji_lg_dagger, emoji_lg_grimace,
+  emoji_lg_mountain, emoji_lg_end_arrow, emoji_lg_hollow_circle, emoji_lg_dragon, emoji_lg_globe_meridians,
+  emoji_lg_eggplant, emoji_lg_shield, emoji_lg_goggles, emoji_lg_lizard, emoji_lg_zany_face,
+  emoji_lg_kangaroo, emoji_lg_feather, emoji_lg_bright, emoji_lg_part_alt, emoji_lg_motorboat,
+  emoji_lg_domino, emoji_lg_satellite, emoji_lg_customs, emoji_lg_cowboy, emoji_lg_wheel,
+  emoji_lg_koala, emoji_lg_control_knobs, emoji_lg_peach, emoji_lg_racing_car,
+  emoji_lg_mouse, emoji_lg_mushroom, emoji_lg_biohazard, emoji_lg_panda,
+  emoji_lg_anger, emoji_lg_dragon_face, emoji_lg_pager, emoji_lg_bee,
+  emoji_lg_bulb, emoji_lg_cat, emoji_lg_fleur, emoji_lg_moon,
+  emoji_lg_coffee, emoji_lg_tooth, emoji_lg_pretzel, emoji_lg_abacus,
+  emoji_lg_moai, emoji_lg_tipping, emoji_lg_hedgehog,
+};
+
+// ======== SMALL 10x10 SPRITES ========
+
+static const uint8_t emoji_sm_joy[] PROGMEM = {
+  0x3F,0x00, 0x61,0x80, 0xF3,0xC0, 0x80,0x40, 0xA1,0x40, 0x9E,0x40, 0x40,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_thumbsup[] PROGMEM = {
+  0x70,0x00, 0x70,0x00, 0x70,0x00, 0x7F,0x00, 0xFF,0x00, 0xFF,0x00, 0x7F,0x00, 0x3E,0x00, 0x1C,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_frown[] PROGMEM = {
+  0x3F,0x00, 0x61,0x80, 0xF3,0xC0, 0x80,0x40, 0x9E,0x40, 0xA1,0x40, 0x40,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_wireless[] PROGMEM = {
+  0x00,0x00, 0x7F,0x80, 0xC0,0xC0, 0x1E,0x00, 0x33,0x00, 0x21,0x00, 0x00,0x00, 0x0C,0x00, 0x0C,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_infinity[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0xE7,0x00, 0x99,0x00, 0x99,0x00, 0xA5,0x00, 0x42,0x00, 0x00,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_trex[] PROGMEM = {
+  0x07,0x80, 0x0F,0x80, 0x0F,0x80, 0x58,0x00, 0x78,0x00, 0x38,0x00, 0x38,0x00, 0x3C,0x00, 0x24,0x00, 0x26,0x00,
+};
+static const uint8_t emoji_sm_skull[] PROGMEM = {
+  0x3F,0x00, 0x61,0x80, 0x73,0x80, 0x40,0x80, 0x52,0x80, 0x3F,0x00, 0x3F,0x00, 0xED,0xC0, 0x6D,0x80, 0xAD,0x40,
+};
+static const uint8_t emoji_sm_cross[] PROGMEM = {
+  0x1E,0x00, 0x1E,0x00, 0x3F,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x1E,0x00, 0x1E,0x00, 0x1E,0x00, 0x1E,0x00,
+};
+static const uint8_t emoji_sm_lightning[] PROGMEM = {
+  0x06,0x00, 0x0E,0x00, 0x1C,0x00, 0x3E,0x00, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_tophat[] PROGMEM = {
+  0x00,0x00, 0x3F,0x00, 0x3F,0x00, 0x3F,0x00, 0x3F,0x00, 0x21,0x00, 0x7F,0x80, 0xFF,0xC0, 0xFF,0xC0, 0x00,0x00,
+};
+static const uint8_t emoji_sm_motorcycle[] PROGMEM = {
+  0x00,0x00, 0x1E,0x00, 0x7F,0x80, 0xDE,0xC0, 0xDE,0xC0, 0xDE,0xC0, 0xDE,0xC0, 0x61,0x80, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_seedling[] PROGMEM = {
+  0x00,0x00, 0x70,0x00, 0x77,0x00, 0x77,0x00, 0x3F,0x00, 0x0C,0x00, 0x0C,0x00, 0x0C,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_flag_au[] PROGMEM = {
+  0x00,0x00, 0x75,0x00, 0x55,0x00, 0x75,0x00, 0x55,0x00, 0x53,0x00, 0x00,0x00, 0xFF,0xC0, 0xFF,0xC0, 0x00,0x00,
+};
+static const uint8_t emoji_sm_umbrella[] PROGMEM = {
+  0x0C,0x00, 0x3F,0x00, 0x7F,0x80, 0xFF,0xC0, 0xF7,0xC0, 0x0C,0x00, 0x0C,0x00, 0x0C,0x00, 0x4C,0x00, 0x78,0x00,
+};
+static const uint8_t emoji_sm_nazar[] PROGMEM = {
+  0x3F,0x00, 0x40,0x80, 0x9E,0x40, 0xBF,0x40, 0xAD,0x40, 0xBF,0x40, 0x9E,0x40, 0x4C,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_globe[] PROGMEM = {
+  0x3F,0x00, 0x69,0x80, 0x4C,0x80, 0x9C,0x40, 0x8C,0x40, 0x80,0xC0, 0x4D,0x80, 0x67,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_radioactive[] PROGMEM = {
+  0x00,0x00, 0x25,0x00, 0x25,0x00, 0x37,0x00, 0x00,0x00, 0x1E,0x00, 0x1E,0x00, 0x40,0x00, 0x73,0x80, 0x1E,0x00,
+};
+static const uint8_t emoji_sm_cow[] PROGMEM = {
+  0x00,0x00, 0xC1,0x80, 0x7F,0x00, 0x3F,0x00, 0x3F,0x00, 0x7F,0x00, 0x7F,0x00, 0x7F,0x00, 0x36,0x00, 0x23,0x00,
+};
+static const uint8_t emoji_sm_alien[] PROGMEM = {
+  0x3F,0x00, 0x7F,0x80, 0x7F,0x80, 0xED,0xC0, 0xAD,0x40, 0x7F,0x80, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x0C,0x00,
+};
+static const uint8_t emoji_sm_invader[] PROGMEM = {
+  0x33,0x00, 0x1E,0x00, 0x3F,0x00, 0x7F,0x80, 0x7F,0x80, 0x61,0x80, 0x73,0x80, 0x33,0x00, 0x33,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_dagger[] PROGMEM = {
+  0x03,0x00, 0x03,0x80, 0x03,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x60,0x00, 0x40,0x00,
+};
+static const uint8_t emoji_sm_grimace[] PROGMEM = {
+  0x3F,0x00, 0x61,0x80, 0x73,0x80, 0x40,0x80, 0x40,0x80, 0x7F,0x80, 0x55,0x00, 0x7F,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_mountain[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x0C,0x00, 0x1E,0x00, 0x33,0x00, 0x6D,0x80, 0xDE,0xC0, 0xFF,0xC0, 0xFF,0xC0, 0x00,0x00,
+};
+static const uint8_t emoji_sm_end_arrow[] PROGMEM = {
+  0x00,0x00, 0x77,0x80, 0x47,0x80, 0x65,0x80, 0x47,0x80, 0x47,0x80, 0x76,0x80, 0x0C,0x00, 0x1E,0x00, 0x0C,0x00,
+};
+static const uint8_t emoji_sm_hollow_circle[] PROGMEM = {
+  0x3F,0x00, 0x40,0x80, 0x80,0x40, 0x80,0x40, 0x80,0x40, 0x80,0x40, 0x80,0x40, 0x40,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_dragon[] PROGMEM = {
+  0x60,0x00, 0xE0,0x00, 0x7C,0x00, 0x3E,0x00, 0x1E,0x00, 0x3F,0x00, 0x7F,0x80, 0x73,0x80, 0x21,0x00, 0x21,0x00,
+};
+static const uint8_t emoji_sm_globe_meridians[] PROGMEM = {
+  0x3F,0x00, 0x4C,0x80, 0x8C,0x40, 0xFF,0xC0, 0x8C,0x40, 0x8C,0x40, 0x4C,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_eggplant[] PROGMEM = {
+  0x03,0x00, 0x06,0x00, 0x0E,0x00, 0x1E,0x00, 0x3E,0x00, 0x7E,0x00, 0x7C,0x00, 0x78,0x00, 0x70,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_shield[] PROGMEM = {
+  0x00,0x00, 0xFF,0xC0, 0xFF,0xC0, 0xDE,0xC0, 0xDE,0xC0, 0x6D,0x80, 0x7F,0x80, 0x3F,0x00, 0x1E,0x00, 0x0C,0x00,
+};
+static const uint8_t emoji_sm_goggles[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x73,0x80, 0xDE,0xC0, 0x8C,0x40, 0x8C,0x40, 0xDE,0xC0, 0x73,0x80, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_lizard[] PROGMEM = {
+  0x00,0x00, 0x07,0x00, 0x9E,0x00, 0x7E,0x00, 0x3E,0x00, 0x27,0x80, 0x43,0x00, 0x01,0x80, 0x00,0x80, 0x00,0x00,
+};
+static const uint8_t emoji_sm_zany_face[] PROGMEM = {
+  0x3F,0x00, 0x60,0x80, 0x72,0x80, 0x40,0x80, 0x40,0x80, 0x5E,0x80, 0x61,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_kangaroo[] PROGMEM = {
+  0x1C,0x00, 0x3E,0x00, 0x1C,0x00, 0x1E,0x00, 0x0F,0x00, 0x4F,0x00, 0x6B,0x00, 0x39,0x00, 0x31,0x00, 0x31,0xC0,
+};
+static const uint8_t emoji_sm_feather[] PROGMEM = {
+  0x00,0x80, 0x01,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00, 0x18,0x00, 0x30,0x00, 0x60,0x00, 0x60,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_bright[] PROGMEM = {
+  0x0C,0x00, 0x2D,0x00, 0x1E,0x00, 0x5E,0x80, 0x7F,0x80, 0x1E,0x00, 0x2D,0x00, 0x0C,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_part_alt[] PROGMEM = {
+  0xC3,0x00, 0xE7,0x00, 0xDB,0x00, 0xDB,0x00, 0xC3,0x00, 0xC3,0x00, 0xC3,0x00, 0xC3,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_motorboat[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x0C,0x00, 0x1E,0x00, 0x3F,0x00, 0xFF,0xC0, 0x7F,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_domino[] PROGMEM = {
+  0xFF,0xC0, 0xB6,0x40, 0xB6,0x40, 0xB6,0x40, 0xFF,0xC0, 0x80,0x40, 0x8C,0x40, 0x80,0x40, 0xFF,0xC0, 0x00,0x00,
+};
+static const uint8_t emoji_sm_satellite[] PROGMEM = {
+  0x70,0x00, 0xD8,0x00, 0x88,0x00, 0xFE,0x00, 0x07,0x00, 0x03,0x80, 0x01,0x80, 0x00,0x80, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_customs[] PROGMEM = {
+  0x3F,0x00, 0x40,0x80, 0x4C,0x80, 0x52,0x80, 0x61,0x80, 0x5E,0x80, 0x44,0x80, 0x3F,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_cowboy[] PROGMEM = {
+  0x1E,0x00, 0x1E,0x00, 0xFF,0xC0, 0x00,0x00, 0x3F,0x00, 0x73,0x80, 0x40,0x80, 0x4C,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_wheel[] PROGMEM = {
+  0x3F,0x00, 0x4C,0x80, 0x9E,0x40, 0xBF,0x40, 0xFF,0xC0, 0xBF,0x40, 0x9E,0x40, 0x4C,0x80, 0x3F,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_koala[] PROGMEM = {
+  0x61,0x80, 0xE1,0xC0, 0xED,0xC0, 0x6D,0x80, 0x3F,0x00, 0x2D,0x00, 0x33,0x00, 0x1E,0x00, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_control_knobs[] PROGMEM = {
+  0x00,0x00, 0x26,0xC0, 0x26,0xC0, 0x26,0xC0, 0x26,0xC0, 0x76,0xC0, 0x7E,0xC0, 0x2F,0xC0, 0x26,0xC0, 0x00,0x00,
+};
+static const uint8_t emoji_sm_peach[] PROGMEM = {
+  0x0C,0x00, 0x18,0x00, 0x3C,0x00, 0x7E,0x00, 0x77,0x00, 0x77,0x00, 0x7F,0x00, 0x3F,0x00, 0x1E,0x00, 0x00,0x00,
+};
+static const uint8_t emoji_sm_racing_car[] PROGMEM = {
+  0x00,0x00, 0x00,0x00, 0x0E,0x00, 0x1F,0x00, 0x7F,0x80, 0xFF,0xC0, 0xFF,0xC0, 0x5E,0x80, 0x00,0x00, 0x00,0x00,
+};
+// [46] mouse 🐭
+static const uint8_t emoji_sm_mouse[] PROGMEM = {
+  0x61,0x80, 0xF3,0xC0, 0x7F,0x80, 0x92,0x40, 0x80,0x40, 0x8C,0x40, 0x52,0x80, 0x40,0x80, 0x3F,0x00, 0x00,0x00,
+};
+// [47] mushroom 🍄
+static const uint8_t emoji_sm_mushroom[] PROGMEM = {
+  0x3F,0x00, 0x7F,0x80, 0xED,0xC0, 0xED,0xC0, 0x7F,0x80, 0x3F,0x00, 0x1E,0x00, 0x1E,0x00, 0x3F,0x00, 0x00,0x00,
+};
+// [48] biohazard ☣️
+static const uint8_t emoji_sm_biohazard[] PROGMEM = {
+  0x1E,0x00, 0x3F,0x00, 0x3F,0x00, 0x1E,0x00, 0x6D,0x80, 0x73,0x80, 0x73,0x80, 0x7B,0x80, 0x33,0x00, 0x00,0x00,
+};
+// [49] panda 🐼
+static const uint8_t emoji_sm_panda[] PROGMEM = {
+  0xC0,0xC0, 0xF3,0xC0, 0x7F,0x80, 0xB3,0x40, 0xB3,0x40, 0x80,0x40, 0x4C,0x80, 0x21,0x00, 0x3F,0x00, 0x00,0x00,
+};
+// [50] anger 💢
+static const uint8_t emoji_sm_anger[] PROGMEM = {
+  0x00,0x00, 0x73,0x00, 0x73,0x00, 0x63,0x00, 0x60,0x00, 0x01,0x80, 0x63,0x00, 0x67,0x00, 0x67,0x00, 0x00,0x00,
+};
+// [51] dragon_face 🐲
+static const uint8_t emoji_sm_dragon_face[] PROGMEM = {
+  0xC0,0xC0, 0xED,0xC0, 0x7F,0x80, 0x52,0x80, 0x40,0x80, 0x4C,0x80, 0x33,0x00, 0x2D,0x00, 0x1E,0x00, 0x00,0x00,
+};
+// [52] pager 📟
+static const uint8_t emoji_sm_pager[] PROGMEM = {
+  0x00,0x00, 0x7F,0x80, 0x40,0x80, 0x5E,0x80, 0x40,0x80, 0x5A,0x80, 0x5A,0x80, 0x40,0x80, 0x7F,0x80, 0x00,0x00,
+};
+// [53] bee 🐝
+static const uint8_t emoji_sm_bee[] PROGMEM = {
+  0x33,0x00, 0x33,0x00, 0x7F,0x00, 0xFF,0x80, 0xFF,0xC0, 0xFF,0x80, 0x7F,0x00, 0x3E,0x80, 0x14,0x00, 0x00,0x00,
+};
+// [54] bulb 💡
+static const uint8_t emoji_sm_bulb[] PROGMEM = {
+  0x3F,0x00, 0x40,0x80, 0x80,0x40, 0x80,0x40, 0x40,0x80, 0x33,0x00, 0x3F,0x00, 0x1E,0x00, 0x1E,0x00, 0x00,0x00,
+};
+// [55] cat 🐱
+static const uint8_t emoji_sm_cat[] PROGMEM = {
+  0x80,0x40, 0xC0,0xC0, 0x7F,0x80, 0xB3,0x40, 0x80,0x40, 0x8C,0x40, 0x52,0x80, 0x61,0x80, 0x3F,0x00, 0x00,0x00,
+};
+// [56] fleur ⚜️
+static const uint8_t emoji_sm_fleur[] PROGMEM = {
+  0x0C,0x00, 0x0C,0x00, 0x6D,0x80, 0xED,0xC0, 0xED,0xC0, 0x6D,0x80, 0x3F,0x00, 0x1E,0x00, 0x33,0x00, 0x00,0x00,
+};
+// [57] moon 🌔
+static const uint8_t emoji_sm_moon[] PROGMEM = {
+  0x3F,0x00, 0x7F,0x80, 0xFF,0x80, 0xFE,0x00, 0xFE,0x00, 0xFE,0x00, 0xFE,0x00, 0xFF,0x80, 0x7F,0x80, 0x3F,0x00,
+};
+// [58] coffee ☕
+static const uint8_t emoji_sm_coffee[] PROGMEM = {
+  0x49,0x00, 0x24,0x80, 0x00,0x00, 0xFF,0x00, 0x81,0xC0, 0x81,0x40, 0x81,0xC0, 0xFF,0x00, 0x00,0x00, 0xFE,0x00,
+};
+// [59] tooth 🦷
+static const uint8_t emoji_sm_tooth[] PROGMEM = {
+  0x7F,0x80, 0xFF,0xC0, 0xFF,0xC0, 0xFF,0xC0, 0x7F,0x80, 0x3F,0x00, 0x3B,0x80, 0x31,0x80, 0x20,0x80, 0x00,0x00,
+};
+// [60] pretzel 🥨
+static const uint8_t emoji_sm_pretzel[] PROGMEM = {
+  0x73,0x80, 0x9E,0x40, 0x8C,0x40, 0x52,0x80, 0x33,0x00, 0x33,0x00, 0x52,0x80, 0x8C,0x40, 0x9E,0x40, 0x73,0x80,
+};
+// [61] abacus 🧮
+static const uint8_t emoji_sm_abacus[] PROGMEM = {
+  0xFF,0xC0, 0x80,0x40, 0xB5,0x40, 0x80,0x40, 0xAD,0x40, 0x80,0x40, 0xAB,0x40, 0x80,0x40, 0xFF,0xC0, 0x00,0x00,
+};
+// [62] moai 🗿
+static const uint8_t emoji_sm_moai[] PROGMEM = {
+  0x7F,0x00, 0x7F,0x00, 0x33,0x00, 0x33,0x00, 0x3F,0x00, 0x2E,0x00, 0x3E,0x00, 0x3E,0x00, 0x3E,0x00, 0x1C,0x00,
+};
+// [63] tipping 💁
+static const uint8_t emoji_sm_tipping[] PROGMEM = {
+  0x3C,0x00, 0x7E,0x00, 0x7E,0x00, 0x3C,0x00, 0x18,0x00, 0x3C,0x00, 0x7E,0x00, 0x1B,0x80, 0x1B,0x80, 0x36,0x00,
+};
+// [64] hedgehog 🦔
+static const uint8_t emoji_sm_hedgehog[] PROGMEM = {
+  0x15,0x00, 0x2A,0x80, 0x55,0x40, 0xFF,0xC0, 0xDB,0x40, 0xFF,0x80, 0x7F,0x80, 0x3F,0x00, 0x24,0x00, 0x00,0x00,
+};
+
+static const uint8_t* const EMOJI_SPRITES_SM[] PROGMEM = {
+  emoji_sm_joy, emoji_sm_thumbsup, emoji_sm_frown,
+  emoji_sm_wireless, emoji_sm_infinity, emoji_sm_trex, emoji_sm_skull, emoji_sm_cross,
+  emoji_sm_lightning, emoji_sm_tophat, emoji_sm_motorcycle, emoji_sm_seedling, emoji_sm_flag_au,
+  emoji_sm_umbrella, emoji_sm_nazar, emoji_sm_globe, emoji_sm_radioactive, emoji_sm_cow,
+  emoji_sm_alien, emoji_sm_invader, emoji_sm_dagger, emoji_sm_grimace,
+  emoji_sm_mountain, emoji_sm_end_arrow, emoji_sm_hollow_circle, emoji_sm_dragon, emoji_sm_globe_meridians,
+  emoji_sm_eggplant, emoji_sm_shield, emoji_sm_goggles, emoji_sm_lizard, emoji_sm_zany_face,
+  emoji_sm_kangaroo, emoji_sm_feather, emoji_sm_bright, emoji_sm_part_alt, emoji_sm_motorboat,
+  emoji_sm_domino, emoji_sm_satellite, emoji_sm_customs, emoji_sm_cowboy, emoji_sm_wheel,
+  emoji_sm_koala, emoji_sm_control_knobs, emoji_sm_peach, emoji_sm_racing_car,
+  emoji_sm_mouse, emoji_sm_mushroom, emoji_sm_biohazard, emoji_sm_panda,
+  emoji_sm_anger, emoji_sm_dragon_face, emoji_sm_pager, emoji_sm_bee,
+  emoji_sm_bulb, emoji_sm_cat, emoji_sm_fleur, emoji_sm_moon,
+  emoji_sm_coffee, emoji_sm_tooth, emoji_sm_pretzel, emoji_sm_abacus,
+  emoji_sm_moai, emoji_sm_tipping, emoji_sm_hedgehog,
+};
+
+// ---- Codepoint lookup for UTF-8 conversion ----
+struct EmojiCodepoint { uint32_t cp; uint32_t cp2; uint8_t escape; };
+
+static const EmojiCodepoint EMOJI_CODEPOINTS[EMOJI_COUNT] = {
+  { 0x1F602, 0x0000, 0x80 }, // joy
+  { 0x1F44D, 0x0000, 0x81 }, // thumbsup
+  { 0x2639,  0x0000, 0x82 }, // frown
+  { 0x1F6DC, 0x0000, 0x83 }, // wireless
+  { 0x267E,  0x0000, 0x84 }, // infinity
+  { 0x1F996, 0x0000, 0x85 }, // trex
+  { 0x2620,  0x0000, 0x86 }, // skull
+  { 0x271D,  0x0000, 0x87 }, // cross
+  { 0x26A1,  0x0000, 0x88 }, // lightning
+  { 0x1F3A9, 0x0000, 0x89 }, // tophat
+  { 0x1F3CD, 0x0000, 0x8A }, // motorcycle
+  { 0x1F331, 0x0000, 0x8B }, // seedling
+  { 0x1F1E6, 0x1F1FA, 0x8C }, // flag_au
+  { 0x2602,  0x0000, 0x8D }, // umbrella
+  { 0x1F9FF, 0x0000, 0x8E }, // nazar
+  { 0x1F30F, 0x0000, 0x8F }, // globe
+  { 0x2622,  0x0000, 0x90 }, // radioactive
+  { 0x1F404, 0x0000, 0x91 }, // cow
+  { 0x1F47D, 0x0000, 0x92 }, // alien
+  { 0x1F47E, 0x0000, 0x93 }, // invader
+  { 0x1F5E1, 0x0000, 0x94 }, // dagger
+  { 0x1F62C, 0x0000, 0x95 }, // grimace
+  { 0x26F0,  0x0000, 0x96 }, // mountain
+  { 0x1F51A, 0x0000, 0x97 }, // end_arrow
+  { 0x2B55,  0x0000, 0x98 }, // hollow_circle
+  { 0x1F409, 0x0000, 0x99 }, // dragon
+  { 0x1F310, 0x0000, 0x9A }, // globe_meridians
+  { 0x1F346, 0x0000, 0x9B }, // eggplant
+  { 0x1F6E1, 0x0000, 0x9C }, // shield
+  { 0x1F97D, 0x0000, 0x9D }, // goggles
+  { 0x1F98E, 0x0000, 0x9E }, // lizard
+  { 0x1F92A, 0x0000, 0x9F }, // zany_face
+  { 0x1F998, 0x0000, 0xA0 }, // kangaroo
+  { 0x1FAB6, 0x0000, 0xA1 }, // feather
+  { 0x1F506, 0x0000, 0xA2 }, // bright
+  { 0x303D,  0x0000, 0xA3 }, // part_alt
+  { 0x1F6E5, 0x0000, 0xA4 }, // motorboat
+  { 0x1F030, 0x0000, 0xA5 }, // domino
+  { 0x1F4E1, 0x0000, 0xA6 }, // satellite
+  { 0x1F6C3, 0x0000, 0xA7 }, // customs
+  { 0x1F920, 0x0000, 0xA8 }, // cowboy
+  { 0x1F6DE, 0x0000, 0xA9 }, // wheel
+  { 0x1F428, 0x0000, 0xAA }, // koala
+  { 0x1F39B, 0x0000, 0xAB }, // control_knobs
+  { 0x1F351, 0x0000, 0xAC }, // peach
+  { 0x1F3CE, 0x0000, 0xAD }, // racing_car
+  { 0x1F42D, 0x0000, 0xAE }, // mouse
+  { 0x1F344, 0x0000, 0xAF }, // mushroom
+  { 0x2623,  0x0000, 0xB0 }, // biohazard
+  { 0x1F43C, 0x0000, 0xB1 }, // panda
+  { 0x1F4A2, 0x0000, 0xB2 }, // anger
+  { 0x1F432, 0x0000, 0xB3 }, // dragon_face
+  { 0x1F4DF, 0x0000, 0xB4 }, // pager
+  { 0x1F41D, 0x0000, 0xB5 }, // bee
+  { 0x1F4A1, 0x0000, 0xB6 }, // bulb
+  { 0x1F431, 0x0000, 0xB7 }, // cat
+  { 0x269C,  0x0000, 0xB8 }, // fleur
+  { 0x1F314, 0x0000, 0xB9 }, // moon
+  { 0x2615,  0x0000, 0xBA }, // coffee
+  { 0x1F9B7, 0x0000, 0xBB }, // tooth
+  { 0x1F968, 0x0000, 0xBC }, // pretzel
+  { 0x1F9EE, 0x0000, 0xBD }, // abacus
+  { 0x1F5FF, 0x0000, 0xBE }, // moai
+  { 0x1F481, 0x0000, 0xBF }, // tipping
+  { 0x1F994, 0x0000, 0xC0 }, // hedgehog
+};
+
+// ---- Helper functions ----
+
+// Alias table: extra codepoints that map to existing emoji escape bytes.
+// Used for variant codepoints (e.g. MWD node identifier 🂎 U+1F08E -> domino sprite)
+struct EmojiAlias { uint32_t cp; uint8_t escape; };
+#define EMOJI_ALIAS_COUNT 1
+static const EmojiAlias EMOJI_ALIASES[EMOJI_ALIAS_COUNT] = {
+  { 0x1F08E, 0xA5 }, // domino tile (MWD node signifier) -> domino sprite
+};
+
+static uint32_t emojiDecodeUtf8(const uint8_t* s, int remaining, int* bytes_consumed) {
+  uint8_t b0 = s[0];
+  if (b0 < 0x80) { *bytes_consumed = 1; return b0; }
+  if ((b0 & 0xE0) == 0xC0 && remaining >= 2) {
+    *bytes_consumed = 2;
+    return ((uint32_t)(b0 & 0x1F) << 6) | (s[1] & 0x3F);
+  }
+  if ((b0 & 0xF0) == 0xE0 && remaining >= 3) {
+    *bytes_consumed = 3;
+    return ((uint32_t)(b0 & 0x0F) << 12) | ((uint32_t)(s[1] & 0x3F) << 6) | (s[2] & 0x3F);
+  }
+  if ((b0 & 0xF8) == 0xF0 && remaining >= 4) {
+    *bytes_consumed = 4;
+    return ((uint32_t)(b0 & 0x07) << 18) | ((uint32_t)(s[1] & 0x3F) << 12) | ((uint32_t)(s[2] & 0x3F) << 6) | (s[3] & 0x3F);
+  }
+  *bytes_consumed = 1;
+  return 0xFFFD;
+}
+
+// Convert UTF-8 text to internal format (emoji codepoints -> escape bytes)
+// Now handles ALL multi-byte UTF-8 (>= 0x80) to prevent raw high bytes in buffer
+static void emojiSanitize(const char* src, char* dst, int dstLen) {
+  const uint8_t* s = (const uint8_t*)src;
+  int si = 0, di = 0;
+  int srcLen = strlen(src);
+  while (si < srcLen && di < dstLen - 1) {
+    uint8_t b = s[si];
+    if (b >= 0x80) {
+      int consumed;
+      uint32_t cp = emojiDecodeUtf8(s + si, srcLen - si, &consumed);
+      if (cp == 0xFE0F) { si += consumed; continue; }
+      bool found = false;
+      for (int e = 0; e < EMOJI_COUNT; e++) {
+        if (EMOJI_CODEPOINTS[e].cp == cp) {
+          if (EMOJI_CODEPOINTS[e].cp2 != 0) {
+            int consumed2;
+            if (si + consumed < srcLen) {
+              uint32_t cp2 = emojiDecodeUtf8(s + si + consumed, srcLen - si - consumed, &consumed2);
+              if (cp2 == EMOJI_CODEPOINTS[e].cp2) {
+                dst[di++] = EMOJI_CODEPOINTS[e].escape;
+                si += consumed + consumed2;
+                found = true; break;
+              }
+            }
+            continue;
+          }
+          dst[di++] = EMOJI_CODEPOINTS[e].escape;
+          si += consumed;
+          // Skip trailing variation selector U+FE0F
+          if (si + 2 < srcLen && s[si] == 0xEF && s[si+1] == 0xB8 && s[si+2] == 0x8F) si += 3;
+          found = true; break;
+        }
+      }
+      if (!found) {
+        // Check alias table for variant codepoints
+        for (int a = 0; a < EMOJI_ALIAS_COUNT; a++) {
+          if (EMOJI_ALIASES[a].cp == cp) {
+            dst[di++] = EMOJI_ALIASES[a].escape;
+            si += consumed;
+            // Skip trailing variation selector U+FE0F
+            if (si + 2 < srcLen && s[si] == 0xEF && s[si+1] == 0xB8 && s[si+2] == 0x8F) si += 3;
+            found = true; break;
+          }
+        }
+      }
+      if (!found) si += consumed;  // Skip unknown multi-byte chars
+    } else {
+      dst[di++] = (char)b;
+      si++;
+    }
+  }
+  dst[di] = '\0';
+}
+
+static inline bool isEmojiEscape(uint8_t b) {
+  return b >= EMOJI_ESCAPE_START && b <= EMOJI_ESCAPE_END;
+}
+
+static int emojiEncodeUtf8(uint32_t cp, uint8_t* dst) {
+  if (cp < 0x80) { dst[0] = (uint8_t)cp; return 1; }
+  if (cp < 0x800) { dst[0] = 0xC0|(cp>>6); dst[1] = 0x80|(cp&0x3F); return 2; }
+  if (cp < 0x10000) { dst[0] = 0xE0|(cp>>12); dst[1] = 0x80|((cp>>6)&0x3F); dst[2] = 0x80|(cp&0x3F); return 3; }
+  dst[0] = 0xF0|(cp>>18); dst[1] = 0x80|((cp>>12)&0x3F); dst[2] = 0x80|((cp>>6)&0x3F); dst[3] = 0x80|(cp&0x3F); return 4;
+}
+
+static void emojiUnescape(const char* src, char* dst, int dstLen) {
+  int si = 0, di = 0;
+  int srcLen = strlen(src);
+  while (si < srcLen && di < dstLen - 1) {
+    uint8_t b = (uint8_t)src[si];
+    if (b == EMOJI_PAD_BYTE) { si++; continue; }
+    if (isEmojiEscape(b)) {
+      int idx = b - EMOJI_ESCAPE_START;
+      if (idx < EMOJI_COUNT) {
+        uint8_t utf8[8];
+        int len = emojiEncodeUtf8(EMOJI_CODEPOINTS[idx].cp, utf8);
+        if (EMOJI_CODEPOINTS[idx].cp2 != 0)
+          len += emojiEncodeUtf8(EMOJI_CODEPOINTS[idx].cp2, utf8 + len);
+        if (di + len < dstLen) { memcpy(dst + di, utf8, len); di += len; } else break;
+      }
+      si++;
+    } else { dst[di++] = src[si++]; }
+  }
+  dst[di] = '\0';
+}
+
+static inline const uint8_t* getEmojiSpriteLg(uint8_t escape_byte) {
+  if (!isEmojiEscape(escape_byte)) return nullptr;
+  return (const uint8_t*)pgm_read_ptr(&EMOJI_SPRITES_LG[escape_byte - EMOJI_ESCAPE_START]);
+}
+
+static inline const uint8_t* getEmojiSpriteSm(uint8_t escape_byte) {
+  if (!isEmojiEscape(escape_byte)) return nullptr;
+  return (const uint8_t*)pgm_read_ptr(&EMOJI_SPRITES_SM[escape_byte - EMOJI_ESCAPE_START]);
+}
+
+static inline int emojiUtf8Cost(uint8_t escape_byte) {
+  if (!isEmojiEscape(escape_byte)) return 1;
+  int idx = escape_byte - EMOJI_ESCAPE_START;
+  uint32_t cp = EMOJI_CODEPOINTS[idx].cp;
+  int cost = (cp < 0x80) ? 1 : (cp < 0x800) ? 2 : (cp < 0x10000) ? 3 : 4;
+  if (EMOJI_CODEPOINTS[idx].cp2 != 0) {
+    uint32_t cp2 = EMOJI_CODEPOINTS[idx].cp2;
+    cost += (cp2 < 0x80) ? 1 : (cp2 < 0x800) ? 2 : (cp2 < 0x10000) ? 3 : 4;
+  }
+  return cost;
+}

examples/companion_radio/ui-new/EpubZipReader.h

@@ -0,0 +1,538 @@
+#pragma once
+// =============================================================================
+// EpubZipReader.h - Minimal ZIP reader for EPUB files on ESP32-S3
+//
+// Parses ZIP archives directly from SD card File objects.
+// Uses the ESP32 ROM's built-in tinfl decompressor for DEFLATE.
+// No external library dependencies.
+//
+// Supports:
+//   - STORED (method 0) entries - direct copy
+//   - DEFLATED (method 8) entries - ROM tinfl decompression
+//   - ZIP64 is NOT supported (EPUBs don't need it)
+//
+// Memory: Allocates decompression buffers from PSRAM when available.
+// Typical EPUB chapter is 5-50KB, well within ESP32-S3's 8MB PSRAM.
+// =============================================================================
+
+#include <SD.h>
+#include <FS.h>
+
+// ROM tinfl decompressor - built into ESP32/ESP32-S3 ROM
+// If this include fails on your platform, see the fallback note at bottom
+#if __has_include(<rom/miniz.h>)
+  #include <rom/miniz.h>
+  #define HAS_ROM_TINFL 1
+#elif __has_include(<esp32s3/rom/miniz.h>)
+  #include <esp32s3/rom/miniz.h>
+  #define HAS_ROM_TINFL 1
+#elif __has_include(<esp32/rom/miniz.h>)
+  #include <esp32/rom/miniz.h>
+  #define HAS_ROM_TINFL 1
+#else
+  #warning "ROM miniz not found - DEFLATED entries will not be supported"
+  #define HAS_ROM_TINFL 0
+#endif
+
+// ---- ZIP format constants ----
+#define ZIP_LOCAL_FILE_HEADER_SIG   0x04034b50
+#define ZIP_CENTRAL_DIR_SIG         0x02014b50
+#define ZIP_END_OF_CENTRAL_DIR_SIG  0x06054b50
+
+#define ZIP_METHOD_STORED   0
+#define ZIP_METHOD_DEFLATED 8
+
+// Maximum files we track in a ZIP (EPUBs typically have 20-100 files)
+#define ZIP_MAX_ENTRIES 128
+
+// Maximum filename length within the ZIP
+#define ZIP_MAX_FILENAME 128
+
+// ---- Data structures ----
+
+struct ZipEntry {
+  char     filename[ZIP_MAX_FILENAME];
+  uint16_t compressionMethod;   // 0=STORED, 8=DEFLATED
+  uint32_t compressedSize;
+  uint32_t uncompressedSize;
+  uint32_t localHeaderOffset;   // Offset to local file header in ZIP
+  uint32_t crc32;
+};
+
+// ---- Helper: read little-endian values from a byte buffer ----
+
+static inline uint16_t zipRead16(const uint8_t* p) {
+  return (uint16_t)p[0] | ((uint16_t)p[1] << 8);
+}
+
+static inline uint32_t zipRead32(const uint8_t* p) {
+  return (uint32_t)p[0] | ((uint32_t)p[1] << 8) |
+         ((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24);
+}
+
+// =============================================================================
+// EpubZipReader class
+// =============================================================================
+
+class EpubZipReader {
+public:
+  EpubZipReader() : _entryCount(0), _isOpen(false), _entries(nullptr) {
+    // Allocate entries array from PSRAM to avoid stack overflow
+    // (128 entries × ~146 bytes = ~19KB — too large for 8KB loopTask stack)
+#ifdef BOARD_HAS_PSRAM
+    _entries = (ZipEntry*)ps_malloc(ZIP_MAX_ENTRIES * sizeof(ZipEntry));
+#endif
+    if (!_entries) {
+      _entries = (ZipEntry*)malloc(ZIP_MAX_ENTRIES * sizeof(ZipEntry));
+    }
+    if (!_entries) {
+      Serial.println("ZipReader: FATAL - failed to allocate entry table");
+    }
+  }
+
+  ~EpubZipReader() {
+    if (_entries) {
+      free(_entries);
+      _entries = nullptr;
+    }
+  }
+
+  // ----------------------------------------------------------
+  // Open a ZIP file and parse its central directory.
+  // Returns true on success, false on error.
+  // After open(), entries are available via getEntryCount()/getEntry().
+  // ----------------------------------------------------------
+  bool open(File& zipFile) {
+    _isOpen = false;
+    _entryCount = 0;
+
+    if (!_entries) {
+      Serial.println("ZipReader: entry table not allocated");
+      return false;
+    }
+
+    if (!zipFile || !zipFile.available()) {
+      Serial.println("ZipReader: file not valid");
+      return false;
+    }
+
+    _file = zipFile;
+    uint32_t fileSize = _file.size();
+
+    if (fileSize < 22) {
+      Serial.println("ZipReader: file too small for ZIP");
+      return false;
+    }
+
+    // ---- Step 1: Find the End of Central Directory record ----
+    // EOCD is at least 22 bytes, at end of file.
+    // Search backwards from end for the EOCD signature.
+    // Comment can be up to 65535 bytes, but EPUBs typically have none.
+    uint32_t searchStart = (fileSize > 65557) ? (fileSize - 65557) : 0;
+    uint32_t eocdOffset = 0;
+    bool foundEocd = false;
+
+    // Read the last chunk into a buffer to search for EOCD signature
+    uint32_t searchLen = fileSize - searchStart;
+    // Cap search buffer to a reasonable size
+    if (searchLen > 1024) {
+      searchStart = fileSize - 1024;
+      searchLen = 1024;
+    }
+
+    uint8_t* searchBuf = (uint8_t*)_allocBuffer(searchLen);
+    if (!searchBuf) {
+      Serial.println("ZipReader: failed to alloc search buffer");
+      return false;
+    }
+
+    _file.seek(searchStart);
+    if (_file.read(searchBuf, searchLen) != (int)searchLen) {
+      free(searchBuf);
+      Serial.println("ZipReader: failed to read EOCD area");
+      return false;
+    }
+
+    // Scan backwards for EOCD signature (0x06054b50)
+    for (int i = (int)searchLen - 22; i >= 0; i--) {
+      if (zipRead32(&searchBuf[i]) == ZIP_END_OF_CENTRAL_DIR_SIG) {
+        eocdOffset = searchStart + i;
+        // Parse EOCD fields
+        uint16_t totalEntries = zipRead16(&searchBuf[i + 10]);
+        uint32_t cdSize       = zipRead32(&searchBuf[i + 12]);
+        uint32_t cdOffset     = zipRead32(&searchBuf[i + 16]);
+
+        _cdOffset = cdOffset;
+        _cdSize = cdSize;
+        _totalEntries = totalEntries;
+        foundEocd = true;
+        break;
+      }
+    }
+    free(searchBuf);
+
+    if (!foundEocd) {
+      Serial.println("ZipReader: EOCD not found - not a valid ZIP");
+      return false;
+    }
+
+    Serial.printf("ZipReader: EOCD found at %u, %u entries, CD at %u (%u bytes)\n",
+                  eocdOffset, _totalEntries, _cdOffset, _cdSize);
+
+    // ---- Step 2: Parse Central Directory entries ----
+    if (_cdSize == 0 || _cdSize > 512 * 1024) {
+      Serial.println("ZipReader: central directory size unreasonable");
+      return false;
+    }
+
+    uint8_t* cdBuf = (uint8_t*)_allocBuffer(_cdSize);
+    if (!cdBuf) {
+      Serial.printf("ZipReader: failed to alloc %u bytes for central directory\n", _cdSize);
+      return false;
+    }
+
+    _file.seek(_cdOffset);
+    if (_file.read(cdBuf, _cdSize) != (int)_cdSize) {
+      free(cdBuf);
+      Serial.println("ZipReader: failed to read central directory");
+      return false;
+    }
+
+    uint32_t pos = 0;
+    _entryCount = 0;
+
+    while (pos + 46 <= _cdSize && _entryCount < ZIP_MAX_ENTRIES) {
+      if (zipRead32(&cdBuf[pos]) != ZIP_CENTRAL_DIR_SIG) {
+        break;  // No more central directory entries
+      }
+
+      uint16_t method       = zipRead16(&cdBuf[pos + 10]);
+      uint32_t crc          = zipRead32(&cdBuf[pos + 16]);
+      uint32_t compSize     = zipRead32(&cdBuf[pos + 20]);
+      uint32_t uncompSize   = zipRead32(&cdBuf[pos + 24]);
+      uint16_t fnLen        = zipRead16(&cdBuf[pos + 28]);
+      uint16_t extraLen     = zipRead16(&cdBuf[pos + 30]);
+      uint16_t commentLen   = zipRead16(&cdBuf[pos + 32]);
+      uint32_t localOffset  = zipRead32(&cdBuf[pos + 42]);
+
+      // Copy filename (truncate if necessary)
+      int copyLen = (fnLen < ZIP_MAX_FILENAME - 1) ? fnLen : ZIP_MAX_FILENAME - 1;
+      memcpy(_entries[_entryCount].filename, &cdBuf[pos + 46], copyLen);
+      _entries[_entryCount].filename[copyLen] = '\0';
+
+      _entries[_entryCount].compressionMethod = method;
+      _entries[_entryCount].compressedSize = compSize;
+      _entries[_entryCount].uncompressedSize = uncompSize;
+      _entries[_entryCount].localHeaderOffset = localOffset;
+      _entries[_entryCount].crc32 = crc;
+
+      // Skip directories (filenames ending with '/')
+      if (copyLen > 0 && _entries[_entryCount].filename[copyLen - 1] != '/') {
+        _entryCount++;
+      }
+
+      // Advance past this central directory entry
+      pos += 46 + fnLen + extraLen + commentLen;
+    }
+
+    free(cdBuf);
+
+    Serial.printf("ZipReader: parsed %d file entries\n", _entryCount);
+    _isOpen = true;
+    return true;
+  }
+
+  // ----------------------------------------------------------
+  // Close the reader (does not close the underlying File).
+  // ----------------------------------------------------------
+  void close() {
+    _isOpen = false;
+    _entryCount = 0;
+  }
+
+  // ----------------------------------------------------------
+  // Get entry count and entries
+  // ----------------------------------------------------------
+  int getEntryCount() const { return _entryCount; }
+
+  const ZipEntry* getEntry(int index) const {
+    if (index < 0 || index >= _entryCount) return nullptr;
+    return &_entries[index];
+  }
+
+  // ----------------------------------------------------------
+  // Find an entry by filename (case-sensitive).
+  // Returns index, or -1 if not found.
+  // ----------------------------------------------------------
+  int findEntry(const char* filename) const {
+    for (int i = 0; i < _entryCount; i++) {
+      if (strcmp(_entries[i].filename, filename) == 0) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  // ----------------------------------------------------------
+  // Find an entry by filename suffix (e.g., ".opf", ".ncx").
+  // Returns index of first match, or -1 if not found.
+  // ----------------------------------------------------------
+  int findEntryBySuffix(const char* suffix) const {
+    int suffixLen = strlen(suffix);
+    for (int i = 0; i < _entryCount; i++) {
+      int fnLen = strlen(_entries[i].filename);
+      if (fnLen >= suffixLen &&
+          strcasecmp(&_entries[i].filename[fnLen - suffixLen], suffix) == 0) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  // ----------------------------------------------------------
+  // Find entries matching a path prefix (e.g., "OEBPS/").
+  // Fills matchIndices[] up to maxMatches. Returns count found.
+  // ----------------------------------------------------------
+  int findEntriesByPrefix(const char* prefix, int* matchIndices, int maxMatches) const {
+    int count = 0;
+    int prefixLen = strlen(prefix);
+    for (int i = 0; i < _entryCount && count < maxMatches; i++) {
+      if (strncmp(_entries[i].filename, prefix, prefixLen) == 0) {
+        matchIndices[count++] = i;
+      }
+    }
+    return count;
+  }
+
+  // ----------------------------------------------------------
+  // Extract a file entry to a newly allocated buffer.
+  //
+  // On success, returns a malloc'd buffer (caller must free!)
+  // and sets *outSize to the uncompressed size.
+  //
+  // On failure, returns nullptr.
+  //
+  // The buffer is allocated from PSRAM if available.
+  // ----------------------------------------------------------
+  uint8_t* extractEntry(int index, uint32_t* outSize) {
+    if (!_isOpen || index < 0 || index >= _entryCount) {
+      return nullptr;
+    }
+
+    const ZipEntry& entry = _entries[index];
+
+    // ---- Read the local file header to get actual data offset ----
+    // Local header: 30 bytes fixed + variable filename + extra field
+    uint8_t localHeader[30];
+    _file.seek(entry.localHeaderOffset);
+    if (_file.read(localHeader, 30) != 30) {
+      Serial.println("ZipReader: failed to read local header");
+      return nullptr;
+    }
+
+    if (zipRead32(localHeader) != ZIP_LOCAL_FILE_HEADER_SIG) {
+      Serial.println("ZipReader: bad local header signature");
+      return nullptr;
+    }
+
+    uint16_t localFnLen    = zipRead16(&localHeader[26]);
+    uint16_t localExtraLen = zipRead16(&localHeader[28]);
+    uint32_t dataOffset = entry.localHeaderOffset + 30 + localFnLen + localExtraLen;
+
+    // ---- Handle based on compression method ----
+    if (entry.compressionMethod == ZIP_METHOD_STORED) {
+      return _extractStored(dataOffset, entry.uncompressedSize, outSize);
+    }
+    else if (entry.compressionMethod == ZIP_METHOD_DEFLATED) {
+      return _extractDeflated(dataOffset, entry.compressedSize,
+                              entry.uncompressedSize, outSize);
+    }
+    else {
+      Serial.printf("ZipReader: unsupported compression method %d for %s\n",
+                    entry.compressionMethod, entry.filename);
+      return nullptr;
+    }
+  }
+
+  // ----------------------------------------------------------
+  // Extract a file entry by filename.
+  // Convenience wrapper around findEntry() + extractEntry().
+  // ----------------------------------------------------------
+  uint8_t* extractByName(const char* filename, uint32_t* outSize) {
+    int idx = findEntry(filename);
+    if (idx < 0) return nullptr;
+    return extractEntry(idx, outSize);
+  }
+
+  // ----------------------------------------------------------
+  // Check if reader is open and valid
+  // ----------------------------------------------------------
+  bool isOpen() const { return _isOpen; }
+
+  // ----------------------------------------------------------
+  // Debug: print all entries
+  // ----------------------------------------------------------
+  void printEntries() const {
+    Serial.printf("ZIP contains %d files:\n", _entryCount);
+    for (int i = 0; i < _entryCount; i++) {
+      const ZipEntry& e = _entries[i];
+      Serial.printf("  [%d] %s (%s, %u -> %u bytes)\n",
+                    i, e.filename,
+                    e.compressionMethod == 0 ? "STORED" : "DEFLATED",
+                    e.compressedSize, e.uncompressedSize);
+    }
+  }
+
+private:
+  File       _file;
+  ZipEntry*  _entries;           // Heap-allocated (PSRAM) entry table
+  int        _entryCount;
+  bool       _isOpen;
+  uint32_t   _cdOffset;
+  uint32_t   _cdSize;
+  uint16_t   _totalEntries;
+
+  // ----------------------------------------------------------
+  // Allocate buffer, preferring PSRAM if available
+  // ----------------------------------------------------------
+  void* _allocBuffer(size_t size) {
+    void* buf = nullptr;
+#ifdef BOARD_HAS_PSRAM
+    buf = ps_malloc(size);
+#endif
+    if (!buf) {
+      buf = malloc(size);
+    }
+    return buf;
+  }
+
+  // ----------------------------------------------------------
+  // Extract a STORED (uncompressed) entry
+  // ----------------------------------------------------------
+  uint8_t* _extractStored(uint32_t dataOffset, uint32_t size, uint32_t* outSize) {
+    uint8_t* buf = (uint8_t*)_allocBuffer(size + 1);  // +1 for null terminator
+    if (!buf) {
+      Serial.printf("ZipReader: failed to alloc %u bytes for stored entry\n", size);
+      return nullptr;
+    }
+
+    _file.seek(dataOffset);
+    uint32_t bytesRead = _file.read(buf, size);
+    if (bytesRead != size) {
+      Serial.printf("ZipReader: short read (got %u, expected %u)\n", bytesRead, size);
+      free(buf);
+      return nullptr;
+    }
+
+    buf[size] = '\0';  // Null-terminate for text files
+    *outSize = size;
+
+    // Release SD CS pin for other SPI users
+    digitalWrite(SDCARD_CS, HIGH);
+
+    return buf;
+  }
+
+  // ----------------------------------------------------------
+  // Extract a DEFLATED entry using ROM tinfl
+  // ----------------------------------------------------------
+  uint8_t* _extractDeflated(uint32_t dataOffset, uint32_t compSize,
+                            uint32_t uncompSize, uint32_t* outSize) {
+#if HAS_ROM_TINFL
+    // Allocate compressed data buffer (from PSRAM)
+    uint8_t* compBuf = (uint8_t*)_allocBuffer(compSize);
+    if (!compBuf) {
+      Serial.printf("ZipReader: failed to alloc %u bytes for compressed data\n", compSize);
+      return nullptr;
+    }
+
+    // Allocate output buffer (+1 for null terminator)
+    uint8_t* outBuf = (uint8_t*)_allocBuffer(uncompSize + 1);
+    if (!outBuf) {
+      Serial.printf("ZipReader: failed to alloc %u bytes for decompressed data\n", uncompSize);
+      free(compBuf);
+      return nullptr;
+    }
+
+    // Heap-allocate the decompressor (~11KB struct - too large for 8KB loopTask stack!)
+    tinfl_decompressor* decomp = (tinfl_decompressor*)_allocBuffer(sizeof(tinfl_decompressor));
+    if (!decomp) {
+      Serial.printf("ZipReader: failed to alloc tinfl_decompressor (%u bytes)\n",
+                    (uint32_t)sizeof(tinfl_decompressor));
+      free(compBuf);
+      free(outBuf);
+      return nullptr;
+    }
+
+    // Read compressed data from file
+    _file.seek(dataOffset);
+    if (_file.read(compBuf, compSize) != (int)compSize) {
+      Serial.println("ZipReader: failed to read compressed data");
+      free(decomp);
+      free(compBuf);
+      free(outBuf);
+      return nullptr;
+    }
+
+    // Release SD CS pin for other SPI users
+    digitalWrite(SDCARD_CS, HIGH);
+
+    // Decompress using ROM tinfl (low-level API to avoid stack allocation)
+    // ZIP DEFLATE is raw deflate (no zlib header).
+    tinfl_init(decomp);
+
+    size_t inBytes = compSize;
+    size_t outBytes = uncompSize;
+    tinfl_status status = tinfl_decompress(
+      decomp,
+      (const mz_uint8*)compBuf,    // compressed input
+      &inBytes,                     // in: available, out: consumed
+      outBuf,                       // output buffer base
+      outBuf,                       // current output position
+      &outBytes,                    // in: available, out: produced
+      TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF  // raw deflate, single-shot
+    );
+
+    free(decomp);
+    free(compBuf);
+
+    if (status != TINFL_STATUS_DONE) {
+      Serial.printf("ZipReader: DEFLATE failed (status %d)\n", (int)status);
+      free(outBuf);
+      return nullptr;
+    }
+
+    outBuf[outBytes] = '\0';  // Null-terminate for text files
+    *outSize = (uint32_t)outBytes;
+
+    if (outBytes != uncompSize) {
+      Serial.printf("ZipReader: decompressed %u bytes, expected %u\n",
+                    (uint32_t)outBytes, uncompSize);
+    }
+
+    return outBuf;
+
+#else
+    // No ROM tinfl available
+    Serial.println("ZipReader: DEFLATE not supported (no ROM tinfl)");
+    *outSize = 0;
+    return nullptr;
+#endif
+  }
+};
+
+// =============================================================================
+// FALLBACK NOTE:
+//
+// If the ROM tinfl includes fail to compile on your ESP32 variant, you have
+// two options:
+//
+// 1. Install lbernstone/miniz-esp32 from PlatformIO:
+//      lib_deps = https://github.com/lbernstone/miniz-esp32.git
+//    Then change the includes above to: #include <miniz.h>
+//
+// 2. Copy just the tinfl source (~550 lines) from:
+//      https://github.com/richgel999/miniz/blob/master/miniz_tinfl.c
+//    into your project. Only tinfl_decompress_mem_to_mem() is needed.
+//
+// =============================================================================

examples/companion_radio/ui-new/Epubprocessor.h

@@ -0,0 +1,888 @@
+#pragma once
+// =============================================================================
+// EpubProcessor.h - Convert EPUB files to plain text for TextReaderScreen
+//
+// Pipeline: EPUB (ZIP) → container.xml → OPF spine → extract chapters →
+//           strip XHTML tags → concatenated plain text → cached .txt on SD
+//
+// The resulting .txt file is placed in /books/ and picked up automatically
+// by TextReaderScreen's existing pagination, indexing, and bookmarking.
+//
+// Dependencies: EpubZipReader.h (for ZIP extraction)
+// =============================================================================
+
+#include <SD.h>
+#include <FS.h>
+#include "EpubZipReader.h"
+#include "Utf8CP437.h"
+
+// Maximum chapters in spine (most novels have 20-80)
+#define EPUB_MAX_CHAPTERS 200
+
+// Maximum manifest items we track
+#define EPUB_MAX_MANIFEST 256
+
+// Buffer size for reading OPF/container XML
+// (These are small files, typically 1-20KB)
+#define EPUB_XML_BUF_SIZE 64
+
+class EpubProcessor {
+public:
+
+  // ----------------------------------------------------------
+  // Process an EPUB file: extract text and write to SD cache.
+  //
+  // epubPath:  source, e.g. "/books/The Iliad.epub"
+  // txtPath:   output, e.g. "/books/The Iliad by Homer.txt"
+  //
+  // Returns true if the .txt file was written successfully.
+  // If txtPath already exists, returns true immediately (cached).
+  // ----------------------------------------------------------
+  static bool processToText(const char* epubPath, const char* txtPath) {
+    // Check if already cached
+    if (SD.exists(txtPath)) {
+      Serial.printf("EpubProc: '%s' already cached\n", txtPath);
+      return true;
+    }
+
+    Serial.printf("EpubProc: Processing '%s'\n", epubPath);
+    unsigned long t0 = millis();
+
+    // Open the EPUB (ZIP archive)
+    File epubFile = SD.open(epubPath, FILE_READ);
+    if (!epubFile) {
+      Serial.println("EpubProc: Cannot open EPUB file");
+      return false;
+    }
+
+    // Heap-allocate zip reader (entries table is ~19KB)
+    EpubZipReader* zip = new EpubZipReader();
+    if (!zip) {
+      epubFile.close();
+      Serial.println("EpubProc: Cannot allocate ZipReader");
+      return false;
+    }
+
+    if (!zip->open(epubFile)) {
+      delete zip;
+      epubFile.close();
+      Serial.println("EpubProc: Cannot parse ZIP structure");
+      return false;
+    }
+
+    // Step 1: Find OPF path from container.xml
+    char opfPath[EPUB_XML_BUF_SIZE];
+    opfPath[0] = '\0';
+    if (!_findOpfPath(zip, opfPath, sizeof(opfPath))) {
+      delete zip;
+      epubFile.close();
+      Serial.println("EpubProc: Cannot find OPF path");
+      return false;
+    }
+    Serial.printf("EpubProc: OPF at '%s'\n", opfPath);
+
+    // Determine the content base directory (e.g., "OEBPS/")
+    char baseDir[EPUB_XML_BUF_SIZE];
+    _getDirectory(opfPath, baseDir, sizeof(baseDir));
+
+    // Step 2: Parse OPF to get title and spine chapter order
+    char title[128];
+    title[0] = '\0';
+
+    // Chapter paths in spine order
+    char** chapterPaths = nullptr;
+    int chapterCount = 0;
+
+    if (!_parseOpf(zip, opfPath, baseDir, title, sizeof(title),
+                   &chapterPaths, &chapterCount)) {
+      delete zip;
+      epubFile.close();
+      Serial.println("EpubProc: Cannot parse OPF");
+      return false;
+    }
+
+    Serial.printf("EpubProc: Title='%s', %d chapters\n", title, chapterCount);
+
+    // Step 3: Extract each chapter, strip XHTML, write to output .txt
+    File outFile = SD.open(txtPath, FILE_WRITE);
+    if (!outFile) {
+      _freeChapterPaths(chapterPaths, chapterCount);
+      delete zip;
+      epubFile.close();
+      Serial.printf("EpubProc: Cannot create '%s'\n", txtPath);
+      return false;
+    }
+
+    // Write title as first line
+    if (title[0]) {
+      outFile.println(title);
+      outFile.println();
+    }
+
+    int chaptersWritten = 0;
+    uint32_t totalBytes = 0;
+
+    for (int i = 0; i < chapterCount; i++) {
+      int entryIdx = zip->findEntry(chapterPaths[i]);
+      if (entryIdx < 0) {
+        Serial.printf("EpubProc: Chapter not found: '%s'\n", chapterPaths[i]);
+        continue;
+      }
+
+      uint32_t rawSize = 0;
+      uint8_t* rawData = zip->extractEntry(entryIdx, &rawSize);
+      if (!rawData || rawSize == 0) {
+        Serial.printf("EpubProc: Failed to extract chapter %d\n", i);
+        if (rawData) free(rawData);
+        continue;
+      }
+
+      // Strip XHTML tags and write plain text
+      uint32_t textLen = 0;
+      uint8_t* plainText = _stripXhtml(rawData, rawSize, &textLen);
+      free(rawData);
+
+      if (plainText && textLen > 0) {
+        outFile.write(plainText, textLen);
+        // Add chapter separator
+        outFile.print("\n\n");
+        totalBytes += textLen + 2;
+        chaptersWritten++;
+      }
+      if (plainText) free(plainText);
+    }
+
+    outFile.flush();
+    outFile.close();
+
+    // Release SD CS for other SPI users
+    digitalWrite(SDCARD_CS, HIGH);
+
+    _freeChapterPaths(chapterPaths, chapterCount);
+    delete zip;
+    epubFile.close();
+
+    unsigned long elapsed = millis() - t0;
+    Serial.printf("EpubProc: Done! %d chapters, %u bytes in %lu ms -> '%s'\n",
+                  chaptersWritten, totalBytes, elapsed, txtPath);
+
+    return chaptersWritten > 0;
+  }
+
+  // ----------------------------------------------------------
+  // Extract just the title from an EPUB (for display in file list).
+  // Returns false if it can't be determined.
+  // ----------------------------------------------------------
+  static bool getTitle(const char* epubPath, char* titleBuf, int titleBufSize) {
+    File epubFile = SD.open(epubPath, FILE_READ);
+    if (!epubFile) return false;
+
+    EpubZipReader* zip = new EpubZipReader();
+    if (!zip) { epubFile.close(); return false; }
+
+    if (!zip->open(epubFile)) {
+      delete zip; epubFile.close(); return false;
+    }
+
+    char opfPath[EPUB_XML_BUF_SIZE];
+    if (!_findOpfPath(zip, opfPath, sizeof(opfPath))) {
+      delete zip; epubFile.close(); return false;
+    }
+
+    // Extract OPF and find <dc:title>
+    int opfIdx = zip->findEntry(opfPath);
+    if (opfIdx < 0) { delete zip; epubFile.close(); return false; }
+
+    uint32_t opfSize = 0;
+    uint8_t* opfData = zip->extractEntry(opfIdx, &opfSize);
+    delete zip;
+    epubFile.close();
+
+    if (!opfData) return false;
+
+    bool found = _extractTagContent((const char*)opfData, opfSize,
+                                     "dc:title", titleBuf, titleBufSize);
+    free(opfData);
+    return found;
+  }
+
+  // ----------------------------------------------------------
+  // Build a cache .txt path from an .epub path.
+  // e.g., "/books/mybook.epub" -> "/books/.epub_cache/mybook.txt"
+  // ----------------------------------------------------------
+  static void buildCachePath(const char* epubPath, char* cachePath, int cachePathSize) {
+    // Extract filename without extension
+    const char* lastSlash = strrchr(epubPath, '/');
+    const char* filename = lastSlash ? lastSlash + 1 : epubPath;
+    
+    // Find the directory part
+    char dir[128];
+    if (lastSlash) {
+      int dirLen = lastSlash - epubPath;
+      if (dirLen >= (int)sizeof(dir)) dirLen = sizeof(dir) - 1;
+      strncpy(dir, epubPath, dirLen);
+      dir[dirLen] = '\0';
+    } else {
+      strcpy(dir, "/books");
+    }
+
+    // Create cache directory if needed
+    char cacheDir[160];
+    snprintf(cacheDir, sizeof(cacheDir), "%s/.epub_cache", dir);
+    if (!SD.exists(cacheDir)) {
+      SD.mkdir(cacheDir);
+    }
+
+    // Strip .epub extension
+    char baseName[128];
+    strncpy(baseName, filename, sizeof(baseName) - 1);
+    baseName[sizeof(baseName) - 1] = '\0';
+    char* dot = strrchr(baseName, '.');
+    if (dot) *dot = '\0';
+
+    snprintf(cachePath, cachePathSize, "%s/%s.txt", cacheDir, baseName);
+  }
+
+private:
+
+  // ----------------------------------------------------------
+  // Parse container.xml to find the OPF file path.
+  // Returns true if found.
+  // ----------------------------------------------------------
+  static bool _findOpfPath(EpubZipReader* zip, char* opfPath, int opfPathSize) {
+    int idx = zip->findEntry("META-INF/container.xml");
+    if (idx < 0) {
+      // Fallback: find any .opf file directly
+      idx = zip->findEntryBySuffix(".opf");
+      if (idx >= 0) {
+        const ZipEntry* e = zip->getEntry(idx);
+        strncpy(opfPath, e->filename, opfPathSize - 1);
+        opfPath[opfPathSize - 1] = '\0';
+        return true;
+      }
+      return false;
+    }
+
+    uint32_t size = 0;
+    uint8_t* data = zip->extractEntry(idx, &size);
+    if (!data) return false;
+
+    // Find: full-path="OEBPS/content.opf"
+    bool found = _extractAttribute((const char*)data, size,
+                                    "full-path", opfPath, opfPathSize);
+    free(data);
+    return found;
+  }
+
+  // ----------------------------------------------------------
+  // Parse OPF to extract title, build manifest, and resolve spine.
+  //
+  // Populates chapterPaths (heap-allocated array of strings) with
+  // full ZIP paths for each chapter in spine order.
+  // Caller must free with _freeChapterPaths().
+  // ----------------------------------------------------------
+  static bool _parseOpf(EpubZipReader* zip, const char* opfPath,
+                         const char* baseDir, char* title, int titleSize,
+                         char*** outChapterPaths, int* outChapterCount) {
+    int opfIdx = zip->findEntry(opfPath);
+    if (opfIdx < 0) return false;
+
+    uint32_t opfSize = 0;
+    uint8_t* opfData = zip->extractEntry(opfIdx, &opfSize);
+    if (!opfData) return false;
+
+    const char* xml = (const char*)opfData;
+
+    // Extract title
+    _extractTagContent(xml, opfSize, "dc:title", title, titleSize);
+
+    // Build manifest: map id -> href
+    // We use two parallel arrays to avoid complex data structures
+    struct ManifestItem {
+      char id[64];
+      char href[128];
+      bool isContent;  // has media-type containing "html" or "xml"
+    };
+
+    // Heap-allocate manifest (could be large)
+    ManifestItem* manifest = (ManifestItem*)ps_malloc(
+        EPUB_MAX_MANIFEST * sizeof(ManifestItem));
+    if (!manifest) {
+      manifest = (ManifestItem*)malloc(EPUB_MAX_MANIFEST * sizeof(ManifestItem));
+    }
+    if (!manifest) {
+      free(opfData);
+      return false;
+    }
+    int manifestCount = 0;
+
+    // Parse <item> elements from <manifest>
+    const char* manifestStart = _findTag(xml, opfSize, "<manifest");
+    const char* manifestEnd = manifestStart ?
+        _findTag(manifestStart, opfSize - (manifestStart - xml), "</manifest") : nullptr;
+    if (!manifestEnd) manifestEnd = xml + opfSize;
+
+    if (manifestStart) {
+      const char* pos = manifestStart;
+      while (pos < manifestEnd && manifestCount < EPUB_MAX_MANIFEST) {
+        pos = _findTag(pos, manifestEnd - pos, "<item");
+        if (!pos || pos >= manifestEnd) break;
+
+        // Find the closing > of this <item ... />
+        const char* tagEnd = (const char*)memchr(pos, '>', manifestEnd - pos);
+        if (!tagEnd) break;
+        tagEnd++;
+
+        ManifestItem& item = manifest[manifestCount];
+        item.id[0] = '\0';
+        item.href[0] = '\0';
+        item.isContent = false;
+
+        _extractAttributeFromTag(pos, tagEnd - pos, "id",
+                                  item.id, sizeof(item.id));
+        _extractAttributeFromTag(pos, tagEnd - pos, "href",
+                                  item.href, sizeof(item.href));
+
+        // Check media-type for content files
+        char mediaType[64];
+        mediaType[0] = '\0';
+        _extractAttributeFromTag(pos, tagEnd - pos, "media-type",
+                                  mediaType, sizeof(mediaType));
+        item.isContent = (strstr(mediaType, "html") != nullptr ||
+                          strstr(mediaType, "xml") != nullptr);
+
+        if (item.id[0] && item.href[0]) {
+          manifestCount++;
+        }
+
+        pos = tagEnd;
+      }
+    }
+
+    Serial.printf("EpubProc: Manifest has %d items\n", manifestCount);
+
+    // Parse <spine> to get reading order
+    // Spine contains <itemref idref="..."/> elements
+    const char* spineStart = _findTag(xml, opfSize, "<spine");
+    const char* spineEnd = spineStart ?
+        _findTag(spineStart, opfSize - (spineStart - xml), "</spine") : nullptr;
+    if (!spineEnd) spineEnd = xml + opfSize;
+
+    // Collect spine idrefs
+    char** chapterPaths = (char**)ps_malloc(EPUB_MAX_CHAPTERS * sizeof(char*));
+    if (!chapterPaths) chapterPaths = (char**)malloc(EPUB_MAX_CHAPTERS * sizeof(char*));
+    if (!chapterPaths) {
+      free(manifest);
+      free(opfData);
+      return false;
+    }
+    int chapterCount = 0;
+
+    if (spineStart) {
+      const char* pos = spineStart;
+      while (pos < spineEnd && chapterCount < EPUB_MAX_CHAPTERS) {
+        pos = _findTag(pos, spineEnd - pos, "<itemref");
+        if (!pos || pos >= spineEnd) break;
+
+        const char* tagEnd = (const char*)memchr(pos, '>', spineEnd - pos);
+        if (!tagEnd) break;
+        tagEnd++;
+
+        char idref[64];
+        idref[0] = '\0';
+        _extractAttributeFromTag(pos, tagEnd - pos, "idref",
+                                  idref, sizeof(idref));
+
+        if (idref[0]) {
+          // Look up in manifest
+          for (int m = 0; m < manifestCount; m++) {
+            if (strcmp(manifest[m].id, idref) == 0 && manifest[m].isContent) {
+              // Build full path: baseDir + href
+              int pathLen = strlen(baseDir) + strlen(manifest[m].href) + 1;
+              char* fullPath = (char*)malloc(pathLen);
+              if (fullPath) {
+                snprintf(fullPath, pathLen, "%s%s", baseDir, manifest[m].href);
+                chapterPaths[chapterCount++] = fullPath;
+              }
+              break;
+            }
+          }
+        }
+
+        pos = tagEnd;
+      }
+    }
+
+    free(manifest);
+    free(opfData);
+
+    *outChapterPaths = chapterPaths;
+    *outChapterCount = chapterCount;
+
+    return chapterCount > 0;
+  }
+
+  // ----------------------------------------------------------
+  // Strip XHTML/HTML tags from raw content, producing plain text.
+  //
+  // Handles:
+  //   - Tag removal (everything between < and >)
+  //   - <p>, <br>, <div>, <h1>-<h6> → newlines
+  //   - HTML entity decoding (&amp; &lt; &gt; &quot; &apos; &#NNN; &#xHH;)
+  //   - Collapse multiple whitespace/newlines
+  //   - Skip <head>, <style>, <script> content entirely
+  //
+  // Returns heap-allocated buffer (caller must free).
+  // ----------------------------------------------------------
+  static uint8_t* _stripXhtml(const uint8_t* input, uint32_t inputLen,
+                               uint32_t* outLen) {
+    // Output can't be larger than input
+    uint8_t* output = (uint8_t*)ps_malloc(inputLen + 1);
+    if (!output) output = (uint8_t*)malloc(inputLen + 1);
+    if (!output) { *outLen = 0; return nullptr; }
+
+    uint32_t outPos = 0;
+    bool inTag = false;
+    bool skipContent = false;  // Inside <head>, <style>, <script>
+    char tagName[32];
+    int tagNamePos = 0;
+    bool tagNameDone = false;
+    bool isClosingTag = false;
+    bool lastWasNewline = false;
+    bool lastWasSpace = false;
+
+    // Skip to <body> if present (ignore everything before it)
+    const uint8_t* start = input;
+    const uint8_t* inputEnd = input + inputLen;
+    const char* bodyStart = _findTagCI((const char*)input, inputLen, "<body");
+    if (bodyStart) {
+      const char* bodyTagEnd = (const char*)memchr(bodyStart, '>', 
+          inputEnd - (const uint8_t*)bodyStart);
+      if (bodyTagEnd) {
+        start = (const uint8_t*)(bodyTagEnd + 1);
+      }
+    }
+    const uint8_t* end = inputEnd;
+
+    for (const uint8_t* p = start; p < end; p++) {
+      char c = (char)*p;
+
+      if (inTag) {
+        // Collecting tag name
+        if (!tagNameDone) {
+          if (tagNamePos == 0 && c == '/') {
+            isClosingTag = true;
+            continue;
+          }
+          if (c == '>' || c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '/') {
+            tagName[tagNamePos] = '\0';
+            tagNameDone = true;
+          } else if (tagNamePos < (int)sizeof(tagName) - 1) {
+            tagName[tagNamePos++] = (c >= 'A' && c <= 'Z') ? (c + 32) : c;
+          }
+        }
+
+        if (c == '>') {
+          inTag = false;
+
+          // Handle skip regions
+          if (!isClosingTag) {
+            if (strcmp(tagName, "head") == 0 ||
+                strcmp(tagName, "style") == 0 ||
+                strcmp(tagName, "script") == 0) {
+              skipContent = true;
+            }
+          } else {
+            if (strcmp(tagName, "head") == 0 ||
+                strcmp(tagName, "style") == 0 ||
+                strcmp(tagName, "script") == 0) {
+              skipContent = false;
+            }
+          }
+
+          if (!skipContent) {
+            // Block-level elements produce newlines
+            if (strcmp(tagName, "p") == 0 ||
+                strcmp(tagName, "div") == 0 ||
+                strcmp(tagName, "br") == 0 ||
+                strcmp(tagName, "h1") == 0 ||
+                strcmp(tagName, "h2") == 0 ||
+                strcmp(tagName, "h3") == 0 ||
+                strcmp(tagName, "h4") == 0 ||
+                strcmp(tagName, "h5") == 0 ||
+                strcmp(tagName, "h6") == 0 ||
+                strcmp(tagName, "li") == 0 ||
+                strcmp(tagName, "tr") == 0 ||
+                strcmp(tagName, "blockquote") == 0 ||
+                strcmp(tagName, "hr") == 0) {
+              if (outPos > 0 && !lastWasNewline) {
+                output[outPos++] = '\n';
+                lastWasNewline = true;
+                lastWasSpace = false;
+              }
+            }
+          }
+
+          continue;
+        }
+        continue;
+      }
+
+      // Not in a tag
+      if (c == '<') {
+        inTag = true;
+        tagNamePos = 0;
+        tagNameDone = false;
+        isClosingTag = false;
+        continue;
+      }
+
+      if (skipContent) continue;
+
+      // Handle HTML entities
+      if (c == '&') {
+        char decoded = _decodeEntity(p, end, &p);
+        if (decoded) {
+          c = decoded;
+          // p now points to the ';' or last char of entity; loop will increment
+        }
+      }
+
+      // Handle UTF-8 multi-byte sequences (smart quotes, em dashes, accented chars, etc.)
+      // These appear as raw bytes in XHTML. Typographic chars are mapped to ASCII;
+      // accented Latin chars are preserved as UTF-8 for CP437 rendering on e-ink.
+      if ((uint8_t)c >= 0xC0) {
+        uint32_t codepoint = 0;
+        int extraBytes = 0;
+
+        if (((uint8_t)c & 0xE0) == 0xC0) {
+          // 2-byte sequence: 110xxxxx 10xxxxxx
+          codepoint = (uint8_t)c & 0x1F;
+          extraBytes = 1;
+        } else if (((uint8_t)c & 0xF0) == 0xE0) {
+          // 3-byte sequence: 1110xxxx 10xxxxxx 10xxxxxx
+          codepoint = (uint8_t)c & 0x0F;
+          extraBytes = 2;
+        } else if (((uint8_t)c & 0xF8) == 0xF0) {
+          // 4-byte sequence: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
+          codepoint = (uint8_t)c & 0x07;
+          extraBytes = 3;
+        }
+
+        // Read continuation bytes
+        bool valid = true;
+        for (int b = 0; b < extraBytes && p + 1 + b < end; b++) {
+          uint8_t cb = *(p + 1 + b);
+          if ((cb & 0xC0) != 0x80) { valid = false; break; }
+          codepoint = (codepoint << 6) | (cb & 0x3F);
+        }
+
+        if (valid && extraBytes > 0) {
+          p += extraBytes;  // Skip continuation bytes (loop increments past lead byte)
+
+          // Map Unicode codepoints to displayable equivalents
+          // Typographic chars → ASCII, accented chars → preserved as UTF-8
+          char mapped = 0;
+          switch (codepoint) {
+            case 0x2018: case 0x2019: mapped = '\''; break;  // Smart single quotes
+            case 0x201C: case 0x201D: mapped = '"';  break;  // Smart double quotes
+            case 0x2013: case 0x2014: mapped = '-';  break;  // En/em dash
+            case 0x2026:             mapped = '.';  break;  // Ellipsis
+            case 0x2022:             mapped = '*';  break;  // Bullet
+            case 0x00A0:             mapped = ' ';  break;  // Non-breaking space
+            case 0x00AB: case 0x00BB: mapped = '"'; break;  // Guillemets
+            case 0x2032:             mapped = '\''; break;  // Prime
+            case 0x2033:             mapped = '"';  break;  // Double prime
+            case 0x2010: case 0x2011: mapped = '-'; break;  // Hyphens
+            case 0x2012:             mapped = '-';  break;  // Figure dash
+            case 0x2015:             mapped = '-';  break;  // Horizontal bar
+            case 0x2039: case 0x203A: mapped = '\''; break; // Single guillemets
+            default:
+              if (codepoint >= 0x20 && codepoint < 0x7F) {
+                mapped = (char)codepoint;  // Basic ASCII range
+              } else if (unicodeToCP437(codepoint)) {
+                // Accented character that the e-ink font can render via CP437.
+                // Preserve as UTF-8 in the output; the text reader will decode
+                // and map to CP437 at render time.
+                if (codepoint <= 0x7FF) {
+                  output[outPos++] = 0xC0 | (codepoint >> 6);
+                  output[outPos++] = 0x80 | (codepoint & 0x3F);
+                } else if (codepoint <= 0xFFFF) {
+                  output[outPos++] = 0xE0 | (codepoint >> 12);
+                  output[outPos++] = 0x80 | ((codepoint >> 6) & 0x3F);
+                  output[outPos++] = 0x80 | (codepoint & 0x3F);
+                }
+                lastWasNewline = false;
+                lastWasSpace = false;
+                continue;  // Already wrote to output
+              } else {
+                continue;  // Skip unmappable characters
+              }
+              break;
+          }
+          c = mapped;
+        } else {
+          continue;  // Skip malformed UTF-8
+        }
+      } else if ((uint8_t)c >= 0x80) {
+        // Stray continuation byte (0x80-0xBF) — skip
+        continue;
+      }
+
+      // Whitespace collapsing
+      if (c == '\n' || c == '\r') {
+        if (!lastWasNewline && outPos > 0) {
+          output[outPos++] = '\n';
+          lastWasNewline = true;
+          lastWasSpace = false;
+        }
+        continue;
+      }
+
+      if (c == ' ' || c == '\t') {
+        if (!lastWasSpace && !lastWasNewline && outPos > 0) {
+          output[outPos++] = ' ';
+          lastWasSpace = true;
+        }
+        continue;
+      }
+
+      // Regular character
+      output[outPos++] = c;
+      lastWasNewline = false;
+      lastWasSpace = false;
+    }
+
+    // Trim trailing whitespace
+    while (outPos > 0 && (output[outPos-1] == '\n' || output[outPos-1] == ' ')) {
+      outPos--;
+    }
+
+    output[outPos] = '\0';
+    *outLen = outPos;
+    return output;
+  }
+
+  // ----------------------------------------------------------
+  // Decode an HTML entity starting at '&'.
+  // Advances *pos to the last character consumed.
+  // Returns the decoded character, or '&' if not recognized.
+  // ----------------------------------------------------------
+  static char _decodeEntity(const uint8_t* p, const uint8_t* end,
+                             const uint8_t** outPos) {
+    // Look for ';' within a reasonable range
+    const uint8_t* semi = p + 1;
+    int maxLen = 10;
+    while (semi < end && semi < p + maxLen && *semi != ';') semi++;
+
+    if (*semi != ';' || semi >= end) {
+      *outPos = p;  // Not an entity, return '&' literal
+      return '&';
+    }
+
+    int entityLen = semi - p - 1;  // Length between & and ;
+    const char* entity = (const char*)(p + 1);
+
+    *outPos = semi;  // Skip past ';'
+
+    // Named entities
+    if (entityLen == 3 && strncmp(entity, "amp", 3) == 0) return '&';
+    if (entityLen == 2 && strncmp(entity, "lt", 2) == 0) return '<';
+    if (entityLen == 2 && strncmp(entity, "gt", 2) == 0) return '>';
+    if (entityLen == 4 && strncmp(entity, "quot", 4) == 0) return '"';
+    if (entityLen == 4 && strncmp(entity, "apos", 4) == 0) return '\'';
+    if (entityLen == 4 && strncmp(entity, "nbsp", 4) == 0) return ' ';
+    if (entityLen == 5 && strncmp(entity, "mdash", 5) == 0) return '-';
+    if (entityLen == 5 && strncmp(entity, "ndash", 5) == 0) return '-';
+    if (entityLen == 6 && strncmp(entity, "hellip", 6) == 0) return '.';
+    if (entityLen == 5 && strncmp(entity, "lsquo", 5) == 0) return '\'';
+    if (entityLen == 5 && strncmp(entity, "rsquo", 5) == 0) return '\'';
+    if (entityLen == 5 && strncmp(entity, "ldquo", 5) == 0) return '"';
+    if (entityLen == 5 && strncmp(entity, "rdquo", 5) == 0) return '"';
+
+    // Common accented character entities → CP437 bytes for built-in font
+    if (entityLen == 6 && strncmp(entity, "eacute", 6) == 0) return (char)0x82;  // é
+    if (entityLen == 6 && strncmp(entity, "egrave", 6) == 0) return (char)0x8A;  // è
+    if (entityLen == 5 && strncmp(entity, "ecirc", 5) == 0) return (char)0x88;   // ê
+    if (entityLen == 4 && strncmp(entity, "euml", 4) == 0) return (char)0x89;    // ë
+    if (entityLen == 6 && strncmp(entity, "agrave", 6) == 0) return (char)0x85;  // à
+    if (entityLen == 6 && strncmp(entity, "aacute", 6) == 0) return (char)0xA0;  // á
+    if (entityLen == 5 && strncmp(entity, "acirc", 5) == 0) return (char)0x83;   // â
+    if (entityLen == 4 && strncmp(entity, "auml", 4) == 0) return (char)0x84;    // ä
+    if (entityLen == 6 && strncmp(entity, "ccedil", 6) == 0) return (char)0x87;  // ç
+    if (entityLen == 6 && strncmp(entity, "iacute", 6) == 0) return (char)0xA1;  // í
+    if (entityLen == 5 && strncmp(entity, "icirc", 5) == 0) return (char)0x8C;   // î
+    if (entityLen == 4 && strncmp(entity, "iuml", 4) == 0) return (char)0x8B;    // ï
+    if (entityLen == 6 && strncmp(entity, "igrave", 6) == 0) return (char)0x8D;  // ì
+    if (entityLen == 6 && strncmp(entity, "oacute", 6) == 0) return (char)0xA2;  // ó
+    if (entityLen == 5 && strncmp(entity, "ocirc", 5) == 0) return (char)0x93;   // ô
+    if (entityLen == 4 && strncmp(entity, "ouml", 4) == 0) return (char)0x94;    // ö
+    if (entityLen == 6 && strncmp(entity, "ograve", 6) == 0) return (char)0x95;  // ò
+    if (entityLen == 6 && strncmp(entity, "uacute", 6) == 0) return (char)0xA3;  // ú
+    if (entityLen == 5 && strncmp(entity, "ucirc", 5) == 0) return (char)0x96;   // û
+    if (entityLen == 4 && strncmp(entity, "uuml", 4) == 0) return (char)0x81;    // ü
+    if (entityLen == 6 && strncmp(entity, "ugrave", 6) == 0) return (char)0x97;  // ù
+    if (entityLen == 6 && strncmp(entity, "ntilde", 6) == 0) return (char)0xA4;  // ñ
+    if (entityLen == 6 && strncmp(entity, "Eacute", 6) == 0) return (char)0x90;  // É
+    if (entityLen == 6 && strncmp(entity, "Ccedil", 6) == 0) return (char)0x80;  // Ç
+    if (entityLen == 6 && strncmp(entity, "Ntilde", 6) == 0) return (char)0xA5;  // Ñ
+    if (entityLen == 4 && strncmp(entity, "Auml", 4) == 0) return (char)0x8E;    // Ä
+    if (entityLen == 4 && strncmp(entity, "Ouml", 4) == 0) return (char)0x99;    // Ö
+    if (entityLen == 4 && strncmp(entity, "Uuml", 4) == 0) return (char)0x9A;    // Ü
+    if (entityLen == 5 && strncmp(entity, "szlig", 5) == 0) return (char)0xE1;   // ß
+
+    // Numeric entities: &#NNN; or &#xHH;
+    if (entityLen >= 2 && entity[0] == '#') {
+      int codepoint = 0;
+      if (entity[1] == 'x' || entity[1] == 'X') {
+        // Hex
+        for (int i = 2; i < entityLen; i++) {
+          char ch = entity[i];
+          if (ch >= '0' && ch <= '9') codepoint = codepoint * 16 + (ch - '0');
+          else if (ch >= 'a' && ch <= 'f') codepoint = codepoint * 16 + (ch - 'a' + 10);
+          else if (ch >= 'A' && ch <= 'F') codepoint = codepoint * 16 + (ch - 'A' + 10);
+        }
+      } else {
+        // Decimal
+        for (int i = 1; i < entityLen; i++) {
+          char ch = entity[i];
+          if (ch >= '0' && ch <= '9') codepoint = codepoint * 10 + (ch - '0');
+        }
+      }
+      // Map to displayable character (best effort)
+      if (codepoint >= 32 && codepoint < 127) return (char)codepoint;
+      if (codepoint == 160) return ' ';   // non-breaking space
+      // Try CP437 mapping for accented characters.
+      // The byte value will be passed through to the built-in font.
+      uint8_t cp437 = unicodeToCP437(codepoint);
+      if (cp437) return (char)cp437;
+      // Unknown codepoint > 127: skip it
+      return ' ';
+    }
+
+    // Unknown entity - output as space
+    return ' ';
+  }
+
+  // ----------------------------------------------------------
+  // Find a tag in XML data (case-sensitive, e.g., "<manifest").
+  // Returns pointer to '<' of found tag, or nullptr.
+  // ----------------------------------------------------------
+  static const char* _findTag(const char* data, int dataLen, const char* tag) {
+    int tagLen = strlen(tag);
+    const char* end = data + dataLen - tagLen;
+    for (const char* p = data; p <= end; p++) {
+      if (memcmp(p, tag, tagLen) == 0) return p;
+    }
+    return nullptr;
+  }
+
+  // ----------------------------------------------------------
+  // Find a tag case-insensitively (for <body>, <BODY>, etc.).
+  // ----------------------------------------------------------
+  static const char* _findTagCI(const char* data, int dataLen, const char* tag) {
+    int tagLen = strlen(tag);
+    const char* end = data + dataLen - tagLen;
+    for (const char* p = data; p <= end; p++) {
+      if (strncasecmp(p, tag, tagLen) == 0) return p;
+    }
+    return nullptr;
+  }
+
+  // ----------------------------------------------------------
+  // Extract an attribute value from a region of XML.
+  // Scans for attr="value" and copies value to outBuf.
+  // ----------------------------------------------------------
+  static bool _extractAttribute(const char* data, int dataLen,
+                                 const char* attrName, char* outBuf, int outBufSize) {
+    int nameLen = strlen(attrName);
+    const char* end = data + dataLen;
+    for (const char* p = data; p < end - nameLen - 2; p++) {
+      if (strncmp(p, attrName, nameLen) == 0 && p[nameLen] == '=') {
+        p += nameLen + 1;
+        char quote = *p;
+        if (quote != '"' && quote != '\'') continue;
+        p++;
+        const char* valEnd = (const char*)memchr(p, quote, end - p);
+        if (!valEnd) continue;
+        int valLen = valEnd - p;
+        if (valLen >= outBufSize) valLen = outBufSize - 1;
+        memcpy(outBuf, p, valLen);
+        outBuf[valLen] = '\0';
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // ----------------------------------------------------------
+  // Extract an attribute value from within a single tag string.
+  // (More targeted version for parsing <item id="x" href="y"/>)
+  // ----------------------------------------------------------
+  static bool _extractAttributeFromTag(const char* tag, int tagLen,
+                                        const char* attrName,
+                                        char* outBuf, int outBufSize) {
+    return _extractAttribute(tag, tagLen, attrName, outBuf, outBufSize);
+  }
+
+  // ----------------------------------------------------------
+  // Extract text content between <tagName>...</tagName>.
+  // Works for simple cases like <dc:title>The Iliad</dc:title>.
+  // ----------------------------------------------------------
+  static bool _extractTagContent(const char* data, int dataLen,
+                                  const char* tagName, char* outBuf, int outBufSize) {
+    // Build open tag pattern: "<dc:title" (without >)
+    char openTag[64];
+    snprintf(openTag, sizeof(openTag), "<%s", tagName);
+
+    const char* start = _findTag(data, dataLen, openTag);
+    if (!start) return false;
+
+    // Find the > that closes the opening tag
+    const char* end = data + dataLen;
+    const char* contentStart = (const char*)memchr(start, '>', end - start);
+    if (!contentStart) return false;
+    contentStart++;  // Skip past '>'
+
+    // Find closing tag
+    char closeTag[64];
+    snprintf(closeTag, sizeof(closeTag), "</%s>", tagName);
+    const char* contentEnd = _findTag(contentStart, end - contentStart, closeTag);
+    if (!contentEnd) return false;
+
+    int len = contentEnd - contentStart;
+    if (len >= outBufSize) len = outBufSize - 1;
+    memcpy(outBuf, contentStart, len);
+    outBuf[len] = '\0';
+    return true;
+  }
+
+  // ----------------------------------------------------------
+  // Get directory portion of a path.
+  // "OEBPS/content.opf" -> "OEBPS/"
+  // "content.opf" -> ""
+  // ----------------------------------------------------------
+  static void _getDirectory(const char* path, char* dirBuf, int dirBufSize) {
+    const char* lastSlash = strrchr(path, '/');
+    if (lastSlash) {
+      int len = lastSlash - path + 1;  // Include trailing /
+      if (len >= dirBufSize) len = dirBufSize - 1;
+      memcpy(dirBuf, path, len);
+      dirBuf[len] = '\0';
+    } else {
+      dirBuf[0] = '\0';
+    }
+  }
+
+  // ----------------------------------------------------------
+  // Free the chapter paths array allocated by _parseOpf().
+  // ----------------------------------------------------------
+  static void _freeChapterPaths(char** paths, int count) {
+    if (paths) {
+      for (int i = 0; i < count; i++) {
+        if (paths[i]) free(paths[i]);
+      }
+      free(paths);
+    }
+  }
+};

examples/companion_radio/ui-new/Lastheardscreen.h

@@ -0,0 +1,237 @@
+#pragma once
+
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <helpers/AdvertDataHelpers.h>
+#include <MeshCore.h>
+
+extern MyMesh the_mesh;
+
+// ==========================================================================
+// Last Heard Screen — passive advert list
+// Shows all recently heard nodes from the advert path table, sorted by
+// recency. Unlike Discovery (active zero-hop scan), this is purely passive
+// — it shows nodes whose adverts have been received over time.
+// ==========================================================================
+class LastHeardScreen : public UIScreen {
+  mesh::RTCClock* _rtc;
+  int _scrollPos;
+
+  // Local sorted copy of advert paths (refreshed each render)
+  AdvertPath _entries[ADVERT_PATH_TABLE_SIZE];
+  int _count;
+
+  static char typeChar(uint8_t adv_type) {
+    switch (adv_type) {
+      case ADV_TYPE_CHAT:     return 'C';
+      case ADV_TYPE_REPEATER: return 'R';
+      case ADV_TYPE_ROOM:     return 'S';
+      case ADV_TYPE_SENSOR:   return 'N';
+      default:                return '?';
+    }
+  }
+
+  // Format age as human-readable string (e.g. "2m", "1h", "3d")
+  static void formatAge(uint32_t now, uint32_t timestamp, char* buf, int bufLen) {
+    if (timestamp == 0 || now < timestamp) {
+      snprintf(buf, bufLen, "---");
+      return;
+    }
+    uint32_t age = now - timestamp;
+    if (age < 60)         snprintf(buf, bufLen, "%ds", age);
+    else if (age < 3600)  snprintf(buf, bufLen, "%dm", age / 60);
+    else if (age < 86400) snprintf(buf, bufLen, "%dh", age / 3600);
+    else                  snprintf(buf, bufLen, "%dd", age / 86400);
+  }
+
+public:
+  LastHeardScreen(mesh::RTCClock* rtc)
+    : _rtc(rtc), _scrollPos(0), _count(0) {}
+
+  void resetScroll() { _scrollPos = 0; }
+
+  int getSelectedIdx() const { return _scrollPos; }
+
+  // Check if selected node is already in contacts
+  bool isSelectedInContacts() const {
+    if (_scrollPos < 0 || _scrollPos >= _count) return false;
+    return the_mesh.lookupContactByPubKey(_entries[_scrollPos].pubkey_prefix, 8) != nullptr;
+  }
+
+  // Get selected entry (for add/delete operations)
+  const AdvertPath* getSelectedEntry() const {
+    if (_scrollPos < 0 || _scrollPos >= _count) return nullptr;
+    return &_entries[_scrollPos];
+  }
+
+  // Tap-to-select: given virtual Y, select row.
+  // Returns: 0=miss, 1=moved, 2=tapped current row.
+  int selectRowAtVY(int vy) {
+    if (_count == 0) return 0;
+    const int headerH = 14, footerH = 14, lineH = the_mesh.getNodePrefs()->smallLineH();
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    const int bodyTop = headerH;
+#else
+    const int bodyTop = headerH + the_mesh.getNodePrefs()->smallHighlightOff();
+#endif
+    if (vy < bodyTop || vy >= 128 - footerH) return 0;
+
+    int maxVisible = (128 - headerH - footerH) / lineH;
+    if (maxVisible < 3) maxVisible = 3;
+    int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                              _count - maxVisible));
+
+    int tappedRow = startIdx + (vy - bodyTop) / lineH;
+    if (tappedRow < 0 || tappedRow >= _count) return 0;
+
+    if (tappedRow == _scrollPos) return 2;
+    _scrollPos = tappedRow;
+    return 1;
+  }
+
+  int render(DisplayDriver& display) override {
+    // Refresh sorted list from mesh
+    _count = the_mesh.getRecentlyHeard(_entries, ADVERT_PATH_TABLE_SIZE);
+
+    // Filter out empty entries (recv_timestamp == 0)
+    int validCount = 0;
+    for (int i = 0; i < _count; i++) {
+      if (_entries[i].recv_timestamp > 0) validCount++;
+      else break;  // sorted by recency, so first zero means rest are empty
+    }
+    _count = validCount;
+
+    if (_scrollPos >= _count) _scrollPos = max(0, _count - 1);
+
+    uint32_t now = _rtc->getCurrentTime();
+
+    // === Header ===
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::GREEN);
+    display.setCursor(0, 0);
+
+    char hdr[32];
+    snprintf(hdr, sizeof(hdr), "Last Heard: %d nodes", _count);
+    display.print(hdr);
+
+    display.drawRect(0, 11, display.width(), 1);
+
+    // === Body — node rows ===
+    display.setTextSize(the_mesh.getNodePrefs()->smallTextSize());
+    int lineHeight = the_mesh.getNodePrefs()->smallLineH();
+    int headerHeight = 14;
+    int footerHeight = 14;
+    int maxY = display.height() - footerHeight;
+    int y = headerHeight;
+
+    if (_count == 0) {
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(4, 28);
+      display.print("No adverts received yet");
+      display.setCursor(4, 38);
+      display.print("Nodes appear as adverts arrive");
+    } else {
+      int maxVisible = (maxY - headerHeight) / lineHeight;
+      if (maxVisible < 3) maxVisible = 3;
+      int startIdx = max(0, min(_scrollPos - maxVisible / 2,
+                                _count - maxVisible));
+      int endIdx = min(_count, startIdx + maxVisible);
+
+      for (int i = startIdx; i < endIdx && y + lineHeight <= maxY; i++) {
+        const AdvertPath& entry = _entries[i];
+        bool selected = (i == _scrollPos);
+
+        // Highlight selected row
+        if (selected) {
+          display.setColor(DisplayDriver::LIGHT);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+          display.fillRect(0, y, display.width(), lineHeight);
+#else
+          display.fillRect(0, y + the_mesh.getNodePrefs()->smallHighlightOff(), display.width(), lineHeight);
+#endif
+          display.setColor(DisplayDriver::DARK);
+        } else {
+          display.setColor(DisplayDriver::LIGHT);
+        }
+
+        display.setCursor(0, y);
+
+        // Prefix: cursor + type char
+        char prefix[4];
+        snprintf(prefix, sizeof(prefix), "%c%c",
+                 selected ? '>' : ' ', typeChar(entry.type));
+        display.print(prefix);
+
+        // Right side: age + hops + [★] for favourites, [+] for other contacts
+        char rightStr[20];
+        char ageBuf[8];
+        formatAge(now, entry.recv_timestamp, ageBuf, sizeof(ageBuf));
+
+        ContactInfo* ci = the_mesh.lookupContactByPubKey(entry.pubkey_prefix, 8);
+        bool inContacts = (ci != nullptr);
+        bool isFav = inContacts && (ci->flags & 0x01);
+        if (isFav) {
+          snprintf(rightStr, sizeof(rightStr), "%s %dh [*]", ageBuf, entry.path_len & 63);
+        } else if (inContacts) {
+          snprintf(rightStr, sizeof(rightStr), "%s %dh [+]", ageBuf, entry.path_len & 63);
+        } else {
+          snprintf(rightStr, sizeof(rightStr), "%s %dh", ageBuf, entry.path_len & 63);
+        }
+        int rightWidth = display.getTextWidth(rightStr) + 2;
+
+        // Name (truncated with ellipsis)
+        char filteredName[32];
+        display.translateUTF8ToBlocks(filteredName, entry.name, sizeof(filteredName));
+        int nameX = display.getTextWidth(prefix) + 2;
+        int nameMaxW = display.width() - nameX - rightWidth - 2;
+        display.drawTextEllipsized(nameX, y, nameMaxW, filteredName);
+
+        // Right-aligned info
+        display.setCursor(display.width() - rightWidth, y);
+        display.print(rightStr);
+
+        y += lineHeight;
+      }
+    }
+
+    display.setTextSize(1);
+
+    // === Footer ===
+    int footerY = display.height() - 12;
+    display.drawRect(0, footerY - 2, display.width(), 1);
+    display.setColor(DisplayDriver::YELLOW);
+
+    display.setCursor(0, footerY);
+#if defined(LilyGo_T5S3_EPaper_Pro)
+    display.print("Swipe:Scroll");
+    const char* right = "Tap:Add/Del";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#else
+    display.print("Q:Bk");
+    const char* right = "Tap/Ent:Add/Del";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+#endif
+
+    return 5000;  // refresh every 5s to update ages
+  }
+
+  bool handleInput(char c) override {
+    // Scroll up
+    if (c == 'w' || c == 'W' || c == 0xF2) {
+      if (_scrollPos > 0) { _scrollPos--; return true; }
+      return false;
+    }
+
+    // Scroll down
+    if (c == 's' || c == 'S' || c == 0xF1) {
+      if (_scrollPos < _count - 1) { _scrollPos++; return true; }
+      return false;
+    }
+
+    // Enter — handled by main.cpp (needs access to private MyMesh methods)
+    // Q — handled by main.cpp (navigation)
+    return false;
+  }
+};

examples/companion_radio/ui-new/M4BMetadata.h

@@ -0,0 +1,651 @@
+#pragma once
+
+// =============================================================================
+// M4BMetadata.h - Lightweight MP4/M4B atom parser for metadata extraction
+//
+// Walks the MP4 atom (box) tree to extract:
+//   - Title     (moov/udta/meta/ilst/©nam)
+//   - Author    (moov/udta/meta/ilst/©ART)
+//   - Cover art (moov/udta/meta/ilst/covr) - JPEG offset+size within file
+//   - Duration  (moov/mvhd timescale + duration)
+//   - Chapter markers (moov/udta/chpl) - Nero-style chapter list
+//
+// Designed for embedded use: no dynamic allocation, reads directly from SD
+// via Arduino File API, uses a small stack buffer for atom headers.
+//
+// Usage:
+//   M4BMetadata meta;
+//   File f = SD.open("/audiobooks/mybook.m4b");
+//   if (meta.parse(f)) {
+//     Serial.printf("Title: %s\n", meta.title);
+//     Serial.printf("Author: %s\n", meta.author);
+//     if (meta.hasCoverArt) {
+//       // JPEG data is at meta.coverOffset, meta.coverSize bytes
+//     }
+//   }
+//   f.close();
+// =============================================================================
+
+#include <SD.h>
+
+// Maximum metadata string lengths (including null terminator)
+#define M4B_MAX_TITLE    128
+#define M4B_MAX_AUTHOR   64
+#define M4B_MAX_CHAPTERS 100
+
+struct M4BChapter {
+  uint32_t startMs;    // Chapter start time in milliseconds
+  char     name[48];   // Chapter title (truncated to fit)
+};
+
+class M4BMetadata {
+public:
+  // Extracted metadata
+  char     title[M4B_MAX_TITLE];
+  char     author[M4B_MAX_AUTHOR];
+  bool     hasCoverArt;
+  uint32_t coverOffset;   // Byte offset of JPEG/PNG data within file
+  uint32_t coverSize;     // Size of cover image data in bytes
+  uint8_t  coverFormat;   // 13=JPEG, 14=PNG (from MP4 well-known type)
+  uint32_t durationMs;    // Total duration in milliseconds
+  uint32_t sampleRate;    // Audio sample rate (from audio stsd)
+  uint32_t bitrate;       // Approximate bitrate in bps
+
+  // Chapter data
+  M4BChapter chapters[M4B_MAX_CHAPTERS];
+  int        chapterCount;
+
+  M4BMetadata() { clear(); }
+
+  void clear() {
+    title[0] = '\0';
+    author[0] = '\0';
+    hasCoverArt = false;
+    coverOffset = 0;
+    coverSize = 0;
+    coverFormat = 0;
+    durationMs = 0;
+    sampleRate = 44100;
+    bitrate = 0;
+    chapterCount = 0;
+  }
+
+  // Parse an open file. Returns true if at least title or duration was found.
+  // File position is NOT preserved — caller should seek as needed afterward.
+  bool parse(File& file) {
+    clear();
+    if (!file || file.size() < 8) return false;
+
+    _fileSize = file.size();
+
+    // Walk top-level atoms looking for 'moov'
+    uint32_t pos = 0;
+    while (pos < _fileSize) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_MOOV) {
+        parseMoov(file, hdr.dataOffset, hdr.dataOffset + hdr.dataSize);
+        break;  // moov found and parsed, we're done
+      }
+
+      // Skip to next top-level atom
+      pos += hdr.size;
+      if (hdr.size == 0) break;  // size=0 means "extends to EOF"
+    }
+
+    return (title[0] != '\0' || durationMs > 0);
+  }
+
+  // Get chapter index for a given playback position (milliseconds).
+  // Returns -1 if no chapters or position is before first chapter.
+  int getChapterForPosition(uint32_t positionMs) const {
+    if (chapterCount == 0) return -1;
+    int ch = 0;
+    for (int i = 1; i < chapterCount; i++) {
+      if (chapters[i].startMs > positionMs) break;
+      ch = i;
+    }
+    return ch;
+  }
+
+  // Get the start position of the next chapter after the given position.
+  // Returns 0 if no next chapter.
+  uint32_t getNextChapterMs(uint32_t positionMs) const {
+    for (int i = 0; i < chapterCount; i++) {
+      if (chapters[i].startMs > positionMs) return chapters[i].startMs;
+    }
+    return 0;
+  }
+
+  // Get the start position of the current or previous chapter.
+  uint32_t getPrevChapterMs(uint32_t positionMs) const {
+    uint32_t prev = 0;
+    for (int i = 0; i < chapterCount; i++) {
+      if (chapters[i].startMs >= positionMs) break;
+      prev = chapters[i].startMs;
+    }
+    return prev;
+  }
+
+private:
+  uint32_t _fileSize;
+
+  // MP4 atom type codes (big-endian FourCC)
+  static constexpr uint32_t ATOM_MOOV = 0x6D6F6F76;  // 'moov'
+  static constexpr uint32_t ATOM_MVHD = 0x6D766864;  // 'mvhd'
+  static constexpr uint32_t ATOM_UDTA = 0x75647461;  // 'udta'
+  static constexpr uint32_t ATOM_META = 0x6D657461;  // 'meta'
+  static constexpr uint32_t ATOM_ILST = 0x696C7374;  // 'ilst'
+  static constexpr uint32_t ATOM_NAM  = 0xA96E616D;  // '©nam'
+  static constexpr uint32_t ATOM_ART  = 0xA9415254;  // '©ART'
+  static constexpr uint32_t ATOM_COVR = 0x636F7672;  // 'covr'
+  static constexpr uint32_t ATOM_DATA = 0x64617461;  // 'data'
+  static constexpr uint32_t ATOM_CHPL = 0x6368706C;  // 'chpl' (Nero chapters)
+  static constexpr uint32_t ATOM_TRAK = 0x7472616B;  // 'trak'
+  static constexpr uint32_t ATOM_MDIA = 0x6D646961;  // 'mdia'
+  static constexpr uint32_t ATOM_MDHD = 0x6D646864;  // 'mdhd'
+  static constexpr uint32_t ATOM_HDLR = 0x68646C72;  // 'hdlr'
+
+  struct AtomHeader {
+    uint32_t type;
+    uint64_t size;        // Total atom size including header
+    uint32_t dataOffset;  // File offset where data begins (after header)
+    uint64_t dataSize;    // size - header_length
+  };
+
+  // Read a 32-bit big-endian value from file at current position
+  static uint32_t readU32BE(File& file) {
+    uint8_t buf[4];
+    file.read(buf, 4);
+    return ((uint32_t)buf[0] << 24) | ((uint32_t)buf[1] << 16) |
+           ((uint32_t)buf[2] << 8)  | buf[3];
+  }
+
+  // Read a 64-bit big-endian value
+  static uint64_t readU64BE(File& file) {
+    uint32_t hi = readU32BE(file);
+    uint32_t lo = readU32BE(file);
+    return ((uint64_t)hi << 32) | lo;
+  }
+
+  // Read a 16-bit big-endian value
+  static uint16_t readU16BE(File& file) {
+    uint8_t buf[2];
+    file.read(buf, 2);
+    return ((uint16_t)buf[0] << 8) | buf[1];
+  }
+
+  // Read atom header at given file offset
+  bool readAtomHeader(File& file, uint32_t offset, AtomHeader& hdr) {
+    if (offset + 8 > _fileSize) return false;
+
+    file.seek(offset);
+    uint32_t size32 = readU32BE(file);
+    hdr.type = readU32BE(file);
+
+    if (size32 == 1) {
+      // 64-bit extended size
+      if (offset + 16 > _fileSize) return false;
+      hdr.size = readU64BE(file);
+      hdr.dataOffset = offset + 16;
+      hdr.dataSize = (hdr.size > 16) ? hdr.size - 16 : 0;
+    } else if (size32 == 0) {
+      // Atom extends to end of file
+      hdr.size = _fileSize - offset;
+      hdr.dataOffset = offset + 8;
+      hdr.dataSize = hdr.size - 8;
+    } else {
+      hdr.size = size32;
+      hdr.dataOffset = offset + 8;
+      hdr.dataSize = (size32 > 8) ? size32 - 8 : 0;
+    }
+
+    return true;
+  }
+
+  // Parse the moov container atom
+  void parseMoov(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      switch (hdr.type) {
+        case ATOM_MVHD:
+          parseMvhd(file, hdr.dataOffset, (uint32_t)hdr.dataSize);
+          break;
+        case ATOM_UDTA:
+          parseUdta(file, hdr.dataOffset, hdr.dataOffset + (uint32_t)hdr.dataSize);
+          break;
+        case ATOM_TRAK:
+          break;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse mvhd (movie header) for duration
+  void parseMvhd(File& file, uint32_t offset, uint32_t size) {
+    file.seek(offset);
+    uint8_t version = file.read();
+
+    if (version == 0) {
+      file.seek(offset + 4);   // skip version(1) + flags(3)
+      /* create_time */ readU32BE(file);
+      /* modify_time */ readU32BE(file);
+      uint32_t timescale = readU32BE(file);
+      uint32_t duration = readU32BE(file);
+      if (timescale > 0) {
+        durationMs = (uint32_t)((uint64_t)duration * 1000 / timescale);
+      }
+    } else if (version == 1) {
+      file.seek(offset + 4);
+      /* create_time */ readU64BE(file);
+      /* modify_time */ readU64BE(file);
+      uint32_t timescale = readU32BE(file);
+      uint64_t duration = readU64BE(file);
+      if (timescale > 0) {
+        durationMs = (uint32_t)(duration * 1000 / timescale);
+      }
+    }
+  }
+
+  // Parse udta container — contains meta and/or chpl
+  void parseUdta(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_META) {
+        parseMeta(file, hdr.dataOffset + 4,
+                  hdr.dataOffset + (uint32_t)hdr.dataSize);
+      } else if (hdr.type == ATOM_CHPL) {
+        parseChpl(file, hdr.dataOffset, (uint32_t)hdr.dataSize);
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse meta container — contains hdlr + ilst
+  void parseMeta(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_ILST) {
+        parseIlst(file, hdr.dataOffset, hdr.dataOffset + (uint32_t)hdr.dataSize);
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Parse ilst (iTunes metadata list) — contains ©nam, ©ART, covr etc.
+  void parseIlst(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      switch (hdr.type) {
+        case ATOM_NAM:
+          extractTextData(file, hdr.dataOffset,
+                          hdr.dataOffset + (uint32_t)hdr.dataSize,
+                          title, M4B_MAX_TITLE);
+          break;
+        case ATOM_ART:
+          extractTextData(file, hdr.dataOffset,
+                          hdr.dataOffset + (uint32_t)hdr.dataSize,
+                          author, M4B_MAX_AUTHOR);
+          break;
+        case ATOM_COVR:
+          extractCoverData(file, hdr.dataOffset,
+                           hdr.dataOffset + (uint32_t)hdr.dataSize);
+          break;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Extract text from a 'data' sub-atom within an ilst entry.
+  void extractTextData(File& file, uint32_t start, uint32_t end,
+                       char* dest, int maxLen) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_DATA && hdr.dataSize > 8) {
+        uint32_t textOffset = hdr.dataOffset + 8;
+        uint32_t textLen = (uint32_t)hdr.dataSize - 8;
+        if (textLen > (uint32_t)(maxLen - 1)) textLen = maxLen - 1;
+
+        file.seek(textOffset);
+        file.read((uint8_t*)dest, textLen);
+        dest[textLen] = '\0';
+        return;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // Extract cover art location from 'data' sub-atom within covr.
+  void extractCoverData(File& file, uint32_t start, uint32_t end) {
+    uint32_t pos = start;
+    while (pos < end) {
+      AtomHeader hdr;
+      if (!readAtomHeader(file, pos, hdr)) break;
+      if (hdr.size < 8) break;
+
+      if (hdr.type == ATOM_DATA && hdr.dataSize > 8) {
+        file.seek(hdr.dataOffset);
+        uint32_t typeIndicator = readU32BE(file);
+        uint8_t wellKnownType = typeIndicator & 0xFF;
+
+        coverOffset = hdr.dataOffset + 8;
+        coverSize = (uint32_t)hdr.dataSize - 8;
+        coverFormat = wellKnownType;  // 13=JPEG, 14=PNG
+        hasCoverArt = (coverSize > 0);
+
+        Serial.printf("M4B: Cover art found - %s, %u bytes at offset %u\n",
+                      wellKnownType == 13 ? "JPEG" :
+                      wellKnownType == 14 ? "PNG" : "unknown",
+                      coverSize, coverOffset);
+        return;
+      }
+
+      pos += (uint32_t)hdr.size;
+    }
+  }
+
+  // =====================================================================
+  // ID3v2 Parser for MP3 files
+  // =====================================================================
+public:
+  // Parse ID3v2 tags from an MP3 file. Extracts title (TIT2), artist
+  // (TPE1), and cover art (APIC). Fills the same metadata fields as
+  // the M4B parser so decodeCoverArt() works unchanged.
+  bool parseID3v2(File& file) {
+    clear();
+    if (!file || file.size() < 10) return false;
+
+    file.seek(0);
+    uint8_t hdr[10];
+    if (file.read(hdr, 10) != 10) return false;
+
+    // Verify "ID3" magic
+    if (hdr[0] != 'I' || hdr[1] != 'D' || hdr[2] != '3') {
+      Serial.println("ID3: No ID3v2 header found");
+      return false;
+    }
+
+    uint8_t versionMajor = hdr[3];  // 3 = ID3v2.3, 4 = ID3v2.4
+    bool v24 = (versionMajor == 4);
+    bool hasExtHeader = (hdr[5] & 0x40) != 0;
+
+    // Tag size is syncsafe integer (4 x 7-bit bytes)
+    uint32_t tagSize = ((uint32_t)(hdr[6] & 0x7F) << 21) |
+                       ((uint32_t)(hdr[7] & 0x7F) << 14) |
+                       ((uint32_t)(hdr[8] & 0x7F) << 7)  |
+                       (hdr[9] & 0x7F);
+
+    uint32_t tagEnd = 10 + tagSize;
+    if (tagEnd > file.size()) tagEnd = file.size();
+
+    Serial.printf("ID3: v2.%d, %u bytes\n", versionMajor, tagSize);
+
+    // Skip extended header if present
+    uint32_t pos = 10;
+    if (hasExtHeader && pos + 4 < tagEnd) {
+      file.seek(pos);
+      uint32_t extSize;
+      if (v24) {
+        uint8_t eb[4];
+        file.read(eb, 4);
+        extSize = ((uint32_t)(eb[0] & 0x7F) << 21) |
+                  ((uint32_t)(eb[1] & 0x7F) << 14) |
+                  ((uint32_t)(eb[2] & 0x7F) << 7)  |
+                  (eb[3] & 0x7F);
+      } else {
+        extSize = readU32BE(file) + 4;
+      }
+      pos += extSize;
+    }
+
+    // Walk ID3v2 frames
+    bool foundTitle = false, foundArtist = false, foundCover = false;
+
+    while (pos + 10 < tagEnd) {
+      file.seek(pos);
+      uint8_t fhdr[10];
+      if (file.read(fhdr, 10) != 10) break;
+
+      if (fhdr[0] == 0) break;
+
+      char frameId[5] = { (char)fhdr[0], (char)fhdr[1],
+                          (char)fhdr[2], (char)fhdr[3], '\0' };
+
+      uint32_t frameSize;
+      if (v24) {
+        frameSize = ((uint32_t)(fhdr[4] & 0x7F) << 21) |
+                    ((uint32_t)(fhdr[5] & 0x7F) << 14) |
+                    ((uint32_t)(fhdr[6] & 0x7F) << 7)  |
+                    (fhdr[7] & 0x7F);
+      } else {
+        frameSize = ((uint32_t)fhdr[4] << 24) | ((uint32_t)fhdr[5] << 16) |
+                    ((uint32_t)fhdr[6] << 8)  | fhdr[7];
+      }
+
+      if (frameSize == 0 || pos + 10 + frameSize > tagEnd) break;
+
+      uint32_t dataStart = pos + 10;
+
+      // --- TIT2 (Title) ---
+      if (!foundTitle && strcmp(frameId, "TIT2") == 0 && frameSize > 1) {
+        id3ExtractText(file, dataStart, frameSize, title, M4B_MAX_TITLE);
+        foundTitle = (title[0] != '\0');
+      }
+      // --- TPE1 (Artist/Author) ---
+      if (!foundArtist && strcmp(frameId, "TPE1") == 0 && frameSize > 1) {
+        id3ExtractText(file, dataStart, frameSize, author, M4B_MAX_AUTHOR);
+        foundArtist = (author[0] != '\0');
+      }
+      // --- APIC (Attached Picture) ---
+      if (!foundCover && strcmp(frameId, "APIC") == 0 && frameSize > 20) {
+        id3ExtractAPIC(file, dataStart, frameSize);
+        foundCover = hasCoverArt;
+      }
+
+      pos = dataStart + frameSize;
+
+      // Early exit once we have everything
+      if (foundTitle && foundArtist && foundCover) break;
+    }
+
+    if (foundTitle) Serial.printf("ID3: Title: %s\n", title);
+    if (foundArtist) Serial.printf("ID3: Author: %s\n", author);
+    return (foundTitle || foundCover);
+  }
+
+private:
+  // Extract text from a TIT2/TPE1 frame.
+  // Format: encoding(1) + text data
+  void id3ExtractText(File& file, uint32_t offset, uint32_t size,
+                      char* dest, int maxLen) {
+    file.seek(offset);
+    uint8_t encoding = file.read();
+    uint32_t textLen = size - 1;
+    if (textLen == 0) return;
+
+    if (encoding == 0 || encoding == 3) {
+      // ISO-8859-1 or UTF-8 — read directly
+      uint32_t readLen = (textLen < (uint32_t)(maxLen - 1))
+                         ? textLen : (uint32_t)(maxLen - 1);
+      file.read((uint8_t*)dest, readLen);
+      dest[readLen] = '\0';
+      // Strip trailing nulls
+      while (readLen > 0 && dest[readLen - 1] == '\0') readLen--;
+      dest[readLen] = '\0';
+    }
+    else if (encoding == 1 || encoding == 2) {
+      // UTF-16 (with or without BOM) — crude ASCII extraction
+      // Static buffer to avoid stack overflow (loopTask has limited stack)
+      static uint8_t u16buf[128];
+      uint32_t readLen = (textLen > sizeof(u16buf)) ? sizeof(u16buf) : textLen;
+      file.read(u16buf, readLen);
+
+      uint32_t srcStart = 0;
+      // Skip BOM if present
+      if (readLen >= 2 && ((u16buf[0] == 0xFF && u16buf[1] == 0xFE) ||
+                           (u16buf[0] == 0xFE && u16buf[1] == 0xFF))) {
+        srcStart = 2;
+      }
+      bool littleEndian = (srcStart >= 2 && u16buf[0] == 0xFF);
+
+      int dstIdx = 0;
+      for (uint32_t i = srcStart; i + 1 < readLen && dstIdx < maxLen - 1; i += 2) {
+        uint8_t lo = littleEndian ? u16buf[i] : u16buf[i + 1];
+        uint8_t hi = littleEndian ? u16buf[i + 1] : u16buf[i];
+        if (lo == 0 && hi == 0) break;  // null terminator
+        if (hi == 0 && lo >= 0x20 && lo < 0x7F) {
+          dest[dstIdx++] = (char)lo;
+        } else {
+          dest[dstIdx++] = '?';
+        }
+      }
+      dest[dstIdx] = '\0';
+    }
+  }
+
+  // Extract APIC (cover art) frame.
+  // Format: encoding(1) + MIME(null-term) + picType(1) + desc(null-term) + imageData
+  void id3ExtractAPIC(File& file, uint32_t offset, uint32_t frameSize) {
+    file.seek(offset);
+    uint8_t encoding = file.read();
+
+    // Read MIME type (null-terminated ASCII)
+    char mime[32] = {0};
+    int mimeLen = 0;
+    while (mimeLen < 31) {
+      int b = file.read();
+      if (b < 0) return;   // Read error
+      if (b == 0) break;   // Null terminator = end of MIME string
+      mime[mimeLen++] = (char)b;
+    }
+    mime[mimeLen] = '\0';
+
+    // Picture type (1 byte)
+    uint8_t picType = file.read();
+    (void)picType;
+
+    // Skip description (null-terminated, encoding-dependent)
+    if (encoding == 0 || encoding == 3) {
+      // Single-byte null terminator
+      while (true) {
+        int b = file.read();
+        if (b < 0) return;   // Read error
+        if (b == 0) break;   // Null terminator
+      }
+    } else {
+      // UTF-16: double-null terminator
+      while (true) {
+        int b1 = file.read();
+        int b2 = file.read();
+        if (b1 < 0 || b2 < 0) return;  // Read error
+        if (b1 == 0 && b2 == 0) break;  // Double-null terminator
+      }
+    }
+
+    // Everything from here to end of frame is image data
+    uint32_t imgOffset = file.position();
+    uint32_t imgEnd = offset + frameSize;
+    if (imgOffset >= imgEnd) return;
+
+    uint32_t imgSize = imgEnd - imgOffset;
+
+    // Determine format from MIME type
+    bool isJpeg = (strstr(mime, "jpeg") || strstr(mime, "jpg"));
+    bool isPng  = (strstr(mime, "png") != nullptr);
+
+    // Also detect by magic bytes if MIME is generic
+    if (!isJpeg && !isPng && imgSize > 4) {
+      file.seek(imgOffset);
+      uint8_t magic[4];
+      file.read(magic, 4);
+      if (magic[0] == 0xFF && magic[1] == 0xD8) isJpeg = true;
+      else if (magic[0] == 0x89 && magic[1] == 'P' &&
+               magic[2] == 'N'  && magic[3] == 'G') isPng = true;
+    }
+
+    coverOffset = imgOffset;
+    coverSize = imgSize;
+    coverFormat = isJpeg ? 13 : (isPng ? 14 : 0);
+    hasCoverArt = (imgSize > 100 && (isJpeg || isPng));
+
+    if (hasCoverArt) {
+      Serial.printf("ID3: Cover %s, %u bytes\n",
+                    isJpeg ? "JPEG" : "PNG", imgSize);
+    }
+  }
+
+  // Parse Nero-style chapter list (chpl atom).
+  void parseChpl(File& file, uint32_t offset, uint32_t size) {
+    if (size < 9) return;
+
+    file.seek(offset);
+    uint8_t version = file.read();
+    file.read();  // flags byte 1
+    file.read();  // flags byte 2
+    file.read();  // flags byte 3
+
+    file.read();  // reserved
+
+    uint32_t count;
+    if (version == 1) {
+      count = readU32BE(file);
+    } else {
+      count = file.read();
+    }
+
+    if (count > M4B_MAX_CHAPTERS) count = M4B_MAX_CHAPTERS;
+
+    chapterCount = 0;
+    for (uint32_t i = 0; i < count; i++) {
+      if (!file.available()) break;
+
+      uint64_t timestamp = readU64BE(file);
+      uint32_t startMs = (uint32_t)(timestamp / 10000);  // 100ns -> ms
+
+      uint8_t nameLen = file.read();
+      if (nameLen == 0 || !file.available()) break;
+
+      M4BChapter& ch = chapters[chapterCount];
+      ch.startMs = startMs;
+
+      uint8_t readLen = (nameLen < sizeof(ch.name) - 1) ? nameLen : sizeof(ch.name) - 1;
+      file.read((uint8_t*)ch.name, readLen);
+      ch.name[readLen] = '\0';
+
+      if (nameLen > readLen) {
+        file.seek(file.position() + (nameLen - readLen));
+      }
+
+      chapterCount++;
+    }
+
+    Serial.printf("M4B: Found %d chapters\n", chapterCount);
+  }
+};

examples/companion_radio/ui-new/Mapscreen.h

@@ -0,0 +1,916 @@
+#pragma once
+
+// =============================================================================
+// MapScreen — OSM Tile Map for T-Deck Pro E-Ink Display
+// =============================================================================
+//
+// Renders standard OSM "slippy map" PNG tiles from SD card onto the e-ink
+// display at native 240×320 resolution (bypassing the 128×128 logical grid).
+//
+// Tiles are B&W PNGs stored at /tiles/{zoom}/{x}/{y}.png — the same format
+// used by Ripple, tdeck-maps, and MTD-Script tile downloaders.
+//
+// REQUIREMENTS:
+//   1. Add PNGdec library to platformio.ini:
+//        lib_deps = ... bitbank2/PNGdec@^1.0.1
+//
+//   2. Add raw display access to GxEPDDisplay.h (public section):
+//        // --- Raw pixel access for MapScreen (bypasses scaling) ---
+//        void drawPixelRaw(int16_t x, int16_t y, uint16_t color) {
+//          display.drawPixel(x, y, color);
+//        }
+//        int16_t rawWidth()  { return display.width(); }
+//        int16_t rawHeight() { return display.height(); }
+//        // Force endFrame() to push to display even if CRC unchanged
+//        // (needed because drawPixelRaw bypasses CRC tracking)
+//        void invalidateFrameCRC() { last_display_crc_value = 0; }
+//
+//   3. Add to UITask.h:
+//        #include "MapScreen.h"
+//        UIScreen* map_screen;
+//        void gotoMapScreen();
+//        bool isOnMapScreen() const { return curr == map_screen; }
+//        UIScreen* getMapScreen() const { return map_screen; }
+//
+//   4. Initialise in UITask::begin():
+//        map_screen = new MapScreen(this);
+//
+//   5. Implement UITask::gotoMapScreen() following gotoTextReader() pattern.
+//
+//   6. Hook 'g' key in main.cpp for GPS/Map access:
+//        case 'g':
+//          if (ui_task.isOnMapScreen()) {
+//            // Already on map — 'g' re-centers on GPS
+//            ui_task.injectKey('g');
+//          } else {
+//            Serial.println("Opening map");
+//            {
+//              MapScreen* ms = (MapScreen*)ui_task.getMapScreen();
+//              if (ms) {
+//                ms->setSDReady(sdCardReady);
+//                ms->setGPSPosition(sensors.node_lat,
+//                                   sensors.node_lon);
+//                // Populate contact markers via iterator
+//                ms->clearMarkers();
+//                ContactsIterator it = the_mesh.startContactsIterator();
+//                ContactInfo ci;
+//                while (it.hasNext(&the_mesh, ci)) {
+//                  double lat = ((double)ci.gps_lat) / 1000000.0;
+//                  double lon = ((double)ci.gps_lon) / 1000000.0;
+//                  ms->addMarker(lat, lon, ci.name, ci.type);
+//                }
+//              }
+//            }
+//            ui_task.gotoMapScreen();
+//          }
+//          break;
+//
+//   7. Route WASD/zoom keys to map screen in main.cpp (in existing handlers):
+//        For 'w', 's', 'a', 'd' cases, add:
+//          if (ui_task.isOnMapScreen()) { ui_task.injectKey(key); break; }
+//        For the default case, add map screen passthrough:
+//          if (ui_task.isOnMapScreen()) { ui_task.injectKey(key); break; }
+//        This covers +, -, i, o, g (re-center) keys too.
+//
+// TILE SOURCES (B&W recommended for e-ink):
+//   - MTD-Script:    github.com/fistulareffigy/MTD-Script
+//   - tdeck-maps:    github.com/JustDr00py/tdeck-maps
+//   - Stamen Toner style gives best e-ink contrast
+// =============================================================================
+
+#include <Arduino.h>
+#include <SD.h>
+#include <PNGdec.h>
+#undef local  // PNGdec's zutil.h defines 'local' as 'static' — breaks any variable named 'local'
+#include <helpers/ui/UIScreen.h>
+#include <helpers/ui/DisplayDriver.h>
+#include <helpers/ui/GxEPDDisplay.h>
+
+// ---------------------------------------------------------------------------
+// Layout constants (physical pixel coordinates, 240×320 display)
+// ---------------------------------------------------------------------------
+#define MAP_DISPLAY_W       240
+#define MAP_DISPLAY_H       320
+
+// Footer bar occupies the bottom — matches other screens' setTextSize(1) footer
+#define MAP_FOOTER_H        24      // ~24px at bottom for nav hints
+#define MAP_VIEWPORT_Y      0       // Map starts at top
+#define MAP_VIEWPORT_H      (MAP_DISPLAY_H - MAP_FOOTER_H)  // 296px for map
+
+#define MAP_TILE_SIZE       256     // Standard OSM tile size in pixels
+#define MAP_DEFAULT_ZOOM    13
+#define MAP_MIN_ZOOM        1
+#define MAP_MAX_ZOOM        17
+
+// PNG decode buffer size — 256×256 RGB = 196KB, but PNGdec streams row-by-row
+// We only need a line buffer. Allocate in PSRAM for safety.
+#define MAP_PNG_BUF_SIZE    (65536)  // 64KB for PNG file read buffer
+
+// Tile path on SD card
+#define MAP_TILE_ROOT       "/tiles"
+
+// Contact type (for label display — matches AdvertDataHelpers.h)
+#ifndef ADV_TYPE_REPEATER
+  #define ADV_TYPE_REPEATER   2
+#endif
+
+// Pan step: fraction of viewport to move per keypress
+#define MAP_PAN_FRACTION    4       // 1/4 of viewport per press
+
+// Max contact markers (PSRAM-allocated, ~37 bytes each)
+#define MAP_MAX_MARKERS     500
+
+
+class MapScreen : public UIScreen {
+public:
+  MapScreen(UITask* task)
+    : _task(task),
+      _einkDisplay(nullptr),
+      _sdReady(false),
+      _needsRedraw(true),
+      _hasFix(false),
+      _centerLat(-33.8688),   // Default: Sydney (most Ripple users)
+      _centerLon(151.2093),
+      _gpsLat(0.0),
+      _gpsLon(0.0),
+      _zoom(MAP_DEFAULT_ZOOM),
+      _zoomMin(MAP_MIN_ZOOM),
+      _zoomMax(MAP_MAX_ZOOM),
+      _pngBuf(nullptr),
+      _lineBuf(nullptr),
+      _tileFound(false)
+  {
+    // Marker array and PNG buffers are deferred to enter() to avoid
+    // consuming 20KB+ PSRAM at boot when the map may never be opened.
+    _markers = nullptr;
+    _numMarkers = 0;
+  }
+
+  ~MapScreen() {
+    if (_pngBuf) { free(_pngBuf); _pngBuf = nullptr; }
+    if (_lineBuf) { free(_lineBuf); _lineBuf = nullptr; }
+    if (_markers) { free(_markers); _markers = nullptr; }
+  }
+
+  void setSDReady(bool ready) { _sdReady = ready; }
+
+  // Set initial GPS position (called when opening map — centers viewport)
+  void setGPSPosition(double lat, double lon) {
+    if (lat != 0.0 || lon != 0.0) {
+      _gpsLat = lat;
+      _gpsLon = lon;
+      _centerLat = lat;
+      _centerLon = lon;
+      _hasFix = true;
+      _needsRedraw = true;
+    }
+  }
+
+  // Update own GPS position without moving viewport (called periodically)
+  void updateGPSPosition(double lat, double lon) {
+    if (lat == 0.0 && lon == 0.0) return;
+    if (lat != _gpsLat || lon != _gpsLon) {
+      _gpsLat = lat;
+      _gpsLon = lon;
+      _hasFix = true;
+      _needsRedraw = true;  // Redraw to move own-position marker
+    }
+  }
+
+  // Add a location marker (call once per contact before entering map)
+  void clearMarkers() { _numMarkers = 0; }
+  void addMarker(double lat, double lon, const char* name = "", uint8_t type = 0) {
+    // Lazy-allocate markers on first use (deferred from constructor)
+    if (!_markers) {
+      _markers = (MapMarker*)ps_calloc(MAP_MAX_MARKERS, sizeof(MapMarker));
+      if (!_markers) return;  // Alloc failed — skip silently
+    }
+    if (_numMarkers >= MAP_MAX_MARKERS) return;
+    if (lat == 0.0 && lon == 0.0) return;  // Skip no-location contacts
+    _markers[_numMarkers].lat = lat;
+    _markers[_numMarkers].lon = lon;
+    _markers[_numMarkers].type = type;
+    strncpy(_markers[_numMarkers].name, name, sizeof(_markers[0].name) - 1);
+    _markers[_numMarkers].name[sizeof(_markers[0].name) - 1] = '\0';
+    _numMarkers++;
+  }
+
+  // Refresh contact markers (called periodically from main loop)
+  // Clears and rebuilds — caller iterates contacts and calls addMarker()
+  int getNumMarkers() const { return _numMarkers; }
+
+  // Called when navigating to map screen
+  void enter(DisplayDriver& display) {
+    _einkDisplay = static_cast<GxEPDDisplay*>(&display);
+    _needsRedraw = true;
+
+    // Allocate marker array in PSRAM on first use (~20KB)
+    if (!_markers) {
+      _markers = (MapMarker*)ps_calloc(MAP_MAX_MARKERS, sizeof(MapMarker));
+      if (_markers) {
+        Serial.printf("MapScreen: markers allocated (%d × %d = %d bytes PSRAM)\n",
+                       MAP_MAX_MARKERS, (int)sizeof(MapMarker),
+                       MAP_MAX_MARKERS * (int)sizeof(MapMarker));
+      } else {
+        Serial.println("MapScreen: marker PSRAM alloc FAILED");
+      }
+    }
+
+    // Allocate PNG read buffer in PSRAM on first use
+    if (!_pngBuf) {
+      _pngBuf = (uint8_t*)ps_malloc(MAP_PNG_BUF_SIZE);
+      if (!_pngBuf) {
+        Serial.println("MapScreen: PSRAM alloc failed, trying heap");
+        _pngBuf = (uint8_t*)malloc(MAP_PNG_BUF_SIZE);
+      }
+      if (_pngBuf) {
+        Serial.printf("MapScreen: PNG buffer allocated (%d bytes)\n", MAP_PNG_BUF_SIZE);
+      } else {
+        Serial.println("MapScreen: PNG buffer alloc FAILED");
+      }
+    }
+
+    // Allocate scanline decode buffer in PSRAM (512 bytes — avoids stack
+    // allocation inside the PNGdec callback which is called 256× per tile)
+    if (!_lineBuf) {
+      _lineBuf = (uint16_t*)ps_malloc(MAP_TILE_SIZE * sizeof(uint16_t));
+      if (!_lineBuf) {
+        _lineBuf = (uint16_t*)malloc(MAP_TILE_SIZE * sizeof(uint16_t));
+      }
+      if (_lineBuf) {
+        Serial.println("MapScreen: lineBuf allocated");
+      } else {
+        Serial.println("MapScreen: lineBuf alloc FAILED");
+      }
+    }
+
+    // Detect available zoom levels from SD card directories
+    detectZoomRange();
+  }
+
+  // ---- UIScreen interface ----
+
+  int render(DisplayDriver& display) override {
+    if (!_einkDisplay) {
+      _einkDisplay = static_cast<GxEPDDisplay*>(&display);
+    }
+
+    if (!_sdReady) {
+      display.setTextSize(1);
+      display.setColor(DisplayDriver::LIGHT);
+      display.setCursor(10, 20);
+      display.print("SD card not found");
+      display.setCursor(10, 35);
+      display.print("Insert SD with");
+      display.setCursor(10, 48);
+      display.print("/tiles/{z}/{x}/{y}.png");
+      return 5000;
+    }
+
+    // Always render tiles — UITask clears the buffer via startFrame() before
+    // calling us, so we must redraw every time (e.g. after alert overlays)
+    bool wasRedraw = _needsRedraw;
+    _needsRedraw = false;
+
+    // Render map tiles into the viewport
+    renderMapViewport();
+
+    // Overlay contact markers
+    renderContactMarkers();
+
+    // Crosshair at viewport center
+    renderCrosshair();
+
+    // Footer bar (uses normal display API with scaling)
+    renderFooter(display);
+
+    // Raw pixel writes bypass CRC tracking — force refresh
+    _einkDisplay->invalidateFrameCRC();
+
+    // If user panned/zoomed, allow quick re-render; otherwise idle longer
+    return wasRedraw ? 1000 : 30000;
+  }
+
+  bool handleInput(char c) override {
+    // Pan distances in degrees — adaptive to zoom level
+    // At zoom Z, one tile covers 360/2^Z degrees of longitude
+    double tileLonSpan = 360.0 / (1 << _zoom);
+    double tileLatSpan = tileLonSpan * cos(_centerLat * PI / 180.0);  // Rough approx
+
+    // Pan by 1/MAP_PAN_FRACTION of viewport (viewport ≈ 1 tile)
+    double panLon = tileLonSpan / MAP_PAN_FRACTION;
+    double panLat = tileLatSpan / MAP_PAN_FRACTION;
+
+    switch (c) {
+      // ---- WASD panning ----
+      case 'w':
+      case 'W':
+        _centerLat += panLat;
+        if (_centerLat > 85.05) _centerLat = 85.05;  // Web Mercator limit
+        _needsRedraw = true;
+        return true;
+
+      case 's':
+      case 'S':
+        _centerLat -= panLat;
+        if (_centerLat < -85.05) _centerLat = -85.05;
+        _needsRedraw = true;
+        return true;
+
+      case 'a':
+      case 'A':
+        _centerLon -= panLon;
+        if (_centerLon < -180.0) _centerLon += 360.0;
+        _needsRedraw = true;
+        return true;
+
+      case 'd':
+      case 'D':
+        _centerLon += panLon;
+        if (_centerLon > 180.0) _centerLon -= 360.0;
+        _needsRedraw = true;
+        return true;
+
+      // ---- Zoom controls ----
+      case 'z':
+      case 'Z':
+        if (_zoom < _zoomMax) {
+          _zoom++;
+          _needsRedraw = true;
+          Serial.printf("MapScreen: zoom in -> %d\n", _zoom);
+        }
+        return true;
+
+      case 'x':
+      case 'X':
+        if (_zoom > _zoomMin) {
+          _zoom--;
+          _needsRedraw = true;
+          Serial.printf("MapScreen: zoom out -> %d\n", _zoom);
+        }
+        return true;
+
+      // ---- Re-center on GPS fix ----
+      case 'g':
+        if (_hasFix) {
+          _centerLat = _gpsLat;
+          _centerLon = _gpsLon;
+          _needsRedraw = true;
+          Serial.println("MapScreen: re-center on GPS");
+        }
+        return true;
+
+      default:
+        return false;
+    }
+  }
+
+private:
+  UITask* _task;
+  GxEPDDisplay* _einkDisplay;
+  bool _sdReady;
+  bool _needsRedraw;
+  bool _hasFix;
+
+  // Map state
+  double _centerLat;
+  double _centerLon;
+  double _gpsLat;       // Own GPS position (separate from viewport center)
+  double _gpsLon;
+  int _zoom;
+  int _zoomMin;     // Detected from SD card
+  int _zoomMax;     // Detected from SD card
+
+  // PNG decode buffer (PSRAM)
+  uint8_t* _pngBuf;
+  uint16_t* _lineBuf;  // Scanline RGB565 buffer for PNG decode (PSRAM)
+  bool _tileFound;      // Did last tile load succeed?
+
+  // PNGdec instance
+  PNG _png;
+
+  // Contacts for marker overlay
+  struct MapMarker {
+    double lat;
+    double lon;
+    char name[20];    // Truncated display name
+    uint8_t type;     // ADV_TYPE_CHAT, ADV_TYPE_REPEATER, etc.
+  };
+  MapMarker* _markers = nullptr;  // PSRAM-allocated
+  int _numMarkers = 0;
+
+  // ---- Rendering state passed to PNG callback ----
+  // PNGdec calls our callback per scanline — we need to know where to draw.
+  // Also carries a PNG* so the static callback can call getLineAsRGB565().
+  struct DrawContext {
+    GxEPDDisplay* display;
+    PNG* png;         // Pointer to the decoder (for getLineAsRGB565)
+    int offsetX;      // Screen X offset for this tile
+    int offsetY;      // Screen Y offset for this tile
+    int viewportY;    // Top of viewport (MAP_VIEWPORT_Y)
+    int viewportH;    // Height of viewport (MAP_VIEWPORT_H)
+    uint16_t* lineBuf; // Scanline decode buffer (PSRAM-allocated, avoids 512B stack usage per callback)
+  };
+  DrawContext _drawCtx;
+
+  // ==========================================================================
+  // Detect available zoom levels from /tiles/{z}/ directories on SD
+  // ==========================================================================
+
+  void detectZoomRange() {
+    if (!_sdReady) return;
+
+    _zoomMin = MAP_MAX_ZOOM;
+    _zoomMax = MAP_MIN_ZOOM;
+
+    char path[32];
+    for (int z = MAP_MIN_ZOOM; z <= MAP_MAX_ZOOM; z++) {
+      snprintf(path, sizeof(path), MAP_TILE_ROOT "/%d", z);
+      if (SD.exists(path)) {
+        if (z < _zoomMin) _zoomMin = z;
+        if (z > _zoomMax) _zoomMax = z;
+      }
+    }
+
+    // If no tiles found, reset to defaults
+    if (_zoomMin > _zoomMax) {
+      _zoomMin = MAP_MIN_ZOOM;
+      _zoomMax = MAP_MAX_ZOOM;
+      Serial.println("MapScreen: no tile directories found");
+    } else {
+      Serial.printf("MapScreen: detected zoom range %d-%d\n", _zoomMin, _zoomMax);
+    }
+
+    // Clamp current zoom to available range
+    if (_zoom > _zoomMax) _zoom = _zoomMax;
+    if (_zoom < _zoomMin) _zoom = _zoomMin;
+  }
+
+  // ==========================================================================
+  // Tile coordinate math (Web Mercator / Slippy Map convention)
+  // ==========================================================================
+
+  // Convert lat/lon to tile X,Y and sub-tile pixel offset at given zoom
+  static void latLonToTileXY(double lat, double lon, int zoom,
+                              int& tileX, int& tileY,
+                              int& pixelX, int& pixelY)
+  {
+    int n = 1 << zoom;
+
+    // Tile X (longitude is linear)
+    double x = (lon + 180.0) / 360.0 * n;
+    tileX = (int)floor(x);
+    pixelX = (int)((x - tileX) * MAP_TILE_SIZE);
+
+    // Tile Y (latitude uses Mercator projection)
+    double latRad = lat * PI / 180.0;
+    double y = (1.0 - log(tan(latRad) + 1.0 / cos(latRad)) / PI) / 2.0 * n;
+    tileY = (int)floor(y);
+    pixelY = (int)((y - tileY) * MAP_TILE_SIZE);
+  }
+
+  // Convert tile X,Y + pixel offset back to lat/lon
+  static void tileXYToLatLon(int tileX, int tileY, int pixelX, int pixelY,
+                              int zoom, double& lat, double& lon)
+  {
+    int n = 1 << zoom;
+    double x = tileX + (double)pixelX / MAP_TILE_SIZE;
+    double y = tileY + (double)pixelY / MAP_TILE_SIZE;
+
+    lon = x / n * 360.0 - 180.0;
+    double latRad = atan(sinh(PI * (1.0 - 2.0 * y / n)));
+    lat = latRad * 180.0 / PI;
+  }
+
+  // Convert a lat/lon to pixel position within the current viewport
+  // Returns false if off-screen
+  bool latLonToScreen(double lat, double lon, int& screenX, int& screenY) {
+    int centerTileX, centerTileY, centerPixelX, centerPixelY;
+    latLonToTileXY(_centerLat, _centerLon, _zoom,
+                   centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    int targetTileX, targetTileY, targetPixelX, targetPixelY;
+    latLonToTileXY(lat, lon, _zoom,
+                   targetTileX, targetTileY, targetPixelX, targetPixelY);
+
+    // Calculate pixel delta from center
+    int dx = (targetTileX - centerTileX) * MAP_TILE_SIZE + (targetPixelX - centerPixelX);
+    int dy = (targetTileY - centerTileY) * MAP_TILE_SIZE + (targetPixelY - centerPixelY);
+
+    screenX = MAP_DISPLAY_W / 2 + dx;
+    screenY = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2 + dy;
+
+    return (screenX >= 0 && screenX < MAP_DISPLAY_W &&
+            screenY >= MAP_VIEWPORT_Y && screenY < MAP_VIEWPORT_Y + MAP_VIEWPORT_H);
+  }
+
+  // ==========================================================================
+  // Tile loading and rendering
+  // ==========================================================================
+
+  // Build tile file path: /tiles/{zoom}/{x}/{y}.png
+  static void buildTilePath(char* buf, int bufSize, int zoom, int x, int y) {
+    snprintf(buf, bufSize, MAP_TILE_ROOT "/%d/%d/%d.png", zoom, x, y);
+  }
+
+  // Load a PNG tile from SD and decode it directly to the display
+  // screenX, screenY = top-left corner on display where this tile goes
+  bool loadAndRenderTile(int tileX, int tileY, int screenX, int screenY) {
+    if (!_pngBuf || !_lineBuf || !_einkDisplay) return false;
+
+    char path[64];
+    buildTilePath(path, sizeof(path), _zoom, tileX, tileY);
+
+    // Check existence first to avoid noisy ESP32 VFS error logs
+    if (!SD.exists(path)) return false;
+
+    File f = SD.open(path, FILE_READ);
+    if (!f) return false;
+
+    // Read entire PNG into buffer
+    int fileSize = f.size();
+    if (fileSize > MAP_PNG_BUF_SIZE) {
+      Serial.printf("MapScreen: tile too large: %s (%d bytes)\n", path, fileSize);
+      f.close();
+      return false;
+    }
+
+    int bytesRead = f.read(_pngBuf, fileSize);
+    f.close();
+
+    if (bytesRead != fileSize) {
+      Serial.printf("MapScreen: short read: %s (%d/%d)\n", path, bytesRead, fileSize);
+      return false;
+    }
+
+    // Set up draw context for the PNG callback
+    _drawCtx.display   = _einkDisplay;
+    _drawCtx.png       = &_png;
+    _drawCtx.offsetX   = screenX;
+    _drawCtx.offsetY   = screenY;
+    _drawCtx.viewportY = MAP_VIEWPORT_Y;
+    _drawCtx.viewportH = MAP_VIEWPORT_H;
+    _drawCtx.lineBuf   = _lineBuf;
+
+    // Open PNG from memory buffer
+    int rc = _png.openRAM(_pngBuf, fileSize, pngDrawCallback);
+    if (rc != PNG_SUCCESS) {
+      Serial.printf("MapScreen: PNG open failed: %s (rc=%d)\n", path, rc);
+      return false;
+    }
+
+    // Decode — triggers pngDrawCallback for each scanline.
+    // First arg is user pointer, passed as pDraw->pUser in callback.
+    rc = _png.decode(&_drawCtx, 0);
+    _png.close();
+
+    if (rc != PNG_SUCCESS) {
+      Serial.printf("MapScreen: PNG decode failed: %s (rc=%d)\n", path, rc);
+      return false;
+    }
+
+    return true;
+  }
+
+  // PNGdec scanline callback — called once per row of the decoded image.
+  // Draws directly to the e-ink display at raw pixel coordinates.
+  // Uses getLineAsRGB565 with correct (little) endianness for ESP32.
+  static int pngDrawCallback(PNGDRAW* pDraw) {
+    DrawContext* ctx = (DrawContext*)pDraw->pUser;
+    if (!ctx || !ctx->display || !ctx->png || !ctx->lineBuf) return 0;
+
+    int screenY = ctx->offsetY + pDraw->y;
+
+    // Clip to viewport vertically
+    if (screenY < ctx->viewportY || screenY >= ctx->viewportY + ctx->viewportH) return 1;
+
+    // Debug: log format on first row of first tile only
+    if (pDraw->y == 0 && ctx->offsetX >= 0 && ctx->offsetY >= 0) {
+      static bool logged = false;
+      if (!logged) {
+        Serial.printf("MapScreen: PNG iBpp=%d iWidth=%d\n", pDraw->iBpp, pDraw->iWidth);
+        logged = true;
+      }
+    }
+
+    uint16_t lineWidth = pDraw->iWidth;
+    if (lineWidth > MAP_TILE_SIZE) lineWidth = MAP_TILE_SIZE;
+    ctx->png->getLineAsRGB565(pDraw, ctx->lineBuf, PNG_RGB565_LITTLE_ENDIAN, 0xFFFFFFFF);
+
+    for (int x = 0; x < lineWidth; x++) {
+      int screenX = ctx->offsetX + x;
+      if (screenX < 0 || screenX >= MAP_DISPLAY_W) continue;
+
+      // RGB565 little-endian on ESP32: standard bit layout
+      // R[15:11] G[10:5] B[4:0]
+      uint16_t pixel = ctx->lineBuf[x];
+
+      // For B&W tiles this is 0x0000 (black) or 0xFFFF (white)
+      // Simple threshold on full 16-bit value handles both cleanly
+      uint16_t color = (pixel > 0x7FFF) ? GxEPD_WHITE : GxEPD_BLACK;
+      ctx->display->drawPixelRaw(screenX, screenY, color);
+    }
+    return 1;
+  }
+
+  // ==========================================================================
+  // Viewport rendering — stitch tiles to fill the screen
+  // ==========================================================================
+
+  void renderMapViewport() {
+    if (!_einkDisplay) return;
+
+    // Find which tile the center point falls in
+    int centerTileX, centerTileY, centerPixelX, centerPixelY;
+    latLonToTileXY(_centerLat, _centerLon, _zoom,
+                   centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    Serial.printf("MapScreen: center tile %d/%d/%d  px(%d,%d)\n",
+                  _zoom, centerTileX, centerTileY, centerPixelX, centerPixelY);
+
+    // Screen position where the center tile's (0,0) corner should be placed
+    // such that the GPS point ends up at viewport center
+    int viewCenterX = MAP_DISPLAY_W / 2;
+    int viewCenterY = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2;
+
+    int baseTileScreenX = viewCenterX - centerPixelX;
+    int baseTileScreenY = viewCenterY - centerPixelY;
+
+    // Determine tile grid range needed to cover the entire viewport
+    int startDX = 0, startDY = 0;
+    int endDX = 0, endDY = 0;
+
+    while (baseTileScreenX + startDX * MAP_TILE_SIZE > 0) startDX--;
+    while (baseTileScreenY + startDY * MAP_TILE_SIZE > MAP_VIEWPORT_Y) startDY--;
+    while (baseTileScreenX + (endDX + 1) * MAP_TILE_SIZE < MAP_DISPLAY_W) endDX++;
+    while (baseTileScreenY + (endDY + 1) * MAP_TILE_SIZE < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) endDY++;
+
+    int maxTile = (1 << _zoom) - 1;
+    int loaded = 0, missing = 0;
+
+    for (int dy = startDY; dy <= endDY; dy++) {
+      for (int dx = startDX; dx <= endDX; dx++) {
+        int tx = centerTileX + dx;
+        int ty = centerTileY + dy;
+
+        // Longitude wraps
+        if (tx < 0) tx += (1 << _zoom);
+        if (tx > maxTile) tx -= (1 << _zoom);
+
+        // Latitude doesn't wrap — skip out-of-range
+        if (ty < 0 || ty > maxTile) continue;
+
+        int screenX = baseTileScreenX + dx * MAP_TILE_SIZE;
+        int screenY = baseTileScreenY + dy * MAP_TILE_SIZE;
+
+        if (loadAndRenderTile(tx, ty, screenX, screenY)) {
+          loaded++;
+        } else {
+          missing++;
+        }
+        yield();  // Feed WDT between tiles — each tile can take 1-2s at 80MHz
+      }
+    }
+
+    Serial.printf("MapScreen: rendered %d tiles, %d missing\n", loaded, missing);
+    _tileFound = (loaded > 0);
+  }
+
+  // ==========================================================================
+  // Contact marker overlay
+  // ==========================================================================
+
+  void renderContactMarkers() {
+    if (!_einkDisplay || !_markers) return;
+
+    int visible = 0;
+    for (int i = 0; i < _numMarkers; i++) {
+      int sx, sy;
+      if (latLonToScreen(_markers[i].lat, _markers[i].lon, sx, sy)) {
+        int r = markerRadius();
+        drawDiamond(sx, sy, r);
+
+        // Draw name label for repeaters (and at higher zoom for all contacts)
+        if (_markers[i].name[0] != '\0' &&
+            (_markers[i].type == ADV_TYPE_REPEATER || _zoom >= 14)) {
+          drawLabel(sx, sy - r - 2, _markers[i].name);
+        }
+        visible++;
+      }
+    }
+
+    // Render own GPS position as a distinct marker (circle)
+    if (_hasFix) {
+      int sx, sy;
+      if (latLonToScreen(_gpsLat, _gpsLon, sx, sy)) {
+        drawOwnPosition(sx, sy);
+        visible++;
+      }
+    }
+  }
+
+  // Marker radius scaled by zoom level
+  // z10→3px, z11→4, z12→5, z13→6, z14→7, z15→8, z16→9, z17→10
+  int markerRadius() {
+    int r = _zoom - 7;
+    if (r < 3) r = 3;
+    if (r > 10) r = 10;
+    return r;
+  }
+
+  // Draw a filled diamond marker at screen coordinates with given radius
+  void drawDiamond(int cx, int cy, int r) {
+    // White outline first (1px larger than fill)
+    for (int dy = -(r + 1); dy <= (r + 1); dy++) {
+      int span = (r + 1) - abs(dy);
+      int innerSpan = r - abs(dy);
+      for (int dx = -span; dx <= span; dx++) {
+        if (abs(dy) <= r && abs(dx) <= innerSpan) continue;
+        int px = cx + dx, py = cy + dy;
+        if (px >= 0 && px < MAP_DISPLAY_W &&
+            py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(px, py, GxEPD_WHITE);
+        }
+      }
+    }
+
+    // Filled black diamond
+    for (int dy = -r; dy <= r; dy++) {
+      int span = r - abs(dy);
+      for (int dx = -span; dx <= span; dx++) {
+        int px = cx + dx, py = cy + dy;
+        if (px >= 0 && px < MAP_DISPLAY_W &&
+            py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+        }
+      }
+    }
+  }
+
+  // Strip non-ASCII characters (emoji, flags, symbols) from label text.
+  // Copies only printable ASCII (0x20-0x7E) into dest buffer.
+  // Skips leading whitespace after stripping. Returns length.
+  static int extractAsciiLabel(const char* src, char* dest, int destSize) {
+    int j = 0;
+    for (int i = 0; src[i] != '\0' && j < destSize - 1; i++) {
+      uint8_t ch = (uint8_t)src[i];
+      if (ch >= 0x20 && ch <= 0x7E) {
+        dest[j++] = src[i];
+      }
+      // Skip continuation bytes of multi-byte UTF-8 sequences
+    }
+    dest[j] = '\0';
+
+    // Trim leading spaces (left after stripping emoji prefix)
+    int start = 0;
+    while (dest[start] == ' ') start++;
+    if (start > 0) {
+      memmove(dest, dest + start, j - start + 1);
+      j -= start;
+    }
+    return j;
+  }
+
+  // Draw a text label above a marker with white background for readability
+  // Built-in font is 5×7 pixels per character
+  void drawLabel(int cx, int topY, const char* text) {
+    // Clean emoji/non-ASCII from label
+    char clean[24];
+    int len = extractAsciiLabel(text, clean, sizeof(clean));
+    if (len == 0) return;  // Nothing printable
+    if (len > 14) len = 14;  // Truncate long names
+    clean[len] = '\0';
+
+    int textW = len * 6;     // 5px char + 1px spacing
+    int textH = 8;           // 7px + 1px padding
+
+    int lx = cx - textW / 2;
+    int ly = topY - textH;
+
+    // Clamp to viewport
+    if (lx < 1) lx = 1;
+    if (lx + textW >= MAP_DISPLAY_W - 1) lx = MAP_DISPLAY_W - textW - 1;
+    if (ly < MAP_VIEWPORT_Y) ly = MAP_VIEWPORT_Y;
+    if (ly + textH >= MAP_VIEWPORT_Y + MAP_VIEWPORT_H) return;
+
+    // White background rectangle
+    for (int y = ly - 1; y <= ly + textH; y++) {
+      for (int x = lx - 1; x <= lx + textW; x++) {
+        if (x >= 0 && x < MAP_DISPLAY_W &&
+            y >= MAP_VIEWPORT_Y && y < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+          _einkDisplay->drawPixelRaw(x, y, GxEPD_WHITE);
+        }
+      }
+    }
+
+    // Draw text using raw font rendering
+    _einkDisplay->drawTextRaw(lx, ly, clean, GxEPD_BLACK);
+  }
+
+  // Draw own-position marker: bold circle with filled center dot
+  // Fixed size (doesn't scale with zoom) so it's always clearly visible
+  void drawOwnPosition(int cx, int cy) {
+    int r = 8;  // Outer radius — always prominent
+
+    // White halo (clears map underneath)
+    for (int dy = -(r + 2); dy <= (r + 2); dy++) {
+      for (int dx = -(r + 2); dx <= (r + 2); dx++) {
+        if (dx * dx + dy * dy <= (r + 2) * (r + 2)) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_WHITE);
+          }
+        }
+      }
+    }
+
+    // Thick black circle outline (2px wide ring)
+    for (int dy = -r; dy <= r; dy++) {
+      for (int dx = -r; dx <= r; dx++) {
+        int d2 = dx * dx + dy * dy;
+        if (d2 >= (r - 2) * (r - 2) && d2 <= r * r) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+          }
+        }
+      }
+    }
+
+    // Filled black center dot (radius 3)
+    for (int dy = -3; dy <= 3; dy++) {
+      for (int dx = -3; dx <= 3; dx++) {
+        if (dx * dx + dy * dy <= 9) {
+          int px = cx + dx, py = cy + dy;
+          if (px >= 0 && px < MAP_DISPLAY_W &&
+              py >= MAP_VIEWPORT_Y && py < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+            _einkDisplay->drawPixelRaw(px, py, GxEPD_BLACK);
+          }
+        }
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Crosshair at viewport center
+  // ==========================================================================
+
+  void renderCrosshair() {
+    if (!_einkDisplay) return;
+
+    int cx = MAP_DISPLAY_W / 2;
+    int cy = MAP_VIEWPORT_Y + MAP_VIEWPORT_H / 2;
+    int len = markerRadius() + 2;  // Scales with zoom
+
+    // Draw thin crosshair: black line with white border for contrast
+    // Horizontal arm
+    for (int x = cx - len; x <= cx + len; x++) {
+      if (x >= 0 && x < MAP_DISPLAY_W) {
+        if (cy - 1 >= MAP_VIEWPORT_Y)
+          _einkDisplay->drawPixelRaw(x, cy - 1, GxEPD_WHITE);
+        if (cy + 1 < MAP_VIEWPORT_Y + MAP_VIEWPORT_H)
+          _einkDisplay->drawPixelRaw(x, cy + 1, GxEPD_WHITE);
+        _einkDisplay->drawPixelRaw(x, cy, GxEPD_BLACK);
+      }
+    }
+
+    // Vertical arm
+    for (int y = cy - len; y <= cy + len; y++) {
+      if (y >= MAP_VIEWPORT_Y && y < MAP_VIEWPORT_Y + MAP_VIEWPORT_H) {
+        if (cx - 1 >= 0)
+          _einkDisplay->drawPixelRaw(cx - 1, y, GxEPD_WHITE);
+        if (cx + 1 < MAP_DISPLAY_W)
+          _einkDisplay->drawPixelRaw(cx + 1, y, GxEPD_WHITE);
+        _einkDisplay->drawPixelRaw(cx, y, GxEPD_BLACK);
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Footer bar — zoom level, GPS status, navigation hints
+  // ==========================================================================
+
+  void renderFooter(DisplayDriver& display) {
+    // Use the standard footer pattern: setTextSize(1) at height()-12
+    display.setTextSize(1);
+    display.setColor(DisplayDriver::LIGHT);
+
+    int footerY = display.height() - 12;
+
+    // Separator line
+    display.drawRect(0, footerY - 2, display.width(), 1);
+
+    // Left: zoom level
+    char left[8];
+    snprintf(left, sizeof(left), "Z%d", _zoom);
+    display.setCursor(0, footerY);
+    display.print(left);
+
+    // Right: navigation hint
+    const char* right = "WASD:pan Z/X:zoom";
+    display.setCursor(display.width() - display.getTextWidth(right) - 2, footerY);
+    display.print(right);
+  }
+};

examples/companion_radio/ui-new/ModemManager.h

@@ -0,0 +1,266 @@
+#pragma once
+
+// =============================================================================
+// ModemManager - A7682E 4G Modem Driver for T-Deck Pro (V1.1 4G variant)
+//
+// Runs AT commands on a dedicated FreeRTOS task (Core 0, priority 1) to never
+// block the mesh radio loop.  Communicates with main loop via lock-free queues.
+//
+// Supports: SMS send/receive, voice call dial/answer/hangup/DTMF
+//
+// Guard: HAS_4G_MODEM (defined only for the 4G build environment)
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef MODEM_MANAGER_H
+#define MODEM_MANAGER_H
+
+#include <Arduino.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+#include <freertos/queue.h>
+#include <freertos/semphr.h>
+#include "variant.h"
+#include "ApnDatabase.h"
+
+// ---------------------------------------------------------------------------
+// Modem pins (from variant.h, always defined for reference)
+//   MODEM_POWER_EN  41   Board 6609 enable
+//   MODEM_PWRKEY    40   Power key toggle
+//   MODEM_RST        9   Reset (shared with I2S BCLK on audio board)
+//   MODEM_RI         7   Ring indicator (shared with I2S DOUT on audio)
+//   MODEM_DTR        8   Data terminal ready (shared with I2S LRC on audio)
+//   MODEM_RX        10   UART RX (shared with PIN_PERF_POWERON)
+//   MODEM_TX        11   UART TX
+// ---------------------------------------------------------------------------
+
+// SMS field limits
+#define SMS_PHONE_LEN    20
+#define SMS_BODY_LEN    161   // 160 chars + null
+
+// Task configuration
+#define MODEM_TASK_PRIORITY   1       // Below mesh (default loop = priority 1 on core 1)
+#define MODEM_TASK_STACK_SIZE 6144    // Increased for call handling
+#define MODEM_TASK_CORE       0       // Run on core 0 (mesh runs on core 1)
+
+// Queue sizes
+#define MODEM_SEND_QUEUE_SIZE  4
+#define MODEM_RECV_QUEUE_SIZE  8
+#define MODEM_CALL_CMD_QUEUE_SIZE  4
+#define MODEM_CALL_EVT_QUEUE_SIZE  4
+
+// ---------------------------------------------------------------------------
+// Modem state machine
+// ---------------------------------------------------------------------------
+enum class ModemState {
+  OFF,
+  POWERING_ON,
+  INITIALIZING,
+  REGISTERING,
+  READY,
+  ERROR,
+  SENDING_SMS,
+  // Voice call states
+  DIALING,        // ATD sent, waiting for connect/carrier
+  RINGING_IN,     // Incoming call detected (RING URC)
+  IN_CALL         // Voice call active
+};
+
+// ---------------------------------------------------------------------------
+// SMS structures (unchanged)
+// ---------------------------------------------------------------------------
+
+// Outgoing SMS (queued from main loop to modem task)
+struct SMSOutgoing {
+  char phone[SMS_PHONE_LEN];
+  char body[SMS_BODY_LEN];
+};
+
+// Incoming SMS (queued from modem task to main loop)
+struct SMSIncoming {
+  char phone[SMS_PHONE_LEN];
+  char body[SMS_BODY_LEN];
+  uint32_t timestamp;   // epoch seconds (from modem RTC or millis-based)
+};
+
+// ---------------------------------------------------------------------------
+// Voice call structures
+// ---------------------------------------------------------------------------
+
+// Commands from main loop → modem task
+enum class CallCmd : uint8_t {
+  DIAL,           // Initiate outgoing call
+  ANSWER,         // Answer incoming call
+  HANGUP,         // End active call or reject incoming
+  DTMF,           // Send DTMF tone during call
+  SET_VOLUME      // Set speaker volume
+};
+
+struct CallCommand {
+  CallCmd cmd;
+  char phone[SMS_PHONE_LEN];   // Used by DIAL
+  char dtmf;                    // Used by DTMF (single digit: 0-9, *, #)
+  uint8_t volume;               // Used by SET_VOLUME (0-5)
+};
+
+// Events from modem task → main loop
+enum class CallEventType : uint8_t {
+  INCOMING,       // Incoming call ringing (+CLIP parsed)
+  CONNECTED,      // Call answered / outgoing connected
+  ENDED,          // Call ended (local hangup, remote hangup, or no carrier)
+  MISSED,         // Incoming call ended before answer
+  BUSY,           // Outgoing call got busy signal
+  NO_ANSWER,      // Outgoing call not answered
+  DIAL_FAILED     // ATD command failed
+};
+
+struct CallEvent {
+  CallEventType type;
+  char phone[SMS_PHONE_LEN];   // Caller/callee number (from +CLIP or dial)
+  uint32_t duration;            // Call duration in seconds (for ENDED)
+};
+
+// ---------------------------------------------------------------------------
+// ModemManager class
+// ---------------------------------------------------------------------------
+
+class ModemManager {
+public:
+  void begin();
+  void shutdown();
+
+  // --- SMS API (unchanged) ---
+  bool sendSMS(const char* phone, const char* body);
+  bool recvSMS(SMSIncoming& out);
+
+  // --- Voice Call API ---
+  bool dialCall(const char* phone);          // Queue outgoing call
+  bool answerCall();                          // Answer incoming call
+  bool hangupCall();                          // End active / reject incoming
+  bool sendDTMF(char digit);                  // Send DTMF during call
+  bool setCallVolume(uint8_t level);          // Set volume 0-5
+  bool pollCallEvent(CallEvent& out);         // Poll from main loop
+
+  // Ringtone control — called from main loop
+  void setRingtoneEnabled(bool en) { _ringtoneEnabled = en; }
+  bool isRingtoneEnabled() const { return _ringtoneEnabled; }
+
+  // --- State queries (lock-free reads) ---
+  ModemState getState() const { return _state; }
+  int  getSignalBars() const;       // 0-5
+  int  getCSQ() const { return _csq; }
+  bool isReady() const { return _state == ModemState::READY; }
+  bool isInCall() const { return _state == ModemState::IN_CALL; }
+  bool isRinging() const { return _state == ModemState::RINGING_IN; }
+  bool isDialing() const { return _state == ModemState::DIALING; }
+  bool isCallActive() const {
+    return _state == ModemState::IN_CALL ||
+           _state == ModemState::DIALING ||
+           _state == ModemState::RINGING_IN;
+  }
+  const char* getOperator() const { return _operator; }
+  const char* getCallPhone() const { return _callPhone; }
+  uint32_t getCallStartTime() const { return _callStartTime; }
+
+  // --- Device info (populated during init) ---
+  const char* getIMEI() const { return _imei; }
+  const char* getIMSI() const { return _imsi; }
+  const char* getAPN() const { return _apn; }
+  const char* getAPNSource() const { return _apnSource; }  // "auto", "network", "user", "none"
+
+  // --- APN configuration ---
+  // Set APN manually (overrides auto-detection). Persists to SD.
+  void setAPN(const char* apn);
+  // Load user-configured APN from SD card. Returns true if found.
+  static bool loadAPNConfig(char* apnOut, int maxLen);
+  // Save user-configured APN to SD card.
+  static void saveAPNConfig(const char* apn);
+
+  // Pause/resume polling — used by web reader to avoid Core 0 contention
+  // during WiFi TLS handshakes.  While paused, the task skips AT commands
+  // (SMS poll, CSQ poll) but still drains URCs and handles call commands
+  // so incoming calls aren't missed.
+  void pausePolling()  { _paused = true; }
+  void resumePolling() { _paused = false; }
+  bool isPaused() const { return _paused; }
+
+  static const char* stateToString(ModemState s);
+
+  // Persistent enable/disable config (SD file /sms/modem.cfg)
+  static bool loadEnabledConfig();
+  static void saveEnabledConfig(bool enabled);
+
+private:
+  volatile ModemState _state = ModemState::OFF;
+  volatile int _csq = 99;    // 99 = unknown
+  volatile bool _paused = false;  // Suppresses AT polling when true
+  char _operator[24] = {0};
+
+  // Device identity (populated during Phase 2 init)
+  char _imei[20] = {0};      // IMEI from AT+GSN
+  char _imsi[20] = {0};      // IMSI from AT+CIMI (for APN lookup)
+  char _apn[64] = {0};       // Active APN
+  char _apnSource[8] = {0};  // "auto", "network", "user", "none"
+
+  // Call state (written by modem task, read by main loop)
+  char _callPhone[SMS_PHONE_LEN] = {0};  // Current call number
+  volatile uint32_t _callStartTime = 0;    // millis() when call connected
+
+  // Ringtone state
+  volatile bool _ringtoneEnabled = false;
+  bool _ringing = false;              // Shadow of RINGING_IN for tone logic
+  unsigned long _nextRingTone = 0;    // Next tone burst timestamp (modem task)
+  bool _toneActive = false;           // Is a tone currently sounding
+
+  TaskHandle_t _taskHandle = nullptr;
+
+  // SMS queues
+  QueueHandle_t _sendQueue = nullptr;
+  QueueHandle_t _recvQueue = nullptr;
+
+  // Call queues
+  QueueHandle_t _callCmdQueue = nullptr;   // main loop → modem task
+  QueueHandle_t _callEvtQueue = nullptr;   // modem task → main loop
+
+  SemaphoreHandle_t _uartMutex = nullptr;
+
+  // URC line buffer (accumulated between AT commands)
+  static const int URC_BUF_SIZE = 256;
+  char _urcBuf[URC_BUF_SIZE];
+  int  _urcPos = 0;
+
+  // UART AT command helpers (called only from modem task)
+  bool modemPowerOn();
+  bool sendAT(const char* cmd, const char* expect, uint32_t timeout_ms = 2000);
+  bool waitResponse(const char* expect, uint32_t timeout_ms, char* buf = nullptr, size_t bufLen = 0);
+  void pollCSQ();
+  void pollIncomingSMS();
+  bool doSendSMS(const char* phone, const char* body);
+
+  // URC (unsolicited result code) handling
+  void drainURCs();                // Read available UART data, process complete lines
+  void processURCLine(const char* line);  // Handle a single URC line
+
+  // APN resolution (called from modem task during init)
+  void resolveAPN();              // Auto-detect APN from network/IMSI/user config
+
+  // Call control (called from modem task)
+  bool doDialCall(const char* phone);
+  bool doAnswerCall();
+  bool doHangup();
+  bool doSendDTMF(char digit);
+  bool doSetVolume(uint8_t level);
+  void queueCallEvent(CallEventType type, const char* phone = nullptr, uint32_t duration = 0);
+  void handleRingtone();  // Play tone bursts while incoming call rings
+
+  // FreeRTOS task
+  static void taskEntry(void* param);
+  void taskLoop();
+};
+
+// Global singleton
+extern ModemManager modemManager;
+
+#endif // MODEM_MANAGER_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/Radiopresets.h

@@ -0,0 +1,34 @@
+#pragma once
+
+// ---------------------------------------------------------------------------
+// Radio presets — shared between SettingsScreen (UI) and MyMesh (Serial CLI)
+// ---------------------------------------------------------------------------
+
+struct RadioPreset {
+  const char* name;
+  float freq;
+  float bw;
+  uint8_t sf;
+  uint8_t cr;
+  uint8_t tx_power;
+};
+
+static const RadioPreset RADIO_PRESETS[] = {
+  { "Australia",              915.800f, 250.0f,  10, 5, 22 },
+  { "Australia (Narrow)",     916.575f,  62.5f,   7, 8, 22 },
+  { "Australia: SA, WA",      923.125f,  62.5f,   8, 8, 22 },
+  { "Australia: QLD",         923.125f,  62.5f,   8, 5, 22 },
+  { "EU/UK (Narrow)",         869.618f,  62.5f,   8, 8, 14 },
+  { "EU/UK (Long Range)",     869.525f, 250.0f,  11, 5, 14 },
+  { "EU/UK (Medium Range)",   869.525f, 250.0f,  10, 5, 14 },
+  { "Czech Republic (Narrow)",869.432f,  62.5f,   7, 5, 14 },
+  { "EU 433 (Long Range)",    433.650f, 250.0f,  11, 5, 14 },
+  { "New Zealand",            917.375f, 250.0f,  11, 5, 22 },
+  { "New Zealand (Narrow)",   917.375f,  62.5f,   7, 5, 22 },
+  { "Portugal 433",           433.375f,  62.5f,   9, 6, 14 },
+  { "Portugal 868",           869.618f,  62.5f,   7, 6, 14 },
+  { "Switzerland",            869.618f,  62.5f,   8, 8, 14 },
+  { "USA/Canada (Recommended)",910.525f, 62.5f,   7, 5, 22 },
+  { "Vietnam",                920.250f, 250.0f,  11, 5, 22 },
+};
+#define NUM_RADIO_PRESETS (sizeof(RADIO_PRESETS) / sizeof(RADIO_PRESETS[0]))

examples/companion_radio/ui-new/SMSContacts.cpp

@@ -0,0 +1,8 @@
+#ifdef HAS_4G_MODEM
+
+#include "SMSContacts.h"
+
+// Global singleton
+SMSContactStore smsContacts;
+
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSContacts.h

@@ -0,0 +1,176 @@
+#pragma once
+
+// =============================================================================
+// SMSContacts - Phone-to-name lookup for SMS contacts (4G variant)
+//
+// Stores contacts in /sms/contacts.txt on SD card.
+// Format: one contact per line as "phone=Display Name"
+//
+// Completely separate from mesh ContactInfo / IdentityStore.
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef SMS_CONTACTS_H
+#define SMS_CONTACTS_H
+
+#include <Arduino.h>
+#include <SD.h>
+
+#define SMS_CONTACT_NAME_LEN   24
+#define SMS_CONTACT_MAX        30
+#define SMS_CONTACTS_FILE      "/sms/contacts.txt"
+
+struct SMSContact {
+  char phone[20];   // matches SMS_PHONE_LEN
+  char name[SMS_CONTACT_NAME_LEN];
+  bool valid;
+};
+
+class SMSContactStore {
+public:
+  void begin() {
+    _count = 0;
+    memset(_contacts, 0, sizeof(_contacts));
+    load();
+  }
+
+  // Look up a name by phone number. Returns nullptr if not found.
+  const char* lookup(const char* phone) const {
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        return _contacts[i].name;
+      }
+    }
+    return nullptr;
+  }
+
+  // Fill buf with display name if found, otherwise copy phone number.
+  // Returns true if a name was found.
+  bool displayName(const char* phone, char* buf, size_t bufLen) const {
+    const char* name = lookup(phone);
+    if (name && name[0]) {
+      strncpy(buf, name, bufLen - 1);
+      buf[bufLen - 1] = '\0';
+      return true;
+    }
+    strncpy(buf, phone, bufLen - 1);
+    buf[bufLen - 1] = '\0';
+    return false;
+  }
+
+  // Add or update a contact. Returns true on success.
+  bool set(const char* phone, const char* name) {
+    // Update existing
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        strncpy(_contacts[i].name, name, SMS_CONTACT_NAME_LEN - 1);
+        _contacts[i].name[SMS_CONTACT_NAME_LEN - 1] = '\0';
+        save();
+        return true;
+      }
+    }
+    // Add new
+    if (_count >= SMS_CONTACT_MAX) return false;
+    strncpy(_contacts[_count].phone, phone, sizeof(_contacts[_count].phone) - 1);
+    _contacts[_count].phone[sizeof(_contacts[_count].phone) - 1] = '\0';
+    strncpy(_contacts[_count].name, name, SMS_CONTACT_NAME_LEN - 1);
+    _contacts[_count].name[SMS_CONTACT_NAME_LEN - 1] = '\0';
+    _contacts[_count].valid = true;
+    _count++;
+    save();
+    return true;
+  }
+
+  // Remove a contact by phone number
+  bool remove(const char* phone) {
+    for (int i = 0; i < _count; i++) {
+      if (_contacts[i].valid && strcmp(_contacts[i].phone, phone) == 0) {
+        for (int j = i; j < _count - 1; j++) {
+          _contacts[j] = _contacts[j + 1];
+        }
+        _count--;
+        memset(&_contacts[_count], 0, sizeof(SMSContact));
+        save();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Accessors for list browsing
+  int count() const { return _count; }
+  const SMSContact& get(int index) const { return _contacts[index]; }
+
+  // Check if a contact exists
+  bool exists(const char* phone) const { return lookup(phone) != nullptr; }
+
+private:
+  SMSContact _contacts[SMS_CONTACT_MAX];
+  int _count = 0;
+
+  void load() {
+    File f = SD.open(SMS_CONTACTS_FILE, FILE_READ);
+    if (!f) {
+      Serial.println("[SMSContacts] No contacts file, starting fresh");
+      return;
+    }
+
+    char line[64];
+    while (f.available() && _count < SMS_CONTACT_MAX) {
+      int pos = 0;
+      while (f.available() && pos < (int)sizeof(line) - 1) {
+        char c = f.read();
+        if (c == '\n' || c == '\r') break;
+        line[pos++] = c;
+      }
+      line[pos] = '\0';
+      if (pos == 0) continue;
+      // Consume trailing CR/LF
+      while (f.available()) {
+        int pk = f.peek();
+        if (pk == '\n' || pk == '\r') { f.read(); continue; }
+        break;
+      }
+
+      // Parse "phone=name"
+      char* eq = strchr(line, '=');
+      if (!eq) continue;
+      *eq = '\0';
+      const char* phone = line;
+      const char* name = eq + 1;
+      if (strlen(phone) == 0 || strlen(name) == 0) continue;
+
+      strncpy(_contacts[_count].phone, phone, sizeof(_contacts[_count].phone) - 1);
+      strncpy(_contacts[_count].name, name, SMS_CONTACT_NAME_LEN - 1);
+      _contacts[_count].valid = true;
+      _count++;
+    }
+    f.close();
+    Serial.printf("[SMSContacts] Loaded %d contacts\n", _count);
+  }
+
+  void save() {
+    if (!SD.exists("/sms")) SD.mkdir("/sms");
+    File f = SD.open(SMS_CONTACTS_FILE, FILE_WRITE);
+    if (!f) {
+      Serial.println("[SMSContacts] Failed to write contacts file");
+      return;
+    }
+    for (int i = 0; i < _count; i++) {
+      if (!_contacts[i].valid) continue;
+      f.print(_contacts[i].phone);
+      f.print('=');
+      f.println(_contacts[i].name);
+    }
+    f.close();
+  }
+};
+
+// Global singleton
+extern SMSContactStore smsContacts;
+
+#endif // SMS_CONTACTS_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSStore.cpp

@@ -0,0 +1,196 @@
+#ifdef HAS_4G_MODEM
+
+#include "SMSStore.h"
+#include <Mesh.h>   // For MESH_DEBUG_PRINTLN
+#include "target.h" // For SDCARD_CS macro
+
+// Global singleton
+SMSStore smsStore;
+
+void SMSStore::begin() {
+  // Ensure SMS directory exists
+  if (!SD.exists(SMS_DIR)) {
+    SD.mkdir(SMS_DIR);
+    MESH_DEBUG_PRINTLN("[SMSStore] created %s", SMS_DIR);
+  }
+  _ready = true;
+  MESH_DEBUG_PRINTLN("[SMSStore] ready");
+}
+
+void SMSStore::phoneToFilename(const char* phone, char* out, size_t outLen) {
+  // Convert phone number to safe filename: strip non-alphanumeric, prefix with dir
+  // e.g. "+1234567890" -> "/sms/p1234567890.sms"
+  char safe[SMS_PHONE_LEN];
+  int j = 0;
+  for (int i = 0; phone[i] && j < SMS_PHONE_LEN - 1; i++) {
+    char c = phone[i];
+    if ((c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) {
+      safe[j++] = c;
+    }
+  }
+  safe[j] = '\0';
+  snprintf(out, outLen, "%s/p%s.sms", SMS_DIR, safe);
+}
+
+bool SMSStore::saveMessage(const char* phone, const char* body, bool isSent, uint32_t timestamp) {
+  if (!_ready) return false;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  // Build record
+  SMSRecord rec;
+  memset(&rec, 0, sizeof(rec));
+  rec.timestamp = timestamp;
+  rec.isSent = isSent ? 1 : 0;
+  rec.bodyLen = strlen(body);
+  if (rec.bodyLen >= SMS_BODY_LEN) rec.bodyLen = SMS_BODY_LEN - 1;
+  strncpy(rec.phone, phone, SMS_PHONE_LEN - 1);
+  strncpy(rec.body, body, SMS_BODY_LEN - 1);
+
+  // Append to file
+  File f = SD.open(filepath, FILE_APPEND);
+  if (!f) {
+    // Try creating
+    f = SD.open(filepath, FILE_WRITE);
+    if (!f) {
+      MESH_DEBUG_PRINTLN("[SMSStore] can't open %s", filepath);
+      return false;
+    }
+  }
+
+  size_t written = f.write((uint8_t*)&rec, sizeof(rec));
+  f.close();
+
+  // Release SD CS
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return written == sizeof(rec);
+}
+
+int SMSStore::loadConversations(SMSConversation* out, int maxCount) {
+  if (!_ready) return 0;
+
+  File dir = SD.open(SMS_DIR);
+  if (!dir || !dir.isDirectory()) return 0;
+
+  int count = 0;
+  File entry;
+  while ((entry = dir.openNextFile()) && count < maxCount) {
+    const char* name = entry.name();
+    // Only process .sms files
+    if (!strstr(name, ".sms")) { entry.close(); continue; }
+
+    size_t fileSize = entry.size();
+    if (fileSize < sizeof(SMSRecord)) { entry.close(); continue; }
+
+    int numRecords = fileSize / sizeof(SMSRecord);
+
+    // Read the last record for preview
+    SMSRecord lastRec;
+    entry.seek(fileSize - sizeof(SMSRecord));
+    if (entry.read((uint8_t*)&lastRec, sizeof(SMSRecord)) != sizeof(SMSRecord)) {
+      entry.close();
+      continue;
+    }
+
+    SMSConversation& conv = out[count];
+    memset(&conv, 0, sizeof(SMSConversation));
+    strncpy(conv.phone, lastRec.phone, SMS_PHONE_LEN - 1);
+    strncpy(conv.preview, lastRec.body, 39);
+    conv.preview[39] = '\0';
+    conv.lastTimestamp = lastRec.timestamp;
+    conv.messageCount = numRecords;
+    conv.unreadCount = 0;  // TODO: track read state
+    conv.valid = true;
+
+    count++;
+    entry.close();
+  }
+  dir.close();
+
+  // Release SD CS
+  digitalWrite(SDCARD_CS, HIGH);
+
+  // Sort by most recent (simple bubble sort, small N)
+  for (int i = 0; i < count - 1; i++) {
+    for (int j = 0; j < count - 1 - i; j++) {
+      if (out[j].lastTimestamp < out[j + 1].lastTimestamp) {
+        SMSConversation tmp = out[j];
+        out[j] = out[j + 1];
+        out[j + 1] = tmp;
+      }
+    }
+  }
+
+  return count;
+}
+
+int SMSStore::loadMessages(const char* phone, SMSMessage* out, int maxCount) {
+  if (!_ready) return 0;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  File f = SD.open(filepath, FILE_READ);
+  if (!f) return 0;
+
+  size_t fileSize = f.size();
+  int numRecords = fileSize / sizeof(SMSRecord);
+
+  // Load from end of file (most recent N messages), in chronological order
+  int startIdx = numRecords > maxCount ? numRecords - maxCount : 0;
+
+  // Read chronologically (oldest first) for chat-style display
+  SMSRecord rec;
+  int outIdx = 0;
+  for (int i = startIdx; i < numRecords && outIdx < maxCount; i++) {
+    f.seek(i * sizeof(SMSRecord));
+    if (f.read((uint8_t*)&rec, sizeof(SMSRecord)) != sizeof(SMSRecord)) continue;
+
+    out[outIdx].timestamp = rec.timestamp;
+    out[outIdx].isSent = rec.isSent != 0;
+    out[outIdx].valid = true;
+    strncpy(out[outIdx].phone, rec.phone, SMS_PHONE_LEN - 1);
+    strncpy(out[outIdx].body, rec.body, SMS_BODY_LEN - 1);
+    outIdx++;
+  }
+
+  f.close();
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return outIdx;
+}
+
+bool SMSStore::deleteConversation(const char* phone) {
+  if (!_ready) return false;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  bool ok = SD.remove(filepath);
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return ok;
+}
+
+int SMSStore::getMessageCount(const char* phone) {
+  if (!_ready) return 0;
+
+  char filepath[64];
+  phoneToFilename(phone, filepath, sizeof(filepath));
+
+  File f = SD.open(filepath, FILE_READ);
+  if (!f) return 0;
+
+  int count = f.size() / sizeof(SMSRecord);
+  f.close();
+
+  digitalWrite(SDCARD_CS, HIGH);
+
+  return count;
+}
+
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/SMSStore.h

@@ -0,0 +1,87 @@
+#pragma once
+
+// =============================================================================
+// SMSStore - SD card backed SMS message storage
+//
+// Stores sent and received messages in /sms/ on the SD card.
+// Each conversation is a separate file named by phone number (sanitised).
+// Messages are appended as fixed-size records for simple random access.
+//
+// Guard: HAS_4G_MODEM
+// =============================================================================
+
+#ifdef HAS_4G_MODEM
+
+#ifndef SMS_STORE_H
+#define SMS_STORE_H
+
+#include <Arduino.h>
+#include <SD.h>
+
+#define SMS_PHONE_LEN    20
+#define SMS_BODY_LEN    161
+#define SMS_MAX_CONVERSATIONS 20
+#define SMS_DIR          "/sms"
+
+// Fixed-size on-disk record (256 bytes, easy alignment)
+struct SMSRecord {
+  uint32_t timestamp;           // epoch seconds
+  uint8_t  isSent;              // 1=sent, 0=received
+  uint8_t  reserved[2];
+  uint8_t  bodyLen;             // actual length of body
+  char     phone[SMS_PHONE_LEN]; // 20
+  char     body[SMS_BODY_LEN];   // 161
+  uint8_t  padding[256 - 4 - 3 - 1 - SMS_PHONE_LEN - SMS_BODY_LEN];
+};
+
+// In-memory message for UI
+struct SMSMessage {
+  uint32_t timestamp;
+  bool     isSent;
+  bool     valid;
+  char     phone[SMS_PHONE_LEN];
+  char     body[SMS_BODY_LEN];
+};
+
+// Conversation summary for inbox view
+struct SMSConversation {
+  char     phone[SMS_PHONE_LEN];
+  char     preview[40];         // last message preview
+  uint32_t lastTimestamp;
+  int      messageCount;
+  int      unreadCount;
+  bool     valid;
+};
+
+class SMSStore {
+public:
+  void begin();
+  bool isReady() const { return _ready; }
+
+  // Save a message (sent or received)
+  bool saveMessage(const char* phone, const char* body, bool isSent, uint32_t timestamp);
+
+  // Load conversation list (sorted by most recent)
+  int loadConversations(SMSConversation* out, int maxCount);
+
+  // Load messages for a specific phone number (chronological, oldest first)
+  int loadMessages(const char* phone, SMSMessage* out, int maxCount);
+
+  // Delete all messages for a phone number
+  bool deleteConversation(const char* phone);
+
+  // Get total message count for a phone number
+  int getMessageCount(const char* phone);
+
+private:
+  bool _ready = false;
+
+  // Convert phone number to safe filename
+  void phoneToFilename(const char* phone, char* out, size_t outLen);
+};
+
+// Global singleton
+extern SMSStore smsStore;
+
+#endif // SMS_STORE_H
+#endif // HAS_4G_MODEM

examples/companion_radio/ui-new/Touchinput.h

@@ -0,0 +1,128 @@
+#pragma once
+
+// =============================================================================
+// TouchInput - Minimal CST328/CST3530 touch driver for T-Deck Pro
+//
+// Uses raw I2C reads on the shared Wire bus. No external library needed.
+// Protocol confirmed via raw serial capture from actual hardware:
+//
+//   Register 0xD000, 7 bytes:
+//   buf[0]: event flags (0xAB = idle/no touch, other = active touch)
+//   buf[1]: X coordinate high data
+//   buf[2]: Y coordinate high data
+//   buf[3]: X low nibble (bits 7:4) | Y low nibble (bits 3:0)
+//   buf[4]: pressure
+//   buf[5]: touch count (& 0x7F), typically 0x01 for single touch
+//   buf[6]: 0xAB always (check byte, ignore)
+//
+//   Coordinate formula:
+//     x = (buf[1] << 4) | ((buf[3] >> 4) & 0x0F)   → 0..239
+//     y = (buf[2] << 4) | (buf[3] & 0x0F)           → 0..319
+//
+// Hardware: CST328 at 0x1A, INT=GPIO12, RST=GPIO38 (V1.1)
+//
+// Guard: HAS_TOUCHSCREEN
+// =============================================================================
+
+#ifdef HAS_TOUCHSCREEN
+
+#ifndef TOUCH_INPUT_H
+#define TOUCH_INPUT_H
+
+#include <Arduino.h>
+#include <Wire.h>
+
+class TouchInput {
+public:
+  static const uint8_t TOUCH_ADDR = 0x1A;
+
+  TouchInput(TwoWire* wire = &Wire)
+    : _wire(wire), _intPin(-1), _initialized(false), _debugCount(0), _lastPoll(0) {}
+
+  bool begin(int intPin) {
+    _intPin = intPin;
+    pinMode(_intPin, INPUT);
+
+    // Verify the touch controller is present on the bus
+    _wire->beginTransmission(TOUCH_ADDR);
+    uint8_t err = _wire->endTransmission();
+    if (err != 0) {
+      Serial.printf("[Touch] CST328 not found at 0x%02X (err=%d)\n", TOUCH_ADDR, err);
+      return false;
+    }
+
+    Serial.printf("[Touch] CST328 found at 0x%02X, INT=GPIO%d\n", TOUCH_ADDR, _intPin);
+    _initialized = true;
+    return true;
+  }
+
+  bool isReady() const { return _initialized; }
+
+  // Poll for touch. Returns true if a finger is down, fills x and y.
+  // Coordinates are in physical display space (0-239 X, 0-319 Y).
+  // NOTE: CST328 INT pin is pulse-based, not level. We cannot rely on
+  // digitalRead(INT) for touch state. Instead, always read and check buf[0].
+  bool getPoint(int16_t &x, int16_t &y) {
+    if (!_initialized) return false;
+
+    // Rate limit: poll at most every 20ms (50 Hz) to avoid I2C bus congestion
+    unsigned long now = millis();
+    if (now - _lastPoll < 20) return false;
+    _lastPoll = now;
+
+    uint8_t buf[7];
+    memset(buf, 0, sizeof(buf));
+
+    // Write register address 0xD000
+    _wire->beginTransmission(TOUCH_ADDR);
+    _wire->write(0xD0);
+    _wire->write(0x00);
+    if (_wire->endTransmission(false) != 0) return false;
+
+    // Read 7 bytes of touch data
+    uint8_t received = _wire->requestFrom(TOUCH_ADDR, (uint8_t)7);
+    if (received < 7) return false;
+    for (int i = 0; i < 7; i++) buf[i] = _wire->read();
+
+    // buf[0] == 0xAB means idle (no touch active)
+    if (buf[0] == 0xAB) return false;
+
+    // buf[0] == 0x00 can appear on finger-up transition — ignore
+    if (buf[0] == 0x00) return false;
+
+    // Touch count from buf[5]
+    uint8_t count = buf[5] & 0x7F;
+    if (count == 0 || count > 5) return false;
+
+    // Parse coordinates (CST226/CST328 format confirmed by hardware capture)
+    //   x = (buf[1] << 4) | high nibble of buf[3]
+    //   y = (buf[2] << 4) | low nibble of buf[3]
+    int16_t tx = ((int16_t)buf[1] << 4) | ((buf[3] >> 4) & 0x0F);
+    int16_t ty = ((int16_t)buf[2] << 4) | (buf[3] & 0x0F);
+
+    // Sanity check (panel is 240x320)
+    if (tx < 0 || tx > 260 || ty < 0 || ty > 340) return false;
+
+    // Debug: log first 20 touch events with parsed coordinates
+    if (_debugCount < 50) {
+      Serial.printf("[Touch] Raw: %02X %02X %02X %02X %02X %02X %02X → x=%d y=%d\n",
+                    buf[0], buf[1], buf[2], buf[3], buf[4], buf[5], buf[6],
+                    tx, ty);
+      _debugCount++;
+    }
+
+    x = tx;
+    y = ty;
+    return true;
+  }
+
+private:
+  TwoWire* _wire;
+  int _intPin;
+  bool _initialized;
+  int _debugCount;
+  unsigned long _lastPoll;
+};
+
+#endif // TOUCH_INPUT_H
+#endif // HAS_TOUCHSCREEN

examples/companion_radio/ui-new/UITask.h

@@ -22,6 +22,25 @@
 #include "../AbstractUITask.h"
 #include "../NodePrefs.h"
 
+#ifdef HAS_4G_MODEM
+  #include "SMSScreen.h"
+#endif
+
+#ifdef MECK_WEB_READER
+  #include "WebReaderScreen.h"
+#endif
+
+#ifdef MECK_AUDIO_VARIANT
+  #include "AlarmScreen.h"
+#endif
+
+#if defined(LilyGo_T5S3_EPaper_Pro)
+  #include "VirtualKeyboard.h"
+#endif
+
+// MapScreen.h included in UITask.cpp and main.cpp only (PNGdec headers
+// conflict with BLE if pulled into the global include chain)
+
 class UITask : public AbstractUITask {
   DisplayDriver* _display;
   SensorManager* _sensors;
@@ -32,11 +51,21 @@ class UITask : public AbstractUITask {
   GenericVibration vibration;
 #endif
   unsigned long _next_refresh, _auto_off;
+  unsigned long _kb_flash_off_at;          // Keyboard flash turn-off timer
+#ifdef HAS_4G_MODEM
+  bool _incomingCallRinging;               // Currently ringing (incoming call)
+  unsigned long _nextCallFlash;            // Next LED toggle time
+  bool _callFlashState;                    // Current LED state during ring
+#endif
   NodePrefs* _node_prefs;
   char _alert[80];
   unsigned long _alert_expiry;
+  bool _hintActive = false;          // Boot navigation hint overlay
+  unsigned long _hintExpiry = 0;     // Auto-dismiss time for hint
+  bool _pendingBootHint = false;     // Deferred hint — show after splash screen
   int _msgcount;
   unsigned long ui_started_at, next_batt_chck;
+  uint8_t _low_batt_count = 0;  // Consecutive low-voltage readings for debounce
   int next_backlight_btn_check = 0;
 #ifdef PIN_STATUS_LED
   int led_state = 0;
@@ -52,7 +81,75 @@ class UITask : public AbstractUITask {
   UIScreen* home;
   UIScreen* msg_preview;
   UIScreen* channel_screen;  // Channel message history screen
+  UIScreen* contacts_screen; // Contacts list screen
+  UIScreen* text_reader;     // *** NEW: Text reader screen ***
+  UIScreen* notes_screen;    // Notes editor screen
+  UIScreen* settings_screen; // Settings/onboarding screen
+  UIScreen* audiobook_screen; // Audiobook player screen (null if not available)
+#ifdef MECK_AUDIO_VARIANT
+  UIScreen* alarm_screen;     // Alarm clock screen (audio variant only)
+#endif
+#ifdef HAS_4G_MODEM
+  UIScreen* sms_screen;      // SMS messaging screen (4G variant only)
+#endif
+  UIScreen* repeater_admin;   // Repeater admin screen
+  UIScreen* discovery_screen;  // Node discovery scan screen
+  UIScreen* last_heard_screen; // Last heard passive advert list
+#ifdef MECK_WEB_READER
+  UIScreen* web_reader;       // Web reader screen (lazy-init, WiFi required)
+#endif
+  UIScreen* map_screen;       // Map tile screen (GPS + SD card tiles)
   UIScreen* curr;
+  bool _homeShowingTiles = false;  // Set by HomeScreen render when tile grid is visible
+  int _tileGridVY = 44;           // Virtual Y of tile grid top (updated each render)
+#if defined(LilyGo_T5S3_EPaper_Pro)
+  UIScreen* lock_screen;     // Lock screen (big clock + battery + unread)
+  UIScreen* _screenBeforeLock = nullptr;
+  bool _locked = false;
+  unsigned long _lastInputMillis = 0;  // Auto-lock idle tracking
+  unsigned long _lastLockRefresh = 0;  // Periodic lock screen clock update
+
+  VirtualKeyboard _vkb;
+  bool _vkbActive = false;
+  UIScreen* _screenBeforeVKB = nullptr;
+  unsigned long _vkbOpenedAt = 0;
+
+  // Powersaving: light sleep when locked + idle (standalone only — no BLE/WiFi)
+  // Wakes on LoRa packet (DIO1), boot button (GPIO0), or 30-min timer
+#if !defined(BLE_PIN_CODE) && !defined(MECK_WIFI_COMPANION)
+  unsigned long _psLastActive = 0;       // millis() at last wake or lock entry
+  unsigned long _psNextSleepSecs = 60;   // Seconds before first sleep (60s), then 5s cycles
+#endif
+#ifdef MECK_CARDKB
+  bool _cardkbDetected = false;
+#endif
+#elif defined(LilyGo_TDeck_Pro)
+  UIScreen* lock_screen;     // Lock screen (big clock + battery + unread)
+  UIScreen* _screenBeforeLock = nullptr;
+  bool _locked = false;
+  unsigned long _lastInputMillis = 0;  // Auto-lock idle tracking
+  unsigned long _lastLockRefresh = 0;  // Periodic lock screen clock update
+#endif
+
+  // --- Message dedup ring buffer (suppress retry spam at UI level) ---
+  #define MSG_DEDUP_SIZE 8
+  #define MSG_DEDUP_WINDOW_MS 60000  // 60 seconds
+  struct MsgDedup {
+    uint32_t name_hash;
+    uint32_t text_hash;
+    unsigned long millis;
+  };
+  MsgDedup _dedup[MSG_DEDUP_SIZE];
+  int _dedupIdx = 0;
+
+  // --- Per-contact DM unread tracking ---
+  uint8_t* _dmUnread = nullptr;  // PSRAM-allocated, MAX_CONTACTS entries
+
+  static uint32_t simpleHash(const char* s) {
+    uint32_t h = 5381;
+    while (*s) { h = ((h << 5) + h) ^ (uint8_t)*s++; }
+    return h;
+  }
 
   void userLedHandler();
 
@@ -68,37 +165,166 @@ public:
 
   UITask(mesh::MainBoard* board, BaseSerialInterface* serial) : AbstractUITask(board, serial), _display(NULL), _sensors(NULL) {
     next_batt_chck = _next_refresh = 0;
+    _kb_flash_off_at = 0;
+  #ifdef HAS_4G_MODEM
+    _incomingCallRinging = false;
+    _nextCallFlash = 0;
+    _callFlashState = false;
+  #endif
     ui_started_at = 0;
     curr = NULL;
   }
   void begin(DisplayDriver* display, SensorManager* sensors, NodePrefs* node_prefs);
 
-  void gotoHomeScreen() { setCurrScreen(home); }
+  void gotoHomeScreen();
   void gotoChannelScreen();  // Navigate to channel message screen
-  void showAlert(const char* text, int duration_millis);
+  void gotoDMTab();          // Navigate directly to DM tab on channel screen
+  void gotoDMConversation(const char* contactName, int contactIdx = -1, uint8_t perms = 0);
+  void gotoContactsScreen(); // Navigate to contacts list
+  void gotoTextReader();     // *** NEW: Navigate to text reader ***
+  void gotoNotesScreen();    // Navigate to notes editor
+  void gotoSettingsScreen(); // Navigate to settings
+  void gotoOnboarding();     // Navigate to settings in onboarding mode
+  void gotoAudiobookPlayer(); // Navigate to audiobook player
+#ifdef MECK_AUDIO_VARIANT
+  void gotoAlarmScreen();     // Navigate to alarm clock
+#endif
+  void gotoRepeaterAdmin(int contactIdx);  // Navigate to repeater admin
+  void gotoRepeaterAdminDirect(int contactIdx);  // Auto-login admin (L key from conversation)
+  void gotoDiscoveryScreen();              // Navigate to node discovery scan
+  void gotoLastHeardScreen();              // Navigate to last heard passive list
+#if HAS_GPS
+  void gotoMapScreen();         // Navigate to map tile screen
+#endif
+#ifdef MECK_WEB_READER
+  void gotoWebReader();         // Navigate to web reader (browser)
+#endif
+#ifdef HAS_4G_MODEM
+  void gotoSMSScreen();
+  bool isOnSMSScreen() const { return curr == sms_screen; }
+  SMSScreen* getSMSScreen() const { return (SMSScreen*)sms_screen; }
+#endif
+  void showAlert(const char* text, int duration_millis) override;
+  void forceRefresh() override { _next_refresh = 100; }
+  void showBootHint(bool immediate = false);  // Show navigation hint overlay on first boot
+  void dismissBootHint();  // Dismiss hint and save preference
+  bool isHintActive() const { return _hintActive; }
+  // Wake display and extend auto-off timer. Call this when handling keys
+  // outside of injectKey() to prevent display auto-off during direct input.
+  void keepAlive() {
+    if (_display != NULL && !_display->isOn()) _display->turnOn();
+    _auto_off = millis() + 15000;  // matches AUTO_OFF_MILLIS default
+  }
   int  getMsgCount() const { return _msgcount; }
+  int  getUnreadMsgCount() const;  // Per-channel unread tracking (standalone)
+  
+  // Per-contact DM unread tracking
+  bool hasDMUnread(int contactIdx) const;
+  int  getDMUnreadCount(int contactIdx) const;
+  void clearDMUnread(int contactIdx);
+
+  // Flag: suppress room→conversation redirect on next login (L key admin access)
+  bool _skipRoomRedirect = false;
   bool hasDisplay() const { return _display != NULL; }
   bool isButtonPressed() const;
   bool isOnChannelScreen() const { return curr == channel_screen; }
+  bool isOnContactsScreen() const { return curr == contacts_screen; }
+  bool isOnTextReader() const { return curr == text_reader; }  // *** NEW ***
+  bool isOnHomeScreen() const { return curr == home; }
+  bool isHomeShowingTiles() const { return _homeShowingTiles; }
+  void setHomeShowingTiles(bool v) { _homeShowingTiles = v; }
+  int  getTileGridVY() const { return _tileGridVY; }
+  void setTileGridVY(int vy) { _tileGridVY = vy; }
+  bool isOnNotesScreen() const { return curr == notes_screen; }
+  bool isOnSettingsScreen() const { return curr == settings_screen; }
+  bool isOnAudiobookPlayer() const { return curr == audiobook_screen; }
+#ifdef MECK_AUDIO_VARIANT
+  bool isOnAlarmScreen() const { return curr == alarm_screen; }
+#endif
+  bool isOnRepeaterAdmin() const { return curr == repeater_admin; }
+  bool isOnDiscoveryScreen() const { return curr == discovery_screen; }
+  bool isOnLastHeardScreen() const { return curr == last_heard_screen; }
+  bool isOnMapScreen() const { return curr == map_screen; }
+#if defined(LilyGo_T5S3_EPaper_Pro) || defined(LilyGo_TDeck_Pro)
+  bool isLocked() const { return _locked; }
+  void lockScreen();
+  void unlockScreen();
+#endif
+#if defined(LilyGo_T5S3_EPaper_Pro)
+  bool isVKBActive() const { return _vkbActive; }
+  unsigned long vkbOpenedAt() const { return _vkbOpenedAt; }
+  VirtualKeyboard& getVKB() { return _vkb; }
+  void showVirtualKeyboard(VKBPurpose purpose, const char* label, const char* initial, int maxLen, int contextIdx = 0);
+  void onVKBSubmit();
+  void onVKBCancel();
+#ifdef MECK_CARDKB
+  void setCardKBDetected(bool v) { _cardkbDetected = v; }
+  bool hasCardKB() const { return _cardkbDetected; }
+  void feedCardKBChar(char c);
+#endif
+#endif
+#ifdef MECK_WEB_READER
+  bool isOnWebReader() const { return curr == web_reader; }
+#endif
+
+#ifdef MECK_AUDIO_VARIANT
+  // Check if audio is playing/paused in the background (for status indicators)
+  bool isAudioPlayingInBackground() const;
+  bool isAudioPausedInBackground() const;
+#endif
   uint8_t getChannelScreenViewIdx() const;
 
   void toggleBuzzer();
   bool getGPSState();
   void toggleGPS();
 
+  // Check if home screen is in an editing mode (e.g. UTC offset editor)
+  bool isEditingHomeScreen() const;
+  // Check if home screen is showing the Recent Adverts page
+  bool isHomeOnRecentPage() const;
+
   // Inject a key press from external source (e.g., keyboard)
   void injectKey(char c);
   
   // Add a sent message to the channel screen history
-  void addSentChannelMessage(uint8_t channel_idx, const char* sender, const char* text);
+  void addSentChannelMessage(uint8_t channel_idx, const char* sender, const char* text) override;
+  void addSentDM(const char* recipientName, const char* sender, const char* text);
+
+  // Mark channel as read when BLE companion app syncs messages
+  void markChannelReadFromBLE(uint8_t channel_idx) override;
+
+  // Repeater admin callbacks
+  void onAdminLoginResult(bool success, uint8_t permissions, uint32_t server_time) override;
+  void onAdminCliResponse(const char* from_name, const char* text) override;
+  void onAdminTelemetryResult(const uint8_t* data, uint8_t len) override;
   
   // Get current screen for checking state
   UIScreen* getCurrentScreen() const { return curr; }
   UIScreen* getMsgPreviewScreen() const { return msg_preview; }
+  UIScreen* getTextReaderScreen() const { return text_reader; }  // *** NEW ***
+  UIScreen* getNotesScreen() const { return notes_screen; }
+  UIScreen* getContactsScreen() const { return contacts_screen; }
+  UIScreen* getChannelScreen() const { return channel_screen; }
+  UIScreen* getSettingsScreen() const { return settings_screen; }
+  NodePrefs* getNodePrefs() const { return _node_prefs; }
+  UIScreen* getAudiobookScreen() const { return audiobook_screen; }
+  void setAudiobookScreen(UIScreen* s) { audiobook_screen = s; }
+#ifdef MECK_AUDIO_VARIANT
+  UIScreen* getAlarmScreen() const { return alarm_screen; }
+  void setAlarmScreen(UIScreen* s) { alarm_screen = s; }
+#endif
+  UIScreen* getRepeaterAdminScreen() const { return repeater_admin; }
+  UIScreen* getDiscoveryScreen() const { return discovery_screen; }
+  UIScreen* getLastHeardScreen() const { return last_heard_screen; }
+  UIScreen* getMapScreen() const { return map_screen; }
+#ifdef MECK_WEB_READER
+  UIScreen* getWebReaderScreen() const { return web_reader; }
+#endif
 
   // from AbstractUITask
   void msgRead(int msgcount) override;
-  void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount) override;
+  void newMsg(uint8_t path_len, const char* from_name, const char* text, int msgcount,
+             const uint8_t* path = nullptr, int8_t snr = 0) override;
   void notify(UIEventType t = UIEventType::none) override;
   void loop() override;
 

examples/companion_radio/ui-new/Utf8cp437.h

@@ -0,0 +1,152 @@
+#pragma once
+// =============================================================================
+// Utf8CP437.h - UTF-8 decoding and Unicode-to-CP437 mapping
+//
+// The Adafruit GFX built-in 6x8 font uses the CP437 character set for codes
+// 128-255. This header provides utilities to:
+//   1. Decode UTF-8 multi-byte sequences into Unicode codepoints
+//   2. Map Unicode codepoints to CP437 byte values for display
+//
+// Used by both EpubProcessor (at XHTML→text conversion time) and
+// TextReaderScreen (at render time for plain .txt files).
+// =============================================================================
+
+// Map a Unicode codepoint to its CP437 equivalent byte.
+// Returns the CP437 byte (0x80-0xFF) for supported accented characters,
+// the codepoint itself for ASCII (0x20-0x7E), or 0 if unmappable.
+inline uint8_t unicodeToCP437(uint32_t cp) {
+  // ASCII passthrough
+  if (cp >= 0x20 && cp < 0x7F) return (uint8_t)cp;
+
+  switch (cp) {
+    // Uppercase accented
+    case 0x00C7: return 0x80;  // Ç
+    case 0x00C9: return 0x90;  // É
+    case 0x00C4: return 0x8E;  // Ä
+    case 0x00C5: return 0x8F;  // Å
+    case 0x00C6: return 0x92;  // Æ
+    case 0x00D6: return 0x99;  // Ö
+    case 0x00DC: return 0x9A;  // Ü
+    case 0x00D1: return 0xA5;  // Ñ
+
+    // Lowercase accented
+    case 0x00E9: return 0x82;  // é
+    case 0x00E2: return 0x83;  // â
+    case 0x00E4: return 0x84;  // ä
+    case 0x00E0: return 0x85;  // à
+    case 0x00E5: return 0x86;  // å
+    case 0x00E7: return 0x87;  // ç
+    case 0x00EA: return 0x88;  // ê
+    case 0x00EB: return 0x89;  // ë
+    case 0x00E8: return 0x8A;  // è
+    case 0x00EF: return 0x8B;  // ï
+    case 0x00EE: return 0x8C;  // î
+    case 0x00EC: return 0x8D;  // ì
+    case 0x00E6: return 0x91;  // æ
+    case 0x00F4: return 0x93;  // ô
+    case 0x00F6: return 0x94;  // ö
+    case 0x00F2: return 0x95;  // ò
+    case 0x00FB: return 0x96;  // û
+    case 0x00F9: return 0x97;  // ù
+    case 0x00FF: return 0x98;  // ÿ
+    case 0x00FC: return 0x81;  // ü
+    case 0x00E1: return 0xA0;  // á
+    case 0x00ED: return 0xA1;  // í
+    case 0x00F3: return 0xA2;  // ó
+    case 0x00FA: return 0xA3;  // ú
+    case 0x00F1: return 0xA4;  // ñ
+
+    // Currency / symbols
+    case 0x00A2: return 0x9B;  // ¢
+    case 0x00A3: return 0x9C;  // £
+    case 0x00A5: return 0x9D;  // ¥
+    case 0x00BF: return 0xA8;  // ¿
+    case 0x00A1: return 0xAD;  // ¡
+    case 0x00AB: return 0xAE;  // «
+    case 0x00BB: return 0xAF;  // »
+    case 0x00B0: return 0xF8;  // °
+    case 0x00B1: return 0xF1;  // ±
+    case 0x00B5: return 0xE6;  // µ
+    case 0x00DF: return 0xE1;  // ß
+
+    // Typographic (smart quotes, dashes, etc.)
+    case 0x2018: case 0x2019: return '\'';  // Smart single quotes
+    case 0x201C: case 0x201D: return '"';   // Smart double quotes
+    case 0x2013: case 0x2014: return '-';   // En/em dash
+    case 0x2010: case 0x2011: case 0x2012: case 0x2015: return '-'; // Hyphens/bars
+    case 0x2026: return 0xFD;              // Ellipsis (CP437 has no …, use ²? no, skip)
+    case 0x2022: return 0x07;              // Bullet → CP437 bullet
+    case 0x00A0: return ' ';               // Non-breaking space
+    case 0x2039: case 0x203A: return '\''; // Single guillemets
+    case 0x2032: return '\'';              // Prime
+    case 0x2033: return '"';               // Double prime
+
+    default: return 0;  // Unmappable
+  }
+}
+
+// Decode a single UTF-8 character from a byte buffer.
+// Returns the Unicode codepoint and advances *pos past the full sequence.
+// If the sequence is invalid, returns 0xFFFD (replacement char) and advances by 1.
+//
+// buf:    input buffer
+// bufLen: total buffer length
+// pos:    pointer to current position (updated on return)
+inline uint32_t decodeUtf8Char(const char* buf, int bufLen, int* pos) {
+  int i = *pos;
+  if (i >= bufLen) return 0;
+
+  uint8_t c = (uint8_t)buf[i];
+
+  // ASCII (single byte)
+  if (c < 0x80) {
+    *pos = i + 1;
+    return c;
+  }
+
+  // Continuation byte without lead byte — skip
+  if (c < 0xC0) {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  uint32_t codepoint;
+  int extraBytes;
+
+  if ((c & 0xE0) == 0xC0) {
+    codepoint = c & 0x1F;
+    extraBytes = 1;
+  } else if ((c & 0xF0) == 0xE0) {
+    codepoint = c & 0x0F;
+    extraBytes = 2;
+  } else if ((c & 0xF8) == 0xF0) {
+    codepoint = c & 0x07;
+    extraBytes = 3;
+  } else {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  // Verify we have enough bytes and they're valid continuation bytes
+  if (i + extraBytes >= bufLen) {
+    *pos = i + 1;
+    return 0xFFFD;
+  }
+
+  for (int b = 1; b <= extraBytes; b++) {
+    uint8_t cb = (uint8_t)buf[i + b];
+    if ((cb & 0xC0) != 0x80) {
+      *pos = i + 1;
+      return 0xFFFD;
+    }
+    codepoint = (codepoint << 6) | (cb & 0x3F);
+  }
+
+  *pos = i + 1 + extraBytes;
+  return codepoint;
+}
+
+// Check if a byte is a UTF-8 continuation byte (10xxxxxx)
+inline bool isUtf8Continuation(uint8_t c) {
+  return (c & 0xC0) == 0x80;
+}

examples/companion_radio/ui-new/emojipicker.h

@@ -0,0 +1,216 @@
+#pragma once
+
+// Emoji Picker with scrolling grid and scroll bar
+// 5 columns, 4 visible rows, scrollable through all 65 emoji
+// WASD navigation, Enter to select, $/Q/Backspace to cancel
+
+#include <helpers/ui/DisplayDriver.h>
+#include "EmojiSprites.h"
+
+#define EMOJI_PICKER_COLS 5
+#define EMOJI_PICKER_VISIBLE_ROWS 4
+#define EMOJI_PICKER_TOTAL_ROWS ((EMOJI_COUNT + EMOJI_PICKER_COLS - 1) / EMOJI_PICKER_COLS)
+
+static const char* EMOJI_LABELS[EMOJI_COUNT] = {
+  "Lol",    // 0  joy
+  "Like",   // 1  thumbsup
+  "Sad",    // 2  frown
+  "WiFi",   // 3  wireless
+  "Inf",    // 4  infinity
+  "Rex",    // 5  trex
+  "Skul",   // 6  skull
+  "Cros",   // 7  cross
+  "Bolt",   // 8  lightning
+  "Hat",    // 9  tophat
+  "Moto",   // 10 motorcycle
+  "Leaf",   // 11 seedling
+  "AU",     // 12 flag_au
+  "Umbr",   // 13 umbrella
+  "Eye",    // 14 nazar
+  "Glob",   // 15 globe
+  "Rad",    // 16 radioactive
+  "Cow",    // 17 cow
+  "ET",     // 18 alien
+  "Inv",    // 19 invader
+  "Dagr",   // 20 dagger
+  "Grim",   // 21 grimace
+  "Mtn",    // 22 mountain
+  "End",    // 23 end_arrow
+  "Ring",   // 24 hollow_circle
+  "Drag",   // 25 dragon
+  "Web",    // 26 globe_meridians
+  "Eggp",   // 27 eggplant
+  "Shld",   // 28 shield
+  "Gogl",   // 29 goggles
+  "Lzrd",   // 30 lizard
+  "Zany",   // 31 zany_face
+  "Roo",    // 32 kangaroo
+  "Fthr",   // 33 feather
+  "Sun",    // 34 bright
+  "Wave",   // 35 part_alt
+  "Boat",   // 36 motorboat
+  "Domi",   // 37 domino
+  "Dish",   // 38 satellite
+  "Pass",   // 39 customs
+  "Cowb",   // 40 cowboy
+  "Whl",    // 41 wheel
+  "Koal",   // 42 koala
+  "Knob",   // 43 control_knobs
+  "Pch",    // 44 peach
+  "Race",   // 45 racing_car
+  "Mous",   // 46 mouse
+  "Shrm",   // 47 mushroom
+  "Bio",    // 48 biohazard
+  "Pnda",   // 49 panda
+  "Bang",   // 50 anger
+  "DrgF",   // 51 dragon_face
+  "Pagr",   // 52 pager
+  "Bee",    // 53 bee
+  "Bulb",   // 54 bulb
+  "Cat",    // 55 cat
+  "Flur",   // 56 fleur
+  "Moon",   // 57 moon
+  "Cafe",   // 58 coffee
+  "Toth",   // 59 tooth
+  "Prtz",   // 60 pretzel
+  "Abac",   // 61 abacus
+  "Moai",   // 62 moai
+  "Hiii",   // 63 tipping
+  "Hedg",   // 64 hedgehog
+};
+
+struct EmojiPicker {
+  int cursor;
+  int scrollRow;
+  
+  EmojiPicker() : cursor(0), scrollRow(0) {}
+  
+  void reset() { cursor = 0; scrollRow = 0; }
+  
+  void ensureVisible() {
+    int cursorRow = cursor / EMOJI_PICKER_COLS;
+    if (cursorRow < scrollRow) scrollRow = cursorRow;
+    else if (cursorRow >= scrollRow + EMOJI_PICKER_VISIBLE_ROWS)
+      scrollRow = cursorRow - EMOJI_PICKER_VISIBLE_ROWS + 1;
+    int maxScroll = EMOJI_PICKER_TOTAL_ROWS - EMOJI_PICKER_VISIBLE_ROWS;
+    if (maxScroll < 0) maxScroll = 0;
+    if (scrollRow > maxScroll) scrollRow = maxScroll;
+    if (scrollRow < 0) scrollRow = 0;
+  }
+  
+  // Returns emoji escape byte, 0xFF for cancel, 0 for no action
+  uint8_t handleInput(char key) {
+    int row = cursor / EMOJI_PICKER_COLS;
+    int col = cursor % EMOJI_PICKER_COLS;
+    
+    switch (key) {
+      case 'w': case 'W': case 0xF2:
+        if (row > 0) cursor -= EMOJI_PICKER_COLS;
+        break;
+      case 's': case 'S': case 0xF1:
+        if (cursor + EMOJI_PICKER_COLS < EMOJI_COUNT)
+          cursor += EMOJI_PICKER_COLS;
+        else if (row < EMOJI_PICKER_TOTAL_ROWS - 1)
+          cursor = EMOJI_COUNT - 1;
+        break;
+      case 'a': case 'A':
+        if (cursor > 0) cursor--;
+        break;
+      case 'd': case 'D':
+        if (cursor + 1 < EMOJI_COUNT) cursor++;
+        break;
+      case '\r':
+        ensureVisible();
+        return (uint8_t)(EMOJI_ESCAPE_START + cursor);
+      case '\b': case 'q': case 'Q': case KB_KEY_EMOJI:
+        return 0xFF;
+      default:
+        return 0;
+    }
+    ensureVisible();
+    return 0;
+  }
+  
+  void draw(DisplayDriver& display) {
+    display.setTextSize(1);
+    display.setCursor(0, 0);
+    display.setColor(DisplayDriver::GREEN);
+    display.print("Select Emoji");
+    
+    display.setColor(DisplayDriver::LIGHT);
+    display.drawRect(0, 11, display.width(), 1);
+    
+    display.setTextSize(0);
+    
+    int startY = 14;
+    int scrollBarW = 4;
+    int gridW = display.width() - scrollBarW - 1;
+    int cellW = gridW / EMOJI_PICKER_COLS;
+    int footerHeight = 14;
+    int gridH = display.height() - startY - footerHeight;
+    int cellH = gridH / EMOJI_PICKER_VISIBLE_ROWS;
+    
+    for (int vr = 0; vr < EMOJI_PICKER_VISIBLE_ROWS; vr++) {
+      int absRow = scrollRow + vr;
+      if (absRow >= EMOJI_PICKER_TOTAL_ROWS) break;
+      
+      for (int col = 0; col < EMOJI_PICKER_COLS; col++) {
+        int idx = absRow * EMOJI_PICKER_COLS + col;
+        if (idx >= EMOJI_COUNT) break;
+        
+        int cx = col * cellW;
+        int cy = startY + vr * cellH;
+        
+        if (idx == cursor) {
+          display.setColor(DisplayDriver::LIGHT);
+          display.drawRect(cx, cy, cellW, cellH);
+          display.drawRect(cx + 1, cy + 1, cellW - 2, cellH - 2);
+        }
+        
+        display.setColor(DisplayDriver::LIGHT);
+        const uint8_t* sprite = (const uint8_t*)pgm_read_ptr(&EMOJI_SPRITES_LG[idx]);
+        if (sprite) {
+          int spriteX = cx + (cellW - EMOJI_LG_W) / 2;
+          int spriteY = cy + 1;
+          display.drawXbm(spriteX, spriteY, sprite, EMOJI_LG_W, EMOJI_LG_H);
+        }
+        
+        display.setColor(DisplayDriver::YELLOW);
+        uint16_t labelW = display.getTextWidth(EMOJI_LABELS[idx]);
+        int labelX = cx + (cellW - (int)labelW) / 2;
+        if (labelX < cx) labelX = cx;
+        display.setCursor(labelX, cy + 14);
+        display.print(EMOJI_LABELS[idx]);
+      }
+    }
+    
+    // Scroll bar
+    int sbX = display.width() - scrollBarW;
+    display.setColor(DisplayDriver::LIGHT);
+    display.drawRect(sbX, startY, scrollBarW, gridH);
+    
+    if (EMOJI_PICKER_TOTAL_ROWS > EMOJI_PICKER_VISIBLE_ROWS) {
+      int thumbH = (EMOJI_PICKER_VISIBLE_ROWS * gridH) / EMOJI_PICKER_TOTAL_ROWS;
+      if (thumbH < 4) thumbH = 4;
+      int maxScroll = EMOJI_PICKER_TOTAL_ROWS - EMOJI_PICKER_VISIBLE_ROWS;
+      int thumbY = startY + (scrollRow * (gridH - thumbH)) / maxScroll;
+      for (int y = thumbY + 1; y < thumbY + thumbH - 1; y++)
+        display.drawRect(sbX + 1, y, scrollBarW - 2, 1);
+    } else {
+      for (int y = startY + 1; y < startY + gridH - 1; y++)
+        display.drawRect(sbX + 1, y, scrollBarW - 2, 1);
+    }
+    
+    // Footer
+    display.setTextSize(1);
+    int footerY = display.height() - 12;
+    display.setColor(DisplayDriver::LIGHT);
+    display.drawRect(0, footerY - 2, display.width(), 1);
+    display.setCursor(0, footerY);
+    display.setColor(DisplayDriver::YELLOW);
+    display.print("WASD:Nav Ent:Pick");
+    const char* ct = "$:Back";
+    display.setCursor(display.width() - display.getTextWidth(ct) - 2, footerY);
+    display.print(ct);
+  }
+};

examples/companion_radio/ui-new/homeicons.h

@@ -0,0 +1,63 @@
+#pragma once
+// =============================================================================
+// HomeIcons — 12x12 icon sprites for T5S3 home screen tiles
+// MSB-first, 2 bytes per row (same format as emoji sprites)
+// =============================================================================
+
+#include <stdint.h>
+#ifdef ESP32
+#include <pgmspace.h>
+#endif
+
+#define HOME_ICON_W 12
+#define HOME_ICON_H 12
+
+// ✉️ Envelope (Messages)
+static const uint8_t icon_envelope[] PROGMEM = {
+  0xFF,0xF0, 0x80,0x10, 0xC0,0x30, 0xA0,0x50, 0x90,0x90, 0x89,0x10,
+  0x86,0x10, 0x80,0x10, 0x80,0x10, 0x80,0x10, 0x80,0x10, 0xFF,0xF0,
+};
+
+// 👥 People (Contacts)
+static const uint8_t icon_people[] PROGMEM = {
+  0x31,0x80, 0x7B,0xC0, 0x7B,0xC0, 0x31,0x80, 0x00,0x00, 0x7B,0xC0,
+  0xFD,0xE0, 0xFD,0xE0, 0x7B,0xC0, 0x00,0x00, 0x00,0x00, 0x00,0x00,
+};
+
+// 🎚 Sliders (Settings)
+static const uint8_t icon_gear[] PROGMEM = {
+  0x22,0x20, 0x22,0x20, 0x72,0x70, 0x72,0x70, 0x27,0x20, 0x27,0x20,
+  0x22,0x20, 0x72,0x20, 0x72,0x70, 0x22,0x70, 0x22,0x20, 0x22,0x20,
+};
+
+// 📖 Book (Reader)
+static const uint8_t icon_book[] PROGMEM = {
+  0x7F,0xC0, 0x41,0x40, 0x5D,0x40, 0x5D,0x40, 0x41,0x40, 0x5D,0x40,
+  0x5D,0x40, 0x41,0x40, 0x5D,0x40, 0x41,0x40, 0x7F,0xC0, 0x00,0x00,
+};
+
+// 🗒 Notepad (Notes)
+static const uint8_t icon_notepad[] PROGMEM = {
+  0x3F,0xC0, 0x20,0x40, 0x2F,0x40, 0x20,0x40, 0x2F,0x40, 0x20,0x40,
+  0x2F,0x40, 0x20,0x40, 0x2F,0x40, 0x20,0x40, 0x3F,0xC0, 0x00,0x00,
+};
+
+// 🔍 Magnifying glass (Discover)
+static const uint8_t icon_search[] PROGMEM = {
+  0x3C,0x00, 0x42,0x00, 0x81,0x00, 0x81,0x00, 0x81,0x00, 0x42,0x00,
+  0x3C,0x00, 0x03,0x00, 0x01,0x80, 0x00,0xC0, 0x00,0x40, 0x00,0x00,
+};
+
+// ⏰ Alarm Clock (AlarmScreen) — 12x12 home tile icon
+static const uint8_t icon_alarm[] PROGMEM = {
+  0x40,0x40, 0x9E,0x20, 0x20,0x80, 0x44,0x40, 0x44,0x40, 0x46,0x40,
+  0x40,0x40, 0x20,0x80, 0x1F,0x00, 0x00,0x00, 0x20,0x40, 0x40,0x20,
+};
+
+// 🔔 Bell — 7x8 status bar indicator (alarm enabled)
+// MSB-first, 1 byte per row
+#define BELL_ICON_W 7
+#define BELL_ICON_H 8
+static const uint8_t icon_bell_small[] PROGMEM = {
+  0x10, 0x38, 0x7C, 0x7C, 0x7C, 0xFE, 0x00, 0x10,
+};

examples/companion_radio/ui-new/virtualkeyboard.h

@@ -0,0 +1,365 @@
+#pragma once
+// =============================================================================
+// VirtualKeyboard — On-screen QWERTY keyboard for T5S3 (touch-only devices)
+//
+// Renders in virtual coordinate space (128×128). Touch hit testing converts
+// physical GT911 coords (960×540) to virtual coords.
+//
+// Usage:
+//   keyboard.open("To: General", "", 137);  // label, initial text, max len
+//   keyboard.render(display);                // in render loop
+//   keyboard.handleTap(vx, vy);              // on touch tap (virtual coords)
+//   if (keyboard.status() == VKB_SUBMITTED) { ... keyboard.getText() ... }
+// =============================================================================
+
+#if defined(LilyGo_T5S3_EPaper_Pro)
+#ifndef VIRTUAL_KEYBOARD_H
+#define VIRTUAL_KEYBOARD_H
+
+#include <Arduino.h>
+#include <helpers/ui/DisplayDriver.h>
+
+enum VKBStatus { VKB_EDITING, VKB_SUBMITTED, VKB_CANCELLED };
+
+// What the keyboard is being used for (dispatch on submit)
+enum VKBPurpose {
+  VKB_CHANNEL_MSG,    // Send to channel
+  VKB_DM,             // Direct message to contact
+  VKB_ADMIN_PASSWORD, // Repeater admin login
+  VKB_ADMIN_CLI,      // Repeater admin CLI command
+  VKB_NOTES,          // Insert text into notes
+  VKB_SETTINGS_NAME,  // Edit node name
+  VKB_SETTINGS_TEXT,  // Generic settings text edit (channel name, freq, APN)
+  VKB_WIFI_PASSWORD,  // WiFi password entry (settings screen)
+#ifdef MECK_WEB_READER
+  VKB_WEB_URL,        // Web reader URL entry
+  VKB_WEB_SEARCH,     // Web reader DuckDuckGo search query
+  VKB_WEB_WIFI_PASS,  // Web reader WiFi password
+  VKB_WEB_LINK,       // Web reader link number entry
+#endif
+  VKB_TEXT_PAGE,       // Text reader: go to page number
+};
+
+class VirtualKeyboard {
+public:
+  static const int MAX_TEXT = 140;
+
+  VirtualKeyboard() : _status(VKB_CANCELLED), _purpose(VKB_CHANNEL_MSG),
+                      _contextIdx(0), _textLen(0), _shifted(false), _symbols(false) {
+    _text[0] = '\0';
+    _label[0] = '\0';
+  }
+
+  void open(VKBPurpose purpose, const char* label, const char* initial, int maxLen, int contextIdx = 0) {
+    _purpose = purpose;
+    _contextIdx = contextIdx;
+    _status = VKB_EDITING;
+    _shifted = false;
+    _symbols = false;
+    _maxLen = (maxLen > 0 && maxLen < MAX_TEXT) ? maxLen : MAX_TEXT;
+
+    strncpy(_label, label, sizeof(_label) - 1);
+    _label[sizeof(_label) - 1] = '\0';
+
+    if (initial && initial[0]) {
+      strncpy(_text, initial, _maxLen);
+      _text[_maxLen] = '\0';
+      _textLen = strlen(_text);
+    } else {
+      _text[0] = '\0';
+      _textLen = 0;
+    }
+  }
+
+  VKBStatus status() const { return _status; }
+  VKBPurpose purpose() const { return _purpose; }
+  int contextIdx() const { return _contextIdx; }
+  const char* getText() const { return _text; }
+  int getTextLen() const { return _textLen; }
+  bool isActive() const { return _status == VKB_EDITING; }
+
+  // --- Render keyboard + input field ---
+  void render(DisplayDriver& display) {
+    // Header label (To: channel, DM: name, etc.)
+    display.setTextSize(0);
+    display.setColor(DisplayDriver::GREEN);
+    display.setCursor(2, 0);
+    display.print(_label);
+
+    // Input text field
+    display.setColor(DisplayDriver::LIGHT);
+    display.drawRect(0, 10, 128, 18);  // Border
+
+    display.setCursor(2, 12);
+    display.setColor(DisplayDriver::LIGHT);
+
+    // Show text with cursor
+    char dispBuf[MAX_TEXT + 2];
+    snprintf(dispBuf, sizeof(dispBuf), "%s_", _text);
+    display.print(dispBuf);
+
+    // Character count
+    {
+      char countBuf[12];
+      snprintf(countBuf, sizeof(countBuf), "%d/%d", _textLen, _maxLen);
+      int cw = display.getTextWidth(countBuf);
+      display.setCursor(128 - cw - 2, 0);
+      display.setColor(DisplayDriver::LIGHT);
+      display.print(countBuf);
+    }
+
+    // Separator
+    display.drawRect(0, 30, 128, 1);
+
+    // --- Draw keyboard rows ---
+    const char* const* layout = getLayout();
+
+    for (int row = 0; row < 3; row++) {
+      int numKeys = strlen(layout[row]);
+      int rowY = KEY_START_Y + row * (KEY_H + KEY_GAP);
+
+      // Calculate key width and starting X for this row
+      int totalW = numKeys * KEY_W + (numKeys - 1) * KEY_GAP;
+      int startX = (128 - totalW) / 2;
+
+      for (int k = 0; k < numKeys; k++) {
+        int kx = startX + k * (KEY_W + KEY_GAP);
+        char ch = layout[row][k];
+
+        // Draw key background (inverted for special keys)
+        bool special = (ch == '<' || ch == '^' || ch == '~' || ch == '>' || ch == '\x01');
+        if (special) {
+          display.setColor(DisplayDriver::LIGHT);
+          display.fillRect(kx, rowY + 1, KEY_W, KEY_H - 1);
+          display.setColor(DisplayDriver::DARK);
+        } else {
+          display.setColor(DisplayDriver::LIGHT);
+          display.drawRect(kx, rowY + 1, KEY_W, KEY_H - 1);
+        }
+
+        // Draw key label
+        char keyLabel[2] = { ch, '\0' };
+        // Remap special chars to display labels
+        if (ch == '<') keyLabel[0] = '<';   // Backspace
+        if (ch == '^') keyLabel[0] = '^';   // Shift
+        if (ch == '>') keyLabel[0] = '>';   // Enter
+
+        if (ch == '~') {
+          // Space key — don't draw individual label
+        } else if (ch == '\x01') {
+          // Symbol toggle in row — show "ab" hint
+          int lx = kx + KEY_W / 2 - display.getTextWidth("ab") / 2;
+          display.setCursor(lx, rowY + 2);
+          display.print("ab");
+        } else {
+          int lx = kx + KEY_W / 2 - display.getTextWidth(keyLabel) / 2;
+          display.setCursor(lx, rowY + 2);
+          display.print(keyLabel);
+        }
+
+        // Restore color
+        display.setColor(DisplayDriver::LIGHT);
+      }
+    }
+
+    // Draw row 4 with variable-width keys
+    int r4y = KEY_START_Y + 3 * (KEY_H + KEY_GAP);
+    drawRow4(display, r4y);
+
+    // Shift/symbol indicator
+    display.setTextSize(0);
+    display.setColor(DisplayDriver::GREEN);
+    if (_shifted) {
+      display.setCursor(2, 126);
+      display.print("SHIFT");
+    } else if (_symbols) {
+      display.setCursor(2, 126);
+      display.print("123");
+    }
+  }
+
+  // --- Handle touch tap (virtual coordinates) ---
+  // Returns true if the tap was consumed
+  bool handleTap(int vx, int vy) {
+    if (_status != VKB_EDITING) return false;
+
+    // Check keyboard rows 0-2
+    const char* const* layout = getLayout();
+
+    for (int row = 0; row < 3; row++) {
+      int numKeys = strlen(layout[row]);
+      int rowY = KEY_START_Y + row * (KEY_H + KEY_GAP);
+      if (vy < rowY || vy >= rowY + KEY_H) continue;
+
+      int totalW = numKeys * KEY_W + (numKeys - 1) * KEY_GAP;
+      int startX = (128 - totalW) / 2;
+
+      for (int k = 0; k < numKeys; k++) {
+        int kx = startX + k * (KEY_W + KEY_GAP);
+        if (vx >= kx && vx < kx + KEY_W) {
+          char ch = layout[row][k];
+          processKey(ch);
+          return true;
+        }
+      }
+      return true;  // Tap was in row area but between keys — consume
+    }
+
+    // Check row 4 (variable width keys)
+    int r4y = KEY_START_Y + 3 * (KEY_H + KEY_GAP);
+    if (vy >= r4y && vy < r4y + KEY_H) {
+      return handleRow4Tap(vx);
+    }
+
+    return false;
+  }
+
+  // Swipe up on keyboard = cancel
+  void cancel() { _status = VKB_CANCELLED; }
+
+  // --- Feed a raw ASCII character from an external physical keyboard ---
+  // Maps standard ASCII control chars to internal VKB actions.
+  // Returns true if the character was consumed.
+#ifdef MECK_CARDKB
+  bool feedChar(char c) {
+    if (_status != VKB_EDITING) return false;
+    switch (c) {
+      case '\r':   processKey('>');  return true;  // Enter → submit
+      case '\b':   processKey('<');  return true;  // Backspace
+      case 0x7F:   processKey('<');  return true;  // Delete → backspace
+      case 0x1B:   _status = VKB_CANCELLED; return true;  // ESC → cancel
+      case ' ':    processKey('~');  return true;  // Space
+      default:
+        // Printable ASCII → insert directly
+        if (c >= 0x20 && c <= 0x7E) {
+          if (_textLen < _maxLen) {
+            _text[_textLen++] = c;
+            _text[_textLen] = '\0';
+          }
+          return true;
+        }
+        return false;  // Non-printable / nav keys — not consumed
+    }
+  }
+#endif
+
+private:
+  VKBStatus _status;
+  VKBPurpose _purpose;
+  int _contextIdx;
+  char _text[MAX_TEXT + 1];
+  int _textLen;
+  int _maxLen;
+  char _label[40];
+  bool _shifted;
+  bool _symbols;
+
+  // Layout constants (virtual coords)
+  static const int KEY_W = 11;
+  static const int KEY_H = 19;
+  static const int KEY_GAP = 1;
+  static const int KEY_START_Y = 34;
+
+  // Key layouts — rows 0-2 as char arrays
+  // Special: ^ = shift, < = backspace, # = symbols, > = enter, ~ = space
+  const char* const* getLayout() const {
+    static const char* const lower[3] = { "qwertyuiop", "asdfghjkl", "^zxcvbnm<" };
+    static const char* const upper[3] = { "QWERTYUIOP", "ASDFGHJKL", "^ZXCVBNM<" };
+    static const char* const syms[3]  = { "1234567890", "-/:;()@$&#", "\x01.,?!'\"_<" };
+    return _symbols ? syms : (_shifted ? upper : lower);
+  }
+
+  // Row 4: variable-width keys [#/ABC] [,] [SPACE] [.] [Enter]
+  // Defined by physical zones, not the char-array approach
+  struct R4Key { int x; int w; char ch; const char* label; };
+
+  void drawRow4(DisplayDriver& display, int y) {
+    // # or ABC toggle: x=4, w=20
+    // comma: x=26, w=11
+    // space: x=39, w=50
+    // period: x=91, w=11
+    // enter: x=104, w=20
+    const R4Key keys[] = {
+      { 4,  20, '\x01', _symbols ? "ABC" : "123" },
+      { 26, 11, ',', "," },
+      { 39, 50, '~', "space" },
+      { 91, 11, '.', "." },
+      { 104, 20, '>', "Send" }
+    };
+
+    for (int i = 0; i < 5; i++) {
+      bool special = (keys[i].ch == '\x01' || keys[i].ch == '>');
+      if (special) {
+        display.setColor(DisplayDriver::LIGHT);
+        display.fillRect(keys[i].x, y + 1, keys[i].w, KEY_H - 1);
+        display.setColor(DisplayDriver::DARK);
+      } else {
+        display.setColor(DisplayDriver::LIGHT);
+        display.drawRect(keys[i].x, y + 1, keys[i].w, KEY_H - 1);
+      }
+
+      // Center label in key
+      display.setTextSize(0);
+      int lw = display.getTextWidth(keys[i].label);
+      int lx = keys[i].x + (keys[i].w - lw) / 2;
+      display.setCursor(lx, y + 2);
+      display.print(keys[i].label);
+      display.setColor(DisplayDriver::LIGHT);
+    }
+  }
+
+  bool handleRow4Tap(int vx) {
+    const R4Key keys[] = {
+      { 4,  20, '\x01', nullptr },
+      { 26, 11, ',', nullptr },
+      { 39, 50, '~', nullptr },
+      { 91, 11, '.', nullptr },
+      { 104, 20, '>', nullptr }
+    };
+    for (int i = 0; i < 5; i++) {
+      if (vx >= keys[i].x && vx < keys[i].x + keys[i].w) {
+        processKey(keys[i].ch);
+        return true;
+      }
+    }
+    return true;  // Consume tap in row area
+  }
+
+  void processKey(char ch) {
+    if (ch == '^') {
+      // Shift toggle
+      _shifted = !_shifted;
+      _symbols = false;
+    } else if (ch == '\x01') {
+      // Symbol/letter toggle
+      _symbols = !_symbols;
+      _shifted = false;
+    } else if (ch == '<') {
+      // Backspace
+      if (_textLen > 0) {
+        _textLen--;
+        _text[_textLen] = '\0';
+      }
+    } else if (ch == '>') {
+      // Enter/Send
+      _status = VKB_SUBMITTED;
+    } else if (ch == '~') {
+      // Space
+      if (_textLen < _maxLen) {
+        _text[_textLen++] = ' ';
+        _text[_textLen] = '\0';
+      }
+    } else {
+      // Regular character
+      if (_textLen < _maxLen) {
+        _text[_textLen++] = ch;
+        _text[_textLen] = '\0';
+        // Auto-unshift after typing one character
+        if (_shifted) _shifted = false;
+      }
+    }
+  }
+};
+
+#endif // VIRTUAL_KEYBOARD_H
+#endif // LilyGo_T5S3_EPaper_Pro

examples/companion_radio/ui-new/webreaderdeps.cpp

@@ -0,0 +1,16 @@
+// WebReaderDeps.cpp
+// -----------------------------------------------------------------------
+// PlatformIO library dependency finder (LDF) hint file.
+//
+// The web reader's WiFi/HTTP includes live in WebReaderScreen.h (header-only),
+// but PlatformIO's LDF can't always trace framework library dependencies
+// through conditional #include chains in headers. This .cpp file exposes
+// the includes at the top level where the scanner reliably finds them.
+//
+// No actual code here — just #include directives for the dependency finder.
+// -----------------------------------------------------------------------
+#ifdef MECK_WEB_READER
+  #include <WiFi.h>
+  #include <HTTPClient.h>
+  #include <WiFiClientSecure.h>
+#endif

merge_firmware.py

@@ -0,0 +1,159 @@
+"""
+PlatformIO post-build script: merge bootloader + partitions + firmware + SPIFFS
+into a single flashable binary.
+
+Includes a pre-formatted empty SPIFFS image so first-boot doesn't need to
+format the partition (which takes 1-2 minutes on 16MB flash).
+
+Output: .pio/build/<env>/firmware_merged.bin
+Flash:  esptool.py --chip esp32s3 write_flash 0x0 firmware_merged.bin
+
+Place this file in the project root alongside platformio.ini.
+Add to each environment (or the base section):
+  extra_scripts = post:merge_firmware.py
+"""
+
+Import("env")
+
+def find_spiffs_partition(partitions_bin):
+    """Parse compiled partitions.bin to find SPIFFS partition offset and size.
+    
+    ESP32 partition entry format (32 bytes each):
+      0xAA50 magic, type, subtype, offset(u32le), size(u32le), label(16), flags(u32le)
+    SPIFFS: type=0x01(data), subtype=0x82(spiffs)
+    """
+    import struct
+
+    with open(partitions_bin, "rb") as f:
+        data = f.read()
+
+    for i in range(0, len(data) - 32, 32):
+        magic = struct.unpack_from("<H", data, i)[0]
+        if magic != 0xAA50:
+            continue
+        ptype = data[i + 2]
+        subtype = data[i + 3]
+        offset = struct.unpack_from("<I", data, i + 4)[0]
+        size = struct.unpack_from("<I", data, i + 8)[0]
+        label = data[i + 12:i + 28].split(b'\x00')[0].decode("ascii", errors="ignore")
+        if ptype == 0x01 and subtype == 0x82:  # data/spiffs
+            return offset, size, label
+    return None, None, None
+
+
+def build_spiffs_image(env, size):
+    """Generate an empty formatted SPIFFS image using mkspiffs."""
+    import subprocess, os, tempfile, glob
+
+    build_dir = env.subst("$BUILD_DIR")
+    spiffs_bin = os.path.join(build_dir, "spiffs_empty.bin")
+
+    # If already generated for this build, reuse it
+    if os.path.isfile(spiffs_bin) and os.path.getsize(spiffs_bin) == size:
+        return spiffs_bin
+
+    # Find mkspiffs in PlatformIO packages
+    pio_home = os.path.expanduser("~/.platformio")
+    mkspiffs_paths = glob.glob(os.path.join(pio_home, "packages", "tool-mkspiffs*", "mkspiffs*"))
+    if not mkspiffs_paths:
+        # Also check platform-specific tool paths
+        mkspiffs_paths = glob.glob(os.path.join(pio_home, "packages", "tool-mklittlefs*", "mkspiffs*"))
+    
+    mkspiffs = None
+    for p in mkspiffs_paths:
+        if os.path.isfile(p) and os.access(p, os.X_OK):
+            mkspiffs = p
+            break
+
+    if not mkspiffs:
+        print("[merge] WARNING: mkspiffs not found, skipping SPIFFS image")
+        return None
+
+    # Create empty data directory for mkspiffs
+    data_dir = os.path.join(build_dir, "_empty_spiffs_data")
+    os.makedirs(data_dir, exist_ok=True)
+
+    # SPIFFS block/page sizes — ESP32 Arduino defaults
+    block_size = 4096
+    page_size = 256
+
+    cmd = [
+        mkspiffs,
+        "-c", data_dir,
+        "-b", str(block_size),
+        "-p", str(page_size),
+        "-s", str(size),
+        spiffs_bin,
+    ]
+
+    print(f"[merge] Generating empty SPIFFS image ({size // 1024} KB)...")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0 and os.path.isfile(spiffs_bin):
+        print(f"[merge] SPIFFS image OK: {spiffs_bin}")
+        return spiffs_bin
+    else:
+        print(f"[merge] mkspiffs failed: {result.stderr}")
+        return None
+
+
+def merge_bin(source, target, env):
+    import subprocess, os
+
+    build_dir = env.subst("$BUILD_DIR")
+    env_name = env.subst("$PIOENV")
+
+    bootloader = os.path.join(build_dir, "bootloader.bin")
+    partitions = os.path.join(build_dir, "partitions.bin")
+    firmware   = os.path.join(build_dir, "firmware.bin")
+    output     = os.path.join(build_dir, "firmware-merged.bin")
+
+    # Verify all inputs exist
+    for f in [bootloader, partitions, firmware]:
+        if not os.path.isfile(f):
+            print(f"[merge] WARNING: {f} not found, skipping merge")
+            return
+
+    # Read flash settings from board config
+    flash_mode = env.BoardConfig().get("build.flash_mode", "qio")
+    flash_freq = env.BoardConfig().get("build.f_flash", "80000000L").rstrip("L")
+    flash_size = env.BoardConfig().get("upload.flash_size", "16MB")
+    mcu = env.BoardConfig().get("build.mcu", "esp32s3")
+
+    # Convert numeric frequency to esptool format
+    freq_map = {"80000000": "80m", "40000000": "40m", "26000000": "26m", "20000000": "20m"}
+    flash_freq_str = freq_map.get(flash_freq, "80m")
+
+    cmd = [
+        env.subst("$PYTHONEXE"), "-m", "esptool",
+        "--chip", mcu,
+        "merge_bin",
+        "-o", output,
+        "--flash_mode", flash_mode,
+        "--flash_freq", flash_freq_str,
+        "--flash_size", flash_size,
+        "0x0",     bootloader,
+        "0x8000",  partitions,
+        "0x10000", firmware,
+    ]
+
+    # Try to include a pre-formatted SPIFFS image (eliminates 1-2 min first-boot format)
+    spiffs_offset, spiffs_size, spiffs_label = find_spiffs_partition(partitions)
+    if spiffs_offset and spiffs_size:
+        spiffs_bin = build_spiffs_image(env, spiffs_size)
+        if spiffs_bin:
+            cmd.extend([f"0x{spiffs_offset:x}", spiffs_bin])
+            print(f"[merge] Including SPIFFS image at 0x{spiffs_offset:x} ({spiffs_size // 1024} KB)")
+    else:
+        print("[merge] No SPIFFS partition found in partition table, skipping SPIFFS image")
+
+    print(f"\n[merge] Creating merged firmware for {env_name}...")
+    print(f"[merge] {' '.join(cmd[-8:])}")
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        size_kb = os.path.getsize(output) / 1024
+        print(f"[merge] OK: {output} ({size_kb:.0f} KB)")
+    else:
+        print(f"[merge] FAILED: {result.stderr}")
+
+env.AddPostAction("$BUILD_DIR/firmware.bin", merge_bin)

platformio.ini

@@ -27,6 +27,7 @@ build_flags = -w -DNDEBUG -DRADIOLIB_STATIC_ONLY=1 -DRADIOLIB_GODMODE=1
   -D LORA_FREQ=869.525
   -D LORA_BW=250
   -D LORA_SF=11
+  -D ENABLE_ADVERT_ON_BOOT=1
   -D ENABLE_PRIVATE_KEY_IMPORT=1   ; NOTE: comment these out for more secure firmware
   -D ENABLE_PRIVATE_KEY_EXPORT=1
   -D RADIOLIB_EXCLUDE_CC1101=1
@@ -55,9 +56,10 @@ build_src_filter =
 [esp32_base]
 extends = arduino_base
 platform = platformio/espressif32@6.11.0
-monitor_filters = esp32_exception_decoder
+monitor_filters = esp32_exception_decoder, clock_sync
 extra_scripts = merge-bin.py
 build_flags = ${arduino_base.build_flags}
+  -D ESP32_PLATFORM
 ;  -D ESP32_CPU_FREQ=80          ; change it to your need
 build_src_filter = ${arduino_base.build_src_filter}
 
@@ -67,10 +69,10 @@ lib_deps =
   file://arch/esp32/AsyncElegantOTA
 
 ; esp32c6 uses arduino framework 3.x
-; WARNING: experimental. pioarduino on esp32c6 needs work - it's not considered stable and has issues.
+; WARNING: experimental. May not work as stable as other platforms.
 [esp32c6_base]
 extends = esp32_base
-platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.12/platform-espressif32.zip
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.13-1/platform-espressif32.zip
 
 ; ----------------- NRF52 ---------------------
 
@@ -79,7 +81,7 @@ extends = arduino_base
 platform = nordicnrf52
 platform_packages =
   framework-arduinoadafruitnrf52 @ 1.10700.0
-extra_scripts = 
+extra_scripts =
   create-uf2.py
   arch/nrf52/extra_scripts/patch_bluefruit.py
 build_flags = ${arduino_base.build_flags}
@@ -147,4 +149,4 @@ lib_deps =
   adafruit/Adafruit_VL53L0X @ ^1.2.4
   stevemarple/MicroNMEA @ ^2.0.6
   adafruit/Adafruit BME680 Library @ ^2.0.4
-  adafruit/Adafruit BMP085 Library @ ^1.2.4
+  adafruit/Adafruit BMP085 Library @ ^1.2.4

src/Dispatcher.cpp

@@ -36,7 +36,7 @@ uint32_t Dispatcher::getCADFailRetryDelay() const {
   return 200;
 }
 uint32_t Dispatcher::getCADFailMaxDuration() const {
-  return 4000;   // 4 seconds
+  return 6000;   // 6 seconds
 }
 
 void Dispatcher::loop() {
@@ -52,10 +52,28 @@ void Dispatcher::loop() {
     prev_isrecv_mode = is_recv;
     if (!is_recv) {
       radio_nonrx_start = _ms->getMillis();
+    } else {
+      rx_stuck_count = 0;  // radio recovered — reset counter
     }
   }
   if (!is_recv && _ms->getMillis() - radio_nonrx_start > 8000) {   // radio has not been in Rx mode for 8 seconds!
     _err_flags |= ERR_EVENT_STARTRX_TIMEOUT;
+
+    rx_stuck_count++;
+    MESH_DEBUG_PRINTLN("%s Dispatcher::loop(): RX stuck (attempt %d), calling onRxStuck()", getLogDateTime(), rx_stuck_count);
+    onRxStuck();
+
+    uint8_t reboot_threshold = getRxFailRebootThreshold();
+    if (reboot_threshold > 0 && rx_stuck_count >= reboot_threshold) {
+      MESH_DEBUG_PRINTLN("%s Dispatcher::loop(): RX unrecoverable after %d attempts", getLogDateTime(), rx_stuck_count);
+      onRxUnrecoverable();
+    }
+
+    // Reset state to give recovery the full 8s window before re-triggering
+    radio_nonrx_start = _ms->getMillis();
+    prev_isrecv_mode = true;
+    cad_busy_start = 0;
+    next_agc_reset_time = futureMillis(getAGCResetInterval());
   }
 
   if (outbound) {  // waiting for outbound send to be completed
@@ -68,7 +86,7 @@ void Dispatcher::loop() {
       next_tx_time = futureMillis(t * getAirtimeBudgetFactor());
 
       _radio->onSendFinished();
-      logTx(outbound, 2 + outbound->path_len + outbound->payload_len);
+      logTx(outbound, 2 + outbound->getPathByteLen() + outbound->payload_len);
       if (outbound->isRouteFlood()) {
         n_sent_flood++;
       } else {
@@ -80,7 +98,7 @@ void Dispatcher::loop() {
       MESH_DEBUG_PRINTLN("%s Dispatcher::loop(): WARNING: outbound packed send timed out!", getLogDateTime());
 
       _radio->onSendFinished();
-      logTxFail(outbound, 2 + outbound->path_len + outbound->payload_len);
+      logTxFail(outbound, 2 + outbound->getPathByteLen() + outbound->payload_len);
 
       releasePacket(outbound);  // return to pool
       outbound = NULL;
@@ -141,12 +159,13 @@ void Dispatcher::checkRecv() {
         }
         pkt->path_len = raw[i++];
 
-        if (pkt->path_len > MAX_PATH_SIZE || i + pkt->path_len > len) {
+        uint16_t path_byte_len = pkt->getPathByteLen();
+        if (path_byte_len > MAX_PATH_SIZE || i + path_byte_len > len) {
           MESH_DEBUG_PRINTLN("%s Dispatcher::checkRecv(): partial or corrupt packet received, len=%d", getLogDateTime(), len);
           _mgr->free(pkt);  // put back into pool
           pkt = NULL;
         } else {
-          memcpy(pkt->path, &raw[i], pkt->path_len); i += pkt->path_len;
+          memcpy(pkt->path, &raw[i], path_byte_len); i += path_byte_len;
 
           pkt->payload_len = len - i;  // payload is remainder
           if (pkt->payload_len > sizeof(pkt->payload)) {
@@ -258,7 +277,8 @@ void Dispatcher::checkSend() {
       memcpy(&raw[len], &outbound->transport_codes[1], 2); len += 2;
     }
     raw[len++] = outbound->path_len;
-    memcpy(&raw[len], outbound->path, outbound->path_len); len += outbound->path_len;
+    uint16_t out_pbl = outbound->getPathByteLen();
+    memcpy(&raw[len], outbound->path, out_pbl); len += out_pbl;
 
     if (len + outbound->payload_len > MAX_TRANS_UNIT) {
       MESH_DEBUG_PRINTLN("%s Dispatcher::checkSend(): FATAL: Invalid packet queued... too long, len=%d", getLogDateTime(), len + outbound->payload_len);
@@ -271,14 +291,31 @@ void Dispatcher::checkSend() {
       outbound_start = _ms->getMillis();
       bool success = _radio->startSendRaw(raw, len);
       if (!success) {
-        MESH_DEBUG_PRINTLN("%s Dispatcher::loop(): ERROR: send start failed!", getLogDateTime());
+        MESH_DEBUG_PRINTLN("%s Dispatcher::checkSend(): ERROR: send start failed!", getLogDateTime());
 
         logTxFail(outbound, outbound->getRawLength());
-  
-        releasePacket(outbound);  // return to pool
+
+        // re-queue packet for retry instead of dropping it
+        int retry_delay = getCADFailRetryDelay();
+        unsigned long retry_time = futureMillis(retry_delay);
+        _mgr->queueOutbound(outbound, 0, retry_time);
         outbound = NULL;
+        next_tx_time = retry_time;
+
+        // count consecutive failures and reset radio if stuck
+        uint8_t threshold = getTxFailResetThreshold();
+        if (threshold > 0) {
+          tx_fail_count++;
+          if (tx_fail_count >= threshold) {
+            MESH_DEBUG_PRINTLN("%s Dispatcher::checkSend(): TX stuck (%d failures), resetting radio", getLogDateTime(), tx_fail_count);
+            onTxStuck();
+            tx_fail_count = 0;
+            next_tx_time = futureMillis(2000);
+          }
+        }
         return;
       }
+      tx_fail_count = 0;  // clear counter on successful TX start
       outbound_expiry = futureMillis(max_airtime);
 
     #if MESH_PACKET_LOGGING
@@ -312,8 +349,8 @@ void Dispatcher::releasePacket(Packet* packet) {
 }
 
 void Dispatcher::sendPacket(Packet* packet, uint8_t priority, uint32_t delay_millis) {
-  if (packet->path_len > MAX_PATH_SIZE || packet->payload_len > MAX_PACKET_PAYLOAD) {
-    MESH_DEBUG_PRINTLN("%s Dispatcher::sendPacket(): ERROR: invalid packet... path_len=%d, payload_len=%d", getLogDateTime(), (uint32_t) packet->path_len, (uint32_t) packet->payload_len);
+  if (packet->getPathByteLen() > MAX_PATH_SIZE || packet->payload_len > MAX_PACKET_PAYLOAD) {
+    MESH_DEBUG_PRINTLN("%s Dispatcher::sendPacket(): ERROR: invalid packet... path_len=%d (byte_len=%d), payload_len=%d", getLogDateTime(), (uint32_t) packet->path_len, (uint32_t) packet->getPathByteLen(), (uint32_t) packet->payload_len);
     _mgr->free(packet);
   } else {
     _mgr->queueOutbound(packet, priority, futureMillis(delay_millis));

src/Dispatcher.h

@@ -122,6 +122,8 @@ class Dispatcher {
   bool  prev_isrecv_mode;
   uint32_t n_sent_flood, n_sent_direct;
   uint32_t n_recv_flood, n_recv_direct;
+  uint8_t tx_fail_count;
+  uint8_t rx_stuck_count;
 
   void processRecvPacket(Packet* pkt);
 
@@ -142,6 +144,8 @@ protected:
     _err_flags = 0;
     radio_nonrx_start = 0;
     prev_isrecv_mode = true;
+    tx_fail_count = 0;
+    rx_stuck_count = 0;
   }
 
   virtual DispatcherAction onRecvPacket(Packet* pkt) = 0;
@@ -159,6 +163,11 @@ protected:
   virtual uint32_t getCADFailMaxDuration() const;
   virtual int getInterferenceThreshold() const { return 0; }    // disabled by default
   virtual int getAGCResetInterval() const { return 0; }    // disabled by default
+  virtual uint8_t getTxFailResetThreshold() const { return 3; }  // reset radio after N consecutive TX failures; 0=disabled
+  virtual void onTxStuck() { _radio->resetAGC(); }              // override to use doFullRadioReset() when available
+  virtual uint8_t getRxFailRebootThreshold() const { return 3; } // reboot after N failed RX recovery attempts; 0=disabled
+  virtual void onRxStuck() { _radio->resetAGC(); }              // called each time RX stuck for 8s; override for deeper reset
+  virtual void onRxUnrecoverable() { }                           // called when reboot threshold exceeded; override to call _board->reboot()
 
 public:
   void begin();
@@ -188,4 +197,4 @@ private:
   void checkSend();
 };
 
-}
+}

src/Identity.h

@@ -20,6 +20,10 @@ public:
     memcpy(dest, pub_key, PATH_HASH_SIZE);    // hash is just prefix of pub_key
     return PATH_HASH_SIZE;
   }
+  int copyHashTo(uint8_t* dest, uint8_t len) const {
+    memcpy(dest, pub_key, len);
+    return len;
+  }
   bool isHashMatch(const uint8_t* hash) const {
     return memcmp(hash, pub_key, PATH_HASH_SIZE) == 0;
   }
@@ -90,5 +94,4 @@ public:
   void readFrom(const uint8_t* src, size_t len);
 };
 
-}
-
+}

src/Mesh.cpp

@@ -15,7 +15,7 @@ bool Mesh::allowPacketForward(const mesh::Packet* packet) {
   return false;  // by default, Transport NOT enabled
 }
 uint32_t Mesh::getRetransmitDelay(const mesh::Packet* packet) { 
-  uint32_t t = (_radio->getEstAirtimeFor(packet->getRawLength()) * 52 / 50) / 2;
+  uint32_t t = (uint32_t)(_radio->getEstAirtimeFor(packet->getPathByteLen() + packet->payload_len + 2) * 0.5f);
 
   return _rng->nextInt(0, 5)*t;
 }
@@ -77,7 +77,9 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) {
     return ACTION_RELEASE;
   }
 
-  if (pkt->isRouteDirect() && pkt->path_len >= PATH_HASH_SIZE) {
+  if (pkt->isRouteDirect() && (pkt->path_len & 63) > 0) {
+    uint8_t dir_bph = (pkt->path_len >> 6) + 1;   // bytes per hop for this packet
+
     // check for 'early received' ACK
     if (pkt->getPayloadType() == PAYLOAD_TYPE_ACK) {
       int i = 0;
@@ -88,7 +90,7 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) {
       }
     }
 
-    if (self_id.isHashMatch(pkt->path) && allowPacketForward(pkt)) {
+    if (self_id.isHashMatch(pkt->path, dir_bph) && allowPacketForward(pkt)) {
       if (pkt->getPayloadType() == PAYLOAD_TYPE_MULTIPART) {
         return forwardMultipartDirect(pkt);
       } else if (pkt->getPayloadType() == PAYLOAD_TYPE_ACK) {
@@ -158,7 +160,7 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) {
               if (pkt->getPayloadType() == PAYLOAD_TYPE_PATH) {
                 int k = 0;
                 uint8_t path_len = data[k++];
-                uint8_t* path = &data[k]; k += path_len;
+                uint8_t* path = &data[k]; k += Packet::getPathByteLenFor(path_len);
                 uint8_t extra_type = data[k++] & 0x0F;   // upper 4 bits reserved for future use
                 uint8_t* extra = &data[k];
                 uint8_t extra_len = len - k;   // remainder of packet (may be padded with zeroes!)
@@ -293,8 +295,7 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) {
         if (type == PAYLOAD_TYPE_ACK && pkt->payload_len >= 5) {    // a multipart ACK
           Packet tmp;
           tmp.header = pkt->header;
-          tmp.path_len = pkt->path_len;
-          memcpy(tmp.path, pkt->path, pkt->path_len);
+          tmp.path_len = Packet::copyPath(tmp.path, pkt->path, pkt->path_len);
           tmp.payload_len = pkt->payload_len - 1;
           memcpy(tmp.payload, &pkt->payload[1], tmp.payload_len);
 
@@ -320,28 +321,34 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) {
 }
 
 void Mesh::removeSelfFromPath(Packet* pkt) {
-  // remove our hash from 'path'
-  pkt->path_len -= PATH_HASH_SIZE;
-#if 0
-  memcpy(pkt->path, &pkt->path[PATH_HASH_SIZE], pkt->path_len);
-#elif PATH_HASH_SIZE == 1
-  for (int k = 0; k < pkt->path_len; k++) {  // shuffle bytes by 1
-    pkt->path[k] = pkt->path[k + 1];
-  }
-#else
-  #error "need path remove impl"
-#endif
+  uint8_t bph = (pkt->path_len >> 6) + 1;   // bytes per hop
+  uint8_t hops = pkt->path_len & 63;
+  if (hops == 0) return;
+
+  uint16_t new_byte_len = (hops - 1) * bph;
+  // remove first bph bytes (our hash) from path, shift remainder
+  memmove(pkt->path, &pkt->path[bph], new_byte_len);
+  // decrement hop count, preserve mode bits
+  pkt->path_len = (pkt->path_len & 0xC0) | ((hops - 1) & 63);
 }
 
 DispatcherAction Mesh::routeRecvPacket(Packet* packet) {
   if (packet->isRouteFlood() && !packet->isMarkedDoNotRetransmit()
-    && packet->path_len + PATH_HASH_SIZE <= MAX_PATH_SIZE && allowPacketForward(packet)) {
-    // append this node's hash to 'path'
-    packet->path_len += self_id.copyHashTo(&packet->path[packet->path_len]);
+    && allowPacketForward(packet)) {
+    uint8_t bph = (packet->path_len >> 6) + 1;   // bytes per hop
+    uint8_t hops = packet->path_len & 63;
+    uint16_t byte_len = hops * bph;
 
-    uint32_t d = getRetransmitDelay(packet);
-    // as this propagates outwards, give it lower and lower priority
-    return ACTION_RETRANSMIT_DELAYED(packet->path_len, d);   // give priority to closer sources, than ones further away
+    if (byte_len + bph <= MAX_PATH_SIZE) {
+      // append this node's hash (bph bytes of pub_key) to path
+      memcpy(&packet->path[byte_len], self_id.pub_key, bph);
+      // increment hop count, preserve mode bits
+      packet->path_len = (packet->path_len & 0xC0) | ((hops + 1) & 63);
+
+      uint32_t d = getRetransmitDelay(packet);
+      // as this propagates outwards, give it lower and lower priority
+      return ACTION_RETRANSMIT_DELAYED(hops + 1, d);   // give priority to closer sources, than ones further away
+    }
   }
   return ACTION_RELEASE;
 }
@@ -353,8 +360,7 @@ DispatcherAction Mesh::forwardMultipartDirect(Packet* pkt) {
   if (type == PAYLOAD_TYPE_ACK && pkt->payload_len >= 5) {    // a multipart ACK
     Packet tmp;
     tmp.header = pkt->header;
-    tmp.path_len = pkt->path_len;
-    memcpy(tmp.path, pkt->path, pkt->path_len);
+    tmp.path_len = Packet::copyPath(tmp.path, pkt->path, pkt->path_len);
     tmp.payload_len = pkt->payload_len - 1;
     memcpy(tmp.payload, &pkt->payload[1], tmp.payload_len);
 
@@ -376,7 +382,7 @@ void Mesh::routeDirectRecvAcks(Packet* packet, uint32_t delay_millis) {
       delay_millis += getDirectRetransmitDelay(packet) + 300;
       auto a1 = createMultiAck(crc, extra);
       if (a1) {
-        memcpy(a1->path, packet->path, a1->path_len = packet->path_len);
+        a1->path_len = Packet::copyPath(a1->path, packet->path, packet->path_len);
         a1->header &= ~PH_ROUTE_MASK;
         a1->header |= ROUTE_TYPE_DIRECT;
         sendPacket(a1, 0, delay_millis);
@@ -386,7 +392,7 @@ void Mesh::routeDirectRecvAcks(Packet* packet, uint32_t delay_millis) {
 
     auto a2 = createAck(crc);
     if (a2) {
-      memcpy(a2->path, packet->path, a2->path_len = packet->path_len);
+      a2->path_len = Packet::copyPath(a2->path, packet->path, packet->path_len);
       a2->header &= ~PH_ROUTE_MASK;
       a2->header |= ROUTE_TYPE_DIRECT;
       sendPacket(a2, 0, delay_millis);
@@ -624,7 +630,7 @@ Packet* Mesh::createControlData(const uint8_t* data, size_t len) {
   return packet;
 }
 
-void Mesh::sendFlood(Packet* packet, uint32_t delay_millis) {
+void Mesh::sendFlood(Packet* packet, uint32_t delay_millis, uint8_t path_bytes_per_hop) {
   if (packet->getPayloadType() == PAYLOAD_TYPE_TRACE) {
     MESH_DEBUG_PRINTLN("%s Mesh::sendFlood(): TRACE type not suspported", getLogDateTime());
     return;
@@ -632,7 +638,9 @@ void Mesh::sendFlood(Packet* packet, uint32_t delay_millis) {
 
   packet->header &= ~PH_ROUTE_MASK;
   packet->header |= ROUTE_TYPE_FLOOD;
-  packet->path_len = 0;
+  // encode bytes-per-hop mode in upper 2 bits of path_len, 0 hops initially
+  uint8_t mode = (path_bytes_per_hop > 1) ? (path_bytes_per_hop - 1) : 0;
+  packet->path_len = (mode << 6);
 
   _tables->hasSeen(packet); // mark this packet as already sent in case it is rebroadcast back to us
 
@@ -647,7 +655,7 @@ void Mesh::sendFlood(Packet* packet, uint32_t delay_millis) {
   sendPacket(packet, pri, delay_millis);
 }
 
-void Mesh::sendFlood(Packet* packet, uint16_t* transport_codes, uint32_t delay_millis) {
+void Mesh::sendFlood(Packet* packet, uint16_t* transport_codes, uint32_t delay_millis, uint8_t path_bytes_per_hop) {
   if (packet->getPayloadType() == PAYLOAD_TYPE_TRACE) {
     MESH_DEBUG_PRINTLN("%s Mesh::sendFlood(): TRACE type not suspported", getLogDateTime());
     return;
@@ -657,7 +665,9 @@ void Mesh::sendFlood(Packet* packet, uint16_t* transport_codes, uint32_t delay_m
   packet->header |= ROUTE_TYPE_TRANSPORT_FLOOD;
   packet->transport_codes[0] = transport_codes[0];
   packet->transport_codes[1] = transport_codes[1];
-  packet->path_len = 0;
+  // encode bytes-per-hop mode in upper 2 bits of path_len, 0 hops initially
+  uint8_t mode = (path_bytes_per_hop > 1) ? (path_bytes_per_hop - 1) : 0;
+  packet->path_len = (mode << 6);
 
   _tables->hasSeen(packet); // mark this packet as already sent in case it is rebroadcast back to us
 
@@ -685,7 +695,7 @@ void Mesh::sendDirect(Packet* packet, const uint8_t* path, uint8_t path_len, uin
     packet->path_len = 0;
     pri = 5;   // maybe make this configurable
   } else {
-    memcpy(packet->path, path, packet->path_len = path_len);
+    packet->path_len = Packet::copyPath(packet->path, path, path_len);
     if (packet->getPayloadType() == PAYLOAD_TYPE_PATH) {
       pri = 1;   // slightly less priority
     } else {

src/Mesh.h

@@ -195,14 +195,16 @@ public:
 
   /**
    * \brief  send a locally-generated Packet with flood routing
+   * \param path_bytes_per_hop  number of bytes per path hop (1=legacy, 2, or 3)
   */
-  void sendFlood(Packet* packet, uint32_t delay_millis=0);
+  void sendFlood(Packet* packet, uint32_t delay_millis=0, uint8_t path_bytes_per_hop=1);
 
   /**
    * \brief  send a locally-generated Packet with flood routing
    * \param transport_codes   array of 2 codes to attach to packet
+   * \param path_bytes_per_hop  number of bytes per path hop (1=legacy, 2, or 3)
   */
-  void sendFlood(Packet* packet, uint16_t* transport_codes, uint32_t delay_millis=0);
+  void sendFlood(Packet* packet, uint16_t* transport_codes, uint32_t delay_millis=0, uint8_t path_bytes_per_hop=1);
 
   /**
    * \brief  send a locally-generated Packet with Direct routing
@@ -222,4 +224,4 @@ public:
 
 };
 
-}
+}

src/Packet.cpp

@@ -11,7 +11,7 @@ Packet::Packet() {
 }
 
 int Packet::getRawLength() const {
-  return 2 + path_len + payload_len + (hasTransportCodes() ? 4 : 0);
+  return 2 + getPathByteLen() + payload_len + (hasTransportCodes() ? 4 : 0);
 }
 
 void Packet::calculatePacketHash(uint8_t* hash) const {
@@ -33,7 +33,8 @@ uint8_t Packet::writeTo(uint8_t dest[]) const {
     memcpy(&dest[i], &transport_codes[1], 2); i += 2;
   }
   dest[i++] = path_len;
-  memcpy(&dest[i], path, path_len); i += path_len;
+  uint16_t pbl = getPathByteLen();
+  memcpy(&dest[i], path, pbl); i += pbl;
   memcpy(&dest[i], payload, payload_len); i += payload_len;
   return i;
 }
@@ -48,8 +49,9 @@ bool Packet::readFrom(const uint8_t src[], uint8_t len) {
     transport_codes[0] = transport_codes[1] = 0;
   }
   path_len = src[i++];
-  if (path_len > sizeof(path)) return false;   // bad encoding
-  memcpy(path, &src[i], path_len); i += path_len;
+  uint16_t pbl = getPathByteLen();
+  if (pbl > sizeof(path)) return false;   // bad encoding
+  memcpy(path, &src[i], pbl); i += pbl;
   if (i >= len) return false;   // bad encoding
   payload_len = len - i;
   if (payload_len > sizeof(payload)) return false;  // bad encoding

src/Packet.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <MeshCore.h>
+#include <string.h>
 
 namespace mesh {
 
@@ -81,6 +82,43 @@ public:
 
   float getSNR() const { return ((float)_snr) / 4.0f; }
 
+  /**
+   * \returns  the actual byte length of path data.
+   *   path_len encodes: lower 6 bits = hop count, upper 2 bits = bytes-per-hop mode
+   *   mode 0 = 1 byte/hop (legacy), mode 1 = 2 bytes/hop, mode 2 = 3 bytes/hop
+   */
+  uint16_t getPathByteLen() const {
+    uint8_t hops = path_len & 63;
+    uint8_t bph = (path_len >> 6) + 1;
+    return hops * bph;
+  }
+
+  /** Static variant for computing byte length from any path_len value */
+  static uint16_t getPathByteLenFor(uint8_t path_len) {
+    return (path_len & 63) * ((path_len >> 6) + 1);
+  }
+
+  /** Validate that encoded path_len won't exceed buffer */
+  static bool isValidPathLen(uint8_t path_len) {
+    return getPathByteLenFor(path_len) <= MAX_PATH_SIZE;
+  }
+
+  /** Copy path bytes using encoded path_len; returns path_len unchanged */
+  static uint8_t copyPath(uint8_t* dest, const uint8_t* src, uint8_t path_len) {
+    uint16_t bl = getPathByteLenFor(path_len);
+    if (bl > MAX_PATH_SIZE) bl = MAX_PATH_SIZE;
+    memcpy(dest, src, bl);
+    return path_len;
+  }
+
+  /** Write path bytes to buffer; returns number of bytes written */
+  static uint8_t writePath(uint8_t* dest, const uint8_t* src, uint8_t path_len) {
+    uint16_t bl = getPathByteLenFor(path_len);
+    if (bl > MAX_PATH_SIZE) bl = MAX_PATH_SIZE;
+    memcpy(dest, src, bl);
+    return (uint8_t)bl;
+  }
+
   /**
    * \returns  the encoded/wire format length of this packet
    */
@@ -101,4 +139,4 @@ public:
   bool readFrom(const uint8_t src[], uint8_t len);
 };
 
-}
+}

src/helpers/BaseChatMesh.cpp

@@ -10,10 +10,10 @@
 #endif
 
 void BaseChatMesh::sendFloodScoped(const ContactInfo& recipient, mesh::Packet* pkt, uint32_t delay_millis) {
-  sendFlood(pkt, delay_millis);
+  sendFlood(pkt, delay_millis, getPathHashSize());
 }
 void BaseChatMesh::sendFloodScoped(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t delay_millis) {
-  sendFlood(pkt, delay_millis);
+  sendFlood(pkt, delay_millis, getPathHashSize());
 }
 
 mesh::Packet* BaseChatMesh::createSelfAdvert(const char* name) {
@@ -39,7 +39,7 @@ mesh::Packet* BaseChatMesh::createSelfAdvert(const char* name, double lat, doubl
 }
 
 void BaseChatMesh::sendAckTo(const ContactInfo& dest, uint32_t ack_hash) {
-  if (dest.out_path_len < 0) {
+  if (dest.out_path_len == OUT_PATH_UNKNOWN) {
     mesh::Packet* ack = createAck(ack_hash);
     if (ack) sendFloodScoped(dest, ack, TXT_ACK_DELAY);
   } else {
@@ -56,6 +56,14 @@ void BaseChatMesh::sendAckTo(const ContactInfo& dest, uint32_t ack_hash) {
 }
 
 void BaseChatMesh::bootstrapRTCfromContacts() {
+  // If the RTC already has a sane time (e.g. hardware RTC like PCF8563, or
+  // GPS-synced), don't overwrite it with a potentially stale contact lastmod.
+  // This bootstrap is only useful for boards with no hardware RTC at all.
+  uint32_t current = getRTCClock()->getCurrentTime();
+  if (current > 1704067200UL) {  // Jan 1 2024 — matches EPOCH_MIN_SANE
+    return;
+  }
+
   uint32_t latest = 0;
   for (int i = 0; i < num_contacts; i++) {
     if (contacts[i].lastmod > latest) {
@@ -92,7 +100,7 @@ ContactInfo* BaseChatMesh::allocateContactSlot() {
 void BaseChatMesh::populateContactFromAdvert(ContactInfo& ci, const mesh::Identity& id, const AdvertDataParser& parser, uint32_t timestamp) {
   memset(&ci, 0, sizeof(ci));
   ci.id = id;
-  ci.out_path_len = -1;  // initially out_path is unknown
+  ci.out_path_len = OUT_PATH_UNKNOWN;  // initially out_path is unknown
   StrHelper::strncpy(ci.name, parser.getName(), sizeof(ci.name));
   ci.type = parser.getType();
   if (parser.hasLatLon()) {
@@ -263,7 +271,7 @@ void BaseChatMesh::onPeerDataRecv(mesh::Packet* packet, uint8_t type, int sender
       } else {
         mesh::Packet* reply = createDatagram(PAYLOAD_TYPE_RESPONSE, from.id, secret, temp_buf, reply_len);
         if (reply) {
-          if (from.out_path_len >= 0) {  // we have an out_path, so send DIRECT
+          if (from.out_path_len != OUT_PATH_UNKNOWN) {  // we have an out_path, so send DIRECT
             sendDirect(reply, from.out_path, from.out_path_len, SERVER_RESPONSE_DELAY);
           } else {
             sendFloodScoped(from, reply, SERVER_RESPONSE_DELAY);
@@ -273,7 +281,7 @@ void BaseChatMesh::onPeerDataRecv(mesh::Packet* packet, uint8_t type, int sender
     }
   } else if (type == PAYLOAD_TYPE_RESPONSE && len > 0) {
     onContactResponse(from, data, len);
-    if (packet->isRouteFlood() && from.out_path_len >= 0) {
+    if (packet->isRouteFlood() && from.out_path_len != OUT_PATH_UNKNOWN) {
       // we have direct path, but other node is still sending flood response, so maybe they didn't receive reciprocal path properly(?)
       handleReturnPathRetry(from, packet->path, packet->path_len);
     }
@@ -295,7 +303,8 @@ bool BaseChatMesh::onPeerPathRecv(mesh::Packet* packet, int sender_idx, const ui
 bool BaseChatMesh::onContactPathRecv(ContactInfo& from, uint8_t* in_path, uint8_t in_path_len, uint8_t* out_path, uint8_t out_path_len, uint8_t extra_type, uint8_t* extra, uint8_t extra_len) {
   // NOTE: default impl, we just replace the current 'out_path' regardless, whenever sender sends us a new out_path.
   // FUTURE: could store multiple out_paths per contact, and try to find which is the 'best'(?)
-  memcpy(from.out_path, out_path, from.out_path_len = out_path_len);  // store a copy of path, for sendDirect()
+  from.out_path_len = out_path_len;
+  mesh::Packet::copyPath(from.out_path, out_path, out_path_len);  // store a copy of path, for sendDirect()
   from.lastmod = getRTCClock()->getCurrentTime();
 
   onContactPathUpdated(from);
@@ -317,7 +326,7 @@ void BaseChatMesh::onAckRecv(mesh::Packet* packet, uint32_t ack_crc) {
     txt_send_timeout = 0;   // matched one we're waiting for, cancel timeout timer
     packet->markDoNotRetransmit();   // ACK was for this node, so don't retransmit
 
-    if (packet->isRouteFlood() && from->out_path_len >= 0) {
+    if (packet->isRouteFlood() && from->out_path_len != OUT_PATH_UNKNOWN) {
       // we have direct path, but other node is still sending flood, so maybe they didn't receive reciprocal path properly(?)
       handleReturnPathRetry(*from, packet->path, packet->path_len);
     }
@@ -386,7 +395,7 @@ int  BaseChatMesh::sendMessage(const ContactInfo& recipient, uint32_t timestamp,
   uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
 
   int rc;
-  if (recipient.out_path_len < 0) {
+  if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
     sendFloodScoped(recipient, pkt);
     txt_send_timeout = futureMillis(est_timeout = calcFloodTimeoutMillisFor(t));
     rc = MSG_SEND_SENT_FLOOD;
@@ -412,7 +421,7 @@ int  BaseChatMesh::sendCommandData(const ContactInfo& recipient, uint32_t timest
 
   uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
   int rc;
-  if (recipient.out_path_len < 0) {
+  if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
     sendFloodScoped(recipient, pkt);
     txt_send_timeout = futureMillis(est_timeout = calcFloodTimeoutMillisFor(t));
     rc = MSG_SEND_SENT_FLOOD;
@@ -500,7 +509,7 @@ int BaseChatMesh::sendLogin(const ContactInfo& recipient, const char* password,
   }
   if (pkt) {
     uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
-    if (recipient.out_path_len < 0) {
+    if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
       sendFloodScoped(recipient, pkt);
       est_timeout = calcFloodTimeoutMillisFor(t);
       return MSG_SEND_SENT_FLOOD;
@@ -525,7 +534,7 @@ int BaseChatMesh::sendAnonReq(const ContactInfo& recipient, const uint8_t* data,
   }
   if (pkt) {
     uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
-    if (recipient.out_path_len < 0) {
+    if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
       sendFloodScoped(recipient, pkt);
       est_timeout = calcFloodTimeoutMillisFor(t);
       return MSG_SEND_SENT_FLOOD;
@@ -552,7 +561,7 @@ int  BaseChatMesh::sendRequest(const ContactInfo& recipient, const uint8_t* req_
   }
   if (pkt) {
     uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
-    if (recipient.out_path_len < 0) {
+    if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
       sendFloodScoped(recipient, pkt);
       est_timeout = calcFloodTimeoutMillisFor(t);
       return MSG_SEND_SENT_FLOOD;
@@ -579,7 +588,7 @@ int  BaseChatMesh::sendRequest(const ContactInfo& recipient, uint8_t req_type, u
   }
   if (pkt) {
     uint32_t t = _radio->getEstAirtimeFor(pkt->getRawLength());
-    if (recipient.out_path_len < 0) {
+    if (recipient.out_path_len == OUT_PATH_UNKNOWN) {
       sendFloodScoped(recipient, pkt);
       est_timeout = calcFloodTimeoutMillisFor(t);
       return MSG_SEND_SENT_FLOOD;
@@ -683,7 +692,7 @@ void BaseChatMesh::checkConnections() {
         MESH_DEBUG_PRINTLN("checkConnections(): Keep_alive contact not found!");
         continue;
       }
-      if (contact->out_path_len < 0) {
+      if (contact->out_path_len == OUT_PATH_UNKNOWN) {
         MESH_DEBUG_PRINTLN("checkConnections(): Keep_alive contact, no out_path!");
         continue;
       }
@@ -710,7 +719,7 @@ void BaseChatMesh::checkConnections() {
 }
 
 void BaseChatMesh::resetPathTo(ContactInfo& recipient) {
-  recipient.out_path_len = -1;
+  recipient.out_path_len = OUT_PATH_UNKNOWN;
 }
 
 static ContactInfo* table;  // pass via global :-(
@@ -875,4 +884,4 @@ void BaseChatMesh::loop() {
     releasePacket(_pendingLoopback);   // undo the obtainNewPacket()
     _pendingLoopback = NULL;
   }
-}
+}

src/helpers/BaseChatMesh.h

@@ -58,9 +58,9 @@ class BaseChatMesh : public mesh::Mesh {
 
   friend class ContactsIterator;
 
-  ContactInfo contacts[MAX_CONTACTS];
+  ContactInfo* contacts;
   int num_contacts;
-  int sort_array[MAX_CONTACTS];
+  int* sort_array;
   int matching_peer_indexes[MAX_SEARCH_RESULTS];
   unsigned long txt_send_timeout;
 #ifdef MAX_GROUP_CHANNELS
@@ -78,6 +78,8 @@ protected:
   BaseChatMesh(mesh::Radio& radio, mesh::MillisecondClock& ms, mesh::RNG& rng, mesh::RTCClock& rtc, mesh::PacketManager& mgr, mesh::MeshTables& tables)
       : mesh::Mesh(radio, ms, rng, rtc, mgr, tables)
   { 
+    contacts = NULL;
+    sort_array = NULL;
     num_contacts = 0;
   #ifdef MAX_GROUP_CHANNELS
     memset(channels, 0, sizeof(channels));
@@ -90,6 +92,19 @@ protected:
 
   void bootstrapRTCfromContacts();
   void resetContacts() { num_contacts = 0; }
+
+  // Must be called from begin() before loadContacts/bootstrapRTCfromContacts.
+  // Deferred from constructor because PSRAM is not available during global init.
+  void initContacts() {
+    if (contacts != NULL) return;  // already initialized
+  #if defined(ESP32) && defined(BOARD_HAS_PSRAM)
+    contacts = (ContactInfo*)ps_calloc(MAX_CONTACTS, sizeof(ContactInfo));
+    sort_array = (int*)ps_calloc(MAX_CONTACTS, sizeof(int));
+  #else
+    contacts = new ContactInfo[MAX_CONTACTS]();
+    sort_array = new int[MAX_CONTACTS]();
+  #endif
+  }
   void populateContactFromAdvert(ContactInfo& ci, const mesh::Identity& id, const AdvertDataParser& parser, uint32_t timestamp);
   ContactInfo* allocateContactSlot(); // helper to find slot for new contact
 
@@ -98,6 +113,7 @@ protected:
   virtual bool shouldAutoAddContactType(uint8_t type) const { return true; }
   virtual void onContactsFull() {};
   virtual bool shouldOverwriteWhenFull() const { return false; }
+  virtual uint8_t getAutoAddMaxHops() const { return 0; }  // 0 = no limit
   virtual void onContactOverwrite(const uint8_t* pub_key) {};
   virtual void onDiscoveredContact(ContactInfo& contact, bool is_new, uint8_t path_len, const uint8_t* path) = 0;
   virtual ContactInfo* processAck(const uint8_t *data) = 0;
@@ -114,6 +130,7 @@ protected:
   virtual void onContactResponse(const ContactInfo& contact, const uint8_t* data, uint8_t len) = 0;
   virtual void handleReturnPathRetry(const ContactInfo& contact, const uint8_t* path, uint8_t path_len);
 
+  virtual uint8_t getPathHashSize() const = 0;
   virtual void sendFloodScoped(const ContactInfo& recipient, mesh::Packet* pkt, uint32_t delay_millis=0);
   virtual void sendFloodScoped(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t delay_millis=0);
 
@@ -169,4 +186,4 @@ public:
   int findChannelIdx(const mesh::GroupChannel& ch);
 
   void loop();
-};
+};

src/helpers/ClientACL.cpp

@@ -114,7 +114,7 @@ ClientInfo* ClientACL::putClient(const mesh::Identity& id, uint8_t init_perms) {
   memset(c, 0, sizeof(*c));
   c->permissions = init_perms;
   c->id = id;
-  c->out_path_len = -1;  // initially out_path is unknown
+  c->out_path_len = OUT_PATH_UNKNOWN;  // initially out_path is unknown
   return c;
 }
 
@@ -140,4 +140,4 @@ bool ClientACL::applyPermissions(const mesh::LocalIdentity& self_id, const uint8
     self_id.calcSharedSecret(c->shared_secret, pubkey);
   }
   return true;
-}
+}

src/helpers/ClientACL.h

@@ -4,6 +4,10 @@
 #include <Mesh.h>
 #include <helpers/IdentityStore.h>
 
+#ifndef OUT_PATH_UNKNOWN
+  #define OUT_PATH_UNKNOWN  0xFF
+#endif
+
 #define PERM_ACL_ROLE_MASK     3   // lower 2 bits
 #define PERM_ACL_GUEST         0
 #define PERM_ACL_READ_ONLY     1
@@ -13,7 +17,7 @@
 struct ClientInfo {
   mesh::Identity id;
   uint8_t permissions;
-  int8_t out_path_len;
+  uint8_t out_path_len;   // OUT_PATH_UNKNOWN = no known path
   uint8_t out_path[MAX_PATH_SIZE];
   uint8_t shared_secret[PUB_KEY_SIZE];
   uint32_t last_timestamp;   // by THEIR clock  (transient)
@@ -55,4 +59,4 @@ public:
 
   int getNumClients() const { return num_clients; }
   ClientInfo* getClientByIdx(int idx) { return &clients[idx]; }
-};
+};

src/helpers/ContactInfo.h

@@ -3,12 +3,14 @@
 #include <Arduino.h>
 #include <Mesh.h>
 
+#define OUT_PATH_UNKNOWN  0xFF   // no known path — triggers flood routing
+
 struct ContactInfo {
   mesh::Identity id;
   char name[32];
   uint8_t type;   // on of ADV_TYPE_*
   uint8_t flags;
-  int8_t out_path_len;
+  uint8_t out_path_len;   // encoded: bits[7:6]=mode, bits[5:0]=hops. OUT_PATH_UNKNOWN=no path
   mutable bool shared_secret_valid; // flag to indicate if shared_secret has been calculated
   uint8_t out_path[MAX_PATH_SIZE];
   uint32_t last_advert_timestamp;   // by THEIR clock
@@ -26,4 +28,4 @@ struct ContactInfo {
 
 private:
   mutable uint8_t shared_secret[PUB_KEY_SIZE];
-};
+};

src/helpers/ESP32Board.h

@@ -10,6 +10,7 @@
 #include <Wire.h>
 #include "esp_wifi.h"
 #include "driver/rtc_io.h"
+#include "driver/gpio.h"
 
 class ESP32Board : public mesh::MainBoard {
 protected:
@@ -60,13 +61,20 @@ public:
 #if defined(CONFIG_IDF_TARGET_ESP32S3) && defined(P_LORA_DIO_1) // Supported ESP32 variants
     if (rtc_gpio_is_valid_gpio((gpio_num_t)P_LORA_DIO_1)) { // Only enter sleep mode if P_LORA_DIO_1 is RTC pin
       esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
-      esp_sleep_enable_ext1_wakeup((1L << P_LORA_DIO_1), ESP_EXT1_WAKEUP_ANY_HIGH); // To wake up when receiving a LoRa packet
+      esp_sleep_enable_ext1_wakeup((1ULL << P_LORA_DIO_1), ESP_EXT1_WAKEUP_ANY_HIGH); // Wake on LoRa packet
+
+      // T5S3: Also wake on boot button press (GPIO0, active LOW).
+      // gpio_wakeup uses level trigger — works for light sleep only.
+#if defined(LilyGo_T5S3_EPaper_Pro) && defined(PIN_USER_BTN)
+      gpio_wakeup_enable((gpio_num_t)PIN_USER_BTN, GPIO_INTR_LOW_LEVEL);
+      esp_sleep_enable_gpio_wakeup();
+#endif
 
       if (secs > 0) {
-        esp_sleep_enable_timer_wakeup(secs * 1000000); // To wake up every hour to do periodically jobs
+        esp_sleep_enable_timer_wakeup(secs * 1000000ULL); // Timer wake (microseconds)
       }
 
-      esp_light_sleep_start(); // CPU enters light sleep
+      esp_light_sleep_start(); // CPU halts here, resumes on wake
     }
 #endif
   }
@@ -154,4 +162,4 @@ public:
   }
 };
 
-#endif
+#endif

src/helpers/esp32/SerialBLEInterface.cpp

@@ -147,15 +147,21 @@ void SerialBLEInterface::enable() {
 }
 
 void SerialBLEInterface::disable() {
+  bool wasEnabled = _isEnabled;
   _isEnabled = false;
 
   BLE_DEBUG_PRINTLN("SerialBLEInterface::disable");
 
-  pServer->getAdvertising()->stop();
-  pServer->disconnect(last_conn_id);
-  pService->stop();
+  // Only try BLE operations if we were previously enabled
+  // (avoids accessing dead BLE objects after btStop/mem_release)
+  if (wasEnabled && pServer) {
+    pServer->getAdvertising()->stop();
+    pServer->disconnect(last_conn_id);
+    pService->stop();
+  }
   oldDeviceConnected = deviceConnected = false;
   adv_restart_time = 0;
+  clearBuffers();
 }
 
 size_t SerialBLEInterface::writeFrame(const uint8_t src[], size_t len) {
@@ -179,13 +185,15 @@ size_t SerialBLEInterface::writeFrame(const uint8_t src[], size_t len) {
   return 0;
 }
 
-#define  BLE_WRITE_MIN_INTERVAL   60
+#define  BLE_WRITE_MIN_INTERVAL   30
 
 bool SerialBLEInterface::isWriteBusy() const {
   return millis() < _last_write + BLE_WRITE_MIN_INTERVAL;   // still too soon to start another write?
 }
 
 size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
+  if (!_isEnabled) return 0;  // BLE disabled — skip all BLE operations
+
   if (send_queue_len > 0   // first, check send queue
     && millis() >= _last_write + BLE_WRITE_MIN_INTERVAL    // space the writes apart
   ) {
@@ -249,4 +257,4 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
 
 bool SerialBLEInterface::isConnected() const {
   return deviceConnected;  //pServer != NULL && pServer->getConnectedCount() > 0;
-}
+}

src/helpers/esp32/SerialBLEInterface.h

@@ -23,7 +23,7 @@ class SerialBLEInterface : public BaseSerialInterface, BLESecurityCallbacks, BLE
     uint8_t buf[MAX_FRAME_SIZE];
   };
 
-  #define FRAME_QUEUE_SIZE  4
+  #define FRAME_QUEUE_SIZE  8
   int recv_queue_len;
   Frame recv_queue[FRAME_QUEUE_SIZE];
   int send_queue_len;
@@ -88,4 +88,4 @@ public:
 #else
   #define BLE_DEBUG_PRINT(...) {}
   #define BLE_DEBUG_PRINTLN(...) {}
-#endif
+#endif

src/helpers/ui/FastEPDDisplay.cpp

@@ -0,0 +1,347 @@
+#include "FastEPDDisplay.h"
+#include "FastEPD.h"
+#include <string.h>
+
+// Fallback if FastEPD doesn't define these constants
+#ifndef BBEP_SUCCESS
+#define BBEP_SUCCESS 0
+#endif
+#ifndef CLEAR_FAST
+#define CLEAR_FAST 0
+#endif
+#ifndef CLEAR_SLOW
+#define CLEAR_SLOW 1
+#endif
+#ifndef BB_MODE_1BPP
+#define BB_MODE_1BPP 0
+#endif
+
+// FastEPD constants (defined in FastEPD.h)
+// BB_PANEL_LILYGO_T5PRO_V2 — board ID for V2 hardware
+// BB_MODE_1BPP — 1-bit per pixel mode
+// CLEAR_FAST, CLEAR_SLOW — full refresh modes
+
+// Periodic slow (deep) refresh to clear ghosting
+#define FULL_SLOW_PERIOD 1  // every frame — eliminates ghosting (increase to 2+ for less flashing)
+
+FastEPDDisplay::~FastEPDDisplay() {
+  delete _canvas;
+  delete _epd;
+}
+
+bool FastEPDDisplay::begin() {
+  if (_init) return true;
+
+  Serial.println("[FastEPD] Initializing T5S3 E-Paper Pro V2...");
+
+  // Create FastEPD instance and init hardware
+  _epd = new FASTEPD;
+  // Meshtastic-proven init for V2 hardware (pinned FastEPD fork commit)
+  Serial.println("[FastEPD] Using BB_PANEL_LILYGO_T5PRO_V2");
+  int rc = _epd->initPanel(BB_PANEL_LILYGO_T5PRO_V2, 28000000);
+  if (rc != BBEP_SUCCESS) {
+    Serial.printf("[FastEPD] initPanel FAILED: %d\n", rc);
+    delete _epd;
+    _epd = nullptr;
+    return false;
+  }
+  Serial.printf("[FastEPD] Panel initialized (rc=%d)\n", rc);
+
+  // Enable display via PCA9535 GPIO (required for V2 hardware)
+  // Pin 0 on PCA9535 = EP_OE (output enable for source driver)
+  _epd->ioPinMode(0, OUTPUT);
+  _epd->ioWrite(0, HIGH);
+  Serial.println("[FastEPD] PCA9535 EP_OE set HIGH");
+
+  // Set 1-bit per pixel mode
+  _epd->setMode(BB_MODE_1BPP);
+  Serial.println("[FastEPD] Mode set to 1BPP");
+
+  // Create Adafruit_GFX canvas for drawing (960×540, 1-bit)
+  // ~64KB, should auto-allocate in PSRAM on ESP32-S3 with PSRAM enabled
+  _canvas = new GFXcanvas1(EPD_WIDTH, EPD_HEIGHT);
+  if (!_canvas || !_canvas->getBuffer()) {
+    Serial.println("[FastEPD] Canvas allocation FAILED!");
+    return false;
+  }
+  Serial.printf("[FastEPD] Canvas allocated: %dx%d (%d bytes)\n",
+                EPD_WIDTH, EPD_HEIGHT, (EPD_WIDTH * EPD_HEIGHT) / 8);
+
+  // Initial clear — white screen
+  Serial.println("[FastEPD] Calling clearWhite()...");
+  _epd->clearWhite();
+  Serial.println("[FastEPD] Calling fullUpdate(true) for initial clear...");
+  _epd->fullUpdate(true);  // blocking initial clear
+  _epd->backupPlane();     // Save clean state for subsequent diffs
+  Serial.println("[FastEPD] Initial clear complete");
+
+  // Set canvas defaults
+  _canvas->fillScreen(1);  // White background (bit=1 → white in FastEPD)
+  _canvas->setTextColor(0);  // Black text (bit=0 → black in FastEPD)
+#ifdef MECK_SERIF_FONT
+  _canvas->setFont(&FreeSerif12pt7b);
+#else
+  _canvas->setFont(&FreeSans12pt7b);
+#endif
+  _canvas->setTextWrap(false);
+
+  _curr_color = GxEPD_BLACK;
+  _init = true;
+  _isOn = true;
+
+  Serial.println("[FastEPD] Display ready (960x540, 1BPP)");
+  return true;
+}
+
+void FastEPDDisplay::turnOn() {
+  if (!_init) begin();
+  _isOn = true;
+}
+
+void FastEPDDisplay::turnOff() {
+  _isOn = false;
+}
+
+void FastEPDDisplay::clear() {
+  if (!_canvas) return;
+  _canvas->fillScreen(1);  // White
+  _canvas->setTextColor(0);
+  _frameCRC.reset();
+}
+
+void FastEPDDisplay::startFrame(Color bkg) {
+  if (!_canvas) return;
+  _canvas->fillScreen(1);  // White background
+  _canvas->setTextColor(0);  // Black text
+  _curr_color = GxEPD_BLACK;
+  _frameCRC.reset();
+  _frameCRC.update<bool>(_darkMode);
+  _frameCRC.update<bool>(_portraitMode);
+}
+
+void FastEPDDisplay::setTextSize(int sz) {
+  if (!_canvas) return;
+  _frameCRC.update<int>(sz);
+
+  // Font mapping for 960×540 display at ~234 DPI
+  // Toggle between font families via -D MECK_SERIF_FONT build flag
+  switch(sz) {
+    case 0:  // Body text — reader content, settings rows, messages, footers
+#ifdef MECK_SERIF_FONT
+      _canvas->setFont(&FreeSerif12pt7b);
+#else
+      _canvas->setFont(&FreeSans12pt7b);
+#endif
+      _canvas->setTextSize(1);
+      break;
+    case 1:  // Headings — screen titles, channel names (bold, same height as body)
+      _canvas->setFont(&FreeSansBold12pt7b);
+      _canvas->setTextSize(1);
+      break;
+    case 2:  // Large bold — MSG count, tile letters
+      _canvas->setFont(&FreeSansBold18pt7b);
+      _canvas->setTextSize(1);
+      break;
+    case 3:  // Extra large — splash screen title
+      _canvas->setFont(&FreeSansBold24pt7b);
+      _canvas->setTextSize(1);
+      break;
+    case 5:  // Clock face — lock screen (FreeSansBold24pt scaled 5×)
+      _canvas->setFont(&FreeSansBold24pt7b);
+      _canvas->setTextSize(5);
+      break;
+    default:
+#ifdef MECK_SERIF_FONT
+      _canvas->setFont(&FreeSerif12pt7b);
+#else
+      _canvas->setFont(&FreeSans12pt7b);
+#endif
+      _canvas->setTextSize(1);
+      break;
+  }
+}
+
+void FastEPDDisplay::setColor(Color c) {
+  if (!_canvas) return;
+  _frameCRC.update<Color>(c);
+
+  // Colours are inverted for e-paper:
+  //   DARK  = background colour = WHITE on e-paper
+  //   LIGHT = foreground colour = BLACK on e-paper
+  if (c == DARK) {
+    _canvas->setTextColor(1);  // White (background)
+    _curr_color = GxEPD_WHITE;
+  } else {
+    _canvas->setTextColor(0);  // Black (foreground)
+    _curr_color = GxEPD_BLACK;
+  }
+}
+
+void FastEPDDisplay::setCursor(int x, int y) {
+  if (!_canvas) return;
+  _frameCRC.update<int>(x);
+  _frameCRC.update<int>(y);
+
+  // Scale virtual coordinates to physical, with baseline offset.
+  // The +5 pushes text baseline down so ascenders at y=0 are visible.
+  _canvas->setCursor(
+    (int)((x + offset_x) * scale_x),
+    (int)((y + offset_y + 5) * scale_y)
+  );
+}
+
+void FastEPDDisplay::print(const char* str) {
+  if (!_canvas || !str) return;
+  _frameCRC.update<char>(str, strlen(str));
+  _canvas->print(str);
+}
+
+void FastEPDDisplay::fillRect(int x, int y, int w, int h) {
+  if (!_canvas) return;
+  _frameCRC.update<int>(x);
+  _frameCRC.update<int>(y);
+  _frameCRC.update<int>(w);
+  _frameCRC.update<int>(h);
+
+  // Canvas uses 1-bit color: convert GxEPD color
+  uint16_t canvasColor = (_curr_color == GxEPD_BLACK) ? 0 : 1;
+  _canvas->fillRect(
+    (int)((x + offset_x) * scale_x),
+    (int)((y + offset_y) * scale_y),
+    (int)(w * scale_x),
+    (int)(h * scale_y),
+    canvasColor
+  );
+}
+
+void FastEPDDisplay::drawRect(int x, int y, int w, int h) {
+  if (!_canvas) return;
+  _frameCRC.update<int>(x);
+  _frameCRC.update<int>(y);
+  _frameCRC.update<int>(w);
+  _frameCRC.update<int>(h);
+
+  uint16_t canvasColor = (_curr_color == GxEPD_BLACK) ? 0 : 1;
+  _canvas->drawRect(
+    (int)((x + offset_x) * scale_x),
+    (int)((y + offset_y) * scale_y),
+    (int)(w * scale_x),
+    (int)(h * scale_y),
+    canvasColor
+  );
+}
+
+void FastEPDDisplay::drawXbm(int x, int y, const uint8_t* bits, int w, int h) {
+  if (!_canvas || !bits) return;
+  _frameCRC.update<int>(x);
+  _frameCRC.update<int>(y);
+  _frameCRC.update<int>(w);
+  _frameCRC.update<int>(h);
+  _frameCRC.update<uint8_t>(bits, (w * h + 7) / 8);
+
+  uint16_t canvasColor = (_curr_color == GxEPD_BLACK) ? 0 : 1;
+  uint16_t startX = (int)((x + offset_x) * scale_x);
+  uint16_t startY = (int)((y + offset_y) * scale_y);
+  uint16_t widthInBytes = (w + 7) / 8;
+
+  for (uint16_t by = 0; by < h; by++) {
+    int y1 = startY + (int)(by * scale_y);
+    int y2 = startY + (int)((by + 1) * scale_y);
+    int block_h = y2 - y1;
+
+    for (uint16_t bx = 0; bx < w; bx++) {
+      int x1 = startX + (int)(bx * scale_x);
+      int x2 = startX + (int)((bx + 1) * scale_x);
+      int block_w = x2 - x1;
+
+      uint16_t byteOffset = (by * widthInBytes) + (bx / 8);
+      uint8_t bitMask = 0x80 >> (bx & 7);
+      bool bitSet = pgm_read_byte(bits + byteOffset) & bitMask;
+
+      if (bitSet) {
+        _canvas->fillRect(x1, y1, block_w, block_h, canvasColor);
+      }
+    }
+  }
+}
+
+uint16_t FastEPDDisplay::getTextWidth(const char* str) {
+  if (!_canvas || !str) return 0;
+  int16_t x1, y1;
+  uint16_t w, h;
+  _canvas->getTextBounds(str, 0, 0, &x1, &y1, &w, &h);
+  return (uint16_t)ceil((w + 1) / scale_x);
+}
+
+void FastEPDDisplay::endFrame() {
+  if (!_epd || !_canvas) return;
+
+  uint32_t crc = _frameCRC.finalize();
+  if (crc == _lastCRC) {
+    return;  // Frame unchanged, skip display update
+  }
+  _lastCRC = crc;
+
+  // Copy GFXcanvas1 buffer to FastEPD's current buffer — direct copy.
+  // Both use same polarity: bit 1 = white, bit 0 = black.
+  uint8_t* src = _canvas->getBuffer();
+  uint8_t* dst = _epd->currentBuffer();
+  size_t bufSize = ((uint32_t)EPD_WIDTH * EPD_HEIGHT) / 8;
+
+  if (!src || !dst) return;
+
+  memcpy(dst, src, bufSize);
+
+  // Dark mode: invert every byte in the buffer (white↔black)
+  if (_darkMode) {
+    for (size_t i = 0; i < bufSize; i++) dst[i] = ~dst[i];
+  }
+
+  // Refresh strategy:
+  //   partialUpdate(true) — no flash, differential, keeps previous buffer
+  //   fullUpdate(false)   — brief flash, clears ghosting (CLEAR_FAST)
+  //   fullUpdate(true)    — full white flash, cleanest (boot only)
+  //
+  // Use partial for most frames. Periodic full refresh every N frames
+  // to clear accumulated ghosting artifacts.
+  _fullRefreshCount++;
+  if (_forcePartial) {
+    // VKB typing mode — no flash, fast differential update
+    _epd->partialUpdate(true);
+    _fullRefreshCount = 0;  // Reset so next non-partial frame does full refresh
+  } else if (_fullRefreshCount >= FULL_SLOW_PERIOD) {
+    _fullRefreshCount = 0;
+    _epd->fullUpdate(true);   // Full clean refresh — clears all ghosting
+  } else {
+    _epd->partialUpdate(true);  // No flash — differential
+  }
+  _epd->backupPlane();
+}
+
+void FastEPDDisplay::setDarkMode(bool dark) {
+  _darkMode = dark;
+  _lastCRC = 0;  // Force redraw
+  Serial.printf("[FastEPD] Dark mode: %s\n", dark ? "ON" : "OFF");
+}
+
+void FastEPDDisplay::setPortraitMode(bool portrait) {
+  if (_portraitMode == portrait) return;
+  _portraitMode = portrait;
+
+  if (!_canvas) return;
+
+  if (portrait) {
+    _canvas->setRotation(3);  // 270° CW — USB-C on right when held portrait
+    scale_x = (float)EPD_HEIGHT / 128.0f;  // 540 / 128 = 4.21875
+    scale_y = (float)EPD_WIDTH / 128.0f;   // 960 / 128 = 7.5
+    Serial.printf("[FastEPD] Portrait mode: ON (logical %dx%d, scale %.2f x %.2f)\n",
+                  EPD_HEIGHT, EPD_WIDTH, scale_x, scale_y);
+  } else {
+    _canvas->setRotation(0);  // Normal landscape
+    scale_x = (float)EPD_WIDTH / 128.0f;   // 960 / 128 = 7.5
+    scale_y = (float)EPD_HEIGHT / 128.0f;  // 540 / 128 = 4.21875
+    Serial.printf("[FastEPD] Portrait mode: OFF (logical %dx%d, scale %.2f x %.2f)\n",
+                  EPD_WIDTH, EPD_HEIGHT, scale_x, scale_y);
+  }
+  _lastCRC = 0;  // Force redraw
+}

src/helpers/ui/FastEPDDisplay.h

@@ -0,0 +1,136 @@
+#pragma once
+
+// =============================================================================
+// FastEPDDisplay — Parallel e-ink display driver for T5 S3 E-Paper Pro
+//
+// Architecture:
+//   - FastEPD handles hardware init, power management, and display refresh
+//   - Adafruit_GFX GFXcanvas1 handles all drawing/text rendering
+//   - On endFrame(), canvas buffer is copied to FastEPD and display is updated
+//
+// This avoids depending on FastEPD's drawing API — only uses its well-tested
+// hardware interface (initPanel, fullUpdate, partialUpdate, currentBuffer).
+// =============================================================================
+
+#include <Adafruit_GFX.h>
+#include "variant.h"  // EPD_WIDTH, EPD_HEIGHT (only compiled for T5S3 builds)
+#include <Fonts/FreeSans9pt7b.h>
+#include <Fonts/FreeSans12pt7b.h>
+#include <Fonts/FreeSans18pt7b.h>
+#include <Fonts/FreeSans24pt7b.h>
+#include <Fonts/FreeSansBold12pt7b.h>
+#include <Fonts/FreeSansBold18pt7b.h>
+#include <Fonts/FreeSansBold24pt7b.h>
+#include <Fonts/FreeSerif12pt7b.h>
+#include <Fonts/FreeSerif18pt7b.h>
+
+#include "DisplayDriver.h"
+
+// GxEPD2 color constant compatibility — MapScreen uses these directly
+#ifndef GxEPD_BLACK
+#define GxEPD_BLACK  0x0000
+#endif
+#ifndef GxEPD_WHITE
+#define GxEPD_WHITE  0xFFFF
+#endif
+
+// Forward declare FastEPD class (actual include in .cpp)
+class FASTEPD;
+
+// Inline CRC32 for frame change detection
+// (Copied from GxEPDDisplay.h — avoids CRC32/PNGdec name collision)
+class FrameCRC32 {
+  uint32_t _crc = 0xFFFFFFFF;
+public:
+  void reset() { _crc = 0xFFFFFFFF; }
+  template<typename T> void update(T val) {
+    const uint8_t* p = (const uint8_t*)&val;
+    for (size_t i = 0; i < sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  template<typename T> void update(const T* data, size_t len) {
+    const uint8_t* p = (const uint8_t*)data;
+    for (size_t i = 0; i < len * sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  uint32_t finalize() { return _crc ^ 0xFFFFFFFF; }
+};
+
+
+class FastEPDDisplay : public DisplayDriver {
+  FASTEPD* _epd;
+  GFXcanvas1* _canvas;       // Adafruit_GFX 1-bit drawing surface (960×540)
+  bool _init = false;
+  bool _isOn = false;
+  uint16_t _curr_color;      // GxEPD_BLACK or GxEPD_WHITE for canvas drawing
+  FrameCRC32 _frameCRC;
+  uint32_t _lastCRC = 0;
+  int _fullRefreshCount = 0;  // Track for periodic slow refresh
+  uint32_t _lastUpdateMs = 0; // Rate limiting — minimum interval between refreshes
+  bool _forcePartial = false; // When true, use partial updates (VKB typing)
+  bool _darkMode = false;     // Invert all pixels (black bg, white text)
+  bool _portraitMode = false; // Rotated 90° (540×960 logical)
+
+  // Virtual 128×128 → physical canvas mapping (runtime, changes with portrait)
+  float scale_x  = 7.5f;       // 960 / 128 (landscape default)
+  float scale_y  = 4.21875f;   // 540 / 128 (landscape default)
+  static constexpr float offset_x = 0.0f;
+  static constexpr float offset_y = 0.0f;
+
+public:
+  FastEPDDisplay() : DisplayDriver(128, 128), _epd(nullptr), _canvas(nullptr) {}
+  ~FastEPDDisplay();
+
+  bool begin();
+
+  bool isOn() override { return _isOn; }
+  void turnOn() override;
+  void turnOff() override;
+  void clear() override;
+  void startFrame(Color bkg = DARK) override;
+  void setTextSize(int sz) override;
+  void setColor(Color c) override;
+  void setCursor(int x, int y) override;
+  void print(const char* str) override;
+  void fillRect(int x, int y, int w, int h) override;
+  void drawRect(int x, int y, int w, int h) override;
+  void drawXbm(int x, int y, const uint8_t* bits, int w, int h) override;
+  uint16_t getTextWidth(const char* str) override;
+  void endFrame() override;
+
+  // --- Raw pixel access for MapScreen (bypasses scaling) ---
+  void drawPixelRaw(int16_t x, int16_t y, uint16_t color) {
+    if (_canvas) _canvas->drawPixel(x, y, color ? 1 : 0);
+  }
+  int16_t rawWidth()  { return EPD_WIDTH; }
+  int16_t rawHeight() { return EPD_HEIGHT; }
+
+  void drawTextRaw(int16_t x, int16_t y, const char* text, uint16_t color) {
+    if (!_canvas) return;
+    _canvas->setFont(NULL);
+    _canvas->setTextSize(3);  // 3× built-in 5×7 = 15×21, readable on 960×540
+    _canvas->setTextColor(color ? 1 : 0);
+    _canvas->setCursor(x, y);
+    _canvas->print(text);
+  }
+
+  void invalidateFrameCRC() { _lastCRC = 0; }
+
+  // Temporarily force partial (no-flash) updates — use during VKB typing
+  void setForcePartial(bool partial) { _forcePartial = partial; }
+  bool isForcePartial() const { return _forcePartial; }
+
+  // Dark mode — invert all pixels in endFrame (black bg, white text)
+  void setDarkMode(bool dark);
+  bool isDarkMode() const { return _darkMode; }
+
+  // Portrait mode — rotate canvas 90° (540×960 logical), swap scale factors
+  void setPortraitMode(bool portrait);
+  bool isPortraitMode() const { return _portraitMode; }
+};

src/helpers/ui/GxEPDDisplay.cpp

@@ -52,7 +52,7 @@ bool GxEPDDisplay::begin() {
 
 void GxEPDDisplay::turnOn() {
   if (!_init) begin();
-#if defined(DISP_BACKLIGHT) && !defined(BACKLIGHT_BTN)
+#if defined(DISP_BACKLIGHT) && !defined(BACKLIGHT_BTN) && !defined(LilyGo_TDeck_Pro)
   digitalWrite(DISP_BACKLIGHT, HIGH);
 #elif defined(EXP_PIN_BACKLIGHT) && !defined(BACKLIGHT_BTN)
   expander.digitalWrite(EXP_PIN_BACKLIGHT, HIGH);
@@ -61,51 +61,87 @@ void GxEPDDisplay::turnOn() {
 }
 
 void GxEPDDisplay::turnOff() {
-#if defined(DISP_BACKLIGHT) && !defined(BACKLIGHT_BTN)
+#if defined(DISP_BACKLIGHT) && !defined(BACKLIGHT_BTN) && !defined(LilyGo_TDeck_Pro)
+  // Only toggle backlight on boards that actually have one.
+  // T-Deck Pro defines DISP_BACKLIGHT (GPIO 45) but has no physical backlight —
+  // setting _isOn=false would stop the render loop, making the device appear frozen.
   digitalWrite(DISP_BACKLIGHT, LOW);
+  _isOn = false;
 #elif defined(EXP_PIN_BACKLIGHT) && !defined(BACKLIGHT_BTN)
   expander.digitalWrite(EXP_PIN_BACKLIGHT, LOW);
-#endif
   _isOn = false;
+#endif
+  // T-Deck Pro: _isOn stays true — e-ink has no backlight, render loop must keep running
 }
 
 void GxEPDDisplay::clear() {
-  display.fillScreen(GxEPD_WHITE);
-  display.setTextColor(GxEPD_BLACK);
+  if (_darkMode) {
+    display.fillScreen(GxEPD_BLACK);
+    display.setTextColor(GxEPD_WHITE);
+  } else {
+    display.fillScreen(GxEPD_WHITE);
+    display.setTextColor(GxEPD_BLACK);
+  }
   display_crc.reset();
 }
 
 void GxEPDDisplay::startFrame(Color bkg) {
-  display.fillScreen(GxEPD_WHITE);
-  display.setTextColor(_curr_color = GxEPD_BLACK);
+  if (_darkMode) {
+    display.fillScreen(GxEPD_BLACK);
+    display.setTextColor(_curr_color = GxEPD_WHITE);
+  } else {
+    display.fillScreen(GxEPD_WHITE);
+    display.setTextColor(_curr_color = GxEPD_BLACK);
+  }
   display_crc.reset();
 }
 
 void GxEPDDisplay::setTextSize(int sz) {
   display_crc.update<int>(sz);
   switch(sz) {
+    case 0:  // Tiny - built-in 6x8 pixel font
+      display.setFont(NULL);
+      display.setTextSize(1);
+      break;
     case 1:  // Small - use 9pt (was 9pt)
       display.setFont(&FreeSans9pt7b);
+      display.setTextSize(1);
       break;
     case 2:  // Medium Bold - use 9pt bold instead of 12pt
       display.setFont(&FreeSans9pt7b);
+      display.setTextSize(1);
       break;
     case 3:  // Large - use 12pt instead of 18pt
       display.setFont(&FreeSansBold12pt7b);
+      display.setTextSize(1);
+      break;
+    case 5:  // Extra Large - lock screen clock face
+      display.setFont(&FreeSansBold12pt7b);
+      display.setTextSize(2);  // GxEPD2 native 2× scaling on 12pt bold
       break;
     default:
       display.setFont(&FreeSans9pt7b);
+      display.setTextSize(1);
       break;
   }
 }
 
 void GxEPDDisplay::setColor(Color c) {
   display_crc.update<Color> (c);
-  // colours need to be inverted for epaper displays
-  if (c == DARK) {
-    display.setTextColor(_curr_color = GxEPD_WHITE);
+  if (_darkMode) {
+    // Dark mode: DARK = black (background), LIGHT/GREEN/YELLOW = white (foreground)
+    if (c == DARK) {
+      display.setTextColor(_curr_color = GxEPD_BLACK);
+    } else {
+      display.setTextColor(_curr_color = GxEPD_WHITE);
+    }
   } else {
-    display.setTextColor(_curr_color = GxEPD_BLACK);
+    // Normal e-paper: DARK = white (background), LIGHT/GREEN/YELLOW = black (foreground)
+    if (c == DARK) {
+      display.setTextColor(_curr_color = GxEPD_WHITE);
+    } else {
+      display.setTextColor(_curr_color = GxEPD_BLACK);
+    }
   }
 }
 

src/helpers/ui/GxEPDDisplay.h

@@ -1,5 +1,11 @@
 #pragma once
 
+// T5S3 E-Paper Pro uses parallel e-ink (FastEPD), not SPI (GxEPD2)
+#if defined(LilyGo_T5S3_EPaper_Pro)
+  #include "FastEPDDisplay.h"
+  using GxEPDDisplay = FastEPDDisplay;
+#else
+
 #include <SPI.h>
 #include <Wire.h>
 
@@ -12,7 +18,31 @@
 #include <Fonts/FreeSans9pt7b.h>
 #include <Fonts/FreeSansBold12pt7b.h>
 #include <Fonts/FreeSans18pt7b.h>
-#include <CRC32.h>
+
+// Inline CRC32 for frame change detection (replaces bakercp/CRC32
+// to avoid naming collision with PNGdec's bundled CRC32.h)
+class FrameCRC32 {
+  uint32_t _crc = 0xFFFFFFFF;
+public:
+  void reset() { _crc = 0xFFFFFFFF; }
+  template<typename T> void update(T val) {
+    const uint8_t* p = (const uint8_t*)&val;
+    for (size_t i = 0; i < sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  template<typename T> void update(const T* data, size_t len) {
+    const uint8_t* p = (const uint8_t*)data;
+    for (size_t i = 0; i < len * sizeof(T); i++) {
+      _crc ^= p[i];
+      for (int b = 0; b < 8; b++)
+        _crc = (_crc >> 1) ^ (0xEDB88320 & -(int32_t)(_crc & 1));
+    }
+  }
+  uint32_t finalize() { return _crc ^ 0xFFFFFFFF; }
+};
 
 #include "DisplayDriver.h"
 
@@ -33,8 +63,9 @@ class GxEPDDisplay : public DisplayDriver {
 #endif
   bool _init = false;
   bool _isOn = false;
+  bool _darkMode = false;
   uint16_t _curr_color;
-  CRC32 display_crc;
+  FrameCRC32 display_crc;
   int last_display_crc_value = 0;
 
 public:
@@ -49,6 +80,11 @@ public:
   bool isOn() override {return _isOn;};
   void turnOn() override;
   void turnOff() override;
+
+  // Dark mode — inverts background/foreground for e-ink
+  bool isDarkMode() const { return _darkMode; }
+  void setDarkMode(bool on) { _darkMode = on; }
+
   void clear() override;
   void startFrame(Color bkg = DARK) override;
   void setTextSize(int sz) override;
@@ -60,4 +96,26 @@ public:
   void drawXbm(int x, int y, const uint8_t* bits, int w, int h) override;
   uint16_t getTextWidth(const char* str) override;
   void endFrame() override;
+
+  // --- Raw pixel access for MapScreen (bypasses scaling) ---
+  void drawPixelRaw(int16_t x, int16_t y, uint16_t color) {
+    display.drawPixel(x, y, color);
+  }
+  int16_t rawWidth()  { return display.width(); }
+  int16_t rawHeight() { return display.height(); }
+
+  // Draw text at raw (unscaled) physical coordinates using built-in 5x7 font
+  void drawTextRaw(int16_t x, int16_t y, const char* text, uint16_t color) {
+    display.setFont(NULL);          // Built-in 5x7 font
+    display.setTextSize(1);
+    display.setTextColor(color);
+    display.setCursor(x, y);
+    display.print(text);
+  }
+
+  // Force endFrame() to push to display even if CRC unchanged
+  // (needed because drawPixelRaw bypasses CRC tracking)
+  void invalidateFrameCRC() { last_display_crc_value = 0; }
 };
+
+#endif // !LilyGo_T5S3_EPaper_Pro

variants/lilygo_t5s3_epaper_pro/CPUPowerManager.h

@@ -0,0 +1,113 @@
+#pragma once
+
+#include <Arduino.h>
+
+// CPU Frequency Scaling for ESP32-S3
+//
+// Typical current draw (CPU only, rough):
+//   240 MHz  ~70-80 mA
+//   160 MHz  ~50-60 mA
+//    80 MHz  ~30-40 mA
+//    40 MHz  ~15-20 mA  (low-power / lock screen mode)
+//
+// SPI peripherals and UART use their own clock dividers from the APB clock,
+// so LoRa, e-ink, and GPS serial all work fine at 80MHz and 40MHz.
+
+#ifdef ESP32
+
+#ifndef CPU_FREQ_IDLE
+#define CPU_FREQ_IDLE   80     // MHz — normal mesh listening
+#endif
+
+#ifndef CPU_FREQ_BOOST
+#define CPU_FREQ_BOOST  240    // MHz — heavy processing
+#endif
+
+#ifndef CPU_FREQ_LOW_POWER
+#define CPU_FREQ_LOW_POWER 80   // MHz — lock screen / idle standby (40 MHz breaks I2C)
+#endif
+
+#ifndef CPU_BOOST_TIMEOUT_MS
+#define CPU_BOOST_TIMEOUT_MS  10000  // 10 seconds
+#endif
+
+class CPUPowerManager {
+public:
+  CPUPowerManager() : _boosted(false), _lowPower(false), _boost_started(0) {}
+
+  void begin() {
+    setCpuFrequencyMhz(CPU_FREQ_IDLE);
+    _boosted = false;
+    _lowPower = false;
+    MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz", CPU_FREQ_IDLE);
+  }
+
+  void loop() {
+    if (_boosted && (millis() - _boost_started >= CPU_BOOST_TIMEOUT_MS)) {
+      // Return to low-power if locked, otherwise normal idle
+      if (_lowPower) {
+        setCpuFrequencyMhz(CPU_FREQ_LOW_POWER);
+        MESH_DEBUG_PRINTLN("CPU power: boost expired, returning to low-power %d MHz", CPU_FREQ_LOW_POWER);
+      } else {
+        setCpuFrequencyMhz(CPU_FREQ_IDLE);
+        MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz", CPU_FREQ_IDLE);
+      }
+      _boosted = false;
+    }
+  }
+
+  void setBoost() {
+    if (!_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_BOOST);
+      _boosted = true;
+      MESH_DEBUG_PRINTLN("CPU power: boosted to %d MHz", CPU_FREQ_BOOST);
+    }
+    _boost_started = millis();
+  }
+
+  void setIdle() {
+    if (_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_IDLE);
+      _boosted = false;
+      MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz", CPU_FREQ_IDLE);
+    }
+    if (_lowPower) {
+      _lowPower = false;
+    }
+  }
+
+  // Low-power mode — drops CPU to 40 MHz for lock screen standby.
+  // If currently boosted, the boost timeout will return to 40 MHz
+  // instead of 80 MHz.
+  void setLowPower() {
+    _lowPower = true;
+    if (!_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_LOW_POWER);
+      MESH_DEBUG_PRINTLN("CPU power: low-power at %d MHz", CPU_FREQ_LOW_POWER);
+    }
+    // If boosted, the loop() timeout will drop to low-power instead of idle
+  }
+
+  // Exit low-power mode — returns to normal idle (80 MHz).
+  // If currently boosted, the boost timeout will return to idle
+  // instead of low-power.
+  void clearLowPower() {
+    _lowPower = false;
+    if (!_boosted) {
+      setCpuFrequencyMhz(CPU_FREQ_IDLE);
+      MESH_DEBUG_PRINTLN("CPU power: idle at %d MHz (low-power cleared)", CPU_FREQ_IDLE);
+    }
+    // If boosted, the loop() timeout will drop to idle as normal
+  }
+
+  bool isBoosted() const { return _boosted; }
+  bool isLowPower() const { return _lowPower; }
+  uint32_t getFrequencyMHz() const { return getCpuFrequencyMhz(); }
+
+private:
+  bool _boosted;
+  bool _lowPower;
+  unsigned long _boost_started;
+};
+
+#endif // ESP32

variants/lilygo_t5s3_epaper_pro/Pcf85063clock.h

@@ -0,0 +1,209 @@
+#pragma once
+// =============================================================================
+// PCF85063Clock — PCF8563/BM8563 RTC driver for T5S3 E-Paper Pro
+//
+// Time registers at 0x02–0x08 (PCF8563 layout):
+//   0x02 Seconds, 0x03 Minutes, 0x04 Hours,
+//   0x05 Days, 0x06 Weekdays, 0x07 Months, 0x08 Years
+// =============================================================================
+
+#include <Arduino.h>
+#include <Wire.h>
+#include <MeshCore.h>
+
+#define PCF8563_ADDR        0x51
+#define PCF8563_REG_SECONDS 0x02
+
+// Reject timestamps outside 2024–2036 (blocks MeshCore contacts garbage)
+#define EPOCH_MIN_SANE  1704067200UL
+#define EPOCH_MAX_SANE  2082758400UL
+
+class PCF85063Clock : public mesh::RTCClock {
+public:
+  PCF85063Clock() : _wire(nullptr), _millis_offset(0),
+                    _has_hw_time(false), _time_set_this_session(false) {}
+
+  bool begin(TwoWire& wire) {
+    _wire = &wire;
+
+    _wire->beginTransmission(PCF8563_ADDR);
+    if (_wire->endTransmission() != 0) {
+      Serial.println("[RTC] PCF8563 not found");
+      return false;
+    }
+
+    // Repair any corrupted registers from prior wrong-offset writes
+    repairRegisters();
+
+    uint32_t t = readHardwareTime();
+    if (t > EPOCH_MIN_SANE && t < EPOCH_MAX_SANE) {
+      _has_hw_time = true;
+      _millis_offset = t - (millis() / 1000);
+      Serial.printf("[RTC] PCF8563 OK, time=%lu\n", t);
+    } else {
+      _has_hw_time = false;
+      Serial.printf("[RTC] PCF8563 no valid time (%lu), awaiting BLE sync\n", t);
+    }
+    return true;
+  }
+
+  uint32_t getCurrentTime() override {
+    if (_time_set_this_session) {
+      return _millis_offset + (millis() / 1000);
+    }
+    if (_has_hw_time && _wire) {
+      uint32_t t = readHardwareTime();
+      if (t > EPOCH_MIN_SANE && t < EPOCH_MAX_SANE) {
+        _millis_offset = t - (millis() / 1000);
+        return t;
+      }
+      _has_hw_time = false;
+    }
+    return _millis_offset + (millis() / 1000);
+  }
+
+  void setCurrentTime(uint32_t time) override {
+    if (time < EPOCH_MIN_SANE || time > EPOCH_MAX_SANE) {
+      Serial.printf("[RTC] setCurrentTime(%lu) REJECTED\n", time);
+      return;
+    }
+    _millis_offset = time - (millis() / 1000);
+    _time_set_this_session = true;
+    Serial.printf("[RTC] setCurrentTime(%lu) OK\n", time);
+    if (_wire) writeHardwareTime(time);
+  }
+
+private:
+  TwoWire*  _wire;
+  uint32_t  _millis_offset;
+  bool      _has_hw_time;
+  bool      _time_set_this_session;
+
+  // ---- Register helpers ----
+  void writeReg(uint8_t reg, uint8_t val) {
+    _wire->beginTransmission(PCF8563_ADDR);
+    _wire->write(reg);
+    _wire->write(val);
+    _wire->endTransmission();
+  }
+
+  uint8_t readReg(uint8_t reg) {
+    _wire->beginTransmission(PCF8563_ADDR);
+    _wire->write(reg);
+    if (_wire->endTransmission(false) != 0) return 0xFF;
+    if (_wire->requestFrom((uint8_t)PCF8563_ADDR, (uint8_t)1) != 1) return 0xFF;
+    return _wire->read();
+  }
+
+  // ---- Fix registers corrupted by prior PCF85063A-mode writes ----
+  void repairRegisters() {
+    uint8_t hours = readReg(0x04) & 0x3F;
+    if (bcd2dec(hours) > 23) {
+      Serial.printf("[RTC] Repairing hours (0x%02X→0x00)\n", hours);
+      writeReg(0x04, 0x00);
+    }
+    uint8_t days = readReg(0x05) & 0x3F;
+    if (bcd2dec(days) == 0 || bcd2dec(days) > 31) {
+      Serial.printf("[RTC] Repairing days (0x%02X→0x01)\n", days);
+      writeReg(0x05, 0x01);
+    }
+    uint8_t month = readReg(0x07) & 0x1F;
+    if (bcd2dec(month) == 0 || bcd2dec(month) > 12) {
+      Serial.printf("[RTC] Repairing month (0x%02X→0x01)\n", month);
+      writeReg(0x07, 0x01);
+    }
+  }
+
+  // ---- BCD ----
+  static uint8_t bcd2dec(uint8_t bcd) { return ((bcd >> 4) * 10) + (bcd & 0x0F); }
+  static uint8_t dec2bcd(uint8_t dec) { return ((dec / 10) << 4) | (dec % 10); }
+
+  // ---- Date helpers ----
+  static bool isLeap(int y) { return (y%4==0 && y%100!=0) || y%400==0; }
+  static int daysInMonth(int m, int y) {
+    static const uint8_t d[] = {31,28,31,30,31,30,31,31,30,31,30,31};
+    return (m==2 && isLeap(y)) ? 29 : d[m-1];
+  }
+
+  static uint32_t toEpoch(int yr, int mo, int dy, int h, int mi, int s) {
+    uint32_t days = 0;
+    for (int y = 1970; y < yr; y++) days += isLeap(y) ? 366 : 365;
+    for (int m = 1; m < mo; m++) days += daysInMonth(m, yr);
+    days += (dy - 1);
+    return days * 86400UL + h * 3600UL + mi * 60UL + s;
+  }
+
+  static void fromEpoch(uint32_t ep, int& yr, int& mo, int& dy, int& h, int& mi, int& s) {
+    s = ep % 60; ep /= 60;
+    mi = ep % 60; ep /= 60;
+    h  = ep % 24; ep /= 24;
+    yr = 1970;
+    while (true) { int d = isLeap(yr)?366:365; if (ep<(uint32_t)d) break; ep-=d; yr++; }
+    mo = 1;
+    while (true) { int d = daysInMonth(mo,yr); if (ep<(uint32_t)d) break; ep-=d; mo++; }
+    dy = ep + 1;
+  }
+
+  // ---- Read time (burst from 0x02) ----
+  uint32_t readHardwareTime() {
+    _wire->beginTransmission(PCF8563_ADDR);
+    _wire->write(PCF8563_REG_SECONDS);
+    if (_wire->endTransmission(false) != 0) return 0;
+    if (_wire->requestFrom((uint8_t)PCF8563_ADDR, (uint8_t)7) != 7) return 0;
+
+    uint8_t raw[7];
+    for (int i = 0; i < 7; i++) raw[i] = _wire->read();
+
+    if (raw[0] & 0x80) {
+      Serial.println("[RTC] OS flag set — clearing");
+      writeReg(PCF8563_REG_SECONDS, raw[0] & 0x7F);
+      return 0;
+    }
+
+    int second = bcd2dec(raw[0] & 0x7F);
+    int minute = bcd2dec(raw[1] & 0x7F);
+    int hour   = bcd2dec(raw[2] & 0x3F);
+    int day    = bcd2dec(raw[3] & 0x3F);
+    int month  = bcd2dec(raw[5] & 0x1F);
+    int year   = 2000 + bcd2dec(raw[6]);
+
+    if (month<1 || month>12 || day<1 || day>31 || hour>23 || minute>59 || second>59)
+      return 0;
+
+    return toEpoch(year, month, day, hour, minute, second);
+  }
+
+  // ---- Write time (burst to 0x02) ----
+  void writeHardwareTime(uint32_t epoch) {
+    int year, month, day, hour, minute, second;
+    fromEpoch(epoch, year, month, day, hour, minute, second);
+
+    static const int dow[] = {0,3,2,5,0,3,5,1,4,6,2,4};
+    int y = year; if (month < 3) y--;
+    int wday = (y + y/4 - y/100 + y/400 + dow[month-1] + day) % 7;
+    int yr = year - 2000;
+
+    // Stop clock
+    writeReg(0x00, 0x20);
+    delay(5);
+
+    // Burst write
+    _wire->beginTransmission(PCF8563_ADDR);
+    _wire->write(PCF8563_REG_SECONDS);
+    _wire->write(dec2bcd(second) & 0x7F);
+    _wire->write(dec2bcd(minute));
+    _wire->write(dec2bcd(hour));
+    _wire->write(dec2bcd(day));
+    _wire->write(dec2bcd(wday));
+    _wire->write(dec2bcd(month));
+    _wire->write(dec2bcd(yr));
+    _wire->endTransmission();
+    delay(5);
+
+    // Restart clock
+    writeReg(0x00, 0x00);
+
+    Serial.printf("[RTC] Wrote %04d-%02d-%02d %02d:%02d:%02d\n",
+                  year, month, day, hour, minute, second);
+  }
+};

variants/lilygo_t5s3_epaper_pro/T5S3Board.cpp

@@ -0,0 +1,461 @@
+#include <Arduino.h>
+#include "variant.h"
+#include "T5S3Board.h"
+#include <Mesh.h>  // For MESH_DEBUG_PRINTLN
+
+void T5S3Board::begin() {
+  MESH_DEBUG_PRINTLN("T5S3Board::begin() - starting");
+
+  // Initialize I2C with T5S3 V2 pins
+  // Note: No explicit peripheral power enable needed on T5S3
+  // (unlike T-Deck Pro's PIN_PERF_POWERON)
+  Wire.begin(I2C_SDA, I2C_SCL);
+  Wire.setClock(100000);  // 100kHz for reliable fuel gauge communication
+  MESH_DEBUG_PRINTLN("T5S3Board::begin() - I2C initialized (SDA=%d, SCL=%d)", I2C_SDA, I2C_SCL);
+
+  // Call parent class begin (handles CPU freq, etc.)
+  // Note: ESP32Board::begin() also calls Wire.begin() but with our
+  // PIN_BOARD_SDA/SCL defines it will use the same pins — harmless.
+  ESP32Board::begin();
+
+  // Configure backlight (off by default — save power)
+  #ifdef BOARD_BL_EN
+    pinMode(BOARD_BL_EN, OUTPUT);
+    digitalWrite(BOARD_BL_EN, LOW);
+    MESH_DEBUG_PRINTLN("T5S3Board::begin() - backlight pin configured (GPIO%d)", BOARD_BL_EN);
+  #endif
+
+  // Configure user button
+  pinMode(PIN_USER_BTN, INPUT);
+
+  // Configure LoRa SPI MISO pullup
+  pinMode(P_LORA_MISO, INPUT_PULLUP);
+
+  // Handle wake from deep sleep
+  esp_reset_reason_t reason = esp_reset_reason();
+  if (reason == ESP_RST_DEEPSLEEP) {
+    uint64_t wakeup_source = esp_sleep_get_ext1_wakeup_status();
+    if (wakeup_source & (1ULL << P_LORA_DIO_1)) {
+      startup_reason = BD_STARTUP_RX_PACKET;
+    }
+    rtc_gpio_hold_dis((gpio_num_t)P_LORA_NSS);
+    rtc_gpio_deinit((gpio_num_t)P_LORA_DIO_1);
+  }
+
+  // Test BQ27220 communication and configure design capacity
+  #if HAS_BQ27220
+    uint16_t voltage = getBattMilliVolts();
+    MESH_DEBUG_PRINTLN("T5S3Board::begin() - Battery voltage: %d mV", voltage);
+    configureFuelGauge();
+  #endif
+
+  // Early low-voltage protection
+  #if HAS_BQ27220 && defined(AUTO_SHUTDOWN_MILLIVOLTS)
+  {
+    uint16_t bootMv = getBattMilliVolts();
+    if (bootMv > 0 && bootMv < AUTO_SHUTDOWN_MILLIVOLTS) {
+      Serial.printf("CRITICAL: Boot voltage %dmV < %dmV — sleeping immediately\n",
+                    bootMv, AUTO_SHUTDOWN_MILLIVOLTS);
+      esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_ALL);
+      esp_sleep_enable_ext1_wakeup(1ULL << PIN_USER_BTN, ESP_EXT1_WAKEUP_ANY_HIGH);
+      esp_deep_sleep_start();
+    }
+  }
+  #endif
+
+  MESH_DEBUG_PRINTLN("T5S3Board::begin() - complete");
+}
+
+// ---- BQ27220 register helpers (static, file-local) ----
+
+#if HAS_BQ27220
+static uint16_t bq27220_read16(uint8_t reg) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(reg);
+  if (Wire.endTransmission(false) != 0) return 0;
+  if (Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)2) != 2) return 0;
+  uint16_t val = Wire.read();
+  val |= (Wire.read() << 8);
+  return val;
+}
+
+static uint8_t bq27220_read8(uint8_t reg) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(reg);
+  if (Wire.endTransmission(false) != 0) return 0;
+  if (Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)1) != 1) return 0;
+  return Wire.read();
+}
+
+static bool bq27220_writeControl(uint16_t subcmd) {
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x00);
+  Wire.write(subcmd & 0xFF);
+  Wire.write((subcmd >> 8) & 0xFF);
+  return Wire.endTransmission() == 0;
+}
+#endif
+
+// ---- BQ27220 public interface ----
+
+uint16_t T5S3Board::getBattMilliVolts() {
+  #if HAS_BQ27220
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(BQ27220_REG_VOLTAGE);
+    if (Wire.endTransmission(false) != 0) return 0;
+    uint8_t count = Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)2);
+    if (count != 2) return 0;
+    uint16_t voltage = Wire.read();
+    voltage |= (Wire.read() << 8);
+    return voltage;
+  #else
+    return 0;
+  #endif
+}
+
+uint8_t T5S3Board::getBatteryPercent() {
+  #if HAS_BQ27220
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(BQ27220_REG_SOC);
+    if (Wire.endTransmission(false) != 0) return 0;
+    uint8_t count = Wire.requestFrom((uint8_t)BQ27220_I2C_ADDR, (uint8_t)2);
+    if (count != 2) return 0;
+    uint16_t soc = Wire.read();
+    soc |= (Wire.read() << 8);
+    return (uint8_t)min(soc, (uint16_t)100);
+  #else
+    return 0;
+  #endif
+}
+
+int16_t T5S3Board::getAvgCurrent() {
+  #if HAS_BQ27220
+    return (int16_t)bq27220_read16(BQ27220_REG_AVG_CURRENT);
+  #else
+    return 0;
+  #endif
+}
+
+int16_t T5S3Board::getAvgPower() {
+  #if HAS_BQ27220
+    return (int16_t)bq27220_read16(BQ27220_REG_AVG_POWER);
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t T5S3Board::getTimeToEmpty() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_TIME_TO_EMPTY);
+  #else
+    return 0xFFFF;
+  #endif
+}
+
+uint16_t T5S3Board::getRemainingCapacity() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_REMAIN_CAP);
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t T5S3Board::getFullChargeCapacity() {
+  #if HAS_BQ27220
+    uint16_t fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+    if (fcc > BQ27220_DESIGN_CAPACITY_MAH) fcc = BQ27220_DESIGN_CAPACITY_MAH;
+    return fcc;
+  #else
+    return 0;
+  #endif
+}
+
+uint16_t T5S3Board::getDesignCapacity() {
+  #if HAS_BQ27220
+    return bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  #else
+    return 0;
+  #endif
+}
+
+int16_t T5S3Board::getBattTemperature() {
+  #if HAS_BQ27220
+    uint16_t raw = bq27220_read16(BQ27220_REG_TEMPERATURE);
+    return (int16_t)(raw - 2731);  // 0.1°K to 0.1°C
+  #else
+    return 0;
+  #endif
+}
+
+// ---- BQ27220 Design Capacity configuration ----
+// The BQ27220 ships with a 3000 mAh default. T5S3 uses a 1500 mAh cell.
+// This function checks on boot and writes the correct value via the
+// MAC Data Memory interface if needed. The value persists in battery-backed
+// RAM, so this typically only writes once (or after a full battery disconnect).
+//
+// When DC and DE are already correct but FCC is stuck (common after initial
+// flash), the root cause is Qmax Cell 0 (0x9106) and stored FCC (0x929D)
+// retaining factory 3000 mAh defaults. This function detects and fixes all
+// three layers: DC/DE, Qmax, and stored FCC.
+
+bool T5S3Board::configureFuelGauge(uint16_t designCapacity_mAh) {
+#if HAS_BQ27220
+  uint16_t currentDC = bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  Serial.printf("BQ27220: Design Capacity = %d mAh (target %d)\n", currentDC, designCapacity_mAh);
+
+  if (currentDC == designCapacity_mAh) {
+    // Design Capacity correct, but check if Full Charge Capacity is sane.
+    uint16_t fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+    Serial.printf("BQ27220: Design Capacity already correct, FCC=%d mAh\n", fcc);
+    if (fcc >= designCapacity_mAh * 3 / 2) {
+      // FCC is >=150% of design — stale from factory defaults (typically 3000 mAh).
+      uint16_t designEnergy = (uint16_t)((uint32_t)designCapacity_mAh * 37 / 10);
+      Serial.printf("BQ27220: FCC %d >> DC %d, checking Design Energy (target %d mWh)\n",
+                    fcc, designCapacity_mAh, designEnergy);
+
+      // Unseal to read data memory and issue RESET
+      bq27220_writeControl(0x0414); delay(2);
+      bq27220_writeControl(0x3672); delay(2);
+      // Full Access
+      bq27220_writeControl(0xFFFF); delay(2);
+      bq27220_writeControl(0xFFFF); delay(2);
+
+      // Enter CFG_UPDATE to access data memory
+      bq27220_writeControl(0x0090);
+      bool ready = false;
+      for (int i = 0; i < 50; i++) {
+        delay(20);
+        uint16_t opSt = bq27220_read16(BQ27220_REG_OP_STATUS);
+        if (opSt & 0x0400) { ready = true; break; }
+      }
+      if (ready) {
+        // Read Design Energy at data memory address 0x92A1
+        Wire.beginTransmission(BQ27220_I2C_ADDR);
+        Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+        Wire.endTransmission();
+        delay(10);
+        uint8_t oldMSB = bq27220_read8(0x40);
+        uint8_t oldLSB = bq27220_read8(0x41);
+        uint16_t currentDE = (oldMSB << 8) | oldLSB;
+
+        if (currentDE != designEnergy) {
+          // Design Energy actually needs updating — write it
+          uint8_t oldChk = bq27220_read8(0x60);
+          uint8_t dLen   = bq27220_read8(0x61);
+          uint8_t newMSB = (designEnergy >> 8) & 0xFF;
+          uint8_t newLSB = designEnergy & 0xFF;
+          uint8_t temp = (255 - oldChk - oldMSB - oldLSB);
+          uint8_t newChk = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+          Serial.printf("BQ27220: DE old=%d new=%d mWh, writing\n", currentDE, designEnergy);
+
+          Wire.beginTransmission(BQ27220_I2C_ADDR);
+          Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+          Wire.write(newMSB); Wire.write(newLSB);
+          Wire.endTransmission();
+          delay(5);
+          Wire.beginTransmission(BQ27220_I2C_ADDR);
+          Wire.write(0x60); Wire.write(newChk); Wire.write(dLen);
+          Wire.endTransmission();
+          delay(10);
+
+          // Exit with reinit since we actually changed data
+          bq27220_writeControl(0x0091);  // EXIT_CFG_UPDATE_REINIT
+          delay(200);
+          Serial.println("BQ27220: Design Energy written, exited CFG_UPDATE");
+        } else {
+          // DC and DE are both correct, but FCC is stuck.
+          // Root cause: Qmax Cell 0 (0x9106) and stored FCC (0x929D) retain
+          // factory 3000 mAh defaults. Overwrite both with designCapacity_mAh.
+          Serial.printf("BQ27220: DE correct (%d mWh) — fixing Qmax + stored FCC\n", currentDE);
+
+          // --- Helper lambda for MAC data memory 2-byte write ---
+          // Reads old value + checksum, computes differential checksum, writes new value.
+          auto writeDM16 = [](uint16_t addr, uint16_t newVal) -> bool {
+            // Select address
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x3E);
+            Wire.write(addr & 0xFF);
+            Wire.write((addr >> 8) & 0xFF);
+            Wire.endTransmission();
+            delay(10);
+
+            uint8_t oldMSB = bq27220_read8(0x40);
+            uint8_t oldLSB = bq27220_read8(0x41);
+            uint8_t oldChk = bq27220_read8(0x60);
+            uint8_t dLen   = bq27220_read8(0x61);
+            uint16_t oldVal = (oldMSB << 8) | oldLSB;
+
+            if (oldVal == newVal) {
+              Serial.printf("BQ27220:   [0x%04X] already %d, skip\n", addr, newVal);
+              return true;  // already correct
+            }
+
+            uint8_t newMSB = (newVal >> 8) & 0xFF;
+            uint8_t newLSB = newVal & 0xFF;
+            uint8_t temp = (255 - oldChk - oldMSB - oldLSB);
+            uint8_t newChk = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+            Serial.printf("BQ27220:   [0x%04X] %d -> %d\n", addr, oldVal, newVal);
+
+            // Write new value
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x3E);
+            Wire.write(addr & 0xFF);
+            Wire.write((addr >> 8) & 0xFF);
+            Wire.write(newMSB);
+            Wire.write(newLSB);
+            Wire.endTransmission();
+            delay(5);
+
+            // Write checksum
+            Wire.beginTransmission(BQ27220_I2C_ADDR);
+            Wire.write(0x60);
+            Wire.write(newChk);
+            Wire.write(dLen);
+            Wire.endTransmission();
+            delay(10);
+            return true;
+          };
+
+          // Overwrite Qmax Cell 0 (IT Cfg) — this is what FCC is derived from
+          writeDM16(0x9106, designCapacity_mAh);
+
+          // Overwrite stored FCC reference (Gas Gauging, 2 bytes before DC)
+          writeDM16(0x929D, designCapacity_mAh);
+
+          // Exit with reinit to apply the new values
+          bq27220_writeControl(0x0091);  // EXIT_CFG_UPDATE_REINIT
+          delay(200);
+          Serial.println("BQ27220: Qmax + stored FCC updated, exited CFG_UPDATE");
+        }
+      } else {
+        Serial.println("BQ27220: Failed to enter CFG_UPDATE for DE check");
+      }
+
+      // Seal first, then issue RESET.
+      // RESET forces the gauge to fully reinitialize its Impedance Track
+      // algorithm and recalculate FCC from the current DC/DE values.
+      bq27220_writeControl(0x0030);  // SEAL
+      delay(5);
+      Serial.println("BQ27220: Issuing RESET to force FCC recalculation...");
+      bq27220_writeControl(0x0041);  // RESET
+      delay(2000);  // Full reset needs generous settle time
+
+      fcc = bq27220_read16(BQ27220_REG_FULL_CAP);
+      Serial.printf("BQ27220: FCC after RESET: %d mAh (target <= %d)\n", fcc, designCapacity_mAh);
+
+      if (fcc > designCapacity_mAh * 3 / 2) {
+        // RESET didn't fix FCC — the gauge IT algorithm is stubbornly
+        // retaining its learned value. This typically resolves after one
+        // full charge/discharge cycle. Software clamp in
+        // getFullChargeCapacity() ensures correct display regardless.
+        Serial.printf("BQ27220: FCC still stale at %d — software clamp active\n", fcc);
+      }
+    }
+    return true;
+  }
+
+  Serial.printf("BQ27220: Updating Design Capacity from %d to %d mAh\n", currentDC, designCapacity_mAh);
+
+  // Step 1: Unseal (default unseal keys)
+  bq27220_writeControl(0x0414); delay(2);
+  bq27220_writeControl(0x3672); delay(2);
+
+  // Step 2: Full Access
+  bq27220_writeControl(0xFFFF); delay(2);
+  bq27220_writeControl(0xFFFF); delay(2);
+
+  // Step 3: Enter CFG_UPDATE
+  bq27220_writeControl(0x0090);
+  bool cfgReady = false;
+  for (int i = 0; i < 50; i++) {
+    delay(20);
+    uint16_t opStatus = bq27220_read16(BQ27220_REG_OP_STATUS);
+    if (opStatus & 0x0400) { cfgReady = true; break; }
+  }
+  if (!cfgReady) {
+    Serial.println("BQ27220: Timeout waiting for CFGUPDATE");
+    bq27220_writeControl(0x0092);
+    bq27220_writeControl(0x0030);
+    return false;
+  }
+
+  // Step 4: Write Design Capacity at 0x929F
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x3E); Wire.write(0x9F); Wire.write(0x92);
+  Wire.endTransmission();
+  delay(10);
+
+  uint8_t oldMSB = bq27220_read8(0x40);
+  uint8_t oldLSB = bq27220_read8(0x41);
+  uint8_t oldChk = bq27220_read8(0x60);
+  uint8_t dataLen = bq27220_read8(0x61);
+
+  uint8_t newMSB = (designCapacity_mAh >> 8) & 0xFF;
+  uint8_t newLSB = designCapacity_mAh & 0xFF;
+  uint8_t temp = (255 - oldChk - oldMSB - oldLSB);
+  uint8_t newChk = 255 - ((temp + newMSB + newLSB) & 0xFF);
+
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x3E); Wire.write(0x9F); Wire.write(0x92);
+  Wire.write(newMSB); Wire.write(newLSB);
+  Wire.endTransmission();
+  delay(5);
+  Wire.beginTransmission(BQ27220_I2C_ADDR);
+  Wire.write(0x60); Wire.write(newChk); Wire.write(dataLen);
+  Wire.endTransmission();
+  delay(10);
+
+  // Step 4a: Write Design Energy at 0x92A1
+  {
+    uint16_t designEnergy = (uint16_t)((uint32_t)designCapacity_mAh * 37 / 10);
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+    Wire.endTransmission();
+    delay(10);
+    uint8_t deOldMSB = bq27220_read8(0x40);
+    uint8_t deOldLSB = bq27220_read8(0x41);
+    uint8_t deOldChk = bq27220_read8(0x60);
+    uint8_t deLen    = bq27220_read8(0x61);
+    uint8_t deNewMSB = (designEnergy >> 8) & 0xFF;
+    uint8_t deNewLSB = designEnergy & 0xFF;
+    uint8_t deTemp = (255 - deOldChk - deOldMSB - deOldLSB);
+    uint8_t deNewChk = 255 - ((deTemp + deNewMSB + deNewLSB) & 0xFF);
+
+    Serial.printf("BQ27220: Design Energy: old=%d new=%d mWh\n",
+                  (deOldMSB << 8) | deOldLSB, designEnergy);
+
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x3E); Wire.write(0xA1); Wire.write(0x92);
+    Wire.write(deNewMSB); Wire.write(deNewLSB);
+    Wire.endTransmission();
+    delay(5);
+    Wire.beginTransmission(BQ27220_I2C_ADDR);
+    Wire.write(0x60); Wire.write(deNewChk); Wire.write(deLen);
+    Wire.endTransmission();
+    delay(10);
+  }
+
+  // Step 5: Exit CFG_UPDATE with reinit
+  bq27220_writeControl(0x0091);
+  Serial.println("BQ27220: Sent EXIT_CFG_UPDATE_REINIT, waiting...");
+  delay(200);
+
+  // Step 6: Seal
+  bq27220_writeControl(0x0030);
+  delay(5);
+
+  // Step 7: Force RESET to reinitialize FCC from new DC/DE
+  bq27220_writeControl(0x0041);  // RESET
+  delay(1000);
+
+  uint16_t verifyDC = bq27220_read16(BQ27220_REG_DESIGN_CAP);
+  uint16_t newFCC = bq27220_read16(BQ27220_REG_FULL_CAP);
+  Serial.printf("BQ27220: Post-config DC=%d FCC=%d mAh\n", verifyDC, newFCC);
+
+  return verifyDC == designCapacity_mAh;
+#else
+  return false;
+#endif
+}

variants/lilygo_t5s3_epaper_pro/T5S3Board.h

@@ -0,0 +1,97 @@
+#pragma once
+
+#include "variant.h"
+#include <Wire.h>
+#include <Arduino.h>
+#include "helpers/ESP32Board.h"
+#include <driver/rtc_io.h>
+
+// BQ27220 Fuel Gauge Registers (shared with TDeckBoard)
+#define BQ27220_REG_TEMPERATURE    0x06
+#define BQ27220_REG_VOLTAGE        0x08
+#define BQ27220_REG_CURRENT        0x0C
+#define BQ27220_REG_SOC            0x2C
+#define BQ27220_REG_REMAIN_CAP     0x10
+#define BQ27220_REG_FULL_CAP       0x12
+#define BQ27220_REG_AVG_CURRENT    0x14
+#define BQ27220_REG_TIME_TO_EMPTY  0x16
+#define BQ27220_REG_AVG_POWER      0x24
+#define BQ27220_REG_DESIGN_CAP     0x3C
+#define BQ27220_REG_OP_STATUS      0x3A
+
+class T5S3Board : public ESP32Board {
+public:
+  void begin();
+
+  void powerOff() override {
+    btStop();
+    // Turn off backlight before sleeping
+    #ifdef BOARD_BL_EN
+      digitalWrite(BOARD_BL_EN, LOW);
+    #endif
+  }
+
+  void enterDeepSleep(uint32_t secs, int pin_wake_btn) {
+    esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
+
+    // Hold LoRa DIO1 and NSS during deep sleep
+    rtc_gpio_set_direction((gpio_num_t)P_LORA_DIO_1, RTC_GPIO_MODE_INPUT_ONLY);
+    rtc_gpio_pulldown_en((gpio_num_t)P_LORA_DIO_1);
+    rtc_gpio_hold_en((gpio_num_t)P_LORA_NSS);
+
+    if (pin_wake_btn < 0) {
+      esp_sleep_enable_ext1_wakeup((1ULL << P_LORA_DIO_1), ESP_EXT1_WAKEUP_ANY_HIGH);
+    } else {
+      esp_sleep_enable_ext1_wakeup((1ULL << P_LORA_DIO_1) | (1ULL << pin_wake_btn), ESP_EXT1_WAKEUP_ANY_HIGH);
+    }
+
+    if (secs > 0) {
+      esp_sleep_enable_timer_wakeup(secs * 1000000ULL);
+    }
+
+    esp_deep_sleep_start();
+  }
+
+  // BQ27220 fuel gauge interface (identical register protocol to TDeckBoard)
+  uint16_t getBattMilliVolts() override;
+  uint8_t  getBatteryPercent();
+  int16_t  getAvgCurrent();
+  int16_t  getAvgPower();
+  uint16_t getTimeToEmpty();
+  uint16_t getRemainingCapacity();
+  uint16_t getFullChargeCapacity();
+  uint16_t getDesignCapacity();
+  int16_t  getBattTemperature();
+  bool     configureFuelGauge(uint16_t designCapacity_mAh = BQ27220_DESIGN_CAPACITY_MAH);
+
+  // Backlight control (GPIO11 — functional warm-tone front-light, PWM capable)
+  // Brightness 0-255 (0=off, 153=comfortable reading, 255=max)
+  bool _backlightOn = false;
+  uint8_t _backlightBrightness = 153;  // Same default as Meshtastic
+
+  void setBacklight(bool on) {
+    #ifdef BOARD_BL_EN
+      _backlightOn = on;
+      analogWrite(BOARD_BL_EN, on ? _backlightBrightness : 0);
+    #endif
+  }
+
+  void setBacklightBrightness(uint8_t brightness) {
+    #ifdef BOARD_BL_EN
+      _backlightBrightness = brightness;
+      if (_backlightOn) {
+        analogWrite(BOARD_BL_EN, brightness);
+      }
+    #endif
+  }
+
+  bool isBacklightOn() const { return _backlightOn; }
+
+  void toggleBacklight() {
+    setBacklight(!_backlightOn);
+  }
+
+  const char* getManufacturerName() const {
+    return "LilyGo T5S3 E-Paper Pro";
+  }
+};

variants/lilygo_t5s3_epaper_pro/pins_arduino.h

@@ -0,0 +1,19 @@
+#ifndef Pins_Arduino_h
+#define Pins_Arduino_h
+
+#include <stdint.h>
+
+#define USB_VID 0x303a
+#define USB_PID 0x1001
+
+// Default Wire will be mapped to RTC, Touch, PCA9535, BQ25896, BQ27220, TPS65185
+static const uint8_t SDA = 39;
+static const uint8_t SCL = 40;
+
+// Default SPI will be mapped to LoRa + SD card
+static const uint8_t SS   = 46;   // LoRa CS
+static const uint8_t MOSI = 13;
+static const uint8_t MISO = 21;
+static const uint8_t SCK  = 14;
+
+#endif /* Pins_Arduino_h */

variants/lilygo_t5s3_epaper_pro/platformio.ini

@@ -0,0 +1,169 @@
+; ===========================================================================
+; LilyGo T5 S3 E-Paper Pro (H752-B / V2 hardware)
+; 4.7" parallel e-ink (960x540), GT911 touch, SX1262 LoRa, no keyboard
+; ===========================================================================
+;
+; Place t5s3-epaper-pro.json in boards/ directory.
+; Place variant files in variants/LilyGo_T5S3_EPaper_Pro/
+; Place FastEPDDisplay.h/.cpp in src/helpers/ui/
+;
+
+[LilyGo_T5S3_EPaper_Pro]
+extends = esp32_base
+extra_scripts = post:merge_firmware.py
+board = t5s3-epaper-pro
+board_build.flash_mode = qio
+board_build.f_flash = 80000000L
+board_build.arduino.memory_type = qio_opi
+board_upload.flash_size = 16MB
+build_flags =
+  ${esp32_base.build_flags}
+  -I variants/LilyGo_T5S3_EPaper_Pro
+  -D LilyGo_T5S3_EPaper_Pro
+  -D T5_S3_EPAPER_PRO_V2
+  -D BOARD_HAS_PSRAM=1
+  -D CORE_DEBUG_LEVEL=1
+  -D FORMAT_SPIFFS_IF_FAILED=1
+  -D FORMAT_LITTLEFS_IF_FAILED=1
+  -D ARDUINO_USB_CDC_ON_BOOT=1
+  -D RADIO_CLASS=CustomSX1262
+  -D WRAPPER_CLASS=CustomSX1262Wrapper
+  -D LORA_TX_POWER=22
+  -D SX126X_DIO2_AS_RF_SWITCH
+  -D SX126X_CURRENT_LIMIT=140
+  -D SX126X_RX_BOOSTED_GAIN=1
+  -D SX126X_DIO3_TCXO_VOLTAGE=2.4f
+  -D P_LORA_DIO_1=10
+  -D P_LORA_NSS=46
+  -D P_LORA_RESET=1
+  -D P_LORA_BUSY=47
+  -D P_LORA_SCLK=14
+  -D P_LORA_MISO=21
+  -D P_LORA_MOSI=13
+  -D ENV_INCLUDE_AHTX0=0
+  -D ENV_INCLUDE_BME280=0
+  -D ENV_INCLUDE_BMP280=0
+  -D ENV_INCLUDE_SHTC3=0
+  -D ENV_INCLUDE_SHT4X=0
+  -D ENV_INCLUDE_LPS22HB=0
+  -D ENV_INCLUDE_INA3221=0
+  -D ENV_INCLUDE_INA219=0
+  -D ENV_INCLUDE_INA226=0
+  -D ENV_INCLUDE_INA260=0
+  -D ENV_INCLUDE_MLX90614=0
+  -D ENV_INCLUDE_VL53L0X=0
+  -D ENV_INCLUDE_BME680=0
+  -D ENV_INCLUDE_BMP085=0
+  -D HAS_BQ27220=1
+  -D AUTO_SHUTDOWN_MILLIVOLTS=2800
+  -D PIN_USER_BTN=0
+  -D SDCARD_USE_SPI1
+  -D ARDUINO_LOOP_STACK_SIZE=32768
+build_src_filter = ${esp32_base.build_src_filter}
+  +<../variants/LilyGo_T5S3_EPaper_Pro>
+lib_deps =
+  ${esp32_base.lib_deps}
+  WebServer
+  DNSServer
+  Update
+
+; ---------------------------------------------------------------------------
+; T5S3 standalone — touch UI (stub), verify display rendering
+; Uses FastEPD for parallel e-ink, Adafruit GFX for drawing
+; OTA enabled: WiFi AP activates only during user-initiated firmware updates.
+; ---------------------------------------------------------------------------
+[env:meck_t5s3_standalone]
+extends = LilyGo_T5S3_EPaper_Pro
+build_flags =
+  ${LilyGo_T5S3_EPaper_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D OFFLINE_QUEUE_SIZE=1
+  -D CHANNEL_MSG_HISTORY_SIZE=800
+  -D DISPLAY_CLASS=FastEPDDisplay
+  -D USE_EINK
+  -D MECK_CARDKB
+  -D MECK_OTA_UPDATE=1
+  ; -D MECK_SERIF_FONT  ; FreeSerif (Times New Roman-like)
+  ;                      ; Default (no flag): FreeSans (Arial-like)
+build_src_filter = ${LilyGo_T5S3_EPaper_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<helpers/ui/FastEPDDisplay.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+lib_deps =
+  ${LilyGo_T5S3_EPaper_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  adafruit/Adafruit GFX Library@^1.11.0
+  https://github.com/mverch67/FastEPD/archive/0df1bff329b6fc782e062f611758880762340647.zip
+  https://github.com/lewisxhe/SensorLib/archive/refs/tags/v0.3.4.zip
+
+; ---------------------------------------------------------------------------
+; T5S3 BLE companion — touch UI, BLE phone bridging
+; Connect via MeshCore iOS/Android app over Bluetooth
+; OTA enabled: WiFi AP activates only during user-initiated firmware updates.
+; Flash: pio run -e meck_t5s3_ble -t upload
+; ---------------------------------------------------------------------------
+[env:meck_t5s3_ble]
+extends = LilyGo_T5S3_EPaper_Pro
+build_flags =
+  ${LilyGo_T5S3_EPaper_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=500
+  -D MAX_GROUP_CHANNELS=20
+  -D BLE_PIN_CODE=123456
+  -D OFFLINE_QUEUE_SIZE=256
+  -D DISPLAY_CLASS=FastEPDDisplay
+  -D USE_EINK
+  -D MECK_CARDKB
+  -D MECK_OTA_UPDATE=1
+  ; -D MECK_SERIF_FONT
+build_src_filter = ${LilyGo_T5S3_EPaper_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<helpers/ui/FastEPDDisplay.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+lib_deps =
+  ${LilyGo_T5S3_EPaper_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  adafruit/Adafruit GFX Library@^1.11.0
+  https://github.com/mverch67/FastEPD/archive/0df1bff329b6fc782e062f611758880762340647.zip
+  https://github.com/lewisxhe/SensorLib/archive/refs/tags/v0.3.4.zip
+
+; ---------------------------------------------------------------------------
+; T5S3 WiFi companion — touch UI, WiFi phone bridging, web browser
+; Connect via MeshCore web app or meshcore.js over local network (TCP:5000)
+; MECK_WEB_READER: shares WiFi companion connection — no extra setup needed
+; Flash: pio run -e meck_t5s3_wifi -t upload
+; ---------------------------------------------------------------------------
+[env:meck_t5s3_wifi]
+extends = LilyGo_T5S3_EPaper_Pro
+build_flags =
+  ${LilyGo_T5S3_EPaper_Pro.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=1500
+  -D MAX_GROUP_CHANNELS=20
+  -D MECK_WIFI_COMPANION=1
+  -D MECK_WEB_READER=1
+  -D MECK_OTA_UPDATE=1
+  -D TCP_PORT=5000
+  -D OFFLINE_QUEUE_SIZE=256
+  -D DISPLAY_CLASS=FastEPDDisplay
+  -D USE_EINK
+  -D MECK_CARDKB
+  ; -D MECK_SERIF_FONT
+build_src_filter = ${LilyGo_T5S3_EPaper_Pro.build_src_filter}
+  +<helpers/esp32/*.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<helpers/ui/FastEPDDisplay.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+lib_deps =
+  ${LilyGo_T5S3_EPaper_Pro.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  adafruit/Adafruit GFX Library@^1.11.0
+  https://github.com/mverch67/FastEPD/archive/0df1bff329b6fc782e062f611758880762340647.zip
+  https://github.com/lewisxhe/SensorLib/archive/refs/tags/v0.3.4.zip

variants/lilygo_t5s3_epaper_pro/target.cpp

@@ -0,0 +1,91 @@
+#include <Arduino.h>
+#include "variant.h"
+#include "target.h"
+
+T5S3Board board;
+
+// LoRa radio on separate SPI bus
+// T5S3 V2 SPI pins: SCLK=14, MISO=21, MOSI=13 (shared with SD card)
+#if defined(P_LORA_SCLK)
+  static SPIClass loraSpi(HSPI);
+  RADIO_CLASS radio = new Module(P_LORA_NSS, P_LORA_DIO_1, P_LORA_RESET, P_LORA_BUSY, loraSpi);
+#else
+  RADIO_CLASS radio = new Module(P_LORA_NSS, P_LORA_DIO_1, P_LORA_RESET, P_LORA_BUSY);
+#endif
+
+WRAPPER_CLASS radio_driver(radio, board);
+
+PCF85063Clock rtc_clock;
+
+// No GPS on H752-B
+#if HAS_GPS
+  GPSStreamCounter gpsStream(Serial2);
+  MicroNMEALocationProvider gps(gpsStream, &rtc_clock);
+  EnvironmentSensorManager sensors(gps);
+#else
+  SensorManager sensors;
+#endif
+
+// Phase 2: Display
+#ifdef DISPLAY_CLASS
+  DISPLAY_CLASS display;
+  MomentaryButton user_btn(PIN_USER_BTN, 1000, true);
+#endif
+
+bool radio_init() {
+  MESH_DEBUG_PRINTLN("radio_init() - starting");
+
+  // NOTE: board.begin() is called by main.cpp setup() before radio_init()
+  // I2C is already initialized there with correct pins
+
+  // PCF85063 hardware RTC — reads correct registers (0x04–0x0A)
+  // Unlike AutoDiscoverRTCClock which uses RTClib's PCF8563 driver (wrong registers)
+  rtc_clock.begin(Wire);
+  MESH_DEBUG_PRINTLN("radio_init() - PCF85063 RTC started");
+
+#if defined(P_LORA_SCLK)
+  MESH_DEBUG_PRINTLN("radio_init() - initializing LoRa SPI (SCLK=%d, MISO=%d, MOSI=%d, NSS=%d)...",
+                     P_LORA_SCLK, P_LORA_MISO, P_LORA_MOSI, P_LORA_NSS);
+  loraSpi.begin(P_LORA_SCLK, P_LORA_MISO, P_LORA_MOSI, P_LORA_NSS);
+  MESH_DEBUG_PRINTLN("radio_init() - SPI initialized, calling radio.std_init()...");
+  bool result = radio.std_init(&loraSpi);
+  if (result) {
+    radio.setPreambleLength(32);
+    MESH_DEBUG_PRINTLN("radio_init() - preamble set to 32 symbols");
+  }
+  MESH_DEBUG_PRINTLN("radio_init() - radio.std_init() returned: %s", result ? "SUCCESS" : "FAILED");
+  return result;
+#else
+  MESH_DEBUG_PRINTLN("radio_init() - calling radio.std_init() without custom SPI...");
+  bool result = radio.std_init();
+  if (result) {
+    radio.setPreambleLength(32);
+    MESH_DEBUG_PRINTLN("radio_init() - preamble set to 32 symbols");
+  }
+  return result;
+#endif
+}
+
+uint32_t radio_get_rng_seed() {
+  return radio.random(0x7FFFFFFF);
+}
+
+void radio_set_params(float freq, float bw, uint8_t sf, uint8_t cr) {
+  radio.setFrequency(freq);
+  radio.setSpreadingFactor(sf);
+  radio.setBandwidth(bw);
+  radio.setCodingRate(cr);
+}
+
+void radio_set_tx_power(uint8_t dbm) {
+  radio.setOutputPower(dbm);
+}
+
+mesh::LocalIdentity radio_new_identity() {
+  RadioNoiseListener rng(radio);
+  return mesh::LocalIdentity(&rng);
+}
+
+void radio_reset_agc() {
+  radio.setRxBoostedGainMode(true);
+}