@typecad/ui 1.0.0-alpha.7 → 1.0.0-alpha.9

package/src/ui-engine/runtime-header/canvas-scrollbar.ts

@@ -13,12 +13,16 @@ static inline void ui_push_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
   // via __ui_gfx (so the single bulk push at frame end captures everything).
   // Otherwise write straight to the display in one SPI transaction.
   if (__ui_fb) {
+    // The framebuffer is the composition target. Track this publish so a
+    // geometry repair or scroll-canvas repair that does not leave a node dirty
+    // still reaches the panel during the frame-end flush.
+    ui_fb_add_rect(x, y, w, h);
     if (w == stride) {
       ui_display_draw_rgb_bitmap(x, y, pixels, w, h);
       return;
     }
     for (int16_t row = 0; row < h; row++) {
-      ui_display_draw_rgb_bitmap(x, y + row, pixels + (int32_t)row * stride, w, 1);
+      ui_display_draw_rgb_bitmap(x, y + row, pixels + static_cast<int32_t>(row) * stride, w, 1);
     }
     return;
   }
@@ -26,12 +30,12 @@ static inline void ui_push_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
   display_setAddrWindow(x, y, w, h);
   if (w == stride) {
     // Full-width: contiguous in buffer, single write.
-    display_writePixels(pixels, (uint32_t)w * h);
+    display_writePixels(pixels, static_cast<uint32_t>(w) * h);
     display_endWrite();
     return;
   }
   for (int16_t row = 0; row < h; row++) {
-    display_writePixels(pixels + (int32_t)row * stride, w);
+    display_writePixels(pixels + static_cast<int32_t>(row) * stride, w);
   }
   display_endWrite();
 }
@@ -45,7 +49,7 @@ static inline void ui_draw_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
     return;
   }
   for (int16_t row = 0; row < h; row++) {
-    ui_display_draw_rgb_bitmap(x, y + row, pixels + (int32_t)row * stride, w, 1);
+    ui_display_draw_rgb_bitmap(x, y + row, pixels + static_cast<int32_t>(row) * stride, w, 1);
   }
 }
 
@@ -67,10 +71,14 @@ static inline void ui_push_buffered_scroll_canvas(CuttlefishCanvas16* bufferedSc
     ui_draw_canvas_rect(bufferedScrollRepaintCanvas, 0, bufferedScrollRepaintY, vw, bufferedScrollRepaintH);
   }
   int16_t tx = vw - 4;
-  uint16_t thumbH = (uint32_t)vh * vh / __ui_nodes[si].contentHeight;
+  uint16_t thumbH = static_cast<uint32_t>(vh) * vh / __ui_nodes[si].contentHeight;
   if (thumbH < 8) thumbH = 8;
+  // Clamp to vh so (vh - thumbH) below can't underflow on a degenerate sub-8px
+  // viewport (which would cast a negative value to a huge uint32_t and place the
+  // thumb off-screen). Matches the guard in ui_render_scroll_bands.
+  if (thumbH > static_cast<uint16_t>(vh)) thumbH = static_cast<uint16_t>(vh);
   int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
-  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  uint16_t thumbY = static_cast<uint32_t>(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
   UI_COLOR_T dimFg = (UI_COLOR_T)((__ui_nodes[si].fg >> 1) & UI_DIM_MASK);
   ui_display_fill_rect(tx, 0, 3, vh, dimFg);
   ui_display_fill_rect(tx, thumbY, 3, thumbH, __ui_nodes[si].fg);
@@ -87,18 +95,22 @@ static inline void ui_push_buffered_scroll_canvas(CuttlefishCanvas16* bufferedSc
 
 // Draw a scroll container's scrollbar directly on the display (Mode C).
 static inline void ui_draw_scrollbar_direct(int16_t si, int16_t vox, int16_t voy) {
-  if (si < 0 || si >= (int16_t)__ui_node_count) return;
+  if (si < 0 || si >= static_cast<int16_t>(__ui_node_count)) return;
   int16_t vw = __ui_nodes[si].box.w;
   int16_t vh = __ui_nodes[si].box.h;
   if (__ui_nodes[si].contentHeight <= vh) return;
   int16_t tx = vox + vw - 4;
-  uint16_t thumbH = (uint32_t)vh * vh / __ui_nodes[si].contentHeight;
+  uint16_t thumbH = static_cast<uint32_t>(vh) * vh / __ui_nodes[si].contentHeight;
   if (thumbH < 8) thumbH = 8;
+  // Clamp to vh so (vh - thumbH) below can't underflow on a degenerate sub-8px
+  // viewport (which would cast a negative value to a huge uint32_t and place the
+  // thumb off-screen). Matches the guard in ui_render_scroll_bands.
+  if (thumbH > static_cast<uint16_t>(vh)) thumbH = static_cast<uint16_t>(vh);
   int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
-  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  uint16_t thumbY = static_cast<uint32_t>(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
   UI_COLOR_T dimFg = (UI_COLOR_T)((__ui_nodes[si].fg >> 1) & UI_DIM_MASK);
   ui_display_fill_rect(tx, voy, 3, vh, dimFg);
-  ui_display_fill_rect(tx, (int16_t)(voy + thumbY), 3, thumbH, __ui_nodes[si].fg);
+  ui_display_fill_rect(tx, static_cast<int16_t>(voy + thumbY), 3, thumbH, __ui_nodes[si].fg);
 }
 
 // Per-node dirty marker (called by press handlers and binding evaluation).`;

package/src/ui-engine/runtime-header/color-mono-refresh.ts

@@ -39,11 +39,11 @@ static inline uint32_t ui_blend888(uint32_t fg, uint32_t bg, uint8_t opacity);
 static inline uint16_t lerp_color(uint16_t a, uint16_t b, uint8_t k100);
 static inline uint32_t lerp_color_888(uint32_t a, uint32_t b, uint8_t k100);
 #if UI_COLOR_DEPTH == 888
-  #define ui_blend(fg, bg, op)        ui_blend888((uint32_t)(fg), (uint32_t)(bg), (op))
-  #define UI_LERP_COLOR(a, b, k)      lerp_color_888((uint32_t)(a), (uint32_t)(b), (k))
+  #define ui_blend(fg, bg, op)        ui_blend888(static_cast<uint32_t>(fg), static_cast<uint32_t>(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color_888(static_cast<uint32_t>(a), static_cast<uint32_t>(b), (k))
 #else
-  #define ui_blend(fg, bg, op)        ui_blend565((uint16_t)(fg), (uint16_t)(bg), (op))
-  #define UI_LERP_COLOR(a, b, k)      lerp_color((uint16_t)(a), (uint16_t)(b), (k))
+  #define ui_blend(fg, bg, op)        ui_blend565(static_cast<uint16_t>(fg), static_cast<uint16_t>(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color(static_cast<uint16_t>(a), static_cast<uint16_t>(b), (k))
 #endif
 
 // ── 1-bit mono snap (UI_NATIVE_MONO) ─────────────────────────────────────────
@@ -57,7 +57,7 @@ static inline uint32_t ui_snap_mono(uint32_t c) {
   uint8_t r = (c >> 16) & 0xff, g = (c >> 8) & 0xff, b = c & 0xff;
   // Match the transpile-time toMono threshold: (0.299r + 0.587g + 0.114b)/255 >= 0.27.
   // Integer form: 299r+587g+114b >= 68850 (= 0.27*255*1000). Verified 0 mismatches.
-  return ((uint32_t)(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffffu : 0x000000u;
+  return (static_cast<uint32_t>(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffffu : 0x000000u;
 }
 // Snap an RGB565 value to 1-bit mono. Mono panels run at UI_COLOR_DEPTH 565, so
 // node fields hold 565 values; reconstruct 8-bit channels then apply the threshold.
@@ -68,10 +68,10 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
   if (c == 0x0001u || c == 0xffffu) return 0xffffu;
   uint8_t r5 = (c >> 11) & 0x1f, g6 = (c >> 5) & 0x3f, b5 = c & 0x1f;
   uint8_t r = (r5 << 3) | (r5 >> 2), g = (g6 << 2) | (g6 >> 4), b = (b5 << 3) | (b5 >> 2);
-  return ((uint32_t)(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffu : 0x0000u;
+  return (static_cast<uint32_t>(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffu : 0x0000u;
 }
-#define UI_MAYBE_SNAP_MONO(c)    (ui_snap_mono((uint32_t)(c)))
-#define UI_MAYBE_SNAP_MONO565(c) (ui_snap_mono565((uint16_t)(c)))
+#define UI_MAYBE_SNAP_MONO(c)    (ui_snap_mono(static_cast<uint32_t>(c)))
+#define UI_MAYBE_SNAP_MONO565(c) (ui_snap_mono565(static_cast<uint16_t>(c)))
 #else
 #define UI_MAYBE_SNAP_MONO(c)    (c)
 #define UI_MAYBE_SNAP_MONO565(c) (c)
@@ -115,7 +115,7 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
       const UIRect16& r = __ui_refresh_rects[i];
       if (r.x < x0) x0 = r.x;
       if (r.y < y0) y0 = r.y;
-      int16_t rx1 = (int16_t)(r.x + r.w), ry1 = (int16_t)(r.y + r.h);
+      int16_t rx1 = static_cast<int16_t>(r.x + r.w), ry1 = static_cast<int16_t>(r.y + r.h);
       if (rx1 > x1) x1 = rx1;
       if (ry1 > y1) y1 = ry1;
     }
@@ -124,7 +124,7 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
     if (x1 > display_width()) x1 = display_width();
     if (y1 > display_height()) y1 = display_height();
     if (x1 > x0 && y1 > y0) {
-      display_partial_refresh(x0, y0, (int16_t)(x1 - x0), (int16_t)(y1 - y0));
+      display_partial_refresh(x0, y0, static_cast<int16_t>(x1 - x0), static_cast<int16_t>(y1 - y0));
     }
   }
 #elif defined(UI_BATCH_SPI_WRITES)

package/src/ui-engine/runtime-header/cuttlefish-gfx.ts

@@ -1,8 +1,9 @@
 // ---------------------------------------------------------------------------
 // Slice of the C++ runtime header. Defines the CuttlefishGFX class — the
-// shared geometry/canvas/text base used by native (non-Arduino) display
-// adapters. Emitted ONLY when a native adapter is active; Arduino paths use
-// Adafruit_GFX directly and never see this code.
+// shared geometry/canvas/text base used by native display adapters that
+// instantiate CuttlefishGFX by value. NOT emitted on macro-alias paths
+// (Adafruit `CuttlefishCanvas16==GFXcanvas16`, SDL
+// `CuttlefishCanvas16==SdlGfxCanvas`), which own the canvas type.
 //
 // ──── BSD-3-Clause attribution ────────────────────────────────────────────
 // The geometry algorithm implementations emitted by this slice (drawLine,
@@ -56,13 +57,16 @@ export function emitCuttlefishGfx(active: boolean): string {
 
   return `
 // ── CuttlefishGFX (native display GFX base) ────────────────────────────────
-// Emitted only when strategy.providesDisplayAdapter() is true.
+// Emitted only for native adapters that instantiate CuttlefishGFX by value;
+// suppressed on macro-alias paths (Adafruit CuttlefishCanvas16==GFXcanvas16,
+// SDL CuttlefishCanvas16==SdlGfxCanvas). Gated in ui-emitter.ts.
 #ifndef CUTTLEFISH_GFX_DEFINED
 #define CUTTLEFISH_GFX_DEFINED
 
 #include <stdint.h>
-#include <stdlib.h>
-#include <string.h>
+#include <cstdlib>
+#include <cstring>
+#include <new>  // std::nothrow for canvas buffer allocation
 
 // ── Panel-ops interface ────────────────────────────────────────────────────
 // Each native adapter fills a CuttlefishPanelOps with function pointers that
@@ -121,7 +125,7 @@ class CuttlefishGFX {
   // Text
   virtual void drawChar(int16_t x, int16_t y, unsigned char c, uint16_t color, uint16_t bg, uint8_t size);
   virtual void write(uint8_t c);
-  void print(const char* s) { while (*s) write((uint8_t)*s++); }
+  void print(const char* s) { while (*s) write(static_cast<uint8_t>(*s++)); }
   void setCursor(int16_t x, int16_t y) { cursor_x_ = x; cursor_y_ = y; }
   void setTextColor(uint16_t c) { textcolor_ = c; }
   void setTextColor(uint16_t c, uint16_t bg) { textcolor_ = c; textbgcolor_ = bg; }
@@ -153,9 +157,18 @@ class CuttlefishGFX {
 // display_deleteCanvas (the runtime reuses persistent canvas slots — see
 // AGENTS.md: __ui_container_canvas, __ui_repair_canvas, __ui_list_canvas,
 // __ui_node_canvas).
-class CuttlefishCanvas16 : public CuttlefishGFX {
+class CuttlefishCanvas16 final : public CuttlefishGFX {
  public:
+  // Noncopyable (owns a heap buffer; a value-copy would double-free).
+  CuttlefishCanvas16(const CuttlefishCanvas16&) = delete;
+  CuttlefishCanvas16& operator=(const CuttlefishCanvas16&) = delete;
+  // Owns its buffer: mallocs w*h*2 bytes and frees it in the dtor.
   CuttlefishCanvas16(int16_t w, int16_t h);
+  // Adopts an externally-allocated buffer (e.g. PSRAM via display_createCanvasPsram).
+  // If takeOwnership is true, the dtor frees the buffer with free() (works for both
+  // SRAM malloc and the ESP unified heap, which includes PSRAM). If false, the
+  // caller owns the buffer's lifetime.
+  CuttlefishCanvas16(int16_t w, int16_t h, uint16_t* externalBuffer, uint8_t takeOwnership = 0);
   virtual ~CuttlefishCanvas16();
   virtual void drawPixel(int16_t x, int16_t y, uint16_t color);
   virtual void fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
@@ -174,13 +187,16 @@ class CuttlefishCanvas16 : public CuttlefishGFX {
  private:
   uint16_t* buffer_;
   int16_t canvas_w_, canvas_h_;
+  uint8_t owns_buffer_;  // 1 = dtor frees buffer_ (malloc'd), 0 = externally owned
 };
 
 // ── 1-bit mono canvas (SSD1309/SSD1680 backing stores) ──────────────────────
 // Mirrors Adafruit_GFXcanvasMono. (w+7)/8 bytes per row. The buffer is the
 // panel backing store on SSD1309 — flush via display_partial_refresh.
-class CuttlefishCanvasMono : public CuttlefishGFX {
+class CuttlefishCanvasMono final : public CuttlefishGFX {
  public:
+  CuttlefishCanvasMono(const CuttlefishCanvasMono&) = delete;
+  CuttlefishCanvasMono& operator=(const CuttlefishCanvasMono&) = delete;
   CuttlefishCanvasMono(int16_t w, int16_t h);
   virtual ~CuttlefishCanvasMono();
   virtual void drawPixel(int16_t x, int16_t y, uint16_t color);
@@ -373,8 +389,8 @@ void CuttlefishGFX::fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1,
     if (a > b) { int16_t t = a; a = b; b = t; }
     drawFastHLine(a, y, b - a + 1, color);
   }
-  sa = (int32_t)dx12 * (last - y1);
-  sb = (int32_t)dx02 * (last - y0);
+  sa = static_cast<int32_t>(dx12) * (last - y1);
+  sb = static_cast<int32_t>(dx02) * (last - y0);
   for (; y <= y2; y++) {
     a = x1 + sa / dy12;
     b = x0 + sb / dy02;
@@ -392,7 +408,7 @@ void CuttlefishGFX::drawRGBBitmap(int16_t x, int16_t y, const uint16_t* bitmap,
   if (!bitmap || w <= 0 || h <= 0) return;
   for (int16_t j = 0; j < h; j++) {
     for (int16_t i = 0; i < w; i++) {
-      drawPixel(x + i, y + j, bitmap[(int32_t)j * w + i]);
+      drawPixel(x + i, y + j, bitmap[static_cast<int32_t>(j) * w + i]);
     }
   }
 }
@@ -406,7 +422,7 @@ void CuttlefishGFX::drawChar(int16_t x, int16_t y, unsigned char c, uint16_t col
     return;
   if (c >= 176) c++; // Adafruit '±' fixup
   for (int8_t i = 0; i < 5; i++) {
-    uint8_t line = cuttlefish_glcdfont[(size_t)c * 5 + i];
+    uint8_t line = cuttlefish_glcdfont[static_cast<size_t>(c) * 5 + i];
     for (int8_t j = 0; j < 8; j++, line >>= 1) {
       if (line & 1) {
         if (size == 1) drawPixel(x + i, y + j, color);
@@ -442,22 +458,36 @@ void CuttlefishGFX::write(uint8_t c) {
 
 CuttlefishCanvas16::CuttlefishCanvas16(int16_t w, int16_t h)
   : CuttlefishGFX(nullptr, nullptr),
-    buffer_(nullptr), canvas_w_(w), canvas_h_(h) {
+    buffer_(nullptr), canvas_w_(w), canvas_h_(h), owns_buffer_(1) {
   if ((w > 0) && (h > 0)) {
-    size_t bytes = (size_t)w * (size_t)h * sizeof(uint16_t);
-    buffer_ = (uint16_t*)malloc(bytes);
+    size_t bytes = static_cast<size_t>(w) * static_cast<size_t>(h) * sizeof(uint16_t);
+    // malloc (not new): on targets with CONFIG_REQUIRES_FULL_LIBCPP but without
+    // CONFIG_CPP_EXCEPTIONS, operator new throws std::bad_alloc on OOM and the
+    // nothrow wrapper's internal catch can't unwind → std::terminate → abort.
+    // malloc returns NULL on failure with no exception path, which is exactly
+    // what the canvas-failure self-heal logic expects.
+    buffer_ = static_cast<uint16_t*>(malloc(bytes));
     if (buffer_) memset(buffer_, 0, bytes);
   }
 }
 
+CuttlefishCanvas16::CuttlefishCanvas16(int16_t w, int16_t h, uint16_t* externalBuffer, uint8_t takeOwnership)
+  : CuttlefishGFX(nullptr, nullptr),
+    buffer_(externalBuffer), canvas_w_(w), canvas_h_(h), owns_buffer_(takeOwnership) {
+  // Zero the buffer so the canvas starts clean whether or not we own it.
+  if (externalBuffer && (w > 0) && (h > 0)) {
+    memset(externalBuffer, 0, static_cast<size_t>(w) * static_cast<size_t>(h) * sizeof(uint16_t));
+  }
+}
+
 CuttlefishCanvas16::~CuttlefishCanvas16() {
-  if (buffer_) free(buffer_);
+  if (buffer_ && owns_buffer_) free(buffer_);
 }
 
 void CuttlefishCanvas16::drawPixel(int16_t x, int16_t y, uint16_t color) {
   if (!buffer_) return;
   if ((x < 0) || (y < 0) || (x >= canvas_w_) || (y >= canvas_h_)) return;
-  buffer_[(size_t)y * (size_t)canvas_w_ + (size_t)x] = color;
+  buffer_[static_cast<size_t>(y) * static_cast<size_t>(canvas_w_) + static_cast<size_t>(x)] = color;
 }
 
 void CuttlefishCanvas16::fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color) {
@@ -469,23 +499,23 @@ void CuttlefishCanvas16::fillRect(int16_t x, int16_t y, int16_t w, int16_t h, ui
   // Cull before the inner loop (AGENTS.md: clip before expensive work).
   if (x2 <= x1 || y2 <= y1) return;
   for (int16_t j = y1; j < y2; j++) {
-    uint16_t* row = buffer_ + (size_t)j * (size_t)canvas_w_;
+    uint16_t* row = buffer_ + static_cast<size_t>(j) * static_cast<size_t>(canvas_w_);
     for (int16_t i = x1; i < x2; i++) row[i] = color;
   }
 }
 
 uint16_t CuttlefishCanvas16::getPixel(int16_t x, int16_t y) const {
   if (!buffer_ || (x < 0) || (y < 0) || (x >= canvas_w_) || (y >= canvas_h_)) return 0;
-  return buffer_[(size_t)y * (size_t)canvas_w_ + (size_t)x];
+  return buffer_[static_cast<size_t>(y) * static_cast<size_t>(canvas_w_) + static_cast<size_t>(x)];
 }
 
 CuttlefishCanvasMono::CuttlefishCanvasMono(int16_t w, int16_t h)
   : CuttlefishGFX(nullptr, nullptr),
     buffer_(nullptr), canvas_w_(w), canvas_h_(h) {
   if ((w > 0) && (h > 0)) {
-    size_t row_bytes = ((size_t)w + 7u) / 8u;
-    size_t bytes = row_bytes * (size_t)h;
-    buffer_ = (uint8_t*)malloc(bytes);
+    size_t row_bytes = (static_cast<size_t>(w) + 7u) / 8u;
+    size_t bytes = row_bytes * static_cast<size_t>(h);
+    buffer_ = static_cast<uint8_t*>(malloc(bytes));
     if (buffer_) memset(buffer_, 0, bytes);
   }
 }
@@ -497,8 +527,8 @@ CuttlefishCanvasMono::~CuttlefishCanvasMono() {
 void CuttlefishCanvasMono::drawPixel(int16_t x, int16_t y, uint16_t color) {
   if (!buffer_) return;
   if ((x < 0) || (y < 0) || (x >= canvas_w_) || (y >= canvas_h_)) return;
-  size_t row_bytes = ((size_t)canvas_w_ + 7u) / 8u;
-  uint8_t* row = buffer_ + (size_t)y * row_bytes;
+  size_t row_bytes = (static_cast<size_t>(canvas_w_) + 7u) / 8u;
+  uint8_t* row = buffer_ + static_cast<size_t>(y) * row_bytes;
   uint8_t mask = 0x80u >> (x & 7);
   if (color) row[x >> 3] |= mask;
   else       row[x >> 3] &= ~mask;
@@ -514,8 +544,8 @@ void CuttlefishCanvasMono::fillRect(int16_t x, int16_t y, int16_t w, int16_t h,
   uint8_t fill = color ? 0xFFu : 0x00u;
   for (int16_t j = y1; j < y2; j++) {
     for (int16_t i = x1; i < x2; i++) {
-      size_t row_bytes = ((size_t)canvas_w_ + 7u) / 8u;
-      uint8_t* row = buffer_ + (size_t)j * row_bytes;
+      size_t row_bytes = (static_cast<size_t>(canvas_w_) + 7u) / 8u;
+      uint8_t* row = buffer_ + static_cast<size_t>(j) * row_bytes;
       uint8_t mask = 0x80u >> (i & 7);
       if (color) row[i >> 3] |= mask;
       else       row[i >> 3] &= ~mask;
@@ -526,8 +556,8 @@ void CuttlefishCanvasMono::fillRect(int16_t x, int16_t y, int16_t w, int16_t h,
 
 uint16_t CuttlefishCanvasMono::getPixel(int16_t x, int16_t y) const {
   if (!buffer_ || (x < 0) || (y < 0) || (x >= canvas_w_) || (y >= canvas_h_)) return 0;
-  size_t row_bytes = ((size_t)canvas_w_ + 7u) / 8u;
-  const uint8_t* row = buffer_ + (size_t)y * row_bytes;
+  size_t row_bytes = (static_cast<size_t>(canvas_w_) + 7u) / 8u;
+  const uint8_t* row = buffer_ + static_cast<size_t>(y) * row_bytes;
   return (row[x >> 3] & (0x80u >> (x & 7))) ? 0xFFFFu : 0x0000u;
 }
 

package/src/ui-engine/runtime-header/dirty-scroll-mutators.ts

@@ -64,7 +64,10 @@ static inline void ui_mark_subtree_dirty_local(uint16_t scrollNode) {
 
 // Mode C strip-only: direct-partial scroll when no viewport canvas fits and the
 // scroll delta is small. Fills only the exposed strip on the display, then marks
-// visible descendants dirty for direct draw — never clears the whole viewport.
+// only the descendants that intersect that strip dirty for direct draw — mirroring
+// the Mode B canvas repair path. Never clears the whole viewport, and never marks
+// the whole subtree dirty (AGENTS.md: keep scroll drag invalidation small — a
+// 1-pixel drag must not repaint every visible child).
 static inline void ui_scroll_direct_prepare(uint16_t s, int16_t* outVX, int16_t* outVY) {
   int16_t vw = __ui_nodes[s].box.w;
   int16_t vh = __ui_nodes[s].box.h;
@@ -73,18 +76,31 @@ static inline void ui_scroll_direct_prepare(uint16_t s, int16_t* outVX, int16_t*
   UI_COLOR_T scrollBg = __ui_nodes[s].hasBg ? __ui_nodes[s].bg : __ui_nodes[s].clearColor;
   int16_t deltaY = __ui_nodes[s].scrollY - __ui_nodes[s].lastPaintedScrollY;
   int16_t absDelta = deltaY < 0 ? -deltaY : deltaY;
-  int16_t stripY = deltaY > 0 ? (int16_t)(vh - absDelta) : 0;
-  ui_display_fill_rect(vox, (int16_t)(voy + stripY), vw, absDelta, scrollBg);
+  int16_t stripY = deltaY > 0 ? static_cast<int16_t>(vh - absDelta) : 0;
+  ui_display_fill_rect(vox, static_cast<int16_t>(voy + stripY), vw, absDelta, scrollBg);
+  // Only descendants whose paint rect intersects the exposed strip need
+  // repainting; the rest keep their last-painted pixels (the strip background
+  // fill already covered the vacated band). Clear stale dirty flags on the
+  // others so a flag set by a prior frame (or a sibling promotion) doesn't
+  // trigger a needless repaint.
+  UIRect exposed = { vox, static_cast<int16_t>(voy + stripY), vw, absDelta };
   for (uint16_t c = s + 1; c < __ui_nodes[s].subtreeEnd; c++) {
     if (!ui_is_effectively_visible(c) || __ui_nodes[c].screenId != __ui_active_screen) {
       __ui_nodes[c].dirty = 0;
       continue;
     }
-    __ui_nodes[c].dirty = 1;
-    if (__ui_nodes[c].kind == NODE_PROGRESS || __ui_nodes[c].kind == NODE_RANGE) {
-      __ui_nodes[c].lastTextWidth = -1;
+    UIRect cr;
+    ui_node_current_paint_rect(c, &cr);
+    if (cr.w > 0 && cr.h > 0 &&
+        ui_rects_intersect(cr.x, cr.y, cr.w, cr.h, exposed.x, exposed.y, exposed.w, exposed.h)) {
+      __ui_nodes[c].dirty = 1;
+      if (__ui_nodes[c].kind == NODE_PROGRESS || __ui_nodes[c].kind == NODE_RANGE) {
+        __ui_nodes[c].lastTextWidth = -1;
+      }
+      __ui_nodes[c].lastTextHeight = 0;
+    } else {
+      __ui_nodes[c].dirty = 0;
     }
-    __ui_nodes[c].lastTextHeight = 0;
   }
   __ui_nodes[s].dirty = 0;
   if (outVX) *outVX = vox;
@@ -96,13 +112,13 @@ static inline int16_t ui_overflow_scroll_compositor(uint16_t nodeIdx) {
   if (nodeIdx >= __ui_node_count) return -1;
   if (__ui_nodes[nodeIdx].scrollable && !__ui_nodes[nodeIdx].virtualized &&
       __ui_nodes[nodeIdx].contentHeight > __ui_nodes[nodeIdx].box.h) {
-    return (int16_t)nodeIdx;
+    return static_cast<int16_t>(nodeIdx);
   }
   uint16_t p = __ui_nodes[nodeIdx].parent;
   while (p != UI_NO_PARENT && p < __ui_node_count) {
     if (__ui_nodes[p].scrollable && !__ui_nodes[p].virtualized &&
         __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
-      return (int16_t)p;
+      return static_cast<int16_t>(p);
     }
     p = __ui_nodes[p].parent;
   }
@@ -151,7 +167,7 @@ static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode) {
 static inline int16_t ui_scroll_ancestor_for_node(uint16_t nodeIdx) {
   uint16_t p = __ui_nodes[nodeIdx].parent;
   while (p != UI_NO_PARENT && p < __ui_node_count) {
-    if (__ui_nodes[p].scrollable) return (int16_t)p;
+    if (__ui_nodes[p].scrollable) return static_cast<int16_t>(p);
     p = __ui_nodes[p].parent;
   }
   return -1;

package/src/ui-engine/runtime-header/display-shim.ts

@@ -26,10 +26,10 @@ static inline int16_t ui_clamp_i16(int16_t value, int16_t lo, int16_t hi) {
   return value;
 }
 static inline void ui_display_target_bounds(int16_t* left, int16_t* top, int16_t* right, int16_t* bottom) {
-  if (left) *left = (int16_t)(-__ui_draw_off_x);
-  if (top) *top = (int16_t)(-__ui_draw_off_y);
-  if (right) *right = (int16_t)(ui_display_target_width() - __ui_draw_off_x);
-  if (bottom) *bottom = (int16_t)(ui_display_target_height() - __ui_draw_off_y);
+  if (left) *left = static_cast<int16_t>(-__ui_draw_off_x);
+  if (top) *top = static_cast<int16_t>(-__ui_draw_off_y);
+  if (right) *right = static_cast<int16_t>(ui_display_target_width() - __ui_draw_off_x);
+  if (bottom) *bottom = static_cast<int16_t>(ui_display_target_height() - __ui_draw_off_y);
 }
 static inline uint8_t ui_clip_rect_to_display_target(int16_t* x, int16_t* y, int16_t* w, int16_t* h) {
   if (!x || !y || !w || !h || *w <= 0 || *h <= 0) return 0;
@@ -37,15 +37,15 @@ static inline uint8_t ui_clip_rect_to_display_target(int16_t* x, int16_t* y, int
   ui_display_target_bounds(&left, &top, &right, &bottom);
   int16_t x0 = *x > left ? *x : left;
   int16_t y0 = *y > top ? *y : top;
-  int16_t x1 = (int16_t)(*x + *w);
-  int16_t y1 = (int16_t)(*y + *h);
+  int16_t x1 = static_cast<int16_t>(*x + *w);
+  int16_t y1 = static_cast<int16_t>(*y + *h);
   if (x1 > right) x1 = right;
   if (y1 > bottom) y1 = bottom;
   if (x0 >= x1 || y0 >= y1) return 0;
   *x = x0;
   *y = y0;
-  *w = (int16_t)(x1 - x0);
-  *h = (int16_t)(y1 - y0);
+  *w = static_cast<int16_t>(x1 - x0);
+  *h = static_cast<int16_t>(y1 - y0);
   return 1;
 }
 static inline void ui_display_draw_pixel(int16_t x, int16_t y, UI_COLOR_T color) {

package/src/ui-engine/runtime-header/forward-decls.ts

@@ -1,6 +1,12 @@
 // Slice of the C++ runtime header (original source lines 622-752).
 // navigate, canvas/scroll/text/paint/clip/AA/image forward declarations, persistent canvas globals.
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+//
+// EMIT BOUNDARY: This file is the structural head of the UI runtime header
+// surface (C) — every partial emitter in this directory produces bytes that are
+// assembled into the C++ header inlined into user sketches. The emitted bytes
+// are covered by the TypeCAD Runtime Exception (see RUNTIME_EXCEPTION.md at the
+// repository root) and are not subject to the license of this tool source.
 export function emitForwardDecls(): string {
   return `
 // Early forward declaration: ui_navigate (below) calls ui_release_canvas_state
@@ -9,9 +15,17 @@ export function emitForwardDecls(): string {
 static inline void ui_release_canvas_state();
 static inline void ui_set_pressed(uint16_t nodeIdx, uint8_t pressed);
 static inline void ui_refresh_active_screen_bg_node();
+static inline CuttlefishCanvas16* ui_get_framebuffer();
+// Set when the next frame must be composed from the active screen background;
+// declared before ui_navigate because navigation can request that composition.
+static uint8_t __ui_fb_needs_compose = 1;
 
 // Navigate to a screen by index. Marks the new screen's nodes dirty, releases
-// persistent canvas state, and optionally clears the display.
+// persistent canvas state, and requests a complete off-screen composition when
+// the full-frame path is available. The physical panel is never cleared here on
+// that path: navigation must not expose an intermediate frame while the next
+// frame is built. Without a full-frame buffer, the fallback remains best-effort;
+// no-TE TFT hardware cannot provide a strict tear-free guarantee.
 static inline void ui_navigate(uint8_t screenIdx) {
   if (screenIdx >= __ui_screen_count || screenIdx == __ui_active_screen) return;
   __ui_active_screen = screenIdx;
@@ -23,7 +37,7 @@ static inline void ui_navigate(uint8_t screenIdx) {
   // and the button would stay stuck in its :pressed color.
   if (__ui_touch_node >= 0 && __ui_touch_node < __ui_node_count &&
       __ui_nodes[__ui_touch_node].kind == NODE_BUTTON && __ui_nodes[__ui_touch_node].value != 0) {
-    ui_set_pressed((uint16_t)__ui_touch_node, 0);
+    ui_set_pressed(static_cast<uint16_t>(__ui_touch_node), 0);
   }
   __ui_scroll_node = -1;
   __ui_touch_node = -1;
@@ -34,17 +48,34 @@ static inline void ui_navigate(uint8_t screenIdx) {
   // resident and fragments the heap, so the new screen's buffer can't get a
   // contiguous block (the "works first, then blanks until reset" symptom).
   ui_release_canvas_state();
-  // Clear the entire display so old screen content doesn't show. On deferred-
-  // refresh panels (e-ink) a full clear flashes, so skip it — the all-nodes-
-  // dirty marking below drives a full repaint via partial refresh instead.
+  // A framebuffer-capable target keeps the old frame visible until the new one
+  // is complete. Targets without enough memory retain the legacy clear fallback
+  // so stale pixels from the old screen cannot remain; this constrained path is
+  // best-effort because the panel has no TE/vblank synchronization.
+  if (ui_get_framebuffer()) {
+    __ui_fb_needs_compose = 1;
+  } else {
 #ifndef UI_REFRESH_DEFERRED
-  display_fillScreen(0x0000);
+    UI_COLOR_T navBg = (UI_COLOR_T)0;
+    if (__ui_active_screen_bg_node < __ui_node_count) {
+      navBg = __ui_nodes[__ui_active_screen_bg_node].hasBg
+        ? __ui_nodes[__ui_active_screen_bg_node].bg
+        : __ui_nodes[__ui_active_screen_bg_node].clearColor;
+    }
+    display_fillScreen(navBg);
 #endif
+  }
   // Mark all nodes dirty so the new screen fully redraws.
   for (uint16_t i = 0; i < __ui_node_count; i++) {
     __ui_nodes[i].dirty = 1;
     __ui_nodes[i].lastTextHeight = 0;
     __ui_nodes[i].layoutCacheKey = 0;
+    if (__ui_nodes[i].scrollable) {
+      // The next screen needs a complete scroll-canvas seed; subsequent local
+      // child updates can use retained-canvas repairs.
+      __ui_nodes[i].lastPaintedScrollY = static_cast<int16_t>(
+        __ui_nodes[i].scrollY - (__ui_nodes[i].box.h > 0 ? __ui_nodes[i].box.h : 1));
+    }
     if (__ui_nodes[i].kind == NODE_PROGRESS || __ui_nodes[i].kind == NODE_RANGE) __ui_nodes[i].lastTextWidth = -1;
     else __ui_nodes[i].lastTextWidth = 0;
   }
@@ -77,6 +108,7 @@ static inline uint8_t ui_subtree_current_paint_rect(uint16_t nodeIdx, UIRect* ou
 static inline void ui_mark_overlapping_higher_layers_dirty(uint16_t nodeIdx);
 static inline void ui_mark_overlapping_higher_layers_dirty_for_rect(uint16_t nodeIdx, const UIRect* r);
 static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode);
+static inline UI_COLOR_T ui_parent_clear_color(uint16_t nodeIdx);
 static inline void ui_release_canvas_state();
 static inline void ui_set_visible(uint16_t nodeIdx, uint8_t visible);
 static inline void ui_invalidate_scroll_canvas_for_node(uint16_t nodeIdx);
@@ -101,6 +133,11 @@ static inline void ui_aa_fill_circle(CuttlefishCanvas16* c, int16_t cx, int16_t
 static inline uint8_t ui_repair_current_node_paint_with_parent(uint16_t nodeIdx, UIRect* r);
 static inline void ui_clear_node_paint_rect(uint16_t nodeIdx, const UIRect* paintRect);
 static inline uint8_t ui_try_repair_geometry_fill(uint16_t nodeIdx, const UIRect* oldRect);
+// Band renderers (defined in node-draw-body; forward-declared so the NODE_LIST
+// case can fall back to ui_render_list_bands before its definition site).
+static inline uint8_t ui_render_node_bands(uint16_t nodeIdx, int16_t prX, int16_t prY, int16_t prW, int16_t prH);
+static inline uint8_t ui_render_list_bands(uint16_t i);
+static inline uint8_t ui_render_list_direct(uint16_t i);
 static inline void ui_draw_node_border(uint16_t i, int16_t drawX, int16_t drawY, UI_COLOR_T color);
 static inline void ui_draw_node_outline(uint16_t i, int16_t drawX, int16_t drawY);
 static inline void ui_draw_gradient_fill(uint16_t i, int16_t drawY);
@@ -114,6 +151,10 @@ static inline void ui_draw_scaled_image(const UIImage* img, int16_t x, int16_t y
                                          int16_t drawW, int16_t drawH);
 
 static CuttlefishDisplayTarget* __ui_gfx = display_defaultTarget();
+// Full-frame composition is required for the first frame and after navigation.
+// Once composed, subsequent dirty updates can safely modify the retained
+// framebuffer without rebuilding unchanged nodes. The flags are declared
+// before ui_navigate above because navigation sets the compose request.
 // Persistent canvas slots, all freed on screen change (ui_navigate) so each
 // screen starts with a clean heap. Without this, the first screen's canvas
 // buffer stays resident and fragments the heap, so a later screen's buffer
@@ -125,6 +166,7 @@ static CuttlefishCanvas16* __ui_list_canvas = nullptr;       // virtualized <lis
 static int16_t __ui_list_canvas_node = -1;                   // node currently represented by __ui_list_canvas
 static CuttlefishCanvas16* __ui_node_canvas = nullptr;       // <canvas> element offscreen
 static CuttlefishCanvas16* __ui_repair_canvas = nullptr;     // buffered-paint / exposed-strip
+static CuttlefishCanvas16* __ui_band_canvas = nullptr;       // band renderer (no-PSRAM scroll)
 static CuttlefishCanvas16* __ui_kb_canvas = nullptr;         // on-screen keyboard overlay
 static int16_t __ui_canvas_fallback_w = 0;                   // dimensions for direct <canvas> fallback
 static int16_t __ui_canvas_fallback_h = 0;