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

package/src/ui-engine/runtime-header/image-drawing.ts

@@ -3,12 +3,54 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitImageDrawing(): string {
   return `
-// ── Full-screen framebuffer (opt-in PSRAM perf experiment) ───────────────────
-// Disabled by default: pushing a full 320×240 frame for a tiny dirty button can
-// look like a global brightness flash on SPI TFTs. Enable only when a target
-// has enough PSRAM and a full-frame repaint is preferable to partial updates.
+// ── Full-screen framebuffer (opt-in PSRAM composition path) ──────────────────
+// Composes a complete frame off-screen so navigation and dirty-node updates do
+// not expose intermediate clears/primitive writes. The panel still receives a
+// sequential SPI transfer; without a TE/vblank signal this is a strong tearing
+// reduction, not a strict hardware-level tear-free guarantee.
 static CuttlefishCanvas16* __ui_fb = nullptr;
 static uint8_t __ui_fb_tried = 0;  // 0 = not yet attempted, 1 = alloc attempted
+// Dirty bounds for the retained framebuffer. A local touch update should not
+// retransmit the entire panel: the full-frame burst is long enough to look like
+// a brightness dip on SPI TFTs even though the framebuffer itself is coherent.
+static uint8_t __ui_fb_dirty = 0;
+static int16_t __ui_fb_dirty_x0 = 0;
+static int16_t __ui_fb_dirty_y0 = 0;
+static int16_t __ui_fb_dirty_x1 = 0;
+static int16_t __ui_fb_dirty_y1 = 0;
+
+static inline void ui_fb_begin_frame() {
+  __ui_fb_dirty = 0;
+  __ui_fb_dirty_x0 = display_width();
+  __ui_fb_dirty_y0 = display_height();
+  __ui_fb_dirty_x1 = 0;
+  __ui_fb_dirty_y1 = 0;
+}
+
+static inline void ui_fb_add_rect(int16_t x, int16_t y, int16_t w, int16_t h) {
+  if (w <= 0 || h <= 0) return;
+  int16_t x0 = x < 0 ? 0 : x;
+  int16_t y0 = y < 0 ? 0 : y;
+  int16_t x1 = x + w;
+  int16_t y1 = y + h;
+  int16_t dw = display_width();
+  int16_t dh = display_height();
+  if (x1 > dw) x1 = dw;
+  if (y1 > dh) y1 = dh;
+  if (x0 >= x1 || y0 >= y1) return;
+  if (!__ui_fb_dirty) {
+    __ui_fb_dirty_x0 = x0;
+    __ui_fb_dirty_y0 = y0;
+    __ui_fb_dirty_x1 = x1;
+    __ui_fb_dirty_y1 = y1;
+    __ui_fb_dirty = 1;
+    return;
+  }
+  if (x0 < __ui_fb_dirty_x0) __ui_fb_dirty_x0 = x0;
+  if (y0 < __ui_fb_dirty_y0) __ui_fb_dirty_y0 = y0;
+  if (x1 > __ui_fb_dirty_x1) __ui_fb_dirty_x1 = x1;
+  if (y1 > __ui_fb_dirty_y1) __ui_fb_dirty_y1 = y1;
+}
 
 // Get the framebuffer, allocating once (in PSRAM when available). Returns null
 // when PSRAM is absent or the allocation failed — callers fall back to direct.
@@ -31,14 +73,42 @@ static inline CuttlefishCanvas16* ui_get_framebuffer() {
   return __ui_fb;
 }
 
-// Push the entire framebuffer to the display in one bulk SPI transaction.
+// Push only the changed framebuffer bounds. Rows are sent separately when the
+// dirty union is narrower than the framebuffer because the source canvas has a
+// wider stride than the panel window. Each row is complete before it reaches
+// the panel, and the display adapter can synchronize each window to scanline.
 static inline void ui_push_framebuffer() {
-  if (!__ui_fb || !display_canvasBuffer(__ui_fb)) return;
-  int16_t w = display_canvasWidth(__ui_fb);
-  int16_t h = display_canvasHeight(__ui_fb);
+  if (!__ui_fb || !display_canvasBuffer(__ui_fb) || !__ui_fb_dirty) return;
+  int16_t fw = display_canvasWidth(__ui_fb);
+  int16_t fh = display_canvasHeight(__ui_fb);
+  int16_t x = __ui_fb_dirty_x0;
+  int16_t y = __ui_fb_dirty_y0;
+  int16_t w = static_cast<int16_t>(__ui_fb_dirty_x1 - x);
+  int16_t h = static_cast<int16_t>(__ui_fb_dirty_y1 - y);
+  if (x < 0 || y < 0 || w <= 0 || h <= 0 || x >= fw || y >= fh) return;
+  if (x + w > fw) w = static_cast<int16_t>(fw - x);
+  if (y + h > fh) h = static_cast<int16_t>(fh - y);
+  // Use the panel's native bulk-pixel path, not drawRGBBitmap(). The native
+  // CuttlefishGFX implementation of drawRGBBitmap is intentionally generic and
+  // emits one writePixel transaction per pixel; using it for a retained-frame
+  // flush turns a small local update into hundreds of visible SPI flashes.
+  UI_COLOR_T* pixels = display_canvasBuffer(__ui_fb);
   display_startWrite();
-  display_setAddrWindow(0, 0, w, h);
-  display_writePixels(display_canvasBuffer(__ui_fb), (uint32_t)w * h);
+  if (x == 0 && w == fw) {
+    // Full-width rows are contiguous and can use one bulk write.
+    display_setAddrWindow(x, y, w, h);
+    display_writePixels(pixels + static_cast<int32_t>(y) * fw,
+      static_cast<uint32_t>(w) * h);
+  } else {
+    // Narrow dirty bounds require one row at a time because the source stride
+    // is fw while each destination window is only w pixels wide.
+    for (int16_t row = 0; row < h; row++) {
+      display_setAddrWindow(x, static_cast<int16_t>(y + row), w, 1);
+      display_writePixels(
+        pixels + static_cast<int32_t>(y + row) * fw + x,
+        static_cast<uint32_t>(w));
+    }
+  }
   display_endWrite();
 }
 
@@ -82,8 +152,8 @@ static inline void ui_draw_image_with_fit(const UIImage* img, int16_t x, int16_t
     offX = 0;
     offY = 0;
   } else if (fitMode == 2 || fitMode == 3 || fitMode == 4) {
-    int32_t scaleX = ((int32_t)targetW * 1000) / srcW;
-    int32_t scaleY = ((int32_t)targetH * 1000) / srcH;
+    int32_t scaleX = (static_cast<int32_t>(targetW) * 1000) / srcW;
+    int32_t scaleY = (static_cast<int32_t>(targetH) * 1000) / srcH;
     if (scaleX < 1) scaleX = 1;
     if (scaleY < 1) scaleY = 1;
     int32_t scale = scaleX;
@@ -95,8 +165,8 @@ static inline void ui_draw_image_with_fit(const UIImage* img, int16_t x, int16_t
       if (scaleY < scaleX) scale = scaleY;
       if (scale > 1000) scale = 1000;
     }
-    drawW = (int16_t)((int32_t)srcW * scale / 1000);
-    drawH = (int16_t)((int32_t)srcH * scale / 1000);
+    drawW = static_cast<int16_t>(static_cast<int32_t>(srcW) * scale / 1000);
+    drawH = static_cast<int16_t>(static_cast<int32_t>(srcH) * scale / 1000);
     if (drawW < 1) drawW = 1;
     if (drawH < 1) drawH = 1;
     if (fitMode == 3) {
@@ -115,40 +185,40 @@ static inline void ui_draw_image_with_fit(const UIImage* img, int16_t x, int16_t
   if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
   int16_t txStart = 0, txEnd = targetW, tyStart = 0, tyEnd = targetH;
   if (q == 0) {
-    txStart = ui_clamp_i16((int16_t)(clipX - x), 0, targetW);
-    txEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, targetW);
-    tyStart = ui_clamp_i16((int16_t)(clipY - y), 0, targetH);
-    tyEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, targetH);
+    txStart = ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, targetW);
+    txEnd = ui_clamp_i16(static_cast<int16_t>(clipX + clipW - x), 0, targetW);
+    tyStart = ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, targetH);
+    tyEnd = ui_clamp_i16(static_cast<int16_t>(clipY + clipH - y), 0, targetH);
   } else if (q == 1) {
-    txStart = ui_clamp_i16((int16_t)(clipY - y), 0, targetW);
-    txEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, targetW);
-    tyStart = ui_clamp_i16((int16_t)(x + targetH - (clipX + clipW)), 0, targetH);
-    tyEnd = ui_clamp_i16((int16_t)(x + targetH - clipX), 0, targetH);
+    txStart = ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, targetW);
+    txEnd = ui_clamp_i16(static_cast<int16_t>(clipY + clipH - y), 0, targetW);
+    tyStart = ui_clamp_i16(static_cast<int16_t>(x + targetH - (clipX + clipW)), 0, targetH);
+    tyEnd = ui_clamp_i16(static_cast<int16_t>(x + targetH - clipX), 0, targetH);
   } else if (q == 2) {
-    txStart = ui_clamp_i16((int16_t)(x + targetW - (clipX + clipW)), 0, targetW);
-    txEnd = ui_clamp_i16((int16_t)(x + targetW - clipX), 0, targetW);
-    tyStart = ui_clamp_i16((int16_t)(y + targetH - (clipY + clipH)), 0, targetH);
-    tyEnd = ui_clamp_i16((int16_t)(y + targetH - clipY), 0, targetH);
+    txStart = ui_clamp_i16(static_cast<int16_t>(x + targetW - (clipX + clipW)), 0, targetW);
+    txEnd = ui_clamp_i16(static_cast<int16_t>(x + targetW - clipX), 0, targetW);
+    tyStart = ui_clamp_i16(static_cast<int16_t>(y + targetH - (clipY + clipH)), 0, targetH);
+    tyEnd = ui_clamp_i16(static_cast<int16_t>(y + targetH - clipY), 0, targetH);
   } else {
-    txStart = ui_clamp_i16((int16_t)(y + targetW - (clipY + clipH)), 0, targetW);
-    txEnd = ui_clamp_i16((int16_t)(y + targetW - clipY), 0, targetW);
-    tyStart = ui_clamp_i16((int16_t)(clipX - x), 0, targetH);
-    tyEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, targetH);
+    txStart = ui_clamp_i16(static_cast<int16_t>(y + targetW - (clipY + clipH)), 0, targetW);
+    txEnd = ui_clamp_i16(static_cast<int16_t>(y + targetW - clipY), 0, targetW);
+    tyStart = ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, targetH);
+    tyEnd = ui_clamp_i16(static_cast<int16_t>(clipX + clipW - x), 0, targetH);
   }
   if (txStart >= txEnd || tyStart >= tyEnd) return;
   for (int16_t ty = tyStart; ty < tyEnd; ty++) {
     int16_t localY = ty - offY;
     if (localY < 0 || localY >= drawH) continue;
-    int16_t srcY = ((int32_t)localY * srcH) / drawH;
+    int16_t srcY = (static_cast<int32_t>(localY) * srcH) / drawH;
     if (srcY < 0) srcY = 0;
     if (srcY >= srcH) srcY = srcH - 1;
     for (int16_t tx = txStart; tx < txEnd; tx++) {
       int16_t localX = tx - offX;
       if (localX < 0 || localX >= drawW) continue;
-      int16_t srcX = ((int32_t)localX * srcW) / drawW;
+      int16_t srcX = (static_cast<int32_t>(localX) * srcW) / drawW;
       if (srcX < 0) srcX = 0;
       if (srcX >= srcW) srcX = srcW - 1;
-      UI_COLOR_T color = img->data[(int32_t)srcY * srcW + srcX];
+      UI_COLOR_T color = img->data[static_cast<int32_t>(srcY) * srcW + srcX];
       int16_t dx = tx;
       int16_t dy = ty;
       if (q == 1) {
@@ -177,43 +247,43 @@ static inline void ui_draw_scaled_image(const UIImage* img, int16_t x, int16_t y
   if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
   int16_t dxStart = 0, dxEnd = drawW, dyStart = 0, dyEnd = drawH;
   if (q == 0) {
-    dxStart = ui_clamp_i16((int16_t)(clipX - x), 0, drawW);
-    dxEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, drawW);
-    dyStart = ui_clamp_i16((int16_t)(clipY - y), 0, drawH);
-    dyEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, drawH);
+    dxStart = ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, drawW);
+    dxEnd = ui_clamp_i16(static_cast<int16_t>(clipX + clipW - x), 0, drawW);
+    dyStart = ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, drawH);
+    dyEnd = ui_clamp_i16(static_cast<int16_t>(clipY + clipH - y), 0, drawH);
   } else if (q == 1) {
-    dxStart = ui_clamp_i16((int16_t)(clipY - y), 0, drawW);
-    dxEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, drawW);
-    dyStart = ui_clamp_i16((int16_t)(x + drawH - (clipX + clipW)), 0, drawH);
-    dyEnd = ui_clamp_i16((int16_t)(x + drawH - clipX), 0, drawH);
+    dxStart = ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, drawW);
+    dxEnd = ui_clamp_i16(static_cast<int16_t>(clipY + clipH - y), 0, drawW);
+    dyStart = ui_clamp_i16(static_cast<int16_t>(x + drawH - (clipX + clipW)), 0, drawH);
+    dyEnd = ui_clamp_i16(static_cast<int16_t>(x + drawH - clipX), 0, drawH);
   } else if (q == 2) {
-    dxStart = ui_clamp_i16((int16_t)(x + drawW - (clipX + clipW)), 0, drawW);
-    dxEnd = ui_clamp_i16((int16_t)(x + drawW - clipX), 0, drawW);
-    dyStart = ui_clamp_i16((int16_t)(y + drawH - (clipY + clipH)), 0, drawH);
-    dyEnd = ui_clamp_i16((int16_t)(y + drawH - clipY), 0, drawH);
+    dxStart = ui_clamp_i16(static_cast<int16_t>(x + drawW - (clipX + clipW)), 0, drawW);
+    dxEnd = ui_clamp_i16(static_cast<int16_t>(x + drawW - clipX), 0, drawW);
+    dyStart = ui_clamp_i16(static_cast<int16_t>(y + drawH - (clipY + clipH)), 0, drawH);
+    dyEnd = ui_clamp_i16(static_cast<int16_t>(y + drawH - clipY), 0, drawH);
   } else {
-    dxStart = ui_clamp_i16((int16_t)(y + drawW - (clipY + clipH)), 0, drawW);
-    dxEnd = ui_clamp_i16((int16_t)(y + drawW - clipY), 0, drawW);
-    dyStart = ui_clamp_i16((int16_t)(clipX - x), 0, drawH);
-    dyEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, drawH);
+    dxStart = ui_clamp_i16(static_cast<int16_t>(y + drawW - (clipY + clipH)), 0, drawW);
+    dxEnd = ui_clamp_i16(static_cast<int16_t>(y + drawW - clipY), 0, drawW);
+    dyStart = ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, drawH);
+    dyEnd = ui_clamp_i16(static_cast<int16_t>(clipX + clipW - x), 0, drawH);
   }
   if (dxStart >= dxEnd || dyStart >= dyEnd) return;
   if (q == 0) {
     // Simple case: no rotation, draw with scaling
     if (drawW == img->w && drawH == img->h) {
-      int16_t rows = (int16_t)(dyEnd - dyStart);
-      int16_t cols = (int16_t)(dxEnd - dxStart);
+      int16_t rows = static_cast<int16_t>(dyEnd - dyStart);
+      int16_t cols = static_cast<int16_t>(dxEnd - dxStart);
       for (int16_t row = 0; row < rows; row++) {
-        ui_display_draw_rgb_bitmap((int16_t)(x + dxStart), (int16_t)(y + dyStart + row),
-          img->data + (int32_t)(dyStart + row) * img->w + dxStart, cols, 1);
+        ui_display_draw_rgb_bitmap(static_cast<int16_t>(x + dxStart), static_cast<int16_t>(y + dyStart + row),
+          img->data + static_cast<int32_t>(dyStart + row) * img->w + dxStart, cols, 1);
       }
     } else {
       // Scale using nearest-neighbor
       for (int16_t dy = dyStart; dy < dyEnd; dy++) {
-        int16_t srcY = ((int32_t)dy * img->h) / drawH;
+        int16_t srcY = (static_cast<int32_t>(dy) * img->h) / drawH;
         for (int16_t dx = dxStart; dx < dxEnd; dx++) {
-          int16_t srcX = ((int32_t)dx * img->w) / drawW;
-          UI_COLOR_T color = img->data[(int32_t)srcY * img->w + srcX];
+          int16_t srcX = (static_cast<int32_t>(dx) * img->w) / drawW;
+          UI_COLOR_T color = img->data[static_cast<int32_t>(srcY) * img->w + srcX];
           ui_display_draw_pixel(x + dx, y + dy, color);
         }
       }
@@ -221,10 +291,10 @@ static inline void ui_draw_scaled_image(const UIImage* img, int16_t x, int16_t y
     return;
   }
   for (int16_t dy = dyStart; dy < dyEnd; dy++) {
-    int16_t srcY = ((int32_t)dy * img->h) / drawH;
+    int16_t srcY = (static_cast<int32_t>(dy) * img->h) / drawH;
     for (int16_t dx = dxStart; dx < dxEnd; dx++) {
-      int16_t srcX = ((int32_t)dx * img->w) / drawW;
-      UI_COLOR_T color = img->data[(int32_t)srcY * img->w + srcX];
+      int16_t srcX = (static_cast<int32_t>(dx) * img->w) / drawW;
+      UI_COLOR_T color = img->data[static_cast<int32_t>(srcY) * img->w + srcX];
       int16_t rdx = 0, rdy = 0;
       if (q == 1) {
         rdx = drawH - 1 - dy;
@@ -249,48 +319,48 @@ static inline void ui_draw_image_rotated(const UIImage* img, int16_t x, int16_t
    int16_t clipH = (q == 1 || q == 3) ? img->w : img->h;
    if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
    if (q == 0) {
-     int16_t sx0 = ui_clamp_i16((int16_t)(clipX - x), 0, (int16_t)img->w);
-     int16_t sy0 = ui_clamp_i16((int16_t)(clipY - y), 0, (int16_t)img->h);
-     int16_t sw = ui_clamp_i16(clipW, 0, (int16_t)(img->w - sx0));
-     int16_t sh = ui_clamp_i16(clipH, 0, (int16_t)(img->h - sy0));
+     int16_t sx0 = ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, static_cast<int16_t>(img->w));
+     int16_t sy0 = ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, static_cast<int16_t>(img->h));
+     int16_t sw = ui_clamp_i16(clipW, 0, static_cast<int16_t>(img->w - sx0));
+     int16_t sh = ui_clamp_i16(clipH, 0, static_cast<int16_t>(img->h - sy0));
      for (int16_t row = 0; row < sh; row++) {
-       ui_display_draw_rgb_bitmap((int16_t)(x + sx0), (int16_t)(y + sy0 + row),
-         img->data + (int32_t)(sy0 + row) * img->w + sx0, sw, 1);
+       ui_display_draw_rgb_bitmap(static_cast<int16_t>(x + sx0), static_cast<int16_t>(y + sy0 + row),
+         img->data + static_cast<int32_t>(sy0 + row) * img->w + sx0, sw, 1);
      }
      return;
    }
    uint16_t sxStart = 0, sxEnd = img->w, syStart = 0, syEnd = img->h;
    if (q == 1) {
-     sxStart = (uint16_t)ui_clamp_i16((int16_t)(clipY - y), 0, (int16_t)img->w);
-     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(clipY + clipH - y), 0, (int16_t)img->w);
-     syStart = (uint16_t)ui_clamp_i16((int16_t)(x + img->h - (clipX + clipW)), 0, (int16_t)img->h);
-     syEnd = (uint16_t)ui_clamp_i16((int16_t)(x + img->h - clipX), 0, (int16_t)img->h);
+     sxStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(clipY - y), 0, static_cast<int16_t>(img->w)));
+     sxEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(clipY + clipH - y), 0, static_cast<int16_t>(img->w)));
+     syStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(x + img->h - (clipX + clipW)), 0, static_cast<int16_t>(img->h)));
+     syEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(x + img->h - clipX), 0, static_cast<int16_t>(img->h)));
    } else if (q == 2) {
-     sxStart = (uint16_t)ui_clamp_i16((int16_t)(x + img->w - (clipX + clipW)), 0, (int16_t)img->w);
-     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(x + img->w - clipX), 0, (int16_t)img->w);
-     syStart = (uint16_t)ui_clamp_i16((int16_t)(y + img->h - (clipY + clipH)), 0, (int16_t)img->h);
-     syEnd = (uint16_t)ui_clamp_i16((int16_t)(y + img->h - clipY), 0, (int16_t)img->h);
+     sxStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(x + img->w - (clipX + clipW)), 0, static_cast<int16_t>(img->w)));
+     sxEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(x + img->w - clipX), 0, static_cast<int16_t>(img->w)));
+     syStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(y + img->h - (clipY + clipH)), 0, static_cast<int16_t>(img->h)));
+     syEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(y + img->h - clipY), 0, static_cast<int16_t>(img->h)));
    } else {
-     sxStart = (uint16_t)ui_clamp_i16((int16_t)(y + img->w - (clipY + clipH)), 0, (int16_t)img->w);
-     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(y + img->w - clipY), 0, (int16_t)img->w);
-     syStart = (uint16_t)ui_clamp_i16((int16_t)(clipX - x), 0, (int16_t)img->h);
-     syEnd = (uint16_t)ui_clamp_i16((int16_t)(clipX + clipW - x), 0, (int16_t)img->h);
+     sxStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(y + img->w - (clipY + clipH)), 0, static_cast<int16_t>(img->w)));
+     sxEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(y + img->w - clipY), 0, static_cast<int16_t>(img->w)));
+     syStart = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(clipX - x), 0, static_cast<int16_t>(img->h)));
+     syEnd = static_cast<uint16_t>(ui_clamp_i16(static_cast<int16_t>(clipX + clipW - x), 0, static_cast<int16_t>(img->h)));
    }
    if (sxStart >= sxEnd || syStart >= syEnd) return;
    for (uint16_t sy = syStart; sy < syEnd; sy++) {
      for (uint16_t sx = sxStart; sx < sxEnd; sx++) {
-       UI_COLOR_T color = img->data[(uint32_t)sy * img->w + sx];
+       UI_COLOR_T color = img->data[static_cast<uint32_t>(sy) * img->w + sx];
        int16_t dx = 0;
        int16_t dy = 0;
        if (q == 1) {
-         dx = (int16_t)(img->h - 1 - sy);
-         dy = (int16_t)sx;
+         dx = static_cast<int16_t>(img->h - 1 - sy);
+         dy = static_cast<int16_t>(sx);
        } else if (q == 2) {
-         dx = (int16_t)(img->w - 1 - sx);
-         dy = (int16_t)(img->h - 1 - sy);
+         dx = static_cast<int16_t>(img->w - 1 - sx);
+         dy = static_cast<int16_t>(img->h - 1 - sy);
        } else {
-         dx = (int16_t)sy;
-         dy = (int16_t)(img->w - 1 - sx);
+         dx = static_cast<int16_t>(sy);
+         dy = static_cast<int16_t>(img->w - 1 - sx);
        }
        ui_display_draw_pixel(x + dx, y + dy, color);
      }

package/src/ui-engine/runtime-header/init-press-input.ts

@@ -13,15 +13,22 @@ static inline void ui_init(void) {
   // containers start locked until the scroll-container loop proves their
   // canvas fits.
   if (!__ui_scroll_canvas_ok && __ui_node_count > 0) {
-    __ui_scroll_canvas_ok = (uint8_t*)calloc(__ui_node_count, sizeof(uint8_t));
+    __ui_scroll_canvas_ok = new (std::nothrow) uint8_t[__ui_node_count]();
   }
-  if (!__ui_scroll_mem_warned && __ui_node_count > 0) {
-    __ui_scroll_mem_warned = (uint8_t*)calloc(__ui_node_count, sizeof(uint8_t));
+  if (!__ui_scroll_render_locked && __ui_node_count > 0) {
+    __ui_scroll_render_locked = new (std::nothrow) uint8_t[__ui_node_count]();
   }
   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) {
+      // Force the first scroll-canvas composition to seed every pixel. After
+      // that, a dirty child can be repaired in place without repainting the
+      // entire viewport.
+      __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;
     }
@@ -32,6 +39,11 @@ static inline void ui_init(void) {
       __ui_nodes[n].hasTextBinding = 1;
       strncpy(__ui_nodes[n].textBuffer, __ui_nodes[n].text ? __ui_nodes[n].text : "", UI_TEXT_BUF);
       __ui_nodes[n].textBuffer[UI_TEXT_BUF] = '\\0';
+    } else if (__ui_bindings[i].fn) {
+      // Prime numeric binding caches once at setup; the first tick can then skip
+      // redundant assignments and dirty propagation when values are unchanged.
+      __ui_bindings[i].lastValue = __ui_bindings[i].fn();
+      __ui_bindings[i].initialized = 1;
     }
   }
   // Seed virtualized-list runtime state. The fn pointers can't be baked into
@@ -52,7 +64,7 @@ static inline void ui_init(void) {
     uint16_t ih = __ui_nodes[i].listItemHeight > 0 ? __ui_nodes[i].listItemHeight : 24;
     uint16_t cnt = __ui_nodes[i].listCountFn();
     __ui_nodes[i].listCount = cnt;
-    __ui_nodes[i].contentHeight = (int16_t)((uint32_t)cnt * ih);
+    __ui_nodes[i].contentHeight = static_cast<int16_t>(static_cast<uint32_t>(cnt) * ih);
     __ui_nodes[i].scrollY = 0;
     __ui_nodes[i].overscrollPx = 0;
     __ui_nodes[i].settling = 0;
@@ -61,6 +73,9 @@ static inline void ui_init(void) {
   ui_build_draw_order();
   ui_build_scroll_owner_table();
   ui_refresh_active_screen_bg_node();
+  if (!__ui_scroll_candidates && __ui_node_count > 0) {
+    __ui_scroll_candidates = new (std::nothrow) UIScrollPaintCandidate[__ui_node_count];
+  }
 }
 
 // Debounce: ignore press/release events within 50ms of the last edge.
@@ -99,7 +114,7 @@ static inline void ui_on_release(uint16_t nodeIdx) {
 }
 
 // Pin-watch callback type: void fn(void)
-typedef void (*PinWatchCallback)(void);
+using PinWatchCallback = void (*)(void);
 
 struct UIPinWatch {
   uint8_t pin;

package/src/ui-engine/runtime-header/keyboard.ts

@@ -49,7 +49,7 @@ static inline void ui_kb_insert(char c) {
   if (__ui_kb_target >= 0) {
     strncpy(__ui_nodes[__ui_kb_target].textBuffer, __ui_kb_buffer, UI_TEXT_BUF);
     __ui_nodes[__ui_kb_target].textBuffer[UI_TEXT_BUF] = 0;
-    ui_mark_dirty((uint16_t)__ui_kb_target);
+    ui_mark_dirty(static_cast<uint16_t>(__ui_kb_target));
   }
 #endif
 }
@@ -62,7 +62,7 @@ static inline void ui_kb_delete() {
   if (__ui_kb_target >= 0) {
     strncpy(__ui_nodes[__ui_kb_target].textBuffer, __ui_kb_buffer, UI_TEXT_BUF);
     __ui_nodes[__ui_kb_target].textBuffer[UI_TEXT_BUF] = 0;
-    ui_mark_dirty((uint16_t)__ui_kb_target);
+    ui_mark_dirty(static_cast<uint16_t>(__ui_kb_target));
   }
 #endif
 }
@@ -92,7 +92,7 @@ static inline void ui_kb_open(uint16_t nodeIdx, uint8_t inputPosition) {
   __ui_kb_buffer[UI_TEXT_BUF] = 0;
   __ui_kb_len = strlen(__ui_kb_buffer);
   uint16_t ml = __ui_nodes[nodeIdx].maxlen;
-  __ui_kb_maxlen = (ml > 0 && ml <= UI_TEXT_BUF) ? (uint8_t)ml : UI_TEXT_BUF;
+  __ui_kb_maxlen = (ml > 0 && ml <= UI_TEXT_BUF) ? static_cast<uint8_t>(ml) : UI_TEXT_BUF;
   __ui_kb_shift = 0;
   __ui_kb_bs_held = 0;
   // Load the key set via the dispatch table.
@@ -113,7 +113,7 @@ static inline void ui_kb_open(uint16_t nodeIdx, uint8_t inputPosition) {
   // keystroke. (The full-screen-flash concern above doesn't apply — there's no
   // opaque overlay being skipped.) Seed the blink phase so the caret is ON for
   // the first ~530ms (bit 0x20 set → visible), so focus feels immediate.
-  if (__ui_kb_target >= 0) ui_mark_dirty((uint16_t)__ui_kb_target);
+  if (__ui_kb_target >= 0) ui_mark_dirty(static_cast<uint16_t>(__ui_kb_target));
   __ui_kb_blink = 0x20;
 #endif
 }
@@ -140,7 +140,7 @@ static inline void ui_kb_close() {
   int16_t screenRoot = -1;
   for (uint16_t i = 0; i < __ui_node_count; i++) {
     if (__ui_nodes[i].parent == UI_NO_PARENT && __ui_nodes[i].screenId == __ui_active_screen) {
-      screenRoot = (int16_t)i;
+      screenRoot = static_cast<int16_t>(i);
       break;
     }
   }
@@ -156,7 +156,7 @@ static inline void ui_kb_close() {
   // scroll clipping — safe here since these nodes are bounded in size, unlike
   // the screen root.
   for (uint16_t i = 0; i < __ui_node_count; i++) {
-    if ((int16_t)i == screenRoot) continue;
+    if (static_cast<int16_t>(i) == screenRoot) continue;
     UIRect r;
     ui_node_current_paint_rect(i, &r);
     if (r.w > 0 && r.h > 0 &&
@@ -173,8 +173,8 @@ static inline void ui_kb_key_rect(uint8_t idx, UIRect* out) {
   uint8_t col = idx % __ui_kb_cols;
   uint8_t row = idx / __ui_kb_cols;
   int16_t keysH = __ui_kb_box.h - UI_KB_TEXT_H;  // key area height (below text row)
-  out->x = __ui_kb_box.x + (int16_t)col * __ui_kb_box.w / __ui_kb_cols;
-  out->y = __ui_kb_box.y + UI_KB_TEXT_H + (int16_t)row * keysH / __ui_kb_rows;
+  out->x = __ui_kb_box.x + static_cast<int16_t>(col) * __ui_kb_box.w / __ui_kb_cols;
+  out->y = __ui_kb_box.y + UI_KB_TEXT_H + static_cast<int16_t>(row) * keysH / __ui_kb_rows;
   out->w = __ui_kb_box.w / __ui_kb_cols;
   out->h = keysH / __ui_kb_rows;
 }
@@ -192,8 +192,8 @@ static inline void ui_kb_handle_touch(int16_t tx, int16_t ty) {
     UIRect r;
     ui_kb_key_rect(i, &r);
     if (tx >= r.x && tx < r.x + r.w && ty >= r.y && ty < r.y + r.h) {
-      __ui_kb_pressed_key = (int8_t)i;  // remember for release
-      __ui_kb_repaint_key = (int8_t)i;
+      __ui_kb_pressed_key = static_cast<int8_t>(i);  // remember for release
+      __ui_kb_repaint_key = static_cast<int8_t>(i);
       __ui_kb_dirty = 2;  // targeted: redraw just this key's highlight
       // Backspace starts deleting immediately + arms auto-repeat.
       if (k.special == 2) {
@@ -273,7 +273,7 @@ static inline void ui_kb_draw_key(uint8_t i) {
   UI_COLOR_T border = ks.borderColor;
   // Shift-active highlight: brighten the shift key's background — but only
   // when not pressed, so the press inversion stays high-contrast.
-  if (k.special == 1 && __ui_kb_shift && (int8_t)i != __ui_kb_pressed_key) {
+  if (k.special == 1 && __ui_kb_shift && static_cast<int8_t>(i) != __ui_kb_pressed_key) {
 #if UI_COLOR_DEPTH == 888
     bg = 0xBDEFFF;
 #else
@@ -281,7 +281,7 @@ static inline void ui_kb_draw_key(uint8_t i) {
 #endif
   }
   // Pressed key: invert colors for clear tap feedback.
-  if ((int8_t)i == __ui_kb_pressed_key) { UI_COLOR_T t = bg; bg = fg; fg = t; }
+  if (static_cast<int8_t>(i) == __ui_kb_pressed_key) { UI_COLOR_T t = bg; bg = fg; fg = t; }
   ui_display_fill_rect(r.x + 1, r.y + 1, r.w - 2, r.h - 2, bg);
   ui_display_draw_rect(r.x + 1, r.y + 1, r.w - 2, r.h - 2, border);
   ui_display_set_text_color(fg, bg);
@@ -295,14 +295,14 @@ static inline void ui_kb_draw_key(uint8_t i) {
     case 3:  labelStr = "OK"; break;
     case 4:  labelStr = __ui_kb_cols <= 4 ? "ABC" : "123"; break;
     default:
-      single[0] = (__ui_kb_shift && k.ch >= 'a' && k.ch <= 'z') ? (char)(k.ch - 32) : k.ch;
+      single[0] = (__ui_kb_shift && k.ch >= 'a' && k.ch <= 'z') ? static_cast<char>(k.ch - 32) : k.ch;
       single[1] = 0;
       labelStr = single;
       break;
   }
   // Center: textW = len * 6px, textH = 8px. Position inside the key rect.
   uint8_t len = strlen(labelStr);
-  int16_t textW = (int16_t)len * 6;
+  int16_t textW = static_cast<int16_t>(len) * 6;
   int16_t textH = 8;
   int16_t cx = r.x + (r.w - textW) / 2;
   int16_t cy = r.y + (r.h - textH) / 2;
@@ -338,11 +338,14 @@ static inline void ui_kb_draw() {
   if (kw <= 0 || kh <= 0) return;
   // (Re)allocate the keyboard canvas to exact size (see repair-canvas comment
   // — stride mismatch corrupts the push when reusing a differently-sized canvas).
+  // ui_create_canvas_best prefers PSRAM when available (a full-width keyboard
+  // canvas can be ~30KB, too big for no-PSRAM internal SRAM) and falls back to
+  // SRAM — same policy as the list/scroll viewport canvases.
   if (!__ui_kb_canvas || !display_canvasBuffer(__ui_kb_canvas) ||
       display_canvasWidth(__ui_kb_canvas) != kw ||
       display_canvasHeight(__ui_kb_canvas) != kh) {
     display_deleteCanvas(__ui_kb_canvas);
-    __ui_kb_canvas = display_createCanvas(kw, kh);
+    __ui_kb_canvas = ui_create_canvas_best(kw, kh);
   }
   if (!__ui_kb_canvas || !display_canvasBuffer(__ui_kb_canvas)) {
     // Canvas alloc failed — fall back to direct draw (slow but correct).
@@ -376,7 +379,7 @@ static inline void ui_kb_draw() {
   ui_display_set_target(__kb_prev_target);
   display_startWrite();
   display_setAddrWindow(saveBoxX, saveBoxY, kw, kh);
-  display_writePixels(display_canvasBuffer(__ui_kb_canvas), (uint32_t)kw * kh);
+  display_writePixels(display_canvasBuffer(__ui_kb_canvas), static_cast<uint32_t>(kw) * kh);
   display_endWrite();
 }
 `;

package/src/ui-engine/runtime-header/node-decoration.ts

@@ -18,19 +18,19 @@ static inline void ui_draw_gradient_fill(uint16_t i, int16_t drawY) {
   uint8_t dir = __ui_nodes[i].gradientEnabled;  // 1=vertical, 2=horizontal
   if (dir == 1) {
     // Vertical: top=c1, bottom=c2. Draw row by row.
-    int16_t yStart = (int16_t)(clipY - by);
-    int16_t yEnd = (int16_t)(clipY + clipH - by);
+    int16_t yStart = static_cast<int16_t>(clipY - by);
+    int16_t yEnd = static_cast<int16_t>(clipY + clipH - by);
     for (int16_t y = yStart; y < yEnd; y++) {
-      uint8_t op = (uint8_t)((uint16_t)y * 100 / (bh > 1 ? bh - 1 : 1));
+      uint8_t op = static_cast<uint8_t>(static_cast<uint16_t>(y) * 100 / (bh > 1 ? bh - 1 : 1));
       uint32_t col = ui_blend(c1, c2, op);
       ui_display_draw_fast_hline(clipX, by + y, clipW, col);
     }
   } else {
     // Horizontal: left=c1, right=c2. Draw column by column.
-    int16_t xStart = (int16_t)(clipX - bx);
-    int16_t xEnd = (int16_t)(clipX + clipW - bx);
+    int16_t xStart = static_cast<int16_t>(clipX - bx);
+    int16_t xEnd = static_cast<int16_t>(clipX + clipW - bx);
     for (int16_t x = xStart; x < xEnd; x++) {
-      uint8_t op = (uint8_t)((uint16_t)x * 100 / (bw > 1 ? bw - 1 : 1));
+      uint8_t op = static_cast<uint8_t>(static_cast<uint16_t>(x) * 100 / (bw > 1 ? bw - 1 : 1));
       uint32_t col = ui_blend(c1, c2, op);
       ui_display_draw_fast_vline(bx + x, clipY, clipH, col);
     }
@@ -79,7 +79,7 @@ static inline void ui_draw_shadow(uint16_t i, int16_t drawY, uint8_t insetOnly)
     }
 
     for (int8_t pass = blur; pass >= 1; pass--) {
-      uint8_t opacity = (uint8_t)((uint16_t)baseAlpha / (pass + 1));
+      uint8_t opacity = static_cast<uint8_t>(static_cast<uint16_t>(baseAlpha) / (pass + 1));
       uint32_t col = ui_blend(shadowCol, inset ? (__ui_nodes[i].hasBg ? __ui_nodes[i].bg : clearCol) : clearCol, opacity);
       if (inset) {
         // Inset: draw inside the element, shrinking inward by pass.
@@ -104,7 +104,7 @@ static inline void ui_draw_shadow(uint16_t i, int16_t drawY, uint8_t insetOnly)
         int16_t sw = bw + 2 * pass;
         int16_t sh_ = bh + 2 * pass;
         if (radius > 0) {
-          uint8_t r = radius + (uint8_t)pass;
+          uint8_t r = radius + static_cast<uint8_t>(pass);
           if (r > sw / 2) r = sw / 2;
           if (r > sh_ / 2) r = sh_ / 2;
           ui_display_fill_round_rect(sx, sy, sw, sh_, r, col);