2026.06.12

Author: trip5

.github/ai-coding-guide.md

@@ -48,6 +48,10 @@
   - **If the change touches ANY firmware file**: You **MUST READ** `.github/code-summary.md` before writing code. Also check `.github/code-issues.md` for known issues in the affected area.
   - **If the change touches ONLY non-firmware files** (workflows, docs, build scripts, config generators, Home Assistant, images, etc.): `code-summary.md` review is **NOT** required. Still check `code-issues.md` if relevant.
   - **One-line/trivial fixes** (typos, formatting) are exempt regardless of file type.
+- **What `.github/code-issues.md` is for**: it tracks **open** issues that still need investigation, or that are blocked — for example, waiting on hardware the maintainer does not own. It is **not** a changelog.
+  - Do **not** add entries for problems found and fixed in the same change set.
+  - Do **not** add general rules or subsystem documentation there; that belongs in `code-summary.md` (Rule #4).
+  - Do read it before editing an affected area, and **update or close an existing entry** if your change fixes it or alters the code that entry describes.
 
 **Enforcement and AI Behavior**
 - Always validate proposed changes against these rules **before every action**.

.github/code-summary.md

@@ -754,6 +754,35 @@ Important rendering invariants:
 - Never call `startWrite()`/`endWrite()` in `write()` or `writePixel`/`writeFillRect` overrides — SPI nesting causes hangs on Adafruit TFT drivers.
 - The `gfxFont == NULL` case (YO_MONO / display font) runs through `_writeGlyph` using DisplayFont, NOT the built-in glcdfont. This means glyph metrics (yAdvance, yOffset, xAdvance) come from DisplayFont.
 
+## Display Widget Memory Ownership
+
+The widget classes mix two allocation conventions; release must match allocation:
+
+| Member | Owner | Allocated with | Released with |
+|---|---|---|---|
+| `_text`, `_oldtext` | `TextWidget` (and `NumWidget`, which duplicates it) | `malloc` | `free` |
+| `_sep`, `_window` | `ScrollWidget` | `malloc` | `free` |
+| `_fb` | `ScrollWidget`, `ClockWidget` | `new psFrameBuffer` | `delete` |
+| `_canvas` | `VuWidget` | `new Canvas` | `delete` |
+
+Rules:
+- Never `free()` a `new`-allocated object: `free()` skips the destructor and leaks the internal buffer.
+- `init()` is re-called on every layout/theme change, so it must release its previous buffers first.
+- Resize an existing `psFrameBuffer` with `freeBuffer()` then `begin()`, never by allocating a second one.
+
+### Optional widget guard fields
+
+Each config type has its own field that makes a widget meaningful, and that is what the creation guard in `display.cpp` must test — never a coordinate, since `{0,0}` is a legitimate position:
+
+| Config type | Fields | Guard field |
+|---|---|---|
+| `WidgetConfig` | `left`, `top`, `textsize`, `align` | `textsize > 0` |
+| `ScrollConfig` | `widget`, `buffsize`, `uppercase`, `width`, ... | `buffsize > 0` |
+| `FillConfig` | `widget`, `width`, `height`, `outlined` | `height > 0` |
+| `BitrateConfig` | `widget`, `dimension` | `dimension > 0` |
+
+`_fullbitrate` and `_bitrate` are alternatives: an empty `.fullbitrateConf` falls back to `.bitrateConf`, and `_reinitWidgets` must tear down whichever one is no longer wanted even when the replacement config is itself empty.
+
 ## Screen Rendering Fixes (Session: SH1106 YO_MONO)
 
 ### ClockWidget colon blink (widgets.cpp)
@@ -775,6 +804,13 @@ Important rendering invariants:
 
 ---
 
+## Screen Rendering Fixes (Session: VU Rotated Layout)
+
+- **New layout flag** `LayoutData::rotateVU` (exposed via `rotateVU_ptr`), treated exactly like `boomboxStyle` — absent means false. `VuWidget::_rotate` is read from `rotateVU_ptr` in `init()`.
+- **Layout ordering** in `displayTFT480x320conf.h`: `_layoutNames` is now `Default`, `Default (VU Rotated)`, `VaraiTamas (BoomBox)`. The rotated layout is layout #2 (`bandsConf = { 32, 130, 4, 2, 10, 3 }`, `.rotateVU = true`); BoomBox moved to #3.
+- **Blit choice**: `VuWidget::_draw()` uses the manual `startWrite()` / `setAddrWindow()` / `writePixels()` / `endWrite()` sequence for all three modes. `drawRGBBitmap()` was deliberately removed from the widget layer — the manual path depends only on `setAddrWindow` and `writePixels`, which every TFT driver is guaranteed to implement, and it issues a single bulk transfer rather than one `writePixels` call per scanline. Do not switch this back.
+- **Direction**: the rotated VU fills left-to-right with `_vumaxcolor` at the right end.
+
 ## CPU Core Assignments & Stack Sizes
 
 The ESP32 has two hardware cores: **Core 0** (PRO_CPU) and **Core 1** (APP_CPU). The ESP32 Arduino framework runs `setup()` and `loop()` on Core 1. Audio decoding is isolated on Core 0; all other application tasks run on Core 1.

src/core/display.cpp

@@ -248,7 +248,7 @@ void Display::_buildPager() {
   if (fullbitrateConf_ptr->dimension > 0) {
     _fullbitrate = new BitrateWidget(*fullbitrateConf_ptr, config.theme.bitrate, config.theme.background);
     pages[PG_PLAYER]->addWidget(_fullbitrate);
-  } else {
+  } else if (bitrateConf_ptr->textsize > 0) {
     _bitrate = new TextWidget(*bitrateConf_ptr, 30, false, config.theme.bitrate, config.theme.background);
     pages[PG_PLAYER]->addWidget(_bitrate);
   }
@@ -310,7 +310,11 @@ void Display::_buildPager() {
 }
 
 void Display::_apScreen() {
-  if (_boot) _pager->removePage(_boot);
+  if (_boot) {
+    _pager->removePage(_boot);
+    _boot = nullptr;
+    _bootstring = nullptr;
+  }
   #ifndef DSP_LCD
     _boot = new Page();
     #if DSP_MODEL!=DSP_NOKIA5110
@@ -349,7 +353,11 @@ void Display::_apScreen() {
 }
 
 void Display::_start() {
-  if (_boot) _pager->removePage(_boot);
+  if (_boot) {
+    _pager->removePage(_boot);
+    _boot = nullptr;
+    _bootstring = nullptr;
+  }
   if (network.status != CONNECTED && network.status != SDOFFLINE) {
     _apScreen();
       _bootStep = 2;
@@ -983,11 +991,13 @@ void Display::_reinitWidgets() {
       pages[PG_PLAYER]->addWidget(_fullbitrate);
     } else _fullbitrate->init(*fullbitrateConf_ptr, config.theme.bitrate, config.theme.background);
   } else {
-    if (!_bitrate) {
-      if (_fullbitrate) { pages[PG_PLAYER]->removeWidget(_fullbitrate); delete _fullbitrate; _fullbitrate = nullptr; }
-      _bitrate = new TextWidget(*bitrateConf_ptr, 30, false, config.theme.bitrate, config.theme.background);
-      pages[PG_PLAYER]->addWidget(_bitrate);
-    } else _bitrate->init(*bitrateConf_ptr, 30, false, config.theme.bitrate, config.theme.background);
+    if (_fullbitrate) { pages[PG_PLAYER]->removeWidget(_fullbitrate); delete _fullbitrate; _fullbitrate = nullptr; }
+    if (bitrateConf_ptr->textsize > 0) {
+      if (!_bitrate) {
+        _bitrate = new TextWidget(*bitrateConf_ptr, 30, false, config.theme.bitrate, config.theme.background);
+        pages[PG_PLAYER]->addWidget(_bitrate);
+      } else _bitrate->init(*bitrateConf_ptr, 30, false, config.theme.bitrate, config.theme.background);
+    }
   }
 
   // --- Footer widgets (lazy-create if newly enabled) ---
@@ -1037,6 +1047,16 @@ void Display::_reinitWidgets() {
   #if DSP_MODEL==DSP_NOKIA5110
     if (_plbackground) _plbackground->init(*playlBGConf_ptr, 1);
   #endif
+  /* _plbackground->init() above resets _height and _config.top back to playlBGConf.
+     Its geometry is meant to follow the live playlist rows, so re-apply the same
+     values _buildPager() uses — otherwise the highlight band keeps the conf
+     height/position instead of matching itemHeight(). */
+  #if !defined(DSP_LCD) && !PLAYLIST_MODE_PAGED
+    if (_plbackground) {
+      _plbackground->setHeight(_plwidget->itemHeight());
+      _plbackground->moveTo({0,(uint16_t)(_plwidget->currentTop()-playlistConf_ptr->widget.textsize*2), (int16_t)playlBGConf_ptr->width});
+    }
+  #endif
 }
 
 void Display::_setLayoutPointers() {

src/displays/conf/displayTFT480x320conf.h

@@ -87,13 +87,11 @@ const LayoutData _layouts[] PROGMEM = {
         .rssiConf            = { TFT_FRAMEWDT, DSP_HEIGHT-38-6, 3, WA_RIGHT },
         .numConf             = { 0, 200, 0, WA_CENTER },
         .clockConf           = { TFT_FRAMEWDT*2, 230, 0, WA_RIGHT },
-        .vuConf              = { TFT_FRAMEWDT, 161, 1, WA_LEFT }, //136 touches title2 almost, 210 touches IP, 162 (161?) top of clock
-        //.vuConf              = { TFT_FRAMEWDT, 159, 1, WA_LEFT }, //136 touches title2 almost, 210 touches IP, 162 (161?) top of clock
+        .vuConf              = { TFT_FRAMEWDT, 161, 1, WA_LEFT },
         /* CODEC BADGE         {{ left, top, fontsize, align }, dimension} - if empty, bitrateConf will be used instead */
         .fullbitrateConf     = {{ DSP_WIDTH-TFT_FRAMEWDT-38, 59, 2, WA_LEFT }, 42 },
         /* VU BANDS            { onebandwidth, onebandheight, bandsHspace, bandsVspace, numofbands, fadespeed } */
-        //.bandsConf           = { 46, 130, 7, 2, 10, 3 }, //1st: 32, 130, 4, 2
-        .bandsConf           = { 25, 130, 17, 3, 10, 3 }, //1st: 32, 130, 4, 2
+        .bandsConf           = { 25, 130, 17, 3, 10, 3 },
         /* MOVES               { left, top, width (-1 keeps Conf position) */
         .clockMove           = { 0, 0, -1 },
         .weatherMove         = { TFT_FRAMEWDT, 120, MAX_WIDTH },

src/displays/tools/psframebuffer.h

@@ -35,9 +35,10 @@ class  psFrameBuffer : public Adafruit_GFX {
       _ready = false;
       if(buffer) {
         _dspl->fillRect(_ll, _tt, _ww, _hh, _bgcolor);
-        psramFrameBufferBytes -= _hh * _ww * sizeof(uint16_t);
+        if (_psram) psramFrameBufferBytes -= _hh * _ww * sizeof(uint16_t);
         free(buffer);
       }
+      _psram = false;
       buffer = nullptr;
     }
     bool begin(yoDisplay *dspl, int16_t l, int16_t t, int16_t w, int16_t h, uint16_t bgcolor = 0){
@@ -99,17 +100,20 @@ class  psFrameBuffer : public Adafruit_GFX {
     int16_t height(){ return _hh; }
   private:
     int16_t _ll, _tt, _ww, _hh;
-    yoDisplay *_dspl;
+    yoDisplay *_dspl = nullptr;
     uint16_t *buffer=nullptr;
     bool _ready = false;
+    bool _psram = false;
     uint16_t _bgcolor;
     void _createBuffer(){
       #if (defined(USE_FBUFFER) && USE_FBUFFER)
         if(psramInit()) {
           buffer = (uint16_t*) ps_calloc(_hh * _ww, sizeof(uint16_t));
+          _psram = true;
           psramFrameBufferBytes += _hh * _ww * sizeof(uint16_t);
         } else {
           buffer = (uint16_t*) calloc(_hh * _ww, sizeof(uint16_t));
+          _psram = false;
         }
       #endif
       if(buffer){

src/displays/widgets/pages.cpp

@@ -47,7 +47,9 @@ void Pager::setPage(Page* page, bool black){
 //}
 
 Page::~Page() {
-  for (const auto& w : _widgets) removeWidget(w);
+  std::list<Widget*> draining;
+  draining.swap(_widgets);
+  for (const auto& w : draining) delete w;
   // what about deleting _pages ???
 }